From 08f446190abadafa9ae9fc224ded171640822858 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Sun, 19 Jul 2026 15:59:36 -0700
Subject: [PATCH 01/54] Standardize per-repo Source Control AI save UX (#9427)

* Standardize per-repo Source Control AI save UX with global recipe patter

Extract draft/save logic into `useRepositorySourceControlAiGlobalUx` hook and
serial persist queue, matching how global action recipes save: selects persist
immediately, CLI args and command template draft until per-action Save.

* Support draft/commit for per-repo custom-command input

- Drafts custom commands locally on keystroke without backend writes
- Commits to persistence only on blur or mode selection change
- Adds forceRepoMode local state to fix mode-select snapping with empty fields
- Mirrors existing pattern used for action recipe text editing
- Improves persist queue with repo-switch safety (returns boolean, pins repoId at schedule time)
- Adds comprehensive test coverage for settings hook and persist queue

* Fix forceRepoMode logic to preserve REPO intent mid-edit

Always set forceRepoMode based on field content instead of
only when a repo command is present. This preserves REPO
intent when the field is empty during editing, only exiting
when a value is explicitly entered. Add test for draft
discard and revert behavior.
---
 .../RepositorySourceControlAiActionRows.tsx   |  24 +-
 ...RepositorySourceControlAiCustomCommand.tsx |  56 ++-
 .../RepositorySourceControlAiSection.test.ts  |  80 +---
 .../RepositorySourceControlAiSection.tsx      | 399 +++---------------
 ...repository-source-control-ai-draft.test.ts |  56 ---
 .../repository-source-control-ai-draft.ts     | 308 ++++++++++----
 ...sitory-source-control-ai-global-ux.test.ts | 236 +++++++++++
 .../repository-source-control-ai-global-ux.ts | 316 ++++++++++++++
 ...ry-source-control-ai-persist-queue.test.ts | 149 +++++++
 ...ository-source-control-ai-persist-queue.ts |  73 ++++
 10 files changed, 1116 insertions(+), 581 deletions(-)
 delete mode 100644 src/renderer/src/components/settings/repository-source-control-ai-draft.test.ts
 create mode 100644 src/renderer/src/components/settings/repository-source-control-ai-global-ux.test.ts
 create mode 100644 src/renderer/src/components/settings/repository-source-control-ai-global-ux.ts
 create mode 100644 src/renderer/src/components/settings/repository-source-control-ai-persist-queue.test.ts
 create mode 100644 src/renderer/src/components/settings/repository-source-control-ai-persist-queue.ts

diff --git a/src/renderer/src/components/settings/RepositorySourceControlAiActionRows.tsx b/src/renderer/src/components/settings/RepositorySourceControlAiActionRows.tsx
index 58a735e04dc..9fcfe68c077 100644
--- a/src/renderer/src/components/settings/RepositorySourceControlAiActionRows.tsx
+++ b/src/renderer/src/components/settings/RepositorySourceControlAiActionRows.tsx
@@ -51,7 +51,8 @@ type RepositorySourceControlAiActionRowsProps = {
   onActionTemplateChange: (actionId: SourceControlActionId, value: string) => void
   onActionAgentArgsChange: (actionId: SourceControlActionId, value: string) => void
   onAppendVariable: (actionId: SourceControlActionId, variable: string) => void
-  isSaving: boolean
+  /** Per-action saving state for CLI args + command template (matches global recipes). */
+  savingActionIds: Partial<Record<SourceControlActionId, boolean>>
   actionDirtyById: Record<SourceControlActionId, boolean>
   onActionDiscard: (actionId: SourceControlActionId) => void
   onActionSave: (actionId: SourceControlActionId) => void
@@ -67,7 +68,7 @@ export function RepositorySourceControlAiActionRows({
   onActionTemplateChange,
   onActionAgentArgsChange,
   onAppendVariable,
-  isSaving,
+  savingActionIds,
   actionDirtyById,
   onActionDiscard,
   onActionSave
@@ -103,6 +104,7 @@ export function RepositorySourceControlAiActionRows({
         const agentWarningText = getSourceControlActionAgentWarningText(actionId, effectiveAgent)
         const agentSupportText = getSourceControlActionAgentSupportText(actionId)
         const actionDirty = actionDirtyById[actionId]
+        const isSavingAction = savingActionIds[actionId] === true
         return (
           <div
             key={actionId}
@@ -249,15 +251,15 @@ export function RepositorySourceControlAiActionRows({
               </div>
             </div>
             {hasOverride ? (
-              <div className="flex items-center justify-between gap-3 border-t border-border pt-3">
+              <div className="mt-3 flex items-center justify-between gap-3">
                 <p className="text-[11px] text-muted-foreground">
                   {actionDirty
                     ? translate(
-                        'auto.components.settings.RepositorySourceControlAiSection.e57dde9d93',
+                        'auto.components.settings.SourceControlAiActionRecipeDefaults.817128d94e',
                         'Unsaved changes'
                       )
                     : translate(
-                        'auto.components.settings.RepositorySourceControlAiSection.ccb07dd027',
+                        'auto.components.settings.SourceControlAiActionRecipeDefaults.9d3cc627f8',
                         'Saved'
                       )}
                 </p>
@@ -268,10 +270,10 @@ export function RepositorySourceControlAiActionRows({
                       variant="ghost"
                       size="xs"
                       onClick={() => onActionDiscard(actionId)}
-                      disabled={isSaving}
+                      disabled={isSavingAction}
                     >
                       {translate(
-                        'auto.components.settings.RepositorySourceControlAiSection.67b3ff5467',
+                        'auto.components.settings.SourceControlAiActionRecipeDefaults.b3914ecbbc',
                         'Discard'
                       )}
                     </Button>
@@ -281,15 +283,15 @@ export function RepositorySourceControlAiActionRows({
                     variant="secondary"
                     size="xs"
                     onClick={() => onActionSave(actionId)}
-                    disabled={!actionDirty || isSaving}
+                    disabled={!actionDirty || isSavingAction}
                   >
-                    {isSaving
+                    {isSavingAction
                       ? translate(
-                          'auto.components.settings.RepositorySourceControlAiSection.57e6e9d4b1',
+                          'auto.components.settings.SourceControlAiActionRecipeDefaults.4f549a5fa8',
                           'Saving...'
                         )
                       : translate(
-                          'auto.components.settings.RepositorySourceControlAiSection.152268c295',
+                          'auto.components.settings.SourceControlAiActionRecipeDefaults.d18d665e12',
                           'Save'
                         )}
                   </Button>
diff --git a/src/renderer/src/components/settings/RepositorySourceControlAiCustomCommand.tsx b/src/renderer/src/components/settings/RepositorySourceControlAiCustomCommand.tsx
index 6a22472b2ee..e3e6e32cf6b 100644
--- a/src/renderer/src/components/settings/RepositorySourceControlAiCustomCommand.tsx
+++ b/src/renderer/src/components/settings/RepositorySourceControlAiCustomCommand.tsx
@@ -1,4 +1,5 @@
 import type React from 'react'
+import { useState } from 'react'
 import type { SourceControlAiSettings } from '../../../../shared/source-control-ai-types'
 import { Input } from '../ui/input'
 import { Label } from '../ui/label'
@@ -12,19 +13,27 @@ import { translate } from '@/i18n/i18n'
 type RepositorySourceControlAiCustomCommandProps = {
   value: string | undefined
   source: SourceControlAiSettings
+  // onChange drafts the value locally (per keystroke); onCommit persists it (on blur / mode change).
   onChange: (value: string | undefined) => void
+  onCommit: (value: string | undefined) => void
+}
+
+function isRepoCommand(value: string | undefined): boolean {
+  return typeof value === 'string' && value.trim().length > 0
 }
 
 export function RepositorySourceControlAiCustomCommand({
   value,
   source,
-  onChange
+  onChange,
+  onCommit
 }: RepositorySourceControlAiCustomCommandProps): React.JSX.Element {
-  // Why: value only counts as a repo command when it is a non-empty trimmed string;
-  // empty/nullish values make hasRepoCommand select CUSTOM_COMMAND_MODE_INHERIT
-  // instead of CUSTOM_COMMAND_MODE_REPO, so clearing the input switches mode.
-  const hasRepoCommand = typeof value === 'string' && value.trim().length > 0
-  const mode = hasRepoCommand ? CUSTOM_COMMAND_MODE_REPO : CUSTOM_COMMAND_MODE_INHERIT
+  // Why: selecting "Repository command" with an empty global/repo value would otherwise snap the
+  // Select back to inherit (empty is not a repo command). Keep a local intent so the user can type.
+  const [forceRepoMode, setForceRepoMode] = useState(false)
+  const hasRepoCommand = isRepoCommand(value)
+  const mode =
+    hasRepoCommand || forceRepoMode ? CUSTOM_COMMAND_MODE_REPO : CUSTOM_COMMAND_MODE_INHERIT
   return (
     <div className="space-y-2 rounded-md border border-border px-3 py-3">
       <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
@@ -45,13 +54,23 @@ export function RepositorySourceControlAiCustomCommand({
         <Select
           value={mode}
           onValueChange={(nextMode) => {
-            // Why: CUSTOM_COMMAND_MODE_REPO pre-populates onChange from
-            // source.customAgentCommand when this repo has no command yet; other modes clear.
-            onChange(
-              nextMode === CUSTOM_COMMAND_MODE_REPO
-                ? (value ?? source.customAgentCommand)
-                : undefined
-            )
+            if (nextMode === CUSTOM_COMMAND_MODE_REPO) {
+              // Why: pre-populate from the current draft or the global command when available; when
+              // both are empty, stay in local REPO mode so the Select does not snap back to inherit.
+              const nextValue = value ?? source.customAgentCommand
+              if (isRepoCommand(nextValue)) {
+                setForceRepoMode(false)
+                onChange(nextValue)
+                onCommit(nextValue)
+                return
+              }
+              setForceRepoMode(true)
+              onChange(nextValue === '' ? undefined : nextValue)
+              return
+            }
+            setForceRepoMode(false)
+            onChange(undefined)
+            onCommit(undefined)
           }}
         >
           <SelectTrigger size="sm" className="h-8 w-full text-xs sm:w-[150px]">
@@ -77,8 +96,19 @@ export function RepositorySourceControlAiCustomCommand({
         value={value ?? ''}
         onChange={(event) => {
           const nextValue = event.target.value
+          // Why: an empty field while typing keeps local REPO intent so the Select doesn't snap to
+          // inherit mid-edit; blur is what commits the clear. A non-empty value exits the intent.
+          setForceRepoMode(!isRepoCommand(nextValue))
           onChange(nextValue === '' ? undefined : nextValue)
         }}
+        onBlur={(event) => {
+          const nextValue = event.target.value
+          // Why: blur with an empty field exits local REPO intent and commits inherit (clear).
+          if (!isRepoCommand(nextValue)) {
+            setForceRepoMode(false)
+          }
+          onCommit(nextValue === '' ? undefined : nextValue)
+        }}
         placeholder={
           source.customAgentCommand ||
           translate(
diff --git a/src/renderer/src/components/settings/RepositorySourceControlAiSection.test.ts b/src/renderer/src/components/settings/RepositorySourceControlAiSection.test.ts
index 45ca21f542a..9d253bf71ee 100644
--- a/src/renderer/src/components/settings/RepositorySourceControlAiSection.test.ts
+++ b/src/renderer/src/components/settings/RepositorySourceControlAiSection.test.ts
@@ -2,89 +2,15 @@ import { describe, expect, it } from 'vitest'
 import React from 'react'
 import { renderToStaticMarkup } from 'react-dom/server'
 import { normalizeRepoSourceControlAiOverrides } from '../../../../shared/source-control-ai'
-import type {
-  RepoSourceControlAiOverrides,
-  SourceControlAiSettings
-} from '../../../../shared/source-control-ai-types'
+import type { SourceControlAiSettings } from '../../../../shared/source-control-ai-types'
 import {
   SOURCE_CONTROL_ACTION_IDS,
   type SourceControlActionId
 } from '../../../../shared/source-control-ai-actions'
-import {
-  createRepoAiDraftState,
-  dropRepoLegacyInstructionForAction,
-  resolveRepoAiDraftState
-} from './RepositorySourceControlAiSection'
+import { dropRepoLegacyInstructionForAction } from './repository-source-control-ai-draft'
 import { RepositorySourceControlAiActionRows } from './RepositorySourceControlAiActionRows'
 import { RepositorySourceControlAiEnablement } from './RepositorySourceControlAiEnablement'
 
-describe('RepositorySourceControlAiSection draft state', () => {
-  it('refreshes clean drafts when persisted repo overrides change', () => {
-    const state = createRepoAiDraftState('repo-1', {
-      instructionsByOperation: {
-        commitMessage: 'old'
-      }
-    })
-    const persisted: RepoSourceControlAiOverrides = {
-      instructionsByOperation: {
-        commitMessage: 'new'
-      }
-    }
-
-    expect(resolveRepoAiDraftState(state, 'repo-1', persisted)).toEqual({
-      repoId: 'repo-1',
-      value: persisted,
-      baseSerialized: JSON.stringify(normalizeRepoSourceControlAiOverrides(persisted))
-    })
-  })
-
-  it('preserves dirty drafts across external repo override changes', () => {
-    const state = createRepoAiDraftState('repo-1', {
-      instructionsByOperation: {
-        commitMessage: 'old'
-      }
-    })
-    state.value = {
-      instructionsByOperation: {
-        commitMessage: 'local edit'
-      }
-    }
-
-    const persisted: RepoSourceControlAiOverrides = {
-      instructionsByOperation: {
-        commitMessage: 'external edit'
-      }
-    }
-
-    expect(resolveRepoAiDraftState(state, 'repo-1', persisted)).toBe(state)
-  })
-
-  it('resets the draft when the selected repo changes', () => {
-    const state = createRepoAiDraftState('repo-1', {
-      prCreationDefaults: {
-        draft: true
-      }
-    })
-    state.value = {
-      prCreationDefaults: {
-        draft: false
-      }
-    }
-
-    const persisted: RepoSourceControlAiOverrides = {
-      prCreationDefaults: {
-        useTemplate: true
-      }
-    }
-
-    expect(resolveRepoAiDraftState(state, 'repo-2', persisted)).toEqual({
-      repoId: 'repo-2',
-      value: persisted,
-      baseSerialized: JSON.stringify(normalizeRepoSourceControlAiOverrides(persisted))
-    })
-  })
-})
-
 describe('RepositorySourceControlAiEnablement', () => {
   it('describes repo enablement as Source Control AI action visibility', () => {
     const markup = renderToStaticMarkup(
@@ -130,7 +56,7 @@ describe('RepositorySourceControlAiActionRows', () => {
         },
         source,
         defaultTuiAgent: 'codex',
-        isSaving: false,
+        savingActionIds: {},
         actionDirtyById,
         onActionModeChange: () => {},
         onActionAgentChange: () => {},
diff --git a/src/renderer/src/components/settings/RepositorySourceControlAiSection.tsx b/src/renderer/src/components/settings/RepositorySourceControlAiSection.tsx
index 5568912edd2..7e600b11bf6 100644
--- a/src/renderer/src/components/settings/RepositorySourceControlAiSection.tsx
+++ b/src/renderer/src/components/settings/RepositorySourceControlAiSection.tsx
@@ -1,65 +1,35 @@
-import { useMemo, useState } from 'react'
+import { useMemo } from 'react'
 import type React from 'react'
-import type { Repo, TuiAgent } from '../../../../shared/types'
-import { CUSTOM_AGENT_ID } from '../../../../shared/commit-message-agent-spec'
-import type { RepoSourceControlAiOverrides } from '../../../../shared/source-control-ai-types'
-import {
-  normalizeRepoSourceControlAiOverrides,
-  normalizeSourceControlAiSettings
-} from '../../../../shared/source-control-ai'
-import { toSourceControlAiRepoUpdate } from '../../../../shared/source-control-ai-recipe-save'
+import type { Repo } from '../../../../shared/types'
+import { normalizeSourceControlAiSettings } from '../../../../shared/source-control-ai'
 import type { SourceControlAiRepoUpdate } from '../../../../shared/source-control-ai-recipe-save'
-import {
-  SOURCE_CONTROL_ACTION_IDS,
-  type SourceControlActionId
-} from '../../../../shared/source-control-ai-actions'
-import { Button } from '../ui/button'
 import { useAppStore } from '../../store'
-import { useMountedRef } from '@/hooks/useMountedRef'
 import { getRepositorySourceControlAiSectionId } from './repository-settings-targets'
 import { RepositorySourceControlAiActionRows } from './RepositorySourceControlAiActionRows'
 import { RepositorySourceControlAiCustomCommand } from './RepositorySourceControlAiCustomCommand'
 import { RepositorySourceControlAiEnablement } from './RepositorySourceControlAiEnablement'
 import { RepositorySourceControlAiHostedReviewDefaults } from './RepositorySourceControlAiHostedReviewDefaults'
 import {
-  buildActionScopedRepoAiSave,
-  createRepoAiDraftState,
-  dropRepoLegacyInstructionForAction,
-  hasOwnActionOverride,
-  normalizeRepoAiDraft,
-  readCompleteRecipeForDraft,
-  resolveRepoAiDraftState,
-  serializeActionOverride,
-  serializeRepoAiDraft,
-  setActionOverride,
-  type RepoAiDraftState
-} from './repository-source-control-ai-draft'
-import {
-  ACTION_MODE_INHERIT,
-  DEFAULT_AGENT_VALUE,
-  readInheritedCommandTemplate
-} from './repository-source-control-ai-labels'
+  normalizePersistedRepoAi,
+  useRepositorySourceControlAiGlobalUx
+} from './repository-source-control-ai-global-ux'
 import { getSettingOwnershipSummary } from './setting-ownership'
 import { translate } from '@/i18n/i18n'
 
-export {
-  createRepoAiDraftState,
-  dropRepoLegacyInstructionForAction,
-  resolveRepoAiDraftState
-} from './repository-source-control-ai-draft'
-
 type RepositorySourceControlAiSectionProps = {
   repo: Repo
   updateRepo: (repoId: string, updates: SourceControlAiRepoUpdate) => void | Promise<boolean>
 }
 
-type HostedReviewDefaultKey = keyof NonNullable<RepoSourceControlAiOverrides['prCreationDefaults']>
-
+/**
+ * Per-repo Source Control AI settings — save UX matches global Git / Source Control AI:
+ * selects and simple controls persist immediately; each action recipe drafts CLI args +
+ * command template until that row's Save (same as global action recipes).
+ */
 export function RepositorySourceControlAiSection({
   repo,
   updateRepo
 }: RepositorySourceControlAiSectionProps): React.JSX.Element {
-  const mountedRef = useMountedRef()
   const settings = useAppStore((state) => state.settings)
   const ownership = getSettingOwnershipSummary('repositorySourceControlAi')
   const source = normalizeSourceControlAiSettings(
@@ -67,254 +37,32 @@ export function RepositorySourceControlAiSection({
     settings?.commitMessageAi
   )
   const persistedRepoAi = useMemo(
-    () => normalizeRepoAiDraft(repo.sourceControlAi),
+    () => normalizePersistedRepoAi(repo.sourceControlAi),
     [repo.sourceControlAi]
   )
-  const persistedSerialized = useMemo(
-    () => serializeRepoAiDraft(persistedRepoAi),
-    [persistedRepoAi]
-  )
-  // Why: repo.sourceControlAi is saved as one nested value; a local draft keeps
-  // textarea keystrokes and sibling controls from racing over IPC/RPC.
-  const [draftState, setDraftState] = useState<RepoAiDraftState>(() =>
-    createRepoAiDraftState(repo.id, persistedRepoAi)
-  )
-  const [isSaving, setIsSaving] = useState(false)
-  const [saveError, setSaveError] = useState<string | null>(null)
-
-  const resolvedDraftState = resolveRepoAiDraftState(
-    draftState,
-    repo.id,
+  const {
+    displayRepoAi,
+    saveError,
+    actionDirtyById,
+    savingActionIds,
+    updateEnablement,
+    updateCustomCommand,
+    updateHostedReviewDefault,
+    updateActionMode,
+    updateActionAgent,
+    updateActionTemplate,
+    updateActionAgentArgs,
+    appendVariable,
+    saveActionRecipeText,
+    discardActionRecipeText,
+    commitCustomCommand
+  } = useRepositorySourceControlAiGlobalUx({
+    repoId: repo.id,
     persistedRepoAi,
-    persistedSerialized
-  )
-  if (resolvedDraftState !== draftState) {
-    // Why: repo settings may be refreshed externally; clean drafts should
-    // follow that source before paint, while dirty edits stay in place.
-    setDraftState(resolvedDraftState)
-    if (saveError !== null) {
-      setSaveError(null)
-    }
-  }
-
-  const repoAi = resolvedDraftState.value
-  const draftSerialized = useMemo(() => serializeRepoAiDraft(repoAi), [repoAi])
-  const isDirty =
-    resolvedDraftState.repoId !== repo.id || draftSerialized !== resolvedDraftState.baseSerialized
-  const actionDirtyById = useMemo(
-    () =>
-      Object.fromEntries(
-        SOURCE_CONTROL_ACTION_IDS.map((actionId) => [
-          actionId,
-          serializeActionOverride(repoAi, actionId) !==
-            serializeActionOverride(persistedRepoAi, actionId)
-        ])
-      ) as Record<SourceControlActionId, boolean>,
-    [persistedRepoAi, repoAi]
-  )
-
-  const updateDraftRepoAi = (
-    update: (current: RepoSourceControlAiOverrides) => RepoSourceControlAiOverrides
-  ): void => {
-    setDraftState((current) => {
-      const resolved = resolveRepoAiDraftState(
-        current,
-        repo.id,
-        persistedRepoAi,
-        persistedSerialized
-      )
-      return {
-        ...resolved,
-        value: normalizeRepoAiDraft(update(resolved.value))
-      }
-    })
-    setSaveError(null)
-  }
-
-  const saveDraft = async (): Promise<void> => {
-    if (!isDirty || isSaving) {
-      return
-    }
-    const next = normalizeRepoAiDraft(resolvedDraftState.value)
-    const nextSerialized = serializeRepoAiDraft(next)
-    const repoUpdate = toSourceControlAiRepoUpdate(next)
-    setIsSaving(true)
-    setSaveError(null)
-    try {
-      const result = await updateRepo(repo.id, repoUpdate)
-      if (!mountedRef.current) {
-        return
-      }
-      if (result === false) {
-        setSaveError('Failed to save Source Control AI settings.')
-        return
-      }
-      const savedValue =
-        repoUpdate.sourceControlAi === null
-          ? {}
-          : (normalizeRepoSourceControlAiOverrides(repoUpdate.sourceControlAi) ?? {})
-      setDraftState((current) => {
-        if (current.repoId !== repo.id) {
-          return current
-        }
-        const currentSerialized = serializeRepoAiDraft(current.value)
-        return {
-          repoId: repo.id,
-          value: currentSerialized === nextSerialized ? savedValue : current.value,
-          baseSerialized: serializeRepoAiDraft(savedValue)
-        }
-      })
-    } catch {
-      if (mountedRef.current) {
-        setSaveError('Failed to save Source Control AI settings.')
-      }
-    } finally {
-      if (mountedRef.current) {
-        setIsSaving(false)
-      }
-    }
-  }
-
-  const discardDraft = (): void => {
-    setDraftState(createRepoAiDraftState(repo.id, persistedRepoAi))
-    setSaveError(null)
-  }
-
-  const discardActionDraft = (actionId: SourceControlActionId): void => {
-    updateDraftRepoAi((current) => {
-      const nextActionOverrides = { ...current.actionOverrides }
-      if (hasOwnActionOverride(persistedRepoAi.actionOverrides, actionId)) {
-        nextActionOverrides[actionId] = persistedRepoAi.actionOverrides?.[actionId]
-      } else {
-        delete nextActionOverrides[actionId]
-      }
-      return dropRepoLegacyInstructionForAction(
-        { ...current, actionOverrides: nextActionOverrides },
-        actionId
-      )
-    })
-  }
-
-  const saveActionDraft = async (actionId: SourceControlActionId): Promise<void> => {
-    if (isSaving || !actionDirtyById[actionId]) {
-      return
-    }
-    // Why: a per-action Save persists only that action's override (its Discard is
-    // action-scoped, so its Save must be too) — never other rows' pending edits.
-    const next = buildActionScopedRepoAiSave(persistedRepoAi, repoAi, actionId)
-    const repoUpdate = toSourceControlAiRepoUpdate(next)
-    setIsSaving(true)
-    setSaveError(null)
-    try {
-      const result = await updateRepo(repo.id, repoUpdate)
-      if (!mountedRef.current) {
-        return
-      }
-      if (result === false) {
-        setSaveError('Failed to save Source Control AI settings.')
-      }
-    } catch {
-      if (mountedRef.current) {
-        setSaveError('Failed to save Source Control AI settings.')
-      }
-    } finally {
-      if (mountedRef.current) {
-        setIsSaving(false)
-      }
-    }
-  }
-
-  const updateEnablement = (value: boolean | undefined): void => {
-    updateDraftRepoAi((current) => ({ ...current, enabled: value }))
-  }
-
-  const updateCustomCommand = (value: string | undefined): void => {
-    updateDraftRepoAi((current) => ({ ...current, customAgentCommand: value }))
-  }
-
-  const updateActionMode = (actionId: SourceControlActionId, mode: string): void => {
-    updateDraftRepoAi((current) => {
-      const nextActionOverrides = { ...current.actionOverrides }
-      if (mode === ACTION_MODE_INHERIT) {
-        delete nextActionOverrides[actionId]
-        return dropRepoLegacyInstructionForAction(
-          { ...current, actionOverrides: nextActionOverrides },
-          actionId
-        )
-      }
-      if (!hasOwnActionOverride(nextActionOverrides, actionId)) {
-        nextActionOverrides[actionId] = readCompleteRecipeForDraft(current, settings, actionId)
-      }
-      return dropRepoLegacyInstructionForAction(
-        { ...current, actionOverrides: nextActionOverrides },
-        actionId
-      )
-    })
-  }
-
-  const updateActionAgent = (actionId: SourceControlActionId, value: string): void => {
-    updateDraftRepoAi((current) => {
-      const currentRecipe =
-        current.actionOverrides?.[actionId] ??
-        readCompleteRecipeForDraft(current, settings, actionId)
-      const nextRecipe = {
-        ...currentRecipe,
-        agentId:
-          value === DEFAULT_AGENT_VALUE
-            ? null
-            : value === CUSTOM_AGENT_ID
-              ? CUSTOM_AGENT_ID
-              : (value as TuiAgent)
-      }
-      return setActionOverride(current, actionId, nextRecipe)
-    })
-  }
-
-  const updateActionTemplate = (actionId: SourceControlActionId, value: string): void => {
-    updateDraftRepoAi((current) => {
-      const currentRecipe =
-        current.actionOverrides?.[actionId] ??
-        readCompleteRecipeForDraft(current, settings, actionId)
-      return setActionOverride(current, actionId, {
-        ...currentRecipe,
-        commandInputTemplate: value
-      })
-    })
-  }
-
-  const updateActionAgentArgs = (actionId: SourceControlActionId, value: string): void => {
-    updateDraftRepoAi((current) => {
-      const currentRecipe =
-        current.actionOverrides?.[actionId] ??
-        readCompleteRecipeForDraft(current, settings, actionId)
-      return setActionOverride(current, actionId, {
-        ...currentRecipe,
-        agentArgs: value
-      })
-    })
-  }
-
-  const appendVariable = (actionId: SourceControlActionId, variable: string): void => {
-    const override = repoAi.actionOverrides?.[actionId]
-    const currentTemplate =
-      typeof override?.commandInputTemplate === 'string'
-        ? override.commandInputTemplate
-        : readInheritedCommandTemplate(source, actionId)
-    const separator = currentTemplate.endsWith('\n') || currentTemplate.length === 0 ? '' : ' '
-    updateActionTemplate(actionId, `${currentTemplate}${separator}{${variable}}`)
-  }
-
-  const updateHostedReviewDefault = (key: HostedReviewDefaultKey, value: string): void => {
-    updateDraftRepoAi((current) => {
-      const nextDefaults = { ...current.prCreationDefaults }
-      if (value === 'inherit') {
-        delete nextDefaults[key]
-      } else {
-        nextDefaults[key] = value === 'on'
-      }
-      return { ...current, prCreationDefaults: nextDefaults }
-    })
-  }
+    settings,
+    source,
+    updateRepo
+  })
 
   return (
     <section
@@ -322,90 +70,45 @@ export function RepositorySourceControlAiSection({
       data-settings-section={getRepositorySourceControlAiSectionId(repo.id)}
       className="space-y-4"
     >
-      <div className="flex items-start justify-between gap-4">
-        <div className="min-w-0 space-y-1">
-          <h3 className="text-sm font-semibold">
-            {translate(
-              'auto.components.settings.RepositorySourceControlAiSection.71b003b62b',
-              'Source Control AI'
-            )}
-          </h3>
-          <p className="text-xs text-muted-foreground">{ownership.description}</p>
-          {saveError ? <p className="text-xs text-destructive">{saveError}</p> : null}
-        </div>
-        <div className="flex shrink-0 flex-wrap items-center justify-end gap-2">
-          <span className="text-[11px] text-muted-foreground">
-            {isDirty
-              ? translate(
-                  'auto.components.settings.RepositorySourceControlAiSection.e57dde9d93',
-                  'Unsaved changes'
-                )
-              : translate(
-                  'auto.components.settings.RepositorySourceControlAiSection.ccb07dd027',
-                  'Saved'
-                )}
-          </span>
-          {isDirty ? (
-            <Button
-              type="button"
-              variant="ghost"
-              size="xs"
-              onClick={discardDraft}
-              disabled={isSaving}
-            >
-              {translate(
-                'auto.components.settings.RepositorySourceControlAiSection.67b3ff5467',
-                'Discard'
-              )}
-            </Button>
-          ) : null}
-          <Button
-            type="button"
-            variant="secondary"
-            size="xs"
-            onClick={() => void saveDraft()}
-            disabled={!isDirty || isSaving}
-          >
-            {isSaving
-              ? translate(
-                  'auto.components.settings.RepositorySourceControlAiSection.57e6e9d4b1',
-                  'Saving...'
-                )
-              : translate(
-                  'auto.components.settings.RepositorySourceControlAiSection.152268c295',
-                  'Save'
-                )}
-          </Button>
-        </div>
+      <div className="min-w-0 space-y-1">
+        <h3 className="text-sm font-semibold">
+          {translate(
+            'auto.components.settings.RepositorySourceControlAiSection.71b003b62b',
+            'Source Control AI'
+          )}
+        </h3>
+        <p className="text-xs text-muted-foreground">{ownership.description}</p>
+        {saveError ? <p className="text-xs text-destructive">{saveError}</p> : null}
       </div>
 
       <RepositorySourceControlAiEnablement
-        value={repoAi.enabled}
+        value={displayRepoAi.enabled}
         source={source}
         onChange={updateEnablement}
       />
       <RepositorySourceControlAiCustomCommand
-        value={repoAi.customAgentCommand}
+        value={displayRepoAi.customAgentCommand}
         source={source}
         onChange={updateCustomCommand}
+        onCommit={commitCustomCommand}
       />
       <RepositorySourceControlAiActionRows
         repoId={repo.id}
-        repoAi={repoAi}
+        repoAi={displayRepoAi}
         source={source}
         defaultTuiAgent={settings?.defaultTuiAgent}
-        isSaving={isSaving}
+        savingActionIds={savingActionIds}
         actionDirtyById={actionDirtyById}
         onActionModeChange={updateActionMode}
         onActionAgentChange={updateActionAgent}
         onActionTemplateChange={updateActionTemplate}
         onActionAgentArgsChange={updateActionAgentArgs}
         onAppendVariable={appendVariable}
-        onActionDiscard={discardActionDraft}
-        onActionSave={(actionId) => void saveActionDraft(actionId)}
+        onActionDiscard={discardActionRecipeText}
+        onActionSave={(actionId) => void saveActionRecipeText(actionId)}
       />
       <RepositorySourceControlAiHostedReviewDefaults
-        value={repoAi.prCreationDefaults}
+        value={displayRepoAi.prCreationDefaults}
         source={source}
         onChange={updateHostedReviewDefault}
       />
diff --git a/src/renderer/src/components/settings/repository-source-control-ai-draft.test.ts b/src/renderer/src/components/settings/repository-source-control-ai-draft.test.ts
deleted file mode 100644
index 1972afde88b..00000000000
--- a/src/renderer/src/components/settings/repository-source-control-ai-draft.test.ts
+++ /dev/null
@@ -1,56 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import type { RepoSourceControlAiOverrides } from '../../../../shared/source-control-ai-types'
-import { buildActionScopedRepoAiSave } from './repository-source-control-ai-draft'
-
-describe('buildActionScopedRepoAiSave', () => {
-  it('persists only the target action, keeping siblings at their saved values', () => {
-    const persisted: RepoSourceControlAiOverrides = {
-      actionOverrides: {
-        resolveConflicts: {
-          agentId: 'claude',
-          commandInputTemplate: '{basePrompt}',
-          agentArgs: ''
-        },
-        fixCommitFailure: { agentId: 'codex', commandInputTemplate: '{basePrompt}', agentArgs: '' }
-      }
-    }
-    const draft: RepoSourceControlAiOverrides = {
-      actionOverrides: {
-        resolveConflicts: {
-          agentId: 'codex',
-          commandInputTemplate: '{basePrompt}\n\nedited',
-          agentArgs: ''
-        },
-        // A half-finished edit on a different row that must NOT be flushed.
-        fixCommitFailure: {
-          agentId: 'gemini',
-          commandInputTemplate: '{basePrompt}\n\nunsaved',
-          agentArgs: ''
-        }
-      }
-    }
-
-    const next = buildActionScopedRepoAiSave(persisted, draft, 'resolveConflicts')
-
-    expect(next.actionOverrides?.resolveConflicts?.agentId).toBe('codex')
-    expect(next.actionOverrides?.resolveConflicts?.commandInputTemplate).toBe(
-      '{basePrompt}\n\nedited'
-    )
-    // Sibling keeps the persisted value, not the draft's pending edit.
-    expect(next.actionOverrides?.fixCommitFailure?.agentId).toBe('codex')
-    expect(next.actionOverrides?.fixCommitFailure?.commandInputTemplate).toBe('{basePrompt}')
-  })
-
-  it('removes the action override when the draft inherits it', () => {
-    const persisted: RepoSourceControlAiOverrides = {
-      actionOverrides: {
-        resolveConflicts: { agentId: 'claude', commandInputTemplate: '{basePrompt}', agentArgs: '' }
-      }
-    }
-    const draft: RepoSourceControlAiOverrides = { actionOverrides: {} }
-
-    const next = buildActionScopedRepoAiSave(persisted, draft, 'resolveConflicts')
-
-    expect(next.actionOverrides?.resolveConflicts).toBeUndefined()
-  })
-})
diff --git a/src/renderer/src/components/settings/repository-source-control-ai-draft.ts b/src/renderer/src/components/settings/repository-source-control-ai-draft.ts
index a085821f23f..1e516bab7a8 100644
--- a/src/renderer/src/components/settings/repository-source-control-ai-draft.ts
+++ b/src/renderer/src/components/settings/repository-source-control-ai-draft.ts
@@ -2,7 +2,10 @@ import {
   normalizeRepoSourceControlAiOverrides,
   resolveSourceControlActionRecipe
 } from '../../../../shared/source-control-ai'
-import type { SourceControlActionId } from '../../../../shared/source-control-ai-actions'
+import {
+  SOURCE_CONTROL_ACTION_IDS,
+  type SourceControlActionId
+} from '../../../../shared/source-control-ai-actions'
 import type { RepoSourceControlAiOverrides } from '../../../../shared/source-control-ai-types'
 import type { GlobalSettings } from '../../../../shared/types'
 import { completeRepoActionRecipe } from './repository-source-control-ai-labels'
@@ -12,12 +15,6 @@ type RepoActionRecipe = NonNullable<
   NonNullable<RepoSourceControlAiOverrides['actionOverrides']>[SourceControlActionId]
 >
 
-export type RepoAiDraftState = {
-  repoId: string
-  value: RepoSourceControlAiOverrides
-  baseSerialized: string
-}
-
 export function hasOwnActionOverride(
   overrides: RepoSourceControlAiOverrides['actionOverrides'],
   actionId: SourceControlActionId
@@ -41,52 +38,6 @@ export function normalizeRepoAiDraft(
   return normalizeRepoSourceControlAiOverrides(value) ?? {}
 }
 
-export function serializeRepoAiDraft(value: RepoSourceControlAiOverrides): string {
-  return JSON.stringify(normalizeRepoAiDraft(value))
-}
-
-export function createRepoAiDraftState(
-  repoId: string,
-  value: RepoSourceControlAiOverrides
-): RepoAiDraftState {
-  const normalized = normalizeRepoAiDraft(value)
-  return {
-    repoId,
-    value: normalized,
-    baseSerialized: serializeRepoAiDraft(normalized)
-  }
-}
-
-export function resolveRepoAiDraftState(
-  current: RepoAiDraftState,
-  repoId: string,
-  persistedRepoAi: RepoSourceControlAiOverrides,
-  persistedSerialized = serializeRepoAiDraft(persistedRepoAi)
-): RepoAiDraftState {
-  const currentSerialized = serializeRepoAiDraft(current.value)
-  // Why: render-time draft sync relies on object identity to avoid repeating
-  // the same state update during server-rendered settings tests.
-  if (
-    current.repoId === repoId &&
-    currentSerialized === persistedSerialized &&
-    current.baseSerialized === persistedSerialized
-  ) {
-    return current
-  }
-  if (
-    current.repoId !== repoId ||
-    currentSerialized === current.baseSerialized ||
-    currentSerialized === persistedSerialized
-  ) {
-    return {
-      repoId,
-      value: persistedRepoAi,
-      baseSerialized: persistedSerialized
-    }
-  }
-  return current
-}
-
 export function dropRepoLegacyInstructionForAction(
   value: RepoSourceControlAiOverrides,
   actionId: SourceControlActionId
@@ -133,35 +84,240 @@ export function setActionOverride(
   )
 }
 
-export function serializeActionOverride(
-  value: RepoSourceControlAiOverrides,
-  actionId: SourceControlActionId
-): string {
-  return JSON.stringify({
-    hasOverride: hasOwnActionOverride(value.actionOverrides, actionId),
-    recipe: value.actionOverrides?.[actionId] ?? null
+export function withRepoAiEnabled(
+  base: RepoSourceControlAiOverrides,
+  enabled: boolean | undefined
+): RepoSourceControlAiOverrides {
+  const next = { ...base }
+  if (enabled === undefined) {
+    delete next.enabled
+  } else {
+    next.enabled = enabled
+  }
+  return normalizeRepoAiDraft(next)
+}
+
+export function withRepoAiCustomCommand(
+  base: RepoSourceControlAiOverrides,
+  customAgentCommand: string | undefined
+): RepoSourceControlAiOverrides {
+  const next = { ...base }
+  if (customAgentCommand === undefined || customAgentCommand.trim().length === 0) {
+    delete next.customAgentCommand
+  } else {
+    next.customAgentCommand = customAgentCommand
+  }
+  return normalizeRepoAiDraft(next)
+}
+
+export function withRepoAiHostedReviewDefault(
+  base: RepoSourceControlAiOverrides,
+  key: keyof NonNullable<RepoSourceControlAiOverrides['prCreationDefaults']>,
+  value: 'inherit' | 'on' | 'off'
+): RepoSourceControlAiOverrides {
+  const nextDefaults = { ...base.prCreationDefaults }
+  if (value === 'inherit') {
+    delete nextDefaults[key]
+  } else {
+    nextDefaults[key] = value === 'on'
+  }
+  return normalizeRepoAiDraft({
+    ...base,
+    prCreationDefaults: Object.keys(nextDefaults).length > 0 ? nextDefaults : undefined
   })
 }
 
-/**
- * Layer only one action's draft override onto the last-saved repo settings, so a
- * per-action save persists that recipe without flushing other rows' edits.
- */
-export function buildActionScopedRepoAiSave(
-  persisted: RepoSourceControlAiOverrides,
-  draft: RepoSourceControlAiOverrides,
-  actionId: SourceControlActionId
+export function withRepoAiActionMode(
+  base: RepoSourceControlAiOverrides,
+  settings: GlobalSettings | null,
+  actionId: SourceControlActionId,
+  mode: 'inherit' | 'override'
 ): RepoSourceControlAiOverrides {
-  const nextActionOverrides = { ...persisted.actionOverrides }
-  if (hasOwnActionOverride(draft.actionOverrides, actionId)) {
-    nextActionOverrides[actionId] = draft.actionOverrides?.[actionId]
-  } else {
+  const nextActionOverrides = { ...base.actionOverrides }
+  if (mode === 'inherit') {
     delete nextActionOverrides[actionId]
+    return normalizeRepoAiDraft(
+      dropRepoLegacyInstructionForAction(
+        {
+          ...base,
+          actionOverrides:
+            Object.keys(nextActionOverrides).length > 0 ? nextActionOverrides : undefined
+        },
+        actionId
+      )
+    )
+  }
+  if (!hasOwnActionOverride(nextActionOverrides, actionId)) {
+    nextActionOverrides[actionId] = readCompleteRecipeForDraft(base, settings, actionId)
   }
   return normalizeRepoAiDraft(
-    dropRepoLegacyInstructionForAction(
-      { ...persisted, actionOverrides: nextActionOverrides },
-      actionId
-    )
+    dropRepoLegacyInstructionForAction({ ...base, actionOverrides: nextActionOverrides }, actionId)
   )
 }
+
+export function withRepoAiActionAgent(
+  base: RepoSourceControlAiOverrides,
+  settings: GlobalSettings | null,
+  actionId: SourceControlActionId,
+  agentId: RepoActionRecipe['agentId']
+): RepoSourceControlAiOverrides {
+  const currentRecipe =
+    base.actionOverrides?.[actionId] ?? readCompleteRecipeForDraft(base, settings, actionId)
+  return normalizeRepoAiDraft(
+    setActionOverride(base, actionId, {
+      ...currentRecipe,
+      agentId
+    })
+  )
+}
+
+export function withRepoAiActionRecipeText(
+  base: RepoSourceControlAiOverrides,
+  settings: GlobalSettings | null,
+  actionId: SourceControlActionId,
+  text: { commandInputTemplate: string; agentArgs: string }
+): RepoSourceControlAiOverrides {
+  const currentRecipe =
+    base.actionOverrides?.[actionId] ?? readCompleteRecipeForDraft(base, settings, actionId)
+  return normalizeRepoAiDraft(
+    setActionOverride(base, actionId, {
+      ...currentRecipe,
+      commandInputTemplate: text.commandInputTemplate,
+      agentArgs: text.agentArgs
+    })
+  )
+}
+
+export type ActionRecipeTextDraft = {
+  commandInputTemplate: string
+  agentArgs: string
+}
+
+export function readActionRecipeTextDraft(
+  value: RepoSourceControlAiOverrides,
+  actionId: SourceControlActionId
+): ActionRecipeTextDraft {
+  const recipe = value.actionOverrides?.[actionId]
+  return {
+    commandInputTemplate:
+      typeof recipe?.commandInputTemplate === 'string' ? recipe.commandInputTemplate : '',
+    agentArgs: typeof recipe?.agentArgs === 'string' ? recipe.agentArgs : ''
+  }
+}
+
+/** Overlay the in-flight custom-command and per-action text drafts onto the optimistic value for display. */
+export function composeDisplayRepoAi(
+  immediate: RepoSourceControlAiOverrides,
+  customCommandDraft: string | null,
+  actionTextDrafts: Partial<Record<SourceControlActionId, ActionRecipeTextDraft>>
+): RepoSourceControlAiOverrides {
+  let next =
+    customCommandDraft === null ? immediate : withRepoAiCustomCommand(immediate, customCommandDraft)
+  for (const actionId of SOURCE_CONTROL_ACTION_IDS) {
+    const draft = actionTextDrafts[actionId]
+    const currentRecipe = next.actionOverrides?.[actionId]
+    if (!draft || !hasOwnActionOverride(next.actionOverrides, actionId) || !currentRecipe) {
+      continue
+    }
+    next = {
+      ...next,
+      actionOverrides: {
+        ...next.actionOverrides,
+        [actionId]: {
+          ...currentRecipe,
+          commandInputTemplate: draft.commandInputTemplate,
+          agentArgs: draft.agentArgs
+        }
+      }
+    }
+  }
+  return next
+}
+
+/** Per-action dirty flags: does the text draft (or optimistic override) differ from the persisted recipe? */
+export function computeActionDirtyById(
+  immediate: RepoSourceControlAiOverrides,
+  persisted: RepoSourceControlAiOverrides,
+  actionTextDrafts: Partial<Record<SourceControlActionId, ActionRecipeTextDraft>>
+): Record<SourceControlActionId, boolean> {
+  return Object.fromEntries(
+    SOURCE_CONTROL_ACTION_IDS.map((actionId) => {
+      if (!hasOwnActionOverride(immediate.actionOverrides, actionId)) {
+        return [actionId, false]
+      }
+      const draft = actionTextDrafts[actionId] ?? readActionRecipeTextDraft(immediate, actionId)
+      // Prefer persisted text as the base; if the override is only optimistic, compare against immediate.
+      const compareBase = hasOwnActionOverride(persisted.actionOverrides, actionId)
+        ? readActionRecipeTextDraft(persisted, actionId)
+        : readActionRecipeTextDraft(immediate, actionId)
+      return [
+        actionId,
+        draft.commandInputTemplate !== compareBase.commandInputTemplate ||
+          draft.agentArgs !== compareBase.agentArgs
+      ]
+    })
+  ) as Record<SourceControlActionId, boolean>
+}
+
+/** Keep only action text drafts that still diverge from the latest persisted recipes. */
+export function retainDivergentActionTextDrafts(
+  current: Partial<Record<SourceControlActionId, ActionRecipeTextDraft>>,
+  persisted: RepoSourceControlAiOverrides
+): Partial<Record<SourceControlActionId, ActionRecipeTextDraft>> {
+  const next: Partial<Record<SourceControlActionId, ActionRecipeTextDraft>> = {}
+  for (const actionId of SOURCE_CONTROL_ACTION_IDS) {
+    const draft = current[actionId]
+    if (!draft || !hasOwnActionOverride(persisted.actionOverrides, actionId)) {
+      continue
+    }
+    const persistedText = readActionRecipeTextDraft(persisted, actionId)
+    if (
+      draft.commandInputTemplate !== persistedText.commandInputTemplate ||
+      draft.agentArgs !== persistedText.agentArgs
+    ) {
+      next[actionId] = draft
+    }
+  }
+  return next
+}
+
+/** Keep a custom-command draft only while it still diverges from the persisted value. */
+export function retainCustomCommandDraft(
+  current: string | null,
+  persistedCustomCommand: string | undefined
+): string | null {
+  return current === null || current === (persistedCustomCommand ?? '') ? null : current
+}
+
+/** Drop an action draft after save unless the user typed something newer while save was in flight. */
+export function clearActionTextDraftIfUnchanged(
+  current: Partial<Record<SourceControlActionId, ActionRecipeTextDraft>>,
+  actionId: SourceControlActionId,
+  saved: ActionRecipeTextDraft
+): Partial<Record<SourceControlActionId, ActionRecipeTextDraft>> {
+  const latest = current[actionId]
+  if (
+    latest &&
+    (latest.commandInputTemplate !== saved.commandInputTemplate ||
+      latest.agentArgs !== saved.agentArgs)
+  ) {
+    return current
+  }
+  const { [actionId]: _removed, ...rest } = current
+  return rest
+}
+
+export function patchActionTextDraft(
+  current: Partial<Record<SourceControlActionId, ActionRecipeTextDraft>>,
+  immediate: RepoSourceControlAiOverrides,
+  actionId: SourceControlActionId,
+  patch: Partial<ActionRecipeTextDraft>
+): Partial<Record<SourceControlActionId, ActionRecipeTextDraft>> {
+  return {
+    ...current,
+    [actionId]: {
+      ...(current[actionId] ?? readActionRecipeTextDraft(immediate, actionId)),
+      ...patch
+    }
+  }
+}
diff --git a/src/renderer/src/components/settings/repository-source-control-ai-global-ux.test.ts b/src/renderer/src/components/settings/repository-source-control-ai-global-ux.test.ts
new file mode 100644
index 00000000000..b22d20b72d2
--- /dev/null
+++ b/src/renderer/src/components/settings/repository-source-control-ai-global-ux.test.ts
@@ -0,0 +1,236 @@
+// @vitest-environment happy-dom
+import { act, renderHook } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { normalizeSourceControlAiSettings } from '../../../../shared/source-control-ai'
+import type { RepoSourceControlAiOverrides } from '../../../../shared/source-control-ai-types'
+import type { SourceControlAiRepoUpdate } from '../../../../shared/source-control-ai-recipe-save'
+import { useRepositorySourceControlAiGlobalUx } from './repository-source-control-ai-global-ux'
+
+const source = normalizeSourceControlAiSettings(undefined, undefined)
+
+function setup(
+  persistedRepoAi: RepoSourceControlAiOverrides,
+  updateRepo: (repoId: string, updates: SourceControlAiRepoUpdate) => void | Promise<boolean>,
+  repoId = 'repo-1'
+) {
+  return renderHook(
+    (props: { repoId: string; persistedRepoAi: RepoSourceControlAiOverrides }) =>
+      useRepositorySourceControlAiGlobalUx({
+        repoId: props.repoId,
+        persistedRepoAi: props.persistedRepoAi,
+        settings: null,
+        source,
+        updateRepo
+      }),
+    { initialProps: { repoId, persistedRepoAi } }
+  )
+}
+
+const withRecipe = (commandInputTemplate: string): RepoSourceControlAiOverrides => ({
+  actionOverrides: {
+    fixCommitFailure: { agentId: null, commandInputTemplate, agentArgs: '' }
+  }
+})
+
+describe('useRepositorySourceControlAiGlobalUx', () => {
+  it('keeps an optimistic immediate field when the persist succeeds', async () => {
+    const updateRepo = vi.fn().mockResolvedValue(true)
+    const { result } = setup({}, updateRepo)
+    await act(async () => {
+      result.current.updateEnablement(true)
+    })
+    expect(result.current.displayRepoAi.enabled).toBe(true)
+    expect(updateRepo).toHaveBeenCalledTimes(1)
+    expect(result.current.saveError).toBeNull()
+  })
+
+  it('drafts the custom command locally and only persists on commit', async () => {
+    const updateRepo = vi.fn().mockResolvedValue(true)
+    const { result } = setup({}, updateRepo)
+    act(() => {
+      result.current.updateCustomCommand('ollama run llama3.1 {prompt}')
+    })
+    // The typed value is shown immediately but NOT written to the backend per keystroke.
+    expect(result.current.displayRepoAi.customAgentCommand).toBe('ollama run llama3.1 {prompt}')
+    expect(updateRepo).not.toHaveBeenCalled()
+    await act(async () => {
+      result.current.commitCustomCommand('ollama run llama3.1 {prompt}')
+    })
+    expect(updateRepo).toHaveBeenCalledTimes(1)
+    expect(result.current.displayRepoAi.customAgentCommand).toBe('ollama run llama3.1 {prompt}')
+  })
+
+  it('does not call updateRepo when committing an unchanged custom command', async () => {
+    const updateRepo = vi.fn().mockResolvedValue(true)
+    const { result } = setup({ customAgentCommand: 'same cmd' }, updateRepo)
+    await act(async () => {
+      result.current.commitCustomCommand('same cmd')
+    })
+    expect(updateRepo).not.toHaveBeenCalled()
+    expect(result.current.saveError).toBeNull()
+  })
+
+  it('clears dirty immediately after a successful action save without a prop echo', async () => {
+    const updateRepo = vi.fn().mockResolvedValue(true)
+    const { result } = setup(withRecipe('orig'), updateRepo)
+    act(() => {
+      result.current.updateActionTemplate('fixCommitFailure', 'edited')
+    })
+    expect(result.current.actionDirtyById.fixCommitFailure).toBe(true)
+    await act(async () => {
+      await result.current.saveActionRecipeText('fixCommitFailure')
+    })
+    // Baseline advances from setPersisted even before parent re-renders with new props.
+    expect(result.current.actionDirtyById.fixCommitFailure).toBe(false)
+    expect(
+      result.current.displayRepoAi.actionOverrides?.fixCommitFailure?.commandInputTemplate
+    ).toBe('edited')
+  })
+
+  it('reverts a typed action draft to the persisted template when discarded', async () => {
+    const updateRepo = vi.fn().mockResolvedValue(true)
+    const { result } = setup(withRecipe('orig'), updateRepo)
+    act(() => {
+      result.current.updateActionTemplate('fixCommitFailure', 'edited')
+    })
+    expect(result.current.actionDirtyById.fixCommitFailure).toBe(true)
+    act(() => {
+      result.current.discardActionRecipeText('fixCommitFailure')
+    })
+    // Discard drops the draft: dirty clears and the template reverts to the persisted value.
+    expect(result.current.actionDirtyById.fixCommitFailure).toBe(false)
+    expect(
+      result.current.displayRepoAi.actionOverrides?.fixCommitFailure?.commandInputTemplate
+    ).toBe('orig')
+    expect(updateRepo).not.toHaveBeenCalled()
+  })
+
+  it('keeps the custom command draft shown when the commit fails', async () => {
+    const updateRepo = vi.fn().mockResolvedValue(false)
+    const { result } = setup({}, updateRepo)
+    act(() => {
+      result.current.updateCustomCommand('bad cmd')
+    })
+    await act(async () => {
+      result.current.commitCustomCommand('bad cmd')
+    })
+    expect(result.current.displayRepoAi.customAgentCommand).toBe('bad cmd')
+    expect(result.current.saveError).toBe('Failed to save Source Control AI settings.')
+  })
+
+  it('rolls an optimistic immediate field back to persisted when the persist fails', async () => {
+    const updateRepo = vi.fn().mockResolvedValue(false)
+    const { result } = setup({}, updateRepo)
+    await act(async () => {
+      result.current.updateEnablement(true)
+    })
+    // A failed save must not leave the toggle showing an unsaved value as if it were saved.
+    expect(result.current.displayRepoAi.enabled).toBeUndefined()
+    expect(result.current.saveError).toBe('Failed to save Source Control AI settings.')
+  })
+
+  it('leaves an action recipe row dirty and retryable when its save fails', async () => {
+    const updateRepo = vi.fn().mockResolvedValue(false)
+    const { result } = setup(withRecipe('orig'), updateRepo)
+    act(() => {
+      result.current.updateActionTemplate('fixCommitFailure', 'edited')
+    })
+    expect(result.current.actionDirtyById.fixCommitFailure).toBe(true)
+    await act(async () => {
+      await result.current.saveActionRecipeText('fixCommitFailure')
+    })
+    expect(result.current.actionDirtyById.fixCommitFailure).toBe(true)
+    expect(result.current.saveError).toBe('Failed to save Source Control AI settings.')
+  })
+
+  it('preserves keystrokes typed while an action save is in flight', async () => {
+    let resolveUpdate: (ok: boolean) => void = () => {}
+    const updateRepo = vi.fn().mockReturnValue(
+      new Promise<boolean>((resolve) => {
+        resolveUpdate = resolve
+      })
+    )
+    const { result } = setup(withRecipe('orig'), updateRepo)
+    act(() => {
+      result.current.updateActionTemplate('fixCommitFailure', 'first')
+    })
+    let savePromise: Promise<void> = Promise.resolve()
+    await act(async () => {
+      savePromise = result.current.saveActionRecipeText('fixCommitFailure')
+      // flush the queue microtask so updateRepo is called and left pending
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+    expect(updateRepo).toHaveBeenCalledTimes(1)
+    // user keeps typing while the save is in flight
+    act(() => {
+      result.current.updateActionTemplate('fixCommitFailure', 'first-and-more')
+    })
+    await act(async () => {
+      resolveUpdate(true)
+      await savePromise
+    })
+    expect(
+      result.current.displayRepoAi.actionOverrides?.fixCommitFailure?.commandInputTemplate
+    ).toBe('first-and-more')
+    expect(result.current.actionDirtyById.fixCommitFailure).toBe(true)
+  })
+
+  it('resets drafts and saving state when the selected repo changes', async () => {
+    let resolveUpdate: (ok: boolean) => void = () => {}
+    const updateRepo = vi.fn().mockReturnValue(
+      new Promise<boolean>((resolve) => {
+        resolveUpdate = resolve
+      })
+    )
+    const { result, rerender } = setup(withRecipe('orig'), updateRepo)
+    act(() => {
+      result.current.updateActionTemplate('fixCommitFailure', 'editing-a')
+      result.current.updateCustomCommand('cmd-a')
+    })
+    let savePromise: Promise<void> = Promise.resolve()
+    await act(async () => {
+      savePromise = result.current.saveActionRecipeText('fixCommitFailure')
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+    expect(result.current.savingActionIds.fixCommitFailure).toBe(true)
+
+    await act(async () => {
+      rerender({ repoId: 'repo-2', persistedRepoAi: withRecipe('repo-2-template') })
+    })
+    expect(
+      result.current.displayRepoAi.actionOverrides?.fixCommitFailure?.commandInputTemplate
+    ).toBe('repo-2-template')
+    expect(result.current.displayRepoAi.customAgentCommand).toBeUndefined()
+    expect(result.current.savingActionIds.fixCommitFailure).toBeFalsy()
+    expect(result.current.actionDirtyById.fixCommitFailure).toBe(false)
+
+    await act(async () => {
+      resolveUpdate(true)
+      await savePromise
+    })
+    // Completing the previous repo's save must not re-apply its draft onto repo-2.
+    expect(
+      result.current.displayRepoAi.actionOverrides?.fixCommitFailure?.commandInputTemplate
+    ).toBe('repo-2-template')
+  })
+
+  it('keeps a successful agent optimistic value when a later enablement persist fails', async () => {
+    const updateRepo = vi
+      .fn()
+      .mockResolvedValueOnce(true) // action mode
+      .mockResolvedValueOnce(true) // agent
+      .mockResolvedValueOnce(false) // enablement
+    const { result } = setup({}, updateRepo)
+    await act(async () => {
+      result.current.updateActionMode('fixCommitFailure', 'override')
+      result.current.updateActionAgent('fixCommitFailure', 'codex')
+      result.current.updateEnablement(true)
+    })
+    // Enablement rolls back; the successfully saved agent override must remain visible.
+    expect(result.current.displayRepoAi.enabled).toBeUndefined()
+    expect(result.current.displayRepoAi.actionOverrides?.fixCommitFailure?.agentId).toBe('codex')
+    expect(result.current.saveError).toBe('Failed to save Source Control AI settings.')
+  })
+})
diff --git a/src/renderer/src/components/settings/repository-source-control-ai-global-ux.ts b/src/renderer/src/components/settings/repository-source-control-ai-global-ux.ts
new file mode 100644
index 00000000000..9cce9bc30fe
--- /dev/null
+++ b/src/renderer/src/components/settings/repository-source-control-ai-global-ux.ts
@@ -0,0 +1,316 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import type { GlobalSettings, TuiAgent } from '../../../../shared/types'
+import { CUSTOM_AGENT_ID } from '../../../../shared/commit-message-agent-spec'
+import type {
+  RepoSourceControlAiOverrides,
+  SourceControlAiSettings
+} from '../../../../shared/source-control-ai-types'
+import type { SourceControlAiRepoUpdate } from '../../../../shared/source-control-ai-recipe-save'
+import type { SourceControlActionId } from '../../../../shared/source-control-ai-actions'
+import { useMountedRef } from '@/hooks/useMountedRef'
+import {
+  clearActionTextDraftIfUnchanged,
+  composeDisplayRepoAi,
+  computeActionDirtyById,
+  hasOwnActionOverride,
+  patchActionTextDraft,
+  readActionRecipeTextDraft,
+  type ActionRecipeTextDraft,
+  retainCustomCommandDraft,
+  retainDivergentActionTextDrafts,
+  withRepoAiActionAgent,
+  withRepoAiActionMode,
+  withRepoAiActionRecipeText,
+  withRepoAiCustomCommand,
+  withRepoAiEnabled,
+  withRepoAiHostedReviewDefault
+} from './repository-source-control-ai-draft'
+import {
+  ACTION_MODE_INHERIT,
+  DEFAULT_AGENT_VALUE,
+  readInheritedCommandTemplate
+} from './repository-source-control-ai-labels'
+import { createRepoAiPersistQueue } from './repository-source-control-ai-persist-queue'
+
+export { normalizeRepoAiDraft as normalizePersistedRepoAi } from './repository-source-control-ai-draft'
+
+type HostedReviewDefaultKey = keyof NonNullable<RepoSourceControlAiOverrides['prCreationDefaults']>
+
+type UseRepositorySourceControlAiGlobalUxArgs = {
+  repoId: string
+  persistedRepoAi: RepoSourceControlAiOverrides
+  settings: GlobalSettings | null
+  source: SourceControlAiSettings
+  updateRepo: (repoId: string, updates: SourceControlAiRepoUpdate) => void | Promise<boolean>
+}
+
+/**
+ * Match global Source Control AI save UX for per-repo overrides:
+ * - Selects / simple controls persist immediately (optimistic UI)
+ * - Action CLI args + command template draft until the per-action Save
+ */
+export function useRepositorySourceControlAiGlobalUx({
+  repoId,
+  persistedRepoAi,
+  settings,
+  source,
+  updateRepo
+}: UseRepositorySourceControlAiGlobalUxArgs) {
+  const mountedRef = useMountedRef()
+  const persistedSerialized = useMemo(() => JSON.stringify(persistedRepoAi), [persistedRepoAi])
+  const persistedRef = useRef(persistedRepoAi)
+  const repoIdRef = useRef(repoId)
+  const updateRepoRef = useRef(updateRepo)
+  repoIdRef.current = repoId
+  updateRepoRef.current = updateRepo
+
+  const [saveError, setSaveError] = useState<string | null>(null)
+  const [immediateRepoAi, setImmediateRepoAi] = useState(persistedRepoAi)
+  const immediateRepoAiRef = useRef(immediateRepoAi)
+  immediateRepoAiRef.current = immediateRepoAi
+  // Local baseline for dirty checks so Save clears before the store prop echo lands.
+  const [baselineRepoAi, setBaselineRepoAi] = useState(persistedRepoAi)
+  const setBaselineRepoAiRef = useRef(setBaselineRepoAi)
+  setBaselineRepoAiRef.current = setBaselineRepoAi
+  const [actionTextDrafts, setActionTextDrafts] = useState<
+    Partial<Record<SourceControlActionId, ActionRecipeTextDraft>>
+  >({})
+  const [customCommandDraft, setCustomCommandDraft] = useState<string | null>(null)
+  const [savingActionIds, setSavingActionIds] = useState<
+    Partial<Record<SourceControlActionId, boolean>>
+  >({})
+  const lastSyncedRepoIdRef = useRef(repoId)
+  const pendingWritesRef = useRef(0)
+
+  const queueRef = useRef(
+    createRepoAiPersistQueue({
+      getRepoId: () => repoIdRef.current,
+      getPersisted: () => persistedRef.current,
+      setPersisted: (value) => {
+        persistedRef.current = value
+        if (mountedRef.current) {
+          setBaselineRepoAiRef.current(value)
+        }
+      },
+      updateRepo: (id, updates) => updateRepoRef.current(id, updates),
+      isMounted: () => mountedRef.current,
+      onError: (message) => {
+        if (mountedRef.current) {
+          setSaveError(message)
+        }
+      }
+    })
+  )
+
+  useEffect(() => {
+    const repoChanged = lastSyncedRepoIdRef.current !== repoId
+    lastSyncedRepoIdRef.current = repoId
+    persistedRef.current = persistedRepoAi
+    setBaselineRepoAi(persistedRepoAi)
+    if (repoChanged) {
+      pendingWritesRef.current = 0
+      setImmediateRepoAi(persistedRepoAi)
+      setActionTextDrafts({})
+      setCustomCommandDraft(null)
+      setSavingActionIds({})
+      setSaveError(null)
+      return
+    }
+    if (pendingWritesRef.current === 0) {
+      setImmediateRepoAi(persistedRepoAi)
+    }
+    setCustomCommandDraft((current) =>
+      retainCustomCommandDraft(current, persistedRepoAi.customAgentCommand)
+    )
+    setActionTextDrafts((current) => retainDivergentActionTextDrafts(current, persistedRepoAi))
+  }, [persistedSerialized, persistedRepoAi, repoId])
+
+  const commitImmediate = (next: RepoSourceControlAiOverrides): void => {
+    immediateRepoAiRef.current = next
+    setImmediateRepoAi(next)
+  }
+
+  const beginWrite = (): string => {
+    setSaveError(null)
+    pendingWritesRef.current += 1
+    return repoIdRef.current
+  }
+
+  const endWrite = (repoIdForWrite: string): boolean => {
+    pendingWritesRef.current = Math.max(0, pendingWritesRef.current - 1)
+    return repoIdRef.current === repoIdForWrite && mountedRef.current
+  }
+
+  const persist = (
+    transform: (base: RepoSourceControlAiOverrides) => RepoSourceControlAiOverrides
+  ): void => {
+    const repoIdForWrite = beginWrite()
+    void queueRef.current.persistTransform(transform).then((ok) => {
+      if (!endWrite(repoIdForWrite)) {
+        return
+      }
+      // Only snap when no sibling write is in flight — a failed field must not wipe another.
+      if (!ok && pendingWritesRef.current === 0) {
+        commitImmediate(persistedRef.current)
+      }
+    })
+  }
+
+  const updateEnablement = (value: boolean | undefined): void => {
+    commitImmediate(withRepoAiEnabled(immediateRepoAiRef.current, value))
+    persist((base) => withRepoAiEnabled(base, value))
+  }
+
+  const updateCustomCommand = (value: string | undefined): void => {
+    setCustomCommandDraft(value ?? '')
+  }
+
+  const commitCustomCommand = (value: string | undefined): void => {
+    setCustomCommandDraft(value ?? '')
+    // Blur fires even when unchanged — skip the queue for true no-ops.
+    const next = withRepoAiCustomCommand(persistedRef.current, value)
+    if (JSON.stringify(next) === JSON.stringify(persistedRef.current)) {
+      setCustomCommandDraft((latest) => (latest === (value ?? '') ? null : latest))
+      return
+    }
+    const repoIdForWrite = beginWrite()
+    void queueRef.current
+      .persistTransform((base) => withRepoAiCustomCommand(base, value))
+      .then((ok) => {
+        if (!endWrite(repoIdForWrite)) {
+          return
+        }
+        if (!ok) {
+          return
+        }
+        commitImmediate(withRepoAiCustomCommand(immediateRepoAiRef.current, value))
+        setCustomCommandDraft((latest) => (latest === (value ?? '') ? null : latest))
+      })
+  }
+
+  const updateHostedReviewDefault = (key: HostedReviewDefaultKey, value: string): void => {
+    const tri = value === 'on' || value === 'off' || value === 'inherit' ? value : 'inherit'
+    commitImmediate(withRepoAiHostedReviewDefault(immediateRepoAiRef.current, key, tri))
+    persist((base) => withRepoAiHostedReviewDefault(base, key, tri))
+  }
+
+  const updateActionMode = (actionId: SourceControlActionId, mode: string): void => {
+    const nextMode = mode === ACTION_MODE_INHERIT ? 'inherit' : 'override'
+    if (nextMode === 'inherit') {
+      setActionTextDrafts((current) => {
+        const { [actionId]: _removed, ...rest } = current
+        return rest
+      })
+    }
+    commitImmediate(withRepoAiActionMode(immediateRepoAiRef.current, settings, actionId, nextMode))
+    persist((base) => withRepoAiActionMode(base, settings, actionId, nextMode))
+  }
+
+  const updateActionAgent = (actionId: SourceControlActionId, value: string): void => {
+    const agentId =
+      value === DEFAULT_AGENT_VALUE
+        ? null
+        : value === CUSTOM_AGENT_ID
+          ? CUSTOM_AGENT_ID
+          : (value as TuiAgent)
+    commitImmediate(withRepoAiActionAgent(immediateRepoAiRef.current, settings, actionId, agentId))
+    persist((base) => withRepoAiActionAgent(base, settings, actionId, agentId))
+  }
+
+  const updateActionTemplate = (actionId: SourceControlActionId, value: string): void => {
+    setActionTextDrafts((current) =>
+      patchActionTextDraft(current, immediateRepoAiRef.current, actionId, {
+        commandInputTemplate: value
+      })
+    )
+  }
+
+  const updateActionAgentArgs = (actionId: SourceControlActionId, value: string): void => {
+    setActionTextDrafts((current) =>
+      patchActionTextDraft(current, immediateRepoAiRef.current, actionId, { agentArgs: value })
+    )
+  }
+
+  const appendVariable = (actionId: SourceControlActionId, variable: string): void => {
+    setActionTextDrafts((current) => {
+      const draft =
+        current[actionId] ?? readActionRecipeTextDraft(immediateRepoAiRef.current, actionId)
+      const currentTemplate =
+        draft.commandInputTemplate.length > 0
+          ? draft.commandInputTemplate
+          : readInheritedCommandTemplate(source, actionId)
+      const separator = currentTemplate.endsWith('\n') || currentTemplate.length === 0 ? '' : ' '
+      return patchActionTextDraft(current, immediateRepoAiRef.current, actionId, {
+        commandInputTemplate: `${currentTemplate}${separator}{${variable}}`
+      })
+    })
+  }
+
+  const actionDirtyById = useMemo(
+    () => computeActionDirtyById(immediateRepoAi, baselineRepoAi, actionTextDrafts),
+    [actionTextDrafts, baselineRepoAi, immediateRepoAi]
+  )
+
+  const saveActionRecipeText = async (actionId: SourceControlActionId): Promise<void> => {
+    if (!actionDirtyById[actionId] || savingActionIds[actionId]) {
+      return
+    }
+    const draft =
+      actionTextDrafts[actionId] ?? readActionRecipeTextDraft(immediateRepoAiRef.current, actionId)
+    setSavingActionIds((current) => ({ ...current, [actionId]: true }))
+    const repoIdForWrite = beginWrite()
+    try {
+      const ok = await queueRef.current.persistTransform((base) => {
+        let next = base
+        if (!hasOwnActionOverride(next.actionOverrides, actionId)) {
+          next = withRepoAiActionMode(next, settings, actionId, 'override')
+        }
+        return withRepoAiActionRecipeText(next, settings, actionId, draft)
+      })
+      if (repoIdRef.current !== repoIdForWrite || !mountedRef.current || !ok) {
+        return
+      }
+      setImmediateRepoAi((current) => {
+        const next = withRepoAiActionRecipeText(current, settings, actionId, draft)
+        immediateRepoAiRef.current = next
+        return next
+      })
+      setActionTextDrafts((current) => clearActionTextDraftIfUnchanged(current, actionId, draft))
+    } finally {
+      pendingWritesRef.current = Math.max(0, pendingWritesRef.current - 1)
+      if (mountedRef.current && repoIdRef.current === repoIdForWrite) {
+        setSavingActionIds((current) => ({ ...current, [actionId]: false }))
+      }
+    }
+  }
+
+  const discardActionRecipeText = (actionId: SourceControlActionId): void => {
+    setActionTextDrafts((current) => {
+      const { [actionId]: _removed, ...rest } = current
+      return rest
+    })
+  }
+
+  const displayRepoAi = useMemo(
+    () => composeDisplayRepoAi(immediateRepoAi, customCommandDraft, actionTextDrafts),
+    [actionTextDrafts, customCommandDraft, immediateRepoAi]
+  )
+
+  return {
+    displayRepoAi,
+    saveError,
+    actionDirtyById,
+    savingActionIds,
+    updateEnablement,
+    updateCustomCommand,
+    commitCustomCommand,
+    updateHostedReviewDefault,
+    updateActionMode,
+    updateActionAgent,
+    updateActionTemplate,
+    updateActionAgentArgs,
+    appendVariable,
+    saveActionRecipeText,
+    discardActionRecipeText
+  }
+}
diff --git a/src/renderer/src/components/settings/repository-source-control-ai-persist-queue.test.ts b/src/renderer/src/components/settings/repository-source-control-ai-persist-queue.test.ts
new file mode 100644
index 00000000000..4e46ef043a3
--- /dev/null
+++ b/src/renderer/src/components/settings/repository-source-control-ai-persist-queue.test.ts
@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { RepoSourceControlAiOverrides } from '../../../../shared/source-control-ai-types'
+import { createRepoAiPersistQueue } from './repository-source-control-ai-persist-queue'
+
+type Harness = ReturnType<typeof makeQueue>
+
+function makeQueue(opts: { isMounted?: () => boolean; getRepoId?: () => string } = {}) {
+  let persisted: RepoSourceControlAiOverrides = {}
+  let repoId = 'repo-1'
+  const updateRepo = vi.fn()
+  const onError = vi.fn()
+  const setPersisted = vi.fn((value: RepoSourceControlAiOverrides) => {
+    persisted = value
+  })
+  const queue = createRepoAiPersistQueue({
+    getRepoId: opts.getRepoId ?? (() => repoId),
+    getPersisted: () => persisted,
+    setPersisted,
+    updateRepo,
+    isMounted: opts.isMounted ?? (() => true),
+    onError
+  })
+  return {
+    queue,
+    updateRepo,
+    onError,
+    setPersisted,
+    getPersisted: () => persisted,
+    setRepoId: (next: string) => {
+      repoId = next
+    }
+  }
+}
+
+describe('createRepoAiPersistQueue', () => {
+  let h: Harness
+  beforeEach(() => {
+    h = makeQueue()
+  })
+
+  it('persists a changed value and stores the normalized saved result', async () => {
+    h.updateRepo.mockResolvedValue(true)
+    const ok = await h.queue.persistTransform((base) => ({ ...base, enabled: true }))
+    expect(ok).toBe(true)
+    expect(h.updateRepo).toHaveBeenCalledTimes(1)
+    expect(h.getPersisted()).toMatchObject({ enabled: true })
+  })
+
+  it('skips the backend write when the transform is a no-op', async () => {
+    h.updateRepo.mockResolvedValue(true)
+    const ok = await h.queue.persistTransform((base) => base)
+    expect(ok).toBe(true)
+    expect(h.updateRepo).not.toHaveBeenCalled()
+  })
+
+  it('serializes queued writes so each composes off the previous saved result', async () => {
+    h.updateRepo.mockResolvedValue(true)
+    const p1 = h.queue.persistTransform((base) => ({ ...base, enabled: true }))
+    const p2 = h.queue.persistTransform((base) => ({ ...base, customAgentCommand: 'run {prompt}' }))
+    await Promise.all([p1, p2])
+    expect(h.updateRepo).toHaveBeenCalledTimes(2)
+    // The second write must carry the first write's field -> it ran against the persisted result, not stale base.
+    expect(h.getPersisted()).toMatchObject({ enabled: true, customAgentCommand: 'run {prompt}' })
+  })
+
+  it('returns false and reports an error when updateRepo returns false, leaving persisted untouched', async () => {
+    h.updateRepo.mockResolvedValue(false)
+    const ok = await h.queue.persistTransform((base) => ({ ...base, enabled: true }))
+    expect(ok).toBe(false)
+    expect(h.onError).toHaveBeenCalledWith('Failed to save Source Control AI settings.')
+    expect(h.setPersisted).not.toHaveBeenCalled()
+    expect(h.getPersisted()).toEqual({})
+  })
+
+  it('returns false and reports an error when updateRepo throws', async () => {
+    h.updateRepo.mockRejectedValue(new Error('ipc down'))
+    const ok = await h.queue.persistTransform((base) => ({ ...base, enabled: true }))
+    expect(ok).toBe(false)
+    expect(h.onError).toHaveBeenCalledWith('Failed to save Source Control AI settings.')
+    expect(h.setPersisted).not.toHaveBeenCalled()
+  })
+
+  it('does not write persisted or report an error after unmount', async () => {
+    const unmounted = makeQueue({ isMounted: () => false })
+    unmounted.updateRepo.mockResolvedValue(true)
+    const ok = await unmounted.queue.persistTransform((base) => ({ ...base, enabled: true }))
+    expect(ok).toBe(true)
+    expect(unmounted.setPersisted).not.toHaveBeenCalled()
+    expect(unmounted.onError).not.toHaveBeenCalled()
+  })
+
+  it('lets a failed write not block the next queued write', async () => {
+    h.updateRepo.mockResolvedValueOnce(false).mockResolvedValueOnce(true)
+    const p1 = h.queue.persistTransform((base) => ({ ...base, enabled: true }))
+    const p2 = h.queue.persistTransform((base) => ({ ...base, enabled: false }))
+    const [ok1, ok2] = await Promise.all([p1, p2])
+    expect(ok1).toBe(false)
+    expect(ok2).toBe(true)
+    expect(h.updateRepo).toHaveBeenCalledTimes(2)
+    expect(h.getPersisted()).toMatchObject({ enabled: false })
+  })
+
+  it('abandons a queued write when the selected repo changes before it runs', async () => {
+    let releaseFirst: () => void = () => {}
+    h.updateRepo.mockImplementationOnce(
+      () =>
+        new Promise<boolean>((resolve) => {
+          releaseFirst = () => resolve(true)
+        })
+    )
+    const p1 = h.queue.persistTransform((base) => ({ ...base, enabled: true }))
+    // Let the first write enter updateRepo before queuing the second / switching repos.
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(h.updateRepo).toHaveBeenCalledTimes(1)
+    expect(h.updateRepo.mock.calls[0]?.[0]).toBe('repo-1')
+
+    const p2 = h.queue.persistTransform((base) => ({
+      ...base,
+      customAgentCommand: 'should-not-write'
+    }))
+    // Switch repos while the first write is in flight and the second is queued.
+    h.setRepoId('repo-2')
+    releaseFirst()
+    const [ok1, ok2] = await Promise.all([p1, p2])
+    expect(ok1).toBe(true)
+    expect(ok2).toBe(true)
+    // Second must not run against repo-2.
+    expect(h.updateRepo).toHaveBeenCalledTimes(1)
+    // Completing a stale write must not seed the new repo's local persisted base.
+    expect(h.setPersisted).not.toHaveBeenCalled()
+  })
+
+  it('does not apply setPersisted when the repo switches during an in-flight updateRepo', async () => {
+    let release: (ok: boolean) => void = () => {}
+    h.updateRepo.mockImplementation(
+      () =>
+        new Promise<boolean>((resolve) => {
+          release = resolve
+        })
+    )
+    const pending = h.queue.persistTransform((base) => ({ ...base, enabled: true }))
+    h.setRepoId('repo-2')
+    release(true)
+    await expect(pending).resolves.toBe(true)
+    expect(h.setPersisted).not.toHaveBeenCalled()
+    expect(h.onError).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/components/settings/repository-source-control-ai-persist-queue.ts b/src/renderer/src/components/settings/repository-source-control-ai-persist-queue.ts
new file mode 100644
index 00000000000..e0e0c1022e4
--- /dev/null
+++ b/src/renderer/src/components/settings/repository-source-control-ai-persist-queue.ts
@@ -0,0 +1,73 @@
+import type { RepoSourceControlAiOverrides } from '../../../../shared/source-control-ai-types'
+import { normalizeRepoSourceControlAiOverrides } from '../../../../shared/source-control-ai'
+import { toSourceControlAiRepoUpdate } from '../../../../shared/source-control-ai-recipe-save'
+import type { SourceControlAiRepoUpdate } from '../../../../shared/source-control-ai-recipe-save'
+
+type PersistQueueOptions = {
+  getRepoId: () => string
+  getPersisted: () => RepoSourceControlAiOverrides
+  setPersisted: (value: RepoSourceControlAiOverrides) => void
+  updateRepo: (repoId: string, updates: SourceControlAiRepoUpdate) => void | Promise<boolean>
+  isMounted: () => boolean
+  onError: (message: string) => void
+}
+
+/** Serializes nested sourceControlAi writes so concurrent field updates cannot clobber each other. */
+export function createRepoAiPersistQueue(options: PersistQueueOptions) {
+  let chain: Promise<void> = Promise.resolve()
+
+  // Resolves true when the write persisted, was a no-op, or was abandoned after a repo switch.
+  // Resolves false when updateRepo failed. Why: callers keep optimistic UI honest (roll back a field /
+  // leave a recipe row dirty); a queue that swallowed failures made `await` always look like success
+  // and silently dropped edits. Abandoned writes return true so a repo switch does not surface a
+  // spurious error on the newly selected repo.
+  const persistTransform = (
+    transform: (base: RepoSourceControlAiOverrides) => RepoSourceControlAiOverrides
+  ): Promise<boolean> => {
+    // Why: pin the target at schedule time — if the settings pane switches repos before this
+    // transform runs, applying it against the new repo's base would corrupt that repo's overrides.
+    const repoIdForWrite = options.getRepoId()
+    const run = chain
+      .catch(() => undefined)
+      .then(async (): Promise<boolean> => {
+        if (options.getRepoId() !== repoIdForWrite) {
+          return true
+        }
+        // Why: keep transform()/toSourceControlAiRepoUpdate() inside the try so a throw there
+        // still routes through onError instead of becoming an unhandled rejection for fire-and-forget callers.
+        try {
+          const next = transform(options.getPersisted())
+          if (JSON.stringify(next) === JSON.stringify(options.getPersisted())) {
+            return true
+          }
+          const repoUpdate = toSourceControlAiRepoUpdate(next)
+          const result = await options.updateRepo(repoIdForWrite, repoUpdate)
+          // Why: even a successful write for the previous repo must not update local persisted state
+          // once the UI is showing a different repo (would seed the wrong base for later edits).
+          if (!options.isMounted() || options.getRepoId() !== repoIdForWrite) {
+            return true
+          }
+          if (result === false) {
+            options.onError('Failed to save Source Control AI settings.')
+            return false
+          }
+          const savedValue =
+            repoUpdate.sourceControlAi === null
+              ? {}
+              : (normalizeRepoSourceControlAiOverrides(repoUpdate.sourceControlAi) ?? {})
+          options.setPersisted(savedValue)
+          return true
+        } catch {
+          if (options.isMounted() && options.getRepoId() === repoIdForWrite) {
+            options.onError('Failed to save Source Control AI settings.')
+          }
+          return false
+        }
+      })
+    // Keep the shared chain a never-rejecting Promise<void> so one write's failure can't block the next.
+    chain = run.then(() => undefined)
+    return run
+  }
+
+  return { persistTransform }
+}

From 3efc9309086723f7b23e0fd85c8201273aa2fa48 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 17 Jul 2026 04:51:46 -0400
Subject: [PATCH 02/54] fix: preserve WSL CWD across daemon sleep wake

---
 docs/wsl-osc7-sleep-wake-cwd.md               | 153 ++++++++++++++++++
 .../daemon/daemon-create-or-attach-result.ts  |  24 +++
 src/main/daemon/daemon-pty-adapter.test.ts    |  42 ++++-
 src/main/daemon/daemon-pty-adapter.ts         |  68 +++++++-
 src/main/daemon/daemon-server.ts              |   1 +
 src/main/daemon/headless-emulator.test.ts     |  16 ++
 src/main/daemon/headless-emulator.ts          |   4 +-
 src/main/daemon/history-reader.test.ts        |  19 +++
 src/main/daemon/history-reader.ts             |  10 +-
 src/main/daemon/osc7-file-uri.test.ts         |  20 ++-
 src/main/daemon/osc7-file-uri.ts              |   6 +
 src/main/daemon/pty-subprocess.ts             |  30 +---
 src/main/daemon/session.test.ts               |   9 ++
 src/main/daemon/session.ts                    |   6 +-
 .../daemon/terminal-host-create-contract.ts   |   1 +
 .../daemon/terminal-host-wsl-context.test.ts  |  94 +++++++++++
 src/main/daemon/terminal-host.ts              |  10 +-
 .../daemon/terminal-osc-cwd-title-scanner.ts  |   4 +-
 src/main/daemon/types.ts                      |   9 +-
 src/main/daemon/wsl-cold-restore-cwd.test.ts  |  40 +++++
 src/main/daemon/wsl-cold-restore-cwd.ts       |  37 +++++
 src/main/daemon/wsl-session-context.ts        |  30 ++++
 src/main/ipc/pty.test.ts                      |  26 ++-
 src/main/ipc/pty.ts                           |  51 ++++++
 src/main/providers/types.ts                   |   2 +
 src/main/runtime/orca-runtime.test.ts         |  70 ++++++++
 src/main/runtime/orca-runtime.ts              | 131 ++++++++++++++-
 src/main/wsl.ts                               |  24 +--
 src/shared/wsl-paths.test.ts                  |  17 +-
 src/shared/wsl-paths.ts                       |  11 ++
 30 files changed, 887 insertions(+), 78 deletions(-)
 create mode 100644 docs/wsl-osc7-sleep-wake-cwd.md
 create mode 100644 src/main/daemon/daemon-create-or-attach-result.ts
 create mode 100644 src/main/daemon/terminal-host-wsl-context.test.ts
 create mode 100644 src/main/daemon/wsl-cold-restore-cwd.test.ts
 create mode 100644 src/main/daemon/wsl-cold-restore-cwd.ts

diff --git a/docs/wsl-osc7-sleep-wake-cwd.md b/docs/wsl-osc7-sleep-wake-cwd.md
new file mode 100644
index 00000000000..24d46b70660
--- /dev/null
+++ b/docs/wsl-osc7-sleep-wake-cwd.md
@@ -0,0 +1,153 @@
+# WSL OSC 7 Sleep/Wake CWD
+
+## Problem
+
+On native Windows, a WSL terminal can persist a fake UNC current working directory and then fail to wake. The deterministic trigger is a WSL shell emitting `file://<machine-hostname>/home/...` before sleep:
+
+- `osc7-file-uri.ts` treats every non-local authority as a UNC server when parsing Win32 paths.
+- `Session` constructs its daemon `HeadlessEmulator` without the WSL execution context, so checkpoints can store `\\<machine-hostname>\home\...`.
+- `OrcaRuntimeService` likewise gives every local Windows PTY Win32 OSC 7 semantics; `remotePosixAuthority` only protects POSIX SSH PTYs.
+- `HistoryReader.restoreFromIncrementalLog` creates a third context-free emulator. A log containing the OSC 7 can therefore re-create the bad CWD even if the base checkpoint is valid.
+- `DaemonPtyAdapter.doSpawn` prefers `restoreInfo.cwd` over the requested worktree CWD. `pty-subprocess.ts` later validates the fake UNC and rejects it before spawning WSL.
+
+Reproduction on Windows 11 build 26200, WSL 2.3.26.0, Ubuntu 24.04.1 LTS, and Orca 1.4.144-rc.4:
+
+1. Open a terminal in `\\wsl.localhost\Ubuntu\home\<user>\...`.
+2. Emit `OSC 7;file://<machine-hostname>/home/<user>/...`.
+3. Sleep for 38-69 seconds, then wake.
+
+Both triggered attempts failed. The saved CWD became `\\<machine-hostname>\home\<user>\...`; the original WSL UNC remained valid. A 60-second control sleep without the hostname OSC 7 passed.
+
+## Root cause and invariant
+
+OSC 7 authority semantics follow the PTY's execution environment, not Electron's host OS. A native Windows shell may legitimately mean `\\server\share` by `file://server/share`; a WSL shell means a POSIX pathname inside its already-known distro. Orca currently classifies local WSL PTYs as generic Win32 PTYs.
+
+The fix must establish one immutable `wslDistro: string | null` per PTY incarnation before any OSC 7 bytes or recovered history are parsed. The same value must drive daemon live parsing, incremental-history replay, runtime parsing, and legacy CWD recovery. URI authority must never select a distro.
+
+Resolve that value with the same precedence already used to launch WSL:
+
+1. distro in an explicit WSL UNC `cwd`;
+2. distro in the worktree encoded by the daemon session ID;
+3. trimmed `terminalWindowsWslDistro` selected for the spawn.
+
+Centralize this resolution with the existing WSL session-context code so the parser and subprocess cannot disagree. Do not infer local WSL context for `connectionId`/SSH PTYs.
+
+## Non-goals
+
+- Do not change native Windows UNC, POSIX SSH, or remote Windows drive-path semantics.
+- Do not redesign terminal history, sleep, renderer link routing, or PTY identity.
+- Do not probe WSL, DNS, the filesystem, or the network on the output path.
+- Do not infer a distro from an OSC hostname or mutable global/default-distro state.
+
+## Design
+
+### 1. Pure conversion and parser context
+
+Move `toWindowsWslPath` to `src/shared/wsl-paths.ts` and re-export it from `src/main/wsl.ts` for existing callers. Preserve its current rules: lowercase `/mnt/<ascii-letter>` maps to a native drive; every other absolute Linux path maps under `\\wsl.localhost\<distro>`. `/MNT` and `/mnt/C` are case-sensitive Linux paths, not drvfs aliases.
+
+Add `wslDistro?: string` to `ParseFileUriPathOptions`. When present, `parseFileUriPathParts` must:
+
+- decode `url.pathname` exactly once;
+- construct the path with `toWindowsWslPath(decodedPath, wslDistro)`, regardless of URI authority;
+- continue returning the normalized URI hostname as metadata;
+- reject malformed URLs/percent encoding as today and leave the prior CWD unchanged.
+
+Without `wslDistro`, retain every existing `pathFlavor` and `remotePosixAuthority` branch.
+
+Thread the option through `TerminalOscCwdTitleScanner` and `HeadlessEmulator`. Scanner options are constructor-scoped, so split sequences retain the same context without global state.
+
+### 2. Daemon and history ownership
+
+`TerminalHost` resolves the immutable distro before spawning. Pass it both to `createPtySubprocess` and to a new `SessionOptions.wslDistro`; `Session` passes it to its `HeadlessEmulator`. Store the resolved value on `Session` and return it on create/attach so a later window observes the live session's context instead of reinterpreting it from current settings. Make the response field additive/optional for compatibility with an older preserved daemon.
+
+Extend `HistoryReader.detectColdRestore` with optional parser context and use it for the scratch `HeadlessEmulator` in `restoreFromIncrementalLog`. Every detect path in `DaemonPtyAdapter`--initial detection, probe/create race recovery, and failed history seeding--must pass the same resolved distro. This is required; fixing only the live `Session` leaves incremental restore able to reproduce the bug.
+
+### 3. Narrow legacy checkpoint recovery
+
+Immediately after each cold-restore detection, normalize `restoreInfo.cwd` before it becomes `effectiveCwd` or `coldRestore.cwd`. Recovery runs only on native Windows with a resolved local WSL distro:
+
+1. Preserve an absolute drive path.
+2. Preserve a `\\wsl.localhost\...` or `\\wsl$\...` path only when its distro matches the resolved distro case-insensitively.
+3. Convert an absolute POSIX path through the resolved distro.
+4. Repair the known legacy shape only when the UNC server equals `os.hostname()` case-insensitively: strip the server, interpret the share and tail as the Linux absolute path, then convert it. Thus `\\HOST\mnt\c\x` becomes `C:\x`.
+5. For a mismatched-distro WSL UNC, another UNC server, a relative path, or malformed input, discard the recovered CWD and fall back to the current requested CWD (or the normal spawn default if none was supplied). Do not guess.
+
+Apply the corrected/fallback value to both subprocess creation and the returned cold-restore payload. This keeps runtime seeding, the sticky restore cache, `initialCwds`, and the next checkpoint consistent. The repair is idempotent and never mutates history files in place.
+
+### 4. Runtime ownership and races
+
+Add `wslDistro: string | null` to `RuntimePtyWorktreeRecord`; a boolean `isWsl` is insufficient for multi-distro parsing. Pass the resolved distro from the spawn result into runtime registration. For reconstructed local records, a WSL UNC worktree may supply a fallback distro via `parseWslUncPath`; never do this for SSH records.
+
+Daemon PTYs can emit output before `provider.spawn` resolves, and cold-restore seeding currently runs before `registerPty`. Register the expected daemon session's execution context before spawn, then replace it with the daemon-returned immutable value before snapshot/cold-restore seeding. If late discovery changes a context after a runtime emulator was created, discard that emulator and re-seed it from the authoritative provider snapshot; never keep a buffer whose CWD was parsed under mixed contexts.
+
+Clear execution context with the other per-PTY parser maps on exit, pruning, failed spawn, and provider-generation reset. Reusing a PTY ID must not inherit a prior distro.
+
+## Data flow
+
+```text
+spawn cwd/session/preference
+  -> resolve one immutable local WSL distro
+  -> daemon Session scanner + HistoryReader replay scanner
+  -> decoded OSC 7 pathname (authority retained only as metadata)
+  -> toWindowsWslPath(pathname, distro)
+  -> daemon checkpoint + runtime live/headless CWD
+  -> sleep/wake with a valid WSL UNC or drive CWD
+```
+
+Legacy recovery is a boundary repair:
+
+```text
+WSL cold restore + old checkpoint CWD
+  -> exact allowlist normalization
+  -> corrected spawn and coldRestore payload
+  -> next checkpoint naturally persists the corrected live CWD
+```
+
+## Consistency and failure modes
+
+- Context is per PTY incarnation, not global, so simultaneous Ubuntu and Debian panes cannot contaminate each other.
+- The first creator owns a daemon session's immutable context. Concurrent/multi-window attaches consume the stored value; changed settings do not mutate a live session.
+- A distro mismatch in externally changed history falls back to the requested worktree CWD instead of launching the wrong distro.
+- Atomic checkpoint replacement remains unchanged. Concurrent restore callers may read different complete generations, but each normalizes before spawn and daemon create/attach still selects one live session.
+- Missing context deliberately preserves current behavior. Tests must cover every local WSL construction path so this fallback cannot silently remain on the affected path.
+- Native UNC and SSH behavior remain isolated because neither receives local WSL context.
+- No filesystem/network work is added per output chunk; parsing remains bounded string work on completed OSC sequences.
+
+## Test plan
+
+- `osc7-file-uri.test.ts` and shared WSL-path tests: hostname/localhost/empty WSL authorities; hostname metadata; `/home`, `/`, lowercase `/mnt/c`, `/MNT`, `/mnt/C`; spaces/percent decoding; invalid encoding; native UNC; POSIX SSH; Windows SSH drive paths.
+- `headless-emulator.test.ts`: WSL context propagation across ordinary and split OSC sequences; two emulators with different distros.
+- `terminal-host.test.ts`/`session.test.ts`: resolved context reaches the daemon emulator; attach returns the session's stored context and does not adopt a conflicting later preference.
+- `history-reader.test.ts`: incremental-log replay containing the exact hostname OSC 7 yields the correct WSL CWD.
+- `daemon-pty-adapter.test.ts`: cover every `detectColdRestore` branch plus sticky-cache output. Repair hostname UNC and POSIX CWDs; preserve matching WSL UNC and drive paths; reject mismatched distro, other UNC, relative, native, and SSH/non-WSL cases. Assert both create/attach CWD and `coldRestore.cwd`.
+- `orca-runtime.test.ts` and IPC PTY tests: context exists before early daemon output and before headless seeding; Windows-host worktree with a selected WSL distro; WSL UNC fallback after reconstruction; attach correction; PTY-ID reuse; simultaneous distros; local native and SSH isolation.
+- Run focused tests, then `pnpm typecheck` and `pnpm lint`.
+- Electron on native Windows: in a real Ubuntu WSL pane, emit the exact hostname OSC 7, sleep/wake twice, run `pwd` after each wake, and verify no `DaemonProtocolError`. Native UNC semantics are covered by deterministic unit tests; a screenshot of an arbitrary UNC string is not meaningful validation.
+
+## UI quality and review evidence
+
+There is no UI, layout, copy, or interaction change, so the Stage 5 visual-quality loop is skipped. Terminal content, CWD, and adjacent native/SSH behavior must remain unchanged.
+
+Electron validation still requires three evidence screenshots for user review:
+
+1. Before sleep: the WSL terminal shows the printed hostname/emission command and `pwd`.
+2. After the first wake: the same pane shows the same `pwd` and no wake error.
+3. After the second wake: the same pane again shows the same `pwd` and no wake error.
+
+## Lightweight engineering review
+
+- **Scope:** Parser context, immutable context propagation, history replay, and narrow legacy recovery. Runtime/IPC fields are necessary because parsing begins outside the daemon and may precede spawn completion.
+- **Architecture/data flow:** One resolved distro drives every parser for one PTY incarnation. The URI hostname remains metadata; it never selects path namespace or distro.
+- **Failure modes:** Covers missing/stale context, incremental replay, probe/create races, sticky restore, mismatched external history, split chunks, concurrent attaches, multi-window reuse, multi-distro isolation, PTY-ID reuse, and SSH/native boundaries.
+- **Tests:** Requires parser tables, propagation tests at every emulator construction site, all adapter restore branches, runtime early-byte/seed races, and the deterministic Windows Electron reproduction twice.
+- **Performance/blast radius:** One optional string per PTY/session and bounded conversion per OSC 7; no probes or new hot-path I/O. Non-WSL behavior is unchanged when the option is absent.
+- **UI/screenshots:** No design-review loop. Three Electron screenshots are required as functional evidence; native UNC stays an automated regression test.
+- **Residual risk:** Legacy checkpoints created from a non-machine hostname cannot be distinguished safely from a real UNC and therefore fall back to the requested CWD. A renamed/uninstalled distro still fails normally; this change does not guess a replacement.
+
+## Rollout
+
+1. Centralize distro resolution and WSL path conversion.
+2. Make the parser, daemon Session, and history replay distro-aware.
+3. Add allowlisted legacy recovery and keep spawn/cold-restore metadata consistent.
+4. Make runtime context available before output/seeding and reset it per incarnation.
+5. Add regressions, run static checks, then validate two Windows sleep/wake cycles with review screenshots.
diff --git a/src/main/daemon/daemon-create-or-attach-result.ts b/src/main/daemon/daemon-create-or-attach-result.ts
new file mode 100644
index 00000000000..6e587537b82
--- /dev/null
+++ b/src/main/daemon/daemon-create-or-attach-result.ts
@@ -0,0 +1,24 @@
+import type { TuiAgent } from '../../shared/types'
+import type { ShellReadyState, TerminalSnapshot } from './types'
+
+export type DaemonCreateOrAttachResult = {
+  isNew: boolean
+  snapshot: TerminalSnapshot | null
+  pid: number | null
+  shellState: ShellReadyState
+  historySeeded?: boolean
+  launchAgent?: TuiAgent
+  wslDistro?: string
+}
+
+export function getDaemonSessionResultMetadata(session: {
+  launchAgent: TuiAgent | null
+  historySeeded: boolean | undefined
+  wslDistro: string | null
+}): Pick<DaemonCreateOrAttachResult, 'launchAgent' | 'historySeeded' | 'wslDistro'> {
+  return {
+    ...(session.launchAgent ? { launchAgent: session.launchAgent } : {}),
+    ...(session.historySeeded !== undefined ? { historySeeded: session.historySeeded } : {}),
+    ...(session.wslDistro ? { wslDistro: session.wslDistro } : {})
+  }
+}
diff --git a/src/main/daemon/daemon-pty-adapter.test.ts b/src/main/daemon/daemon-pty-adapter.test.ts
index 42a7ada9735..a9f25d5865a 100644
--- a/src/main/daemon/daemon-pty-adapter.test.ts
+++ b/src/main/daemon/daemon-pty-adapter.test.ts
@@ -1,6 +1,6 @@
 /* oxlint-disable max-lines */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { tmpdir } from 'node:os'
+import { hostname, tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { mkdtempSync, mkdirSync, rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { DaemonClient } from './client'
@@ -1350,6 +1350,46 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       })
     })
 
+    it('repairs legacy hostname UNC cwd for WSL spawn and cold-restore metadata', async () => {
+      const platform = Object.getOwnPropertyDescriptor(process, 'platform')
+      Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' })
+      try {
+        const sessionId = 'wsl-legacy-cwd'
+        const sessionDir = join(historyDir, getHistorySessionDirName(sessionId))
+        mkdirSync(sessionDir, { recursive: true })
+        writeFileSync(
+          join(sessionDir, 'meta.json'),
+          JSON.stringify({
+            cwd: `\\\\${hostname()}\\home\\jin`,
+            cols: 80,
+            rows: 24,
+            startedAt: '2026-04-15T10:00:00Z',
+            endedAt: null,
+            exitCode: null
+          })
+        )
+        writeFileSync(join(sessionDir, 'scrollback.bin'), 'legacy WSL output\r\n')
+        historyAdapter = new DaemonPtyAdapter({ socketPath, tokenPath, historyPath: historyDir })
+
+        const result = await historyAdapter.spawn({
+          cols: 80,
+          rows: 24,
+          cwd: '\\\\wsl.localhost\\Ubuntu\\home\\jin\\repo',
+          terminalWindowsWslDistro: 'Debian',
+          sessionId
+        })
+
+        const repaired = '\\\\wsl.localhost\\Ubuntu\\home\\jin'
+        expect(lastSpawnOpts?.cwd).toBe(repaired)
+        expect(result.coldRestore?.cwd).toBe(repaired)
+        expect(result.wslDistro).toBe('Ubuntu')
+      } finally {
+        if (platform) {
+          Object.defineProperty(process, 'platform', platform)
+        }
+      }
+    })
+
     it('returns cold restore OSC link ranges from checkpoint history', async () => {
       const sessionId = 'cold-restore-osc-links'
       const sessionDir = join(historyDir, getHistorySessionDirName(sessionId))
diff --git a/src/main/daemon/daemon-pty-adapter.ts b/src/main/daemon/daemon-pty-adapter.ts
index 6437711729b..5d44eeb71d9 100644
--- a/src/main/daemon/daemon-pty-adapter.ts
+++ b/src/main/daemon/daemon-pty-adapter.ts
@@ -29,9 +29,12 @@ import type {
   PtySpawnResult
 } from '../providers/types'
 import { isShellProcess } from '../../shared/agent-detection'
+import { resolveWslSessionContext } from './wsl-session-context'
+import { normalizeWslColdRestoreCwd } from './wsl-cold-restore-cwd'
 import { recognizeAgentProcessFromCommandLine } from '../../shared/agent-process-recognition'
 import { shouldUseShellReadyStartupDelivery } from '../../shared/codex-startup-delivery'
 import type { TerminalOscLinkRange } from '../../shared/terminal-osc-link-ranges'
+import { resolveSafePtyDefaultCwd } from '../providers/pty-default-cwd'
 
 type ColdRestorePayload = {
   scrollback: string
@@ -104,6 +107,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
   private backgroundStreamListeners: ((payload: PtyBackgroundStreamEvent) => void)[] = []
   private removeEventListener: (() => void) | null = null
   private initialCwds = new Map<string, string>()
+  private wslDistrosBySessionId = new Map<string, string>()
   // Why: React re-renders and StrictMode double-mounts can call createOrAttach
   // for a session the user just killed. Without tombstones, the daemon would
   // create a fresh session — resurrecting a terminal the user explicitly closed.
@@ -196,6 +200,28 @@ export class DaemonPtyAdapter implements IPtyProvider {
 
   private async doSpawn(opts: PtySpawnOptions): Promise<PtySpawnResult> {
     const sessionId = opts.sessionId ?? mintPtySessionId(opts.worktreeId)
+    let wslDistro = resolveWslSessionContext({
+      cwd: opts.cwd,
+      sessionId,
+      shellOverride: opts.shellOverride,
+      terminalWindowsWslDistro: opts.terminalWindowsWslDistro
+    })?.distro
+    const detectColdRestore = (options?: { ignoreCleanEnd?: boolean }): ColdRestoreInfo | null => {
+      const restoreInfo =
+        this.historyReader?.detectColdRestore(sessionId, { ...options, wslDistro }) ?? null
+      if (!restoreInfo) {
+        return null
+      }
+      return {
+        ...restoreInfo,
+        cwd:
+          normalizeWslColdRestoreCwd({
+            recoveredCwd: restoreInfo.cwd,
+            requestedCwd: opts.cwd ?? resolveSafePtyDefaultCwd(),
+            wslDistro
+          }) ?? ''
+      }
+    }
 
     if (this.killedSessionTombstones.has(sessionId)) {
       throw new TerminalKilledError(sessionId)
@@ -228,7 +254,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       if ((await this.getAppliedSize(sessionId)) !== null) {
         restoreSkippedForLiveSession = true
       } else {
-        restoreInfo = this.historyReader.detectColdRestore(sessionId)
+        restoreInfo = detectColdRestore()
       }
     }
     let effectiveCwd = restoreInfo?.cwd ?? opts.cwd
@@ -275,6 +301,12 @@ export class DaemonPtyAdapter implements IPtyProvider {
 
     let scrollback = restoreInfo ? getRecoveredHistorySeed(restoreInfo) : null
     let result = await createOrAttach(scrollback)
+    wslDistro = result.wslDistro ?? wslDistro
+    if (wslDistro) {
+      this.wslDistrosBySessionId.set(sessionId, wslDistro)
+    } else if (result.isNew) {
+      this.wslDistrosBySessionId.delete(sessionId)
+    }
     const launchIdentity = (): { launchAgent?: NonNullable<typeof result.launchAgent> } =>
       result.launchAgent ? { launchAgent: result.launchAgent } : {}
 
@@ -305,6 +337,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
         pid,
         ...launchIdentity(),
         coldRestore: cachedRestore,
+        ...(wslDistro ? { wslDistro } : {}),
         ...(!result.isNew ? { isReattach: true } : {})
       }
     }
@@ -318,8 +351,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
     // must not null the restore here, or the openSession branch below would
     // delete the checkpoint instead of restoring it.
     if (result.isNew && restoreSkippedForLiveSession) {
-      restoreInfo =
-        this.historyReader?.detectColdRestore(sessionId, { ignoreCleanEnd: true }) ?? null
+      restoreInfo = detectColdRestore({ ignoreCleanEnd: true })
       scrollback = restoreInfo ? getRecoveredHistorySeed(restoreInfo) : null
       if (restoreInfo && scrollback) {
         // Why: the aliveness probe raced with session death, so the first
@@ -329,11 +361,17 @@ export class DaemonPtyAdapter implements IPtyProvider {
         effectiveCols = restoreInfo.cols
         effectiveRows = restoreInfo.rows
         result = await createOrAttach(scrollback)
+        wslDistro = result.wslDistro ?? wslDistro
+        if (wslDistro) {
+          this.wslDistrosBySessionId.set(sessionId, wslDistro)
+        } else if (result.isNew) {
+          this.wslDistrosBySessionId.delete(sessionId)
+        }
         pid = typeof result.pid === 'number' && result.pid > 0 ? result.pid : null
         this.initialCwds.set(sessionId, effectiveCwd)
       }
     } else if (!result.isNew && result.historySeeded === false) {
-      restoreInfo = this.historyReader?.detectColdRestore(sessionId) ?? null
+      restoreInfo = detectColdRestore()
       scrollback = restoreInfo ? getRecoveredHistorySeed(restoreInfo) : null
     }
 
@@ -371,6 +409,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
           pid,
           ...launchIdentity(),
           coldRestore,
+          ...(wslDistro ? { wslDistro } : {}),
           ...(providerSequence ? { providerSequence } : {}),
           ...(!result.isNew ? { isReattach: true } : {})
         }
@@ -379,6 +418,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
         id: sessionId,
         pid,
         ...launchIdentity(),
+        ...(wslDistro ? { wslDistro } : {}),
         ...(providerSequence ? { providerSequence } : {})
       }
     }
@@ -418,6 +458,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
         id: sessionId,
         pid,
         ...launchIdentity(),
+        ...(wslDistro ? { wslDistro } : {}),
         ...(providerSequence ? { providerSequence } : {}),
         ...(isReattach ? { isReattach: true } : {})
       }
@@ -437,6 +478,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       id: sessionId,
       pid,
       ...launchIdentity(),
+      ...(wslDistro ? { wslDistro } : {}),
       snapshot: snapshotPayload,
       snapshotCols: result.snapshot.cols,
       snapshotRows: result.snapshot.rows,
@@ -527,7 +569,19 @@ export class DaemonPtyAdapter implements IPtyProvider {
         await this.checkpointInFlight
       }
       await this.checkpointSessions([id], { final: true, teardown: true })
-      const restoreInfo = this.historyReader?.detectColdRestore(id) ?? null
+      const wslDistro = this.wslDistrosBySessionId.get(id)
+      const detected = this.historyReader?.detectColdRestore(id, { wslDistro }) ?? null
+      const restoreInfo = detected
+        ? {
+            ...detected,
+            cwd:
+              normalizeWslColdRestoreCwd({
+                recoveredCwd: detected.cwd,
+                requestedCwd: this.initialCwds.get(id) ?? resolveSafePtyDefaultCwd(),
+                wslDistro
+              }) ?? ''
+          }
+        : null
       const coldRestore = restoreInfo ? this.buildColdRestorePayload(restoreInfo) : null
       if (coldRestore) {
         this.coldRestoreCache.set(id, coldRestore)
@@ -552,6 +606,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.lastFullCheckpointAt.delete(id)
     this.stopCheckpointTimerIfIdle()
     this.initialCwds.delete(id)
+    this.wslDistrosBySessionId.delete(id)
     // Why: history removal is for the "user explicitly closed this terminal"
     // path. Sleep also calls shutdown but expects scrollback to survive — wake
     // re-spawns and the cold-restore reader needs the dir intact. Caller
@@ -903,6 +958,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.dirtySessionVersions.clear()
     this.lastFullCheckpointAt.clear()
     this.coldRestoreCache.clear()
+    this.wslDistrosBySessionId.clear()
     this.pausedProducerSessionIds.clear()
     this.producerResumesOwedOnReconnect.clear()
     this.removeEventListener?.()
@@ -941,6 +997,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.dirtySessionVersions.clear()
     this.lastFullCheckpointAt.clear()
     this.coldRestoreCache.clear()
+    this.wslDistrosBySessionId.clear()
     // Why: the detached daemon keeps these PTYs alive for warm reattach; a
     // pause left behind would block their shells for a failsafe window.
     for (const id of this.pausedProducerSessionIds) {
@@ -1386,6 +1443,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
             .catch((err) => console.warn('[history] closeSession failed:', event.sessionId, err))
         }
         this.initialCwds.delete(event.sessionId)
+        this.wslDistrosBySessionId.delete(event.sessionId)
         // oxlint-disable-next-line unicorn/no-useless-spread -- copy-safe: listeners may unsubscribe during iteration
         for (const listener of [...this.exitListeners]) {
           listener({ id: event.sessionId, code: event.payload.code })
diff --git a/src/main/daemon/daemon-server.ts b/src/main/daemon/daemon-server.ts
index c33e618bf02..2ee3aeba35b 100644
--- a/src/main/daemon/daemon-server.ts
+++ b/src/main/daemon/daemon-server.ts
@@ -467,6 +467,7 @@ export class DaemonServer {
           pid: result.pid,
           shellState: result.shellState,
           ...(result.launchAgent ? { launchAgent: result.launchAgent } : {}),
+          ...(result.wslDistro ? { wslDistro: result.wslDistro } : {}),
           ...(result.historySeeded !== undefined ? { historySeeded: result.historySeeded } : {})
         }
       }
diff --git a/src/main/daemon/headless-emulator.test.ts b/src/main/daemon/headless-emulator.test.ts
index b9630b8ff7e..37633f32334 100644
--- a/src/main/daemon/headless-emulator.test.ts
+++ b/src/main/daemon/headless-emulator.test.ts
@@ -263,6 +263,22 @@ describe('HeadlessEmulator', () => {
 
       expect(emulator.getSnapshot().cwd).toBe(expectedNativePath('/split-escape'))
     })
+
+    it('keeps split WSL OSC-7 parsing scoped to each emulator distro', async () => {
+      const ubuntu = new HeadlessEmulator({ cols: 80, rows: 24, wslDistro: 'Ubuntu' })
+      const debian = new HeadlessEmulator({ cols: 80, rows: 24, wslDistro: 'Debian' })
+      try {
+        await ubuntu.write('\x1b]7;file://machine/home/jin')
+        await debian.write('\x1b]7;file://machine/home/jin/repo\x07')
+        await ubuntu.write('/repo\x07')
+
+        expect(ubuntu.getSnapshot().cwd).toBe('\\\\wsl.localhost\\Ubuntu\\home\\jin\\repo')
+        expect(debian.getSnapshot().cwd).toBe('\\\\wsl.localhost\\Debian\\home\\jin\\repo')
+      } finally {
+        ubuntu.dispose()
+        debian.dispose()
+      }
+    })
   })
 
   describe('OSC title tracking', () => {
diff --git a/src/main/daemon/headless-emulator.ts b/src/main/daemon/headless-emulator.ts
index e7da2a4589e..767c9904a6c 100644
--- a/src/main/daemon/headless-emulator.ts
+++ b/src/main/daemon/headless-emulator.ts
@@ -35,6 +35,7 @@ export type HeadlessEmulatorOptions = {
   onQueryReply?: (reply: string) => void
   pathFlavor?: 'posix' | 'win32'
   remotePosixFileUriAuthority?: boolean
+  wslDistro?: string
 }
 
 export type HeadlessEmulatorWriteOptions = {
@@ -93,7 +94,8 @@ export class HeadlessEmulator {
     this.remotePosixFileUriAuthority = opts.remotePosixFileUriAuthority === true
     this.oscText = new TerminalOscCwdTitleScanner({
       pathFlavor: this.pathFlavor,
-      remotePosixAuthority: this.remotePosixFileUriAuthority
+      remotePosixAuthority: this.remotePosixFileUriAuthority,
+      wslDistro: opts.wslDistro
     })
     this.terminal = new Terminal({
       cols: opts.cols,
diff --git a/src/main/daemon/history-reader.test.ts b/src/main/daemon/history-reader.test.ts
index 50caff6d486..4330b0e2c9e 100644
--- a/src/main/daemon/history-reader.test.ts
+++ b/src/main/daemon/history-reader.test.ts
@@ -5,6 +5,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
 import { HistoryReader } from './history-reader'
 import { getHistorySessionDirName } from './history-paths'
 import type { SessionMeta } from './history-manager'
+import { encodeLogBatch, encodeLogHeader } from './terminal-history-log'
 
 function createTestDir(): string {
   return mkdtempSync(join(tmpdir(), 'history-reader-test-'))
@@ -164,6 +165,24 @@ describe('HistoryReader', () => {
     })
   })
 
+  it('replays incremental hostname OSC-7 with the same WSL context', () => {
+    writeSessionWithCheckpoint(dir, 'wsl-log', makeMeta(), makeCheckpoint({ generation: 7 }))
+    const sessionDir = join(dir, getHistorySessionDirName('wsl-log'))
+    writeFileSync(
+      join(sessionDir, 'output.log'),
+      Buffer.concat([
+        encodeLogHeader(7),
+        encodeLogBatch(1, [
+          { kind: 'output', data: '\x1b]7;file://DESKTOP-ORCA/home/user/project\x07' }
+        ])
+      ])
+    )
+
+    const info = reader.detectColdRestore('wsl-log', { wslDistro: 'Ubuntu' })
+
+    expect(info?.cwd).toBe('\\\\wsl.localhost\\Ubuntu\\home\\user\\project')
+  })
+
   describe('detectColdRestore — scrollback.bin fallback (backward compatibility)', () => {
     it('restores from scrollback.bin when checkpoint.json is absent', () => {
       writeSessionWithScrollback(dir, 'old-sess', makeMeta(), 'old format data\r\n')
diff --git a/src/main/daemon/history-reader.ts b/src/main/daemon/history-reader.ts
index 8d31e3c638d..e219d58cfc4 100644
--- a/src/main/daemon/history-reader.ts
+++ b/src/main/daemon/history-reader.ts
@@ -39,7 +39,7 @@ export class HistoryReader {
 
   detectColdRestore(
     sessionId: string,
-    opts?: { ignoreCleanEnd?: boolean }
+    opts?: { ignoreCleanEnd?: boolean; wslDistro?: string }
   ): ColdRestoreInfo | null {
     const meta = this.readMeta(sessionId)
     if (!meta) {
@@ -69,7 +69,7 @@ export class HistoryReader {
     // byte-exact output up to ~5s before the crash (up to the full-snapshot
     // cooldown, ~45s, for a streaming session mid-deferral), while the
     // checkpoint can be a full log-cap (~5MB of output) stale.
-    const logRestore = this.restoreFromIncrementalLog(sessionDir, meta, checkpoint)
+    const logRestore = this.restoreFromIncrementalLog(sessionDir, meta, checkpoint, opts?.wslDistro)
     if (logRestore) {
       return logRestore
     }
@@ -122,7 +122,8 @@ export class HistoryReader {
   private restoreFromIncrementalLog(
     sessionDir: string,
     meta: SessionMeta,
-    checkpoint: TerminalCheckpointFile | null
+    checkpoint: TerminalCheckpointFile | null,
+    wslDistro?: string
   ): ColdRestoreInfo | null {
     let logBuffer: Buffer
     try {
@@ -148,7 +149,8 @@ export class HistoryReader {
 
     const emulator = new HeadlessEmulator({
       cols: checkpoint?.cols ?? meta.cols,
-      rows: checkpoint?.rows ?? meta.rows
+      rows: checkpoint?.rows ?? meta.rows,
+      wslDistro
     })
     try {
       if (checkpoint) {
diff --git a/src/main/daemon/osc7-file-uri.test.ts b/src/main/daemon/osc7-file-uri.test.ts
index faa84879c55..4aa20a0dbfc 100644
--- a/src/main/daemon/osc7-file-uri.test.ts
+++ b/src/main/daemon/osc7-file-uri.test.ts
@@ -3,7 +3,9 @@ import { parseFileUriPath, parseFileUriPathParts } from './osc7-file-uri'
 
 describe('parseFileUriPath', () => {
   it('accepts host-qualified POSIX file URI authorities as plain paths', () => {
-    expect(parseFileUriPath('file://remote-host/tmp/result.json')).toBe('/tmp/result.json')
+    expect(parseFileUriPath('file://remote-host/tmp/result.json', { pathFlavor: 'posix' })).toBe(
+      '/tmp/result.json'
+    )
   })
 
   it('accepts empty and localhost POSIX file URI authorities', () => {
@@ -51,4 +53,20 @@ describe('parseFileUriPath', () => {
       }
     }
   })
+
+  it.each(['machine-name', 'localhost', ''])(
+    'uses the resolved WSL distro for authority %s',
+    (authority) => {
+      const uri = authority ? `file://${authority}/home/me/my%20repo` : 'file:///home/me/my%20repo'
+      expect(parseFileUriPathParts(uri, { pathFlavor: 'win32', wslDistro: 'Ubuntu' })).toEqual({
+        path: '\\\\wsl.localhost\\Ubuntu\\home\\me\\my repo',
+        hostname: authority === 'localhost' ? '' : authority
+      })
+    }
+  )
+
+  it('maps lowercase drvfs paths and rejects malformed percent encoding in WSL context', () => {
+    expect(parseFileUriPath('file://host/mnt/c/work', { wslDistro: 'Ubuntu' })).toBe('C:\\work')
+    expect(parseFileUriPath('file://host/home/%ZZ', { wslDistro: 'Ubuntu' })).toBeNull()
+  })
 })
diff --git a/src/main/daemon/osc7-file-uri.ts b/src/main/daemon/osc7-file-uri.ts
index f931174ee03..ce7b8493462 100644
--- a/src/main/daemon/osc7-file-uri.ts
+++ b/src/main/daemon/osc7-file-uri.ts
@@ -1,3 +1,5 @@
+import { toWindowsWslPath } from '../../shared/wsl-paths'
+
 export type ParsedFileUriPath = {
   path: string
   hostname: string
@@ -6,6 +8,7 @@ export type ParsedFileUriPath = {
 export type ParseFileUriPathOptions = {
   pathFlavor?: 'posix' | 'win32'
   remotePosixAuthority?: boolean
+  wslDistro?: string
 }
 
 export function parseFileUriPath(
@@ -27,6 +30,9 @@ export function parseFileUriPathParts(
 
     const decodedPath = decodeURIComponent(url.pathname)
     const hostname = url.hostname.toLowerCase()
+    if (options.wslDistro) {
+      return { path: toWindowsWslPath(decodedPath, options.wslDistro), hostname }
+    }
     const pathFlavor = options.pathFlavor ?? (process.platform === 'win32' ? 'win32' : 'posix')
     if (pathFlavor !== 'win32') {
       return { path: decodedPath, hostname }
diff --git a/src/main/daemon/pty-subprocess.ts b/src/main/daemon/pty-subprocess.ts
index 2ab88945689..60a8af8ac70 100644
--- a/src/main/daemon/pty-subprocess.ts
+++ b/src/main/daemon/pty-subprocess.ts
@@ -39,7 +39,7 @@ import {
   mergeGitConfigEnvProtocol
 } from '../../shared/git-credential-prompt-env'
 import { TERMINAL_GIT_CREDENTIAL_GUARD_POLICY_ENV } from '../../shared/terminal-git-credential-guard'
-import { getWslContextFromSessionId } from './wsl-session-context'
+import { resolveWslSessionContext } from './wsl-session-context'
 import { addOrcaWslInteropEnv } from '../pty/wsl-orca-env'
 import {
   POWERLEVEL10K_WIZARD_DISABLE_ENV,
@@ -177,16 +177,6 @@ function removeInheritedDevAgentHookEndpoint(
   }
 }
 
-/**
- * Resolves a WSL launch context from a user-selected distro name.
- */
-function getWslContextFromPreferredDistro(
-  distro: string | null | undefined
-): { distro: string } | undefined {
-  const trimmed = distro?.trim()
-  return trimmed ? { distro: trimmed } : undefined
-}
-
 /**
  * Strips Electron's internal run-as-node flag from user shell environments.
  */
@@ -605,18 +595,11 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
   // setting, relayed by main) takes priority over env.COMSPEC — otherwise
   // Windows always resolves to cmd.exe (COMSPEC) or PowerShell by fallback,
   // no matter which shell the user actually picked.
-  const cwdWslInfo = process.platform === 'win32' ? parseWslPath(opts.cwd ?? '') : null
-  const sessionWslContext =
-    process.platform === 'win32' ? getWslContextFromSessionId(opts.sessionId) : undefined
-  const preferredWslContext =
-    process.platform === 'win32'
-      ? getWslContextFromPreferredDistro(opts.terminalWindowsWslDistro)
-      : undefined
+  const resolvedWslContext = resolveWslSessionContext(opts)
   // Why: WSL worktree cwd is the repo's execution environment. Older persisted
   // tabs can carry a PowerShell/cmd shellOverride; ignore it so reconnects and
   // daemon-backed terminals enter the WSL distro just like LocalPtyProvider.
-  let shellPath =
-    cwdWslInfo || sessionWslContext ? 'wsl.exe' : opts.shellOverride || resolvePtyShellPath(env)
+  let shellPath = resolvedWslContext ? 'wsl.exe' : opts.shellOverride || resolvePtyShellPath(env)
   let shellArgs: string[]
   let startupCommandDeliveredInShellArgs = false
   let windowsFallbackAttempts: WindowsShellSpawnAttempt[] = []
@@ -672,7 +655,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
       shellPath,
       cwd: spawnCwd,
       defaultCwd: getDefaultCwd(),
-      wslContext: sessionWslContext ?? preferredWslContext,
+      wslContext: resolvedWslContext,
       startupCommand: opts.command
     })
     const primaryAttempt = windowsFallbackAttempts[0]
@@ -687,7 +670,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
         shellPath,
         spawnCwd,
         getDefaultCwd(),
-        sessionWslContext ?? preferredWslContext,
+        resolvedWslContext,
         opts.command
       )
       shellArgs = resolved.shellArgs
@@ -703,8 +686,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
     const codexHomeWslInfo = env.CODEX_HOME ? parseWslPath(env.CODEX_HOME) : null
     if (pathWin32.basename(shellPath).toLowerCase() === 'wsl.exe') {
       if (codexHomeWslInfo) {
-        const launchWslDistro =
-          cwdWslInfo?.distro ?? sessionWslContext?.distro ?? preferredWslContext?.distro
+        const launchWslDistro = resolvedWslContext?.distro
         if (launchWslDistro && launchWslDistro !== codexHomeWslInfo.distro) {
           delete env.CODEX_HOME
           delete env.ORCA_CODEX_HOME
diff --git a/src/main/daemon/session.test.ts b/src/main/daemon/session.test.ts
index c022604ceb2..3b8f068868c 100644
--- a/src/main/daemon/session.test.ts
+++ b/src/main/daemon/session.test.ts
@@ -106,12 +106,14 @@ describe('Session', () => {
     cols?: number
     rows?: number
     launchAgent?: TuiAgent
+    wslDistro?: string
   }): Session {
     session = new Session({
       sessionId: 'test-session',
       cols: opts?.cols ?? 80,
       rows: opts?.rows ?? 24,
       ...(opts?.launchAgent ? { launchAgent: opts.launchAgent } : {}),
+      wslDistro: opts?.wslDistro,
       subprocess,
       shellReadySupported: opts?.shellReadySupported ?? false,
       ...(opts?.shellReadyTimeoutMs !== undefined
@@ -665,6 +667,13 @@ describe('Session', () => {
   })
 
   describe('snapshot', () => {
+    it('parses live OSC-7 output in the session WSL distro', () => {
+      createSession({ wslDistro: 'Ubuntu' })
+
+      subprocess.simulateData('\x1b]7;file://DESKTOP-ORCA/home/jin/repo\x07')
+
+      expect(session.getCwd()).toBe('\\\\wsl.localhost\\Ubuntu\\home\\jin\\repo')
+    })
     it('returns a terminal snapshot', async () => {
       createSession()
       subprocess.simulateData('$ hello\r\n')
diff --git a/src/main/daemon/session.ts b/src/main/daemon/session.ts
index a40cce8480a..7ca52cf0c2a 100644
--- a/src/main/daemon/session.ts
+++ b/src/main/daemon/session.ts
@@ -90,6 +90,7 @@ export type SessionOptions = {
   shellReadyTimeoutMs?: number
   historySeed?: string
   scrollback?: number
+  wslDistro?: string
   // Why: fired once the session reaches a terminal state (natural exit or
   // kill-timeout force-dispose) so the owner (TerminalHost) can reap it —
   // dispose the headless emulator and drop it from its session map. Without a
@@ -108,6 +109,7 @@ export class Session {
   readonly sessionId: string
   readonly terminalHandle: string | null
   readonly launchAgent: TuiAgent | null
+  readonly wslDistro: string | null
   private _state: SessionState = 'running'
   private _shellState: ShellReadyState
   private _exitCode: number | null = null
@@ -138,13 +140,15 @@ export class Session {
     this.sessionId = opts.sessionId
     this.terminalHandle = opts.terminalHandle ?? null
     this.launchAgent = opts.launchAgent ?? null
+    this.wslDistro = opts.wslDistro ?? null
     this.subprocess = opts.subprocess
     this.onSessionExit = opts.onExit
     const size = normalizePtySize(opts.cols, opts.rows)
     this.emulator = new HeadlessEmulator({
       cols: size.cols,
       rows: size.rows,
-      scrollback: opts.scrollback
+      scrollback: opts.scrollback,
+      wslDistro: opts.wslDistro
       // No onData wiring: the daemon-side emulator must never reply to
       // terminal query sequences. The renderer's xterm is the authoritative
       // responder; any daemon reply races ahead via in-process parsing and
diff --git a/src/main/daemon/terminal-host-create-contract.ts b/src/main/daemon/terminal-host-create-contract.ts
index a60570ac5fe..5c4ad2d9a69 100644
--- a/src/main/daemon/terminal-host-create-contract.ts
+++ b/src/main/daemon/terminal-host-create-contract.ts
@@ -29,5 +29,6 @@ export type CreateOrAttachResult = {
   shellState: ShellReadyState
   historySeeded?: boolean
   launchAgent?: TuiAgent
+  wslDistro?: string
   attachToken: symbol
 }
diff --git a/src/main/daemon/terminal-host-wsl-context.test.ts b/src/main/daemon/terminal-host-wsl-context.test.ts
new file mode 100644
index 00000000000..e9fccb7b737
--- /dev/null
+++ b/src/main/daemon/terminal-host-wsl-context.test.ts
@@ -0,0 +1,94 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { TerminalHost } from './terminal-host'
+import type { SubprocessHandle } from './session'
+import { resolveWslSessionContext } from './wsl-session-context'
+
+function createSubprocess(): SubprocessHandle {
+  let onExit: ((code: number) => void) | undefined
+  return {
+    pid: 123,
+    getForegroundProcess: () => null,
+    write: vi.fn(),
+    resize: vi.fn(),
+    kill: vi.fn(() => onExit?.(0)),
+    forceKill: vi.fn(() => onExit?.(137)),
+    signal: vi.fn(),
+    onData: vi.fn(),
+    onExit: vi.fn((callback: (code: number) => void) => {
+      onExit = callback
+    }),
+    dispose: vi.fn()
+  }
+}
+
+describe('TerminalHost WSL context', () => {
+  let host: TerminalHost | undefined
+
+  afterEach(async () => {
+    await host?.dispose()
+  })
+
+  it('returns the first creator context on conflicting later attaches', async () => {
+    const spawnSubprocess = vi.fn(() => createSubprocess())
+    host = new TerminalHost({ spawnSubprocess })
+    const platform = Object.getOwnPropertyDescriptor(process, 'platform')
+    Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' })
+    try {
+      const created = await host.createOrAttach({
+        sessionId: 'session-wsl',
+        cols: 80,
+        rows: 24,
+        cwd: '\\\\wsl.localhost\\Ubuntu\\home\\jin',
+        terminalWindowsWslDistro: 'Debian',
+        streamClient: { onData: vi.fn(), onExit: vi.fn() }
+      })
+      const attached = await host.createOrAttach({
+        sessionId: 'session-wsl',
+        cols: 80,
+        rows: 24,
+        terminalWindowsWslDistro: 'Debian',
+        streamClient: { onData: vi.fn(), onExit: vi.fn() }
+      })
+
+      expect(created.wslDistro).toBe('Ubuntu')
+      expect(attached.wslDistro).toBe('Ubuntu')
+      expect(spawnSubprocess).toHaveBeenCalledOnce()
+    } finally {
+      if (platform) {
+        Object.defineProperty(process, 'platform', platform)
+      }
+    }
+  })
+
+  it('uses a remembered distro only when the selected shell is WSL', () => {
+    const platform = Object.getOwnPropertyDescriptor(process, 'platform')
+    Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' })
+    try {
+      expect(
+        resolveWslSessionContext({
+          cwd: 'C:\\Users\\jin\\repo',
+          shellOverride: 'powershell.exe',
+          terminalWindowsWslDistro: 'Ubuntu'
+        })
+      ).toBeUndefined()
+      expect(
+        resolveWslSessionContext({
+          cwd: '\\\\server\\share\\repo',
+          shellOverride: 'powershell.exe',
+          terminalWindowsWslDistro: 'Ubuntu'
+        })
+      ).toBeUndefined()
+      expect(
+        resolveWslSessionContext({
+          cwd: 'C:\\Users\\jin\\repo',
+          shellOverride: 'wsl.exe',
+          terminalWindowsWslDistro: ' Ubuntu '
+        })
+      ).toEqual({ distro: 'Ubuntu', treatPosixCwdAsWsl: true })
+    } finally {
+      if (platform) {
+        Object.defineProperty(process, 'platform', platform)
+      }
+    }
+  })
+})
diff --git a/src/main/daemon/terminal-host.ts b/src/main/daemon/terminal-host.ts
index 7bf06f57012..ba15c6ed814 100644
--- a/src/main/daemon/terminal-host.ts
+++ b/src/main/daemon/terminal-host.ts
@@ -13,6 +13,8 @@ import {
 import type { CreateOrAttachOptions, CreateOrAttachResult } from './terminal-host-create-contract'
 import { shutdownTerminalHostSessions } from './terminal-host-session-shutdown'
 import { TerminalSessionTeardown } from './terminal-session-teardown'
+import { resolveWslSessionContext } from './wsl-session-context'
+import { getDaemonSessionResultMetadata } from './daemon-create-or-attach-result'
 
 export type { CreateOrAttachOptions, CreateOrAttachResult } from './terminal-host-create-contract'
 
@@ -89,8 +91,7 @@ export class TerminalHost {
         snapshot,
         pid: existing.pid,
         shellState: existing.shellState,
-        ...(existing.launchAgent ? { launchAgent: existing.launchAgent } : {}),
-        ...(existing.historySeeded !== undefined ? { historySeeded: existing.historySeeded } : {}),
+        ...getDaemonSessionResultMetadata(existing),
         attachToken: token
       }
     }
@@ -110,6 +111,7 @@ export class TerminalHost {
     // Clear tombstone if re-creating a killed session
     this.killedTombstones.delete(opts.sessionId)
     const size = normalizePtySize(opts.cols, opts.rows)
+    const wslDistro = resolveWslSessionContext(opts)?.distro
 
     const subprocess = this.spawnSubprocess({
       sessionId: opts.sessionId,
@@ -145,6 +147,7 @@ export class TerminalHost {
       subprocess,
       shellReadySupported,
       historySeed: opts.historySeed,
+      wslDistro,
       // Why: reap the dead session (dispose emulator + drop from the map) the
       // moment its subprocess exits, instead of retaining it for the daemon's
       // lifetime. Nothing reads a dead session's emulator (getSnapshot/
@@ -185,8 +188,7 @@ export class TerminalHost {
       snapshot: null,
       pid: subprocess.pid,
       shellState: session.shellState,
-      ...(session.launchAgent ? { launchAgent: session.launchAgent } : {}),
-      ...(session.historySeeded !== undefined ? { historySeeded: session.historySeeded } : {}),
+      ...getDaemonSessionResultMetadata(session),
       attachToken: token
     }
   }
diff --git a/src/main/daemon/terminal-osc-cwd-title-scanner.ts b/src/main/daemon/terminal-osc-cwd-title-scanner.ts
index f3736d7c009..91f592e3796 100644
--- a/src/main/daemon/terminal-osc-cwd-title-scanner.ts
+++ b/src/main/daemon/terminal-osc-cwd-title-scanner.ts
@@ -11,6 +11,7 @@ const OSC_SCAN_TAIL_LIMIT = 4096
 export type TerminalOscCwdTitleScannerOptions = {
   pathFlavor?: 'posix' | 'win32'
   remotePosixAuthority?: boolean
+  wslDistro?: string
 }
 
 export class TerminalOscCwdTitleScanner {
@@ -39,7 +40,8 @@ export class TerminalOscCwdTitleScanner {
     scanOsc7Uris(input, (uri) => {
       const parsed = parseFileUriPath(uri, {
         pathFlavor: this.parseOptions.pathFlavor,
-        remotePosixAuthority: this.parseOptions.remotePosixAuthority
+        remotePosixAuthority: this.parseOptions.remotePosixAuthority,
+        wslDistro: this.parseOptions.wslDistro
       })
       if (parsed) {
         this.cwd = parsed
diff --git a/src/main/daemon/types.ts b/src/main/daemon/types.ts
index 6f48e1ccdbf..63c5edc577b 100644
--- a/src/main/daemon/types.ts
+++ b/src/main/daemon/types.ts
@@ -359,14 +359,7 @@ export type RpcResponseError = {
 
 export type RpcResponse<T = unknown> = RpcResponseOk<T> | RpcResponseError
 
-export type CreateOrAttachResult = {
-  isNew: boolean
-  snapshot: TerminalSnapshot | null
-  pid: number | null
-  shellState: ShellReadyState
-  historySeeded?: boolean
-  launchAgent?: TuiAgent
-}
+export type { DaemonCreateOrAttachResult as CreateOrAttachResult } from './daemon-create-or-attach-result'
 export type GetSnapshotResult = {
   snapshot: TerminalSnapshot | null
 }
diff --git a/src/main/daemon/wsl-cold-restore-cwd.test.ts b/src/main/daemon/wsl-cold-restore-cwd.test.ts
new file mode 100644
index 00000000000..d9c5cf54770
--- /dev/null
+++ b/src/main/daemon/wsl-cold-restore-cwd.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest'
+import { normalizeWslColdRestoreCwd } from './wsl-cold-restore-cwd'
+
+const base = {
+  platform: 'win32' as const,
+  hostname: 'DESKTOP-ORCA',
+  requestedCwd: '\\\\wsl.localhost\\Ubuntu\\home\\jin\\repo',
+  wslDistro: 'Ubuntu'
+}
+
+describe('normalizeWslColdRestoreCwd', () => {
+  it.each([
+    ['C:\\work', 'C:\\work'],
+    ['\\\\wsl.localhost\\ubuntu\\home\\jin', '\\\\wsl.localhost\\ubuntu\\home\\jin'],
+    ['/home/jin', '\\\\wsl.localhost\\Ubuntu\\home\\jin'],
+    ['\\\\desktop-orca\\home\\jin', '\\\\wsl.localhost\\Ubuntu\\home\\jin'],
+    ['\\\\DESKTOP-ORCA\\mnt\\c\\work', 'C:\\work']
+  ])('allows or repairs %s', (recoveredCwd, expected) => {
+    expect(normalizeWslColdRestoreCwd({ ...base, recoveredCwd })).toBe(expected)
+  })
+
+  it.each([
+    '\\\\wsl.localhost\\Debian\\home\\jin',
+    '\\\\server\\share\\repo',
+    '//server/share/repo',
+    'relative/path',
+    '\\\\other-host\\home\\jin'
+  ])('falls back instead of guessing for %s', (recoveredCwd) => {
+    expect(normalizeWslColdRestoreCwd({ ...base, recoveredCwd })).toBe(base.requestedCwd)
+  })
+
+  it('leaves native and missing-context restores unchanged', () => {
+    expect(
+      normalizeWslColdRestoreCwd({ ...base, platform: 'linux', recoveredCwd: '/home/jin' })
+    ).toBe('/home/jin')
+    expect(
+      normalizeWslColdRestoreCwd({ ...base, wslDistro: undefined, recoveredCwd: '\\\\server\\x' })
+    ).toBe('\\\\server\\x')
+  })
+})
diff --git a/src/main/daemon/wsl-cold-restore-cwd.ts b/src/main/daemon/wsl-cold-restore-cwd.ts
new file mode 100644
index 00000000000..b3f921106dc
--- /dev/null
+++ b/src/main/daemon/wsl-cold-restore-cwd.ts
@@ -0,0 +1,37 @@
+import { hostname as getHostname } from 'node:os'
+import { parseWslUncPath, toWindowsWslPath } from '../../shared/wsl-paths'
+
+export function normalizeWslColdRestoreCwd(args: {
+  recoveredCwd: string
+  requestedCwd?: string
+  wslDistro?: string
+  platform?: NodeJS.Platform
+  hostname?: string
+}): string | undefined {
+  if ((args.platform ?? process.platform) !== 'win32' || !args.wslDistro) {
+    return args.recoveredCwd
+  }
+
+  if (/^[A-Za-z]:[\\/]/.test(args.recoveredCwd)) {
+    return args.recoveredCwd
+  }
+
+  const wslPath = parseWslUncPath(args.recoveredCwd)
+  if (wslPath) {
+    return wslPath.distro.toLowerCase() === args.wslDistro.toLowerCase()
+      ? args.recoveredCwd
+      : args.requestedCwd
+  }
+
+  if (/^\/(?!\/)/.test(args.recoveredCwd)) {
+    return toWindowsWslPath(args.recoveredCwd, args.wslDistro)
+  }
+
+  const uncMatch = args.recoveredCwd.match(/^[\\/]{2}([^\\/]+)[\\/]([^\\/]+)([\\/].*)?$/)
+  if (uncMatch?.[1].toLowerCase() === (args.hostname ?? getHostname()).toLowerCase()) {
+    const linuxPath = `/${uncMatch[2]}${(uncMatch[3] ?? '').replace(/\\/g, '/')}`
+    return toWindowsWslPath(linuxPath, args.wslDistro)
+  }
+
+  return args.requestedCwd
+}
diff --git a/src/main/daemon/wsl-session-context.ts b/src/main/daemon/wsl-session-context.ts
index f6d568a7042..582e8a66a05 100644
--- a/src/main/daemon/wsl-session-context.ts
+++ b/src/main/daemon/wsl-session-context.ts
@@ -1,6 +1,8 @@
 import { splitWorktreeIdForFilesystem } from '../../shared/worktree-id'
+import { isWslShellName } from '../../shared/local-windows-terminal-runtime'
 import { parseWslPath } from '../wsl'
 import { parsePtySessionId } from './pty-session-id'
+import { parseWslUncPath } from '../../shared/wsl-paths'
 
 export type WslSessionContext = {
   distro: string
@@ -15,3 +17,31 @@ export function getWslContextFromSessionId(sessionId: string): WslSessionContext
   const wslInfo = worktreePath ? parseWslPath(worktreePath) : null
   return wslInfo ? { distro: wslInfo.distro, treatPosixCwdAsWsl: true } : undefined
 }
+
+export function getWslContextFromPreferredDistro(
+  distro: string | null | undefined
+): WslSessionContext | undefined {
+  const trimmed = distro?.trim()
+  return trimmed ? { distro: trimmed, treatPosixCwdAsWsl: true } : undefined
+}
+
+export function resolveWslSessionContext(args: {
+  cwd?: string
+  sessionId?: string
+  shellOverride?: string
+  terminalWindowsWslDistro?: string | null
+}): WslSessionContext | undefined {
+  if (process.platform !== 'win32') {
+    return undefined
+  }
+  const cwdDistro = args.cwd ? parseWslUncPath(args.cwd)?.distro : undefined
+  if (cwdDistro) {
+    return { distro: cwdDistro, treatPosixCwdAsWsl: true }
+  }
+  return (
+    (args.sessionId ? getWslContextFromSessionId(args.sessionId) : undefined) ??
+    (isWslShellName(args.shellOverride)
+      ? getWslContextFromPreferredDistro(args.terminalWindowsWslDistro)
+      : undefined)
+  )
+}
diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index b3a41ef10eb..a8dd387dffe 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -2301,13 +2301,24 @@ describe('registerPtyHandlers', () => {
           listProcesses: vi.fn(async () => []),
           getForegroundProcess: vi.fn(async () => null)
         } as never)
+        const runtime = {
+          setPtyController: vi.fn(),
+          createPreAllocatedTerminalHandle: vi.fn(() => null),
+          preAllocateHandleForPty: vi.fn(),
+          preparePtyExecutionContext: vi.fn().mockReturnValue(true)
+        }
         handlers.clear()
-        registerPtyHandlers(mainWindow as never)
+        registerPtyHandlers(mainWindow as never, runtime as never)
         await expect(
           handlers.get('pty:spawn')!(null, { cols: 80, rows: 24, env: {} })
         ).rejects.toThrow(/spawn boom/)
         expect(openCodeClearPtyMock).toHaveBeenCalled()
         expect(piClearPtyMock).toHaveBeenCalled()
+        expect(runtime.preparePtyExecutionContext).toHaveBeenLastCalledWith(
+          expect.any(String),
+          null,
+          { resetIncarnation: true }
+        )
       })
 
       it('does NOT sweep per-PTY state on provider.spawn failure for CALLER-supplied sessionId', async () => {
@@ -2329,8 +2340,14 @@ describe('registerPtyHandlers', () => {
           listProcesses: vi.fn(async () => []),
           getForegroundProcess: vi.fn(async () => null)
         } as never)
+        const runtime = {
+          setPtyController: vi.fn(),
+          createPreAllocatedTerminalHandle: vi.fn(() => null),
+          preAllocateHandleForPty: vi.fn(),
+          preparePtyExecutionContext: vi.fn().mockReturnValue(true)
+        }
         handlers.clear()
-        registerPtyHandlers(mainWindow as never)
+        registerPtyHandlers(mainWindow as never, runtime as never)
         await expect(
           handlers.get('pty:spawn')!(null, {
             cols: 80,
@@ -2341,6 +2358,11 @@ describe('registerPtyHandlers', () => {
         ).rejects.toThrow(/spawn boom/)
         expect(openCodeClearPtyMock).not.toHaveBeenCalled()
         expect(piClearPtyMock).not.toHaveBeenCalled()
+        expect(runtime.preparePtyExecutionContext).toHaveBeenLastCalledWith(
+          'caller-owned-session',
+          null,
+          { resetIncarnation: true }
+        )
       })
 
       it('does NOT inject host-local env on SSH spawns (connectionId set)', async () => {
diff --git a/src/main/ipc/pty.ts b/src/main/ipc/pty.ts
index 03a99cb2946..0c1803d4555 100644
--- a/src/main/ipc/pty.ts
+++ b/src/main/ipc/pty.ts
@@ -66,6 +66,7 @@ import {
 import { parseAppSshPtyId, toAppSshPtyId, toRelaySshPtyId } from '../providers/ssh-pty-id'
 import { createPtySpawnTiming } from './pty-spawn-timing'
 import { mintPtySessionId, isSafePtySessionId } from '../daemon/pty-session-id'
+import { resolveWslSessionContext } from '../daemon/wsl-session-context'
 import { addNodePtyRecoveryHint } from '../daemon/node-pty-error-hints'
 import { recordDaemonStreamBacklogEvent } from '../daemon/daemon-stream-backlog-probe'
 import type { ClaudeRuntimeAuthPreparation } from '../claude-accounts/runtime-auth-service'
@@ -3044,6 +3045,14 @@ export function registerPtyHandlers(
       const effectiveSessionAppId =
         sessionId !== undefined ? getAppPtyId(args.connectionId, sessionId) : undefined
       const isMintedSessionId = requestedSessionId === undefined && isDaemonHostSpawn
+      const expectedWslDistro = !args.connectionId
+        ? (resolveWslSessionContext({
+            cwd,
+            sessionId,
+            shellOverride: terminalRuntimeOptions.shellOverride,
+            terminalWindowsWslDistro: terminalRuntimeOptions.terminalWindowsWslDistro
+          })?.distro ?? null)
+        : null
       const shouldPersistHostSessionBinding = args.persistHostSessionBinding === true
       let hostSessionBinding: {
         store: NonNullable<typeof store>
@@ -3199,12 +3208,20 @@ export function registerPtyHandlers(
         ? reservePaneSpawn(materializedPaneKey)
         : null
       let result: PtySpawnResult
+      let preparedProvisionalExecutionContext = false
       try {
         try {
           if (args.preAllocatedHandle) {
             trustedTerminalHandleEnv.add(args.preAllocatedHandle)
           }
           const expectedPtyId = effectiveSessionAppId ?? sessionId
+          if (isDaemonHostSpawn && expectedPtyId) {
+            preparedProvisionalExecutionContext =
+              runtime?.preparePtyExecutionContext?.(expectedPtyId, expectedWslDistro, {
+                resetIncarnation: isMintedSessionId,
+                preserveExisting: !isMintedSessionId
+              }) ?? false
+          }
           const sequenceBeforeProviderSpawn = expectedPtyId
             ? (runtime?.getPtyOutputSequence?.(expectedPtyId) ?? 0)
             : 0
@@ -3216,7 +3233,16 @@ export function registerPtyHandlers(
               sequenceBeforeProviderSpawn
             )
           }
+          runtime?.preparePtyExecutionContext?.(
+            result.id,
+            args.connectionId ? null : (result.wslDistro ?? expectedWslDistro)
+          )
         } catch (err) {
+          if ((isMintedSessionId || preparedProvisionalExecutionContext) && effectiveSessionAppId) {
+            runtime?.preparePtyExecutionContext?.(effectiveSessionAppId, null, {
+              resetIncarnation: true
+            })
+          }
           const rawMessage = err instanceof Error ? err.message : String(err)
           const spawnError = normalizeNodePtySpawnError(err)
           const isIdentityMismatch =
@@ -3865,6 +3891,14 @@ export function registerPtyHandlers(
         effectiveSessionId !== undefined
           ? getRelayPtyId(args.connectionId, effectiveSessionId)
           : undefined
+      const expectedWslDistro = !args.connectionId
+        ? (resolveWslSessionContext({
+            cwd,
+            sessionId: effectiveSessionId,
+            shellOverride: terminalRuntimeOptions.shellOverride,
+            terminalWindowsWslDistro: terminalRuntimeOptions.terminalWindowsWslDistro
+          })?.distro ?? null)
+        : null
       const startupTerminalColorQueryReplyColors = getStartupTerminalColorQueryReplyColors(args)
       const preSpawnStartupTerminalColorReplyPtyId =
         startupTerminalColorQueryReplyColors && effectiveSessionId !== undefined
@@ -4158,6 +4192,7 @@ export function registerPtyHandlers(
         markHiddenRendererPty(preSpawnHiddenMarkId)
       }
       let result: PtySpawnResult
+      let preparedProvisionalExecutionContext = false
       try {
         try {
           if (preAllocatedHandle) {
@@ -4173,6 +4208,13 @@ export function registerPtyHandlers(
           }
           spawnTiming.mark('options')
           const expectedPtyId = effectiveSessionAppId ?? effectiveSessionId
+          if (isDaemonHostSpawn && expectedPtyId) {
+            preparedProvisionalExecutionContext =
+              runtime?.preparePtyExecutionContext?.(expectedPtyId, expectedWslDistro, {
+                resetIncarnation: isMintedSessionId,
+                preserveExisting: !isMintedSessionId
+              }) ?? false
+          }
           const sequenceBeforeProviderSpawn = expectedPtyId
             ? (runtime?.getPtyOutputSequence?.(expectedPtyId) ?? 0)
             : 0
@@ -4184,8 +4226,17 @@ export function registerPtyHandlers(
               sequenceBeforeProviderSpawn
             )
           }
+          runtime?.preparePtyExecutionContext?.(
+            result.id,
+            args.connectionId ? null : (result.wslDistro ?? expectedWslDistro)
+          )
           spawnTiming.mark('provider_spawn')
         } catch (err) {
+          if ((isMintedSessionId || preparedProvisionalExecutionContext) && effectiveSessionAppId) {
+            runtime?.preparePtyExecutionContext?.(effectiveSessionAppId, null, {
+              resetIncarnation: true
+            })
+          }
           // Why: a failed spawn must not leave a stale hidden mark on a session
           // id a later visible attach may reuse.
           if (preSpawnHiddenMarkId !== null) {
diff --git a/src/main/providers/types.ts b/src/main/providers/types.ts
index 2e98dbca243..8b04b0b096a 100644
--- a/src/main/providers/types.ts
+++ b/src/main/providers/types.ts
@@ -111,6 +111,8 @@ export type PtySpawnResult = {
   pid?: number | null
   /** Minimal allowlisted launch ownership returned by daemon reattach. */
   launchAgent?: TuiAgent
+  /** Immutable local WSL execution context returned by a daemon session. */
+  wslDistro?: string
   /** ANSI snapshot of the terminal screen, present when reattaching to an
    *  existing daemon session. Write this to xterm.js to restore visual state. */
   snapshot?: string
diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index 44bb1117c43..8045a45cd6a 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -8648,6 +8648,7 @@ describe('OrcaRuntimeService', () => {
   it('keeps SSH OSC7 cwd POSIX when the desktop runtime is on Windows', async () => {
     setPlatform('win32')
     const runtime = new OrcaRuntimeService(store)
+    runtime.preparePtyExecutionContext('pty-ssh', 'Ubuntu', { resetIncarnation: true })
     runtime.registerPty('pty-ssh', TEST_WORKTREE_ID, 'ssh-conn-1')
 
     runtime.onPtyData('pty-ssh', '\x1b]7;file://remote-host/home/me/repo/src\x07', 123)
@@ -8655,9 +8656,78 @@ describe('OrcaRuntimeService', () => {
     const internals = runtime as unknown as {
       terminalCwdByPtyId: Map<string, string>
       terminalFileUriHostnameByPtyId: Map<string, string>
+      wslDistroByPtyId: Map<string, string>
     }
     expect(internals.terminalCwdByPtyId.get('pty-ssh')).toBe('/home/me/repo/src')
     expect(internals.terminalFileUriHostnameByPtyId.get('pty-ssh')).toBe('remote-host')
+    expect(internals.wslDistroByPtyId.has('pty-ssh')).toBe(false)
+  })
+
+  it('uses per-incarnation WSL context before registration and across simultaneous distros', () => {
+    setPlatform('win32')
+    const runtime = new OrcaRuntimeService(store)
+    runtime.preparePtyExecutionContext('pty-ubuntu', 'Ubuntu', { resetIncarnation: true })
+    runtime.preparePtyExecutionContext('pty-debian', 'Debian', { resetIncarnation: true })
+    runtime.registerPty('pty-ubuntu', TEST_WORKTREE_ID)
+    runtime.registerPty('pty-debian', TEST_WORKTREE_ID)
+
+    runtime.onPtyData('pty-ubuntu', '\x1b]7;file://DESKTOP/home/me/repo\x07', 1)
+    runtime.onPtyData('pty-debian', '\x1b]7;file://DESKTOP/home/me/repo\x07', 1)
+
+    const cwds = (runtime as unknown as { terminalCwdByPtyId: Map<string, string> })
+      .terminalCwdByPtyId
+    expect(cwds.get('pty-ubuntu')).toBe('\\\\wsl.localhost\\Ubuntu\\home\\me\\repo')
+    expect(cwds.get('pty-debian')).toBe('\\\\wsl.localhost\\Debian\\home\\me\\repo')
+  })
+
+  it('does not retain WSL context when a PTY id is reused', () => {
+    setPlatform('win32')
+    const runtime = new OrcaRuntimeService(store)
+    runtime.preparePtyExecutionContext('pty-reused', 'Ubuntu', { resetIncarnation: true })
+    runtime.registerPty('pty-reused', TEST_WORKTREE_ID)
+    runtime.onPtyExit('pty-reused', 0)
+
+    runtime.preparePtyExecutionContext('pty-reused', null, { resetIncarnation: true })
+    runtime.registerPty('pty-reused', TEST_WORKTREE_ID)
+    runtime.onPtyData('pty-reused', '\x1b]7;file://server/share/repo\x07', 1)
+
+    const cwds = (runtime as unknown as { terminalCwdByPtyId: Map<string, string> })
+      .terminalCwdByPtyId
+    expect(cwds.get('pty-reused')).toBe('\\\\server\\share\\repo')
+  })
+
+  it('preserves immutable context while a live daemon attach is unresolved', () => {
+    setPlatform('win32')
+    const runtime = new OrcaRuntimeService(store)
+    runtime.preparePtyExecutionContext('pty-attached', 'Ubuntu', { resetIncarnation: true })
+    runtime.registerPty('pty-attached', TEST_WORKTREE_ID)
+
+    const changed = runtime.preparePtyExecutionContext('pty-attached', 'Debian', {
+      preserveExisting: true
+    })
+    runtime.onPtyData('pty-attached', '\x1b]7;file://DESKTOP/home/me/repo\x07', 1)
+
+    const cwd = (
+      runtime as unknown as { terminalCwdByPtyId: Map<string, string> }
+    ).terminalCwdByPtyId.get('pty-attached')
+    expect(changed).toBe(false)
+    expect(cwd).toBe('\\\\wsl.localhost\\Ubuntu\\home\\me\\repo')
+  })
+
+  it('infers local reconstructed WSL context from a WSL UNC worktree', () => {
+    setPlatform('win32')
+    const runtime = new OrcaRuntimeService(store)
+    runtime.registerPty(
+      'pty-reconstructed',
+      `${TEST_REPO_ID}::\\\\wsl.localhost\\Ubuntu\\home\\me\\repo`
+    )
+
+    runtime.onPtyData('pty-reconstructed', '\x1b]7;file://DESKTOP/home/me/repo/src\x07', 1)
+
+    const cwd = (
+      runtime as unknown as { terminalCwdByPtyId: Map<string, string> }
+    ).terminalCwdByPtyId.get('pty-reconstructed')
+    expect(cwd).toBe('\\\\wsl.localhost\\Ubuntu\\home\\me\\repo\\src')
   })
 
   it('clears stale terminal file URI hostnames after empty-host OSC7 cwd updates', () => {
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 60160117a6a..cf880c038db 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -245,7 +245,7 @@ import {
   normalizeRuntimePathForComparison
 } from '../../shared/cross-platform-path'
 import { resolveTerminalStartupCwd } from '../../shared/terminal-startup-cwd'
-import { isWslUncPath } from '../../shared/wsl-paths'
+import { isWslUncPath, parseWslUncPath } from '../../shared/wsl-paths'
 import {
   folderWorkspaceKey,
   isWorkspaceKey,
@@ -1014,6 +1014,7 @@ type RuntimePtyWorktreeRecord = {
   // Why: a Windows host can own both native and WSL panes; preamble command
   // selection must follow the pane that executes it, not process.platform.
   isWsl: boolean | null
+  wslDistro: 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
@@ -1246,7 +1247,7 @@ type RuntimePtyController = {
     leafId?: string
     sessionId?: string
     persistHostSessionBinding?: boolean
-  }): Promise<{ id: string }>
+  }): Promise<{ id: string; wslDistro?: string }>
   write(ptyId: string, data: string): boolean
   kill(ptyId: string): boolean
   stopAndWait?(ptyId: string, opts?: { keepHistory?: boolean }): Promise<boolean>
@@ -2323,6 +2324,7 @@ export class OrcaRuntimeService {
   // iterates them all. Listeners are cleaned up via subscriptionCleanups.
   private notificationListeners = new Set<(event: MobileNotificationEvent) => void>()
   private ptysById = new Map<string, RuntimePtyWorktreeRecord>()
+  private wslDistroByPtyId = new Map<string, string>()
   private titleObservationSequence = 0
   private headlessTerminals = new Map<string, RuntimeHeadlessTerminal>()
   private ptyOutputSequenceById = new Map<string, number>()
@@ -6007,6 +6009,44 @@ export class OrcaRuntimeService {
     }
   }
 
+  preparePtyExecutionContext(
+    ptyId: string,
+    wslDistro: string | null,
+    options: { resetIncarnation?: boolean; preserveExisting?: boolean } = {}
+  ): boolean {
+    const pty = this.ptysById.get(ptyId)
+    const hadExistingContext = this.wslDistroByPtyId.has(ptyId) || pty !== undefined
+    if (options.preserveExisting && hadExistingContext) {
+      // Why: attach-time settings are only a fallback; a live PTY's recorded
+      // execution namespace remains authoritative until its provider replies.
+      return false
+    }
+
+    if (options.resetIncarnation) {
+      this.disposeHeadlessTerminal(ptyId)
+      this.osc7ScanTailByPtyId.delete(ptyId)
+      this.terminalCwdByPtyId.delete(ptyId)
+      this.terminalFileUriHostnameByPtyId.delete(ptyId)
+      this.wslDistroByPtyId.delete(ptyId)
+    }
+
+    const previous = this.wslDistroByPtyId.get(ptyId) ?? null
+    if (wslDistro) {
+      this.wslDistroByPtyId.set(ptyId, wslDistro)
+    } else {
+      this.wslDistroByPtyId.delete(ptyId)
+    }
+    if (pty) {
+      pty.wslDistro = wslDistro
+    }
+    if (!options.resetIncarnation && previous !== wslDistro && this.headlessTerminals.has(ptyId)) {
+      // Why: bytes parsed with two distro namespaces would leave an internally
+      // inconsistent CWD; rebuild from the provider's authoritative snapshot.
+      this.replaceHeadlessTerminalAfterExecutionContextChange(ptyId)
+    }
+    return options.resetIncarnation === true || !hadExistingContext || previous !== wslDistro
+  }
+
   /** Record the spawn launch command so the per-PTY Command Code detector can
    *  arm from it (renderer startupCommand parity). Best-effort: a chunk that
    *  beats this call falls back to the detector's banner arming. */
@@ -6828,7 +6868,10 @@ export class OrcaRuntimeService {
     return uri
       ? parseFileUriPathParts(uri, {
           pathFlavor,
-          remotePosixAuthority: !!pty?.connectionId && pathFlavor !== 'win32'
+          remotePosixAuthority: !!pty?.connectionId && pathFlavor !== 'win32',
+          wslDistro: pty?.connectionId
+            ? undefined
+            : (this.wslDistroByPtyId.get(ptyId) ?? pty?.wslDistro ?? undefined)
         })
       : null
   }
@@ -7036,6 +7079,13 @@ export class OrcaRuntimeService {
         this.disposeHeadlessTerminal(ptyId)
       }
       this.providerModeTrackersByPtyId.delete(ptyId)
+      this.wslDistroByPtyId.delete(ptyId)
+      this.terminalCwdByPtyId.delete(ptyId)
+      this.terminalFileUriHostnameByPtyId.delete(ptyId)
+      const pty = this.ptysById.get(ptyId)
+      if (pty) {
+        pty.wslDistro = null
+      }
       if (replacesExistingRuntimeGeneration && postSpawnSequence === 0) {
         this.resetTrackedTerminalStateForProviderGeneration(ptyId)
       }
@@ -7521,6 +7571,9 @@ export class OrcaRuntimeService {
       pathFlavor,
       remotePosixFileUriAuthority:
         !!this.ptysById.get(ptyId)?.connectionId && pathFlavor !== 'win32',
+      wslDistro: this.ptysById.get(ptyId)?.connectionId
+        ? undefined
+        : (this.wslDistroByPtyId.get(ptyId) ?? this.ptysById.get(ptyId)?.wslDistro ?? undefined),
       // Why: replies take the provider input path (same entry as pty:write —
       // daemon shell-ready gating and the SSH relay write apply unchanged),
       // NOT writePtyInput, so renderer interactive-output metering never
@@ -7573,6 +7626,37 @@ export class OrcaRuntimeService {
     return state
   }
 
+  private replaceHeadlessTerminalAfterExecutionContextChange(ptyId: string): void {
+    this.disposeHeadlessTerminal(ptyId)
+    this.providerSnapshotPreferredPtys.add(ptyId)
+    const dims = this.getTerminalSize(ptyId) ?? { cols: 80, rows: 24 }
+    const state = this.createPtyHeadlessTerminalState(ptyId, dims)
+    this.headlessTerminals.set(ptyId, state)
+    state.writeChain = state.writeChain
+      .then(async () => {
+        const snapshot = await this.serializeProviderTerminalBuffer(ptyId)
+        if (!snapshot) {
+          return
+        }
+        const data = `${snapshot.scrollbackAnsi ?? ''}${snapshot.data}`
+        this.recordOsc7MetadataForPty(ptyId, data)
+        await state.emulator.write(data)
+        if (snapshot.cwd !== undefined) {
+          state.emulator.setCwd(snapshot.cwd)
+        }
+        if (snapshot.oscLinks !== undefined) {
+          state.emulator.setRestoredOscLinks(snapshot.oscLinks)
+        }
+        state.outputSequence = snapshot.seq
+      })
+      .catch(() => {
+        // Best-effort: live bytes already chain behind this replacement state.
+      })
+      .finally(() => {
+        this.providerSnapshotPreferredPtys.delete(ptyId)
+      })
+  }
+
   private resizeHeadlessTerminal(ptyId: string, cols: number, rows: number): void {
     const state = this.headlessTerminals.get(ptyId)
     if (!state) {
@@ -9117,6 +9201,7 @@ export class OrcaRuntimeService {
     this.osc7ScanTailByPtyId.delete(ptyId)
     this.terminalCwdByPtyId.delete(ptyId)
     this.terminalFileUriHostnameByPtyId.delete(ptyId)
+    this.wslDistroByPtyId.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.
@@ -18918,6 +19003,9 @@ export class OrcaRuntimeService {
           : {})
       })
       this.registerPreAllocatedHandleForPty(result.id, preAllocatedHandle)
+      if (result.wslDistro) {
+        this.preparePtyExecutionContext(result.id, result.wslDistro)
+      }
       this.registerPty(result.id, workspace.id, workspace.connectionId)
       const pty = this.getOrCreatePtyWorktreeRecord(result.id)
       if (pty) {
@@ -20091,6 +20179,9 @@ export class OrcaRuntimeService {
       preAllocatedHandle
     })
     this.registerPreAllocatedHandleForPty(result.id, preAllocatedHandle)
+    if (result.wslDistro) {
+      this.preparePtyExecutionContext(result.id, result.wslDistro)
+    }
     this.registerPty(result.id, workspace.id, workspace.connectionId)
     const createdPty = this.getOrCreatePtyWorktreeRecord(result.id)
     if (createdPty) {
@@ -21582,17 +21673,29 @@ export class OrcaRuntimeService {
         | 'title'
         | 'connectionId'
         | 'isWsl'
+        | 'wslDistro'
       >
     > = {}
   ): RuntimePtyWorktreeRecord {
     let pty = this.ptysById.get(ptyId)
     if (!pty) {
       const titleObservedAt = state.title ? this.nextTitleObservationSequence() : null
+      const connectionId = state.connectionId ?? parseAppSshPtyId(ptyId)?.connectionId ?? null
+      const worktreePath = splitWorktreeIdForFilesystem(worktreeId)?.worktreePath
+      const fallbackWslDistro =
+        process.platform === 'win32' && connectionId === null && worktreePath
+          ? parseWslUncPath(worktreePath)?.distro
+          : undefined
+      const wslDistro =
+        connectionId === null
+          ? (state.wslDistro ?? this.wslDistroByPtyId.get(ptyId) ?? fallbackWslDistro ?? null)
+          : null
       pty = {
         ptyId,
         worktreeId,
-        connectionId: state.connectionId ?? parseAppSshPtyId(ptyId)?.connectionId ?? null,
+        connectionId,
         isWsl: state.isWsl ?? null,
+        wslDistro,
         tabId: state.tabId ?? null,
         paneKey: state.paneKey ?? null,
         launchConfig: null,
@@ -21625,6 +21728,13 @@ export class OrcaRuntimeService {
         this.setPtyManagementTitleFromObservedTitle(pty, state.title, titleObservedAt ?? 0)
       }
       this.ptysById.set(ptyId, pty)
+      if (wslDistro) {
+        this.wslDistroByPtyId.set(ptyId, wslDistro)
+      } else if (connectionId !== null) {
+        // Why: restored SSH IDs can collide with stale local parser state;
+        // connection ownership must win before their first output is parsed.
+        this.wslDistroByPtyId.delete(ptyId)
+      }
       // Why: restored/controller-discovered PTYs learn their worktree here
       // without registerPty(), so URL enrichment must bind at this source.
       advertisedUrlWatcher.bindPty(ptyId, worktreeId)
@@ -21634,10 +21744,22 @@ export class OrcaRuntimeService {
     pty.worktreeId = worktreeId
     if (state.connectionId !== undefined) {
       pty.connectionId = state.connectionId
+      if (state.connectionId !== null) {
+        pty.wslDistro = null
+        this.wslDistroByPtyId.delete(ptyId)
+      }
     }
     if (state.isWsl !== undefined) {
       pty.isWsl = state.isWsl
     }
+    if (state.wslDistro !== undefined) {
+      pty.wslDistro = state.wslDistro
+      if (state.wslDistro) {
+        this.wslDistroByPtyId.set(ptyId, state.wslDistro)
+      } else {
+        this.wslDistroByPtyId.delete(ptyId)
+      }
+    }
     if (state.tabId !== undefined) {
       pty.tabId = state.tabId
     }
@@ -21799,6 +21921,7 @@ export class OrcaRuntimeService {
     this.osc7ScanTailByPtyId.delete(ptyId)
     this.terminalCwdByPtyId.delete(ptyId)
     this.terminalFileUriHostnameByPtyId.delete(ptyId)
+    this.wslDistroByPtyId.delete(ptyId)
     this.clearAgentRowSnapshotsForPty(ptyId)
     const handle = this.handleByPtyId.get(ptyId)
     if (handle) {
diff --git a/src/main/wsl.ts b/src/main/wsl.ts
index 1d27b694d2c..504ac981010 100644
--- a/src/main/wsl.ts
+++ b/src/main/wsl.ts
@@ -1,5 +1,7 @@
 import { execFile, execFileSync } from 'node:child_process'
-import { parseWslUncPath } from '../shared/wsl-paths'
+import { parseWslUncPath, toWindowsWslPath } from '../shared/wsl-paths'
+
+export { toWindowsWslPath } from '../shared/wsl-paths'
 
 export type WslPathInfo = {
   distro: string
@@ -89,26 +91,6 @@ export function toLinuxPath(windowsPath: string): string {
   return `/mnt/${driveLetter}/${rest}`
 }
 
-/**
- * Convert a Linux path inside a WSL distro to a Windows path.
- *
- * Why two forms: paths under /mnt/<drive>/... are Windows-native filesystem
- * paths that WSL exposes via the DrvFs mount. These map back to their native
- * Windows form (e.g. /mnt/c/Users → C:\Users). All other paths live on the
- * WSL virtual filesystem and use the UNC form (\\wsl.localhost\Distro\...).
- */
-export function toWindowsWslPath(linuxPath: string, distro: string): string {
-  // /mnt/c/Users/... → C:\Users\...
-  const mntMatch = linuxPath.match(/^\/mnt\/([a-z])(\/.*)?$/)
-  if (mntMatch) {
-    const driveLetter = mntMatch[1].toUpperCase()
-    const rest = (mntMatch[2] || '').replace(/\//g, '\\')
-    return `${driveLetter}:${rest || '\\'}`
-  }
-
-  return `\\\\wsl.localhost\\${distro}${linuxPath.replace(/\//g, '\\')}`
-}
-
 // ─── WSL home directory resolution ──────────────────────────────────
 
 const wslHomeCache = new Map<string, string>()
diff --git a/src/shared/wsl-paths.test.ts b/src/shared/wsl-paths.test.ts
index 498e3c02860..6a9641d41ac 100644
--- a/src/shared/wsl-paths.test.ts
+++ b/src/shared/wsl-paths.test.ts
@@ -1,5 +1,10 @@
 import { describe, expect, it } from 'vitest'
-import { foldWslUncPathCaseInsensitiveParts, isWslUncPath, parseWslUncPath } from './wsl-paths'
+import {
+  foldWslUncPathCaseInsensitiveParts,
+  isWslUncPath,
+  parseWslUncPath,
+  toWindowsWslPath
+} from './wsl-paths'
 
 describe('wsl path helpers', () => {
   it('parses modern and legacy WSL UNC paths without platform checks', () => {
@@ -17,6 +22,16 @@ describe('wsl path helpers', () => {
     expect(isWslUncPath('C:\\Users\\jin\\repo')).toBe(false)
     expect(isWslUncPath('/home/jin/repo')).toBe(false)
   })
+
+  it.each([
+    ['/home/jin/repo', '\\\\wsl.localhost\\Ubuntu\\home\\jin\\repo'],
+    ['/', '\\\\wsl.localhost\\Ubuntu\\'],
+    ['/mnt/c/Users/jin', 'C:\\Users\\jin'],
+    ['/MNT/c/Repo', '\\\\wsl.localhost\\Ubuntu\\MNT\\c\\Repo'],
+    ['/mnt/C/Repo', '\\\\wsl.localhost\\Ubuntu\\mnt\\C\\Repo']
+  ])('converts %s without folding case-sensitive Linux paths', (linuxPath, expected) => {
+    expect(toWindowsWslPath(linuxPath, 'Ubuntu')).toBe(expected)
+  })
 })
 
 describe('foldWslUncPathCaseInsensitiveParts', () => {
diff --git a/src/shared/wsl-paths.ts b/src/shared/wsl-paths.ts
index 3db38712251..f8acb9d69d6 100644
--- a/src/shared/wsl-paths.ts
+++ b/src/shared/wsl-paths.ts
@@ -20,6 +20,17 @@ export function isWslUncPath(path: string): boolean {
   return parseWslUncPath(path) !== null
 }
 
+/** Convert an absolute Linux path in a known WSL distro to its Windows form. */
+export function toWindowsWslPath(linuxPath: string, distro: string): string {
+  const mntMatch = linuxPath.match(/^\/mnt\/([a-z])(\/.*)?$/)
+  if (mntMatch) {
+    const rest = (mntMatch[2] || '').replace(/\//g, '\\')
+    return `${mntMatch[1].toUpperCase()}:${rest || '\\'}`
+  }
+
+  return `\\\\wsl.localhost\\${distro}${linuxPath.replace(/\//g, '\\')}`
+}
+
 // Why: Windows folds the share (\\wsl$ aliases \\wsl.localhost), the distro, and
 // drvfs /mnt/<drive> tails case-insensitively; the rest of the Linux path is not.
 export function foldWslUncPathCaseInsensitiveParts(path: string): string | null {

From 01ce6db1685d5afd46e73503d9c921211722d9e6 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 17 Jul 2026 16:21:28 -0400
Subject: [PATCH 03/54] test: make WSL cwd fixture cross-platform

---
 src/main/daemon/pty-subprocess.test.ts | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/src/main/daemon/pty-subprocess.test.ts b/src/main/daemon/pty-subprocess.test.ts
index 30f45915a82..b378068a4c2 100644
--- a/src/main/daemon/pty-subprocess.test.ts
+++ b/src/main/daemon/pty-subprocess.test.ts
@@ -2363,7 +2363,8 @@ describe('createPtySubprocess', () => {
     const proc = mockPtyProcess()
     spawnMock.mockReturnValue(proc)
     const platform = Object.getOwnPropertyDescriptor(process, 'platform')
-    const cwd = mkdtempSync(join(tmpdir(), 'daemon-pty-wsl-distro-test-'))
+    // Keep the fixture Windows-shaped even when this test runs on a Linux CI host.
+    const cwd = 'C:\\repo'
 
     Object.defineProperty(process, 'platform', { value: 'win32' })
 
@@ -2380,18 +2381,11 @@ describe('createPtySubprocess', () => {
       if (platform) {
         Object.defineProperty(process, 'platform', platform)
       }
-      rmSync(cwd, { recursive: true, force: true })
     }
 
-    const normalizedCwd = cwd.replace(/\\/g, '/')
-    const driveMatch = normalizedCwd.match(/^([A-Za-z]):\/?(.*)$/)
-    const expectedLinuxCwd = driveMatch
-      ? `/mnt/${driveMatch[1].toLowerCase()}${driveMatch[2] ? `/${driveMatch[2]}` : ''}`
-      : '/mnt/c'
-
     expect(spawnMock).toHaveBeenCalledWith(
       'wsl.exe',
-      ['-d', 'Debian', '--', 'sh', '-c', expect.stringContaining(`cd '${expectedLinuxCwd}'`)],
+      ['-d', 'Debian', '--', 'sh', '-c', expect.stringContaining("cd '/mnt/c/repo'")],
       expect.objectContaining({ cwd: expect.any(String) })
     )
   })

From 8281038d602335df05425bf812cd52f898a4a0f3 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 17 Jul 2026 17:14:12 -0400
Subject: [PATCH 04/54] fix: refresh CWD after late WSL context

---
 src/main/runtime/orca-runtime.test.ts | 86 +++++++++++++++++++++++++++
 src/main/runtime/orca-runtime.ts      | 10 +++-
 2 files changed, 95 insertions(+), 1 deletion(-)

diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index 8045a45cd6a..9e194212d35 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -8714,6 +8714,92 @@ describe('OrcaRuntimeService', () => {
     expect(cwd).toBe('\\\\wsl.localhost\\Ubuntu\\home\\me\\repo')
   })
 
+  it('replaces a cwd parsed before late WSL context with the provider cwd', async () => {
+    setPlatform('win32')
+    const runtime = new OrcaRuntimeService(store)
+    const ptyId = 'pty-late-wsl-context'
+    const providerCwd = '\\\\wsl.localhost\\Ubuntu\\home\\me\\repo'
+    runtime.setPtyController({
+      write: () => true,
+      kill: () => true,
+      getForegroundProcess: async () => null,
+      getSize: () => ({ cols: 80, rows: 24 }),
+      serializeProviderBuffer: vi.fn().mockResolvedValue({
+        data: 'restored screen',
+        cols: 80,
+        rows: 24,
+        cwd: providerCwd,
+        seq: 1,
+        source: 'headless'
+      })
+    })
+    runtime.registerPty(ptyId, TEST_WORKTREE_ID)
+    runtime.seedHeadlessTerminal(ptyId, '\x1b]7;file://DESKTOP/home/me/repo\x07')
+
+    const internals = runtime as unknown as {
+      headlessTerminals: Map<string, { writeChain: Promise<void> }>
+      terminalCwdByPtyId: Map<string, string>
+    }
+    await internals.headlessTerminals.get(ptyId)?.writeChain
+    expect(internals.terminalCwdByPtyId.get(ptyId)).toBe('\\\\desktop\\home\\me\\repo')
+
+    runtime.preparePtyExecutionContext(ptyId, 'Ubuntu')
+    await internals.headlessTerminals.get(ptyId)?.writeChain
+
+    expect(internals.terminalCwdByPtyId.get(ptyId)).toBe(providerCwd)
+  })
+
+  it('keeps a live WSL cwd that arrives during late-context snapshot recovery', async () => {
+    setPlatform('win32')
+    const runtime = new OrcaRuntimeService(store)
+    const ptyId = 'pty-late-wsl-context-race'
+    type ProviderSnapshot = {
+      data: string
+      cols: number
+      rows: number
+      cwd: string
+      seq: number
+      source: 'headless'
+    }
+    let resolveProviderSnapshot: ((snapshot: ProviderSnapshot) => void) | undefined
+    runtime.setPtyController({
+      write: () => true,
+      kill: () => true,
+      getForegroundProcess: async () => null,
+      getSize: () => ({ cols: 80, rows: 24 }),
+      serializeProviderBuffer: vi.fn(
+        () =>
+          new Promise<ProviderSnapshot>((resolve) => {
+            resolveProviderSnapshot = resolve
+          })
+      )
+    })
+    runtime.registerPty(ptyId, TEST_WORKTREE_ID)
+    runtime.seedHeadlessTerminal(ptyId, '\x1b]7;file://DESKTOP/home/me/old\x07')
+    const internals = runtime as unknown as {
+      headlessTerminals: Map<string, { writeChain: Promise<void> }>
+      terminalCwdByPtyId: Map<string, string>
+    }
+    await internals.headlessTerminals.get(ptyId)?.writeChain
+
+    runtime.preparePtyExecutionContext(ptyId, 'Ubuntu')
+    await vi.waitFor(() => expect(resolveProviderSnapshot).toBeDefined())
+    runtime.onPtyData(ptyId, '\x1b]7;file://DESKTOP/home/me/live\x07', 1)
+    resolveProviderSnapshot?.({
+      data: 'older restored screen',
+      cols: 80,
+      rows: 24,
+      cwd: '\\\\wsl.localhost\\Ubuntu\\home\\me\\old',
+      seq: 1,
+      source: 'headless'
+    })
+    await internals.headlessTerminals.get(ptyId)?.writeChain
+
+    expect(internals.terminalCwdByPtyId.get(ptyId)).toBe(
+      '\\\\wsl.localhost\\Ubuntu\\home\\me\\live'
+    )
+  })
+
   it('infers local reconstructed WSL context from a WSL UNC worktree', () => {
     setPlatform('win32')
     const runtime = new OrcaRuntimeService(store)
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index cf880c038db..418809d2f57 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -6042,6 +6042,7 @@ export class OrcaRuntimeService {
     if (!options.resetIncarnation && previous !== wslDistro && this.headlessTerminals.has(ptyId)) {
       // Why: bytes parsed with two distro namespaces would leave an internally
       // inconsistent CWD; rebuild from the provider's authoritative snapshot.
+      this.terminalCwdByPtyId.delete(ptyId)
       this.replaceHeadlessTerminalAfterExecutionContextChange(ptyId)
     }
     return options.resetIncarnation === true || !hadExistingContext || previous !== wslDistro
@@ -7639,10 +7640,17 @@ export class OrcaRuntimeService {
           return
         }
         const data = `${snapshot.scrollbackAnsi ?? ''}${snapshot.data}`
-        this.recordOsc7MetadataForPty(ptyId, data)
+        // Why: a newer live OSC 7 can arrive while the snapshot is in flight;
+        // only seed metadata while no post-correction CWD has won the race.
+        if (!this.terminalCwdByPtyId.has(ptyId)) {
+          this.recordOsc7MetadataForPty(ptyId, data)
+        }
         await state.emulator.write(data)
         if (snapshot.cwd !== undefined) {
           state.emulator.setCwd(snapshot.cwd)
+          if (!this.terminalCwdByPtyId.has(ptyId) && snapshot.cwd?.trim()) {
+            this.terminalCwdByPtyId.set(ptyId, snapshot.cwd)
+          }
         }
         if (snapshot.oscLinks !== undefined) {
           state.emulator.setRestoredOscLinks(snapshot.oscLinks)

From bbb54065e876707b5a0677d47b33b0411bef7e53 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Sun, 19 Jul 2026 15:01:14 -0700
Subject: [PATCH 05/54] fix: preserve native PTY context on reattach

---
 .../daemon/daemon-create-or-attach-result.ts  | 13 +++-
 src/main/daemon/daemon-pty-adapter.test.ts    | 32 +++++++++
 src/main/daemon/daemon-pty-adapter.ts         | 22 +++---
 src/main/daemon/daemon-server.ts              |  2 +-
 .../daemon/terminal-host-create-contract.ts   |  2 +-
 .../daemon/terminal-host-wsl-context.test.ts  | 33 +++++++++
 src/main/ipc/pty.test.ts                      | 69 ++++++++++++++++++-
 src/main/ipc/pty.ts                           | 12 +++-
 src/main/providers/local-pty-provider.test.ts | 54 ++++++++++++++-
 src/main/providers/local-pty-provider.ts      | 24 ++++++-
 src/main/providers/types.ts                   |  6 +-
 11 files changed, 246 insertions(+), 23 deletions(-)

diff --git a/src/main/daemon/daemon-create-or-attach-result.ts b/src/main/daemon/daemon-create-or-attach-result.ts
index 6e587537b82..79417577ab7 100644
--- a/src/main/daemon/daemon-create-or-attach-result.ts
+++ b/src/main/daemon/daemon-create-or-attach-result.ts
@@ -8,17 +8,24 @@ export type DaemonCreateOrAttachResult = {
   shellState: ShellReadyState
   historySeeded?: boolean
   launchAgent?: TuiAgent
-  wslDistro?: string
+  /** Undefined only when talking to a daemon predating WSL session context. */
+  wslDistro?: string | null
 }
 
 export function getDaemonSessionResultMetadata(session: {
   launchAgent: TuiAgent | null
   historySeeded: boolean | undefined
   wslDistro: string | null
-}): Pick<DaemonCreateOrAttachResult, 'launchAgent' | 'historySeeded' | 'wslDistro'> {
+}): {
+  launchAgent?: TuiAgent
+  historySeeded?: boolean
+  wslDistro: string | null
+} {
   return {
     ...(session.launchAgent ? { launchAgent: session.launchAgent } : {}),
     ...(session.historySeeded !== undefined ? { historySeeded: session.historySeeded } : {}),
-    ...(session.wslDistro ? { wslDistro: session.wslDistro } : {})
+    // Why: null authoritatively identifies a native session; omission is
+    // reserved for older daemons that predate this wire field.
+    wslDistro: session.wslDistro
   }
 }
diff --git a/src/main/daemon/daemon-pty-adapter.test.ts b/src/main/daemon/daemon-pty-adapter.test.ts
index a9f25d5865a..14243aa15eb 100644
--- a/src/main/daemon/daemon-pty-adapter.test.ts
+++ b/src/main/daemon/daemon-pty-adapter.test.ts
@@ -149,6 +149,38 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       expect(result.id).toContain('wt-1')
     })
 
+    it('keeps a reattached native UNC session native despite a conflicting WSL preference', async () => {
+      const platform = Object.getOwnPropertyDescriptor(process, 'platform')
+      Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' })
+      try {
+        const sessionId = 'native-conflicting-wsl-attach'
+        const created = await adapter.spawn({
+          cols: 80,
+          rows: 24,
+          sessionId,
+          cwd: '\\\\server\\share\\repo',
+          shellOverride: 'powershell.exe'
+        })
+        const attached = await adapter.spawn({
+          cols: 80,
+          rows: 24,
+          sessionId,
+          cwd: 'C:\\repo',
+          shellOverride: 'wsl.exe',
+          terminalWindowsWslDistro: 'Ubuntu'
+        })
+
+        expect(created.wslDistro).toBeNull()
+        expect(attached.wslDistro).toBeNull()
+        expect(attached.isReattach).toBe(true)
+        expect(lastSpawnOpts?.cwd).toBe('\\\\server\\share\\repo')
+      } finally {
+        if (platform) {
+          Object.defineProperty(process, 'platform', platform)
+        }
+      }
+    })
+
     itOnPosix('keeps plain Codex startup on the short daemon shell-ready timeout', async () => {
       await adapter.spawn({
         cols: 80,
diff --git a/src/main/daemon/daemon-pty-adapter.ts b/src/main/daemon/daemon-pty-adapter.ts
index 5d44eeb71d9..202718eab7f 100644
--- a/src/main/daemon/daemon-pty-adapter.ts
+++ b/src/main/daemon/daemon-pty-adapter.ts
@@ -301,10 +301,13 @@ export class DaemonPtyAdapter implements IPtyProvider {
 
     let scrollback = restoreInfo ? getRecoveredHistorySeed(restoreInfo) : null
     let result = await createOrAttach(scrollback)
-    wslDistro = result.wslDistro ?? wslDistro
+    let providerWslDistro = result.wslDistro === undefined ? wslDistro : result.wslDistro
+    // Why: explicit null from a current daemon overrides the caller's WSL
+    // preference; undefined preserves compatibility with older daemons.
+    wslDistro = providerWslDistro ?? undefined
     if (wslDistro) {
       this.wslDistrosBySessionId.set(sessionId, wslDistro)
-    } else if (result.isNew) {
+    } else if (providerWslDistro === null || result.isNew) {
       this.wslDistrosBySessionId.delete(sessionId)
     }
     const launchIdentity = (): { launchAgent?: NonNullable<typeof result.launchAgent> } =>
@@ -337,7 +340,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
         pid,
         ...launchIdentity(),
         coldRestore: cachedRestore,
-        ...(wslDistro ? { wslDistro } : {}),
+        ...(providerWslDistro !== undefined ? { wslDistro: providerWslDistro } : {}),
         ...(!result.isNew ? { isReattach: true } : {})
       }
     }
@@ -361,10 +364,11 @@ export class DaemonPtyAdapter implements IPtyProvider {
         effectiveCols = restoreInfo.cols
         effectiveRows = restoreInfo.rows
         result = await createOrAttach(scrollback)
-        wslDistro = result.wslDistro ?? wslDistro
+        providerWslDistro = result.wslDistro === undefined ? wslDistro : result.wslDistro
+        wslDistro = providerWslDistro ?? undefined
         if (wslDistro) {
           this.wslDistrosBySessionId.set(sessionId, wslDistro)
-        } else if (result.isNew) {
+        } else if (providerWslDistro === null || result.isNew) {
           this.wslDistrosBySessionId.delete(sessionId)
         }
         pid = typeof result.pid === 'number' && result.pid > 0 ? result.pid : null
@@ -409,7 +413,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
           pid,
           ...launchIdentity(),
           coldRestore,
-          ...(wslDistro ? { wslDistro } : {}),
+          ...(providerWslDistro !== undefined ? { wslDistro: providerWslDistro } : {}),
           ...(providerSequence ? { providerSequence } : {}),
           ...(!result.isNew ? { isReattach: true } : {})
         }
@@ -418,7 +422,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
         id: sessionId,
         pid,
         ...launchIdentity(),
-        ...(wslDistro ? { wslDistro } : {}),
+        ...(providerWslDistro !== undefined ? { wslDistro: providerWslDistro } : {}),
         ...(providerSequence ? { providerSequence } : {})
       }
     }
@@ -458,7 +462,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
         id: sessionId,
         pid,
         ...launchIdentity(),
-        ...(wslDistro ? { wslDistro } : {}),
+        ...(providerWslDistro !== undefined ? { wslDistro: providerWslDistro } : {}),
         ...(providerSequence ? { providerSequence } : {}),
         ...(isReattach ? { isReattach: true } : {})
       }
@@ -478,7 +482,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       id: sessionId,
       pid,
       ...launchIdentity(),
-      ...(wslDistro ? { wslDistro } : {}),
+      ...(providerWslDistro !== undefined ? { wslDistro: providerWslDistro } : {}),
       snapshot: snapshotPayload,
       snapshotCols: result.snapshot.cols,
       snapshotRows: result.snapshot.rows,
diff --git a/src/main/daemon/daemon-server.ts b/src/main/daemon/daemon-server.ts
index 2ee3aeba35b..c5d6c04dfee 100644
--- a/src/main/daemon/daemon-server.ts
+++ b/src/main/daemon/daemon-server.ts
@@ -467,7 +467,7 @@ export class DaemonServer {
           pid: result.pid,
           shellState: result.shellState,
           ...(result.launchAgent ? { launchAgent: result.launchAgent } : {}),
-          ...(result.wslDistro ? { wslDistro: result.wslDistro } : {}),
+          wslDistro: result.wslDistro,
           ...(result.historySeeded !== undefined ? { historySeeded: result.historySeeded } : {})
         }
       }
diff --git a/src/main/daemon/terminal-host-create-contract.ts b/src/main/daemon/terminal-host-create-contract.ts
index 5c4ad2d9a69..10cd5733cd3 100644
--- a/src/main/daemon/terminal-host-create-contract.ts
+++ b/src/main/daemon/terminal-host-create-contract.ts
@@ -29,6 +29,6 @@ export type CreateOrAttachResult = {
   shellState: ShellReadyState
   historySeeded?: boolean
   launchAgent?: TuiAgent
-  wslDistro?: string
+  wslDistro: string | null
   attachToken: symbol
 }
diff --git a/src/main/daemon/terminal-host-wsl-context.test.ts b/src/main/daemon/terminal-host-wsl-context.test.ts
index e9fccb7b737..123726beae2 100644
--- a/src/main/daemon/terminal-host-wsl-context.test.ts
+++ b/src/main/daemon/terminal-host-wsl-context.test.ts
@@ -60,6 +60,39 @@ describe('TerminalHost WSL context', () => {
     }
   })
 
+  it('returns authoritative null when a native session is attached with a WSL preference', async () => {
+    const spawnSubprocess = vi.fn(() => createSubprocess())
+    host = new TerminalHost({ spawnSubprocess })
+    const platform = Object.getOwnPropertyDescriptor(process, 'platform')
+    Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' })
+    try {
+      const created = await host.createOrAttach({
+        sessionId: 'session-native',
+        cols: 80,
+        rows: 24,
+        cwd: '\\\\server\\share\\repo',
+        shellOverride: 'powershell.exe',
+        streamClient: { onData: vi.fn(), onExit: vi.fn() }
+      })
+      const attached = await host.createOrAttach({
+        sessionId: 'session-native',
+        cols: 80,
+        rows: 24,
+        shellOverride: 'wsl.exe',
+        terminalWindowsWslDistro: 'Ubuntu',
+        streamClient: { onData: vi.fn(), onExit: vi.fn() }
+      })
+
+      expect(created.wslDistro).toBeNull()
+      expect(attached.wslDistro).toBeNull()
+      expect(spawnSubprocess).toHaveBeenCalledOnce()
+    } finally {
+      if (platform) {
+        Object.defineProperty(process, 'platform', platform)
+      }
+    }
+  })
+
   it('uses a remembered distro only when the selected shell is WSL', () => {
     const platform = Object.getOwnPropertyDescriptor(process, 'platform')
     Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' })
diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index a8dd387dffe..984bd045431 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -1414,14 +1414,18 @@ describe('registerPtyHandlers', () => {
       // OpenCode plugin dir, Pi managed extension env, Codex home, and dev-mode CLI
       // overrides were silently missing for daemon users (the common case).
 
-      function setupDaemonAdapter(supportsGitCredentialGuardHost = true) {
+      function setupDaemonAdapter(
+        supportsGitCredentialGuardHost = true,
+        reportedWslDistro?: string | null
+      ) {
         const daemonSpawn = vi.fn(
           async (options: {
             env: Record<string, string>
             sessionId?: string
             isNewSession?: boolean
           }) => ({
-            id: options.sessionId ?? 'daemon-pty'
+            id: options.sessionId ?? 'daemon-pty',
+            ...(reportedWslDistro !== undefined ? { wslDistro: reportedWslDistro } : {})
           })
         )
         setLocalPtyProvider({
@@ -1934,6 +1938,67 @@ describe('registerPtyHandlers', () => {
         })
       })
 
+      it('distinguishes an attached native context from an older daemon fallback', async () => {
+        await withWin32Platform(async () => {
+          _setWslCachesForTests({ available: true, distros: ['Ubuntu'] })
+          const settings = {
+            localWindowsRuntimeDefault: { kind: 'wsl', distro: 'Ubuntu' },
+            terminalWindowsShell: 'wsl.exe',
+            terminalWindowsWslDistro: 'Ubuntu',
+            terminalWindowsPowerShellImplementation: 'auto'
+          }
+          const cases: {
+            reportedWslDistro: string | null | undefined
+            expectedWslDistro: string | null
+            sessionId: string
+          }[] = [
+            {
+              reportedWslDistro: null,
+              expectedWslDistro: null,
+              sessionId: 'native-session'
+            },
+            {
+              reportedWslDistro: undefined,
+              expectedWslDistro: 'Ubuntu',
+              sessionId: 'older-daemon-session'
+            }
+          ]
+
+          for (const testCase of cases) {
+            setupDaemonAdapter(true, testCase.reportedWslDistro)
+            const runtime = {
+              setPtyController: vi.fn(),
+              createPreAllocatedTerminalHandle: vi.fn(() => null),
+              preAllocateHandleForPty: vi.fn(),
+              registerPty: vi.fn(),
+              onPtySpawned: vi.fn(),
+              onPtyExit: vi.fn(),
+              onPtyData: vi.fn(),
+              preparePtyExecutionContext: vi.fn().mockReturnValue(true)
+            }
+            handlers.clear()
+            registerPtyHandlers(
+              mainWindow as never,
+              runtime as never,
+              undefined,
+              (() => settings) as never
+            )
+
+            await handlers.get('pty:spawn')!(null, {
+              cols: 80,
+              rows: 24,
+              sessionId: testCase.sessionId,
+              cwd: '\\\\server\\share\\repo'
+            })
+
+            expect(runtime.preparePtyExecutionContext).toHaveBeenLastCalledWith(
+              testCase.sessionId,
+              testCase.expectedWslDistro
+            )
+          }
+        })
+      })
+
       it('blocks runtime-created daemon PTYs when project WSL runtime requires repair', async () => {
         await withWin32Platform(async () => {
           _setWslCachesForTests({ available: true, distros: ['Debian'] })
diff --git a/src/main/ipc/pty.ts b/src/main/ipc/pty.ts
index 0c1803d4555..8c6b89d0d48 100644
--- a/src/main/ipc/pty.ts
+++ b/src/main/ipc/pty.ts
@@ -3235,7 +3235,11 @@ export function registerPtyHandlers(
           }
           runtime?.preparePtyExecutionContext?.(
             result.id,
-            args.connectionId ? null : (result.wslDistro ?? expectedWslDistro)
+            args.connectionId
+              ? null
+              : result.wslDistro === undefined
+                ? expectedWslDistro
+                : result.wslDistro
           )
         } catch (err) {
           if ((isMintedSessionId || preparedProvisionalExecutionContext) && effectiveSessionAppId) {
@@ -4228,7 +4232,11 @@ export function registerPtyHandlers(
           }
           runtime?.preparePtyExecutionContext?.(
             result.id,
-            args.connectionId ? null : (result.wslDistro ?? expectedWslDistro)
+            args.connectionId
+              ? null
+              : result.wslDistro === undefined
+                ? expectedWslDistro
+                : result.wslDistro
           )
           spawnTiming.mark('provider_spawn')
         } catch (err) {
diff --git a/src/main/providers/local-pty-provider.test.ts b/src/main/providers/local-pty-provider.test.ts
index 4e2b189deaa..fcd6235b101 100644
--- a/src/main/providers/local-pty-provider.test.ts
+++ b/src/main/providers/local-pty-provider.test.ts
@@ -228,11 +228,63 @@ describe('LocalPtyProvider', () => {
 
       const second = await provider.spawn({ cols: 120, rows: 40, sessionId: first.id })
 
-      expect(second).toEqual({ id: 'serve-session-1', pid: 12345, isReattach: true })
+      expect(second).toEqual({
+        id: 'serve-session-1',
+        pid: 12345,
+        wslDistro: null,
+        isReattach: true
+      })
       expect(mockProc.resize).toHaveBeenCalledWith(120, 40)
       expect(spawnMock).not.toHaveBeenCalled()
     })
 
+    it('keeps a native UNC session native on a conflicting WSL reattach', async () => {
+      Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' })
+      const first = await provider.spawn({
+        cols: 80,
+        rows: 24,
+        sessionId: 'native-session',
+        cwd: '\\\\server\\share\\repo',
+        shellOverride: 'powershell.exe'
+      })
+      spawnMock.mockClear()
+
+      const second = await provider.spawn({
+        cols: 120,
+        rows: 40,
+        sessionId: first.id,
+        shellOverride: 'wsl.exe',
+        terminalWindowsWslDistro: 'Ubuntu'
+      })
+
+      expect(first.wslDistro).toBeNull()
+      expect(second.wslDistro).toBeNull()
+      expect(spawnMock).not.toHaveBeenCalled()
+    })
+
+    it('keeps the first WSL distro on a conflicting distro reattach', async () => {
+      Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' })
+      const first = await provider.spawn({
+        cols: 80,
+        rows: 24,
+        sessionId: 'wsl-session',
+        cwd: '\\\\wsl.localhost\\Ubuntu\\home\\jin\\repo'
+      })
+      spawnMock.mockClear()
+
+      const second = await provider.spawn({
+        cols: 120,
+        rows: 40,
+        sessionId: first.id,
+        shellOverride: 'wsl.exe',
+        terminalWindowsWslDistro: 'Debian'
+      })
+
+      expect(first.wslDistro).toBe('Ubuntu')
+      expect(second.wslDistro).toBe('Ubuntu')
+      expect(spawnMock).not.toHaveBeenCalled()
+    })
+
     it('does not reattach numeric caller session ids that can collide after restart', async () => {
       const first = await provider.spawn({ cols: 80, rows: 24 })
       spawnMock.mockClear()
diff --git a/src/main/providers/local-pty-provider.ts b/src/main/providers/local-pty-provider.ts
index fef99e7d4f8..28c5586152c 100644
--- a/src/main/providers/local-pty-provider.ts
+++ b/src/main/providers/local-pty-provider.ts
@@ -103,6 +103,9 @@ const ptyAgentForegroundContextPaths = new Map<string, string[]>()
 const ptyLastRecognizedForeground = new Map<string, string>()
 const ptyTerminalHandle = new Map<string, string>()
 const ptyInitialCwd = new Map<string, string>()
+// Why: reattach requests carry current settings, not the live process's launch
+// context. Keep the first creator's WSL/native identity for the PTY incarnation.
+const ptyWslDistroById = new Map<string, string | null>()
 // Why: node-pty callbacks must be disposed before environment teardown, but
 // onExit separately owns physical process-exit proof during termination.
 const ptyDisposables = new Map<string, { dispose: () => void }[]>()
@@ -239,6 +242,7 @@ function clearPtyState(id: string): void {
   ptyLastRecognizedForeground.delete(id)
   ptyTerminalHandle.delete(id)
   ptyInitialCwd.delete(id)
+  ptyWslDistroById.delete(id)
   ptyLoadGeneration.delete(id)
   ptyTerminationMode.delete(id)
   ptyPhysicalExits.delete(id)
@@ -518,12 +522,18 @@ export class LocalPtyProvider implements IPtyProvider {
       }
       const existing = ptyProcesses.get(reattachId)
       if (existing) {
+        const existingWslDistro = ptyWslDistroById.get(reattachId)
         try {
           existing.resize(args.cols, args.rows)
         } catch {
           /* Existing PTY may reject resize during teardown; still return the live handle. */
         }
-        return { id: reattachId, pid: existing.pid, isReattach: true }
+        return {
+          id: reattachId,
+          pid: existing.pid,
+          ...(ptyWslDistroById.has(reattachId) ? { wslDistro: existingWslDistro ?? null } : {}),
+          isReattach: true
+        }
       }
     }
     const id = allocatePtyId(reattachId ?? undefined)
@@ -871,9 +881,15 @@ export class LocalPtyProvider implements IPtyProvider {
     }
 
     const proc = spawnResult.process
+    const spawnedShellIsWsl =
+      process.platform === 'win32' && pathWin32.basename(shellPath).toLowerCase() === 'wsl.exe'
+    const spawnedWslDistro = spawnedShellIsWsl ? (launchWslDistro ?? undefined) : null
     createPtyPhysicalExit(id)
     ptyProcesses.set(id, proc)
     ptyInitialCwd.set(id, cwd)
+    if (spawnedWslDistro !== undefined) {
+      ptyWslDistroById.set(id, spawnedWslDistro)
+    }
     // Why both signals: launchAgent is the caller's explicit intent and
     // survives command rewriting (e.g. auth env prefixes); recognition covers
     // callers that pass a bare agent command line without the flag.
@@ -1031,7 +1047,11 @@ export class LocalPtyProvider implements IPtyProvider {
     // briefly 0/undefined if node-pty hasn't observed the forked child yet.
     const rawPid = proc.pid
     const pid = typeof rawPid === 'number' && Number.isFinite(rawPid) && rawPid > 0 ? rawPid : null
-    return { id, pid }
+    return {
+      id,
+      pid,
+      ...(spawnedWslDistro !== undefined ? { wslDistro: spawnedWslDistro } : {})
+    }
   }
 
   // Local PTYs are always attached -- no-op. Remote providers use this to resubscribe.
diff --git a/src/main/providers/types.ts b/src/main/providers/types.ts
index 8b04b0b096a..36f58318c1d 100644
--- a/src/main/providers/types.ts
+++ b/src/main/providers/types.ts
@@ -111,8 +111,10 @@ export type PtySpawnResult = {
   pid?: number | null
   /** Minimal allowlisted launch ownership returned by daemon reattach. */
   launchAgent?: TuiAgent
-  /** Immutable local WSL execution context returned by a daemon session. */
-  wslDistro?: string
+  /** Immutable local WSL execution context returned by a daemon session.
+   *  Null authoritatively identifies a native session; undefined means the
+   *  provider cannot report the context (including older daemons). */
+  wslDistro?: string | null
   /** ANSI snapshot of the terminal screen, present when reattaching to an
    *  existing daemon session. Write this to xterm.js to restore visual state. */
   snapshot?: string

From 1ffe14986e5aa0fb6262d9fcffe9134ddf999091 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Sun, 19 Jul 2026 15:05:02 -0700
Subject: [PATCH 06/54] chore: keep provider types within lint limit

---
 src/main/providers/types.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/main/providers/types.ts b/src/main/providers/types.ts
index 36f58318c1d..082903f8558 100644
--- a/src/main/providers/types.ts
+++ b/src/main/providers/types.ts
@@ -111,9 +111,7 @@ export type PtySpawnResult = {
   pid?: number | null
   /** Minimal allowlisted launch ownership returned by daemon reattach. */
   launchAgent?: TuiAgent
-  /** Immutable local WSL execution context returned by a daemon session.
-   *  Null authoritatively identifies a native session; undefined means the
-   *  provider cannot report the context (including older daemons). */
+  /** Local WSL context: null is native; undefined is unavailable/legacy. */
   wslDistro?: string | null
   /** ANSI snapshot of the terminal screen, present when reattaching to an
    *  existing daemon session. Write this to xterm.js to restore visual state. */

From ca7b9fb04eb05014ad3d7929ec5d965dff510141 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Sun, 19 Jul 2026 15:10:41 -0700
Subject: [PATCH 07/54] refactor: split PTY spawn result contract

---
 src/main/providers/pty-spawn-result.ts | 59 ++++++++++++++++++++++++++
 src/main/providers/types.ts            | 58 +------------------------
 2 files changed, 61 insertions(+), 56 deletions(-)
 create mode 100644 src/main/providers/pty-spawn-result.ts

diff --git a/src/main/providers/pty-spawn-result.ts b/src/main/providers/pty-spawn-result.ts
new file mode 100644
index 00000000000..5a126e7e77d
--- /dev/null
+++ b/src/main/providers/pty-spawn-result.ts
@@ -0,0 +1,59 @@
+import type { TerminalOscLinkRange } from '../../shared/terminal-osc-link-ranges'
+import type { TuiAgent } from '../../shared/types'
+
+export type PtySpawnResult = {
+  /** App-facing PTY id. Remote providers must return globally routable ids,
+   *  not relay-local handles, because renderer/runtime IPC routes by this key. */
+  id: string
+  /** OS-level pid of the shell process, when available at spawn time.
+   *  Why: the memory collector needs this to walk each PTY's process
+   *  subtree. Daemon-backed providers return it from the RPC result;
+   *  local providers read it from node-pty. Null when the underlying
+   *  provider could not publish a pid (e.g., race during spawn). */
+  pid?: number | null
+  /** Minimal allowlisted launch ownership returned by daemon reattach. */
+  launchAgent?: TuiAgent
+  /** Local WSL context: null is native; undefined is unavailable/legacy. */
+  wslDistro?: string | null
+  /** ANSI snapshot of the terminal screen, present when reattaching to an
+   *  existing daemon session. Write this to xterm.js to restore visual state. */
+  snapshot?: string
+  /** Dimensions the snapshot was captured at. Resize xterm.js to these before
+   *  writing the snapshot so ANSI cursor positions land correctly. */
+  snapshotCols?: number
+  snapshotRows?: number
+  /** Provider sequence at the attach boundary. `reset` starts a new provider
+   *  generation; `continued` resumes the existing absolute domain. */
+  providerSequence?: {
+    value: number
+    generation: 'continued' | 'reset'
+  }
+  /** Kitty keyboard flags persisted in the daemon snapshot, threaded so the
+   *  re-seeded runtime emulator answers hidden `CSI ? u` with the real flags
+   *  (terminal-query-authority.md §kitty). Never replayed into a renderer
+   *  xterm — POST_REPLAY_REATTACH_RESET's kitty reset stays authoritative. */
+  snapshotKittyKeyboardFlags?: number
+  /** True when the spawn reattached to an existing daemon session. */
+  isReattach?: boolean
+  /** True when the reattached session uses the alternate screen buffer
+   *  (e.g., Codex CLI, vim). Normal-screen TUIs like Claude Code are false. */
+  isAlternateScreen?: boolean
+  /** Buffered output returned by relay pty.attach. Unlike snapshot, this is
+   *  incremental scrollback and must not clear the terminal before replay. */
+  replay?: string
+  /** True when the caller requested reattach (sessionId was provided) but the
+   *  relay PTY was gone (grace window elapsed). The renderer uses this to show
+   *  a brief "Session expired — new shell started" message. */
+  sessionExpired?: boolean
+  /** Present when cold-restoring from disk history after a daemon crash.
+   *  Contains the saved scrollback and CWD. The new shell spawns in the
+   *  saved CWD; the scrollback is written to xterm.js as read-only history. */
+  coldRestore?: {
+    scrollback: string
+    cwd: string
+    /** Optional for compatibility with restore payloads from older app code. */
+    cols?: number
+    rows?: number
+    oscLinks?: TerminalOscLinkRange[]
+  }
+}
diff --git a/src/main/providers/types.ts b/src/main/providers/types.ts
index 082903f8558..6941e4c3063 100644
--- a/src/main/providers/types.ts
+++ b/src/main/providers/types.ts
@@ -24,6 +24,7 @@ import type { StartupCommandDelivery } from '../../shared/codex-startup-delivery
 import type { TerminalOscLinkRange } from '../../shared/terminal-osc-link-ranges'
 import type { TerminalGitHubPRLink } from '../../shared/terminal-github-pr-link-detector'
 import type { GitProviderStatusOptions } from './git-provider-status-options'
+import type { PtySpawnResult } from './pty-spawn-result'
 
 // ─── PTY Provider ───────────────────────────────────────────────────
 
@@ -99,62 +100,7 @@ export type PtySpawnOptions = {
   terminalWindowsPowerShellImplementation?: 'auto' | 'powershell.exe' | 'pwsh.exe'
 }
 
-export type PtySpawnResult = {
-  /** App-facing PTY id. Remote providers must return globally routable ids,
-   *  not relay-local handles, because renderer/runtime IPC routes by this key. */
-  id: string
-  /** OS-level pid of the shell process, when available at spawn time.
-   *  Why: the memory collector needs this to walk each PTY's process
-   *  subtree. Daemon-backed providers return it from the RPC result;
-   *  local providers read it from node-pty. Null when the underlying
-   *  provider could not publish a pid (e.g., race during spawn). */
-  pid?: number | null
-  /** Minimal allowlisted launch ownership returned by daemon reattach. */
-  launchAgent?: TuiAgent
-  /** Local WSL context: null is native; undefined is unavailable/legacy. */
-  wslDistro?: string | null
-  /** ANSI snapshot of the terminal screen, present when reattaching to an
-   *  existing daemon session. Write this to xterm.js to restore visual state. */
-  snapshot?: string
-  /** Dimensions the snapshot was captured at. Resize xterm.js to these before
-   *  writing the snapshot so ANSI cursor positions land correctly. */
-  snapshotCols?: number
-  snapshotRows?: number
-  /** Provider sequence at the attach boundary. `reset` starts a new provider
-   *  generation; `continued` resumes the existing absolute domain. */
-  providerSequence?: {
-    value: number
-    generation: 'continued' | 'reset'
-  }
-  /** Kitty keyboard flags persisted in the daemon snapshot, threaded so the
-   *  re-seeded runtime emulator answers hidden `CSI ? u` with the real flags
-   *  (terminal-query-authority.md §kitty). Never replayed into a renderer
-   *  xterm — POST_REPLAY_REATTACH_RESET's kitty reset stays authoritative. */
-  snapshotKittyKeyboardFlags?: number
-  /** True when the spawn reattached to an existing daemon session. */
-  isReattach?: boolean
-  /** True when the reattached session uses the alternate screen buffer
-   *  (e.g., Codex CLI, vim). Normal-screen TUIs like Claude Code are false. */
-  isAlternateScreen?: boolean
-  /** Buffered output returned by relay pty.attach. Unlike snapshot, this is
-   *  incremental scrollback and must not clear the terminal before replay. */
-  replay?: string
-  /** True when the caller requested reattach (sessionId was provided) but the
-   *  relay PTY was gone (grace window elapsed). The renderer uses this to show
-   *  a brief "Session expired — new shell started" message. */
-  sessionExpired?: boolean
-  /** Present when cold-restoring from disk history after a daemon crash.
-   *  Contains the saved scrollback and CWD. The new shell spawns in the
-   *  saved CWD; the scrollback is written to xterm.js as read-only history. */
-  coldRestore?: {
-    scrollback: string
-    cwd: string
-    /** Optional for compatibility with restore payloads from older app code. */
-    cols?: number
-    rows?: number
-    oscLinks?: TerminalOscLinkRange[]
-  }
-}
+export type { PtySpawnResult }
 
 export type PtyProcessInfo = {
   id: string

From d7dc7e9f252f7fb975f3ec5f574e8253a8612897 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Sun, 19 Jul 2026 15:24:22 -0700
Subject: [PATCH 08/54] test: expect native context from local PTY

---
 src/main/ipc/pty.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index 984bd045431..c8843bd5076 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -10746,7 +10746,7 @@ describe('registerPtyHandlers', () => {
         worktreeId: 'repo-1::/tmp'
       })
 
-      expect(result).toEqual({ id: expect.any(String), pid: 12345 })
+      expect(result).toEqual({ id: expect.any(String), pid: 12345, wslDistro: null })
       expect(spawnMock).toHaveBeenCalledTimes(1)
       expect(spawnMock).toHaveBeenCalledWith(
         '/bin/zsh',

From c5d40565af825848ad6ec7c20ef47c17b86aa054 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Sun, 19 Jul 2026 16:10:32 -0700
Subject: [PATCH 09/54] Clarify Orca Mobile pairing connection paths (#9425)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Restructure mobile pairing setup into a clear stepped layout

* Rework mobile pairing UI: radio-style path selector with sign-in gate fo

* fix(mobile): resolve mobile-pairing review findings

Applies the code-review findings for the reworked pairing UI:

- Clear a displayed Relay QR on sign-out in both MobilePage and MobilePane
  (the rework dropped the wasSignedInRef watcher, leaving a stale Relay QR
  next to a "sign in required" prompt). Anywhere stays selected; the QR
  re-mints as local-only. [#1, #3]
- Extract useMobilePairingConnectionMode so both panes resolve the saved
  preference identically instead of duplicating the state + resync effect. [#6]
- Delete ~24 i18n keys the rework left unreferenced; sync locale catalogs
  to parity. [#4]
- Give the connection-path radiogroup roving tabindex + arrow-key nav and
  document why it diverges from SettingsSegmentedControl. [#7]
- Add MobilePane.test.tsx (previously untested safety logic) and a
  MobilePage saved-local-only restore test. [#2, #5]

Verified: 22 targeted tests pass, typecheck + oxlint clean, localization
catalog/coverage and max-lines ratchet green.

* fix(mobile): resolve adversarial-review findings for pairing UI

Address accepted findings from the mobile pairing UI rework:

- MobilePane: add a request-generation epoch so a late getPairingQR
  response can't paint a stale Relay QR after sign-out, a mode switch,
  or an address change; arm rotation when discarding a pending mint.
- MobilePage: on sign-in, upgrade a signed-out local-only fallback QR to
  Relay (invalidate + rotate-regenerate); handle null->connected too.
- Extract useMobilePairingQrInvalidation so both sign-in/out edges and
  cross-window preference syncs invalidate/re-mint the QR consistently.
- MobilePane: clear + rotate the QR when the selected address changes
  (manual pick or refresh-driven) so it can't encode the old endpoint.
- MobilePairingConnectionOptions: guard the Sign in CTA on configured;
  show an Unavailable panel on unconfigured builds instead of dead CTA.
- Drop the duplicate sign-in helper from MobilePairingSetupSection.
- Remove dead i18n keys (title, recommended, signInToGenerate) and add
  relayUnavailable across all locale catalogs.
- Add tests: deferred sign-out/mode-switch races, sign-in upgrade,
  cross-window sync, unconfigured build, arrow-key radiogroup.

TODO left for the relay-label-honesty finding: getPairingQR does not
expose the actually-encoded mode when an automatic offer degrades to
local-only, so the mismatch can't be surfaced without a new return field.

* fix(mobile): resolve relay-pairing deep-review regressions

- MobilePane: invalidatePairing now clears loading so a superseded
  mid-flight generate can't wedge Generate disabled forever
- MobilePage: stop auto-minting a local-only QR under the Relay label
  when signed out with Anywhere; gate Step 2 auto-generate and the
  Generate button on a shared canMintMobilePairingOffer helper, align
  with Settings, clear QR + loading on sign-out, mint Relay on sign-in
- qr-invalidation: clear pairQrDataUrl (and loading) on every
  invalidation path so a stale QR can't stay scannable during rotation
- Strengthen MobilePane/MobilePage tests for the aligned behavior and
  stuck-loading coverage
- Translate relayUnavailable in es/ja/ko/zh

Co-authored-by: Orca <help@stably.ai>

* fix(mobile): refuse to mint QR when signed-out with Anywhere selected

Replace silent degradation of Anywhere mode to local-only QR with explicit
refusal. Add canMintMobilePairingOffer guard across all mint paths (address
change, network invalidation, connection mode switch). This ensures the UI
honestly encodes the selected pairing path. Improve keyboard focus visibility
on the path selector by adding a persistent focus ring.

* fix(mobile): detect and flag Relay provisioning degradation

When Relay provisioning fails during automatic (Anywhere) pairing offer creation, the offer silently degrades to local-only. This confuses users who selected Anywhere expecting cellular capability.

Add connectionMode field to the pairing offer result to expose what the offer actually encodes. The UI now flags degradation when the offered mode mismatches the user's selection.

Also move credential rotation logic to the main process: rotate when requested mode differs from the pending token's encoded mode. This ensures QR codes displayed under an old policy can't pair under a new one, and windows reminting after preference sync converge on one token.

Rename MobileRelayBetaAvailability → MobileRelayBetaNotice.

* test(mobile): verify pairing codes don't flash during Relay mint

Assert that the pairing QR and URL remain hidden while the Relay mint is
pending, preventing confusing intermediate states when signing in unlocks
Relay.

---------

Co-authored-by: Orca <help@stably.ai>
---
 src/main/ipc/mobile.test.ts                   |  10 +-
 src/main/ipc/mobile.ts                        |   6 +-
 src/main/runtime/runtime-rpc.test.ts          | 115 ++++++
 src/main/runtime/runtime-rpc.ts               |  36 +-
 src/preload/api-types.ts                      |   3 +
 src/preload/index.ts                          |   1 +
 .../src/components/mobile/MobileHero.test.tsx |  26 +-
 .../src/components/mobile/MobileHero.tsx      |  26 +-
 .../src/components/mobile/MobilePage.test.tsx | 164 ++++++--
 .../src/components/mobile/MobilePage.tsx      | 165 ++++----
 .../components/mobile/MobilePageContent.tsx   |   6 +
 .../use-mobile-pairing-connection-mode.ts     |  26 ++
 .../mobile/use-mobile-pairing-generation.ts   | 134 +++++++
 .../use-mobile-pairing-qr-invalidation.ts     | 112 ++++++
 .../MobilePairingConnectionOptions.test.tsx   | 132 ++++---
 .../MobilePairingConnectionOptions.tsx        | 354 +++++++++--------
 .../MobilePairingSetupSection.test.tsx        |  45 ++-
 .../settings/MobilePairingSetupSection.tsx    | 154 ++++----
 .../components/settings/MobilePane.test.tsx   | 373 ++++++++++++++++--
 .../src/components/settings/MobilePane.tsx    | 178 +++++++--
 .../settings/MobileRelayBetaAvailability.tsx  |  40 --
 .../settings/MobileRelayBetaNotice.tsx        |  12 +
 .../settings/MobileSettingsPane.tsx           |  61 +--
 .../settings/mobile-settings-search.ts        |   8 +
 src/renderer/src/i18n/locales/en.json         |  50 ++-
 src/renderer/src/i18n/locales/es.json         |  46 ++-
 src/renderer/src/i18n/locales/ja.json         |  46 ++-
 src/renderer/src/i18n/locales/ko.json         |  46 ++-
 src/renderer/src/i18n/locales/zh.json         |  50 ++-
 src/shared/constants.ts                       |   3 +
 .../mobile-pairing-connection-mode.test.ts    |  42 ++
 src/shared/mobile-pairing-connection-mode.ts  |  40 ++
 src/shared/types.ts                           |   4 +
 33 files changed, 1839 insertions(+), 675 deletions(-)
 create mode 100644 src/renderer/src/components/mobile/use-mobile-pairing-connection-mode.ts
 create mode 100644 src/renderer/src/components/mobile/use-mobile-pairing-generation.ts
 create mode 100644 src/renderer/src/components/mobile/use-mobile-pairing-qr-invalidation.ts
 delete mode 100644 src/renderer/src/components/settings/MobileRelayBetaAvailability.tsx
 create mode 100644 src/renderer/src/components/settings/MobileRelayBetaNotice.tsx
 create mode 100644 src/shared/mobile-pairing-connection-mode.test.ts

diff --git a/src/main/ipc/mobile.test.ts b/src/main/ipc/mobile.test.ts
index 49a39686a28..ff53b23374e 100644
--- a/src/main/ipc/mobile.test.ts
+++ b/src/main/ipc/mobile.test.ts
@@ -68,7 +68,8 @@ describe('registerMobileHandlers', () => {
       available: true,
       pairingUrl: 'orca://pair#mobile',
       endpoint: 'ws://100.102.47.57:6768',
-      deviceId: 'mobile-1'
+      deviceId: 'mobile-1',
+      connectionMode: 'automatic'
     })
     const rpcServer = { createMobilePairingOffer }
 
@@ -78,7 +79,9 @@ describe('registerMobileHandlers', () => {
       available: true,
       pairingUrl: 'orca://pair#mobile',
       endpoint: 'ws://100.102.47.57:6768',
-      deviceId: 'mobile-1'
+      deviceId: 'mobile-1',
+      // The encoded mode passes through so the UI can flag a degraded mint.
+      connectionMode: 'automatic'
     })
 
     expect(createMobilePairingOffer).toHaveBeenCalledWith({
@@ -97,7 +100,8 @@ describe('registerMobileHandlers', () => {
       available: true,
       pairingUrl: 'orca://pair#local',
       endpoint: 'ws://192.168.1.24:6768',
-      deviceId: 'mobile-local'
+      deviceId: 'mobile-local',
+      connectionMode: 'local-only'
     })
 
     registerMobileHandlers({ createMobilePairingOffer } as never)
diff --git a/src/main/ipc/mobile.ts b/src/main/ipc/mobile.ts
index 4cc09bc0b51..46c83f1234a 100644
--- a/src/main/ipc/mobile.ts
+++ b/src/main/ipc/mobile.ts
@@ -125,7 +125,11 @@ export function registerMobileHandlers(
         qrDataUrl,
         pairingUrl: offer.pairingUrl,
         endpoint: offer.endpoint,
-        deviceId: offer.deviceId
+        deviceId: offer.deviceId,
+        // Why: an automatic request can degrade to a local-only offer when
+        // Relay provisioning fails; the UI needs the encoded mode to avoid
+        // labeling a LAN-only code as Relay.
+        connectionMode: offer.connectionMode
       }
     }
   )
diff --git a/src/main/runtime/runtime-rpc.test.ts b/src/main/runtime/runtime-rpc.test.ts
index 1b0a31dd2b0..7744bbe67eb 100644
--- a/src/main/runtime/runtime-rpc.test.ts
+++ b/src/main/runtime/runtime-rpc.test.ts
@@ -548,6 +548,7 @@ describe('OrcaRuntimeRpcServer', () => {
         expect.objectContaining({ endpoint: offer.endpoint, scope: 'mobile', relay })
       )
       expect(parsed).not.toHaveProperty('endpoints')
+      expect(offer.connectionMode).toBe('automatic')
       expect(server.getDeviceRegistry()?.getDevice(offer.deviceId)?.relayBinding).toEqual({
         relayHostId: relay.relayHostId,
         relayDeviceId: offer.deviceId,
@@ -585,6 +586,9 @@ describe('OrcaRuntimeRpcServer', () => {
         scope: 'mobile'
       })
       expect(parsePairingCode(offer.pairingUrl)).not.toHaveProperty('relay')
+      // Why: the result reports what the offer actually encodes so the UI can
+      // flag the degraded mint instead of labeling it as Relay.
+      expect(offer.connectionMode).toBe('local-only')
     } finally {
       await server.stop()
     }
@@ -618,6 +622,7 @@ describe('OrcaRuntimeRpcServer', () => {
       }
       expect(parsePairingCode(offer.pairingUrl)).not.toHaveProperty('relay')
       expect(createPairingRelay).not.toHaveBeenCalled()
+      expect(offer.connectionMode).toBe('local-only')
       expect(server.getDeviceRegistry()?.getMobilePairingConnectionMode(offer.deviceId)).toBe(
         'local-only'
       )
@@ -715,6 +720,116 @@ describe('OrcaRuntimeRpcServer', () => {
     }
   })
 
+  it('rotates a pending local-only code when switching it back to Anywhere', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const server = new OrcaRuntimeRpcServer({
+      runtime: new OrcaRuntimeService(),
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0
+    })
+    server.setMobileRelayPairingProvider({
+      createPairingRelay: async (relayDeviceId) => ({
+        relay: {
+          v: 1,
+          directorUrl: 'https://relay.example.com',
+          cellUrl: 'https://cell.example.com',
+          assignmentEpoch: 7,
+          relayHostId: 'AbCdEf0123_-xyZ9',
+          inviteToken: 'A'.repeat(43),
+          inviteExpiresAt: Date.now() + 60_000,
+          e2eeFraming: 2
+        },
+        binding: {
+          relayHostId: 'AbCdEf0123_-xyZ9',
+          relayDeviceId,
+          ownerIdentityKey: 'user\0profile\0org'
+        }
+      }),
+      onDeviceRevokeQueued: vi.fn(),
+      getEndpoints: vi.fn(),
+      provisionRelay: vi.fn()
+    })
+
+    await server.start()
+    try {
+      const local = await server.createMobilePairingOffer({
+        address: '100.64.1.20',
+        connectionMode: 'local-only'
+      })
+      expect(local.available).toBe(true)
+      if (!local.available) {
+        throw new Error('WebSocket pairing unavailable')
+      }
+      const anywhere = await server.createMobilePairingOffer({ address: '100.64.1.20' })
+      expect(anywhere.available).toBe(true)
+      if (!anywhere.available) {
+        throw new Error('WebSocket pairing unavailable')
+      }
+      // Why: a QR displayed under the local-only pledge must not become an
+      // anywhere-capable credential; the policy switch mints a fresh token.
+      expect(anywhere.deviceId).not.toBe(local.deviceId)
+      expect(server.getDeviceRegistry()?.getDevice(local.deviceId)).toBeNull()
+      expect(anywhere.connectionMode).toBe('automatic')
+      expect(parsePairingCode(anywhere.pairingUrl)).toHaveProperty('relay')
+    } finally {
+      await server.stop()
+    }
+  })
+
+  it('reuses the pending token when the requested mode is unchanged', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const server = new OrcaRuntimeRpcServer({
+      runtime: new OrcaRuntimeService(),
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0
+    })
+    const onDeviceRevokeQueued = vi.fn()
+    server.setMobileRelayPairingProvider({
+      createPairingRelay: async (relayDeviceId) => ({
+        relay: {
+          v: 1,
+          directorUrl: 'https://relay.example.com',
+          cellUrl: 'https://cell.example.com',
+          assignmentEpoch: 7,
+          relayHostId: 'AbCdEf0123_-xyZ9',
+          inviteToken: 'A'.repeat(43),
+          inviteExpiresAt: Date.now() + 60_000,
+          e2eeFraming: 2
+        },
+        binding: {
+          relayHostId: 'AbCdEf0123_-xyZ9',
+          relayDeviceId,
+          ownerIdentityKey: 'user\0profile\0org'
+        }
+      }),
+      onDeviceRevokeQueued,
+      getEndpoints: vi.fn(),
+      provisionRelay: vi.fn()
+    })
+
+    await server.start()
+    try {
+      const first = await server.createMobilePairingOffer({ address: '100.64.1.20' })
+      expect(first.available).toBe(true)
+      if (!first.available) {
+        throw new Error('WebSocket pairing unavailable')
+      }
+      // Why: a same-mode remint (e.g. two windows converging after a
+      // preference sync) must not race rotations off each other's token.
+      const second = await server.createMobilePairingOffer({ address: '100.64.1.20' })
+      expect(second.available).toBe(true)
+      if (!second.available) {
+        throw new Error('WebSocket pairing unavailable')
+      }
+      expect(second.deviceId).toBe(first.deviceId)
+      expect(onDeviceRevokeQueued).not.toHaveBeenCalled()
+    } finally {
+      await server.stop()
+    }
+  })
+
   it('records cloud cleanup before rotating or deleting the local mobile credential', async () => {
     const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
     const server = new OrcaRuntimeRpcServer({
diff --git a/src/main/runtime/runtime-rpc.ts b/src/main/runtime/runtime-rpc.ts
index 5c7c44574d4..da0b9a0f626 100644
--- a/src/main/runtime/runtime-rpc.ts
+++ b/src/main/runtime/runtime-rpc.ts
@@ -636,14 +636,31 @@ export class OrcaRuntimeRpcServer {
     connectionMode?: MobilePairingConnectionMode
     name?: string
     rotate?: boolean
-  }): Promise<ReturnType<OrcaRuntimeRpcServer['createPairingOffer']>> {
+  }): Promise<
+    | { available: false }
+    | {
+        available: true
+        pairingUrl: string
+        endpoint: string
+        deviceId: string
+        webClientUrl: string | null
+        /** Mode the returned offer actually encodes — 'local-only' when an
+         *  automatic request degraded because Relay could not be attached. */
+        connectionMode: MobilePairingConnectionMode
+      }
+  > {
     // Why: the renderer is outside the trust boundary; only the explicit
     // local-only value may suppress Relay provisioning.
     const connectionMode = args.connectionMode === 'local-only' ? 'local-only' : 'automatic'
     const pending = this.deviceRegistry?.getPendingDevice('mobile')
-    const switchingPendingToLocal =
-      connectionMode === 'local-only' && pending?.relayBinding !== undefined
-    if (args.rotate || switchingPendingToLocal) {
+    // Why: an offer's connection policy is part of its credential. Rotating on
+    // any policy switch here (not in the renderer) means a QR displayed under
+    // the old policy cannot pair under the new one, and windows reminting after
+    // a preference sync converge on one token instead of racing rotations.
+    const switchingPendingMode =
+      pending != null &&
+      this.deviceRegistry?.getMobilePairingConnectionMode(pending.deviceId) !== connectionMode
+    if (args.rotate || switchingPendingMode) {
       if (pending?.relayBinding) {
         // Why: the durable cloud revoke is recorded before rotating the local
         // token, so a previously displayed relay invite cannot outlive the QR.
@@ -652,7 +669,7 @@ export class OrcaRuntimeRpcServer {
     }
     const direct = this.createPairingOffer({
       ...args,
-      rotate: args.rotate || switchingPendingToLocal,
+      rotate: args.rotate || switchingPendingMode,
       scope: 'mobile'
     })
     if (!direct.available) {
@@ -660,21 +677,22 @@ export class OrcaRuntimeRpcServer {
     }
     this.deviceRegistry?.setMobilePairingConnectionMode(direct.deviceId, connectionMode)
     if (connectionMode === 'local-only' || !this.mobileRelayPairingProvider) {
-      return direct
+      return { ...direct, connectionMode: 'local-only' }
     }
     const device = this.deviceRegistry?.getDevice(direct.deviceId)
     const publicKeyB64 = this.getE2EEPublicKey()
     if (!device || !publicKeyB64) {
-      return direct
+      return { ...direct, connectionMode: 'local-only' }
     }
     try {
       const relayPairing = await this.mobileRelayPairingProvider.createPairingRelay(device.deviceId)
       if (!this.deviceRegistry?.setRelayBinding(device.deviceId, relayPairing.binding)) {
-        return direct
+        return { ...direct, connectionMode: 'local-only' }
       }
       this.mobileRelayPairingProvider.onDemandStateChanged?.()
       return {
         ...direct,
+        connectionMode: 'automatic',
         pairingUrl: encodePairingOffer({
           v: PAIRING_OFFER_VERSION,
           endpoint: direct.endpoint,
@@ -687,7 +705,7 @@ export class OrcaRuntimeRpcServer {
     } catch {
       // Why: relay is additive. A transient auth/director/control outage must
       // still yield the valid LAN/Tailscale pairing offer.
-      return direct
+      return { ...direct, connectionMode: 'local-only' }
     }
   }
 
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 8fbe1a6ac7a..e5aa341101c 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -3255,6 +3255,9 @@ export type PreloadApi = {
           pairingUrl: string
           endpoint: string
           deviceId: string
+          /** Mode the QR actually encodes; 'local-only' when an automatic
+           *  request degraded because Relay could not be attached. */
+          connectionMode: MobilePairingConnectionMode
         }
     >
     getWindowsFirewallStatus: (args?: { address?: string }) => Promise<
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 59097c34f72..237090a4402 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -4342,6 +4342,7 @@ const api = {
           pairingUrl: string
           endpoint: string
           deviceId: string
+          connectionMode: MobilePairingConnectionMode
         }
     > => ipcRenderer.invoke('mobile:getPairingQR', args),
 
diff --git a/src/renderer/src/components/mobile/MobileHero.test.tsx b/src/renderer/src/components/mobile/MobileHero.test.tsx
index 4026b03b3b3..04fff8c9092 100644
--- a/src/renderer/src/components/mobile/MobileHero.test.tsx
+++ b/src/renderer/src/components/mobile/MobileHero.test.tsx
@@ -57,7 +57,10 @@ describe('HeroFlow height', () => {
     }
   })
 
-  function renderFlow(stepIdx: StepIndex) {
+  function renderFlow(
+    stepIdx: StepIndex,
+    overrides: Partial<React.ComponentProps<typeof HeroFlow>> = {}
+  ) {
     return render(
       <HeroFlow
         stepIdx={stepIdx}
@@ -71,10 +74,12 @@ describe('HeroFlow height', () => {
         onCopyInstallUrl={vi.fn()}
         pairQrDataUrl={null}
         pairingUrl={null}
+        relayDegraded={false}
         pairLoading={false}
         connectionMode="automatic"
         onConnectionModeChange={vi.fn()}
         onRegeneratePairing={vi.fn()}
+        canGeneratePairing
         onCopyPairingCode={vi.fn()}
         networkInterfaces={[]}
         selectedAddress={undefined}
@@ -83,6 +88,7 @@ describe('HeroFlow height', () => {
         refreshingNetworkInterfaces={false}
         onBack={vi.fn()}
         onContinue={vi.fn()}
+        {...overrides}
       />
     )
   }
@@ -106,10 +112,12 @@ describe('HeroFlow height', () => {
         onCopyInstallUrl={vi.fn()}
         pairQrDataUrl={null}
         pairingUrl={null}
+        relayDegraded={false}
         pairLoading={false}
         connectionMode="automatic"
         onConnectionModeChange={vi.fn()}
         onRegeneratePairing={vi.fn()}
+        canGeneratePairing
         onCopyPairingCode={vi.fn()}
         networkInterfaces={[]}
         selectedAddress={undefined}
@@ -124,4 +132,20 @@ describe('HeroFlow height', () => {
     expect(viewport).toHaveStyle({ height: '520px' })
     expect(screen.getByText('Step 1 of 2').closest('.mp-flow-screen')).toHaveAttribute('inert')
   })
+
+  it('flags a degraded Anywhere code and always shows the Relay beta note', () => {
+    renderFlow(1, {
+      pairQrDataUrl: 'data:image/png;base64,qr',
+      relayDegraded: true
+    })
+    expect(screen.getByTestId('relay-degraded-notice')).toHaveTextContent(
+      'only works on your local network'
+    )
+    expect(screen.getByText('Orca Relay is in beta.')).toBeInTheDocument()
+  })
+
+  it('hides the degradation notice when the code encodes what was selected', () => {
+    renderFlow(1, { pairQrDataUrl: 'data:image/png;base64,qr' })
+    expect(screen.queryByTestId('relay-degraded-notice')).not.toBeInTheDocument()
+  })
 })
diff --git a/src/renderer/src/components/mobile/MobileHero.tsx b/src/renderer/src/components/mobile/MobileHero.tsx
index aace116e811..335a691a020 100644
--- a/src/renderer/src/components/mobile/MobileHero.tsx
+++ b/src/renderer/src/components/mobile/MobileHero.tsx
@@ -1,10 +1,11 @@
 import { useLayoutEffect, useRef, useState } from 'react'
-import { ArrowLeft, ArrowRight, Copy, RefreshCw } from 'lucide-react'
+import { ArrowLeft, ArrowRight, CircleAlert, Copy, RefreshCw } from 'lucide-react'
 import { cn } from '../../lib/utils'
 import type { MobileNetworkInterface } from '../settings/mobile-network-interface-selection'
 import { AndroidLogo, IosBrandIcon } from './MobileBrandIcons'
 import { NetworkInterfacePicker } from './NetworkInterfacePicker'
 import { MobilePairingConnectionOptions } from '../settings/MobilePairingConnectionOptions'
+import { MobileRelayBetaNotice } from '../settings/MobileRelayBetaNotice'
 import { getChannelTagline, type InstallCopy, type IosChannel } from './mobile-platform-copy'
 import { WindowsFirewallNotice } from './WindowsFirewallNotice'
 import type { MobilePairingConnectionMode } from '../../../../shared/mobile-pairing-connection-mode'
@@ -39,10 +40,13 @@ type HeroFlowProps = {
   onCopyInstallUrl: () => void
   pairQrDataUrl: string | null
   pairingUrl: string | null
+  /** True when the shown QR degraded to local-only under an Anywhere selection. */
+  relayDegraded: boolean
   pairLoading: boolean
   connectionMode: MobilePairingConnectionMode
   onConnectionModeChange: (mode: MobilePairingConnectionMode) => void
   onRegeneratePairing: () => void
+  canGeneratePairing: boolean
   onCopyPairingCode: () => void
   networkInterfaces: readonly MobileNetworkInterface[]
   selectedAddress: string | undefined
@@ -66,10 +70,12 @@ export function HeroFlow({
   onCopyInstallUrl,
   pairQrDataUrl,
   pairingUrl,
+  relayDegraded,
   pairLoading,
   connectionMode,
   onConnectionModeChange,
   onRegeneratePairing,
+  canGeneratePairing,
   onCopyPairingCode,
   networkInterfaces,
   selectedAddress,
@@ -243,6 +249,7 @@ export function HeroFlow({
                 onChange={onConnectionModeChange}
                 compact
               />
+              <MobileRelayBetaNotice className="mt-1.5" />
             </div>
             <div className="mp-qr-stack mp-pairing-qr">
               <div
@@ -270,7 +277,10 @@ export function HeroFlow({
                 type="button"
                 className="mp-link-under"
                 onClick={onRegeneratePairing}
-                disabled={pairLoading}
+                // Why: signed-out Anywhere can't serve Relay; disabling avoids
+                // minting a local-only QR under the Relay label. Sign in or pick
+                // Local network (shown in the path options above) to enable it.
+                disabled={pairLoading || !canGeneratePairing}
               >
                 {pairLoading
                   ? translate('auto.components.mobile.MobileHero.65b3f2e8bc', 'Generating…')
@@ -278,6 +288,18 @@ export function HeroFlow({
                     ? translate('auto.components.mobile.MobileHero.e59a252eca', 'Regenerate code')
                     : translate('auto.components.mobile.MobileHero.a6cffbbb0b', 'Generate code')}
               </button>
+              {relayDegraded ? (
+                <p
+                  className="flex items-start gap-1.5 text-xs text-muted-foreground"
+                  data-testid="relay-degraded-notice"
+                >
+                  <CircleAlert className="mt-0.5 size-3.5 shrink-0" aria-hidden />
+                  {translate(
+                    'auto.components.mobile.MobileHero.relayDegradedNotice',
+                    'Relay couldn’t be reached — this code only works on your local network.'
+                  )}
+                </p>
+              ) : null}
             </div>
             <div className="mp-pairing-controls">
               <div className="mp-network-row">
diff --git a/src/renderer/src/components/mobile/MobilePage.test.tsx b/src/renderer/src/components/mobile/MobilePage.test.tsx
index 2f56e664cb3..23d9feb286b 100644
--- a/src/renderer/src/components/mobile/MobilePage.test.tsx
+++ b/src/renderer/src/components/mobile/MobilePage.test.tsx
@@ -10,7 +10,7 @@ import type { MobilePairingConnectionMode } from '../../../../shared/mobile-pair
 type StoreState = {
   closeMobilePage: () => void
   orcaProfileAuthStatus: { state: 'connected' | 'local' }
-  settings: { showMobileButton: boolean }
+  settings: { showMobileButton: boolean; mobilePairingConnectionMode?: MobilePairingConnectionMode }
   updateSettings: () => Promise<void>
 }
 
@@ -39,8 +39,10 @@ vi.mock('../settings/mobile-pairing-device-polling', () => ({
 vi.mock('./MobilePageContent', () => ({
   MobilePageContent: (props: {
     connectionMode: MobilePairingConnectionMode
+    canGeneratePairing: boolean
     enterFlow: () => void
     handleConnectionModeChange: (mode: MobilePairingConnectionMode) => void
+    handleAddressChange: (address: string) => void
     handleContinue: () => void
     pairQrDataUrl: string | null
     pairingUrl: string | null
@@ -51,6 +53,7 @@ vi.mock('./MobilePageContent', () => ({
       <span data-testid="stage">{props.stage ?? 'loading'}</span>
       <span data-testid="step">{props.stepIdx}</span>
       <span data-testid="mode">{props.connectionMode}</span>
+      <span data-testid="can-generate">{String(props.canGeneratePairing)}</span>
       <span data-testid="pairing-qr">{props.pairQrDataUrl ?? 'none'}</span>
       <span data-testid="pairing-url">{props.pairingUrl ?? 'none'}</span>
       <button type="button" onClick={props.enterFlow}>
@@ -60,10 +63,13 @@ vi.mock('./MobilePageContent', () => ({
         Continue
       </button>
       <button type="button" onClick={() => props.handleConnectionModeChange('automatic')}>
-        Anywhere
+        Orca Relay
       </button>
       <button type="button" onClick={() => props.handleConnectionModeChange('local-only')}>
-        Local only
+        Local network
+      </button>
+      <button type="button" onClick={() => props.handleAddressChange('10.0.0.2')}>
+        Change address
       </button>
     </div>
   )
@@ -110,14 +116,130 @@ describe('MobilePage pairing connection mode', () => {
     await user.click(screen.getByRole('button', { name: 'Continue' }))
   }
 
-  it('defaults signed-in pairing to local-only and rotates when Relay is selected', async () => {
+  it('defaults signed-in pairing to Anywhere and remints when same-network is selected', async () => {
     const user = userEvent.setup()
     await openPairingStep()
 
+    await waitFor(() => expect(getPairingQR).toHaveBeenCalledWith({ connectionMode: 'automatic' }))
+    await waitFor(() => expect(screen.getByTestId('pairing-qr')).toHaveTextContent('base64,qr'))
+    expect(screen.getByTestId('mode')).toHaveTextContent('automatic')
+
+    let resolveRotatedLocalQr: ((value: Record<string, unknown>) => void) | undefined
+    getPairingQR.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveRotatedLocalQr = resolve
+        })
+    )
+    await user.click(screen.getByRole('button', { name: 'Local network' }))
+    // No rotate flag: the main process rotates exactly once on the policy
+    // mismatch, so concurrent windows converge on the same fresh token.
+    await waitFor(() =>
+      expect(getPairingQR).toHaveBeenLastCalledWith({
+        connectionMode: 'local-only'
+      })
+    )
+    expect(screen.getByTestId('mode')).toHaveTextContent('local-only')
+    // The prior Relay QR clears immediately so the old policy's code is never
+    // shown while the reminted local-only offer is still pending.
+    expect(screen.getByTestId('pairing-qr')).toHaveTextContent('none')
+    expect(screen.getByTestId('pairing-url')).toHaveTextContent('none')
+    expect(mocks.storeState.updateSettings).toHaveBeenCalledWith({
+      mobilePairingConnectionMode: 'local-only'
+    })
+
+    resolveRotatedLocalQr?.({
+      available: true,
+      qrDataUrl: 'data:image/png;base64,local-qr',
+      pairingUrl: 'orca://pair#local'
+    })
+    await waitFor(() => expect(screen.getByTestId('pairing-qr')).toHaveTextContent('local-qr'))
+  })
+
+  it('restores a saved local-only preference without user interaction', async () => {
+    mocks.storeState.settings = {
+      showMobileButton: true,
+      mobilePairingConnectionMode: 'local-only'
+    }
+    await openPairingStep()
+
+    await waitFor(() => expect(getPairingQR).toHaveBeenCalledWith({ connectionMode: 'local-only' }))
+    expect(screen.getByTestId('mode')).toHaveTextContent('local-only')
+  })
+
+  it('does not auto-mint any QR when signed out with Anywhere selected', async () => {
+    mocks.storeState.orcaProfileAuthStatus = { state: 'local' }
+    await openPairingStep()
+
+    // Aligned with Settings: signed-out Anywhere cannot serve Relay, so we mint
+    // nothing rather than a scannable local-only QR under the Relay label.
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(getPairingQR).not.toHaveBeenCalled()
+    expect(screen.getByTestId('mode')).toHaveTextContent('automatic')
+    expect(screen.getByTestId('pairing-qr')).toHaveTextContent('none')
+    expect(screen.getByTestId('can-generate')).toHaveTextContent('false')
+  })
+
+  it('mints a local-only QR when switching to Local network while signed out', async () => {
+    mocks.storeState.orcaProfileAuthStatus = { state: 'local' }
+    const user = userEvent.setup()
+    await openPairingStep()
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(getPairingQR).not.toHaveBeenCalled()
+
+    // Picking Local network is an honest local-only path, so a QR mints.
+    await user.click(screen.getByRole('button', { name: 'Local network' }))
     await waitFor(() => expect(getPairingQR).toHaveBeenCalledWith({ connectionMode: 'local-only' }))
     await waitFor(() => expect(screen.getByTestId('pairing-qr')).toHaveTextContent('base64,qr'))
     expect(screen.getByTestId('mode')).toHaveTextContent('local-only')
+  })
 
+  it('does not remint when switching from Local to Anywhere while signed out', async () => {
+    mocks.storeState.orcaProfileAuthStatus = { state: 'local' }
+    const user = userEvent.setup()
+    await openPairingStep()
+
+    await user.click(screen.getByRole('button', { name: 'Local network' }))
+    await waitFor(() => expect(screen.getByTestId('pairing-qr')).toHaveTextContent('base64,qr'))
+    getPairingQR.mockClear()
+
+    // Switching back to Orca Relay must clear the local QR, not remint a
+    // local-only code under the Relay label.
+    await user.click(screen.getByRole('button', { name: 'Orca Relay' }))
+    await waitFor(() => expect(screen.getByTestId('mode')).toHaveTextContent('automatic'))
+    await waitFor(() => expect(screen.getByTestId('pairing-qr')).toHaveTextContent('none'))
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(getPairingQR).not.toHaveBeenCalled()
+    expect(screen.getByTestId('can-generate')).toHaveTextContent('false')
+  })
+
+  it('does not mint on address change while signed out with Anywhere selected', async () => {
+    mocks.storeState.orcaProfileAuthStatus = { state: 'local' }
+    const user = userEvent.setup()
+    await openPairingStep()
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(getPairingQR).not.toHaveBeenCalled()
+
+    await user.click(screen.getByRole('button', { name: 'Change address' }))
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(getPairingQR).not.toHaveBeenCalled()
+    expect(screen.getByTestId('pairing-qr')).toHaveTextContent('none')
+  })
+
+  it('mints a Relay QR when signing in with Anywhere selected', async () => {
+    mocks.storeState.orcaProfileAuthStatus = { state: 'local' }
+    const user = userEvent.setup()
+    const { rerender } = render(<MobilePage />)
+    await waitFor(() => expect(screen.getByTestId('stage')).toHaveTextContent('intro'))
+    await user.click(screen.getByRole('button', { name: 'Enter flow' }))
+    await user.click(screen.getByRole('button', { name: 'Continue' }))
+
+    // Signed-out Anywhere shows no QR at all.
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(getPairingQR).not.toHaveBeenCalled()
+    expect(screen.getByTestId('pairing-qr')).toHaveTextContent('none')
+
+    // Hold the sign-in mint pending so we can inspect the upgrade window.
     let resolveRelayQr: ((value: Record<string, unknown>) => void) | undefined
     getPairingQR.mockImplementationOnce(
       () =>
@@ -125,31 +247,23 @@ describe('MobilePage pairing connection mode', () => {
           resolveRelayQr = resolve
         })
     )
-    await user.click(screen.getByRole('button', { name: 'Anywhere' }))
-    await waitFor(() =>
-      expect(getPairingQR).toHaveBeenLastCalledWith({
-        connectionMode: 'automatic',
-        rotate: true
-      })
-    )
-    expect(screen.getByTestId('mode')).toHaveTextContent('automatic')
-    expect(screen.getByTestId('pairing-qr')).toHaveTextContent('base64,qr')
+
+    // Signing in unlocks Relay, so Step 2 mints an honest Relay QR.
+    mocks.storeState.orcaProfileAuthStatus = { state: 'connected' }
+    rerender(<MobilePage />)
+    await waitFor(() => expect(getPairingQR).toHaveBeenCalledWith({ connectionMode: 'automatic' }))
+    // Between the auth flip and the mint resolving, no code may be shown — the
+    // QR must not flash a stale/optimistic value while the Relay offer is pending.
+    expect(screen.getByTestId('pairing-qr')).toHaveTextContent('none')
     expect(screen.getByTestId('pairing-url')).toHaveTextContent('none')
 
     resolveRelayQr?.({
       available: true,
-      qrDataUrl: 'data:image/png;base64,relay-qr',
-      pairingUrl: 'orca://pair#relay'
+      qrDataUrl: 'data:image/png;base64,qr',
+      pairingUrl: 'orca://pair#automatic'
     })
-    await waitFor(() => expect(screen.getByTestId('pairing-qr')).toHaveTextContent('relay-qr'))
-  })
-
-  it('defaults signed-out pairing to local-only', async () => {
-    mocks.storeState.orcaProfileAuthStatus = { state: 'local' }
-    await openPairingStep()
-
-    await waitFor(() => expect(getPairingQR).toHaveBeenCalledWith({ connectionMode: 'local-only' }))
-    expect(screen.getByTestId('mode')).toHaveTextContent('local-only')
+    await waitFor(() => expect(screen.getByTestId('pairing-qr')).toHaveTextContent('base64,qr'))
+    expect(screen.getByTestId('mode')).toHaveTextContent('automatic')
   })
 
   it('removes the old QR if policy rotation fails', async () => {
@@ -158,7 +272,7 @@ describe('MobilePage pairing connection mode', () => {
     await waitFor(() => expect(screen.getByTestId('pairing-qr')).toHaveTextContent('base64,qr'))
 
     getPairingQR.mockRejectedValueOnce(new Error('rotation failed'))
-    await user.click(screen.getByRole('button', { name: 'Anywhere' }))
+    await user.click(screen.getByRole('button', { name: 'Local network' }))
 
     await waitFor(() => expect(screen.getByTestId('pairing-qr')).toHaveTextContent('none'))
     expect(screen.getByTestId('pairing-url')).toHaveTextContent('none')
diff --git a/src/renderer/src/components/mobile/MobilePage.tsx b/src/renderer/src/components/mobile/MobilePage.tsx
index 4ed7bfc22ed..f50ceb070ce 100644
--- a/src/renderer/src/components/mobile/MobilePage.tsx
+++ b/src/renderer/src/components/mobile/MobilePage.tsx
@@ -12,7 +12,13 @@ import { translate } from '@/i18n/i18n'
 import { useMobilePageEscape } from './use-mobile-page-escape'
 import { MobilePageContent } from './MobilePageContent'
 import { useMobileInstallQr } from './use-mobile-install-qr'
-import type { MobilePairingConnectionMode } from '../../../../shared/mobile-pairing-connection-mode'
+import {
+  canMintMobilePairingOffer,
+  type MobilePairingConnectionMode
+} from '../../../../shared/mobile-pairing-connection-mode'
+import { useMobilePairingConnectionMode } from './use-mobile-pairing-connection-mode'
+import { useMobilePairingGeneration } from './use-mobile-pairing-generation'
+import { useMobilePairingQrInvalidation } from './use-mobile-pairing-qr-invalidation'
 import { useMobileInstallActions } from './use-mobile-install-actions'
 import { useMobilePagePairedDevices } from './use-mobile-page-paired-devices'
 
@@ -26,11 +32,13 @@ export default function MobilePage(): React.JSX.Element {
 
   const [pairQrDataUrl, setPairQrDataUrl] = useState<string | null>(null)
   const [pairingUrl, setPairingUrl] = useState<string | null>(null)
+  // Mode the displayed QR actually encodes; can be 'local-only' under an
+  // Anywhere selection when Relay provisioning degraded server-side.
+  const [encodedConnectionMode, setEncodedConnectionMode] =
+    useState<MobilePairingConnectionMode | null>(null)
   const [pairLoading, setPairLoading] = useState(false)
   const signedIn = useAppStore((state) => state.orcaProfileAuthStatus?.state === 'connected')
-  // Why: Relay is opt-in while compatible mobile builds are limited to the
-  // TestFlight preview and Android APK.
-  const [connectionMode, setConnectionMode] = useState<MobilePairingConnectionMode>('local-only')
+  const [connectionMode, setConnectionMode] = useMobilePairingConnectionMode()
   const [networkInterfaces, setNetworkInterfaces] = useState<MobileNetworkInterface[]>([])
   const [selectedAddress, setSelectedAddress] = useState<string | undefined>(undefined)
   // Why: tracks whether `selectedAddress` came from the user typing a
@@ -40,7 +48,6 @@ export default function MobilePage(): React.JSX.Element {
   const [refreshingNetworkInterfaces, setRefreshingNetworkInterfaces] = useState(false)
   const hasGeneratedRef = useRef(false)
   const pairingRequestIdRef = useRef(0)
-  const wasSignedInRef = useRef(signedIn)
   const mountedRef = useMountedRef()
   const closeMobilePage = useAppStore((s) => s.closeMobilePage)
   const showMobileButton = useAppStore((s) => s.settings?.showMobileButton !== false)
@@ -58,95 +65,44 @@ export default function MobilePage(): React.JSX.Element {
   const installQrUrl = useMobileInstallQr(stage, platform, iosChannel)
   const { copyInstallUrl, openInstallUrl } = useMobileInstallActions(platform, iosChannel)
 
-  const generatePairing = useCallback(
-    async (
-      rotate: boolean,
-      addressOverride?: string,
-      connectionModeOverride?: MobilePairingConnectionMode
-    ) => {
-      const requestId = ++pairingRequestIdRef.current
-      // Mark the request synchronously so state changes cannot make the
-      // Step 2 auto-generate effect start a second offer in parallel.
-      hasGeneratedRef.current = true
-      if (mountedRef.current) {
-        setPairLoading(true)
-      }
-      try {
-        const address = addressOverride ?? selectedAddress
-        const nextConnectionMode = connectionModeOverride ?? connectionMode
-        const result = await window.api.mobile.getPairingQR({
-          ...(address ? { address } : {}),
-          connectionMode: nextConnectionMode,
-          ...(rotate ? { rotate: true } : {})
-        })
-        if (requestId !== pairingRequestIdRef.current) {
-          return
-        }
-        if (result.available) {
-          if (mountedRef.current) {
-            setPairQrDataUrl(result.qrDataUrl)
-            setPairingUrl(result.pairingUrl)
-          }
-        } else {
-          hasGeneratedRef.current = false
-          if (mountedRef.current) {
-            setPairQrDataUrl(null)
-            setPairingUrl(null)
-            toast.error(
-              translate(
-                'auto.components.mobile.MobilePage.b353e18de1',
-                'WebSocket transport is not running'
-              )
-            )
-          }
-        }
-      } catch {
-        if (mountedRef.current && requestId === pairingRequestIdRef.current) {
-          hasGeneratedRef.current = false
-          setPairQrDataUrl(null)
-          setPairingUrl(null)
-          toast.error(
-            translate(
-              'auto.components.mobile.MobilePage.4c8bd11c1a',
-              'Failed to generate pairing code'
-            )
-          )
-        }
-      } finally {
-        if (mountedRef.current && requestId === pairingRequestIdRef.current) {
-          setPairLoading(false)
-        }
-      }
-    },
-    [connectionMode, mountedRef, selectedAddress]
-  )
+  const { generatePairing } = useMobilePairingGeneration({
+    connectionMode,
+    signedIn,
+    selectedAddress,
+    mountedRef,
+    hasGeneratedRef,
+    pairingRequestIdRef,
+    setPairQrDataUrl,
+    setPairingUrl,
+    setPairLoading,
+    setEncodedConnectionMode
+  })
 
   const handleConnectionModeChange = useCallback(
     (nextMode: MobilePairingConnectionMode): void => {
       if (nextMode === connectionMode) {
         return
       }
+      // Why: persist the pick and update local state. The QR invalidation +
+      // rotate-regenerate is handled centrally by useMobilePairingQrInvalidation
+      // (below), which also covers cross-window preference syncs.
       setConnectionMode(nextMode)
-      // Why: an offer encodes its connection policy. Invalidate the prior
-      // request before rotating so a late response cannot restore a stale QR.
-      pairingRequestIdRef.current += 1
-      const shouldRegenerate = hasGeneratedRef.current || pairLoading
-      hasGeneratedRef.current = false
-      setPairingUrl(null)
-      if (shouldRegenerate) {
-        void generatePairing(true, undefined, nextMode)
-      }
+      void updateSettings({ mobilePairingConnectionMode: nextMode })
     },
-    [connectionMode, generatePairing, pairLoading]
+    [connectionMode, updateSettings, setConnectionMode]
   )
 
-  useEffect(() => {
-    const wasSignedIn = wasSignedInRef.current
-    wasSignedInRef.current = signedIn
-    if (wasSignedIn && !signedIn) {
-      handleConnectionModeChange('local-only')
-    }
-  }, [handleConnectionModeChange, signedIn])
+  useMobilePairingQrInvalidation({
+    connectionMode,
+    signedIn,
+    pairLoading,
+    hasGeneratedRef,
+    pairingRequestIdRef,
+    setPairQrDataUrl,
+    setPairingUrl,
+    setPairLoading,
+    regenerate: (mode, opts) => void generatePairing(opts.rotate, undefined, mode)
+  })
 
   const loadNetworkInterfaces = useCallback(async () => {
     if (mountedRef.current) {
@@ -177,7 +133,12 @@ export default function MobilePage(): React.JSX.Element {
           !result.interfaces.some((iface) => iface.address === newAddress)
         setAddressIsManual(nextIsManual)
       }
-      if (newAddress !== selectedAddress && hasGeneratedRef.current && mountedRef.current) {
+      if (
+        newAddress !== selectedAddress &&
+        hasGeneratedRef.current &&
+        canMintMobilePairingOffer({ connectionMode, signedIn }) &&
+        mountedRef.current
+      ) {
         void generatePairing(true, newAddress)
       }
     } catch {
@@ -187,7 +148,7 @@ export default function MobilePage(): React.JSX.Element {
         setRefreshingNetworkInterfaces(false)
       }
     }
-  }, [selectedAddress, generatePairing, mountedRef, addressIsManual])
+  }, [selectedAddress, generatePairing, mountedRef, addressIsManual, connectionMode, signedIn])
 
   useEffect(() => {
     if (stage !== 'flow') {
@@ -204,10 +165,13 @@ export default function MobilePage(): React.JSX.Element {
       // not snap it back to a tailnet/LAN fallback.
       const isManual = !networkInterfaces.some((iface) => iface.address === address)
       setAddressIsManual(isManual)
-      // Switching network must remint so the QR encodes the new endpoint.
-      void generatePairing(true, address)
+      // Switching network must remint so the QR encodes the new endpoint —
+      // but only when the selected path may honestly mint (not signed-out Anywhere).
+      if (canMintMobilePairingOffer({ connectionMode, signedIn })) {
+        void generatePairing(true, address)
+      }
     },
-    [generatePairing, networkInterfaces]
+    [generatePairing, networkInterfaces, connectionMode, signedIn]
   )
 
   const copyPairingCode = useCallback(async () => {
@@ -234,30 +198,37 @@ export default function MobilePage(): React.JSX.Element {
   // Why: when Step 2 first becomes visible, mint a pairing offer so the
   // user sees a real QR immediately. Subsequent visits keep the existing
   // token unless they hit Regenerate.
+  const canGenerate = canMintMobilePairingOffer({ connectionMode, signedIn })
   useEffect(() => {
     if (stage !== 'flow' || stepIdx !== 1 || hasGeneratedRef.current) {
       return
     }
+    // Why: signed-out Anywhere cannot serve Relay; auto-minting here would show a
+    // scannable local-only QR under the Relay label. Wait for sign-in or a switch
+    // to Local network (both flip canGenerate and re-run this effect) instead.
+    if (!canGenerate) {
+      return
+    }
     void generatePairing(false)
-  }, [stage, stepIdx, generatePairing])
+  }, [stage, stepIdx, canGenerate, generatePairing])
 
+  // Why: entering the flow must mint a fresh pairing token — clear stale QR
+  // state so we never flash an expired code from a previous session.
   const enterFlow = (): void => {
-    // Force the auto-generate effect to mint a fresh pairing token on next
-    // entry into Step 2, and clear stale QR state so we never flash an
-    // expired code from a previous session.
     hasGeneratedRef.current = false
     setPairQrDataUrl(null)
     setPairingUrl(null)
+    setEncodedConnectionMode(null)
     showFirstPairingFlow()
   }
 
   // Why: from the paired summary, "Pair another device" jumps straight to
   // Step 2 since the app is presumably already installed on the user's phone.
   const pairAnotherDevice = (): void => {
-    // Same reset as enterFlow — re-entering must mint a fresh pairing offer.
     hasGeneratedRef.current = false
     setPairQrDataUrl(null)
     setPairingUrl(null)
+    setEncodedConnectionMode(null)
     showPairAnotherDeviceFlow()
   }
 
@@ -290,6 +261,7 @@ export default function MobilePage(): React.JSX.Element {
       devices={devices}
       enterFlow={enterFlow}
       generatePairing={(rotate) => void generatePairing(rotate)}
+      canGeneratePairing={canGenerate}
       handleAddressChange={handleAddressChange}
       handleBack={handleBack}
       handleContinue={handleContinue}
@@ -305,6 +277,11 @@ export default function MobilePage(): React.JSX.Element {
       handleConnectionModeChange={handleConnectionModeChange}
       pairQrDataUrl={pairQrDataUrl}
       pairingUrl={pairingUrl}
+      relayDegraded={
+        pairQrDataUrl != null &&
+        connectionMode === 'automatic' &&
+        encodedConnectionMode === 'local-only'
+      }
       platform={platform}
       refreshingNetworkInterfaces={refreshingNetworkInterfaces}
       revokeDevice={(id) => void revokeDevice(id)}
diff --git a/src/renderer/src/components/mobile/MobilePageContent.tsx b/src/renderer/src/components/mobile/MobilePageContent.tsx
index c2b4c5ecbf7..432e4e5f654 100644
--- a/src/renderer/src/components/mobile/MobilePageContent.tsx
+++ b/src/renderer/src/components/mobile/MobilePageContent.tsx
@@ -15,6 +15,7 @@ type MobilePageContentProps = {
   devices: readonly PairedDevice[]
   enterFlow: () => void
   generatePairing: (rotate: boolean) => void
+  canGeneratePairing: boolean
   handleAddressChange: (address: string) => void
   handleBack: () => void
   handleContinue: () => void
@@ -30,6 +31,7 @@ type MobilePageContentProps = {
   handleConnectionModeChange: (mode: MobilePairingConnectionMode) => void
   pairQrDataUrl: string | null
   pairingUrl: string | null
+  relayDegraded: boolean
   platform: Platform
   refreshingNetworkInterfaces: boolean
   revokeDevice: (id: string) => void
@@ -50,6 +52,7 @@ export function MobilePageContent({
   devices,
   enterFlow,
   generatePairing,
+  canGeneratePairing,
   handleAddressChange,
   handleBack,
   handleContinue,
@@ -65,6 +68,7 @@ export function MobilePageContent({
   handleConnectionModeChange,
   pairQrDataUrl,
   pairingUrl,
+  relayDegraded,
   platform,
   refreshingNetworkInterfaces,
   revokeDevice,
@@ -108,10 +112,12 @@ export function MobilePageContent({
               onCopyInstallUrl={copyInstallUrl}
               pairQrDataUrl={pairQrDataUrl}
               pairingUrl={pairingUrl}
+              relayDegraded={relayDegraded}
               pairLoading={pairLoading}
               connectionMode={connectionMode}
               onConnectionModeChange={handleConnectionModeChange}
               onRegeneratePairing={() => generatePairing(true)}
+              canGeneratePairing={canGeneratePairing}
               onCopyPairingCode={copyPairingCode}
               networkInterfaces={networkInterfaces}
               selectedAddress={selectedAddress}
diff --git a/src/renderer/src/components/mobile/use-mobile-pairing-connection-mode.ts b/src/renderer/src/components/mobile/use-mobile-pairing-connection-mode.ts
new file mode 100644
index 00000000000..2b0eaea7ff0
--- /dev/null
+++ b/src/renderer/src/components/mobile/use-mobile-pairing-connection-mode.ts
@@ -0,0 +1,26 @@
+import { useEffect, useState } from 'react'
+import { useAppStore } from '@/store'
+import {
+  resolveMobilePairingConnectionMode,
+  type MobilePairingConnectionMode
+} from '../../../../shared/mobile-pairing-connection-mode'
+
+/**
+ * Selected pairing path, seeded from the persisted preference and re-synced
+ * when it changes. Anywhere is the default; an explicit saved `local-only`
+ * means the user already chose same-network only. Shared by MobilePage and
+ * MobilePane so the two surfaces cannot resolve the saved value differently.
+ */
+export function useMobilePairingConnectionMode(): [
+  MobilePairingConnectionMode,
+  React.Dispatch<React.SetStateAction<MobilePairingConnectionMode>>
+] {
+  const savedConnectionMode = useAppStore((s) => s.settings?.mobilePairingConnectionMode)
+  const [connectionMode, setConnectionMode] = useState<MobilePairingConnectionMode>(() =>
+    resolveMobilePairingConnectionMode(savedConnectionMode)
+  )
+  useEffect(() => {
+    setConnectionMode(resolveMobilePairingConnectionMode(savedConnectionMode))
+  }, [savedConnectionMode])
+  return [connectionMode, setConnectionMode]
+}
diff --git a/src/renderer/src/components/mobile/use-mobile-pairing-generation.ts b/src/renderer/src/components/mobile/use-mobile-pairing-generation.ts
new file mode 100644
index 00000000000..cb77f82e65f
--- /dev/null
+++ b/src/renderer/src/components/mobile/use-mobile-pairing-generation.ts
@@ -0,0 +1,134 @@
+import { useCallback } from 'react'
+import { toast } from 'sonner'
+import { translate } from '@/i18n/i18n'
+import {
+  canMintMobilePairingOffer,
+  type MobilePairingConnectionMode
+} from '../../../../shared/mobile-pairing-connection-mode'
+
+type MutableRef<T> = { current: T }
+
+/**
+ * Mints (or rotates) a pairing QR. Every caller must go through this path so
+ * signed-out Anywhere is refused rather than silently degraded to a local-only
+ * code under the Relay label.
+ */
+export function useMobilePairingGeneration(params: {
+  connectionMode: MobilePairingConnectionMode
+  signedIn: boolean
+  selectedAddress: string | undefined
+  mountedRef: MutableRef<boolean>
+  hasGeneratedRef: MutableRef<boolean>
+  pairingRequestIdRef: MutableRef<number>
+  setPairQrDataUrl: (value: string | null) => void
+  setPairingUrl: (value: string | null) => void
+  setPairLoading: (value: boolean) => void
+  /** Mode the minted QR actually encodes (degraded Relay mints report
+   *  'local-only'); null while no QR is shown. */
+  setEncodedConnectionMode: (value: MobilePairingConnectionMode | null) => void
+}): {
+  generatePairing: (
+    rotate: boolean,
+    addressOverride?: string,
+    connectionModeOverride?: MobilePairingConnectionMode
+  ) => Promise<void>
+} {
+  const {
+    connectionMode,
+    signedIn,
+    selectedAddress,
+    mountedRef,
+    hasGeneratedRef,
+    pairingRequestIdRef,
+    setPairQrDataUrl,
+    setPairingUrl,
+    setPairLoading,
+    setEncodedConnectionMode
+  } = params
+
+  const generatePairing = useCallback(
+    async (
+      rotate: boolean,
+      addressOverride?: string,
+      connectionModeOverride?: MobilePairingConnectionMode
+    ) => {
+      const preferredMode = connectionModeOverride ?? connectionMode
+      // Why: every mint path (auto-generate, regenerate, address change, path
+      // invalidation) must refuse signed-out Anywhere rather than degrade to a
+      // local-only QR under the Relay label.
+      if (!canMintMobilePairingOffer({ connectionMode: preferredMode, signedIn })) {
+        return
+      }
+      const requestId = ++pairingRequestIdRef.current
+      // Mark the request synchronously so state changes cannot make the
+      // Step 2 auto-generate effect start a second offer in parallel.
+      hasGeneratedRef.current = true
+      if (mountedRef.current) {
+        setPairLoading(true)
+      }
+      try {
+        const address = addressOverride ?? selectedAddress
+        // canMint already requires sign-in for Anywhere, so preferred is honest.
+        const result = await window.api.mobile.getPairingQR({
+          ...(address ? { address } : {}),
+          connectionMode: preferredMode,
+          ...(rotate ? { rotate: true } : {})
+        })
+        if (requestId !== pairingRequestIdRef.current) {
+          return
+        }
+        if (result.available) {
+          if (mountedRef.current) {
+            setPairQrDataUrl(result.qrDataUrl)
+            setPairingUrl(result.pairingUrl)
+            setEncodedConnectionMode(result.connectionMode)
+          }
+        } else {
+          hasGeneratedRef.current = false
+          if (mountedRef.current) {
+            setPairQrDataUrl(null)
+            setPairingUrl(null)
+            setEncodedConnectionMode(null)
+            toast.error(
+              translate(
+                'auto.components.mobile.MobilePage.b353e18de1',
+                'WebSocket transport is not running'
+              )
+            )
+          }
+        }
+      } catch {
+        if (mountedRef.current && requestId === pairingRequestIdRef.current) {
+          hasGeneratedRef.current = false
+          setPairQrDataUrl(null)
+          setPairingUrl(null)
+          setEncodedConnectionMode(null)
+          toast.error(
+            translate(
+              'auto.components.mobile.MobilePage.4c8bd11c1a',
+              'Failed to generate pairing code'
+            )
+          )
+        }
+      } finally {
+        if (mountedRef.current && requestId === pairingRequestIdRef.current) {
+          setPairLoading(false)
+        }
+      }
+    },
+    [
+      connectionMode,
+      hasGeneratedRef,
+      mountedRef,
+      pairingRequestIdRef,
+      selectedAddress,
+      setEncodedConnectionMode,
+      setPairLoading,
+      setPairQrDataUrl,
+      setPairingUrl,
+      signedIn
+    ]
+  )
+
+  return { generatePairing }
+}
diff --git a/src/renderer/src/components/mobile/use-mobile-pairing-qr-invalidation.ts b/src/renderer/src/components/mobile/use-mobile-pairing-qr-invalidation.ts
new file mode 100644
index 00000000000..47f57dfd063
--- /dev/null
+++ b/src/renderer/src/components/mobile/use-mobile-pairing-qr-invalidation.ts
@@ -0,0 +1,112 @@
+import { useEffect, useRef } from 'react'
+import {
+  canMintMobilePairingOffer,
+  type MobilePairingConnectionMode
+} from '../../../../shared/mobile-pairing-connection-mode'
+
+type MutableRef<T> = { current: T }
+
+/**
+ * Keeps the displayed pairing QR consistent with the selected path and sign-in
+ * state. Signing out of Anywhere clears the Relay QR (Step 2 does not re-mint a
+ * local-only code under the Relay label), signing in mints Relay, and a path
+ * change (local or cross-window) invalidates the encoded policy — otherwise the
+ * shown code silently mismatches what it actually encodes.
+ */
+export function useMobilePairingQrInvalidation(params: {
+  connectionMode: MobilePairingConnectionMode
+  signedIn: boolean
+  pairLoading: boolean
+  hasGeneratedRef: MutableRef<boolean>
+  pairingRequestIdRef: MutableRef<number>
+  setPairQrDataUrl: (value: string | null) => void
+  setPairingUrl: (value: string | null) => void
+  setPairLoading: (value: boolean) => void
+  regenerate: (mode: MobilePairingConnectionMode, opts: { rotate: boolean }) => void
+}): void {
+  const {
+    connectionMode,
+    signedIn,
+    pairLoading,
+    hasGeneratedRef,
+    pairingRequestIdRef,
+    setPairQrDataUrl,
+    setPairingUrl,
+    setPairLoading,
+    regenerate
+  } = params
+  const wasSignedInRef = useRef(signedIn)
+  // Tracks the mode we last acted on so the mode effect can tell a cross-window
+  // preference sync apart from an already-handled change.
+  const handledModeRef = useRef(connectionMode)
+
+  // Sign-in/out edges on Anywhere: signing out clears the Relay QR without
+  // re-minting (a local-only code must not appear under the Relay label);
+  // signing in mints Relay. Anywhere stays selected across both edges. Clear
+  // loading too so a superseded in-flight generate can't leave a stuck spinner.
+  useEffect(() => {
+    const wasSignedIn = wasSignedInRef.current
+    wasSignedInRef.current = signedIn
+    if (connectionMode !== 'automatic' || !hasGeneratedRef.current || wasSignedIn === signedIn) {
+      return
+    }
+    pairingRequestIdRef.current += 1
+    hasGeneratedRef.current = false
+    setPairingUrl(null)
+    setPairQrDataUrl(null)
+    if (signedIn && canMintMobilePairingOffer({ connectionMode, signedIn })) {
+      // Why: rotate on the sign-in edge — the token behind the QR cleared at
+      // sign-out may have been exposed, so the fresh session mints fresh.
+      regenerate(connectionMode, { rotate: true })
+    } else {
+      setPairLoading(false)
+    }
+  }, [
+    connectionMode,
+    signedIn,
+    hasGeneratedRef,
+    pairingRequestIdRef,
+    setPairQrDataUrl,
+    setPairingUrl,
+    setPairLoading,
+    regenerate
+  ])
+
+  // Any path change — a user pick or another window persisting a new default —
+  // invalidates the prior request before rotating so a late response cannot
+  // restore a QR for the old policy. No updateSettings here (the caller/other
+  // window already wrote it) so there is no cross-window loop.
+  // Why: remint only when the new path may honestly encode a QR. Switching into
+  // signed-out Anywhere must clear, not mint a local-only code under Relay.
+  useEffect(() => {
+    if (connectionMode === handledModeRef.current) {
+      return
+    }
+    handledModeRef.current = connectionMode
+    pairingRequestIdRef.current += 1
+    const shouldRegenerate = hasGeneratedRef.current || pairLoading
+    hasGeneratedRef.current = false
+    setPairingUrl(null)
+    setPairQrDataUrl(null)
+    if (shouldRegenerate && canMintMobilePairingOffer({ connectionMode, signedIn })) {
+      // Why: no rotate here — the main process rotates exactly once when the
+      // requested mode differs from the pending token's minted mode, so the
+      // initiating window and windows reacting to a cross-window preference
+      // sync converge on the same fresh token instead of racing rotations.
+      regenerate(connectionMode, { rotate: false })
+    } else {
+      // No honest re-mint (blocked path or nothing pending); drop spinner.
+      setPairLoading(false)
+    }
+  }, [
+    connectionMode,
+    signedIn,
+    pairLoading,
+    hasGeneratedRef,
+    pairingRequestIdRef,
+    setPairQrDataUrl,
+    setPairingUrl,
+    setPairLoading,
+    regenerate
+  ])
+}
diff --git a/src/renderer/src/components/settings/MobilePairingConnectionOptions.test.tsx b/src/renderer/src/components/settings/MobilePairingConnectionOptions.test.tsx
index 1fa6d2bbcb1..c334245554e 100644
--- a/src/renderer/src/components/settings/MobilePairingConnectionOptions.test.tsx
+++ b/src/renderer/src/components/settings/MobilePairingConnectionOptions.test.tsx
@@ -13,6 +13,7 @@ type MobileRelayStoreState = {
   orcaProfileAuthStatus: OrcaProfileAuthStatus | null
   orcaProfileConnecting: boolean
   connectCurrentOrcaProfile: () => Promise<null>
+  fetchOrcaProfileAuthStatus: () => Promise<OrcaProfileAuthStatus | null>
 }
 
 const mocks = vi.hoisted(() => ({
@@ -30,10 +31,12 @@ vi.mock('../../i18n/i18n', () => ({
 describe('MobilePairingConnectionOptions', () => {
   let statusListener: ((status: MobileRelayStatus) => void) | null
   const connect = vi.fn().mockResolvedValue(null)
+  const fetchAuthStatus = vi.fn().mockResolvedValue(null)
 
   beforeEach(() => {
     statusListener = null
     connect.mockClear()
+    fetchAuthStatus.mockClear()
     Object.defineProperty(window, 'api', {
       configurable: true,
       value: {
@@ -55,23 +58,89 @@ describe('MobilePairingConnectionOptions', () => {
         persistence: 'none'
       },
       orcaProfileConnecting: false,
-      connectCurrentOrcaProfile: connect
+      connectCurrentOrcaProfile: connect,
+      fetchOrcaProfileAuthStatus: fetchAuthStatus
     }
   })
 
   afterEach(() => cleanup())
 
-  it('offers local-only pairing while Relay requires sign-in', async () => {
+  it('shows a compact Sign in row when Orca Relay is selected and signed out', async () => {
     const user = userEvent.setup()
-    render(<MobilePairingConnectionOptions value="local-only" onChange={vi.fn()} />)
+    const onChange = vi.fn()
+    render(<MobilePairingConnectionOptions value="automatic" onChange={onChange} />)
+
+    expect(screen.getByTestId('anywhere-sign-in-panel')).toBeVisible()
+    expect(screen.getByText('Sign in to use Orca Mobile Relay.')).toBeVisible()
+    // Why: do not surface build-setup diagnostics in the pairing flow.
+    expect(screen.queryByText(/not configured for this build/i)).toBeNull()
 
-    expect(screen.getByRole('switch', { name: /connect with Orca Relay/i })).toBeDisabled()
-    expect(screen.getByRole('switch', { name: /connect with Orca Relay/i })).not.toBeChecked()
     await user.click(screen.getByRole('button', { name: 'Sign in' }))
+    expect(onChange).toHaveBeenCalledWith('automatic')
     expect(connect).toHaveBeenCalledOnce()
   })
 
-  it('selects either automatic fallback or local-only pairing when signed in', async () => {
+  it('hides Sign in when local network is selected', () => {
+    render(<MobilePairingConnectionOptions value="local-only" onChange={vi.fn()} />)
+    expect(screen.queryByTestId('anywhere-sign-in-panel')).toBeNull()
+  })
+
+  it('shows Unavailable instead of a dead Sign in on unconfigured builds', () => {
+    mocks.state = {
+      ...mocks.state,
+      orcaProfileAuthStatus: {
+        activeProfileId: 'profile-1',
+        configured: false,
+        state: 'unconfigured',
+        persistence: 'none'
+      }
+    }
+    render(<MobilePairingConnectionOptions value="automatic" onChange={vi.fn()} />)
+
+    // No Relay endpoint to sign into — the Sign in CTA must not appear.
+    expect(screen.queryByTestId('anywhere-sign-in-panel')).toBeNull()
+    expect(screen.queryByRole('button', { name: /Sign in/i })).toBeNull()
+    expect(screen.getByTestId('anywhere-unavailable-panel')).toBeVisible()
+    expect(screen.getByText('Unavailable')).toBeVisible()
+  })
+
+  it('moves selection with the arrow keys as a radiogroup', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<MobilePairingConnectionOptions value="automatic" onChange={onChange} />)
+
+    screen.getByRole('radio', { name: /Orca Relay/i }).focus()
+    await user.keyboard('{ArrowDown}')
+    expect(onChange).toHaveBeenCalledWith('local-only')
+  })
+
+  it('selects a path from the compact list', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<MobilePairingConnectionOptions value="local-only" onChange={onChange} />)
+
+    expect(
+      screen.getByText('Phone can be on cellular or any Wi‑Fi. Sign-in required.')
+    ).toBeVisible()
+    expect(
+      screen.getByText('Phone must be on this Wi‑Fi or your Tailscale. No sign-in.')
+    ).toBeVisible()
+
+    await user.click(screen.getByRole('radio', { name: /Orca Relay/i }))
+    expect(onChange).toHaveBeenCalledWith('automatic')
+  })
+
+  it('refreshes auth status when it is missing on mount', () => {
+    mocks.state = {
+      ...mocks.state,
+      orcaProfileAuthStatus: null
+    }
+    render(<MobilePairingConnectionOptions value="automatic" onChange={vi.fn()} />)
+    expect(fetchAuthStatus).toHaveBeenCalledOnce()
+    expect(screen.getByTestId('anywhere-sign-in-panel')).toBeVisible()
+  })
+
+  it('shows relay status when signed in on Orca Relay', async () => {
     mocks.state = {
       orcaProfileAuthStatus: {
         activeProfileId: 'profile-1',
@@ -80,59 +149,18 @@ describe('MobilePairingConnectionOptions', () => {
         persistence: 'encrypted'
       },
       orcaProfileConnecting: false,
-      connectCurrentOrcaProfile: connect
+      connectCurrentOrcaProfile: connect,
+      fetchOrcaProfileAuthStatus: fetchAuthStatus
     }
     const onChange = vi.fn()
     const user = userEvent.setup()
     render(<MobilePairingConnectionOptions value="automatic" onChange={onChange} />)
 
     await waitFor(() => expect(screen.getByText('Ready')).toBeVisible())
-    expect(screen.getByRole('switch', { name: /connect with Orca Relay/i })).toBeChecked()
-    await user.click(screen.getByRole('switch', { name: /connect with Orca Relay/i }))
+    expect(screen.queryByTestId('anywhere-sign-in-panel')).toBeNull()
+
+    await user.click(screen.getByRole('radio', { name: /Local network/i }))
     expect(onChange).toHaveBeenCalledWith('local-only')
     statusListener?.('standby')
-    await waitFor(() => expect(screen.getByText('Available')).toBeVisible())
-  })
-
-  it('shows the Relay beta availability inline and opens both compatible mobile builds', async () => {
-    const user = userEvent.setup()
-    render(<MobilePairingConnectionOptions value="local-only" onChange={vi.fn()} />)
-
-    expect(screen.getByText('Beta')).toBeVisible()
-    expect(screen.getByText('Available on')).toBeVisible()
-
-    await user.click(screen.getByRole('button', { name: 'TestFlight' }))
-    expect(window.api.shell.openUrl).toHaveBeenCalledWith(
-      'https://testflight.apple.com/join/YjeGMQBA'
-    )
-
-    await user.click(screen.getByRole('button', { name: 'Android APK' }))
-    expect(window.api.shell.openUrl).toHaveBeenCalledWith(
-      'https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.31/app-release.apk'
-    )
-  })
-
-  it('keeps the compact onboarding choices structurally stable across modes', async () => {
-    mocks.state = {
-      orcaProfileAuthStatus: {
-        activeProfileId: 'profile-1',
-        configured: true,
-        state: 'connected',
-        persistence: 'encrypted'
-      },
-      orcaProfileConnecting: false,
-      connectCurrentOrcaProfile: connect
-    }
-    const props = { compact: true, onChange: vi.fn() }
-    const { rerender } = render(<MobilePairingConnectionOptions {...props} value="automatic" />)
-
-    expect(screen.getByRole('switch', { name: /connect with Orca Relay/i })).toBeChecked()
-    expect(screen.getByText(/direct connection when available/i)).toBeVisible()
-    expect(screen.queryByText('Ready')).toBeNull()
-
-    rerender(<MobilePairingConnectionOptions {...props} value="local-only" />)
-    expect(screen.getByRole('switch', { name: /connect with Orca Relay/i })).not.toBeChecked()
-    expect(screen.getByText(/direct connection when available/i)).toBeVisible()
-    expect(screen.queryByText(/without connecting this phone through Orca Relay/i)).toBeNull()
   })
 })
diff --git a/src/renderer/src/components/settings/MobilePairingConnectionOptions.tsx b/src/renderer/src/components/settings/MobilePairingConnectionOptions.tsx
index 3411cc9d38c..986fed94b7a 100644
--- a/src/renderer/src/components/settings/MobilePairingConnectionOptions.tsx
+++ b/src/renderer/src/components/settings/MobilePairingConnectionOptions.tsx
@@ -1,13 +1,12 @@
-import { useEffect, useState } from 'react'
-import { Cloud, Loader2 } from 'lucide-react'
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import { Loader2 } from 'lucide-react'
 import { Badge } from '../ui/badge'
 import { Button } from '../ui/button'
 import { translate } from '../../i18n/i18n'
 import { useAppStore } from '../../store'
+import { cn } from '@/lib/utils'
 import type { MobileRelayStatus } from '../../../../shared/mobile-relay-status'
 import type { MobilePairingConnectionMode } from '../../../../shared/mobile-pairing-connection-mode'
-import { MobileRelayBetaAvailability } from './MobileRelayBetaAvailability'
-import { SettingsRow, SettingsSwitch } from './SettingsFormControls'
 
 function relayStatusLabel(status: MobileRelayStatus): string {
   if (status === 'registered') {
@@ -37,122 +36,68 @@ function relayStatusLabel(status: MobileRelayStatus): string {
   )
 }
 
-type CompactConnectionOptionsProps = {
-  value: MobilePairingConnectionMode
-  onChange: (value: MobilePairingConnectionMode) => void
-  signedIn: boolean
-  configured: boolean
-  connecting: boolean
-  connect: () => Promise<unknown>
-  relayStatus: MobileRelayStatus
+type PathOptionProps = {
+  selected: boolean
+  onSelect: () => void
+  title: string
+  description: string
+  trailing?: ReactNode
+  tabIndex: number
+  optionRef?: (el: HTMLDivElement | null) => void
 }
 
-function ConnectionModeSwitch({
-  value,
-  onChange,
-  signedIn,
-  relayStatus,
-  showStatus = true
-}: Pick<CompactConnectionOptionsProps, 'value' | 'onChange' | 'signedIn' | 'relayStatus'> & {
-  showStatus?: boolean
-}): React.JSX.Element {
+// Why: this is a bespoke radio row rather than the canonical SettingsSegmentedControl
+// because each option needs a two-line title + description plus a trailing status
+// badge, which the single-line segmented pill cannot carry (STYLEGUIDE.md's
+// "real difference in role" carve-out). Arrow-key nav and roving tabindex below
+// keep it a conformant ARIA radiogroup.
+function PathOption({
+  selected,
+  onSelect,
+  title,
+  description,
+  trailing,
+  tabIndex,
+  optionRef
+}: PathOptionProps): React.JSX.Element {
   return (
-    <SettingsRow
-      label={
-        <span className="inline-flex items-center gap-2">
-          <Cloud className="size-4 text-muted-foreground" />
-          <span>
-            {translate(
-              'auto.components.settings.MobilePairingConnectionOptions.anywhere',
-              'Connect with Orca Relay'
-            )}
-          </span>
-        </span>
-      }
-      description={
-        <span className="block space-y-0.5">
-          <span className="block">
-            {signedIn
-              ? translate(
-                  'auto.components.settings.MobilePairingConnectionOptions.automaticDescription',
-                  'Orca uses a direct connection when available and Relay otherwise.'
-                )
-              : translate(
-                  'auto.components.settings.MobilePairingConnectionOptions.signInDescription',
-                  'Sign in on this desktop to use Orca Relay.'
-                )}
-          </span>
-          <MobileRelayBetaAvailability />
-        </span>
-      }
-      alignTop
-      control={
-        <div className="flex items-center gap-2">
-          {showStatus && signedIn && value === 'automatic' ? (
-            <Badge variant="outline" className="shrink-0">
-              {relayStatusLabel(relayStatus)}
-            </Badge>
-          ) : null}
-          <SettingsSwitch
-            checked={value === 'automatic'}
-            disabled={!signedIn}
-            ariaLabel={translate(
-              'auto.components.settings.MobilePairingConnectionOptions.anywhere',
-              'Connect with Orca Relay'
-            )}
-            onChange={() => onChange(value === 'automatic' ? 'local-only' : 'automatic')}
-          />
+    <div
+      ref={optionRef}
+      role="radio"
+      tabIndex={tabIndex}
+      aria-checked={selected}
+      onClick={onSelect}
+      onKeyDown={(event) => {
+        if (event.key === ' ' || event.key === 'Enter') {
+          event.preventDefault()
+          onSelect()
+        }
+      }}
+      className={cn(
+        'flex cursor-pointer items-start gap-3 px-3 py-2.5 outline-none transition-colors',
+        // Why: match SettingsFormControls focus ring so keyboard focus is visible
+        // even when the selected row already uses bg-accent/40.
+        'focus-visible:bg-accent/50 focus-visible:ring-[3px] focus-visible:ring-ring/50',
+        selected ? 'bg-accent/40' : 'hover:bg-accent/20'
+      )}
+    >
+      <span
+        className={cn(
+          'mt-0.5 flex size-3.5 shrink-0 items-center justify-center rounded-full border',
+          selected ? 'border-foreground bg-foreground' : 'border-muted-foreground/40'
+        )}
+        aria-hidden
+      >
+        {selected ? <span className="size-1.5 rounded-full bg-background" /> : null}
+      </span>
+      <div className="min-w-0 flex-1">
+        <div className="flex flex-wrap items-center gap-2">
+          <span className="text-sm font-medium leading-none">{title}</span>
+          {trailing}
         </div>
-      }
-    />
-  )
-}
-
-function CompactConnectionOptions({
-  value,
-  onChange,
-  signedIn,
-  configured,
-  connecting,
-  connect,
-  relayStatus
-}: CompactConnectionOptionsProps): React.JSX.Element {
-  return (
-    <section className="w-full">
-      <ConnectionModeSwitch
-        value={value}
-        onChange={onChange}
-        signedIn={signedIn}
-        relayStatus={relayStatus}
-        showStatus={false}
-      />
-      {!signedIn ? (
-        <div className="flex justify-start">
-          {configured ? (
-            <Button
-              type="button"
-              size="xs"
-              className="shrink-0"
-              disabled={connecting}
-              onClick={() => void connect()}
-            >
-              {connecting ? <Loader2 className="animate-spin" /> : null}
-              {translate(
-                'auto.components.settings.MobilePairingConnectionOptions.signIn',
-                'Sign in'
-              )}
-            </Button>
-          ) : (
-            <Badge variant="outline" className="shrink-0">
-              {translate(
-                'auto.components.settings.MobilePairingConnectionOptions.unavailable',
-                'Unavailable'
-              )}
-            </Badge>
-          )}
-        </div>
-      ) : null}
-    </section>
+        <p className="mt-1 text-xs text-muted-foreground">{description}</p>
+      </div>
+    </div>
   )
 }
 
@@ -168,9 +113,38 @@ export function MobilePairingConnectionOptions({
   const authStatus = useAppStore((state) => state.orcaProfileAuthStatus)
   const connecting = useAppStore((state) => state.orcaProfileConnecting)
   const connect = useAppStore((state) => state.connectCurrentOrcaProfile)
+  const fetchAuthStatus = useAppStore((state) => state.fetchOrcaProfileAuthStatus)
   const [relayStatus, setRelayStatus] = useState<MobileRelayStatus>('offline')
   const signedIn = authStatus?.state === 'connected'
+  const reconnectRequired = authStatus?.state === 'reconnect-required'
+  // Why: an unconfigured build has no Relay endpoint to sign into, so a Sign in
+  // CTA would be dead. Treat that case as unavailable (matching the prior UI)
+  // and only offer Sign in when the build can actually reach Relay.
   const configured = authStatus?.configured !== false
+  const needsSignIn = value === 'automatic' && !signedIn && configured
+  const relayUnavailable = value === 'automatic' && !signedIn && !configured
+  const optionRefs = useRef<Record<MobilePairingConnectionMode, HTMLDivElement | null>>({
+    automatic: null,
+    'local-only': null
+  })
+
+  // Why: ARIA radiogroups move selection with the arrow keys; wrap between the
+  // two options and move focus so keyboard users get standard behavior.
+  const handleArrowKeys = (event: React.KeyboardEvent): void => {
+    if (!['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(event.key)) {
+      return
+    }
+    event.preventDefault()
+    const next: MobilePairingConnectionMode = value === 'automatic' ? 'local-only' : 'automatic'
+    onChange(next)
+    optionRefs.current[next]?.focus()
+  }
+
+  useEffect(() => {
+    if (!authStatus) {
+      void fetchAuthStatus()
+    }
+  }, [authStatus, fetchAuthStatus])
 
   useEffect(() => {
     let receivedEvent = false
@@ -195,54 +169,112 @@ export function MobilePairingConnectionOptions({
     }
   }, [])
 
-  if (compact) {
-    return (
-      <CompactConnectionOptions
-        value={value}
-        onChange={onChange}
-        signedIn={signedIn}
-        configured={configured}
-        connecting={connecting}
-        connect={connect}
-        relayStatus={relayStatus}
-      />
-    )
-  }
-
   return (
-    <section>
-      <ConnectionModeSwitch
-        value={value}
-        onChange={onChange}
-        signedIn={signedIn}
-        relayStatus={relayStatus}
-      />
-      {!signedIn ? (
-        <div className="flex justify-end">
-          {configured ? (
-            <Button
-              type="button"
-              size="sm"
-              className="w-24 shrink-0"
-              disabled={connecting}
-              onClick={() => void connect()}
-            >
-              {connecting ? <Loader2 className="animate-spin" /> : null}
-              {translate(
-                'auto.components.settings.MobilePairingConnectionOptions.signIn',
-                'Sign in'
-              )}
-            </Button>
-          ) : (
-            <Badge variant="outline" className="shrink-0">
-              {translate(
-                'auto.components.settings.MobilePairingConnectionOptions.unavailable',
-                'Unavailable'
-              )}
-            </Badge>
+    <div className={cn('space-y-2', compact && 'space-y-1.5')}>
+      <div
+        role="radiogroup"
+        aria-label={translate(
+          'auto.components.settings.MobilePairingConnectionOptions.pathGroup',
+          'How the phone reaches this computer'
+        )}
+        onKeyDown={handleArrowKeys}
+        className="overflow-hidden rounded-md border border-border"
+      >
+        <PathOption
+          selected={value === 'automatic'}
+          tabIndex={value === 'automatic' ? 0 : -1}
+          optionRef={(el) => {
+            optionRefs.current.automatic = el
+          }}
+          onSelect={() => onChange('automatic')}
+          title={translate(
+            'auto.components.settings.MobilePairingConnectionOptions.anywhereTitle',
+            'Orca Relay'
           )}
+          description={translate(
+            'auto.components.settings.MobilePairingConnectionOptions.anywhereDescription',
+            'Phone can be on cellular or any Wi‑Fi. Sign-in required.'
+          )}
+          trailing={
+            signedIn && value === 'automatic' ? (
+              <Badge variant="outline" className="text-[11px]">
+                {relayStatusLabel(relayStatus)}
+              </Badge>
+            ) : null
+          }
+        />
+        <div className="border-t border-border" />
+        <PathOption
+          selected={value === 'local-only'}
+          tabIndex={value === 'local-only' ? 0 : -1}
+          optionRef={(el) => {
+            optionRefs.current['local-only'] = el
+          }}
+          onSelect={() => onChange('local-only')}
+          title={translate(
+            'auto.components.settings.MobilePairingConnectionOptions.localTitle',
+            'Local network'
+          )}
+          description={translate(
+            'auto.components.settings.MobilePairingConnectionOptions.localDescription',
+            'Phone must be on this Wi‑Fi or your Tailscale. No sign-in.'
+          )}
+        />
+      </div>
+
+      {needsSignIn ? (
+        <div
+          className="flex flex-wrap items-center justify-between gap-2 rounded-md border border-border px-3 py-2"
+          data-testid="anywhere-sign-in-panel"
+        >
+          <p className="min-w-0 flex-1 text-xs text-muted-foreground">
+            {translate(
+              'auto.components.settings.MobilePairingConnectionOptions.signInRequired',
+              'Sign in to use Orca Mobile Relay.'
+            )}
+          </p>
+          <Button
+            type="button"
+            size="sm"
+            disabled={connecting}
+            onClick={() => {
+              onChange('automatic')
+              void connect()
+            }}
+          >
+            {connecting ? <Loader2 className="animate-spin" /> : null}
+            {reconnectRequired
+              ? translate(
+                  'auto.components.settings.MobilePairingConnectionOptions.signInAgain',
+                  'Sign in again'
+                )
+              : translate(
+                  'auto.components.settings.MobilePairingConnectionOptions.signIn',
+                  'Sign in'
+                )}
+          </Button>
         </div>
       ) : null}
-    </section>
+
+      {relayUnavailable ? (
+        <div
+          className="flex flex-wrap items-center justify-between gap-2 rounded-md border border-border px-3 py-2"
+          data-testid="anywhere-unavailable-panel"
+        >
+          <p className="min-w-0 flex-1 text-xs text-muted-foreground">
+            {translate(
+              'auto.components.settings.MobilePairingConnectionOptions.relayUnavailable',
+              'Orca Relay isn’t available in this build. Use Local network.'
+            )}
+          </p>
+          <Badge variant="outline" className="shrink-0">
+            {translate(
+              'auto.components.settings.MobilePairingConnectionOptions.unavailable',
+              'Unavailable'
+            )}
+          </Badge>
+        </div>
+      ) : null}
+    </div>
   )
 }
diff --git a/src/renderer/src/components/settings/MobilePairingSetupSection.test.tsx b/src/renderer/src/components/settings/MobilePairingSetupSection.test.tsx
index cce8bdce341..59ed1b9a3c9 100644
--- a/src/renderer/src/components/settings/MobilePairingSetupSection.test.tsx
+++ b/src/renderer/src/components/settings/MobilePairingSetupSection.test.tsx
@@ -3,7 +3,7 @@
 import '@testing-library/jest-dom/vitest'
 
 import React from 'react'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import { MobilePairingSetupSection } from './MobilePairingSetupSection'
@@ -23,7 +23,7 @@ function renderSection(
   const onGenerateQr = vi.fn()
   const props: React.ComponentProps<typeof MobilePairingSetupSection> = {
     connectionMode: 'local-only',
-    relayConnectionControl: null,
+    connectionPathControl: <div data-testid="path-control">path</div>,
     networkInterfaces: [LAN, TAILNET],
     selectedAddress: TAILNET.address,
     onSelectedAddressChange,
@@ -44,18 +44,37 @@ function renderSection(
 }
 
 describe('MobilePairingSetupSection', () => {
-  it('keeps local settings visible for local-only pairing', () => {
-    renderSection()
-    expect(screen.getByRole('combobox')).toHaveTextContent('100.64.1.20 (tailscale0)')
-    expect(screen.getByText(/connects only through the local network address/i)).toBeVisible()
+  beforeEach(() => {
+    Object.defineProperty(window, 'api', {
+      configurable: true,
+      value: {
+        shell: { openUrl: vi.fn().mockResolvedValue(undefined) }
+      }
+    })
   })
 
-  it('keeps local settings visible for automatic direct-first pairing', () => {
+  it('shows connection, address, and generate in a compact flow', () => {
+    renderSection()
+    expect(screen.getByText('Pair a phone')).toBeVisible()
+    expect(screen.getByText('Connection')).toBeVisible()
+    expect(screen.getByText('This computer’s address')).toBeVisible()
+    expect(screen.getByTestId('path-control')).toBeVisible()
+    expect(screen.getByRole('combobox')).toHaveTextContent('100.64.1.20 (tailscale0)')
+    expect(screen.getByRole('button', { name: 'Generate QR code' })).toBeVisible()
+    expect(screen.getByText(/must be able to reach this address/i)).toBeVisible()
+  })
+
+  it('describes address role when Anywhere is selected', () => {
     renderSection({ connectionMode: 'automatic' })
-    expect(screen.getByRole('combobox')).toBeVisible()
-    expect(
-      screen.getByText(/includes direct access and encrypted Orca Relay fallback/i)
-    ).toBeVisible()
+    expect(screen.getByText(/faster direct path when nearby/i)).toBeVisible()
+  })
+
+  it('disables generate when sign-in is required', () => {
+    // The sign-in explanation lives in the connection panel above, not here, so
+    // this section only gates the button rather than repeating the copy.
+    renderSection({ canGenerate: false })
+    expect(screen.getByRole('button', { name: 'Generate QR code' })).toBeDisabled()
+    expect(screen.queryByText(/Sign in above first/i)).toBeNull()
   })
 
   it('commits an OS interface picked from the list', async () => {
@@ -65,9 +84,9 @@ describe('MobilePairingSetupSection', () => {
     expect(onSelectedAddressChange).toHaveBeenCalledWith('192.168.1.24')
   })
 
-  it('generates a pairing code with the selected mode', async () => {
+  it('generates a pairing code', async () => {
     const { user, onGenerateQr } = renderSection()
-    await user.click(screen.getByRole('button', { name: 'Generate QR Code' }))
+    await user.click(screen.getByRole('button', { name: 'Generate QR code' }))
     expect(onGenerateQr).toHaveBeenCalledOnce()
   })
 })
diff --git a/src/renderer/src/components/settings/MobilePairingSetupSection.tsx b/src/renderer/src/components/settings/MobilePairingSetupSection.tsx
index caf1f6b6873..2f5453013b9 100644
--- a/src/renderer/src/components/settings/MobilePairingSetupSection.tsx
+++ b/src/renderer/src/components/settings/MobilePairingSetupSection.tsx
@@ -1,6 +1,5 @@
 import type { ReactNode } from 'react'
-import { ExternalLink, Loader2, QrCode, RefreshCw } from 'lucide-react'
-import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '../ui/accordion'
+import { Loader2, QrCode, RefreshCw } from 'lucide-react'
 import { Button } from '../ui/button'
 import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
 import { translate } from '@/i18n/i18n'
@@ -8,11 +7,11 @@ import { NetworkInterfacePicker } from '../mobile/NetworkInterfacePicker'
 import type { MobileNetworkInterface } from './mobile-network-interface-selection'
 import type { MobilePairingConnectionMode } from '../../../../shared/mobile-pairing-connection-mode'
 
-const TAILSCALE_DOWNLOAD_URL = 'https://tailscale.com/download'
-
 type MobilePairingSetupSectionProps = {
   connectionMode: MobilePairingConnectionMode
-  relayConnectionControl: ReactNode
+  /** False when Anywhere is selected but Relay cannot be committed yet. */
+  canGenerate?: boolean
+  connectionPathControl: ReactNode
   networkInterfaces: MobileNetworkInterface[]
   selectedAddress: string | undefined
   onSelectedAddressChange: (address: string) => void
@@ -25,7 +24,8 @@ type MobilePairingSetupSectionProps = {
 
 export function MobilePairingSetupSection({
   connectionMode,
-  relayConnectionControl,
+  canGenerate = true,
+  connectionPathControl,
   networkInterfaces,
   selectedAddress,
   onSelectedAddressChange,
@@ -35,60 +35,38 @@ export function MobilePairingSetupSection({
   hasQrCode,
   onGenerateQr
 }: MobilePairingSetupSectionProps): React.JSX.Element {
-  return (
-    <section>
-      <h3 className="text-sm font-medium">
-        {translate('auto.components.settings.MobilePairingSetupSection.title', 'Pair a phone')}
-      </h3>
-      <p className="mt-1 text-xs text-muted-foreground">
-        {connectionMode === 'automatic'
-          ? translate(
-              'auto.components.settings.MobilePairingSetupSection.automaticDescription',
-              'The pairing code includes direct access and encrypted Orca Relay fallback.'
-            )
-          : translate(
-              'auto.components.settings.MobilePairingSetupSection.localDescription',
-              'The pairing code connects only through the local network address below.'
-            )}
-      </p>
-      <div className="mt-2">{relayConnectionControl}</div>
-      <Button
-        onClick={onGenerateQr}
-        disabled={loading || !selectedAddress}
-        size="sm"
-        className="mt-3 gap-1.5"
-      >
-        {loading ? (
-          <Loader2 className="size-3.5 animate-spin" />
-        ) : hasQrCode ? (
-          <RefreshCw className="size-3.5" />
-        ) : (
-          <QrCode className="size-3.5" />
-        )}
-        {hasQrCode
-          ? translate('auto.components.settings.MobilePairingSetupSection.regenerate', 'Regenerate')
-          : translate(
-              'auto.components.settings.MobilePairingSetupSection.generate',
-              'Generate QR Code'
-            )}
-      </Button>
+  const usingRelay = connectionMode === 'automatic'
+  const generateDisabled = loading || !selectedAddress || !canGenerate
 
-      <div className="mt-4 space-y-3 border-t border-border/60 pt-4">
-        <div className="space-y-1">
-          <h4 className="text-xs font-medium">
-            {translate(
-              'auto.components.settings.MobilePairingSetupSection.localSettings',
-              'Local connection settings'
-            )}
-          </h4>
-          <p className="text-xs text-muted-foreground">
-            {translate(
-              'auto.components.settings.MobilePairingSetupSection.localAddressDescription',
-              'Choose the LAN or private-network address that Orca Mobile can use to reach this computer directly.'
-            )}
-          </p>
-        </div>
-        <div className="flex flex-wrap items-center gap-3">
+  return (
+    <section className="space-y-5">
+      <div className="space-y-1">
+        <h3 className="text-sm font-medium">
+          {translate('auto.components.settings.MobilePairingSetupSection.title', 'Pair a phone')}
+        </h3>
+        <p className="text-xs text-muted-foreground">
+          {translate(
+            'auto.components.settings.MobilePairingSetupSection.overview',
+            'Generate a QR code, then scan it in Orca Mobile under Pair Desktop.'
+          )}
+        </p>
+      </div>
+
+      <div className="space-y-2">
+        <p className="text-xs font-medium text-foreground">
+          {translate('auto.components.settings.MobilePairingSetupSection.step1Title', 'Connection')}
+        </p>
+        {connectionPathControl}
+      </div>
+
+      <div className="space-y-2">
+        <p className="text-xs font-medium text-foreground">
+          {translate(
+            'auto.components.settings.MobilePairingSetupSection.step2Title',
+            'This computer’s address'
+          )}
+        </p>
+        <div className="flex flex-wrap items-center gap-2">
           <NetworkInterfacePicker
             networkInterfaces={networkInterfaces}
             selectedAddress={selectedAddress}
@@ -120,37 +98,39 @@ export function MobilePairingSetupSection({
             </TooltipContent>
           </Tooltip>
         </div>
+        <p className="text-xs text-muted-foreground">
+          {usingRelay
+            ? translate(
+                'auto.components.settings.MobilePairingSetupSection.step2RelayDescription',
+                'Used for a faster direct path when nearby. Relay covers remote access.'
+              )
+            : translate(
+                'auto.components.settings.MobilePairingSetupSection.step2LocalDescription',
+                'The phone must be able to reach this address on Wi‑Fi or Tailscale.'
+              )}
+        </p>
       </div>
 
-      <Accordion type="single" collapsible className="mt-2">
-        <AccordionItem value="tailnet-guide" className="border-b-0">
-          <AccordionTrigger className="py-2 text-xs">
-            {translate(
-              'auto.components.settings.MobilePairingSetupSection.tailnet',
-              'Connect with your own tailnet'
-            )}
-          </AccordionTrigger>
-          <AccordionContent className="space-y-3 text-xs text-muted-foreground">
-            <p>
-              {translate(
-                'auto.components.settings.MobilePairingSetupSection.tailnetDescription',
-                'Install Tailscale on this computer and your phone, sign in to the same tailnet, then select its 100.x.y.z address above.'
+      <div className="space-y-2">
+        <Button onClick={onGenerateQr} disabled={generateDisabled} size="sm" className="gap-1.5">
+          {loading ? (
+            <Loader2 className="size-3.5 animate-spin" />
+          ) : hasQrCode ? (
+            <RefreshCw className="size-3.5" />
+          ) : (
+            <QrCode className="size-3.5" />
+          )}
+          {hasQrCode
+            ? translate(
+                'auto.components.settings.MobilePairingSetupSection.regenerate',
+                'Regenerate QR code'
+              )
+            : translate(
+                'auto.components.settings.MobilePairingSetupSection.generate',
+                'Generate QR code'
               )}
-            </p>
-            <button
-              type="button"
-              onClick={() => void window.api.shell.openUrl(TAILSCALE_DOWNLOAD_URL)}
-              className="inline-flex items-center gap-1 font-medium text-foreground underline-offset-2 hover:underline"
-            >
-              {translate(
-                'auto.components.settings.MobilePairingSetupSection.getTailscale',
-                'Get Tailscale'
-              )}
-              <ExternalLink className="size-3" />
-            </button>
-          </AccordionContent>
-        </AccordionItem>
-      </Accordion>
+        </Button>
+      </div>
     </section>
   )
 }
diff --git a/src/renderer/src/components/settings/MobilePane.test.tsx b/src/renderer/src/components/settings/MobilePane.test.tsx
index 3a7eb23eff0..2b7986f7959 100644
--- a/src/renderer/src/components/settings/MobilePane.test.tsx
+++ b/src/renderer/src/components/settings/MobilePane.test.tsx
@@ -1,12 +1,17 @@
 // @vitest-environment happy-dom
 
+import '@testing-library/jest-dom/vitest'
+
 import { act } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import {
   _resetPairedMobileDevicesCacheForTests,
   type PairedMobileDevice
 } from '../mobile/paired-mobile-devices'
+import type { MobilePairingConnectionMode } from '../../../../shared/mobile-pairing-connection-mode'
 
 type PairedDevice = PairedMobileDevice
 
@@ -17,62 +22,351 @@ type PairedDevicesProps = {
 }
 
 type StoreState = {
+  orcaProfileAuthStatus: { state: 'connected' | 'local' }
   settings: {
     mobileAutoRestoreFitMs: number | null
+    mobilePairingConnectionMode?: MobilePairingConnectionMode
   }
-  updateSettings: (settings: { mobileAutoRestoreFitMs: number | null }) => void
+  updateSettings: (patch: Record<string, unknown>) => Promise<void>
+  recordFeatureInteraction: (feature: string) => void
 }
 
-const mocks = vi.hoisted(() => ({
-  latestPairedDevicesProps: null as PairedDevicesProps | null,
-  listDevices: vi.fn(),
-  listNetworkInterfaces: vi.fn(),
-  revokeDevice: vi.fn(),
-  toastError: vi.fn(),
-  toastSuccess: vi.fn(),
-  updateSettings: vi.fn()
-}))
+const mocks = vi.hoisted(() => {
+  const holder: { state: StoreState } = { state: {} as StoreState }
+  const useAppStore = Object.assign(
+    (selector: (state: StoreState) => unknown) => selector(holder.state),
+    { getState: () => holder.state }
+  )
+  return {
+    holder,
+    useAppStore,
+    latestPairedDevicesProps: null as PairedDevicesProps | null,
+    getPairingQR: vi.fn(),
+    listDevices: vi.fn(),
+    listNetworkInterfaces: vi.fn(),
+    revokeDevice: vi.fn(),
+    toastError: vi.fn(),
+    toastSuccess: vi.fn(),
+    updateSettings: vi.fn()
+  }
+})
 
-vi.mock('../../store', () => ({
-  useAppStore: (selector: (state: StoreState) => unknown) =>
-    selector({
-      settings: { mobileAutoRestoreFitMs: null },
-      updateSettings: mocks.updateSettings
-    })
-}))
+vi.mock('@/store', () => ({ useAppStore: mocks.useAppStore }))
+vi.mock('../../store', () => ({ useAppStore: mocks.useAppStore }))
 
+vi.mock('@/i18n/i18n', () => ({ translate: (_key: string, fallback: string) => fallback }))
 vi.mock('sonner', () => ({
   toast: {
     error: mocks.toastError,
     success: mocks.toastSuccess
   }
 }))
+vi.mock('./mobile-pairing-device-polling', () => ({ useMobilePairingDevicePolling: vi.fn() }))
 
-vi.mock('./MobileNetworkInterfaceSection', () => ({
-  MobileNetworkInterfaceSection: () => null
-}))
-
+// Stub the child sections so the test targets MobilePane's own connection-mode
+// safety wiring (effective mode, canGenerate gate, persistence) in isolation.
 vi.mock('./MobilePairingSetupSection', () => ({
-  MobilePairingSetupSection: () => null
+  MobilePairingSetupSection: (props: {
+    connectionMode: MobilePairingConnectionMode
+    canGenerate?: boolean
+    loading: boolean
+    connectionPathControl: React.ReactNode
+    onGenerateQr: () => void
+  }) => (
+    <div>
+      <span data-testid="mode">{props.connectionMode}</span>
+      <span data-testid="can-generate">{String(props.canGenerate)}</span>
+      <span data-testid="loading">{String(props.loading)}</span>
+      {props.connectionPathControl}
+      {/* Mirror the real Generate gate (loading/canGenerate) so a stuck
+          loading flag surfaces as a disabled control the tests can catch. */}
+      <button
+        type="button"
+        onClick={props.onGenerateQr}
+        disabled={props.loading || props.canGenerate === false}
+      >
+        Generate
+      </button>
+    </div>
+  )
+}))
+vi.mock('./MobilePairingConnectionOptions', () => ({
+  MobilePairingConnectionOptions: (props: {
+    onChange: (mode: MobilePairingConnectionMode) => void
+  }) => (
+    <div>
+      <button type="button" onClick={() => props.onChange('automatic')}>
+        choose-anywhere
+      </button>
+      <button type="button" onClick={() => props.onChange('local-only')}>
+        choose-local
+      </button>
+    </div>
+  )
 }))
-
 vi.mock('./MobilePairingQrSection', () => ({
-  MobilePairingQrSection: () => null
+  MobilePairingQrSection: (props: { qrDataUrl: string | null }) => (
+    <span data-testid="qr">{props.qrDataUrl ?? 'none'}</span>
+  )
 }))
-
-vi.mock('./MobileAutoRestoreFitSection', () => ({
-  MobileAutoRestoreFitSection: () => null
-}))
-
 vi.mock('./MobilePairedDevicesSection', () => ({
   MobilePairedDevicesSection: (props: PairedDevicesProps) => {
     mocks.latestPairedDevicesProps = props
     return <div data-testid="paired-devices">{props.devices.map((d) => d.deviceId).join(',')}</div>
   }
 }))
+vi.mock('./MobileAutoRestoreFitSection', () => ({ MobileAutoRestoreFitSection: () => <div /> }))
+vi.mock('../mobile/WindowsFirewallNotice', () => ({ WindowsFirewallNotice: () => <div /> }))
 
 import { MobilePane } from './MobilePane'
 
+describe('MobilePane pairing connection mode', () => {
+  const getPairingQR = mocks.getPairingQR
+  const updateSettings = mocks.updateSettings
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    _resetPairedMobileDevicesCacheForTests()
+    mocks.latestPairedDevicesProps = null
+    getPairingQR.mockReset().mockResolvedValue({
+      available: true,
+      qrDataUrl: 'data:image/png;base64,qr',
+      pairingUrl: 'orca://pair',
+      endpoint: 'ws://host',
+      connectionMode: 'automatic'
+    })
+    mocks.listDevices.mockReset().mockResolvedValue({ devices: [] })
+    mocks.listNetworkInterfaces.mockReset().mockResolvedValue({ interfaces: [] })
+    mocks.revokeDevice.mockReset().mockResolvedValue({ revoked: true })
+    updateSettings.mockReset().mockResolvedValue(undefined)
+    mocks.holder.state = {
+      orcaProfileAuthStatus: { state: 'connected' },
+      settings: { mobileAutoRestoreFitMs: null },
+      updateSettings,
+      recordFeatureInteraction: vi.fn()
+    }
+    Object.defineProperty(window, 'api', {
+      configurable: true,
+      value: {
+        mobile: {
+          getPairingQR,
+          listDevices: mocks.listDevices,
+          listNetworkInterfaces: mocks.listNetworkInterfaces,
+          revokeDevice: mocks.revokeDevice
+        }
+      }
+    })
+  })
+
+  afterEach(() => {
+    cleanup()
+    _resetPairedMobileDevicesCacheForTests()
+    document.body.innerHTML = ''
+  })
+
+  it('defaults to Anywhere and issues an automatic QR when signed in', async () => {
+    const user = userEvent.setup()
+    render(<MobilePane />)
+    expect(screen.getByTestId('mode')).toHaveTextContent('automatic')
+    expect(screen.getByTestId('can-generate')).toHaveTextContent('true')
+
+    await user.click(screen.getByRole('button', { name: 'Generate' }))
+    await waitFor(() => expect(getPairingQR).toHaveBeenCalledWith({ connectionMode: 'automatic' }))
+  })
+
+  it('keeps Anywhere selected but blocks generation when signed out', async () => {
+    mocks.holder.state.orcaProfileAuthStatus = { state: 'local' }
+    const user = userEvent.setup()
+    render(<MobilePane />)
+    expect(screen.getByTestId('mode')).toHaveTextContent('automatic')
+    // Why: the signed-out desktop cannot serve Relay, so Generate is gated off
+    // and no misleading local-only QR is minted under the Relay label.
+    expect(screen.getByTestId('can-generate')).toHaveTextContent('false')
+    expect(screen.getByRole('button', { name: 'Generate' })).toBeDisabled()
+
+    await user.click(screen.getByRole('button', { name: 'Generate' }))
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    expect(getPairingQR).not.toHaveBeenCalled()
+  })
+
+  it('flags an Anywhere mint that degraded to a local-only code', async () => {
+    getPairingQR.mockResolvedValue({
+      available: true,
+      qrDataUrl: 'data:image/png;base64,qr',
+      pairingUrl: 'orca://pair#degraded',
+      endpoint: 'ws://host',
+      // Relay provisioning failed server-side; the offer encodes local-only.
+      connectionMode: 'local-only'
+    })
+    const user = userEvent.setup()
+    render(<MobilePane />)
+
+    await user.click(screen.getByRole('button', { name: 'Generate' }))
+    await waitFor(() =>
+      expect(screen.getByTestId('relay-degraded-notice')).toHaveTextContent(
+        'only works on your local network'
+      )
+    )
+
+    // Switching to Local network clears the mismatch along with the QR.
+    await user.click(screen.getByRole('button', { name: 'choose-local' }))
+    await waitFor(() =>
+      expect(screen.queryByTestId('relay-degraded-notice')).not.toBeInTheDocument()
+    )
+  })
+
+  it('does not flag an honest Relay mint', async () => {
+    const user = userEvent.setup()
+    render(<MobilePane />)
+
+    await user.click(screen.getByRole('button', { name: 'Generate' }))
+    await waitFor(() => expect(screen.getByTestId('qr')).toHaveTextContent('base64,qr'))
+    expect(screen.queryByTestId('relay-degraded-notice')).not.toBeInTheDocument()
+  })
+
+  it('persists the chosen path when the mode changes', async () => {
+    const user = userEvent.setup()
+    render(<MobilePane />)
+    await user.click(screen.getByRole('button', { name: 'choose-local' }))
+    expect(updateSettings).toHaveBeenCalledWith({ mobilePairingConnectionMode: 'local-only' })
+    expect(screen.getByTestId('mode')).toHaveTextContent('local-only')
+  })
+
+  it('restores a saved local-only preference without user interaction', () => {
+    mocks.holder.state.settings = {
+      mobileAutoRestoreFitMs: null,
+      mobilePairingConnectionMode: 'local-only'
+    }
+    render(<MobilePane />)
+    expect(screen.getByTestId('mode')).toHaveTextContent('local-only')
+  })
+
+  it('discards a Relay QR that resolves after signing out mid-generate', async () => {
+    const user = userEvent.setup()
+    let resolveQr: ((value: Record<string, unknown>) => void) | undefined
+    getPairingQR.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveQr = resolve
+        })
+    )
+    const { rerender } = render(<MobilePane />)
+    await user.click(screen.getByRole('button', { name: 'Generate' }))
+    await waitFor(() => expect(getPairingQR).toHaveBeenCalledWith({ connectionMode: 'automatic' }))
+
+    // Sign out while the Relay mint is still in flight.
+    mocks.holder.state.orcaProfileAuthStatus = { state: 'local' }
+    rerender(<MobilePane />)
+
+    // The superseded response arrives; it must not paint a QR on a desktop that
+    // can no longer serve Relay.
+    resolveQr?.({
+      available: true,
+      qrDataUrl: 'data:image/png;base64,relay',
+      pairingUrl: 'orca://relay',
+      endpoint: 'ws://relay'
+    })
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    expect(screen.getByTestId('qr')).toHaveTextContent('none')
+  })
+
+  it('drops loading and re-enables Generate after signing out mid-generate', async () => {
+    const user = userEvent.setup()
+    let resolveQr: ((value: Record<string, unknown>) => void) | undefined
+    getPairingQR.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveQr = resolve
+        })
+    )
+    const { rerender } = render(<MobilePane />)
+    await user.click(screen.getByRole('button', { name: 'Generate' }))
+    await waitFor(() => expect(getPairingQR).toHaveBeenCalledWith({ connectionMode: 'automatic' }))
+    // The hung generate holds the spinner up.
+    expect(screen.getByTestId('loading')).toHaveTextContent('true')
+
+    // Sign out while the Relay mint is still in flight; the superseded request
+    // must drop loading so Generate isn't wedged disabled forever.
+    mocks.holder.state.orcaProfileAuthStatus = { state: 'local' }
+    rerender(<MobilePane />)
+    await waitFor(() => expect(screen.getByTestId('loading')).toHaveTextContent('false'))
+
+    // The late response resolves but must not resurrect the spinner.
+    resolveQr?.({
+      available: true,
+      qrDataUrl: 'data:image/png;base64,relay',
+      pairingUrl: 'orca://relay',
+      endpoint: 'ws://relay'
+    })
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    expect(screen.getByTestId('loading')).toHaveTextContent('false')
+
+    // Switching to Local network re-enables Generate (no signed-in gate).
+    await user.click(screen.getByRole('button', { name: 'choose-local' }))
+    expect(screen.getByRole('button', { name: 'Generate' })).toBeEnabled()
+  })
+
+  it('drops loading after switching path mid-generate', async () => {
+    const user = userEvent.setup()
+    getPairingQR.mockImplementationOnce(() => new Promise(() => {}))
+    render(<MobilePane />)
+    await user.click(screen.getByRole('button', { name: 'Generate' }))
+    await waitFor(() => expect(getPairingQR).toHaveBeenCalledWith({ connectionMode: 'automatic' }))
+    expect(screen.getByTestId('loading')).toHaveTextContent('true')
+
+    // Switch to Local network before the mint resolves; loading must clear so
+    // Generate can be used again for the new path.
+    await user.click(screen.getByRole('button', { name: 'choose-local' }))
+    await waitFor(() => expect(screen.getByTestId('loading')).toHaveTextContent('false'))
+    expect(screen.getByRole('button', { name: 'Generate' })).toBeEnabled()
+  })
+
+  it('clears a shown QR when another window changes the saved path', async () => {
+    const user = userEvent.setup()
+    const { rerender } = render(<MobilePane />)
+    await user.click(screen.getByRole('button', { name: 'Generate' }))
+    await waitFor(() => expect(screen.getByTestId('qr')).toHaveTextContent('base64,qr'))
+
+    // Another window persists a new path; the shared hook syncs it in without
+    // routing through changeConnectionMode.
+    mocks.holder.state.settings = {
+      mobileAutoRestoreFitMs: null,
+      mobilePairingConnectionMode: 'local-only'
+    }
+    rerender(<MobilePane />)
+
+    await waitFor(() => expect(screen.getByTestId('mode')).toHaveTextContent('local-only'))
+    expect(screen.getByTestId('qr')).toHaveTextContent('none')
+  })
+
+  it('discards a QR that resolves after switching path mid-generate', async () => {
+    const user = userEvent.setup()
+    let resolveQr: ((value: Record<string, unknown>) => void) | undefined
+    getPairingQR.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveQr = resolve
+        })
+    )
+    render(<MobilePane />)
+    await user.click(screen.getByRole('button', { name: 'Generate' }))
+    await waitFor(() => expect(getPairingQR).toHaveBeenCalledWith({ connectionMode: 'automatic' }))
+
+    // Switch to Local network before the Relay mint resolves.
+    await user.click(screen.getByRole('button', { name: 'choose-local' }))
+
+    resolveQr?.({
+      available: true,
+      qrDataUrl: 'data:image/png;base64,relay',
+      pairingUrl: 'orca://relay',
+      endpoint: 'ws://relay'
+    })
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    expect(screen.getByTestId('qr')).toHaveTextContent('none')
+    expect(screen.getByTestId('mode')).toHaveTextContent('local-only')
+  })
+})
+
 const mountedRoots: Root[] = []
 
 function pairedDevice(deviceId: string): PairedDevice {
@@ -105,23 +399,40 @@ async function unmountMobilePaneRoots(): Promise<void> {
 describe('MobilePane', () => {
   beforeEach(() => {
     vi.clearAllMocks()
-    mocks.latestPairedDevicesProps = null
     _resetPairedMobileDevicesCacheForTests()
+    mocks.latestPairedDevicesProps = null
+    mocks.getPairingQR.mockReset().mockResolvedValue({
+      available: true,
+      qrDataUrl: 'data:image/png;base64,qr',
+      pairingUrl: 'orca://pair',
+      endpoint: 'ws://host'
+    })
+    mocks.listDevices.mockReset()
+    mocks.listNetworkInterfaces.mockReset().mockResolvedValue({ interfaces: [] })
+    mocks.revokeDevice.mockReset()
+    mocks.updateSettings.mockReset().mockResolvedValue(undefined)
+    mocks.holder.state = {
+      orcaProfileAuthStatus: { state: 'connected' },
+      settings: { mobileAutoRestoreFitMs: null },
+      updateSettings: mocks.updateSettings,
+      recordFeatureInteraction: vi.fn()
+    }
     Object.defineProperty(window, 'api', {
       configurable: true,
       value: {
         mobile: {
+          getPairingQR: mocks.getPairingQR,
           listDevices: mocks.listDevices,
           listNetworkInterfaces: mocks.listNetworkInterfaces,
           revokeDevice: mocks.revokeDevice
         }
       }
     })
-    mocks.listNetworkInterfaces.mockResolvedValue({ interfaces: [] })
   })
 
   afterEach(async () => {
     await unmountMobilePaneRoots()
+    _resetPairedMobileDevicesCacheForTests()
     document.body.innerHTML = ''
   })
 
diff --git a/src/renderer/src/components/settings/MobilePane.tsx b/src/renderer/src/components/settings/MobilePane.tsx
index 0d001142cd6..35b0e1cbc05 100644
--- a/src/renderer/src/components/settings/MobilePane.tsx
+++ b/src/renderer/src/components/settings/MobilePane.tsx
@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
+import { CircleAlert } from 'lucide-react'
 import { toast } from 'sonner'
 import { useAppStore } from '../../store'
 import { useMountedRef } from '@/hooks/useMountedRef'
@@ -19,7 +20,11 @@ import { MobilePairingConnectionOptions } from './MobilePairingConnectionOptions
 import { MobilePairingSetupSection } from './MobilePairingSetupSection'
 import { WindowsFirewallNotice } from '../mobile/WindowsFirewallNotice'
 import { translate } from '@/i18n/i18n'
-import type { MobilePairingConnectionMode } from '../../../../shared/mobile-pairing-connection-mode'
+import {
+  canMintMobilePairingOffer,
+  type MobilePairingConnectionMode
+} from '../../../../shared/mobile-pairing-connection-mode'
+import { useMobilePairingConnectionMode } from '../mobile/use-mobile-pairing-connection-mode'
 export { getMobilePaneSearchEntries } from './mobile-pane-search'
 
 export function MobilePane(): React.JSX.Element {
@@ -27,6 +32,9 @@ export function MobilePane(): React.JSX.Element {
   const updateSettings = useAppStore((s) => s.updateSettings)
   const [qrDataUrl, setQrDataUrl] = useState<string | null>(null)
   const [pairingUrl, setPairingUrl] = useState<string | null>(null)
+  // Mode the displayed QR actually encodes; can be 'local-only' under an
+  // Anywhere selection when Relay provisioning degraded server-side.
+  const [qrEncodedMode, setQrEncodedMode] = useState<MobilePairingConnectionMode | null>(null)
   const [endpoint, setEndpoint] = useState<string | null>(null)
   const [loading, setLoading] = useState(false)
   const [qrEnlarged, setQrEnlarged] = useState(false)
@@ -36,12 +44,23 @@ export function MobilePane(): React.JSX.Element {
   const [codeCopied, setCodeCopied] = useState(false)
   const [deviceCountAtQr, setDeviceCountAtQr] = useState<number | null>(null)
   const signedIn = useAppStore((state) => state.orcaProfileAuthStatus?.state === 'connected')
-  // Why: Relay is opt-in while compatible mobile builds are limited to the
-  // TestFlight preview and Android APK.
-  const [connectionMode, setConnectionMode] = useState<MobilePairingConnectionMode>('local-only')
+  const [connectionMode, setConnectionMode] = useMobilePairingConnectionMode()
   const [rotateNextQr, setRotateNextQr] = useState(false)
-  const wasSignedInRef = useRef(signedIn)
   const codeCopiedResetTimerRef = useRef<number | null>(null)
+  const wasSignedInRef = useRef(signedIn)
+  // Why: monotonically bumped per pairing request so a late getPairingQR
+  // response cannot paint a stale QR after sign-out, a mode switch, or an
+  // address change invalidated the request that produced it.
+  const pairingRequestIdRef = useRef(0)
+  // Tracks the mode we last acted on so the connectionMode effect can tell a
+  // cross-window preference sync apart from our own path change.
+  const handledModeRef = useRef(connectionMode)
+  // Latest address without stale-closure risk inside loadNetworkInterfaces.
+  const selectedAddressRef = useRef<string | undefined>(selectedAddress)
+  // Ref mirrors of QR-visible / loading so invalidatePairing stays stable and
+  // cannot make loadNetworkInterfaces re-fetch on every generate.
+  const qrDisplayedRef = useRef(false)
+  const loadingRef = useRef(false)
   const mountedRef = useMountedRef()
   const {
     devices,
@@ -49,6 +68,50 @@ export function MobilePane(): React.JSX.Element {
     refresh: refreshDevices
   } = usePairedMobileDevices({ refreshOnMount: false })
 
+  useEffect(() => {
+    qrDisplayedRef.current = qrDataUrl != null
+  }, [qrDataUrl])
+
+  useEffect(() => {
+    loadingRef.current = loading
+  }, [loading])
+
+  // Why: an offer encodes a specific policy + endpoint. When the selection that
+  // produced it changes, drop any displayed QR and invalidate the in-flight
+  // request so a late response can't restore it; arm rotation so the next mint
+  // issues a fresh credential rather than the discarded pending one.
+  const invalidatePairing = useCallback((opts: { armRotate?: boolean } = {}): void => {
+    pairingRequestIdRef.current += 1
+    const hadPending = qrDisplayedRef.current || loadingRef.current
+    setQrDataUrl(null)
+    setPairingUrl(null)
+    setQrEncodedMode(null)
+    setEndpoint(null)
+    // Why: a superseded in-flight generate no longer clears loading in its
+    // finally (the epoch bump skips it), so drop the spinner here or Generate
+    // stays disabled forever after a mid-flight path/sign-out/address change.
+    loadingRef.current = false
+    setLoading(false)
+    // armRotate:false for path changes — the main process rotates exactly once
+    // when the requested mode differs from the pending token's minted mode, so
+    // an extra renderer rotate would only race other windows off the new token.
+    if (hadPending && opts.armRotate !== false) {
+      setRotateNextQr(true)
+    }
+  }, [])
+
+  // Why: a Relay QR minted while signed in must not linger on a now-signed-out
+  // desktop — Generate is disabled in that state. Invalidate any pending relay
+  // mint too, not just a displayed QR, so a late response can't paint a Relay
+  // code after sign-out. Anywhere stays selected.
+  useEffect(() => {
+    const wasSignedIn = wasSignedInRef.current
+    wasSignedInRef.current = signedIn
+    if (wasSignedIn && !signedIn && connectionMode === 'automatic') {
+      invalidatePairing()
+    }
+  }, [signedIn, connectionMode, invalidatePairing])
+
   const clearCodeCopiedResetTimer = useCallback((): void => {
     if (codeCopiedResetTimerRef.current !== null) {
       window.clearTimeout(codeCopiedResetTimerRef.current)
@@ -71,9 +134,17 @@ export function MobilePane(): React.JSX.Element {
         const result = await window.api.mobile.listNetworkInterfaces()
         if (mountedRef.current) {
           setNetworkInterfaces(result.interfaces)
-          setSelectedAddress((currentAddress) =>
-            selectRefreshedNetworkAddress(currentAddress, result.interfaces)
+          const nextAddress = selectRefreshedNetworkAddress(
+            selectedAddressRef.current,
+            result.interfaces
           )
+          if (nextAddress !== selectedAddressRef.current) {
+            selectedAddressRef.current = nextAddress
+            setSelectedAddress(nextAddress)
+            // A refresh moved the active interface; invalidate so a shown QR
+            // can't keep encoding the previous endpoint.
+            invalidatePairing()
+          }
         }
       } catch {
         if (opts.notifyOnError && mountedRef.current) {
@@ -90,23 +161,38 @@ export function MobilePane(): React.JSX.Element {
         }
       }
     },
-    [mountedRef]
+    [mountedRef, invalidatePairing]
   )
 
   const generateQR = useCallback(
     async (opts: { rotate?: boolean } = {}) => {
+      // Why: refuse signed-out Anywhere rather than degrading to a local-only QR
+      // under the Relay label (canMint is the shared honesty gate).
+      if (!canMintMobilePairingOffer({ connectionMode, signedIn })) {
+        return
+      }
+      const requestId = ++pairingRequestIdRef.current
       setLoading(true)
       try {
         const result = await window.api.mobile.getPairingQR({
           ...(selectedAddress ? { address: selectedAddress } : {}),
+          // canMint already requires sign-in for Anywhere, so the preferred path
+          // is the honest encoded mode.
           connectionMode,
           ...(opts.rotate || rotateNextQr ? { rotate: true } : {})
         })
+        // Why: sign-out, a mode switch, or an address change bump the epoch.
+        // A response for a superseded request must not paint a QR that no
+        // longer matches the current selection.
+        if (requestId !== pairingRequestIdRef.current) {
+          return
+        }
         if (result.available) {
           useAppStore.getState().recordFeatureInteraction('mobile-pairing')
           if (mountedRef.current) {
             setQrDataUrl(result.qrDataUrl)
             setPairingUrl(result.pairingUrl)
+            setQrEncodedMode(result.connectionMode)
             setEndpoint(result.endpoint)
             setDeviceCountAtQr(getPairedMobileDevicesSnapshot().length)
             clearCodeCopiedResetTimer()
@@ -125,7 +211,7 @@ export function MobilePane(): React.JSX.Element {
           }
         }
       } catch {
-        if (mountedRef.current) {
+        if (mountedRef.current && requestId === pairingRequestIdRef.current) {
           toast.error(
             translate(
               'auto.components.settings.MobilePane.e3c427e020',
@@ -134,7 +220,7 @@ export function MobilePane(): React.JSX.Element {
           )
         }
       } finally {
-        if (mountedRef.current) {
+        if (mountedRef.current && requestId === pairingRequestIdRef.current) {
           setLoading(false)
         }
       }
@@ -145,7 +231,8 @@ export function MobilePane(): React.JSX.Element {
       loadDevices,
       mountedRef,
       rotateNextQr,
-      selectedAddress
+      selectedAddress,
+      signedIn
     ]
   )
 
@@ -154,19 +241,40 @@ export function MobilePane(): React.JSX.Element {
       if (nextMode === connectionMode) {
         return
       }
+      // Why: remember the path so reopening Settings keeps the user's choice
+      // instead of snapping back to the default.
+      handledModeRef.current = nextMode
       setConnectionMode(nextMode)
-      if (qrDataUrl) {
-        // Why: a displayed code encodes the old connection policy. Hide it and
-        // rotate its pending credential before showing a code for the new mode.
-        setQrDataUrl(null)
-        setPairingUrl(null)
-        setEndpoint(null)
-        setRotateNextQr(true)
-      }
+      void updateSettings({ mobilePairingConnectionMode: nextMode })
+      // A displayed or in-flight code encodes the old connection policy. The
+      // main process rotates on the mode mismatch, so don't arm a second rotate.
+      invalidatePairing({ armRotate: false })
     },
-    [connectionMode, qrDataUrl]
+    [connectionMode, invalidatePairing, updateSettings, setConnectionMode]
   )
 
+  const handleSelectedAddressChange = useCallback(
+    (address: string): void => {
+      setSelectedAddress(address)
+      selectedAddressRef.current = address
+      // Switching endpoints: a shown QR now encodes the old address.
+      invalidatePairing()
+    },
+    [invalidatePairing]
+  )
+
+  // Why: another window can persist a different path; the shared hook syncs
+  // connectionMode here without routing through changeConnectionMode. Treat
+  // that external change like a user path change so a QR for the old policy
+  // can't linger. No updateSettings call here — avoids a cross-window loop.
+  useEffect(() => {
+    if (connectionMode === handledModeRef.current) {
+      return
+    }
+    handledModeRef.current = connectionMode
+    invalidatePairing({ armRotate: false })
+  }, [connectionMode, invalidatePairing])
+
   useEffect(() => {
     void loadNetworkInterfaces()
   }, [loadNetworkInterfaces])
@@ -179,14 +287,6 @@ export function MobilePane(): React.JSX.Element {
     }
   }, [devicesLoaded, loadDevices])
 
-  useEffect(() => {
-    const wasSignedIn = wasSignedInRef.current
-    wasSignedInRef.current = signedIn
-    if (wasSignedIn && !signedIn) {
-      changeConnectionMode('local-only')
-    }
-  }, [changeConnectionMode, signedIn])
-
   useMobilePairingDevicePolling({
     deviceCountAtQr,
     currentDeviceCount: devices.length,
@@ -226,12 +326,13 @@ export function MobilePane(): React.JSX.Element {
     <div className="space-y-6">
       <MobilePairingSetupSection
         connectionMode={connectionMode}
-        relayConnectionControl={
+        canGenerate={canMintMobilePairingOffer({ connectionMode, signedIn })}
+        connectionPathControl={
           <MobilePairingConnectionOptions value={connectionMode} onChange={changeConnectionMode} />
         }
         networkInterfaces={networkInterfaces}
         selectedAddress={selectedAddress}
-        onSelectedAddressChange={setSelectedAddress}
+        onSelectedAddressChange={handleSelectedAddressChange}
         refreshingNetworkInterfaces={refreshingNetworkInterfaces}
         onRefreshNetworkInterfaces={() => void loadNetworkInterfaces({ notifyOnError: true })}
         loading={loading}
@@ -239,6 +340,23 @@ export function MobilePane(): React.JSX.Element {
         onGenerateQr={() => void generateQR({ rotate: qrDataUrl != null })}
       />
 
+      {qrDataUrl != null && connectionMode === 'automatic' && qrEncodedMode === 'local-only' ? (
+        // Why: an Anywhere mint can degrade server-side when Relay provisioning
+        // fails; say so instead of letting the Relay label overclaim the code.
+        <div
+          className="flex items-start gap-2.5 rounded-lg border border-border bg-muted/40 p-3"
+          data-testid="relay-degraded-notice"
+        >
+          <CircleAlert className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
+          <p className="text-xs text-muted-foreground">
+            {translate(
+              'auto.components.settings.MobilePane.relayDegradedNotice',
+              'Relay couldn’t be reached — this code only works on your local network. Regenerate to try again.'
+            )}
+          </p>
+        </div>
+      ) : null}
+
       <MobilePairingQrSection
         qrDataUrl={qrDataUrl}
         pairingUrl={pairingUrl}
diff --git a/src/renderer/src/components/settings/MobileRelayBetaAvailability.tsx b/src/renderer/src/components/settings/MobileRelayBetaAvailability.tsx
deleted file mode 100644
index f49a32be99b..00000000000
--- a/src/renderer/src/components/settings/MobileRelayBetaAvailability.tsx
+++ /dev/null
@@ -1,40 +0,0 @@
-import { translate } from '@/i18n/i18n'
-
-const TESTFLIGHT_URL = 'https://testflight.apple.com/join/YjeGMQBA'
-const ANDROID_APK_URL =
-  'https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.31/app-release.apk'
-
-export function MobileRelayBetaAvailability(): React.JSX.Element {
-  return (
-    <span className="inline-flex flex-wrap items-baseline gap-x-1 text-[11px] text-muted-foreground">
-      <span className="font-medium text-foreground/80">
-        {translate('auto.components.settings.MobileRelayBetaAvailability.beta', 'Beta')}
-      </span>
-      <span aria-hidden="true">—</span>
-      <span>
-        {translate(
-          'auto.components.settings.MobileRelayBetaAvailability.availability',
-          'Available on'
-        )}
-      </span>
-      <button
-        type="button"
-        className="rounded-sm font-medium text-foreground underline decoration-border underline-offset-2 hover:decoration-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
-        onClick={() => void window.api.shell.openUrl(TESTFLIGHT_URL)}
-      >
-        {translate('auto.components.settings.MobileRelayBetaAvailability.testFlight', 'TestFlight')}
-      </button>
-      <span aria-hidden="true">/</span>
-      <button
-        type="button"
-        className="rounded-sm font-medium text-foreground underline decoration-border underline-offset-2 hover:decoration-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
-        onClick={() => void window.api.shell.openUrl(ANDROID_APK_URL)}
-      >
-        {translate(
-          'auto.components.settings.MobileRelayBetaAvailability.androidApk',
-          'Android APK'
-        )}
-      </button>
-    </span>
-  )
-}
diff --git a/src/renderer/src/components/settings/MobileRelayBetaNotice.tsx b/src/renderer/src/components/settings/MobileRelayBetaNotice.tsx
new file mode 100644
index 00000000000..5002689c10e
--- /dev/null
+++ b/src/renderer/src/components/settings/MobileRelayBetaNotice.tsx
@@ -0,0 +1,12 @@
+import { cn } from '@/lib/utils'
+import { translate } from '@/i18n/i18n'
+
+// Why: Relay ships in the public builds but is still beta; keep a quiet
+// qualifier wherever the Relay path is offered.
+export function MobileRelayBetaNotice({ className }: { className?: string }): React.JSX.Element {
+  return (
+    <p className={cn('text-[11px] text-muted-foreground', className)}>
+      {translate('auto.components.settings.MobileRelayBetaNotice.notice', 'Orca Relay is in beta.')}
+    </p>
+  )
+}
diff --git a/src/renderer/src/components/settings/MobileSettingsPane.tsx b/src/renderer/src/components/settings/MobileSettingsPane.tsx
index a6b72d3a6c0..36e1b33e068 100644
--- a/src/renderer/src/components/settings/MobileSettingsPane.tsx
+++ b/src/renderer/src/components/settings/MobileSettingsPane.tsx
@@ -8,6 +8,7 @@ import {
 } from './mobile-settings-search'
 import { translate } from '@/i18n/i18n'
 import { useAppStore } from '@/store'
+import { MobileRelayBetaNotice } from './MobileRelayBetaNotice'
 export { getMobileSettingsPaneSearchEntries }
 
 const ORCA_IOS_APP_STORE_URL = 'https://apps.apple.com/app/orca-ide/id6766130217'
@@ -29,33 +30,39 @@ export function MobileSettingsPane(): React.JSX.Element {
         keywords={getMobileOverviewSearchEntry().keywords}
         className="space-y-3 py-2"
       >
-        <p className="text-xs text-muted-foreground">
-          {translate(
-            'auto.components.settings.MobileSettingsPane.c8491c17ef',
-            'Control Orca from your phone by scanning a QR code. Get the iOS app from the'
-          )}{' '}
-          <button
-            type="button"
-            onClick={() => void window.api.shell.openUrl(ORCA_IOS_APP_STORE_URL)}
-            className="cursor-pointer underline underline-offset-2 hover:text-foreground"
-          >
-            {translate('auto.components.settings.MobileSettingsPane.b5a2ed83ff', 'App Store')}
-          </button>{' '}
-          {translate(
-            'auto.components.settings.MobileSettingsPane.b0088412a1',
-            'or the Android APK from'
-          )}{' '}
-          <button
-            type="button"
-            // Why: Android is moving to Google Play soon, but until then
-            // link directly to the pinned APK asset for the current mobile release.
-            onClick={() => void window.api.shell.openUrl(ORCA_ANDROID_APK_URL)}
-            className="cursor-pointer underline underline-offset-2 hover:text-foreground"
-          >
-            {translate('auto.components.settings.MobileSettingsPane.9a3c280e49', 'GitHub Releases')}
-          </button>
-          .
-        </p>
+        <div className="space-y-2 text-xs text-muted-foreground">
+          <p>
+            {translate(
+              'auto.components.settings.MobileSettingsPane.installIntro',
+              'Install Orca Mobile from the'
+            )}{' '}
+            <button
+              type="button"
+              onClick={() => void window.api.shell.openUrl(ORCA_IOS_APP_STORE_URL)}
+              className="cursor-pointer underline underline-offset-2 hover:text-foreground"
+            >
+              {translate('auto.components.settings.MobileSettingsPane.b5a2ed83ff', 'App Store')}
+            </button>
+            {' · '}
+            <button
+              type="button"
+              // Why: Android is moving to Google Play soon, but until then
+              // link directly to the pinned APK asset for the current mobile release.
+              onClick={() => void window.api.shell.openUrl(ORCA_ANDROID_APK_URL)}
+              className="cursor-pointer underline underline-offset-2 hover:text-foreground"
+            >
+              {translate(
+                'auto.components.settings.MobileSettingsPane.androidApkLabel',
+                'Android APK'
+              )}
+            </button>
+            {translate(
+              'auto.components.settings.MobileSettingsPane.installOutro',
+              ', then pair below.'
+            )}
+          </p>
+          <MobileRelayBetaNotice />
+        </div>
       </SearchableSetting>
 
       <SearchableSetting
diff --git a/src/renderer/src/components/settings/mobile-settings-search.ts b/src/renderer/src/components/settings/mobile-settings-search.ts
index a874bd1a163..6fce884fc12 100644
--- a/src/renderer/src/components/settings/mobile-settings-search.ts
+++ b/src/renderer/src/components/settings/mobile-settings-search.ts
@@ -20,6 +20,10 @@ export const getMobileOverviewSearchEntry = createLocalizedCatalog(
         'auto.components.settings.mobile.settings.search.f4ed142753',
         'phone'
       ),
+      ...translateSearchKeyword(
+        'auto.components.settings.mobile.settings.search.5d5af8e041',
+        'iphone'
+      ),
       ...translateSearchKeyword(
         'auto.components.settings.mobile.settings.search.cf2c93b479',
         'pair'
@@ -37,6 +41,10 @@ export const getMobileOverviewSearchEntry = createLocalizedCatalog(
         'auto.components.settings.mobile.settings.search.7e801801ac',
         'remote'
       ),
+      ...translateSearchKeyword(
+        'auto.components.settings.mobile.settings.search.e4f4daea0e',
+        'relay'
+      ),
       ...translateSearchKeyword(
         'auto.components.settings.mobile.settings.search.a7eececc1d',
         'android'
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 9bad363c2b3..06fe05685de 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -5955,12 +5955,16 @@
           "aa1263e881": "Keep at phone size (default)",
           "6436e56546": "QR Code for mobile pairing",
           "1b1b70279a": "No devices paired yet.",
-          "1592afcc7a": "No devices paired yet. Scan the QR code with the Orca mobile app."
+          "1592afcc7a": "No devices paired yet. Scan the QR code with the Orca mobile app.",
+          "relayDegradedNotice": "Relay couldn’t be reached — this code only works on your local network. Regenerate to try again."
         },
         "MobileSettingsPane": {
           "9a3c280e49": "GitHub Releases",
           "b0088412a1": "or the Android APK from",
           "b5a2ed83ff": "App Store",
+          "installIntro": "Install Orca Mobile from the",
+          "installOutro": ", then pair below.",
+          "androidApkLabel": "Android APK",
           "c8491c17ef": "Control Orca from your phone by scanning a QR code. Beta / early preview - expect bugs and breaking changes. Get the iOS app from the",
           "e7a3ae8c4e": "Mobile",
           "174f4a3c6d": "Control terminals and agents from your phone.",
@@ -8100,7 +8104,9 @@
               "671eb4173c": "Control terminals and agents from your phone.",
               "ffd52a96e4": "Mobile",
               "1de96ec8a6": "Show Orca Mobile Button",
-              "682293cadf": "Show the Orca Mobile button at the top of the left sidebar."
+              "682293cadf": "Show the Orca Mobile button at the top of the left sidebar.",
+              "e4f4daea0e": "relay",
+              "5d5af8e041": "iphone"
             }
           }
         },
@@ -9192,28 +9198,26 @@
           "available": "Available",
           "reconnecting": "Reconnecting",
           "unavailable": "Unavailable",
-          "title": "How should the new phone connect?",
-          "anywhere": "Connect with Orca Relay",
-          "recommended": "Recommended",
-          "automaticDescription": "Orca uses a direct connection when available and Relay otherwise.",
-          "signInDescription": "Sign in on this desktop to use Orca Relay.",
+          "pathGroup": "How the phone reaches this computer",
+          "anywhereTitle": "Orca Relay",
+          "anywhereDescription": "Phone can be on cellular or any Wi‑Fi. Sign-in required.",
+          "signInRequired": "Sign in to use Orca Mobile Relay.",
+          "relayUnavailable": "Orca Relay isn’t available in this build. Use Local network.",
           "signIn": "Sign in",
-          "localOnly": "Local network only",
-          "localShort": "LAN or Tailscale",
-          "localDescription": "Uses LAN or Tailscale without connecting this phone through Orca Relay."
+          "signInAgain": "Sign in again",
+          "localTitle": "Local network",
+          "localDescription": "Phone must be on this Wi‑Fi or your Tailscale. No sign-in."
         },
         "MobilePairingSetupSection": {
           "title": "Pair a phone",
-          "automaticDescription": "The pairing code includes direct access and encrypted Orca Relay fallback.",
-          "localDescription": "The pairing code connects only through the local network address below.",
-          "regenerate": "Regenerate",
-          "generate": "Generate QR Code",
-          "localSettings": "Local connection settings",
-          "localAddressDescription": "Choose the LAN or private-network address that Orca Mobile can use to reach this computer directly.",
-          "refresh": "Refresh network interfaces",
-          "tailnet": "Connect with your own tailnet",
-          "tailnetDescription": "Install Tailscale on this computer and your phone, sign in to the same tailnet, then select its 100.x.y.z address above.",
-          "getTailscale": "Get Tailscale"
+          "overview": "Generate a QR code, then scan it in Orca Mobile under Pair Desktop.",
+          "step1Title": "Connection",
+          "step2Title": "This computer’s address",
+          "step2RelayDescription": "Used for a faster direct path when nearby. Relay covers remote access.",
+          "step2LocalDescription": "The phone must be able to reach this address on Wi‑Fi or Tailscale.",
+          "regenerate": "Regenerate QR code",
+          "generate": "Generate QR code",
+          "refresh": "Refresh network interfaces"
         },
         "MobileRelayBetaAvailability": {
           "about": "About the Orca Relay beta",
@@ -9238,6 +9242,9 @@
           "howToUseDescription": "Ask an agent working a Linear-linked worktree to read context, post updates, move the ticket, or attach the PR.",
           "terminalTitle": "Linear skill setup",
           "terminalAriaLabel": "Linear skill install terminal"
+        },
+        "MobileRelayBetaNotice": {
+          "notice": "Orca Relay is in beta."
         }
       },
       "right": {
@@ -10752,7 +10759,8 @@
             "group": "Release channel",
             "preview": "Preview",
             "stable": "Stable"
-          }
+          },
+          "relayDegradedNotice": "Relay couldn’t be reached — this code only works on your local network."
         },
         "MobilePage": {
           "e17393c6a3": "Phone preview",
diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json
index 05b76df3900..fe010cb3095 100644
--- a/src/renderer/src/i18n/locales/es.json
+++ b/src/renderer/src/i18n/locales/es.json
@@ -5895,7 +5895,8 @@
           "aa1263e881": "Mantener en tamaño de teléfono (predeterminado)",
           "6436e56546": "Código QR para emparejamiento móvil",
           "1b1b70279a": "Aún no hay dispositivos emparejados.",
-          "1592afcc7a": "Aún no hay dispositivos emparejados. Escanea el código QR con la aplicación móvil de Orca."
+          "1592afcc7a": "Aún no hay dispositivos emparejados. Escanea el código QR con la aplicación móvil de Orca.",
+          "relayDegradedNotice": "Relay couldn’t be reached — this code only works on your local network. Regenerate to try again."
         },
         "MobileSettingsPane": {
           "9a3c280e49": "GitHub Releases",
@@ -5906,7 +5907,10 @@
           "174f4a3c6d": "Controla terminales y agentes desde tu teléfono.",
           "1de96ec8a6": "Mostrar botón de Orca Mobile",
           "682293cadf": "Mostrar el botón de Orca Mobile en la parte superior de la barra lateral izquierda.",
-          "d4f2b65f30": "Mostrar el acceso directo de Orca Mobile en la barra lateral."
+          "d4f2b65f30": "Mostrar el acceso directo de Orca Mobile en la barra lateral.",
+          "installIntro": "Instala Orca Mobile desde la",
+          "installOutro": ", luego empareja a continuación.",
+          "androidApkLabel": "Android APK"
         },
         "NotificationsPane": {
           "906b4afebf": "Enviar notificación de prueba",
@@ -8040,7 +8044,9 @@
               "671eb4173c": "Controla terminales y agentes desde tu teléfono.",
               "ffd52a96e4": "Móvil",
               "1de96ec8a6": "Mostrar botón de Orca Mobile",
-              "682293cadf": "Mostrar el botón de Orca Mobile en la parte superior de la barra lateral izquierda."
+              "682293cadf": "Mostrar el botón de Orca Mobile en la parte superior de la barra lateral izquierda.",
+              "e4f4daea0e": "relé",
+              "5d5af8e041": "iPhone"
             }
           }
         },
@@ -9169,28 +9175,26 @@
           "available": "Disponible",
           "reconnecting": "Reconectando",
           "unavailable": "No disponible",
-          "title": "¿Cómo debe conectarse el teléfono nuevo?",
-          "anywhere": "Conectar con Orca Relay",
-          "recommended": "Recomendado",
-          "automaticDescription": "Orca usa una conexión directa cuando está disponible y Relay en caso contrario.",
-          "signInDescription": "Inicia sesión en este ordenador para usar Orca Relay.",
           "signIn": "Iniciar sesión",
-          "localOnly": "Solo red local",
-          "localShort": "LAN o Tailscale",
-          "localDescription": "Usa LAN o Tailscale sin conectar este teléfono mediante Orca Relay."
+          "localDescription": "El teléfono debe estar en esta Wi‑Fi o en tu Tailscale. No requiere inicio de sesión.",
+          "pathGroup": "Cómo llega el teléfono a este ordenador",
+          "anywhereTitle": "Orca Relay",
+          "anywhereDescription": "El teléfono puede estar en datos móviles o cualquier Wi‑Fi. Se requiere inicio de sesión.",
+          "signInRequired": "Inicia sesión para usar Orca Mobile Relay.",
+          "relayUnavailable": "Orca Relay no está disponible en esta compilación. Usa Red local.",
+          "signInAgain": "Iniciar sesión de nuevo",
+          "localTitle": "Red local"
         },
         "MobilePairingSetupSection": {
           "title": "Vincular un teléfono",
-          "automaticDescription": "El código de vinculación incluye acceso directo y Orca Relay cifrado como respaldo.",
-          "localDescription": "El código de vinculación solo se conecta mediante la dirección de red local indicada abajo.",
           "regenerate": "Regenerar",
           "generate": "Generar código QR",
-          "localSettings": "Configuración de conexión local",
-          "localAddressDescription": "Elige la dirección LAN o de red privada que Orca Mobile puede usar para acceder directamente a este ordenador.",
           "refresh": "Actualizar interfaces de red",
-          "tailnet": "Conectarse con tu propia tailnet",
-          "tailnetDescription": "Instala Tailscale en este ordenador y en tu teléfono, inicia sesión en la misma tailnet y selecciona arriba su dirección 100.x.y.z.",
-          "getTailscale": "Obtener Tailscale"
+          "overview": "Genera un código QR, luego escanéalo en Orca Mobile en Pair Desktop.",
+          "step1Title": "Método de conexión",
+          "step2Title": "Dirección de este ordenador",
+          "step2RelayDescription": "Se usa para una ruta directa más rápida cuando está cerca. Relay cubre el acceso remoto.",
+          "step2LocalDescription": "El teléfono debe poder alcanzar esta dirección por Wi‑Fi o Tailscale."
         },
         "MobileRelayBetaAvailability": {
           "about": "Acerca de la beta de Orca Relay",
@@ -9215,6 +9219,9 @@
           "howToUseDescription": "Ask an agent working a Linear-linked worktree to read context, post updates, move the ticket, or attach the PR.",
           "terminalTitle": "Linear skill setup",
           "terminalAriaLabel": "Linear skill install terminal"
+        },
+        "MobileRelayBetaNotice": {
+          "notice": "Orca Relay is in beta."
         }
       },
       "right": {
@@ -10729,7 +10736,8 @@
             "group": "Canal de versión",
             "preview": "Vista previa",
             "stable": "Estable"
-          }
+          },
+          "relayDegradedNotice": "Relay couldn’t be reached — this code only works on your local network."
         },
         "MobilePage": {
           "e17393c6a3": "Vista previa del teléfono",
diff --git a/src/renderer/src/i18n/locales/ja.json b/src/renderer/src/i18n/locales/ja.json
index 8150d25ca97..326b87d99b2 100644
--- a/src/renderer/src/i18n/locales/ja.json
+++ b/src/renderer/src/i18n/locales/ja.json
@@ -5917,7 +5917,8 @@
           "aa1263e881": "スマートフォンサイズを維持（デフォルト）",
           "6436e56546": "モバイルペアリング用のQRコード",
           "1b1b70279a": "まだデバイスがペアリングされていません。",
-          "1592afcc7a": "まだデバイスがペアリングされていません。 Orca モバイル アプリで QR コードをスキャンします。"
+          "1592afcc7a": "まだデバイスがペアリングされていません。 Orca モバイル アプリで QR コードをスキャンします。",
+          "relayDegradedNotice": "Relay couldn’t be reached — this code only works on your local network. Regenerate to try again."
         },
         "MobileSettingsPane": {
           "9a3c280e49": "GitHub リリース",
@@ -5928,7 +5929,10 @@
           "174f4a3c6d": "スマートフォンから terminals と agents を操作",
           "1de96ec8a6": "Orca Mobile ボタンを表示",
           "682293cadf": "左サイドバー上部に Orca Mobile ボタンを表示します。",
-          "d4f2b65f30": "サイドバーに Orca Mobile ショートカットを表示します。"
+          "d4f2b65f30": "サイドバーに Orca Mobile ショートカットを表示します。",
+          "installIntro": "Orca Mobile は",
+          "installOutro": "からインストールし、以下でペアリングしてください。",
+          "androidApkLabel": "Android APK"
         },
         "NotificationsPane": {
           "906b4afebf": "テスト通知を送信する",
@@ -8062,7 +8066,9 @@
               "671eb4173c": "スマートフォンから terminals と agents を操作",
               "ffd52a96e4": "モバイル",
               "1de96ec8a6": "Orca Mobile ボタンを表示",
-              "682293cadf": "左サイドバー上部に Orca Mobile ボタンを表示します。"
+              "682293cadf": "左サイドバー上部に Orca Mobile ボタンを表示します。",
+              "e4f4daea0e": "リレー",
+              "5d5af8e041": "iPhone"
             }
           }
         },
@@ -9169,28 +9175,26 @@
           "available": "利用可能",
           "reconnecting": "再接続中",
           "unavailable": "利用不可",
-          "title": "新しいスマートフォンをどのように接続しますか？",
-          "anywhere": "Orca Relay で接続",
-          "recommended": "推奨",
-          "automaticDescription": "利用可能な場合は直接接続し、それ以外ではOrca Relayを使用します。",
-          "signInDescription": "Orca Relayを使用するには、このデスクトップでサインインしてください。",
           "signIn": "サインイン",
-          "localOnly": "ローカルネットワークのみ",
-          "localShort": "LAN または Tailscale",
-          "localDescription": "このスマートフォンをOrca Relayに接続せず、LANまたはTailscaleを使用します。"
+          "localDescription": "スマートフォンがこの Wi‑Fi または Tailscale に接続されている必要があります。サインインは不要です。",
+          "pathGroup": "スマートフォンがこのコンピューターに到達する方法",
+          "anywhereTitle": "Orca Relay",
+          "anywhereDescription": "スマートフォンはモバイル回線または Wi‑Fi から接続できます。サインインが必要です。",
+          "signInRequired": "Orca Mobile Relay を使用するにはサインインしてください。",
+          "relayUnavailable": "このビルドでは Orca Relay を利用できません。ローカルネットワークをご利用ください。",
+          "signInAgain": "再サインイン",
+          "localTitle": "ローカルネットワーク"
         },
         "MobilePairingSetupSection": {
           "title": "スマートフォンをペアリング",
-          "automaticDescription": "ペアリングコードには、直接接続と暗号化されたOrca Relayのフォールバックが含まれます。",
-          "localDescription": "ペアリングコードは、下のローカルネットワークアドレスだけを使用します。",
           "regenerate": "再生成",
           "generate": "QRコードを生成",
-          "localSettings": "ローカル接続設定",
-          "localAddressDescription": "Orca Mobileからこのコンピューターへ直接接続できるLANまたはプライベートネットワークのアドレスを選択します。",
           "refresh": "ネットワークインターフェースを更新",
-          "tailnet": "自分のtailnetで接続",
-          "tailnetDescription": "このコンピューターとスマートフォンにTailscaleをインストールし、同じtailnetにサインインして、上で100.x.y.zアドレスを選択します。",
-          "getTailscale": "Tailscaleを入手"
+          "overview": "QR コードを生成し、Orca Mobile の Pair Desktop でスキャンしてください。",
+          "step1Title": "接続方法",
+          "step2Title": "このコンピューターのアドレス",
+          "step2RelayDescription": "近くでは高速な直接接続に使用されます。Relay はリモートアクセスに対応します。",
+          "step2LocalDescription": "スマートフォンが Wi‑Fi または Tailscale でこのアドレスに到達できる必要があります。"
         },
         "MobileRelayBetaAvailability": {
           "about": "Orca Relay ベータについて",
@@ -9215,6 +9219,9 @@
           "howToUseDescription": "Ask an agent working a Linear-linked worktree to read context, post updates, move the ticket, or attach the PR.",
           "terminalTitle": "Linear skill setup",
           "terminalAriaLabel": "Linear skill install terminal"
+        },
+        "MobileRelayBetaNotice": {
+          "notice": "Orca Relay is in beta."
         }
       },
       "right": {
@@ -10729,7 +10736,8 @@
             "group": "リリースチャンネル",
             "preview": "プレビュー",
             "stable": "安定版"
-          }
+          },
+          "relayDegradedNotice": "Relay couldn’t be reached — this code only works on your local network."
         },
         "MobilePage": {
           "e17393c6a3": "スマートフォンプレビュー",
diff --git a/src/renderer/src/i18n/locales/ko.json b/src/renderer/src/i18n/locales/ko.json
index cc28a9e9dd9..0de35bc772f 100644
--- a/src/renderer/src/i18n/locales/ko.json
+++ b/src/renderer/src/i18n/locales/ko.json
@@ -5880,7 +5880,8 @@
           "aa1263e881": "휴대폰 크기로 유지(기본값)",
           "6436e56546": "모바일 페어링을 위한 QR 코드",
           "1b1b70279a": "아직 페어링된 기기가 없습니다.",
-          "1592afcc7a": "아직 페어링된 기기가 없습니다. Orca 모바일 앱으로 QR 코드를 스캔하세요."
+          "1592afcc7a": "아직 페어링된 기기가 없습니다. Orca 모바일 앱으로 QR 코드를 스캔하세요.",
+          "relayDegradedNotice": "Relay couldn’t be reached — this code only works on your local network. Regenerate to try again."
         },
         "MobileSettingsPane": {
           "9a3c280e49": "GitHub 릴리스",
@@ -5891,7 +5892,10 @@
           "174f4a3c6d": "휴대폰에서 terminals과 agents를 제어하세요.",
           "1de96ec8a6": "Orca Mobile 버튼 표시",
           "682293cadf": "왼쪽 사이드바 상단에 Orca Mobile 버튼을 표시합니다.",
-          "d4f2b65f30": "사이드바에 Orca Mobile 바로가기를 표시합니다."
+          "d4f2b65f30": "사이드바에 Orca Mobile 바로가기를 표시합니다.",
+          "installIntro": "다음 스토어에서 Orca Mobile 설치",
+          "installOutro": "하고 아래에서 페어링하세요.",
+          "androidApkLabel": "Android APK"
         },
         "NotificationsPane": {
           "906b4afebf": "테스트 알림 보내기",
@@ -8025,7 +8029,9 @@
               "671eb4173c": "휴대폰에서 terminals과 agents를 제어하세요.",
               "ffd52a96e4": "모바일",
               "1de96ec8a6": "Orca Mobile 버튼 표시",
-              "682293cadf": "왼쪽 사이드바 상단에 Orca Mobile 버튼을 표시합니다."
+              "682293cadf": "왼쪽 사이드바 상단에 Orca Mobile 버튼을 표시합니다.",
+              "e4f4daea0e": "릴레이",
+              "5d5af8e041": "iPhone"
             }
           }
         },
@@ -9169,28 +9175,26 @@
           "available": "사용 가능",
           "reconnecting": "다시 연결 중",
           "unavailable": "사용할 수 없음",
-          "title": "새 휴대폰을 어떻게 연결할까요?",
-          "anywhere": "Orca Relay로 연결",
-          "recommended": "권장",
-          "automaticDescription": "가능하면 직접 연결하고, 그렇지 않으면 Orca Relay를 사용합니다.",
-          "signInDescription": "Orca Relay를 사용하려면 이 데스크톱에서 로그인하세요.",
           "signIn": "로그인",
-          "localOnly": "로컬 네트워크만",
-          "localShort": "LAN 또는 Tailscale",
-          "localDescription": "이 휴대폰을 Orca Relay에 연결하지 않고 LAN 또는 Tailscale을 사용합니다."
+          "localDescription": "휴대폰이 이 Wi‑Fi 또는 Tailscale에 연결되어 있어야 합니다. 로그인이 필요하지 않습니다.",
+          "pathGroup": "휴대폰이 이 컴퓨터에 연결되는 방식",
+          "anywhereTitle": "Orca Relay",
+          "anywhereDescription": "휴대폰이 모바일 네트워크 또는 모든 Wi‑Fi에서 연결 가능합니다. 로그인이 필요합니다.",
+          "signInRequired": "Orca Mobile Relay를 사용하려면 로그인하세요.",
+          "relayUnavailable": "이 빌드에서는 Orca Relay를 사용할 수 없습니다. 로컬 네트워크를 사용하세요.",
+          "signInAgain": "다시 로그인",
+          "localTitle": "로컬 네트워크"
         },
         "MobilePairingSetupSection": {
           "title": "휴대폰 페어링",
-          "automaticDescription": "페어링 코드에는 직접 연결과 암호화된 Orca Relay 대체 연결이 포함됩니다.",
-          "localDescription": "페어링 코드는 아래의 로컬 네트워크 주소로만 연결합니다.",
           "regenerate": "다시 생성",
           "generate": "QR 코드 생성",
-          "localSettings": "로컬 연결 설정",
-          "localAddressDescription": "Orca Mobile에서 이 컴퓨터에 직접 연결할 수 있는 LAN 또는 사설 네트워크 주소를 선택하세요.",
           "refresh": "네트워크 인터페이스 새로 고침",
-          "tailnet": "내 tailnet으로 연결",
-          "tailnetDescription": "이 컴퓨터와 휴대폰에 Tailscale을 설치하고 같은 tailnet에 로그인한 다음 위에서 100.x.y.z 주소를 선택하세요.",
-          "getTailscale": "Tailscale 받기"
+          "overview": "QR 코드를 생성한 후 Orca Mobile의 Pair Desktop에서 스캔하세요.",
+          "step1Title": "연결 방식",
+          "step2Title": "이 컴퓨터의 주소",
+          "step2RelayDescription": "가까운 곳에서는 빠른 직접 연결에 사용됩니다. 먼 거리에서는 Relay가 원격 액세스를 제공합니다.",
+          "step2LocalDescription": "휴대폰이 Wi‑Fi 또는 Tailscale을 통해 이 주소에 접근할 수 있어야 합니다."
         },
         "MobileRelayBetaAvailability": {
           "about": "Orca Relay 베타 정보",
@@ -9215,6 +9219,9 @@
           "howToUseDescription": "Ask an agent working a Linear-linked worktree to read context, post updates, move the ticket, or attach the PR.",
           "terminalTitle": "Linear skill setup",
           "terminalAriaLabel": "Linear skill install terminal"
+        },
+        "MobileRelayBetaNotice": {
+          "notice": "Orca Relay is in beta."
         }
       },
       "right": {
@@ -10729,7 +10736,8 @@
             "group": "릴리스 채널",
             "preview": "미리 보기",
             "stable": "안정 버전"
-          }
+          },
+          "relayDegradedNotice": "Relay couldn’t be reached — this code only works on your local network."
         },
         "MobilePage": {
           "e17393c6a3": "휴대폰 미리보기",
diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json
index a649bc1611c..6a8e1bd94a6 100644
--- a/src/renderer/src/i18n/locales/zh.json
+++ b/src/renderer/src/i18n/locales/zh.json
@@ -5880,7 +5880,8 @@
           "aa1263e881": "保持手机尺寸（默认）",
           "6436e56546": "用于手机配对的二维码",
           "1b1b70279a": "尚未配对任何设备。",
-          "1592afcc7a": "尚未配对任何设备。使用 Orca 手机应用程序扫描二维码。"
+          "1592afcc7a": "尚未配对任何设备。使用 Orca 手机应用程序扫描二维码。",
+          "relayDegradedNotice": "Relay couldn’t be reached — this code only works on your local network. Regenerate to try again."
         },
         "MobileSettingsPane": {
           "9a3c280e49": "GitHub 发布",
@@ -5891,7 +5892,10 @@
           "174f4a3c6d": "通过手机控制终端和智能体。",
           "1de96ec8a6": "显示 Orca 手机端按钮",
           "682293cadf": "在左侧边栏顶部显示 Orca 手机端按钮。",
-          "d4f2b65f30": "在边栏中显示 Orca 手机端 快捷入口。"
+          "d4f2b65f30": "在边栏中显示 Orca 手机端 快捷入口。",
+          "installIntro": "从以下应用商店安装 Orca Mobile",
+          "installOutro": "，然后在下方配对。",
+          "androidApkLabel": "Android APK"
         },
         "NotificationsPane": {
           "906b4afebf": "发送测试通知",
@@ -7982,7 +7986,7 @@
               "6db86f445f": "移动端",
               "707fc78052": "选择关闭应用程序或切换离开后，您在手机设备上查看的终端会发生什么情况。",
               "1e711aca11": "当您离开手机应用程序时",
-              "126afc5dbd": "偏僻的",
+              "126afc5dbd": "远程",
               "70f505f3c3": "局域网",
               "1802188b5d": "无线上网",
               "dd6e671aa9": "地址",
@@ -8015,7 +8019,7 @@
               "8d4ba0ef09": "Beta",
               "6bfa001752": "应用程序",
               "a7eececc1d": "安卓",
-              "7e801801ac": "偏僻的",
+              "7e801801ac": "远程",
               "0b7e585cb9": "扫描",
               "59b1d75fd1": "代码",
               "87816d1c59": "qr",
@@ -8025,7 +8029,9 @@
               "671eb4173c": "通过手机控制终端和智能体。",
               "ffd52a96e4": "移动端",
               "1de96ec8a6": "显示 Orca Mobile 按钮",
-              "682293cadf": "在左侧边栏顶部显示 Orca Mobile 按钮。"
+              "682293cadf": "在左侧边栏顶部显示 Orca Mobile 按钮。",
+              "e4f4daea0e": "中继",
+              "5d5af8e041": "iPhone"
             }
           }
         },
@@ -9169,28 +9175,26 @@
           "available": "可用",
           "reconnecting": "正在重新连接",
           "unavailable": "不可用",
-          "title": "新手机应如何连接？",
-          "anywhere": "使用 Orca Relay 连接",
-          "recommended": "推荐",
-          "automaticDescription": "Orca 会优先使用直接连接，否则使用 Orca Relay。",
-          "signInDescription": "请在此桌面端登录以使用 Orca Relay。",
           "signIn": "登录",
-          "localOnly": "仅限本地网络",
-          "localShort": "局域网或 Tailscale",
-          "localDescription": "使用局域网或 Tailscale，不通过 Orca Relay 连接这部手机。"
+          "localDescription": "手机必须连接此 Wi‑Fi 或您的 Tailscale。无需登录。",
+          "pathGroup": "手机访问此电脑的方式",
+          "anywhereTitle": "Orca Relay",
+          "anywhereDescription": "手机可通过蜂窝网络或任意 Wi‑Fi 连接。需要登录。",
+          "signInRequired": "请登录以使用 Orca Mobile Relay。",
+          "relayUnavailable": "此版本不支持 Orca Relay。请使用本地网络。",
+          "signInAgain": "重新登录",
+          "localTitle": "本地网络"
         },
         "MobilePairingSetupSection": {
           "title": "配对手机",
-          "automaticDescription": "配对码包含直接访问方式和加密的 Orca Relay 备用连接。",
-          "localDescription": "配对码仅通过下方的本地网络地址连接。",
           "regenerate": "重新生成",
           "generate": "生成二维码",
-          "localSettings": "本地连接设置",
-          "localAddressDescription": "选择 Orca Mobile 可用于直接访问此电脑的局域网或专用网络地址。",
           "refresh": "刷新网络接口",
-          "tailnet": "使用自己的 tailnet 连接",
-          "tailnetDescription": "在此电脑和手机上安装 Tailscale，登录同一个 tailnet，然后在上方选择其 100.x.y.z 地址。",
-          "getTailscale": "获取 Tailscale"
+          "overview": "生成二维码，然后在 Orca Mobile 的 Pair Desktop 中扫描。",
+          "step1Title": "连接方式",
+          "step2Title": "此电脑的地址",
+          "step2RelayDescription": "距离较近时用于快速直接连接。Relay 覆盖远程访问。",
+          "step2LocalDescription": "手机必须能通过 Wi‑Fi 或 Tailscale 访问此地址。"
         },
         "MobileRelayBetaAvailability": {
           "about": "关于 Orca Relay 测试版",
@@ -9215,6 +9219,9 @@
           "howToUseDescription": "Ask an agent working a Linear-linked worktree to read context, post updates, move the ticket, or attach the PR.",
           "terminalTitle": "Linear skill setup",
           "terminalAriaLabel": "Linear skill install terminal"
+        },
+        "MobileRelayBetaNotice": {
+          "notice": "Orca Relay is in beta."
         }
       },
       "right": {
@@ -10729,7 +10736,8 @@
             "group": "发布渠道",
             "preview": "预览版",
             "stable": "稳定版"
-          }
+          },
+          "relayDegradedNotice": "Relay couldn’t be reached — this code only works on your local network."
         },
         "MobilePage": {
           "e17393c6a3": "手机预览",
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index 71201caef74..d65182c20c4 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -368,6 +368,9 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     // explicit return-to-desktop-size action, no wall-clock guess.
     // See docs/mobile-fit-hold.md.
     mobileAutoRestoreFitMs: null,
+    // Why: Anywhere (Relay + local) is the default remote path. Explicit
+    // `local-only` is only written after the user picks same-network only.
+    mobilePairingConnectionMode: 'automatic',
     // Why: off by default — opt-in cosmetic joke feature. Leaving the default
     // false keeps the overlay unmounted for users who never enable it.
     experimentalPet: false,
diff --git a/src/shared/mobile-pairing-connection-mode.test.ts b/src/shared/mobile-pairing-connection-mode.test.ts
new file mode 100644
index 00000000000..d0f22933b7c
--- /dev/null
+++ b/src/shared/mobile-pairing-connection-mode.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import {
+  canMintMobilePairingOffer,
+  effectiveMobilePairingConnectionMode,
+  resolveMobilePairingConnectionMode
+} from './mobile-pairing-connection-mode'
+
+describe('mobile pairing connection mode defaults', () => {
+  it('defaults to Anywhere when no preference is saved', () => {
+    expect(resolveMobilePairingConnectionMode(undefined)).toBe('automatic')
+    expect(resolveMobilePairingConnectionMode(null)).toBe('automatic')
+  })
+
+  it('keeps an explicit same-network preference', () => {
+    expect(resolveMobilePairingConnectionMode('local-only')).toBe('local-only')
+  })
+
+  it('keeps an explicit Anywhere preference', () => {
+    expect(resolveMobilePairingConnectionMode('automatic')).toBe('automatic')
+  })
+
+  it('cannot commit Anywhere into a QR while signed out', () => {
+    expect(effectiveMobilePairingConnectionMode({ preferred: 'automatic', signedIn: false })).toBe(
+      'local-only'
+    )
+    expect(effectiveMobilePairingConnectionMode({ preferred: 'automatic', signedIn: true })).toBe(
+      'automatic'
+    )
+    expect(effectiveMobilePairingConnectionMode({ preferred: 'local-only', signedIn: false })).toBe(
+      'local-only'
+    )
+  })
+
+  it('refuses to mint under signed-out Anywhere and allows honest paths', () => {
+    // Why: mint refusal is the UI honesty gate that replaces silent degradation
+    // for renderer mint paths (signed-out Anywhere must not show a local QR).
+    expect(canMintMobilePairingOffer({ connectionMode: 'automatic', signedIn: false })).toBe(false)
+    expect(canMintMobilePairingOffer({ connectionMode: 'automatic', signedIn: true })).toBe(true)
+    expect(canMintMobilePairingOffer({ connectionMode: 'local-only', signedIn: false })).toBe(true)
+    expect(canMintMobilePairingOffer({ connectionMode: 'local-only', signedIn: true })).toBe(true)
+  })
+})
diff --git a/src/shared/mobile-pairing-connection-mode.ts b/src/shared/mobile-pairing-connection-mode.ts
index cde61a6fde5..c6c06d2ae34 100644
--- a/src/shared/mobile-pairing-connection-mode.ts
+++ b/src/shared/mobile-pairing-connection-mode.ts
@@ -1 +1,41 @@
 export type MobilePairingConnectionMode = 'automatic' | 'local-only'
+
+/**
+ * Resolve the pairing path to show / remember.
+ *
+ * - Explicit saved preference wins (user already chose).
+ * - Otherwise default to Anywhere (`automatic`). Relay still requires sign-in
+ *   at QR time; the UI can keep Anywhere selected while signed out.
+ */
+export function resolveMobilePairingConnectionMode(
+  saved: MobilePairingConnectionMode | null | undefined
+): MobilePairingConnectionMode {
+  return saved === 'local-only' ? 'local-only' : 'automatic'
+}
+
+/**
+ * Mode encoded into a pairing QR. Anywhere cannot be committed without a
+ * signed-in desktop session for Relay.
+ */
+export function effectiveMobilePairingConnectionMode(args: {
+  preferred: MobilePairingConnectionMode
+  signedIn: boolean
+}): MobilePairingConnectionMode {
+  if (args.preferred === 'automatic' && !args.signedIn) {
+    return 'local-only'
+  }
+  return args.preferred
+}
+
+/**
+ * Whether a scannable pairing offer may be minted for the selected path. Anywhere
+ * (Relay) needs a signed-in desktop; minting a local-only QR under the Relay
+ * label would misrepresent what the code encodes, so both surfaces gate
+ * generation on this rather than silently degrading to local-only.
+ */
+export function canMintMobilePairingOffer(args: {
+  connectionMode: MobilePairingConnectionMode
+  signedIn: boolean
+}): boolean {
+  return !(args.connectionMode === 'automatic' && !args.signedIn)
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 9f3d62e6968..405d9ed5ba6 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -2966,6 +2966,10 @@ export type GlobalSettings = {
    *  on read into [5_000ms, 60min] to defend against bad config.
    *  See docs/mobile-fit-hold.md. */
   mobileAutoRestoreFitMs: number | null
+  /** Preferred mobile pairing path for new QR codes: Anywhere (Orca Relay +
+   *  local) or same-network only. Missing/undefined defaults to Anywhere.
+   *  An explicit `local-only` means the user already chose that path. */
+  mobilePairingConnectionMode?: 'automatic' | 'local-only'
   /** Experimental: floating animated pet (claude.webp) in the bottom-right
    *  corner. Opt-in because it's a cosmetic joke feature; users who leave it
    *  off never mount the overlay. Toggling takes effect immediately in the

From d67ede15947e59127e061c603ecb2c09651a6ea3 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Sun, 19 Jul 2026 16:32:36 -0700
Subject: [PATCH 10/54] Implement confirm-only PR panel composer with
 classified error blocking (#9428)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Clarify PR panel guidance: classify errors and confirm-only composer

Replace the ambiguous GitHub hosted-review boolean with a four-state evidence
model (found/positive_unresolved/not_found/unknown) so "No PR found" never
appears without an accepted lookup result. Classify GitHub refresh failures
into types (rate_limited, auth, network, permission, repo_unavailable,
gh_unavailable, unknown) for stable, honest copy. Confirmed-only composer:
preserve drafts across transient failures; hide Create during hard errors and
positive-unresolved evidence. Hard errors clear only when an eligibility
request starts after the error and returns an accepted outcome. Propagate
error types and unified retry schedule through the store. Sync mobile parity
with shouldOpenChecksPanelCreateComposer gating. Localize all new copy.

* Clarify PR panel guidance: classify errors and confirm-only composer

Add reviewLookupOutcome to hosted-review eligibility and thread it through
the panel so it never claims "No PR found" without accepted evidence. A
failed lookup is unavailable, not a settled no-PR. Fail closed on positive
unresolved evidence, hard refresh errors, and unavailable lookups. Add
structured GitHub refresh-error classification with Retry-After parsing.
Implement confirmed-only composer gating based on fresh, matching-context
eligibility with hard-error clearing. Mobile gates on reviewLookupOutcome
to prevent false Create claims. Surface throwOnFailure variants for each
provider so transport failures cross the RPC boundary instead of collapsing
to null. (Design success criteria 1–4; invariant 8.)

* Add exec-error helpers for subprocess error classification

Extracts stderr/stdout parsing and Retry-After detection into a
lightweight module that can be imported without pulling in the heavier
runner machinery. Supports PR-refresh error classification and proper
rate-limit handling for gh commands.

* test(mobile): include reviewLookupOutcome in create eligibility fixtures

Create / Push & Create now fails closed unless the lookup is not_found.
Update mobile test fixtures so accepted-no-PR cases can still proceed.

* Add OrThrow mock variants to forge-provider test mocks

forge-provider resolves branch reviews via the OrThrow variant so
lookup failures surface as unavailable instead of "no PR found".
---
 ...hosted-review-create-intent-runner.test.ts |   2 +
 .../mobile-hosted-review-service.ts           |  25 +-
 .../source-control/mobile-pr-create.test.ts   | 146 +++++-
 mobile/src/source-control/mobile-pr-create.ts |  10 +-
 .../azure-devops/azure-devops-api-request.ts  |  19 +-
 src/main/azure-devops/client.test.ts          |  32 ++
 src/main/azure-devops/client.ts               |  32 +-
 src/main/bitbucket/client.test.ts             |  19 +-
 src/main/bitbucket/client.ts                  |  50 +-
 src/main/git/exec-error.ts                    | 111 ++++
 src/main/git/runner.ts                        | 108 +---
 src/main/gitea/client.test.ts                 |  14 +
 src/main/gitea/client.ts                      |  67 ++-
 src/main/github/client.test.ts                |  28 +
 src/main/github/client.ts                     |  67 +--
 src/main/github/gh-utils.ts                   |   7 +-
 src/main/github/pr-refresh-coordinator.ts     | 163 +++++-
 .../pr-refresh-error-classification.test.ts   | 144 +++++
 .../github/pr-refresh-error-classification.ts | 144 +++++
 src/main/gitlab/client-mr.test.ts             |  14 +
 src/main/gitlab/client.ts                     |  26 +-
 src/main/runtime/orca-runtime.test.ts         |  18 +-
 src/main/runtime/orca-runtime.ts              |  12 +-
 .../runtime/rpc/methods/hosted-review.test.ts |   1 +
 src/main/source-control/forge-provider.ts     |  25 +-
 ...hosted-review-creation-eligibility.test.ts |  92 +++-
 .../source-control/hosted-review-creation.ts  |  53 +-
 src/main/source-control/hosted-review.test.ts |  12 +
 .../components/right-sidebar/ChecksPanel.tsx  | 437 +++++++++++++++-
 .../right-sidebar/CommitArea.test.tsx         |   6 +-
 .../right-sidebar/SourceControl.tsx           |   6 +-
 ...ecks-panel-ambiguous-github-review.test.ts |  44 --
 .../checks-panel-ambiguous-github-review.ts   |  22 -
 .../checks-panel-blocker-copy.ts              | 220 ++++++++
 .../checks-panel-empty-state.test.ts          | 495 ++++++++----------
 .../right-sidebar/checks-panel-empty-state.ts | 335 +++++++-----
 .../checks-panel-git-status-snapshot.ts       |   5 +
 .../right-sidebar/checks-panel-review-copy.ts | 288 ++++++++++
 .../checks-panel-review-creation.test.ts      | 397 +++++++++++---
 .../checks-panel-review-creation.ts           | 168 +++++-
 ...ecks-panel-review-lookup-authority.test.ts | 130 +++++
 .../checks-panel-review-lookup-authority.ts   | 120 +++++
 .../checks-panel-review-state-model.ts        | 165 ++++++
 ...urce-control-create-pr-intent-flow.test.ts |  18 +-
 ...ntrol-create-review-blocked-action.test.ts |   1 +
 .../source-control-dropdown-items.test.ts     |  21 +-
 ...view-creation-eligibility-snapshot.test.ts |  13 +-
 ...ed-review-creation-eligibility-snapshot.ts |  12 +-
 ...ol-primary-action.create-pr-intent.test.ts |  60 ++-
 .../source-control-primary-action.test.ts     |  15 +-
 .../useCreatePullRequestDialogFields.test.ts  |   1 +
 .../useCreatePullRequestDialogFields.ts       |  25 +-
 src/renderer/src/i18n/locales/en.json         | 141 ++++-
 src/renderer/src/i18n/locales/es.json         | 141 ++++-
 src/renderer/src/i18n/locales/ja.json         | 141 ++++-
 src/renderer/src/i18n/locales/ko.json         | 141 ++++-
 src/renderer/src/i18n/locales/zh.json         | 141 ++++-
 src/renderer/src/store/slices/github.ts       |  73 ++-
 src/shared/hosted-review.ts                   |   9 +
 .../source-control-create-review-intent.ts    |   5 +
 ...ce-control-primary-action-decision.test.ts |   6 +-
 src/shared/types.ts                           |  21 +-
 62 files changed, 4359 insertions(+), 905 deletions(-)
 create mode 100644 src/main/git/exec-error.ts
 create mode 100644 src/main/github/pr-refresh-error-classification.test.ts
 create mode 100644 src/main/github/pr-refresh-error-classification.ts
 delete mode 100644 src/renderer/src/components/right-sidebar/checks-panel-ambiguous-github-review.test.ts
 delete mode 100644 src/renderer/src/components/right-sidebar/checks-panel-ambiguous-github-review.ts
 create mode 100644 src/renderer/src/components/right-sidebar/checks-panel-blocker-copy.ts
 create mode 100644 src/renderer/src/components/right-sidebar/checks-panel-review-copy.ts
 create mode 100644 src/renderer/src/components/right-sidebar/checks-panel-review-lookup-authority.test.ts
 create mode 100644 src/renderer/src/components/right-sidebar/checks-panel-review-lookup-authority.ts
 create mode 100644 src/renderer/src/components/right-sidebar/checks-panel-review-state-model.ts

diff --git a/mobile/src/source-control/mobile-hosted-review-create-intent-runner.test.ts b/mobile/src/source-control/mobile-hosted-review-create-intent-runner.test.ts
index c96edaded01..b64bb888798 100644
--- a/mobile/src/source-control/mobile-hosted-review-create-intent-runner.test.ts
+++ b/mobile/src/source-control/mobile-hosted-review-create-intent-runner.test.ts
@@ -35,6 +35,8 @@ function eligibility(overrides: Record<string, unknown>) {
     defaultBaseRef: 'main',
     title: 'Ship mobile PR create',
     body: 'Generated body',
+    // Accepted no-review lookup so Create / Push & Create is allowed unless overridden.
+    reviewLookupOutcome: 'not_found',
     ...overrides
   }
 }
diff --git a/mobile/src/source-control/mobile-hosted-review-service.ts b/mobile/src/source-control/mobile-hosted-review-service.ts
index c219586edc7..c040b7a2c19 100644
--- a/mobile/src/source-control/mobile-hosted-review-service.ts
+++ b/mobile/src/source-control/mobile-hosted-review-service.ts
@@ -3,6 +3,7 @@ import type {
   HostedReviewCreationBlockedReason,
   HostedReviewCreationEligibility,
   HostedReviewCreationNextAction,
+  HostedReviewLookupOutcome,
   HostedReviewProvider
 } from '../../../src/shared/hosted-review'
 import type { RpcClient } from '../transport/rpc-client'
@@ -62,6 +63,10 @@ export type MobileHostedReviewPrefill = {
   canCreate?: boolean
   blockedReason?: HostedReviewCreationBlockedReason
   nextAction?: HostedReviewCreationNextAction
+  // Why: mobile lacks the desktop refresh/review-lookup signals, so it fails
+  // closed on ambiguity. When the host could not prove the branch has no review
+  // (`unavailable`), create — including the Push & Create path — stays blocked.
+  reviewLookupOutcome?: HostedReviewLookupOutcome
 }
 
 // Resolve the mobile compose prefill from the same hosted-review eligibility
@@ -97,7 +102,14 @@ export async function resolveMobileHostedReviewPrefill(
       behind: args.behind
     })
     if (!eligibility) {
-      return { ...fallback, canCreate: false, blockedReason: null, nextAction: null }
+      // Eligibility itself could not be resolved: the review lookup is unproven.
+      return {
+        ...fallback,
+        canCreate: false,
+        blockedReason: null,
+        nextAction: null,
+        reviewLookupOutcome: 'unavailable'
+      }
     }
     return {
       provider: eligibility.provider,
@@ -106,10 +118,17 @@ export async function resolveMobileHostedReviewPrefill(
       body: eligibility.body || '',
       canCreate: eligibility.canCreate,
       blockedReason: eligibility.blockedReason,
-      nextAction: eligibility.nextAction
+      nextAction: eligibility.nextAction,
+      reviewLookupOutcome: eligibility.reviewLookupOutcome
     }
   } catch {
-    return { ...fallback, canCreate: false, blockedReason: null, nextAction: null }
+    return {
+      ...fallback,
+      canCreate: false,
+      blockedReason: null,
+      nextAction: null,
+      reviewLookupOutcome: 'unavailable'
+    }
   }
 }
 
diff --git a/mobile/src/source-control/mobile-pr-create.test.ts b/mobile/src/source-control/mobile-pr-create.test.ts
index 28f2e4b691f..deb36b9e9f0 100644
--- a/mobile/src/source-control/mobile-pr-create.test.ts
+++ b/mobile/src/source-control/mobile-pr-create.test.ts
@@ -40,6 +40,7 @@ function eligibility(
     canCreate: true,
     blockedReason: null,
     nextAction: null,
+    reviewLookupOutcome: 'not_found',
     defaultBaseRef: 'main',
     title: 'Add feature',
     body: '',
@@ -118,12 +119,115 @@ describe('mobile create form gating parity', () => {
         body: desktopEligibility.body ?? '',
         canCreate: desktopEligibility.canCreate,
         blockedReason: desktopEligibility.blockedReason,
-        nextAction: desktopEligibility.nextAction
+        nextAction: desktopEligibility.nextAction,
+        // Mobile receives the lookup outcome from eligibility; thread it so the
+        // gate reflects real prefills (current hosts always populate it).
+        reviewLookupOutcome: desktopEligibility.reviewLookupOutcome
       }) === null
 
     expect(mobileAllowsComposer).toBe(desktopAllowsComposer)
   })
 
+  it('fails closed when the review-lookup outcome is missing (older host)', () => {
+    // A host that predates `reviewLookupOutcome` leaves review existence unproven.
+    // Mobile must not open Create / Push & Create on that ambiguity.
+    expect(
+      getMobilePrCreateBlockMessage({
+        provider: 'github',
+        base: 'main',
+        title: 'Add feature',
+        body: '',
+        canCreate: true,
+        blockedReason: null
+      })
+    ).toBe(
+      'Orca could not confirm whether this branch already has a pull request. Try again in a moment.'
+    )
+    expect(
+      getMobilePrCreateBlockMessage({
+        provider: 'github',
+        base: 'main',
+        title: 'Add feature',
+        body: '',
+        canCreate: false,
+        blockedReason: 'needs_push'
+      })
+    ).toBe(
+      'Orca could not confirm whether this branch already has a pull request. Try again in a moment.'
+    )
+  })
+
+  it('desktop gate hard-blocks on positive unresolved review evidence', () => {
+    // Mobile lacks review-lookup signals, so it fails closed on ambiguity: the
+    // shared desktop gate must return false even when eligibility looks ready.
+    expect(
+      shouldOpenChecksPanelCreateComposer({
+        activeReview: null,
+        isFolder: false,
+        branch: 'feature/x',
+        hostedReviewCreation: eligibility({ canCreate: true }),
+        reviewLookup: 'positive_unresolved'
+      })
+    ).toBe(false)
+  })
+
+  it('desktop gate hard-blocks during a hard refresh error', () => {
+    expect(
+      shouldOpenChecksPanelCreateComposer({
+        activeReview: null,
+        isFolder: false,
+        branch: 'feature/x',
+        hostedReviewCreation: eligibility({ canCreate: true }),
+        hasHardRefreshError: true
+      })
+    ).toBe(false)
+  })
+
+  it('fails closed on an unavailable review lookup even when eligibility looks ready', () => {
+    // The existing-review lookup could not prove there is no PR; mobile has no
+    // review-lookup signal of its own, so create must be blocked.
+    expect(
+      getMobilePrCreateBlockMessage({
+        provider: 'github',
+        base: 'main',
+        title: 'Add feature',
+        body: '',
+        canCreate: true,
+        blockedReason: null,
+        reviewLookupOutcome: 'unavailable'
+      })
+    ).toBe(
+      'Orca could not confirm whether this branch already has a pull request. Try again in a moment.'
+    )
+  })
+
+  it('fails closed on unavailable even on the needs_push Push & Create path', () => {
+    // needs_push would normally be allowed (Push & Create); an unavailable lookup
+    // must still block it — this is the fail-open gap the parity gate closes.
+    const mobileBlocked =
+      getMobilePrCreateBlockMessage({
+        provider: 'github',
+        base: 'main',
+        title: 'Add feature',
+        body: '',
+        canCreate: false,
+        blockedReason: 'needs_push',
+        reviewLookupOutcome: 'unavailable'
+      }) !== null
+    const desktopAllowsComposer = shouldOpenChecksPanelCreateComposer({
+      activeReview: null,
+      isFolder: false,
+      branch: 'feature/x',
+      hostedReviewCreation: eligibility({
+        canCreate: false,
+        blockedReason: 'needs_push',
+        reviewLookupOutcome: 'unavailable'
+      })
+    })
+    expect(mobileBlocked).toBe(true)
+    expect(desktopAllowsComposer).toBe(false)
+  })
+
   it('stays safely blocked for a reason added by a newer desktop contract', () => {
     expect(
       getMobilePrCreateBlockMessage({
@@ -158,7 +262,8 @@ describe('resolveMobilePrPrefill', () => {
         nextAction: null,
         defaultBaseRef: 'develop',
         title: 'Add feature',
-        body: 'Body'
+        body: 'Body',
+        reviewLookupOutcome: 'not_found'
       })
     ])
     await expect(resolveMobilePrPrefill(client, 'repo-1::/tmp/wt', baseArgs)).resolves.toEqual({
@@ -168,7 +273,8 @@ describe('resolveMobilePrPrefill', () => {
       body: 'Body',
       canCreate: true,
       blockedReason: null,
-      nextAction: null
+      nextAction: null,
+      reviewLookupOutcome: 'not_found'
     })
   })
 
@@ -182,7 +288,8 @@ describe('resolveMobilePrPrefill', () => {
         nextAction: 'push',
         defaultBaseRef: 'main',
         title: 'Add feature',
-        body: ''
+        body: '',
+        reviewLookupOutcome: 'not_found'
       })
     ])
     const prefill = await resolveMobilePrPrefill(client, 'repo-1::/tmp/wt', baseArgs)
@@ -198,7 +305,8 @@ describe('resolveMobilePrPrefill', () => {
         review: null,
         blockedReason: 'dirty',
         nextAction: 'commit',
-        defaultBaseRef: 'main'
+        defaultBaseRef: 'main',
+        reviewLookupOutcome: 'not_found'
       })
     ])
     const prefill = await resolveMobilePrPrefill(client, 'repo-1::/tmp/wt', baseArgs)
@@ -209,15 +317,39 @@ describe('resolveMobilePrPrefill', () => {
 
   it('returns a blocked fallback when eligibility is unavailable', async () => {
     const client = clientWith([fail('nope')])
-    await expect(resolveMobilePrPrefill(client, 'repo-1::/tmp/wt', baseArgs)).resolves.toEqual({
+    const prefill = await resolveMobilePrPrefill(client, 'repo-1::/tmp/wt', baseArgs)
+    expect(prefill).toEqual({
       provider: 'github',
       base: 'main',
       title: 'feature/x',
       body: '',
       canCreate: false,
       blockedReason: null,
-      nextAction: null
+      nextAction: null,
+      // Eligibility could not be resolved, so the review lookup is unproven.
+      reviewLookupOutcome: 'unavailable'
     })
+    // A prefill Orca could not resolve must not offer create.
+    expect(getMobilePrCreateBlockMessage(prefill)).not.toBeNull()
+  })
+
+  it('threads reviewLookupOutcome from eligibility into the prefill and blocks needs_push', async () => {
+    const client = clientWith([
+      ok({
+        provider: 'github',
+        canCreate: false,
+        review: null,
+        blockedReason: 'needs_push',
+        nextAction: 'push',
+        defaultBaseRef: 'main',
+        title: 'Add feature',
+        body: '',
+        reviewLookupOutcome: 'unavailable'
+      })
+    ])
+    const prefill = await resolveMobilePrPrefill(client, 'repo-1::/tmp/wt', baseArgs)
+    expect(prefill.reviewLookupOutcome).toBe('unavailable')
+    expect(getMobilePrCreateBlockMessage(prefill)).not.toBeNull()
   })
 
   it('blocks without calling the RPC when there is no branch', async () => {
diff --git a/mobile/src/source-control/mobile-pr-create.ts b/mobile/src/source-control/mobile-pr-create.ts
index b584b86e202..20f908d3df2 100644
--- a/mobile/src/source-control/mobile-pr-create.ts
+++ b/mobile/src/source-control/mobile-pr-create.ts
@@ -43,10 +43,18 @@ export function getMobilePrCreateSuccessWarning(
 }
 
 export function getMobilePrCreateBlockMessage(prefill: MobilePrPrefill): string | null {
+  const copy = hostedReviewCopy(prefill.provider)
   if (prefill.canCreate !== false || shouldPushBeforeMobileHostedReviewCreate(prefill)) {
+    // Fail closed: only an accepted no-review lookup (`not_found`) may open
+    // Create / Push & Create. `unavailable`, `found`, or a missing outcome (an
+    // older host that predates the field) all leave review existence unproven —
+    // mobile has no refresh/review-lookup signal of its own, so it must not
+    // offer create, or the needs_push Push & Create path would slip through.
+    if (prefill.reviewLookupOutcome !== 'not_found') {
+      return `Orca could not confirm whether this branch already has a ${copy.reviewLabel}. Try again in a moment.`
+    }
     return null
   }
-  const copy = hostedReviewCopy(prefill.provider)
   switch (prefill.blockedReason) {
     case 'dirty':
       return `Commit changes before creating a ${copy.reviewLabel}.`
diff --git a/src/main/azure-devops/azure-devops-api-request.ts b/src/main/azure-devops/azure-devops-api-request.ts
index 089975cf5a2..5fc8f256793 100644
--- a/src/main/azure-devops/azure-devops-api-request.ts
+++ b/src/main/azure-devops/azure-devops-api-request.ts
@@ -73,7 +73,11 @@ function apiUrl(
 export async function requestAzureDevOpsJsonAtBase<T>(
   baseUrl: string,
   path: string,
-  options: AzureDevOpsRequestOptions = {}
+  options: AzureDevOpsRequestOptions = {},
+  // Why: the existing-review lookup behind Create must distinguish a real
+  // transport/auth failure from an accepted "no PR". When true, a failed request
+  // throws instead of collapsing to null so callers never report false not_found.
+  throwOnFailure = false
 ): Promise<T | null> {
   const config = getAzureDevOpsAuthConfig()
   try {
@@ -86,10 +90,16 @@ export async function requestAzureDevOpsJsonAtBase<T>(
     })
     if (!response.ok) {
       await cancelUnreadResponseBody(response)
+      if (throwOnFailure) {
+        throw new Error(`Azure DevOps request failed: HTTP ${response.status}`)
+      }
       return null
     }
     return (await response.json()) as T
-  } catch {
+  } catch (error) {
+    if (throwOnFailure) {
+      throw error
+    }
     return null
   }
 }
@@ -97,7 +107,8 @@ export async function requestAzureDevOpsJsonAtBase<T>(
 export function requestAzureDevOpsJson<T>(
   repo: AzureDevOpsRepoRef,
   path: string,
-  options: AzureDevOpsRequestOptions = {}
+  options: AzureDevOpsRequestOptions = {},
+  throwOnFailure = false
 ): Promise<T | null> {
-  return requestAzureDevOpsJsonAtBase(configuredApiBaseUrl(repo), path, options)
+  return requestAzureDevOpsJsonAtBase(configuredApiBaseUrl(repo), path, options, throwOnFailure)
 }
diff --git a/src/main/azure-devops/client.test.ts b/src/main/azure-devops/client.test.ts
index d394962fcff..8c993a9db0d 100644
--- a/src/main/azure-devops/client.test.ts
+++ b/src/main/azure-devops/client.test.ts
@@ -3,6 +3,7 @@ import { cancelTrackingResponse } from '../lib/unread-response-body.test-fixture
 import {
   getAzureDevOpsAuthStatus,
   getAzureDevOpsPullRequestForBranch,
+  getAzureDevOpsPullRequestForBranchOrThrow,
   normalizeAzureDevOpsApiBaseUrl
 } from './client'
 import { _resetAzureDevOpsRepoRefCache } from './repository-ref'
@@ -122,6 +123,37 @@ describe('Azure DevOps client', () => {
     ])
   })
 
+  it('getAzureDevOpsPullRequestForBranchOrThrow surfaces a list failure instead of null (finding 4)', async () => {
+    gitExecFileAsyncMock.mockResolvedValue({
+      stdout: 'https://dev.azure.com/acme/Project/_git/repo\n'
+    })
+    globalThis.fetch = vi.fn(async (input: string | URL | Request) => {
+      const url = new URL(String(input))
+      if (url.pathname === '/acme/Project/_apis/git/repositories/repo') {
+        return new Response(
+          JSON.stringify({
+            id: 'repo-guid',
+            webUrl: 'https://dev.azure.com/acme/Project/_git/repo'
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } }
+        )
+      }
+      // The pull-request list lookup fails (auth/transport).
+      return new Response(JSON.stringify({ message: 'forbidden' }), { status: 403 })
+    }) as never
+
+    // The swallowing variant collapses the failure into a false "no PR".
+    await expect(
+      getAzureDevOpsPullRequestForBranch('/repo', 'refs/heads/feature/azure')
+    ).resolves.toBeNull()
+    _resetAzureDevOpsRepoRefCache()
+    // The throwing variant makes the failure visible so eligibility records
+    // `unavailable` rather than a false "No pull request found".
+    await expect(
+      getAzureDevOpsPullRequestForBranchOrThrow('/repo', 'refs/heads/feature/azure')
+    ).rejects.toThrow(/Azure DevOps request failed/)
+  })
+
   it('uses the most recent branch PR instead of preferring stale active PRs', async () => {
     gitExecFileAsyncMock.mockResolvedValue({
       stdout: 'https://dev.azure.com/acme/Project/_git/repo\n'
diff --git a/src/main/azure-devops/client.ts b/src/main/azure-devops/client.ts
index 2bed23c2cd4..25390ba4bfa 100644
--- a/src/main/azure-devops/client.ts
+++ b/src/main/azure-devops/client.ts
@@ -197,7 +197,8 @@ export async function getAzureDevOpsPullRequestForBranch(
   branch: string,
   linkedPRNumber?: number | null,
   connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
+  options: HostedReviewExecutionOptions = {},
+  throwOnFailure = false
 ): Promise<AzureDevOpsPullRequestInfo | null> {
   const branchName = branch.replace(/^refs\/heads\//, '')
   if (!branchName && linkedPRNumber == null) {
@@ -224,7 +225,8 @@ export async function getAzureDevOpsPullRequestForBranch(
           'searchCriteria.status': 'all',
           $top: 10
         }
-      }
+      },
+      throwOnFailure
     )
     const raw = (list?.value ?? []).sort(sortPullRequestsForBranch)[0]
     if (raw) {
@@ -239,11 +241,35 @@ export async function getAzureDevOpsPullRequestForBranch(
     repo,
     `/_apis/git/repositories/${encodePathSegment(repository.idOrName)}/pullRequests/${encodePathSegment(
       String(linkedPRNumber)
-    )}`
+    )}`,
+    {},
+    throwOnFailure
   )
   return raw ? normalizePullRequest(repo, repository.idOrName, repository.webBaseUrl, raw) : null
 }
 
+/**
+ * Existing-review lookup that surfaces transport/auth failures instead of
+ * collapsing them to null, so a failed lookup becomes
+ * `reviewLookupOutcome: 'unavailable'` rather than a false "No pull request found".
+ */
+export function getAzureDevOpsPullRequestForBranchOrThrow(
+  repoPath: string,
+  branch: string,
+  linkedPRNumber?: number | null,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<AzureDevOpsPullRequestInfo | null> {
+  return getAzureDevOpsPullRequestForBranch(
+    repoPath,
+    branch,
+    linkedPRNumber,
+    connectionId,
+    options,
+    true
+  )
+}
+
 export async function getAzureDevOpsRepoSlug(
   repoPath: string,
   connectionId?: string | null,
diff --git a/src/main/bitbucket/client.test.ts b/src/main/bitbucket/client.test.ts
index 4e552ab59cd..7ecfeb64151 100644
--- a/src/main/bitbucket/client.test.ts
+++ b/src/main/bitbucket/client.test.ts
@@ -9,7 +9,11 @@ vi.mock('../git/runner', () => ({
   gitExecFileAsync: gitExecFileAsyncMock
 }))
 
-import { getBitbucketAuthStatus, getBitbucketPullRequestForBranch } from './client'
+import {
+  getBitbucketAuthStatus,
+  getBitbucketPullRequestForBranch,
+  getBitbucketPullRequestForBranchOrThrow
+} from './client'
 import { _resetBitbucketRepoRefCache } from './repository-ref'
 
 const OLD_ENV = process.env
@@ -93,6 +97,19 @@ describe('Bitbucket client', () => {
     )
   })
 
+  it('getBitbucketPullRequestForBranchOrThrow surfaces a failure instead of null (finding 4)', async () => {
+    const fetchMock = vi.fn(async () => Response.json({ error: 'forbidden' }, { status: 403 }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    // The swallowing variant collapses a real failure into a false "no PR".
+    await expect(getBitbucketPullRequestForBranch('/repo', 'feature/bitbucket')).resolves.toBeNull()
+    // The throwing variant makes the failure visible so eligibility records
+    // `unavailable` rather than a false "No pull request found".
+    await expect(
+      getBitbucketPullRequestForBranchOrThrow('/repo', 'feature/bitbucket')
+    ).rejects.toThrow(/Bitbucket request failed/)
+  })
+
   it('falls back to a linked PR number when branch lookup misses', async () => {
     const fetchMock = vi.fn(async (url: string, _init?: RequestInit) => {
       if (url.includes('/statuses/build')) {
diff --git a/src/main/bitbucket/client.ts b/src/main/bitbucket/client.ts
index 6dbc11f65da..ae4158fa180 100644
--- a/src/main/bitbucket/client.ts
+++ b/src/main/bitbucket/client.ts
@@ -87,7 +87,14 @@ function apiUrl(path: string, searchParams?: RequestOptions['searchParams']): st
   return url.toString()
 }
 
-async function requestJson<T>(path: string, options: RequestOptions = {}): Promise<T | null> {
+async function requestJson<T>(
+  path: string,
+  options: RequestOptions = {},
+  // Why: the existing-review lookup behind Create must distinguish a real
+  // transport/auth failure from an accepted "no PR". When true, a failed request
+  // throws instead of collapsing to null so callers never report false not_found.
+  throwOnFailure = false
+): Promise<T | null> {
   const config = getAuthConfig()
   try {
     const response = await fetch(apiUrl(path, options.searchParams), {
@@ -99,10 +106,16 @@ async function requestJson<T>(path: string, options: RequestOptions = {}): Promi
     })
     if (!response.ok) {
       await cancelUnreadResponseBody(response)
+      if (throwOnFailure) {
+        throw new Error(`Bitbucket request failed: HTTP ${response.status}`)
+      }
       return null
     }
     return (await response.json()) as T
-  } catch {
+  } catch (error) {
+    if (throwOnFailure) {
+      throw error
+    }
     return null
   }
 }
@@ -184,7 +197,8 @@ export async function getBitbucketPullRequestForBranch(
   branch: string,
   linkedPRNumber?: number | null,
   connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
+  options: HostedReviewExecutionOptions = {},
+  throwOnFailure = false
 ): Promise<BitbucketPullRequestInfo | null> {
   const branchName = branch.replace(/^refs\/heads\//, '')
   if (!branchName && linkedPRNumber == null) {
@@ -214,7 +228,8 @@ export async function getBitbucketPullRequestForBranch(
           q: query,
           state: ALL_PULL_REQUEST_STATES
         }
-      }
+      },
+      throwOnFailure
     )
     const raw = list?.values?.[0]
     if (raw) {
@@ -226,11 +241,36 @@ export async function getBitbucketPullRequestForBranch(
     return null
   }
   const raw = await requestJson<RawBitbucketPullRequest>(
-    `/repositories/${encodedRepoPath(repo)}/pullrequests/${encodeURIComponent(String(linkedPRNumber))}`
+    `/repositories/${encodedRepoPath(repo)}/pullrequests/${encodeURIComponent(String(linkedPRNumber))}`,
+    {},
+    throwOnFailure
   )
   return raw ? normalizePullRequest(repo, raw) : null
 }
 
+/**
+ * Existing-review lookup that surfaces transport/auth failures instead of
+ * collapsing them to null. The hosted-review creation preflight uses this so a
+ * failed lookup becomes `reviewLookupOutcome: 'unavailable'`, never a false
+ * "No pull request found".
+ */
+export function getBitbucketPullRequestForBranchOrThrow(
+  repoPath: string,
+  branch: string,
+  linkedPRNumber?: number | null,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<BitbucketPullRequestInfo | null> {
+  return getBitbucketPullRequestForBranch(
+    repoPath,
+    branch,
+    linkedPRNumber,
+    connectionId,
+    options,
+    true
+  )
+}
+
 export async function getBitbucketRepoSlug(
   repoPath: string,
   connectionId?: string | null,
diff --git a/src/main/git/exec-error.ts b/src/main/git/exec-error.ts
new file mode 100644
index 00000000000..fb44e54917a
--- /dev/null
+++ b/src/main/git/exec-error.ts
@@ -0,0 +1,111 @@
+/**
+ * Pure helpers for reading diagnostics out of a subprocess (git/gh/glab)
+ * rejection. Kept in a standalone module (not `runner.ts`) so lightweight
+ * consumers — e.g. PR-refresh error classification — can import them without
+ * pulling in the runner's heavy execution machinery, and so tests that mock
+ * `./runner` still get the real implementations.
+ */
+
+/**
+ * Extract stderr/stdout from an execFile rejection.
+ *
+ * Why: Node's execFile rejects with an Error that has `.stdout` and `.stderr`
+ * fields populated separately from `.message`. Reading `err.message` alone is
+ * unreliable — it can truncate stderr or omit it entirely depending on Node
+ * version and maxBuffer behavior. We prefer the explicit fields and fall
+ * back to `.message` only when neither is present.
+ */
+export function extractExecError(err: unknown): { stderr: string; stdout: string } {
+  if (err && typeof err === 'object') {
+    const e = err as { stderr?: unknown; stdout?: unknown; message?: unknown }
+    const stderr =
+      typeof e.stderr === 'string'
+        ? e.stderr
+        : Buffer.isBuffer(e.stderr)
+          ? e.stderr.toString('utf-8')
+          : ''
+    const stdout =
+      typeof e.stdout === 'string'
+        ? e.stdout
+        : Buffer.isBuffer(e.stdout)
+          ? e.stdout.toString('utf-8')
+          : ''
+    if (stderr || stdout) {
+      return { stderr, stdout }
+    }
+    if (typeof e.message === 'string') {
+      return { stderr: e.message, stdout: '' }
+    }
+  }
+  return { stderr: String(err), stdout: '' }
+}
+
+/**
+ * Detect a Retry-After hint in gh stderr and return the suggested delay in ms,
+ * or null when the response includes no Retry-After.
+ *
+ * Why: gh forwards response headers when verbose, and prints "Retry-After:
+ * <seconds>" in error output for primary rate-limit 429s. When present, the
+ * caller is better served by propagating the error so the UI can surface the
+ * real wait time — retrying on our own 250ms cadence just earns another 429
+ * and burns the retry budget. Also supports HTTP-date Retry-After values.
+ */
+export function parseRetryAfterMs(stderr: string): number | null {
+  const raw = findRetryAfterHeaderValue(stderr)
+  if (raw === null) {
+    return null
+  }
+  if (/^\d+$/.test(raw)) {
+    const seconds = Number(raw)
+    return Number.isFinite(seconds) ? seconds * 1000 : null
+  }
+  const ts = Date.parse(raw)
+  if (Number.isNaN(ts)) {
+    return null
+  }
+  return Math.max(0, ts - Date.now())
+}
+
+function findRetryAfterHeaderValue(stderr: string): string | null {
+  const headerIndex = indexOfAsciiIgnoreCase(stderr, 'retry-after:', 0)
+  if (headerIndex === -1) {
+    return null
+  }
+  let valueStart = headerIndex + 'retry-after:'.length
+  while (valueStart < stderr.length) {
+    const code = stderr.charCodeAt(valueStart)
+    if (code !== 9 && code !== 32) {
+      break
+    }
+    valueStart++
+  }
+  let valueEnd = valueStart
+  while (valueEnd < stderr.length) {
+    const code = stderr.charCodeAt(valueEnd)
+    if (code === 10 || code === 13) {
+      break
+    }
+    valueEnd++
+  }
+  const value = stderr.slice(valueStart, valueEnd).trim()
+  return value.length > 0 ? value : null
+}
+
+function indexOfAsciiIgnoreCase(value: string, search: string, fromIndex: number): number {
+  const lastStart = value.length - search.length
+  for (let index = Math.max(0, fromIndex); index <= lastStart; index++) {
+    let matches = true
+    for (let offset = 0; offset < search.length; offset++) {
+      const code = value.charCodeAt(index + offset)
+      const normalizedCode = code >= 65 && code <= 90 ? code + 32 : code
+      if (normalizedCode !== search.charCodeAt(offset)) {
+        matches = false
+        break
+      }
+    }
+    if (matches) {
+      return index
+    }
+  }
+  return -1
+}
diff --git a/src/main/git/runner.ts b/src/main/git/runner.ts
index 27d1e5837b9..8c70421e3ef 100644
--- a/src/main/git/runner.ts
+++ b/src/main/git/runner.ts
@@ -42,6 +42,10 @@ import {
 } from '../../shared/wsl-login-shell-command'
 import { UNTRANSLATED_GIT_OUTPUT_ENV } from '../../shared/git-output-locale'
 import { endSubprocessStdin } from '../../shared/subprocess-stdin-write'
+// Re-exported for existing importers; lightweight consumers should import these
+// from './exec-error' directly so they do not depend on this heavy module.
+import { extractExecError, parseRetryAfterMs } from './exec-error'
+export { extractExecError, parseRetryAfterMs }
 
 // ─── Core resolution ────────────────────────────────────────────────
 
@@ -1233,110 +1237,6 @@ function argsLookIdempotent(args: string[]): boolean {
   return true
 }
 
-/**
- * Extract stderr from an execFile rejection.
- *
- * Why: Node's execFile rejects with an Error that has `.stdout` and `.stderr`
- * fields populated separately from `.message`. Reading `err.message` alone is
- * unreliable — it can truncate stderr or omit it entirely depending on Node
- * version and maxBuffer behavior. We prefer the explicit fields and fall
- * back to `.message` only when neither is present.
- */
-export function extractExecError(err: unknown): { stderr: string; stdout: string } {
-  if (err && typeof err === 'object') {
-    const e = err as { stderr?: unknown; stdout?: unknown; message?: unknown }
-    const stderr =
-      typeof e.stderr === 'string'
-        ? e.stderr
-        : Buffer.isBuffer(e.stderr)
-          ? e.stderr.toString('utf-8')
-          : ''
-    const stdout =
-      typeof e.stdout === 'string'
-        ? e.stdout
-        : Buffer.isBuffer(e.stdout)
-          ? e.stdout.toString('utf-8')
-          : ''
-    if (stderr || stdout) {
-      return { stderr, stdout }
-    }
-    if (typeof e.message === 'string') {
-      return { stderr: e.message, stdout: '' }
-    }
-  }
-  return { stderr: String(err), stdout: '' }
-}
-
-/**
- * Detect a Retry-After hint in gh stderr and return the suggested delay in ms,
- * or null when the response includes no Retry-After.
- *
- * Why: gh forwards response headers when verbose, and prints "Retry-After:
- * <seconds>" in error output for primary rate-limit 429s. When present, the
- * caller is better served by propagating the error so the UI can surface the
- * real wait time — retrying on our own 250ms cadence just earns another 429
- * and burns the retry budget. Also supports HTTP-date Retry-After values.
- */
-export function parseRetryAfterMs(stderr: string): number | null {
-  const raw = findRetryAfterHeaderValue(stderr)
-  if (raw === null) {
-    return null
-  }
-  if (/^\d+$/.test(raw)) {
-    const seconds = Number(raw)
-    return Number.isFinite(seconds) ? seconds * 1000 : null
-  }
-  const ts = Date.parse(raw)
-  if (Number.isNaN(ts)) {
-    return null
-  }
-  return Math.max(0, ts - Date.now())
-}
-
-function findRetryAfterHeaderValue(stderr: string): string | null {
-  const headerIndex = indexOfAsciiIgnoreCase(stderr, 'retry-after:', 0)
-  if (headerIndex === -1) {
-    return null
-  }
-  let valueStart = headerIndex + 'retry-after:'.length
-  while (valueStart < stderr.length) {
-    const code = stderr.charCodeAt(valueStart)
-    if (code !== 9 && code !== 32) {
-      break
-    }
-    valueStart++
-  }
-  let valueEnd = valueStart
-  while (valueEnd < stderr.length) {
-    const code = stderr.charCodeAt(valueEnd)
-    if (code === 10 || code === 13) {
-      break
-    }
-    valueEnd++
-  }
-  const value = stderr.slice(valueStart, valueEnd).trim()
-  return value.length > 0 ? value : null
-}
-
-function indexOfAsciiIgnoreCase(value: string, search: string, fromIndex: number): number {
-  const lastStart = value.length - search.length
-  for (let index = Math.max(0, fromIndex); index <= lastStart; index++) {
-    let matches = true
-    for (let offset = 0; offset < search.length; offset++) {
-      const code = value.charCodeAt(index + offset)
-      const normalizedCode = code >= 65 && code <= 90 ? code + 32 : code
-      if (normalizedCode !== search.charCodeAt(offset)) {
-        matches = false
-        break
-      }
-    }
-    if (matches) {
-      return index
-    }
-  }
-  return -1
-}
-
 /**
  * Classify whether a gh execFile rejection is worth retrying.
  *
diff --git a/src/main/gitea/client.test.ts b/src/main/gitea/client.test.ts
index a0ae0b3ce4f..60f3441263c 100644
--- a/src/main/gitea/client.test.ts
+++ b/src/main/gitea/client.test.ts
@@ -12,6 +12,7 @@ vi.mock('../git/runner', () => ({
 import {
   getGiteaAuthStatus,
   getGiteaPullRequestForBranch,
+  getGiteaPullRequestForBranchOrThrow,
   normalizeGiteaApiBaseUrl
 } from './client'
 import { _resetGiteaRepoRefCache } from './repository-ref'
@@ -172,6 +173,19 @@ describe('Gitea client', () => {
     }
   })
 
+  it('surfaces a lookup failure via getGiteaPullRequestForBranchOrThrow instead of null (finding 4)', async () => {
+    const fetchMock = vi.fn(async () => Response.json({ message: 'unauthorized' }, { status: 403 }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    // The swallowing variant returns null — indistinguishable from "no PR".
+    await expect(getGiteaPullRequestForBranch('/repo', 'feature/gitea')).resolves.toBeNull()
+    // The throwing variant makes the failure visible so eligibility records
+    // `unavailable` rather than a false "No pull request found".
+    await expect(getGiteaPullRequestForBranchOrThrow('/repo', 'feature/gitea')).rejects.toThrow(
+      /Gitea request failed/
+    )
+  })
+
   it('expires successful scans and bounds retained repository listings', async () => {
     vi.useFakeTimers()
     try {
diff --git a/src/main/gitea/client.ts b/src/main/gitea/client.ts
index 9889598b612..da6c498d8b7 100644
--- a/src/main/gitea/client.ts
+++ b/src/main/gitea/client.ts
@@ -78,7 +78,11 @@ function apiUrl(baseUrl: string, path: string, searchParams?: RequestOptions['se
 async function requestJsonAtBase<T>(
   baseUrl: string,
   path: string,
-  options: RequestOptions = {}
+  options: RequestOptions = {},
+  // Why: the existing-review lookup behind Create must distinguish a real
+  // transport/auth failure from an accepted "no PR". When true, a failed request
+  // throws instead of collapsing to null so callers never report false not_found.
+  throwOnFailure = false
 ): Promise<T | null> {
   const config = getAuthConfig()
   try {
@@ -91,10 +95,16 @@ async function requestJsonAtBase<T>(
     })
     if (!response.ok) {
       await cancelUnreadResponseBody(response)
+      if (throwOnFailure) {
+        throw new Error(`Gitea request failed: HTTP ${response.status}`)
+      }
       return null
     }
     return (await response.json()) as T
-  } catch {
+  } catch (error) {
+    if (throwOnFailure) {
+      throw error
+    }
     return null
   }
 }
@@ -102,9 +112,10 @@ async function requestJsonAtBase<T>(
 function requestJson<T>(
   repo: GiteaRepoRef,
   path: string,
-  options: RequestOptions = {}
+  options: RequestOptions = {},
+  throwOnFailure = false
 ): Promise<T | null> {
-  return requestJsonAtBase(configuredApiBaseUrl(repo), path, options)
+  return requestJsonAtBase(configuredApiBaseUrl(repo), path, options, throwOnFailure)
 }
 
 function encodedRepoPath(repo: GiteaRepoRef): string {
@@ -227,7 +238,8 @@ export async function getGiteaPullRequestForBranch(
   branch: string,
   linkedPRNumber?: number | null,
   connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
+  options: HostedReviewExecutionOptions = {},
+  throwOnFailure = false
 ): Promise<GiteaPullRequestInfo | null> {
   const branchName = branch.replace(/^refs\/heads\//, '')
   if (!branchName && linkedPRNumber == null) {
@@ -245,17 +257,25 @@ export async function getGiteaPullRequestForBranch(
 
   if (branchName) {
     const pullRequests = await scanGiteaPullRequests(
-      giteaPullRequestScanKey(repo),
+      // Why: throwing scans keep a separate cache namespace so they never reuse a
+      // prior swallowing scan's cached-empty from a failed page fetch, which would
+      // otherwise let a real lookup failure masquerade as "no PR".
+      throwOnFailure ? `${giteaPullRequestScanKey(repo)}::strict` : giteaPullRequestScanKey(repo),
       (page) =>
-        requestJson<RawGiteaPullRequest[]>(repo, `/repos/${encodedRepoPath(repo)}/pulls`, {
-          searchParams: {
-            state: 'all',
-            sort: 'recentupdate',
-            page,
-            limit: PULL_REQUEST_PAGE_LIMIT
+        requestJson<RawGiteaPullRequest[]>(
+          repo,
+          `/repos/${encodedRepoPath(repo)}/pulls`,
+          {
+            searchParams: {
+              state: 'all',
+              sort: 'recentupdate',
+              page,
+              limit: PULL_REQUEST_PAGE_LIMIT
+            },
+            timeoutMs: PULL_REQUEST_LIST_TIMEOUT_MS
           },
-          timeoutMs: PULL_REQUEST_LIST_TIMEOUT_MS
-        }),
+          throwOnFailure
+        ),
       PULL_REQUEST_PAGE_LIMIT,
       MAX_PULL_REQUEST_PAGES
     )
@@ -270,11 +290,28 @@ export async function getGiteaPullRequestForBranch(
   }
   const raw = await requestJson<RawGiteaPullRequest>(
     repo,
-    `/repos/${encodedRepoPath(repo)}/pulls/${encodeURIComponent(String(linkedPRNumber))}`
+    `/repos/${encodedRepoPath(repo)}/pulls/${encodeURIComponent(String(linkedPRNumber))}`,
+    {},
+    throwOnFailure
   )
   return raw ? normalizePullRequest(repo, raw) : null
 }
 
+/**
+ * Existing-review lookup that surfaces transport/auth failures instead of
+ * collapsing them to null, so a failed lookup becomes
+ * `reviewLookupOutcome: 'unavailable'` rather than a false "No pull request found".
+ */
+export function getGiteaPullRequestForBranchOrThrow(
+  repoPath: string,
+  branch: string,
+  linkedPRNumber?: number | null,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<GiteaPullRequestInfo | null> {
+  return getGiteaPullRequestForBranch(repoPath, branch, linkedPRNumber, connectionId, options, true)
+}
+
 export async function getGiteaRepoSlug(
   repoPath: string,
   connectionId?: string | null,
diff --git a/src/main/github/client.test.ts b/src/main/github/client.test.ts
index d403d582fcd..07a007f7f1e 100644
--- a/src/main/github/client.test.ts
+++ b/src/main/github/client.test.ts
@@ -1268,6 +1268,34 @@ describe('getPRForBranch', () => {
     )
   })
 
+  it('propagates a Retry-After cooldown into the rate-limited retry schedule', async () => {
+    resolvePRRepositoryCandidatesMock.mockResolvedValueOnce({
+      candidates: [{ owner: 'stablyai', repo: 'orca' }],
+      headRepo: null
+    })
+    // gh puts the diagnostic on `.stderr`; a secondary limit carries Retry-After.
+    ghExecFileAsyncMock
+      .mockRejectedValueOnce(
+        Object.assign(new Error('gh exited with 1.'), {
+          stderr: 'HTTP 403: You have exceeded a secondary rate limit\nRetry-After: 120'
+        })
+      )
+      .mockResolvedValueOnce({ stdout: JSON.stringify([]) })
+
+    const before = Date.now()
+    const outcome = await getPRForBranchOutcome('/repo-root', 'feature/test')
+    expect(outcome.kind).toBe('upstream-error')
+    if (outcome.kind !== 'upstream-error') {
+      throw new Error('expected upstream-error')
+    }
+    expect(outcome.errorType).toBe('rate_limited')
+    // ~120s cooldown surfaced as both the manual gate and the auto-retry time.
+    expect(outcome.retryDisabledUntil).toBeDefined()
+    expect(outcome.nextAutoRetryAt).toBe(outcome.retryDisabledUntil)
+    expect(outcome.retryDisabledUntil ?? 0).toBeGreaterThanOrEqual(before + 119_000)
+    expect(outcome.retryDisabledUntil ?? 0).toBeLessThanOrEqual(Date.now() + 121_000)
+  })
+
   it('reports no PR when fallback branch discovery cleanly misses', async () => {
     resolvePRRepositoryCandidatesMock.mockResolvedValueOnce({
       candidates: [{ owner: 'stablyai', repo: 'orca' }],
diff --git a/src/main/github/client.ts b/src/main/github/client.ts
index 67d34bef4ba..d9d41f4f653 100644
--- a/src/main/github/client.ts
+++ b/src/main/github/client.ts
@@ -39,6 +39,10 @@ import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { sliceCheckLogTail } from './check-job-log-tail-slice'
+import {
+  classifyPRRefreshError,
+  safePRRefreshErrorMessage
+} from './pr-refresh-error-classification'
 import { getPRConflictSummary } from './conflict-summary'
 import { getSshFilesystemProvider } from '../providers/ssh-filesystem-dispatch'
 import { joinWorktreeRelativePath } from '../runtime/runtime-relative-paths'
@@ -47,7 +51,6 @@ import {
   execFileAsync,
   ghExecFileAsync,
   gitExecFileAsync,
-  extractExecError,
   acquire,
   release,
   getOwnerRepo,
@@ -63,6 +66,9 @@ import {
   type LocalGitExecOptions,
   type OwnerRepo
 } from './gh-utils'
+// Import the pure error-parsing helpers from the lightweight module, not
+// `./gh-utils`, so tests that mock gh-utils still resolve the real functions.
+import { extractExecError, parseRetryAfterMs } from '../git/exec-error'
 import {
   isCommitPartOfMergedPR,
   type MergedPRCommitMembership
@@ -181,61 +187,28 @@ async function assertRateLimitBudget(bucket: RateLimitBucketKind): Promise<void>
   }
 }
 
-function classifyPRRefreshError(
-  err: unknown
-): Extract<PRRefreshOutcome, { kind: 'upstream-error' }>['errorType'] {
-  const message = err instanceof Error ? err.message : String(err)
-  // Why: GitHub-unreachable buckets (5xx outage / network / rate limit) share
-  // one detector with the Tasks work-item path so both surfaces attribute an
-  // outage to GitHub identically. Rate-limit responses also carry "HTTP 403",
-  // so this must run before the permission check below.
-  const unavailable = classifyGitHubUnavailable(message)
-  if (unavailable) {
-    return unavailable
-  }
-  const lower = message.toLowerCase()
-  if (lower.includes('http 403') || lower.includes('resource not accessible')) {
-    return 'permission'
-  }
-  if (lower.includes('http 404') || lower.includes('could not resolve to a repository')) {
-    return 'repo_unavailable'
-  }
-  return /auth|login|credential/i.test(message) ? 'auth' : 'unknown'
-}
-
-function safePRRefreshErrorMessage(
-  errorType: Extract<PRRefreshOutcome, { kind: 'upstream-error' }>['errorType']
-): string {
-  switch (errorType) {
-    case 'rate_limited':
-      return 'GitHub rate limit is low. Try again after the limit resets.'
-    case 'auth':
-      return 'GitHub authentication is unavailable. Check your gh login.'
-    case 'network':
-      return 'GitHub is unreachable right now. Check your network and try again.'
-    case 'server_error':
-      return "GitHub's API is temporarily unavailable (server error). This is a GitHub-side issue."
-    case 'permission':
-      return 'GitHub did not allow access to this pull request.'
-    case 'repo_unavailable':
-      return 'The GitHub repository is unavailable or cannot be resolved.'
-    case 'gh_unavailable':
-      return 'GitHub CLI is unavailable.'
-    case 'unknown':
-      return 'GitHub pull request refresh failed.'
-  }
-}
-
 function prRefreshUpstreamError(
   err: unknown
 ): Extract<PRRefreshOutcome, { kind: 'upstream-error' }> {
   const errorType = classifyPRRefreshError(err)
-  return {
+  const outcome: Extract<PRRefreshOutcome, { kind: 'upstream-error' }> = {
     kind: 'upstream-error',
     errorType,
     message: safePRRefreshErrorMessage(errorType),
     fetchedAt: Date.now()
   }
+  // Why: a rate limit that carries a Retry-After is a real cooldown — surface it
+  // as the retry schedule so the renderer disables manual Retry until the reset
+  // and shows a truthful auto-retry time, instead of retrying into another 429.
+  if (errorType === 'rate_limited') {
+    const retryAfterMs = parseRetryAfterMs(extractExecError(err).stderr)
+    if (retryAfterMs !== null && retryAfterMs > 0) {
+      const retryAt = Date.now() + retryAfterMs
+      outcome.nextAutoRetryAt = retryAt
+      outcome.retryDisabledUntil = retryAt
+    }
+  }
+  return outcome
 }
 
 function isNoPullRequestError(err: unknown): boolean {
diff --git a/src/main/github/gh-utils.ts b/src/main/github/gh-utils.ts
index 38b3d23cf30..b294e90ac1a 100644
--- a/src/main/github/gh-utils.ts
+++ b/src/main/github/gh-utils.ts
@@ -1,11 +1,14 @@
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
-import { gitExecFileAsync, ghExecFileAsync, extractExecError } from '../git/runner'
+import { gitExecFileAsync, ghExecFileAsync } from '../git/runner'
+// Pure error-parsing helpers come from the lightweight module (not `runner`) so
+// tests that mock `../git/runner` still resolve the real implementations.
+import { extractExecError, parseRetryAfterMs } from '../git/exec-error'
 
 // Why: legacy generic execFile wrapper - only used by callers that don't need
 // WSL-aware routing. Repo-scoped callers should use the runner exports below.
 export const execFileAsync = promisify(execFile)
-export { ghExecFileAsync, gitExecFileAsync, extractExecError }
+export { ghExecFileAsync, gitExecFileAsync, extractExecError, parseRetryAfterMs }
 export { classifyGhError, classifyListIssuesError } from './gh-error-classification'
 export {
   _getOwnerRepoCacheSize,
diff --git a/src/main/github/pr-refresh-coordinator.ts b/src/main/github/pr-refresh-coordinator.ts
index bd59fc77cf2..700cc32ecd2 100644
--- a/src/main/github/pr-refresh-coordinator.ts
+++ b/src/main/github/pr-refresh-coordinator.ts
@@ -83,7 +83,30 @@ const queue = new Map<string, QueueEntry>()
 const backgroundStarts: number[] = []
 const activeStartsByScope = new Map<string, number[]>()
 const errorBackoff = new Map<string, { failures: number; retryAt: number }>()
+// Per-key manual-retry cooldown from a real secondary rate limit (Retry-After).
+// refreshPRNow refuses a manual retry until this time so a stale renderer cannot
+// bypass the gate the client advertised via `retryDisabledUntil`.
+const manualRetryGates = new Map<string, number>()
 let lastBackgroundStartAt = 0
+
+/**
+ * Track (or clear) the manual-retry cooldown for a key from a broadcast outcome.
+ * Only a rate-limit outcome carrying `retryDisabledUntil` sets a gate; any other
+ * settled outcome clears it.
+ */
+function noteManualRetryGate(key: string, outcome: PRRefreshOutcome): void {
+  if (outcome.kind === 'upstream-error' && outcome.retryDisabledUntil !== undefined) {
+    manualRetryGates.set(key, outcome.retryDisabledUntil)
+  } else {
+    manualRetryGates.delete(key)
+  }
+}
+
+/** Reset all per-key retry state (backoff + manual cooldown) when a key resets. */
+function resetKeyRetryState(key: string): void {
+  errorBackoff.delete(key)
+  manualRetryGates.delete(key)
+}
 const visibleByWindow = new Map<number, { generation: number; keys: Set<string> }>()
 let outcomeObserver: PRRefreshOutcomeObserver | null = null
 const diagnosticsCounters = {
@@ -101,7 +124,7 @@ function removeInvisibleVisibleRefreshes(): void {
   for (const [key, entry] of queue) {
     if (entry.reason === 'visible' && !isVisibleKey(key)) {
       queue.delete(key)
-      errorBackoff.delete(key)
+      resetKeyRetryState(key)
       broadcast({
         aliases: Array.from(entry.aliases.values()),
         reason: 'visible',
@@ -177,7 +200,7 @@ export function pruneWorktreePRRefreshAliases(worktreeId: string): void {
     // No aliases left means no worktree still cares about this refresh.
     if (entry.aliases.size === 0) {
       queue.delete(key)
-      errorBackoff.delete(key)
+      resetKeyRetryState(key)
       continue
     }
     // Keep the entry alive but ensure its representative candidate is not a
@@ -385,7 +408,7 @@ function removeQueuedAliasForInvalidCandidate(key: string, alias: GitHubPRRefres
   const replacementAlias = existing.aliases.values().next().value
   if (!replacementAlias) {
     queue.delete(key)
-    errorBackoff.delete(key)
+    resetKeyRetryState(key)
     return
   }
 
@@ -405,6 +428,44 @@ function removeQueuedAliasForInvalidCandidate(key: string, alias: GitHubPRRefres
   }
 }
 
+/**
+ * Advances the visible-key error backoff and returns the earliest retry time.
+ * The renderer surfaces this as `nextAutoRetryAt`; only visible keys auto-retry,
+ * so callers must gate on `isVisibleKey` before computing a schedule.
+ */
+function nextVisibleErrorRetryAt(key: string): number {
+  const failures = (errorBackoff.get(key)?.failures ?? 0) + 1
+  const retryAt =
+    Date.now() + Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** Math.min(failures - 1, 4))
+  errorBackoff.set(key, { failures, retryAt })
+  return retryAt
+}
+
+/**
+ * Stamps the auto-retry time onto an error outcome before broadcast so every
+ * alias receives identical timing.
+ *
+ * Why: this only sets `nextAutoRetryAt` (the "Orca will retry at {time}" hint).
+ * It must NOT set `retryDisabledUntil` — that field disables *manual* Retry and
+ * is reserved for a real rate-limit gate (the paused/breaker path in
+ * `refreshPRNow`, which maps `pausedUntil` into it). Deriving it from ordinary
+ * exponential backoff would disable a manual Retry that `refreshPRNow` would in
+ * fact accept.
+ */
+function withErrorSchedule(outcome: PRRefreshOutcome, retryAt: number): PRRefreshOutcome {
+  if (outcome.kind !== 'upstream-error') {
+    return outcome
+  }
+  // Why: preserve a real Retry-After cooldown the client already stamped on the
+  // outcome (`retryDisabledUntil`); auto-retry no earlier than both the backoff
+  // and that cooldown so we do not retry into an active secondary rate limit.
+  const cooldownUntil = outcome.retryDisabledUntil
+  return {
+    ...outcome,
+    nextAutoRetryAt: cooldownUntil !== undefined ? Math.max(retryAt, cooldownUntil) : retryAt
+  }
+}
+
 function scheduleVisibleFollowUp(
   key: string,
   candidate: GitHubPRRefreshCandidate,
@@ -412,19 +473,18 @@ function scheduleVisibleFollowUp(
   priority: number,
   aliases: GitHubPRRefreshAlias[],
   windowId?: number,
-  options?: { pendingMergeabilityDelayMs?: number }
+  options?: { pendingMergeabilityDelayMs?: number; plannedRetryAt?: number }
 ): void {
   if (!isVisibleKey(key)) {
     // Why: manual/active refreshes can remove the queued visible retry after
     // its owner window is gone, leaving the retry backoff without an owner.
-    errorBackoff.delete(key)
+    resetKeyRetryState(key)
     return
   }
   if (outcome.kind === 'upstream-error') {
-    const failures = (errorBackoff.get(key)?.failures ?? 0) + 1
-    const retryAt =
-      Date.now() + Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** Math.min(failures - 1, 4))
-    errorBackoff.set(key, { failures, retryAt })
+    // Why: reuse the retry time already computed for the broadcast schedule so
+    // the same failure is not counted twice against the backoff.
+    const retryAt = options?.plannedRetryAt ?? nextVisibleErrorRetryAt(key)
     setVisibleFollowUp({
       key,
       candidate,
@@ -440,7 +500,7 @@ function scheduleVisibleFollowUp(
     scheduleDrain(retryAt - Date.now())
     return
   }
-  errorBackoff.delete(key)
+  resetKeyRetryState(key)
   const followUpCandidate = visibleCandidateAfterOutcome(candidate, outcome)
   const regularDueAt = freshRetryAt(followUpCandidate) ?? Date.now()
   const pendingMergeabilityDueAt =
@@ -693,7 +753,7 @@ async function drainQueue(): Promise<void> {
         continue
       }
       if (next.reason === 'visible' && !isVisibleKey(next.key)) {
-        errorBackoff.delete(next.key)
+        resetKeyRetryState(next.key)
         broadcast({ aliases, reason: next.reason, status: 'skipped', skippedReason: 'fresh' })
         continue
       }
@@ -748,15 +808,30 @@ async function drainQueue(): Promise<void> {
         next.candidate.linkedPRNumber == null ? (next.candidate.fallbackPRNumber ?? null) : null,
         ...hostedReviewOptionArgs(next.candidate)
       )
+      // Why: compute the retry schedule before broadcasting so the outcome and
+      // its follow-up retry share one timing; only visible keys auto-retry.
+      let plannedRetryAt: number | undefined
+      let broadcastOutcome = outcome
+      if (outcome.kind === 'upstream-error' && isVisibleKey(next.key)) {
+        plannedRetryAt = nextVisibleErrorRetryAt(next.key)
+        broadcastOutcome = withErrorSchedule(outcome, plannedRetryAt)
+      }
       outcomeObserver?.(next.candidate, outcome)
-      broadcast({ aliases, reason: next.reason, outcome, requestStartedAt }, requestSequence)
+      noteManualRetryGate(next.key, broadcastOutcome)
+      broadcast(
+        { aliases, reason: next.reason, outcome: broadcastOutcome, requestStartedAt },
+        requestSequence
+      )
       scheduleVisibleFollowUp(
         next.key,
         next.candidate,
         outcome,
         next.priority,
         aliases,
-        next.windowId
+        next.windowId,
+        {
+          plannedRetryAt
+        }
       )
     }
   } finally {
@@ -893,6 +968,53 @@ export async function refreshPRNow(candidate: GitHubPRRefreshCandidate): Promise
     return outcome
   }
 
+  // Why: enforce the same rate-limit gate main advertises via `retryDisabledUntil`
+  // so a stale renderer cannot bypass it. A blocked primary bucket means gh would
+  // 403 anyway; a recorded secondary Retry-After cooldown means gh would 429
+  // again. Refuse without spending quota until the later of the two and report
+  // the pause honestly.
+  const manualBlockedGuard = backgroundRefreshBuckets()
+    .map((bucket) => rateLimitGuard(bucket))
+    .find((guard) => guard.blocked)
+  const secondaryGateUntil = manualRetryGates.get(key)
+  const gateUntil = Math.max(
+    manualBlockedGuard?.blocked ? manualBlockedGuard.resetAt * 1000 : 0,
+    secondaryGateUntil !== undefined ? secondaryGateUntil : 0
+  )
+  if (gateUntil > Date.now()) {
+    const retryAt = gateUntil
+    // Why: the paused broadcast maps `pausedUntil` into the renderer's
+    // `nextAutoRetryAt` ("Orca will retry at {time}"), so that auto-retry must be
+    // real. Requeue this candidate at the reset time and wake the drain then —
+    // mirroring the background paused path — instead of advertising an automatic
+    // retry that was never scheduled (finding 12).
+    queue.set(key, {
+      key,
+      candidate,
+      aliases: aliasMap,
+      reason: 'manual',
+      priority: 40,
+      dueAt: retryAt,
+      queuedAt: nextQueueOrder()
+    })
+    broadcast({
+      aliases,
+      reason: 'manual',
+      status: 'paused',
+      pausedUntil: retryAt,
+      skippedReason: 'rate-limit'
+    })
+    scheduleDrain(Math.max(1_000, retryAt - Date.now()))
+    return {
+      kind: 'upstream-error',
+      errorType: 'rate_limited',
+      message: 'GitHub is temporarily limiting requests. Try again after the limit resets.',
+      fetchedAt: Date.now(),
+      nextAutoRetryAt: retryAt,
+      retryDisabledUntil: retryAt
+    }
+  }
+
   queue.delete(key)
   const requestSequence = nextSequence()
   const requestStartedAt = Date.now()
@@ -905,12 +1027,23 @@ export async function refreshPRNow(candidate: GitHubPRRefreshCandidate): Promise
     candidate.linkedPRNumber == null ? (candidate.fallbackPRNumber ?? null) : null,
     ...hostedReviewOptionArgs(candidate)
   )
+  let plannedRetryAt: number | undefined
+  let broadcastOutcome = outcome
+  if (outcome.kind === 'upstream-error' && isVisibleKey(key)) {
+    plannedRetryAt = nextVisibleErrorRetryAt(key)
+    broadcastOutcome = withErrorSchedule(outcome, plannedRetryAt)
+  }
   outcomeObserver?.(candidate, outcome)
-  broadcast({ aliases, reason: 'manual', outcome, requestStartedAt }, requestSequence)
+  noteManualRetryGate(key, broadcastOutcome)
+  broadcast(
+    { aliases, reason: 'manual', outcome: broadcastOutcome, requestStartedAt },
+    requestSequence
+  )
   scheduleVisibleFollowUp(key, candidate, outcome, 40, aliases, undefined, {
+    plannedRetryAt,
     // Why: GitHub often reports UNKNOWN immediately after `gh pr reopen`;
     // do one prompt visible retry so conflicts replace the transient label.
     pendingMergeabilityDelayMs: MANUAL_MERGEABILITY_PENDING_REFRESH_MS
   })
-  return outcome
+  return broadcastOutcome
 }
diff --git a/src/main/github/pr-refresh-error-classification.test.ts b/src/main/github/pr-refresh-error-classification.test.ts
new file mode 100644
index 00000000000..549fc10fdc8
--- /dev/null
+++ b/src/main/github/pr-refresh-error-classification.test.ts
@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'vitest'
+import {
+  classifyPRRefreshError,
+  safePRRefreshErrorMessage
+} from './pr-refresh-error-classification'
+
+describe('classifyPRRefreshError', () => {
+  it('classifies an HTTP 429 as rate_limited even without a rate-limit body', () => {
+    expect(classifyPRRefreshError(new Error('HTTP 429 Too Many Requests'))).toBe('rate_limited')
+  })
+
+  it('classifies secondary rate limit markers as rate_limited, not permission', () => {
+    for (const message of [
+      'You have exceeded a secondary rate limit',
+      'abuse detection mechanism triggered',
+      'abuse-rate-limits',
+      'you have triggered an abuse detection mechanism'
+    ]) {
+      expect(classifyPRRefreshError(new Error(message))).toBe('rate_limited')
+    }
+  })
+
+  it('classifies a 403 carrying Retry-After as rate_limited, not permission', () => {
+    expect(classifyPRRefreshError(new Error('HTTP 403 Forbidden; Retry-After: 60'))).toBe(
+      'rate_limited'
+    )
+  })
+
+  it('classifies the primary breaker language as rate_limited', () => {
+    expect(classifyPRRefreshError(new Error('API rate limit exceeded for user'))).toBe(
+      'rate_limited'
+    )
+  })
+
+  it('classifies a plain 403 resource denial as permission', () => {
+    expect(
+      classifyPRRefreshError(new Error('HTTP 403: Resource not accessible by integration'))
+    ).toBe('permission')
+  })
+
+  it('classifies network failures', () => {
+    for (const message of ['ETIMEDOUT', 'could not resolve host github.com', 'network is down']) {
+      expect(classifyPRRefreshError(new Error(message))).toBe('network')
+    }
+  })
+
+  it('classifies 404 / could not resolve repository as repo_unavailable', () => {
+    expect(classifyPRRefreshError(new Error('HTTP 404 Not Found'))).toBe('repo_unavailable')
+    expect(
+      classifyPRRefreshError(new Error('Could not resolve to a Repository with the name'))
+    ).toBe('repo_unavailable')
+  })
+
+  it('classifies an ENOENT spawn failure as gh_unavailable', () => {
+    const err = Object.assign(new Error('spawn gh ENOENT'), { code: 'ENOENT' })
+    expect(classifyPRRefreshError(err)).toBe('gh_unavailable')
+    expect(classifyPRRefreshError(new Error("'gh' is not recognized as an internal command"))).toBe(
+      'gh_unavailable'
+    )
+  })
+
+  it('classifies auth failures after rate-limit and permission checks', () => {
+    expect(classifyPRRefreshError(new Error('authentication failed: bad credentials'))).toBe('auth')
+  })
+
+  it('falls back to unknown', () => {
+    expect(classifyPRRefreshError(new Error('something unexpected happened'))).toBe('unknown')
+  })
+
+  it('does not classify a message that merely contains "author" as auth', () => {
+    for (const message of [
+      'PR author octocat has no write access to the fork',
+      'authored 3 commits, none pushed',
+      'unexpected failure from author service'
+    ]) {
+      expect(classifyPRRefreshError(new Error(message))).toBe('unknown')
+    }
+  })
+
+  it('does not classify a repository name containing "network" as a network failure', () => {
+    // A repo/branch called "network-*" is not a connectivity failure; without a
+    // structured code or a real connectivity phrase this must stay unknown.
+    expect(classifyPRRefreshError(new Error('operation failed for repo acme/network-tools'))).toBe(
+      'unknown'
+    )
+  })
+
+  it('classifies a 404 repository error even when the message mentions network', () => {
+    // 404 ranks before the network branch so the repo error is not misread.
+    expect(
+      classifyPRRefreshError(
+        new Error('Could not resolve to a Repository named acme/network-proxy (HTTP 404)')
+      )
+    ).toBe('repo_unavailable')
+  })
+
+  it('classifies a 401 as auth', () => {
+    expect(classifyPRRefreshError(new Error('HTTP 401 Unauthorized'))).toBe('auth')
+  })
+
+  it('classifies from the real runner error shape where the signal is on .stderr', () => {
+    // Why: the runner rejects with a generic message and puts the gh diagnostic
+    // on `.stderr` (string or Buffer). Reading `.message` alone would misclassify
+    // these hard errors as `unknown` and treat them as transient.
+    const permission = Object.assign(new Error('gh exited with 1.'), {
+      stderr: 'HTTP 403: Resource not accessible by integration'
+    })
+    expect(classifyPRRefreshError(permission)).toBe('permission')
+
+    const repo = Object.assign(new Error('gh exited with 1.'), {
+      stderr: Buffer.from('HTTP 404: Not Found')
+    })
+    expect(classifyPRRefreshError(repo)).toBe('repo_unavailable')
+
+    const secondary = Object.assign(new Error('gh exited with 1.'), {
+      stderr: 'You have exceeded a secondary rate limit'
+    })
+    expect(classifyPRRefreshError(secondary)).toBe('rate_limited')
+
+    const auth = Object.assign(new Error('gh exited with 1.'), {
+      stdout: '',
+      stderr: 'gh auth login required: bad credentials'
+    })
+    expect(classifyPRRefreshError(auth)).toBe('auth')
+  })
+})
+
+describe('safePRRefreshErrorMessage', () => {
+  it('returns non-empty copy for every classified type without leaking raw errors', () => {
+    for (const type of [
+      'rate_limited',
+      'auth',
+      'network',
+      'permission',
+      'repo_unavailable',
+      'gh_unavailable',
+      'unknown'
+    ] as const) {
+      const message = safePRRefreshErrorMessage(type)
+      expect(message.length).toBeGreaterThan(0)
+      expect(message).not.toContain('ENOENT')
+    }
+  })
+})
diff --git a/src/main/github/pr-refresh-error-classification.ts b/src/main/github/pr-refresh-error-classification.ts
new file mode 100644
index 00000000000..aa9e226939d
--- /dev/null
+++ b/src/main/github/pr-refresh-error-classification.ts
@@ -0,0 +1,144 @@
+import type { PRRefreshErrorType } from '../../shared/types'
+import { classifyGitHubUnavailable } from '../../shared/github-api-availability'
+import { extractExecError } from '../git/exec-error'
+
+/**
+ * Sanitization boundary for GitHub PR-refresh failures. Maps a raw runner/CLI
+ * error to a stable {@link PRRefreshErrorType}; the renderer turns that into
+ * classified copy so raw stderr / env values never reach the UI.
+ *
+ * Classification order (see docs/reference/pr-panel-refresh-guidance.md):
+ * HTTP 429 / secondary rate limit → primary rate limit → repo_unavailable (404) →
+ * network → permission (403) → gh_unavailable → auth → unknown. GitHub returns
+ * 403 OR 429 for both primary and secondary limits, so the http-403 permission
+ * branch must run only after the rate-limit checks. 404 is matched before the
+ * network branch so a repository error whose message happens to contain a
+ * substring like "network" is not misread as a connectivity failure. Auth and
+ * network detection avoid broad substrings (e.g. "auth" inside "author", or a
+ * repo name containing "network") in favor of structured codes and full phrases.
+ */
+export function classifyPRRefreshError(err: unknown): PRRefreshErrorType {
+  // Why: the git/gh runner keeps diagnostics on `.stderr`/`.stdout` separate
+  // from `.message` (which can be just "gh exited with 1."). Reading message
+  // alone would misclassify a real "HTTP 403" / "HTTP 404" as `unknown`, so a
+  // hard error would be treated as transient. Combine all three for substring
+  // detection while still preferring the structured spawn `code`.
+  const { stderr, stdout } = extractExecError(err)
+  const message = err instanceof Error ? err.message : String(err)
+  const lower = `${message}\n${stderr}\n${stdout}`.toLowerCase()
+  const code =
+    err && typeof err === 'object' && 'code' in err
+      ? String((err as { code?: unknown }).code ?? '').toLowerCase()
+      : ''
+
+  // Rate limits first: a 429 is always a rate-limit signal; secondary limits also
+  // arrive as abuse-mechanism phrasing or a 403/429 carrying Retry-After, none of
+  // which contain "rate limit".
+  const isHttp429 = lower.includes('http 429') || lower.includes('429 too many requests')
+  const isHttp403 = lower.includes('http 403')
+  const hasRetryAfter = lower.includes('retry-after')
+  if (
+    isHttp429 ||
+    lower.includes('secondary rate limit') ||
+    lower.includes('abuse detection') ||
+    lower.includes('abuse-rate-limits') ||
+    lower.includes('you have triggered an abuse') ||
+    ((isHttp403 || isHttp429) && hasRetryAfter) ||
+    lower.includes('api rate limit exceeded') ||
+    lower.includes('rate limit')
+  ) {
+    return 'rate_limited'
+  }
+  // Repository resolution failures (404) rank before the network branch: a "could
+  // not resolve to a Repository" message must not be captured by a connectivity
+  // heuristic, and matching 404 first isolates it from any incidental substring.
+  if (lower.includes('http 404') || lower.includes('could not resolve to a repository')) {
+    return 'repo_unavailable'
+  }
+  // Why: keep GitHub 5xx/network attribution aligned with other GitHub surfaces.
+  const unavailable = classifyGitHubUnavailable(lower)
+  if (unavailable) {
+    return unavailable
+  }
+  // Network: structured error codes and full connectivity phrases only. Never a
+  // bare "network" substring — a repo/branch/message containing "network" is not
+  // evidence of a connectivity failure.
+  const networkCodes = new Set([
+    'etimedout',
+    'econnreset',
+    'econnrefused',
+    'enotfound',
+    'eai_again',
+    'enetunreach',
+    'enetdown'
+  ])
+  if (
+    networkCodes.has(code) ||
+    lower.includes('etimedout') ||
+    lower.includes('econnreset') ||
+    lower.includes('econnrefused') ||
+    lower.includes('enotfound') ||
+    lower.includes('eai_again') ||
+    lower.includes('timed out') ||
+    lower.includes('timeout') ||
+    lower.includes('could not resolve host') ||
+    lower.includes('no such host') ||
+    lower.includes('network is unreachable') ||
+    lower.includes('network is down') ||
+    lower.includes('network error') ||
+    lower.includes('connection refused') ||
+    lower.includes('connection reset')
+  ) {
+    return 'network'
+  }
+  if (isHttp403 || lower.includes('resource not accessible')) {
+    return 'permission'
+  }
+  // gh CLI launch failure: prefer the structured spawn error code over a broad
+  // substring so a repo path merely containing "gh" is not misclassified.
+  if (
+    code === 'enoent' ||
+    lower.includes('spawn gh enoent') ||
+    lower.includes('gh: command not found') ||
+    lower.includes("'gh' is not recognized")
+  ) {
+    return 'gh_unavailable'
+  }
+  // Auth last: match full auth phrases and a 401, never a bare "auth" substring
+  // that also fires on "author"/"authored". "unauthorized"/"authorization" are
+  // long enough not to collide with "author".
+  if (
+    lower.includes('http 401') ||
+    lower.includes('unauthorized') ||
+    lower.includes('authorization') ||
+    lower.includes('authentication') ||
+    lower.includes('bad credentials') ||
+    lower.includes('gh auth') ||
+    /\b(login|credentials?)\b/i.test(lower)
+  ) {
+    return 'auth'
+  }
+  return 'unknown'
+}
+
+/** Stable, non-destructive fallback message for a classified refresh error. */
+export function safePRRefreshErrorMessage(errorType: PRRefreshErrorType): string {
+  switch (errorType) {
+    case 'rate_limited':
+      return 'GitHub rate limit is low. Try again after the limit resets.'
+    case 'auth':
+      return 'GitHub authentication is unavailable. Check your gh login.'
+    case 'network':
+      return 'GitHub is unreachable right now. Check your network and try again.'
+    case 'server_error':
+      return "GitHub's API is temporarily unavailable (server error). This is a GitHub-side issue."
+    case 'permission':
+      return 'GitHub did not allow access to this pull request.'
+    case 'repo_unavailable':
+      return 'The GitHub repository is unavailable or cannot be resolved.'
+    case 'gh_unavailable':
+      return 'GitHub CLI is unavailable.'
+    case 'unknown':
+      return 'GitHub pull request refresh failed.'
+  }
+}
diff --git a/src/main/gitlab/client-mr.test.ts b/src/main/gitlab/client-mr.test.ts
index a090ec7963b..aac5193c1e3 100644
--- a/src/main/gitlab/client-mr.test.ts
+++ b/src/main/gitlab/client-mr.test.ts
@@ -41,6 +41,7 @@ import {
   addMRComment,
   getMergeRequest,
   getMergeRequestForBranch,
+  getMergeRequestForBranchOrThrow,
   getJobTrace,
   addMRInlineComment,
   closeMR,
@@ -74,6 +75,19 @@ describe('gitlab client — MR operations', () => {
     })
   })
 
+  it('getMergeRequestForBranchOrThrow surfaces a glab failure instead of null (finding 4)', async () => {
+    getProjectRefMock.mockResolvedValue({ host: 'gitlab.com', path: 'g/p' })
+    glabExecFileAsyncMock.mockRejectedValue(new Error('glab: connection refused'))
+
+    // The swallowing variant collapses a real failure into a false "no MR".
+    await expect(getMergeRequestForBranch('/repo', 'feature/x')).resolves.toBeNull()
+    // The throwing variant makes the failure visible so eligibility records
+    // `unavailable` rather than a false "No merge request found".
+    await expect(getMergeRequestForBranchOrThrow('/repo', 'feature/x')).rejects.toThrow(
+      /connection refused/
+    )
+  })
+
   it('routes local WSL MR review-management and job actions through project resolution and glab options', async () => {
     const localGitOptions = { wslDistro: 'Ubuntu' }
     glabExecFileAsyncMock
diff --git a/src/main/gitlab/client.ts b/src/main/gitlab/client.ts
index b6b32dfb8c3..370553db9e1 100644
--- a/src/main/gitlab/client.ts
+++ b/src/main/gitlab/client.ts
@@ -313,7 +313,11 @@ export async function getMergeRequestForBranch(
   branch: string,
   linkedMRIid?: number | null,
   connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
+  options: HostedReviewExecutionOptions = {},
+  // Why: the existing-review lookup behind Create must distinguish a real glab
+  // transport/auth failure from an accepted "no MR". When true, a failed lookup
+  // throws instead of collapsing to null so callers never report false not_found.
+  throwOnFailure = false
 ): Promise<MRInfo | null> {
   const branchName = branch.replace(/^refs\/heads\//, '')
   if (!branchName && linkedMRIid == null) {
@@ -369,13 +373,31 @@ export async function getMergeRequestForBranch(
     }
     const pipelineStatus = derivePipelineStatus(raw.head_pipeline ?? raw.pipeline ?? null)
     return mapMRInfo(raw, pipelineStatus)
-  } catch {
+  } catch (error) {
+    if (throwOnFailure) {
+      throw error
+    }
     return null
   } finally {
     release()
   }
 }
 
+/**
+ * Existing-review lookup that surfaces glab transport/auth failures instead of
+ * collapsing them to null, so a failed lookup becomes
+ * `reviewLookupOutcome: 'unavailable'` rather than a false "No merge request found".
+ */
+export function getMergeRequestForBranchOrThrow(
+  repoPath: string,
+  branch: string,
+  linkedMRIid?: number | null,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<MRInfo | null> {
+  return getMergeRequestForBranch(repoPath, branch, linkedMRIid, connectionId, options, true)
+}
+
 function mrListStateFlags(state: MRListState): string[] {
   switch (state) {
     case 'opened':
diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index 9e194212d35..a3f6e0b2cc0 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -193,6 +193,7 @@ const {
   getHostedReviewCreationEligibilityMock,
   getHostedReviewForBranchMock,
   getPRForBranchMock,
+  getPRForBranchOutcomeMock,
   getRepoSlugMock,
   getRepoUpstreamMock,
   getGitHubWorkItemMock,
@@ -298,6 +299,7 @@ const {
     getHostedReviewCreationEligibilityMock: vi.fn(),
     getHostedReviewForBranchMock: vi.fn(),
     getPRForBranchMock: vi.fn().mockResolvedValue(null),
+    getPRForBranchOutcomeMock: vi.fn().mockResolvedValue({ kind: 'no-pr', fetchedAt: 0 }),
     getRepoSlugMock: vi.fn().mockResolvedValue(null),
     getRepoUpstreamMock: vi.fn().mockResolvedValue(null),
     getGitHubWorkItemMock: vi.fn(),
@@ -463,6 +465,7 @@ vi.mock('../github/client', async (importOriginal) => {
   return {
     ...actual,
     getPRForBranch: getPRForBranchMock,
+    getPRForBranchOutcome: getPRForBranchOutcomeMock,
     getRepoSlug: getRepoSlugMock,
     getRepoUpstream: getRepoUpstreamMock,
     getWorkItem: getGitHubWorkItemMock,
@@ -671,6 +674,8 @@ function resetRuntimeTestMocks(): void {
   getHostedReviewForBranchMock.mockResolvedValue(null)
   getPRForBranchMock.mockReset()
   getPRForBranchMock.mockResolvedValue(null)
+  getPRForBranchOutcomeMock.mockReset()
+  getPRForBranchOutcomeMock.mockResolvedValue({ kind: 'no-pr', fetchedAt: 0 })
   getRepoSlugMock.mockReset()
   getRepoSlugMock.mockResolvedValue(null)
   getRepoUpstreamMock.mockReset()
@@ -5572,9 +5577,16 @@ describe('OrcaRuntimeService', () => {
       prRepo
     })
 
-    expect(getPRForBranchMock).toHaveBeenCalledWith(TEST_REPO_PATH, 'feature/wsl', 42, null, null, {
-      localGitExecOptions: localGitOptions
-    })
+    expect(getPRForBranchOutcomeMock).toHaveBeenCalledWith(
+      TEST_REPO_PATH,
+      'feature/wsl',
+      42,
+      null,
+      null,
+      {
+        localGitExecOptions: localGitOptions
+      }
+    )
     expect(getGitHubWorkItemMock).toHaveBeenCalledWith(
       TEST_REPO_PATH,
       42,
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 418809d2f57..c255a65863c 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -378,6 +378,7 @@ import type { BrowserBackend } from '../browser/browser-backend'
 import { BrowserError } from '../browser/cdp-bridge'
 import {
   getPRForBranch,
+  getPRForBranchOutcome,
   getRepoSlug,
   getRepoUpstream,
   getWorkItem,
@@ -456,7 +457,8 @@ import type {
   GitLabProjectRef,
   GitLabWorkItem,
   ListWorkItemsResult,
-  MRListState
+  MRListState,
+  PRRefreshOutcome
 } from '../../shared/types'
 import { inspectSetupScriptImportCandidates } from '../../shared/setup-script-imports'
 import type {
@@ -13977,7 +13979,7 @@ export class OrcaRuntimeService {
     fallbackPRNumber?: number | null,
     acceptMergedFallbackPR?: boolean,
     currentHeadOid?: string | null
-  ): Promise<Awaited<ReturnType<typeof getPRForBranch>>> {
+  ): Promise<PRRefreshOutcome> {
     const repo = await this.resolveRepoSelector(repoSelector)
     const options: GitHubPRBranchLookupOptions = this.getHostedReviewExecutionOptions(repo) ?? {}
     const lookupOptions = { ...options }
@@ -13989,7 +13991,11 @@ export class OrcaRuntimeService {
     }
     const lookupOptionArgs: [] | [GitHubPRBranchLookupOptions] =
       Object.keys(lookupOptions).length > 0 ? [lookupOptions] : []
-    return getPRForBranch(
+    // Why: return the full classified outcome (not PRInfo|null) so a runtime gh
+    // auth/network failure crosses the RPC as `upstream-error` instead of
+    // collapsing to `null`, which the renderer would otherwise cache as a false
+    // accepted "no PR found" (design success criterion 1).
+    return getPRForBranchOutcome(
       repo.path,
       branch,
       linkedPRNumber ?? null,
diff --git a/src/main/runtime/rpc/methods/hosted-review.test.ts b/src/main/runtime/rpc/methods/hosted-review.test.ts
index 5c3c683b617..7c2e3cb7bb9 100644
--- a/src/main/runtime/rpc/methods/hosted-review.test.ts
+++ b/src/main/runtime/rpc/methods/hosted-review.test.ts
@@ -58,6 +58,7 @@ describe('hosted review RPC methods', () => {
         canCreate: true,
         blockedReason: null,
         nextAction: null,
+        reviewLookupOutcome: 'not_found',
         defaultBaseRef: 'main',
         head: 'feature/create-pr',
         title: 'Create PR'
diff --git a/src/main/source-control/forge-provider.ts b/src/main/source-control/forge-provider.ts
index a7d22ad48ae..1a6ea4a4368 100644
--- a/src/main/source-control/forge-provider.ts
+++ b/src/main/source-control/forge-provider.ts
@@ -6,24 +6,24 @@ import type {
 } from '../../shared/hosted-review'
 import {
   getAzureDevOpsPullRequest,
-  getAzureDevOpsPullRequestForBranch,
+  getAzureDevOpsPullRequestForBranchOrThrow,
   getAzureDevOpsRepoSlug
 } from '../azure-devops/client'
 import { createAzureDevOpsPullRequest } from '../azure-devops/pull-request-creation'
 import {
   getBitbucketPullRequest,
-  getBitbucketPullRequestForBranch,
+  getBitbucketPullRequestForBranchOrThrow,
   getBitbucketRepoSlug
 } from '../bitbucket/client'
 import {
   getGiteaPullRequest,
-  getGiteaPullRequestForBranch,
+  getGiteaPullRequestForBranchOrThrow,
   getGiteaRepoSlug
 } from '../gitea/client'
 import { createGiteaPullRequest } from '../gitea/pull-request-creation'
 import { createGitHubPullRequest, getPRForBranchOutcome, getRepoSlug } from '../github/client'
 import { getEnterpriseGitHubRepoSlug } from '../github/github-enterprise-repository'
-import { getMergeRequest, getMergeRequestForBranch, getProjectSlug } from '../gitlab/client'
+import { getMergeRequest, getMergeRequestForBranchOrThrow, getProjectSlug } from '../gitlab/client'
 import { createGitLabMergeRequest } from '../gitlab/merge-request-creation'
 import {
   mapAzureDevOpsReview,
@@ -86,7 +86,10 @@ const gitLabForgeProvider = {
   resolveRepository: (context) =>
     getProjectSlug(context.repoPath, context.connectionId, ...hostedReviewExecutionArgs(context)),
   async getReviewForBranch(input) {
-    const mr = await getMergeRequestForBranch(
+    // Why: throw (not null) on a real lookup failure so eligibility records
+    // `unavailable`, never a false "No merge request found" — same contract the
+    // GitHub adapter uses so hosted-review callers preserve last-known state.
+    const mr = await getMergeRequestForBranchOrThrow(
       input.repoPath,
       input.branch,
       input.linkedReviewNumber ?? null,
@@ -188,7 +191,9 @@ const bitbucketForgeProvider = {
       ...hostedReviewExecutionArgs(context)
     ),
   async getReviewForBranch(input) {
-    const pr = await getBitbucketPullRequestForBranch(
+    // Why: surface a real lookup failure so eligibility records `unavailable`
+    // instead of a false "No pull request found".
+    const pr = await getBitbucketPullRequestForBranchOrThrow(
       input.repoPath,
       input.branch,
       input.linkedReviewNumber ?? null,
@@ -218,7 +223,9 @@ const azureDevOpsForgeProvider = {
       ...hostedReviewExecutionArgs(context)
     ),
   async getReviewForBranch(input) {
-    const pr = await getAzureDevOpsPullRequestForBranch(
+    // Why: surface a real lookup failure so eligibility records `unavailable`
+    // instead of a false "No pull request found".
+    const pr = await getAzureDevOpsPullRequestForBranchOrThrow(
       input.repoPath,
       input.branch,
       input.linkedReviewNumber ?? null,
@@ -245,7 +252,9 @@ const giteaForgeProvider = {
   resolveRepository: (context) =>
     getGiteaRepoSlug(context.repoPath, context.connectionId, ...hostedReviewExecutionArgs(context)),
   async getReviewForBranch(input) {
-    const pr = await getGiteaPullRequestForBranch(
+    // Why: surface a real lookup failure so eligibility records `unavailable`
+    // instead of a false "No pull request found".
+    const pr = await getGiteaPullRequestForBranchOrThrow(
       input.repoPath,
       input.branch,
       input.linkedReviewNumber ?? null,
diff --git a/src/main/source-control/hosted-review-creation-eligibility.test.ts b/src/main/source-control/hosted-review-creation-eligibility.test.ts
index 010d950d50f..484ede6cbff 100644
--- a/src/main/source-control/hosted-review-creation-eligibility.test.ts
+++ b/src/main/source-control/hosted-review-creation-eligibility.test.ts
@@ -115,7 +115,7 @@ vi.mock('./hosted-review', () => ({
   getHostedReviewForBranch: getHostedReviewForBranchMock
 }))
 
-import { getHostedReviewCreationEligibility } from './hosted-review-creation'
+import { createHostedReview, getHostedReviewCreationEligibility } from './hosted-review-creation'
 
 function resetMocks(): void {
   for (const mock of [
@@ -232,6 +232,96 @@ describe('getHostedReviewCreationEligibility', () => {
     })
   })
 
+  it('reports reviewLookupOutcome: found when an existing review is returned', async () => {
+    getHostedReviewForBranchMock.mockResolvedValue({ number: 7, url: 'https://x/pull/7' })
+    await expect(
+      getHostedReviewCreationEligibility({
+        repoPath: '/repo',
+        branch: 'feature/x',
+        hasUncommittedChanges: false,
+        hasUpstream: true,
+        ahead: 0,
+        behind: 0
+      })
+    ).resolves.toMatchObject({ blockedReason: 'existing_review', reviewLookupOutcome: 'found' })
+  })
+
+  it('reports reviewLookupOutcome: not_found when the lookup accepts no review', async () => {
+    getHostedReviewForBranchMock.mockResolvedValue(null)
+    await expect(
+      getHostedReviewCreationEligibility({
+        repoPath: '/repo',
+        branch: 'feature/x',
+        hasUncommittedChanges: false,
+        hasUpstream: true,
+        ahead: 0,
+        behind: 0
+      })
+    ).resolves.toMatchObject({ reviewLookupOutcome: 'not_found' })
+  })
+
+  it('reports reviewLookupOutcome: unavailable when a swallowed lookup failure yields a local blocker', async () => {
+    getHostedReviewForBranchMock.mockRejectedValue(new Error('ssh: connection refused'))
+    await expect(
+      getHostedReviewCreationEligibility({
+        repoPath: '/repo',
+        branch: 'feature/x',
+        hasUncommittedChanges: false,
+        hasUpstream: false,
+        ahead: 0,
+        behind: 0
+      })
+    ).resolves.toMatchObject({ blockedReason: 'no_upstream', reviewLookupOutcome: 'unavailable' })
+  })
+
+  it('never marks a clean, in-sync branch creatable when the review lookup fails', async () => {
+    // A failed existing-review lookup leaves review existence unproven, so the
+    // happy path must not claim canCreate — that would offer Create against a
+    // branch that might already have a review (finding 4).
+    getHostedReviewForBranchMock.mockRejectedValue(new Error('gh: could not connect to github.com'))
+    await expect(
+      getHostedReviewCreationEligibility({
+        repoPath: '/repo',
+        branch: 'feature/x',
+        base: 'origin/main',
+        hasUncommittedChanges: false,
+        hasUpstream: true,
+        ahead: 0,
+        behind: 0
+      })
+    ).resolves.toMatchObject({
+      canCreate: false,
+      blockedReason: null,
+      reviewLookupOutcome: 'unavailable'
+    })
+  })
+
+  it('refuses to create when the existing-review lookup is unavailable (finding 5)', async () => {
+    getHostedReviewForBranchMock.mockRejectedValue(new Error('glab: connection refused'))
+    getUpstreamStatusMock.mockResolvedValue({ hasUpstream: true, ahead: 0, behind: 0 })
+    gitExecFileAsyncMock.mockImplementation(async (args: string[]) => {
+      if (args[0] === 'rev-parse') {
+        return { stdout: 'feature/x\n', stderr: '' }
+      }
+      if (args[0] === 'status') {
+        return { stdout: '', stderr: '' }
+      }
+      // symbolic-ref / for-each-ref resolve the base on the remote.
+      return { stdout: 'refs/remotes/origin/main\n', stderr: '' }
+    })
+
+    const result = await createHostedReview('/repo', {
+      provider: 'github',
+      base: 'main',
+      head: 'feature/x',
+      title: 'Add feature'
+    })
+
+    expect(result).toMatchObject({ ok: false, code: 'validation' })
+    // The provider create API must never run on an inconclusive lookup.
+    expect(createGitHubPullRequestMock).not.toHaveBeenCalled()
+  })
+
   // Stacked-worktree base resolution (Change 1/2). `stackedArgs` defaults to a
   // bare local-only parent; `mockRefs` controls the remote-tracking snapshot.
   const stackedArgs = (
diff --git a/src/main/source-control/hosted-review-creation.ts b/src/main/source-control/hosted-review-creation.ts
index 1e19f1d4fa8..a0271d0ea3d 100644
--- a/src/main/source-control/hosted-review-creation.ts
+++ b/src/main/source-control/hosted-review-creation.ts
@@ -6,6 +6,7 @@ import type {
   HostedReviewCreationBlockedReason,
   HostedReviewCreationEligibility,
   HostedReviewCreationEligibilityArgs,
+  HostedReviewLookupOutcome,
   HostedReviewProvider
 } from '../../shared/hosted-review'
 import {
@@ -435,6 +436,18 @@ async function validateCurrentBranchCanCreateReview(
       enforceBaseOnRemote: true,
       ...options
     })
+    // Why: never call the provider create API when the existing-review lookup
+    // could not prove the branch has no review. An `unavailable` outcome means a
+    // real MR/PR might exist that a failed lookup could not see; refuse
+    // inconclusively (design invariant 8 / submission boundary) so we never
+    // create a duplicate. The composed title/body are preserved by the caller.
+    if (eligibility.reviewLookupOutcome === 'unavailable') {
+      return {
+        ok: false,
+        code: 'validation',
+        error: `Create ${copy.shortLabel} failed: Orca could not confirm whether this branch already has a ${copy.reviewLabel}. Retry once the ${copy.providerName} lookup succeeds.`
+      }
+    }
     // Why: renderer eligibility can be stale by submit time; the main process
     // is the last chance to avoid creating a PR from an out-of-date remote head.
     return blockedEligibilityToCreateResult(eligibility, submittedBase)
@@ -475,6 +488,10 @@ export async function getHostedReviewCreationEligibility(
   }
   const baseBranch = defaultBaseRef ? normalizeHostedReviewBaseRef(defaultBaseRef) : null
   let review: Awaited<ReturnType<typeof getHostedReviewForBranch>> = null
+  // Why: a swallowed lookup failure must not masquerade as authoritative
+  // no-review evidence. Track it so the renderer can distinguish an accepted
+  // no-PR result (`not_found`) from a local-blocker fallback (`unavailable`).
+  let lookupFailed = false
   try {
     review = await getHostedReviewForBranch({
       repoPath: args.repoPath,
@@ -489,23 +506,25 @@ export async function getHostedReviewCreationEligibility(
       ...hostedReviewExecutionContext(args)
     })
   } catch (error) {
-    const canReturnLocalBlocker =
-      branch &&
-      branch !== 'HEAD' &&
-      supportsHostedReviewCreation(provider) &&
-      (!baseBranch || branch.toLowerCase() !== baseBranch.toLowerCase()) &&
-      (args.hasUncommittedChanges || args.hasUpstream !== true || (args.behind ?? 0) > 0)
-    if (!canReturnLocalBlocker) {
-      throw error
-    }
-    // Why: local blockers still let the UI offer Create PR preparation; a
-    // flaky existing-review lookup should not hide the affordance entirely.
-    console.warn('Hosted review lookup failed while resolving local review blocker:', error)
+    // Why: a failed existing-review lookup can never authorize Create — it might
+    // be hiding a real PR. Record `unavailable` and fall through so any local
+    // blocker (dirty/no-upstream/behind) still supplies primary guidance, but the
+    // clean-branch happy path below is forced to `canCreate: false`. Never rethrow
+    // here: a thrown lookup must not collapse into a false `not_found` and must
+    // stay a structured, honest empty state for the renderer.
+    lookupFailed = true
+    console.warn('Hosted review lookup failed; treating existing-review as unavailable:', error)
   }
 
+  const reviewLookupOutcome: HostedReviewLookupOutcome = review
+    ? 'found'
+    : lookupFailed
+      ? 'unavailable'
+      : 'not_found'
   const baseResult = {
     provider,
     review: review ? { number: review.number, url: review.url } : null,
+    reviewLookupOutcome,
     defaultBaseRef,
     head: branch || null
   }
@@ -575,7 +594,15 @@ export async function getHostedReviewCreationEligibility(
       nextAction: null
     }
   }
-  return { ...baseResult, canCreate: Boolean(baseBranch), blockedReason: null, nextAction: null }
+  // Why: a lookup that failed leaves review existence unproven, so the clean,
+  // in-sync happy path must not claim `canCreate` — that would open Create
+  // against a branch that may already have a review. Stays `unavailable`.
+  return {
+    ...baseResult,
+    canCreate: lookupFailed ? false : Boolean(baseBranch),
+    blockedReason: null,
+    nextAction: null
+  }
 }
 
 export async function createHostedReview(
diff --git a/src/main/source-control/hosted-review.test.ts b/src/main/source-control/hosted-review.test.ts
index 51c5ee8d927..102ebfebdbb 100644
--- a/src/main/source-control/hosted-review.test.ts
+++ b/src/main/source-control/hosted-review.test.ts
@@ -27,6 +27,9 @@ const {
 vi.mock('../gitlab/client', () => ({
   getProjectSlug: getProjectSlugMock,
   getMergeRequestForBranch: getMergeRequestForBranchMock,
+  // Why: forge-provider resolves branch reviews via the OrThrow variant so
+  // lookup failures surface as unavailable instead of "no PR found".
+  getMergeRequestForBranchOrThrow: getMergeRequestForBranchMock,
   getMergeRequest: vi.fn()
 }))
 
@@ -39,18 +42,27 @@ vi.mock('../github/client', () => ({
 vi.mock('../bitbucket/client', () => ({
   getBitbucketRepoSlug: getBitbucketRepoSlugMock,
   getBitbucketPullRequestForBranch: getBitbucketPullRequestForBranchMock,
+  // Why: forge-provider resolves branch reviews via the OrThrow variant so
+  // lookup failures surface as unavailable instead of "no PR found".
+  getBitbucketPullRequestForBranchOrThrow: getBitbucketPullRequestForBranchMock,
   getBitbucketPullRequest: vi.fn()
 }))
 
 vi.mock('../azure-devops/client', () => ({
   getAzureDevOpsRepoSlug: getAzureDevOpsRepoSlugMock,
   getAzureDevOpsPullRequestForBranch: getAzureDevOpsPullRequestForBranchMock,
+  // Why: forge-provider resolves branch reviews via the OrThrow variant so
+  // lookup failures surface as unavailable instead of "no PR found".
+  getAzureDevOpsPullRequestForBranchOrThrow: getAzureDevOpsPullRequestForBranchMock,
   getAzureDevOpsPullRequest: vi.fn()
 }))
 
 vi.mock('../gitea/client', () => ({
   getGiteaRepoSlug: getGiteaRepoSlugMock,
   getGiteaPullRequestForBranch: getGiteaPullRequestForBranchMock,
+  // Why: forge-provider resolves branch reviews via the OrThrow variant so
+  // lookup failures surface as unavailable instead of "no PR found".
+  getGiteaPullRequestForBranchOrThrow: getGiteaPullRequestForBranchMock,
   getGiteaPullRequest: vi.fn()
 }))
 
diff --git a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
index ac08b19fdf9..66ff0f85a35 100644
--- a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
@@ -60,7 +60,8 @@ import type {
   PRInfo,
   PRCheckDetail,
   PRCheckRunDetails,
-  PRComment
+  PRComment,
+  PRRefreshErrorType
 } from '../../../../shared/types'
 import { getConnectionId } from '@/lib/connection-context'
 import {
@@ -82,6 +83,7 @@ import type {
   HostedReviewProvider
 } from '../../../../shared/hosted-review'
 import { resolveHostedReviewCreationProvider } from '../../../../shared/hosted-review-creation-providers'
+import { normalizeGlobalWindowsRuntimeDefault } from '../../../../shared/project-execution-runtime'
 import { normalizeHostedReviewHeadRef } from '../../../../shared/hosted-review-refs'
 import { getHostedReviewCacheKey, refreshHostedReviewCard } from '@/store/slices/hosted-review'
 import { toast } from 'sonner'
@@ -99,11 +101,17 @@ import {
 } from './pr-comment-thread-resolution'
 import { installWindowVisibilityTimeoutPoller } from '@/lib/window-visibility-timeout-poller'
 import {
-  getChecksPanelEmptyStateCopy,
+  getChecksPanelReviewState,
   shouldShowChecksPanelPublishBranchAction
 } from './checks-panel-empty-state'
 import { getChecksPanelRefreshErrorBannerLine } from './github-refresh-error-copy'
-import { hasAmbiguousGitHubHostedReviewForChecksPanel } from './checks-panel-ambiguous-github-review'
+import { resolveChecksPanelReviewLookup } from './checks-panel-review-lookup-authority'
+import {
+  computeChecksPanelConfirmedReadiness,
+  isChecksPanelHardErrorCleared,
+  isChecksPanelHardRefreshErrorType,
+  type ChecksPanelConfirmedReadinessInput
+} from './checks-panel-review-creation'
 import { recordChecksPanelPRRefreshBreadcrumb } from './checks-panel-pr-refresh-breadcrumb'
 import {
   cancelRuntimeGeneratePullRequestFields,
@@ -181,12 +189,47 @@ const GIT_STATUS_FAILURE_RETRY_MS = 3000
 
 type HostedReviewCreationSnapshot = {
   requestKey: string
+  /** Panel context key (repo/worktree/branch/host) at request time. */
+  contextKey: string
   repoId: string
   worktreeId: string | null
   branch: string
+  /** Wall-clock time the eligibility request started (hard-error clear ordering). */
+  requestStartedAt: number
+  /** Wall-clock time the eligibility result settled (confirmed freshness window). */
+  completedAt: number
+  /** Git snapshot fingerprint used for this eligibility (confirmed freshness). */
+  gitFingerprint: string
   data: HostedReviewCreationEligibility
 }
 
+// Confirmed readiness must drop when HEAD, dirty, upstream, base, or the
+// execution host move under the eligibility that produced it. Fingerprint those
+// fields so a stale snapshot cannot keep an enabled Create open.
+function buildChecksPanelEligibilityGitFingerprint(input: {
+  headOid: string | null
+  hasUncommittedChanges: boolean | undefined
+  hasUpstream: boolean | undefined
+  ahead: number | undefined
+  behind: number | undefined
+  base: string | null
+  runtimeEnvironmentId: string | null
+  repoConnectionId: string | null
+  localExecutionScope: string | null
+}): string {
+  return JSON.stringify({
+    headOid: input.headOid ?? null,
+    hasUncommittedChanges: input.hasUncommittedChanges ?? null,
+    hasUpstream: input.hasUpstream ?? null,
+    ahead: input.ahead ?? null,
+    behind: input.behind ?? null,
+    base: input.base ?? null,
+    runtimeEnvironmentId: input.runtimeEnvironmentId ?? null,
+    repoConnectionId: input.repoConnectionId ?? null,
+    localExecutionScope: input.localExecutionScope ?? null
+  })
+}
+
 type ChecksAgentComposerState = {
   actionId: SourceControlLaunchActionId
   title: string
@@ -416,6 +459,7 @@ export default function ChecksPanel(): React.JSX.Element {
   )
   const isRemoteOperationActive = useAppStore((s) => s.isRemoteOperationActive)
   const pushBranch = useAppStore((s) => s.pushBranch)
+  const syncBranch = useAppStore((s) => s.syncBranch)
   const fetchUpstreamStatus = useAppStore((s) => s.fetchUpstreamStatus)
   const setRightSidebarOpen = useAppStore((s) => s.setRightSidebarOpen)
   const setRightSidebarTab = useAppStore((s) => s.setRightSidebarTab)
@@ -452,6 +496,7 @@ export default function ChecksPanel(): React.JSX.Element {
   const [isCreatingPr, setIsCreatingPr] = useState(false)
   const [createPrError, setCreatePrError] = useState<string | null>(null)
   const [isPublishingBranch, setIsPublishingBranch] = useState(false)
+  const [isSyncingBranch, setIsSyncingBranch] = useState(false)
   const isResolvingConflictsWithAI = false
   const [isFixingChecksWithAI, setIsFixingChecksWithAI] = useState(false)
   const [agentComposerState, setAgentComposerState] = useState<ChecksAgentComposerState | null>(
@@ -459,10 +504,28 @@ export default function ChecksPanel(): React.JSX.Element {
   )
   const [hostedReviewCreationSnapshot, setHostedReviewCreationSnapshot] =
     useState<HostedReviewCreationSnapshot | null>(null)
+  // Sticky observation of the most recent hard refresh error for the exact
+  // context. Persisted across queued/in-flight auto-retries so Create cannot
+  // flap back until a qualifying eligibility request clears it.
+  const [hardRefreshError, setHardRefreshError] = useState<{
+    observedAt: number
+    errorType: PRRefreshErrorType
+    contextKey: string
+  } | null>(null)
   const [gitStatusSnapshot, setGitStatusSnapshot] = useState<ChecksPanelGitStatusSnapshot | null>(
     null
   )
+  // Context key whose git-status probe failed with no usable snapshot, so the
+  // empty state can distinguish "checking branch status" from "could not check".
+  const [gitStatusProbeErrorContextKey, setGitStatusProbeErrorContextKey] = useState<string | null>(
+    null
+  )
   const [gitStatusRefreshNonce, setGitStatusRefreshNonce] = useState(0)
+  // Bumped by a manual Retry/Refresh so eligibility re-runs even when the Git
+  // snapshot is unchanged. A hard error can only be cleared by an eligibility
+  // request that started strictly after the error, so an auth fix followed by
+  // Retry (which does not change Git state) must still trigger a fresh request.
+  const [eligibilityRefreshNonce, setEligibilityRefreshNonce] = useState(0)
   const [editingTitle, setEditingTitle] = useState(false)
   const [titleDraft, setTitleDraft] = useState('')
   const [titleSaving, setTitleSaving] = useState(false)
@@ -543,6 +606,16 @@ export default function ChecksPanel(): React.JSX.Element {
     [runtimeEnvironmentId, settings]
   )
   const repoConnectionId = repo?.connectionId?.trim() || null
+  // Local execution host variant (`wsl:{distro}` vs `host`). WSL is a local-host
+  // variant, not a runtime/SSH host, so it only applies when execution is local;
+  // remote contexts are already scoped by runtimeEnvironmentId / connectionId.
+  const localExecutionScope = useMemo<string | null>(() => {
+    if (runtimeEnvironmentId != null || repoConnectionId != null) {
+      return null
+    }
+    const localRuntime = normalizeGlobalWindowsRuntimeDefault(settings?.localWindowsRuntimeDefault)
+    return localRuntime.kind === 'wsl' ? `wsl:${localRuntime.distro ?? ''}` : 'host'
+  }, [runtimeEnvironmentId, repoConnectionId, settings?.localWindowsRuntimeDefault])
   const sshConnectionStatus = useAppStore((s) =>
     repoConnectionId ? s.sshConnectionStates.get(repoConnectionId)?.status : undefined
   )
@@ -558,6 +631,7 @@ export default function ChecksPanel(): React.JSX.Element {
     linkedGiteaPR: activeWorktree?.linkedGiteaPR ?? null,
     runtimeEnvironmentId,
     repoConnectionId,
+    localExecutionScope,
     pushTarget: activeWorktreePushTarget
   })
   const panelContextKeyRef = useRef(panelContextKey)
@@ -607,7 +681,9 @@ export default function ChecksPanel(): React.JSX.Element {
     setIsPublishingBranch(false)
     setAgentComposerState(null)
     setHostedReviewCreationSnapshot(null)
+    setHardRefreshError(null)
     setGitStatusSnapshot(null)
+    setGitStatusProbeErrorContextKey(null)
     setGitStatusRefreshNonce((value) => value + 1)
     pollIntervalRef.current = 30_000
     prevChecksRef.current = ''
@@ -659,11 +735,13 @@ export default function ChecksPanel(): React.JSX.Element {
   const hostedReview = useAppStore((s) =>
     hostedReviewCacheKey ? (s.hostedReviewCache[hostedReviewCacheKey]?.data ?? null) : null
   )
-  const hasAmbiguousGitHubHostedReview = hasAmbiguousGitHubHostedReviewForChecksPanel({
-    hostedReview,
-    prCacheEntry,
-    prCacheKey
-  })
+  const linkedReviewNumber =
+    activeWorktree?.linkedPR ??
+    activeWorktree?.linkedGitLabMR ??
+    activeWorktree?.linkedBitbucketPR ??
+    activeWorktree?.linkedAzureDevOpsPR ??
+    activeWorktree?.linkedGiteaPR ??
+    null
   // Fetch PR data when the active worktree/branch changes.
   // Why: branch lookup is lossy for fork/deleted-head PRs; reuse a known PR
   // number from metadata or the visible cache whenever we have one.
@@ -748,6 +826,25 @@ export default function ChecksPanel(): React.JSX.Element {
     panelVisibleSinceRef.current = Date.now()
   }, [isPanelVisible, panelContextKey])
 
+  // Record the latest hard refresh error for the exact context. Kept sticky
+  // (only cleared via computeChecksPanelConfirmedReadiness) so a background
+  // queued/in-flight auto-retry — which replaces `status: 'error'` — cannot
+  // silently re-enable Create while the lookup is still impossible here.
+  useEffect(() => {
+    const errorType = prRefreshState?.status === 'error' ? prRefreshState.errorType : undefined
+    if (!isChecksPanelHardRefreshErrorType(errorType)) {
+      return
+    }
+    const observedAt = prRefreshState?.updatedAt ?? Date.now()
+    const contextKey = panelContextKeyRef.current
+    setHardRefreshError((prev) => {
+      if (prev && prev.contextKey === contextKey && prev.observedAt >= observedAt) {
+        return prev
+      }
+      return { observedAt, errorType: errorType as PRRefreshErrorType, contextKey }
+    })
+  }, [prRefreshState])
+
   // Why: select only timestamps (not whole cache records) so the entry-refresh
   // effect doesn't re-run on every cache mutation. See
   // docs/refresh-on-checks-tab.md.
@@ -824,6 +921,27 @@ export default function ChecksPanel(): React.JSX.Element {
   const gitStatusReadyForPanelContext = gitStatusInputs.hasUncommittedChanges !== undefined
   const hasUncommittedChanges = gitStatusInputs.hasUncommittedChanges
   const remoteStatus = gitStatusInputs.remoteStatus
+  const eligibilityHeadOid =
+    gitStatusSnapshot?.contextKey === panelContextKey
+      ? (gitStatusSnapshot.gitIdentity?.head ?? null)
+      : null
+  // Read at eligibility request time via a ref so a HEAD move drops confirmed
+  // (fingerprint mismatch) without re-triggering the eligibility network call.
+  const eligibilityHeadOidRef = useRef(eligibilityHeadOid)
+  eligibilityHeadOidRef.current = eligibilityHeadOid
+  const eligibilityGitFingerprint = gitStatusReadyForPanelContext
+    ? buildChecksPanelEligibilityGitFingerprint({
+        headOid: eligibilityHeadOid,
+        hasUncommittedChanges,
+        hasUpstream: remoteStatus?.hasUpstream,
+        ahead: remoteStatus?.ahead,
+        behind: remoteStatus?.behind,
+        base: repo?.worktreeBaseRef ?? null,
+        runtimeEnvironmentId,
+        repoConnectionId,
+        localExecutionScope
+      })
+    : null
   // Why: Create PR eligibility waits for the stricter panel snapshot, but the
   // Publish affordance can use the active worktree poller when SSH snapshot
   // refresh is delayed; publishing is still blocked for dirty fallback status.
@@ -843,7 +961,70 @@ export default function ChecksPanel(): React.JSX.Element {
   const hostedReviewCreateProvider = resolveHostedReviewCreationProvider(
     hostedReviewCreation?.provider
   )
+  // Only GitHub contexts run the gh-based PR refresh coordinator. Bitbucket /
+  // Azure DevOps / Gitea / GitLab must never be driven by (or show copy from) a
+  // GitHub `gh` failure — that would hide a valid composer and mislabel the CLI.
+  // Prefer the resolved eligibility provider (authoritative); before it resolves,
+  // treat a non-GitHub linked review as a definite non-GitHub signal and stay
+  // GitHub-optimistic otherwise so GitHub status is not delayed on initial load.
+  // (`resolveHostedReviewCreationProvider` defaults null → 'github', so the raw
+  // value cannot distinguish "unknown" from "GitHub".)
+  const hasNonGitHubLinkedReview =
+    activeWorktree?.linkedGitLabMR != null ||
+    activeWorktree?.linkedBitbucketPR != null ||
+    activeWorktree?.linkedAzureDevOpsPR != null ||
+    activeWorktree?.linkedGiteaPR != null
+  const isGitHubReviewContext = hostedReviewCreation
+    ? hostedReviewCreation.provider === 'github'
+    : !hasNonGitHubLinkedReview
   const hostedReviewCreateCopy = localizedHostedReviewCopy(hostedReviewCreateProvider)
+  // The PR cache is branch/host scoped but not push-target scoped, so an accepted
+  // no-PR fetched for a previous push target could alias as `not_found` after the
+  // push target (or other exact-context field) changes. When an eligibility
+  // snapshot exists for a *different* context than the current one, the context
+  // has moved and that branch-scoped no-PR is not authoritative for it — demote
+  // it to unknown until eligibility re-resolves. Same-context background churn
+  // (snapshot matches, or no snapshot yet) keeps the sticky no-review intact.
+  const prCachedHasPRForContext =
+    hostedReviewCreationSnapshot && hostedReviewCreationSnapshot.contextKey !== panelContextKey
+      ? null
+      : prCachedHasPR
+  // Four-state review evidence: replaces the old ambiguous-GitHub boolean so the
+  // empty state can never claim "No review found" without accepted evidence.
+  const checksPanelReviewLookupResult = resolveChecksPanelReviewLookup({
+    pr,
+    prCachedHasPR: prCachedHasPRForContext,
+    hostedReview,
+    linkedReviewNumber,
+    eligibilityReviewLookupOutcome: hostedReviewCreation?.reviewLookupOutcome ?? null,
+    eligibilityReview: hostedReviewCreation?.review ?? null
+  })
+  const checksPanelReviewLookup = checksPanelReviewLookupResult.state
+  // Confirmed readiness for the exact context, computed from the last confirmed
+  // eligibility snapshot rather than live `canCreate` (which would be circular
+  // and would flap during transient refresh/eligibility failures). This both
+  // gates the composer and clears the sticky hard-error block below.
+  const hardErrorObservedAt =
+    isGitHubReviewContext && hardRefreshError && hardRefreshError.contextKey === panelContextKey
+      ? hardRefreshError.observedAt
+      : undefined
+  const confirmedReadinessInput: ChecksPanelConfirmedReadinessInput = {
+    contextKeyMatches: hostedReviewCreationSnapshot?.contextKey === panelContextKey,
+    eligibility: hostedReviewCreationSnapshot?.data ?? null,
+    eligibilityCompletedAt: hostedReviewCreationSnapshot?.completedAt,
+    eligibilityRequestStartedAt: hostedReviewCreationSnapshot?.requestStartedAt,
+    reviewLookup: checksPanelReviewLookup,
+    hardErrorObservedAt,
+    gitSnapshotMatches:
+      eligibilityGitFingerprint !== null &&
+      hostedReviewCreationSnapshot?.gitFingerprint === eligibilityGitFingerprint,
+    now: Date.now()
+  }
+  const confirmedReadiness = computeChecksPanelConfirmedReadiness(confirmedReadinessInput)
+  // A hard error stays active across auto-retries until a qualifying eligibility
+  // request clears it, so `status: 'queued' | 'in-flight'` no longer un-hides Create.
+  const checksPanelHasHardRefreshError =
+    hardErrorObservedAt !== undefined && !isChecksPanelHardErrorCleared(confirmedReadinessInput)
   const activePullRequestGenerationKey = getPullRequestGenerationRecordKey({
     worktreeId: activeWorktreeId,
     worktreePath: activeWorktreePath,
@@ -919,12 +1100,12 @@ export default function ChecksPanel(): React.JSX.Element {
     () => (settings ? resolveSourceControlAiEnabled({ settings, repo }) : false),
     [repo, settings]
   )
+  // Confirmed-only composer gate. Driven by confirmed readiness (context match,
+  // fresh eligibility, matching git snapshot, cleared hard error) so an
+  // already-confirmed composer survives transient refresh/eligibility failures
+  // but a refresh failure never *opens* a never-confirmed Create.
   const createComposerOpen =
-    !activeReview &&
-    !isFolder &&
-    Boolean(branch) &&
-    (hostedReviewCreation?.canCreate === true ||
-      hostedReviewCreation?.blockedReason === 'needs_push')
+    !isFolder && !activeReview && Boolean(branch) && confirmedReadiness.confirmed
   const handleGeneratePullRequestFieldsForActive = useCallback(
     async (
       fields: PullRequestGenerationFields,
@@ -1121,6 +1302,9 @@ export default function ChecksPanel(): React.JSX.Element {
     submitting: isCreatingPr,
     prCreationDefaults,
     sourceControlAiActionsVisible,
+    // Preserve the draft when a hard refresh error hides the composer so the
+    // user's title/body/base survive recovery for the same exact context.
+    retainDraftWhenClosed: true,
     generation: {
       generating: activePullRequestGenerationRecord?.status === 'running',
       generateError: activePullRequestGenerationRecord?.error ?? null,
@@ -1232,7 +1416,10 @@ export default function ChecksPanel(): React.JSX.Element {
         linkedGiteaPR,
         staleWhileRevalidate: true
       })
-      if (activeWorktreeId && !isGitLabReviewContext) {
+      // Why: the gh-based PR refresh coordinator is GitHub-only. Running it for
+      // Bitbucket/Azure/Gitea produced a spurious `gh_unavailable` hard error that
+      // hid a valid composer; those providers refresh via fetchHostedReviewForBranch.
+      if (activeWorktreeId && isGitHubReviewContext) {
         const refreshRequest = resolveChecksPanelPRRefreshRequest({
           cachedHasPR: prCachedHasPR,
           cachedFetchedAt: prFetchedAt ?? null,
@@ -1248,7 +1435,7 @@ export default function ChecksPanel(): React.JSX.Element {
     fallbackGitHubPRNumber,
     fetchHostedReviewForBranch,
     isFolder,
-    isGitLabReviewContext,
+    isGitHubReviewContext,
     isPanelVisible,
     activeWorktree?.head,
     linkedAzureDevOpsPR,
@@ -1382,6 +1569,9 @@ export default function ChecksPanel(): React.JSX.Element {
               branch: status.branch ?? (status.head ? null : undefined)
             }
           })
+          // A fresh probe succeeded, so this context is no longer in the failed
+          // "could not check branch status" state.
+          setGitStatusProbeErrorContextKey((key) => (key === requestContextKey ? null : key))
         }
       })
       .catch((error) => {
@@ -1392,6 +1582,13 @@ export default function ChecksPanel(): React.JSX.Element {
           setGitStatusSnapshot((snapshot) =>
             shouldClearChecksPanelGitStatusSnapshot(snapshot, requestContextKey) ? null : snapshot
           )
+          // Mark the probe as failed so the empty state can show "Could not check
+          // branch status" instead of an indefinite "Checking branch status".
+          if (
+            shouldCommitChecksPanelGitStatusSnapshot(panelContextKeyRef.current, requestContextKey)
+          ) {
+            setGitStatusProbeErrorContextKey(requestContextKey)
+          }
           gitStatusSnapshotRetryTimerRef.current = setTimeout(() => {
             gitStatusSnapshotRetryTimerRef.current = null
             if (
@@ -1454,6 +1651,19 @@ export default function ChecksPanel(): React.JSX.Element {
       return
     }
     let stale = false
+    const requestContextKey = panelContextKey
+    const requestStartedAt = Date.now()
+    const requestGitFingerprint = buildChecksPanelEligibilityGitFingerprint({
+      headOid: eligibilityHeadOidRef.current,
+      hasUncommittedChanges,
+      hasUpstream: remoteStatus?.hasUpstream,
+      ahead: remoteStatus?.ahead,
+      behind: remoteStatus?.behind,
+      base: repo.worktreeBaseRef ?? null,
+      runtimeEnvironmentId,
+      repoConnectionId,
+      localExecutionScope
+    })
     void getHostedReviewCreationEligibility({
       repoPath: repo.path,
       repoId: repo.id,
@@ -1475,22 +1685,31 @@ export default function ChecksPanel(): React.JSX.Element {
         if (!stale) {
           setHostedReviewCreationSnapshot({
             requestKey: hostedReviewCreationRequestKey,
+            contextKey: requestContextKey,
             repoId: repo.id,
             worktreeId: activeWorktreeId,
             branch,
+            requestStartedAt,
+            completedAt: Date.now(),
+            gitFingerprint: requestGitFingerprint,
             data: result
           })
         }
       })
       .catch(() => {
-        if (!stale) {
-          setHostedReviewCreationSnapshot(null)
-        }
+        // Why: a transient GitHub outage makes the existing-review lookup inside
+        // eligibility rethrow. Do NOT tear down the last confirmed snapshot — a
+        // clean, already-confirmed composer must survive the outage. Confirmed
+        // readiness still gates it on context + git-fingerprint + freshness, so a
+        // stale snapshot can never open a never-confirmed Create.
       })
     return () => {
       stale = true
     }
   }, [
+    panelContextKey,
+    runtimeEnvironmentId,
+    repoConnectionId,
     activeWorktreeId,
     activeWorktreePath,
     branch,
@@ -1498,6 +1717,8 @@ export default function ChecksPanel(): React.JSX.Element {
     gitStatusReadyForPanelContext,
     hasUncommittedChanges,
     hostedReviewCreationRequestKey,
+    eligibilityRefreshNonce,
+    localExecutionScope,
     isFolder,
     isPanelVisible,
     linkedPR,
@@ -2181,6 +2402,10 @@ export default function ChecksPanel(): React.JSX.Element {
       if (isCurrentRequest()) {
         refreshInFlightRef.current = false
         setIsRefreshing(false)
+        // Why: force a fresh eligibility request whose start time is after any
+        // current hard-refresh error, so a resolved auth/permission failure can
+        // clear the sticky hard error even when Git state did not change.
+        setEligibilityRefreshNonce((value) => value + 1)
       }
     }
   }, [
@@ -3263,6 +3488,51 @@ export default function ChecksPanel(): React.JSX.Element {
     pushBranch
   ])
 
+  // Sync the branch with its upstream using the same runtime-scoped operation and
+  // push target as Source Control, so a `needs_sync` create blocker is actionable
+  // from the Checks panel instead of showing guidance with no button.
+  const handleSyncBranch = useCallback(async (): Promise<void> => {
+    if (!activeWorktreeId || !activeWorktree?.path || isSyncingBranch || isRemoteOperationActive) {
+      return
+    }
+    const connectionId = activeConnectionId ?? undefined
+    setIsSyncingBranch(true)
+    try {
+      await syncBranch(
+        activeWorktreeId,
+        activeWorktree.path,
+        connectionId,
+        activeWorktree.pushTarget,
+        {
+          runtimeTargetSettings: ownerSettings
+        }
+      )
+      await fetchUpstreamStatus(
+        activeWorktreeId,
+        activeWorktree.path,
+        connectionId,
+        activeWorktree.pushTarget,
+        { runtimeTargetSettings: ownerSettings }
+      )
+    } catch {
+      // Store remote actions already surface the sync failure toast.
+    } finally {
+      // Why: syncing changes ahead/behind, which the panel uses to choose between
+      // Sync, Create PR, and Push & Create PR.
+      setGitStatusRefreshNonce((value) => value + 1)
+      setIsSyncingBranch(false)
+    }
+  }, [
+    activeWorktree,
+    activeWorktreeId,
+    activeConnectionId,
+    fetchUpstreamStatus,
+    isSyncingBranch,
+    isRemoteOperationActive,
+    ownerSettings,
+    syncBranch
+  ])
+
   const handlePullRequestCreated = useCallback(
     async (result: {
       provider: HostedReviewProvider
@@ -3581,17 +3851,79 @@ export default function ChecksPanel(): React.JSX.Element {
           hasUpstream: publishActionRemoteStatus?.hasUpstream,
           hasCurrentBranch: Boolean(branch)
         }))
-    const emptyStateCopy = getChecksPanelEmptyStateCopy({
+    // Non-GitHub providers (GitLab/Bitbucket/Azure/Gitea) have no typed GitHub
+    // refresh state; only feed the GitHub refresh classification into the selector
+    // for GitHub contexts. When a hard error is still active (sticky across
+    // auto-retries), surface it as the refresh state so the hard-error card and
+    // composer suppression persist even while a queued/in-flight retry is
+    // temporarily the live status.
+    const emptyRefreshInput = !isGitHubReviewContext
+      ? undefined
+      : checksPanelHasHardRefreshError && hardRefreshError
+        ? { status: 'error' as const, errorType: hardRefreshError.errorType }
+        : prRefreshState
+          ? {
+              status: prRefreshState.status,
+              errorType: prRefreshState.errorType,
+              skippedReason: prRefreshState.skippedReason,
+              nextAutoRetryAt: prRefreshState.nextAutoRetryAt,
+              retryDisabledUntil: prRefreshState.retryDisabledUntil
+            }
+          : undefined
+    const emptyGitStatusPhase: 'loading' | 'ready' | 'error' =
+      gitStatusInputs.hasUncommittedChanges !== undefined
+        ? 'ready'
+        : gitStatusProbeErrorContextKey === panelContextKey
+          ? 'error'
+          : 'loading'
+    const reviewState = getChecksPanelReviewState({
       operationLabel,
-      prRefreshStatus: emptyReviewIsGitLab ? undefined : prRefreshState?.status,
-      prRefreshErrorType: emptyReviewIsGitLab ? undefined : prRefreshState?.errorType,
-      hostedReviewBlockedReason: hostedReviewCreation?.blockedReason,
-      hasUpstream: publishActionRemoteStatus?.hasUpstream,
-      hasCurrentBranch: Boolean(branch),
       reviewLabel: emptyReviewLabel,
       reviewShortLabel: emptyReviewShortLabel,
-      hasAmbiguousGitHubHostedReview
+      providerName: hostedReviewCreateCopy.providerName,
+      isGitHubProvider: hostedReviewCreateProvider === 'github',
+      reviewLookup: checksPanelReviewLookup,
+      openReviewUrl: checksPanelReviewLookupResult.openReviewUrl,
+      eligibilityBlockedReason: hostedReviewCreation?.blockedReason,
+      // Confirmed readiness (not the live create gate) drives composer mode so
+      // the selector matches the preserved-composer semantics.
+      confirmedReadiness: confirmedReadiness.confirmed,
+      confirmedNeedsPush: confirmedReadiness.needsPush,
+      refresh: emptyRefreshInput,
+      gitStatusPhase: emptyGitStatusPhase,
+      hasUpstream: publishActionRemoteStatus?.hasUpstream,
+      hasCurrentBranch: Boolean(branch)
     })
+    const emptyStateCopy = { title: reviewState.title, description: reviewState.description }
+    const reviewStateAutoRetryText =
+      reviewState.autoRetryAt !== undefined && reviewState.autoRetryAt > Date.now()
+        ? translate(
+            'auto.components.right.sidebar.ChecksPanel.review.auto_retry',
+            'Orca will retry at {{time}}.',
+            { time: new Date(reviewState.autoRetryAt).toLocaleTimeString() }
+          )
+        : null
+    const reviewRecoveryRetryDisabled =
+      reviewState.retryDisabledUntil !== undefined && Date.now() < reviewState.retryDisabledUntil
+    const reviewRecoveryLabelIsRefresh = reviewState.recovery.includes('refresh')
+    // Only offer Retry/Refresh when the selector's recovery set includes it;
+    // states like git-status loading, bare, or archived expose no recovery.
+    const reviewShowRetryOrRefresh =
+      reviewState.recovery.includes('retry') || reviewRecoveryLabelIsRefresh
+    const reviewShowOpenReview =
+      reviewState.recovery.includes('open_review') && Boolean(reviewState.openReviewUrl)
+    // The selector is the authority for the Sync workflow action; a `needs_sync`
+    // create blocker must expose Sync Branch, not just guidance copy.
+    const reviewShowSyncBranch = reviewState.workflowAction === 'sync_branch'
+    // The action row must render whenever any action is available — recovery
+    // actions (Retry/Refresh/Open Review) are shown independently of the composer
+    // so a preserved confirmed composer still exposes a working Retry during a
+    // transient failure.
+    const reviewShowActionRow =
+      canPublishBranch ||
+      reviewShowSyncBranch ||
+      (reviewShowOpenReview && Boolean(reviewState.openReviewUrl)) ||
+      reviewShowRetryOrRefresh
     return (
       <div className="px-4 py-6">
         {detachedHeadDisplay && (
@@ -3601,6 +3933,12 @@ export default function ChecksPanel(): React.JSX.Element {
         )}
         <div className="text-sm font-medium text-foreground">{emptyStateCopy.title}</div>
         <div className="mt-1 text-xs text-muted-foreground">{emptyStateCopy.description}</div>
+        {reviewState.detail ? (
+          <div className="mt-1 text-xs text-muted-foreground">{reviewState.detail}</div>
+        ) : null}
+        {reviewStateAutoRetryText ? (
+          <div className="mt-1 text-xs text-muted-foreground">{reviewStateAutoRetryText}</div>
+        ) : null}
         {!operationInProgress && createComposerOpen ? (
           <div className="mt-4 border-t border-border pt-3">
             <CreateHostedReviewComposer
@@ -3648,7 +3986,7 @@ export default function ChecksPanel(): React.JSX.Element {
             />
           </div>
         ) : null}
-        {!operationInProgress && (!createComposerOpen || canPublishBranch) && (
+        {!operationInProgress && reviewShowActionRow && (
           <div className="mt-3 flex flex-wrap gap-2">
             {canPublishBranch && (
               <Button
@@ -3664,11 +4002,50 @@ export default function ChecksPanel(): React.JSX.Element {
                     )}
               </Button>
             )}
-            {!createComposerOpen ? (
+            {reviewShowSyncBranch && (
+              <Button
+                size="xs"
+                disabled={isSyncingBranch || isRemoteOperationActive}
+                onClick={() => void handleSyncBranch()}
+              >
+                {isSyncingBranch
+                  ? translate('auto.components.right.sidebar.ChecksPanel.sync.pending', 'Syncing…')
+                  : translate(
+                      'auto.components.right.sidebar.ChecksPanel.sync.branch',
+                      'Sync Branch'
+                    )}
+              </Button>
+            )}
+            {reviewShowOpenReview && reviewState.openReviewUrl ? (
               <Button
                 size="xs"
                 variant="outline"
-                disabled={emptyRefreshing || isPublishingBranch || isRemoteOperationActive}
+                disabled={isRemoteOperationActive}
+                onClick={(event) =>
+                  openChecksPanelHostedReviewUrl({
+                    url: reviewState.openReviewUrl as string,
+                    event,
+                    isMac: isMacPlatform(),
+                    worktreeId: activeWorktreeId
+                  })
+                }
+              >
+                {translate(
+                  'auto.components.right.sidebar.ChecksPanel.review.open_review',
+                  'Open Review'
+                )}
+              </Button>
+            ) : null}
+            {reviewShowRetryOrRefresh ? (
+              <Button
+                size="xs"
+                variant="outline"
+                disabled={
+                  emptyRefreshing ||
+                  isPublishingBranch ||
+                  isRemoteOperationActive ||
+                  reviewRecoveryRetryDisabled
+                }
                 onClick={() => {
                   if (!activeWorktreeId) {
                     return
@@ -3681,7 +4058,9 @@ export default function ChecksPanel(): React.JSX.Element {
               >
                 {emptyRefreshing
                   ? translate('auto.components.right.sidebar.ChecksPanel.71026ca2cb', 'Refreshing…')
-                  : translate('auto.components.right.sidebar.ChecksPanel.7f4489f370', 'Refresh')}
+                  : reviewRecoveryLabelIsRefresh
+                    ? translate('auto.components.right.sidebar.ChecksPanel.7f4489f370', 'Refresh')
+                    : translate('auto.components.right.sidebar.ChecksPanel.review.retry', 'Retry')}
               </Button>
             ) : null}
           </div>
diff --git a/src/renderer/src/components/right-sidebar/CommitArea.test.tsx b/src/renderer/src/components/right-sidebar/CommitArea.test.tsx
index b360795e662..a34540f7823 100644
--- a/src/renderer/src/components/right-sidebar/CommitArea.test.tsx
+++ b/src/renderer/src/components/right-sidebar/CommitArea.test.tsx
@@ -448,7 +448,8 @@ describe('CommitArea', () => {
         review: null,
         canCreate: false,
         blockedReason: 'dirty',
-        nextAction: 'commit'
+        nextAction: 'commit',
+        reviewLookupOutcome: 'not_found'
       }
     })
     const markup = renderCommitArea(baseProps(input))
@@ -481,7 +482,8 @@ describe('CommitArea', () => {
         review: null,
         canCreate: false,
         blockedReason: 'needs_push',
-        nextAction: 'push'
+        nextAction: 'push',
+        reviewLookupOutcome: 'not_found'
       }
     })
     const markup = renderCommitArea(baseProps(input))
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index 665fd7419c1..a4eaf4250bc 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -3333,10 +3333,8 @@ function SourceControlInner(): React.JSX.Element {
         if (stale) {
           return
         }
-        // Why: a failed/timed-out remote probe must not leave an inert disabled
-        // button. When the local git status determines a blocker (dirty, no
-        // upstream, needs push/sync), surface the actionable preparation intent;
-        // otherwise fall back to the retryable failed state.
+        // Why: a failed remote probe can provide branch guidance, but it cannot
+        // authorize hosted-review creation.
         const localBlocker = buildLocalBlockerHostedReviewCreationEligibility(
           resolveCurrentHostedReviewCreationProvider(),
           {
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-ambiguous-github-review.test.ts b/src/renderer/src/components/right-sidebar/checks-panel-ambiguous-github-review.test.ts
deleted file mode 100644
index db51fd6ef33..00000000000
--- a/src/renderer/src/components/right-sidebar/checks-panel-ambiguous-github-review.test.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { hasAmbiguousGitHubHostedReviewForChecksPanel } from './checks-panel-ambiguous-github-review'
-
-describe('hasAmbiguousGitHubHostedReviewForChecksPanel', () => {
-  it('treats missing PR cache as ambiguous when a GitHub hosted review exists', () => {
-    expect(
-      hasAmbiguousGitHubHostedReviewForChecksPanel({
-        hostedReview: { provider: 'github' },
-        prCacheEntry: undefined,
-        prCacheKey: 'repo::feature'
-      })
-    ).toBe(true)
-  })
-
-  it('treats cached no-PR data as ambiguous when a GitHub hosted review exists', () => {
-    expect(
-      hasAmbiguousGitHubHostedReviewForChecksPanel({
-        hostedReview: { provider: 'github' },
-        prCacheEntry: { data: null },
-        prCacheKey: 'repo::feature'
-      })
-    ).toBe(true)
-  })
-
-  it('does not treat existing PR cache data as ambiguous', () => {
-    expect(
-      hasAmbiguousGitHubHostedReviewForChecksPanel({
-        hostedReview: { provider: 'github' },
-        prCacheEntry: { data: { number: 12 } },
-        prCacheKey: 'repo::feature'
-      })
-    ).toBe(false)
-  })
-
-  it('does not treat non-GitHub hosted reviews as ambiguous', () => {
-    expect(
-      hasAmbiguousGitHubHostedReviewForChecksPanel({
-        hostedReview: { provider: 'gitlab' },
-        prCacheEntry: { data: null },
-        prCacheKey: 'repo::feature'
-      })
-    ).toBe(false)
-  })
-})
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-ambiguous-github-review.ts b/src/renderer/src/components/right-sidebar/checks-panel-ambiguous-github-review.ts
deleted file mode 100644
index bca25a7a228..00000000000
--- a/src/renderer/src/components/right-sidebar/checks-panel-ambiguous-github-review.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-type HostedReviewProviderLike = {
-  provider?: string | null
-}
-
-type PRCacheEntryLike = {
-  data?: unknown
-}
-
-/**
- * Flags GitHub-hosted review metadata whose matching PR cache may still be unknown.
- */
-export function hasAmbiguousGitHubHostedReviewForChecksPanel(input: {
-  hostedReview: HostedReviewProviderLike | null | undefined
-  prCacheEntry: PRCacheEntryLike | null | undefined
-  prCacheKey: string
-}): boolean {
-  return (
-    input.hostedReview?.provider === 'github' &&
-    input.prCacheKey !== '' &&
-    input.prCacheEntry?.data == null
-  )
-}
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-blocker-copy.ts b/src/renderer/src/components/right-sidebar/checks-panel-blocker-copy.ts
new file mode 100644
index 00000000000..1313afa7e05
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/checks-panel-blocker-copy.ts
@@ -0,0 +1,220 @@
+import type { HostedReviewCreationBlockedReason } from '../../../../shared/hosted-review'
+import { translate } from '@/i18n/i18n'
+import {
+  autoRetrySchedule,
+  capitalizeReviewLabel,
+  isHardRefreshError,
+  type ChecksPanelRecoveryAction,
+  type ChecksPanelReviewState,
+  type ChecksPanelReviewStateInput
+} from './checks-panel-review-state-model'
+import { concurrentLookupDetail } from './checks-panel-review-copy'
+
+type KeyedCopy = { key: string; fallback: string }
+
+const SAFETY_COPY: Record<
+  | 'detached_head'
+  | 'dirty'
+  | 'default_branch'
+  | 'fork_head_unsupported'
+  | 'base_not_on_remote'
+  | 'unsupported_provider',
+  { title: KeyedCopy; body: KeyedCopy }
+> = {
+  detached_head: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.detached.title',
+      fallback: 'No current branch'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.detached.body',
+      fallback: 'Check out a branch before creating a {{reviewLabel}}.'
+    }
+  },
+  dirty: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.dirty.title',
+      fallback: 'Commit changes first'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.dirty.body',
+      fallback: 'Commit or stash your changes before creating a {{reviewLabel}}.'
+    }
+  },
+  default_branch: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.default_branch.title',
+      fallback: 'On the default branch'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.default_branch.body',
+      fallback: 'Switch to a feature branch before creating a {{reviewLabel}}.'
+    }
+  },
+  fork_head_unsupported: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.fork.title',
+      fallback: 'Fork head unsupported'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.fork.body',
+      fallback: 'Orca cannot create a {{reviewLabel}} from this fork head here.'
+    }
+  },
+  base_not_on_remote: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.base_missing.title',
+      fallback: 'Base branch not on remote'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.base_missing.body',
+      fallback:
+        "This branch's base is not on the remote yet, so a {{reviewLabel}} cannot target it."
+    }
+  },
+  unsupported_provider: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.unsupported.title',
+      fallback: '{{reviewLabelCap}} not supported here'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.unsupported.body',
+      fallback: 'This repository provider does not support creating a {{reviewLabel}} from Orca.'
+    }
+  }
+}
+
+export function safetyBlockerState(
+  input: ChecksPanelReviewStateInput,
+  reason: NonNullable<HostedReviewCreationBlockedReason>
+): ChecksPanelReviewState {
+  const { reviewLabel } = input
+  if (reason === 'existing_review') {
+    // Same family as positive evidence — offer trusted Open Review, never Create.
+    return {
+      renderReview: false,
+      title: translate(
+        'auto.components.right.sidebar.checks.panel.review.existing.title',
+        '{{reviewLabelCap}} already exists',
+        { reviewLabelCap: capitalizeReviewLabel(reviewLabel) }
+      ),
+      description: translate(
+        'auto.components.right.sidebar.checks.panel.review.existing.body',
+        'Orca found an existing {{reviewLabel}} for this branch.',
+        { reviewLabel }
+      ),
+      composerMode: 'hidden',
+      workflowAction: null,
+      recovery: input.openReviewUrl ? ['open_review'] : [],
+      openReviewUrl: input.openReviewUrl
+    }
+  }
+  const copy = SAFETY_COPY[reason as keyof typeof SAFETY_COPY] ?? SAFETY_COPY.unsupported_provider
+  const vars = { reviewLabel, reviewLabelCap: capitalizeReviewLabel(reviewLabel) }
+  return {
+    renderReview: false,
+    title: translate(copy.title.key, copy.title.fallback, vars),
+    description: translate(copy.body.key, copy.body.fallback, vars),
+    composerMode: 'hidden',
+    workflowAction: null,
+    recovery: []
+  }
+}
+
+const BRANCH_BLOCKER_COPY: Record<
+  'no_upstream' | 'needs_sync' | 'auth_required',
+  { title: KeyedCopy; body: KeyedCopy; workflow: ChecksPanelReviewState['workflowAction'] }
+> = {
+  no_upstream: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.no_upstream.title',
+      fallback: 'No upstream configured'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.no_upstream.body',
+      fallback: 'Publish this branch to set its upstream before creating a {{reviewLabel}}.'
+    },
+    workflow: 'publish_branch'
+  },
+  needs_sync: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.needs_sync.title',
+      fallback: 'Branch needs to sync'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.needs_sync.body',
+      fallback: 'Sync this branch with its upstream before creating a {{reviewLabel}}.'
+    },
+    workflow: 'sync_branch'
+  },
+  auth_required: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.auth_required.title',
+      fallback: 'Connect {{provider}}'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.auth_required.body',
+      fallback:
+        '{{provider}} must be connected in this environment before Orca can create a {{reviewLabel}}.'
+    },
+    workflow: null
+  }
+}
+
+export function branchBlockerState(
+  input: ChecksPanelReviewStateInput,
+  reason: NonNullable<HostedReviewCreationBlockedReason>
+): ChecksPanelReviewState {
+  const { reviewLabel, providerName } = input
+  const detail = concurrentLookupDetail(input)
+  const schedule = detail ? autoRetrySchedule(input) : {}
+  // Positive-unresolved evidence with a trusted URL must still expose Open Review
+  // beneath the blocker (Create/Push & Create stay suppressed). Retry is offered
+  // whenever a concurrent lookup failure produced a detail sentence.
+  const canOpenReview = input.reviewLookup === 'positive_unresolved' && Boolean(input.openReviewUrl)
+  const lookupRecovery: ChecksPanelRecoveryAction[] = [
+    ...(canOpenReview ? (['open_review'] as ChecksPanelRecoveryAction[]) : []),
+    ...(detail ? (['retry'] as ChecksPanelRecoveryAction[]) : [])
+  ]
+  const openReviewUrl = canOpenReview ? input.openReviewUrl : undefined
+  const vars = { reviewLabel, provider: providerName }
+
+  if (reason === 'needs_push') {
+    // Push & Create unless review evidence or a hard error blocks create.
+    const blocked =
+      input.reviewLookup === 'positive_unresolved' ||
+      isHardRefreshError(input.refresh) ||
+      !input.confirmedReadiness
+    return {
+      renderReview: false,
+      title: translate(
+        'auto.components.right.sidebar.checks.panel.review.needs_push.title',
+        'Branch has unpushed commits'
+      ),
+      description: translate(
+        'auto.components.right.sidebar.checks.panel.review.needs_push.body',
+        'Push the latest commits before creating a {{reviewLabel}}.',
+        { reviewLabel }
+      ),
+      detail,
+      composerMode: blocked ? 'hidden' : 'needs_push_open',
+      workflowAction: blocked ? null : 'push_and_create',
+      recovery: lookupRecovery,
+      openReviewUrl,
+      ...schedule
+    }
+  }
+
+  const copy = BRANCH_BLOCKER_COPY[reason as keyof typeof BRANCH_BLOCKER_COPY]
+  return {
+    renderReview: false,
+    title: translate(copy.title.key, copy.title.fallback, vars),
+    description: translate(copy.body.key, copy.body.fallback, vars),
+    detail,
+    composerMode: 'hidden',
+    workflowAction: copy.workflow,
+    recovery: lookupRecovery,
+    openReviewUrl,
+    ...schedule
+  }
+}
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-empty-state.test.ts b/src/renderer/src/components/right-sidebar/checks-panel-empty-state.test.ts
index 7e3f8ca3c41..941012d7a8d 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel-empty-state.test.ts
+++ b/src/renderer/src/components/right-sidebar/checks-panel-empty-state.test.ts
@@ -1,281 +1,263 @@
 import { describe, expect, it } from 'vitest'
 import {
-  getChecksPanelEmptyStateCopy,
-  shouldShowChecksPanelPublishBranchAction
+  getChecksPanelReviewState,
+  shouldShowChecksPanelPublishBranchAction,
+  type ChecksPanelReviewStateInput
 } from './checks-panel-empty-state'
 
-describe('getChecksPanelEmptyStateCopy', () => {
-  it('shows a local-only branch message instead of a refresh error', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        hostedReviewBlockedReason: 'no_upstream',
-        hasUpstream: false
-      })
-    ).toEqual({
-      title: 'Branch not published',
-      description: 'Publish this branch before creating a pull request.'
-    })
+function input(overrides: Partial<ChecksPanelReviewStateInput> = {}): ChecksPanelReviewStateInput {
+  return {
+    operationLabel: null,
+    reviewLabel: 'pull request',
+    reviewShortLabel: 'PR',
+    providerName: 'GitHub',
+    isGitHubProvider: true,
+    reviewLookup: 'unknown',
+    openReviewUrl: null,
+    eligibilityBlockedReason: undefined,
+    confirmedReadiness: false,
+    confirmedNeedsPush: false,
+    refresh: undefined,
+    gitStatusPhase: 'ready',
+    hasUpstream: true,
+    hasCurrentBranch: true,
+    ...overrides
+  }
+}
+
+describe('getChecksPanelReviewState — no-review honesty', () => {
+  it('only renders "No pull request found" for an accepted no-review result', () => {
+    expect(getChecksPanelReviewState(input({ reviewLookup: 'not_found' })).title).toBe(
+      'No pull request found'
+    )
   })
 
-  it('uses remote status as a fallback before eligibility finishes', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        hostedReviewBlockedReason: undefined,
-        hasUpstream: false
-      }).title
-    ).toBe('Branch not published')
+  it('never says "No pull request found" for a missing/unknown lookup', () => {
+    const state = getChecksPanelReviewState(input({ reviewLookup: 'unknown' }))
+    expect(state.title).not.toContain('No pull request found')
+    expect(state.title).toBe('Pull request status unavailable')
   })
 
-  it('does not show unpublished branch copy when HEAD is detached', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        hostedReviewBlockedReason: 'no_upstream',
-        hasUpstream: false,
-        hasCurrentBranch: false
-      }).title
-    ).toBe('Could not refresh pull request')
+  it('never says "No pull request found" for a paused refresh', () => {
+    const state = getChecksPanelReviewState(
+      input({ reviewLookup: 'unknown', refresh: { status: 'paused' } })
+    )
+    expect(state.title).toBe('GitHub refresh paused')
   })
 
-  it('uses remote status as a fallback when eligibility has no concrete blocker', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        hostedReviewBlockedReason: null,
-        hasUpstream: false
-      }).title
-    ).toBe('Branch not published')
+  it('never says "No pull request found" for a skipped refresh', () => {
+    const state = getChecksPanelReviewState(
+      input({ reviewLookup: 'unknown', refresh: { status: 'skipped', skippedReason: 'bare' } })
+    )
+    expect(state.title).toBe('Bare repository')
   })
 
-  it('shows unpushed commits before a refresh error', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        hostedReviewBlockedReason: 'needs_push',
-        hasUpstream: true
-      })
-    ).toEqual({
-      title: 'Branch has unpushed commits',
-      description: 'Push your branch before creating a pull request.'
-    })
-  })
-
-  it('shows unpublished branch copy even when PR provider eligibility has another blocker', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        hostedReviewBlockedReason: 'unsupported_provider',
-        hasUpstream: false
-      }).title
-    ).toBe('Branch not published')
-  })
-
-  it('keeps the generic refresh error when no local branch action is known', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        hostedReviewBlockedReason: null,
-        hasUpstream: true
-      }).title
-    ).toBe('Could not refresh pull request')
-  })
-
-  it('uses merge request copy for GitLab review contexts', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: undefined,
-        hostedReviewBlockedReason: 'unsupported_provider',
-        hasUpstream: true,
+  it('uses merge request wording for GitLab', () => {
+    const state = getChecksPanelReviewState(
+      input({
         reviewLabel: 'merge request',
-        reviewShortLabel: 'MR'
+        reviewShortLabel: 'MR',
+        providerName: 'GitLab',
+        isGitHubProvider: false,
+        reviewLookup: 'not_found'
       })
-    ).toEqual({
-      title: 'No merge request found',
-      description: 'Create a merge request to start checks and review.'
-    })
+    )
+    expect(state.title).toBe('No merge request found')
+  })
+})
+
+describe('getChecksPanelReviewState — precedence', () => {
+  it('operation in progress wins', () => {
+    expect(
+      getChecksPanelReviewState(input({ operationLabel: 'Rebase', reviewLookup: 'not_found' }))
+        .title
+    ).toBe('Rebase in progress')
   })
 
-  it('uses neutral copy when GitHub hosted-review data exists without PR cache', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: undefined,
-        hostedReviewBlockedReason: null,
-        hasUpstream: true,
-        hasAmbiguousGitHubHostedReview: true
+  it('renderReview for found lookup', () => {
+    expect(getChecksPanelReviewState(input({ reviewLookup: 'found' })).renderReview).toBe(true)
+  })
+
+  it('positive_unresolved blocks create and offers Open Review', () => {
+    const state = getChecksPanelReviewState(
+      input({ reviewLookup: 'positive_unresolved', openReviewUrl: 'https://x/pull/1' })
+    )
+    expect(state.title).toBe('Pull request details unavailable')
+    expect(state.composerMode).toBe('hidden')
+    expect(state.workflowAction).toBeNull()
+    expect(state.recovery).toContain('open_review')
+    expect(state.openReviewUrl).toBe('https://x/pull/1')
+  })
+
+  it('offers Open Review under a branch blocker when positive evidence has a trusted URL', () => {
+    // A concurrent branch blocker owns the copy but must not swallow the known
+    // review: Open Review is exposed while Create / Push & Create stay suppressed.
+    const state = getChecksPanelReviewState(
+      input({
+        reviewLookup: 'positive_unresolved',
+        openReviewUrl: 'https://x/pull/7',
+        eligibilityBlockedReason: 'no_upstream',
+        hasUpstream: false
       })
-    ).toEqual({
-      title: 'Pull request status unavailable',
-      description: 'Refresh GitHub status for this branch to load checks and review.'
-    })
+    )
+    expect(state.title).toBe('No upstream configured')
+    expect(state.workflowAction).toBe('publish_branch')
+    expect(state.composerMode).toBe('hidden')
+    expect(state.recovery).toContain('open_review')
+    expect(state.openReviewUrl).toBe('https://x/pull/7')
   })
 
-  it('does not show no-PR copy for paused ambiguous GitHub hosted-review data', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'paused',
-        hostedReviewBlockedReason: null,
-        hasUpstream: true,
-        hasAmbiguousGitHubHostedReview: true
-      }).title
-    ).toBe('Pull request status unavailable')
+  it('needs_sync emits a sync_branch workflow action for the renderer', () => {
+    const state = getChecksPanelReviewState(input({ eligibilityBlockedReason: 'needs_sync' }))
+    expect(state.title).toBe('Branch needs to sync')
+    expect(state.workflowAction).toBe('sync_branch')
   })
 
-  it('keeps refresh errors for ambiguous GitHub hosted-review data', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        hostedReviewBlockedReason: null,
-        hasUpstream: true,
-        hasAmbiguousGitHubHostedReview: true
-      }).title
-    ).toBe('Could not refresh pull request')
-  })
-
-  it('uses neutral copy for ambiguous GitHub hosted-review data before unpublished branch copy', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: undefined,
-        hostedReviewBlockedReason: 'no_upstream',
+  it('branch blocker (no_upstream) ranks above a refresh error', () => {
+    const state = getChecksPanelReviewState(
+      input({
+        eligibilityBlockedReason: 'no_upstream',
         hasUpstream: false,
-        hasAmbiguousGitHubHostedReview: true
-      }).title
-    ).toBe('Pull request status unavailable')
-  })
-
-  it('uses neutral copy for ambiguous GitHub hosted-review data before remote fallback publish copy', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: undefined,
-        hostedReviewBlockedReason: undefined,
-        hasUpstream: false,
-        hasAmbiguousGitHubHostedReview: true
-      }).title
-    ).toBe('Pull request status unavailable')
-  })
-
-  it('uses neutral copy for ambiguous GitHub hosted-review data before unpushed commit copy', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: undefined,
-        hostedReviewBlockedReason: 'needs_push',
-        hasUpstream: true,
-        hasAmbiguousGitHubHostedReview: true
-      }).title
-    ).toBe('Pull request status unavailable')
-  })
-
-  // Regression: a local-only branch with an ambiguous GitHub hosted-review card
-  // flip-flopped between "Branch not published" (during an active PR refresh) and
-  // "Pull request status unavailable" (while idle) as background refreshes cycled
-  // the status. The ambiguous copy must stay stable across the whole lifecycle.
-  it('keeps stable ambiguous copy while a PR refresh is queued on an unpublished branch', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'queued',
-        hostedReviewBlockedReason: 'no_upstream',
-        hasUpstream: false,
-        hasAmbiguousGitHubHostedReview: true
-      }).title
-    ).toBe('Pull request status unavailable')
-  })
-
-  it('keeps stable ambiguous copy while a PR refresh is in-flight on an unpublished branch', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'in-flight',
-        hostedReviewBlockedReason: undefined,
-        hasUpstream: false,
-        hasAmbiguousGitHubHostedReview: true
-      }).title
-    ).toBe('Pull request status unavailable')
-  })
-
-  it('does not fall back to unpublished-branch copy on refresh error for ambiguous data', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        hostedReviewBlockedReason: 'no_upstream',
-        hasUpstream: false,
-        hasAmbiguousGitHubHostedReview: true
-      }).title
-    ).toBe('Could not refresh pull request')
-  })
-
-  it('attributes a 5xx outage to GitHub instead of the generic refresh error', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        prRefreshErrorType: 'server_error',
-        hostedReviewBlockedReason: null,
-        hasUpstream: true
+        refresh: { status: 'error', errorType: 'auth' }
       })
-    ).toEqual({
+    )
+    expect(state.title).toBe('No upstream configured')
+    expect(state.workflowAction).toBe('publish_branch')
+    // Hard error concurrent with the blocker: detail appended, create suppressed.
+    expect(state.detail).toBe(
+      'Orca also could not confirm whether this branch already has a pull request.'
+    )
+  })
+
+  it('hard refresh error hides the composer', () => {
+    const state = getChecksPanelReviewState(
+      input({ refresh: { status: 'error', errorType: 'auth' } })
+    )
+    expect(state.title).toBe('GitHub authentication failed')
+    expect(state.composerMode).toBe('hidden')
+    expect(state.workflowAction).toBeNull()
+  })
+
+  it('hard refresh error overrides an accepted no-review', () => {
+    const state = getChecksPanelReviewState(
+      input({ reviewLookup: 'not_found', refresh: { status: 'error', errorType: 'permission' } })
+    )
+    expect(state.title).toBe('GitHub access denied')
+  })
+})
+
+describe('getChecksPanelReviewState — composer preserve', () => {
+  it('accepted no-review with confirmed readiness opens the composer', () => {
+    const state = getChecksPanelReviewState(
+      input({ reviewLookup: 'not_found', confirmedReadiness: true })
+    )
+    expect(state.composerMode).toBe('confirmed_open')
+    expect(state.workflowAction).toBe('create')
+  })
+
+  it('transient error preserves a confirmed composer', () => {
+    const state = getChecksPanelReviewState(
+      input({ confirmedReadiness: true, refresh: { status: 'error', errorType: 'network' } })
+    )
+    expect(state.composerMode).toBe('confirmed_open')
+    expect(state.title).toBe('Could not reach GitHub')
+  })
+
+  it('attributes a transient 5xx outage to GitHub and preserves a confirmed composer', () => {
+    const state = getChecksPanelReviewState(
+      input({ confirmedReadiness: true, refresh: { status: 'error', errorType: 'server_error' } })
+    )
+    expect(state).toMatchObject({
       title: 'GitHub is unavailable',
       description:
-        "GitHub's API is temporarily unavailable. This panel reloads automatically once it recovers."
+        "GitHub's API is temporarily unavailable. This panel reloads automatically once it recovers.",
+      composerMode: 'confirmed_open',
+      workflowAction: 'create'
     })
   })
 
-  it('attributes a network failure to GitHub in the ambiguous hosted-review branch', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        prRefreshErrorType: 'network',
-        hostedReviewBlockedReason: null,
-        hasUpstream: true,
-        hasAmbiguousGitHubHostedReview: true
-      }).title
-    ).toBe("Can't reach GitHub")
-  })
-
-  it('keeps the generic refresh error for non-outage error types', () => {
-    expect(
-      getChecksPanelEmptyStateCopy({
-        operationLabel: null,
-        prRefreshStatus: 'error',
-        prRefreshErrorType: 'auth',
-        hostedReviewBlockedReason: null,
-        hasUpstream: true
-      }).title
-    ).toBe('Could not refresh pull request')
-  })
-
-  it('renders a single stable title across a full ambiguous refresh cycle', () => {
-    const cycle = ['queued', 'in-flight', undefined, 'skipped', 'paused'] as const
-    const titles = new Set(
-      cycle.map(
-        (prRefreshStatus) =>
-          getChecksPanelEmptyStateCopy({
-            operationLabel: null,
-            prRefreshStatus,
-            hostedReviewBlockedReason: 'no_upstream',
-            hasUpstream: false,
-            hasAmbiguousGitHubHostedReview: true
-          }).title
-      )
+  it('transient error without confirmed readiness never opens a composer', () => {
+    const state = getChecksPanelReviewState(
+      input({ confirmedReadiness: false, refresh: { status: 'error', errorType: 'network' } })
     )
-    expect([...titles]).toEqual(['Pull request status unavailable'])
+    expect(state.composerMode).toBe('hidden')
+  })
+
+  it('needs_push with positive_unresolved never exposes Push & Create', () => {
+    const state = getChecksPanelReviewState(
+      input({
+        eligibilityBlockedReason: 'needs_push',
+        reviewLookup: 'positive_unresolved',
+        confirmedReadiness: true,
+        confirmedNeedsPush: true
+      })
+    )
+    expect(state.composerMode).toBe('hidden')
+    expect(state.workflowAction).toBeNull()
+  })
+
+  it('needs_push with confirmed readiness offers Push & Create', () => {
+    const state = getChecksPanelReviewState(
+      input({
+        eligibilityBlockedReason: 'needs_push',
+        reviewLookup: 'not_found',
+        confirmedReadiness: true,
+        confirmedNeedsPush: true
+      })
+    )
+    expect(state.composerMode).toBe('needs_push_open')
+    expect(state.workflowAction).toBe('push_and_create')
+  })
+})
+
+describe('getChecksPanelReviewState — schedule', () => {
+  it('carries auto-retry schedule on the paused row', () => {
+    const state = getChecksPanelReviewState(
+      input({ refresh: { status: 'paused', nextAutoRetryAt: 123, retryDisabledUntil: 123 } })
+    )
+    expect(state.autoRetryAt).toBe(123)
+    expect(state.retryDisabledUntil).toBe(123)
+  })
+
+  it('carries auto-retry schedule on a transient network error', () => {
+    const state = getChecksPanelReviewState(
+      input({ refresh: { status: 'error', errorType: 'network', nextAutoRetryAt: 456 } })
+    )
+    expect(state.autoRetryAt).toBe(456)
+    expect(state.retryDisabledUntil).toBeUndefined()
+  })
+})
+
+describe('getChecksPanelReviewState — git status', () => {
+  it('shows loading copy when upstream is unknown', () => {
+    expect(
+      getChecksPanelReviewState(input({ gitStatusPhase: 'loading', hasUpstream: undefined })).title
+    ).toBe('Checking branch status')
+  })
+
+  it('shows failed copy when the probe failed and upstream is unknown', () => {
+    const state = getChecksPanelReviewState(
+      input({ gitStatusPhase: 'error', hasUpstream: undefined })
+    )
+    expect(state.title).toBe('Could not check branch status')
+    expect(state.recovery).toContain('retry')
+    expect(state.composerMode).toBe('hidden')
+  })
+})
+
+describe('getChecksPanelReviewState — active and skipped', () => {
+  it('queued shows checking copy', () => {
+    expect(getChecksPanelReviewState(input({ refresh: { status: 'queued' } })).title).toBe(
+      'Checking pull request status'
+    )
+  })
+
+  it('disconnected host row', () => {
+    expect(
+      getChecksPanelReviewState(
+        input({ refresh: { status: 'skipped', skippedReason: 'disconnected' } })
+      ).title
+    ).toBe('Host disconnected')
   })
 })
 
@@ -289,21 +271,6 @@ describe('shouldShowChecksPanelPublishBranchAction', () => {
     ).toBe(true)
   })
 
-  it('uses remote status even when provider eligibility has a separate blocker', () => {
-    expect(
-      shouldShowChecksPanelPublishBranchAction({
-        hostedReviewBlockedReason: undefined,
-        hasUpstream: false
-      })
-    ).toBe(true)
-    expect(
-      shouldShowChecksPanelPublishBranchAction({
-        hostedReviewBlockedReason: 'unsupported_provider',
-        hasUpstream: false
-      })
-    ).toBe(true)
-  })
-
   it('does not show publish when HEAD is detached', () => {
     expect(
       shouldShowChecksPanelPublishBranchAction({
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-empty-state.ts b/src/renderer/src/components/right-sidebar/checks-panel-empty-state.ts
index 78dd6610ae4..6679a57fa3f 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel-empty-state.ts
+++ b/src/renderer/src/components/right-sidebar/checks-panel-empty-state.ts
@@ -1,40 +1,49 @@
 import type { HostedReviewCreationBlockedReason } from '../../../../shared/hosted-review'
-import type { PRRefreshUpstreamErrorType } from '../../../../shared/types'
 import { translate } from '@/i18n/i18n'
-import { getGitHubUnavailableEmptyStateCopy } from './github-refresh-error-copy'
+import {
+  autoRetrySchedule,
+  capitalizeReviewLabel,
+  confirmedComposerMode,
+  ELIGIBILITY_SAFETY_BLOCKERS,
+  isBranchBlocker,
+  isHardRefreshError,
+  isTransientRefreshFailure,
+  workflowActionForComposer,
+  type ChecksPanelReviewState,
+  type ChecksPanelReviewStateInput
+} from './checks-panel-review-state-model'
+import {
+  concurrentLookupDetail,
+  hardRefreshErrorState,
+  skippedRefreshState,
+  transientRefreshState
+} from './checks-panel-review-copy'
+import { branchBlockerState, safetyBlockerState } from './checks-panel-blocker-copy'
 
-type PRRefreshStatus = 'queued' | 'in-flight' | 'paused' | 'error' | 'skipped' | undefined
-
-type ChecksPanelEmptyStateInput = {
-  operationLabel: string | null
-  prRefreshStatus: PRRefreshStatus
-  // Why: lets the error empty-state attribute a GitHub outage (5xx/network/rate
-  // limit) instead of showing generic "could not refresh" copy that reads like
-  // an Orca bug.
-  prRefreshErrorType?: PRRefreshUpstreamErrorType
-  hostedReviewBlockedReason: HostedReviewCreationBlockedReason | undefined
-  hasUpstream: boolean | undefined
-  hasCurrentBranch?: boolean
-  reviewLabel?: 'pull request' | 'merge request'
-  reviewShortLabel?: 'PR' | 'MR'
-  hasAmbiguousGitHubHostedReview?: boolean
-}
-
-type ChecksPanelEmptyStateCopy = {
-  title: string
-  description: string
-}
+export type {
+  ChecksPanelComposerMode,
+  ChecksPanelWorkflowAction,
+  ChecksPanelRecoveryAction,
+  ChecksPanelReviewState,
+  ChecksPanelRefreshInput,
+  ChecksPanelReviewStateInput
+} from './checks-panel-review-state-model'
 
 /**
- * Chooses neutral empty-state copy when GitHub review status is still ambiguous.
+ * One exhaustive selector for the Checks-panel empty state. Copy, composer mode,
+ * workflow action, and recovery actions are decided together — never in separate
+ * branches — so an error, pause, skip, or unknown state can never be rendered as
+ * "No {reviewLabel} found." See docs/design/pr-panel-refresh-guidance.md.
  */
-export function getChecksPanelEmptyStateCopy(
-  input: ChecksPanelEmptyStateInput
-): ChecksPanelEmptyStateCopy {
-  const reviewLabel = input.reviewLabel ?? 'pull request'
-  const reviewShortLabel = input.reviewShortLabel ?? 'PR'
+export function getChecksPanelReviewState(
+  input: ChecksPanelReviewStateInput
+): ChecksPanelReviewState {
+  const { reviewLabel, reviewShortLabel, providerName } = input
+
+  // 0. Operation in progress — never overridden by refresh copy.
   if (input.operationLabel) {
     return {
+      renderReview: false,
       title: translate(
         'auto.components.right.sidebar.checks.panel.empty.state.d77c513c1e',
         '{{value0}} in progress',
@@ -44,142 +53,186 @@ export function getChecksPanelEmptyStateCopy(
         'auto.components.right.sidebar.checks.panel.empty.state.05e4aec17b',
         '{{value0}} checks will be available after the operation completes',
         { value0: reviewShortLabel }
-      )
+      ),
+      composerMode: 'hidden',
+      workflowAction: null,
+      recovery: []
     }
   }
 
-  const blockedReason = input.hostedReviewBlockedReason
-  // Why: a GitHub hosted-review card with no cached PR is ambiguous. Resolve the
-  // whole empty state here so the copy stays stable across a background PR
-  // refresh's lifecycle (idle/queued/in-flight/paused/skipped). Previously only
-  // the idle statuses were handled and active ones fell through to the
-  // publish-branch branch, so the panel flip-flopped between "Branch not
-  // published" and "Pull request status unavailable" as refreshes cycled. Only a
-  // hard refresh error still surfaces a distinct — but equally stable — message.
-  if (input.hasAmbiguousGitHubHostedReview === true) {
-    if (input.prRefreshStatus === 'error') {
-      return (
-        getGitHubUnavailableEmptyStateCopy(input.prRefreshErrorType) ?? {
-          title: translate(
-            'auto.components.right.sidebar.checks.panel.empty.state.5f478ab3d3',
-            'Could not refresh pull request'
-          ),
-          description: translate(
-            'auto.components.right.sidebar.checks.panel.empty.state.2bdd7aaf2d',
-            'GitHub status could not be refreshed. Existing cached data was preserved.'
-          )
-        }
-      )
-    }
+  // 1. Renderable review wins over every empty state.
+  if (input.reviewLookup === 'found') {
     return {
+      renderReview: true,
+      title: '',
+      description: '',
+      composerMode: 'hidden',
+      workflowAction: null,
+      recovery: []
+    }
+  }
+
+  const blockedReason = input.eligibilityBlockedReason
+
+  // 2. Eligibility safety states own their guidance (existing_review is a hard
+  //    create block in the positive-evidence family).
+  if (blockedReason && ELIGIBILITY_SAFETY_BLOCKERS.has(blockedReason)) {
+    return safetyBlockerState(input, blockedReason)
+  }
+
+  // 3. Positive unresolved review evidence: never offer Create / Push & Create.
+  if (input.reviewLookup === 'positive_unresolved' && !isBranchBlocker(blockedReason)) {
+    return {
+      renderReview: false,
       title: translate(
-        'auto.components.right.sidebar.checks.panel.empty.state.3322603418',
-        'Pull request status unavailable'
+        'auto.components.right.sidebar.checks.panel.review.positive.title',
+        '{{reviewLabelCap}} details unavailable',
+        { reviewLabelCap: capitalizeReviewLabel(reviewLabel) }
       ),
       description: translate(
-        'auto.components.right.sidebar.checks.panel.empty.state.b597440265',
-        'Refresh GitHub status for this branch to load checks and review.'
-      )
+        'auto.components.right.sidebar.checks.panel.review.positive.body',
+        'Orca has saved {{reviewLabel}} information for this branch but could not confirm its current status.',
+        { reviewLabel }
+      ),
+      composerMode: 'hidden',
+      workflowAction: null,
+      recovery: input.openReviewUrl ? ['open_review', 'retry'] : ['retry'],
+      openReviewUrl: input.openReviewUrl
     }
   }
 
-  if (
-    shouldShowChecksPanelPublishBranchAction({
-      hostedReviewBlockedReason: blockedReason,
-      hasUpstream: input.hasUpstream,
-      hasCurrentBranch: input.hasCurrentBranch
-    })
-  ) {
-    // Why: a local-only branch cannot have GitHub PR status yet; surfacing a
-    // refresh error here makes a normal pre-publish state look broken.
+  // 4. Actionable creation blockers (publish / sync / auth / needs_push).
+  if (isBranchBlocker(blockedReason)) {
+    return branchBlockerState(
+      input,
+      blockedReason as NonNullable<HostedReviewCreationBlockedReason>
+    )
+  }
+  // A ready Git status reporting no upstream is a publish state even before
+  // eligibility resolves. `hasUpstream === undefined` is unknown, never false.
+  if (input.gitStatusPhase === 'ready' && input.hasUpstream === false && input.hasCurrentBranch) {
+    return branchBlockerState(input, 'no_upstream')
+  }
+
+  // 5. Hard refresh error with no blocker above → hide composer until cleared.
+  if (isHardRefreshError(input.refresh)) {
+    return hardRefreshErrorState(input)
+  }
+
+  // 6. Accepted no-review for the exact context.
+  if (input.reviewLookup === 'not_found') {
+    const detail = isTransientRefreshFailure(input.refresh)
+      ? concurrentLookupDetail(input)
+      : undefined
+    const mode = confirmedComposerMode(input)
     return {
+      renderReview: false,
       title: translate(
-        'auto.components.right.sidebar.checks.panel.empty.state.41252bc53f',
-        'Branch not published'
+        'auto.components.right.sidebar.checks.panel.review.no_review.title',
+        'No {{reviewLabel}} found',
+        { reviewLabel }
       ),
       description: translate(
-        'auto.components.right.sidebar.checks.panel.empty.state.f8543140cc',
-        'Publish this branch before creating a {{value0}}.',
-        { value0: reviewLabel }
-      )
+        'auto.components.right.sidebar.checks.panel.review.no_review.body',
+        'Create a {{reviewLabel}} to start checks and review.',
+        { reviewLabel }
+      ),
+      detail,
+      composerMode: mode,
+      workflowAction: workflowActionForComposer(mode),
+      recovery: detail ? ['retry'] : ['refresh'],
+      ...(detail ? autoRetrySchedule(input) : {})
     }
   }
 
-  if (blockedReason === 'needs_push') {
+  // 7. Transient classified error / rate-limit pause with no accepted result.
+  if (isTransientRefreshFailure(input.refresh)) {
+    const mode = confirmedComposerMode(input)
+    return transientRefreshState(input, mode, workflowActionForComposer(mode))
+  }
+
+  // 8. Active refresh (queued / in-flight) with no accepted result.
+  if (input.refresh?.status === 'queued' || input.refresh?.status === 'in-flight') {
+    const mode = confirmedComposerMode(input)
     return {
+      renderReview: false,
       title: translate(
-        'auto.components.right.sidebar.checks.panel.empty.state.76e15946a9',
-        'Branch has unpushed commits'
+        'auto.components.right.sidebar.checks.panel.review.active.title',
+        'Checking {{reviewLabel}} status',
+        { reviewLabel }
       ),
       description: translate(
-        'auto.components.right.sidebar.checks.panel.empty.state.6ce9d4e069',
-        'Push your branch before creating a {{value0}}.',
-        { value0: reviewLabel }
-      )
+        'auto.components.right.sidebar.checks.panel.review.active.body',
+        'Orca is checking {{provider}} for a {{reviewLabel}} on this branch.',
+        { reviewLabel, provider: providerName }
+      ),
+      composerMode: mode,
+      workflowAction: workflowActionForComposer(mode),
+      recovery: []
     }
   }
 
-  switch (input.prRefreshStatus) {
-    case 'error':
-      return (
-        getGitHubUnavailableEmptyStateCopy(input.prRefreshErrorType) ?? {
-          title: translate(
-            'auto.components.right.sidebar.checks.panel.empty.state.5f478ab3d3',
-            'Could not refresh pull request'
-          ),
-          description: translate(
-            'auto.components.right.sidebar.checks.panel.empty.state.2bdd7aaf2d',
-            'GitHub status could not be refreshed. Existing cached data was preserved.'
-          )
-        }
-      )
-    case 'queued':
-      return {
-        title: translate(
-          'auto.components.right.sidebar.checks.panel.empty.state.938b5606a6',
-          'Checking for pull request'
-        ),
-        description: translate(
-          'auto.components.right.sidebar.checks.panel.empty.state.6ba2440770',
-          'Waiting to refresh GitHub status for this branch'
-        )
-      }
-    case 'in-flight':
-      return {
-        title: translate(
-          'auto.components.right.sidebar.checks.panel.empty.state.938b5606a6',
-          'Checking for pull request'
-        ),
-        description: translate(
-          'auto.components.right.sidebar.checks.panel.empty.state.3d4af82ff4',
-          'Refreshing GitHub status for this branch'
-        )
-      }
-    case 'paused':
-      return {
-        title: translate(
-          'auto.components.right.sidebar.checks.panel.empty.state.7c299df37b',
-          'No pull request found'
-        ),
-        description: translate(
-          'auto.components.right.sidebar.checks.panel.empty.state.d372072df1',
-          'GitHub refresh is paused by the current rate-limit budget'
-        )
-      }
-    case 'skipped':
-    case undefined:
-      return {
-        title: translate(
-          'auto.components.right.sidebar.checks.panel.empty.state.13e1c7d5ed',
-          'No {{value0}} found',
-          { value0: reviewLabel }
-        ),
-        description: translate(
-          'auto.components.right.sidebar.checks.panel.empty.state.5b0cfae9a5',
-          'Create a {{value0}} to start checks and review.',
-          { value0: reviewLabel }
-        )
-      }
+  // 9. Git status loading / failure when upstream is still unknown.
+  if (input.gitStatusPhase === 'loading' && input.hasUpstream === undefined) {
+    return {
+      renderReview: false,
+      title: translate(
+        'auto.components.right.sidebar.checks.panel.review.git_loading.title',
+        'Checking branch status'
+      ),
+      description: translate(
+        'auto.components.right.sidebar.checks.panel.review.git_loading.body',
+        'Orca is checking this branch before showing create or publish actions.'
+      ),
+      composerMode: 'hidden',
+      workflowAction: null,
+      recovery: []
+    }
+  }
+  if (input.gitStatusPhase === 'error' && input.hasUpstream === undefined) {
+    return {
+      renderReview: false,
+      title: translate(
+        'auto.components.right.sidebar.checks.panel.review.git_error.title',
+        'Could not check branch status'
+      ),
+      description: translate(
+        'auto.components.right.sidebar.checks.panel.review.git_error.body',
+        "Orca could not confirm this branch's upstream from this environment. Retry before publishing or creating a {{reviewLabel}}.",
+        { reviewLabel }
+      ),
+      composerMode: 'hidden',
+      workflowAction: null,
+      recovery: ['retry']
+    }
+  }
+
+  // 10. Skipped structural reasons and missing / unknown — status unavailable.
+  if (input.refresh?.status === 'skipped' && input.refresh.skippedReason) {
+    if (input.refresh.skippedReason === 'rate-limit') {
+      const mode = confirmedComposerMode(input)
+      return transientRefreshState(input, mode, workflowActionForComposer(mode))
+    }
+    const skipped = skippedRefreshState(input, input.refresh.skippedReason)
+    if (skipped) {
+      return skipped
+    }
+  }
+  return {
+    renderReview: false,
+    title: translate(
+      'auto.components.right.sidebar.checks.panel.review.unknown.title',
+      '{{reviewLabelCap}} status unavailable',
+      { reviewLabelCap: capitalizeReviewLabel(reviewLabel) }
+    ),
+    description: translate(
+      'auto.components.right.sidebar.checks.panel.review.unknown.body',
+      'Orca has not confirmed the {{reviewLabel}} status for this branch. Retry to check again.',
+      { reviewLabel }
+    ),
+    composerMode: 'hidden',
+    workflowAction: null,
+    recovery: ['retry']
   }
 }
 
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-git-status-snapshot.ts b/src/renderer/src/components/right-sidebar/checks-panel-git-status-snapshot.ts
index 897b93b3e22..78063f3b211 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel-git-status-snapshot.ts
+++ b/src/renderer/src/components/right-sidebar/checks-panel-git-status-snapshot.ts
@@ -13,6 +13,10 @@ export type ChecksPanelGitStatusContextInput = {
   runtimeEnvironmentId: string | null
   repoConnectionId: string | null
   pushTarget: GitPushTarget | null | undefined
+  // Local execution host variant (`wsl:{distro}` vs `host`) so a Windows-host
+  // result never authorizes a WSL context (or another distro), and vice versa.
+  // Null for SSH/runtime contexts, which are already scoped by their host ids.
+  localExecutionScope?: string | null
 }
 
 export type ChecksPanelGitStatusSnapshot = {
@@ -60,6 +64,7 @@ export function buildChecksPanelGitStatusContextKey(
     linkedGiteaPR: input.linkedGiteaPR ?? null,
     runtimeEnvironmentId: input.runtimeEnvironmentId ?? '',
     repoConnectionId: input.repoConnectionId ?? '',
+    localExecutionScope: input.localExecutionScope ?? null,
     pushTarget: input.pushTarget
       ? {
           remoteName: input.pushTarget.remoteName,
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-review-copy.ts b/src/renderer/src/components/right-sidebar/checks-panel-review-copy.ts
new file mode 100644
index 00000000000..b4486bec769
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/checks-panel-review-copy.ts
@@ -0,0 +1,288 @@
+import type { GitHubPRRefreshSkippedReason } from '../../../../shared/types'
+import { translate } from '@/i18n/i18n'
+import { getGitHubUnavailableEmptyStateCopy } from './github-refresh-error-copy'
+import {
+  autoRetrySchedule,
+  capitalizeReviewLabel,
+  isHardRefreshError,
+  isRateLimitRefresh,
+  type ChecksPanelRecoveryAction,
+  type ChecksPanelReviewState,
+  type ChecksPanelReviewStateInput
+} from './checks-panel-review-state-model'
+
+type KeyedCopy = { key: string; fallback: string }
+
+/**
+ * Muted sentence appended beneath a blocker or accepted-no-review body when a
+ * concurrent lookup failure or positive-unresolved evidence is also current.
+ */
+export function concurrentLookupDetail(input: ChecksPanelReviewStateInput): string | undefined {
+  const { reviewLabel, providerName, refresh } = input
+  if (input.reviewLookup === 'positive_unresolved') {
+    return translate(
+      'auto.components.right.sidebar.checks.panel.review.detail.positive',
+      'Orca also has saved {{reviewLabel}} information that it could not verify.',
+      { reviewLabel }
+    )
+  }
+  if (isRateLimitRefresh(refresh)) {
+    return translate(
+      'auto.components.right.sidebar.checks.panel.review.detail.rate_limited',
+      'Orca also could not check {{reviewLabel}} status because {{provider}} is temporarily limiting requests.',
+      { reviewLabel, provider: providerName }
+    )
+  }
+  if (refresh?.errorType === 'network') {
+    return translate(
+      'auto.components.right.sidebar.checks.panel.review.detail.network',
+      'Orca also could not check {{reviewLabel}} status because this environment could not reach {{provider}}.',
+      { reviewLabel, provider: providerName }
+    )
+  }
+  if (refresh?.status === 'error' || isHardRefreshError(refresh)) {
+    return translate(
+      'auto.components.right.sidebar.checks.panel.review.detail.untyped',
+      'Orca also could not confirm whether this branch already has a {{reviewLabel}}.',
+      { reviewLabel }
+    )
+  }
+  return undefined
+}
+
+export function transientRefreshState(
+  input: ChecksPanelReviewStateInput,
+  composerMode: ChecksPanelReviewState['composerMode'],
+  workflowAction: ChecksPanelReviewState['workflowAction']
+): ChecksPanelReviewState {
+  const { reviewLabel, providerName, refresh } = input
+  const schedule = autoRetrySchedule(input)
+  const base = {
+    renderReview: false as const,
+    composerMode,
+    workflowAction,
+    recovery: ['retry'] as ChecksPanelRecoveryAction[],
+    ...schedule
+  }
+  // Why: preserve the upstream GitHub-attributed 5xx copy in the unified state model.
+  const githubUnavailableCopy =
+    refresh?.errorType === 'server_error'
+      ? getGitHubUnavailableEmptyStateCopy(refresh.errorType)
+      : null
+  if (githubUnavailableCopy) {
+    return { ...base, ...githubUnavailableCopy }
+  }
+  if (isRateLimitRefresh(refresh)) {
+    return {
+      ...base,
+      title: translate(
+        'auto.components.right.sidebar.checks.panel.review.paused.title',
+        '{{provider}} refresh paused',
+        { provider: providerName }
+      ),
+      description: translate(
+        'auto.components.right.sidebar.checks.panel.review.paused.body',
+        '{{provider}} is temporarily limiting requests. This can happen even when the displayed API quota is not exhausted.',
+        { provider: providerName }
+      )
+    }
+  }
+  if (refresh?.errorType === 'network') {
+    return {
+      ...base,
+      title: translate(
+        'auto.components.right.sidebar.checks.panel.review.network.title',
+        'Could not reach {{provider}}',
+        { provider: providerName }
+      ),
+      description: translate(
+        'auto.components.right.sidebar.checks.panel.review.network.body',
+        'This environment could not reach {{provider}}. Check its connection, then retry.',
+        { provider: providerName }
+      )
+    }
+  }
+  if (refresh?.errorType === 'unknown') {
+    return {
+      ...base,
+      title: translate(
+        'auto.components.right.sidebar.checks.panel.review.unknown_error.title',
+        'Could not check {{reviewLabel}} status',
+        { reviewLabel }
+      ),
+      description: translate(
+        'auto.components.right.sidebar.checks.panel.review.unknown_error.body',
+        'The lookup failed, so Orca could not confirm whether this branch already has a {{reviewLabel}}.',
+        { reviewLabel }
+      )
+    }
+  }
+  return {
+    ...base,
+    title: translate(
+      'auto.components.right.sidebar.checks.panel.review.untyped.title',
+      '{{reviewLabelCap}} status unavailable',
+      { reviewLabelCap: capitalizeReviewLabel(reviewLabel) }
+    ),
+    description: translate(
+      'auto.components.right.sidebar.checks.panel.review.untyped.body',
+      'Orca could not confirm whether this branch already has a {{reviewLabel}}. Retry to check again.',
+      { reviewLabel }
+    )
+  }
+}
+
+const HARD_ERROR_COPY: Record<
+  'auth' | 'permission' | 'repo_unavailable' | 'gh_unavailable',
+  {
+    title: KeyedCopy
+    body: KeyedCopy
+  }
+> = {
+  auth: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.auth.title',
+      fallback: '{{provider}} authentication failed'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.auth.body',
+      fallback:
+        '{{provider}} could not authenticate the credentials available in this environment. Check the {{provider}} login or environment token, then retry.'
+    }
+  },
+  permission: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.permission.title',
+      fallback: '{{provider}} access denied'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.permission.body',
+      fallback:
+        "The current {{provider}} credentials cannot read this repository's {{reviewLabel}}s. Check the account, token scopes, and repository access, then retry."
+    }
+  },
+  repo_unavailable: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.repo.title',
+      fallback: '{{provider}} repository unavailable'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.repo.body',
+      fallback:
+        '{{provider}} could not resolve or access the repository for the current remote and account. Check the remote and repository access, then retry.'
+    }
+  },
+  gh_unavailable: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.cli.title',
+      fallback: '{{provider}} CLI unavailable'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.cli.body',
+      fallback:
+        'Orca could not run {{provider}} CLI in this environment. Set it up here, then retry.'
+    }
+  }
+}
+
+export function hardRefreshErrorState(input: ChecksPanelReviewStateInput): ChecksPanelReviewState {
+  const { reviewLabel, providerName, refresh } = input
+  const copy =
+    HARD_ERROR_COPY[(refresh?.errorType as keyof typeof HARD_ERROR_COPY) ?? 'gh_unavailable'] ??
+    HARD_ERROR_COPY.gh_unavailable
+  const vars = { provider: providerName, reviewLabel }
+  return {
+    renderReview: false,
+    title: translate(copy.title.key, copy.title.fallback, vars),
+    description: translate(copy.body.key, copy.body.fallback, vars),
+    composerMode: 'hidden',
+    workflowAction: null,
+    recovery: ['retry']
+  }
+}
+
+const SKIPPED_COPY: Partial<
+  Record<
+    GitHubPRRefreshSkippedReason,
+    { title: KeyedCopy; body: KeyedCopy; recovery: ChecksPanelRecoveryAction[] }
+  >
+> = {
+  disconnected: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.skipped.disconnected.title',
+      fallback: 'Host disconnected'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.skipped.disconnected.body',
+      fallback:
+        "This repository's execution host is disconnected, so Orca cannot refresh {{reviewLabel}} status."
+    },
+    recovery: ['retry']
+  },
+  bare: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.skipped.bare.title',
+      fallback: 'Bare repository'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.skipped.bare.body',
+      fallback: 'This repository is bare, so {{reviewLabel}} status is not available here.'
+    },
+    recovery: []
+  },
+  archived: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.skipped.archived.title',
+      fallback: 'Repository archived'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.skipped.archived.body',
+      fallback: 'This repository is archived, so Orca is not refreshing {{reviewLabel}} status.'
+    },
+    recovery: []
+  },
+  'not-git': {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.skipped.not_git.title',
+      fallback: 'Not a Git repository'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.skipped.not_git.body',
+      fallback: 'Orca could not treat this folder as a Git repository for {{reviewLabel}} status.'
+    },
+    recovery: []
+  },
+  remote: {
+    title: {
+      key: 'auto.components.right.sidebar.checks.panel.review.skipped.remote.title',
+      fallback: 'Remote-only context'
+    },
+    body: {
+      key: 'auto.components.right.sidebar.checks.panel.review.skipped.remote.body',
+      fallback:
+        'Orca could not refresh {{reviewLabel}} status for this remote context. Retry after the host is available.'
+    },
+    recovery: ['retry']
+  }
+}
+
+/** Returns the skipped-reason row, or `null` to defer to the missing/unknown row. */
+export function skippedRefreshState(
+  input: ChecksPanelReviewStateInput,
+  skippedReason: GitHubPRRefreshSkippedReason
+): ChecksPanelReviewState | null {
+  const copy = SKIPPED_COPY[skippedReason]
+  if (!copy) {
+    // `fresh` (and any unknown skip) with no accepted result → missing/unknown.
+    return null
+  }
+  const vars = { reviewLabel: input.reviewLabel }
+  return {
+    renderReview: false,
+    title: translate(copy.title.key, copy.title.fallback, vars),
+    description: translate(copy.body.key, copy.body.fallback, vars),
+    composerMode: 'hidden',
+    workflowAction: null,
+    recovery: copy.recovery
+  }
+}
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-review-creation.test.ts b/src/renderer/src/components/right-sidebar/checks-panel-review-creation.test.ts
index 69d1dc32690..4a53eab87b0 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel-review-creation.test.ts
+++ b/src/renderer/src/components/right-sidebar/checks-panel-review-creation.test.ts
@@ -1,9 +1,33 @@
 import { describe, expect, it } from 'vitest'
+import type {
+  HostedReviewCreationBlockedReason,
+  HostedReviewCreationEligibility,
+  HostedReviewLookupOutcome
+} from '../../../../shared/hosted-review'
 import {
+  computeChecksPanelConfirmedReadiness,
+  isChecksPanelCreateEligibilityConfirmable,
+  isChecksPanelHardErrorCleared,
+  isChecksPanelHardRefreshErrorType,
   resolveChecksPanelHostedReviewBaseRef,
-  shouldOpenChecksPanelCreateComposer
+  shouldOpenChecksPanelCreateComposer,
+  type ChecksPanelConfirmedReadinessInput
 } from './checks-panel-review-creation'
 
+function eligibility(
+  overrides: Partial<HostedReviewCreationEligibility> = {}
+): HostedReviewCreationEligibility {
+  return {
+    provider: 'github',
+    review: null,
+    canCreate: true,
+    blockedReason: null,
+    nextAction: null,
+    reviewLookupOutcome: 'not_found',
+    ...overrides
+  }
+}
+
 describe('resolveChecksPanelHostedReviewBaseRef', () => {
   it('prefers the worktree base ref over the repo default', () => {
     expect(
@@ -14,66 +38,70 @@ describe('resolveChecksPanelHostedReviewBaseRef', () => {
     ).toBe('release/1.4')
   })
 
-  it('falls back to the repo base ref when the worktree has no override', () => {
-    expect(
-      resolveChecksPanelHostedReviewBaseRef({
-        worktreeBaseRef: null,
-        repoBaseRef: ' main '
-      })
-    ).toBe('main')
-  })
-
   it('returns null when both inputs are null', () => {
     expect(
-      resolveChecksPanelHostedReviewBaseRef({
-        worktreeBaseRef: null,
-        repoBaseRef: null
-      })
+      resolveChecksPanelHostedReviewBaseRef({ worktreeBaseRef: null, repoBaseRef: null })
     ).toBe(null)
   })
+})
 
-  it('returns null when worktree base ref is whitespace-only', () => {
+describe('isChecksPanelCreateEligibilityConfirmable (shared desktop/mobile floor)', () => {
+  const base = { reviewLookup: 'not_found' as const, hasHardRefreshError: false }
+
+  it('allows canCreate and needs_push when nothing hard-blocks', () => {
+    expect(isChecksPanelCreateEligibilityConfirmable({ ...base, eligibility: eligibility() })).toBe(
+      true
+    )
     expect(
-      resolveChecksPanelHostedReviewBaseRef({
-        worktreeBaseRef: '   ',
-        repoBaseRef: null
+      isChecksPanelCreateEligibilityConfirmable({
+        ...base,
+        eligibility: eligibility({ canCreate: false, blockedReason: 'needs_push' })
       })
-    ).toBe(null)
+    ).toBe(true)
   })
 
-  it('strips origin prefix from the worktree base ref', () => {
+  it('fails closed on every hard-block: null, existing_review, positive, hard error, unavailable', () => {
+    expect(isChecksPanelCreateEligibilityConfirmable({ ...base, eligibility: null })).toBe(false)
     expect(
-      resolveChecksPanelHostedReviewBaseRef({
-        worktreeBaseRef: 'origin/main',
-        repoBaseRef: 'develop'
+      isChecksPanelCreateEligibilityConfirmable({
+        ...base,
+        eligibility: eligibility({ canCreate: false, blockedReason: 'existing_review' })
       })
-    ).toBe('main')
-  })
-
-  it('strips upstream prefix from the repo base ref', () => {
+    ).toBe(false)
     expect(
-      resolveChecksPanelHostedReviewBaseRef({
-        worktreeBaseRef: null,
-        repoBaseRef: 'upstream/develop'
+      isChecksPanelCreateEligibilityConfirmable({
+        ...base,
+        eligibility: eligibility(),
+        reviewLookup: 'positive_unresolved'
       })
-    ).toBe('develop')
+    ).toBe(false)
+    expect(
+      isChecksPanelCreateEligibilityConfirmable({
+        ...base,
+        eligibility: eligibility(),
+        hasHardRefreshError: true
+      })
+    ).toBe(false)
+    expect(
+      isChecksPanelCreateEligibilityConfirmable({
+        ...base,
+        eligibility: eligibility({
+          blockedReason: 'needs_push',
+          reviewLookupOutcome: 'unavailable'
+        })
+      })
+    ).toBe(false)
   })
 })
 
 describe('shouldOpenChecksPanelCreateComposer', () => {
-  it('opens for GitLab MR creation eligibility', () => {
+  it('opens for creation eligibility', () => {
     expect(
       shouldOpenChecksPanelCreateComposer({
         activeReview: null,
         isFolder: false,
-        branch: 'feature/gitlab-mr',
-        hostedReviewCreation: {
-          provider: 'gitlab',
-          review: null,
-          canCreate: true,
-          blockedReason: null,
-          nextAction: null
-        }
+        branch: 'feature/x',
+        hostedReviewCreation: eligibility({ canCreate: true })
       })
     ).toBe(true)
   })
@@ -83,66 +111,281 @@ describe('shouldOpenChecksPanelCreateComposer', () => {
       shouldOpenChecksPanelCreateComposer({
         activeReview: null,
         isFolder: false,
-        branch: 'feature/gitlab-mr',
-        hostedReviewCreation: {
-          provider: 'gitlab',
-          review: null,
-          canCreate: false,
-          blockedReason: 'needs_push',
-          nextAction: 'push'
-        }
+        branch: 'feature/x',
+        hostedReviewCreation: eligibility({ canCreate: false, blockedReason: 'needs_push' })
       })
     ).toBe(true)
   })
 
-  it('does not open when an active review exists', () => {
+  it('does not open on positive unresolved review evidence', () => {
     expect(
       shouldOpenChecksPanelCreateComposer({
-        activeReview: { provider: 'github', number: 123 },
+        activeReview: null,
         isFolder: false,
-        branch: 'feature/test',
-        hostedReviewCreation: {
-          provider: 'github',
-          review: null,
-          canCreate: true,
-          blockedReason: null,
-          nextAction: null
-        }
+        branch: 'feature/x',
+        hostedReviewCreation: eligibility({ canCreate: false, blockedReason: 'needs_push' }),
+        reviewLookup: 'positive_unresolved'
       })
     ).toBe(false)
   })
 
-  it('does not open for folder repos', () => {
+  it('does not open during a hard refresh error', () => {
+    expect(
+      shouldOpenChecksPanelCreateComposer({
+        activeReview: null,
+        isFolder: false,
+        branch: 'feature/x',
+        hostedReviewCreation: eligibility({ canCreate: true }),
+        hasHardRefreshError: true
+      })
+    ).toBe(false)
+  })
+
+  it('does not open when a review already exists', () => {
+    expect(
+      shouldOpenChecksPanelCreateComposer({
+        activeReview: null,
+        isFolder: false,
+        branch: 'feature/x',
+        hostedReviewCreation: eligibility({ canCreate: false, blockedReason: 'existing_review' })
+      })
+    ).toBe(false)
+  })
+
+  it('does not open for folders or empty branches', () => {
     expect(
       shouldOpenChecksPanelCreateComposer({
         activeReview: null,
         isFolder: true,
-        branch: 'feature/test',
-        hostedReviewCreation: {
-          provider: 'github',
-          review: null,
-          canCreate: true,
-          blockedReason: null,
-          nextAction: null
-        }
+        branch: 'feature/x',
+        hostedReviewCreation: eligibility()
       })
     ).toBe(false)
-  })
-
-  it('does not open when branch is empty', () => {
     expect(
       shouldOpenChecksPanelCreateComposer({
         activeReview: null,
         isFolder: false,
         branch: '',
-        hostedReviewCreation: {
-          provider: 'github',
-          review: null,
-          canCreate: true,
-          blockedReason: null,
-          nextAction: null
-        }
+        hostedReviewCreation: eligibility()
       })
     ).toBe(false)
   })
 })
+
+describe('isChecksPanelHardRefreshErrorType', () => {
+  it('flags the four hard error types', () => {
+    for (const t of ['auth', 'permission', 'repo_unavailable', 'gh_unavailable']) {
+      expect(isChecksPanelHardRefreshErrorType(t)).toBe(true)
+    }
+  })
+  it('does not flag transient types or undefined', () => {
+    for (const t of ['rate_limited', 'network', 'unknown']) {
+      expect(isChecksPanelHardRefreshErrorType(t)).toBe(false)
+    }
+    expect(isChecksPanelHardRefreshErrorType(undefined)).toBe(false)
+  })
+})
+
+describe('computeChecksPanelConfirmedReadiness', () => {
+  const NOW = 1_000_000
+  function readiness(
+    overrides: Partial<ChecksPanelConfirmedReadinessInput> = {}
+  ): ChecksPanelConfirmedReadinessInput {
+    return {
+      contextKeyMatches: true,
+      eligibility: { canCreate: true, blockedReason: null, reviewLookupOutcome: 'not_found' },
+      eligibilityCompletedAt: NOW - 1_000,
+      eligibilityRequestStartedAt: NOW - 2_000,
+      reviewLookup: 'not_found',
+      hardErrorObservedAt: undefined,
+      gitSnapshotMatches: true,
+      now: NOW,
+      ...overrides
+    }
+  }
+
+  it('confirms fresh, matching eligibility', () => {
+    expect(computeChecksPanelConfirmedReadiness(readiness())).toEqual({
+      confirmed: true,
+      needsPush: false
+    })
+  })
+
+  it('confirms needs_push as the Push & Create path', () => {
+    expect(
+      computeChecksPanelConfirmedReadiness(
+        readiness({
+          eligibility: {
+            canCreate: false,
+            blockedReason: 'needs_push',
+            reviewLookupOutcome: 'not_found'
+          }
+        })
+      )
+    ).toEqual({ confirmed: true, needsPush: true })
+  })
+
+  it('drops confirmed when the context key does not match', () => {
+    expect(
+      computeChecksPanelConfirmedReadiness(readiness({ contextKeyMatches: false })).confirmed
+    ).toBe(false)
+  })
+
+  it('drops confirmed on positive unresolved and existing_review', () => {
+    expect(
+      computeChecksPanelConfirmedReadiness(readiness({ reviewLookup: 'positive_unresolved' }))
+        .confirmed
+    ).toBe(false)
+    expect(
+      computeChecksPanelConfirmedReadiness(
+        readiness({
+          eligibility: {
+            canCreate: false,
+            blockedReason: 'existing_review',
+            reviewLookupOutcome: 'found'
+          }
+        })
+      ).confirmed
+    ).toBe(false)
+  })
+
+  it('drops confirmed when eligibility is older than 5 minutes', () => {
+    expect(
+      computeChecksPanelConfirmedReadiness(
+        readiness({ eligibilityCompletedAt: NOW - 5 * 60_000 - 1 })
+      ).confirmed
+    ).toBe(false)
+  })
+
+  it('drops confirmed when the git snapshot no longer matches', () => {
+    expect(
+      computeChecksPanelConfirmedReadiness(readiness({ gitSnapshotMatches: false })).confirmed
+    ).toBe(false)
+  })
+
+  it('preserves confirmed across a transient refresh failure once past the error', () => {
+    // The panel keeps the last confirmed eligibility snapshot; a transient
+    // failure (no hard error observed) must not drop confirmed.
+    expect(
+      computeChecksPanelConfirmedReadiness(
+        readiness({ hardErrorObservedAt: undefined, reviewLookup: 'not_found' })
+      )
+    ).toEqual({ confirmed: true, needsPush: false })
+  })
+
+  describe('hard error clearing', () => {
+    it('clears when the request started strictly after the error with an accepted outcome', () => {
+      expect(
+        computeChecksPanelConfirmedReadiness(
+          readiness({
+            hardErrorObservedAt: NOW - 3_000,
+            eligibilityRequestStartedAt: NOW - 2_000,
+            eligibility: { canCreate: true, blockedReason: null, reviewLookupOutcome: 'not_found' }
+          })
+        ).confirmed
+      ).toBe(true)
+    })
+
+    it('does not clear for an in-flight request that started before the error', () => {
+      expect(
+        computeChecksPanelConfirmedReadiness(
+          readiness({ hardErrorObservedAt: NOW - 1_500, eligibilityRequestStartedAt: NOW - 2_000 })
+        ).confirmed
+      ).toBe(false)
+    })
+
+    it('does not clear on a late unavailable fallback', () => {
+      expect(
+        computeChecksPanelConfirmedReadiness(
+          readiness({
+            hardErrorObservedAt: NOW - 3_000,
+            eligibilityRequestStartedAt: NOW - 2_000,
+            eligibility: {
+              canCreate: false,
+              blockedReason: 'no_upstream',
+              reviewLookupOutcome: 'unavailable'
+            }
+          })
+        ).confirmed
+      ).toBe(false)
+    })
+  })
+})
+
+describe('isChecksPanelHardErrorCleared', () => {
+  const NOW = 1_000_000
+  function cleared(
+    overrides: Partial<ChecksPanelConfirmedReadinessInput> = {}
+  ): ChecksPanelConfirmedReadinessInput {
+    return {
+      contextKeyMatches: true,
+      eligibility: { canCreate: true, blockedReason: null, reviewLookupOutcome: 'not_found' },
+      eligibilityCompletedAt: NOW - 1_000,
+      eligibilityRequestStartedAt: NOW - 2_000,
+      reviewLookup: 'not_found',
+      hardErrorObservedAt: NOW - 3_000,
+      gitSnapshotMatches: true,
+      now: NOW,
+      ...overrides
+    }
+  }
+
+  it('is cleared (true) when no hard error is observed', () => {
+    expect(isChecksPanelHardErrorCleared(cleared({ hardErrorObservedAt: undefined }))).toBe(true)
+  })
+
+  it('stays blocked while only a queued/in-flight retry replaced the error', () => {
+    // No request that both started after the error and settled with an accepted
+    // outcome, so Create must not flap back.
+    expect(isChecksPanelHardErrorCleared(cleared({ eligibilityRequestStartedAt: undefined }))).toBe(
+      false
+    )
+  })
+
+  it('stays blocked for a request that started before the error', () => {
+    expect(
+      isChecksPanelHardErrorCleared(
+        cleared({ hardErrorObservedAt: NOW - 1_000, eligibilityRequestStartedAt: NOW - 2_000 })
+      )
+    ).toBe(false)
+  })
+
+  it('stays blocked when the clearing request is for a different context', () => {
+    expect(isChecksPanelHardErrorCleared(cleared({ contextKeyMatches: false }))).toBe(false)
+  })
+
+  it('stays blocked on an unavailable outcome even if the request started after', () => {
+    expect(
+      isChecksPanelHardErrorCleared(
+        cleared({
+          eligibility: {
+            canCreate: false,
+            blockedReason: 'no_upstream',
+            reviewLookupOutcome: 'unavailable'
+          }
+        })
+      )
+    ).toBe(false)
+  })
+
+  it('clears when a later request settles found or not_found', () => {
+    expect(isChecksPanelHardErrorCleared(cleared())).toBe(true)
+    expect(
+      isChecksPanelHardErrorCleared(
+        cleared({
+          eligibility: {
+            canCreate: false,
+            blockedReason: 'existing_review',
+            reviewLookupOutcome: 'found'
+          }
+        })
+      )
+    ).toBe(true)
+  })
+})
+
+// Type-only usage to keep the imports meaningful across refactors.
+const _blocked: HostedReviewCreationBlockedReason = null
+const _outcome: HostedReviewLookupOutcome = 'not_found'
+void _blocked
+void _outcome
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-review-creation.ts b/src/renderer/src/components/right-sidebar/checks-panel-review-creation.ts
index 11e42d40fe1..95c9ccfde97 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel-review-creation.ts
+++ b/src/renderer/src/components/right-sidebar/checks-panel-review-creation.ts
@@ -1,5 +1,14 @@
-import type { HostedReviewCreationEligibility } from '../../../../shared/hosted-review'
+import type {
+  HostedReviewCreationBlockedReason,
+  HostedReviewCreationEligibility,
+  HostedReviewLookupOutcome
+} from '../../../../shared/hosted-review'
+import type { PRRefreshErrorType } from '../../../../shared/types'
 import { normalizeHostedReviewBaseRef } from '../../../../shared/hosted-review-refs'
+import type { ChecksPanelReviewLookup } from './checks-panel-review-lookup-authority'
+// Single source of truth for the hard-refresh error set, shared with the
+// review-state model so the composer gate and empty-state selector cannot drift.
+import { HARD_REFRESH_ERROR_TYPES } from './checks-panel-review-state-model'
 
 export function resolveChecksPanelHostedReviewBaseRef(input: {
   worktreeBaseRef?: string | null
@@ -14,17 +23,160 @@ function normalizeChecksPanelHostedReviewBaseRef(ref: string | null | undefined)
   return normalizedRef || null
 }
 
+/**
+ * Shared create-eligibility floor for the desktop confirmed gate and the
+ * mobile-shared composer gate. Create / Push & Create is impossible when review
+ * existence cannot be proven no-review: positive unresolved evidence, a current
+ * hard refresh error, `existing_review`, or an `unavailable` existing-review
+ * lookup all fail closed. Otherwise it allows the `canCreate` / `needs_push`
+ * paths. Both callers route through this so their hard-block semantics cannot
+ * drift; the desktop confirmed gate layers freshness/context checks on top.
+ */
+export function isChecksPanelCreateEligibilityConfirmable(input: {
+  eligibility: Pick<
+    HostedReviewCreationEligibility,
+    'canCreate' | 'blockedReason' | 'reviewLookupOutcome'
+  > | null
+  reviewLookup: ChecksPanelReviewLookup
+  hasHardRefreshError: boolean
+}): boolean {
+  const eligibility = input.eligibility
+  if (!eligibility || eligibility.blockedReason === 'existing_review') {
+    return false
+  }
+  if (input.reviewLookup === 'positive_unresolved' || input.hasHardRefreshError) {
+    return false
+  }
+  // An `unavailable` existing-review lookup could be hiding a real PR. Block even
+  // the Push & Create (needs_push) path, which would otherwise slip through the
+  // canCreate check below with review existence unproven.
+  if (eligibility.reviewLookupOutcome === 'unavailable') {
+    return false
+  }
+  return eligibility.canCreate === true || eligibility.blockedReason === 'needs_push'
+}
+
+/**
+ * Confirmed-only composer gate shared with mobile. Delegates the hard-block
+ * decision to {@link isChecksPanelCreateEligibilityConfirmable} so the desktop
+ * confirmed gate and this mobile-shared gate cannot drift. Phase 1 adds no
+ * provisional or draft-preserve path.
+ */
 export function shouldOpenChecksPanelCreateComposer(input: {
   activeReview: unknown | null
   isFolder: boolean
   branch: string
   hostedReviewCreation: HostedReviewCreationEligibility | null
+  reviewLookup?: ChecksPanelReviewLookup
+  hasHardRefreshError?: boolean
 }): boolean {
-  return (
-    !input.activeReview &&
-    !input.isFolder &&
-    Boolean(input.branch) &&
-    (input.hostedReviewCreation?.canCreate === true ||
-      input.hostedReviewCreation?.blockedReason === 'needs_push')
-  )
+  if (input.activeReview || input.isFolder || !input.branch) {
+    return false
+  }
+  return isChecksPanelCreateEligibilityConfirmable({
+    eligibility: input.hostedReviewCreation,
+    reviewLookup: input.reviewLookup ?? 'unknown',
+    hasHardRefreshError: input.hasHardRefreshError === true
+  })
 }
+
+const CONFIRMED_ELIGIBILITY_MAX_AGE_MS = 5 * 60_000
+
+export function isChecksPanelHardRefreshErrorType(errorType: string | undefined): boolean {
+  return errorType != null && HARD_REFRESH_ERROR_TYPES.has(errorType as PRRefreshErrorType)
+}
+
+export type ChecksPanelConfirmedReadiness = {
+  confirmed: boolean
+  /** The confirmed path is Push & Create rather than plain Create. */
+  needsPush: boolean
+}
+
+export type ChecksPanelConfirmedReadinessInput = {
+  /** The eligibility result's context key equals the panel's current context. */
+  contextKeyMatches: boolean
+  eligibility: Pick<
+    HostedReviewCreationEligibility,
+    'canCreate' | 'blockedReason' | 'reviewLookupOutcome'
+  > | null
+  /** Wall-clock time the eligibility result settled. */
+  eligibilityCompletedAt?: number
+  /** Wall-clock time the eligibility request that produced the result started. */
+  eligibilityRequestStartedAt?: number
+  reviewLookup: ChecksPanelReviewLookup
+  /**
+   * Observation time of the most recent hard refresh error for this context, or
+   * undefined when no hard error is current.
+   */
+  hardErrorObservedAt?: number
+  /**
+   * Whether the Git snapshot used for the eligibility still matches current HEAD,
+   * branch, upstream/ahead/behind/dirty, base, and execution-host fields.
+   */
+  gitSnapshotMatches: boolean
+  now: number
+}
+
+const NOT_CONFIRMED: ChecksPanelConfirmedReadiness = { confirmed: false, needsPush: false }
+
+/**
+ * A hard error is cleared only by an eligibility request that started strictly
+ * after the error was observed, completed for the same exact context with a
+ * `found` / `not_found` lookup outcome, with no newer hard error since. A late
+ * `unavailable` fallback or an already-in-flight request cannot clear it.
+ *
+ * Exported so the panel can keep the hard-error block sticky across
+ * `queued` / `in-flight` auto-retries (which drop `status: 'error'` and would
+ * otherwise let Create flap back) until this predicate says it is cleared.
+ */
+export function isChecksPanelHardErrorCleared(input: ChecksPanelConfirmedReadinessInput): boolean {
+  if (input.hardErrorObservedAt === undefined) {
+    return true
+  }
+  const startedAt = input.eligibilityRequestStartedAt
+  if (startedAt === undefined || !(startedAt > input.hardErrorObservedAt)) {
+    return false
+  }
+  if (!input.contextKeyMatches) {
+    return false
+  }
+  const outcome: HostedReviewLookupOutcome | undefined = input.eligibility?.reviewLookupOutcome
+  return outcome === 'found' || outcome === 'not_found'
+}
+
+/**
+ * Confirmed readiness for the exact context. Any failed check drops confirmed
+ * immediately; transient refresh failures never appear here (the caller only
+ * passes a hard error observation, never a transient one).
+ */
+export function computeChecksPanelConfirmedReadiness(
+  input: ChecksPanelConfirmedReadinessInput
+): ChecksPanelConfirmedReadiness {
+  const eligibility = input.eligibility
+  if (!input.contextKeyMatches) {
+    return NOT_CONFIRMED
+  }
+  // Share the hard-block floor with the mobile-shared gate; an uncleared hard
+  // error is folded in as the `hasHardRefreshError` input so the two cannot drift.
+  if (
+    !isChecksPanelCreateEligibilityConfirmable({
+      eligibility,
+      reviewLookup: input.reviewLookup,
+      hasHardRefreshError: !isChecksPanelHardErrorCleared(input)
+    })
+  ) {
+    return NOT_CONFIRMED
+  }
+  // Freshness: eligibility must be recent and its Git snapshot must still match.
+  if (
+    input.eligibilityCompletedAt === undefined ||
+    input.now - input.eligibilityCompletedAt > CONFIRMED_ELIGIBILITY_MAX_AGE_MS ||
+    !input.gitSnapshotMatches
+  ) {
+    return NOT_CONFIRMED
+  }
+  return { confirmed: true, needsPush: eligibility?.blockedReason === 'needs_push' }
+}
+
+// Re-exported for callers that need the blocker type alongside the gate.
+export type { HostedReviewCreationBlockedReason }
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-review-lookup-authority.test.ts b/src/renderer/src/components/right-sidebar/checks-panel-review-lookup-authority.test.ts
new file mode 100644
index 00000000000..36a814a930c
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/checks-panel-review-lookup-authority.test.ts
@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest'
+import {
+  isRenderableChecksPanelReviewDetails,
+  normalizeTrustedReviewUrl,
+  resolveChecksPanelReviewLookup
+} from './checks-panel-review-lookup-authority'
+
+const EMPTY = {
+  pr: null,
+  prCachedHasPR: null,
+  hostedReview: null
+} as const
+
+describe('resolveChecksPanelReviewLookup', () => {
+  it('returns found with a trusted URL when PR details are renderable', () => {
+    expect(
+      resolveChecksPanelReviewLookup({
+        ...EMPTY,
+        pr: { number: 42, url: 'https://github.com/o/r/pull/42' }
+      })
+    ).toEqual({ state: 'found', openReviewUrl: 'https://github.com/o/r/pull/42' })
+  })
+
+  it('does not treat a summary without a positive number as found', () => {
+    expect(
+      resolveChecksPanelReviewLookup({
+        ...EMPTY,
+        pr: { number: 0, url: 'https://github.com/o/r/pull/0' },
+        hostedReview: { provider: 'github', url: 'https://github.com/o/r/pull/1', number: 1 }
+      }).state
+    ).toBe('positive_unresolved')
+  })
+
+  it('classifies a github hosted-review card with no PR cache as positive_unresolved', () => {
+    // Replaces the old hasAmbiguousGitHubHostedReview boolean.
+    expect(
+      resolveChecksPanelReviewLookup({
+        ...EMPTY,
+        prCachedHasPR: null,
+        hostedReview: { provider: 'github', number: 7, url: 'https://github.com/o/r/pull/7' }
+      })
+    ).toEqual({ state: 'positive_unresolved', openReviewUrl: 'https://github.com/o/r/pull/7' })
+  })
+
+  it('keeps positive evidence over an accepted null no-PR entry (conflict)', () => {
+    expect(
+      resolveChecksPanelReviewLookup({
+        ...EMPTY,
+        prCachedHasPR: false,
+        linkedReviewNumber: 5
+      }).state
+    ).toBe('positive_unresolved')
+  })
+
+  it('returns not_found for an accepted no-PR cache entry', () => {
+    expect(resolveChecksPanelReviewLookup({ ...EMPTY, prCachedHasPR: false })).toEqual({
+      state: 'not_found',
+      openReviewUrl: null
+    })
+  })
+
+  it('returns not_found for eligibility not_found', () => {
+    expect(
+      resolveChecksPanelReviewLookup({
+        ...EMPTY,
+        eligibilityReviewLookupOutcome: 'not_found'
+      }).state
+    ).toBe('not_found')
+  })
+
+  it('treats eligibility found as positive_unresolved when no renderable details', () => {
+    expect(
+      resolveChecksPanelReviewLookup({
+        ...EMPTY,
+        eligibilityReviewLookupOutcome: 'found',
+        eligibilityReview: { url: 'https://gitlab.com/o/r/-/merge_requests/3' }
+      })
+    ).toEqual({
+      state: 'positive_unresolved',
+      openReviewUrl: 'https://gitlab.com/o/r/-/merge_requests/3'
+    })
+  })
+
+  it('returns unknown for a missing entry and unavailable eligibility', () => {
+    expect(
+      resolveChecksPanelReviewLookup({
+        ...EMPTY,
+        prCachedHasPR: null,
+        eligibilityReviewLookupOutcome: 'unavailable'
+      }).state
+    ).toBe('unknown')
+  })
+
+  it('does not offer Open Review for a non-http url', () => {
+    expect(
+      resolveChecksPanelReviewLookup({
+        ...EMPTY,
+        hostedReview: { provider: 'github', number: 9, url: 'javascript:alert(1)' }
+      })
+    ).toEqual({ state: 'positive_unresolved', openReviewUrl: null })
+  })
+})
+
+describe('normalizeTrustedReviewUrl', () => {
+  it('accepts http and https', () => {
+    expect(normalizeTrustedReviewUrl(' https://x.test/pull/1 ')).toBe('https://x.test/pull/1')
+    expect(normalizeTrustedReviewUrl('http://x.test/pull/1')).toBe('http://x.test/pull/1')
+  })
+
+  it('rejects empty and non-web schemes', () => {
+    expect(normalizeTrustedReviewUrl(null)).toBe(null)
+    expect(normalizeTrustedReviewUrl('')).toBe(null)
+    expect(normalizeTrustedReviewUrl('ftp://x.test')).toBe(null)
+    expect(normalizeTrustedReviewUrl('file:///etc/passwd')).toBe(null)
+    expect(normalizeTrustedReviewUrl('not a url')).toBe(null)
+  })
+
+  it('rejects credential-bearing URLs so tokens never reach the browser/shell', () => {
+    expect(normalizeTrustedReviewUrl('https://user:token@git.test/repo/pull/1')).toBe(null)
+    expect(normalizeTrustedReviewUrl('https://user@git.test/repo/pull/1')).toBe(null)
+  })
+})
+
+describe('isRenderableChecksPanelReviewDetails', () => {
+  it('requires a positive number', () => {
+    expect(isRenderableChecksPanelReviewDetails({ number: 1 })).toBe(true)
+    expect(isRenderableChecksPanelReviewDetails({ number: 0 })).toBe(false)
+    expect(isRenderableChecksPanelReviewDetails(null)).toBe(false)
+  })
+})
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-review-lookup-authority.ts b/src/renderer/src/components/right-sidebar/checks-panel-review-lookup-authority.ts
new file mode 100644
index 00000000000..55d24fefd39
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/checks-panel-review-lookup-authority.ts
@@ -0,0 +1,120 @@
+import type { HostedReviewLookupOutcome } from '../../../../shared/hosted-review'
+import { isPositiveHostedReviewNumber } from '../../../../shared/hosted-review'
+
+/**
+ * Four-state review evidence model for the Checks panel. Replaces the single
+ * `hasAmbiguousGitHubHostedReview` Boolean, which collapsed materially different
+ * states (missing lookup, failed lookup, positive-but-unrenderable evidence).
+ *
+ * - `found`: current review details are renderable — leave the empty state.
+ * - `positive_unresolved`: a review is known to exist but details are not
+ *   renderable. Never offer Create / Push & Create; prefer trusted Open Review.
+ * - `not_found`: an accepted no-review result for the exact context.
+ * - `unknown`: no accepted positive or no-review result (missing entry, failed
+ *   or skipped lookup, in-flight).
+ */
+export type ChecksPanelReviewLookup = 'found' | 'positive_unresolved' | 'not_found' | 'unknown'
+
+type ReviewLookupNumberLike = number | null | undefined
+
+export type ChecksPanelReviewLookupInput = {
+  /**
+   * Renderable review details for the exact context (GitHub `PRInfo` payload or
+   * equivalent). Treated as renderable only when it carries a usable identity.
+   */
+  pr: { number?: ReviewLookupNumberLike; url?: string | null } | null | undefined
+  /**
+   * Tri-state from the PR cache entry: `true` = has PR, `false` = accepted
+   * no-PR, `null` = no accepted entry (missing / never fetched). Distinguishes an
+   * accepted no-review outcome from a missing lookup.
+   */
+  prCachedHasPR: boolean | null
+  /** Positive hosted-review cache for the exact context, when present. */
+  hostedReview:
+    | { provider?: string | null; number?: ReviewLookupNumberLike; url?: string | null }
+    | null
+    | undefined
+  /** Durable linked review number for the exact context. */
+  linkedReviewNumber?: ReviewLookupNumberLike
+  /** Settled eligibility lookup outcome for the exact context. */
+  eligibilityReviewLookupOutcome?: HostedReviewLookupOutcome | null
+  /** Eligibility review summary (may be summary-only). */
+  eligibilityReview?: { number?: ReviewLookupNumberLike; url?: string | null } | null
+}
+
+export type ChecksPanelReviewLookupResult = {
+  state: ChecksPanelReviewLookup
+  /** Trusted http(s) URL for Open Review, when one is known; else null. */
+  openReviewUrl: string | null
+}
+
+/**
+ * Returns the URL only when it is a plain http(s) link with no embedded
+ * credentials, so a credential-bearing or non-web value never reaches an Open
+ * Review affordance (and never lands in browser history / shell logs).
+ */
+export function normalizeTrustedReviewUrl(url: string | null | undefined): string | null {
+  if (!url) {
+    return null
+  }
+  const trimmed = url.trim()
+  let parsed: URL
+  try {
+    parsed = new URL(trimmed)
+  } catch {
+    return null
+  }
+  // Reject non-web schemes and any userinfo (`user:token@host`) — a prefix regex
+  // alone would forward embedded credentials to the browser/shell.
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return null
+  }
+  if (parsed.username !== '' || parsed.password !== '') {
+    return null
+  }
+  return trimmed
+}
+
+/**
+ * Review details render the normal review chrome only with a usable identity: a
+ * positive review number. A provider-neutral summary without renderable details
+ * maps to `positive_unresolved`, not `found`.
+ */
+export function isRenderableChecksPanelReviewDetails(
+  pr: { number?: ReviewLookupNumberLike } | null | undefined
+): boolean {
+  return pr != null && isPositiveHostedReviewNumber(pr.number)
+}
+
+export function resolveChecksPanelReviewLookup(
+  input: ChecksPanelReviewLookupInput
+): ChecksPanelReviewLookupResult {
+  if (isRenderableChecksPanelReviewDetails(input.pr)) {
+    return {
+      state: 'found',
+      openReviewUrl: normalizeTrustedReviewUrl(input.pr?.url)
+    }
+  }
+
+  // Positive evidence wins over an accepted null no-PR entry: a conflict must
+  // stay `positive_unresolved` until a newer accepted result clears it, never
+  // collapse to "no PR."
+  const openReviewUrl =
+    normalizeTrustedReviewUrl(input.hostedReview?.url) ??
+    normalizeTrustedReviewUrl(input.eligibilityReview?.url)
+  const hasPositiveEvidence =
+    isPositiveHostedReviewNumber(input.linkedReviewNumber) ||
+    isPositiveHostedReviewNumber(input.hostedReview?.number) ||
+    isPositiveHostedReviewNumber(input.eligibilityReview?.number) ||
+    input.eligibilityReviewLookupOutcome === 'found' ||
+    (input.hostedReview != null && openReviewUrl !== null)
+  if (hasPositiveEvidence) {
+    return { state: 'positive_unresolved', openReviewUrl }
+  }
+
+  if (input.prCachedHasPR === false || input.eligibilityReviewLookupOutcome === 'not_found') {
+    return { state: 'not_found', openReviewUrl: null }
+  }
+
+  return { state: 'unknown', openReviewUrl: null }
+}
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-review-state-model.ts b/src/renderer/src/components/right-sidebar/checks-panel-review-state-model.ts
new file mode 100644
index 00000000000..4b43615ebd9
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/checks-panel-review-state-model.ts
@@ -0,0 +1,165 @@
+import type { HostedReviewCreationBlockedReason } from '../../../../shared/hosted-review'
+import type { GitHubPRRefreshSkippedReason, PRRefreshErrorType } from '../../../../shared/types'
+import type { ChecksPanelReviewLookup } from './checks-panel-review-lookup-authority'
+
+/**
+ * Composer visibility the panel should render. Phase 1 never *opens* a new
+ * composer from a refresh failure — `confirmed_open` / `needs_push_open` mean an
+ * already-confirmed composer stays open. (Phase 2's disabled draft-preserve mode
+ * is intentionally absent until that phase ships.)
+ */
+export type ChecksPanelComposerMode = 'hidden' | 'confirmed_open' | 'needs_push_open'
+
+export type ChecksPanelWorkflowAction =
+  | 'create'
+  | 'push_and_create'
+  | 'publish_branch'
+  | 'sync_branch'
+  | 'authenticate'
+  | null
+
+export type ChecksPanelRecoveryAction = 'retry' | 'refresh' | 'open_review'
+
+export type ChecksPanelReviewState = {
+  /** True only for `reviewLookup: found` — the caller renders review chrome. */
+  renderReview: boolean
+  title: string
+  description: string
+  /** One muted sentence appended beneath the body (concurrent lookup failure). */
+  detail?: string
+  composerMode: ChecksPanelComposerMode
+  workflowAction: ChecksPanelWorkflowAction
+  recovery: ChecksPanelRecoveryAction[]
+  openReviewUrl?: string | null
+  /** Drives "Orca will retry at {time}"; only when a future auto-retry exists. */
+  autoRetryAt?: number
+  /** Retry button stays disabled while now < retryDisabledUntil. */
+  retryDisabledUntil?: number
+}
+
+export type ChecksPanelRefreshInput = {
+  status?: 'queued' | 'in-flight' | 'paused' | 'error' | 'skipped'
+  errorType?: PRRefreshErrorType
+  skippedReason?: GitHubPRRefreshSkippedReason
+  nextAutoRetryAt?: number
+  retryDisabledUntil?: number
+}
+
+export type ChecksPanelReviewStateInput = {
+  operationLabel: string | null
+  reviewLabel: 'pull request' | 'merge request'
+  reviewShortLabel: 'PR' | 'MR'
+  /** Localized provider display name, e.g. "GitHub". */
+  providerName: string
+  /** GitHub gets typed error rows; other providers use neutral copy. */
+  isGitHubProvider: boolean
+  reviewLookup: ChecksPanelReviewLookup
+  openReviewUrl: string | null
+  eligibilityBlockedReason: HostedReviewCreationBlockedReason | undefined
+  /** Confirmed readiness held for the exact context (see review-creation). */
+  confirmedReadiness: boolean
+  /** The confirmed path is the Push & Create workflow rather than plain Create. */
+  confirmedNeedsPush: boolean
+  refresh?: ChecksPanelRefreshInput
+  gitStatusPhase: 'loading' | 'ready' | 'error'
+  hasUpstream: boolean | undefined
+  hasCurrentBranch: boolean
+}
+
+export const HARD_REFRESH_ERROR_TYPES = new Set<PRRefreshErrorType>([
+  'auth',
+  'permission',
+  'repo_unavailable',
+  'gh_unavailable'
+])
+
+/** Eligibility blockers that own their own guidance and outrank refresh copy. */
+export const ELIGIBILITY_SAFETY_BLOCKERS = new Set<NonNullable<HostedReviewCreationBlockedReason>>([
+  'detached_head',
+  'dirty',
+  'default_branch',
+  'existing_review',
+  'fork_head_unsupported',
+  'base_not_on_remote',
+  'unsupported_provider'
+])
+
+export function isHardRefreshError(refresh: ChecksPanelRefreshInput | undefined): boolean {
+  return (
+    refresh?.status === 'error' &&
+    refresh.errorType != null &&
+    HARD_REFRESH_ERROR_TYPES.has(refresh.errorType)
+  )
+}
+
+export function isRateLimitRefresh(refresh: ChecksPanelRefreshInput | undefined): boolean {
+  return (
+    refresh?.status === 'paused' ||
+    refresh?.errorType === 'rate_limited' ||
+    (refresh?.status === 'skipped' && refresh.skippedReason === 'rate-limit')
+  )
+}
+
+export function isTransientRefreshFailure(refresh: ChecksPanelRefreshInput | undefined): boolean {
+  if (!refresh) {
+    return false
+  }
+  if (isRateLimitRefresh(refresh)) {
+    return true
+  }
+  if (refresh.status === 'error') {
+    // Untyped and typed-transient errors only pause background refresh; they do
+    // not prove a fresh user-initiated lookup would fail.
+    return (
+      refresh.errorType == null ||
+      refresh.errorType === 'network' ||
+      refresh.errorType === 'server_error' ||
+      refresh.errorType === 'unknown'
+    )
+  }
+  return false
+}
+
+export function isBranchBlocker(reason: HostedReviewCreationBlockedReason | undefined): boolean {
+  return (
+    reason === 'no_upstream' ||
+    reason === 'needs_sync' ||
+    reason === 'auth_required' ||
+    reason === 'needs_push'
+  )
+}
+
+export function confirmedComposerMode(
+  input: Pick<ChecksPanelReviewStateInput, 'confirmedReadiness' | 'confirmedNeedsPush'>
+): ChecksPanelComposerMode {
+  if (!input.confirmedReadiness) {
+    return 'hidden'
+  }
+  return input.confirmedNeedsPush ? 'needs_push_open' : 'confirmed_open'
+}
+
+export function workflowActionForComposer(
+  mode: ChecksPanelComposerMode
+): ChecksPanelWorkflowAction {
+  if (mode === 'confirmed_open') {
+    return 'create'
+  }
+  if (mode === 'needs_push_open') {
+    return 'push_and_create'
+  }
+  return null
+}
+
+export function autoRetrySchedule(input: ChecksPanelReviewStateInput): {
+  autoRetryAt?: number
+  retryDisabledUntil?: number
+} {
+  return {
+    autoRetryAt: input.refresh?.nextAutoRetryAt,
+    retryDisabledUntil: input.refresh?.retryDisabledUntil
+  }
+}
+
+export function capitalizeReviewLabel(value: string): string {
+  return value.length > 0 ? value[0].toUpperCase() + value.slice(1) : value
+}
diff --git a/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts b/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts
index 4f14097388d..a1f6459dce2 100644
--- a/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts
@@ -190,7 +190,8 @@ describe('source-control Create PR intent flow helpers', () => {
           review: null,
           canCreate: false,
           blockedReason: 'no_upstream',
-          nextAction: 'publish'
+          nextAction: 'publish',
+          reviewLookupOutcome: 'not_found'
         }
       })
     ).toBe('publish')
@@ -204,7 +205,8 @@ describe('source-control Create PR intent flow helpers', () => {
           review: null,
           canCreate: false,
           blockedReason: 'needs_push',
-          nextAction: 'push'
+          nextAction: 'push',
+          reviewLookupOutcome: 'not_found'
         }
       })
     ).toBe('push')
@@ -224,7 +226,8 @@ describe('source-control Create PR intent flow helpers', () => {
           review: null,
           canCreate: false,
           blockedReason: 'needs_sync',
-          nextAction: 'sync'
+          nextAction: 'sync',
+          reviewLookupOutcome: 'not_found'
         }
       })
     ).toBe('force_push')
@@ -242,7 +245,8 @@ describe('source-control Create PR intent flow helpers', () => {
           review: null,
           canCreate: false,
           blockedReason: 'needs_sync',
-          nextAction: 'sync'
+          nextAction: 'sync',
+          reviewLookupOutcome: 'not_found'
         }
       })
     ).toBe('blocked')
@@ -257,7 +261,8 @@ describe('source-control Create PR intent flow helpers', () => {
           review: null,
           canCreate: false,
           blockedReason: 'needs_sync',
-          nextAction: 'sync'
+          nextAction: 'sync',
+          reviewLookupOutcome: 'not_found'
         }
       })
     ).toBe('sync')
@@ -272,7 +277,8 @@ describe('source-control Create PR intent flow helpers', () => {
           review: null,
           canCreate: false,
           blockedReason: 'no_upstream',
-          nextAction: 'publish'
+          nextAction: 'publish',
+          reviewLookupOutcome: 'not_found'
         }
       })
     ).toBe('blocked')
diff --git a/src/renderer/src/components/right-sidebar/source-control-create-review-blocked-action.test.ts b/src/renderer/src/components/right-sidebar/source-control-create-review-blocked-action.test.ts
index 10419bad3ea..e2bd937f1c2 100644
--- a/src/renderer/src/components/right-sidebar/source-control-create-review-blocked-action.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-create-review-blocked-action.test.ts
@@ -14,6 +14,7 @@ function eligibility(
     canCreate: false,
     blockedReason: 'needs_push',
     nextAction: 'push',
+    reviewLookupOutcome: 'not_found',
     ...overrides
   }
 }
diff --git a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts
index 86af5bafdb7..d97707dd273 100644
--- a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts
@@ -183,7 +183,8 @@ describe('resolveDropdownItems', () => {
           review: null,
           canCreate: false,
           blockedReason: 'needs_sync',
-          nextAction: 'sync'
+          nextAction: 'sync',
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -360,7 +361,8 @@ describe('resolveDropdownItems', () => {
           review: null,
           canCreate: true,
           blockedReason: null,
-          nextAction: null
+          nextAction: null,
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -671,7 +673,8 @@ describe('resolveDropdownItems', () => {
           review: null,
           canCreate: false,
           blockedReason: 'needs_push',
-          nextAction: 'push'
+          nextAction: 'push',
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -693,7 +696,8 @@ describe('resolveDropdownItems', () => {
           review: null,
           canCreate: false,
           blockedReason: 'needs_push',
-          nextAction: 'push'
+          nextAction: 'push',
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -719,7 +723,8 @@ describe('resolveDropdownItems', () => {
             review: null,
             canCreate: false,
             blockedReason: 'needs_push',
-            nextAction: 'push'
+            nextAction: 'push',
+            reviewLookupOutcome: 'not_found'
           }
         })
       )
@@ -747,7 +752,8 @@ describe('resolveDropdownItems', () => {
           review: null,
           canCreate: false,
           blockedReason: 'auth_required',
-          nextAction: 'authenticate'
+          nextAction: 'authenticate',
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -766,7 +772,8 @@ describe('resolveDropdownItems', () => {
           review: null,
           canCreate: false,
           blockedReason: 'auth_required',
-          nextAction: 'authenticate'
+          nextAction: 'authenticate',
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
diff --git a/src/renderer/src/components/right-sidebar/source-control-hosted-review-creation-eligibility-snapshot.test.ts b/src/renderer/src/components/right-sidebar/source-control-hosted-review-creation-eligibility-snapshot.test.ts
index ae6dceadc7c..13d7bc5dac9 100644
--- a/src/renderer/src/components/right-sidebar/source-control-hosted-review-creation-eligibility-snapshot.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-hosted-review-creation-eligibility-snapshot.test.ts
@@ -32,7 +32,7 @@ describe('resolveHostedReviewCreationProviderForTarget', () => {
 })
 
 describe('buildLocalBlockerHostedReviewCreationEligibility', () => {
-  it('reports dirty when there are uncommitted changes', () => {
+  it('reports dirty without offering create intent when the review lookup failed', () => {
     const eligibility = buildLocalBlockerHostedReviewCreationEligibility('github', {
       ...featureBranch,
       hasUncommittedChanges: true,
@@ -40,9 +40,12 @@ describe('buildLocalBlockerHostedReviewCreationEligibility', () => {
       ahead: 0,
       behind: 0
     })
-    expect(eligibility).toMatchObject({ blockedReason: 'dirty', nextAction: 'commit' })
-    // The synthesized blocker must drive the actionable Create PR intent so a
-    // failed remote probe still offers commit/publish preparation.
+    expect(eligibility).toMatchObject({
+      blockedReason: 'dirty',
+      nextAction: 'commit',
+      reviewLookupOutcome: 'unavailable'
+    })
+    // Why: branch guidance can remain specific, but a failed lookup cannot authorize creation.
     expect(
       resolveCreatePrIntentEligibility({
         stagedCount: 1,
@@ -53,7 +56,7 @@ describe('buildLocalBlockerHostedReviewCreationEligibility', () => {
         hostedReviewCreation: eligibility,
         branchCommitsAhead: 0
       })
-    ).toEqual({ eligible: true, kind: 'dirty' })
+    ).toEqual({ eligible: false, kind: null })
   })
 
   it('prefers dirty over no_upstream when both apply, matching main-process ordering', () => {
diff --git a/src/renderer/src/components/right-sidebar/source-control-hosted-review-creation-eligibility-snapshot.ts b/src/renderer/src/components/right-sidebar/source-control-hosted-review-creation-eligibility-snapshot.ts
index f951af458f0..0857f94f6a0 100644
--- a/src/renderer/src/components/right-sidebar/source-control-hosted-review-creation-eligibility-snapshot.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-hosted-review-creation-eligibility-snapshot.ts
@@ -13,7 +13,9 @@ export function buildLoadingHostedReviewCreationEligibility(
     review: null,
     canCreate: false,
     blockedReason: null,
-    nextAction: null
+    nextAction: null,
+    // Why: a loading placeholder has no authoritative existing-review result.
+    reviewLookupOutcome: 'unavailable'
   }
 }
 
@@ -36,8 +38,8 @@ export function resolveHostedReviewCreationProviderForTarget(
 
 /**
  * Local-status-only eligibility used when the remote creation probe fails or
- * times out, so a failed probe still offers the actionable commit/publish/sync
- * preparation action instead of leaving an inert disabled button.
+ * times out, so the UI can show branch guidance without treating the failed
+ * lookup as authority to create a review.
  *
  * Mirrors the main process's own lookup-failure fallback exactly — both its
  * `canReturnLocalBlocker` guard and its blocker ordering
@@ -77,7 +79,9 @@ export function buildLocalBlockerHostedReviewCreationEligibility(
     review: null,
     canCreate: false as const,
     defaultBaseRef: null,
-    head: branch
+    head: branch,
+    // Why: local Git blockers cannot prove that a hosted review does not exist.
+    reviewLookupOutcome: 'unavailable' as const
   }
   if (status.hasUncommittedChanges) {
     return { ...base, blockedReason: 'dirty', nextAction: 'commit' }
diff --git a/src/renderer/src/components/right-sidebar/source-control-primary-action.create-pr-intent.test.ts b/src/renderer/src/components/right-sidebar/source-control-primary-action.create-pr-intent.test.ts
index 086f86565ed..5d5f249a3bd 100644
--- a/src/renderer/src/components/right-sidebar/source-control-primary-action.create-pr-intent.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-primary-action.create-pr-intent.test.ts
@@ -39,7 +39,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
           review: null,
           canCreate: false,
           blockedReason: 'no_upstream',
-          nextAction: 'publish'
+          nextAction: 'publish',
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -63,7 +64,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
           review: null,
           canCreate: false,
           blockedReason: 'needs_sync',
-          nextAction: 'sync'
+          nextAction: 'sync',
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -84,7 +86,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
         review: null,
         canCreate: false,
         blockedReason: 'needs_sync',
-        nextAction: 'sync'
+        nextAction: 'sync',
+        reviewLookupOutcome: 'not_found'
       }
     })
     const result = resolvePrimaryAction(input)
@@ -106,7 +109,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
         review: null,
         canCreate: false,
         blockedReason: 'needs_push',
-        nextAction: 'push'
+        nextAction: 'push',
+        reviewLookupOutcome: 'not_found'
       }
     })
     const result = resolvePrimaryAction(input)
@@ -137,7 +141,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
           review: null,
           canCreate: false,
           blockedReason: 'dirty',
-          nextAction: 'commit'
+          nextAction: 'commit',
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -159,7 +164,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
             review: null,
             canCreate: false,
             blockedReason: 'dirty',
-            nextAction: 'commit'
+            nextAction: 'commit',
+            reviewLookupOutcome: 'not_found'
           }
         })
       )
@@ -181,7 +187,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
         review: null,
         canCreate: false,
         blockedReason: 'dirty',
-        nextAction: 'commit'
+        nextAction: 'commit',
+        reviewLookupOutcome: 'not_found'
       }
     })
     const result = resolvePrimaryAction(input)
@@ -206,7 +213,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
             review: null,
             canCreate: false,
             blockedReason: 'default_branch',
-            nextAction: null
+            nextAction: null,
+            reviewLookupOutcome: 'not_found'
           }
         })
       )
@@ -229,7 +237,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
           review: null,
           canCreate: false,
           blockedReason: 'dirty',
-          nextAction: 'commit'
+          nextAction: 'commit',
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -250,7 +259,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
             review: null,
             canCreate: false,
             blockedReason: 'dirty',
-            nextAction: 'commit'
+            nextAction: 'commit',
+            reviewLookupOutcome: 'not_found'
           }
         })
       )
@@ -270,7 +280,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
         review: null,
         canCreate: false,
         blockedReason: 'dirty',
-        nextAction: 'commit'
+        nextAction: 'commit',
+        reviewLookupOutcome: 'not_found'
       }
     })
 
@@ -299,7 +310,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
             review: null,
             canCreate: false,
             blockedReason: 'needs_push',
-            nextAction: 'push'
+            nextAction: 'push',
+            reviewLookupOutcome: 'not_found'
           }
         })
       )
@@ -321,7 +333,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
         review: null,
         canCreate: false,
         blockedReason: 'no_upstream',
-        nextAction: 'publish'
+        nextAction: 'publish',
+        reviewLookupOutcome: 'not_found'
       }
     })
 
@@ -354,7 +367,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
         review: null,
         canCreate: false,
         blockedReason: 'needs_sync',
-        nextAction: 'sync'
+        nextAction: 'sync',
+        reviewLookupOutcome: 'not_found'
       }
     })
 
@@ -387,7 +401,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
         review: null,
         canCreate: false,
         blockedReason: 'needs_sync',
-        nextAction: 'sync'
+        nextAction: 'sync',
+        reviewLookupOutcome: 'not_found'
       }
     })
 
@@ -409,7 +424,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
             review: null,
             canCreate: true,
             blockedReason: null,
-            nextAction: null
+            nextAction: null,
+            reviewLookupOutcome: 'not_found'
           }
         })
       )
@@ -430,7 +446,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
             review: null,
             canCreate: false,
             blockedReason: null,
-            nextAction: null
+            nextAction: null,
+            reviewLookupOutcome: 'not_found'
           },
           isHostedReviewCreationLoading: true
         })
@@ -452,7 +469,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
             review: null,
             canCreate: true,
             blockedReason: null,
-            nextAction: null
+            nextAction: null,
+            reviewLookupOutcome: 'not_found'
           },
           isHostedReviewCreationLoading: true
         })
@@ -474,7 +492,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
             review: null,
             canCreate: true,
             blockedReason: null,
-            nextAction: null
+            nextAction: null,
+            reviewLookupOutcome: 'not_found'
           },
           isHostedReviewCreationLoading: true
         })
@@ -498,7 +517,8 @@ describe('resolvePrimaryAction Create PR intent', () => {
             review: null,
             canCreate: false,
             blockedReason: 'no_upstream',
-            nextAction: 'publish'
+            nextAction: 'publish',
+            reviewLookupOutcome: 'not_found'
           }
         })
       )
diff --git a/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts b/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts
index b71ae52185d..f03f1e490d7 100644
--- a/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts
@@ -429,7 +429,8 @@ describe('resolvePrimaryAction', () => {
         review: null,
         canCreate: false,
         blockedReason: 'dirty',
-        nextAction: 'commit'
+        nextAction: 'commit',
+        reviewLookupOutcome: 'not_found'
       }
     })
 
@@ -455,7 +456,8 @@ describe('resolvePrimaryAction', () => {
         review: null,
         canCreate: false,
         blockedReason: 'dirty',
-        nextAction: 'commit'
+        nextAction: 'commit',
+        reviewLookupOutcome: 'not_found'
       }
     })
 
@@ -542,7 +544,8 @@ describe('resolvePrimaryAction', () => {
           review: null,
           canCreate: true,
           blockedReason: null,
-          nextAction: null
+          nextAction: null,
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -563,7 +566,8 @@ describe('resolvePrimaryAction', () => {
           review: null,
           canCreate: true,
           blockedReason: null,
-          nextAction: null
+          nextAction: null,
+          reviewLookupOutcome: 'not_found'
         }
       })
     )
@@ -586,7 +590,8 @@ describe('resolvePrimaryAction', () => {
             review: null,
             canCreate: true,
             blockedReason: null,
-            nextAction: null
+            nextAction: null,
+            reviewLookupOutcome: 'not_found'
           }
         })
       )
diff --git a/src/renderer/src/components/right-sidebar/useCreatePullRequestDialogFields.test.ts b/src/renderer/src/components/right-sidebar/useCreatePullRequestDialogFields.test.ts
index d09fc41cc32..8017aea4445 100644
--- a/src/renderer/src/components/right-sidebar/useCreatePullRequestDialogFields.test.ts
+++ b/src/renderer/src/components/right-sidebar/useCreatePullRequestDialogFields.test.ts
@@ -51,6 +51,7 @@ function createEligibility(
     canCreate: true,
     blockedReason: null,
     nextAction: null,
+    reviewLookupOutcome: 'not_found',
     defaultBaseRef: 'refs/remotes/origin/main',
     title: 'Review title',
     body: 'Review body',
diff --git a/src/renderer/src/components/right-sidebar/useCreatePullRequestDialogFields.ts b/src/renderer/src/components/right-sidebar/useCreatePullRequestDialogFields.ts
index 08a3b311de6..815a18abba3 100644
--- a/src/renderer/src/components/right-sidebar/useCreatePullRequestDialogFields.ts
+++ b/src/renderer/src/components/right-sidebar/useCreatePullRequestDialogFields.ts
@@ -48,6 +48,11 @@ type UseCreatePullRequestDialogFieldsOptions = {
   submitting: boolean
   prCreationDefaults?: SourceControlAiPrCreationDefaults
   sourceControlAiActionsVisible?: boolean
+  // When the composer is hidden by a temporary policy (a hard refresh error) for
+  // the same context rather than dismissed, retain the in-memory draft so
+  // recovery does not discard the user's title/body/base edits. Reopening a
+  // different context still reseeds (guarded by the eligibility key).
+  retainDraftWhenClosed?: boolean
   onBranchChangedByGeneration?: () => Promise<void>
   generation?: {
     generating: boolean
@@ -131,6 +136,7 @@ export function useCreatePullRequestDialogFields({
   submitting,
   prCreationDefaults,
   sourceControlAiActionsVisible = true,
+  retainDraftWhenClosed = false,
   onBranchChangedByGeneration,
   generation
 }: UseCreatePullRequestDialogFieldsOptions) {
@@ -254,12 +260,18 @@ export function useCreatePullRequestDialogFields({
           }
         }
         generateInFlightRef.current = false
-        generationSeedRef.current = null
-        initializedFromEligibilityRef.current = null
-        syncedDefaultBaseRef.current = null
-        baseEditedByUserRef.current = false
-        setInitializedEligibilityKey(null)
-        autoGeneratedForKeyRef.current = null
+        // Why: retain the draft + init marker across a temporary policy hide so a
+        // hard-error recovery reopening the same context does not reseed and wipe
+        // edits. A genuine context change still reseeds (the eligibility key on
+        // reopen differs from the retained marker).
+        if (!retainDraftWhenClosed) {
+          generationSeedRef.current = null
+          initializedFromEligibilityRef.current = null
+          syncedDefaultBaseRef.current = null
+          baseEditedByUserRef.current = false
+          setInitializedEligibilityKey(null)
+          autoGeneratedForKeyRef.current = null
+        }
         setGenerating(false)
         setGenerateError(null)
       }
@@ -316,6 +328,7 @@ export function useCreatePullRequestDialogFields({
     repoId,
     resolvedDefaultBaseRef,
     resolvedPrDefaults.draft,
+    retainDraftWhenClosed,
     worktreeId,
     worktreePath
   ])
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 06fe05685de..23cfccec709 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -9292,7 +9292,16 @@
             "f273f2271c": "Started the agent. Marked {{value0}} resolved, skipped {{value1}}, failed {{value2}}.",
             "aa95b81a3a": "Started the agent. Marked {{value0}} resolved, skipped {{value1}}, failed {{value2}}.",
             "495b2f8c4b": "Started the agent, but could not mark the selected comments resolved.",
-            "3c3ad3a1d2": "Started the agent. No selected comments can be marked resolved on the host."
+            "3c3ad3a1d2": "Started the agent. No selected comments can be marked resolved on the host.",
+            "review": {
+              "auto_retry": "Orca will retry at {{time}}.",
+              "open_review": "Open Review",
+              "retry": "Retry"
+            },
+            "sync": {
+              "pending": "Syncing…",
+              "branch": "Sync Branch"
+            }
           },
           "CreatePullRequestDialog": {
             "2bc1b4345e": "Cancel",
@@ -9908,6 +9917,136 @@
                   "d77c513c1e": "{{value0}} in progress",
                   "b597440265": "Refresh GitHub status for this branch to load checks and review."
                 }
+              },
+              "review": {
+                "detail": {
+                  "positive": "Orca also has saved {{reviewLabel}} information that it could not verify.",
+                  "rate_limited": "Orca also could not check {{reviewLabel}} status because {{provider}} is temporarily limiting requests.",
+                  "network": "Orca also could not check {{reviewLabel}} status because this environment could not reach {{provider}}.",
+                  "untyped": "Orca also could not confirm whether this branch already has a {{reviewLabel}}."
+                },
+                "positive": {
+                  "title": "{{reviewLabelCap}} details unavailable",
+                  "body": "Orca has saved {{reviewLabel}} information for this branch but could not confirm its current status."
+                },
+                "no_review": {
+                  "title": "No {{reviewLabel}} found",
+                  "body": "Create a {{reviewLabel}} to start checks and review."
+                },
+                "active": {
+                  "title": "Checking {{reviewLabel}} status",
+                  "body": "Orca is checking {{provider}} for a {{reviewLabel}} on this branch."
+                },
+                "git_loading": {
+                  "title": "Checking branch status",
+                  "body": "Orca is checking this branch before showing create or publish actions."
+                },
+                "git_error": {
+                  "title": "Could not check branch status",
+                  "body": "Orca could not confirm this branch's upstream from this environment. Retry before publishing or creating a {{reviewLabel}}."
+                },
+                "unknown": {
+                  "title": "{{reviewLabelCap}} status unavailable",
+                  "body": "Orca has not confirmed the {{reviewLabel}} status for this branch. Retry to check again."
+                },
+                "paused": {
+                  "title": "{{provider}} refresh paused",
+                  "body": "{{provider}} is temporarily limiting requests. This can happen even when the displayed API quota is not exhausted."
+                },
+                "network": {
+                  "title": "Could not reach {{provider}}",
+                  "body": "This environment could not reach {{provider}}. Check its connection, then retry."
+                },
+                "unknown_error": {
+                  "title": "Could not check {{reviewLabel}} status",
+                  "body": "The lookup failed, so Orca could not confirm whether this branch already has a {{reviewLabel}}."
+                },
+                "untyped": {
+                  "title": "{{reviewLabelCap}} status unavailable",
+                  "body": "Orca could not confirm whether this branch already has a {{reviewLabel}}. Retry to check again."
+                },
+                "auth": {
+                  "title": "{{provider}} authentication failed",
+                  "body": "{{provider}} could not authenticate the credentials available in this environment. Check the {{provider}} login or environment token, then retry."
+                },
+                "permission": {
+                  "title": "{{provider}} access denied",
+                  "body": "The current {{provider}} credentials cannot read this repository's {{reviewLabel}}s. Check the account, token scopes, and repository access, then retry."
+                },
+                "repo": {
+                  "title": "{{provider}} repository unavailable",
+                  "body": "{{provider}} could not resolve or access the repository for the current remote and account. Check the remote and repository access, then retry."
+                },
+                "cli": {
+                  "title": "{{provider}} CLI unavailable",
+                  "body": "Orca could not run {{provider}} CLI in this environment. Set it up here, then retry."
+                },
+                "skipped": {
+                  "disconnected": {
+                    "title": "Host disconnected",
+                    "body": "This repository's execution host is disconnected, so Orca cannot refresh {{reviewLabel}} status."
+                  },
+                  "bare": {
+                    "title": "Bare repository",
+                    "body": "This repository is bare, so {{reviewLabel}} status is not available here."
+                  },
+                  "archived": {
+                    "title": "Repository archived",
+                    "body": "This repository is archived, so Orca is not refreshing {{reviewLabel}} status."
+                  },
+                  "not_git": {
+                    "title": "Not a Git repository",
+                    "body": "Orca could not treat this folder as a Git repository for {{reviewLabel}} status."
+                  },
+                  "remote": {
+                    "title": "Remote-only context",
+                    "body": "Orca could not refresh {{reviewLabel}} status for this remote context. Retry after the host is available."
+                  }
+                },
+                "no_upstream": {
+                  "title": "No upstream configured",
+                  "body": "Publish this branch to set its upstream before creating a {{reviewLabel}}."
+                },
+                "needs_sync": {
+                  "title": "Branch needs to sync",
+                  "body": "Sync this branch with its upstream before creating a {{reviewLabel}}."
+                },
+                "auth_required": {
+                  "title": "Connect {{provider}}",
+                  "body": "{{provider}} must be connected in this environment before Orca can create a {{reviewLabel}}."
+                },
+                "needs_push": {
+                  "title": "Branch has unpushed commits",
+                  "body": "Push the latest commits before creating a {{reviewLabel}}."
+                },
+                "existing": {
+                  "title": "{{reviewLabelCap}} already exists",
+                  "body": "Orca found an existing {{reviewLabel}} for this branch."
+                },
+                "detached": {
+                  "title": "No current branch",
+                  "body": "Check out a branch before creating a {{reviewLabel}}."
+                },
+                "dirty": {
+                  "title": "Commit changes first",
+                  "body": "Commit or stash your changes before creating a {{reviewLabel}}."
+                },
+                "default_branch": {
+                  "title": "On the default branch",
+                  "body": "Switch to a feature branch before creating a {{reviewLabel}}."
+                },
+                "fork": {
+                  "title": "Fork head unsupported",
+                  "body": "Orca cannot create a {{reviewLabel}} from this fork head here."
+                },
+                "base_missing": {
+                  "title": "Base branch not on remote",
+                  "body": "This branch's base is not on the remote yet, so a {{reviewLabel}} cannot target it."
+                },
+                "unsupported": {
+                  "title": "{{reviewLabelCap}} not supported here",
+                  "body": "This repository provider does not support creating a {{reviewLabel}} from Orca."
+                }
               }
             }
           },
diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json
index fe010cb3095..fe3ac1620a8 100644
--- a/src/renderer/src/i18n/locales/es.json
+++ b/src/renderer/src/i18n/locales/es.json
@@ -9269,7 +9269,16 @@
             "f273f2271c": "Agente iniciado. Marcados como resueltos: {{value0}}; omitidos: {{value1}}; con error: {{value2}}.",
             "aa95b81a3a": "Agente iniciado. Marcados como resueltos: {{value0}}; omitidos: {{value1}}; con error: {{value2}}.",
             "495b2f8c4b": "Agente iniciado, pero no se pudieron marcar los comentarios seleccionados como resueltos.",
-            "3c3ad3a1d2": "Agente iniciado. No se puede marcar ningún comentario seleccionado como resuelto en el host."
+            "3c3ad3a1d2": "Agente iniciado. No se puede marcar ningún comentario seleccionado como resuelto en el host.",
+            "review": {
+              "auto_retry": "Orca reintentará a las {{time}}.",
+              "open_review": "Abrir revisión",
+              "retry": "Reintentar"
+            },
+            "sync": {
+              "pending": "Syncing…",
+              "branch": "Sync Branch"
+            }
           },
           "CreatePullRequestDialog": {
             "2bc1b4345e": "Cancelar",
@@ -9885,6 +9894,136 @@
                   "d77c513c1e": "{{value0}} en progreso",
                   "b597440265": "Actualiza el estado de GitHub de esta rama para cargar checks y revisión."
                 }
+              },
+              "review": {
+                "detail": {
+                  "positive": "Orca también tiene información de {{reviewLabel}} guardada que no pudo verificar.",
+                  "rate_limited": "Orca también no pudo verificar el estado de {{reviewLabel}} porque {{provider}} está limitando temporalmente las solicitudes.",
+                  "network": "Orca también no pudo verificar el estado de {{reviewLabel}} porque este entorno no pudo conectar con {{provider}}.",
+                  "untyped": "Orca también no pudo confirmar si esta rama ya tiene un {{reviewLabel}}."
+                },
+                "positive": {
+                  "title": "Detalles de {{reviewLabelCap}} no disponibles",
+                  "body": "Orca ha guardado información de {{reviewLabel}} para esta rama pero no pudo confirmar su estado actual."
+                },
+                "no_review": {
+                  "title": "No se encontró ningún {{reviewLabel}}",
+                  "body": "Crea un {{reviewLabel}} para iniciar las verificaciones y la revisión."
+                },
+                "active": {
+                  "title": "Verificando estado de {{reviewLabel}}",
+                  "body": "Orca está verificando {{provider}} para un {{reviewLabel}} en esta rama."
+                },
+                "git_loading": {
+                  "title": "Verificando estado de la rama",
+                  "body": "Orca está verificando esta rama antes de mostrar las acciones de creación o publicación."
+                },
+                "git_error": {
+                  "title": "No se pudo verificar el estado de la rama",
+                  "body": "Orca no pudo confirmar el upstream de esta rama desde este entorno. Reintenta antes de publicar o crear un {{reviewLabel}}."
+                },
+                "unknown": {
+                  "title": "Estado de {{reviewLabelCap}} no disponible",
+                  "body": "Orca no ha confirmado el estado de {{reviewLabel}} para esta rama. Reintenta para verificar de nuevo."
+                },
+                "paused": {
+                  "title": "Actualización de {{provider}} pausada",
+                  "body": "{{provider}} está limitando temporalmente las solicitudes. Esto puede ocurrir incluso cuando la cuota de API mostrada no está agotada."
+                },
+                "network": {
+                  "title": "No se pudo conectar con {{provider}}",
+                  "body": "Este entorno no pudo conectar con {{provider}}. Verifica su conexión y reintenta."
+                },
+                "unknown_error": {
+                  "title": "No se pudo verificar el estado de {{reviewLabel}}",
+                  "body": "La búsqueda falló, por lo que Orca no pudo confirmar si esta rama ya tiene un {{reviewLabel}}."
+                },
+                "untyped": {
+                  "title": "Estado de {{reviewLabelCap}} no disponible",
+                  "body": "Orca no pudo confirmar si esta rama ya tiene un {{reviewLabel}}. Reintenta para verificar de nuevo."
+                },
+                "auth": {
+                  "title": "Autenticación de {{provider}} fallida",
+                  "body": "{{provider}} no pudo autenticar las credenciales disponibles en este entorno. Verifica el inicio de sesión de {{provider}} o el token del entorno y reintenta."
+                },
+                "permission": {
+                  "title": "Acceso denegado por {{provider}}",
+                  "body": "Las credenciales actuales de {{provider}} no pueden leer los {{reviewLabel}} de este repositorio. Verifica la cuenta, los alcances del token y el acceso al repositorio, luego reintenta."
+                },
+                "repo": {
+                  "title": "Repositorio de {{provider}} no disponible",
+                  "body": "{{provider}} no pudo resolver o acceder al repositorio del remote y cuenta actuales. Verifica el remote y el acceso al repositorio, luego reintenta."
+                },
+                "cli": {
+                  "title": "CLI de {{provider}} no disponible",
+                  "body": "Orca no pudo ejecutar la CLI de {{provider}} en este entorno. Configúrala aquí y reintenta."
+                },
+                "skipped": {
+                  "disconnected": {
+                    "title": "Host desconectado",
+                    "body": "El host de ejecución de este repositorio está desconectado, por lo que Orca no puede actualizar el estado de {{reviewLabel}}."
+                  },
+                  "bare": {
+                    "title": "Repositorio bare",
+                    "body": "Este repositorio es bare, por lo que el estado de {{reviewLabel}} no está disponible aquí."
+                  },
+                  "archived": {
+                    "title": "Repositorio archivado",
+                    "body": "Este repositorio está archivado, por lo que Orca no está actualizando el estado de {{reviewLabel}}."
+                  },
+                  "not_git": {
+                    "title": "No es un repositorio Git",
+                    "body": "Orca no pudo tratar esta carpeta como un repositorio Git para el estado de {{reviewLabel}}."
+                  },
+                  "remote": {
+                    "title": "Contexto solo remoto",
+                    "body": "Orca no pudo actualizar el estado de {{reviewLabel}} para este contexto remoto. Reintenta cuando el host esté disponible."
+                  }
+                },
+                "no_upstream": {
+                  "title": "Sin upstream configurado",
+                  "body": "Publica esta rama para configurar su upstream antes de crear un {{reviewLabel}}."
+                },
+                "needs_sync": {
+                  "title": "La rama necesita sincronizarse",
+                  "body": "Sincroniza esta rama con su upstream antes de crear un {{reviewLabel}}."
+                },
+                "auth_required": {
+                  "title": "Conecta {{provider}}",
+                  "body": "{{provider}} debe estar conectado en este entorno antes de que Orca pueda crear un {{reviewLabel}}."
+                },
+                "needs_push": {
+                  "title": "La rama tiene commits sin enviar",
+                  "body": "Envía los últimos commits antes de crear un {{reviewLabel}}."
+                },
+                "existing": {
+                  "title": "{{reviewLabelCap}} ya existe",
+                  "body": "Orca encontró un {{reviewLabel}} existente para esta rama."
+                },
+                "detached": {
+                  "title": "Sin rama actual",
+                  "body": "Selecciona una rama antes de crear un {{reviewLabel}}."
+                },
+                "dirty": {
+                  "title": "Primero confirma los cambios",
+                  "body": "Confirma o guarda tus cambios antes de crear un {{reviewLabel}}."
+                },
+                "default_branch": {
+                  "title": "En la rama por defecto",
+                  "body": "Cambia a una rama de características antes de crear un {{reviewLabel}}."
+                },
+                "fork": {
+                  "title": "Fork head no soportado",
+                  "body": "Orca no puede crear un {{reviewLabel}} desde este fork head aquí."
+                },
+                "base_missing": {
+                  "title": "La rama base no está en el remote",
+                  "body": "La base de esta rama aún no está en el remote, por lo que un {{reviewLabel}} no puede apuntar a ella."
+                },
+                "unsupported": {
+                  "title": "{{reviewLabelCap}} no soportado aquí",
+                  "body": "Este proveedor de repositorio no soporta la creación de un {{reviewLabel}} desde Orca."
+                }
               }
             }
           },
diff --git a/src/renderer/src/i18n/locales/ja.json b/src/renderer/src/i18n/locales/ja.json
index 326b87d99b2..eaf4518ccbb 100644
--- a/src/renderer/src/i18n/locales/ja.json
+++ b/src/renderer/src/i18n/locales/ja.json
@@ -9269,7 +9269,16 @@
             "f273f2271c": "agent を開始しました。{{value0}} 件を解決済みにし、{{value1}} 件をスキップ、{{value2}} 件が失敗しました。",
             "aa95b81a3a": "agent を開始しました。{{value0}} 件を解決済みにし、{{value1}} 件をスキップ、{{value2}} 件が失敗しました。",
             "495b2f8c4b": "agent を開始しましたが、選択したコメントを解決済みにできませんでした。",
-            "3c3ad3a1d2": "agent を開始しました。選択したコメントにホスト上で解決済みにできるものはありません。"
+            "3c3ad3a1d2": "agent を開始しました。選択したコメントにホスト上で解決済みにできるものはありません。",
+            "review": {
+              "auto_retry": "Orca は {{time}} に再試行します。",
+              "open_review": "レビューを開く",
+              "retry": "再試行"
+            },
+            "sync": {
+              "pending": "Syncing…",
+              "branch": "Sync Branch"
+            }
           },
           "CreatePullRequestDialog": {
             "2bc1b4345e": "キャンセル",
@@ -9885,6 +9894,136 @@
                   "d77c513c1e": "{{value0}} が進行中です",
                   "b597440265": "Refresh GitHub status for this branch to load checks and review."
                 }
+              },
+              "review": {
+                "detail": {
+                  "positive": "Orca は保存された {{reviewLabel}} 情報を持っていますが、検証できませんでした。",
+                  "rate_limited": "Orca は {{provider}} がリクエストを一時的に制限しているため、{{reviewLabel}} ステータスを確認できませんでした。",
+                  "network": "Orca はこの環境から {{provider}} に接続できないため、{{reviewLabel}} ステータスを確認できませんでした。",
+                  "untyped": "Orca はこのブランチに {{reviewLabel}} が既に存在するかどうかを確認できませんでした。"
+                },
+                "positive": {
+                  "title": "{{reviewLabelCap}} の詳細が利用できません",
+                  "body": "Orca はこのブランチの {{reviewLabel}} 情報を保存しましたが、現在のステータスを確認できませんでした。"
+                },
+                "no_review": {
+                  "title": "{{reviewLabel}} が見つかりません",
+                  "body": "{{reviewLabel}} を作成して、チェックとレビューを開始します。"
+                },
+                "active": {
+                  "title": "{{reviewLabel}} ステータスを確認中",
+                  "body": "Orca はこのブランチの {{provider}} 上の {{reviewLabel}} を確認しています。"
+                },
+                "git_loading": {
+                  "title": "ブランチのステータスを確認中",
+                  "body": "Orca はこのブランチの作成または公開アクションを表示する前に確認しています。"
+                },
+                "git_error": {
+                  "title": "ブランチのステータスを確認できませんでした",
+                  "body": "Orca はこの環境からこのブランチのアップストリームを確認できませんでした。公開または {{reviewLabel}} の作成前に再試行してください。"
+                },
+                "unknown": {
+                  "title": "{{reviewLabelCap}} ステータスが利用できません",
+                  "body": "Orca はこのブランチの {{reviewLabel}} ステータスを確認していません。再試行して再度確認してください。"
+                },
+                "paused": {
+                  "title": "{{provider}} の更新が一時停止されています",
+                  "body": "{{provider}} がリクエストを一時的に制限しています。表示された API クォータが枯渇していない場合でも発生する可能性があります。"
+                },
+                "network": {
+                  "title": "{{provider}} に接続できませんでした",
+                  "body": "この環境から {{provider}} に接続できませんでした。接続を確認して再試行してください。"
+                },
+                "unknown_error": {
+                  "title": "{{reviewLabel}} ステータスを確認できませんでした",
+                  "body": "検索に失敗したため、Orca はこのブランチに {{reviewLabel}} が既に存在するかどうかを確認できませんでした。"
+                },
+                "untyped": {
+                  "title": "{{reviewLabelCap}} ステータスが利用できません",
+                  "body": "Orca はこのブランチに {{reviewLabel}} が既に存在するかどうかを確認できませんでした。再試行して再度確認してください。"
+                },
+                "auth": {
+                  "title": "{{provider}} の認証に失敗しました",
+                  "body": "{{provider}} はこの環境で使用可能な資格情報を認証できませんでした。{{provider}} のログインまたは環境トークンを確認して再試行してください。"
+                },
+                "permission": {
+                  "title": "{{provider}} のアクセスが拒否されました",
+                  "body": "現在の {{provider}} の資格情報ではこのリポジトリの {{reviewLabel}} を読み取れません。アカウント、トークンスコープ、リポジトリのアクセス権を確認して再試行してください。"
+                },
+                "repo": {
+                  "title": "{{provider}} リポジトリが利用できません",
+                  "body": "{{provider}} は現在のリモートとアカウントのリポジトリを解決またはアクセスできませんでした。リモートとリポジトリのアクセス権を確認して再試行してください。"
+                },
+                "cli": {
+                  "title": "{{provider}} CLI が利用できません",
+                  "body": "Orca はこの環境で {{provider}} CLI を実行できませんでした。ここでセットアップして再試行してください。"
+                },
+                "skipped": {
+                  "disconnected": {
+                    "title": "ホストが切断されました",
+                    "body": "このリポジトリの実行ホストが切断されたため、Orca は {{reviewLabel}} ステータスを更新できません。"
+                  },
+                  "bare": {
+                    "title": "ベアリポジトリ",
+                    "body": "このリポジトリはベアリポジトリであるため、{{reviewLabel}} ステータスはここでは利用できません。"
+                  },
+                  "archived": {
+                    "title": "リポジトリがアーカイブされています",
+                    "body": "このリポジトリはアーカイブされているため、Orca は {{reviewLabel}} ステータスを更新しません。"
+                  },
+                  "not_git": {
+                    "title": "Git リポジトリではありません",
+                    "body": "Orca はこのフォルダを {{reviewLabel}} ステータス用の Git リポジトリとして扱えませんでした。"
+                  },
+                  "remote": {
+                    "title": "リモートのみのコンテキスト",
+                    "body": "Orca はこのリモートコンテキストの {{reviewLabel}} ステータスを更新できませんでした。ホストが利用可能になった後に再試行してください。"
+                  }
+                },
+                "no_upstream": {
+                  "title": "アップストリームが設定されていません",
+                  "body": "このブランチを公開してアップストリームを設定してから {{reviewLabel}} を作成してください。"
+                },
+                "needs_sync": {
+                  "title": "ブランチの同期が必要です",
+                  "body": "{{reviewLabel}} を作成する前に、このブランチをアップストリームと同期してください。"
+                },
+                "auth_required": {
+                  "title": "{{provider}} を接続してください",
+                  "body": "Orca が {{reviewLabel}} を作成する前に、この環境で {{provider}} を接続する必要があります。"
+                },
+                "needs_push": {
+                  "title": "ブランチに未プッシュのコミットがあります",
+                  "body": "{{reviewLabel}} を作成する前に、最新のコミットをプッシュしてください。"
+                },
+                "existing": {
+                  "title": "{{reviewLabelCap}} は既に存在します",
+                  "body": "Orca はこのブランチの既存の {{reviewLabel}} を見つけました。"
+                },
+                "detached": {
+                  "title": "現在のブランチがありません",
+                  "body": "{{reviewLabel}} を作成する前にブランチをチェックアウトしてください。"
+                },
+                "dirty": {
+                  "title": "まず変更をコミットしてください",
+                  "body": "{{reviewLabel}} を作成する前に、変更をコミットまたはスタッシュしてください。"
+                },
+                "default_branch": {
+                  "title": "デフォルトブランチ上です",
+                  "body": "{{reviewLabel}} を作成する前に、フィーチャーブランチに切り替えてください。"
+                },
+                "fork": {
+                  "title": "フォークヘッドはサポートされていません",
+                  "body": "Orca はここからこのフォークヘッドの {{reviewLabel}} を作成できません。"
+                },
+                "base_missing": {
+                  "title": "ベースブランチがリモートにありません",
+                  "body": "このブランチのベースがまだリモートにないため、{{reviewLabel}} をターゲットにできません。"
+                },
+                "unsupported": {
+                  "title": "ここでは {{reviewLabelCap}} はサポートされていません",
+                  "body": "このリポジトリプロバイダーは、Orca からの {{reviewLabel}} の作成をサポートしていません。"
+                }
               }
             }
           },
diff --git a/src/renderer/src/i18n/locales/ko.json b/src/renderer/src/i18n/locales/ko.json
index 0de35bc772f..742d8531e4c 100644
--- a/src/renderer/src/i18n/locales/ko.json
+++ b/src/renderer/src/i18n/locales/ko.json
@@ -9269,7 +9269,16 @@
             "f273f2271c": "agent를 시작했습니다. {{value0}}개 해결됨으로 표시, {{value1}}개 건너뜀, {{value2}}개 실패.",
             "aa95b81a3a": "agent를 시작했습니다. {{value0}}개 해결됨으로 표시, {{value1}}개 건너뜀, {{value2}}개 실패.",
             "495b2f8c4b": "agent를 시작했지만 선택한 댓글을 해결됨으로 표시할 수 없습니다.",
-            "3c3ad3a1d2": "agent를 시작했습니다. 호스트에서 해결됨으로 표시할 수 있는 선택된 댓글이 없습니다."
+            "3c3ad3a1d2": "agent를 시작했습니다. 호스트에서 해결됨으로 표시할 수 있는 선택된 댓글이 없습니다.",
+            "review": {
+              "auto_retry": "Orca가 {{time}}에 다시 시도합니다.",
+              "open_review": "검토 열기",
+              "retry": "다시 시도"
+            },
+            "sync": {
+              "pending": "Syncing…",
+              "branch": "Sync Branch"
+            }
           },
           "CreatePullRequestDialog": {
             "2bc1b4345e": "취소",
@@ -9885,6 +9894,136 @@
                   "d77c513c1e": "{{value0}} 진행 중",
                   "b597440265": "검사와 리뷰를 불러오려면 이 브랜치의 GitHub 상태를 새로 고치세요."
                 }
+              },
+              "review": {
+                "detail": {
+                  "positive": "Orca에는 확인할 수 없는 저장된 {{reviewLabel}} 정보가 있습니다.",
+                  "rate_limited": "{{provider}}가 요청을 일시적으로 제한하고 있어 Orca도 {{reviewLabel}} 상태를 확인할 수 없었습니다.",
+                  "network": "이 환경에서 {{provider}}에 연결할 수 없어 Orca도 {{reviewLabel}} 상태를 확인할 수 없었습니다.",
+                  "untyped": "Orca는 이 브랜치에 이미 {{reviewLabel}}가 있는지 확인할 수 없었습니다."
+                },
+                "positive": {
+                  "title": "{{reviewLabelCap}} 세부 정보를 사용할 수 없음",
+                  "body": "Orca는 이 브랜치의 {{reviewLabel}} 정보를 저장했지만 현재 상태를 확인할 수 없었습니다."
+                },
+                "no_review": {
+                  "title": "{{reviewLabel}}를 찾을 수 없음",
+                  "body": "{{reviewLabel}}를 만들어 검사와 리뷰를 시작하세요."
+                },
+                "active": {
+                  "title": "{{reviewLabel}} 상태 확인 중",
+                  "body": "Orca는 이 브랜치의 {{provider}}에서 {{reviewLabel}}를 확인하고 있습니다."
+                },
+                "git_loading": {
+                  "title": "브랜치 상태 확인 중",
+                  "body": "Orca는 생성 또는 게시 작업을 표시하기 전에 이 브랜치를 확인하고 있습니다."
+                },
+                "git_error": {
+                  "title": "브랜치 상태를 확인할 수 없음",
+                  "body": "Orca는 이 환경에서 이 브랜치의 업스트림을 확인할 수 없었습니다. 게시하거나 {{reviewLabel}}를 만들기 전에 다시 시도하세요."
+                },
+                "unknown": {
+                  "title": "{{reviewLabelCap}} 상태를 사용할 수 없음",
+                  "body": "Orca가 이 브랜치의 {{reviewLabel}} 상태를 확인하지 못했습니다. 다시 시도하여 확인하세요."
+                },
+                "paused": {
+                  "title": "{{provider}} 새로고침 일시 중지됨",
+                  "body": "{{provider}}가 요청을 일시적으로 제한하고 있습니다. 표시된 API 할당량이 소진되지 않은 경우에도 발생할 수 있습니다."
+                },
+                "network": {
+                  "title": "{{provider}}에 연결할 수 없음",
+                  "body": "이 환경에서 {{provider}}에 연결할 수 없었습니다. 연결을 확인한 후 다시 시도하세요."
+                },
+                "unknown_error": {
+                  "title": "{{reviewLabel}} 상태를 확인할 수 없음",
+                  "body": "조회에 실패하여 Orca는 이 브랜치에 이미 {{reviewLabel}}가 있는지 확인할 수 없었습니다."
+                },
+                "untyped": {
+                  "title": "{{reviewLabelCap}} 상태를 사용할 수 없음",
+                  "body": "Orca는 이 브랜치에 이미 {{reviewLabel}}가 있는지 확인할 수 없었습니다. 다시 시도하여 확인하세요."
+                },
+                "auth": {
+                  "title": "{{provider}} 인증 실패",
+                  "body": "{{provider}}는 이 환경에서 사용 가능한 자격 증명을 인증할 수 없었습니다. {{provider}} 로그인 또는 환경 토큰을 확인한 후 다시 시도하세요."
+                },
+                "permission": {
+                  "title": "{{provider}} 접근 거부됨",
+                  "body": "현재 {{provider}} 자격 증명으로는 이 리포지토리의 {{reviewLabel}}를 읽을 수 없습니다. 계정, 토큰 범위 및 리포지토리 접근 권한을 확인한 후 다시 시도하세요."
+                },
+                "repo": {
+                  "title": "{{provider}} 리포지토리를 사용할 수 없음",
+                  "body": "{{provider}}는 현재 리모트와 계정의 리포지토리를 확인하거나 접근할 수 없었습니다. 리모트와 리포지토리 접근 권한을 확인한 후 다시 시도하세요."
+                },
+                "cli": {
+                  "title": "{{provider}} CLI를 사용할 수 없음",
+                  "body": "Orca는 이 환경에서 {{provider}} CLI를 실행할 수 없었습니다. 여기에서 설정한 후 다시 시도하세요."
+                },
+                "skipped": {
+                  "disconnected": {
+                    "title": "호스트 연결 끊김",
+                    "body": "이 리포지토리의 실행 호스트가 연결 해제되어 Orca가 {{reviewLabel}} 상태를 새로고칠 수 없습니다."
+                  },
+                  "bare": {
+                    "title": "베어 리포지토리",
+                    "body": "이 리포지토리는 베어 리포지토리이므로 여기에서 {{reviewLabel}} 상태를 사용할 수 없습니다."
+                  },
+                  "archived": {
+                    "title": "리포지토리가 보관됨",
+                    "body": "이 리포지토리가 보관되어 있으므로 Orca가 {{reviewLabel}} 상태를 새로고치지 않습니다."
+                  },
+                  "not_git": {
+                    "title": "Git 리포지토리가 아님",
+                    "body": "Orca는 {{reviewLabel}} 상태용으로 이 폴더를 Git 리포지토리로 처리할 수 없었습니다."
+                  },
+                  "remote": {
+                    "title": "리모트 전용 컨텍스트",
+                    "body": "Orca는 이 리모트 컨텍스트의 {{reviewLabel}} 상태를 새로고칠 수 없었습니다. 호스트를 사용할 수 있을 때 다시 시도하세요."
+                  }
+                },
+                "no_upstream": {
+                  "title": "업스트림이 설정되지 않음",
+                  "body": "{{reviewLabel}}를 만들기 전에 이 브랜치를 게시하여 업스트림을 설정하세요."
+                },
+                "needs_sync": {
+                  "title": "브랜치 동기화 필요",
+                  "body": "{{reviewLabel}}를 만들기 전에 이 브랜치를 업스트림과 동기화하세요."
+                },
+                "auth_required": {
+                  "title": "{{provider}} 연결",
+                  "body": "Orca가 {{reviewLabel}}를 만들려면 이 환경에서 {{provider}}가 연결되어 있어야 합니다."
+                },
+                "needs_push": {
+                  "title": "브랜치에 푸시하지 않은 커밋이 있음",
+                  "body": "{{reviewLabel}}를 만들기 전에 최신 커밋을 푸시하세요."
+                },
+                "existing": {
+                  "title": "{{reviewLabelCap}}이(가) 이미 존재함",
+                  "body": "Orca는 이 브랜치의 기존 {{reviewLabel}}를 찾았습니다."
+                },
+                "detached": {
+                  "title": "현재 브랜치가 없음",
+                  "body": "{{reviewLabel}}를 만들기 전에 브랜치를 체크아웃하세요."
+                },
+                "dirty": {
+                  "title": "먼저 변경 사항을 커밋하세요",
+                  "body": "{{reviewLabel}}를 만들기 전에 변경 사항을 커밋하거나 스태시하세요."
+                },
+                "default_branch": {
+                  "title": "기본 브랜치 위에 있음",
+                  "body": "{{reviewLabel}}를 만들기 전에 기능 브랜치로 전환하세요."
+                },
+                "fork": {
+                  "title": "포크 헤드 지원되지 않음",
+                  "body": "Orca는 여기에서 이 포크 헤드의 {{reviewLabel}}를 만들 수 없습니다."
+                },
+                "base_missing": {
+                  "title": "기본 브랜치가 리모트에 없음",
+                  "body": "이 브랜치의 기본이 아직 리모트에 없으므로 {{reviewLabel}}가 이를 대상으로 할 수 없습니다."
+                },
+                "unsupported": {
+                  "title": "여기서 {{reviewLabelCap}}이(가) 지원되지 않음",
+                  "body": "이 리포지토리 제공자는 Orca에서 {{reviewLabel}}를 만드는 것을 지원하지 않습니다."
+                }
               }
             }
           },
diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json
index 6a8e1bd94a6..657a353bd8c 100644
--- a/src/renderer/src/i18n/locales/zh.json
+++ b/src/renderer/src/i18n/locales/zh.json
@@ -9269,7 +9269,16 @@
             "f273f2271c": "已启动智能体。已标记 {{value0}} 个为已解决，跳过 {{value1}} 个，失败 {{value2}} 个。",
             "aa95b81a3a": "已启动智能体。已标记 {{value0}} 个为已解决，跳过 {{value1}} 个，失败 {{value2}} 个。",
             "495b2f8c4b": "已启动智能体，但无法将选中的评论标记为已解决。",
-            "3c3ad3a1d2": "已启动智能体。选中的评论中没有可在托管平台上标记为已解决的评论。"
+            "3c3ad3a1d2": "已启动智能体。选中的评论中没有可在托管平台上标记为已解决的评论。",
+            "review": {
+              "auto_retry": "Orca 将在 {{time}} 重试。",
+              "open_review": "打开评审",
+              "retry": "重试"
+            },
+            "sync": {
+              "pending": "Syncing…",
+              "branch": "Sync Branch"
+            }
           },
           "CreatePullRequestDialog": {
             "2bc1b4345e": "取消",
@@ -9885,6 +9894,136 @@
                   "d77c513c1e": "{{value0}} 正在进行中",
                   "b597440265": "刷新此分支的 GitHub 状态以加载检查和审核。"
                 }
+              },
+              "review": {
+                "detail": {
+                  "positive": "Orca 也有已保存的 {{reviewLabel}} 信息但无法验证。",
+                  "rate_limited": "Orca 无法检查 {{reviewLabel}} 状态，因为 {{provider}} 正在临时限制请求。",
+                  "network": "Orca 无法检查 {{reviewLabel}} 状态，因为当前环境无法连接到 {{provider}}。",
+                  "untyped": "Orca 无法确认此分支是否已有 {{reviewLabel}}。"
+                },
+                "positive": {
+                  "title": "{{reviewLabelCap}} 详细信息不可用",
+                  "body": "Orca 已为此分支保存了 {{reviewLabel}} 信息，但无法确认其当前状态。"
+                },
+                "no_review": {
+                  "title": "未找到 {{reviewLabel}}",
+                  "body": "创建 {{reviewLabel}} 以开始检查和评审。"
+                },
+                "active": {
+                  "title": "正在检查 {{reviewLabel}} 状态",
+                  "body": "Orca 正在检查 {{provider}} 上此分支的 {{reviewLabel}}。"
+                },
+                "git_loading": {
+                  "title": "正在检查分支状态",
+                  "body": "Orca 正在检查此分支，然后显示创建或发布操作。"
+                },
+                "git_error": {
+                  "title": "无法检查分支状态",
+                  "body": "Orca 无法从当前环境确认此分支的上游。请在发布或创建 {{reviewLabel}} 之前重试。"
+                },
+                "unknown": {
+                  "title": "{{reviewLabelCap}} 状态不可用",
+                  "body": "Orca 尚未确认此分支的 {{reviewLabel}} 状态。请重试以再次检查。"
+                },
+                "paused": {
+                  "title": "{{provider}} 刷新已暂停",
+                  "body": "{{provider}} 正在临时限制请求。即使显示的 API 配额未用完，也可能发生这种情况。"
+                },
+                "network": {
+                  "title": "无法连接到 {{provider}}",
+                  "body": "当前环境无法连接到 {{provider}}。请检查连接后重试。"
+                },
+                "unknown_error": {
+                  "title": "无法检查 {{reviewLabel}} 状态",
+                  "body": "查询失败，Orca 无法确认此分支是否已有 {{reviewLabel}}。"
+                },
+                "untyped": {
+                  "title": "{{reviewLabelCap}} 状态不可用",
+                  "body": "Orca 无法确认此分支是否已有 {{reviewLabel}}。请重试以再次检查。"
+                },
+                "auth": {
+                  "title": "{{provider}} 身份验证失败",
+                  "body": "{{provider}} 无法验证当前环境中的凭据。请检查 {{provider}} 登录或环境令牌后重试。"
+                },
+                "permission": {
+                  "title": "{{provider}} 访问被拒绝",
+                  "body": "当前 {{provider}} 凭据无法读取此仓库的 {{reviewLabel}}。请检查账户、令牌范围和仓库访问权限后重试。"
+                },
+                "repo": {
+                  "title": "{{provider}} 仓库不可用",
+                  "body": "{{provider}} 无法解析或访问当前远程和账户的仓库。请检查远程和仓库访问权限后重试。"
+                },
+                "cli": {
+                  "title": "{{provider}} CLI 不可用",
+                  "body": "Orca 无法在当前环境中运行 {{provider}} CLI。请在此处设置后重试。"
+                },
+                "skipped": {
+                  "disconnected": {
+                    "title": "主机已断开连接",
+                    "body": "此仓库的执行主机已断开连接，Orca 无法刷新 {{reviewLabel}} 状态。"
+                  },
+                  "bare": {
+                    "title": "裸仓库",
+                    "body": "此仓库是裸仓库，因此此处无法使用 {{reviewLabel}} 状态。"
+                  },
+                  "archived": {
+                    "title": "仓库已归档",
+                    "body": "此仓库已归档，Orca 不会刷新 {{reviewLabel}} 状态。"
+                  },
+                  "not_git": {
+                    "title": "不是 Git 仓库",
+                    "body": "Orca 无法将此文件夹作为 Git 仓库来获取 {{reviewLabel}} 状态。"
+                  },
+                  "remote": {
+                    "title": "仅远程上下文",
+                    "body": "Orca 无法刷新此远程上下文的 {{reviewLabel}} 状态。请在主机可用后重试。"
+                  }
+                },
+                "no_upstream": {
+                  "title": "未配置上游",
+                  "body": "请在创建 {{reviewLabel}} 之前发布此分支以设置其上游。"
+                },
+                "needs_sync": {
+                  "title": "分支需要同步",
+                  "body": "请在创建 {{reviewLabel}} 之前将此分支与其上游同步。"
+                },
+                "auth_required": {
+                  "title": "连接 {{provider}}",
+                  "body": "Orca 创建 {{reviewLabel}} 之前，必须在当前环境中连接 {{provider}}。"
+                },
+                "needs_push": {
+                  "title": "分支有未推送的提交",
+                  "body": "请在创建 {{reviewLabel}} 之前推送最新提交。"
+                },
+                "existing": {
+                  "title": "{{reviewLabelCap}} 已存在",
+                  "body": "Orca 找到了此分支的现有 {{reviewLabel}}。"
+                },
+                "detached": {
+                  "title": "没有当前分支",
+                  "body": "请在创建 {{reviewLabel}} 之前检出分支。"
+                },
+                "dirty": {
+                  "title": "请先提交更改",
+                  "body": "请在创建 {{reviewLabel}} 之前提交或暂存更改。"
+                },
+                "default_branch": {
+                  "title": "在默认分支上",
+                  "body": "请在创建 {{reviewLabel}} 之前切换到功能分支。"
+                },
+                "fork": {
+                  "title": "不支持 Fork 头",
+                  "body": "Orca 无法从此处的 Fork 头创建 {{reviewLabel}}。"
+                },
+                "base_missing": {
+                  "title": "基础分支不在远程上",
+                  "body": "此分支的基础尚未在远程上，因此无法将 {{reviewLabel}} 定向到它。"
+                },
+                "unsupported": {
+                  "title": "此处不支持 {{reviewLabelCap}}",
+                  "body": "此仓库提供程序不支持从 Orca 创建 {{reviewLabel}}。"
+                }
               }
             }
           },
diff --git a/src/renderer/src/store/slices/github.ts b/src/renderer/src/store/slices/github.ts
index 322fc8568c0..7a6527e46f0 100644
--- a/src/renderer/src/store/slices/github.ts
+++ b/src/renderer/src/store/slices/github.ts
@@ -12,7 +12,9 @@ import type {
   GitHubPRRefreshCandidate,
   GitHubPRRefreshEvent,
   GitHubPRRefreshReason,
-  PRRefreshUpstreamErrorType,
+  GitHubPRRefreshSkippedReason,
+  PRRefreshErrorType,
+  PRRefreshOutcome,
   GitHubCommentResult,
   IssueInfo,
   PRCheckDetail,
@@ -676,10 +678,11 @@ export type PRRefreshState = {
   updatedAt: number
   pausedUntil?: number
   message?: string
-  // Why: lets error surfaces render translated, GitHub-attributed copy keyed on
-  // the failure kind (e.g. a 5xx outage vs. a rate limit) rather than showing
-  // the main process's English `message` verbatim.
-  errorType?: PRRefreshUpstreamErrorType
+  // Why: classified errors drive stable copy without exposing raw upstream messages.
+  errorType?: PRRefreshErrorType
+  skippedReason?: GitHubPRRefreshSkippedReason
+  nextAutoRetryAt?: number
+  retryDisabledUntil?: number
 }
 
 export type PRRefreshStateClearToken = {
@@ -2171,6 +2174,24 @@ export type GitHubSlice = {
   patchProjectRowContent: (cacheKey: string, rowId: string, patch: ProjectRowContentPatch) => void
 }
 
+/**
+ * Normalizes the `github.prForBranch` runtime RPC result into a
+ * {@link PRRefreshOutcome}. Current hosts return the full outcome (with a
+ * `kind`), so a runtime `upstream-error` is preserved instead of collapsing to a
+ * false accepted "no PR". A legacy host that still returns `PRInfo | null` is
+ * mapped to `found` / `no-pr` to preserve backward behavior on that host only.
+ */
+function normalizeRuntimePRForBranchOutcome(
+  result: PRRefreshOutcome | PRInfo | null
+): PRRefreshOutcome {
+  if (result && typeof result === 'object' && 'kind' in result) {
+    return result
+  }
+  return result
+    ? { kind: 'found', pr: result, fetchedAt: Date.now() }
+    : { kind: 'no-pr', fetchedAt: Date.now() }
+}
+
 export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (set, get) => ({
   prCache: {},
   issueCache: {},
@@ -3202,7 +3223,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           : null
         const requestHeadOid = candidateWorktree?.head ?? null
         const outcome = runtimeRepo
-          ? await callRuntimeRpc<PRInfo | null>(
+          ? await callRuntimeRpc<PRRefreshOutcome | PRInfo | null>(
               runtimeRepo.target,
               'github.prForBranch',
               {
@@ -3215,11 +3236,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
                   : {})
               },
               { timeoutMs: 30_000 }
-            ).then((pr) =>
-              pr
-                ? ({ kind: 'found', pr, fetchedAt: Date.now() } as const)
-                : ({ kind: 'no-pr', fetchedAt: Date.now() } as const)
-            )
+            ).then((result) => normalizeRuntimePRForBranchOutcome(result))
           : await (async () => {
               const candidate: GitHubPRRefreshCandidate = {
                 repoId: repoId ?? '',
@@ -3263,6 +3280,27 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
         const pr: PRInfo | null =
           outcome.kind === 'found' ? outcome.pr : outcome.kind === 'no-pr' ? null : null
         if (outcome.kind === 'upstream-error') {
+          // Why: the runtime RPC path does not flow through the coordinator
+          // broadcast that populates prRefreshStates on native execution, so a
+          // runtime/SSH gh failure would otherwise show generic "checking" copy.
+          // Record the classified error + schedule here so the Checks panel shows
+          // the same classified failure copy as native (design criterion 2).
+          if (runtimeRepo && prRequestGenerations.get(cacheKey) === generation) {
+            set((s) => {
+              const nextStates = { ...s.prRefreshStates }
+              delete nextStates[cacheKey]
+              nextStates[cacheKey] = {
+                status: 'error',
+                reason: 'swr',
+                updatedAt: Date.now(),
+                message: outcome.message,
+                errorType: outcome.errorType,
+                nextAutoRetryAt: outcome.nextAutoRetryAt,
+                retryDisabledUntil: outcome.retryDisabledUntil
+              }
+              return { prRefreshStates: nextStates }
+            })
+          }
           return cached?.data ?? null
         }
         if (prRequestGenerations.get(cacheKey) === generation) {
@@ -4155,7 +4193,9 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
               reason: event.reason,
               updatedAt: Date.now(),
               message: event.outcome.message,
-              errorType: event.outcome.errorType
+              errorType: event.outcome.errorType,
+              nextAutoRetryAt: event.outcome.nextAutoRetryAt,
+              retryDisabledUntil: event.outcome.retryDisabledUntil
             }
             continue
           }
@@ -4347,11 +4387,18 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           // Why: delete-then-set moves this key to the end of insertion order so
           // capRecordByInsertionOrder evicts genuinely idle keys, not active ones.
           delete nextStates[alias.cacheKey]
+          const isPaused = event.status === 'paused'
           nextStates[alias.cacheKey] = {
             status: event.status,
             reason: event.reason,
             updatedAt: Date.now(),
-            pausedUntil: event.pausedUntil
+            pausedUntil: event.pausedUntil,
+            skippedReason: event.skippedReason,
+            // Why: a paused refresh is a rate-limit gate. Map its pausedUntil into
+            // the unified schedule so the panel shows the auto-retry time and
+            // disables manual Retry until the limit resets.
+            nextAutoRetryAt: isPaused ? event.pausedUntil : undefined,
+            retryDisabledUntil: isPaused ? event.pausedUntil : undefined
           }
         }
       }
diff --git a/src/shared/hosted-review.ts b/src/shared/hosted-review.ts
index 04094cf0774..23cfa655865 100644
--- a/src/shared/hosted-review.ts
+++ b/src/shared/hosted-review.ts
@@ -119,12 +119,21 @@ export type HostedReviewCreationNextAction =
   | 'open_existing_review'
   | null
 
+/**
+ * Records whether the eligibility result observed an authoritative existing-review
+ * lookup. `found` / `not_found` come only from an accepted provider lookup;
+ * `unavailable` marks a local-blocker fallback returned after a swallowed or
+ * skipped lookup, so it can never masquerade as authoritative no-review evidence.
+ */
+export type HostedReviewLookupOutcome = 'found' | 'not_found' | 'unavailable'
+
 export type HostedReviewCreationEligibility = {
   provider: HostedReviewProvider
   review: HostedReviewSummary | null
   canCreate: boolean
   blockedReason: HostedReviewCreationBlockedReason
   nextAction: HostedReviewCreationNextAction
+  reviewLookupOutcome: HostedReviewLookupOutcome
   defaultBaseRef?: string | null
   head?: string | null
   title?: string | null
diff --git a/src/shared/source-control-create-review-intent.ts b/src/shared/source-control-create-review-intent.ts
index f3cb5854f4e..880fce17700 100644
--- a/src/shared/source-control-create-review-intent.ts
+++ b/src/shared/source-control-create-review-intent.ts
@@ -41,6 +41,11 @@ export function resolveCreateReviewIntentEligibility({
     !hasCurrentBranch ||
     !hostedReviewCreation ||
     hostedReviewCreation.canCreate ||
+    // Fail closed when the existing-review lookup could not prove there is no
+    // review: a local blocker (e.g. needs_push) returned after a failed lookup
+    // must not offer a Create PR intent that would push under a false promise —
+    // the main preflight would refuse the create anyway (invariant 8).
+    hostedReviewCreation.reviewLookupOutcome === 'unavailable' ||
     !supportsHostedReviewCreation(hostedReviewCreation.provider)
   ) {
     return { eligible: false, kind: null }
diff --git a/src/shared/source-control-primary-action-decision.test.ts b/src/shared/source-control-primary-action-decision.test.ts
index 1cdcc1193b5..6f153d74bbe 100644
--- a/src/shared/source-control-primary-action-decision.test.ts
+++ b/src/shared/source-control-primary-action-decision.test.ts
@@ -151,7 +151,8 @@ describe('source-control primary action decision', () => {
         review: null,
         canCreate: true,
         blockedReason: null,
-        nextAction: null
+        nextAction: null,
+        reviewLookupOutcome: 'not_found'
       }
     })
     expect(resolveSourceControlPrimaryActionDecision(input).kind).toBe('create_pr')
@@ -167,7 +168,8 @@ describe('source-control primary action decision', () => {
           review: null,
           canCreate: false,
           blockedReason: null,
-          nextAction: null
+          nextAction: null,
+          reviewLookupOutcome: 'not_found'
         },
         isHostedReviewCreationLoading: true
       })
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 405d9ed5ba6..ec80f68b690 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1202,9 +1202,13 @@ export type PRInfo = {
   conflictSummary?: PRConflictSummary
 }
 
-// server_error covers GitHub-side HTTP 5xx outages (githubstatus.com incidents),
-// distinct from a transport-level `network` failure or a `rate_limited` budget.
-export type PRRefreshUpstreamErrorType =
+/**
+ * Discriminates a classified GitHub PR-refresh failure. The renderer maps these
+ * to stable, non-destructive empty-state copy; a `hard` subset (auth, permission,
+ * repo_unavailable, gh_unavailable) means the existing-review lookup is currently
+ * impossible and must hide the Create composer.
+ */
+export type PRRefreshErrorType =
   | 'rate_limited'
   | 'auth'
   | 'network'
@@ -1214,14 +1218,23 @@ export type PRRefreshUpstreamErrorType =
   | 'server_error'
   | 'unknown'
 
+// Backward-compatible name used by outage-copy consumers added on main.
+export type PRRefreshUpstreamErrorType = PRRefreshErrorType
+
 export type PRRefreshOutcome =
   | { kind: 'found'; pr: PRInfo; fetchedAt: number }
   | { kind: 'no-pr'; fetchedAt: number }
   | {
       kind: 'upstream-error'
-      errorType: PRRefreshUpstreamErrorType
+      errorType: PRRefreshErrorType
       message: string
       fetchedAt: number
+      // Unified retry schedule (see docs/reference/pr-panel-refresh-guidance.md).
+      // `nextAutoRetryAt`: earliest time main expects to auto-retry this key.
+      // `retryDisabledUntil`: earliest time a manual Retry / refreshPRNow is
+      // accepted (rate-limit gates only, never ordinary network/auth backoff).
+      nextAutoRetryAt?: number
+      retryDisabledUntil?: number
     }
 
 export type GitHubPRRefreshReason = 'visible' | 'active' | 'post-push' | 'manual' | 'swr'

From 098db336383875bea7a6a9f3c970f3fcba05c78b Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Sun, 19 Jul 2026 16:35:12 -0700
Subject: [PATCH 11/54] Keep lineage children with their parent when dragging
 to another status lane (#9472)

Dragging a parent worktree card to a different status lane in the sidebar
moved only the parent, orphaning its visible lineage children in the old
lane even though the drag preview showed them moving as one unit. All
status-lane and board drop commit paths (plus their hover previews) now
use the same lineage-expanded dragged set the reorder path already uses.

Fixes #9083
---
 ...treeList.status-lane-lineage-drop.test.tsx | 438 ++++++++++++++++++
 .../src/components/sidebar/WorktreeList.tsx   |  56 ++-
 2 files changed, 474 insertions(+), 20 deletions(-)
 create mode 100644 src/renderer/src/components/sidebar/WorktreeList.status-lane-lineage-drop.test.tsx

diff --git a/src/renderer/src/components/sidebar/WorktreeList.status-lane-lineage-drop.test.tsx b/src/renderer/src/components/sidebar/WorktreeList.status-lane-lineage-drop.test.tsx
new file mode 100644
index 00000000000..0311879c5b7
--- /dev/null
+++ b/src/renderer/src/components/sidebar/WorktreeList.status-lane-lineage-drop.test.tsx
@@ -0,0 +1,438 @@
+// @vitest-environment happy-dom
+
+import { act, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+import type {
+  Repo,
+  WorkspaceStatus,
+  Worktree,
+  WorktreeCardProperty,
+  WorktreeLineage,
+  WorktreeMeta
+} from '../../../../shared/types'
+import { DEFAULT_WORKSPACE_STATUSES } from '../../../../shared/workspace-status-defaults'
+import {
+  WORKSPACE_STATUS_DRAG_IDS_TYPE,
+  WORKSPACE_STATUS_DRAG_TYPE
+} from './workspace-status-drag-data'
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true
+
+const mockStore = vi.hoisted(() => ({
+  state: {} as Record<string, unknown>,
+  activateWorktreeFromSidebar: vi.fn(),
+  openModal: vi.fn(),
+  updateWorktreeMeta: vi.fn(),
+  updateWorktreesMeta: vi.fn(),
+  setSortBy: vi.fn(),
+  fetchHostedReviewForBranch: vi.fn(),
+  fetchIssue: vi.fn(),
+  fetchLinearIssue: vi.fn(),
+  openTaskPage: vi.fn()
+}))
+
+type WorktreeListComponent = React.ComponentType<{
+  scrollOffsetRef: React.RefObject<number>
+  scrollAnchorRef: React.RefObject<unknown>
+}>
+
+let WorktreeList: WorktreeListComponent
+
+function makeFolderWorkspacePathStatusMockState(): Record<string, unknown> {
+  return {
+    fetchFolderWorkspacePathStatus: vi.fn(),
+    folderWorkspaces: [],
+    folderWorkspacePathStatuses: {},
+    getFolderWorkspacePathStatusCacheKey: (request: unknown) => JSON.stringify(request),
+    getFreshFolderWorkspacePathStatus: () => null
+  }
+}
+
+vi.mock('@/store', () => {
+  const useAppStore = ((selector: (state: Record<string, unknown>) => unknown) =>
+    selector(mockStore.state)) as ((
+    selector: (state: Record<string, unknown>) => unknown
+  ) => unknown) & {
+    getState: () => Record<string, unknown>
+  }
+  useAppStore.getState = () => mockStore.state
+  return { useAppStore }
+})
+
+vi.mock('@tanstack/react-virtual', () => ({
+  defaultRangeExtractor: ({ startIndex, endIndex }: { startIndex: number; endIndex: number }) =>
+    Array.from({ length: endIndex - startIndex + 1 }, (_, index) => startIndex + index),
+  measureElement: () => 32,
+  useVirtualizer: ({ count }: { count: number }) => ({
+    elementsCache: new Map(),
+    getTotalSize: () => count * 96,
+    getVirtualItems: () =>
+      Array.from({ length: count }, (_, index) => ({
+        index,
+        key: `row-${index}`,
+        start: index * 96
+      })),
+    measureElement: vi.fn(),
+    scrollToIndex: vi.fn()
+  })
+}))
+
+vi.mock('@/hooks/useVirtualizedScrollAnchor', () => ({
+  VIRTUALIZED_SCROLL_ANCHOR_RECORD_EVENT: 'orca:test-record-scroll-anchor',
+  useVirtualizedScrollAnchor: vi.fn()
+}))
+
+vi.mock('./project-header-drag', () => ({
+  useRepoHeaderDrag: () => ({
+    state: { draggingRepoId: null, dropIndicatorY: null },
+    onHandlePointerDown: vi.fn()
+  }),
+  isRepoHeaderActionTarget: () => false
+}))
+
+vi.mock('@/components/ui/hover-card', () => ({
+  HoverCard: ({ children }: { children: ReactNode }) => <>{children}</>,
+  HoverCardContent: ({ children }: { children: ReactNode }) => (
+    <div data-hover-card-content="">{children}</div>
+  ),
+  HoverCardTrigger: ({ children }: { children: ReactNode }) => <>{children}</>
+}))
+
+vi.mock('@/components/ui/tooltip', () => ({
+  Tooltip: ({ children }: { children: ReactNode }) => <>{children}</>,
+  TooltipContent: ({ children }: { children: ReactNode }) => <>{children}</>,
+  TooltipTrigger: ({ children }: { children: ReactNode }) => <>{children}</>
+}))
+
+vi.mock('@/components/ui/dropdown-menu', () => ({
+  DropdownMenu: ({ children }: { children: ReactNode }) => <>{children}</>,
+  DropdownMenuContent: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  DropdownMenuItem: ({ children, onSelect }: { children: ReactNode; onSelect?: () => void }) => (
+    <button onClick={onSelect}>{children}</button>
+  ),
+  DropdownMenuSeparator: () => <hr />,
+  DropdownMenuSub: ({ children }: { children: ReactNode }) => <>{children}</>,
+  DropdownMenuSubContent: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  DropdownMenuSubTrigger: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  DropdownMenuTrigger: ({ children }: { children: ReactNode }) => <>{children}</>
+}))
+
+vi.mock('@/lib/sidebar-worktree-activation', () => ({
+  activateWorktreeFromSidebar: mockStore.activateWorktreeFromSidebar
+}))
+
+vi.mock('@/lib/worktree-activation', () => ({
+  activateAndRevealWorktree: vi.fn()
+}))
+
+vi.mock('@/runtime/runtime-rpc-client', () => ({
+  getActiveRuntimeTarget: () => ({ kind: 'local' }),
+  callRuntimeRpc: vi.fn()
+}))
+
+vi.mock('./CacheTimer', () => ({
+  default: () => null,
+  usePromptCacheCountdownStartedAt: () => null
+}))
+
+vi.mock('./WorktreeCardAgents', () => ({
+  default: ({ worktreeId }: { worktreeId: string }) => (
+    <div data-agent-worktree-id={worktreeId}>Agent row</div>
+  ),
+  SUPPRESS_WORKTREE_LIST_SCROLL_ADJUSTMENT_EVENT: 'orca:test-suppress-scroll-adjustment'
+}))
+
+vi.mock('./SshDisconnectedDialog', () => ({
+  SshDisconnectedDialog: () => null
+}))
+
+vi.mock('./WorktreeContextMenu', () => ({
+  default: ({ children }: { children: ReactNode }) => <>{children}</>,
+  CLOSE_ALL_CONTEXT_MENUS_EVENT: 'orca:test-close-context-menus',
+  WORKTREE_CONTEXT_MENU_SCOPE_ATTR: 'data-orca-context-menu-scope',
+  WORKTREE_NATIVE_CONTEXT_MENU_ATTR: 'data-worktree-native-context-menu'
+}))
+
+function makeRepo(): Repo {
+  return {
+    id: 'repo-1',
+    path: '/tmp/status-lane-lineage',
+    displayName: 'status-lane-lineage',
+    badgeColor: '#999999',
+    addedAt: 1
+  }
+}
+
+function makeWorktree(args: {
+  id: string
+  displayName: string
+  branch: string
+  sortOrder: number
+  instanceId: string
+  workspaceStatus: WorkspaceStatus
+}): Worktree {
+  return {
+    id: args.id,
+    instanceId: args.instanceId,
+    repoId: 'repo-1',
+    path: `/tmp/status-lane-lineage/${args.id}`,
+    displayName: args.displayName,
+    branch: args.branch,
+    head: 'abc123',
+    isBare: false,
+    isMainWorktree: false,
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: args.sortOrder,
+    lastActivityAt: args.sortOrder,
+    workspaceStatus: args.workspaceStatus
+  }
+}
+
+function makeLineage(worktree: Worktree, parent: Worktree): WorktreeLineage {
+  return {
+    worktreeId: worktree.id,
+    worktreeInstanceId: worktree.instanceId!,
+    parentWorktreeId: parent.id,
+    parentWorktreeInstanceId: parent.instanceId!,
+    origin: 'orchestration',
+    capture: { source: 'orchestration-context', confidence: 'explicit' },
+    createdAt: 1
+  }
+}
+
+function makeFolderWorkspacePathStatusState(): Record<string, unknown> {
+  return {
+    fetchFolderWorkspacePathStatus: vi.fn(),
+    folderWorkspacePathStatuses: {},
+    folderWorkspaces: [],
+    getFolderWorkspacePathStatusCacheKey: (request: unknown) => JSON.stringify(request),
+    getFreshFolderWorkspacePathStatus: vi.fn(() => null)
+  }
+}
+
+// Grouped by workspace status: parent + its visible lineage child both live in the
+// "in-progress" lane; an unrelated bystander sits in "todo".
+function setStatusLaneState(): void {
+  const repo = makeRepo()
+  const parent = makeWorktree({
+    id: 'parent',
+    instanceId: 'parent-instance',
+    displayName: 'lineage parent',
+    branch: 'parent-branch',
+    sortOrder: 30,
+    workspaceStatus: 'in-progress'
+  })
+  const child = makeWorktree({
+    id: 'child',
+    instanceId: 'child-instance',
+    displayName: 'lineage child',
+    branch: 'child-branch',
+    sortOrder: 20,
+    workspaceStatus: 'in-progress'
+  })
+  const bystander = makeWorktree({
+    id: 'bystander',
+    instanceId: 'bystander-instance',
+    displayName: 'bystander',
+    branch: 'bystander-branch',
+    sortOrder: 10,
+    workspaceStatus: 'todo'
+  })
+  mockStore.state = {
+    ...makeFolderWorkspacePathStatusMockState(),
+    activeModal: '',
+    activeView: 'terminal',
+    activeWorktreeId: null,
+    agentStatusByPaneKey: {},
+    agentStatusEpoch: 0,
+    browserTabsByWorktree: {},
+    clearPendingRevealWorktreeId: vi.fn(),
+    collapsedGroups: new Set<string>(),
+    deleteStateByWorktreeId: {},
+    detectedWorktreesByRepo: {},
+    fetchHostedReviewForBranch: mockStore.fetchHostedReviewForBranch,
+    fetchIssue: mockStore.fetchIssue,
+    fetchLinearIssue: mockStore.fetchLinearIssue,
+    filterRepoIds: [],
+    ...makeFolderWorkspacePathStatusState(),
+    gitConflictOperationByWorktree: {},
+    groupBy: 'workspace-status',
+    hideDefaultBranchWorkspace: false,
+    hostedReviewCache: {},
+    issueCache: {},
+    linearIssueCache: {},
+    linearStatus: null,
+    migrationUnsupportedByPtyId: {},
+    openModal: mockStore.openModal,
+    openSettingsPage: vi.fn(),
+    openSettingsTarget: null,
+    openTaskPage: mockStore.openTaskPage,
+    pendingRevealWorktree: null,
+    prCache: {},
+    projectGroups: [],
+    ptyIdsByTabId: {},
+    recordFeatureInteraction: vi.fn(),
+    remoteBranchConflictByWorktreeId: {},
+    reorderRepos: vi.fn(),
+    reportVisibleGitHubPRRefreshCandidates: vi.fn(),
+    repos: [repo],
+    retainedAgentsByPaneKey: {},
+    revealWorktreeInSidebar: vi.fn(),
+    runtimePaneTitlesByTabId: {},
+    setFilterRepoIds: vi.fn(),
+    setHideDefaultBranchWorkspace: vi.fn(),
+    setRenamingWorktreeId: vi.fn(),
+    setShowSleepingWorkspaces: vi.fn(),
+    setSortBy: mockStore.setSortBy,
+    setWorktreesPinnedAndReveal: vi.fn(),
+    settings: null,
+    showSleepingWorkspaces: true,
+    sortBy: 'manual',
+    sortEpoch: 0,
+    sshConnectedGeneration: 0,
+    sshConnectionStates: new Map(),
+    sshTargetLabels: new Map(),
+    tabsByWorktree: {},
+    terminalLayoutsByTabId: {},
+    toggleCollapsedGroup: vi.fn(),
+    updateRepo: vi.fn(),
+    updateWorktreeMeta: mockStore.updateWorktreeMeta,
+    updateWorktreesMeta: mockStore.updateWorktreesMeta,
+    workspaceHostScope: 'all',
+    workspacePortScan: null,
+    workspaceStatuses: [...DEFAULT_WORKSPACE_STATUSES],
+    worktreeCardProperties: [
+      'status',
+      'pr',
+      'comment',
+      'inline-agents'
+    ] satisfies WorktreeCardProperty[],
+    worktreeLineageById: { [child.id]: makeLineage(child, parent) },
+    worktreesByRepo: { [repo.id]: [parent, child, bystander] }
+  }
+}
+
+const mountedRoots: Root[] = []
+
+async function renderWorktreeList(): Promise<HTMLDivElement> {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  mountedRoots.push(root)
+  await act(async () => {
+    root.render(
+      <WorktreeList scrollOffsetRef={{ current: 0 }} scrollAnchorRef={{ current: null }} />
+    )
+  })
+  return container
+}
+
+// A minimal DataTransfer stand-in: the native-drop commit path only reads the
+// worktree-id payloads and the type list off it.
+function makeWorktreeIdDataTransfer(worktreeIds: readonly string[]): DataTransfer {
+  const [firstId] = worktreeIds
+  const data: Record<string, string> = {
+    [WORKSPACE_STATUS_DRAG_TYPE]: firstId ?? '',
+    [WORKSPACE_STATUS_DRAG_IDS_TYPE]: JSON.stringify(worktreeIds),
+    'text/plain': firstId ?? ''
+  }
+  return {
+    effectAllowed: 'move',
+    types: Object.keys(data),
+    getData: (type: string) => data[type] ?? '',
+    setData: () => {}
+  } as unknown as DataTransfer
+}
+
+function findStatusLaneHeader(container: HTMLElement, status: WorkspaceStatus): HTMLElement {
+  const header = container.querySelector<HTMLElement>(
+    `[data-workspace-status-drop-target][data-workspace-status="${status}"]`
+  )
+  if (!header) {
+    throw new Error(`No status lane header rendered for "${status}"`)
+  }
+  return header
+}
+
+async function dropWorktreesOnStatusLane(
+  header: HTMLElement,
+  worktreeIds: readonly string[]
+): Promise<void> {
+  const event = new Event('drop', { bubbles: true, cancelable: true })
+  Object.defineProperty(event, 'dataTransfer', {
+    value: makeWorktreeIdDataTransfer(worktreeIds)
+  })
+  await act(async () => {
+    header.dispatchEvent(event)
+  })
+}
+
+function committedStatusUpdates(): Map<string, Partial<WorktreeMeta>> {
+  expect(mockStore.updateWorktreesMeta).toHaveBeenCalledTimes(1)
+  return mockStore.updateWorktreesMeta.mock.calls[0]![0] as Map<string, Partial<WorktreeMeta>>
+}
+
+describe('WorktreeList status-lane drop carries visible lineage children (#9083)', () => {
+  beforeAll(async () => {
+    WorktreeList = (await import('./WorktreeList')).default as WorktreeListComponent
+  }, 60_000)
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setStatusLaneState()
+  })
+
+  afterEach(async () => {
+    await act(async () => {
+      for (const root of mountedRoots.splice(0)) {
+        root.unmount()
+      }
+    })
+    document.body.innerHTML = ''
+  })
+
+  it('moves a dragged parent and its visible lineage child to the dropped lane', async () => {
+    const container = await renderWorktreeList()
+    const todoHeader = findStatusLaneHeader(container, 'todo')
+
+    // Only the parent id rides on the native drag payload; the wrapper must expand it.
+    await dropWorktreesOnStatusLane(todoHeader, ['parent'])
+
+    const updates = committedStatusUpdates()
+    expect(updates.get('parent')).toEqual({ workspaceStatus: 'todo' })
+    expect(updates.get('child')).toEqual({ workspaceStatus: 'todo' })
+  })
+
+  it('leaves worktrees in other lanes untouched', async () => {
+    const container = await renderWorktreeList()
+    const todoHeader = findStatusLaneHeader(container, 'todo')
+
+    await dropWorktreesOnStatusLane(todoHeader, ['parent'])
+
+    const updates = committedStatusUpdates()
+    expect(updates.has('bystander')).toBe(false)
+    expect(updates.size).toBe(2)
+  })
+
+  it('commits only itself when a childless worktree is dropped onto another lane', async () => {
+    const container = await renderWorktreeList()
+    const inProgressHeader = findStatusLaneHeader(container, 'in-progress')
+
+    await dropWorktreesOnStatusLane(inProgressHeader, ['bystander'])
+
+    const updates = committedStatusUpdates()
+    expect(updates.get('bystander')).toEqual({
+      workspaceStatus: 'in-progress'
+    })
+    expect(updates.has('parent')).toBe(false)
+    expect(updates.has('child')).toBe(false)
+    expect(updates.size).toBe(1)
+  })
+})
diff --git a/src/renderer/src/components/sidebar/WorktreeList.tsx b/src/renderer/src/components/sidebar/WorktreeList.tsx
index e73e9142f3e..137f364e084 100644
--- a/src/renderer/src/components/sidebar/WorktreeList.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeList.tsx
@@ -2844,7 +2844,8 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
       y: drag.currentY,
       shouldShowDropIndicator: (target) =>
         Boolean(
-          target.status && shouldShowWorkspaceBoardDropIndicator(drag.draggedIds, target.status)
+          target.status &&
+          shouldShowWorkspaceBoardDropIndicator(drag.reorderDraggedIds, target.status)
         )
     })
     drag.latestBoardDropTarget = {
@@ -2919,7 +2920,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         ? computeWorktreeStatusDrop({
             pointerY: drag.currentY,
             status: preferredStatusTarget.status,
-            draggedIds: drag.draggedIds
+            draggedIds: drag.reorderDraggedIds
           })
         : null
       if (statusDrop) {
@@ -2967,7 +2968,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         ? computeWorktreeStatusDrop({
             pointerY: drag.currentY,
             status: target.status,
-            draggedIds: drag.draggedIds
+            draggedIds: drag.reorderDraggedIds
           })
         : null
       if (statusDrop) {
@@ -3258,7 +3259,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         onPinWorktrees(drag.draggedIds)
       } else if (boardDropTarget.status) {
         onDropWorktreesOnWorkspaceBoard({
-          worktreeIds: drag.draggedIds,
+          worktreeIds: drag.reorderDraggedIds,
           status: boardDropTarget.status,
           dropIndex: boardDropTarget.dropIndex,
           groups: getWorkspaceKanbanSidebarDropGroups()
@@ -3290,7 +3291,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
             ? computeWorktreeStatusDrop({
                 pointerY: event.clientY,
                 status: preferredStatusTarget.status,
-                draggedIds: drag.draggedIds
+                draggedIds: drag.reorderDraggedIds
               })
             : null
           if (preferredStatusTarget.isPinDrop) {
@@ -3298,13 +3299,13 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
           } else if (preferredStatusTarget.status) {
             if (statusDrop) {
               onMoveWorktreesToStatusAtIndex({
-                worktreeIds: drag.draggedIds,
+                worktreeIds: drag.reorderDraggedIds,
                 status: preferredStatusTarget.status,
                 dropIndex: statusDrop.dropIndex,
                 groups: worktreeDragGroups
               })
             } else {
-              onMoveWorktreesToStatus(drag.draggedIds, preferredStatusTarget.status)
+              onMoveWorktreesToStatus(drag.reorderDraggedIds, preferredStatusTarget.status)
             }
           }
           clearWorktreeDrag()
@@ -3332,7 +3333,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
             ? computeWorktreeStatusDrop({
                 pointerY: event.clientY,
                 status: currentTarget.status,
-                draggedIds: drag.draggedIds
+                draggedIds: drag.reorderDraggedIds
               })
             : null
           const { target, preview: statusDrop } = resolveWorktreeSidebarStatusDropCommitTarget({
@@ -3349,13 +3350,13 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
           } else if (target.status) {
             if (statusDrop) {
               onMoveWorktreesToStatusAtIndex({
-                worktreeIds: drag.draggedIds,
+                worktreeIds: drag.reorderDraggedIds,
                 status: target.status,
                 dropIndex: statusDrop.dropIndex,
                 groups: worktreeDragGroups
               })
             } else {
-              onMoveWorktreesToStatus(drag.draggedIds, target.status)
+              onMoveWorktreesToStatus(drag.reorderDraggedIds, target.status)
             }
           }
         }
@@ -3454,7 +3455,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
             ? computeWorktreeStatusDrop({
                 pointerY: point.clientY,
                 status: target.status,
-                draggedIds: session.draggedIds
+                draggedIds: session.reorderDraggedIds
               })
             : null
           if (statusDrop) {
@@ -3603,7 +3604,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
           ? computeWorktreeStatusDrop({
               pointerY: event.clientY,
               status: target.status,
-              draggedIds: session.draggedIds
+              draggedIds: session.reorderDraggedIds
             })
           : null
         if (statusDrop) {
@@ -3701,14 +3702,14 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
           ? computeWorktreeStatusDrop({
               pointerY: event.clientY,
               status: target.status,
-              draggedIds: session.draggedIds
+              draggedIds: session.reorderDraggedIds
             })
           : null
         if (target.status && statusDrop) {
           event.preventDefault()
           event.stopPropagation()
           onMoveWorktreesToStatusAtIndex({
-            worktreeIds: session.draggedIds,
+            worktreeIds: session.reorderDraggedIds,
             status: target.status,
             dropIndex: statusDrop.dropIndex,
             groups: worktreeDragGroups
@@ -3896,14 +3897,14 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         ? computeWorktreeStatusDrop({
             pointerY: event.clientY,
             status,
-            draggedIds: session.draggedIds
+            draggedIds: session.reorderDraggedIds
           })
         : null
       setDragOverStatus(null)
       if (session && statusDrop) {
         event.stopPropagation()
         onMoveWorktreesToStatusAtIndex({
-          worktreeIds: session.draggedIds,
+          worktreeIds: session.reorderDraggedIds,
           status,
           dropIndex: statusDrop.dropIndex,
           groups: worktreeDragGroups
@@ -3911,11 +3912,17 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         clearWorktreeDrag()
         return
       }
-      onMoveWorktreesToStatus(worktreeIds, status)
+      // Match the status-drop scope to the drag-preview scope (#9083): with a live session use its
+      // precomputed expanded set; the session-less foreign-origin case expands the dataTransfer ids live.
+      onMoveWorktreesToStatus(
+        session ? session.reorderDraggedIds : getReorderDraggedIds(worktreeIds),
+        status
+      )
     },
     [
       clearWorktreeDrag,
       computeWorktreeStatusDrop,
+      getReorderDraggedIds,
       onMoveWorktreesToStatus,
       onMoveWorktreesToStatusAtIndex,
       worktreeDragGroups
@@ -3956,14 +3963,14 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
           ? computeWorktreeStatusDrop({
               pointerY: event.clientY,
               status: target.status,
-              draggedIds: session.draggedIds
+              draggedIds: session.reorderDraggedIds
             })
           : null
         if (target.status && statusDrop) {
           event.preventDefault()
           event.stopPropagation()
           onMoveWorktreesToStatusAtIndex({
-            worktreeIds: session.draggedIds,
+            worktreeIds: session.reorderDraggedIds,
             status: target.status,
             dropIndex: statusDrop.dropIndex,
             groups: worktreeDragGroups
@@ -4034,6 +4041,15 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     return () => document.removeEventListener('visibilitychange', handleVisibilityChange)
   }, [clearWorktreeDrag])
 
+  // Why: this session-less capture-phase committer is the primary native-drop path in packaged
+  // Electron. Expand at this call site (not in the shared hook, which WorkspaceKanbanDrawer uses for
+  // its flat board) so a dropped parent carries its visible lineage children (#9083).
+  const moveWorktreesToStatusForDocumentDrop = useCallback(
+    (ids: readonly string[], status: WorkspaceStatus) =>
+      onMoveWorktreesToStatus(getReorderDraggedIds(ids), status),
+    [getReorderDraggedIds, onMoveWorktreesToStatus]
+  )
+
   useWorkspaceStatusDocumentDrop(
     scrollRef,
     onMoveWorktreeToStatus,
@@ -4041,7 +4057,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     handleWorkspaceStatusDragFinish,
     hasWorkspaceDropTargets,
     {
-      onMoveWorktreesToStatus,
+      onMoveWorktreesToStatus: moveWorktreesToStatusForDocumentDrop,
       onPinWorktrees
     }
   )

From 85ab72901be1ca4c8dc59eaf00025905ed7bdc8c Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Sun, 19 Jul 2026 16:35:26 -0700
Subject: [PATCH 12/54] Persist the AI Vault session parse cache across
 restarts (#9474)

Cold launches re-parsed the entire agent-transcript corpus (measured
6.7 GB / 109 s upstream; 1.79 GB / 3.7 s locally) because the parse
cache was an in-memory Map. Persist the reusable portion (mtime+size
gated session entries, resume states dropped) to one JSON file under
the canonical userData dir: lazy load before the first scan, debounced
atomic save after scans that parsed anything. Restart scans now reuse
unchanged files (measured 328 ms / 3 MB, reused=1036).
---
 .../session-parse-cache-persistence.test.ts   | 437 ++++++++++++++++++
 .../session-parse-cache-persistence.ts        | 209 +++++++++
 .../ai-vault/session-scanner-parse-cache.ts   |  46 ++
 src/main/ai-vault/session-scanner.ts          |   9 +
 src/main/index.ts                             |   8 +
 5 files changed, 709 insertions(+)
 create mode 100644 src/main/ai-vault/session-parse-cache-persistence.test.ts
 create mode 100644 src/main/ai-vault/session-parse-cache-persistence.ts

diff --git a/src/main/ai-vault/session-parse-cache-persistence.test.ts b/src/main/ai-vault/session-parse-cache-persistence.test.ts
new file mode 100644
index 00000000000..4d7aa7113d6
--- /dev/null
+++ b/src/main/ai-vault/session-parse-cache-persistence.test.ts
@@ -0,0 +1,437 @@
+import { existsSync } from 'node:fs'
+import {
+  appendFile,
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rm,
+  stat,
+  utimes,
+  writeFile
+} from 'node:fs/promises'
+import * as fsPromises from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  ensureSessionParseCacheLoaded,
+  flushSessionParseCachePersistForTests,
+  initSessionParseCachePersistence,
+  resetSessionParseCachePersistenceForTests,
+  scheduleSessionParseCachePersist
+} from './session-parse-cache-persistence'
+import { scanAiVaultSessions } from './session-scanner'
+import {
+  createSessionParseStats,
+  parseAgentSessionFileCached,
+  resetSessionParseCacheForTests,
+  seedSessionParseCache,
+  type PersistedSessionParseCacheEntry,
+  type SessionParseStats
+} from './session-scanner-parse-cache'
+import { isolatedScanRoots } from './session-scanner-test-fixtures'
+import { parseClaudeSessionFile } from './session-scanner-primary-parsers'
+import type { FileWithMtime, SessionFileCandidate } from './session-scanner-types'
+
+// Spy-wrap (real implementations still run) so the zero-disk-IO test can
+// assert the uninitialized module never touches the filesystem.
+vi.mock('node:fs/promises', { spy: true })
+
+const APP_VERSION = '1.2.3-test'
+
+let tempRoots: string[] = []
+
+beforeEach(() => {
+  resetSessionParseCacheForTests()
+  resetSessionParseCachePersistenceForTests()
+})
+
+afterEach(async () => {
+  resetSessionParseCachePersistenceForTests()
+  await Promise.all(tempRoots.map((root) => rm(root, { recursive: true, force: true })))
+  tempRoots = []
+})
+
+async function makeTempDir(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'orca-parse-cache-persist-'))
+  tempRoots.push(root)
+  return root
+}
+
+async function claudeCandidate(path: string): Promise<SessionFileCandidate> {
+  const fileStat = await stat(path)
+  const file: FileWithMtime = {
+    path,
+    mtimeMs: fileStat.mtimeMs,
+    modifiedAt: fileStat.mtime.toISOString(),
+    sizeBytes: fileStat.size
+  }
+  return { agent: 'claude', file, codexHome: null }
+}
+
+function userRecord(index: number, text: string): string {
+  return JSON.stringify({
+    type: 'user',
+    sessionId: 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee',
+    timestamp: new Date(1740000000000 + index * 60_000).toISOString(),
+    cwd: '/repo/app',
+    gitBranch: 'main',
+    message: { role: 'user', content: text }
+  })
+}
+
+function assistantRecord(index: number, text: string): string {
+  return JSON.stringify({
+    type: 'assistant',
+    sessionId: 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee',
+    timestamp: new Date(1740000000000 + index * 60_000).toISOString(),
+    message: {
+      role: 'assistant',
+      model: 'claude-fable-5',
+      content: [{ type: 'text', text }],
+      usage: { input_tokens: 100, output_tokens: 40 }
+    }
+  })
+}
+
+async function writeTranscript(root: string): Promise<string> {
+  const path = join(root, 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee.jsonl')
+  await writeFile(path, `${userRecord(0, 'first question')}\n${assistantRecord(1, 'answer')}\n`)
+  return path
+}
+
+async function parseAndPersist(path: string): Promise<SessionParseStats> {
+  const stats = createSessionParseStats()
+  await ensureSessionParseCacheLoaded()
+  await parseAgentSessionFileCached(await claudeCandidate(path), process.platform, stats)
+  scheduleSessionParseCachePersist(stats)
+  await flushSessionParseCachePersistForTests()
+  return stats
+}
+
+// Clear the in-memory cache and the persistence module's memoized state, then
+// re-enable persistence against the same file — a fresh launch, same profile.
+function simulateRestart(cacheFile: string, appVersion = APP_VERSION): void {
+  resetSessionParseCacheForTests()
+  resetSessionParseCachePersistenceForTests()
+  initSessionParseCachePersistence({ filePath: cacheFile, appVersion })
+}
+
+async function coldParseStats(path: string): Promise<SessionParseStats> {
+  const stats = createSessionParseStats()
+  await ensureSessionParseCacheLoaded()
+  await parseAgentSessionFileCached(await claudeCandidate(path), process.platform, stats)
+  return stats
+}
+
+describe('session parse cache persistence', () => {
+  it('round-trips: a persisted entry is a reused hit after a restart, without reading the transcript', async () => {
+    const root = await makeTempDir()
+    const cacheFile = join(root, 'vault-state', 'session-parse-cache.json')
+    initSessionParseCachePersistence({ filePath: cacheFile, appVersion: APP_VERSION })
+
+    const transcript = await writeTranscript(root)
+    const candidate = await claudeCandidate(transcript)
+    const stats = createSessionParseStats()
+    await ensureSessionParseCacheLoaded()
+    const first = await parseAgentSessionFileCached(candidate, process.platform, stats)
+    expect(first).not.toBeNull()
+    expect(stats.fullParses).toBe(1)
+
+    scheduleSessionParseCachePersist(stats)
+    await flushSessionParseCachePersistForTests()
+    expect(existsSync(cacheFile)).toBe(true)
+
+    simulateRestart(cacheFile)
+    await ensureSessionParseCacheLoaded()
+
+    // Deleting the transcript proves the hit needs no transcript read at all.
+    await rm(transcript)
+    const reusedStats = createSessionParseStats()
+    const reused = await parseAgentSessionFileCached(candidate, process.platform, reusedStats)
+    expect(reusedStats.reused).toBe(1)
+    expect(reusedStats.fullParses).toBe(0)
+    expect(reusedStats.incremental).toBe(0)
+    expect(reusedStats.bytesRead).toBe(0)
+    expect(reused).toEqual(first)
+  })
+
+  it('ignores a corrupt cache file and scans cold', async () => {
+    const root = await makeTempDir()
+    const cacheFile = join(root, 'session-parse-cache.json')
+    await writeFile(cacheFile, 'not json {{{')
+    initSessionParseCachePersistence({ filePath: cacheFile, appVersion: APP_VERSION })
+
+    const transcript = await writeTranscript(root)
+    const stats = await coldParseStats(transcript)
+    expect(stats.fullParses).toBe(1)
+    expect(stats.reused).toBe(0)
+  })
+
+  it('ignores a cache file with a mismatched schemaVersion', async () => {
+    const root = await makeTempDir()
+    const cacheFile = join(root, 'session-parse-cache.json')
+    initSessionParseCachePersistence({ filePath: cacheFile, appVersion: APP_VERSION })
+    const transcript = await writeTranscript(root)
+    await parseAndPersist(transcript)
+
+    const persisted = JSON.parse(await readFile(cacheFile, 'utf-8'))
+    persisted.schemaVersion = 999
+    await writeFile(cacheFile, JSON.stringify(persisted))
+
+    simulateRestart(cacheFile)
+    const stats = await coldParseStats(transcript)
+    expect(stats.fullParses).toBe(1)
+    expect(stats.reused).toBe(0)
+  })
+
+  it('ignores a cache file written by a different app version', async () => {
+    const root = await makeTempDir()
+    const cacheFile = join(root, 'session-parse-cache.json')
+    initSessionParseCachePersistence({ filePath: cacheFile, appVersion: APP_VERSION })
+    const transcript = await writeTranscript(root)
+    await parseAndPersist(transcript)
+
+    simulateRestart(cacheFile, '9.9.9-other')
+    const stats = await coldParseStats(transcript)
+    expect(stats.fullParses).toBe(1)
+    expect(stats.reused).toBe(0)
+  })
+
+  it('seeding never clobbers a live in-memory entry', async () => {
+    const root = await makeTempDir()
+    const transcript = await writeTranscript(root)
+    const candidate = await claudeCandidate(transcript)
+    const live = await parseAgentSessionFileCached(candidate, process.platform)
+    expect(live).not.toBeNull()
+
+    // A stale persisted entry for the same path (session: null marker).
+    seedSessionParseCache([
+      [
+        transcript,
+        {
+          mtimeMs: candidate.file.mtimeMs,
+          sizeBytes: candidate.file.sizeBytes ?? null,
+          platform: process.platform,
+          session: null
+        }
+      ]
+    ])
+
+    const stats = createSessionParseStats()
+    const after = await parseAgentSessionFileCached(candidate, process.platform, stats)
+    expect(stats.reused).toBe(1)
+    expect(after).toBe(live)
+  })
+
+  it('falls through to a full parse when a seeded file changed while the app was closed', async () => {
+    const root = await makeTempDir()
+    const cacheFile = join(root, 'session-parse-cache.json')
+    initSessionParseCachePersistence({ filePath: cacheFile, appVersion: APP_VERSION })
+    const transcript = await writeTranscript(root)
+    await parseAndPersist(transcript)
+
+    simulateRestart(cacheFile)
+    await ensureSessionParseCacheLoaded()
+
+    // Grown while "closed": seeded entries have no resume state, so this is a
+    // full parse (not incremental) whose result matches a cold parse.
+    await appendFile(transcript, `${userRecord(2, 'follow-up')}\n${assistantRecord(3, 'more')}\n`)
+    const stats = createSessionParseStats()
+    const reparsed = await parseAgentSessionFileCached(
+      await claudeCandidate(transcript),
+      process.platform,
+      stats
+    )
+    expect(stats.fullParses).toBe(1)
+    expect(stats.incremental).toBe(0)
+    expect(stats.reused).toBe(0)
+    expect(reparsed).toEqual(await parseClaudeSessionFile((await claudeCandidate(transcript)).file))
+    expect(reparsed?.messageCount).toBe(4)
+  })
+
+  it('performs zero disk IO when never initialized', async () => {
+    vi.clearAllMocks()
+
+    await ensureSessionParseCacheLoaded()
+    scheduleSessionParseCachePersist({ reused: 0, incremental: 2, fullParses: 5, bytesRead: 10 })
+    await flushSessionParseCachePersistForTests()
+
+    expect(fsPromises.readFile).not.toHaveBeenCalled()
+    expect(fsPromises.writeFile).not.toHaveBeenCalled()
+    expect(fsPromises.mkdir).not.toHaveBeenCalled()
+    expect(fsPromises.rename).not.toHaveBeenCalled()
+    expect(fsPromises.rm).not.toHaveBeenCalled()
+  })
+
+  it('collapses back-to-back schedules into one write', async () => {
+    const root = await makeTempDir()
+    const cacheFile = join(root, 'session-parse-cache.json')
+    initSessionParseCachePersistence({ filePath: cacheFile, appVersion: APP_VERSION })
+    const transcript = await writeTranscript(root)
+    const stats = await coldParseStats(transcript)
+
+    vi.clearAllMocks()
+    scheduleSessionParseCachePersist(stats)
+    scheduleSessionParseCachePersist(stats)
+    await flushSessionParseCachePersistForTests()
+
+    expect(fsPromises.rename).toHaveBeenCalledTimes(1)
+    expect(existsSync(cacheFile)).toBe(true)
+  })
+
+  it('sweeps orphaned temp files from a prior crashed save on load', async () => {
+    const root = await makeTempDir()
+    const cacheFile = join(root, 'session-parse-cache.json')
+    const orphan = join(root, 'session-parse-cache-12345-99.tmp')
+    await writeFile(orphan, '{"half":"written')
+    initSessionParseCachePersistence({ filePath: cacheFile, appVersion: APP_VERSION })
+
+    await ensureSessionParseCacheLoaded()
+    expect(existsSync(orphan)).toBe(false)
+  })
+
+  it('scanAiVaultSessions seeds from the persisted cache and persists after parsing', async () => {
+    const root = await makeTempDir()
+    const cacheFile = join(root, 'session-parse-cache.json')
+    initSessionParseCachePersistence({ filePath: cacheFile, appVersion: APP_VERSION })
+    const roots = isolatedScanRoots(root)
+    const transcript = join(roots.claudeProjectsDir, 'project', 'scan-session.jsonl')
+    await mkdir(join(roots.claudeProjectsDir, 'project'), { recursive: true })
+    // Same-length markers so the rewrite below preserves sizeBytes exactly.
+    await writeFile(
+      transcript,
+      `${userRecord(0, 'persisted-scan-marker-AAAA')}\n${assistantRecord(1, 'answer')}\n`
+    )
+    const pinnedMtime = new Date(1740000000000)
+    await utimes(transcript, pinnedMtime, pinnedMtime)
+
+    const first = await scanAiVaultSessions(roots)
+    expect(first.sessions).toHaveLength(1)
+    expect(JSON.stringify(first.sessions[0])).toContain('persisted-scan-marker-AAAA')
+    // The scan itself (not a manual schedule call) must have queued the save.
+    await flushSessionParseCachePersistForTests()
+    expect(existsSync(cacheFile)).toBe(true)
+
+    simulateRestart(cacheFile)
+    // Rewrite with identical length and mtime: only a seeded cache hit can
+    // still return the original marker; a cold re-parse would see BBBB.
+    await writeFile(
+      transcript,
+      `${userRecord(0, 'persisted-scan-marker-BBBB')}\n${assistantRecord(1, 'answer')}\n`
+    )
+    await utimes(transcript, pinnedMtime, pinnedMtime)
+
+    const second = await scanAiVaultSessions(roots)
+    expect(second.sessions).toHaveLength(1)
+    expect(JSON.stringify(second.sessions[0])).toContain('persisted-scan-marker-AAAA')
+    expect(second.sessions[0]).toEqual(first.sessions[0])
+  })
+
+  it('an over-cap seed list keeps the newest tail of the snapshot order', async () => {
+    const root = await makeTempDir()
+    const transcript = await writeTranscript(root)
+    const candidate = await claudeCandidate(transcript)
+    // Snapshot order is oldest→newest, so a foreign over-cap file must keep
+    // its newest (last) entries; the real transcript rides at the very end.
+    const fakes: [string, PersistedSessionParseCacheEntry][] = Array.from(
+      { length: 4100 },
+      (_, index): [string, PersistedSessionParseCacheEntry] => [
+        `/nonexistent/fake-${index}.jsonl`,
+        { mtimeMs: index, sizeBytes: 1, platform: process.platform, session: null }
+      ]
+    )
+    seedSessionParseCache([
+      ...fakes,
+      [
+        transcript,
+        {
+          mtimeMs: candidate.file.mtimeMs,
+          sizeBytes: candidate.file.sizeBytes ?? null,
+          platform: process.platform,
+          session: null
+        }
+      ]
+    ])
+
+    const stats = createSessionParseStats()
+    await parseAgentSessionFileCached(candidate, process.platform, stats)
+    expect(stats.reused).toBe(1)
+    expect(stats.fullParses).toBe(0)
+  })
+
+  it('a failing rename cleans up its temp file and keeps the previous snapshot usable', async () => {
+    const root = await makeTempDir()
+    const cacheFile = join(root, 'session-parse-cache.json')
+    initSessionParseCachePersistence({ filePath: cacheFile, appVersion: APP_VERSION })
+    const transcript = await writeTranscript(root)
+    await parseAndPersist(transcript)
+    const previousSnapshot = await readFile(cacheFile, 'utf-8')
+
+    // A second session parsed after the good save; its save's rename is
+    // rejected (the Windows EPERM/EBUSY story: target held open elsewhere).
+    const other = join(root, 'ffffffff-bbbb-4ccc-8ddd-eeeeeeeeeeee.jsonl')
+    await writeFile(other, `${userRecord(2, 'second session')}\n${assistantRecord(3, 'reply')}\n`)
+    const stats = createSessionParseStats()
+    await parseAgentSessionFileCached(await claudeCandidate(other), process.platform, stats)
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {})
+    vi.mocked(fsPromises.rename).mockRejectedValueOnce(
+      Object.assign(new Error('EPERM: rename blocked'), { code: 'EPERM' })
+    )
+    scheduleSessionParseCachePersist(stats)
+    await expect(flushSessionParseCachePersistForTests()).resolves.toBeUndefined()
+    expect(debugSpy).toHaveBeenCalled()
+
+    // The temp file was written before the rename failed; it must not linger,
+    // and the previous snapshot must be byte-identical (never torn).
+    expect((await readdir(root)).filter((name) => name.endsWith('.tmp'))).toEqual([])
+    expect(await readFile(cacheFile, 'utf-8')).toBe(previousSnapshot)
+
+    // That intact previous snapshot still round-trips on the next launch.
+    simulateRestart(cacheFile)
+    await ensureSessionParseCacheLoaded()
+    const reusedStats = createSessionParseStats()
+    await parseAgentSessionFileCached(
+      await claudeCandidate(transcript),
+      process.platform,
+      reusedStats
+    )
+    expect(reusedStats.reused).toBe(1)
+    debugSpy.mockRestore()
+  })
+
+  it('swallows save failures and leaves scan results unaffected', async () => {
+    const root = await makeTempDir()
+    // A regular file where the cache directory should be makes mkdir fail on
+    // every platform (no chmod tricks, which don't hold on Windows or as root).
+    const blocker = join(root, 'blocker')
+    await writeFile(blocker, 'a file, not a directory')
+    initSessionParseCachePersistence({
+      filePath: join(blocker, 'session-parse-cache.json'),
+      appVersion: APP_VERSION
+    })
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {})
+
+    const transcript = await writeTranscript(root)
+    const candidate = await claudeCandidate(transcript)
+    const stats = createSessionParseStats()
+    await ensureSessionParseCacheLoaded()
+    const session = await parseAgentSessionFileCached(candidate, process.platform, stats)
+    expect(session).not.toBeNull()
+
+    scheduleSessionParseCachePersist(stats)
+    await expect(flushSessionParseCachePersistForTests()).resolves.toBeUndefined()
+    expect(debugSpy).toHaveBeenCalled()
+
+    // The in-memory cache still serves hits and no partial files were left behind.
+    const reusedStats = createSessionParseStats()
+    expect(await parseAgentSessionFileCached(candidate, process.platform, reusedStats)).toBe(
+      session
+    )
+    expect(reusedStats.reused).toBe(1)
+    expect(await readdir(root)).toEqual(expect.arrayContaining(['blocker']))
+    expect((await readdir(root)).filter((name) => name.endsWith('.tmp'))).toEqual([])
+    debugSpy.mockRestore()
+  })
+})
diff --git a/src/main/ai-vault/session-parse-cache-persistence.ts b/src/main/ai-vault/session-parse-cache-persistence.ts
new file mode 100644
index 00000000000..f4a924bd82f
--- /dev/null
+++ b/src/main/ai-vault/session-parse-cache-persistence.ts
@@ -0,0 +1,209 @@
+// Persists the reusable portion of the AI Vault session parse cache to one
+// JSON file under userData so a fresh launch reuses prior parse work instead
+// of re-reading the whole transcript corpus (issue #9210: 6.7 GB / 109 s cold
+// scans). Disabled unless the composition root calls init; every failure mode
+// degrades to today's cold-scan behavior.
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import {
+  seedSessionParseCache,
+  snapshotSessionParseCacheForPersistence,
+  type PersistedSessionParseCacheEntry,
+  type SessionParseStats
+} from './session-scanner-parse-cache'
+
+// Bump when the persisted entry layout changes; a mismatched file is discarded whole.
+const SCHEMA_VERSION = 1
+// Debounce so back-to-back scans (desktop IPC + runtime RPC) collapse into one write.
+const SAVE_DEBOUNCE_MS = 1_500
+// The payload contains transcript-derived preview text; keep it user-only
+// (mode bits are inert on Windows — the userData ACL grant is the boundary there).
+const PRIVATE_DIRECTORY_MODE = 0o700
+const PRIVATE_FILE_MODE = 0o600
+
+type SessionParseCachePersistenceOptions = {
+  filePath: string
+  appVersion: string
+}
+
+let options: SessionParseCachePersistenceOptions | null = null
+let loadPromise: Promise<void> | null = null
+let saveTimer: NodeJS.Timeout | null = null
+let lastSave: Promise<void> = Promise.resolve()
+
+/** Enable persistence. Called only from the composition root; every export is a no-op until then. */
+export function initSessionParseCachePersistence(next: SessionParseCachePersistenceOptions): void {
+  options = next
+}
+
+export function resetSessionParseCachePersistenceForTests(): void {
+  options = null
+  loadPromise = null
+  if (saveTimer) {
+    clearTimeout(saveTimer)
+    saveTimer = null
+  }
+  lastSave = Promise.resolve()
+}
+
+/**
+ * Seed the in-memory parse cache from disk. Memoized: concurrent scans at
+ * startup all await the same load. Resolves immediately when uninitialized.
+ */
+export function ensureSessionParseCacheLoaded(): Promise<void> {
+  if (options === null) {
+    return Promise.resolve()
+  }
+  loadPromise ??= loadPersistedEntries(options)
+  return loadPromise
+}
+
+/**
+ * Schedule a debounced snapshot write after a scan that parsed something.
+ * Reused-only scans schedule no write (the file already reflects the cache).
+ */
+export function scheduleSessionParseCachePersist(stats: SessionParseStats): void {
+  if (options === null || stats.incremental + stats.fullParses <= 0) {
+    return
+  }
+  const current = options
+  if (saveTimer) {
+    clearTimeout(saveTimer)
+  }
+  saveTimer = setTimeout(() => {
+    saveTimer = null
+    // Chained so a slow write and a rescheduled save can't rename out of order
+    // (an older snapshot landing last); persistSnapshot never rejects.
+    lastSave = lastSave.then(() => persistSnapshot(current))
+  }, SAVE_DEBOUNCE_MS)
+  // Why: a pending cache save must not keep a quitting process alive.
+  if (typeof saveTimer.unref === 'function') {
+    saveTimer.unref()
+  }
+}
+
+/** Run any pending debounced save immediately and wait for it. Test-only. */
+export async function flushSessionParseCachePersistForTests(): Promise<void> {
+  if (saveTimer) {
+    clearTimeout(saveTimer)
+    saveTimer = null
+    if (options !== null) {
+      const current = options
+      lastSave = lastSave.then(() => persistSnapshot(current))
+    }
+  }
+  await lastSave
+}
+
+async function loadPersistedEntries(current: SessionParseCachePersistenceOptions): Promise<void> {
+  await sweepOrphanedTempFiles(current.filePath)
+  try {
+    const raw = await readFile(current.filePath, 'utf-8')
+    const entries = parsePersistedFile(JSON.parse(raw), current.appVersion)
+    if (entries) {
+      seedSessionParseCache(entries)
+    }
+  } catch {
+    // Why: a missing/corrupt/foreign cache file must never fail the scan;
+    // worst case is exactly today's cold scan.
+  }
+}
+
+// A death between temp-write and rename orphans a uniquely named .tmp forever;
+// sweep once per launch so they can't accumulate. Racing another instance's
+// in-flight save at worst loses that save — the already-accepted rename trade.
+async function sweepOrphanedTempFiles(filePath: string): Promise<void> {
+  const directory = dirname(filePath)
+  try {
+    const names = await readdir(directory)
+    await Promise.all(
+      names
+        .filter((name) => name.startsWith('session-parse-cache-') && name.endsWith('.tmp'))
+        .map((name) => rm(join(directory, name), { force: true }).catch(() => {}))
+    )
+  } catch {
+    // Directory missing or unreadable — nothing to sweep.
+  }
+}
+
+function parsePersistedFile(
+  parsed: unknown,
+  appVersion: string
+): [string, PersistedSessionParseCacheEntry][] | null {
+  if (typeof parsed !== 'object' || parsed === null) {
+    return null
+  }
+  const file = parsed as Record<string, unknown>
+  // Why: parser output shape/semantics may change between app versions, so a
+  // cross-version file is discarded — one cold scan per update is the price.
+  if (file.schemaVersion !== SCHEMA_VERSION || file.appVersion !== appVersion) {
+    return null
+  }
+  if (!Array.isArray(file.entries)) {
+    return null
+  }
+  const entries: [string, PersistedSessionParseCacheEntry][] = []
+  for (const item of file.entries) {
+    const entry = parsePersistedEntry(item)
+    if (entry === null) {
+      // One malformed entry means the file can't be trusted; discard it whole.
+      return null
+    }
+    entries.push(entry)
+  }
+  return entries
+}
+
+function parsePersistedEntry(item: unknown): [string, PersistedSessionParseCacheEntry] | null {
+  if (!Array.isArray(item) || item.length !== 2) {
+    return null
+  }
+  const [path, value] = item as [unknown, unknown]
+  if (typeof path !== 'string' || typeof value !== 'object' || value === null) {
+    return null
+  }
+  const entry = value as Record<string, unknown>
+  if (typeof entry.mtimeMs !== 'number') {
+    return null
+  }
+  if (entry.sizeBytes !== null && typeof entry.sizeBytes !== 'number') {
+    return null
+  }
+  if (typeof entry.platform !== 'string') {
+    return null
+  }
+  if (entry.session !== null && typeof entry.session !== 'object') {
+    return null
+  }
+  return [
+    path,
+    {
+      mtimeMs: entry.mtimeMs,
+      sizeBytes: entry.sizeBytes,
+      platform: entry.platform as NodeJS.Platform,
+      session: entry.session as PersistedSessionParseCacheEntry['session']
+    }
+  ]
+}
+
+async function persistSnapshot(current: SessionParseCachePersistenceOptions): Promise<void> {
+  const directory = dirname(current.filePath)
+  const tempPath = join(directory, `session-parse-cache-${process.pid}-${Date.now()}.tmp`)
+  try {
+    const payload = JSON.stringify({
+      schemaVersion: SCHEMA_VERSION,
+      appVersion: current.appVersion,
+      entries: snapshotSessionParseCacheForPersistence()
+    })
+    await mkdir(directory, { recursive: true, mode: PRIVATE_DIRECTORY_MODE })
+    await writeFile(tempPath, payload, { mode: PRIVATE_FILE_MODE })
+    // Atomic on POSIX; on Windows a rename racing an open handle fails and is
+    // caught below (save lost, never a torn file).
+    await rename(tempPath, current.filePath)
+  } catch (err) {
+    // Why: the save runs from a timer — every error must be swallowed here or
+    // it becomes an unhandled rejection. Worst case is the no-file case.
+    await rm(tempPath, { force: true }).catch(() => {})
+    console.debug('[ai-vault] session parse cache save failed', err)
+  }
+}
diff --git a/src/main/ai-vault/session-scanner-parse-cache.ts b/src/main/ai-vault/session-scanner-parse-cache.ts
index d42da123437..b7aab770432 100644
--- a/src/main/ai-vault/session-scanner-parse-cache.ts
+++ b/src/main/ai-vault/session-scanner-parse-cache.ts
@@ -97,6 +97,52 @@ export function resetSessionParseCacheForTests(): void {
   cache.clear()
 }
 
+// Persisted subset of a cache entry: the non-serializable `resume` parser
+// state is dropped (see session-parse-cache-persistence.ts).
+export type PersistedSessionParseCacheEntry = Omit<SessionParseCacheEntry, 'resume'>
+
+export function snapshotSessionParseCacheForPersistence(): [
+  string,
+  PersistedSessionParseCacheEntry
+][] {
+  return [...cache].map(([path, entry]): [string, PersistedSessionParseCacheEntry] => [
+    path,
+    {
+      mtimeMs: entry.mtimeMs,
+      sizeBytes: entry.sizeBytes,
+      platform: entry.platform,
+      session: entry.session
+    }
+  ])
+}
+
+// Seeded entries carry `resume: null`: after a restart an unchanged file is a
+// cache hit; a file that changed while the app was closed pays one full
+// (not incremental) re-parse.
+export function seedSessionParseCache(
+  entries: Iterable<[string, PersistedSessionParseCacheEntry]>
+): void {
+  const list = [...entries]
+  // Snapshot order is oldest→newest (LRU); an over-cap list keeps the newest
+  // tail rather than seeding the oldest entries and dropping the tail.
+  for (const [path, entry] of list.slice(Math.max(0, list.length - MAX_CACHE_ENTRIES))) {
+    if (cache.size >= MAX_CACHE_ENTRIES) {
+      return
+    }
+    // In-process entries are always fresher than persisted ones; never clobber.
+    if (cache.has(path)) {
+      continue
+    }
+    cache.set(path, {
+      mtimeMs: entry.mtimeMs,
+      sizeBytes: entry.sizeBytes,
+      platform: entry.platform,
+      session: entry.session,
+      resume: null
+    })
+  }
+}
+
 function storeEntry(path: string, entry: SessionParseCacheEntry): void {
   cache.delete(path)
   cache.set(path, entry)
diff --git a/src/main/ai-vault/session-scanner.ts b/src/main/ai-vault/session-scanner.ts
index ddb9ba7a861..795257c7408 100644
--- a/src/main/ai-vault/session-scanner.ts
+++ b/src/main/ai-vault/session-scanner.ts
@@ -13,6 +13,10 @@ import {
 } from './session-scanner-antigravity-history'
 import { antigravityHistoryPathForBrainDir } from './session-scanner-antigravity-paths'
 import { codexHomeForSessionsDir } from './session-scanner-codex-paths'
+import {
+  ensureSessionParseCacheLoaded,
+  scheduleSessionParseCachePersist
+} from './session-parse-cache-persistence'
 import {
   createSessionParseStats,
   parseAgentSessionFileCached,
@@ -61,6 +65,9 @@ export async function scanAiVaultSessions(
     const issues: AiVaultScanIssue[] = []
     const parseStats = createSessionParseStats()
     const antigravityWorkspaceResolver = createAntigravityWorkspaceResolver(readOptionalTextFile)
+    // Why: persisted entries must be seeded before any candidate is parsed, or
+    // the cold scan gains nothing from the cache file (#9210).
+    await ensureSessionParseCacheLoaded()
     const discoveries = await discoverAiVaultSessionSources({ options, limitPerAgent, issues })
 
     const candidates = discoveries
@@ -113,6 +120,8 @@ export async function scanAiVaultSessions(
     span.setAttribute('bytesRead', parseStats.bytesRead)
     span.setAttribute('issues', issues.length)
 
+    scheduleSessionParseCachePersist(parseStats)
+
     return {
       sessions: mergeSessions(cappedSessions, scopeSessions),
       issues: issues.map((issue) => ({ executionHostId, ...issue })),
diff --git a/src/main/index.ts b/src/main/index.ts
index cc9fba24144..1b289f4102d 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -14,6 +14,7 @@ import {
   getCanonicalUserDataPath,
   migrateMobilePairingDataToCanonicalUserDataPath
 } from './persistence'
+import { initSessionParseCachePersistence } from './ai-vault/session-parse-cache-persistence'
 import { ensureActiveOrcaProfile, initOrcaProfilePaths } from './orca-profiles/profile-index-store'
 import { getOrcaCloudAuthConfig } from './orca-profiles/profile-cloud-auth-config'
 import { getProfileUserDataPath } from './orca-profiles/profile-storage-paths'
@@ -650,6 +651,13 @@ if (hasSingleInstanceLock) {
   // orca-dev in dev mode) but before app.setName('Orca') inside whenReady
   // (which would change the resolved path on case-sensitive filesystems).
   initDataPath()
+  // Why: the parse cache file must live under the canonical userData path
+  // captured above — late app.getPath('userData') can resolve differently
+  // across restarts, silently defeating persistence (reused=0 forever).
+  initSessionParseCachePersistence({
+    filePath: join(getCanonicalUserDataPath(), 'ai-vault', 'session-parse-cache.json'),
+    appVersion: app.getVersion()
+  })
   initOrcaProfilePaths()
   // Why: same timing constraint as initDataPath — capture the userData path
   // before app.setName changes it. See persistence.ts:20-28.

From 245d79cc8c0aab4c5d3823a16e94f3091802c8c6 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Sun, 19 Jul 2026 16:36:00 -0700
Subject: [PATCH 13/54] Preserve surviving workspace state when removing a
 runtime host (#9468)

* fix(runtime): preserve surviving workspace state on host removal

Avoid purging worktree-scoped tabs and editor state when an exact worktree id still exists on another host. Also retire legacy unhosted rows when the removed runtime was their repo's sole unambiguous owner.

* fix(runtime): purge rows when all owners are removed

* fix(runtime): include host setups in purge ownership

* fix(runtime): purge session-only state on host removal

* fix(runtime): respect restored session ownership on host purge

* fix(runtime): preserve surviving restored sessions on host purge
---
 ...purge-stale-runtime-host-ownership.test.ts | 147 +++++++++++
 .../purge-stale-runtime-host-state.test.ts    | 247 +++++++++++++++++-
 .../slices/stale-runtime-host-rows.test.ts    |  16 ++
 .../store/slices/stale-runtime-host-rows.ts   |  20 +-
 src/renderer/src/store/slices/worktrees.ts    | 149 ++++++++++-
 5 files changed, 552 insertions(+), 27 deletions(-)
 create mode 100644 src/renderer/src/store/slices/purge-stale-runtime-host-ownership.test.ts

diff --git a/src/renderer/src/store/slices/purge-stale-runtime-host-ownership.test.ts b/src/renderer/src/store/slices/purge-stale-runtime-host-ownership.test.ts
new file mode 100644
index 00000000000..8cab720923e
--- /dev/null
+++ b/src/renderer/src/store/slices/purge-stale-runtime-host-ownership.test.ts
@@ -0,0 +1,147 @@
+import { describe, expect, it, vi } from 'vitest'
+import { toRuntimeExecutionHostId } from '../../../../shared/execution-host'
+import { worktreeWorkspaceKey } from '../../../../shared/workspace-scope'
+
+vi.mock('sonner', () => ({
+  toast: { info: vi.fn(), success: vi.fn(), error: vi.fn(), warning: vi.fn() }
+}))
+
+vi.mock('@/components/terminal-pane/pty-dispatcher', () => ({
+  restorePtyDataHandlersAfterFailedShutdown: vi.fn(),
+  unregisterPtyDataHandlers: vi.fn()
+}))
+
+// @ts-expect-error -- minimal window.api stub for the store under test
+globalThis.window = { api: {} }
+
+import { createTestStore, makeTab, makeWorktree, seedStore } from './store-test-helpers'
+
+const RUNTIME_A = toRuntimeExecutionHostId('env-a')
+const RUNTIME_B = toRuntimeExecutionHostId('env-b')
+
+describe('purgeStaleRuntimeHostState ownership evidence', () => {
+  it('uses an explicit removed-host worktree as owner evidence before catalogs load', () => {
+    const store = createTestStore()
+    const removedWorktreeId = 'repoA::/hosted'
+    const legacyWorktreeId = 'repoA::/legacy'
+    seedStore(store, {
+      repos: [],
+      worktreesByRepo: {
+        repoA: [
+          makeWorktree({ id: removedWorktreeId, repoId: 'repoA', hostId: RUNTIME_A }),
+          makeWorktree({ id: legacyWorktreeId, repoId: 'repoA', hostId: undefined })
+        ]
+      },
+      tabsByWorktree: {
+        [legacyWorktreeId]: [makeTab({ id: 'legacy-tab', worktreeId: legacyWorktreeId })]
+      }
+    })
+
+    store.getState().purgeStaleRuntimeHostState(['env-a'])
+
+    expect(store.getState().worktreesByRepo.repoA).toEqual([])
+    expect(store.getState().tabsByWorktree[legacyWorktreeId]).toBeUndefined()
+  })
+
+  it('purges restored session state owned by the removed host despite an exact-id survivor', () => {
+    const store = createTestStore()
+    const worktreeId = 'shared::/same/path'
+    seedStore(store, {
+      repos: [
+        {
+          id: 'shared',
+          path: '/shared-a',
+          displayName: 'A',
+          executionHostId: RUNTIME_A
+        } as never,
+        {
+          id: 'shared',
+          path: '/shared-b',
+          displayName: 'B',
+          executionHostId: RUNTIME_B
+        } as never
+      ],
+      worktreesByRepo: {
+        shared: [
+          makeWorktree({ id: worktreeId, repoId: 'shared', hostId: RUNTIME_A }),
+          makeWorktree({ id: worktreeId, repoId: 'shared', hostId: RUNTIME_B })
+        ]
+      },
+      tabsByWorktree: {
+        [worktreeId]: [
+          makeTab({ id: 'removed-host-tab', worktreeId, ptyId: 'remote:env-a@@terminal-a' })
+        ]
+      },
+      restoredRuntimeHostIdByWorkspaceSessionKey: { [worktreeId]: RUNTIME_A },
+      activeWorktreeId: worktreeId,
+      activeWorkspaceKey: worktreeWorkspaceKey(worktreeId)
+    })
+
+    store.getState().purgeStaleRuntimeHostState(['env-a'])
+
+    const state = store.getState()
+    expect(state.worktreesByRepo.shared).toHaveLength(1)
+    expect(state.worktreesByRepo.shared[0]?.hostId).toBe(RUNTIME_B)
+    expect(state.tabsByWorktree[worktreeId]).toBeUndefined()
+    expect(state.restoredRuntimeHostIdByWorkspaceSessionKey[worktreeId]).toBeUndefined()
+    expect(state.activeWorktreeId).toBeNull()
+    expect(state.activeWorkspaceKey).toBeNull()
+  })
+
+  it('purges a removed host session after its catalog rows have already disappeared', () => {
+    const store = createTestStore()
+    const worktreeId = 'repoA::/session-only'
+    seedStore(store, {
+      repos: [],
+      worktreesByRepo: {},
+      tabsByWorktree: {
+        [worktreeId]: [makeTab({ id: 'removed-host-tab', worktreeId })]
+      },
+      restoredRuntimeHostIdByWorkspaceSessionKey: { [worktreeId]: RUNTIME_A }
+    })
+
+    store.getState().purgeStaleRuntimeHostState(['env-a'])
+
+    const state = store.getState()
+    expect(state.tabsByWorktree[worktreeId]).toBeUndefined()
+    expect(state.restoredRuntimeHostIdByWorkspaceSessionKey[worktreeId]).toBeUndefined()
+  })
+
+  it('preserves a surviving restored session before its catalog rows load', () => {
+    const store = createTestStore()
+    const removedWorktreeId = 'shared::/removed-host'
+    const survivingWorktreeId = 'shared::/surviving-host'
+    const survivingTabs = [
+      makeTab({
+        id: 'surviving-host-tab',
+        worktreeId: survivingWorktreeId,
+        ptyId: 'remote:env-b@@terminal-b'
+      })
+    ]
+    seedStore(store, {
+      repos: [],
+      worktreesByRepo: {},
+      tabsByWorktree: {
+        [removedWorktreeId]: [makeTab({ id: 'removed-host-tab', worktreeId: removedWorktreeId })],
+        [survivingWorktreeId]: survivingTabs
+      },
+      restoredRuntimeHostIdByWorkspaceSessionKey: {
+        [removedWorktreeId]: RUNTIME_A,
+        [survivingWorktreeId]: RUNTIME_B
+      },
+      activeWorktreeId: survivingWorktreeId,
+      activeWorkspaceKey: worktreeWorkspaceKey(survivingWorktreeId)
+    })
+
+    store.getState().purgeStaleRuntimeHostState(['env-a'])
+
+    const state = store.getState()
+    expect(state.tabsByWorktree[removedWorktreeId]).toBeUndefined()
+    expect(state.tabsByWorktree[survivingWorktreeId]).toBe(survivingTabs)
+    expect(state.restoredRuntimeHostIdByWorkspaceSessionKey).toEqual({
+      [survivingWorktreeId]: RUNTIME_B
+    })
+    expect(state.activeWorktreeId).toBe(survivingWorktreeId)
+    expect(state.activeWorkspaceKey).toBe(worktreeWorkspaceKey(survivingWorktreeId))
+  })
+})
diff --git a/src/renderer/src/store/slices/purge-stale-runtime-host-state.test.ts b/src/renderer/src/store/slices/purge-stale-runtime-host-state.test.ts
index e6926e7669d..0d05535ed2d 100644
--- a/src/renderer/src/store/slices/purge-stale-runtime-host-state.test.ts
+++ b/src/renderer/src/store/slices/purge-stale-runtime-host-state.test.ts
@@ -9,6 +9,7 @@
  */
 import { describe, it, expect, vi } from 'vitest'
 import { toRuntimeExecutionHostId } from '../../../../shared/execution-host'
+import { worktreeWorkspaceKey } from '../../../../shared/workspace-scope'
 import type { ProjectHostSetup, DetectedWorktreeListResult } from '../../../../shared/types'
 
 vi.mock('sonner', () => ({
@@ -53,7 +54,7 @@ function detectedResult(
 function detected(
   id: string,
   repoId: string,
-  hostId: ReturnType<typeof toRuntimeExecutionHostId> | 'local'
+  hostId: ReturnType<typeof toRuntimeExecutionHostId> | 'local' | undefined
 ): DetectedWorktreeListResult['worktrees'][number] {
   return {
     ...makeWorktree({ id, repoId, hostId }),
@@ -171,6 +172,7 @@ describe('purgeStaleRuntimeHostState', () => {
     const store = createTestStore()
     seedStore(store, {
       repos: [TEST_REPO],
+      projectHostSetups: [setup({ id: 's-local', repoId: 'repo1', hostId: 'local' })],
       worktreesByRepo: {
         repo1: [makeWorktree({ id: 'repo1::/wt', repoId: 'repo1', hostId: 'local' })]
       }
@@ -179,6 +181,7 @@ describe('purgeStaleRuntimeHostState', () => {
     const epochBefore = before.sortEpoch
     const worktreesRef = before.worktreesByRepo
     const reposRef = before.repos
+    const setupsRef = before.projectHostSetups
 
     store.getState().purgeStaleRuntimeHostState([])
     store.getState().purgeStaleRuntimeHostState(['env-does-not-exist'])
@@ -188,16 +191,17 @@ describe('purgeStaleRuntimeHostState', () => {
     // Nothing stale => the reducer returns state untouched (same references).
     expect(s.worktreesByRepo).toBe(worktreesRef)
     expect(s.repos).toBe(reposRef)
+    expect(s.projectHostSetups).toBe(setupsRef)
   })
 
-  it('same-repoId-on-two-hosts: keeps the local row and the repo key after purge', () => {
+  it('same-repoId-on-two-hosts: keeps an ambiguous unhosted row and the repo key', () => {
     const store = createTestStore()
     // repoId 'shared' exists under both local and runtime:env-a in worktreesByRepo.
     seedStore(store, {
       repos: [
         { id: 'shared', path: '/shared', displayName: 'shared', badgeColor: '#000', addedAt: 0 },
         {
-          id: 'sharedRuntime',
+          id: 'shared',
           path: '/shared',
           displayName: 'shared',
           badgeColor: '#000',
@@ -207,7 +211,7 @@ describe('purgeStaleRuntimeHostState', () => {
       ],
       worktreesByRepo: {
         shared: [
-          makeWorktree({ id: 'shared::/wt-local', repoId: 'shared', hostId: 'local' }),
+          makeWorktree({ id: 'shared::/wt-local', repoId: 'shared', hostId: undefined }),
           makeWorktree({ id: 'shared::/wt-a', repoId: 'shared', hostId: RUNTIME_A })
         ]
       }
@@ -218,6 +222,241 @@ describe('purgeStaleRuntimeHostState', () => {
     const s = store.getState()
     expect(s.worktreesByRepo).toHaveProperty('shared')
     expect(s.worktreesByRepo.shared.map((w) => w.id)).toEqual(['shared::/wt-local'])
+    expect(s.worktreesByRepo.shared[0]?.hostId).toBeUndefined()
+  })
+
+  it('preserves worktree-scoped state when the exact same id survives on another host', () => {
+    const store = createTestStore()
+    const RUNTIME_B = toRuntimeExecutionHostId('env-b')
+    const worktreeId = 'shared::/same/path'
+    const tabs = [makeTab({ id: 'tab-surviving', worktreeId })]
+    seedStore(store, {
+      repos: [
+        {
+          id: 'shared',
+          path: '/shared',
+          displayName: 'shared',
+          badgeColor: '#000',
+          addedAt: 0,
+          executionHostId: RUNTIME_A
+        },
+        {
+          id: 'shared',
+          path: '/shared',
+          displayName: 'shared',
+          badgeColor: '#000',
+          addedAt: 0,
+          executionHostId: RUNTIME_B
+        }
+      ],
+      worktreesByRepo: {
+        shared: [
+          makeWorktree({ id: worktreeId, repoId: 'shared', hostId: RUNTIME_A }),
+          makeWorktree({ id: worktreeId, repoId: 'shared', hostId: RUNTIME_B })
+        ]
+      },
+      tabsByWorktree: { [worktreeId]: tabs },
+      restoredRuntimeHostIdByWorkspaceSessionKey: { [worktreeId]: RUNTIME_B },
+      activeWorktreeId: worktreeId,
+      activeWorkspaceKey: worktreeWorkspaceKey(worktreeId)
+    })
+    const restoredOwners = store.getState().restoredRuntimeHostIdByWorkspaceSessionKey
+
+    store.getState().purgeStaleRuntimeHostState(['env-a'])
+
+    const s = store.getState()
+    expect(s.worktreesByRepo.shared).toHaveLength(1)
+    expect(s.worktreesByRepo.shared[0]?.hostId).toBe(RUNTIME_B)
+    expect(s.tabsByWorktree[worktreeId]).toBe(tabs)
+    expect(s.restoredRuntimeHostIdByWorkspaceSessionKey).toBe(restoredOwners)
+    expect(s.restoredRuntimeHostIdByWorkspaceSessionKey[worktreeId]).toBe(RUNTIME_B)
+    expect(s.activeWorktreeId).toBe(worktreeId)
+    expect(s.activeWorkspaceKey).toBe(worktreeWorkspaceKey(worktreeId))
+  })
+
+  it('purges a legacy unhosted row when its sole repo owner was removed', () => {
+    const store = createTestStore()
+    const worktreeId = 'repoA::/legacy'
+    seedStore(store, {
+      repos: [
+        {
+          id: 'repoA',
+          path: '/repoA',
+          displayName: 'A',
+          badgeColor: '#000',
+          addedAt: 0,
+          executionHostId: RUNTIME_A
+        }
+      ],
+      worktreesByRepo: {
+        repoA: [makeWorktree({ id: worktreeId, repoId: 'repoA', hostId: undefined })]
+      },
+      tabsByWorktree: { [worktreeId]: [makeTab({ id: 'legacy-tab', worktreeId })] }
+    })
+
+    store.getState().purgeStaleRuntimeHostState(['env-a'])
+
+    const s = store.getState()
+    expect(s.worktreesByRepo.repoA).toEqual([])
+    expect(s.tabsByWorktree[worktreeId]).toBeUndefined()
+  })
+
+  it('uses a removed host setup to purge an unhosted row before its repo loads', () => {
+    const store = createTestStore()
+    const worktreeId = 'repoA::/legacy'
+    seedStore(store, {
+      repos: [],
+      projectHostSetups: [setup({ id: 's-a', repoId: 'repoA', hostId: RUNTIME_A })],
+      worktreesByRepo: {
+        repoA: [makeWorktree({ id: worktreeId, repoId: 'repoA', hostId: undefined })]
+      },
+      tabsByWorktree: { [worktreeId]: [makeTab({ id: 'legacy-tab', worktreeId })] }
+    })
+
+    store.getState().purgeStaleRuntimeHostState(['env-a'])
+
+    const s = store.getState()
+    expect(s.projectHostSetups).toEqual([])
+    expect(s.worktreesByRepo.repoA).toEqual([])
+    expect(s.tabsByWorktree[worktreeId]).toBeUndefined()
+  })
+
+  it('purges hydrated worktree state before its worktree row loads', () => {
+    const store = createTestStore()
+    const worktreeId = 'repoA::/session-only'
+    seedStore(store, {
+      repos: [
+        {
+          id: 'repoA',
+          path: '/repoA',
+          displayName: 'A',
+          badgeColor: '#000',
+          addedAt: 0,
+          executionHostId: RUNTIME_A
+        }
+      ],
+      worktreesByRepo: {},
+      tabsByWorktree: { [worktreeId]: [makeTab({ id: 'hydrated-tab', worktreeId })] },
+      activeWorktreeId: worktreeId,
+      activeWorkspaceKey: worktreeWorkspaceKey(worktreeId)
+    })
+
+    store.getState().purgeStaleRuntimeHostState(['env-a'])
+
+    const s = store.getState()
+    expect(s.tabsByWorktree[worktreeId]).toBeUndefined()
+    expect(s.activeWorktreeId).toBeNull()
+    expect(s.activeWorkspaceKey).toBeNull()
+  })
+
+  it('uses an explicit surviving worktree row as owner evidence during catalog loading', () => {
+    const store = createTestStore()
+    const RUNTIME_B = toRuntimeExecutionHostId('env-b')
+    const legacyWorktreeId = 'shared::/legacy'
+    const survivingWorktreeId = 'shared::/host-b'
+    const tabs = [makeTab({ id: 'surviving-tab', worktreeId: legacyWorktreeId })]
+    seedStore(store, {
+      repos: [
+        {
+          id: 'shared',
+          path: '/shared-a',
+          displayName: 'A',
+          badgeColor: '#000',
+          addedAt: 0,
+          executionHostId: RUNTIME_A
+        }
+      ],
+      worktreesByRepo: {
+        shared: [makeWorktree({ id: legacyWorktreeId, repoId: 'shared', hostId: undefined })]
+      },
+      detectedWorktreesByRepo: {
+        shared: detectedResult('shared', [detected(survivingWorktreeId, 'shared', RUNTIME_B)])
+      },
+      tabsByWorktree: { [legacyWorktreeId]: tabs }
+    })
+
+    store.getState().purgeStaleRuntimeHostState(['env-a'])
+
+    const s = store.getState()
+    expect(s.repos).toEqual([])
+    expect(s.worktreesByRepo.shared.map((worktree) => worktree.id)).toEqual([legacyWorktreeId])
+    expect(s.detectedWorktreesByRepo.shared.worktrees.map((worktree) => worktree.id)).toEqual([
+      survivingWorktreeId
+    ])
+    expect(s.tabsByWorktree[legacyWorktreeId]).toBe(tabs)
+  })
+
+  it('preserves an unhosted row when a setup proves another host still owns it', () => {
+    const store = createTestStore()
+    const RUNTIME_B = toRuntimeExecutionHostId('env-b')
+    const worktreeId = 'shared::/legacy'
+    const tabs = [makeTab({ id: 'surviving-tab', worktreeId })]
+    seedStore(store, {
+      repos: [
+        {
+          id: 'shared',
+          path: '/shared-a',
+          displayName: 'A',
+          badgeColor: '#000',
+          addedAt: 0,
+          executionHostId: RUNTIME_A
+        }
+      ],
+      projectHostSetups: [setup({ id: 's-b', repoId: 'shared', hostId: RUNTIME_B })],
+      worktreesByRepo: {
+        shared: [makeWorktree({ id: worktreeId, repoId: 'shared', hostId: undefined })]
+      },
+      tabsByWorktree: { [worktreeId]: tabs }
+    })
+
+    store.getState().purgeStaleRuntimeHostState(['env-a'])
+
+    const s = store.getState()
+    expect(s.repos).toEqual([])
+    expect(s.projectHostSetups).toHaveLength(1)
+    expect(s.worktreesByRepo.shared).toHaveLength(1)
+    expect(s.tabsByWorktree[worktreeId]).toBe(tabs)
+  })
+
+  it('purges a legacy unhosted row when every repo owner is removed together', () => {
+    const store = createTestStore()
+    const RUNTIME_B = toRuntimeExecutionHostId('env-b')
+    const worktreeId = 'shared::/legacy'
+    seedStore(store, {
+      repos: [
+        {
+          id: 'shared',
+          path: '/shared-a',
+          displayName: 'A',
+          badgeColor: '#000',
+          addedAt: 0,
+          executionHostId: RUNTIME_A
+        },
+        {
+          id: 'shared',
+          path: '/shared-b',
+          displayName: 'B',
+          badgeColor: '#000',
+          addedAt: 0,
+          executionHostId: RUNTIME_B
+        }
+      ],
+      worktreesByRepo: {
+        shared: [makeWorktree({ id: worktreeId, repoId: 'shared', hostId: undefined })]
+      },
+      detectedWorktreesByRepo: {
+        shared: detectedResult('shared', [detected(worktreeId, 'shared', undefined)])
+      },
+      tabsByWorktree: { [worktreeId]: [makeTab({ id: 'legacy-tab', worktreeId })] }
+    })
+
+    store.getState().purgeStaleRuntimeHostState(['env-a', 'env-b'])
+
+    const s = store.getState()
+    expect(s.repos).toEqual([])
+    expect(s.worktreesByRepo.shared).toEqual([])
+    expect(s.detectedWorktreesByRepo.shared.worktrees).toEqual([])
+    expect(s.tabsByWorktree[worktreeId]).toBeUndefined()
   })
 
   it('clears activeRepoId and drops the purged id from filterRepoIds', () => {
diff --git a/src/renderer/src/store/slices/stale-runtime-host-rows.test.ts b/src/renderer/src/store/slices/stale-runtime-host-rows.test.ts
index 6d0e2a5dfff..767763a9b1a 100644
--- a/src/renderer/src/store/slices/stale-runtime-host-rows.test.ts
+++ b/src/renderer/src/store/slices/stale-runtime-host-rows.test.ts
@@ -97,4 +97,20 @@ describe('dropWorktreeRowsForRemovedRuntimeEnvironments', () => {
     expect(result.rowsByRepo.repoChanging).not.toBe(changing)
     expect(result.rowsByRepo.repoChanging).toEqual([row('w-keep', 'local')])
   })
+
+  it('drops unhosted rows only for an unambiguously removed sole-owner repo', () => {
+    const rowsByRepo = {
+      removedRepo: [row('w-legacy')],
+      ambiguousRepo: [row('w-ambiguous')]
+    }
+    const result = dropWorktreeRowsForRemovedRuntimeEnvironments(
+      rowsByRepo,
+      new Set(['env-a']),
+      new Set(['removedRepo'])
+    )
+
+    expect(result.rowsByRepo.removedRepo).toEqual([])
+    expect(result.rowsByRepo.ambiguousRepo).toEqual([row('w-ambiguous')])
+    expect(result.removedWorktreeIds).toEqual(['w-legacy'])
+  })
 })
diff --git a/src/renderer/src/store/slices/stale-runtime-host-rows.ts b/src/renderer/src/store/slices/stale-runtime-host-rows.ts
index 896873be8ed..11b8e0b7530 100644
--- a/src/renderer/src/store/slices/stale-runtime-host-rows.ts
+++ b/src/renderer/src/store/slices/stale-runtime-host-rows.ts
@@ -21,19 +21,18 @@ export type DropRuntimeRowsResult<T> = {
 }
 
 /**
- * Drops rows whose `hostId` is a removed-env runtime host from a
- * `worktreesByRepo`-shaped map. Returns the SAME reference when nothing changed
- * (render-churn guard). Repo keys are kept even when their row list empties — the
- * repo itself is purged from `repos`, so grouping never references an empty entry,
- * and keeping keys avoids threading a cross-slice "does this repo survive" callback
- * into a pure helper. Generic so it serves both `Worktree[]` and the detected
- * worktrees' `.worktrees` arrays.
+ * Drops rows owned by a removed-env runtime host from a `worktreesByRepo`-shaped
+ * map. Legacy unhosted rows are dropped only when their repo had removed owners
+ * and none survive. Returns the SAME reference when nothing changed (render-churn
+ * guard). Repo keys are kept even when their row list empties. Generic so it serves
+ * both `Worktree[]` and the detected worktrees' `.worktrees` arrays.
  */
 export function dropWorktreeRowsForRemovedRuntimeEnvironments<
   T extends { id: string; hostId?: ExecutionHostId }
 >(
   rowsByRepo: Record<string, T[]>,
-  removedEnvironmentIds: ReadonlySet<string>
+  removedEnvironmentIds: ReadonlySet<string>,
+  repoIdsWithoutSurvivingOwners?: ReadonlySet<string>
 ): DropRuntimeRowsResult<T> {
   if (removedEnvironmentIds.size === 0) {
     return { rowsByRepo, removedWorktreeIds: [] }
@@ -43,7 +42,10 @@ export function dropWorktreeRowsForRemovedRuntimeEnvironments<
   const next: Record<string, T[]> = {}
   for (const [repoId, rows] of Object.entries(rowsByRepo)) {
     const survivors = rows.filter((row) => {
-      if (isRemovedRuntimeHostId(row.hostId, removedEnvironmentIds)) {
+      if (
+        isRemovedRuntimeHostId(row.hostId, removedEnvironmentIds) ||
+        (row.hostId === undefined && repoIdsWithoutSurvivingOwners?.has(repoId) === true)
+      ) {
         removedWorktreeIds.push(row.id)
         return false
       }
diff --git a/src/renderer/src/store/slices/worktrees.ts b/src/renderer/src/store/slices/worktrees.ts
index 1845663c7d7..49c9cdce963 100644
--- a/src/renderer/src/store/slices/worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees.ts
@@ -4983,20 +4983,38 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       return
     }
     set((s) => {
-      const survivingRepos = s.repos.filter(
-        (repo) => !isRemovedRuntimeHostId(getRepoExecutionHostId(repo), removed)
-      )
+      const repoIdsWithRemovedOwners = new Set<string>()
+      const survivingRepoIds = new Set<string>()
+      const repoIdsWithSurvivingOwners = new Set<string>()
+      const survivingRepos: AppState['repos'] = []
+      for (const repo of s.repos) {
+        if (isRemovedRuntimeHostId(getRepoExecutionHostId(repo), removed)) {
+          repoIdsWithRemovedOwners.add(repo.id)
+        } else {
+          survivingRepos.push(repo)
+          survivingRepoIds.add(repo.id)
+          repoIdsWithSurvivingOwners.add(repo.id)
+        }
+      }
       const reposChanged = survivingRepos.length !== s.repos.length
 
       // Why: broader than filterSetupsForPrunedRepoRows — a repoId-less setup on
       // the removed host can still flip projectIdsRequiringSetupGroups and split a
       // surviving project group, so drop every setup owned by the removed host.
-      const survivingSetups = s.projectHostSetups.filter(
-        (setup) => !isRemovedRuntimeHostId(setup.hostId, removed)
-      )
+      const survivingSetups: AppState['projectHostSetups'] = []
+      for (const setup of s.projectHostSetups) {
+        if (isRemovedRuntimeHostId(setup.hostId, removed)) {
+          if (setup.repoId) {
+            repoIdsWithRemovedOwners.add(setup.repoId)
+          }
+        } else {
+          survivingSetups.push(setup)
+          if (setup.repoId) {
+            repoIdsWithSurvivingOwners.add(setup.repoId)
+          }
+        }
+      }
       const setupsChanged = survivingSetups.length !== s.projectHostSetups.length
-
-      const worktreeDrop = dropWorktreeRowsForRemovedRuntimeEnvironments(s.worktreesByRepo, removed)
       const detectedRows: Record<string, DetectedWorktreeListResult['worktrees']> =
         Object.fromEntries(
           Object.entries(s.detectedWorktreesByRepo).map(([repoId, result]) => [
@@ -5004,21 +5022,122 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             result.worktrees
           ])
         )
-      const detectedDrop = dropWorktreeRowsForRemovedRuntimeEnvironments(detectedRows, removed)
+      // Why: repo/setup catalogs can lag session hydration; hosted worktree rows
+      // are ownership evidence during that loading gap too.
+      const recordWorktreeOwners = (
+        rowsByRepo: Record<string, readonly { hostId?: ExecutionHostId }[]>
+      ): void => {
+        for (const [repoId, rows] of Object.entries(rowsByRepo)) {
+          for (const row of rows) {
+            if (!row.hostId) {
+              continue
+            }
+            const ownerSet = isRemovedRuntimeHostId(row.hostId, removed)
+              ? repoIdsWithRemovedOwners
+              : repoIdsWithSurvivingOwners
+            ownerSet.add(repoId)
+          }
+        }
+      }
+      recordWorktreeOwners(s.worktreesByRepo)
+      recordWorktreeOwners(detectedRows)
+
+      const sessionWorktreeIdsOwnedByRemovedHosts = new Set<string>()
+      let survivingRestoredSessionOwners = s.restoredRuntimeHostIdByWorkspaceSessionKey
+      for (const [workspaceKey, hostId] of Object.entries(
+        s.restoredRuntimeHostIdByWorkspaceSessionKey
+      )) {
+        const scope = parseWorkspaceKey(workspaceKey)
+        if (scope?.type === 'folder') {
+          continue
+        }
+        const worktreeId = scope?.type === 'worktree' ? scope.worktreeId : workspaceKey
+        const repoId = getRepoIdFromWorktreeId(worktreeId)
+        if (!isRemovedRuntimeHostId(hostId, removed)) {
+          // Why: restored sessions can be the only surviving-owner evidence before catalogs load.
+          repoIdsWithSurvivingOwners.add(repoId)
+          continue
+        }
+        sessionWorktreeIdsOwnedByRemovedHosts.add(worktreeId)
+        repoIdsWithRemovedOwners.add(repoId)
+        if (survivingRestoredSessionOwners === s.restoredRuntimeHostIdByWorkspaceSessionKey) {
+          survivingRestoredSessionOwners = { ...survivingRestoredSessionOwners }
+        }
+        delete survivingRestoredSessionOwners[workspaceKey]
+      }
+
+      // Why: legacy rows predate host stamps; every available owner record must
+      // agree that no other host survives before an unhosted row can be retired.
+      const repoIdsWithoutSurvivingOwners = new Set(repoIdsWithRemovedOwners)
+      for (const repoId of repoIdsWithSurvivingOwners) {
+        repoIdsWithoutSurvivingOwners.delete(repoId)
+      }
+
+      const worktreeDrop = dropWorktreeRowsForRemovedRuntimeEnvironments(
+        s.worktreesByRepo,
+        removed,
+        repoIdsWithoutSurvivingOwners
+      )
+      const detectedDrop = dropWorktreeRowsForRemovedRuntimeEnvironments(
+        detectedRows,
+        removed,
+        repoIdsWithoutSurvivingOwners
+      )
 
       const worktreesChanged = worktreeDrop.rowsByRepo !== s.worktreesByRepo
       const detectedChanged = detectedDrop.rowsByRepo !== detectedRows
-      if (!reposChanged && !setupsChanged && !worktreesChanged && !detectedChanged) {
-        return s
-      }
 
       const removedWorktreeIds = new Set([
         ...worktreeDrop.removedWorktreeIds,
-        ...detectedDrop.removedWorktreeIds
+        ...detectedDrop.removedWorktreeIds,
+        ...sessionWorktreeIdsOwnedByRemovedHosts
       ])
+      // Why: terminal tabs hydrate before worktree metadata; session-only ids for
+      // repos whose owners are all gone still need the full worktree-state purge.
+      if (repoIdsWithoutSurvivingOwners.size > 0) {
+        for (const worktreeId of Object.keys(s.tabsByWorktree)) {
+          const scope = parseWorkspaceKey(worktreeId)
+          const rawWorktreeId = scope?.type === 'worktree' ? scope.worktreeId : worktreeId
+          if (
+            scope?.type !== 'folder' &&
+            repoIdsWithoutSurvivingOwners.has(getRepoIdFromWorktreeId(rawWorktreeId))
+          ) {
+            removedWorktreeIds.add(rawWorktreeId)
+          }
+        }
+      }
+      // Why: bare-id state follows an exact survivor unless the restored session
+      // partition proves that state belonged to the removed host.
+      for (const rows of Object.values(worktreeDrop.rowsByRepo)) {
+        for (const row of rows) {
+          if (!sessionWorktreeIdsOwnedByRemovedHosts.has(row.id)) {
+            removedWorktreeIds.delete(row.id)
+          }
+        }
+      }
+      for (const rows of Object.values(detectedDrop.rowsByRepo)) {
+        for (const row of rows) {
+          if (!sessionWorktreeIdsOwnedByRemovedHosts.has(row.id)) {
+            removedWorktreeIds.delete(row.id)
+          }
+        }
+      }
       const purgeState =
         removedWorktreeIds.size > 0 ? buildWorktreePurgeState(s, [...removedWorktreeIds]) : {}
 
+      const restoredSessionOwnersChanged =
+        survivingRestoredSessionOwners !== s.restoredRuntimeHostIdByWorkspaceSessionKey
+      if (
+        !reposChanged &&
+        !setupsChanged &&
+        !worktreesChanged &&
+        !detectedChanged &&
+        !restoredSessionOwnersChanged &&
+        removedWorktreeIds.size === 0
+      ) {
+        return s
+      }
+
       const detectedWorktreesByRepo = detectedChanged
         ? Object.fromEntries(
             Object.entries(s.detectedWorktreesByRepo).map(([repoId, result]) => [
@@ -5029,13 +5148,15 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         : s.detectedWorktreesByRepo
 
       const rowsChanged = worktreesChanged || detectedChanged
-      const survivingRepoIds = new Set(survivingRepos.map((repo) => repo.id))
       return {
         ...purgeState,
         ...(reposChanged ? { repos: survivingRepos } : {}),
         ...(setupsChanged ? { projectHostSetups: survivingSetups } : {}),
         ...(worktreesChanged ? { worktreesByRepo: worktreeDrop.rowsByRepo } : {}),
         ...(detectedChanged ? { detectedWorktreesByRepo } : {}),
+        ...(restoredSessionOwnersChanged
+          ? { restoredRuntimeHostIdByWorkspaceSessionKey: survivingRestoredSessionOwners }
+          : {}),
         ...(rowsChanged ? { sortEpoch: s.sortEpoch + 1 } : {}),
         // Why: mirror validateRepoScopedUi's repo-scoped UI subset so a filtered or
         // active sidebar can't be left referencing a purged repo id.

From b320bcb374c032e88eb4512db57d2c79785601be Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Sun, 19 Jul 2026 16:54:31 -0700
Subject: [PATCH 14/54] fix(gitlab): bound and coalesce auth probes (#9476)

---
 src/main/git/runner-wsl-gh-fallback.test.ts   |  91 ++++++++++++
 src/main/git/runner.ts                        | 132 +++++++++++++-----
 src/main/gitlab/client.ts                     |  22 ++-
 src/main/gitlab/gitlab-known-host-probe.ts    | 110 +++++++++++++++
 .../gitlab/gitlab-project-ref-resolution.ts   |  91 ++----------
 src/main/gitlab/gl-utils.test.ts              |  97 +++++++++++++
 src/main/gitlab/issues.test.ts                |   2 +-
 src/main/gitlab/issues.ts                     |  14 +-
 src/main/gitlab/work-item-details.ts          |   2 +-
 src/main/runtime/orca-runtime.ts              |   4 +-
 10 files changed, 427 insertions(+), 138 deletions(-)
 create mode 100644 src/main/gitlab/gitlab-known-host-probe.ts

diff --git a/src/main/git/runner-wsl-gh-fallback.test.ts b/src/main/git/runner-wsl-gh-fallback.test.ts
index c7710858838..8b802c2f0d6 100644
--- a/src/main/git/runner-wsl-gh-fallback.test.ts
+++ b/src/main/git/runner-wsl-gh-fallback.test.ts
@@ -1,3 +1,4 @@
+import { EventEmitter } from 'node:events'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type * as WslModule from '../wsl'
 
@@ -21,11 +22,26 @@ vi.mock('../wsl', async (importOriginal) => ({
 
 import { ghExecFileAsync, glabExecFileAsync } from './runner'
 
+type MockChildProcess = EventEmitter & {
+  pid: number
+  kill: ReturnType<typeof vi.fn>
+  unref: ReturnType<typeof vi.fn>
+}
+
+function createMockChildProcess(pid: number): MockChildProcess {
+  const child = new EventEmitter() as MockChildProcess
+  child.pid = pid
+  child.kill = vi.fn()
+  child.unref = vi.fn()
+  return child
+}
+
 describe('ghExecFileAsync WSL fallback', () => {
   const originalPlatform = process.platform
 
   beforeEach(() => {
     execFileMock.mockReset()
+    spawnMock.mockReset()
     getDefaultWslDistroMock.mockReset()
     getDefaultWslDistroMock.mockReturnValue(null)
     Object.defineProperty(process, 'platform', {
@@ -35,6 +51,7 @@ describe('ghExecFileAsync WSL fallback', () => {
   })
 
   afterEach(() => {
+    vi.useRealTimers()
     Object.defineProperty(process, 'platform', {
       configurable: true,
       value: originalPlatform
@@ -352,6 +369,80 @@ describe('ghExecFileAsync WSL fallback', () => {
     )
   })
 
+  it('times out the default-WSL glab fallback and waits for full tree cleanup', async () => {
+    vi.useFakeTimers()
+    getDefaultWslDistroMock.mockReturnValue('Ubuntu')
+    const nativeChild = createMockChildProcess(1200)
+    const wslChild = createMockChildProcess(2400)
+    const taskkill = createMockChildProcess(3600)
+    execFileMock
+      .mockImplementationOnce((_binary, _args, _options, callback) => {
+        callback(Object.assign(new Error('spawn glab ENOENT'), { code: 'ENOENT' }))
+        return nativeChild
+      })
+      .mockReturnValueOnce(wslChild)
+    spawnMock.mockReturnValue(taskkill)
+
+    const promise = glabExecFileAsync(['auth', 'status'], { timeout: 1000 })
+    const rejection = expect(promise).rejects.toThrow('wsl.exe timed out.')
+    let rejected = false
+    void promise.catch(() => {
+      rejected = true
+    })
+
+    await vi.advanceTimersByTimeAsync(999)
+    expect(spawnMock).not.toHaveBeenCalled()
+    await vi.advanceTimersByTimeAsync(1)
+    expect(spawnMock).toHaveBeenCalledWith(
+      'taskkill',
+      ['/pid', '2400', '/t', '/f'],
+      expect.objectContaining({ stdio: 'ignore', windowsHide: true })
+    )
+    await Promise.resolve()
+    expect(rejected).toBe(false)
+
+    taskkill.emit('close', 0)
+    await rejection
+    expect(wslChild.kill).not.toHaveBeenCalled()
+  })
+
+  it('aborts the default-WSL glab fallback with full process-tree cleanup', async () => {
+    getDefaultWslDistroMock.mockReturnValue('Ubuntu')
+    const nativeChild = createMockChildProcess(1200)
+    const wslChild = createMockChildProcess(2400)
+    const taskkill = createMockChildProcess(3600)
+    execFileMock
+      .mockImplementationOnce((_binary, _args, _options, callback) => {
+        callback(Object.assign(new Error('spawn glab ENOENT'), { code: 'ENOENT' }))
+        return nativeChild
+      })
+      .mockReturnValueOnce(wslChild)
+    spawnMock.mockReturnValue(taskkill)
+    const controller = new AbortController()
+
+    const promise = glabExecFileAsync(['auth', 'status'], { signal: controller.signal })
+    const rejection = expect(promise).rejects.toMatchObject({ name: 'AbortError' })
+    await vi.waitFor(() => expect(execFileMock).toHaveBeenCalledTimes(2))
+    controller.abort()
+
+    expect(execFileMock).toHaveBeenNthCalledWith(
+      2,
+      'wsl.exe',
+      ['-d', 'Ubuntu', '--', 'bash', '-c', "'glab' 'auth' 'status'"],
+      expect.not.objectContaining({ signal: controller.signal }),
+      expect.any(Function)
+    )
+    expect(spawnMock).toHaveBeenCalledWith(
+      'taskkill',
+      ['/pid', '2400', '/t', '/f'],
+      expect.objectContaining({ stdio: 'ignore', windowsHide: true })
+    )
+    taskkill.emit('close', 0)
+
+    await rejection
+    expect(wslChild.kill).not.toHaveBeenCalled()
+  })
+
   it('does not wake the default WSL distro for host-only GitLab diagnostics', async () => {
     getDefaultWslDistroMock.mockReturnValue('Ubuntu')
     execFileMock
diff --git a/src/main/git/runner.ts b/src/main/git/runner.ts
index 8c70421e3ef..598ed2a9781 100644
--- a/src/main/git/runner.ts
+++ b/src/main/git/runner.ts
@@ -323,24 +323,57 @@ function createAbortError(): Error {
   return error
 }
 
-function killSpawnedCommandTree(child: ChildProcess): void {
+const WINDOWS_TREE_KILL_WAIT_MS = 2_000
+
+function killSpawnedCommandTree(child: ChildProcess): Promise<void> {
   const pid = child.pid
   if (!pid || process.platform !== 'win32') {
     child.kill()
-    return
+    return Promise.resolve()
   }
-  try {
-    // Why: Windows package-manager CLIs are often .cmd shims. Killing only
-    // cmd.exe leaves the underlying node/npm/pnpm child running.
-    const killer = spawn('taskkill', ['/pid', String(pid), '/t', '/f'], {
-      stdio: 'ignore',
-      windowsHide: true
-    })
-    killer.on('error', () => child.kill())
+  return new Promise((resolve) => {
+    let killer: ChildProcess
+    try {
+      // Why: Windows shims and wsl.exe can own descendants; wait for /t tree
+      // cleanup before settling so a timed-out command cannot outlive its probe.
+      killer = spawn('taskkill', ['/pid', String(pid), '/t', '/f'], {
+        stdio: 'ignore',
+        windowsHide: true
+      })
+      if (!killer || typeof killer.unref !== 'function') {
+        child.kill()
+        resolve()
+        return
+      }
+    } catch {
+      child.kill()
+      resolve()
+      return
+    }
+    let settled = false
+    let timer: NodeJS.Timeout | null = null
+    const finish = (fallbackToChildKill: boolean): void => {
+      if (settled) {
+        return
+      }
+      settled = true
+      if (timer) {
+        clearTimeout(timer)
+      }
+      killer.removeAllListeners()
+      if (fallbackToChildKill) {
+        child.kill()
+      }
+      resolve()
+    }
+    killer.once('error', () => finish(true))
+    killer.once('close', (code) => finish(code !== 0))
+    timer = setTimeout(() => {
+      killer.kill()
+      finish(true)
+    }, WINDOWS_TREE_KILL_WAIT_MS)
     killer.unref()
-  } catch {
-    child.kill()
-  }
+  })
 }
 
 type ExecFileCaptureOptions = Omit<ExecFileOptions, 'timeout'> & {
@@ -376,6 +409,7 @@ function execFileCapture(
     }
 
     let settled = false
+    let terminating = false
     let child: ChildProcess | null = null
     let timer: NodeJS.Timeout | null = null
     const cleanup = (): void => {
@@ -405,14 +439,26 @@ function execFileCapture(
       resolve({ stdout, stderr })
     }
     const onAbort = (): void => {
-      if (child) {
-        killSpawnedCommandTree(child)
+      if (settled || terminating) {
+        return
       }
-      finish(createAbortError())
+      terminating = true
+      const abortError = createAbortError()
+      if (!child) {
+        terminating = false
+        finish(abortError)
+        return
+      }
+      void killSpawnedCommandTree(child).then(() => {
+        terminating = false
+        finish(abortError)
+      })
     }
 
     try {
       const spawnStartedAt = performance.now()
+      // Why: the abort listener below owns tree-aware cleanup. Node's
+      // signal handler could kill wsl.exe before taskkill sees its children.
       child = execFile(
         command,
         args,
@@ -420,10 +466,12 @@ function execFileCapture(
           cwd: options.cwd,
           encoding: options.encoding,
           maxBuffer: options.maxBuffer ?? DEFAULT_GIT_MAX_BUFFER,
-          env: options.env,
-          signal: options.signal
+          env: options.env
         },
         (error, stdout, stderr) => {
+          if (terminating) {
+            return
+          }
           if (!error && stderr === undefined && isExecFileResultObject(stdout)) {
             finish(null, stdout.stdout, stdout.stderr)
             return
@@ -437,21 +485,34 @@ function execFileCapture(
       return
     }
 
-    child.once('error', (error) => finish(error))
+    child.once('error', (error) => {
+      if (!terminating) {
+        finish(error)
+      }
+    })
 
     if (options.stdin !== undefined) {
       endSubprocessStdin(child.stdin, options.stdin)
     }
 
-    // Why: Node's native execFile timeout waits for the child to exit after
-    // signaling it. Some CLIs ignore that signal, so reject the UI operation
-    // on our own timer and kill the child only as best effort.
+    // Why: Node's native timeout can wait forever for signal-ignoring CLIs;
+    // enforce our own deadline and settle after bounded process-tree cleanup.
     if (options.timeout && options.timeout > 0) {
       timer = setTimeout(() => {
-        if (child) {
-          killSpawnedCommandTree(child)
+        if (settled || terminating) {
+          return
         }
-        finish(new Error(`${command} timed out.`))
+        terminating = true
+        const timeoutError = new Error(`${command} timed out.`)
+        if (!child) {
+          terminating = false
+          finish(timeoutError)
+          return
+        }
+        void killSpawnedCommandTree(child).then(() => {
+          terminating = false
+          finish(timeoutError)
+        })
       }, options.timeout)
     }
     options.signal?.addEventListener('abort', onAbort, { once: true })
@@ -484,7 +545,7 @@ async function spawnCommandCapture(
     recordSubprocessSpawn(spawnCmd, spawnArgs, performance.now() - spawnStartedAt)
     let timer: NodeJS.Timeout | null = null
     const onAbort = (): void => {
-      killSpawnedCommandTree(child)
+      void killSpawnedCommandTree(child)
       finish(createAbortError())
     }
     const cleanupListeners = (): void => {
@@ -512,7 +573,7 @@ async function spawnCommandCapture(
     }
     timer = options.timeout
       ? setTimeout(() => {
-          killSpawnedCommandTree(child)
+          void killSpawnedCommandTree(child)
           finish(new Error(`${command} timed out.`))
         }, options.timeout)
       : null
@@ -520,7 +581,7 @@ async function spawnCommandCapture(
     function onStdoutData(chunk: Buffer): void {
       stdoutBytes += chunk.byteLength
       if (options.maxBuffer && stdoutBytes > options.maxBuffer) {
-        killSpawnedCommandTree(child)
+        void killSpawnedCommandTree(child)
         finish(new Error(`${command} stdout exceeded maxBuffer.`))
         return
       }
@@ -529,7 +590,7 @@ async function spawnCommandCapture(
     function onStderrData(chunk: Buffer): void {
       stderrBytes += chunk.byteLength
       if (options.maxBuffer && stderrBytes > options.maxBuffer) {
-        killSpawnedCommandTree(child)
+        void killSpawnedCommandTree(child)
         finish(new Error(`${command} stderr exceeded maxBuffer.`))
         return
       }
@@ -997,7 +1058,7 @@ export async function gitStreamStdout(
       function onStdoutData(chunk: Buffer): void {
         stdoutBytes += chunk.byteLength
         if (stdoutBytes > maxBuffer) {
-          killSpawnedCommandTree(child)
+          void killSpawnedCommandTree(child)
           finish(new Error('git stdout exceeded maxBuffer.'))
           return
         }
@@ -1012,7 +1073,7 @@ export async function gitStreamStdout(
         try {
           shouldStop = options.onStdout(decoded)
         } catch (error) {
-          killSpawnedCommandTree(child)
+          void killSpawnedCommandTree(child)
           finish(error instanceof Error ? error : new Error(String(error)))
           return
         }
@@ -1020,14 +1081,14 @@ export async function gitStreamStdout(
           // Why: parser hit its limit. Kill git and resolve cleanly — the
           // partial output we already parsed is the intended result.
           stoppedEarly = true
-          killSpawnedCommandTree(child)
+          void killSpawnedCommandTree(child)
           finish(null)
         }
       }
       function onStderrData(chunk: Buffer): void {
         stderrBytes += chunk.byteLength
         if (stderrBytes > maxBuffer) {
-          killSpawnedCommandTree(child)
+          void killSpawnedCommandTree(child)
           finish(new Error('git stderr exceeded maxBuffer.'))
           return
         }
@@ -1044,7 +1105,7 @@ export async function gitStreamStdout(
         finish(new Error(`git exited with ${code}: ${stderr}`))
       }
       function onAbort(): void {
-        killSpawnedCommandTree(child)
+        void killSpawnedCommandTree(child)
         finish(createAbortError())
       }
 
@@ -1468,7 +1529,8 @@ export async function glabExecFileAsync(
         encoding: (options.encoding ?? 'utf-8') as BufferEncoding,
         maxBuffer: options.maxBuffer,
         timeout: options.timeout,
-        env: options.env
+        env: options.env,
+        signal: options.signal
       })
       return { stdout: stdout as string, stderr: stderr as string }
     } catch (err) {
diff --git a/src/main/gitlab/client.ts b/src/main/gitlab/client.ts
index 370553db9e1..eef57b3aaba 100644
--- a/src/main/gitlab/client.ts
+++ b/src/main/gitlab/client.ts
@@ -248,13 +248,9 @@ export async function getProjectSlug(
   connectionId?: string | null,
   options: HostedReviewExecutionOptions = {}
 ): Promise<ProjectRef | null> {
-  const knownHosts = await getGlabKnownHosts(connectionId)
-  return getProjectRef(
-    repoPath,
-    knownHosts,
-    connectionId,
-    ...hostedReviewLocalGitOptionArgs(options)
-  )
+  const localGitArgs = hostedReviewLocalGitOptionArgs(options)
+  const knownHosts = await getGlabKnownHosts(connectionId, localGitArgs[0])
+  return getProjectRef(repoPath, knownHosts, connectionId, ...localGitArgs)
 }
 
 /**
@@ -268,9 +264,9 @@ export async function getMergeRequest(
   connectionId?: string | null,
   options: HostedReviewExecutionOptions = {}
 ): Promise<MRInfo | null> {
-  const knownHosts = await getGlabKnownHosts(connectionId)
   const localGitArgs = hostedReviewLocalGitOptionArgs(options)
   const localGitOptions = localGitArgs[0] ?? {}
+  const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
   const projectRef = await getProjectRef(repoPath, knownHosts, connectionId, ...localGitArgs)
   await acquire()
   try {
@@ -323,9 +319,9 @@ export async function getMergeRequestForBranch(
   if (!branchName && linkedMRIid == null) {
     return null
   }
-  const knownHosts = await getGlabKnownHosts(connectionId)
   const localGitArgs = hostedReviewLocalGitOptionArgs(options)
   const localGitOptions = localGitArgs[0] ?? {}
+  const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
   const projectRef = await getProjectRef(repoPath, knownHosts, connectionId, ...localGitArgs)
   if (!projectRef) {
     return null
@@ -425,7 +421,7 @@ export async function listMergeRequests(
   connectionId?: string | null,
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<ListMergeRequestsResult> {
-  const knownHosts = await getGlabKnownHosts(connectionId)
+  const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
   // Why: MRs sit on `origin` in the fork model (the user's fork is where
   // they push branches and submit MRs). Mirror github's `getOwnerRepo`
   // call site by going through the upstream/origin preference resolver
@@ -623,7 +619,7 @@ export async function listWorkItems(
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<GitLabPagedResult<GitLabWorkItem>> {
   const issueState = mrStateToIssueState(state)
-  const knownHosts = await getGlabKnownHosts(connectionId)
+  const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
   const { source: projectRef } = await resolveIssueSource(
     repoPath,
     preference,
@@ -759,7 +755,7 @@ export async function listTodos(
 ): Promise<GitLabTodo[]> {
   const projectRef = await getProjectRef(
     repoPath,
-    await getGlabKnownHosts(connectionId),
+    await getGlabKnownHosts(connectionId, localGitOptions),
     connectionId,
     localGitOptions
   )
@@ -838,7 +834,7 @@ async function withProjectRef<T>(
       await resolveIssueSource(
         repoPath,
         preference,
-        await getGlabKnownHosts(connectionId),
+        await getGlabKnownHosts(connectionId, localGitOptions),
         connectionId,
         localGitOptions
       )
diff --git a/src/main/gitlab/gitlab-known-host-probe.ts b/src/main/gitlab/gitlab-known-host-probe.ts
new file mode 100644
index 00000000000..1756df4ce96
--- /dev/null
+++ b/src/main/gitlab/gitlab-known-host-probe.ts
@@ -0,0 +1,110 @@
+import { glabExecFileAsync } from '../git/runner'
+import { getSshGitProviderGeneration } from '../providers/ssh-git-dispatch'
+import { DEFAULT_GITLAB_HOSTS, normalizeGitLabHost } from './project-ref-parser'
+
+export type LocalGitExecOptions = {
+  wslDistro?: string
+}
+
+const GLAB_KNOWN_HOSTS_TIMEOUT_MS = 10_000
+const knownHostsCacheByExecutionContext = new Map<string, readonly string[]>()
+const knownHostsInFlightByExecutionContext = new Map<string, Promise<readonly string[]>>()
+
+function knownHostsExecutionKey(
+  connectionId?: string | null,
+  localGitOptions: LocalGitExecOptions = {}
+): string {
+  if (connectionId) {
+    // Why: reconnecting can replace the SSH/relay execution host under the same id.
+    return `connection:${connectionId}:${getSshGitProviderGeneration(connectionId)}`
+  }
+  return localGitOptions.wslDistro ? `wsl:${localGitOptions.wslDistro}` : 'native'
+}
+
+/** @internal - exposed for tests only */
+export function _resetKnownHostsCache(): void {
+  knownHostsCacheByExecutionContext.clear()
+  knownHostsInFlightByExecutionContext.clear()
+}
+
+export function rememberGlabKnownHost(
+  host: string,
+  connectionId?: string | null,
+  localGitOptions: LocalGitExecOptions = {}
+): void {
+  const normalizedHost = normalizeGitLabHost(host)
+  const key = knownHostsExecutionKey(connectionId, localGitOptions)
+  const cached = knownHostsCacheByExecutionContext.get(key)
+  if (!cached || cached.map(normalizeGitLabHost).includes(normalizedHost)) {
+    return
+  }
+  knownHostsCacheByExecutionContext.set(key, [...cached, normalizedHost])
+}
+
+export async function getGlabKnownHosts(
+  connectionId?: string | null,
+  localGitOptions: LocalGitExecOptions = {}
+): Promise<readonly string[]> {
+  const key = knownHostsExecutionKey(connectionId, localGitOptions)
+  const cached = knownHostsCacheByExecutionContext.get(key)
+  if (cached) {
+    return cached
+  }
+  const inFlight = knownHostsInFlightByExecutionContext.get(key)
+  if (inFlight) {
+    return inFlight
+  }
+  const probe = probeGlabKnownHosts(key, connectionId, localGitOptions)
+  knownHostsInFlightByExecutionContext.set(key, probe)
+  try {
+    return await probe
+  } finally {
+    if (knownHostsInFlightByExecutionContext.get(key) === probe) {
+      knownHostsInFlightByExecutionContext.delete(key)
+    }
+  }
+}
+
+async function probeGlabKnownHosts(
+  key: string,
+  connectionId?: string | null,
+  localGitOptions: LocalGitExecOptions = {}
+): Promise<readonly string[]> {
+  try {
+    // Why: auth config belongs to the executing host; do not share native, WSL,
+    // or reconnected SSH/relay results, and bound an otherwise global probe.
+    const { stdout, stderr } = await glabExecFileAsync(['auth', 'status'], {
+      timeout: GLAB_KNOWN_HOSTS_TIMEOUT_MS,
+      ...(!connectionId && localGitOptions.wslDistro
+        ? { wslDistro: localGitOptions.wslDistro }
+        : {})
+    })
+    const hosts = parseGlabAuthStatusHosts(`${stdout}\n${stderr}`)
+    const merged = Array.from(new Set([...DEFAULT_GITLAB_HOSTS, ...hosts]))
+    knownHostsCacheByExecutionContext.set(key, merged)
+    return merged
+  } catch {
+    // Keep failures uncached so auth or tunnel recovery is discovered later.
+    return [...DEFAULT_GITLAB_HOSTS]
+  }
+}
+
+export function parseGlabAuthStatusHosts(output: string): string[] {
+  const hosts = new Set<string>()
+  // Why: self-hosted GitLab can run on a non-default port; preserve it so
+  // services on the same hostname remain distinct downstream.
+  for (const match of output.matchAll(/logged in to ([a-zA-Z0-9.-]+(?::\d+)?)/gi)) {
+    hosts.add(match[1].toLowerCase())
+  }
+  for (const line of output.split('\n')) {
+    const bareLine = line.trim()
+    const hostLine = bareLine.endsWith(':') ? bareLine.slice(0, -1) : bareLine
+    if (
+      line === bareLine &&
+      /^[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?(?::\d+)?$/.test(hostLine)
+    ) {
+      hosts.add(hostLine.toLowerCase())
+    }
+  }
+  return Array.from(hosts)
+}
diff --git a/src/main/gitlab/gitlab-project-ref-resolution.ts b/src/main/gitlab/gitlab-project-ref-resolution.ts
index 1dba771d05e..218a41869c9 100644
--- a/src/main/gitlab/gitlab-project-ref-resolution.ts
+++ b/src/main/gitlab/gitlab-project-ref-resolution.ts
@@ -2,6 +2,11 @@ import { gitExecFileAsync, glabExecFileAsync } from '../git/runner'
 import type { IssueSourcePreference } from '../../shared/types'
 import { getSshGitProvider } from '../providers/ssh-git-dispatch'
 import { clearProjectRefInFlight, runProjectRefProbeOnce } from './project-ref-inflight'
+import {
+  parseGlabAuthStatusHosts,
+  rememberGlabKnownHost,
+  type LocalGitExecOptions
+} from './gitlab-known-host-probe'
 import {
   DEFAULT_GITLAB_HOSTS,
   normalizeGitLabHost,
@@ -12,26 +17,16 @@ import {
 
 export { DEFAULT_GITLAB_HOSTS, parseGitLabProjectRef }
 export type { ProjectRef }
-
-export type LocalGitExecOptions = {
-  wslDistro?: string
-}
+export {
+  _resetKnownHostsCache,
+  getGlabKnownHosts,
+  parseGlabAuthStatusHosts
+} from './gitlab-known-host-probe'
+export type { LocalGitExecOptions } from './gitlab-known-host-probe'
 
 const PROJECT_REF_CACHE_MAX_ENTRIES = 512
 const projectRefCache = new Map<string, ProjectRef | null>()
 
-// Why: known hosts are cached PER connection. A repo on an SSH connection
-// authenticates against a different glab context than the local one, so a
-// process-global cache would leak one connection's hosts into another (and
-// poison a connection that probes before its tunnel is ready). The local
-// context uses the `'local'` key.
-const LOCAL_CONNECTION_KEY = 'local'
-const knownHostsCacheByConnection = new Map<string, readonly string[]>()
-
-function connectionCacheKey(connectionId?: string | null): string {
-  return connectionId ?? LOCAL_CONNECTION_KEY
-}
-
 /** @internal - exposed for tests only */
 export function _resetProjectRefCache(): void {
   projectRefCache.clear()
@@ -43,11 +38,6 @@ export function _getProjectRefCacheSize(): number {
   return projectRefCache.size
 }
 
-/** @internal - exposed for tests only */
-export function _resetKnownHostsCache(): void {
-  knownHostsCacheByConnection.clear()
-}
-
 function rememberProjectRefCacheEntry(cacheKey: string, value: ProjectRef | null): void {
   projectRefCache.set(cacheKey, value)
   while (projectRefCache.size > PROJECT_REF_CACHE_MAX_ENTRIES) {
@@ -118,7 +108,7 @@ async function resolveProjectRefForRemote(
         localGitOptions
       ))
     ) {
-      rememberGlabKnownHost(remoteCandidate.host, connectionId)
+      rememberGlabKnownHost(remoteCandidate.host, connectionId, localGitOptions)
       rememberProjectRefCacheEntry(cacheKey, remoteCandidate)
       return remoteCandidate
     }
@@ -230,16 +220,6 @@ export function glabHostnameArgs(
   return connectionId && projectRef?.host ? ['--hostname', projectRef.host] : []
 }
 
-function rememberGlabKnownHost(host: string, connectionId?: string | null): void {
-  const normalizedHost = normalizeGitLabHost(host)
-  const key = connectionCacheKey(connectionId)
-  const cached = knownHostsCacheByConnection.get(key)
-  if (!cached || cached.map(normalizeGitLabHost).includes(normalizedHost)) {
-    return
-  }
-  knownHostsCacheByConnection.set(key, [...cached, normalizedHost])
-}
-
 async function isGlabConfiguredForRemoteHost(
   repoPath: string,
   projectRef: Pick<ProjectRef, 'host'>,
@@ -262,50 +242,3 @@ async function isGlabConfiguredForRemoteHost(
     return hosts.includes(normalizeGitLabHost(projectRef.host))
   }
 }
-
-export async function getGlabKnownHosts(connectionId?: string | null): Promise<readonly string[]> {
-  const key = connectionCacheKey(connectionId)
-  const cached = knownHostsCacheByConnection.get(key)
-  if (cached) {
-    return cached
-  }
-  try {
-    // Why: `glab auth status` is host-scoped, not cwd-scoped — glab reads its
-    // own config to list authenticated hosts. The connectionId is threaded so
-    // the RESULT is cached per connection (a connected repo can have a
-    // different set of authenticated self-hosted hosts than the local one),
-    // mirroring how project-ref resolution caches per connection.
-    const { stdout, stderr } = await glabExecFileAsync(['auth', 'status'])
-    const hosts = parseGlabAuthStatusHosts(`${stdout}\n${stderr}`)
-    const merged = Array.from(new Set([...DEFAULT_GITLAB_HOSTS, ...hosts]))
-    knownHostsCacheByConnection.set(key, merged)
-    return merged
-  } catch {
-    // Auth check failed (glab not installed, no auth, tunnel not ready,
-    // etc.) — fall back to the canonical default for THIS call, but do NOT
-    // cache the fallback. A later probe (e.g. after the SSH tunnel comes
-    // up) must be able to discover the real self-hosted host.
-    return [...DEFAULT_GITLAB_HOSTS]
-  }
-}
-
-export function parseGlabAuthStatusHosts(output: string): string[] {
-  const hosts = new Set<string>()
-  // Why: self-hosted GitLab can run on a non-default port (e.g.
-  // `gitlab.example.com:8443`); capture the optional `:port` so two services
-  // on the same hostname but different ports stay distinct downstream.
-  for (const m of output.matchAll(/logged in to ([a-zA-Z0-9.-]+(?::\d+)?)/gi)) {
-    hosts.add(m[1].toLowerCase())
-  }
-  for (const line of output.split('\n')) {
-    const bareLine = line.trim()
-    const hostLine = bareLine.endsWith(':') ? bareLine.slice(0, -1) : bareLine
-    if (
-      line === bareLine &&
-      /^[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?(?::\d+)?$/.test(hostLine)
-    ) {
-      hosts.add(hostLine.toLowerCase())
-    }
-  }
-  return Array.from(hosts)
-}
diff --git a/src/main/gitlab/gl-utils.test.ts b/src/main/gitlab/gl-utils.test.ts
index 7306c5b7fd4..9ab99ddc441 100644
--- a/src/main/gitlab/gl-utils.test.ts
+++ b/src/main/gitlab/gl-utils.test.ts
@@ -434,6 +434,7 @@ describe('getGlabKnownHosts', () => {
     })
 
     await expect(getGlabKnownHosts()).resolves.toEqual(['gitlab.com', 'gitlab.example.com'])
+    expect(glabExecFileAsyncMock).toHaveBeenCalledWith(['auth', 'status'], { timeout: 10_000 })
   })
 
   it('falls back to default when glab auth status fails', async () => {
@@ -453,6 +454,55 @@ describe('getGlabKnownHosts', () => {
     expect(glabExecFileAsyncMock).toHaveBeenCalledTimes(1)
   })
 
+  it('coalesces many simultaneous callers in one execution context', async () => {
+    let resolveProbe!: (value: { stdout: string; stderr: string }) => void
+    glabExecFileAsyncMock.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveProbe = resolve
+        })
+    )
+
+    const probes = Array.from({ length: 64 }, () => getGlabKnownHosts())
+
+    expect(glabExecFileAsyncMock).toHaveBeenCalledTimes(1)
+    resolveProbe({ stdout: 'Logged in to gitlab.concurrent.test as user\n', stderr: '' })
+    const results = await Promise.all(probes)
+    expect(results.every((result) => result === results[0])).toBe(true)
+    expect(results[0]).toEqual(['gitlab.com', 'gitlab.concurrent.test'])
+  })
+
+  it('keeps simultaneous native, WSL distro, and connection probes isolated', async () => {
+    glabExecFileAsyncMock
+      .mockResolvedValueOnce({ stdout: 'Logged in to ubuntu.test as user\n', stderr: '' })
+      .mockResolvedValueOnce({ stdout: 'Logged in to debian.test as user\n', stderr: '' })
+      .mockResolvedValueOnce({ stdout: 'Logged in to native.test as user\n', stderr: '' })
+      .mockResolvedValueOnce({ stdout: 'Logged in to ssh.test as user\n', stderr: '' })
+
+    const [ubuntu, ubuntuAgain, debian, native, ssh] = await Promise.all([
+      getGlabKnownHosts(undefined, { wslDistro: 'Ubuntu' }),
+      getGlabKnownHosts(undefined, { wslDistro: 'Ubuntu' }),
+      getGlabKnownHosts(undefined, { wslDistro: 'Debian' }),
+      getGlabKnownHosts(),
+      getGlabKnownHosts('conn-1')
+    ])
+
+    expect(ubuntuAgain).toBe(ubuntu)
+    expect(ubuntu).toEqual(['gitlab.com', 'ubuntu.test'])
+    expect(debian).toEqual(['gitlab.com', 'debian.test'])
+    expect(native).toEqual(['gitlab.com', 'native.test'])
+    expect(ssh).toEqual(['gitlab.com', 'ssh.test'])
+    expect(glabExecFileAsyncMock).toHaveBeenCalledTimes(4)
+    expect(glabExecFileAsyncMock).toHaveBeenNthCalledWith(1, ['auth', 'status'], {
+      timeout: 10_000,
+      wslDistro: 'Ubuntu'
+    })
+    expect(glabExecFileAsyncMock).toHaveBeenNthCalledWith(2, ['auth', 'status'], {
+      timeout: 10_000,
+      wslDistro: 'Debian'
+    })
+  })
+
   it('recognizes a self-hosted host on a non-default port', async () => {
     glabExecFileAsyncMock.mockResolvedValueOnce({
       stdout: '✓ Logged in to gitlab.example.com:8080 as user\n',
@@ -500,4 +550,51 @@ describe('getGlabKnownHosts', () => {
     ])
     expect(glabExecFileAsyncMock).toHaveBeenCalledTimes(2)
   })
+
+  it('removes a timed-out probe from in-flight state so a later call retries', async () => {
+    let rejectProbe!: (error: Error) => void
+    glabExecFileAsyncMock
+      .mockImplementationOnce(
+        () =>
+          new Promise((_resolve, reject) => {
+            rejectProbe = reject
+          })
+      )
+      .mockResolvedValueOnce({ stdout: 'Logged in to recovered.test as user\n', stderr: '' })
+
+    const first = getGlabKnownHosts(undefined, { wslDistro: 'Ubuntu' })
+    const concurrent = getGlabKnownHosts(undefined, { wslDistro: 'Ubuntu' })
+    expect(glabExecFileAsyncMock).toHaveBeenCalledTimes(1)
+    rejectProbe(new Error('wsl.exe timed out.'))
+
+    await expect(Promise.all([first, concurrent])).resolves.toEqual([
+      ['gitlab.com'],
+      ['gitlab.com']
+    ])
+    await expect(getGlabKnownHosts(undefined, { wslDistro: 'Ubuntu' })).resolves.toEqual([
+      'gitlab.com',
+      'recovered.test'
+    ])
+    expect(glabExecFileAsyncMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not reuse a successful result after an SSH provider reconnects', async () => {
+    const connectionId = 'conn-reconnected'
+    registerSshGitProvider(connectionId, {} as never)
+    glabExecFileAsyncMock
+      .mockResolvedValueOnce({ stdout: 'Logged in to old-tunnel.test as user\n', stderr: '' })
+      .mockResolvedValueOnce({ stdout: 'Logged in to new-tunnel.test as user\n', stderr: '' })
+
+    await expect(getGlabKnownHosts(connectionId)).resolves.toEqual([
+      'gitlab.com',
+      'old-tunnel.test'
+    ])
+    registerSshGitProvider(connectionId, {} as never)
+    await expect(getGlabKnownHosts(connectionId)).resolves.toEqual([
+      'gitlab.com',
+      'new-tunnel.test'
+    ])
+    expect(glabExecFileAsyncMock).toHaveBeenCalledTimes(2)
+    unregisterSshGitProvider(connectionId)
+  })
 })
diff --git a/src/main/gitlab/issues.test.ts b/src/main/gitlab/issues.test.ts
index edc6d245733..cde9d4f9e01 100644
--- a/src/main/gitlab/issues.test.ts
+++ b/src/main/gitlab/issues.test.ts
@@ -214,7 +214,7 @@ describe('gitlab issue operations', () => {
 
     await listIssues('/repo-root', 5, undefined, 'opened', undefined, 'conn-7')
 
-    expect(getGlabKnownHostsMock).toHaveBeenCalledWith('conn-7')
+    expect(getGlabKnownHostsMock).toHaveBeenCalledWith('conn-7', {})
   })
 
   it('creates an issue and returns its iid + web_url', async () => {
diff --git a/src/main/gitlab/issues.ts b/src/main/gitlab/issues.ts
index ec36f68a0f8..970f9ff1f03 100644
--- a/src/main/gitlab/issues.ts
+++ b/src/main/gitlab/issues.ts
@@ -44,7 +44,7 @@ export async function getIssue(
   connectionId?: string | null,
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<GitLabIssueInfo | null> {
-  const knownHosts = await getGlabKnownHosts(connectionId)
+  const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
   const projectRef = await getIssueProjectRef(repoPath, knownHosts, connectionId, localGitOptions)
   // Why: don't fall back to a cwd-inferred `glab issue view` when the project
   // can't be resolved — on an SSH connection cwd is not the repo dir, so glab
@@ -92,7 +92,7 @@ export async function listIssues(
   connectionId?: string | null,
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<IssueListResult> {
-  const knownHosts = await getGlabKnownHosts(connectionId)
+  const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
   const { source: projectRef } = await resolveIssueSource(
     repoPath,
     preference,
@@ -162,7 +162,7 @@ export async function createIssue(
   if (!trimmedTitle) {
     return { ok: false, error: 'Title is required' }
   }
-  const knownHosts = await getGlabKnownHosts(connectionId)
+  const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
   const { source: projectRef } = await resolveIssueSource(
     repoPath,
     preference,
@@ -232,7 +232,7 @@ export async function updateIssue(
       await resolveIssueSource(
         repoPath,
         preference,
-        await getGlabKnownHosts(connectionId),
+        await getGlabKnownHosts(connectionId, localGitOptions),
         connectionId,
         localGitOptions
       )
@@ -369,7 +369,7 @@ export async function addIssueComment(
       await resolveIssueSource(
         repoPath,
         preference,
-        await getGlabKnownHosts(connectionId),
+        await getGlabKnownHosts(connectionId, localGitOptions),
         connectionId,
         localGitOptions
       )
@@ -427,7 +427,7 @@ export async function listLabels(
   connectionId?: string | null,
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<string[]> {
-  const knownHosts = await getGlabKnownHosts(connectionId)
+  const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
   const { source: projectRef } = await resolveIssueSource(
     repoPath,
     preference,
@@ -468,7 +468,7 @@ export async function listAssignableUsers(
   connectionId?: string | null,
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<GitLabAssignableUser[]> {
-  const knownHosts = await getGlabKnownHosts(connectionId)
+  const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
   const { source: projectRef } = await resolveIssueSource(
     repoPath,
     preference,
diff --git a/src/main/gitlab/work-item-details.ts b/src/main/gitlab/work-item-details.ts
index d9f744c138f..0b37206d6bb 100644
--- a/src/main/gitlab/work-item-details.ts
+++ b/src/main/gitlab/work-item-details.ts
@@ -361,7 +361,7 @@ export async function getWorkItemDetails(
       await resolveIssueSource(
         repoPath,
         preference,
-        await getGlabKnownHosts(connectionId),
+        await getGlabKnownHosts(connectionId, localGitOptions),
         connectionId,
         localGitOptions
       )
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index c255a65863c..17fcec9ba87 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -17895,7 +17895,7 @@ export class OrcaRuntimeService {
       } catch (error) {
         return { error: error instanceof Error ? error.message : 'Could not resolve git remote.' }
       }
-      const knownHosts = await getGlabKnownHosts(repo.connectionId ?? null)
+      const knownHosts = await getGlabKnownHosts(repo.connectionId ?? null, localWorktreeGitOptions)
       const projectRef = await getGitLabProjectRefForRemote(
         repo.path,
         remote,
@@ -18020,7 +18020,7 @@ export class OrcaRuntimeService {
     connectionId?: string | null,
     localGitOptions: { wslDistro?: string } = {}
   ): Promise<string> {
-    const knownHosts = await getGlabKnownHosts(connectionId)
+    const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
     const localGitOptionArgs =
       Object.keys(localGitOptions).length > 0 ? ([localGitOptions] as const) : []
     if (preference === 'origin') {

From daf22f0720b0730911c9e56efa399dd82f1cecbe Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Sun, 19 Jul 2026 17:13:19 -0700
Subject: [PATCH 15/54] Make Create PR handle sync by fast-forwarding
 behind-only branches (#9481)

- Create PR now fast-forwards behind-only branches before committing, using
  git pull --ff-only. This prevents the dirty-then-ahead+behind stall that
  occurred after commit without prior sync.
- Refactor runRemoteAction to return explicit status ('ok', 'failed',
  'superseded', 'skipped') instead of boolean ok + nullable error. Allows
  callers to distinguish real failures from action supersession or skips
  without stale-cache issues.
- Remove isCreatePrIntentSyncConflictError function and sync-conflict-specific
  copy since --ff-only fails cleanly if branch diverged; no merge conflicts
  to resolve.
- Extract isBehindOnlyUpstream predicate to shared module so eligibility
  checks and the one-click flow always agree.
---
 src/main/keybindings/keybinding-file.test.ts  |  10 +-
 src/main/keybindings/keybinding-file.ts       |  39 +++---
 .../right-sidebar/SourceControl.tsx           | 110 +++++++++++------
 ...urce-control-create-pr-intent-flow.test.ts |  88 +-------------
 .../source-control-create-pr-intent-flow.ts   |  40 ++-----
 ...ol-primary-action.create-pr-intent.test.ts |   2 +-
 .../terminal-pane/pty-connection.test.ts      | 113 +++++++++---------
 src/renderer/src/i18n/locales/en.json         |   5 +-
 src/renderer/src/i18n/locales/es.json         |   5 +-
 src/renderer/src/i18n/locales/ja.json         |   5 +-
 src/renderer/src/i18n/locales/ko.json         |   5 +-
 src/renderer/src/i18n/locales/zh.json         |   5 +-
 .../src/lib/source-control-remote-error.ts    |  16 +--
 src/shared/git-upstream-status.test.ts        |  35 ++++++
 src/shared/git-upstream-status.ts             |   8 ++
 .../source-control-create-review-intent.ts    |  17 +--
 16 files changed, 242 insertions(+), 261 deletions(-)

diff --git a/src/main/keybindings/keybinding-file.test.ts b/src/main/keybindings/keybinding-file.test.ts
index 57a000c3217..4fd295d4c50 100644
--- a/src/main/keybindings/keybinding-file.test.ts
+++ b/src/main/keybindings/keybinding-file.test.ts
@@ -370,13 +370,17 @@ describe('keybinding-file', () => {
 
   it('throws instead of freezing the seed when a legacy binding fails normalization', () => {
     // A dropped pin must not be silent: the service catches the throw and keeps
-    // the cohort pending so a corrected build can retry the seed.
+    // the cohort pending so a corrected build can retry the seed. Valid pins
+    // from the same batch are still written so users keep the good shortcuts.
     expect(() =>
       seedLegacyTabSwitchBindings(filePath, 'darwin', {
-        'tab.nextSameType': ['J']
+        'tab.nextSameType': ['J'],
+        'tab.previousSameType': ['Mod+Shift+BracketLeft']
       })
     ).toThrow(/normalize/i)
-    expect(readKeybindingFile(filePath, 'darwin').platformOverrides.darwin).toEqual({})
+    expect(readKeybindingFile(filePath, 'darwin').platformOverrides.darwin).toEqual({
+      'tab.previousSameType': ['Mod+Shift+BracketLeft']
+    })
   })
 
   it('does not replace an unreadable keybindings file while seeding', () => {
diff --git a/src/main/keybindings/keybinding-file.ts b/src/main/keybindings/keybinding-file.ts
index b07e8759e72..4d41a42ba87 100644
--- a/src/main/keybindings/keybinding-file.ts
+++ b/src/main/keybindings/keybinding-file.ts
@@ -353,26 +353,31 @@ export function seedLegacyTabSwitchBindings(
     return { seeded: false, snapshot: current }
   }
 
-  // Why: never freeze the one-shot after dropping a pin — a normalization
-  // failure must throw so the cohort stays pending and a fixed build retries.
-  const pins = toSeed.map((actionId) => {
+  // Why: seed every pin that normalizes, but never freeze the one-shot if any
+  // pin was dropped — throw after writing good pins so the cohort stays pending
+  // and a fixed build retries the failed action without wiping the others.
+  const pins: (readonly [KeybindingActionId, string[]])[] = []
+  const failedActionIds: KeybindingActionId[] = []
+  for (const actionId of toSeed) {
     const normalized = normalizeKeybindingArrayForAction(actionId, legacyBindings[actionId] ?? [])
     if (!Array.isArray(normalized)) {
-      throw new Error(`Could not normalize legacy binding for "${actionId}".`)
+      failedActionIds.push(actionId)
+      continue
     }
-    return [actionId, normalized] as const
-  })
-  const snapshot = writeActivePlatformSection(
-    path,
-    platform,
-    current.commonOverrides,
-    (activePlatform) => {
-      for (const [actionId, normalized] of pins) {
-        activePlatform[actionId] = normalized
-      }
-    }
-  )
-  return { seeded: true, snapshot }
+    pins.push([actionId, normalized])
+  }
+  const snapshot =
+    pins.length > 0
+      ? writeActivePlatformSection(path, platform, current.commonOverrides, (activePlatform) => {
+          for (const [actionId, normalized] of pins) {
+            activePlatform[actionId] = normalized
+          }
+        })
+      : current
+  if (failedActionIds.length > 0) {
+    throw new Error(`Could not normalize legacy binding for "${failedActionIds.join('", "')}".`)
+  }
+  return { seeded: pins.length > 0, snapshot }
 }
 
 // Why: the one-shot seed migration and Settings writes must produce the same
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index a4eaf4250bc..d9cb51a24a3 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -195,7 +195,10 @@ import { resolveCreateReviewDraftTitle } from './create-review-draft-title'
 import { GitHistoryPanel, type GitHistoryPanelState } from './GitHistoryPanel'
 import { useGitHistoryCommitActions } from './useGitHistoryCommitActions'
 import { normalizeHostedReviewHeadRef } from '../../../../shared/hosted-review-refs'
-import { shouldForcePushWithLeaseForUpstream } from '../../../../shared/git-upstream-status'
+import {
+  isBehindOnlyUpstream,
+  shouldForcePushWithLeaseForUpstream
+} from '../../../../shared/git-upstream-status'
 import type {
   DiffComment,
   GitBranchChangeEntry,
@@ -258,7 +261,6 @@ import {
   createPrIntentRunTokenMatches,
   getCreatePrIntentCommitFailureNoticeMessage,
   getCreatePrIntentStagePaths,
-  isCreatePrIntentSyncConflictError,
   resolveCreatePrIntentReviewBase,
   resolveCreatePrIntentRemoteStep,
   type CreatePrIntentRunToken
@@ -2515,6 +2517,16 @@ function SourceControlInner(): React.JSX.Element {
   // chevron dropdown can trigger. Keeps the error-swallow pattern in one
   // place — store slices already surface actionable toasts, so additional
   // try/catch here would duplicate the notification.
+  // Why: callers must distinguish real failures from "a newer remote action won
+  // the sequence" and "this call was a no-op (missing target/base)". Collapsing
+  // those into `{ ok: false, error: null }` made Create PR treat supersession as
+  // a destructive remote failure.
+  type RunRemoteActionResult =
+    | { status: 'ok' }
+    | { status: 'failed'; error: SourceControlActionError }
+    | { status: 'superseded' }
+    | { status: 'skipped' }
+
   const runRemoteAction = useCallback(
     async (
       kind:
@@ -2530,10 +2542,7 @@ function SourceControlInner(): React.JSX.Element {
         target?: SourceControlOperationTarget
         baseRef?: string | null
       }
-      // Why: return the failure inline (null error = success or superseded) so
-      // callers like the Create PR intent flow can classify it without a
-      // stale-prone mirror of remoteActionErrors.
-    ): Promise<{ ok: boolean; error: SourceControlActionError | null }> => {
+    ): Promise<RunRemoteActionResult> => {
       const target =
         options?.target ??
         (activeWorktreeId && worktreePath
@@ -2546,7 +2555,7 @@ function SourceControlInner(): React.JSX.Element {
             }
           : null)
       if (!target) {
-        return { ok: false, error: null }
+        return { status: 'skipped' }
       }
       const sequence = (remoteActionErrorSequenceByWorktreeRef.current[target.worktreeId] ?? 0) + 1
       remoteActionErrorSequenceByWorktreeRef.current[target.worktreeId] = sequence
@@ -2572,7 +2581,7 @@ function SourceControlInner(): React.JSX.Element {
             target.pushTarget,
             { runtimeTargetSettings: target.settings }
           )
-          return { ok: true, error: null }
+          return { status: 'ok' }
         }
         if (kind === 'push') {
           // Why: kind 'push' must stay a regular push. Force-with-lease is only
@@ -2587,7 +2596,7 @@ function SourceControlInner(): React.JSX.Element {
             target.pushTarget,
             { runtimeTargetSettings: target.settings }
           )
-          return { ok: true, error: null }
+          return { status: 'ok' }
         }
         if (kind === 'force_push') {
           await pushBranch(
@@ -2598,7 +2607,7 @@ function SourceControlInner(): React.JSX.Element {
             target.pushTarget,
             { forceWithLease: true, runtimeTargetSettings: target.settings }
           )
-          return { ok: true, error: null }
+          return { status: 'ok' }
         }
         if (kind === 'pull') {
           await pullBranch(
@@ -2610,7 +2619,7 @@ function SourceControlInner(): React.JSX.Element {
               runtimeTargetSettings: target.settings
             }
           )
-          return { ok: true, error: null }
+          return { status: 'ok' }
         }
         if (kind === 'fast_forward') {
           await fastForwardBranch(
@@ -2620,7 +2629,7 @@ function SourceControlInner(): React.JSX.Element {
             target.pushTarget,
             { runtimeTargetSettings: target.settings }
           )
-          return { ok: true, error: null }
+          return { status: 'ok' }
         }
         if (kind === 'fetch') {
           await fetchBranch(
@@ -2632,12 +2641,12 @@ function SourceControlInner(): React.JSX.Element {
               runtimeTargetSettings: target.settings
             }
           )
-          return { ok: true, error: null }
+          return { status: 'ok' }
         }
         if (kind === 'rebase') {
           const baseRef = options?.baseRef ?? effectiveBaseRef
           if (!baseRef) {
-            return { ok: false, error: null }
+            return { status: 'skipped' }
           }
           await rebaseFromBase(
             target.worktreeId,
@@ -2647,7 +2656,7 @@ function SourceControlInner(): React.JSX.Element {
             target.pushTarget,
             { runtimeTargetSettings: target.settings }
           )
-          return { ok: true, error: null }
+          return { status: 'ok' }
         }
         await syncBranch(
           target.worktreeId,
@@ -2661,14 +2670,14 @@ function SourceControlInner(): React.JSX.Element {
         if (remoteActionErrorSequenceByWorktreeRef.current[target.worktreeId] === sequence) {
           setRemoteActionErrors((prev) => ({ ...prev, [target.worktreeId]: null }))
         }
-        return { ok: true, error: null }
+        return { status: 'ok' }
       } catch (error) {
         // Why: remote action failures are surfaced by editor-slice actions to keep
         // one consistent toast path and avoid duplicate notifications in the UI.
         // Keep the latest failure inline too: dropdown-only actions like Fetch can
         // otherwise look like nothing happened once the menu closes.
         if (remoteActionErrorSequenceByWorktreeRef.current[target.worktreeId] !== sequence) {
-          return { ok: false, error: null }
+          return { status: 'superseded' }
         }
         const actionError: SourceControlActionError = {
           kind,
@@ -2682,7 +2691,7 @@ function SourceControlInner(): React.JSX.Element {
           sequence
         }
         setRemoteActionErrors((prev) => ({ ...prev, [target.worktreeId]: actionError }))
-        return { ok: false, error: actionError }
+        return { status: 'failed', error: actionError }
       } finally {
         if (!options?.target) {
           refreshSourceControlAfterRemoteAction({
@@ -3965,6 +3974,42 @@ function SourceControlInner(): React.JSX.Element {
         return
       }
 
+      // Why: fast-forward behind-only *before* commit so a dirty worktree does
+      // not become ahead+behind after Create PR commits, then dead-end at the
+      // explicit sync-first stop. --ff-only refuses if the branch diverged mid
+      // flight or local edits would be overwritten — never auto-merges.
+      if (isBehindOnlyUpstream(latestUpstreamStatus)) {
+        setCreatePrIntentNoticeForWorktree(token.worktreeId, {
+          tone: 'muted',
+          message: translate(
+            'auto.components.right.sidebar.SourceControl.createPrIntentFastForwarding',
+            'Updating branch…'
+          )
+        })
+        const earlyFfResult = await runRemoteAction('fast_forward', {
+          target: operationTarget
+        })
+        if (abortIfStale()) {
+          return
+        }
+        if (earlyFfResult.status === 'superseded') {
+          return
+        }
+        if (earlyFfResult.status !== 'ok') {
+          setCreatePrIntentNoticeForWorktree(token.worktreeId, {
+            tone: 'destructive',
+            message: translate(
+              'auto.components.right.sidebar.SourceControl.createPrIntentRemoteFailed',
+              'Could not update the remote branch. Retry Create PR.'
+            )
+          })
+          return
+        }
+        if (!(await refreshIntentSnapshot())) {
+          return
+        }
+      }
+
       if (!(await stageLatestIntentPaths())) {
         return
       }
@@ -4098,7 +4143,7 @@ function SourceControlInner(): React.JSX.Element {
       if (remoteStep === 'blocked' || remoteStep === 'none') {
         setCreatePrIntentNoticeForWorktree(token.worktreeId, {
           tone: 'muted',
-          // Why: a diverged branch is deliberately not auto-synced (that would
+          // Why: a diverged branch is deliberately not auto-prepared (that would
           // merge without consent), so keep the explicit sync-first guidance.
           message:
             eligibility.blockedReason === 'needs_sync'
@@ -4129,10 +4174,10 @@ function SourceControlInner(): React.JSX.Element {
                   'auto.components.right.sidebar.SourceControl.createPrIntentForcePushing',
                   'Force pushing with lease…'
                 )
-              : remoteStep === 'sync'
+              : remoteStep === 'fast_forward'
                 ? translate(
-                    'auto.components.right.sidebar.SourceControl.createPrIntentSyncing',
-                    'Syncing branch…'
+                    'auto.components.right.sidebar.SourceControl.createPrIntentFastForwarding',
+                    'Updating branch…'
                   )
                 : translate(
                     'auto.components.right.sidebar.SourceControl.createPrIntentPushing',
@@ -4146,20 +4191,17 @@ function SourceControlInner(): React.JSX.Element {
       if (abortIfStale()) {
         return
       }
-      if (!remoteResult.ok) {
-        // A sync push-stage rejection is not a conflict — it falls to the generic
-        // copy so the push-recovery panel drives the fix.
+      // Superseded by a newer remote action — drop quietly, same as target drift.
+      if (remoteResult.status === 'superseded') {
+        return
+      }
+      if (remoteResult.status !== 'ok') {
         setCreatePrIntentNoticeForWorktree(token.worktreeId, {
           tone: 'destructive',
-          message: isCreatePrIntentSyncConflictError(remoteResult.error)
-            ? translate(
-                'auto.components.right.sidebar.SourceControl.createPrIntentSyncConflicts',
-                'Sync hit conflicts. Resolve them, then retry Create PR.'
-              )
-            : translate(
-                'auto.components.right.sidebar.SourceControl.createPrIntentRemoteFailed',
-                'Could not update the remote branch. Retry Create PR.'
-              )
+          message: translate(
+            'auto.components.right.sidebar.SourceControl.createPrIntentRemoteFailed',
+            'Could not update the remote branch. Retry Create PR.'
+          )
         })
         return
       }
diff --git a/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts b/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts
index a1f6459dce2..753ebaaa750 100644
--- a/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts
@@ -7,7 +7,6 @@ import {
   createPrIntentRunTokenMatches,
   getCreatePrIntentCommitFailureNoticeMessage,
   getCreatePrIntentStagePaths,
-  isCreatePrIntentSyncConflictError,
   resolveCreatePrIntentReviewBase,
   resolveCreatePrIntentRemoteStep
 } from './source-control-create-pr-intent-flow'
@@ -233,9 +232,9 @@ describe('source-control Create PR intent flow helpers', () => {
     ).toBe('force_push')
   })
 
-  it('syncs behind-only branches, blocks diverged and unpublished-without-commits branches', () => {
-    // Genuinely diverged (local + non-equivalent remote commits): auto-syncing
-    // would merge without consent, so the intent flow keeps the explicit stop.
+  it('fast-forwards behind-only branches, blocks diverged and unpublished-without-commits branches', () => {
+    // Genuinely diverged (local + non-equivalent remote commits): auto-merging
+    // would reconcile without consent, so the intent flow keeps the explicit stop.
     expect(
       resolveCreatePrIntentRemoteStep({
         upstreamStatus: { hasUpstream: true, ahead: 1, behind: 1 },
@@ -251,7 +250,7 @@ describe('source-control Create PR intent flow helpers', () => {
       })
     ).toBe('blocked')
 
-    // Behind with no local commits (pure fast-forward case) auto-syncs.
+    // Behind with no local commits: pure --ff-only (never plain merge sync).
     expect(
       resolveCreatePrIntentRemoteStep({
         upstreamStatus: { hasUpstream: true, ahead: 0, behind: 3 },
@@ -265,7 +264,7 @@ describe('source-control Create PR intent flow helpers', () => {
           reviewLookupOutcome: 'not_found'
         }
       })
-    ).toBe('sync')
+    ).toBe('fast_forward')
 
     expect(
       resolveCreatePrIntentRemoteStep({
@@ -302,81 +301,4 @@ describe('source-control Create PR intent flow helpers', () => {
       })
     ).toBe('localized Pre-commit hook failed.')
   })
-
-  it('treats only a genuine merge-conflict sync failure as a conflict for notice copy', () => {
-    // Pull/merge conflict from this sync: the user must resolve conflicts.
-    expect(
-      isCreatePrIntentSyncConflictError({
-        kind: 'sync',
-        syncPushStage: false,
-        rawError: 'CONFLICT (content): Merge conflict in src/app.ts'
-      })
-    ).toBe(true)
-    // An unconcluded prior merge also counts as a conflict to resolve.
-    expect(
-      isCreatePrIntentSyncConflictError({
-        kind: 'sync',
-        rawError: 'error: you have not concluded your merge (MERGE_HEAD exists).'
-      })
-    ).toBe(true)
-
-    // A fetch/network/auth failure during sync is NOT a conflict, even though it
-    // is not marked as the push stage — it must fall to the generic copy.
-    expect(
-      isCreatePrIntentSyncConflictError({
-        kind: 'sync',
-        syncPushStage: false,
-        rawError: 'fatal: Authentication failed for remote'
-      })
-    ).toBe(false)
-    // No raw error at all is not a conflict.
-    expect(isCreatePrIntentSyncConflictError({ kind: 'sync' })).toBe(false)
-
-    // Push-stage rejection during sync is a push failure, not a conflict.
-    expect(
-      isCreatePrIntentSyncConflictError({
-        kind: 'sync',
-        syncPushStage: true,
-        rawError: 'CONFLICT (content): Merge conflict in src/app.ts'
-      })
-    ).toBe(false)
-
-    // Non-sync remote failures never use the conflict copy.
-    expect(isCreatePrIntentSyncConflictError({ kind: 'push' })).toBe(false)
-    expect(
-      isCreatePrIntentSyncConflictError({
-        kind: 'force_push',
-        syncPushStage: false,
-        rawError: 'CONFLICT (content): Merge conflict in src/app.ts'
-      })
-    ).toBe(false)
-    expect(isCreatePrIntentSyncConflictError(null)).toBe(false)
-    expect(isCreatePrIntentSyncConflictError(undefined)).toBe(false)
-  })
-
-  it('recognizes every merge-conflict wording git can emit during sync', () => {
-    // The fresh-conflict pattern's other alternatives: "Automatic merge failed"
-    // and "fix conflicts" are the most common real pull output.
-    expect(
-      isCreatePrIntentSyncConflictError({
-        kind: 'sync',
-        syncPushStage: false,
-        rawError: 'Automatic merge failed; fix conflicts and then commit the result.'
-      })
-    ).toBe(true)
-    // The unconcluded-merge pattern's other alternatives: "unmerged files" and
-    // "needs merge".
-    expect(
-      isCreatePrIntentSyncConflictError({
-        kind: 'sync',
-        rawError: 'error: Pulling is not possible because you have unmerged files.'
-      })
-    ).toBe(true)
-    expect(
-      isCreatePrIntentSyncConflictError({
-        kind: 'sync',
-        rawError: "error: path 'src/app.ts' needs merge"
-      })
-    ).toBe(true)
-  })
 })
diff --git a/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.ts b/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.ts
index 000fc19db21..bafba4c8504 100644
--- a/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.ts
@@ -1,12 +1,13 @@
-import { shouldForcePushWithLeaseForUpstream } from '../../../../shared/git-upstream-status'
+import {
+  isBehindOnlyUpstream,
+  shouldForcePushWithLeaseForUpstream
+} from '../../../../shared/git-upstream-status'
 import type { HostedReviewCreationEligibility } from '../../../../shared/hosted-review'
 import {
   normalizeHostedReviewBaseRef,
   normalizeHostedReviewHeadRef
 } from '../../../../shared/hosted-review-refs'
 import type { GitStatusEntry, GitUpstreamStatus } from '../../../../shared/types'
-import { isMergeConflictErrorMessage } from '../../lib/source-control-remote-error'
-import type { SourceControlActionError } from './source-control-action-error'
 import { summarizeCommitFailure } from './commit-failure-summary'
 import { getStageAllPaths } from './discard-all-sequence'
 
@@ -14,7 +15,7 @@ export type CreatePrIntentRemoteStep =
   | 'publish'
   | 'push'
   | 'force_push'
-  | 'sync'
+  | 'fast_forward'
   | 'blocked'
   | 'none'
 
@@ -150,36 +151,17 @@ export function resolveCreatePrIntentRemoteStep({
     if (shouldForcePushWithLeaseForUpstream(upstreamStatus)) {
       return 'force_push'
     }
-    // Why: auto-sync only a behind-only branch, where the pull is a fast-forward
-    // that cannot create a merge commit or strand the worktree mid-merge. A
-    // genuinely diverged branch keeps the explicit sync-first stop so Create PR
-    // never merges without consent.
-    return upstreamStatus?.hasUpstream && upstreamStatus.ahead === 0 && upstreamStatus.behind > 0
-      ? 'sync'
-      : 'blocked'
+    // Why: auto-prepare only a behind-only branch, and only via `--ff-only`.
+    // Plain sync/merge could create a merge commit if the branch diverges mid
+    // flight or the user has pull.ff=no; --ff-only enforces the no-consent-
+    // merge invariant at execution time. Genuinely diverged branches keep the
+    // explicit sync-first stop.
+    return isBehindOnlyUpstream(upstreamStatus) ? 'fast_forward' : 'blocked'
   }
 
   return 'none'
 }
 
-export type CreatePrIntentRemoteFailure =
-  | (Pick<SourceControlActionError, 'kind' | 'syncPushStage'> &
-      Partial<Pick<SourceControlActionError, 'rawError'>>)
-  | null
-  | undefined
-
-export function isCreatePrIntentSyncConflictError(error: CreatePrIntentRemoteFailure): boolean {
-  // Why: only a genuine merge conflict earns the "resolve conflicts" copy. A
-  // sync push-stage rejection is a push failure, and a fetch/network/auth
-  // failure during sync is neither a conflict nor push-stage — both must fall
-  // to the generic remote-failed notice, so match the raw git output rather
-  // than assuming every non-push-stage sync failure is a conflict.
-  if (error?.kind !== 'sync' || error.syncPushStage === true) {
-    return false
-  }
-  return isMergeConflictErrorMessage(error.rawError ?? '')
-}
-
 export function getCreatePrIntentCommitFailureNoticeMessage(
   commitError: string | null | undefined,
   copy: {
diff --git a/src/renderer/src/components/right-sidebar/source-control-primary-action.create-pr-intent.test.ts b/src/renderer/src/components/right-sidebar/source-control-primary-action.create-pr-intent.test.ts
index 5d5f249a3bd..c56892b71ec 100644
--- a/src/renderer/src/components/right-sidebar/source-control-primary-action.create-pr-intent.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-primary-action.create-pr-intent.test.ts
@@ -73,7 +73,7 @@ describe('resolvePrimaryAction Create PR intent', () => {
     expect(result.disabled).toBe(false)
   })
 
-  it('returns Create PR intent for a behind-only branch (fast-forward sync)', () => {
+  it('returns Create PR intent for a behind-only branch (fast-forward prepare)', () => {
     const input = inputs({
       upstreamStatus: {
         hasUpstream: true,
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.test.ts b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
index 70a79b26d31..7b119905d47 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
@@ -17731,64 +17731,69 @@ describe('connectPanePty', () => {
     // land in the first advance window, confirming exit before the replacement
     // hook owner is set and racing the very veto this test asserts.
     const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0.5)
-    const getForegroundProcess = vi.mocked(window.api.pty.getForegroundProcess)
-    getForegroundProcess.mockResolvedValue('codex')
-    const paneKey = makePaneKey('tab-1', LEAF_1)
-    const pane = createPane(1)
-    const manager = createManager(1)
-    const deps = createDeps()
+    try {
+      const getForegroundProcess = vi.mocked(window.api.pty.getForegroundProcess)
+      getForegroundProcess.mockResolvedValue('codex')
+      const paneKey = makePaneKey('tab-1', LEAF_1)
+      const pane = createPane(1)
+      const manager = createManager(1)
+      const deps = createDeps()
 
-    connectPanePty(pane as never, manager as never, deps as never)
-    await flushAsyncTicks()
-    const titleHandler = createdTransportOptions[0]?.onTitleChange as
-      | ((title: string, rawTitle: string) => void)
-      | undefined
-    const idleHandler = createdTransportOptions[0]?.onAgentBecameIdle as
-      | ((title: string) => void)
-      | undefined
-    if (!titleHandler || !idleHandler) {
-      throw new Error('Expected title and idle handlers to be registered')
-    }
-
-    titleHandler('Codex working', 'Codex working')
-    await vi.advanceTimersByTimeAsync(2_500)
-    const inspectionsBeforeIdle = getForegroundProcess.mock.calls.length
-    getForegroundProcess.mockResolvedValue(null)
-    // Why: active process polling is jittered, so a fixed window can consume
-    // both null samples before the replacement hook row is installed.
-    for (
-      let attempts = 0;
-      getForegroundProcess.mock.calls.length === inspectionsBeforeIdle;
-      attempts += 1
-    ) {
-      if (attempts >= 10) {
-        throw new Error('Expected the first idle process inspection')
+      connectPanePty(pane as never, manager as never, deps as never)
+      await flushAsyncTicks()
+      const titleHandler = createdTransportOptions[0]?.onTitleChange as
+        | ((title: string, rawTitle: string) => void)
+        | undefined
+      const idleHandler = createdTransportOptions[0]?.onAgentBecameIdle as
+        | ((title: string) => void)
+        | undefined
+      if (!titleHandler || !idleHandler) {
+        throw new Error('Expected title and idle handlers to be registered')
       }
-      await vi.advanceTimersToNextTimerAsync()
-    }
-    expect(getForegroundProcess).toHaveBeenCalledTimes(inspectionsBeforeIdle + 1)
 
-    mockStoreState.agentStatusByPaneKey[paneKey] = {
-      state: 'working',
-      prompt: 'replacement agent turn',
-      updatedAt: Date.now(),
-      stateStartedAt: Date.now(),
-      agentType: 'claude',
-      paneKey,
-      stateHistory: []
-    }
-    idleHandler('Claude done')
-    await vi.advanceTimersByTimeAsync(800)
-    await vi.advanceTimersByTimeAsync(AGENT_TASK_COMPLETE_NOTIFICATION_MAX_WAIT_MS)
+      titleHandler('Codex working', 'Codex working')
+      await vi.advanceTimersByTimeAsync(2_500)
+      const inspectionsBeforeIdle = getForegroundProcess.mock.calls.length
+      getForegroundProcess.mockResolvedValue(null)
+      // Why: active process polling is jittered, so a fixed window can consume
+      // both null samples before the replacement hook row is installed.
+      for (
+        let attempts = 0;
+        getForegroundProcess.mock.calls.length === inspectionsBeforeIdle;
+        attempts += 1
+      ) {
+        if (attempts >= 10) {
+          throw new Error('Expected the first idle process inspection')
+        }
+        await vi.advanceTimersToNextTimerAsync()
+      }
+      expect(getForegroundProcess).toHaveBeenCalledTimes(inspectionsBeforeIdle + 1)
 
-    expect(deps.dispatchNotification).not.toHaveBeenCalledWith(
-      expect.objectContaining({ source: 'agent-task-complete' })
-    )
-    expect(pane.terminal.write).not.toHaveBeenCalledWith(
-      RESET_TERMINAL_CURSOR_STYLE,
-      expect.any(Function)
-    )
-    randomSpy.mockRestore()
+      mockStoreState.agentStatusByPaneKey[paneKey] = {
+        state: 'working',
+        prompt: 'replacement agent turn',
+        updatedAt: Date.now(),
+        stateStartedAt: Date.now(),
+        agentType: 'claude',
+        paneKey,
+        stateHistory: []
+      }
+      idleHandler('Claude done')
+      await vi.advanceTimersByTimeAsync(800)
+      await vi.advanceTimersByTimeAsync(AGENT_TASK_COMPLETE_NOTIFICATION_MAX_WAIT_MS)
+
+      expect(deps.dispatchNotification).not.toHaveBeenCalledWith(
+        expect.objectContaining({ source: 'agent-task-complete' })
+      )
+      expect(pane.terminal.write).not.toHaveBeenCalledWith(
+        RESET_TERMINAL_CURSOR_STYLE,
+        expect.any(Function)
+      )
+    } finally {
+      // Why: any assertion failure above must not pin Math.random for later tests
+      // in this large suite.
+      randomSpy.mockRestore()
+    }
   })
 
   it('preserves replacement-agent title side effects through the process replacement veto', async () => {
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 23cfccec709..427fa58d0e5 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -9709,6 +9709,7 @@
             "createPrIntentPublishing": "Publishing branch…",
             "createPrIntentForcePushing": "Force pushing with lease…",
             "createPrIntentPushing": "Pushing commits…",
+            "createPrIntentFastForwarding": "Updating branch…",
             "createPrIntentRemoteFailed": "Could not update the remote branch. Retry Create PR.",
             "createPrIntentGeneratingDetails": "Generating review details…",
             "createPrIntentBranchChangedDuringDetails": "Branch changed while generating review details. Retry Create PR.",
@@ -9741,9 +9742,7 @@
               "a9bf7c171a": "Push Failed",
               "834cb3f23d": "Fix with AI",
               "783a808870": "Close"
-            },
-            "createPrIntentSyncConflicts": "Sync hit conflicts. Resolve them, then retry Create PR.",
-            "createPrIntentSyncing": "Syncing branch…"
+            }
           },
           "SourceControlAgentActionDialog": {
             "8e856842d1": "Could not start the selected agent.",
diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json
index fe3ac1620a8..c7e2e7ccc1c 100644
--- a/src/renderer/src/i18n/locales/es.json
+++ b/src/renderer/src/i18n/locales/es.json
@@ -9686,6 +9686,7 @@
             "createPrIntentPublishing": "Publicando rama…",
             "createPrIntentForcePushing": "Haciendo force push con lease…",
             "createPrIntentPushing": "Haciendo push de commits…",
+            "createPrIntentFastForwarding": "Actualizando rama…",
             "createPrIntentRemoteFailed": "No se pudo actualizar la rama remota. Vuelve a intentar Crear PR.",
             "createPrIntentGeneratingDetails": "Generando detalles de revisión…",
             "createPrIntentBranchChangedDuringDetails": "La rama cambió mientras se generaban los detalles de la revisión. Vuelve a intentar Crear PR.",
@@ -9718,9 +9719,7 @@
               "a9bf7c171a": "Push fallido",
               "834cb3f23d": "Corregir con AI",
               "783a808870": "Cerrar"
-            },
-            "createPrIntentSyncConflicts": "La sincronización encontró conflictos. Resuélvelos y vuelve a intentar Crear PR.",
-            "createPrIntentSyncing": "Sincronizando rama…"
+            }
           },
           "SourceControlAgentActionDialog": {
             "8e856842d1": "No se pudo iniciar el agente seleccionado.",
diff --git a/src/renderer/src/i18n/locales/ja.json b/src/renderer/src/i18n/locales/ja.json
index eaf4518ccbb..6c4390633c4 100644
--- a/src/renderer/src/i18n/locales/ja.json
+++ b/src/renderer/src/i18n/locales/ja.json
@@ -9686,6 +9686,7 @@
             "createPrIntentPublishing": "ブランチを公開中…",
             "createPrIntentForcePushing": "lease 付きで強制プッシュ中…",
             "createPrIntentPushing": "commits をプッシュ中…",
+            "createPrIntentFastForwarding": "ブランチを更新中…",
             "createPrIntentRemoteFailed": "リモートブランチを更新できませんでした。Create PR を再試行してください。",
             "createPrIntentGeneratingDetails": "レビューの詳細を生成中…",
             "createPrIntentBranchChangedDuringDetails": "レビューの詳細を生成中にブランチが変更されました。Create PR を再試行してください。",
@@ -9718,9 +9719,7 @@
               "a9bf7c171a": "プッシュ失敗",
               "834cb3f23d": "AIで修正",
               "783a808870": "閉じる"
-            },
-            "createPrIntentSyncConflicts": "同期で競合が発生しました。解決してから Create PR を再試行してください。",
-            "createPrIntentSyncing": "ブランチを同期中…"
+            }
           },
           "SourceControlAgentActionDialog": {
             "8e856842d1": "選択した agent を開始できませんでした。",
diff --git a/src/renderer/src/i18n/locales/ko.json b/src/renderer/src/i18n/locales/ko.json
index 742d8531e4c..5da5129544d 100644
--- a/src/renderer/src/i18n/locales/ko.json
+++ b/src/renderer/src/i18n/locales/ko.json
@@ -9686,6 +9686,7 @@
             "createPrIntentPublishing": "브랜치를 게시하는 중…",
             "createPrIntentForcePushing": "lease로 강제 푸시하는 중…",
             "createPrIntentPushing": "commits을 푸시하는 중…",
+            "createPrIntentFastForwarding": "브랜치를 업데이트하는 중…",
             "createPrIntentRemoteFailed": "원격 브랜치를 업데이트할 수 없습니다. Create PR을 다시 시도하세요.",
             "createPrIntentGeneratingDetails": "리뷰 세부 정보 생성 중…",
             "createPrIntentBranchChangedDuringDetails": "리뷰 세부 정보를 생성하는 동안 브랜치가 변경되었습니다. Create PR을 다시 시도하세요.",
@@ -9718,9 +9719,7 @@
               "a9bf7c171a": "푸시 실패",
               "834cb3f23d": "AI로 수정",
               "783a808870": "닫기"
-            },
-            "createPrIntentSyncConflicts": "동기화 중 충돌이 발생했습니다. 해결한 다음 Create PR을 다시 시도하세요.",
-            "createPrIntentSyncing": "브랜치를 동기화하는 중…"
+            }
           },
           "SourceControlAgentActionDialog": {
             "8e856842d1": "선택한 agent를 시작할 수 없습니다.",
diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json
index 657a353bd8c..be2ed642cc5 100644
--- a/src/renderer/src/i18n/locales/zh.json
+++ b/src/renderer/src/i18n/locales/zh.json
@@ -9686,6 +9686,7 @@
             "createPrIntentPublishing": "正在发布分支…",
             "createPrIntentForcePushing": "正在使用 lease 强制推送…",
             "createPrIntentPushing": "正在推送提交…",
+            "createPrIntentFastForwarding": "正在更新分支…",
             "createPrIntentRemoteFailed": "无法更新远程分支。请重试创建 PR。",
             "createPrIntentGeneratingDetails": "正在生成审查详情…",
             "createPrIntentBranchChangedDuringDetails": "生成审查详情时分支已更改。请重试创建 PR。",
@@ -9718,9 +9719,7 @@
               "a9bf7c171a": "推送失败",
               "834cb3f23d": "使用 AI 修复",
               "783a808870": "关闭"
-            },
-            "createPrIntentSyncConflicts": "同步遇到冲突。请解决后重试创建 PR。",
-            "createPrIntentSyncing": "正在同步分支…"
+            }
           },
           "SourceControlAgentActionDialog": {
             "8e856842d1": "无法启动选定的智能体。",
diff --git a/src/renderer/src/lib/source-control-remote-error.ts b/src/renderer/src/lib/source-control-remote-error.ts
index 57edcd211be..286f2e21531 100644
--- a/src/renderer/src/lib/source-control-remote-error.ts
+++ b/src/renderer/src/lib/source-control-remote-error.ts
@@ -110,24 +110,12 @@ export function isSyncPushStageError(error: unknown): boolean {
   )
 }
 
-// Why: shared patterns so conflict classification and toast copy cannot drift.
-// Unconcluded prior merge vs. a fresh conflict from this operation produce
-// different user-facing messages, but Create PR treats both as "sync conflict".
+// Why: shared patterns so unconcluded-merge vs fresh-conflict toast copy cannot
+// drift between the two branches below.
 const UNCONCLUDED_MERGE_ERROR_PATTERN =
   /unmerged files|needs merge|you have not concluded your merge/i
 const FRESH_MERGE_CONFLICT_ERROR_PATTERN = /automatic merge failed|CONFLICT \(|fix conflicts/i
 
-// Why: detects "the working tree has merge conflicts the user must resolve" —
-// both an unconcluded prior merge and a fresh conflict from this operation.
-// Lets the Create PR flow tell a real sync conflict apart from a
-// fetch/network/auth/push failure that only looks similar.
-export function isMergeConflictErrorMessage(message: string): boolean {
-  return (
-    UNCONCLUDED_MERGE_ERROR_PATTERN.test(message) ||
-    FRESH_MERGE_CONFLICT_ERROR_PATTERN.test(message)
-  )
-}
-
 export function resolveRemoteOperationErrorMessage(
   error: unknown,
   options?: RemoteOperationErrorOptions
diff --git a/src/shared/git-upstream-status.test.ts b/src/shared/git-upstream-status.test.ts
index 62e9e57cb4f..32cf16ab92e 100644
--- a/src/shared/git-upstream-status.test.ts
+++ b/src/shared/git-upstream-status.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
+  isBehindOnlyUpstream,
   shouldForcePushWithLeaseForUpstream,
   upstreamOnlyCommitsArePatchEquivalent
 } from './git-upstream-status'
@@ -53,3 +54,37 @@ describe('shouldForcePushWithLeaseForUpstream', () => {
     ).toBe(false)
   })
 })
+
+describe('isBehindOnlyUpstream', () => {
+  it('is true only when the branch tracks upstream and is purely behind', () => {
+    expect(
+      isBehindOnlyUpstream({
+        hasUpstream: true,
+        ahead: 0,
+        behind: 3
+      })
+    ).toBe(true)
+    expect(
+      isBehindOnlyUpstream({
+        hasUpstream: true,
+        ahead: 1,
+        behind: 2
+      })
+    ).toBe(false)
+    expect(
+      isBehindOnlyUpstream({
+        hasUpstream: true,
+        ahead: 0,
+        behind: 0
+      })
+    ).toBe(false)
+    expect(
+      isBehindOnlyUpstream({
+        hasUpstream: false,
+        ahead: 0,
+        behind: 3
+      })
+    ).toBe(false)
+    expect(isBehindOnlyUpstream(undefined)).toBe(false)
+  })
+})
diff --git a/src/shared/git-upstream-status.ts b/src/shared/git-upstream-status.ts
index 45152f408f6..6d4ed338dab 100644
--- a/src/shared/git-upstream-status.ts
+++ b/src/shared/git-upstream-status.ts
@@ -46,3 +46,11 @@ export function shouldForcePushWithLeaseForUpstream(
     status.behindCommitsArePatchEquivalent === true
   )
 }
+
+// Why: behind-only is the only auto-prepare case Create PR can safely handle
+// with a pure fast-forward (no local unique commits to reconcile). Eligibility
+// and the intent remote-step resolver must share this predicate so the button
+// and the one-click flow never disagree on what "behind-only" means.
+export function isBehindOnlyUpstream(status: GitUpstreamStatus | undefined): boolean {
+  return status?.hasUpstream === true && status.ahead === 0 && status.behind > 0
+}
diff --git a/src/shared/source-control-create-review-intent.ts b/src/shared/source-control-create-review-intent.ts
index 880fce17700..5d1f517280b 100644
--- a/src/shared/source-control-create-review-intent.ts
+++ b/src/shared/source-control-create-review-intent.ts
@@ -1,4 +1,4 @@
-import { shouldForcePushWithLeaseForUpstream } from './git-upstream-status'
+import { isBehindOnlyUpstream, shouldForcePushWithLeaseForUpstream } from './git-upstream-status'
 import type { HostedReviewCreationEligibility } from './hosted-review'
 import { supportsHostedReviewCreation } from './hosted-review-creation-providers'
 import type { GitUpstreamStatus } from './git-status-types'
@@ -77,16 +77,11 @@ export function resolveCreateReviewIntentEligibility({
     return { eligible: true, kind: 'force_push' }
   }
 
-  // Why: a behind-only branch (no local commits) is safe to prepare with a
-  // fast-forward sync, so the intent flow can handle it in one click. A
-  // genuinely diverged branch stays ineligible — syncing it would merge
-  // without consent, so the user keeps the explicit sync-first step.
-  if (
-    hostedReviewCreation.blockedReason === 'needs_sync' &&
-    upstreamStatus?.hasUpstream === true &&
-    upstreamStatus.ahead === 0 &&
-    upstreamStatus.behind > 0
-  ) {
+  // Why: a behind-only branch is safe to prepare with `git pull --ff-only`, so
+  // the intent flow can handle it in one click. A genuinely diverged branch
+  // stays ineligible — auto-merging would reconcile without consent, so the
+  // user keeps the explicit sync-first step.
+  if (hostedReviewCreation.blockedReason === 'needs_sync' && isBehindOnlyUpstream(upstreamStatus)) {
     return { eligible: true, kind: 'needs_sync' }
   }
 

From a6df23c7624f5827b24f6142d9ba102d80fc1279 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Sun, 19 Jul 2026 17:17:40 -0700
Subject: [PATCH 16/54] Tighten orchestration worktree isolation policy (#9482)

* docs(orchestration): require true isolation for worker worktrees

* docs(orchestration): deduplicate parallel worker guidance

* docs(orchestration): clarify isolation exceptions

* docs(orchestration): clarify checkout preference

* Tighten orchestration worktree isolation policy guidance

- Clarify that same-worktree workers remain orchestration children
  despite appearing as peers in the sidebar
- Define new-worktree creation as required only for explicit requests
  or concrete filesystem/checkout conflicts, not convenience
- Distinguish stacked worktrees from independent ones via --no-parent
- Rename agent-first guidance to reflect conditional requirement

* Release orchestration skill v25 with tightened worktree policy
---
 .../orchestration-skill-guidance.test.mjs     | 21 +++++++++----------
 resources/skills/current-manifest.json        | 14 ++++++-------
 resources/skills/snapshot-registry.json       | 16 ++++++++++++++
 skill-guides/orchestration.md                 | 11 +++++-----
 skills/orchestration/SKILL.md                 | 11 +++++-----
 src/cli/bundled-skill-guides.ts               |  2 +-
 6 files changed, 46 insertions(+), 29 deletions(-)

diff --git a/config/scripts/orchestration-skill-guidance.test.mjs b/config/scripts/orchestration-skill-guidance.test.mjs
index 16747b1ad3d..21324f11672 100644
--- a/config/scripts/orchestration-skill-guidance.test.mjs
+++ b/config/scripts/orchestration-skill-guidance.test.mjs
@@ -144,23 +144,22 @@ describe('orchestration skill guidance', () => {
       'Sidebar lineage and orchestration lifecycle are related but not identical.'
     )
     expect(workerTerminals).toContain(
-      'A same-worktree worker created with `orca terminal create --worktree active` may appear as a peer terminal/agent'
+      'A same-worktree worker may appear as a peer under that worktree in the sidebar'
+    )
+    expect(workerTerminals).toContain('while remaining a child dispatch in orchestration state')
+    expect(workerTerminals).toContain(
+      'only an actual child worktree creates visible parent/child worktree lineage'
     )
     expect(workerTerminals).toContain(
-      'even though it is a child dispatch in Orca orchestration state'
+      'Create a new worktree only when the user explicitly requests one or a concrete checkout or filesystem conflict makes sharing unsafe or impossible'
     )
     expect(workerTerminals).toContain(
-      'A visible parent/child worktree relationship requires creating a child worktree'
+      'Independent tasks, parallel execution, convenience, or a preference for separate checkouts are not isolation requirements.'
     )
     expect(workerTerminals).toContain(
-      'only when the task can safely run from an isolated checkout and does not need uncommitted artifacts from the current working tree'
-    )
-    expect(workerTerminals).toContain(
-      'For supervised new-worktree workers, decide the desired Orca lineage before creation'
-    )
-    expect(workerTerminals).toContain(
-      'use `--no-parent` for independent repo-wide fixes, standalone feature work, or unrelated follow-up tasks'
+      'When a new worktree is allowed, use child lineage for isolated work that is stacked under or dependent on the active worktree'
     )
+    expect(workerTerminals).toContain('use `--no-parent` when it is not stacked')
   })
 
   it('keeps review-only completions and named next-owner fixes in their lanes', () => {
@@ -213,7 +212,7 @@ describe('orchestration skill guidance', () => {
       /```bash\norca worktree create --name <task-name> --agent codex --json\n[\s\S]*?```/
     )?.[0]
 
-    expect(workerTerminals).toContain('Agent-first (required for ordinary agent workers)')
+    expect(workerTerminals).toContain('For an allowed new worktree, use agent-first:')
     expect(workerTerminals).toContain('fallback shell + agent pair')
     expect(workerTerminals).toContain(
       'Repo setup or default-terminal settings may still add tabs or splits'
diff --git a/resources/skills/current-manifest.json b/resources/skills/current-manifest.json
index b0053b7b118..1b489f39c0f 100644
--- a/resources/skills/current-manifest.json
+++ b/resources/skills/current-manifest.json
@@ -130,18 +130,18 @@
     {
       "name": "orchestration",
       "sourcePath": "skills/orchestration",
-      "releaseRevision": 24,
-      "packageDigest": "9fbfa2ae3f3f99441563a4b8b1c6302107944480db8718ddb326a862a51f7ab9",
-      "gitTreeSha": "086c41e0b353b4908d2963694b4a7c791d4b3982",
+      "releaseRevision": 25,
+      "packageDigest": "c19171d213e827bdf5364b733b67889566aaa2fb3667ebe029db87044d08f908",
+      "gitTreeSha": "da346803bccae7fb1fdade31bbe9b4d851b25e38",
       "files": [
         {
           "path": "SKILL.md",
-          "size": 22861,
+          "size": 22676,
           "executable": false,
           "classification": "text",
-          "exactSha256": "0cb898d37560ab7ac4cb477a2d7e8ba3e593d45affd6d7e9f99151879aaeb1a5",
-          "textNormalizedSha256": "0cb898d37560ab7ac4cb477a2d7e8ba3e593d45affd6d7e9f99151879aaeb1a5",
-          "identitySha256": "0cb898d37560ab7ac4cb477a2d7e8ba3e593d45affd6d7e9f99151879aaeb1a5"
+          "exactSha256": "0cfb6a082625edc0d474bae430eb22c28bbe484e54fbfebedb4ff89d96e36305",
+          "textNormalizedSha256": "0cfb6a082625edc0d474bae430eb22c28bbe484e54fbfebedb4ff89d96e36305",
+          "identitySha256": "0cfb6a082625edc0d474bae430eb22c28bbe484e54fbfebedb4ff89d96e36305"
         }
       ]
     }
diff --git a/resources/skills/snapshot-registry.json b/resources/skills/snapshot-registry.json
index 58d6c7f6c0e..f522706ff6c 100644
--- a/resources/skills/snapshot-registry.json
+++ b/resources/skills/snapshot-registry.json
@@ -899,6 +899,22 @@
             "identitySha256": "0cb898d37560ab7ac4cb477a2d7e8ba3e593d45affd6d7e9f99151879aaeb1a5"
           }
         ]
+      },
+      {
+        "releaseRevision": 25,
+        "packageDigest": "c19171d213e827bdf5364b733b67889566aaa2fb3667ebe029db87044d08f908",
+        "gitTreeSha": "da346803bccae7fb1fdade31bbe9b4d851b25e38",
+        "files": [
+          {
+            "path": "SKILL.md",
+            "size": 22676,
+            "executable": false,
+            "classification": "text",
+            "exactSha256": "0cfb6a082625edc0d474bae430eb22c28bbe484e54fbfebedb4ff89d96e36305",
+            "textNormalizedSha256": "0cfb6a082625edc0d474bae430eb22c28bbe484e54fbfebedb4ff89d96e36305",
+            "identitySha256": "0cfb6a082625edc0d474bae430eb22c28bbe484e54fbfebedb4ff89d96e36305"
+          }
+        ]
       }
     ],
     "mobile-fit-debug": [
diff --git a/skill-guides/orchestration.md b/skill-guides/orchestration.md
index 583fc2ad661..c7d15250e00 100644
--- a/skill-guides/orchestration.md
+++ b/skill-guides/orchestration.md
@@ -183,7 +183,7 @@ Wait only for `tui-idle` when needed to avoid losing the prompt. Do not monitor
 
 ## Worker Terminals
 
-Choose the worker location before creating a terminal. `Fresh worker` means a fresh agent session, not a new git worktree. If the task says current worktree only, depends on uncommitted files/artifacts, or must validate/PR the current branch, create the worker in the active worktree:
+Choose the worker location before creating a terminal. `Fresh worker` means a fresh agent session, not a new git worktree. For parallel work, create one fresh agent terminal per worker in the same required worktree, falling back to the active worktree when none is named. If the task says current worktree only, depends on uncommitted files/artifacts, or must validate/PR the current branch, keep every worker in the active worktree:
 
 ```bash
 orca terminal create --worktree active --title <task-name> --command "codex" --json
@@ -191,7 +191,9 @@ orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
 orca orchestration dispatch --task <task_id> --to <handle> --inject --json
 ```
 
-Reuse an idle agent in the required worktree only if the prompt allows reuse; otherwise create a fresh terminal there. Use a new worktree only when explicitly requested or when independent isolated checkout state is intended. For supervised new-worktree workers, decide the desired Orca lineage before creation: use child lineage only when the work is conceptually stacked under or dependent on the active worktree, and use `--no-parent` for independent repo-wide fixes, standalone feature work, or unrelated follow-up tasks. Decide the Git base separately from lineage: `--no-parent` makes the worktree top-level in Orca, while omitted `--base-branch` uses the repo default base.
+Reuse an idle agent in the required worktree only if the prompt allows reuse; otherwise create a fresh terminal there. Create a new worktree only when the user explicitly requests one or a concrete checkout or filesystem conflict makes sharing unsafe or impossible; if the user did not request it, state that conflict before running `worktree create`. Independent tasks, parallel execution, convenience, or a preference for separate checkouts are not isolation requirements.
+
+When a new worktree is allowed, use child lineage for isolated work that is stacked under or dependent on the active worktree, and use `--no-parent` when it is not stacked. Decide the Git base separately: `--no-parent` makes the worktree top-level in Orca, while omitted `--base-branch` uses the repo default base.
 
 ```bash
 orca worktree create --name <task-name> --agent codex --json
@@ -203,11 +205,11 @@ orca orchestration dispatch --task <task_id> --to <handle> --inject --json
 
 For new-worktree workers, read the id and `startupTerminal.handle` from `worktree create`. Use that as the sole worker handle when present; otherwise use `terminal list` to resolve the agent handle. Omit `--repo` only inside an Orca-managed worktree; otherwise pass `--repo <selector>`.
 
-**Agent-first (required for ordinary agent workers):** `--agent` reveals the new worktree and launches the selected agent **in its first terminal**, without adding a separate fallback shell for that worker. Repo setup or default-terminal settings may still add tabs or splits. Do **not** run bare `worktree create` and then `terminal create --command <agent>` for the same worker when agent-first create is available: without configured default tabs, that two-step path leaves a fallback shell + agent pair. Only use it when custom agent argv is required (for example Codex model/effort flags) or when an older CLI rejects `--agent`; if you must, message only the agent handle. Configured default tabs are intentional surfaces, so close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell. Do not run `worktree create` when the task must stay in the current worktree.
+**For an allowed new worktree, use agent-first:** `--agent` reveals the new worktree and launches the selected agent **in its first terminal**, without adding a separate fallback shell for that worker. Repo setup or default-terminal settings may still add tabs or splits. Do **not** run bare `worktree create` and then `terminal create --command <agent>` for the same worker when agent-first create is available: without configured default tabs, that two-step path leaves a fallback shell + agent pair. Only use it when custom agent argv is required (for example Codex model/effort flags) or when an older CLI rejects `--agent`; if you must, message only the agent handle. Configured default tabs are intentional surfaces, so close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell. Do not run `worktree create` when the task must stay in the current worktree.
 
 Use `orca worktree create --prompt ...` or `orca terminal send ...` for full handoffs or untracked/lightweight prompts. Those paths do not attach `taskId`/`dispatchId`; the worker should not send lifecycle messages unless the prompt supplies a live orchestration preamble.
 
-Sidebar lineage and orchestration lifecycle are related but not identical. A same-worktree worker created with `orca terminal create --worktree active` may appear as a peer terminal/agent under the same worktree in the sidebar even though it is a child dispatch in Orca orchestration state. A visible parent/child worktree relationship requires creating a child worktree, but do that only when the task can safely run from an isolated checkout and does not need uncommitted artifacts from the current working tree.
+Sidebar lineage and orchestration lifecycle are related but not identical. A same-worktree worker may appear as a peer under that worktree in the sidebar while remaining a child dispatch in orchestration state; only an actual child worktree creates visible parent/child worktree lineage.
 
 Other terminal commands coordinators often need:
 
@@ -234,7 +236,6 @@ Wait for `tui-idle` before dispatching. Always pass `--timeout-ms`; real coding
 - If blocked before completion, use `ask`; use `escalation` only when ownership is valid and the coordinator must intervene.
 - Treat preambles inherited through terminal history or full handoffs as stale unless the current prompt explicitly keeps that coordinator in the loop.
 - Coordinators should use `task-list --ready` as external memory, dispatch parallel waves, and avoid dependency chains deeper than 3-4 steps.
-- Prefer inter-worktree workers only for independent work that does not need current uncommitted state. When same-worktree work is required, create fresh terminals in that worktree and keep edit ownership clear.
 
 ## Example
 
diff --git a/skills/orchestration/SKILL.md b/skills/orchestration/SKILL.md
index 583fc2ad661..c7d15250e00 100644
--- a/skills/orchestration/SKILL.md
+++ b/skills/orchestration/SKILL.md
@@ -183,7 +183,7 @@ Wait only for `tui-idle` when needed to avoid losing the prompt. Do not monitor
 
 ## Worker Terminals
 
-Choose the worker location before creating a terminal. `Fresh worker` means a fresh agent session, not a new git worktree. If the task says current worktree only, depends on uncommitted files/artifacts, or must validate/PR the current branch, create the worker in the active worktree:
+Choose the worker location before creating a terminal. `Fresh worker` means a fresh agent session, not a new git worktree. For parallel work, create one fresh agent terminal per worker in the same required worktree, falling back to the active worktree when none is named. If the task says current worktree only, depends on uncommitted files/artifacts, or must validate/PR the current branch, keep every worker in the active worktree:
 
 ```bash
 orca terminal create --worktree active --title <task-name> --command "codex" --json
@@ -191,7 +191,9 @@ orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
 orca orchestration dispatch --task <task_id> --to <handle> --inject --json
 ```
 
-Reuse an idle agent in the required worktree only if the prompt allows reuse; otherwise create a fresh terminal there. Use a new worktree only when explicitly requested or when independent isolated checkout state is intended. For supervised new-worktree workers, decide the desired Orca lineage before creation: use child lineage only when the work is conceptually stacked under or dependent on the active worktree, and use `--no-parent` for independent repo-wide fixes, standalone feature work, or unrelated follow-up tasks. Decide the Git base separately from lineage: `--no-parent` makes the worktree top-level in Orca, while omitted `--base-branch` uses the repo default base.
+Reuse an idle agent in the required worktree only if the prompt allows reuse; otherwise create a fresh terminal there. Create a new worktree only when the user explicitly requests one or a concrete checkout or filesystem conflict makes sharing unsafe or impossible; if the user did not request it, state that conflict before running `worktree create`. Independent tasks, parallel execution, convenience, or a preference for separate checkouts are not isolation requirements.
+
+When a new worktree is allowed, use child lineage for isolated work that is stacked under or dependent on the active worktree, and use `--no-parent` when it is not stacked. Decide the Git base separately: `--no-parent` makes the worktree top-level in Orca, while omitted `--base-branch` uses the repo default base.
 
 ```bash
 orca worktree create --name <task-name> --agent codex --json
@@ -203,11 +205,11 @@ orca orchestration dispatch --task <task_id> --to <handle> --inject --json
 
 For new-worktree workers, read the id and `startupTerminal.handle` from `worktree create`. Use that as the sole worker handle when present; otherwise use `terminal list` to resolve the agent handle. Omit `--repo` only inside an Orca-managed worktree; otherwise pass `--repo <selector>`.
 
-**Agent-first (required for ordinary agent workers):** `--agent` reveals the new worktree and launches the selected agent **in its first terminal**, without adding a separate fallback shell for that worker. Repo setup or default-terminal settings may still add tabs or splits. Do **not** run bare `worktree create` and then `terminal create --command <agent>` for the same worker when agent-first create is available: without configured default tabs, that two-step path leaves a fallback shell + agent pair. Only use it when custom agent argv is required (for example Codex model/effort flags) or when an older CLI rejects `--agent`; if you must, message only the agent handle. Configured default tabs are intentional surfaces, so close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell. Do not run `worktree create` when the task must stay in the current worktree.
+**For an allowed new worktree, use agent-first:** `--agent` reveals the new worktree and launches the selected agent **in its first terminal**, without adding a separate fallback shell for that worker. Repo setup or default-terminal settings may still add tabs or splits. Do **not** run bare `worktree create` and then `terminal create --command <agent>` for the same worker when agent-first create is available: without configured default tabs, that two-step path leaves a fallback shell + agent pair. Only use it when custom agent argv is required (for example Codex model/effort flags) or when an older CLI rejects `--agent`; if you must, message only the agent handle. Configured default tabs are intentional surfaces, so close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell. Do not run `worktree create` when the task must stay in the current worktree.
 
 Use `orca worktree create --prompt ...` or `orca terminal send ...` for full handoffs or untracked/lightweight prompts. Those paths do not attach `taskId`/`dispatchId`; the worker should not send lifecycle messages unless the prompt supplies a live orchestration preamble.
 
-Sidebar lineage and orchestration lifecycle are related but not identical. A same-worktree worker created with `orca terminal create --worktree active` may appear as a peer terminal/agent under the same worktree in the sidebar even though it is a child dispatch in Orca orchestration state. A visible parent/child worktree relationship requires creating a child worktree, but do that only when the task can safely run from an isolated checkout and does not need uncommitted artifacts from the current working tree.
+Sidebar lineage and orchestration lifecycle are related but not identical. A same-worktree worker may appear as a peer under that worktree in the sidebar while remaining a child dispatch in orchestration state; only an actual child worktree creates visible parent/child worktree lineage.
 
 Other terminal commands coordinators often need:
 
@@ -234,7 +236,6 @@ Wait for `tui-idle` before dispatching. Always pass `--timeout-ms`; real coding
 - If blocked before completion, use `ask`; use `escalation` only when ownership is valid and the coordinator must intervene.
 - Treat preambles inherited through terminal history or full handoffs as stale unless the current prompt explicitly keeps that coordinator in the loop.
 - Coordinators should use `task-list --ready` as external memory, dispatch parallel waves, and avoid dependency chains deeper than 3-4 steps.
-- Prefer inter-worktree workers only for independent work that does not need current uncommitted state. When same-worktree work is required, create fresh terminals in that worktree and keep edit ownership clear.
 
 ## Example
 
diff --git a/src/cli/bundled-skill-guides.ts b/src/cli/bundled-skill-guides.ts
index 8f9a747993a..ed49d565cd4 100644
--- a/src/cli/bundled-skill-guides.ts
+++ b/src/cli/bundled-skill-guides.ts
@@ -30,7 +30,7 @@ const ORCA_LINEAR_MARKDOWN = "---\nname: orca-linear\ndescription: >-\n  Use Orc
 const ORCA_PER_WORKSPACE_ENV_MARKDOWN = "---\nname: orca-per-workspace-env\ndescription: >-\n  Set up, review, debug, or validate Orca per-workspace environment recipes —\n  on-demand, disposable runtimes (cloud sandboxes, VMs, or local) created fresh\n  for each workspace. Covers first-time setup (provider prerequisites, the\n  reusable base snapshot, the coding-agent auth snapshot, credentials, and\n  state), not just the per-workspace lifecycle scripts. Use to stand up\n  per-workspace environments, fix an `environmentRecipes` entry in `orca.yaml`, scaffold\n  provider lifecycle scripts, or resolve an `orca vm recipe doctor` failure.\n---\n\n# Per-Workspace Environments\n\nHelp a user stand up and maintain a repo-owned per-workspace environment recipe end to end. Each\nworkspace gets its own on-demand, disposable runtime (a cloud sandbox, a VM, or a local one),\ncreated fresh and torn down after.\n\nOrca is a **thin wrapper**: you guide, detect, and scaffold; you never own the user's cloud account,\nbilling, images, or credentials.\n\n- **You DO:** sequence the setup, detect what's detectable (provider CLI present/logged-in? recipe\n  present? `doctor` passing?), scaffold provider-templated scripts the user fills in, drive the slow\n  snapshot/auth phases with the user, and always show the next action.\n- **You DO NOT:** create accounts, choose plans/regions, invent org/project/scope ids, store or print\n  secrets, or run anything that spends money without an explicit user OK.\n\nFirst-time setup has **four phases before the per-workspace recipe runs** — easy to miss, so walk\nthem in order:\n\n1. **Prerequisites** — cloud account, provider CLI, scope/project, plan limits, git token (§2).\n2. **Base snapshot** — reusable image: tools + repo + headless build, snapshotted once (§3).\n3. **Agent-auth snapshot** — boot the base, run interactive device-auth, re-snapshot (§4).\n4. **State** — thread snapshot id / scope / project / port between phases via a state file (§6).\n\nThen the **per-workspace contract** (create/suspend/resume/destroy) runs fast (§8).\n\n**The one branch that shapes everything — connection mode:** **Orca-server** (`create` runs `orca serve`\nin the env and emits a `pairingCode`; §7c/§7f) vs **SSH** (`create` runs no server and emits a\n`connection.type:\"ssh\"` block Orca dials into; §7g/§7h). Settle this first — it changes the `create`\noutput shape and half the templates.\n\n**Quick-start (happy path):** interview the user (connection mode Orca-server vs SSH, provider, agent CLI,\ngit auth — §1.2) + read the provider's CLI docs → scaffold `scripts/orca-vm/` from §7 → run the\nbase-snapshot script, then the auth script (you invoke these by hand; not via `orca.yaml`) → wire\n`environmentRecipes` in `orca.yaml` → `orca vm recipe doctor <id> --json` (free) → then the `--provision`\nself-test loop (§9) until it passes.\n\n---\n\n## 1. Setup workflow\n\nDrive these with the user. **[CHECKPOINT]** steps need explicit confirmation — they spend money, take\na long time, or need the user at the keyboard. Never create an Orca workspace or commit unless asked.\n\n1. **Inspect the repo** for an existing `environmentRecipes` entry, `scripts/orca-vm/`, a state file, or setup\n   notes. If a working recipe exists, jump to Doctor (§9) instead of rebuilding.\n2. **Interview the user up front** — gather these choices and confirm them back before scaffolding\n   anything. Don't pick for them (§11); don't guess.\n   - **Connection mode:** how Orca attaches to the environment — an **Orca server** (the VM runs\n     `orca serve` and Orca pairs over its pairing URL; worked example §7f) or **SSH** (Orca connects to\n     the host over SSH; §7g). This decides the recipe's connection shape, so settle it first.\n   - **Provider:** Vercel Sandbox, Fly, Modal, an existing SSH host, … For non-obvious providers, also\n     ask scope/project/region and plan limits (§2). Then **read that provider's CLI/SDK docs** (or\n     `<cli> --help`) before scaffolding — you need its exact create/exec/snapshot/remove verbs.\n     If a provider advertises `ssh`, verify whether it exposes a real dialable SSH target\n     (host/port/user/key or proxy command) or only a provider-mediated interactive shell; Orca SSH mode\n     needs the former.\n   - **Coding-agent CLI + account:** which agent runs in the VM (`codex`, `claude`, …) and that the user\n     has an account for it — it gets logged in during the Phase-3 auth snapshot (§4).\n   - **Git auth:** the token source for cloning a private repo (`GH_TOKEN`/`GITHUB_TOKEN` or `gh auth\n     token`; §5).\n3. **Check prerequisites (§2)** — detect the provider CLI + auth and confirm the items above are in\n   place before any paid step.\n4. **Scaffold scripts + state file** from §7 (worked Vercel example: §7f; SSH host: §7g; Docker SSH:\n   §7h; Windows: §7i), filling in the provider's real commands. Make them executable.\n5. **[CHECKPOINT] Build the base snapshot (§3)** — paid, slow.\n6. **[CHECKPOINT] Authenticate the agent (§4)** — interactive; the user follows a URL/code. **You cannot\n   drive this step** — you run commands non-interactively, so there's no TTY for `docker exec -it` /\n   `ssh -t` to prompt against. The **user** runs the Phase-3 login in their own terminal (or via the\n   Claude Code harness bang-prefix — `! <cmd>`, with the required space after `!`); you scaffold and drive\n   the non-interactive phases around it. After kicking it off, **ask the user to report back once the login\n   finishes** — you can't observe it completing, and you need that confirmation before resuming the\n   non-interactive steps (base/auth commit, doctor, provision).\n7. **Wire the recipe** so `orca.yaml` points create/suspend/resume/destroy at the scripts (§8). The\n   workspace composer reads `environmentRecipes` from the project's primary checkout of `orca.yaml`, **not** from\n   a feature branch or worktree. So a recipe added only on a branch won't appear as a \"Run on\" option\n   until that `orca.yaml` change is committed and merged to the project's primary branch. Tell the user\n   this up front: `doctor`/`--provision` validate the scripts from the working copy on any branch, but\n   creating a workspace from the recipe in the picker needs it on primary.\n8. **Dry-run doctor** — `orca vm recipe doctor <recipe-id> --repo-path <repo> --json` (free, static; §9).\n   Fix every failure before going live.\n9. **[CHECKPOINT] Live self-test** — get the user's OK once, then run\n   `orca vm recipe doctor <recipe-id> --provision --json` as a loop: it runs create → validates →\n   destroys, and on failure returns a full transcript. Read it, fix the scripts, and re-run yourself until\n   it passes (§9). Spends cloud money; the one approval covers the loop.\n10. **[CHECKPOINT] Optional workspace test** — only if asked: create a workspace via the picker, then\n    verify sleep/wake/delete.\n\n---\n\n## 2. Phase 1 — Prerequisites\n\nThe user's responsibility; verify what's verifiable, ask for the rest, invent nothing. State which\nitems you verified vs. which the user asserted.\n\n- **Connection mode** (Orca server vs SSH) confirmed with the user — see §1 step 2; it shapes the recipe.\n- **Cloud account + plan** that allows sandboxes/VMs. Ask.\n- **Provider CLI installed + authenticated** — detect (`command -v <cli>`), check auth (e.g.\n  `vercel whoami`). If missing, point at the provider's docs; don't log them in.\n- **Scope / project / region** the sandboxes live under. Ask; flows into every script via state.\n- **Plan / timeout / RAM caps.** Record them — e.g. Vercel Hobby caps sandbox timeout at **45m**,\n  which limits both the base build and per-workspace runtime (see §10).\n- **Git token for private repos** (`GH_TOKEN`/`GITHUB_TOKEN`, or the provider's git auth; can fall back\n  to `gh auth token`). See §5.\n- **Coding-agent CLI choice** (`codex`, `claude`…) and that the user has an account — it gets\n  authenticated into the VM in Phase 3.\n\n---\n\n## 3. Phase 2 — Base snapshot (the reusable image)\n\nBuild **once**, snapshot, and every workspace boots from it in seconds instead of rebuilding.\nProvisioning + building takes a while (often ~20–30 min), so it runs behind a checkpoint. The script\nshape is §7a; key points:\n\n- Build the **headless Electron main only** (not the renderer) so it fits in plan RAM.\n- Use the VM image's package manager (`apt`/`dnf`/`apk`, per the base distro — not the provider brand).\n- Clone with the git token via `GIT_ASKPASS` (§5).\n- **Trap errors and remove the half-built sandbox** so a crash doesn't leave a paid resource running.\n- Snapshot the stopped sandbox, parse the snapshot id, and write it + scope/project/port/repo to state.\n\n---\n\n## 4. Phase 3 — Agent-auth snapshot (interactive)\n\nThe base snapshot has the agent CLI installed but **not logged in**, and per-workspace VMs are\nephemeral — so authenticate once and bake it into a second snapshot layer. Script shape is §7b:\n\n1. Boot a sandbox from the base `snapshotId` (from state).\n2. Run the agent's login **interactively** (`--interactive --tty`); the user completes the URL/code in\n   their browser. On a **headless VM this must be the device-auth flow** (e.g. `codex login --device-auth`),\n   **not** plain `codex login`: the default OAuth login starts a loopback callback server on a container\n   port the host browser can't reach, so it hangs. Device-auth instead prints a URL + code the user opens\n   on the **host**.\n3. Verify login; **refuse to snapshot an unauthenticated VM.** Prefer the status command's **exit code**\n   (most agent CLIs exit non-zero when unauthenticated). If you grep instead, agent status often goes to\n   **stderr** (e.g. `codex login status` prints \"Logged in using ChatGPT\" there), so **fold stderr first**\n   (`... 2>&1 | grep …`) and match the agent's **exact success line** — never `grep -qi 'logged in'`, which\n   also matches \"**not** logged in\" and would commit an unauthenticated image.\n4. Re-snapshot, parse the new id, and overwrite `snapshotId` in state to the authenticated image\n   (recording `authSourceSnapshotId`). Remove the auth sandbox.\n\n**You can't drive step 2 yourself** (you run commands non-interactively — no TTY). The **user** runs it in\ntheir own terminal, or via the Claude Code harness bang-prefix (`! <cmd>`, with the required space after\n`!`). You scaffold/boot the sandbox and run steps 3–4, but **you cannot observe the interactive login\nfinishing** — so **ask the user to tell you when it's done** before you verify and re-snapshot.\n\nIf the agent's credentials are short-lived, warn that the snapshot may need periodic re-auth (§10).\n\nFor disposable runtimes, do **not** treat a host agent config directory (for example `~/.codex`) as the\nauth snapshot by bind-mounting or copying it wholesale. Agent homes often contain sqlite state, hook\napproval state, caches, logs, and host-specific env/config. Instead, authenticate/configure the agent\ninside the disposable runtime and snapshot/commit that runtime layer.\n\n---\n\n## 5. Credentials\n\n- **Never** commit secrets or put them in `userData`, recipe JSON, comments, docs, or the state file.\n- **Git token:** read from env (`GH_TOKEN`/`GITHUB_TOKEN`), falling back to `gh auth token`. Pass to the\n  VM only via the provider's ephemeral `--env`. Inside the VM, use a `GIT_ASKPASS` helper with\n  `x-access-token` (not the token in the clone URL) and `GIT_TERMINAL_PROMPT=0` so a missing token fails\n  fast instead of hanging. When you write the helper from inside `bash -lc` under `set -u`, escape the\n  positional arg and the token (`\\$1`, `\\$GH_TOKEN`) so they land **literally** and resolve at git-runtime\n  — an unescaped `$1` aborts with \"unbound variable\", and a literal `$GH_TOKEN` keeps the real token out of\n  the written file. `rm -f` the helper after the clone/fetch.\n- **Provider auth:** rely on the provider CLI's logged-in session, not checked-in keys.\n- **Agent auth:** lives in the authenticated snapshot (Phase 3) — never a file you write or commit.\n- State holds only **non-secret** wiring (snapshot ids, scope, project, port, repo url/ref).\n\n---\n\n## 6. State file\n\nA repo-local JSON file (e.g. `scripts/orca-vm/<provider>-state.json`) threads non-secret values between\nphases. Each script resolves values as **env var → state → built-in fallback**, and merges its outputs\nback. Phase 2 writes the base `snapshotId`; Phase 3 overwrites it with the authenticated snapshot;\nper-workspace `create` boots from `snapshotId`.\n\n```json\n{\n  \"baseName\": \"orca-base\",\n  \"snapshotId\": \"snap_authenticated_image_id\",\n  \"authSourceSnapshotId\": \"snap_base_image_id\",\n  \"scope\": \"<provider-scope>\",\n  \"project\": \"<provider-project>\",\n  \"port\": 7331,\n  \"repoUrl\": \"https://host/org/repo.git\",\n  \"repoRef\": \"main\",\n  \"projectRoot\": \"/abs/path/on/remote/repo\"\n}\n```\n\n---\n\n## 7. Script templates (provider-agnostic shapes)\n\nScaffold under `scripts/orca-vm/`. These are **shapes** — fill in the provider's real commands. All\nreserve stdout for the final JSON and log progress to stderr. Include a shared `json_value <key>` /\n`env_value <NAME>` reader (env → state → fallback) in each.\n\n**Where each script runs:**\n\n- **Local-side** (`create`/`suspend`/`resume`/`destroy` + the base-snapshot/auth scripts the user\n  invokes) runs **on the user's desktop**, so it must run on their OS. macOS/Linux: `#!/usr/bin/env\n  bash`, `set -euo pipefail`, quoted paths. **Windows:** a bare `.sh` won't run — scaffold `.ps1`/`.cmd`\n  or require WSL/Git-Bash and point `orca.yaml` at the right launcher.\n- **Remote-side** (commands you `exec` *inside* the Linux VM) always runs in the VM's Linux shell, so\n  bash is fine there regardless of the user's OS.\n\n### 7a. Base-snapshot (`<provider>-base-snapshot.sh`) — Phase 2\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve base_name/repo_url/repo_ref/project_root/port/scope/project/timeout (env→state→fallback)\n# resolve gh token: GH_TOKEN | GITHUB_TOKEN | `gh auth token`\n# 1. provision a sandbox (timeout/vcpus/published port/snapshot retention); trap: remove on error\n# 2. remote exec (long timeout): install pkgs + gh + corepack/pnpm + agent CLI;\n#    clone with GIT_ASKPASS(token); write headless main-only build config;\n#    dev setup; pnpm install; build CLI; build headless electron main; smoke-check tools\n# 3. snapshot stopped sandbox; parse snapshot id (fail if unparseable)\n# 4. merge { baseName, snapshotId, projectRoot, repoUrl, repoRef, port, scope, project } into state\n# print only the state JSON to stdout\n```\n\nWorked Vercel commands for this phase are in §7f. You run this script by hand (not via `orca.yaml`),\nafter exporting the first-run inputs the state file doesn't have yet — e.g. provider scope/project, the\nrepo URL/ref, and a git token (`GH_TOKEN`); later runs read them back from state.\n\n### 7b. Auth (`<provider>-base-auth.sh`) — Phase 3\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# read source snapshot from state.snapshotId (fail if absent); auth_name=\"${base_name}-auth\"\n# 1. boot sandbox from source snapshot; trap: remove on error\n# 2. INTERACTIVE/TTY remote exec: agent login — user completes URL/code. Headless VM: MUST use the\n#    device-auth flow (e.g. `codex login --device-auth`) — plain OAuth login binds a loopback callback\n#    port the host can't reach and hangs. User runs this themselves (you have no interactive TTY); ask\n#    them to report back when it's done before continuing.\n# 3. verify login, then refuse to snapshot if not logged in. Prefer the status command's EXIT CODE (most\n#    agent CLIs exit non-zero when unauthenticated) over string-matching. If you must grep, fold stderr\n#    first (`status 2>&1 | grep …` — many agents print the success line there) and match the agent's exact\n#    success line; never `grep -qi 'logged in'`, which also matches \"not logged in\". Codex example: §7f.\n# 4. snapshot; parse new id\n# 5. merge { snapshotId:<new>, authSourceSnapshotId:<source> } into state; remove auth sandbox\n# print only the state JSON to stdout\n```\n\n### 7c. Create (`<provider>-create.sh`) — per workspace\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# read authenticated snapshotId/scope/project/port/repo*/project_root (env→state→fallback)\n# fail clearly if snapshotId is missing (point back to Phases 2–3)\n# name = orca-${ORCA_VM_RECIPE_ID}-${ORCA_VM_INSTANCE_ID} (sanitized, length-capped)\n# 1. boot sandbox from snapshotId with a published port; capture the public URL → pairing address\n#    (an externally reachable wss:// URL); trap: remove sandbox on error\n# 2. remote exec: ensure repo at desired commit; rebuild only if commit changed (cache marker)\n# 3. remote exec: start orca serve in the background and read the recipe JSON it writes (see below)\n# 4. print serve's JSON to stdout, optionally enriched with userData:\n#    { schemaVersion:1, pairingCode, projectRoot, userData:{ provider, resourceId:name, snapshotId } }\n```\n\n**The exact `orca serve` invocation and its output (verified — do not improvise the flags).** Inside the\nVM, run:\n\n```bash\norca serve \\\n  --port \"$PORT\" \\\n  --project-root \"$ABS_REPO_PATH_ON_REMOTE\" \\\n  --pairing-address \"$EXTERNAL_WSS_URL\" \\\n  --recipe-json\n```\n\n**Binary name:** in a VM built from source (the Phase-2 flow), run it as `pnpm exec orca-dev serve …`\nfrom the repo root — `orca-dev` is the in-repo entrypoint and is what the §7f example uses. Plain\n`orca serve …` is the same command when the built CLI is installed on the VM's PATH. The flags/output\nare identical either way.\n\nThere is **no `--host` flag**. `--project-root` must be an absolute directory on the remote. With\n`--recipe-json` the server **stays running** and prints exactly this single object to **stdout**, then\nkeeps serving:\n\n```json\n{ \"schemaVersion\": 1, \"pairingCode\": \"<orca pairing URL>\", \"projectRoot\": \"<the --project-root you passed>\" }\n```\n\n`pairingCode` is the pairing URL, already pointing at whatever you passed as `--pairing-address` — so set\n`--pairing-address` to the externally reachable address and **pass `pairingCode` through unchanged; never\nhand-rewrite it**. Because serve runs in the foreground and doesn't exit, redirect its stdout to a file\nand poll until that file parses as JSON (and bail if the process dies — dump its stderr log). Your\n`create` script then prints that JSON (optionally merging `userData`). Concrete pattern: §7f.\n\n### 7d. Suspend / resume / destroy — per workspace\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\npayload=\"$(cat)\"                       # Orca passes lifecycle JSON on stdin\nresource_id=\"$(node -e 'const d=JSON.parse(process.argv[1]); process.stdout.write(d.recipeResult?.userData?.resourceId ?? \"\")' \"$payload\")\"\n[ -n \"$resource_id\" ] || { echo \"No resource id in lifecycle payload\" >&2; exit 1; }\n# suspend: provider suspend \"$resource_id\"\n# resume:  provider resume \"$resource_id\"; then RE-EMIT fresh recipe JSON (pairing may change)\n# destroy: provider remove \"$resource_id\"   (or set destroy: none in orca.yaml)\n```\n\n### 7e. State file — scaffold with scope/project/repo filled in and snapshot ids empty (§6).\n\n### 7f. Worked example — Vercel Sandbox (all three phases)\n\nA real, working shape (the Vercel surface is a CLI: `vercel sandbox create|exec|snapshot|remove`). Adapt\nnames; verify flags against `vercel sandbox --help` for the user's CLI version before relying on them.\nThese ground §7a (base snapshot) and §7b (auth), which are otherwise generic skeletons.\n\n**Phase 2 — base snapshot (§7a):** provision → install tools + clone + headless build → snapshot.\n\n```bash\n# provision a fresh build sandbox (retain a couple of snapshots); trap-remove on error\nvercel sandbox create --name \"$base\" --runtime node24 --timeout 30m --vcpus 4 --publish-port \"$port\" \\\n  --snapshot-expiration 30d --keep-last-snapshots 2 \"${vercel_args[@]}\" >&2\n# remote build (long timeout): install pkgs+gh+pnpm+agent CLI, clone with GIT_ASKPASS (write the helper\n# with LITERAL \\$1/\\$GH_TOKEN so they resolve at git-runtime, not write-time — see §5/§7f create — then\n# `rm -f /tmp/askpass.sh`), write the headless main-only build config (drop the renderer), dev setup,\n# build CLI + headless main, smoke-check\nvercel sandbox exec \"$base\" \"${vercel_args[@]}\" --timeout 25m --env \"GH_TOKEN=$gh_token\" … -- bash -lc '…build…' >&2\n# snapshot the STOPPED sandbox and parse the id from CLI output (fail if unparseable)\nout=\"$(vercel sandbox snapshot \"$base\" --stop --expiration 30d \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$out\" >&2\nsnapshot_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n# merge { baseName, snapshotId, scope, project, port, repoUrl, repoRef, projectRoot } into state; print state JSON\n```\n\n**Phase 3 — agent-auth snapshot (§7b):** boot the base, log the agent in interactively, re-snapshot.\n(`codex` below is an example — substitute the user's chosen agent's login/status verbs, e.g. `claude`.)\n\n```bash\nvercel sandbox create --name \"$auth\" --snapshot \"$snapshot_id\" --timeout 30m --publish-port \"$port\" \"${vercel_args[@]}\" >&2\n# INTERACTIVE — the USER runs this in their own terminal (you have no interactive TTY) and completes the\n# URL/code on the HOST. --device-auth is MANDATORY on a headless VM: plain `codex login` binds a loopback\n# callback port the host browser can't reach and hangs. Ask the user to report back when login finishes.\nvercel sandbox exec --interactive --tty \"$auth\" \"${vercel_args[@]}\" -- bash -lc 'codex login --device-auth'\n# refuse to snapshot an unauthenticated VM — fold stderr, match codex's exact success line (§4)\nvercel sandbox exec \"$auth\" \"${vercel_args[@]}\" --timeout 30s -- bash -lc 'codex login status 2>&1' | grep -Eqi 'Logged in using ChatGPT|Logged in via device' \\\n  || { echo \"agent not logged in; not snapshotting\" >&2; exit 1; }\nout=\"$(vercel sandbox snapshot \"$auth\" --stop --expiration 30d \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$out\" >&2\nnew_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n# overwrite state.snapshotId = new_id, record authSourceSnapshotId = snapshot_id; remove the auth sandbox\n```\n\n**Per-workspace `create`** (the fast path):\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback: snapshot_id, scope, project, port, repo_url, repo_ref, project_root\nvercel_args=(); [ -n \"$scope\" ] && vercel_args+=(--scope \"$scope\"); [ -n \"$project\" ] && vercel_args+=(--project \"$project\")\n[ -n \"$snapshot_id\" ] || { echo \"snapshotId missing — run Phases 2–3 first\" >&2; exit 1; }\ngh_token=\"${GH_TOKEN:-${GITHUB_TOKEN:-$(command -v gh >/dev/null 2>&1 && gh auth token 2>/dev/null || true)}}\"\nname=\"orca-${ORCA_VM_RECIPE_ID:-vercel-sandbox}-${ORCA_VM_INSTANCE_ID:-$(date +%s)}\"  # sanitize+cap to 63 chars\n\n# Arm cleanup BEFORE create so a failing create can't leak a half-built paid sandbox.\ncleanup_on_error() { [ \"$?\" -ne 0 ] && vercel sandbox remove \"$name\" \"${vercel_args[@]}\" >/dev/null 2>&1 || true; }\ntrap cleanup_on_error EXIT\n\n# 1. boot from the authenticated snapshot, publish the serve port\ncreate_output=\"$(vercel sandbox create --name \"$name\" --snapshot \"$snapshot_id\" \\\n  --timeout 30m --publish-port \"$port\" \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$create_output\" >&2\n# Vercel prints the published https URL; derive the external wss:// pairing address from it\npublic_url=\"$(printf '%s\\n' \"$create_output\" | sed -nE 's#.*(https://[^[:space:]]+\\.vercel\\.run).*#\\1#p' | head -1)\"\n[ -n \"$public_url\" ] || { echo \"no published URL in create output\" >&2; exit 1; }\npairing_ws=\"${public_url/https:\\/\\//wss://}\"\n\n# 2. (remote) ensure the repo is at the right commit; rebuild only if the commit changed (cache marker)\nvercel sandbox exec \"$name\" \"${vercel_args[@]}\" --timeout 20m \\\n  --env \"GH_TOKEN=$gh_token\" --env \"ORCA_PROJECT_ROOT=$project_root\" \\\n  --env \"ORCA_REPO_URL=$repo_url\" --env \"ORCA_REPO_REF=$repo_ref\" \\\n  -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; \\\n    # Re-establish git auth for the private-repo fetch (why + full rationale: §5); else it hangs on a prompt.\n    # Load-bearing escaping: \\$1 and \\$GH_TOKEN must land LITERALLY and resolve at git-runtime. Test after\n    # any edit here — reformatting the nested printf/node quoting silently breaks the fetch or leaks the token.\n    if [ -n \"${GH_TOKEN:-}\" ]; then \\\n      printf \"%s\\n\" \"#!/usr/bin/env bash\" \"case \\\"\\$1\\\" in *Username*) echo x-access-token;; *Password*) echo \\\"\\$GH_TOKEN\\\";; esac\" > /tmp/askpass.sh; \\\n      chmod 700 /tmp/askpass.sh; export GIT_ASKPASS=/tmp/askpass.sh GIT_TERMINAL_PROMPT=0; fi; \\\n    git fetch origin \"$ORCA_REPO_REF\"; \\\n    git checkout -B \"$ORCA_REPO_REF\" FETCH_HEAD; \\\n    rm -f /tmp/askpass.sh; \\\n    c=\"$(git rev-parse HEAD)\"; [ -f .orca-built ] && [ \"$(cat .orca-built)\" = \"$c\" ] || { \\\n      pnpm install --prefer-offline && pnpm run build:cli && \\\n      node config/scripts/run-electron-vite-build.mjs --config config/electron-vite.vm-serve.config.ts && \\\n      printf \"%s\" \"$c\" > .orca-built; }' >&2\n\n# 3. (remote) start orca serve in the background, writing recipe JSON to a file; poll until it parses\nrecipe_json=\"$(vercel sandbox exec \"$name\" \"${vercel_args[@]}\" --timeout 60s \\\n  --env \"ORCA_PORT=$port\" --env \"ORCA_PROJECT_ROOT=$project_root\" --env \"ORCA_PAIRING_ADDRESS=$pairing_ws\" \\\n  -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; rm -f /tmp/orca-recipe.json /tmp/orca-serve.log; \\\n    nohup pnpm exec orca-dev serve --port \"$ORCA_PORT\" --project-root \"$ORCA_PROJECT_ROOT\" \\\n      --pairing-address \"$ORCA_PAIRING_ADDRESS\" --recipe-json >/tmp/orca-recipe.json 2>/tmp/orca-serve.log </dev/null & \\\n    pid=$!; for _ in $(seq 1 80); do \\\n      node -e \"JSON.parse(require(\\\"node:fs\\\").readFileSync(\\\"/tmp/orca-recipe.json\\\",\\\"utf8\\\"))\" >/dev/null 2>&1 && { cat /tmp/orca-recipe.json; exit 0; }; \\\n      kill -0 \"$pid\" 2>/dev/null || { cat /tmp/orca-serve.log >&2; exit 1; }; sleep 0.25; \\\n    done; cat /tmp/orca-serve.log >&2; echo \"serve recipe JSON timed out\" >&2; exit 1')\"\n\n# 4. print serve's JSON enriched with userData (single object on stdout)\nnode -e 'const p=JSON.parse(process.argv[1]); console.log(JSON.stringify({...p, schemaVersion:1,\n  userData:{...p.userData, provider:\"vercel-sandbox\", resourceId:process.argv[2], snapshotId:process.argv[3]}}))' \\\n  \"$recipe_json\" \"$name\" \"$snapshot_id\"\ntrap - EXIT\n```\n\n`suspend`/`resume`/`destroy` use `vercel sandbox stop|...|remove \"$resource_id\"` reading\n`userData.resourceId` from stdin (§7d). This is the **Orca-server** connection mode (the recipe emits a\npairing URL). If the user chose **SSH** in the §1 interview, use §7g instead.\n\n### 7g. Worked example — existing SSH host (SSH connection mode)\n\nSSH mode is **fundamentally different from §7c/§7f**, not a relabeling of them:\n\n- **`create` does NOT run `orca serve` and does NOT emit a `pairingCode`.** Orca itself connects to the\n  host over its SSH relay, brings up the git + filesystem providers, and imports the repo. The script's\n  only job is to make the host ready and **print SSH connection details** Orca will dial.\n- The result uses a `connection` block with `type: \"ssh\"` and a `target`, **not** the flat\n  `pairingCode`/`projectRoot` shape. Exact shape (Orca rejects anything else):\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"connection\": {\n    \"type\": \"ssh\",\n    \"projectRoot\": \"/abs/path/to/repo/on/host\",\n    \"target\": {\n      \"label\": \"my-box\",\n      \"host\": \"192.0.2.10\",\n      \"port\": 22,\n      \"username\": \"ubuntu\",\n      \"identityFile\": \"~/.ssh/id_ed25519\",\n      \"jumpHost\": \"bastion.example.com\",\n      \"proxyCommand\": \"cloudflared access ssh --hostname %h\",\n      \"relayGracePeriodSeconds\": 0,\n      \"portForwards\": []\n    }\n  }\n}\n```\n\n`label`, `host`, `port`, `username` are required; the rest are optional — omit any you don't need.\n\n**Networking → which `target` fields to set** (how *your desktop* reaches the box — there is no\n`orca serve` URL in SSH mode):\n\n- Public IP / DNS, or a Tailscale/VPN address → `host`; SSH port → `port` (usually 22).\n- Key auth → `identityFile` (add `identitiesOnly: true` if the agent has many keys).\n- Through a bastion → `jumpHost` (a `user@host` ProxyJump) **or** a full `proxyCommand` (e.g. an access\n  proxy). Use one, not both.\n- A service port the workspace needs → add entries to `portForwards`.\n- `relayGracePeriodSeconds` (optional): how long Orca keeps the SSH relay alive after the workspace\n  detaches before tearing it down; `0` = tear down immediately. Leave it off unless the user wants a\n  reconnect grace window.\n\n**Toolchain & agent auth on a persistent (no-snapshot) host — do this ONCE, by hand, before wiring the\nrecipe** (there's no base image to bake; the host *is* the base). Run the §7f Phase-2 install steps and\nthe §7f Phase-3 `<agent> login --device-auth` **directly over SSH on the host** (interactive, e.g.\n`ssh -t user@host '<agent> login --device-auth'`). After that the host stays ready across workspaces.\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback (default unset optionals to \"\"): ssh_username, host,\n#   ssh_port (default 22), identity_file, jump_host, proxy_command, project_root, repo_url, repo_ref\n: \"${identity_file:=}\"; : \"${jump_host:=}\"; : \"${proxy_command:=}\"   # avoid set -u aborts on optionals\ngh_token=\"${GH_TOKEN:-${GITHUB_TOKEN:-$(command -v gh >/dev/null 2>&1 && gh auth token 2>/dev/null || true)}}\"\nssh_target=\"${ssh_username}@${host}\"\nssh_opts=(-p \"$ssh_port\"); [ -n \"$identity_file\" ] && ssh_opts+=(-i \"$identity_file\")\n# Why: a fresh host's key isn't in known_hosts; a StrictHostKeyChecking prompt would HANG a\n# non-interactive create. Pre-add the key (or set the option) so it can't block.\nssh-keyscan -p \"$ssh_port\" \"$host\" >> \"$HOME/.ssh/known_hosts\" 2>/dev/null || true\n\n# 1. ensure the repo is present and at the right commit on the host (NO orca serve here)\nssh \"${ssh_opts[@]}\" \"$ssh_target\" \\\n  \"GH_TOKEN='$gh_token' GIT_TERMINAL_PROMPT=0 bash -lc '\n     set -euo pipefail\n     [ -d \\\"$project_root/.git\\\" ] || git clone \\\"$repo_url\\\" \\\"$project_root\\\"\n     cd \\\"$project_root\\\" && git fetch origin \\\"$repo_ref\\\" && git checkout -B \\\"$repo_ref\\\" FETCH_HEAD\n   '\" >&2\n\n# 2. print the SSH connection block (NO pairingCode, NO orca serve). host/port/username tell Orca's\n#    relay how to dial in; identityFile/jumpHost/proxyCommand/portForwards are emitted when set.\nnode -e 'const [host,port,user,idf,jh,pc,root]=process.argv.slice(1);\n  const target={ label:\"per-workspace-host\", host, port:Number(port), username:user };\n  if(idf) target.identityFile=idf; if(jh) target.jumpHost=jh; if(pc) target.proxyCommand=pc;\n  // add target.portForwards=[...] here if the workspace needs forwarded service ports\n  console.log(JSON.stringify({ schemaVersion:1, connection:{ type:\"ssh\", projectRoot:root, target } }))' \\\n  \"$host\" \"$ssh_port\" \"$ssh_username\" \"$identity_file\" \"$jump_host\" \"$proxy_command\" \"$project_root\"\n```\n\n`suspend`/`resume`/`destroy`: on a persistent host there's usually nothing to tear down — set\n`destroy: none` and omit suspend/resume. (Orca still disconnects/reconnects its own SSH relay on\nsleep/wake/delete — that's separate from these scripts.)\n\nIf the SSH host is instead an **ephemeral/snapshot-capable VM** (your hypervisor, or a cloud VM with\nimage support), keep the §7f Phase-2/3 base-image model for provisioning, but still emit the\n`connection.type:\"ssh\"` block above instead of starting `orca serve`.\n\n### 7h. Worked example — local Docker SSH (SSH connection mode)\n\nLocal Docker can model an ephemeral SSH VM without cloud cost: build a base image with `sshd`, tools,\nrepo prerequisites, and the agent CLI; run an **interactive auth container** once; then `docker commit`\nthat container as the authenticated image used by per-workspace `create`.\n\nKey points:\n\n- Publish container SSH to a random localhost port (`-p 127.0.0.1::22`) and emit\n  `connection.type:\"ssh\"` with `host:\"127.0.0.1\"`, that port, `username`, `identityFile`, and\n  `identitiesOnly:true`.\n- Generate a repo-local SSH key if needed, but gitignore the private/public key files.\n- **Bake SSH host keys into the base image** (`ssh-keygen -A` at **build** time; at runtime only generate\n  if absent). Ephemeral containers all present the **same** host key, so `known_hosts` on `127.0.0.1`\n  doesn't churn as the published port rotates across workspaces (otherwise every container's freshly\n  generated key collides on `localhost` and trips host-key-changed warnings).\n- The auth image is the Docker equivalent of Phase 3: the **user** runs the agent login **inside** the\n  container (you can't drive it — you have no interactive TTY), configures proxy env/config, approves\n  hooks, and you commit once they report it's done. On a headless container use the **device-auth** flow\n  (§4). Verify login before committing — exit code, or fold stderr and match the exact success line (§4).\n- Do not bind-mount or copy the host's full agent home into the image. Let each container have writable\n  agent state; only the committed auth image should carry reusable authenticated state.\n- If committing from an interactive shell, force the runtime entrypoint back to `sshd`:\n  `docker commit --change='ENTRYPOINT [\"/usr/local/bin/orca-docker-ssh-entrypoint\"]' …`.\n- `destroy` should read `recipeResult.userData.resourceId` and run `docker rm -f \"$resource_id\"`.\n\nValidation before wiring/live use:\n\n```bash\ndocker image inspect \"$auth_image\" --format '{{json .Config.Entrypoint}}'\ndocker run -d --name \"$name\" -p 127.0.0.1::22 -e \"ORCA_SSH_PUBLIC_KEY=$pubkey\" \"$auth_image\"\ndocker ps -a --filter \"name=$name\"\ndocker logs \"$name\"\nssh -i \"$key\" -p \"$port\" -o IdentitiesOnly=yes user@127.0.0.1 'codex --version'\n```\n\nIf the container exits immediately, inspect logs before the cleanup trap removes it; a committed\ninteractive image with `ENTRYPOINT [\"bash\"]` is a common cause.\n\nAlso confirm the **host key is stable** across containers: the SSH `ssh -i … 127.0.0.1` dial should not\ntrigger a host-key-changed warning when a second container reuses the port. If it does, the host keys\nweren't baked into the base image (see the `ssh-keygen -A` point above).\n\n### 7i. Windows local-side scripts\n\nThe local-side scripts run on the user's desktop. On **Windows**, a bare `.sh` won't execute. Either\nrequire WSL/Git-Bash (and point `orca.yaml` at e.g. `bash ./scripts/orca-vm/<name>.sh` via a `.cmd`\nlauncher), or scaffold PowerShell equivalents. Minimal PowerShell shape:\n\n```powershell\n#requires -Version 5\n$ErrorActionPreference = 'Stop'\n# resolve env→state→fallback; run the provider CLI / ssh the same way;\n# capture provider output; build the result object for the chosen mode and write ONE line of JSON to stdout.\n# Orca-server mode: @{ schemaVersion=1; pairingCode=$pairingCode; projectRoot=$projectRoot; userData=@{...} }\n# SSH mode:        @{ schemaVersion=1; connection=@{ type=\"ssh\"; projectRoot=$projectRoot;\n#                     target=@{ label=$label; host=$host; port=$port; username=$user } } }  (see §7g/§7h)\n($result | ConvertTo-Json -Compress -Depth 6)\n# progress/errors → Write-Error / the error stream, never stdout.\n```\n\nThe remote-side commands you run *inside* the Linux VM stay bash regardless of the desktop OS.\n\n---\n\n## 8. Per-workspace recipe contract (the fast path)\n\nOnce the authenticated snapshot exists, this runs on every workspace create. Define recipes in\n`orca.yaml`:\n\n```yaml\nenvironmentRecipes:\n  - id: cloud-sandbox\n    name: Cloud Sandbox\n    create: ./scripts/orca-vm/cloud-sandbox-create.sh\n    suspend: ./scripts/orca-vm/cloud-sandbox-suspend.sh\n    resume: ./scripts/orca-vm/cloud-sandbox-resume.sh\n    destroy: ./scripts/orca-vm/cloud-sandbox-destroy.sh\n```\n\n`create` runs **locally from the repo root** and prints **one** JSON object to stdout. Its shape depends\non the connection mode chosen in §1:\n\n**Orca-server mode** — boot the env, start `orca serve` in it, and print serve's result:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"pairingCode\": \"orca-pairing-code-or-url\",\n  \"projectRoot\": \"/absolute/path/to/repo/on/remote\",\n  \"userData\": { \"provider\": \"example\", \"resourceId\": \"provider-resource-id\" }\n}\n```\n\nHere `pairingCode` (from `orca serve --recipe-json`) and `projectRoot` are required; `schemaVersion` (`1`)\nand `userData` are optional.\n\n**SSH mode** — do **not** run `orca serve`; print the `connection.type:\"ssh\"` block instead (full shape +\nworked script in §7g). `pairingCode` is **not** used in SSH mode.\n\nLifecycle hooks (all run locally):\n\n- `create`: required. Prints recipe result JSON.\n- `suspend`: optional. Sleep; reads lifecycle payload on stdin.\n- `resume`: optional. Wake; reads payload on stdin and **prints fresh recipe JSON** (pairing may change).\n- `destroy`: optional unless `destroy: none`. Delete/cleanup; reads payload on stdin.\n\nStart Orca remotely with `orca serve --port \"$PORT\" --project-root \"$ABS_ROOT\" --pairing-address\n\"$EXTERNAL_WSS_URL\" --recipe-json` (exact flags + output in §7c). Set `--pairing-address` to the\nexternally reachable address so the emitted `pairingCode` is reachable; tunneling/port mapping is the\nscript's job.\n\nBackward compatibility: `command`→`create`, `cleanup`→`destroy`, `cleanup: none`→`destroy: none`.\nPrefer the lifecycle names.\n\n---\n\n## 9. Doctor and validation\n\nValidate in two stages — the cheap dry run first, then the live self-test.\n\n### Dry run (free, non-destructive) — always do this first\n\n`orca vm recipe doctor <recipe-id> --repo-path <repo> --json` validates **static wiring only** — it does\n**not** boot anything. It checks: local-host execution (v1), repo path, recipe id exists,\ncreate/destroy/suspend/resume command paths resolve, suspend/resume are paired, and each script is\nexecutable (POSIX exec bit; skipped on Windows). Fix every failure here before spending any cloud money.\n\n### Live self-test (`--provision`) — diagnose and iterate yourself\n\n`orca vm recipe doctor <recipe-id> --repo-path <repo> --provision --json` actually runs the recipe end\nto end: it executes `create`, validates the returned recipe JSON, then runs `destroy` to **tear the\nenvironment back down** (so the test leaves nothing running, as long as `destroy` works). It spends real\ncloud money, so get the user's OK **once** before starting — that one approval covers the whole loop\nbelow; do not re-ask before each run.\n\nOn failure, the JSON result includes a `provisionTranscript` with the **complete** captured output of\neach stage so you can self-diagnose without asking the user to relay logs:\n\n```json\n{\n  \"ok\": false,\n  \"checks\": [ { \"id\": \"recipe.provision\", \"status\": \"fail\", \"message\": \"…\" } ],\n  \"provisionTranscript\": {\n    \"provision\": { \"exitCode\": 0, \"signal\": null, \"stdout\": \"…\", \"stderr\": \"…\", \"parseError\": \"…\" },\n    \"destroy\":   { \"exitCode\": 0, \"signal\": null, \"stdout\": \"…\", \"stderr\": \"…\" }\n  }\n}\n```\n\n**Run it as a loop:** read `provisionTranscript.provision.stderr` / `.stdout` / `.parseError` (and\n`destroy.*`), fix the script, and re-run `--provision` until `ok` is `true` — iterating on your own\nrather than waiting for the user to paste errors. Common reads: a non-empty `stderr` with `exitCode 0`\nplus a `parseError` means `create` ran but printed something other than the single recipe-result JSON on\nstdout (often a stray `echo` — route it to stderr, see §10); a non-zero `exitCode` is a provider/script\nfailure described in `stderr`. Each stream is redacted and capped (head+tail) — large logs keep both the\nsetup context and the failure.\n\nThe self-test cannot see provider-side truth beyond what the scripts print, so still confirm: state has a\npopulated **authenticated** `snapshotId` (Phases 2–3 done), and `destroy` is implemented/tested (or\nexplicitly `none` — in which case the self-test won't tear down, so clean up manually).\n\nFor SSH recipes, also smoke-test the exact emitted target before declaring success: dial the host/port\nwith the identity/proxy settings, run `pwd`, verify the repo path, check the agent binary, and confirm\n`destroy` removes the provider resource/container. For Docker, inspect the auth image entrypoint and do a\nstartup-only `docker run` before the full clone/install path.\n\n---\n\n## 10. Failure modes\n\n- **Build exceeds plan timeout (e.g. Hobby 45m).** Use enough vCPUs and a timeout covering the build;\n  else split work or use a higher plan. The cap also limits per-workspace runtime — surface it.\n- **Build exceeds plan RAM.** Build the **headless main only** (drop the renderer) — the biggest fitter.\n- **Private-repo clone hangs/fails.** Wrong/missing token. Use `GIT_ASKPASS` + `GIT_TERMINAL_PROMPT=0`\n  so it fails fast instead of prompting.\n- **`GIT_ASKPASS` helper aborts the clone with \"`$1: unbound variable`\".** The `printf`/heredoc that writes\n  the helper inside `bash -lc` under `set -u` expanded `$1`/`$GH_TOKEN` at **write** time. Escape them\n  (`\\$1`, `\\$GH_TOKEN`) so they land literally and resolve at git-runtime; this also keeps the real token\n  out of the file. `rm -f` the helper afterward (§5, §7f).\n- **Agent verified as \"not logged in\" despite a good login.** `codex login status` (and similar) print\n  \"Logged in …\" to **stderr**; an stdout-only `grep` misses it. Prefer the status **exit code**; if you\n  grep, fold stderr first (`status 2>&1 | grep …`) and match the exact success line — not `grep -qi\n  'logged in'`, which also matches \"not logged in\".\n- **Headless agent login hangs.** Plain OAuth `login` starts a loopback callback server on a VM/container\n  port the host browser can't reach. Use the **device-auth** flow (`login --device-auth`) — it prints a\n  URL + code the user opens on the host.\n- **`known_hosts` host-key churn on local Docker.** Each ephemeral container regenerating its SSH host key\n  collides on `127.0.0.1` as the published port rotates. Bake host keys into the base image at build time\n  (`ssh-keygen -A`; runtime generates only if absent) so all containers share one stable key (§7h).\n- **Snapshot expired/evicted.** If `create` hits an unknown snapshot id, rerun Phases 2–3 and update\n  `snapshotId`.\n- **Agent auth didn't persist.** Confirm `snapshotId` points at the **authenticated** snapshot; re-run\n  Phase 3. Warn that short-lived tokens may need periodic re-auth.\n- **Agent auth copied from the host breaks.** Do not bind-mount/copy a full host agent home; sqlite\n  files can be unwritable or host-specific, hooks may need approval again, and config may reference\n  local-only env vars. Authenticate inside the runtime and snapshot/commit that layer.\n- **Docker auth image exits immediately.** Inspect `docker image inspect … .Config.Entrypoint` and\n  `docker logs`. If the image was committed from an interactive shell, reset the entrypoint to the SSH\n  entrypoint during `docker commit`.\n- **Leaked paid resource.** Every long script must trap errors and remove the sandbox it created.\n- **`create` emits non-JSON on stdout.** A stray `echo` corrupts the result — stdout is for the final\n  JSON only; everything else to stderr. The `--provision` self-test surfaces this as `exitCode 0` + a\n  `parseError` with the offending stdout in `provisionTranscript` (§9).\n\n---\n\n## 11. Boundaries\n\n- Don't create accounts, choose plans/regions, or invent scope/project/org/image/billing ids.\n- Don't invent or store credentials; no secrets in `userData`, state, comments, docs, or commits.\n- Don't run paid/long phases (base snapshot, auth, live test) without an explicit OK.\n- Don't hide provider errors behind generic messages — preserve actionable stderr.\n- Don't make Orca own provider lifecycle beyond invoking the configured scripts.\n- Don't commit or create an Orca workspace unless asked.\n"
 
 // oxfmt-ignore
-const ORCHESTRATION_MARKDOWN = "---\nname: orchestration\ndescription: >-\n  Use Orca orchestration for structured multi-agent coordination: threaded\n  messages, blocking ask/reply flows, task dispatch, worker_done/escalation\n  waits, task DAGs, decision gates, coordinator loops, or decomposing work\n  across agents. Use `orca-cli` instead for full ownership handoffs, including\n  requests phrased as \"hand off\", \"handoff\", \"handover\", \"give this to another\n  agent\", or \"another worktree\" when the user did not explicitly ask to\n  supervise, monitor, wait for results, or coordinate a DAG. Use `orca-cli` for\n  ordinary terminal control, lightweight terminal prompts, shell commands, Orca\n  worktree management, reading or waiting on terminals, and automation of the\n  browser embedded inside Orca. Use Computer Use for browser windows, webviews,\n  Orca app UI, or desktop UI outside Orca's embedded browser.\n---\n\n# Orca Inter-Agent Orchestration\n\nOrchestration is Orca's structured coordination layer for agent messages, task ownership, dispatch state, and worker completion tracking.\n\nUse this skill when coordination state matters. For lightweight terminal prompts or basic worktree/terminal/built-in-browser control, use `orca-cli`.\n\n## Tool Boundary\n\nIf a task says to use Orca orchestration, the coordinator must create Orca runtime state with `orca orchestration task-create` and `orca orchestration dispatch --inject` or `orca orchestration run`.\n\nDo not substitute non-Orca subagent tools, generic agent-spawn APIs, or chat-only parallel worker features. Those may create useful workers, but they do not create Orca task/dispatch provenance, injected lifecycle preambles, `worker_done` authority, or decision gates.\n\nBefore claiming a worker was orchestrated, verify the task/dispatch exists:\n\n```bash\norca orchestration task-list --json\norca orchestration dispatch-show --task <task_id> --json\n```\n\nIf the work was accidentally run outside Orca orchestration, say so plainly. To repair provenance, rerun or revalidate the needed work through a fresh Orca terminal plus injected dispatch; do not retroactively describe the external worker as orchestrated.\n\n## When To Use\n\n- Send/reply/ask between agent terminals with persistent messages.\n- Dispatch structured tasks to workers and wait for `worker_done` or `escalation`.\n- Track task DAGs with dependencies.\n- Run coordinator loops or decision gates.\n\nDo not use orchestration merely because the user says \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", or asks for another worktree/agent/model/effort. Those are full ownership transfers unless the user explicitly asks to supervise, monitor, wait for worker completion/results, coordinate a DAG, use decision gates, or keep a blocking ask/reply loop.\n\n## Preconditions\n\n- `orca status --json` should show a running runtime.\n- `orca` must be on PATH (`orca-ide` on Linux).\n- The orchestration experimental feature must be enabled in Settings > Experimental.\n- `orca orchestration` commands are RPC calls to the running Orca runtime.\n\n## Ownership\n\nOrchestration messages and tasks are runtime-global. Lifecycle authority comes from the payload `taskId` + `dispatchId` of the active dispatch, verified against the dispatched pane. Terminal handles are routing metadata — a pane can receive a new handle after restart — so never accept or reject lifecycle provenance by comparing handles. Send `worker_done` and `heartbeat` from the worker's own terminal; the runtime ignores them when sent from a different pane.\n\nClassify inherited context before sending lifecycle messages:\n\n- Coordinated subtask: a live coordinator owns the DAG and waits on this dispatch. Follow the preamble exactly, including `worker_done`, heartbeat/status, `ask`, and `escalation`.\n- Full handoff means ownership transfer, not supervised dispatch. The original actor is not monitoring a DAG, so do not create lifecycle obligations unless the user explicitly asks you to supervise.\n- Classify requests containing \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"another agent\", or \"another worktree\" as full handoffs by default, even when the user names a custom model or reasoning effort.\n- Use supervised orchestration only when the user explicitly asks you to \"supervise\", \"monitor\", \"wait\", \"track completion\", \"wait for worker_done\", return results, coordinate a DAG, use a decision gate, or manage ask/reply flow.\n- Do not use `orca orchestration dispatch --inject` for full handoffs. It injects a coordinator preamble that tells the worker to send `worker_done`, heartbeat, and `ask` messages, then end its turn under the original terminal's dispatch lifecycle.\n- Do not run `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. Do not peek at terminal output after prompt delivery to monitor progress.\n- A review-only `worker_done` reports findings; it does not authorize coordinator file edits. After a review-only completion, synthesize findings, ask a decision gate if ownership is unclear, and dispatch or hand off fixes unless the user explicitly asked the coordinator to own fixes.\n- If the user's plan names a next owner agent (for example, \"then use opencode to create a PR\"), post-review corrections and PR prep belong to that named owner. The coordinator routes, synthesizes, asks decision gates when needed, and supervises; the named owner edits files and creates the PR.\n\nIf unclear, inspect orchestration state before sending lifecycle messages:\n\n```bash\norca orchestration task-list --json\norca terminal list --json\n# If inherited context includes a task id:\norca orchestration dispatch-show --task <task_id> --json\n```\n\n## Messaging\n\n```bash\norca orchestration send --to <handle|@group> --subject <text> [--from <handle>] [--body <text>] [--type <type>] [--priority <level>] [--thread-id <id>] [--payload <json>] [--json]\norca orchestration check [--terminal <handle>] [--unread|--peek|--all] [--types <type,...>] [--inject] [--wait] [--timeout-ms <n>] [--json]\norca orchestration reply --id <msg_id> --body <text> [--from <handle>] [--json]\norca orchestration ask --to <handle> --question <text> [--options <csv>] [--timeout-ms <n>] [--from <handle>] [--json]\norca orchestration inbox [--limit <n>] [--json]\n```\n\nRules:\n\n- Omit `--from` unless impersonating another terminal; Orca auto-resolves it from the current terminal.\n- `check` and `check --unread` return unread matches and mark them read. Use `--peek` for unread matches without consuming them; use `--all` for read and unread history without consuming anything. If an older CLI rejects `--peek` as an unknown flag, use `--all` and filter unread rows yourself.\n- Message **one** live agent handle per worker. Use `startupTerminal.handle` from the create response when present; if it is missing or later returns `terminal_handle_stale`, re-resolve with `orca terminal list --worktree ... --json` and continue with the replacement only.\n- `orca orchestration check --unread --inject --json` renders unread mail for the agent terminal that runs it; it does not remotely wake another terminal. Use `orchestration dispatch --inject` to deliver a tracked task, or `terminal send` when an existing agent needs a free-form prompt.\n- While supervising workers manually, use `check --wait --types worker_done,escalation,decision_gate --timeout-ms <n>` instead of sleep/poll loops. Reply to `decision_gate` messages with `orca orchestration reply --id <msg_id> --body <answer> --json`, then keep waiting.\n- Treat a `check --wait` timeout or `{count:0}` as a checkpoint, not a worker failure. Long coding tasks routinely run 15-60 minutes; keep using rolling waits unless you receive `worker_done`/`escalation`, the terminal exits or disappears, or the user explicitly asks you to stop.\n- Heartbeats and visible terminal activity mean the worker is alive, not done. Do not stop, close, kill, or restart a worker just because it has not produced a completion message yet.\n- Use `ask` when a worker needs a blocking answer from the coordinator; it waits for the reply and returns the answer directly.\n- `check --wait` returns one message at a time. If N workers may finish together, loop N times and dispatch newly ready tasks after each completion.\n- Group addresses include `@all`, `@idle`, `@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`, `@cursor`, and `@worktree:<id>`.\n- Message types include `status`, `dispatch`, `worker_done`, `merge_ready`, `escalation`, `handoff`, `decision_gate`, and `heartbeat`.\n- Use group addresses only for messages that are genuinely useful to many terminals, such as `status` broadcasts or intentional fan-out questions. Do not send dispatch lifecycle messages to groups.\n- `worker_done` must target the concrete coordinator handle from the live preamble. It is completion authority for one dispatch; group fanout would create false lifecycle mail in unrelated terminals.\n- A valid `worker_done` for the active `taskId` + `dispatchId` marks the task and dispatch completed automatically. Do not follow it with `task-update --status completed`; reserve manual updates for explicit recovery or overrides.\n- `heartbeat` is also dispatch-scoped. Send it only to the concrete coordinator handle with both `taskId` and `dispatchId`; use `status` for broad progress updates.\n\n## Tasks And Dispatch\n\nA task is the work item, a dispatch assigns it to a terminal, and a gate blocks progress until a coordinator or user decision is recorded.\n\n```bash\norca orchestration task-create --spec <text> [--deps <json_array>] [--parent <task_id>] [--json]\norca orchestration task-list [--status <status>] [--ready] [--brief] [--json]\norca orchestration task-update --id <task_id> --status <status> [--result <json>] [--json]\norca orchestration dispatch --task <task_id> --to <handle> [--from <handle>] [--inject] [--json]\norca orchestration dispatch-show --task <task_id> [--json]\n```\n\nTask statuses: `pending`, `ready`, `dispatched`, `completed`, `failed`, `blocked`.\n\nDispatch rules:\n\n- `--inject` sends the task spec plus preamble into a recognized agent CLI so it can report `worker_done`.\n- If the target is a bare shell, omit `--inject`, dispatch for tracking if needed, then send the prompt manually with `orca terminal send --terminal <handle> --text <prompt> --enter --json`.\n- After 3 consecutive failures on one task, the dispatch context circuit-breaks and the task is marked failed.\n- Use `task-list --brief --json` for coordinator sweeps; it collapses whitespace and caps each echoed spec at 160 characters (`spec_truncated` marks shortened rows). Omit `--brief` when the full spec is required, or when an older CLI rejects it as an unknown flag.\n\n## Gates And Coordinator\n\n```bash\norca orchestration gate-create --task <task_id> --question <text> [--options <json_array>] [--json]\norca orchestration gate-resolve --id <gate_id> --resolution <text> [--json]\norca orchestration gate-list [--task <task_id>] [--status <status>] [--json]\norca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector>] [--json]\norca orchestration run-stop [--json]\n```\n\n`run` returns immediately with a run ID. Query progress with `task-list`. Use `ask` for worker-to-coordinator questions; it creates a `decision_gate` message that the coordinator answers with `reply`. Use `gate-create` only for coordinator-managed task DAG decisions, not for answering a worker's `ask`.\n\nRecovery only: `orca orchestration reset --tasks|--messages|--all --json` clears runtime-global orchestration state. Do not run it during active coordination unless explicitly abandoning that state.\n\n## Full Handoffs\n\nFor full ownership transfer, use non-lifecycle terminal/worktree commands and then stop monitoring unless the user asks for supervision.\n\nTreat these as full handoff requests by default: \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"send this to another agent\", \"another agent\", \"another worktree\", or \"launch another agent to own this.\" Custom model or reasoning effort words such as `gpt-5.5`, `high`, or `xhigh` do not make the handoff supervised.\n\nSupervised orchestration remains available only when the user explicitly asks for supervision or coordination: \"supervise\", \"monitor\", \"wait for worker_done\", \"wait for results\", \"track completion\", \"DAG\", \"decision gate\", \"ask/reply\", or \"coordinate workers.\"\n\nDo not run `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. `task-create` is also forbidden because it records coordinator-owned tracking state; if a task row is needed, the user asked for supervised orchestration. Do not create a `taskId`/`dispatchId`, inject a lifecycle preamble, wait for completion, or read the worker terminal after prompt delivery except to avoid losing the initial prompt.\n\nNew top-level worktree handoff:\n\n```bash\norca worktree create --name <task-name> --no-parent --agent codex --prompt \"<task brief>\" --json\n```\n\nBefore creating a new worktree from an active feature branch, decide and state whether the desired Orca lineage is child or top-level. Use child worktree lineage only when the new work is conceptually stacked under or dependent on the active worktree. For independent repo-wide fixes, standalone feature work, or unrelated follow-up tasks, create a top-level worktree with `--no-parent`.\n\nExisting terminal handoff:\n\n```bash\norca terminal send --terminal <handle> --text \"<task brief>\" --enter --json\n```\n\nCustom Codex model/effort handoff:\n\n`orca worktree create --agent codex --prompt ...` launches the known Codex agent but does not accept Codex-specific `--model` or `-c model_reasoning_effort=...` arguments. When the user asks for a specific Codex model or effort, create the independent worktree first, launch Codex with the requested command in that worktree, wait only for TUI readiness if prompt delivery would otherwise race startup, send the prompt, and stop.\n\nNote: when no repo default-terminal configuration supplies a primary terminal, bare create opens a fallback shell before `terminal create` adds the agent. Configured default tabs are materialized instead and may run real commands. Prefer `--agent` whenever custom argv is not required. With the two-step path, target only the agent handle; close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell.\n\nUse the exact full `<repo-id>::<path>` worktree id returned by `orca worktree create --json`; a bare repo id cannot target the new worktree.\n\n```bash\norca worktree create --name <task-name> --no-parent --json\norca terminal create --worktree id:<newFullWorktreeId> --title <task-name> --command 'codex --model gpt-5.5 -c model_reasoning_effort=\"xhigh\"' --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca terminal send --terminal <handle> --text \"<task brief>\" --enter --json\n```\n\nWait only for `tui-idle` when needed to avoid losing the prompt. Do not monitor task completion.\n\n`--no-parent` only controls Orca lineage; it does not choose the Git base. If the work should start from the repo default base, omit `--base-branch` so Orca uses that default, or explicitly pass the repo default base (`origin/main`, `origin/master`, or the `orca repo show --repo <selector> --json` value); never base it on the current feature branch unless the user explicitly asks for stacked work or \"branch from current\". Put current-branch context in the prompt instead.\n\n## Worker Terminals\n\nChoose the worker location before creating a terminal. `Fresh worker` means a fresh agent session, not a new git worktree. If the task says current worktree only, depends on uncommitted files/artifacts, or must validate/PR the current branch, create the worker in the active worktree:\n\n```bash\norca terminal create --worktree active --title <task-name> --command \"codex\" --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\n```\n\nReuse an idle agent in the required worktree only if the prompt allows reuse; otherwise create a fresh terminal there. Use a new worktree only when explicitly requested or when independent isolated checkout state is intended. For supervised new-worktree workers, decide the desired Orca lineage before creation: use child lineage only when the work is conceptually stacked under or dependent on the active worktree, and use `--no-parent` for independent repo-wide fixes, standalone feature work, or unrelated follow-up tasks. Decide the Git base separately from lineage: `--no-parent` makes the worktree top-level in Orca, while omitted `--base-branch` uses the repo default base.\n\n```bash\norca worktree create --name <task-name> --agent codex --json\n# or: --agent claude | omp | pi | grok | ...\n# Read <handle> from startupTerminal.handle in the create response.\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\n```\n\nFor new-worktree workers, read the id and `startupTerminal.handle` from `worktree create`. Use that as the sole worker handle when present; otherwise use `terminal list` to resolve the agent handle. Omit `--repo` only inside an Orca-managed worktree; otherwise pass `--repo <selector>`.\n\n**Agent-first (required for ordinary agent workers):** `--agent` reveals the new worktree and launches the selected agent **in its first terminal**, without adding a separate fallback shell for that worker. Repo setup or default-terminal settings may still add tabs or splits. Do **not** run bare `worktree create` and then `terminal create --command <agent>` for the same worker when agent-first create is available: without configured default tabs, that two-step path leaves a fallback shell + agent pair. Only use it when custom agent argv is required (for example Codex model/effort flags) or when an older CLI rejects `--agent`; if you must, message only the agent handle. Configured default tabs are intentional surfaces, so close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell. Do not run `worktree create` when the task must stay in the current worktree.\n\nUse `orca worktree create --prompt ...` or `orca terminal send ...` for full handoffs or untracked/lightweight prompts. Those paths do not attach `taskId`/`dispatchId`; the worker should not send lifecycle messages unless the prompt supplies a live orchestration preamble.\n\nSidebar lineage and orchestration lifecycle are related but not identical. A same-worktree worker created with `orca terminal create --worktree active` may appear as a peer terminal/agent under the same worktree in the sidebar even though it is a child dispatch in Orca orchestration state. A visible parent/child worktree relationship requires creating a child worktree, but do that only when the task can safely run from an isolated checkout and does not need uncommitted artifacts from the current working tree.\n\nOther terminal commands coordinators often need:\n\n```bash\norca terminal list [--worktree <selector>] [--json]\norca terminal create [--worktree <selector>] [--title <text>] [--command <cmd>] [--json]\norca terminal split --terminal <handle> [--direction horizontal|vertical] [--command <cmd>] [--json]\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms <n> --json\norca terminal read --terminal <handle> --json\norca terminal send --terminal <handle> --text <text> --enter --json\n```\n\nIf an older CLI rejects `worktree create --agent`, create the worktree normally, then run `orca terminal create --worktree <selector> --command \"codex\" --json` or `--command \"claude\"`.\n\nWait for `tui-idle` before dispatching. Always pass `--timeout-ms`; real coding tasks can take 15-60 minutes. During supervision, use rolling `check --wait` windows. If a window returns no matching message, inspect `task-list`, `terminal read`, or `terminal wait --for tui-idle` as a liveness checkpoint; if the terminal is still working or producing activity, keep waiting instead of retrying the task.\n\n## Agent Guidance\n\n- Workers with a valid live preamble must send `worker_done` exactly once from their own terminal, even on failure:\n  `orca orchestration send --to <coordinator_handle> --type worker_done --subject \"<short status>\" --body \"<3-sentence summary: what you did, what you found, what's left>\" --payload '{\"taskId\":\"<task_id>\",\"dispatchId\":\"<dispatch_id>\",\"filesModified\":[\"path/a\"],\"reportPath\":\"<optional>\"}' --json`\n- After sending `worker_done`, end your turn and idle at the agent prompt. Do not poll or keep calling `orca orchestration check`; the coordinator re-engages you with a fresh preamble + TASK block delivered as new terminal input.\n- For long tasks, send heartbeat/status only when the preamble asks for it, including both IDs:\n  `orca orchestration send --to <coordinator_handle> --type heartbeat --subject \"alive\" --payload '{\"taskId\":\"<task_id>\",\"dispatchId\":\"<dispatch_id>\",\"phase\":\"implementing\"}' --json`\n- If blocked before completion, use `ask`; use `escalation` only when ownership is valid and the coordinator must intervene.\n- Treat preambles inherited through terminal history or full handoffs as stale unless the current prompt explicitly keeps that coordinator in the loop.\n- Coordinators should use `task-list --ready` as external memory, dispatch parallel waves, and avoid dependency chains deeper than 3-4 steps.\n- Prefer inter-worktree workers only for independent work that does not need current uncommitted state. When same-worktree work is required, create fresh terminals in that worktree and keep edit ownership clear.\n\n## Example\n\n```bash\norca terminal create --worktree active --title login-css-worker --command \"claude\" --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration task-create --spec \"Fix the login button CSS\" --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\norca orchestration check --wait --types worker_done,escalation,decision_gate --timeout-ms 900000 --json\n```\n\n## Next Action\n\nCoordinator: confirm `orca status --json`, inspect `task-list`/`dispatch-show` if inheriting state, then choose either a manual loop (`task-create` -> worker -> `dispatch --inject` -> `check --wait`) or `orchestration run`.\n\nWorker: if the current prompt contains a live dispatch preamble, do the task, use `ask` for blocking questions, and send `worker_done` once with the required payload. If the preamble is stale or absent, do not send lifecycle messages; inspect state or treat the prompt as an ordinary handoff.\n"
+const ORCHESTRATION_MARKDOWN = "---\nname: orchestration\ndescription: >-\n  Use Orca orchestration for structured multi-agent coordination: threaded\n  messages, blocking ask/reply flows, task dispatch, worker_done/escalation\n  waits, task DAGs, decision gates, coordinator loops, or decomposing work\n  across agents. Use `orca-cli` instead for full ownership handoffs, including\n  requests phrased as \"hand off\", \"handoff\", \"handover\", \"give this to another\n  agent\", or \"another worktree\" when the user did not explicitly ask to\n  supervise, monitor, wait for results, or coordinate a DAG. Use `orca-cli` for\n  ordinary terminal control, lightweight terminal prompts, shell commands, Orca\n  worktree management, reading or waiting on terminals, and automation of the\n  browser embedded inside Orca. Use Computer Use for browser windows, webviews,\n  Orca app UI, or desktop UI outside Orca's embedded browser.\n---\n\n# Orca Inter-Agent Orchestration\n\nOrchestration is Orca's structured coordination layer for agent messages, task ownership, dispatch state, and worker completion tracking.\n\nUse this skill when coordination state matters. For lightweight terminal prompts or basic worktree/terminal/built-in-browser control, use `orca-cli`.\n\n## Tool Boundary\n\nIf a task says to use Orca orchestration, the coordinator must create Orca runtime state with `orca orchestration task-create` and `orca orchestration dispatch --inject` or `orca orchestration run`.\n\nDo not substitute non-Orca subagent tools, generic agent-spawn APIs, or chat-only parallel worker features. Those may create useful workers, but they do not create Orca task/dispatch provenance, injected lifecycle preambles, `worker_done` authority, or decision gates.\n\nBefore claiming a worker was orchestrated, verify the task/dispatch exists:\n\n```bash\norca orchestration task-list --json\norca orchestration dispatch-show --task <task_id> --json\n```\n\nIf the work was accidentally run outside Orca orchestration, say so plainly. To repair provenance, rerun or revalidate the needed work through a fresh Orca terminal plus injected dispatch; do not retroactively describe the external worker as orchestrated.\n\n## When To Use\n\n- Send/reply/ask between agent terminals with persistent messages.\n- Dispatch structured tasks to workers and wait for `worker_done` or `escalation`.\n- Track task DAGs with dependencies.\n- Run coordinator loops or decision gates.\n\nDo not use orchestration merely because the user says \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", or asks for another worktree/agent/model/effort. Those are full ownership transfers unless the user explicitly asks to supervise, monitor, wait for worker completion/results, coordinate a DAG, use decision gates, or keep a blocking ask/reply loop.\n\n## Preconditions\n\n- `orca status --json` should show a running runtime.\n- `orca` must be on PATH (`orca-ide` on Linux).\n- The orchestration experimental feature must be enabled in Settings > Experimental.\n- `orca orchestration` commands are RPC calls to the running Orca runtime.\n\n## Ownership\n\nOrchestration messages and tasks are runtime-global. Lifecycle authority comes from the payload `taskId` + `dispatchId` of the active dispatch, verified against the dispatched pane. Terminal handles are routing metadata — a pane can receive a new handle after restart — so never accept or reject lifecycle provenance by comparing handles. Send `worker_done` and `heartbeat` from the worker's own terminal; the runtime ignores them when sent from a different pane.\n\nClassify inherited context before sending lifecycle messages:\n\n- Coordinated subtask: a live coordinator owns the DAG and waits on this dispatch. Follow the preamble exactly, including `worker_done`, heartbeat/status, `ask`, and `escalation`.\n- Full handoff means ownership transfer, not supervised dispatch. The original actor is not monitoring a DAG, so do not create lifecycle obligations unless the user explicitly asks you to supervise.\n- Classify requests containing \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"another agent\", or \"another worktree\" as full handoffs by default, even when the user names a custom model or reasoning effort.\n- Use supervised orchestration only when the user explicitly asks you to \"supervise\", \"monitor\", \"wait\", \"track completion\", \"wait for worker_done\", return results, coordinate a DAG, use a decision gate, or manage ask/reply flow.\n- Do not use `orca orchestration dispatch --inject` for full handoffs. It injects a coordinator preamble that tells the worker to send `worker_done`, heartbeat, and `ask` messages, then end its turn under the original terminal's dispatch lifecycle.\n- Do not run `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. Do not peek at terminal output after prompt delivery to monitor progress.\n- A review-only `worker_done` reports findings; it does not authorize coordinator file edits. After a review-only completion, synthesize findings, ask a decision gate if ownership is unclear, and dispatch or hand off fixes unless the user explicitly asked the coordinator to own fixes.\n- If the user's plan names a next owner agent (for example, \"then use opencode to create a PR\"), post-review corrections and PR prep belong to that named owner. The coordinator routes, synthesizes, asks decision gates when needed, and supervises; the named owner edits files and creates the PR.\n\nIf unclear, inspect orchestration state before sending lifecycle messages:\n\n```bash\norca orchestration task-list --json\norca terminal list --json\n# If inherited context includes a task id:\norca orchestration dispatch-show --task <task_id> --json\n```\n\n## Messaging\n\n```bash\norca orchestration send --to <handle|@group> --subject <text> [--from <handle>] [--body <text>] [--type <type>] [--priority <level>] [--thread-id <id>] [--payload <json>] [--json]\norca orchestration check [--terminal <handle>] [--unread|--peek|--all] [--types <type,...>] [--inject] [--wait] [--timeout-ms <n>] [--json]\norca orchestration reply --id <msg_id> --body <text> [--from <handle>] [--json]\norca orchestration ask --to <handle> --question <text> [--options <csv>] [--timeout-ms <n>] [--from <handle>] [--json]\norca orchestration inbox [--limit <n>] [--json]\n```\n\nRules:\n\n- Omit `--from` unless impersonating another terminal; Orca auto-resolves it from the current terminal.\n- `check` and `check --unread` return unread matches and mark them read. Use `--peek` for unread matches without consuming them; use `--all` for read and unread history without consuming anything. If an older CLI rejects `--peek` as an unknown flag, use `--all` and filter unread rows yourself.\n- Message **one** live agent handle per worker. Use `startupTerminal.handle` from the create response when present; if it is missing or later returns `terminal_handle_stale`, re-resolve with `orca terminal list --worktree ... --json` and continue with the replacement only.\n- `orca orchestration check --unread --inject --json` renders unread mail for the agent terminal that runs it; it does not remotely wake another terminal. Use `orchestration dispatch --inject` to deliver a tracked task, or `terminal send` when an existing agent needs a free-form prompt.\n- While supervising workers manually, use `check --wait --types worker_done,escalation,decision_gate --timeout-ms <n>` instead of sleep/poll loops. Reply to `decision_gate` messages with `orca orchestration reply --id <msg_id> --body <answer> --json`, then keep waiting.\n- Treat a `check --wait` timeout or `{count:0}` as a checkpoint, not a worker failure. Long coding tasks routinely run 15-60 minutes; keep using rolling waits unless you receive `worker_done`/`escalation`, the terminal exits or disappears, or the user explicitly asks you to stop.\n- Heartbeats and visible terminal activity mean the worker is alive, not done. Do not stop, close, kill, or restart a worker just because it has not produced a completion message yet.\n- Use `ask` when a worker needs a blocking answer from the coordinator; it waits for the reply and returns the answer directly.\n- `check --wait` returns one message at a time. If N workers may finish together, loop N times and dispatch newly ready tasks after each completion.\n- Group addresses include `@all`, `@idle`, `@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`, `@cursor`, and `@worktree:<id>`.\n- Message types include `status`, `dispatch`, `worker_done`, `merge_ready`, `escalation`, `handoff`, `decision_gate`, and `heartbeat`.\n- Use group addresses only for messages that are genuinely useful to many terminals, such as `status` broadcasts or intentional fan-out questions. Do not send dispatch lifecycle messages to groups.\n- `worker_done` must target the concrete coordinator handle from the live preamble. It is completion authority for one dispatch; group fanout would create false lifecycle mail in unrelated terminals.\n- A valid `worker_done` for the active `taskId` + `dispatchId` marks the task and dispatch completed automatically. Do not follow it with `task-update --status completed`; reserve manual updates for explicit recovery or overrides.\n- `heartbeat` is also dispatch-scoped. Send it only to the concrete coordinator handle with both `taskId` and `dispatchId`; use `status` for broad progress updates.\n\n## Tasks And Dispatch\n\nA task is the work item, a dispatch assigns it to a terminal, and a gate blocks progress until a coordinator or user decision is recorded.\n\n```bash\norca orchestration task-create --spec <text> [--deps <json_array>] [--parent <task_id>] [--json]\norca orchestration task-list [--status <status>] [--ready] [--brief] [--json]\norca orchestration task-update --id <task_id> --status <status> [--result <json>] [--json]\norca orchestration dispatch --task <task_id> --to <handle> [--from <handle>] [--inject] [--json]\norca orchestration dispatch-show --task <task_id> [--json]\n```\n\nTask statuses: `pending`, `ready`, `dispatched`, `completed`, `failed`, `blocked`.\n\nDispatch rules:\n\n- `--inject` sends the task spec plus preamble into a recognized agent CLI so it can report `worker_done`.\n- If the target is a bare shell, omit `--inject`, dispatch for tracking if needed, then send the prompt manually with `orca terminal send --terminal <handle> --text <prompt> --enter --json`.\n- After 3 consecutive failures on one task, the dispatch context circuit-breaks and the task is marked failed.\n- Use `task-list --brief --json` for coordinator sweeps; it collapses whitespace and caps each echoed spec at 160 characters (`spec_truncated` marks shortened rows). Omit `--brief` when the full spec is required, or when an older CLI rejects it as an unknown flag.\n\n## Gates And Coordinator\n\n```bash\norca orchestration gate-create --task <task_id> --question <text> [--options <json_array>] [--json]\norca orchestration gate-resolve --id <gate_id> --resolution <text> [--json]\norca orchestration gate-list [--task <task_id>] [--status <status>] [--json]\norca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector>] [--json]\norca orchestration run-stop [--json]\n```\n\n`run` returns immediately with a run ID. Query progress with `task-list`. Use `ask` for worker-to-coordinator questions; it creates a `decision_gate` message that the coordinator answers with `reply`. Use `gate-create` only for coordinator-managed task DAG decisions, not for answering a worker's `ask`.\n\nRecovery only: `orca orchestration reset --tasks|--messages|--all --json` clears runtime-global orchestration state. Do not run it during active coordination unless explicitly abandoning that state.\n\n## Full Handoffs\n\nFor full ownership transfer, use non-lifecycle terminal/worktree commands and then stop monitoring unless the user asks for supervision.\n\nTreat these as full handoff requests by default: \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"send this to another agent\", \"another agent\", \"another worktree\", or \"launch another agent to own this.\" Custom model or reasoning effort words such as `gpt-5.5`, `high`, or `xhigh` do not make the handoff supervised.\n\nSupervised orchestration remains available only when the user explicitly asks for supervision or coordination: \"supervise\", \"monitor\", \"wait for worker_done\", \"wait for results\", \"track completion\", \"DAG\", \"decision gate\", \"ask/reply\", or \"coordinate workers.\"\n\nDo not run `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. `task-create` is also forbidden because it records coordinator-owned tracking state; if a task row is needed, the user asked for supervised orchestration. Do not create a `taskId`/`dispatchId`, inject a lifecycle preamble, wait for completion, or read the worker terminal after prompt delivery except to avoid losing the initial prompt.\n\nNew top-level worktree handoff:\n\n```bash\norca worktree create --name <task-name> --no-parent --agent codex --prompt \"<task brief>\" --json\n```\n\nBefore creating a new worktree from an active feature branch, decide and state whether the desired Orca lineage is child or top-level. Use child worktree lineage only when the new work is conceptually stacked under or dependent on the active worktree. For independent repo-wide fixes, standalone feature work, or unrelated follow-up tasks, create a top-level worktree with `--no-parent`.\n\nExisting terminal handoff:\n\n```bash\norca terminal send --terminal <handle> --text \"<task brief>\" --enter --json\n```\n\nCustom Codex model/effort handoff:\n\n`orca worktree create --agent codex --prompt ...` launches the known Codex agent but does not accept Codex-specific `--model` or `-c model_reasoning_effort=...` arguments. When the user asks for a specific Codex model or effort, create the independent worktree first, launch Codex with the requested command in that worktree, wait only for TUI readiness if prompt delivery would otherwise race startup, send the prompt, and stop.\n\nNote: when no repo default-terminal configuration supplies a primary terminal, bare create opens a fallback shell before `terminal create` adds the agent. Configured default tabs are materialized instead and may run real commands. Prefer `--agent` whenever custom argv is not required. With the two-step path, target only the agent handle; close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell.\n\nUse the exact full `<repo-id>::<path>` worktree id returned by `orca worktree create --json`; a bare repo id cannot target the new worktree.\n\n```bash\norca worktree create --name <task-name> --no-parent --json\norca terminal create --worktree id:<newFullWorktreeId> --title <task-name> --command 'codex --model gpt-5.5 -c model_reasoning_effort=\"xhigh\"' --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca terminal send --terminal <handle> --text \"<task brief>\" --enter --json\n```\n\nWait only for `tui-idle` when needed to avoid losing the prompt. Do not monitor task completion.\n\n`--no-parent` only controls Orca lineage; it does not choose the Git base. If the work should start from the repo default base, omit `--base-branch` so Orca uses that default, or explicitly pass the repo default base (`origin/main`, `origin/master`, or the `orca repo show --repo <selector> --json` value); never base it on the current feature branch unless the user explicitly asks for stacked work or \"branch from current\". Put current-branch context in the prompt instead.\n\n## Worker Terminals\n\nChoose the worker location before creating a terminal. `Fresh worker` means a fresh agent session, not a new git worktree. For parallel work, create one fresh agent terminal per worker in the same required worktree, falling back to the active worktree when none is named. If the task says current worktree only, depends on uncommitted files/artifacts, or must validate/PR the current branch, keep every worker in the active worktree:\n\n```bash\norca terminal create --worktree active --title <task-name> --command \"codex\" --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\n```\n\nReuse an idle agent in the required worktree only if the prompt allows reuse; otherwise create a fresh terminal there. Create a new worktree only when the user explicitly requests one or a concrete checkout or filesystem conflict makes sharing unsafe or impossible; if the user did not request it, state that conflict before running `worktree create`. Independent tasks, parallel execution, convenience, or a preference for separate checkouts are not isolation requirements.\n\nWhen a new worktree is allowed, use child lineage for isolated work that is stacked under or dependent on the active worktree, and use `--no-parent` when it is not stacked. Decide the Git base separately: `--no-parent` makes the worktree top-level in Orca, while omitted `--base-branch` uses the repo default base.\n\n```bash\norca worktree create --name <task-name> --agent codex --json\n# or: --agent claude | omp | pi | grok | ...\n# Read <handle> from startupTerminal.handle in the create response.\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\n```\n\nFor new-worktree workers, read the id and `startupTerminal.handle` from `worktree create`. Use that as the sole worker handle when present; otherwise use `terminal list` to resolve the agent handle. Omit `--repo` only inside an Orca-managed worktree; otherwise pass `--repo <selector>`.\n\n**For an allowed new worktree, use agent-first:** `--agent` reveals the new worktree and launches the selected agent **in its first terminal**, without adding a separate fallback shell for that worker. Repo setup or default-terminal settings may still add tabs or splits. Do **not** run bare `worktree create` and then `terminal create --command <agent>` for the same worker when agent-first create is available: without configured default tabs, that two-step path leaves a fallback shell + agent pair. Only use it when custom agent argv is required (for example Codex model/effort flags) or when an older CLI rejects `--agent`; if you must, message only the agent handle. Configured default tabs are intentional surfaces, so close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell. Do not run `worktree create` when the task must stay in the current worktree.\n\nUse `orca worktree create --prompt ...` or `orca terminal send ...` for full handoffs or untracked/lightweight prompts. Those paths do not attach `taskId`/`dispatchId`; the worker should not send lifecycle messages unless the prompt supplies a live orchestration preamble.\n\nSidebar lineage and orchestration lifecycle are related but not identical. A same-worktree worker may appear as a peer under that worktree in the sidebar while remaining a child dispatch in orchestration state; only an actual child worktree creates visible parent/child worktree lineage.\n\nOther terminal commands coordinators often need:\n\n```bash\norca terminal list [--worktree <selector>] [--json]\norca terminal create [--worktree <selector>] [--title <text>] [--command <cmd>] [--json]\norca terminal split --terminal <handle> [--direction horizontal|vertical] [--command <cmd>] [--json]\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms <n> --json\norca terminal read --terminal <handle> --json\norca terminal send --terminal <handle> --text <text> --enter --json\n```\n\nIf an older CLI rejects `worktree create --agent`, create the worktree normally, then run `orca terminal create --worktree <selector> --command \"codex\" --json` or `--command \"claude\"`.\n\nWait for `tui-idle` before dispatching. Always pass `--timeout-ms`; real coding tasks can take 15-60 minutes. During supervision, use rolling `check --wait` windows. If a window returns no matching message, inspect `task-list`, `terminal read`, or `terminal wait --for tui-idle` as a liveness checkpoint; if the terminal is still working or producing activity, keep waiting instead of retrying the task.\n\n## Agent Guidance\n\n- Workers with a valid live preamble must send `worker_done` exactly once from their own terminal, even on failure:\n  `orca orchestration send --to <coordinator_handle> --type worker_done --subject \"<short status>\" --body \"<3-sentence summary: what you did, what you found, what's left>\" --payload '{\"taskId\":\"<task_id>\",\"dispatchId\":\"<dispatch_id>\",\"filesModified\":[\"path/a\"],\"reportPath\":\"<optional>\"}' --json`\n- After sending `worker_done`, end your turn and idle at the agent prompt. Do not poll or keep calling `orca orchestration check`; the coordinator re-engages you with a fresh preamble + TASK block delivered as new terminal input.\n- For long tasks, send heartbeat/status only when the preamble asks for it, including both IDs:\n  `orca orchestration send --to <coordinator_handle> --type heartbeat --subject \"alive\" --payload '{\"taskId\":\"<task_id>\",\"dispatchId\":\"<dispatch_id>\",\"phase\":\"implementing\"}' --json`\n- If blocked before completion, use `ask`; use `escalation` only when ownership is valid and the coordinator must intervene.\n- Treat preambles inherited through terminal history or full handoffs as stale unless the current prompt explicitly keeps that coordinator in the loop.\n- Coordinators should use `task-list --ready` as external memory, dispatch parallel waves, and avoid dependency chains deeper than 3-4 steps.\n\n## Example\n\n```bash\norca terminal create --worktree active --title login-css-worker --command \"claude\" --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration task-create --spec \"Fix the login button CSS\" --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\norca orchestration check --wait --types worker_done,escalation,decision_gate --timeout-ms 900000 --json\n```\n\n## Next Action\n\nCoordinator: confirm `orca status --json`, inspect `task-list`/`dispatch-show` if inheriting state, then choose either a manual loop (`task-create` -> worker -> `dispatch --inject` -> `check --wait`) or `orchestration run`.\n\nWorker: if the current prompt contains a live dispatch preamble, do the task, use `ask` for blocking questions, and send `worker_done` once with the required payload. If the preamble is stale or absent, do not send lifecycle messages; inspect state or treat the prompt as an ordinary handoff.\n"
 
 // Why: no current guide has bundled reference documents, so --full is byte-identical for now.
 // oxfmt-ignore

From 1def694e80ef6822428128557784e326fb671b0b Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Sun, 19 Jul 2026 17:31:34 -0700
Subject: [PATCH 17/54] Add native chat skill picker with host-aware discovery
 (#9480)

* Add native chat skill and command picker with host-aware discovery

Adds a unified, keyboard-first skill and command picker to native chat that:

- Uses agent-native invocation syntax (slash for Claude/OpenClaude/Grok, dollar for Codex)
- Discovers skills only on the pane's execution host (local, WSL, SSH-unavailable, or runtime)
- Groups or separates commands and skills per agent configuration
- Deduplicates by canonical path but preserves visibility through all contributing roots
- Handles IME composition, loading states, and errors without claiming PTY-level control
- Records picker telemetry (open, item accepted, send classification, discovery outcomes)
- Extends shared agent profiles to define per-agent skill grammars and source ownership

* Remove obsolete reference and design documentation

Clean up stale design specs, implementation plans, and investigation notes from
docs/reference/. These documents predate the current implementation and are no
longer actively maintained or referenced by the codebase.

* Extract shared skill discovery utilities and add skill invocation envelo

- Move skill comparison and source classification to shared module for native/WSL reuse
- Extract display text sanitization to prevent control/zero-width character spoofing
- Add native-chat command envelope parser and surfacer for skill invocations
- Extend discovery timeout backstop to account for WSL metadata read sequence

* Localize skill picker UI for Spanish, Japanese, Korean, Chinese

Translate skill picker UI strings including commands, skills, loading
states, error messages, and scope labels for the new skill picker feature
across four language locales.

* Fix skill picker bugs and improve code robustness

- Fix i18n plural handling: rename `count` to `sourceCount` to prevent unintended plural-key resolution in localized strings
- Fix skill discovery array mutations: copy `root.providers` to prevent bugs during dedup merge
- Fix image attachments being silently dropped when message text starts with /skill or agent prefix
- Extract `quoteBashString` utility for WSL command code reuse across builders
- Add line-separator safety characters (0x2028/0x2029) to skill display filter
- Remove stale doc reference links and clarify inline comments

* Add reference docs for git compatibility and headless Linux server setup

Track previously untracked operational guides in `docs/reference/` that
explain Git binary compatibility requirements across host types and how to
run `orca serve` on headless Linux. Update AGENTS.md and README.md to link
to these references.
---
 .gitignore                                    |  13 +-
 ...ca-mobile-manual-network-address-design.md | 193 ----
 docs/reference/README.md                      |  17 -
 docs/reference/agent-hook-stdin-lifecycle.md  | 204 ----
 .../agent-session-resume-cli-evidence.md      | 341 ------
 .../browser-local-https-certificate-trust.md  | 926 -----------------
 docs/reference/direct-url-or-file-entry.md    | 146 ---
 .../feature-discovery-interaction-tracking.md |  68 --
 .../feature-education-retention-analytics.md  | 182 ----
 docs/reference/feature-education-state.md     |  75 --
 .../keyboard-layout-shortcut-dispatch.md      |  66 --
 .../new-user-parallel-work-telemetry.md       | 245 -----
 .../opencode-commit-message-stdin.md          | 105 --
 ...6-27-orca-mobile-manual-network-address.md | 972 ------------------
 ...2026-07-10-ssh-repo-host-reconciliation.md | 131 ---
 docs/reference/project-ordering-mode.md       | 108 --
 .../reliability-gates-implementation-plan.md  | 783 --------------
 .../reliability-pain-points-2026-06-30.md     | 712 -------------
 docs/reference/ssh-gssapi-kerberos.md         |  39 -
 .../ssh-typing-latency-under-relay-load.md    | 115 ---
 docs/reference/telemetry-availability.md      | 393 -------
 .../terminal-cold-park-reveal-cost.md         | 132 ---
 .../reference/terminal-hidden-view-parking.md | 119 ---
 .../reference/terminal-model-view-contract.md | 218 ----
 docs/reference/terminal-query-authority.md    | 347 -------
 docs/reference/terminal-session-lifecycle.md  | 580 -----------
 .../terminal-side-effect-authority.md         | 252 -----
 ...erminal-switch-typing-lag-investigation.md | 362 -------
 .../headless-emulator-fidelity.fuzz.test.ts   |   4 +-
 src/main/daemon/headless-emulator.ts          |   2 +-
 .../terminal-view-attribute-responder.ts      |   4 +-
 src/main/ipc/pty-hidden-delivery-gate.ts      |   1 -
 src/main/ipc/skills.test.ts                   |  61 +-
 src/main/ipc/skills.ts                        |  59 +-
 src/main/runtime/orca-runtime.ts              |  10 +
 src/main/runtime/rpc/methods/skills.test.ts   |  68 ++
 src/main/runtime/rpc/methods/skills.ts        |  27 +-
 .../runtime/terminal-model-query-authority.ts |   2 +-
 .../runtime/terminal-query-responder.test.ts  |   2 +-
 .../runtime/terminal-view-attribute-store.ts  |   4 +-
 .../claude-plugin-skill-sources-wsl.test.ts   |  38 +
 .../skills/claude-plugin-skill-sources-wsl.ts | 100 ++
 .../claude-plugin-skill-sources.test.ts       | 122 +++
 .../skills/claude-plugin-skill-sources.ts     | 219 ++++
 src/main/skills/discovery.test.ts             |  84 ++
 src/main/skills/discovery.ts                  | 108 +-
 src/main/skills/skill-discovery-sources.ts    | 147 ++-
 src/main/skills/skill-discovery-target.ts     |  70 ++
 .../skill-discovery-wsl-plugins.test.ts       |  83 ++
 src/main/skills/skill-discovery-wsl.test.ts   |  96 ++
 src/main/skills/skill-discovery-wsl.ts        | 212 ++++
 .../skill-freshness-inventory-limits.test.ts  |   3 +-
 src/main/telemetry/validator.test.ts          |   2 +-
 src/main/wsl-bash-command.ts                  |   5 +-
 src/preload/api-types.ts                      |   2 +-
 .../NativeChatAutocompleteMenus.test.tsx      | 126 +++
 .../NativeChatAutocompleteMenus.tsx           | 325 ++++--
 .../native-chat/NativeChatComposer.test.tsx   |  15 +-
 .../native-chat/NativeChatComposer.tsx        | 207 ++--
 .../native-chat/NativeChatComposerField.tsx   |  61 +-
 .../native-chat/native-chat-agent-commands.ts |   8 -
 .../native-chat-composer-state.test.ts        | 214 +++-
 .../native-chat/native-chat-composer-state.ts | 291 +++---
 .../native-chat/native-chat-picker-items.ts   | 248 +++++
 .../native-chat-skill-discovery-context.ts    | 156 +++
 .../use-native-chat-composer-keydown.test.tsx |  99 ++
 .../use-native-chat-composer-keydown.ts       | 110 +-
 .../use-native-chat-live-session.ts           |  19 +-
 ...use-native-chat-picker-command-dispatch.ts |  97 ++
 .../use-native-chat-picker-state.ts           | 198 ++++
 .../use-native-chat-skills.react.test.tsx     | 144 +++
 .../use-native-chat-skills.test.ts            |  90 +-
 .../native-chat/use-native-chat-skills.ts     | 278 ++++-
 .../use-native-chat-typed-insertion.ts        |  50 +
 .../use-onboarding-flow-persistence.ts        |   2 +-
 .../agent-task-complete-policy.ts             |   3 +-
 .../parked-terminal-byte-watcher.ts           |   3 +-
 .../terminal-pane/pty-delivery-interest.ts    |   2 +-
 .../terminal-parked-tab-watchers.ts           |   1 -
 .../terminal-side-effect-facts-handler.ts     |   4 +-
 .../terminal-view-attributes-publisher.ts     |   4 +-
 .../use-terminal-tab-cold-parking.ts          |   2 +-
 src/renderer/src/i18n/locales/en.json         |  15 +
 src/renderer/src/i18n/locales/es.json         |  17 +-
 src/renderer/src/i18n/locales/ja.json         |  17 +-
 src/renderer/src/i18n/locales/ko.json         |  17 +-
 src/renderer/src/i18n/locales/zh.json         |  17 +-
 src/renderer/src/lib/native-chat-telemetry.ts |  42 +
 src/renderer/src/web/web-preload-api.test.ts  |  29 +
 src/renderer/src/web/web-preload-api.ts       |   6 +-
 src/shared/command-code-output-status.ts      |   3 +-
 src/shared/feature-interaction-catalog.ts     |   4 +-
 src/shared/native-chat-agent-profiles.test.ts |  30 +
 src/shared/native-chat-agent-profiles.ts      |  45 +
 .../native-chat-command-envelope.test.ts      |  96 ++
 src/shared/native-chat-command-envelope.ts    |  63 ++
 src/shared/skill-display-text.ts              |  26 +
 src/shared/skills.ts                          |  60 ++
 src/shared/telemetry-events.ts                |  20 +
 src/shared/terminal-bell-detector.ts          |   4 +-
 src/shared/terminal-output-side-effects.ts    |   4 +-
 src/shared/terminal-side-effect-facts.ts      |   1 -
 src/shared/terminal-view-attributes.ts        |   4 +-
 src/shared/types.ts                           |   9 +-
 104 files changed, 4134 insertions(+), 8531 deletions(-)
 delete mode 100644 docs/reference/2026-06-27-orca-mobile-manual-network-address-design.md
 delete mode 100644 docs/reference/README.md
 delete mode 100644 docs/reference/agent-hook-stdin-lifecycle.md
 delete mode 100644 docs/reference/agent-session-resume-cli-evidence.md
 delete mode 100644 docs/reference/browser-local-https-certificate-trust.md
 delete mode 100644 docs/reference/direct-url-or-file-entry.md
 delete mode 100644 docs/reference/feature-discovery-interaction-tracking.md
 delete mode 100644 docs/reference/feature-education-retention-analytics.md
 delete mode 100644 docs/reference/feature-education-state.md
 delete mode 100644 docs/reference/keyboard-layout-shortcut-dispatch.md
 delete mode 100644 docs/reference/new-user-parallel-work-telemetry.md
 delete mode 100644 docs/reference/opencode-commit-message-stdin.md
 delete mode 100644 docs/reference/plans/2026-06-27-orca-mobile-manual-network-address.md
 delete mode 100644 docs/reference/plans/2026-07-10-ssh-repo-host-reconciliation.md
 delete mode 100644 docs/reference/project-ordering-mode.md
 delete mode 100644 docs/reference/reliability-gates-implementation-plan.md
 delete mode 100644 docs/reference/reliability-pain-points-2026-06-30.md
 delete mode 100644 docs/reference/ssh-gssapi-kerberos.md
 delete mode 100644 docs/reference/ssh-typing-latency-under-relay-load.md
 delete mode 100644 docs/reference/telemetry-availability.md
 delete mode 100644 docs/reference/terminal-cold-park-reveal-cost.md
 delete mode 100644 docs/reference/terminal-hidden-view-parking.md
 delete mode 100644 docs/reference/terminal-model-view-contract.md
 delete mode 100644 docs/reference/terminal-query-authority.md
 delete mode 100644 docs/reference/terminal-session-lifecycle.md
 delete mode 100644 docs/reference/terminal-side-effect-authority.md
 delete mode 100644 docs/reference/terminal-switch-typing-lag-investigation.md
 create mode 100644 src/main/runtime/rpc/methods/skills.test.ts
 create mode 100644 src/main/skills/claude-plugin-skill-sources-wsl.test.ts
 create mode 100644 src/main/skills/claude-plugin-skill-sources-wsl.ts
 create mode 100644 src/main/skills/claude-plugin-skill-sources.test.ts
 create mode 100644 src/main/skills/claude-plugin-skill-sources.ts
 create mode 100644 src/main/skills/skill-discovery-target.ts
 create mode 100644 src/main/skills/skill-discovery-wsl-plugins.test.ts
 create mode 100644 src/main/skills/skill-discovery-wsl.test.ts
 create mode 100644 src/main/skills/skill-discovery-wsl.ts
 create mode 100644 src/renderer/src/components/native-chat/NativeChatAutocompleteMenus.test.tsx
 delete mode 100644 src/renderer/src/components/native-chat/native-chat-agent-commands.ts
 create mode 100644 src/renderer/src/components/native-chat/native-chat-picker-items.ts
 create mode 100644 src/renderer/src/components/native-chat/native-chat-skill-discovery-context.ts
 create mode 100644 src/renderer/src/components/native-chat/use-native-chat-composer-keydown.test.tsx
 create mode 100644 src/renderer/src/components/native-chat/use-native-chat-picker-command-dispatch.ts
 create mode 100644 src/renderer/src/components/native-chat/use-native-chat-picker-state.ts
 create mode 100644 src/renderer/src/components/native-chat/use-native-chat-skills.react.test.tsx
 create mode 100644 src/renderer/src/components/native-chat/use-native-chat-typed-insertion.ts
 create mode 100644 src/shared/native-chat-agent-profiles.test.ts
 create mode 100644 src/shared/native-chat-agent-profiles.ts
 create mode 100644 src/shared/native-chat-command-envelope.test.ts
 create mode 100644 src/shared/native-chat-command-envelope.ts
 create mode 100644 src/shared/skill-display-text.ts

diff --git a/.gitignore b/.gitignore
index 1874a068079..1b3f81e72c0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -77,20 +77,21 @@ design-docs/
 # Machine-local agent hook endpoint files may contain auth tokens.
 /agent-hooks/
 
-# Local-only design/planning docs (not checked in).
-# Durable docs must live in one of the allow-listed locations below.
+# Local-only design/planning docs (not checked in), including most of docs/reference/.
+# Durable docs that should be tracked must live in one of the allow-listed
+# locations below (assets, readme, STYLEGUIDE, mobile terminal shortcut bar,
+# and the tracked reference docs linked from AGENTS.md / README.md).
 docs/**
 !docs/
 !docs/assets/
 !docs/assets/**
 !docs/readme/
 !docs/readme/**
-!docs/reference/
-!docs/reference/**
-# Keep generated React perf scan ledgers local; durable docs still use docs/reference.
-docs/reference/react-performance-audit.md
 !docs/STYLEGUIDE.md
 !docs/mobile-terminal-shortcut-bar.md
+!docs/reference/
+!docs/reference/git-compatibility.md
+!docs/reference/headless-linux-server.md
 
 # Stably CLI (only docs/ are tracked)
 .stably/*
diff --git a/docs/reference/2026-06-27-orca-mobile-manual-network-address-design.md b/docs/reference/2026-06-27-orca-mobile-manual-network-address-design.md
deleted file mode 100644
index fdcc7987af0..00000000000
--- a/docs/reference/2026-06-27-orca-mobile-manual-network-address-design.md
+++ /dev/null
@@ -1,193 +0,0 @@
-# Design: Manual network address entry for Orca desktop mobile pairing
-
-**Date:** 2026-06-27
-**Scope:** Desktop renderer (Settings → Mobile → Network Interface section)
-**Status:** Draft, awaiting user review
-
-## Problem
-
-`src/renderer/src/components/settings/MobileNetworkInterfaceSection.tsx` lets the user pick the network address that gets baked into the mobile-pairing QR code. Today the only options come from `networkInterfaces`, which is the list returned by the main process enumerating OS network interfaces (`en0`, `tailscale0`, etc.). If a user wants a tailnet address that the OS hasn't surfaced yet — a Tailscale MagicDNS hostname, a ZeroTier-assigned address not yet visible to the OS, or a manual LAN IP — they have no way to type one in. The QR ends up pointing at an interface the phone cannot actually reach.
-
-## Decision summary
-
-Replace the inner `Select` of `MobileNetworkInterfaceSection` with a `Popover + Command` ("combobox") pattern modeled on the existing `AgentCombobox`. The popover contains a single `CommandInput` that filters the auto-discovered interfaces above and renders a special "Use …" entry at the bottom of the list whenever the input is a valid IPv4 address or Tailscale MagicDNS hostname. Picking that entry selects a custom address; the trigger shows `<address> (custom)`. Custom addresses are session-scoped (cleared when the settings pane closes).
-
-## Constraints (from `CONTRIBUTING.md` + `AGENTS.md`)
-
-- Cross-platform: code paths must not assume a single platform; the manual entry path itself is platform-neutral.
-- No `helpers`/`utils`/`misc` file names; use concrete names.
-- No `eslint-disable max-lines`; split files instead.
-- Prefer `.ts` over `.d.ts`.
-- UI work follows `docs/STYLEGUIDE.md` and uses shadcn primitives from `src/renderer/src/components/ui/`.
-- The renderer ↔ shared boundary is `src/shared/`; pure logic that may be reused outside the renderer goes there.
-- Comments explain *why*, briefly.
-
-## Files
-
-| Path | Change |
-| --- | --- |
-| `src/shared/network/manual-address.ts` | **New.** Pure `parseManualNetworkAddress(input)` returning a discriminated union. |
-| `src/shared/network/manual-address.test.ts` | **New.** Vitest cases for IPv4 and MagicDNS hostname validation. |
-| `src/renderer/src/components/settings/mobile-network-interface-selection.ts` | Replace `mergeForSelect` with `buildComboboxEntries(interfaces, customAddress)` returning the entry list the UI maps over. |
-| `src/renderer/src/components/settings/mobile-network-interface-selection.test.ts` | Replace `mergeForSelect` tests with `buildComboboxEntries` tests. |
-| `src/renderer/src/components/settings/MobileNetworkInterfaceSection.tsx` | Swap `Select` for `Popover + Command`; add `open`/`query`/`customAddress` state. |
-| `src/renderer/src/components/settings/MobileNetworkInterfaceSection.test.tsx` | **New.** Render tests via `@testing-library/react`. |
-
-No changes to: `mobile/app/pair-scan.tsx`, `MobilePairingQrSection.tsx`, `use-mobile-install-qr.ts`, or any main-process code. The QR generation pipeline already consumes `selectedAddress: string`, which is all the new flow produces.
-
-## Module 1: `parseManualNetworkAddress`
-
-```ts
-// src/shared/network/manual-address.ts
-export type ParseManualAddressResult =
-  | { ok: true; address: string }
-  | { ok: false; error: string }
-
-export function parseManualNetworkAddress(input: string): ParseManualAddressResult
-```
-
-**Rules** (in order):
-
-1. `input.trim()` must be non-empty. Otherwise `{ ok: false, error: 'Enter an IPv4 address or Tailscale MagicDNS hostname' }`.
-2. Reject any input containing whitespace anywhere; reject any input longer than 253 chars (DNS hostname cap).
-3. Accept if it matches the IPv4 grammar (four dotted octets, each 0–255). No leading zeros except for `0` itself.
-4. Accept if it matches the Tailscale MagicDNS hostname grammar:
-   - Regex (case-insensitive): `/^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*\.ts\.net$/`
-5. Otherwise return the same error as (1).
-
-Pure function, no React, no I/O. Unit-testable in isolation.
-
-## Module 2: `buildComboboxEntries`
-
-```ts
-// src/renderer/src/components/settings/mobile-network-interface-selection.ts
-export type MobileNetworkInterface = { name: string; address: string }
-
-export type ComboboxEntry =
-  | { kind: 'interface'; iface: MobileNetworkInterface }
-  | { kind: 'use-query'; address: string }   // only emitted when current query is valid
-
-export function buildComboboxEntries(
-  interfaces: readonly MobileNetworkInterface[],
-  query: string
-): readonly ComboboxEntry[]
-```
-
-**Behavior:**
-
-- Trim `query`; if empty, return only `kind: 'interface'` entries from `interfaces` (no `use-query`).
-- If `query` is non-empty, behavior branches on `parseManualNetworkAddress(query)`:
-  - **Valid query:** skip substring filtering and keep every interface visible (so the user can pivot to an existing interface mid-typing). Emit each as `kind: 'interface'`.
-  - **Invalid query:** filter `interfaces` by case-insensitive substring match on `iface.address` OR `iface.name`. Emit each as `kind: 'interface'`. If the filter yields zero matches, fall back to the full `interfaces` list (so the user always sees the available options, never an empty list mid-typing).
-- After the interface entries, if the query parsed as valid AND no emitted interface has an `address` exactly equal to `parsed.address`, append `{ kind: 'use-query', address: parsed.address }`. (Suppression happens regardless of whether filtering ran, because valid queries skip filtering entirely — the check is against the visible interface list, which for valid queries is the full list.)
-- Order: interface entries first (stable, in input order — either filtered or the full list per the branch above), then the optional `use-query`.
-- The `selectRefreshedNetworkAddress` function is **kept** unchanged — it's still the rule that decides the *initial* `selectedAddress` when no manual entry exists. The UI calls it on mount and on Refresh; afterwards, the combobox owns the selection.
-
-## Module 3: `MobileNetworkInterfaceSection` UI
-
-Outer JSX (header text, description, Generate QR button, Refresh button, Tailnet accordion) is untouched. Only the inner selection control is replaced.
-
-**State:**
-
-```ts
-const [open, setOpen] = useState(false)
-const [query, setQuery] = useState('')
-const [customAddress, setCustomAddress] = useState<string | null>(null)
-```
-
-`customAddress` is the last value the user confirmed via the `use-query` entry. It is the "session-scoped" custom selection that the trigger displays with the `(custom)` label. It is reset when the settings pane unmounts (React unmount handles this automatically; no global store involved).
-
-**Trigger:** A `Button` styled like the existing `SelectTrigger` (`min-w-[220px]`, `size="sm"`). Label uses the same `formatInterfaceLabel` helper:
-
-```ts
-function formatInterfaceLabel(iface: { name: string; address: string }): string {
-  return `${iface.address} (${iface.name})`
-}
-```
-
-For the custom selection the rendered iface is `{ name: 'custom', address: customAddress }`, so the trigger shows `100.64.1.20 (custom)`.
-
-**Popover body:** `Command` containing:
-
-- `CommandInput` with placeholder `Search or type an address…` and `value={query}` / `onValueChange={setQuery}`.
-- `CommandList` containing:
-  - `CommandEmpty` shown only when no interfaces match AND `parseManualNetworkAddress(query)` is invalid (i.e., truly nothing to pick).
-  - One `CommandItem` per `kind: 'interface'` entry from `buildComboboxEntries(networkInterfaces, query)`. `onSelect` calls `onSelectedAddressChange(iface.address)`, `setCustomAddress(null)`, `setQuery('')`, `setOpen(false)`.
-  - Optional visual separator (e.g., `CommandSeparator`) before the `use-query` entry.
-  - One `CommandItem` for `kind: 'use-query'` (only present when query is valid). Label: `Use "<query>"`. `onSelect` calls `onSelectedAddressChange(address)`, `setCustomAddress(address)`, `setQuery('')`, `setOpen(false)`.
-
-**Controlled cmdk selection:** Copy the controlled-`commandValue` pattern from `src/renderer/src/components/agent/AgentCombobox.tsx` (imports `createAgentComboboxCommandState`, `resolveAgentComboboxCommandState`, `updateAgentComboboxCommandValue` from `@/components/agent/agent-combobox-command-state`, plus the `Command`, `CommandEmpty`, `CommandInput`, `CommandItem`, `CommandList` primitives from `@/components/ui/command`) so that hovering the footer doesn't leave a stale highlight on a list item. The exact state shape will be minimal — only one list, no footer-group complexity — so the borrowed helpers are sufficient. No new helpers are introduced in this design.
-
-**Validation feedback:**
-
-- When `query` is non-empty and invalid, render a one-line `text-xs text-statusRed` message directly below the trigger: `"Enter an IPv4 address or Tailscale MagicDNS hostname"`. Use the existing `statusRed` token from the theme to stay style-guide compliant.
-- The `use-query` entry only appears when valid; no need to disable it.
-
-**Refresh button:** Unchanged. Calls `onRefreshNetworkInterfaces`. The combobox re-renders with the new `networkInterfaces`; `query` and `customAddress` are preserved (user might be mid-typing).
-
-**Generate QR button:** Unchanged. Disabled when `!selectedAddress`. No new branches.
-
-## Data flow
-
-```
-networkInterfaces (prop, refreshed by parent)
-        │
-        ▼
-buildComboboxEntries(networkInterfaces, query)
-        │
-        ▼
-CommandList rows
-        │
-        ▼ onSelect
-onSelectedAddressChange(string)  ─► parent re-renders MobilePairingQrSection
-                                  ─► QR is regenerated with new endpoint
-```
-
-The parent of `MobileNetworkInterfaceSection` (whichever Settings tab owns it) already maintains `selectedAddress` and re-passes it down. This design does not change that contract.
-
-## Edge cases
-
-1. **Duplicate manual entry vs. existing interface** — `buildComboboxEntries` suppresses the `use-query` entry whenever the parsed query exactly equals an emitted interface's `address`. For valid queries the visible list is the full interface list (no substring filter runs), so the suppression check is against every interface, not just filtered ones. The user lands on the existing interface row instead of a duplicate.
-2. **OS discovers the manual address later** — If `customAddress === '100.64.1.20'` and a refresh surfaces `100.64.1.20 (tailscale0)`, both are valid options; the user's selection stays. A future iteration may add a "merge" action; out of scope here.
-3. **Empty `networkInterfaces`** — All-interface list is empty. If `query` is also empty, `CommandEmpty` shows. If `query` is valid, the `use-query` entry still appears so the user can type an address even when nothing is enumerated. The trigger shows `No interfaces found`.
-4. **Manual address becomes unreachable at pair time** — Not handled here. The QR generation succeeds; `pair-scan.tsx` already surfaces "Cannot connect — same network?" on failure.
-5. **Closing the popover with an invalid query typed** — `customAddress` and `selectedAddress` are unchanged. Next open starts with an empty `query`.
-
-## Testing
-
-**`src/shared/network/manual-address.test.ts`**
-
-- Accepts: `0.0.0.0`, `255.255.255.255`, `192.168.1.24`, `100.64.1.20`.
-- Rejects: `''`, `'   '`, `'1.2.3'`, `'1.2.3.4.5'`, `'256.0.0.1'`, `'01.02.03.04'` (leading zeros), `'192.168.1.24 '` (trailing space).
-- Accepts MagicDNS: `my-mac.ts.net`, `my-mac.tail-abcd.ts.net`, `a.b.c.d.ts.net`.
-- Rejects MagicDNS: `my-mac` (no `.ts.net`), `my-mac.ts.com`, `-foo.ts.net`, `MY-MAC.TS.NET` is accepted (case-insensitive).
-- Rejects anything > 253 chars; rejects whitespace anywhere.
-- Pure unit tests; no React, no mocks.
-
-**`mobile-network-interface-selection.test.ts`**
-
-- `buildComboboxEntries([LAN, TAILNET], '')` returns two interface entries, no `use-query`.
-- `buildComboboxEntries([LAN, TAILNET], '100')` (invalid query) returns the tailnet interface only — substring filter on `100.64.1.20` matches `100` — and no `use-query` because the query did not parse.
-- `buildComboboxEntries([LAN, TAILNET], '100.64.1.20')` (valid query) returns both interface entries (valid queries skip substring filtering) AND suppresses `use-query` because the parsed address equals an existing interface's `address`.
-- `buildComboboxEntries([LAN, TAILNET], 'my-mac.tail-abcd.ts.net')` (valid query) returns both interface entries (valid queries skip substring filtering) plus a `use-query` with the trimmed address.
-- `buildComboboxEntries([], '1.2.3.4')` returns just `use-query`.
-
-**`MobileNetworkInterfaceSection.test.tsx`** (new)
-
-- Open popover, type `100.64.1.20`, click `Use "100.64.1.20"` → trigger label becomes `100.64.1.20 (custom)`, query clears.
-- Type `not-an-address` → error message renders, no `Use …` row.
-- Type `192.168.1.24` (matches `en0`) → no `Use …` row; clicking the existing interface selects it as `en0`, not `custom`.
-- Trigger label `No interfaces found` shown when `networkInterfaces` is empty and no manual selection.
-
-## Out of scope
-
-- Persistent storage of manual addresses across sessions (user explicitly chose session-scoped).
-- IPv6, port suffixes, non-Tailscale hostnames (rejected by the parser).
-- Mobile-side endpoint override (separate flow; see `mobile/app/pair-scan.tsx`).
-- Main-process changes — the renderer has enough information already.
-
-## Open questions for reviewer
-
-1. Should the error message stay in English-only here, or get the same `translate('auto.…', 'fallback')` wrap as the rest of the section? Recommend: wrap it for consistency, since the rest of the component already uses `translate()`.
-2. Should `customAddress` survive a "Refresh" click? Recommend yes — user might be mid-typing during a VPN reconnect. Confirmed in Edge case 5 above.
-3. Should `CommandInput` accept paste of a multi-line string (e.g. user pastes `orca://pair?code=…`)? Recommend: no special handling; the existing trim+validate treats it as an invalid address and shows the error. Pair-URL paste remains the path through `pair-scan.tsx`.
diff --git a/docs/reference/README.md b/docs/reference/README.md
deleted file mode 100644
index 1ced066c57b..00000000000
--- a/docs/reference/README.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Durable Docs
-
-Keep this folder for versioned reference docs that are meant to survive past a single design or implementation pass.
-
-## What Goes Here
-
-- Stable reference material.
-- Public-facing docs that are not part of the root README.
-- Docs that other checked-in files link to.
-- Telemetry availability notes that dashboard authors need after the original design or implementation branch is gone. See [Telemetry Availability](./telemetry-availability.md).
-- Headless Linux server setup for remote `orca serve` hosts. See [Headless Linux Server](./headless-linux-server.md).
-- Feature education state, interaction tracking, and retention analytics notes that define how contextual tours are persisted and measured. See [Feature Education State](./feature-education-state.md), [Feature Discovery Interaction Tracking](./feature-discovery-interaction-tracking.md), and [Feature Education Retention Analytics](./feature-education-retention-analytics.md).
-- New-user parallel work telemetry notes that define how the parallel-work tour and setup guide should be measured against retention. See [New User Parallel Work Telemetry](./new-user-parallel-work-telemetry.md).
-
-## What Stays Out
-
-Ephemeral design notes, implementation sketches, and planning docs should stay as local Markdown files under `docs/`. They are ignored by default so they do not get checked in accidentally.
diff --git a/docs/reference/agent-hook-stdin-lifecycle.md b/docs/reference/agent-hook-stdin-lifecycle.md
deleted file mode 100644
index 98b404c97ac..00000000000
--- a/docs/reference/agent-hook-stdin-lifecycle.md
+++ /dev/null
@@ -1,204 +0,0 @@
-# Agent Hook Stdin Lifecycle
-
-## Problem
-
-Orca installs agent hooks in global agent configuration, so a managed hook can
-run in an Orca pane, an SSH/WSL runtime, a detached session, or an ordinary
-terminal with no Orca environment. Hook runners write an event payload to the
-child process's stdin after spawn.
-
-The generated scripts currently inspect Orca environment variables before they
-read stdin. When a guard exits first, the hook runner can still be writing to a
-pipe whose reader has closed. POSIX reports `EPIPE`; Windows reports
-`ERROR_BROKEN_PIPE`. The same failure exists when a managed launcher finds that
-its script was removed or is no longer executable.
-
-This is an ownership bug rather than an agent-specific parsing bug. Every
-process that accepts a hook payload owns the read end until it reaches EOF,
-including processes that decide the event is irrelevant.
-
-## Goals
-
-- Make successful hook no-ops consume stdin to EOF on macOS, Linux, Windows,
-  WSL, and SSH hosts.
-- Encode stdin ownership once per platform instead of copying ad hoc drains
-  into every early-exit branch.
-- Preserve payload bytes, hook output, transport timeouts, exit-code behavior,
-  and provider-specific event metadata on the forwarding path.
-- Cover every generated script and missing-script launcher with behavioral
-  regression tests.
-
-## Non-goals
-
-- Do not redesign hook configuration schemas, endpoint discovery, relay HTTP
-  payloads, or event selection.
-- Do not make hook payloads unbounded; existing agent and config timeouts remain
-  the outer lifecycle bound.
-- Do not suppress failures from a script that exists and actually runs. Only a
-  deliberate no-op path exits successfully after consuming stdin.
-- Do not change plugin-based integrations that do not receive piped hook stdin.
-
-## Contract
-
-1. A generated hook script consumes its input exactly once.
-2. No whole-script success exit may occur before that consumption completes.
-3. A launcher that declines to start a missing, unreadable, or non-executable
-   managed script becomes the stdin owner and drains to EOF before returning
-   success.
-4. A launcher propagates the exit code of a managed script that was started.
-5. Output required by an agent protocol may be emitted before stdin is read,
-   but the process must still retain the read end until EOF.
-6. Drain commands are platform-qualified where the platform searches the
-   working directory implicitly.
-
-## Design
-
-### POSIX generated scripts
-
-Capture stdin near the start of the generated script, after any protocol output
-that must be immediate and before endpoint refresh, environment guards, or
-provider-specific skips:
-
-```sh
-payload=$(cat)
-if [ -z "$payload" ]; then
-  exit 0
-fi
-```
-
-Antigravity is the one semantic exception: events without payload still post an
-empty object, so its shared capture policy maps empty input to `{}` instead of
-exiting. Claude's Devin-import skip happens after capture. Command Code captures
-before ancestor/endpoint recovery so its comparatively expensive discovery
-cannot leave the writer blocked.
-
-The common payload-capture fragments live in
-`src/main/agent-hooks/hook-stdin-contract.ts`. Templates choose the required or
-empty-object policy instead of spelling the lifecycle independently.
-
-### Windows batch generated scripts
-
-Batch scripts stream stdin directly into system `curl.exe`; buffering arbitrary
-JSON in an environment variable would corrupt metacharacters and hit size
-limits. Their posting path therefore remains streaming.
-
-All environment guard failures jump to one epilogue:
-
-```bat
-if "%ORCA_AGENT_HOOK_PORT%"=="" goto :orca_agent_hook_drain_stdin
-...
-exit /b 0
-:orca_agent_hook_drain_stdin
-"%SystemRoot%\System32\more.com" >nul 2>nul
-exit /b 0
-```
-
-`more.com` is qualified because Windows searches the current working directory
-for executables. Shared guard and epilogue builders keep labels and commands
-identical across templates. Command Code's existing endpoint-discovery labels
-remain subroutines and the drain epilogue is placed after them.
-
-### PowerShell generated scripts
-
-PowerShell captures with `[Console]::In.ReadToEnd()` before endpoint and
-environment guards. Copilot then parses the captured value only on the posting
-path. This mirrors POSIX ownership without starting an additional process.
-
-### Managed launchers
-
-- POSIX `/bin/sh` launchers require a regular, readable, executable file. The
-  rejected path drains with `cat`; the started-script branch keeps propagating
-  status.
-- Encoded PowerShell launchers use `Test-Path -PathType Leaf`. A missing script
-  calls `[Console]::In.ReadToEnd()` and exits zero; an existing script preserves
-  `$LASTEXITCODE`.
-- Codex's (and Antigravity's/Devin's) cmd fast path is the bare, directly
-  spawnable `.cmd` path. These agents launch the hook command as a program
-  (argv[0]), not through cmd.exe, so the launcher cannot lead with a cmd builtin
-  such as `if` — that argv[0] is unspawnable and fails every hook. A missing
-  script therefore surfaces a normal launch failure on this fast path; only
-  launchers that already require a real interpreter (encoded PowerShell, Git
-  Bash) drain a missing script. Paths cmd.exe cannot invoke verbatim fall back to
-  the encoded PowerShell launcher, which owns stdin for the missing case.
-- Claude's Git Bash fast path uses a POSIX file guard and drain while continuing
-  to execute the `.cmd` directly rather than interpreting it as shell source.
-- Agent-specific direct launchers, including Antigravity event wrappers and
-  Copilot's PowerShell-file command, adopt the same missing-file behavior.
-
-## Data Flow
-
-```text
-hook runner spawns command
-  -> runner writes payload and closes stdin
-  -> launcher starts managed script
-       -> script consumes payload
-       -> refreshes endpoint / evaluates guards
-       -> posts or exits zero
-  -> OR launcher cannot start script
-       -> launcher drains payload
-       -> exits zero
-```
-
-Local, WSL, and SSH installs serialize the same POSIX template. Windows local
-installs use the batch or PowerShell template. No host assumes another host's
-path syntax or shell.
-
-## Failure Semantics
-
-- Missing Orca environment: consume input, exit zero, emit only protocol-required
-  output.
-- Empty payload: consume EOF, then follow the agent's existing empty-event rule.
-- Missing/unreadable/non-executable script: launcher consumes input and exits
-  zero.
-- Endpoint parse/read failure: preserve the existing fail-open behavior after
-  stdin ownership has been satisfied.
-- Existing script returns nonzero: propagate its status; do not drain again or
-  disguise the script failure.
-- Hook runner never closes stdin: the existing config-level timeout terminates
-  the hook. Reading to EOF does not introduce an unbounded lifecycle beyond that
-  already required by normal payload parsing.
-
-## Verification
-
-Add one cross-agent lifecycle suite rather than per-service string-position
-assertions.
-
-- Generate every SSH-compatible POSIX managed script, spawn it with Orca
-  environment removed, write a payload larger than pipe buffers, and assert:
-  exit zero, no stdin error, and required protocol output remains valid.
-- Exercise the Claude Devin skip independently because it is a second no-op
-  condition before endpoint forwarding.
-- Exercise POSIX, encoded PowerShell, cmd.exe, and Git Bash missing-script
-  launchers with a large payload and verify zero write errors.
-- On Windows CI, install and execute every local batch/PowerShell managed script
-  with missing Orca environment and a large payload.
-- Keep structural assertions for shared batch guard/epilogue generation, but do
-  not use substring placement as the primary regression gate.
-- Preserve existing successful-post, timeout, quoting, SSH install, WSL, and
-  nonzero-exit propagation tests.
-
-For a macOS smoke test, launch the real Electron app with an isolated `HOME`
-and `ORCA_DEV_USER_DATA_PATH`, record the launch time, then run:
-
-```sh
-node config/scripts/verify-agent-hook-stdin-lifecycle.mjs \
-  --home "$ISOLATED_HOME" \
-  --min-mtime "$LAUNCH_START_MS"
-```
-
-The verifier rejects stale files, then exercises the 12 POSIX scripts written
-by that Electron launch with a payload larger than pipe buffers. It covers
-successful no-ops, loopback forwarding without payload changes, required JSON
-stdout, Claude's Devin skip, and both branches of the installed missing-script
-launcher.
-
-## Rollout And Compatibility
-
-The generated scripts are rewritten by existing install/update flows, so no
-config migration is needed. Commands use POSIX `sh` primitives, Windows inbox
-executables, and PowerShell features available on supported Windows releases.
-No Git behavior or provider-specific review behavior changes.
-
-The change should ship atomically across templates and launchers. A partial
-rollout would leave global hooks with platform- or agent-dependent pipe safety,
-which is the inconsistency this design removes.
diff --git a/docs/reference/agent-session-resume-cli-evidence.md b/docs/reference/agent-session-resume-cli-evidence.md
deleted file mode 100644
index 5c26f9ecbc6..00000000000
--- a/docs/reference/agent-session-resume-cli-evidence.md
+++ /dev/null
@@ -1,341 +0,0 @@
-# Agent Session Resume Evidence for Sleep/Wake
-
-Date: June 5, 2026
-
-Scope: issue [stablyai/orca#1796](https://github.com/stablyai/orca/issues/1796), current worktree code, installed agent CLIs on this machine, cloned open-source CLI repos under `/tmp/orca-agent-resume-research`, and official provider docs where available.
-
-## Executive conclusion
-
-Orca can implement one-click agent resume on wake, but it cannot use terminal PTY IDs, pane keys, tab IDs, or worktree IDs as the agent session ID. Those are Orca terminal identifiers. The required value is the provider's conversation/session/thread ID.
-
-For several first-tier providers, the exact provider ID is available in hook payloads today, but Orca drops it during normalization:
-
-- Claude: hook payloads include `session_id`; resume command is `claude --resume <session_id>`.
-- Codex: hook runtime sends `session_id`; resume command is `codex resume <session_id>`.
-- Gemini: hook payloads include `session_id`; resume command is `gemini --resume <session_id>`.
-- Antigravity: hook payloads include `conversationId`; resume command is `agy --conversation <conversationId>`.
-- OpenCode: Orca's managed plugin already reads OpenCode `sessionID`; resume command is `opencode --session <sessionID>`.
-- Droid: hook payloads include `session_id`; resume command is `droid --resume <session_id>`.
-- Grok: hook payloads include `sessionId`/`session_id`; resume command is `grok --resume <sessionId>`.
-
-The current blocker is not primarily "how do we resume?" The exact resume action is to spawn a new agent process on wake in the same workspace/pane context using the provider-specific resume command. The blocker is that Orca's current hook event and status types have no durable provider-session field, so the ID is discarded before sleep.
-
-## Current Orca behavior
-
-Issue #1796 is accurate about current behavior. The issue says sleep loses agent type, session ID, last prompt, and resume command because `dropAgentStatusByWorktree` wipes rows before wake can offer resume.
-
-Verified current code path:
-
-- Sleep calls terminal shutdown with identifiers preserved, not provider conversation metadata. See `src/renderer/src/components/sidebar/sleep-worktree-flow.ts`.
-- `shutdownWorktreeTerminals(worktreeId, { keepIdentifiers: true })` preserves terminal IDs/layout wake hints, then calls `dropAgentStatusByWorktree(worktreeId)`. See `src/renderer/src/store/slices/terminals.ts`.
-- `agentStatusByPaneKey` is explicitly documented as "Real-time only - lives in renderer memory, not persisted to disk." See `src/renderer/src/store/slices/agent-status.ts`.
-- `WorkspaceSessionState` persists terminal/browser/editor/SSH state, including terminal layouts and remote relay PTY IDs, but no sleeping-agent records. See `src/shared/types.ts`, `src/renderer/src/lib/workspace-session.ts`, and `src/shared/workspace-session-schema.ts`.
-- `AgentStatusEntry` has `state`, `prompt`, timestamps, `agentType`, pane/tab/worktree attribution, tool previews, assistant preview, and orchestration context. It has no provider session ID or resume command field. See `src/shared/agent-status-types.ts`.
-
-The existing sleep persistence is terminal-resume metadata. The feature needs provider-conversation-resume metadata.
-
-## Hook pipeline gap
-
-The current local and SSH hook wire shapes drop provider IDs:
-
-- `AgentHookEventPayload` in `src/shared/agent-hook-listener.ts` includes pane/tab/worktree, prompt cache fields, hook event name, Claude tool/subagent IDs, and normalized `payload`. It has no provider session ID field.
-- `AgentHookRelayEnvelope` in `src/shared/agent-hook-relay.ts` mirrors that normalized shape for SSH. Its comment states the relay normalizes before sending the envelope. Therefore remote/SSH events lose provider IDs at the relay boundary too unless the new field is added to the shared envelope.
-- `ParsedAgentStatusPayload` in `src/shared/agent-status-types.ts` includes only status fields: `state`, `prompt`, `agentType`, `toolName`, `toolInput`, `lastAssistantMessage`, `interrupted`.
-
-Implementation implication: provider-session metadata must be extracted before normalization completes and must be carried through both the local HTTP path and the SSH relay path.
-
-## Installed CLI versions checked
-
-These exact binaries were available on this machine:
-
-| Agent | Version checked |
-| --- | --- |
-| Claude Code | `2.1.165` |
-| Codex | `codex-cli 0.137.0` |
-| Gemini | `0.44.0` |
-| OpenCode | `1.15.13` |
-| Cursor Agent | `2025.09.18-7ae6800` |
-| Antigravity | `1.0.5` |
-| Droid | `0.122.0` |
-| Grok | `grok 0.2.22 (967574cb117) [stable]` |
-| Pi | `0.72.1` |
-| Amp, Copilot, Command Code, Hermes | Not installed locally |
-
-## Provider matrix
-
-Legend:
-
-- `Exact supported`: exact resume command and exact ID source are both verified.
-- `Resume verified, ID capture missing`: CLI can resume, but current Orca hook path does not expose a durable exact ID.
-- `ID seen, resume not verified`: Orca/source exposes an ID, but no exact resume CLI command was verified.
-- `Out of current hook scope`: Orca has no current hook source for this TUI agent.
-
-| Agent | Resume command evidence | Exact ID source evidence | Current Orca support status |
-| --- | --- | --- | --- |
-| Claude | `claude --resume <session_id>` verified by local `claude --help` and Anthropic CLI docs. | Claude hook docs show hook input includes `session_id` and `transcript_path`; current Orca normalizer drops `session_id`. | Exact supported after adding provider-session metadata extraction. |
-| Codex | `codex resume <session_id>` verified by local help and cloned Codex source `codex-rs/utils/cli/src/resume_command.rs`. | Cloned Codex source `codex-rs/core/src/hook_runtime.rs` sends `session_id` on `SessionStart`, `PreToolUse`, `PermissionRequest`, and `PostToolUse` hook requests. | Exact supported after extraction. |
-| Gemini | `gemini --resume <session_id>` verified by local help and Gemini docs. | Gemini hooks reference says all hooks receive `session_id` and `transcript_path`. | Exact supported after extraction. |
-| Antigravity | `agy --conversation <uuid>` verified by local help and Antigravity docs. | Antigravity hook docs list `conversationId` as the active conversation UUID. | Exact supported after extraction. |
-| OpenCode | `opencode --session <sessionID>` verified by local help, official docs, and cloned OpenCode TUI source. | Orca's OpenCode plugin already reads `event.properties?.sessionID` before posting. | Exact supported after preserving `sessionID`. |
-| Droid | `droid --resume <sessionId>` verified by local help and Factory CLI docs. | Factory hooks reference includes `session_id`; Orca installs Droid hooks and already subscribes to `SessionStart`. | Exact supported after extraction. |
-| Grok | `grok --resume <SESSION_ID>` verified by local help. | Orca already reads `sessionId`/`session_id` in `getGrokChatHistoryPath`, but only to locate chat history. | Exact supported after preserving that same ID. |
-| Cursor | `cursor-agent --resume <chatId>` and `cursor-agent resume` verified by local help and Cursor docs. | Current Orca Cursor hook install deliberately omits `sessionStart`/`sessionEnd`; the subscribed event set does not currently prove a chat ID source. `cursor-agent create-chat` was locally verified to return a UUID, but preallocation for Orca launches still needs an end-to-end test before relying on it. | Resume verified, ID capture missing. |
-| Pi | `pi --session <path|id>`, `pi --resume`, and `pi --continue` verified by local help and Pi docs. | Orca's bundled Pi/OMP extension posts status events but does not include session file path, session UUID, or session name in the status payload. | Resume verified, ID capture missing. |
-| OMP | Same launch family as Pi in Orca. | Orca reuses Pi extension API shape and does not include exact session pointer. | Resume verified by inheritance only from Pi-like CLI contract; exact OMP ID capture missing. |
-| Amp | Orca's managed plugin posts `threadId: event.thread.id`. | Amp is not installed locally, and no exact Amp CLI resume command was verified in this investigation. | ID seen, resume not verified. |
-| Hermes | Orca's managed Hermes plugin selects `session_id` for session/LLM/tool events. | Hermes is not installed locally, and no exact Hermes CLI resume command was verified in this investigation. | ID seen, resume not verified. |
-| Copilot | Orca installs broad Copilot hooks. | Local Copilot CLI not installed; no exact resume command or session ID contract was verified. | Not supported for exact resume yet. |
-| Command Code | Orca installs hooks for `PreToolUse`, `PostToolUse`, and `Stop`. | Local Command Code CLI not installed; no exact resume command or session ID contract was verified. | Not supported for exact resume yet. |
-| openclaude, autohand, aider, goose, kilo, kiro, crush, aug, cline, codebuff, continue, kimi, mistral-vibe, qwen-code, rovo, openclaw | Not investigated to exact-resume standard. | Not in `HOOK_SOURCE_BY_PATHNAME` today. | Out of current hook scope. |
-
-## Exact resume behavior by provider
-
-### Claude
-
-Verified:
-
-- Local `claude --help` shows `--continue`, `--resume [value]`, `--session-id <uuid>`, `--fork-session`, and `--no-session-persistence`.
-- Anthropic CLI docs show `claude -r "<session-id>" "query"` and document `--resume` as resuming a specific session by ID.
-- Claude hooks docs show hook input includes `session_id` and `transcript_path`.
-
-Resume command:
-
-```sh
-claude --resume <session_id>
-```
-
-If Orca stores `lastPromptSummary` separately, it should not pass that summary as a new user prompt by default. The one-click resume action should reopen the prior conversation. Auto-submitting a summary would create a new turn.
-
-### Codex
-
-Verified:
-
-- Local `codex resume --help` accepts `[SESSION_ID] [PROMPT]`, where the session target is a UUID or session name.
-- Cloned Codex source `codex-rs/utils/cli/src/resume_command.rs` formats `codex resume <thread_id>`.
-- Cloned Codex source `codex-rs/core/src/hook_runtime.rs` sends `session_id` on hook requests.
-- Cloned Codex source has tests asserting resumed root sessions use the thread ID as session ID.
-
-Resume command:
-
-```sh
-codex resume <session_id>
-```
-
-Avoid `codex resume --last` for this feature when an exact ID is available. `--last` can resume the wrong conversation if another Codex session ran after the slept workspace.
-
-### Gemini
-
-Verified:
-
-- Local `gemini --help` shows `--resume`, `--session-id`, `--session-file`, and `--list-sessions`.
-- Gemini official hooks reference states all hook input includes `session_id` and `transcript_path`.
-- Gemini official configuration docs describe `--resume [session_id]` and state that a UUID can be supplied.
-
-Resume command:
-
-```sh
-gemini --resume <session_id>
-```
-
-### Antigravity
-
-Verified:
-
-- Local `agy --help` shows `--continue` and `--conversation`.
-- Antigravity conversation docs show `agy --continue` for most recent and `agy --conversation <uuid>` for a specific session.
-- Antigravity hooks docs define common hook input `conversationId`.
-
-Resume command:
-
-```sh
-agy --conversation <conversationId>
-```
-
-### OpenCode
-
-Verified:
-
-- Local `opencode --help` shows `--continue` and `--session`.
-- Official OpenCode docs list `--session` as the session ID to continue.
-- Cloned OpenCode source `packages/opencode/src/cli/cmd/tui/thread.ts` defines `--session` and passes it into TUI args as `sessionID`.
-- Cloned OpenCode source `validate-session.ts` validates the supplied session ID through the OpenCode client.
-- Orca's managed OpenCode plugin reads `event.properties?.sessionID`.
-
-Resume command:
-
-```sh
-opencode --session <sessionID>
-```
-
-### Droid
-
-Verified:
-
-- Local `droid --help` shows `--resume [sessionId]`, `--fork <sessionId>`, and `--cwd`.
-- Factory CLI docs list resume behavior and `droid exec -s <id>` for exec mode.
-- Factory hooks reference says `SessionStart` has a `resume` matcher and hook input includes `session_id`.
-
-Resume command:
-
-```sh
-droid --resume <session_id>
-```
-
-### Grok
-
-Verified:
-
-- Local `grok --help` shows `--resume [<SESSION_ID>]`, `--continue`, `--cwd`, and `--restore-code`.
-- Orca already reads `sessionId`/`session_id` in `getGrokChatHistoryPath`.
-
-Resume command:
-
-```sh
-grok --resume <sessionId>
-```
-
-### Cursor
-
-Verified:
-
-- Local `cursor-agent --help` shows `--resume [chatId]`.
-- Cursor docs show listing prior chats with `cursor-agent ls`, resuming latest with `cursor-agent resume`, and resuming a specific conversation with `cursor-agent --resume="chat-id-here"`.
-- Local help shows `cursor-agent create-chat` creates an empty chat and returns its ID.
-- Running `cursor-agent create-chat` locally returned UUID `1fff2e62-9dd0-4cf3-9d8c-3569fea0aff7`, proving the command can preallocate a chat ID without an initial prompt.
-
-Not verified:
-
-- Current Orca Cursor hook install subscribes to `beforeSubmitPrompt`, `stop`, tool events, approval events, and `afterAgentResponse`, but intentionally does not subscribe to `sessionStart`/`sessionEnd`.
-- I did not verify a current subscribed Cursor hook payload containing `chatId`.
-- I did not run `cursor-agent --resume <chatId> <prompt>` because that would start a real agent turn and may make workspace changes.
-
-Conclusion: exact Cursor resume is CLI-supported, but Orca currently needs either a verified hook payload chat ID or a launch preallocation strategy that is tested end to end.
-
-### Pi and OMP
-
-Verified:
-
-- Local `pi --help` shows `--continue`, `--resume`, `--session <path|id>`, `--fork <path|id>`, `--session-dir`, and `--no-session`.
-- Pi docs state `/resume` opens a picker and `pi -r` opens the same picker at startup.
-- Orca's Pi/OMP extension posts status events from Pi's extension API, but the status events do not include session path, UUID, or session name.
-
-Resume command:
-
-```sh
-pi --session <path-or-id>
-```
-
-Conclusion: exact Pi resume is CLI-supported, but current Orca capture is missing the exact pointer.
-
-## What Orca should store
-
-Store a durable record per sleeping agent pane, not per worktree only:
-
-```ts
-type SleepingAgentSessionRecord = {
-  id: string
-  worktreeId: string
-  tabId?: string
-  paneKey: string
-  connectionId: string | null
-  agentType: TuiAgent
-  providerSession: {
-    kind: 'session_id' | 'conversation_id' | 'thread_id' | 'chat_id' | 'path'
-    value: string
-  }
-  resumeCommand: {
-    argv: string[]
-    cwd?: string
-  }
-  lastPrompt: string
-  lastAssistantMessage?: string
-  capturedAt: number
-  retentionUntil?: number | null
-}
-```
-
-Important constraints:
-
-- `resumeCommand.argv` should be structured argv, not a shell string. This avoids cross-platform quoting bugs.
-- Do not persist a terminal PTY ID as `providerSession.value`.
-- For SSH, `cwd` and the command execute on the remote host. The provider session ID also belongs to the remote CLI's session store.
-- For local workspaces, execute locally in the worktree path.
-- For auto-resume, launch exactly one process per sleeping agent record and guard against double-click/duplicate wake races.
-
-## Provider extraction map
-
-This is the extraction map that is supported by the evidence above:
-
-| Hook source | Provider session field(s) to extract | Resume argv |
-| --- | --- | --- |
-| `claude` | `session_id` | `['claude', '--resume', id]` |
-| `codex` | `session_id` | `['codex', 'resume', id]` |
-| `gemini` | `session_id` | `['gemini', '--resume', id]` |
-| `antigravity` | `conversationId` | `['agy', '--conversation', id]` |
-| `opencode` | `sessionID` | `['opencode', '--session', id]` |
-| `droid` | `session_id` | `['droid', '--resume', id]` |
-| `grok` | `sessionId`, fallback `session_id` | `['grok', '--resume', id]` |
-| `amp` | `threadId` | not enabled until Amp resume command is verified |
-| `hermes` | `session_id` | not enabled until Hermes resume command is verified |
-
-## Required implementation shape
-
-1. Add a provider-session metadata type to shared hook types.
-2. Extract provider session evidence in `parseAgentHookEvent` from raw `hookPayloadRecord` before normalizing to `ParsedAgentStatusPayload`.
-3. Carry it in `AgentHookEventPayload`.
-4. Carry it in `AgentHookRelayEnvelope` so SSH does not lose it.
-5. Store latest provider-session evidence by pane key alongside live agent status.
-6. On sleep, snapshot the live agent status plus latest provider-session evidence before `dropAgentStatusByWorktree`.
-7. Persist sleeping-agent records in `WorkspaceSessionState` and schema.
-8. On wake, render sleeping resumable rows separately from active rows and launch the provider-specific structured argv when the user resumes.
-9. Clear records on explicit worktree removal, not on sleep.
-10. If the provider session no longer exists, let the provider CLI fail and surface that failure without deleting the record until the user dismisses it.
-
-## Open questions that remain genuinely unverified
-
-- Cursor: whether any currently subscribed Cursor hook payload carries `chatId`. If not, the only plausible exact strategy is preallocating a chat with `cursor-agent create-chat` at launch and starting/resuming that known chat. That needs an end-to-end test before productizing.
-- Pi/OMP: whether the extension API can expose the current session file/path/UUID. Current Orca extension does not forward it.
-- Amp: whether the Amp CLI has an exact thread resume command matching `threadId`.
-- Hermes: whether Hermes has an exact session resume CLI command matching `session_id`.
-- Copilot and Command Code: exact resume command and exact hook session field were not verified because the CLIs were not installed locally and no sufficient primary docs/source were found during this pass.
-- Non-hook TUI agents: no exact support should be promised until Orca adds a hook/metadata capture path for each.
-
-## Sources
-
-Local Orca source:
-
-- `src/shared/agent-hook-listener.ts`
-- `src/shared/agent-hook-relay.ts`
-- `src/shared/agent-status-types.ts`
-- `src/shared/types.ts`
-- `src/shared/tui-agent-config.ts`
-- `src/renderer/src/store/slices/terminals.ts`
-- `src/renderer/src/store/slices/agent-status.ts`
-- `src/renderer/src/lib/workspace-session.ts`
-- `src/shared/workspace-session-schema.ts`
-- `src/main/opencode/hook-service.ts`
-- `src/main/amp/hook-service.ts`
-- `src/main/hermes/hook-service.ts`
-- `src/main/pi/agent-status-extension-source.ts`
-- `src/main/cursor/hook-service.ts`
-
-Cloned source:
-
-- `/tmp/orca-agent-resume-research/codex`
-- `/tmp/orca-agent-resume-research/gemini-cli`
-- `/tmp/orca-agent-resume-research/opencode`
-
-Official docs:
-
-- GitHub issue: https://github.com/stablyai/orca/issues/1796
-- Claude CLI reference: https://docs.anthropic.com/en/docs/claude-code/cli-usage
-- Claude hooks reference: https://code.claude.com/docs/en/hooks
-- Gemini hooks reference: https://geminicli.com/docs/hooks/reference/
-- Cursor CLI parameters: https://docs.cursor.com/en/cli/reference/parameters
-- Cursor CLI usage: https://docs.cursor.com/en/cli/using
-- OpenCode CLI docs: https://opencode.ai/docs/cli/
-- Antigravity conversation docs: https://antigravity.google/docs/cli-conversations
-- Antigravity hooks docs: https://www.antigravity.google/docs/hooks
-- Factory Droid hooks reference: https://docs.factory.ai/cli/configuration/hooks-reference
-- Factory Droid CLI reference: https://docs.factory.ai/cli/configuration/cli-reference
-- Pi docs: https://pi.dev/docs/latest/tree
diff --git a/docs/reference/browser-local-https-certificate-trust.md b/docs/reference/browser-local-https-certificate-trust.md
deleted file mode 100644
index d858e030cb9..00000000000
--- a/docs/reference/browser-local-https-certificate-trust.md
+++ /dev/null
@@ -1,926 +0,0 @@
-# Built-in Browser Local HTTPS and Certificate Trust
-
-## Status
-
-Implemented reference design for
-[issue #8454](https://github.com/stablyai/orca/issues/8454).
-
-The branch includes scheme-less local-dev URL classification, certificate-specific
-failure copy, `Try HTTPS`, exact per-WebContents certificate grants,
-`Proceed Anyway (Unsafe)`, local IPC, remote/headless runtime propagation, and
-focused unit and real-Electron coverage. A session-level request gate contains
-Chromium's cached certificate continuation so approval cannot leak to sibling
-tabs, assets, fetches, iframes, or WebSockets. The release gates below remain
-the acceptance contract for Electron upgrades and cross-platform validation.
-
-## Summary
-
-Orca's built-in browser cannot open a local HTTPS development server when the
-server presents an untrusted certificate. A scheme-less local address also
-defaults to HTTP, so entering `localhost:3000` does not discover an HTTPS-only
-server.
-
-This design keeps HTTP as the default for the scheme-less local forms that
-already use it, adds a visible `Try HTTPS` recovery action after a failed local
-HTTP navigation, and adds an explicit `Proceed Anyway (Unsafe)` path for an
-untrusted local HTTPS certificate. Certificate approval is narrow and
-temporary: it is bound to one browser WebContents, one secure endpoint, the
-SHA-256 digest of the exact leaf certificate, and the specific certificate
-error. A secure endpoint treats `https` and its companion `wss` scheme as one
-TLS endpoint but still includes the canonical hostname and effective port. No
-approval state is persisted.
-
-The certificate decision runs in the process that owns the browser page. Local
-desktop webviews use the desktop main process; SSH/headless pages use the remote
-runtime process and expose the decision through runtime RPC.
-
-## Problem
-
-There are three independent behaviors behind the current failure.
-
-1. `normalizeBrowserNavigationUrl` and the tab-create entry classifier prepend
-   `http://` to scheme-less loopback input. Explicit `https://` input is already
-   preserved.
-2. Electron rejects an untrusted server certificate by default. Orca has no
-   `certificate-error` decision flow, so a self-signed development certificate
-   fails with a Chromium certificate error such as
-   `ERR_CERT_AUTHORITY_INVALID (-202)`.
-3. Browser load errors are presented as generic connectivity failures. For a
-   loopback URL, Orca advises the user to check that the server is running even
-   when the server responded and only certificate verification failed.
-
-The same trust limitation exists in the offscreen browser backend used by
-headless and SSH-owned browser pages. A desktop-only handler would fix the
-visible local webview while leaving remote browser ownership inconsistent.
-
-## Goals
-
-- Show certificate-specific failure copy for main-frame certificate errors.
-- Let a user explicitly approve an untrusted local development certificate.
-- Bind approval to the exact browser surface, secure endpoint, leaf certificate
-  digest, and certificate error.
-- Keep approval in memory only and clear it with the owning browser surface.
-- Support both desktop webviews and SSH/headless offscreen browser pages.
-- Give scheme-less local input a discoverable path to HTTPS without silently
-  changing the existing HTTP default.
-- Preserve the current browser sandbox, navigation allowlist, session profiles,
-  and mixed-content policy.
-- Keep browser failure state accurate across event-order races, early webview
-  attachment, reload, stale user actions, and remote latency.
-
-## Non-goals
-
-- Do not automatically trust a self-signed certificate.
-- Do not disable `webSecurity`, enable insecure mixed content, or add
-  `--ignore-certificate-errors`.
-- Do not install a certificate into the operating-system trust store.
-- Do not persist certificate exceptions across app restarts, browser surface
-  recreation, or session-profile changes.
-- Do not default every scheme-less localhost URL to HTTPS.
-- Do not automatically probe HTTPS and then downgrade to HTTP.
-- Do not add a general-purpose exception flow for public websites in v1.
-- Do not make every Chromium certificate error overridable in v1.
-- Do not extend localhost worktree-label proxying to HTTPS targets.
-
-## Product Decisions
-
-### Scheme-less local input continues to use HTTP
-
-`localhost:3000` remains `http://localhost:3000/`. HTTP is still the common
-development-server default, and changing the inference globally would turn
-working HTTP servers into certificate or TLS failures.
-
-When an HTTP navigation to a loopback URL fails, the browser failure overlay
-offers `Try HTTPS`. The action replaces only the URL scheme and preserves the
-host, explicit non-default port, path, query, and fragment. An absent port, or
-an explicit `:80` normalized away by the URL parser, becomes HTTPS's default
-port 443. Orca does not automatically retry because an invisible
-cross-protocol retry would add latency, send an unexpected second request, and
-make downgrade behavior opaque.
-
-Explicit input remains authoritative:
-
-- `http://localhost:3000` stays HTTP.
-- `https://localhost:3000` stays HTTPS.
-- URLs advertised by a workspace process keep their advertised scheme.
-
-The shared browser URL domain becomes the source of truth for the existing
-scheme-less local-dev classification. The tab-create entry classifier calls
-that shared logic instead of keeping a second regular expression and scheme
-rule. This consolidation must not reuse the stricter certificate-eligibility
-predicate: doing so would change current behavior for inputs such as
-`0.0.0.0`, bracketed non-loopback IPv6 addresses, and `.localhost` subdomains.
-
-### V1 approval covers untrusted local authorities only
-
-The first version offers `Proceed Anyway (Unsafe)` only when all of these are
-true:
-
-- the failure is for the main frame;
-- the attempted URL is HTTPS;
-- Electron reports `net::ERR_CERT_AUTHORITY_INVALID`, corresponding to
-  Chromium load error `-202`;
-- the host is an eligible loopback host;
-- the WebContents is a browser surface managed by Orca; and
-- Orca retained a live pending challenge for that browser surface.
-
-Other certificate errors receive accurate copy but no bypass action. In
-particular, v1 does not bypass revoked certificates, malformed certificates,
-weak keys, date errors, or hostname/SAN mismatches. Expanding the allowlist
-requires a separate security decision and dedicated tests.
-
-### Eligible loopback hosts
-
-The shared predicate accepts:
-
-- `localhost`, case-insensitively, with an optional trailing dot;
-- valid subdomains of `.localhost`, also with an optional trailing dot;
-- valid IPv4 addresses in `127.0.0.0/8`; and
-- IPv6 loopback `::1`.
-
-The predicate does not treat `0.0.0.0`, `::`, arbitrary bracketed IPv6
-addresses, private LAN addresses, or a DNS name that merely resolves to
-loopback as certificate-bypass eligible. Wildcard bind addresses should already
-be normalized to a connectable loopback address before navigation.
-
-SSH local forwards are eligible when their browser-facing URL uses one of these
-loopback hosts. Forwarding does not fix certificate names: a URL using
-`127.0.0.1` still needs an IP SAN for `127.0.0.1`; a certificate containing only
-`localhost` will fail with `ERR_CERT_COMMON_NAME_INVALID`, which v1 does not
-bypass. Custom advertised DNS names remain subject to normal system trust in
-v1, even if the name maps to loopback.
-
-### Approval lifetime
-
-An accepted grant is scoped to:
-
-```text
-browser WebContents ID + secure endpoint + leaf SHA-256 digest + error name
-```
-
-The secure endpoint canonicalizes `wss:` to its companion `https:` endpoint and
-includes the normalized hostname and effective port. This lets an approved
-local page load same-endpoint HTTPS assets and its WSS development socket. A
-grant for `https://localhost:3000` does not apply to port 3001, to
-`https://127.0.0.1:3000`, to another browser tab, or to a replacement
-certificate.
-
-Construct the secure endpoint from the parsed request URL: map `https:` and
-`wss:` to `https:`, lowercase the hostname, remove one optional trailing dot,
-use the URL parser's canonical IP representation, and use port 443 when the
-parsed port is empty. Exclude credentials, path, query, and fragment. Reject
-every other scheme.
-
-Accepted grants survive reloads and same-surface navigation back to the exact
-endpoint. They are cleared when the WebContents commits a main-frame navigation
-whose canonical secure endpoint differs from the grant's endpoint (reusing the
-per-WebContents navigation-sequence tracking), when the WebContents is destroyed
-or replaced, the session profile changes, the browser-owning process exits, or
-the app restarts. Binding grant lifetime to the granting main-frame document
-prevents a later top-level document in the same tab — for example a navigation
-to a public site — from silently reusing the loopback grant for a same-endpoint
-iframe, fetch, or WSS subrequest.
-Clearing a grant affects future requests; it cannot retroactively terminate a
-document that already loaded. Grants are not written to settings, browser
-history, workspace session state, or logs.
-
-Chromium caches an accepted `certificate-error` continuation across the
-Electron session partition. Orca therefore retains every endpoint/certificate
-identity accepted in that partition until the browser-owning process exits and
-gates all later HTTPS/WSS requests with `webRequest.onBeforeRequest`. Only the
-WebContents holding the matching grant may reach a cached endpoint. A sibling
-main-frame navigation receives a synthetic challenge for the known identity;
-sibling subresources, fetches, iframes, workers, and WSS requests fail silently.
-
-Because a preflight request gate cannot inspect the certificate that will be
-presented after Chromium's cache is consulted, one endpoint is locked to the
-first accepted untrusted leaf identity for that process lifetime. If that
-endpoint later presents a different untrusted leaf, strict verification rejects
-it and Orca does not offer another bypass until the browser-owning process
-restarts. A replacement system-trusted certificate may load normally; the
-conservative request gate still keeps sibling WebContents blocked until restart.
-
-## User Experience
-
-### Local HTTP failure
-
-For a failed `http://` loopback navigation, keep the current connectivity
-title and recovery hint. Add `Try HTTPS` when an HTTPS form can be constructed.
-
-Example:
-
-```text
-Can't reach localhost:3000
-We couldn't connect to your local server.
-
-[Try HTTPS] [Retry] [Copy Address] [Open Externally]
-```
-
-`Try HTTPS` is the default button because it is the targeted recovery action
-for a local HTTP failure. Keep the existing `Copy Address` recovery action;
-`Retry` uses `outline`, while `Copy Address` and `Open Externally` stay quiet
-secondary actions. `Try HTTPS` does not appear for an already-HTTPS URL or a
-non-eligible host.
-
-### Certificate failure
-
-For `ERR_CERT_AUTHORITY_INVALID (-202)` on an eligible local endpoint, replace
-the generic connectivity content with:
-
-```text
-Connection isn't secure
-Orca doesn't trust the authority that issued the certificate for localhost:3000.
-
-For local development, use a trusted local certificate when possible.
-
-[Open Externally] [Retry] [Copy Address] [Proceed Anyway (Unsafe)]
-```
-
-- `Open Externally` is the default safe recovery action when the URL is
-  reachable from the desktop.
-- When `Open Externally` is unavailable, `Retry` becomes the default action.
-- `Proceed Anyway (Unsafe)` uses `outline`; `Copy Address` stays quiet.
-- `Proceed Anyway (Unsafe)` is always visibly labeled; it is not hidden behind
-  a tooltip.
-- The unsafe action does not use the destructive color. It does not delete or
-  irreversibly mutate user data, and the explicit label carries the warning.
-- Use a muted `ShieldAlert` icon from `lucide-react`; do not add a warning color
-  or new token.
-
-For a remote-owned page whose URL is remote localhost, `Open Externally` is
-hidden because the desktop system browser cannot reach the remote loopback
-address. It remains available for a desktop-owned page or a locally forwarded
-URL.
-
-For certificate errors that v1 does not permit bypassing, show the same
-certificate-specific title with error-specific body text, `Retry`,
-`Copy Address`, and an eligible `Open Externally` action. `Copy Address` remains
-present as a quiet secondary action in every certificate-failure branch,
-eligible or not, so only `Try HTTPS` and `Proceed Anyway (Unsafe)` toggle in and
-out across cases. The same default-action rule applies as for `-202`:
-`Open Externally` is the default when the URL is reachable from the desktop,
-otherwise `Retry` becomes the default. Do not show the local-server-running
-hint.
-
-Use this presentation mapping, inserting the display host into the copy:
-
-| Chromium code           | Body copy                                                                  | Proceed in v1                 |
-| ----------------------- | -------------------------------------------------------------------------- | ----------------------------- |
-| `-200`                  | `The certificate doesn't match {host}.`                                    | No                            |
-| `-201`                  | `The certificate for {host} isn't valid at the current date and time.`     | No                            |
-| `-202`                  | `Orca doesn't trust the authority that issued the certificate for {host}.` | Eligible local endpoints only |
-| Other certificate error | `Orca couldn't verify the certificate for {host}.`                         | No                            |
-
-Keep the raw error name/code available to diagnostics and optional details, but
-do not make users interpret it to understand the primary failure.
-
-### Interaction behavior
-
-- The overlay is persistent inline UI because the user must read and act on the
-  failure; do not use a toast.
-- The overlay does not steal focus when it appears.
-- Actions are reachable by Tab and have visible focus rings.
-- Use `aria-live="polite"`; repeated background failures must not repeatedly
-  announce the same message.
-- Clicking `Proceed Anyway (Unsafe)` disables the action immediately, and also
-  disables the other overlay actions (`Retry`, `Try HTTPS`, `Copy Address`,
-  `Open Externally`) for the duration of the approval round-trip so a stale
-  click cannot race the controller's own `loadURL`. Re-enable them once a
-  success or typed-failure response returns.
-- Map every `proceedCertificate` failure reason to an overlay outcome:
-  `expired`, `changed`, `ineligible`, and `missing` keep the overlay open and
-  show the inline recovery message below; `navigated` shows no message because
-  the overlay for that navigation is already cleared. In every non-success case
-  `Proceed Anyway (Unsafe)` stays disabled until a fresh pending challenge is
-  announced rather than re-enabling on its own.
-- Delay the spinner by 200 ms, matching the style guide's remote-latency rule.
-  After that delay, show the canonical `Loader2` with `Connecting…` and use a
-  fixed button width so the label swap cannot move adjacent actions.
-- If approval expired or the certificate changed, keep the overlay open and
-  show `The certificate changed or the approval expired. Retry the page.`
-- A successful main-frame navigation clears the visible certificate failure.
-
-The UI must use existing `background`, `foreground`, `muted-foreground`,
-`border`, and `ring` tokens plus the existing shadcn `Button` primitive. No new
-color, radius, or shadow tier is required. Do not apply a blanket opacity to
-the overlay's interactive content; use semantic muted text classes so button
-and focus-ring contrast remains intact. Put every new user-visible string
-through the existing localization catalog.
-
-## Architecture
-
-### Ownership
-
-The browser-owning main process is the only authority that can accept a
-certificate challenge.
-
-- Desktop-owned `<webview>` pages are controlled by the desktop main process.
-- Headless/SSH-owned pages are controlled by the remote `orca serve` main
-  process through `OffscreenBrowserBackend`.
-- The renderer only presents a pending challenge and requests approval. It
-  never decides whether a certificate is trusted.
-
-### New main-process controller
-
-Add `src/main/browser/browser-certificate-trust-controller.ts` to manage pending
-certificate challenges, and
-`src/main/browser/browser-certificate-request-guard.ts` to manage grants plus
-the session-level cached-certificate request boundary.
-
-The controller owns:
-
-```ts
-type BrowserCertificateFailure = {
-  challengeId: string
-  browserPageId: string
-  errorCode: number | null
-  error: string
-  origin: string
-  displayHost: string
-  canProceed: boolean
-  observedAt: number
-}
-
-type PendingBrowserCertificateChallenge = {
-  challengeId: string
-  guestWebContentsId: number
-  browserPageId: string | null
-  navigationSequence: number
-  navigationUrl: string
-  origin: string
-  secureEndpoint: string
-  leafCertificateSha256: string
-  errorCode: number | null
-  error: string
-  expiresAt: number
-}
-
-type BrowserCertificateGrant = {
-  guestWebContentsId: number
-  secureEndpoint: string
-  leafCertificateSha256: string
-  error: string
-}
-```
-
-Generate challenge IDs with `randomUUID()`. Compute the certificate identity in
-the browser-owning main process as SHA-256 over the DER bytes of Electron's leaf
-`certificate.data`; do not depend on the undocumented formatting or algorithm
-of `certificate.fingerprint`. Renderer and runtime payloads expose no
-certificate bytes or digest—only the challenge ID, display host, origin, error
-code, error name, `canProceed`, and observation time.
-
-Pending challenges expire after five minutes and are bounded to 32 entries.
-Accepted grants are bounded to 32 entries per browser-owning process and are
-also removed with their WebContents. Bounds evict the oldest entry and notify
-the affected UI when a live challenge is evicted. Ordinary cleanup should keep
-both collections much smaller. Accepted endpoint identities are not evicted:
-Chromium's corresponding cache cannot be cleared narrowly, so forgetting one
-would reopen cross-WebContents access until process exit.
-
-### Certificate event handling
-
-Register exactly one app-level `certificate-error` listener after Electron is
-ready but before either a desktop window or the offscreen backend can create a
-browser page. Every branch must call Electron's callback exactly once; an
-unexpected exception fails closed with `callback(false)`.
-
-Electron supplies the certificate error as a string on this event, while
-`did-fail-load` supplies the Chromium number later. Normalize the string to one
-canonical error name and map only known names to numbers for presentation. An
-unknown name keeps `errorCode: null` and is never bypass-eligible.
-
-For every event:
-
-1. Resolve the WebContents through `BrowserManager` and reject unmanaged,
-   retired, or popup WebContents.
-2. Parse the request URL, normalize its secure endpoint, and compute the leaf
-   certificate SHA-256 digest. Invalid data fails closed.
-3. Compare the normalized error name, endpoint, and digest against an accepted
-   grant for this exact WebContents. On an exact match, first retain the accepted
-   identity in the owning Electron session, then call `event.preventDefault()`
-   and `callback(true)`.
-4. If no grant matches, reject non-main-frame failures without creating a
-   challenge. Subresources and iframes can consume an existing grant but cannot
-   mint one.
-5. For a main-frame failure, record a pending challenge only when the URL and
-   error are eligible. Notify the owning page when its page ID is known, then
-   call `callback(false)`.
-
-Track a monotonically increasing main-frame navigation sequence per
-WebContents. A new main-frame navigation invalidates its pending challenge in
-both main and renderer state before the next certificate decision. Repeated
-identical events within one sequence reuse the challenge ID; a retry or a
-different navigation gets a new ID. This prevents an old button or compromised
-renderer from approving a page the user has already left.
-
-The first failure is always rejected. User approval records a grant and reloads
-the page; the next certificate event is the one that succeeds.
-
-Do not leave Electron's callback pending while waiting for user input. Rejecting
-first gives Orca a normal load-failure lifecycle, avoids an unbounded blocked
-navigation, and makes stale approval cleanup deterministic.
-
-Do not use `session.setCertificateVerifyProc`. It applies to an entire session
-partition, cannot bind a decision to one browser page, and verification results
-can be cached by Chromium's network service.
-
-### Session request gate and Electron upgrade guard
-
-The pinned Electron 43 binary caches `callback(true)` broadly enough that a
-second WebContents in the same partition can load the endpoint without another
-`certificate-error` event. The certificate callback alone is therefore not an
-isolation boundary.
-
-Install exactly one `webRequest.onBeforeRequest` listener on every Orca browser
-session before its first page loads. Electron permits only one listener for this
-event, so the browser session registry owns installation and removal. Once an
-endpoint identity has been accepted, the listener blocks every HTTPS/WSS
-request to that endpoint unless `details.webContentsId` has the matching grant.
-Requests without a WebContents ID, including background/worker traffic, fail
-closed. A blocked main-frame request recreates the challenge and certificate
-load error; other resource types are canceled without replacing the current
-page's overlay.
-
-The real-Electron integration suite must prove same-tab reload, same-endpoint
-HTTPS assets and WSS, different-tab documents and subresources, and
-different-port isolation against the exact Electron version in
-`pnpm-lock.yaml`. Any Electron upgrade that breaks those tests blocks release
-until the design is revised; unit mocks are insufficient.
-
-### BrowserManager integration
-
-Add a narrow BrowserManager query API instead of exposing its internal maps:
-
-```ts
-getManagedBrowserGuestContext(webContentsId: number): {
-  browserPageId: string | null
-  worktreeId: string | null
-  sessionProfileId: string | null
-  owner: 'desktop-webview' | 'offscreen'
-} | null
-```
-
-For guest lifecycle, follow the existing extracted-controller precedent
-(`browser-grab-session-controller.ts`, `browser-guest-ui.ts`,
-`browser-download-destination.ts`), all of which BrowserManager drives by
-calling a plain method on the controller directly from `registerGuest` /
-`unregisterGuest`. Have BrowserManager call
-`certificateTrustController.onGuestRegistered({ browserPageId, webContentsId })`
-and `.onGuestRetired(webContentsId)` from those same bodies, rather than adding a
-new listener/emitter registration API to BrowserManager — there is no such
-pub-sub surface in `src/main/browser` today and this single consumer does not
-warrant introducing one.
-
-`getManagedBrowserGuestContext` must recognize an attached primary desktop
-guest before renderer registration, returning a null page ID, while rejecting
-popup descendants that merely inherited browser policies. It must also
-recognize offscreen pages after `registerOffscreenGuest` and stop recognizing a
-guest immediately when BrowserManager retires or unregisters it. The controller
-re-checks this ownership on every certificate event even if it still has an
-in-memory grant.
-
-An attached desktop webview can encounter a certificate error before its
-document reaches `dom-ready`, which is when BrowserPane currently registers the
-guest. Keep pending challenges keyed by WebContents ID until registration
-supplies the page ID, then flush the failure to the renderer.
-
-BrowserPane should also register idempotently on the webview's `did-attach`
-event, with `dom-ready` retained as a fallback. `registerGuest` should report
-whether the main process accepted the registration so a rare attach-policy race
-can retry at `dom-ready`; the renderer must not cache the WebContents ID as
-registered until it receives `true`.
-
-Offscreen pages already register before `loadURL`, so their page ID is normally
-available when the certificate event fires. Bring their main-frame navigation
-and `did-fail-load` observation under the same BrowserManager lifecycle used by
-desktop guests; the current offscreen loader only logs a rejected `loadURL`, so
-it cannot by itself populate runtime failure snapshots.
-
-### Renderer state
-
-Certificate challenges are transient runtime state and must not be added to
-the persisted `BrowserPage` schema.
-
-Add a transient map to the browser store:
-
-```ts
-browserCertificateFailuresByPageId: Record<string, BrowserCertificateFailure>
-```
-
-The workspace session serializer must omit this map. Clear an entry when:
-
-- the page completes a successful main-frame navigation;
-- the user starts a different navigation;
-- the page or workspace closes;
-- the owning browser WebContents is replaced; or
-- the main process reports that the challenge expired.
-
-The existing `BrowserLoadError` remains the persisted diagnostic source. Add a
-pure Chromium-error classifier for Electron 43's certificate range (`-200`
-through `-219`, excluding the unused values) so certificate failures still
-render accurate copy after restore even when no live challenge exists. A live
-certificate failure's error code takes presentation precedence over a
-synthesized `-1` Chromium-error-page fallback. Independently, only a live,
-matching challenge controls whether `Proceed Anyway (Unsafe)` is enabled.
-
-Use both the page ID and attempted origin when combining the live challenge
-with `BrowserLoadError`. A stale challenge from a prior navigation must never
-add a proceed action to a different failure. Main-process navigation-sequence
-invalidation is the security boundary; renderer cleanup is defense in depth and
-keeps the UI honest.
-
-### Local IPC
-
-Extend the browser preload API with:
-
-```ts
-onCertificateFailureChanged(
-  callback: (event: {
-    browserPageId: string
-    failure: BrowserCertificateFailure | null
-  }) => void
-): () => void
-
-proceedCertificate(args: {
-  browserPageId: string
-  challengeId: string
-}): Promise<
-  | { ok: true }
-  | {
-      ok: false
-      reason: 'expired' | 'changed' | 'ineligible' | 'missing' | 'navigated'
-    }
->
-```
-
-Register the handler with the existing browser IPC group and reuse
-`isTrustedBrowserRenderer`. The main process resolves the page to its current
-WebContents and then consumes the exact pending challenge. Renderer-provided
-origin, error code, or certificate identity are never trusted.
-
-On success, main consumes the challenge, records the grant, and calls
-`loadURL` with the challenge's main-owned `navigationUrl`. It must not use
-`webContents.getURL()`, which may be `chrome-error://chromewebdata/` or a
-previously committed page. It also must not reload if the page's current
-navigation sequence no longer matches the challenge. The renderer does not
-assign `webview.src` as a second side effect.
-
-### Remote runtime RPC
-
-The remote browser owner exposes equivalent behavior through:
-
-```text
-browser.certificate.proceed
-```
-
-with the runtime worktree selector, remote browser page ID, and challenge ID.
-Advertise support through a new `browser.certificate-trust.v1` capability only
-when the runtime has both a browser backend and the certificate controller.
-Keep the method out of the mobile-scope RPC allowlist; it is for an
-authenticated runtime-scope Orca client presenting browser chrome, not a guest
-page or unauthenticated caller.
-
-Extend `RuntimeMobileSessionBrowserTab` compatibly with optional `loadError`
-and `certificateFailure` fields. Both are emitted from live runtime state.
-`loadError` keeps the existing `BrowserPage` last-known diagnostic semantics,
-including workspace persistence; `certificateFailure` is transient and is
-never written to workspace persistence. Controller changes, challenge expiry,
-navigation, and offscreen `did-fail-load` must mark the runtime session snapshot
-dirty so clients do not wait for unrelated state to change. Web clients and
-desktop clients reconcile these fields through the existing remote page-handle
-mapping. Each full snapshot replaces the prior transient certificate failure
-for that page, including clearing it when the field is absent. An older runtime
-without the capability always clears any previously mirrored proceed action.
-
-When the active page has a remote owner, BrowserPane routes approval to that
-environment. It must not call local desktop IPC. If the runtime lacks the new
-capability, the UI still classifies the certificate failure accurately but does
-not render `Proceed Anyway (Unsafe)`. `Try HTTPS`, retry, and other navigation
-actions continue through the existing owner-aware navigation path rather than
-touching a local webview for a remote-owned page.
-
-### Scheme recovery
-
-Add pure functions in the shared browser URL domain:
-
-```ts
-classifySchemeLessLocalDevAddress(rawInput: string): URL | null
-isEligibleLocalCertificateHost(hostname: string): boolean
-toHttpsRecoveryUrl(rawUrl: string): string | null
-```
-
-`classifySchemeLessLocalDevAddress` preserves the exact current HTTP-default
-input set and is shared by address-bar normalization and tab-create entry. It
-is deliberately broader than certificate eligibility.
-
-`isEligibleLocalCertificateHost` accepts a parsed/canonical hostname; normalize
-case and an optional trailing dot and handle the brackets returned by
-`URL.hostname` for IPv6. Validate IPv4 octets and DNS label boundaries instead
-of using a substring or loose suffix check.
-
-`toHttpsRecoveryUrl` returns a value only for an HTTP URL with an eligible
-loopback host. It changes `protocol` to `https:` on a parsed `URL` object and
-preserves credentials, hostname, an explicit non-default port, path, query, and
-fragment. When no port is present, including when the parsed HTTP URL normalized
-`:80` away, the result uses HTTPS's default port 443. It never probes either
-protocol.
-
-Both address-bar submission and tab-create entry use the shared local-address
-classifier. Existing advertised workspace-port URLs remain authoritative and
-require no new probing.
-
-## Security Model
-
-### Invariants
-
-- Default certificate verification remains strict.
-- Only a trusted Orca renderer or authenticated runtime-scope Orca client can
-  request approval.
-- The renderer cannot choose the origin, certificate digest, error,
-  WebContents, or eligibility result.
-- A grant is exact-match only and never applies across tabs, ports,
-  certificates, or browser-owning processes.
-- Session-cached accepted endpoints remain request-gated until process exit,
-  even after their original WebContents or bounded grant is removed.
-- Certificate PEM/DER data and certificate digests do not enter workspace
-  state, history, telemetry, or ordinary logs.
-- Subresource and iframe certificate failures cannot mint an approval action;
-  they can consume an already-approved exact-endpoint grant on the same
-  WebContents.
-- The proceed affordance exists only in Orca chrome; guest content has no
-  direct approval channel. Main-process challenge validation remains the
-  security boundary and does not assume proof of a physical click.
-- A remote client cannot approve a certificate in a different runtime
-  environment.
-- Starting another main-frame navigation invalidates the pending approval in
-  the browser-owning process, not only in renderer state.
-
-### Threat cases
-
-| Threat                                          | Required behavior                                                                                             |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Compromised web page sends forged IPC           | Guest WebContents has no preload API; trusted-renderer check rejects it.                                      |
-| Compromised renderer invents a challenge        | Main consumes only a server-created pending challenge tied to the current page and WebContents.               |
-| Certificate changes after approval              | Leaf-digest mismatch rejects; a second untrusted leaf for that endpoint cannot be bypassed until restart.      |
-| Same host uses a different port                 | Secure-endpoint mismatch rejects.                                                                             |
-| Another tab visits the approved endpoint        | WebContents mismatch rejects.                                                                                 |
-| Approved tab later loads a foreign top document | Grant is invalidated when the main frame navigates to a different endpoint; the new document cannot reuse it. |
-| Challenge is replayed                           | Challenge ID is single-use and expires.                                                                       |
-| User leaves the failed page before clicking     | Navigation-sequence mismatch rejects without reloading the stale URL.                                         |
-| Approved page opens same-endpoint WSS/HMR       | Existing endpoint grant permits it; WSS cannot create a grant by itself.                                      |
-| Public site presents an untrusted certificate   | Host eligibility fails; no proceed action is available.                                                       |
-| Remote page approval is sent locally            | Ownership routing and remote page handles select the browser-owning runtime.                                  |
-| App restarts after approval                     | No persisted grant exists.                                                                                    |
-
-## Failure Handling
-
-- If a certificate event arrives before guest registration, retain it by
-  WebContents ID and flush after registration.
-- If guest registration never completes, expire the pending challenge without
-  notifying unrelated pages.
-- If `Proceed` arrives after expiry, navigation, or WebContents replacement,
-  return a typed failure and leave strict verification in place.
-- If reload fails for a different reason, clear the certificate challenge and
-  present the new load error.
-- If the same rejected challenge fires repeatedly in one navigation, coalesce
-  it without rotating the challenge ID or stacking announcements.
-- If the certificate-error listener cannot parse the URL or leaf certificate,
-  reject normally and do not offer approval.
-- If the remote connection drops during approval, keep the local UI stable and
-  surface the runtime error inline after the latency threshold.
-- If an unexpected controller error occurs, call Electron's callback once with
-  `false`; never leave the request suspended.
-- If an accepted main-frame page later opens a new same-endpoint TLS connection,
-  apply the exact grant to that HTTPS/WSS subrequest. Reject unmatched
-  subrequests silently without replacing the main-frame overlay.
-- If an accepted endpoint presents a different untrusted leaf, reject it without
-  replacing the process-lifetime accepted identity or offering a second bypass.
-
-## Data and Privacy
-
-No migration is required.
-
-Add no new product analytics in v1. Do not record URLs, certificate digests,
-challenge IDs, certificate subjects, or approval results. If product analytics
-becomes a requirement later, define coarse actions in the existing typed
-feature-interaction catalog as a separate reviewed change.
-
-Existing diagnostics may retain the Chromium numerical error code, as they do
-for other browser load failures. Debug logging must contain at most the error
-name, page ID, owner kind, and normalized loopback host class; omit query
-strings, full URLs, and certificate digests.
-
-## Test Plan
-
-### Shared URL tests
-
-- Explicit HTTP and HTTPS local URLs remain unchanged.
-- Scheme-less `localhost`, IPv4 loopback, and IPv6 loopback still normalize to
-  HTTP.
-- Tab-create and address-bar local-address classification stay in parity for
-  the full legacy set, including wildcard and bracketed IPv6 inputs.
-- The broader scheme-less classifier is not accidentally substituted for the
-  stricter certificate-eligibility predicate.
-- `toHttpsRecoveryUrl` preserves host, an explicit non-default port, path,
-  query, and fragment; a URL with no parsed port changes from HTTP's default 80
-  to HTTPS's default 443.
-- `Try HTTPS` is unavailable for HTTPS, file URLs, public hosts, wildcard bind
-  hosts, private LAN hosts, and invalid URLs.
-- Loopback eligibility covers `localhost`, trailing-dot localhost,
-  `.localhost` subdomains with and without a trailing dot, the full valid IPv4
-  127/8 range, and bracketed or unbracketed `::1` after URL parsing.
-- Reject malformed IPv4, arbitrary bracketed IPv6, `0.0.0.0`, `::`, and names
-  that only contain the word `localhost`.
-
-### Main-process trust-controller tests
-
-- Unmanaged, retired, and popup WebContents are rejected without pending
-  challenges.
-- A managed `-202` loopback failure creates one pending challenge and calls
-  `callback(false)`.
-- Every event path calls its callback exactly once; only an accepted grant calls
-  `preventDefault()` and `callback(true)`.
-- The digest is SHA-256 over DER leaf bytes and is stable across PEM formatting.
-- An exact accepted grant covers same-endpoint HTTPS assets, WSS, and iframes on
-  the same WebContents without allowing those requests to mint a challenge.
-- Wrong page, WebContents, origin, port, certificate digest, error type, and
-  challenge ID fail closed.
-- A token is single-use and expires after five minutes.
-- Repeated identical failures in one navigation coalesce; a new navigation
-  invalidates the token and rotates the challenge ID.
-- Approving after navigation returns `navigated` and never reloads the old URL.
-- Approval loads the main-owned challenged URL, not the current Chromium error
-  URL or a renderer-supplied URL.
-- Certificate rotation fails closed and cannot replace the process-lifetime
-  accepted endpoint identity.
-- WebContents destruction removes pending challenges and grants.
-- Bounds evict the oldest pending challenge/grant.
-- Registering a page after an early certificate event flushes the event to the
-  correct renderer.
-- Concurrent tabs and session profiles remain isolated.
-
-### IPC and runtime tests
-
-- Browser certificate IPC rejects untrusted senders and malformed arguments.
-- Renderer-supplied origin or certificate-identity fields are neither accepted
-  nor used.
-- Local approval reloads only the currently mapped guest.
-- Remote approval calls the owning environment's RPC with the remote page ID.
-- Local IPC is not called for a remote-owned page.
-- Mobile-scope runtime clients cannot call the approval method.
-- Older runtimes without `browser.certificate-trust.v1` never show an enabled
-  proceed action.
-- Runtime snapshots carry live load errors and certificate failure state,
-  publish immediately on changes, and do not add certificate challenges to
-  persisted session schemas.
-- A snapshot that omits or clears a challenge removes the mirrored proceed
-  action rather than leaving a stale one behind.
-- Two runtime environments with identical page IDs cannot approve each other's
-  challenge.
-
-### Renderer tests
-
-- `-202` renders certificate-specific copy and no server-running hint.
-- A live certificate challenge still wins when Chromium's error-page fallback
-  produced diagnostic code `-1`.
-- A live eligible challenge renders `Proceed Anyway (Unsafe)`.
-- A restored `-202` load error without a live challenge remains accurate but
-  cannot proceed.
-- Other certificate errors render accurate copy without v1 bypass.
-- Local HTTP failures render `Try HTTPS`; HTTPS and non-loopback failures do not.
-- Starting a new navigation clears stale certificate state.
-- Success clears the overlay.
-- Proceed disables immediately, delays the spinner, and preserves its width.
-- Expired/changed responses show the inline recovery message.
-- Keyboard focus and `aria-live` behavior do not regress the address bar.
-- `Copy Address` remains available, interactive content is not blanket-dimmed,
-  and all new strings are present in the localization catalog.
-
-### Electron integration
-
-Run a local HTTPS server with a generated certificate whose SAN includes
-`localhost` but whose authority is not trusted.
-
-1. `https://localhost:<port>` fails with `-202` and shows certificate copy.
-2. `Proceed Anyway (Unsafe)` reloads and renders the page.
-3. HTTPS assets and a WSS echo/HMR endpoint on the same host and port load after
-   approval; a different-port asset remains blocked.
-4. Reload in the same tab remains allowed without broadening the grant.
-5. A second tab using the same session profile, origin, and certificate remains
-   blocked. This is a release-blocking assertion against the pinned Electron
-   binary, not a mocked controller test.
-6. Navigating away before clicking makes the old challenge unusable and does
-   not pull the tab back to the failed URL.
-7. Replacing the certificate keeps the original tab blocked and offers no
-   second bypass until the browser-owning process restarts.
-8. Closing and recreating the browser surface removes the grant.
-9. Restarting Orca removes the grant.
-10. A system-trusted local certificate loads without an interstitial.
-11. A public/non-loopback untrusted origin has no proceed action.
-12. A hostname/SAN mismatch shows certificate copy but no proceed action.
-13. `localhost:<port>` first attempts HTTP and its failure offers `Try HTTPS`.
-
-Repeat the ownership-sensitive cases for:
-
-- a local desktop webview;
-- an SSH local port forward opened in the desktop browser, using a certificate
-  whose SAN matches the browser-facing forwarded hostname; and
-- a headless/offscreen browser page owned by `orca serve` under Linux/Xvfb.
-
-## Implementation Plan
-
-1. Add the shared scheme-less local classifier, strict certificate-host
-   predicate, secure-endpoint canonicalizer, and HTTPS-recovery function with
-   focused tests.
-2. Consolidate address-bar and tab-create local classification without changing
-   current scheme defaults.
-3. Add BrowserManager ownership/registration/retirement hooks, early
-   `did-attach` registration with a `dom-ready` fallback, and offscreen load
-   failure observation.
-4. Add shared certificate failure/result types and the main-process trust
-   controller, including navigation-sequence invalidation and the app-level
-   listener. Its certificate-event handling resolves ownership through the
-   BrowserManager hooks from step 3, so those must land first.
-5. Add local IPC, preload APIs, and transient renderer state.
-6. Add the certificate-specific classification and copy as new exported
-   functions/branches in the existing `browser-notices.ts` (which already owns
-   load-failure copy via `formatLoadFailureDescription` /
-   `formatLoadFailureRecoveryHint`), and extract only the overlay JSX into a
-   focused `browser-load-failure-overlay.tsx` module instead of growing the
-   already grandfathered `BrowserPane.tsx`; do not add or extend a max-lines
-   disable.
-7. Add certificate-specific and `Try HTTPS` UI, preserve existing recovery
-   actions, and update the localization catalog.
-8. Add the offscreen/runtime capability, live snapshot fields and publication,
-   and approval RPC.
-9. Add unit, IPC, renderer, runtime, and real-Electron integration coverage.
-10. Run formatting, typecheck, lint, localization verification, targeted tests,
-    and cross-platform manual validation.
-
-## Rollout
-
-No feature flag is required for accurate error copy or `Try HTTPS` because both
-paths preserve strict certificate verification.
-
-The proceed path should ship only after desktop and offscreen ownership tests
-pass. If remote runtime support cannot land in the same release, gate the
-button on `browser.certificate-trust.v1`; local desktop support may ship while
-older/remote owners retain accurate error copy and trusted-CA guidance.
-
-Do not close issue #8454 until a packaged build has been validated against a
-real self-signed local HTTPS server. Unit mocks alone do not establish Electron
-certificate-event ordering.
-
-## UI Quality Bar
-
-- Follow `docs/STYLEGUIDE.md` and the adjacent browser failure overlay.
-- Use only existing semantic tokens, shadcn buttons, and lucide icons.
-- Keep the overlay quiet and monochrome; certificate failure must not introduce
-  an amber warning treatment.
-- Copy must distinguish connection, DNS, and certificate failures without
-  claiming more than the Chromium error proves.
-- Buttons must remain on one line at supported pane widths or wrap as one
-  deliberate group without overlap.
-- Validate light/dark mode, macOS/Windows/Linux font metrics, and 200 ms remote
-  latency.
-- Capture review evidence for local HTTP failure, eligible certificate failure,
-  ineligible certificate failure, accepted certificate, and the same browser
-  chrome after recovery.
-
-## Release Gates and Open Risks
-
-- The pinned Electron binary must prove that the session request gate blocks a
-  second tab, sibling HTTPS subresources/WSS, and a second port even when
-  Chromium does not re-emit `certificate-error`. If any isolation assertion
-  fails, omit the proceed path or redesign it around a dedicated ephemeral
-  partition; do not silently widen the grant.
-- Same-endpoint WSS and fresh HTTPS subresource connections must work after
-  approval. A main document that renders while HMR/API traffic remains blocked
-  does not fix the local-development use case.
-- A remote/headless certificate failure must reach the client as both accurate
-  load-error copy and a live challenge. Logging a rejected offscreen `loadURL`
-  is not sufficient.
-- Stale approval must be rejected in the browser-owning process after any new
-  main-frame navigation, including when renderer cleanup or a remote snapshot
-  is delayed.
-- SSH-forward validation must use a certificate whose SAN matches the
-  browser-facing hostname. Authority bypass must not mask a hostname mismatch.
-- The app-level listener and real-certificate tests must pass on macOS, Windows,
-  and Linux/Xvfb. Platform trust-store differences do not justify enabling a
-  broader error allowlist.
-
-## Review Decisions and Follow-ups
-
-### From 2026-07-12 review
-
-- The integrated browser is part of the development workflow (including
-  automation, annotations, and remote ownership), so `Open Externally` and trusted
-  local-certificate guidance remain safer alternatives but do not replace an
-  explicit in-browser decision.
-- V1 intentionally limits approval to `ERR_CERT_AUTHORITY_INVALID (-202)`.
-  Hostname/SAN, date, revoked, and malformed-certificate failures remain blocked;
-  broadening that set requires a separate security review and real-certificate
-  tests.
-- Raw error details remain available to existing diagnostics rather than adding a
-  new disclosure affordance to the quiet recovery overlay.
diff --git a/docs/reference/direct-url-or-file-entry.md b/docs/reference/direct-url-or-file-entry.md
deleted file mode 100644
index 8664965147f..00000000000
--- a/docs/reference/direct-url-or-file-entry.md
+++ /dev/null
@@ -1,146 +0,0 @@
-# Direct URL Or File Entry
-
-## Problem
-
-The tab bar `+` menu only offers fixed actions: terminal, browser, new markdown, and open markdown in `src/renderer/src/components/tab-bar/TabBar.tsx`. It has no text entry point for a user who already knows the URL or file path they want.
-
-Quick Open already loads files for the active worktree through `listRuntimeFiles`, watches the active SSH target status, excludes nested linked worktrees, ranks via `prepareQuickOpenFiles`/`rankQuickOpenFiles`, and opens a selected match with `openFile`. That flow is modal and file-only. It does not live in the `+` menu, does not accept URLs, and cannot create a named new file from the typed query.
-
-The runtime file client has the required local/SSH/runtime primitives, with caveats:
-
-- `listRuntimeFiles(context, { rootPath, excludePaths })` returns relative paths only and can fail for auth, missing provider, ripgrep/size, or stale worktree reasons.
-- `statRuntimePath(context, absolutePath)` is a one-path existence/type check.
-- `createRuntimePath(context, absolutePath, 'file')` creates a single empty file and creates parent directories on the current local, SSH, and runtime-backed paths. Directory creation has separate no-clobber/recursive semantics elsewhere in the file stack, so v1 should create files directly and not expose directory creation as a separate action.
-
-## Goal
-
-Add an entry field at the top of the tab bar `+` menu so users can type:
-
-1. A URL to open an Orca browser tab.
-2. An existing file name/path to open an editor tab.
-3. A new relative file path to create in the active worktree and open.
-
-The behavior must work from both the titlebar tab strip and split-group tab strips. File operations must route through `RuntimeFileOperationArgs`; browser/editor creation must preserve the target group.
-
-## Non-goals
-
-- Do not replace global Quick Open.
-- Do not add persisted launcher state.
-- Do not support standalone directory creation.
-- Do not open external URLs outside Orca.
-- Do not make URL/file detection configurable.
-
-## Design
-
-1. Add a `TabBarCreateEntry` surface inside `TabBar`'s dropdown content above the fixed rows. Use the existing `DropdownMenu` shell, but render the input in a plain form/container, not as a `DropdownMenuItem`; Radix menu item typeahead/selection should not own text input keystrokes. Stop propagation only where required for input typing, and close the dropdown only after a successful submit.
-
-2. Extend `TabBarProps` with a presentation callback that resolves success by returning and failure by throwing:
-
-   ```ts
-   onOpenEntry?: (args: { query: string; worktreeId: string; groupId: string }) => Promise<void>
-   ```
-
-   `TabBar` owns input text, pending state, focus, and dropdown close behavior. It does not create browser tabs or files. `groupId` should be `groupId ?? worktreeId`, matching the existing `resolvedGroupId` fallback.
-
-3. Add a small hook/helper pair instead of duplicating Quick Open logic:
-   - `useTabEntryFileList` loads the file list when the menu opens, using the same inputs as `QuickOpen`: active worktree path, `getConnectionId(worktreeId)`, nested worktree exclusions, and active SSH target status. It cancels stale requests on close or key changes.
-   - A pure classifier/opening helper accepts the query, file-list snapshot, load/error state, worktree metadata, runtime context, and target group.
-
-4. Wire the callback in both owners:
-   - `Terminal.tsx` titlebar fallback resolves the current active worktree and target group the same way `handleNewTab` / `handleNewBrowserTab` do.
-   - `useTabGroupWorkspaceModel` passes its explicit `worktreeId` and `groupId`. Do not rely on ambient `activeGroupIdByWorktree`; split-group `+` can be invoked from an unfocused group.
-
-5. Classify submissions in this order:
-   - Empty after trim: reject inline.
-   - Explicit URL: accept only `http://` and `https://` URLs with a parseable host.
-   - Existing file: once the file-list snapshot is ready, normalize query separators for matching, prefer exact relative-path match, then exact basename match, then `rankQuickOpenFiles`. Before opening, `statRuntimePath` the matched absolute path and reject directories/stale missing matches instead of blindly opening stale list entries.
-   - Host-like URL: only after there is no existing file match, accept strict bare hosts such as `example.com`, `localhost:3000`, or `127.0.0.1:3000`, normalized to `https://...` when no scheme is present. Do not run host-like URL parsing for bare input containing `/` or `\`; `new URL('https://docs/readme.md')` parses, so parsing alone is not a path/file guard. Also reject common source/document filename extensions such as `md`, `ts`, `tsx`, `js`, `jsx`, `json`, `yml`, `yaml`, `toml`, `css`, `html`, and `py` so `README.md` and `src/foo.test.ts` stay file/create candidates.
-   - New file: only after file listing has completed successfully with no existing-file match and no host-like URL match. Treat the query as a relative worktree path. If listing fails, allow explicit `http://` / `https://` URLs only; keep bare host-like inputs blocked because they cannot be disambiguated from files.
-
-6. Validate new file paths before joining:
-   - Reject POSIX absolute paths, Windows drive paths, UNC paths, `~`, empty path, trailing slash, control characters, `.` / `..` segments, and empty raw segments such as `a//b`.
-   - Normalize `\` to `/` only after absolute-path checks, then run segment validation on the normalized path too so traversal like `a\..\b` is still rejected.
-   - Build the absolute path with `joinPath(worktreePath, relativePath)`, then create with `createRuntimePath(context, absolutePath, 'file')`.
-   - On `EEXIST` / "exists", immediately `statRuntimePath`; if it is now a file, open it. If it is a directory, show an error. This handles another window/process winning the create race.
-
-7. Open actions:
-   - URL: in paired web clients, call `createWebRuntimeSessionBrowserTab({ worktreeId, url, targetGroupId: groupId })`; otherwise call `createBrowserTab(worktreeId, url, { activate: true, targetGroupId: groupId, title: url })`. Do not use `openNewBrowserTabInActiveWorkspace`; it only opens the default URL.
-   - Existing/new file: call `openFile(fileInfo, { preview: false, targetGroupId: groupId })` with `language: detectLanguage(relativePath)`. Include the active runtime environment owner as `runtimeEnvironmentId` through the normal `openFile` fallback; do not suppress runtime ownership.
-
-8. Preserve current fixed actions. Existing `New Terminal`, `New Browser Tab`, `New Markdown`, `Open Markdown...`, and quick-launch rows remain below the entry and keep their current shortcuts/icons.
-
-9. Surface errors with existing toast or compact inline text. Keep the dropdown open and preserve the query on validation/runtime errors. For Quick Open's special ripgrep guidance, either extract its parser/UI deliberately or show the cleaned error string; do not duplicate a private parser inline.
-
-## Data Flow
-
-- User opens the `+` menu.
-- `TabBarCreateEntry` focuses the input and `useTabEntryFileList` starts/reuses the menu-local file-list request.
-- User types; the menu may show the best existing-file match or "create file" affordance based on the current snapshot.
-- Enter calls `onOpenEntry({ query, worktreeId, groupId })`.
-- Helper classifies and dispatches:
-  - URL -> browser tab creation with target group.
-  - Existing file -> stat matched path -> `openFile(..., { targetGroupId })`.
-  - New file -> validate -> `createRuntimePath(..., 'file')` -> `openFile(..., { targetGroupId })`.
-- Success closes the dropdown. Failure keeps it open.
-
-## Edge Cases
-
-- No active worktree: disable the entry, including URL entry, because Orca browser tabs are worktree-scoped.
-- SSH/runtime connection not ready: mirror Quick Open by keying the list request on active target status. Non-URL submissions are disabled while loading/connecting to avoid creating a duplicate before the real list arrives.
-- File listing failure: explicit `http://` / `https://` URL submissions still work; file and bare host-like submissions are blocked with the cleaned list error.
-- Ambiguous host-like/file names: an existing listed file wins over bare host-like URL normalization. Explicit `http://` or `https://` input is the escape hatch when the user wants a browser tab despite a file-name collision.
-- File list stale because another window/process added or removed a file: stat before opening matched files; handle create `EEXIST` by stat-and-open.
-- Existing directory match: show an error; do not open as an editor tab.
-- Internal spaces in file paths are allowed. Leading/trailing whitespace is trimmed. Control characters are rejected.
-- Windows-style separators match existing relative paths after normalization, but Windows absolute and UNC paths are rejected for creation.
-- Duplicate Enter while pending is disabled.
-- Browser creation in paired web/mobile clients must use `createWebRuntimeSessionBrowserTab`; local desktop uses `createBrowserTab`.
-- External file-watch invalidation is not required for v1. The menu-local list reloads on each open and on worktree/connection/status changes; successful create can close the menu without mutating the list.
-
-## Test Plan
-
-- Unit test URL classification: schemes, host-like domains, localhost/IP ports, listed file named `example.com` winning over host-like normalization, `README.md`/`readme.md`, `src/foo.test.ts`, `docs/readme.md`, whitespace, and invalid schemes.
-- Unit test path validation: Windows/POSIX absolute paths, UNC, `~`, traversal, empty segments, trailing slash, control characters, spaces, and separator normalization.
-- Unit test existing-file selection with `prepareQuickOpenFiles`/`rankQuickOpenFiles`: exact path beats basename, basename beats fuzzy, stale stat failure blocks open, directory stat blocks open.
-- Unit/helper test new-file creation with `RuntimeFileOperationArgs`, `createRuntimePath`, `statRuntimePath`, EEXIST stat-and-open, and SSH/runtime connection context.
-- Component test `TabBar`: input renders above fixed rows, focuses on open, typing does not close the menu, Enter awaits the callback, success closes, failure preserves text, fixed actions still fire.
-- Store/model tests: titlebar and split-group callbacks pass `targetGroupId`; URL creation uses `createWebRuntimeSessionBrowserTab` in web runtime and `createBrowserTab` otherwise.
-- Electron validation: open URL, open existing file by exact path/name, create nested new file, invalid traversal/absolute path error, and smoke-test existing menu actions.
-
-## UI Quality Bar
-
-- Follow `docs/STYLEGUIDE.md` and existing `DropdownMenu`/`Input` tokens. Do not add custom colors, shadows, or a modal-like panel inside the menu.
-- The input is the first focus target and must not break menu keyboarding.
-- The menu remains compact; loading, match preview, create preview, and error rows fit at the current menu width without overlap or awkward height jumps.
-- Long typed paths scroll/truncate within the input; fixed rows retain icons, shortcuts, hover states, and dense spacing.
-
-## Review Screenshots
-
-Attach evidence to the PR conversation; do not commit images.
-
-1. `+` menu open in a normal workspace with the entry focused and fixed rows visible.
-2. Typed URL state.
-3. Typed existing-file query with visible best match.
-4. Typed new-file path/create state.
-5. Rejected absolute/traversal path error.
-6. Adjacent-feature smoke: fixed menu rows still visible and aligned.
-
-## Rollout
-
-1. Add classifier/path-validation helper and tests.
-2. Add menu-local file-list hook by extracting the reusable Quick Open loading inputs, not by copying private UI-only parsing.
-3. Add `TabBarCreateEntry` and wire it into `TabBar`.
-4. Add titlebar and split-group callbacks.
-5. Add component/store tests.
-6. Run typecheck, lint, targeted tests, UI review, and Electron validation with screenshots.
-
-## Lightweight Eng Review
-
-- Scope: Correctly scoped to the tab bar `+` menu. The implementation must not mutate Quick Open behavior except for extracting reusable search/listing code.
-- Architecture/data flow: Good if `TabBar` stays presentational and all worktree/runtime/group decisions live in owners plus a shared helper. The original `onOpenEntry(query, groupId?)` shape was under-specified; include `worktreeId` and a resolved `groupId`.
-- Failure modes: Must explicitly handle loading list, failed list, stale list, directory matches, create races, no active worktree, no SSH provider yet, and paired web runtime browser creation.
-- Feasibility: Specific URL browser tabs cannot go through `openNewBrowserTabInActiveWorkspace` because that action uses the default URL. `createRuntimePath(..., 'file')` is feasible and creates parent directories for current local/SSH/runtime paths, but do not expose recursive directory creation as a separate v1 behavior.
-- Concurrency/invalidation: A menu-local file list is acceptable if every matched file is statted before open and `EEXIST` is handled on create. No global cache is needed.
-- Performance/blast radius: Listing on menu open has Quick Open's cost class, but the menu is more casually opened than the modal; cancel stale loads and key requests tightly by worktree path, connection, exclusions, and SSH status.
-- Tests: Add pure helper tests first; then component and store/model tests. Electron screenshots are required because Radix menu focus/input behavior is the highest-risk UI part.
-- Residual risk: Host-like URL heuristics can surprise users. Keep the heuristic narrow and prefer file matches over host-like normalization whenever the query contains path separators or matches a listed file.
diff --git a/docs/reference/feature-discovery-interaction-tracking.md b/docs/reference/feature-discovery-interaction-tracking.md
deleted file mode 100644
index a9e9eb1a46f..00000000000
--- a/docs/reference/feature-discovery-interaction-tracking.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# Feature Discovery Interaction Tracking
-
-This document defines local feature-interaction state used to decide whether Orca should still teach a feature with an education surface such as a tour or feature tip.
-
-## Decision
-
-Track first meaningful interaction plus local interaction count for education-targeted features in `PersistedUIState.featureInteractions`.
-
-Do not upload this state as broad analytics. Product analytics should continue to use bounded telemetry events and downstream product events. Local interaction state answers a different question: "Has this user already found enough of this feature that education would be redundant?"
-
-## Rules
-
-- Add a `FeatureInteractionId` in `src/shared/feature-interactions.ts` before using it.
-- Preserve `firstInteractedAt`, and increment `interactionCount` on each later meaningful interaction.
-- Prefer explicit actions over passive visibility.
-- Passive visibility is acceptable only when opening the surface is itself the product use, such as opening Tasks.
-- Record after persisted UI is hydrated by using `recordFeatureInteraction(...)`; it no-ops before hydration.
-- Keep IDs stable. If the meaning changes materially, add a new ID.
-- Do not include user text, paths, URLs, repo names, branch names, hostnames, commands, prompts, or tokens in this state.
-- Old records without `interactionCount` hydrate as `interactionCount: 1`.
-
-## Feature Catalog
-
-| Feature                        | Interaction ID              | Record when                                                                                                                                                                                                            | Education use                                                                                                                        |
-| ------------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| Review notes to agent          | `review-notes`              | A diff or markdown review note is added, or review notes are marked sent to an agent.                                                                                                                                  | Suppress or target a future review-notes tour/tip about adding line notes and sending focused feedback back to an agent.             |
-| AI commit generation           | `ai-commit-generation`      | AI commit-message generation is enabled or an AI commit message is generated.                                                                                                                                          | Suppress future education about AI commit generation. No contextual tour is planned for this branch.                                 |
-| AI PR generation               | `ai-pr-generation`          | AI pull-request title/body/draft fields are generated.                                                                                                                                                                 | Suppress future education about AI PR generation. No contextual tour is planned for this branch.                                     |
-| Floating Workspace             | `floating-workspace`        | The floating workspace opens, is enabled, or is configured.                                                                                                                                                            | Keep the existing Floating Workspace tour, and suppress future education about the global terminal/browser/markdown workspace.       |
-| Quick Commands                 | `quick-commands`            | A terminal quick command is created or edited.                                                                                                                                                                         | Suppress future tips about saved terminal commands. No contextual tour is planned for this branch.                                   |
-| Computer Use setup             | `computer-use-setup`        | Computer Use was selected in legacy onboarding, a permission setup is opened, or the skill setup terminal opens.                                                                                                       | Suppress setup-focused tips once the user has started setup.                                                                         |
-| Computer Use                   | `computer-use`              | A successful `computer.*` runtime method other than capability probing is handled.                                                                                                                                     | Suppress future usage tips once an agent has actually invoked Computer Use.                                                          |
-| Mobile pairing                 | `mobile-pairing`            | Mobile is enabled or a mobile pairing QR/code is generated.                                                                                                                                                            | Suppress future mobile-pairing tips. No contextual tour is planned for this branch.                                                  |
-| Browser element grab           | `browser-grab`              | Browser grab mode is started, an element is copied, or an element screenshot is copied.                                                                                                                                | Suppress future tips about grabbing page context once the user has used the element picker.                                          |
-| Browser annotations            | `browser-annotations`       | Browser annotation mode is started, an annotation is added, browser annotations are copied, or browser annotations are cleared.                                                                                        | Suppress future tips about annotating local pages and sending concrete UI feedback to an agent.                                      |
-| Cookie import                  | `cookie-import`             | Browser cookies are imported from another browser or file, imported through runtime browser profile methods, or default imported cookies are cleared.                                                                  | Suppress future cookie-import education without conflating cookie setup with Agent Browser Use itself.                               |
-| Workspace board actions        | `workspace-board-actions`   | A card/status action, lane configuration, density change, pin drop, or board drag action is used.                                                                                                                      | Keep the existing workspace-board tour, and avoid repeating deeper board-action education after real use.                            |
-| Automation creation            | `automation-created`        | A local automation or external Hermes cron is created.                                                                                                                                                                 | Keep the existing Automations tour, and suppress creation-focused education after the user creates one.                              |
-| Automation run                 | `automation-run`            | A local or external automation run is manually queued.                                                                                                                                                                 | Keep the existing Automations tour, and suppress run/inspection education after the user queues a run.                               |
-| Resource Manager               | `resource-manager`          | The Resource Manager status-bar popover is opened, or its status-bar visibility is toggled in Appearance/status-bar controls.                                                                                          | Suppress future tips about CPU, memory, session, daemon, and workspace disk-scan controls after the user has found the manager.      |
-| Workspace cleanup / disk space | `workspace-cleanup`         | The Space page opens, a workspace disk scan starts/cancels, or cleanup removes scanned workspace rows.                                                                                                                 | Suppress future tips about scanning workspace disk usage and reclaiming old workspace storage.                                       |
-| Ports                          | `ports`                     | The Ports popover opens, the Ports status-bar item is configured, external ports are expanded, or a port is opened/copied/stopped.                                                                                     | Suppress future tips about discovering and acting on workspace ports.                                                                |
-| SSH                            | `ssh`                       | SSH status opens, SSH status-bar visibility changes, a target is added/imported/tested, or an SSH target is connected/disconnected.                                                                                    | Suppress future SSH setup/status tips after the user has interacted with remote target controls.                                     |
-| Provider usage tracking        | `usage-tracking`            | Stats & Usage is opened, Claude/Codex/OpenCode usage analytics are enabled, provider usage details are opened from the status bar, Gemini usage/OAuth is configured, or provider usage status-bar toggles are changed. | Suppress future tips about where to find token/rate-limit/usage tracking for Claude, Codex, Gemini, OpenCode, and related providers. |
-| Claude account switching       | `claude-account-switching`  | A Claude managed account is added, selected, reauthenticated, removed, or selected from the status bar.                                                                                                                | Suppress future tips about using multiple Claude accounts once the user has started account management.                              |
-| Codex account switching        | `codex-account-switching`   | A Codex managed account is added, selected, reauthenticated, removed, or selected from the status bar.                                                                                                                 | Suppress future tips about Codex account switching and restart follow-up flows.                                                      |
-| Workspace tabs                 | `terminal-tabs`             | A workspace tab is created, reordered, renamed, recolored, pinned/unpinned, moved, or closed.                                                                                                                          | Suppress future tips about tab-level workspace organization. These are real workspace tabs, not workspace board cards.               |
-| Split panes                    | `terminal-panes`            | A split group is created from the pane shortcut/menu, a split is resized, or panes are merged.                                                                                                                         | Suppress future tips about pane-level split workflows.                                                                               |
-| Tab splits                     | `tab-splits`                | A workspace tab is moved into another pane or split into a new pane from a tab split/drop action.                                                                                                                      | Suppress future tips about tab-level split workflows separately from pane creation/resizing.                                         |
-| Agent Browser Use setup        | `agent-browser-setup`       | Browser Use was selected in legacy onboarding, enabled in settings, or its setup terminal opens.                                                                                                                       | Suppress future setup tips once the user has started Browser Use setup.                                                              |
-| Agent Browser Use              | `agent-browser-use`         | A successful non-profile `browser.*` runtime method is handled.                                                                                                                                                        | Suppress future usage tips once an agent/runtime has actually driven Orca's browser.                                                 |
-| Agent Orchestration setup      | `agent-orchestration-setup` | Orchestration was selected in legacy onboarding, enabled in settings, or its setup terminal opens.                                                                                                                     | Suppress future setup tips once the user has started Orchestration setup.                                                            |
-| Agent Orchestration            | `agent-orchestration`       | A successful `orchestration.*` runtime method is handled.                                                                                                                                                              | Suppress future usage tips once an agent/runtime has actually used orchestration.                                                    |
-| Notifications                  | `notifications`             | Notifications are enabled in onboarding/settings or a test notification is sent.                                                                                                                                       | Suppress future notification setup tips.                                                                                             |
-
-## Surface-Level Features
-
-Orca also records surface-level interactions for feature areas where opening the surface is itself a meaningful discovery signal:
-
-- `workspace-board`: workspace board opened
-- `workspace-agent-sessions`: workspace terminal surface opened with agent split controls visible
-- `browser`: non-blank browser page viewed
-- `tasks`: Tasks page opened
-- `automations`: Automations page opened
-- `floating-workspace`: floating workspace opened
-- `workspace-creation`: workspace creation flow opened
-
-These remain intentionally separate from action-level IDs such as `workspace-board-actions`, `automation-created`, and `automation-run`. Surface-level IDs answer "has the user entered the feature area?" Action-level IDs answer "has the user performed the deeper workflow?"
diff --git a/docs/reference/feature-education-retention-analytics.md b/docs/reference/feature-education-retention-analytics.md
deleted file mode 100644
index df259f43172..00000000000
--- a/docs/reference/feature-education-retention-analytics.md
+++ /dev/null
@@ -1,182 +0,0 @@
-# Feature Education Retention Analytics
-
-This document records how Orca should use contextual-tour telemetry to evaluate retention and feature adoption.
-
-## Decision
-
-Track only contextual tour exposure and outcome in PostHog:
-
-- `contextual_tour_shown`
-- `contextual_tour_outcome`
-
-Do not add broad telemetry that mirrors local education state, such as "feature interaction first recorded." Local state like `featureInteractions` exists to suppress redundant education on the user's machine; it is not the analytics source of truth.
-
-Feature adoption analysis should join tour cohorts to existing downstream product events. Add new telemetry only for concrete user actions that are not already represented by an existing event.
-
-Automatic contextual tours are limited to new users for this rollout. The local `contextualToursAutoEligible` flag is set once after persisted UI and onboarding state load: users still in first-run onboarding become eligible; users with closed onboarding become ineligible. This avoids surprising existing users with education for surfaces they may already understand.
-
-## Product Questions
-
-Use the data to answer:
-
-- Do users who see contextual tours retain better at D1 and D7?
-- Do completed tours correlate with higher downstream feature adoption than skipped or cancelled tours?
-- Which tours have high skip/cancel rates and should be revised or suppressed?
-- Which tours introduce features that users later use in real workflows?
-
-## Event Contract
-
-### `contextual_tour_shown`
-
-Emitted once when a contextual tour first renders a measured target.
-
-Payload:
-
-- `tour_id`: `workspace-board`, `workspace-agent-sessions`, `browser`, `tasks`, `automations`, or `workspace-creation`
-- `source`: bounded source enum from `src/shared/feature-education-telemetry.ts`
-- `was_feature_previously_interacted`: boolean from local education state at the moment the tour is shown
-
-### `contextual_tour_outcome`
-
-Emitted once when a contextual tour ends.
-
-Payload:
-
-- `tour_id`: same enum as `contextual_tour_shown`
-- `source`: same bounded source enum
-- `outcome`: `completed`, `skipped`, or `cancelled`
-- `steps_seen`: bounded integer
-- `total_steps`: bounded integer
-
-## Dashboard Plan
-
-Create a PostHog dashboard named **Feature Education Retention**.
-
-### Tile: Tour Exposure Volume
-
-Question: How often are tours shown?
-
-Insight:
-
-- Event: `contextual_tour_shown`
-- Breakdown: `tour_id`
-- Visualization: stacked time series by day
-
-Action:
-
-- If volume is unexpectedly high, inspect gating before expanding tours.
-- If a tour is never shown, verify the surface gate and target selectors.
-
-### Tile: Tour Outcome Rate
-
-Question: Which tours are completed, skipped, or cancelled?
-
-Insight:
-
-- Event: `contextual_tour_outcome`
-- Breakdown: `tour_id` and `outcome`
-- Visualization: stacked bar or table
-
-Action:
-
-- High skipped rate means copy, timing, or audience targeting needs revision.
-- High cancelled rate means UI state is likely interrupting tours or targets are disappearing.
-
-### Tile: Median Steps Seen
-
-Question: How far do users get before leaving?
-
-Insight:
-
-- Event: `contextual_tour_outcome`
-- Metric: median `steps_seen`
-- Breakdown: `tour_id`
-- Optional derived ratio: `steps_seen / total_steps`
-
-Action:
-
-- If most users see only step 1, shorten or reprioritize the tour.
-- If later steps are rarely reached, do not rely on those steps for critical education.
-
-### Tile: D1/D7 Retention By Tour Outcome
-
-Question: Does tour status correlate with retention?
-
-Insight:
-
-- Cohort A: users with `contextual_tour_outcome` where `outcome = completed`
-- Cohort B: users with `contextual_tour_outcome` where `outcome = skipped`
-- Cohort C: users with `contextual_tour_outcome` where `outcome = cancelled`
-- Cohort D: users with no `contextual_tour_shown`
-- Retention: return to `app_opened` on day 1 and day 7
-- Breakdown: `tour_id` where PostHog supports it, otherwise build one insight per tour
-
-Action:
-
-- Keep or expand tours whose completed cohort outperforms skipped/no-tour cohorts.
-- Rework or suppress tours whose shown cohort underperforms no-tour users.
-
-### Tile: Downstream Feature Adoption By Tour
-
-Question: Do users later use the feature taught by the tour?
-
-Build funnels from tour events to real product events:
-
-- `tasks`: `contextual_tour_outcome` -> workspace creation from task-linked flows where existing telemetry exposes the source; if the current event is insufficient, add a targeted task-started-workspace event.
-- `workspace-creation`: `contextual_tour_outcome` -> `workspace_created`
-- `browser`: `contextual_tour_outcome` -> browser grab/annotation events. If these do not exist, add targeted events for the concrete actions, not a broad feature-interaction event.
-- `automations`: `contextual_tour_outcome` -> automation creation/run events. If these do not exist, add targeted events for create/run.
-- `workspace-board`: `contextual_tour_outcome` -> board-specific actions such as card moved/status changed. If these do not exist, add targeted events for those actions.
-- `workspace-agent-sessions`: `contextual_tour_outcome` -> terminal pane split actions and later workspace creation.
-
-Recommended funnel shape:
-
-1. `contextual_tour_shown` filtered by `tour_id`
-2. `contextual_tour_outcome` filtered by same `tour_id`, broken down by `outcome`
-3. Downstream action event within 1 day and 7 days
-
-Action:
-
-- If completion improves downstream action conversion, keep the tour.
-- If shown-but-skipped users still convert, the surface may be discoverable without a tour.
-- If no downstream event exists, add the smallest action-specific telemetry needed for that feature.
-
-## Telemetry Cost Rule
-
-At 1,000 DAU, this PR should emit at most:
-
-- One `contextual_tour_shown` per shown tour
-- One `contextual_tour_outcome` per shown tour
-- Currently one contextual tour per session
-
-Expected launch volume: under 2,000 events/day at 1,000 DAU and lower for mature cohorts because existing users are not auto-eligible and `contextualToursSeenIds` fills in for eligible new users.
-
-Do not add recurring, render-loop, polling, passive snapshot, or local-state-mirror events for this analysis.
-
-## Privacy Rule
-
-Payloads must remain low-cardinality and bounded. Do not include:
-
-- prompts
-- commands
-- paths
-- URLs
-- hostnames
-- repo names
-- branch names
-- user-entered text
-- raw errors
-- tokens or IDs beyond the existing anonymous telemetry identity
-
-## Existing Users
-
-Existing users should not receive automatic contextual tours from this rollout. We cannot reliably know whether they have already viewed or used every covered surface, so the least surprising default is to leave them alone and measure this launch on new-user cohorts.
-
-Implementation:
-
-- `contextualToursAutoEligible: false` for profiles whose onboarding is already closed when the rollout first runs
-- `contextualToursAutoEligible: true` for profiles still in first-run onboarding when the rollout first runs
-- automatic tour requests require `contextualToursAutoEligible === true`
-- local `featureInteractions` still records supported surface entry for all users after UI hydration
-
-For existing-user analysis, compare users by actual tour exposure and outcome only when they have exposure. Most existing users should fall into the no-tour baseline for this PR. If a later release adds manual tour entry points or truly new feature education, evaluate that release separately instead of reusing this rollout's eligibility rule.
diff --git a/docs/reference/feature-education-state.md b/docs/reference/feature-education-state.md
deleted file mode 100644
index 950d4823d48..00000000000
--- a/docs/reference/feature-education-state.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# Feature Education State
-
-Orca uses local persisted UI state to decide which education surfaces should appear for a user. Keep these concepts separate; they answer different questions and should not be collapsed into one flag.
-
-For the feature-interaction catalog, see [`feature-discovery-interaction-tracking.md`](./feature-discovery-interaction-tracking.md). For retention analysis and dashboard construction, see [`feature-education-retention-analytics.md`](./feature-education-retention-analytics.md).
-
-## State Types
-
-`featureTipsSeenIds` answers: "Has Orca already surfaced this tip?"
-
-Set this when a restart tip is opened, dismissed, or acted on. It prevents the same tip from reappearing after restart, crash, or dismissal. It does not mean the user used the feature.
-
-`contextualToursSeenIds` answers: "Has Orca already surfaced this contextual tour?"
-
-Set this after a tour has rendered a measured target, or when the user skips/completes the tour. It prevents the same tour from showing again. It does not mean the user used the feature.
-
-`contextualToursAutoEligible` answers: "May this profile receive automatic contextual tours from this rollout?"
-
-Missing means Orca has not classified the profile yet. On first hydrated launch after this change, the renderer sets it once:
-
-- `true` when first-run onboarding is still open, which covers new users from this rollout forward
-- `false` when onboarding is already closed, which covers existing users
-
-Automatic contextual tours require this flag to be `true`. Existing users still get local feature interaction state recorded when they enter supported surfaces, but they are not auto-toured by this rollout.
-
-`featureInteractions` answers: "Has the user actually interacted with this feature?"
-
-This is the product-state signal for already-discovered features. It lives in `PersistedUIState.featureInteractions`, keyed by `FeatureInteractionId`, and stores the first local interaction timestamp plus a local interaction count:
-
-```ts
-{
-  tasks: {
-    firstInteractedAt: 1716500000000,
-    interactionCount: 3
-  }
-}
-```
-
-Use this to suppress tips or tours that would teach a feature the user has already found on their own.
-
-## Rules
-
-- Define every trackable feature in `src/shared/feature-interactions.ts`.
-- The `interaction` text must clearly state what counts as "used." Avoid vague labels like "seen" or "visited" unless passive visibility is truly the intended signal.
-- Record only the first interaction. Repeated opens should not churn the user-data file.
-- Record interactions only after persisted UI state is hydrated, so startup defaults cannot overwrite real user data.
-- Do not rename or reuse ids. If semantics change materially, add a new id and leave the old one readable.
-- Unknown or malformed persisted ids are ignored during hydration for forward/backward compatibility.
-- This state is local product state, not telemetry. Analytics should use the bounded feature-education telemetry events (`contextual_tour_shown` and `contextual_tour_outcome`) plus existing downstream action events, rather than reading or uploading the persisted state blob.
-- Automatic contextual tours are new-user-only for this rollout. Do not reset `contextualToursAutoEligible` for existing users unless the product decision changes for a later release.
-
-## Adding A Tip
-
-When a tip should not show after the user has already used the feature, add the relevant interaction id to the tip definition:
-
-```ts
-{
-  id: 'voice-dictation',
-  completedByFeatureInteractions: ['voice-dictation']
-}
-```
-
-Then make sure the feature records its interaction at the meaningful product moment. For example, voice dictation records only after a session reaches `listening`, not when the settings pane opens.
-
-## Adding A Tour
-
-Tours still use `contextualToursSeenIds` to avoid repeating the same tour. If opening or using the toured surface should also suppress future education for that feature, call `recordFeatureInteraction(featureId)` from the surface's meaningful interaction point.
-
-For contextual tours in this branch, `useContextualTour(...)` records the matching interaction once the surface is enabled and persisted UI is ready. Surface-specific gates decide what "enabled" means; for example, the browser tour waits for a non-blank local browser page.
-
-## Test Profiles
-
-Completed-onboarding E2E profiles should preseed both education exposure and feature interaction state. That keeps first-run education from covering unrelated UI under test while preserving production behavior for real profiles.
-
-Profiles that model existing users should also set `contextualToursAutoEligible: false`; profiles that explicitly exercise contextual tours can set it to `true`.
diff --git a/docs/reference/keyboard-layout-shortcut-dispatch.md b/docs/reference/keyboard-layout-shortcut-dispatch.md
deleted file mode 100644
index 33a2a4d867e..00000000000
--- a/docs/reference/keyboard-layout-shortcut-dispatch.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Keyboard Layout Shortcut Dispatch
-
-## Problem
-
-Keyboard shortcuts must follow the user's active keyboard layout. A shortcut like `Cmd+W`
-means "Command plus the key that produces `w`", not "Command plus the physical key labeled
-W on a US keyboard." Physical-position matching breaks Dvorak, Colemak, AZERTY, JIS, and
-other non-US layouts, and it also makes user keybinding overrides impossible to reason about.
-
-## Decision
-
-Orca app shortcuts dispatch by logical key by default.
-
-The shared keybinding registry in `src/shared/keybindings.ts` is the source of truth for
-app commands, configurable commands, shortcut recording, labels, conflict detection, browser
-guest forwarding, and terminal pane commands. Code handling a user-facing app command must
-call `keybindingMatchesAction`, `keybindingMatchesInput`, or a policy function built on those
-helpers.
-
-Physical `KeyboardEvent.code` may only decide a shortcut when the key is layout-invariant or
-the platform cannot provide a real logical key.
-
-Allowed physical-code uses:
-
-- Modifier key release tracking, such as left/right Control release for held `Ctrl+Tab`.
-- Layout-invariant keys, such as arrows, Tab, Enter, Escape, Backspace, Delete, Insert,
-  PageUp, PageDown, and explicit numpad bindings.
-- Dead, unidentified, or missing logical keys where `KeyboardEvent.key` cannot describe the
-  produced key.
-- Terminal byte encoding where the intent is a physical terminal escape sequence rather than
-  an Orca command.
-
-Disallowed physical-code uses:
-
-- Letter shortcuts for app actions.
-- Punctuation shortcuts for app actions when `KeyboardEvent.key` reports the produced
-  punctuation.
-- Clipboard shortcuts that are exposed as app or terminal UI commands.
-- Hardcoded undo/redo/new/close/copy/paste handling outside the shared registry.
-
-## Terminal Boundary
-
-Terminal handling has two different jobs:
-
-1. Orca commands that act on terminal UI, such as copy selection, paste, search, clear,
-   pane focus, split, and close. These are app shortcuts and must be layout-aware.
-2. Bytes sent to the shell, such as readline escapes and Option-as-Alt sequences. These may
-   use physical key positions when terminal compatibility requires it.
-
-This boundary is intentional. It lets non-US layouts use Orca commands naturally while
-preserving shell behavior where users expect physical terminal-control sequences.
-
-## Regression Requirements
-
-Shortcut tests must cover both directions of a non-QWERTY swap:
-
-- The key that produces the configured logical character must match, even if its physical code
-  differs.
-- The physical US key must not match when it produces a different logical character.
-
-Tests must also cover intentional exceptions:
-
-- Dead or missing key fallback.
-- Shifted punctuation aliases.
-- Numpad-specific bindings.
-- Terminal byte-encoding paths that intentionally use physical codes.
diff --git a/docs/reference/new-user-parallel-work-telemetry.md b/docs/reference/new-user-parallel-work-telemetry.md
deleted file mode 100644
index abe64e6f881..00000000000
--- a/docs/reference/new-user-parallel-work-telemetry.md
+++ /dev/null
@@ -1,245 +0,0 @@
-# New User Parallel Work Telemetry
-
-## Goal
-
-Measure whether the new parallel-work tours and the eight-step `Getting started` flow improve new-user activation and retention.
-
-The product question is not "did the tour render?" It is:
-
-- Did users who were eligible for the new parallel-work education retain better at D1, D3, and D7?
-- Did seeing or completing the tour increase the behaviors that the activation plan expects: terminal splits, two agents in one worktree, two worktrees within 72 hours, task/review source use, setup script configuration, notifications, and agent capability setup?
-- Where do users leave the education flow: before the tour starts, during a tour, after skipping a tour, after opening `Getting started`, or partway through the eight setup steps?
-
-This document implements the telemetry portion of [`new-user-parallel-work-activation.md`](./new-user-parallel-work-activation.md).
-
-Validation mode: the current branch logs the would-be event name and payload to the console instead of sending these new feature-education events through product telemetry. Keep the logged payload shape identical to the event payloads below so reviewers can verify what would be emitted before product telemetry is re-enabled.
-
-## Product Decisions
-
-Question: Should Orca keep, revise, or disable the automatic `workspace-agent-sessions` tour for new users?
-
-Decision owner/use: Product and growth review the retention and activation read after rollout. If exposed users retain and activate better than eligible-but-unexposed users, keep or expand the tour. If exposed users underperform or skip/cancel heavily, revise copy, timing, or gating.
-
-Question: Which part of the education flow is weak?
-
-Decision owner/use: If users usually stop on a specific tour step, revise that step or shorten the tour. If users complete the tour but do not progress through `Getting started`, improve the handoff. If users open `Getting started` but stall before the first two parallel-work steps, revise the checklist actions.
-
-Dashboard: `New User Parallel Work Activation`
-
-Action: Use the dashboard to decide whether to continue rollout, adjust the tour, reorder checklist steps, or add missing downstream action telemetry.
-
-## Existing Telemetry To Reuse
-
-Keep the existing contextual-tour events as the primary tour exposure and outcome contract:
-
-- `contextual_tour_shown`
-- `contextual_tour_outcome`
-
-`contextual_tour_outcome` already carries:
-
-- `tour_id`
-- `source`
-- `outcome`: `completed`, `skipped`, or `cancelled`
-- `steps_seen`
-- `total_steps`
-
-For the current branch, `workspace-agent-sessions` is the activation tour. Its source should distinguish automatic first-workspace exposure from checklist-triggered education:
-
-- `workspace_agent_sessions_visible` for automatic surface-driven tour exposure
-- `setup_guide_parallel_work` for the explicit checklist `Try it out` path
-
-Do not add one telemetry event per tour opportunity or step render. Opportunity checks are driven by local UI eligibility, retries, target visibility, modal state, and session guards; emitting every "not shown" reason would turn tour gating into passive eligibility telemetry. One shown event plus one outcome event keeps volume low and still answers whether users saw, skipped, cancelled, completed, and how far they got.
-
-## Tour Depth Improvement
-
-Add stable step-depth fields to `contextual_tour_outcome` so the analysis can tell whether a user reached the actual late steps, not only how many visible steps happened to render.
-
-Additive schema fields:
-
-- `furthest_step_index`: integer `1..8`
-- `defined_step_count`: integer `1..8`
-
-Keep `steps_seen` and `total_steps`:
-
-- `steps_seen` remains the count of unique rendered visible steps.
-- `total_steps` remains the visible-step denominator for the user session.
-- `furthest_step_index` is the highest 1-based index from the tour definition reached by the user.
-- `defined_step_count` is the number of steps defined for that tour, regardless of target skipping.
-
-This handles target-skipping correctly. A user who sees tour steps 1, 4, and 5 should report `steps_seen: 3`, `total_steps: 3`, `furthest_step_index: 5`, and `defined_step_count: 5`.
-
-## New Setup Guide Events
-
-The eight `Getting started` steps need a small telemetry contract because they are not contextual-tour steps. They are durable activation milestones.
-
-### `setup_guide_opened`
-
-Emit once when the modal opens.
-
-Payload:
-
-- `source`: `sidebar`, `contextual_tour`, `settings`, `feature_wall`, `help_menu`, or `unknown`
-- `initial_completed_count`: integer `0..8`
-- `total_steps`: integer `8`
-- `first_incomplete_step_id`: one of the eight setup step ids, or `none`
-
-Use:
-
-- Measures whether users reach the checklist after the tour.
-- Establishes starting depth so existing progress does not look like checklist-driven progress.
-
-### `setup_guide_closed`
-
-Emit once when a shown setup guide closes or unmounts.
-
-Payload:
-
-- `source`: same value used by `setup_guide_opened`
-- `outcome`: `completed`, `dismissed`, or `interrupted`
-- `initial_completed_count`: integer `0..8`
-- `final_completed_count`: integer `0..8`
-- `total_steps`: integer `8`
-- `active_step_id`: one of the eight setup step ids, or `none`
-
-Use:
-
-- Measures whether users treat the checklist as useful or dismiss it without progress.
-- Gives a compact "how far through the 8 steps" read without uploading a progress snapshot on every render.
-
-### `setup_guide_step_completed`
-
-Emit once per setup step when that step first transitions from incomplete to complete while the setup guide is visible. Hidden/background progress is persisted locally as baseline state but not emitted, because async setup refresh cannot reliably distinguish old completions from new user action.
-
-Payload:
-
-- `step_id`: one of `two-worktrees`, `browser`, `notifications`, `default-agent`, `task-sources`, `setup-script`, `add-two-repos`, `agent-capabilities`
-- `section_id`: `parallel-work` or `setup`
-- `completed_count`: integer `1..8`
-- `total_steps`: integer `8`
-- `setup_guide_visible`: boolean
-
-Use:
-
-- Measures the in-guide depth through the eight steps without backfilling old setup state on launch.
-- Lets retention analysis bucket users by `0`, `1`, `2`, `3-4`, `5-7`, and `8` completed setup steps.
-
-Implementation detail: persist a local set of emitted setup-guide step ids, similar in spirit to `contextualToursSeenIds`, so inferred durable state does not re-emit on every launch. Do not upload that local set.
-
-## Downstream Activation Events
-
-Reuse existing downstream events whenever possible:
-
-- `workspace_created` for worktree/workspace creation depth
-- `agent_started` for agent activity and follow-up actions
-- `settings_changed` for supported settings such as notifications
-- setup script prompt events for setup-script configuration paths
-- task/source-specific events where they already exist
-
-Add action-specific downstream telemetry only when the retention question cannot be answered from existing events. The first likely gap is terminal splitting. The activation plan names first-session terminal split as a primary success criterion, but the branch currently records `terminal-pane-split` as local feature-interaction state, not product telemetry.
-
-If no existing telemetry captures terminal split, add:
-
-### `terminal_pane_split`
-
-Emit when a split succeeds, capped to the first split for each `source` + `direction` pair per UTC day on the local profile. This keeps the event useful for activation cohorts without making heavy terminal users dominate telemetry volume.
-
-Payload:
-
-- `source`: `contextual_tour`, `keyboard`, `context_menu`, `command`, `unknown`
-- `direction`: `vertical` or `horizontal`
-
-Do not include pane ids, worktree ids, paths, commands, prompts, repo names, branch names, hostnames, or terminal content.
-
-## Retention Analysis
-
-Use new-user eligibility as the least-biased baseline:
-
-1. Eligible baseline: new-user cohorts represented by first-run/onboarding events rather than uploading local tour eligibility state.
-2. Exposed cohort: users with `contextual_tour_shown` where `tour_id = workspace-agent-sessions`.
-3. Tour outcome cohorts: users with `contextual_tour_outcome` broken down by `outcome`.
-4. Tour depth cohorts: `furthest_step_index / defined_step_count` and `steps_seen / total_steps`.
-5. Checklist depth cohorts: latest `setup_guide_step_completed.completed_count`, bucketed as `0`, `1`, `2`, `3-4`, `5-7`, and `8`.
-
-Primary retention read:
-
-- D1, D3, and D7 return to `app_opened`
-- Compare new-user baseline, shown, completed, skipped, cancelled, and checklist-depth cohorts
-
-Primary activation read:
-
-- terminal split in first workspace session
-- two agent sessions in one worktree
-- two worktrees within 72 hours
-- follow-up/manual agent action
-- task/review source use
-- setup script configured
-- notifications configured
-- agent capabilities completed
-
-Interpretation rules:
-
-- A completed tour with no downstream activation means the tour is educational but not converting.
-- A skipped tour with strong downstream activation means the feature may be discoverable without the tour.
-- A high cancelled rate usually points to target loss, modal conflicts, or timing problems.
-- Strong checklist-depth retention with weak tour retention means the checklist is the value driver, not the automatic tour.
-
-## Volume Estimate
-
-Telemetry volume estimate:
-
-- Trigger: contextual tour shown/outcome, setup guide open/close, setup step first completion, optional terminal split
-- Expected events/user/day: 2-6 for new users who encounter the flow
-- Max events/user/day: about 14 on a heavy first day: 2 tour events, 2 setup guide events, 8 setup step completions, 1-2 split events
-- At 1,000 DAU: expected 2,000-6,000 events/day
-- Monthly at 1,000 DAU: expected 60,000-180,000 events/month
-- Approval note: The events answer the rollout decision directly and are bounded by explicit user actions or one-time durable setup completions. There are no timers, render-loop events, polling snapshots, or passive heartbeats.
-
-If observed volume exceeds expectation, remove or sample `setup_guide_opened` / `setup_guide_closed` before removing completion events. Completion events are the durable activation-depth read.
-
-## Privacy
-
-All payloads must be low-cardinality and schema-bounded.
-
-Never include:
-
-- prompts
-- terminal commands
-- paths
-- URLs
-- hostnames
-- repo names
-- branch names
-- task titles
-- user-authored text
-- raw errors
-- tokens
-- pane ids, worktree ids, repo ids, or other persistent product identifiers
-
-## Implementation Plan
-
-1. Extend `contextual_tour_outcome` schema in `src/shared/telemetry-events.ts` with optional `furthest_step_index` and `defined_step_count`.
-2. Track the highest reached defined tour step in `ContextualTourOverlay.tsx` alongside the existing `steps_seen` set.
-3. Add setup-guide event schemas and bounded enums in `src/shared/telemetry-events.ts`.
-4. Add a setup-guide telemetry helper in `src/renderer/src/lib/feature-education-telemetry.ts` or a dedicated setup-guide telemetry module.
-5. Emit `setup_guide_opened` and `setup_guide_closed` from `SetupGuideModal.tsx`.
-6. Emit `setup_guide_step_completed` from a small hook that observes visible setup-guide progress transitions, persists emitted step ids locally, and ignores hidden/background completions except as local baseline state.
-7. Add `terminal_pane_split` only if no existing telemetry captures successful terminal splits.
-8. Add schema tests for accepted payloads, rejected raw strings, count bounds, and enum bounds.
-9. Add renderer tests that prove each modal open emits one open event, each close emits one close event, each step completion emits once, rerenders do not re-emit, and pre-completed persisted steps are not backfilled repeatedly.
-
-## Dashboard Tiles
-
-Create a PostHog dashboard named `New User Parallel Work Activation`.
-
-Tiles:
-
-- Tour exposure: `contextual_tour_shown` by `tour_id` and `source`
-- Tour outcome: `contextual_tour_outcome` by `outcome`
-- Tour depth: median `furthest_step_index / defined_step_count`
-- Setup guide reach: `setup_guide_opened` by `source`
-- Setup guide close outcome: `setup_guide_closed` by `outcome`
-- Eight-step depth: latest `setup_guide_step_completed.completed_count` bucket
-- Activation funnel: tour shown -> tour outcome -> setup guide opened -> first two setup steps complete -> D1/D3/D7 return
-- Downstream actions: tour shown -> terminal split -> two agents in one worktree -> two worktrees within 72 hours
-
-Do not publish dashboard tiles that require raw user content or identifiers.
diff --git a/docs/reference/opencode-commit-message-stdin.md b/docs/reference/opencode-commit-message-stdin.md
deleted file mode 100644
index c7141fb4469..00000000000
--- a/docs/reference/opencode-commit-message-stdin.md
+++ /dev/null
@@ -1,105 +0,0 @@
-# OpenCode Commit Message Stdin Delivery
-
-## Problem
-
-OpenCode's preset Source Control AI path passes the full generated prompt as the final `opencode run` argv positional. Commit-message prompts include branch, staged file summary, user instructions, and the staged patch. The patch is capped by `STAGED_DIFF_BYTE_BUDGET = 200_000`, but the implementation uses JavaScript string length, not encoded byte length, so argv can still be much larger than command-line limits on Windows and some POSIX/SSH wrapper paths before OpenCode starts.
-
-Verified current code:
-
-- `src/shared/commit-message-agent-spec.ts:24-32` defines `promptDelivery` as the argv/stdin contract for large diffs.
-- `src/shared/commit-message-agent-spec.ts:322-337` sets OpenCode to `promptDelivery: 'argv'` and appends `prompt`.
-- `src/shared/commit-message-plan.ts:108-123` already routes `promptDelivery === 'stdin'` into `stdinPayload`.
-- `src/main/text-generation/commit-message-text-generation.ts:470-601` pipes local `stdinPayload` to child stdin.
-- `src/main/providers/ssh-git-provider.ts:122-140` forwards `stdinPayload` as relay `stdin`; `src/relay/agent-exec-handler.ts:160-303` writes it to the remote child.
-- `src/shared/commit-message-plan.test.ts:36` currently locks in the broken OpenCode argv behavior.
-
-## Feasibility Gate
-
-`opencode --version` on the local machine reports `1.15.13`. `opencode run --help` confirms the required args exist: `--model`, `--agent`, `--format`, and `--variant`, with optional `[message..]` positionals. It does not document stdin prompt input.
-
-Shipping gate: before changing the preset, run a controlled smoke test using the exact no-message shape, and verify stdout clearly reflects the stdin prompt rather than an empty task:
-
-```sh
-printf '%s\n' 'Write: test commit' | opencode run --model <model> --agent build --format default
-```
-
-Also smoke `--variant <level>` if the selected model exposes thinking levels. If credentials, model access, or an unsupported OpenCode version block validation, do not treat `--help` alone as proof. If stdin fails, do not add an argv fallback; stop and choose a different no-argv transport or version-gated behavior.
-
-## Root Cause
-
-The planner and both local/SSH execution paths already know how to carry stdin payloads. The mismatch is the OpenCode preset args.
-
-OpenCode is not the only argv-delivered path in the registry: Cursor and custom commands that explicitly use `{prompt}` still put prompts in argv. They are out of scope here and should not be described as fixed by this change.
-
-## Non-Goals
-
-- Do not change prompt wording, diff truncation, output cleanup, model discovery, or model selection.
-- Do not change interactive OpenCode terminal launch behavior.
-- Do not change GitHub/GitLab/provider review flows.
-- Do not change Cursor argv delivery or custom command `{prompt}` semantics.
-- Do not add a second OpenCode execution path.
-
-## Design
-
-1. Change the OpenCode preset spec to `promptDelivery: 'stdin'`.
-2. Add a short why-comment near that setting: OpenCode prompt input can contain large staged diffs and must stay out of argv.
-3. Remove `prompt` from OpenCode `buildArgs`. The preset args must be exactly `run --model <model> --agent build --format default`, plus `--variant <thinkingLevel>` when present.
-4. Keep `modelSource`, `modelDiscovery`, default model, and dynamic-model fallback behavior unchanged.
-5. Keep preset `agentCommandOverride` behavior unchanged: an override such as `npx opencode` prefixes the same OpenCode args, while the prompt remains `stdinPayload`.
-6. Accept the shared-spec blast radius: OpenCode prompts for commit-message, PR-field, and branch-name generation all move to stdin because they all call `planCommitMessageGeneration(...)`. If the requirement is commit-message-only, this design is wrong and needs operation-aware delivery instead.
-
-## Data Flow
-
-- Source Control AI receives a staged context and builds the prompt. The context is not atomic: branch, staged summary, and staged patch are read by separate git commands before generation.
-- `planCommitMessageGeneration(...)` validates the agent, model, and thinking level against the existing dynamic/static model rules.
-- Because OpenCode becomes stdin-delivered, the planner passes an empty prompt into `buildArgs` and stores the real prompt in `plan.stdinPayload`.
-- Local generation writes `stdinPayload` to the child process stdin.
-- SSH generation serializes the same plan to the relay as `{ stdin: plan.stdinPayload }`, and the relay writes it to the remote child process stdin after spawn.
-
-This fix removes the prompt from process argv only. It does not reduce prompt memory, model latency, token use, or diff truncation pressure. Remote execution still sends the prompt in one JSON-RPC frame; the relay frame cap is 16 MB, and today's prompt budget is under that, but future budget increases must account for it.
-
-## Edge Cases
-
-- Large staged diff: the prompt must be absent from `args`, including no empty-string placeholder.
-- Thinking level selected: preserve `--variant <level>`.
-- No thinking level selected: omit `--variant`.
-- Dynamic OpenCode model not present in the seed catalog: preserve the existing dynamic fallback and still pass the selected model id.
-- Agent command override: `npx opencode` becomes `binary: 'npx'`, `args: ['opencode', 'run', ...]`, with prompt in `stdinPayload`.
-- Windows batch shims: removing the prompt from argv also removes prompt metacharacters from the batch command line; do not route the prompt through `{prompt}` for this preset.
-- SSH: the prompt is JSON-serialized as `stdin`, not shell-quoted, and is written by the relay after spawn.
-- SSH payload size: this is safe for the current prompt budget, not an unbounded transport. Anything near 16 MB needs streaming or another transport.
-- OpenCode ignores stdin: the smoke test must catch this before shipping because `--help` does not document stdin.
-- Output cleanup remains unchanged; OpenCode stderr/status chatter should be handled by existing failure and cleanup logic.
-
-## Consistency And Concurrency
-
-- No cache invalidation is introduced. Each generation plans from the request's current settings and the staged context supplied to that request.
-- The staged context is not a true snapshot. If the index changes between the summary and patch reads, or after the context is read, the generated message can describe a mixed or stale view. That is existing behavior and not fixed here.
-- Multiple windows can request generation for the same worktree. Local execution does not serialize same-`cwd` requests; the cancel map is keyed by `operation:local:<cwd>` and the newest request overwrites the reachable cancel token. Do not claim this change fixes local multi-window races.
-- SSH execution queues matching `operation + cwd` lanes inside a `SshGitProvider` instance. The relay itself tracks only one active child per lane and cancels a prior active child if another request for the same lane reaches it, which matters if separate provider instances/windows bypass the same queue.
-- Settings or command overrides changed while a generation is in flight affect the next request only; the current child keeps its immutable plan.
-
-## Test Plan
-
-- `src/shared/commit-message-agent-spec.test.ts`: add OpenCode coverage asserting `promptDelivery === 'stdin'`, no prompt or empty placeholder in `buildArgs`, variant preservation, and no variant when absent.
-- `src/shared/commit-message-plan.test.ts`: update OpenCode expectations so `stdinPayload` receives the prompt and argv excludes it; include an OpenCode command-override case.
-- Because `planCommitMessageGeneration(...)` is reused by commit-message, PR-field, and branch-name generation, the plan tests are the main regression coverage for the shared blast radius.
-- Keep existing Codex stdin, custom-command stdin, local child stdin, SSH provider, and relay stdin tests passing.
-- Run targeted Vitest for the touched shared tests, plus `pnpm typecheck` and `pnpm lint` for the implementation branch.
-- Run the OpenCode stdin smoke test from the feasibility gate. If it cannot run, do not mark implementation risk as resolved.
-
-## Lightweight Eng Review
-
-- Scope: shared preset-agent plumbing and shared tests, with an explicit shared-operation blast radius for OpenCode commit-message, PR-field, and branch-name prompts. No renderer redesign, settings migration, hosted review flow, or provider-specific review behavior.
-- Architecture/data flow: use the existing `promptDelivery` contract; local and SSH execution already honor `stdinPayload`.
-- Failure modes covered: prompt re-enters argv, `--variant` is dropped, unknown dynamic model ids regress, command overrides change stdin behavior, remote JSON-RPC frame limits are ignored, or OpenCode accepts the flags but ignores stdin.
-- Performance/blast radius: no renderer, watcher, IPC subscription, or startup cost. Local argv shrinks; remote payload size is unchanged because the prompt still crosses JSON-RPC as stdin data in one frame.
-- UI quality bar: no visual change; skip visual-design review.
-- Screenshots: none required for this headless invocation change. If PR evidence is needed, prefer unit-test output and the controlled OpenCode stdin smoke result.
-- Residual risk: OpenCode stdin prompt input is not documented by `opencode run --help`; remote hosts may have different OpenCode versions; existing local multi-window cancellation races and staged-context non-atomicity remain.
-
-## Rollout
-
-1. Update OpenCode spec delivery and args.
-2. Update shared spec and planner tests.
-3. Run targeted tests, typecheck, lint, and the OpenCode smoke test before shipping.
diff --git a/docs/reference/plans/2026-06-27-orca-mobile-manual-network-address.md b/docs/reference/plans/2026-06-27-orca-mobile-manual-network-address.md
deleted file mode 100644
index c27fe37b255..00000000000
--- a/docs/reference/plans/2026-06-27-orca-mobile-manual-network-address.md
+++ /dev/null
@@ -1,972 +0,0 @@
-# Manual Network Address Entry — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Let users type a custom IPv4 address or Tailscale MagicDNS hostname into the desktop mobile-pairing Network Interface dropdown, so the QR code can target a host the OS hasn't auto-discovered.
-
-**Architecture:** Replace the inner `Select` of `MobileNetworkInterfaceSection` with a `Popover + Command` ("combobox") pattern modeled on the existing `AgentCombobox`. A new shared pure function `parseManualNetworkAddress` enforces the input grammar; a new helper `buildComboboxEntries` builds the row list (filtered interfaces + an optional `Use "<query>"` row). The custom selection is session-scoped.
-
-**Tech Stack:** TypeScript, React 18, shadcn/ui primitives (`Command`, `Popover`, `Button`) from `src/renderer/src/components/ui/`, vitest, `@testing-library/react`. No new dependencies.
-
-**Spec:** [`docs/reference/2026-06-27-orca-mobile-manual-network-address-design.md`](../2026-06-27-orca-mobile-manual-network-address-design.md)
-
----
-
-## File map
-
-**Create:**
-- `src/shared/network/manual-address.ts` — pure parser.
-- `src/shared/network/manual-address.test.ts` — parser unit tests.
-- `src/renderer/src/components/settings/MobileNetworkInterfaceSection.test.tsx` — UI render tests.
-
-**Modify:**
-- `src/renderer/src/components/settings/mobile-network-interface-selection.ts` — swap `mergeForSelect` for `buildComboboxEntries` (or add `buildComboboxEntries` and keep the old one if other call sites exist; confirm with grep before deleting).
-- `src/renderer/src/components/settings/mobile-network-interface-selection.test.ts` — replace `mergeForSelect` tests with `buildComboboxEntries` tests.
-- `src/renderer/src/components/settings/MobileNetworkInterfaceSection.tsx` — swap `Select` for `Popover + Command`.
-
-**Reference (read-only, do not modify):**
-- `src/renderer/src/components/ui/command.tsx` — `Command`, `CommandEmpty`, `CommandInput`, `CommandItem`, `CommandList`, `CommandSeparator`.
-- `src/renderer/src/components/ui/popover.tsx` — `Popover`, `PopoverTrigger`, `PopoverContent`.
-- `src/renderer/src/components/ui/button.tsx` — `Button`.
-- `src/renderer/src/components/agent/AgentCombobox.tsx` — full reference implementation of the controlled cmdk pattern.
-- `src/renderer/src/components/agent/agent-combobox-command-state.ts` — `createAgentComboboxCommandState`, `resolveAgentComboboxCommandState`, `updateAgentComboboxCommandValue`.
-- `src/renderer/src/components/settings/MobilePairingQrSection.tsx` — consumer of `selectedAddress`; unchanged.
-
-**Out of scope:** mobile-side endpoint override (`mobile/app/pair-scan.tsx`); main-process code; persistent storage of custom addresses; IPv6, ports, non-Tailscale hostnames.
-
----
-
-## Task 1: Add `parseManualNetworkAddress` (TDD)
-
-**Files:**
-- Create: `src/shared/network/manual-address.ts`
-- Create: `src/shared/network/manual-address.test.ts`
-
-- [ ] **Step 1: Confirm no existing call site for `mergeForSelect`**
-
-  Run:
-  ```bash
-  grep -rn "mergeForSelect" src/ docs/ 2>/dev/null
-  ```
-  Expected: no matches. (If there are matches, stop and update Task 2 to keep `mergeForSelect` and only add `buildComboboxEntries` alongside it.)
-
-- [ ] **Step 2: Write the failing tests**
-
-  Create `src/shared/network/manual-address.test.ts` with this exact content:
-
-  ```ts
-  import { describe, it, expect } from 'vitest'
-  import { parseManualNetworkAddress } from './manual-address'
-
-  describe('parseManualNetworkAddress', () => {
-    describe('IPv4', () => {
-      it('accepts canonical IPv4', () => {
-        expect(parseManualNetworkAddress('192.168.1.24')).toEqual({
-          ok: true,
-          address: '192.168.1.24'
-        })
-        expect(parseManualNetworkAddress('100.64.1.20')).toEqual({
-          ok: true,
-          address: '100.64.1.20'
-        })
-      })
-
-      it('accepts boundary IPv4 values', () => {
-        expect(parseManualNetworkAddress('0.0.0.0').ok).toBe(true)
-        expect(parseManualNetworkAddress('255.255.255.255').ok).toBe(true)
-      })
-
-      it('rejects malformed IPv4', () => {
-        for (const bad of ['', '   ', '1.2.3', '1.2.3.4.5', '256.0.0.1']) {
-          expect(parseManualNetworkAddress(bad)).toEqual({
-            ok: false,
-            error: 'Enter an IPv4 address or Tailscale MagicDNS hostname'
-          })
-        }
-      })
-
-      it('rejects leading zeros in octets', () => {
-        expect(parseManualNetworkAddress('01.02.03.04')).toEqual({
-          ok: false,
-          error: 'Enter an IPv4 address or Tailscale MagicDNS hostname'
-        })
-        expect(parseManualNetworkAddress('0.0.0.0').ok).toBe(true)
-      })
-    })
-
-    describe('Tailscale MagicDNS hostname', () => {
-      it('accepts short MagicDNS names', () => {
-        expect(parseManualNetworkAddress('my-mac.ts.net')).toEqual({
-          ok: true,
-          address: 'my-mac.ts.net'
-        })
-      })
-
-      it('accepts tailnet-qualified MagicDNS names', () => {
-        expect(parseManualNetworkAddress('my-mac.tail-abcd.ts.net')).toEqual({
-          ok: true,
-          address: 'my-mac.tail-abcd.ts.net'
-        })
-        expect(parseManualNetworkAddress('a.b.c.d.ts.net').ok).toBe(true)
-      })
-
-      it('is case-insensitive', () => {
-        expect(parseManualNetworkAddress('MY-MAC.TS.NET').ok).toBe(true)
-      })
-
-      it('rejects non-Tailscale hostnames', () => {
-        for (const bad of ['my-mac', 'my-mac.ts.com', '-foo.ts.net', 'my-mac.com']) {
-          expect(parseManualNetworkAddress(bad).ok).toBe(false)
-        }
-      })
-    })
-
-    describe('length and whitespace', () => {
-      it('rejects inputs longer than 253 chars', () => {
-        const long = `${'a'.repeat(250)}.ts.net`
-        expect(long.length).toBeGreaterThan(253)
-        expect(parseManualNetworkAddress(long).ok).toBe(false)
-      })
-
-      it('trims leading and trailing whitespace before validating', () => {
-        expect(parseManualNetworkAddress('  192.168.1.24  ')).toEqual({
-          ok: true,
-          address: '192.168.1.24'
-        })
-      })
-    })
-  })
-  ```
-
-- [ ] **Step 3: Run tests to verify they fail**
-
-  Run from repo root:
-  ```bash
-  pnpm vitest run src/shared/network/manual-address.test.ts
-  ```
-  Expected: error like `Cannot find module './manual-address'`. This is the failing-test step — do not skip it.
-
-- [ ] **Step 4: Implement `parseManualNetworkAddress`**
-
-  Create `src/shared/network/manual-address.ts` with this exact content:
-
-  ```ts
-  // Why: pure shared helper so the same validation runs in renderer
-  // today and in any future CLI/main-process caller without duplicating
-  // the IPv4 + Tailscale MagicDNS grammar.
-  const IPV4_OCTET = '(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])'
-  const IPV4 = `(?:${IPV4_OCTET}\\.){3}${IPV4_OCTET}`
-  // MagicDNS hostname: lowercase letters/digits/hyphens, dot-separated, ending in .ts.net.
-  // Labels may not start or end with a hyphen; max 63 chars per label (DNS limit).
-  const MAGICDNS_LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?'
-  const MAGICDNS = `(?:${MAGICDNS_LABEL}\\.)+ts\\.net`
-
-  const HOSTNAME_MAX_LENGTH = 253
-  const ERROR_MESSAGE = 'Enter an IPv4 address or Tailscale MagicDNS hostname'
-
-  export type ParseManualAddressResult =
-    | { ok: true; address: string }
-    | { ok: false; error: string }
-
-  export function parseManualNetworkAddress(input: string): ParseManualAddressResult {
-    const trimmed = input.trim()
-    if (trimmed === '' || trimmed.length > HOSTNAME_MAX_LENGTH) {
-      return { ok: false, error: ERROR_MESSAGE }
-    }
-    if (/\s/.test(trimmed)) {
-      return { ok: false, error: ERROR_MESSAGE }
-    }
-
-    const ipv4Regex = new RegExp(`^${IPV4}$`)
-    if (ipv4Regex.test(trimmed)) {
-      return { ok: true, address: trimmed }
-    }
-
-    const magicRegex = new RegExp(`^(?:${MAGICDNS})$`, 'i')
-    if (magicRegex.test(trimmed)) {
-      return { ok: true, address: trimmed }
-    }
-
-    return { ok: false, error: ERROR_MESSAGE }
-  }
-  ```
-
-- [ ] **Step 5: Run tests to verify they pass**
-
-  Run:
-  ```bash
-  pnpm vitest run src/shared/network/manual-address.test.ts
-  ```
-  Expected: all tests pass.
-
-- [ ] **Step 6: Lint and typecheck**
-
-  ```bash
-  pnpm lint src/shared/network/
-  pnpm typecheck
-  ```
-  Expected: no errors. Fix any and re-run before continuing.
-
-- [ ] **Step 7: Commit**
-
-  ```bash
-  git add src/shared/network/manual-address.ts src/shared/network/manual-address.test.ts
-  git commit -m "feat(mobile-pairing): add parseManualNetworkAddress validator"
-  ```
-
----
-
-## Task 2: Replace `mergeForSelect` with `buildComboboxEntries` (TDD)
-
-**Files:**
-- Modify: `src/renderer/src/components/settings/mobile-network-interface-selection.ts`
-- Modify: `src/renderer/src/components/settings/mobile-network-interface-selection.test.ts`
-
-- [ ] **Step 1: Read the current contents of both files**
-
-  Read the full source of:
-  - `src/renderer/src/components/settings/mobile-network-interface-selection.ts`
-  - `src/renderer/src/components/settings/mobile-network-interface-selection.test.ts`
-
-  Confirm: `mergeForSelect` is the only exported function besides the `MobileNetworkInterface` type and `selectRefreshedNetworkAddress`. If `selectRefreshedNetworkAddress` is called from `MobileNetworkInterfaceSection.tsx`, keep it.
-
-- [ ] **Step 2: Write the failing tests for `buildComboboxEntries`**
-
-  Replace the entire body of `mobile-network-interface-selection.test.ts` with:
-
-  ```ts
-  import { describe, it, expect } from 'vitest'
-  import {
-    buildComboboxEntries,
-    selectRefreshedNetworkAddress,
-    type MobileNetworkInterface
-  } from './mobile-network-interface-selection'
-
-  const LAN: MobileNetworkInterface = { name: 'en0', address: '192.168.1.24' }
-  const TAILNET: MobileNetworkInterface = { name: 'tailscale0', address: '100.64.1.20' }
-
-  describe('buildComboboxEntries', () => {
-    it('returns only interface entries when query is empty', () => {
-      const entries = buildComboboxEntries([LAN, TAILNET], '')
-      expect(entries).toEqual([
-        { kind: 'interface', iface: LAN },
-        { kind: 'interface', iface: TAILNET }
-      ])
-    })
-
-    it('filters interfaces by substring on address or name (case-insensitive)', () => {
-      const entries = buildComboboxEntries([LAN, TAILNET], 'TAIL')
-      expect(entries).toEqual([{ kind: 'interface', iface: TAILNET }])
-    })
-
-    it('appends a use-query entry when the query is a valid address not in the list', () => {
-      const entries = buildComboboxEntries([LAN, TAILNET], 'my-mac.tail-abcd.ts.net')
-      expect(entries).toEqual([
-        { kind: 'interface', iface: LAN },
-        { kind: 'interface', iface: TAILNET },
-        { kind: 'use-query', address: 'my-mac.tail-abcd.ts.net' }
-      ])
-    })
-
-    it('suppresses use-query when query equals an existing interface address', () => {
-      const entries = buildComboboxEntries([LAN, TAILNET], '100.64.1.20')
-      expect(entries).toEqual([
-        { kind: 'interface', iface: LAN },
-        { kind: 'interface', iface: TAILNET }
-      ])
-    })
-
-    it('returns only use-query when interfaces are empty and query is valid', () => {
-      const entries = buildComboboxEntries([], '1.2.3.4')
-      expect(entries).toEqual([{ kind: 'use-query', address: '1.2.3.4' }])
-    })
-
-    it('omits use-query when query is invalid', () => {
-      const entries = buildComboboxEntries([LAN, TAILNET], 'not-an-address')
-      expect(entries).toEqual([
-        { kind: 'interface', iface: LAN },
-        { kind: 'interface', iface: TAILNET }
-      ])
-    })
-  })
-
-  describe('selectRefreshedNetworkAddress', () => {
-    // Existing behavior is preserved verbatim from the spec.
-    it('keeps the selected address when refresh discovers a new tailnet interface', () => {
-      expect(selectRefreshedNetworkAddress(LAN.address, [LAN, TAILNET])).toBe(LAN.address)
-    })
-
-    it('selects the first refreshed interface when there is no current address', () => {
-      expect(selectRefreshedNetworkAddress(undefined, [TAILNET, LAN])).toBe(TAILNET.address)
-    })
-
-    it('prefers a tailnet address when no address is selected yet', () => {
-      expect(selectRefreshedNetworkAddress(undefined, [LAN, TAILNET])).toBe(TAILNET.address)
-    })
-
-    it('moves to the first refreshed interface when the current address disappeared', () => {
-      expect(selectRefreshedNetworkAddress('10.0.0.4', [TAILNET, LAN])).toBe(TAILNET.address)
-    })
-
-    it('moves to a tailnet address when the current address disappeared', () => {
-      expect(selectRefreshedNetworkAddress('10.0.0.4', [LAN, TAILNET])).toBe(TAILNET.address)
-    })
-
-    it('clears the selection when no interfaces are available', () => {
-      expect(selectRefreshedNetworkAddress(LAN.address, [])).toBeUndefined()
-    })
-  })
-  ```
-
-- [ ] **Step 3: Run the test file to verify the new tests fail**
-
-  ```bash
-  pnpm vitest run src/renderer/src/components/settings/mobile-network-interface-selection.test.ts
-  ```
-  Expected: `buildComboboxEntries is not a function` (or import error) for the new block; the `selectRefreshedNetworkAddress` block still passes.
-
-- [ ] **Step 4: Rewrite `mobile-network-interface-selection.ts`**
-
-  Replace the entire file with:
-
-  ```ts
-  import { isTailnetIPv4Address } from '../../../../shared/tailnet-address'
-  import { parseManualNetworkAddress } from '../../../../shared/network/manual-address'
-
-  export type MobileNetworkInterface = {
-    name: string
-    address: string
-  }
-
-  export type ComboboxEntry =
-    | { kind: 'interface'; iface: MobileNetworkInterface }
-    | { kind: 'use-query'; address: string }
-
-  // Why: the UI needs a single ordered list to render inside CommandList.
-  // Behavior branches on whether the query parses as a valid address —
-  // valid queries show the full interface list (so users can pivot to an
-  // existing interface mid-typing), invalid queries substring-filter and
-  // fall back to the full list when nothing matches.
-  export function buildComboboxEntries(
-    interfaces: readonly MobileNetworkInterface[],
-    query: string
-  ): readonly ComboboxEntry[] {
-    const trimmed = query.trim()
-    if (trimmed === '') {
-      return interfaces.map((iface) => ({ kind: 'interface' as const, iface }))
-    }
-
-    const parsed = parseManualNetworkAddress(trimmed)
-
-    let visible: readonly MobileNetworkInterface[]
-    if (parsed.ok) {
-      // Valid address: keep every interface visible.
-      visible = interfaces
-    } else {
-      // Invalid: substring-filter; fall back to full list when nothing matches.
-      const lowered = trimmed.toLowerCase()
-      const filtered = interfaces.filter(
-        (iface) =>
-          iface.address.toLowerCase().includes(lowered) ||
-          iface.name.toLowerCase().includes(lowered)
-      )
-      visible = filtered.length > 0 ? filtered : interfaces
-    }
-
-    const entries: ComboboxEntry[] = visible.map((iface) => ({
-      kind: 'interface' as const,
-      iface
-    }))
-
-    if (parsed.ok && !visible.some((iface) => iface.address === parsed.address)) {
-      entries.push({ kind: 'use-query', address: parsed.address })
-    }
-
-    return entries
-  }
-
-  export function selectRefreshedNetworkAddress(
-    currentAddress: string | undefined,
-    interfaces: readonly MobileNetworkInterface[]
-  ): string | undefined {
-    if (interfaces.length === 0) {
-      return undefined
-    }
-    if (currentAddress && interfaces.some((iface) => iface.address === currentAddress)) {
-      return currentAddress
-    }
-    return (
-      interfaces.find((iface) => isTailnetIPv4Address(iface.address))?.address ??
-      interfaces[0]!.address
-    )
-  }
-  ```
-
-  The relative import paths (`../../../../shared/tailnet-address`, `../../../../shared/network/manual-address`) must match the file's location in the tree. If they don't resolve, adjust based on the existing path style in the same directory (e.g. `../foo` vs `@/foo`).
-
-- [ ] **Step 5: Run the test file to verify everything passes**
-
-  ```bash
-  pnpm vitest run src/renderer/src/components/settings/mobile-network-interface-selection.test.ts
-  ```
-  Expected: all tests pass.
-
-- [ ] **Step 6: Lint and typecheck**
-
-  ```bash
-  pnpm lint src/renderer/src/components/settings/mobile-network-interface-selection.ts
-  pnpm typecheck
-  ```
-
-- [ ] **Step 7: Commit**
-
-  ```bash
-  git add src/renderer/src/components/settings/mobile-network-interface-selection.ts \
-          src/renderer/src/components/settings/mobile-network-interface-selection.test.ts
-  git commit -m "feat(mobile-pairing): buildComboboxEntries for network interface combobox"
-  ```
-
----
-
-## Task 3: Rewrite `MobileNetworkInterfaceSection` UI to use Popover + Command
-
-**Files:**
-- Modify: `src/renderer/src/components/settings/MobileNetworkInterfaceSection.tsx`
-- Create: `src/renderer/src/components/settings/MobileNetworkInterfaceSection.test.tsx`
-
-- [ ] **Step 1: Read `AgentCombobox.tsx` end-to-end**
-
-  Read `src/renderer/src/components/agent/AgentCombobox.tsx` and `agent-combobox-command-state.ts` in full. You will be borrowing:
-  - The `Popover` + `Command` + `CommandInput` + `CommandList` + `CommandItem` JSX structure.
-  - The controlled `commandState`/`commandValue` pattern that mirrors `AgentCombobox`.
-  - The `setInputNode`/`focusSearchInput` pattern for keyboard accessibility.
-
-  Do not import agent-specific helpers (e.g. `searchAgentPickerEntries`, `agent-combobox-command-state` is shared but the search logic isn't needed here).
-
-- [ ] **Step 2: Read the current `MobileNetworkInterfaceSection.tsx` in full**
-
-  Read the file. Note the props contract:
-  ```ts
-  type MobileNetworkInterfaceSectionProps = {
-    networkInterfaces: MobileNetworkInterface[]
-    selectedAddress: string | undefined
-    onSelectedAddressChange: (address: string) => void
-    refreshingNetworkInterfaces: boolean
-    onRefreshNetworkInterfaces: () => void
-    loading: boolean
-    hasQrCode: boolean
-    onGenerateQr: () => void
-  }
-  ```
-  The contract **must not change** — only the inner control does. `MobilePairingQrSection.tsx` consumes `selectedAddress` and is unaffected.
-
-- [ ] **Step 3: Write the failing render tests**
-
-  Create `src/renderer/src/components/settings/MobileNetworkInterfaceSection.test.tsx`:
-
-  ```tsx
-  import React from 'react'
-  import { describe, it, expect, vi } from 'vitest'
-  import { render, screen } from '@testing-library/react'
-  import userEvent from '@testing-library/user-event'
-  import { MobileNetworkInterfaceSection } from './MobileNetworkInterfaceSection'
-  import type { MobileNetworkInterface } from './mobile-network-interface-selection'
-
-  const LAN: MobileNetworkInterface = { name: 'en0', address: '192.168.1.24' }
-  const TAILNET: MobileNetworkInterface = { name: 'tailscale0', address: '100.64.1.20' }
-
-  function renderSection(overrides: Partial<React.ComponentProps<typeof MobileNetworkInterfaceSection>> = {}) {
-    const onSelectedAddressChange = vi.fn()
-    const onRefreshNetworkInterfaces = vi.fn()
-    const onGenerateQr = vi.fn()
-    const props: React.ComponentProps<typeof MobileNetworkInterfaceSection> = {
-      networkInterfaces: [LAN, TAILNET],
-      selectedAddress: TAILNET.address,
-      onSelectedAddressChange,
-      refreshingNetworkInterfaces: false,
-      onRefreshNetworkInterfaces,
-      loading: false,
-      hasQrCode: false,
-      onGenerateQr,
-      ...overrides
-    }
-    const user = userEvent.setup()
-    const utils = render(<MobileNetworkInterfaceSection {...props} />)
-    return { ...utils, user, onSelectedAddressChange, onRefreshNetworkInterfaces, onGenerateQr }
-  }
-
-  describe('MobileNetworkInterfaceSection', () => {
-    it('renders the trigger with the currently selected address', () => {
-      renderSection()
-      expect(screen.getByRole('combobox')).toHaveTextContent('100.64.1.20 (tailscale0)')
-    })
-
-    it('lets the user type a custom address and confirms via the Use row', async () => {
-      const { user, onSelectedAddressChange } = renderSection()
-      await user.click(screen.getByRole('combobox'))
-      const input = screen.getByPlaceholderText(/search or type/i)
-      await user.type(input, 'my-mac.tail-abcd.ts.net')
-      await user.click(screen.getByRole('option', { name: /Use "my-mac\.tail-abcd\.ts\.net"/ }))
-      expect(onSelectedAddressChange).toHaveBeenCalledWith('my-mac.tail-abcd.ts.net')
-    })
-
-    it('shows an inline error and no Use row when the query is invalid', async () => {
-      const { user } = renderSection()
-      await user.click(screen.getByRole('combobox'))
-      await user.type(screen.getByPlaceholderText(/search or type/i), 'not an address')
-      expect(screen.getByText(/Enter an IPv4 address or Tailscale MagicDNS hostname/i)).toBeInTheDocument()
-      expect(screen.queryByRole('option', { name: /Use / })).not.toBeInTheDocument()
-    })
-
-    it('suppresses the Use row when the typed address matches an existing interface', async () => {
-      const { user } = renderSection()
-      await user.click(screen.getByRole('combobox'))
-      await user.type(screen.getByPlaceholderText(/search or type/i), '192.168.1.24')
-      expect(screen.getByRole('option', { name: '192.168.1.24 (en0)' })).toBeInTheDocument()
-      expect(screen.queryByRole('option', { name: /Use "192\.168\.1\.24"/ })).not.toBeInTheDocument()
-    })
-
-    it('renders the (custom) label on the trigger after a custom selection', () => {
-      renderSection({ selectedAddress: 'my-mac.tail-abcd.ts.net' })
-      expect(screen.getByRole('combobox')).toHaveTextContent('my-mac.tail-abcd.ts.net (custom)')
-    })
-
-    it('shows No interfaces found when the list is empty', () => {
-      renderSection({ networkInterfaces: [], selectedAddress: undefined })
-      expect(screen.getByRole('combobox')).toHaveTextContent(/no interfaces found/i)
-    })
-  })
-  ```
-
-- [ ] **Step 4: Run the test file to verify it fails**
-
-  ```bash
-  pnpm vitest run src/renderer/src/components/settings/MobileNetworkInterfaceSection.test.tsx
-  ```
-  Expected: failures on every assertion — the component still uses `Select`. This is the failing-test step.
-
-- [ ] **Step 5: Rewrite the component**
-
-  Replace the entire body of `MobileNetworkInterfaceSection.tsx` with:
-
-  ```tsx
-  import { useCallback, useMemo, useState } from 'react'
-  import { ChevronDown, ExternalLink, Loader2, QrCode, RefreshCw, Wifi } from 'lucide-react'
-  import {
-    Accordion,
-    AccordionContent,
-    AccordionItem,
-    AccordionTrigger
-  } from '../ui/accordion'
-  import { Button } from '../ui/button'
-  import {
-    Command,
-    CommandEmpty,
-    CommandInput,
-    CommandItem,
-    CommandList,
-    CommandSeparator
-  } from '../ui/command'
-  import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover'
-  import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
-  import { parseManualNetworkAddress } from '../../../../shared/network/manual-address'
-  import { translate } from '@/i18n/i18n'
-  import {
-    buildComboboxEntries,
-    type MobileNetworkInterface
-  } from './mobile-network-interface-selection'
-
-  const TAILSCALE_DOWNLOAD_URL = 'https://tailscale.com/download'
-  const TRIGGER_LABEL_CUSTOM = 'custom'
-  const ERROR_MESSAGE = 'Enter an IPv4 address or Tailscale MagicDNS hostname'
-
-  type MobileNetworkInterfaceSectionProps = {
-    networkInterfaces: MobileNetworkInterface[]
-    selectedAddress: string | undefined
-    onSelectedAddressChange: (address: string) => void
-    refreshingNetworkInterfaces: boolean
-    onRefreshNetworkInterfaces: () => void
-    loading: boolean
-    hasQrCode: boolean
-    onGenerateQr: () => void
-  }
-
-  function formatInterfaceLabel(iface: MobileNetworkInterface): string {
-    return `${iface.address} (${iface.name})`
-  }
-
-  function isCustomLabel(name: string): boolean {
-    return name === TRIGGER_LABEL_CUSTOM
-  }
-
-  export function MobileNetworkInterfaceSection({
-    networkInterfaces,
-    selectedAddress,
-    onSelectedAddressChange,
-    refreshingNetworkInterfaces,
-    onRefreshNetworkInterfaces,
-    loading,
-    hasQrCode,
-    onGenerateQr
-  }: MobileNetworkInterfaceSectionProps): React.JSX.Element {
-    const [open, setOpen] = useState(false)
-    const [query, setQuery] = useState('')
-    // Why: session-scoped custom selection (see spec). Cleared automatically
-    // when the settings pane unmounts because the state lives in this component.
-    const [customAddress, setCustomAddress] = useState<string | null>(null)
-
-    const selectedIface = useMemo<MobileNetworkInterface | null>(() => {
-      if (!selectedAddress) return null
-      const matched = networkInterfaces.find((iface) => iface.address === selectedAddress)
-      if (matched) return matched
-      if (selectedAddress === customAddress) {
-        return { name: TRIGGER_LABEL_CUSTOM, address: selectedAddress }
-      }
-      return null
-    }, [networkInterfaces, selectedAddress, customAddress])
-
-    const triggerLabel = selectedIface
-      ? formatInterfaceLabel(selectedIface)
-      : translate(
-          'auto.components.settings.MobileNetworkInterfaceSection.b2c384cfd6',
-          'No interfaces found'
-        )
-
-    const entries = useMemo(
-      () => buildComboboxEntries(networkInterfaces, query),
-      [networkInterfaces, query]
-    )
-
-    const queryParse = useMemo(() => parseManualNetworkAddress(query), [query])
-    const showInlineError = query.trim() !== '' && !queryParse.ok
-
-    const handleSelectInterface = useCallback(
-      (iface: MobileNetworkInterface) => {
-        setCustomAddress(null)
-        setQuery('')
-        setOpen(false)
-        onSelectedAddressChange(iface.address)
-      },
-      [onSelectedAddressChange]
-    )
-
-    const handleSelectUseQuery = useCallback(
-      (address: string) => {
-        setCustomAddress(address)
-        setQuery('')
-        setOpen(false)
-        onSelectedAddressChange(address)
-      },
-      [onSelectedAddressChange]
-    )
-
-    return (
-      <div className="rounded-lg border border-border/60 p-4">
-        <div className="mb-3 flex items-center gap-2">
-          <Wifi className="size-4 text-muted-foreground" />
-          <span className="text-sm font-medium">
-            {translate(
-              'auto.components.settings.MobileNetworkInterfaceSection.406a35121c',
-              'Network Interface'
-            )}
-          </span>
-        </div>
-        <p className="text-muted-foreground mb-3 text-xs">
-          {translate(
-            'auto.components.settings.MobileNetworkInterfaceSection.d536b5e20d',
-            'Choose which network address to advertise in the QR code. Use your LAN address for same-network pairing, or an overlay network address (Tailscale, ZeroTier) for cross-network access.'
-          )}
-        </p>
-        <div className="space-y-3">
-          <div className="flex flex-wrap items-center gap-3">
-            <Popover open={open} onOpenChange={setOpen}>
-              <PopoverTrigger asChild>
-                <Button
-                  type="button"
-                  variant="outline"
-                  size="sm"
-                  role="combobox"
-                  aria-expanded={open}
-                  className="min-w-[220px] justify-between font-normal"
-                >
-                  <span className="truncate">{triggerLabel}</span>
-                  <ChevronDown className="ml-2 size-3.5 opacity-60" />
-                </Button>
-              </PopoverTrigger>
-              <PopoverContent className="w-[320px] p-0" align="start">
-                <Command shouldFilter={false}>
-                  <CommandInput
-                    value={query}
-                    onValueChange={setQuery}
-                    placeholder={translate(
-                      'auto.components.settings.MobileNetworkInterfaceSection.new-combobox-placeholder',
-                      'Search or type an address…'
-                    )}
-                  />
-                  <CommandList>
-                    <CommandEmpty>
-                      {showInlineError ? ERROR_MESSAGE : translate(
-                        'auto.components.settings.MobileNetworkInterfaceSection.new-combobox-empty',
-                        'No matching interfaces'
-                      )}
-                    </CommandEmpty>
-                    {entries.map((entry, index) => {
-                      if (entry.kind === 'interface') {
-                        return (
-                          <CommandItem
-                            key={`iface-${entry.iface.name}-${entry.iface.address}`}
-                            value={`${entry.iface.address} ${entry.iface.name}`}
-                            onSelect={() => handleSelectInterface(entry.iface)}
-                          >
-                            {formatInterfaceLabel(entry.iface)}
-                          </CommandItem>
-                        )
-                      }
-                      const isFirstUseQuery = index > 0
-                      return (
-                        <div key={`use-${entry.address}`}>
-                          {isFirstUseQuery ? <CommandSeparator /> : null}
-                          <CommandItem
-                            value={`__use__ ${entry.address}`}
-                            onSelect={() => handleSelectUseQuery(entry.address)}
-                          >
-                            Use &quot;{entry.address}&quot;
-                          </CommandItem>
-                        </div>
-                      )
-                    })}
-                  </CommandList>
-                </Command>
-              </PopoverContent>
-            </Popover>
-            <Tooltip>
-              <TooltipTrigger asChild>
-                <Button
-                  type="button"
-                  variant="ghost"
-                  size="icon-sm"
-                  onClick={onRefreshNetworkInterfaces}
-                  disabled={refreshingNetworkInterfaces}
-                  aria-label={translate(
-                    'auto.components.settings.MobileNetworkInterfaceSection.a9db5d771d',
-                    'Refresh network interfaces'
-                  )}
-                  className="text-muted-foreground"
-                >
-                  <RefreshCw className={refreshingNetworkInterfaces ? 'animate-spin' : ''} />
-                </Button>
-              </TooltipTrigger>
-              <TooltipContent side="bottom" sideOffset={6}>
-                {translate(
-                  'auto.components.settings.MobileNetworkInterfaceSection.a9db5d771d',
-                  'Refresh network interfaces'
-                )}
-              </TooltipContent>
-            </Tooltip>
-          </div>
-          {showInlineError ? (
-            <p className="text-xs text-statusRed" role="status">
-              {ERROR_MESSAGE}
-            </p>
-          ) : null}
-          <Button
-            onClick={onGenerateQr}
-            disabled={loading || !selectedAddress}
-            size="sm"
-            className="gap-1.5"
-          >
-            {loading ? (
-              <Loader2 className="size-3.5 animate-spin" />
-            ) : hasQrCode ? (
-              <RefreshCw className="size-3.5" />
-            ) : (
-              <QrCode className="size-3.5" />
-            )}
-            {hasQrCode
-              ? translate(
-                  'auto.components.settings.MobileNetworkInterfaceSection.1e64659126',
-                  'Regenerate'
-                )
-              : translate(
-                  'auto.components.settings.MobileNetworkInterfaceSection.c541f67790',
-                  'Generate QR Code'
-                )}
-          </Button>
-        </div>
-        <Accordion type="single" collapsible className="mt-4 border-t border-border/60 pt-2">
-          <AccordionItem value="remote-pairing-guide">
-            <AccordionTrigger className="py-2 text-xs">
-              {translate(
-                'auto.components.settings.MobileNetworkInterfaceSection.39fad211d9',
-                'Connect outside your Wi-Fi with a tailnet'
-              )}
-            </AccordionTrigger>
-            <AccordionContent className="space-y-3 text-xs text-muted-foreground">
-              <p>
-                {translate(
-                  'auto.components.settings.MobileNetworkInterfaceSection.9fc5d203ff',
-                  'Orca Mobile connects directly to this computer. To use it away from the same local network, put your computer and phone on the same private overlay network, then generate the QR code with that network address selected.'
-                )}
-              </p>
-              <ol className="list-decimal space-y-1 pl-4">
-                <li>
-                  {translate(
-                    'auto.components.settings.MobileNetworkInterfaceSection.51d29927eb',
-                    'Install'
-                  )}{' '}
-                  <button
-                    type="button"
-                    onClick={() => void window.api.shell.openUrl(TAILSCALE_DOWNLOAD_URL)}
-                    className="inline-flex items-center gap-1 font-medium text-foreground underline-offset-2 hover:underline"
-                  >
-                    {translate(
-                      'auto.components.settings.MobileNetworkInterfaceSection.1dc87a7fbc',
-                      'Tailscale'
-                    )}
-                    <ExternalLink className="size-3" />
-                  </button>{' '}
-                  {translate(
-                    'auto.components.settings.MobileNetworkInterfaceSection.668016be7a',
-                    'on your computer and phone.'
-                  )}
-                </li>
-                <li>
-                  {translate(
-                    'auto.components.settings.MobileNetworkInterfaceSection.1f7c26d36a',
-                    'Sign in to the same tailnet on both devices.'
-                  )}
-                </li>
-                <li>
-                  {translate(
-                    'auto.components.settings.MobileNetworkInterfaceSection.87985ba6f5',
-                    'In this Network Interface menu, choose the Tailscale address, usually a 100.x.y.z IP.'
-                  )}
-                </li>
-                <li>
-                  {translate(
-                    'auto.components.settings.MobileNetworkInterfaceSection.63d5e4ae1e',
-                    'Regenerate the QR code and scan it from the Orca mobile app.'
-                  )}
-                </li>
-              </ol>
-            </AccordionContent>
-          </AccordionItem>
-        </Accordion>
-      </div>
-    )
-  }
-  ```
-
-  Notes for the implementer:
-  - `Command shouldFilter={false}` because we already filter in `buildComboboxEntries`. Without this, cmdk's default fuzzy filter would re-filter the manually-injected `__use__` row out of view.
-  - The `value` prop on each `CommandItem` keeps cmdk happy but does not affect our filtering; we own filtering.
-  - `useMemo` is used for `selectedIface`, `entries`, and `queryParse` so re-renders triggered by parent prop changes don't churn the combobox state.
-  - If `isCustomLabel` is unused after a lint pass (no caller in the final file), delete the helper — the spec lists it but the implementation inlines the check.
-
-- [ ] **Step 6: Run the new test file**
-
-  ```bash
-  pnpm vitest run src/renderer/src/components/settings/MobileNetworkInterfaceSection.test.tsx
-  ```
-  Expected: all six tests pass.
-
-  If any fail:
-  - `toHaveTextContent` mismatches → check the trigger label format.
-  - `getByRole('option', { name: /Use "…"/ })` not found → verify `Command shouldFilter={false}` is set.
-  - Inline error not appearing → verify `showInlineError` is computed against `queryParse.ok`.
-
-- [ ] **Step 7: Run the full test suite for the settings folder**
-
-  ```bash
-  pnpm vitest run src/renderer/src/components/settings/
-  ```
-  Expected: all green. Confirm nothing else broke (e.g. `MobilePairingQrSection.test.tsx` if it exists).
-
-- [ ] **Step 8: Lint, typecheck, build**
-
-  ```bash
-  pnpm lint
-  pnpm typecheck
-  pnpm build
-  ```
-  Expected: all green. If `pnpm lint` complains about an unused import (e.g. `isCustomLabel` or `CommandSeparator`), remove it and re-run.
-
-- [ ] **Step 9: Commit**
-
-  ```bash
-  git add src/renderer/src/components/settings/MobileNetworkInterfaceSection.tsx \
-          src/renderer/src/components/settings/MobileNetworkInterfaceSection.test.tsx
-  git commit -m "feat(mobile-pairing): combobox with manual address entry"
-  ```
-
----
-
-## Task 4: End-to-end verification & PR prep
-
-**Files:** none modified; verification only.
-
-- [ ] **Step 1: Run the four CI checks locally**
-
-  ```bash
-  pnpm lint
-  pnpm typecheck
-  pnpm test
-  pnpm build
-  ```
-  Expected: all green. This is exactly what `.github/workflows/` runs.
-
-- [ ] **Step 2: Manual smoke check**
-
-  If Orca can be launched locally with the desktop build:
-  1. Open Settings → Mobile.
-  2. Click the Network Interface dropdown — confirm both interfaces list.
-  3. Type a tailnet address — confirm the `Use "…"` row appears.
-  4. Click `Use "…"` — confirm the trigger switches to `… (custom)`.
-  5. Click Refresh — confirm the custom selection survives.
-  6. Type an invalid string — confirm the inline error appears and no `Use …` row is shown.
-  7. Type an address that already matches an interface (e.g. `192.168.1.24`) — confirm the `Use` row is hidden and selecting the interface row does NOT show `(custom)`.
-
-  Skip any step that requires a running desktop build and note it in the PR description.
-
-- [ ] **Step 3: Capture before/after screenshots**
-
-  Save screenshots to a temp directory (NOT to the repo — `CONTRIBUTING.md` and `AGENTS.md` forbid committing PR evidence images). Use gstack browse if running the production binary:
-  ```bash
-  $HOME/.claude/skills/gstack/browse/dist/browse screenshot /tmp/orca-mobile-section-before.png --selector ...
-  ```
-  Attach the screenshots to the PR conversation (never use `gh-attach`).
-
-- [ ] **Step 4: Push the branch and draft the PR**
-
-  ```bash
-  git push origin HEAD
-  gh pr create \
-    --title "feat(mobile-pairing): combobox with manual network address entry" \
-    --body-file /tmp/pr-body.md
-  ```
-
-  The PR body should follow `pull_request_template.md`:
-  - **Summary:** explain that the desktop Network Interface dropdown now accepts a manually-typed IPv4 or Tailscale MagicDNS hostname.
-  - **Screenshots:** link to the conversation-attached screenshots.
-  - **Testing:** check all four `pnpm` boxes; note that `pnpm test` includes the three new test files (`manual-address.test.ts`, `mobile-network-interface-selection.test.ts`, `MobileNetworkInterfaceSection.test.tsx`).
-  - **AI Review Report:** confirm the review checked cross-platform (no platform-specific code; uses shadcn primitives + cmdk patterns already in the codebase), SSH/remote/local compatibility (no change to main-process IPC), agent/integration compatibility (no change), performance (UI re-render cost is bounded by `useMemo` over the interface list), UI quality (follows STYLEGUIDE.md; uses `text-statusRed` for the error), security (no new IPC; the address flows through the existing `selectedAddress` prop which `MobilePairingQrSection` already validated).
-  - **Security Audit:** no new IPC, no new auth surface, no new dependency, no new env var. The parser rejects malformed input early so the QR endpoint never sees invalid data.
-  - **Notes:** none — single platform-agnostic renderer change.
-  - **X handle:** include the contributor's X handle per CONTRIBUTING.md so maintainers can shout out.
-
-- [ ] **Step 5: Request review**
-
-  ```bash
-  gh pr edit --add-reviewer <maintainer-handle>
-  ```
-  Or comment `@<maintainer>` in the PR if reviewer auto-assignment isn't available.
-
----
-
-## Definition of done
-
-- All four `pnpm` checks pass locally.
-- All new and existing tests pass.
-- The component renders correctly in a smoke test (or smoke-test steps are documented as skipped in the PR).
-- The PR is open with a body matching `pull_request_template.md`.
-- The contributor's X handle is in the PR description.
diff --git a/docs/reference/plans/2026-07-10-ssh-repo-host-reconciliation.md b/docs/reference/plans/2026-07-10-ssh-repo-host-reconciliation.md
deleted file mode 100644
index ac3249d306e..00000000000
--- a/docs/reference/plans/2026-07-10-ssh-repo-host-reconciliation.md
+++ /dev/null
@@ -1,131 +0,0 @@
-# SSH Repo Host Reconciliation Design
-
-Date: 2026-07-10
-
-## Problem
-
-The proven flow is **Settings -> SSH -> remove host -> re-add the same host**. Main matches the
-removal tombstone and `Store.reassignSshTargetId` moves the persisted repo from the old target ID to
-the new target ID without changing `Repo.id`. A renderer catalog merge can then retain the cached
-old-target row alongside the fetched new-target row because repo rows are keyed by execution host
-and repo ID.
-
-The stale row can route a terminal or destructive action to a removed SSH target. PR #7997 made
-worktree deletion host-scoped and fail closed; this follow-up removes the superseded renderer row
-without weakening that boundary.
-
-## Why UUID Inference Is Unsafe
-
-The same `Repo.id` can legitimately exist on multiple hosts. For example, a local checkout and a
-checkout on an SSH server can share the repository UUID. Removing the SSH host without re-adding it
-must keep the SSH ghost visible so the user can forget it. A local or runtime row with the same UUID
-does not prove that the SSH row moved.
-
-Main already has exact migration evidence. `readoptOrphanedWorkspacesForTarget` selects a removed
-target tombstone, and `Store.reassignSshTargetId` knows which repo IDs it moved from that old target
-to the new target. The renderer must consume this evidence instead of inferring migration from live
-siblings or SSH target metadata.
-
-## Ordering Gap
-
-Main sends `repos:changed` before `ssh:addTarget` or `ssh:importConfig` returns. Either order is
-possible in renderer state:
-
-1. The catalog transaction can merge old and new rows before the add response supplies migration
-   evidence.
-2. The add response can supply evidence while renderer state still contains only the old row.
-
-Evidence must therefore remain pending until the corresponding new direct-SSH row arrives. At that
-point the renderer removes only the mapped `(repoId, oldTargetId)` row and its old host setup, and
-moves cached worktree ownership onto the new host.
-
-## Non-Goals
-
-- Do not re-key repo or worktree UUIDs or introduce compound serialized IDs.
-- Do not infer host migration from labels, paths, target-list absence, or same-UUID siblings.
-- Do not remove PR #7997's execution-host context from destructive operations.
-- Do not change git-provider behavior or add provider-specific assumptions.
-
-## Design
-
-1. `Store.reassignSshTargetId` returns the exact repo IDs it moved instead of only a count.
-2. Main records a list of `{ oldTargetId, newTargetId, repoIds }` for each add/import operation.
-3. The SSH IPC add and import results return the changed targets plus this migration evidence. Main
-   still sends `repos:changed` when at least one repo moved.
-4. Both desktop SSH management surfaces record the evidence in the repo slice immediately after the
-   invoke resolves. The web preload returns an empty evidence list because target management is
-   desktop-only.
-5. The repo slice merges duplicate evidence and keeps unresolved repo IDs pending. Every local,
-   targeted-runtime, and all-host catalog transaction reconciles against the latest pending set.
-6. Reconciliation requires the exact new direct-SSH owner to exist before pruning the exact old
-   direct-SSH owner. Local rows, runtime-owned rows, unrelated SSH hosts, and same-UUID siblings are
-   not considered evidence.
-7. When a repo row is pruned, its matching `ProjectHostSetup` is removed. The desktop catalog owns
-   local and direct-SSH setups; `runtime:<environmentId>` setups remain authoritative on the remote
-   Orca server.
-8. Cached visible and detected worktree rows for the migrated repo are moved from the exact old SSH
-   host to the new host. If a new-host worktree row already arrived, it wins and the stale duplicate
-   is discarded.
-9. A host-scoped worktree response is ignored if its captured repo/host owner no longer exists.
-   Repo catalog transactions also reapply pending worktree migration, covering responses that land
-   after evidence arrives but before the new repo row.
-
-```text
-main: remove target -> tombstone
-main: re-add matching identity -> reassign old target ID to new target ID
-main: return exact (old target, new target, moved repo IDs)
-renderer: retain evidence until catalog includes the exact new SSH owner
-renderer: remove only the exact old SSH row/setup and migrate cached worktree ownership
-```
-
-## Safety Constraints
-
-- A local or runtime sibling with the same UUID never supersedes an SSH ghost.
-- A mapping is not consumed until the exact new direct-SSH row exists.
-- Runtime-owned SSH rows and `runtime:<environmentId>` setup rows remain untouched.
-- Catalog transactions reconcile inside the Zustand updater so overlapping responses use the latest
-  repos and pending evidence.
-- Missing, offline, or unhydrated target metadata is not deletion or migration evidence.
-
-## Test Plan
-
-- Persistence returns exact migrated repo IDs and leaves other hosts untouched.
-- Tombstone re-adoption returns exact old/new/repo mappings for manual add and multi-host import.
-- SSH IPC returns the evidence, sends `repos:changed`, and clears operation-local evidence.
-- Pure renderer tests prove exact pruning, pending evidence, unrelated-host preservation, runtime
-  ownership preservation, and evidence deduplication.
-- Store tests cover both event orders: catalog first and evidence first.
-- Remove-without-re-add keeps a forgettable SSH row and setup when a local repo shares its UUID.
-- Old direct-SSH setups are removed only for proven migrations; runtime setups remain.
-- Old/new cached worktree duplicates collapse to the authoritative new-host row, and an old-only
-  worktree row migrates to the exact new host.
-- A deferred old-host worktree response cannot restore old visible or detected ownership after the
-  new repo catalog consumes the migration evidence.
-- Targeted runtime and all-host catalog transactions reconcile against the latest state.
-
-Run focused tests, typecheck, lint, `pnpm check:max-lines-ratchet`, and the production build required
-by the repository.
-
-## Electron Validation
-
-Use an isolated profile and a throwaway Linux SSH target:
-
-1. Add a repo through the throwaway SSH target.
-2. Remove the SSH target and re-add the same identity without restarting the renderer.
-3. Confirm exactly one SSH project row remains and its worktree opens.
-4. Confirm Explorer lists the remote files without an ambiguous-host routing error.
-5. Repeat the cycle and confirm the stale row does not return.
-6. Keep an adjacent local project visible and confirm it remains unchanged.
-
-There is no new control or copy. The behavioral evidence is the stable row, successful workspace
-routing, and deterministic store assertions.
-
-## Performance And Scope
-
-Renderer reconciliation indexes direct SSH repo owners once, then processes each migrated repo ID
-once. Setup cleanup is linear in current repos and setups. The change adds no polling, listeners,
-subprocesses, or persistent renderer state. IPC payload growth is bounded by the repo IDs actually
-migrated during the user-triggered add/import operation.
-
-Windows and POSIX paths do not participate in reconciliation. SSH identity matching remains the
-existing strict alias or host/user/port logic, and git-provider identity is not used.
diff --git a/docs/reference/project-ordering-mode.md b/docs/reference/project-ordering-mode.md
deleted file mode 100644
index 4cdc159551b..00000000000
--- a/docs/reference/project-ordering-mode.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# Project Ordering Mode
-
-## Problem
-
-The sidebar can group workspaces by project, but project header order is currently coupled to workspace sorting instead of having its own user choice.
-
-- `src/renderer/src/components/sidebar/SidebarWorkspaceOptionsMenu.tsx:59` defines one `Sort by` control for workspaces; it has no separate project-order setting.
-- `src/renderer/src/store/slices/ui.ts:723` stores only `sortBy`, and `src/shared/types.ts:2543` persists the same workspace sort field.
-- `src/renderer/src/components/sidebar/worktree-list-groups.ts:36` derives `ProjectGroupOrdering` from `sortBy`, so project headers follow the highest-ranked visible workspace in Recent/Smart and fall back to manual order otherwise.
-- `src/renderer/src/components/sidebar/WorktreeList.tsx:3765` computes the ordered workspace ids, and `src/renderer/src/components/sidebar/WorktreeList.tsx:4060` feeds the derived project ordering into `buildRows(...)`.
-- `src/renderer/src/components/sidebar/WorktreeList.tsx:826` only enables project-header drag when project grouping is manual and there are no Project Groups.
-- `src/renderer/src/components/sidebar/project-header-drag.ts:1` already implements pointer-based project header dragging for virtualized rows, and `src/renderer/src/store/slices/repos.ts:699`, `src/main/ipc/repos.ts:1029`, and `src/main/persistence.ts:2497` already persist whole-repo manual reorders.
-
-Result: users cannot choose Manual vs Recent ordering specifically for projects, the default is not Manual, and changing workspace sort can unexpectedly reorder projects.
-
-## Goal
-
-Add a project-only ordering preference with two modes:
-
-- `Manual`, the default. Project headers render in the persisted manual project order, and users can drag project headers to reorder them.
-- `Recent`. Project headers render by the most recent visible workspace activity in each project.
-
-This must affect only project header order in `groupBy: 'repo'`. Worktree/workspace rows inside each project must continue to use the existing workspace `sortBy`, filtering, pinning, lineage, status, and manual-order behavior.
-
-## Non-goals
-
-- Do not change `sortBy` semantics or the workspace `Sort by` control.
-- Do not change worktree `manualOrder`, `sortOrder`, `lastActivityAt`, or `buildWorktreeComparator(...)`.
-- Do not reorder worktrees inside a project when the project ordering mode changes.
-- Do not change Project Group header order; groups continue to use `ProjectGroup.tabOrder`.
-- Do not add GitHub-specific behavior. Repo/project ordering must remain provider-neutral and work for GitLab, folder projects, local repos, SSH repos, and runtime environments.
-- Do not add telemetry in this pass unless a later product requirement asks for it.
-
-## Design
-
-1. Add a persisted project-order preference.
-   - Introduce `ProjectOrderBy = 'manual' | 'recent'` in `src/shared/types.ts` or a concrete sidebar ordering module.
-   - Add `projectOrderBy: ProjectOrderBy` to `PersistedUIState`, defaulting to `'manual'` in `getDefaultUIState()` (`src/shared/constants.ts:387`).
-   - Add `projectOrderBy` and `setProjectOrderBy` to the UI slice next to `sortBy` (`src/renderer/src/store/slices/ui.ts:723`). Like `setSortBy`, this setter is a bare `set({...})` — it does not persist on its own.
-   - Persist through the debounced UI writer, not the setter. `sortBy`/`groupBy` reach disk only via the explicit field list in `App.tsx`'s `window.api.ui.set({...})` effect (`src/renderer/src/App.tsx:1019`) plus its dependency array (`src/renderer/src/App.tsx:1042`). Add `projectOrderBy` to both, or the value lives only in memory and silently resets to `'manual'` every restart.
-   - Normalize persisted values in `src/main/persistence.ts` the same way `sortBy` is normalized at `src/main/persistence.ts:323`, and wire the normalizer into both `getUI()` (`src/main/persistence.ts:3116`) and `updateUI()` (`src/main/persistence.ts:3147`); invalid or missing values resolve to `'manual'`.
-   - Hydration in `src/renderer/src/store/slices/ui.ts:1862` should read the normalized value without migrating existing `sortBy`.
-
-2. Expose the choice in the sidebar options menu.
-   - In `SidebarWorkspaceOptionsMenu`, keep the existing `Sort by` submenu as workspace sorting.
-   - Add a second radio submenu labeled `Project order` with `Manual` and `Recent`.
-   - Show it only when `groupBy === 'repo'`, because project ordering has no visible effect in `none`, `workspace-status`, or `pr-status`.
-   - Use existing `DropdownMenuRadioGroup` and sidebar/menu styling from `docs/STYLEGUIDE.md`; no new tokens or custom colors.
-   - Copy should make the scope clear: Manual description `Drag projects to arrange them`; Recent description `Most recent workspace activity`.
-
-3. Decouple project header ordering from workspace sorting.
-   - Replace `getProjectGroupOrdering(groupBy, sortBy)` with a project-order resolver that depends on `groupBy` and `projectOrderBy`, not workspace `sortBy`.
-   - Update `buildRows(...)` so `groupBy !== 'repo'` ignores project order, `projectOrderBy === 'manual'` uses persisted manual ranks, and `projectOrderBy === 'recent'` sorts project header entries by a per-repo recent timestamp.
-   - Recent must be timestamp-based, not first-encounter. Today's `'visible-worktree-order'` path (`src/renderer/src/components/sidebar/worktree-list-groups.ts:548`) works only because the caller pre-sorts the worktree array by recency when `sortBy` is `recent`/`smart`. Decoupling from `sortBy` removes that guarantee — the incoming array may be name- or manual-sorted — so the Recent resolver must explicitly compute `max(lastActivityAt)` per repo rather than relying on encounter order.
-   - Recent project rank should be the maximum `lastActivityAt` among that repo's visible, unpinned worktrees passed into `buildRows(...)`. Empty placeholder projects and imported-worktree-card-only projects fall back to `Repo.addedAt`, then manual rank, then label.
-   - Do not reorder `group.items`; only reorder the project header entries before `appendOrderedGroups(...)`. This preserves the existing `orderMainWorktreeFirst(...)` and workspace row ordering at `src/renderer/src/components/sidebar/worktree-list-groups.ts:632`.
-   - With Project Groups, keep group headers ordered by `tabOrder`; apply Manual/Recent only to project entries within each group or the ungrouped bucket.
-
-4. Make Manual drag/drop project-scoped (no-Project-Groups case only in v1).
-   - Enable project header dragging when `groupBy === 'repo' && projectOrderBy === 'manual'`, regardless of workspace `sortBy`. Today `canReorderRepoHeaders` is additionally gated on `!hasProjectGroups` (`src/renderer/src/components/sidebar/WorktreeList.tsx:827`); the only change here is dropping the `sortBy`-derived `projectGroupOrdering` input in favor of `projectOrderBy === 'manual'`. The `!hasProjectGroups` gate stays.
-   - Keep using pointer events from `project-header-drag.ts` unchanged; the virtualized-row reasoning at `src/renderer/src/components/sidebar/project-header-drag.ts:3` still applies. For the no-Project-Groups case it already does exactly what we need: a flat whole-list permutation committed through `reorderRepos(...)`, preserving current behavior and IPC rejection semantics.
-   - Continue to suppress click-to-collapse only after a promoted drag, matching `src/renderer/src/components/sidebar/project-header-drag.ts:142`.
-   - Defer grouped (within-Project-Group) drag to a follow-up. `useRepoHeaderDrag` is built for a single flat `orderedRepoIds` permutation: `endDrag` (`src/renderer/src/components/sidebar/project-header-drag.ts:130`) computes `fromIndex`/`insertAt` over one array and calls `onCommit` → `reorderRepos`, and `onHandlePointerDown` (`src/renderer/src/components/sidebar/project-header-drag.ts:300`) snapshots every on-screen `[data-repo-header-id]` with no notion of group boundaries. Supporting in-group reorder needs new hook logic — bucket-aware drop targets, rejecting drops outside the source sibling bucket, computing a midpoint between neighbor `projectGroupOrder` values, and a second commit mode that calls `moveProjectToGroup(projectId, sameGroupId, order)` (`src/renderer/src/store/slices/repos.ts:138`) instead of `reorderRepos`. This is its own change and is out of scope for v1.
-   - In v1, Project-Groups users keep the project actions menu as the move surface (it already calls `moveProjectToGroup`). Manual project order still applies to their headers via the row-builder sort (step 3); only drag-to-reorder is unavailable inside groups.
-   - Do not turn a project reorder drag into a cross-group move in any version. The existing project actions menu remains the cross-group move surface.
-
-5. Keep persistence and runtime parity intact.
-   - Local no-group manual reorder continues through `repos:reorder` (`src/main/ipc/repos.ts:1029`) and `Store.reorderRepos(...)` (`src/main/persistence.ts:2497`).
-   - Remote no-group manual reorder continues through `repo.reorder` (`src/renderer/src/store/slices/repos.ts:723`).
-   - Grouped manual reorder via drag is deferred (see step 4); the follow-up would route through `projectGroup.moveProject` / `moveProjectToGroup(...)`, which already handles local and runtime-environment calls. In v1, grouped projects move only through the existing actions menu.
-   - The project-order preference is renderer UI state, not repo metadata. It persists through the `App.tsx` debounced `window.api.ui.set({...})` writer (step 1), not through any repo record.
-
-6. Tests.
-   - Add row-builder tests proving `projectOrderBy: 'manual'` orders project headers by `repoOrder` without changing workspace row order.
-   - Add row-builder tests proving `projectOrderBy: 'recent'` orders project headers by max visible `worktree.lastActivityAt` while preserving each project's child row order.
-   - Add Project Group tests for Manual and Recent within groups, plus unchanged `ProjectGroup.tabOrder`.
-   - Rewrite, do not extend, the existing Recent/`getProjectGroupOrdering` tests. The current cases at `src/renderer/src/components/sidebar/worktree-list-groups.test.ts:639` ("orders repo headers by first encounter…"), `:663` ("…highest-ranked visible child"), and the `getProjectGroupOrdering` block at `:752` all assert the old first-encounter coupling and are semantically incompatible with timestamp-based Recent. Replace them with tests for the new resolver and the `max(lastActivityAt)` ordering.
-   - Add UI slice/persistence normalization tests for default Manual, invalid value fallback, and hydration. Include a persistence-writer test (or note) that `projectOrderBy` is part of the `App.tsx` `ui.set` payload so it actually round-trips across restart.
-   - Grouped manual drag persistence tests are deferred with the grouped-drag feature (step 4).
-
-## Edge cases
-
-- Existing users with no `projectOrderBy` get Manual, even if their workspace `sortBy` is Recent.
-- Changing workspace `sortBy` must not change project header order unless `projectOrderBy === 'recent'` and the visible worktree set/activity data changes.
-- Changing `projectOrderBy` must not mutate any worktree `manualOrder` or repo order by itself.
-- Manual drag while a project is added or removed can race. Whole-repo reorder (the only v1 drag path) keeps the existing permutation rejection and refetch behavior. (Grouped midpoint writes and their refetch-on-failure handling come with the deferred grouped-drag follow-up.)
-- In Recent mode, projects with no visible worktrees should still render when they are placeholders or imported-worktree-card candidates; they sort after projects with activity.
-- Pinned worktrees remain in the Pinned section. They should not make their project jump in Recent ordering unless an unpinned visible workspace in that project is also recent.
-- Filters and hidden sleeping/default-branch workspaces affect the visible worktree set. Recent project order should reflect the rows the user can currently see.
-- Project Group collapse state must not change when the order mode changes.
-- Dragging a project inside a collapsed Project Group is impossible because its repo headers are not mounted; no special handling is needed.
-- Dragging across Project Group boundaries should not silently move the project; cross-group moves stay on the actions menu. (In v1 there is no in-group drag at all — see step 4 — so this only constrains the deferred grouped-drag follow-up.)
-- SSH/runtime projects must use the same store actions as local projects. No local filesystem path assumptions are needed.
-- Folder projects have synthetic worktrees and should participate through the same `lastActivityAt` and manual repo order paths.
-- Multi-window or external mutations are last-writer-wins through existing persistence. A rejected whole-repo permutation refetches repos (existing behavior); a failed grouped move would do the same once grouped drag lands.
-- Behavior change on upgrade: existing users on `sortBy: recent`/`smart` currently see project headers bubble to follow workspace activity. After this change they default to Manual project order, so headers stop bubbling until they pick Recent in the new submenu. This is intended (matches the "no `projectOrderBy` → Manual" edge case) but is a visible change worth calling out in release notes.
-
-## Rollout
-
-1. Add `ProjectOrderBy` types/defaults/normalization, the UI slice setter, the `App.tsx` debounced-writer field, and persistence `getUI()`/`updateUI()` wiring.
-2. Add the `Project order` submenu in `SidebarWorkspaceOptionsMenu`.
-3. Update `WorktreeList` to read `projectOrderBy`, pass it to row construction, and enable project drag only in Manual project order (no-Project-Groups case, keeping the `!hasProjectGroups` gate).
-4. Update `worktree-list-groups.ts` to order project headers by Manual or Recent independently from workspace `sortBy`, with Recent using `max(lastActivityAt)` per repo.
-5. Add focused row-builder and UI persistence/round-trip tests; rewrite the incompatible first-encounter/`getProjectGroupOrdering` tests.
-6. Run targeted Vitest for sidebar row ordering and repo slice tests, then `pnpm typecheck` and `pnpm lint`.
-7. Validate in Electron: default startup shows Manual project order, the choice survives restart, project drag/drop reorders project headers only (ungrouped), Recent project order follows workspace activity, and worktree rows inside each project do not change when toggling project order.
-
-Deferred follow-up (separate change): extend `useRepoHeaderDrag` for grouped sibling buckets — bucket-aware drop targets and a second commit mode using `moveProjectToGroup(...)` midpoint ordering inside Project Groups — plus its grouped-drag persistence tests.
diff --git a/docs/reference/reliability-gates-implementation-plan.md b/docs/reference/reliability-gates-implementation-plan.md
deleted file mode 100644
index 818bdb175e1..00000000000
--- a/docs/reference/reliability-gates-implementation-plan.md
+++ /dev/null
@@ -1,783 +0,0 @@
-# Reliability Gates Implementation Plan
-
-Date: 2026-07-02
-
-Source context: [`docs/reference/reliability-pain-points-2026-06-30.md`](./reliability-pain-points-2026-06-30.md).
-
-## Current Status
-
-Last updated: 2026-07-03.
-
-The first repo-side reliability batch is useful, but it should be treated as a first-layer regression net, not a finished terminal reliability program. Before final merge claims, rebase or retarget the stack onto fresh `origin/main` and verify it still includes the protections that landed there after the branch was cut.
-
-Stack topology facts the rest of this plan depends on (verified 2026-07-02):
-
-- `brennanb2025/fix-terminal-reliability` is simultaneously the integration worktree and the head branch of #7001, and it is the base branch of all five child PRs (#7004-#7008). Committing broad product changes to it would turn #7001 into the single large terminal PR this plan forbids and would silently change every child PR's diff.
-- The committed branch contains only the manifest, checker, checker tests, and these docs (a 5-gate manifest as committed). Everything else this plan describes — the expanded manifest, product hardening, and new or updated tests across roughly 39 modified files plus 3 untracked files — exists only as uncommitted working-tree changes in this worktree. No evidence run below is reproducible from any pushed ref until the split branches are committed and pushed.
-- The branch's merge-base with `origin/main` is roughly 97 commits stale. Fresh main renamed `terminal-webgl-paste-recovery.{ts,test.ts}` to `terminal-webgl-atlas-recovery.{ts,test.ts}` in #6949, so the current `xterm-addon.boundary-containment` manifest entry and its documented command break on rebase; see Fresh-Eyes Corrections.
-- The manifest is the single source of truth for gate counts and per-gate status. Where this document records counts they are dated snapshots; `pnpm run check:reliability-gates` prints the current gate total.
-
-Known Orca PR stack:
-
-- [#7001](https://github.com/stablyai/orca/pull/7001), `Add reliability gate manifest`: merged on 2026-07-03. The manifest, checker, and plan docs are on main; [#7295](https://github.com/stablyai/orca/pull/7295) hardens the checker policy and registers the merged #7133/#7148/#7173/#7192 regression tests as partial gates with fresh main-side evidence.
-- [#7005](https://github.com/stablyai/orca/pull/7005), `Add terminal snapshot freshness contract gate`: depends on #7001 and protects the stale-liveness/newborn-PTY class behind `terminal-session.snapshot-freshness`.
-- [#7008](https://github.com/stablyai/orca/pull/7008), `Expand provider session replay ownership gate`: depends on #7001 and protects the agent/provider ownership class behind `agent-session.provider-ownership`.
-- [#7004](https://github.com/stablyai/orca/pull/7004), `Contain xterm addon failures to terminal panes`: depends on #7001. The current branch has a first executable xterm containment slice for addon load, link-provider, search, and WebGL failure containment; it still needs live typed input/output survival before promotion.
-- [#7006](https://github.com/stablyai/orca/pull/7006), `Prove visible terminal size convergence`: depends on #7001. The current branch now has a first deterministic renderer/main contract slice for post-spawn reconcile, split-right 0x0 recovery, applied `pty:getSize`, and resume-time size reassertion; it still needs live shell, SSH/remote, and Windows ConPTY geometry proof before promotion.
-- [#7007](https://github.com/stablyai/orca/pull/7007), `Add persisted session upgrade fixture gate`: depends on #7001. The current manifest entry is still commandless in this branch, so treat it as a registered startup-upgrade gap until immutable fixture commands are wired.
-
-Merged related product hardening:
-
-- [#7054](https://github.com/stablyai/orca/pull/7054), `Prevent hidden terminal TUI overlap`: merged on 2026-07-01 with `verify`, Wayland terminal input, golden Linux E2E, golden mac E2E, and community tracking checks passing. This fixes the hidden regular-terminal TUI overlap class by scheduling bounded post-parse WebGL atlas recovery for risky hidden TUI redraws while keeping hidden bytes on the background write path.
-- [#7133](https://github.com/stablyai/orca/pull/7133), `Fix stale terminal frames on worktree return`: merged on 2026-07-02 as a high-priority regression fix, root-caused on a live repro. Hidden-output restore skipped the destructive clear for alternate-screen snapshots, `?1049h` is a no-op on a pane already on the alt screen, and serialized frames skip blank cells, so the pre-hide frame bled through the final frame until a select or resize. The fix writes an alt-only `\x1b[?1049h\x1b[2J\x1b[H` preamble before alt-screen snapshot data (normal-buffer scrollback untouched, still no `3J`) and hardens the WebGL reveal path: dispose-on-bail with a single-addon invariant, refresh-always atlas reset, and a settled-frame pane-scoped repaint on tab reveal, worktree resume, and window wake. It supersedes the reverted #7058 approach and closes the alt-screen hole that #7054's hidden-output skip machinery made load-bearing. Its deterministic tests — the alt-only-clear-before-snapshot assertions in `pty-connection.test.ts`, plus `pane-webgl-renderer.test.ts`, `pane-reveal-repaint.test.ts`, and `terminal-visibility-resume.test.ts` — are the seed assertions for `terminal-output.scrollback-restore` and the WebGL side of `xterm-addon.boundary-containment` once the stack rebases.
-
-- [#7148](https://github.com/stablyai/orca/pull/7148), `Match main terminal mirror character widths to the renderer`: merged on 2026-07-02, hours after #7133. Root cause of the residual post-#7133 bottom-row tears: the renderer xterm measures with Unicode 11 + ZWJ joining while the daemon headless mirror used default-width tables, so every positioned write after an emoji lands shifted and the tears are baked into the very mirror that restores replay — #7133's clear made restores faithful to the mirror and exposed it. The fix moves the unicode provider to `src/shared/terminal-unicode-provider.ts` and activates it in the headless emulator. Its red-green width test, `src/main/daemon/headless-emulator-unicode-width.test.ts` on main, is the seed assertion for the new `terminal-mirror.parser-parity` gate, and the shared provider plus `pane-terminal-options.ts` are the shared-construction seams that gate must assert on. #7148 also touches `pane-lifecycle.ts`, which both this worktree and #7004's branch modify — another confirmed rebase-conflict site.
-- [#7173](https://github.com/stablyai/orca/pull/7173), `Fix Codex pane output tearing after app occlusion`: merged on 2026-07-03. A delayed background-origin Codex chunk carrying a stateful query could take the hidden live-write path after a newer snapshot restore had already rebuilt the renderer, overwriting newer state; an adversarial review pass added seq-restart guards so revived sessions (hibernation wake, kill plus cold-restore under the same PTY id) cannot silently freeze hidden output against a stale seq high-water mark. Its three red-proven tests in `pty-connection.test.ts` on main — reference-parse buffer equality over the ordered raw stream plus both revival guards — are exactly the exactness-oracle shape this plan prescribes and seed the hidden/live interleaving slice of `terminal-output.scrollback-restore`.
-- [#7192](https://github.com/stablyai/orca/pull/7192), `Keep runtime mirror sized with desktop terminal resizes`: merged on 2026-07-03. Desktop `pty:resize` updated the PTY and renderer but never the runtime mirror, so the mirror parsed all subsequent bytes at its birth width, soft-wrapped TUI repaints into a corrupted ladder, and baked that corruption into every restore snapshot; the fix fans accepted desktop resizes to the mirror and serializes mirror reflow with queued output writes on the per-PTY write chain. This exposed a plan gap now fixed: the runtime mirror is a geometry authority in its own right, and renderer-vs-mirror convergence checks cannot see corruption upstream of the mirror. Its red-proven tests in `orca-runtime.test.ts` and `pty.test.ts` on main seed the mirror-geometry slice of `terminal-geometry.visible-convergence`.
-
-Factory and skill status:
-
-- [orca-internal #491](https://github.com/stablyai/orca-internal/pull/491), `Require reliability gates in factory reviews`: merged on 2026-07-01. This updates the factory review flow so terminal/session/provider/startup/release changes must name the relevant reliability class, invariant, gate or accepted gap, and validation evidence.
-- [orca-internal #493](https://github.com/stablyai/orca-internal/pull/493), `Add Playwright reliability test skill`: as last reviewed, this still needed rebase/regeneration before merge because the reliability plan depends on Playwright tests being evidence-based, low-flake, and tied to named invariants.
-
-Remaining work:
-
-- Rebase or retarget the reliability stack on fresh `origin/main` before making final merge claims. Current main already contains terminal fixes that the stack must absorb, including hidden TUI overlap, input-lag, scrollback replay, Windows ConPTY keyboard reset, resume width flicker, remote mirror polling, and the #7133 stale alt-screen frame fixes. As part of the rebase, mechanically verify every declared `testFiles` entry in the manifest exists on fresh `origin/main`; the #6949 WebGL rename is a confirmed break. #7133 (merged 2026-07-02) touches `pty-connection.{ts,test.ts}` and `use-terminal-pane-global-effects.test.ts`, which this worktree also modifies, and `pane-webgl-renderer.{ts,test.ts}`, which #7004's branch also edits — expect real conflicts there. #7148 (merged 2026-07-02) additionally touches `pane-lifecycle.ts` and `headless-emulator.ts`, so the worktree's and #7004's pane-lifecycle edits must absorb its shared unicode-provider wiring. #7173 (merged 2026-07-03) rewrites the hidden live-write path in `pty-connection.{ts,test.ts}` and #7192 (merged 2026-07-03) touches `pty.test.ts` — both carry heavy worktree modifications, so the conflict surface keeps widening the longer the rebase waits. This worktree's replay/SSH/backpressure changes and #7004's containment changes must be rebased over #7133's alt-clear preamble, #7148's width fix, #7173's seq filtering, #7192's mirror resize fan-out, and the reveal-repaint hardening without weakening any side.
-- Materialize the split: commit each uncommitted working-tree slice to its owning branch per the file assignment in the PR Split Plan, reset diverged child branches from the worktree versions of their files, and push. Only manifest, checker, and doc changes may be committed to `brennanb2025/fix-terminal-reliability` itself.
-- Wire the aggregated non-blocking `reliability-gates` CI job (see Evidence Provenance And CI Wiring) so runtime and flake history accrue with machine provenance instead of hand-entered evidence.
-- Split the current integration branch into focused PRs before final review and merge. Do not land this as one large terminal reliability PR; each PR should have its own invariant, evidence command, residual gaps, dependency note, and follow-up relationship to the rest of the stack.
-- #7001 merged on 2026-07-03. Merge the gate-specific PRs only after resetting each from the worktree slice per the file assignment.
-- Before merging each child PR, recheck it against the latest #7001/main because the shared manifest file can create normal stack drift or conflicts even when the PR currently reports clean.
-- After merge, run the registered gate commands in soak and record runtime/flake evidence before promoting any gate to blocking.
-- Update the factory skills again after the repo-side gate commands and CI jobs are stable, so agents can invoke exact commands instead of only requiring reliability evidence.
-- Keep #7054's accepted gap visible: deterministic Claude-like TUI streams validated the renderer path, but live Claude Code was not part of that PR's validation. #7133 has since closed the alt-screen snapshot-restore hole in the same hidden-output machinery, and its buffer-merge root cause is exactly the class the `terminal-output.scrollback-restore` gate must make hard to reintroduce; the live-Claude validation gap remains.
-
-## PR Split Plan
-
-The current `brennanb2025/fix-terminal-reliability` branch is an integration branch, not the desired final review shape. It should be split into smaller PRs so reviewers can verify one reliability class at a time, bisect failures, and avoid merging a broad terminal lifecycle change without understanding which protection each file belongs to.
-
-Branch and manifest ownership rules:
-
-1. `brennanb2025/fix-terminal-reliability` is #7001's head branch. Only manifest, checker, checker-test, and plan-doc changes may be committed to it. Split items 2-6 go to their own branches, stacked on this branch and retargeted to `main` after #7001 merges.
-2. #7001 may only declare gates whose `testFiles` all exist on `origin/main`. The checker's declared-file rule makes this self-enforcing: a manifest entry whose test files land in a later PR cannot pass CI inside #7001.
-3. Every later PR owns its own manifest entries. It adds or upgrades the gates it implements — entry, `evidenceRuns`, and `assertionRefs` — in the same PR as the tests and hardening they reference. The manifest file is shared, but each entry has exactly one owning PR, and manifest conflicts are resolved by entry ownership, never by hand-merging divergent copies of an entry.
-4. Commandless registered-gap entries (`protection: "none"`, no test files) may ride in #7001 because they reference nothing that can drift.
-5. The integration worktree is the single authoritative copy of every overlapping file. Child branches that have diverged (for example, `resume-sleeping-agent-session.ts` on #7008's branch is ~156 diff lines behind this worktree) must be reset from the worktree slice, not reconciled by hand.
-
-Recommended split:
-
-1. Reliability gate manifest and plan docs.
-   This PR owns `config/reliability-gates.jsonc`, the manifest checker hardening, checker tests, and this plan document. It should merge first because later PRs reference gate ids, evidence metadata, and promotion rules from the manifest. It should not include terminal product behavior changes.
-
-2. Provider ownership and session replay safety.
-   This PR owns the agent/provider identity invariant: activation, restore, sleep, hibernate, dedupe, clearing, and reconnect paths must not replay a provider session that is already owned, queued, pending, retained, or live in the workspace. It should include the provider-session ownership tests, repeat-activation lower-layer proofs, automatic resume claim coverage, same-session/wrong-session hook coverage, and any narrowly required product hardening.
-
-3. Startup hydration, provider fanout, and targeted liveness.
-   This PR owns startup-adjacent PTY registry hydration, targeted `pty.hasPty(id)` liveness, no-hot `pty:listSessions()` paths, Resource Manager polling scoping, SSH/provider unknown-liveness semantics, degraded-daemon fail-closed behavior, and related tests. It should depend on the manifest PR and should explicitly say that live SSH, WSL, remote-runtime, and production startup reconcile remain follow-up gates unless implemented in the same PR.
-
-4. Terminal lifecycle observability.
-   This PR owns compact anomaly breadcrumbs and bounded lifecycle traces for terminal lifecycle diagnosis. It should make failures easier to debug without claiming to prevent them. It should prove that diagnostics are compact, deduped or bounded, privacy-conscious, and included in the right local crash/diagnostic surfaces. Diagnostics-bundle export and live forbidden-transition artifacts should remain visible follow-ups until proven.
-
-5. PTY output, IPC, and performance hardening.
-   This PR owns daemon stream batching, main-to-renderer pending output caps, ACK/backpressure behavior, replay queue bounds, runtime/mobile stream byte budgets, and related perf-sensitive contracts. It needs the hardest review because small behavior changes here can cause input latency, hidden-output, memory, or ordering regressions. It should include explicit runtime budgets and should not promote any perf gate to blocking without soak evidence.
-
-6. Live local PTY and E2E reliability slice.
-   This PR owns the first live Electron/local PTY liveness gate. It should stay small: spawn a real terminal, prove one active PTY, type through focused xterm, verify process-visible output, hide/restore the workspace without duplicating or losing the PTY, resize and verify applied size, then exit and verify cleanup. It should remain `experimental` until CI/runtime history proves it is not flaky. Tab switch, app restart, SSH, WSL, Windows ConPTY, and scrollback restore should be explicit follow-ups unless included with equally strong oracles.
-
-Mapping to the open stack and file assignment:
-
-The six split items and the five open child PRs overlap; this mapping is authoritative. Every working-tree file must land in exactly one PR below. Four files contain changes from multiple reliability classes and must be split by hunk, with the earlier PR in the merge order owning its hunks first: `config/reliability-gates.jsonc` (per-entry ownership), `src/main/ipc/pty.ts` and its test, `src/renderer/src/components/terminal-pane/pty-connection.ts` and its test, and `src/renderer/src/store/slices/terminals.ts`.
-
-1. #7001 (split item 1, manifest and plan docs): `config/scripts/check-reliability-gates.mjs`, `config/scripts/check-reliability-gates.test.mjs`, `docs/reference/reliability-gates-implementation-plan.md`, and the manifest restricted to gates whose test files exist on `origin/main` plus commandless gap entries.
-2. #7008 (split item 2, provider ownership and replay safety): `src/renderer/src/lib/resume-sleeping-agent-session.ts` and test, plus its ownership slice of `terminals.ts`. Reset the branch from the worktree slice; keep the PR number for review continuity.
-3. #7005 (snapshot freshness and targeted renderer liveness): `terminal-dead-session-reconcile.ts` and test, `use-terminal-pane-lifecycle.ts` and test, `use-terminal-pane-global-effects.test.ts`, and the `pty.hasPty` preload/API plumbing (`src/preload/api-types.ts`, `src/preload/index.ts`, `src/renderer/src/web/web-preload-api.ts`, the `hasPty` slice of `src/main/ipc/pty.ts`).
-4. New PR (split item 3, startup hydration, provider contracts, no-hot listing): `hydrate-local-pty-registry.ts` and test, `daemon-pty-adapter.ts` and test, `daemon-pty-router.ts` and test, `degraded-daemon-pty-provider.ts` and test, `pty-session-id.test.ts`, `src/shared/pty-session-id-format.ts`, `src/main/providers/ssh-pty-provider.ts`, `ResourceUsageStatusSegment.tsx`, `resource-manager-session-polling.test.ts` (currently untracked), `store-session-cascades.test.ts`, and the SSH/liveness slices of `pty.ts`, `pty-connection.ts`, and `terminals.ts`.
-5. New PR (split item 4, lifecycle observability): `terminal-lifecycle-diagnostics.ts` and `terminal-lifecycle-diagnostics.test.ts` (currently untracked).
-6. New PR (split item 5, PTY output/IPC/perf hardening): `daemon-stream-data-batcher.ts` and test, `terminal-output-batching.test.ts`, `terminal-subscribe-buffer.test.ts`, and the pending-output-cap and replay/ACK slices of `pty.ts` and `pty-connection.ts`.
-7. #7004 (xterm addon containment, outside the six split items): keep as its own PR; reset `pane-lifecycle.ts` and test from the worktree versions, and adopt fresh main's renamed WebGL test files during rebase.
-8. #7006 (visible geometry, outside the six split items): keep as its own PR; any geometry hunks in `pty-connection.ts` belong to it.
-9. #7007 (persisted upgrade fixtures): the gate is commandless with `protection: "none"`, so its manifest entry rides in #7001 under rule 4. Keep #7007 open only if it will deliver the actual fixture corpus and command; otherwise close it as absorbed.
-10. New PR (split item 6, live local PTY E2E slice): `tests/e2e/terminal-live-pty-liveness.spec.ts` (currently untracked).
-
-Merge order: #7001, then #7008, then #7005, then startup hydration/provider contracts, then lifecycle observability, then PTY output/IPC/perf hardening, then #7004, then #7006, then the live E2E slice. #7007 can merge any time after #7001 or be closed. The stack stays flat on #7001; each child rebases onto the merged state immediately before its own merge, and manifest conflicts are resolved by entry ownership.
-
-If one later PR reveals a missing invariant in an earlier PR, update the earlier manifest entry or PR description before promotion rather than silently broadening the later PR's claim. The split is part of the reliability plan because reviewability, dependency clarity, and targeted rollback are themselves reliability controls.
-
-Each split PR should follow Brennan's PR process before it is considered ready: write a scoped design doc, run delegated design review, implement from the reviewed doc, verify completeness against the original request and reliability gate, audit headline behavior, run `perf`, run the code-review/fix loop, run merge-confidence validation, open an unmerged PR, verify pushed state, and stabilize CodeRabbit/check findings. The PR text should describe that process as "Brennan's PR process"; do not mention the internal skill name in PR-facing text.
-
-## PR Proof Contract
-
-Every split PR must include a short proof section in its PR description before it can be treated as ready. This section should use direct evidence, not confidence language. Avoid absolute claims such as "this guarantees terminal reliability" or "this cannot regress performance." The valid claim is narrower: "this PR is safe to merge because the affected invariant, performance budget, and residual gaps were checked with the evidence below."
-
-Required PR description sections:
-
-- **Reliability invariant:** the class-level rule this PR protects and the recent issue, PR, or accepted gap that motivated it.
-- **Material impact:** why this will meaningfully reduce escaped regressions, including which known bug class becomes harder to reintroduce.
-- **Product change type:** docs/tooling, test-only gate, product hardening, diagnostics, perf hardening, or mixed.
-- **Performance risk inventory:** whether the PR touches typing, focus, tab/workspace switch, visibility resume, resize, render, startup, provider listing, hidden output, PTY output, store subscribers, git/worktree scans, SSH, WSL, Windows, or mobile/relay paths.
-- **No-regression evidence:** the exact count test, deterministic contract test, metric artifact, typecheck, or live run that proves the PR did not add unbounded scans, polling, hidden-pane wake loops, startup awaits, subprocess churn, renderer jank, or output buffering growth.
-- **Correctness evidence:** the exact oracle and command proving the invariant. Tests that only prove implementation shape are not enough.
-- **Provider/platform coverage:** local, daemon, SSH, WSL, remote-runtime, mobile/relay, macOS, Linux, and Windows must be marked covered, unaffected, or accepted-gap.
-- **Residual gaps:** what this PR still does not prove. These gaps must remain in the manifest until a later PR removes them.
-- **Promotion status:** whether the gate is `none`, `partial`, or `active`, and why it is not promoted beyond its current maturity.
-- **Rollback or demotion rule:** what signal should cause the PR's gate to be demoted, disabled, or followed up.
-
-Performance rule:
-
-- A reliability PR is incomplete if it adds polling, global session listing, provider fanout, hidden-pane renderer wakeups, startup-critical awaits, repeated resize IPC, subprocess churn, unbounded output queues, broad store subscriptions, or uncapped diagnostics without a deterministic count test or metric budget.
-- `pty:listSessions()` remains a global management/diagnostic operation, not a hot-path liveness primitive. Typing, focus, tab/workspace switch, visibility resume, resize, render, and per-pane liveness paths should use targeted APIs or cached ownership unless a PR provides measured proof that the broader call is safe.
-- Any PR touching git/worktree scans, SSH git providers, WSL paths, cleanup, or startup repository enumeration must include the `git-crash-perf` style proof: bounded subprocesses, timeout/abort behavior, provider parity, and no startup-critical scan.
-- Any PR touching terminal/session/provider/startup code must use the terminal-session reliability contract plus a performance budget. A green reliability test without a perf proof is not enough.
-- Any PR that changes PTY output, IPC batching, ACK/backpressure, replay, or hidden-output behavior (split item 5 especially) must include a before/after run of an existing terminal perf artifact — `test:e2e:terminal-perf:scale:report` or the typing-latency specs — on the same machine, with both results in the PR description. Deterministic byte/count contracts prove bounds; only the perf artifact proves interactive latency did not regress.
-- The gates themselves are a performance surface. Every command-backed gate must declare a runtime budget in the manifest, unit-layer gate commands should stay in single-digit seconds, and the aggregated CI job in Evidence Provenance And CI Wiring must stay inside its own wall-clock budget so reliability coverage does not degrade the development loop it protects.
-
-Per-PR proof expectations:
-
-1. Reliability gate manifest and plan docs.
-   Performance proof: no runtime product path changes. Checker runtime should stay cheap and deterministic, and manifest validation should not depend on network calls or live providers.
-   Materiality proof: the checker prevents overclaiming by requiring evidence metadata, existing test files, command-backed assertions, covered scope, and clear `none`/`partial`/`active` status.
-
-2. Provider ownership and session replay safety.
-   Performance proof: activation and replay checks must be bounded by indexed workspace-local state, not repeated provider listing or O(records x pending-startups) scans. Tests should include repeat activation and bounded-work assertions where scans are introduced.
-   Materiality proof: this blocks the class where an inactive or hidden but valid provider session is mistaken for unowned and resumed again.
-
-3. Startup hydration, provider fanout, and targeted liveness.
-   Performance proof: startup hydration must not block first usable UI, must expose bounded counters, and must not multiply provider/git scans across repos and worktrees without a budget. Hot interaction paths must prove zero broad `pty:listSessions()` calls.
-   Materiality proof: this prevents stale global snapshots or failed provider observations from closing or replacing the wrong terminal, while reducing session-listing fanout.
-
-4. Terminal lifecycle observability.
-   Performance proof: breadcrumbs and traces must be capped, primitive-only, deduped or ring-buffered, and must not serialize terminal output, filesystem trees, scrollback, or large state. Tests must prove caps and sanitization.
-   Materiality proof: this does not itself prevent regressions, but it materially shortens future diagnosis by preserving the lifecycle facts needed to debug ownership, liveness, restore, resize, and replay failures.
-
-5. PTY output, IPC, and performance hardening.
-   Performance proof: this PR must carry the strongest perf evidence in the stack: byte caps, queue caps, ACK/backpressure ordering, active-output priority, hidden-output behavior, and no unbounded renderer/main buffering. It should not become blocking until soak data shows stable runtime and no unexplained flakes.
-   Materiality proof: this protects the freeze/input-lag/memory-growth class where background or high-volume terminal output harms the active terminal or the app.
-
-6. Live local PTY and E2E reliability slice.
-   Performance proof: the Playwright gate must be small, serial where needed, artifact-producing, and timed. It should prove the user path without becoming a broad slow/flaky suite. Runtime and flake history are required before promotion.
-   Materiality proof: this covers the layer that fake providers cannot prove: real Electron terminal spawn, keyboard input, process-visible output, hide/restore, resize, and cleanup.
-
-## Factory And Skill Follow-Up
-
-The current factory skills are close enough that the next step should be targeted edits, not a large new skill stack. The terminal-specific skill already exists, and Brennan's PR process already requires design review, perf review, code review, validation, pushed-state checks, and PR stabilization. The missing factory behavior is that reviewers and validators should explicitly fail PRs that omit the PR Proof Contract above.
-
-Recommended skill/factory updates:
-
-1. Update `terminal-session-reliability`.
-   Add the PR Proof Contract as a required output for terminal/session/provider/startup PRs. The skill should require reliability invariant, material impact, performance risk inventory, no-regression evidence, provider/platform coverage, residual gaps, promotion status, and rollback/demotion rule.
-
-2. Update `review-code`.
-   Make missing proof-contract sections a review finding for P0-capable terminal/session/provider/startup/release surfaces. Reviewers should not accept "tests pass" as enough when the PR lacks a named invariant, perf budget, provider/platform matrix, or accepted-gap statement.
-
-3. Update `brennan-test-changes`.
-   Require validation reports to say whether the relevant reliability gate command ran, whether the evidence proves the user-visible invariant, whether the test layer is sufficient, and whether any skipped SSH, WSL, Windows, remote-runtime, mobile, or live-Electron path is an accepted gap.
-
-4. Update `playwright-reliability-tests`.
-   Add the live-terminal reliability bar directly: Playwright terminal tests must prove real input/output or visible degraded state, use deterministic event oracles instead of blind sleeps, record runtime/artifacts, and stay `experimental` until flake history supports promotion.
-
-5. Update `perf`.
-   Add the PR Proof Contract's no-regression evidence language so perf reviewers require deterministic count tests or metric artifacts for polling, global session listing, provider fanout, hidden-pane wakeups, startup awaits, subprocess churn, output queue growth, and broad store subscriptions.
-
-6. After the repo-side gate commands stabilize, update factory prompts to invoke exact gate ids and commands.
-   Do this after the PRs land or after their commands are stable enough to reference. Before then, the factory should require the gate class and evidence, but should not hard-code commands that may still split or rename during PR extraction.
-
-Do not add a separate broad "terminal reliability reviewer" skill unless the existing skills fail to enforce this contract after these edits. Too many overlapping skills can make agents diffuse responsibility; the better shape is one terminal reliability contract plus required calls from design, review, perf, Playwright, and validation stages.
-
-## Coverage Reality Check
-
-This first stack is useful, but it must not be described as "terminal reliability is covered." The executable protection in this branch covers a deliberately small first slice of recent escaped classes:
-
-- stale local/daemon liveness snapshots closing newer PTY bindings;
-- provider-session replay ownership for several active, inactive, queued, pending, live, retained, same-session hook, and wrong-session hook records, with real hook timing through Electron still explicitly partial;
-- targeted `hasPty` liveness after visibility resume instead of hot-path global `listSessions`;
-- degraded daemon fallback fail-closed behavior for restored worktree-scoped and legacy/non-scoped ids;
-- SSH provider listing/`hasPty` failures treated as unknown rather than destructive ownership evidence, plus mocked provider/renderer coverage for deferred SSH attach, passphrase cancellation, transient deferred reattach failure, and expired deferred relay fallback;
-- remote replay coalescing, FIFO ordering, and bounded burst-tail coalescing at the renderer unit layer;
-- visible geometry contract behavior for delayed split layout settle, 0x0 split-right recovery, applied-vs-requested `pty:getSize`, and resume-time size reassertion;
-- boot-time local PTY registry hydration counters for repo/worktree enumeration, skipped SSH repos, adapter/session listing, registration/skips, duration, and failure phase;
-- terminal lifecycle anomaly breadcrumbs recorded into renderer crash diagnostics with dedupe and compact identity fields;
-- live local Electron PTY spawn, active PTY listed exactly once, focused xterm keyboard input, process-visible output, repeated workspace hide/restore of the same PTY, actual resize propagation, and exit cleanup.
-
-Those gates should catch re-regressions in those classes, and the tests are intentionally deterministic. They mostly use renderer-unit, renderer-state, provider-contract, or fixture layers because those layers provide precise oracles with low flake risk. That is a strength for the classes they cover.
-
-The manifest also contains commandless registered gaps for persisted-session upgrade fixtures, Windows ConPTY, startup color-query handling, and other future gates. Those entries are useful planning structure, not executable protection. Visible geometry convergence, xterm addon containment, IME/native text forwarding, runtime/mobile streams, and startup hydration counters now have first executable contract slices, but they remain `experimental` until they have repeatable CI/runtime history and red-green evidence. Output backpressure now has daemon stream and main pending-output contract slices, but the broader live perf budget remains experimental until it has repeatable metric artifacts, runtime history, and red-green evidence. The live local PTY gate now has a first executable Playwright slice that includes repeated workspace hide/restore of the same PTY, but it remains `experimental` until it has repeatable CI/runtime history and red-green evidence.
-
-The critique that this stack is still shallow is fair. The current gates do not yet prove:
-
-- tab-switch restore, scrollback after restore, app restart persistence, and non-local live providers;
-- Windows ConPTY behavior, including shell resolution, cursor restore, rewrite repaint, CJK/IME edge cases, kitty/input protocol behavior, and activation hangs;
-- terminal input latency, throughput, hidden-output pressure, renderer CPU, and store/subscriber hot paths under load;
-- IME and synthetic input forwarding across macOS, Windows, Linux/fcitx/Sogou, Vietnamese, CJK, Arabic, paste, and modifier paths;
-- focus recovery after browser/terminal handoffs, tab switches, app restart, and non-local provider restore;
-- daemon degraded spawns, stale bootstrap, remote-runtime startup, SSH/WSL provider boundaries, and mirror polling;
-- scrollback clearing/restoration correctness across hidden output, snapshot replay, and restore.
-
-Those missing classes already appear in the full pain-points report, but this implementation plan should keep them visible so the first stack does not become false confidence.
-
-## Fresh-Eyes Corrections
-
-The follow-up reviews changed the plan in several concrete ways:
-
-- Windows/IME/CJK are not covered by the current executable stack. Orca has useful unit coverage and product logic for local Windows ConPTY compatibility, including withholding Kitty keyboard protocol for local native Windows panes, but no live Windows ConPTY gate proves post-agent ordinary keys, shell parity, CJK repaint, cursor restore, resize readback, or real IME composition.
-- SSH restore is better covered than the first manifest draft said, but only at store/provider/main/renderer contract layers. The current gate asserts deferred wake metadata, deferred attach/passphrase/expired-relay contracts, and unknown-liveness behavior with fake transports; it does not prove a live SSH relay, WSL, remote-runtime mirror polling, false-live visual state, or real network reconnect timing.
-- Perf/backpressure is currently deterministic byte-accounting proof, not live responsiveness proof. The branch asserts daemon `write(false)`/`drain` behavior, cross-session drain priority for flush-immediate output, pure-backpressure cleanup, and main pending-output caps; it does not yet prove renderer parse pressure, event-loop delay, active key latency, or live hidden-output flood behavior.
-- Daemon startup reconcile remains a mechanism, not a production-proven startup behavior. Either wire it with dry-run diagnostics and prior-worktree aliases, or keep it as an accepted gap with a named owner.
-- Gate evidence is still too easy to hand-enter. The checker now prevents obvious metadata overclaims, but it does not prove the registered command was run in CI, preserve artifacts, or verify that each declared assertion executed. Add machine-checkable artifact/CI-run provenance before promoting gates to blocking.
-- Manifest evidence in this worktree is not yet durable. Three referenced test files are untracked (`resource-manager-session-polling.test.ts`, `terminal-lifecycle-diagnostics.test.ts`, `tests/e2e/terminal-live-pty-liveness.spec.ts`) and roughly 39 more files carry uncommitted modifications. Until each slice is committed and pushed to its owning split branch, the manifest references proof that CI cannot run and that no one can reproduce from a ref.
-- Fresh `origin/main` renamed `terminal-webgl-paste-recovery.{ts,test.ts}` to `terminal-webgl-atlas-recovery.{ts,test.ts}` and added `pane-webgl-context-recovery.test.ts` and `pane-webgl-renderer.test.ts` in #6949. The `xterm-addon.boundary-containment` gate and its documented command reference the old filename and will fail the checker after rebase; the gate should adopt the renamed and new tests during the rebase. #7133 (merged 2026-07-02) further modified `pane-webgl-renderer.{ts,test.ts}` and added `pane-reveal-repaint.{ts,test.ts}` and `terminal-visibility-resume.{ts,test.ts}`; the containment gate should evaluate those reveal-hardening tests for adoption in the same sweep. This is a confirmed instance of the stale-branch risk, and it shows the fresh-main review must include a mechanical testFiles-vs-main sweep, not only behavioral spot checks.
-- This document itself drifted from the manifest it describes (a prior revision said 23 gates, 13 partial/10 none, while the manifest held 24 gates, 15 partial/9 none). Treat the manifest as authoritative and this document's counts as dated snapshots.
-- The Resource Manager status segment no longer polls broad `pty:listSessions()` for its closed-popover badge in this branch. Broad session inventory is now scoped to the open Resource Manager and explicit kill/restart refresh paths; the no-hot-listing plan still needs status/diagnostic budgets and broader Electron counters before promotion.
-- Boot-time local PTY registry hydration now exposes a debug snapshot and deterministic tests for retry state, SSH skip-before-worktree-enumeration, local registration counters, adapter/session listing counts, recoverable adapter-list failures, fatal hydration failures, router adapter fanout, duration, and large daemon lists. This is still only a startup-hydration counter slice; it does not prove focus, typing, tab switch, workspace switch, render, high-session provider fanout, or real Electron startup budgets.
-- Terminal lifecycle anomaly diagnostics now record compact crash breadcrumbs in addition to console warnings. This is useful support evidence, not yet the full pane lifecycle trace buffer requested in the pain-points report.
-
-## Fresh Main Architecture Findings
-
-These findings came from focused reviews of current terminal lifecycle, renderer/input/perf, and provider/platform/startup code against freshly fetched `origin/main`. They are not all regressions introduced by the reliability-gate branch. They are the places the plan must cover before claiming broad terminal reliability.
-
-Current coverage already exists in more places than the first gate stack showed:
-
-- `terminal-dead-session-reconcile.test.ts`, `resume-sleeping-agent-session.test.ts`, and `pty-connection.test.ts` have substantial deterministic lifecycle coverage. A focused run of those files passed 292 tests.
-- Existing E2E/perf tests include terminal typing latency, hidden TUI visual restore, long-table scroll restore, daemon slow-init PTY restore, SSH localhost, and terminal tab-switch SIGWINCH restore.
-- Existing scripts include terminal perf report commands such as `test:e2e:terminal-perf`, `test:e2e:terminal-perf:scale`, `test:e2e:terminal-perf:scale:report`, and `test:e2e:terminal-perf:check-report`.
-
-The problem is that these tests are not yet organized into reliability gates with named invariants, owners, maturity, runtime budgets, flake history, red/green evidence, and promotion rules. Some also need review before promotion because a useful regression test can still be too broad, too slow, or too flaky to be a blocking gate.
-
-Local validation evidence from this review pass:
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/renderer/src/components/terminal-pane/terminal-dead-session-reconcile.test.ts \
-  src/renderer/src/lib/resume-sleeping-agent-session.test.ts \
-  src/renderer/src/components/terminal-pane/pty-connection.test.ts
-```
-
-Result on 2026-07-01: 3 test files passed, 292 tests passed, duration 6.04s. This asserts the current deterministic lifecycle/unit layer is healthy in this worktree; it does not prove the broader live/platform/provider/perf gaps.
-
-The provider-session ownership gate now includes the queued/pending resume bridge from fresh `origin/main`: automatic resumes thread `resumeProviderSession` through `pendingStartupByTabId`, claim `automaticAgentResumeClaimsByTabId`, and treat pending startup, time-bounded runtime claims, and live agent statuses as provider-session ownership. The queued/pending claim scan is indexed once per activation so replay protection does not rescan every pending startup for every sleeping record. It also asserts live hook evidence claims only the matching provider session; a wrong-session hook cannot claim a replayed sleeping record; and stale automatic bridge claims cannot suppress recovery forever.
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/renderer/src/lib/resume-sleeping-agent-session.test.ts
-```
-
-Result on 2026-07-01: 1 test file passed, 34 tests passed, duration 7.86s. This focused command asserts repeat activation or replayed sleeping records do not launch a second resume for the same provider session while the first resume is still pending, queued pending-startup provider-session ids are read once per activation rather than once per replayed record, a live hook for the same provider session owns the replay, and a wrong-session hook does not. It does not yet prove real hook timing through Electron or a full Electron workspace activation loop.
-
-Structural manifest validation also passed locally:
-
-```sh
-pnpm run check:reliability-gates
-```
-
-Result on 2026-07-01 after the first expansion: reliability gate manifest check passed for 22 gates. This validated the manifest schema/metadata shape only; it did not prove that the registered commands covered the full terminal runtime.
-
-After the broader architecture review and fresh-agent review, the manifest was expanded further, including a dedicated WSL restore contract instead of burying WSL under SSH/remote coverage, and later the three convergence/escape-detection gaps registered after the #7133/#7148 saga. As of 2026-07-03, main's manifest holds 27 gates split 9 `partial` (gates whose evidence exists on main itself, including the #7133/#7148/#7173/#7192 regression tests) and 18 `none`; the pending stack raises more gates to `partial` as its slices land. These counts are dated snapshots, and the manifest itself is authoritative. The new entries are intentionally `experimental`; a few now have first executable slices, while others are still commandless gap markers. They are not active protection until each gate gets an implemented command, red/green proof, runtime evidence, and promotion history.
-
-The manifest checker now enforces the review lessons that were easy to miss manually:
-
-- declared `testFiles` must exist;
-- every declared executable `testFiles` entry must be referenced by at least one gate command, so a manifest cannot borrow credibility from a file the registered command does not run;
-- command-backed gates cannot use title selectors such as `-t`, `--grep`, or `--testNamePattern`, because title drift silently changes coverage;
-- every gate must declare `protection: none | partial | active`;
-- commandless gates must declare `protection: "none"`, while command-backed gates must declare at least `protection: "partial"`;
-- `protection: "active"` is reserved for blocking gates with stable flake history and complete red/green evidence;
-- `partial` and `active` gates must include at least one passed structured `evidenceRuns` entry whose command exactly matches the gate command;
-- `none` gates must have no evidence runs, so planning gaps cannot look like tested coverage;
-- `partial` and `active` gates must include `assertionRefs` that point to declared test files and name the invariant assertions inside those files;
-- `none` gates must have no assertion refs, so planning gaps cannot borrow credibility from unrelated tests;
-- every gate must split risk scope from covered scope with `coveredPlatforms`, `coveredProviders`, and `coverageNotes`;
-- `coveredPlatforms` and `coveredProviders` must be inside the declared risk scope, and passed evidence-run platforms must appear in `coveredPlatforms`;
-- `soak` and `blocking` gates must have soaking/stable flake evidence and complete red/green evidence.
-
-How to read the manifest:
-
-- `platforms` and `providers` describe the affected risk scope for an invariant. They do not mean the current command exercises every listed platform/provider.
-- `coveredPlatforms`, `coveredProviders`, and `coverageNotes` describe the scope actually covered by current evidence. Empty `coveredProviders` on a partial gate usually means renderer/state/RPC contract coverage, not a real provider run.
-- `protection: "none"` means a registered gap only; `protection: "partial"` means useful executable coverage that is not blocking protection yet; `protection: "active"` means the gate is blocking and has stable evidence.
-- `evidenceRuns` are factual run records: date, runner, platform, exact command, result, duration, and summary. A local passed run supports `partial` coverage; it does not imply CI stability or flake history.
-- `assertionRefs` explain which assertion groups in the listed test files carry the gate. This is especially important for shared files like `pty-connection.test.ts`, where the whole file passing is not the same as the whole file being relevant.
-- `oracle`, `redGreenEvidence`, and `knownGaps` are the authoritative source for what is actually proved today.
-- Commandless `experimental` gates are registered gaps, not active protection.
-
-New or expanded manifest entries:
-
-- `terminal-platform.live-pty-liveness`
-- `terminal-platform.windows-conpty-liveness`
-- `terminal-performance.no-hot-list-sessions`
-- `terminal-performance.output-backpressure-budget`
-- `terminal-performance.input-throughput`
-- `terminal-performance.daemon-stream-backpressure`
-- `terminal-performance.store-and-git-hot-paths`
-- `terminal-provider.daemon-startup-degraded-contract`
-- `terminal-provider.ssh-remote-reattach-contract`
-- `xterm-addon.boundary-containment`
-- `terminal-output.scrollback-replay-fifo`
-- `terminal-output.scrollback-restore`
-- `terminal-input.ime-and-synthetic-forwarding`
-- `terminal-input.windows-conpty-keyboard-reset`
-- `terminal-render.windows-cjk-repaint`
-- `terminal-shell.windows-resolution-parity`
-- `terminal-capability.startup-color-query`
-- `terminal-runtime.mobile-stream-budget`
-- `terminal-mirror.parser-parity`
-- `terminal-observability.restore-convergence-selfcheck`
-- `terminal-render.pixel-refresh-repair`
-
-The visible geometry gate now has its first deterministic renderer/main contract slice:
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/renderer/src/components/terminal-pane/pty-size-reconcile.test.ts \
-  src/renderer/src/components/terminal-pane/split-right-white-screen.test.ts \
-  src/renderer/src/components/terminal-pane/pty-connection.test.ts \
-  src/main/ipc/pty.test.ts
-```
-
-Result on 2026-07-02: 4 test files passed, 481 tests passed, duration 5.98s. This focused command asserts delayed hidden split-layout settles are forwarded instead of stopping on a fixed frame budget, unmeasurable frames do not count as settled, visible 0x0 split-right panes get a nonzero recovery size while hidden background 0x0 panes are not forced to desktop size, `pty:getSize` reports applied size when a provider can expose it, and visibility resume reasserts only real PTY/xterm drift without falling back to `listSessions`. It does not yet prove shell-visible `stty`, SSH/remote geometry, Windows ConPTY geometry/readback, or full Electron geometry under real split/tab/app-restart workflows.
-
-The live local PTY gate now has its first executable Electron slice:
-
-```sh
-pnpm run ensure:electron-runtime && npx playwright test \
-  tests/e2e/terminal-live-pty-liveness.spec.ts \
-  --config tests/playwright.config.ts --project electron-headless --workers=1
-```
-
-Result on 2026-07-02 after adding two workspace hide/restore cycles, exact active-PTY listing, and actual resize convergence: 1 Playwright test passed, test body 8.6s, full command 58.6s including build/setup. This one local macOS run asserts a real Electron local terminal binds a PTY, lists the active PTY id exactly once, accepts keyboard input through focused xterm, renders process output markers, preserves the same PTY id through repeated worktree switch-away/switch-back cycles, accepts additional keyboard input after each restore, applies an actual `pty:getSize` change after viewport resize, reports the same process-visible size, exits the probe, exits the shell, and removes the PTY id from `pty:listSessions`. It does not yet prove tab switch within the same worktree, scrollback after restore, app restart persistence, daemon, SSH, WSL, remote-runtime, Linux CI stability, or Windows ConPTY behavior.
-
-The IME/native-text gate now has its first deterministic renderer-unit slice:
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/renderer/src/components/terminal-pane/terminal-ime-native-text-forwarder.test.ts \
-  src/renderer/src/components/terminal-pane/terminal-ime-input-source.test.ts \
-  src/renderer/src/components/terminal-pane/terminal-paste-runtime.test.ts
-```
-
-Result on 2026-07-02: 3 test files passed, 63 tests passed, duration 887ms. This registers existing native-text, input-source, and paste/runtime forwarding contracts as a reliability gate slice. It does not prove real OS IME automation, Windows ConPTY post-agent keyboard reset, Arabic/RTL, JIS-yen, or the full CJK/Vietnamese/platform matrix.
-
-The xterm addon containment gate now has its first deterministic renderer-unit slice and product hardening for core addon load failures:
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/renderer/src/lib/pane-manager/pane-lifecycle.test.ts \
-  src/renderer/src/lib/pane-manager/terminal-link-provider-guard.test.ts \
-  src/renderer/src/components/terminal-search-safe-find.test.ts \
-  src/renderer/src/lib/pane-manager/pane-webgl-refresh-lifecycle.test.ts \
-  src/renderer/src/components/terminal-pane/terminal-webgl-paste-recovery.test.ts
-```
-
-Result on 2026-07-02: 5 test files passed, 39 tests passed, duration 370ms. This focused command asserts a core addon `loadAddon` throw is pane-scoped and later addons still load, link provider throws degrade to no-link results, search decoration positive-integer crashes return `false` instead of escaping, and WebGL attach/refresh/recovery failures stay contained. It does not yet prove typed PTY input/output survives a live addon failure in Electron, nor WebGL dispose/reset throws across active, hidden, and resumed panes.
-
-The runtime/mobile stream budget gate now has its first deterministic runtime-RPC slice:
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/main/runtime/rpc/terminal-subscribe-buffer.test.ts \
-  src/main/runtime/rpc/terminal-output-batching.test.ts \
-  src/main/runtime/rpc/terminal-multiplex.test.ts
-```
-
-Result on 2026-07-02: 3 test files passed, 29 tests passed, duration 2.78s. The covered contracts assert mobile initial snapshots downgrade until they fit the 512KB budget, requested binary snapshots downgrade until they fit the 2MB budget, binary live output queued while the initial snapshot is serializing stays within 256KB while preserving the newest tail, large binary output is split into 48KB-or-smaller frames, output bursts are coalesced before emission, aborted subscribes do not register stale listeners, and stale mobile resize re-stream completions are dropped. It does not yet decide JSON subscribe fallback parity/deprecation.
-
-The replay/scrollback gate now has its first executable slice:
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/renderer/src/components/terminal-pane/pty-connection.test.ts
-```
-
-Result on 2026-07-02: 1 test file passed as part of the focused pty-connection validation, with 255 tests in that file. The relevant replay assertions cover four replay invariants: remote replay payloads that overlap before parsing starts intentionally coalesce to the latest payload, a replay whose xterm parsing has already started is not overwritten by a newer replay, multiple replay notifications accepted after parsing starts drain FIFO, and burst tails are bounded while keeping the newest snapshot. It does not yet prove fresh-main `clearBeforeReplay` metadata, metadata-only replay, or hidden-output/live-output interleaving.
-
-The no-hot-`listSessions` gate now has its first executable slice and product hardening. The renderer/preload/main path exposes `pty.hasPty(id)` and uses targeted liveness on visibility resume and first input after resume, instead of calling global `pty:listSessions()` from that hot path. The resize-on-resume slice also asserts it uses targeted `getSize` plus `resize` rather than broad session listing. Light tab switches and visible active-state resume now assert they do not call `pty:listSessions`, `pty.hasPty`, or `pty.getSize`; a representative active-PTY case proves the scheduler hint `setActiveRendererPty` is the only allowed PTY API call there. Resource Manager broad session inventory is now scoped to the open popover instead of polling for its closed badge.
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/renderer/src/components/terminal-pane/terminal-dead-session-reconcile.test.ts \
-  src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.test.ts \
-  src/renderer/src/components/terminal-pane/pty-connection.test.ts \
-  src/renderer/src/components/status-bar/resource-manager-session-polling.test.ts \
-  src/renderer/src/components/terminal-pane/use-terminal-pane-global-effects.test.ts
-```
-
-Result on 2026-07-02: 5 test files passed, 321 tests passed, duration 6.34s. The focused no-hot command asserts visibility resume prefers targeted `hasPty` even when `listSessions` is available, first input after visibility resume calls targeted `hasPty` once, resize re-assertion after visibility resume uses `getSize`/`resize` without `listSessions`, light tab switches and visible active-state resume avoid `listSessions`/`hasPty`/`getSize` fanout while still allowing the active PTY scheduler hint, SSH/remote broad listing is skipped, Resource Manager broad session inventory polling is scoped to the open popover, panes close only on authoritative `false`, and unknown liveness keeps panes alive. It does not yet count raw focus, workspace switch, render, high-session typing, or real provider fanout in Electron.
-
-The store/git hot-path gate now has its first boot-hydration counter slice. This is not broad interactive perf coverage; it is the narrow startup-adjacent part that previously had no measurable budget.
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/main/memory/hydrate-local-pty-registry.test.ts
-```
-
-Result on 2026-07-02: 1 test file passed, 8 tests passed, duration 0.342s. The focused command asserts provider-unavailable hydration does not scan repos/worktrees/providers and remains retryable, SSH repos are skipped before worktree enumeration, local daemon sessions are registered with debug counters for repo/worktree/adapter/session/register/skip/duration fields, recoverable adapter-list failures are counted without failing the whole hydration pass, fatal hydration failures record failed phase and error message, router-backed hydration records multi-adapter fanout counts, pre-existing pid rows are not clobbered, and large daemon session lists hydrate without spreading into argument-limit failures. It does not yet count store recomputes, git status requests, provider listings, focus, typing, tab switch, workspace switch, render, or high-session Electron fanout.
-
-The degraded-daemon provider contract now has its first executable slice and product hardening. Existing-session operations fail closed when ownership is unknown, and restored daemon session ids, including legacy/non-worktree-scoped ids, cannot silently spawn a local fallback PTY under the old id. Fresh degraded-mode PTY creation still intentionally routes through fallback when the caller marks it as new, and process inspection returns benign defaults for unknown ownership instead of leaking fail-closed routing errors into window-close flows.
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/main/daemon/degraded-daemon-pty-provider.test.ts \
-  src/main/daemon/daemon-pty-adapter.test.ts \
-  src/main/daemon/daemon-pty-router.test.ts
-```
-
-Result on 2026-07-02: 3 test files passed, 107 tests passed, duration 2.54s. Focused provider validation asserts discovered daemon sessions route to the daemon, fresh degraded-mode PTYs route to fallback only when marked new, router spawn discovers uncached existing sessions before choosing an adapter, router spawn fails closed instead of falling through to current when legacy ownership cannot be listed or a known session has exited, targeted `hasPty` discovery caches legacy ownership before later operations, real daemon adapter `listProcesses()` discovery seeds targeted `hasPty` liveness, folder and floating terminal workspace ids survive startup reconcile when valid, restored worktree-scoped and legacy/non-scoped ids do not fall back through spawn after ownership is lost or unknown, unknown or exited existing ids fail closed for routing operations, startup reconcile can dry-run orphan detection without killing live daemon sessions, and process inspection returns benign defaults for unknown ownership. It does not yet prove production startup reconcile wiring, prior-worktree aliases, or real daemon process restart behavior.
-
-The SSH/remote provider contract now has its first executable provider/main/renderer slice. Provider observation failures are treated as unknown instead of destructive evidence: a failed SSH `listProcesses()` call does not clear previously learned ownership, and a rejected SSH `hasPty()` probe returns unknown liveness (`null`) rather than dead. The focused renderer/provider tests also assert that saved SSH sessions reattach through relay `pty.attach`, expired relay attach does not silently fresh-spawn inside the provider, deferred passphrase cancellation does not auto-reconnect, saved leaf/tab session ids are used after connection, transient deferred reattach failure preserves the saved session id without clearing pane/tab bindings or fresh-spawning, deferred SSH no-result cleanup clears the pending serializer without consuming the saved restore id, and expired deferred relay state clears stale pane/tab bindings before one fresh replacement spawn.
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/main/providers/ssh-pty-provider.test.ts \
-  src/main/ipc/pty.test.ts \
-  src/renderer/src/components/terminal-pane/pty-connection.test.ts \
-  src/renderer/src/store/slices/store-session-cascades.test.ts
-```
-
-Result on 2026-07-02: 4 test files passed, 546 tests passed, duration 6.48s. Focused validation asserts store wake-hint metadata for disconnected SSH relay ids, provider attach/expired-attach behavior, main-process ownership and targeted-liveness failure semantics including async provider rejection, mocked-renderer deferred SSH attach/transient-failure/expired-relay fallback, and deferred SSH no-result cleanup that clears the pending serializer without consuming the saved restore id. It does not yet prove WSL, remote-runtime mirror polling, a live SSH relay, pending-vs-attached UI status, or real network reconnect timing.
-
-API-surface validation after adding `pty.hasPty(id)`:
-
-```sh
-pnpm run typecheck:node
-pnpm run typecheck:web
-```
-
-Result on 2026-07-02: both typechecks passed.
-
-The output-backpressure budget gate now has a deterministic provider/IPC/renderer slice:
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/main/daemon/daemon-stream-data-batcher.test.ts \
-  src/main/ipc/pty.test.ts \
-  src/renderer/src/components/terminal-pane/pty-connection.test.ts
-```
-
-Result on 2026-07-02: 3 test files passed, 469 tests passed, duration 9.35s. The focused command asserts daemon socket `write(false)`/`drain` ordering, cross-session interactive output priority, pure-backpressure cleanup, bounded daemon queued bytes, main pending renderer caps, active pending-output protection, replay/backlog slices, and ACK-gated in-flight bounds. It does not yet prove live hidden-output floods, renderer parse pressure, event-loop delay, active key latency, or full Electron perf artifacts.
-
-Combined focused terminal/provider validation:
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/main/daemon/degraded-daemon-pty-provider.test.ts \
-  src/main/ipc/pty.test.ts \
-  src/renderer/src/components/terminal-pane/terminal-dead-session-reconcile.test.ts \
-  src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.test.ts \
-  src/renderer/src/components/terminal-pane/pty-connection.test.ts \
-  src/renderer/src/lib/resume-sleeping-agent-session.test.ts
-```
-
-Result on 2026-07-01: 8 test files passed, 625 tests passed, duration 6.55s. This was focused terminal/provider validation, not structural manifest validation.
-
-Reliability manifest checker validation is separate:
-
-```sh
-pnpm run check:reliability-gates
-```
-
-Result on 2026-07-02: reliability gate manifest check passed for 27 gates. This validates the manifest shape and referenced files; it does not prove the registered commands cover the full terminal runtime.
-
-The highest-risk architecture boundaries are:
-
-- Terminal/session ownership is spread across tab PTY ids, leaf PTY ids, last-known relay ids, pending reconnect maps, deferred SSH maps, sleeping records, and provider ownership. The plan needs a derived ownership snapshot oracle for tests/logging so attach, reattach, exit, clear, hibernate, and restore can prove all authorities agree.
-- Queued or pending provider sessions must count as owned. This branch now restores the pending startup and automatic resume claim bridge and covers same-session/wrong-session hook evidence, but real hook timing and repeat activation through Electron still need coverage. This is the class-level invariant motivated by #6800.
-- Stale branch risk is real. The reliability branch previously lacked some protections present on fresh `origin/main`, including queued automatic agent resume claims and exact `hasPty` missing-session reconciliation. This branch has restored those two deterministic slices; the full stack still needs final rebase/retarget verification before landing.
-- Main PTY ownership historically had convenient fallback behavior for unknown ownership. This branch now hardens daemon-router and degraded-provider paths so discovered legacy ownership is cached and unknown existing-session operations fail closed, but SSH/remote/diagnostic listing paths still need live coverage.
-- Startup daemon reconciliation is present as a mechanism but not wired as production startup behavior. Without it, the daemon can still have a session while the adapter no longer knows it owns that session.
-- Degraded daemon routing on fresh `origin/main` can fall back to local for unknown existing-looking sessions. This branch now hardens operation plus restored worktree-scoped and legacy/non-scoped spawn paths to fail closed and registers a focused provider contract, but startup reconcile, prior-worktree aliases, and real daemon restart behavior still need coverage.
-- `pty:listSessions` both observes and mutates provider ownership. This branch now asserts failed SSH observation does not clear previously learned ownership and mocked deferred SSH attach/transient-failure/expired-relay fallback behaves correctly, but WSL, remote-runtime mirror polling, live SSH reconnect timing, and false-live tab behavior remain unproved.
-- Resource Manager broad session inventory is now limited to popover-open and explicit management refreshes. It still needs a status/diagnostic budget proving open-popover polling is bounded with many providers and does not become a hot-path substitute.
-- Boot hydration (`hydrateLocalPtyRegistryAtBoot`) is fire-and-forget, and this branch now records startup phase counters for repo/worktree enumeration, skipped remote repos, adapter/session listing, registrations/skips, duration, and failures. It can still create startup-adjacent git subprocess and daemon-listing churn across many local repos, so do not treat startup reliability as covered until those counters are budgeted in CI/runtime evidence.
-- Deferred SSH restore intentionally marks a saved PTY id before actual attach. This branch now covers the mocked renderer contract for passphrase cancellation, attach after connection, transient attach failure preserving retry state, and expired relay fallback; remaining work is false-live visual state, live SSH relay timing, and duplicate-spawn prevention under real reconnect churn.
-- Geometry truth is incomplete across SSH/remote paths. Requested size, renderer size, provider-applied size, shell-visible size, and the runtime mirror's parse dimensions must be separated instead of treated as interchangeable. #7192 proved the mirror can silently stay at birth dimensions while every other authority resizes, corrupting every later restore snapshot, and that mirror reflow must stay ordered with queued output writes.
-- Production diagnostics are still incomplete. This branch now records compact crash breadcrumbs for explicit terminal lifecycle anomalies, but real user reports still need a bounded pane lifecycle trace for ordinary transitions and a diagnostics-bundle artifact proving those breadcrumbs/traces are included.
-
-The lifecycle breadcrumb gate now has its first executable slice:
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/renderer/src/components/terminal-pane/terminal-lifecycle-diagnostics.test.ts
-```
-
-Result on 2026-07-02: 1 test file passed, 2 tests passed, duration 0.593s. The focused command asserts `warnTerminalLifecycleAnomaly` preserves its console warning, records a compact `terminal_lifecycle_anomaly` renderer crash breadcrumb with terminal identity/provider/PTY/reason fields, and dedupes repeated anomalies by lifecycle identity. It does not yet prove a full pane lifecycle trace buffer, diagnostics-bundle export, or forbidden-transition assertions across live Electron/provider flows.
-
-Specific current-source evidence checked in this pass:
-
-- Fresh `origin/main` has queued provider-session protections in `src/renderer/src/lib/resume-sleeping-agent-session.ts`: `resumeProviderSession`, `claimAutomaticAgentResume`, and `automaticAgentResumeClaimsByTabId`.
-- Fresh `origin/main` has exact liveness reconciliation in `src/renderer/src/components/terminal-pane/terminal-dead-session-reconcile.ts` and the `pty:hasPty` IPC handler in `src/main/ipc/pty.ts`.
-- Fresh `origin/main` still uses a single `pendingReplayData` slot in `src/renderer/src/components/terminal-pane/pty-connection.ts` (re-verified after #7133 merged; #7133 changed the same file's `applyMainBufferSnapshot` alt-screen restore path, not replay draining). This branch changes replay draining to coalesce snapshots before xterm parsing starts, queue accepted snapshots FIFO once parsing is in progress, and coalesce burst tails to the newest snapshot once the in-flight queue is full. The broader scrollback gate still needs metadata-only replay, `clearBeforeReplay`, and hidden/live-output interleaving coverage.
-- Fresh `origin/main` still has `DaemonPtyAdapter.reconcileOnStartup` with the explicit note that it has no production caller yet. This branch adds a dry-run mode so future startup wiring can audit would-kill sessions before destructive cleanup, but production startup-persistence remains a real gap until wired with prior-worktree aliases or tracked as an accepted gap with a gate.
-- Fresh `origin/main` still lets `DegradedDaemonPtyProvider.providerFor()` fall back to local when an existing-looking session id is unmapped and not rediscovered by `hasPty`. This branch changes existing-session operation paths and restored worktree-scoped plus legacy/non-scoped spawn paths to fail closed, adds contract tests, and makes real daemon adapter `listProcesses()` discovery seed targeted `hasPty` liveness. Startup reconcile wiring and live daemon-restart validation are still required before the full provider lifecycle is covered.
-- Fresh `origin/main` let the daemon router spawn an unknown existing `sessionId` on the current daemon when routing cache/discovery missed its real owner. This branch now probes/discovers all adapters first, requires `isNewSession` for intentional replacement after an authoritative exit event, and fails closed if legacy ownership cannot be listed or the known id has exited, so a stale existing id cannot silently mint over another daemon's history on current.
-- Fresh `origin/main` let canonical daemon-worktree restores treat a non-minted stale/local PTY id as restorable metadata. This branch now rejects non-minted restored ids when the workspace owner is canonical (`repo::path`, `folder:<id>`, or `global-floating-terminal`), clears the stale pane/tab binding, and fresh-spawns instead of calling daemon reattach or attaching that stale id. Shared parsing also recognizes folder and floating minted ids so startup reconcile does not falsely reap valid non-repo terminal sessions.
-- Fresh `origin/main` still lets `pty:listSessions` rebuild provider ownership while SSH listing failures become empty lists. This branch adds store/main/provider/renderer contracts proving disconnected SSH relay ids are retained as deferred reconnect metadata and sidebar wake hints rather than attached PTY proof, failed SSH observation does not clear previously learned ownership, `hasPty` failure is unknown, saved SSH sessions attach through relay `pty.attach`, deferred passphrase cancellation does not auto-reconnect, transient deferred reattach failure preserves the saved session id, deferred SSH no-result cleanup clears pending serializer state without consuming retry metadata, and expired deferred relay state clears stale pane/tab bindings before one fresh replacement spawn. Live SSH, WSL, remote-runtime mirror polling, false-live visual state, and real reconnect timing remain unproved.
-- Fresh `origin/main` has strong Windows/unit coverage around ConPTY packaging, shell resolution, size validation, keyboard reset, complex-script classification, and Windows PTY compatibility, but the real Windows Electron/ConPTY path is still not covered as a reliable PR gate.
-- Fresh `origin/main` still exposes global `pty:listSessions`; this branch now also uses targeted `hasPty` for visibility/input liveness, but gates should keep typing, focus, tab switch, visibility resume, resize, and render paths from reintroducing broad daemon/provider listing.
-- Fresh `origin/main` has main-to-renderer ACK/backpressure, renderer output-scheduler caps, terminal perf scripts, and a daily/manual terminal perf workflow. This branch adds daemon stream batcher assertions that socket `write(false)` pauses further stream events until `drain`, flush-immediate output from another session drains before unrelated background backlog, global cleanup clears clients that only have backpressured writes, and queued daemon stream bytes stay bounded by preserving priority output plus the newest tail under sustained pressure; it also caps main pending renderer output per PTY and in total, trims background pending output before active pending output under total pressure, and asserts `seq`/`rawLength` metadata stays correct for the surviving tail. Live hidden-output pressure, active input latency, and full Electron perf artifacts remain unproved.
-- Fresh `origin/main` has binary runtime/mobile terminal stream caps, but the legacy JSON subscription path has weaker buffering/backpressure guarantees. Either gate both paths or explicitly deprecate/accept the JSON gap.
-
-Existing E2E/perf tests that should be reviewed for promotion:
-
-- `tests/e2e/daemon-slow-init-pty-gate.spec.ts`: strong daemon live-session restore signal; already has a tight user-visible invariant.
-- `tests/e2e/daemon-live-session-preservation.spec.ts` and `tests/e2e/daemon-slow-health-check-preservation.spec.ts`: likely useful daemon liveness/preservation gates after oracle and flake review.
-- `tests/e2e/terminal-typing-latency.spec.ts`, `tests/e2e/terminal-codex-local-typing-latency.spec.ts`, and `tests/e2e/terminal-history-size-typing-latency.spec.ts`: useful perf signals, but should be tied to stable budgets and artifacts before blocking promotion.
-- `tests/e2e/terminal-output-scheduler.spec.ts`, `tests/e2e/artificial-opencode-terminal-load.spec.ts`, and hidden-pressure scenarios: useful for output/backpressure, but should become metric-gates rather than visual-only broad E2Es.
-- `tests/e2e/terminal-hidden-tui-visual-restore.spec.ts`, `tests/e2e/terminal-document-visibility-webgl-recovery.spec.ts`, and `tests/e2e/terminal-tab-switch-visual-restore.spec.ts`: useful rendering recovery coverage; must keep deterministic text/buffer oracles and limit screenshots to diagnostics.
-- `tests/e2e/terminal-long-table-scroll-restore.spec.ts` and `tests/e2e/terminal-raw-emoji-table-scroll-restore.spec.ts`: useful scrollback/rendering regression evidence, but they contain timed waits and should be reviewed before blocking promotion.
-- `tests/e2e/ssh-localhost.spec.ts`, `tests/e2e/ssh-docker-relay-perf.spec.ts`, and SSH Codex replay/reconnect specs: useful SSH coverage, but should be separated into deterministic provider contracts plus a small number of environment-dependent live SSH soaks.
-- `tests/e2e/terminal-windows-shell-paste-ownership.spec.ts` and Windows env/icon tests: useful Windows path coverage, but not a substitute for a Windows ConPTY live liveness gate.
-
-Promotion split for existing E2Es:
-
-- Promote after soak: a smaller derivative of `terminal-typing-latency.spec.ts` as the live local PTY input/output gate.
-- Promote after soak: daemon preservation specs, especially slow-init and stale launch identity, as daemon warm-reattach gates.
-- Promote targeted: paste ownership tests where the oracle is visible output plus exactly-one PTY write.
-- Keep in soak/nightly: artificial OpenCode load, terminal scale perf report, hidden real-PTY pressure, and SSH Docker perf.
-- Keep as release evidence: raw emoji/golden rendering, long-table rendering, WebGL recovery, and Codex/OpenCode artifact repros.
-- Rewrite before blocking: column desync specs need resize-applied acknowledgement or an in-PTY `SIGWINCH` marker instead of post-resize sleeps.
-- Rewrite before blocking: SSH Codex artifact repros and headful dead-terminal repros need deterministic fixtures/events instead of long waits and screenshots as primary proof.
-
-The first live PTY gate is deliberately small:
-
-- File: `tests/e2e/terminal-live-pty-liveness.spec.ts`.
-- Command: `pnpm run ensure:electron-runtime && npx playwright test tests/e2e/terminal-live-pty-liveness.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1`.
-- Invariant: a newly opened local terminal has one active PTY id listed exactly once, accepts real keyboard input through focused xterm, delivers process output visibly, keeps the same PTY id through repeated workspace hide/restore cycles, accepts input after restore, applies an actual size change, and exits without leaving a stale binding.
-- Oracle: start a deterministic Node raw-mode probe, wait for `LIVE_PTY_READY_<runId>`, require the active PTY id to appear exactly once in `pty:listSessions`, type through `.xterm-helper-textarea`, require ordered per-key markers in serialized terminal content, switch to another worktree and back twice, require the active pane to keep the original PTY id, type again after each restore, resize and require `pty:getSize` to change plus a matching process-visible size marker, then exit the probe and shell and require the old PTY id to disappear from `pty:listSessions`.
-- Wait rule: no blind sleeps. Wait only on PTY binding, active worktree changes, ready marker, key markers, resize marker, and list-session absence.
-- Budget: target p95 under 75s on Linux including e2e build/setup, hard test timeout 90s. Start blocking on Linux only after soak; run macOS/Windows nightly until each platform has its own history.
-- Failure artifacts: PTY id, provider classification, pid if available, size snapshots, key latencies, final `listSessions`, trace, and screenshot.
-- Red/green proof: intentionally break xterm focus, PTY write forwarding, resize forwarding, and exit cleanup in separate local runs and confirm the gate fails for each class.
-- Local run on 2026-07-02: 1 Playwright test passed in 58.6s total, with an 8.6s test body, on this macOS worktree. This is one green local run for the local live PTY path, not enough flake/runtime history for blocking promotion.
-
-## Gate Coverage Matrix
-
-This is the intended shape after rebasing the stack. The first two columns are what we have now; the last two are what must be added or promoted before the plan earns broader reliability claims.
-
-| Reliability class | Existing evidence | Gap | Next gate or action |
-| --- | --- | --- | --- |
-| Stale liveness snapshots closing newer PTYs | `terminal-session.snapshot-freshness`; deterministic unit coverage | No full Electron tab-survival/input echo proof | Add `terminal-platform.live-pty-liveness` and keep snapshot gate as lower-layer guard |
-| Provider-session replay ownership | `agent-session.provider-ownership`; renderer state tests; queued/pending resume claim proof; bounded queued-claim index proof; same-session and wrong-session hook proof | Needs real Electron repeated activation/hook timing and bounded hook/status scan assertions if those grow | Add Electron activation proof |
-| Exact PTY liveness | Fresh main has targeted `hasPty` path | Current branch must not lose it; provider failures must be unknown, not dead | Rebase/restore exact liveness reconciliation and register it as a gate |
-| Store/session ownership coherence | Many focused tests touch pieces | No single derived oracle across tab, leaf, relay, reconnect, deferred SSH, and sleeping maps | Add ownership snapshot helper for tests/logging |
-| Terminal lifecycle diagnostics | `terminal-observability.lifecycle-breadcrumbs` now records compact anomaly breadcrumbs into crash diagnostics | No full pane lifecycle trace buffer or diagnostics-bundle artifact proof | Add bounded trace buffer and bundle artifact test |
-| Xterm addon/search/WebGL containment | `xterm-addon.boundary-containment`; deterministic core addon load, link-provider, search, and WebGL containment tests; #7054 hidden TUI product hardening | Needs live Electron typed input/output survival after addon failure, and WebGL dispose/reset throw coverage across active/hidden/resumed panes | Add focused component/live input echo follow-up; promote hidden TUI E2E after flake review |
-| Visible terminal geometry | #7006 renderer/provider-style gate; #7192's merged mirror-resize and reflow-ordering red tests on main | SSH/remote and shell-visible truth not fully covered; mirror-geometry slice unregistered until rebase | Add live PTY size readback and provider-applied-size contract; register #7192's mirror-authority tests |
-| Persisted session upgrade | #7007 fixture gate | Needs broader old-version corpus and daemon/SSH cases | Build immutable fixture corpus with startup timing |
-| Live local PTY lifecycle | `terminal-platform.live-pty-liveness` now has a focused Electron Playwright slice covering local spawn, single active PTY listing, xterm input, PTY output, repeated workspace hide/restore, actual resize propagation, and cleanup | Needs flake/runtime history, red-green evidence, tab switch, scrollback after restore, app restart persistence, and non-local provider coverage | Promote first slice after soak; add tab-switch/scrollback/restart follow-ups |
-| Windows ConPTY lifecycle | Recent fixes on main, some unit/platform logic | No required Windows live gate for ConPTY echo/resize/cursor/CJK/IME | Add `terminal-platform.windows-conpty-liveness` |
-| Windows keyboard reset | Unit coverage and recent #6999/#6858 fixes | No live proof that Enter/Backspace/Arrow return to normal after agent/TUI exit | Add `terminal-input.windows-conpty-keyboard-reset` |
-| Windows CJK/repaint | Complex-script and compatibility tests plus recent CJK repaint fixes | No Windows visual/pixel oracle for wide-glyph in-place redraws | Add `terminal-render.windows-cjk-repaint` |
-| Windows shell parity | Shell resolution unit coverage and packaging fixes | No local-vs-daemon parity gate for PowerShell 5/7, cmd, Git Bash, WSL, startup command delivery | Add `terminal-shell.windows-resolution-parity` |
-| Input latency/perf | Existing terminal perf scripts and typing-latency spec | Not registered, not tied to budgets/owners/promotion | Add `terminal-performance.input-throughput` |
-| Hot interaction listing | Recent #7002 fix, targeted `hasPty` path, deterministic visibility/input/resize no-listing assertions, light tab/active-state resume no-provider-fanout assertions, and closed Resource Manager broad-listing avoidance | No count gate proving `pty:listSessions` stays out of raw focus/workspace-switch/render/high-session Electron scenarios; open Resource Manager polling still needs an explicit budget | Extend `terminal-performance.no-hot-list-sessions` |
-| Daemon stream backpressure | Batching/chunking plus new batcher contract proof for `write(false)`/`drain`, cross-session flush-immediate drain priority, pure-backpressure cleanup, and bounded queued tails | No live hidden-output flood proof or active input latency artifact | Extend `terminal-performance.output-backpressure-budget` |
-| Renderer/main ACK and backlog | Main ACK gates, renderer scheduler caps, focused unit coverage, and bounded main pending tails exist | No live metric artifact tying hidden restore, active key latency, queued chars, and dropped backlogs to promotion | Extend `terminal-performance.output-backpressure-budget` |
-| Runtime/mobile terminal stream | `terminal-runtime.mobile-stream-budget`; runtime-RPC tests assert mobile initial snapshot <=512KB, requested binary snapshot <=2MB, pending live output <=256KB while snapshot loads, output frames <=48KB, output coalescing, abort cleanup, and stale resize re-stream suppression | Legacy JSON path parity/deprecation is undecided | Decide/gate/deprecate JSON fallback |
-| Store/git hot paths around terminal changes | Perf/git-crash skills exist; git status limits/coalescing exist; `terminal-performance.store-and-git-hot-paths` now has a boot-hydration counter slice | No Electron count gate for terminal-adjacent store projection, git status, focus, typing, tab/workspace switch, render, or high-session provider fanout | Extend `terminal-performance.store-and-git-hot-paths` with interactive counters |
-| IME and synthetic input | Input forwarding code and scattered coverage | No representative matrix or byte/cell oracle | Add `terminal-input.ime-and-synthetic-forwarding` |
-| Daemon degraded/startup provider contract | Mechanisms exist; daemon slow-init E2E helps | Startup reconcile is unwired; degraded fallback needs fail-closed/probe proof | Add daemon degraded and startup reconcile contract gates |
-| SSH/remote restore and mirror polling | SSH localhost and remote fixes exist; this branch has store/provider/main/renderer proof for deferred SSH wake metadata, SSH attach, listing failure, deferred attach, passphrase cancellation, transient deferred reattach failure, and expired deferred relay fallback | Remote mirror polling, live SSH relay behavior, false-live visual state, pending-vs-attached UI status, and real reconnect timing remain unproved | Add live SSH soak and remote mirror polling gates |
-| WSL restore and launch identity | `terminal-provider.wsl-restore-contract` is now registered as a first-class gap | No WSL provider contract or live Windows WSL smoke yet proves cwd/path identity, startup command delivery, targeted liveness, or restore ownership | Add deterministic WSL provider contract, then one focused Windows WSL smoke |
-| Scrollback/replay restore | Recent #7012 fix, long-table restore coverage, this branch's remote replay ordering proof, #7133's merged alt-only-clear tests, and #7173's merged ordered-seq interleaving and session-revival tests on main | Normal-buffer clear semantics and metadata-only replay still need deterministic lower-layer proof; the merged #7133/#7173 tests are unregistered until rebase | Add `terminal-output.scrollback-restore` as a dirty-state exactness contract, seeded with #7133's and #7173's tests |
-| Renderer/mirror parser parity | #7148 (merged 2026-07-02) fixed the first known width divergence; its red-green width test exists on main | Parser configs can still drift silently on any axis besides widths; no parity gate command is registered | Add `terminal-mirror.parser-parity` built on the shared `terminal-unicode-provider.ts`/`pane-terminal-options.ts` seams |
-| Post-restore convergence detection in production | Anomaly-breadcrumb machinery exists in this branch | Nothing measures renderer-vs-mirror divergence after real restores; #7133-class corruption stays silent until a user notices | Add `terminal-observability.restore-convergence-selfcheck` probe plus telemetry |
-| Stale pixels after reveal (render-level) | #7133's reveal hardening and the live repro harness's refresh-repair oracle | Buffer oracles are blind to buffer-clean, pixels-stale variants by definition | Add `terminal-render.pixel-refresh-repair` to the release-blocking terminal-rendering-golden suite |
-
-## Convergence Oracles And Escape Detection
-
-The #7133 saga is the design input for this section. One user-visible symptom — stale terminal frames on worktree return — decomposed into five distinct mechanisms: the skipped alt-screen clear (#7133 primary fix), the WebGL render-model fossil (#7133 hardening), the daemon mirror unicode width divergence (#7148), the stale hidden-chunk ordering hole with seq-restart data loss (#7173), and desktop resizes never reaching the runtime mirror (#7192). None of the three was predictable in advance, and seventeen faithful fresh-window repro attempts missed the class because the bugs only exist in dirty, long-lived pane states. Mechanism-enumeration testing cannot catch this family. Layer-convergence assertion can.
-
-Orca holds four copies of what a terminal shows: the PTY application's intended screen, the main-process headless mirror buffer, the renderer xterm buffer, and the WebGL-rendered pixels. Every bug in this family is two adjacent copies silently disagreeing. The strategy is two layers that map to the program's two goals — catching issues nobody predicted, and catching regressions to issues already fixed.
-
-Catch novel escapes:
-
-1. `terminal-observability.restore-convergence-selfcheck`: after every hidden-to-visible reveal settles — whether or not a restore was triggered — compare a bounded row-hash sample of the renderer buffer against the current main-mirror state; on mismatch, record a compact content-free `terminal_lifecycle_anomaly` breadcrumb (machinery already in this branch) and count it in telemetry. Per-reveal scope is load-bearing: #7173's frozen-output variant restores faithfully and then silently drops later hidden output, so a restore-scoped probe would never fire. This turns silent corruption into a measurable signal — #7133 and #7173 would have appeared in anomaly counts weeks before the user reports — and after each fix the anomaly rate is the in-production regression detector. Budget: one bounded comparison per reveal, no polling, no content capture beyond hashed row samples.
-2. `terminal-render.pixel-refresh-repair`: the render-level variant is invisible to every buffer oracle by definition (buffer clean, pixels stale). The content-independent oracle: screenshot the revealed pane, force a full model-invalidating repaint, screenshot again; a material diff means something rendered stale, whatever the mechanism. Productize the existing live repro harness with this oracle plus a JS-level render-model-vs-buffer comparison, and land it in the release-blocking `terminal-rendering-golden` suite that `release-cut.yml` already runs against every release tag. Use nightly runs only as the interim phase to stabilize the per-platform diff threshold; golden-set membership is what makes "the next release does not ship this class" directly checkable.
-3. Session-corpus replay: record real agent-session byte streams (a Claude run is exactly the #7133 shape — banner, prompt echo, final frame with blank regions) as fixtures and replay them through the hide/skip/restore machinery under the convergence oracles. Real corpora contain escape-sequence conjunctions nobody writes by hand. This is fixture strategy for the gates above, not a separate gate.
-
-Catch regressions to known fixes:
-
-4. `terminal-mirror.parser-parity`: feed identical byte corpora to the renderer xterm configuration and the main headless mirror and assert cell-identical buffers, with both parsers constructed from one shared configuration module. #7148's divergence (Unicode 11 + ZWJ in the renderer, default width tables in the mirror) existed since the mirror was born and was catchable by a millisecond-scale unit test; this gate also blocks the next one-sided config drift.
-5. The dirty-state restore exactness contract as `terminal-output.scrollback-restore`'s command: apply snapshots onto adversarially dirty panes and assert the resulting buffer exactly equals the snapshot frame. Exactness is load-bearing — presence-of-marker oracles pass on merged frames. Seeded with #7133's merged alt-only-clear tests and #7148's positioned-overwrite width oracle.
-6. Manifest registration of every escape: each fixed escape's red-green test becomes gate evidence, and per the Operating Rules the fix PR must also strengthen the relevant convergence oracle, so each escape permanently shrinks the space for the next one.
-
-Seam placement is part of the design: convergence must be asserted at every adjacent pair of copies, not at one seam. #7192 proved this the hard way — a renderer-vs-mirror check is blind to corruption inside the mirror itself, because the restore is perfectly faithful to a corrupted source. That is why the geometry gate owns the runtime mirror's dimensions and reflow ordering as a first-class size authority, upstream of the seam this section's self-check watches.
-
-The honest limit stands: this shrinks the escape space rather than zeroing it. The first four mechanisms in the saga are caught by items 1, 2, 4, and 5 without predicting any of them; the fifth (#7192) escaped every renderer-side oracle as originally specced and was closed by adding the mirror to the geometry authority list — evidence that the escape-driven loop (item 6) is not optional. The three new gates and the strengthened `terminal-output.scrollback-restore` entry are registered in the manifest as `protection: "none"` gaps, so the checker, factory reviews, and this plan cannot claim them as coverage before their commands exist.
-
-## Immediate Fix Candidates
-
-These are the concrete pieces to prioritize before declaring the plan implemented:
-
-Three mechanical prerequisites gate everything below:
-
-- Materialize the split: commit each working-tree slice to its owning branch per the file assignment in the PR Split Plan, reset the diverged child branches (#7004, #7005, #7006, #7008) from the worktree versions of their files, and push. Until then, every evidence run in this plan and in the manifest refers to unreproducible state.
-- During the rebase, run the testFiles-vs-fresh-main audit and fix the confirmed #6949 WebGL rename by adopting `terminal-webgl-atlas-recovery.test.ts` and evaluating `pane-webgl-context-recovery.test.ts` and `pane-webgl-renderer.test.ts` for the containment gate.
-- Open the aggregated non-blocking `reliability-gates` CI job so promotion evidence starts accruing with machine provenance.
-
-1. Rebase or retarget the existing reliability PR stack onto fresh `origin/main`, then verify the stack still contains queued automatic resume claims and exact `hasPty` missing-session reconciliation. This branch has restored both deterministic slices, but final stack verification is still required.
-2. Extend the provider-session ownership test from the current queued/pending, bounded-index, same-session hook, and wrong-session hook proof to a real Electron repeated-activation test, plus bounded-work assertions for any new hook/status scans.
-3. Add or restore exact liveness tests: `hasPty(id) === false` tears down only the matching local PTY, while `true`, `null`, rejection, SSH/remote unknown states, and stale pre-bind responses do not close panes.
-4. Add a small derived terminal ownership snapshot helper for tests and diagnostics. It should report whether each live PTY is represented once by the intended tab/leaf and absent from stale maps after attach, reattach, exit, clear, hibernate, and restore.
-5. Keep the replay FIFO/burst fix and tests in the stack, rebased over #7133's alt-clear restore preamble in the same file. This branch now asserts that multiple replay notifications arriving during an async drain cannot overwrite one another, cannot reorder accepted replay snapshots, and cannot grow an unbounded replay queue under bursty snapshots; remaining replay work is normal-buffer clear semantics (alt-screen clear landed in #7133), metadata-only replay, and hidden/live-output interleaving.
-6. Wire `DaemonPtyAdapter.reconcileOnStartup`, or explicitly create a provider-contract gate and accepted gap if wiring is not safe yet.
-7. Keep the degraded daemon fail-closed contract in place and extend it to startup/restart coverage. This branch now prevents unknown existing ids from silently routing operation calls or restored worktree-scoped and legacy/non-scoped spawn calls to fallback; the remaining work is production startup reconcile, prior-worktree aliases, and live daemon-restart validation.
-8. Keep the daemon-router targeted-discovery fix in place. This branch now caches ownership discovered by `hasPty()` before later write/resize-style operations and fails closed for operations on unknown existing session ids, preventing legacy-daemon sessions from silently routing to the current daemon.
-9. Extend provider listing failure contract tests. This branch now asserts disconnected SSH relay ids are retained as deferred reconnect metadata and sidebar wake hints rather than attached PTY proof, a rejected SSH listing does not clear previously learned ownership, thrown SSH `hasPty` is unknown, provider expired attach does not silently fresh-spawn, deferred SSH passphrase cancellation does not reconnect, deferred attach uses saved session ids, transient deferred reattach failure preserves retry metadata instead of fresh-spawning, and expired deferred relay fallback clears stale pane/tab bindings before one fresh spawn. Remaining work is empty-but-ambiguous provider snapshots, WSL, remote-runtime mirror polling, live SSH relay timing, false-live visual state, pending-vs-attached UI status, and pane-close behavior.
-10. Extend the new lifecycle anomaly breadcrumbs into a bounded structured lifecycle trace outside E2E-only mode for reattach, expired sessions, provider-list failure, unknown ownership, fallback routing, replay, and terminal input recovery.
-11. Extend the hot-interaction listing count gate. The targeted `hasPty`, resize-on-resume, light tab/active-state resume, and closed Resource Manager polling slices are implemented; next it should prove `pty:listSessions()` calls are zero during raw focus, workspace switch, render, high-session Electron scenarios, and separately budget open status/diagnostic polling.
-12. Add a cheaper Resource Manager session-status path or an explicit budget for open-popover `pty:listSessions()` polling. The closed-popover poll is removed, but the visible Resource Manager inventory still fans out to providers and mutates ownership, so it should have a measured ceiling.
-13. Budget the new startup hydration counters for `hydrateLocalPtyRegistryAtBoot` in CI/runtime evidence, including repo/worktree enumeration count, git subprocess count proxy, daemon session-list duration, and confirmation that no startup-critical path awaits the scan.
-14. Extend the output backpressure proof. The daemon stream batcher now pauses after `write(false)`, prioritizes flush-immediate output from another session ahead of unrelated background backlog on `drain`, clears pure-backpressure queues on global cleanup, bounds queued stream bytes, and resumes on `drain`; main pending renderer output is capped per PTY and in total. Next, hidden-output floods and active key latency need metric artifacts under the perf budget.
-15. Add Windows platform gates rather than relying on Linux/macOS live PTY evidence: ConPTY liveness, keyboard reset, CJK repaint, shell resolution parity, and IME/native-text forwarding.
-16. Decide whether the legacy JSON runtime terminal subscribe path is supported. If supported, gate its snapshot/live-output byte caps; if not, mark it as an accepted gap with a deprecation path.
-17. Implement the dirty-state restore exactness contract as `terminal-output.scrollback-restore`'s first command, seeded with #7133's merged alt-only-clear tests and #7173's ordered-seq interleaving and session-revival tests: apply snapshots onto already-alt-screen panes with stale content in cells the new frame leaves blank, include revived sessions with restarted PTY seq counters in the dirty-state matrix, and assert exact buffer equality.
-18. Implement the parser-parity seed during the rebase, now that #7148 has merged: register `headless-emulator-unicode-width.test.ts` plus a shared parser-construction assertion over `terminal-unicode-provider.ts` and `pane-terminal-options.ts` as `terminal-mirror.parser-parity`'s first command. The test file exists on fresh main but not at this branch's stale merge-base, so the command cannot be registered before the rebase.
-19. Implement the per-reveal convergence self-check behind the existing anomaly-breadcrumb machinery — comparing the renderer buffer against current mirror state on every reveal, not only after restores, with a strict per-reveal budget and no content capture — and productize the stale-render repro harness into `terminal-render.pixel-refresh-repair` targeting the release-blocking terminal-rendering-golden suite.
-20. Register #7192's merged mirror-geometry red tests as the mirror-authority slice of `terminal-geometry.visible-convergence` during the rebase, covering both accepted-resize fan-out to the runtime mirror and reflow-vs-queued-output ordering.
-
-Next gates to add before claiming broad terminal reliability coverage:
-
-1. `terminal-platform.live-pty-liveness`: first focused Electron/live-PTY slice is implemented for local Linux/macOS-style terminals. One local macOS run asserts bind, single active PTY listing, focus, keyboard input, PTY echo, repeated workspace hide/restore of the same PTY, post-restore input, actual size propagation, and exit cleanup. Follow up with scrollback-after-restore, tab switch, app restart, and non-local providers before broad live-terminal claims; keep it `experimental` until it has flake/runtime and red-green evidence.
-2. `terminal-platform.windows-conpty-liveness`: Windows-specific gate for ConPTY spawn/activation, PowerShell resolution, cursor/rewrite repaint, CJK/IME bytes, and no stuck `stale_bootstrap`. Use lower-level provider contracts where possible and one focused Windows Electron smoke for the real ConPTY path.
-3. `terminal-input.windows-conpty-keyboard-reset`: Windows local ConPTY gate proving Enter, Backspace, Arrow, paste, and ordinary shell submission behave normally after an agent or TUI exits. Oracle should include PTY input logs proving stale Kitty/CSI-u mode is not still applied to standard keys.
-4. `terminal-render.windows-cjk-repaint`: Windows local ConPTY wide-glyph redraw gate. Oracle should combine xterm buffer/text evidence with screenshot/canvas/pixel evidence and a bounded refresh count.
-5. `terminal-shell.windows-resolution-parity`: local and daemon providers must resolve equivalent shell path, args, cwd, env, startup command delivery, and fallback behavior for PowerShell 5/7, cmd, Git Bash, WSL, and missing `pwsh`.
-6. `terminal-performance.input-throughput`: non-blocking perf gate for typing latency, hidden-output pressure, renderer CPU, terminal output throughput, resize churn, and store subscriber work. This should be metric-based, not screenshot-based.
-7. `terminal-performance.no-hot-list-sessions`: deterministic count gate proving `pty:listSessions()` is not called from typing, focus, tab/workspace switch, visibility resume, resize, render, or per-pane liveness paths.
-8. `terminal-performance.daemon-stream-backpressure`: provider/daemon contract gate proving daemon socket writes respect backpressure under output floods and do not starve active input.
-9. `terminal-performance.output-backpressure-budget`: main-to-renderer ACK and renderer scheduler budget gate. Suggested ceilings: peak renderer in-flight bytes <=8MB total, <=512KB per PTY plus active reserve, renderer queued chars <=2MB, dropped renderer backlogs 0 in normal perf scenarios, and hidden restore <=1000ms.
-10. `terminal-runtime.mobile-stream-budget`: runtime/mobile stream gate proving binary terminal snapshots stay <=512KB mobile or <=2MB requested, live pending output stays <=256KB while snapshot loads, chunks stay <=48KB, and batches stay <=64KB.
-11. `terminal-input.ime-and-synthetic-forwarding`: representative IME/input matrix with deterministic byte/cell oracles at the lowest reliable layer, plus platform-specific manual/soak coverage where real IMEs are required.
-12. `terminal-provider.remote-daemon-contract`: provider contract for daemon degraded spawn, SSH/remote unknown liveness, mirror polling, reconnect, and path/cwd authority.
-13. `terminal-provider.wsl-restore-contract`: Windows WSL provider contract proving host/guest cwd identity, shell launch args, startup command delivery, targeted liveness semantics, and restore ownership, followed by one focused live WSL smoke.
-14. `terminal-output.scrollback-restore`: deterministic scrollback/snapshot/replay gate for hidden output, restore, clearing, and no cross-tab or stale-output overlap. Seed it with #7133's merged assertions — the alt-only clear preamble written before alt-screen snapshot data (and no `3J`) in `pty-connection.test.ts`, plus the reveal-repaint ordering tests — then extend to normal-buffer clear semantics, metadata-only replay, and hidden/live-output interleaving. #7133's buffer-merge escape (pre-hide frame bleeding through blank cells) is the motivating regression for this gate.
-15. `terminal-capability.startup-color-query`: startup OSC 10/11 replies are answered out of band at startup only, do not leak into shell/renderer streams, and ordinary OSC color queries remain renderer-handled.
-16. `terminal-mirror.parser-parity`: renderer xterm and the main headless mirror parse identical byte corpora into cell-identical buffers, with both parsers constructed from one shared configuration module. Seed with #7148's merged width test (`headless-emulator-unicode-width.test.ts`) plus a shared-construction assertion over `terminal-unicode-provider.ts` and `pane-terminal-options.ts`; extend with recorded agent-session corpora.
-17. `terminal-observability.restore-convergence-selfcheck`: production per-reveal probe comparing a bounded row-hash sample of the renderer buffer against current main-mirror state — on every reveal, not only after restores, because #7173's frozen-output variant never triggers another restore — recording deduped content-free anomaly breadcrumbs and telemetry counts. This is the in-production escape detector for the whole restore family; corruption upstream of the mirror itself is owned by the geometry gate.
-18. `terminal-render.pixel-refresh-repair`: content-independent refresh-repair oracle (screenshot, force a model-invalidating repaint, screenshot, bounded diff) plus a render-model-vs-buffer comparison, productized from the existing stale-render repro harness into the release-blocking `terminal-rendering-golden` suite; nightly runs only until the diff threshold is stable.
-
-Specific near-term hardening before promotion:
-
-- #7008 now includes a bounded queued-claim assertion plus same-session and wrong-session hook cases for provider-session ownership checks. It should still be followed by a real Electron repeated-activation proof and any additional bounded-work assertions if hook/status ownership scans grow.
-- Each gate PR should keep its residual gaps in the PR description and manifest until a real follow-up gate removes them. Do not let a green lower-layer gate imply live Electron, SSH, WSL, Windows ConPTY, or IME coverage.
-
-Promotion rule for these additions is unchanged: do not make any of them blocking until they have red/green proof, stable runtime history, zero unexplained flakes in the promotion window, a clear owner, and a demotion rule. A non-blocking gate is useful evidence and documentation; it becomes protection only after promotion criteria are met.
-
-## Goal
-
-Prevent the recent terminal, tab, session, startup, provider, and performance regressions from escaping again by turning each high-risk reliability class into a small executable gate with explicit maturity, owner, runtime budget, flake history, and promotion evidence.
-
-This plan is broad in scope but staged in rollout. The first milestone exercises the operating model end to end; later milestones add live Electron, Windows ConPTY, SSH/remote, daemon, IME, scrollback, and performance gates without turning the suite into noisy sprawl.
-
-## Operating Rules
-
-- Add gates only when they protect a named invariant tied to a real issue, PR, or accepted gap.
-- Prefer deterministic unit or provider-contract tests over Electron UI tests when the lower layer proves the user-visible invariant.
-- Never promote a gate to blocking until it has red/green evidence, stable runtime evidence, and a named demotion rule.
-- Keep stress/torture runs non-blocking unless they have deterministic oracles and flake history.
-- Include a performance or crash-safety budget whenever the protected change touches terminal throughput, hidden panes, persistence, startup, polling, subprocesses, git/worktree scans, SSH, WSL, or Windows paths.
-- Restore, replay, reattach, and snapshot gates must start from adversarially dirty initial states — already-alt-screen panes, stale content occupying cells the new frame leaves blank, scrollback present, wide/emoji glyphs — never only fresh terminals. Fresh-state-only testing is why the #7133 class survived seventeen faithful repro attempts.
-- Restore and replay oracles must assert frame exactness or stale-content absence. Marker-presence oracles pass on merged frames and are not acceptable correctness evidence for restore paths.
-- Every escaped terminal bug's fix PR must ship both the narrow mechanism regression test and a strengthening of the relevant convergence oracle (parser parity, restore exactness, convergence self-check, or pixel refresh-repair), so each escape permanently shrinks the space for the next one.
-
-## Milestone 1
-
-Milestone 1 creates the reliability-gate loop with the two highest-leverage escaped classes:
-
-1. `terminal-session.snapshot-freshness`
-   A stale local/daemon liveness snapshot cannot close a newer PTY binding.
-
-2. `agent-session.provider-ownership`
-   Workspace activation, restore, sleep, hibernate, dedupe, clearing, or reconnect code cannot replay or resume a provider session already owned, queued, pending, or live in the workspace.
-
-Both gates already have targeted tests in the repo. Milestone 1 makes them reviewable factory artifacts by registering their invariant, command, owner, maturity, known gaps, and promotion criteria in `config/reliability-gates.jsonc`.
-
-## First Commands
-
-Run the structural manifest check:
-
-```sh
-pnpm run check:reliability-gates
-```
-
-Run the first two gate tests:
-
-```sh
-pnpm exec vitest run --config config/vitest.config.ts \
-  src/renderer/src/components/terminal-pane/terminal-dead-session-reconcile.test.ts \
-  src/renderer/src/lib/resume-sleeping-agent-session.test.ts
-```
-
-Run the existing terminal perf report gate before promoting terminal lifecycle gates to blocking:
-
-```sh
-pnpm run test:e2e:terminal-perf:scale:report
-```
-
-## Promotion Criteria
-
-A gate can move from `experimental` to `soak` when:
-
-- it is registered in the manifest;
-- it has a deterministic oracle with no blind sleeps;
-- it has a cheap command that can run repeatedly;
-- it names the failure artifact reviewers should inspect;
-- it has a clear owner and demotion rule.
-
-A gate can move from `soak` to `blocking` when:
-
-- it has red/green evidence against the old behavior, a regression fixture, or an intentionally broken variant;
-- it has at least 100 consecutive passing soak runs or 14 days of required-platform CI history, whichever is more appropriate for the gate;
-- that history comes from the aggregated `reliability-gates` CI job with machine-recorded results (see Evidence Provenance And CI Wiring), not from hand-entered local runs;
-- p95 runtime is within the manifest budget;
-- there are zero unexplained flakes in the promotion window;
-- any required perf/git-crash budget has measured evidence.
-
-For visual and live release-assurance gates, `blocking` means membership in the release-blocking `terminal-rendering-golden` suite that `release-cut.yml` runs against every release tag — the existing golden rail, not a new checkpoint mechanism, and never PR-blocking. Deterministic unit and contract gates stay on the PR path, where catching a regression is strictly cheaper than catching it at release time.
-
-The manifest also allows `accepted-gap` for explicitly deferred reliability work with a named owner and `deprecated` for gates superseded by a stronger invariant or removed product surface. Those levels should stay visible in the manifest so factory review can distinguish intentional gaps from missing coverage.
-
-## Factory Contract
-
-`brennan-yolo-lite`, `review-code`, `perf`, and `git-crash-perf` should treat the manifest as the source of truth.
-
-For any PR touching a P0-capable surface, the agent or reviewer should:
-
-- identify the touched reliability class;
-- name the matching manifest gate or accepted gap;
-- run the gate command or explain why it does not apply;
-- require a new manifest entry when the PR introduces a new reliability class;
-- invoke `perf` or `git-crash-perf` when the touched surface matches their risk scope.
-
-## Evidence Provenance And CI Wiring
-
-Hand-entered evidence is the weakest link in this plan: the checker validates metadata shape, but nothing yet proves a registered command actually ran against the code it claims to cover. Reliability gates become protection only when they run automatically, against pushed commits, with recorded history. Requirements:
-
-1. Every `evidenceRuns` entry must record the pushed commit SHA it ran against. A run against uncommitted working-tree state is a development note, not promotion evidence; it must be re-run and re-recorded once the owning PR's branch is pushed. All evidence runs currently in the manifest predate the split and must be refreshed this way.
-2. Add one aggregated non-blocking `reliability-gates` CI job that runs `check:reliability-gates` plus every command-backed gate command, and uploads a machine-readable per-gate result artifact (gate id, command, result, duration, commit SHA, runner platform). Run it nightly and on PRs that touch terminal/session/provider/startup paths. Because every gate command except the live Playwright slice is a focused vitest run measured in seconds (a combined run of all 28 unit-layer gate test files completed in 10.2s with 928 tests on 2026-07-02), the job's cost is dominated by setup, not by gate count.
-3. Promotion to `active`/blocking requires history from that CI job — the 100-consecutive-run or 14-day criteria in Promotion Criteria — not local runs. Flakes recorded by the job must be triaged before the affected gate can be promoted, and an unexplained flake on an `active` gate is the demotion signal.
-4. Checker follow-up: once the CI artifact exists, extend the checker so `active` gates require at least one CI-provenance evidence run, and so evidence-run commit SHAs are verified to be ancestors of the branch under check.
-5. Rebase audit: before any merge claim, mechanically verify every declared `testFiles` entry exists on fresh `origin/main` (or on the rebased tree) rather than trusting memory. The #6949 WebGL rename is the standing example of why.
-
-## Milestone 2
-
-After Milestone 1 works, add the next three gates as experimental entries with deterministic harnesses:
-
-- `terminal-geometry.visible-convergence`
-- `xterm-addon.boundary-containment`
-- `startup-upgrade.persisted-session-corpus`
-
-These should not become blocking until the team has red/green, runtime, and flake evidence. The goal is fewer useful gates, not a larger noisy suite.
-
-## Milestone 3
-
-Milestone 3 is where the plan stops being only a lower-layer regression net and starts exercising the real terminal runtime:
-
-- Register existing terminal perf and E2E tests as experimental manifest gates only after reviewing their oracles, waits, artifacts, and flake history.
-- Add the live local PTY gate with a tight oracle: spawn a shell, print a unique token, switch hidden-visible, assert the same PTY/session id, verify visible buffer content, type again, and prove no duplicate tab or blank pane appeared.
-- Add Windows ConPTY coverage on Windows CI for echo, resize/readback, cursor visibility, CJK/emoji output, keyboard reset, shell resolution parity, and activation after restore.
-- Add daemon degraded/startup reconcile contracts before relying on daemon fallback behavior.
-- Add live SSH, WSL, remote-runtime mirror polling, and provider-listing edge contracts before treating remote/SSH restore as broadly covered; the current mocked SSH deferred-reattach and expired-relay tests are useful lower-layer proof, not live remote coverage.
-- Add perf gates with explicit budgets for input latency, event-loop delay, hidden-output pressure, daemon stream backpressure, no hot `listSessions`, pending bytes, renderer ACK behavior, store hot paths, and runtime/mobile stream byte caps.
-- Add IME/synthetic-input coverage at the lowest deterministic layer, with platform-specific manual or soak coverage only where real IMEs are required.
-
-Milestone 3 gates should begin as `experimental`. They become `soak` only when the command is stable enough to run repeatedly and the failure artifact tells an engineer exactly what broke. They become `blocking` only after the promotion criteria above are satisfied.
diff --git a/docs/reference/reliability-pain-points-2026-06-30.md b/docs/reference/reliability-pain-points-2026-06-30.md
deleted file mode 100644
index 8049e3e7191..00000000000
--- a/docs/reference/reliability-pain-points-2026-06-30.md
+++ /dev/null
@@ -1,712 +0,0 @@
-# Reliability Pain Points and Improvement Plan
-
-Date: 2026-06-30
-
-## Scope
-
-This note summarizes the recent reliability review across:
-
-- Recently merged reliability PRs, especially terminal/tab/startup/session work from 2026-06-26 through 2026-06-30.
-- GitHub issues labeled `P0` and `P1`.
-- Local git history for authorship when issue text or PR bodies named a regressing change.
-
-The goal is to identify where Orca is hurting, what engineering improvements would reduce repeat incidents, and what can fairly be said about attribution.
-
-## Issue Snapshot
-
-At the time of review:
-
-- Open `P0`: 9
-- Total `P0`: 14
-- Open `P1`: 191
-- Open `P1` split: 90 bugs, 86 enhancements, 15 other
-
-Last seven days reviewed: 2026-06-23 through 2026-06-30.
-
-- Merged PRs in the window: 386
-- `P0` issues created in the window: 8
-- `P1` issues created in the window: 83
-
-The last-seven-day issue set is the strongest signal for the current pain. It includes the new-tab autoclose `P0`, Windows terminal activation hangs, renderer CPU/input lag, Windows startup visibility failure, Codex config corruption on Windows, a large terminal/IME/rendering cluster, WSL/remote/provider drift, and agent/sidebar/session identity drift.
-
-Open `P0` issues:
-
-- [#6877](https://github.com/stablyai/orca/issues/6877): macOS 1.4.106 nested `simcam` dylib is unnotarized and rejected by Gatekeeper.
-- [#6874](https://github.com/stablyai/orca/issues/6874): Windows `AppHangB1` when opening or activating a terminal session; runtime stuck in `stale_bootstrap`.
-- [#6873](https://github.com/stablyai/orca/issues/6873): likely duplicate or near-duplicate of #6874, though the issue metadata says macOS while the title/body describe Windows.
-- [#6795](https://github.com/stablyai/orca/issues/6795): app became very slow after an update; typing can lag by 2-5 seconds.
-- [#6773](https://github.com/stablyai/orca/issues/6773): cannot create a new terminal tab or agent; the tab opens and closes immediately.
-- [#6655](https://github.com/stablyai/orca/issues/6655): high `Orca Helper (Renderer)` CPU on Mac Mini M4 causing severe UI/input lag.
-- [#5787](https://github.com/stablyai/orca/issues/5787): whole Windows window freezes; input dies in every pane; sessions close on click.
-- [#5356](https://github.com/stablyai/orca/issues/5356): session loss on first launch after upgrading from 1.4.65 to 1.4.68.
-- [#5314](https://github.com/stablyai/orca/issues/5314): Windows close button and Alt+F4 do nothing.
-
-Closed `P0` issues worth keeping in the reliability history:
-
-- [#6233](https://github.com/stablyai/orca/issues/6233): Windows window fails to appear while the process runs in the background.
-- [#6163](https://github.com/stablyai/orca/issues/6163): Orca-managed Codex `config.toml` duplicate key.
-- [#5377](https://github.com/stablyai/orca/issues/5377): native watcher main-process crash on macOS.
-- [#5144](https://github.com/stablyai/orca/issues/5144): Windows close-confirmation deadlock.
-- [#5109](https://github.com/stablyai/orca/issues/5109): sidebar agent status mismatch.
-
-## P1 Reliability Clusters
-
-The `P1` set is too large to treat as a flat list. The high-signal reliability clusters are:
-
-### Terminal Rendering and Input
-
-- [#6901](https://github.com/stablyai/orca/issues/6901): garbled text.
-- [#6764](https://github.com/stablyai/orca/issues/6764): Windows terminal issues.
-- [#6632](https://github.com/stablyai/orca/issues/6632): display artifacts in Claude Code full-screen TUI.
-- [#6144](https://github.com/stablyai/orca/issues/6144): laggy Claude Code terminal scroll.
-- [#5969](https://github.com/stablyai/orca/issues/5969): remote-over-SSH Codex display artifacts.
-- [#5345](https://github.com/stablyai/orca/issues/5345): Windows/WSL scrolling causes duplicated or garbled text and content overlap.
-
-### IME and International Text
-
-- [#6905](https://github.com/stablyai/orca/issues/6905): Vietnamese IME input broken in terminal.
-- [#6765](https://github.com/stablyai/orca/issues/6765): Linux Sogou Pinyin/fcitx only commits the first CJK character.
-- [#6698](https://github.com/stablyai/orca/issues/6698): Vietnamese Telex input loses characters.
-- [#5921](https://github.com/stablyai/orca/issues/5921): CJK characters duplicated in Orca terminal on Windows.
-- [#5262](https://github.com/stablyai/orca/issues/5262): Arabic text rendering appears reversed or disconnected in terminal input.
-
-### Paste and Clipboard
-
-- [#5365](https://github.com/stablyai/orca/issues/5365): terminal freezes for seconds when pasting long text on Windows.
-- [#5358](https://github.com/stablyai/orca/issues/5358): Windows paste preview collapses long text and cannot expand it.
-- [#5919](https://github.com/stablyai/orca/issues/5919): generic paste reliability issue.
-- [#5960](https://github.com/stablyai/orca/issues/5960): bad screen result when pasting links.
-- [#6364](https://github.com/stablyai/orca/issues/6364): pasting images into an agent CLI does not work using Remote Host.
-
-### SSH, Remote Runtime, WSL, and Provider Boundaries
-
-- [#6106](https://github.com/stablyai/orca/issues/6106): SSH terminal loses pre-TUI shell output after Codex tab restore.
-- [#6846](https://github.com/stablyai/orca/issues/6846): remote PTY sessions do not stay alive on disconnect.
-- [#6908](https://github.com/stablyai/orca/issues/6908): WSL project added through UI does not discover branches/base refs, while CLI repo add works.
-- [#6907](https://github.com/stablyai/orca/issues/6907): Codex launched in a WSL worktree does not appear in agent status/sidebar.
-- [#6916](https://github.com/stablyai/orca/issues/6916): OMP launched in a WSL worktree has no live agent status.
-- [#6032](https://github.com/stablyai/orca/issues/6032): Remote Orca Servers can lose host-scoped repo and project state.
-- [#6688](https://github.com/stablyai/orca/issues/6688): viewing a diff on remote host errors.
-- [#6753](https://github.com/stablyai/orca/issues/6753): remote-host GitHub merge errors.
-
-### Agent, Tab, Session, and Sidebar State Drift
-
-- [#6910](https://github.com/stablyai/orca/issues/6910): active agent tabs duplicate UI sessions when switching repositories.
-- [#6803](https://github.com/stablyai/orca/issues/6803): multiple working agents thrash their order in the sidebar.
-- [#6072](https://github.com/stablyai/orca/issues/6072): mobile keeps showing old agent rows after terminals are closed.
-- [#5913](https://github.com/stablyai/orca/issues/5913): Pi compact agent row remains after closing its terminal tab.
-- [#5718](https://github.com/stablyai/orca/issues/5718): OMP sessions not showing up in Agent Session History or filter options.
-- [#5404](https://github.com/stablyai/orca/issues/5404): false "agent running" notifications persist after starting Claude Agents on VSSH/WSL.
-
-### Mobile Terminal and Tabs
-
-- [#5421](https://github.com/stablyai/orca/issues/5421): iOS workspace tabs do not open.
-- [#6756](https://github.com/stablyai/orca/issues/6756): iOS terminal renders in cursive/italic font and continuously flickers.
-- [#5628](https://github.com/stablyai/orca/issues/5628): mobile resizing feature request, closely related to terminal fit/reflow reliability.
-
-### Browser, Profile, and Embedded Runtime
-
-- [#6923](https://github.com/stablyai/orca/issues/6923): browser profiles do not isolate storage.
-- [#6760](https://github.com/stablyai/orca/issues/6760): floating browser cannot load any page.
-- [#6268](https://github.com/stablyai/orca/issues/6268): embedded-browser cookie/session limitation prevents Auth0 login.
-- [#6875](https://github.com/stablyai/orca/issues/6875): cannot copy Google Chrome cookies database.
-- [#6652](https://github.com/stablyai/orca/issues/6652): browser zoom broken.
-
-### Startup, Install, and Platform Hangs
-
-- [#5657](https://github.com/stablyai/orca/issues/5657): macOS startup PATH probe can hang under Endpoint Security agents.
-- [#5107](https://github.com/stablyai/orca/issues/5107): Orca opens very slowly on Windows 11 and leaves a residual process.
-- [#5989](https://github.com/stablyai/orca/issues/5989): Windows Defender blocks application during installation.
-
-## Recent Reliability PR Context
-
-The late-June reliability work clustered around the same few subsystems:
-
-- New terminal tabs opening and immediately closing: [#6796](https://github.com/stablyai/orca/pull/6796), [#6801](https://github.com/stablyai/orca/pull/6801).
-- Stale/frozen/blank terminals: [#6514](https://github.com/stablyai/orca/pull/6514), [#6800](https://github.com/stablyai/orca/pull/6800), [#6833](https://github.com/stablyai/orca/pull/6833), [#6830](https://github.com/stablyai/orca/pull/6830), [#6866](https://github.com/stablyai/orca/pull/6866).
-- PTY size and layout desync: [#6644](https://github.com/stablyai/orca/pull/6644), [#6649](https://github.com/stablyai/orca/pull/6649), [#6684](https://github.com/stablyai/orca/pull/6684), [#6725](https://github.com/stablyai/orca/pull/6725), [#6785](https://github.com/stablyai/orca/pull/6785), [#6853](https://github.com/stablyai/orca/pull/6853).
-- Renderer/xterm crash hardening: [#6852](https://github.com/stablyai/orca/pull/6852), [#6872](https://github.com/stablyai/orca/pull/6872), [#6855](https://github.com/stablyai/orca/pull/6855), [#6868](https://github.com/stablyai/orca/pull/6868), [#6856](https://github.com/stablyai/orca/pull/6856), [#6857](https://github.com/stablyai/orca/pull/6857).
-- Windows shell/spawn/input: [#6537](https://github.com/stablyai/orca/pull/6537), [#6876](https://github.com/stablyai/orca/pull/6876), [#6858](https://github.com/stablyai/orca/pull/6858), [#6890](https://github.com/stablyai/orca/pull/6890).
-- Hidden/agent startup behavior: [#6824](https://github.com/stablyai/orca/pull/6824), [#6798](https://github.com/stablyai/orca/pull/6798), [#6836](https://github.com/stablyai/orca/pull/6836).
-
-## Last-Seven-Day Regression Origin Map
-
-This section maps recent regressions to the place where the system failed, and to the gate that should catch the same class next time.
-
-| Issue | Symptom | Regression point | Fix / related PR | Missing gate |
-| --- | --- | --- | --- | --- |
-| [#6773](https://github.com/stablyai/orca/issues/6773) | New terminal/agent tab opens and closes immediately | Dead-session reconciliation could treat a fresh PTY binding as absent from a stale `listSessions()` snapshot. This likely traces to the local dead-session reconcile path introduced for hidden exited panes in [#6514](https://github.com/stablyai/orca/pull/6514). | [#6796](https://github.com/stablyai/orca/pull/6796), [#6801](https://github.com/stablyai/orca/pull/6801) | Newborn terminal lifecycle test: create shell and agent tabs while liveness reconciliation is in flight; assert the tab cannot be closed by an older snapshot. |
-| [#5356](https://github.com/stablyai/orca/issues/5356) | First launch after upgrade loses active floating/agent terminal sessions | Cold-restore relied on state that only versions after the fix could write, so users upgrading from pre-fix versions had no migration source. Issue text explicitly names [#5234](https://github.com/stablyai/orca/pull/5234) and [#5240](https://github.com/stablyai/orca/pull/5240). | Not fully closed in current open `P0` set | Upgrade fixture test: boot current app with persisted state from the last affected production version and assert active terminal/agent sessions are preserved or visibly recoverable. |
-| [#5319](https://github.com/stablyai/orca/issues/5319) | Linux/Wayland terminals render but stop accepting keyboard/scroll input | Wayland-aware GPU safeguard was removed in [#1344](https://github.com/stablyai/orca/pull/1344), leaving eager GPU channel setup able to wedge terminal input on affected systems. | [#6557](https://github.com/stablyai/orca/pull/6557) | Platform GPU matrix test: Linux Wayland launch with terminal WebGL/input smoke and assertion that GPU flags preserve input, not only rendering. |
-| [#6233](https://github.com/stablyai/orca/issues/6233) | Windows process runs but no window appears | Startup window reveal depended on Electron `ready-to-show`; if that event stalled, there was no fallback reveal or user-visible failure. | [#6462](https://github.com/stablyai/orca/pull/6462) | Startup watchdog test: simulate missing `ready-to-show` on Windows and assert the app either reveals or exits with a clear recovery path. |
-| [#6163](https://github.com/stablyai/orca/issues/6163) | Orca-managed Codex `config.toml` fails with duplicate `hooks.state` keys on Windows | Two TOML writers serialized the same Windows path key differently, and Orca deduped textually rather than by decoded key. | [#6318](https://github.com/stablyai/orca/pull/6318), follow-up [#6388](https://github.com/stablyai/orca/pull/6388) bug-scan fix | Cross-writer config round-trip test: seed config with Codex-written literal Windows paths, run Orca hook sync twice, then parse with a TOML parser and assert one decoded key. |
-| [#6244](https://github.com/stablyai/orca/issues/6244) | Headless-launched automation terminal showed only a bash prompt until unmount/remount | Hidden/background automation worktrees were not mounted early enough for output/replay to hydrate on first view. | [#6568](https://github.com/stablyai/orca/pull/6568) | Headless automation mount test: launch background automation, wait for output, first-focus the tab, and assert output is already visible. |
-| [#6331](https://github.com/stablyai/orca/issues/6331) | WSL workspaces with UNC cwd hit `DaemonProtocolError` | Windows/WSL path handling crossed provider boundaries and daemon spawn assumptions. | [#6536](https://github.com/stablyai/orca/pull/6536) | WSL UNC provider contract: add/open/delete workspace whose root is `\\wsl.localhost\...`; assert daemon and file operations use the right host/path semantics. |
-| [#6336](https://github.com/stablyai/orca/issues/6336) | Monorepo subfolder import opened the repo root instead of the selected subfolder | Git-root normalization leaked into the first-terminal cwd/user-facing workspace root behavior. | [#6574](https://github.com/stablyai/orca/pull/6574) | Add-project matrix: repo root, monorepo subfolder, folder workspace, remote runtime; assert file tree root and first terminal cwd separately. |
-| [#6147](https://github.com/stablyai/orca/issues/6147) | Chinese full-width punctuation became half-width ASCII in terminal | IME/composition forwarding lacked coverage for macOS full-width punctuation and composition-owned text. | [#6417](https://github.com/stablyai/orca/pull/6417) | IME matrix test: macOS CJK full-width punctuation, Vietnamese Telex, Linux fcitx/Sogou, Windows CJK; assert committed bytes and displayed cells. |
-| [#5656](https://github.com/stablyai/orca/issues/5656) / [#5653](https://github.com/stablyai/orca/issues/5653) | Windows Claude Code prompt showed phantom/overwritten characters until resize | Rewrite-style terminal output did not reliably force visible row repaint for CR/CHA/erase updates. | [#6544](https://github.com/stablyai/orca/pull/6544), [#6449](https://github.com/stablyai/orca/pull/6449) | Terminal redraw fixture: feed CR, CHA, backspace, erase-line/screen and assert visible cells after each chunk without resize. |
-| [#5161](https://github.com/stablyai/orca/issues/5161) | PowerShell terminal failed to spawn with Windows error code 5 | Windows shell resolver handed ConPTY a bare `pwsh.exe`, which could resolve to an App Execution Alias stub. | [#6537](https://github.com/stablyai/orca/pull/6537), [#6876](https://github.com/stablyai/orca/pull/6876) | Windows shell resolution contract: auto and explicit PowerShell selections must resolve to real executables and skip WindowsApps aliases. |
-| [#6270](https://github.com/stablyai/orca/issues/6270) | Restoring agent sessions was not working for SSH/runtime use cases | Resume logic and runtime host restrictions did not cover SSH workspaces. | [#6685](https://github.com/stablyai/orca/pull/6685) | Agent resume provider matrix: local, daemon, SSH, remote runtime, Windows shell; assert resume command is queued on the configured host/provider. |
-| [#6852](https://github.com/stablyai/orca/pull/6852) / [#6872](https://github.com/stablyai/orca/pull/6872) | Terminal search could crash terminal surface on narrow viewports | xterm search decorations received invalid dimensions and threw through the terminal surface. | [#6852](https://github.com/stablyai/orca/pull/6852), [#6872](https://github.com/stablyai/orca/pull/6872) | xterm addon safety test: narrow viewport, zero/near-zero columns, wrapped matches, keyboard next/previous; assert addon errors are caught and pane remains usable. |
-| [#6855](https://github.com/stablyai/orca/pull/6855) | xterm web-link provider `RangeError` could kill the Windows renderer | Link provider ran synchronously inside xterm with no guard around pathological wrapped lines. | [#6855](https://github.com/stablyai/orca/pull/6855) | Addon boundary policy: all xterm addon callbacks are guarded and failure disables only that addon for that pane. |
-| [#6853](https://github.com/stablyai/orca/pull/6853) | Split-right PTY stayed at `0x0` and rendered a white screen | Deferred spawn measured an unlaid-out pane; post-spawn reconcile could terminate before forwarding a usable size. | [#6853](https://github.com/stablyai/orca/pull/6853) | Split spawn invariant: visible panes must never keep PTY size `0x0`; fallback size must be forwarded if measurement is unavailable. |
-
-The repeated pattern is not one person repeatedly making the same mistake. It is that Orca does not yet have enough executable contracts around lifecycle, provider boundaries, terminal sizing, xterm safety, platform shell behavior, and upgrade state.
-
-## PR Process Evidence
-
-Reading the PR descriptions for the confirmed or likely regression chains shows that the failure was usually not "no process." The failure was that the process accepted plausible local validation without requiring the invariant that would have protected the escaped user path.
-
-### #6514: Dead-Session Reconcile Introduced a Newborn-Tab Hazard
-
-[PR #6514](https://github.com/stablyai/orca/pull/6514) was a Brennan-authored reliability fix for frozen terminal panes after a backgrounded agent exits. The PR body shows a substantial process: design review, completeness verification, headline behavior status, perf audit, code-review loop, Electron validation, and targeted unit tests. The stated non-goal explicitly excluded SSH/remote reconciliation, and the implementation revalidated pane/PTY identity at apply time.
-
-What still got through:
-
-- The PR protected "stale dead pane should close" but did not name the dual invariant "a fresh or newly bound pane cannot be closed by a liveness snapshot requested before that binding existed."
-- The tests covered live/dead/remote/idempotency paths, but not the TOCTOU case where `listSessions()` is requested, a new PTY binds before the response returns, and the stale response omits the newborn id.
-- Reviewers accepted "healthy panes are untouched" as a semantic claim, but the executable gate did not prove that claim under delayed session enumeration.
-
-Skill implication:
-
-- `brennan-yolo-lite`, `auto-design-review-fix`, `review-code`, and `brennan-test-changes` all need to force lifecycle changes to state the inverse safety property, not only the intended cleanup behavior.
-- For terminal lifecycle changes, the review checklist should ask "what newer state can this async observation accidentally destroy?"
-
-### #5234 and #5240: Session-Restore Fixes Missed Old-Version Upgrade Fixtures
-
-[PR #5234](https://github.com/stablyai/orca/pull/5234) and [PR #5240](https://github.com/stablyai/orca/pull/5240) were Jinwoo-authored fixes for slow-startup daemon PTY restoration and quit-time agent session persistence. Their PR descriptions show AI review, negative controls, targeted tests, and high-quality e2e coverage against the newly modeled behavior.
-
-What still got through:
-
-- The tests proved the new behavior once the new data and startup gates existed.
-- They did not appear to boot the current app against serialized persisted state from the affected production versions before the fix.
-- The escaped class is an upgrade/migration class: a fix can be correct for state written after the fix while still losing users who upgrade from state written before it.
-
-Skill implication:
-
-- Startup, restore, daemon, and persistence PRs need an "old state corpus" gate: seed data from the last affected production version, not only state produced by current code.
-- Negative controls should include "old production fixture fails before fix and is preserved after fix" when the bug is upgrade-related.
-
-### #1344: GPU Rendering Parity Missed Linux Wayland Input Failure
-
-[PR #1344](https://github.com/stablyai/orca/pull/1344) replaced global GPU opt-ins with VS Code-style GPU startup flags and terminal GPU acceleration settings. The PR description cites reference behavior and local tests, but it does not show the later, stricter Brennan PR process markers used in the June reliability fixes.
-
-What still got through:
-
-- The change removed or bypassed the Wayland-aware GPU safeguard later identified by [PR #6557](https://github.com/stablyai/orca/pull/6557).
-- Validation covered configuration and pane lifecycle tests, but not a Linux Wayland terminal input smoke where rendering appears live while keyboard/scroll input is wedged.
-- One TypeScript command was reported as failing on existing project-include issues, which made the PR less clean as a release-risk artifact.
-
-Skill implication:
-
-- Cross-platform rendering/startup changes need an explicit platform matrix tied to the failure mode: not just "renders," but "renders and accepts input."
-- Reference implementations are useful context, but factory review must still require Orca-specific platform hazards to be named and tested or accepted.
-
-### Regression Lessons From Fresh Review
-
-Fresh reviewer passes on the recent regression chains pointed to these reusable misses. These are class-level gates, not new blame findings.
-
-- [#6514](https://github.com/stablyai/orca/pull/6514) -> [#6773](https://github.com/stablyai/orca/issues/6773), fixed by [#6796](https://github.com/stablyai/orca/pull/6796) and [#6801](https://github.com/stablyai/orca/pull/6801): the original PR correctly proved the forward cleanup case, where a hidden local/daemon PTY exits and should reconcile on resume while live listed panes survive. The missed invariant was the inverse lifecycle property: a destructive liveness snapshot can only close state that existed before the snapshot was requested. The escaped path was a macOS local new shell or agent tab where `listSessions()` was requested, a new PTY bound before the response returned, the stale response omitted the newborn id, and the renderer routed the healthy binding through exit teardown. The next gate is a Terminal Snapshot Freshness and Ownership Gate: a fake daemon holds `listSessions()` at `t0`, binds a newborn PTY at `t1`, resolves the stale `t0` snapshot without that PTY, and asserts the tab/pane survives, still owns the same PTY, accepts input, and renders output. A later post-bind snapshot may close a genuinely dead PTY, but only when provider, pane, PTY id, and binding epoch still match.
-- [#6800](https://github.com/stablyai/orca/pull/6800), with [#5240](https://github.com/stablyai/orca/pull/5240), [#6411](https://github.com/stablyai/orca/pull/6411), [#6514](https://github.com/stablyai/orca/pull/6514), and [#6833](https://github.com/stablyai/orca/pull/6833) as related context: the original fix correctly proved that active worktree-sleep records should not be claimed merely because old tab/layout state exists; visible connecting panes with restorable identity can own wake, stale hidden panes fresh-resume, and completed hibernation evidence stays passive. The missed invariant was provider-session ownership, not "pane connects now." For each provider-session claim key, exactly one durable owner must exist: a live hook/status for that same provider session, a queued/sent resume command for that same provider session, or an explicit retained record because spawn/connect failed. Layout match, PTY wake hints, replayed terminal bytes, and cold-restored screen snapshots are display evidence, not ownership evidence. The next gate is an Agent Provider Session Ownership Matrix covering active focused tabs, inactive tabs, visible non-focused splits, live/quit/worktree-sleep origins, replay-only/cold-restore-only/wrong-session/no-hook/delayed-hook cases, and repeated workspace activation.
-- [#5234](https://github.com/stablyai/orca/pull/5234) / [#5240](https://github.com/stablyai/orca/pull/5240) -> [#5356](https://github.com/stablyai/orca/issues/5356): the original PRs correctly proved slow-daemon restoration and newly written quit-origin provider-session persistence. The missed invariant was first-open-after-upgrade compatibility: startup/restore fixes must preserve or explicitly recover user sessions from the last affected production persisted-state schema, not only from state written by the fixed build. The escaped path was first launch after a 1.4.65 -> 1.4.68 upgrade, including Windows 10 active floating shell and Claude panes, where the old version had no `sleepingAgentSessionsByPaneKey` payload to consume. The next gate is a Persisted Session Upgrade/Restore Contract: boot current Orca against immutable user-data fixtures from the last affected version, including active and inactive tabs, visible and hidden splits, old tab-level PTY wake hints, missing `sleepingAgentSessionsByPaneKey`, live/quit/worktree-sleep/legacy origins, repeat activation, and a second restart after current code writes upgraded state. The oracle rejects blank replacement panes, duplicate resume tabs, silent session loss, and "works only after current code writes new state."
-- [#1344](https://github.com/stablyai/orca/pull/1344) -> [#5319](https://github.com/stablyai/orca/issues/5319) / [#6557](https://github.com/stablyai/orca/pull/6557): the original PR correctly attempted to replace broad GPU opt-ins with VS Code-style GPU channel flags and prove terminal GPU/WebGL fallback at unit level. The missed invariant was terminal platform liveness, not visual readiness. A terminal is healthy only if it renders output, receives focus, delivers keyboard input to the correct PTY, echoes process output back to the xterm buffer, scrolls, and survives GPU/renderer startup on the target platform. The next gate is a Terminal Platform Liveness Gate across Linux Wayland GPU paths, headless Weston plus at least one scheduled/manual headful Wayland run, control Linux/macOS/Windows paths when renderer policy is shared, active and inactive tabs, visible and hidden panes, first mount, tab switch, repeated workspace activation, local PTY, and SSH/remote PTY. Screenshots alone never pass.
-- [#6644](https://github.com/stablyai/orca/pull/6644) / [#6649](https://github.com/stablyai/orca/pull/6649) / [#6725](https://github.com/stablyai/orca/pull/6725) / [#6785](https://github.com/stablyai/orca/pull/6785) / [#6794](https://github.com/stablyai/orca/pull/6794) / [#6853](https://github.com/stablyai/orca/pull/6853) / [#6939](https://github.com/stablyai/orca/pull/6939): the fixes correctly proved pieces of the PTY geometry class: first-mount column desync, single-frame insufficiency, split-mount convergence, requested-size versus applied-size drift, mobile-owned PTY exceptions, visible split `0x0` fallback, and visible geometry reassertion after stable fit. The missed invariant was cross-layer terminal geometry authority. A visible desktop-owned terminal is not valid until xterm `cols/rows`, fit/proposed dimensions, applied PTY winsize, shell-visible `stty`/`stdout.columns`, and echo-wrap behavior converge after layout settles. Hidden/inactive panes may defer resize, and mobile/remote providers may intentionally diverge, but every transition into visible desktop ownership must converge. The next gate is a terminal geometry matrix with fault injection for first `0x0` fit, delayed layout settle, dropped/delayed resize acknowledgement, requested-size-versus-applied-size drift, SSH-style unknown applied size, hidden-to-visible activation, split create/collapse, restore, repeated workspace activation, and no redundant hidden SIGWINCH.
-- [#6852](https://github.com/stablyai/orca/pull/6852) / [#6872](https://github.com/stablyai/orca/pull/6872) / [#6855](https://github.com/stablyai/orca/pull/6855), with [#6868](https://github.com/stablyai/orca/pull/6868), [#6856](https://github.com/stablyai/orca/pull/6856), and [#6857](https://github.com/stablyai/orca/pull/6857) as nearby WebGL/renderer-risk hardening: the fixes correctly moved toward safe wrappers for search dimensions, keyboard search navigation, link providers, WebGL addon patches, and renderer/GPU crash fallback. The missed invariant was xterm addon boundary containment. Optional addons are untrusted boundary code: search decorations, link providers, WebGL attach/reset/dispose, renderer fallback, hover callbacks, and stale async callbacks must not throw across the pane, React, or window boundary. The next gate is an xterm-addon-boundary harness that injects throwing addon behavior under active tabs, inactive tabs, visible and hidden splits, hidden-to-visible resume, floating tab switch, repeated workspace activation, and pane destroy/recreate; the oracle is pane-scoped addon disable/degrade with one breadcrumb, no React/window crash, and surviving focus, input, PTY echo, and rendering.
-
-Concrete gate shapes from the fresh passes:
-
-- **Snapshot freshness harness**: defer and reorder `listSessions()` / `listTerminals()` responses. Request a snapshot at `t0`, bind a new PTY at `t1`, resolve the `t0` response without the new PTY, and assert the pane survives with PTY id, tab ownership, and input/output proof. Then request a fresh `t2 > t1` snapshot for a genuinely killed PTY and assert teardown works. Run active/inactive tabs, visible/hidden splits, first-input probes, restore/reattach, repeat activation, and SSH/remote unknown-liveness variants.
-- **Provider-session ownership matrix**: model provider-session ownership separately from terminal render output. For live, quit, active worktree-sleep, and completed worktree-sleep origins, prove each provider session is exactly one of owned, resuming, or intentionally retained. Cover active focused tabs, inactive hidden tabs, visible non-focused splits, delayed/missing/wrong hooks, duplicate legacy records, fresh-spawn failure, and repeat activation. Displayed replay must never count as ownership.
-- **Old-version restore corpus**: keep immutable user-data fixtures from the last affected production versions, especially pre-#5232 session state. Boot current Orca against those fixtures and assert every persisted PTY/agent record is preserved, resumed once, warm-reattached once, or visibly marked unrecoverable. Include second restart after current Orca writes upgraded state.
-- **Wayland platform liveness**: extend the Linux Wayland verifier so it proves terminal render, focus, keyboard input, PTY echo, scrollback movement, and GPU crash/stall absence across active/inactive tabs, visible/hidden splits, first mount, tab switch, restore, repeated activation, local PTY, and SSH/remote runtime. Screenshot-only evidence is not enough.
-- **Terminal geometry convergence**: add an `assertTerminalGeometryConverged` oracle that compares xterm cols/rows, fit/proposed dimensions, applied PTY size when available, shell-visible `stty size` / `$COLUMNS`, and deterministic echo/wrap behavior. Inject dropped resize, delayed resize until visible, stale applied size, null SSH-style readback, initial `0x0`, and layout settling after more frames than old fixed budgets.
-- **xterm addon boundary harness**: inject throwing search decorations, link providers, WebGL attach/reset/dispose, and stale async callbacks under active tab, inactive tab, visible split, hidden split, hidden-to-visible resume, floating tab switch, repeat activation, and pane destroy/recreate. Assert no `window.onerror` or React boundary hit, one structured breadcrumb, addon-scoped degradation, focus/input survival, PTY/output rendering, and WebGL fallback to DOM when needed.
-
-### Corrective PRs Show the Desired Direction
-
-The later fixes, especially [#6801](https://github.com/stablyai/orca/pull/6801), show the right shape: root-cause description, happens-before proof, explicit `auto-design-review-fix`, completeness verification, code-review loop, `brennan-test-changes`, and targeted tests for the stale snapshot/newborn binding race. [#6852](https://github.com/stablyai/orca/pull/6852), [#6853](https://github.com/stablyai/orca/pull/6853), and [#6855](https://github.com/stablyai/orca/pull/6855) also show good local invariant tests around xterm addon throws and PTY `0x0` sizing.
-
-The process improvement is to make that shape mandatory before the regression escapes, and to promote only the deterministic, red/green parts into blocking CI.
-
-## Core Pain Points
-
-### 1. Terminal Lifecycle Is Inferred Instead of Owned
-
-Many paths infer terminal state from a combination of pane visibility, provider session membership, stored pane layout, active leaf ids, sleeping-agent records, and xterm mount state. That makes it easy for a stale observation to tear down a fresh pane, or for a dead pane to look live.
-
-Common symptoms:
-
-- New tab opens and immediately closes.
-- Hidden terminal exits but the visible pane later looks frozen and swallows input.
-- Sleeping or hibernated agents get stranded in stale panes.
-- Mobile and desktop disagree about which terminal/session still exists.
-
-### 2. PTY Size Authority Is Split Across Too Many Places
-
-`FitAddon`, `ResizeObserver`, deferred `requestAnimationFrame`, mobile-fit locks, hidden-pane guards, PTY locks, split layout equalization, and provider resize forwarding all compete to decide the active terminal size.
-
-Common symptoms:
-
-- PTY born at `0x0`.
-- White split pane.
-- First-mount column desync.
-- TUI output wraps at the wrong width until manual resize.
-- Mobile-size terminals fight desktop-size restoration.
-
-### 3. xterm Addons Are Unsafe Boundary Code
-
-The terminal surface trusts addon behavior too much. Recent failures came from search decorations, web-link providers, WebGL texture atlas resets, CJK/wide glyph rendering, and synchronized-output buffering.
-
-Any addon that can throw synchronously or produce invalid dimensions can take down the workbench unless Orca wraps it defensively.
-
-### 4. Provider Semantics Drift
-
-Local PTY, daemon PTY, SSH relay, remote runtime, WSL, Windows ConPTY, Linux Wayland, and mobile sessions do not share the same truth source for liveness, size, replay, cwd, shell, or reconnect behavior.
-
-Common symptoms:
-
-- Local-only liveness checks are accidentally applied to SSH/remote panes.
-- Remote paths miss fixes made only in the renderer.
-- WSL works through CLI add but not UI add.
-- Daemon can be protocol-healthy while PTY spawn is degraded.
-
-### 5. Agent Identity Is Coupled to Terminal UI Details
-
-Agent status, sidebar rows, compact rows, mobile session tabs, sleeping-agent records, terminal helper identity, and pane reuse all share responsibility for "what agent is this?"
-
-Common symptoms:
-
-- Duplicate agent tabs.
-- Stale sidebar rows after terminal close.
-- Wrong agent icon/title.
-- False running/completed notifications.
-- Worktree switching changes agent ordering or ownership.
-
-Class-level invariant:
-
-- Agent/provider session replay must be ownership-safe. When code touches agent launch, restore, sleep, hibernate, dedupe, clearing, or workspace activation, it must prove Orca does not replay or resume a provider session id that is already owned, queued, pending, or live in that workspace. This applies across active and inactive tabs, visible and hidden panes, repeat activation of the same workspace, and session records whose origin is live, quit, or worktree sleep.
-- Motivating example: the #6800 escape showed how code can conflate "this pane will connect right now" with "this pane/session owns this provider session." A valid inactive or hidden existing session can then look unowned, causing workspace activation to replay `agent resume <same-session-id>` instead of recognizing the session is already represented. The gate should protect the whole class, not only the #6800 path.
-- Display evidence is not ownership evidence. Replayed terminal bytes, cold-restored screen snapshots, tab layout matches, and "will connect soon" state must never count as proof that a provider session id is already claimed.
-
-### 6. Upgrade and Startup Are Under-Tested as First-Class Flows
-
-Several failures only appear after an app update, daemon survival across versions, old persisted state, stale helper paths, or a first launch after migration.
-
-Common symptoms:
-
-- First launch after upgrade loses sessions.
-- Daemon remains reachable but cannot spawn PTYs.
-- App process runs but no window appears.
-- Release packaging/notarization works at top level but fails for a nested binary.
-
-### 7. Reliability Fixes Can Regress Performance or Crash Safety
-
-Several reliability fixes add watchers, reconciliation loops, terminal replay, git scans, or richer diagnostics. Those are high-risk performance surfaces if they wake hidden panes, serialize large state, multiply subprocesses, or make cleanup scans wait for final results before showing progress.
-
-Common symptoms:
-
-- Terminal input becomes correct but slower under foreground TUI redraw or background PTY output.
-- Hidden panes keep waking the renderer for data/title/spinner frames.
-- Store subscribers or persistence writes serialize large terminal/worktree maps on common interactions.
-- Git/worktree cleanup opens a modal that spins, duplicates rows, hangs on a subprocess, or crashes on Windows/WSL/SSH paths.
-- Safety checks run unbounded git subprocesses or trust stale cleanup evidence before destructive removal.
-
-## Proposed Improvements
-
-### A. Build a Terminal Lifecycle State Machine
-
-Create a single source of truth for terminal lifecycle:
-
-- `newborn`
-- `connecting`
-- `live`
-- `hidden-live`
-- `exited-observed`
-- `exited-unobserved`
-- `hibernated`
-- `restoring`
-- `degraded`
-- `closed`
-
-All teardown, restore, reconnect, hibernation, and liveness decisions should transition through this machine. Avoid having individual React effects independently infer lifecycle from partial state.
-
-### B. Make Liveness Reconciliation Epoch-Based
-
-Every pane/PTY binding should carry a monotonic renderer-local epoch or generation. Any async liveness snapshot must include the epoch it was requested against.
-
-Rules:
-
-- A snapshot requested before a bind cannot close that bind.
-- A provider membership result can only prove death when the current binding still exactly matches the request context: pane id, provider id, connection id, PTY id, and epoch.
-- Remote/SSH/WSL providers must supply provider-scoped liveness, or the reconciler must treat them as unknown.
-
-This generalizes the timestamp guard added for newborn terminal tabs and makes it harder to reintroduce the class.
-
-### C. Define a PTY Size Ownership Protocol
-
-Document and enforce one protocol for size authority:
-
-- Initial spawn size source.
-- Hidden-pane spawn behavior.
-- Mobile-fit lock behavior.
-- Split layout settle behavior.
-- Fallback size behavior.
-- Provider resize acknowledgement.
-- Applied PTY size reporting.
-- Dropped, delayed, or skipped resize recovery.
-- Hand-off from reconcile loop to live `ResizeObserver`.
-
-Add invariant tests that a visible terminal never remains `0x0`, and that xterm `cols/rows` converge with PTY-reported `cols/rows` under split, restore, reload, and mobile-fit scenarios.
-
-Class-level invariant:
-
-- A visible terminal pane must have one authoritative size path from layout measurement to xterm fit to provider resize to applied PTY size. `0x0` and unknown layout measurements are non-authoritative for visible panes. If a resize is skipped because of a mobile lock, PTY lock, hidden state, split layout settle, first mount, provider delay, or dropped acknowledgement, Orca must keep reconciling until the applied PTY size and xterm size converge or the pane enters an explicit degraded state.
-
-Required deterministic hooks:
-
-- Force first measurement to `0x0` during split-right spawn.
-- Delay split layout settlement across frames.
-- Hold and release mobile-fit or PTY locks while reconcile is active.
-- Drop or delay one provider resize acknowledgement.
-- Report applied PTY size separately from requested size.
-- Switch hidden-to-visible or worktree-to-worktree while a resize is pending.
-
-Required oracle:
-
-- After the fault, assert visible xterm `cols/rows`, provider-reported applied PTY `cols/rows`, and process-observed `stdout.columns/rows` converge.
-- Assert a width-sensitive TUI or long-line fixture renders without one-column wrapping.
-- Assert typed input reaches the process and echoed output appears after convergence.
-- Assert no test is promoted to blocking if it relies on blind `waitForTimeout()` instead of size/lifecycle events or controlled fault release.
-
-### D. Add Provider Contract Tests
-
-Start with a deterministic fake/fault-injection provider, then run the same lifecycle contract against real providers.
-
-The fake provider should be able to:
-
-- Delay and reorder `listSessions()` responses.
-- Return `unknown` separately from empty/live/dead.
-- Delay attach/replay and resize acknowledgements.
-- Kill processes while panes are hidden.
-- Drop or duplicate exit/replay/resize events.
-- Simulate stale cwd/helper paths.
-
-After the fake provider is stable, run the contract against:
-
-- local PTY
-- daemon PTY
-- degraded daemon wrapper
-- SSH relay
-- remote runtime
-- WSL path/shell combinations
-- mobile session replay
-
-Required scenarios:
-
-- spawn
-- hidden spawn
-- visible restore
-- hidden exit
-- reconnect
-- resize before/after mount
-- cwd deleted
-- helper binary moved after upgrade
-- process dies while renderer is hidden
-
-### E. Create a Terminal Torture Harness
-
-Add a nightly and pre-release reliability suite that exercises:
-
-- rapid tab create/close
-- agent create/close
-- split right/down
-- reload with split layout
-- hidden-to-visible switching
-- huge streaming TUI output
-- CJK, Vietnamese, Arabic, and emoji input/output
-- long paste, link paste, image paste
-- browser/terminal focus handoffs
-- hibernation wake
-- daemon restart/degraded fallback
-- mobile connect/disconnect during active terminal traffic
-
-This should record screenshots, terminal snapshots, PTY sizes, lifecycle transitions, and renderer CPU.
-
-Each scenario must also declare its oracle before it can be promoted beyond `experimental`: the observable pass condition, the failure artifact, and whether it is a discovery/stress run or a merge-blocking gate. Stress scenarios without deterministic oracles should stay nightly/pre-release only.
-
-### F. Wrap xterm Addons Behind Safe Adapters
-
-Search, links, WebGL, decorations, and input-protocol helpers should be treated as untrusted code:
-
-- Catch synchronous addon throws.
-- Validate all rows/cols/decoration dimensions before calling xterm APIs.
-- Disable or degrade an addon for a pane after repeated failures.
-- Emit a structured breadcrumb with pane id, provider, terminal size, addon name, and sanitized error.
-
-Class-level invariant:
-
-- xterm addon failures must be contained to the addon and pane. A search, link, WebGL, decoration, input-protocol, or keyboard-navigation error must never unmount the terminal surface, crash the renderer, break focus, or stop typed input/output for the PTY. Invalid dimensions, wrapped-line ranges, zero columns, texture atlas resets, and synchronous callback throws should either be validated away before the addon call or caught and downgraded after the call.
-
-Required deterministic hooks:
-
-- Force zero or near-zero terminal columns.
-- Force wrapped search and link ranges across line boundaries.
-- Throw from search, link, decoration, and WebGL callback boundaries.
-- Simulate WebGL texture/atlas reset or addon initialization failure.
-- Invoke next/previous search navigation while the search addon reports an invalid match.
-
-Required oracle:
-
-- The terminal pane remains mounted and focused.
-- The failing addon is disabled or downgraded only for the affected pane.
-- A structured breadcrumb names the addon and sanitized failure.
-- Typed input reaches the process and echoed output appears after the addon failure.
-
-### G. Add Upgrade Fixtures
-
-Keep serialized workspaces and daemon/session state from known old versions:
-
-- pre-#5232 session restore data
-- stale daemon cwd
-- stale node-pty helper path
-- old hibernated agent records
-- old mobile session snapshots
-- old Windows shell settings
-
-CI should boot the current app against these fixtures and assert no session loss, no blank first pane, and no startup deadlock.
-
-Fixture rules:
-
-- Name the exact production version and build source.
-- Store the pre-migration state immutably and copy it to a temp profile before boot.
-- Document the expected pre-migration shape and post-migration behavior.
-- Include stale daemon/helper/path state when that is the real user upgrade path.
-- Treat silent blank replacement as a failure. If exact restoration is impossible, the accepted outcome must be an explicit recoverable/degraded state or user-facing migration notice, not silent session loss.
-
-### H. Add Platform Startup, Input, and Release Artifact Contracts
-
-Some failures look visually healthy while the product is broken. Platform contracts must prove the user action, not only the frame.
-
-Required contracts:
-
-- Terminal rendering/input: on Linux Wayland, Windows ConPTY, and macOS, assert the terminal renders, accepts typed input, echoes process output, scrolls, and preserves focus after GPU/renderer startup paths touched by the PR.
-- IME/input: when terminal input handling changes, assert representative CJK, Vietnamese, Arabic, paste, and modifier paths at the lowest deterministic layer available.
-- Startup/window lifecycle: packaged app reveals, close button and Alt+F4 work on Windows, startup watchdogs recover when `ready-to-show` stalls, and PATH/shell probes time out with a recoverable state.
-- Release artifact: packaged builds include required nested binaries and pass signing/notarization checks, not only top-level app validation.
-- Daemon degradation: daemon reachable-but-unable-to-spawn and stale helper/cwd states produce a visible degraded path instead of blank or frozen terminals.
-
-### I. Add an Agent Identity Contract
-
-Provider and terminal tests are not enough for agent/session identity drift. Add a contract for:
-
-- Pane reuse and tab close.
-- Worktree switch and sidebar ordering.
-- Sleep/wake and hibernation records.
-- Provider session id capture and consumption.
-- Mobile rows and desktop rows converging after terminal close.
-- False running/completed notifications.
-- Agent history/filter visibility for restored sessions.
-- Provider session replay ownership: workspace activation, launch, restore, sleep/hibernate, dedupe, clearing, and reconnect code must not issue a second resume/launch for a provider session id already owned by an active tab, inactive tab, visible pane, hidden pane, queued pane, pending connection, or live session in the same workspace.
-- Session record origins: the same invariant must be proved for live sessions, quit-restored sessions, and worktree-sleep records, including repeat activation of an already-active workspace.
-
-Required agent identity scenarios:
-
-- Activate a workspace with an existing visible live agent pane; assert no duplicate `resume <provider-session-id>` is queued.
-- Activate a workspace with an existing hidden/inactive live agent pane; assert the provider session is recognized as represented even before the pane visibly reconnects.
-- Re-activate the same workspace repeatedly while agent restore/session discovery is pending; assert the pending ownership claim dedupes all replay attempts.
-- Restore a quit-origin session and a worktree-sleep-origin session; assert each is claimed once, survives hidden-to-visible transitions, and does not produce duplicate sidebar/mobile rows.
-- Clear or close stale panes while a same-session replacement is queued or pending; assert cleanup cannot erase the newer ownership claim or trigger a second replay.
-
-### J. Introduce Reliability Gates for Terminal/Session PRs
-
-For PRs touching terminal, agent status, sessions, startup, provider routing, or hibernation, require:
-
-- Provider matrix explicitly listed.
-- Hidden-pane behavior listed.
-- SSH/remote behavior listed.
-- Windows/WSL behavior listed when shell, cwd, path, ConPTY, or process launch is touched.
-- A regression test that fails against the old behavior.
-- A manual or automated stress command if the change touches timing.
-- PTY size authority proof when the PR touches terminal spawn, split layout, hidden/visible transitions, mobile fit, resize forwarding, PTY locks, provider resize acknowledgement, or xterm fit. The proof must cover `0x0` quarantine, requested versus applied PTY size, xterm/process size convergence, and a user-visible input/output oracle.
-- Agent/provider replay ownership proof when the PR touches agent launch, restore, sleep/hibernate, dedupe, clearing, workspace activation, pane reuse, provider session id capture, sidebar/mobile agent rows, or session history. The proof must cover active versus inactive tabs, visible versus hidden panes, repeat workspace activation, and live, quit, and worktree-sleep session record origins.
-- xterm addon containment proof when the PR touches search, links, WebGL, decorations, keyboard terminal shortcuts, synchronized output, or xterm addon registration. The proof must show addon throws and invalid geometry cannot crash the terminal surface, unmount the pane, or break typed input/output.
-- The terminal/session checklist should explicitly ask: "Can this change make an already represented provider session look unowned, or replay/resume it a second time?"
-- The terminal/session checklist should explicitly ask: "Can this change make a visible pane trust `0x0`, stale requested size, or renderer-only size instead of the size the PTY actually applied?"
-- The terminal/session checklist should explicitly ask: "Can an xterm addon callback or invalid addon geometry throw through the terminal surface instead of being contained?"
-
-### K. Make Reliability Tests Predictable and Useful
-
-The goal is not "more tests." The goal is a small set of executable contracts that protect named invariants from real failures.
-
-Required shape for every new reliability gate:
-
-- Name the invariant it protects.
-- Name the real issue, PR, or failure mode that motivated it.
-- Prove red/green: the gate must fail against the old behavior, a regression fixture, or a small intentionally broken variant before it becomes a trusted blocker.
-- Attach a promotion record: invariant id, motivating issue/PR, old-fail evidence, new-pass evidence, exact command, failure output or CI link, deterministic wait condition, owner, runtime budget, and demotion rule.
-- Pick the cheapest deterministic layer: pure state-machine or provider-contract tests first, integration tests second, Electron/UI tests only for the small number of golden paths that require the real app shell.
-- Avoid sleeps as proof. Wait for observable state, protocol events, lifecycle transitions, PTY size convergence, replay completion, or process exit.
-- Record why the test is allowed to block merges: expected runtime, flake history, covered invariant, and owner.
-
-Test maturity levels:
-
-- `experimental`: local or nightly only; useful for shaking out the harness, not allowed to block merges.
-- `soak`: runs repeatedly in CI but non-blocking; collects flake rate, runtime, and whether failures are actionable.
-- `blocking`: promoted only after red/green proof, stable runtime, and low flake rate.
-
-Flake policy:
-
-- Blocking promotion should require numeric evidence, for example 100 consecutive soak runs or 14 days across required CI platforms, p95 runtime within the gate budget, and zero unexplained flakes. Tune the numbers later, but do not leave "stable" undefined.
-- A blocking reliability test that flakes above the agreed threshold should be demoted or fixed quickly; rerun-only culture hides weak gates.
-- CI should quarantine or demote a blocking test automatically when it exceeds the threshold over the configured window, open or update an owner issue, and require a fresh soak window before re-promotion.
-- A flaky test should be treated as a product or harness bug with an owner, not as background noise.
-- If a scenario cannot be made deterministic yet, keep it as soak/manual evidence and do not let it become required CI until the signal is trustworthy.
-
-Deletion policy:
-
-- Delete or demote tests that do not map to an invariant, duplicate a stronger gate, assert implementation details instead of behavior, only fail from timing/environment noise, or require blind sleeps.
-- Prefer one high-signal contract test over several UI tests that all exercise the same happy path.
-- Track regression coverage by invariant, not by raw test count.
-- Maintain a reliability-gates manifest in the repo. Each gate should list invariant id, motivating issue/PR, layer, owner, maturity, runtime budget, flake history link, promotion record, and replacement gate if deprecated. Tests without current metadata should fail review or be demoted.
-
-How to know the program is working:
-
-- Every recent P0/P1 reliability class maps to an invariant and an executable gate or explicitly accepted gap.
-- New gates carry red/green evidence.
-- Blocking gate flake rate and runtime stay within budget.
-- Future incidents identify either a missing invariant, a failed gate, or an explicit accepted gap instead of requiring archaeology.
-- Accepted gaps have an owner, reason, affected platforms/providers, issue link, and expiry date. Expired gaps should block future high-risk PRs until renewed or closed.
-- The dashboard tracks touched high-risk PRs, gates required, gates implemented, accepted gaps by age/owner, promotions, demotions, and escaped regressions by invariant.
-
-### L. Make Performance and Git Crash Safety First-Class Gates
-
-Correctness gates must include a performance budget when the fix touches terminal throughput, hidden panes, store subscribers, persistence, startup, polling, git/worktree scans, cleanup modals, subprocesses, SSH/WSL providers, or Windows git paths.
-
-Required performance contract:
-
-- Name the user-visible performance symptom that could regress: typing latency, scroll/resize jank, terminal throughput, startup delay, modal loading, CPU, memory, subprocess churn, or crash/reload.
-- Name the resource being protected: renderer frame time, event-loop delay, PTY IPC count, xterm writes, serialized bytes, subprocess count, file descriptors, WebGL contexts, webviews, or retained buffers.
-- Add a before/after measurement or deterministic count/leak test. Do not rely on "felt faster."
-- Keep foreground input echo and control responses latency-sensitive while batching background or high-volume redraw streams.
-- Prove hidden snapshot-capable panes do not wake the renderer per PTY chunk/title frame and restore from main-owned buffers when shown.
-- Preserve `orca terminal read` pagination, cursor metadata, bounded preview behavior, partial-line handling, truncation flags, and total counts when changing terminal buffering.
-- Prove subscriber, persistence, and publication paths avoid unchanged large slices and record serialized byte size when persisted payloads are touched.
-- Keep stress/torture runs non-blocking until they have numeric runtime and flake evidence.
-
-Required git crash/perf contract:
-
-- Bound every git subprocess in scan/cleanup paths with a timeout or abort signal, and kill the process tree where applicable.
-- Use bounded concurrency and in-flight dedupe; avoid one subprocess per repo x worktree x polling tick.
-- Stream progress incrementally to the renderer and remove IPC listeners in `finally`.
-- Verify close/reopen/refresh during active or just-settled scans clears loading state, preserves rows, and does not duplicate progress.
-- Recheck cleanup candidates immediately before destructive delete, including dirty files, unpushed commits, unknown upstream/base, folder repos, main worktrees, pinned workspaces, running terminals, disconnected SSH, and WSL paths.
-- Keep local, WSL, and SSH git providers at parity for timeouts, aborts, errors, and path handling.
-- On Windows-risky cleanup changes, validate a real Electron flow when feasible: progress appears before final completion, close/reopen recovers, a clean old worktree delete does not crash, and no orphan Electron/git process remains.
-
-Promotion rule:
-
-- A reliability fix cannot become a blocking gate if it makes the product slower or crashier. The promotion record must include the perf command or measurement, budget, result, platform/provider scope, and any accepted perf gap.
-
-### M. Make the Factory Enforce Those Gates
-
-The factory should turn the reliability gate into default behavior for planning, review, and merge-confidence testing. This should be treated as part of the prevention plan, not as a substitute for the actual test harnesses and CI gates above.
-
-Factory changes to carry forward:
-
-- `brennan-yolo-lite` should require a Reliability regression gate in the design doc whenever terminal, tab, session, provider, startup, upgrade, persistence, packaging, shell, path, or release behavior is touched.
-- The gate should force the agent to classify touched P0-capable surfaces: terminal lifecycle, tab creation/binding, dead-session reconciliation, hidden-to-visible resume, PTY identity/routing, PTY geometry including `0x0` quarantine, xterm addon boundaries, IME/paste/redraw behavior, local/daemon/SSH/remote/WSL/mobile provider contracts, attach/replay/resize/exit ordering, startup/upgrade persisted state, daemon survival, renderer/GPU crash containment, packaging/notarization, shell/PATH probing, terminal throughput, hidden-pane output, store subscriber hot paths, persistence payload size, git/worktree scan subprocess churn, cleanup modal progress, and Windows/WSL/SSH git crash risk.
-- Completeness verification should block when a touched P0-capable surface has no implemented or explicitly accepted reliability gate.
-- `review-code` should treat missing reliability tests or validation gates as findings for these surfaces, with the same review weight as lifecycle, provider, or cross-platform regressions.
-- `review-code` should invoke the `perf` skill for slow UI, terminal throughput, high CPU, memory/resource leaks, polling, subprocess churn, startup latency, render churn, or persistence writes.
-- `review-code` should invoke the `git-crash-perf` skill for worktree cleanup, git scans/status/listing, destructive removal, cleanup modal progress, SSH/WSL git providers, subprocess timeouts, or Windows git crash risk.
-- `brennan-test-changes` should run or explicitly justify the relevant terminal torture, provider contract, startup/upgrade, persisted-state, release, cross-platform, perf, or git crash/perf matrix subset.
-
-Current implementation status:
-
-- Internal factory skill update PR: https://github.com/stablyai/orca-internal/pull/491
-- Scope of that PR: add the reliability gate to `brennan-yolo-lite` and expand `review-code` to inspect the recent terminal/session/provider/startup/release failure classes.
-- Follow-up needed: once the concrete repo-side harnesses exist, update the skills again to name the exact commands and required CI jobs instead of only naming the expected reliability evidence.
-
-Additional factory follow-up:
-
-- `auto-design-review-fix`: treat missing reliability gates for P0-capable surfaces as design findings; require inverse invariants for cleanup/reconcile/init code.
-- `review-code-fix-loop`: require the final loop report to name the touched reliability classes, invariant, gate, and whether both reviewers addressed them. A clean review that never discusses the required reliability class should not count as clean.
-- `brennan-test-changes`: add merge-confidence sub-gates for stale snapshot/newborn binding races, hidden-to-visible resume, attach/replay/exit ordering, old-version persisted state, provider/platform matrices, and render-live/input-live checks.
-- `pr-review`: classify P0-capable surfaces before review/fix and require the same invariant/test/platform matrix before approval.
-- `yolo-lite` and `electron`: require terminal/runtime validation to prove input, scroll, focus, process output, and relevant platform behavior, not only screenshots or visible frames.
-- `playwright-reliability-tests`: add a focused skill for writing and reviewing Playwright tests that are evidence-based, low-flake, and tied to named invariants, so browser/Electron tests do not become more noisy checklist coverage.
-- `perf`: require measurement-backed review for terminal throughput, hidden pane output, store subscribers, persistence, startup, polling, subprocess churn, resource leaks, and memory growth.
-- `git-crash-perf`: require bounded subprocesses, progress streaming, close/reopen recovery, fresh delete preflight, provider parity, and Windows Electron validation for git cleanup/worktree changes.
-
-### N. Add Pane Lifecycle Telemetry and Diagnostics
-
-Each terminal pane should be able to emit a compact lifecycle trace:
-
-- pane id, tab id, worktree id
-- provider and connection id
-- pty id and binding epoch
-- visibility transitions
-- spawn/connect timestamps
-- resize measurements and forwarded sizes
-- liveness snapshot request/response times
-- teardown reason
-- hibernation/restore reason
-
-This will make future reports much easier to attribute without guessing. It should also be test-consumable: CI should be able to fail on forbidden transitions, stale close attempts, stuck `0x0`, missing input echo, and startup watchdog expiry.
-
-## Attribution Methodology
-
-"Who caused it?" is not reliably answerable from labels alone. This review separates:
-
-- **Confirmed**: the issue body or fix PR explicitly names the introducing PR/change.
-- **Likely**: the fix PR identifies the failing subsystem and local git history shows the regressing mechanism was introduced by a specific PR.
-- **Area ownership**: the same people are repeatedly fixing or modifying the subsystem, but there is not enough evidence to say they caused a given issue.
-- **Systemic**: no single introducer is evident; the problem is a missing invariant, provider contract, or test harness.
-
-## Attribution Findings
-
-### Confirmed Regression Chains
-
-- [#5356](https://github.com/stablyai/orca/issues/5356), session loss on first launch after upgrading from 1.4.65 to 1.4.68, explicitly names PRs [#5234](https://github.com/stablyai/orca/pull/5234) and [#5240](https://github.com/stablyai/orca/pull/5240). Local git history shows both PRs were authored by Jinwoo Hong. Count: Jinwoo 1 confirmed open `P0` regression chain.
-- [#5319](https://github.com/stablyai/orca/issues/5319), Linux/Wayland terminal input freeze, is closed, but the fixing PR [#6557](https://github.com/stablyai/orca/pull/6557) says the Wayland-aware GPU path had been removed in [#1344](https://github.com/stablyai/orca/pull/1344). Local git history shows #1344 was authored by Neil. Count: Neil 1 confirmed closed `P1` regression chain.
-
-### Likely Regression Chains
-
-- [#6773](https://github.com/stablyai/orca/issues/6773), new terminal/agent tabs opening and immediately closing, was fixed by [#6796](https://github.com/stablyai/orca/pull/6796) and [#6801](https://github.com/stablyai/orca/pull/6801). Those PRs identify the dead-session reconciler as the cause. Local git history shows [#6514](https://github.com/stablyai/orca/pull/6514), which introduced the focused dead-session reconcile module for hidden exited panes, was authored by Brennan Benson. Count: Brennan 1 likely open `P0` regression chain.
-
-### Area Ownership Without Clear Causation
-
-The recent terminal reliability churn is concentrated among Brennan, Neil, and Jinwoo because they authored many of the fixes and nearby changes. That does not mean each issue was caused by them. It does mean the riskiest ownership surfaces are:
-
-- Terminal lifecycle/reconcile/session persistence: Brennan, Neil, Jinwoo.
-- PTY size/layout/reflow: Neil, Jinjing, Jinwoo, Brennan.
-- Daemon/degraded spawn/focus/remote lifecycle: Neil, Jinwoo.
-- Windows terminal/shell/ConPTY/GPU recovery: Brennan, Neil, Jinwoo.
-- Agent status/sidebar/session identity: Brennan, Neil, Jinwoo, Jinjing.
-
-### Current Conservative Count
-
-For currently open `P0`/`P1` issues with a clear or likely PR-caused chain:
-
-- Jinwoo: 1 confirmed open `P0` regression chain.
-- Brennan: 1 likely open `P0` regression chain.
-- Neil: 0 confirmed open `P0`/`P1` chains from the evidence pulled, plus 1 confirmed closed `P1` chain.
-
-Most open `P0`/`P1` issues do not identify an introducing PR. Treating those as individual blame would be misleading. The stronger conclusion is that Orca has systemic reliability gaps around terminal/session lifecycle, provider contracts, PTY sizing, and upgrade/startup flows.
-
-## Recommended Next Steps
-
-Implementation plan: [`docs/reference/reliability-gates-implementation-plan.md`](./reliability-gates-implementation-plan.md).
-
-1. Deduplicate and update `P0` issues #6873/#6874 and #6773 with the suspected fix status.
-2. Add narrow red/green gates for known escapes first: newborn liveness race, PTY `0x0`, xterm addon throw containment, old-version upgrade fixture, and Linux Wayland render-live/input-live smoke.
-3. Define test maturity levels, promotion records, numeric flake/demotion policy, and a reliability-gates manifest before making new reliability gates blocking.
-4. Build the fake/fault-injection provider contract kit, then run the same contract against local and daemon PTY before expanding to SSH, WSL, remote runtime, and mobile.
-5. Add upgrade/startup/release fixtures for pre-#5232 session data, stale daemon/helper paths, packaged app reveal/close, nested notarization, PATH probe timeout, and Windows terminal activation.
-6. Add the terminal lifecycle state machine design doc and implement it incrementally behind the known escaped-regression gates.
-7. Formalize the PTY size protocol and make `0x0` a quarantined/non-authoritative state for visible panes.
-8. Add the agent identity contract for pane reuse, worktree switch, sidebar/mobile rows, provider session ids, stale notifications, and ownership-safe provider session replay across active/inactive tabs, visible/hidden panes, repeated activation, and live/quit/worktree-sleep records.
-9. Add performance budgets and measurements to reliability gates that touch terminal throughput, hidden panes, store subscribers, persistence, startup, polling, subprocess churn, git/worktree scans, cleanup modals, SSH/WSL git providers, or Windows git crash risk.
-10. Gate terminal/session PRs behind the reliability checklist above, including perf and git crash/perf checks when those surfaces are touched.
-11. Keep the factory skill update as the enforcement layer, add the Playwright reliability-testing skill, and make `perf` plus `git-crash-perf` mandatory companion skills for relevant PRs; then revise companion skills once exact repo commands and CI job names exist.
-12. Add pane lifecycle traces so future issues can be attributed from evidence instead of archaeology.
diff --git a/docs/reference/ssh-gssapi-kerberos.md b/docs/reference/ssh-gssapi-kerberos.md
deleted file mode 100644
index e7594151667..00000000000
--- a/docs/reference/ssh-gssapi-kerberos.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Kerberos / GSSAPI SSH Authentication
-
-Orca's ssh2-based SSH stack cannot speak `gssapi-with-mic` — the ssh2 library
-has no GSSAPI userauth support, and adding it would mean forking ssh2's
-protocol layer plus shipping the `kerberos` native module (MIT krb5 / Heimdal /
-Windows SSPI) as a prebuilt Electron dependency on three platforms. Instead,
-hosts that need Kerberos ride the existing **system OpenSSH transport** — the
-same parallel transport already used for `ProxyCommand`/`ProxyJump` hosts —
-which delegates GSSAPI, ticket lookup (`kinit` cache, Windows domain logon),
-and credential delegation to the platform's own `ssh` binary on macOS, Linux,
-and Windows (Win32-OpenSSH uses SSPI).
-
-## Transport selection
-
-Two tiers, deliberately asymmetric because RHEL-family distros ship
-`GSSAPIAuthentication yes` in the global `/etc/ssh/ssh_config`, which makes
-`ssh -G` report GSSAPI enabled for *every* host:
-
-1. **Proactive** — a target with `gssapiAuthentication: true` (parsed from an
-   explicit `GSSAPIAuthentication yes` in the host's `~/.ssh/config` block, or
-   set on the target directly) tries the system-ssh probe first. If that fails
-   (e.g. no ticket), the connect falls through to the normal ssh2 key/agent
-   path where passphrase/password prompts remain available — OpenSSH semantics
-   allow other auth methods alongside GSSAPI.
-2. **Auth-failure fallback** — when ssh2 exhausts key/agent auth and the
-   `ssh -G`-resolved config enables GSSAPI (`isGssapiSystemSshFallbackCandidate`
-   in `ssh-connection-utils.ts`), the connection retries over system ssh
-   *before* prompting the user for credentials. Kerberos-only hosts on
-   distro-default configs connect this way; hosts where keys work never leave
-   the ssh2 path.
-
-Manual (non-ssh-config) targets flagged for GSSAPI get an explicit
-`-o GSSAPIAuthentication=yes` in `system-ssh-args.ts`; config-backed targets
-inherit the option from their own `Host` block since the system binary re-reads
-ssh_config.
-
-Both tiers work headless (`orca serve`): the system-ssh probe needs no
-credential callbacks, and GSSAPI itself is non-interactive once a ticket
-exists.
diff --git a/docs/reference/ssh-typing-latency-under-relay-load.md b/docs/reference/ssh-typing-latency-under-relay-load.md
deleted file mode 100644
index f7ae8e0b3a7..00000000000
--- a/docs/reference/ssh-typing-latency-under-relay-load.md
+++ /dev/null
@@ -1,115 +0,0 @@
-# SSH Typing Latency Under Relay Load
-
-Date: 2026-07-06
-
-## Symptom
-
-Typing in an SSH-host terminal can become extremely slow (hundreds of ms to
-seconds per echoed keystroke) while other SSH work is active — file previews,
-source-control refresh, search. A quiet SSH shell stays snappy, which made the
-reports look unreproducible.
-
-This is distinct from the local warm-switch lag documented in
-`terminal-switch-typing-lag-investigation.md` (daemon `listSessions()`
-snapshot cost — already fixed; `TerminalHost.listSessions()` is now
-metadata-only via `getAppliedSize()`).
-
-## Root Cause
-
-The relay and the Electron client share ONE ordered SSH channel for all
-JSON-RPC traffic: PTY input/output, file streams, git responses, search, port
-scans. Two mechanisms turned bulk traffic into typing latency:
-
-1. **Relay-side head-of-line blocking (primary).** The `fs.readFileStream`
-   pump (`src/relay/fs-handler-file-read.ts`) wrote every 256KB chunk (~340KB
-   framed) into the relay's stdout as fast as local disk reads completed,
-   ignoring the `write() === false` backpressure signal. A 10MB preview
-   enqueued ~13.6MB into the pipe at once; a `pty.data` echo emitted
-   mid-stream queued behind ALL of it. At 2MB/s WAN that is multiple seconds
-   of echo delay per open file. The reproduced measurement: 4,195,592 bytes
-   (the entire remaining 3MB test file, framed) queued ahead of one echo
-   frame.
-
-2. **Client-side O(n²) frame buffering (secondary).** `FrameDecoder.feed()`
-   in both `src/main/ssh/relay-protocol.ts` and `src/relay/protocol.ts` did
-   `Buffer.concat([buffered, chunk])` per data event, re-copying the whole
-   backlog for every ~32KB TCP chunk — ~2MB of memcpy per 340KB frame,
-   ~80MB per 10MB file — on the Electron main thread, delaying `pty:write`
-   IPC dispatch and echo delivery to the renderer.
-
-## Fix
-
-- **Bulk lane with sink backpressure** (`RelayDispatcher.notifyBulk`):
-  `fs.streamChunk` frames are serialized per client and each send waits for
-  the sink's `drain` when `write()` returns `false`. Interactive frames
-  (`pty.data`) still use plain `notify()` and are admitted immediately —
-  because the bulk lane keeps the outbound buffer at ~1 frame, an echo jumps
-  ahead of every not-yet-admitted chunk. Sinks (`relay.ts` stdout + Unix
-  socket clients) surface `write()`'s boolean and a one-shot
-  `waitWriteDrain`; every death path (EPIPE, stdin end, detach, dispose)
-  flushes parked waiters so a pump can never hang on a dead pipe.
-
-- **Credit-based flow control** (`fs.streamAck`): the client requests
-  streams with `flowControl: 'ack'` and acks each processed chunk; the relay
-  caps unacked chunks at `STREAM_ACK_WINDOW_CHUNKS = 4` (~1MB raw). This
-  bounds in-flight bulk bytes even past the relay's own pipe (sshd/TCP
-  buffers) and paces the relay's base64/JSON encode loop so incoming
-  keystroke frames get event-loop turns. A parked pump wakes on ack, cancel,
-  release, client detach, and a 1s staleness recheck.
-
-- **Cross-version compatibility**: old client + new relay → no
-  `flowControl` param → legacy unpaced pump (still drain-bounded, which is
-  transparent). New client + old relay → `fs.streamAck` is an unknown
-  notification and is silently ignored. `STREAM_CHUNK_SIZE` (256KB) is
-  intentionally unchanged — both sides bake it into chunk offset math, so
-  changing it would corrupt cross-version streams.
-
-- **FrameDecoder rewrite** (both mirrored protocol files): chunk-list
-  buffering; each frame is assembled exactly once (one copy) instead of
-  re-concatenating the backlog per feed.
-
-## What Stays Fast / Unchanged
-
-- Relay PTY output batching (interactive echo fast path in
-  `src/relay/pty-handler.ts`) is untouched.
-- No `listSessions()` / provider inventory was added anywhere near typing,
-  focus, switch, resume, resize, or render paths.
-- Remote file streaming correctness: per-chunk length checks, chunk-count and
-  byte-count invariants, cancel paths, and the 12MB round-trip integration
-  test all pass unchanged.
-
-## Regression Coverage
-
-- `src/relay/fs-stream-pty-echo-backpressure.integration.test.ts` — real
-  mux ↔ dispatcher ↔ FsHandler over a congestible in-memory pipe; asserts
-  deterministic BYTE bounds (not wall-clock): echo queues behind < 2 framed
-  chunks when congested (pre-fix: whole file), ack window caps in-flight
-  chunks, legacy no-ack clients still get complete streams.
-- `src/relay/fs-handler-stream.test.ts` — pump parks at the ack window,
-  resumes per ack, and releases its file handle when cancelled while parked.
-- `src/relay/dispatcher.test.ts` — notifyBulk semantics: drain gating,
-  per-client targeting, dispose releases parked senders, interactive
-  notify() not gated behind a stalled bulk lane.
-- `src/main/ssh/relay-protocol.test.ts` — decoder byte-at-a-time boundary
-  straddling, oversized-frame resync across odd chunk sizes, and a
-  no-`Buffer.concat`-during-feed guard that locks out the O(n²) shape.
-- `tests/e2e/ssh-docker-relay-perf.spec.ts` — new "busy relay" scenario:
-  types while two 8MB remote file-read loops and a git.status loop run;
-  budgets median < 500ms, worst < 2000ms. (On loopback Docker the pre-fix
-  HOL is only tens of ms — the in-process byte-bound test is the
-  authoritative red/green; the e2e guards the end-to-end wiring.)
-
-## Residual Gaps
-
-- **Large single-frame responses**: `git.*` responses (stdout capped at
-  `MAX_GIT_BUFFER` = 10MB → ~13MB framed) and other request/response results
-  are one atomic frame on the wire; a huge diff can still delay an echo by
-  its own transfer time. Fixing this requires response chunking (a protocol
-  change); bounded by the 16MB `MAX_MESSAGE_SIZE`.
-- **Outbound direction**: a large `fs.writeFile` request frame (client →
-  relay) can queue ahead of keystroke `pty.data` frames on `channel.stdin`.
-  Same shape, opposite direction, rarer trigger (saving a large remote file
-  while typing).
-- `pty.ackData` flow control for PTY output remains unenforced
-  (`src/relay/pty-handler.ts` — "not yet enforced"); PTY output floods are
-  already paced by the relay's 8ms batch/16KB slice scheduler.
diff --git a/docs/reference/telemetry-availability.md b/docs/reference/telemetry-availability.md
deleted file mode 100644
index e6d4924d699..00000000000
--- a/docs/reference/telemetry-availability.md
+++ /dev/null
@@ -1,393 +0,0 @@
-# Telemetry Availability
-
-Append-only reference for dashboard authors. Use this file to answer: "From what date is this event or property trustworthy enough to chart?"
-
-This file records operational availability. Event contracts still live in `src/shared/telemetry-events.ts`, and dashboard/query examples live with the dashboard work that introduced them.
-
-## How To Use
-
-- Prefer `dashboard_ready_at_utc` as the lower bound for saved PostHog retention, funnel, and cohort tiles.
-- If `dashboard_ready_at_utc` is `TBD`, do not save production cohort or retention tiles. QA/exploratory charts may proceed only after checking first-seen evidence, and their descriptions must say the boundary is not final.
-- Use the latest required first-valid timestamp when a dashboard depends on multiple signals. An earlier timestamp may prove one event exists while a join key or depth field is still absent, which silently biases cohorts.
-- Do not save a cohort chart from one isolated first-seen row.
-- Mention rollout boundaries in saved insight descriptions when querying across pre-rollout data.
-- Do not add these timestamps to telemetry payloads. They are repo-side interpretation metadata.
-
-## Boundary Fields
-
-| Field                    | Meaning                                                                                                                    |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| `code_merged_at_utc`     | When the implementation reached `main`. Useful for source history only.                                                    |
-| `first_released_at_utc`  | First release commit/build that contains the code. This is the earliest possible user exposure.                            |
-| `first_seen_at_utc`      | First observed PostHog row for the event/property. This proves at least one event flowed.                                  |
-| `dashboard_ready_at_utc` | Earliest lower bound for saved dashboards after all required signals have first-valid rows and pass any validation window. |
-
-First-valid means the released app version has been observed, the required event/property fields are populated, joins used by the dashboard are available, and any validation window listed in the rollout entry has passed.
-
-D1+/D3+/D7+ retention means the user fired `app_opened` at least once after 24/72/168 hours from cohort start, matching the existing dashboards' mature-denominator logic. Do not read D3/D7 as exactly-on-day returns, and do not include users whose cohort start is too recent to satisfy the relevant window.
-
-## Cross-Cutting Rules
-
-- `app_opened` is the return marker. It fires once per app session after telemetry consent/gating resolves.
-- `nth_repo_added = 0` means the user had no repos at emit time. It is not a missing-value sentinel.
-- Missing `nth_repo_added` means the classifier failed soft or the event predates the property. Do not bucket it with `0`.
-- Main injects `nth_repo_added` only into schemas that declare the field, and injects onboarding `cohort` only into schemas that declare `cohort`.
-- `onboarding_started { cohort: 'fresh_install' }` is the fresh-install anchor. `upgrade_backfill` rows should not be mixed into new-user onboarding funnels.
-- Classify a user's fresh-install onboarding cohort from the first `onboarding_started { cohort: 'fresh_install' }` and carry that forward. Existing-user classification can flip after live completion is persisted, so later event-level `cohort` values are not a replacement for the start anchor.
-- Numeric onboarding step values are rollout-specific. Prefer `value_kind` when the relevant event/property is available.
-- Current `onboarding_step_skipped` means an optional preference/setup step was skipped toward required project setup. It does not mean the user abandoned repo setup.
-- `source = 'unknown'` is not a real product surface. It means the caller omitted a source or the value failed schema validation.
-- `workspace_created` means create-worktree IPC succeeded. It is not a general "usable workspace exists" or "workspace revealed" marker.
-- `add_repo_setup_step_action` is a historical post-add choice-screen event. Current Add Project flows auto-open the default checkout or reveal the project row, so absence of this event after the default-checkout handoff rollout is expected and should not be read as setup abandonment.
-- `add_repo_existing_workspaces_detected` is a detection signal for migration opportunity, not proof that a user chose an existing workspace. Current Add Project flows may emit it before automatically opening the default checkout.
-- `add_repo_default_checkout_handoff.result = 'revealed_project'` means Orca could not confidently open the default checkout and instead revealed the newly added project row. It is the direct fallback metric for the 2026-06-03 Add Project handoff rollout.
-- `agent_started` means PTY spawn succeeded with agent telemetry attached. It is not first-repo activation and does not prove the user sent a prompt.
-- `agent_prompt_sent` means a live agent hook observed an explicit non-empty user prompt. It excludes hydrated/replayed status, agent auto-start, bare shells, draft prefill, and hookless sessions; missing rows mean no hook-confirmed interaction was observed, not proof the user never typed.
-- Workspace-outcome joins are native Electron coverage unless the query explicitly proves remote/web instrumentation. Remote runtime and web paths can bypass native repo/worktree telemetry, so do not interpret missing workspace outcome rows as product drop-off for SSH, remote, or web users.
-
-## Rollouts
-
-### 2026-05-08 - Repo Cohort Property
-
-Scope: `nth_repo_added` on repo/activation/retention events. Current schemas declare it on `app_opened`, `repo_added`, `add_repo_setup_step_action`, `add_repo_existing_workspaces_detected`, `add_repo_default_checkout_handoff`, `workspace_created`, `workspace_create_failed`, `setup_script_prompt_shown`, `setup_script_prompt_action`, `agent_started`, `agent_prompt_sent`, and `agent_error`. The original rollout covered `app_opened`, `repo_added`, `add_repo_setup_step_action`, `workspace_created`, `workspace_create_failed`, `agent_started`, and `agent_error`; later events have their own first-seen timestamps below.
-
-| Field                        | Value                                                                                                                                                                                    |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| PR                           | `#1591`                                                                                                                                                                                  |
-| Merge commit                 | `002e2acc38cad262d694049cc86c0962ffd381ce`                                                                                                                                               |
-| `code_merged_at_utc`         | `2026-05-08T17:50:44Z`                                                                                                                                                                   |
-| First release                | `v1.3.42-rc.1`                                                                                                                                                                           |
-| First release commit         | `b6dab85aaa0e9b600ec93846824ba815542a1e1e`                                                                                                                                               |
-| `first_released_at_utc`      | `2026-05-08T17:56:35Z`                                                                                                                                                                   |
-| Earliest `first_seen_at_utc` | `2026-05-08T18:40:00.354Z` on `app_opened`                                                                                                                                               |
-| `dashboard_ready_at_utc`     | Event-dependent. Use `2026-05-08T18:40:00.354Z` for general `app_opened` repo-count cuts; use `2026-05-08T20:01:06.364Z` or later for first-repo activation cuts requiring `repo_added`. |
-
-PostHog evidence checked at `2026-05-23T23:34:32Z`:
-
-| Event                                   | First seen with `nth_repo_added`           |
-| --------------------------------------- | ------------------------------------------ |
-| `app_opened`                            | `2026-05-08T18:40:00.354Z` (`1.3.42-rc.1`) |
-| `workspace_created`                     | `2026-05-08T19:15:06.913Z`                 |
-| `agent_started`                         | `2026-05-08T19:15:07.130Z`                 |
-| `agent_prompt_sent`                     | `TBD`                                      |
-| `repo_added`                            | `2026-05-08T20:01:06.364Z` (`1.3.42`)      |
-| `add_repo_setup_step_action`            | `2026-05-08T20:01:20.897Z`                 |
-| `workspace_create_failed`               | `2026-05-08T23:04:32.315Z`                 |
-| `agent_error`                           | `2026-05-13T14:13:16.096Z`                 |
-| `add_repo_existing_workspaces_detected` | `2026-05-20T05:33:20.160Z`                 |
-| `add_repo_default_checkout_handoff`     | `TBD`                                      |
-| `setup_script_prompt_shown`             | `2026-05-21T04:09:04.231Z`                 |
-| `setup_script_prompt_action`            | `2026-05-21T04:10:31.616Z`                 |
-
-Dashboard caveats:
-
-- Earlier rows do not have `nth_repo_added`; show them as pre-rollout or exclude them from repo-count cohorts.
-- A dashboard that depends on a specific event must use that event's first-seen timestamp, not the earliest `app_opened` timestamp.
-- `repo_added nth_repo_added = 1` is the first-repo activation marker.
-- `add_repo_setup_step_action` is only representative of the old post-add choice-screen funnel. After the 2026-06-03 default-checkout handoff change below, Add Project no longer shows that choice screen during the normal Git add/clone/create/onboarding paths.
-
-### 2026-05-09 - Onboarding Cohort Injection
-
-Scope: `cohort` on onboarding events. Current schemas declare it on `onboarding_started`, `onboarding_step_viewed`, `onboarding_step_completed`, `onboarding_step_skipped`, `onboarding_tour_outcome`, `onboarding_step4_path_clicked`, `onboarding_step4_path_failed`, `onboarding_task_sources_snapshot`, `onboarding_windows_terminal_snapshot`, `onboarding_completed`, `onboarding_dismissed`, `onboarding_agent_picked`, onboarding import/setup events, `onboarding_feature_setup_toggled`, `onboarding_feature_setup_run`, `onboarding_feature_setup_terminal_opened`, and `onboarding_feature_setup_terminal_interacted`. See `src/shared/telemetry-events.ts` for the exact current roster.
-
-The original `#1608` rollout covered `onboarding_started`, `onboarding_step_viewed`, `onboarding_step_completed`, `onboarding_step_skipped`, `onboarding_step4_path_clicked`, `onboarding_step4_path_failed`, `onboarding_completed`, `onboarding_dismissed`, `onboarding_agent_picked`, and onboarding import events. Later onboarding events joined the roster by declaring `cohort` in their schemas.
-
-| Field                        | Value                                                                                                                                                      |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| PR                           | `#1608`                                                                                                                                                    |
-| Merge commit                 | `318e2b4c2c501b50280dc9e5b11ed34bd899bdd9`                                                                                                                 |
-| `code_merged_at_utc`         | `2026-05-09T02:57:18Z`                                                                                                                                     |
-| First release                | `v1.3.44`                                                                                                                                                  |
-| First release commit         | `e602decf1d35dc54c84eea516fc2b9afdc065cce`                                                                                                                 |
-| `first_released_at_utc`      | `2026-05-09T08:05:39Z`                                                                                                                                     |
-| Earliest `first_seen_at_utc` | `2026-05-09T09:54:03.038Z` on `onboarding_started { cohort: 'fresh_install' }` (`1.3.45`)                                                                  |
-| `dashboard_ready_at_utc`     | `2026-05-09T09:54:03.038Z` for fresh-install onboarding-start cohorts; use later event-specific first-seen timestamps where a tile requires another event. |
-
-Later onboarding cohort events:
-
-| Event                                          | PR                                                   | First release                           | `first_seen_at_utc`                       |
-| ---------------------------------------------- | ---------------------------------------------------- | --------------------------------------- | ----------------------------------------- |
-| `onboarding_feature_setup_run`                 | `#1853` (`2e5ac1c8ebdc93f6281622d9e4ef60ab14c71096`) | `v1.4.2-rc.1` at `2026-05-14T22:23:46Z` | `2026-05-15T05:55:37.248Z` (`1.4.2-rc.4`) |
-| `onboarding_feature_setup_terminal_opened`     | `#1853` (`2e5ac1c8ebdc93f6281622d9e4ef60ab14c71096`) | `v1.4.2-rc.1` at `2026-05-14T22:23:46Z` | `2026-05-15T05:55:37.261Z` (`1.4.2-rc.4`) |
-| `onboarding_feature_setup_terminal_interacted` | `#1853` (`2e5ac1c8ebdc93f6281622d9e4ef60ab14c71096`) | `v1.4.2-rc.1` at `2026-05-14T22:23:46Z` | `2026-05-15T11:47:28.022Z` (`1.4.2-rc.6`) |
-| `onboarding_feature_setup_toggled`             | `#1853` (`2e5ac1c8ebdc93f6281622d9e4ef60ab14c71096`) | `v1.4.2-rc.1` at `2026-05-14T22:23:46Z` | `2026-05-17T03:03:54.535Z` (`1.4.3`)      |
-| `onboarding_task_sources_snapshot`             | `#2275` (`ececd27fd8203a7acb3e430fa016fb4653aaa93c`) | `v1.4.7-rc.1` at `2026-05-19T00:47:11Z` | `2026-05-19T04:18:23.872Z` (`1.4.7`)      |
-
-Dashboard caveats:
-
-- Use `onboarding_started { cohort: 'fresh_install' }` as the new-user denominator.
-- Keep the single observed `upgrade_backfill` rows out of fresh-install funnels.
-- `onboarding_step_completed` had semantic `value_kind` before the tour instrumentation, but `onboarding_step_viewed` and `onboarding_step_skipped` only became semantic-step-safe with the tour telemetry rollout below.
-- Later onboarding events joined the `cohort` roster by declaring `cohort` in their schema. Use event-specific first-seen timestamps for tiles that depend on those later events.
-- `onboarding_task_sources_snapshot` fires only when the integrations step exits through Continue or Skip to project setup. Viewing integrations and leaving does not emit the snapshot.
-- Old numeric step analysis must be scoped to the flow version being analyzed.
-
-### 2026-05-14 - Feature Wall Base Telemetry
-
-Scope: first feature-wall tour event family before the inline onboarding tour. This added base open/close and tile activity telemetry. Historical `feature_wall_closed` rows from this rollout have `dwell_ms`; the source/depth fields needed for tour cohort retention only arrive in the later tour telemetry rollout.
-
-| Field                    | Value                                                                                                            |
-| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| PR                       | `#1772`                                                                                                          |
-| Merge commit             | `fdf7d9e97a46f27b3667d9bae6c8aca5d11345d8`                                                                       |
-| `code_merged_at_utc`     | `2026-05-14T22:20:50Z`                                                                                           |
-| First release            | `v1.4.2-rc.1`                                                                                                    |
-| First release commit     | `c66e9801fe5f159cac23564ec7c028957973692a`                                                                       |
-| `first_released_at_utc`  | `2026-05-14T22:23:46Z`                                                                                           |
-| `first_seen_at_utc`      | `2026-05-15T06:15:30.263Z` on `feature_wall_opened { source: 'popup' }` (`1.4.2-rc.4`)                           |
-| `dashboard_ready_at_utc` | Event-dependent. Useful for base feature-wall usage after first-seen rows, not for inline-tour cohort retention. |
-
-PostHog evidence checked at `2026-05-23T23:34:32Z`:
-
-| Event/property                                    | `first_seen_at_utc`                       |
-| ------------------------------------------------- | ----------------------------------------- |
-| `feature_wall_opened { source: 'popup' }`         | `2026-05-15T06:15:30.263Z` (`1.4.2-rc.4`) |
-| `feature_wall_tile_focused`                       | `2026-05-15T06:15:31.073Z` (`1.4.2-rc.4`) |
-| `feature_wall_closed` with legacy `dwell_ms` only | `2026-05-15T06:18:22.677Z`                |
-| `feature_wall_tile_clicked`                       | `2026-05-17T04:35:04.142Z` (`1.4.3`)      |
-| `feature_wall_opened { source: 'help_menu' }`     | `2026-05-17T07:02:23.278Z` (`1.4.3`)      |
-
-Dashboard caveats:
-
-- Do not infer inline onboarding tour cohorts from this rollout.
-- Historical `feature_wall_closed` null `source`/depth fields are pre-rollout absence, not product behavior.
-
-### 2026-05-23 - Inline Tour Surface
-
-Scope: optional "Explore Orca" tour during onboarding and the Help menu entry point. This shipped the product surface, not the full retention cohort instrumentation. It also added `source = 'onboarding'` to the feature-wall open source enum and added feature-wall group/feature/docs click events with source.
-
-| Field                      | Value                                                                        |
-| -------------------------- | ---------------------------------------------------------------------------- |
-| PR                         | `#2652`                                                                      |
-| Merge commit               | `669ade23133b9905fff1b6ed22755ee2911ea517`                                   |
-| `code_merged_at_utc`       | `2026-05-23T19:21:14Z`                                                       |
-| First release              | `v1.4.23-rc.0`                                                               |
-| First release commit       | `1f1171e0dee5d0fbf969de56845882bf8deb9037`                                   |
-| `first_released_at_utc`    | `2026-05-23T20:14:38Z`                                                       |
-| First app version observed | `1.4.23-rc.0` at `2026-05-23T20:54:12.343Z`                                  |
-| `dashboard_ready_at_utc`   | `TBD`; do not use this surface-only rollout for tour cohort retention tiles. |
-
-Dashboard caveats:
-
-- `feature_wall_opened { source: 'onboarding' }` is a release-availability signal for the inline surface, not the canonical tour cohort assignment.
-- Use this boundary only for exploratory checks that do not require the new outcome/depth fields.
-- Tour cohorts are observational and self-selected. Do not use causal "lift" or "impact" language unless a separate experiment supports it.
-
-### 2026-05-23 - Onboarding Tour Retention Telemetry
-
-Scope: low-cardinality telemetry that makes inline-tour cohort retention dashboards possible.
-
-Current status: the inline first-run onboarding tour was later removed from active onboarding after PR #2734 moved these education/setup moments to contextual feature tours and the Getting started with Orca guide. The historical schemas still accept seven-step `tour`/`agent_setup` onboarding rows for compatibility, but current active onboarding should not emit new `onboarding_step_* { value_kind: 'tour' }` rows.
-
-Added/changed signals:
-
-- `onboarding_tour_outcome` with `outcome`, intro/tour duration fields, optional tour depth fields, `advanced_via`, and injected onboarding `cohort`.
-- `onboarding_step_viewed.value_kind` and `onboarding_step_skipped.value_kind`, including `value_kind = 'tour'`.
-- `feature_wall_closed` optional `source`, `exit_action`, `furthest_step`, `last_group_id`, and bounded visited/completed depth counts.
-- `feature_wall_opened { source: 'onboarding' }` through the inline tour surface.
-
-| Field                    | Value                                      |
-| ------------------------ | ------------------------------------------ |
-| PR                       | `#2713`                                    |
-| Branch commit            | `9115143927dce38547545a07e58b85d17796fd7a` |
-| Merge commit             | `b9c55bb07127f799528761ec31d7e2b7f8598c07` |
-| `code_merged_at_utc`     | `2026-05-23T21:15:11Z`                     |
-| First release            | `v1.4.23-rc.1`                             |
-| First release commit     | `c74765922e770c6540496735a5a2be838457256a` |
-| `first_released_at_utc`  | `2026-05-23T21:16:38Z`                     |
-| `first_seen_at_utc`      | `TBD`                                      |
-| `dashboard_ready_at_utc` | `TBD`                                      |
-
-Required readiness signals:
-
-| Signal                                                                                 | `first_seen_at_utc`                                                                  |
-| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `onboarding_tour_outcome` with valid `outcome` and joinable fresh-install start        | `TBD`                                                                                |
-| `onboarding_step_viewed { value_kind: 'tour' }`                                        | Historical only; no new active-onboarding rows after the PR #2734 education handoff. |
-| `feature_wall_closed` with non-null `source`, `exit_action`, and expected depth fields | `TBD`                                                                                |
-
-QA/opportunistic signals:
-
-| Signal                                           | `first_seen_at_utc`                                                       |
-| ------------------------------------------------ | ------------------------------------------------------------------------- |
-| `onboarding_step_skipped { value_kind: 'tour' }` | Historical only; do not gate dashboard readiness on natural skip traffic. |
-| `feature_wall_opened { source: 'onboarding' }`   | `TBD`; surface availability only.                                         |
-
-PostHog evidence checked at `2026-05-23T23:34:32Z`:
-
-- `1.4.23-rc.0` had app traffic from `2026-05-23T20:54:12.343Z` through `2026-05-23T22:59:47.599Z`.
-- No `1.4.23-rc.1` or `1.4.23-rc.2` app traffic was observed in the checked query window.
-- No rows were observed for `onboarding_tour_outcome`, `onboarding_step_viewed { value_kind: 'tour' }`, `onboarding_step_skipped { value_kind: 'tour' }`, `feature_wall_opened { source: 'onboarding' }`, or `feature_wall_closed` with the new source/depth fields.
-- No rows were observed for `feature_wall_group_selected`, `feature_wall_feature_selected`, or `feature_wall_docs_clicked` in the checked query window.
-
-Dashboard readiness rule:
-
-Set this rollout's `dashboard_ready_at_utc` to the latest first-valid timestamp across the required readiness signals, then use that as the lower bound. If a query uses a local variable, name it `tour_telemetry_ready_at_utc` and assign it to the same value. After first-seen rows exist, keep saved cohort tiles in QA/exploratory mode until there is at least a 24-hour validation window where reached-tour users reconcile to exactly one primary inline cohort and closed tour sessions include depth fields.
-
-Invalid before this rollout's `dashboard_ready_at_utc`:
-
-- Tour cohort onboarding completion/progress.
-- Corrected onboarding outcome split by tour cohort.
-- Tour depth before abandonment.
-- Skipped-tour later Help recovery.
-- D1/D3/D7 retention by tour cohort, until cohorts are also old enough for each maturity window.
-- Numeric-step max-progress charts unless segmented by rollout or app version.
-
-Primary cohort interpretation:
-
-- Historical denominator for inline completed/partial/skipped rates: `onboarding_step_viewed { value_kind: 'tour' }` after this rollout's `dashboard_ready_at_utc`. Do not use this as a current active-onboarding readiness signal after the PR #2734 education handoff.
-- `onboarding_tour_outcome.outcome = 'completed_inline'` means the user completed the inline tour during fresh onboarding.
-- `onboarding_tour_outcome.outcome = 'started_partial'` means the user started the inline tour but the fresh onboarding session resolved without inline completion.
-- `onboarding_tour_outcome.outcome = 'skipped_intro'` means the user reached the tour intro and skipped without starting the inline tour.
-- Users who started onboarding but never reached the tour intro are `pre_tour_abandoned`, not `unresolved_inline_outcome`.
-- Users who reached the tour intro but have no outcome event are `unresolved_inline_outcome`; monitor this as a telemetry QA gap.
-- Later Help menu tour usage is an overlay on the user's inline cohort. It does not replace the primary inline outcome.
-- `completed_inline` wins over earlier partial state if the user returns and completes during the fresh onboarding session.
-- `started_partial` resolves only after the user started the inline tour and the fresh onboarding session resolves without inline completion.
-- `skipped_intro` intentionally has no `tour_dwell_ms` or depth fields.
-
-Feature-wall close interpretation:
-
-- `feature_wall_closed.dwell_ms` is session-close dwell time.
-- `feature_wall_closed.source` is the entry point (`onboarding`, `help_menu`, `popup`, or `unknown`).
-- `exit_action = 'onboarding_continue'` means the inline onboarding tour ended through Continue to project setup.
-- `exit_action = 'done'` means a non-onboarding tour session ended through Done.
-- `exit_action = 'dismissed'` is the default close/unmount path.
-- Depth fields are per explicit tour session. Persisted completion state can affect UI progress but must not be interpreted as current-session depth.
-- Missing/null `feature_wall_closed.source` or depth fields mean the row predates the expanded schema, came from an older app version, or failed field coverage. Do not bucket null with `source = 'unknown'`; exclude it from source/depth cohort tiles or show it as a telemetry coverage gap.
-
-### 2026-06-02 - Active Onboarding Step Removal
-
-Scope: active first-run onboarding no longer emits the `agent_setup` or `tour` semantic steps. The removed "Set up Orca for agents" and "Explore Orca" education/setup moments are covered by PR #2734 through contextual feature tours and the Getting started with Orca guide.
-
-This is a product-flow and telemetry-interpretation boundary, not a new event rollout. Historical onboarding schemas still accept seven-step `agent_setup` and `tour` rows so old data remains queryable, but dashboard authors should not expect new active-onboarding rows for those semantic steps after this rollout.
-
-| Field                    | Value                                                                           |
-| ------------------------ | ------------------------------------------------------------------------------- |
-| PR                       | `#4445`                                                                         |
-| Merge commit             | `TBD`                                                                           |
-| `code_merged_at_utc`     | `TBD`                                                                           |
-| First release            | `TBD`                                                                           |
-| First release commit     | `TBD`                                                                           |
-| `first_released_at_utc`  | `TBD`                                                                           |
-| `first_seen_at_utc`      | N/A                                                                             |
-| `dashboard_ready_at_utc` | Event-dependent; use this as a cutoff only after the PR is merged and released. |
-
-Dashboard caveats:
-
-- Treat `onboarding_step_* { value_kind: 'agent_setup' }`, `onboarding_step_* { value_kind: 'tour' }`, and `onboarding_tour_outcome` as historical first-run onboarding signals after this rollout.
-- Do not use absence of new `agent_setup` or `tour` onboarding rows as a drop-off signal; those steps no longer exist in active onboarding.
-- Segment numeric onboarding step analysis across this boundary. The active final step changed from seven-step onboarding to the five-step active flow.
-- Continue using `contextual_tour_shown` and `contextual_tour_outcome` from PR #2734 for current feature-education exposure and outcome analysis.
-
-### 2026-06-03 - Final Code Onboarding Step Removal
-
-Scope: active first-run onboarding no longer emits the final code/project picker step. The notifications step is now the final step, and completing it opens the Add Project modal.
-
-This is a product-flow and telemetry-interpretation boundary, not a new event rollout. Historical onboarding schemas still accept five-step rows so old data remains queryable, but dashboard authors should not expect new active-onboarding rows for the removed final code/project picker step after this rollout.
-
-| Field                    | Value                                                                           |
-| ------------------------ | ------------------------------------------------------------------------------- |
-| PR                       | `#4524`                                                                         |
-| Merge commit             | `TBD`                                                                           |
-| `code_merged_at_utc`     | `TBD`                                                                           |
-| First release            | `TBD`                                                                           |
-| First release commit     | `TBD`                                                                           |
-| `first_released_at_utc`  | `TBD`                                                                           |
-| `first_seen_at_utc`      | N/A                                                                             |
-| `dashboard_ready_at_utc` | Event-dependent; use this as a cutoff only after the PR is merged and released. |
-
-Dashboard caveats:
-
-- Treat `onboarding_step_*` rows for the removed final code/project picker step as historical first-run onboarding signals after this rollout.
-- Segment numeric onboarding step analysis across this boundary. At this boundary, the active final step changed from the five-step active flow to `ONBOARDING_FINAL_STEP = 4`; later onboarding step rollouts may supersede that final-step value.
-- Do not use absence of new final code/project picker rows as a drop-off signal; that step no longer exists in active onboarding.
-
-### 2026-06-03 - Add Project Default Checkout Handoff
-
-Scope: Add Project handoff telemetry and interpretation change. The Git add/clone/create/onboarding flows no longer show the post-add setup-choice screen; they close the add modal and open the project/default checkout when available. If no default checkout is available, they reveal the project row instead.
-
-`repo_added` remains the add/import marker. `add_repo_existing_workspaces_detected` remains a low-cardinality detection event for pre-existing non-main workspaces on local folder, runtime server path, and SSH server path adds. `add_repo_default_checkout_handoff` is the direct rollout-health event for the automatic handoff decision.
-
-| Field                    | Value                                                                                 |
-| ------------------------ | ------------------------------------------------------------------------------------- |
-| PR                       | `#4530`                                                                               |
-| Merge commit             | `TBD`                                                                                 |
-| `code_merged_at_utc`     | `TBD`                                                                                 |
-| First release            | `TBD`                                                                                 |
-| First release commit     | `TBD`                                                                                 |
-| `first_released_at_utc`  | `TBD`                                                                                 |
-| `first_seen_at_utc`      | `TBD` on `add_repo_default_checkout_handoff`                                          |
-| `dashboard_ready_at_utc` | Use the first release boundary once known for charts that compare setup-choice usage. |
-
-Dashboard caveats:
-
-- Treat `add_repo_setup_step_action` rows after this rollout as historical compatibility or stale modal cleanup only, not the normal Add Project funnel.
-- Do not build current-flow conversion funnels that require `repo_added -> add_repo_setup_step_action`; the normal next step is an automatic workspace reveal/open, not a tracked user choice.
-- Use `add_repo_existing_workspaces_detected` to estimate how often added projects had non-main existing workspaces, but do not infer the user selected "use existing worktrees" because that choice no longer exists in the normal flow.
-- Use `add_repo_default_checkout_handoff` for the current handoff outcome. `result = 'opened_default_checkout'` is the expected path; `result = 'revealed_project'` is the graceful fallback. Break down fallback rows by `source` and `reason`.
-
-### 2026-06-10 - Repo Added Git-vs-Folder Signal
-
-Scope: `repo_added.is_git_repo` replaces the retired `onboarding_completed.is_git_repo` split for git-vs-folder analysis. Project selection moved out of onboarding in the 1.4.46 flow, so `onboarding_completed` now fires before any repo is chosen. After that boundary, the old `onboarding_completed.is_git_repo` value is not a valid git-vs-folder signal.
-
-`repo_added.is_git_repo` is sourced from git detection at the add point. It is optional so SSH/remote paths that genuinely cannot determine git-ness can omit the property instead of defaulting to `false`.
-
-| Field                    | Value                                                                                       |
-| ------------------------ | ------------------------------------------------------------------------------------------- |
-| PR                       | `#5121`                                                                                     |
-| Merge commit             | `TBD`                                                                                       |
-| `code_merged_at_utc`     | `TBD`                                                                                       |
-| First release            | `TBD`                                                                                       |
-| First release commit     | `TBD`                                                                                       |
-| `first_released_at_utc`  | `TBD`                                                                                       |
-| `first_seen_at_utc`      | `TBD` on `repo_added.is_git_repo`                                                           |
-| `dashboard_ready_at_utc` | `TBD`; use only after first-seen rows exist and field coverage has been checked in PostHog. |
-
-PostHog evidence checked at `2026-06-10T19:00:00Z`:
-
-- Dashboard tile "Fresh-install onboarding completion over time" (`JlIt5J1N`, insight id `9076383`, project `406068`) showed the git-repo share collapse to about 4% while plain-folder completions spiked to about 88% on 2026-06-05.
-- Raw `onboarding_completed.is_git_repo` counts by `app_version` showed a version cliff: versions through `1.4.45` were about 80% true, while `1.4.46`, `1.4.47`, and `1.4.48` had zero true rows in the sampled data.
-
-Dashboard caveats:
-
-- Treat `onboarding_completed.is_git_repo` as historical only after app version `1.4.45`.
-- Do not stitch historical `onboarding_completed.is_git_repo` and new `repo_added.is_git_repo` series without an explicit version boundary and label change; they are emitted at different funnel moments.
-- Repoint dashboard tile `JlIt5J1N` to use `repo_added.is_git_repo` once the new field is observed in release telemetry.
-- Omitted `repo_added.is_git_repo` means unknown/degraded detection, not plain folder. Only explicit `false` means plain folder.
-
-### 2026-06-16 - Windows Terminal Preferences Onboarding Step
-
-Scope: Windows first-run onboarding adds a terminal preferences step before notifications. The step lets users choose the default Windows terminal shell and right-click paste/menu behavior before their first project handoff.
-
-`onboarding_step_*` rows can now emit `value_kind = 'windows_terminal'` at step `4`. Notifications move to step `5`, so `ONBOARDING_FINAL_STEP = 5` for current active onboarding. Non-Windows clients skip the Windows terminal step but still persist through the skipped step so resumed onboarding lands on notifications. `onboarding_windows_terminal_snapshot` records the low-cardinality selected shell bucket, right-click behavior, exit action, duration, and advance method when the visible Windows terminal step exits.
-
-| Field                    | Value                                                                                  |
-| ------------------------ | -------------------------------------------------------------------------------------- |
-| PR                       | `#5488`                                                                                |
-| Merge commit             | `68abadba8198c627fb642c41e54937c04ccddfe8`                                             |
-| `code_merged_at_utc`     | `2026-06-16T21:07:26Z`                                                                 |
-| First release            | `TBD`                                                                                  |
-| First release commit     | `TBD`                                                                                  |
-| `first_released_at_utc`  | `TBD`                                                                                  |
-| `first_seen_at_utc`      | `TBD` on `onboarding_step_viewed { value_kind: 'windows_terminal' }` and `onboarding_windows_terminal_snapshot` |
-| `dashboard_ready_at_utc` | `TBD`; use only after first-seen rows exist and Windows/non-Windows split plus snapshot coverage are verified. |
-
-Dashboard caveats:
-
-- Segment numeric onboarding step analysis across this boundary. Step `4` is Windows terminal preferences in the current flow, but was notifications in the previous active flow.
-- Use `value_kind` rather than numeric `step` when comparing notifications or Windows terminal setup across releases.
-- Non-Windows users can have persisted `lastCompletedStep` values that include the skipped Windows step; do not treat that as evidence they viewed the Windows terminal page.
-- `onboarding_windows_terminal_snapshot.default_shell = 'other'` means Orca could not bucket the persisted setting. It is not a raw shell path and should be monitored as telemetry quality, not a product choice.
-
-## Updating This File
-
-When adding or changing telemetry that dashboard authors will depend on:
-
-1. Add or update one rollout entry in this file.
-2. Record PR, merge commit, first release, release commit, `first_released_at_utc`, `first_seen_at_utc`, and `dashboard_ready_at_utc`.
-3. Include the app version/build on first-seen rows when it is available.
-4. Add `PostHog evidence checked at ...` with the UTC query time.
-5. If dashboard readiness depends on multiple signals, add a required readiness signal table and set `dashboard_ready_at_utc` only after all of them are first-valid.
-6. Add dashboard caveats for pre-rollout rows, missing/null fields, and maturity windows.
-7. Keep product-specific facts here, not in agent instructions or telemetry payloads.
diff --git a/docs/reference/terminal-cold-park-reveal-cost.md b/docs/reference/terminal-cold-park-reveal-cost.md
deleted file mode 100644
index e4eecd7fb91..00000000000
--- a/docs/reference/terminal-cold-park-reveal-cost.md
+++ /dev/null
@@ -1,132 +0,0 @@
-# Cold-park reveal cost — measured
-
-Companion to [`terminal-hidden-view-parking.md`](./terminal-hidden-view-parking.md).
-Quantifies the reveal latency a user pays when returning to a terminal whose
-hidden view was cold-parked, so the keep-warm policy is tuned from data rather
-than guessed. Motivated by field reports that "terminal mounting is jumpy —
-switching to a worktree after a while takes ~1s".
-
-## How to reproduce
-
-```bash
-pnpm bench:cold-park-reveal -- --cycles=12                      # empty shell
-pnpm bench:cold-park-reveal -- --cycles=10 --scrollback-lines=5000
-pnpm bench:cold-park-reveal -- --cycles=10 --scrollback-lines=20000
-```
-
-The bench (`tools/benchmarks/terminal-cold-park-reveal-bench.mjs`) drives the
-real dev app over CDP. Each cycle times a **cold** reveal (tab confirmed parked
-via `window.__terminalParkingDebug.parkedTabIds()` before revealing) and a
-**warm** reveal (revealed inside the hot-retain window, confirmed not parked),
-so the cold−warm delta is the isolated cost of parking. It shrinks the 30s
-hysteresis with `ORCA_E2E_TERMINAL_PARKING_DELAY_MS` and roots userData under a
-short `~/.ocpb` path — the default `/var/folders` tmp path overruns the macOS
-104-char Unix-socket limit, the daemon fails to bind, and terminals fall back to
-non-snapshot PTYs that never park.
-
-Phases per reveal (ms from the switch-back click): `activationMs` (store active
-worktree flips), `ptyBindMs` (revealed pane has a bound pty — xterm remounted
-and attached), `paintSettleMs` (two RAFs after ptyBind).
-
-## Results (macOS, dev app, medians / p95)
-
-| Scrollback | warm paintSettle | cold paintSettle | **cold-park penalty** |
-| ---------- | ---------------- | ---------------- | --------------------- |
-| empty shell   | 104 ms | 264 / 298 ms | **+160 ms** |
-| 5 000 lines   | 131 ms | 318 / 423 ms | **+187 ms** |
-| 20 000 lines  | 102 ms | 266 / 286 ms | **+164 ms** |
-
-All cold samples confirmed parked (`parkedConfirmed = N/N`); all warm samples
-confirmed not parked.
-
-## Finding
-
-**The cold-park reveal penalty is ~160–190 ms and effectively flat across buffer
-size.** Growing scrollback 0 → 20 000 lines did not grow the penalty (the 20k
-run is within noise of empty). So the cost is **fixed remount overhead** — React
-subtree teardown/rebuild, fresh xterm construction, WebGL attach, fit, and the
-reattach reset — **not** daemon snapshot replay, which scales fine.
-
-Implications for tuning:
-
-- The lever is **how often a remount happens**, not how much is replayed.
-  Widening the keep-warm working set (worktree hot-retain limit is 4, tabs 12)
-  and never parking the last-active tab per worktree remove remounts entirely
-  for the common switch-away-and-back, which is worth more than shaving the
-  ~170 ms remount itself.
-- Pre-warming a predicted reveal (sidebar hover, jump-palette selection) hides
-  the fixed cost behind the navigation instead of eliminating it.
-- This synthetic terminal is a plain shell. A live agent TUI in the alternate
-  screen pays additional reattach-reset + mode-rehydrate work on reveal (see the
-  Grok-scrollback reattach path), so real-world cold reveals of a busy agent
-  pane can exceed these numbers — the ~170 ms here is a floor for the mount
-  overhead, not a ceiling for the full experience.
-
-## Is parking worth having? (benefit side)
-
-`tools/benchmarks/terminal-cold-park-resource-bench.mjs`
-(`pnpm bench:cold-park-resource`) A/Bs the `terminalHiddenViewParking` setting
-in one session: mount N worktree terminals, background all but one, then read
-resources with parking off vs on. Measured at 8 backgrounded worktrees
-(5 000-line scrollback each):
-
-| metric | parking off | parking on | released |
-| ------ | ----------- | ---------- | -------- |
-| mounted pane managers | 9 | 1 | **8** |
-| DOM nodes | 2 941 | 1 389 | **1 552** |
-| attached WebGL contexts | 1 | 1 | **0** |
-
-So parking's unique win is **releasing every hidden terminal's mounted view** —
-8 xterm instances + their DOM subtrees (~1 550 nodes) here. At xterm's default
-5 000-row scrollback, each terminal buffer alone is ≥ ~4–5 MB of typed-array
-cell data (12 bytes/cell × 80 cols × 5 000 rows), so the renderer-memory floor
-is on the order of **several MB per hidden terminal** — tens of MB across a
-many-worktree session, before DOM and addon overhead.
-
-Two honest caveats on the numbers:
-
-- The **WebGL-context budget is NOT parking's win.** Even with parking off, only
-  one context was attached across 9 mounted terminals — the separate
-  WebGL-suspend-on-hide path (`suspendRendering`) already releases hidden panes'
-  contexts. So the #6874 context-exhaustion protection stands with or without
-  parking; parking's benefit is renderer memory + DOM, not contexts.
-- The measured JS-heap delta was small (~1.7 MB) because detached xterm
-  typed-array buffers GC lazily and the first measurement ran before they were
-  reclaimed. The bench was upgraded to force multi-pass GC and read whole-app
-  process memory (`window.api.memory.getSnapshot`), but a machine under disk +
-  memory pressure could not complete the upgraded run (esbuild dev-service
-  crashes). Re-run the upgraded bench on a healthy machine to get the settled
-  whole-app memory figure; the pane-manager / DOM release above is the robust,
-  reproducible part.
-
-### Verdict
-
-Parking earns its keep for the **many-worktree power user** (the reporter's
-profile): it is the only mechanism that frees hidden terminals' view memory and
-DOM, which is the dominant renderer cost at scale. It does **not** provide the
-GPU-context protection (that is suspend-on-hide's job). The reveal price is a
-flat ~170 ms remount. Net: keep it, and tune the keep-warm caps so the common
-few-worktree rotation never pays the remount.
-
-### Tuning applied
-
-Because the reveal cost is a fixed remount, the levers are all about
-**frequency**, not replay size. Three changes to
-`terminal-hidden-view-parking.ts`:
-
-- **Worktree hot-retain limit 4 → 8.** Eight covers the ordinary working set;
-  at the ~4–5 MB renderer floor per hidden worktree that is ~16–20 MB worst
-  case to eliminate remounts for the common rotation. Beyond 8, parking still
-  reclaims for the heavy tail it was built for.
-- **Hot-retain TTL 5 min → 15 min** (worktree and tab). The cap, not the clock,
-  is the primary evictor now; 5 min was aggressive enough that a meeting-length
-  absence parked the whole warm set. The tab count cap stays 12 (already
-  generous).
-- **Last-active exemption.** The single most-recently-hidden worktree/tab is
-  never parked, regardless of TTL or cap, so returning to the view you just
-  left is always instant. Implemented in `selectIdsBeyondHotRetain`; it holds
-  one warm slot and counts against the cap.
-
-Not done (deliberately): pre-warm on predicted reveal — it hides the cost
-behind navigation rather than removing it and adds hover/prediction complexity;
-and the 30 s cold-park delay is unchanged (it is the quick-flip guard).
diff --git a/docs/reference/terminal-hidden-view-parking.md b/docs/reference/terminal-hidden-view-parking.md
deleted file mode 100644
index 55583ab5a79..00000000000
--- a/docs/reference/terminal-hidden-view-parking.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Terminal Hidden View Parking
-
-Status: Shipped — Phase 1 of the terminal model/view architecture, kill switch
-`terminalHiddenViewParking` (default on). See
-[`terminal-model-view-contract.md`](./terminal-model-view-contract.md) for the
-invariants this design extends and the full phase list.
-
-## Problem
-
-Hidden terminal panes keep a full renderer xterm instance alive (buffer,
-scrollback, DOM, addons). At many-worktree scale this is the dominant renderer
-memory cost, and it forces every hidden byte through renderer-side write/skip
-decisions. The main-process model (daemon + runtime headless emulators) already
-ingests every byte and can serve restorable snapshots, so the renderer view for
-a long-hidden pane is redundant state.
-
-A previous attempt shipped and was reverted the same day. The post-mortem
-finding: parking unmounted the pane component, which also tore down the
-renderer's PTY byte parsers — and those parsers are the only source of bell
-notifications, title-transition agent-complete notifications, and tab titles.
-A parked worktree whose agent finished would never notify. This design keeps
-those side effects alive while parked.
-
-## Design
-
-### Park policy (renderer)
-
-A pure policy module decides which hidden terminal tabs may park:
-
-- Cold-park hysteresis: a tab must be hidden for 30s before parking.
-- Hot-retain working set: recently visible worktrees/tabs are retained
-  (15 minutes; up to 8 worktrees / 12 tabs) so quick tab switches never pay a
-  re-hydrate. The single most-recently-hidden (last-active) worktree/tab is
-  exempt from both the retain TTL and the count cap, so switching back to the
-  view you just left is always instant regardless of how long you were away.
-  See `terminal-cold-park-reveal-cost.md` for the data behind these caps.
-- Eligibility excludes: visible panes, hidden-measuring startup probes,
-  activity-portal panes, tabs with pending startup commands or pending
-  activation spawns, floating-panel tabs, and any tab whose PTY is not
-  snapshot-backed (remote-runtime `remote:` PTYs and SSH PTYs are excluded).
-- Kill switch: `settings.terminalHiddenViewParking === false` disables parking
-  entirely.
-
-### Park mechanics
-
-Parking a tab unmounts its `TerminalPane` React subtree (the overlay layer
-renders null for parked tabs). This is the same teardown that tab-group moves
-already exercise: transports detach but the PTY session, daemon model, and tab
-state all survive. The xterm instance, its buffers, DOM, and WebGL/addon
-resources are released.
-
-### Parked watcher (the piece the reverted attempt lacked)
-
-While a tab is parked, a pane-less watcher
-(`parked-terminal-byte-watcher.ts`) keeps the pane's side effects alive. Its
-consumption mode is decided once at watcher start:
-
-- **Main side-effect authority on (default):** the watcher is purely
-  fact-driven — it registers exactly one `pty:sideEffect` fact consumer and
-  parses no bytes. Titles, agent working/idle/exited transitions, BEL
-  attention, and PR links arrive as main-tracker facts and drive the same
-  policy callbacks a mounted pane uses. With the hidden-delivery gate also on,
-  the watcher marks the PTY hidden so main stops renderer byte delivery
-  entirely; the DECSET 2031 color-scheme subscribe arrives as main's
-  `2031-subscribe` fact and the watcher replies out-of-band via
-  `transport.sendInput`.
-- **Kill switch off:** the watcher subscribes to raw bytes through the
-  dispatcher sidecar mechanism (the same mechanism background agent launches
-  use) and runs the transport-level byte parsers with no xterm — OSC 0/1/2
-  titles (all-titles ordering, live-path normalization), the title-transition
-  agent tracker (completion notification, prompt-cache timer), the OSC-aware
-  stateful BEL detector, the GitHub PR link scan, and a dedicated DECSET 2031
-  byte responder (`parked-terminal-mode2031-responder.ts`, whose
-  `subscribeToPtyData` registration doubles as the delivery-interest signal).
-
-The two modes drive one shared policy-callback block, so flipping the kill
-switch never changes notification semantics. Main's synthetic
-agent-title/permission frames feed the main tracker directly and arrive as
-facts; the legacy synthetic `pty:data` copy exists only in kill-switch-off
-mode.
-
-Out of scope while parked: OSC 52 clipboard writes. Terminal queries inside
-hidden-dropped chunks are answered by main's model responder
-([`terminal-query-authority.md`](./terminal-query-authority.md)); in
-kill-switch-off byte mode only the 2031 reply is answered and Command Code
-output is not scraped, matching the pre-gate status quo.
-
-### Reveal
-
-Revealing a parked tab remounts the pane subtree and rides the existing
-reattach path: fresh xterm via `openTerminal` (unicode provider activation
-before any write), daemon model snapshot > relay replay > cold restore
-precedence, replay-guarded so snapshot-embedded queries never answer, then
-`POST_REPLAY_REATTACH_RESET` hygiene, fit, and PTY resize. The watcher is
-disposed before the pane handlers re-register.
-
-## Invariants
-
-1. PTY reads never stop; parking only changes renderer-side view lifetime.
-2. Bell, agent-completion, title, and PR-link side effects keep working while
-   parked (watcher parity tests).
-3. Reveal shows model-correct output (visual gates: hidden TUI restore, long
-   table, rendering golden) and accepts input immediately.
-4. Sleep/wake, pane close, and PTY restart while parked must not leak watchers
-   or strand parked state.
-5. Memory: parked tabs hold no xterm buffers; renderer memory scales with
-   visible panes.
-
-## Relation to later phases (all shipped)
-
-Side-effect authority in main (Phase 3) replaced the watcher's byte parsing
-with the `pty:sideEffect` fact consumer; the hidden-delivery gate (Phase 4)
-stops hidden byte delivery in main, moving the parked 2031 reply from the
-byte sidecar to the `2031-subscribe` fact; the model query responder
-(Phase 5) answers queries in hidden-dropped chunks. The watcher's byte-parser
-mode survives only behind the kill switches. Parking still excludes
-remote-runtime and SSH PTYs (no local snapshot to restore from); the watcher
-would return as a byte parser only if remote-runtime tabs — whose bytes never
-transit local main — ever became parkable.
diff --git a/docs/reference/terminal-model-view-contract.md b/docs/reference/terminal-model-view-contract.md
deleted file mode 100644
index 79fb55575f3..00000000000
--- a/docs/reference/terminal-model-view-contract.md
+++ /dev/null
@@ -1,218 +0,0 @@
-# Terminal Model/View Contract
-
-## Goal
-
-Terminal output should have one authoritative model path and many disposable
-views. A renderer xterm is the fast interactive view, but it must not be the
-only place hidden, remote, mobile, SSH, or CLI-visible terminal state exists.
-
-This contract defines the boundary the shipped terminal stack implements — and
-that future terminal work must preserve — without changing the query-response
-behavior that real shells and TUIs depend on. See [Architecture
-Status](#architecture-status) for the shipped phases.
-
-## Terms
-
-- **PTY stream:** Ordered bytes read from a local PTY, daemon PTY, SSH relay PTY,
-  or remote runtime PTY.
-- **Terminal model:** Main/runtime-owned state derived from PTY bytes. Today this
-  is mostly the headless emulator plus retained read transcript state.
-- **Terminal view:** A renderer xterm, mobile subscriber, remote desktop
-  subscriber, or CLI read page consuming model state and live output.
-- **Snapshot:** A bounded model serialization that can restore a view without
-  replaying an unbounded byte log.
-- **Transcript:** The retained output contract for `orca terminal read`; it is
-  line/cursor oriented and distinct from a screen snapshot.
-
-## Non-Negotiable Invariants
-
-1. PTY reads do not stop to protect renderer performance. Backpressure may bound
-   delivery to views, but terminal state, notifications, titles, and agent
-   status keep advancing from the PTY stream.
-2. Active visible terminal input/output stays on the lowest-latency path. Bulk
-   hidden or background output must not delay keystroke-sized foreground redraws.
-3. Hidden views do not own unbounded output memory. Main's hidden-delivery
-   gate drops renderer-bound bytes for hidden-marked PTYs after model
-   ingestion and emits an out-of-band restore marker
-   (`pty:modelRestoreNeeded`) so the view restores from the model on reveal.
-   With the gate's kill switches off, hidden bytes ride a bounded renderer
-   queue whose overflow latches the same model restore.
-4. Returning to a hidden or slept terminal must show model-correct output. A
-   stale or replaced view may be cleared and replayed from a snapshot, but it
-   must not show a warning fallback when model recovery is available.
-5. Snapshots and live bytes have ordering metadata. A view restore must not
-   duplicate bytes already included in the snapshot or drop bytes that arrived
-   after it. Main buffer snapshots report the pending-delivery start sequence
-   (`pendingDeliveryStartSeq`) so the renderer reconciles live chunks racing a
-   restore without misreading foreign sequence domains as duplicates.
-6. Terminal query authority is singular and structural: the party that
-   writes a chunk into a live terminal answers its queries. Visible renderer
-   and remote views keep xterm authority. Chunks dropped by the
-   hidden-delivery gate are answered exactly once by the main model
-   responder, from runtime-emulator state plus renderer-pushed view
-   attributes. Replayed, seeded, or snapshot bytes are answered by no one.
-   The daemon emulator never answers. (Amended by Phase 5 — see
-   [`terminal-query-authority.md`](./terminal-query-authority.md).)
-7. The transcript contract stays separate from screen restore. `orca terminal
-   read` must preserve bounded previews, cursor pagination, partial-line rules,
-   truncation flags, and total counts even if view snapshots change shape.
-8. Local, daemon, SSH, remote runtime, mobile, and CLI paths must either satisfy
-   the same model/view contract or explicitly report that model recovery is
-   unavailable.
-
-## Current Owners
-
-| Responsibility | Current owner |
-| --- | --- |
-| PTY byte source and local/SSH delivery | `src/main/ipc/pty.ts` |
-| Hidden-delivery gate (hidden marks, delivery interest, drop accounting, restore markers) | `src/main/ipc/pty-hidden-delivery-gate.ts`, drop sites in `src/main/ipc/pty.ts` and `src/main/ssh/ssh-relay-session.ts` |
-| Side-effect parsing and the `pty:sideEffect` facts channel | `src/shared/terminal-output-side-effects.ts` driven from `OrcaRuntimeService.onPtyData`; renderer policy in `src/renderer/src/components/terminal-pane/terminal-side-effect-facts-handler.ts` |
-| Model query responder and view-attribute bridge | `src/main/runtime/terminal-model-query-authority.ts`, `src/main/daemon/terminal-view-attribute-responder.ts`, `src/main/runtime/terminal-view-attribute-store.ts` |
-| Hidden view parking policy and parked watcher | `src/renderer/src/components/terminal-pane/terminal-hidden-view-parking.ts`, `parked-terminal-byte-watcher.ts` |
-| Daemon PTY state and headless snapshots | `src/main/daemon/headless-emulator.ts` |
-| Runtime headless state, retained reads, mobile/session tabs | `src/main/runtime/orca-runtime.ts` |
-| Remote terminal subscribe/multiplex/ACK semantics | `src/main/runtime/rpc/methods/terminal.ts` |
-| Renderer xterm view and hidden restore behavior | `src/renderer/src/components/terminal-pane/pty-connection.ts` |
-| Remote desktop runtime xterm transport | `src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts` |
-
-## Snapshot Contract
-
-A model snapshot must include:
-
-- terminal dimensions used to produce the snapshot;
-- enough ANSI state to rehydrate xterm before snapshot content;
-- bounded screen and scrollback content;
-- title and cwd metadata when known;
-- source metadata that distinguishes headless/model snapshots from renderer
-  fallback snapshots;
-- monotonic ordering metadata for live-output reconciliation when available.
-
-A snapshot must not:
-
-- include unbounded transcript history;
-- answer terminal queries while replaying into the model;
-- overwrite newer live view output with older model output;
-- hide that recovery was unavailable for a PTY surface.
-
-## View Contract
-
-A renderer or remote view may:
-
-- write active visible output immediately;
-- budget visible inactive output;
-- stop receiving hidden output entirely while main's hidden-delivery gate owns
-  the bytes (model restore on reveal);
-- request fresh snapshots for restore, mobile subscription, or explicit remote
-  snapshot recovery.
-
-A view must:
-
-- keep live-output buffers bounded while a snapshot is in flight;
-- apply generation or sequence checks before replaying a snapshot;
-- refresh/repaint after replay when xterm/WebGL needs an explicit paint;
-- keep side effects such as title, bell, cwd, and agent status flowing from the
-  PTY/model path (the `pty:sideEffect` facts channel) even while renderer byte
-  delivery is budgeted, gated, or parked.
-
-## Transcript Contract
-
-The retained read transcript is not a screen dump. It must preserve:
-
-- uncursored bounded latest preview behavior;
-- cursor reads over completed retained lines;
-- `oldestCursor`, `nextCursor`, `latestCursor`, and `returnedLineCount`;
-- partial-line duplication rules;
-- `truncated`, `limited`, and total count metadata;
-- bounded memory for long partial lines and large output bursts.
-
-Snapshot optimizations must be tested against this transcript contract instead
-of assuming xterm scrollback serialization can replace it.
-
-## Required Contract Tests
-
-Before moving more runtime behavior behind the model/view boundary, add or
-extend tests that prove:
-
-- headless snapshots rehydrate rich alternate-screen TUI state;
-- the daemon emulator never answers DA, DSR, OSC 11, or theme-sensitive
-  queries (the `session.test.ts` pins are permanent);
-- the main runtime responder answers queries only from live chunks the
-  hidden-delivery gate dropped — never delivered, replayed, seeded, or
-  remote-subscribed chunks;
-- hidden renderer overflow restores from model state without duplicate live
-  output;
-- sleep/wake and worktree revisit restore from model-correct state;
-- SSH-backed PTYs follow the same snapshot and ordering semantics as local PTYs;
-- remote runtime multiplex output remains ACK bounded and can request recovery
-  snapshots;
-- mobile subscribers receive bounded snapshots without unbounded pending live
-  output;
-- retained terminal reads remain pageable and bounded after large output.
-
-Current coverage is spread across:
-
-- `src/main/daemon/headless-emulator.test.ts`
-- `src/main/daemon/session.test.ts`
-- `src/main/ipc/pty.test.ts` (hidden-gate drops, restore markers,
-  `pendingDeliveryStartSeq`)
-- `src/main/ipc/pty-hidden-delivery-gate.test.ts`
-- `src/main/runtime/mobile-subscribe-integration.test.ts`
-- `src/main/runtime/rpc/terminal-subscribe-buffer.test.ts`
-- `src/main/runtime/rpc/terminal-multiplex.test.ts`
-- `src/main/runtime/orca-runtime.test.ts`
-- `src/main/runtime/terminal-query-responder.test.ts`
-- `src/shared/terminal-output-side-effects.test.ts`
-- `src/renderer/src/components/terminal-pane/terminal-title-tracker-parity.test.ts`
-- `src/renderer/src/components/terminal-pane/terminal-side-effect-facts-handler.test.ts`
-- `src/renderer/src/components/terminal-pane/terminal-hidden-view-parking.test.ts`
-- `src/renderer/src/components/terminal-pane/parked-terminal-byte-watcher.test.ts`
-- `src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.test.ts`
-- `tests/e2e/terminal-hidden-tui-visual-restore.spec.ts`
-- `tests/e2e/terminal-hidden-view-parking.spec.ts`
-- `tests/e2e/terminal-parked-memory.spec.ts`
-- `tests/e2e/terminal-sleep-wake-restore.spec.ts`
-- `tests/e2e/terminal-output-scheduler.spec.ts`
-- `tests/e2e/artificial-opencode-terminal-load.spec.ts`
-
-## Architecture Status
-
-All six phases of the terminal model/view architecture are shipped; the kill
-switches noted in parentheses default on:
-
-1. **Hidden view parking** — "Park hidden terminal views behind a byte
-   watcher": hidden terminal tabs unmount their xterm after a cold-park
-   hysteresis; a pane-less watcher keeps bell/title/agent/PR side effects
-   alive while parked (`terminalHiddenViewParking`). See
-   [`terminal-hidden-view-parking.md`](./terminal-hidden-view-parking.md).
-2. **Parked memory benchmarks** — "Benchmark parked hidden terminal memory":
-   renderer heap and live-terminal counts gate parking in the perf suite
-   (`tests/e2e/terminal-parked-memory.spec.ts`).
-3. **Side-effect authority in main** — "Track terminal titles in main with
-   all-titles ordering", "Move terminal side-effect authority to a main facts
-   channel", "Complete terminal side-effect facts coverage", "Finish terminal
-   side-effect authority migration": every local/daemon/SSH PTY byte is
-   side-effect-parsed once in main and delivered as `pty:sideEffect` facts
-   (`terminalMainSideEffectAuthority`). See
-   [`terminal-side-effect-authority.md`](./terminal-side-effect-authority.md).
-4. **Hidden delivery gate** — "Gate PTY delivery to hidden terminal views":
-   main drops renderer-bound bytes for hidden-marked PTYs after model
-   ingestion; delivery-interest registrations exempt sidecar byte consumers,
-   out-of-band restore markers latch model restore, and
-   `pendingDeliveryStartSeq` reconciles live output racing a restore
-   (`terminalHiddenDeliveryGate`).
-5. **Model query authority** — "Answer hidden terminal queries from the
-   model", "Bridge renderer view attributes to the model responder", "Align
-   query authority contract and spawn-time ownership": hidden-dropped queries
-   are answered by the runtime emulator plus renderer-pushed view attributes,
-   and hidden-at-spawn PTYs are marked before byte one
-   (`terminalModelQueryAuthority`). See
-   [`terminal-query-authority.md`](./terminal-query-authority.md).
-6. **Skip grammar deletion** — "Delete the hidden renderer skip grammar": the
-   renderer's per-chunk hidden-skip eligibility grammar and the 10s codex
-   startup query window are deleted; the kill-switch-off fallback is the
-   bounded background queue with overflow-latched model restore.
-
-Treat every hidden/slept/revisited TUI glitch as a contract failure, not as a
-local repaint quirk. Renderer fallback paths retire only when their kill
-switches do, and only after the equivalent model path has platform and TUI
-golden coverage.
diff --git a/docs/reference/terminal-query-authority.md b/docs/reference/terminal-query-authority.md
deleted file mode 100644
index bb6b11fea8c..00000000000
--- a/docs/reference/terminal-query-authority.md
+++ /dev/null
@@ -1,347 +0,0 @@
-# Terminal Query Authority
-
-Status: Shipped — Phase 5 of the terminal model/view architecture, kill
-switch `terminalModelQueryAuthority` (default on). Builds on
-[`terminal-model-view-contract.md`](./terminal-model-view-contract.md) (this
-phase **amends invariant 6**),
-[`terminal-side-effect-authority.md`](./terminal-side-effect-authority.md)
-(Phase 3), and the Phase-4 hidden-delivery gate
-(`src/main/ipc/pty-hidden-delivery-gate.ts`).
-
-## Problem
-
-Phase 4 drops renderer-bound bytes for hidden-gated PTYs after model ingestion
-(`src/main/ipc/pty.ts:1426,1515`, `src/main/ssh/ssh-relay-session.ts:931`).
-Queries embedded in dropped bytes get no reply: DA1 (ConPTY 1.22+ blocks
-waiting for it — `terminal-conpty-device-attributes.ts:22`), CPR probes hang
-TUIs, OSC 10/11 leaves `claude /theme` blind while hidden. The pre-Phase-4
-hidden skip latch had the same hole (only mode 2031 and the 10s codex startup
-window answered), so this is not a regression — it is the long-standing gap
-this phase closes.
-
-Contract invariant 6 ("the model must never answer queries") was written
-against a real bug: the daemon emulator replying ahead of the renderer with
-default-xterm values (the OSC-11 default-black-background race,
-`headless-emulator.ts:86-97`, pinned by `session.test.ts:163-190`). The danger
-was never "the model answers" — it was **two answerers for the same bytes**,
-one of them with wrong values. Phase 5 keeps the singularity and fixes the
-values.
-
-## Decision: the delivery decision is the reply decision
-
-Main answers a query **iff main dropped the chunk that carried it**. The same
-per-chunk hidden-gate predicate (`shouldDropHiddenRendererPtyData`) that
-decides renderer delivery decides reply ownership, evaluated once,
-synchronously, at ingestion:
-
-- Visible/unmarked PTY → chunk delivered → renderer xterm auto-replies via
-  `Terminal.onData` → `transport.sendInput`, unchanged.
-- Hidden-marked, no delivery interest → chunk dropped → main answers from the
-  runtime headless emulator, via the provider input path (`provider.write`,
-  same path as `pty:write`; daemon shell-ready write gating and the SSH relay
-  write apply unchanged).
-- Replayed/seeded/snapshot bytes → answered by no one (replay guards on both
-  sides).
-
-This is structurally exactly-one-responder: a chunk is delivered or dropped,
-never both, and each side only answers bytes it actually parsed live. The
-mark/unmark ordering, unhide-before-restore, and restore-marker IPC all exist
-from Phase 4 and are reused, not duplicated.
-
-Rejected alternatives:
-
-- **Fact-based renderer replies per query class** (the mode-2031 pattern
-  generalized): needs a main-side detection grammar per query, a fact round
-  trip per reply, and the renderer cannot answer CPR/DECRPM anyway — the
-  emulator is the only state for a hidden pane. The 2031 fact stays because it
-  is subscription registration, not a state query.
-- **Emulator always answers**: re-creates the OSC-11 double-reply race for
-  visible panes. Never.
-
-## Mechanism: forwarded emulator onData, not a new grammar
-
-`HeadlessEmulator` has `onData` wiring behind a per-write capture flag.
-For static and model-state queries, xterm core **is** the query grammar: the
-runtime emulator runs the same xterm version with equivalent options as the
-renderer pane, so main's reply set equals the visible renderer's by
-construction — verified empirically against the bundled headless build:
-DA1/DA2, DSR 5n, CPR, DECRPM (including unknown-mode `0`), DECRQSS (including
-DECSCUSR from cursor options), XTVERSION, kitty `CSI ? u` all reply; XTWINOPS
-(`windowOptions` stays default-off) and XTGETTCAP stay silent, matching
-visible behavior today. The headless build has **no theme service**: OSC
-4/10/11/12 queries and DSR ?996n return nothing even with the `theme` option
-set, so the view-attribute class is answered by responder-registered parser
-handlers instead (below) — never by core defaults.
-
-Forwarding predicate, captured per chunk in `OrcaRuntimeService.onPtyData` and
-attached to the emulator `writeChain` link (the mark can flip between
-ingestion and an async write; the decision must not be re-read at reply time):
-
-1. gate enabled (`terminalMainSideEffectAuthority` and
-   `terminalHiddenDeliveryGate` both on) AND new kill switch
-   `terminalModelQueryAuthority !== false`;
-2. the chunk was hidden-dropped for this PTY (`shouldDropHiddenRendererPtyData`
-   — same module state, same tick as the drop sites);
-3. the write is live PTY data — never `seedHeadlessTerminal`,
-   `maybeHydrateHeadlessFromRenderer`, option pushes, or any snapshot replay
-   (main-side replay guard, mirror of the renderer's `replay-guard.ts`);
-4. no remote view subscriber is attached to the PTY (runtime terminal-RPC
-   subscriber records / `mobileSubscribers`): a mobile/web/remote-desktop
-   xterm receiving the multiplexed stream answers with view authority, exactly
-   like a visible local pane. Legacy JSON `terminal.subscribe` streams **do**
-   register as view subscribers and suppress, even when the consumer is a
-   read-only watcher — deliberately conservative, because the stream may feed
-   an older live xterm view and a withheld reply (the pre-Phase-5 status quo)
-   is strictly safer than a double reply. Consumers that never register a
-   stream (CLI `terminal.read`, automation observers) do not suppress — they
-   also do not answer; that bounded no-reply case matches today's behavior.
-
-Mobile streams preserve that singularity across snapshot startup and multiple
-views. The mobile WebView suppresses `onData` during snapshot replay, then
-enables replies at an explicit live-output boundary. Clearing the WebView drops
-that replay queue and resumes live reply authority immediately. If a live query
-arrived while the initial snapshot was being built and its output sequence is
-covered by that snapshot, runtime RPC re-emits only the bounded query sequence
-after the snapshot; ordinary covered output stays deduplicated. `terminal.send`
-accepts the resulting `inputKind: query-reply` only from the earliest active
-phone-fitted mobile subscriber while mobile owns the terminal driver. Earliest
-is determined by preserved `subscribedAt`, so a soft-leave resubscribe does not
-change reply ownership; passive desktop-mode watchers are excluded. Peer phones
-are rejected, the next subscriber is promoted on unsubscribe, and desktop
-parser and capability handlers stay silent until desktop retakes the driver.
-Mixed versions: hosts advertise `terminal.query-reply-input.v1`; a mobile
-client never forwards replies to a host that lacks it, because such hosts
-strip `inputKind` and would treat the bytes as floor-taking shell input.
-Residual: a desktop→mobile driver handoff has a bounded double-reply window
-until the async driver-change event reaches the desktop renderer's cached
-driver map (`isPtyLocked`).
-
-Everything the emulator emits outside a forwarding window is discarded, which
-also swallows unsolicited core emissions (e.g. native 997 color-scheme pushes
-triggered by option mutations).
-
-## Reply classes
-
-| Class                        | Queries                                                                                                                                     | Answer source                                                                                                                                                                                                                                    |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Static                       | DA1 `CSI c` (ConPTY override below), DA2, DSR 5n, XTVERSION, DECRQM unknown → `0`, kitty `CSI ? u`                                          | xterm core constants + kitty flag state                                                                                                                                                                                                          |
-| Model-state                  | CPR `6n`/`?6n`, DECRPM mode table (?1 ?6 ?7 ?25 mouse ?1004 ?1006 ?1016 ?1049 ?2004 ?2026, insert), DECRQSS DECSTBM/DECSCA/SGR, kitty flags | emulator buffer/mode state — for a hidden pane it is the only state, hence authoritative                                                                                                                                                         |
-| View-attribute               | OSC 4/10/11/12 `;?` queries, DSR ?996n                                                                                                      | responder parser handlers + renderer attribute push (below); **silent until first push**                                                                                                                                                         |
-| View-attribute (via options) | DECRQSS DECSCUSR, DECRQM 12                                                                                                                 | xterm core, from pushed `cursorStyle`/`cursorBlink` emulator options                                                                                                                                                                             |
-| Silent                       | XTWINOPS, XTGETTCAP, ?15n/?25n/?26n/?53n                                                                                                    | nobody, visible or hidden                                                                                                                                                                                                                        |
-| Mode 2031                    | DECSET 2031 subscribe                                                                                                                       | unchanged in Phase 5: main emits the `2031-subscribe` fact, the renderer replies (`handleHiddenMode2031SubscribeFact`, `pty-connection.ts`; parked watcher fact callback). Emulator-native 2031/997 output is suppressed by the forwarding guard |
-
-### View-attribute bridge
-
-Renderer→main push, `pty:terminalViewAttributes` — one global snapshot,
-not per-PTY: the composed terminal `ITheme` (from
-`applyTerminalAppearance`, `terminal-appearance.ts`),
-`terminalCursorStyle`, `terminalCursorBlink`, and the resolved color-scheme
-mode (`resolveTerminalColorSchemeMode` — the same source as the existing
-hidden 2031 reply). Pushed on renderer startup and on every theme/settings
-apply.
-
-Main consumes it two ways:
-
-- `cursorStyle`/`cursorBlink` are applied to every runtime emulator's options
-  inside the replay guard; xterm core then answers DECRQSS DECSCUSR and
-  DECRQM 12 with renderer-true values (verified working headless).
-- Palette and color-scheme replies come from responder-registered parser
-  handlers on the emulator (`registerOscHandler` 4/10/11/12,
-  `registerCsiHandler` for DSR ?996n), because the headless core cannot
-  answer them. The OSC handlers see SET payloads too, so runtime OSC
-  4/10/11/12 mutations (and 104/110/111/112 resets) from the byte stream are
-  tracked per PTY and layered over the pushed base palette — matching what
-  the renderer's theme service reports for a visible pane.
-
-Staleness rules: replies use the last push; a theme flip is stale for at most
-one IPC hop (subscribed TUIs are corrected by the 2031/997 flip push).
-**Before the first push main answers no view-attribute query** — a fabricated
-default would resurrect the default-black OSC-11 bug; silence is the
-documented hidden status quo.
-
-### Kitty keyboard flags
-
-`vtExtensions.kittyKeyboard: true` is enabled in `HeadlessEmulator`, matching
-`buildDefaultTerminalOptions` (`pane-terminal-options.ts:50`). Risk is low:
-for the write-only daemon use, keyboard state never alters serialization; the
-change only makes the emulator parse `CSI =/>/< u` pushes instead of ignoring
-them, and lets the responder answer `CSI ? u` with the flags the hidden app
-actually pushed. Snapshot parity: add `kittyKeyboardFlags` to `TerminalModes`
-for emulator re-seed parity only. `rehydrateSequences` must **not** push kitty
-flags into a renderer xterm — `POST_REPLAY_REATTACH_RESET`'s deliberate kitty
-reset (stale CSI-u Ctrl+C hazard, `terminal-replay-cursor-state.test.ts`)
-stays authoritative. Slice 3 wires the re-seed consumer: the daemon
-warm-reattach snapshot threads `modes.kittyKeyboardFlags` through the spawn
-result into `seedHeadlessTerminal`, which applies them to the fresh runtime
-emulator via its own `CSI = flags ; 1 u` parse (outside any forwarding
-window), so hidden `CSI ? u` reports the flags the hidden app actually
-pushed. Paths without a snapshot (cold restore spawns a fresh shell) answer
-`?0u`; protocol-conformant programs re-push.
-
-### ConPTY DA1 variant
-
-The provider kind is known main-side: mirror `isLocalNativeWindowsPty`
-(`windows-pty-compatibility.ts:59`) from the spawn record (local/daemon
-provider, `win32`, not WSL). For such PTYs register a CSI `c` override on the
-emulator parser (the main-side twin of
-`installConptyDeviceAttributesHandler`) replying `CSI ?61;4c`, still gated by
-the forwarding predicate. The override is installed at emulator creation and
-retrofitted when the spawn mark lands (daemon stream data can create the
-emulator before the awaited spawn response marks the PTY). ConPTY blocking on
-a missing DA1 is a spawn-time hazard; the hidden-at-spawn loss window is
-closed by the slice-3 `initiallyHidden` spawn flag (races section).
-
-## Suppression: when main never replies
-
-- Visible or unmarked PTY (chunk was delivered).
-- Renderer delivery interest registered (chunk was delivered to a sidecar).
-- Remote-runtime (`remote:`) PTYs — never markable
-  (`isHiddenDeliveryGateManagedPty`), bytes never transit local main.
-- Remote view subscriber attached (mobile/web/remote desktop owns replies).
-- Seed/hydration/snapshot writes into the emulator, and option pushes.
-- Kill switches off — no marks exist, and `terminalModelQueryAuthority` is an
-  independent off switch for the responder alone.
-- The **daemon** emulator: never, under any setting. The responder lives in
-  main's runtime only; `session.test.ts:163-190` stays pinned verbatim.
-
-## Transition races
-
-Worst cases, per direction:
-
-- **visible→hidden**: chunks delivered between the visibility flip and the
-  mark landing in main are hidden-skipped by the renderer write path without
-  query scanning. No reply, no duplicate — identical to the pre-Phase-4 hidden
-  skip behavior, bounded by one renderer→main IPC hop. After the mark lands,
-  main answers everything it drops.
-- **hidden→visible**: unmark consumes the drop latch and emits the restore
-  marker; the snapshot replay is replay-guarded, so queries main already
-  answered are never re-answered from the snapshot; post-unmark live chunks
-  are answered by xterm once (restore-queued live chunks reply late, not
-  twice).
-- **Split queries across the drop/deliver boundary**: neither parser saw the
-  whole sequence → no reply; the restore marker resets renderer cross-chunk
-  state and replay hygiene resets the parser. At-most-once holds.
-
-Safe-side rule per class: duplicates are structurally impossible (one decision
-point per chunk); where the race costs anything it costs a missing reply.
-That is acceptable for state queries (DSR/CPR/DECRPM — TUIs re-probe or
-tolerate silence, as they did for every hidden pane before this phase). The
-one blocking-on-no-reply sequence, ConPTY DA1, only fires at spawn. A visible
-pane answers it from the renderer xterm. A PTY spawned hidden previously had
-no answerer until the renderer's hidden mark landed in main (one IPC hop
-after spawn). Slice 3 closes that window with the `initiallyHidden`
-spawn-record flag: the renderer declares hidden-at-spawn on `pty:spawn`
-(never for remote-runtime transports), and main marks the PTY hidden before
-the first byte — pre-spawn for
-daemon-host sessions whose id is minted up front, immediately after
-`provider.spawn` resolves otherwise — so the gate and responder own queries
-from byte one. The pane's first visibility sync then re-marks or unmarks
-through the existing Phase-4 machinery (unmark emits the restore marker for
-any spawn-window drops).
-
-## Invariants
-
-1. Exactly one party may answer any query, chosen by the chunk's delivery
-   decision: delivered → the consuming live view's xterm; dropped → main's
-   model responder; replayed/seeded → no one. The decision is captured once,
-   synchronously, at ingestion.
-2. Main answers only from live PTY bytes parsed by the runtime emulator —
-   never from snapshot, seed, hydration, or option-push writes.
-3. View-attribute answers are renderer-true or absent: no reply is ever
-   fabricated from emulator defaults (the OSC-11 lesson).
-4. The daemon emulator stays write-only; daemon subprocess query writes stay
-   zero (`session.test.ts` pins are permanent).
-5. Reply parity is structural for static and model-state classes: same xterm
-   core, equivalent options, no hand-rolled grammar — the only overrides are
-   the documented ConPTY DA1 variant and the view-attribute parser handlers
-   the headless core cannot serve.
-6. Remote views keep view authority; main yields whenever a remote view
-   subscriber is attached. When multiple desktop/mobile views coexist, the
-   terminal driver and server-side mobile election keep one reply writer.
-
-**Contract amendment** — `terminal-model-view-contract.md` invariant 6 is
-replaced by:
-
-> 6. Terminal query authority is singular and structural: the party that
->    writes a chunk into a live terminal answers its queries. Visible renderer
->    and remote views keep xterm authority. Chunks dropped by the
->    hidden-delivery gate are answered exactly once by the main model
->    responder, from runtime-emulator state plus renderer-pushed view
->    attributes. Replayed, seeded, or snapshot bytes are answered by no one.
->    The daemon emulator never answers.
-
-The contract's test bullet "headless tracking does not answer DA, DSR, OSC 11,
-or theme-sensitive queries" splits into: daemon emulator never answers
-(unchanged pins) / runtime responder answers only hidden-dropped chunks. The
-side-effect authority matrix row "DECSET 2031 reply — query authority stays
-with the view (contract invariant 6)" gains a pointer here; its reply path is
-otherwise untouched in this phase.
-
-## Test strategy
-
-- Responder unit tests beside `orca-runtime.test.ts`: marked vs unmarked vs
-  interest-suppressed; each reply class; seed/hydrate silence; remote-
-  subscriber suppression; ConPTY DA1 variant; kill-switch off; mark flip
-  between ingestion and async emulator write (captured decision wins).
-- Parity harness: shared query byte fixtures through a renderer-configured
-  xterm (onData capture) and through the responder; assert byte-identical
-  replies for static + model-state classes, and for view-attribute classes
-  after an attribute push.
-- `session.test.ts:163-190`: assertions stay; the comment is updated to name
-  the main responder (not "the renderer") as the hidden answerer.
-- E2E: hidden `claude /theme` reports the configured theme; hidden TUI
-  blocked on CPR/DA unblocks while gated; reveal shows no stray reply
-  fragments (`?1;2c`, `rgb:` …) on the prompt; Windows ConPTY golden and
-  `terminal-hidden-view-parking.spec.ts` stay green.
-
-## Cut-offs (shipped as three stacked slices)
-
-1. **Responder core.** Emulator onData wiring + per-write capture + main
-   replay guard; kitty flag enable (+ `TerminalModes.kittyKeyboardFlags`);
-   static + model-state classes; ConPTY DA1 override; remote-subscriber
-   suppression; `terminalModelQueryAuthority` switch; unit + parity tests.
-   Main-only — no renderer change. Ships the DA1/CPR/DECRPM unblock.
-2. **View-attribute bridge.** `pty:terminalViewAttributes` push, cursor
-   option application under the guard, responder OSC/DSR parser handlers with
-   per-PTY palette-mutation tracking, silent-until-push rule, `/theme` e2e.
-3. **Contract alignment.** Invariant-6 amendment in the contract doc, test
-   bullet split, `session.test.ts` comment, side-effect matrix pointer, and
-   the Phase 6 prerequisites below recorded as accepted.
-
-## Phase 6 (delete skip grammar + startup window): prerequisites from this design
-
-Phase 6 is shipped: the renderer hidden-skip eligibility grammar and the 10s
-codex startup renderer-query window are deleted. Kill-switch-off hidden panes
-fall back to the pre-grammar path — hidden bytes ride the bounded background
-scheduler queue; overflow latches the model-snapshot restore — and never run
-a per-chunk content scan.
-
-Accepted and shipped in slice 3 (except where noted):
-
-- **Mark-before-first-byte** (shipped): panes spawned without a visible view
-  are hidden-marked at spawn via the `initiallyHidden` flag on `pty:spawn`
-  (spawn-record flag, not a renderer round trip) so startup queries —
-  including ConPTY's blocking DA1 — are main-owned from byte zero. Phase 6
-  removed the codex exclusion with the window: codex spawns are main-owned
-  from byte zero too, the responder answering their startup probes.
-- **Attributes before spawn** (shipped): the renderer pushes composed view
-  attributes once at app start (right after settings load, before terminal
-  reconnect/spawn), so spawn-time view-attribute queries no longer fall into
-  the silent-until-push rule. Per-pane appearance applies keep re-publishing
-  through the same deduped publisher.
-- **Daemon shell-ready write gating** (verified): responder replies through
-  `ptyController.write` → daemon `Session.write` are QUEUED pre-ready, never
-  dropped, and the queue flushes at the shell-ready marker or the 15s
-  `SHELL_READY_TIMEOUT_MS` bound (`session.ts`). The codex window was removed
-  with hosted ConPTY golden coverage, unit DA1 parity, and the kill switches
-  as the safety net; explicit spawn-time e2e on Windows daemon PTYs remains
-  worth adding.
-- With the skip grammar deleted, every chunk is either written to a live
-  xterm or dropped — the delivered-but-skipped no-reply gap disappears and
-  the only remaining loss window is the mark IPC race.
-- **2031 consolidation** (optional follow-up): move the subscription registry
-  into the responder (the headless core cannot serve 997 pushes any more than
-  it can ?996n) and push 997 flips from the attribute cache, retiring the
-  `2031-subscribe` fact reply, the parked responder, and the parked-tab
-  theme-flip gap.
diff --git a/docs/reference/terminal-session-lifecycle.md b/docs/reference/terminal-session-lifecycle.md
deleted file mode 100644
index 0b11fd15557..00000000000
--- a/docs/reference/terminal-session-lifecycle.md
+++ /dev/null
@@ -1,580 +0,0 @@
-# Terminal Session Ownership and Teardown
-
-**Status:** Incident fix and pane-authority transfer implemented
-**Date:** 2026-07-13
-**Incident:** [`../../pty-exhaustion-agent-session-leak.md`](../../pty-exhaustion-agent-session-leak.md)
-**Related contracts:** [`terminal-model-view-contract.md`](./terminal-model-view-contract.md),
-[`terminal-hidden-view-parking.md`](./terminal-hidden-view-parking.md)
-
-## Summary
-
-Terminal process lifetime must be owned by explicit product intent, never by
-whether a React view happens to be mounted.
-
-Orca currently preserves a PTY when a terminal view detaches, which is correct
-for view parking, tab moves, renderer reload, and warm reattach. It also relies
-on `TerminalPane` unmount to destroy a PTY after a tab is closed. Hidden-view
-parking invalidated that implicit invariant: a parked tab has no mounted pane,
-so closing it removes renderer state and observers without terminating the PTY.
-Agent resume records survive the same close and later interpret the missing pane
-as failed recovery, launching the deliberately closed session again.
-
-This design establishes one authoritative lifecycle contract:
-
-- **Close tab or pane:** permanently retire the surface, terminate every PTY it
-  owns, and revoke every resume record for its panes.
-- **Detach or park:** remove only the view connection; preserve the PTY and its
-  durable identity.
-- **Sleep:** intentionally checkpoint resumable agents, terminate the PTYs, and
-  preserve only the checkpoint needed for wake.
-- **Quit or reload:** follow the configured persistence policy; warm detach is
-  allowed, but it is not a tab close.
-
-The immediate implementation makes the existing terminal-tab state close the
-authoritative compatibility boundary for explicit retirement while adding an
-explicit natural-exit reason for callers that are only reconciling an already
-dead PTY. A follow-up separates the command and reducer APIs once all direct
-store callers have migrated.
-
-## Implementation status
-
-The incident patch ships the retirement planner, provider-aware close routing,
-unified-only retirement, parked watcher/candidate disposal, resume-authority
-revocation, explicit natural-exit handling, late-binding rejection, and direct
-background-launch ownership checks. It also adds exact pane retirement and a
-persisted physical-to-owner pane-key alias for detach, plus a live Electron
-parked-close gate. Focused tests cover local, SSH, split, parked, shared,
-paired-host, ordinary runtime, pane-transfer, and late-spawn paths.
-
-`orca terminal close --tab` extends that same ownership boundary to automation.
-With an attached renderer, main sends a request/reply close, the renderer runs
-the canonical retirement path, persists a fresh host-partitioned session, and
-forces the main store to disk before acknowledging success. Without a renderer,
-the runtime applies the equivalent immutable projection to the persisted
-aggregate tab, removes every split binding and resume record, safely selects a
-surviving browser/editor/terminal surface, stops exact live or durable SSH PTYs,
-and flushes before returning. The ordinary `terminal close` pane/session
-contract is unchanged.
-
-This durability boundary does not use replay fences or tombstones. Renderer
-session writes are ordered through the same IPC sender, and a pending debounced
-write rebuilds from the latest store state, so the forced fresh snapshot is not
-followed by a captured pre-close topology patch. Headless closes update the
-single main-owned session projection directly.
-
-Origin-aware defensive expiry remains a follow-up. Immediate deletion on
-explicit close fixes the incident without applying a wall-clock policy that
-could invalidate intentional long-lived `worktree-sleep` checkpoints.
-
-## Goals
-
-1. Closing a terminal tab submits retirement for all exclusively owned local,
-   daemon, WSL, SSH, or runtime PTYs, including every split pane, whether its
-   views are mounted or parked.
-2. Closing a terminal pane terminates only that pane's PTY; detaching a pane to
-   another tab preserves its PTY, hook identity, and resume authority under the
-   new owning pane.
-3. Closing a tab permanently removes its agent resume authority. App restart,
-   worktree activation, mobile wake, and periodic capture must not resurrect it.
-4. Parking, tab-group moves, renderer reload, and warm reattach keep their
-   existing process-preservation behavior.
-5. Remote-runtime and web-session surfaces are terminated by their owning host,
-   not by sending a host-scoped ID to the local PTY provider.
-6. Teardown is idempotent and safe under duplicate close requests, late PTY
-   exits, late agent-hook events, in-flight spawns, and provider disconnects.
-7. A future bookkeeping regression cannot grow without bound: unowned defensive
-   resume records have an origin-aware expiry, and provider-owned detached
-   sessions gain a bounded orphan policy in the daemon-lease phase.
-
-## Non-goals
-
-- Changing terminal output, snapshot, replay, query-response, or hidden-delivery
-  behavior.
-- Killing processes that deliberately daemonize away from a plain user
-  terminal's process group (nohup-style survivors remain user intent there).
-  For **agent sessions**, close/kill additionally terminates the snapshotted
-  descendant tree — including detached-pgid children the PTY's SIGHUP cannot
-  reach — via `pty-descendant-termination.ts` (bounded fresh snapshot with
-  same-turn coalescing, SIGTERM, grace window, then identity-safe SIGKILL).
-  Completed process tables are never reused as signal targets, and identity
-  checks use C-locale timestamps from the source scan. Later requests start a
-  fresh same-turn-coalesced successor inside their own deadline instead of
-  waiting behind older scans. A session is marked as terminating before capture
-  and keeps request ownership through natural exit, so reattach, duplicate kill,
-  and graceful-to-immediate upgrade cannot race the snapshot; descendant signals
-  still require the exact root session/handle to be live. Windows and SSH-hosted
-  PTYs keep the previous foreground-tree contract for now.
-- Changing agent-provider resume commands or permission flags.
-- Making a UI close wait for a remote process to exit before the tab disappears.
-- Replacing worktree sleep with tab close. Sleep remains resumable by design.
-- Claiming that a disconnected SSH relay process is already dead when main can
-  only tombstone its app-scoped ID. Durable relay-side kill-on-reconnect is a
-  follow-up.
-
-## Terminology
-
-- **Surface:** a terminal tab or a pane within a split terminal tab.
-- **View:** a renderer xterm or pane-less parked watcher observing a surface.
-- **Session:** the provider-owned PTY identified by a PTY ID.
-- **Resume authority:** a `sleepingAgentSessionsByPaneKey` record that permits
-  Orca to launch an agent-provider resume command.
-- **Retire:** permanently close a surface and revoke its process and resume
-  ownership.
-- **Detach:** disconnect a view while preserving the session for reattachment.
-
-## Open-source prior art
-
-The lifecycle distinction is established in mature terminal implementations:
-
-- VS Code's terminal instance disposal calls process-manager disposal, and the
-  process manager marks the process `KilledByUser` before shutdown. Its separate
-  `detachFromProcess` path deliberately clears the client reference without
-  shutting down the process. It also shuts down a process whose asynchronous
-  creation completes after the manager was disposed. See
-  [`terminalInstance.ts`](https://github.com/microsoft/vscode/blob/3f5c62a95ddb886424da463b41ac3ac5e45aa04f/src/vs/workbench/contrib/terminal/browser/terminalInstance.ts#L1287-L1325)
-  and
-  [`terminalProcessManager.ts`](https://github.com/microsoft/vscode/blob/3f5c62a95ddb886424da463b41ac3ac5e45aa04f/src/vs/workbench/contrib/terminal/browser/terminalProcessManager.ts#L207-L239).
-- tmux exposes the same contract as separate commands: `detach-client` removes
-  a client while leaving the session intact, whereas `kill-session` destroys
-  the session and its windows. See
-  [`tmux.1`](https://github.com/tmux/tmux/blob/42b3ea0d7411acb4cd0357a3c2829d986b455918/tmux.1#L1177-L1218).
-
-Orca needs the same semantic split, extended across local, WSL, SSH, persistent
-daemon, and remote-runtime ownership. The important precedent is the explicit
-intent boundary, not a particular framework or process API.
-
-## Non-negotiable invariants
-
-1. View lifetime and process lifetime are independent. Mount and unmount may
-   attach or detach observers; they do not decide whether a session should live.
-2. Every live PTY has an owning surface or an explicit bounded detached state.
-3. A user close is terminal: once accepted, no status event, session snapshot,
-   or runtime replay may recreate the closed surface or resume its agent.
-4. A tab's retirement candidates are the union of its live index, tab row,
-   persisted split layout, last-known relay ID, deferred SSH ID, and pending
-   reconnect ID. A candidate is killable only when no other live surface claims
-   it.
-5. Provider routing follows the execution owner:
-   - local/daemon/WSL and app-scoped SSH IDs use `pty.kill`;
-   - `remote:` runtime mirror IDs are never passed to the local PTY provider;
-   - paired web tabs are closed through the host session RPC.
-6. Teardown requests are idempotent. Repeated kill, exit-after-kill, and
-   close-after-exit must converge on the same empty state.
-7. Resume-record validity is origin-aware. Intentional `worktree-sleep` records
-   are not expired by agent-status freshness; unowned defensive `live` and
-   `quit` records use a documented decision-time horizon.
-8. Natural process exit and explicit user retirement are distinct intents.
-   Reconciliation after an exit must not silently adopt destructive user-close
-   semantics.
-
-## Lifecycle matrix
-
-| Intent                | View                                       | PTY                                | Resume record                                       | Persistent tab state |
-| --------------------- | ------------------------------------------ | ---------------------------------- | --------------------------------------------------- | -------------------- |
-| Switch tabs/worktrees | hidden or parked                           | keep                               | keep/update                                         | keep                 |
-| Move pane/tab group   | detach, then remount                       | keep                               | keep                                                | move                 |
-| Renderer reload       | detach                                     | keep when warm persistence applies | keep                                                | keep                 |
-| App quit              | detach or terminate per persistence policy | policy-dependent                   | capture live agents                                 | keep                 |
-| Sleep worktree        | unmount                                    | terminate                          | capture intentional sleep checkpoint                | keep identifiers     |
-| Close split pane      | destroy                                    | terminate that pane                | delete that pane record                             | remove pane          |
-| Close terminal tab    | destroy or already absent                  | terminate all tab PTYs             | delete all tab records                              | remove tab           |
-| Remove worktree       | destroy                                    | terminate all worktree PTYs        | delete all worktree records                         | remove worktree      |
-| PTY exits naturally   | disconnect                                 | already dead                       | clear or retain completed evidence per agent policy | reconcile surface    |
-
-## Current failure
-
-The current close path deletes `ptyIdsByTabId[tabId]` and the tab layout, then
-relies on a mounted `TerminalPane` cleanup to call `transport.destroy()`. A
-parked tab has already run the detach branch and has no mounted cleanup left.
-`disposeParkedTabWatchers` only unregisters observers. The provider session is
-therefore alive after Orca discards its last renderer-side owner.
-
-The same state close drops live agent status but not
-`sleepingAgentSessionsByPaneKey`. Worktree activation intentionally fresh-resumes
-records that no preserved pane can own. A deliberately closed pane therefore
-looks like a failed restore. The existing age check compares `capturedAt` with
-`updatedAt`; that detects a status that was stale at capture time but never
-expires a record as wall time advances.
-
-## Proposed architecture
-
-### 1. Authoritative tab retirement plan
-
-Before deleting any tab-scoped state, build a `TerminalTabRetirementPlan` from
-one store snapshot:
-
-```ts
-type TerminalTabRetirementPlan = {
-  tabId: string
-  worktreeId: string | null
-  ptyIds: string[]
-  localOrSshPtyIds: string[]
-  runtimeTerminals: Array<{ environmentId: string; handle: string }>
-  sharedPtyIds: string[]
-  paneKeys: string[]
-}
-```
-
-`ptyIds` is the deduplicated union of:
-
-- `ptyIdsByTabId[tabId]`;
-- the tab row's legacy `ptyId`;
-- every value in `terminalLayoutsByTabId[tabId].ptyIdsByLeafId`;
-- `lastKnownRelayPtyIdByTabId[tabId]`;
-- `deferredSshSessionIdsByTabId[tabId]`;
-- `pendingReconnectPtyIdByTabId[tabId]`.
-
-This snapshot must be built before any of those maps are pruned. PTY IDs are
-classified structurally with `parseRemoteRuntimePtyId`, not by assuming a host
-or platform from the current active workspace. Before shutdown, the planner
-subtracts IDs referenced by another tab row, live index, split layout, or relay
-and reconnect map. A partially completed pane move must not let closing the
-source tab kill the target tab's session.
-
-The immediate compatibility boundary is `closeTab`, because several production
-paths still call the store action directly. Its options carry an explicit
-`reason: 'user' | 'pty-exit' | 'cleanup'`; `user` and `cleanup` retire, while
-`pty-exit` reconciles an already-dead session without killing siblings or
-revoking crash-recovery policy by accident. Making only the rendered tab-bar
-action destructive would leave background launch cleanup, floating terminal,
-onboarding, runtime notifications, and future direct callers vulnerable.
-
-### 2. Teardown ordering
-
-A local tab retirement executes in this order:
-
-1. Snapshot the retirement plan and its execution-owner classifications.
-2. Mark the tab recently closed so late agent-hook events cannot reintroduce
-   status or resume authority.
-3. Dispose the whole tab's parked registry entry and captured candidates, and
-   silence teardown side-effect handlers while preserving deterministic exit
-   observation.
-4. Submit `pty.kill` for exclusive local or SSH IDs and `terminal.close` for
-   exclusive ordinary runtime handles. A paired host-session close remains
-   owned by `session.tabs.close` and is not duplicated locally.
-5. Atomically remove the tab, layout/binding maps, agent status, and resume
-   records from renderer state.
-6. Let subsequent React unmount cleanup run idempotently. It is no longer the
-   process-lifetime authority.
-
-Steps 3 and 4 are issued before the state loses its IDs. The UI state mutation
-remains synchronous and does not await provider exit. Completion is observed
-with `Promise.allSettled` so rejections cannot become unhandled promises. The
-current Phase 1 fallback for a rejected retirement is provider `listSessions`
-plus Resource Manager orphan cleanup; durable retry inventory belongs to the
-main-owned retirement phase.
-
-Remote-runtime mirrors are different: their `remote:` IDs are excluded from
-local `pty.kill`. Ordinary runtime terminals retire through `terminal.close`.
-Paired host-session tabs retire through `session.tabs.close`, which owns the
-entire host tab graph. The local mirror may be pruned optimistically only after
-the host close intent is recorded, as it is today.
-
-### 3. Resume-authority revocation
-
-Tab retirement removes every sleeping record whose:
-
-- map key begins with `${tabId}:`; or
-- record has `tabId === tabId`.
-
-The explicit `record.tabId` check covers migrated or legacy keys whose key no
-longer encodes the current tab identity. Sibling tabs and other worktrees retain
-their records by reference when unchanged.
-
-The existing recently-closed tab registry remains the short-lived race guard
-for hook events already in flight. It must prevent those events from creating a
-new `origin: 'live'` resume record after retirement. Tests must cover both event
-orders: close then late status, and status queued in the same turn as close.
-
-Periodic capture iterates only current live status entries. Once close removes
-the live entry and resume record, the periodic pass has nothing to persist.
-
-### 4. Origin-aware defensive record expiry
-
-An unowned defensive `live` or `quit` record may expire when:
-
-```ts
-Date.now() - record.capturedAt > DEFENSIVE_AGENT_RESUME_MAX_AGE_MS
-```
-
-Intentional `worktree-sleep` records are exempt from the agent-status freshness
-window. Originless legacy behavior remains unchanged until its migration policy
-is explicitly chosen. The same validator must run before desktop activation and
-mobile/background wake so one entry point cannot bypass it.
-
-Expiry is defense in depth, not the primary close mechanism. A correctly closed
-record is deleted immediately; it is not retained for 30 minutes.
-
-### 5. Pane close remains pane-scoped
-
-`PaneManager.closePane` already distinguishes `reason: 'close'` from
-`reason: 'detach'`. Preserve that distinction with explicit pane authority:
-
-- `close` must clear the exact pane's resume authority, add a pane-scoped late
-  event tombstone, and destroy the pane transport;
-- `detach` must atomically transfer or alias resume ownership because the agent
-  process retains its immutable source `ORCA_PANE_KEY`.
-
-The last-pane path routes to terminal-tab retirement so it receives the same
-parked, split, SSH, and resume cleanup behavior as a tab-bar close.
-
-### 6. Provider-side safety net
-
-Client correctness is necessary but not sufficient for a daemon deliberately
-designed to outlive renderer and app processes. Add a follow-up provider-owned
-orphan policy:
-
-- track attachments/ownership leases rather than treating `detach` as a no-op;
-- distinguish warm-reattach grace from ownerless retirement;
-- reap sessions that have no owner after a bounded grace period;
-- never idle-reap a session merely because it produces no output;
-- scope leases to native, WSL, SSH provider, relay connection, or runtime host;
-- expose orphan count and oldest orphan age in Resource Manager diagnostics.
-
-This hardening is not required to land the immediate close fix, because a lease
-protocol changes daemon compatibility and needs its own migration. It is the
-defense against a future client bookkeeping regression.
-
-## Provider behavior
-
-| Provider/session kind   | Close operation                     | Notes                                                                                          |
-| ----------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
-| Local native            | `pty.kill(id)`                      | Main routes to the owning local/daemon provider.                                               |
-| Persistent daemon       | `pty.kill(id)`                      | Explicit close overrides warm-reattach persistence.                                            |
-| Windows ConPTY          | `pty.kill(id)`                      | Provider shutdown owns Windows process-tree semantics.                                         |
-| WSL                     | `pty.kill(id)`                      | Route by PTY ownership; do not infer from path separators.                                     |
-| SSH                     | `pty.kill(appScopedId)`             | Main resolves the connection-specific SSH provider.                                            |
-| Disconnected SSH        | `pty.kill(appScopedId)`             | Tombstones locally and prevents fallback; relay-side death requires reconnect-aware follow-up. |
-| Ordinary remote runtime | host `terminal.close`               | Classify environment and handle from the `remote:` ID.                                         |
-| Paired web host tab     | host `session.tabs.close`           | Host owns the complete tab and pane graph.                                                     |
-| Web client local mirror | optimistic prune after close intent | Host snapshot confirms final removal.                                                          |
-
-## Failure and race handling
-
-### Duplicate close
-
-The first close snapshots and retires the tab. Later closes find no target and
-no-op. Provider shutdown is idempotent for an already exited session.
-
-### PTY exit races close
-
-Observers are unregistered before shutdown. If an exit event was already
-queued, the recently-closed tab guard and missing tab make it a no-op. It must
-not recreate a tab, completion row, resume record, or notification.
-
-### Spawn completes after close
-
-The transport already kills a PTY when its spawn resolves after `destroyed` is
-set, but the two direct background launchers do not use that transport. Each
-direct launcher must revalidate tab ownership immediately after `pty.spawn` or
-`terminal.create` resolves and before writing any binding, layout, eager buffer,
-subscription, or mount request. A retired local or SSH result is killed; a
-retired runtime result is closed through `terminal.close`.
-
-### Provider shutdown fails
-
-The tab remains closed; reappearing would violate user intent. Report the
-provider class through structured diagnostics and leave the session visible in
-provider inventory so existing Resource Manager orphan cleanup can retry. A
-durable pending-retirement inventory is a later main-process API and is not
-claimed by Phase 1. Do not restore resume authority after a failed terminal
-kill.
-
-### Remote host is unavailable
-
-Keep the local close intent until either a host snapshot confirms removal or the
-existing intent TTL expires. If it expires, the host remains authoritative and
-may republish the tab; log the failed close. Never pretend a local mirror prune
-terminated the host PTY.
-
-### App exits during close
-
-Submit shutdown IPC before discarding the only local PTY identifiers. The main
-process/provider owns completion after accepting the request. A future batched
-shutdown IPC may return per-ID acceptance, but UI close does not wait for it.
-
-## Implementation plan
-
-### Phase 1: correctness patch (implemented)
-
-1. Add a small store-independent terminal-tab retirement planner that collects
-   all six ID sources, classifies execution owners, and excludes IDs shared by
-   another live surface.
-2. Add an explicit close reason, update natural-exit callers, and make explicit
-   `closeTab` retirement dispose the whole parked-tab registry, submit local,
-   SSH, or runtime shutdown, atomically clear all reconnect maps, and remove
-   tab-owned resume records.
-3. Add post-await owner checks to both direct background launchers so a late
-   local, SSH, or runtime spawn is terminated before any renderer binding.
-4. Defer decision-time expiry until unowned defensive `live` or `quit` records
-   can be distinguished without changing intentional `worktree-sleep` or legacy
-   recovery behavior.
-5. Add focused planner, store, launcher-race, and resume-policy tests. Keep one
-   local Electron parked-close proof as an RC release gate.
-
-### Phase 2: remaining API cleanup
-
-1. Rename the state-only reducer primitive so `closeTab` cannot ambiguously mean
-   either UI cleanup or lifecycle teardown.
-2. Route all user and runtime close call sites through one domain command.
-3. Keep explicit `detach` and `sleep` APIs; do not encode them as close options.
-4. Add a development assertion when tab state is removed with provider PTY IDs
-   but no retirement plan.
-
-Exact pane retirement, persisted detach authority transfer, and unified-only
-terminal routing landed with Phase 1 because exact-head review found they were
-required to avoid introducing adjacent close regressions.
-
-### Phase 3: daemon ownership leases
-
-1. Define versioned attach/detach/retire lease messages.
-2. Preserve warm reattach across renderer/app restarts within a bounded grace.
-3. Reap ownerless sessions and expose pressure telemetry.
-4. Add compatibility tests across the supported daemon protocol versions and
-   native/WSL/SSH host isolation.
-
-## Test plan
-
-### Unit/store tests
-
-- Closing an active single-pane tab submits exactly its PTY for shutdown and
-  removes all tab state.
-- Closing a parked tab with no mounted transport still submits its PTY.
-- Closing a split tab submits every unique PTY found across tab row, index, and
-  layout plus relay/deferred/reconnect maps, including IDs present in only one
-  source.
-- Duplicate IDs are submitted once by the authoritative retirement plan.
-- An ID referenced by another live tab is not killed when the source tab closes.
-- `remote:` IDs are excluded from local PTY shutdown.
-- App-scoped SSH IDs are included and are not mistaken for remote runtime IDs.
-- All sleeping records for the tab are removed by key prefix or `record.tabId`;
-  sibling records retain identity.
-- Periodic capture after close does not recreate the record.
-- Late agent status after close cannot recreate live status or resume authority.
-- Closing twice and close-after-exit are no-ops after the first retirement.
-- A spawn resolving after close kills the newly returned PTY.
-- A defensive live/quit record at the expiry boundary is retained; one
-  millisecond past it is cleared and never launched, while an older intentional
-  worktree-sleep record still resumes.
-
-### Renderer integration tests
-
-- Mounted tab close still destroys its xterm and terminates the PTY.
-- Parked watcher disposal occurs before or with PTY shutdown and emits no final
-  completion/bell notification.
-- Closing one split pane preserves the sibling; closing the last pane retires
-  the tab.
-- Pane-to-tab detach preserves the PTY and resume record.
-- Pinned-tab cancellation performs no shutdown; confirmed close does.
-- Bulk close (`close others`, `close right`, kill-all) uses the same semantics.
-
-### Provider/main tests
-
-- Local, daemon, WSL, ConPTY, and SSH ownership route explicit close to the
-  correct provider.
-- Disconnected SSH close tombstones the app-scoped ID and never falls through to
-  a local provider.
-- Repeated `pty.kill` for the same ID is benign.
-- Remote-runtime IDs cannot reach the local kill handler from renderer close.
-
-### Electron end-to-end regression
-
-1. Create a worktree terminal and start a deterministic long-lived child.
-2. Switch worktrees and wait until the source worktree is cold-parked.
-3. Close the parked tab.
-4. Assert its exact PTY disappears from `pty:listSessions` and the child exits.
-5. Restart/reload Orca and activate the worktree.
-6. Assert no terminal or agent resume command is recreated for the closed pane.
-7. Repeat with two split panes and with an SSH fixture where CI supports it.
-
-### Soak and pressure gate
-
-Run repeated create, park, close, reload, and reopen cycles. App-owned PTY count
-must return to baseline after each cycle and remain bounded over the run. Record
-the peak and final provider session count in CI artifacts.
-
-## Observability
-
-Emit a synchronous scheduled summary and an asynchronous completion summary:
-
-- tab/worktree identifiers in hashed or existing diagnostic form;
-- number of PTY IDs discovered by each source;
-- provider classification counts;
-- submitted count, then fulfilled/rejected counts after `Promise.allSettled`;
-- number of resume records removed;
-- whether the tab was parked or mounted when retired.
-
-After the daemon-lease phase, Resource Manager should distinguish:
-
-- attached sessions;
-- warm-detached sessions eligible for reattach;
-- ownerless/orphan sessions;
-- pending/failed explicit retirement.
-
-Alert locally before app-owned PTYs approach platform pressure. The warning is a
-defense, not a substitute for lifecycle correctness.
-
-## Rollout
-
-1. Land the correctness patch without a feature flag. User close semantics are
-   restorative behavior, not an experiment.
-2. Keep hidden-view parking enabled; disabling it masks the ownership bug and
-   forfeits its memory benefit.
-3. Run focused unit/integration tests plus the live parked-close Electron gate.
-4. Cut an RC and soak create/close/restart cycles while monitoring provider and
-   OS PTY counts.
-5. Ship daemon leases separately behind protocol compatibility and telemetry.
-
-## Alternatives rejected
-
-### Disable hidden-view parking
-
-This restores the old accidental unmount behavior at significant memory cost
-and leaves every other state-only close path fragile. It does not repair resume
-records or daemon ownership.
-
-### Kill only from `TerminalPane` cleanup
-
-There is intentionally no pane during parking and some headless/runtime flows.
-View cleanup cannot be process authority.
-
-### Clear only resume records
-
-This prevents resurrection but still leaks the live PTY until app/daemon exit.
-
-### Kill only the tab row's `ptyId`
-
-Split panes and partially reconciled layouts can own multiple IDs. The full
-union is required.
-
-### Rely only on a daemon idle timeout
-
-Interactive agents can be legitimately idle for hours. Reaping by output
-idleness loses user work; ownership, not activity, is the safe signal.
-
-### Await every provider exit before hiding the tab
-
-Remote and disconnected providers can take seconds or fail. UI retirement must
-be immediate once the user confirms; provider completion is asynchronous and
-observable.
-
-## Phase 1 acceptance criteria
-
-- A confirmed terminal-tab close submits retirement for every exclusively owned
-  session Orca can currently reach and reports rejected requests without an
-  unhandled promise.
-- A closed agent session is never resumed by restart, activation, or mobile wake.
-- Parking, move/detach, sleep/wake, and warm app reattach retain their documented
-  behavior.
-- Split, local, SSH, and remote-runtime ownership are covered by deterministic
-  tests; Windows/WSL process-tree behavior remains a live-platform follow-up.
-- PTY counts remain bounded across the soak scenario.
-- No process-lifetime decision depends on React component mount state.
-
-## Full-contract follow-ups
-
-- Durable main-owned retirement intent and bounded retry inventory.
-- Disconnected SSH relay kill-on-reconnect.
-- Serializable daemon attachment leases with protocol-version fallback.
-- Positive ownership validation for late hook events beyond the bounded recent-
-  close registry.
diff --git a/docs/reference/terminal-side-effect-authority.md b/docs/reference/terminal-side-effect-authority.md
deleted file mode 100644
index 852a607d5bf..00000000000
--- a/docs/reference/terminal-side-effect-authority.md
+++ /dev/null
@@ -1,252 +0,0 @@
-# Terminal Side-Effect Authority
-
-Status: Shipped — Phase 3 of the terminal model/view architecture, kill switch
-`terminalMainSideEffectAuthority` (default on). Builds on
-[`terminal-model-view-contract.md`](./terminal-model-view-contract.md) and
-[`terminal-hidden-view-parking.md`](./terminal-hidden-view-parking.md) (Phase 1).
-
-## Problem
-
-Main parses every local/daemon/SSH PTY byte before renderer delivery
-(`OrcaRuntimeService.onPtyData` in `src/main/runtime/orca-runtime.ts`:
-side-effect tracker, OSC 9999 agent status, headless emulator, tails, URL
-watchers; SSH feeds the same path from `wireUpPtyEvents` in
-`src/main/ssh/ssh-relay-session.ts`). Before this phase, the side effects
-users see — bell unread/notifications, title transitions, agent-complete
-notifications, command lifecycle, PR links — were derived a second time by
-renderer byte parsers. That duplication forced Phase 1's watcher to parse
-bytes, forced main to fabricate synthetic OSC title frames over `pty:data`
-just so renderer parsers could see them, and blocked Phase 4 from ever
-stopping hidden byte delivery. Phase 3 made main the side-effect parser for
-every PTY whose bytes transit local main; the renderer byte parsers
-(`createPtyOutputProcessor` in `pty-transport.ts`, the parked watcher's byte
-mode) survive only for remote-runtime PTYs and the kill-switch-off fallback.
-
-## Authority Matrix
-
-"Main" means parsed once in `onPtyData` and delivered as derived facts.
-Remote-runtime PTYs (`remote:`) never transit local main; the renderer
-(`remote-runtime-pty-transport.ts:74`) stays their parser permanently.
-
-| Side effect | local-daemon | SSH | remote-runtime |
-| --- | --- | --- | --- |
-| OSC 9999 agent status | main (parsed in `onPtyData`, emitted as `agentStatus:set`) | main | renderer (`shouldOwnAgentStatusInRenderer`, `pty-connection.ts`) |
-| OSC 0/1/2 titles + working/idle/exited tracker + 3s stale-title timer | main | main | renderer |
-| BEL attention (OSC-aware stateful detector) | main | main | renderer |
-| OSC 133;D command-finished exit code | main | main | renderer |
-| GitHub PR-link scan | main | main | renderer |
-| Command Code output scrape | main (per-PTY detector beside the tracker → `command-code-working`/`command-code-done` facts; the renderer pane keeps the done settle timer — it must consult the live status row) | main | renderer |
-| DECSET 2031 color-scheme reply | renderer view/watcher — the 2031 fact reply path is untouched by Phase 5; general query authority is now per-chunk structural ownership, see [`terminal-query-authority.md`](./terminal-query-authority.md) (contract invariant 6 as amended) | same | renderer |
-| DECSET 2004 paste readiness (`agent-paste-draft.ts`) | renderer — input pacing, not a model side effect | renderer | renderer |
-
-## Main-Side Tracker
-
-- The side-effect core shared with the renderer processor lives in
-  `src/shared/terminal-output-side-effects.ts`: all-titles ordering via
-  `extractAllOscTitles` (coalesced working→idle transitions are why last-title
-  is insufficient — issue #1083), `normalizeTerminalTitle`, the literal
-  `cursor agent` title drop (`CURSOR_NATIVE_TITLE_LOWER`,
-  `src/shared/agent-detection.ts`), the `createAgentStatusTracker`
-  transitions, the stale-working-title 3s timer
-  (`STALE_WORKING_TITLE_TIMEOUT_MS`), and the stateful BEL detector
-  (`src/shared/terminal-bell-detector.ts`).
-- One tracker per PTY on `OrcaRuntimeService`, lazily created like
-  `agentStatusOscProcessorsByPtyId`; disposed in `onPtyExit` (cancels the
-  stale-title timer).
-- It replaced the chunk-level last-title extraction in `onPtyData`: titles
-  feed in byte order, so `lastOscTitle`/`lastAgentStatus`, tui-idle waiters,
-  and pending-message delivery see intermediate transitions instead of only
-  the chunk's last title. PTY/leaf records keep the **raw** last title
-  (worktree `ps` and mobile tab titles expect raw); emitted facts carry
-  `(normalizedTitle, rawTitle)` like `onTitleChange`.
-- No deferred drain in main — the renderer's setTimeout(0) batching
-  (`sideEffectDrainTimer`, `pty-transport.ts`) protects xterm paint, which
-  does not exist in main. Main applies synchronously and batches the IPC per
-  flush.
-- The stats `AgentDetector` (`src/main/stats/agent-detector.ts`) keeps its own
-  last-title scan, untouched: synthetic titles must never reach it.
-
-## Event Transport: `pty:sideEffect`
-
-One batched main→renderer channel (`window.api.pty.onSideEffect`,
-`src/preload/index.ts`). It is **not** routed through the pty dispatcher:
-the renderer fact-consumer registry
-(`terminal-side-effect-facts-handler.ts`) subscribes directly via
-`window.api.pty.onSideEffect` — one channel subscription per renderer, with
-exactly one registered fact consumer per PTY. Events are **facts, not
-decisions**: `title`, `bell`, `agent-working`, `agent-idle` (with title),
-`agent-exited`, `command-finished` (exit code), `pr-link`. Each carries
-`ptyId`, main-known attribution (worktreeId/tabId/paneKey from runtime leaf
-records, same resolution as `emitTerminalAgentStatusEvents`), and the PTY
-`outputSequence`.
-
-Ordering rules:
-
-1. Per-PTY in-order; facts from one chunk are emitted in byte order (status
-   payloads, then titles in sequence, then bell — the renderer drain's order).
-2. Deliberately **not** synchronized with `pty:data`: side effects must keep
-   advancing while renderer delivery is ACK-gated (contract invariant 1). A
-   completion title may reach the store before the visible xterm paints the
-   final output; that is acceptable — attention/title state is out-of-band UI
-   state, and today's renderer drain already decouples by many batches under
-   timer throttling.
-3. No attention replay: facts emitted while no renderer is subscribed are
-   dropped. On transport attach/park-handoff the renderer pulls a title-only
-   snapshot (`pty:sideEffectSnapshot`) marked `replay: true` — this reproduces
-   the eager-buffer behavior where replay restores titles but is barred from
-   bells/completions (`suppressAttentionEvents`, `pty-transport.ts`). The
-   store handler ignores a replay title older (by `outputSequence`) than the
-   last live title fact it applied.
-
-## Renderer Store Handler (policy stays in the renderer)
-
-Notification semantics, all preserved across the authority flip:
-
-- BEL marks worktree+tab unread unconditionally — including the focused pane
-  (`onBell`, `pty-connection.ts`); pane unread only behind
-  `experimentalTerminalAttention`; keydown clears unread
-  (`onTerminalKeyDown`, `pty-connection.ts`).
-- BEL's OS notification is delayed 250 ms and yields to a pending
-  agent-task-complete (`scheduleTerminalBellNotification`,
-  `pty-connection.ts`).
-- working→idle starts the Claude cache timer (null settings = not hydrated,
-  treat enabled) and schedules completion with 250 ms grace + 1500 ms max
-  wait + detail-wait store subscription
-  (`AGENT_TASK_COMPLETE_NOTIFICATION_GRACE_MS` /
-  `AGENT_TASK_COMPLETE_NOTIFICATION_MAX_WAIT_MS`,
-  `agent-task-complete-policy.ts`).
-- Completion unread is suppressed only for the exact visible foreground pane
-  (`isVisibleForegroundPaneKey`, `use-notification-dispatch.ts`); BEL unread
-  has no such check.
-- Dispatch-time liveness/staleness guards
-  (`dispatchTerminalNotification`, `use-notification-dispatch.ts`) and main's
-  5 s per-worktree cooldown (`NOTIFICATION_COOLDOWN_MS`,
-  `src/main/ipc/notifications.ts`) remain the final gates.
-
-These need live renderer store state (PTY/layout maps, pane visibility,
-settings, `agentStatusByPaneKey`, repo labels), so they stay in the renderer:
-the pane-independent per-paneKey handler module
-(`terminal-side-effect-facts-handler.ts`) consumes `pty:sideEffect` and
-subsumes both `pty-connection.ts`'s callbacks and the parked watcher's
-callback block (`sideEffectCallbacks`, `parked-terminal-byte-watcher.ts`) —
-one policy path whether the tab is mounted, hidden, or parked. Main holds
-**no** notification timers; only the stale-title timer (parser state) lives
-in main.
-
-## Synthetic Frame Reroute
-
-`driveSyntheticTitleFromHook` and the spinner tick (`sendSyntheticTitle`,
-`src/main/index.ts`) feed `runtime.ingestSyntheticTitleFrame(ptyId, data)`,
-so synthetic agent-title/BEL frames enter the per-PTY tracker directly —
-**not** `onPtyData`, so emulator state, tails, transcripts, and stats never
-see them. The decorative-frame visibility gating
-(`shouldSendSyntheticTitleFrame`) stands. The legacy synthetic `pty:data`
-copy survives only in kill-switch-off mode, where renderer parsers still
-need the bytes. The visible xterm renders nothing from titles, but
-`pane.terminal.onTitleChange` feeds `registerPtyTitleSource`
-(`pty-connection.ts`) → renderer serialize-snapshot `lastTitle` (mobile
-parity); main prefers its own tracked title over renderer snapshot
-`lastTitle` in both serialize paths. Under main authority synthetic frames
-no longer produce phantom ACKs for bytes main never metered (`ackPtyData`,
-`pty-dispatcher.ts`).
-
-## Migration Switch and Double-Fire Prevention
-
-Authority is structural per PTY kind — the predicate is "bytes transit local
-main", exactly the `shouldOwnAgentStatusInRenderer` split
-(`pty-connection.ts`). One renderer-consulted kill switch
-(`settings.terminalMainSideEffectAuthority`, default on, mirroring
-`terminalHiddenViewParking`): when on, IPC transports and the parked watcher
-do not register byte parsers for local/SSH and the store handler consumes
-`pty:sideEffect`; when off, renderer parsers register and `pty:sideEffect`
-events are ignored. Main always parses and emits (its internal consumers need
-the tracker regardless); main consults the same setting only to keep the
-legacy synthetic-frame `pty:data` path alive while the switch is off. Exactly
-one consumer per fact at any time — decided at transport/watcher creation, so
-no per-chunk race.
-
-## Sidecar Consumers and Phase 4
-
-Keep renderer byte access (input pacing / raw-output consumers, not side
-effects): `agent-paste-draft.ts` (DECSET 2004 readiness),
-`launch-agent-background-session.ts` (startup-injection pacing, onData
-passthrough), `automation-session-observer.ts` (onData passthrough), and
-`parked-terminal-mode2031-responder.ts` (DECSET 2031 theme replies for
-parked tabs while the delivery gate is off). Their duplicated local OSC 9999
-store writes are gated off under main authority (the `onAgentStatus`
-automation callbacks still fire; only the racing `setAgentStatus` store
-writes drop). The Phase-4 hidden-delivery gate exempts PTYs with an active
-`subscribeToPtyData` sidecar: registration is auto-surfaced to main as a
-ref-counted delivery-interest signal (`pty-delivery-interest.ts`). With main
-authoritative, the parked watcher is purely fact-driven: byte parsing exists
-only in kill-switch-off mode, and the 2031 reply comes from the
-`2031-subscribe` fact when the gate is on (the byte responder sidecar only
-when it is off). The watcher file is deleted outright only when the kill
-switch retires — it returns as a byte parser only if remote-runtime tabs
-ever become parkable.
-
-## Invariants
-
-1. Every byte is side-effect-parsed exactly once, by exactly one authority,
-   chosen structurally per PTY kind.
-2. Attention facts never replay: snapshot/eager/attach replays restore title
-   state only.
-3. Notification policy (grace timers, yielding, suppression, dispatch guards)
-   lives with the renderer store; main emits facts with ordering metadata.
-4. Side-effect facts keep flowing while renderer byte delivery is
-   backpressured, parked, or stopped by the hidden-delivery gate.
-5. Synthetic agent frames feed the model tracker, never the emulator, tails,
-   transcripts, or stats.
-
-## Test Strategy
-
-- Parity harness (`terminal-title-tracker-parity.test.ts`): shared byte
-  fixtures (agent title cycles incl. coalesced chunks, BEL inside/spanning
-  OSC, CAN/SUB cancellation, cursor-agent literal, stale-title timeout under
-  fake timers, OSC 133;D, split PR URLs) run through the renderer
-  `createPtyOutputProcessor` and the main tracker; assert identical ordered
-  fact sequences.
-- Unit: main tracker tests beside `orca-runtime.test.ts` (lastOscTitle
-  parity, tui-idle waiter transitions, synthetic ingestion); store-handler
-  tests reusing `parked-terminal-byte-watcher.test.ts` scenarios.
-- Pinned tests that flip or retire: `pty-connection.test.ts` callback wiring,
-  `parked-terminal-byte-watcher.test.ts` (retires with the watcher);
-  `pty-transport*.test.ts` stay (processor remains for remote + kill switch).
-- E2E gates that must stay green throughout: `terminal-attention.spec.ts`,
-  `droid-notification.spec.ts`, `terminal-hidden-view-parking.spec.ts`,
-  `terminal-parked-memory.spec.ts`; add main-authority bell/completion cases
-  (parked tab, focused-pane suppression, kill switch off). SSH parity is
-  exercised manually per the SSH test procedure before each slice ships.
-
-## Cut-Offs (shipped as four stacked slices)
-
-1. **Shared tracker in main.** Extract the processor core to shared, run the
-   per-PTY tracker in `onPtyData` replacing `extractLastOscTitle`, parity
-   tests. Main-internal consumers only; no IPC or renderer change.
-2. **Authority flip.** `pty:sideEffect` channel, renderer store handler,
-   titles/bell/tracker authority to main for local+SSH behind the kill
-   switch; parked watcher stops byte parsing for those kinds.
-3. **Inversion unwind.** Synthetic frames into the tracker, off `pty:data`;
-   OSC 133;D and PR-link facts; mobile `lastTitle` source preference.
-4. **Long tail.** Command Code scrape to main, sidecar OSC 9999 dedup, parked
-   watcher shrunk to fact-driven mode (deletion waits on kill-switch
-   retirement), Phase 4 delivery-interest registration documented in the gate
-   design.
-
-## Open Items
-
-- **Daemon checkpoint `lastTitle` is write-only.** The daemon sleep/periodic
-  checkpoint (`daemon-pty-adapter.checkpointSessions` → daemon
-  `Session.getSnapshot`) persists the daemon emulator's `lastTitle`, which is
-  derived from real PTY bytes only — synthetic hook title frames never reach
-  the daemon process, so that field cannot carry hook-driven titles. Today no
-  restore path reads it back (`ColdRestoreInfo` drops it; reattach snapshots
-  surface only the ANSI payload), so there is nothing to fix. Main-side
-  consumers of the renderer serializer's `lastTitle` (mobile snapshot reads
-  and the headless hydration seed) prefer main's tracked title. If a future
-  consumer starts reading checkpoint `lastTitle`, it must route through the
-  same tracked-title preference.
-- **Kill-switch retirement.** Once `terminalMainSideEffectAuthority` is
-  removed, the parked watcher's byte-parser mode, the renderer transport
-  parsers for local/SSH, and the legacy synthetic-frame `pty:data` copy all
-  become dead code and the watcher byte path can be deleted outright.
diff --git a/docs/reference/terminal-switch-typing-lag-investigation.md b/docs/reference/terminal-switch-typing-lag-investigation.md
deleted file mode 100644
index d8f6da5a608..00000000000
--- a/docs/reference/terminal-switch-typing-lag-investigation.md
+++ /dev/null
@@ -1,362 +0,0 @@
-# Terminal Switch Typing Lag Investigation
-
-Date: 2026-07-01
-
-## Scope
-
-This note tracks the investigation into terminal input lag that appears after switching workspaces or terminals in a heavy packaged Orca profile.
-
-The user-visible symptom is that typing after switching back to a workspace can feel delayed for about one second. Text may appear all at once after the delay. The issue reproduced in the user's main packaged Orca app, but not reliably in lighter dev profiles.
-
-## Current Reproduction Setup
-
-- Main packaged Orca app is used for the meaningful repro.
-- The main profile had roughly 150 terminals when the lag reproduced.
-- The current worktree under test is `/Users/jinwoohong/orca/workspaces/orca/osprey`.
-- The main app did not expose CDP, so browser-level renderer profiling was limited.
-- The harness creates a throwaway bash terminal, switches away and back, sends a marker command, waits for a receipt file, and closes the throwaway terminal.
-- Harness path: `.tmp/terminal-main-app-typing-lag/probe.mjs`
-- The strongest repro switches through an old, output-rich workspace before typing in the probe terminal.
-- Current deterministic alternate terminal:
-  `term_4d7a0b50-e9ae-420e-ac5d-7ec12cbfa408` in the `triage-issues` workspace.
-
-Useful harness modes:
-
-```sh
-ORCA_PROBE_RUNS=8 ORCA_PROBE_FOCUS_EACH_RUN=0 ORCA_PROBE_TYPE_MODE=terminal-send ORCA_PROBE_RECEIPT_MODE=file node .tmp/terminal-main-app-typing-lag/probe.mjs
-ORCA_PROBE_RUNS=8 ORCA_PROBE_FOCUS_EACH_RUN=0 ORCA_PROBE_TYPE_MODE=daemon-direct-request ORCA_PROBE_RECEIPT_MODE=file node .tmp/terminal-main-app-typing-lag/probe.mjs
-ORCA_PROBE_RUNS=8 ORCA_PROBE_SKIP_SWITCH=1 ORCA_PROBE_FOCUS_EACH_RUN=0 ORCA_PROBE_TYPE_MODE=daemon-direct-request ORCA_PROBE_RECEIPT_MODE=file node .tmp/terminal-main-app-typing-lag/probe.mjs
-ORCA_PROBE_RUNS=4 ORCA_PROBE_FOCUS_EACH_RUN=0 ORCA_PROBE_SKIP_FOCUS=1 ORCA_PROBE_SAMPLE_RENDERER=0 ORCA_PROBE_ALT_TERMINAL=term_4d7a0b50-e9ae-420e-ac5d-7ec12cbfa408 ORCA_PROBE_TYPE_MODE=daemon-direct-request ORCA_PROBE_RECEIPT_MODE=file node .tmp/terminal-main-app-typing-lag/probe.mjs
-```
-
-## Key Measurements
-
-### 2026-07-01 follow-up: cold visit vs warm revisit
-
-After the metadata-only `listSessions()` fix, the user reported a sharper
-pattern:
-
-- First visit to a terminal, where the terminal briefly shows blank while the
-  renderer/webgl surface loads, does not show the typing lag.
-- Revisiting that same already-mounted terminal brings the lag back.
-
-Code-level reproduction:
-
-- `connectPanePty` previously armed a one-shot input liveness check from
-  `noteVisibilityResume()`.
-- The first `xterm.onData` input after a warm visibility resume called
-  `window.api.pty.listSessions()` before forwarding the byte with
-  `transport.sendInput(data)`.
-- A focused unit regression captured the bad order as
-  `["listSessions", "sendInput"]`.
-
-Fix direction:
-
-- Terminal input no longer starts a renderer→main→daemon session enumeration.
-- Hidden→visible lifecycle reconciliation and daemon missing-session exit events
-  remain responsible for stale pane cleanup.
-- The focused regression now asserts that repeated warm resumes plus typing
-  produce zero `listSessions()` calls from the input handler.
-
-### 2026-07-01 follow-up: preserved old daemon after input fix
-
-After the input-handler fix, the main packaged profile still reproduced the
-warm-switch lag because the live v18 daemon was preserved from an older build:
-
-- Fresh main-profile repro:
-  `.tmp/terminal-main-app-typing-lag/result-2026-07-01T09-59-08-111Z.json`
-- Direct daemon writes after switching took 661, 982, 998, 980, and 1000 ms.
-- Receipt latency after the daemon write returned stayed low at 77-85 ms.
-- No-switch control:
-  `.tmp/terminal-main-app-typing-lag/result-2026-07-01T09-59-28-346Z.json`
-  ended with fast direct daemon writes once the probe terminal settled.
-
-The remaining source hot path was the visibility-resume dead-session sweep:
-
-1. Switching a warm terminal hidden→visible ran the lifecycle visibility effect.
-2. The effect scheduled `reconcileDeadSessions`.
-3. `reconcileDeadSessions` invoked `window.api.pty.listSessions()`.
-4. A preserved old daemon still implemented `listSessions` by snapshotting every
-   live session, so the user's next daemon `write` queued behind that work.
-
-Fix:
-
-- Replace the automatic visibility-resume `listSessions()` sweep with a targeted
-  single-session liveness check.
-- Main exposes `pty:hasPty(id)`, which reads provider-owned in-memory PTY state
-  and returns `null` when the provider cannot answer authoritatively.
-- Renderer visible-resume asks only about each mounted pane's current PTY id.
-  The pane tears down only on an authoritative `false`; `true`, `null`, rejected
-  checks, remote-runtime ids, SSH ids, and stale/newborn races all fail open.
-- Keep visibility resume process tracking and PTY-size reassertion intact.
-- This preserves the recovery added by `a9ef6f916` for panes that missed
-  `pty:exit` while hidden, without putting a daemon-wide session enumeration on
-  the warm-switch/input path.
-
-Verification:
-
-- Focused vitest suite: `508` tests passed across terminal lifecycle,
-  pty-connection, dead-session reconcile, and PTY IPC.
-- Headful fullscreen E2E harness:
-  `tests/e2e/terminal-warm-switch-no-list-sessions.tmp.spec.ts`
-  wraps main-process `pty:listSessions` with an 800 ms stall and then switches
-  warm workspaces and types into the terminal.
-- Latest E2E artifact:
-  `.tmp/terminal-warm-switch-no-list-sessions/result-1782929853828.json`
-  showed `fullscreen: true`, `listSessionCallCount: 0`, and
-  `postTypeEchoLatencyMs: 10`.
-
-### CLI `terminal-send`, switch away/back
-
-Result file: `.tmp/terminal-main-app-typing-lag/result-2026-07-01T06-59-45-098Z.json`
-
-- Average echo latency was about 1841 ms.
-- Receipt latency was roughly 836-1445 ms.
-
-### CLI `terminal-send`, no switch
-
-- Average echo latency was about 312 ms.
-
-### CLI `terminal-send`, switch away/back, 1000 ms settle before send
-
-- Average echo latency was about 574 ms.
-- Receipt latency was mostly 1-227 ms, with one run around 684 ms.
-- This suggests the problematic window is bounded and concentrated immediately after switch/resume.
-
-### Direct daemon request, switch away/back
-
-Result file: `.tmp/terminal-main-app-typing-lag/result-2026-07-01T07-04-43-497Z.json`
-
-- The harness opened its own daemon control socket and sent the real daemon `write` request directly.
-- Daemon write response time was roughly 947-1142 ms.
-- Receipt latency after the daemon write response was about 76 ms.
-- Average echo latency was about 1385 ms.
-
-### Direct daemon request, no switch
-
-Result file: `.tmp/terminal-main-app-typing-lag/result-2026-07-01T07-05-12-496Z.json`
-
-- Daemon write response time was 0-45 ms.
-- Receipt latency was roughly 76-85 ms.
-- Average echo latency was about 258 ms.
-
-### Direct daemon request, output-rich workspace switch
-
-Result file: `.tmp/terminal-main-app-typing-lag/result-2026-07-01T07-22-06-789Z.json`
-
-- The alternate terminal was `term_4d7a0b50-e9ae-420e-ac5d-7ec12cbfa408` in the `triage-issues` workspace.
-- All four runs delayed.
-- Direct daemon `write` response times were 1566, 1527, 1477, and 1333 ms.
-- Average echo latency was about 1790 ms.
-- A daemon CPU sample was captured at `.tmp/terminal-main-app-typing-lag/daemon-71111-sample-20260701032206.txt`.
-
-Latest reproduced run:
-`.tmp/terminal-main-app-typing-lag/result-2026-07-01T07-27-25-513Z.json`
-
-- Two runs after switching through `triage-issues`.
-- Direct daemon `write` response times were 1556 and 1582 ms.
-- Receipt latency after the daemon write response was about 76-77 ms.
-- This confirms the daemon request itself waits; once it returns, the PTY and shell process the input quickly.
-
-### Direct daemon ping loop during switch
-
-A direct daemon client sent `ping` requests every roughly 50 ms while the harness issued `orca terminal switch` away and back.
-
-- Pings before and after the switch were effectively immediate.
-- One ping sent around 469 ms after switch start waited 1212 ms.
-- No terminal input was involved in this probe.
-
-This is the strongest evidence so far that workspace/terminal switching creates a daemon event-loop stall. The typing lag is a user-visible symptom of the same stall, not the root trigger.
-
-### Direct daemon request, no switch
-
-Latest no-switch result:
-`.tmp/terminal-main-app-typing-lag/result-2026-07-01T07-27-58-622Z.json`
-
-- First run had a direct daemon `write` response of 571 ms, likely a new-probe/settling artifact.
-- Next two runs were 0-1 ms.
-- No-switch is generally fast once the probe terminal is settled.
-
-### Pause after switching away
-
-- Adding `ORCA_PROBE_AFTER_SWITCH_AWAY_MS=1500` before switching back made direct daemon writes fast again.
-- This indicates expensive work starts when Orca switches into or resumes the output-rich workspace, then spills into the immediate switch-back/write window.
-
-Latest pause-control result:
-`.tmp/terminal-main-app-typing-lag/result-2026-07-01T07-29-58-568Z.json`
-
-- Direct daemon `write` response times were 0, 0, and 0 ms.
-- Echo latency was about 343-363 ms.
-- This bounds the problematic window to roughly the first 1-1.5 seconds after switching into/through the expensive workspace.
-
-### Synthetic heavy terminals
-
-- Synthetic split panes with large scrollback were not enough to reproduce reliably.
-- A plain heavy scrollback split reproduced once in four runs, then larger synthetic scrollback stayed fast.
-- A synthetic TUI repaint split stayed fast.
-- The issue is therefore not simply "large output" or "any hidden repaint"; old retained/reattach/snapshot state is still suspect.
-
-### Output timestamp check
-
-- `lastOutputAt` did not advance when switching through the `triage-issues` terminal and away.
-- That weakens the theory that a resume-triggered SIGWINCH caused the child TUI to emit a fresh repaint burst.
-- The delay can happen without fresh PTY output from the child process.
-
-### Snapshot and resize controls
-
-Direct `getSnapshot` probes on real sessions were much cheaper than the observed lag:
-
-- Output-rich `triage` terminal: about 10 ms, roughly 122 KB response.
-- Active `osprey` Codex terminal: about 57 ms, roughly 804 KB response.
-
-Synthetic resize pulses on throwaway heavy-scrollback terminals were also cheap:
-
-- Background 80x24 resize pulse: about 2 ms.
-- Focused 232x86 resize pulse: about 2 ms.
-
-These controls weaken the idea that one ordinary snapshot or one ordinary resize explains a 1.2-1.6 second stall. The remaining suspicious shape is switch-time fanout: many warm reattachments, snapshots, visibility/resume requests, pending-output drains, or checkpoint-like work running serially in the daemon.
-
-### Daemon `listSessions` proof
-
-The daemon-only measurement identified the blocking request:
-
-```json
-[
-  { "type": "ping", "elapsedMs": 0 },
-  { "type": "listSessions", "elapsedMs": 552, "count": 137 },
-  { "type": "ping", "elapsedMs": 0 },
-  { "type": "listSessions", "elapsedMs": 547, "count": 137 },
-  { "type": "ping", "elapsedMs": 0 }
-]
-```
-
-A second daemon-only queue test sent two `listSessions` requests and then a `ping` from another client:
-
-```json
-{
-  "totalMs": 1069,
-  "listSessions1Ms": 1068,
-  "listSessions2Ms": 1068,
-  "pingBehindListSessionsMs": 1034,
-  "sessions": 137
-}
-```
-
-This reproduces the same stall shape without terminal input or UI switching: a control request sent behind resume-time `listSessions` waits about one second.
-
-Source cause:
-
-- `TerminalHost.listSessions()` loops every live daemon session.
-- For each session, it calls `session.getSnapshot()` only to read `cols` and `rows`.
-- `getSnapshot()` serializes the headless xterm buffer, so a liveness/session-list request scales with terminal scrollback/state across the whole profile.
-- Renderer visibility resume calls `window.api.pty.listSessions()` for dead-session reconciliation. With about 137 live daemon sessions, one resume-time list was about 550 ms; two back-to-back resumes were about 1.0-1.1 seconds.
-
-## What This Rules Out
-
-- It is probably not keyboard focus. Direct daemon writes reproduce the delay.
-- It is probably not only renderer paint. Direct daemon writes wait before the shell receives bytes.
-- It is probably not bash or node-pty readiness. No-switch direct writes are fast, and receipt latency after a delayed daemon response is low.
-- It is probably not queueing only on Orca's normal daemon client socket. The direct-daemon harness uses a separate socket and still sees the delay.
-- It is not caused by typing itself. A ping loop with no write showed the daemon stall during switching.
-- It is unlikely to be a single normal `getSnapshot` or `resize` call, because direct controls for those operations are much cheaper than the observed stall.
-- The resume-time dead-pane recovery is still necessary; the hot path should
-  use single-PTY liveness, not a global session list.
-
-## Current Conclusion
-
-Switching workspaces or terminals can create a short daemon/main busy window
-when warm resume triggers global session enumeration. During that window, even a
-direct terminal `write` request waits before the daemon services it. Once the
-daemon services the write, the shell receives and processes the bytes quickly.
-
-The confirmed root for the remaining warm-switch lag is the visibility-resume
-dead-session reconciliation path calling global `listSessions()` in profiles
-with many preserved daemon sessions. The original dead-session recovery is valid;
-the expensive primitive was the problem.
-
-## Leading Hypotheses
-
-1. Confirmed: resume-time dead-session reconciliation called daemon
-   `listSessions`, and older daemons synchronously snapshot every live session
-   to return cols/rows.
-2. Confirmed: avoiding global `listSessions()` on warm resume removes the
-   request that queued ahead of first post-switch input.
-3. Possible secondary contributor: switching to certain old or output-rich
-   workspaces may also reattach existing daemon-backed PTYs. The daemon
-   `createOrAttach` path synchronously calls `existing.getSnapshot()` before
-   responding.
-4. Possible secondary contributor: hidden-output recovery, pending-output
-   draining, or another snapshot-like serialization path runs synchronously on
-   resume and delays request handling.
-5. Less likely: workspace or terminal resume triggers visible-terminal
-   resize/SIGWINCH or TUI repaint output. The unchanged `lastOutputAt`
-   observation currently makes this less likely than `listSessions`.
-
-## Relevant Code Areas
-
-- CLI terminal send: `src/cli/handlers/terminal.ts`
-- Runtime terminal send/focus/write: `src/main/runtime/orca-runtime.ts`
-- Runtime PTY data handling: `onPtyData`, `trackHeadlessTerminalData`, hidden-output serialization in `src/main/runtime/orca-runtime.ts`
-- Daemon request routing: `src/main/daemon/daemon-server.ts`
-- Daemon session write/resize/output handling: `src/main/daemon/session.ts`
-- Daemon-side headless terminal state: `src/main/daemon/headless-emulator.ts`
-- Daemon adapter: `src/main/daemon/daemon-pty-adapter.ts`
-- Main IPC PTY controller: `src/main/ipc/pty.ts`
-- Renderer terminal resume: `src/renderer/src/components/terminal-pane/terminal-visibility-resume.ts`
-- Renderer PTY connection and resume size reassertion: `src/renderer/src/components/terminal-pane/pty-connection.ts`
-- Renderer output scheduler: `src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts`
-- Existing-session reattach snapshot: `TerminalHost.createOrAttach` in `src/main/daemon/terminal-host.ts`
-- Session snapshot serialization: `TerminalSession.getSnapshot()` in `src/main/daemon/session.ts`
-- Snapshot cost benchmark: `src/main/daemon/headless-emulator-snapshot-cost.bench.test.ts`
-
-## Current Root-Cause Theory
-
-The root cause is using global session enumeration as a per-pane liveness check:
-
-1. Workspace switching makes a terminal pane visible again.
-2. The renderer schedules dead-session reconciliation on hidden-to-visible resume.
-3. The old reconcile path called `window.api.pty.listSessions()`, which reaches
-   the daemon `listSessions` RPC.
-4. Older preserved daemons implement `TerminalHost.listSessions()` by calling
-   `session.getSnapshot()` for every live session.
-5. With a heavy profile, those snapshot serializations block the daemon event
-   loop for about 550 ms per list.
-6. A switch away/back can put a `write` behind two resume-time lists, yielding
-   about 1.0-1.6 seconds of delayed input.
-
-This theory fits the current evidence:
-
-- Direct daemon writes block, so the delay is below keyboard focus and normal CLI plumbing.
-- Receipt handling after the daemon write response is fast, so the shell and PTY are not the bottleneck.
-- No-switch writes are fast.
-- Waiting after switching away lets the expensive resume work finish, so switching back and typing is fast.
-- `lastOutputAt` does not advance, so the child process probably is not generating the expensive work.
-- Synthetic fresh heavy output did not reproduce reliably, which points toward retained old session/state, request fanout, or workspace-specific resume behavior rather than simple line count.
-
-The correct fix is two-layered:
-
-1. Keep daemon `listSessions` metadata-only for builds where callers genuinely
-   need the global session list.
-2. Do not use `listSessions` for warm-resume dead-pane recovery. Use
-   `pty:hasPty(id)` to ask about the pane's own PTY id, backed by provider
-   in-memory state. Close only on authoritative `false`; fail open on `true`,
-   `null`, unsupported providers, remote-runtime/SSH ids, and stale/newborn
-   races.
-
-## Investigation Constraints
-
-- Do not kill or restart the user's main packaged Orca app or daemon without explicit approval.
-- Use throwaway terminals for probes and close them afterward.
-- Keep temp harnesses and screenshots out of commits unless explicitly requested.
-- Reproduce in the real main-app flow when possible; lighter dev profiles may not show the problem.
-
-## Verification Plan
-
-1. Unit-test that `pty:hasPty(id)` does not call provider `listProcesses()`.
-2. Unit-test that targeted liveness still closes a missing local PTY and fails
-   open for live/unknown/stale cases.
-3. Unit-test that terminal input and warm resume do not call `listSessions()`.
-4. Re-run the headful fullscreen warm-switch E2E with `pty:listSessions`
-   artificially delayed and assert the count stays zero.
-5. Re-run the main-app direct-daemon switch/no-switch harness when validating
-   against the user's heavy profile.
diff --git a/src/main/daemon/headless-emulator-fidelity.fuzz.test.ts b/src/main/daemon/headless-emulator-fidelity.fuzz.test.ts
index 8ce1191722d..77db320650c 100644
--- a/src/main/daemon/headless-emulator-fidelity.fuzz.test.ts
+++ b/src/main/daemon/headless-emulator-fidelity.fuzz.test.ts
@@ -19,8 +19,8 @@ import {
   writeChunksToTerminal
 } from '../../shared/terminal-restore-parity-fixture'
 
-// Differential garble gate for the hidden-terminal model/view contract
-// (docs/reference/terminal-model-view-contract.md): with the hidden-delivery
+// Differential garble gate for the hidden-terminal model/view contract:
+// with the hidden-delivery
 // gate on, a hidden pane receives NOTHING — main's HeadlessEmulator is the
 // source of truth and reveal repaints the renderer xterm from
 // preamble + rehydrateSequences + snapshotAnsi (applyMainBufferSnapshot).
diff --git a/src/main/daemon/headless-emulator.ts b/src/main/daemon/headless-emulator.ts
index 767c9904a6c..e1950d9caf5 100644
--- a/src/main/daemon/headless-emulator.ts
+++ b/src/main/daemon/headless-emulator.ts
@@ -131,7 +131,7 @@ export class HeadlessEmulator {
     // the visible casualty). Only main's runtime per-PTY emulators pass a
     // sink, and even then replies flow only for chunks the hidden-delivery
     // gate DROPPED, where the renderer never sees the bytes and main is the
-    // single answerer. See docs/reference/terminal-query-authority.md.
+    // single answerer under main's terminal query authority.
     this.onQueryReply = opts.onQueryReply ?? null
     if (this.onQueryReply) {
       this.terminal.onData((reply) => this.emitQueryReply(reply))
diff --git a/src/main/daemon/terminal-view-attribute-responder.ts b/src/main/daemon/terminal-view-attribute-responder.ts
index 68ff83c349f..ddd04bf11dc 100644
--- a/src/main/daemon/terminal-view-attribute-responder.ts
+++ b/src/main/daemon/terminal-view-attribute-responder.ts
@@ -1,6 +1,6 @@
 /**
- * Phase 5 slice 2 (docs/reference/terminal-query-authority.md §View-attribute
- * bridge): OSC 4/10/11/12 and DSR ?996n responder handlers for the runtime
+ * Phase 5 slice 2 (View-attribute bridge): OSC 4/10/11/12 and DSR ?996n
+ * responder handlers for the runtime
  * headless emulator. The headless xterm core has no theme service, so these
  * handlers compute replies from the renderer's pushed attribute snapshot,
  * with per-PTY OSC SET mutations layered on top — mirroring exactly what the
diff --git a/src/main/ipc/pty-hidden-delivery-gate.ts b/src/main/ipc/pty-hidden-delivery-gate.ts
index 77230f7300c..b1f089e385e 100644
--- a/src/main/ipc/pty-hidden-delivery-gate.ts
+++ b/src/main/ipc/pty-hidden-delivery-gate.ts
@@ -8,7 +8,6 @@
  * the existing seq-guarded machinery. Any renderer party that still needs raw
  * bytes (dispatcher sidecars) registers delivery
  * interest, which suppresses the gate for that PTY.
- * See docs/reference/terminal-side-effect-authority.md (Open Items).
  */
 import type { GlobalSettings } from '../../shared/types'
 
diff --git a/src/main/ipc/skills.test.ts b/src/main/ipc/skills.test.ts
index 91c449f751f..4a412f2494d 100644
--- a/src/main/ipc/skills.test.ts
+++ b/src/main/ipc/skills.test.ts
@@ -3,15 +3,19 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 const {
   handleMock,
   discoverSkillsMock,
+  discoverSkillsInWslMock,
   inventorySkillFreshnessMock,
   getDefaultWslDistroMock,
-  getWslHomeMock
+  getWslHomeMock,
+  parseWslPathMock
 } = vi.hoisted(() => ({
   handleMock: vi.fn(),
   discoverSkillsMock: vi.fn(),
+  discoverSkillsInWslMock: vi.fn(),
   inventorySkillFreshnessMock: vi.fn(),
   getDefaultWslDistroMock: vi.fn(),
-  getWslHomeMock: vi.fn()
+  getWslHomeMock: vi.fn(),
+  parseWslPathMock: vi.fn()
 }))
 
 vi.mock('electron', () => ({
@@ -27,13 +31,27 @@ vi.mock('../skills/discovery', () => ({
   discoverSkills: discoverSkillsMock
 }))
 
+vi.mock('../skills/skill-discovery-wsl', () => ({
+  discoverSkillsInWsl: discoverSkillsInWslMock
+}))
+
 vi.mock('../skills/skill-freshness-inventory', () => ({
   inventorySkillFreshness: inventorySkillFreshnessMock
 }))
 
 vi.mock('../wsl', () => ({
   getDefaultWslDistro: getDefaultWslDistroMock,
-  getWslHome: getWslHomeMock
+  getWslHome: getWslHomeMock,
+  parseWslPath: parseWslPathMock,
+  toLinuxPath: (pathValue: string) => {
+    if (pathValue === '\\\\wsl.localhost\\Ubuntu\\home\\alice') {
+      return '/home/alice'
+    }
+    if (pathValue === 'C:\\repo\\worktree') {
+      return '/mnt/c/repo/worktree'
+    }
+    return pathValue
+  }
 }))
 
 import { registerSkillsHandlers } from './skills'
@@ -48,9 +66,13 @@ describe('registerSkillsHandlers', () => {
   beforeEach(() => {
     handleMock.mockReset()
     discoverSkillsMock.mockReset()
+    discoverSkillsInWslMock.mockReset()
     getDefaultWslDistroMock.mockReset()
     getWslHomeMock.mockReset()
+    parseWslPathMock.mockReset()
+    parseWslPathMock.mockReturnValue(null)
     discoverSkillsMock.mockResolvedValue({ skills: [], sources: [], scannedAt: 1 })
+    discoverSkillsInWslMock.mockResolvedValue({ skills: [], sources: [], scannedAt: 1 })
     inventorySkillFreshnessMock.mockResolvedValue({
       schemaVersion: 1,
       installations: [],
@@ -139,10 +161,35 @@ describe('registerSkillsHandlers', () => {
 
     expect(getDefaultWslDistroMock).not.toHaveBeenCalled()
     expect(getWslHomeMock).toHaveBeenCalledWith('Ubuntu')
-    expect(discoverSkillsMock).toHaveBeenCalledWith({
-      repos: [],
-      homeDir: '\\\\wsl.localhost\\Ubuntu\\home\\alice',
-      cwd: '\\\\wsl.localhost\\Ubuntu\\home\\alice'
+    expect(discoverSkillsInWslMock).toHaveBeenCalledWith({
+      distro: 'Ubuntu',
+      homeDir: '/home/alice',
+      cwd: '/home/alice'
+    })
+  })
+
+  it('scans the requested project directory in the selected WSL runtime', async () => {
+    const handler = getDiscoverHandler()
+
+    await handler(null, {
+      cwd: 'C:\\repo\\worktree',
+      projectRuntime: {
+        status: 'resolved',
+        runtime: {
+          kind: 'wsl',
+          hostPlatform: 'wsl',
+          projectId: 'repo-1',
+          distro: 'Ubuntu',
+          reason: 'project-override',
+          cacheKey: 'repo-1:wsl:Ubuntu'
+        }
+      }
+    })
+
+    expect(discoverSkillsInWslMock).toHaveBeenCalledWith({
+      distro: 'Ubuntu',
+      homeDir: '/home/alice',
+      cwd: '/mnt/c/repo/worktree'
     })
   })
 
diff --git a/src/main/ipc/skills.ts b/src/main/ipc/skills.ts
index 711162927fe..c349af8b24e 100644
--- a/src/main/ipc/skills.ts
+++ b/src/main/ipc/skills.ts
@@ -1,60 +1,23 @@
 import { app, ipcMain } from 'electron'
 import type { Store } from '../persistence'
-import { discoverSkills } from '../skills/discovery'
-import type { SkillDiscoveryResult, SkillDiscoveryTarget } from '../../shared/skills'
+import {
+  SkillDiscoveryTargetSchema,
+  type SkillDiscoveryResult,
+  type SkillDiscoveryTarget
+} from '../../shared/skills'
 import type { SkillFreshnessInventory } from '../../shared/skill-freshness'
-import { getDefaultWslDistro, getWslHome } from '../wsl'
 import { inventorySkillFreshness } from '../skills/skill-freshness-inventory'
-
-type SkillDiscoveryRuntimeTarget =
-  | { runtime: 'host' }
-  | { runtime: 'wsl'; wslDistro: string | null | undefined }
-
-function getSkillDiscoveryRuntimeTarget(
-  target: SkillDiscoveryTarget | undefined
-): SkillDiscoveryRuntimeTarget {
-  const projectRuntime = target?.projectRuntime
-  if (!projectRuntime) {
-    return target?.runtime === 'wsl'
-      ? { runtime: 'wsl', wslDistro: target.wslDistro }
-      : { runtime: 'host' }
-  }
-
-  if (projectRuntime.status === 'repair-required') {
-    throw new Error(
-      `Project runtime requires repair before skill discovery: ${projectRuntime.repair.reason}`
-    )
-  }
-
-  if (projectRuntime.runtime.kind === 'wsl') {
-    return { runtime: 'wsl', wslDistro: projectRuntime.runtime.distro }
-  }
-
-  return { runtime: 'host' }
-}
+import {
+  discoverSkillsOnTarget,
+  resolveSkillDiscoveryTarget
+} from '../skills/skill-discovery-target'
 
 export function registerSkillsHandlers(store: Store): void {
   ipcMain.handle(
     'skills:discover',
     async (_event, target?: SkillDiscoveryTarget): Promise<SkillDiscoveryResult> => {
-      const runtimeTarget = getSkillDiscoveryRuntimeTarget(target)
-      if (runtimeTarget.runtime === 'wsl') {
-        if (process.platform !== 'win32') {
-          throw new Error('WSL skill discovery is only available on Windows.')
-        }
-        const distro = runtimeTarget.wslDistro?.trim() || getDefaultWslDistro()
-        if (!distro) {
-          throw new Error('No WSL distribution is available for skill discovery.')
-        }
-        const homeDir = getWslHome(distro)
-        if (!homeDir) {
-          throw new Error(`Could not resolve the WSL home directory for ${distro}.`)
-        }
-        return discoverSkills({ repos: [], homeDir, cwd: homeDir })
-      }
-
-      const cwd = target?.cwd?.trim() || undefined
-      return cwd ? discoverSkills({ repos: [], cwd }) : discoverSkills({ repos: store.getRepos() })
+      const parsedTarget = target ? SkillDiscoveryTargetSchema.parse(target) : undefined
+      return discoverSkillsOnTarget(resolveSkillDiscoveryTarget(parsedTarget), store.getRepos())
     }
   )
 
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 17fcec9ba87..9231beb040a 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -8233,6 +8233,16 @@ export class OrcaRuntimeService {
     return pty ? { worktreeId: pty.worktreeId, connectionId: pty.connectionId } : null
   }
 
+  // Why: remote clients cannot resolve this runtime's WSL project preference,
+  // so host-affecting RPCs (skill discovery) resolve it from the owning store.
+  resolveProjectRuntimeForWorktree(
+    worktreeId: string | null | undefined
+  ): ProjectExecutionRuntimeResolution | undefined {
+    return this.store && worktreeId
+      ? resolveLocalProjectRuntimeForWorktreeId(this.requireStore(), worktreeId)
+      : undefined
+  }
+
   getTerminalOrchestrationCliCommand(handle: string): 'orca' | 'orca-ide' {
     let pty: RuntimePtyWorktreeRecord | null = null
     try {
diff --git a/src/main/runtime/rpc/methods/skills.test.ts b/src/main/runtime/rpc/methods/skills.test.ts
new file mode 100644
index 00000000000..a4335ec2e62
--- /dev/null
+++ b/src/main/runtime/rpc/methods/skills.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { RpcContext } from '../core'
+
+vi.mock('../../../skills/skill-discovery-target', () => ({
+  resolveSkillDiscoveryTarget: vi.fn((target) => ({ kind: 'native-host', cwd: target?.cwd })),
+  discoverSkillsOnTarget: vi.fn(async () => ({ skills: [], sources: [], scannedAt: 1 }))
+}))
+
+import { SKILL_METHODS } from './skills'
+import { resolveSkillDiscoveryTarget } from '../../../skills/skill-discovery-target'
+
+const WSL_RUNTIME = {
+  status: 'resolved',
+  runtime: {
+    kind: 'wsl',
+    hostPlatform: 'wsl',
+    projectId: 'project-1',
+    distro: 'Ubuntu',
+    reason: 'project-override',
+    cacheKey: 'wsl:Ubuntu'
+  }
+} as const
+
+function makeContext(overrides: {
+  resolveProjectRuntimeForWorktree?: (worktreeId: string | null | undefined) => unknown
+}): RpcContext {
+  return {
+    runtime: {
+      listRepos: () => [],
+      resolveProjectRuntimeForWorktree:
+        overrides.resolveProjectRuntimeForWorktree ?? (() => undefined)
+    }
+  } as unknown as RpcContext
+}
+
+function discoverMethod() {
+  const method = SKILL_METHODS.find((entry) => entry.name === 'skills.discover')
+  if (!method) {
+    throw new Error('skills.discover method not registered')
+  }
+  return method
+}
+
+describe('skills.discover RPC', () => {
+  it('resolves the project runtime from the owning runtime store when the caller omits it', async () => {
+    const resolveProjectRuntimeForWorktree = vi.fn(() => WSL_RUNTIME)
+    await discoverMethod().handler(
+      { cwd: 'C:\\repo', worktreeId: 'worktree-1' },
+      makeContext({ resolveProjectRuntimeForWorktree })
+    )
+    expect(resolveProjectRuntimeForWorktree).toHaveBeenCalledWith('worktree-1')
+    expect(vi.mocked(resolveSkillDiscoveryTarget)).toHaveBeenLastCalledWith(
+      expect.objectContaining({ projectRuntime: WSL_RUNTIME })
+    )
+  })
+
+  it('prefers a caller-supplied project runtime over store resolution', async () => {
+    const resolveProjectRuntimeForWorktree = vi.fn()
+    await discoverMethod().handler(
+      { cwd: '/repo', worktreeId: 'worktree-1', projectRuntime: WSL_RUNTIME },
+      makeContext({ resolveProjectRuntimeForWorktree })
+    )
+    expect(resolveProjectRuntimeForWorktree).not.toHaveBeenCalled()
+    expect(vi.mocked(resolveSkillDiscoveryTarget)).toHaveBeenLastCalledWith(
+      expect.objectContaining({ projectRuntime: WSL_RUNTIME })
+    )
+  })
+})
diff --git a/src/main/runtime/rpc/methods/skills.ts b/src/main/runtime/rpc/methods/skills.ts
index 8719cc528ab..346198aeffc 100644
--- a/src/main/runtime/rpc/methods/skills.ts
+++ b/src/main/runtime/rpc/methods/skills.ts
@@ -1,20 +1,25 @@
-import { z } from 'zod'
 import { defineMethod, type RpcMethod } from '../core'
-import { discoverSkills } from '../../../skills/discovery'
-
-const SkillDiscoveryParams = z.object({
-  cwd: z.string().optional().nullable()
-})
+import { SkillDiscoveryTargetSchema } from '../../../../shared/skills'
+import {
+  discoverSkillsOnTarget,
+  resolveSkillDiscoveryTarget
+} from '../../../skills/skill-discovery-target'
 
 export const SKILL_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'skills.discover',
-    params: SkillDiscoveryParams,
+    params: SkillDiscoveryTargetSchema.default({}),
     handler: async (params, { runtime }) => {
-      const cwd = params.cwd?.trim() || undefined
-      return cwd
-        ? discoverSkills({ repos: [], cwd })
-        : discoverSkills({ repos: runtime.listRepos() })
+      // Why: the executing runtime owns WSL project preferences. Remote callers
+      // send worktree identity only; trusting their projectRuntime absence
+      // would scan this host's native filesystem for a WSL-configured project.
+      const target = params.projectRuntime
+        ? params
+        : {
+            ...params,
+            projectRuntime: runtime.resolveProjectRuntimeForWorktree(params.worktreeId)
+          }
+      return discoverSkillsOnTarget(resolveSkillDiscoveryTarget(target), runtime.listRepos())
     }
   })
 ]
diff --git a/src/main/runtime/terminal-model-query-authority.ts b/src/main/runtime/terminal-model-query-authority.ts
index e1e0f9c28ef..df8f05798a4 100644
--- a/src/main/runtime/terminal-model-query-authority.ts
+++ b/src/main/runtime/terminal-model-query-authority.ts
@@ -1,6 +1,6 @@
 /**
  * Phase 5 of the terminal model/view architecture: main-side terminal query
- * authority (docs/reference/terminal-query-authority.md).
+ * authority.
  *
  * The delivery decision is the reply decision: main answers a query iff the
  * hidden-delivery gate dropped the chunk that carried it. This module owns
diff --git a/src/main/runtime/terminal-query-responder.test.ts b/src/main/runtime/terminal-query-responder.test.ts
index b6988e06731..896fa59b060 100644
--- a/src/main/runtime/terminal-query-responder.test.ts
+++ b/src/main/runtime/terminal-query-responder.test.ts
@@ -1,5 +1,5 @@
 /**
- * Phase 5 model query responder (docs/reference/terminal-query-authority.md):
+ * Phase 5 model query responder:
  * reply parity through the runtime emulator, the per-chunk ownership matrix,
  * the main-side replay guard, and the ingestion-time capture race.
  */
diff --git a/src/main/runtime/terminal-view-attribute-store.ts b/src/main/runtime/terminal-view-attribute-store.ts
index ee55581bfe9..2743dd70e3b 100644
--- a/src/main/runtime/terminal-view-attribute-store.ts
+++ b/src/main/runtime/terminal-view-attribute-store.ts
@@ -1,6 +1,6 @@
 /**
- * Phase 5 slice 2 (docs/reference/terminal-query-authority.md §View-attribute
- * bridge): main-side cache of the renderer's `pty:terminalViewAttributes`
+ * Phase 5 slice 2 (View-attribute bridge): main-side cache of the renderer's
+ * `pty:terminalViewAttributes`
  * push. One app-global snapshot, not per-PTY — per-pane font zoom never
  * affects these attributes and the color/cursor settings are global.
  *
diff --git a/src/main/skills/claude-plugin-skill-sources-wsl.test.ts b/src/main/skills/claude-plugin-skill-sources-wsl.test.ts
new file mode 100644
index 00000000000..4d4f1add82c
--- /dev/null
+++ b/src/main/skills/claude-plugin-skill-sources-wsl.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildWslClaudePluginMetadataCommand,
+  parseWslClaudePluginMetadataOutput
+} from './claude-plugin-skill-sources-wsl'
+
+function record(...fields: string[]): string {
+  return `${fields.join('\0')}\0`
+}
+
+describe('WSL Claude plugin metadata', () => {
+  it('reads metadata paths inside the distro without exposing them to Windows shell parsing', () => {
+    const command = buildWslClaudePluginMetadataCommand(["/home/alice's/.claude/settings.json"])
+    const encoded = /printf %s '([^']+)'/.exec(command)?.[1]
+    expect(encoded).toBeTruthy()
+    const script = Buffer.from(encoded!, 'base64').toString('utf8')
+
+    expect(script).toContain(`'/home/alice'\\''s/.claude/settings.json'`)
+    expect(script).toContain('base64 < "$metadata_path"')
+    expect(command).not.toContain('/home/alice')
+  })
+
+  it('decodes present files and retains missing files as null', () => {
+    const settings = JSON.stringify({ enabledPlugins: { 'plugin@market': true } })
+    const output = [
+      record('F', '0', '1', Buffer.from(settings).toString('base64')),
+      record('F', '1', '0', '')
+    ].join('')
+
+    expect(parseWslClaudePluginMetadataOutput(output, 2)).toEqual([settings, null])
+  })
+
+  it('rejects malformed metadata responses', () => {
+    expect(() => parseWslClaudePluginMetadataOutput(record('F', '4', '1', ''), 1)).toThrow(
+      'invalid response'
+    )
+  })
+})
diff --git a/src/main/skills/claude-plugin-skill-sources-wsl.ts b/src/main/skills/claude-plugin-skill-sources-wsl.ts
new file mode 100644
index 00000000000..d3adddfde55
--- /dev/null
+++ b/src/main/skills/claude-plugin-skill-sources-wsl.ts
@@ -0,0 +1,100 @@
+import { execFile } from 'node:child_process'
+import { posix as pathPosix } from 'node:path'
+import { buildEncodedWslBashCommand, quoteBashString } from '../wsl-bash-command'
+import {
+  getClaudePluginMetadataPaths,
+  resolveClaudePluginSkillSources,
+  type ClaudePluginMetadata
+} from './claude-plugin-skill-sources'
+import type { SkillScanRoot } from './skill-discovery-sources'
+
+const MAX_PLUGIN_METADATA_BYTES = 4 * 1024 * 1024
+const WSL_METADATA_TIMEOUT_MS = 5_000
+const WSL_METADATA_MAX_BUFFER_BYTES = 32 * 1024 * 1024
+
+export function buildWslClaudePluginMetadataCommand(paths: readonly string[]): string {
+  const lines = [
+    'set -u',
+    'set -o pipefail',
+    'read_metadata() {',
+    '  metadata_index=$1',
+    '  metadata_path=$2',
+    `  metadata_size=$(stat -c '%s' -- "$metadata_path" 2>/dev/null || true)`,
+    `  if [ -z "$metadata_size" ] || [ "$metadata_size" -gt ${MAX_PLUGIN_METADATA_BYTES} ]; then`,
+    `    printf '%s\\0%s\\0%s\\0\\0' F "$metadata_index" 0`,
+    '    return',
+    '  fi',
+    `  encoded_metadata=$(base64 < "$metadata_path" | tr -d '\\n') || { printf '%s\\0%s\\0%s\\0\\0' F "$metadata_index" 0; return; }`,
+    `  printf '%s\\0%s\\0%s\\0%s\\0' F "$metadata_index" 1 "$encoded_metadata"`,
+    '}'
+  ]
+  paths.forEach((pathValue, index) => {
+    lines.push(`read_metadata ${index} ${quoteBashString(pathValue)}`)
+  })
+  return buildEncodedWslBashCommand(lines.join('\n'))
+}
+
+export function parseWslClaudePluginMetadataOutput(
+  output: string,
+  fileCount: number
+): (string | null)[] {
+  const contents = Array<string | null>(fileCount).fill(null)
+  const fields = output.split('\0')
+  let index = 0
+  while (index < fields.length && fields[index]) {
+    const kind = fields[index++]
+    const fileIndex = Number.parseInt(fields[index++] ?? '', 10)
+    const exists = fields[index++] === '1'
+    const encoded = fields[index++]
+    if (kind !== 'F' || !Number.isInteger(fileIndex) || fileIndex < 0 || fileIndex >= fileCount) {
+      throw new Error('WSL Claude plugin metadata returned an invalid response.')
+    }
+    if (exists && encoded !== undefined) {
+      contents[fileIndex] = Buffer.from(encoded, 'base64').toString('utf8')
+    }
+  }
+  return contents
+}
+
+function executeWslMetadataRead(distro: string, command: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      'wsl.exe',
+      ['-d', distro, '--', 'bash', '-c', command],
+      {
+        encoding: 'utf8',
+        maxBuffer: WSL_METADATA_MAX_BUFFER_BYTES,
+        timeout: WSL_METADATA_TIMEOUT_MS,
+        windowsHide: true
+      },
+      (error, stdout) => {
+        if (error) {
+          reject(error)
+          return
+        }
+        resolve(stdout)
+      }
+    )
+  })
+}
+
+export async function discoverClaudePluginSkillSourcesInWsl(args: {
+  distro: string
+  homeDir: string
+  cwd: string
+}): Promise<SkillScanRoot[]> {
+  const paths = getClaudePluginMetadataPaths(args.homeDir, args.cwd, pathPosix)
+  const orderedPaths = [paths.installedPlugins, ...paths.settings]
+  // Why: plugin enablement and install paths belong to the distro just like
+  // SKILL.md identity; reading them through UNC could apply Windows semantics.
+  const output = await executeWslMetadataRead(
+    args.distro,
+    buildWslClaudePluginMetadataCommand(orderedPaths)
+  )
+  const [installedPlugins, ...settings] = parseWslClaudePluginMetadataOutput(
+    output,
+    orderedPaths.length
+  )
+  const metadata: ClaudePluginMetadata = { installedPlugins, settings }
+  return resolveClaudePluginSkillSources({ metadata, cwd: args.cwd, pathApi: pathPosix })
+}
diff --git a/src/main/skills/claude-plugin-skill-sources.test.ts b/src/main/skills/claude-plugin-skill-sources.test.ts
new file mode 100644
index 00000000000..c12f2e3415c
--- /dev/null
+++ b/src/main/skills/claude-plugin-skill-sources.test.ts
@@ -0,0 +1,122 @@
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { resolveClaudePluginSkillSources } from './claude-plugin-skill-sources'
+
+function installedPlugins(installs: Record<string, Record<string, unknown>[]>): string {
+  return JSON.stringify({ version: 2, plugins: installs })
+}
+
+function settings(enabledPlugins: Record<string, boolean>): string {
+  return JSON.stringify({ enabledPlugins })
+}
+
+describe('Claude plugin skill sources', () => {
+  const pluginId = 'compound-engineering@compound-engineering-plugin'
+  const projectPath = join('/workspace', 'orca')
+  const cwd = join(projectPath, 'worktree')
+
+  it('selects the applicable project install over a stale user version', () => {
+    const roots = resolveClaudePluginSkillSources({
+      cwd,
+      metadata: {
+        installedPlugins: installedPlugins({
+          [pluginId]: [
+            {
+              scope: 'user',
+              installPath: '/home/alice/.claude/plugins/cache/compound/3.13.1',
+              lastUpdated: '2026-06-23T00:00:00.000Z'
+            },
+            {
+              scope: 'project',
+              projectPath,
+              installPath: '/home/alice/.claude/plugins/cache/compound/3.14.3',
+              lastUpdated: '2026-06-25T00:00:00.000Z'
+            }
+          ]
+        }),
+        settings: [settings({ [pluginId]: true })]
+      }
+    })
+
+    expect(roots).toEqual([
+      expect.objectContaining({
+        label: 'Claude plugin compound-engineering',
+        path: join('/home/alice/.claude/plugins/cache/compound/3.14.3', 'skills'),
+        sourceKind: 'plugin',
+        providers: ['claude'],
+        owner: 'claude'
+      })
+    ])
+  })
+
+  it('falls back to the user install outside the project scope', () => {
+    const roots = resolveClaudePluginSkillSources({
+      cwd: '/workspace/another-project',
+      metadata: {
+        installedPlugins: installedPlugins({
+          [pluginId]: [
+            {
+              scope: 'user',
+              installPath: '/home/alice/.claude/plugins/cache/compound/user'
+            },
+            {
+              scope: 'project',
+              projectPath,
+              installPath: '/home/alice/.claude/plugins/cache/compound/project'
+            }
+          ]
+        }),
+        settings: [settings({ [pluginId]: true })]
+      }
+    })
+
+    expect(roots[0]?.path).toBe(join('/home/alice/.claude/plugins/cache/compound/user', 'skills'))
+  })
+
+  it('honors project and local settings overrides for disabled plugins', () => {
+    const roots = resolveClaudePluginSkillSources({
+      cwd,
+      metadata: {
+        installedPlugins: installedPlugins({
+          [pluginId]: [
+            {
+              scope: 'project',
+              projectPath,
+              installPath: '/home/alice/.claude/plugins/cache/compound/3.14.3'
+            }
+          ]
+        }),
+        settings: [settings({ [pluginId]: true }), settings({ [pluginId]: false })]
+      }
+    })
+
+    expect(roots).toEqual([])
+  })
+
+  it('chooses the newest applicable install within the same scope', () => {
+    const roots = resolveClaudePluginSkillSources({
+      cwd,
+      metadata: {
+        installedPlugins: installedPlugins({
+          [pluginId]: [
+            {
+              scope: 'project',
+              projectPath,
+              installPath: '/home/alice/.claude/plugins/cache/compound/old',
+              lastUpdated: '2026-01-01T00:00:00.000Z'
+            },
+            {
+              scope: 'project',
+              projectPath,
+              installPath: '/home/alice/.claude/plugins/cache/compound/new',
+              lastUpdated: '2026-07-01T00:00:00.000Z'
+            }
+          ]
+        }),
+        settings: [settings({ [pluginId]: true })]
+      }
+    })
+
+    expect(roots[0]?.path).toBe(join('/home/alice/.claude/plugins/cache/compound/new', 'skills'))
+  })
+})
diff --git a/src/main/skills/claude-plugin-skill-sources.ts b/src/main/skills/claude-plugin-skill-sources.ts
new file mode 100644
index 00000000000..1726cfdc9db
--- /dev/null
+++ b/src/main/skills/claude-plugin-skill-sources.ts
@@ -0,0 +1,219 @@
+import { open, stat } from 'node:fs/promises'
+import { basename, isAbsolute, join, relative, sep, type posix } from 'node:path'
+import { stablePathId, type SkillScanRoot } from './skill-discovery-sources'
+import { stripUnsafeDisplayCharacters } from '../../shared/skill-display-text'
+
+const MAX_PLUGIN_METADATA_BYTES = 4 * 1024 * 1024
+
+export type SkillDiscoveryPathApi = Pick<
+  typeof posix,
+  'basename' | 'isAbsolute' | 'join' | 'relative' | 'sep'
+>
+
+export type ClaudePluginMetadata = {
+  installedPlugins: string | null
+  settings: (string | null)[]
+}
+
+type ClaudePluginInstall = {
+  scope: 'user' | 'project' | 'local'
+  installPath: string
+  projectPath?: string
+  installedAt?: string
+  lastUpdated?: string
+}
+
+const defaultPathApi: SkillDiscoveryPathApi = { basename, isAbsolute, join, relative, sep }
+
+export function getClaudePluginMetadataPaths(
+  homeDir: string,
+  cwd: string,
+  pathApi: SkillDiscoveryPathApi = defaultPathApi
+): { installedPlugins: string; settings: string[] } {
+  return {
+    installedPlugins: pathApi.join(homeDir, '.claude', 'plugins', 'installed_plugins.json'),
+    // Claude merges user, project, then project-local settings in this order.
+    settings: [
+      pathApi.join(homeDir, '.claude', 'settings.json'),
+      pathApi.join(cwd, '.claude', 'settings.json'),
+      pathApi.join(cwd, '.claude', 'settings.local.json')
+    ]
+  }
+}
+
+function parseJsonObject(content: string | null): Record<string, unknown> | null {
+  if (!content) {
+    return null
+  }
+  try {
+    const parsed: unknown = JSON.parse(content)
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null
+  } catch {
+    return null
+  }
+}
+
+function readEnabledPlugins(settingsContents: readonly (string | null)[]): Map<string, boolean> {
+  const enabled = new Map<string, boolean>()
+  for (const content of settingsContents) {
+    const settings = parseJsonObject(content)
+    const configured = settings?.enabledPlugins
+    if (!configured || typeof configured !== 'object' || Array.isArray(configured)) {
+      continue
+    }
+    for (const [pluginId, value] of Object.entries(configured)) {
+      if (typeof value === 'boolean') {
+        enabled.set(pluginId, value)
+      }
+    }
+  }
+  return enabled
+}
+
+function parseInstall(value: unknown): ClaudePluginInstall | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null
+  }
+  const record = value as Record<string, unknown>
+  if (
+    (record.scope !== 'user' && record.scope !== 'project' && record.scope !== 'local') ||
+    typeof record.installPath !== 'string'
+  ) {
+    return null
+  }
+  return {
+    scope: record.scope,
+    installPath: record.installPath,
+    ...(typeof record.projectPath === 'string' ? { projectPath: record.projectPath } : {}),
+    ...(typeof record.installedAt === 'string' ? { installedAt: record.installedAt } : {}),
+    ...(typeof record.lastUpdated === 'string' ? { lastUpdated: record.lastUpdated } : {})
+  }
+}
+
+function isProjectInstallApplicable(
+  install: ClaudePluginInstall,
+  cwd: string,
+  pathApi: SkillDiscoveryPathApi
+): boolean {
+  if (install.scope === 'user') {
+    return true
+  }
+  if (!install.projectPath || !pathApi.isAbsolute(install.projectPath)) {
+    return false
+  }
+  const relativePath = pathApi.relative(install.projectPath, cwd)
+  return (
+    relativePath === '' ||
+    (relativePath !== '..' &&
+      !relativePath.startsWith(`..${pathApi.sep}`) &&
+      !pathApi.isAbsolute(relativePath))
+  )
+}
+
+function installPriority(install: ClaudePluginInstall): number {
+  return install.scope === 'local' ? 2 : install.scope === 'project' ? 1 : 0
+}
+
+function installTimestamp(install: ClaudePluginInstall): number {
+  const timestamp = Date.parse(install.lastUpdated ?? install.installedAt ?? '')
+  return Number.isFinite(timestamp) ? timestamp : 0
+}
+
+function selectActiveInstall(
+  values: unknown[],
+  cwd: string,
+  pathApi: SkillDiscoveryPathApi
+): ClaudePluginInstall | null {
+  return (
+    values
+      .map(parseInstall)
+      .filter((install): install is ClaudePluginInstall => install !== null)
+      .filter(
+        (install) =>
+          pathApi.isAbsolute(install.installPath) &&
+          isProjectInstallApplicable(install, cwd, pathApi)
+      )
+      .sort(
+        (a, b) =>
+          installPriority(b) - installPriority(a) ||
+          (b.projectPath?.length ?? 0) - (a.projectPath?.length ?? 0) ||
+          installTimestamp(b) - installTimestamp(a)
+      )[0] ?? null
+  )
+}
+
+function safePluginLabel(pluginId: string, pathApi: SkillDiscoveryPathApi): string {
+  const packageName = pluginId.split('@')[0] || pathApi.basename(pluginId)
+  const safeLabel = stripUnsafeDisplayCharacters(packageName).slice(0, 80)
+  return safeLabel || 'plugin'
+}
+
+export function resolveClaudePluginSkillSources(args: {
+  metadata: ClaudePluginMetadata
+  cwd: string
+  pathApi?: SkillDiscoveryPathApi
+}): SkillScanRoot[] {
+  const pathApi = args.pathApi ?? defaultPathApi
+  const installed = parseJsonObject(args.metadata.installedPlugins)?.plugins
+  if (!installed || typeof installed !== 'object' || Array.isArray(installed)) {
+    return []
+  }
+  const enabled = readEnabledPlugins(args.metadata.settings)
+  const roots = new Map<string, SkillScanRoot>()
+  for (const [pluginId, rawInstalls] of Object.entries(installed)) {
+    if (enabled.get(pluginId) !== true || !Array.isArray(rawInstalls)) {
+      continue
+    }
+    const install = selectActiveInstall(rawInstalls, args.cwd, pathApi)
+    if (!install) {
+      continue
+    }
+    const skillsPath = pathApi.join(install.installPath, 'skills')
+    if (!roots.has(skillsPath)) {
+      roots.set(skillsPath, {
+        id: `claude-plugin-${stablePathId(skillsPath)}`,
+        label: `Claude plugin ${safePluginLabel(pluginId, pathApi)}`,
+        path: skillsPath,
+        sourceKind: 'plugin',
+        providers: ['claude'],
+        owner: 'claude'
+      })
+    }
+  }
+  return [...roots.values()]
+}
+
+async function readMetadataFile(pathValue: string): Promise<string | null> {
+  try {
+    const fileStat = await stat(pathValue)
+    if (!fileStat.isFile() || fileStat.size > MAX_PLUGIN_METADATA_BYTES) {
+      return null
+    }
+    const file = await open(pathValue, 'r')
+    try {
+      const buffer = Buffer.alloc(fileStat.size)
+      const { bytesRead } = await file.read(buffer, 0, buffer.length, 0)
+      return buffer.toString('utf8', 0, bytesRead)
+    } finally {
+      await file.close()
+    }
+  } catch {
+    return null
+  }
+}
+
+export async function discoverClaudePluginSkillSources(args: {
+  homeDir: string
+  cwd: string
+}): Promise<SkillScanRoot[]> {
+  const paths = getClaudePluginMetadataPaths(args.homeDir, args.cwd)
+  const [installedPlugins, ...settings] = await Promise.all(
+    [paths.installedPlugins, ...paths.settings].map(readMetadataFile)
+  )
+  return resolveClaudePluginSkillSources({
+    metadata: { installedPlugins, settings },
+    cwd: args.cwd
+  })
+}
diff --git a/src/main/skills/discovery.test.ts b/src/main/skills/discovery.test.ts
index d65f30dc391..a5d113aebe9 100644
--- a/src/main/skills/discovery.test.ts
+++ b/src/main/skills/discovery.test.ts
@@ -45,6 +45,90 @@ describe('skill discovery', () => {
     expect(result.skills.find((skill) => skill.name === 'Docs')?.providers).toEqual(['claude'])
   })
 
+  it('discovers the enabled Claude plugin version applicable to the project cwd', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'orca-skills-'))
+    const home = join(root, 'home')
+    const project = join(root, 'project')
+    const cwd = join(project, 'worktree')
+    const userInstall = join(home, '.claude', 'plugins', 'cache', 'compound', '3.13.1')
+    const projectInstall = join(home, '.claude', 'plugins', 'cache', 'compound', '3.14.3')
+    const pluginId = 'compound-engineering@compound-engineering-plugin'
+    await mkdir(join(userInstall, 'skills', 'old-plan'), { recursive: true })
+    await mkdir(join(projectInstall, 'skills', 'ce-plan'), { recursive: true })
+    await mkdir(join(home, '.claude', 'plugins'), { recursive: true })
+    await mkdir(cwd, { recursive: true })
+    await writeFile(join(userInstall, 'skills', 'old-plan', 'SKILL.md'), '# old-plan')
+    await writeFile(
+      join(projectInstall, 'skills', 'ce-plan', 'SKILL.md'),
+      '---\nname: ce-plan\ndescription: Create structured plans.\n---\n'
+    )
+    await writeFile(
+      join(home, '.claude', 'plugins', 'installed_plugins.json'),
+      JSON.stringify({
+        plugins: {
+          [pluginId]: [
+            { scope: 'user', installPath: userInstall },
+            { scope: 'project', projectPath: project, installPath: projectInstall }
+          ]
+        }
+      })
+    )
+    await writeFile(
+      join(home, '.claude', 'settings.json'),
+      JSON.stringify({ enabledPlugins: { [pluginId]: true } })
+    )
+
+    const result = await discoverSkills({ homeDir: home, cwd, repos: [] })
+
+    expect(result.skills.map((skill) => skill.name)).toContain('ce-plan')
+    expect(result.skills.map((skill) => skill.name)).not.toContain('old-plan')
+    const pluginSource = result.sources.find(
+      (source) => source.path === join(projectInstall, 'skills')
+    )
+    expect(pluginSource).toMatchObject({ sourceKind: 'plugin', owner: 'claude', exists: true })
+  })
+
+  it('skips Claude plugin discovery when no explicit cwd targets the scan (Settings shape)', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'orca-skills-'))
+    const home = join(root, 'home')
+    const install = join(home, '.claude', 'plugins', 'cache', 'compound', '3.14.3')
+    const pluginId = 'compound-engineering@compound-engineering-plugin'
+    await mkdir(join(install, 'skills', 'ce-plan'), { recursive: true })
+    await writeFile(join(install, 'skills', 'ce-plan', 'SKILL.md'), '# ce-plan')
+    await writeFile(
+      join(home, '.claude', 'plugins', 'installed_plugins.json'),
+      JSON.stringify({ plugins: { [pluginId]: [{ scope: 'user', installPath: install }] } })
+    )
+    await writeFile(
+      join(home, '.claude', 'settings.json'),
+      JSON.stringify({ enabledPlugins: { [pluginId]: true } })
+    )
+
+    const result = await discoverSkills({ homeDir: home, repos: [], includeCwd: false })
+
+    expect(result.skills.map((skill) => skill.name)).not.toContain('ce-plan')
+    expect(result.sources.some((source) => source.id.startsWith('claude-plugin'))).toBe(false)
+  })
+
+  it('records every contributing root when symlinked roots dedup to one skill', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'orca-skills-'))
+    const home = join(root, 'home')
+    const codexSkills = join(home, '.codex', 'skills')
+    await mkdir(join(codexSkills, 'review'), { recursive: true })
+    await writeFile(join(codexSkills, 'review', 'SKILL.md'), '# review')
+    await mkdir(join(home, '.agents'), { recursive: true })
+    // Shared root is a symlink onto the Codex root: one canonical file, two roots.
+    await symlink(codexSkills, join(home, '.agents', 'skills'), 'dir')
+
+    const result = await discoverSkills({ homeDir: home, repos: [], includeCwd: false })
+
+    const reviews = result.skills.filter((skill) => skill.name === 'review')
+    expect(reviews).toHaveLength(1)
+    expect(reviews[0].rootPaths?.slice().sort()).toEqual(
+      [codexSkills, join(home, '.agents', 'skills')].sort()
+    )
+  })
+
   it('does not add SSH-backed repository paths to local scan roots', () => {
     const roots = buildSkillDiscoverySources({
       homeDir: '/home/test',
diff --git a/src/main/skills/discovery.ts b/src/main/skills/discovery.ts
index ed74ef3ffa6..00edfc8e705 100644
--- a/src/main/skills/discovery.ts
+++ b/src/main/skills/discovery.ts
@@ -1,19 +1,23 @@
 import type { Dirent } from 'node:fs'
 import { open, readdir, realpath, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path'
 import { summarizeSkillMarkdown } from '../../shared/skill-metadata'
 import type { Repo } from '../../shared/types'
 import type {
   DiscoveredSkill,
   SkillDiscoveryResult,
-  SkillDiscoverySource,
-  SkillSourceKind
+  SkillDiscoverySource
 } from '../../shared/skills'
 import {
   buildSkillDiscoverySources,
+  compareSkills,
+  sourceKindForSkill,
+  sourceLabelForSkill,
   stablePathId,
   type SkillScanRoot
 } from './skill-discovery-sources'
+import { discoverClaudePluginSkillSources } from './claude-plugin-skill-sources'
 
 export { buildSkillDiscoverySources } from './skill-discovery-sources'
 
@@ -30,14 +34,6 @@ async function pathExists(pathValue: string): Promise<boolean> {
   }
 }
 
-function compareSkills(a: DiscoveredSkill, b: DiscoveredSkill): number {
-  return (
-    a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }) ||
-    a.sourceLabel.localeCompare(b.sourceLabel, undefined, { sensitivity: 'base' }) ||
-    a.skillFilePath.localeCompare(b.skillFilePath)
-  )
-}
-
 function isWithinDepth(rootPath: string, childPath: string, maxDepth: number): boolean {
   const rel = relative(rootPath, childPath)
   if (!rel) {
@@ -50,23 +46,6 @@ function isWithinDepth(rootPath: string, childPath: string, maxDepth: number): b
   return rel.split(sep).length <= maxDepth
 }
 
-function sourceKindForSkill(root: SkillScanRoot, skillFilePath: string): SkillSourceKind {
-  if (
-    root.sourceKind === 'home' &&
-    relative(root.path, skillFilePath).split(sep)[0] === '.system'
-  ) {
-    return 'bundled'
-  }
-  return root.sourceKind
-}
-
-function sourceLabelForSkill(root: SkillScanRoot, sourceKind: SkillSourceKind): string {
-  if (sourceKind === 'bundled') {
-    return `${root.label} bundled`
-  }
-  return root.label
-}
-
 async function findSkillFiles(rootPath: string, maxDepth: number): Promise<string[]> {
   const out: string[] = []
   const visitedDirectoryPaths = new Set<string>()
@@ -182,7 +161,7 @@ async function readSkillSummary(skillFilePath: string): Promise<{
   name: string | null
   description: string | null
   updatedAt: number | null
-}> {
+} | null> {
   try {
     const fileStat = await stat(skillFilePath)
     const file = await open(skillFilePath, 'r')
@@ -199,23 +178,33 @@ async function readSkillSummary(skillFilePath: string): Promise<{
       updatedAt: fileStat.mtimeMs
     }
   } catch {
-    return { name: null, description: null, updatedAt: null }
+    return null
   }
 }
 
-async function scanRoot(root: SkillScanRoot): Promise<DiscoveredSkill[]> {
+type ScannedSkill = DiscoveredSkill & { canonicalSkillFilePath: string }
+
+async function scanRoot(root: SkillScanRoot): Promise<ScannedSkill[]> {
   const maxDepth = root.sourceKind === 'plugin' ? 9 : 4
   const skillFiles = await findSkillFiles(root.path, maxDepth)
   const skills = await Promise.all(
-    skillFiles.map(async (skillFilePath) => {
+    skillFiles.map(async (skillFilePath): Promise<ScannedSkill | null> => {
+      // Why: path identity belongs to the scanning host; canonicalizing before
+      // returning prevents symlinked roots from becoming duplicate picker rows.
+      const canonicalSkillFilePath = await realpath(skillFilePath).catch(() => skillFilePath)
       const directoryPath = dirname(skillFilePath)
       const summary = await readSkillSummary(skillFilePath)
-      const sourceKind = sourceKindForSkill(root, skillFilePath)
+      if (!summary) {
+        return null
+      }
+      const sourceKind = sourceKindForSkill(root, skillFilePath, { relative, sep })
       return {
-        id: stablePathId(skillFilePath),
+        id: stablePathId(canonicalSkillFilePath),
         name: summary.name ?? basename(directoryPath),
         description: summary.description,
-        providers: root.providers,
+        // Copy: `root.providers` is shared across every skill/source from this
+        // root, so the dedup merge below must not mutate the aliased array.
+        providers: [...root.providers],
         sourceKind,
         sourceLabel: sourceLabelForSkill(root, sourceKind),
         rootPath: root.path,
@@ -223,11 +212,12 @@ async function scanRoot(root: SkillScanRoot): Promise<DiscoveredSkill[]> {
         skillFilePath,
         installed: true,
         fileCount: await countFiles(directoryPath),
-        updatedAt: summary.updatedAt
-      } satisfies DiscoveredSkill
+        updatedAt: summary.updatedAt,
+        canonicalSkillFilePath
+      } satisfies ScannedSkill
     })
   )
-  return skills
+  return skills.filter((skill): skill is ScannedSkill => skill !== null)
 }
 
 export async function discoverSkills(args: {
@@ -236,12 +226,25 @@ export async function discoverSkills(args: {
   cwd?: string
   includeCwd?: boolean
 }): Promise<SkillDiscoveryResult> {
-  const roots = buildSkillDiscoverySources(args)
+  const homeDir = args.homeDir ?? homedir()
+  const roots = [
+    ...buildSkillDiscoverySources({ ...args, homeDir }),
+    // Why: plugin discovery is native-chat data keyed to an explicit workspace.
+    // Untargeted scans (Settings) keep their pre-picker inventory and cost.
+    ...(args.cwd && args.includeCwd !== false
+      ? await discoverClaudePluginSkillSources({ homeDir, cwd: args.cwd })
+      : [])
+  ]
   const sources: SkillDiscoverySource[] = []
   const skillGroups = await Promise.all(
     roots.map(async (root) => {
       const exists = await pathExists(root.path)
-      sources.push({ ...root, exists, skippedReason: exists ? undefined : 'missing' })
+      sources.push({
+        ...root,
+        providers: [...root.providers],
+        exists,
+        skippedReason: exists ? undefined : 'missing'
+      })
       if (!exists) {
         return []
       }
@@ -250,11 +253,30 @@ export async function discoverSkills(args: {
   )
   const seen = new Map<string, DiscoveredSkill>()
   for (const skill of skillGroups.flat()) {
-    // Why: WSL discovery sets cwd to the WSL home, so home skills can also be
-    // reached through the synthetic repo root. Keep the global home identity.
-    if (!seen.has(skill.skillFilePath)) {
-      seen.set(skill.skillFilePath, skill)
+    // Why: overlapping repo/cwd roots and symlinked provider homes can reach
+    // the same file. Keep the first source's higher-level scope identity, but
+    // record every contributing root so per-agent visibility survives dedup.
+    const existing = seen.get(skill.canonicalSkillFilePath)
+    if (existing) {
+      if (existing.rootPaths && !existing.rootPaths.includes(skill.rootPath)) {
+        existing.rootPaths.push(skill.rootPath)
+      }
+      // Why: providers is per-agent visibility just like rootPaths; keeping only
+      // the first root's tags makes a shared/symlinked skill under-report which
+      // agents can see it on the Settings provider badges/filter. Reassign a
+      // fresh array — `providers` aliases the scan root's array, so pushing in
+      // place would mutate the root and every sibling skill/source sharing it.
+      const mergedProviders = [...existing.providers]
+      for (const provider of skill.providers) {
+        if (!mergedProviders.includes(provider)) {
+          mergedProviders.push(provider)
+        }
+      }
+      existing.providers = mergedProviders
+      continue
     }
+    const { canonicalSkillFilePath, ...publicSkill } = skill
+    seen.set(canonicalSkillFilePath, { ...publicSkill, rootPaths: [skill.rootPath] })
   }
   return {
     skills: Array.from(seen.values()).sort(compareSkills),
diff --git a/src/main/skills/skill-discovery-sources.ts b/src/main/skills/skill-discovery-sources.ts
index ba3726f43e0..f17d15e1ef2 100644
--- a/src/main/skills/skill-discovery-sources.ts
+++ b/src/main/skills/skill-discovery-sources.ts
@@ -1,24 +1,63 @@
 import { createHash } from 'node:crypto'
 import { homedir } from 'node:os'
-import { basename, join } from 'node:path'
-import type { SkillDiscoverySource, SkillProvider, SkillSourceKind } from '../../shared/skills'
+import { basename, join, type posix } from 'node:path'
+import type {
+  DiscoveredSkill,
+  SkillDiscoverySource,
+  SkillProvider,
+  SkillSourceKind
+} from '../../shared/skills'
+import type { AgentType } from '../../shared/agent-status-types'
 import type { Repo } from '../../shared/types'
 import { getRepoExecutionHostId, LOCAL_EXECUTION_HOST_ID } from '../../shared/execution-host'
 
 export type SkillScanRoot = Omit<SkillDiscoverySource, 'exists' | 'skippedReason'>
+type SkillDiscoveryPathApi = Pick<typeof posix, 'basename' | 'join'>
 
 export function stablePathId(pathValue: string): string {
   return createHash('sha1').update(pathValue).digest('hex').slice(0, 16)
 }
 
+// Skill classification and ordering are identical for native and WSL discovery;
+// only the path arithmetic differs (node:path vs pathPosix), so both callers
+// share these and pass the matching path adapter.
+type SkillRelativePathApi = { relative: (from: string, to: string) => string; sep: string }
+
+export function sourceKindForSkill(
+  root: SkillScanRoot,
+  skillFilePath: string,
+  pathApi: SkillRelativePathApi
+): SkillSourceKind {
+  if (
+    root.sourceKind === 'home' &&
+    pathApi.relative(root.path, skillFilePath).split(pathApi.sep)[0] === '.system'
+  ) {
+    return 'bundled'
+  }
+  return root.sourceKind
+}
+
+export function sourceLabelForSkill(root: SkillScanRoot, sourceKind: SkillSourceKind): string {
+  return sourceKind === 'bundled' ? `${root.label} bundled` : root.label
+}
+
+export function compareSkills(a: DiscoveredSkill, b: DiscoveredSkill): number {
+  return (
+    a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }) ||
+    a.sourceLabel.localeCompare(b.sourceLabel, undefined, { sensitivity: 'base' }) ||
+    a.skillFilePath.localeCompare(b.skillFilePath)
+  )
+}
+
 function source(
   id: string,
   label: string,
   path: string,
   sourceKind: SkillSourceKind,
-  providers: SkillProvider[]
+  providers: SkillProvider[],
+  owner: AgentType | null
 ): SkillScanRoot {
-  return { id, label, path, sourceKind, providers }
+  return { id, label, path, sourceKind, providers, owner }
 }
 
 export function buildSkillDiscoverySources(
@@ -27,39 +66,95 @@ export function buildSkillDiscoverySources(
     cwd?: string
     repos?: Repo[]
     includeCwd?: boolean
+    pathApi?: SkillDiscoveryPathApi
   } = {}
 ): SkillScanRoot[] {
+  const pathApi = args.pathApi ?? { basename, join }
   const home = args.homeDir ?? homedir()
   const cwd = args.cwd ?? process.cwd()
   const roots: SkillScanRoot[] = [
-    source('home-codex', 'Codex home', join(home, '.codex', 'skills'), 'home', ['codex']),
-    source('home-agents', 'Agent skills home', join(home, '.agents', 'skills'), 'home', [
-      'agent-skills'
-    ]),
-    source('home-claude', 'Claude home', join(home, '.claude', 'skills'), 'home', ['claude']),
+    source(
+      'home-codex',
+      'Codex home',
+      pathApi.join(home, '.codex', 'skills'),
+      'home',
+      ['codex'],
+      'codex'
+    ),
+    source(
+      'home-agents',
+      'Agent skills home',
+      pathApi.join(home, '.agents', 'skills'),
+      'home',
+      ['agent-skills'],
+      null
+    ),
+    source(
+      'home-claude',
+      'Claude home',
+      pathApi.join(home, '.claude', 'skills'),
+      'home',
+      ['claude'],
+      'claude'
+    ),
     source(
       'codex-plugin-cache',
       'Codex plugin cache',
-      join(home, '.codex', 'plugins', 'cache'),
+      pathApi.join(home, '.codex', 'plugins', 'cache'),
       'plugin',
-      ['codex', 'agent-skills']
+      ['codex', 'agent-skills'],
+      'codex'
     ),
     // Why: `npx skills add --global` writes into each agent's own home skills
     // directory, so coverage misses them unless we scan every provider root.
-    source('home-grok', 'Grok home', join(home, '.grok', 'skills'), 'home', ['agent-skills']),
-    source('home-opencode', 'OpenCode home', join(home, '.config', 'opencode', 'skills'), 'home', [
-      'agent-skills'
-    ]),
-    source('home-pi', 'Pi home', join(home, '.pi', 'agent', 'skills'), 'home', ['agent-skills']),
-    source('home-gemini', 'Gemini home', join(home, '.gemini', 'skills'), 'home', ['agent-skills']),
+    source(
+      'home-grok',
+      'Grok home',
+      pathApi.join(home, '.grok', 'skills'),
+      'home',
+      ['agent-skills'],
+      'grok'
+    ),
+    source(
+      'home-opencode',
+      'OpenCode home',
+      pathApi.join(home, '.config', 'opencode', 'skills'),
+      'home',
+      ['agent-skills'],
+      'opencode'
+    ),
+    source(
+      'home-pi',
+      'Pi home',
+      pathApi.join(home, '.pi', 'agent', 'skills'),
+      'home',
+      ['agent-skills'],
+      'pi'
+    ),
+    source(
+      'home-gemini',
+      'Gemini home',
+      pathApi.join(home, '.gemini', 'skills'),
+      'home',
+      ['agent-skills'],
+      'gemini'
+    ),
     source(
       'home-antigravity',
       'Antigravity home',
-      join(home, '.gemini', 'antigravity', 'skills'),
+      pathApi.join(home, '.gemini', 'antigravity', 'skills'),
       'home',
-      ['agent-skills']
+      ['agent-skills'],
+      'antigravity'
     ),
-    source('home-cursor', 'Cursor home', join(home, '.cursor', 'skills'), 'home', ['agent-skills'])
+    source(
+      'home-cursor',
+      'Cursor home',
+      pathApi.join(home, '.cursor', 'skills'),
+      'home',
+      ['agent-skills'],
+      'cursor'
+    )
   ]
 
   const projectPaths = new Set<string>()
@@ -76,21 +171,23 @@ export function buildSkillDiscoverySources(
   }
 
   for (const repoPath of projectPaths) {
-    const label = `Repo ${basename(repoPath)}`
+    const label = `Repo ${pathApi.basename(repoPath)}`
     roots.push(
       source(
         `repo-agents-${stablePathId(repoPath)}`,
         `${label} .agents`,
-        join(repoPath, '.agents', 'skills'),
+        pathApi.join(repoPath, '.agents', 'skills'),
         'repo',
-        ['agent-skills']
+        ['agent-skills'],
+        null
       ),
       source(
         `repo-claude-${stablePathId(repoPath)}`,
         `${label} .claude`,
-        join(repoPath, '.claude', 'skills'),
+        pathApi.join(repoPath, '.claude', 'skills'),
         'repo',
-        ['claude']
+        ['claude'],
+        'claude'
       )
     )
   }
diff --git a/src/main/skills/skill-discovery-target.ts b/src/main/skills/skill-discovery-target.ts
new file mode 100644
index 00000000000..2be10232c8c
--- /dev/null
+++ b/src/main/skills/skill-discovery-target.ts
@@ -0,0 +1,70 @@
+import type { Repo } from '../../shared/types'
+import type { SkillDiscoveryResult, SkillDiscoveryTarget } from '../../shared/skills'
+import { getDefaultWslDistro, getWslHome, parseWslPath, toLinuxPath } from '../wsl'
+import { discoverSkills } from './discovery'
+import { discoverSkillsInWsl } from './skill-discovery-wsl'
+
+export type ResolvedSkillDiscoveryTarget =
+  | { kind: 'native-host'; cwd: string | undefined }
+  | { kind: 'wsl'; distro: string; homeDir: string; cwd: string }
+
+export function resolveSkillDiscoveryTarget(
+  target: SkillDiscoveryTarget | undefined
+): ResolvedSkillDiscoveryTarget {
+  const projectRuntime = target?.projectRuntime
+  if (projectRuntime?.status === 'repair-required') {
+    throw new Error(
+      `Project runtime requires repair before skill discovery: ${projectRuntime.repair.reason}`
+    )
+  }
+
+  const wslRequested =
+    (projectRuntime?.status === 'resolved' && projectRuntime.runtime.kind === 'wsl') ||
+    (!projectRuntime && target?.runtime === 'wsl')
+  const wslDistro =
+    projectRuntime?.status === 'resolved' && projectRuntime.runtime.kind === 'wsl'
+      ? projectRuntime.runtime.distro
+      : !projectRuntime && target?.runtime === 'wsl'
+        ? target.wslDistro?.trim() || getDefaultWslDistro()
+        : null
+  if (wslRequested && !wslDistro) {
+    throw new Error('No WSL distribution is available for skill discovery.')
+  }
+  if (!wslDistro) {
+    return { kind: 'native-host', cwd: target?.cwd?.trim() || undefined }
+  }
+  if (process.platform !== 'win32') {
+    throw new Error('WSL skill discovery is only available on Windows.')
+  }
+  const homeDir = getWslHome(wslDistro)
+  if (!homeDir) {
+    throw new Error(`Could not resolve the WSL home directory for ${wslDistro}.`)
+  }
+
+  const requestedCwd = target?.cwd?.trim()
+  const parsedCwd = requestedCwd ? parseWslPath(requestedCwd) : null
+  if (parsedCwd && parsedCwd.distro.toLowerCase() !== wslDistro.toLowerCase()) {
+    throw new Error(
+      `The workspace belongs to WSL distribution ${parsedCwd.distro}, not ${wslDistro}.`
+    )
+  }
+  const linuxHomeDir = toLinuxPath(homeDir)
+  const cwd = parsedCwd?.linuxPath ?? (requestedCwd ? toLinuxPath(requestedCwd) : linuxHomeDir)
+  return { kind: 'wsl', distro: wslDistro, homeDir: linuxHomeDir, cwd }
+}
+
+export async function discoverSkillsOnTarget(
+  target: ResolvedSkillDiscoveryTarget,
+  repos: readonly Repo[]
+): Promise<SkillDiscoveryResult> {
+  if (target.kind === 'wsl') {
+    return discoverSkillsInWsl({
+      distro: target.distro,
+      homeDir: target.homeDir,
+      cwd: target.cwd
+    })
+  }
+  return target.cwd
+    ? discoverSkills({ repos: [], cwd: target.cwd })
+    : discoverSkills({ repos: [...repos] })
+}
diff --git a/src/main/skills/skill-discovery-wsl-plugins.test.ts b/src/main/skills/skill-discovery-wsl-plugins.test.ts
new file mode 100644
index 00000000000..fcb48befa33
--- /dev/null
+++ b/src/main/skills/skill-discovery-wsl-plugins.test.ts
@@ -0,0 +1,83 @@
+import { posix as pathPosix } from 'node:path'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const execFileMock = vi.hoisted(() => vi.fn())
+
+vi.mock('node:child_process', () => ({ execFile: execFileMock }))
+
+import { buildSkillDiscoverySources } from './skill-discovery-sources'
+import { discoverSkillsInWsl } from './skill-discovery-wsl'
+
+function record(...fields: string[]): string {
+  return `${fields.join('\0')}\0`
+}
+
+function completeExecFileCall(callIndex: number, stdout: string): void {
+  const callback = execFileMock.mock.calls[callIndex]?.[3] as
+    | ((error: Error | null, stdout: string) => void)
+    | undefined
+  callback?.(null, stdout)
+}
+
+describe('WSL Claude plugin skill discovery', () => {
+  beforeEach(() => execFileMock.mockReset())
+
+  it('reads enabled plugin metadata and scans the selected install inside the distro', async () => {
+    const homeDir = '/home/alice'
+    const cwd = '/work/orca'
+    const pluginId = 'compound-engineering@compound-engineering-plugin'
+    const installPath = '/home/alice/.claude/plugins/cache/compound/3.14.3'
+    const installed = JSON.stringify({
+      plugins: {
+        [pluginId]: [{ scope: 'project', projectPath: cwd, installPath }]
+      }
+    })
+    const settings = JSON.stringify({ enabledPlugins: { [pluginId]: true } })
+    const metadataOutput = [
+      record('F', '0', '1', Buffer.from(installed).toString('base64')),
+      record('F', '1', '1', Buffer.from(settings).toString('base64')),
+      record('F', '2', '0', ''),
+      record('F', '3', '0', '')
+    ].join('')
+    const baseRootCount = buildSkillDiscoverySources({
+      homeDir,
+      cwd,
+      repos: [],
+      pathApi: pathPosix
+    }).length
+    const skillPath = `${installPath}/skills/ce-plan/SKILL.md`
+    const markdown = Buffer.from('---\nname: ce-plan\ndescription: Plan work.\n---\n').toString(
+      'base64'
+    )
+    const scanOutput = [
+      record('R', String(baseRootCount), '1'),
+      record('S', String(baseRootCount), skillPath, skillPath, '1700000000', '2', markdown)
+    ].join('')
+    execFileMock.mockImplementationOnce((..._args: unknown[]) => {
+      queueMicrotask(() => completeExecFileCall(0, metadataOutput))
+    })
+    execFileMock.mockImplementationOnce((..._args: unknown[]) => {
+      queueMicrotask(() => completeExecFileCall(1, scanOutput))
+    })
+
+    const result = await discoverSkillsInWsl({ distro: 'Ubuntu', homeDir, cwd })
+
+    expect(execFileMock).toHaveBeenCalledTimes(2)
+    const scanArgs = execFileMock.mock.calls[1]?.[1] as string[]
+    const encoded = /printf %s '([^']+)'/.exec(scanArgs[5] ?? '')?.[1]
+    const scanScript = Buffer.from(encoded ?? '', 'base64').toString('utf8')
+    expect(scanScript).toContain(`${installPath}/skills`)
+    expect(result.skills).toEqual([
+      expect.objectContaining({
+        name: 'ce-plan',
+        sourceKind: 'plugin',
+        rootPath: `${installPath}/skills`
+      })
+    ])
+    expect(result.sources).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: `${installPath}/skills`, owner: 'claude', exists: true })
+      ])
+    )
+  })
+})
diff --git a/src/main/skills/skill-discovery-wsl.test.ts b/src/main/skills/skill-discovery-wsl.test.ts
new file mode 100644
index 00000000000..621b9f4c0a3
--- /dev/null
+++ b/src/main/skills/skill-discovery-wsl.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import type { SkillScanRoot } from './skill-discovery-sources'
+import { buildWslSkillDiscoveryCommand, parseWslSkillDiscoveryOutput } from './skill-discovery-wsl'
+
+const homeRoot: SkillScanRoot = {
+  id: 'home-codex',
+  label: 'Codex home',
+  path: '/home/alice/.codex/skills',
+  sourceKind: 'home',
+  providers: ['codex'],
+  owner: 'codex'
+}
+const repoRoot: SkillScanRoot = {
+  id: 'repo-agents',
+  label: 'Repo project .agents',
+  path: '/work/project/.agents/skills',
+  sourceKind: 'repo',
+  providers: ['agent-skills'],
+  owner: null
+}
+
+function record(...fields: string[]): string {
+  return `${fields.join('\0')}\0`
+}
+
+describe('WSL skill discovery', () => {
+  it('parses distro-native metadata and deduplicates canonical skill paths', () => {
+    const markdown = Buffer.from(
+      '---\nname: Review\ndescription: Review this change\n---\n',
+      'utf8'
+    ).toString('base64')
+    const output = [
+      record('R', '0', '1'),
+      record('R', '1', '0'),
+      record(
+        'S',
+        '0',
+        '/home/alice/.codex/skills/.system/review/SKILL.md',
+        '/opt/orca/review/SKILL.md',
+        '1700000000',
+        '7',
+        markdown
+      ),
+      record(
+        'S',
+        '1',
+        '/work/project/.agents/skills/review/SKILL.md',
+        '/opt/orca/review/SKILL.md',
+        '1700000001',
+        '9',
+        markdown
+      )
+    ].join('')
+
+    const result = parseWslSkillDiscoveryOutput(output, [homeRoot, repoRoot], 42)
+
+    expect(result.scannedAt).toBe(42)
+    expect(result.skills).toEqual([
+      expect.objectContaining({
+        name: 'Review',
+        description: 'Review this change',
+        sourceKind: 'bundled',
+        rootPath: homeRoot.path,
+        skillFilePath: '/home/alice/.codex/skills/.system/review/SKILL.md',
+        fileCount: 7,
+        updatedAt: 1_700_000_000_000
+      })
+    ])
+    expect(result.sources).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ id: 'home-codex', exists: true }),
+        expect.objectContaining({ id: 'repo-agents', exists: false, skippedReason: 'missing' })
+      ])
+    )
+  })
+
+  it('builds a distro-side scan for enumeration, reads, and canonical identity', () => {
+    const command = buildWslSkillDiscoveryCommand([
+      { ...repoRoot, path: "/work/alice's project/.agents/skills" }
+    ])
+    const encoded = /printf %s '([^']+)'/.exec(command)?.[1]
+    expect(encoded).toBeTruthy()
+    const script = Buffer.from(encoded!, 'base64').toString('utf8')
+
+    expect(script).toContain('find -L "$root_path"')
+    expect(script).toContain('realpath -- "$skill_file"')
+    expect(script).toContain('head -c 262144 -- "$skill_file"')
+    expect(script).toContain(`'/work/alice'\\''s project/.agents/skills'`)
+  })
+
+  it('rejects malformed host responses instead of reporting an empty scan', () => {
+    expect(() => parseWslSkillDiscoveryOutput(record('S', '9'), [homeRoot])).toThrow(
+      'unknown source'
+    )
+  })
+})
diff --git a/src/main/skills/skill-discovery-wsl.ts b/src/main/skills/skill-discovery-wsl.ts
new file mode 100644
index 00000000000..c4f553225ae
--- /dev/null
+++ b/src/main/skills/skill-discovery-wsl.ts
@@ -0,0 +1,212 @@
+import { execFile } from 'node:child_process'
+import { posix as pathPosix } from 'node:path'
+import { summarizeSkillMarkdown } from '../../shared/skill-metadata'
+import type {
+  DiscoveredSkill,
+  SkillDiscoveryResult,
+  SkillDiscoverySource
+} from '../../shared/skills'
+import { buildEncodedWslBashCommand, quoteBashString } from '../wsl-bash-command'
+import {
+  buildSkillDiscoverySources,
+  compareSkills,
+  sourceKindForSkill,
+  sourceLabelForSkill,
+  stablePathId,
+  type SkillScanRoot
+} from './skill-discovery-sources'
+import { discoverClaudePluginSkillSourcesInWsl } from './claude-plugin-skill-sources-wsl'
+
+const MAX_MARKDOWN_BYTES = 256 * 1024
+const MAX_PACKAGE_FILES = 200
+const WSL_SCAN_TIMEOUT_MS = 10_000
+const WSL_SCAN_MAX_BUFFER_BYTES = 128 * 1024 * 1024
+
+export function buildWslSkillDiscoveryCommand(roots: readonly SkillScanRoot[]): string {
+  const lines = [
+    'set -u',
+    'set -o pipefail',
+    'scan_root() {',
+    '  root_index=$1',
+    '  root_path=$2',
+    '  max_depth=$3',
+    '  if [ ! -d "$root_path" ]; then',
+    `    printf '%s\\0%s\\0%s\\0' R "$root_index" 0`,
+    '    return',
+    '  fi',
+    `  printf '%s\\0%s\\0%s\\0' R "$root_index" 1`,
+    `  while IFS= read -r -d '' skill_file; do`,
+    `    canonical_path=$(realpath -- "$skill_file" 2>/dev/null || printf '%s' "$skill_file")`,
+    `    directory_path=\${skill_file%/*}`,
+    `    updated_at=$(stat -c '%Y' -- "$skill_file" 2>/dev/null || true)`,
+    `    encoded_markdown=$(head -c ${MAX_MARKDOWN_BYTES} -- "$skill_file" 2>/dev/null | base64 | tr -d '\\n') || continue`,
+    '    file_count=0',
+    `    while IFS= read -r -d '' package_file; do`,
+    '      file_count=$((file_count + 1))',
+    `      [ "$file_count" -ge ${MAX_PACKAGE_FILES} ] && break`,
+    `    done < <(find -L "$directory_path" -type f -print0 2>/dev/null)`,
+    `    printf '%s\\0%s\\0%s\\0%s\\0%s\\0%s\\0' S "$root_index" "$skill_file" "$canonical_path" "$updated_at" "$file_count"`,
+    `    printf '%s' "$encoded_markdown"`,
+    `    printf '\\0'`,
+    `  done < <(find -L "$root_path" -mindepth 1 -maxdepth "$max_depth" -type f -name 'SKILL.md' -print0 2>/dev/null)`,
+    '}'
+  ]
+  roots.forEach((root, index) => {
+    const maxDepth = root.sourceKind === 'plugin' ? 10 : 5
+    lines.push(`scan_root ${index} ${quoteBashString(root.path)} ${maxDepth}`)
+  })
+  return buildEncodedWslBashCommand(lines.join('\n'))
+}
+
+function executeWslSkillDiscovery(distro: string, command: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      'wsl.exe',
+      ['-d', distro, '--', 'bash', '-c', command],
+      {
+        encoding: 'utf8',
+        maxBuffer: WSL_SCAN_MAX_BUFFER_BYTES,
+        timeout: WSL_SCAN_TIMEOUT_MS,
+        windowsHide: true
+      },
+      (error, stdout) => {
+        if (error) {
+          reject(error)
+          return
+        }
+        resolve(stdout)
+      }
+    )
+  })
+}
+
+function readProtocolField(fields: string[], index: number): string {
+  const value = fields[index]
+  if (value === undefined) {
+    throw new Error('WSL skill discovery returned an incomplete response.')
+  }
+  return value
+}
+
+export function parseWslSkillDiscoveryOutput(
+  output: string,
+  roots: readonly SkillScanRoot[],
+  scannedAt = Date.now()
+): SkillDiscoveryResult {
+  const fields = output.split('\0')
+  const rootExists = new Map<number, boolean>()
+  const skillsByCanonicalPath = new Map<string, DiscoveredSkill>()
+  let index = 0
+  while (index < fields.length && fields[index]) {
+    const recordKind = fields[index++]
+    const rootIndex = Number.parseInt(readProtocolField(fields, index++), 10)
+    const root = roots[rootIndex]
+    if (!root) {
+      throw new Error('WSL skill discovery returned an unknown source.')
+    }
+    if (recordKind === 'R') {
+      rootExists.set(rootIndex, readProtocolField(fields, index++) === '1')
+      continue
+    }
+    if (recordKind !== 'S') {
+      throw new Error('WSL skill discovery returned an invalid response.')
+    }
+
+    const skillFilePath = readProtocolField(fields, index++)
+    const canonicalSkillFilePath = readProtocolField(fields, index++)
+    const updatedAtSeconds = Number.parseInt(readProtocolField(fields, index++), 10)
+    const fileCount = Number.parseInt(readProtocolField(fields, index++), 10)
+    const markdown = Buffer.from(readProtocolField(fields, index++), 'base64').toString('utf8')
+    const existing = skillsByCanonicalPath.get(canonicalSkillFilePath)
+    if (existing) {
+      // Why: dedup keeps one row, but every contributing root must survive so
+      // per-agent visibility does not depend on root scan order. providers is
+      // per-agent visibility too, so union it rather than keeping only the first.
+      if (existing.rootPaths && !existing.rootPaths.includes(root.path)) {
+        existing.rootPaths.push(root.path)
+      }
+      // Reassign a fresh array — `providers` aliases the scan root's array, so
+      // pushing in place would mutate the root and sibling skills/sources.
+      const mergedProviders = [...existing.providers]
+      for (const provider of root.providers) {
+        if (!mergedProviders.includes(provider)) {
+          mergedProviders.push(provider)
+        }
+      }
+      existing.providers = mergedProviders
+      continue
+    }
+    const directoryPath = pathPosix.dirname(skillFilePath)
+    const summary = summarizeSkillMarkdown(markdown)
+    const sourceKind = sourceKindForSkill(root, skillFilePath, pathPosix)
+    skillsByCanonicalPath.set(canonicalSkillFilePath, {
+      id: stablePathId(canonicalSkillFilePath),
+      name: summary.name ?? pathPosix.basename(directoryPath),
+      description: summary.description,
+      // Copy: `root.providers` is shared across every skill/source from this
+      // root, so a later in-place merge must not mutate the aliased array.
+      providers: [...root.providers],
+      sourceKind,
+      sourceLabel: sourceLabelForSkill(root, sourceKind),
+      rootPath: root.path,
+      rootPaths: [root.path],
+      directoryPath,
+      skillFilePath,
+      installed: true,
+      fileCount: Number.isFinite(fileCount) ? fileCount : 0,
+      updatedAt: Number.isFinite(updatedAtSeconds) ? updatedAtSeconds * 1000 : null
+    })
+  }
+
+  const sources: SkillDiscoverySource[] = roots.map((root, rootIndex) => {
+    const exists = rootExists.get(rootIndex) ?? false
+    return {
+      ...root,
+      providers: [...root.providers],
+      exists,
+      skippedReason: exists ? undefined : 'missing'
+    }
+  })
+  return {
+    skills: [...skillsByCanonicalPath.values()].sort(compareSkills),
+    sources: sources.sort((a, b) =>
+      a.label.localeCompare(b.label, undefined, { sensitivity: 'base' })
+    ),
+    scannedAt
+  }
+}
+
+export async function discoverSkillsInWsl(args: {
+  distro: string
+  homeDir: string
+  cwd: string
+}): Promise<SkillDiscoveryResult> {
+  // Plugin roots are resolved (in JS) from metadata this first wsl.exe call
+  // reads, then fed to the scan's own wsl.exe call below — two sequential
+  // process boots. That is a deliberate one-time-per-pane cost (the renderer
+  // caches per pane); folding both into one invocation would require porting
+  // the plugin-install resolution into bash, which is not worth the risk.
+  //
+  // Why: plugin-metadata enrichment is optional. A failed/timed-out read must
+  // degrade to zero plugin roots (matching the native readMetadataFile path),
+  // not abort the mandatory native/home/repo/bundled scan.
+  let pluginRoots: SkillScanRoot[] = []
+  try {
+    pluginRoots = await discoverClaudePluginSkillSourcesInWsl(args)
+  } catch {
+    pluginRoots = []
+  }
+  const roots = [
+    ...buildSkillDiscoverySources({
+      homeDir: args.homeDir,
+      cwd: args.cwd,
+      repos: [],
+      pathApi: pathPosix
+    }),
+    ...pluginRoots
+  ]
+  // Why: UNC traversal applies Windows casing and symlink rules. The distro
+  // must own enumeration, metadata reads, and canonical path identity.
+  const output = await executeWslSkillDiscovery(args.distro, buildWslSkillDiscoveryCommand(roots))
+  return parseWslSkillDiscoveryOutput(output, roots)
+}
diff --git a/src/main/skills/skill-freshness-inventory-limits.test.ts b/src/main/skills/skill-freshness-inventory-limits.test.ts
index c43d137fcd0..b818f968238 100644
--- a/src/main/skills/skill-freshness-inventory-limits.test.ts
+++ b/src/main/skills/skill-freshness-inventory-limits.test.ts
@@ -14,7 +14,8 @@ describe('skill freshness inventory limits', () => {
         label: `Repo ${index}`,
         path: `/repo-${index}/.agents/skills`,
         sourceKind: 'repo',
-        providers: ['agent-skills']
+        providers: ['agent-skills'],
+        owner: null
       })
     )
 
diff --git a/src/main/telemetry/validator.test.ts b/src/main/telemetry/validator.test.ts
index 031df8d208f..15ddfe9d638 100644
--- a/src/main/telemetry/validator.test.ts
+++ b/src/main/telemetry/validator.test.ts
@@ -165,7 +165,7 @@ describe('validate', () => {
     expect(result.ok).toBe(true)
   })
 
-  // ── repo_added.is_git_repo (docs/reference/telemetry-availability.md)
+  // ── repo_added.is_git_repo
   // The git-vs-folder signal moved here from onboarding_completed once project
   // selection left onboarding. Optional so SSH/remote edges can omit it.
 
diff --git a/src/main/wsl-bash-command.ts b/src/main/wsl-bash-command.ts
index ff7426ae6ec..1b561a1182f 100644
--- a/src/main/wsl-bash-command.ts
+++ b/src/main/wsl-bash-command.ts
@@ -1,4 +1,5 @@
-function quoteShell(value: string): string {
+/** Single-quote a value for safe interpolation into a Bash command line. */
+export function quoteBashString(value: string): string {
   return `'${value.replace(/'/g, "'\\''")}'`
 }
 
@@ -6,5 +7,5 @@ export function buildEncodedWslBashCommand(command: string): string {
   // Why: wsl.exe preprocesses `$local_shell_vars` in command arguments before
   // Bash sees them. Base64 keeps validation scripts intact across that boundary.
   const encoded = Buffer.from(command, 'utf8').toString('base64')
-  return `set -o pipefail; printf %s ${quoteShell(encoded)} | base64 -d | bash`
+  return `set -o pipefail; printf %s ${quoteBashString(encoded)} | base64 -d | bash`
 }
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index e5aa341101c..f25cf0f56df 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -1448,7 +1448,7 @@ export type PreloadApi = {
      *  the model snapshot. Never delivered in-band on pty:data. */
     onModelRestoreNeeded: (callback: (event: PtyModelRestoreNeededEvent) => void) => () => void
     /** Batched derived side-effect facts for PTYs whose bytes transit local
-     *  main; see docs/reference/terminal-side-effect-authority.md. */
+     *  main. */
     onSideEffect: (callback: (batch: TerminalSideEffectBatch) => void) => () => void
     /** Title-only replay snapshot for (re)attach; attention facts never replay. */
     getSideEffectSnapshot: (id: string) => Promise<TerminalSideEffectBatch | null>
diff --git a/src/renderer/src/components/native-chat/NativeChatAutocompleteMenus.test.tsx b/src/renderer/src/components/native-chat/NativeChatAutocompleteMenus.test.tsx
new file mode 100644
index 00000000000..74476af1fb2
--- /dev/null
+++ b/src/renderer/src/components/native-chat/NativeChatAutocompleteMenus.test.tsx
@@ -0,0 +1,126 @@
+// @vitest-environment happy-dom
+
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { NativeChatPickerMenu } from './NativeChatAutocompleteMenus'
+import type { ComposerAutocomplete } from './native-chat-composer-state'
+
+function autocomplete(
+  overrides: Partial<Extract<ComposerAutocomplete, { mode: 'slash' }>> = {}
+): Extract<ComposerAutocomplete, { mode: 'slash' }> {
+  return {
+    mode: 'slash',
+    query: '',
+    triggerKey: '/:0',
+    prefix: '/',
+    grouped: true,
+    commandsEnabled: true,
+    skillsEnabled: true,
+    items: [
+      {
+        kind: 'command',
+        id: 'command:clear',
+        name: 'clear',
+        description: 'Clear history',
+        skillCollision: false
+      },
+      {
+        kind: 'skill',
+        id: 'skill:browser',
+        name: 'browser',
+        description: 'Use a browser',
+        sources: [{ sourceKind: 'repo', skillFilePath: '/repo/browser/SKILL.md' }]
+      }
+    ],
+    skillStatus: 'ready',
+    ...overrides
+  }
+}
+
+describe('NativeChatPickerMenu', () => {
+  afterEach(() => cleanup())
+
+  it('renders grouped command and skill options with active-descendant ids', () => {
+    const onChoose = vi.fn()
+    render(
+      <NativeChatPickerMenu
+        autocomplete={autocomplete()}
+        activeIndex={1}
+        listboxId="picker"
+        onChoose={onChoose}
+        onRetry={vi.fn()}
+      />
+    )
+    expect(screen.getByText('Commands')).toBeTruthy()
+    expect(screen.getByText('Skills')).toBeTruthy()
+    expect(screen.getByRole('option', { name: /browser/i }).getAttribute('aria-selected')).toBe(
+      'true'
+    )
+    expect(screen.getByText('Project')).toBeTruthy()
+  })
+
+  it('completes a command on pointer down instead of dispatching it internally', () => {
+    const onChoose = vi.fn()
+    const value = autocomplete()
+    render(
+      <NativeChatPickerMenu
+        autocomplete={value}
+        activeIndex={0}
+        listboxId="picker"
+        onChoose={onChoose}
+        onRetry={vi.fn()}
+      />
+    )
+    fireEvent.pointerDown(screen.getByRole('option', { name: /clear/i }))
+    expect(onChoose).toHaveBeenCalledWith(value.items[0])
+  })
+
+  it('keeps commands selectable while skills load', () => {
+    render(
+      <NativeChatPickerMenu
+        autocomplete={autocomplete({ items: [autocomplete().items[0]], skillStatus: 'loading' })}
+        activeIndex={0}
+        listboxId="picker"
+        onChoose={vi.fn()}
+        onRetry={vi.fn()}
+      />
+    )
+    expect(screen.getByRole('option', { name: /clear/i })).toBeTruthy()
+    expect(screen.getAllByText('Loading skills...')).toHaveLength(2)
+  })
+
+  it('uses command-only empty copy for a picker without skill support', () => {
+    render(
+      <NativeChatPickerMenu
+        autocomplete={autocomplete({
+          grouped: false,
+          items: [],
+          skillsEnabled: false,
+          skillStatus: 'ready'
+        })}
+        activeIndex={0}
+        listboxId="picker"
+        onChoose={vi.fn()}
+        onRetry={vi.fn()}
+      />
+    )
+    expect(screen.getAllByText('No matching commands')).toHaveLength(2)
+  })
+
+  it('announces a successful empty skill result distinctly from loading', () => {
+    render(
+      <NativeChatPickerMenu
+        autocomplete={autocomplete({
+          commandsEnabled: false,
+          items: [],
+          skillStatus: 'ready'
+        })}
+        activeIndex={0}
+        listboxId="picker"
+        onChoose={vi.fn()}
+        onRetry={vi.fn()}
+      />
+    )
+    expect(screen.getAllByText('No matching skills')).toHaveLength(2)
+  })
+})
diff --git a/src/renderer/src/components/native-chat/NativeChatAutocompleteMenus.tsx b/src/renderer/src/components/native-chat/NativeChatAutocompleteMenus.tsx
index f0662c52acd..8357931fb49 100644
--- a/src/renderer/src/components/native-chat/NativeChatAutocompleteMenus.tsx
+++ b/src/renderer/src/components/native-chat/NativeChatAutocompleteMenus.tsx
@@ -1,38 +1,262 @@
-import { useEffect, useRef } from 'react'
+import { memo, useEffect, useRef } from 'react'
+import { Loader2, Package, RotateCcw } from 'lucide-react'
 import { translate } from '@/i18n/i18n'
 import { cn } from '@/lib/utils'
-import type { SlashCommandSuggestion } from './native-chat-composer-state'
-import type { DiscoveredSkill } from '../../../../shared/skills'
+import type { SkillSourceKind } from '../../../../shared/skills'
+import type { ComposerAutocomplete, NativeChatPickerItem } from './native-chat-composer-state'
 
-export function NativeChatSlashMenu({
-  suggestions,
+export const NativeChatPickerMenu = memo(function NativeChatPickerMenu({
+  autocomplete,
   activeIndex,
-  onChoose
+  listboxId,
+  onChoose,
+  onRetry
 }: {
-  suggestions: SlashCommandSuggestion[]
+  autocomplete: Extract<ComposerAutocomplete, { mode: 'slash' | 'skill' }>
   activeIndex: number
-  onChoose: (command: SlashCommandSuggestion) => void
+  listboxId: string
+  onChoose: (item: NativeChatPickerItem) => void
+  onRetry: () => void
 }): React.JSX.Element {
+  const activeItemRef = useRef<HTMLButtonElement | null>(null)
+  const commands = autocomplete.items.filter(
+    (item): item is Extract<NativeChatPickerItem, { kind: 'command' }> => item.kind === 'command'
+  )
+  const skills = autocomplete.items.filter(
+    (item): item is Extract<NativeChatPickerItem, { kind: 'skill' }> => item.kind === 'skill'
+  )
+
+  useEffect(() => {
+    activeItemRef.current?.scrollIntoView({ block: 'nearest' })
+  }, [activeIndex, autocomplete.items])
+
+  const hasSkillStatus =
+    autocomplete.skillStatus === 'loading' || autocomplete.skillStatus === 'error'
+  const showCommandsHeading = autocomplete.grouped && commands.length > 0
+  const showSkillsHeading = autocomplete.grouped && (skills.length > 0 || hasSkillStatus)
+  const noMatches =
+    autocomplete.skillStatus === 'ready' && commands.length === 0 && skills.length === 0
+  const emptyText = noMatches ? getPickerEmptyText(autocomplete) : null
+  const collision = commands.find((item) => item.skillCollision)
+  const duplicate = skills.find((item) => item.sources.length > 1)
+
+  let optionIndex = 0
   return (
-    <div className="absolute bottom-full left-3 right-3 mb-1 overflow-hidden rounded-md border border-border bg-popover shadow-md sm:left-4 sm:right-4">
-      {suggestions.map((command, index) => (
-        <button
-          key={command.name}
-          type="button"
-          onClick={() => onChoose(command)}
-          className={cn(
-            'flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm',
-            index === activeIndex ? 'bg-accent text-accent-foreground' : 'text-foreground'
-          )}
-        >
-          <span className="font-medium">/{command.name}</span>
-          {command.description ? (
-            <span className="truncate text-xs text-muted-foreground">{command.description}</span>
+    <div
+      id={listboxId}
+      role="listbox"
+      className="scrollbar-sleek absolute bottom-full left-0 right-0 z-20 mb-1 max-h-72 overflow-y-auto rounded-lg border border-border bg-popover p-1 text-popover-foreground shadow-[0_10px_24px_rgba(0,0,0,0.18)]"
+    >
+      {showCommandsHeading ? <PickerGroupHeading kind="commands" /> : null}
+      {commands.map((item) => {
+        const index = optionIndex++
+        return (
+          <PickerOption
+            key={item.id}
+            item={item}
+            prefix={autocomplete.prefix}
+            index={index}
+            activeIndex={activeIndex}
+            listboxId={listboxId}
+            activeItemRef={activeItemRef}
+            onChoose={onChoose}
+          />
+        )
+      })}
+      {showSkillsHeading ? <PickerGroupHeading kind="skills" /> : null}
+      {autocomplete.skillStatus === 'loading' ? (
+        <PickerStatus>
+          <Loader2 className="size-3.5 animate-spin" />
+          {translate('components.native-chat.composer.loadingSkills', 'Loading skills...')}
+        </PickerStatus>
+      ) : null}
+      {autocomplete.skillStatus === 'error' ? (
+        <PickerStatus>
+          <span className="min-w-0 flex-1">
+            {autocomplete.skillErrorKind === 'unavailable'
+              ? translate(
+                  'components.native-chat.composer.skillsUnavailableHost',
+                  'Skills are unavailable for this host'
+                )
+              : translate(
+                  'components.native-chat.composer.skillsLoadFailed',
+                  'Could not load skills from this host'
+                )}
+          </span>
+          {autocomplete.skillErrorKind !== 'unavailable' ? (
+            <button
+              type="button"
+              onPointerDown={(event) => event.preventDefault()}
+              onClick={onRetry}
+              className="flex shrink-0 items-center gap-1 rounded-sm px-1.5 py-0.5 text-foreground hover:bg-accent hover:text-accent-foreground"
+            >
+              <RotateCcw className="size-3" />
+              {translate('components.native-chat.composer.retrySkills', 'Retry')}
+            </button>
           ) : null}
-        </button>
-      ))}
+        </PickerStatus>
+      ) : null}
+      {skills.map((item) => {
+        const index = optionIndex++
+        return (
+          <PickerOption
+            key={item.id}
+            item={item}
+            prefix={autocomplete.prefix}
+            index={index}
+            activeIndex={activeIndex}
+            listboxId={listboxId}
+            activeItemRef={activeItemRef}
+            onChoose={onChoose}
+          />
+        )
+      })}
+      {noMatches ? <PickerStatus>{emptyText}</PickerStatus> : null}
+      <div aria-live="polite" className="sr-only">
+        {autocomplete.skillStatus === 'loading'
+          ? translate('components.native-chat.composer.loadingSkills', 'Loading skills...')
+          : autocomplete.skillStatus === 'error'
+            ? translate(
+                'components.native-chat.composer.skillsLoadFailed',
+                'Could not load skills from this host'
+              )
+            : emptyText
+              ? emptyText
+              : autocomplete.skillsEnabled
+                ? [
+                    translate('components.native-chat.composer.skillsLoaded', 'Skills loaded'),
+                    collision
+                      ? getPickerAnnotation(collision)
+                      : duplicate
+                        ? getPickerAnnotation(duplicate)
+                        : null
+                  ]
+                    .filter(Boolean)
+                    .join('. ')
+                : ''}
+      </div>
     </div>
   )
+})
+
+function getPickerEmptyText(
+  autocomplete: Extract<ComposerAutocomplete, { mode: 'slash' | 'skill' }>
+): string {
+  if (autocomplete.mode === 'skill' || !autocomplete.commandsEnabled) {
+    return translate('components.native-chat.composer.noSkills', 'No matching skills')
+  }
+  if (autocomplete.skillsEnabled) {
+    return translate(
+      'components.native-chat.composer.noCommandsOrSkills',
+      'No matching commands or skills'
+    )
+  }
+  return translate('components.native-chat.composer.noCommands', 'No matching commands')
+}
+
+function PickerGroupHeading({ kind }: { kind: 'commands' | 'skills' }): React.JSX.Element {
+  return (
+    <div className="px-2 pb-1 pt-1.5 text-[11px] font-semibold uppercase tracking-[0.05em] text-muted-foreground">
+      {kind === 'commands'
+        ? translate('components.native-chat.composer.commands', 'Commands')
+        : translate('components.native-chat.composer.skills', 'Skills')}
+    </div>
+  )
+}
+
+function PickerStatus({ children }: { children: React.ReactNode }): React.JSX.Element {
+  return (
+    <div className="flex items-center gap-2 px-2 py-1.5 text-xs text-muted-foreground">
+      {children}
+    </div>
+  )
+}
+
+function PickerOption({
+  item,
+  prefix,
+  index,
+  activeIndex,
+  listboxId,
+  activeItemRef,
+  onChoose
+}: {
+  item: NativeChatPickerItem
+  prefix: '/' | '$'
+  index: number
+  activeIndex: number
+  listboxId: string
+  activeItemRef: React.MutableRefObject<HTMLButtonElement | null>
+  onChoose: (item: NativeChatPickerItem) => void
+}): React.JSX.Element {
+  const annotation = getPickerAnnotation(item)
+  const selected = index === activeIndex
+  return (
+    <button
+      id={`${listboxId}-option-${index}`}
+      ref={selected ? activeItemRef : null}
+      role="option"
+      aria-selected={selected}
+      type="button"
+      onPointerDown={(event) => {
+        // Why: the textarea owns query and caret state, so pointer acceptance
+        // must run before the browser transfers focus to this row.
+        event.preventDefault()
+        onChoose(item)
+      }}
+      className={cn(
+        'flex w-full items-start gap-2 rounded-md border border-transparent px-2 py-1.5 text-left text-[13px] hover:bg-accent hover:text-accent-foreground',
+        selected && 'border-border bg-accent text-accent-foreground'
+      )}
+    >
+      {item.kind === 'skill' ? (
+        <Package className="mt-0.5 size-3.5 shrink-0 text-muted-foreground" />
+      ) : null}
+      <span className="min-w-0 flex-1">
+        <span className="block truncate font-mono font-medium">{prefix + item.name}</span>
+        {item.description ? (
+          <span className="block truncate text-xs text-muted-foreground">{item.description}</span>
+        ) : null}
+        {annotation ? (
+          <span className="block truncate text-[11px] text-muted-foreground">{annotation}</span>
+        ) : null}
+      </span>
+      {item.kind === 'skill' ? (
+        <span className="shrink-0 pt-0.5 text-[11px] text-muted-foreground">
+          {scopeLabel(item.sources[0]?.sourceKind)}
+        </span>
+      ) : null}
+    </button>
+  )
+}
+
+function getPickerAnnotation(item: NativeChatPickerItem): string | null {
+  if (item.kind === 'command' && item.skillCollision) {
+    return translate(
+      'components.native-chat.composer.skillCommandCollision',
+      'Also a skill name - agent decides'
+    )
+  }
+  if (item.kind === 'skill' && item.sources.length > 1) {
+    // Why: name the interpolation `sourceCount`, not `count` — a `count` option
+    // makes i18next resolve plural-suffixed keys that these locales don't define.
+    return translate(
+      'components.native-chat.composer.skillMultipleSources',
+      '{{sourceCount}} sources - agent resolves',
+      { sourceCount: item.sources.length }
+    )
+  }
+  return null
+}
+
+function scopeLabel(sourceKind: SkillSourceKind | undefined): string {
+  const labels: Record<string, string> = {
+    repo: translate('components.native-chat.composer.skillScopeProject', 'Project'),
+    home: translate('components.native-chat.composer.skillScopePersonal', 'Personal'),
+    bundled: translate('components.native-chat.composer.skillScopeBuiltIn', 'Built-in'),
+    plugin: translate('components.native-chat.composer.skillScopePlugin', 'Plugin')
+  }
+  return sourceKind ? (labels[sourceKind] ?? '') : ''
 }
 
 export function NativeChatMentionHint({
@@ -45,7 +269,10 @@ export function NativeChatMentionHint({
   return (
     <button
       type="button"
-      onClick={onAccept}
+      onPointerDown={(event) => {
+        event.preventDefault()
+        onAccept()
+      }}
       className="absolute bottom-full left-3 right-3 mb-1 flex w-auto items-center gap-2 rounded-md border border-border bg-popover px-3 py-1.5 text-left text-xs text-muted-foreground shadow-md sm:left-4 sm:right-4"
     >
       {translate('components.native-chat.composer.mentionHint', 'Referencing file:')}{' '}
@@ -53,51 +280,3 @@ export function NativeChatMentionHint({
     </button>
   )
 }
-
-export function NativeChatSkillMenu({
-  suggestions,
-  activeIndex,
-  onChoose
-}: {
-  suggestions: DiscoveredSkill[]
-  activeIndex: number
-  onChoose: (skill: DiscoveredSkill) => void
-}): React.JSX.Element {
-  const activeItemRef = useRef<HTMLButtonElement | null>(null)
-
-  useEffect(() => {
-    activeItemRef.current?.scrollIntoView({ block: 'nearest' })
-  }, [activeIndex, suggestions])
-
-  return (
-    <div className="scrollbar-sleek absolute bottom-full left-0 right-0 mb-1 max-h-64 overflow-y-auto rounded-md border border-border bg-popover p-1 shadow-md">
-      {suggestions.length === 0 ? (
-        <div className="px-2 py-1.5 text-xs text-muted-foreground">
-          {translate('components.native-chat.composer.noSkills', 'No matching skills')}
-        </div>
-      ) : null}
-      {suggestions.map((skill, index) => (
-        <button
-          key={skill.id}
-          ref={index === activeIndex ? activeItemRef : null}
-          type="button"
-          onClick={() => onChoose(skill)}
-          className={cn(
-            'flex w-full items-start gap-2 rounded-sm px-2 py-1.5 text-left text-sm',
-            index === activeIndex ? 'bg-accent text-accent-foreground' : 'text-foreground'
-          )}
-        >
-          <span className="min-w-0 flex-1">
-            <span className="block truncate font-medium">${skill.name}</span>
-            {skill.description ? (
-              <span className="block truncate text-xs text-muted-foreground">
-                {skill.description}
-              </span>
-            ) : null}
-          </span>
-          <span className="shrink-0 text-[11px] text-muted-foreground">{skill.sourceLabel}</span>
-        </button>
-      ))}
-    </div>
-  )
-}
diff --git a/src/renderer/src/components/native-chat/NativeChatComposer.test.tsx b/src/renderer/src/components/native-chat/NativeChatComposer.test.tsx
index 25000521dbc..cb340ee0c13 100644
--- a/src/renderer/src/components/native-chat/NativeChatComposer.test.tsx
+++ b/src/renderer/src/components/native-chat/NativeChatComposer.test.tsx
@@ -6,6 +6,7 @@ import type {
   SessionOptionDescriptor,
   SessionOptionsSurface
 } from '../../../../shared/native-chat-session-options'
+import type * as nativeChatAgentProfiles from '../../../../shared/native-chat-agent-profiles'
 import { clearNativeChatSessionOptionCacheForTests } from './native-chat-session-option-cache'
 
 const mocks = vi.hoisted(() => ({
@@ -63,11 +64,15 @@ vi.mock('./claude-model-switch-confirmation', () => ({
   createClaudeModelSwitchConfirmationObserver: (...args: unknown[]) =>
     mocks.createClaudeModelSwitchConfirmationObserver(...args)
 }))
-vi.mock('./native-chat-agent-commands', () => ({
-  getAgentSlashCommands: () => []
+vi.mock('../../../../shared/native-chat-agent-profiles', async (importOriginal) => ({
+  ...(await importOriginal<typeof nativeChatAgentProfiles>()),
+  getVerifiedNativeChatCommands: () => []
 }))
 vi.mock('@/lib/native-chat-telemetry', () => ({
-  emitNativeChatMessageSent: vi.fn()
+  emitNativeChatMessageSent: vi.fn(),
+  emitNativeChatPickerItemAccepted: vi.fn(),
+  emitNativeChatPickerOpened: vi.fn(),
+  emitNativeChatSendClassified: vi.fn()
 }))
 vi.mock('./use-native-chat-draft', () => ({
   useNativeChatDraft: (scopeKey: string) => {
@@ -84,7 +89,9 @@ vi.mock('./NativeChatComposerField', () => ({
     return null
   }
 }))
-vi.mock('./use-native-chat-skills', () => ({ useNativeChatSkills: () => [] }))
+vi.mock('./use-native-chat-skills', () => ({
+  useNativeChatSkills: () => ({ status: 'ready', skills: [], error: null, retry: () => {} })
+}))
 vi.mock('./use-native-chat-composer-attachments', () => ({
   useNativeChatComposerAttachments: () => ({
     imageAttachments: [],
diff --git a/src/renderer/src/components/native-chat/NativeChatComposer.tsx b/src/renderer/src/components/native-chat/NativeChatComposer.tsx
index e9a6f8f8407..b2c763e6e26 100644
--- a/src/renderer/src/components/native-chat/NativeChatComposer.tsx
+++ b/src/renderer/src/components/native-chat/NativeChatComposer.tsx
@@ -8,19 +8,13 @@ import {
   submitNativeChatPrompt
 } from './native-chat-runtime-send'
 import type { NativeChatSendHandle } from './native-chat-runtime-send'
-import { getAgentSlashCommands } from './native-chat-agent-commands'
+import { getVerifiedNativeChatCommands } from '../../../../shared/native-chat-agent-profiles'
 import { emitNativeChatMessageSent } from '@/lib/native-chat-telemetry'
 import {
   applyMentionSuggestion,
-  applySkillSuggestion,
-  applySlashSuggestion,
-  deriveComposerAutocomplete,
   EMPTY_HISTORY,
-  isSlashCommandDraft,
   pushHistory,
-  slashCommandDispatchText,
-  type HistoryState,
-  type SlashCommandSuggestion
+  type HistoryState
 } from './native-chat-composer-state'
 import { readNativeChatDraftCache } from './native-chat-draft-cache'
 import { useNativeChatDraft } from './use-native-chat-draft'
@@ -29,7 +23,6 @@ import {
   nativeChatComposerTargetIsRemote,
   type NativeChatResolvedTarget
 } from './native-chat-composer-target'
-import { useNativeChatSkills } from './use-native-chat-skills'
 import { useNativeChatComposerAttachments } from './use-native-chat-composer-attachments'
 import { useNativeChatComposerPaste } from './use-native-chat-composer-paste'
 import { useNativeChatExternalAttachments } from './use-native-chat-external-attachments'
@@ -39,6 +32,9 @@ import { useNativeChatSessionOptions } from './use-native-chat-session-options'
 import { useNativeChatFileAttachmentActions } from './use-native-chat-file-attachment-actions'
 import { useNativeChatDictationActions } from './use-native-chat-dictation-actions'
 import { useNativeChatSessionOptionCommand } from './use-native-chat-session-option-command'
+import { useNativeChatPickerState } from './use-native-chat-picker-state'
+import { useNativeChatPickerCommandDispatch } from './use-native-chat-picker-command-dispatch'
+import { useNativeChatTypedInsertion } from './use-native-chat-typed-insertion'
 import type {
   NativeChatComposerHandle,
   NativeChatComposerProps
@@ -92,8 +88,8 @@ export const NativeChatComposer = forwardRef<NativeChatComposerHandle, NativeCha
     const [activeSuggestion, setActiveSuggestion] = useState(0)
     const [notice, setNotice] = useState<string | null>(null)
     const [dictationPressed, setDictationPressed] = useState(false)
-    const skills = useNativeChatSkills(agent, terminalTabId)
     const textareaRef = useRef<HTMLTextAreaElement>(null)
+    const isComposingRef = useRef(false)
     const { cancelPendingSends, trackPendingSend } = useNativeChatSendLifecycle(
       terminalTabId,
       targetPtyId,
@@ -118,12 +114,27 @@ export const NativeChatComposer = forwardRef<NativeChatComposerHandle, NativeCha
       setCaret(readNativeChatDraftCache(draftScopeKey).length)
     }
 
-    const agentCommands = useMemo(() => getAgentSlashCommands(agent), [agent])
-    const autocomplete = useMemo(
-      () =>
-        deriveComposerAutocomplete(draft, caret, agentCommands, agent === 'codex' ? skills : []),
-      [draft, caret, agentCommands, agent, skills]
-    )
+    const agentCommands = useMemo(() => getVerifiedNativeChatCommands(agent), [agent])
+    const picker = useNativeChatPickerState({
+      agent,
+      terminalTabId,
+      draftScopeKey,
+      draft,
+      caret,
+      agentCommands,
+      textareaRef,
+      setDraft,
+      setCaret,
+      setActiveSuggestion
+    })
+    const {
+      autocomplete,
+      classifySend,
+      clearSkillOrigin,
+      completeItem,
+      dismiss,
+      handleDraftOrCaretChange
+    } = picker
 
     // Resolve the live ptyId for this chat leaf; runtime owner settings route
     // local vs remote (SSH) sends.
@@ -134,8 +145,7 @@ export const NativeChatComposer = forwardRef<NativeChatComposerHandle, NativeCha
       return { ptyId: targetPtyId, settings: getSettingsForAgentTabRuntimeOwner(terminalTabId) }
     }, [targetPtyId, terminalTabId])
 
-    const hasPty = targetPtyId !== null
-    const disabled = !hasPty || !canSend
+    const [hasPty, disabled] = [targetPtyId !== null, targetPtyId === null || !canSend]
 
     const syncCaret = useCallback((el: HTMLTextAreaElement) => {
       setCaret(el.selectionStart ?? el.value.length)
@@ -155,37 +165,15 @@ export const NativeChatComposer = forwardRef<NativeChatComposerHandle, NativeCha
       ? !hasPty || !onStop
       : disabled || (draft.trim() === '' && imageAttachments.length === 0)
 
-    const insertTypedText = useCallback(
-      (text: string): boolean => {
-        const textarea = textareaRef.current
-        if (!textarea || textarea.disabled) {
-          return false
-        }
-        const selectionStart = textarea.selectionStart ?? caret
-        const selectionEnd = textarea.selectionEnd ?? selectionStart
-        const next = `${draft.slice(0, selectionStart)}${text}${draft.slice(selectionEnd)}`
-        const nextCaret = selectionStart + text.length
-        textarea.focus()
-        setDraft(next)
-        setCaret(nextCaret)
-        setHistory((prev) => ({ entries: prev.entries, index: null }))
-        setActiveSuggestion(0)
-        requestAnimationFrame(() => {
-          textarea.setSelectionRange(nextCaret, nextCaret)
-        })
-        return true
-      },
-      [caret, draft, setDraft]
-    )
-
-    const focus = useCallback((): boolean => {
-      const textarea = textareaRef.current
-      if (!textarea || textarea.disabled) {
-        return false
-      }
-      textarea.focus()
-      return true
-    }, [])
+    const { insertTypedText, focus } = useNativeChatTypedInsertion({
+      textareaRef,
+      caret,
+      draft,
+      setDraft,
+      setCaret,
+      setHistory,
+      setActiveSuggestion
+    })
 
     const { attachExternalPaths, resolveAttachmentOwner } = useNativeChatExternalAttachments({
       terminalTabId,
@@ -249,14 +237,12 @@ export const NativeChatComposer = forwardRef<NativeChatComposerHandle, NativeCha
       if (!target) {
         return
       }
-      // Slash commands are TUI controls, not chat turns — never attach images to
-      // one (the chat turn is suppressed below, so the images would leak into the
-      // runtime with no visible message). Otherwise images are deferred to submit
-      // (like text) so the GUI chips and TUI input stay in sync and removing a
-      // chip needs no TUI un-paste: send images, then text, then Enter atomically.
-      const isSlashCommand = isSlashCommandDraft(text)
+      const classification = classifySend(text)
       let pendingHandle: NativeChatSendHandle | null = null
-      if (isSlashCommand) {
+      // Why: image attachments take the attachment send path even for a
+      // command/unknown send, otherwise `clearImageAttachments()` below drops
+      // them silently when the text starts with the agent's slash/skill prefix.
+      if (classification !== 'chat' && imagePaths.length === 0) {
         pendingHandle = sendNativeChatMessage(target.settings, target.ptyId, text)
       } else if (imagePaths.length > 0) {
         pendingHandle = sendNativeChatMessageWithImageAttachments(
@@ -270,14 +256,16 @@ export const NativeChatComposer = forwardRef<NativeChatComposerHandle, NativeCha
       } else {
         submitNativeChatPrompt(target.settings, target.ptyId)
       }
-      // Slash commands don't echo a user bubble, but DO surface a small
-      // "Ran /clear" system line so the command leaves a visible trace.
-      if (isSlashCommand) {
+      if (classification !== 'chat') {
         if (pendingHandle) {
           trackPendingSend(pendingHandle)
         }
-        onSlashCommand?.(text.trim())
-        sessionOptionsSurface?.recordOutgoingCommand(text.trim())
+        // Why: only verified catalog commands can truthfully claim they ran or
+        // mutate session-option state; unknown slash-like text has no such proof.
+        if (classification === 'command') {
+          onSlashCommand?.(text.trim())
+          sessionOptionsSurface?.recordOutgoingCommand(text.trim())
+        }
       } else {
         const pendingId = onOptimisticSend?.(text, imagePaths)
         if (pendingHandle) {
@@ -293,10 +281,13 @@ export const NativeChatComposer = forwardRef<NativeChatComposerHandle, NativeCha
       setHistory((prev) => pushHistory(prev, text))
       setDraft('')
       setCaret(0)
+      clearSkillOrigin()
       clearImageAttachments()
       setNotice(null)
     }, [
       agent,
+      classifySend,
+      clearSkillOrigin,
       clearImageAttachments,
       draft,
       imageAttachments,
@@ -323,58 +314,32 @@ export const NativeChatComposer = forwardRef<NativeChatComposerHandle, NativeCha
       sendRuntimePtyInput(target.settings, target.ptyId, ESC)
     }, [cancelPendingSends, isWorking, onStop, resolveTarget])
 
-    const chooseSlash = useCallback(
-      (command: SlashCommandSuggestion) => {
-        const next = applySlashSuggestion(command)
-        setDraft(next)
-        setCaret(next.length)
-        setActiveSuggestion(0)
-        textareaRef.current?.focus()
-      },
-      [setDraft]
-    )
-
-    const dispatchSlash = useCallback(
-      (command: SlashCommandSuggestion) => {
-        const next = slashCommandDispatchText(command)
-        const target = resolveTarget()
-        if (!target || disabled) {
-          return
-        }
-        trackPendingSend(sendNativeChatMessage(target.settings, target.ptyId, next))
-        // Surface the command as a system line (this is the autocomplete-menu
-        // dispatch path; the typed-Enter path in `send` does the same).
-        onSlashCommand?.(next.trim())
-        sessionOptionsSurface?.recordOutgoingCommand(next.trim())
-        emitNativeChatMessageSent({
-          agent,
-          runtime: nativeChatComposerTargetIsRemote(target.ptyId) ? 'remote' : 'local'
-        })
-        setHistory((prev) => pushHistory(prev, next))
-        setDraft('')
-        setCaret(0)
-        setActiveSuggestion(0)
-        setNotice(null)
-      },
-      [
-        agent,
-        disabled,
-        resolveTarget,
-        onSlashCommand,
-        sessionOptionsSurface,
-        setDraft,
-        trackPendingSend
-      ]
-    )
+    const dispatchPickerCommand = useNativeChatPickerCommandDispatch({
+      agent,
+      disabled,
+      isDispatchingSessionOption,
+      resolveTarget,
+      onSlashCommand,
+      sessionOptionsSurface,
+      trackPendingSend,
+      setHistory,
+      setDraft,
+      setCaret,
+      setActiveSuggestion,
+      clearSkillOrigin,
+      clearImageAttachments,
+      setNotice
+    })
 
     const handleKeyDown = useNativeChatComposerKeyDown({
       autocomplete,
       activeSuggestion,
       draft,
-      caret,
       history,
-      chooseSlash,
-      dispatchSlash,
+      isComposing: () => isComposingRef.current,
+      completePickerItem: completeItem,
+      dispatchPickerCommand,
+      dismissPicker: dismiss,
       interrupt,
       send,
       setActiveSuggestion,
@@ -404,12 +369,25 @@ export const NativeChatComposer = forwardRef<NativeChatComposerHandle, NativeCha
           setDraft(value)
           setHistory((prev) => ({ entries: prev.entries, index: null }))
           syncCaret(element)
+          handleDraftOrCaretChange(value, element.selectionStart ?? value.length)
+          setActiveSuggestion(0)
+        }}
+        onTextareaSelect={(element) => {
+          syncCaret(element)
+          handleDraftOrCaretChange(element.value, element.selectionStart ?? element.value.length)
           setActiveSuggestion(0)
         }}
-        onTextareaSelect={syncCaret}
         onKeyDown={handleKeyDown}
+        onCompositionStart={() => {
+          isComposingRef.current = true
+        }}
+        onCompositionEnd={() => {
+          isComposingRef.current = false
+        }}
         onPaste={handlePaste}
-        onChooseSlash={chooseSlash}
+        pickerListboxId={picker.listboxId}
+        onChoosePickerItem={completeItem}
+        onRetrySkills={picker.retrySkills}
         onAcceptMention={() => {
           if (autocomplete.mode !== 'mention') {
             return
@@ -417,14 +395,9 @@ export const NativeChatComposer = forwardRef<NativeChatComposerHandle, NativeCha
           const result = applyMentionSuggestion(draft, caret, autocomplete.query)
           setDraft(result.draft)
           setCaret(result.caret)
-          textareaRef.current?.focus()
-        }}
-        onChooseSkill={(skill) => {
-          const result = applySkillSuggestion(draft, caret, skill.name)
-          setDraft(result.draft)
-          setCaret(result.caret)
-          setActiveSuggestion(0)
-          textareaRef.current?.focus()
+          const textarea = textareaRef.current
+          textarea?.focus()
+          requestAnimationFrame(() => textarea?.setSelectionRange(result.caret, result.caret))
         }}
         onRemoveImageAttachment={(id) => removeImageAttachment(id)}
         onAttach={pickAttachment}
diff --git a/src/renderer/src/components/native-chat/NativeChatComposerField.tsx b/src/renderer/src/components/native-chat/NativeChatComposerField.tsx
index fd76146650b..8da288e3b39 100644
--- a/src/renderer/src/components/native-chat/NativeChatComposerField.tsx
+++ b/src/renderer/src/components/native-chat/NativeChatComposerField.tsx
@@ -1,19 +1,19 @@
-import type { ClipboardEventHandler, KeyboardEventHandler, RefObject } from 'react'
+import type {
+  ClipboardEventHandler,
+  CompositionEventHandler,
+  KeyboardEventHandler,
+  RefObject
+} from 'react'
 import { Image as ImageIcon, ImageOff, X } from 'lucide-react'
 import { translate } from '@/i18n/i18n'
 import { cn } from '@/lib/utils'
 import { NATIVE_FILE_DROP_TARGET } from '../../../../shared/native-file-drop'
 import { basename } from '@/lib/path'
 import { isNativeChatPastedImagePath } from './native-chat-image-paste'
-import type { ComposerAutocomplete, SlashCommandSuggestion } from './native-chat-composer-state'
-import {
-  NativeChatMentionHint,
-  NativeChatSkillMenu,
-  NativeChatSlashMenu
-} from './NativeChatAutocompleteMenus'
+import type { ComposerAutocomplete, NativeChatPickerItem } from './native-chat-composer-state'
+import { NativeChatMentionHint, NativeChatPickerMenu } from './NativeChatAutocompleteMenus'
 import { NativeChatComposerActions } from './NativeChatComposerActions'
 import { nativeChatComposerPlaceholder } from './native-chat-composer-target'
-import type { DiscoveredSkill } from '../../../../shared/skills'
 import type {
   SessionOptionDescriptor,
   SessionOptionsSurface
@@ -38,10 +38,13 @@ export type NativeChatComposerFieldProps = {
   onDraftChange: (value: string, element: HTMLTextAreaElement) => void
   onTextareaSelect: (element: HTMLTextAreaElement) => void
   onKeyDown: KeyboardEventHandler<HTMLTextAreaElement>
+  onCompositionStart: CompositionEventHandler<HTMLTextAreaElement>
+  onCompositionEnd: CompositionEventHandler<HTMLTextAreaElement>
   onPaste: ClipboardEventHandler<HTMLTextAreaElement>
-  onChooseSlash: (command: SlashCommandSuggestion) => void
+  pickerListboxId: string
+  onChoosePickerItem: (item: NativeChatPickerItem) => void
+  onRetrySkills: () => void
   onAcceptMention: () => void
-  onChooseSkill: (skill: DiscoveredSkill) => void
   onRemoveImageAttachment: (id: string) => void
   onAttach: () => void
   onDictationToggle: () => void
@@ -77,10 +80,13 @@ export function NativeChatComposerField({
   onDraftChange,
   onTextareaSelect,
   onKeyDown,
+  onCompositionStart,
+  onCompositionEnd,
   onPaste,
-  onChooseSlash,
+  pickerListboxId,
+  onChoosePickerItem,
+  onRetrySkills,
   onAcceptMention,
-  onChooseSkill,
   onRemoveImageAttachment,
   onAttach,
   onDictationToggle,
@@ -96,23 +102,18 @@ export function NativeChatComposerField({
       {/* Extra bottom padding keeps the input box off the window rim. */}
       <div className="px-3 pt-2 pb-4 sm:px-4">
         <div className="relative mx-auto w-full max-w-4xl">
-          {autocomplete.mode === 'slash' && autocomplete.suggestions.length > 0 ? (
-            <NativeChatSlashMenu
-              suggestions={autocomplete.suggestions}
+          {autocomplete.mode === 'slash' || autocomplete.mode === 'skill' ? (
+            <NativeChatPickerMenu
+              autocomplete={autocomplete}
               activeIndex={activeSuggestion}
-              onChoose={onChooseSlash}
+              listboxId={pickerListboxId}
+              onChoose={onChoosePickerItem}
+              onRetry={onRetrySkills}
             />
           ) : null}
           {autocomplete.mode === 'mention' ? (
             <NativeChatMentionHint query={autocomplete.query} onAccept={onAcceptMention} />
           ) : null}
-          {autocomplete.mode === 'skill' ? (
-            <NativeChatSkillMenu
-              suggestions={autocomplete.suggestions}
-              activeIndex={activeSuggestion}
-              onChoose={onChooseSkill}
-            />
-          ) : null}
           {notice ? (
             <div className="mb-1.5 flex items-center gap-1.5 text-xs text-muted-foreground">
               <ImageOff className="size-3.5 shrink-0" />
@@ -168,8 +169,22 @@ export function NativeChatComposerField({
               rows={2}
               onChange={(e) => onDraftChange(e.target.value, e.currentTarget)}
               onKeyDown={onKeyDown}
+              onCompositionStart={onCompositionStart}
+              onCompositionEnd={onCompositionEnd}
               onPaste={onPaste}
               onSelect={(e) => onTextareaSelect(e.currentTarget)}
+              aria-expanded={autocomplete.mode === 'slash' || autocomplete.mode === 'skill'}
+              aria-controls={
+                autocomplete.mode === 'slash' || autocomplete.mode === 'skill'
+                  ? pickerListboxId
+                  : undefined
+              }
+              aria-activedescendant={
+                (autocomplete.mode === 'slash' || autocomplete.mode === 'skill') &&
+                autocomplete.items.length > 0
+                  ? `${pickerListboxId}-option-${Math.min(activeSuggestion, autocomplete.items.length - 1)}`
+                  : undefined
+              }
               placeholder={nativeChatComposerPlaceholder(hasPty, canSend)}
               // Why: coarse-pointer min-height follows the app's touch target convention.
               // scrollbar-sleek keeps the overflow gutter from showing the heavy
diff --git a/src/renderer/src/components/native-chat/native-chat-agent-commands.ts b/src/renderer/src/components/native-chat/native-chat-agent-commands.ts
deleted file mode 100644
index 3c363bf5e53..00000000000
--- a/src/renderer/src/components/native-chat/native-chat-agent-commands.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-// The per-agent slash-command catalog now lives in src/shared so the desktop
-// renderer and the mobile app share one source of truth (no drift). This file
-// re-exports it for existing desktop import sites.
-
-export {
-  getAgentSlashCommands,
-  type SlashCommandSuggestion
-} from '../../../../shared/native-chat-slash-commands'
diff --git a/src/renderer/src/components/native-chat/native-chat-composer-state.test.ts b/src/renderer/src/components/native-chat/native-chat-composer-state.test.ts
index 499d2b1610c..802ecfe5c45 100644
--- a/src/renderer/src/components/native-chat/native-chat-composer-state.test.ts
+++ b/src/renderer/src/components/native-chat/native-chat-composer-state.test.ts
@@ -1,11 +1,13 @@
 import { describe, expect, it } from 'vitest'
 import {
   applyMentionSuggestion,
-  applySkillSuggestion,
+  applyPickerSuggestion,
   applySlashSuggestion,
+  buildNativeChatPickerItems,
+  classifyNativeChatSend,
   deriveComposerAutocomplete,
+  editReplacesTriggerToken,
   EMPTY_HISTORY,
-  filterSkillSuggestions,
   filterSlashCommands,
   isSlashCommandDraft,
   pushHistory,
@@ -15,6 +17,7 @@ import {
   type SlashCommandSuggestion
 } from './native-chat-composer-state'
 import type { DiscoveredSkill } from '../../../../shared/skills'
+import { getNativeChatAgentProfile } from '../../../../shared/native-chat-agent-profiles'
 
 const COMMANDS: SlashCommandSuggestion[] = [
   { name: 'clear' },
@@ -48,7 +51,7 @@ describe('deriveComposerAutocomplete — slash', () => {
       return
     }
     expect(result.query).toBe('cl')
-    expect(result.suggestions.map((c) => c.name)).toEqual(['clear'])
+    expect(result.items.map((item) => item.name)).toEqual(['clear'])
   })
 
   it('a bare `/` returns the full command list', () => {
@@ -57,7 +60,7 @@ describe('deriveComposerAutocomplete — slash', () => {
     if (result.mode !== 'slash') {
       return
     }
-    expect(result.suggestions).toHaveLength(3)
+    expect(result.items).toHaveLength(3)
   })
 
   it('does not fire slash mode after a space', () => {
@@ -106,7 +109,7 @@ describe('deriveComposerAutocomplete — skill', () => {
       return
     }
     expect(result.query).toBe('type')
-    expect(result.suggestions.map((entry) => entry.name)).toEqual(['typescript'])
+    expect(result.items.map((entry) => entry.name)).toEqual(['typescript'])
   })
 
   it('fires at the start of input too', () => {
@@ -132,20 +135,6 @@ describe('isSlashCommandDraft', () => {
   })
 })
 
-describe('filterSkillSuggestions', () => {
-  it('filters installed skills by name or directory basename', () => {
-    const skills = [
-      skill({ name: 'TypeScript' }),
-      skill({ name: 'Display Name', directoryPath: '/repo/.agents/skills/ref-oss' }),
-      skill({ name: 'hidden', installed: false })
-    ]
-    expect(filterSkillSuggestions(skills, 'ref').map((entry) => entry.name)).toEqual([
-      'Display Name'
-    ])
-    expect(filterSkillSuggestions(skills, 'h')).toEqual([])
-  })
-})
-
 describe('history recall', () => {
   it('up-arrow on empty composer recalls the last sent input', () => {
     const history = pushHistory(EMPTY_HISTORY, 'first')
@@ -205,9 +194,192 @@ describe('apply suggestions', () => {
     expect(result.caret).toBe('open @src/app.ts '.length)
   })
 
-  it('applySkillSuggestion replaces the active $token at the caret', () => {
-    const result = applySkillSuggestion('use $typ now', 8, 'typescript')
+  it('applyPickerSuggestion replaces the active $token at the caret', () => {
+    const result = applyPickerSuggestion(
+      'use $typ now',
+      8,
+      { kind: 'skill', id: 'skill:typescript', name: 'typescript', description: null, sources: [] },
+      '$'
+    )
     expect(result.draft).toBe('use $typescript  now')
     expect(result.caret).toBe('use $typescript '.length)
   })
 })
+
+describe('native skill and command picker', () => {
+  it('keeps Codex commands under slash and skills under dollar', () => {
+    const profile = getNativeChatAgentProfile('codex')
+    const slash = deriveComposerAutocomplete('/', 1, COMMANDS, [skill({})], profile)
+    expect(slash.mode).toBe('slash')
+    if (slash.mode === 'slash') {
+      expect(slash.items.every((item) => item.kind === 'command')).toBe(true)
+    }
+    const dollar = deriveComposerAutocomplete('$', 1, COMMANDS, [skill({})], profile)
+    expect(dollar.mode).toBe('skill')
+    if (dollar.mode === 'skill') {
+      expect(dollar.items.every((item) => item.kind === 'skill')).toBe(true)
+    }
+  })
+
+  it('groups Claude commands and skills under slash', () => {
+    const result = deriveComposerAutocomplete(
+      '/',
+      1,
+      COMMANDS,
+      [skill({ name: 'browser' })],
+      getNativeChatAgentProfile('claude')
+    )
+    expect(result.mode).toBe('slash')
+    if (result.mode === 'slash') {
+      expect(result.grouped).toBe(true)
+      expect(result.items.map((item) => item.kind)).toContain('command')
+      expect(result.items.map((item) => item.kind)).toContain('skill')
+    }
+  })
+
+  it('ranks exact, prefix, fuzzy, then description matches within a group', () => {
+    const items = buildNativeChatPickerItems(
+      [],
+      [
+        skill({ name: 'deploy', skillFilePath: '/1/SKILL.md' }),
+        skill({ name: 'deployment', skillFilePath: '/2/SKILL.md' }),
+        skill({ name: 'd-e-p-l-o-y', skillFilePath: '/3/SKILL.md' }),
+        skill({
+          name: 'release',
+          description: 'Deploy an application',
+          skillFilePath: '/4/SKILL.md'
+        })
+      ],
+      'deploy',
+      '$'
+    )
+    expect(items.map((item) => item.name)).toEqual([
+      'deploy',
+      'deployment',
+      'd-e-p-l-o-y',
+      'release'
+    ])
+  })
+
+  it('merges duplicate names but annotates command collisions on one command row', () => {
+    const duplicateSkills = [
+      skill({ name: 'clear', skillFilePath: '/project/clear/SKILL.md', sourceKind: 'repo' }),
+      skill({ name: 'clear', skillFilePath: '/home/clear/SKILL.md', sourceKind: 'home' })
+    ]
+    const skillOnly = buildNativeChatPickerItems([], duplicateSkills, '', '$')
+    expect(skillOnly).toEqual([
+      expect.objectContaining({ kind: 'skill', name: 'clear', sources: expect.any(Array) })
+    ])
+    expect(skillOnly[0].kind === 'skill' ? skillOnly[0].sources : []).toHaveLength(2)
+
+    const collision = buildNativeChatPickerItems(COMMANDS, duplicateSkills, 'clear', '/')
+    expect(collision).toEqual([
+      expect.objectContaining({ kind: 'command', name: 'clear', skillCollision: true })
+    ])
+  })
+
+  it('keeps a long token-safe name intact for insertion instead of truncating it', () => {
+    const longName = `skill-${'x'.repeat(100)}`
+    const items = buildNativeChatPickerItems(
+      [],
+      [skill({ name: longName, skillFilePath: '/long/SKILL.md' })],
+      '',
+      '$'
+    )
+    expect(items.map((item) => item.name)).toEqual([longName])
+    const applied = applyPickerSuggestion('$sk', 3, items[0], '$')
+    expect(applied.draft).toBe(`$${longName} `)
+  })
+
+  it('rejects names carrying zero-width characters instead of inserting them', () => {
+    const items = buildNativeChatPickerItems(
+      [],
+      [
+        skill({
+          name: 'cle\u200bar',
+          directoryPath: '/repo/.agents/skills/safe-dir',
+          skillFilePath: '/repo/.agents/skills/safe-dir/SKILL.md'
+        })
+      ],
+      '',
+      '$'
+    )
+    expect(items.map((item) => item.name)).toEqual(['safe-dir'])
+  })
+
+  it('falls back to a token-safe directory name and strips unsafe display text', () => {
+    const items = buildNativeChatPickerItems(
+      [],
+      [
+        skill({
+          name: 'Spoof\u202e Name',
+          directoryPath: '/repo/.agents/skills/safe-name',
+          skillFilePath: '/repo/.agents/skills/safe-name/SKILL.md'
+        })
+      ],
+      '',
+      '$'
+    )
+    expect(items.map((item) => item.name)).toEqual(['safe-name'])
+  })
+
+  it('replaces only the active slash token and preserves text after the caret', () => {
+    const result = applyPickerSuggestion(
+      '/bro trailing',
+      4,
+      { kind: 'skill', id: 'skill:browser', name: 'browser', description: null, sources: [] },
+      '/'
+    )
+    expect(result.draft).toBe('/browser  trailing')
+    expect(result.caret).toBe('/browser '.length)
+  })
+
+  it('classifies sends only from the origin tag and exact command catalog', () => {
+    expect(classifyNativeChatSend('/browser do work', COMMANDS, '/browser', '/')).toBe('chat')
+    expect(classifyNativeChatSend('/clear', COMMANDS, null, '/')).toBe('command')
+    expect(classifyNativeChatSend('/Clear', COMMANDS, null, '/')).toBe('unknown-token')
+    expect(classifyNativeChatSend('/usr/bin/python is missing', COMMANDS, null, '/')).toBe(
+      'unknown-token'
+    )
+    expect(classifyNativeChatSend('ordinary prompt', COMMANDS, null, '/')).toBe('chat')
+  })
+
+  it('leading whitespace makes a slash draft prose, never a dispatched command', () => {
+    expect(classifyNativeChatSend(' /clear', COMMANDS, null, '/')).toBe('chat')
+  })
+
+  it('treats a leading $ token as unknown only for the $-prefix (Codex) profile', () => {
+    expect(classifyNativeChatSend('$deploy now', COMMANDS, null, '$')).toBe('unknown-token')
+    expect(classifyNativeChatSend('$PATH is wrong', COMMANDS, null, '/')).toBe('chat')
+    expect(classifyNativeChatSend('$50 is the budget', COMMANDS, null, null)).toBe('chat')
+  })
+
+  it('treats a one-edit token swap as a new trigger occurrence', () => {
+    expect(editReplacesTriggerToken('/foo', '/bar', '/:0')).toBe(true)
+    expect(editReplacesTriggerToken('use $foo', 'use $bar', '$:4')).toBe(true)
+  })
+
+  it('keeps suppression while typing or deleting inside the dismissed token', () => {
+    expect(editReplacesTriggerToken('/foo', '/food', '/:0')).toBe(false)
+    expect(editReplacesTriggerToken('/food', '/foo', '/:0')).toBe(false)
+    expect(editReplacesTriggerToken('use $foo now', 'ran $foo now', '$:4')).toBe(false)
+  })
+
+  it('suppresses only the dismissed trigger occurrence', () => {
+    const profile = getNativeChatAgentProfile('codex')
+    expect(deriveComposerAutocomplete('use $bro', 8, COMMANDS, [skill({})], profile).mode).toBe(
+      'skill'
+    )
+    expect(
+      deriveComposerAutocomplete(
+        'use $bro',
+        8,
+        COMMANDS,
+        [skill({})],
+        profile,
+        { status: 'ready', skills: [skill({})] },
+        '$:4'
+      ).mode
+    ).toBe('none')
+  })
+})
diff --git a/src/renderer/src/components/native-chat/native-chat-composer-state.ts b/src/renderer/src/components/native-chat/native-chat-composer-state.ts
index 9871bba1b95..c7c320af52e 100644
--- a/src/renderer/src/components/native-chat/native-chat-composer-state.ts
+++ b/src/renderer/src/components/native-chat/native-chat-composer-state.ts
@@ -1,11 +1,5 @@
-// Pure state machine for the native chat composer. Given the current draft,
-// caret position, sent-input history, and the active agent's known slash
-// commands/skills, it derives the autocomplete mode, the
-// query, and the filtered suggestions. Keeping this DOM-free makes the slash /
-// mention / skill / history behavior unit-testable; the .tsx only owns rendering and
-// the actual textarea/caret wiring.
-
 import type { DiscoveredSkill } from '../../../../shared/skills'
+import type { NativeChatAgentProfile } from '../../../../shared/native-chat-agent-profiles'
 import {
   filterSlashCommands,
   isSlashCommandDraft,
@@ -13,145 +7,165 @@ import {
   slashCommandDispatchText,
   type SlashCommandSuggestion
 } from '../../../../shared/native-chat-slash-commands'
+import {
+  buildNativeChatPickerItems,
+  type NativeChatPickerItem,
+  type NativeChatSkillDiscoverySnapshot
+} from './native-chat-picker-items'
 
 export type { SlashCommandSuggestion }
 export { filterSlashCommands, isSlashCommandDraft, applySlashSuggestion, slashCommandDispatchText }
+export {
+  applyPickerSuggestion,
+  buildNativeChatPickerItems,
+  classifyNativeChatSend,
+  type NativeChatPickerItem,
+  type NativeChatSendClassification,
+  type NativeChatSkillDiscoverySnapshot
+} from './native-chat-picker-items'
 
 export type ComposerAutocompleteMode = 'none' | 'slash' | 'mention' | 'skill'
 
-export type ComposerAutocomplete =
-  | { mode: 'none' }
-  | { mode: 'slash'; query: string; suggestions: SlashCommandSuggestion[] }
-  | { mode: 'mention'; query: string }
-  | { mode: 'skill'; query: string; suggestions: DiscoveredSkill[] }
-
-export type ComposerDerivation = {
-  autocomplete: ComposerAutocomplete
+type PickerAutocomplete = {
+  query: string
+  items: NativeChatPickerItem[]
+  triggerKey: string
+  prefix: '/' | '$'
+  grouped: boolean
+  commandsEnabled: boolean
+  skillsEnabled: boolean
+  skillStatus: NativeChatSkillDiscoverySnapshot['status']
+  skillErrorKind?: NativeChatSkillDiscoverySnapshot['errorKind']
 }
 
-/**
- * Detect the active autocomplete trigger from the text before the caret.
- *
- * Rules (intentionally conservative to avoid firing inside ordinary prose):
- *  - Slash: the draft starts with `/` and the caret is within that first token
- *    (no whitespace between `/` and the caret). Agent slash commands are only
- *    valid at the very start of the input, mirroring how the TUIs accept them.
- *  - Mention: an `@` immediately preceded by start-of-input or whitespace, with
- *    no whitespace between it and the caret. Works anywhere in the line so you
- *    can reference a file mid-sentence.
- */
+export type ComposerAutocomplete =
+  | { mode: 'none' }
+  | ({ mode: 'slash' } & PickerAutocomplete)
+  | { mode: 'mention'; query: string }
+  | ({ mode: 'skill' } & PickerAutocomplete)
+
+const EMPTY_DISCOVERY: NativeChatSkillDiscoverySnapshot = { status: 'ready', skills: [] }
+
 export function deriveComposerAutocomplete(
   draft: string,
   caret: number,
   agentCommands: readonly SlashCommandSuggestion[],
-  skills: readonly DiscoveredSkill[] = []
+  skills: readonly DiscoveredSkill[] = [],
+  profile: NativeChatAgentProfile | null = null,
+  discovery: NativeChatSkillDiscoverySnapshot = { ...EMPTY_DISCOVERY, skills },
+  dismissedTriggerKey: string | null = null
 ): ComposerAutocomplete {
   const before = draft.slice(0, caret)
-
-  // Slash: only at the absolute start of the input, and only while the caret is
-  // still inside the unbroken command token.
   if (before.startsWith('/') && !/\s/.test(before)) {
-    const query = before.slice(1)
-    return { mode: 'slash', query, suggestions: filterSlashCommands(agentCommands, query) }
+    return deriveSlashAutocomplete(before, agentCommands, profile, discovery, dismissedTriggerKey)
   }
-
   const mentionMatch = before.match(/(?:^|\s)@(\S*)$/)
   if (mentionMatch) {
     return { mode: 'mention', query: mentionMatch[1] }
   }
-
-  const skillMatch = before.match(/(?:^|\s)\$(\S*)$/)
-  if (skillMatch) {
-    const query = skillMatch[1]
-    return { mode: 'skill', query, suggestions: filterSkillSuggestions(skills, query) }
+  const skillMatch =
+    profile?.skillPrefix === '$' || (!profile && skills.length > 0)
+      ? before.match(/(?:^|\s)\$(\S*)$/)
+      : null
+  if (!skillMatch) {
+    return { mode: 'none' }
   }
-
-  return { mode: 'none' }
-}
-
-export function filterSkillSuggestions(
-  skills: readonly DiscoveredSkill[],
-  query: string
-): DiscoveredSkill[] {
-  const normalized = query.toLowerCase()
-  const installed = skills.filter((skill) => skill.installed)
-  if (normalized === '') {
-    return installed.slice(0, 12)
+  const triggerKey = `$:${before.length - skillMatch[1].length - 1}`
+  if (dismissedTriggerKey === triggerKey) {
+    return { mode: 'none' }
   }
-  return installed
-    .filter((skill) => {
-      const name = skill.name.toLowerCase()
-      const dirName = skill.directoryPath.split(/[\\/]/).findLast(Boolean)?.toLowerCase()
-      return name.startsWith(normalized) || dirName?.startsWith(normalized)
-    })
-    .slice(0, 12)
-}
-
-export type HistoryState = {
-  /** Most-recent-last list of previously sent drafts. */
-  entries: readonly string[]
-  /** Cursor into `entries`; null means "live draft" (not recalling). */
-  index: number | null
-}
-
-export const EMPTY_HISTORY: HistoryState = { entries: [], index: null }
-
-/** Append a sent draft to history and reset the recall cursor. Blank sends and
- *  immediate duplicates of the last entry are not recorded (shell-style). */
-export function pushHistory(history: HistoryState, sent: string): HistoryState {
-  if (sent.trim() === '') {
-    return { entries: history.entries, index: null }
-  }
-  if (history.entries.at(-1) === sent) {
-    return { entries: history.entries, index: null }
-  }
-  return { entries: [...history.entries, sent], index: null }
-}
-
-export type HistoryRecall = {
-  history: HistoryState
-  /** The draft text to show, or null to leave the live draft untouched. */
-  draft: string | null
-}
-
-/**
- * Move one step toward older entries (Up arrow). From the live draft this jumps
- * to the most recent entry; thereafter it walks backward and clamps at the
- * oldest. Returns the recalled draft, or null when there is nothing to recall.
- */
-export function recallPrevious(history: HistoryState): HistoryRecall {
-  if (history.entries.length === 0) {
-    return { history, draft: null }
-  }
-  const nextIndex =
-    history.index === null ? history.entries.length - 1 : Math.max(0, history.index - 1)
+  const query = skillMatch[1]
   return {
-    history: { entries: history.entries, index: nextIndex },
-    draft: history.entries[nextIndex]
+    mode: 'skill',
+    query,
+    triggerKey,
+    prefix: '$',
+    grouped: false,
+    commandsEnabled: false,
+    skillsEnabled: true,
+    items: buildNativeChatPickerItems([], discovery.skills, query, '$'),
+    skillStatus: discovery.status === 'idle' ? 'loading' : discovery.status,
+    ...(discovery.errorKind ? { skillErrorKind: discovery.errorKind } : {})
   }
 }
 
-/**
- * Move one step toward newer entries (Down arrow). Walking past the newest entry
- * returns to the live (empty) draft and clears the recall cursor. Returns null
- * draft when not currently recalling.
- */
-export function recallNext(history: HistoryState): HistoryRecall {
-  if (history.index === null) {
-    return { history, draft: null }
-  }
-  const nextIndex = history.index + 1
-  if (nextIndex >= history.entries.length) {
-    return { history: { entries: history.entries, index: null }, draft: '' }
+function deriveSlashAutocomplete(
+  before: string,
+  agentCommands: readonly SlashCommandSuggestion[],
+  profile: NativeChatAgentProfile | null,
+  discovery: NativeChatSkillDiscoverySnapshot,
+  dismissedTriggerKey: string | null
+): ComposerAutocomplete {
+  const triggerKey = '/:0'
+  if (dismissedTriggerKey === triggerKey) {
+    return { mode: 'none' }
   }
+  const query = before.slice(1)
+  const hasSlashSkills = profile?.skillPrefix === '/'
+  // Why: the caller owns catalog policy (e.g. Grok ships skills-only until a
+  // verified catalog lands); this derivation must not re-gate per agent.
+  const items = buildNativeChatPickerItems(
+    agentCommands,
+    hasSlashSkills ? discovery.skills : [],
+    query,
+    '/'
+  )
   return {
-    history: { entries: history.entries, index: nextIndex },
-    draft: history.entries[nextIndex]
+    mode: 'slash',
+    query,
+    triggerKey,
+    prefix: '/',
+    grouped: profile?.groupedSlash === true,
+    commandsEnabled: agentCommands.length > 0,
+    skillsEnabled: hasSlashSkills,
+    items,
+    skillStatus: hasSlashSkills
+      ? discovery.status === 'idle'
+        ? 'loading'
+        : discovery.status
+      : 'ready',
+    ...(hasSlashSkills && discovery.errorKind ? { skillErrorKind: discovery.errorKind } : {})
   }
 }
 
-/** Replace the active `@query` token before the caret with the chosen path.
- *  Returns the new full draft and the caret offset to place after insertion. */
+/** True when one edit both removed and inserted text across the dismissed
+ *  trigger token — a wholesale replacement (e.g. select-all + paste), which is
+ *  a new trigger occurrence even though a trigger character lands back on the
+ *  same draft position. Typing or deleting inside the token is not. */
+export function editReplacesTriggerToken(
+  previous: string,
+  next: string,
+  triggerKey: string
+): boolean {
+  const triggerPosition = Number.parseInt(triggerKey.slice(triggerKey.indexOf(':') + 1), 10)
+  if (!Number.isFinite(triggerPosition) || previous === next) {
+    return false
+  }
+  let commonPrefix = 0
+  const maxPrefix = Math.min(previous.length, next.length)
+  while (commonPrefix < maxPrefix && previous[commonPrefix] === next[commonPrefix]) {
+    commonPrefix += 1
+  }
+  let commonSuffix = 0
+  while (
+    commonSuffix < previous.length - commonPrefix &&
+    commonSuffix < next.length - commonPrefix &&
+    previous[previous.length - 1 - commonSuffix] === next[next.length - 1 - commonSuffix]
+  ) {
+    commonSuffix += 1
+  }
+  const removed = previous.length - commonPrefix - commonSuffix
+  const inserted = next.length - commonPrefix - commonSuffix
+  if (removed === 0 || inserted === 0) {
+    return false
+  }
+  let tokenEnd = triggerPosition + 1
+  while (tokenEnd < previous.length && !/\s/.test(previous[tokenEnd])) {
+    tokenEnd += 1
+  }
+  return commonPrefix < tokenEnd && previous.length - commonSuffix > triggerPosition
+}
+
 export function applyMentionSuggestion(
   draft: string,
   caret: number,
@@ -163,25 +177,38 @@ export function applyMentionSuggestion(
   if (!match) {
     return { draft, caret }
   }
-  const tokenStart = before.length - match[2].length - 1 // -1 for the '@'
-  const insertion = `@${path} `
-  const nextBefore = before.slice(0, tokenStart) + insertion
+  const tokenStart = before.length - match[2].length - 1
+  const nextBefore = `${before.slice(0, tokenStart)}@${path} `
   return { draft: nextBefore + after, caret: nextBefore.length }
 }
 
-export function applySkillSuggestion(
-  draft: string,
-  caret: number,
-  skillName: string
-): { draft: string; caret: number } {
-  const before = draft.slice(0, caret)
-  const after = draft.slice(caret)
-  const match = before.match(/(^|\s)\$(\S*)$/)
-  if (!match) {
-    return { draft, caret }
+export type HistoryState = { entries: readonly string[]; index: number | null }
+export const EMPTY_HISTORY: HistoryState = { entries: [], index: null }
+
+export function pushHistory(history: HistoryState, sent: string): HistoryState {
+  if (sent.trim() === '' || history.entries.at(-1) === sent) {
+    return { entries: history.entries, index: null }
   }
-  const tokenStart = before.length - match[2].length - 1 // -1 for the '$'
-  const insertion = `$${skillName} `
-  const nextBefore = before.slice(0, tokenStart) + insertion
-  return { draft: nextBefore + after, caret: nextBefore.length }
+  return { entries: [...history.entries, sent], index: null }
+}
+
+export type HistoryRecall = { history: HistoryState; draft: string | null }
+
+export function recallPrevious(history: HistoryState): HistoryRecall {
+  if (history.entries.length === 0) {
+    return { history, draft: null }
+  }
+  const index = history.index === null ? history.entries.length - 1 : Math.max(0, history.index - 1)
+  return { history: { entries: history.entries, index }, draft: history.entries[index] }
+}
+
+export function recallNext(history: HistoryState): HistoryRecall {
+  if (history.index === null) {
+    return { history, draft: null }
+  }
+  const index = history.index + 1
+  if (index >= history.entries.length) {
+    return { history: { entries: history.entries, index: null }, draft: '' }
+  }
+  return { history: { entries: history.entries, index }, draft: history.entries[index] }
 }
diff --git a/src/renderer/src/components/native-chat/native-chat-picker-items.ts b/src/renderer/src/components/native-chat/native-chat-picker-items.ts
new file mode 100644
index 00000000000..e1c2c4fc78f
--- /dev/null
+++ b/src/renderer/src/components/native-chat/native-chat-picker-items.ts
@@ -0,0 +1,248 @@
+import type { DiscoveredSkill, SkillSourceKind } from '../../../../shared/skills'
+import type { SlashCommandSuggestion } from '../../../../shared/native-chat-slash-commands'
+import {
+  isSafeDisplayCharacter,
+  stripUnsafeDisplayCharacters
+} from '../../../../shared/skill-display-text'
+
+export type NativeChatPickerItem =
+  | {
+      kind: 'command'
+      id: string
+      name: string
+      description?: string
+      skillCollision: boolean
+    }
+  | {
+      kind: 'skill'
+      id: string
+      name: string
+      description: string | null
+      sources: { sourceKind: SkillSourceKind; skillFilePath: string }[]
+    }
+
+export type NativeChatSkillDiscoverySnapshot = {
+  status: 'idle' | 'loading' | 'ready' | 'error'
+  skills: readonly DiscoveredSkill[]
+  errorKind?: 'unavailable' | 'timeout' | 'host' | 'unknown'
+}
+
+const PICKER_RESULT_LIMIT = 50
+const SCOPE_PRIORITY: Record<SkillSourceKind, number> = {
+  repo: 0,
+  home: 1,
+  bundled: 2,
+  plugin: 3
+}
+
+export function buildNativeChatPickerItems(
+  commands: readonly SlashCommandSuggestion[],
+  skills: readonly DiscoveredSkill[],
+  query: string,
+  prefix: '/' | '$'
+): NativeChatPickerItem[] {
+  const mergedSkills = mergeNativeChatSkills(skills)
+  const skillNames = new Set(mergedSkills.map((skill) => skill.name))
+  const commandNames = new Set(commands.map((command) => command.name))
+  const commandItems = rankItems(
+    commands.map((command, index) => ({
+      item: {
+        kind: 'command' as const,
+        // Why: the name is the dispatch token and the catalog is curated, so
+        // it is inserted verbatim; only untrusted skill text gets sanitized.
+        id: `command:${command.name}`,
+        name: command.name,
+        description: command.description ? sanitizePickerText(command.description, 240) : undefined,
+        skillCollision: prefix === '/' && skillNames.has(command.name)
+      },
+      stableOrder: index
+    })),
+    query
+  )
+  const skillItems = rankItems(
+    mergedSkills
+      .filter((skill) => !(prefix === '/' && commandNames.has(skill.name)))
+      .map((item, index) => ({ item, stableOrder: index })),
+    query
+  )
+  return [
+    ...commandItems.slice(0, PICKER_RESULT_LIMIT),
+    ...skillItems.slice(0, PICKER_RESULT_LIMIT)
+  ]
+}
+
+function mergeNativeChatSkills(
+  skills: readonly DiscoveredSkill[]
+): Extract<NativeChatPickerItem, { kind: 'skill' }>[] {
+  const exactPaths = new Map<string, DiscoveredSkill>()
+  for (const skill of skills) {
+    if (skill.installed && !exactPaths.has(skill.skillFilePath)) {
+      exactPaths.set(skill.skillFilePath, skill)
+    }
+  }
+  const byName = new Map<string, DiscoveredSkill[]>()
+  for (const skill of exactPaths.values()) {
+    const safeName = getSafeSkillName(skill)
+    if (!safeName) {
+      continue
+    }
+    byName.set(safeName, [...(byName.get(safeName) ?? []), { ...skill, name: safeName }])
+  }
+  return [...byName.entries()]
+    .map(([name, namedSkills]) => {
+      const sorted = [...namedSkills].sort(compareDiscoveredSkills)
+      return {
+        kind: 'skill' as const,
+        id: `skill:${name}`,
+        name,
+        description: sorted[0]?.description ? sanitizePickerText(sorted[0].description, 240) : null,
+        sources: sorted.map((skill) => ({
+          sourceKind: skill.sourceKind,
+          skillFilePath: skill.skillFilePath
+        }))
+      }
+    })
+    .sort(comparePickerSkills)
+}
+
+function rankItems<T extends NativeChatPickerItem>(
+  entries: { item: T; stableOrder: number }[],
+  query: string
+): T[] {
+  if (!query) {
+    return entries.map((entry) => entry.item)
+  }
+  return entries
+    .map((entry) => ({ ...entry, rank: getMatchRank(entry.item, query) }))
+    .filter((entry) => entry.rank !== null)
+    .sort((a, b) => a.rank! - b.rank! || a.stableOrder - b.stableOrder)
+    .map((entry) => entry.item)
+}
+
+function getMatchRank(
+  item: Pick<NativeChatPickerItem, 'name' | 'description'>,
+  query: string
+): number | null {
+  const normalizedQuery = query.toLocaleLowerCase()
+  const name = item.name.toLocaleLowerCase()
+  if (name === normalizedQuery) {
+    return 0
+  }
+  if (name.startsWith(normalizedQuery)) {
+    return 1
+  }
+  if (name.includes(normalizedQuery)) {
+    return 2
+  }
+  if (isSubsequence(normalizedQuery, name)) {
+    return 3
+  }
+  if (item.description?.toLocaleLowerCase().includes(normalizedQuery)) {
+    return 4
+  }
+  return null
+}
+
+function isSubsequence(query: string, value: string): boolean {
+  let queryIndex = 0
+  for (const character of value) {
+    if (character === query[queryIndex]) {
+      queryIndex += 1
+    }
+    if (queryIndex === query.length) {
+      return true
+    }
+  }
+  return false
+}
+
+// Why: the row's visual truncation is CSS; the name IS the inserted PTY token,
+// so it must never be sliced. Token safety instead rejects absurd lengths.
+const MAX_TOKEN_SAFE_NAME_LENGTH = 200
+
+function getSafeSkillName(skill: DiscoveredSkill): string | null {
+  if (isTokenSafe(skill.name)) {
+    return skill.name
+  }
+  const directoryName = skill.directoryPath.split(/[\\/]/).findLast(Boolean) ?? ''
+  return isTokenSafe(directoryName) ? directoryName : null
+}
+
+function isTokenSafe(value: string): boolean {
+  return (
+    value.length > 0 &&
+    value.length <= MAX_TOKEN_SAFE_NAME_LENGTH &&
+    !/\s/u.test(value) &&
+    [...value].every(isSafeDisplayCharacter)
+  )
+}
+
+function sanitizePickerText(value: string, maxLength: number): string {
+  return stripUnsafeDisplayCharacters(value).slice(0, maxLength)
+}
+
+function compareDiscoveredSkills(a: DiscoveredSkill, b: DiscoveredSkill): number {
+  return (
+    SCOPE_PRIORITY[a.sourceKind] - SCOPE_PRIORITY[b.sourceKind] ||
+    a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }) ||
+    a.skillFilePath.localeCompare(b.skillFilePath)
+  )
+}
+
+function comparePickerSkills(
+  a: Extract<NativeChatPickerItem, { kind: 'skill' }>,
+  b: Extract<NativeChatPickerItem, { kind: 'skill' }>
+): number {
+  return (
+    SCOPE_PRIORITY[a.sources[0].sourceKind] - SCOPE_PRIORITY[b.sources[0].sourceKind] ||
+    a.name.localeCompare(b.name, undefined, { sensitivity: 'base' })
+  )
+}
+
+export function applyPickerSuggestion(
+  draft: string,
+  caret: number,
+  item: NativeChatPickerItem,
+  prefix: '/' | '$'
+): { draft: string; caret: number; insertedToken: string } {
+  const before = draft.slice(0, caret)
+  const after = draft.slice(caret)
+  const match = prefix === '/' ? before.match(/^\/(\S*)$/) : before.match(/(^|\s)\$(\S*)$/)
+  if (!match) {
+    return { draft, caret, insertedToken: '' }
+  }
+  const query = match.at(-1) ?? ''
+  const tokenStart = before.length - query.length - 1
+  const insertedToken = `${prefix}${item.name}`
+  const nextBefore = `${before.slice(0, tokenStart)}${insertedToken} `
+  return { draft: nextBefore + after, caret: nextBefore.length, insertedToken }
+}
+
+export type NativeChatSendClassification = 'chat' | 'command' | 'unknown-token'
+
+export function classifyNativeChatSend(
+  draft: string,
+  commands: readonly SlashCommandSuggestion[],
+  pickerSkillOriginToken: string | null,
+  skillPrefix: '/' | '$' | null
+): NativeChatSendClassification {
+  // Why: the supported TUIs only treat a line-leading token as a command, so a
+  // draft with leading whitespace is prose; trimming here would claim a "Ran"
+  // line for text the agent never dispatched.
+  const firstToken = draft.split(/\s/, 1)[0] ?? ''
+  if (pickerSkillOriginToken && firstToken === pickerSkillOriginToken) {
+    return 'chat'
+  }
+  if (commands.some((command) => firstToken === `/${command.name}`)) {
+    return 'command'
+  }
+  if (firstToken.startsWith('/')) {
+    return 'unknown-token'
+  }
+  // Why: `$` is Codex grammar only. For other agents a leading `$PATH`-style
+  // token is ordinary prose and must keep its bubble and attachments.
+  if (skillPrefix === '$' && firstToken.startsWith('$')) {
+    return 'unknown-token'
+  }
+  return 'chat'
+}
diff --git a/src/renderer/src/components/native-chat/native-chat-skill-discovery-context.ts b/src/renderer/src/components/native-chat/native-chat-skill-discovery-context.ts
new file mode 100644
index 00000000000..17e05af6a5c
--- /dev/null
+++ b/src/renderer/src/components/native-chat/native-chat-skill-discovery-context.ts
@@ -0,0 +1,156 @@
+import type { AppState } from '../../store/types'
+import type { SkillDiscoveryTarget } from '../../../../shared/skills'
+import { parseExecutionHostId } from '../../../../shared/execution-host'
+import type { RuntimeClientTarget } from '@/runtime/runtime-rpc-client'
+import {
+  getExplicitRuntimeEnvironmentIdForWorktree,
+  getExecutionHostIdForWorktree
+} from '@/lib/worktree-runtime-owner'
+import { getLocalProjectExecutionRuntimeContext } from '@/lib/local-preflight-context'
+import { parseWorkspaceKey } from '../../../../shared/workspace-scope'
+
+export type NativeChatSkillStateInputs = Pick<
+  AppState,
+  | 'activeRepoId'
+  | 'activeWorktreeId'
+  | 'folderWorkspaces'
+  | 'projectGroups'
+  | 'projects'
+  | 'repos'
+  | 'restoredRuntimeHostIdByWorkspaceSessionKey'
+  | 'settings'
+  | 'tabsByWorktree'
+  | 'worktreesByRepo'
+>
+
+type NativeChatSkillTab = { id: string; startupCwd?: string }
+
+type NativeChatSkillWorktreeState = {
+  tabsByWorktree: Record<string, readonly NativeChatSkillTab[]>
+  worktreesByRepo: Record<string, readonly { id: string; path: string }[]>
+}
+
+export type NativeChatSkillDiscoveryContext = {
+  key: string
+  cwd: string
+  executionHostKind: 'local' | 'runtime' | 'ssh'
+  runtimeTarget: RuntimeClientTarget
+  discoveryTarget: SkillDiscoveryTarget
+}
+
+export function selectNativeChatSkillStateInputs(state: AppState): NativeChatSkillStateInputs {
+  return {
+    activeRepoId: state.activeRepoId,
+    activeWorktreeId: state.activeWorktreeId,
+    folderWorkspaces: state.folderWorkspaces,
+    projectGroups: state.projectGroups,
+    projects: state.projects,
+    repos: state.repos,
+    restoredRuntimeHostIdByWorkspaceSessionKey: state.restoredRuntimeHostIdByWorkspaceSessionKey,
+    settings: state.settings,
+    tabsByWorktree: state.tabsByWorktree,
+    worktreesByRepo: state.worktreesByRepo
+  }
+}
+
+export function resolveNativeChatSkillDiscoveryCwd(
+  state: NativeChatSkillWorktreeState,
+  terminalTabId: string
+): string | null {
+  const found = findTerminalTab(state.tabsByWorktree, terminalTabId)
+  if (!found) {
+    return null
+  }
+  // Why: the agent runs where its pane started. A pane launched in a
+  // subdirectory must not scan (or share a cache key with) the worktree root.
+  const startupCwd = found.tab.startupCwd?.trim()
+  if (startupCwd) {
+    return startupCwd
+  }
+  for (const worktrees of Object.values(state.worktreesByRepo)) {
+    const worktree = worktrees.find((entry) => entry.id === found.worktreeId)
+    if (worktree) {
+      return worktree.path
+    }
+  }
+  return null
+}
+
+export function resolveNativeChatSkillDiscoveryContext(
+  state: NativeChatSkillStateInputs,
+  terminalTabId: string
+): NativeChatSkillDiscoveryContext | null {
+  const worktreeId = findTerminalTab(state.tabsByWorktree, terminalTabId)?.worktreeId ?? null
+  if (!worktreeId) {
+    return null
+  }
+  const workspaceScope = parseWorkspaceKey(worktreeId)
+  const cwd =
+    resolveNativeChatSkillDiscoveryCwd(state, terminalTabId) ??
+    (workspaceScope?.type === 'folder'
+      ? state.folderWorkspaces.find(
+          (workspace) => workspace.id === workspaceScope.folderWorkspaceId
+        )?.folderPath
+      : null)
+  if (!cwd) {
+    return null
+  }
+
+  const hostId = getExecutionHostIdForWorktree(state, worktreeId)
+  const parsedHost = parseExecutionHostId(hostId)
+  if (parsedHost?.kind === 'ssh') {
+    return {
+      key: JSON.stringify(['ssh', hostId, cwd]),
+      cwd,
+      executionHostKind: 'ssh',
+      runtimeTarget: { kind: 'local' },
+      discoveryTarget: { cwd, worktreeId }
+    }
+  }
+
+  const runtimeEnvironmentId = getExplicitRuntimeEnvironmentIdForWorktree(state, worktreeId)
+  // Why: a selected global runtime is not proof that it owns this pane. Modern
+  // panes carry an owner stamp; ambiguous legacy panes stay not-ready.
+  if (parsedHost?.kind === 'runtime' && !runtimeEnvironmentId) {
+    return null
+  }
+  const runtimeTarget: RuntimeClientTarget = runtimeEnvironmentId
+    ? { kind: 'environment', environmentId: runtimeEnvironmentId }
+    : { kind: 'local' }
+  const projectRuntime = runtimeEnvironmentId
+    ? undefined
+    : getLocalProjectExecutionRuntimeContext(state, worktreeId)
+  const projectRuntimeKey =
+    projectRuntime?.status === 'resolved'
+      ? projectRuntime.runtime.cacheKey
+      : projectRuntime?.repair.cacheKey
+  return {
+    key: JSON.stringify([
+      runtimeTarget.kind,
+      runtimeTarget.kind === 'environment' ? runtimeTarget.environmentId : null,
+      hostId,
+      projectRuntimeKey ?? null,
+      cwd
+    ]),
+    cwd,
+    executionHostKind: runtimeEnvironmentId ? 'runtime' : 'local',
+    runtimeTarget,
+    // Why: worktreeId lets the owning runtime resolve its own WSL project
+    // preference when this client cannot supply projectRuntime (environment-
+    // owned panes resolve host semantics on the runtime, never here).
+    discoveryTarget: { cwd, worktreeId, ...(projectRuntime ? { projectRuntime } : {}) }
+  }
+}
+
+function findTerminalTab(
+  tabsByWorktree: Record<string, readonly NativeChatSkillTab[]>,
+  terminalTabId: string
+): { worktreeId: string; tab: NativeChatSkillTab } | null {
+  for (const [worktreeId, tabs] of Object.entries(tabsByWorktree)) {
+    const tab = tabs.find((entry) => entry.id === terminalTabId)
+    if (tab) {
+      return { worktreeId, tab }
+    }
+  }
+  return null
+}
diff --git a/src/renderer/src/components/native-chat/use-native-chat-composer-keydown.test.tsx b/src/renderer/src/components/native-chat/use-native-chat-composer-keydown.test.tsx
new file mode 100644
index 00000000000..ed3814e8476
--- /dev/null
+++ b/src/renderer/src/components/native-chat/use-native-chat-composer-keydown.test.tsx
@@ -0,0 +1,99 @@
+// @vitest-environment happy-dom
+
+import { renderHook } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { EMPTY_HISTORY, type ComposerAutocomplete } from './native-chat-composer-state'
+import { useNativeChatComposerKeyDown } from './use-native-chat-composer-keydown'
+
+const COMMAND = {
+  kind: 'command' as const,
+  id: 'command:clear',
+  name: 'clear',
+  description: 'Clear history',
+  skillCollision: false
+}
+
+function picker(items = [COMMAND]): Extract<ComposerAutocomplete, { mode: 'slash' }> {
+  return {
+    mode: 'slash',
+    query: '',
+    items,
+    triggerKey: '/:0',
+    prefix: '/',
+    grouped: false,
+    commandsEnabled: true,
+    skillsEnabled: false,
+    skillStatus: 'ready'
+  }
+}
+
+function setup(autocomplete: ComposerAutocomplete = picker(), composing = false) {
+  const callbacks = {
+    completePickerItem: vi.fn(),
+    dispatchPickerCommand: vi.fn(),
+    dismissPicker: vi.fn(),
+    interrupt: vi.fn(),
+    send: vi.fn(),
+    setActiveSuggestion: vi.fn(),
+    setDraft: vi.fn(),
+    setCaret: vi.fn(),
+    setHistory: vi.fn()
+  }
+  const hook = renderHook(() =>
+    useNativeChatComposerKeyDown({
+      autocomplete,
+      activeSuggestion: 0,
+      draft: '/',
+      history: EMPTY_HISTORY,
+      isComposing: () => composing,
+      ...callbacks
+    })
+  )
+  return { handler: hook.result.current, callbacks }
+}
+
+function keyEvent(key: string, isComposing = false) {
+  return {
+    key,
+    shiftKey: false,
+    keyCode: isComposing ? 229 : 0,
+    nativeEvent: { isComposing },
+    preventDefault: vi.fn()
+  }
+}
+
+describe('useNativeChatComposerKeyDown', () => {
+  it('dispatches command Enter but completes command Tab', () => {
+    const enter = setup()
+    enter.handler(keyEvent('Enter') as never)
+    expect(enter.callbacks.dispatchPickerCommand).toHaveBeenCalledWith(COMMAND)
+    expect(enter.callbacks.completePickerItem).not.toHaveBeenCalled()
+
+    const tab = setup()
+    tab.handler(keyEvent('Tab') as never)
+    expect(tab.callbacks.completePickerItem).toHaveBeenCalledWith(COMMAND)
+    expect(tab.callbacks.dispatchPickerCommand).not.toHaveBeenCalled()
+  })
+
+  it('falls through to composer send when the open picker has no options', () => {
+    const { handler, callbacks } = setup(picker([]))
+    handler(keyEvent('Enter') as never)
+    expect(callbacks.send).toHaveBeenCalledOnce()
+  })
+
+  it('dismisses Escape without interrupting the agent', () => {
+    const { handler, callbacks } = setup()
+    handler(keyEvent('Escape') as never)
+    expect(callbacks.dismissPicker).toHaveBeenCalledWith('/:0')
+    expect(callbacks.interrupt).not.toHaveBeenCalled()
+  })
+
+  it('does not accept or submit while IME composition is active', () => {
+    const { handler, callbacks } = setup(picker(), true)
+    const event = keyEvent('Enter', true)
+    handler(event as never)
+    expect(event.preventDefault).toHaveBeenCalledOnce()
+    expect(callbacks.dispatchPickerCommand).not.toHaveBeenCalled()
+    expect(callbacks.send).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/components/native-chat/use-native-chat-composer-keydown.ts b/src/renderer/src/components/native-chat/use-native-chat-composer-keydown.ts
index ac28aae3482..d287ab4fdce 100644
--- a/src/renderer/src/components/native-chat/use-native-chat-composer-keydown.ts
+++ b/src/renderer/src/components/native-chat/use-native-chat-composer-keydown.ts
@@ -1,22 +1,21 @@
 import { useCallback, type Dispatch, type KeyboardEventHandler, type SetStateAction } from 'react'
-import type { DiscoveredSkill } from '../../../../shared/skills'
 import {
-  applySkillSuggestion,
   recallNext,
   recallPrevious,
   type ComposerAutocomplete,
   type HistoryState,
-  type SlashCommandSuggestion
+  type NativeChatPickerItem
 } from './native-chat-composer-state'
 
 export type UseNativeChatComposerKeyDownArgs = {
   autocomplete: ComposerAutocomplete
   activeSuggestion: number
   draft: string
-  caret: number
   history: HistoryState
-  chooseSlash: (command: SlashCommandSuggestion) => void
-  dispatchSlash: (command: SlashCommandSuggestion) => void
+  isComposing: () => boolean
+  completePickerItem: (item: NativeChatPickerItem) => void
+  dispatchPickerCommand: (item: Extract<NativeChatPickerItem, { kind: 'command' }>) => void
+  dismissPicker: (triggerKey: string) => void
   interrupt: () => void
   send: () => void
   setActiveSuggestion: Dispatch<SetStateAction<number>>
@@ -29,10 +28,11 @@ export function useNativeChatComposerKeyDown({
   autocomplete,
   activeSuggestion,
   draft,
-  caret,
   history,
-  chooseSlash,
-  dispatchSlash,
+  isComposing,
+  completePickerItem,
+  dispatchPickerCommand,
+  dismissPicker,
   interrupt,
   send,
   setActiveSuggestion,
@@ -42,60 +42,40 @@ export function useNativeChatComposerKeyDown({
 }: UseNativeChatComposerKeyDownArgs): KeyboardEventHandler<HTMLTextAreaElement> {
   return useCallback(
     (event) => {
-      if (autocomplete.mode === 'slash' && autocomplete.suggestions.length > 0) {
-        if (event.key === 'ArrowDown') {
-          event.preventDefault()
-          setActiveSuggestion((i) => (i + 1) % autocomplete.suggestions.length)
-          return
-        }
-        if (event.key === 'ArrowUp') {
-          event.preventDefault()
-          setActiveSuggestion(
-            (i) => (i - 1 + autocomplete.suggestions.length) % autocomplete.suggestions.length
-          )
-          return
-        }
+      if (isComposing() || event.nativeEvent.isComposing || event.keyCode === 229) {
+        // Why: IME Enter confirms composition; allowing it to fall through
+        // would accept a picker row or submit a partial draft.
         if (event.key === 'Enter') {
           event.preventDefault()
-          dispatchSlash(autocomplete.suggestions[activeSuggestion] ?? autocomplete.suggestions[0])
-          return
-        }
-        if (event.key === 'Tab') {
-          event.preventDefault()
-          chooseSlash(autocomplete.suggestions[activeSuggestion] ?? autocomplete.suggestions[0])
-          return
-        }
-        if (event.key === 'Escape') {
-          event.preventDefault()
-          setDraft('')
-          setCaret(0)
-          return
         }
+        return
       }
 
-      if (autocomplete.mode === 'skill') {
-        if (event.key === 'ArrowDown' && autocomplete.suggestions.length > 0) {
+      if (autocomplete.mode === 'slash' || autocomplete.mode === 'skill') {
+        const items = autocomplete.items
+        if (event.key === 'ArrowDown' && items.length > 0) {
           event.preventDefault()
-          setActiveSuggestion((i) => (i + 1) % autocomplete.suggestions.length)
+          setActiveSuggestion((index) => (index + 1) % items.length)
           return
         }
-        if (event.key === 'ArrowUp' && autocomplete.suggestions.length > 0) {
+        if (event.key === 'ArrowUp' && items.length > 0) {
           event.preventDefault()
-          setActiveSuggestion(
-            (i) => (i - 1 + autocomplete.suggestions.length) % autocomplete.suggestions.length
-          )
+          setActiveSuggestion((index) => (index - 1 + items.length) % items.length)
           return
         }
-        if ((event.key === 'Enter' || event.key === 'Tab') && autocomplete.suggestions.length > 0) {
+        if ((event.key === 'Enter' || event.key === 'Tab') && items.length > 0) {
           event.preventDefault()
-          const skill = autocomplete.suggestions[activeSuggestion] ?? autocomplete.suggestions[0]
-          applySkill({ skill, draft, caret, setDraft, setCaret, setActiveSuggestion })
+          const item = items[activeSuggestion] ?? items[0]
+          if (event.key === 'Enter' && item.kind === 'command') {
+            dispatchPickerCommand(item)
+          } else {
+            completePickerItem(item)
+          }
           return
         }
         if (event.key === 'Escape') {
           event.preventDefault()
-          setDraft('')
-          setCaret(0)
+          dismissPicker(autocomplete.triggerKey)
           return
         }
       }
@@ -105,13 +85,11 @@ export function useNativeChatComposerKeyDown({
         interrupt()
         return
       }
-
       if (event.key === 'Enter' && !event.shiftKey) {
         event.preventDefault()
         send()
         return
       }
-
       if (event.key === 'ArrowUp' && (draft === '' || history.index !== null)) {
         const recall = recallPrevious(history)
         if (recall.draft !== null) {
@@ -133,15 +111,16 @@ export function useNativeChatComposerKeyDown({
       }
     },
     [
-      autocomplete,
       activeSuggestion,
-      chooseSlash,
-      dispatchSlash,
-      interrupt,
-      send,
+      autocomplete,
+      completePickerItem,
+      dismissPicker,
+      dispatchPickerCommand,
       draft,
-      caret,
       history,
+      interrupt,
+      isComposing,
+      send,
       setActiveSuggestion,
       setCaret,
       setDraft,
@@ -149,24 +128,3 @@ export function useNativeChatComposerKeyDown({
     ]
   )
 }
-
-function applySkill({
-  skill,
-  draft,
-  caret,
-  setDraft,
-  setCaret,
-  setActiveSuggestion
-}: {
-  skill: DiscoveredSkill
-  draft: string
-  caret: number
-  setDraft: Dispatch<SetStateAction<string>>
-  setCaret: Dispatch<SetStateAction<number>>
-  setActiveSuggestion: Dispatch<SetStateAction<number>>
-}): void {
-  const result = applySkillSuggestion(draft, caret, skill.name)
-  setDraft(result.draft)
-  setCaret(result.caret)
-  setActiveSuggestion(0)
-}
diff --git a/src/renderer/src/components/native-chat/use-native-chat-live-session.ts b/src/renderer/src/components/native-chat/use-native-chat-live-session.ts
index bcca032fac7..74a4d12b6c3 100644
--- a/src/renderer/src/components/native-chat/use-native-chat-live-session.ts
+++ b/src/renderer/src/components/native-chat/use-native-chat-live-session.ts
@@ -16,6 +16,8 @@ import {
   reset as resetAssembler
 } from './native-chat-incremental-assembler'
 import { mergeNativeChatLiveSession } from './native-chat-live-status'
+import { getVerifiedNativeChatCommands } from '../../../../shared/native-chat-agent-profiles'
+import { surfaceSkillInvocationUserTurns } from '../../../../shared/native-chat-command-envelope'
 import {
   hasMoreNativeChatHistory,
   NATIVE_CHAT_INITIAL_LIMIT,
@@ -386,9 +388,22 @@ export function useNativeChatLiveSession(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [baseMessages, appended, sessionId, agent])
 
+  // Why: Claude-family harnesses record slash inputs as command envelopes,
+  // which the noise filter hides. A skill invocation is the user's chat turn,
+  // so surface it here — upstream of pending-echo pruning, view state, and the
+  // list — as the literal token; catalog commands keep their `Ran /x` marker.
+  const surfacedMessages = useMemo(
+    () =>
+      surfaceSkillInvocationUserTurns(
+        assembledMessages,
+        new Set(getVerifiedNativeChatCommands(agent).map((command) => command.name))
+      ),
+    [assembledMessages, agent]
+  )
+
   return useMemo<NativeChatLiveSession>(() => {
     const session = mergeNativeChatLiveSession({
-      sources: { transcript: assembledMessages },
+      sources: { transcript: surfacedMessages },
       sessionId,
       agent,
       hookState,
@@ -404,7 +419,7 @@ export function useNativeChatLiveSession(
     })
     return { ...session, hasMore, loadingEarlier, loadEarlier }
   }, [
-    assembledMessages,
+    surfacedMessages,
     read,
     sessionId,
     agent,
diff --git a/src/renderer/src/components/native-chat/use-native-chat-picker-command-dispatch.ts b/src/renderer/src/components/native-chat/use-native-chat-picker-command-dispatch.ts
new file mode 100644
index 00000000000..66f34362fce
--- /dev/null
+++ b/src/renderer/src/components/native-chat/use-native-chat-picker-command-dispatch.ts
@@ -0,0 +1,97 @@
+import { useCallback, type Dispatch, type SetStateAction } from 'react'
+import type { AgentType } from '../../../../shared/agent-status-types'
+import {
+  emitNativeChatMessageSent,
+  emitNativeChatPickerItemAccepted,
+  emitNativeChatSendClassified
+} from '@/lib/native-chat-telemetry'
+import { sendNativeChatMessage } from './native-chat-runtime-send'
+import {
+  nativeChatComposerTargetIsRemote,
+  type NativeChatResolvedTarget
+} from './native-chat-composer-target'
+import {
+  pushHistory,
+  type HistoryState,
+  type NativeChatPickerItem
+} from './native-chat-composer-state'
+import type { NativeChatSendLifecycle } from './use-native-chat-send-lifecycle'
+import type { NativeChatPtySessionOptionsSurface } from './native-chat-pty-session-options'
+
+export function useNativeChatPickerCommandDispatch(args: {
+  agent: AgentType
+  disabled: boolean
+  isDispatchingSessionOption: boolean
+  resolveTarget: () => NativeChatResolvedTarget | null
+  onSlashCommand?: (command: string) => void
+  sessionOptionsSurface: NativeChatPtySessionOptionsSurface | null
+  trackPendingSend: NativeChatSendLifecycle['trackPendingSend']
+  setHistory: Dispatch<SetStateAction<HistoryState>>
+  setDraft: (value: string) => void
+  setCaret: Dispatch<SetStateAction<number>>
+  setActiveSuggestion: Dispatch<SetStateAction<number>>
+  clearSkillOrigin: () => void
+  clearImageAttachments: () => void
+  setNotice: Dispatch<SetStateAction<string | null>>
+}): (command: Extract<NativeChatPickerItem, { kind: 'command' }>) => void {
+  const {
+    agent,
+    disabled,
+    isDispatchingSessionOption,
+    resolveTarget,
+    onSlashCommand,
+    sessionOptionsSurface,
+    trackPendingSend,
+    setHistory,
+    setDraft,
+    setCaret,
+    setActiveSuggestion,
+    clearSkillOrigin,
+    clearImageAttachments,
+    setNotice
+  } = args
+  return useCallback(
+    (command) => {
+      const text = `/${command.name}`
+      const target = resolveTarget()
+      if (!target || disabled || isDispatchingSessionOption) {
+        return
+      }
+      trackPendingSend(sendNativeChatMessage(target.settings, target.ptyId, text))
+      emitNativeChatPickerItemAccepted({ agent, itemKind: 'command' })
+      // Why: picker dispatch is a catalog-verified command send; it must leave
+      // the same telemetry and composer state as the typed path — including
+      // disarming attachments, or a stale image rides the next prompt.
+      emitNativeChatSendClassified({ agent, outcome: 'command' })
+      onSlashCommand?.(text)
+      sessionOptionsSurface?.recordOutgoingCommand(text)
+      emitNativeChatMessageSent({
+        agent,
+        runtime: nativeChatComposerTargetIsRemote(target.ptyId) ? 'remote' : 'local'
+      })
+      setHistory((previous) => pushHistory(previous, text))
+      setDraft('')
+      setCaret(0)
+      setActiveSuggestion(0)
+      clearSkillOrigin()
+      clearImageAttachments()
+      setNotice(null)
+    },
+    [
+      agent,
+      clearImageAttachments,
+      clearSkillOrigin,
+      disabled,
+      isDispatchingSessionOption,
+      onSlashCommand,
+      resolveTarget,
+      sessionOptionsSurface,
+      setActiveSuggestion,
+      setCaret,
+      setDraft,
+      setHistory,
+      setNotice,
+      trackPendingSend
+    ]
+  )
+}
diff --git a/src/renderer/src/components/native-chat/use-native-chat-picker-state.ts b/src/renderer/src/components/native-chat/use-native-chat-picker-state.ts
new file mode 100644
index 00000000000..d66228356a2
--- /dev/null
+++ b/src/renderer/src/components/native-chat/use-native-chat-picker-state.ts
@@ -0,0 +1,198 @@
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type Dispatch,
+  type RefObject,
+  type SetStateAction
+} from 'react'
+import type { AgentType } from '../../../../shared/agent-status-types'
+import { getNativeChatAgentProfile } from '../../../../shared/native-chat-agent-profiles'
+import type { SlashCommandSuggestion } from '../../../../shared/native-chat-slash-commands'
+import {
+  applyPickerSuggestion,
+  classifyNativeChatSend,
+  deriveComposerAutocomplete,
+  editReplacesTriggerToken,
+  type ComposerAutocomplete,
+  type NativeChatPickerItem,
+  type NativeChatSendClassification
+} from './native-chat-composer-state'
+import { useNativeChatSkills } from './use-native-chat-skills'
+import {
+  emitNativeChatPickerItemAccepted,
+  emitNativeChatPickerOpened,
+  emitNativeChatSendClassified
+} from '@/lib/native-chat-telemetry'
+
+export type NativeChatPickerState = {
+  autocomplete: ComposerAutocomplete
+  listboxId: string
+  retrySkills: () => void
+  classifySend: (draft: string) => NativeChatSendClassification
+  clearSkillOrigin: () => void
+  completeItem: (item: NativeChatPickerItem) => void
+  dismiss: (triggerKey: string) => void
+  handleDraftOrCaretChange: (value: string, caret: number) => void
+}
+
+export function useNativeChatPickerState(args: {
+  agent: AgentType
+  terminalTabId: string
+  draftScopeKey: string
+  draft: string
+  caret: number
+  agentCommands: readonly SlashCommandSuggestion[]
+  textareaRef: RefObject<HTMLTextAreaElement | null>
+  setDraft: (value: string) => void
+  setCaret: Dispatch<SetStateAction<number>>
+  setActiveSuggestion: Dispatch<SetStateAction<number>>
+}): NativeChatPickerState {
+  const {
+    agent,
+    terminalTabId,
+    draftScopeKey,
+    draft,
+    caret,
+    agentCommands,
+    textareaRef,
+    setDraft,
+    setCaret,
+    setActiveSuggestion
+  } = args
+  const profile = useMemo(() => getNativeChatAgentProfile(agent), [agent])
+  const beforeCaret = draft.slice(0, caret)
+  const skillPickerTriggered =
+    profile?.skillPrefix === '$'
+      ? /(?:^|\s)\$\S*$/.test(beforeCaret)
+      : profile?.skillPrefix === '/'
+        ? beforeCaret.startsWith('/') && !/\s/.test(beforeCaret)
+        : false
+  const discovery = useNativeChatSkills(agent, terminalTabId, skillPickerTriggered)
+  const listboxId = `native-chat-picker-${useId().replaceAll(':', '')}`
+  const dismissalContext = `${draftScopeKey}:${agent}`
+  const [dismissed, setDismissed] = useState<{ context: string; triggerKey: string } | null>(null)
+  const skillOriginRef = useRef<string | null>(null)
+  const lastOpenKeyRef = useRef<string | null>(null)
+  const autocomplete = useMemo(
+    () =>
+      deriveComposerAutocomplete(
+        draft,
+        caret,
+        agentCommands,
+        discovery.skills,
+        profile,
+        discovery,
+        dismissed?.context === dismissalContext ? dismissed.triggerKey : null
+      ),
+    [agentCommands, caret, dismissalContext, dismissed, discovery, draft, profile]
+  )
+
+  useEffect(() => {
+    // Why: suppression is per-trigger-occurrence AND per-context. The composer
+    // is reused across pane/agent switches, so a stale dismissal must clear or
+    // the picker stays closed for an in-progress token when that context returns.
+    skillOriginRef.current = null
+    setDismissed(null)
+  }, [dismissalContext])
+
+  useEffect(() => {
+    if (autocomplete.mode !== 'slash' && autocomplete.mode !== 'skill') {
+      lastOpenKeyRef.current = null
+      return
+    }
+    const openKey = `${dismissalContext}:${autocomplete.triggerKey}`
+    if (lastOpenKeyRef.current !== openKey) {
+      lastOpenKeyRef.current = openKey
+      emitNativeChatPickerOpened({ agent, prefix: autocomplete.prefix })
+    }
+  }, [agent, autocomplete, dismissalContext])
+
+  const completeItem = useCallback(
+    (item: NativeChatPickerItem) => {
+      if (autocomplete.mode !== 'slash' && autocomplete.mode !== 'skill') {
+        return
+      }
+      const result = applyPickerSuggestion(draft, caret, item, autocomplete.prefix)
+      setDraft(result.draft)
+      setCaret(result.caret)
+      setActiveSuggestion(0)
+      setDismissed(null)
+      skillOriginRef.current = item.kind === 'skill' ? result.insertedToken : null
+      emitNativeChatPickerItemAccepted({ agent, itemKind: item.kind })
+      const textarea = textareaRef.current
+      textarea?.focus()
+      requestAnimationFrame(() => textarea?.setSelectionRange(result.caret, result.caret))
+    },
+    [agent, autocomplete, caret, draft, setActiveSuggestion, setCaret, setDraft, textareaRef]
+  )
+
+  const handleDraftOrCaretChange = useCallback(
+    (value: string, nextCaret: number) => {
+      const firstToken = value.split(/\s/, 1)[0] ?? ''
+      if (skillOriginRef.current && firstToken !== skillOriginRef.current) {
+        skillOriginRef.current = null
+      }
+      if (!dismissed || dismissed.context !== dismissalContext) {
+        return
+      }
+      // Why: a single edit that replaces the dismissed token wholesale (e.g.
+      // select-all + paste) is a new trigger occurrence even though a trigger
+      // character lands back on the same draft position.
+      if (editReplacesTriggerToken(draft, value, dismissed.triggerKey)) {
+        setDismissed(null)
+        return
+      }
+      const next = deriveComposerAutocomplete(
+        value,
+        nextCaret,
+        agentCommands,
+        discovery.skills,
+        profile,
+        discovery
+      )
+      if (
+        (next.mode !== 'slash' && next.mode !== 'skill') ||
+        next.triggerKey !== dismissed.triggerKey
+      ) {
+        setDismissed(null)
+      }
+    },
+    [agentCommands, dismissalContext, dismissed, discovery, draft, profile]
+  )
+
+  const classifySend = useCallback(
+    (value: string) => {
+      const outcome = classifyNativeChatSend(
+        value,
+        agentCommands,
+        skillOriginRef.current,
+        profile?.skillPrefix ?? null
+      )
+      emitNativeChatSendClassified({ agent, outcome })
+      return outcome
+    },
+    [agent, agentCommands, profile]
+  )
+  const clearSkillOrigin = useCallback(() => {
+    skillOriginRef.current = null
+  }, [])
+  const dismiss = useCallback(
+    (triggerKey: string) => setDismissed({ context: dismissalContext, triggerKey }),
+    [dismissalContext]
+  )
+
+  return {
+    autocomplete,
+    listboxId,
+    retrySkills: discovery.retry,
+    classifySend,
+    clearSkillOrigin,
+    completeItem,
+    dismiss,
+    handleDraftOrCaretChange
+  }
+}
diff --git a/src/renderer/src/components/native-chat/use-native-chat-skills.react.test.tsx b/src/renderer/src/components/native-chat/use-native-chat-skills.react.test.tsx
new file mode 100644
index 00000000000..647a07b2f4f
--- /dev/null
+++ b/src/renderer/src/components/native-chat/use-native-chat-skills.react.test.tsx
@@ -0,0 +1,144 @@
+// @vitest-environment happy-dom
+
+import { cleanup, render, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { NativeChatSkillDiscovery } from './use-native-chat-skills'
+
+const mocks = vi.hoisted(() => ({
+  callRuntimeRpc: vi.fn(),
+  state: {} as Record<string, unknown>,
+  snapshots: [] as NativeChatSkillDiscovery[]
+}))
+
+vi.mock('../../store', () => ({
+  useAppStore: (selector: (state: Record<string, unknown>) => unknown) => selector(mocks.state)
+}))
+vi.mock('@/runtime/runtime-rpc-client', () => ({
+  callRuntimeRpc: (...args: unknown[]) => mocks.callRuntimeRpc(...args)
+}))
+vi.mock('@/lib/local-preflight-context', () => ({
+  getLocalProjectExecutionRuntimeContext: () => undefined
+}))
+vi.mock('@/lib/native-chat-telemetry', () => ({ emitNativeChatSkillDiscovery: vi.fn() }))
+
+import {
+  resetNativeChatSkillDiscoveryCacheForTests,
+  useNativeChatSkills
+} from './use-native-chat-skills'
+
+function stateForHost(hostId: string) {
+  return {
+    activeRepoId: 'repo-1',
+    activeWorktreeId: 'worktree-1',
+    folderWorkspaces: [],
+    projectGroups: [],
+    projects: [],
+    repos: [
+      {
+        id: 'repo-1',
+        path: '/repo',
+        connectionId: null,
+        executionHostId: hostId
+      }
+    ],
+    restoredRuntimeHostIdByWorkspaceSessionKey: {},
+    settings: { activeRuntimeEnvironmentId: null },
+    tabsByWorktree: { 'worktree-1': [{ id: 'tab-1' }] },
+    worktreesByRepo: {
+      'repo-1': [{ id: 'worktree-1', repoId: 'repo-1', path: '/repo/worktree', hostId }]
+    }
+  }
+}
+
+function Probe({ enabled }: { enabled: boolean }): null {
+  mocks.snapshots.push(useNativeChatSkills('codex', 'tab-1', enabled))
+  return null
+}
+
+describe('useNativeChatSkills', () => {
+  beforeEach(() => {
+    mocks.state = stateForHost('local')
+    mocks.snapshots = []
+    mocks.callRuntimeRpc.mockReset()
+    mocks.callRuntimeRpc.mockResolvedValue({
+      skills: [
+        {
+          id: 'browser',
+          name: 'browser',
+          description: null,
+          providers: ['agent-skills'],
+          sourceKind: 'home',
+          sourceLabel: 'Agent skills home',
+          rootPath: '/home/test/.agents/skills',
+          directoryPath: '/home/test/.agents/skills/browser',
+          skillFilePath: '/home/test/.agents/skills/browser/SKILL.md',
+          installed: true,
+          fileCount: 1,
+          updatedAt: null
+        }
+      ],
+      sources: [
+        {
+          id: 'home-agents',
+          label: 'Agent skills home',
+          path: '/home/test/.agents/skills',
+          sourceKind: 'home',
+          providers: ['agent-skills'],
+          owner: null,
+          exists: true
+        }
+      ],
+      scannedAt: 1
+    })
+    resetNativeChatSkillDiscoveryCacheForTests()
+  })
+
+  afterEach(() => cleanup())
+
+  it('starts lazily and exposes loading separately from ready results', async () => {
+    const view = render(<Probe enabled={false} />)
+    expect(mocks.callRuntimeRpc).not.toHaveBeenCalled()
+    expect(mocks.snapshots.at(-1)?.status).toBe('idle')
+
+    view.rerender(<Probe enabled />)
+    expect(mocks.snapshots.at(-1)?.status).toBe('loading')
+    await waitFor(() => expect(mocks.snapshots.at(-1)?.status).toBe('ready'))
+    expect(mocks.snapshots.at(-1)?.skills.map((skill) => skill.name)).toEqual(['browser'])
+    expect(mocks.callRuntimeRpc).toHaveBeenCalledWith(
+      { kind: 'local' },
+      'skills.discover',
+      { cwd: '/repo/worktree', worktreeId: 'worktree-1' },
+      { timeoutMs: 10_000 }
+    )
+  })
+
+  it('shares one in-flight request between sibling panes', async () => {
+    render(
+      <>
+        <Probe enabled />
+        <Probe enabled />
+      </>
+    )
+    await waitFor(() => expect(mocks.snapshots.at(-1)?.status).toBe('ready'))
+    expect(mocks.callRuntimeRpc).toHaveBeenCalledTimes(1)
+  })
+
+  it('marks SSH discovery unavailable without scanning another host', async () => {
+    mocks.state = stateForHost('ssh:connection-1')
+    render(<Probe enabled />)
+    await waitFor(() => expect(mocks.snapshots.at(-1)?.errorKind).toBe('unavailable'))
+    expect(mocks.callRuntimeRpc).not.toHaveBeenCalled()
+  })
+
+  it('routes runtime-owned panes through their saved environment', async () => {
+    mocks.state = stateForHost('runtime:env-1')
+    render(<Probe enabled />)
+    await waitFor(() => expect(mocks.snapshots.at(-1)?.status).toBe('ready'))
+    expect(mocks.callRuntimeRpc).toHaveBeenCalledWith(
+      { kind: 'environment', environmentId: 'env-1' },
+      'skills.discover',
+      { cwd: '/repo/worktree', worktreeId: 'worktree-1' },
+      { timeoutMs: 10_000 }
+    )
+  })
+})
diff --git a/src/renderer/src/components/native-chat/use-native-chat-skills.test.ts b/src/renderer/src/components/native-chat/use-native-chat-skills.test.ts
index 9efe7a23d0e..7154abb1043 100644
--- a/src/renderer/src/components/native-chat/use-native-chat-skills.test.ts
+++ b/src/renderer/src/components/native-chat/use-native-chat-skills.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import type { DiscoveredSkill } from '../../../../shared/skills'
+import type { DiscoveredSkill, SkillDiscoveryResult } from '../../../../shared/skills'
 import {
   isNativeChatSkillForAgent,
   resolveNativeChatSkillDiscoveryCwd
@@ -23,6 +23,22 @@ function skill(overrides: Partial<DiscoveredSkill>): DiscoveredSkill {
   }
 }
 
+function discovery(owner: string | null, rootPath = '/Users/test/.agents/skills') {
+  return {
+    sources: [
+      {
+        id: 'source',
+        label: 'Source',
+        path: rootPath,
+        sourceKind: 'home' as const,
+        providers: ['agent-skills' as const],
+        owner,
+        exists: true
+      }
+    ]
+  } satisfies Pick<SkillDiscoveryResult, 'sources'>
+}
+
 describe('isNativeChatSkillForAgent', () => {
   it('shows Codex-native and generic agent skills for Codex chat', () => {
     expect(isNativeChatSkillForAgent('codex', skill({ providers: ['codex'] }))).toBe(true)
@@ -36,6 +52,59 @@ describe('isNativeChatSkillForAgent', () => {
   it('does not enable skill autocomplete for other agents yet', () => {
     expect(isNativeChatSkillForAgent('claude', skill({ providers: ['agent-skills'] }))).toBe(false)
   })
+
+  it('uses explicit source ownership and keeps shared roots visible', () => {
+    const shared = discovery(null)
+    expect(isNativeChatSkillForAgent('codex', skill({}), shared)).toBe(true)
+    expect(isNativeChatSkillForAgent('claude', skill({}), shared)).toBe(true)
+    expect(isNativeChatSkillForAgent('grok', skill({}), shared)).toBe(true)
+  })
+
+  it('aliases OpenClaude to Claude roots without exposing them to other agents', () => {
+    const claude = discovery('claude')
+    expect(isNativeChatSkillForAgent('claude', skill({}), claude)).toBe(true)
+    expect(isNativeChatSkillForAgent('openclaude', skill({}), claude)).toBe(true)
+    expect(isNativeChatSkillForAgent('codex', skill({}), claude)).toBe(false)
+    expect(isNativeChatSkillForAgent('grok', skill({}), claude)).toBe(false)
+  })
+
+  it('grants visibility through any contributing root, not just the dedup survivor', () => {
+    const result = {
+      sources: [
+        {
+          id: 'codex-home',
+          label: 'Codex home',
+          path: '/Users/test/.codex/skills',
+          sourceKind: 'home' as const,
+          providers: ['codex' as const],
+          owner: 'codex',
+          exists: true
+        },
+        {
+          id: 'shared-home',
+          label: 'Agent skills home',
+          path: '/Users/test/.agents/skills',
+          sourceKind: 'home' as const,
+          providers: ['agent-skills' as const],
+          owner: null,
+          exists: true
+        }
+      ]
+    } satisfies Pick<SkillDiscoveryResult, 'sources'>
+    // A symlinked skill deduped under the Codex root but also reachable
+    // through the shared root stays visible to every agent.
+    const merged = skill({
+      rootPath: '/Users/test/.codex/skills',
+      rootPaths: ['/Users/test/.codex/skills', '/Users/test/.agents/skills']
+    })
+    expect(isNativeChatSkillForAgent('claude', merged, result)).toBe(true)
+    expect(isNativeChatSkillForAgent('codex', merged, result)).toBe(true)
+    const codexOnly = skill({
+      rootPath: '/Users/test/.codex/skills',
+      rootPaths: ['/Users/test/.codex/skills']
+    })
+    expect(isNativeChatSkillForAgent('claude', codexOnly, result)).toBe(false)
+  })
 })
 
 describe('resolveNativeChatSkillDiscoveryCwd', () => {
@@ -69,4 +138,23 @@ describe('resolveNativeChatSkillDiscoveryCwd', () => {
       resolveNativeChatSkillDiscoveryCwd({ tabsByWorktree: {}, worktreesByRepo: {} }, 'tab-1')
     ).toBeNull()
   })
+
+  it('prefers the pane startupCwd over the worktree root', () => {
+    expect(
+      resolveNativeChatSkillDiscoveryCwd(
+        {
+          tabsByWorktree: {
+            'repo-1::/repo/worktree': [
+              { id: 'tab-1', startupCwd: '/repo/worktree/packages/app' },
+              { id: 'tab-2' }
+            ]
+          },
+          worktreesByRepo: {
+            'repo-1': [{ id: 'repo-1::/repo/worktree', path: '/repo/worktree' }]
+          }
+        },
+        'tab-1'
+      )
+    ).toBe('/repo/worktree/packages/app')
+  })
 })
diff --git a/src/renderer/src/components/native-chat/use-native-chat-skills.ts b/src/renderer/src/components/native-chat/use-native-chat-skills.ts
index 04327478956..42c7702d017 100644
--- a/src/renderer/src/components/native-chat/use-native-chat-skills.ts
+++ b/src/renderer/src/components/native-chat/use-native-chat-skills.ts
@@ -1,71 +1,249 @@
-import { useEffect, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useShallow } from 'zustand/react/shallow'
 import { useAppStore } from '../../store'
 import type { AgentType } from '../../../../shared/agent-status-types'
-import type { DiscoveredSkill } from '../../../../shared/skills'
+import type { DiscoveredSkill, SkillDiscoveryResult } from '../../../../shared/skills'
+import { getNativeChatAgentProfile } from '../../../../shared/native-chat-agent-profiles'
+import { callRuntimeRpc } from '@/runtime/runtime-rpc-client'
+import { emitNativeChatSkillDiscovery } from '@/lib/native-chat-telemetry'
+import {
+  resolveNativeChatSkillDiscoveryContext,
+  selectNativeChatSkillStateInputs,
+  type NativeChatSkillDiscoveryContext
+} from './native-chat-skill-discovery-context'
 
-type NativeChatSkillWorktreeState = {
-  tabsByWorktree: Record<string, readonly { id: string }[]>
-  worktreesByRepo: Record<string, readonly { id: string; path: string }[]>
+export {
+  resolveNativeChatSkillDiscoveryContext,
+  resolveNativeChatSkillDiscoveryCwd
+} from './native-chat-skill-discovery-context'
+
+// The host scan budget honored by runtime targets that respect timeoutMs.
+const DISCOVERY_TIMEOUT_MS = 10_000
+// Renderer wall-clock backstop for the local branch (which ignores timeoutMs).
+// It must exceed the host's summed worst case — a WSL scan runs a metadata read
+// (5s) then the tree walk (10s) in sequence — so the host's own precise timeout
+// wins and a WSL cold boot does not surface a healthy scan as a spurious timeout.
+const DISCOVERY_BACKSTOP_TIMEOUT_MS = 18_000
+
+export type NativeChatSkillDiscovery = {
+  status: 'idle' | 'loading' | 'ready' | 'error'
+  skills: DiscoveredSkill[]
+  error: Error | null
+  errorKind?: 'unavailable' | 'timeout' | 'host' | 'unknown'
+  retry: () => void
 }
 
-export function isNativeChatSkillForAgent(agent: AgentType, skill: DiscoveredSkill): boolean {
-  if (agent !== 'codex') {
+type StoredDiscoveryState = Omit<NativeChatSkillDiscovery, 'retry'> & {
+  contextKey: string | null
+}
+
+const IDLE_STATE: StoredDiscoveryState = {
+  status: 'idle',
+  skills: [],
+  error: null,
+  contextKey: null
+}
+const inFlightDiscovery = new Map<string, Promise<SkillDiscoveryResult>>()
+
+export function isNativeChatSkillForAgent(
+  agent: AgentType,
+  skill: DiscoveredSkill,
+  result?: Pick<SkillDiscoveryResult, 'sources'>
+): boolean {
+  const profile = getNativeChatAgentProfile(agent)
+  if (!profile) {
     return false
   }
-  // Why: Codex sessions can see both Codex-native skills and generic agent
-  // skills (for example ~/.agents/skills), so the picker should mirror that.
-  return skill.providers.includes('codex') || skill.providers.includes('agent-skills')
+  if (!result) {
+    return (
+      agent === 'codex' &&
+      (skill.providers.includes('codex') || skill.providers.includes('agent-skills'))
+    )
+  }
+  // Why: canonical-path dedup keeps one row per file, but a symlinked skill can
+  // be reachable through several roots; any shared or agent-owned root grants
+  // visibility regardless of which root the scanner happened to list first.
+  const rootPaths = skill.rootPaths?.length ? skill.rootPaths : [skill.rootPath]
+  return rootPaths.some((rootPath) => {
+    const source = result.sources.find((entry) => entry.path === rootPath)
+    return source?.owner === null || source?.owner === profile.skillSourceOwner
+  })
 }
 
-export function resolveNativeChatSkillDiscoveryCwd(
-  state: NativeChatSkillWorktreeState,
-  terminalTabId: string
-): string | null {
-  let ownerWorktreeId: string | null = null
-  for (const [worktreeId, tabs] of Object.entries(state.tabsByWorktree)) {
-    if (tabs.some((tab) => tab.id === terminalTabId)) {
-      ownerWorktreeId = worktreeId
-      break
-    }
-  }
-  if (!ownerWorktreeId) {
-    return null
-  }
-  for (const worktrees of Object.values(state.worktreesByRepo)) {
-    const worktree = worktrees.find((entry) => entry.id === ownerWorktreeId)
-    if (worktree) {
-      return worktree.path
-    }
-  }
-  return null
-}
-
-export function useNativeChatSkills(agent: AgentType, terminalTabId: string): DiscoveredSkill[] {
-  const [skills, setSkills] = useState<DiscoveredSkill[]>([])
-  const cwd = useAppStore((state) => resolveNativeChatSkillDiscoveryCwd(state, terminalTabId))
+export function useNativeChatSkills(
+  agent: AgentType,
+  terminalTabId: string,
+  enabled = false
+): NativeChatSkillDiscovery {
+  const inputs = useAppStore(useShallow(selectNativeChatSkillStateInputs))
+  const context = useMemo(
+    () => resolveNativeChatSkillDiscoveryContext(inputs, terminalTabId),
+    [inputs, terminalTabId]
+  )
+  const [state, setState] = useState<StoredDiscoveryState>(IDLE_STATE)
+  const [retryGeneration, setRetryGeneration] = useState(0)
+  const paneDiscoveryCache = useRef(new Map<string, SkillDiscoveryResult>())
+  const profile = getNativeChatAgentProfile(agent)
 
   useEffect(() => {
     let cancelled = false
-    if (agent !== 'codex') {
-      setSkills([])
+    if (!profile || !enabled || !context) {
+      setState(IDLE_STATE)
       return
     }
-    void window.api.skills
-      .discover(cwd ? { cwd } : undefined)
-      .then((result) => {
-        if (!cancelled) {
-          setSkills(result.skills.filter((skill) => isNativeChatSkillForAgent(agent, skill)))
-        }
+    if (context.executionHostKind === 'ssh') {
+      emitNativeChatSkillDiscovery({
+        agent,
+        outcome: 'unavailable',
+        executionHostKind: 'ssh'
       })
-      .catch(() => {
-        if (!cancelled) {
-          setSkills([])
-        }
+      setState({
+        status: 'error',
+        skills: [],
+        error: new Error('Skill discovery is unavailable for SSH hosts.'),
+        errorKind: 'unavailable',
+        contextKey: context.key
       })
+      return
+    }
+
+    const paneCacheKey = context.key
+    const cached = paneDiscoveryCache.current.get(paneCacheKey)
+    if (cached) {
+      emitNativeChatSkillDiscovery({
+        agent,
+        outcome: 'ready',
+        executionHostKind: context.executionHostKind
+      })
+      setState({ status: 'ready', skills: cached.skills, error: null, contextKey: context.key })
+      return
+    }
+    setState({ status: 'loading', skills: [], error: null, contextKey: context.key })
+    const request = getOrStartDiscovery(context)
+    void request.then(
+      (result) => {
+        paneDiscoveryCache.current.set(paneCacheKey, result)
+        if (cancelled) {
+          return
+        }
+        emitNativeChatSkillDiscovery({
+          agent,
+          outcome: 'ready',
+          executionHostKind: context.executionHostKind
+        })
+        setState({ status: 'ready', skills: result.skills, error: null, contextKey: paneCacheKey })
+      },
+      (reason) => {
+        if (cancelled) {
+          return
+        }
+        const error = reason instanceof Error ? reason : new Error(String(reason))
+        const timedOut = /timed?\s*out|timeout/i.test(error.message)
+        emitNativeChatSkillDiscovery({
+          agent,
+          outcome: timedOut ? 'timeout' : 'error',
+          executionHostKind: context.executionHostKind
+        })
+        setState({
+          status: 'error',
+          skills: [],
+          error,
+          errorKind: timedOut
+            ? 'timeout'
+            : context.executionHostKind === 'runtime'
+              ? 'host'
+              : 'unknown',
+          contextKey: paneCacheKey
+        })
+      }
+    )
     return () => {
       cancelled = true
     }
-  }, [agent, cwd])
+  }, [agent, context, enabled, profile, retryGeneration])
 
-  return skills
+  const effectiveState = useMemo(
+    () =>
+      !profile || !enabled || !context
+        ? IDLE_STATE
+        : state.contextKey === context.key
+          ? state
+          : { status: 'loading' as const, skills: [], error: null, contextKey: context.key },
+    [context, enabled, profile, state]
+  )
+  const visibleSkills = useMemo(() => {
+    if (!profile || effectiveState.status !== 'ready') {
+      return []
+    }
+    const result = context ? paneDiscoveryCache.current.get(context.key) : undefined
+    return result
+      ? effectiveState.skills.filter((skill) => isNativeChatSkillForAgent(agent, skill, result))
+      : []
+  }, [agent, context, effectiveState, profile])
+
+  const retry = useCallback(() => {
+    if (context) {
+      paneDiscoveryCache.current.delete(context.key)
+      setState({ status: 'loading', skills: [], error: null, contextKey: context.key })
+    }
+    setRetryGeneration((generation) => generation + 1)
+  }, [context])
+  return useMemo(
+    () => ({
+      status: effectiveState.status,
+      skills: visibleSkills,
+      error: effectiveState.error,
+      ...(effectiveState.errorKind ? { errorKind: effectiveState.errorKind } : {}),
+      retry
+    }),
+    [effectiveState, retry, visibleSkills]
+  )
+}
+
+function getOrStartDiscovery(
+  context: NativeChatSkillDiscoveryContext
+): Promise<SkillDiscoveryResult> {
+  const existing = inFlightDiscovery.get(context.key)
+  if (existing) {
+    return existing
+  }
+  // Why: the local runtime.call branch ignores timeoutMs, so the renderer must
+  // enforce the design's scan timeout itself or a stalled local scan loads forever.
+  const request = withDiscoveryTimeout(
+    callRuntimeRpc<SkillDiscoveryResult>(
+      context.runtimeTarget,
+      'skills.discover',
+      context.discoveryTarget,
+      {
+        timeoutMs: DISCOVERY_TIMEOUT_MS
+      }
+    ),
+    DISCOVERY_BACKSTOP_TIMEOUT_MS
+  ).finally(() => {
+    if (inFlightDiscovery.get(context.key) === request) {
+      inFlightDiscovery.delete(context.key)
+    }
+  })
+  inFlightDiscovery.set(context.key, request)
+  return request
+}
+
+function withDiscoveryTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('Skill discovery timed out.')), timeoutMs)
+    promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (reason) => {
+        clearTimeout(timer)
+        reject(reason)
+      }
+    )
+  })
+}
+
+export function resetNativeChatSkillDiscoveryCacheForTests(): void {
+  inFlightDiscovery.clear()
 }
diff --git a/src/renderer/src/components/native-chat/use-native-chat-typed-insertion.ts b/src/renderer/src/components/native-chat/use-native-chat-typed-insertion.ts
new file mode 100644
index 00000000000..c82e808e9fa
--- /dev/null
+++ b/src/renderer/src/components/native-chat/use-native-chat-typed-insertion.ts
@@ -0,0 +1,50 @@
+import { useCallback, type Dispatch, type RefObject, type SetStateAction } from 'react'
+import type { HistoryState } from './native-chat-composer-state'
+
+/** Imperative text insertion and focus for the composer textarea, used by the
+ *  paste pipeline and the composer's imperative handle. */
+export function useNativeChatTypedInsertion(args: {
+  textareaRef: RefObject<HTMLTextAreaElement | null>
+  caret: number
+  draft: string
+  setDraft: (value: string) => void
+  setCaret: Dispatch<SetStateAction<number>>
+  setHistory: Dispatch<SetStateAction<HistoryState>>
+  setActiveSuggestion: Dispatch<SetStateAction<number>>
+}): { insertTypedText: (text: string) => boolean; focus: () => boolean } {
+  const { textareaRef, caret, draft, setDraft, setCaret, setHistory, setActiveSuggestion } = args
+
+  const insertTypedText = useCallback(
+    (text: string): boolean => {
+      const textarea = textareaRef.current
+      if (!textarea || textarea.disabled) {
+        return false
+      }
+      const selectionStart = textarea.selectionStart ?? caret
+      const selectionEnd = textarea.selectionEnd ?? selectionStart
+      const next = `${draft.slice(0, selectionStart)}${text}${draft.slice(selectionEnd)}`
+      const nextCaret = selectionStart + text.length
+      textarea.focus()
+      setDraft(next)
+      setCaret(nextCaret)
+      setHistory((prev) => ({ entries: prev.entries, index: null }))
+      setActiveSuggestion(0)
+      requestAnimationFrame(() => {
+        textarea.setSelectionRange(nextCaret, nextCaret)
+      })
+      return true
+    },
+    [caret, draft, setActiveSuggestion, setCaret, setDraft, setHistory, textareaRef]
+  )
+
+  const focus = useCallback((): boolean => {
+    const textarea = textareaRef.current
+    if (!textarea || textarea.disabled) {
+      return false
+    }
+    textarea.focus()
+    return true
+  }, [textareaRef])
+
+  return { insertTypedText, focus }
+}
diff --git a/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.ts b/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.ts
index 12fe7d1bf00..c0354249fc5 100644
--- a/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.ts
+++ b/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.ts
@@ -119,7 +119,7 @@ export function useCloseWith({
         const total = Math.max(0, Date.now() - startTimeRef.current)
         // Why: no `is_git_repo` — project selection now happens in the Add
         // Project modal after this fires, so the signal moved to
-        // `repo_added.is_git_repo`. See docs/reference/telemetry-availability.md.
+        // `repo_added.is_git_repo`.
         track('onboarding_completed', {
           path: completedPath,
           total_duration_ms: total
diff --git a/src/renderer/src/components/terminal-pane/agent-task-complete-policy.ts b/src/renderer/src/components/terminal-pane/agent-task-complete-policy.ts
index 7b08ca0c5c1..6275cc9553c 100644
--- a/src/renderer/src/components/terminal-pane/agent-task-complete-policy.ts
+++ b/src/renderer/src/components/terminal-pane/agent-task-complete-policy.ts
@@ -3,8 +3,7 @@
  *
  * Why extracted from pty-connection.ts: the parked byte watcher and the
  * pty:sideEffect facts handler apply the exact live-path semantics without a
- * pane, and policy must not drift between the three consumers
- * (docs/reference/terminal-side-effect-authority.md). This module is
+ * pane, and policy must not drift between the three consumers. This module is
  * deliberately dependency-light — no pane/xterm imports — so pane-less
  * consumers can use it.
  */
diff --git a/src/renderer/src/components/terminal-pane/parked-terminal-byte-watcher.ts b/src/renderer/src/components/terminal-pane/parked-terminal-byte-watcher.ts
index c4907718589..359f8815b68 100644
--- a/src/renderer/src/components/terminal-pane/parked-terminal-byte-watcher.ts
+++ b/src/renderer/src/components/terminal-pane/parked-terminal-byte-watcher.ts
@@ -11,8 +11,7 @@
  * gate ON answers from main's '2031-subscribe' fact (no parked bytes exist),
  * gate OFF keeps the byte sidecar (parked-terminal-mode2031-responder.ts).
  * Either way the reply is sent from the renderer — query authority never
- * moves to main. See docs/reference/terminal-hidden-view-parking.md and
- * docs/reference/terminal-side-effect-authority.md.
+ * moves to main.
  */
 import { isClaudeAgent } from '../../../../shared/agent-detection'
 import { makePaneKey } from '../../../../shared/stable-pane-id'
diff --git a/src/renderer/src/components/terminal-pane/pty-delivery-interest.ts b/src/renderer/src/components/terminal-pane/pty-delivery-interest.ts
index a695b77d82f..56519c09e90 100644
--- a/src/renderer/src/components/terminal-pane/pty-delivery-interest.ts
+++ b/src/renderer/src/components/terminal-pane/pty-delivery-interest.ts
@@ -1,6 +1,6 @@
 /**
  * Renderer-side delivery-interest registry for the Phase-4 hidden-delivery
- * gate (docs/reference/terminal-side-effect-authority.md, Open Items).
+ * gate.
  *
  * Why: main only drops hidden PTY byte delivery while NO renderer party needs
  * raw bytes. Dispatcher sidecars and eager pre-mount buffers register
diff --git a/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts b/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts
index 5926cc8c153..d58460161ab 100644
--- a/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts
@@ -8,7 +8,6 @@
  * reveal, tab close, PTY exit, or worktree teardown. The bookkeeping maps
  * live in terminal-parked-watcher-registry so the terminals store slice can
  * dispose watchers without importing this store-coupled module.
- * See docs/reference/terminal-hidden-view-parking.md.
  */
 import { isTerminalLeafId } from '../../../../shared/stable-pane-id'
 import type { TerminalTab } from '../../../../shared/types'
diff --git a/src/renderer/src/components/terminal-pane/terminal-side-effect-facts-handler.ts b/src/renderer/src/components/terminal-pane/terminal-side-effect-facts-handler.ts
index 06d80b03754..d9f3c8d7d31 100644
--- a/src/renderer/src/components/terminal-pane/terminal-side-effect-facts-handler.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-side-effect-facts-handler.ts
@@ -1,8 +1,8 @@
 /**
  * Renderer consumer registry for the `pty:sideEffect` channel.
  *
- * Why: with main as the side-effect parser for local-daemon/SSH PTYs
- * (docs/reference/terminal-side-effect-authority.md), the renderer no longer
+ * Why: with main as the side-effect parser for local-daemon/SSH PTYs, the
+ * renderer no longer
  * derives title/bell/agent facts from bytes for those PTYs. This module is
  * the single channel subscriber; mounted panes and parked-tab watchers
  * register exactly one fact consumer per PTY (their existing policy
diff --git a/src/renderer/src/components/terminal-pane/terminal-view-attributes-publisher.ts b/src/renderer/src/components/terminal-pane/terminal-view-attributes-publisher.ts
index 304ff399f6c..aeecb1a6f48 100644
--- a/src/renderer/src/components/terminal-pane/terminal-view-attributes-publisher.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-view-attributes-publisher.ts
@@ -1,6 +1,6 @@
 /**
- * Phase 5 slice 2 (docs/reference/terminal-query-authority.md §View-attribute
- * bridge): renderer→main `pty:terminalViewAttributes` publication. Composes
+ * Phase 5 slice 2 (View-attribute bridge): renderer→main
+ * `pty:terminalViewAttributes` publication. Composes
  * the reply-relevant slots of the active terminal theme exactly the way
  * xterm's browser ThemeService resolves an ITheme (defaults, cursor blend,
  * 256-entry palette), so main's hidden-PTY responder replies byte-identically
diff --git a/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.ts b/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.ts
index 56172164490..fa7de03116e 100644
--- a/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.ts
+++ b/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.ts
@@ -4,7 +4,7 @@
  * Why: owns the cold-park policy bookkeeping (hiddenSince tracking, recheck
  * timers, parked-set selection) and the parked byte-watcher reconciliation so
  * the overlay layer only consumes the final parked tab set when deciding to
- * render a slot as null. See docs/reference/terminal-hidden-view-parking.md.
+ * render a slot as null.
  */
 import { useEffect, useMemo, useRef, useState } from 'react'
 import type { TerminalTab } from '../../../../shared/types'
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 427fa58d0e5..c6bafdd07a6 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -13436,6 +13436,21 @@
         "startDictation": "Start dictation",
         "stopDictation": "Stop dictation",
         "noSkills": "No matching skills",
+        "noCommandsOrSkills": "No matching commands or skills",
+        "noCommands": "No matching commands",
+        "commands": "Commands",
+        "skills": "Skills",
+        "loadingSkills": "Loading skills...",
+        "skillsLoaded": "Skills loaded",
+        "skillsUnavailableHost": "Skills are unavailable for this host",
+        "skillsLoadFailed": "Could not load skills from this host",
+        "retrySkills": "Retry",
+        "skillCommandCollision": "Also a skill name - agent decides",
+        "skillMultipleSources": "{{sourceCount}} sources - agent resolves",
+        "skillScopeProject": "Project",
+        "skillScopePersonal": "Personal",
+        "skillScopeBuiltIn": "Built-in",
+        "skillScopePlugin": "Plugin",
         "localAttachmentUnsupported": "Local attachments are not available for remote sessions.",
         "removeAttachment": "Remove attachment",
         "pastedImageLabel": "Pasted image",
diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json
index c7e2e7ccc1c..62827c20dec 100644
--- a/src/renderer/src/i18n/locales/es.json
+++ b/src/renderer/src/i18n/locales/es.json
@@ -13443,7 +13443,22 @@
           "max": "Máximo",
           "on": "Activado",
           "off": "Desactivado"
-        }
+        },
+        "noCommandsOrSkills": "No hay comandos o habilidades coincidentes",
+        "commands": "Comandos",
+        "skills": "Habilidades",
+        "loadingSkills": "Cargando habilidades…",
+        "skillsUnavailableHost": "Las habilidades no están disponibles para este host",
+        "skillsLoadFailed": "No se pudieron cargar las habilidades de este host",
+        "retrySkills": "Reintentar",
+        "skillCommandCollision": "También es un nombre de habilidad - el agente decide",
+        "skillMultipleSources": "{{sourceCount}} fuentes - el agente resuelve",
+        "skillScopeProject": "Proyecto",
+        "skillScopePersonal": "Personal",
+        "skillScopeBuiltIn": "Integrado",
+        "skillScopePlugin": "Plugin",
+        "skillsLoaded": "Habilidades cargadas",
+        "noCommands": "No hay comandos coincidentes"
       },
       "tool": {
         "running": "Ejecutando…",
diff --git a/src/renderer/src/i18n/locales/ja.json b/src/renderer/src/i18n/locales/ja.json
index 6c4390633c4..d1c9f5e043c 100644
--- a/src/renderer/src/i18n/locales/ja.json
+++ b/src/renderer/src/i18n/locales/ja.json
@@ -13443,7 +13443,22 @@
           "max": "最大",
           "on": "オン",
           "off": "オフ"
-        }
+        },
+        "noCommandsOrSkills": "一致するコマンドやスキルがありません",
+        "commands": "コマンド",
+        "skills": "スキル",
+        "loadingSkills": "スキルを読み込み中…",
+        "skillsUnavailableHost": "このホストではスキルが利用できません",
+        "skillsLoadFailed": "このホストからスキルを読み込めませんでした",
+        "retrySkills": "再試行",
+        "skillCommandCollision": "スキル名でもあります - エージェントが判断します",
+        "skillMultipleSources": "{{sourceCount}} 個のソース - エージェントが解決します",
+        "skillScopeProject": "プロジェクト",
+        "skillScopePersonal": "個人",
+        "skillScopeBuiltIn": "組み込み",
+        "skillScopePlugin": "プラグイン",
+        "skillsLoaded": "スキルを読み込みました",
+        "noCommands": "一致するコマンドがありません"
       },
       "tool": {
         "running": "実行中…",
diff --git a/src/renderer/src/i18n/locales/ko.json b/src/renderer/src/i18n/locales/ko.json
index 5da5129544d..875dafd5756 100644
--- a/src/renderer/src/i18n/locales/ko.json
+++ b/src/renderer/src/i18n/locales/ko.json
@@ -13443,7 +13443,22 @@
           "max": "최대",
           "on": "켜짐",
           "off": "꺼짐"
-        }
+        },
+        "noCommandsOrSkills": "일치하는 명령어 또는 스킬이 없습니다",
+        "commands": "명령어",
+        "skills": "스킬",
+        "loadingSkills": "스킬 로딩 중…",
+        "skillsUnavailableHost": "이 호스트에서는 스킬을 사용할 수 없습니다",
+        "skillsLoadFailed": "이 호스트에서 스킬을 불러올 수 없습니다",
+        "retrySkills": "재시도",
+        "skillCommandCollision": "스킬 이름이기도 합니다 - 에이전트가 결정합니다",
+        "skillMultipleSources": "{{sourceCount}}개 소스 - 에이전트가 해결합니다",
+        "skillScopeProject": "프로젝트",
+        "skillScopePersonal": "개인",
+        "skillScopeBuiltIn": "내장",
+        "skillScopePlugin": "플러그인",
+        "skillsLoaded": "스킬 로드 완료",
+        "noCommands": "일치하는 명령어가 없습니다"
       },
       "tool": {
         "running": "실행 중…",
diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json
index be2ed642cc5..3716898ceb2 100644
--- a/src/renderer/src/i18n/locales/zh.json
+++ b/src/renderer/src/i18n/locales/zh.json
@@ -13443,7 +13443,22 @@
           "max": "最大",
           "on": "开",
           "off": "关"
-        }
+        },
+        "noCommandsOrSkills": "没有匹配的命令或技能",
+        "commands": "命令",
+        "skills": "技能",
+        "loadingSkills": "正在加载技能…",
+        "skillsUnavailableHost": "此主机不可用技能",
+        "skillsLoadFailed": "无法从此主机加载技能",
+        "retrySkills": "重试",
+        "skillCommandCollision": "也是技能名称 - 由代理决定",
+        "skillMultipleSources": "{{sourceCount}} 个来源 - 由代理解析",
+        "skillScopeProject": "项目",
+        "skillScopePersonal": "个人",
+        "skillScopeBuiltIn": "内置",
+        "skillScopePlugin": "插件",
+        "skillsLoaded": "技能已加载",
+        "noCommands": "没有匹配的命令"
       },
       "tool": {
         "running": "正在运行…",
diff --git a/src/renderer/src/lib/native-chat-telemetry.ts b/src/renderer/src/lib/native-chat-telemetry.ts
index efc6e90d33e..0d6f96584d2 100644
--- a/src/renderer/src/lib/native-chat-telemetry.ts
+++ b/src/renderer/src/lib/native-chat-telemetry.ts
@@ -58,3 +58,45 @@ export function emitNativeChatMessageSent(args: {
     runtime: args.runtime
   })
 }
+
+export function emitNativeChatPickerOpened(args: {
+  agent: NativeChatTelemetryAgent
+  prefix: '/' | '$'
+}): void {
+  track('native_chat_picker_opened', {
+    agent_kind: resolveAgentKind(args.agent),
+    prefix: args.prefix === '/' ? 'slash' : 'dollar'
+  })
+}
+
+export function emitNativeChatPickerItemAccepted(args: {
+  agent: NativeChatTelemetryAgent
+  itemKind: 'command' | 'skill'
+}): void {
+  track('native_chat_picker_item_accepted', {
+    agent_kind: resolveAgentKind(args.agent),
+    item_kind: args.itemKind
+  })
+}
+
+export function emitNativeChatSendClassified(args: {
+  agent: NativeChatTelemetryAgent
+  outcome: 'chat' | 'command' | 'unknown-token'
+}): void {
+  track('native_chat_send_classified', {
+    agent_kind: resolveAgentKind(args.agent),
+    outcome: args.outcome
+  })
+}
+
+export function emitNativeChatSkillDiscovery(args: {
+  agent: NativeChatTelemetryAgent
+  outcome: 'ready' | 'error' | 'timeout' | 'unavailable'
+  executionHostKind: 'local' | 'runtime' | 'ssh'
+}): void {
+  track('native_chat_skill_discovery', {
+    agent_kind: resolveAgentKind(args.agent),
+    outcome: args.outcome,
+    execution_host_kind: args.executionHostKind
+  })
+}
diff --git a/src/renderer/src/web/web-preload-api.test.ts b/src/renderer/src/web/web-preload-api.test.ts
index 79e3a846b49..bb95dcad904 100644
--- a/src/renderer/src/web/web-preload-api.test.ts
+++ b/src/renderer/src/web/web-preload-api.test.ts
@@ -1822,6 +1822,35 @@ describe('web UI preload API', () => {
     )
   })
 
+  it('rejects paired web skill discovery failures instead of returning an empty scan', async () => {
+    vi.doMock('./web-runtime-client', () => ({
+      WebRuntimeClient: class {
+        call(method: string): Promise<RuntimeRpcResponse<unknown>> {
+          if (method === 'skills.discover') {
+            return Promise.reject(new Error('runtime disconnected'))
+          }
+          return Promise.resolve({
+            id: method,
+            ok: true,
+            result: {},
+            _meta: { runtimeId: 'runtime-1' }
+          })
+        }
+
+        close(): void {}
+      }
+    }))
+
+    const globals = installBrowserGlobals('Linux')
+    writeStoredRuntimeEnvironment(globals.storage)
+    const { installWebPreloadApi } = await import('./web-preload-api')
+    installWebPreloadApi()
+
+    await expect(globals.window.api.skills.discover({ cwd: '/repo' })).rejects.toThrow(
+      'runtime disconnected'
+    )
+  })
+
   it('rejects paired web computer-use status failures instead of marking the helper unavailable', async () => {
     vi.doMock('./web-runtime-client', () => ({
       WebRuntimeClient: class {
diff --git a/src/renderer/src/web/web-preload-api.ts b/src/renderer/src/web/web-preload-api.ts
index d5f8f2c59f2..41fb9833684 100644
--- a/src/renderer/src/web/web-preload-api.ts
+++ b/src/renderer/src/web/web-preload-api.ts
@@ -2766,11 +2766,7 @@ function createComputerUsePermissionsApi(): NonNullable<
 function createSkillsApi(): NonNullable<Partial<PreloadApi>['skills']> {
   return {
     discover: (target) =>
-      callRuntimeResult<SkillDiscoveryResult>('skills.discover', target, 15_000).catch(() => ({
-        skills: [],
-        sources: [],
-        scannedAt: Date.now()
-      })),
+      callRuntimeResult<SkillDiscoveryResult>('skills.discover', target, 15_000),
     // Why: browser clients have no local skill homes, and remote-host
     // freshness stays disabled until its update rail has equivalent coverage.
     freshnessInventory: (): Promise<SkillFreshnessInventory> =>
diff --git a/src/shared/command-code-output-status.ts b/src/shared/command-code-output-status.ts
index 8bba8a7472b..459831aee79 100644
--- a/src/shared/command-code-output-status.ts
+++ b/src/shared/command-code-output-status.ts
@@ -3,8 +3,7 @@
  * agent-status rows are seeded from its rendered status words and idle
  * composer. Shared because main runs this per-PTY under side-effect authority
  * (emitting command-code facts) while the renderer keeps the byte path for
- * remote-runtime PTYs and the kill switch
- * (docs/reference/terminal-side-effect-authority.md).
+ * remote-runtime PTYs and the kill switch.
  */
 import {
   cleanCommandCodePromptCandidate,
diff --git a/src/shared/feature-interaction-catalog.ts b/src/shared/feature-interaction-catalog.ts
index c77fcf06c16..5d313734e69 100644
--- a/src/shared/feature-interaction-catalog.ts
+++ b/src/shared/feature-interaction-catalog.ts
@@ -59,8 +59,8 @@ export type FeatureInteractionDefinition = {
   interaction: string
 }
 
-// Why: these ids become persisted product state; see
-// docs/reference/feature-discovery-interaction-tracking.md before changing them.
+// Why: these ids become persisted product state; changing them breaks
+// feature-discovery interaction tracking.
 export const FEATURE_INTERACTIONS = [
   { id: 'workspace-board', interaction: 'workspace board opened' },
   {
diff --git a/src/shared/native-chat-agent-profiles.test.ts b/src/shared/native-chat-agent-profiles.test.ts
new file mode 100644
index 00000000000..27b7e07d33b
--- /dev/null
+++ b/src/shared/native-chat-agent-profiles.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+import { getNativeChatAgentProfile } from './native-chat-agent-profiles'
+
+describe('native chat agent picker profiles', () => {
+  it('keeps Codex dollar skills separate from slash commands', () => {
+    expect(getNativeChatAgentProfile('codex')).toMatchObject({
+      skillPrefix: '$',
+      groupedSlash: false,
+      skillSourceOwner: 'codex'
+    })
+  })
+
+  it('groups Claude-family and Grok skills under slash', () => {
+    expect(getNativeChatAgentProfile('claude')).toMatchObject({
+      skillPrefix: '/',
+      groupedSlash: true,
+      skillSourceOwner: 'claude'
+    })
+    expect(getNativeChatAgentProfile('openclaude')).toMatchObject({ skillSourceOwner: 'claude' })
+    expect(getNativeChatAgentProfile('grok')).toMatchObject({
+      skillPrefix: '/',
+      groupedSlash: true,
+      skillSourceOwner: 'grok'
+    })
+  })
+
+  it('does not grant custom or unverified agents a skill grammar', () => {
+    expect(getNativeChatAgentProfile('custom-agent')).toBeNull()
+  })
+})
diff --git a/src/shared/native-chat-agent-profiles.ts b/src/shared/native-chat-agent-profiles.ts
new file mode 100644
index 00000000000..ae52b48efef
--- /dev/null
+++ b/src/shared/native-chat-agent-profiles.ts
@@ -0,0 +1,45 @@
+import type { AgentType } from './agent-status-types'
+import { getAgentSlashCommands, type SlashCommandSuggestion } from './native-chat-slash-commands'
+
+export type NativeChatAgentProfile = {
+  skillPrefix: '$' | '/'
+  groupedSlash: boolean
+  /** OpenClaude reads Claude-owned roots, so this can differ from the agent. */
+  skillSourceOwner: AgentType
+}
+
+const NATIVE_CHAT_AGENT_PROFILES: Partial<Record<AgentType, NativeChatAgentProfile>> = {
+  codex: {
+    skillPrefix: '$',
+    groupedSlash: false,
+    skillSourceOwner: 'codex'
+  },
+  claude: {
+    skillPrefix: '/',
+    groupedSlash: true,
+    skillSourceOwner: 'claude'
+  },
+  openclaude: {
+    skillPrefix: '/',
+    groupedSlash: true,
+    skillSourceOwner: 'claude'
+  },
+  grok: {
+    skillPrefix: '/',
+    groupedSlash: true,
+    skillSourceOwner: 'grok'
+  }
+}
+
+export function getNativeChatAgentProfile(
+  agent: AgentType | null | undefined
+): NativeChatAgentProfile | null {
+  return agent ? (NATIVE_CHAT_AGENT_PROFILES[agent] ?? null) : null
+}
+
+/** The catalog that send classification, collision detection, and transcript
+ *  envelope surfacing key off. Grok has no verified catalog yet, so its slash
+ *  surface stays skills-only — this is the single place that policy lives. */
+export function getVerifiedNativeChatCommands(agent: AgentType): readonly SlashCommandSuggestion[] {
+  return agent === 'grok' ? [] : getAgentSlashCommands(agent)
+}
diff --git a/src/shared/native-chat-command-envelope.test.ts b/src/shared/native-chat-command-envelope.test.ts
new file mode 100644
index 00000000000..6f878e90903
--- /dev/null
+++ b/src/shared/native-chat-command-envelope.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import type { NativeChatMessage } from './native-chat-types'
+import {
+  parseNativeChatCommandEnvelope,
+  surfaceSkillInvocationUserTurns
+} from './native-chat-command-envelope'
+
+const CATALOG = new Set(['clear', 'model'])
+
+function userTurn(text: string, overrides: Partial<NativeChatMessage> = {}): NativeChatMessage {
+  return {
+    id: 'user-1',
+    role: 'user',
+    blocks: [{ type: 'text', text }],
+    timestamp: 100,
+    source: 'transcript',
+    ...overrides
+  }
+}
+
+describe('parseNativeChatCommandEnvelope', () => {
+  it('parses name-first and message-first envelope orderings', () => {
+    expect(
+      parseNativeChatCommandEnvelope(
+        '<command-name>/model</command-name>\n  <command-message>model</command-message>\n  <command-args></command-args>'
+      )
+    ).toEqual({ name: '/model', args: '' })
+    expect(
+      parseNativeChatCommandEnvelope(
+        '<command-message>ce-brainstorm</command-message>\n<command-name>/ce-brainstorm</command-name>\n<command-args>improve the picker</command-args>'
+      )
+    ).toEqual({ name: '/ce-brainstorm', args: 'improve the picker' })
+  })
+
+  it('ignores ordinary prompts and non-leading envelope tags', () => {
+    expect(parseNativeChatCommandEnvelope('deploy the app')).toBeNull()
+    expect(parseNativeChatCommandEnvelope('see <command-name>/x</command-name>')).toBeNull()
+    expect(parseNativeChatCommandEnvelope('<commander>/x</commander>')).toBeNull()
+  })
+})
+
+describe('surfaceSkillInvocationUserTurns', () => {
+  it('renders a skill-invocation envelope as the literal user token', () => {
+    const messages = [
+      userTurn(
+        '<command-message>ce-brainstorm</command-message>\n<command-name>/ce-brainstorm</command-name>\n<command-args>improve the picker</command-args>'
+      )
+    ]
+    const out = surfaceSkillInvocationUserTurns(messages, CATALOG)
+    expect(out[0].blocks).toEqual([{ type: 'text', text: '/ce-brainstorm improve the picker' }])
+    expect(out[0].id).toBe('user-1')
+  })
+
+  it('shortens plugin-qualified names back to the token the user sent', () => {
+    const messages = [
+      userTurn(
+        '<command-message>compound-engineering:ce-brainstorm</command-message>\n<command-name>/compound-engineering:ce-brainstorm</command-name>\n<command-args>hi</command-args>'
+      )
+    ]
+    const out = surfaceSkillInvocationUserTurns(messages, CATALOG)
+    expect(out[0].blocks).toEqual([{ type: 'text', text: '/ce-brainstorm hi' }])
+  })
+
+  it('never hides a plugin skill whose short name shadows a catalog command', () => {
+    const messages = [
+      userTurn('<command-name>/some-plugin:clear</command-name>\n<command-args></command-args>')
+    ]
+    const out = surfaceSkillInvocationUserTurns(messages, CATALOG)
+    expect(out[0].blocks).toEqual([{ type: 'text', text: '/clear' }])
+  })
+
+  it('leaves catalog command envelopes for the noise filter and Ran marker', () => {
+    const messages = [
+      userTurn('<command-name>/model</command-name>\n<command-args></command-args>')
+    ]
+    expect(surfaceSkillInvocationUserTurns(messages, CATALOG)).toBe(messages)
+  })
+
+  it('does not touch assistant turns, plain prompts, or non-text blocks', () => {
+    const messages: NativeChatMessage[] = [
+      userTurn('hello there'),
+      userTurn('<command-name>/skill</command-name>', {
+        id: 'user-2',
+        role: 'assistant'
+      }),
+      userTurn('<command-name>/skill</command-name>', {
+        id: 'user-3',
+        blocks: [
+          { type: 'text', text: '<command-name>/skill</command-name>' },
+          { type: 'image-ref', path: '/tmp/a.png' }
+        ]
+      })
+    ]
+    expect(surfaceSkillInvocationUserTurns(messages, CATALOG)).toBe(messages)
+  })
+})
diff --git a/src/shared/native-chat-command-envelope.ts b/src/shared/native-chat-command-envelope.ts
new file mode 100644
index 00000000000..1ac398d58f1
--- /dev/null
+++ b/src/shared/native-chat-command-envelope.ts
@@ -0,0 +1,63 @@
+// Claude-family harnesses record a slash input's user turn as a command
+// envelope (`<command-name>/x</command-name>…`), not as the typed text. The
+// noise filter rightly hides those for catalog commands — Orca shows a local
+// `Ran /x` line instead — but a skill invocation IS the user's chat turn, so
+// dropping its envelope makes the assistant appear to answer an empty
+// conversation. Surface non-catalog envelopes back as plain user text.
+
+import { isTextBlock, type NativeChatMessage } from './native-chat-types'
+
+const COMMAND_NAME = /<command-name>([\s\S]*?)<\/command-name>/
+const COMMAND_ARGS = /<command-args>([\s\S]*?)<\/command-args>/
+
+export type NativeChatCommandEnvelope = { name: string; args: string }
+
+/** Parse a user turn recorded as a command envelope. Returns null for any text
+ *  that does not lead with an envelope tag (ordinary prompts, XML pastes). */
+export function parseNativeChatCommandEnvelope(text: string): NativeChatCommandEnvelope | null {
+  const trimmed = text.trimStart()
+  if (!trimmed.toLowerCase().startsWith('<command-')) {
+    return null
+  }
+  const name = COMMAND_NAME.exec(trimmed)?.[1]?.trim()
+  if (!name) {
+    return null
+  }
+  return { name, args: COMMAND_ARGS.exec(trimmed)?.[1]?.trim() ?? '' }
+}
+
+/**
+ * Replace skill-invocation envelopes with the token the user sent (`/name
+ * args`) so the turn renders as their message and the optimistic echo can
+ * reconcile against it. Catalog commands stay untouched — the noise filter
+ * hides them and the local `Ran /name` marker is their feedback.
+ */
+export function surfaceSkillInvocationUserTurns(
+  messages: readonly NativeChatMessage[],
+  catalogCommandNames: ReadonlySet<string>
+): NativeChatMessage[] {
+  let changed = false
+  const out = messages.map((message) => {
+    if (message.role !== 'user' || !message.blocks.every(isTextBlock)) {
+      return message
+    }
+    const envelope = parseNativeChatCommandEnvelope(
+      message.blocks.map((block) => block.text).join('\n')
+    )
+    if (!envelope || catalogCommandNames.has(envelope.name.replace(/^\//, ''))) {
+      return message
+    }
+    // Why: the harness canonicalizes a plugin skill to `/plugin:name`, but the
+    // user (and the picker) sent the short frontmatter name. Render the short
+    // token so the bubble shows what was typed and the optimistic echo prunes
+    // instead of duplicating the turn.
+    const shortName = envelope.name.replace(/^\//, '').split(':').at(-1) ?? ''
+    const token = `/${shortName}`
+    changed = true
+    return {
+      ...message,
+      blocks: [{ type: 'text' as const, text: envelope.args ? `${token} ${envelope.args}` : token }]
+    }
+  })
+  return changed ? out : (messages as NativeChatMessage[])
+}
diff --git a/src/shared/skill-display-text.ts b/src/shared/skill-display-text.ts
new file mode 100644
index 00000000000..d2e61b4ac8b
--- /dev/null
+++ b/src/shared/skill-display-text.ts
@@ -0,0 +1,26 @@
+// Untrusted skill and plugin names/descriptions are shown in the picker and the
+// Settings skill list. Control, C1, zero-width, and bidi-override codepoints can
+// spoof a row or hide characters, so both the main-process label builder and the
+// renderer picker strip them through this one predicate rather than maintaining
+// divergent copies.
+export function isSafeDisplayCharacter(character: string): boolean {
+  const code = character.codePointAt(0) ?? 0
+  return !(
+    code <= 0x1f ||
+    (code >= 0x7f && code <= 0x9f) ||
+    code === 0x200b ||
+    code === 0x200e ||
+    code === 0x200f ||
+    code === 0x061c ||
+    code === 0x2060 ||
+    code === 0xfeff ||
+    code === 0x2028 ||
+    code === 0x2029 ||
+    (code >= 0x202a && code <= 0x202e) ||
+    (code >= 0x2066 && code <= 0x2069)
+  )
+}
+
+export function stripUnsafeDisplayCharacters(value: string): string {
+  return [...value].filter(isSafeDisplayCharacter).join('')
+}
diff --git a/src/shared/skills.ts b/src/shared/skills.ts
index 0b386624cbf..c908954d3a9 100644
--- a/src/shared/skills.ts
+++ b/src/shared/skills.ts
@@ -1,3 +1,5 @@
+import { z } from 'zod'
+import type { AgentType } from './agent-status-types'
 import type { ProjectExecutionRuntimeResolution } from './project-execution-runtime'
 
 export type SkillProvider = 'codex' | 'claude' | 'agent-skills'
@@ -12,6 +14,9 @@ export type DiscoveredSkill = {
   sourceKind: SkillSourceKind
   sourceLabel: string
   rootPath: string
+  /** Every root that reached this file. Canonical-path dedup keeps one row but
+   *  must not erase co-owning roots, or shared symlinked skills lose agents. */
+  rootPaths?: string[]
   directoryPath: string
   skillFilePath: string
   installed: boolean
@@ -25,6 +30,8 @@ export type SkillDiscoverySource = {
   path: string
   sourceKind: SkillSourceKind
   providers: SkillProvider[]
+  /** Agent that owns this root; null is the explicit shared-skills scope. */
+  owner: AgentType | null
   exists: boolean
   skippedReason?: 'missing' | 'remote-repo'
 }
@@ -40,9 +47,62 @@ export type SkillDiscoveryTarget = {
   wslDistro?: string | null
   /** Workspace path whose local .agents/.claude skill roots should be scanned. */
   cwd?: string | null
+  /** Lets the owning runtime resolve the project runtime from its own store
+   *  when the caller (e.g. a remote client) cannot supply `projectRuntime`. */
+  worktreeId?: string | null
   projectRuntime?: ProjectExecutionRuntimeResolution
 }
 
+const ResolvedProjectRuntimeSchema = z.object({
+  status: z.literal('resolved'),
+  runtime: z.discriminatedUnion('kind', [
+    z.object({
+      kind: z.literal('local-host'),
+      hostPlatform: z.string(),
+      projectId: z.string(),
+      reason: z.literal('non-windows'),
+      cacheKey: z.string()
+    }),
+    z.object({
+      kind: z.literal('windows-host'),
+      hostPlatform: z.literal('win32'),
+      projectId: z.string(),
+      reason: z.enum(['project-override', 'global-default', 'migration-fallback']),
+      cacheKey: z.string()
+    }),
+    z.object({
+      kind: z.literal('wsl'),
+      hostPlatform: z.literal('wsl'),
+      projectId: z.string(),
+      distro: z.string(),
+      reason: z.enum(['project-override', 'global-default']),
+      cacheKey: z.string()
+    })
+  ])
+})
+
+const RepairProjectRuntimeSchema = z.object({
+  status: z.literal('repair-required'),
+  repair: z.object({
+    projectId: z.string(),
+    preferredRuntime: z.object({ kind: z.literal('wsl'), distro: z.string().nullable() }),
+    reason: z.enum(['wsl-unavailable', 'wsl-distro-required', 'wsl-distro-missing']),
+    source: z.enum(['project-override', 'global-default']),
+    cacheKey: z.string()
+  })
+})
+
+/** Both desktop IPC and runtime RPC parse the complete discovery target here. */
+export const SkillDiscoveryTargetSchema: z.ZodType<SkillDiscoveryTarget> = z.object({
+  runtime: z.enum(['host', 'wsl']).optional(),
+  wslDistro: z.string().nullable().optional(),
+  cwd: z.string().nullable().optional(),
+  worktreeId: z.string().nullable().optional(),
+  projectRuntime: z
+    .discriminatedUnion('status', [ResolvedProjectRuntimeSchema, RepairProjectRuntimeSchema])
+    .optional()
+})
+
 export type SkillFrontmatterSummary = {
   name: string | null
   description: string | null
diff --git a/src/shared/telemetry-events.ts b/src/shared/telemetry-events.ts
index ee34b53ec3c..f7f43c076d9 100644
--- a/src/shared/telemetry-events.ts
+++ b/src/shared/telemetry-events.ts
@@ -470,6 +470,22 @@ const nativeChatMessageSentSchema = z
     runtime: nativeChatRuntimeSchema
   })
   .strict()
+const nativeChatPickerOpenedSchema = z
+  .object({ agent_kind: agentKindSchema, prefix: z.enum(['slash', 'dollar']) })
+  .strict()
+const nativeChatPickerItemAcceptedSchema = z
+  .object({ agent_kind: agentKindSchema, item_kind: z.enum(['command', 'skill']) })
+  .strict()
+const nativeChatSendClassifiedSchema = z
+  .object({ agent_kind: agentKindSchema, outcome: z.enum(['chat', 'command', 'unknown-token']) })
+  .strict()
+const nativeChatSkillDiscoverySchema = z
+  .object({
+    agent_kind: agentKindSchema,
+    outcome: z.enum(['ready', 'error', 'timeout', 'unavailable']),
+    execution_host_kind: z.enum(['local', 'runtime', 'ssh'])
+  })
+  .strict()
 
 const telemetryOptedInSchema = z.object({ via: optInViaSchema }).strict()
 const telemetryOptedOutSchema = z.object({ via: optInViaSchema }).strict()
@@ -1432,6 +1448,10 @@ export const eventSchemas = {
 
   native_chat_toggled: nativeChatToggledSchema,
   native_chat_message_sent: nativeChatMessageSentSchema,
+  native_chat_picker_opened: nativeChatPickerOpenedSchema,
+  native_chat_picker_item_accepted: nativeChatPickerItemAcceptedSchema,
+  native_chat_send_classified: nativeChatSendClassifiedSchema,
+  native_chat_skill_discovery: nativeChatSkillDiscoverySchema,
 
   telemetry_opted_in: telemetryOptedInSchema,
   telemetry_opted_out: telemetryOptedOutSchema,
diff --git a/src/shared/terminal-bell-detector.ts b/src/shared/terminal-bell-detector.ts
index cce08a7dbd0..7b909e50b32 100644
--- a/src/shared/terminal-bell-detector.ts
+++ b/src/shared/terminal-bell-detector.ts
@@ -3,8 +3,8 @@
  * occurring inside OSC escape sequences.
  *
  * Shared between the renderer transport processor and main's per-PTY
- * side-effect tracker (docs/reference/terminal-side-effect-authority.md):
- * bell semantics must not drift between the two parsing authorities.
+ * side-effect tracker: bell semantics must not drift between the two parsing
+ * authorities.
  *
  * Why stateful: PTY data arrives in arbitrary chunks, so an OSC sequence
  * may span multiple calls. The detector tracks in-progress escape state
diff --git a/src/shared/terminal-output-side-effects.ts b/src/shared/terminal-output-side-effects.ts
index 02bf28efa80..4f00c9f1753 100644
--- a/src/shared/terminal-output-side-effects.ts
+++ b/src/shared/terminal-output-side-effects.ts
@@ -3,8 +3,8 @@
  * both the renderer transport (`createPtyOutputProcessor`) and main's
  * per-PTY tracker in `OrcaRuntimeService.onPtyData`.
  *
- * Why shared: docs/reference/terminal-side-effect-authority.md makes main the
- * side-effect parser for every PTY whose bytes transit local main. Title
+ * Why shared: main is the side-effect parser for every PTY whose bytes transit
+ * local main. Title
  * semantics (all-titles ordering, cursor-agent literal drop, normalization,
  * stale-working-title clearing) must not drift between the two paths.
  */
diff --git a/src/shared/terminal-side-effect-facts.ts b/src/shared/terminal-side-effect-facts.ts
index 1a546324006..8dee0e6242c 100644
--- a/src/shared/terminal-side-effect-facts.ts
+++ b/src/shared/terminal-side-effect-facts.ts
@@ -3,7 +3,6 @@
  * (main → renderer). Events are facts, not decisions: main parses every
  * local-daemon/SSH PTY byte exactly once and emits what it observed; the
  * renderer store handler owns notification/unread policy.
- * See docs/reference/terminal-side-effect-authority.md.
  */
 
 import type { TerminalGitHubPRLink } from './terminal-github-pr-link-detector'
diff --git a/src/shared/terminal-view-attributes.ts b/src/shared/terminal-view-attributes.ts
index fa587a17b5c..638ee1df176 100644
--- a/src/shared/terminal-view-attributes.ts
+++ b/src/shared/terminal-view-attributes.ts
@@ -1,6 +1,6 @@
 /**
- * Phase 5 slice 2 (docs/reference/terminal-query-authority.md §View-attribute
- * bridge): payload contract for the renderer→main `pty:terminalViewAttributes`
+ * Phase 5 slice 2 (View-attribute bridge): payload contract for the
+ * renderer→main `pty:terminalViewAttributes`
  * push, plus main/renderer mirrors of xterm's XParseColor color-spec grammar
  * so main's responder replies byte-identically to a visible renderer xterm.
  */
diff --git a/src/shared/types.ts b/src/shared/types.ts
index ec80f68b690..b28bf97d451 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -2822,14 +2822,12 @@ export type GlobalSettings = {
   terminalScopeHistoryByWorktree: boolean
   /** Kill switch for hidden terminal view parking — unmounting long-hidden
    *  terminal panes while a pane-less watcher keeps PTY side effects alive.
-   *  Defaults to true; `false` disables parking entirely.
-   *  See docs/reference/terminal-hidden-view-parking.md. */
+   *  Defaults to true; `false` disables parking entirely. */
   terminalHiddenViewParking?: boolean
   /** Kill switch for main-process terminal side-effect authority: when true
    *  (default), local-daemon/SSH PTY title/bell/agent facts are consumed from
    *  the `pty:sideEffect` channel and renderer byte parsers stay unregistered
-   *  for those PTYs; `false` restores renderer byte parsing.
-   *  See docs/reference/terminal-side-effect-authority.md. */
+   *  for those PTYs; `false` restores renderer byte parsing. */
   terminalMainSideEffectAuthority?: boolean
   /** Kill switch for main's hidden-delivery gate (Phase 4): when true
    *  (default) AND terminalMainSideEffectAuthority is on, main drops PTY byte
@@ -2839,8 +2837,7 @@ export type GlobalSettings = {
   /** Kill switch for the main model query responder (Phase 5): when true
    *  (default) AND both Phase-4 gate switches are on, main answers terminal
    *  queries (DA1/CPR/DECRPM, …) embedded in hidden-dropped chunks from the
-   *  runtime emulator. `false` silences the responder without changing drops.
-   *  See docs/reference/terminal-query-authority.md. */
+   *  runtime emulator. `false` silences the responder without changing drops. */
   terminalModelQueryAuthority?: boolean
   /** Which agent to pre-select in the new-workspace composer.
    *  - null: auto (first detected agent)

From e3721e8cf2d296b301fa81f9119a7d633cfd035d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20S=C3=A1ez?= <hg.saezs@gmail.com>
Date: Sun, 19 Jul 2026 20:42:41 -0400
Subject: [PATCH 18/54] fix(pi): detect ask_user_question and surface as
 blocked state (#9457)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(pi): detect ask_user_question and surface as blocked state

   Maps Pi tool_call/tool_execution_start events with ask_user_question
   to blocked state (was working), so worktrees surface in attention sort
   and trigger notifications — matching Claude/Codex/Grok behavior.

   Guards interactivePrompt derivation to Pi-only, OMP unchanged.
   5 new tests covering blocked transition, regression, malformed input,
   and OMP guard.

* fix(pi): gate ask_user_question blocked on raw tool_name and cover state exit

Address code-review findings on the Pi ask_user_question detection:

- Gate the Pi blocked classification on the event's own tool_name (matching the
  Claude/Grok normalizers) instead of the merged snapshot, so a partial
  follow-up event can't inherit a stale ask_user_question name from the tool
  cache and spuriously re-enter blocked. resolveToolState moves back after the
  state-name guard, so it no longer runs on discarded events.
- Make extractPiToolFields' agentKind parameter required; the sole call site
  always supplies it, and optional risked a future Pi caller silently falling
  back to OMP-safe (no interactivePrompt) behavior with no type error.
- Add coverage for the transition OUT of blocked (tool_execution_end -> working,
  agent_end -> done) and that a following regular Pi tool clears interactivePrompt.

* test(pty-connection): gate confirming null sample in idle-exit veto test

CI failed on a flaky call-count assertion: one timer advance can start
multiple getForegroundProcess reads, so the confirming null sample could
land before the replacement hook owner was installed. Hold 2nd+ null
samples until the veto owner is in place instead of requiring exactly
one extra call.

---------

Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
---
 .../terminal-pane/pty-connection.test.ts      |  37 ++-
 src/shared/agent-hook-listener.test.ts        | 275 ++++++++++++++++++
 src/shared/agent-hook-listener.ts             |  39 ++-
 3 files changed, 329 insertions(+), 22 deletions(-)

diff --git a/src/renderer/src/components/terminal-pane/pty-connection.test.ts b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
index 7b119905d47..1c9323dd0a9 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
@@ -17733,7 +17733,26 @@ describe('connectPanePty', () => {
     const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0.5)
     try {
       const getForegroundProcess = vi.mocked(window.api.pty.getForegroundProcess)
-      getForegroundProcess.mockResolvedValue('codex')
+      // Why: call-count alone is flaky — one advanceTimersToNextTimerAsync can start
+      // multiple getForegroundProcess reads (completion cadence + pane tracker /
+      // confirmForegroundProcess alias). Gate the 2nd+ null sample until the
+      // replacement hook owner is installed so the confirming sample always sees it.
+      let idleMode = false
+      let nullSamplesStarted = 0
+      let releaseConfirmingNullSample: (() => void) | undefined
+      const confirmingNullSampleGate = new Promise<void>((resolve) => {
+        releaseConfirmingNullSample = resolve
+      })
+      getForegroundProcess.mockImplementation(async () => {
+        if (!idleMode) {
+          return 'codex'
+        }
+        nullSamplesStarted += 1
+        if (nullSamplesStarted >= 2) {
+          await confirmingNullSampleGate
+        }
+        return null
+      })
       const paneKey = makePaneKey('tab-1', LEAF_1)
       const pane = createPane(1)
       const manager = createManager(1)
@@ -17753,21 +17772,16 @@ describe('connectPanePty', () => {
 
       titleHandler('Codex working', 'Codex working')
       await vi.advanceTimersByTimeAsync(2_500)
-      const inspectionsBeforeIdle = getForegroundProcess.mock.calls.length
-      getForegroundProcess.mockResolvedValue(null)
-      // Why: active process polling is jittered, so a fixed window can consume
-      // both null samples before the replacement hook row is installed.
-      for (
-        let attempts = 0;
-        getForegroundProcess.mock.calls.length === inspectionsBeforeIdle;
-        attempts += 1
-      ) {
+      idleMode = true
+      for (let attempts = 0; nullSamplesStarted < 1; attempts += 1) {
         if (attempts >= 10) {
           throw new Error('Expected the first idle process inspection')
         }
         await vi.advanceTimersToNextTimerAsync()
       }
-      expect(getForegroundProcess).toHaveBeenCalledTimes(inspectionsBeforeIdle + 1)
+      // Why: let the first null sample apply pendingProcessExitAgent before the
+      // replacement owner is installed; later samples stay gated until then.
+      await flushAsyncTicks()
 
       mockStoreState.agentStatusByPaneKey[paneKey] = {
         state: 'working',
@@ -17778,6 +17792,7 @@ describe('connectPanePty', () => {
         paneKey,
         stateHistory: []
       }
+      releaseConfirmingNullSample?.()
       idleHandler('Claude done')
       await vi.advanceTimersByTimeAsync(800)
       await vi.advanceTimersByTimeAsync(AGENT_TASK_COMPLETE_NOTIFICATION_MAX_WAIT_MS)
diff --git a/src/shared/agent-hook-listener.test.ts b/src/shared/agent-hook-listener.test.ts
index 08c8f00ca15..cc99a807837 100644
--- a/src/shared/agent-hook-listener.test.ts
+++ b/src/shared/agent-hook-listener.test.ts
@@ -372,6 +372,247 @@ describe('shared agent-hook-listener', () => {
     expect(event?.payload.interactivePrompt).toBe(JSON.stringify(properties))
   })
 
+  it('maps Pi tool_call ask_user_question to blocked with interactivePrompt', () => {
+    const questions = {
+      questions: [
+        {
+          question: 'What is your priority?',
+          options: ['A', 'B', 'C']
+        }
+      ]
+    }
+    const blocked = normalizeHookPayload(
+      state,
+      'pi',
+      {
+        paneKey: PANE_KEY,
+        tabId: 'tab-1',
+        worktreeId: 'wt',
+        env: 'production',
+        version: '1',
+        payload: {
+          hook_event_name: 'tool_call',
+          tool_name: 'ask_user_question',
+          tool_input: questions
+        }
+      },
+      'production'
+    )
+    expect(blocked?.payload).toMatchObject({
+      state: 'blocked',
+      agentType: 'pi',
+      toolName: 'ask_user_question'
+    })
+    expect(blocked?.payload.interactivePrompt).toBe(JSON.stringify(questions))
+  })
+
+  it('maps Pi tool_execution_start ask_user_question to blocked with interactivePrompt', () => {
+    const questions = {
+      questions: [
+        {
+          question: 'Pick a path',
+          options: ['path-1', 'path-2']
+        }
+      ]
+    }
+    const blocked = normalizeHookPayload(
+      state,
+      'pi',
+      {
+        paneKey: PANE_KEY,
+        tabId: 'tab-1',
+        worktreeId: 'wt',
+        env: 'production',
+        version: '1',
+        payload: {
+          hook_event_name: 'tool_execution_start',
+          tool_name: 'ask_user_question',
+          tool_input: questions
+        }
+      },
+      'production'
+    )
+    expect(blocked?.payload).toMatchObject({
+      state: 'blocked',
+      agentType: 'pi',
+      toolName: 'ask_user_question'
+    })
+    expect(blocked?.payload.interactivePrompt).toBe(JSON.stringify(questions))
+  })
+
+  it('keeps Pi regular tool_call notifications as working', () => {
+    const working = normalizeHookPayload(
+      state,
+      'pi',
+      {
+        paneKey: PANE_KEY,
+        tabId: 'tab-1',
+        worktreeId: 'wt',
+        env: 'production',
+        version: '1',
+        payload: {
+          hook_event_name: 'tool_call',
+          tool_name: 'bash',
+          tool_input: { command: 'git status' }
+        }
+      },
+      'production'
+    )
+    expect(working?.payload).toMatchObject({
+      state: 'working',
+      agentType: 'pi',
+      toolName: 'bash',
+      toolInput: 'git status'
+    })
+    expect(working?.payload.interactivePrompt).toBeUndefined()
+  })
+
+  it('keeps Pi ask_user_question blocked when tool_input is missing', () => {
+    const blocked = normalizeHookPayload(
+      state,
+      'pi',
+      {
+        paneKey: PANE_KEY,
+        tabId: 'tab-1',
+        worktreeId: 'wt',
+        env: 'production',
+        version: '1',
+        payload: {
+          hook_event_name: 'tool_call',
+          tool_name: 'ask_user_question'
+        }
+      },
+      'production'
+    )
+    expect(blocked?.payload).toMatchObject({
+      state: 'blocked',
+      agentType: 'pi',
+      toolName: 'ask_user_question'
+    })
+    expect(blocked?.payload.interactivePrompt).toBeUndefined()
+  })
+
+  it('clears Pi ask_user_question blocked once the tool_execution_end arrives', () => {
+    const questions = {
+      questions: [{ question: 'Ship it?', options: ['yes', 'no'] }]
+    }
+    const base = {
+      paneKey: PANE_KEY,
+      tabId: 'tab-1',
+      worktreeId: 'wt',
+      env: 'production' as const,
+      version: '1'
+    }
+    const blocked = normalizeHookPayload(
+      state,
+      'pi',
+      {
+        ...base,
+        payload: {
+          hook_event_name: 'tool_call',
+          tool_name: 'ask_user_question',
+          tool_input: questions
+        }
+      },
+      'production'
+    )
+    expect(blocked?.payload.state).toBe('blocked')
+    expect(blocked?.payload.interactivePrompt).toBe(JSON.stringify(questions))
+
+    // Why: the answered question must leave the blocked/needs-attention state so
+    // the notification and attention sort clear; tool_execution_end is working.
+    const cleared = normalizeHookPayload(
+      state,
+      'pi',
+      {
+        ...base,
+        payload: {
+          hook_event_name: 'tool_execution_end',
+          tool_name: 'ask_user_question'
+        }
+      },
+      'production'
+    )
+    expect(cleared?.payload.state).toBe('working')
+    expect(cleared?.payload.interactivePrompt).toBeUndefined()
+  })
+
+  it('marks Pi done when agent_end follows an ask_user_question block', () => {
+    const base = {
+      paneKey: PANE_KEY,
+      tabId: 'tab-1',
+      worktreeId: 'wt',
+      env: 'production' as const,
+      version: '1'
+    }
+    normalizeHookPayload(
+      state,
+      'pi',
+      {
+        ...base,
+        payload: {
+          hook_event_name: 'tool_call',
+          tool_name: 'ask_user_question',
+          tool_input: { questions: [{ question: 'Pick', options: ['a', 'b'] }] }
+        }
+      },
+      'production'
+    )
+    const done = normalizeHookPayload(
+      state,
+      'pi',
+      { ...base, payload: { hook_event_name: 'agent_end' } },
+      'production'
+    )
+    expect(done?.payload.state).toBe('done')
+    expect(done?.payload.interactivePrompt).toBeUndefined()
+  })
+
+  it('clears the ask_user_question interactivePrompt when a regular Pi tool runs next', () => {
+    const base = {
+      paneKey: PANE_KEY,
+      tabId: 'tab-1',
+      worktreeId: 'wt',
+      env: 'production' as const,
+      version: '1'
+    }
+    normalizeHookPayload(
+      state,
+      'pi',
+      {
+        ...base,
+        payload: {
+          hook_event_name: 'tool_call',
+          tool_name: 'ask_user_question',
+          tool_input: { questions: [{ question: 'Pick', options: ['a', 'b'] }] }
+        }
+      },
+      'production'
+    )
+    // Why: a follow-up regular tool must not inherit the prior question's blocked
+    // state or its live interactivePrompt card.
+    const working = normalizeHookPayload(
+      state,
+      'pi',
+      {
+        ...base,
+        payload: {
+          hook_event_name: 'tool_call',
+          tool_name: 'bash',
+          tool_input: { command: 'ls' }
+        }
+      },
+      'production'
+    )
+    expect(working?.payload).toMatchObject({
+      state: 'working',
+      agentType: 'pi',
+      toolName: 'bash',
+      toolInput: 'ls'
+    })
+    expect(working?.payload.interactivePrompt).toBeUndefined()
+  })
+
   it('normalizes OMP Pi-compatible hooks with OMP attribution', () => {
     const event = normalizeHookPayload(
       state,
@@ -419,6 +660,40 @@ describe('shared agent-hook-listener', () => {
       toolName: 'bash',
       toolInput: 'pnpm test'
     })
+    expect(tool?.payload.interactivePrompt).toBeUndefined()
+  })
+
+  it('keeps OMP ask_user_question behavior on Pi-compatible events', () => {
+    const tool = normalizeHookPayload(
+      state,
+      'omp',
+      {
+        paneKey: PANE_KEY,
+        tabId: 'tab-1',
+        worktreeId: 'wt',
+        env: 'production',
+        version: '1',
+        payload: {
+          hook_event_name: 'tool_call',
+          tool_name: 'ask_user_question',
+          tool_input: {
+            questions: [
+              {
+                question: 'Choose',
+                options: ['x', 'y']
+              }
+            ]
+          }
+        }
+      },
+      'production'
+    )
+    expect(tool?.payload).toMatchObject({
+      state: 'working',
+      agentType: 'omp',
+      toolName: 'ask_user_question'
+    })
+    expect(tool?.payload.interactivePrompt).toBeUndefined()
   })
 
   it('captures Pi session ids on Pi-compatible status events', () => {
diff --git a/src/shared/agent-hook-listener.ts b/src/shared/agent-hook-listener.ts
index c4df60fb28f..f983d409e79 100644
--- a/src/shared/agent-hook-listener.ts
+++ b/src/shared/agent-hook-listener.ts
@@ -1898,7 +1898,8 @@ function extractCopilotToolFields(
 
 function extractPiToolFields(
   eventName: unknown,
-  hookPayload: Record<string, unknown>
+  hookPayload: Record<string, unknown>,
+  agentKind: 'pi' | 'omp'
 ): ToolSnapshot {
   if (
     eventName === 'tool_call' ||
@@ -1906,9 +1907,16 @@ function extractPiToolFields(
     eventName === 'tool_execution_end'
   ) {
     const toolName = readString(hookPayload, 'tool_name')
-    const toolInput = deriveToolInputPreview(toolName, hookPayload.tool_input)
+    const rawToolInput = hookPayload.tool_input
+    const toolInput = deriveToolInputPreview(toolName, rawToolInput)
+    // Why: OMP shares this extractor. interactivePrompt derivation should
+    // only apply to Pi so OMP ask_user_question metadata stays unchanged.
+    const interactivePrompt =
+      agentKind === 'pi' && (eventName === 'tool_call' || eventName === 'tool_execution_start')
+        ? deriveInteractivePrompt(toolName, rawToolInput, eventName)
+        : undefined
     return toolUpdate(
-      { toolName, toolInput },
+      { toolName, toolInput, interactivePrompt },
       { hasToolInputField: hasOwnField(hookPayload, 'tool_input') }
     )
   }
@@ -2386,7 +2394,7 @@ function extractToolFields(
       return extractCursorToolFields(eventName, hookPayload)
     case 'pi':
     case 'omp':
-      return extractPiToolFields(eventName, hookPayload)
+      return extractPiToolFields(eventName, hookPayload, source)
     case 'droid':
       return extractDroidToolFields(eventName, hookPayload)
     case 'command-code':
@@ -3422,13 +3430,22 @@ function normalizePiCompatibleEvent(
     return null
   }
 
-  const stateName =
-    eventName === 'before_agent_start' ||
-    eventName === 'agent_start' ||
-    eventName === 'tool_call' ||
-    eventName === 'tool_execution_start' ||
-    eventName === 'tool_execution_end' ||
-    eventName === 'message_end'
+  // Why: gate on the event's own tool_name (matching the Claude/Grok normalizers),
+  // not a merged snapshot, so a partial follow-up event can't inherit a stale
+  // ask_user_question name from the tool cache and spuriously re-enter blocked.
+  const isPiAskUserQuestion =
+    agentType === 'pi' &&
+    isAskUserQuestionTool(readString(hookPayload, 'tool_name')) &&
+    (eventName === 'tool_call' || eventName === 'tool_execution_start')
+
+  const stateName = isPiAskUserQuestion
+    ? 'blocked'
+    : eventName === 'before_agent_start' ||
+        eventName === 'agent_start' ||
+        eventName === 'tool_call' ||
+        eventName === 'tool_execution_start' ||
+        eventName === 'tool_execution_end' ||
+        eventName === 'message_end'
       ? 'working'
       : eventName === 'agent_end'
         ? 'done'

From 808299cd1f786ade0e54180f13282abc81d3ab25 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Sun, 19 Jul 2026 18:59:22 -0700
Subject: [PATCH 19/54] fix(cli): avoid Windows PATH status timeout (#9483)

---
 config/electron-builder.config.cjs            |  11 +-
 config/packaged-runtime-node-modules.cjs      |  14 +-
 config/scripts/ensure-native-runtime.mjs      |  28 ++-
 config/scripts/ensure-native-runtime.test.mjs |  14 ++
 ...package-electron-runtime-contract.test.mjs |  42 +++++
 config/scripts/rebuild-native-deps.mjs        |  81 +++++++-
 config/scripts/rebuild-native-deps.test.mjs   | 105 ++++++++++-
 package.json                                  |   3 +-
 pnpm-lock.yaml                                |  18 ++
 src/main/cli/cli-installer.test.ts            | 178 +++++++++++++++---
 src/main/cli/cli-installer.ts                 | 152 +++++++++++----
 .../cli/windows-user-path-registry.test.ts    | 127 +++++++++++++
 src/main/cli/windows-user-path-registry.ts    | 160 ++++++++++++++++
 src/main/cli/wsl-cli-installer.test.ts        |  21 +++
 .../mobile-emulator-agent-setup-cli-state.ts  |   2 +-
 .../feature-tip-cli-install-action.ts         |   2 +-
 .../feature-tips/feature-tip-startup-gate.ts  |   2 +-
 .../onboarding-feature-setup.test.ts          |  20 ++
 .../onboarding/onboarding-feature-setup.ts    |  10 +-
 .../components/settings/BrowserUsePane.tsx    |   3 +-
 .../components/settings/CliSection.test.tsx   |  50 ++++-
 .../src/components/settings/CliSection.tsx    |  15 +-
 .../settings/CliSkillRuntimeSetup.tsx         |  12 +-
 src/renderer/src/i18n/locales/en.json         |   6 +-
 src/renderer/src/i18n/locales/es.json         |   6 +-
 src/renderer/src/i18n/locales/ja.json         |   6 +-
 src/renderer/src/i18n/locales/ko.json         |   6 +-
 src/renderer/src/i18n/locales/zh.json         |   6 +-
 .../lib/agent-skill-cli-prerequisite.test.ts  |  22 +++
 .../src/lib/agent-skill-cli-prerequisite.ts   |  22 ++-
 src/shared/cli-install-types.ts               |   3 +-
 31 files changed, 1033 insertions(+), 114 deletions(-)
 create mode 100644 src/main/cli/windows-user-path-registry.test.ts
 create mode 100644 src/main/cli/windows-user-path-registry.ts

diff --git a/config/electron-builder.config.cjs b/config/electron-builder.config.cjs
index 98beb0c1c1f..85e3d244d68 100644
--- a/config/electron-builder.config.cjs
+++ b/config/electron-builder.config.cjs
@@ -35,13 +35,7 @@ const relayExtraResource = {
 // from package directories where pnpm's symlink farm is absent. Copy the exact
 // runtime dependency closure to Resources/node_modules so bare require() calls
 // do not fall through to a developer checkout's node_modules.
-const packagedRuntimeNodeModuleResources = createPackagedRuntimeNodeModuleResources()
-
-const commonExtraResources = [
-  relayExtraResource,
-  ...packagedRuntimeNodeModuleResources,
-  skillFreshnessResources
-]
+const commonExtraResources = [relayExtraResource, skillFreshnessResources]
 const macSpeechNativeResource = {
   from: 'node_modules/sherpa-onnx-darwin-${arch}',
   to: 'node_modules/sherpa-onnx-darwin-${arch}'
@@ -198,6 +192,7 @@ module.exports = {
     },
     extraResources: [
       ...commonExtraResources,
+      ...createPackagedRuntimeNodeModuleResources('win32'),
       winSpeechNativeResource,
       {
         from: 'resources/win32/bin/orca.cmd',
@@ -261,6 +256,7 @@ module.exports = {
     notarize: isMacRelease,
     extraResources: [
       ...commonExtraResources,
+      ...createPackagedRuntimeNodeModuleResources('darwin'),
       macSpeechNativeResource,
       {
         from: 'resources/darwin/bin/orca',
@@ -324,6 +320,7 @@ module.exports = {
     },
     extraResources: [
       ...commonExtraResources,
+      ...createPackagedRuntimeNodeModuleResources('linux'),
       linuxSpeechNativeResource,
       {
         from: 'resources/linux/bin/orca-ide',
diff --git a/config/packaged-runtime-node-modules.cjs b/config/packaged-runtime-node-modules.cjs
index d3f81817cee..8854f866f42 100644
--- a/config/packaged-runtime-node-modules.cjs
+++ b/config/packaged-runtime-node-modules.cjs
@@ -31,6 +31,7 @@ const PACKAGED_RUNTIME_PACKAGE_ROOTS = [
   'yaml',
   'zod'
 ]
+const WINDOWS_PACKAGED_RUNTIME_PACKAGE_ROOTS = ['windows-native-registry']
 
 const NODE_PTY_PREBUILD_PREFIX_BY_PLATFORM = {
   darwin: 'darwin-',
@@ -128,7 +129,7 @@ function isKnownOmittedServeSimDependency(packageName, fromDir) {
   }
 }
 
-function collectPackagedRuntimePackages() {
+function collectPackagedRuntimePackages(electronPlatformName = process.platform) {
   const packages = new Map()
   const visit = (packageName, fromDir = projectDir) => {
     if (packageName === 'electron' || packages.has(packageName)) {
@@ -156,7 +157,12 @@ function collectPackagedRuntimePackages() {
     }
   }
 
-  for (const packageName of PACKAGED_RUNTIME_PACKAGE_ROOTS) {
+  // Why: cross-builds must select native dependencies from the artifact target, not the build host.
+  const packageRoots = [
+    ...PACKAGED_RUNTIME_PACKAGE_ROOTS,
+    ...(electronPlatformName === 'win32' ? WINDOWS_PACKAGED_RUNTIME_PACKAGE_ROOTS : [])
+  ]
+  for (const packageName of packageRoots) {
     visit(packageName)
   }
 
@@ -183,8 +189,8 @@ function collectPackagedRuntimePackages() {
   return [...packages.entries()].sort(([left], [right]) => left.localeCompare(right))
 }
 
-function createPackagedRuntimeNodeModuleResources() {
-  return collectPackagedRuntimePackages().map(([packageName, packageDir]) => ({
+function createPackagedRuntimeNodeModuleResources(electronPlatformName = process.platform) {
+  return collectPackagedRuntimePackages(electronPlatformName).map(([packageName, packageDir]) => ({
     from: packageDir,
     to: join('node_modules', ...packageName.split('/'))
   }))
diff --git a/config/scripts/ensure-native-runtime.mjs b/config/scripts/ensure-native-runtime.mjs
index eac27a90965..98b064cd30d 100644
--- a/config/scripts/ensure-native-runtime.mjs
+++ b/config/scripts/ensure-native-runtime.mjs
@@ -11,7 +11,11 @@ const scriptPath = import.meta.filename
 const projectDir = resolve(import.meta.dirname, '../..')
 const runtime = readRuntimeArg()
 
-const NATIVE_MODULES = ['node-pty']
+const NATIVE_MODULES = [
+  'node-pty',
+  ...(process.platform === 'win32' ? ['windows-native-registry'] : [])
+]
+const NODE_PTY_CONPTY_RUNTIME_FILES = ['conpty.dll', 'OpenConsole.exe']
 const CHILD_CHECK_FLAG = '--check-only'
 
 if (process.argv.includes(CHILD_CHECK_FLAG)) {
@@ -240,6 +244,12 @@ function collectNativeModuleFailures() {
 }
 
 function loadNativeModule(moduleName) {
+  if (moduleName === 'windows-native-registry') {
+    const registry = require(moduleName)
+    // Why: the package defers loading its .node addon until the first registry call.
+    registry.getRegistryKey(registry.HK.CU, 'Environment')
+    return
+  }
   if (moduleName === 'node-pty') {
     loadNodePtyNativeModule()
     return
@@ -256,13 +266,27 @@ function loadNodePtyNativeModule() {
   // Why: node-pty's Windows JS wrapper defers conpty.node/pty.node until a
   // terminal is created, so require('node-pty') alone can miss ABI mismatches.
   const native = loadNativeModule(nativeName)
-  if (requiresPatchedNodePtySourceBuild() && !isNodePtyReleaseBuildDir(native.dir)) {
+  assertNodePtyWindowsConptyRuntime(native?.dir)
+  if (requiresPatchedNodePtySourceBuild() && !isNodePtyReleaseBuildDir(native?.dir)) {
     throw new Error(
       `node-pty resolved to ${native.dir}; expected build/Release so Orca's node-pty patch is active`
     )
   }
 }
 
+function assertNodePtyWindowsConptyRuntime(nativeDir) {
+  if (process.platform !== 'win32' || !isNodePtyReleaseBuildDir(nativeDir)) {
+    return
+  }
+  const runtimeDir = resolve(projectDir, 'node_modules', 'node-pty', 'build', 'Release', 'conpty')
+  const missingFile = NODE_PTY_CONPTY_RUNTIME_FILES.find(
+    (filename) => !existsSync(resolve(runtimeDir, filename))
+  )
+  if (missingFile) {
+    throw new Error(`node-pty ConPTY runtime file is missing: ${resolve(runtimeDir, missingFile)}`)
+  }
+}
+
 function getNodePtyNativeModuleName() {
   if (process.platform !== 'win32') {
     return 'pty'
diff --git a/config/scripts/ensure-native-runtime.test.mjs b/config/scripts/ensure-native-runtime.test.mjs
index 1041ca924f2..0bc8e5ae077 100644
--- a/config/scripts/ensure-native-runtime.test.mjs
+++ b/config/scripts/ensure-native-runtime.test.mjs
@@ -193,6 +193,7 @@ exports.loadNativeModule = function loadNativeModule(nativeName) {
 }
 `
   )
+  writeFakeWindowsRegistry(projectDir)
 }
 
 function writeLoadableNativeModules(projectDir, { nativeDir = null } = {}) {
@@ -214,6 +215,19 @@ exports.loadNativeModule = function loadNativeModule(nativeName) {
 }
 `
   )
+  writeFakeWindowsRegistry(projectDir)
+}
+
+function writeFakeWindowsRegistry(projectDir) {
+  if (process.platform !== 'win32') {
+    return
+  }
+  const registryDir = join(projectDir, 'node_modules', 'windows-native-registry')
+  mkdirSync(registryDir, { recursive: true })
+  writeFileSync(
+    join(registryDir, 'index.js'),
+    'exports.HK = { CU: 0x80000001 }; exports.getRegistryKey = () => ({})\n'
+  )
 }
 
 function writeNodePtyPatchFile(projectDir) {
diff --git a/config/scripts/package-electron-runtime-contract.test.mjs b/config/scripts/package-electron-runtime-contract.test.mjs
index c18272d56a4..204ca03b2f9 100644
--- a/config/scripts/package-electron-runtime-contract.test.mjs
+++ b/config/scripts/package-electron-runtime-contract.test.mjs
@@ -1,9 +1,12 @@
 import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { join, resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { parse } from 'yaml'
 
 const projectDir = resolve(import.meta.dirname, '../..')
+const require = createRequire(import.meta.url)
+const { createPackagedRuntimeNodeModuleResources } = require('../packaged-runtime-node-modules.cjs')
 const packageJson = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'))
 
 describe('Electron runtime package contract', () => {
@@ -25,6 +28,45 @@ describe('Electron runtime package contract', () => {
     expect(packageJson.pnpm.onlyBuiltDependencies).not.toContain('electron')
   })
 
+  it('keeps the native Windows registry addon optional and platform-gated', () => {
+    const rebuildScript = readFileSync(
+      join(projectDir, 'config/scripts/rebuild-native-deps.mjs'),
+      'utf8'
+    )
+    const ensureScript = readFileSync(
+      join(projectDir, 'config/scripts/ensure-native-runtime.mjs'),
+      'utf8'
+    )
+    expect(packageJson.optionalDependencies['windows-native-registry']).toBe('3.2.2')
+    // Why: pnpm installs optional target architectures on every host; the root
+    // Windows-only rebuild owns this addon so macOS/Linux never run node-gyp for it.
+    expect(packageJson.pnpm.onlyBuiltDependencies).not.toContain('windows-native-registry')
+    expect(rebuildScript).toContain(
+      "rebuildPlatform === 'win32' ? ['windows-native-registry'] : []"
+    )
+    expect(ensureScript).toContain(
+      "process.platform === 'win32' ? ['windows-native-registry'] : []"
+    )
+    const packageTargets = {
+      win32: createPackagedRuntimeNodeModuleResources('win32'),
+      darwin: createPackagedRuntimeNodeModuleResources('darwin'),
+      linux: createPackagedRuntimeNodeModuleResources('linux')
+    }
+    expect(packageTargets.win32).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ to: join('node_modules', 'windows-native-registry') }),
+        expect.objectContaining({ to: join('node_modules', 'node-addon-api') })
+      ])
+    )
+    for (const platform of ['darwin', 'linux']) {
+      expect(packageTargets[platform]).not.toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ to: join('node_modules', 'windows-native-registry') })
+        ])
+      )
+    }
+  })
+
   it('guards package scripts that launch Electron tooling', () => {
     const scripts = packageJson.scripts
     const guardedScripts = [
diff --git a/config/scripts/rebuild-native-deps.mjs b/config/scripts/rebuild-native-deps.mjs
index 199149edaa1..cf91055d1e3 100644
--- a/config/scripts/rebuild-native-deps.mjs
+++ b/config/scripts/rebuild-native-deps.mjs
@@ -20,9 +20,18 @@
 
 import { rebuild } from '@electron/rebuild'
 import { execFileSync, spawnSync } from 'node:child_process'
-import { existsSync, globSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import {
+  copyFileSync,
+  existsSync,
+  globSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs'
 import { platform as osPlatform } from 'node:os'
-import { resolve } from 'node:path'
+import { join, resolve } from 'node:path'
 
 const projectDir = process.cwd()
 let cliOptions
@@ -40,6 +49,7 @@ const electronVersion = JSON.parse(
 ).version
 
 const ignoreModules = ['cpu-features']
+const NODE_PTY_CONPTY_RUNTIME_FILES = ['conpty.dll', 'OpenConsole.exe']
 
 if (ignoreModules.length > 0) {
   console.log(`[rebuild] Skipping optional Electron rebuild modules: ${ignoreModules.join(', ')}`)
@@ -49,7 +59,11 @@ if (ignoreModules.length > 0) {
 // modules inside pnpm's .pnpm/ store. Passing an explicit list of modules to
 // rebuild via `onlyModules` ensures they're recompiled against Electron's Node
 // ABI regardless of the package manager's store layout.
-const NATIVE_MODULES = ['node-pty', 'cpu-features']
+const NATIVE_MODULES = [
+  'node-pty',
+  'cpu-features',
+  ...(rebuildPlatform === 'win32' ? ['windows-native-registry'] : [])
+]
 const onlyModules = NATIVE_MODULES.filter((m) => !ignoreModules.includes(m))
 const forceRebuild =
   process.env.ORCA_FORCE_NATIVE_REBUILD === '1' ||
@@ -58,6 +72,7 @@ const forceRebuild =
   rebuildArch !== process.arch
 
 ensureElectronPackageInstalled()
+restoreNodePtyWindowsConptyRuntime()
 
 const patchedNodePtyRebuildReason = forceRebuild ? null : getPatchedNodePtyRebuildReason()
 
@@ -124,6 +139,7 @@ try {
     // Node before postinstall runs this script.
     force: true
   })
+  restoreNodePtyWindowsConptyRuntime()
 } catch (/** @type {any} */ err) {
   console.error('[rebuild] Native module rebuild failed:', err?.message ?? err)
   if (isWindowsNativeLockError(err)) {
@@ -143,6 +159,37 @@ try {
   process.exit(1)
 }
 
+function restoreNodePtyWindowsConptyRuntime() {
+  if (rebuildPlatform !== 'win32' || !onlyModules.includes('node-pty')) {
+    return
+  }
+
+  const nodePtyDir = resolve(projectDir, 'node_modules', 'node-pty')
+  if (!existsSync(join(nodePtyDir, 'build', 'Release', 'conpty.node'))) {
+    return
+  }
+  const conptyRoot = join(nodePtyDir, 'third_party', 'conpty')
+  const sourceDir = readdirSync(conptyRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(conptyRoot, entry.name, `win10-${rebuildArch}`))
+    .find((candidate) => existsSync(candidate))
+  if (!sourceDir) {
+    throw new Error(`node-pty has no ConPTY runtime payload for win10-${rebuildArch}`)
+  }
+
+  const runtimeDir = join(nodePtyDir, 'build', 'Release', 'conpty')
+  mkdirSync(runtimeDir, { recursive: true })
+  for (const filename of NODE_PTY_CONPTY_RUNTIME_FILES) {
+    const sourceFile = join(sourceDir, filename)
+    if (!existsSync(sourceFile)) {
+      throw new Error(`node-pty is missing ${sourceFile}`)
+    }
+    copyFileSync(sourceFile, join(runtimeDir, filename))
+  }
+  // Why: @electron/rebuild bypasses node-pty's postinstall step that normally copies these DLLs.
+  console.log(`[rebuild] Restored node-pty ConPTY runtime files for win10-${rebuildArch}.`)
+}
+
 function ensureElectronPackageInstalled() {
   if (electronPackageIsUsable()) {
     return
@@ -390,6 +437,7 @@ function probeElectronNativeModules(moduleNames) {
 
   const probeSource = `
 const { createRequire } = require('node:module')
+const { existsSync } = require('node:fs')
 const { release } = require('node:os')
 const { resolve } = require('node:path')
 const projectRequire = createRequire(resolve(process.cwd(), 'package.json'))
@@ -411,10 +459,17 @@ if (failures.length > 0) {
 }
 
 function loadNativeModule(moduleName) {
+  if (moduleName === 'windows-native-registry') {
+    const registry = projectRequire(moduleName)
+    // Why: the package defers loading its .node addon until the first registry call.
+    registry.getRegistryKey(registry.HK.CU, 'Environment')
+    return
+  }
   if (moduleName === 'node-pty') {
     projectRequire('node-pty')
     const { loadNativeModule } = projectRequire('node-pty/lib/utils')
     const native = loadNativeModule(getNodePtyNativeModuleName())
+    assertNodePtyWindowsConptyRuntime(native.dir)
     if (requirePatchedNodePtySourceBuild && !isNodePtyReleaseBuildDir(native.dir)) {
       throw new Error(
         'node-pty resolved to ' +
@@ -427,6 +482,26 @@ function loadNativeModule(moduleName) {
   projectRequire(moduleName)
 }
 
+function assertNodePtyWindowsConptyRuntime(nativeDir) {
+  if (process.platform !== 'win32' || !isNodePtyReleaseBuildDir(nativeDir)) {
+    return
+  }
+  const runtimeDir = resolve(
+    process.cwd(),
+    'node_modules',
+    'node-pty',
+    'build',
+    'Release',
+    'conpty'
+  )
+  for (const filename of ${JSON.stringify(NODE_PTY_CONPTY_RUNTIME_FILES)}) {
+    const runtimeFile = resolve(runtimeDir, filename)
+    if (!existsSync(runtimeFile)) {
+      throw new Error('node-pty ConPTY runtime file is missing: ' + runtimeFile)
+    }
+  }
+}
+
 function isNodePtyReleaseBuildDir(nativeDir) {
   return typeof nativeDir === 'string' && nativeDir.replace(/\\\\/g, '/').includes('build/Release/')
 }
diff --git a/config/scripts/rebuild-native-deps.test.mjs b/config/scripts/rebuild-native-deps.test.mjs
index 15e1e616aa9..1eacf9aa127 100644
--- a/config/scripts/rebuild-native-deps.test.mjs
+++ b/config/scripts/rebuild-native-deps.test.mjs
@@ -124,6 +124,61 @@ describe('rebuild-native-deps Electron install fallback', () => {
 })
 
 describe('rebuild-native-deps patched node-pty rebuild', () => {
+  it.skipIf(process.platform !== 'win32')(
+    'repairs a missing ConPTY runtime before probing without recompiling node-pty',
+    () => {
+      const projectDir = mkTempProject()
+
+      try {
+        const rebuildLogPath = join(projectDir, 'electron-rebuild.log')
+        writeFakeUsableElectronPackage(projectDir, { platform: 'win32' })
+        writeFakeElectronRebuild(projectDir, { logPathEnv: 'ORCA_REBUILD_TEST_LOG' })
+        writeFakeLoadableNodePty(projectDir, { nativeDir: '../build/Release/' })
+        writeFakeWindowsRegistry(projectDir)
+        writeFakeNodePtyConptyPayload(projectDir, process.arch)
+
+        const result = runRebuildScript(projectDir, {
+          ORCA_REBUILD_TEST_LOG: rebuildLogPath,
+          npm_config_platform: 'win32',
+          npm_config_arch: process.arch
+        })
+
+        expect(result.status, result.stderr).toBe(0)
+        expect(result.stdout).toContain('Restored node-pty ConPTY runtime files')
+        expect(result.stdout).toContain(
+          'Native modules already load in Electron; skipping rebuild.'
+        )
+        expect(existsSync(rebuildLogPath)).toBe(false)
+      } finally {
+        rmSync(projectDir, { recursive: true, force: true })
+      }
+    }
+  )
+
+  it('restores the ConPTY runtime payload after a Windows Electron rebuild', () => {
+    const projectDir = mkTempProject()
+
+    try {
+      writeFakeUsableElectronPackage(projectDir, { platform: 'win32' })
+      writeFakeElectronRebuild(projectDir)
+      writeFakeNodePtyConptyPayload(projectDir, 'x64')
+
+      const result = runRebuildScript(
+        projectDir,
+        { npm_config_platform: 'win32', npm_config_arch: 'x64' },
+        ['--platform=win32', '--arch=x64', '--force']
+      )
+
+      expect(result.status, result.stderr).toBe(0)
+      expect(result.stdout).toContain('Restored node-pty ConPTY runtime files for win10-x64')
+      const runtimeDir = join(projectDir, 'node_modules', 'node-pty', 'build', 'Release', 'conpty')
+      expect(readFileSync(join(runtimeDir, 'conpty.dll'), 'utf8')).toBe('conpty.dll x64')
+      expect(readFileSync(join(runtimeDir, 'OpenConsole.exe'), 'utf8')).toBe('OpenConsole.exe x64')
+    } finally {
+      rmSync(projectDir, { recursive: true, force: true })
+    }
+  })
+
   it.skipIf(process.platform === 'win32')(
     'rebuilds when Electron can load node-pty but patched build artifacts are missing',
     () => {
@@ -225,7 +280,7 @@ function mkTempProject() {
   return projectDir
 }
 
-function runRebuildScript(projectDir, extraEnv = {}) {
+function runRebuildScript(projectDir, extraEnv = {}, args = []) {
   const env = {
     ...process.env,
     npm_config_platform: 'linux',
@@ -239,7 +294,7 @@ function runRebuildScript(projectDir, extraEnv = {}) {
       delete env[key]
     }
   }
-  return spawnSync(process.execPath, ['config/scripts/rebuild-native-deps.mjs'], {
+  return spawnSync(process.execPath, ['config/scripts/rebuild-native-deps.mjs', ...args], {
     cwd: projectDir,
     encoding: 'utf8',
     env: {
@@ -360,16 +415,20 @@ export async function rebuild(options) {
   )
 }
 
-function writeFakeUsableElectronPackage(projectDir) {
+function writeFakeUsableElectronPackage(projectDir, { platform = 'linux' } = {}) {
   writeFakeElectronPackage(projectDir)
   const electronDir = join(projectDir, 'node_modules', 'electron')
-  const electronPath = join(electronDir, 'dist', 'electron')
+  const platformExecutable = platform === 'win32' ? 'electron.exe' : 'electron'
+  const electronPath = join(electronDir, 'dist', platformExecutable)
   mkdirSync(join(electronDir, 'dist'), { recursive: true })
-  writeFileSync(join(electronDir, 'path.txt'), 'electron')
+  writeFileSync(join(electronDir, 'path.txt'), platformExecutable)
   writeFileSync(join(electronDir, 'dist', 'version'), 'v41.5.0')
-  writeFileSync(
-    electronPath,
-    `#!/usr/bin/env node
+  if (platform === 'win32') {
+    copyFileSync(process.execPath, electronPath)
+  } else {
+    writeFileSync(
+      electronPath,
+      `#!/usr/bin/env node
 const { spawnSync } = require('node:child_process')
 
 const result = spawnSync(process.execPath, process.argv.slice(2), {
@@ -385,8 +444,27 @@ if (result.error) {
 
 process.exit(result.status ?? 0)
 `
+    )
+    chmodSync(electronPath, 0o755)
+  }
+}
+
+function writeFakeNodePtyConptyPayload(projectDir, arch) {
+  const releaseDir = join(projectDir, 'node_modules', 'node-pty', 'build', 'Release')
+  mkdirSync(releaseDir, { recursive: true })
+  writeFileSync(join(releaseDir, 'conpty.node'), 'native addon')
+  const sourceDir = join(
+    projectDir,
+    'node_modules',
+    'node-pty',
+    'third_party',
+    'conpty',
+    '0.1.0',
+    `win10-${arch}`
   )
-  chmodSync(electronPath, 0o755)
+  mkdirSync(sourceDir, { recursive: true })
+  writeFileSync(join(sourceDir, 'conpty.dll'), `conpty.dll ${arch}`)
+  writeFileSync(join(sourceDir, 'OpenConsole.exe'), `OpenConsole.exe ${arch}`)
 }
 
 function writeFakeLoadableNodePty(projectDir, { nativeDir = 'prebuilds/pty' } = {}) {
@@ -403,6 +481,15 @@ exports.loadNativeModule = function loadNativeModule(nativeName) {
   )
 }
 
+function writeFakeWindowsRegistry(projectDir) {
+  const registryDir = join(projectDir, 'node_modules', 'windows-native-registry')
+  mkdirSync(registryDir, { recursive: true })
+  writeFileSync(
+    join(registryDir, 'index.js'),
+    'exports.HK = { CU: 0x80000001 }; exports.getRegistryKey = () => ({})\n'
+  )
+}
+
 function writeNodePtyPatchFile(projectDir) {
   mkdirSync(join(projectDir, 'config', 'patches'), { recursive: true })
   writeFileSync(join(projectDir, 'config', 'patches', 'node-pty@1.1.0.patch'), 'patch marker\n')
diff --git a/package.json b/package.json
index 5035c621383..e5734083688 100644
--- a/package.json
+++ b/package.json
@@ -230,7 +230,8 @@
     "sherpa-onnx-darwin-x64": "1.12.37",
     "sherpa-onnx-linux-arm64": "1.12.37",
     "sherpa-onnx-linux-x64": "1.12.37",
-    "sherpa-onnx-win-x64": "1.12.37"
+    "sherpa-onnx-win-x64": "1.12.37",
+    "windows-native-registry": "3.2.2"
   },
   "lint-staged": {
     "*.{ts,tsx,js,jsx,mjs,mts,cts}": [
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b6ee54760e0..0ed99b766af 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -399,6 +399,9 @@ importers:
       sherpa-onnx-win-x64:
         specifier: 1.12.37
         version: 1.12.37
+      windows-native-registry:
+        specifier: 3.2.2
+        version: 3.2.2
 
 packages:
 
@@ -5453,6 +5456,9 @@ packages:
   node-addon-api@1.7.2:
     resolution: {integrity: sha512-ibPK3iA+vaY1eEjESkQkM0BbCqFOaZMiXRTtdB0u7b4djtY6JnsjvPdUHVMg6xQt3B8fpTTWHI9A+ADjM9frzg==}
 
+  node-addon-api@4.3.0:
+    resolution: {integrity: sha512-73sE9+3UaLYYFmDsFZnqCInzPyh3MqIwZO9cw58yIqAZhONrrabrYyYe3TuIqtIiOuTXVhsGau8hcrhhwSsDIQ==}
+
   node-addon-api@7.1.1:
     resolution: {integrity: sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==}
 
@@ -6745,6 +6751,10 @@ packages:
     engines: {node: '>=8'}
     hasBin: true
 
+  windows-native-registry@3.2.2:
+    resolution: {integrity: sha512-yg1ZnuzUExn+Uq3cODB23Ju15URw0F/sRrSpjavVhHMi46s6Pcukp4+PtumoELmefoeHarCgci0XV34COpuYkw==}
+    os: [win32]
+
   wrap-ansi@6.2.0:
     resolution: {integrity: sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==}
     engines: {node: '>=8'}
@@ -12003,6 +12013,9 @@ snapshots:
   node-addon-api@1.7.2:
     optional: true
 
+  node-addon-api@4.3.0:
+    optional: true
+
   node-addon-api@7.1.1: {}
 
   node-api-version@0.2.1:
@@ -13465,6 +13478,11 @@ snapshots:
       siginfo: 2.0.0
       stackback: 0.0.2
 
+  windows-native-registry@3.2.2:
+    dependencies:
+      node-addon-api: 4.3.0
+    optional: true
+
   wrap-ansi@6.2.0:
     dependencies:
       ansi-styles: 4.3.0
diff --git a/src/main/cli/cli-installer.test.ts b/src/main/cli/cli-installer.test.ts
index a42805313c0..9c17fd21116 100644
--- a/src/main/cli/cli-installer.test.ts
+++ b/src/main/cli/cli-installer.test.ts
@@ -29,6 +29,14 @@ vi.mock('node:child_process', () => ({
 
 import { CliInstaller } from './cli-installer'
 import { buildAppImageCliWrapper } from './appimage-cli-wrapper'
+import {
+  WindowsUserPathRegistryReader,
+  type WindowsUserPathReadResult
+} from './windows-user-path-registry'
+
+function userPathRead(value: string | null, expandable = false): WindowsUserPathReadResult {
+  return { state: 'success', value, expandable }
+}
 
 async function makeFixture(): Promise<{
   root: string
@@ -323,7 +331,7 @@ describe('CliInstaller', () => {
       execPath: 'C:\\Users\\me\\AppData\\Local\\Orca\\Orca.exe',
       appPath: fixture.appPath,
       commandPathOverride: installPath,
-      userPathReader: async () => userPath,
+      userPathReader: async () => userPathRead(userPath),
       userPathWriter: async (value) => {
         userPath = value
       }
@@ -358,7 +366,7 @@ describe('CliInstaller', () => {
         execPath: 'C:\\Users\\me\\AppData\\Local\\Orca\\Orca.exe',
         appPath: fixture.appPath,
         commandPathOverride: installPath,
-        userPathReader: async () => 'C:\\Windows\\System32',
+        userPathReader: async () => userPathRead('C:\\Windows\\System32'),
         userPathWriter: async () => {
           // The .NET error id survives localized or mojibake PowerShell output.
           const error = new Error(
@@ -390,7 +398,7 @@ describe('CliInstaller', () => {
       execPath: 'C:\\Users\\me\\AppData\\Local\\Orca\\Orca.exe',
       appPath: fixture.appPath,
       commandPathOverride: join(fixture.root, 'Programs', 'Orca', 'bin', 'orca.cmd'),
-      userPathReader: async () => 'C:\\Windows\\System32',
+      userPathReader: async () => userPathRead('C:\\Windows\\System32'),
       userPathWriter
     })
 
@@ -416,7 +424,7 @@ describe('CliInstaller', () => {
         execPath: 'C:\\Users\\me\\AppData\\Local\\Orca\\Orca.exe',
         appPath: fixture.appPath,
         commandPathOverride: installPath,
-        userPathReader: async () => 'C:\\Windows\\System32',
+        userPathReader: async () => userPathRead('C:\\Windows\\System32'),
         userPathWriter: async () => {
           throw new Error(message)
         }
@@ -428,36 +436,133 @@ describe('CliInstaller', () => {
     }
   )
 
-  it('settles when the Windows PATH query hangs', async () => {
-    vi.useFakeTimers()
+  it('reports an unknown Windows PATH without spawning PowerShell', async () => {
     const fixture = await makeFixture()
     const installPath = join(fixture.root, 'Programs', 'Orca', 'bin', 'orca.cmd')
-    const killMock = vi.fn()
-    execFileMock.mockImplementation(() => ({ kill: killMock }))
     const installer = new CliInstaller({
       platform: 'win32',
       isPackaged: false,
       userDataPath: fixture.userDataPath,
       execPath: 'C:\\Users\\me\\AppData\\Local\\Orca\\Orca.exe',
       appPath: fixture.appPath,
-      commandPathOverride: installPath
+      commandPathOverride: installPath,
+      userPathReader: async () => ({
+        state: 'unknown',
+        detail: 'Orca could not read the Windows user PATH registry value.'
+      })
     })
 
-    const promise = installer.getStatus()
-    let settled = false
-    void promise
-      .catch(() => undefined)
-      .finally(() => {
-        settled = true
+    await expect(installer.getStatus()).resolves.toMatchObject({
+      state: 'not_installed',
+      pathConfigured: null,
+      detail: expect.stringContaining('could not read')
+    })
+    expect(execFileMock).not.toHaveBeenCalled()
+  })
+
+  it('fails closed without writing when a Windows PATH mutation cannot read the registry', async () => {
+    const fixture = await makeFixture()
+    const userPathWriter = vi.fn()
+    const installer = new CliInstaller({
+      platform: 'win32',
+      isPackaged: false,
+      userDataPath: fixture.userDataPath,
+      execPath: 'C:\\Users\\me\\AppData\\Local\\Orca\\Orca.exe',
+      appPath: fixture.appPath,
+      commandPathOverride: join(fixture.root, 'Programs', 'Orca', 'bin', 'orca.cmd'),
+      userPathReader: async () => ({
+        state: 'unknown',
+        detail: 'Orca could not read the Windows user PATH registry value.'
+      }),
+      userPathWriter
+    })
+
+    await expect(installer.install()).rejects.toThrow('No PATH changes were made')
+    expect(userPathWriter).not.toHaveBeenCalled()
+  })
+
+  it('bypasses cached status data before a Windows PATH mutation', async () => {
+    const fixture = await makeFixture()
+    const installPath = join(fixture.root, 'Programs', 'Orca', 'bin', 'orca.cmd')
+    const pathDirectory = dirname(installPath)
+    let registryPath = 'C:\\Tools'
+    const registryReader = new WindowsUserPathRegistryReader({
+      platform: 'win32',
+      registryLoader: async () => ({
+        HK: { CU: 0x80000001 },
+        getRegistryKey: () => ({
+          Path: { name: 'Path', type: 2, value: registryPath }
+        })
       })
+    })
+    const userPathWriter = vi.fn(async (value: string) => {
+      registryPath = value
+    })
+    const installer = new CliInstaller({
+      platform: 'win32',
+      isPackaged: false,
+      userDataPath: fixture.userDataPath,
+      execPath: 'C:\\Users\\me\\AppData\\Local\\Orca\\Orca.exe',
+      appPath: fixture.appPath,
+      commandPathOverride: installPath,
+      userPathReader: () => registryReader.read(),
+      userPathMutationReader: () => registryReader.readFresh(),
+      userPathWriter,
+      userPathCacheInvalidator: () => registryReader.invalidate()
+    })
 
-    await vi.waitFor(() => expect(execFileMock).toHaveBeenCalled())
-    await vi.advanceTimersByTimeAsync(5_000)
-    await Promise.resolve()
+    await installer.getStatus()
+    registryPath = 'C:\\Tools;C:\\AddedByAnotherInstaller'
+    await installer.install()
 
-    expect(settled).toBe(true)
-    await expect(promise).rejects.toThrow('Windows PATH command timed out')
-    expect(killMock).toHaveBeenCalled()
+    expect(userPathWriter).toHaveBeenCalledWith(
+      `C:\\Tools;C:\\AddedByAnotherInstaller;${pathDirectory}`
+    )
+  })
+
+  it('matches expandable Windows PATH entries case-insensitively without rewriting them', async () => {
+    const fixture = await makeFixture()
+    const installPath = join(fixture.root, 'Local App Data', 'Orca', 'bin', 'orca.cmd')
+    const userPathWriter = vi.fn()
+    const installer = new CliInstaller({
+      platform: 'win32',
+      isPackaged: false,
+      userDataPath: fixture.userDataPath,
+      execPath: 'C:\\Users\\me\\AppData\\Local\\Orca\\Orca.exe',
+      appPath: fixture.appPath,
+      commandPathOverride: installPath,
+      windowsEnvironment: { LOCALAPPDATA: join(fixture.root, 'Local App Data') },
+      userPathReader: async () => userPathRead('%localappdata%\\Orca\\bin\\', true),
+      userPathWriter
+    })
+
+    await expect(installer.install()).resolves.toMatchObject({
+      state: 'installed',
+      pathConfigured: true
+    })
+    expect(userPathWriter).not.toHaveBeenCalled()
+  })
+
+  it('does not expand environment variables stored in a REG_SZ Windows PATH', async () => {
+    const fixture = await makeFixture()
+    const installPath = join(fixture.root, 'Local App Data', 'Orca', 'bin', 'orca.cmd')
+    const pathDirectory = dirname(installPath)
+    const userPathWriter = vi.fn()
+    const installer = new CliInstaller({
+      platform: 'win32',
+      isPackaged: false,
+      userDataPath: fixture.userDataPath,
+      execPath: 'C:\\Users\\me\\AppData\\Local\\Orca\\Orca.exe',
+      appPath: fixture.appPath,
+      commandPathOverride: installPath,
+      windowsEnvironment: { LOCALAPPDATA: join(fixture.root, 'Local App Data') },
+      userPathReader: async () => userPathRead('%LOCALAPPDATA%\\Orca\\bin'),
+      userPathWriter
+    })
+
+    await installer.install()
+
+    expect(userPathWriter).toHaveBeenCalledWith(`%LOCALAPPDATA%\\Orca\\bin;${pathDirectory}`)
   })
 
   // Why: this test creates a Unix symlink to /tmp/not-orca, which only applies on macOS/Linux.
@@ -1189,7 +1294,7 @@ describe('CliInstaller', () => {
       userDataPath: fixture.userDataPath,
       execPath: join(fixture.root, 'D Custom Orca', 'Orca.exe'),
       appPath: fixture.appPath,
-      userPathReader: async () => null,
+      userPathReader: async () => userPathRead(null),
       userPathWriter: async () => {}
     })
 
@@ -1197,6 +1302,33 @@ describe('CliInstaller', () => {
     expect(status.commandPath).toBe(join(resourcesPath, 'bin', 'orca.exe'))
   })
 
+  it('keeps a bundled Windows launcher installed when the user PATH read is unknown', async () => {
+    const fixture = await makeFixture()
+    const resourcesPath = join(fixture.root, 'resources')
+    const bundledLauncher = join(resourcesPath, 'bin', 'orca.exe')
+    await mkdir(dirname(bundledLauncher), { recursive: true })
+    await writeFile(bundledLauncher, 'native launcher', 'utf8')
+
+    const installer = new CliInstaller({
+      platform: 'win32',
+      isPackaged: true,
+      resourcesPath,
+      userDataPath: fixture.userDataPath,
+      execPath: join(fixture.root, 'Orca.exe'),
+      appPath: fixture.appPath,
+      userPathReader: async () => ({
+        state: 'unknown',
+        detail: 'Orca could not read the Windows user PATH registry value.'
+      })
+    })
+
+    await expect(installer.getStatus()).resolves.toMatchObject({
+      state: 'installed',
+      pathConfigured: null,
+      detail: expect.stringContaining('could not read')
+    })
+  })
+
   it('does not overwrite the packaged Windows launcher while registering PATH', async () => {
     const fixture = await makeFixture()
     const localAppDataPath = join(fixture.root, 'AppData', 'Local')
@@ -1215,7 +1347,7 @@ describe('CliInstaller', () => {
       userDataPath: fixture.userDataPath,
       execPath: join(fixture.root, 'D Custom Orca', 'Orca.exe'),
       appPath: fixture.appPath,
-      userPathReader: async () => userPath,
+      userPathReader: async () => userPathRead(userPath),
       userPathWriter: async (value) => {
         userPath = value
       }
diff --git a/src/main/cli/cli-installer.ts b/src/main/cli/cli-installer.ts
index c5f1286126b..431c04e917b 100644
--- a/src/main/cli/cli-installer.ts
+++ b/src/main/cli/cli-installer.ts
@@ -18,6 +18,12 @@ import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:pat
 import { promisify } from 'node:util'
 import type { CliInstallMethod, CliInstallStatus } from '../../shared/cli-install-types'
 import { buildAppImageCliWrapper } from './appimage-cli-wrapper'
+import {
+  invalidateWindowsUserPathRegistryCache,
+  readFreshWindowsUserPathRegistry,
+  readWindowsUserPathRegistry,
+  type WindowsUserPathReadResult
+} from './windows-user-path-registry'
 
 const execFileAsync = promisify(execFile)
 const DEFAULT_MAC_COMMAND_PATH = '/usr/local/bin/orca'
@@ -25,7 +31,7 @@ const DEV_COMMAND_NAME = 'orca-dev'
 const LINUX_COMMAND_NAME = 'orca-ide'
 const LEGACY_LINUX_COMMAND_NAME = 'orca'
 const DEV_LAUNCHER_DIR = ['cli', 'bin']
-const WINDOWS_PATH_COMMAND_TIMEOUT_MS = 5_000
+const WINDOWS_PATH_WRITE_TIMEOUT_MS = 5_000
 
 type CliInstallerOptions = {
   platform?: NodeJS.Platform
@@ -41,8 +47,11 @@ type CliInstallerOptions = {
   /** Feeds into the /usr/local/bin existence check at construction time; used in tests to simulate absent /usr/local/bin on arm64 without relying on real filesystem state. */
   defaultMacCommandPath?: string
   privilegedRunner?: (command: string) => Promise<void>
-  userPathReader?: () => Promise<string | null>
+  userPathReader?: () => Promise<WindowsUserPathReadResult>
+  userPathMutationReader?: () => Promise<WindowsUserPathReadResult>
   userPathWriter?: (value: string) => Promise<void>
+  userPathCacheInvalidator?: () => void
+  windowsEnvironment?: NodeJS.ProcessEnv
   /** Why: AppImage reports a stable outer file path via $APPIMAGE while bundled resources live in an ephemeral FUSE mount. */
   appImagePath?: string | null
 }
@@ -65,8 +74,11 @@ export class CliInstaller {
   private readonly commandPathOverride: string | null
   private readonly macCommandPath: string
   private readonly privilegedRunner: (command: string) => Promise<void>
-  private readonly userPathReader: () => Promise<string | null>
+  private readonly userPathReader: () => Promise<WindowsUserPathReadResult>
+  private readonly userPathMutationReader: () => Promise<WindowsUserPathReadResult>
   private readonly userPathWriter: (value: string) => Promise<void>
+  private readonly userPathCacheInvalidator: () => void
+  private readonly windowsEnvironment: NodeJS.ProcessEnv
   private readonly appImagePath: string | null
 
   private get commandName(): string {
@@ -105,8 +117,13 @@ export class CliInstaller {
       ? candidateMacPath
       : join(this.homePath, '.local', 'bin', 'orca')
     this.privilegedRunner = options.privilegedRunner ?? runMacPrivilegedCommand
-    this.userPathReader = options.userPathReader ?? (() => readWindowsUserPath())
+    this.userPathReader = options.userPathReader ?? readWindowsUserPathRegistry
+    this.userPathMutationReader =
+      options.userPathMutationReader ?? options.userPathReader ?? readFreshWindowsUserPathRegistry
     this.userPathWriter = options.userPathWriter ?? ((value) => writeWindowsUserPath(value))
+    this.userPathCacheInvalidator =
+      options.userPathCacheInvalidator ?? invalidateWindowsUserPathRegistryCache
+    this.windowsEnvironment = options.windowsEnvironment ?? process.env
     this.appImagePath =
       this.platform === 'linux' && this.isPackaged
         ? (options.appImagePath ?? process.env.APPIMAGE ?? null)
@@ -164,8 +181,8 @@ export class CliInstaller {
           ? await this.inspectAppImageWrapper(spec.commandPath, launcherPath)
           : await this.inspectWindowsWrapper(spec.commandPath, launcherPath)
     const pathDirectory = dirname(spec.commandPath)
-    const pathConfigured = await this.isPathConfigured(pathDirectory)
-    return this.withPathInfo(baseStatus, pathDirectory, pathConfigured)
+    const pathProbe = await this.probePathConfiguration(pathDirectory)
+    return this.withPathInfo(baseStatus, pathDirectory, pathProbe)
   }
 
   async install(): Promise<CliInstallStatus> {
@@ -763,23 +780,40 @@ export class CliInstaller {
     }
   }
 
-  private async isPathConfigured(pathDirectory: string): Promise<boolean> {
-    const pathValue =
-      this.platform === 'win32' ? await this.userPathReader() : (this.processPathEnv ?? '')
-    return splitPathEntries(this.platform, pathValue).some((entry) =>
-      samePathEntry(this.platform, entry, pathDirectory)
-    )
+  private async probePathConfiguration(
+    pathDirectory: string
+  ): Promise<{ configured: boolean | null; detail: string | null }> {
+    if (this.platform !== 'win32') {
+      return {
+        configured: splitPathEntries(this.platform, this.processPathEnv ?? '').some((entry) =>
+          samePathEntry(this.platform, entry, pathDirectory)
+        ),
+        detail: null
+      }
+    }
+
+    const result = await this.userPathReader()
+    if (result.state === 'unknown') {
+      return { configured: null, detail: result.detail }
+    }
+    return {
+      configured: splitPathEntries('win32', result.value).some((entry) =>
+        samePathEntry('win32', entry, pathDirectory, this.windowsEnvironment, result.expandable)
+      ),
+      detail: null
+    }
   }
 
   private withPathInfo(
     status: CliInstallStatus,
     pathDirectory: string,
-    pathConfigured: boolean
+    pathProbe: { configured: boolean | null; detail: string | null }
   ): CliInstallStatus {
+    const { configured: pathConfigured } = pathProbe
     if (
       this.isWindowsPackagedBundledCommand(status.commandPath, status.launcherPath) &&
       status.state === 'installed' &&
-      !pathConfigured
+      pathConfigured === false
     ) {
       return {
         ...status,
@@ -791,6 +825,17 @@ export class CliInstaller {
       }
     }
 
+    if (pathConfigured === null) {
+      return {
+        ...status,
+        pathDirectory,
+        pathConfigured,
+        detail:
+          pathProbe.detail ??
+          'The Orca launcher exists, but Orca could not check your Windows user PATH.'
+      }
+    }
+
     if (status.state !== 'installed') {
       return {
         ...status,
@@ -819,9 +864,13 @@ export class CliInstaller {
   }
 
   private async ensureWindowsPathEntry(pathDirectory: string): Promise<void> {
-    const current = await this.userPathReader()
-    const entries = splitPathEntries('win32', current)
-    if (entries.some((entry) => samePathEntry('win32', entry, pathDirectory))) {
+    const current = await this.readWindowsUserPathForMutation()
+    const entries = splitPathEntries('win32', current.value)
+    if (
+      entries.some((entry) =>
+        samePathEntry('win32', entry, pathDirectory, this.windowsEnvironment, current.expandable)
+      )
+    ) {
       return
     }
     entries.push(pathDirectory)
@@ -832,15 +881,31 @@ export class CliInstaller {
     if (this.platform !== 'win32') {
       return
     }
-    const current = await this.userPathReader()
-    const entries = splitPathEntries('win32', current)
-    const nextEntries = entries.filter((entry) => !samePathEntry('win32', entry, pathDirectory))
+    const current = await this.readWindowsUserPathForMutation()
+    const entries = splitPathEntries('win32', current.value)
+    const nextEntries = entries.filter(
+      (entry) =>
+        !samePathEntry('win32', entry, pathDirectory, this.windowsEnvironment, current.expandable)
+    )
     if (nextEntries.length === entries.length) {
       return
     }
     await this.writeWindowsUserPathEntry(nextEntries.join(';'), pathDirectory, 'remove')
   }
 
+  private async readWindowsUserPathForMutation(): Promise<{
+    value: string | null
+    expandable: boolean
+  }> {
+    const result = await this.userPathMutationReader()
+    if (result.state === 'success') {
+      return { value: result.value, expandable: result.expandable }
+    }
+    // Why: PATH updates are read-modify-write; continuing after an unknown read
+    // could replace the user's existing PATH with an incomplete value.
+    throw new Error(`${result.detail} No PATH changes were made.`)
+  }
+
   // Why: raw PowerShell errors reach the UI, so translate denied PATH writes
   // while preserving the original diagnostic as the error cause.
   private async writeWindowsUserPathEntry(
@@ -850,6 +915,7 @@ export class CliInstaller {
   ): Promise<void> {
     try {
       await this.userPathWriter(value)
+      this.userPathCacheInvalidator()
     } catch (error) {
       if (!isWindowsUserPathPermissionError(error)) {
         throw error
@@ -1019,9 +1085,16 @@ function uniquePathEntries(platform: NodeJS.Platform, entries: string[]): string
   return result
 }
 
-function samePathEntry(platform: NodeJS.Platform, left: string, right: string): boolean {
+function samePathEntry(
+  platform: NodeJS.Platform,
+  left: string,
+  right: string,
+  windowsEnvironment: NodeJS.ProcessEnv = process.env,
+  expandWindowsVariables = true
+): boolean {
   return platform === 'win32'
-    ? normalizeWindowsPath(left) === normalizeWindowsPath(right)
+    ? normalizeWindowsPath(left, windowsEnvironment, expandWindowsVariables) ===
+        normalizeWindowsPath(right, windowsEnvironment, expandWindowsVariables)
     : left === right
 }
 
@@ -1043,8 +1116,22 @@ async function isExecutableFile(commandPath: string): Promise<boolean> {
   }
 }
 
-function normalizeWindowsPath(value: string): string {
-  return value.replaceAll('/', '\\').replace(/\\+$/, '').toLowerCase()
+function normalizeWindowsPath(
+  value: string,
+  env: NodeJS.ProcessEnv = process.env,
+  expandEnvironmentVariables = true
+): string {
+  return (expandEnvironmentVariables ? expandWindowsEnvironmentVariables(value, env) : value)
+    .replaceAll('/', '\\')
+    .replace(/\\+$/, '')
+    .toLowerCase()
+}
+
+function expandWindowsEnvironmentVariables(value: string, env: NodeJS.ProcessEnv): string {
+  return value.replace(/%([^%]+)%/g, (match, rawName: string) => {
+    const envKey = Object.keys(env).find((key) => key.toLowerCase() === rawName.toLowerCase())
+    return envKey && env[envKey] ? env[envKey] : match
+  })
 }
 
 function escapeWindowsBatchValue(value: string): string {
@@ -1108,15 +1195,6 @@ function isAbsoluteForPlatform(platform: NodeJS.Platform, value: string): boolea
   return isAbsolute(value)
 }
 
-async function readWindowsUserPath(): Promise<string | null> {
-  const stdout = await runWindowsPathCommand([
-    '-NoProfile',
-    '-Command',
-    "[Environment]::GetEnvironmentVariable('Path','User')"
-  ])
-  return stdout.trim() || null
-}
-
 async function writeWindowsUserPath(value: string): Promise<void> {
   await runWindowsPathCommand([
     '-NoProfile',
@@ -1150,16 +1228,14 @@ function runWindowsPathCommand(args: string[]): Promise<string> {
     // not keep command registration status or install/remove pending forever.
     const timeout = setTimeout(() => {
       child?.kill()
-      finish(
-        new Error(`Windows PATH command timed out after ${WINDOWS_PATH_COMMAND_TIMEOUT_MS}ms.`)
-      )
-    }, WINDOWS_PATH_COMMAND_TIMEOUT_MS)
+      finish(new Error(`Windows PATH command timed out after ${WINDOWS_PATH_WRITE_TIMEOUT_MS}ms.`))
+    }, WINDOWS_PATH_WRITE_TIMEOUT_MS)
 
     try {
       child = execFile(
         'powershell',
         args,
-        { encoding: 'utf8', timeout: WINDOWS_PATH_COMMAND_TIMEOUT_MS },
+        { encoding: 'utf8', timeout: WINDOWS_PATH_WRITE_TIMEOUT_MS },
         (error, stdout) => {
           finish(error ?? null, stdout)
         }
diff --git a/src/main/cli/windows-user-path-registry.test.ts b/src/main/cli/windows-user-path-registry.test.ts
new file mode 100644
index 00000000000..12beca13852
--- /dev/null
+++ b/src/main/cli/windows-user-path-registry.test.ts
@@ -0,0 +1,127 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  invalidateWindowsUserPathRegistryCache,
+  readWindowsUserPathRegistry,
+  WindowsUserPathRegistryReader
+} from './windows-user-path-registry'
+
+function registryModule(pathValue?: string, type = 2) {
+  return {
+    HK: { CU: 0x80000001 },
+    REG: { SZ: 1, EXPAND_SZ: 2 },
+    getRegistryKey: vi.fn(() =>
+      pathValue === undefined ? {} : { Path: { name: 'Path', type, value: pathValue } }
+    )
+  }
+}
+
+describe('WindowsUserPathRegistryReader', () => {
+  it('reads Unicode REG_EXPAND_SZ values without expanding the stored text', async () => {
+    const registry = registryModule('%LOCALAPPDATA%\\Orca;C:\\工具\\bin;C:\\Développement')
+    const reader = new WindowsUserPathRegistryReader({
+      platform: 'win32',
+      registryLoader: async () => registry
+    })
+
+    await expect(reader.read()).resolves.toEqual({
+      state: 'success',
+      value: '%LOCALAPPDATA%\\Orca;C:\\工具\\bin;C:\\Développement',
+      expandable: true
+    })
+    expect(registry.getRegistryKey).toHaveBeenCalledWith(0x80000001, 'Environment')
+  })
+
+  it('distinguishes a missing Path value from a registry read failure', async () => {
+    const missingReader = new WindowsUserPathRegistryReader({
+      platform: 'win32',
+      registryLoader: async () => registryModule()
+    })
+    const failedReader = new WindowsUserPathRegistryReader({
+      platform: 'win32',
+      registryLoader: async () => {
+        throw new Error('native addon unavailable')
+      }
+    })
+
+    await expect(missingReader.read()).resolves.toEqual({
+      state: 'success',
+      value: null,
+      expandable: false
+    })
+    await expect(failedReader.read()).resolves.toMatchObject({ state: 'unknown' })
+  })
+
+  it('coalesces concurrent reads, caches status reads, and bypasses the cache when fresh', async () => {
+    let now = 100
+    let resolveRegistry!: (value: ReturnType<typeof registryModule>) => void
+    const registryLoader = vi.fn(
+      () =>
+        new Promise<ReturnType<typeof registryModule>>((resolve) => {
+          resolveRegistry = resolve
+        })
+    )
+    const reader = new WindowsUserPathRegistryReader({
+      platform: 'win32',
+      registryLoader,
+      now: () => now,
+      cacheTtlMs: 1_000
+    })
+
+    const first = reader.read()
+    const concurrent = reader.read()
+    expect(registryLoader).toHaveBeenCalledOnce()
+    resolveRegistry(registryModule('C:\\Tools'))
+    await expect(Promise.all([first, concurrent])).resolves.toEqual([
+      { state: 'success', value: 'C:\\Tools', expandable: true },
+      { state: 'success', value: 'C:\\Tools', expandable: true }
+    ])
+
+    await reader.read()
+    expect(registryLoader).toHaveBeenCalledOnce()
+
+    now += 1
+    const refreshed = reader.readFresh()
+    expect(registryLoader).toHaveBeenCalledTimes(2)
+    resolveRegistry(registryModule('C:\\Tools;C:\\Orca'))
+    await expect(refreshed).resolves.toEqual({
+      state: 'success',
+      value: 'C:\\Tools;C:\\Orca',
+      expandable: true
+    })
+  })
+
+  it.each([
+    { type: 1, expandable: false },
+    { type: 2, expandable: true }
+  ])('preserves whether registry type $type expands variables', async ({ type, expandable }) => {
+    const reader = new WindowsUserPathRegistryReader({
+      platform: 'win32',
+      registryLoader: async () => registryModule('%LOCALAPPDATA%\\Orca', type)
+    })
+
+    await expect(reader.read()).resolves.toEqual({
+      state: 'success',
+      value: '%LOCALAPPDATA%\\Orca',
+      expandable
+    })
+  })
+
+  it('does not load the Windows-only dependency on other platforms', async () => {
+    const registryLoader = vi.fn(async () => registryModule('C:\\Tools'))
+    const reader = new WindowsUserPathRegistryReader({
+      platform: 'linux',
+      registryLoader
+    })
+
+    await expect(reader.read()).resolves.toMatchObject({ state: 'unknown' })
+    expect(registryLoader).not.toHaveBeenCalled()
+  })
+
+  it.runIf(process.platform === 'win32')(
+    'loads the real native addon and reads the current Windows user PATH',
+    async () => {
+      invalidateWindowsUserPathRegistryCache()
+      await expect(readWindowsUserPathRegistry()).resolves.toMatchObject({ state: 'success' })
+    }
+  )
+})
diff --git a/src/main/cli/windows-user-path-registry.ts b/src/main/cli/windows-user-path-registry.ts
new file mode 100644
index 00000000000..d3e493fd87d
--- /dev/null
+++ b/src/main/cli/windows-user-path-registry.ts
@@ -0,0 +1,160 @@
+import { createRequire } from 'node:module'
+
+export type WindowsUserPathReadResult =
+  | { state: 'success'; value: string | null; expandable: boolean }
+  | { state: 'unknown'; detail: string }
+
+type RegistryValue = {
+  name?: unknown
+  type?: unknown
+  value?: unknown
+}
+
+type WindowsRegistryModule = {
+  HK: { CU: number }
+  getRegistryKey: (
+    root: number,
+    path: string
+  ) => Record<string, RegistryValue | undefined> | null | undefined
+}
+
+type WindowsUserPathRegistryReaderOptions = {
+  platform?: NodeJS.Platform
+  registryLoader?: () => Promise<WindowsRegistryModule>
+  now?: () => number
+  cacheTtlMs?: number
+}
+
+const DEFAULT_CACHE_TTL_MS = 1_000
+const USER_ENVIRONMENT_KEY = 'Environment'
+const USER_PATH_VALUE = 'Path'
+const REG_SZ = 1
+const REG_EXPAND_SZ = 2
+const requireFromMain = createRequire(__filename)
+
+async function loadWindowsRegistryModule(): Promise<WindowsRegistryModule> {
+  // Why: the optional dependency is not present in non-Windows installs, so
+  // TypeScript and the main bundle must not resolve it eagerly.
+  return requireFromMain('windows-native-registry') as WindowsRegistryModule
+}
+
+export class WindowsUserPathRegistryReader {
+  private readonly platform: NodeJS.Platform
+  private readonly registryLoader: () => Promise<WindowsRegistryModule>
+  private readonly now: () => number
+  private readonly cacheTtlMs: number
+  private cached: { readAt: number; result: WindowsUserPathReadResult } | null = null
+  private inFlight: Promise<WindowsUserPathReadResult> | null = null
+  private generation = 0
+
+  constructor(options: WindowsUserPathRegistryReaderOptions = {}) {
+    this.platform = options.platform ?? process.platform
+    this.registryLoader = options.registryLoader ?? loadWindowsRegistryModule
+    this.now = options.now ?? Date.now
+    this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS
+  }
+
+  async read(): Promise<WindowsUserPathReadResult> {
+    if (this.platform !== 'win32') {
+      return {
+        state: 'unknown',
+        detail: 'The Windows user PATH registry is only available on Windows.'
+      }
+    }
+
+    const now = this.now()
+    const cacheAge = this.cached ? now - this.cached.readAt : null
+    if (this.cached && cacheAge !== null && cacheAge >= 0 && cacheAge < this.cacheTtlMs) {
+      return this.cached.result
+    }
+    if (this.inFlight) {
+      return this.inFlight
+    }
+
+    const generation = this.generation
+    const inFlight = this.readUncached().then((result) => {
+      if (result.state === 'success' && generation === this.generation) {
+        this.cached = { readAt: this.now(), result }
+      }
+      return result
+    })
+    this.inFlight = inFlight
+    try {
+      return await inFlight
+    } finally {
+      if (this.inFlight === inFlight) {
+        this.inFlight = null
+      }
+    }
+  }
+
+  async readFresh(): Promise<WindowsUserPathReadResult> {
+    this.invalidate()
+    const generation = this.generation
+    const result = await this.readUncached()
+    if (result.state === 'success' && generation === this.generation) {
+      this.cached = { readAt: this.now(), result }
+    }
+    return result
+  }
+
+  invalidate(): void {
+    this.generation += 1
+    this.cached = null
+    // Why: a mutation must not join a registry read that may predate an external PATH update.
+    this.inFlight = null
+  }
+
+  private async readUncached(): Promise<WindowsUserPathReadResult> {
+    try {
+      const registry = await this.registryLoader()
+      const key = registry.getRegistryKey(registry.HK.CU, USER_ENVIRONMENT_KEY)
+      if (!key || typeof key !== 'object') {
+        return {
+          state: 'unknown',
+          detail: 'Orca could not read the Windows user PATH registry key.'
+        }
+      }
+
+      const pathEntry = Object.entries(key).find(
+        ([name]) => name.toLowerCase() === USER_PATH_VALUE.toLowerCase()
+      )?.[1]
+      if (!pathEntry) {
+        return { state: 'success', value: null, expandable: false }
+      }
+      if (
+        (pathEntry.type !== REG_SZ && pathEntry.type !== REG_EXPAND_SZ) ||
+        typeof pathEntry.value !== 'string'
+      ) {
+        return {
+          state: 'unknown',
+          detail: 'The Windows user PATH registry value has an unsupported format.'
+        }
+      }
+      return {
+        state: 'success',
+        value: pathEntry.value || null,
+        expandable: pathEntry.type === REG_EXPAND_SZ
+      }
+    } catch {
+      return {
+        state: 'unknown',
+        detail: 'Orca could not read the Windows user PATH registry value.'
+      }
+    }
+  }
+}
+
+const defaultWindowsUserPathRegistryReader = new WindowsUserPathRegistryReader()
+
+export function readWindowsUserPathRegistry(): Promise<WindowsUserPathReadResult> {
+  return defaultWindowsUserPathRegistryReader.read()
+}
+
+export function readFreshWindowsUserPathRegistry(): Promise<WindowsUserPathReadResult> {
+  return defaultWindowsUserPathRegistryReader.readFresh()
+}
+
+export function invalidateWindowsUserPathRegistryCache(): void {
+  defaultWindowsUserPathRegistryReader.invalidate()
+}
diff --git a/src/main/cli/wsl-cli-installer.test.ts b/src/main/cli/wsl-cli-installer.test.ts
index 547679df46f..13bd8088de3 100644
--- a/src/main/cli/wsl-cli-installer.test.ts
+++ b/src/main/cli/wsl-cli-installer.test.ts
@@ -206,6 +206,27 @@ describe('WslCliInstaller', () => {
     expect(installCommand).toContain('[ ! -L "$legacy_command_path" ]')
   })
 
+  it('continues checking WSL when the host launcher exists but host PATH is unknown', async () => {
+    const wsl = createWslRunner()
+    const hostStatus = {
+      ...makeHostStatus(),
+      pathConfigured: null,
+      detail: 'Orca could not read the Windows user PATH registry value.'
+    } satisfies CliInstallStatus
+    const installer = new WslCliInstaller({
+      platform: 'win32',
+      distro: 'Ubuntu',
+      hostInstaller: { getStatus: async () => hostStatus },
+      wslRunner: wsl.runner
+    })
+
+    await expect(installer.getStatus()).resolves.toMatchObject({
+      supported: true,
+      state: 'not_installed',
+      commandPath: '/home/alice/.local/bin/orca-ide'
+    })
+  })
+
   it('derives the shared WSL bridge path for current and legacy command names', () => {
     expect(_internals.getBridgePathFromCommandPath('/home/alice/.local/bin/orca-ide')).toBe(
       '/home/alice/.local/share/orca/orca-wsl-bridge.ps1'
diff --git a/src/renderer/src/components/emulator-pane/mobile-emulator-agent-setup-cli-state.ts b/src/renderer/src/components/emulator-pane/mobile-emulator-agent-setup-cli-state.ts
index d464a64f894..b20565d823f 100644
--- a/src/renderer/src/components/emulator-pane/mobile-emulator-agent-setup-cli-state.ts
+++ b/src/renderer/src/components/emulator-pane/mobile-emulator-agent-setup-cli-state.ts
@@ -2,7 +2,7 @@ import type { CliInstallStatus } from '../../../../shared/cli-install-types'
 import type { StepState } from '../settings/BrowserUseStepBadge'
 
 export function getMobileEmulatorCliPathNeedsAttention(status: CliInstallStatus | null): boolean {
-  return status?.state === 'installed' && !status.pathConfigured
+  return status?.state === 'installed' && status.pathConfigured === false
 }
 
 export function getMobileEmulatorCliStepBadgeState(input: {
diff --git a/src/renderer/src/components/feature-tips/feature-tip-cli-install-action.ts b/src/renderer/src/components/feature-tips/feature-tip-cli-install-action.ts
index e78e5695cdc..dbf4364808a 100644
--- a/src/renderer/src/components/feature-tips/feature-tip-cli-install-action.ts
+++ b/src/renderer/src/components/feature-tips/feature-tip-cli-install-action.ts
@@ -8,7 +8,7 @@ export async function installCliFromFeatureTip(
   installCli: () => Promise<CliInstallStatus>
 ): Promise<FeatureTipCliInstallResult> {
   const status = await installCli()
-  if (status.state === 'installed' && status.pathConfigured) {
+  if (status.state === 'installed' && status.pathConfigured === true) {
     return { kind: 'installed', status }
   }
   return { kind: 'needs-attention', status }
diff --git a/src/renderer/src/components/feature-tips/feature-tip-startup-gate.ts b/src/renderer/src/components/feature-tips/feature-tip-startup-gate.ts
index ea426225130..a7eef0b8ead 100644
--- a/src/renderer/src/components/feature-tips/feature-tip-startup-gate.ts
+++ b/src/renderer/src/components/feature-tips/feature-tip-startup-gate.ts
@@ -16,7 +16,7 @@ export type FeatureTipsAppOpenDecision =
 export function isCliFeatureTipCompleted(status: CliInstallStatus): boolean {
   // Why: unsupported launch modes cannot complete setup, but an installed
   // launcher still needs attention until it is reachable on PATH.
-  return !status.supported || (status.state === 'installed' && status.pathConfigured)
+  return !status.supported || (status.state === 'installed' && status.pathConfigured === true)
 }
 
 export function getFeatureTipsAppOpenDecision(args: {
diff --git a/src/renderer/src/components/onboarding/onboarding-feature-setup.test.ts b/src/renderer/src/components/onboarding/onboarding-feature-setup.test.ts
index ab1d1a43f91..e0916c5fad0 100644
--- a/src/renderer/src/components/onboarding/onboarding-feature-setup.test.ts
+++ b/src/renderer/src/components/onboarding/onboarding-feature-setup.test.ts
@@ -301,4 +301,24 @@ describe('onboarding feature setup runner', () => {
       installCli.mock.invocationCallOrder[0]
     )
   })
+
+  it('warns without changing PATH when the Windows registry read is unknown', async () => {
+    const unknownStatus: CliInstallStatus = {
+      ...INSTALLED_CLI_STATUS,
+      platform: 'win32',
+      pathConfigured: null,
+      detail: 'Orca could not read the Windows user PATH registry value.'
+    }
+    const deps = createDeps({ getCliStatus: vi.fn(async () => unknownStatus) })
+
+    const result = await runOnboardingFeatureSetup(
+      { browserUse: true, computerUse: false, orchestration: false, linearTickets: false },
+      deps
+    )
+
+    expect(result.cliTouched).toBe(false)
+    expect(result.warnings).toContainEqual({ featureId: 'cli', message: unknownStatus.detail })
+    expect(deps.showCliRegistrationPrompt).not.toHaveBeenCalled()
+    expect(deps.installCli).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/renderer/src/components/onboarding/onboarding-feature-setup.ts b/src/renderer/src/components/onboarding/onboarding-feature-setup.ts
index c16632d874b..f92a5e85f63 100644
--- a/src/renderer/src/components/onboarding/onboarding-feature-setup.ts
+++ b/src/renderer/src/components/onboarding/onboarding-feature-setup.ts
@@ -225,7 +225,13 @@ export async function runOnboardingFeatureSetup(
         featureId: 'cli',
         message: status.detail ?? 'Orca CLI registration is not available on this platform.'
       })
-    } else if (status.state !== 'installed' || !status.pathConfigured) {
+    } else if (status.pathConfigured === null) {
+      // Why: an unknown registry read cannot safely drive a PATH read-modify-write.
+      warnings.push({
+        featureId: 'cli',
+        message: status.detail ?? 'Orca could not check your Windows user PATH.'
+      })
+    } else if (status.state !== 'installed' || status.pathConfigured === false) {
       await deps.showCliRegistrationPrompt?.()
       const next = await deps.installCli()
       cliTouched = true
@@ -234,7 +240,7 @@ export async function runOnboardingFeatureSetup(
           featureId: 'cli',
           message: next.detail ?? 'Orca CLI registration needs attention.'
         })
-      } else if (!next.pathConfigured && next.detail) {
+      } else if (next.pathConfigured !== true && next.detail) {
         warnings.push({ featureId: 'cli', message: next.detail })
       }
     }
diff --git a/src/renderer/src/components/settings/BrowserUsePane.tsx b/src/renderer/src/components/settings/BrowserUsePane.tsx
index 8f2dea14ee4..9871615acdf 100644
--- a/src/renderer/src/components/settings/BrowserUsePane.tsx
+++ b/src/renderer/src/components/settings/BrowserUsePane.tsx
@@ -128,7 +128,8 @@ export function BrowserUseSetup({
   const cookiesImported = !!defaultProfile?.source
 
   const cliEnabled = isOrcaCliAvailableOnPath(cliStatus)
-  const cliPathNeedsAttention = cliStatus?.state === 'installed' && !cliStatus.pathConfigured
+  const cliPathNeedsAttention =
+    cliStatus?.state === 'installed' && cliStatus.pathConfigured === false
   const cliSupported = cliStatus?.supported ?? false
 
   const {
diff --git a/src/renderer/src/components/settings/CliSection.test.tsx b/src/renderer/src/components/settings/CliSection.test.tsx
index 2c34b299d8b..7db93106fe4 100644
--- a/src/renderer/src/components/settings/CliSection.test.tsx
+++ b/src/renderer/src/components/settings/CliSection.test.tsx
@@ -1,5 +1,8 @@
+// @vitest-environment happy-dom
+
 import { renderToStaticMarkup } from 'react-dom/server'
-import { describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { getDefaultSettings } from '../../../../shared/constants'
 import { CliSection } from './CliSection'
 
@@ -12,6 +15,9 @@ const capturedPanel = vi.hoisted(() => ({
   },
   useInstalledAgentSkill: vi.fn()
 }))
+const toastError = vi.hoisted(() => vi.fn())
+
+vi.mock('sonner', () => ({ toast: { error: toastError, success: vi.fn() } }))
 
 vi.mock('@/hooks/useInstalledAgentSkills', () => ({
   GLOBAL_AGENT_SKILL_SOURCE_KINDS: ['global'],
@@ -25,6 +31,12 @@ capturedPanel.useInstalledAgentSkill.mockReturnValue({
   refresh: vi.fn()
 })
 
+afterEach(() => {
+  cleanup()
+  toastError.mockReset()
+  vi.unstubAllGlobals()
+})
+
 vi.mock('./AgentSkillSetupPanel', () => ({
   AgentSkillSetupPanel: function AgentSkillSetupPanel(props: {
     command: string
@@ -98,4 +110,40 @@ describe('CliSection project runtime defaults', () => {
     expect(getWslInstallStatus).toHaveBeenCalledWith({ distro: 'Ubuntu' })
     expect(getWslInstallStatus).toHaveBeenCalledTimes(2)
   })
+
+  it('renders an inline unknown PATH state without offering a mutation', async () => {
+    const getInstallStatus = vi.fn().mockResolvedValue({
+      platform: 'win32',
+      commandName: 'orca',
+      commandPath: 'C:\\Program Files\\Orca\\resources\\bin\\orca.exe',
+      pathDirectory: 'C:\\Program Files\\Orca\\resources\\bin',
+      pathConfigured: null,
+      launcherPath: 'C:\\Program Files\\Orca\\resources\\bin\\orca.exe',
+      installMethod: 'wrapper',
+      supported: true,
+      state: 'installed',
+      currentTarget: 'C:\\Program Files\\Orca\\resources\\bin\\orca.exe',
+      unsupportedReason: null,
+      detail: 'Orca could not read the Windows user PATH registry value.'
+    })
+    Object.assign(window, {
+      api: {
+        cli: {
+          getInstallStatus,
+          getWslInstallStatus: vi.fn(),
+          install: vi.fn(),
+          remove: vi.fn()
+        },
+        shell: { openPath: vi.fn() }
+      }
+    })
+
+    render(<CliSection currentPlatform="win32" settings={getDefaultSettings('/tmp')} />)
+
+    expect(await screen.findByText(/could not read the Windows user PATH/i)).toBeDefined()
+    const registrationSwitch = screen.getByRole('switch') as HTMLButtonElement
+    expect(registrationSwitch.disabled).toBe(true)
+    expect(registrationSwitch.getAttribute('aria-checked')).toBe('false')
+    expect(toastError).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/renderer/src/components/settings/CliSection.tsx b/src/renderer/src/components/settings/CliSection.tsx
index eae2ce2a76b..5f61d1e8ef3 100644
--- a/src/renderer/src/components/settings/CliSection.tsx
+++ b/src/renderer/src/components/settings/CliSection.tsx
@@ -155,7 +155,8 @@ export function CliSection({
     void refreshStatus()
   }, [refreshStatus])
 
-  const isEnabled = status?.state === 'installed'
+  const pathStatusUnknown = currentPlatform === 'win32' && status?.pathConfigured === null
+  const isEnabled = status?.state === 'installed' && !pathStatusUnknown
   const isSupported = status?.supported ?? false
   const isBrowserManaged = status?.unsupportedReason === 'launch_mode_unavailable'
   const revealLabel = getRevealLabel(currentPlatform)
@@ -251,7 +252,9 @@ export function CliSection({
             <Label>
               {translate('auto.components.settings.CliSection.38edbb5721', 'Shell command')}
             </Label>
-            <p className="text-xs text-muted-foreground">
+            <p
+              className={`text-xs ${pathStatusUnknown ? 'text-amber-600 dark:text-amber-400' : 'text-muted-foreground'}`}
+            >
               {loading
                 ? translate(
                     'auto.components.settings.CliSection.d363e5929b',
@@ -286,11 +289,11 @@ export function CliSection({
               <button
                 role="switch"
                 aria-checked={isEnabled}
-                disabled={loading || !isSupported || busyAction !== null}
+                disabled={loading || !isSupported || pathStatusUnknown || busyAction !== null}
                 onClick={() => setDialogOpen(true)}
                 className={`relative inline-flex h-5 w-9 shrink-0 items-center rounded-full border border-transparent transition-colors ${
                   isEnabled ? 'bg-foreground' : 'bg-muted-foreground/30'
-                } ${loading || !isSupported || busyAction !== null ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'}`}
+                } ${loading || !isSupported || pathStatusUnknown || busyAction !== null ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'}`}
               >
                 <span
                   className={`pointer-events-none block size-3.5 rounded-full bg-background shadow-sm transition-transform ${
@@ -319,7 +322,9 @@ export function CliSection({
           </p>
         ) : null}
 
-        {status?.state === 'installed' && !status.pathConfigured && status.pathDirectory ? (
+        {status?.state === 'installed' &&
+        status.pathConfigured === false &&
+        status.pathDirectory ? (
           <p className="text-xs text-amber-600 dark:text-amber-400">
             {status.pathDirectory}{' '}
             {translate(
diff --git a/src/renderer/src/components/settings/CliSkillRuntimeSetup.tsx b/src/renderer/src/components/settings/CliSkillRuntimeSetup.tsx
index 469bb17acd7..2c5134b2bcf 100644
--- a/src/renderer/src/components/settings/CliSkillRuntimeSetup.tsx
+++ b/src/renderer/src/components/settings/CliSkillRuntimeSetup.tsx
@@ -193,7 +193,17 @@ export async function ensureWslCliAvailableForAgentSkillTerminal(
       )
       return status
     }
-    if (status.state !== 'installed' || !status.pathConfigured) {
+    if (status.pathConfigured === null) {
+      toast.warning(
+        translate(
+          'auto.components.settings.CliSkillRuntimeSetup.windowsPathUnknown',
+          'WSL shell command PATH could not be checked'
+        ),
+        { description: status.detail ?? 'Refresh CLI registration status and try again.' }
+      )
+      return status
+    }
+    if (status.state !== 'installed' || status.pathConfigured === false) {
       await showOrcaCliRegistrationPromptToast()
       const next = await window.api.cli.installWsl(args)
       if (!isOrcaCliAvailableOnPath(next)) {
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index c6bafdd07a6..40f61f74600 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -364,7 +364,8 @@
               "2db0bd7515": "Orca CLI registration is unavailable",
               "8d6eedf97e": "Failed to register the Orca CLI in PATH.",
               "0f116999f1": "Restart your shell or add the Orca CLI directory to PATH before setup.",
-              "15cbedc3e3": "Install the Orca CLI before running agent skill setup."
+              "15cbedc3e3": "Install the Orca CLI before running agent skill setup.",
+              "windowsPathUnknown": "Orca could not check your Windows user PATH"
             }
           }
         }
@@ -5343,7 +5344,8 @@
           "0c9f3cf9da": "Choose where Orca checks and installs global agent skills.",
           "f00d6aa9b5": "WSL is not available on this machine.",
           "7c776ff9d8": "wsl",
-          "fc0fcf72fd": "Register the WSL shell command before skill setup."
+          "fc0fcf72fd": "Register the WSL shell command before skill setup.",
+          "windowsPathUnknown": "WSL shell command PATH could not be checked"
         },
         "CommitMessageAiPane": {
           "841ed9884a": "Used by repositories that have not customized Source Control AI.",
diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json
index 62827c20dec..1565076a578 100644
--- a/src/renderer/src/i18n/locales/es.json
+++ b/src/renderer/src/i18n/locales/es.json
@@ -341,7 +341,8 @@
               "2db0bd7515": "El registro de Orca CLI no está disponible",
               "8d6eedf97e": "No se pudo registrar Orca CLI en PATH.",
               "0f116999f1": "Reinicia tu shell o agrega el directorio de Orca CLI a PATH antes de la configuración.",
-              "15cbedc3e3": "Instala la CLI de Orca antes de configurar skills para agentes."
+              "15cbedc3e3": "Instala la CLI de Orca antes de configurar skills para agentes.",
+              "windowsPathUnknown": "Orca could not check your Windows user PATH"
             }
           }
         }
@@ -5320,7 +5321,8 @@
           "0c9f3cf9da": "Elige dónde Orca comprueba e instala agent skills globales.",
           "f00d6aa9b5": "WSL no está disponible en esta máquina.",
           "7c776ff9d8": "wsl",
-          "fc0fcf72fd": "Registra el comando de shell de WSL antes de configurar el skill."
+          "fc0fcf72fd": "Registra el comando de shell de WSL antes de configurar el skill.",
+          "windowsPathUnknown": "WSL shell command PATH could not be checked"
         },
         "CommitMessageAiPane": {
           "841ed9884a": "Usado por repositorios que no han personalizado Source Control AI.",
diff --git a/src/renderer/src/i18n/locales/ja.json b/src/renderer/src/i18n/locales/ja.json
index d1c9f5e043c..45b3893de81 100644
--- a/src/renderer/src/i18n/locales/ja.json
+++ b/src/renderer/src/i18n/locales/ja.json
@@ -341,7 +341,8 @@
               "2db0bd7515": "Orca CLI 登録は利用できません",
               "8d6eedf97e": "Orca CLI を PATH に登録できませんでした。",
               "0f116999f1": "セットアップ前にシェルを再起動するか、Orca CLI ディレクトリを PATH に追加します。",
-              "15cbedc3e3": "agent スキル セットアップを実行する前に、Orca CLI をインストールします。"
+              "15cbedc3e3": "agent スキル セットアップを実行する前に、Orca CLI をインストールします。",
+              "windowsPathUnknown": "Orca could not check your Windows user PATH"
             }
           }
         }
@@ -5305,7 +5306,8 @@
           "0c9f3cf9da": "Orca がグローバル agent スキルをチェックしてインストールする場所を選択します。",
           "f00d6aa9b5": "このマシンでは WSL を利用できません。",
           "7c776ff9d8": "wsl",
-          "fc0fcf72fd": "スキルセットアップ前に WSL シェルコマンドを登録してください。"
+          "fc0fcf72fd": "スキルセットアップ前に WSL シェルコマンドを登録してください。",
+          "windowsPathUnknown": "WSL shell command PATH could not be checked"
         },
         "CommitMessageAiPane": {
           "841ed9884a": "ソース管理 AI をカスタマイズしていない repos によって使用されます。",
diff --git a/src/renderer/src/i18n/locales/ko.json b/src/renderer/src/i18n/locales/ko.json
index 875dafd5756..106911afaad 100644
--- a/src/renderer/src/i18n/locales/ko.json
+++ b/src/renderer/src/i18n/locales/ko.json
@@ -341,7 +341,8 @@
               "2db0bd7515": "Orca CLI 등록을 사용할 수 없습니다.",
               "8d6eedf97e": "PATH에 Orca CLI를 등록하지 못했습니다.",
               "0f116999f1": "설정하기 전에 셸을 다시 시작하거나 Orca CLI 디렉터리를 PATH에 추가하세요.",
-              "15cbedc3e3": "agent 스킬 설정을 실행하기 전에 Orca CLI를 설치하십시오."
+              "15cbedc3e3": "agent 스킬 설정을 실행하기 전에 Orca CLI를 설치하십시오.",
+              "windowsPathUnknown": "Orca could not check your Windows user PATH"
             }
           }
         }
@@ -5305,7 +5306,8 @@
           "0c9f3cf9da": "Orca가 글로벌 agent 스킬을 확인하고 설치하는 위치를 선택합니다.",
           "f00d6aa9b5": "이 컴퓨터에서는 WSL을 사용할 수 없습니다.",
           "7c776ff9d8": "wsl",
-          "fc0fcf72fd": "스킬 설정 전 WSL 쉘 명령어를 등록하세요."
+          "fc0fcf72fd": "스킬 설정 전 WSL 쉘 명령어를 등록하세요.",
+          "windowsPathUnknown": "WSL shell command PATH could not be checked"
         },
         "CommitMessageAiPane": {
           "841ed9884a": "소스 제어 AI를 사용자 정의하지 않은 리포지토리에서 사용됩니다.",
diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json
index 3716898ceb2..3938f0dad79 100644
--- a/src/renderer/src/i18n/locales/zh.json
+++ b/src/renderer/src/i18n/locales/zh.json
@@ -341,7 +341,8 @@
               "2db0bd7515": "Orca CLI 注册不可用",
               "8d6eedf97e": "无法在 PATH 中注册 Orca CLI。",
               "0f116999f1": "在安装之前重新启动 shell 或将 Orca CLI 目录添加到 PATH。",
-              "15cbedc3e3": "在运行智能体技能设置之前安装 Orca CLI。"
+              "15cbedc3e3": "在运行智能体技能设置之前安装 Orca CLI。",
+              "windowsPathUnknown": "Orca could not check your Windows user PATH"
             }
           }
         }
@@ -5305,7 +5306,8 @@
           "0c9f3cf9da": "选择 Orca 检查和安装全局智能体技能的位置。",
           "f00d6aa9b5": "WSL 在此计算机上不可用。",
           "7c776ff9d8": "wsl",
-          "fc0fcf72fd": "在技​​能设置之前注册 WSL shell 命令。"
+          "fc0fcf72fd": "在技​​能设置之前注册 WSL shell 命令。",
+          "windowsPathUnknown": "WSL shell command PATH could not be checked"
         },
         "CommitMessageAiPane": {
           "841ed9884a": "由未自定义源代码控制 AI 的存储库使用。",
diff --git a/src/renderer/src/lib/agent-skill-cli-prerequisite.test.ts b/src/renderer/src/lib/agent-skill-cli-prerequisite.test.ts
index df0d6fc1b32..ea948d6e8c7 100644
--- a/src/renderer/src/lib/agent-skill-cli-prerequisite.test.ts
+++ b/src/renderer/src/lib/agent-skill-cli-prerequisite.test.ts
@@ -83,6 +83,28 @@ describe('ensureOrcaCliAvailableForAgentSkillTerminal', () => {
     expect(onStatusChange).toHaveBeenNthCalledWith(2, installed)
   })
 
+  it('does not run the CLI installer when the Windows PATH read is unknown', async () => {
+    const initial = cliStatus({
+      platform: 'win32',
+      pathConfigured: null,
+      detail: 'Orca could not read the Windows user PATH registry value.'
+    })
+    const install = vi.fn()
+    vi.stubGlobal('window', {
+      api: { cli: { getInstallStatus: vi.fn().mockResolvedValue(initial), install } }
+    })
+
+    await expect(
+      ensureOrcaCliAvailableForAgentSkillTerminal({ registrationPromptDelayMs: 0 })
+    ).resolves.toBe(initial)
+
+    expect(install).not.toHaveBeenCalled()
+    expect(toast.warning).toHaveBeenCalledWith(
+      expect.stringMatching(/could not check/i),
+      expect.objectContaining({ description: initial.detail })
+    )
+  })
+
   it('lets the registration toast paint before opening the native installer', async () => {
     vi.useFakeTimers()
     const initial = cliStatus({ state: 'stale' })
diff --git a/src/renderer/src/lib/agent-skill-cli-prerequisite.ts b/src/renderer/src/lib/agent-skill-cli-prerequisite.ts
index 06dd6d76bc3..1c731bae1fe 100644
--- a/src/renderer/src/lib/agent-skill-cli-prerequisite.ts
+++ b/src/renderer/src/lib/agent-skill-cli-prerequisite.ts
@@ -15,7 +15,7 @@ export const CLI_PREREQUISITE_REGISTRATION_TOAST_DESCRIPTION =
   'Approve the system prompt so skill setup can use the Orca CLI command.'
 
 export function isOrcaCliAvailableOnPath(status: CliInstallStatus | null | undefined): boolean {
-  return status?.state === 'installed' && status.pathConfigured
+  return status?.state === 'installed' && status.pathConfigured === true
 }
 
 export async function ensureOrcaCliAvailableForAgentSkillTerminal({
@@ -31,7 +31,12 @@ export async function ensureOrcaCliAvailableForAgentSkillTerminal({
       return status
     }
 
-    if (status.state !== 'installed' || !status.pathConfigured) {
+    if (status.pathConfigured === null) {
+      showCliPrerequisiteWarning(status)
+      return status
+    }
+
+    if (status.state !== 'installed' || status.pathConfigured === false) {
       // Why: macOS may immediately show a native authorization prompt, so the
       // user needs app-level context before that OS dialog appears.
       await showOrcaCliRegistrationPromptToast(registrationPromptDelayMs)
@@ -106,7 +111,18 @@ function showCliPrerequisiteWarning(status: CliInstallStatus): void {
     return
   }
 
-  if (!status.pathConfigured) {
+  if (status.pathConfigured === null) {
+    toast.warning(
+      translate(
+        'auto.lib.agent.skill.cli.prerequisite.windowsPathUnknown',
+        'Orca could not check your Windows user PATH'
+      ),
+      { description: status.detail ?? 'Refresh CLI registration status and try again.' }
+    )
+    return
+  }
+
+  if (status.pathConfigured === false) {
     // Why: the skill installer opens a real shell; agents only get the expected
     // Orca affordances when that shell can resolve the Orca CLI command.
     toast.warning(
diff --git a/src/shared/cli-install-types.ts b/src/shared/cli-install-types.ts
index e47bf33237e..3553749b01b 100644
--- a/src/shared/cli-install-types.ts
+++ b/src/shared/cli-install-types.ts
@@ -12,7 +12,8 @@ export type CliInstallStatus = {
   commandName: string
   commandPath: string | null
   pathDirectory: string | null
-  pathConfigured: boolean
+  /** Null means the persisted PATH could not be read, so callers must not offer a mutation. */
+  pathConfigured: boolean | null
   launcherPath: string | null
   installMethod: CliInstallMethod | null
   supported: boolean

From 3a847bfac9da57bd47665ec5fcb447b25217f46a Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Sun, 19 Jul 2026 19:14:15 -0700
Subject: [PATCH 20/54] fix(ssh): clear stamped agent status on disconnect
 (#9484)

* fix(ssh): clear stamped agent status on disconnect

Batch transient cleanup by accepted SSH connection authority and use a monotonic cutoff so reconnect replay wins over delayed clears. Preserve pane launch, resume, acknowledgement, and retention metadata.

Caveat: legacy or renderer-owned rows without an accepted connection stamp are intentionally left to existing pane/PTY teardown; clearing them by host would be ambiguous.

* docs(ssh): explain stale status watermark

* fix(ssh): preserve status ordering after restart
---
 src/main/agent-hooks/server.test.ts           | 149 +++++++++++++++++-
 src/main/agent-hooks/server.ts                |  99 ++++++++++--
 src/main/index.ts                             |   4 +-
 ...ay-session-agent-hooks.integration.test.ts |  29 ++++
 src/main/ssh/ssh-relay-session.ts             |   4 +
 src/preload/api-types.ts                      |   5 +-
 src/preload/index.ts                          |   5 +-
 src/renderer/src/hooks/useIpcEvents.test.ts   | 137 +++++++++++++++-
 src/renderer/src/hooks/useIpcEvents.ts        |  71 +++++++--
 .../agent-status-ssh-connection-clear.test.ts |  97 ++++++++++++
 src/renderer/src/store/slices/agent-status.ts |  48 +++++-
 src/shared/agent-status-types.ts              |  11 ++
 12 files changed, 624 insertions(+), 35 deletions(-)
 create mode 100644 src/renderer/src/store/slices/agent-status-ssh-connection-clear.test.ts

diff --git a/src/main/agent-hooks/server.test.ts b/src/main/agent-hooks/server.test.ts
index b666c9329bb..f1aba1cb09f 100644
--- a/src/main/agent-hooks/server.test.ts
+++ b/src/main/agent-hooks/server.test.ts
@@ -1425,7 +1425,92 @@ describe('AgentHookServer listener replay', () => {
     server.clearPaneState(PANE)
 
     expect(listener).toHaveBeenCalledTimes(1)
-    expect(listener).toHaveBeenCalledWith(PANE)
+    expect(listener).toHaveBeenCalledWith({ paneKey: PANE })
+  })
+
+  it('batches connection cleanup and retains sibling and local statuses', () => {
+    const server = new AgentHookServer()
+    const paneKeyAt = (prefix: string, index: number): string =>
+      makePaneKey(
+        `${prefix}-tab-${index}`,
+        `00000000-0000-4000-8000-${(index + 1).toString(16).padStart(12, '0')}`
+      )
+    const targetPaneKeys = Array.from({ length: 100 }, (_, index) => paneKeyAt('target', index))
+    const siblingPaneKeys = Array.from({ length: 100 }, (_, index) =>
+      paneKeyAt('sibling', index + 100)
+    )
+    const unstampedPaneKey = paneKeyAt('legacy', 250)
+    const statusListener = vi.fn()
+    const clearListener = vi.fn()
+    const internals = server as unknown as AgentHookServerCacheInternals
+    const persistSpy = vi.spyOn(internals, 'scheduleStatusPersist')
+    server.subscribeStatusChanges(statusListener)
+    server.setPaneStatusClearListener(clearListener)
+    for (const paneKey of targetPaneKeys) {
+      server.ingestRemote({ paneKey, payload: { state: 'working', agentType: 'claude' } }, 'ssh-a')
+    }
+    for (const paneKey of siblingPaneKeys) {
+      server.ingestRemote({ paneKey, payload: { state: 'working', agentType: 'claude' } }, 'ssh-b')
+    }
+    server.ingestTerminalStatus({
+      paneKey: unstampedPaneKey,
+      payload: { state: 'working', prompt: '', agentType: 'codex' }
+    })
+    statusListener.mockClear()
+    persistSpy.mockClear()
+
+    server.clearStatusEntriesForConnection('ssh-a')
+
+    expect(statusListener).toHaveBeenCalledOnce()
+    expect(persistSpy).toHaveBeenCalledOnce()
+    expect(clearListener).toHaveBeenCalledOnce()
+    expect(clearListener).toHaveBeenCalledWith({
+      transient: true,
+      connectionId: 'ssh-a',
+      clearedAt: expect.any(Number)
+    })
+    expect(server.getStatusSnapshot().map((entry) => entry.paneKey)).toEqual([
+      ...siblingPaneKeys,
+      unstampedPaneKey
+    ])
+  })
+
+  it('emits a connection cutoff after a pane-key collision and orders replay after it', () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(1_700_000_000_000)
+    const server = new AgentHookServer()
+    const clearListener = vi.fn()
+    server.setPaneStatusClearListener(clearListener)
+    server.ingestRemote(
+      { paneKey: PANE, payload: { state: 'working', agentType: 'claude' } },
+      'ssh-a'
+    )
+    server.ingestRemote(
+      { paneKey: PANE, payload: { state: 'working', agentType: 'codex' } },
+      'ssh-b'
+    )
+
+    server.clearStatusEntriesForConnection('ssh-a')
+    const clear = clearListener.mock.calls[0]?.[0] as {
+      transient: true
+      connectionId: string
+      clearedAt: number
+    }
+    server.ingestRemote(
+      { paneKey: GOOD_PANE, payload: { state: 'working', agentType: 'claude' }, isReplay: true },
+      'ssh-a'
+    )
+
+    expect(clear).toMatchObject({ transient: true, connectionId: 'ssh-a' })
+    expect(server.getStatusSnapshot()).toEqual([
+      expect.objectContaining({ paneKey: PANE, connectionId: 'ssh-b' }),
+      expect.objectContaining({
+        paneKey: GOOD_PANE,
+        connectionId: 'ssh-a',
+        receivedAt: clear.clearedAt + 1
+      })
+    ])
+    vi.useRealTimers()
   })
 
   it('drops cached statuses and pane-scoped listener caches under one tab prefix', () => {
@@ -6111,6 +6196,68 @@ describe('Last-status persistence', () => {
     }
   })
 
+  it('keeps SSH status ordering monotonic across hydration and clock rollback', async () => {
+    const now = 1_700_000_000_000
+    vi.spyOn(Date, 'now').mockReturnValue(now)
+    mkdirSync(join(userDataPath, 'agent-hooks'), { recursive: true })
+    const receivedAt = now + 1_000
+    writeFileSync(
+      lastStatusPath(),
+      JSON.stringify({
+        version: 2,
+        entries: {
+          [PANE]: {
+            paneKey: PANE,
+            tabId: 'tab-1',
+            worktreeId: 'wt-1',
+            connectionId: 'ssh-a',
+            receivedAt,
+            stateStartedAt: receivedAt,
+            payload: { state: 'working', prompt: 'before restart', agentType: 'claude' }
+          }
+        }
+      }),
+      'utf8'
+    )
+
+    const server = new AgentHookServer()
+    await server.start({ env: 'production', userDataPath })
+    try {
+      const clearListener = vi.fn()
+      server.setPaneStatusClearListener(clearListener)
+      server.ingestRemote(
+        { paneKey: PANE, payload: { state: 'working', agentType: 'codex' } },
+        'ssh-a'
+      )
+
+      expect(server.getStatusSnapshot()[0]?.receivedAt).toBe(receivedAt + 1)
+      server.clearStatusEntriesForConnection('ssh-a')
+      const clearedAt = receivedAt + 2
+      expect(clearListener).toHaveBeenCalledWith({
+        transient: true,
+        connectionId: 'ssh-a',
+        clearedAt
+      })
+      server.ingestRemote(
+        {
+          paneKey: GOOD_PANE,
+          isReplay: true,
+          payload: { state: 'working', agentType: 'claude' }
+        },
+        'ssh-a'
+      )
+      expect(server.getStatusSnapshot()).toEqual([
+        expect.objectContaining({
+          paneKey: GOOD_PANE,
+          connectionId: 'ssh-a',
+          receivedAt: clearedAt + 1
+        })
+      ])
+    } finally {
+      server.stop()
+    }
+  })
+
   it('drops persisted idle Claude child rows from hydration replay', async () => {
     mkdirSync(join(userDataPath, 'agent-hooks'), { recursive: true })
     const receivedAt = recentTs()
diff --git a/src/main/agent-hooks/server.ts b/src/main/agent-hooks/server.ts
index e810a45f3d4..4c5d4c80cc1 100644
--- a/src/main/agent-hooks/server.ts
+++ b/src/main/agent-hooks/server.ts
@@ -44,6 +44,7 @@ import {
 import type { AgentHookSource } from '../../shared/agent-hook-relay'
 import {
   AGENT_STATUS_STALE_AFTER_MS,
+  type AgentStatusClearIpcPayload,
   type AgentStatusIpcPayload,
   type AgentType,
   type AgentStatusState,
@@ -93,7 +94,7 @@ export type AgentHookStatusChangeEntry = {
 }
 
 type StatusChangeListener = (statuses: AgentHookStatusChangeEntry[]) => void
-type PaneStatusClearListener = (paneKey: string) => void
+type PaneStatusClearListener = (clear: AgentStatusClearIpcPayload) => void
 type PaneKeyAliasPersistenceListener = (entries: LegacyPaneKeyAliasEntry[]) => void
 type PaneKeyAliasEntry = {
   stablePaneKey: string
@@ -528,6 +529,7 @@ export class AgentHookServer {
   private promptSentHashSalt = randomBytes(16).toString('hex')
   private closedAgentStatusTabIds = new Set<string>()
   private closedAgentStatusPaneKeys = new Set<string>()
+  private connectionTimestampWatermarkById = new Map<string, number>()
   // Why: identity check — skip writes when the JSON-stringified contents
   // exactly match the last successful disk write. Cheap protection against
   // re-firing trailing timers when nothing changed.
@@ -896,7 +898,15 @@ export class AgentHookServer {
     const previous = this.state.lastStatusByPaneKey.get(payload.paneKey) as
       | EnrichedAgentHookEventPayload
       | undefined
-    const now = Date.now()
+    const connectionClearWatermark = payload.connectionId
+      ? this.connectionTimestampWatermarkById.get(payload.connectionId)
+      : undefined
+    // Why: Date.now() can repeat across disconnect and reconnect. A remote
+    // replay must sort strictly after its connection's transient clear.
+    const now = Math.max(Date.now(), (connectionClearWatermark ?? -1) + 1)
+    if (payload.connectionId) {
+      this.connectionTimestampWatermarkById.set(payload.connectionId, now)
+    }
     if (payload.providerSessionOnly) {
       // Why: Pi session_start must replace stale turn state and survive snapshot
       // replay, but it must not emit prompt telemetry or a fabricated status.
@@ -1305,7 +1315,7 @@ export class AgentHookServer {
       this.scheduleStatusPersist()
       this.notifyStatusChangeListeners()
       for (const paneKey of clearedStatusPaneKeys) {
-        this.onPaneStatusCleared?.(paneKey)
+        this.onPaneStatusCleared?.({ paneKey })
       }
     }
   }
@@ -1677,6 +1687,7 @@ export class AgentHookServer {
     this.promptSentDedupeByPaneKey.clear()
     this.closedAgentStatusTabIds.clear()
     this.closedAgentStatusPaneKeys.clear()
+    this.connectionTimestampWatermarkById.clear()
     this.legacyPaneKeyAliases.clear()
     clearAllListenerCaches(this.state)
     this.notifyStatusChangeListeners()
@@ -1690,21 +1701,69 @@ export class AgentHookServer {
    *  lands. clearPaneState (which wipes all three caches) is the right shape
    *  only for PTY-teardown. */
   dropStatusEntry(paneKey: string): void {
-    const resolvedPaneKey = this.resolvePaneKeyAlias(paneKey)
-    if (!this.state.lastStatusByPaneKey.has(resolvedPaneKey)) {
+    if (!this.deleteStatusEntry(paneKey)) {
       return
     }
-    const existing = this.state.lastStatusByPaneKey.get(resolvedPaneKey)
-    this.state.lastStatusByPaneKey.delete(resolvedPaneKey)
-    this.clearAssistantMessageRetry(resolvedPaneKey)
-    this.runtimeObservedStatusPaneKeys.delete(resolvedPaneKey)
-    if (existing?.payload.state === 'done') {
-      this.promptSentDedupeByPaneKey.delete(resolvedPaneKey)
-    }
     this.scheduleStatusPersist()
     this.notifyStatusChangeListeners()
   }
 
+  /** Clear statuses proven to belong to one lost SSH transport. */
+  clearStatusEntriesForConnection(connectionId: string): void {
+    const normalizedConnectionId = connectionId.trim()
+    if (normalizedConnectionId.length === 0) {
+      return
+    }
+    const clearedAt = Math.max(
+      Date.now(),
+      (this.connectionTimestampWatermarkById.get(normalizedConnectionId) ?? -1) + 1
+    )
+    this.connectionTimestampWatermarkById.set(normalizedConnectionId, clearedAt)
+    let statusChanged = false
+    for (const [paneKey, rawEntry] of this.state.lastStatusByPaneKey) {
+      const entry = rawEntry as EnrichedAgentHookEventPayload
+      // Why: legacy/unstamped rows cannot be safely attributed to one host.
+      // Leave them for normal pane teardown instead of risking cross-host loss.
+      if (entry.connectionId !== normalizedConnectionId) {
+        continue
+      }
+      if (this.deleteStatusEntry(paneKey)) {
+        statusChanged = true
+      }
+    }
+    if (statusChanged) {
+      // Why: one disconnect can own many panes; persist and notify subscribers
+      // once so cleanup cost does not fan out with the pane count.
+      this.scheduleStatusPersist()
+      this.notifyStatusChangeListeners()
+    }
+    // Why: another host can overwrite the same pane key in main's cache while
+    // renderer still shows this connection's older row. Always send the
+    // connection cutoff, even when no current main entry matched.
+    this.onPaneStatusCleared?.({
+      transient: true,
+      connectionId: normalizedConnectionId,
+      clearedAt
+    })
+  }
+
+  private deleteStatusEntry(paneKey: string): EnrichedAgentHookEventPayload | null {
+    const resolvedPaneKey = this.resolvePaneKeyAlias(paneKey)
+    const existing = this.state.lastStatusByPaneKey.get(resolvedPaneKey) as
+      | EnrichedAgentHookEventPayload
+      | undefined
+    if (!existing) {
+      return null
+    }
+    this.state.lastStatusByPaneKey.delete(resolvedPaneKey)
+    this.clearAssistantMessageRetry(resolvedPaneKey)
+    this.runtimeObservedStatusPaneKeys.delete(resolvedPaneKey)
+    if (existing.payload.state === 'done') {
+      this.promptSentDedupeByPaneKey.delete(resolvedPaneKey)
+    }
+    return existing
+  }
+
   dropStatusEntriesByTabPrefix(tabId: string): void {
     this.markTabClosedForAgentStatus(tabId)
     const paneKeysToClear = new Set<string>()
@@ -1802,7 +1861,7 @@ export class AgentHookServer {
       this.runtimeObservedStatusPaneKeys.delete(resolvedPaneKey)
       this.scheduleStatusPersist()
       this.notifyStatusChangeListeners()
-      this.onPaneStatusCleared?.(resolvedPaneKey)
+      this.onPaneStatusCleared?.({ paneKey: resolvedPaneKey })
     }
   }
 
@@ -1917,6 +1976,15 @@ export class AgentHookServer {
           entry.payload = hydratedPayload
         }
         this.state.lastStatusByPaneKey.set(resolvedPaneKey, entry)
+        if (entry.connectionId) {
+          // Why: a restarted process can observe an earlier wall clock; seed
+          // transport ordering so new events and clears stay after disk state.
+          const previousWatermark = this.connectionTimestampWatermarkById.get(entry.connectionId)
+          this.connectionTimestampWatermarkById.set(
+            entry.connectionId,
+            Math.max(previousWatermark ?? -1, entry.receivedAt)
+          )
+        }
         // Why: preserve only working children across restart. Live activity
         // confirms them; a later complete inventory may reap stale seeds.
         if (entry.payload.subagents) {
@@ -2043,6 +2111,10 @@ export class AgentHookServer {
   _resetPromptSentDedupeForTests(): void {
     this.promptSentDedupeByPaneKey.clear()
   }
+
+  _resetConnectionTimestampWatermarksForTests(): void {
+    this.connectionTimestampWatermarkById.clear()
+  }
 }
 
 export const agentHookServer = new AgentHookServer()
@@ -2061,5 +2133,6 @@ export const _internals = {
   resetCachesForTests: (): void => {
     clearAllListenerCaches(agentHookServer._getStateForTests())
     agentHookServer._resetPromptSentDedupeForTests()
+    agentHookServer._resetConnectionTimestampWatermarksForTests()
   }
 }
diff --git a/src/main/index.ts b/src/main/index.ts
index 1b289f4102d..9278eb043ec 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1210,11 +1210,11 @@ function openMainWindow(): BrowserWindow {
       }
     }
   )
-  agentHookServer.setPaneStatusClearListener((paneKey) => {
+  agentHookServer.setPaneStatusClearListener((clear) => {
     if (mainWindow?.isDestroyed()) {
       return
     }
-    mainWindow?.webContents.send('agentStatus:clear', { paneKey })
+    mainWindow?.webContents.send('agentStatus:clear', clear)
   })
   setMigrationUnsupportedPtyListener((event) => {
     if (mainWindow?.isDestroyed()) {
diff --git a/src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts b/src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts
index 91ee554dff4..d6c98bf03a0 100644
--- a/src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts
+++ b/src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts
@@ -210,6 +210,7 @@ describe('SshRelaySession agent hooks over a fake relay transport', () => {
     session = null
     relay = null
     agentHookServer.setListener(null)
+    agentHookServer.setPaneStatusClearListener(null)
     agentHookInternals.resetCachesForTests()
     warnSpy.mockRestore()
     if (previousRemoteHooksFlag === undefined) {
@@ -272,6 +273,34 @@ describe('SshRelaySession agent hooks over a fake relay transport', () => {
     })
   })
 
+  it('clears stamped status on reconnect loss but not final shutdown', async () => {
+    const initialRelay = createFakeRelay()
+    relay = createFakeRelay()
+    vi.mocked(deployAndLaunchRelay)
+      .mockResolvedValueOnce({ transport: initialRelay.transport, platform: 'linux-x64' })
+      .mockResolvedValueOnce({ transport: relay.transport, platform: 'linux-x64' })
+    const clearListener = vi.fn()
+    agentHookServer.setPaneStatusClearListener(clearListener)
+    session = createSession('conn-clear')
+    await session.establish({} as SshConnection)
+    initialRelay.notifyAgentHook(makeEnvelope())
+    await vi.waitFor(() => expect(agentHookServer.getStatusSnapshot()).toHaveLength(1))
+
+    await session.reconnect({} as SshConnection)
+    initialRelay.dispose()
+
+    expect(agentHookServer.getStatusSnapshot()).toEqual([])
+    expect(clearListener).toHaveBeenCalledOnce()
+    expect(clearListener).toHaveBeenCalledWith({
+      transient: true,
+      connectionId: 'conn-clear',
+      clearedAt: expect.any(Number)
+    })
+    session.dispose()
+    session = null
+    expect(clearListener).toHaveBeenCalledOnce()
+  })
+
   it('asks the fake relay for cached hook replay after the session wires its listener', async () => {
     relay = createFakeRelay()
     relay.replayEnvelopes.push(
diff --git a/src/main/ssh/ssh-relay-session.ts b/src/main/ssh/ssh-relay-session.ts
index 11f7f5f931f..969878c1220 100644
--- a/src/main/ssh/ssh-relay-session.ts
+++ b/src/main/ssh/ssh-relay-session.ts
@@ -1020,6 +1020,10 @@ export class SshRelaySession {
 
     if (reason === 'shutdown') {
       clearPtyOwnershipForConnection(this.targetId)
+    } else {
+      // Why: handlers are detached above, so no late event can recreate a
+      // stamped status between this clear and reconnect replay.
+      agentHookServer.clearStatusEntriesForConnection(this.targetId)
     }
 
     const ptyProvider = getSshPtyProvider(this.targetId)
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index f25cf0f56df..3911de36f9d 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -304,6 +304,7 @@ import type { CliInstallStatus } from '../shared/cli-install-types'
 import type { E2EConfig } from '../shared/e2e-config'
 import type { AgentHookInstallStatus } from '../shared/agent-hook-types'
 import type {
+  AgentStatusClearIpcPayload,
   AgentStatusIpcPayload,
   MigrationUnsupportedPtyEntry
 } from '../shared/agent-status-types'
@@ -3211,8 +3212,8 @@ export type PreloadApi = {
   agentStatus: {
     /** Listen for agent status updates forwarded from native hook receivers. */
     onSet: (callback: (data: AgentStatusIpcPayload) => void) => () => void
-    /** Listen for main-process pane teardown that evicted a cached hook status. */
-    onClear: (callback: (data: { paneKey: string }) => void) => () => void
+    /** Listen for main-process cleanup that evicted cached hook status. */
+    onClear: (callback: (data: AgentStatusClearIpcPayload) => void) => () => void
     /** Return the current main-process hook cache after renderer hydration. */
     getSnapshot: () => Promise<AgentStatusIpcPayload[]>
     inferInterrupt: (request: AgentInterruptInferenceRequest) => Promise<boolean>
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 237090a4402..dc8023b1e85 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -142,6 +142,7 @@ import type {
   EnrichedDetectedPort
 } from '../shared/ssh-types'
 import type {
+  AgentStatusClearIpcPayload,
   AgentStatusIpcPayload,
   MigrationUnsupportedPtyEntry
 } from '../shared/agent-status-types'
@@ -4401,8 +4402,8 @@ const api = {
       ipcRenderer.on('agentStatus:set', listener)
       return () => ipcRenderer.removeListener('agentStatus:set', listener)
     },
-    onClear: (callback: (data: { paneKey: string }) => void): (() => void) => {
-      const listener = (_event: Electron.IpcRendererEvent, data: { paneKey: string }) =>
+    onClear: (callback: (data: AgentStatusClearIpcPayload) => void): (() => void) => {
+      const listener = (_event: Electron.IpcRendererEvent, data: AgentStatusClearIpcPayload) =>
         callback(data)
       ipcRenderer.on('agentStatus:clear', listener)
       return () => ipcRenderer.removeListener('agentStatus:clear', listener)
diff --git a/src/renderer/src/hooks/useIpcEvents.test.ts b/src/renderer/src/hooks/useIpcEvents.test.ts
index 16f5deaddd8..40e59841751 100644
--- a/src/renderer/src/hooks/useIpcEvents.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents.test.ts
@@ -12,6 +12,7 @@ import {
   resolveZoomTarget
 } from './useIpcEvents'
 import type { SleepingAgentLaunchConfig } from '../../../shared/agent-session-resume'
+import type { AgentStatusClearIpcPayload } from '../../../shared/agent-status-types'
 import type { TuiAgent } from '../../../shared/types'
 import { makePaneKey } from '../../../shared/stable-pane-id'
 import { YOLO_TUI_AGENT_ARGS } from '../../../shared/tui-agent-permissions'
@@ -4624,6 +4625,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
       runtimePaneTitlesByTabId: {},
       terminalLayoutsByTabId: {},
       agentStatusByPaneKey: {},
+      clearTransientAgentStatuses: vi.fn(),
       getAgentLaunchConfigForStatusMetadata: vi.fn(() => undefined),
       recentlyClosedAgentStatusTabIds: {},
       repos: [],
@@ -4638,7 +4640,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
 
   function buildWindowApi(args: {
     onSet: (cb: (data: AgentStatusSetData) => void) => () => void
-    onClear?: (cb: (data: { paneKey: string }) => void) => () => void
+    onClear?: (cb: (data: AgentStatusClearIpcPayload) => void) => () => void
     getSnapshot?: () => Promise<AgentStatusSetData[]>
     drop?: (paneKey: string) => void
     remoteWorkspace?: Record<string, unknown>
@@ -5715,7 +5717,9 @@ describe('useIpcEvents agent status snapshot integration', () => {
     const onSetListenerRef: { current: ((data: AgentStatusSetData) => void) | null } = {
       current: null
     }
-    const onClearListenerRef: { current: ((data: { paneKey: string }) => void) | null } = {
+    const onClearListenerRef: {
+      current: ((data: AgentStatusClearIpcPayload) => void) | null
+    } = {
       current: null
     }
 
@@ -5805,9 +5809,136 @@ describe('useIpcEvents agent status snapshot integration', () => {
     expect(removeAgentStatus).toHaveBeenCalledWith(FUTURE_PANE_KEY)
   })
 
+  it('blocks cleared snapshots across remount and accepts newer reconnect replay', async () => {
+    let resolveOldSnapshot!: (entries: AgentStatusSetData[]) => void
+    let resolveCurrentSnapshot!: (entries: AgentStatusSetData[]) => void
+    const oldSnapshot = new Promise<AgentStatusSetData[]>((resolve) => {
+      resolveOldSnapshot = resolve
+    })
+    const currentSnapshot = new Promise<AgentStatusSetData[]>((resolve) => {
+      resolveCurrentSnapshot = resolve
+    })
+    const effectCleanups: (() => void)[] = []
+    const setAgentStatus = vi.fn()
+    const clearTransientAgentStatuses = vi.fn()
+    const onSetListenerRef: { current: ((data: AgentStatusSetData) => void) | null } = {
+      current: null
+    }
+    const onClearListenerRef: {
+      current: ((data: AgentStatusClearIpcPayload) => void) | null
+    } = { current: null }
+    const storeState: StoreLike = buildStoreState({
+      setAgentStatus,
+      clearTransientAgentStatuses,
+      workspaceSessionReady: true,
+      settings: { terminalFontSize: 13, notifications: { enabled: false } },
+      repos: [{ id: 'repo-1', connectionId: 'ssh-a' }],
+      worktreesByRepo: { 'repo-1': [{ id: 'wt-1', repoId: 'repo-1' }] },
+      tabsByWorktree: {
+        'wt-1': [{ id: 'tab-future', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Remote agent' }]
+      },
+      terminalLayoutsByTabId: {
+        'tab-future': { root: { type: 'leaf', leafId: FUTURE_LEAF_ID } }
+      }
+    })
+
+    vi.doMock('react', async () => {
+      const actual = await vi.importActual<typeof ReactModule>('react')
+      return {
+        ...actual,
+        useEffect: (effect: () => void | (() => void)) => {
+          const cleanup = effect()
+          effectCleanups.push(typeof cleanup === 'function' ? cleanup : () => {})
+        }
+      }
+    })
+    vi.doMock('../store', () => ({
+      useAppStore: {
+        subscribe: vi.fn(() => () => {}),
+        getState: () => storeState
+      }
+    }))
+    stubAuxiliaryModules()
+    vi.stubGlobal(
+      'window',
+      buildWindowApi({
+        onSet: (callback) => {
+          onSetListenerRef.current = callback
+          return () => {}
+        },
+        onClear: (callback) => {
+          onClearListenerRef.current = callback
+          return () => {}
+        },
+        getSnapshot: vi.fn().mockReturnValueOnce(oldSnapshot).mockReturnValueOnce(currentSnapshot)
+      })
+    )
+
+    const { useIpcEvents } = await import('./useIpcEvents')
+    useIpcEvents()
+    await Promise.resolve()
+    effectCleanups[0]?.()
+    useIpcEvents()
+    await Promise.resolve()
+    if (!onSetListenerRef.current || !onClearListenerRef.current) {
+      throw new Error('Expected agent status listeners to be registered')
+    }
+
+    expect(() =>
+      onClearListenerRef.current?.(null as unknown as AgentStatusClearIpcPayload)
+    ).not.toThrow()
+    expect(clearTransientAgentStatuses).not.toHaveBeenCalled()
+
+    onClearListenerRef.current({
+      transient: true,
+      connectionId: 'ssh-a',
+      clearedAt: 100
+    })
+    const staleEntry: AgentStatusSetData = {
+      paneKey: FUTURE_PANE_KEY,
+      state: 'working',
+      prompt: 'stale snapshot',
+      agentType: 'codex',
+      worktreeId: 'wt-1',
+      connectionId: 'ssh-a',
+      receivedAt: 100,
+      stateStartedAt: 90
+    }
+    resolveOldSnapshot([staleEntry])
+    resolveCurrentSnapshot([staleEntry])
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(clearTransientAgentStatuses).toHaveBeenCalledWith('ssh-a', 100)
+    expect(setAgentStatus).not.toHaveBeenCalled()
+
+    onSetListenerRef.current({
+      paneKey: FUTURE_PANE_KEY,
+      state: 'working',
+      prompt: 'replayed',
+      agentType: 'codex',
+      worktreeId: 'wt-1',
+      connectionId: 'ssh-a',
+      receivedAt: 101,
+      stateStartedAt: 101
+    })
+
+    expect(setAgentStatus).toHaveBeenCalledOnce()
+    expect(setAgentStatus).toHaveBeenCalledWith(
+      FUTURE_PANE_KEY,
+      expect.objectContaining({ prompt: 'replayed' }),
+      'Remote agent',
+      { updatedAt: 101, stateStartedAt: 101 },
+      expect.objectContaining({ worktreeId: 'wt-1', connectionId: 'ssh-a' }),
+      undefined
+    )
+  })
+
   it('keeps a completed worktree-attributed row when main reports pane teardown', async () => {
     const removeAgentStatus = vi.fn()
-    const onClearListenerRef: { current: ((data: { paneKey: string }) => void) | null } = {
+    const onClearListenerRef: {
+      current: ((data: AgentStatusClearIpcPayload) => void) | null
+    } = {
       current: null
     }
 
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index cadc9d48a77..3b83dc4603d 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -57,6 +57,7 @@ import {
 } from '@/lib/simulator-launch-coordination'
 import {
   normalizeAgentStatusPayload,
+  type AgentStatusClearIpcPayload,
   type AgentStatusIpcPayload,
   type ParsedAgentStatusPayload
 } from '../../../shared/agent-status-types'
@@ -849,6 +850,8 @@ export function useIpcEvents(): void {
     }
     type AgentStatusApplyResult = 'applied' | 'pending' | 'dropped'
     const pendingAgentStatusEvents: PendingAgentStatusEvent[] = []
+    const transientClearWatermarkByConnectionId = new Map<string, number>()
+    let agentStatusEffectDisposed = false
     let pendingAgentStatusRetryTimer: ReturnType<typeof setTimeout> | null = null
     // Why: applyAgentStatus -> store.setAgentStatus notifies the store
     // subscriber synchronously, which re-enters flushPendingAgentStatuses while
@@ -3147,6 +3150,15 @@ export function useIpcEvents(): void {
       const ownershipConnectionId = isWslHookRelayConnectionId(data.connectionId)
         ? null
         : data.connectionId
+      const transientClearWatermark =
+        typeof data.connectionId === 'string'
+          ? transientClearWatermarkByConnectionId.get(data.connectionId)
+          : undefined
+      // Why: delayed snapshots and queued relay events must not resurrect a
+      // status cleared by a newer disconnect from the same connection.
+      if (transientClearWatermark !== undefined && data.receivedAt <= transientClearWatermark) {
+        return 'dropped'
+      }
       const canAcceptPendingRemoteOwnership =
         ownershipConnectionId !== undefined &&
         ownershipConnectionId !== null &&
@@ -3242,7 +3254,8 @@ export function useIpcEvents(): void {
         {
           tabId: ownerTabId,
           worktreeId: statusWorktreeId,
-          terminalHandle: data.terminalHandle
+          terminalHandle: data.terminalHandle,
+          ...(ownershipConnectionId !== undefined ? { connectionId: ownershipConnectionId } : {})
         },
         data.providerSession || data.launchToken
           ? {
@@ -3288,7 +3301,7 @@ export function useIpcEvents(): void {
       const requestId = ++snapshotRequestId
       void getSnapshot()
         .then((entries) => {
-          if (requestId !== snapshotRequestId) {
+          if (agentStatusEffectDisposed || requestId !== snapshotRequestId) {
             return
           }
           const current = useAppStore.getState()
@@ -3304,6 +3317,9 @@ export function useIpcEvents(): void {
             return
           }
           void getMigrationUnsupportedSnapshot().then((unsupportedEntries) => {
+            if (agentStatusEffectDisposed || requestId !== snapshotRequestId) {
+              return
+            }
             const unsupportedStore = useAppStore.getState()
             if (!unsupportedStore.workspaceSessionReady) {
               return
@@ -3332,16 +3348,45 @@ export function useIpcEvents(): void {
         applyAgentStatus(data)
       })
     )
-    const unsubscribeAgentStatusClear = window.api.agentStatus.onClear?.((data) => {
-      if (typeof data?.paneKey !== 'string') {
-        return
+    const unsubscribeAgentStatusClear = window.api.agentStatus.onClear?.(
+      (data: AgentStatusClearIpcPayload) => {
+        if (typeof data !== 'object' || data === null) {
+          return
+        }
+        if ('transient' in data && data.transient === true) {
+          if (
+            typeof data.connectionId !== 'string' ||
+            data.connectionId.length === 0 ||
+            !Number.isFinite(data.clearedAt)
+          ) {
+            return
+          }
+          const previousWatermark =
+            transientClearWatermarkByConnectionId.get(data.connectionId) ?? -1
+          const effectiveWatermark = Math.max(previousWatermark, data.clearedAt)
+          transientClearWatermarkByConnectionId.set(data.connectionId, effectiveWatermark)
+          for (let index = pendingAgentStatusEvents.length - 1; index >= 0; index -= 1) {
+            const pending = pendingAgentStatusEvents[index].data
+            if (
+              pending.connectionId === data.connectionId &&
+              pending.receivedAt <= effectiveWatermark
+            ) {
+              pendingAgentStatusEvents.splice(index, 1)
+            }
+          }
+          useAppStore.getState().clearTransientAgentStatuses(data.connectionId, effectiveWatermark)
+          return
+        }
+        if (!('paneKey' in data) || typeof data.paneKey !== 'string') {
+          return
+        }
+        const store = useAppStore.getState()
+        if (store.agentStatusByPaneKey[data.paneKey]?.state === 'done') {
+          return
+        }
+        store.removeAgentStatus(data.paneKey)
       }
-      const store = useAppStore.getState()
-      if (store.agentStatusByPaneKey[data.paneKey]?.state === 'done') {
-        return
-      }
-      store.removeAgentStatus(data.paneKey)
-    })
+    )
     if (unsubscribeAgentStatusClear) {
       unsubs.push(unsubscribeAgentStatusClear)
     }
@@ -3502,6 +3547,10 @@ export function useIpcEvents(): void {
     }
 
     return () => {
+      // Why: React remount can leave an older snapshot promise in flight. It
+      // must not write through after the replacement effect processes a clear.
+      agentStatusEffectDisposed = true
+      snapshotRequestId += 1
       if (pendingAgentStatusRetryTimer !== null) {
         globalThis.clearTimeout(pendingAgentStatusRetryTimer)
       }
diff --git a/src/renderer/src/store/slices/agent-status-ssh-connection-clear.test.ts b/src/renderer/src/store/slices/agent-status-ssh-connection-clear.test.ts
new file mode 100644
index 00000000000..774264c2c37
--- /dev/null
+++ b/src/renderer/src/store/slices/agent-status-ssh-connection-clear.test.ts
@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { AppState } from '../types'
+import { createTestStore } from './store-test-helpers'
+
+describe('agent status cleanup for a lost SSH connection', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('clears one connection in one update while preserving newer and unstamped rows', () => {
+    vi.useFakeTimers()
+    const store = createTestStore()
+    const oldA = 'tab-a:11111111-1111-4111-8111-111111111111'
+    const secondA = 'tab-a2:22222222-2222-4222-8222-222222222222'
+    const newerA = 'tab-new:33333333-3333-4333-8333-333333333333'
+    const siblingB = 'tab-b:44444444-4444-4444-8444-444444444444'
+    const unstamped = 'tab-legacy:55555555-5555-4555-8555-555555555555'
+    for (const [paneKey, updatedAt, connectionId] of [
+      [oldA, 10, 'ssh-a'],
+      [secondA, 20, 'ssh-a'],
+      [newerA, 31, 'ssh-a'],
+      [siblingB, 15, 'ssh-b']
+    ] as const) {
+      store
+        .getState()
+        .setAgentStatus(
+          paneKey,
+          { state: 'working', prompt: paneKey, agentType: 'codex' },
+          undefined,
+          { updatedAt },
+          { connectionId }
+        )
+    }
+    store
+      .getState()
+      .setAgentStatus(
+        unstamped,
+        { state: 'working', prompt: 'legacy', agentType: 'claude' },
+        undefined,
+        { updatedAt: 5 }
+      )
+    store.setState({
+      agentLaunchConfigByPaneKey: {
+        [oldA]: {
+          launchConfig: { agentCommand: 'codex', agentArgs: '--full-auto', agentEnv: {} },
+          registeredAt: 1,
+          identity: {}
+        }
+      },
+      acknowledgedAgentsByPaneKey: { [oldA]: 2 },
+      retentionSuppressedPaneKeys: { [oldA]: true }
+    } as Partial<AppState>)
+    const subscriber = vi.fn()
+    const unsubscribe = store.subscribe(subscriber)
+    const queueMicrotaskSpy = vi.spyOn(globalThis, 'queueMicrotask').mockImplementation(() => {})
+
+    store.getState().clearTransientAgentStatuses('ssh-a', 30)
+
+    unsubscribe()
+    expect(subscriber).toHaveBeenCalledOnce()
+    expect(queueMicrotaskSpy).toHaveBeenCalledOnce()
+    expect(store.getState().agentStatusByPaneKey[oldA]).toBeUndefined()
+    expect(store.getState().agentStatusByPaneKey[secondA]).toBeUndefined()
+    expect(store.getState().agentStatusByPaneKey[newerA]).toBeDefined()
+    expect(store.getState().agentStatusByPaneKey[siblingB]).toBeDefined()
+    expect(store.getState().agentStatusByPaneKey[unstamped]).toBeDefined()
+    expect(store.getState().agentLaunchConfigByPaneKey[oldA]).toBeDefined()
+    expect(store.getState().acknowledgedAgentsByPaneKey[oldA]).toBe(2)
+    expect(store.getState().retentionSuppressedPaneKeys[oldA]).toBe(true)
+  })
+
+  it('retains an accepted connection stamp across later unstamped pings', () => {
+    const store = createTestStore()
+    const paneKey = 'tab-a:11111111-1111-4111-8111-111111111111'
+    store
+      .getState()
+      .setAgentStatus(
+        paneKey,
+        { state: 'working', prompt: 'first', agentType: 'codex' },
+        undefined,
+        { updatedAt: 1 },
+        { connectionId: 'ssh-a' }
+      )
+    store
+      .getState()
+      .setAgentStatus(
+        paneKey,
+        { state: 'working', prompt: 'ping', agentType: 'codex' },
+        undefined,
+        { updatedAt: 2 }
+      )
+
+    expect(store.getState().agentStatusByPaneKey[paneKey]?.connectionId).toBe('ssh-a')
+  })
+})
diff --git a/src/renderer/src/store/slices/agent-status.ts b/src/renderer/src/store/slices/agent-status.ts
index 14fa98fefe7..c6b34559fe3 100644
--- a/src/renderer/src/store/slices/agent-status.ts
+++ b/src/renderer/src/store/slices/agent-status.ts
@@ -162,7 +162,12 @@ export type AgentStatusSlice = {
     },
     terminalTitle?: string,
     timing?: { updatedAt?: number; stateStartedAt?: number },
-    routing?: { tabId?: string; worktreeId?: string; terminalHandle?: string },
+    routing?: {
+      tabId?: string
+      worktreeId?: string
+      terminalHandle?: string
+      connectionId?: string | null
+    },
     metadata?: {
       providerSession?: AgentProviderSessionMetadata
       launchConfig?: SleepingAgentLaunchConfig
@@ -207,6 +212,9 @@ export type AgentStatusSlice = {
    *  Used when a tab is closed — same prefix-sweep as cacheTimerByKey cleanup. */
   removeAgentStatusByTabPrefix: (tabIdPrefix: string) => void
 
+  /** Remove stale live rows while preserving pane launch and resume identity. */
+  clearTransientAgentStatuses: (connectionId: string, clearedAt: number) => void
+
   /** Remove a single entry AND suppress re-retention on its next disappearance.
    *  Used for USER-INITIATED teardown — the dashboard/hover X button, and
    *  pane close — where the user is telling us "I'm done with this row". */
@@ -1785,6 +1793,11 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
             existing?.worktreeId ??
             findAgentPaneWorktreeId(s, paneKey) ??
             undefined,
+          ...(routing?.connectionId !== undefined
+            ? { connectionId: routing.connectionId }
+            : existing?.connectionId !== undefined
+              ? { connectionId: existing.connectionId }
+              : {}),
           tabId: statusTabId,
           terminalTitle: effectiveTitle,
           stateHistory: history,
@@ -2180,6 +2193,39 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
       queueMicrotask(() => freshness.schedule())
     },
 
+    clearTransientAgentStatuses: (connectionId, clearedAt) => {
+      if (connectionId.length === 0 || !Number.isFinite(clearedAt)) {
+        return
+      }
+      let removed = false
+      set((s) => {
+        let next: Record<string, AgentStatusEntry> | null = null
+        for (const [paneKey, existing] of Object.entries(s.agentStatusByPaneKey)) {
+          // Why: undefined is an unstamped legacy/renderer-owned row. Its host
+          // cannot be proven, so normal pane teardown remains its safe cleanup.
+          if (existing.connectionId !== connectionId || existing.updatedAt > clearedAt) {
+            continue
+          }
+          next ??= { ...s.agentStatusByPaneKey }
+          delete next[paneKey]
+        }
+        if (!next) {
+          return s
+        }
+        removed = true
+        // Why: transport loss is reversible. Keep launch, resume, retention,
+        // and acknowledgement maps intact for same-pane relay replay.
+        return {
+          agentStatusByPaneKey: next,
+          agentStatusEpoch: s.agentStatusEpoch + 1,
+          sortEpoch: s.sortEpoch + 1
+        }
+      })
+      if (removed) {
+        queueMicrotask(() => freshness.schedule())
+      }
+    },
+
     dropAgentStatus: (paneKey) => {
       // Why: single sync read — zustand set is synchronous, so the value we
       // observe inside the set callback is the same one we would re-read via
diff --git a/src/shared/agent-status-types.ts b/src/shared/agent-status-types.ts
index 728d8e1b9bb..5eaec131742 100644
--- a/src/shared/agent-status-types.ts
+++ b/src/shared/agent-status-types.ts
@@ -121,6 +121,8 @@ export type AgentStatusEntry = {
    *  present in a renderer; retaining this lets worktree-level UI still show
    *  the live child agent instead of dropping it as unattributed. */
   worktreeId?: string
+  /** Accepted transport authority for this live row; null means local. */
+  connectionId?: string | null
   /** Tab attribution from the hook IPC payload, when available. */
   tabId?: string
   terminalTitle?: string
@@ -230,6 +232,15 @@ export type AgentStatusIpcPayload = ParsedAgentStatusPayload & {
   promptInteractionKey?: string
 }
 
+/** Wire shape for ordinary pane teardown or a stamped SSH disconnect batch. */
+export type AgentStatusClearIpcPayload =
+  | { paneKey: string }
+  | {
+      transient: true
+      connectionId: string
+      clearedAt: number
+    }
+
 /** Maximum character length for the toolName field. */
 export const AGENT_STATUS_TOOL_NAME_MAX_LENGTH = 60
 /** Maximum character length for the toolInput preview. */

From 7adda25b0a72598ea92f7955045adaa158da54cd Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Sun, 19 Jul 2026 19:38:44 -0700
Subject: [PATCH 21/54] fix(daemon): retire empty current-generation daemons
 (#9277)

* fix(daemon): retire empty current-generation daemons

Co-authored-by: Orca <help@stably.ai>

* fix(daemon): retire empty daemons on disconnect

Co-authored-by: Orca <help@stably.ai>

* test(daemon): authenticate Windows lifecycle harness

Co-authored-by: Orca <help@stably.ai>

* test(daemon): assert remaining shutdown budget

Co-authored-by: Orca <help@stably.ai>

---------

Co-authored-by: Orca <help@stably.ai>
---
 .../windows-daemon-workspace-close-repro.mjs  | 122 ++-
 .../2026-07-18-daemon-lifecycle-retirement.md | 279 ++++++
 src/main/daemon/client.test.ts                | 100 +-
 src/main/daemon/client.ts                     | 188 +++-
 src/main/daemon/daemon-entry.test.ts          |  43 +
 src/main/daemon/daemon-entry.ts               |  39 +-
 ...n-foreground-confirmation-protocol.test.ts |   4 +-
 src/main/daemon/daemon-hello-protocol.ts      |  20 +
 src/main/daemon/daemon-idle-shutdown.test.ts  | 728 +++++++++++++++
 src/main/daemon/daemon-init.test.ts           | 761 ++++++++++++++-
 src/main/daemon/daemon-init.ts                | 878 ++++++++++++------
 src/main/daemon/daemon-main.ts                |  17 +-
 src/main/daemon/daemon-pty-adapter.ts         |  90 +-
 .../daemon-self-retirement-respawn.test.ts    | 228 +++++
 src/main/daemon/daemon-server.test.ts         |  95 +-
 src/main/daemon/daemon-server.ts              | 492 ++++++++--
 src/main/daemon/daemon-spawner.test.ts        |  67 +-
 src/main/daemon/daemon-spawner.ts             |  98 +-
 src/main/daemon/production-launcher.test.ts   | 215 ++++-
 src/main/daemon/production-launcher.ts        | 188 +++-
 src/main/daemon/types.ts                      |  29 +-
 tests/e2e/daemon-lifecycle-retirement.spec.ts | 241 +++++
 tests/e2e/fixtures/daemon-lifecycle-entry.ts  | 122 +++
 23 files changed, 4492 insertions(+), 552 deletions(-)
 create mode 100644 docs/reference/plans/2026-07-18-daemon-lifecycle-retirement.md
 create mode 100644 src/main/daemon/daemon-hello-protocol.ts
 create mode 100644 src/main/daemon/daemon-idle-shutdown.test.ts
 create mode 100644 src/main/daemon/daemon-self-retirement-respawn.test.ts
 create mode 100644 tests/e2e/daemon-lifecycle-retirement.spec.ts
 create mode 100644 tests/e2e/fixtures/daemon-lifecycle-entry.ts

diff --git a/config/scripts/windows-daemon-workspace-close-repro.mjs b/config/scripts/windows-daemon-workspace-close-repro.mjs
index be920ca7192..974e865722d 100644
--- a/config/scripts/windows-daemon-workspace-close-repro.mjs
+++ b/config/scripts/windows-daemon-workspace-close-repro.mjs
@@ -30,19 +30,99 @@ function readProtocolVersion() {
   return Number(match[1])
 }
 
+function createStreamSocket(socketPath, token, protocolVersion, clientId, onFailure) {
+  const socket = connect(socketPath)
+  let buffer = ''
+
+  return new Promise((resolveStream, rejectStream) => {
+    let handshakeComplete = false
+    const rejectHandshake = (error) => {
+      if (handshakeComplete) {
+        onFailure(error)
+        return
+      }
+      handshakeComplete = true
+      clearTimeout(timer)
+      socket.removeListener('data', onData)
+      socket.removeListener('error', onError)
+      socket.removeListener('close', onClose)
+      socket.destroy()
+      rejectStream(error)
+    }
+    const onError = (error) => rejectHandshake(error)
+    const onClose = () => rejectHandshake(new Error('Daemon stream socket closed'))
+    const onData = (chunk) => {
+      buffer += chunk.toString('utf8')
+      const newline = buffer.indexOf('\n')
+      if (newline === -1) {
+        return
+      }
+      const message = JSON.parse(buffer.slice(0, newline))
+      if (message.type !== 'hello') {
+        return
+      }
+      if (!message.ok) {
+        rejectHandshake(new Error(message.error ?? 'Daemon rejected stream hello'))
+        return
+      }
+      handshakeComplete = true
+      clearTimeout(timer)
+      socket.removeListener('data', onData)
+      // Why: drain terminal events even though this lifecycle repro only asserts through RPC.
+      socket.on('data', () => {})
+      resolveStream(socket)
+    }
+    const timer = setTimeout(
+      () => rejectHandshake(new Error('Daemon stream hello timed out')),
+      requestTimeoutMs
+    )
+    socket.on('error', onError)
+    socket.on('close', onClose)
+    socket.on('data', onData)
+    socket.once('connect', () => {
+      socket.write(
+        `${JSON.stringify({
+          type: 'hello',
+          version: protocolVersion,
+          token,
+          clientId,
+          role: 'stream'
+        })}\n`
+      )
+    })
+  })
+}
+
 function createRpcClient(socketPath, tokenPath) {
   const socket = connect(socketPath)
+  const clientId = randomUUID()
+  const protocolVersion = readProtocolVersion()
+  const token = readFileSync(tokenPath, 'utf8').trim()
   const pending = new Map()
   let buffer = ''
   let requestId = 0
+  let streamSocket
+  let connectionError
   let helloResolve
   let helloReject
+  let helloTimer
   const hello = new Promise((resolveHello, rejectHello) => {
-    helloResolve = resolveHello
-    helloReject = rejectHello
+    helloResolve = () => {
+      clearTimeout(helloTimer)
+      resolveHello()
+    }
+    helloReject = (error) => {
+      clearTimeout(helloTimer)
+      rejectHello(error)
+    }
   })
+  helloTimer = setTimeout(() => {
+    helloReject(new Error('Daemon control hello timed out'))
+    socket.destroy()
+  }, requestTimeoutMs)
 
   const rejectPending = (error) => {
+    connectionError ??= error
     helloReject(error)
     for (const { reject, timer } of pending.values()) {
       clearTimeout(timer)
@@ -82,25 +162,40 @@ function createRpcClient(socketPath, tokenPath) {
     }
   })
 
-  const connected = new Promise((resolveConnected, rejectConnected) => {
+  const socketConnected = new Promise((resolveConnected, rejectConnected) => {
     socket.once('connect', resolveConnected)
     socket.once('error', rejectConnected)
-  }).then(() => {
-    socket.write(
-      `${JSON.stringify({
-        type: 'hello',
-        version: readProtocolVersion(),
-        token: readFileSync(tokenPath, 'utf8').trim(),
-        clientId: randomUUID(),
-        role: 'control'
-      })}\n`
+  })
+  const connected = Promise.all([
+    socketConnected.then(() => {
+      socket.write(
+        `${JSON.stringify({
+          type: 'hello',
+          version: protocolVersion,
+          token,
+          clientId,
+          role: 'control'
+        })}\n`
+      )
+    }),
+    hello
+  ]).then(async () => {
+    // Why: v24 only admits terminals for the same complete control+stream pair as production.
+    streamSocket = await createStreamSocket(
+      socketPath,
+      token,
+      protocolVersion,
+      clientId,
+      rejectPending
     )
-    return hello
   })
 
   return {
     async request(type, payload) {
       await connected
+      if (connectionError) {
+        throw connectionError
+      }
       const id = `repro-${++requestId}`
       return new Promise((resolveRequest, rejectRequest) => {
         const timer = setTimeout(() => {
@@ -112,6 +207,7 @@ function createRpcClient(socketPath, tokenPath) {
       })
     },
     close() {
+      streamSocket?.destroy()
       socket.destroy()
     }
   }
diff --git a/docs/reference/plans/2026-07-18-daemon-lifecycle-retirement.md b/docs/reference/plans/2026-07-18-daemon-lifecycle-retirement.md
new file mode 100644
index 00000000000..104f6409929
--- /dev/null
+++ b/docs/reference/plans/2026-07-18-daemon-lifecycle-retirement.md
@@ -0,0 +1,279 @@
+# Daemon lifecycle retirement for issue #9138
+
+## Status
+
+Implemented and locally validated for PR #9277.
+
+The earlier full ownership/audit prototype is preserved at:
+
+- branch: `Jinwoo-H/issue-9138-full-ownership-audit-snapshot`
+- commit: `7c915909bd26670b8af36aa683cff85077395dd1`
+- GitHub: <https://github.com/stablyai/orca/tree/Jinwoo-H/issue-9138-full-ownership-audit-snapshot>
+
+That branch is the recovery point for ownership persistence, cross-profile raw extraction, startup
+audit, the candidate journal, profile-transfer recovery, natural-exit reconciliation, and future
+legacy enforcement. None of those systems ship in this PR.
+
+Current `main` assigned protocol v23 to the macOS login-shell preparation change while this work was
+in progress. The lifecycle contract therefore ships as v24; v23 is preserved as a legacy generation
+alongside v22 and older versions.
+
+## Inputs and scope decision
+
+Issue: <https://github.com/stablyai/orca/issues/9138>
+
+Reviewed design comment by AmethystLiang:
+<https://github.com/stablyai/orca/issues/9138#issuecomment-5006601124>
+
+The reviewed comment correctly identifies two different problems:
+
+1. current-generation daemons have no daemon-owned empty lifecycle;
+2. legacy sessions need complete cross-profile ownership evidence before an app-side reaper can act.
+
+This PR solves only the first problem. The second problem is much larger, adds steady-state
+persistence and startup-audit cost, and is audit-only until field evidence can justify enforcement.
+Keeping it out makes the user-visible fix small enough to review and benchmark independently.
+
+The narrow implementation retains these important rules from AmethystLiang's design:
+
+- daemon lifecycle behavior requires a protocol bump because old running daemons cannot acquire it;
+- live sessions always win over cleanup;
+- absence from a worktree, pane layout, profile, or failed listing is never destructive evidence;
+- exact PID, process-start time, and per-launch nonce identify a v24 endpoint incarnation;
+- the daemon, not app startup, makes the atomic empty decision;
+- pre-v24 daemons stay reattachable and are not automatically shut down;
+- SSH, WSL, remote-runtime, degraded-provider, sleep/wake, and profile behavior stay unchanged.
+
+The narrow implementation changes one policy from the original comment: it does not use a blanket
+30-minute idle timer. Any loss of the last fully authenticated app client is an exact lifecycle
+event, so a daemon retires as soon as it can atomically prove it is empty. This removes runtime
+inactivity heuristics and periodic ownership work.
+
+## User-visible behavior
+
+```text
+Before
+
+app disconnects ──> daemon stays forever
+                         ├── live sessions stay (wanted)
+                         └── zero sessions also stay (leak)
+
+After
+
+clean app detach ──> daemon atomically checks itself
+                         ├── any live session/work/client ──> stay alive
+                         └── exactly empty ──> exit immediately
+
+unexpected drop ──> daemon atomically checks itself
+                         ├── live session/work/connection ──> stay alive
+                         └── exactly empty ──> exit immediately
+
+v23 and older ──> existing reattach behavior; no automatic retirement
+```
+
+An end user with live terminals should notice no change. An end user who quits with no daemon-backed
+terminals should no longer accumulate the new v24 generation. If Orca crashes or loses its socket,
+live terminals still keep the daemon alive indefinitely. An empty daemon exits immediately; a later
+app restart launches a fresh daemon instead of reusing an empty process.
+
+## Protocol and lifecycle design
+
+### Endpoint identity
+
+Protocol v24 hello responses include:
+
+```ts
+type DaemonEndpointIdentity = {
+  pid: number
+  startedAtMs: number
+  launchNonce: string
+}
+```
+
+The parent generates the launch nonce, passes the nonce and PID-record path to the daemon, and writes
+the daemon's self-reported start time plus the same nonce to the PID record. Both authenticated client
+sockets must report the same valid identity. v24 rejects a missing or malformed identity; v23 keeps
+the previous identity-free handshake.
+
+PID publication is fail-closed. Missing readiness identity, invalid PID, an existing PID record, or a
+write failure terminates the new child and fails launch instead of leaving an untracked daemon.
+
+### Clean detach
+
+At the end of `DaemonPtyAdapter.disconnectOnly()`, after final checkpoints and producer resumes, a
+v24 adapter establishes a full connection if necessary and sends `shutdownIfIdle` within one shared
+250 ms budget. v23 and older adapters skip it.
+
+Initialization establishes one authenticated v24 lifecycle lease even before the first terminal is
+opened. This cancels the initial launch-adoption watchdog and ensures a never-used daemon can still
+receive clean retirement on quit. If startup fallback has already won, the late daemon is not
+installed; it instead receives the same bounded retirement attempt, which an adopted live session
+will reject.
+
+The daemon accepts retirement only when, in one event-loop turn:
+
+- the requesting authenticated client has both control and stream sockets;
+- it is the only authenticated client;
+- every accepted transport belongs to that client;
+- no `createOrAttach` operation is in flight;
+- the terminal host has zero sessions.
+
+When all conditions hold, the daemon synchronously closes the listening server before replying. That
+is the admission fence: a new socket or terminal cannot appear after the empty proof. Cleanup then
+runs asynchronously and the process exits. A failed RPC is non-fatal to app quit and falls back to
+the same event-driven empty check when the authenticated sockets close.
+
+### Initial adoption watchdog
+
+A freshly launched v24 daemon gets up to two minutes to receive its first complete authenticated
+client pair. Without this startup-only watchdog, the daemon would prove itself empty and exit in the
+normal launch handoff before the parent could connect; without a bound, a parent crash during that
+handoff would orphan the new daemon forever.
+
+A complete pair permanently cancels this watchdog, and terminal admission requires that complete
+pair. Raw and partial transports pause it without extending its original deadline. It is never
+rearmed after adoption and is not a terminal inactivity or crash-reconnect timer.
+
+### Unexpected disconnect
+
+When the last client that completed both authenticated sockets loses its control connection, the
+daemon records an event-driven retirement request with no wall-clock grace.
+
+- A complete authenticated reconnect cancels the request if existing work or a transport kept the
+  daemon alive long enough to reconnect.
+- Only a complete authenticated pair may admit a terminal; completing that pair cancels the request
+  before admission can begin.
+- A raw socket, one-socket health probe, or partial authenticated connection blocks retirement but
+  cannot erase evidence that the last fully connected app left.
+- Replacing a client ID first records the old full connection's loss; completing the replacement
+  stream cancels that evidence, while an incomplete replacement only blocks retirement.
+- A live session prevents shutdown indefinitely. When the last session exits, the daemon immediately
+  rechecks every guard and retires only if it is then exactly empty.
+
+The adapter remembers an authenticated unexpected disconnect. If self-retirement later removes the
+token, a token-file `ENOENT` is respawnable only with that prior evidence. An initial missing token is
+not broadened into destructive or respawn authority.
+
+### Artifact cleanup
+
+The daemon removes only artifacts it can claim as its own:
+
+- token contents must match the daemon's in-memory token;
+- PID and launch nonce must match the daemon process and launch nonce;
+- cleanup first renames the canonical entry to a unique claim, validates that claim, and never
+  overwrites or unlinks a replacement installed at the canonical path.
+
+Current-protocol external cleanup waits for v24 self-shutdown and does not unconditionally remove v24
+PID/socket artifacts. Legacy cleanup behavior is unchanged.
+
+## Performance design
+
+There is no polling, profile enumeration, ownership checksum, candidate journal, process scan, or
+steady-state persistence write in this PR.
+
+The steady-state terminal hot path adds no timer work and no per-byte hashing. Initialization adds one
+two-socket authenticated lifecycle handshake; the only new RPC is on app/provider detach, and its
+connect-plus-request path shares a 250 ms cap, including when quit joins an existing connection
+attempt; teardown fences that attempt from resurrecting sockets afterward. Unexpected-disconnect
+bookkeeping changes only socket and session lifecycle events. Each unadopted daemon owns at most one
+unref'ed startup watchdog, which is canceled permanently on adoption.
+
+Validation compares current main and the branch for:
+
+- daemon connect plus two-socket hello latency;
+- repeated `listSessions` RPC latency;
+- terminal echo/stream throughput through a real socket daemon;
+- clean empty-detach latency;
+- event-loop delay under repeated RPC/stream work;
+- idle CPU/RSS and timer count where observable.
+
+The acceptance target is no statistically meaningful terminal throughput regression and no new
+steady-state disk writes. Results are recorded in the PR body.
+
+### Local performance regression screen
+
+The final local host was not quiet enough for publication-grade absolute numbers: load averages were
+17-38 and unrelated Orca, browser, simulator, and VM processes occupied several cores. A paired
+same-host screen still found no large regression. Five `main` v23 samples were bracketed by ten v24
+branch samples; medians across sample medians were:
+
+| Measure              | `main` v23 | branch v24 |
+| -------------------- | ---------: | ---------: |
+| two-socket connect   |    1.38 ms |    1.32 ms |
+| `listSessions` RPC   |  0.0366 ms |  0.0374 ms |
+| terminal echo stream | 3.28 MiB/s | 3.14 MiB/s |
+
+All three medians were within about 5%. Individual stream samples varied from 0.66 to 4.04 MiB/s and
+event-loop-delay samples had similar load-driven outliers, so these results are a coarse regression
+screen, not evidence of an exact performance delta. Static hot-path review confirms lifecycle work
+runs on connection, disconnection, session admission/exit, and quit events, with no new work per PTY
+byte and no steady-state persistence or polling.
+
+## Verification and validation
+
+### Focused unit and integration tests
+
+- v24 requires valid matching endpoint identity on both sockets.
+- v23 and v22 accept the prior identity-free handshake and remain listed as previous protocols.
+- production launch passes PID path and nonce and writes the exact readiness identity.
+- incomplete readiness identity or failed exclusive PID publication kills and rejects the child.
+- clean empty detach exits immediately.
+- a never-used current adapter connects and retires cleanly on quit.
+- initial adoption cancels the launch watchdog and keeps first-terminal spawn working after its old
+  deadline.
+- a live session, another client, raw transport, or in-flight admission rejects clean retirement.
+- a control-only overlapping client blocks but cannot erase the last full-client retirement request.
+- a same-client-ID control replacement cannot erase the prior full connection's retirement request.
+- a control-only client cannot admit a terminal or erase startup/retirement evidence with a failed
+  request.
+- startup fail-open performs bounded empty retirement without installing a late provider.
+- quit remains bounded while a prior handshake is stalled and cannot resurrect client sockets later.
+- the synchronous listener fence rejects post-fence connections as retryable.
+- an unexpected empty disconnect retires immediately without a runtime inactivity timer.
+- a real reconnect cancels pending retirement while live work keeps the daemon available.
+- raw and health probes block but cannot erase pending retirement.
+- final session exit triggers an immediate guarded retirement check.
+- token/PID cleanup preserves malformed, stale, and replacement artifacts.
+- authenticated token disappearance performs one coalesced respawn; initial token absence does not.
+
+### Process/E2E tests
+
+- start a real isolated v24 daemon with real socket/named-pipe, token, and PID artifacts;
+- authenticate, disconnect the last empty client, and verify the exact process and owned artifacts
+  exit;
+- prove a live session rejects retirement and remains reattachable;
+- run a protocol-v22 fixture beside v24 and prove v22 remains connectable/reattachable;
+- never target a production runtime directory or signal a process not created by the fixture.
+
+### Repository validation
+
+- Node typecheck;
+- oxlint and repository max-lines policy;
+- focused daemon, adapter, launcher, restart, and legacy-routing suites;
+- full daemon test suite;
+- desktop and web production builds;
+- `git diff --check` and review of every changed file against `origin/main`;
+- independent review-until-clean, with review loops recorded in `.orca/bug-factory.json`;
+- packaged Windows/Linux validation where CI is available; local macOS process E2E before publication.
+
+Final local results on macOS arm64 after the event-driven policy revision:
+
+- full daemon suite: 56 files passed, 2 skipped; 939 tests passed, 5 skipped;
+- process E2E: v22 remained live and reattachable while the exact empty v24 process and its owned
+  artifacts retired immediately after its final authenticated client disconnected;
+- full Node typecheck, focused oxlint, max-lines ratchet, and `git diff --check` passed;
+- full desktop, web, and native production build passed with existing build warnings;
+- three independent post-revision review tracks covering architecture/state machines,
+  ownership/adoption, and process lifecycle ended clean after actionable findings were fixed.
+
+The local shell used Node 26.5.0 while the repository requests Node 24; the commands completed
+successfully, and repository CI remains responsible for the supported Node/platform matrix.
+
+## Rollout and rollback
+
+This PR changes only v24. Existing v23 and older daemons are preserved. Rolling back the app leaves
+v24 as another legacy generation and does not give an older app authority to shut it down.
+
+If the lifecycle behavior must be disabled, revert the v24 protocol/lifecycle commit. The separated
+ownership/audit prototype remains recoverable from the archived branch and commit above; it should
+return only as a separately reviewed, benchmarked follow-up.
diff --git a/src/main/daemon/client.test.ts b/src/main/daemon/client.test.ts
index 25aaebe164f..a3d6d9f610d 100644
--- a/src/main/daemon/client.test.ts
+++ b/src/main/daemon/client.test.ts
@@ -68,6 +68,12 @@ describe('DaemonClient', () => {
     onStreamHello?: (msg: HelloMessage) => void
     rejectVersion?: boolean
     suppressHelloResponse?: boolean
+    omitHelloIdentity?: boolean
+    helloIdentity?: (role: 'control' | 'stream') => {
+      pid: number
+      startedAtMs: number
+      launchNonce: string
+    }
   }): Promise<void> {
     return new Promise((resolve) => {
       server = createServer((socket) => {
@@ -103,7 +109,19 @@ describe('DaemonClient', () => {
                 socket.write(encodeNdjson({ type: 'hello', ok: false, error: 'Version mismatch' }))
                 return
               }
-              socket.write(encodeNdjson({ type: 'hello', ok: true }))
+              socket.write(
+                encodeNdjson({
+                  type: 'hello',
+                  ok: true,
+                  ...(!opts?.omitHelloIdentity
+                    ? {
+                        daemonIdentity: opts?.helloIdentity
+                          ? opts.helloIdentity(hello.role)
+                          : { pid: 123, startedAtMs: 456, launchNonce: 'default-launch' }
+                      }
+                    : {})
+                })
+              )
               if (hello.role === 'stream') {
                 opts?.onStreamHello?.(hello)
               }
@@ -136,6 +154,48 @@ describe('DaemonClient', () => {
       await waitFor(() => hellos.length > 0)
     })
 
+    it('captures one matching endpoint identity from both authenticated sockets', async () => {
+      const identity = { pid: 123, startedAtMs: 456, launchNonce: 'launch-a' }
+      await startMockDaemon({ helloIdentity: () => identity })
+
+      client = new DaemonClient({ socketPath, tokenPath })
+      await client.ensureConnected()
+
+      expect(client.getDaemonIdentity()).toEqual(identity)
+    })
+
+    it('rejects a v24 daemon that omits endpoint identity', async () => {
+      await startMockDaemon({ omitHelloIdentity: true })
+      client = new DaemonClient({ socketPath, tokenPath })
+
+      await expect(client.ensureConnected()).rejects.toThrow('Invalid daemon identity')
+    })
+
+    it('allows a legacy v23 daemon to omit endpoint identity', async () => {
+      await startMockDaemon({ omitHelloIdentity: true })
+      client = new DaemonClient({ socketPath, tokenPath, protocolVersion: 23 })
+
+      await expect(client.ensureConnected()).resolves.toBeUndefined()
+      expect(client.getDaemonIdentity()).toBeNull()
+    })
+
+    it('rejects when control and stream sockets report different daemon identities', async () => {
+      await startMockDaemon({
+        helloIdentity: (role) => ({
+          pid: role === 'control' ? 123 : 124,
+          startedAtMs: 456,
+          launchNonce: 'launch-a'
+        })
+      })
+
+      client = new DaemonClient({ socketPath, tokenPath })
+
+      await expect(client.ensureConnected()).rejects.toThrow(
+        'Daemon identity changed during connection'
+      )
+      expect(client.getDaemonIdentity()).toBeNull()
+    })
+
     it('removes socket startup listeners after connecting', async () => {
       await startMockDaemon()
 
@@ -189,6 +249,35 @@ describe('DaemonClient', () => {
       }
     })
 
+    it('bounds a waiter on an existing connection attempt and prevents socket resurrection', async () => {
+      let resolveHello: () => void = () => {}
+      const helloReceived = new Promise<void>((resolve) => {
+        resolveHello = resolve
+      })
+      await startMockDaemon({
+        suppressHelloResponse: true,
+        onHello: resolveHello
+      })
+      client = new DaemonClient({ socketPath, tokenPath })
+      const ownerAttempt = client.ensureConnected().catch((error: Error) => error)
+      await helloReceived
+
+      await expect(client.ensureConnectedWithin(25)).rejects.toThrow(
+        'Connection attempt wait timed out'
+      )
+      client.disconnect()
+      await expect(ownerAttempt).resolves.toBeInstanceOf(Error)
+      await new Promise((resolve) => setTimeout(resolve, 25))
+
+      const disconnected = client as unknown as {
+        controlSocket: Socket | null
+        streamSocket: Socket | null
+      }
+      expect(client.isConnected()).toBe(false)
+      expect(disconnected.controlSocket).toBeNull()
+      expect(disconnected.streamSocket).toBeNull()
+    })
+
     it('removes hello startup listeners after timeout', async () => {
       vi.useFakeTimers()
 
@@ -200,11 +289,16 @@ describe('DaemonClient', () => {
       socket.destroy = destroy as unknown as Socket['destroy']
       const sendHello = (
         client as unknown as {
-          sendHello(socket: Socket, token: string, role: 'control' | 'stream'): Promise<void>
+          sendHello(
+            socket: Socket,
+            token: string,
+            role: 'control' | 'stream',
+            timeoutMs: number
+          ): Promise<void>
         }
       ).sendHello.bind(client)
 
-      const promise = sendHello(socket, 'test-token-123', 'control')
+      const promise = sendHello(socket, 'test-token-123', 'control', 5000)
       const rejection = expect(promise).rejects.toThrow('Hello response timed out')
       await vi.advanceTimersByTimeAsync(5000)
 
diff --git a/src/main/daemon/client.ts b/src/main/daemon/client.ts
index 8b6c1b29d90..d0dd2453471 100644
--- a/src/main/daemon/client.ts
+++ b/src/main/daemon/client.ts
@@ -4,11 +4,23 @@ import { readFileSync } from 'node:fs'
 import { randomUUID } from 'node:crypto'
 import { StringDecoder } from 'node:string_decoder'
 import { encodeNdjson, createNdjsonParser } from './ndjson'
-import { PROTOCOL_VERSION, NOTIFY_PREFIX, DaemonProtocolError } from './types'
-import type { HelloMessage, HelloResponse, RpcResponse, DaemonEvent } from './types'
+import {
+  CLEAN_DISCONNECT_PROTOCOL_VERSION,
+  PROTOCOL_VERSION,
+  NOTIFY_PREFIX,
+  DaemonProtocolError
+} from './types'
+import type {
+  DaemonEndpointIdentity,
+  HelloMessage,
+  HelloResponse,
+  RpcResponse,
+  DaemonEvent
+} from './types'
 import { addNodePtyRecoveryHint } from './node-pty-error-hints'
 
 const CONNECT_TIMEOUT_MS = 5000
+const CONNECTION_ATTEMPT_WAIT_MS = CONNECT_TIMEOUT_MS * 4
 const REQUEST_TIMEOUT_MS = 30000
 
 export type DaemonClientOptions = {
@@ -42,6 +54,9 @@ export class DaemonClient {
   // all call ensureConnected(). Without a lock, each starts a separate
   // connection attempt, overwriting sockets and triggering "Connection lost".
   private connectingPromise: Promise<void> | null = null
+  private connectionAttemptGeneration = 0
+  private daemonIdentity: DaemonEndpointIdentity | null = null
+  private observedAuthenticatedDisconnect = false
 
   private pendingRequests = new Map<string, PendingRequest>()
   private eventListeners: ((event: unknown) => void)[] = []
@@ -59,15 +74,38 @@ export class DaemonClient {
     return this.connected
   }
 
+  getDaemonIdentity(): DaemonEndpointIdentity | null {
+    return this.daemonIdentity ? { ...this.daemonIdentity } : null
+  }
+
+  hasObservedAuthenticatedDisconnect(): boolean {
+    return this.observedAuthenticatedDisconnect
+  }
+
   async ensureConnected(): Promise<void> {
+    return this.ensureConnectedWithTimeout(CONNECT_TIMEOUT_MS, false)
+  }
+
+  async ensureConnectedWithin(timeoutMs: number): Promise<void> {
+    return this.ensureConnectedWithTimeout(timeoutMs, true)
+  }
+
+  private async ensureConnectedWithTimeout(
+    timeoutMs: number,
+    sharedBudget: boolean
+  ): Promise<void> {
     if (this.connected) {
       return
     }
     if (this.connectingPromise) {
-      return this.connectingPromise
+      // Why: a normal connection may legitimately consume one timeout for each
+      // socket and hello; bounded teardown calls instead keep their one shared budget.
+      const waiterTimeoutMs = sharedBudget ? timeoutMs : CONNECTION_ATTEMPT_WAIT_MS
+      return this.waitForConnectionAttempt(this.connectingPromise, waiterTimeoutMs)
     }
 
-    this.connectingPromise = this.doConnect()
+    const attemptGeneration = this.connectionAttemptGeneration
+    this.connectingPromise = this.doConnect(timeoutMs, attemptGeneration, sharedBudget)
     try {
       await this.connectingPromise
     } finally {
@@ -75,8 +113,15 @@ export class DaemonClient {
     }
   }
 
-  private async doConnect(): Promise<void> {
+  private async doConnect(
+    timeoutMs: number,
+    attemptGeneration: number,
+    sharedBudget: boolean
+  ): Promise<void> {
     const token = readFileSync(this.tokenPath, 'utf-8').trim()
+    const deadlineMs = Date.now() + timeoutMs
+    const remainingMs = (): number =>
+      sharedBudget ? Math.max(1, deadlineMs - Date.now()) : timeoutMs
     const pendingListenerCleanups: (() => void)[] = []
     const cleanupPendingListeners = (): void => {
       for (const cleanup of pendingListenerCleanups.splice(0)) {
@@ -86,15 +131,32 @@ export class DaemonClient {
 
     try {
       // Sequential: control first, then stream
-      this.controlSocket = await this.connectSocket()
-      await this.sendHello(this.controlSocket, token, 'control')
+      const pendingControlSocket = await this.connectSocket(remainingMs())
+      this.assertConnectionAttemptCurrent(attemptGeneration, pendingControlSocket)
+      this.controlSocket = pendingControlSocket
+      const controlIdentity = await this.sendHello(
+        this.controlSocket,
+        token,
+        'control',
+        remainingMs()
+      )
+      this.assertConnectionAttemptCurrent(attemptGeneration, this.controlSocket)
       pendingListenerCleanups.push(this.setupControlParser(this.controlSocket))
 
-      this.streamSocket = await this.connectSocket()
-      await this.sendHello(this.streamSocket, token, 'stream')
+      const pendingStreamSocket = await this.connectSocket(remainingMs())
+      this.assertConnectionAttemptCurrent(attemptGeneration, pendingStreamSocket)
+      this.streamSocket = pendingStreamSocket
+      const streamIdentity = await this.sendHello(this.streamSocket, token, 'stream', remainingMs())
+      this.assertConnectionAttemptCurrent(attemptGeneration, this.streamSocket)
+      if (!sameDaemonIdentity(controlIdentity, streamIdentity)) {
+        throw new DaemonProtocolError('Daemon identity changed during connection')
+      }
       pendingListenerCleanups.push(this.setupStreamParser(this.streamSocket))
 
+      this.assertConnectionAttemptCurrent(attemptGeneration)
       this.connected = true
+      this.observedAuthenticatedDisconnect = false
+      this.daemonIdentity = controlIdentity
       this.disconnectArmed = true
       this.connectionGeneration++
 
@@ -120,12 +182,17 @@ export class DaemonClient {
       this.controlSocket = null
       this.streamSocket = null
       this.connected = false
+      this.daemonIdentity = null
       this.disconnectArmed = false
       throw error
     }
   }
 
-  async request<T = unknown>(type: string, payload: unknown): Promise<T> {
+  async request<T = unknown>(
+    type: string,
+    payload: unknown,
+    timeoutMs = REQUEST_TIMEOUT_MS
+  ): Promise<T> {
     if (!this.connected || !this.controlSocket) {
       throw new DaemonProtocolError('Not connected')
     }
@@ -136,8 +203,8 @@ export class DaemonClient {
     return new Promise<T>((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pendingRequests.delete(id)
-        reject(new DaemonProtocolError(`Request ${type} timed out after ${REQUEST_TIMEOUT_MS}ms`))
-      }, REQUEST_TIMEOUT_MS)
+        reject(new DaemonProtocolError(`Request ${type} timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
 
       this.pendingRequests.set(id, {
         resolve: resolve as (value: unknown) => void,
@@ -180,7 +247,9 @@ export class DaemonClient {
   }
 
   disconnect(): void {
+    this.connectionAttemptGeneration++
     this.connected = false
+    this.daemonIdentity = null
     this.disconnectArmed = false
     this.cleanupActiveSocketListeners()
 
@@ -196,7 +265,7 @@ export class DaemonClient {
     this.streamSocket = null
   }
 
-  private connectSocket(): Promise<Socket> {
+  private connectSocket(timeoutMs: number): Promise<Socket> {
     return new Promise((resolve, reject) => {
       const socket = connect(this.socketPath)
       const cleanup = (): void => {
@@ -216,14 +285,45 @@ export class DaemonClient {
         cleanup()
         socket.destroy()
         reject(new DaemonProtocolError('Connection timed out'))
-      }, CONNECT_TIMEOUT_MS)
+      }, timeoutMs)
 
       socket.on('connect', onConnect)
       socket.on('error', onError)
     })
   }
 
-  private sendHello(socket: Socket, token: string, role: 'control' | 'stream'): Promise<void> {
+  private waitForConnectionAttempt(attempt: Promise<void>, timeoutMs: number): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new DaemonProtocolError('Connection attempt wait timed out'))
+      }, timeoutMs)
+      attempt.then(
+        () => {
+          clearTimeout(timer)
+          resolve()
+        },
+        (error) => {
+          clearTimeout(timer)
+          reject(error)
+        }
+      )
+    })
+  }
+
+  private assertConnectionAttemptCurrent(attemptGeneration: number, socket?: Socket): void {
+    if (attemptGeneration === this.connectionAttemptGeneration) {
+      return
+    }
+    socket?.destroy()
+    throw new DaemonProtocolError('Disconnected')
+  }
+
+  private sendHello(
+    socket: Socket,
+    token: string,
+    role: 'control' | 'stream',
+    timeoutMs: number
+  ): Promise<DaemonEndpointIdentity | null> {
     return new Promise((resolve, reject) => {
       const hello: HelloMessage = {
         type: 'hello',
@@ -245,7 +345,7 @@ export class DaemonClient {
         socket.removeListener('error', onError)
         socket.removeListener('close', onClose)
       }
-      const finish = (error?: Error): void => {
+      const finish = (error?: Error, identity: DaemonEndpointIdentity | null = null): void => {
         if (settled) {
           return
         }
@@ -255,7 +355,7 @@ export class DaemonClient {
           reject(error)
           return
         }
-        resolve()
+        resolve(identity)
       }
       // Why: daemon socket chunks can split emoji/box-drawing UTF-8 bytes.
       // Decoding each Buffer independently would permanently inject U+FFFD.
@@ -271,7 +371,15 @@ export class DaemonClient {
         try {
           const response = JSON.parse(line) as HelloResponse
           if (response.ok) {
-            finish()
+            const identity = parseDaemonEndpointIdentity(response.daemonIdentity)
+            if (
+              (this.protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION && identity === null) ||
+              (response.daemonIdentity !== undefined && identity === null)
+            ) {
+              finish(new DaemonProtocolError('Invalid daemon identity'))
+              return
+            }
+            finish(undefined, identity)
           } else {
             finish(
               new DaemonProtocolError(addNodePtyRecoveryHint(response.error ?? 'Hello rejected'))
@@ -290,7 +398,7 @@ export class DaemonClient {
         // without a handshake timeout, startup waits forever on ensureConnected().
         finish(new DaemonProtocolError('Hello response timed out'))
         socket.destroy()
-      }, CONNECT_TIMEOUT_MS)
+      }, timeoutMs)
       socket.on('data', onData)
       socket.on('error', onError)
       socket.on('close', onClose)
@@ -352,7 +460,12 @@ export class DaemonClient {
       return
     }
     this.disconnectArmed = false
+    this.connectionAttemptGeneration++
+    if (this.daemonIdentity) {
+      this.observedAuthenticatedDisconnect = true
+    }
     this.connected = false
+    this.daemonIdentity = null
     this.cleanupActiveSocketListeners()
 
     for (const [id, pending] of this.pendingRequests) {
@@ -377,3 +490,40 @@ export class DaemonClient {
     cleanup?.()
   }
 }
+
+function parseDaemonEndpointIdentity(value: unknown): DaemonEndpointIdentity | null {
+  if (!value || typeof value !== 'object') {
+    return null
+  }
+  const identity = value as { pid?: unknown; startedAtMs?: unknown; launchNonce?: unknown }
+  if (
+    !Number.isSafeInteger(identity.pid) ||
+    (identity.pid as number) <= 0 ||
+    typeof identity.startedAtMs !== 'number' ||
+    !Number.isFinite(identity.startedAtMs) ||
+    identity.startedAtMs <= 0 ||
+    typeof identity.launchNonce !== 'string' ||
+    identity.launchNonce.length === 0
+  ) {
+    return null
+  }
+  return {
+    pid: identity.pid as number,
+    startedAtMs: identity.startedAtMs,
+    launchNonce: identity.launchNonce
+  }
+}
+
+function sameDaemonIdentity(
+  left: DaemonEndpointIdentity | null,
+  right: DaemonEndpointIdentity | null
+): boolean {
+  return (
+    (left === null && right === null) ||
+    (left !== null &&
+      right !== null &&
+      left.pid === right.pid &&
+      left.startedAtMs === right.startedAtMs &&
+      left.launchNonce === right.launchNonce)
+  )
+}
diff --git a/src/main/daemon/daemon-entry.test.ts b/src/main/daemon/daemon-entry.test.ts
index e24f1c8b3fe..deedb82a2c8 100644
--- a/src/main/daemon/daemon-entry.test.ts
+++ b/src/main/daemon/daemon-entry.test.ts
@@ -51,6 +51,49 @@ describe('daemon-entry parseArgs', () => {
     })
   })
 
+  it('parses the internal PID-record ownership pair', () => {
+    expect(
+      parseArgs([
+        '--socket',
+        '/tmp/t.sock',
+        '--token',
+        '/tmp/t.token',
+        '--pid-record',
+        '/tmp/t.pid',
+        '--launch-nonce',
+        'launch-a'
+      ])
+    ).toEqual({
+      socketPath: '/tmp/t.sock',
+      tokenPath: '/tmp/t.token',
+      pidPath: '/tmp/t.pid',
+      launchNonce: 'launch-a'
+    })
+  })
+
+  it('rejects either PID-record ownership argument without its pair', () => {
+    expect(() =>
+      parseArgs([
+        '--socket',
+        '/tmp/t.sock',
+        '--token',
+        '/tmp/t.token',
+        '--pid-record',
+        '/tmp/t.pid'
+      ])
+    ).toThrow('provided together')
+    expect(() =>
+      parseArgs([
+        '--socket',
+        '/tmp/t.sock',
+        '--token',
+        '/tmp/t.token',
+        '--launch-nonce',
+        'launch-a'
+      ])
+    ).toThrow('provided together')
+  })
+
   it('still requires --socket and --token when --log-file is given', () => {
     expect(() => parseArgs(['--log-file', '/tmp/daemon.log'])).toThrow('Usage:')
   })
diff --git a/src/main/daemon/daemon-entry.ts b/src/main/daemon/daemon-entry.ts
index 4d5207276e0..12c5ad8dd29 100644
--- a/src/main/daemon/daemon-entry.ts
+++ b/src/main/daemon/daemon-entry.ts
@@ -17,6 +17,8 @@ import { prepareMacosTccLoginShell } from '../providers/macos-tcc-login-shell'
 export type ParsedDaemonArgs = {
   socketPath: string
   tokenPath: string
+  pidPath?: string
+  launchNonce?: string
   /** Optional — absent for adopted old daemons and tests, which log nothing. */
   logFilePath?: string
 }
@@ -25,6 +27,8 @@ export function parseArgs(argv: string[]): ParsedDaemonArgs {
   let socketPath = ''
   let tokenPath = ''
   let logFilePath = ''
+  let pidPath = ''
+  let launchNonce = ''
 
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--socket' && argv[i + 1]) {
@@ -36,6 +40,12 @@ export function parseArgs(argv: string[]): ParsedDaemonArgs {
     } else if (argv[i] === '--log-file' && argv[i + 1]) {
       logFilePath = argv[i + 1]
       i++
+    } else if (argv[i] === '--pid-record' && argv[i + 1]) {
+      pidPath = argv[i + 1]
+      i++
+    } else if (argv[i] === '--launch-nonce' && argv[i + 1]) {
+      launchNonce = argv[i + 1]
+      i++
     }
   }
 
@@ -43,7 +53,16 @@ export function parseArgs(argv: string[]): ParsedDaemonArgs {
     throw new Error('Usage: daemon-entry --socket <path> --token <path> [--log-file <path>]')
   }
 
-  return logFilePath ? { socketPath, tokenPath, logFilePath } : { socketPath, tokenPath }
+  if ((pidPath && !launchNonce) || (!pidPath && launchNonce)) {
+    throw new Error('Daemon PID record path and launch nonce must be provided together')
+  }
+
+  return {
+    socketPath,
+    tokenPath,
+    ...(pidPath ? { pidPath, launchNonce } : {}),
+    ...(logFilePath ? { logFilePath } : {})
+  }
 }
 
 async function main(): Promise<void> {
@@ -54,7 +73,10 @@ async function main(): Promise<void> {
   // an otherwise healthy detached daemon. Swallow it: stderr is diagnostic only.
   process.stderr.on('error', () => {})
 
-  const { socketPath, tokenPath, logFilePath } = parseArgs(process.argv.slice(2))
+  const { socketPath, tokenPath, pidPath, launchNonce, logFilePath } = parseArgs(
+    process.argv.slice(2)
+  )
+  const startedAtMs = Date.now() - process.uptime() * 1000
   // Fail-open: a broken log path must never block daemon startup.
   const daemonLog = logFilePath ? createDaemonFileLog(logFilePath) : createNoopDaemonFileLog()
   daemonLog.log('startup', { protocolVersion: PROTOCOL_VERSION, socketPath })
@@ -126,16 +148,25 @@ async function main(): Promise<void> {
   daemon = await startDaemon({
     socketPath,
     tokenPath,
+    ...(pidPath ? { pidPath } : {}),
+    ...(launchNonce ? { launchNonce } : {}),
+    ...(pidPath ? { startedAtMs } : {}),
     log: daemonLog,
     preparePtySpawn: prepareMacosTccLoginShell,
-    spawnSubprocess: (opts) => createPtySubprocess(opts)
+    spawnSubprocess: (opts) => createPtySubprocess(opts),
+    onIdleShutdown: () => {
+      shuttingDown = true
+      daemonLog.log('shutdown', { reason: 'idle' })
+      daemonLog.close()
+      process.exit(0)
+    }
   })
 
   // Signal readiness to parent via IPC (if available)
   if (process.send) {
     // Why: Windows has no cheap OS query for a child's start time, so the
     // daemon self-reports it here for the pid file's pid-recycling guard.
-    process.send({ type: 'ready', startedAtMs: Date.now() - process.uptime() * 1000 })
+    process.send({ type: 'ready', startedAtMs })
   }
   daemonLog.log('ready')
 
diff --git a/src/main/daemon/daemon-foreground-confirmation-protocol.test.ts b/src/main/daemon/daemon-foreground-confirmation-protocol.test.ts
index 4fbb3047d6a..028fb8f0c4c 100644
--- a/src/main/daemon/daemon-foreground-confirmation-protocol.test.ts
+++ b/src/main/daemon/daemon-foreground-confirmation-protocol.test.ts
@@ -3,7 +3,9 @@ import { PREVIOUS_DAEMON_PROTOCOL_VERSIONS, PROTOCOL_VERSION } from './types'
 
 describe('foreground-confirmation daemon protocol', () => {
   it('rejects daemons from before the fresh-confirmation RPC', () => {
-    expect(PROTOCOL_VERSION).toBeGreaterThan(19)
+    expect(PROTOCOL_VERSION).toBe(24)
     expect(PREVIOUS_DAEMON_PROTOCOL_VERSIONS).toContain(19)
+    expect(PREVIOUS_DAEMON_PROTOCOL_VERSIONS).toContain(22)
+    expect(PREVIOUS_DAEMON_PROTOCOL_VERSIONS).toContain(23)
   })
 })
diff --git a/src/main/daemon/daemon-hello-protocol.ts b/src/main/daemon/daemon-hello-protocol.ts
new file mode 100644
index 00000000000..4e288e4db9b
--- /dev/null
+++ b/src/main/daemon/daemon-hello-protocol.ts
@@ -0,0 +1,20 @@
+export type HelloMessage = {
+  type: 'hello'
+  version: number
+  token: string
+  clientId: string
+  role: 'control' | 'stream'
+}
+
+export type DaemonEndpointIdentity = {
+  pid: number
+  startedAtMs: number
+  launchNonce: string
+}
+
+export type HelloResponse = {
+  type: 'hello'
+  ok: boolean
+  error?: string
+  daemonIdentity?: DaemonEndpointIdentity
+}
diff --git a/src/main/daemon/daemon-idle-shutdown.test.ts b/src/main/daemon/daemon-idle-shutdown.test.ts
new file mode 100644
index 00000000000..fa12ba50034
--- /dev/null
+++ b/src/main/daemon/daemon-idle-shutdown.test.ts
@@ -0,0 +1,728 @@
+import { EventEmitter } from 'node:events'
+import { connect, type Socket } from 'node:net'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { DaemonClient } from './client'
+import { DaemonPtyAdapter } from './daemon-pty-adapter'
+import { DaemonServer } from './daemon-server'
+import { PROTOCOL_VERSION } from './types'
+import {
+  getDaemonPidPath,
+  getDaemonSocketPath,
+  serializeDaemonPidFile,
+  unlinkOwnedDaemonPidFile
+} from './daemon-spawner'
+import type { SubprocessHandle } from './session'
+
+type ManualTimer = {
+  callback: () => void
+  dueAt: number
+  cancelled: boolean
+}
+
+class ManualIdleClock {
+  private nowMs = 0
+  private timers = new Set<ManualTimer>()
+
+  setTimeout(callback: () => void, delayMs: number): ManualTimer {
+    const timer = { callback, dueAt: this.nowMs + delayMs, cancelled: false }
+    this.timers.add(timer)
+    return timer
+  }
+
+  clearTimeout(handle: unknown): void {
+    const timer = handle as ManualTimer
+    timer.cancelled = true
+    this.timers.delete(timer)
+  }
+
+  now(): number {
+    return this.nowMs
+  }
+
+  advanceBy(ms: number): void {
+    this.nowMs += ms
+    for (const timer of [...this.timers].sort((a, b) => a.dueAt - b.dueAt)) {
+      if (timer.cancelled || timer.dueAt > this.nowMs) {
+        continue
+      }
+      this.timers.delete(timer)
+      timer.callback()
+    }
+  }
+
+  get pendingCount(): number {
+    return this.timers.size
+  }
+}
+
+function createMockSubprocess(): SubprocessHandle & { exit(code: number): void } {
+  let onExit: ((code: number) => void) | null = null
+  return {
+    pid: 9345,
+    getForegroundProcess: () => null,
+    write: vi.fn(),
+    resize: vi.fn(),
+    kill: vi.fn(),
+    forceKill: vi.fn(),
+    signal: vi.fn(),
+    onData: vi.fn(),
+    onExit(callback) {
+      onExit = callback
+    },
+    dispose: vi.fn(),
+    exit(code) {
+      onExit?.(code)
+    }
+  }
+}
+
+async function waitFor(predicate: () => boolean): Promise<void> {
+  const deadline = Date.now() + 2_000
+  while (!predicate()) {
+    if (Date.now() >= deadline) {
+      throw new Error('Timed out waiting for daemon idle state')
+    }
+    await new Promise((resolve) => setTimeout(resolve, 5))
+  }
+}
+
+async function requestOnRawSocket(
+  socket: Socket,
+  request: { id: string; type: string; payload: unknown }
+): Promise<{ error?: string }> {
+  return new Promise((resolve, reject) => {
+    let buffer = ''
+    const cleanup = (): void => {
+      clearTimeout(timeout)
+      socket.off('data', onData)
+    }
+    const onData = (chunk: Buffer): void => {
+      buffer += chunk.toString('utf8')
+      for (;;) {
+        const newlineIndex = buffer.indexOf('\n')
+        if (newlineIndex === -1) {
+          return
+        }
+        const line = buffer.slice(0, newlineIndex)
+        buffer = buffer.slice(newlineIndex + 1)
+        const message = JSON.parse(line) as { id?: string; error?: string }
+        if (message.id === request.id) {
+          cleanup()
+          resolve(message)
+          return
+        }
+      }
+    }
+    const timeout = setTimeout(() => {
+      cleanup()
+      reject(new Error(`Timed out waiting for raw response ${request.id}`))
+    }, 2_000)
+    socket.on('data', onData)
+    socket.write(`${JSON.stringify(request)}\n`)
+  })
+}
+
+describe('current daemon lifecycle retirement', () => {
+  let dir: string
+  let socketPath: string
+  let tokenPath: string
+  let pidPath: string
+  let clock: ManualIdleClock
+  let server: DaemonServer | null
+  let subprocess: ReturnType<typeof createMockSubprocess>
+  let onIdleShutdown: ReturnType<typeof vi.fn<() => void>>
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'daemon-idle-shutdown-'))
+    socketPath = getDaemonSocketPath(dir)
+    tokenPath = join(dir, 'daemon.token')
+    pidPath = getDaemonPidPath(dir)
+    clock = new ManualIdleClock()
+    subprocess = createMockSubprocess()
+    onIdleShutdown = vi.fn<() => void>()
+    server = null
+  })
+
+  afterEach(async () => {
+    await server?.shutdown().catch(() => {})
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  async function startServer(
+    options: {
+      launchNonce?: string
+      protocolVersion?: number
+    } = {}
+  ): Promise<void> {
+    server = new DaemonServer({
+      socketPath,
+      tokenPath,
+      ...(options.launchNonce ? { pidPath, launchNonce: options.launchNonce } : {}),
+      ...(options.protocolVersion !== undefined
+        ? { protocolVersion: options.protocolVersion }
+        : {}),
+      initialAdoptionTestConfig: { timeoutMs: 100, clock },
+      onIdleShutdown,
+      spawnSubprocess: () => subprocess
+    })
+    await server.start()
+  }
+
+  it('retires immediately after an unexpected empty disconnect and removes owned artifacts', async () => {
+    const launchNonce = 'launch-a'
+    writeFileSync(
+      pidPath,
+      serializeDaemonPidFile({ pid: process.pid, startedAtMs: null, launchNonce })
+    )
+    await startServer({ launchNonce })
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+    client.disconnect()
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+
+    expect(clock.pendingCount).toBe(0)
+    expect(existsSync(tokenPath)).toBe(false)
+    expect(existsSync(pidPath)).toBe(false)
+    if (process.platform !== 'win32') {
+      expect(existsSync(socketPath)).toBe(false)
+    }
+  })
+
+  it('retires a fresh daemon that is never adopted by a full client pair', async () => {
+    await startServer()
+
+    expect(clock.pendingCount).toBe(1)
+    clock.advanceBy(100)
+
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+  })
+
+  it('retires immediately after an authenticated clean disconnect proves it is empty', async () => {
+    await startServer()
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+
+    await expect(client.request('shutdownIfIdle', undefined)).resolves.toEqual({
+      retiring: true
+    })
+    client.disconnect()
+
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+    expect(clock.pendingCount).toBe(0)
+  })
+
+  it('keeps resources alive until the shutdownIfIdle reply write flushes', async () => {
+    await startServer()
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+    const daemon = server as unknown as {
+      clients: Map<string, { controlSocket: Socket }>
+      host: { dispose: () => Promise<void> }
+    }
+    const controlSocket = [...daemon.clients.values()][0].controlSocket
+    const originalWrite = controlSocket.write.bind(controlSocket)
+    let replyFlushed: (() => void) | undefined
+    vi.spyOn(controlSocket, 'write').mockImplementation(((
+      chunk: string | Uint8Array,
+      ...args: unknown[]
+    ) => {
+      replyFlushed = args.find((arg) => typeof arg === 'function') as (() => void) | undefined
+      return originalWrite(chunk)
+    }) as unknown as Socket['write'])
+    const dispose = vi.spyOn(daemon.host, 'dispose')
+
+    await expect(client.request('shutdownIfIdle', undefined)).resolves.toEqual({ retiring: true })
+    expect(dispose).not.toHaveBeenCalled()
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+
+    replyFlushed?.()
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+    expect(dispose).toHaveBeenCalledOnce()
+    client.disconnect()
+  })
+
+  it('finishes shutdownIfIdle when the peer closes before its reply callback', async () => {
+    await startServer()
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+    const daemon = server as unknown as {
+      clients: Map<string, { controlSocket: Socket }>
+      host: { dispose: () => Promise<void> }
+    }
+    const controlSocket = [...daemon.clients.values()][0].controlSocket
+    const originalWrite = controlSocket.write.bind(controlSocket)
+    vi.spyOn(controlSocket, 'write').mockImplementation(((chunk: string | Uint8Array) =>
+      originalWrite(chunk)) as unknown as Socket['write'])
+    const dispose = vi.spyOn(daemon.host, 'dispose')
+
+    await expect(client.request('shutdownIfIdle', undefined)).resolves.toEqual({ retiring: true })
+    expect(dispose).not.toHaveBeenCalled()
+    client.disconnect()
+
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+    expect(dispose).toHaveBeenCalledOnce()
+  })
+
+  it('connects and retires a never-used adapter during clean disconnect', async () => {
+    await startServer()
+    const adapter = new DaemonPtyAdapter({ socketPath, tokenPath })
+
+    await adapter.disconnectOnly()
+
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+    expect(clock.pendingCount).toBe(0)
+  })
+
+  it('preserves a live session after clean detach and retires when that session exits', async () => {
+    await startServer()
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+    await client.request('createOrAttach', { sessionId: 'preserved', cols: 80, rows: 24 })
+
+    await expect(client.request('shutdownIfIdle', undefined)).resolves.toEqual({
+      retiring: false
+    })
+    client.disconnect()
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+    subprocess.exit(0)
+
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+    expect(clock.pendingCount).toBe(0)
+  })
+
+  it('rejects clean retirement while create or attach is in flight', async () => {
+    await startServer()
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+    const daemon = server as unknown as { createOrAttachInFlight: number }
+    daemon.createOrAttachInFlight = 1
+
+    await expect(client.request('shutdownIfIdle', undefined)).resolves.toEqual({
+      retiring: false
+    })
+
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+    client.disconnect()
+  })
+
+  it('rejects clean retirement when an unknown transport is connected', async () => {
+    await startServer()
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+    const rawSocket = connect(socketPath)
+    await new Promise<void>((resolve) => rawSocket.once('connect', resolve))
+
+    await expect(client.request('shutdownIfIdle', undefined)).resolves.toEqual({
+      retiring: false
+    })
+    rawSocket.destroy()
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+    client.disconnect()
+  })
+
+  it('rejects clean retirement while another authenticated client is connected', async () => {
+    await startServer()
+    const first = new DaemonClient({ socketPath, tokenPath })
+    const second = new DaemonClient({ socketPath, tokenPath })
+    await Promise.all([first.ensureConnected(), second.ensureConnected()])
+
+    await expect(first.request('shutdownIfIdle', undefined)).resolves.toEqual({
+      retiring: false
+    })
+
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+    first.disconnect()
+    second.disconnect()
+  })
+
+  it("preserves another client's live session when failed adoption disconnects", async () => {
+    await startServer()
+    const adoptingAdapter = new DaemonPtyAdapter({ socketPath, tokenPath })
+    const liveOwner = new DaemonClient({ socketPath, tokenPath })
+    await Promise.all([adoptingAdapter.establishLifecycleLease(), liveOwner.ensureConnected()])
+    await liveOwner.request('createOrAttach', {
+      sessionId: 'owned-by-second-client',
+      cols: 80,
+      rows: 24
+    })
+
+    await adoptingAdapter.disconnectOnly()
+
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+    await expect(liveOwner.request('listSessions', undefined)).resolves.toMatchObject({
+      sessions: [expect.objectContaining({ sessionId: 'owned-by-second-client', isAlive: true })]
+    })
+    subprocess.exit(0)
+    liveOwner.disconnect()
+  })
+
+  it('lets an overlapping raw socket block but not erase empty retirement', async () => {
+    await startServer()
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+    const rawSocket = connect(socketPath)
+    await new Promise<void>((resolve) => rawSocket.once('connect', resolve))
+    client.disconnect()
+
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+
+    rawSocket.destroy()
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+    expect(clock.pendingCount).toBe(0)
+  })
+
+  it('retires after the last authenticated client disconnects with no sessions', async () => {
+    await startServer()
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+    expect(clock.pendingCount).toBe(0)
+
+    client.disconnect()
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+    expect(clock.pendingCount).toBe(0)
+  })
+
+  it('lets a complete reconnect cancel retirement while a live session blocks it', async () => {
+    await startServer()
+    const first = new DaemonClient({ socketPath, tokenPath })
+    await first.ensureConnected()
+    await first.request('createOrAttach', { sessionId: 'reconnected', cols: 80, rows: 24 })
+    first.disconnect()
+    const daemon = server as unknown as { retirementRequested: boolean }
+    await waitFor(() => daemon.retirementRequested)
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+
+    const second = new DaemonClient({ socketPath, tokenPath })
+    await second.ensureConnected()
+    await waitFor(() => !daemon.retirementRequested)
+    subprocess.exit(0)
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+
+    second.disconnect()
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+  })
+
+  it('cancels the initial-adoption timeout before the adapter creates its first terminal', async () => {
+    await startServer()
+    await waitFor(() => clock.pendingCount === 1)
+    clock.advanceBy(50)
+
+    const adopted = new DaemonPtyAdapter({ socketPath, tokenPath })
+    await adopted.establishLifecycleLease()
+    expect(clock.pendingCount).toBe(0)
+
+    clock.advanceBy(100)
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+    await expect(
+      adopted.spawn({
+        sessionId: 'first-after-adoption',
+        cols: 80,
+        rows: 24
+      })
+    ).resolves.toMatchObject({ id: 'first-after-adoption' })
+    subprocess.exit(0)
+    adopted.dispose()
+  })
+
+  it('does not let repeated authenticated control probes extend the startup deadline', async () => {
+    await startServer()
+    const healthControl = connect(socketPath)
+    await new Promise<void>((resolve) => healthControl.once('connect', resolve))
+    healthControl.write(
+      `${JSON.stringify({
+        type: 'hello',
+        version: PROTOCOL_VERSION,
+        token: readFileSync(tokenPath, 'utf8').trim(),
+        clientId: 'startup-health-control',
+        role: 'control'
+      })}\n`
+    )
+    const daemon = server as unknown as { clients: Map<string, unknown> }
+    await waitFor(() => daemon.clients.has('startup-health-control'))
+    clock.advanceBy(1_000)
+    healthControl.destroy()
+
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+  })
+
+  it('does not let a control-only create cancel the initial-adoption timeout', async () => {
+    await startServer()
+    const control = connect(socketPath)
+    await new Promise<void>((resolve) => control.once('connect', resolve))
+    control.write(
+      `${JSON.stringify({
+        type: 'hello',
+        version: PROTOCOL_VERSION,
+        token: readFileSync(tokenPath, 'utf8').trim(),
+        clientId: 'startup-control-create',
+        role: 'control'
+      })}\n`
+    )
+    const daemon = server as unknown as {
+      clients: Map<string, unknown>
+      retirementRequested: boolean
+    }
+    await waitFor(() => daemon.clients.has('startup-control-create'))
+    const response = await requestOnRawSocket(control, {
+      id: 'control-only-create',
+      type: 'createOrAttach',
+      payload: { sessionId: 'must-not-start', cols: 80, rows: 24 }
+    })
+    expect(response.error).toContain('connection is incomplete')
+    expect(daemon.retirementRequested).toBe(false)
+    expect(clock.pendingCount).toBe(0)
+
+    clock.advanceBy(1_000)
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+
+    control.destroy()
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+  })
+
+  it('keeps empty-retirement intent when a control-only client overlaps the last app', async () => {
+    await startServer()
+    const paired = new DaemonClient({ socketPath, tokenPath })
+    await paired.ensureConnected()
+    const incomplete = connect(socketPath)
+    await new Promise<void>((resolve) => incomplete.once('connect', resolve))
+    incomplete.write(
+      `${JSON.stringify({
+        type: 'hello',
+        version: PROTOCOL_VERSION,
+        token: readFileSync(tokenPath, 'utf8').trim(),
+        clientId: 'control-only-overlap',
+        role: 'control'
+      })}\n`
+    )
+    const daemon = server as unknown as {
+      clients: Map<string, unknown>
+      retirementRequested: boolean
+    }
+    await waitFor(() => daemon.clients.has('control-only-overlap'))
+
+    paired.disconnect()
+    await waitFor(() => daemon.retirementRequested)
+    expect(clock.pendingCount).toBe(0)
+    const response = await requestOnRawSocket(incomplete, {
+      id: 'overlap-control-create',
+      type: 'createOrAttach',
+      payload: { sessionId: 'must-not-start', cols: 80, rows: 24 }
+    })
+    expect(response.error).toContain('connection is incomplete')
+    expect(daemon.retirementRequested).toBe(true)
+
+    incomplete.destroy()
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+  })
+
+  it('keeps retirement intent when a same-client replacement never completes its stream', async () => {
+    await startServer()
+    const paired = new DaemonClient({ socketPath, tokenPath })
+    await paired.ensureConnected()
+    const clientId = (paired as unknown as { clientId: string }).clientId
+    const replacementControl = connect(socketPath)
+    await new Promise<void>((resolve) => replacementControl.once('connect', resolve))
+    replacementControl.write(
+      `${JSON.stringify({
+        type: 'hello',
+        version: PROTOCOL_VERSION,
+        token: readFileSync(tokenPath, 'utf8').trim(),
+        clientId,
+        role: 'control'
+      })}\n`
+    )
+    const daemon = server as unknown as {
+      retirementRequested: boolean
+    }
+    await waitFor(() => daemon.retirementRequested)
+    expect(clock.pendingCount).toBe(0)
+
+    replacementControl.destroy()
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+  })
+
+  it('keeps a live session after clients disconnect, then retires on its exit', async () => {
+    await startServer()
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+    await client.request('createOrAttach', { sessionId: 'live', cols: 80, rows: 24 })
+    client.disconnect()
+    const daemon = server as unknown as { retirementRequested: boolean }
+    await waitFor(() => daemon.retirementRequested)
+
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+    expect(clock.pendingCount).toBe(0)
+
+    subprocess.exit(0)
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+  })
+
+  it('uses the direct-construction protocol fixture version for hello compatibility', async () => {
+    await startServer({ protocolVersion: 22 })
+    const client = new DaemonClient({ socketPath, tokenPath, protocolVersion: 22 })
+
+    await expect(client.ensureConnected()).resolves.toBeUndefined()
+    client.disconnect()
+  })
+
+  it('requests clean retirement only for protocol v24 and newer adapters', async () => {
+    await startServer()
+    const current = new DaemonPtyAdapter({ socketPath, tokenPath })
+    await current.listProcesses()
+    const currentClient = (
+      current as unknown as {
+        client: DaemonClient
+      }
+    ).client
+    const currentRequest = vi.spyOn(currentClient, 'request')
+
+    await current.disconnectOnly()
+
+    expect(currentRequest).toHaveBeenCalledOnce()
+    expect(currentRequest.mock.calls[0]?.slice(0, 2)).toEqual(['shutdownIfIdle', undefined])
+    const timeoutMs = currentRequest.mock.calls[0]?.[2]
+    // Why: connection and RPC share a wall-clock budget, so elapsed setup time is expected.
+    expect(timeoutMs).toEqual(expect.any(Number))
+    expect(timeoutMs).toBeGreaterThan(0)
+    expect(timeoutMs).toBeLessThanOrEqual(250)
+  })
+
+  it('does not send the v24 clean-disconnect RPC to a legacy daemon', async () => {
+    await startServer({ protocolVersion: 23 })
+    const legacy = new DaemonPtyAdapter({ socketPath, tokenPath, protocolVersion: 23 })
+    await legacy.listProcesses()
+    const legacyClient = (
+      legacy as unknown as {
+        client: DaemonClient
+      }
+    ).client
+    const legacyRequest = vi.spyOn(legacyClient, 'request')
+
+    await legacy.disconnectOnly()
+
+    expect(legacyRequest.mock.calls.map(([type]) => type)).not.toContain('shutdownIfIdle')
+  })
+
+  it('rejects create or attach once the idle admission fence is pending', async () => {
+    await startServer()
+    const daemon = server as unknown as {
+      idleShutdownState: string
+      routeRequest(clientId: string, request: unknown): Promise<unknown>
+    }
+    daemon.idleShutdownState = 'idle-shutdown-pending'
+
+    await expect(
+      daemon.routeRequest('late-client', {
+        id: 'late-create',
+        type: 'createOrAttach',
+        payload: { sessionId: 'late', cols: 80, rows: 24 }
+      })
+    ).rejects.toThrow('temporarily unavailable; reconnect')
+  })
+
+  it('aborts the pending shutdown when create or attach started before the fence', async () => {
+    await startServer()
+    const daemon = server as unknown as {
+      createOrAttachInFlight: number
+      idleShutdownState: string
+      beginIdleShutdown(): void
+    }
+    daemon.createOrAttachInFlight = 1
+
+    daemon.beginIdleShutdown()
+
+    expect(daemon.idleShutdownState).toBe('running')
+    expect(onIdleShutdown).not.toHaveBeenCalled()
+  })
+
+  it('explicitly marks a post-fence accepted transport as retryable', async () => {
+    await startServer()
+    const daemon = server as unknown as {
+      idleShutdownState: string
+      handleConnection(socket: Socket): void
+    }
+    daemon.idleShutdownState = 'idle-shutdown-pending'
+    const socket = new EventEmitter() as Socket
+    socket.end = vi.fn() as unknown as Socket['end']
+
+    daemon.handleConnection(socket)
+
+    const payload = vi.mocked(socket.end).mock.calls[0]?.[0]
+    expect(JSON.parse(String(payload))).toMatchObject({ ok: false, retryable: true })
+    socket.emit('close')
+  })
+
+  it('preserves a replacement PID record during otherwise successful idle cleanup', async () => {
+    writeFileSync(
+      pidPath,
+      serializeDaemonPidFile({ pid: process.pid, startedAtMs: null, launchNonce: 'replacement' })
+    )
+    await startServer({ launchNonce: 'mine' })
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+
+    await client.request('shutdownIfIdle', undefined)
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+
+    expect(JSON.parse(readFileSync(pidPath, 'utf8'))).toMatchObject({
+      pid: process.pid,
+      launchNonce: 'replacement'
+    })
+  })
+
+  it('preserves a token file replaced before idle cleanup', async () => {
+    await startServer()
+    const client = new DaemonClient({ socketPath, tokenPath })
+    await client.ensureConnected()
+    writeFileSync(tokenPath, 'replacement-token')
+
+    await client.request('shutdownIfIdle', undefined)
+    await waitFor(() => onIdleShutdown.mock.calls.length === 1)
+
+    expect(readFileSync(tokenPath, 'utf8')).toBe('replacement-token')
+  })
+})
+
+describe('daemon PID record ownership cleanup', () => {
+  let dir: string
+  let pidPath: string
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'daemon-pid-ownership-'))
+    pidPath = join(dir, 'daemon.pid')
+  })
+
+  afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+  it('unlinks only an exact PID and launch nonce match', () => {
+    writeFileSync(
+      pidPath,
+      serializeDaemonPidFile({ pid: 123, startedAtMs: null, launchNonce: 'mine' })
+    )
+
+    expect(unlinkOwnedDaemonPidFile(pidPath, 123, 'mine')).toBe(true)
+    expect(existsSync(pidPath)).toBe(false)
+  })
+
+  it.each([
+    ['malformed', '{'],
+    ['stale PID', serializeDaemonPidFile({ pid: 456, startedAtMs: null, launchNonce: 'mine' })],
+    [
+      'replacement nonce',
+      serializeDaemonPidFile({ pid: 123, startedAtMs: null, launchNonce: 'new' })
+    ]
+  ])('preserves a %s record', (_label, contents) => {
+    writeFileSync(pidPath, contents)
+
+    expect(unlinkOwnedDaemonPidFile(pidPath, 123, 'mine')).toBe(false)
+    expect(readFileSync(pidPath, 'utf8')).toBe(contents)
+  })
+
+  it('leaves a missing record missing', () => {
+    expect(unlinkOwnedDaemonPidFile(pidPath, 123, 'mine')).toBe(false)
+    expect(existsSync(pidPath)).toBe(false)
+  })
+})
diff --git a/src/main/daemon/daemon-init.test.ts b/src/main/daemon/daemon-init.test.ts
index 89493f675bf..9bc78a4da75 100644
--- a/src/main/daemon/daemon-init.test.ts
+++ b/src/main/daemon/daemon-init.test.ts
@@ -38,11 +38,17 @@ const {
   killStaleDaemonMock,
   getProcessStartedAtMsMock,
   parseDaemonPidFileMock,
+  unlinkOwnedDaemonPidFileMock,
   daemonClientMock,
   spawnerInstances,
   ensureRunningOverrides,
+  adoptionLeaseReleases,
+  lifecycleLeaseErrors,
+  disconnectOnlyErrors,
+  routerSubscriptionError,
   adapterInstances,
   defaultListSessionsSessions,
+  listProcessesControl,
   getLocalPtyProviderMock,
   localFallbackProvider,
   setLocalPtyProviderMock,
@@ -98,6 +104,7 @@ const {
   const parseDaemonPidFileMock = vi.fn(
     (): { pid: number; startedAtMs: number | null } | null => null
   )
+  const unlinkOwnedDaemonPidFileMock = vi.fn(() => true)
 
   const daemonClientMock = vi.fn().mockImplementation(function MockDaemonClient() {
     return {
@@ -115,12 +122,19 @@ const {
     tokenPath: string
     mode?: 'degraded-new-pty-fallback'
   }>)[] = []
+  const adoptionLeaseReleases: ReturnType<typeof vi.fn>[] = []
+  const lifecycleLeaseErrors: Error[] = []
+  const disconnectOnlyErrors: Error[] = []
+  const routerSubscriptionError: { current: Error | null } = { current: null }
   // Same for DaemonPtyAdapter. The test asserts the replacement adapter is a
   // fresh instance whose respawn closure targets the *original* spawner.
   const adapterInstances: MockAdapter[] = []
   // Why: adapters are constructed inside initDaemonPtyProvider, so tests that
   // need listSessions to report live sessions set this before calling init.
   const defaultListSessionsSessions: { sessionId: string }[] = []
+  const listProcessesControl: {
+    current: null | (() => Promise<{ sessionId: string }[]>)
+  } = { current: null }
 
   const localFallbackProvider = {
     routesFreshSpawnsToLocalProvider: undefined,
@@ -171,11 +185,17 @@ const {
     killStaleDaemonMock,
     getProcessStartedAtMsMock,
     parseDaemonPidFileMock,
+    unlinkOwnedDaemonPidFileMock,
     daemonClientMock,
     spawnerInstances,
     ensureRunningOverrides,
+    adoptionLeaseReleases,
+    lifecycleLeaseErrors,
+    disconnectOnlyErrors,
+    routerSubscriptionError,
     adapterInstances,
     defaultListSessionsSessions,
+    listProcessesControl,
     getLocalPtyProviderMock,
     localFallbackProvider,
     setLocalPtyProviderMock,
@@ -205,6 +225,7 @@ type MockAdapter = {
   fanoutSyntheticExits: ReturnType<typeof vi.fn>
   listProcesses: ReturnType<typeof vi.fn>
   listSessions: ReturnType<typeof vi.fn>
+  establishLifecycleLease: ReturnType<typeof vi.fn>
   shutdown: ReturnType<typeof vi.fn>
   dispose: ReturnType<typeof vi.fn>
   disconnectOnly: ReturnType<typeof vi.fn>
@@ -261,7 +282,11 @@ vi.mock('./daemon-spawner', () => ({
     readonly shutdown: ReturnType<typeof vi.fn>
     readonly getHandle: ReturnType<typeof vi.fn>
     private socketCounter: number
-    private handle: { mode?: 'degraded-new-pty-fallback'; shutdown: () => Promise<void> } | null
+    private handle: {
+      mode?: 'degraded-new-pty-fallback'
+      releaseAdoptionLease?: () => void
+      shutdown: () => Promise<void>
+    } | null
     constructor(opts: { runtimeDir: string; launcher: unknown }) {
       this.launcher = opts.launcher
       this.socketCounter = 0
@@ -273,7 +298,9 @@ vi.mock('./daemon-spawner', () => ({
         const override = ensureRunningOverrides.shift()
         if (override) {
           const result = await override()
-          this.handle = { shutdown: vi.fn(async () => {}) }
+          const releaseAdoptionLease = vi.fn()
+          adoptionLeaseReleases.push(releaseAdoptionLease)
+          this.handle = { releaseAdoptionLease, shutdown: vi.fn(async () => {}) }
           if (result.mode) {
             this.handle.mode = result.mode
           }
@@ -283,7 +310,9 @@ vi.mock('./daemon-spawner', () => ({
           }
         }
         this.socketCounter += 1
-        this.handle = { shutdown: vi.fn(async () => {}) }
+        const releaseAdoptionLease = vi.fn()
+        adoptionLeaseReleases.push(releaseAdoptionLease)
+        this.handle = { releaseAdoptionLease, shutdown: vi.fn(async () => {}) }
         return {
           socketPath: `/fake/socket-${this.socketCounter}`,
           tokenPath: `/fake/token-${this.socketCounter}`
@@ -301,7 +330,8 @@ vi.mock('./daemon-spawner', () => ({
     `/fake/daemon/daemon-v${version ?? PROTOCOL_VERSION}.token`,
   getDaemonPidPath: (_dir: string, version?: number) =>
     `/fake/daemon/daemon-v${version ?? PROTOCOL_VERSION}.pid`,
-  serializeDaemonPidFile: (obj: unknown) => JSON.stringify(obj)
+  serializeDaemonPidFile: (obj: unknown) => JSON.stringify(obj),
+  unlinkOwnedDaemonPidFile: unlinkOwnedDaemonPidFileMock
 }))
 
 vi.mock('./daemon-pty-adapter', () => ({
@@ -312,6 +342,7 @@ vi.mock('./daemon-pty-adapter', () => ({
     readonly fanoutSyntheticExits: ReturnType<typeof vi.fn>
     readonly listProcesses: ReturnType<typeof vi.fn>
     readonly listSessions: ReturnType<typeof vi.fn>
+    readonly establishLifecycleLease: ReturnType<typeof vi.fn>
     readonly shutdown: ReturnType<typeof vi.fn>
     readonly dispose: ReturnType<typeof vi.fn>
     readonly disconnectOnly: ReturnType<typeof vi.fn>
@@ -326,12 +357,32 @@ vi.mock('./daemon-pty-adapter', () => ({
       this.fanoutSyntheticExits = vi.fn(() => {
         this.callOrder.push('fanoutSyntheticExits')
       })
-      this.listProcesses = vi.fn(async () => [])
+      this.listProcesses = vi.fn(async () =>
+        listProcessesControl.current ? listProcessesControl.current() : []
+      )
       this.listSessions = vi.fn(async () => [...defaultListSessionsSessions])
+      const lifecycleLeaseError = lifecycleLeaseErrors.shift()
+      this.establishLifecycleLease = vi.fn(async () => {
+        if (lifecycleLeaseError) {
+          throw lifecycleLeaseError
+        }
+      })
       this.shutdown = vi.fn(async () => {})
       this.dispose = vi.fn()
-      this.disconnectOnly = vi.fn(async () => {})
-      this.onData = vi.fn(() => () => {})
+      const disconnectOnlyError = disconnectOnlyErrors.shift()
+      this.disconnectOnly = vi.fn(async () => {
+        if (disconnectOnlyError) {
+          throw disconnectOnlyError
+        }
+      })
+      this.onData = vi.fn(() => {
+        if (routerSubscriptionError.current) {
+          const error = routerSubscriptionError.current
+          routerSubscriptionError.current = null
+          throw error
+        }
+        return () => {}
+      })
       this.onExit = vi.fn(() => () => {})
       adapterInstances.push(this as unknown as MockAdapter)
     }
@@ -349,8 +400,13 @@ async function importFresh() {
   vi.resetModules()
   spawnerInstances.length = 0
   ensureRunningOverrides.length = 0
+  adoptionLeaseReleases.length = 0
+  lifecycleLeaseErrors.length = 0
+  disconnectOnlyErrors.length = 0
+  routerSubscriptionError.current = null
   adapterInstances.length = 0
   defaultListSessionsSessions.length = 0
+  listProcessesControl.current = null
   getLocalPtyProviderMock.mockClear()
   localFallbackProvider.spawn.mockClear()
   localFallbackProvider.write.mockClear()
@@ -374,7 +430,14 @@ async function importFresh() {
   forkMock.mockReset()
   isPackagedMock.mockReset()
   isPackagedMock.mockReturnValue(false)
-  daemonClientMock.mockClear()
+  daemonClientMock.mockReset()
+  daemonClientMock.mockImplementation(function MockDaemonClient() {
+    return {
+      ensureConnected: vi.fn(async () => {}),
+      request: vi.fn(async () => ({ sessions: [] })),
+      disconnect: vi.fn()
+    }
+  })
   probeSocketExistsMock.mockClear()
   writeFileSyncMock.mockClear()
   readFileSyncMock.mockReset()
@@ -384,6 +447,8 @@ async function importFresh() {
   unlinkSyncMock.mockClear()
   parseDaemonPidFileMock.mockReset()
   parseDaemonPidFileMock.mockReturnValue(null)
+  unlinkOwnedDaemonPidFileMock.mockReset()
+  unlinkOwnedDaemonPidFileMock.mockReturnValue(true)
   getProcessStartedAtMsMock.mockReset()
   getProcessStartedAtMsMock.mockReturnValue(1_000_000)
   // Why: importing daemon-init *after* resetModules means the module-level
@@ -393,6 +458,16 @@ async function importFresh() {
   return import('./daemon-init')
 }
 
+function mockConnectedAdoptionClientOnce(): void {
+  daemonClientMock.mockImplementationOnce(function MockAdoptionClient() {
+    return {
+      ensureConnected: vi.fn(async () => {}),
+      request: vi.fn(),
+      disconnect: vi.fn()
+    }
+  })
+}
+
 describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
   beforeEach(() => {
     probeSocketExistsMock.mockReturnValue(false)
@@ -429,6 +504,50 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     expect(rebindLocalProviderListenersMock.mock.invocationCallOrder[0]).toBeGreaterThan(
       setLocalPtyProviderMock.mock.invocationCallOrder[0]
     )
+    expect(adapterInstances[0].establishLifecycleLease).toHaveBeenCalledOnce()
+    expect(adapterInstances[0].establishLifecycleLease.mock.invocationCallOrder[0]).toBeLessThan(
+      setLocalPtyProviderMock.mock.invocationCallOrder[0]
+    )
+    expect(adoptionLeaseReleases[0]).toHaveBeenCalledOnce()
+    expect(adapterInstances[0].establishLifecycleLease.mock.invocationCallOrder[0]).toBeLessThan(
+      adoptionLeaseReleases[0].mock.invocationCallOrder[0]
+    )
+  })
+
+  it('uses daemon-owned idle retirement when a fresh launch fails permanent adoption', async () => {
+    const mod = await importFresh()
+    ensureRunningOverrides.push(async () => ({
+      socketPath: '/fake/launched-socket',
+      tokenPath: '/fake/launched-token'
+    }))
+    lifecycleLeaseErrors.push(new Error('lease identity mismatch'))
+
+    await expect(mod.initDaemonPtyProvider()).rejects.toThrow('lease identity mismatch')
+
+    expect(adoptionLeaseReleases[0]).toHaveBeenCalledOnce()
+    expect(adapterInstances[0].disconnectOnly).toHaveBeenCalledOnce()
+    expect(adapterInstances[0].dispose).not.toHaveBeenCalled()
+    expect(spawnerInstances[0].shutdown).not.toHaveBeenCalled()
+    expect(adapterInstances[0].establishLifecycleLease.mock.invocationCallOrder[0]).toBeLessThan(
+      adoptionLeaseReleases[0].mock.invocationCallOrder[0]
+    )
+    expect(setLocalPtyProviderMock).not.toHaveBeenCalled()
+  })
+
+  it('does not kill a preserved daemon when startup lease acquisition fails', async () => {
+    const mod = await importFresh()
+    ensureRunningOverrides.push(async () => ({
+      socketPath: '/fake/preserved-socket',
+      tokenPath: '/fake/preserved-token'
+    }))
+    lifecycleLeaseErrors.push(new Error('preserved lease failed'))
+
+    await expect(mod.initDaemonPtyProvider()).rejects.toThrow('preserved lease failed')
+
+    expect(adoptionLeaseReleases[0]).toHaveBeenCalledOnce()
+    expect(adapterInstances[0].disconnectOnly).toHaveBeenCalledOnce()
+    expect(spawnerInstances[0].shutdown).not.toHaveBeenCalled()
+    expect(setLocalPtyProviderMock).not.toHaveBeenCalled()
   })
 
   it('prunes seeded Claude live-PTY ids against daemon sessions after init', async () => {
@@ -474,12 +593,100 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     resolveEnsureRunning({ socketPath: '/fake/socket-late', tokenPath: '/fake/token-late' })
     await started
 
-    expect(adapterInstances).toHaveLength(0)
+    expect(adapterInstances).toHaveLength(1)
+    expect(adapterInstances[0].disconnectOnly).toHaveBeenCalledOnce()
+    expect(adapterInstances[0].establishLifecycleLease).not.toHaveBeenCalled()
     expect(setLocalPtyProviderMock).not.toHaveBeenCalled()
     expect(rebindLocalProviderListenersMock).not.toHaveBeenCalled()
     expect(mod.getDaemonProvider()).toBeNull()
   })
 
+  it('disconnects uninstalled adapter leases when startup aborts during legacy discovery', async () => {
+    const mod = await importFresh()
+    probeSocketExistsMock.mockImplementation((p?: string) => p?.endsWith('daemon-v9.sock') ?? false)
+    netConnectMock.mockImplementation(() => {
+      const handlers: Record<string, (() => void)[]> = { connect: [], error: [] }
+      return {
+        on(event: string, cb: () => void) {
+          handlers[event]?.push(cb)
+          if (event === 'connect') {
+            queueMicrotask(() => cb())
+          }
+          return this
+        },
+        removeListener(event: string, cb: () => void) {
+          handlers[event] = handlers[event]?.filter((handler) => handler !== cb) ?? []
+          return this
+        },
+        destroy() {}
+      }
+    })
+    let resolveDiscovery!: (sessions: { sessionId: string }[]) => void
+    const discovery = new Promise<{ sessionId: string }[]>((resolve) => {
+      resolveDiscovery = resolve
+    })
+    listProcessesControl.current = () => discovery
+    const abortController = new AbortController()
+
+    const started = mod.initDaemonPtyProvider(abortController.signal)
+    await vi.waitFor(() => {
+      expect(adapterInstances.some((instance) => instance.protocolVersion === 9)).toBe(true)
+      expect(
+        adapterInstances.some((instance) => instance.listProcesses.mock.calls.length > 0)
+      ).toBe(true)
+    })
+    abortController.abort()
+    resolveDiscovery([])
+    await started
+
+    expect(adapterInstances).toHaveLength(2)
+    expect(adapterInstances[0].disconnectOnly).toHaveBeenCalledOnce()
+    expect(adapterInstances[1].disconnectOnly).toHaveBeenCalledOnce()
+    expect(setLocalPtyProviderMock).not.toHaveBeenCalled()
+    expect(mod.getDaemonProvider()).toBeNull()
+  })
+
+  it('retains every adapter cleanup failure when legacy router setup aborts', async () => {
+    const mod = await importFresh()
+    probeSocketExistsMock.mockImplementation(
+      (path?: string) => path?.endsWith('daemon-v9.sock') ?? false
+    )
+    netConnectMock.mockImplementation(() => {
+      const handlers: Record<string, (() => void)[]> = { connect: [], error: [] }
+      return {
+        on(event: string, callback: () => void) {
+          handlers[event]?.push(callback)
+          if (event === 'connect') {
+            queueMicrotask(() => callback())
+          }
+          return this
+        },
+        removeListener(event: string, callback: () => void) {
+          handlers[event] = handlers[event]?.filter((handler) => handler !== callback) ?? []
+          return this
+        },
+        destroy() {}
+      }
+    })
+    const discoveryError = new Error('router subscription failed')
+    const currentCleanupError = new Error('current cleanup failed')
+    const legacyCleanupError = new Error('legacy cleanup failed')
+    routerSubscriptionError.current = discoveryError
+    disconnectOnlyErrors.push(currentCleanupError, legacyCleanupError)
+
+    const error = await mod.initDaemonPtyProvider().catch((caught: unknown) => caught)
+    expect(error).toBeInstanceOf(AggregateError)
+    const topLevelErrors = (error as AggregateError).errors
+    expect(topLevelErrors[0]).toBe(discoveryError)
+    expect(topLevelErrors[1]).toBeInstanceOf(AggregateError)
+    expect((topLevelErrors[1] as AggregateError).errors).toEqual([
+      legacyCleanupError,
+      currentCleanupError
+    ])
+    expect(adapterInstances[0].disconnectOnly).toHaveBeenCalledOnce()
+    expect(adapterInstances[1].disconnectOnly).toHaveBeenCalledOnce()
+  })
+
   it('routes fresh PTYs to the local fallback when a preserved daemon cannot spawn new PTYs', async () => {
     const mod = await importFresh()
     ensureRunningOverrides.push(async () => ({
@@ -537,6 +744,26 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     expect(order).toEqual(['fanout', 'unbind'])
   })
 
+  it('uses daemon-owned idle retirement after a failed manual-restart adoption', async () => {
+    const mod = await importFresh()
+    await mod.initDaemonPtyProvider()
+    const originalProvider = mod.getDaemonProvider()
+    ensureRunningOverrides.push(async () => ({
+      socketPath: '/fake/restart-failure-socket',
+      tokenPath: '/fake/restart-failure-token'
+    }))
+    lifecycleLeaseErrors.push(new Error('restart lease failed'))
+
+    await expect(mod.restartDaemon()).rejects.toThrow('restart lease failed')
+
+    expect(adoptionLeaseReleases[1]).toHaveBeenCalledOnce()
+    expect(adapterInstances[1].disconnectOnly).toHaveBeenCalledOnce()
+    expect(spawnerInstances[0].shutdown).not.toHaveBeenCalled()
+    expect(mod.getDaemonProvider()).toBe(originalProvider)
+    expect(unbindLocalProviderListenersMock).toHaveBeenCalledOnce()
+    expect(rebindLocalProviderListenersMock).toHaveBeenCalledTimes(2)
+  })
+
   it('fans exits for preserved degraded current-daemon sessions during restart', async () => {
     const mod = await importFresh()
     ensureRunningOverrides.push(async () => ({
@@ -801,6 +1028,10 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     // result, so its existence proves the ordering.
     expect(adapterInstances).toHaveLength(2)
     expect(adapterInstances[1].options.socketPath).toBe('/fake/socket-2')
+    expect(adapterInstances[1].establishLifecycleLease).toHaveBeenCalledOnce()
+    expect(adapterInstances[1].establishLifecycleLease.mock.invocationCallOrder[0]).toBeLessThan(
+      setLocalPtyProviderMock.mock.invocationCallOrder.at(-1) as number
+    )
   })
 
   it('exercises the alive-daemon cleanup path: issues shutdown RPC via DaemonClient before spawning a replacement', async () => {
@@ -820,9 +1051,8 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     })
     const ensureConnectedMock = vi.fn(async () => {})
     const disconnectMock = vi.fn()
-    // Why: DaemonClient is invoked via `new DaemonClient(...)`, so the mock
-    // factory must return a constructor-compatible function. Capture the
-    // existing impl so later tests aren't affected.
+    const mod = await importFresh()
+    await mod.initDaemonPtyProvider()
     daemonClientMock.mockImplementationOnce(function MockDaemonClientForShutdown() {
       return {
         ensureConnected: ensureConnectedMock,
@@ -831,9 +1061,6 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       }
     })
 
-    const mod = await importFresh()
-    await mod.initDaemonPtyProvider()
-
     // Make probeSocket return true for the current-version path by toggling
     // both the fs.existsSync proxy AND net.connect resolving "alive".
     probeSocketExistsMock.mockReturnValue(true)
@@ -996,7 +1223,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
         on(event: string, cb: (arg?: unknown) => void) {
           handlers[event]?.push(cb)
           if (event === 'message') {
-            queueMicrotask(() => cb({ type: 'ready' }))
+            queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
           }
           return this
         },
@@ -1036,6 +1263,79 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     )
   })
 
+  it('holds a full adoption pair before a healthy launcher resolves', async () => {
+    const mod = await importFresh()
+    await mod.initDaemonPtyProvider()
+    const events: string[] = []
+    const disconnect = vi.fn()
+    daemonClientMock.mockImplementationOnce(function MockAdoptionClient() {
+      return {
+        ensureConnected: vi.fn(async () => {
+          events.push('full-pair')
+        }),
+        request: vi.fn(),
+        disconnect
+      }
+    })
+    checkDaemonHealthMock.mockImplementationOnce(async () => {
+      events.push('health')
+      return 'healthy'
+    })
+    const launcher = spawnerInstances[0].launcher as (
+      socketPath: string,
+      tokenPath: string
+    ) => Promise<{
+      releaseAdoptionLease?(): void
+      shutdown(): Promise<void>
+    }>
+
+    const handle = await launcher('/fake/socket', '/fake/token')
+
+    expect(events[0]).toBe('full-pair')
+    expect(events.indexOf('full-pair')).toBeLessThan(events.indexOf('health'))
+    expect(disconnect).not.toHaveBeenCalled()
+    handle.releaseAdoptionLease?.()
+    expect(disconnect).toHaveBeenCalledOnce()
+  })
+
+  it('disconnects every temporary client when healthy adoption fails', async () => {
+    const mod = await importFresh()
+    await mod.initDaemonPtyProvider()
+    const initialDisconnect = vi.fn()
+    const replacementDisconnect = vi.fn()
+    daemonClientMock
+      .mockImplementationOnce(function MockInitialAdoptionClient() {
+        return {
+          ensureConnected: vi.fn(async () => {
+            throw new Error('initial adoption failed')
+          }),
+          request: vi.fn(),
+          disconnect: initialDisconnect
+        }
+      })
+      .mockImplementationOnce(function MockReplacementAdoptionClient() {
+        return {
+          ensureConnected: vi.fn(async () => {
+            throw new Error('replacement adoption failed')
+          }),
+          request: vi.fn(),
+          disconnect: replacementDisconnect
+        }
+      })
+    const launcher = spawnerInstances[0].launcher as (
+      socketPath: string,
+      tokenPath: string
+    ) => Promise<{ shutdown(): Promise<void> }>
+
+    await expect(launcher('/fake/socket', '/fake/token')).rejects.toThrow(
+      'replacement adoption failed'
+    )
+
+    expect(initialDisconnect).toHaveBeenCalledOnce()
+    expect(replacementDisconnect).toHaveBeenCalledOnce()
+    expect(forkMock).not.toHaveBeenCalled()
+  })
+
   it('preserves a daemon launched from another app path when it owns live sessions', async () => {
     const mod = await importFresh()
     await mod.initDaemonPtyProvider()
@@ -1052,6 +1352,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       return {}
     })
     const disconnectMock = vi.fn()
+    mockConnectedAdoptionClientOnce()
     daemonClientMock.mockImplementationOnce(function MockDaemonClient() {
       return {
         ensureConnected: vi.fn(async () => {}),
@@ -1091,6 +1392,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       return {}
     })
     const disconnectMock = vi.fn()
+    mockConnectedAdoptionClientOnce()
     daemonClientMock.mockImplementationOnce(function MockDaemonClient() {
       return {
         ensureConnected: vi.fn(async () => {}),
@@ -1133,7 +1435,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
         on(event: string, cb: (arg?: unknown) => void) {
           handlers[event]?.push(cb)
           if (event === 'message') {
-            queueMicrotask(() => cb({ type: 'ready' }))
+            queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
           }
           return this
         },
@@ -1185,6 +1487,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       return {}
     })
     const disconnectMock = vi.fn()
+    mockConnectedAdoptionClientOnce()
     daemonClientMock.mockImplementationOnce(function MockDaemonClient() {
       return {
         ensureConnected: vi.fn(async () => {}),
@@ -1220,6 +1523,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       return {}
     })
     const disconnectMock = vi.fn()
+    mockConnectedAdoptionClientOnce()
     daemonClientMock.mockImplementationOnce(function MockDaemonClient() {
       return {
         ensureConnected: vi.fn(async () => {}),
@@ -1264,7 +1568,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
         on(event: string, cb: (arg?: unknown) => void) {
           handlers[event]?.push(cb)
           if (event === 'message') {
-            queueMicrotask(() => cb({ type: 'ready' }))
+            queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
           }
           return this
         },
@@ -1316,7 +1620,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       on(event: string, cb: (arg?: unknown) => void) {
         handlers[event]?.push(cb)
         if (event === 'message') {
-          queueMicrotask(() => cb({ type: 'ready' }))
+          queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
         }
         return this
       },
@@ -1336,16 +1640,355 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     expect(handlers.exit).toHaveLength(0)
     expect(child.disconnect).toHaveBeenCalledOnce()
     expect(child.unref).toHaveBeenCalledOnce()
-    expect(writeFileSyncMock).toHaveBeenCalledWith(
-      `/fake/daemon/daemon-v${PROTOCOL_VERSION}.pid`,
-      JSON.stringify({
-        pid: 12345,
-        startedAtMs: 1_000_000,
-        entryPath: FAKE_DAEMON_ENTRY_PATH,
-        appVersion: '1.2.3'
-      }),
-      { mode: 0o600 }
+    const [pidPath, pidContents, pidOptions] = writeFileSyncMock.mock.calls.at(-1) ?? []
+    expect(pidPath).toBe(`/fake/daemon/daemon-v${PROTOCOL_VERSION}.pid`)
+    expect(JSON.parse(pidContents as string)).toEqual({
+      pid: 12345,
+      startedAtMs: 1_000_000,
+      entryPath: FAKE_DAEMON_ENTRY_PATH,
+      appVersion: '1.2.3',
+      launchNonce: expect.stringMatching(/^[0-9a-f-]{36}$/)
+    })
+    expect(pidOptions).toEqual({ mode: 0o600, flag: 'wx' })
+    const launchArgs = forkMock.mock.calls.at(-1)?.[1] as string[]
+    const launchNonceIndex = launchArgs.indexOf('--launch-nonce')
+    expect(launchArgs).toEqual(
+      expect.arrayContaining([
+        '--pid-record',
+        `/fake/daemon/daemon-v${PROTOCOL_VERSION}.pid`,
+        '--launch-nonce'
+      ])
     )
+    expect(launchArgs[launchNonceIndex + 1]).toBe(JSON.parse(pidContents as string).launchNonce)
+  })
+
+  it('keeps a live PID record after adoption failure and removes it on exact child exit', async () => {
+    const mod = await importFresh()
+    checkDaemonHealthMock.mockResolvedValue('unreachable')
+    await mod.initDaemonPtyProvider()
+    const adoptionDisconnects: ReturnType<typeof vi.fn>[] = []
+    function MockFailingAdoptionClient() {
+      const disconnect = vi.fn()
+      adoptionDisconnects.push(disconnect)
+      return {
+        ensureConnected: vi.fn(async () => {
+          throw new Error('adoption unavailable')
+        }),
+        request: vi.fn(),
+        disconnect
+      }
+    }
+    for (let index = 0; index < 3; index++) {
+      daemonClientMock.mockImplementationOnce(MockFailingAdoptionClient)
+    }
+    const handlers: Record<string, ((arg?: unknown) => void)[]> = {
+      message: [],
+      error: [],
+      exit: []
+    }
+    const child = {
+      pid: 12345,
+      connected: true,
+      exitCode: null as number | null,
+      signalCode: null as NodeJS.Signals | null,
+      on(event: string, callback: (arg?: unknown) => void) {
+        handlers[event]?.push(callback)
+        if (event === 'message') {
+          queueMicrotask(() => callback({ type: 'ready', startedAtMs: 1_000_000 }))
+        }
+        return this
+      },
+      once(event: string, callback: (arg?: unknown) => void) {
+        handlers[event]?.push(callback)
+        return this
+      },
+      off(event: string, callback: (arg?: unknown) => void) {
+        handlers[event] = handlers[event]?.filter((handler) => handler !== callback) ?? []
+        return this
+      },
+      disconnect: vi.fn(() => {
+        child.connected = false
+      }),
+      unref: vi.fn()
+    }
+    forkMock.mockReturnValueOnce(child)
+    const launcher = spawnerInstances[0].launcher as (
+      socketPath: string,
+      tokenPath: string,
+      pidPath?: string,
+      launchNonce?: string
+    ) => Promise<{ shutdown(): Promise<void> }>
+
+    await expect(
+      launcher('/fake/socket', '/fake/token', '/fake/daemon.pid', 'launch-delayed')
+    ).rejects.toThrow('adoption unavailable')
+
+    expect(writeFileSyncMock).toHaveBeenCalledWith(
+      '/fake/daemon.pid',
+      expect.stringContaining('launch-delayed'),
+      { mode: 0o600, flag: 'wx' }
+    )
+    expect(unlinkOwnedDaemonPidFileMock).not.toHaveBeenCalled()
+    expect(adoptionDisconnects.at(-1)).toHaveBeenCalledOnce()
+
+    child.exitCode = 0
+    for (const callback of handlers.exit.slice()) {
+      callback(0)
+    }
+    expect(unlinkOwnedDaemonPidFileMock).toHaveBeenCalledWith(
+      '/fake/daemon.pid',
+      12345,
+      'launch-delayed'
+    )
+  })
+
+  it('kills and rejects a daemon whose readiness message omits its start time', async () => {
+    const mod = await importFresh()
+    checkDaemonHealthMock.mockResolvedValue('unreachable')
+    await mod.initDaemonPtyProvider()
+
+    const launcher = spawnerInstances[0].launcher as (
+      socketPath: string,
+      tokenPath: string
+    ) => Promise<{ shutdown(): Promise<void> }>
+    const kill = vi.spyOn(process, 'kill').mockImplementation(() => {
+      throw Object.assign(new Error('already exited'), { code: 'ESRCH' })
+    })
+    const child = {
+      pid: 12345,
+      on(event: string, cb: (arg?: unknown) => void) {
+        if (event === 'message') {
+          queueMicrotask(() => cb({ type: 'ready' }))
+        }
+        return this
+      },
+      off: vi.fn(),
+      disconnect: vi.fn(),
+      unref: vi.fn()
+    }
+    forkMock.mockReturnValueOnce(child)
+
+    try {
+      await expect(launcher('/fake/socket', '/fake/token')).rejects.toThrow(
+        'Daemon readiness identity is incomplete'
+      )
+      expect(kill).toHaveBeenCalledWith(12345, 'SIGTERM')
+      expect(writeFileSyncMock).not.toHaveBeenCalled()
+      expect(child.disconnect).not.toHaveBeenCalled()
+      expect(child.unref).toHaveBeenCalledOnce()
+    } finally {
+      kill.mockRestore()
+    }
+  })
+
+  it('rejects startup cleanup when SIGKILL never produces child exit', async () => {
+    vi.useFakeTimers()
+    const kill = vi.spyOn(process, 'kill').mockReturnValue(true)
+    try {
+      const mod = await importFresh()
+      checkDaemonHealthMock.mockResolvedValue('unreachable')
+      await mod.initDaemonPtyProvider()
+      const handlers: Record<string, ((arg?: unknown) => void)[]> = {
+        message: [],
+        error: [],
+        exit: []
+      }
+      const child = {
+        pid: 12345,
+        connected: true,
+        exitCode: null,
+        signalCode: null,
+        on(event: string, callback: (arg?: unknown) => void) {
+          handlers[event]?.push(callback)
+          if (event === 'message') {
+            queueMicrotask(() => callback({ type: 'ready' }))
+          }
+          return this
+        },
+        off(event: string, callback: (arg?: unknown) => void) {
+          handlers[event] = handlers[event]?.filter((handler) => handler !== callback) ?? []
+          return this
+        },
+        disconnect: vi.fn(() => {
+          child.connected = false
+        }),
+        unref: vi.fn()
+      }
+      forkMock.mockReturnValueOnce(child)
+      const launcher = spawnerInstances[0].launcher as (
+        socketPath: string,
+        tokenPath: string
+      ) => Promise<{ shutdown(): Promise<void> }>
+
+      const launch = launcher('/fake/socket', '/fake/token')
+      await Promise.resolve()
+      await Promise.resolve()
+      const rejection = expect(launch).rejects.toThrow('startup and child cleanup both failed')
+      await vi.advanceTimersByTimeAsync(6_000)
+      await rejection
+
+      expect(kill).toHaveBeenNthCalledWith(1, 12345, 'SIGTERM')
+      expect(kill).toHaveBeenNthCalledWith(2, 12345, 'SIGKILL')
+      expect(child.disconnect).toHaveBeenCalledOnce()
+      expect(child.unref).toHaveBeenCalledOnce()
+    } finally {
+      kill.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('surfaces non-ESRCH startup termination errors and releases IPC', async () => {
+    const signalError = Object.assign(new Error('operation not permitted'), { code: 'EPERM' })
+    const kill = vi.spyOn(process, 'kill').mockImplementation(() => {
+      throw signalError
+    })
+    try {
+      const mod = await importFresh()
+      checkDaemonHealthMock.mockResolvedValue('unreachable')
+      await mod.initDaemonPtyProvider()
+      const child = {
+        pid: 12345,
+        connected: true,
+        exitCode: null,
+        signalCode: null,
+        on(event: string, callback: (arg?: unknown) => void) {
+          if (event === 'message') {
+            queueMicrotask(() => callback({ type: 'ready' }))
+          }
+          return this
+        },
+        off: vi.fn(),
+        disconnect: vi.fn(() => {
+          child.connected = false
+        }),
+        unref: vi.fn()
+      }
+      forkMock.mockReturnValueOnce(child)
+      const launcher = spawnerInstances[0].launcher as (
+        socketPath: string,
+        tokenPath: string
+      ) => Promise<{ shutdown(): Promise<void> }>
+
+      const error = await launcher('/fake/socket', '/fake/token').catch((caught: unknown) => caught)
+
+      expect(error).toBeInstanceOf(AggregateError)
+      expect((error as AggregateError).errors).toEqual([
+        expect.objectContaining({ message: 'Daemon readiness identity is incomplete' }),
+        signalError
+      ])
+      expect(child.disconnect).toHaveBeenCalledOnce()
+      expect(child.unref).toHaveBeenCalledOnce()
+    } finally {
+      kill.mockRestore()
+    }
+  })
+
+  it('settles startup with both errors when a malformed-ready child ignores termination', async () => {
+    vi.useFakeTimers()
+    const kill = vi.spyOn(process, 'kill').mockReturnValue(true)
+    try {
+      const mod = await importFresh()
+      checkDaemonHealthMock.mockResolvedValue('unreachable')
+      await mod.initDaemonPtyProvider()
+      const handlers: Record<string, ((arg?: unknown) => void)[]> = {
+        message: [],
+        error: [],
+        exit: []
+      }
+      const child = {
+        pid: 12345,
+        connected: true,
+        exitCode: null,
+        signalCode: null,
+        on(event: string, callback: (arg?: unknown) => void) {
+          handlers[event]?.push(callback)
+          if (event === 'message') {
+            queueMicrotask(() => callback({ type: 'ready' }))
+          }
+          return this
+        },
+        off(event: string, callback: (arg?: unknown) => void) {
+          handlers[event] = handlers[event]?.filter((handler) => handler !== callback) ?? []
+          return this
+        },
+        disconnect: vi.fn(() => {
+          child.connected = false
+        }),
+        unref: vi.fn()
+      }
+      forkMock.mockReturnValueOnce(child)
+      const launcher = spawnerInstances[0].launcher as (
+        socketPath: string,
+        tokenPath: string
+      ) => Promise<{ shutdown(): Promise<void> }>
+
+      const launch = launcher('/fake/socket', '/fake/token').catch((error: unknown) => error)
+      await vi.advanceTimersByTimeAsync(6_000)
+      const error = await launch
+
+      expect(error).toBeInstanceOf(AggregateError)
+      expect((error as AggregateError).errors).toEqual([
+        expect.objectContaining({ message: 'Daemon readiness identity is incomplete' }),
+        expect.objectContaining({ message: 'Daemon did not exit after SIGKILL' })
+      ])
+      expect(kill).toHaveBeenNthCalledWith(1, 12345, 'SIGTERM')
+      expect(kill).toHaveBeenNthCalledWith(2, 12345, 'SIGKILL')
+      expect(handlers.message).toHaveLength(0)
+      expect(handlers.error).toHaveLength(0)
+      expect(handlers.exit).toHaveLength(0)
+      expect(child.disconnect).toHaveBeenCalledOnce()
+      expect(child.unref).toHaveBeenCalledOnce()
+    } finally {
+      kill.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('kills and rejects a daemon when exclusive PID publication fails', async () => {
+    const mod = await importFresh()
+    checkDaemonHealthMock.mockResolvedValue('unreachable')
+    await mod.initDaemonPtyProvider()
+
+    const launcher = spawnerInstances[0].launcher as (
+      socketPath: string,
+      tokenPath: string
+    ) => Promise<{ shutdown(): Promise<void> }>
+    const kill = vi.spyOn(process, 'kill').mockImplementation(() => {
+      throw Object.assign(new Error('already exited'), { code: 'ESRCH' })
+    })
+    const child = {
+      pid: 12345,
+      on(event: string, cb: (arg?: unknown) => void) {
+        if (event === 'message') {
+          queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
+        }
+        return this
+      },
+      off: vi.fn(),
+      disconnect: vi.fn(),
+      unref: vi.fn()
+    }
+    const publicationError = Object.assign(new Error('PID record already exists'), {
+      code: 'EEXIST'
+    })
+    writeFileSyncMock.mockImplementationOnce(() => {
+      throw publicationError
+    })
+    forkMock.mockReturnValueOnce(child)
+
+    try {
+      await expect(launcher('/fake/socket', '/fake/token')).rejects.toBe(publicationError)
+      expect(writeFileSyncMock).toHaveBeenCalledWith(
+        `/fake/daemon/daemon-v${PROTOCOL_VERSION}.pid`,
+        expect.any(String),
+        { mode: 0o600, flag: 'wx' }
+      )
+      expect(kill).toHaveBeenCalledWith(12345, 'SIGTERM')
+      expect(child.disconnect).not.toHaveBeenCalled()
+      expect(child.unref).toHaveBeenCalledOnce()
+    } finally {
+      kill.mockRestore()
+    }
   })
 
   it('removes detached daemon startup listeners after startup error', async () => {
@@ -1390,7 +2033,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     expect(handlers.error).toHaveLength(0)
     expect(handlers.exit).toHaveLength(0)
     expect(child.disconnect).not.toHaveBeenCalled()
-    expect(child.unref).not.toHaveBeenCalled()
+    expect(child.unref).toHaveBeenCalledOnce()
   })
 
   it('captures daemon startup stderr into the failure error', async () => {
@@ -1429,6 +2072,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     }
     const child = {
       pid: 4321,
+      exitCode: null as number | null,
       stderr,
       on(event: string, cb: (arg?: unknown) => void) {
         handlers[event]?.push(cb)
@@ -1439,6 +2083,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
             for (const dataCb of stderrDataCbs.slice()) {
               dataCb(Buffer.from("Error: Cannot find module 'electron'\n"))
             }
+            child.exitCode = 1
             cb(1)
           })
         }
@@ -1492,10 +2137,14 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       on(event: string, cb: (arg?: unknown) => void) {
         handlers[event]?.push(cb)
         if (event === 'message') {
-          queueMicrotask(() => cb({ type: 'ready' }))
+          queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
         }
         return this
       },
+      once(event: string, cb: (arg?: unknown) => void) {
+        handlers[event]?.push(cb)
+        return this
+      },
       off: vi.fn(() => child),
       disconnect: vi.fn(),
       unref: vi.fn()
@@ -1523,6 +2172,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       return {}
     })
     const disconnectMock = vi.fn()
+    mockConnectedAdoptionClientOnce()
     daemonClientMock.mockImplementationOnce(function MockDaemonClient() {
       return {
         ensureConnected: vi.fn(async () => {}),
@@ -1557,6 +2207,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       }
       return {}
     })
+    mockConnectedAdoptionClientOnce()
     daemonClientMock.mockImplementationOnce(function MockDaemonClient() {
       return {
         ensureConnected: vi.fn(async () => {}),
@@ -1602,10 +2253,13 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       pid: 12345,
       on(event: string, cb: (arg?: unknown) => void) {
         if (event === 'message') {
-          queueMicrotask(() => cb({ type: 'ready' }))
+          queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
         }
         return this
       },
+      once() {
+        return this
+      },
       off() {
         return this
       },
@@ -1700,11 +2354,16 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
         disconnect: vi.fn()
       }
     }
-    // Every probe across the whole grace window times out (permanent wedge).
+    // Every probe across the whole grace window times out (permanent wedge),
+    // then the freshly spawned daemon accepts the temporary adoption lease.
+    let daemonClientConstructionCount = 0
     daemonClientMock.mockImplementation(function MockDaemonClient() {
+      daemonClientConstructionCount++
       return {
         ensureConnected: vi.fn(async () => {
-          throw new Error('Hello response timed out')
+          if (daemonClientConstructionCount <= 2 + WEDGED_DAEMON_GRACE_RETRIES) {
+            throw new Error('Hello response timed out')
+          }
         }),
         request: vi.fn(),
         disconnect: vi.fn()
@@ -1722,7 +2381,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       pid: 12345,
       on(event: string, cb: (arg?: unknown) => void) {
         if (event === 'message') {
-          queueMicrotask(() => cb({ type: 'ready' }))
+          queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
         }
         return this
       },
@@ -1747,7 +2406,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       expect(forkMock).toHaveBeenCalled()
       // The launcher probes the full grace budget before giving up: 1 initial
       // probe + WEDGED_DAEMON_GRACE_RETRIES retries.
-      expect(daemonClientMock).toHaveBeenCalledTimes(1 + WEDGED_DAEMON_GRACE_RETRIES)
+      expect(daemonClientMock).toHaveBeenCalledTimes(3 + WEDGED_DAEMON_GRACE_RETRIES)
     } finally {
       // Restore the answering default so the persistent throwing impl above
       // does not leak into later tests (clearAllMocks clears calls, not impls).
@@ -1842,7 +2501,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       pid: 12345,
       on(event: string, cb: (arg?: unknown) => void) {
         if (event === 'message') {
-          queueMicrotask(() => cb({ type: 'ready' }))
+          queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
         }
         return this
       },
@@ -1864,8 +2523,9 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     expect(forkMock).toHaveBeenCalled()
     // Pins the 'rejected' fast-path: a daemon that actively refuses the
     // handshake is never worth a grace window, so it is probed exactly once
-    // (no retries) before replacement.
-    expect(daemonClientMock).toHaveBeenCalledTimes(1)
+    // (no retries) before replacement. The other clients are the initial
+    // adoption attempt and the fresh daemon's temporary adoption lease.
+    expect(daemonClientMock).toHaveBeenCalledTimes(3)
   })
 
   it('adopts a healthy daemon whose pid-file identity cannot be verified (null startedAtMs metadata)', async () => {
@@ -1917,16 +2577,16 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
 
     await launcher('/fake/socket', '/fake/token')
 
-    expect(writeFileSyncMock).toHaveBeenCalledWith(
-      `/fake/daemon/daemon-v${PROTOCOL_VERSION}.pid`,
-      JSON.stringify({
-        pid: 12345,
-        startedAtMs: 1_700_000_123_456,
-        entryPath: FAKE_DAEMON_ENTRY_PATH,
-        appVersion: '1.2.3'
-      }),
-      { mode: 0o600 }
-    )
+    const [pidPath, pidContents, pidOptions] = writeFileSyncMock.mock.calls.at(-1) ?? []
+    expect(pidPath).toBe(`/fake/daemon/daemon-v${PROTOCOL_VERSION}.pid`)
+    expect(JSON.parse(pidContents as string)).toEqual({
+      pid: 12345,
+      startedAtMs: 1_700_000_123_456,
+      entryPath: FAKE_DAEMON_ENTRY_PATH,
+      appVersion: '1.2.3',
+      launchNonce: expect.stringMatching(/^[0-9a-f-]{36}$/)
+    })
+    expect(pidOptions).toEqual({ mode: 0o600, flag: 'wx' })
   })
 
   it('keeps legacy daemon pid/token files when the probe fails but the pid-file process is alive', async () => {
@@ -1987,7 +2647,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
         on(event: string, cb: (arg?: unknown) => void) {
           handlers[event]?.push(cb)
           if (event === 'message') {
-            queueMicrotask(() => cb({ type: 'ready' }))
+            queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
           }
           return this
         },
@@ -2073,7 +2733,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
         on(event: string, cb: (arg?: unknown) => void) {
           handlers[event]?.push(cb)
           if (event === 'message') {
-            queueMicrotask(() => cb({ type: 'ready' }))
+            queueMicrotask(() => cb({ type: 'ready', startedAtMs: 1_000_000 }))
           }
           return this
         },
@@ -2126,6 +2786,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       return {}
     })
     const disconnectMock = vi.fn()
+    mockConnectedAdoptionClientOnce()
     daemonClientMock.mockImplementationOnce(function MockDaemonClient() {
       return {
         ensureConnected: vi.fn(async () => {}),
diff --git a/src/main/daemon/daemon-init.ts b/src/main/daemon/daemon-init.ts
index 1bbc2cad9c3..093cb7a00f7 100644
--- a/src/main/daemon/daemon-init.ts
+++ b/src/main/daemon/daemon-init.ts
@@ -7,9 +7,10 @@ files with no cleaner ownership seam: restart, replaceDaemonProvider, and the
 module-level spawner/adapter singletons must stay co-located so a future
 change cannot leave them drifting out of sync. */
 import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
 import { app } from 'electron'
 import { mkdirSync, existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
-import { fork } from 'node:child_process'
+import { fork, type ChildProcess } from 'node:child_process'
 import { connect } from 'node:net'
 import {
   DaemonSpawner,
@@ -17,6 +18,7 @@ import {
   getDaemonSocketPath,
   getDaemonTokenPath,
   serializeDaemonPidFile,
+  unlinkOwnedDaemonPidFile,
   type DaemonLauncher,
   type DaemonProcessHandle
 } from './daemon-spawner'
@@ -24,6 +26,7 @@ import { DaemonPtyAdapter } from './daemon-pty-adapter'
 import { DaemonPtyRouter } from './daemon-pty-router'
 import { DaemonClient } from './client'
 import {
+  CLEAN_DISCONNECT_PROTOCOL_VERSION,
   PREVIOUS_DAEMON_PROTOCOL_VERSIONS,
   PROTOCOL_VERSION,
   type ListSessionsResult
@@ -31,7 +34,6 @@ import {
 import {
   getMacDaemonSystemResolverHealth,
   getDaemonLaunchIdentity,
-  getProcessStartedAtMs,
   checkDaemonHealth,
   isDaemonStaleForCurrentBundle,
   killStaleDaemon,
@@ -82,6 +84,9 @@ function logDaemonMilestone(event: string, details: Record<string, unknown> = {}
 // that takes longer than ~60s to drain is replaced (live processes lost, though
 // scrollback cold-restores). Raise this only alongside the fail-open cap.
 export const WEDGED_DAEMON_GRACE_RETRIES = 11
+const DAEMON_SELF_SHUTDOWN_WAIT_MS = 5_000
+const DAEMON_CHILD_TERMINATION_GRACE_MS = 5_000
+const DAEMON_CHILD_FORCE_EXIT_WAIT_MS = 1_000
 
 let spawner: DaemonSpawner | null = null
 type DaemonProvider = DaemonPtyRouter | DaemonPtyAdapter | DegradedDaemonPtyProvider
@@ -205,6 +210,134 @@ function createPreservedDaemonHandle(
   return handle
 }
 
+async function holdDaemonAdoptionLease(
+  handle: DaemonProcessHandle,
+  socketPath: string,
+  tokenPath: string,
+  connectedClient?: DaemonClient
+): Promise<DaemonProcessHandle> {
+  const client = connectedClient ?? new DaemonClient({ socketPath, tokenPath })
+  try {
+    await client.ensureConnected()
+  } catch (error) {
+    client.disconnect()
+    throw error
+  }
+  handle.releaseAdoptionLease = () => client.disconnect()
+  return handle
+}
+
+function releaseDaemonAdoptionLease(handle: DaemonProcessHandle | null): void {
+  takeDaemonAdoptionLeaseRelease(handle)?.()
+}
+
+function takeDaemonAdoptionLeaseRelease(
+  handle: DaemonProcessHandle | null
+): (() => void) | undefined {
+  const release = handle?.releaseAdoptionLease
+  if (!release || !handle) {
+    return undefined
+  }
+  delete handle.releaseAdoptionLease
+  return release
+}
+
+async function cleanupFailedDaemonAdoption(
+  failedSpawner: DaemonSpawner,
+  current: DaemonPtyAdapter,
+  legacy: DaemonPtyAdapter[] = []
+): Promise<void> {
+  const handle = failedSpawner.getHandle()
+  const results = await Promise.allSettled([
+    Promise.resolve().then(() => releaseDaemonAdoptionLease(handle)),
+    ...legacy.map((entry) => entry.disconnectOnly()),
+    (async () => {
+      try {
+        // Why: endpoint publication allows other authenticated clients to win;
+        // only daemon-side shutdownIfIdle may prove a failed adoption is killable.
+        await current.disconnectOnly()
+      } catch (error) {
+        current.dispose()
+        throw error
+      }
+    })()
+  ])
+  const failures = results.flatMap((result) =>
+    result.status === 'rejected' ? [result.reason] : []
+  )
+  if (failures.length > 0) {
+    throw new AggregateError(failures, 'Daemon adoption cleanup failed')
+  }
+}
+
+async function terminateLaunchedDaemonChild(child: ChildProcess): Promise<void> {
+  try {
+    if (
+      (child.exitCode !== null && child.exitCode !== undefined) ||
+      (child.signalCode !== null && child.signalCode !== undefined)
+    ) {
+      return
+    }
+    await new Promise<void>((resolve, reject) => {
+      let gracefulTimer: ReturnType<typeof setTimeout>
+      let forcedTimer: ReturnType<typeof setTimeout> | undefined
+      let settled = false
+      const finish = (error?: unknown): void => {
+        if (settled) {
+          return
+        }
+        settled = true
+        clearTimeout(gracefulTimer)
+        if (forcedTimer) {
+          clearTimeout(forcedTimer)
+        }
+        child.off('exit', onExit)
+        if (error) {
+          reject(error)
+        } else {
+          resolve()
+        }
+      }
+      const onExit = (): void => finish()
+      child.on('exit', onExit)
+      gracefulTimer = setTimeout(() => {
+        if (child.pid) {
+          try {
+            process.kill(child.pid, 'SIGKILL')
+          } catch (error) {
+            finish(isNoSuchProcessError(error) ? undefined : error)
+            return
+          }
+        }
+        if (!settled) {
+          forcedTimer = setTimeout(
+            () => finish(new Error('Daemon did not exit after SIGKILL')),
+            DAEMON_CHILD_FORCE_EXIT_WAIT_MS
+          )
+        }
+      }, DAEMON_CHILD_TERMINATION_GRACE_MS)
+      if (child.pid) {
+        try {
+          process.kill(child.pid, 'SIGTERM')
+        } catch (error) {
+          finish(isNoSuchProcessError(error) ? undefined : error)
+        }
+      } else {
+        finish()
+      }
+    })
+  } finally {
+    if (child.connected) {
+      child.disconnect()
+    }
+    child.unref()
+  }
+}
+
+function isNoSuchProcessError(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ESRCH'
+}
+
 async function shouldPreserveDaemonWithLiveSessions(
   socketPath: string,
   tokenPath: string,
@@ -223,275 +356,351 @@ async function shouldPreserveDaemonWithLiveSessions(
 }
 
 function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
-  return async (socketPath, tokenPath) => {
+  return async (socketPath, tokenPath, suppliedPidPath, suppliedLaunchNonce) => {
     const entryPath = getDaemonEntryPath()
-    const health = await checkDaemonHealth(socketPath, tokenPath)
-    if (health === 'healthy') {
-      const resolverHealth = await getMacDaemonSystemResolverHealth(socketPath, tokenPath)
-      if (resolverHealth === 'unhealthy') {
-        const liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
-        if (liveSessionCount !== 0) {
-          console.warn(
-            liveSessionCount === null
-              ? '[daemon] Preserving daemon with unavailable macOS system resolver because live session state could not be verified'
-              : `[daemon] Preserving daemon with unavailable macOS system resolver because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}`
-          )
-          return createPreservedDaemonHandle(runtimeDir)
-        }
-        console.warn('[daemon] Replacing daemon with unavailable macOS system resolver')
-        await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
-      } else {
-        // Why: a protocol-healthy daemon can outlive the app bundle that
-        // launched it. In dev this happens after deleting/rebuilding a
-        // worktree; in packaged apps it happens when the stable
-        // /Applications/Orca.app path is replaced during update.
-        const identity = await getDaemonLaunchIdentity(runtimeDir, socketPath, tokenPath, entryPath)
-        const stalePackagedBundle =
-          app.isPackaged &&
-          (await isDaemonStaleForCurrentBundle(runtimeDir, socketPath, tokenPath, app.getVersion()))
-        if (identity === 'mismatch' || stalePackagedBundle) {
-          // Why: replacing a healthy daemon kills its child PTYs; defer code
-          // freshness until no live terminal sessions would be lost.
-          const replacementLabel = stalePackagedBundle
-            ? 'launched before the current app bundle was installed'
-            : 'launched from a different app path'
-          if (await shouldPreserveDaemonWithLiveSessions(socketPath, tokenPath, replacementLabel)) {
-            return createPreservedDaemonHandle(runtimeDir)
+    const pidPath = suppliedPidPath ?? getDaemonPidPath(runtimeDir)
+    const launchNonce = suppliedLaunchNonce ?? randomUUID()
+    let adoptionClient: DaemonClient | null = new DaemonClient({ socketPath, tokenPath })
+    try {
+      // Why: acquire the full pair before any control-only probes so an expired
+      // inherited deadline cannot fire in the probe-to-adoption gap.
+      await adoptionClient.ensureConnected()
+    } catch {
+      adoptionClient.disconnect()
+      adoptionClient = null
+    }
+    const preserveDaemon = async (
+      mode?: 'degraded-new-pty-fallback'
+    ): Promise<DaemonProcessHandle> => {
+      const connectedClient = adoptionClient ?? undefined
+      adoptionClient = null
+      return holdDaemonAdoptionLease(
+        createPreservedDaemonHandle(runtimeDir, PROTOCOL_VERSION, mode),
+        socketPath,
+        tokenPath,
+        connectedClient
+      )
+    }
+    try {
+      const health = await checkDaemonHealth(socketPath, tokenPath)
+      if (health === 'healthy') {
+        const resolverHealth = await getMacDaemonSystemResolverHealth(socketPath, tokenPath)
+        if (resolverHealth === 'unhealthy') {
+          const liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
+          if (liveSessionCount !== 0) {
+            console.warn(
+              liveSessionCount === null
+                ? '[daemon] Preserving daemon with unavailable macOS system resolver because live session state could not be verified'
+                : `[daemon] Preserving daemon with unavailable macOS system resolver because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}`
+            )
+            return preserveDaemon()
           }
-          console.warn(
-            stalePackagedBundle
-              ? '[daemon] Replacing daemon launched before the current app bundle was installed'
-              : '[daemon] Replacing daemon launched from a different app path'
-          )
+          console.warn('[daemon] Replacing daemon with unavailable macOS system resolver')
           await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
         } else {
-          // Why: daemon is already running from a previous app session and
-          // responded to a protocol-level ping. Safe to reuse.
-          return createPreservedDaemonHandle(runtimeDir)
-        }
-      }
-    } else {
-      // Why: a busy machine (e.g. right after an update) can time out the
-      // health check while the daemon is alive and owning terminals. Killing
-      // it would destroy every live session, so re-verify with a session list
-      // first.
-      let liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
-      // Why: on a Windows update relaunch the daemon can be transiently wedged
-      // past every RPC budget (final checkpoint flush + installer/AV disk
-      // pressure) while its sessions are still alive — replacing it here is what
-      // killed those sessions. A pipe that still accepts connections proves a
-      // live daemon, so give a wedged-but-connectable daemon a bounded grace to
-      // drain and answer before deciding. A PERMANENTLY wedged daemon (accepts
-      // connections but its event loop never answers hello — #8689) exhausts the
-      // grace and falls through to replacement below, instead of being preserved
-      // forever, which strands the app with zero working terminals. 'rejected'
-      // means the daemon answered and refused the handshake — it can never be
-      // adopted, so it skips the grace and replacement stays the only recovery.
-      let graceRetry = 0
-      while (
-        liveSessionCount === null &&
-        health !== 'rejected' &&
-        graceRetry < WEDGED_DAEMON_GRACE_RETRIES &&
-        (await probeSocket(socketPath))
-      ) {
-        liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
-        graceRetry++
-      }
-      if (liveSessionCount !== null && liveSessionCount > 0) {
-        if (health === 'pty-spawn-unhealthy') {
-          console.warn(
-            `[daemon] DEGRADED MODE: preserving daemon that failed the PTY spawn health check because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}. Existing sessions keep working; fresh terminals run on the local provider WITHOUT daemon persistence until you restart the daemon (Manage Sessions → Restart).`
-          )
-          return createPreservedDaemonHandle(
+          // Why: a protocol-healthy daemon can outlive the app bundle that
+          // launched it. In dev this happens after deleting/rebuilding a
+          // worktree; in packaged apps it happens when the stable
+          // /Applications/Orca.app path is replaced during update.
+          const identity = await getDaemonLaunchIdentity(
             runtimeDir,
-            PROTOCOL_VERSION,
-            'degraded-new-pty-fallback'
+            socketPath,
+            tokenPath,
+            entryPath
           )
-        }
-        console.warn(
-          `[daemon] Preserving daemon that failed the health check because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}`
-        )
-        return createPreservedDaemonHandle(runtimeDir)
-      }
-    }
-
-    // Why: a raw socket can outlive a broken or wedged daemon. Kill by PID
-    // before respawn so the new daemon does not race the stale process.
-    await killStaleDaemon(runtimeDir, socketPath, tokenPath)
-
-    const userDataPath = app.getPath('userData')
-    // Why: on win32 packaged, fork from a copy of the Electron runtime staged
-    // in userData so the daemon's image + loaded modules escape the install dir
-    // the NSIS updater deletes and force-closes. Staged here (not at app start)
-    // so the one-time copy stays off the first-paint path and is skipped on
-    // launches that adopt a live daemon. Fail-open: null → in-dir host, below.
-    const relocatedHost = materializeRelocatedDaemonHost()
-    // Fork the relocated entry when available; otherwise the install-dir entry.
-    const forkEntryPath = relocatedHost ? relocatedHost.entryPath : entryPath
-    const child = fork(
-      forkEntryPath,
-      ['--socket', socketPath, '--token', tokenPath, ...daemonLogArgs()],
-      {
-        // Why: detached daemons can outlive dev worktrees. Starting from
-        // userData keeps process.cwd() valid after a repo/worktree is deleted.
-        cwd: userDataPath,
-        // Why: detached + unref lets the daemon outlive the Electron process.
-        // stdout stays 'ignore' so the child never holds the parent's stdout
-        // open (which would block Electron exit); stderr is 'pipe' so a
-        // module-load crash during startup is captured instead of discarded
-        // (v1.4.129-rc.1 shipped a daemon that only logged "exited with code 1"
-        // because stderr was thrown away). The pipe is destroyed on readiness.
-        detached: true,
-        stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
-        // Why: run the relocated Orca.exe copy instead of the install-dir one.
-        // It is byte-identical, so run-as-node behavior is unchanged; only the
-        // image path moves out of the updater's kill zone.
-        ...(relocatedHost ? { execPath: relocatedHost.execPath } : {}),
-        // Why: ELECTRON_RUN_AS_NODE makes the forked process run as a plain
-        // Node.js process instead of an Electron renderer/main process. Without
-        // it, Electron's GPU/display initialization can interfere with native
-        // module operations like node-pty's posix_spawn of the spawn-helper.
-        env: {
-          ...process.env,
-          ELECTRON_RUN_AS_NODE: '1',
-          // Why: the detached daemon is plain Node and cannot call Electron's
-          // app.getPath(), but shell-ready rcfiles must live outside swept tmp.
-          ORCA_USER_DATA_PATH: userDataPath
-        }
-      }
-    )
-
-    // Why: keep only the startup-window stderr tail so a crash cause is
-    // visible without unbounded memory if the daemon spews before dying.
-    const STARTUP_STDERR_MAX_BYTES = 8192
-    let startupStderr = ''
-    let collectingStderr = true
-    const onStartupStderr = (chunk: Buffer): void => {
-      if (!collectingStderr) {
-        return
-      }
-      startupStderr += chunk.toString('utf8')
-      if (startupStderr.length > STARTUP_STDERR_MAX_BYTES) {
-        startupStderr = startupStderr.slice(-STARTUP_STDERR_MAX_BYTES)
-      }
-    }
-    child.stderr?.on('data', onStartupStderr)
-    // Why: once the daemon is up (or has failed) the parent must not keep a
-    // live handle on the detached daemon's stderr — a piped stream would ref
-    // the parent event loop and prevent Electron from exiting cleanly.
-    const releaseStderr = (): void => {
-      collectingStderr = false
-      child.stderr?.off('data', onStartupStderr)
-      child.stderr?.destroy()
-    }
-
-    // Wait for the daemon to signal readiness via IPC
-    await new Promise<void>((resolve, reject) => {
-      let timer: ReturnType<typeof setTimeout> | undefined
-      let settled = false
-      function cleanupStartupListeners(): void {
-        if (timer) {
-          clearTimeout(timer)
-        }
-        child.off('message', onReadyMessage)
-        child.off('error', onStartupError)
-        child.off('exit', onStartupExit)
-      }
-      function fail(error: Error): void {
-        if (settled) {
-          return
-        }
-        settled = true
-        cleanupStartupListeners()
-        // Why: stderr was previously discarded, so a startup crash surfaced only
-        // as "exited with code 1". Attach the captured tail to the thrown error
-        // (which the fallback path reports) and log it so the real cause shows.
-        const stderrTail = startupStderr.trim()
-        if (stderrTail) {
-          console.warn(`[daemon] startup failed; captured stderr tail:\n${stderrTail}`)
-        }
-        releaseStderr()
-        if (child.pid) {
-          try {
-            process.kill(child.pid, 'SIGTERM')
-          } catch {
-            // Already dead
+          const stalePackagedBundle =
+            app.isPackaged &&
+            (await isDaemonStaleForCurrentBundle(
+              runtimeDir,
+              socketPath,
+              tokenPath,
+              app.getVersion()
+            ))
+          if (identity === 'mismatch' || stalePackagedBundle) {
+            // Why: replacing a healthy daemon kills its child PTYs; defer code
+            // freshness until no live terminal sessions would be lost.
+            const replacementLabel = stalePackagedBundle
+              ? 'launched before the current app bundle was installed'
+              : 'launched from a different app path'
+            if (
+              await shouldPreserveDaemonWithLiveSessions(socketPath, tokenPath, replacementLabel)
+            ) {
+              return preserveDaemon()
+            }
+            console.warn(
+              stalePackagedBundle
+                ? '[daemon] Replacing daemon launched before the current app bundle was installed'
+                : '[daemon] Replacing daemon launched from a different app path'
+            )
+            await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
+          } else {
+            // Why: daemon is already running from a previous app session and
+            // responded to a protocol-level ping. Safe to reuse.
+            return preserveDaemon()
           }
         }
-        reject(
-          stderrTail ? new Error(`${error.message}\nDaemon stderr (tail):\n${stderrTail}`) : error
-        )
+      } else {
+        // Why: a busy machine (e.g. right after an update) can time out the
+        // health check while the daemon is alive and owning terminals. Killing
+        // it would destroy every live session, so re-verify with a session list
+        // first.
+        let liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
+        // Why: on a Windows update relaunch the daemon can be transiently wedged
+        // past every RPC budget (final checkpoint flush + installer/AV disk
+        // pressure) while its sessions are still alive — replacing it here is what
+        // killed those sessions. A pipe that still accepts connections proves a
+        // live daemon, so give a wedged-but-connectable daemon a bounded grace to
+        // drain and answer before deciding. A PERMANENTLY wedged daemon (accepts
+        // connections but its event loop never answers hello — #8689) exhausts the
+        // grace and falls through to replacement below, instead of being preserved
+        // forever, which strands the app with zero working terminals. 'rejected'
+        // means the daemon answered and refused the handshake — it can never be
+        // adopted, so it skips the grace and replacement stays the only recovery.
+        let graceRetry = 0
+        while (
+          liveSessionCount === null &&
+          health !== 'rejected' &&
+          graceRetry < WEDGED_DAEMON_GRACE_RETRIES &&
+          (await probeSocket(socketPath))
+        ) {
+          liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
+          graceRetry++
+        }
+        if (liveSessionCount !== null && liveSessionCount > 0) {
+          if (health === 'pty-spawn-unhealthy') {
+            console.warn(
+              `[daemon] DEGRADED MODE: preserving daemon that failed the PTY spawn health check because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}. Existing sessions keep working; fresh terminals run on the local provider WITHOUT daemon persistence until you restart the daemon (Manage Sessions → Restart).`
+            )
+            return preserveDaemon('degraded-new-pty-fallback')
+          }
+          console.warn(
+            `[daemon] Preserving daemon that failed the health check because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}`
+          )
+          return preserveDaemon()
+        }
       }
-      function onReadyMessage(msg: unknown): void {
-        if (msg && typeof msg === 'object' && (msg as { type?: string }).type === 'ready') {
+
+      // Why: a raw socket can outlive a broken or wedged daemon. Kill by PID
+      // before respawn so the new daemon does not race the stale process.
+      adoptionClient?.disconnect()
+      adoptionClient = null
+      await killStaleDaemon(runtimeDir, socketPath, tokenPath)
+
+      const userDataPath = app.getPath('userData')
+      // Why: on win32 packaged, fork from a copy of the Electron runtime staged
+      // in userData so the daemon's image + loaded modules escape the install dir
+      // the NSIS updater deletes and force-closes. Staged here (not at app start)
+      // so the one-time copy stays off the first-paint path and is skipped on
+      // launches that adopt a live daemon. Fail-open: null → in-dir host, below.
+      const relocatedHost = materializeRelocatedDaemonHost()
+      // Fork the relocated entry when available; otherwise the install-dir entry.
+      const forkEntryPath = relocatedHost ? relocatedHost.entryPath : entryPath
+      const child = fork(
+        forkEntryPath,
+        [
+          '--socket',
+          socketPath,
+          '--token',
+          tokenPath,
+          '--pid-record',
+          pidPath,
+          '--launch-nonce',
+          launchNonce,
+          ...daemonLogArgs()
+        ],
+        {
+          // Why: detached daemons can outlive dev worktrees. Starting from
+          // userData keeps process.cwd() valid after a repo/worktree is deleted.
+          cwd: userDataPath,
+          // Why: detached + unref lets the daemon outlive the Electron process.
+          // stdout stays 'ignore' so the child never holds the parent's stdout
+          // open (which would block Electron exit); stderr is 'pipe' so a
+          // module-load crash during startup is captured instead of discarded
+          // (v1.4.129-rc.1 shipped a daemon that only logged "exited with code 1"
+          // because stderr was thrown away). The pipe is destroyed on readiness.
+          detached: true,
+          stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+          // Why: run the relocated Orca.exe copy instead of the install-dir one.
+          // It is byte-identical, so run-as-node behavior is unchanged; only the
+          // image path moves out of the updater's kill zone.
+          ...(relocatedHost ? { execPath: relocatedHost.execPath } : {}),
+          // Why: ELECTRON_RUN_AS_NODE makes the forked process run as a plain
+          // Node.js process instead of an Electron renderer/main process. Without
+          // it, Electron's GPU/display initialization can interfere with native
+          // module operations like node-pty's posix_spawn of the spawn-helper.
+          env: {
+            ...process.env,
+            ELECTRON_RUN_AS_NODE: '1',
+            // Why: the detached daemon is plain Node and cannot call Electron's
+            // app.getPath(), but shell-ready rcfiles must live outside swept tmp.
+            ORCA_USER_DATA_PATH: userDataPath
+          }
+        }
+      )
+
+      // Why: keep only the startup-window stderr tail so a crash cause is
+      // visible without unbounded memory if the daemon spews before dying.
+      const STARTUP_STDERR_MAX_BYTES = 8192
+      let startupStderr = ''
+      let collectingStderr = true
+      const onStartupStderr = (chunk: Buffer): void => {
+        if (!collectingStderr) {
+          return
+        }
+        startupStderr += chunk.toString('utf8')
+        if (startupStderr.length > STARTUP_STDERR_MAX_BYTES) {
+          startupStderr = startupStderr.slice(-STARTUP_STDERR_MAX_BYTES)
+        }
+      }
+      child.stderr?.on('data', onStartupStderr)
+      // Why: once the daemon is up (or has failed) the parent must not keep a
+      // live handle on the detached daemon's stderr — a piped stream would ref
+      // the parent event loop and prevent Electron from exiting cleanly.
+      const releaseStderr = (): void => {
+        collectingStderr = false
+        child.stderr?.off('data', onStartupStderr)
+        child.stderr?.destroy()
+      }
+
+      // Wait for the daemon to signal readiness via IPC
+      await new Promise<void>((resolve, reject) => {
+        let timer: ReturnType<typeof setTimeout> | undefined
+        let settled = false
+        function cleanupStartupListeners(): void {
+          if (timer) {
+            clearTimeout(timer)
+          }
+          child.off('message', onReadyMessage)
+          child.off('error', onStartupError)
+          child.off('exit', onStartupExit)
+        }
+        async function fail(error: Error): Promise<void> {
           if (settled) {
             return
           }
           settled = true
-          // Why: the daemon process is detached after readiness; leaving
-          // startup listeners attached retains this launch promise closure.
           cleanupStartupListeners()
-          if (child.pid) {
-            // Why: JSON pid file carries pid + process start time so later
-            // killStaleDaemon() can verify the pid still belongs to the daemon
-            // we forked before SIGTERMing it. Prevents pid-recycling hazard
-            // where the OS hands the daemon's old pid to an unrelated process.
-            // Why the ready-message fallback: Windows has no cheap OS query
-            // for start time, so the daemon self-reports it — without this the
-            // recycling guard was permanently inert on win32.
-            const selfReported = (msg as { startedAtMs?: unknown }).startedAtMs
-            writeFileSync(
-              getDaemonPidPath(runtimeDir),
-              serializeDaemonPidFile({
-                pid: child.pid,
-                startedAtMs:
-                  getProcessStartedAtMs(child.pid) ??
-                  (typeof selfReported === 'number' && Number.isFinite(selfReported)
-                    ? selfReported
-                    : null),
-                entryPath,
-                appVersion: app.getVersion()
-              }),
-              { mode: 0o600 }
-            )
+          // Why: stderr was previously discarded, so a startup crash surfaced only
+          // as "exited with code 1". Attach the captured tail to the thrown error
+          // (which the fallback path reports) and log it so the real cause shows.
+          const stderrTail = startupStderr.trim()
+          if (stderrTail) {
+            console.warn(`[daemon] startup failed; captured stderr tail:\n${stderrTail}`)
           }
-          // Why: disconnect IPC channel, release the stderr pipe, and unref so
-          // Electron can exit without waiting for the daemon. The daemon keeps
-          // running detached.
           releaseStderr()
-          child.disconnect()
-          child.unref()
-          resolve()
-        }
-      }
-
-      function onStartupError(err: Error): void {
-        fail(err)
-      }
-
-      function onStartupExit(code: number | null): void {
-        fail(new Error(`Daemon exited during startup with code ${code}`))
-      }
-
-      timer = setTimeout(() => {
-        fail(new Error('Daemon startup timed out'))
-      }, 10000)
-
-      child.on('message', onReadyMessage)
-      child.on('error', onStartupError)
-      child.on('exit', onStartupExit)
-    })
-
-    return {
-      shutdown: async () => {
-        if (child.pid) {
+          const startupError = stderrTail
+            ? new Error(`${error.message}\nDaemon stderr (tail):\n${stderrTail}`)
+            : error
           try {
-            process.kill(child.pid, 'SIGTERM')
-          } catch {
-            // Already dead
+            await terminateLaunchedDaemonChild(child)
+          } catch (cleanupError) {
+            reject(
+              new AggregateError(
+                [startupError, cleanupError],
+                'Daemon startup and child cleanup both failed'
+              )
+            )
+            return
+          }
+          reject(startupError)
+        }
+        function onReadyMessage(msg: unknown): void {
+          if (msg && typeof msg === 'object' && (msg as { type?: string }).type === 'ready') {
+            if (settled) {
+              return
+            }
+            const selfReported = (msg as { startedAtMs?: unknown }).startedAtMs
+            if (
+              !Number.isSafeInteger(child.pid) ||
+              (child.pid as number) <= 0 ||
+              typeof selfReported !== 'number' ||
+              !Number.isFinite(selfReported) ||
+              selfReported <= 0
+            ) {
+              void fail(new Error('Daemon readiness identity is incomplete'))
+              return
+            }
+            try {
+              // Why: hello and the PID record must share the daemon's self time
+              // and nonce so cleanup can identify this exact process incarnation.
+              writeFileSync(
+                pidPath,
+                serializeDaemonPidFile({
+                  pid: child.pid as number,
+                  startedAtMs: selfReported,
+                  entryPath,
+                  appVersion: app.getVersion(),
+                  launchNonce
+                }),
+                { mode: 0o600, flag: 'wx' }
+              )
+            } catch (error) {
+              void fail(error instanceof Error ? error : new Error(String(error)))
+              return
+            }
+            settled = true
+            // Why: the daemon process is detached after readiness; leaving
+            // startup listeners attached retains this launch promise closure.
+            cleanupStartupListeners()
+            // Why: disconnect IPC channel, release the stderr pipe, and unref so
+            // Electron can exit without waiting for the daemon. The daemon keeps
+            // running detached.
+            releaseStderr()
+            child.disconnect()
+            child.unref()
+            resolve()
           }
         }
+
+        function onStartupError(err: Error): void {
+          void fail(err)
+        }
+
+        function onStartupExit(code: number | null): void {
+          void fail(new Error(`Daemon exited during startup with code ${code}`))
+        }
+
+        timer = setTimeout(() => {
+          void fail(new Error('Daemon startup timed out'))
+        }, 10000)
+
+        child.on('message', onReadyMessage)
+        child.on('error', onStartupError)
+        child.on('exit', onStartupExit)
+      })
+
+      try {
+        return await holdDaemonAdoptionLease(
+          {
+            shutdown: () => terminateLaunchedDaemonChild(child)
+          },
+          socketPath,
+          tokenPath
+        )
+      } catch (error) {
+        // Why: another client may have adopted this still-live process. Keep its
+        // valid identity until exit, but remove a record published after an early exit.
+        let pidRecordRemoved = false
+        const removeExitedPidRecord = (): void => {
+          if (pidRecordRemoved) {
+            return
+          }
+          pidRecordRemoved = true
+          unlinkOwnedDaemonPidFile(pidPath, child.pid as number, launchNonce)
+        }
+        child.once('exit', removeExitedPidRecord)
+        if (
+          (child.exitCode !== null && child.exitCode !== undefined) ||
+          (child.signalCode !== null && child.signalCode !== undefined)
+        ) {
+          child.off('exit', removeExitedPidRecord)
+          removeExitedPidRecord()
+        }
+        throw error
       }
+    } catch (error) {
+      adoptionClient?.disconnect()
+      throw error
     }
   }
 }
@@ -525,7 +734,14 @@ export async function initDaemonPtyProvider(signal?: AbortSignal): Promise<void>
   logDaemonMilestone('daemon-current-ready')
   if (signal?.aborted) {
     // Why: startup fail-open may already have allowed fallback LocalPtyProvider
-    // PTYs to spawn. A late daemon swap would strand those PTYs on the old owner.
+    // PTYs to spawn. Do not install late, but give an empty daemon one bounded
+    // authenticated retirement attempt; live adopted sessions reject it and survive.
+    const abortedStartupAdapter = new DaemonPtyAdapter({
+      socketPath: info.socketPath,
+      tokenPath: info.tokenPath
+    })
+    releaseDaemonAdoptionLease(newSpawner.getHandle())
+    await abortedStartupAdapter.disconnectOnly()
     return
   }
 
@@ -541,37 +757,54 @@ export async function initDaemonPtyProvider(signal?: AbortSignal): Promise<void>
       console.warn('[daemon] Daemon process died — respawning')
       newSpawner.resetHandle()
       await newSpawner.ensureRunning()
+      return takeDaemonAdoptionLeaseRelease(newSpawner.getHandle())
     }
   })
+  let legacyAdapters: DaemonPtyAdapter[] = []
+  let routedAdapter: DaemonProvider = newAdapter
+  try {
+    // Why: the launcher's temporary pair closes only after this permanent
+    // adapter pair is established, leaving no retirement gap during adoption.
+    await newAdapter.establishLifecycleLease()
+    releaseDaemonAdoptionLease(newSpawner.getHandle())
 
-  const legacyAdapters = await createLegacyDaemonAdapters(runtimeDir)
-  const routedAdapter =
-    launchMode === 'degraded-new-pty-fallback'
-      ? new DegradedDaemonPtyProvider({
-          current: newAdapter,
-          legacy: legacyAdapters,
-          fallback: getLocalPtyProvider()
-        })
-      : legacyAdapters.length > 0
-        ? new DaemonPtyRouter({
+    legacyAdapters = await createLegacyDaemonAdapters(runtimeDir)
+    routedAdapter =
+      launchMode === 'degraded-new-pty-fallback'
+        ? new DegradedDaemonPtyProvider({
             current: newAdapter,
-            legacy: legacyAdapters
+            legacy: legacyAdapters,
+            fallback: getLocalPtyProvider()
           })
-        : newAdapter
-  if (routedAdapter instanceof DegradedDaemonPtyProvider) {
-    // Why: the preserved daemon cannot create fresh terminals, but its live
-    // sessions may still be writable. Discover those ids so only known old
-    // sessions route to the degraded daemon; fresh panes fall back locally.
-    await routedAdapter.discoverDaemonSessions()
-  } else if (routedAdapter instanceof DaemonPtyRouter) {
-    await routedAdapter.discoverLegacySessions()
+        : legacyAdapters.length > 0
+          ? new DaemonPtyRouter({
+              current: newAdapter,
+              legacy: legacyAdapters
+            })
+          : newAdapter
+    if (routedAdapter instanceof DegradedDaemonPtyProvider) {
+      // Why: the preserved daemon cannot create fresh terminals, but its live
+      // sessions may still be writable. Discover those ids so only known old
+      // sessions route to the degraded daemon; fresh panes fall back locally.
+      await routedAdapter.discoverDaemonSessions()
+    } else if (routedAdapter instanceof DaemonPtyRouter) {
+      await routedAdapter.discoverLegacySessions()
+    }
+    if (signal?.aborted) {
+      // Why: same late-swap guard after legacy discovery, which can also exceed
+      // the first-window startup timeout on slow or stale daemon state. Release
+      // every uninstalled adapter lease without killing its live sessions.
+      await routedAdapter.disconnectOnly()
+      return
+    }
+  } catch (error) {
+    try {
+      await cleanupFailedDaemonAdoption(newSpawner, newAdapter, legacyAdapters)
+    } catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], 'Daemon adoption and cleanup both failed')
+    }
+    throw error
   }
-  if (signal?.aborted) {
-    // Why: same late-swap guard after legacy discovery, which can also exceed
-    // the first-window startup timeout on slow or stale daemon state.
-    return
-  }
-
   spawner = newSpawner
   adapter = routedAdapter
   setLocalPtyProvider(routedAdapter)
@@ -713,12 +946,20 @@ async function runRestartDaemon(): Promise<RestartDaemonResult> {
 
   // Step 3: kill the current-protocol daemon process (shutdown RPC → fallback
   // killStaleDaemon → socket/pid unlink). Legacy adapters untouched.
-  await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
+  let info: Awaited<ReturnType<DaemonSpawner['ensureRunning']>>
+  try {
+    await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
 
-  // Step 4: reuse the existing spawner so the respawn closure baked into
-  // long-lived adapters stays valid. Do NOT construct a new DaemonSpawner.
-  currentSpawner.resetHandle()
-  const info = await currentSpawner.ensureRunning()
+    // Step 4: reuse the existing spawner so the respawn closure baked into
+    // long-lived adapters stays valid. Do NOT construct a new DaemonSpawner.
+    currentSpawner.resetHandle()
+    info = await currentSpawner.ensureRunning()
+  } catch (error) {
+    // Why: the old provider remains authoritative until the final swap, even
+    // if cleanup or replacement launch fails after listener teardown.
+    rebindLocalProviderListeners()
+    throw error
+  }
 
   // Step 5: build a fresh current adapter against the respawned daemon. Its
   // respawn callback closes over the same spawner instance (identical to the
@@ -731,18 +972,43 @@ async function runRestartDaemon(): Promise<RestartDaemonResult> {
       console.warn('[daemon] Daemon process died — respawning')
       currentSpawner.resetHandle()
       await currentSpawner.ensureRunning()
+      return takeDaemonAdoptionLeaseRelease(currentSpawner.getHandle())
     }
   })
+  let newProvider: DaemonProvider = newCurrent
+  try {
+    // Why: the temporary launcher lease overlaps this permanent pair so manual
+    // restart cannot strand a newly spawned daemon during adoption.
+    await newCurrent.establishLifecycleLease()
+    releaseDaemonAdoptionLease(currentSpawner.getHandle())
 
-  // Re-wrap in router if there were legacy adapters at startup; otherwise
-  // point straight at the new adapter. Legacy instances are preserved by
-  // reference — they still route to the same pre-upgrade daemons.
-  const newProvider =
-    legacyAdapters.length > 0
-      ? new DaemonPtyRouter({ current: newCurrent, legacy: legacyAdapters })
-      : newCurrent
-  if (newProvider instanceof DaemonPtyRouter) {
-    await newProvider.discoverLegacySessions()
+    // Re-wrap in router if there were legacy adapters at startup; otherwise
+    // point straight at the new adapter. Legacy instances are preserved by
+    // reference — they still route to the same pre-upgrade daemons.
+    newProvider =
+      legacyAdapters.length > 0
+        ? new DaemonPtyRouter({ current: newCurrent, legacy: legacyAdapters })
+        : newCurrent
+    if (newProvider instanceof DaemonPtyRouter) {
+      await newProvider.discoverLegacySessions()
+    }
+  } catch (error) {
+    let cleanupError: unknown
+    try {
+      if (newProvider instanceof DaemonPtyRouter) {
+        newProvider.disposeRouterOnly()
+      }
+      await cleanupFailedDaemonAdoption(currentSpawner, newCurrent)
+    } catch (caught) {
+      cleanupError = caught
+    }
+    // Why: the previous provider remains module-authoritative until the swap;
+    // restore its renderer bindings when replacement adoption fails.
+    rebindLocalProviderListeners()
+    if (cleanupError) {
+      throw new AggregateError([error, cleanupError], 'Daemon restart and cleanup both failed')
+    }
+    throw error
   }
 
   // Why: drain the outgoing router's subscriptions from the shared legacy
@@ -777,11 +1043,6 @@ export async function shutdownDaemon(): Promise<void> {
   adapter = null
   await spawner?.shutdown()
   spawner = null
-  try {
-    unlinkSync(getDaemonPidPath(getRuntimeDir()))
-  } catch {
-    // Best-effort
-  }
 }
 
 export type OrphanedDaemonCleanupResult = {
@@ -803,6 +1064,11 @@ export async function cleanupDaemonForProtocol(
 
   const alive = await probeSocket(socketPath)
   if (!alive) {
+    if (protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
+      // Why: endpoint absence does not prove a canonical PID record still
+      // belongs to the current protocol; the exact daemon owns its artifact cleanup.
+      return { cleaned: false, killedCount: 0 }
+    }
     // Why: still best-effort remove a stale socket file so a future opt-in
     // launch doesn't hit EADDRINUSE when the daemon tries to bind.
     if (process.platform !== 'win32' && existsSync(socketPath)) {
@@ -848,6 +1114,15 @@ export async function cleanupDaemonForProtocol(
     client.disconnect()
   }
 
+  if (didRequestShutdown && protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
+    if (!(await waitForDaemonEndpointExit(socketPath))) {
+      // Why: never fork a replacement while the old incarnation may still
+      // own the endpoint or be disposing terminal children.
+      throw new Error('Timed out waiting for daemon self-shutdown')
+    }
+    return { cleaned: true, killedCount }
+  }
+
   // Why: after `shutdown`, the daemon unlinks its socket itself — but on some
   // crash paths the file lingers. Clean up defensively so a later opt-in
   // relaunch can bind cleanly.
@@ -867,6 +1142,17 @@ export async function cleanupDaemonForProtocol(
   return { cleaned: didRequestShutdown || didKillStaleDaemon, killedCount }
 }
 
+async function waitForDaemonEndpointExit(socketPath: string): Promise<boolean> {
+  const deadline = Date.now() + DAEMON_SELF_SHUTDOWN_WAIT_MS
+  while (Date.now() < deadline) {
+    if (!(await probeSocket(socketPath))) {
+      return true
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+  return !(await probeSocket(socketPath))
+}
+
 function legacyDaemonProcessMayBeAlive(runtimeDir: string, protocolVersion: number): boolean {
   try {
     const parsed = parseDaemonPidFile(
diff --git a/src/main/daemon/daemon-main.ts b/src/main/daemon/daemon-main.ts
index 8d2d0a36c64..9884cdf0c80 100644
--- a/src/main/daemon/daemon-main.ts
+++ b/src/main/daemon/daemon-main.ts
@@ -4,9 +4,16 @@ import type { DaemonFileLog } from './daemon-file-log'
 export type DaemonStartOptions = {
   socketPath: string
   tokenPath: string
+  pidPath?: string
+  launchNonce?: string
+  startedAtMs?: number
+  /** Direct-construction seam for versioned protocol fixtures; never CLI/env configured. */
+  protocolVersion?: number
   spawnSubprocess: DaemonServerOptions['spawnSubprocess']
   preparePtySpawn?: DaemonServerOptions['preparePtySpawn']
   log?: DaemonFileLog
+  onIdleShutdown?: () => void
+  initialAdoptionTestConfig?: DaemonServerOptions['initialAdoptionTestConfig']
 }
 
 export type DaemonHandle = {
@@ -17,9 +24,17 @@ export async function startDaemon(opts: DaemonStartOptions): Promise<DaemonHandl
   const server = new DaemonServer({
     socketPath: opts.socketPath,
     tokenPath: opts.tokenPath,
+    ...(opts.pidPath ? { pidPath: opts.pidPath } : {}),
+    ...(opts.launchNonce ? { launchNonce: opts.launchNonce } : {}),
+    ...(opts.startedAtMs ? { startedAtMs: opts.startedAtMs } : {}),
+    ...(opts.protocolVersion !== undefined ? { protocolVersion: opts.protocolVersion } : {}),
     spawnSubprocess: opts.spawnSubprocess,
     ...(opts.preparePtySpawn ? { preparePtySpawn: opts.preparePtySpawn } : {}),
-    ...(opts.log ? { log: opts.log } : {})
+    ...(opts.log ? { log: opts.log } : {}),
+    ...(opts.onIdleShutdown ? { onIdleShutdown: opts.onIdleShutdown } : {}),
+    ...(opts.initialAdoptionTestConfig
+      ? { initialAdoptionTestConfig: opts.initialAdoptionTestConfig }
+      : {})
   })
 
   await server.start()
diff --git a/src/main/daemon/daemon-pty-adapter.ts b/src/main/daemon/daemon-pty-adapter.ts
index 202718eab7f..0fe8ecc2a4d 100644
--- a/src/main/daemon/daemon-pty-adapter.ts
+++ b/src/main/daemon/daemon-pty-adapter.ts
@@ -11,6 +11,7 @@ import { mintPtySessionId, parsePtySessionId } from './pty-session-id'
 import { supportsPtyStartupBarrier } from './shell-ready'
 import { CODEX_SHELL_READY_TIMEOUT_MS } from './session'
 import {
+  CLEAN_DISCONNECT_PROTOCOL_VERSION,
   GIT_CREDENTIAL_GUARD_HOST_PROTOCOL_VERSION,
   PROTOCOL_VERSION,
   type CreateOrAttachResult,
@@ -72,7 +73,7 @@ export type DaemonPtyAdapterOptions = {
   historyPath?: string
   /** Called when the daemon socket is unreachable (process died). Expected to
    *  fork a fresh daemon so the next connection attempt can succeed. */
-  respawn?: () => Promise<void>
+  respawn?: () => Promise<void | (() => void)>
 }
 
 const MAX_TOMBSTONES = 1000
@@ -92,7 +93,9 @@ export class DaemonPtyAdapter implements IPtyProvider {
   private client: DaemonClient
   private historyManager: HistoryManager | null
   private historyReader: HistoryReader | null
-  private respawnFn: (() => Promise<void>) | null
+  private respawnFn: (() => Promise<void | (() => void)>) | null
+  private pendingRespawnAdoptionRelease: (() => void) | null = null
+  private respawnAdoptionClosed = false
   // Why: multiple pane mounts can call spawn() concurrently. If the daemon is
   // dead, all calls enter withDaemonRetry's catch block at once. Without a
   // lock, each would fork its own daemon process. This promise coalesces
@@ -958,6 +961,8 @@ export class DaemonPtyAdapter implements IPtyProvider {
   }
 
   dispose(): void {
+    this.respawnAdoptionClosed = true
+    this.releasePendingRespawnAdoptionLease()
     this.stopCheckpointTimer()
     this.dirtySessionVersions.clear()
     this.lastFullCheckpointAt.clear()
@@ -978,6 +983,15 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.client.disconnect()
   }
 
+  async establishLifecycleLease(): Promise<void> {
+    if (this.protocolVersion < CLEAN_DISCONNECT_PROTOCOL_VERSION) {
+      return
+    }
+    // Why: an authenticated pair cancels the launch-adoption watchdog and gives
+    // a never-used adapter authority to retire its empty daemon during clean quit.
+    await this.client.ensureConnected()
+  }
+
   // Why: for in-process daemon mode, disconnect without flushing history.
   // dispose() writes endedAt for all sessions, which would prevent cold
   // restore. disconnectOnly() leaves history files in unclean state so
@@ -985,6 +999,8 @@ export class DaemonPtyAdapter implements IPtyProvider {
   // We write a final checkpoint before disconnecting so that if the daemon
   // later crashes while Orca is closed, checkpoint.json has recovery data.
   async disconnectOnly(): Promise<void> {
+    this.respawnAdoptionClosed = true
+    this.releasePendingRespawnAdoptionLease()
     this.stopCheckpointTimer()
     // Why: wait for any in-flight timer pass to finish before starting
     // the final checkpoint. Otherwise both passes race on the shared tmp
@@ -1011,11 +1027,31 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.producerResumesOwedOnReconnect.clear()
     this.removeEventListener?.()
     this.removeEventListener = null
+    if (this.protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
+      try {
+        // Why: only the authenticated daemon can atomically prove it is empty;
+        // one shared budget keeps a first connection plus retirement off quit's critical path.
+        const deadlineMs = Date.now() + 250
+        if (!this.client.isConnected()) {
+          await this.client.ensureConnectedWithin(Math.max(1, deadlineMs - Date.now()))
+        }
+        await this.client.request('shutdownIfIdle', undefined, Math.max(1, deadlineMs - Date.now()))
+      } catch {
+        // An unreachable daemon falls back to event-driven retirement when its
+        // authenticated sockets close and it can prove itself empty.
+      }
+    }
     this.client.disconnect()
   }
 
   private async ensureConnected(): Promise<void> {
-    await this.client.ensureConnected()
+    try {
+      await this.client.ensureConnected()
+    } finally {
+      // Why: a respawn launcher holds a temporary full pair until this adapter
+      // has attempted its permanent reconnect, preventing both gaps and leaks.
+      this.releasePendingRespawnAdoptionLease()
+    }
     // Why sampled before setupEventRouting: routing is (re)installed exactly
     // once per connection, so "no listener yet" identifies a fresh connect —
     // the only time the daemon-side backgrounded set needs a resync (it is
@@ -1298,7 +1334,15 @@ export class DaemonPtyAdapter implements IPtyProvider {
     try {
       return await fn()
     } catch (err) {
-      if (!this.respawnFn || !isDaemonGoneError(err)) {
+      // Why: self-retirement removes the token only after an authenticated
+      // endpoint dropped; an initial missing token may still hide a live daemon.
+      const missingRetiredEndpointToken =
+        isMissingTokenFileError(err) && this.client.hasObservedAuthenticatedDisconnect()
+      if (
+        this.respawnAdoptionClosed ||
+        !this.respawnFn ||
+        (!isDaemonGoneError(err) && !missingRetiredEndpointToken)
+      ) {
         throw err
       }
       if (!this.respawnPromise) {
@@ -1307,7 +1351,13 @@ export class DaemonPtyAdapter implements IPtyProvider {
         })
       }
       await this.respawnPromise
-      return await fn()
+      try {
+        return await fn()
+      } finally {
+        // Why: the retried operation may reject before it reaches a connection
+        // attempt (for example, a tombstone racing respawn).
+        this.releasePendingRespawnAdoptionLease()
+      }
     }
   }
 
@@ -1371,7 +1421,20 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.removeEventListener?.()
     this.removeEventListener = null
     this.client.disconnect()
-    await this.respawnFn!()
+    const releaseAdoptionLease = await this.respawnFn!()
+    if (this.respawnAdoptionClosed) {
+      // Why: app teardown may win while the launcher is still acquiring its
+      // temporary pair; a late result must not reinstall a lease nobody owns.
+      releaseAdoptionLease?.()
+      throw new Error('Daemon adapter closed during respawn')
+    }
+    this.pendingRespawnAdoptionRelease = releaseAdoptionLease ?? null
+  }
+
+  private releasePendingRespawnAdoptionLease(): void {
+    const release = this.pendingRespawnAdoptionRelease
+    this.pendingRespawnAdoptionRelease = null
+    release?.()
   }
 
   private setupEventRouting(): void {
@@ -1476,5 +1539,18 @@ function isDaemonGoneError(err: unknown): boolean {
     return true
   }
   const msg = err.message
-  return msg === 'Connection lost' || msg === 'Not connected' || msg === 'Hello response timed out'
+  return (
+    msg === 'Connection lost' ||
+    msg === 'Not connected' ||
+    msg === 'Hello response timed out' ||
+    msg === 'Daemon temporarily unavailable; reconnect'
+  )
+}
+
+function isMissingTokenFileError(err: unknown): boolean {
+  if (!(err instanceof Error)) {
+    return false
+  }
+  const errno = err as NodeJS.ErrnoException
+  return errno.code === 'ENOENT' && errno.syscall === 'open'
 }
diff --git a/src/main/daemon/daemon-self-retirement-respawn.test.ts b/src/main/daemon/daemon-self-retirement-respawn.test.ts
new file mode 100644
index 00000000000..a7184272111
--- /dev/null
+++ b/src/main/daemon/daemon-self-retirement-respawn.test.ts
@@ -0,0 +1,228 @@
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { DaemonPtyAdapter } from './daemon-pty-adapter'
+import { DaemonServer } from './daemon-server'
+import { getDaemonSocketPath } from './daemon-spawner'
+import type { SubprocessHandle } from './session'
+
+function fixtureSubprocess(): SubprocessHandle {
+  let onExit: ((code: number) => void) | null = null
+  return {
+    pid: process.pid,
+    getForegroundProcess: () => null,
+    write: () => {},
+    resize: () => {},
+    kill: () => queueMicrotask(() => onExit?.(0)),
+    forceKill: () => queueMicrotask(() => onExit?.(137)),
+    signal: () => {},
+    onData: () => {},
+    onExit: (callback) => {
+      onExit = callback
+    },
+    dispose: () => {}
+  }
+}
+
+async function waitFor(predicate: () => boolean): Promise<void> {
+  const deadline = Date.now() + 2_000
+  while (!predicate()) {
+    if (Date.now() >= deadline) {
+      throw new Error('Timed out waiting for daemon disconnect')
+    }
+    await new Promise((resolve) => setTimeout(resolve, 5))
+  }
+}
+
+describe('daemon self-retirement respawn', () => {
+  let dir: string
+  let socketPath: string
+  let tokenPath: string
+  let server: DaemonServer | null
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'daemon-retirement-respawn-'))
+    socketPath = getDaemonSocketPath(dir)
+    tokenPath = join(dir, 'daemon.token')
+    server = null
+  })
+
+  afterEach(async () => {
+    await server?.shutdown().catch(() => {})
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  async function startServer(): Promise<DaemonServer> {
+    const next = new DaemonServer({
+      socketPath,
+      tokenPath,
+      spawnSubprocess: () => fixtureSubprocess()
+    })
+    await next.start()
+    server = next
+    return next
+  }
+
+  it('coalesces respawn after an authenticated endpoint removes its token', async () => {
+    const original = await startServer()
+    const respawn = vi.fn(async () => {
+      await startServer()
+    })
+    const adapter = new DaemonPtyAdapter({ socketPath, tokenPath, respawn })
+    await adapter.listProcesses()
+    const client = (
+      adapter as unknown as {
+        client: { hasObservedAuthenticatedDisconnect(): boolean }
+      }
+    ).client
+
+    await original.shutdown()
+    await waitFor(() => client.hasObservedAuthenticatedDisconnect())
+
+    await Promise.all([
+      adapter.spawn({ sessionId: 'first', cols: 80, rows: 24 }),
+      adapter.spawn({ sessionId: 'second', cols: 80, rows: 24 })
+    ])
+
+    expect(respawn).toHaveBeenCalledTimes(1)
+    adapter.dispose()
+  })
+
+  it('releases the temporary respawn lease before clean retirement', async () => {
+    const original = await startServer()
+    let temporaryAdapter: DaemonPtyAdapter | null = null
+    const releaseTemporaryLease = vi.fn(() => temporaryAdapter?.dispose())
+    const respawn = vi.fn(async () => {
+      await startServer()
+      temporaryAdapter = new DaemonPtyAdapter({ socketPath, tokenPath })
+      await temporaryAdapter.establishLifecycleLease()
+      return releaseTemporaryLease
+    })
+    const adapter = new DaemonPtyAdapter({ socketPath, tokenPath, respawn })
+    await adapter.listProcesses()
+    const client = (
+      adapter as unknown as {
+        client: { hasObservedAuthenticatedDisconnect(): boolean }
+      }
+    ).client
+    await original.shutdown()
+    await waitFor(() => client.hasObservedAuthenticatedDisconnect())
+
+    await adapter.spawn({ sessionId: 'respawned', cols: 80, rows: 24 })
+    expect(releaseTemporaryLease).toHaveBeenCalledOnce()
+    await adapter.shutdown('respawned', { immediate: true })
+    await adapter.disconnectOnly()
+
+    await waitFor(() => !existsSync(tokenPath))
+  })
+
+  it('releases a temporary lease when a tombstone wins the respawn race', async () => {
+    const original = await startServer()
+    let temporaryAdapter: DaemonPtyAdapter | null = null
+    const releaseTemporaryLease = vi.fn(() => temporaryAdapter?.dispose())
+    let adapter!: DaemonPtyAdapter
+    const respawn = vi.fn(async () => {
+      await startServer()
+      temporaryAdapter = new DaemonPtyAdapter({ socketPath, tokenPath })
+      await temporaryAdapter.establishLifecycleLease()
+      const tombstones = (adapter as unknown as { killedSessionTombstones: Map<string, number> })
+        .killedSessionTombstones
+      tombstones.set('closed-during-respawn', Date.now())
+      return releaseTemporaryLease
+    })
+    adapter = new DaemonPtyAdapter({ socketPath, tokenPath, respawn })
+    await adapter.listProcesses()
+    const client = (
+      adapter as unknown as {
+        client: { hasObservedAuthenticatedDisconnect(): boolean }
+      }
+    ).client
+    await original.shutdown()
+    await waitFor(() => client.hasObservedAuthenticatedDisconnect())
+
+    await expect(
+      adapter.spawn({ sessionId: 'closed-during-respawn', cols: 80, rows: 24 })
+    ).rejects.toThrow('was explicitly killed')
+
+    expect(releaseTemporaryLease).toHaveBeenCalledOnce()
+    adapter.dispose()
+  })
+
+  it('releases a lease returned after disposal and does not reconnect', async () => {
+    const original = await startServer()
+    let temporaryAdapter: DaemonPtyAdapter | null = null
+    const releaseTemporaryLease = vi.fn(() => temporaryAdapter?.dispose())
+    let returnRespawnLease!: () => void
+    const respawn = vi.fn(async () => {
+      await startServer()
+      temporaryAdapter = new DaemonPtyAdapter({ socketPath, tokenPath })
+      await temporaryAdapter.establishLifecycleLease()
+      await new Promise<void>((resolve) => {
+        returnRespawnLease = resolve
+      })
+      return releaseTemporaryLease
+    })
+    const adapter = new DaemonPtyAdapter({ socketPath, tokenPath, respawn })
+    await adapter.listProcesses()
+    const client = (
+      adapter as unknown as {
+        client: { hasObservedAuthenticatedDisconnect(): boolean; isConnected(): boolean }
+      }
+    ).client
+    await original.shutdown()
+    await waitFor(() => client.hasObservedAuthenticatedDisconnect())
+
+    const spawn = adapter.spawn({ sessionId: 'disposed', cols: 80, rows: 24 })
+    await waitFor(() => returnRespawnLease !== undefined)
+    adapter.dispose()
+    returnRespawnLease()
+
+    await expect(spawn).rejects.toThrow('closed during respawn')
+    expect(releaseTemporaryLease).toHaveBeenCalledOnce()
+    expect(client.isConnected()).toBe(false)
+  })
+
+  it('does not start a respawn after disposal rejects an in-flight operation', async () => {
+    await startServer()
+    const respawn = vi.fn(async () => {})
+    const adapter = new DaemonPtyAdapter({ socketPath, tokenPath, respawn })
+    await adapter.establishLifecycleLease()
+    let rejectCreate!: (error: Error) => void
+    const client = (
+      adapter as unknown as {
+        client: {
+          request: (method: string, params: unknown) => Promise<unknown>
+        }
+      }
+    ).client
+    vi.spyOn(client, 'request').mockImplementationOnce(
+      () =>
+        new Promise((_, reject) => {
+          rejectCreate = reject
+        })
+    )
+
+    const spawn = adapter.spawn({ sessionId: 'disposed-in-flight', cols: 80, rows: 24 })
+    await waitFor(() => rejectCreate !== undefined)
+    adapter.dispose()
+    rejectCreate(new Error('Connection lost'))
+
+    await expect(spawn).rejects.toThrow('Connection lost')
+    expect(respawn).not.toHaveBeenCalled()
+  })
+
+  it('does not treat an initial missing token as respawn authority', async () => {
+    const respawn = vi.fn(async () => {})
+    const adapter = new DaemonPtyAdapter({ socketPath, tokenPath, respawn })
+
+    await expect(adapter.spawn({ sessionId: 'missing', cols: 80, rows: 24 })).rejects.toMatchObject(
+      {
+        code: 'ENOENT'
+      }
+    )
+
+    expect(respawn).not.toHaveBeenCalled()
+    adapter.dispose()
+  })
+})
diff --git a/src/main/daemon/daemon-server.test.ts b/src/main/daemon/daemon-server.test.ts
index 40a624103cc..aedf2384e08 100644
--- a/src/main/daemon/daemon-server.test.ts
+++ b/src/main/daemon/daemon-server.test.ts
@@ -2,13 +2,13 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { connect, type Server, type Socket } from 'node:net'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { existsSync, mkdtempSync, rmSync, readFileSync } from 'node:fs'
+import { existsSync, mkdtempSync, rmSync, readFileSync, writeFileSync } from 'node:fs'
 import { DaemonServer } from './daemon-server'
 import { DaemonClient } from './client'
 import { encodeNdjson } from './ndjson'
 import { PROTOCOL_VERSION, type DaemonRequest } from './types'
 import type { SubprocessHandle } from './session'
-import { getDaemonSocketPath } from './daemon-spawner'
+import { getDaemonPidPath, getDaemonSocketPath, serializeDaemonPidFile } from './daemon-spawner'
 
 const confirmForegroundProcessMock = vi.fn(async () => 'droid')
 
@@ -58,6 +58,7 @@ type DaemonServerPrivate = {
       clientId: string
       controlSocket: Socket
       streamSocket: Socket | null
+      authenticatedPairEstablished: boolean
     }
   >
   routeRequest(clientId: string, request: DaemonRequest): Promise<unknown>
@@ -67,6 +68,7 @@ describe('DaemonServer', () => {
   let dir: string
   let socketPath: string
   let tokenPath: string
+  let pidPath: string
   let server: DaemonServer
   let client: DaemonClient
 
@@ -75,6 +77,7 @@ describe('DaemonServer', () => {
     dir = createTestDir()
     socketPath = getDaemonSocketPath(dir)
     tokenPath = join(dir, 'test.token')
+    pidPath = getDaemonPidPath(dir)
   })
 
   afterEach(async () => {
@@ -83,10 +86,11 @@ describe('DaemonServer', () => {
     rmSync(dir, { recursive: true, force: true })
   })
 
-  async function startServer(): Promise<void> {
+  async function startServer(launchNonce?: string): Promise<void> {
     server = new DaemonServer({
       socketPath,
       tokenPath,
+      ...(launchNonce ? { pidPath, launchNonce } : {}),
       spawnSubprocess: () => createMockSubprocess()
     })
     await server.start()
@@ -290,12 +294,12 @@ describe('DaemonServer', () => {
         spawnSubprocess
       })
       await server.start()
-      const daemon = server as unknown as DaemonServerPrivate
+      const c = await connectClient()
 
-      const create = daemon.routeRequest('shutdown-client', {
-        id: 'shutdown-create',
-        type: 'createOrAttach',
-        payload: { sessionId: 'shutdown-pending', cols: 80, rows: 24 }
+      const create = c.request('createOrAttach', {
+        sessionId: 'shutdown-pending',
+        cols: 80,
+        rows: 24
       })
       const canceledCreate = expect(create).rejects.toThrow(
         'Attach canceled for session shutdown-pending'
@@ -535,7 +539,8 @@ describe('DaemonServer', () => {
         daemon.clients.set('client-1', {
           clientId: 'client-1',
           controlSocket,
-          streamSocket
+          streamSocket,
+          authenticatedPairEstablished: true
         })
 
         await daemon.routeRequest('client-1', {
@@ -591,7 +596,8 @@ describe('DaemonServer', () => {
         daemon.clients.set('client-1', {
           clientId: 'client-1',
           controlSocket,
-          streamSocket
+          streamSocket,
+          authenticatedPairEstablished: true
         })
 
         await daemon.routeRequest('client-1', {
@@ -648,7 +654,8 @@ describe('DaemonServer', () => {
         daemon.clients.set('client-1', {
           clientId: 'client-1',
           controlSocket,
-          streamSocket
+          streamSocket,
+          authenticatedPairEstablished: true
         })
         await daemon.routeRequest('client-1', {
           id: 'req-1',
@@ -780,6 +787,68 @@ describe('DaemonServer', () => {
   })
 
   describe('shutdown', () => {
+    it('waits for the ordinary shutdown reply write before destroying resources', async () => {
+      await startServer()
+      const c = await connectClient()
+      const daemon = server as unknown as DaemonServerPrivate & {
+        host: { dispose: () => Promise<void> }
+      }
+      const controlSocket = [...daemon.clients.values()][0].controlSocket
+      const originalWrite = controlSocket.write.bind(controlSocket)
+      let replyFlushed: (() => void) | undefined
+      vi.spyOn(controlSocket, 'write').mockImplementation(((
+        chunk: string | Uint8Array,
+        ...args: unknown[]
+      ) => {
+        replyFlushed = args.find((arg) => typeof arg === 'function') as (() => void) | undefined
+        return originalWrite(chunk)
+      }) as unknown as Socket['write'])
+      const dispose = vi.spyOn(daemon.host, 'dispose')
+
+      await expect(c.request('shutdown', { killSessions: false })).resolves.toEqual({})
+      expect(dispose).not.toHaveBeenCalled()
+      expect(existsSync(tokenPath)).toBe(true)
+
+      replyFlushed?.()
+      await waitFor(() => !existsSync(tokenPath))
+      expect(dispose).toHaveBeenCalledOnce()
+    })
+
+    it('removes only its owned token and PID record', async () => {
+      const launchNonce = 'ordinary-shutdown'
+      writeFileSync(
+        pidPath,
+        serializeDaemonPidFile({ pid: process.pid, startedAtMs: null, launchNonce })
+      )
+      await startServer(launchNonce)
+
+      await server.shutdown()
+
+      expect(existsSync(tokenPath)).toBe(false)
+      expect(existsSync(pidPath)).toBe(false)
+    })
+
+    it('preserves token and PID artifacts replaced before ordinary cleanup', async () => {
+      await startServer('mine')
+      writeFileSync(tokenPath, 'replacement-token')
+      writeFileSync(
+        pidPath,
+        serializeDaemonPidFile({
+          pid: process.pid,
+          startedAtMs: null,
+          launchNonce: 'replacement'
+        })
+      )
+
+      await server.shutdown()
+
+      expect(readFileSync(tokenPath, 'utf8')).toBe('replacement-token')
+      expect(JSON.parse(readFileSync(pidPath, 'utf8'))).toMatchObject({
+        pid: process.pid,
+        launchNonce: 'replacement'
+      })
+    })
+
     it('stops accepting connections after shutdown', async () => {
       await startServer()
       await server.shutdown()
@@ -800,9 +869,7 @@ describe('DaemonServer', () => {
       )
 
       const c = await connectClient()
-      // The daemon may self-terminate before the reply flushes; callers treat
-      // that as success, so only the observable teardown below is asserted.
-      await c.request('shutdown', { killSessions: true }).catch(() => {})
+      await expect(c.request('shutdown', { killSessions: true })).resolves.toEqual({})
 
       await waitFor(() => daemon.server === null)
       await waitFor(() => !existsSync(socketPath))
diff --git a/src/main/daemon/daemon-server.ts b/src/main/daemon/daemon-server.ts
index c5d6c04dfee..15ec9fecd21 100644
--- a/src/main/daemon/daemon-server.ts
+++ b/src/main/daemon/daemon-server.ts
@@ -4,7 +4,7 @@
 import { createServer, type Server, type Socket } from 'node:net'
 import { randomUUID } from 'node:crypto'
 import { performance } from 'node:perf_hooks'
-import { writeFileSync, chmodSync, unlinkSync } from 'node:fs'
+import { writeFileSync, chmodSync } from 'node:fs'
 import { StringDecoder } from 'node:string_decoder'
 import { encodeNdjson, createNdjsonParser } from './ndjson'
 import { TerminalHost } from './terminal-host'
@@ -23,7 +23,9 @@ import type { SubprocessHandle } from './session'
 import { checkPtySpawnHealth } from './pty-subprocess'
 import { createNoopDaemonFileLog, type DaemonFileLog } from './daemon-file-log'
 import { isTuiAgent } from '../../shared/tui-agent-config'
+import { unlinkOwnedDaemonPidFile, unlinkOwnedDaemonTokenFile } from './daemon-spawner'
 import {
+  CLEAN_DISCONNECT_PROTOCOL_VERSION,
   PROTOCOL_VERSION,
   NOTIFY_PREFIX,
   SessionNotFoundError,
@@ -35,6 +37,21 @@ import {
 export type DaemonServerOptions = {
   socketPath: string
   tokenPath: string
+  pidPath?: string
+  launchNonce?: string
+  startedAtMs?: number
+  /** Direct-construction seam for protocol fixture tests; production never overrides it. */
+  protocolVersion?: number
+  onIdleShutdown?: () => void
+  /** Direct-construction-only controls; production uses the compiled initial-adoption timeout. */
+  initialAdoptionTestConfig?: {
+    timeoutMs: number
+    clock: {
+      setTimeout(callback: () => void, delayMs: number): unknown
+      clearTimeout(handle: unknown): void
+      now(): number
+    }
+  }
   ptySpawnHealthCheck?: () => Promise<void>
   preparePtySpawn?: () => Promise<void>
   log?: DaemonFileLog
@@ -53,21 +70,46 @@ type ConnectedClient = {
   clientId: string
   controlSocket: Socket
   streamSocket: Socket | null
+  authenticatedPairEstablished: boolean
 }
 
 type PendingPtySpawnPreparation = {
   canceled: boolean
 }
 
+type PendingShutdownReply = {
+  start: () => void
+}
+
 export class DaemonServer {
+  // Why: a new daemon must survive long enough for its first client pair, but
+  // a parent crash between launch and adoption must not orphan it forever.
+  private static readonly INITIAL_ADOPTION_TIMEOUT_MS = 2 * 60 * 1000
+  private static readonly SHUTDOWN_REPLY_FLUSH_TIMEOUT_MS = 1_000
   private server: Server | null = null
   private token: string
   private host: TerminalHost
   private socketPath: string
   private tokenPath: string
+  private pidPath: string | null
+  private launchNonce: string | null
+  private startedAtMs: number | null
+  private protocolVersion: number
+  private onIdleShutdown: () => void
   private ptySpawnHealthCheck: () => Promise<void>
   private preparePtySpawn: () => Promise<void>
   private log: DaemonFileLog
+  private transportSockets = new Set<Socket>()
+  private createOrAttachInFlight = 0
+  private idleShutdownState: 'running' | 'idle-shutdown-pending' | 'shutting-down' = 'running'
+  private initialAdoptionTimer: unknown | null = null
+  private initialAdoptionDeadlineMs: number | null = null
+  private retirementRequested = false
+  private shutdownPromise: Promise<void> | null = null
+  private ordinaryShutdownServerClose: Promise<void> | null = null
+  private pendingShutdownReplies = new Map<string, PendingShutdownReply>()
+  private initialAdoptionTimeoutMs: number
+  private lifecycleClock: NonNullable<DaemonServerOptions['initialAdoptionTestConfig']>['clock']
 
   private clients = new Map<string, ConnectedClient>()
   private streamDataBatcher = new DaemonStreamDataBatcher(
@@ -116,6 +158,28 @@ export class DaemonServer {
   constructor(opts: DaemonServerOptions) {
     this.socketPath = opts.socketPath
     this.tokenPath = opts.tokenPath
+    this.pidPath = opts.pidPath ?? null
+    this.protocolVersion = opts.protocolVersion ?? PROTOCOL_VERSION
+    this.launchNonce =
+      opts.launchNonce ??
+      (this.protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION ? randomUUID() : null)
+    this.startedAtMs =
+      opts.startedAtMs ??
+      (this.protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION
+        ? Date.now() - process.uptime() * 1000
+        : null)
+    this.onIdleShutdown = opts.onIdleShutdown ?? (() => {})
+    this.initialAdoptionTimeoutMs =
+      opts.initialAdoptionTestConfig?.timeoutMs ?? DaemonServer.INITIAL_ADOPTION_TIMEOUT_MS
+    this.lifecycleClock = opts.initialAdoptionTestConfig?.clock ?? {
+      setTimeout: (callback, delayMs) => {
+        const timer = setTimeout(callback, delayMs)
+        timer.unref()
+        return timer
+      },
+      clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+      now: () => Date.now()
+    }
     this.token = randomUUID()
     this.host = new TerminalHost({ spawnSubprocess: opts.spawnSubprocess })
     this.ptySpawnHealthCheck = opts.ptySpawnHealthCheck ?? checkPtySpawnHealth
@@ -150,12 +214,48 @@ export class DaemonServer {
         } catch {
           // Best-effort on platforms that support it
         }
+        if (this.protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
+          // Why: a parent crash before the first full client pair must not leave
+          // a freshly published, empty daemon alive forever.
+          this.armInitialAdoptionTimeout()
+        }
         resolve()
       })
     })
   }
 
   async shutdown(): Promise<void> {
+    if (this.shutdownPromise) {
+      return this.shutdownPromise
+    }
+    const serverClose = this.beginOrdinaryShutdownFence()
+    this.shutdownPromise = this.finishOrdinaryShutdown(serverClose)
+    return this.shutdownPromise
+  }
+
+  private beginOrdinaryShutdownFence(): Promise<void> {
+    this.idleShutdownState = 'shutting-down'
+    this.cancelInitialAdoptionTimer()
+    this.ordinaryShutdownServerClose ??= this.beginServerClose()
+    return this.ordinaryShutdownServerClose
+  }
+
+  private async finishOrdinaryShutdown(serverClose: Promise<void>): Promise<void> {
+    this.unlinkOwnedEndpointArtifacts()
+    await this.disposeDaemonResources()
+    await serverClose
+  }
+
+  private unlinkOwnedEndpointArtifacts(): void {
+    // Why: close has already fenced this endpoint, but ownership checks still
+    // prevent a late replacement's canonical token or PID record from removal.
+    unlinkOwnedDaemonTokenFile(this.tokenPath, this.token)
+    if (this.pidPath && this.launchNonce) {
+      unlinkOwnedDaemonPidFile(this.pidPath, process.pid, this.launchNonce)
+    }
+  }
+
+  private async disposeDaemonResources(): Promise<void> {
     this.stopStreamBacklogProbe()
     this.transientFactRelay.dispose()
     this.cancelAllPendingPtySpawnPreparations()
@@ -169,29 +269,142 @@ export class DaemonServer {
       })
     }
     this.streamDataBatcher.clear()
+    this.pendingShutdownReplies.clear()
 
     for (const [, client] of this.clients) {
       client.controlSocket.destroy()
       client.streamSocket?.destroy()
     }
     this.clients.clear()
+    for (const socket of this.transportSockets) {
+      socket.destroy()
+    }
+    this.transportSockets.clear()
+  }
 
+  private beginServerClose(): Promise<void> {
+    const server = this.server
+    this.server = null
+    if (!server) {
+      return Promise.resolve()
+    }
     return new Promise<void>((resolve) => {
-      if (this.server) {
-        this.server.close(() => {
-          try {
-            unlinkSync(this.socketPath)
-          } catch {}
-          resolve()
-        })
-        this.server = null
-      } else {
+      // Why: call close synchronously before any awaited cleanup so no new
+      // transport can enter after the idle fence is proven empty.
+      server.close(() => {
+        // Node owns unlinking its Unix listener. An extra check-then-unlink here could
+        // delete a replacement endpoint installed concurrently after close.
         resolve()
-      }
+      })
     })
   }
 
+  private isIdle(): boolean {
+    return (
+      this.transportSockets.size === 0 &&
+      this.clients.size === 0 &&
+      this.createOrAttachInFlight === 0 &&
+      this.host.listSessions().length === 0
+    )
+  }
+
+  private reevaluateIdleShutdown(): void {
+    if (this.idleShutdownState !== 'running') {
+      return
+    }
+    if (this.retirementRequested) {
+      this.cancelInitialAdoptionTimer()
+      if (this.isIdle()) {
+        this.beginIdleShutdown()
+      }
+      return
+    }
+    if (!this.isIdle() || this.initialAdoptionDeadlineMs === null) {
+      this.cancelInitialAdoptionTimer()
+      return
+    }
+    if (this.initialAdoptionTimer !== null) {
+      return
+    }
+    const remainingMs = Math.max(0, this.initialAdoptionDeadlineMs - this.lifecycleClock.now())
+    if (remainingMs === 0) {
+      this.initialAdoptionDeadlineMs = null
+      this.retirementRequested = true
+      this.beginIdleShutdown()
+      return
+    }
+    this.initialAdoptionTimer = this.lifecycleClock.setTimeout(() => {
+      this.initialAdoptionTimer = null
+      this.initialAdoptionDeadlineMs = null
+      this.retirementRequested = true
+      this.beginIdleShutdown()
+    }, remainingMs)
+  }
+
+  private armInitialAdoptionTimeout(): void {
+    this.initialAdoptionDeadlineMs = this.lifecycleClock.now() + this.initialAdoptionTimeoutMs
+    this.reevaluateIdleShutdown()
+  }
+
+  private cancelInitialAdoptionTimer(): void {
+    if (this.initialAdoptionTimer === null) {
+      return
+    }
+    this.lifecycleClock.clearTimeout(this.initialAdoptionTimer)
+    this.initialAdoptionTimer = null
+  }
+
+  private beginIdleShutdown(): void {
+    this.initialAdoptionTimer = null
+    if (this.idleShutdownState !== 'running') {
+      return
+    }
+    this.idleShutdownState = 'idle-shutdown-pending'
+    if (!this.isIdle()) {
+      // Why: work admitted before the fence wins. Clearing the pending state
+      // keeps that already-started client/session fully usable.
+      this.idleShutdownState = 'running'
+      this.reevaluateIdleShutdown()
+      return
+    }
+
+    this.idleShutdownState = 'shutting-down'
+    // beginServerClose() runs synchronously up to server.close(), before host
+    // disposal or file cleanup can yield to a racing connection.
+    const serverClose = this.beginServerClose()
+    this.shutdownPromise = this.finishIdleShutdown(serverClose)
+  }
+
+  private async finishIdleShutdown(serverClose: Promise<void>): Promise<void> {
+    this.unlinkOwnedEndpointArtifacts()
+    await this.disposeDaemonResources()
+    await serverClose
+    this.onIdleShutdown()
+  }
+
   private handleConnection(socket: Socket): void {
+    this.cancelInitialAdoptionTimer()
+    this.transportSockets.add(socket)
+    const removeTransport = (): void => {
+      this.transportSockets.delete(socket)
+      this.reevaluateIdleShutdown()
+    }
+    socket.once('close', removeTransport)
+    socket.on('error', () => socket.destroy())
+
+    if (this.idleShutdownState !== 'running') {
+      // Why: an accepted connection queued just before server.close() must get
+      // an explicit retry signal instead of appearing authenticated then dying.
+      socket.end(
+        encodeNdjson({
+          type: 'hello',
+          ok: false,
+          error: 'Daemon temporarily unavailable; reconnect',
+          retryable: true
+        })
+      )
+      return
+    }
     // Why: clients can send multibyte prompt/input text split across socket
     // chunks; keep UTF-8 sequences intact before NDJSON parsing.
     const decoder = new StringDecoder('utf8')
@@ -203,7 +416,6 @@ export class DaemonServer {
     )
 
     socket.on('data', (chunk) => parser.feed(decoder.write(chunk)))
-    socket.on('error', () => socket.destroy())
   }
 
   private handleFirstMessage(
@@ -219,7 +431,7 @@ export class DaemonServer {
       return
     }
 
-    if (hello.version !== PROTOCOL_VERSION) {
+    if (hello.version !== this.protocolVersion) {
       this.log.log('client-hello-rejected', {
         reason: 'protocol-mismatch',
         clientVersion: hello.version
@@ -237,18 +449,34 @@ export class DaemonServer {
     }
 
     this.log.log('client-hello-accepted', { role: hello.role, clientId: hello.clientId })
-    socket.write(encodeNdjson({ type: 'hello', ok: true }))
+    socket.write(
+      encodeNdjson({
+        type: 'hello',
+        ok: true,
+        ...(this.launchNonce && this.startedAtMs
+          ? {
+              daemonIdentity: {
+                pid: process.pid,
+                startedAtMs: this.startedAtMs,
+                launchNonce: this.launchNonce
+              }
+            }
+          : {})
+      })
+    )
 
     if (hello.role === 'control') {
       const previous = this.clients.get(hello.clientId)
       const client: ConnectedClient = {
         clientId: hello.clientId,
         controlSocket: socket,
-        streamSocket: null
+        streamSocket: null,
+        authenticatedPairEstablished: false
       }
       this.clients.set(hello.clientId, client)
       this.setupControlSocket(socket, hello.clientId)
       if (previous) {
+        this.recordFullyAuthenticatedDisconnect(previous.authenticatedPairEstablished)
         // Why: a reconnect can reuse a clientId before the old sockets notice
         // their close. Tear them down after installing the new owner so stale
         // close events cannot delete the replacement client entry.
@@ -264,6 +492,12 @@ export class DaemonServer {
         return
       }
       this.setupStreamSocket(socket, client)
+      client.authenticatedPairEstablished = true
+      // A complete app connection, unlike a health or raw socket probe, owns
+      // the endpoint again and cancels pending event-driven retirement.
+      this.initialAdoptionDeadlineMs = null
+      this.retirementRequested = false
+      this.cancelInitialAdoptionTimer()
     }
   }
 
@@ -285,12 +519,28 @@ export class DaemonServer {
       if (client?.controlSocket !== socket) {
         return
       }
+      const wasFullyAuthenticated = client.authenticatedPairEstablished
       this.streamDataBatcher.clear(clientId)
       client.streamSocket?.destroy()
       this.clients.delete(clientId)
+      this.recordFullyAuthenticatedDisconnect(wasFullyAuthenticated)
+      this.reevaluateIdleShutdown()
     })
   }
 
+  private recordFullyAuthenticatedDisconnect(wasFullyAuthenticated: boolean): void {
+    if (
+      !wasFullyAuthenticated ||
+      [...this.clients.values()].some((remaining) => remaining.authenticatedPairEstablished) ||
+      this.idleShutdownState !== 'running'
+    ) {
+      return
+    }
+    // Why: once the last full client is gone, exact daemon-side emptiness is
+    // sufficient; incomplete transports may block but never erase this request.
+    this.retirementRequested = true
+  }
+
   private setupStreamSocket(socket: Socket, client: ConnectedClient): void {
     const previous = client.streamSocket
     socket.removeAllListeners('data')
@@ -330,7 +580,12 @@ export class DaemonServer {
     try {
       const result = await this.routeRequest(clientId, request)
       if (!isNotify) {
-        socket.write(encodeNdjson({ id: request.id, ok: true, payload: result }))
+        const pendingShutdown = this.pendingShutdownReplies.get(
+          this.shutdownReplyKey(clientId, request.id)
+        )
+        socket.write(encodeNdjson({ id: request.id, ok: true, payload: result }), () => {
+          pendingShutdown?.start()
+        })
       }
     } catch (err) {
       if (!isNotify) {
@@ -345,6 +600,41 @@ export class DaemonServer {
     }
   }
 
+  private shutdownReplyKey(clientId: string, requestId: string): string {
+    return `${clientId}\u0000${requestId}`
+  }
+
+  private deferShutdownUntilReply(
+    clientId: string,
+    requestId: string,
+    socket: Socket,
+    finish: () => Promise<void>
+  ): void {
+    const key = this.shutdownReplyKey(clientId, requestId)
+    let started = false
+    let timer: ReturnType<typeof setTimeout>
+    const start = (): void => {
+      if (started) {
+        return
+      }
+      started = true
+      clearTimeout(timer)
+      socket.off('close', start)
+      socket.off('error', start)
+      this.pendingShutdownReplies.delete(key)
+      if (!this.shutdownPromise) {
+        this.shutdownPromise = finish()
+      }
+    }
+    // Why: a non-reading authenticated peer must not pin a fenced daemon by
+    // holding its acknowledgement behind permanent socket backpressure.
+    timer = setTimeout(start, DaemonServer.SHUTDOWN_REPLY_FLUSH_TIMEOUT_MS)
+    timer.unref()
+    socket.once('close', start)
+    socket.once('error', start)
+    this.pendingShutdownReplies.set(key, { start })
+  }
+
   private async preparePtySpawnUnlessCanceled(sessionId: string): Promise<void> {
     const preparation: PendingPtySpawnPreparation = { canceled: false }
     const pending = this.pendingPtySpawnPreparations.get(sessionId) ?? new Set()
@@ -387,64 +677,80 @@ export class DaemonServer {
 
     switch (request.type) {
       case 'createOrAttach': {
+        if (this.idleShutdownState !== 'running') {
+          throw new Error('Daemon temporarily unavailable; reconnect')
+        }
+        if (!client?.authenticatedPairEstablished || client.streamSocket === null) {
+          // Why: a control-only replacement cannot own terminal admission or
+          // erase the prior full client's monotonic retirement request.
+          throw new Error('Daemon client connection is incomplete; reconnect')
+        }
+        this.createOrAttachInFlight++
         const p = request.payload
-        await this.preparePtySpawnUnlessCanceled(p.sessionId)
-        const result = await this.host.createOrAttach({
-          sessionId: p.sessionId,
-          cols: p.cols,
-          rows: p.rows,
-          cwd: p.cwd,
-          env: p.env,
-          envToDelete: p.envToDelete,
-          command: p.command,
-          startupCommandDelivery: p.startupCommandDelivery,
-          // Why: daemon RPC payloads are untrusted JSON. Persist only the
-          // allowlisted enum used for byte routing, never arbitrary identity.
-          ...(isTuiAgent(p.launchAgent) ? { launchAgent: p.launchAgent } : {}),
-          shellOverride: p.shellOverride,
-          terminalWindowsWslDistro: p.terminalWindowsWslDistro,
-          terminalWindowsPowerShellImplementation: p.terminalWindowsPowerShellImplementation,
-          shellReadySupported: p.shellReadySupported,
-          historySeed: p.historySeed,
-          ...(p.shellReadyTimeoutMs !== undefined
-            ? { shellReadyTimeoutMs: p.shellReadyTimeoutMs }
-            : {}),
-          streamClient: {
-            onData: (data) => {
-              // Scan BEFORE enqueue: the batcher may keep-tail drop this
-              // chunk, but its facts must be captured regardless.
-              this.transientFactRelay.onSessionData(p.sessionId, data)
-              const lastInputAt = this.lastInputAtBySessionId.get(p.sessionId)
-              const isInteractiveOutput =
-                data.length <= DaemonServer.INTERACTIVE_OUTPUT_MAX_CHARS &&
-                lastInputAt !== undefined &&
-                performance.now() - lastInputAt <= DaemonServer.INTERACTIVE_OUTPUT_WINDOW_MS
-              this.streamDataBatcher.enqueue(clientId, p.sessionId, data, {
-                flushImmediately: isInteractiveOutput,
-                flushMaxChars: DaemonServer.INTERACTIVE_OUTPUT_MAX_CHARS
-              })
-            },
-            onExit: (code) => {
-              // Why: exit tears down renderer handlers, so it must ride the
-              // ordered queue behind final output even when the shallow socket
-              // gate holds that output for a later drain pass.
-              this.log.log('session-exited', { sessionId: p.sessionId, code })
-              this.streamDataBatcher.enqueueControlEvent(clientId, p.sessionId, {
-                type: 'event',
-                event: 'exit',
-                sessionId: p.sessionId,
-                payload: { code }
-              })
-              this.streamDataBatcher.flush(clientId)
-              recordDaemonStreamBacklogEvent('sessionExit', {
-                sessionIdSuffix: p.sessionId.slice(-10)
-              })
-              this.transientFactRelay.onSessionExit(p.sessionId)
-              this.streamClientIdBySessionId.delete(p.sessionId)
-              this.lastInputAtBySessionId.delete(p.sessionId)
+        let result: Awaited<ReturnType<TerminalHost['createOrAttach']>>
+        try {
+          await this.preparePtySpawnUnlessCanceled(p.sessionId)
+          result = await this.host.createOrAttach({
+            sessionId: p.sessionId,
+            cols: p.cols,
+            rows: p.rows,
+            cwd: p.cwd,
+            env: p.env,
+            envToDelete: p.envToDelete,
+            command: p.command,
+            startupCommandDelivery: p.startupCommandDelivery,
+            // Why: daemon RPC payloads are untrusted JSON. Persist only the
+            // allowlisted enum used for byte routing, never arbitrary identity.
+            ...(isTuiAgent(p.launchAgent) ? { launchAgent: p.launchAgent } : {}),
+            shellOverride: p.shellOverride,
+            terminalWindowsWslDistro: p.terminalWindowsWslDistro,
+            terminalWindowsPowerShellImplementation: p.terminalWindowsPowerShellImplementation,
+            shellReadySupported: p.shellReadySupported,
+            historySeed: p.historySeed,
+            ...(p.shellReadyTimeoutMs !== undefined
+              ? { shellReadyTimeoutMs: p.shellReadyTimeoutMs }
+              : {}),
+            streamClient: {
+              onData: (data) => {
+                // Scan BEFORE enqueue: the batcher may keep-tail drop this
+                // chunk, but its facts must be captured regardless.
+                this.transientFactRelay.onSessionData(p.sessionId, data)
+                const lastInputAt = this.lastInputAtBySessionId.get(p.sessionId)
+                const isInteractiveOutput =
+                  data.length <= DaemonServer.INTERACTIVE_OUTPUT_MAX_CHARS &&
+                  lastInputAt !== undefined &&
+                  performance.now() - lastInputAt <= DaemonServer.INTERACTIVE_OUTPUT_WINDOW_MS
+                this.streamDataBatcher.enqueue(clientId, p.sessionId, data, {
+                  flushImmediately: isInteractiveOutput,
+                  flushMaxChars: DaemonServer.INTERACTIVE_OUTPUT_MAX_CHARS
+                })
+              },
+              onExit: (code) => {
+                // Why: exit tears down renderer handlers, so it must ride the
+                // ordered queue behind final output even when the shallow socket
+                // gate holds that output for a later drain pass.
+                this.log.log('session-exited', { sessionId: p.sessionId, code })
+                this.streamDataBatcher.enqueueControlEvent(clientId, p.sessionId, {
+                  type: 'event',
+                  event: 'exit',
+                  sessionId: p.sessionId,
+                  payload: { code }
+                })
+                this.streamDataBatcher.flush(clientId)
+                recordDaemonStreamBacklogEvent('sessionExit', {
+                  sessionIdSuffix: p.sessionId.slice(-10)
+                })
+                this.transientFactRelay.onSessionExit(p.sessionId)
+                this.streamClientIdBySessionId.delete(p.sessionId)
+                this.lastInputAtBySessionId.delete(p.sessionId)
+                this.reevaluateIdleShutdown()
+              }
             }
-          }
-        })
+          })
+        } finally {
+          this.createOrAttachInFlight--
+          this.reevaluateIdleShutdown()
+        }
         this.streamClientIdBySessionId.set(p.sessionId, clientId)
         // Why an attach-time marker: the adapter resyncs the background set on
         // a fresh connection, which can precede this attach — main's scan
@@ -599,6 +905,35 @@ export class DaemonServer {
       case 'listSessions':
         return { sessions: this.host.listSessions() }
 
+      case 'shutdownIfIdle': {
+        const authenticatedClient = this.clients.get(clientId)
+        const retiring =
+          authenticatedClient !== undefined &&
+          authenticatedClient.streamSocket !== null &&
+          this.clients.size === 1 &&
+          this.createOrAttachInFlight === 0 &&
+          this.host.listSessions().length === 0 &&
+          [...this.transportSockets].every(
+            (transport) =>
+              transport === authenticatedClient.controlSocket ||
+              transport === authenticatedClient.streamSocket
+          )
+        if (!retiring) {
+          return { retiring: false }
+        }
+        this.idleShutdownState = 'shutting-down'
+        this.initialAdoptionDeadlineMs = null
+        this.retirementRequested = false
+        this.cancelInitialAdoptionTimer()
+        // Why: close before acknowledging retirement so no new terminal can
+        // race between the empty proof and daemon disposal.
+        const serverClose = this.beginServerClose()
+        this.deferShutdownUntilReply(clientId, request.id, authenticatedClient.controlSocket, () =>
+          this.finishIdleShutdown(serverClose)
+        )
+        return { retiring: true }
+      }
+
       case 'getSnapshot': {
         const snapshotStart = performance.now()
         const requestedScrollbackRows = request.payload.scrollbackRows
@@ -644,11 +979,12 @@ export class DaemonServer {
         await this.ptySpawnHealthCheck()
         return { healthy: true }
 
-      case 'shutdown':
+      case 'shutdown': {
         this.log.log('shutdown', {
           reason: 'rpc',
           killSessions: request.payload.killSessions === true
         })
+        const serverClose = this.beginOrdinaryShutdownFence()
         if (request.payload.killSessions) {
           try {
             await this.host.dispose()
@@ -661,8 +997,16 @@ export class DaemonServer {
             })
           }
         }
-        process.nextTick(() => this.shutdown())
+        const controlSocket = this.clients.get(clientId)?.controlSocket
+        if (controlSocket) {
+          this.deferShutdownUntilReply(clientId, request.id, controlSocket, () =>
+            this.finishOrdinaryShutdown(serverClose)
+          )
+        } else if (!this.shutdownPromise) {
+          this.shutdownPromise = this.finishOrdinaryShutdown(serverClose)
+        }
         return {}
+      }
     }
     throw new Error(`Unknown request type: ${(request as { type: string }).type}`)
   }
diff --git a/src/main/daemon/daemon-spawner.test.ts b/src/main/daemon/daemon-spawner.test.ts
index f0367319ed5..613b9e6a149 100644
--- a/src/main/daemon/daemon-spawner.test.ts
+++ b/src/main/daemon/daemon-spawner.test.ts
@@ -1,12 +1,13 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { mkdtempSync, rmSync } from 'node:fs'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import {
   DaemonSpawner,
   getDaemonPidPath,
   getDaemonSocketPath,
-  getDaemonTokenPath
+  getDaemonTokenPath,
+  restoreClaimedDaemonArtifact
 } from './daemon-spawner'
 import { startDaemon, type DaemonHandle } from './daemon-main'
 import { DaemonClient } from './client'
@@ -70,6 +71,20 @@ describe('DaemonSpawner', () => {
   }
 
   describe('ensureRunning', () => {
+    it('passes the scoped PID path and a fresh launch nonce to the launcher', async () => {
+      const launcher = vi.fn(async () => ({ shutdown: vi.fn(async () => {}) }))
+      spawner = new DaemonSpawner({ runtimeDir: dir, launcher })
+
+      await spawner.ensureRunning()
+
+      expect(launcher).toHaveBeenCalledWith(
+        getDaemonSocketPath(dir),
+        getDaemonTokenPath(dir),
+        getDaemonPidPath(dir),
+        expect.stringMatching(/^[0-9a-f-]{36}$/)
+      )
+    })
+
     it('uses protocol-scoped socket and token paths', () => {
       const socketPath = getDaemonSocketPath(dir)
       const tokenPath = getDaemonTokenPath(dir)
@@ -172,3 +187,51 @@ describe('DaemonSpawner', () => {
     })
   })
 })
+
+describe('restoreClaimedDaemonArtifact', () => {
+  it('retains the unique claim when restoration fails without a replacement', () => {
+    expect(
+      restoreClaimedDaemonArtifact('/claimed', '/canonical', {
+        copyExclusive: () => {
+          throw new Error('injected ENOSPC')
+        },
+        canonicalExists: () => false
+      })
+    ).toBe(false)
+  })
+
+  it('retains the unique claim when a failed copy leaves a partial canonical file', () => {
+    const restoreDir = createTestDir()
+    const canonicalPath = join(restoreDir, 'partial-canonical')
+    try {
+      expect(
+        restoreClaimedDaemonArtifact('/claimed', canonicalPath, {
+          copyExclusive: () => {
+            writeFileSync(canonicalPath, 'partial')
+            throw Object.assign(new Error('injected ENOSPC'), { code: 'ENOSPC' })
+          },
+          canonicalExists: () => true
+        })
+      ).toBe(false)
+    } finally {
+      rmSync(restoreDir, { recursive: true, force: true })
+    }
+  })
+
+  it('allows claim cleanup after successful restore or a confirmed replacement', () => {
+    expect(
+      restoreClaimedDaemonArtifact('/claimed', '/canonical', {
+        copyExclusive: () => {},
+        canonicalExists: () => false
+      })
+    ).toBe(true)
+    expect(
+      restoreClaimedDaemonArtifact('/claimed', '/canonical', {
+        copyExclusive: () => {
+          throw Object.assign(new Error('injected EEXIST'), { code: 'EEXIST' })
+        },
+        canonicalExists: () => true
+      })
+    ).toBe(true)
+  })
+})
diff --git a/src/main/daemon/daemon-spawner.ts b/src/main/daemon/daemon-spawner.ts
index ef54ed9a25d..ba0ea239c67 100644
--- a/src/main/daemon/daemon-spawner.ts
+++ b/src/main/daemon/daemon-spawner.ts
@@ -1,4 +1,5 @@
-import { createHash } from 'node:crypto'
+import { createHash, randomUUID } from 'node:crypto'
+import { constants, copyFileSync, existsSync, readFileSync, renameSync, unlinkSync } from 'node:fs'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from './types'
 
@@ -12,14 +13,21 @@ export type DaemonPidFile = {
   startedAtMs: number | null
   entryPath?: string
   appVersion?: string
+  launchNonce?: string
 }
 
 export type DaemonProcessHandle = {
   mode?: 'degraded-new-pty-fallback'
+  releaseAdoptionLease?(): void
   shutdown(): Promise<void>
 }
 
-export type DaemonLauncher = (socketPath: string, tokenPath: string) => Promise<DaemonProcessHandle>
+export type DaemonLauncher = (
+  socketPath: string,
+  tokenPath: string,
+  pidPath?: string,
+  launchNonce?: string
+) => Promise<DaemonProcessHandle>
 
 export type DaemonSpawnerOptions = {
   runtimeDir: string
@@ -32,12 +40,14 @@ export class DaemonSpawner {
   private handle: DaemonProcessHandle | null = null
   private socketPath: string
   private tokenPath: string
+  private pidPath: string
 
   constructor(opts: DaemonSpawnerOptions) {
     this.runtimeDir = opts.runtimeDir
     this.launcher = opts.launcher
     this.socketPath = getDaemonSocketPath(this.runtimeDir)
     this.tokenPath = getDaemonTokenPath(this.runtimeDir)
+    this.pidPath = getDaemonPidPath(this.runtimeDir)
   }
 
   async ensureRunning(): Promise<DaemonConnectionInfo> {
@@ -45,7 +55,9 @@ export class DaemonSpawner {
       return { socketPath: this.socketPath, tokenPath: this.tokenPath }
     }
 
-    this.handle = await this.launcher(this.socketPath, this.tokenPath)
+    // Why: a detached daemon may clean up after its parent exits. A unique
+    // launch identity keeps it from deleting a replacement daemon's PID file.
+    this.handle = await this.launcher(this.socketPath, this.tokenPath, this.pidPath, randomUUID())
 
     return { socketPath: this.socketPath, tokenPath: this.tokenPath }
   }
@@ -96,3 +108,83 @@ export function getDaemonPidPath(runtimeDir: string, protocolVersion = PROTOCOL_
 export function serializeDaemonPidFile(pidFile: DaemonPidFile): string {
   return JSON.stringify(pidFile)
 }
+
+export function unlinkOwnedDaemonPidFile(
+  pidPath: string,
+  expectedPid: number,
+  expectedLaunchNonce: string
+): boolean {
+  return claimAndUnlinkOwnedFile(pidPath, (content) => {
+    try {
+      const parsed = JSON.parse(content) as { pid?: unknown; launchNonce?: unknown }
+      return parsed.pid === expectedPid && parsed.launchNonce === expectedLaunchNonce
+    } catch {
+      return false
+    }
+  })
+}
+
+export function unlinkOwnedDaemonTokenFile(tokenPath: string, expectedToken: string): boolean {
+  return claimAndUnlinkOwnedFile(tokenPath, (content) => content.trim() === expectedToken)
+}
+
+function claimAndUnlinkOwnedFile(
+  filePath: string,
+  ownsContent: (content: string) => boolean
+): boolean {
+  const claimedPath = `${filePath}.cleanup-${process.pid}-${randomUUID()}`
+  try {
+    // Why: rename claims one exact directory entry before inspection, so a replacement
+    // installed afterward stays at the canonical path and cannot be unlinked by us.
+    renameSync(filePath, claimedPath)
+  } catch {
+    return false
+  }
+  try {
+    if (ownsContent(readFileSync(claimedPath, 'utf8'))) {
+      unlinkSync(claimedPath)
+      return true
+    }
+  } catch {
+    // Restore below when the claimed file cannot be validated as ours.
+  }
+
+  const restoredOrReplaced = restoreClaimedDaemonArtifact(claimedPath, filePath)
+  if (restoredOrReplaced) {
+    try {
+      unlinkSync(claimedPath)
+    } catch {
+      // A uniquely named unowned claim is safer to leave than overwriting a replacement.
+    }
+  }
+  return false
+}
+
+export function restoreClaimedDaemonArtifact(
+  claimedPath: string,
+  canonicalPath: string,
+  operations: {
+    copyExclusive?: (source: string, target: string) => void
+    canonicalExists?: (path: string) => boolean
+  } = {}
+): boolean {
+  const copyExclusive =
+    operations.copyExclusive ??
+    ((source: string, target: string) => copyFileSync(source, target, constants.COPYFILE_EXCL))
+  const canonicalExists = operations.canonicalExists ?? existsSync
+  try {
+    // Why: exclusive restore never overwrites a newer canonical replacement.
+    copyExclusive(claimedPath, canonicalPath)
+    return true
+  } catch (error) {
+    // Why: copy failures can leave a partial canonical file. Only EEXIST proves
+    // another owner had already installed a replacement before our copy.
+    return (
+      typeof error === 'object' &&
+      error !== null &&
+      'code' in error &&
+      error.code === 'EEXIST' &&
+      canonicalExists(canonicalPath)
+    )
+  }
+}
diff --git a/src/main/daemon/production-launcher.test.ts b/src/main/daemon/production-launcher.test.ts
index 59b5c998f74..12edb3b8a7c 100644
--- a/src/main/daemon/production-launcher.test.ts
+++ b/src/main/daemon/production-launcher.test.ts
@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { mkdtempSync, rmSync } from 'node:fs'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { createProductionLauncher } from './production-launcher'
 import { startDaemon, type DaemonHandle } from './daemon-main'
 import { DaemonClient } from './client'
@@ -63,6 +63,20 @@ describe('createProductionLauncher', () => {
     expect(typeof launcher).toBe('function')
   })
 
+  it('rejects either ownership argument without its pair before forking', async () => {
+    const launcher = createProductionLauncher({
+      getDaemonEntryPath: () => '/fake/path.js'
+    })
+
+    await expect(
+      launcher(socketPathFor(dir), tokenPathFor(dir), join(dir, 'daemon.pid'))
+    ).rejects.toThrow('provided together')
+    await expect(
+      launcher(socketPathFor(dir), tokenPathFor(dir), undefined, 'launch-a')
+    ).rejects.toThrow('provided together')
+    expect(forkMock).not.toHaveBeenCalled()
+  })
+
   it('can be used with DaemonSpawner (in-process fallback)', async () => {
     // Use in-process launcher for testing (same as DaemonSpawner tests)
     const launcher = async (socketPath: string, tokenPath: string) => {
@@ -115,8 +129,9 @@ describe('createProductionLauncher', () => {
       getDaemonEntryPath: () => join(dir, 'daemon-entry.js')
     })
 
-    const launch = launcher(socketPathFor(dir), tokenPathFor(dir))
-    handlers.message[0]?.({ type: 'ready' })
+    const pidPath = join(dir, 'daemon.pid')
+    const launch = launcher(socketPathFor(dir), tokenPathFor(dir), pidPath, 'launch-a')
+    handlers.message[0]?.({ type: 'ready', startedAtMs: 123_456 })
     const handle = await launch
 
     expect(handle.shutdown).toEqual(expect.any(Function))
@@ -125,9 +140,73 @@ describe('createProductionLauncher', () => {
     expect(handlers.exit).toHaveLength(0)
     expect(child.disconnect).toHaveBeenCalled()
     expect(child.unref).toHaveBeenCalled()
+    expect(JSON.parse(readFileSync(pidPath, 'utf8'))).toEqual({
+      pid: 12345,
+      startedAtMs: 123_456,
+      entryPath: join(dir, 'daemon-entry.js'),
+      launchNonce: 'launch-a'
+    })
+    expect(forkMock).toHaveBeenCalledWith(
+      join(dir, 'daemon-entry.js'),
+      expect.arrayContaining(['--pid-record', pidPath, '--launch-nonce', 'launch-a']),
+      expect.objectContaining({ stdio: ['ignore', 'ignore', 'ignore', 'ipc'] })
+    )
   })
 
-  it('removes shutdown exit listener when force-kill timeout settles first', async () => {
+  it('resolves shutdown only after observing child exit', async () => {
+    const handlers: Record<string, ((arg?: unknown) => void)[]> = {
+      message: [],
+      error: [],
+      exit: []
+    }
+    const child = {
+      pid: 12345,
+      connected: true,
+      exitCode: null as number | null,
+      signalCode: null as NodeJS.Signals | null,
+      on: vi.fn((event: string, callback: (arg?: unknown) => void) => {
+        handlers[event]?.push(callback)
+        return child
+      }),
+      once: vi.fn((event: string, callback: (arg?: unknown) => void) => {
+        handlers[event]?.push(callback)
+        return child
+      }),
+      off: vi.fn((event: string, callback: (arg?: unknown) => void) => {
+        handlers[event] = handlers[event]?.filter((handler) => handler !== callback) ?? []
+        return child
+      }),
+      kill: vi.fn((signal: NodeJS.Signals) => {
+        if (signal === 'SIGTERM') {
+          queueMicrotask(() => {
+            child.exitCode = 0
+            for (const callback of handlers.exit.slice()) {
+              callback(0)
+            }
+          })
+        }
+        return true
+      }),
+      disconnect: vi.fn(() => {
+        child.connected = false
+      }),
+      unref: vi.fn()
+    }
+    forkMock.mockReturnValueOnce(child)
+    const launcher = createProductionLauncher({
+      getDaemonEntryPath: () => join(dir, 'daemon-entry.js')
+    })
+    const launch = launcher(socketPathFor(dir), tokenPathFor(dir))
+    handlers.message[0]?.({ type: 'ready', startedAtMs: 123_456 })
+    const handle = await launch
+
+    await expect(handle.shutdown()).resolves.toBeUndefined()
+
+    expect(child.kill).toHaveBeenCalledWith('SIGTERM')
+    expect(child.exitCode).toBe(0)
+  })
+
+  it('rejects shutdown and releases child handles when SIGKILL never produces exit', async () => {
     vi.useFakeTimers()
     try {
       const handlers: Record<string, ((arg?: unknown) => void)[]> = {
@@ -138,6 +217,9 @@ describe('createProductionLauncher', () => {
       const child = {
         pid: 12345,
         killed: false,
+        connected: false,
+        exitCode: null,
+        signalCode: null,
         on: vi.fn((event: string, cb: (arg?: unknown) => void) => {
           handlers[event]?.push(cb)
           return child
@@ -150,8 +232,10 @@ describe('createProductionLauncher', () => {
           handlers[event] = handlers[event]?.filter((handler) => handler !== cb) ?? []
           return child
         }),
-        kill: vi.fn(),
-        disconnect: vi.fn(),
+        kill: vi.fn(() => true),
+        disconnect: vi.fn(() => {
+          child.connected = false
+        }),
         unref: vi.fn()
       }
       forkMock.mockReturnValueOnce(child)
@@ -161,22 +245,135 @@ describe('createProductionLauncher', () => {
       })
 
       const launch = launcher(socketPathFor(dir), tokenPathFor(dir))
-      handlers.message[0]?.({ type: 'ready' })
+      handlers.message[0]?.({ type: 'ready', startedAtMs: 123_456 })
       const handle = await launch
 
-      const shutdown = handle.shutdown()
+      const shutdown = expect(handle.shutdown()).rejects.toThrow(
+        'Daemon did not exit after SIGKILL'
+      )
       expect(handlers.exit).toHaveLength(1)
 
-      await vi.advanceTimersByTimeAsync(5000)
+      await vi.advanceTimersByTimeAsync(6000)
       await shutdown
 
       expect(child.kill).toHaveBeenNthCalledWith(1, 'SIGTERM')
       expect(child.kill).toHaveBeenNthCalledWith(2, 'SIGKILL')
       expect(handlers.exit).toHaveLength(0)
+      expect(child.unref).toHaveBeenCalledTimes(2)
     } finally {
       vi.useRealTimers()
     }
   })
+
+  it('preserves readiness and signaling failures while releasing startup IPC', async () => {
+    vi.useFakeTimers()
+    try {
+      const handlers: Record<string, ((arg?: unknown) => void)[]> = {
+        message: [],
+        error: [],
+        exit: []
+      }
+      const signalError = Object.assign(new Error('permission denied'), { code: 'EACCES' })
+      const child = {
+        pid: 12345,
+        connected: true,
+        exitCode: null,
+        signalCode: null,
+        on: vi.fn((event: string, cb: (arg?: unknown) => void) => {
+          handlers[event]?.push(cb)
+          return child
+        }),
+        once: vi.fn((event: string, cb: (arg?: unknown) => void) => {
+          handlers[event]?.push(cb)
+          return child
+        }),
+        off: vi.fn((event: string, cb: (arg?: unknown) => void) => {
+          handlers[event] = handlers[event]?.filter((handler) => handler !== cb) ?? []
+          return child
+        }),
+        kill: vi.fn(() => {
+          throw signalError
+        }),
+        disconnect: vi.fn(() => {
+          child.connected = false
+        }),
+        unref: vi.fn()
+      }
+      forkMock.mockReturnValueOnce(child)
+
+      const launcher = createProductionLauncher({
+        getDaemonEntryPath: () => join(dir, 'daemon-entry.js')
+      })
+      const launch = launcher(socketPathFor(dir), tokenPathFor(dir))
+      handlers.message[0]?.({ type: 'ready' })
+
+      const error = await launch.catch((caught: unknown) => caught)
+      expect(error).toBeInstanceOf(AggregateError)
+      expect((error as AggregateError).errors).toEqual([
+        expect.objectContaining({ message: 'Daemon readiness identity is incomplete' }),
+        signalError
+      ])
+      expect(child.disconnect).toHaveBeenCalledOnce()
+      expect(child.unref).toHaveBeenCalledOnce()
+      expect(handlers.message).toHaveLength(0)
+      expect(handlers.error).toHaveLength(0)
+      expect(handlers.exit).toHaveLength(0)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('preserves PID publication and cleanup failures', async () => {
+    const handlers: Record<string, ((arg?: unknown) => void)[]> = {
+      message: [],
+      error: [],
+      exit: []
+    }
+    const signalError = Object.assign(new Error('signal blocked'), { code: 'EPERM' })
+    const child = {
+      pid: 12345,
+      connected: true,
+      exitCode: null,
+      signalCode: null,
+      on: vi.fn((event: string, cb: (arg?: unknown) => void) => {
+        handlers[event]?.push(cb)
+        return child
+      }),
+      once: vi.fn((event: string, cb: (arg?: unknown) => void) => {
+        handlers[event]?.push(cb)
+        return child
+      }),
+      off: vi.fn((event: string, cb: (arg?: unknown) => void) => {
+        handlers[event] = handlers[event]?.filter((handler) => handler !== cb) ?? []
+        return child
+      }),
+      kill: vi.fn(() => {
+        throw signalError
+      }),
+      disconnect: vi.fn(() => {
+        child.connected = false
+      }),
+      unref: vi.fn()
+    }
+    forkMock.mockReturnValueOnce(child)
+    const pidPath = join(dir, 'occupied.pid')
+    writeFileSync(pidPath, 'occupied')
+    const launcher = createProductionLauncher({
+      getDaemonEntryPath: () => join(dir, 'daemon-entry.js')
+    })
+
+    const launch = launcher(socketPathFor(dir), tokenPathFor(dir), pidPath, 'launch-b')
+    handlers.message[0]?.({ type: 'ready', startedAtMs: 123_456 })
+
+    const error = await launch.catch((caught: unknown) => caught)
+    expect(error).toBeInstanceOf(AggregateError)
+    expect((error as AggregateError).errors).toEqual([
+      expect.objectContaining({ code: 'EEXIST' }),
+      signalError
+    ])
+    expect(child.disconnect).toHaveBeenCalledOnce()
+    expect(child.unref).toHaveBeenCalledOnce()
+  })
 })
 
 function socketPathFor(dir: string): string {
diff --git a/src/main/daemon/production-launcher.ts b/src/main/daemon/production-launcher.ts
index 3fb5d7e792c..b9fe704a41d 100644
--- a/src/main/daemon/production-launcher.ts
+++ b/src/main/daemon/production-launcher.ts
@@ -1,5 +1,10 @@
 import { fork, type ChildProcess } from 'node:child_process'
-import type { DaemonLauncher, DaemonProcessHandle } from './daemon-spawner'
+import { writeFileSync } from 'node:fs'
+import {
+  serializeDaemonPidFile,
+  type DaemonLauncher,
+  type DaemonProcessHandle
+} from './daemon-spawner'
 
 const READY_TIMEOUT_MS = 10_000
 
@@ -8,17 +13,63 @@ export type ProductionLauncherOptions = {
 }
 
 export function createProductionLauncher(opts: ProductionLauncherOptions): DaemonLauncher {
-  return async (socketPath: string, tokenPath: string): Promise<DaemonProcessHandle> => {
+  return async (
+    socketPath: string,
+    tokenPath: string,
+    pidPath?: string,
+    launchNonce?: string
+  ): Promise<DaemonProcessHandle> => {
+    if ((pidPath === undefined) !== (launchNonce === undefined)) {
+      // Why: partial ownership metadata would launch a v24 daemon that cannot
+      // prove which PID record it may remove during self-retirement.
+      throw new Error('Daemon PID path and launch nonce must be provided together')
+    }
     const entryPath = opts.getDaemonEntryPath()
 
-    const child = fork(entryPath, ['--socket', socketPath, '--token', tokenPath], {
-      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
-      detached: true,
-      env: { ...process.env },
-      ...(process.platform === 'win32' ? { windowsHide: true } : {})
-    })
+    const child = fork(
+      entryPath,
+      [
+        '--socket',
+        socketPath,
+        '--token',
+        tokenPath,
+        ...(pidPath && launchNonce ? ['--pid-record', pidPath, '--launch-nonce', launchNonce] : [])
+      ],
+      {
+        // Why: detached daemon output is not consumed; ignored streams cannot
+        // keep Electron alive after the child and IPC channel are unreferenced.
+        stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+        detached: true,
+        env: { ...process.env },
+        ...(process.platform === 'win32' ? { windowsHide: true } : {})
+      }
+    )
 
-    await waitForReady(child)
+    let startedAtMs: number
+    try {
+      startedAtMs = await waitForReady(child)
+    } catch (error) {
+      return rejectAfterChildCleanup(child, error)
+    }
+    if (pidPath && launchNonce) {
+      if (!Number.isSafeInteger(child.pid) || (child.pid as number) <= 0) {
+        return rejectAfterChildCleanup(child, new Error('Daemon readiness identity is incomplete'))
+      }
+      try {
+        writeFileSync(
+          pidPath,
+          serializeDaemonPidFile({
+            pid: child.pid as number,
+            startedAtMs,
+            entryPath,
+            launchNonce
+          }),
+          { mode: 0o600, flag: 'wx' }
+        )
+      } catch (error) {
+        return rejectAfterChildCleanup(child, error)
+      }
+    }
 
     // Unref so the Electron process can exit without waiting for the daemon
     child.unref()
@@ -30,7 +81,7 @@ export function createProductionLauncher(opts: ProductionLauncherOptions): Daemo
   }
 }
 
-function waitForReady(child: ChildProcess): Promise<void> {
+function waitForReady(child: ChildProcess): Promise<number> {
   return new Promise((resolve, reject) => {
     let timeout: ReturnType<typeof setTimeout> | undefined
     let settled = false
@@ -42,15 +93,12 @@ function waitForReady(child: ChildProcess): Promise<void> {
       child.off('error', onError)
       child.off('exit', onExit)
     }
-    function fail(error: Error, killChild = false): void {
+    function fail(error: Error): void {
       if (settled) {
         return
       }
       settled = true
       cleanupStartupListeners()
-      if (killChild) {
-        child.kill('SIGTERM')
-      }
       reject(error)
     }
     function onMessage(msg: unknown): void {
@@ -58,11 +106,16 @@ function waitForReady(child: ChildProcess): Promise<void> {
         if (settled) {
           return
         }
+        const startedAtMs = (msg as { startedAtMs?: unknown }).startedAtMs
+        if (typeof startedAtMs !== 'number' || !Number.isFinite(startedAtMs) || startedAtMs <= 0) {
+          fail(new Error('Daemon readiness identity is incomplete'))
+          return
+        }
         settled = true
         // Why: the daemon is detached after readiness, so startup listeners
         // must not keep the child process closure alive for the daemon lifetime.
         cleanupStartupListeners()
-        resolve()
+        resolve(startedAtMs)
       }
     }
     function onError(err: Error): void {
@@ -73,7 +126,7 @@ function waitForReady(child: ChildProcess): Promise<void> {
     }
 
     timeout = setTimeout(() => {
-      fail(new Error('Daemon failed to signal readiness within timeout'), true)
+      fail(new Error('Daemon failed to signal readiness within timeout'))
     }, READY_TIMEOUT_MS)
 
     child.on('message', onMessage)
@@ -82,35 +135,88 @@ function waitForReady(child: ChildProcess): Promise<void> {
   })
 }
 
-function shutdownChild(child: ChildProcess): Promise<void> {
-  return new Promise((resolve) => {
-    if (child.killed) {
-      resolve()
+async function shutdownChild(child: ChildProcess): Promise<void> {
+  try {
+    if (
+      (child.exitCode !== null && child.exitCode !== undefined) ||
+      (child.signalCode !== null && child.signalCode !== undefined)
+    ) {
       return
     }
-
-    let settled = false
-    let timeout: ReturnType<typeof setTimeout>
-    function finish(): void {
-      if (settled) {
-        return
+    await new Promise<void>((resolve, reject) => {
+      let settled = false
+      let timeout: ReturnType<typeof setTimeout>
+      let forceTimeout: ReturnType<typeof setTimeout> | undefined
+      function finish(error?: unknown): void {
+        if (settled) {
+          return
+        }
+        settled = true
+        clearTimeout(timeout)
+        if (forceTimeout) {
+          clearTimeout(forceTimeout)
+        }
+        child.off('exit', onExit)
+        if (error) {
+          reject(error)
+        } else {
+          resolve()
+        }
       }
-      settled = true
-      clearTimeout(timeout)
-      child.off('exit', onExit)
-      resolve()
+
+      function onExit(): void {
+        finish()
+      }
+
+      timeout = setTimeout(() => {
+        try {
+          if (child.kill('SIGKILL') === false) {
+            finish(new Error('Failed to deliver SIGKILL to daemon'))
+            return
+          }
+        } catch (error) {
+          finish(isNoSuchProcessError(error) ? undefined : error)
+          return
+        }
+        // Why: signal delivery is not process exit; keep the listener for one
+        // bounded interval before releasing launcher-owned handles.
+        if (!settled) {
+          forceTimeout = setTimeout(
+            () => finish(new Error('Daemon did not exit after SIGKILL')),
+            1000
+          )
+        }
+      }, 5000)
+
+      child.once('exit', onExit)
+      try {
+        if (child.kill('SIGTERM') === false) {
+          finish(new Error('Failed to deliver SIGTERM to daemon'))
+        }
+      } catch (error) {
+        finish(isNoSuchProcessError(error) ? undefined : error)
+      }
+    })
+  } finally {
+    if (child.connected) {
+      child.disconnect()
     }
+    child.unref()
+  }
+}
 
-    function onExit(): void {
-      finish()
-    }
+async function rejectAfterChildCleanup(child: ChildProcess, launchError: unknown): Promise<never> {
+  try {
+    await shutdownChild(child)
+  } catch (cleanupError) {
+    throw new AggregateError(
+      [launchError, cleanupError],
+      'Daemon launch and child cleanup both failed'
+    )
+  }
+  throw launchError
+}
 
-    timeout = setTimeout(() => {
-      child.kill('SIGKILL')
-      finish()
-    }, 5000)
-
-    child.once('exit', onExit)
-    child.kill('SIGTERM')
-  })
+function isNoSuchProcessError(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ESRCH'
 }
diff --git a/src/main/daemon/types.ts b/src/main/daemon/types.ts
index 63c5edc577b..0daaf0ac0cf 100644
--- a/src/main/daemon/types.ts
+++ b/src/main/daemon/types.ts
@@ -16,10 +16,11 @@ import type { TuiAgent } from '../../shared/types'
 // when daemon-baked behavior cannot be delivered by on-disk wrapper refresh.
 // Why: bump when adding daemon wire behavior so same-version old daemons do
 // not silently accept the handshake and then reject new RPCs.
-export const PROTOCOL_VERSION = 23
+export const PROTOCOL_VERSION = 24
 export const GIT_CREDENTIAL_GUARD_HOST_PROTOCOL_VERSION = 22
+export const CLEAN_DISCONNECT_PROTOCOL_VERSION = 24
 export const PREVIOUS_DAEMON_PROTOCOL_VERSIONS = [
-  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22
+  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23
 ] as const
 
 // ─── Session State Machine ──────────────────────────────────────────
@@ -80,19 +81,7 @@ export type { TerminalCheckpointFile } from './daemon-checkpoint-file'
 // ─── NDJSON Protocol Messages ───────────────────────────────────────
 
 // Hello handshake (first message on each socket)
-export type HelloMessage = {
-  type: 'hello'
-  version: number
-  token: string
-  clientId: string
-  role: 'control' | 'stream'
-}
-
-export type HelloResponse = {
-  type: 'hello'
-  ok: boolean
-  error?: string
-}
+export type { DaemonEndpointIdentity, HelloMessage, HelloResponse } from './daemon-hello-protocol'
 
 // ─── RPC Requests (Client → Daemon, on control socket) ─────────────
 
@@ -211,6 +200,11 @@ export type ListSessionsRequest = {
   type: 'listSessions'
 }
 
+export type ShutdownIfIdleRequest = {
+  id: string
+  type: 'shutdownIfIdle'
+}
+
 export type DetachRequest = {
   id: string
   type: 'detach'
@@ -330,6 +324,7 @@ export type DaemonRequest =
   | KillRequest
   | SignalRequest
   | ListSessionsRequest
+  | ShutdownIfIdleRequest
   | DetachRequest
   | GetCwdRequest
   | GetForegroundProcessRequest
@@ -368,6 +363,10 @@ export type ListSessionsResult = {
   sessions: SessionInfo[]
 }
 
+export type ShutdownIfIdleResult = {
+  retiring: boolean
+}
+
 export type SystemResolverHealth = 'healthy' | 'unhealthy' | 'unknown'
 
 export type SystemResolverHealthResult = {
diff --git a/tests/e2e/daemon-lifecycle-retirement.spec.ts b/tests/e2e/daemon-lifecycle-retirement.spec.ts
new file mode 100644
index 00000000000..f522088998e
--- /dev/null
+++ b/tests/e2e/daemon-lifecycle-retirement.spec.ts
@@ -0,0 +1,241 @@
+import { fork, type ChildProcess } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { build } from 'esbuild'
+import { expect, test } from '@playwright/test'
+import { DaemonClient } from '../../src/main/daemon/client'
+import { DaemonPtyAdapter } from '../../src/main/daemon/daemon-pty-adapter'
+import {
+  getDaemonPidPath,
+  getDaemonSocketPath,
+  getDaemonTokenPath
+} from '../../src/main/daemon/daemon-spawner'
+import { PROTOCOL_VERSION } from '../../src/main/daemon/types'
+
+type FixtureDaemon = {
+  child: ChildProcess
+  protocolVersion: number
+  socketPath: string
+  tokenPath: string
+  pidPath: string
+}
+
+async function waitFor(
+  label: string,
+  predicate: () => boolean | Promise<boolean>,
+  timeoutMs = 10_000
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (!(await predicate())) {
+    if (Date.now() >= deadline) {
+      throw new Error(`Timed out waiting for ${label}`)
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25))
+  }
+}
+
+async function launchFixture(
+  entryPath: string,
+  daemonDir: string,
+  protocolVersion: number
+): Promise<FixtureDaemon> {
+  const socketPath = getDaemonSocketPath(daemonDir, protocolVersion)
+  const tokenPath = getDaemonTokenPath(daemonDir, protocolVersion)
+  const pidPath = getDaemonPidPath(daemonDir, protocolVersion)
+  const launchNonce = randomUUID()
+  const child = fork(
+    entryPath,
+    [
+      '--protocol',
+      String(protocolVersion),
+      '--socket',
+      socketPath,
+      '--token',
+      tokenPath,
+      ...(protocolVersion >= PROTOCOL_VERSION
+        ? ['--pid-record', pidPath, '--launch-nonce', launchNonce]
+        : [])
+    ],
+    {
+      stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+      env: {
+        ...process.env,
+        NODE_PATH: [path.join(process.cwd(), 'node_modules'), process.env.NODE_PATH]
+          .filter(Boolean)
+          .join(path.delimiter)
+      }
+    }
+  )
+  let stderr = ''
+  child.stderr?.on('data', (chunk) => {
+    stderr = `${stderr}${String(chunk)}`.slice(-8_192)
+  })
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const cleanup = (): void => {
+        clearTimeout(timeout)
+        child.off('message', onMessage)
+        child.off('error', onError)
+        child.off('exit', onExit)
+      }
+      const onMessage = (message: unknown): void => {
+        if ((message as { type?: unknown }).type !== 'ready') {
+          return
+        }
+        cleanup()
+        resolve()
+      }
+      const onError = (error: Error): void => {
+        cleanup()
+        reject(error)
+      }
+      const onExit = (code: number | null): void => {
+        cleanup()
+        reject(new Error(`Lifecycle fixture exited with ${code}: ${stderr.trim()}`))
+      }
+      const timeout = setTimeout(() => {
+        cleanup()
+        reject(new Error('Lifecycle fixture startup timed out'))
+      }, 10_000)
+      child.on('message', onMessage)
+      child.on('error', onError)
+      child.on('exit', onExit)
+    })
+  } catch (error) {
+    try {
+      await stopChild(child, `fixture v${protocolVersion}`)
+    } catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], 'Fixture startup and cleanup both failed')
+    }
+    throw error
+  }
+  return { child, protocolVersion, socketPath, tokenPath, pidPath }
+}
+
+async function stopChild(child: ChildProcess, label: string): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return
+  }
+  child.kill('SIGTERM')
+  try {
+    await waitFor(
+      `${label} graceful exit`,
+      () => child.exitCode !== null || child.signalCode !== null,
+      3_000
+    )
+    return
+  } catch {
+    child.kill('SIGKILL')
+  }
+  await waitFor(
+    `${label} forced exit`,
+    () => child.exitCode !== null || child.signalCode !== null,
+    3_000
+  )
+}
+
+async function stopFixture(fixture: FixtureDaemon): Promise<void> {
+  await stopChild(fixture.child, `fixture v${fixture.protocolVersion}`)
+}
+
+test('v22 stays reattachable while v24 retires after its last empty client disconnects', async () => {
+  const rootDir = mkdtempSync(path.join(tmpdir(), 'orca-daemon-lifecycle-'))
+  const daemonDir = path.join(rootDir, 'daemon')
+  mkdirSync(daemonDir, { recursive: true })
+  const entryPath = path.join(rootDir, 'daemon-lifecycle-entry.cjs')
+  const fixtures: FixtureDaemon[] = []
+  let testError: unknown
+
+  try {
+    await build({
+      entryPoints: [path.join(process.cwd(), 'tests/e2e/fixtures/daemon-lifecycle-entry.ts')],
+      outfile: entryPath,
+      bundle: true,
+      platform: 'node',
+      format: 'cjs',
+      target: 'node20',
+      external: ['node-pty'],
+      logLevel: 'silent'
+    })
+
+    const legacy = await launchFixture(entryPath, daemonDir, 22)
+    fixtures.push(legacy)
+    const legacyClient = new DaemonClient({
+      socketPath: legacy.socketPath,
+      tokenPath: legacy.tokenPath,
+      protocolVersion: 22
+    })
+    await legacyClient.ensureConnected()
+    await expect(
+      legacyClient.request('createOrAttach', { sessionId: 'legacy-live', cols: 80, rows: 24 })
+    ).resolves.toMatchObject({ isNew: true })
+    legacyClient.disconnect()
+
+    const current = await launchFixture(entryPath, daemonDir, PROTOCOL_VERSION)
+    fixtures.push(current)
+    const reattachClient = new DaemonClient({
+      socketPath: legacy.socketPath,
+      tokenPath: legacy.tokenPath,
+      protocolVersion: 22
+    })
+    await reattachClient.ensureConnected()
+    await expect(
+      reattachClient.request('createOrAttach', {
+        sessionId: 'legacy-live',
+        cols: 80,
+        rows: 24
+      })
+    ).resolves.toMatchObject({ isNew: false })
+    reattachClient.disconnect()
+
+    const currentAdapter = new DaemonPtyAdapter({
+      socketPath: current.socketPath,
+      tokenPath: current.tokenPath
+    })
+    const secondCurrentClient = new DaemonClient({
+      socketPath: current.socketPath,
+      tokenPath: current.tokenPath
+    })
+    await secondCurrentClient.ensureConnected()
+
+    // Why: failed adoption may overlap another authenticated app client, so
+    // only daemon-owned idle retirement can safely decide whether to exit.
+    await currentAdapter.disconnectOnly()
+    expect(current.child.exitCode).toBeNull()
+    await expect(secondCurrentClient.request('listSessions', undefined)).resolves.toEqual({
+      sessions: []
+    })
+    secondCurrentClient.disconnect()
+
+    await waitFor('v24 process exit', () => current.child.exitCode !== null)
+    expect(existsSync(current.tokenPath)).toBe(false)
+    expect(existsSync(current.pidPath)).toBe(false)
+    if (process.platform !== 'win32') {
+      expect(existsSync(current.socketPath)).toBe(false)
+    }
+    expect(legacy.child.exitCode).toBeNull()
+  } catch (error) {
+    testError = error
+  }
+
+  const results = await Promise.allSettled(fixtures.map((fixture) => stopFixture(fixture)))
+  const cleanupErrors = results.flatMap((result) =>
+    result.status === 'rejected' ? [result.reason] : []
+  )
+  try {
+    rmSync(rootDir, { recursive: true, force: true })
+  } catch (error) {
+    cleanupErrors.push(error)
+  }
+  if (testError !== undefined && cleanupErrors.length > 0) {
+    throw new AggregateError([testError, ...cleanupErrors], 'Lifecycle test and cleanup failed')
+  }
+  if (testError !== undefined) {
+    throw testError
+  }
+  if (cleanupErrors.length > 0) {
+    throw new AggregateError(cleanupErrors, 'Lifecycle fixture cleanup failed')
+  }
+})
diff --git a/tests/e2e/fixtures/daemon-lifecycle-entry.ts b/tests/e2e/fixtures/daemon-lifecycle-entry.ts
new file mode 100644
index 00000000000..0e09897b0c0
--- /dev/null
+++ b/tests/e2e/fixtures/daemon-lifecycle-entry.ts
@@ -0,0 +1,122 @@
+import process from 'node:process'
+import { writeFileSync } from 'node:fs'
+import { startDaemon, type DaemonHandle } from '../../../src/main/daemon/daemon-main'
+import { serializeDaemonPidFile } from '../../../src/main/daemon/daemon-spawner'
+import type { SubprocessHandle } from '../../../src/main/daemon/session'
+
+type FixtureArgs = {
+  protocolVersion: number
+  socketPath: string
+  tokenPath: string
+  pidPath?: string
+  launchNonce?: string
+}
+
+function parseArgs(argv: string[]): FixtureArgs {
+  const values = new Map<string, string>()
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index]
+    const value = argv[index + 1]
+    if (!key || !value) {
+      throw new Error('Lifecycle fixture arguments must be key/value pairs')
+    }
+    values.set(key, value)
+  }
+  const protocolVersion = Number(values.get('--protocol'))
+  const socketPath = values.get('--socket')
+  const tokenPath = values.get('--token')
+  const pidPath = values.get('--pid-record')
+  const launchNonce = values.get('--launch-nonce')
+  if (
+    !Number.isInteger(protocolVersion) ||
+    protocolVersion < 1 ||
+    !socketPath ||
+    !tokenPath ||
+    Boolean(pidPath) !== Boolean(launchNonce)
+  ) {
+    throw new Error('Invalid lifecycle fixture arguments')
+  }
+  return {
+    protocolVersion,
+    socketPath,
+    tokenPath,
+    ...(pidPath && launchNonce ? { pidPath, launchNonce } : {})
+  }
+}
+
+function createFixtureSubprocess(): SubprocessHandle {
+  let onData: ((data: string) => void) | null = null
+  let onExit: ((code: number) => void) | null = null
+  let exited = false
+  const exit = (code: number): void => {
+    if (exited) {
+      return
+    }
+    exited = true
+    onExit?.(code)
+  }
+  return {
+    pid: process.pid,
+    getForegroundProcess: () => null,
+    write: (data) => onData?.(data),
+    resize: () => {},
+    kill: () => exit(0),
+    forceKill: () => exit(137),
+    signal: () => {},
+    onData: (callback) => {
+      onData = callback
+    },
+    onExit: (callback) => {
+      onExit = callback
+    },
+    dispose: () => exit(0)
+  }
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2))
+  const startedAtMs = Date.now() - process.uptime() * 1000
+  let daemon: DaemonHandle | null = await startDaemon({
+    protocolVersion: args.protocolVersion,
+    socketPath: args.socketPath,
+    tokenPath: args.tokenPath,
+    ...(args.pidPath ? { pidPath: args.pidPath } : {}),
+    ...(args.launchNonce ? { launchNonce: args.launchNonce } : {}),
+    startedAtMs,
+    spawnSubprocess: () => createFixtureSubprocess(),
+    onIdleShutdown: () => process.exit(0)
+  })
+  if (args.pidPath && args.launchNonce) {
+    writeFileSync(
+      args.pidPath,
+      serializeDaemonPidFile({
+        pid: process.pid,
+        startedAtMs,
+        launchNonce: args.launchNonce
+      }),
+      { mode: 0o600, flag: 'wx' }
+    )
+  }
+
+  let shuttingDown = false
+  const shutdown = async (): Promise<void> => {
+    if (shuttingDown) {
+      return
+    }
+    shuttingDown = true
+    try {
+      await daemon?.shutdown()
+      daemon = null
+    } finally {
+      process.exit(0)
+    }
+  }
+  process.on('SIGTERM', () => void shutdown())
+  process.on('SIGINT', () => void shutdown())
+  process.send?.({ type: 'ready', pid: process.pid, startedAtMs })
+}
+
+void main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

From d628c9300eae658497435bcbeabebad7566883cb Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Sun, 19 Jul 2026 22:54:39 -0400
Subject: [PATCH 22/54] fix(terminal): harden revealed inline-TUI convergence
 (#9503)

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
---
 .../terminal-pane/pty-connection.test.ts      | 256 ++++++-
 .../terminal-pane/pty-connection.ts           |  72 +-
 .../components/terminal-pane/replay-guard.ts  |   3 +
 .../pane-fit-continuation-retry.ts            |  87 +++
 .../src/lib/pane-manager/pane-fit.test.ts     | 169 +++++
 src/renderer/src/lib/pane-manager/pane-fit.ts |  56 +-
 ...-terminal-foreground-render-settle.test.ts |  83 ++
 .../pane-terminal-foreground-render-settle.ts |  33 +-
 .../codex-inline-live-block-fixture.cjs       | 139 ++++
 ...inal-inline-tui-reveal-convergence.spec.ts | 718 ++++++++++++++++++
 10 files changed, 1597 insertions(+), 19 deletions(-)
 create mode 100644 src/renderer/src/lib/pane-manager/pane-fit-continuation-retry.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-fit.test.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-terminal-foreground-render-settle.test.ts
 create mode 100644 tests/e2e/fixtures/codex-inline-live-block-fixture.cjs
 create mode 100644 tests/e2e/terminal-inline-tui-reveal-convergence.spec.ts

diff --git a/src/renderer/src/components/terminal-pane/pty-connection.test.ts b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
index 1c9323dd0a9..3f05c9a5371 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
@@ -5953,7 +5953,8 @@ describe('connectPanePty', () => {
     reattach.resolve()
     await flushAsyncTicks()
 
-    expect(transport.resize).toHaveBeenLastCalledWith(65, 63)
+    expect(transport.resize).toHaveBeenCalledWith(65, 63)
+    expect(transport.resize).toHaveBeenLastCalledWith(65, 63, { claim: true })
   })
 
   it('adopts a live eager PTY and withholds snapshots after its renderer dies', async () => {
@@ -7404,7 +7405,10 @@ describe('connectPanePty', () => {
     const blankViewport = buildFreshShellViewportBlankingSequence(destinationRows)
     expect(pane.terminal.resize).toHaveBeenCalledWith(recoveredCols, recoveredRows)
     expect(transport.resize).not.toHaveBeenCalledWith(recoveredCols, recoveredRows)
-    expect(transport.resize).toHaveBeenLastCalledWith(destinationCols, destinationRows)
+    expect(transport.resize).toHaveBeenCalledWith(destinationCols, destinationRows)
+    expect(transport.resize).toHaveBeenLastCalledWith(destinationCols, destinationRows, {
+      claim: true
+    })
     expect(written).toContain(viewportClear)
     expect(written).not.toContain('\x1b[2J\x1b[3J\x1b[H')
     expect(written).toEqual(
@@ -8617,6 +8621,161 @@ describe('connectPanePty', () => {
     expect(liveIndex).toBeGreaterThan(snapshotIndex)
   })
 
+  it('re-enforces follow intent after deferred reattach live output parses', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+    const { markTerminalFollowOutput } = await import('@/lib/pane-manager/terminal-scroll-intent')
+    const transport = createMockTransport('tab-pty')
+    transport.connect.mockImplementation(
+      async ({ sessionId, callbacks }: { sessionId?: string; callbacks?: ConnectCallbacks }) => {
+        if (!sessionId) {
+          return null
+        }
+        callbacks?.onData?.('post-snapshot-live')
+        return { id: sessionId, snapshot: 'authoritative-snapshot' }
+      }
+    )
+    transportFactoryQueue.push(transport)
+    const pane = createPane(1)
+    pane.terminal.buffer.active.baseY = 100
+    pane.terminal.buffer.active.viewportY = 100
+    markTerminalFollowOutput(pane.terminal)
+    const parseCallbacks: (() => void)[] = []
+    pane.terminal.write = vi.fn((data: string, callback?: () => void) => {
+      parseCallbacks.push(() => {
+        if (data === 'post-snapshot-live') {
+          pane.terminal.buffer.active.baseY = 200
+          pane.terminal.buffer.active.viewportY = 100
+        }
+        callback?.()
+      })
+    })
+    const deps = createDeps({
+      restoredLeafId: LEAF_1,
+      restoredPtyIdByLeafId: { [LEAF_1]: 'tab-pty' }
+    })
+
+    connectPanePty(pane as never, createManager(1) as never, deps as never)
+    await flushAsyncTicks(20)
+    for (let index = 0; index < 30; index += 1) {
+      parseCallbacks.shift()?.()
+      await flushAsyncTicks(4)
+      if (parseCallbacks.length === 0 && index > 5) {
+        break
+      }
+    }
+
+    expect(pane.terminal.buffer.active.viewportY).toBe(200)
+  })
+
+  it('does not steal a newer user pin while deferred reattach output settles', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+    const { markTerminalFollowOutput, markTerminalPinnedViewport } =
+      await import('@/lib/pane-manager/terminal-scroll-intent')
+    const transport = createMockTransport('tab-pty')
+    transport.connect.mockImplementation(
+      async ({ sessionId, callbacks }: { sessionId?: string; callbacks?: ConnectCallbacks }) => {
+        if (!sessionId) {
+          return null
+        }
+        callbacks?.onData?.('post-snapshot-live')
+        return { id: sessionId, snapshot: 'authoritative-snapshot' }
+      }
+    )
+    transportFactoryQueue.push(transport)
+    const pane = createPane(1)
+    pane.terminal.buffer.active.baseY = 100
+    pane.terminal.buffer.active.viewportY = 100
+    markTerminalFollowOutput(pane.terminal)
+    const parseCallbacks: { data: string; run: () => void }[] = []
+    pane.terminal.write = vi.fn((data: string, callback?: () => void) => {
+      parseCallbacks.push({
+        data,
+        run: () => {
+          if (data === 'post-snapshot-live') {
+            pane.terminal.buffer.active.baseY = 200
+            pane.terminal.buffer.active.viewportY = 100
+          }
+          callback?.()
+        }
+      })
+    })
+    const deps = createDeps({
+      restoredLeafId: LEAF_1,
+      restoredPtyIdByLeafId: { [LEAF_1]: 'tab-pty' }
+    })
+
+    connectPanePty(pane as never, createManager(1) as never, deps as never)
+    await flushAsyncTicks(20)
+    for (let index = 0; index < 40; index += 1) {
+      const pending = parseCallbacks.shift()
+      pending?.run()
+      await flushAsyncTicks(4)
+      if (pending?.data === 'post-snapshot-live') {
+        pane.terminal.buffer.active.viewportY = 150
+        markTerminalPinnedViewport(pane.terminal)
+      }
+      if (parseCallbacks.length === 0 && index > 8) {
+        break
+      }
+    }
+
+    expect(pane.terminal.buffer.active.viewportY).toBe(150)
+  })
+
+  it('does not enforce a deferred viewport after the pane becomes hidden', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+    const { markTerminalFollowOutput } = await import('@/lib/pane-manager/terminal-scroll-intent')
+    const transport = createMockTransport('tab-pty')
+    transport.connect.mockImplementation(
+      async ({ sessionId, callbacks }: { sessionId?: string; callbacks?: ConnectCallbacks }) => {
+        if (!sessionId) {
+          return null
+        }
+        callbacks?.onData?.('post-snapshot-live')
+        return { id: sessionId, snapshot: 'authoritative-snapshot' }
+      }
+    )
+    transportFactoryQueue.push(transport)
+    const pane = createPane(1)
+    pane.terminal.buffer.active.baseY = 100
+    pane.terminal.buffer.active.viewportY = 100
+    markTerminalFollowOutput(pane.terminal)
+    const parseCallbacks: { data: string; run: () => void }[] = []
+    pane.terminal.write = vi.fn((data: string, callback?: () => void) => {
+      parseCallbacks.push({
+        data,
+        run: () => {
+          if (data === 'post-snapshot-live') {
+            pane.terminal.buffer.active.baseY = 200
+            pane.terminal.buffer.active.viewportY = 100
+          }
+          callback?.()
+        }
+      })
+    })
+    const deps = createDeps({
+      isVisibleRef: { current: true },
+      restoredLeafId: LEAF_1,
+      restoredPtyIdByLeafId: { [LEAF_1]: 'tab-pty' }
+    })
+
+    connectPanePty(pane as never, createManager(1) as never, deps as never)
+    await flushAsyncTicks(20)
+    for (let index = 0; index < 40; index += 1) {
+      const pending = parseCallbacks.shift()
+      pending?.run()
+      await flushAsyncTicks(4)
+      if (pending?.data === 'post-snapshot-live') {
+        ;(deps.isVisibleRef as { current: boolean }).current = false
+      }
+      if (parseCallbacks.length === 0 && index > 8) {
+        break
+      }
+    }
+
+    expect(pane.terminal.buffer.active.viewportY).toBe(100)
+  })
+
   it('does not fresh-spawn after a dead deferred session delivers its buffered exit', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('tab-pty')
@@ -11777,6 +11936,99 @@ describe('connectPanePty', () => {
     disposable.dispose()
   })
 
+  it('slices abandoned pending chunks against a replay that already painted', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+    const transport = createMockTransport('pty-id')
+    const capturedDataCallback: {
+      current: ((data: string, meta?: { seq?: number; rawLength?: number }) => void) | null
+    } = { current: null }
+    transport.connect.mockImplementation(async ({ callbacks }: { callbacks: ConnectCallbacks }) => {
+      capturedDataCallback.current = callbacks.onData ?? null
+      return 'pty-id'
+    })
+    transportFactoryQueue.push(transport)
+    const getMainBufferSnapshot = window.api.pty.getMainBufferSnapshot as unknown as ReturnType<
+      typeof vi.fn
+    >
+    const snapshot = createDeferred<{
+      data: string
+      cols: number
+      rows: number
+      seq: number
+      pendingDeliveryStartSeq: number
+    }>()
+    getMainBufferSnapshot.mockReturnValue(snapshot.promise)
+    const hidden = 'hidden-codex-output\r\n'
+    const coveredLive = 'LIVE_DUP_LINE\r\n'
+    const afterAbandon = 'AFTER_ABANDON\r\n'
+
+    const pane = createPane(1)
+    const manager = createManager(1)
+    const deps = createDeps({
+      isVisibleRef: { current: false },
+      startup: { command: 'codex' }
+    })
+    const disposable = connectPanePty(pane as never, manager as never, deps as never)
+    await flushAsyncTicks(6)
+    expect(capturedDataCallback.current).not.toBeNull()
+
+    vi.useFakeTimers()
+    capturedDataCallback.current?.(hidden, { seq: hidden.length, rawLength: hidden.length })
+    ;(deps.isVisibleRef as { current: boolean }).current = true
+    capturedDataCallback.current?.(coveredLive, {
+      seq: hidden.length + coveredLive.length,
+      rawLength: coveredLive.length
+    })
+    await flushAsyncTicks(4)
+
+    const heldCallbacks: (() => void)[] = []
+    pane.terminal.write.mockImplementation(function write(
+      data: string,
+      callback?: () => void
+    ): void {
+      if (callback) {
+        heldCallbacks.push(callback)
+      }
+      void data
+    })
+    snapshot.resolve({
+      data: 'SNAP_STATE\r\n',
+      cols: 100,
+      rows: 30,
+      seq: hidden.length + coveredLive.length,
+      pendingDeliveryStartSeq: 0
+    })
+    await flushAsyncTicks(6)
+
+    vi.advanceTimersByTime(750)
+    await flushAsyncTicks(10)
+
+    const writtenAfterAbandon = pane.terminal.write.mock.calls.map(([data]) => data as string)
+    expect(writtenAfterAbandon.join('')).not.toContain('LIVE_DUP_LINE')
+
+    pane.terminal.write.mockClear()
+    capturedDataCallback.current?.(coveredLive, {
+      seq: hidden.length + coveredLive.length,
+      rawLength: coveredLive.length
+    })
+    await flushAsyncTicks(4)
+    expect(pane.terminal.write.mock.calls.map(([data]) => data as string).join('')).not.toContain(
+      'LIVE_DUP_LINE'
+    )
+
+    capturedDataCallback.current?.(afterAbandon, {
+      seq: hidden.length + coveredLive.length + afterAbandon.length,
+      rawLength: afterAbandon.length
+    })
+    await flushAsyncTicks(4)
+    expect(pane.terminal.write.mock.calls.map(([data]) => data as string).join('')).toContain(
+      'AFTER_ABANDON'
+    )
+
+    heldCallbacks.forEach((callback) => callback())
+    disposable.dispose()
+  })
+
   it('abandons a stalled hidden restore and drains pending foreground chunks warning-first', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-id')
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.ts b/src/renderer/src/components/terminal-pane/pty-connection.ts
index 17fb6225ba3..18066ae75d2 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.ts
@@ -131,6 +131,7 @@ import { recordTerminalOutput } from '@/lib/pane-manager/pane-scroll'
 import { ensureArabicShapingJoinerForText } from '@/lib/pane-manager/terminal-arabic-shaping-joiner'
 import { clearTerminalScrollbackAndFollowOutput } from '@/lib/pane-manager/terminal-scrollback-clear'
 import {
+  enforceTerminalCurrentScrollIntent,
   getTerminalScrollIntentKind,
   markTerminalFollowOutput
 } from '@/lib/pane-manager/terminal-scroll-intent'
@@ -4907,7 +4908,8 @@ export function connectPanePty(
       // scheduler's deferred drain cannot land older bytes on top of the replay.
       flushTerminalOutput(pane.terminal)
       replayIntoTerminal(pane, deps.replayingPanesRef, data, {
-        shouldRefreshViewportSynchronously: shouldRefreshForegroundSynchronously
+        shouldRefreshViewportSynchronously: shouldRefreshForegroundSynchronously,
+        shouldReleaseRenderPause: () => deps.isVisibleRef.current
       })
     }
 
@@ -4916,7 +4918,8 @@ export function connectPanePty(
       // merely after the write was queued.
       flushTerminalOutput(pane.terminal)
       return replayIntoTerminalAsync(pane, deps.replayingPanesRef, data, {
-        shouldRefreshViewportSynchronously: shouldRefreshForegroundSynchronously
+        shouldRefreshViewportSynchronously: shouldRefreshForegroundSynchronously,
+        shouldReleaseRenderPause: () => deps.isVisibleRef.current
       })
     }
 
@@ -5215,6 +5218,12 @@ export function connectPanePty(
     let hiddenOutputRestoreGeneration = 0
     // Flood-backpressure suppression (HIDDEN_OUTPUT_RESTORE_FLOOD_SUPPRESS_MS).
     let hiddenOutputRestoreFloodSuppressedUntil = 0
+    // Why: queued replay writes still paint after deadline abandonment; the
+    // fallback drain must not write snapshot-covered live bytes a second time.
+    let hiddenOutputRestoreReplayingSnapshot: {
+      seq?: number
+      pendingDeliveryStartSeq?: number
+    } | null = null
     let hiddenOutputRestoreFloodRepaintTimer: ReturnType<typeof setTimeout> | null = null
     // Why: after a snapshot restore, main can still drain ACK-backlog chunks
     // whose bytes the snapshot already covers — writing them unguarded
@@ -6311,6 +6320,8 @@ export function connectPanePty(
         ? []
         : hiddenOutputRestorePendingChunks.slice()
       const hadPendingOverflow = hiddenOutputRestorePendingOverflow
+      const replayingSnapshot = hiddenOutputRestoreReplayingSnapshot
+      hiddenOutputRestoreReplayingSnapshot = null
       hiddenOutputRestoreGeneration += 1
       if (
         hiddenOutputSnapshotScrollRestore?.valid &&
@@ -6346,7 +6357,21 @@ export function connectPanePty(
       if (hadPendingOverflow) {
         return
       }
-      const pendingData = pendingChunks.map((chunk) => chunk.data).join('')
+      const replayedSeq = typeof replayingSnapshot?.seq === 'number' ? replayingSnapshot.seq : null
+      let pendingData = ''
+      for (const chunk of pendingChunks) {
+        const sliced =
+          replayedSeq === null ? chunk.data : getChunkDataAfterSnapshot(chunk, replayedSeq)
+        pendingData += sliced ?? chunk.data
+      }
+      if (replayingSnapshot && replayedSeq !== null) {
+        setRestoredSnapshotBaseline(expectedPtyId, replayingSnapshot)
+        for (const chunk of pendingChunks) {
+          if (typeof chunk.seq === 'number' && restoredSnapshotExpectedStartSeq !== null) {
+            restoredSnapshotExpectedStartSeq = Math.max(restoredSnapshotExpectedStartSeq, chunk.seq)
+          }
+        }
+      }
       if (pendingData) {
         writePtyOutputToXterm(pendingData, true)
       }
@@ -6391,6 +6416,7 @@ export function connectPanePty(
       resetHiddenRendererRiskState()
       hiddenOutputRestoreNeeded = false
       hiddenOutputRestorePtyId = null
+      hiddenOutputRestoreReplayingSnapshot = null
       hiddenOutputRestoreGeneration += 1
     }
 
@@ -6482,6 +6508,7 @@ export function connectPanePty(
       cols: number
       rows: number
       seq?: number
+      pendingDeliveryStartSeq?: number
       alternateScreen?: boolean
       scrollbackAnsi?: string
       pendingEscapeTailAnsi?: string
@@ -6517,6 +6544,14 @@ export function connectPanePty(
               return
             }
             scrollRestore.started = true
+            if (typeof snapshot.seq === 'number') {
+              hiddenOutputRestoreReplayingSnapshot = {
+                seq: snapshot.seq,
+                ...(typeof snapshot.pendingDeliveryStartSeq === 'number'
+                  ? { pendingDeliveryStartSeq: snapshot.pendingDeliveryStartSeq }
+                  : {})
+              }
+            }
             discardTerminalOutput(pane.terminal)
             if (
               hasSnapshotDimensions &&
@@ -6613,7 +6648,7 @@ export function connectPanePty(
                     }
                   }
                 },
-                { shouldContinue: isCurrentRestore }
+                { shouldContinue: isCurrentRestore, retryIfUnmeasurable: true }
               )
               pendingHiddenSnapshotFit = fit
               try {
@@ -6783,6 +6818,7 @@ export function connectPanePty(
           // still draining from main's ACK backlog below that point are
           // duplicates the dataCallback reconciliation must suppress.
           setRestoredSnapshotBaseline(currentPtyId, snapshot)
+          hiddenOutputRestoreReplayingSnapshot = null
           const needsFreshSnapshot = hiddenOutputRestoreFreshSnapshotNeeded
           hiddenOutputRestoreFreshSnapshotNeeded = false
           const drainOutcome = drainPendingLiveChunksAfterSnapshot(snapshot.seq)
@@ -7162,6 +7198,7 @@ export function connectPanePty(
       // Why: createOrAttach snapshots precede bytes emitted before its IPC
       // reply. Paint the authoritative replay first, then admit those live
       // chunks so the replay clear cannot erase newer output.
+      let deliveredDeferredChunks = 0
       for (const chunk of chunks) {
         if (
           chunk.ptyId !== currentPtyId ||
@@ -7171,6 +7208,23 @@ export function connectPanePty(
           continue
         }
         dataCallback(chunk.data, chunk.meta, chunk.streamGeneration)
+        deliveredDeferredChunks += 1
+      }
+      if (deliveredDeferredChunks > 0) {
+        // Why: replay restores the viewport before these newer bytes parse;
+        // settle the bounded deferred slice, then apply the latest user intent.
+        flushTerminalOutput(pane.terminal, { maxChars: MAX_DEFERRED_REATTACH_LIVE_CHARS })
+        void waitForTerminalReplayWritesParsed(pane.terminal).then(() => {
+          if (
+            disposed ||
+            !deps.isVisibleRef.current ||
+            transport.getPtyId() !== currentPtyId ||
+            transportStreamGeneration !== currentGeneration
+          ) {
+            return
+          }
+          enforceTerminalCurrentScrollIntent(pane.terminal)
+        })
       }
     }
 
@@ -7472,16 +7526,22 @@ export function connectPanePty(
                 window.api.pty.signal(reattachPtyId, 'SIGWINCH')
               }
             },
-            { shouldContinue: isCurrentReattachPayload }
+            { shouldContinue: isCurrentReattachPayload, retryIfUnmeasurable: true }
           )
           pendingReattachFit = fit
+          let fitCompleted = false
           try {
-            await fit.completion
+            fitCompleted = await fit.completion
           } finally {
             if (pendingReattachFit === fit) {
               pendingReattachFit = null
             }
           }
+          if (fitCompleted && isCurrentReattachPayload() && deps.isVisibleRef.current) {
+            // Why: reattach resize is fire-and-forget; verify the provider's
+            // applied grid while this reveal still owns the visible pane.
+            ptySizeReassertion.request({ fit: false })
+          }
         } else if (isCurrentReattachPayload() && !isRemoteRuntimePtyId(reattachPtyId)) {
           window.api.pty.signal(reattachPtyId, 'SIGWINCH')
         }
diff --git a/src/renderer/src/components/terminal-pane/replay-guard.ts b/src/renderer/src/components/terminal-pane/replay-guard.ts
index 6711390d851..b7e43ff82cb 100644
--- a/src/renderer/src/components/terminal-pane/replay-guard.ts
+++ b/src/renderer/src/components/terminal-pane/replay-guard.ts
@@ -64,6 +64,7 @@ const REPLAY_GUARD_STALL_CHECK_MS = 10_000
 
 type ReplayTerminalOptions = {
   shouldRefreshViewportSynchronously?: () => boolean
+  shouldReleaseRenderPause?: () => boolean
   stallCheckMs?: number
 }
 
@@ -208,6 +209,7 @@ export function replayIntoTerminal(
     forceViewportRefresh: true,
     followupViewportRefresh: true,
     shouldRefreshViewportSynchronously: options.shouldRefreshViewportSynchronously,
+    shouldReleaseRenderPause: options.shouldReleaseRenderPause,
     onParsed: guardCallbacks.onParsed,
     onWriteFailure: guardCallbacks.onWriteFailure
   })
@@ -242,6 +244,7 @@ export function replayIntoTerminalAsync(
       forceViewportRefresh: true,
       followupViewportRefresh: true,
       shouldRefreshViewportSynchronously: options.shouldRefreshViewportSynchronously,
+      shouldReleaseRenderPause: options.shouldReleaseRenderPause,
       onParsed: guardCallbacks.onParsed,
       onWriteFailure: guardCallbacks.onWriteFailure
     })
diff --git a/src/renderer/src/lib/pane-manager/pane-fit-continuation-retry.ts b/src/renderer/src/lib/pane-manager/pane-fit-continuation-retry.ts
new file mode 100644
index 00000000000..8567ad44884
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-fit-continuation-retry.ts
@@ -0,0 +1,87 @@
+import { recordRendererCrashBreadcrumb } from '@/lib/crash-breadcrumb-recorder'
+import type { ManagedPane } from './pane-manager-types'
+
+const MAX_RETRY_FRAMES = 40
+const LAYOUT_SETTLE_MS = 16
+
+type RetrySchedule = { cancel: () => void }
+
+type RetryState = {
+  attempts: number
+  schedule: RetrySchedule | null
+  retry: () => boolean
+  onExhausted: () => void
+}
+
+const retryByPane = new WeakMap<ManagedPane, RetryState>()
+
+function scheduleRetryTick(run: () => void): RetrySchedule {
+  if (typeof requestAnimationFrame === 'function') {
+    let cancelled = false
+    let timer: ReturnType<typeof setTimeout> | null = null
+    const rafId = requestAnimationFrame(() => {
+      if (!cancelled) {
+        // Why: FitAddon must observe committed CSS, and synchronous rAF test
+        // shims must not recursively consume the whole retry budget inline.
+        timer = setTimeout(run, LAYOUT_SETTLE_MS)
+      }
+    })
+    return {
+      cancel: () => {
+        cancelled = true
+        if (typeof cancelAnimationFrame === 'function') {
+          cancelAnimationFrame(rafId)
+        }
+        if (timer !== null) {
+          clearTimeout(timer)
+        }
+      }
+    }
+  }
+  const timer = setTimeout(run, LAYOUT_SETTLE_MS)
+  return { cancel: () => clearTimeout(timer) }
+}
+
+export function clearPaneFitContinuationRetry(pane: ManagedPane): void {
+  const state = retryByPane.get(pane)
+  if (!state) {
+    return
+  }
+  retryByPane.delete(pane)
+  state.schedule?.cancel()
+  state.schedule = null
+}
+
+export function armPaneFitContinuationRetry(
+  pane: ManagedPane,
+  callbacks: { retry: () => boolean; onExhausted: () => void }
+): void {
+  const state = retryByPane.get(pane) ?? {
+    attempts: 0,
+    schedule: null,
+    ...callbacks
+  }
+  state.retry = callbacks.retry
+  state.onExhausted = callbacks.onExhausted
+  retryByPane.set(pane, state)
+  if (state.schedule) {
+    return
+  }
+  state.schedule = scheduleRetryTick(() => {
+    state.schedule = null
+    if (state.retry()) {
+      clearPaneFitContinuationRetry(pane)
+      return
+    }
+    state.attempts += 1
+    if (state.attempts >= MAX_RETRY_FRAMES) {
+      recordRendererCrashBreadcrumb('terminal_safe_fit_retry_exhausted', {
+        paneId: pane.id
+      })
+      clearPaneFitContinuationRetry(pane)
+      state.onExhausted()
+      return
+    }
+    armPaneFitContinuationRetry(pane, state)
+  })
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-fit.test.ts b/src/renderer/src/lib/pane-manager/pane-fit.test.ts
new file mode 100644
index 00000000000..5857349e3a6
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-fit.test.ts
@@ -0,0 +1,169 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { recordRendererCrashBreadcrumb } from '@/lib/crash-breadcrumb-recorder'
+import type { ManagedPane, ScrollState } from './pane-manager-types'
+import { safeFit, safeFitAndThen } from './pane-fit'
+
+vi.mock('@/lib/crash-breadcrumb-recorder', () => ({
+  recordRendererCrashBreadcrumb: vi.fn()
+}))
+
+let nextRafId = 1
+let pendingRafs = new Map<number, FrameRequestCallback>()
+
+function flushAnimationFrames(timestamp = 16): void {
+  const callbacks = Array.from(pendingRafs.values())
+  pendingRafs = new Map()
+  for (const callback of callbacks) {
+    callback(timestamp)
+  }
+}
+
+function createPane(options: {
+  rect: { width: number; height: number }
+  proposed?: () => { cols: number; rows: number } | undefined
+}): ManagedPane & { setRect: (rect: { width: number; height: number }) => void } {
+  let rect = options.rect
+  const leafId = '22222222-2222-4222-8222-222222222222'
+  const pane = {
+    id: 7,
+    leafId,
+    stablePaneId: leafId,
+    terminal: { cols: 80, rows: 24 },
+    container: {
+      dataset: {},
+      getBoundingClientRect: () => ({ width: rect.width, height: rect.height })
+    },
+    xtermContainer: {
+      getBoundingClientRect: () => ({ width: rect.width, height: rect.height })
+    },
+    fitAddon: {
+      fit: vi.fn(),
+      proposeDimensions: vi.fn(options.proposed ?? (() => ({ cols: 132, rows: 40 })))
+    },
+    serializeAddon: {},
+    searchAddon: {},
+    pendingSplitScrollState: null as ScrollState | null,
+    setRect: (next: { width: number; height: number }) => {
+      rect = next
+    }
+  }
+  return pane as unknown as ManagedPane & {
+    setRect: (rect: { width: number; height: number }) => void
+  }
+}
+
+describe('safeFitAndThen unmeasurable-pane retry', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    nextRafId = 1
+    pendingRafs = new Map()
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      vi.fn((callback: FrameRequestCallback) => {
+        const id = nextRafId++
+        pendingRafs.set(id, callback)
+        return id
+      })
+    )
+    vi.stubGlobal(
+      'cancelAnimationFrame',
+      vi.fn((id: number) => {
+        pendingRafs.delete(id)
+      })
+    )
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('runs the continuation once reveal layout becomes measurable', async () => {
+    const pane = createPane({ rect: { width: 0, height: 0 } })
+    const continuation = vi.fn()
+
+    const handle = safeFitAndThen(pane, 'reattach-pty-resize', continuation, {
+      retryIfUnmeasurable: true
+    })
+    pane.setRect({ width: 800, height: 600 })
+    flushAnimationFrames()
+    vi.advanceTimersByTime(16)
+
+    expect(continuation).toHaveBeenCalledTimes(1)
+    await expect(handle.completion).resolves.toBe(true)
+  })
+
+  it('cancels its scheduled frame with the continuation', async () => {
+    const pane = createPane({ rect: { width: 0, height: 0 } })
+    const continuation = vi.fn()
+
+    const handle = safeFitAndThen(pane, 'reattach-pty-resize', continuation, {
+      retryIfUnmeasurable: true
+    })
+    handle.cancel()
+    pane.setRect({ width: 800, height: 600 })
+    flushAnimationFrames()
+
+    expect(continuation).not.toHaveBeenCalled()
+    await expect(handle.completion).resolves.toBe(false)
+  })
+
+  it('does not retry a stale restore', async () => {
+    const pane = createPane({ rect: { width: 0, height: 0 } })
+    const continuation = vi.fn()
+    let current = true
+
+    const handle = safeFitAndThen(pane, 'reattach-pty-resize', continuation, {
+      shouldContinue: () => current,
+      retryIfUnmeasurable: true
+    })
+    current = false
+    pane.setRect({ width: 800, height: 600 })
+    flushAnimationFrames()
+    vi.advanceTimersByTime(16)
+
+    expect(continuation).not.toHaveBeenCalled()
+    await expect(handle.completion).resolves.toBe(false)
+  })
+
+  it('still flushes through an ordinary external fit', async () => {
+    const pane = createPane({ rect: { width: 0, height: 0 } })
+    const continuation = vi.fn()
+
+    const handle = safeFitAndThen(pane, 'reattach-pty-resize', continuation)
+    pane.setRect({ width: 800, height: 600 })
+    flushAnimationFrames()
+    vi.advanceTimersByTime(16)
+    expect(continuation).not.toHaveBeenCalled()
+
+    safeFit(pane)
+
+    expect(continuation).toHaveBeenCalledTimes(1)
+    await expect(handle.completion).resolves.toBe(true)
+  })
+
+  it('resolves failure after the bounded frame budget instead of hanging reattach', async () => {
+    const pane = createPane({ rect: { width: 0, height: 0 } })
+    const continuation = vi.fn()
+
+    const handle = safeFitAndThen(pane, 'reattach-pty-resize', continuation, {
+      retryIfUnmeasurable: true
+    })
+    for (let frame = 0; frame < 40; frame += 1) {
+      flushAnimationFrames(frame * 16)
+      vi.advanceTimersByTime(16)
+    }
+
+    expect(continuation).not.toHaveBeenCalled()
+    expect(recordRendererCrashBreadcrumb).toHaveBeenCalledWith(
+      'terminal_safe_fit_retry_exhausted',
+      { paneId: 7 }
+    )
+    await expect(handle.completion).resolves.toBe(false)
+
+    pane.setRect({ width: 800, height: 600 })
+    safeFit(pane)
+    expect(continuation).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/lib/pane-manager/pane-fit.ts b/src/renderer/src/lib/pane-manager/pane-fit.ts
index 573ba6ab7ed..e555a478031 100644
--- a/src/renderer/src/lib/pane-manager/pane-fit.ts
+++ b/src/renderer/src/lib/pane-manager/pane-fit.ts
@@ -1,5 +1,9 @@
 import type { ManagedPane, ManagedPaneInternal, ScrollState } from './pane-manager-types'
 import { getFitOverrideForPty } from './mobile-fit-overrides'
+import {
+  armPaneFitContinuationRetry,
+  clearPaneFitContinuationRetry
+} from './pane-fit-continuation-retry'
 import {
   captureTerminalStructuralScrollIntent,
   isTerminalStructuralScrollIntentCurrent,
@@ -163,6 +167,7 @@ function settlePendingSafeFitContinuation(
   operations.delete(operationKey)
   if (operations.size === 0) {
     pendingSafeFitContinuations.delete(pane)
+    clearPaneFitContinuationRetry(pane)
   }
   pending.resolve(completed)
 }
@@ -192,11 +197,52 @@ export function safeFit(pane: ManagedPane): boolean {
     // Why: replay transactions may be waiting for renderer dimensions; any
     // successful ordinary fit is the event that makes their PTY grid authoritative.
     flushPendingSafeFitContinuations(pane)
+    clearPaneFitContinuationRetry(pane)
   }
   return completed
 }
 
+function pruneStaleSafeFitContinuations(pane: ManagedPane): void {
+  const operations = pendingSafeFitContinuations.get(pane)
+  if (!operations) {
+    return
+  }
+  for (const [operationKey, pending] of operations) {
+    if (!pending.shouldContinue()) {
+      settlePendingSafeFitContinuation(pane, operationKey, pending, false)
+    }
+  }
+}
+
+function failPendingSafeFitContinuations(pane: ManagedPane): void {
+  const operations = pendingSafeFitContinuations.get(pane)
+  if (!operations) {
+    return
+  }
+  for (const [operationKey, pending] of Array.from(operations.entries())) {
+    settlePendingSafeFitContinuation(pane, operationKey, pending, false)
+  }
+}
+
+function armSafeFitContinuationRetry(pane: ManagedPane): void {
+  armPaneFitContinuationRetry(pane, {
+    retry: () => {
+      pruneStaleSafeFitContinuations(pane)
+      if (!pendingSafeFitContinuations.get(pane)?.size) {
+        return true
+      }
+      return safeFit(pane)
+    },
+    onExhausted: () => {
+      // Why: a reveal transaction must degrade after its bounded layout wait;
+      // leaving completion pending forever blocks deferred output release.
+      failPendingSafeFitContinuations(pane)
+    }
+  })
+}
+
 export function cancelPendingSafeFitContinuations(pane: ManagedPane): void {
+  clearPaneFitContinuationRetry(pane)
   const operations = pendingSafeFitContinuations.get(pane)
   if (!operations) {
     return
@@ -213,7 +259,7 @@ export function safeFitAndThen(
   pane: ManagedPane,
   operationKey: string,
   continuation: () => void,
-  options: { shouldContinue?: () => boolean } = {}
+  options: { shouldContinue?: () => boolean; retryIfUnmeasurable?: boolean } = {}
 ): SafeFitContinuationHandle {
   const operations = pendingSafeFitContinuations.get(pane) ?? new Map()
   const replaced = operations.get(operationKey)
@@ -245,13 +291,17 @@ export function safeFitAndThen(
       `safe-fit-and-then:${operationKey}`,
       () => {
         if (pendingSafeFitContinuations.get(pane)?.get(operationKey) === pending) {
-          safeFit(pane)
+          if (!safeFit(pane) && options.retryIfUnmeasurable) {
+            armSafeFitContinuationRetry(pane)
+          }
         }
       }
     )
   ) {
     return { completion, cancel }
   }
-  safeFit(pane)
+  if (!safeFit(pane) && options.retryIfUnmeasurable) {
+    armSafeFitContinuationRetry(pane)
+  }
   return { completion, cancel }
 }
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-foreground-render-settle.test.ts b/src/renderer/src/lib/pane-manager/pane-terminal-foreground-render-settle.test.ts
new file mode 100644
index 00000000000..cb62cd15fb7
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-foreground-render-settle.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from 'vitest'
+import { writeForegroundTerminalChunk } from './pane-terminal-foreground-render-settle'
+
+type RefreshFn = (start: number, end: number, sync?: boolean) => void
+
+type RenderServiceStub = {
+  _isPaused: boolean
+  _needsFullRefresh: boolean
+  refreshRows: ReturnType<typeof vi.fn<RefreshFn>>
+}
+
+function createTerminal(paused: boolean): {
+  terminal: {
+    rows: number
+    buffer: { active: { cursorY: number; baseY: number; viewportY: number } }
+    _core: { refresh: ReturnType<typeof vi.fn<RefreshFn>>; _renderService: RenderServiceStub }
+    refresh: ReturnType<typeof vi.fn<(start: number, end: number) => void>>
+    write: (data: string, callback?: () => void) => void
+  }
+  renderService: RenderServiceStub
+} {
+  const renderService: RenderServiceStub = {
+    _isPaused: paused,
+    _needsFullRefresh: paused,
+    refreshRows: vi.fn<RefreshFn>()
+  }
+  const terminal = {
+    rows: 24,
+    buffer: { active: { cursorY: 0, baseY: 0, viewportY: 0 } },
+    _core: { refresh: vi.fn<RefreshFn>(), _renderService: renderService },
+    refresh: vi.fn<(start: number, end: number) => void>(),
+    write: (_data: string, callback?: () => void) => callback?.()
+  }
+  return { terminal, renderService }
+}
+
+describe('writeForegroundTerminalChunk render-pause ownership', () => {
+  it('drives a paused render only for a currently visible reveal replay', () => {
+    const { terminal, renderService } = createTerminal(true)
+
+    writeForegroundTerminalChunk(terminal, 'replayed snapshot bytes', {
+      forceViewportRefresh: true,
+      shouldReleaseRenderPause: () => true
+    })
+
+    expect(renderService.refreshRows).toHaveBeenCalledWith(0, 23, true)
+    expect(renderService._isPaused).toBe(false)
+    expect(renderService._needsFullRefresh).toBe(false)
+  })
+
+  it('leaves a newly-hidden terminal paused when replay parsing finishes', () => {
+    const { terminal, renderService } = createTerminal(true)
+    let parsed: (() => void) | undefined
+    let visible = true
+    terminal.write = (_data: string, callback?: () => void) => {
+      parsed = callback
+    }
+
+    writeForegroundTerminalChunk(terminal, 'late replay bytes', {
+      forceViewportRefresh: true,
+      shouldReleaseRenderPause: () => visible
+    })
+    visible = false
+    parsed?.()
+
+    expect(renderService.refreshRows).not.toHaveBeenCalled()
+    expect(renderService._isPaused).toBe(true)
+    expect(renderService._needsFullRefresh).toBe(true)
+  })
+
+  it('does not inspect RenderService on the ordinary forced-refresh path', () => {
+    const { terminal, renderService } = createTerminal(true)
+    const renderServiceRead = vi.fn(() => renderService)
+    Object.defineProperty(terminal._core, '_renderService', { get: renderServiceRead })
+
+    writeForegroundTerminalChunk(terminal, 'ordinary output', {
+      forceViewportRefresh: true
+    })
+
+    expect(renderServiceRead).not.toHaveBeenCalled()
+    expect(terminal._core.refresh).toHaveBeenCalledWith(0, 23, true)
+  })
+})
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-foreground-render-settle.ts b/src/renderer/src/lib/pane-manager/pane-terminal-foreground-render-settle.ts
index 4819212adb1..508fb7e1240 100644
--- a/src/renderer/src/lib/pane-manager/pane-terminal-foreground-render-settle.ts
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-foreground-render-settle.ts
@@ -1,3 +1,4 @@
+import { forceRepaintThroughRenderPause } from './terminal-render-pause-release'
 import { runGuardedWriteCompletionStep } from './xterm-write-callback-guard'
 
 export type ForegroundTerminalOutputTarget = {
@@ -20,6 +21,7 @@ type ForegroundTerminalWriteOptions = {
   forceViewportRefresh?: boolean
   followupViewportRefresh?: boolean
   shouldRefreshViewportSynchronously?: () => boolean
+  shouldReleaseRenderPause?: () => boolean
   onParsed?: () => void
   onWriteFailure?: () => void
 }
@@ -36,15 +38,21 @@ type ViewportSnapshot = {
 
 function refreshVisibleRows(
   terminal: ForegroundTerminalOutputTarget,
-  synchronously: boolean
+  synchronously: boolean,
+  shouldReleaseRenderPause?: () => boolean
 ): void {
   if (typeof terminal.rows !== 'number' || terminal.rows < 1) {
     return
   }
 
-  const start = 0
-  const end = Math.max(0, terminal.rows - 1)
   try {
+    // Why: only reveal-owned replay may override xterm's paused observer state;
+    // ordinary or newly-hidden output must leave background rendering paused.
+    if (shouldReleaseRenderPause?.() === true && forceRepaintThroughRenderPause(terminal)) {
+      return
+    }
+    const start = 0
+    const end = Math.max(0, terminal.rows - 1)
     // Why: DOM-rendered Windows ConPTY rewrites need an immediate repair, while
     // WebGL can merge this full-grid request into xterm's already-queued frame.
     if (synchronously && typeof terminal._core?.refresh === 'function') {
@@ -100,13 +108,14 @@ function cancelScheduledViewportSettleRefresh(terminal: ForegroundTerminalOutput
 
 function scheduleViewportSettleRefresh(
   terminal: ForegroundTerminalOutputTarget,
-  shouldRefreshSynchronously?: () => boolean
+  shouldRefreshSynchronously?: () => boolean,
+  shouldReleaseRenderPause?: () => boolean
 ): void {
   cancelScheduledViewportSettleRefresh(terminal)
   if (typeof requestAnimationFrame === 'function') {
     const id = requestAnimationFrame(() => {
       pendingViewportSettleRefreshByTerminal.delete(terminal)
-      refreshVisibleRows(terminal, shouldRefreshSynchronously?.() ?? true)
+      refreshVisibleRows(terminal, shouldRefreshSynchronously?.() ?? true, shouldReleaseRenderPause)
     })
     pendingViewportSettleRefreshByTerminal.set(terminal, { kind: 'raf', id })
     return
@@ -114,7 +123,7 @@ function scheduleViewportSettleRefresh(
 
   const id = setTimeout(() => {
     pendingViewportSettleRefreshByTerminal.delete(terminal)
-    refreshVisibleRows(terminal, shouldRefreshSynchronously?.() ?? true)
+    refreshVisibleRows(terminal, shouldRefreshSynchronously?.() ?? true, shouldReleaseRenderPause)
   }, 16)
   pendingViewportSettleRefreshByTerminal.set(terminal, { kind: 'timeout', id })
 }
@@ -124,7 +133,11 @@ function settleForegroundRender(
   beforeWriteViewport: ViewportSnapshot,
   options: ForegroundTerminalWriteOptions
 ): void {
-  refreshVisibleRows(terminal, options.shouldRefreshViewportSynchronously?.() ?? true)
+  refreshVisibleRows(
+    terminal,
+    options.shouldRefreshViewportSynchronously?.() ?? true,
+    options.shouldReleaseRenderPause
+  )
   // Why: when output advances the viewport, Chromium can paint the freshly
   // scrolled top row one frame later than xterm finishes parsing. Repaint once
   // more after the scroll settles so the user doesn't need to jiggle the window.
@@ -132,7 +145,11 @@ function settleForegroundRender(
     options.followupViewportRefresh ||
     viewportChangedDuringWrite(terminal, beforeWriteViewport)
   ) {
-    scheduleViewportSettleRefresh(terminal, options.shouldRefreshViewportSynchronously)
+    scheduleViewportSettleRefresh(
+      terminal,
+      options.shouldRefreshViewportSynchronously,
+      options.shouldReleaseRenderPause
+    )
   }
 }
 
diff --git a/tests/e2e/fixtures/codex-inline-live-block-fixture.cjs b/tests/e2e/fixtures/codex-inline-live-block-fixture.cjs
new file mode 100644
index 00000000000..78d3596f613
--- /dev/null
+++ b/tests/e2e/fixtures/codex-inline-live-block-fixture.cjs
@@ -0,0 +1,139 @@
+// Codex-like INLINE-mode TUI (normal buffer, never alt-screen): history lines
+// scroll into terminal scrollback while a live block (working spinner + input
+// box + status line) repaints glued to the bottom of the screen, wrapped in
+// synchronized-output brackets. This is the write shape a real Codex CLI
+// produces mid-generation — the shape the alt-screen fixtures cannot cover.
+//
+// argv[2] = heartbeat file path (latest frame number, rewritten every tick).
+// argv[3] = history lines per second (default 4) — raise it so a hidden/parked
+//           window accumulates a field-sized backlog for the reveal to race.
+// The stream NEVER stops on its own; tests park/hide/reveal around it and
+// assert the revealed terminal converges to the live frame without a resize.
+const fs = require('node:fs')
+
+const heartbeatPath = process.argv[2]
+const TICK_MS = 60
+const HISTORY_LINES_PER_SECOND = Math.max(0, Number(process.argv[3]) || 4)
+const BLOCK_ROWS = 6
+// argv[4]: seed scrollback size — a field Codex session carries thousands of
+// lines, which is what makes the reveal replay long enough to lose races.
+const INITIAL_HISTORY_LINES = Math.max(0, Number(process.argv[4]) || 120)
+
+let frame = 0
+let hist = 0
+
+function rows() {
+  return process.stdout.rows || 24
+}
+
+function cols() {
+  return process.stdout.columns || 80
+}
+
+function historyLine() {
+  hist += 1
+  return `HIST_${String(hist).padStart(6, '0')} tool call output ${'-'.repeat(24)}`
+}
+
+function liveBlock() {
+  const width = Math.max(20, Math.min(cols() - 2, 76))
+  const bar = '─'.repeat(width)
+  const pad = (text) => `${`│ ${text}`.padEnd(width + 1, ' ')}│`
+  const top = Math.max(1, rows() - BLOCK_ROWS + 1)
+  const lines = [
+    `╭${bar}╮`,
+    pad(`CODEX_FRAME_${String(frame).padStart(6, '0')} working${'.'.repeat(frame % 4).padEnd(3)}`),
+    pad(`tokens ${frame * 17} · ${frame % 2 === 0 ? 'thinking' : 'streaming'}`),
+    `╰${bar}╯`,
+    '› INPUT_BOX_READY_MARKER',
+    'status: streaming · esc to interrupt'
+  ]
+  // Absolute-position to the block top and clear below, like ratatui's inline
+  // viewport redraw.
+  return `\x1b[${top};1H\x1b[J${lines.join('\r\n')}`
+}
+
+// ratatui insert_before-style history: scroll one line into scrollback from
+// the bottom row, then write the new history line just above the live block.
+function insertHistory(count) {
+  const r = rows()
+  const histTop = Math.max(1, r - BLOCK_ROWS)
+  let out = ''
+  for (let i = 0; i < count; i += 1) {
+    out += `\x1b[${r};1H\n\x1b[${histTop};1H${historyLine()}`
+  }
+  return out
+}
+
+let historyCarry = 0
+
+function tick() {
+  frame += 1
+  historyCarry += (HISTORY_LINES_PER_SECOND * TICK_MS) / 1000
+  const historyThisTick = Math.floor(historyCarry)
+  historyCarry -= historyThisTick
+  let out = '\x1b[?2026h\x1b[?25l'
+  if (historyThisTick > 0) {
+    out += insertHistory(historyThisTick)
+  }
+  out += liveBlock()
+  out += '\x1b[?25h\x1b[?2026l'
+  process.stdout.write(out)
+  if (heartbeatPath) {
+    try {
+      fs.writeFileSync(heartbeatPath, String(frame))
+    } catch {
+      // heartbeat is best-effort; the stream itself is the product
+    }
+  }
+}
+
+// Codex-shaped startup: terminal queries (answered by xterm or the daemon's
+// model responder) and mouse reporting, so the run takes the live-agent
+// classification branches instead of the plain-shell ones.
+process.stdout.write('\x1b[c\x1b[6n\x1b]10;?\x07\x1b]11;?\x07')
+process.stdout.write('\x1b[?1002h\x1b[?1006h')
+
+// Seed scrollback before any park so the reveal replays real history.
+{
+  const seed = []
+  for (let i = 0; i < INITIAL_HISTORY_LINES; i += 1) {
+    seed.push(historyLine())
+  }
+  process.stdout.write(`${seed.join('\r\n')}\r\n`)
+}
+
+const tickTimer = setInterval(tick, TICK_MS)
+// A real inline TUI fully repaints its live block on SIGWINCH. Keep that
+// behavior for realism, but tests must converge WITHOUT relying on it.
+process.stdout.on('resize', () => {
+  process.stdout.write(`\x1b[?2026h\x1b[?25l${liveBlock()}\x1b[?25h\x1b[?2026l`)
+})
+// Swallow query replies / mouse reports / keys like a real TUI agent.
+process.stdin.resume()
+if (process.stdin.isTTY) {
+  process.stdin.setRawMode(true)
+}
+
+let stopping = false
+function stop() {
+  if (stopping) {
+    return
+  }
+  stopping = true
+  clearInterval(tickTimer)
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(false)
+  }
+  // Why: the e2e sends Ctrl+C while raw mode is active, so Node receives a
+  // byte instead of SIGINT; explicitly restore modes and terminate the fixture.
+  process.stdout.write('\x1b[?1002l\x1b[?1006l\x1b[?25h\x1b[?2026l', () => process.exit(0))
+}
+
+process.stdin.on('data', (data) => {
+  if (Buffer.from(data).includes(3)) {
+    stop()
+  }
+})
+process.on('SIGINT', stop)
+process.on('SIGTERM', stop)
diff --git a/tests/e2e/terminal-inline-tui-reveal-convergence.spec.ts b/tests/e2e/terminal-inline-tui-reveal-convergence.spec.ts
new file mode 100644
index 00000000000..f0ba620eb2c
--- /dev/null
+++ b/tests/e2e/terminal-inline-tui-reveal-convergence.spec.ts
@@ -0,0 +1,718 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { PNG } from 'pngjs'
+import type { ElectronApplication, Page, TestInfo } from '@stablyai/playwright-test'
+import { test, expect } from './helpers/orca-app'
+import {
+  ensureTerminalVisible,
+  getActiveTabId,
+  switchToOtherWorktree,
+  switchToWorktree,
+  waitForActiveWorktree,
+  waitForSessionReady
+} from './helpers/store'
+import {
+  sendToTerminal,
+  waitForActiveTerminalManager,
+  waitForPaneIdentitySnapshot
+} from './helpers/terminal'
+import { waitForTabParked } from './helpers/terminal-hidden-parking'
+
+// Field bug (v1.4.144-rc.4): switching back to a workspace whose Codex TUI kept
+// streaming while hidden shows a mostly-blank terminal — live block (input box)
+// missing, viewport stranded mid-buffer — until a manual resize (Cmd+L) forces
+// SIGWINCH and Codex repaints. The alt-screen park/reveal specs never caught it
+// because Codex runs in INLINE mode and keeps writing across the reveal.
+//
+// These tests drive a codex-shaped inline TUI that never stops writing, hide
+// the pane across the gate/park boundaries, reveal, and require convergence to
+// the live frame WITHOUT any resize:
+//  1. viewport anchored at the buffer bottom (not stranded mid-scrollback),
+//  2. a recent CODEX_FRAME + the input-box row visible in the on-screen rows,
+//  3. still following (frame number advances on screen) after convergence,
+//  4. xterm grid == fit proposal == PTY-applied size (no stale 80x24 PTY).
+
+const PARKING_DELAY_MS = Number(process.env.ORCA_E2E_TERMINAL_PARKING_DELAY_MS) || 500
+
+test.use({
+  orcaAppExtraEnv: { ORCA_E2E_TERMINAL_PARKING_DELAY_MS: String(PARKING_DELAY_MS) }
+})
+
+const FIXTURE_PATH = path.join(__dirname, 'fixtures', 'codex-inline-live-block-fixture.cjs')
+const FRAME_RE = /CODEX_FRAME_(\d+)/g
+const INPUT_BOX_MARKER = 'INPUT_BOX_READY_MARKER'
+// The fixture ticks every 60ms; allow a generous parse/delivery lag while
+// still rejecting a frozen frame from before the hide.
+const MAX_VISIBLE_FRAME_LAG = 50
+
+type RevealProbe = {
+  ptyId: string | null
+  viewportY: number
+  baseY: number
+  cols: number
+  rows: number
+  proposed: { cols: number; rows: number } | null
+  appliedPtySize: { cols: number; rows: number } | null
+  screenRows: string[]
+}
+
+function latestFrame(text: string): number {
+  let latest = -1
+  for (const match of text.matchAll(FRAME_RE)) {
+    latest = Math.max(latest, Number(match[1]))
+  }
+  return latest
+}
+
+function heartbeatFrame(heartbeatPath: string): number {
+  try {
+    return Number(readFileSync(heartbeatPath, 'utf8').trim())
+  } catch {
+    return -1
+  }
+}
+
+// Why the pane resolves by tab (not a captured ptyId): agent quick-launch
+// startup can respawn the tab's PTY after the initial bind, so a ptyId
+// captured at mount can go stale while the pane itself stays healthy.
+async function probeRevealedPane(page: Page, tabId: string): Promise<RevealProbe | null> {
+  return page.evaluate(
+    async ({ tabId }) => {
+      const manager = window.__paneManagers?.get(tabId)
+      const pane = manager?.getActivePane?.() ?? manager?.getPanes?.()[0] ?? null
+      if (!pane) {
+        return null
+      }
+      const ptyId = pane.container.dataset.ptyId ?? null
+      const terminal = pane.terminal
+      const buffer = terminal.buffer.active
+      const screenRows: string[] = []
+      for (let i = 0; i < terminal.rows; i += 1) {
+        const line = buffer.getLine(buffer.viewportY + i)
+        screenRows.push(line ? line.translateToString(true) : '')
+      }
+      let proposed: { cols: number; rows: number } | null = null
+      try {
+        proposed = pane.fitAddon.proposeDimensions() ?? null
+      } catch {
+        proposed = null
+      }
+      let appliedPtySize: { cols: number; rows: number } | null = null
+      try {
+        appliedPtySize = ptyId ? ((await window.api.pty.getSize(ptyId)) ?? null) : null
+      } catch {
+        appliedPtySize = null
+      }
+      return {
+        ptyId,
+        viewportY: buffer.viewportY,
+        baseY: buffer.baseY,
+        cols: terminal.cols,
+        rows: terminal.rows,
+        proposed,
+        appliedPtySize,
+        screenRows
+      }
+    },
+    { tabId }
+  )
+}
+
+// Painted-pixels check: buffer-level assertions cannot see paint-layer bugs
+// (atlas wipe races, paused-RenderService swallowed refreshes), where xterm's
+// buffer is perfect but the canvas shows blank/stale cells until a resize.
+// Measure the "ink" (non-background pixel ratio) of a horizontal band of the
+// pane screenshot; the fixture's live block guarantees box-drawing + text ink
+// in its bottom rows whenever paint is healthy.
+function measureBandInkRatio(
+  screenshot: Buffer,
+  bandTopFraction: number,
+  bandBottomFraction: number
+): number {
+  const png = PNG.sync.read(screenshot)
+  const colorCounts = new Map<number, number>()
+  for (let offset = 0; offset < png.data.length; offset += 32) {
+    const key =
+      ((png.data[offset] ?? 0) << 16) |
+      ((png.data[offset + 1] ?? 0) << 8) |
+      (png.data[offset + 2] ?? 0)
+    colorCounts.set(key, (colorCounts.get(key) ?? 0) + 1)
+  }
+  let backgroundKey = 0
+  let backgroundCount = -1
+  for (const [key, count] of colorCounts) {
+    if (count > backgroundCount) {
+      backgroundKey = key
+      backgroundCount = count
+    }
+  }
+  const backgroundRed = (backgroundKey >> 16) & 0xff
+  const backgroundGreen = (backgroundKey >> 8) & 0xff
+  const backgroundBlue = backgroundKey & 0xff
+  const yStart = Math.max(0, Math.floor(png.height * bandTopFraction))
+  const yEnd = Math.min(png.height, Math.ceil(png.height * bandBottomFraction))
+  let ink = 0
+  let total = 0
+  for (let y = yStart; y < yEnd; y += 1) {
+    for (let x = 0; x < png.width; x += 1) {
+      const offset = (y * png.width + x) * 4
+      const diff =
+        Math.abs((png.data[offset] ?? 0) - backgroundRed) +
+        Math.abs((png.data[offset + 1] ?? 0) - backgroundGreen) +
+        Math.abs((png.data[offset + 2] ?? 0) - backgroundBlue)
+      total += 1
+      if (diff > 48) {
+        ink += 1
+      }
+    }
+  }
+  return total > 0 ? ink / total : 0
+}
+
+async function forceWebglOnActiveTab(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const state = window.__store?.getState()
+    if (!state?.settings) {
+      throw new Error('Store unavailable')
+    }
+    window.__store?.setState({
+      settings: {
+        ...state.settings,
+        terminalGpuAcceleration: 'on'
+      }
+    })
+    const worktreeId = state.activeWorktreeId
+    const tabId =
+      state.activeTabType === 'terminal'
+        ? state.activeTabId
+        : worktreeId
+          ? (state.activeTabIdByWorktree?.[worktreeId] ?? null)
+          : null
+    window.__paneManagers?.get(tabId ?? '')?.setTerminalGpuAcceleration?.('on')
+  })
+}
+
+async function paneClipRect(
+  page: Page,
+  tabId: string
+): Promise<{ x: number; y: number; width: number; height: number } | null> {
+  return page.evaluate((tabId) => {
+    const manager = window.__paneManagers?.get(tabId)
+    const pane = manager?.getActivePane?.() ?? manager?.getPanes?.()[0] ?? null
+    if (!pane) {
+      return null
+    }
+    const rect = pane.container.getBoundingClientRect()
+    if (rect.width < 10 || rect.height < 10) {
+      return null
+    }
+    return { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
+  }, tabId)
+}
+
+async function isTerminalPaneMounted(page: Page, tabId: string): Promise<boolean> {
+  return page.evaluate((tabId) => {
+    const manager = window.__paneManagers?.get(tabId)
+    return Boolean(manager && manager.getPanes().length > 0)
+  }, tabId)
+}
+
+function describeProbe(probe: RevealProbe | null): string {
+  if (!probe) {
+    return 'pane not mounted'
+  }
+  return JSON.stringify(
+    {
+      viewportY: probe.viewportY,
+      baseY: probe.baseY,
+      cols: probe.cols,
+      rows: probe.rows,
+      proposed: probe.proposed,
+      appliedPtySize: probe.appliedPtySize,
+      screenTail: probe.screenRows.slice(-10)
+    },
+    null,
+    1
+  )
+}
+
+async function activateTerminalTab(page: Page, tabId: string): Promise<void> {
+  await page.evaluate((targetTabId) => {
+    const store = window.__store
+    if (!store) {
+      throw new Error('activateTerminalTab: window.__store is unavailable')
+    }
+    const state = store.getState()
+    state.setActiveTabType('terminal')
+    state.setActiveTab(targetTabId)
+  }, tabId)
+  await expect
+    .poll(() => getActiveTabId(page), {
+      timeout: 5_000,
+      message: `terminal tab ${tabId} did not become active`
+    })
+    .toBe(tabId)
+}
+
+async function createActiveTerminalTab(page: Page, worktreeId: string): Promise<string> {
+  const tabId = await page.evaluate((worktreeId) => {
+    const store = window.__store
+    if (!store) {
+      throw new Error('createActiveTerminalTab: window.__store is unavailable')
+    }
+    const state = store.getState()
+    const tab = state.createTab(worktreeId, undefined, undefined, { activate: true })
+    state.setActiveTab(tab.id)
+    state.setActiveTabType('terminal')
+    return tab.id
+  }, worktreeId)
+  await expect
+    .poll(() => getActiveTabId(page), {
+      timeout: 5_000,
+      message: 'newly created terminal tab did not become active'
+    })
+    .toBe(tabId)
+  await waitForActiveTerminalManager(page, 30_000)
+  await waitForPaneIdentitySnapshot(page, 1)
+  return tabId
+}
+
+type StreamingTabSetup = {
+  worktreeId: string
+  tabId: string
+  ptyId: string
+  heartbeatPath: string
+  stop: () => Promise<void>
+}
+
+// Why a fresh tab per test: the app instance is shared across this file's
+// serial tests, so reusing the initial tab would type the launch command into
+// the previous test's still-running fixture instead of a shell prompt.
+//
+// Why agent-marked: a real Codex tab carries launchAgent/telemetry, which
+// flips the reveal into the live-agent reattach branches (mode-preserving
+// resets, hidden startup query grammar, post-replay focus-in) — the branches
+// the field bug lives behind.
+async function startStreamingInlineTui(
+  page: Page,
+  testInfo: TestInfo,
+  options: { historyLinesPerSecond?: number; seedLines?: number } = {}
+): Promise<StreamingTabSetup> {
+  await waitForSessionReady(page)
+  const worktreeId = await waitForActiveWorktree(page)
+  await ensureTerminalVisible(page)
+  const heartbeatPath = testInfo.outputPath(`codex-inline-heartbeat-${Date.now()}.txt`)
+  const command = `node ${JSON.stringify(FIXTURE_PATH)} ${JSON.stringify(heartbeatPath)} ${options.historyLinesPerSecond ?? 4} ${options.seedLines ?? 120}`
+  const tabId = await page.evaluate(
+    ({ worktreeId, command }) => {
+      const store = window.__store
+      if (!store) {
+        throw new Error('startStreamingInlineTui: window.__store is unavailable')
+      }
+      const state = store.getState()
+      const tab = state.createTab(worktreeId, undefined, undefined, { launchAgent: 'codex' })
+      state.queueTabStartupCommand(tab.id, {
+        command,
+        launchAgent: 'codex',
+        telemetry: {
+          agent_kind: 'codex',
+          launch_source: 'tab_bar_quick_launch',
+          request_kind: 'new'
+        }
+      })
+      state.setActiveTab(tab.id)
+      state.setActiveTabType('terminal')
+      return tab.id
+    },
+    { worktreeId, command }
+  )
+  await expect
+    .poll(() => getActiveTabId(page), {
+      timeout: 5_000,
+      message: 'agent-marked streaming tab did not become active'
+    })
+    .toBe(tabId)
+  await waitForActiveTerminalManager(page, 30_000)
+  await waitForPaneIdentitySnapshot(page, 1)
+  // WebGL on: the paint-layer seams under test (atlas wipes, render-pause
+  // release) only exist on the GPU renderer path.
+  await forceWebglOnActiveTab(page)
+  await expect
+    .poll(
+      async () => latestFrame((await probeRevealedPane(page, tabId))?.screenRows.join('\n') ?? ''),
+      {
+        timeout: 20_000,
+        message: 'inline TUI fixture did not start streaming in the visible pane'
+      }
+    )
+    .toBeGreaterThan(5)
+  // Capture the PTY id only after the fixture streams: agent quick-launch can
+  // respawn the tab's PTY when the startup command binds.
+  const ptyId = (await probeRevealedPane(page, tabId))?.ptyId
+  if (!ptyId) {
+    throw new Error('streaming tab did not bind a PTY')
+  }
+  return {
+    worktreeId,
+    tabId,
+    ptyId,
+    heartbeatPath,
+    stop: async () => {
+      // Ctrl+C so the shared app does not accumulate streaming fixtures.
+      await sendToTerminal(page, ptyId, '\x03').catch(() => {})
+      await page.waitForTimeout(100)
+    }
+  }
+}
+
+async function assertRevealConvergence(
+  page: Page,
+  testInfo: TestInfo,
+  setup: StreamingTabSetup,
+  label: string
+): Promise<void> {
+  const { tabId, heartbeatPath } = setup
+
+  // Premise: the fixture kept streaming while hidden.
+  const heartbeatAtReveal = heartbeatFrame(heartbeatPath)
+  expect(heartbeatAtReveal, 'fixture stopped streaming while hidden').toBeGreaterThan(5)
+
+  let lastProbe: RevealProbe | null = null
+  await expect
+    .poll(
+      async () => {
+        lastProbe = await probeRevealedPane(page, tabId)
+        if (!lastProbe) {
+          return 'pane-not-mounted'
+        }
+        if (lastProbe.viewportY !== lastProbe.baseY) {
+          return `viewport-stranded viewportY=${lastProbe.viewportY} baseY=${lastProbe.baseY}`
+        }
+        const screen = lastProbe.screenRows.join('\n')
+        if (!screen.includes(INPUT_BOX_MARKER)) {
+          return 'input-box-row-missing'
+        }
+        const visibleFrame = latestFrame(screen)
+        const liveFrame = heartbeatFrame(heartbeatPath)
+        if (visibleFrame < 0 || liveFrame - visibleFrame > MAX_VISIBLE_FRAME_LAG) {
+          return `stale-frame visible=${visibleFrame} live=${liveFrame}`
+        }
+        return 'converged'
+      },
+      {
+        timeout: 20_000,
+        message: `${label}: revealed pane did not converge to the live inline TUI without a resize`
+      }
+    )
+    .toBe('converged')
+    .catch(async (error) => {
+      testInfo.annotations.push({
+        type: `${label}-divergence-probe`,
+        description: describeProbe(lastProbe)
+      })
+      const screenshotPath = testInfo.outputPath(`${label}-divergence.png`)
+      await page.screenshot({ path: screenshotPath, fullPage: true })
+      await testInfo.attach(`${label}-divergence.png`, {
+        path: screenshotPath,
+        contentType: 'image/png'
+      })
+      throw error
+    })
+
+  // Still following: the on-screen frame must keep advancing after convergence
+  // with the viewport still pinned to the bottom.
+  const convergedFrame = latestFrame(
+    (await probeRevealedPane(page, tabId))?.screenRows.join('\n') ?? ''
+  )
+  await expect
+    .poll(
+      async () => {
+        const probe = await probeRevealedPane(page, tabId)
+        if (!probe || probe.viewportY !== probe.baseY) {
+          return -1
+        }
+        return latestFrame(probe.screenRows.join('\n'))
+      },
+      {
+        timeout: 10_000,
+        message: `${label}: revealed pane stopped following live output after convergence`
+      }
+    )
+    .toBeGreaterThan(convergedFrame)
+
+  // Geometry: no stale-80x24 leg — xterm grid, fit proposal, and PTY-applied
+  // size must agree without any manual resize.
+  const probe = await probeRevealedPane(page, tabId)
+  expect(probe, `${label}: pane disappeared after convergence`).not.toBeNull()
+  expect(probe!.proposed, `${label}: fit proposal diverges: ${describeProbe(probe)}`).toEqual({
+    cols: probe!.cols,
+    rows: probe!.rows
+  })
+  expect(
+    probe!.appliedPtySize,
+    `${label}: PTY applied-size read unavailable: ${describeProbe(probe)}`
+  ).not.toBeNull()
+  expect(
+    probe!.appliedPtySize,
+    `${label}: PTY applied size diverges: ${describeProbe(probe)}`
+  ).toEqual({ cols: probe!.cols, rows: probe!.rows })
+
+  // Painted pixels: the live block guarantees box-drawing + text ink in the
+  // pane's bottom rows. Blank band + healthy buffer = paint-layer divergence
+  // (atlas wipe race / paused RenderService) — the class a resize also heals.
+  const clip = await paneClipRect(page, tabId)
+  expect(clip, `${label}: pane rect unavailable for paint check`).not.toBeNull()
+  const bandTop = Math.max(0, 1 - 8 / (probe!.rows || 24))
+  await expect
+    .poll(
+      async () => {
+        const shot = await page.screenshot({ clip: clip! })
+        return measureBandInkRatio(shot, bandTop, 1)
+      },
+      {
+        timeout: 10_000,
+        message: `${label}: live block rows painted blank while the buffer holds content (paint-layer divergence)`
+      }
+    )
+    .toBeGreaterThan(0.005)
+}
+
+async function resizeAppWindow(
+  electronApp: ElectronApplication,
+  deltaWidth: number,
+  deltaHeight: number
+): Promise<void> {
+  // Why the retry: the main-process utility context Playwright evaluates in
+  // can be transiently recycled ("Execution context was destroyed") right
+  // after heavy renderer work like a worktree switch; the resize itself is
+  // idempotent-safe to attempt again.
+  let lastError: unknown = null
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      await electronApp.evaluate(
+        ({ BrowserWindow }, { deltaWidth, deltaHeight }) => {
+          const window = BrowserWindow.getAllWindows()[0]
+          if (!window) {
+            throw new Error('No Electron window')
+          }
+          const [width, height] = window.getSize()
+          window.setSize(width + deltaWidth, height + deltaHeight)
+        },
+        { deltaWidth, deltaHeight }
+      )
+      return
+    } catch (error) {
+      lastError = error
+      await new Promise((resolve) => setTimeout(resolve, 500))
+    }
+  }
+  throw lastError
+}
+
+// CPU throttling around the reveal action simulates the loaded-machine
+// conditions the field failures occur under, deterministically.
+async function withCpuThrottle<T>(page: Page, rate: number, run: () => Promise<T>): Promise<T> {
+  const session = await page.context().newCDPSession(page)
+  try {
+    await session.send('Emulation.setCPUThrottlingRate', { rate })
+    return await run()
+  } finally {
+    await session.send('Emulation.setCPUThrottlingRate', { rate: 1 }).catch(() => {})
+    await session.detach().catch(() => {})
+  }
+}
+
+async function streamWhileParked(setup: StreamingTabSetup, minFrames: number): Promise<void> {
+  const heartbeatBefore = heartbeatFrame(setup.heartbeatPath)
+  await expect
+    .poll(() => heartbeatFrame(setup.heartbeatPath), {
+      timeout: 60_000,
+      message: 'fixture did not keep streaming while hidden/parked'
+    })
+    .toBeGreaterThan(heartbeatBefore + minFrames)
+}
+
+test.describe('Inline TUI reveal convergence', () => {
+  test('hidden-but-mounted tab reveal converges while the inline TUI streams', async ({
+    orcaPage
+  }, testInfo) => {
+    test.setTimeout(120_000)
+    const setup = await startStreamingInlineTui(orcaPage, testInfo)
+    try {
+      // Tab B hides tab A. Reveal quickly — inside the cold-park delay — so
+      // the reveal exercises the hidden-delivery-gate restore, not parking.
+      const tabBId = await createActiveTerminalTab(orcaPage, setup.worktreeId)
+      expect(tabBId).not.toBe(setup.tabId)
+      await orcaPage.waitForTimeout(Math.max(50, Math.min(PARKING_DELAY_MS / 2, 200)))
+      expect(
+        await isTerminalPaneMounted(orcaPage, setup.tabId),
+        'hidden-mounted scenario cold-parked before reveal'
+      ).toBe(true)
+
+      await activateTerminalTab(orcaPage, setup.tabId)
+      await waitForActiveTerminalManager(orcaPage, 30_000)
+      await assertRevealConvergence(orcaPage, testInfo, setup, 'hidden-mounted-reveal')
+    } finally {
+      await setup.stop()
+    }
+  })
+
+  test('worktree switch reveal converges after a hidden-time window resize', async ({
+    orcaPage,
+    electronApp
+  }, testInfo) => {
+    test.setTimeout(120_000)
+    const setup = await startStreamingInlineTui(orcaPage, testInfo, {
+      historyLinesPerSecond: 20
+    })
+    try {
+      // Surface hide: switch to ANOTHER WORKTREE (the field action), which
+      // suspends rendering and takes the heavy resume path on return.
+      const otherWorktreeId = await switchToOtherWorktree(orcaPage, setup.worktreeId)
+      test.skip(!otherWorktreeId, 'test session has a single worktree; cannot surface-hide')
+
+      // Change the window size while the pane is display:none (0x0 container,
+      // no fit runs). This is what Cmd+L's sidebar toggle does to every hidden
+      // workspace: at reveal the pane grid differs from the daemon snapshot's.
+      await resizeAppWindow(electronApp, -180, -120)
+      await orcaPage.waitForTimeout(2_500)
+
+      await switchToWorktree(orcaPage, setup.worktreeId)
+      await activateTerminalTab(orcaPage, setup.tabId)
+      await waitForActiveTerminalManager(orcaPage, 30_000)
+      await assertRevealConvergence(orcaPage, testInfo, setup, 'worktree-resize-reveal')
+    } finally {
+      await resizeAppWindow(electronApp, 180, 120).catch(() => {})
+      await setup.stop()
+    }
+  })
+
+  test('parked tab reveal converges across repeated cycles while the inline TUI streams heavily', async ({
+    orcaPage
+  }, testInfo) => {
+    test.setTimeout(480_000)
+    const setup = await startStreamingInlineTui(orcaPage, testInfo, {
+      historyLinesPerSecond: 30,
+      seedLines: 8_000
+    })
+    try {
+      // Tab B hides tab A; the decoy then hides tab B so B (most recently
+      // hidden) takes the #8262 last-active exemption and tab A cold-parks.
+      const tabBId = await createActiveTerminalTab(orcaPage, setup.worktreeId)
+      const decoyTabId = await createActiveTerminalTab(orcaPage, setup.worktreeId)
+
+      // The field failure is periodic, not every reveal — cycle the park →
+      // stream → reveal boundary and require convergence every time.
+      const CYCLES = 6
+      for (let cycle = 0; cycle < CYCLES; cycle += 1) {
+        if (cycle > 0) {
+          await activateTerminalTab(orcaPage, tabBId)
+          await activateTerminalTab(orcaPage, decoyTabId)
+        }
+        await waitForTabParked(orcaPage, setup.tabId, { parkDelayMs: PARKING_DELAY_MS })
+
+        // Accumulate a field-sized backlog against the parked (unmounted)
+        // view so the reveal replay races the live stream, like a real Codex.
+        await streamWhileParked(setup, 100)
+
+        // Reveal under CPU throttle: a long replay parse + throttled frames is
+        // the loaded-machine window where the corrective fit and follow-anchor
+        // lose their races in the field.
+        await withCpuThrottle(orcaPage, 6, async () => {
+          await activateTerminalTab(orcaPage, setup.tabId)
+          await waitForActiveTerminalManager(orcaPage, 30_000)
+          await orcaPage.waitForTimeout(3_000)
+        })
+        const revealed = await waitForPaneIdentitySnapshot(orcaPage, 1)
+        expect(revealed.panes[0]?.ptyId).toBe(setup.ptyId)
+        await assertRevealConvergence(orcaPage, testInfo, setup, `parked-heavy-reveal-c${cycle}`)
+      }
+    } finally {
+      await setup.stop()
+    }
+  })
+
+  test('rapid tab hide/reveal flapping never wedges delivery for the streaming inline TUI', async ({
+    orcaPage
+  }, testInfo) => {
+    test.setTimeout(150_000)
+    const setup = await startStreamingInlineTui(orcaPage, testInfo, {
+      historyLinesPerSecond: 10
+    })
+    try {
+      const tabBId = await createActiveTerminalTab(orcaPage, setup.worktreeId)
+      // Rapid flapping drives the hidden-delivery gate claim/release IPC and
+      // the hidden-output restore against each other at varied phases — the
+      // desync class behind "bytes dropped on a visible pane" field freezes.
+      for (let flap = 0; flap < 12; flap += 1) {
+        await activateTerminalTab(orcaPage, tabBId)
+        await orcaPage.waitForTimeout(50 + (flap % 3) * 120)
+        await activateTerminalTab(orcaPage, setup.tabId)
+        await orcaPage.waitForTimeout(50 + ((flap * 7) % 5) * 90)
+      }
+      await waitForActiveTerminalManager(orcaPage, 30_000)
+      await assertRevealConvergence(orcaPage, testInfo, setup, 'tab-flapping-reveal')
+    } finally {
+      await setup.stop()
+    }
+  })
+
+  test('rapid worktree switch flapping never wedges delivery for the streaming inline TUI', async ({
+    orcaPage
+  }, testInfo) => {
+    test.setTimeout(150_000)
+    const setup = await startStreamingInlineTui(orcaPage, testInfo, {
+      historyLinesPerSecond: 10,
+      seedLines: 4_000
+    })
+    try {
+      const otherWorktreeId = await switchToOtherWorktree(orcaPage, setup.worktreeId)
+      test.skip(!otherWorktreeId, 'test session has a single worktree; cannot surface-flap')
+      // Surface-level flapping (the field action): suspend/resume rendering +
+      // heavy resume path race the gate resync and reveal repaint each cycle,
+      // under CPU throttle to widen the race windows like a loaded machine.
+      await withCpuThrottle(orcaPage, 6, async () => {
+        for (let flap = 0; flap < 10; flap += 1) {
+          await switchToWorktree(orcaPage, otherWorktreeId!)
+          await orcaPage.waitForTimeout(60 + (flap % 4) * 110)
+          await switchToWorktree(orcaPage, setup.worktreeId)
+          await orcaPage.waitForTimeout(60 + ((flap * 5) % 4) * 130)
+        }
+      })
+      await activateTerminalTab(orcaPage, setup.tabId)
+      await waitForActiveTerminalManager(orcaPage, 30_000)
+      await assertRevealConvergence(orcaPage, testInfo, setup, 'worktree-flapping-reveal')
+    } finally {
+      await setup.stop()
+    }
+  })
+
+  test('parked tab reveal converges after a parked-time window resize', async ({
+    orcaPage,
+    electronApp
+  }, testInfo) => {
+    test.setTimeout(180_000)
+    const setup = await startStreamingInlineTui(orcaPage, testInfo, {
+      historyLinesPerSecond: 20
+    })
+    try {
+      await createActiveTerminalTab(orcaPage, setup.worktreeId)
+      await createActiveTerminalTab(orcaPage, setup.worktreeId)
+      await waitForTabParked(orcaPage, setup.tabId, { parkDelayMs: PARKING_DELAY_MS })
+
+      // Resize while parked: the remount measures a grid that matches neither
+      // the pre-park xterm nor the daemon snapshot — maximum dimension churn.
+      await resizeAppWindow(electronApp, -180, -120)
+      await streamWhileParked(setup, 100)
+
+      await activateTerminalTab(orcaPage, setup.tabId)
+      await waitForActiveTerminalManager(orcaPage, 30_000)
+      const revealed = await waitForPaneIdentitySnapshot(orcaPage, 1)
+      expect(revealed.panes[0]?.ptyId).toBe(setup.ptyId)
+      await assertRevealConvergence(orcaPage, testInfo, setup, 'parked-resize-reveal')
+    } finally {
+      await resizeAppWindow(electronApp, 180, 120).catch(() => {})
+      await setup.stop()
+    }
+  })
+})

From c0f0810dd9c89c57e2130e5d7b5adcbef883845c Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Sun, 19 Jul 2026 20:25:52 -0700
Subject: [PATCH 23/54] Fix native Windows PTY startup query handling (#9500)

* Fix native Windows PTY startup query handling

* Fix daemon boot smoke protocol lookup

* Fix Windows daemon repro protocol lookup
---
 config/scripts/daemon-boot-smoke.mjs          |   5 +-
 .../windows-daemon-workspace-close-repro.mjs  |   5 +-
 ...onpty-startup-query-and-focus-authority.md | 523 ++++++++++++++++++
 src/main/daemon/daemon-protocol-version.ts    |  12 +
 src/main/daemon/daemon-pty-adapter.test.ts    |  66 +++
 src/main/daemon/daemon-pty-adapter.ts         |  34 +-
 src/main/daemon/daemon-pty-router.ts          |  14 +-
 src/main/daemon/daemon-server.ts              |  16 +-
 .../daemon/daemon-stream-data-batcher.test.ts |  17 +
 src/main/daemon/daemon-stream-data-batcher.ts |  49 +-
 src/main/daemon/daemon-stream-data-entry.ts   |  46 ++
 src/main/daemon/daemon-stream-data-split.ts   |  42 +-
 src/main/daemon/daemon-stream-events.ts       |   9 +-
 .../daemon/daemon-stream-keep-tail-drop.ts    |   2 +
 .../daemon/degraded-daemon-pty-provider.ts    |  15 +-
 src/main/daemon/session.test.ts               |  56 ++
 src/main/daemon/session.ts                    |  56 +-
 .../daemon/terminal-host-create-contract.ts   |   7 +-
 src/main/daemon/terminal-host-options.ts      |  27 +
 src/main/daemon/terminal-host.ts              |  37 +-
 src/main/daemon/terminal-modes.ts             |  11 +
 src/main/daemon/terminal-snapshot.ts          |  20 +
 src/main/daemon/types.ts                      |  76 +--
 src/main/ipc/pty.test.ts                      | 107 +++-
 src/main/ipc/pty.ts                           | 169 +++---
 src/main/ipc/ssh.test.ts                      |  17 +-
 .../terminal-startup-color-query-replies.ts   | 141 +----
 src/main/providers/local-pty-provider.test.ts |  41 ++
 src/main/providers/local-pty-provider.ts      |  65 ++-
 src/main/providers/pty-provider-events.ts     |  22 +
 src/main/providers/ssh-pty-provider.test.ts   |  57 ++
 src/main/providers/ssh-pty-provider.ts        |  34 +-
 src/main/providers/types.ts                   |  30 +-
 src/main/runtime/orca-runtime.ts              |  23 +-
 src/main/runtime/rpc/methods/terminal.ts      |  49 +-
 .../ssh-relay-session-data-delivery.test.ts   | 112 ++++
 .../ssh-relay-session-terminal-error.test.ts  |   3 +-
 src/main/ssh/ssh-relay-session.test.ts        |  10 +-
 src/main/ssh/ssh-relay-session.ts             |  27 +-
 src/preload/api-types.ts                      |   1 +
 src/preload/index.ts                          |   2 +
 src/relay/pty-handler.test.ts                 |  67 +++
 src/relay/pty-handler.ts                      | 134 ++++-
 .../terminal-pane/pty-connection.ts           |   1 +
 .../terminal-pane/pty-dispatcher.ts           |   6 +
 ...runtime-terminal-frame-drop-resync.test.ts |  47 +-
 .../remote-runtime-terminal-multiplexer.ts    |  46 +-
 src/shared/pty-startup-ingress-intent.ts      |  52 ++
 src/shared/pty-startup-ingress.test.ts        | 158 ++++++
 src/shared/pty-startup-ingress.ts             | 340 ++++++++++++
 src/shared/terminal-stream-protocol.ts        |   6 +-
 51 files changed, 2415 insertions(+), 497 deletions(-)
 create mode 100644 docs/reference/plans/2026-07-19-windows-conpty-startup-query-and-focus-authority.md
 create mode 100644 src/main/daemon/daemon-protocol-version.ts
 create mode 100644 src/main/daemon/daemon-stream-data-entry.ts
 create mode 100644 src/main/daemon/terminal-host-options.ts
 create mode 100644 src/main/daemon/terminal-modes.ts
 create mode 100644 src/main/daemon/terminal-snapshot.ts
 create mode 100644 src/main/providers/pty-provider-events.ts
 create mode 100644 src/main/ssh/ssh-relay-session-data-delivery.test.ts
 create mode 100644 src/shared/pty-startup-ingress-intent.ts
 create mode 100644 src/shared/pty-startup-ingress.test.ts
 create mode 100644 src/shared/pty-startup-ingress.ts

diff --git a/config/scripts/daemon-boot-smoke.mjs b/config/scripts/daemon-boot-smoke.mjs
index dc593b650b2..4ed155e8c5f 100644
--- a/config/scripts/daemon-boot-smoke.mjs
+++ b/config/scripts/daemon-boot-smoke.mjs
@@ -36,10 +36,11 @@ function log(message) {
 // Why: the daemon rejects a hello whose protocol version differs, so read the
 // current version from source rather than hardcoding a number that can drift.
 function readProtocolVersion() {
-  const source = readFileSync(join(projectDir, 'src/main/daemon/types.ts'), 'utf8')
+  const protocolSourcePath = 'src/main/daemon/daemon-protocol-version.ts'
+  const source = readFileSync(join(projectDir, protocolSourcePath), 'utf8')
   const match = source.match(/PROTOCOL_VERSION\s*=\s*(\d+)/)
   if (!match) {
-    throw new Error('could not read PROTOCOL_VERSION from src/main/daemon/types.ts')
+    throw new Error(`could not read PROTOCOL_VERSION from ${protocolSourcePath}`)
   }
   return Number(match[1])
 }
diff --git a/config/scripts/windows-daemon-workspace-close-repro.mjs b/config/scripts/windows-daemon-workspace-close-repro.mjs
index 974e865722d..1385ffc17d2 100644
--- a/config/scripts/windows-daemon-workspace-close-repro.mjs
+++ b/config/scripts/windows-daemon-workspace-close-repro.mjs
@@ -22,7 +22,10 @@ function log(message) {
 }
 
 function readProtocolVersion() {
-  const source = readFileSync(join(projectDir, 'src/main/daemon/types.ts'), 'utf8')
+  const source = readFileSync(
+    join(projectDir, 'src/main/daemon/daemon-protocol-version.ts'),
+    'utf8'
+  )
   const match = source.match(/PROTOCOL_VERSION\s*=\s*(\d+)/)
   if (!match) {
     throw new Error('Could not read the daemon protocol version')
diff --git a/docs/reference/plans/2026-07-19-windows-conpty-startup-query-and-focus-authority.md b/docs/reference/plans/2026-07-19-windows-conpty-startup-query-and-focus-authority.md
new file mode 100644
index 00000000000..1a0c9922a35
--- /dev/null
+++ b/docs/reference/plans/2026-07-19-windows-conpty-startup-query-and-focus-authority.md
@@ -0,0 +1,523 @@
+# Windows ConPTY Startup Query and Focus Authority Design
+
+Date: 2026-07-19
+
+Status: Final decision; implementation pending
+
+## Problem
+
+On native Windows ConPTY sessions, a new agent can sometimes show terminal protocol bytes as user
+text:
+
+```text
+]10;rgb:2e2e/3434/3434\]11;rgb:ffff/ffff/ffff\
+```
+
+An independent symptom can prefix user input with `[I`, the printable tail of the standard terminal
+focus-in report `CSI I`.
+
+The OSC text is an Orca-generated reply to the agent's OSC 10/11 foreground/background query. The
+agent can issue that query before a daemon-backed `spawn()` resolves to the renderer, and waits only
+about 100 ms for the answer. Orca therefore has a short-lived main-side startup responder in
+addition to the normal renderer/model query authorities. On affected ConPTY timing, the reply sent
+to the PTY is returned as cooked output with its ESC bytes removed. The current ingestion order
+records that cooked echo in the authoritative runtime model before any renderer-bound filtering.
+
+The focus symptom must not be treated as the same bug without evidence. ConPTY deliberately emits
+DECSET 1004 (focus reporting) and DECSET 9001 (Win32 input mode) at startup. A direct native
+PowerShell ConPTY capture consistently produced the bootstrap pair, while an injected `CSI I` was
+consumed as a focus event and did not render as `[I`. The bootstrap is valid transport protocol;
+the failure requires an additional agent, timing, input-mode, or replay condition.
+
+## Root Cause
+
+The startup OSC responder currently runs in Electron main only after runtime ingestion
+([`pty.ts`](../../../src/main/ipc/pty.ts)). `LocalPtyProvider` calls the runtime before its public
+data listeners ([`local-pty-provider.ts`](../../../src/main/providers/local-pty-provider.ts)), while
+daemon `Session` advances sequence state, writes its emulator, persists pending output, and fans out
+data before Electron main receives it ([`session.ts`](../../../src/main/daemon/session.ts)). A
+renderer-only filter can therefore hide the symptom without removing it from the authoritative
+model, daemon history, snapshots, or remote delivery.
+
+The corrupted echo is timing-dependent but its ordering failure is deterministic: any sanitizer
+downstream of an authoritative consumer is too late. The independent `[I` symptom has not yet met
+that evidentiary bar, so this design fixes the proven OSC path and adds the real focus-path harness
+without pre-approving a speculative focus workaround.
+
+## Data Flow
+
+```text
+node-pty / remote relay PTY
+  -> shell-ready marker scan
+  -> source-owned serialized ingress transaction
+       -> consume an early OSC query and write one canonical reply
+       -> match or losslessly release the measured native-Windows echo projection
+  -> authoritative emulator + persistence/history
+  -> runtime side effects and mobile/remote stream
+  -> renderer delivery or hidden-drop decision
+  -> live terminal / snapshot restore
+```
+
+Raw sequence spans travel beside cleaned strings through every downstream hop. Empty transformed
+spans advance sequence and flow-control state without writing bytes into an emulator or view.
+
+## Rejected Prototype
+
+The current working-tree prototype is not the implementation of this design:
+
+- It removes ConPTY's leading `?1004h` in the renderer. This changes valid native-console focus
+  semantics for every Windows PTY, including programs unrelated to agents.
+- It filters OSC echo text only after runtime/model ingestion. The live pane can look clean while a
+  hidden restore, reconnect, mobile view, or CLI snapshot still contains the garbage.
+- Its echo state activates only after both color slots are answered. An echo of the first response
+  can escape if it arrives before the second query.
+- Its partial-match buffer can be lost on timeout, and its substring search can remove a later
+  legitimate string that happens to equal a reply.
+
+Implementation starts by removing the prototype's bootstrap output filter and renderer-only cooked
+echo filtering. Existing unrelated Windows focus-idle safeguards remain.
+
+## Existing Contracts Preserved
+
+This design extends, rather than replaces:
+
+- [`terminal-model-view-contract.md`](../terminal-model-view-contract.md), especially singular query
+  authority, authoritative model restore, and raw sequence ordering;
+- [`terminal-query-authority.md`](../terminal-query-authority.md), especially delivered-versus-
+  hidden-dropped ownership and replay silence;
+- [`terminal-side-effect-authority.md`](../terminal-side-effect-authority.md), especially parsing PTY
+  bytes once in main before renderer delivery.
+
+The startup responder is a bounded exception needed before normal delivered/dropped ownership can be
+established. It must join the same ingestion decision, not operate as an unrelated renderer scrub.
+
+## Decision 1: Source-Owned PTY Ingress Transaction
+
+Sanitization must run on the host that owns the PTY, before that host mutates any authoritative
+model or persistence. Electron main is too late for daemon sessions: `Session` has already advanced
+its sequence, written its emulator, recorded pending output, and broadcast the data before main's
+provider callback runs.
+
+The transaction therefore has three installations of the same shared state machine:
+
+- in `LocalPtyProvider`, before its configured runtime callback and data listeners;
+- in daemon `Session`, before `outputSequence`, emulator writes, pending/checkpoint records, and
+  attached-client fanout;
+- in relay `PtyHandler`, before relay replay/history buffering and `pty.data` fanout. Main's
+  `SshPtyProvider` is only an RPC proxy and never sanitizes relay output.
+
+Electron main receives already-classified daemon data. A remote-runtime desktop client does not
+reinterpret the stream; the remote Orca host owns its transaction. WSL sessions follow their actual
+provider owner but never enable the native-Windows compatibility projection.
+
+Fresh-session creation carries startup-transaction intent atomically. Daemon `createOrAttach`
+receives the recognized-agent intent, execution-host kind, deadline, and validated renderer-pushed
+color attributes. It first decides fresh versus reattach; only a fresh result constructs the
+transaction before releasing the subprocess's already-buffered early output. A reattach discards
+the intent without arming state. Cancellation, spawn failure, and teardown clear intent before any
+PTY id can be reused.
+
+Local creation installs the transaction before subscribing to node-pty output. Relay `pty.spawn`
+carries the same fresh-session intent and installs it before releasing relay PTY output; relay
+`pty.attach` never accepts it. If any owner cannot establish this ordering, the early responder is
+not armed and normal query authority handles the query.
+
+Increment `DAEMON_PROTOCOL_VERSION` for the new create/wire shape and add a named numeric-threshold
+predicate in the daemon adapter/router. Current exact-version hello behavior remains; supported
+legacy versions route through their existing adapters and fail the predicate. The SSH relay gets a
+separate versioned spawn/data capability because daemon protocol support says nothing about relay
+support.
+
+An old daemon or relay keeps the legacy behavior and is never treated as having sanitized snapshots
+or history. Main must not apply a second best-effort scrub to legacy output. New sessions receive
+the invariant only after the owning daemon/relay is upgraded or restarted; an already-attached
+legacy session remains explicitly outside it.
+
+### Composition with shell-ready preprocessing
+
+The ingress sequence domain begins after the existing shell-ready scanner. That scanner may hold
+transport bytes and removes its private ready marker; marker bytes have never belonged to terminal
+model or delivery sequence space and continue not to count. Its released non-marker bytes enter the
+new ingress transaction in original order.
+
+Snapshot and teardown barriers drain in pipeline order: the shell-ready scanner first releases its
+non-marker buffer, then the ingress transaction resolves or abandons its candidate, then the model,
+persistence, and views observe the resulting emissions. No later stage may introduce an unmetered
+string transform.
+
+### Raw sequence and emission contract
+
+The state machine accepts source chunks with an explicit raw half-open range and returns zero or
+more ordered emissions:
+
+```ts
+type PtyIngressSourceChunk = {
+  data: string
+  rawStartSeq: number
+  rawEndSeq: number
+}
+
+type PtyIngressEmission = {
+  data: string
+  rawStartSeq: number
+  rawEndSeq: number
+  transformed: boolean
+}
+```
+
+The raw range is the post-shell-ready ingress sequence domain and remains contiguous even when
+`data` is shorter after sanitization. The ordered emissions partition accepted source ranges without
+overlap. Producer flow-control acknowledgement follows those emitted raw spans and is counted once
+from `rawEndSeq - rawStartSeq`, never from emitted string length. A held prefix delays its ACK; the
+buffer is strictly bounded and the serialized queue cannot acknowledge later output ahead of it.
+
+The ingress raw high-water advances when a source chunk is accepted. Model-applied and
+view-delivered high-waters advance only through ordered emissions, including empty transformed
+emissions that consume a raw range. Runtime/mobile listener metadata carries
+`rawLength = rawEndSeq - rawStartSeq`, not `data.length`. A restore that overlaps a transformed span
+cannot slice cleaned text by raw offset and must request a fresh authoritative snapshot, matching
+the existing `rawLength !== data.length` safety rule.
+
+This metadata is end-to-end, not local to the state machine. Implementation changes the complete
+path:
+
+1. daemon `Session` or relay `PtyHandler` emission callback;
+2. daemon/relay batching, coalescing, splitting, and wire notification;
+3. daemon adapter or `SshPtyProvider` decode;
+4. `OrcaRuntimeService` model and runtime/mobile listeners;
+5. main renderer batching, pending/drop accounting, and preload payload;
+6. renderer reconciliation and remote-runtime binary/live frame decoding.
+
+The wire representation carries `data`, `seq = rawEndSeq`, `rawLength`, and `transformed`. A
+span-only emission has empty `data` but non-zero `rawLength`; no layer may drop it before advancing
+its high-water and producer ACK. It is not written to an emulator or xterm. Coalescing is permitted
+only for contiguous spans and sums raw lengths independently of string lengths. A transformed
+emission is indivisible because there is no byte-for-byte raw-to-clean offset; splitters must flush
+it as its own frame or request snapshot reconciliation instead of slicing it.
+
+If a snapshot is requested while a partial candidate is held, the transaction first abandons that
+candidate and releases its bytes unchanged as an ordered emission. The authoritative emulator and
+snapshot sequence therefore describe the same raw high-water.
+
+### Serialization and teardown
+
+Each PTY has a non-reentrant serialized ingress queue. A provider write may synchronously produce a
+nested callback, but that callback is appended after the current source chunk rather than delivered
+ahead of its remaining bytes. Timeout releases and snapshot barriers enter the same queue.
+
+On exit, the queue releases all buffered bytes, applies those emissions to the authoritative model
+and persistence, and fans them out before `onPtyExit`, `pty:exit`, or PTY state cleanup. Relay
+disposal must flush both ingress prefixes and its existing pending output batches before clearing
+them or killing PTYs, matching the natural-exit flush-before-`pty.exit` order. No drain may recreate
+state after teardown. Ordinary chunks pass through as one unchanged emission.
+
+## Decision 2: Startup OSC Queries Are Consumed Authoritatively
+
+The early OSC 10/11 responder remains because removing it would regress daemon-hosted agent startup
+and the agent's short color-query timeout. Its implementation moves into the source-owned ingress
+transaction.
+
+When registered for an agent spawn, it:
+
+1. recognizes exact OSC 10/11 query grammar across provider chunks;
+2. builds replies from validated renderer-pushed foreground/background attributes;
+3. emits the canonical ST-terminated, 16-bit-channel reply used by renderer/model query authority,
+   regardless of whether the query ended with BEL or ST;
+4. records each reply transaction before writing it to the provider;
+5. consumes the answered query from the authoritative model and view emissions so neither the
+   hidden model nor a delivered renderer can answer it a second time;
+6. begins echo recognition as soon as each individual reply is written.
+
+If attributes or a provider are unavailable, the query is not consumed. It passes through unchanged
+to normal query authority. A reattach never registers startup response state, matching current
+behavior.
+
+### Exact authority transfer
+
+Startup query interception opens only for a fresh session whose atomic creation installed the
+transaction before buffered output release. It closes at the first of:
+
+- both OSC 10 and OSC 11 slots have been answered;
+- the startup deadline expires;
+- main sends an ordered authority-close control after either the consuming-view handshake or the
+  hidden-runtime ownership mark is established;
+- the spawn fails, is cancelled, reattaches, or exits.
+
+Closing query interception does not discard already-written reply candidates. Echo recognition has
+its own bounded lifetime and may finish or drain after normal authority takes over. A close and a
+provider callback are ordered by the source owner's per-PTY ingress queue. Transport attachment to
+a daemon/relay client is not a consuming-view signal. Main sends the close over a versioned control
+method, and the source owner acknowledges the applied ingress sequence. Queries before that ordered
+boundary are either consumed at source or removed from emissions; queries after it pass unchanged
+to the normal delivered/hidden decision. Each query therefore belongs to exactly one authority.
+
+The regular authority rules continue after the bounded startup window:
+
+- delivered live bytes are answered by the live view;
+- hidden-dropped live bytes are answered by the runtime model;
+- replayed, seeded, and snapshot bytes are answered by nobody;
+- the daemon's persistence emulator never writes replies.
+
+Implementation must amend `terminal-model-view-contract.md` and `terminal-query-authority.md` to
+name this source-owner startup authority, its opening/closing events, and its no-replay rule. It is a
+real third responder class, not an undocumented exception.
+
+## Decision 3: Matched Echo Suppression Is Lossless and Pre-Model
+
+Only native Windows ConPTY agent spawns that pass the deterministic provider harness enable a
+compatibility projection for replies written by the startup transaction. WSL and POSIX SSH PTYs do
+not. A remote-runtime PTY can enable it only on its owning Windows host under the same evidence and
+capability gate.
+
+The harness records the exact projection ConPTY returns for the canonical ST reply, including its
+chunking and any console transformation. The implementation must not assume that the projection is
+always merely "remove ESC", and BEL or other reply forms are not added without separate evidence.
+For every written reply, the transaction records that exact expected projection. Recognition is:
+
+- FIFO in reply-write order;
+- anchored at the next possible output position, not an unbounded substring search;
+- active immediately for each reply instead of waiting for both color slots;
+- bounded by the startup deadline and maximum reply length;
+- streaming across chunk boundaries.
+
+If incoming bytes diverge from the expected projection, all buffered bytes are released unchanged
+and that candidate is abandoned. If the deadline expires or the PTY is cleared while a prefix is
+buffered, the prefix is released through the serialized ingestion queue; it is never discarded. A
+match advances the raw span but emits no bytes to the model, persistence, or views.
+
+Projection matching cannot prove provenance. An application can print the same projected text at
+the candidate position, causing a false-positive removal while the later real echo remains visible.
+This is the central drawback of the workaround. It is accepted only if the real provider harness
+shows a stable, immediate projection inside the narrow registered-agent startup window; otherwise
+Orca disables the projection and keeps the visible output rather than risking deletion.
+
+When the projection is enabled, the exact-collision behavior is explicit: the first identical
+anchored candidate is removed and a later real echo is allowed through. The test fixture must assert
+that result. This accepts a narrowly bounded false-positive risk instead of pretending provenance
+is knowable; the release gate must document the observed timing window and justify that tradeoff.
+Unknown, delayed, or interleaved transformations pass through visibly.
+
+## Decision 4: Preserve ConPTY Focus Protocol
+
+Orca must deliver the ConPTY bootstrap `?1004h`/`?9001h` to live terminal emulators unchanged. It
+must not remove, reorder, or fabricate transport bootstrap modes.
+
+The `[I` investigation gets a deterministic harness before a behavior change. The harness must
+exercise the actual renderer focus callback and provider write path, not only inject `CSI I`
+directly into node-pty. It records:
+
+- raw provider output and its order;
+- whether the focus report came from live ConPTY bootstrap state, an application-owned DECSET 1004,
+  or replayed snapshot state;
+- the exact bytes written to the provider;
+- the exact bytes returned by the provider and stored in the model;
+- agent lifecycle state when the report was emitted.
+
+The implementation gate is strict:
+
+- If stale snapshot modes cause the report, fix snapshot rehydration. Transport bootstrap focus mode
+  is not persisted as application ownership.
+- If a live agent receives transport focus before it owns terminal focus reporting, record that
+  evidence without shipping a suppression heuristic from this document.
+- If provider input/output transformation corrupts a correctly owned focus report, fix or sanitize
+  that transformation at the same pre-model ingress boundary used for OSC replies.
+
+No global `?1004h` filter ships under any outcome.
+
+If the harness proves a focus-ownership race, a follow-up design is required before implementation.
+That design must define the output-to-input ownership signal, distinguish xterm focus events from
+identical typed/pasted/programmatic bytes, specify startup transitions and deadlines, define any
+snapshot/wire metadata, and cover the separate explicit reattach-focus write path. This document
+does not pre-approve an ownership state machine whose input provenance cannot yet be represented.
+
+## Snapshot and Replay Rules
+
+Interactive modes in a snapshot are capabilities of the live application, not proof that a new
+view should emit input immediately.
+
+- Cold restore into a fresh shell keeps the existing full mode reset.
+- Reattach to a live agent may rehydrate application-owned focus mode, but never transport-only
+  bootstrap ownership.
+- Snapshot serialization/replay must not mutate live ownership trackers.
+- A snapshot containing an OSC query or an old Orca reply never produces a provider write.
+- Model and renderer snapshots must both be free of matched cooked reply projections.
+
+Any future focus ownership metadata must be explicit; it cannot be inferred from serialized
+`?1004h` text.
+
+## Failure Policy
+
+Safety is asymmetric:
+
+- This design does not intentionally suppress a focus notification; evidence of a focus-ownership
+  race triggers a follow-up design instead.
+- Passing through an unrecognized OSC echo is safer than deleting output that may belong to the
+  application.
+- Missing a startup color reply falls back to the existing renderer/model authority. Duplicate
+  replies are forbidden.
+- Losing buffered output on timeout or teardown is forbidden.
+
+## Cross-Platform and Remote Scope
+
+- Native Windows local and daemon ConPTY: startup response plus evidence-gated echo compatibility
+  path; focus investigation only until a proven root cause has its own complete design.
+- WSL: normal Linux terminal semantics; no ConPTY echo or focus workaround.
+- SSH: the same ingress/query ownership ordering, but no native Windows echo projection unless the
+  remote host protocol later supplies explicit equivalent evidence.
+- Remote runtime: the remote Orca host owns ingestion and must implement the same contract there;
+  desktop local main does not reinterpret its stream.
+- Mobile/web views: consume the sanitized authoritative model stream and retain exactly-one query
+  response authority through the existing terminal-driver election.
+
+## Edge Cases
+
+- A query or echo split at any byte boundary, including OSC ST split across chunks.
+- The first reply echo arriving before the second color query.
+- Unrelated output, an exact application-text collision, or a partial match before the real echo.
+- Timeout, snapshot, detach, process exit, daemon shutdown, or relay disposal while bytes are held.
+- A provider write causing a synchronous nested output callback.
+- Fresh spawn versus reattach, cancellation, PTY-id reuse, and an authority-close control racing
+  with output.
+- BEL-terminated queries still receiving the canonical ST reply.
+- Empty transformed spans crossing coalescing, splitting, ACK, mobile, and remote-runtime layers.
+- Old daemon/relay protocol versions and sessions that survive an application upgrade.
+- WSL or POSIX SSH running from a Windows desktop without inheriting local ConPTY workarounds.
+- Focus gained through normal terminal input versus the separate explicit reattach-focus write path.
+
+## Test Plan
+
+### Deterministic provider harness
+
+- Capture the native ConPTY bootstrap across natural and forced chunk boundaries.
+- Reproduce the OSC reply echo with the real provider and an agent query fixture.
+- Exercise BEL and ST queries and assert the same canonical ST reply, plus separate OSC 10/11
+  queries and combined OSC 10 `?;?`.
+- Force the first reply echo before the second query.
+- Split every byte boundary in query and echo fixtures.
+- Print the expected projection immediately before the real echo and assert that the first
+  identical candidate is removed while the later echo passes through.
+- Exercise focus gain/loss through the actual xterm focus path.
+
+### Ingress integration
+
+- Assert local runtime ingestion and daemon emulator/pending/checkpoint persistence receive
+  classified data before storing it.
+- Assert renderer and mobile delivery receive the same visible output.
+- Assert raw start/end spans advance by original provider length, producer ACK contribution is
+  counted exactly once, and mobile/runtime metadata reports the raw span rather than string length.
+- Assert a partial candidate is released unchanged on mismatch, timeout, snapshot barrier, move,
+  and teardown, including a prefix held from an earlier callback.
+- Assert re-entrant provider callbacks remain ordered behind the source chunk that caused the
+  write.
+- Assert restore overlap across a transformed or delayed span requests a fresh snapshot rather
+  than slicing cleaned text.
+- Assert `LocalPtyProvider`, daemon `Session`, and relay `PtyHandler` install the source-side seam;
+  assert `SshPtyProvider` does not reinterpret relay data.
+- Assert WSL, SSH, and remote-runtime streams do not enable the native-Windows projection.
+- Assert a capable daemon sanitizes live output, snapshots, pending records, checkpoints, and cold
+  restore; assert capable relay replay/history has the same property. Assert old daemon and relay
+  versions are detected and never represented as sanitized.
+
+### Authority and restore
+
+- Assert an early-consumed query is answered once by its source owner and never by renderer or
+  hidden model.
+- Assert normal delivered/dropped query authority resumes after startup state clears.
+- Assert the main snapshot, renderer snapshot, hidden reveal, reconnect, and mobile subscription do
+  not contain cooked OSC text.
+- Assert replay never sends OSC or focus replies.
+- Assert ordinary native console focus behavior remains enabled.
+- Assert the focus harness captures both terminal `onData` and explicit reattach-focus writes. Any
+  later ownership implementation defines its tests in the required follow-up design.
+
+### End-to-end acceptance
+
+On native Windows, repeatedly create, hide, reveal, and reconnect new and resumed agent sessions.
+Before typing, neither live output nor any restore path may contain `]10;rgb`/`]11;rgb`. Repeat the
+focus/blur scenarios to classify `[I`; if it reproduces through an ownership race, this work stops
+at the follow-up-design gate rather than claiming the symptom fixed. Application-owned focus
+behavior must still move the TUI caret correctly after focus and reattach. Repeat with a plain
+PowerShell terminal and a native focus-event consumer to prove no global regression.
+
+Run renderer and main PTY suites, runtime snapshot/query suites, node/web typechecks, lint,
+formatting, max-lines ratchet, reliability gates, and Electron validation. SSH ingestion changes also
+require the repository's SSH end-to-end procedure.
+
+## UI Quality Bar
+
+This is not a layout, styling, or copy change. Existing terminal rendering and focus behavior must
+look unchanged except that matched protocol garbage is absent. A passing terminal screenshot has a
+clean prompt, no clipped or duplicated startup output, no restore flash, and the existing cursor and
+focus presentation.
+
+## Review Screenshots
+
+1. A fresh native-Windows agent prompt after startup, with no OSC reply text.
+2. The same session after hide/reveal restore, still clean and without duplicated output.
+3. The session after focus, blur, and reconnect, showing the focus-harness outcome and prompt state.
+4. A plain native PowerShell terminal after focus/blur, showing unchanged adjacent behavior.
+
+## Rollout
+
+1. **Correct seam and rollback.** Remove the prototype filters. Add the shared serialized ingress
+   state machine, explicit raw-span emissions, and separate ACK accounting after shell-ready
+   preprocessing. Install pass-through mode in `LocalPtyProvider`, daemon `Session`, and relay
+   `PtyHandler` before their models, persistence/replay, and fanout.
+2. **Protocol and authority contract.** Bump the daemon protocol, add relay capability/version gates,
+   carry atomic fresh-spawn intent, define legacy fallback, and amend the canonical model/query
+   authority documents with exact transfer events.
+3. **Startup transaction.** Move OSC startup recognition/reply into source ingress, retain canonical
+   ST replies, consume answered queries for model and views, and retain raw sequence accounting.
+4. **Windows compatibility projection.** Gate the measured projection on provider evidence; add FIFO
+   anchored recognition, serialized re-entrant delivery, lossless drains, false-positive coverage,
+   and authoritative daemon/model/snapshot tests.
+5. **Focus evidence.** Land the real focus-path harness. If it proves a focus-ownership race, stop
+   for the required follow-up design; a direct snapshot or provider-transformation bug may be fixed
+   only with a failing regression test that selects that branch.
+6. **Electron and SSH gates.** Validate visible, hidden, restored, mobile-owned, native console, WSL,
+   and SSH scenarios before removing the old startup implementation.
+
+Each slice must keep query authority singular. The compatibility projection does not ship without a
+model-snapshot assertion, and no focus behavior change ships before the deterministic focus harness
+fails on the old behavior and passes on the new behavior.
+
+## Lightweight Eng Review
+
+- Scope: limited to the proven OSC startup corruption plus deterministic focus evidence. Global
+  focus filtering and an unproven ownership state machine remain out of scope.
+- Architecture/data flow: classification belongs at each PTY source owner after shell-ready
+  preprocessing and before every authoritative model, persistence, replay, or delivery consumer.
+- Failure modes covered: partial/mismatched projections, false-positive collision, nested writes,
+  authority races, snapshot and teardown drains, protocol-version skew, reattach, and host
+  isolation.
+- Test coverage required: byte-boundary unit tests for the shared transaction; local, daemon, relay,
+  runtime/mobile, restore, and legacy-protocol integration tests; real native-Windows provider and
+  renderer-focus harnesses; Electron and SSH end-to-end validation.
+- Performance/blast radius: ordinary output is a pass-through emission. Buffering is bounded by one
+  startup reply candidate and its deadline. Protocol and sequence metadata touch every delivery
+  path, so existing high-throughput, ACK, hidden-drop, and reconnect tests are mandatory.
+- UI quality bar: terminal layout and styling are unchanged; only matched startup garbage
+  disappears, without cursor/focus regressions or restore flashes.
+- Required review screenshots: the four terminal states in `Review Screenshots`.
+- Residual risks: the native projection may be too unstable to enable; exact projected application
+  output can collide; `[I` may require a separately reviewed focus-ownership design.
+
+## Non-Goals
+
+- Replacing xterm's general query parser.
+- Filtering arbitrary escape-looking terminal output.
+- Disabling ConPTY focus or Win32 input mode globally.
+- Changing WSL, SSH, or remote-runtime terminal semantics to imitate local Windows.
+- Solving unrelated MCP startup warnings reported beside the terminal garbage.
+
+## Final Invariants
+
+1. Provider bytes are classified once before model ingestion and view delivery.
+2. A live query has exactly one responder; replay has none.
+3. Source-owner persistence, runtime/model state, and every view agree on removal of a matched
+   startup-reply projection.
+4. Raw provider sequence accounting survives sanitization.
+5. Buffered unmatched output is always released; the sanitizer cannot silently lose user data.
+6. ConPTY bootstrap modes reach live emulators unchanged.
+7. No focus suppression ships from this design; a proven ownership race requires a follow-up design.
+8. PTY teardown clears all startup-transaction buffers and focus-harness measurement state.
diff --git a/src/main/daemon/daemon-protocol-version.ts b/src/main/daemon/daemon-protocol-version.ts
new file mode 100644
index 00000000000..119a3bb14d7
--- /dev/null
+++ b/src/main/daemon/daemon-protocol-version.ts
@@ -0,0 +1,12 @@
+// Why: daemons survive app updates, so wire behavior must be version-gated.
+export const PROTOCOL_VERSION = 24
+export const PTY_STARTUP_INGRESS_PROTOCOL_VERSION = 24
+export const GIT_CREDENTIAL_GUARD_HOST_PROTOCOL_VERSION = 22
+export const CLEAN_DISCONNECT_PROTOCOL_VERSION = 24
+export const PREVIOUS_DAEMON_PROTOCOL_VERSIONS = [
+  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23
+] as const
+
+export function supportsPtyStartupIngress(protocolVersion: number): boolean {
+  return protocolVersion >= PTY_STARTUP_INGRESS_PROTOCOL_VERSION
+}
diff --git a/src/main/daemon/daemon-pty-adapter.test.ts b/src/main/daemon/daemon-pty-adapter.test.ts
index 14243aa15eb..707d2800e15 100644
--- a/src/main/daemon/daemon-pty-adapter.test.ts
+++ b/src/main/daemon/daemon-pty-adapter.test.ts
@@ -144,6 +144,72 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       expect(result.providerSequence).toEqual({ value: 0, generation: 'reset' })
     })
 
+    it('carries classified startup spans from the daemon source to the adapter', async () => {
+      const onData = vi.fn()
+      adapter.onData(onData)
+      const { id } = await adapter.spawn({
+        cols: 80,
+        rows: 24,
+        startupIngress: {
+          colors: { foreground: '#2e3434', background: '#ffffff' },
+          deadlineMs: 5_000,
+          ...(process.platform === 'win32'
+            ? { echoProjection: 'windows-conpty-esc-stripped' as const }
+            : {})
+        }
+      })
+      const query = '\x1b]10;?\x07'
+      lastSubprocess._simulateData(query)
+      lastSubprocess._simulateData('prompt')
+
+      await waitFor(() => onData.mock.calls.length >= 2)
+
+      expect(lastSubprocess.write).toHaveBeenCalledWith('\x1b]10;rgb:2e2e/3434/3434\x1b\\')
+      expect(onData).toHaveBeenCalledWith({
+        id,
+        data: '',
+        sequenceChars: query.length,
+        seq: query.length,
+        transformed: true
+      })
+      expect(onData).toHaveBeenCalledWith({ id, data: 'prompt' })
+      await expect(adapter.getBufferSnapshot(id)).resolves.toMatchObject({
+        data: expect.not.stringContaining(']10;rgb')
+      })
+    })
+
+    it('omits startup intent and close control for the preserved v23 protocol', async () => {
+      const ensureConnectedSpy = vi
+        .spyOn(DaemonClient.prototype, 'ensureConnected')
+        .mockResolvedValue()
+      const requestSpy = vi.spyOn(DaemonClient.prototype, 'request').mockResolvedValue({
+        isNew: true,
+        pid: null,
+        shellState: 'unsupported',
+        snapshot: null
+      } as never)
+      const legacy = new DaemonPtyAdapter({ socketPath, tokenPath, protocolVersion: 23 })
+      try {
+        await legacy.spawn({
+          sessionId: 'legacy-session',
+          cols: 80,
+          rows: 24,
+          startupIngress: {
+            colors: { foreground: '#2e3434', background: '#ffffff' },
+            deadlineMs: 5_000
+          }
+        })
+        const createPayload = requestSpy.mock.calls.find(([type]) => type === 'createOrAttach')?.[1]
+        expect(createPayload).not.toHaveProperty('startupIngress')
+        await expect(legacy.closeStartupQueryAuthority('legacy-session')).resolves.toBe(0)
+        expect(requestSpy).not.toHaveBeenCalledWith('closeStartupQueryAuthority', expect.anything())
+      } finally {
+        legacy.dispose()
+        requestSpy.mockRestore()
+        ensureConnectedSpy.mockRestore()
+      }
+    })
+
     it('uses worktreeId as session prefix when provided', async () => {
       const result = await adapter.spawn({ cols: 80, rows: 24, worktreeId: 'wt-1' })
       expect(result.id).toContain('wt-1')
diff --git a/src/main/daemon/daemon-pty-adapter.ts b/src/main/daemon/daemon-pty-adapter.ts
index 0fe8ecc2a4d..81e91f16c63 100644
--- a/src/main/daemon/daemon-pty-adapter.ts
+++ b/src/main/daemon/daemon-pty-adapter.ts
@@ -14,6 +14,7 @@ import {
   CLEAN_DISCONNECT_PROTOCOL_VERSION,
   GIT_CREDENTIAL_GUARD_HOST_PROTOCOL_VERSION,
   PROTOCOL_VERSION,
+  supportsPtyStartupIngress,
   type CreateOrAttachResult,
   type DaemonEvent,
   type GetSnapshotResult,
@@ -105,6 +106,8 @@ export class DaemonPtyAdapter implements IPtyProvider {
     id: string
     data: string
     sequenceChars?: number
+    transformed?: boolean
+    seq?: number
   }) => void)[] = []
   private exitListeners: ((payload: { id: string; code: number }) => void)[] = []
   private backgroundStreamListeners: ((payload: PtyBackgroundStreamEvent) => void)[] = []
@@ -142,6 +145,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
   // must never see them, so gating makes them silent no-ops there.
   private supportsProducerFlowControl: boolean
   private supportsAuthoritativeBufferSnapshots: boolean
+  private supportsStartupIngress: boolean
   private pausedProducerSessionIds = new Set<string>()
   // Why tracked here: the daemon's background set (keep-tail stream thinning
   // + transient-fact scan authority) dies with the daemon process/socket;
@@ -185,6 +189,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.supportsIncrementalCheckpoints = this.protocolVersion >= 13
     this.supportsProducerFlowControl = this.protocolVersion >= 19
     this.supportsAuthoritativeBufferSnapshots = this.protocolVersion >= 20
+    this.supportsStartupIngress = supportsPtyStartupIngress(this.protocolVersion)
     this.client.onDisconnected(() => {
       for (const id of this.pausedProducerSessionIds) {
         this.producerResumesOwedOnReconnect.add(id)
@@ -299,7 +304,10 @@ export class DaemonPtyAdapter implements IPtyProvider {
         terminalWindowsPowerShellImplementation: opts.terminalWindowsPowerShellImplementation,
         shellReadySupported,
         ...(shellReadyTimeoutMs !== undefined ? { shellReadyTimeoutMs } : {}),
-        ...(historySeed ? { historySeed } : {})
+        ...(historySeed ? { historySeed } : {}),
+        ...(this.supportsStartupIngress && opts.startupIngress
+          ? { startupIngress: opts.startupIngress }
+          : {})
       })
 
     let scrollback = restoreInfo ? getRecoveredHistorySeed(restoreInfo) : null
@@ -925,7 +933,13 @@ export class DaemonPtyAdapter implements IPtyProvider {
   }
 
   onData(
-    callback: (payload: { id: string; data: string; sequenceChars?: number }) => void
+    callback: (payload: {
+      id: string
+      data: string
+      sequenceChars?: number
+      transformed?: boolean
+      seq?: number
+    }) => void
   ): () => void {
     this.dataListeners.push(callback)
     return () => {
@@ -1455,9 +1469,11 @@ export class DaemonPtyAdapter implements IPtyProvider {
           listener({
             id: event.sessionId,
             data: event.payload.data,
-            ...(event.payload.sequenceChars === undefined
+            ...((event.payload.rawLength ?? event.payload.sequenceChars) === undefined
               ? {}
-              : { sequenceChars: event.payload.sequenceChars })
+              : { sequenceChars: event.payload.rawLength ?? event.payload.sequenceChars }),
+            ...(event.payload.transformed ? { transformed: true } : {}),
+            ...(event.payload.seq === undefined ? {} : { seq: event.payload.seq })
           })
         }
       } else if (event.event === 'sessionBackgroundMarker') {
@@ -1518,6 +1534,16 @@ export class DaemonPtyAdapter implements IPtyProvider {
       }
     })
   }
+
+  async closeStartupQueryAuthority(id: string): Promise<number> {
+    if (!this.supportsStartupIngress) {
+      return 0
+    }
+    const result = await this.client.request<{ appliedSeq: number }>('closeStartupQueryAuthority', {
+      sessionId: id
+    })
+    return result.appliedSeq
+  }
 }
 
 // Why: ENOENT/ECONNREFUSED with syscall 'connect' mean the socket is
diff --git a/src/main/daemon/daemon-pty-router.ts b/src/main/daemon/daemon-pty-router.ts
index f8cad04b43b..a726b4000d9 100644
--- a/src/main/daemon/daemon-pty-router.ts
+++ b/src/main/daemon/daemon-pty-router.ts
@@ -17,6 +17,8 @@ export class DaemonPtyRouter implements IPtyProvider {
     id: string
     data: string
     sequenceChars?: number
+    transformed?: boolean
+    seq?: number
   }) => void)[] = []
   private exitListeners: ((payload: { id: string; code: number }) => void)[] = []
 
@@ -143,6 +145,10 @@ export class DaemonPtyRouter implements IPtyProvider {
     await this.adapterFor(id).clearBuffer(id)
   }
 
+  async closeStartupQueryAuthority(id: string): Promise<number> {
+    return (await this.adapterFor(id).closeStartupQueryAuthority?.(id)) ?? 0
+  }
+
   acknowledgeDataEvent(id: string, charCount: number): void {
     this.adapterFor(id).acknowledgeDataEvent(id, charCount)
   }
@@ -183,7 +189,13 @@ export class DaemonPtyRouter implements IPtyProvider {
   }
 
   onData(
-    callback: (payload: { id: string; data: string; sequenceChars?: number }) => void
+    callback: (payload: {
+      id: string
+      data: string
+      sequenceChars?: number
+      transformed?: boolean
+      seq?: number
+    }) => void
   ): () => void {
     this.dataListeners.push(callback)
     return () => {
diff --git a/src/main/daemon/daemon-server.ts b/src/main/daemon/daemon-server.ts
index 15ec9fecd21..93ee537c126 100644
--- a/src/main/daemon/daemon-server.ts
+++ b/src/main/daemon/daemon-server.ts
@@ -23,6 +23,8 @@ import type { SubprocessHandle } from './session'
 import { checkPtySpawnHealth } from './pty-subprocess'
 import { createNoopDaemonFileLog, type DaemonFileLog } from './daemon-file-log'
 import { isTuiAgent } from '../../shared/tui-agent-config'
+import { parsePtyStartupIngressIntent } from '../../shared/pty-startup-ingress'
+import { isNativeWindowsLocalPtySpawn } from '../runtime/terminal-model-query-authority'
 import { unlinkOwnedDaemonPidFile, unlinkOwnedDaemonTokenFile } from './daemon-spawner'
 import {
   CLEAN_DISCONNECT_PROTOCOL_VERSION,
@@ -707,11 +709,18 @@ export class DaemonServer {
             terminalWindowsPowerShellImplementation: p.terminalWindowsPowerShellImplementation,
             shellReadySupported: p.shellReadySupported,
             historySeed: p.historySeed,
+            startupIngress: parsePtyStartupIngressIntent(p.startupIngress, {
+              allowWindowsEchoProjection: isNativeWindowsLocalPtySpawn({
+                connectionId: null,
+                cwd: p.cwd,
+                shellOverride: p.shellOverride
+              })
+            }),
             ...(p.shellReadyTimeoutMs !== undefined
               ? { shellReadyTimeoutMs: p.shellReadyTimeoutMs }
               : {}),
             streamClient: {
-              onData: (data) => {
+              onData: (data, rawLength = data.length, transformed = false, seq) => {
                 // Scan BEFORE enqueue: the batcher may keep-tail drop this
                 // chunk, but its facts must be captured regardless.
                 this.transientFactRelay.onSessionData(p.sessionId, data)
@@ -722,7 +731,10 @@ export class DaemonServer {
                   performance.now() - lastInputAt <= DaemonServer.INTERACTIVE_OUTPUT_WINDOW_MS
                 this.streamDataBatcher.enqueue(clientId, p.sessionId, data, {
                   flushImmediately: isInteractiveOutput,
-                  flushMaxChars: DaemonServer.INTERACTIVE_OUTPUT_MAX_CHARS
+                  flushMaxChars: DaemonServer.INTERACTIVE_OUTPUT_MAX_CHARS,
+                  rawLength,
+                  transformed,
+                  seq
                 })
               },
               onExit: (code) => {
diff --git a/src/main/daemon/daemon-stream-data-batcher.test.ts b/src/main/daemon/daemon-stream-data-batcher.test.ts
index 32d85ff87b0..12eec59f758 100644
--- a/src/main/daemon/daemon-stream-data-batcher.test.ts
+++ b/src/main/daemon/daemon-stream-data-batcher.test.ts
@@ -77,6 +77,23 @@ describe('DaemonStreamDataBatcher', () => {
     }
   })
 
+  it('preserves transformed span metadata through an immediate flush', () => {
+    const { batcher, streamSocket } = createBatcher()
+
+    batcher.enqueue('client-1', 'session-1', '', {
+      flushImmediately: true,
+      rawLength: 9,
+      seq: 17,
+      transformed: true
+    })
+
+    expect(streamSocket.write).toHaveBeenCalledTimes(1)
+    expect(JSON.parse(String(streamSocket.write.mock.calls[0]?.[0]))).toMatchObject({
+      event: 'data',
+      payload: { data: '', rawLength: 9, seq: 17, sequenceChars: 9, transformed: true }
+    })
+  })
+
   it('keeps large pending output batched even when an interactive redraw follows', () => {
     vi.useFakeTimers()
     try {
diff --git a/src/main/daemon/daemon-stream-data-batcher.ts b/src/main/daemon/daemon-stream-data-batcher.ts
index 84f7465b913..b27c4020217 100644
--- a/src/main/daemon/daemon-stream-data-batcher.ts
+++ b/src/main/daemon/daemon-stream-data-batcher.ts
@@ -13,6 +13,7 @@ import {
   type PendingStreamDataBatch
 } from './daemon-stream-keep-tail-drop'
 import type { DaemonEvent } from './types'
+import { appendDaemonStreamData, type DaemonStreamEnqueueOptions } from './daemon-stream-data-entry'
 
 type StreamDataClient = {
   streamSocket: Socket | null
@@ -59,11 +60,6 @@ const HELD_WRITE_THROUGH_TOTAL_CHARS = 32 * 1024 * 1024
 // sessions × this ≈ tens of KB.
 const SMALL_SESSION_HOLD_BYPASS_CHARS = 4 * 1024
 
-type EnqueueOptions = {
-  flushImmediately?: boolean
-  flushMaxChars?: number
-}
-
 type DaemonStreamDataBatcherOptions = {
   maxLineBytes?: number
   /** Fires after each stream-socket write — the only place backlog grows, so
@@ -97,26 +93,19 @@ export class DaemonStreamDataBatcher {
     this.salvageDroppedData = options.salvageDroppedData ?? (() => '')
   }
 
-  enqueue(clientId: string, sessionId: string, data: string, options: EnqueueOptions = {}): void {
+  enqueue(
+    clientId: string,
+    sessionId: string,
+    data: string,
+    options: DaemonStreamEnqueueOptions = {}
+  ): void {
     const client = this.getClient(clientId)
     if (!client?.streamSocket || client.streamSocket.destroyed) {
       return
     }
 
     const batch = this.getOrCreateBatch(clientId)
-    const last = batch.queue.at(-1)
-    // Never coalesce across a control entry — it marks a position in the
-    // session's byte order.
-    if (last?.sessionId === sessionId && !last.control) {
-      last.data += data
-    } else {
-      batch.queue.push({ sessionId, data })
-    }
-    batch.queuedChars += data.length
-    batch.queuedCharsBySession.set(
-      sessionId,
-      (batch.queuedCharsBySession.get(sessionId) ?? 0) + data.length
-    )
+    appendDaemonStreamData(batch, sessionId, data, options)
 
     if (this.isSessionDroppable(sessionId)) {
       // Keep-tail scales down as more backgrounded sessions queue, bounding
@@ -256,12 +245,16 @@ export class DaemonStreamDataBatcher {
         })
       }
       const end =
-        entry.data.length <= BULK_WRITE_SLICE_CHARS
+        entry.transformed || entry.data.length <= BULK_WRITE_SLICE_CHARS
           ? entry.data.length
           : clampToSafeSplitIndex(entry.data, 0, BULK_WRITE_SLICE_CHARS)
       const slice = entry.data.slice(0, end)
       const entrySequenceChars = entry.sequenceChars ?? entry.data.length
-      const sliceSequenceChars = entrySequenceChars === 0 ? 0 : slice.length
+      const sliceSequenceChars = entry.transformed
+        ? entrySequenceChars
+        : entrySequenceChars === 0
+          ? 0
+          : slice.length
       if (end >= entry.data.length) {
         batch.queue.shift()
       } else {
@@ -278,7 +271,15 @@ export class DaemonStreamDataBatcher {
       } else {
         batch.queuedCharsBySession.set(entry.sessionId, sessionHeldAfter)
       }
-      writeStreamDataEvents(socket, entry.sessionId, slice, this.maxLineBytes, sliceSequenceChars)
+      writeStreamDataEvents(
+        socket,
+        entry.sessionId,
+        slice,
+        this.maxLineBytes,
+        sliceSequenceChars,
+        entry.seq,
+        entry.transformed
+      )
       this.onAfterSocketWrite?.()
     }
     if (retained.length > 0) {
@@ -369,7 +370,9 @@ export class DaemonStreamDataBatcher {
           entry.sessionId,
           entry.data,
           this.maxLineBytes,
-          entry.sequenceChars ?? entry.data.length
+          entry.sequenceChars ?? entry.data.length,
+          entry.seq,
+          entry.transformed
         )
         this.onAfterSocketWrite?.()
       }
diff --git a/src/main/daemon/daemon-stream-data-entry.ts b/src/main/daemon/daemon-stream-data-entry.ts
new file mode 100644
index 00000000000..6d44c6a49e8
--- /dev/null
+++ b/src/main/daemon/daemon-stream-data-entry.ts
@@ -0,0 +1,46 @@
+import type { PendingStreamDataBatch } from './daemon-stream-keep-tail-drop'
+
+export type DaemonStreamEnqueueOptions = {
+  flushImmediately?: boolean
+  flushMaxChars?: number
+  rawLength?: number
+  transformed?: boolean
+  seq?: number
+}
+
+export function appendDaemonStreamData(
+  batch: PendingStreamDataBatch,
+  sessionId: string,
+  data: string,
+  options: DaemonStreamEnqueueOptions
+): void {
+  const last = batch.queue.at(-1)
+  // Why: control and transformed spans mark indivisible source-stream positions.
+  if (
+    last?.sessionId === sessionId &&
+    !last.control &&
+    !last.transformed &&
+    options.transformed !== true
+  ) {
+    last.data += data
+    const rawLengthBefore = last.sequenceChars ?? last.data.length - data.length
+    const combinedRawLength = rawLengthBefore + (options.rawLength ?? data.length)
+    last.sequenceChars = combinedRawLength === last.data.length ? undefined : combinedRawLength
+    last.seq = options.seq
+  } else {
+    batch.queue.push({
+      sessionId,
+      data,
+      ...(options.rawLength === undefined || options.rawLength === data.length
+        ? {}
+        : { sequenceChars: options.rawLength }),
+      ...(options.transformed ? { transformed: true } : {}),
+      ...(options.seq === undefined ? {} : { seq: options.seq })
+    })
+  }
+  batch.queuedChars += data.length
+  batch.queuedCharsBySession.set(
+    sessionId,
+    (batch.queuedCharsBySession.get(sessionId) ?? 0) + data.length
+  )
+}
diff --git a/src/main/daemon/daemon-stream-data-split.ts b/src/main/daemon/daemon-stream-data-split.ts
index 0e15cf49523..986aeb7abca 100644
--- a/src/main/daemon/daemon-stream-data-split.ts
+++ b/src/main/daemon/daemon-stream-data-split.ts
@@ -9,18 +9,26 @@ import type { Socket } from 'node:net'
 export function encodeStreamDataEvent(
   sessionId: string,
   data: string,
-  sequenceChars?: number
+  rawLength?: number,
+  seq?: number,
+  transformed?: boolean
 ): string {
   return encodeNdjson({
     type: 'event',
     event: 'data',
     sessionId,
-    payload: { data, ...(sequenceChars === undefined ? {} : { sequenceChars }) }
+    payload: {
+      data,
+      ...(seq === undefined ? {} : { seq }),
+      ...(rawLength === undefined ? {} : { rawLength }),
+      ...(rawLength === undefined ? {} : { sequenceChars: rawLength }),
+      ...(transformed ? { transformed: true } : {})
+    }
   })
 }
 
-function streamDataEventLineBytes(sessionId: string, data: string, sequenceChars?: number): number {
-  return Buffer.byteLength(encodeStreamDataEvent(sessionId, data, sequenceChars), 'utf8')
+function streamDataEventLineBytes(sessionId: string, data: string, rawLength?: number): number {
+  return Buffer.byteLength(encodeStreamDataEvent(sessionId, data, rawLength), 'utf8')
 }
 
 function isHighSurrogate(value: number): boolean {
@@ -100,15 +108,27 @@ export function writeStreamDataEvents(
   sessionId: string,
   data: string,
   maxLineBytes: number,
-  sequenceChars = data.length
+  rawLength = data.length,
+  seq?: number,
+  transformed = false
 ): void {
-  const explicitSequenceChars = sequenceChars === data.length ? undefined : sequenceChars
-  for (const chunk of splitStreamDataForNdjson(
+  const explicitRawLength = rawLength === data.length ? undefined : rawLength
+  if (transformed) {
+    streamSocket.write(encodeStreamDataEvent(sessionId, data, rawLength, seq, true))
+    return
+  }
+  const carriesMetadata = explicitRawLength !== undefined || seq !== undefined
+  const chunks = splitStreamDataForNdjson(
     sessionId,
     data,
-    maxLineBytes,
-    explicitSequenceChars
-  )) {
-    streamSocket.write(encodeStreamDataEvent(sessionId, chunk, explicitSequenceChars))
+    carriesMetadata ? Math.max(1, maxLineBytes - 96) : maxLineBytes,
+    explicitRawLength
+  )
+  let consumed = 0
+  for (const chunk of chunks) {
+    consumed += chunk.length
+    const chunkEndSeq = seq === undefined ? undefined : seq - (data.length - consumed)
+    const chunkRawLength = explicitRawLength === 0 ? 0 : carriesMetadata ? chunk.length : undefined
+    streamSocket.write(encodeStreamDataEvent(sessionId, chunk, chunkRawLength, chunkEndSeq))
   }
 }
diff --git a/src/main/daemon/daemon-stream-events.ts b/src/main/daemon/daemon-stream-events.ts
index 1644642bd09..b47e7413992 100644
--- a/src/main/daemon/daemon-stream-events.ts
+++ b/src/main/daemon/daemon-stream-events.ts
@@ -5,7 +5,14 @@ export type DataEvent = {
   type: 'event'
   event: 'data'
   sessionId: string
-  payload: { data: string; sequenceChars?: number }
+  payload: {
+    data: string
+    seq?: number
+    rawLength?: number
+    transformed?: boolean
+    /** Legacy v23 name retained for old adapter fixtures. */
+    sequenceChars?: number
+  }
 }
 
 export type ExitEvent = {
diff --git a/src/main/daemon/daemon-stream-keep-tail-drop.ts b/src/main/daemon/daemon-stream-keep-tail-drop.ts
index 0dc57e53522..0ef7bd0aab9 100644
--- a/src/main/daemon/daemon-stream-keep-tail-drop.ts
+++ b/src/main/daemon/daemon-stream-keep-tail-drop.ts
@@ -21,6 +21,8 @@ export type StreamQueueEntry = {
   /** Original PTY characters represented by data. Salvaged query copies are
    * delivered bytes but represent zero new positions in the source stream. */
   sequenceChars?: number
+  seq?: number
+  transformed?: boolean
   control?: DaemonEvent
 }
 
diff --git a/src/main/daemon/degraded-daemon-pty-provider.ts b/src/main/daemon/degraded-daemon-pty-provider.ts
index 572cb0aca37..591c2cfa53d 100644
--- a/src/main/daemon/degraded-daemon-pty-provider.ts
+++ b/src/main/daemon/degraded-daemon-pty-provider.ts
@@ -3,6 +3,7 @@ import { shutdownDegradedFallbackSessions } from './degraded-daemon-fallback-shu
 import type {
   IPtyProvider,
   PtyBackgroundStreamEvent,
+  PtyDataEvent,
   PtyProviderBufferSnapshot,
   PtyProcessInfo,
   PtySpawnOptions,
@@ -26,11 +27,7 @@ export class DegradedDaemonPtyProvider implements IPtyProvider {
   private fallback: ManagedPtyProvider
   private sessionProviders = new Map<string, ManagedPtyProvider>()
   private unsubscribers: (() => void)[] = []
-  private dataListeners: ((payload: {
-    id: string
-    data: string
-    sequenceChars?: number
-  }) => void)[] = []
+  private dataListeners: ((payload: PtyDataEvent) => void)[] = []
   private exitListeners: ((payload: { id: string; code: number }) => void)[] = []
 
   constructor(opts: {
@@ -148,6 +145,10 @@ export class DegradedDaemonPtyProvider implements IPtyProvider {
     await this.providerFor(id).clearBuffer(id)
   }
 
+  async closeStartupQueryAuthority(id: string): Promise<number> {
+    return (await this.providerFor(id).closeStartupQueryAuthority?.(id)) ?? 0
+  }
+
   acknowledgeDataEvent(id: string, charCount: number): void {
     this.providerFor(id).acknowledgeDataEvent(id, charCount)
   }
@@ -187,9 +188,7 @@ export class DegradedDaemonPtyProvider implements IPtyProvider {
     return this.fallback.getProfiles()
   }
 
-  onData(
-    callback: (payload: { id: string; data: string; sequenceChars?: number }) => void
-  ): () => void {
+  onData(callback: (payload: PtyDataEvent) => void): () => void {
     this.dataListeners.push(callback)
     return () => {
       const idx = this.dataListeners.indexOf(callback)
diff --git a/src/main/daemon/session.test.ts b/src/main/daemon/session.test.ts
index 3b8f068868c..b5446524ebf 100644
--- a/src/main/daemon/session.test.ts
+++ b/src/main/daemon/session.test.ts
@@ -106,6 +106,11 @@ describe('Session', () => {
     cols?: number
     rows?: number
     launchAgent?: TuiAgent
+    startupIngress?: {
+      colors: { foreground: string; background: string }
+      deadlineMs: number
+      echoProjection?: 'windows-conpty-esc-stripped'
+    }
     wslDistro?: string
   }): Session {
     session = new Session({
@@ -116,6 +121,7 @@ describe('Session', () => {
       wslDistro: opts?.wslDistro,
       subprocess,
       shellReadySupported: opts?.shellReadySupported ?? false,
+      ...(opts?.startupIngress ? { startupIngress: opts.startupIngress } : {}),
       ...(opts?.shellReadyTimeoutMs !== undefined
         ? { shellReadyTimeoutMs: opts.shellReadyTimeoutMs }
         : {})
@@ -187,6 +193,56 @@ describe('Session', () => {
       expect(received1).toEqual(['broadcast'])
       expect(received2).toEqual(['broadcast'])
     })
+
+    it('classifies startup queries and cooked echoes before model, persistence, and fanout', () => {
+      createSession({
+        startupIngress: {
+          colors: { foreground: '#2e3434', background: '#ffffff' },
+          deadlineMs: 5_000,
+          echoProjection: 'windows-conpty-esc-stripped'
+        }
+      })
+      const onData = vi.fn()
+      session.attachClient({ onData, onExit: () => {} })
+      const query = '\x1b]10;?\x07'
+      const echo = ']10;rgb:2e2e/3434/3434\\'
+
+      subprocess.simulateData(query)
+      subprocess.simulateData(echo)
+      subprocess.simulateData('prompt')
+
+      expect(subprocess.written).toEqual(['\x1b]10;rgb:2e2e/3434/3434\x1b\\'])
+      expect(onData.mock.calls).toEqual([
+        ['', query.length, true, query.length],
+        ['', echo.length, true, query.length + echo.length],
+        ['prompt']
+      ])
+      expect(session.takePendingOutput(false)?.records).toEqual([
+        { kind: 'output', data: 'prompt' }
+      ])
+      expect(session.getSnapshot()).toMatchObject({
+        outputSequence: query.length + echo.length + 'prompt'.length
+      })
+      expect(session.getSnapshot()?.snapshotAnsi).toContain('prompt')
+      expect(session.getSnapshot()?.snapshotAnsi).not.toContain(']10;rgb')
+    })
+
+    it('releases a held cooked-echo prefix before taking a snapshot', () => {
+      createSession({
+        startupIngress: {
+          colors: { foreground: '#2e3434', background: '#ffffff' },
+          deadlineMs: 5_000,
+          echoProjection: 'windows-conpty-esc-stripped'
+        }
+      })
+      subprocess.simulateData('\x1b]10;?\x07')
+      subprocess.simulateData(']10;rgb:2e2e/')
+
+      const snapshot = session.getSnapshot()
+
+      expect(snapshot?.snapshotAnsi).toContain(']10;rgb:2e2e/')
+      expect(snapshot?.outputSequence).toBe('\x1b]10;?\x07]10;rgb:2e2e/'.length)
+    })
   })
 
   describe('write', () => {
diff --git a/src/main/daemon/session.ts b/src/main/daemon/session.ts
index 7ca52cf0c2a..1c414046cb3 100644
--- a/src/main/daemon/session.ts
+++ b/src/main/daemon/session.ts
@@ -12,6 +12,11 @@ import { isPowerShellProcess } from '../../shared/shell-process-detection'
 import { killWithDescendantSweep } from '../pty-descendant-termination'
 import type { TuiAgent } from '../../shared/types'
 import { PhysicalExitTracker } from '../../shared/physical-exit-tracker'
+import {
+  PtyStartupIngress,
+  type PtyIngressEmission,
+  type PtyStartupIngressIntent
+} from '../../shared/pty-startup-ingress'
 import type {
   PendingOutputRecord,
   SessionState,
@@ -97,11 +102,12 @@ export type SessionOptions = {
   // reaper, dead sessions (and their ~5000-row scrollback emulators) accumulate
   // for the lifetime of the long-lived daemon process.
   onExit?: (code: number) => void
+  startupIngress?: PtyStartupIngressIntent
 }
 
 type AttachedClient = {
   token: symbol
-  onData: (data: string) => void
+  onData: (data: string, rawLength?: number, transformed?: boolean, seq?: number) => void
   onExit: (code: number) => void
 }
 
@@ -135,6 +141,7 @@ export class Session {
   private forceKillSent = false
   private subprocessDisposed = false
   private readonly physicalExit = new PhysicalExitTracker()
+  private readonly startupIngress: PtyStartupIngress
 
   constructor(opts: SessionOptions) {
     this.sessionId = opts.sessionId
@@ -170,6 +177,11 @@ export class Session {
     }
 
     this.postReadyFlushGate = new PostReadyFlushGate(() => this.flushPreReadyQueue())
+    this.startupIngress = new PtyStartupIngress({
+      ...(opts.startupIngress ? { intent: opts.startupIngress } : {}),
+      write: (data) => this.subprocess.write(data),
+      onEmission: (emission) => this.emitSubprocessOutput(emission)
+    })
     this.subprocess.onData((data) => this.handleSubprocessData(data))
     this.subprocess.onExit((code) => this.handleSubprocessExit(code))
   }
@@ -389,7 +401,7 @@ export class Session {
     this.subprocess.signal(sig)
   }
 
-  attachClient(client: { onData: (data: string) => void; onExit: (code: number) => void }): symbol {
+  attachClient(client: Omit<AttachedClient, 'token'>): symbol {
     const token = Symbol('attach')
     this.attachedClients.push({ token, ...client })
     return token
@@ -413,6 +425,7 @@ export class Session {
   }
 
   getSnapshot(opts: { scrollbackRows?: number } = {}): TerminalSnapshot | null {
+    this.startupIngress.snapshotBarrier()
     if (this._disposed) {
       return null
     }
@@ -518,7 +531,9 @@ export class Session {
   }
 
   prepareForFinalSnapshot(): string {
-    return this.releaseHeldShellReadyBytes()
+    const held = this.releaseHeldShellReadyBytes()
+    this.startupIngress.snapshotBarrier()
+    return held
   }
 
   dispose(): void {
@@ -533,6 +548,8 @@ export class Session {
     // move this capture below #teardownSubprocess or the `_state = 'exited'`
     // assignment — #teardownSubprocess flips `_disposed` but the invariant
     // depends on the PRE-flip value of `_state`.
+    this.releaseHeldShellReadyBytes()
+    this.startupIngress.drainAndClose()
     const wasTerminating = this._isTerminating && this._state !== 'exited'
     const clientsToNotify = wasTerminating ? this.attachedClients.slice() : []
     if (wasTerminating) {
@@ -667,25 +684,29 @@ export class Session {
       this.postReadyFlushGate.notifyData()
     }
 
-    this.emitSubprocessOutput(data)
+    this.startupIngress.accept(data)
   }
 
-  private emitSubprocessOutput(data: string): void {
-    if (data.length === 0) {
-      return
-    }
-
+  private emitSubprocessOutput(emission: PtyIngressEmission): void {
+    const { data } = emission
+    const rawLength = emission.rawEndSeq - emission.rawStartSeq
     // Why: daemon stream thinning can omit bytes before main sees them. The
     // absolute count lets an authoritative snapshot cover those gaps while
     // renderer reconciliation deduplicates any queued post-snapshot tail.
-    this.outputSequence += data.length
+    this.outputSequence += rawLength
     // Feed data to headless emulator for state tracking
-    this.emulator.write(data)
-    this.recordPendingOutput({ kind: 'output', data })
+    if (data.length > 0) {
+      this.emulator.write(data)
+      this.recordPendingOutput({ kind: 'output', data })
+    }
 
     // Broadcast to attached clients
     for (const client of this.attachedClients) {
-      client.onData(data)
+      if (emission.transformed || rawLength !== data.length) {
+        client.onData(data, rawLength, true, this.outputSequence)
+      } else {
+        client.onData(data)
+      }
     }
   }
 
@@ -695,13 +716,14 @@ export class Session {
       return
     }
 
+    this.releaseHeldShellReadyBytes()
+    this.startupIngress.drainAndClose()
     this._exitCode = code
     this._state = 'exited'
     this._isTerminating = false
     // Why resume:false — the child is reaped, so there is nothing to unblock;
     // only the failsafe timer must not outlive the session.
     this.releaseProducerPause({ resume: false })
-    this.releaseHeldShellReadyBytes()
 
     if (this.killTimer) {
       clearTimeout(this.killTimer)
@@ -740,10 +762,14 @@ export class Session {
     // bytes can be stripped. If readiness never completes, preserve the
     // previous behavior by releasing any held prefix before timeout or exit
     // state changes discard it.
-    this.emitSubprocessOutput(heldBytes)
+    this.startupIngress.accept(heldBytes)
     return heldBytes
   }
 
+  closeStartupQueryAuthority(): number {
+    return this.startupIngress.closeQueryAuthority()
+  }
+
   private transitionToReady(postMarkerBytesObserved = false): void {
     this._shellState = 'ready'
     this.shellReadyScanState = null
diff --git a/src/main/daemon/terminal-host-create-contract.ts b/src/main/daemon/terminal-host-create-contract.ts
index 10cd5733cd3..47fba51b2c3 100644
--- a/src/main/daemon/terminal-host-create-contract.ts
+++ b/src/main/daemon/terminal-host-create-contract.ts
@@ -1,6 +1,7 @@
 import type { StartupCommandDelivery } from '../../shared/codex-startup-delivery'
 import type { TuiAgent } from '../../shared/types'
 import type { ShellReadyState, TerminalSnapshot } from './types'
+import type { PtyStartupIngressIntent } from '../../shared/pty-startup-ingress'
 
 export type CreateOrAttachOptions = {
   sessionId: string
@@ -19,7 +20,11 @@ export type CreateOrAttachOptions = {
   shellReadySupported?: boolean
   shellReadyTimeoutMs?: number
   historySeed?: string
-  streamClient: { onData: (data: string) => void; onExit: (code: number) => void }
+  startupIngress?: PtyStartupIngressIntent
+  streamClient: {
+    onData: (data: string, rawLength?: number, transformed?: boolean, seq?: number) => void
+    onExit: (code: number) => void
+  }
 }
 
 export type CreateOrAttachResult = {
diff --git a/src/main/daemon/terminal-host-options.ts b/src/main/daemon/terminal-host-options.ts
new file mode 100644
index 00000000000..a879a618c25
--- /dev/null
+++ b/src/main/daemon/terminal-host-options.ts
@@ -0,0 +1,27 @@
+import type { StartupCommandDelivery } from '../../shared/codex-startup-delivery'
+import type { SubprocessHandle } from './session'
+import type { TakePendingOutputResult, TerminalSnapshot } from './types'
+
+export type TerminalHostOptions = {
+  spawnSubprocess: (opts: {
+    sessionId: string
+    cols: number
+    rows: number
+    cwd?: string
+    env?: Record<string, string>
+    envToDelete?: string[]
+    command?: string
+    startupCommandDelivery?: StartupCommandDelivery
+    shellOverride?: string
+    terminalWindowsWslDistro?: string | null
+    terminalWindowsPowerShellImplementation?: 'auto' | 'powershell.exe' | 'pwsh.exe'
+  }) => SubprocessHandle
+  // Why: graceful shutdown checkpoints must finish in-process before teardown.
+  onFinalCheckpoint?: (
+    sessionId: string,
+    snapshot: TerminalSnapshot,
+    records: TakePendingOutputResult['records']
+  ) => void
+  // Why: tests need deterministic tombstone eviction without thousands of sessions.
+  maxTombstones?: number
+}
diff --git a/src/main/daemon/terminal-host.ts b/src/main/daemon/terminal-host.ts
index ba15c6ed814..d8458aa81ad 100644
--- a/src/main/daemon/terminal-host.ts
+++ b/src/main/daemon/terminal-host.ts
@@ -1,8 +1,7 @@
-import { Session, type SubprocessHandle } from './session'
+import { Session } from './session'
 import { normalizePtySize } from './daemon-pty-size'
 import { shellPathSupportsPtyStartupBarrier } from './shell-ready'
 import { resolveProcessCwd } from '../providers/process-cwd'
-import type { StartupCommandDelivery } from '../../shared/codex-startup-delivery'
 import { buildStartupCommandSubmission } from '../../shared/startup-command-submission'
 import {
   SessionNotFoundError,
@@ -11,42 +10,17 @@ import {
   type TerminalSnapshot
 } from './types'
 import type { CreateOrAttachOptions, CreateOrAttachResult } from './terminal-host-create-contract'
+import type { TerminalHostOptions } from './terminal-host-options'
 import { shutdownTerminalHostSessions } from './terminal-host-session-shutdown'
 import { TerminalSessionTeardown } from './terminal-session-teardown'
 import { resolveWslSessionContext } from './wsl-session-context'
 import { getDaemonSessionResultMetadata } from './daemon-create-or-attach-result'
 
 export type { CreateOrAttachOptions, CreateOrAttachResult } from './terminal-host-create-contract'
+export type { TerminalHostOptions } from './terminal-host-options'
 
 const DEFAULT_MAX_TOMBSTONES = 1000
 
-export type TerminalHostOptions = {
-  spawnSubprocess: (opts: {
-    sessionId: string
-    cols: number
-    rows: number
-    cwd?: string
-    env?: Record<string, string>
-    envToDelete?: string[]
-    command?: string
-    startupCommandDelivery?: StartupCommandDelivery
-    shellOverride?: string
-    terminalWindowsWslDistro?: string | null
-    terminalWindowsPowerShellImplementation?: 'auto' | 'powershell.exe' | 'pwsh.exe'
-  }) => SubprocessHandle
-  // Why: on graceful shutdown, the host writes final checkpoints for all live
-  // sessions before killing them. This bypasses the RPC round-trip — the daemon
-  // writes checkpoints in-process, guaranteeing completion before teardown.
-  onFinalCheckpoint?: (
-    sessionId: string,
-    snapshot: TerminalSnapshot,
-    records: TakePendingOutputResult['records']
-  ) => void
-  // Why: production keeps a large cap, but tests need a small deterministic cap
-  // without spawning thousands of full terminal sessions.
-  maxTombstones?: number
-}
-
 export class TerminalHost {
   private sessions = new Map<string, Session>()
   private sessionTeardown = new TerminalSessionTeardown(this.sessions)
@@ -147,6 +121,7 @@ export class TerminalHost {
       subprocess,
       shellReadySupported,
       historySeed: opts.historySeed,
+      ...(opts.startupIngress ? { startupIngress: opts.startupIngress } : {}),
       wslDistro,
       // Why: reap the dead session (dispose emulator + drop from the map) the
       // moment its subprocess exits, instead of retaining it for the daemon's
@@ -197,6 +172,10 @@ export class TerminalHost {
     this.getAliveSession(sessionId).write(data)
   }
 
+  closeStartupQueryAuthority(sessionId: string): number {
+    return this.getAliveSession(sessionId).closeStartupQueryAuthority()
+  }
+
   resize(sessionId: string, cols: number, rows: number): void {
     this.getAliveSession(sessionId).resize(cols, rows)
   }
diff --git a/src/main/daemon/terminal-modes.ts b/src/main/daemon/terminal-modes.ts
new file mode 100644
index 00000000000..41718b196fc
--- /dev/null
+++ b/src/main/daemon/terminal-modes.ts
@@ -0,0 +1,11 @@
+export type TerminalModes = {
+  bracketedPaste: boolean
+  mouseTracking: boolean
+  mouseTrackingMode?: 'none' | 'x10' | 'vt200' | 'drag' | 'any'
+  sgrMouseMode?: boolean
+  sgrMousePixelsMode?: boolean
+  applicationCursor: boolean
+  alternateScreen: boolean
+  /** Kitty keyboard protocol flags used only to reseed a warm daemon emulator. */
+  kittyKeyboardFlags?: number
+}
diff --git a/src/main/daemon/terminal-snapshot.ts b/src/main/daemon/terminal-snapshot.ts
new file mode 100644
index 00000000000..653d8fc4bd6
--- /dev/null
+++ b/src/main/daemon/terminal-snapshot.ts
@@ -0,0 +1,20 @@
+import type { TerminalOscLinkRange } from '../../shared/terminal-osc-link-ranges'
+import type { TerminalModes } from './terminal-modes'
+
+export type TerminalSnapshot = {
+  snapshotAnsi: string
+  /** Parser tail is already counted by the snapshot sequence and must restore last. */
+  pendingEscapeTailAnsi?: string
+  /** Normal buffer captured separately while snapshotAnsi holds an alternate buffer. */
+  scrollbackAnsi: string
+  oscLinks?: TerminalOscLinkRange[]
+  rehydrateSequences: string
+  cwd: string | null
+  modes: TerminalModes
+  cols: number
+  rows: number
+  scrollbackLines: number
+  lastTitle?: string
+  /** Optional because persisted snapshots and older v19 daemons lack it. */
+  outputSequence?: number
+}
diff --git a/src/main/daemon/types.ts b/src/main/daemon/types.ts
index 0daaf0ac0cf..5c148dbf238 100644
--- a/src/main/daemon/types.ts
+++ b/src/main/daemon/types.ts
@@ -1,4 +1,3 @@
-import type { TerminalOscLinkRange } from '../../shared/terminal-osc-link-ranges'
 import type {
   ConfirmForegroundProcessRequest,
   GetForegroundProcessRequest
@@ -12,67 +11,24 @@ export type {
 // ─── Protocol Version ────────────────────────────────────────────────
 import type { StartupCommandDelivery } from '../../shared/codex-startup-delivery'
 import type { TuiAgent } from '../../shared/types'
-// Why: daemons can survive app updates. Bump for IPC wire-shape changes, or
-// when daemon-baked behavior cannot be delivered by on-disk wrapper refresh.
-// Why: bump when adding daemon wire behavior so same-version old daemons do
-// not silently accept the handshake and then reject new RPCs.
-export const PROTOCOL_VERSION = 24
-export const GIT_CREDENTIAL_GUARD_HOST_PROTOCOL_VERSION = 22
-export const CLEAN_DISCONNECT_PROTOCOL_VERSION = 24
-export const PREVIOUS_DAEMON_PROTOCOL_VERSIONS = [
-  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23
-] as const
+import type { PtyStartupIngressIntent } from '../../shared/pty-startup-ingress'
+export type { TerminalModes } from './terminal-modes'
+import type { TerminalSnapshot } from './terminal-snapshot'
+export type { TerminalSnapshot } from './terminal-snapshot'
+export {
+  CLEAN_DISCONNECT_PROTOCOL_VERSION,
+  GIT_CREDENTIAL_GUARD_HOST_PROTOCOL_VERSION,
+  PREVIOUS_DAEMON_PROTOCOL_VERSIONS,
+  PROTOCOL_VERSION,
+  PTY_STARTUP_INGRESS_PROTOCOL_VERSION,
+  supportsPtyStartupIngress
+} from './daemon-protocol-version'
 
 // ─── Session State Machine ──────────────────────────────────────────
 export type SessionState = 'created' | 'spawning' | 'running' | 'exiting' | 'exited'
 
 export type ShellReadyState = 'pending' | 'ready' | 'timed_out' | 'unsupported'
 
-// ─── Terminal Snapshot ──────────────────────────────────────────────
-export type TerminalSnapshot = {
-  snapshotAnsi: string
-  /** Trailing incomplete escape sequence the emulator ingested but xterm's
-   *  parser is still holding (a PTY read ended mid-escape). Restorers must
-   *  write this LAST — after their own post-replay resets, immediately before
-   *  post-snapshot live chunks — so the continuation bytes complete it
-   *  exactly as live (Bug E / #7329, notes/garble-fuzz-divergences.md). Its
-   *  bytes are already counted by the snapshot seq. */
-  pendingEscapeTailAnsi?: string
-  /** Normal buffer captured separately while snapshotAnsi holds an active
-   *  alternate buffer. Empty for normal-screen snapshots. */
-  scrollbackAnsi: string
-  oscLinks?: TerminalOscLinkRange[]
-  rehydrateSequences: string
-  cwd: string | null
-  modes: TerminalModes
-  cols: number
-  rows: number
-  scrollbackLines: number
-  lastTitle?: string
-  /** Absolute UTF-16 character count ingested by this live daemon session.
-   *  Optional because persisted snapshots and older v19 daemons lack it. */
-  outputSequence?: number
-}
-
-export type TerminalModes = {
-  bracketedPaste: boolean
-  mouseTracking: boolean
-  mouseTrackingMode?: 'none' | 'x10' | 'vt200' | 'drag' | 'any'
-  sgrMouseMode?: boolean
-  sgrMousePixelsMode?: boolean
-  applicationCursor: boolean
-  alternateScreen: boolean
-  /** Kitty keyboard protocol flags (CSI = u pushes) for emulator re-seed
-   *  parity ONLY. Consumed by the daemon warm-reattach path: the spawn
-   *  result threads them into seedHeadlessTerminal, which re-applies them to
-   *  the fresh runtime emulator (HeadlessEmulator.applyKittyKeyboardFlags)
-   *  so hidden `CSI ? u` answers the real flags instead of ?0u.
-   *  rehydrateSequences must never push these into a renderer xterm —
-   *  POST_REPLAY_REATTACH_RESET's deliberate kitty reset stays authoritative
-   *  (terminal-query-authority.md §kitty). */
-  kittyKeyboardFlags?: number
-}
-
 // The on-disk checkpoint.json shape lives in daemon-checkpoint-file.ts (it
 // depends only on TerminalModes here) — re-exported so existing importers of
 // `./types` keep working.
@@ -115,9 +71,16 @@ export type CreateOrAttachRequest = {
     shellReadyTimeoutMs?: number
     /** Recovered ANSI applied before the new subprocess can emit startup output. */
     historySeed?: string
+    startupIngress?: PtyStartupIngressIntent
   }
 }
 
+export type CloseStartupQueryAuthorityRequest = {
+  id: string
+  type: 'closeStartupQueryAuthority'
+  payload: { sessionId: string }
+}
+
 export type CancelCreateOrAttachRequest = {
   id: string
   type: 'cancelCreateOrAttach'
@@ -337,6 +300,7 @@ export type DaemonRequest =
   | GetSnapshotRequest
   | GetSizeRequest
   | TakePendingOutputRequest
+  | CloseStartupQueryAuthorityRequest
 
 // ─── RPC Responses (Daemon → Client, on control socket) ────────────
 
diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index c8843bd5076..5fddd31c1f8 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -3852,7 +3852,8 @@ describe('registerPtyHandlers', () => {
         result.id,
         'daemon output',
         expect.any(Number),
-        'daemon output'.length
+        'daemon output'.length,
+        undefined
       )
       expect(mainWindow.webContents.send).toHaveBeenCalledWith('pty:data', {
         id: result.id,
@@ -8257,14 +8258,17 @@ describe('registerPtyHandlers', () => {
       mockProc.proc.write.mockClear()
       mainWindow.webContents.send.mockClear()
 
-      mockProc.emitData('\x1b]10;?\x1b\\\x1b]11;?\x1b\\ready')
+      const sourceData = '\x1b]10;?\x1b\\\x1b]11;?\x1b\\ready'
+      mockProc.emitData(sourceData)
 
       expect(mockProc.proc.write).toHaveBeenCalledWith('\x1b]10;rgb:eeee/eeee/eeee\x1b\\')
       expect(mockProc.proc.write).toHaveBeenCalledWith('\x1b]11;rgb:1111/1111/1111\x1b\\')
       vi.advanceTimersByTime(2)
       expect(mainWindow.webContents.send).toHaveBeenCalledWith('pty:data', {
         id: spawnResult.id,
-        data: 'ready'
+        data: 'ready',
+        rawLength: sourceData.length,
+        transformed: true
       })
     } finally {
       vi.useRealTimers()
@@ -8291,14 +8295,17 @@ describe('registerPtyHandlers', () => {
       mockProc.proc.write.mockClear()
       mainWindow.webContents.send.mockClear()
 
-      mockProc.emitData('\x1b]10;?;?\x1b\\ready')
+      const sourceData = '\x1b]10;?;?\x1b\\ready'
+      mockProc.emitData(sourceData)
 
       expect(mockProc.proc.write).toHaveBeenCalledWith('\x1b]10;rgb:eeee/eeee/eeee\x1b\\')
       expect(mockProc.proc.write).toHaveBeenCalledWith('\x1b]11;rgb:1111/1111/1111\x1b\\')
       vi.advanceTimersByTime(2)
       expect(mainWindow.webContents.send).toHaveBeenCalledWith('pty:data', {
         id: spawnResult.id,
-        data: 'ready'
+        data: 'ready',
+        rawLength: sourceData.length,
+        transformed: true
       })
     } finally {
       vi.useRealTimers()
@@ -8371,13 +8378,28 @@ describe('registerPtyHandlers', () => {
     }
   })
 
-  it('answers daemon agent startup OSC color queries before spawn resolves', async () => {
+  it('accepts source-classified daemon startup spans before spawn resolves', async () => {
     vi.useFakeTimers()
-    let dataHandler: ((payload: { id: string; data: string }) => void) | null = null
+    type ProviderData = {
+      id: string
+      data: string
+      sequenceChars?: number
+      transformed?: boolean
+      seq?: number
+    }
+    let dataHandler: ((payload: ProviderData) => void) | null = null
     const write = vi.fn()
-    const spawn = vi.fn(async (options: { sessionId?: string }) => {
+    const query = '\x1b]10;?\x1b\\\x1b]11;?\x1b\\'
+    const spawn = vi.fn(async (options: { sessionId?: string; startupIngress?: unknown }) => {
       const id = options.sessionId ?? 'daemon-pty'
-      dataHandler?.({ id, data: '\x1b]10;?\x1b\\\x1b]11;?\x1b\\daemon-ready' })
+      dataHandler?.({
+        id,
+        data: '',
+        sequenceChars: query.length,
+        transformed: true,
+        seq: query.length
+      })
+      dataHandler?.({ id, data: 'daemon-ready' })
       return { id }
     })
     setLocalPtyProvider({
@@ -8395,7 +8417,7 @@ describe('registerPtyHandlers', () => {
       getForegroundProcess: vi.fn(),
       serialize: vi.fn(),
       revive: vi.fn(),
-      onData: vi.fn((handler: (payload: { id: string; data: string }) => void) => {
+      onData: vi.fn((handler: (payload: ProviderData) => void) => {
         dataHandler = handler
         return () => {}
       }),
@@ -8408,7 +8430,16 @@ describe('registerPtyHandlers', () => {
     } as never)
 
     try {
-      registerPtyHandlers(mainWindow as never)
+      let seq = 0
+      const runtime = {
+        setPtyController: vi.fn(),
+        createPreAllocatedTerminalHandle: vi.fn(() => null),
+        onPtyData: vi.fn(
+          (_id: string, _data: string, _at: number, rawLength: number) => (seq += rawLength)
+        ),
+        registerPty: vi.fn()
+      }
+      registerPtyHandlers(mainWindow as never, runtime as never)
       const spawnResult = (await handlers.get('pty:spawn')!(null, {
         cols: 80,
         rows: 24,
@@ -8420,22 +8451,39 @@ describe('registerPtyHandlers', () => {
         }
       })) as { id: string }
 
-      expect(write).toHaveBeenCalledWith(spawnResult.id, '\x1b]10;rgb:eeee/eeee/eeee\x1b\\')
-      expect(write).toHaveBeenCalledWith(spawnResult.id, '\x1b]11;rgb:1111/1111/1111\x1b\\')
+      expect(spawn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          startupIngress: expect.objectContaining({
+            colors: { foreground: '#eeeeee', background: '#111111' },
+            deadlineMs: 5_000
+          })
+        })
+      )
+      expect(write).not.toHaveBeenCalled()
       vi.advanceTimersByTime(2)
       expect(mainWindow.webContents.send).toHaveBeenCalledWith('pty:data', {
         id: spawnResult.id,
-        data: 'daemon-ready'
+        data: 'daemon-ready',
+        seq: query.length + 'daemon-ready'.length,
+        rawLength: query.length + 'daemon-ready'.length,
+        transformed: true
       })
     } finally {
       vi.useRealTimers()
     }
   })
 
-  it('drops renderer sequence metadata when an answered OSC query is batched', async () => {
+  it('preserves source raw sequence metadata when a consumed query is batched', async () => {
     vi.useFakeTimers()
+    type ProviderData = {
+      id: string
+      data: string
+      sequenceChars?: number
+      transformed?: boolean
+      seq?: number
+    }
     const providerEvents: {
-      dataHandler?: (payload: { id: string; data: string }) => void
+      dataHandler?: (payload: ProviderData) => void
     } = {}
     const write = vi.fn()
     const spawn = vi.fn(async (options: { sessionId?: string }) => ({
@@ -8456,7 +8504,7 @@ describe('registerPtyHandlers', () => {
       getForegroundProcess: vi.fn(),
       serialize: vi.fn(),
       revive: vi.fn(),
-      onData: vi.fn((handler: (payload: { id: string; data: string }) => void) => {
+      onData: vi.fn((handler: (payload: ProviderData) => void) => {
         providerEvents.dataHandler = handler
         return () => {}
       }),
@@ -8471,8 +8519,8 @@ describe('registerPtyHandlers', () => {
     const runtime = {
       setPtyController: vi.fn(),
       createPreAllocatedTerminalHandle: vi.fn(() => null),
-      onPtyData: vi.fn((_id: string, data: string) => {
-        seq += data.length
+      onPtyData: vi.fn((_id: string, data: string, _at: number, rawLength = data.length) => {
+        seq += rawLength
         return seq
       }),
       registerPty: vi.fn()
@@ -8493,17 +8541,24 @@ describe('registerPtyHandlers', () => {
       mainWindow.webContents.send.mockClear()
 
       providerEvents.dataHandler?.({ id: spawnResult.id, data: 'prefix' })
+      const query = '\x1b]10;?\x1b\\\x1b]11;?\x1b\\'
       providerEvents.dataHandler?.({
         id: spawnResult.id,
-        data: '\x1b]10;?\x1b\\\x1b]11;?\x1b\\ready'
+        data: '',
+        sequenceChars: query.length,
+        transformed: true,
+        seq: 'prefix'.length + query.length
       })
+      providerEvents.dataHandler?.({ id: spawnResult.id, data: 'ready' })
       vi.advanceTimersByTime(2)
 
-      expect(write).toHaveBeenCalledWith(spawnResult.id, '\x1b]10;rgb:eeee/eeee/eeee\x1b\\')
-      expect(write).toHaveBeenCalledWith(spawnResult.id, '\x1b]11;rgb:1111/1111/1111\x1b\\')
+      expect(write).not.toHaveBeenCalled()
       expect(mainWindow.webContents.send).toHaveBeenCalledWith('pty:data', {
         id: spawnResult.id,
-        data: 'prefixready'
+        data: 'prefixready',
+        seq: 'prefix'.length + query.length + 'ready'.length,
+        rawLength: 'prefix'.length + query.length + 'ready'.length,
+        transformed: true
       })
     } finally {
       vi.useRealTimers()
@@ -9925,7 +9980,8 @@ describe('registerPtyHandlers', () => {
           result.id,
           'hidden output',
           expect.any(Number),
-          'hidden output'.length
+          'hidden output'.length,
+          undefined
         )
         expect(mainWindow.webContents.send).toHaveBeenCalledTimes(1)
         // Why out-of-band: an in-band empty pty:data chunk is ambiguous with
@@ -10477,7 +10533,8 @@ describe('registerPtyHandlers', () => {
           'daemon-session',
           'pre-spawn prompt\x1b[c',
           expect.any(Number),
-          'pre-spawn prompt\x1b[c'.length
+          'pre-spawn prompt\x1b[c'.length,
+          undefined
         )
         expect(mainWindow.webContents.send).toHaveBeenCalledTimes(1)
         expect(mainWindow.webContents.send).toHaveBeenCalledWith('pty:modelRestoreNeeded', {
diff --git a/src/main/ipc/pty.ts b/src/main/ipc/pty.ts
index 8c6b89d0d48..956383b7651 100644
--- a/src/main/ipc/pty.ts
+++ b/src/main/ipc/pty.ts
@@ -149,13 +149,7 @@ import { isHostCodexHomeForWsl, isWslCodexHomeForHost } from '../pty/codex-home-
 import { buildConfiguredProxyEnv, type NetworkProxySettings } from '../../shared/network-proxy'
 import { resolveSetupAgentSequenceLaunchCommand } from '../../shared/setup-agent-sequencing'
 import { parseWorkspaceKey } from '../../shared/workspace-scope'
-import {
-  answerStartupTerminalColorQueries,
-  clearStartupTerminalColorQueryReplies,
-  getStartupTerminalColorQueryReplyColors,
-  moveStartupTerminalColorQueryReplies,
-  registerStartupTerminalColorQueryReplies
-} from './terminal-startup-color-query-replies'
+import { getStartupTerminalColorQueryReplyColors } from './terminal-startup-color-query-replies'
 import {
   assertFolderWorkspacePathUsable,
   getFolderWorkspacePathStatus
@@ -459,20 +453,14 @@ function tryGetProviderForPty(ptyId: string): IPtyProvider | undefined {
   }
 }
 
-function getProviderForStartupTerminalColorReply(ptyId: string): IPtyProvider | undefined {
-  const ownedConnectionId = ptyOwnership.get(ptyId)
-  if (ownedConnectionId !== undefined) {
-    return getProvider(ownedConnectionId)
+function closeStartupQueryAuthorityForPty(ptyId: string): void {
+  try {
+    void Promise.resolve(tryGetProviderForPty(ptyId)?.closeStartupQueryAuthority?.(ptyId)).catch(
+      () => {}
+    )
+  } catch {
+    /* Best-effort handoff; the bounded source deadline remains the fallback. */
   }
-  const parsedSshId = parseAppSshPtyId(ptyId)
-  if (parsedSshId) {
-    return getProvider(parsedSshId.connectionId)
-  }
-  return localProvider
-}
-
-export function answerStartupTerminalColorQueriesForPty(ptyId: string, data: string): string {
-  return answerStartupTerminalColorQueries(ptyId, data, getProviderForStartupTerminalColorReply)
 }
 
 function normalizeNodePtySpawnError(err: unknown): Error {
@@ -1189,7 +1177,6 @@ export function clearProviderPtyState(id: string): void {
   rendererVisibilityKnownPtys.delete(id)
   pendingHiddenRendererResizeOutputPtys.delete(id)
   deliveredHiddenRendererResizeOutputPtys.delete(id)
-  clearStartupTerminalColorQueryReplies(id)
   // Why: every PTY teardown path funnels through here (local exit, daemon
   // shutdown, SSH exit/connection teardown) — hidden/interest gate bits must
   // not outlive the PTY or a reused map entry could silently gate a new one.
@@ -1637,7 +1624,8 @@ export function registerPtyHandlers(
         markClaudePtyExited(id)
         runtime?.onPtyExit(id, code)
       },
-      onData: (id, data, timestamp) => runtime?.onPtyData(id, data, timestamp)
+      onData: (id, data, timestamp, sequenceChars, transformed) =>
+        runtime?.onPtyData(id, data, timestamp, sequenceChars ?? data.length, transformed)
     })
   }
 
@@ -1648,6 +1636,8 @@ export function registerPtyHandlers(
   type PendingPtyData = {
     data: string
     startSeq?: number
+    rawLength?: number
+    transformed?: true
     containsBackgroundOutput?: boolean
     // Why droppedOutput (not main's droppedBacklog trim): this branch bounds
     // the unsent backlog with the O(1) drop-to-sentinel + query-salvage +
@@ -1662,6 +1652,7 @@ export function registerPtyHandlers(
     data: string
     seq?: number
     rawLength?: number
+    transformed?: boolean
     background?: boolean
     droppedOutput?: boolean
   }
@@ -2057,20 +2048,23 @@ export function registerPtyHandlers(
     return true
   }
 
-  function getChunkStartSeq(endSeq: number | undefined, data: string): number | undefined {
-    return typeof endSeq === 'number' ? Math.max(0, endSeq - data.length) : undefined
-  }
-
   function makePtyDataPayload(
     id: string,
     data: string,
     startSeq: number | undefined,
-    containsBackgroundOutput: boolean | undefined
+    containsBackgroundOutput: boolean | undefined,
+    rawLength = data.length,
+    transformed = false
   ): PtyDataPayload {
     const payload: PtyDataPayload = { id, data }
     if (typeof startSeq === 'number') {
-      payload.seq = startSeq + data.length
-      payload.rawLength = data.length
+      payload.seq = startSeq + rawLength
+    }
+    if (typeof startSeq === 'number' || rawLength !== data.length || transformed) {
+      payload.rawLength = rawLength
+    }
+    if (transformed) {
+      payload.transformed = true
     }
     if (containsBackgroundOutput === true) {
       payload.background = true
@@ -2362,7 +2356,9 @@ export function registerPtyHandlers(
     data: string,
     startSeq: number | undefined,
     preservesSeq: boolean,
-    containsBackgroundOutput: boolean
+    containsBackgroundOutput: boolean,
+    rawLength = data.length,
+    transformed = false
   ): PendingPtyData {
     // Why: once over the cap, stay dropped at O(1) memory until the renderer
     // can receive again — the restore sentinel supersedes any interim bytes.
@@ -2377,21 +2373,21 @@ export function registerPtyHandlers(
     }
     const nextContainsBackgroundOutput =
       existing?.containsBackgroundOutput === true || containsBackgroundOutput
-    if (!preservesSeq) {
-      return dropOversizedPendingPtyData(id, {
-        data: (existing?.data ?? '') + data,
-        ...(nextContainsBackgroundOutput ? { containsBackgroundOutput: true } : {})
-      })
-    }
     if (!existing) {
       return dropOversizedPendingPtyData(id, {
         data,
         ...(typeof startSeq === 'number' ? { startSeq } : {}),
+        ...(rawLength !== data.length ? { rawLength } : {}),
+        ...(transformed ? { transformed: true } : {}),
         ...(nextContainsBackgroundOutput ? { containsBackgroundOutput: true } : {})
       })
     }
+    const existingRawLength = existing.rawLength ?? existing.data.length
     const next: PendingPtyData = {
       data: existing.data + data,
+      ...(!preservesSeq || existing.transformed || transformed
+        ? { rawLength: existingRawLength + rawLength, transformed: true as const }
+        : {}),
       ...(nextContainsBackgroundOutput ? { containsBackgroundOutput: true } : {})
     }
     if (typeof existing.startSeq === 'number') {
@@ -2490,8 +2486,9 @@ export function registerPtyHandlers(
         continue
       }
       const { data } = pending
-      const chunk = data.slice(0, PTY_BATCH_FLUSH_CHUNK_CHARS)
-      const remaining = data.slice(PTY_BATCH_FLUSH_CHUNK_CHARS)
+      const indivisible = pending.transformed === true
+      const chunk = indivisible ? data : data.slice(0, PTY_BATCH_FLUSH_CHUNK_CHARS)
+      const remaining = indivisible ? '' : data.slice(PTY_BATCH_FLUSH_CHUNK_CHARS)
       if (remaining) {
         const nextPending: PendingPtyData = { data: remaining }
         if (typeof pending.startSeq === 'number') {
@@ -2507,7 +2504,14 @@ export function registerPtyHandlers(
       updateProducerFlowControl(id)
       sendPtyDataToRenderer(
         id,
-        makePtyDataPayload(id, chunk, pending.startSeq, pending.containsBackgroundOutput)
+        makePtyDataPayload(
+          id,
+          chunk,
+          pending.startSeq,
+          pending.containsBackgroundOutput,
+          pending.rawLength,
+          pending.transformed
+        )
       )
       writes++
     }
@@ -2580,7 +2584,9 @@ export function registerPtyHandlers(
             payload.id,
             remaining.data,
             remaining.startSeq,
-            remaining.containsBackgroundOutput
+            remaining.containsBackgroundOutput,
+            remaining.rawLength,
+            remaining.transformed
           )
         )
       }
@@ -2668,19 +2674,14 @@ export function registerPtyHandlers(
     const isLocalProvider = localProvider instanceof LocalPtyProvider
 
     localDataUnsub = localProvider.onData((payload) => {
+      const rawLength = payload.sequenceChars ?? payload.data.length
       const outputSeq = isLocalProvider
         ? runtime?.getPtyOutputSequence(payload.id)
-        : runtime?.onPtyData(
-            payload.id,
-            payload.data,
-            Date.now(),
-            payload.sequenceChars ?? payload.data.length
-          )
-      const rendererData = answerStartupTerminalColorQueriesForPty(payload.id, payload.data)
-      const preservesSeq =
-        rendererData === payload.data &&
-        (payload.sequenceChars === undefined || payload.sequenceChars === payload.data.length)
-      const startSeq = preservesSeq ? getChunkStartSeq(outputSeq, payload.data) : undefined
+        : runtime?.onPtyData(payload.id, payload.data, Date.now(), rawLength, payload.transformed)
+      const rendererData = payload.data
+      const preservesSeq = !payload.transformed && rawLength === payload.data.length
+      const startSeq =
+        typeof outputSeq === 'number' ? Math.max(0, outputSeq - rawLength) : undefined
       if (mainWindow.isDestroyed()) {
         // Why: clear the pending flush timer so it doesn't fire after the window
         // is gone. Without this, macOS app re-activation leaks orphaned timers
@@ -2713,7 +2714,7 @@ export function registerPtyHandlers(
         }
         return
       }
-      if (rendererData.length === 0) {
+      if (rendererData.length === 0 && !payload.transformed) {
         return
       }
       const containsBackgroundOutput =
@@ -2728,7 +2729,9 @@ export function registerPtyHandlers(
         rendererData,
         startSeq,
         preservesSeq,
-        containsBackgroundOutput
+        containsBackgroundOutput,
+        rawLength,
+        payload.transformed === true
       )
       const nextData = pending.data
       const isInteractiveOutput = shouldSendInteractiveOutputNow(
@@ -2760,8 +2763,12 @@ export function registerPtyHandlers(
           id: payload.id,
           data: nextData,
           ...(typeof pending.startSeq === 'number'
-            ? { seq: pending.startSeq + nextData.length, rawLength: nextData.length }
+            ? {
+                seq: pending.startSeq + (pending.rawLength ?? nextData.length),
+                rawLength: pending.rawLength ?? nextData.length
+              }
             : {}),
+          ...(pending.transformed ? { transformed: true } : {}),
           ...(pending.containsBackgroundOutput === true ? { background: true } : {}),
           ...(pending.droppedOutput === true ? { droppedOutput: true } : {})
         })
@@ -3904,10 +3911,6 @@ export function registerPtyHandlers(
           })?.distro ?? null)
         : null
       const startupTerminalColorQueryReplyColors = getStartupTerminalColorQueryReplyColors(args)
-      const preSpawnStartupTerminalColorReplyPtyId =
-        startupTerminalColorQueryReplyColors && effectiveSessionId !== undefined
-          ? (effectiveSessionAppId ?? effectiveSessionId)
-          : null
       // Why: the renderer sets pane env for SSH too. Only forward it to the
       // remote when the relay hook path is enabled; otherwise a newer relay
       // could emit statuses this Orca build is not prepared to route.
@@ -4015,6 +4018,11 @@ export function registerPtyHandlers(
       const validatedLeafId = verifiedLeafId ?? metadataLeafId
       let env: Record<string, string> | undefined = baseEnv
       const effectiveShellOverride = terminalRuntimeOptions.shellOverride
+      const nativeWindowsConptySpawn = isNativeWindowsLocalPtySpawn({
+        connectionId: args.connectionId,
+        cwd: args.cwd,
+        shellOverride: effectiveShellOverride
+      })
       const codexSelectionTarget = getCodexSelectionTargetForPty(
         effectiveShellOverride,
         cwd,
@@ -4169,6 +4177,15 @@ export function registerPtyHandlers(
           ? (getSettings()?.terminalWindowsPowerShellImplementation ?? 'auto')
           : undefined
       }
+      if (startupTerminalColorQueryReplyColors) {
+        spawnOptions.startupIngress = {
+          colors: startupTerminalColorQueryReplyColors,
+          deadlineMs: 5_000,
+          ...(nativeWindowsConptySpawn
+            ? { echoProjection: 'windows-conpty-esc-stripped' as const }
+            : {})
+        }
+      }
       const existingPaneSpawn = reservationPaneKey
         ? paneSpawnReservationsByPaneKey.get(reservationPaneKey)
         : undefined
@@ -4202,14 +4219,6 @@ export function registerPtyHandlers(
           if (preAllocatedHandle) {
             trustedTerminalHandleEnv.add(preAllocatedHandle)
           }
-          if (preSpawnStartupTerminalColorReplyPtyId && startupTerminalColorQueryReplyColors) {
-            // Why: Codex probes OSC 10/11 with a 100 ms timeout and daemon PTYs
-            // can emit that query before spawn() resolves to the renderer.
-            registerStartupTerminalColorQueryReplies(
-              preSpawnStartupTerminalColorReplyPtyId,
-              startupTerminalColorQueryReplyColors
-            )
-          }
           spawnTiming.mark('options')
           const expectedPtyId = effectiveSessionAppId ?? effectiveSessionId
           if (isDaemonHostSpawn && expectedPtyId) {
@@ -4254,9 +4263,6 @@ export function registerPtyHandlers(
           const spawnError = normalizeNodePtySpawnError(err)
           const isIdentityMismatch =
             isSshPtyIdentityMismatchError(spawnError) || isSshPtyIdentityMismatchError(rawMessage)
-          if (preSpawnStartupTerminalColorReplyPtyId) {
-            clearStartupTerminalColorQueryReplies(preSpawnStartupTerminalColorReplyPtyId)
-          }
           if (effectiveSessionAppId !== undefined) {
             if (isIdentityMismatch && hadSessionSizeBeforeAttach && sessionSizeBeforeAttach) {
               ptySizes.set(effectiveSessionAppId, sessionSizeBeforeAttach)
@@ -4337,33 +4343,14 @@ export function registerPtyHandlers(
           // ownership, and a hidden-spawned agent should be paceable from its
           // first flood, not from its first visibility transition.
           syncPtyBackgroundedDelivery(result.id, 'spawn')
+          closeStartupQueryAuthorityForPty(result.id)
         }
         // Why: Phase-5 ConPTY DA1 — record the native-Windows-local-PTY
         // determination from the spawn record before the headless seed below,
         // so the runtime emulator's DA1 override exists from byte zero.
-        if (
-          isNativeWindowsLocalPtySpawn({
-            connectionId: args.connectionId,
-            cwd: args.cwd,
-            shellOverride: effectiveShellOverride
-          })
-        ) {
+        if (nativeWindowsConptySpawn) {
           markNativeWindowsConptyPty(result.id)
         }
-        if (startupTerminalColorQueryReplyColors) {
-          if (result.isReattach) {
-            if (preSpawnStartupTerminalColorReplyPtyId) {
-              clearStartupTerminalColorQueryReplies(preSpawnStartupTerminalColorReplyPtyId)
-            }
-          } else if (preSpawnStartupTerminalColorReplyPtyId) {
-            moveStartupTerminalColorQueryReplies(preSpawnStartupTerminalColorReplyPtyId, result.id)
-          } else {
-            registerStartupTerminalColorQueryReplies(
-              result.id,
-              startupTerminalColorQueryReplyColors
-            )
-          }
-        }
         const relayResultId = getRelayPtyId(args.connectionId, result.id)
         if (store && args.connectionId) {
           // Why: remote PTYs live in the SSH relay grace window after Orca
@@ -5085,6 +5072,7 @@ export function registerPtyHandlers(
     rendererVisibilityKnownPtys.add(args.id)
     if (args.visible) {
       visibleRendererPtys.add(args.id)
+      closeStartupQueryAuthorityForPty(args.id)
     } else {
       visibleRendererPtys.delete(args.id)
     }
@@ -5101,6 +5089,7 @@ export function registerPtyHandlers(
     })
     if (args.hidden === true) {
       markHiddenRendererPty(args.id)
+      closeStartupQueryAuthorityForPty(args.id)
       // Why: bytes already queued for a newly hidden PTY are model-owned
       // state; drop them now instead of holding them under ACK starvation.
       // Reveal restores from the snapshot.
diff --git a/src/main/ipc/ssh.test.ts b/src/main/ipc/ssh.test.ts
index c925f592aa2..cbca2db9d2a 100644
--- a/src/main/ipc/ssh.test.ts
+++ b/src/main/ipc/ssh.test.ts
@@ -161,7 +161,6 @@ vi.mock('./pty', () => ({
   clearProviderPtyState: vi.fn(),
   deletePtyOwnership: vi.fn(),
   setPtyOwnership: vi.fn(),
-  answerStartupTerminalColorQueriesForPty: vi.fn((_id: string, data: string) => data),
   getSshPtyProvider: vi.fn(),
   getPtyIdsForConnection: vi.fn().mockReturnValue([]),
   isRendererPtyOutputPaused: vi.fn().mockReturnValue(false)
@@ -809,7 +808,13 @@ describe('SSH IPC handlers', () => {
     onData?.({ id: 'remote-pty', data: 'hello' })
     onExit?.({ id: 'remote-pty', code: 7 })
 
-    expect(runtime.onPtyData).toHaveBeenCalledWith('remote-pty', 'hello', expect.any(Number))
+    expect(runtime.onPtyData).toHaveBeenCalledWith(
+      'remote-pty',
+      'hello',
+      expect.any(Number),
+      'hello'.length,
+      undefined
+    )
     expect(runtime.onPtyExit).toHaveBeenCalledWith('remote-pty', 7)
   })
 
@@ -1180,7 +1185,13 @@ describe('SSH IPC handlers', () => {
       targetId: 'ssh-1',
       ports: expect.arrayContaining([expect.objectContaining({ port: 3000 })])
     })
-    expect(secondRuntime.onPtyData).toHaveBeenCalledWith('remote-pty', 'hello', expect.any(Number))
+    expect(secondRuntime.onPtyData).toHaveBeenCalledWith(
+      'remote-pty',
+      'hello',
+      expect.any(Number),
+      'hello'.length,
+      undefined
+    )
     expect(secondRuntime.onPtyExit).toHaveBeenCalledWith('remote-pty', 9)
     expect(firstRuntime.onPtyData).not.toHaveBeenCalled()
     expect(firstRuntime.onPtyExit).not.toHaveBeenCalled()
diff --git a/src/main/ipc/terminal-startup-color-query-replies.ts b/src/main/ipc/terminal-startup-color-query-replies.ts
index 5bcee8208bb..6d6b8ebff42 100644
--- a/src/main/ipc/terminal-startup-color-query-replies.ts
+++ b/src/main/ipc/terminal-startup-color-query-replies.ts
@@ -3,71 +3,10 @@ import { isTuiAgent } from '../../shared/tui-agent-config'
 import { agentKindSchema } from '../../shared/telemetry-events'
 import type { SleepingAgentLaunchConfig } from '../../shared/agent-session-resume'
 import {
-  parseTerminalOscColorQuery,
-  terminalOscColorQueryReplies,
   terminalOscColorQueryReply,
-  type TerminalOscColorQueryReplyColors,
-  type TerminalOscColorQuerySlot
+  type TerminalOscColorQueryReplyColors
 } from '../../shared/terminal-osc-color-reply'
 
-type StartupTerminalColorQueryProvider = {
-  write(id: string, data: string): void
-}
-
-type StartupTerminalColorQueryReplyState = {
-  colors: TerminalOscColorQueryReplyColors
-  pending: string
-  answeredSlots: Set<TerminalOscColorQuerySlot>
-  timeout: ReturnType<typeof setTimeout>
-}
-
-const STARTUP_TERMINAL_COLOR_QUERY_REPLY_WINDOW_MS = 5_000
-const STARTUP_TERMINAL_COLOR_QUERY_PENDING_CHARS = 64
-const startupTerminalColorQueryRepliesByPty = new Map<string, StartupTerminalColorQueryReplyState>()
-
-export function clearStartupTerminalColorQueryReplies(ptyId: string): void {
-  const state = startupTerminalColorQueryRepliesByPty.get(ptyId)
-  if (!state) {
-    return
-  }
-  clearTimeout(state.timeout)
-  startupTerminalColorQueryRepliesByPty.delete(ptyId)
-}
-
-export function moveStartupTerminalColorQueryReplies(fromPtyId: string, toPtyId: string): void {
-  if (fromPtyId === toPtyId) {
-    return
-  }
-  const state = startupTerminalColorQueryRepliesByPty.get(fromPtyId)
-  if (!state) {
-    return
-  }
-  startupTerminalColorQueryRepliesByPty.delete(fromPtyId)
-  clearStartupTerminalColorQueryReplies(toPtyId)
-  startupTerminalColorQueryRepliesByPty.set(toPtyId, state)
-}
-
-export function registerStartupTerminalColorQueryReplies(
-  ptyId: string,
-  colors: TerminalOscColorQueryReplyColors
-): void {
-  if (!terminalOscColorQueryReply(colors, 10) || !terminalOscColorQueryReply(colors, 11)) {
-    return
-  }
-  clearStartupTerminalColorQueryReplies(ptyId)
-  const timeout = setTimeout(
-    () => clearStartupTerminalColorQueryReplies(ptyId),
-    STARTUP_TERMINAL_COLOR_QUERY_REPLY_WINDOW_MS
-  )
-  timeout.unref?.()
-  startupTerminalColorQueryRepliesByPty.set(ptyId, {
-    colors,
-    pending: '',
-    answeredSlots: new Set(),
-    timeout
-  })
-}
-
 function normalizeTerminalColorQueryReplyColors(
   value: unknown
 ): TerminalOscColorQueryReplyColors | null {
@@ -117,81 +56,3 @@ export function getStartupTerminalColorQueryReplyColors(args: {
   }
   return normalizeTerminalColorQueryReplyColors(args.terminalColorQueryReplies)
 }
-
-function writeStartupTerminalColorQueryReplies(
-  ptyId: string,
-  slots: readonly TerminalOscColorQuerySlot[],
-  state: StartupTerminalColorQueryReplyState,
-  getProvider: (ptyId: string) => StartupTerminalColorQueryProvider | undefined
-): boolean {
-  const replies = terminalOscColorQueryReplies(state.colors, slots)
-  let provider: StartupTerminalColorQueryProvider | undefined
-  try {
-    provider = replies ? getProvider(ptyId) : undefined
-  } catch {
-    provider = undefined
-  }
-  if (!replies || !provider) {
-    return false
-  }
-  try {
-    for (const [index, reply] of replies.entries()) {
-      const slot = slots[index]
-      if (slot === undefined) {
-        return false
-      }
-      provider.write(ptyId, reply)
-      state.answeredSlots.add(slot)
-    }
-    return true
-  } catch {
-    return false
-  }
-}
-
-export function answerStartupTerminalColorQueries(
-  ptyId: string,
-  data: string,
-  getProvider: (ptyId: string) => StartupTerminalColorQueryProvider | undefined
-): string {
-  const state = startupTerminalColorQueryRepliesByPty.get(ptyId)
-  if (!state || data.length === 0) {
-    return data
-  }
-  const input = state.pending + data
-  let pending = ''
-  let output = ''
-  let offset = 0
-  while (offset < input.length) {
-    const candidateIndex = input.indexOf('\x1b', offset)
-    if (candidateIndex === -1) {
-      output += input.slice(offset)
-      break
-    }
-    output += input.slice(offset, candidateIndex)
-    const query = parseTerminalOscColorQuery(input, candidateIndex)
-    if (query.kind === 'none') {
-      output += input[candidateIndex]
-      offset = candidateIndex + 1
-      continue
-    }
-    if (query.kind === 'partial') {
-      const candidate = input.slice(candidateIndex)
-      if (candidate.length <= STARTUP_TERMINAL_COLOR_QUERY_PENDING_CHARS) {
-        pending = candidate
-      } else {
-        output += candidate
-      }
-      break
-    }
-    if (!writeStartupTerminalColorQueryReplies(ptyId, query.slots, state, getProvider)) {
-      output += input.slice(candidateIndex, query.endIndex)
-    }
-    offset = query.endIndex
-  }
-  state.pending = pending
-  if (state.answeredSlots.has(10) && state.answeredSlots.has(11)) {
-    clearStartupTerminalColorQueryReplies(ptyId)
-  }
-  return output
-}
diff --git a/src/main/providers/local-pty-provider.test.ts b/src/main/providers/local-pty-provider.test.ts
index fcd6235b101..3eaa8c557d6 100644
--- a/src/main/providers/local-pty-provider.test.ts
+++ b/src/main/providers/local-pty-provider.test.ts
@@ -1582,6 +1582,47 @@ describe('LocalPtyProvider', () => {
       expect(dataHandler).toHaveBeenCalledWith({ id, data: 'hello world' })
     })
 
+    it('classifies startup queries before runtime and public data listeners', async () => {
+      const runtimeData = vi.fn()
+      const dataHandler = vi.fn()
+      provider.configure({ onData: runtimeData })
+      provider.onData(dataHandler)
+      const { id } = await provider.spawn({
+        cols: 80,
+        rows: 24,
+        startupIngress: {
+          colors: { foreground: '#2e3434', background: '#ffffff' },
+          deadlineMs: 5_000,
+          echoProjection: 'windows-conpty-esc-stripped'
+        }
+      })
+      const onDataCb = mockProc.onData.mock.calls[0][0]
+      const query = '\x1b]10;?\x07'
+      const echo = ']10;rgb:2e2e/3434/3434\\'
+
+      onDataCb(query)
+      onDataCb(echo)
+      onDataCb('prompt')
+
+      expect(mockProc.write).toHaveBeenCalledWith('\x1b]10;rgb:2e2e/3434/3434\x1b\\')
+      expect(runtimeData.mock.calls.map((call) => call.slice(1))).toEqual([
+        ['', expect.any(Number), query.length, true],
+        ['', expect.any(Number), echo.length, true],
+        ['prompt', expect.any(Number)]
+      ])
+      expect(dataHandler.mock.calls.map(([payload]) => payload)).toEqual([
+        { id, data: '', sequenceChars: query.length, seq: query.length, transformed: true },
+        {
+          id,
+          data: '',
+          sequenceChars: echo.length,
+          seq: query.length + echo.length,
+          transformed: true
+        },
+        { id, data: 'prompt' }
+      ])
+    })
+
     it('notifies exit listeners when PTY exits', async () => {
       const exitHandler = vi.fn()
       provider.onExit(exitHandler)
diff --git a/src/main/providers/local-pty-provider.ts b/src/main/providers/local-pty-provider.ts
index 28c5586152c..4cc456bd799 100644
--- a/src/main/providers/local-pty-provider.ts
+++ b/src/main/providers/local-pty-provider.ts
@@ -68,6 +68,7 @@ import { assertSafeAgentStartupCwd, resolveSafePtyDefaultCwd } from './pty-defau
 import { ORCA_HERMES_STARTUP_QUERY_ENV } from '../../shared/hermes-startup-query'
 import { PhysicalExitTracker } from '../../shared/physical-exit-tracker'
 import { mergeGitConfigEnvProtocol } from '../../shared/git-credential-prompt-env'
+import { PtyStartupIngress, type PtyIngressEmission } from '../../shared/pty-startup-ingress'
 
 const PANE_IDENTITY_ENV_KEYS = [
   'ORCA_PANE_KEY',
@@ -122,11 +123,18 @@ export const LOCAL_PTY_FORCE_KILL_RETRY_MS = 250
 let loadGeneration = 0
 const ptyLoadGeneration = new Map<string, number>()
 
-type DataCallback = (payload: { id: string; data: string }) => void
+type DataCallback = (payload: {
+  id: string
+  data: string
+  sequenceChars?: number
+  transformed?: boolean
+  seq?: number
+}) => void
 type ExitCallback = (payload: { id: string; code: number }) => void
 
 const dataListeners = new Set<DataCallback>()
 const exitListeners = new Set<ExitCallback>()
+const startupIngressByPty = new Map<string, PtyStartupIngress>()
 
 /**
  * Returns a stable default cwd for locally spawned PTYs.
@@ -492,7 +500,13 @@ export type LocalPtyProviderOptions = {
   pwshAvailable?: () => boolean
   onSpawned?: (id: string) => void
   onExit?: (id: string, code: number) => void
-  onData?: (id: string, data: string, timestamp: number) => void
+  onData?: (
+    id: string,
+    data: string,
+    timestamp: number,
+    sequenceChars?: number,
+    transformed?: boolean
+  ) => void
 }
 
 export class LocalPtyProvider implements IPtyProvider {
@@ -907,6 +921,34 @@ export class LocalPtyProvider implements IPtyProvider {
     ptyLoadGeneration.set(id, loadGeneration)
     this.opts.onSpawned?.(id)
 
+    const emitIngressData = (emission: PtyIngressEmission): void => {
+      const sequenceChars = emission.rawEndSeq - emission.rawStartSeq
+      if (emission.transformed || sequenceChars !== emission.data.length) {
+        this.opts.onData?.(id, emission.data, Date.now(), sequenceChars, true)
+      } else {
+        this.opts.onData?.(id, emission.data, Date.now())
+      }
+      for (const cb of dataListeners) {
+        cb(
+          emission.transformed || sequenceChars !== emission.data.length
+            ? {
+                id,
+                data: emission.data,
+                sequenceChars,
+                seq: emission.rawEndSeq,
+                transformed: true
+              }
+            : { id, data: emission.data }
+        )
+      }
+    }
+    const startupIngress = new PtyStartupIngress({
+      ...(args.startupIngress ? { intent: args.startupIngress } : {}),
+      write: (data) => proc.write(data),
+      onEmission: emitIngressData
+    })
+    startupIngressByPty.set(id, startupIngress)
+
     // Shell-ready startup command support
     let resolveShellReady: ((signal: ShellReadySignal) => void) | null = null
     let shellReadyTimeout: ReturnType<typeof setTimeout> | null = null
@@ -938,10 +980,7 @@ export class LocalPtyProvider implements IPtyProvider {
       if (heldBytes.length === 0) {
         return
       }
-      this.opts.onData?.(id, heldBytes, Date.now())
-      for (const cb of dataListeners) {
-        cb({ id, data: heldBytes })
-      }
+      startupIngress.accept(heldBytes)
     }
     if (args.command) {
       if (shellReadyLaunch?.supportsReadyMarker) {
@@ -977,13 +1016,7 @@ export class LocalPtyProvider implements IPtyProvider {
           finishShellReady({ postMarkerBytesObserved: scanned.postMarkerBytesObserved })
         }
       }
-      if (data.length === 0) {
-        return
-      }
-      this.opts.onData?.(id, data, Date.now())
-      for (const cb of dataListeners) {
-        cb({ id, data })
-      }
+      startupIngress.accept(data)
     })
     if (onDataDisposable) {
       disposables.push(onDataDisposable)
@@ -1010,6 +1043,8 @@ export class LocalPtyProvider implements IPtyProvider {
       }
       startupCommandCleanup?.()
       clearPtyState(id)
+      startupIngress.drainAndClose()
+      startupIngressByPty.delete(id)
       // Why: release the master ptmx fd on the natural-exit path — without
       // this, a shell that exits cleanly (the common case) never releases its
       // fd until the next GC. See docs/fix-pty-fd-leak.md.
@@ -1223,11 +1258,15 @@ export class LocalPtyProvider implements IPtyProvider {
     // only safe at an empty prompt, and without a headless emulator this
     // provider cannot tell whether input is pending.
     try {
+      startupIngressByPty.get(id)?.snapshotBarrier()
       ptyProcesses.get(id)?.clear()
     } catch {
       /* PTY may have just exited */
     }
   }
+  closeStartupQueryAuthority(id: string): number {
+    return startupIngressByPty.get(id)?.closeQueryAuthority() ?? 0
+  }
   acknowledgeDataEvent(_id: string, _charCount: number): void {
     /* no flow control for local */
   }
diff --git a/src/main/providers/pty-provider-events.ts b/src/main/providers/pty-provider-events.ts
new file mode 100644
index 00000000000..6de435cb23f
--- /dev/null
+++ b/src/main/providers/pty-provider-events.ts
@@ -0,0 +1,22 @@
+import type { TerminalGitHubPRLink } from '../../shared/terminal-github-pr-link-detector'
+
+export type PtyDataEvent = {
+  id: string
+  data: string
+  sequenceChars?: number
+  transformed?: boolean
+  seq?: number
+}
+
+/** Notification-bearing fact a thinning transport detected while it held
+ *  scan authority for a backgrounded PTY (see onBackgroundStreamEvent). */
+export type PtyTransientFact =
+  | { kind: 'bell' }
+  | { kind: 'command-finished'; exitCode: number | null }
+  | { kind: 'pr-link'; link: TerminalGitHubPRLink }
+  | { kind: '2031-subscribe' }
+
+export type PtyBackgroundStreamEvent =
+  | { id: string; kind: 'backgroundMarker'; background: boolean; scanSeedAnsi?: string }
+  | { id: string; kind: 'dataGap'; droppedChars: number; sequenceChars?: number }
+  | { id: string; kind: 'transientFact'; fact: PtyTransientFact }
diff --git a/src/main/providers/ssh-pty-provider.test.ts b/src/main/providers/ssh-pty-provider.test.ts
index 375aeb86b54..ccbc60edcee 100644
--- a/src/main/providers/ssh-pty-provider.test.ts
+++ b/src/main/providers/ssh-pty-provider.test.ts
@@ -49,6 +49,21 @@ describe('SshPtyProvider', () => {
       expect(result).toEqual({ id: scopedPty1 })
     })
 
+    it('gates fresh startup intent with the relay ingress capability version', async () => {
+      mux.request.mockResolvedValue({ id: 'pty-1' })
+      const startupIngress = {
+        colors: { foreground: '#eeeeee', background: '#111111' },
+        deadlineMs: 5_000
+      }
+
+      await provider.spawn({ cols: 80, rows: 24, startupIngress })
+
+      expect(mux.request).toHaveBeenCalledWith(
+        'pty.spawn',
+        expect.objectContaining({ startupIngressVersion: 1, startupIngress })
+      )
+    })
+
     it('passes cwd and env through', async () => {
       mux.request.mockResolvedValue({ id: 'pty-2' })
 
@@ -324,6 +339,26 @@ describe('SshPtyProvider', () => {
       })
     })
 
+    it('never sends fresh startup intent on relay reattach', async () => {
+      mux.request.mockResolvedValue({ replay: 'restored' })
+
+      await provider.spawn({
+        cols: 80,
+        rows: 24,
+        sessionId: scopedPty1,
+        startupIngress: {
+          colors: { foreground: '#eeeeee', background: '#111111' },
+          deadlineMs: 5_000
+        }
+      })
+
+      expect(mux.request).toHaveBeenCalledWith(
+        'pty.attach',
+        expect.not.objectContaining({ startupIngress: expect.anything() })
+      )
+      expect(mux.request).not.toHaveBeenCalledWith('pty.spawn', expect.anything())
+    })
+
     it('reattaches scoped app ids using raw relay ids', async () => {
       mux.request.mockResolvedValue({ replay: 'buffered-output' })
 
@@ -531,6 +566,28 @@ describe('SshPtyProvider', () => {
       expect(handler).toHaveBeenCalledWith({ id: scopedPty1, data: 'output' })
     })
 
+    it('forwards empty transformed relay spans without reinterpreting them', () => {
+      const handler = vi.fn()
+      provider.onData(handler)
+      const notifHandler = mux.onNotification.mock.calls[0][0]
+
+      notifHandler('pty.data', {
+        id: 'pty-1',
+        data: '',
+        rawLength: 9,
+        seq: 9,
+        transformed: true
+      })
+
+      expect(handler).toHaveBeenCalledWith({
+        id: scopedPty1,
+        data: '',
+        sequenceChars: 9,
+        seq: 9,
+        transformed: true
+      })
+    })
+
     it('forwards pty.replay notifications to replay listeners', () => {
       const handler = vi.fn()
       provider.onReplay(handler)
diff --git a/src/main/providers/ssh-pty-provider.ts b/src/main/providers/ssh-pty-provider.ts
index bdc81787996..1182104cefa 100644
--- a/src/main/providers/ssh-pty-provider.ts
+++ b/src/main/providers/ssh-pty-provider.ts
@@ -2,8 +2,15 @@ import type { SshChannelMultiplexer } from '../ssh/ssh-channel-multiplexer'
 import type { IPtyProvider, PtyProcessInfo, PtySpawnOptions, PtySpawnResult } from './types'
 import { toAppSshPtyId, toRelaySshPtyId } from './ssh-pty-id'
 import { seedPowerlevel10kWizardEnv } from '../pty/powerlevel10k-wizard-env'
+import { PTY_STARTUP_INGRESS_VERSION } from '../../shared/pty-startup-ingress'
 
-type DataCallback = (payload: { id: string; data: string }) => void
+type DataCallback = (payload: {
+  id: string
+  data: string
+  sequenceChars?: number
+  transformed?: boolean
+  seq?: number
+}) => void
 type ReplayCallback = (payload: { id: string; data: string }) => void
 type ExitCallback = (payload: { id: string; code: number }) => void
 type RemoteCliBridgeEnv = {
@@ -56,7 +63,15 @@ export class SshPtyProvider implements IPtyProvider {
       switch (method) {
         case 'pty.data':
           for (const cb of this.dataListeners) {
-            cb({ id: this.toAppPtyId(params.id as string), data: params.data as string })
+            cb({
+              id: this.toAppPtyId(params.id as string),
+              data: params.data as string,
+              ...(typeof params.rawLength === 'number'
+                ? { sequenceChars: params.rawLength as number }
+                : {}),
+              ...(params.transformed === true ? { transformed: true } : {}),
+              ...(typeof params.seq === 'number' ? { seq: params.seq as number } : {})
+            })
           }
           break
 
@@ -167,7 +182,13 @@ export class SshPtyProvider implements IPtyProvider {
       // remote hooks are disabled, but the relay still needs attach identity
       // metadata to reject cross-generation PTY id collisions.
       ...(opts.paneKey ? { paneKey: opts.paneKey } : {}),
-      ...(opts.tabId ? { tabId: opts.tabId } : {})
+      ...(opts.tabId ? { tabId: opts.tabId } : {}),
+      ...(opts.startupIngress
+        ? {
+            startupIngressVersion: PTY_STARTUP_INGRESS_VERSION,
+            startupIngress: opts.startupIngress
+          }
+        : {})
     })
     return {
       ...(result as PtySpawnResult),
@@ -261,6 +282,13 @@ export class SshPtyProvider implements IPtyProvider {
     await this.mux.request('pty.clearBuffer', { id: this.toRelayPtyId(id) })
   }
 
+  async closeStartupQueryAuthority(id: string): Promise<number> {
+    const result = (await this.mux.request('pty.closeStartupQueryAuthority', {
+      id: this.toRelayPtyId(id)
+    })) as { appliedSeq?: number }
+    return result.appliedSeq ?? 0
+  }
+
   acknowledgeDataEvent(id: string, charCount: number): void {
     this.mux.notify('pty.ackData', { id: this.toRelayPtyId(id), charCount })
   }
diff --git a/src/main/providers/types.ts b/src/main/providers/types.ts
index 6941e4c3063..ea2ea2c57dc 100644
--- a/src/main/providers/types.ts
+++ b/src/main/providers/types.ts
@@ -18,29 +18,23 @@ import type {
   SearchResult
 } from '../../shared/types'
 import type { GitHistoryOptions, GitHistoryResult } from '../../shared/git-history'
+import type { PtyStartupIngressIntent } from '../../shared/pty-startup-ingress'
 import type { CommitMessageDraftContext } from '../../shared/commit-message-generation'
 import type { WorkspaceSpaceDirectoryScanResult } from '../../shared/workspace-space-types'
 import type { StartupCommandDelivery } from '../../shared/codex-startup-delivery'
 import type { TerminalOscLinkRange } from '../../shared/terminal-osc-link-ranges'
-import type { TerminalGitHubPRLink } from '../../shared/terminal-github-pr-link-detector'
 import type { GitProviderStatusOptions } from './git-provider-status-options'
+import type { PtyBackgroundStreamEvent, PtyDataEvent } from './pty-provider-events'
 import type { PtySpawnResult } from './pty-spawn-result'
 
+export type {
+  PtyBackgroundStreamEvent,
+  PtyDataEvent,
+  PtyTransientFact
+} from './pty-provider-events'
+
 // ─── PTY Provider ───────────────────────────────────────────────────
 
-/** Notification-bearing fact a thinning transport detected while it held
- *  scan authority for a backgrounded PTY (see onBackgroundStreamEvent). */
-export type PtyTransientFact =
-  | { kind: 'bell' }
-  | { kind: 'command-finished'; exitCode: number | null }
-  | { kind: 'pr-link'; link: TerminalGitHubPRLink }
-  | { kind: '2031-subscribe' }
-
-export type PtyBackgroundStreamEvent =
-  | { id: string; kind: 'backgroundMarker'; background: boolean; scanSeedAnsi?: string }
-  | { id: string; kind: 'dataGap'; droppedChars: number; sequenceChars?: number }
-  | { id: string; kind: 'transientFact'; fact: PtyTransientFact }
-
 export type PtyProviderBufferSnapshot = {
   data: string
   /** Authoritative normal buffer captured beside an alternate-screen frame. */
@@ -98,6 +92,8 @@ export type PtySpawnOptions = {
    *  through spawn options keeps local PTY and daemon PTY semantics aligned
    *  without promoting pwsh into a separate shell family. */
   terminalWindowsPowerShellImplementation?: 'auto' | 'powershell.exe' | 'pwsh.exe'
+  /** Fresh-spawn-only source authority installed before any PTY output is released. */
+  startupIngress?: PtyStartupIngressIntent
 }
 
 export type { PtySpawnResult }
@@ -170,6 +166,8 @@ export type IPtyProvider = {
   getCwd(id: string): Promise<string>
   getInitialCwd(id: string): Promise<string>
   clearBuffer(id: string): Promise<void>
+  /** Ordered handoff from startup source authority to the live/hidden view authority. */
+  closeStartupQueryAuthority?: (id: string) => Promise<number> | number
   acknowledgeDataEvent(id: string, charCount: number): void
   hasChildProcesses(id: string): Promise<boolean>
   getForegroundProcess(id: string): Promise<string | null>
@@ -180,9 +178,7 @@ export type IPtyProvider = {
   listProcesses(): Promise<PtyProcessInfo[]>
   getDefaultShell(): Promise<string>
   getProfiles(): Promise<{ name: string; path: string }[]>
-  onData(
-    callback: (payload: { id: string; data: string; sequenceChars?: number }) => void
-  ): () => void
+  onData(callback: (payload: PtyDataEvent) => void): () => void
   onReplay(callback: (payload: { id: string; data: string }) => void): () => void
   onExit(callback: (payload: { id: string; code: number }) => void): () => void
 }
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 9231beb040a..b5e2f0df995 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -2282,7 +2282,12 @@ export class OrcaRuntimeService {
   // 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; cwd?: string }) => void>
+    Set<
+      (
+        data: string,
+        meta?: { seq?: number; rawLength?: number; transformed?: boolean; cwd?: string }
+      ) => 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.
@@ -6064,7 +6069,13 @@ export class OrcaRuntimeService {
    * 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, sequenceChars = data.length): number {
+  onPtyData(
+    ptyId: string,
+    data: string,
+    at: number,
+    sequenceChars = data.length,
+    transformed = false
+  ): number {
     const outputSequence = (this.ptyOutputSequenceById.get(ptyId) ?? 0) + sequenceChars
     this.ptyOutputSequenceById.set(ptyId, outputSequence)
     this.providerModeTrackersByPtyId.get(ptyId)?.scan(data)
@@ -6282,7 +6293,8 @@ export class OrcaRuntimeService {
     if (listeners) {
       const meta = {
         seq: outputSequence,
-        rawLength: data.length,
+        rawLength: sequenceChars,
+        ...(transformed ? { transformed: true } : {}),
         ...(cwdChanged && cwd !== null ? { cwd } : {})
       }
       for (const listener of listeners) {
@@ -7133,7 +7145,10 @@ export class OrcaRuntimeService {
 
   subscribeToTerminalData(
     ptyId: string,
-    listener: (data: string, meta?: { seq?: number; rawLength?: number; cwd?: string }) => void
+    listener: (
+      data: string,
+      meta?: { seq?: number; rawLength?: number; transformed?: boolean; cwd?: string }
+    ) => void
   ): () => void {
     return addListenerToMap(this.dataListeners, ptyId, listener)
   }
diff --git a/src/main/runtime/rpc/methods/terminal.ts b/src/main/runtime/rpc/methods/terminal.ts
index b0983d5e06f..05c5045c50b 100644
--- a/src/main/runtime/rpc/methods/terminal.ts
+++ b/src/main/runtime/rpc/methods/terminal.ts
@@ -140,11 +140,17 @@ type TerminalOutputChunk = {
   meta?: TerminalOutputMeta
 }
 
-type TerminalOutputMeta = { seq?: number; rawLength?: number; cwd?: string }
+type TerminalOutputMeta = {
+  seq?: number
+  rawLength?: number
+  transformed?: boolean
+  cwd?: string
+}
 
 type TerminalOutputFrameChunk = {
   bytes: Uint8Array<ArrayBufferLike>
   seq?: number
+  opcode?: TerminalStreamOpcode
 }
 
 function createTerminalOutputBatcher(onFlush: (data: string, meta?: TerminalOutputMeta) => void): {
@@ -156,6 +162,7 @@ function createTerminalOutputBatcher(onFlush: (data: string, meta?: TerminalOutp
   let bytes = 0
   let lastSeq: number | undefined
   let pendingCwd: string | undefined
+  let pendingRawLength = 0
   let timer: ReturnType<typeof setTimeout> | null = null
 
   const clearTimer = (): void => {
@@ -168,14 +175,14 @@ function createTerminalOutputBatcher(onFlush: (data: string, meta?: TerminalOutp
 
   const flush = (): void => {
     clearTimer()
-    if (chunks.length === 0) {
+    if (chunks.length === 0 && pendingRawLength === 0) {
       return
     }
     const data = chunks.length === 1 ? chunks[0]! : chunks.join('')
     const meta =
       typeof lastSeq === 'number' || pendingCwd !== undefined
         ? {
-            ...(typeof lastSeq === 'number' ? { seq: lastSeq, rawLength: data.length } : {}),
+            ...(typeof lastSeq === 'number' ? { seq: lastSeq, rawLength: pendingRawLength } : {}),
             ...(pendingCwd !== undefined ? { cwd: pendingCwd } : {})
           }
         : undefined
@@ -183,12 +190,19 @@ function createTerminalOutputBatcher(onFlush: (data: string, meta?: TerminalOutp
     bytes = 0
     lastSeq = undefined
     pendingCwd = undefined
+    pendingRawLength = 0
     onFlush(data, meta)
   }
 
   return {
     push(data: string, meta?: TerminalOutputMeta): void {
-      if (!data) {
+      const rawLength = meta?.rawLength ?? data.length
+      if (!data && rawLength === 0) {
+        return
+      }
+      if (meta?.transformed || rawLength !== data.length) {
+        flush()
+        onFlush(data, { ...meta, rawLength, transformed: true })
         return
       }
       if (meta?.cwd !== undefined) {
@@ -196,6 +210,7 @@ function createTerminalOutputBatcher(onFlush: (data: string, meta?: TerminalOutp
         pendingCwd = meta.cwd
       }
       chunks.push(data)
+      pendingRawLength += rawLength
       const remainingBudget = Math.max(1, TERMINAL_OUTPUT_BATCH_MAX_BYTES - bytes)
       const measurement = measureTerminalStreamByteLength(data, {
         stopAfterBytes: remainingBudget
@@ -222,6 +237,7 @@ function createTerminalOutputBatcher(onFlush: (data: string, meta?: TerminalOutp
       clearTimer()
       chunks = []
       bytes = 0
+      pendingRawLength = 0
     }
   }
 }
@@ -230,11 +246,19 @@ function* iterateTerminalOutputFrameChunks(
   data: string,
   meta?: TerminalOutputMeta
 ): Generator<TerminalOutputFrameChunk> {
+  const rawLength = meta?.rawLength ?? data.length
+  if (meta?.transformed || rawLength !== data.length) {
+    yield {
+      opcode: TerminalStreamOpcode.OutputSpan,
+      bytes: encodeTerminalStreamJson({ data, rawLength, transformed: true }),
+      seq: meta?.seq
+    }
+    return
+  }
   if (!terminalStreamByteLengthExceeds(data, TERMINAL_STREAM_CHUNK_BYTES)) {
     yield { bytes: encodeTerminalStreamText(data), seq: meta?.seq }
     return
   }
-  const rawLength = meta?.rawLength ?? data.length
   const canPreserveChunkSeq = typeof meta?.seq === 'number' && rawLength === data.length
   const shouldDelayFinalSeq = !canPreserveChunkSeq && typeof meta?.seq === 'number'
   const startSeq = canPreserveChunkSeq ? meta.seq! - rawLength : undefined
@@ -1640,7 +1664,12 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         stream: TerminalMultiplexStream,
         chunk: TerminalOutputFrameChunk
       ): void => {
-        sendFrame(stream.streamId, TerminalStreamOpcode.Output, chunk.bytes, chunk.seq)
+        sendFrame(
+          stream.streamId,
+          chunk.opcode ?? TerminalStreamOpcode.Output,
+          chunk.bytes,
+          chunk.seq
+        )
         if (stream.ackOutput) {
           stream.ackInFlightBytes += chunk.bytes.byteLength
           ackTotalInFlightBytes += chunk.bytes.byteLength
@@ -2802,7 +2831,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           )
         }
         for (const chunk of iterateTerminalOutputFrameChunks(data, meta)) {
-          sendFrame(TerminalStreamOpcode.Output, chunk.bytes, chunk.seq)
+          sendFrame(chunk.opcode ?? TerminalStreamOpcode.Output, chunk.bytes, chunk.seq)
         }
       })
       unregisterBinaryHandler =
@@ -3199,6 +3228,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         if (!initialOutputOverflowed) {
           for (const item of bufferedOutput) {
             let uncoveredData = getOutputAfterSnapshotSeq(item, snapshotOutputSeq)
+            let uncoveredMeta = item.meta
             if (
               uncoveredData &&
               uncoveredData !== item.data &&
@@ -3206,6 +3236,9 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
               typeof item.meta?.seq === 'number' &&
               typeof item.meta.rawLength === 'number'
             ) {
+              if (item.meta.rawLength === item.data.length) {
+                uncoveredMeta = { ...item.meta, rawLength: uncoveredData.length }
+              }
               uncoveredData = stripSnapshotBoundaryQuerySuffixes(
                 uncoveredData,
                 snapshotOutputSeq,
@@ -3214,7 +3247,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
               )
             }
             if (uncoveredData) {
-              outputBatcher.push(uncoveredData, item.meta)
+              outputBatcher.push(uncoveredData, uncoveredMeta)
             }
           }
         }
diff --git a/src/main/ssh/ssh-relay-session-data-delivery.test.ts b/src/main/ssh/ssh-relay-session-data-delivery.test.ts
new file mode 100644
index 00000000000..901f7940d31
--- /dev/null
+++ b/src/main/ssh/ssh-relay-session-data-delivery.test.ts
@@ -0,0 +1,112 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { SshRelaySession } from './ssh-relay-session'
+import { createMockDeps, mockDeploySuccess } from './ssh-relay-session-test-fixtures'
+
+const { muxRequestMock } = vi.hoisted(() => ({ muxRequestMock: vi.fn() }))
+
+vi.mock('./ssh-relay-deploy', () => ({ deployAndLaunchRelay: vi.fn() }))
+
+vi.mock('./ssh-channel-multiplexer', () => ({
+  SshChannelMultiplexer: class MockSshChannelMultiplexer {
+    notify = vi.fn()
+    request = muxRequestMock
+    onNotification = vi.fn().mockReturnValue(() => {})
+    onRequest = vi.fn().mockReturnValue(() => {})
+    onDispose = vi.fn().mockReturnValue(() => {})
+    dispose = vi.fn()
+    isDisposed = vi.fn().mockReturnValue(false)
+  }
+}))
+
+vi.mock('../agent-hooks/remote-managed-hook-installers', () => ({
+  installRemoteManagedAgentHooks: vi.fn().mockResolvedValue([])
+}))
+
+vi.mock('../providers/ssh-pty-provider', () => ({
+  isSshPtyNotFoundError: vi.fn().mockReturnValue(false),
+  isSshPtyIdentityMismatchError: vi.fn().mockReturnValue(false),
+  SshPtyProvider: class MockSshPtyProvider {
+    onData = vi.fn().mockReturnValue(() => {})
+    onReplay = vi.fn().mockReturnValue(() => {})
+    onExit = vi.fn().mockReturnValue(() => {})
+    attach = vi.fn().mockResolvedValue(undefined)
+    attachForReconnect = vi.fn().mockResolvedValue({})
+    dispose = vi.fn()
+  }
+}))
+
+vi.mock('../providers/ssh-filesystem-provider', () => ({
+  SshFilesystemProvider: class MockSshFilesystemProvider {
+    dispose = vi.fn()
+  }
+}))
+
+vi.mock('../providers/ssh-git-provider', () => ({
+  SshGitProvider: class MockSshGitProvider {}
+}))
+
+vi.mock('../ipc/pty', () => ({
+  registerSshPtyProvider: vi.fn(),
+  unregisterSshPtyProvider: vi.fn(),
+  getSshPtyProvider: vi.fn().mockReturnValue({ dispose: vi.fn() }),
+  getPtyIdsForConnection: vi.fn().mockReturnValue([]),
+  clearPtyOwnershipForConnection: vi.fn(),
+  clearProviderPtyState: vi.fn(),
+  deletePtyOwnership: vi.fn(),
+  setPtyOwnership: vi.fn()
+}))
+
+vi.mock('../providers/ssh-filesystem-dispatch', () => ({
+  registerSshFilesystemProvider: vi.fn(),
+  unregisterSshFilesystemProvider: vi.fn(),
+  getSshFilesystemProvider: vi.fn().mockReturnValue({ dispose: vi.fn() })
+}))
+
+vi.mock('../providers/ssh-git-dispatch', () => ({
+  registerSshGitProvider: vi.fn(),
+  unregisterSshGitProvider: vi.fn()
+}))
+
+const { registerSshPtyProvider } = await import('../ipc/pty')
+
+describe('SshRelaySession data delivery', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    muxRequestMock.mockResolvedValue([])
+    mockDeploySuccess()
+  })
+
+  it('delivers empty transformed relay spans with raw sequence metadata', async () => {
+    const { mockConn, mockStore, mockPortForward, getMainWindow, mockWindow } = createMockDeps()
+    const runtime = { onPtyData: vi.fn(() => 17), onPtyExit: vi.fn() }
+    const session = new SshRelaySession(
+      'target-1',
+      getMainWindow,
+      mockStore,
+      mockPortForward,
+      runtime as never
+    )
+    await session.establish(mockConn)
+    const ptyProvider = vi.mocked(registerSshPtyProvider).mock.calls[0]?.[1] as unknown as {
+      onData: ReturnType<typeof vi.fn>
+    }
+    const onData = ptyProvider.onData.mock.calls[0]?.[0] as (payload: {
+      id: string
+      data: string
+      sequenceChars?: number
+      transformed?: boolean
+    }) => void
+
+    onData({ id: 'ssh-pty-1', data: '', sequenceChars: 9, transformed: true })
+
+    expect(runtime.onPtyData).toHaveBeenCalledWith('ssh-pty-1', '', expect.any(Number), 9, true)
+    expect(mockWindow.webContents.send).toHaveBeenCalledWith('pty:data', {
+      id: 'ssh-pty-1',
+      data: '',
+      sequenceChars: 9,
+      transformed: true,
+      seq: 17,
+      rawLength: 9
+    })
+  })
+})
diff --git a/src/main/ssh/ssh-relay-session-terminal-error.test.ts b/src/main/ssh/ssh-relay-session-terminal-error.test.ts
index 56d12ec9cef..ce9317c6660 100644
--- a/src/main/ssh/ssh-relay-session-terminal-error.test.ts
+++ b/src/main/ssh/ssh-relay-session-terminal-error.test.ts
@@ -65,8 +65,7 @@ vi.mock('../ipc/pty', () => ({
   clearPtyOwnershipForConnection: vi.fn(),
   clearProviderPtyState: vi.fn(),
   deletePtyOwnership: vi.fn(),
-  setPtyOwnership: vi.fn(),
-  answerStartupTerminalColorQueriesForPty: vi.fn((_id: string, data: string) => data)
+  setPtyOwnership: vi.fn()
 }))
 
 vi.mock('../providers/ssh-filesystem-dispatch', () => ({
diff --git a/src/main/ssh/ssh-relay-session.test.ts b/src/main/ssh/ssh-relay-session.test.ts
index da490ae7be0..55abd17b9c6 100644
--- a/src/main/ssh/ssh-relay-session.test.ts
+++ b/src/main/ssh/ssh-relay-session.test.ts
@@ -73,8 +73,7 @@ vi.mock('../ipc/pty', () => ({
   clearPtyOwnershipForConnection: vi.fn(),
   clearProviderPtyState: vi.fn(),
   deletePtyOwnership: vi.fn(),
-  setPtyOwnership: vi.fn(),
-  answerStartupTerminalColorQueriesForPty: vi.fn((_id: string, data: string) => data)
+  setPtyOwnership: vi.fn()
 }))
 
 vi.mock('../providers/ssh-filesystem-dispatch', () => ({
@@ -152,7 +151,9 @@ describe('SshRelaySession', () => {
     expect(runtime.onPtyData).toHaveBeenCalledWith(
       'ssh-pty-1',
       'hidden ssh output',
-      expect.any(Number)
+      expect.any(Number),
+      'hidden ssh output'.length,
+      undefined
     )
     expect(mockWindow.webContents.send).toHaveBeenCalledTimes(1)
     // Why out-of-band: an in-band empty pty:data sentinel is ambiguous with
@@ -207,7 +208,8 @@ describe('SshRelaySession', () => {
 
     expect(mockWindow.webContents.send).toHaveBeenCalledWith('pty:data', {
       id: 'ssh-pty-1',
-      data: 'still delivered'
+      data: 'still delivered',
+      rawLength: 'still delivered'.length
     })
   })
 
diff --git a/src/main/ssh/ssh-relay-session.ts b/src/main/ssh/ssh-relay-session.ts
index 969878c1220..b9c41c84c1d 100644
--- a/src/main/ssh/ssh-relay-session.ts
+++ b/src/main/ssh/ssh-relay-session.ts
@@ -41,8 +41,7 @@ import {
   clearPtyOwnershipForConnection,
   clearProviderPtyState,
   deletePtyOwnership,
-  setPtyOwnership,
-  answerStartupTerminalColorQueriesForPty
+  setPtyOwnership
 } from '../ipc/pty'
 import {
   recordHiddenRendererPtyDataDrop,
@@ -1120,8 +1119,14 @@ export class SshRelaySession {
 
   private wireUpPtyEvents(ptyProvider: SshPtyProvider): void {
     ptyProvider.onData((payload) => {
-      const seq = this.runtime?.onPtyData(payload.id, payload.data, Date.now())
-      const rendererData = answerStartupTerminalColorQueriesForPty(payload.id, payload.data)
+      const rawLength = payload.sequenceChars ?? payload.data.length
+      const seq = this.runtime?.onPtyData(
+        payload.id,
+        payload.data,
+        Date.now(),
+        rawLength,
+        payload.transformed
+      )
       const win = this.getMainWindow()
       if (!win || win.isDestroyed()) {
         return
@@ -1133,7 +1138,7 @@ export class SshRelaySession {
       // OSC-9999-only chunks legitimately strip to empty in the renderer.
       const store = this.store as { getSettings?: Store['getSettings'] }
       if (shouldDropHiddenRendererPtyData(payload.id, store.getSettings?.())) {
-        const drop = recordHiddenRendererPtyDataDrop(payload.id, payload.data.length)
+        const drop = recordHiddenRendererPtyDataDrop(payload.id, rawLength)
         if (drop.shouldEmitRestoreMarker) {
           win.webContents.send('pty:modelRestoreNeeded', {
             id: payload.id,
@@ -1143,16 +1148,12 @@ export class SshRelaySession {
         }
         return
       }
-      // Why: startup color-query answering can strip query-only chunks to
-      // empty; skip empty sends and only attach seq metadata when the chunk
-      // reaches the renderer unmodified (seq tracks raw stream offsets).
-      if (rendererData.length > 0) {
+      if (payload.data.length > 0 || payload.transformed) {
         win.webContents.send('pty:data', {
           ...payload,
-          data: rendererData,
-          ...(rendererData === payload.data && typeof seq === 'number'
-            ? { seq, rawLength: payload.data.length }
-            : {})
+          ...(typeof seq === 'number' ? { seq } : {}),
+          rawLength,
+          ...(payload.transformed ? { transformed: true } : {})
         })
       }
     })
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 3911de36f9d..487f7b2e0dd 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -1439,6 +1439,7 @@ export type PreloadApi = {
         data: string
         seq?: number
         rawLength?: number
+        transformed?: boolean
         background?: boolean
         droppedOutput?: boolean
       }) => void
diff --git a/src/preload/index.ts b/src/preload/index.ts
index dc8023b1e85..5571f9349b9 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -1061,6 +1061,7 @@ const api = {
         data: string
         seq?: number
         rawLength?: number
+        transformed?: boolean
         background?: boolean
         droppedOutput?: boolean
       }) => void
@@ -1072,6 +1073,7 @@ const api = {
           data: string
           seq?: number
           rawLength?: number
+          transformed?: boolean
           background?: boolean
           droppedOutput?: boolean
         }
diff --git a/src/relay/pty-handler.test.ts b/src/relay/pty-handler.test.ts
index 8de7ec8051b..0c0b33d9b94 100644
--- a/src/relay/pty-handler.test.ts
+++ b/src/relay/pty-handler.test.ts
@@ -10,6 +10,7 @@ import {
   resolveSetupAgentSequenceLaunchCommand,
   SETUP_AGENT_SEQUENCE_STARTUP_COMMAND_ENV
 } from '../shared/setup-agent-sequencing'
+import { PTY_STARTUP_INGRESS_VERSION } from '../shared/pty-startup-ingress'
 
 const { mockPtySpawn, mockPtyInstance } = vi.hoisted(() => ({
   mockPtySpawn: vi.fn(),
@@ -968,6 +969,72 @@ describe('PtyHandler', () => {
     expect(dispatcher.notify).toHaveBeenCalledWith('pty.data', { id: 'pty-1', data: 'hello world' })
   })
 
+  it('consumes capable startup queries before relay replay and fanout', async () => {
+    let dataCallback: ((data: string) => void) | undefined
+    const term = {
+      ...mockPtyInstance,
+      onData: vi.fn((cb: (data: string) => void) => {
+        dataCallback = cb
+      }),
+      onExit: vi.fn()
+    }
+    mockPtySpawn.mockReturnValue(term)
+    await dispatcher.callRequest('pty.spawn', {
+      startupIngressVersion: PTY_STARTUP_INGRESS_VERSION,
+      startupIngress: {
+        colors: { foreground: '#2e3434', background: '#ffffff' },
+        deadlineMs: 5_000
+      }
+    })
+
+    const query = '\x1b]10;?\x07'
+    dataCallback!(query)
+    dataCallback!('prompt')
+    vi.advanceTimersByTime(8)
+
+    expect(term.write).toHaveBeenCalledWith('\x1b]10;rgb:2e2e/3434/3434\x1b\\')
+    expect(dispatcher.notify).toHaveBeenCalledWith('pty.data', {
+      id: 'pty-1',
+      data: '',
+      rawLength: query.length,
+      seq: query.length,
+      transformed: true
+    })
+    expect(dispatcher.notify).toHaveBeenCalledWith('pty.data', { id: 'pty-1', data: 'prompt' })
+    await expect(
+      dispatcher.callRequest('pty.attach', {
+        id: 'pty-1',
+        suppressReplayNotification: true
+      })
+    ).resolves.toEqual({ replay: 'prompt' })
+  })
+
+  it('leaves startup queries untouched for an unsupported relay capability version', async () => {
+    let dataCallback: ((data: string) => void) | undefined
+    const term = {
+      ...mockPtyInstance,
+      onData: vi.fn((cb: (data: string) => void) => {
+        dataCallback = cb
+      }),
+      onExit: vi.fn()
+    }
+    mockPtySpawn.mockReturnValue(term)
+    await dispatcher.callRequest('pty.spawn', {
+      startupIngressVersion: PTY_STARTUP_INGRESS_VERSION - 1,
+      startupIngress: {
+        colors: { foreground: '#2e3434', background: '#ffffff' },
+        deadlineMs: 5_000
+      }
+    })
+
+    const query = '\x1b]10;?\x07'
+    dataCallback!(query)
+    vi.advanceTimersByTime(8)
+
+    expect(term.write).not.toHaveBeenCalled()
+    expect(dispatcher.notify).toHaveBeenCalledWith('pty.data', { id: 'pty-1', data: query })
+  })
+
   it('coalesces background PTY output before notifying the client', async () => {
     let dataCallback: ((data: string) => void) | undefined
     mockPtySpawn.mockReturnValue({
diff --git a/src/relay/pty-handler.ts b/src/relay/pty-handler.ts
index fb0d38bf53c..d06695342d0 100644
--- a/src/relay/pty-handler.ts
+++ b/src/relay/pty-handler.ts
@@ -39,6 +39,12 @@ import {
 } from '../shared/git-credential-prompt-env'
 import { isTuiAgent } from '../shared/tui-agent-config'
 import { forceKillPosixPtyProcessGroups } from '../main/pty/posix-pty-process-groups'
+import {
+  PTY_STARTUP_INGRESS_VERSION,
+  PtyStartupIngress,
+  parsePtyStartupIngressIntent,
+  type PtyIngressEmission
+} from '../shared/pty-startup-ingress'
 
 function isMissingNodePtyNativeBinding(error: unknown): boolean {
   return (
@@ -78,10 +84,15 @@ type ManagedPty = {
   physicalExit?: PhysicalExitTracker
   forceKillSent?: boolean
   gracefulKillSent?: boolean
+  startupIngress?: PtyStartupIngress
+  startupIngressIntent?: ReturnType<typeof parsePtyStartupIngressIntent>
 }
 
 type PendingPtyOutput = {
   data: string
+  rawLength?: number
+  transformed?: boolean
+  seq?: number
 }
 
 type ManagedStartupCommand = {
@@ -471,6 +482,9 @@ export class PtyHandler {
   }
 
   private appendReplayBuffer(managed: ManagedPty, data: string): void {
+    if (data.length === 0) {
+      return
+    }
     managed.buffered += data
     if (managed.buffered.length > REPLAY_BUFFER_MAX) {
       managed.buffered = managed.buffered.slice(-REPLAY_BUFFER_MAX)
@@ -504,8 +518,7 @@ export class PtyHandler {
     if (startup.scanState) {
       const heldBytes = drainShellReadyHeldBytes(startup.scanState)
       if (heldBytes) {
-        this.appendReplayBuffer(managed, heldBytes)
-        this.enqueuePtyOutput(managed.id, heldBytes)
+        managed.startupIngress?.accept(heldBytes)
       }
     }
     const submit = process.platform === 'win32' ? '\r' : '\n'
@@ -525,6 +538,22 @@ export class PtyHandler {
   private wireAndStore(managed: ManagedPty): void {
     managed.physicalExit = new PhysicalExitTracker()
     this.ptys.set(managed.id, managed)
+    const emitIngressData = (emission: PtyIngressEmission): void => {
+      const rawLength = emission.rawEndSeq - emission.rawStartSeq
+      this.appendReplayBuffer(managed, emission.data)
+      this.enqueuePtyOutput(
+        managed.id,
+        emission.data,
+        emission.transformed || rawLength !== emission.data.length
+          ? { rawLength, seq: emission.rawEndSeq, transformed: true }
+          : {}
+      )
+    }
+    managed.startupIngress ??= new PtyStartupIngress({
+      ...(managed.startupIngressIntent ? { intent: managed.startupIngressIntent } : {}),
+      write: (data) => managed.pty.write(data),
+      onEmission: emitIngressData
+    })
     managed.pty.onData((data: string) => {
       const startup = managed.startupCommand
       if (startup?.waitForShellReady && startup.scanState && !startup.delivered) {
@@ -534,8 +563,7 @@ export class PtyHandler {
           this.scheduleStartupCommandDelivery(managed, STARTUP_COMMAND_WRITE_DELAY_MS)
         }
       }
-      this.appendReplayBuffer(managed, data)
-      this.enqueuePtyOutput(managed.id, data)
+      managed.startupIngress?.accept(data)
     })
     managed.pty.onExit(({ exitCode }: { exitCode: number }) => {
       managed.physicalExit?.markExited()
@@ -560,6 +588,7 @@ export class PtyHandler {
         managed.killTimer = undefined
       }
       this.clearStartupCommandTimer(managed)
+      this.releaseRelayIngress(managed)
       this.flushPtyOutput(managed.id)
       this.dispatcher.notify('pty.exit', { id: managed.id, code: exitCode })
       this.notifyExitListener(managed)
@@ -572,6 +601,17 @@ export class PtyHandler {
     })
   }
 
+  private releaseRelayIngress(managed: ManagedPty): void {
+    const startupCommand = managed.startupCommand
+    const scanState = startupCommand?.scanState
+    if (scanState) {
+      const held = drainShellReadyHeldBytes(scanState)
+      startupCommand.scanState = null
+      managed.startupIngress?.accept(held)
+    }
+    managed.startupIngress?.drainAndClose()
+  }
+
   private notifyExitListener(managed: ManagedPty): void {
     if (managed.exitListenerNotified) {
       return
@@ -605,6 +645,9 @@ export class PtyHandler {
     this.dispatcher.onRequest('pty.serialize', (p) => this.serialize(p))
     this.dispatcher.onRequest('pty.revive', (p) => this.revive(p))
     this.dispatcher.onRequest('pty.getProfiles', async () => listShellProfiles())
+    this.dispatcher.onRequest('pty.closeStartupQueryAuthority', (p) =>
+      this.closeStartupQueryAuthority(p)
+    )
 
     this.dispatcher.onNotification('pty.data', (p) => this.writeData(p))
     this.dispatcher.onNotification('pty.resize', (p) => this.resize(p))
@@ -620,6 +663,17 @@ export class PtyHandler {
     return data.length <= INTERACTIVE_REDRAW_MAX_CHARS && data.includes('\x1b[')
   }
 
+  private async closeStartupQueryAuthority(
+    params: Record<string, unknown>
+  ): Promise<{ appliedSeq: number }> {
+    const id = params.id as string
+    const managed = this.ptys.get(id)
+    if (!managed || managed.disposed) {
+      throw new Error(`PTY "${id}" not found`)
+    }
+    return { appliedSeq: managed.startupIngress?.closeQueryAuthority() ?? 0 }
+  }
+
   private shouldSendInteractiveOutputNow(id: string, data: string): boolean {
     const lastInputAt = this.lastInputAtByPty.get(id)
     const now = performance.now()
@@ -640,15 +694,35 @@ export class PtyHandler {
     return true
   }
 
-  private enqueuePtyOutput(id: string, data: string): void {
+  private enqueuePtyOutput(
+    id: string,
+    data: string,
+    meta: { rawLength?: number; transformed?: boolean; seq?: number } = {}
+  ): void {
     const existing = this.pendingOutputByPty.get(id)
-    const pending = { data: (existing?.data ?? '') + data }
+    if (meta.transformed === true) {
+      // Why: transformed spans have no raw-to-clean slice mapping, so neither
+      // side of their boundary may be folded into the relay's output batch.
+      if (existing) {
+        this.flushPtyOutput(id)
+      }
+      this.dispatcher.notify('pty.data', { id, data, ...meta })
+      return
+    }
+    const pending: PendingPtyOutput = { data: (existing?.data ?? '') + data }
+    if (existing?.rawLength !== undefined || meta.rawLength !== undefined) {
+      pending.rawLength =
+        (existing?.rawLength ?? existing?.data.length ?? 0) + (meta.rawLength ?? data.length)
+    }
+    if (meta.seq !== undefined) {
+      pending.seq = meta.seq
+    }
     if (this.shouldSendInteractiveOutputNow(id, pending.data)) {
       this.pendingOutputByPty.delete(id)
       this.clearOutputFlushTimerIfIdle()
       // Why: remote agent TUIs redraw around each keystroke. Background relay
       // batching should reduce SSH chatter, not add visible input echo delay.
-      this.dispatcher.notify('pty.data', { id, data: pending.data })
+      this.dispatcher.notify('pty.data', { id, ...pending })
       return
     }
     this.pendingOutputByPty.set(id, pending)
@@ -670,12 +744,31 @@ export class PtyHandler {
         break
       }
       this.pendingOutputByPty.delete(id)
-      const chunk = pending.data.slice(0, PTY_OUTPUT_FLUSH_CHUNK_CHARS)
-      const remaining = pending.data.slice(PTY_OUTPUT_FLUSH_CHUNK_CHARS)
+      const chunk = pending.transformed
+        ? pending.data
+        : pending.data.slice(0, PTY_OUTPUT_FLUSH_CHUNK_CHARS)
+      const remaining = pending.transformed ? '' : pending.data.slice(PTY_OUTPUT_FLUSH_CHUNK_CHARS)
       if (remaining) {
-        this.pendingOutputByPty.set(id, { data: remaining })
+        this.pendingOutputByPty.set(id, {
+          data: remaining,
+          ...(pending.rawLength === undefined ? {} : { rawLength: remaining.length }),
+          seq: pending.seq
+        })
       }
-      this.dispatcher.notify('pty.data', { id, data: chunk })
+      const chunkRawLength = pending.transformed
+        ? pending.rawLength
+        : pending.rawLength === undefined
+          ? undefined
+          : chunk.length
+      const chunkSeq =
+        pending.seq === undefined ? undefined : pending.seq - (pending.data.length - chunk.length)
+      this.dispatcher.notify('pty.data', {
+        id,
+        data: chunk,
+        ...(chunkSeq === undefined ? {} : { seq: chunkSeq }),
+        ...(chunkRawLength === undefined ? {} : { rawLength: chunkRawLength }),
+        ...(pending.transformed ? { transformed: true } : {})
+      })
       writes++
     }
     if (this.pendingOutputByPty.size > 0 && writes > 0) {
@@ -691,7 +784,7 @@ export class PtyHandler {
       return
     }
     this.pendingOutputByPty.delete(id)
-    this.dispatcher.notify('pty.data', { id, data: pending.data })
+    this.dispatcher.notify('pty.data', { id, ...pending })
     this.clearOutputFlushTimerIfIdle()
   }
 
@@ -891,6 +984,12 @@ export class PtyHandler {
       tabId: typeof params.tabId === 'string' ? params.tabId : tabId
     }
     const worktreeId = typeof env?.ORCA_WORKTREE_ID === 'string' ? env.ORCA_WORKTREE_ID : undefined
+    const startupIngressIntent =
+      params.startupIngressVersion === PTY_STARTUP_INGRESS_VERSION
+        ? parsePtyStartupIngressIntent(params.startupIngress, {
+            allowWindowsEchoProjection: false
+          })
+        : undefined
     const managed: ManagedPty = {
       id,
       pty: term,
@@ -903,6 +1002,7 @@ export class PtyHandler {
       ...(explicitTerm !== undefined ? { explicitTerm } : {}),
       envToDelete,
       gitCredentialPromptGuarded,
+      ...(startupIngressIntent ? { startupIngressIntent } : {}),
       ...(terminalHandle ? { terminalHandle } : {}),
       ...(shouldProviderDeliverCommand
         ? {
@@ -958,6 +1058,8 @@ export class PtyHandler {
     // grace window already takes.
     if (managed.pty.pid && !isProcessAlive(managed.pty.pid)) {
       managed.physicalExit?.markExited()
+      this.releaseRelayIngress(managed)
+      this.flushPtyOutput(id)
       this.notifyExitListener(managed)
       disposeManagedPty(managed)
       this.ptys.delete(id)
@@ -984,6 +1086,8 @@ export class PtyHandler {
       throw new Error(`PTY "${id}" not found (identity mismatch)`)
     }
 
+    managed.startupIngress?.snapshotBarrier()
+
     // Replay buffered output. During pty.spawn({ sessionId }) the renderer has
     // not registered replay handlers yet, so return the bytes to the caller
     // instead of notifying them too early.
@@ -1175,6 +1279,7 @@ export class PtyHandler {
     const id = params.id as string
     const managed = this.ptys.get(id)
     if (managed && !managed.disposed) {
+      managed.startupIngress?.snapshotBarrier()
       managed.pty.clear()
     }
   }
@@ -1385,6 +1490,10 @@ export class PtyHandler {
   private async disposePtys(waitForPhysicalExit: boolean): Promise<void> {
     this.cancelGraceTimer()
     await this.waitForPendingPtyCreations()
+    for (const managed of this.ptys.values()) {
+      this.releaseRelayIngress(managed)
+      this.flushPtyOutput(managed.id)
+    }
     if (this.outputFlushTimer !== null) {
       clearTimeout(this.outputFlushTimer)
       this.outputFlushTimer = null
@@ -1414,6 +1523,7 @@ export class PtyHandler {
       managed.killTimer = undefined
     }
     this.clearStartupCommandTimer(managed)
+    this.releaseRelayIngress(managed)
     // Why: relay exit must retain the native owner until SIGKILL is accepted
     // (with one bounded retry) or onExit proves the process is already gone.
     await this.requestForceKillForRelayShutdown(managed)
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.ts b/src/renderer/src/components/terminal-pane/pty-connection.ts
index 18066ae75d2..0c1259d665e 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.ts
@@ -7085,6 +7085,7 @@ export function connectPanePty(
         return
       }
       if (!foreground && orderedRendererData.length === 0) {
+        recordRendererOrderedSeq(rendererMeta)
         schedulePendingStartupCommandDelivery()
         return
       }
diff --git a/src/renderer/src/components/terminal-pane/pty-dispatcher.ts b/src/renderer/src/components/terminal-pane/pty-dispatcher.ts
index 2b8781a5221..efc103531ba 100644
--- a/src/renderer/src/components/terminal-pane/pty-dispatcher.ts
+++ b/src/renderer/src/components/terminal-pane/pty-dispatcher.ts
@@ -37,6 +37,7 @@ import { installTerminalFreezeReport } from './terminal-freeze-report'
 export type PtyDataMeta = {
   seq?: number
   rawLength?: number
+  transformed?: boolean
   background?: boolean
   /** Main dropped this PTY's buffered output at the pending cap; the pane
    *  must repaint from the main-owned snapshot instead of the live stream. */
@@ -170,6 +171,7 @@ function handleDispatchedPtyData(payload: {
   data: string
   seq?: number
   rawLength?: number
+  transformed?: boolean
   background?: boolean
   droppedOutput?: boolean
 }): void {
@@ -182,6 +184,10 @@ function handleDispatchedPtyData(payload: {
     meta ??= {}
     meta.rawLength = payload.rawLength
   }
+  if (payload.transformed === true) {
+    meta ??= {}
+    meta.transformed = true
+  }
   if (payload.background === true) {
     meta ??= {}
     meta.background = true
diff --git a/src/renderer/src/runtime/remote-runtime-terminal-frame-drop-resync.test.ts b/src/renderer/src/runtime/remote-runtime-terminal-frame-drop-resync.test.ts
index e5ada3e6ca6..0c49f0a479f 100644
--- a/src/renderer/src/runtime/remote-runtime-terminal-frame-drop-resync.test.ts
+++ b/src/renderer/src/runtime/remote-runtime-terminal-frame-drop-resync.test.ts
@@ -105,6 +105,23 @@ class FakeMultiplexServer {
     this.send(TerminalStreamOpcode.Output, encodeTerminalStreamText(text), this.cursorUnits)
   }
 
+  outputSpan(data: string, rawLength: number): void {
+    this.cursorUnits += rawLength
+    this.send(
+      TerminalStreamOpcode.OutputSpan,
+      encodeTerminalStreamJson({ data, rawLength, transformed: true }),
+      this.cursorUnits
+    )
+  }
+
+  malformedOutputSpan(): void {
+    this.send(
+      TerminalStreamOpcode.OutputSpan,
+      encodeTerminalStreamJson({ data: 'framing must not render' }),
+      this.cursorUnits
+    )
+  }
+
   flushHeldManualSnapshot(): void {
     if (this.heldManualRequestId === null) {
       throw new Error('No manual snapshot is held')
@@ -144,24 +161,29 @@ describe('remote terminal frame-drop resync', () => {
 
   async function subscribeClient(): Promise<{
     data: string[]
+    metas: { seq?: number; rawLength?: number; transformed?: boolean }[]
     snapshots: string[]
     stream: RemoteRuntimeMultiplexedTerminal
   }> {
     const data: string[] = []
+    const metas: { seq?: number; rawLength?: number; transformed?: boolean }[] = []
     const snapshots: string[] = []
     const multiplexer = getRemoteRuntimeTerminalMultiplexer('env-1')
     const stream = await multiplexer.subscribeTerminal({
       terminal: 'terminal-1',
       client: { id: 'desktop-1', type: 'desktop' },
       callbacks: {
-        onData: (chunk) => data.push(chunk),
+        onData: (chunk, meta) => {
+          data.push(chunk)
+          metas.push(meta ?? {})
+        },
         onSnapshot: (chunk) => snapshots.push(chunk)
       }
     })
     // Let the initial snapshot round-trip settle.
     await Promise.resolve()
     await Promise.resolve()
-    return { data, snapshots, stream }
+    return { data, metas, snapshots, stream }
   }
 
   it('detects a dropped Output frame via the seq gap and resyncs', async () => {
@@ -197,6 +219,27 @@ describe('remote terminal frame-drop resync', () => {
     expect(snapshots).toEqual(['INITIAL'])
   })
 
+  it('delivers an empty transformed span with its raw sequence metadata', async () => {
+    const { data, metas, snapshots } = await subscribeClient()
+
+    server.outputSpan('', 9)
+
+    expect(data).toEqual([''])
+    expect(metas).toEqual([{ seq: 9, rawLength: 9, transformed: true }])
+    expect(snapshots).toEqual(['INITIAL'])
+  })
+
+  it('requests an authoritative resync instead of rendering malformed span JSON', async () => {
+    const { data, snapshots } = await subscribeClient()
+
+    server.malformedOutputSpan()
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(data).toEqual([])
+    expect(snapshots).toEqual(['INITIAL', '\x1b[2J\x1b[3J\x1b[HRECOVERED'])
+  })
+
   it('uses UTF-16 sequence units when detecting gaps in multibyte output', async () => {
     const { data, snapshots } = await subscribeClient()
 
diff --git a/src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts b/src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
index 7adf6b5dcf2..f4990423409 100644
--- a/src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
+++ b/src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
@@ -37,7 +37,7 @@ type TerminalMultiplexEvent =
   | { type: string; streamId?: number; [key: string]: unknown }
 
 export type RemoteRuntimeMultiplexedTerminalCallbacks = {
-  onData: (data: string, meta?: { seq?: number; rawLength?: number }) => void
+  onData: (data: string, meta?: { seq?: number; rawLength?: number; transformed?: boolean }) => void
   onSnapshot: (data: string, meta?: { pendingEscapeTailAnsi?: string }) => void
   onSubscribed?: () => void
   onEnd?: () => void
@@ -437,10 +437,42 @@ class RemoteRuntimeTerminalMultiplexer {
     if (!stream) {
       return
     }
-    if (frame.opcode === TerminalStreamOpcode.Output) {
-      const data = decodeTerminalStreamText(frame.payload)
+    if (
+      frame.opcode === TerminalStreamOpcode.Output ||
+      frame.opcode === TerminalStreamOpcode.OutputSpan
+    ) {
+      const span =
+        frame.opcode === TerminalStreamOpcode.OutputSpan
+          ? decodeTerminalStreamJson<{
+              data?: unknown
+              rawLength?: unknown
+              transformed?: unknown
+            }>(frame.payload)
+          : null
+      const validSpan =
+        frame.opcode !== TerminalStreamOpcode.OutputSpan ||
+        (typeof span?.data === 'string' &&
+          typeof span.rawLength === 'number' &&
+          Number.isSafeInteger(span.rawLength) &&
+          span.rawLength >= 0 &&
+          span.transformed === true)
+      const data =
+        frame.opcode === TerminalStreamOpcode.OutputSpan
+          ? validSpan
+            ? (span!.data as string)
+            : ''
+          : decodeTerminalStreamText(frame.payload)
       try {
-        const rawLength = data.length
+        if (!validSpan) {
+          // Why: rendering malformed span JSON would expose protocol framing
+          // as terminal text and lose its raw sequence accounting.
+          this.requestResyncSnapshot(stream)
+          return
+        }
+        const rawLength =
+          frame.opcode === TerminalStreamOpcode.OutputSpan && typeof span?.rawLength === 'number'
+            ? span.rawLength
+            : data.length
         // Why: a resync snapshot is authoritative; discard live output while
         // it is in flight, but still return transport credit in finally.
         if (stream.resyncInFlight) {
@@ -454,7 +486,11 @@ class RemoteRuntimeTerminalMultiplexer {
         if (typeof seq === 'number') {
           stream.expectedSeq = seq
         }
-        stream.callbacks.onData(data, { seq, rawLength })
+        stream.callbacks.onData(data, {
+          seq,
+          rawLength,
+          ...(frame.opcode === TerminalStreamOpcode.OutputSpan ? { transformed: true } : {})
+        })
       } finally {
         if (stream.acknowledgeOutput) {
           if (shouldHoldE2eRemoteTerminalAck(stream.terminal)) {
diff --git a/src/shared/pty-startup-ingress-intent.ts b/src/shared/pty-startup-ingress-intent.ts
new file mode 100644
index 00000000000..8b58c1183b6
--- /dev/null
+++ b/src/shared/pty-startup-ingress-intent.ts
@@ -0,0 +1,52 @@
+import {
+  terminalOscColorQueryReplies,
+  type TerminalOscColorQueryReplyColors
+} from './terminal-osc-color-reply'
+
+export type PtyStartupIngressIntent = {
+  colors: TerminalOscColorQueryReplyColors
+  deadlineMs: number
+  echoProjection?: 'windows-conpty-esc-stripped'
+}
+
+export const PTY_STARTUP_INGRESS_VERSION = 1
+
+export function parsePtyStartupIngressIntent(
+  value: unknown,
+  options: { allowWindowsEchoProjection: boolean }
+): PtyStartupIngressIntent | undefined {
+  if (!value || typeof value !== 'object') {
+    return undefined
+  }
+  const record = value as Record<string, unknown>
+  const colors = record.colors
+  if (!colors || typeof colors !== 'object') {
+    return undefined
+  }
+  const colorRecord = colors as Record<string, unknown>
+  const normalizedColors = {
+    ...(typeof colorRecord.foreground === 'string' ? { foreground: colorRecord.foreground } : {}),
+    ...(typeof colorRecord.background === 'string' ? { background: colorRecord.background } : {})
+  }
+  if (
+    !terminalOscColorQueryReplies(normalizedColors, [10, 11]) ||
+    typeof record.deadlineMs !== 'number' ||
+    !Number.isFinite(record.deadlineMs) ||
+    record.deadlineMs < 0 ||
+    record.deadlineMs > 30_000
+  ) {
+    return undefined
+  }
+  const projection = record.echoProjection
+  if (
+    projection !== undefined &&
+    (projection !== 'windows-conpty-esc-stripped' || !options.allowWindowsEchoProjection)
+  ) {
+    return undefined
+  }
+  return {
+    colors: normalizedColors,
+    deadlineMs: record.deadlineMs,
+    ...(projection === 'windows-conpty-esc-stripped' ? { echoProjection: projection } : {})
+  }
+}
diff --git a/src/shared/pty-startup-ingress.test.ts b/src/shared/pty-startup-ingress.test.ts
new file mode 100644
index 00000000000..55268f04f7b
--- /dev/null
+++ b/src/shared/pty-startup-ingress.test.ts
@@ -0,0 +1,158 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  PtyStartupIngress,
+  parsePtyStartupIngressIntent,
+  type PtyIngressEmission
+} from './pty-startup-ingress'
+
+const COLORS = { foreground: '#2e3434', background: '#ffffff' }
+
+function createHarness(options: { projection?: boolean; nested?: (data: string) => void } = {}) {
+  const emissions: PtyIngressEmission[] = []
+  let ingress!: PtyStartupIngress
+  const writes: string[] = []
+  ingress = new PtyStartupIngress({
+    intent: {
+      colors: COLORS,
+      deadlineMs: 5_000,
+      ...(options.projection ? { echoProjection: 'windows-conpty-esc-stripped' as const } : {})
+    },
+    write: (data) => {
+      writes.push(data)
+      options.nested?.(data)
+    },
+    onEmission: (emission) => emissions.push(emission)
+  })
+  return { ingress, writes, emissions }
+}
+
+function visible(emissions: readonly PtyIngressEmission[]): string {
+  return emissions.map((emission) => emission.data).join('')
+}
+
+describe('PtyStartupIngress', () => {
+  afterEach(() => vi.useRealTimers())
+
+  it('validates intent bounds and rejects a Windows projection on isolated hosts', () => {
+    const intent = {
+      colors: COLORS,
+      deadlineMs: 5_000,
+      echoProjection: 'windows-conpty-esc-stripped'
+    }
+    expect(parsePtyStartupIngressIntent(intent, { allowWindowsEchoProjection: true })).toEqual(
+      intent
+    )
+    expect(parsePtyStartupIngressIntent(intent, { allowWindowsEchoProjection: false })).toBe(
+      undefined
+    )
+    expect(
+      parsePtyStartupIngressIntent(
+        { ...intent, deadlineMs: 30_001 },
+        {
+          allowWindowsEchoProjection: true
+        }
+      )
+    ).toBeUndefined()
+  })
+
+  it('recognizes BEL/ST queries at every split and emits canonical replies', () => {
+    const query = '\x1b]10;?\x07\x1b]11;?\x1b\\'
+    for (let split = 0; split <= query.length; split += 1) {
+      const { ingress, writes, emissions } = createHarness()
+      ingress.accept(query.slice(0, split))
+      ingress.accept(query.slice(split))
+      ingress.drainAndClose()
+      expect(visible(emissions), `split ${split}`).toBe('')
+      expect(writes, `split ${split}`).toEqual([
+        '\x1b]10;rgb:2e2e/3434/3434\x1b\\',
+        '\x1b]11;rgb:ffff/ffff/ffff\x1b\\'
+      ])
+      expect(emissions.reduce((sum, item) => sum + item.rawEndSeq - item.rawStartSeq, 0)).toBe(
+        query.length
+      )
+    }
+  })
+
+  it('suppresses the first echo immediately and keeps a later exact collision', () => {
+    const { ingress, emissions } = createHarness({ projection: true })
+    ingress.accept('\x1b]10;?\x07')
+    const projected = ']10;rgb:2e2e/3434/3434\\'
+    ingress.accept(projected)
+    ingress.accept(projected)
+    ingress.drainAndClose()
+    expect(visible(emissions)).toBe(projected)
+  })
+
+  it('matches each echo across every split without skipping an earlier FIFO candidate', () => {
+    const foregroundEcho = ']10;rgb:2e2e/3434/3434\\'
+    const backgroundEcho = ']11;rgb:ffff/ffff/ffff\\'
+    for (const projected of [foregroundEcho, backgroundEcho]) {
+      for (let split = 0; split <= projected.length; split += 1) {
+        const { ingress, emissions } = createHarness({ projection: true })
+        ingress.accept(projected === foregroundEcho ? '\x1b]10;?\x07' : '\x1b]11;?\x1b\\')
+        ingress.accept(projected.slice(0, split))
+        ingress.accept(projected.slice(split))
+        ingress.drainAndClose()
+        expect(visible(emissions), `${projected.slice(0, 3)} split ${split}`).toBe('')
+      }
+    }
+
+    const fifo = createHarness({ projection: true })
+    fifo.ingress.accept('\x1b]10;?;?\x1b\\')
+    fifo.ingress.accept(backgroundEcho)
+    fifo.ingress.accept(backgroundEcho)
+    fifo.ingress.drainAndClose()
+    expect(visible(fifo.emissions)).toBe(backgroundEcho)
+  })
+
+  it('releases partial echo bytes on mismatch, timeout, and snapshot barrier', () => {
+    vi.useFakeTimers()
+    const mismatch = createHarness({ projection: true })
+    mismatch.ingress.accept('\x1b]10;?\x07')
+    mismatch.ingress.accept(']10;rgb:2e2e/nope')
+    expect(visible(mismatch.emissions)).toBe(']10;rgb:2e2e/nope')
+
+    const timeout = createHarness({ projection: true })
+    timeout.ingress.accept('\x1b]10;?\x07')
+    timeout.ingress.accept(']10;rgb:2e2e/')
+    vi.advanceTimersByTime(5_000)
+    expect(visible(timeout.emissions)).toBe(']10;rgb:2e2e/')
+
+    const snapshot = createHarness({ projection: true })
+    snapshot.ingress.accept('\x1b]10;?\x07')
+    snapshot.ingress.accept(']10;rgb:2e2e/')
+    snapshot.ingress.snapshotBarrier()
+    expect(visible(snapshot.emissions)).toBe(']10;rgb:2e2e/')
+
+    snapshot.ingress.accept('\x1b]11;?\x07')
+    expect(snapshot.writes.at(-1)).toBe('\x1b]11;rgb:ffff/ffff/ffff\x1b\\')
+  })
+
+  it('serializes a synchronous nested provider callback after the consumed query span', () => {
+    const emissions: PtyIngressEmission[] = []
+    let ingress!: PtyStartupIngress
+    ingress = new PtyStartupIngress({
+      intent: { colors: COLORS, deadlineMs: 5_000 },
+      write: () => ingress.accept('nested'),
+      onEmission: (emission) => emissions.push(emission)
+    })
+    ingress.accept('before\x1b]10;?\x07after')
+    ingress.drainAndClose()
+    expect(emissions.map(({ data, transformed }) => ({ data, transformed }))).toEqual([
+      { data: 'before', transformed: false },
+      { data: '', transformed: true },
+      { data: 'after', transformed: false },
+      { data: 'nested', transformed: false }
+    ])
+  })
+
+  it('ignores callbacks after teardown without recreating the raw sequence domain', () => {
+    const { ingress, emissions } = createHarness({ projection: true })
+    ingress.accept('\x1b]10;?\x07')
+    ingress.accept(']10;rgb:2e2e/')
+    const closedAt = ingress.drainAndClose()
+    ingress.accept('late')
+    expect(ingress.acceptedRawSequence).toBe(closedAt)
+    expect(visible(emissions)).toBe(']10;rgb:2e2e/')
+  })
+})
diff --git a/src/shared/pty-startup-ingress.ts b/src/shared/pty-startup-ingress.ts
new file mode 100644
index 00000000000..56042a6c52d
--- /dev/null
+++ b/src/shared/pty-startup-ingress.ts
@@ -0,0 +1,340 @@
+import {
+  parseTerminalOscColorQuery,
+  terminalOscColorQueryReplies,
+  type TerminalOscColorQuerySlot
+} from './terminal-osc-color-reply'
+import type { PtyStartupIngressIntent } from './pty-startup-ingress-intent'
+
+export {
+  PTY_STARTUP_INGRESS_VERSION,
+  parsePtyStartupIngressIntent
+} from './pty-startup-ingress-intent'
+export type { PtyStartupIngressIntent } from './pty-startup-ingress-intent'
+
+export type PtyIngressEmission = {
+  data: string
+  rawStartSeq: number
+  rawEndSeq: number
+  transformed: boolean
+}
+
+type PtyIngressSourceChunk = {
+  data: string
+  rawStartSeq: number
+  rawEndSeq: number
+}
+
+type PendingOperation =
+  | { kind: 'data'; chunk: PtyIngressSourceChunk }
+  | { kind: 'close-query' }
+  | { kind: 'snapshot' }
+  | { kind: 'teardown' }
+  | { kind: 'expire' }
+
+type PendingSpan = PtyIngressSourceChunk
+
+export type PtyStartupIngressOptions = {
+  intent?: PtyStartupIngressIntent
+  write: (data: string) => void
+  onEmission: (emission: PtyIngressEmission) => void
+}
+
+const MAX_QUERY_CANDIDATE_CHARS = 64
+
+function spanSlice(span: PendingSpan, start: number, end = span.data.length): PendingSpan {
+  return {
+    data: span.data.slice(start, end),
+    rawStartSeq: span.rawStartSeq + start,
+    rawEndSeq: span.rawStartSeq + end
+  }
+}
+
+function combineSpans(first: PendingSpan | null, second: PendingSpan): PendingSpan {
+  if (!first) {
+    return second
+  }
+  return {
+    data: first.data + second.data,
+    rawStartSeq: first.rawStartSeq,
+    rawEndSeq: second.rawEndSeq
+  }
+}
+
+function projectedWindowsConptyReply(reply: string): string {
+  // Why: the native provider harness observes ConPTY's cooked echo with ESC removed.
+  return reply.replaceAll('\x1b', '')
+}
+
+/**
+ * Serialized source-side startup classifier. Its raw sequence begins after
+ * shell-ready preprocessing and every accepted range is emitted exactly once.
+ */
+export class PtyStartupIngress {
+  private readonly intent: PtyStartupIngressIntent | undefined
+  private readonly writeProvider: (data: string) => void
+  private readonly onEmission: (emission: PtyIngressEmission) => void
+  private readonly operations: PendingOperation[] = []
+  private readonly answeredSlots = new Set<TerminalOscColorQuerySlot>()
+  private readonly expectedEchoes: string[] = []
+  private processing = false
+  private closed = false
+  private queryOpen: boolean
+  private rawHighWater = 0
+  private queryPending: PendingSpan | null = null
+  private echoPending: PendingSpan | null = null
+  private deadlineTimer: ReturnType<typeof setTimeout> | null = null
+
+  constructor(options: PtyStartupIngressOptions) {
+    this.intent = options.intent
+    this.writeProvider = options.write
+    this.onEmission = options.onEmission
+    this.queryOpen = options.intent !== undefined
+    if (options.intent) {
+      this.deadlineTimer = setTimeout(
+        () => this.enqueue({ kind: 'expire' }),
+        Math.max(0, options.intent.deadlineMs)
+      )
+      this.deadlineTimer.unref?.()
+    }
+  }
+
+  get acceptedRawSequence(): number {
+    return this.rawHighWater
+  }
+
+  accept(data: string): void {
+    if (this.closed || data.length === 0) {
+      return
+    }
+    const rawStartSeq = this.rawHighWater
+    this.rawHighWater += data.length
+    this.enqueue({
+      kind: 'data',
+      chunk: { data, rawStartSeq, rawEndSeq: this.rawHighWater }
+    })
+  }
+
+  closeQueryAuthority(): number {
+    this.enqueue({ kind: 'close-query' })
+    return this.rawHighWater
+  }
+
+  snapshotBarrier(): number {
+    this.enqueue({ kind: 'snapshot' })
+    return this.rawHighWater
+  }
+
+  drainAndClose(): number {
+    this.enqueue({ kind: 'teardown' })
+    return this.rawHighWater
+  }
+
+  private enqueue(operation: PendingOperation): void {
+    if (this.closed) {
+      return
+    }
+    this.operations.push(operation)
+    if (this.processing) {
+      return
+    }
+    this.processing = true
+    try {
+      let next: PendingOperation | undefined
+      while ((next = this.operations.shift())) {
+        this.applyOperation(next)
+      }
+    } finally {
+      this.processing = false
+    }
+  }
+
+  private applyOperation(operation: PendingOperation): void {
+    switch (operation.kind) {
+      case 'data':
+        this.processEchoSpan(operation.chunk)
+        return
+      case 'close-query':
+        this.queryOpen = false
+        this.releaseQueryPending()
+        return
+      case 'expire':
+        this.queryOpen = false
+        this.releaseAllPending()
+        this.expectedEchoes.length = 0
+        this.clearDeadline()
+        return
+      case 'snapshot':
+        this.releaseSnapshotPending()
+        return
+      case 'teardown':
+        this.queryOpen = false
+        this.releaseAllPending()
+        this.expectedEchoes.length = 0
+        this.clearDeadline()
+        this.closed = true
+    }
+  }
+
+  private processEchoSpan(span: PendingSpan): void {
+    let input = combineSpans(this.echoPending, span)
+    this.echoPending = null
+
+    while (this.expectedEchoes.length > 0) {
+      const expected = this.expectedEchoes[0]
+      const compared = Math.min(input.data.length, expected.length)
+      let matching = 0
+      while (matching < compared && input.data[matching] === expected[matching]) {
+        matching += 1
+      }
+      if (matching < compared) {
+        this.expectedEchoes.shift()
+        this.processQuerySpan(input)
+        return
+      }
+      if (input.data.length < expected.length) {
+        this.echoPending = input
+        return
+      }
+
+      this.expectedEchoes.shift()
+      this.emit(spanSlice(input, 0, expected.length), true, '')
+      input = spanSlice(input, expected.length)
+      if (input.data.length === 0) {
+        return
+      }
+    }
+
+    this.processQuerySpan(input)
+  }
+
+  private processQuerySpan(span: PendingSpan): void {
+    const input = combineSpans(this.queryPending, span)
+    this.queryPending = null
+    if (!this.queryOpen || !this.intent) {
+      this.emit(input, false)
+      return
+    }
+
+    let offset = 0
+    while (offset < input.data.length) {
+      const candidateIndex = input.data.indexOf('\x1b', offset)
+      if (candidateIndex === -1) {
+        this.emit(spanSlice(input, offset), false)
+        return
+      }
+      if (candidateIndex > offset) {
+        this.emit(spanSlice(input, offset, candidateIndex), false)
+      }
+      const query = parseTerminalOscColorQuery(input.data, candidateIndex)
+      if (query.kind === 'none') {
+        this.emit(spanSlice(input, candidateIndex, candidateIndex + 1), false)
+        offset = candidateIndex + 1
+        continue
+      }
+      if (query.kind === 'partial') {
+        const candidate = spanSlice(input, candidateIndex)
+        if (candidate.data.length <= MAX_QUERY_CANDIDATE_CHARS) {
+          this.queryPending = candidate
+        } else {
+          this.emit(candidate, false)
+        }
+        return
+      }
+
+      const querySpan = spanSlice(input, candidateIndex, query.endIndex)
+      if (!this.answerQuery(query.slots)) {
+        this.emit(querySpan, false)
+      } else {
+        this.emit(querySpan, true, '')
+      }
+      offset = query.endIndex
+    }
+  }
+
+  private answerQuery(slots: readonly TerminalOscColorQuerySlot[]): boolean {
+    if (slots.some((slot) => this.answeredSlots.has(slot)) || !this.intent) {
+      return false
+    }
+    const replies = terminalOscColorQueryReplies(this.intent.colors, slots)
+    if (!replies) {
+      return false
+    }
+
+    let wroteAny = false
+    for (const [index, reply] of replies.entries()) {
+      const slot = slots[index]
+      if (slot === undefined) {
+        return wroteAny
+      }
+      this.answeredSlots.add(slot)
+      const projected =
+        this.intent.echoProjection === 'windows-conpty-esc-stripped'
+          ? projectedWindowsConptyReply(reply)
+          : null
+      if (projected) {
+        // Why: register before write because node-pty can synchronously re-enter onData.
+        this.expectedEchoes.push(projected)
+      }
+      try {
+        this.writeProvider(reply)
+        wroteAny = true
+      } catch {
+        this.answeredSlots.delete(slot)
+        if (projected) {
+          this.expectedEchoes.pop()
+        }
+        return wroteAny
+      }
+    }
+
+    if (this.answeredSlots.has(10) && this.answeredSlots.has(11)) {
+      this.queryOpen = false
+    }
+    return wroteAny
+  }
+
+  private releaseQueryPending(): void {
+    if (!this.queryPending) {
+      return
+    }
+    const pending = this.queryPending
+    this.queryPending = null
+    this.emit(pending, false)
+  }
+
+  private releaseAllPending(): void {
+    const pending = this.echoPending ?? this.queryPending
+    this.echoPending = null
+    this.queryPending = null
+    if (pending) {
+      this.emit(pending, false)
+    }
+  }
+
+  private releaseSnapshotPending(): void {
+    if (this.echoPending) {
+      const pending = this.echoPending
+      this.echoPending = null
+      this.expectedEchoes.shift()
+      this.emit(pending, false)
+    }
+    this.releaseQueryPending()
+  }
+
+  private emit(span: PendingSpan, transformed: boolean, data = span.data): void {
+    this.onEmission({
+      data,
+      rawStartSeq: span.rawStartSeq,
+      rawEndSeq: span.rawEndSeq,
+      transformed
+    })
+  }
+
+  private clearDeadline(): void {
+    if (!this.deadlineTimer) {
+      return
+    }
+    clearTimeout(this.deadlineTimer)
+    this.deadlineTimer = null
+  }
+}
diff --git a/src/shared/terminal-stream-protocol.ts b/src/shared/terminal-stream-protocol.ts
index 02314fb39e4..bcfa3b46d9c 100644
--- a/src/shared/terminal-stream-protocol.ts
+++ b/src/shared/terminal-stream-protocol.ts
@@ -20,7 +20,8 @@ export enum TerminalStreamOpcode {
   Ack = 13,
   // Why 14: Ack already occupies 13 on current clients; older runtimes ignore
   // this opcode and still receive the compatibility Resize frame behind it.
-  ClaimViewport = 14
+  ClaimViewport = 14,
+  OutputSpan = 15
 }
 
 export type TerminalStreamFrame = {
@@ -102,6 +103,7 @@ function isTerminalStreamOpcode(value: number): value is TerminalStreamOpcode {
     value === TerminalStreamOpcode.SnapshotRequest ||
     value === TerminalStreamOpcode.Metadata ||
     value === TerminalStreamOpcode.Ack ||
-    value === TerminalStreamOpcode.ClaimViewport
+    value === TerminalStreamOpcode.ClaimViewport ||
+    value === TerminalStreamOpcode.OutputSpan
   )
 }

From 7df56adaf1b4b5a062b8f671797d5eb03beae931 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sun, 19 Jul 2026 21:16:33 -0700
Subject: [PATCH 24/54] fix(ui): restore spaces around orca.yaml in trust
 dialog (#9511)

---
 .../sidebar/OrcaYamlTrustDialog.test.tsx      | 98 +++++++++++++++++++
 .../sidebar/OrcaYamlTrustDialog.tsx           |  9 +-
 src/renderer/src/i18n/locales/es.json         |  4 +-
 3 files changed, 104 insertions(+), 7 deletions(-)
 create mode 100644 src/renderer/src/components/sidebar/OrcaYamlTrustDialog.test.tsx

diff --git a/src/renderer/src/components/sidebar/OrcaYamlTrustDialog.test.tsx b/src/renderer/src/components/sidebar/OrcaYamlTrustDialog.test.tsx
new file mode 100644
index 00000000000..65f937da42b
--- /dev/null
+++ b/src/renderer/src/components/sidebar/OrcaYamlTrustDialog.test.tsx
@@ -0,0 +1,98 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import type { ButtonHTMLAttributes, ReactNode } from 'react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  state: {
+    activeModal: 'confirm-orca-yaml-hooks' as string | null,
+    modalData: {} as Record<string, unknown>,
+    closeModal: vi.fn(),
+    markOrcaHookScriptConfirmed: vi.fn(),
+    markOrcaHookRepoAlwaysTrusted: vi.fn()
+  }
+}))
+
+vi.mock('@/store', () => ({
+  useAppStore: Object.assign(
+    (selector: (state: typeof mocks.state) => unknown) => selector(mocks.state),
+    {
+      getState: () => mocks.state
+    }
+  )
+}))
+
+vi.mock('@/components/ui/dialog', () => ({
+  Dialog: ({ open, children }: { open: boolean; children: ReactNode }) =>
+    open ? <div>{children}</div> : null,
+  DialogContent: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  DialogDescription: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  DialogFooter: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  DialogHeader: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  DialogTitle: ({ children }: { children: ReactNode }) => <div>{children}</div>
+}))
+
+vi.mock('@/components/ui/button', () => ({
+  Button: ({
+    children,
+    ...props
+  }: ButtonHTMLAttributes<HTMLButtonElement> & { children: ReactNode }) => (
+    <button {...props}>{children}</button>
+  )
+}))
+
+// Why: fall back to English defaults so this test doesn't depend on locale files
+// being loaded; the bug is missing JSX whitespace around those fragments.
+vi.mock('@/i18n/i18n', () => ({
+  translate: (_key: string, fallback: string) => fallback
+}))
+
+function decodeHtml(html: string): string {
+  return html
+    .replace(/&#x27;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+}
+
+describe('OrcaYamlTrustDialog', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.state.activeModal = 'confirm-orca-yaml-hooks'
+    mocks.state.modalData = {
+      repoId: 'repo-1',
+      repoName: 'orca',
+      scriptKind: 'setup',
+      scriptContent: 'node config/scripts/run-internal-dev-setup.mjs\npnpm install',
+      contentHash: 'hash-1',
+      previouslyApproved: false
+    }
+  })
+
+  it('keeps spaces around orca.yaml and the repo name in the first-run copy', async () => {
+    const { default: OrcaYamlTrustDialog } = await import('./OrcaYamlTrustDialog')
+    const text = decodeHtml(renderToStaticMarkup(<OrcaYamlTrustDialog />)).replace(/<[^>]+>/g, '')
+
+    expect(text).toContain("This repository's orca.yaml runs on your machine")
+    expect(text).toContain('Only run if you trust orca.')
+    expect(text).toContain('Always trust orca.yaml in orca')
+    expect(text).not.toContain("repository'sorca.yaml")
+    expect(text).not.toContain('trustorca')
+    expect(text).not.toContain('trustorca.yaml')
+    expect(text).not.toContain('inorca')
+  })
+
+  it('keeps spaces around orca.yaml when the script changed since last approval', async () => {
+    mocks.state.modalData = {
+      ...mocks.state.modalData,
+      previouslyApproved: true
+    }
+    const { default: OrcaYamlTrustDialog } = await import('./OrcaYamlTrustDialog')
+    const text = decodeHtml(renderToStaticMarkup(<OrcaYamlTrustDialog />)).replace(/<[^>]+>/g, '')
+
+    expect(text).toContain('orca.yaml changed since you last approved')
+    expect(text).toContain('Always trust orca.yaml in orca')
+    expect(text).not.toContain('Always trustorca.yaml')
+    expect(text).not.toContain('inorca')
+  })
+})
diff --git a/src/renderer/src/components/sidebar/OrcaYamlTrustDialog.tsx b/src/renderer/src/components/sidebar/OrcaYamlTrustDialog.tsx
index 63489c8b282..60ea9bcf90f 100644
--- a/src/renderer/src/components/sidebar/OrcaYamlTrustDialog.tsx
+++ b/src/renderer/src/components/sidebar/OrcaYamlTrustDialog.tsx
@@ -136,7 +136,7 @@ const OrcaYamlTrustDialog = React.memo(function OrcaYamlTrustDialog() {
                 {translate(
                   'auto.components.sidebar.OrcaYamlTrustDialog.aa3ffb33fb',
                   "This repository's"
-                )}
+                )}{' '}
                 <code>
                   {translate('auto.components.sidebar.OrcaYamlTrustDialog.79afc6772b', 'orca.yaml')}
                 </code>{' '}
@@ -148,7 +148,7 @@ const OrcaYamlTrustDialog = React.memo(function OrcaYamlTrustDialog() {
                 {translate(
                   'auto.components.sidebar.OrcaYamlTrustDialog.bf800b7e04',
                   '. Only run if you trust'
-                )}
+                )}{' '}
                 {repoName}.
               </>
             )}
@@ -190,12 +190,11 @@ const OrcaYamlTrustDialog = React.memo(function OrcaYamlTrustDialog() {
             onChange={(event) => setAlwaysTrust(event.target.checked)}
           />
           <span className="text-xs font-medium text-foreground">
-            {translate('auto.components.sidebar.OrcaYamlTrustDialog.531689199b', 'Always trust')}
+            {translate('auto.components.sidebar.OrcaYamlTrustDialog.531689199b', 'Always trust')}{' '}
             <code>
               {translate('auto.components.sidebar.OrcaYamlTrustDialog.79afc6772b', 'orca.yaml')}
             </code>{' '}
-            {translate('auto.components.sidebar.OrcaYamlTrustDialog.c494b3ccb1', 'in')}
-            {repoName}
+            {translate('auto.components.sidebar.OrcaYamlTrustDialog.c494b3ccb1', 'in')} {repoName}
           </span>
         </label>
 
diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json
index 1565076a578..64f47a9c258 100644
--- a/src/renderer/src/i18n/locales/es.json
+++ b/src/renderer/src/i18n/locales/es.json
@@ -3903,9 +3903,9 @@
           "c494b3ccb1": "en",
           "79afc6772b": "orca.yaml",
           "531689199b": "Confiar siempre",
-          "bf800b7e04": ". Ejecútalo solo si confías en ",
+          "bf800b7e04": ". Ejecútalo solo si confías en",
           "831f2cd9f0": "se ejecuta en tu máquina",
-          "aa3ffb33fb": "El archivo ",
+          "aa3ffb33fb": "El archivo",
           "c55beddbf8": "cambió desde la última vez que lo aprobaste. Revísalo de nuevo antes de que se ejecute",
           "95bf974a1a": "Script {{value0}}",
           "9e52effffd": "Nuevo script {{value0}}",

From 0d97653e3928f511cc28cb7a446c1985126e11fd Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sun, 19 Jul 2026 21:24:24 -0700
Subject: [PATCH 25/54] fix(ui): restore missing spaces in i18n JSX fragment
 copy (#9513)

---
 .../src/components/GitHubItemDialog.tsx       |   5 +-
 .../src/components/GitLabItemDialog.tsx       |   4 +-
 .../src/components/PullRequestPage.tsx        |   5 +-
 src/renderer/src/components/TaskPage.tsx      |   2 +-
 src/renderer/src/components/UpdateCard.tsx    |   3 +-
 .../automations/AutomationsPage.tsx           |   2 +-
 .../ExternalAutomationRunTable.tsx            |   2 +-
 .../ContextualTourProgressDots.tsx            |   2 +-
 .../components/editor/CombinedDiffViewer.tsx  |   2 +-
 .../components/editor/ConflictComponents.tsx  |   6 +-
 .../src/components/editor/IpynbViewer.tsx     |   2 +-
 .../src/components/editor/MermaidBlock.tsx    |   3 +-
 .../editor/RichMarkdownDocLinkMenu.tsx        |   4 +-
 .../ReviewNotesAnimatedVisual.tsx             |   2 +-
 .../ReviewPRViewAnimatedVisual.tsx            |   2 +-
 .../feature-wall/ReviewShipAnimatedVisual.tsx |   2 +-
 .../feature-wall/review-notes-diff-rows.tsx   |   2 +-
 .../components/github/PRFilterSections.tsx    |   3 +-
 .../github/github-rate-limit-display.tsx      |   4 +-
 .../gitlab/gitlab-rate-limit-display.tsx      |   2 +-
 .../src/components/linear-priority-icon.tsx   |   9 +-
 .../right-sidebar/FileExplorerTreeStatus.tsx  |   2 +-
 .../SourceControlAgentActionDialogForm.tsx    |   2 +-
 .../right-sidebar/checks-panel-content.tsx    |   4 +-
 .../src/components/settings/AccountsPane.tsx  |   4 +-
 .../AutoRenameBranchFromWorkSetting.tsx       |   8 +-
 .../src/components/settings/BaseRefPicker.tsx |   4 +-
 .../settings/BrowserSessionCookiesSection.tsx |   2 +-
 .../src/components/settings/CliSection.tsx    |   2 +-
 .../settings/CommitMessageAiPane.tsx          |   2 +-
 .../settings/GeneralEditorSettingsSection.tsx |   2 +-
 .../settings/GeneralUpdateSettingsSection.tsx |   4 +-
 .../src/components/settings/GitPane.tsx       |   9 +-
 .../settings/ManageSessionKillDialog.tsx      |   2 +-
 .../settings/NotificationSoundSection.tsx     |   2 +-
 .../settings/RepositoryHooksSection.tsx       |   6 +-
 .../components/settings/RepositoryPane.tsx    |   2 +-
 ...orySourceControlAiHostedReviewDefaults.tsx |   2 +-
 .../settings/RuntimeEnvironmentsPane.tsx      |   2 +-
 .../settings/SshPassphraseDialog.tsx          |   4 +-
 .../settings/WslCliRegistration.tsx           |   2 +-
 .../sidebar/DeleteWorktreeWarningPanels.tsx   |   4 +-
 .../sidebar/SetupScriptPromptCardViews.tsx    |   6 +-
 .../src/components/stats/ShareUsageCard.tsx   |   2 +-
 .../components/stats/UsageOverviewPane.tsx    |   2 +-
 .../src/lib/i18n-jsx-spacing-guard.test.ts    | 140 ++++++++++++++++++
 46 files changed, 212 insertions(+), 77 deletions(-)
 create mode 100644 src/renderer/src/lib/i18n-jsx-spacing-guard.test.ts

diff --git a/src/renderer/src/components/GitHubItemDialog.tsx b/src/renderer/src/components/GitHubItemDialog.tsx
index 6f6b7fb2424..5d98a84f0f1 100644
--- a/src/renderer/src/components/GitHubItemDialog.tsx
+++ b/src/renderer/src/components/GitHubItemDialog.tsx
@@ -4935,13 +4935,12 @@ function ChecksTab({
               </span>
               {startedAt && (
                 <span>
-                  {translate('auto.components.GitHubItemDialog.4812814bc8', 'Started')}
-                  {startedAt}
+                  {translate('auto.components.GitHubItemDialog.4812814bc8', 'Started')} {startedAt}
                 </span>
               )}
               {completedAt && (
                 <span>
-                  {translate('auto.components.GitHubItemDialog.0f478f5efa', 'Completed')}
+                  {translate('auto.components.GitHubItemDialog.0f478f5efa', 'Completed')}{' '}
                   {completedAt}
                 </span>
               )}
diff --git a/src/renderer/src/components/GitLabItemDialog.tsx b/src/renderer/src/components/GitLabItemDialog.tsx
index b71386b4c34..827d86ad2d8 100644
--- a/src/renderer/src/components/GitLabItemDialog.tsx
+++ b/src/renderer/src/components/GitLabItemDialog.tsx
@@ -1034,7 +1034,7 @@ export default function GitLabItemDialog({
                     <StateBadge state={item.state} />
                     {item.author ? (
                       <span>
-                        {translate('auto.components.GitLabItemDialog.9bfb4a24d7', 'by')}
+                        {translate('auto.components.GitLabItemDialog.9bfb4a24d7', 'by')}{' '}
                         {item.author}
                       </span>
                     ) : null}
@@ -1521,7 +1521,7 @@ export default function GitLabItemDialog({
                                       {translate(
                                         'auto.components.GitLabItemDialog.a7eb4f4916',
                                         'from'
-                                      )}
+                                      )}{' '}
                                       {file.oldPath}
                                     </div>
                                   ) : null}
diff --git a/src/renderer/src/components/PullRequestPage.tsx b/src/renderer/src/components/PullRequestPage.tsx
index b53ba354618..8cd3f872974 100644
--- a/src/renderer/src/components/PullRequestPage.tsx
+++ b/src/renderer/src/components/PullRequestPage.tsx
@@ -5030,13 +5030,12 @@ function ChecksTab({
               </span>
               {startedAt && (
                 <span>
-                  {translate('auto.components.PullRequestPage.76551b1161', 'Started')}
-                  {startedAt}
+                  {translate('auto.components.PullRequestPage.76551b1161', 'Started')} {startedAt}
                 </span>
               )}
               {completedAt && (
                 <span>
-                  {translate('auto.components.PullRequestPage.000f90afcf', 'Completed')}
+                  {translate('auto.components.PullRequestPage.000f90afcf', 'Completed')}{' '}
                   {completedAt}
                 </span>
               )}
diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index 51bbc201879..727c0a44970 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -9323,7 +9323,7 @@ export default function TaskPage(): React.JSX.Element {
                   // Why: per-repo partial-failure signal — distinct from a hard
                   // IPC reject (tasksError). The two are mutually exclusive.
                   <div className="border-b border-border/50 bg-amber-500/10 px-4 py-3 text-sm text-amber-700 dark:text-amber-200">
-                    {failedCount} {translate('auto.components.TaskPage.7762f4b03a', 'of')}
+                    {failedCount} {translate('auto.components.TaskPage.7762f4b03a', 'of')}{' '}
                     {selectedRepos.length}{' '}
                     {translate('auto.components.TaskPage.d1766fd62d', 'projects failed to load')}
                   </div>
diff --git a/src/renderer/src/components/UpdateCard.tsx b/src/renderer/src/components/UpdateCard.tsx
index 9010a740e10..c080b518f64 100644
--- a/src/renderer/src/components/UpdateCard.tsx
+++ b/src/renderer/src/components/UpdateCard.tsx
@@ -887,8 +887,7 @@ function DownloadingContent({
       <div className="flex items-start justify-between gap-2">
         {release ? (
           <h3 className="text-sm font-semibold">
-            {translate('auto.components.UpdateCard.f58b5c57a6', 'New:')}
-            {release.title}
+            {translate('auto.components.UpdateCard.f58b5c57a6', 'New:')} {release.title}
           </h3>
         ) : (
           <h3 className="text-sm font-semibold">
diff --git a/src/renderer/src/components/automations/AutomationsPage.tsx b/src/renderer/src/components/automations/AutomationsPage.tsx
index 98a78ef9845..538cec979e3 100644
--- a/src/renderer/src/components/automations/AutomationsPage.tsx
+++ b/src/renderer/src/components/automations/AutomationsPage.tsx
@@ -2877,7 +2877,7 @@ export default function AutomationsPage(): React.JSX.Element {
                     )}
                   </TabsTrigger>
                   <TabsTrigger value="runs" disabled={!selected}>
-                    {translate('auto.components.automations.AutomationsPage.0e110a3469', 'Runs')}
+                    {translate('auto.components.automations.AutomationsPage.0e110a3469', 'Runs')}{' '}
                     <span className="text-xs text-muted-foreground">{selectedRuns.length}</span>
                   </TabsTrigger>
                 </TabsList>
diff --git a/src/renderer/src/components/automations/ExternalAutomationRunTable.tsx b/src/renderer/src/components/automations/ExternalAutomationRunTable.tsx
index aa8ff9666c7..f6e5f693371 100644
--- a/src/renderer/src/components/automations/ExternalAutomationRunTable.tsx
+++ b/src/renderer/src/components/automations/ExternalAutomationRunTable.tsx
@@ -288,7 +288,7 @@ export function ExternalAutomationRunTable({
           <FileText className="size-3.5" />
           <span>
             {pageStart}-{pageEnd}{' '}
-            {translate('auto.components.automations.ExternalAutomationRunTable.7475c0ce96', 'of')}
+            {translate('auto.components.automations.ExternalAutomationRunTable.7475c0ce96', 'of')}{' '}
             {totalCount}
           </span>
         </div>
diff --git a/src/renderer/src/components/contextual-tours/ContextualTourProgressDots.tsx b/src/renderer/src/components/contextual-tours/ContextualTourProgressDots.tsx
index b52cbb6fdf4..bb7fde46fe1 100644
--- a/src/renderer/src/components/contextual-tours/ContextualTourProgressDots.tsx
+++ b/src/renderer/src/components/contextual-tours/ContextualTourProgressDots.tsx
@@ -46,7 +46,7 @@ export function ContextualTourProgressDots({
       </span>
       <span className="whitespace-nowrap text-[11px] font-medium leading-none text-muted-foreground">
         {current}{' '}
-        {translate('auto.components.contextual.tours.ContextualTourProgressDots.7734cb8ad3', 'of')}
+        {translate('auto.components.contextual.tours.ContextualTourProgressDots.7734cb8ad3', 'of')}{' '}
         {total}
       </span>
     </div>
diff --git a/src/renderer/src/components/editor/CombinedDiffViewer.tsx b/src/renderer/src/components/editor/CombinedDiffViewer.tsx
index 9ae116de477..7622980a231 100644
--- a/src/renderer/src/components/editor/CombinedDiffViewer.tsx
+++ b/src/renderer/src/components/editor/CombinedDiffViewer.tsx
@@ -2022,7 +2022,7 @@ export default function CombinedDiffViewer({
               {translate('auto.components.editor.CombinedDiffViewer.948a5fd6c8', 'Clear Notes')}
             </DialogTitle>
             <DialogDescription className="text-xs">
-              {translate('auto.components.editor.CombinedDiffViewer.84898c548d', 'Clear')}
+              {translate('auto.components.editor.CombinedDiffViewer.84898c548d', 'Clear')}{' '}
               {diffCommentCount}{' '}
               {diffCommentCount === 1
                 ? translate('auto.components.editor.CombinedDiffViewer.8ab3248fd8', 'note')
diff --git a/src/renderer/src/components/editor/ConflictComponents.tsx b/src/renderer/src/components/editor/ConflictComponents.tsx
index 47c74ae88db..32159e23f00 100644
--- a/src/renderer/src/components/editor/ConflictComponents.tsx
+++ b/src/renderer/src/components/editor/ConflictComponents.tsx
@@ -101,7 +101,7 @@ export function ConflictBanner({
           )}
           <span className="min-w-0 truncate font-medium text-foreground">
             {label}{' '}
-            {translate('auto.components.editor.ConflictComponents.55d61a0ccd', 'conflict ·')}
+            {translate('auto.components.editor.ConflictComponents.55d61a0ccd', 'conflict ·')}{' '}
             {CONFLICT_KIND_LABELS[conflict.conflictKind]}
           </span>
           {conflictNavigation && conflictNavigation.total > 0 && (
@@ -171,7 +171,7 @@ export function ConflictBanner({
       )}
       {entry?.oldPath && (
         <div className="mt-1 text-muted-foreground">
-          {translate('auto.components.editor.ConflictComponents.d5edd81755', 'Renamed from')}
+          {translate('auto.components.editor.ConflictComponents.d5edd81755', 'Renamed from')}{' '}
           {entry.oldPath}
         </div>
       )}
@@ -334,7 +334,7 @@ export function ConflictReviewPanel({
                 {translate(
                   'auto.components.editor.ConflictComponents.a1ce36f77d',
                   'Snapshot captured at'
-                )}
+                )}{' '}
                 {snapshotTime}.
               </span>
             </div>
diff --git a/src/renderer/src/components/editor/IpynbViewer.tsx b/src/renderer/src/components/editor/IpynbViewer.tsx
index fc19ca04175..ecb20f2ff63 100644
--- a/src/renderer/src/components/editor/IpynbViewer.tsx
+++ b/src/renderer/src/components/editor/IpynbViewer.tsx
@@ -899,7 +899,7 @@ export default function IpynbViewer({
             {translate('auto.components.editor.IpynbViewer.329764e9fc', 'BETA')}
           </span>
           <span className="font-mono">
-            {translate('auto.components.editor.IpynbViewer.8c3b21369a', 'nbformat')}
+            {translate('auto.components.editor.IpynbViewer.8c3b21369a', 'nbformat')}{' '}
             {notebook.nbformat}
           </span>
         </div>
diff --git a/src/renderer/src/components/editor/MermaidBlock.tsx b/src/renderer/src/components/editor/MermaidBlock.tsx
index 250a0c32161..f25de3983ff 100644
--- a/src/renderer/src/components/editor/MermaidBlock.tsx
+++ b/src/renderer/src/components/editor/MermaidBlock.tsx
@@ -103,8 +103,7 @@ export default function MermaidBlock({
     return (
       <div className="mermaid-block">
         <div className="mermaid-error">
-          {translate('auto.components.editor.MermaidBlock.dcc132e691', 'Diagram error:')}
-          {error}
+          {translate('auto.components.editor.MermaidBlock.dcc132e691', 'Diagram error:')} {error}
         </div>
         <pre>
           <code>{content}</code>
diff --git a/src/renderer/src/components/editor/RichMarkdownDocLinkMenu.tsx b/src/renderer/src/components/editor/RichMarkdownDocLinkMenu.tsx
index d339f1e3da6..dafc70c658b 100644
--- a/src/renderer/src/components/editor/RichMarkdownDocLinkMenu.tsx
+++ b/src/renderer/src/components/editor/RichMarkdownDocLinkMenu.tsx
@@ -68,9 +68,9 @@ export function RichMarkdownDocLinkMenu({
       )}
       {overflow ? (
         <div className="rich-markdown-doc-link-footer">
-          {translate('auto.components.editor.RichMarkdownDocLinkMenu.2aaf7d9678', 'Showing')}
+          {translate('auto.components.editor.RichMarkdownDocLinkMenu.2aaf7d9678', 'Showing')}{' '}
           {rows.length}{' '}
-          {translate('auto.components.editor.RichMarkdownDocLinkMenu.90c5f0e1e4', 'of')}
+          {translate('auto.components.editor.RichMarkdownDocLinkMenu.90c5f0e1e4', 'of')}{' '}
           {totalMatches}
         </div>
       ) : null}
diff --git a/src/renderer/src/components/feature-wall/ReviewNotesAnimatedVisual.tsx b/src/renderer/src/components/feature-wall/ReviewNotesAnimatedVisual.tsx
index 24c8399761e..ba9684ba708 100644
--- a/src/renderer/src/components/feature-wall/ReviewNotesAnimatedVisual.tsx
+++ b/src/renderer/src/components/feature-wall/ReviewNotesAnimatedVisual.tsx
@@ -381,7 +381,7 @@ export function ReviewNotesAnimatedVisual(props: { reducedMotion: boolean }): JS
         </button>
         <div className="ravs-popover" data-note-popover>
           <div className="ravs-pop-label">
-            {translate('auto.components.feature.wall.ReviewNotesAnimatedVisual.a7a89d8f94', 'Line')}
+            {translate('auto.components.feature.wall.ReviewNotesAnimatedVisual.a7a89d8f94', 'Line')}{' '}
             <span data-pop-line>?</span>
           </div>
           <div className="ravs-pop-input" data-pop-input />
diff --git a/src/renderer/src/components/feature-wall/ReviewPRViewAnimatedVisual.tsx b/src/renderer/src/components/feature-wall/ReviewPRViewAnimatedVisual.tsx
index be3148a0e7c..461da2f21c6 100644
--- a/src/renderer/src/components/feature-wall/ReviewPRViewAnimatedVisual.tsx
+++ b/src/renderer/src/components/feature-wall/ReviewPRViewAnimatedVisual.tsx
@@ -272,7 +272,7 @@ export function ReviewPRViewAnimatedVisual(props: { reducedMotion: boolean }): J
                   {translate(
                     'auto.components.feature.wall.ReviewPRViewAnimatedVisual.6f4c2d7cb7',
                     'Add a coverage case for'
-                  )}
+                  )}{' '}
                   <code>
                     {translate(
                       'auto.components.feature.wall.ReviewPRViewAnimatedVisual.c2062da7ec',
diff --git a/src/renderer/src/components/feature-wall/ReviewShipAnimatedVisual.tsx b/src/renderer/src/components/feature-wall/ReviewShipAnimatedVisual.tsx
index 0b2ef880ffa..548ac8334f2 100644
--- a/src/renderer/src/components/feature-wall/ReviewShipAnimatedVisual.tsx
+++ b/src/renderer/src/components/feature-wall/ReviewShipAnimatedVisual.tsx
@@ -303,7 +303,7 @@ export function ReviewShipAnimatedVisual(props: { reducedMotion: boolean }): JSX
               {translate(
                 'auto.components.feature.wall.ReviewShipAnimatedVisual.e725000cd7',
                 'Changes'
-              )}
+              )}{' '}
               <span className="ravs-sc-changes-count">{SHIP_FILES.length}</span>
             </span>
             <span className="ravs-sc-view-all">
diff --git a/src/renderer/src/components/feature-wall/review-notes-diff-rows.tsx b/src/renderer/src/components/feature-wall/review-notes-diff-rows.tsx
index c5c476a39d2..cbba8da521c 100644
--- a/src/renderer/src/components/feature-wall/review-notes-diff-rows.tsx
+++ b/src/renderer/src/components/feature-wall/review-notes-diff-rows.tsx
@@ -85,7 +85,7 @@ export function ReviewDiffRows(): JSX.Element {
                   {translate(
                     'auto.components.feature.wall.review.notes.diff.rows.f621c734f8',
                     'Note · line'
-                  )}
+                  )}{' '}
                   <span data-slot-line>?</span>
                 </div>
                 <div className="ravs-note-body" data-slot-body />
diff --git a/src/renderer/src/components/github/PRFilterSections.tsx b/src/renderer/src/components/github/PRFilterSections.tsx
index 59fc7634120..6f65eee8e55 100644
--- a/src/renderer/src/components/github/PRFilterSections.tsx
+++ b/src/renderer/src/components/github/PRFilterSections.tsx
@@ -208,8 +208,7 @@ export function SectionMenu({
   return (
     <div className="py-1 text-xs">
       <div className="px-3 py-1.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
-        {translate('auto.components.github.PRFilterSections.8177eda37e', 'Filter')}
-        {subject}
+        {translate('auto.components.github.PRFilterSections.8177eda37e', 'Filter')} {subject}
       </div>
       {rows.map((row) => (
         <button
diff --git a/src/renderer/src/components/github/github-rate-limit-display.tsx b/src/renderer/src/components/github/github-rate-limit-display.tsx
index 38297503285..9b7002476ce 100644
--- a/src/renderer/src/components/github/github-rate-limit-display.tsx
+++ b/src/renderer/src/components/github/github-rate-limit-display.tsx
@@ -154,12 +154,12 @@ function GitHubRateLimitRows({
               )}
             >
               {v.remaining}{' '}
-              {translate('auto.components.github.github.rate.limit.display.f42790d150', 'of')}
+              {translate('auto.components.github.github.rate.limit.display.f42790d150', 'of')}{' '}
               {v.limit}{' '}
               {translate(
                 'auto.components.github.github.rate.limit.display.6da1858354',
                 'left · resets in'
-              )}
+              )}{' '}
               {formatGitHubRateLimitReset(v.resetAt)}
             </span>
           </div>
diff --git a/src/renderer/src/components/gitlab/gitlab-rate-limit-display.tsx b/src/renderer/src/components/gitlab/gitlab-rate-limit-display.tsx
index 6bc87d967e8..a85c566b0d6 100644
--- a/src/renderer/src/components/gitlab/gitlab-rate-limit-display.tsx
+++ b/src/renderer/src/components/gitlab/gitlab-rate-limit-display.tsx
@@ -133,7 +133,7 @@ function GitLabRateLimitRows({
           )}
         >
           {rest.remaining}{' '}
-          {translate('auto.components.gitlab.gitlab.rate.limit.display.ea8ad0bae8', 'of')}
+          {translate('auto.components.gitlab.gitlab.rate.limit.display.ea8ad0bae8', 'of')}{' '}
           {rest.limit}{' '}
           {translate(
             'auto.components.gitlab.gitlab.rate.limit.display.3e2c982cfa',
diff --git a/src/renderer/src/components/linear-priority-icon.tsx b/src/renderer/src/components/linear-priority-icon.tsx
index ae9ebbb16a8..92f8bfaa210 100644
--- a/src/renderer/src/components/linear-priority-icon.tsx
+++ b/src/renderer/src/components/linear-priority-icon.tsx
@@ -54,8 +54,7 @@ export function LinearPriorityIcon({
       >
         <span aria-hidden="true">!</span>
         <span className="sr-only">
-          {translate('auto.components.linear.priority.icon.c43d3e065b', 'Priority:')}
-          {label}
+          {translate('auto.components.linear.priority.icon.c43d3e065b', 'Priority:')} {label}
         </span>
       </span>
     )
@@ -72,8 +71,7 @@ export function LinearPriorityIcon({
           className="size-3 rounded-full border border-muted-foreground/55"
         />
         <span className="sr-only">
-          {translate('auto.components.linear.priority.icon.c43d3e065b', 'Priority:')}
-          {label}
+          {translate('auto.components.linear.priority.icon.c43d3e065b', 'Priority:')} {label}
         </span>
       </span>
     )
@@ -110,8 +108,7 @@ export function LinearPriorityIcon({
         })}
       </svg>
       <span className="sr-only">
-        {translate('auto.components.linear.priority.icon.c43d3e065b', 'Priority:')}
-        {label}
+        {translate('auto.components.linear.priority.icon.c43d3e065b', 'Priority:')} {label}
       </span>
     </span>
   )
diff --git a/src/renderer/src/components/right-sidebar/FileExplorerTreeStatus.tsx b/src/renderer/src/components/right-sidebar/FileExplorerTreeStatus.tsx
index 7f8d3824151..58fa294e5da 100644
--- a/src/renderer/src/components/right-sidebar/FileExplorerTreeStatus.tsx
+++ b/src/renderer/src/components/right-sidebar/FileExplorerTreeStatus.tsx
@@ -29,7 +29,7 @@ export function FileExplorerTreeStatus({
         {translate(
           'auto.components.right.sidebar.FileExplorerTreeStatus.c76693e456',
           'Could not load files for this workspace:'
-        )}
+        )}{' '}
         {error}
       </div>
     )
diff --git a/src/renderer/src/components/right-sidebar/SourceControlAgentActionDialogForm.tsx b/src/renderer/src/components/right-sidebar/SourceControlAgentActionDialogForm.tsx
index 4f2caf0133b..8f9fff3e657 100644
--- a/src/renderer/src/components/right-sidebar/SourceControlAgentActionDialogForm.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControlAgentActionDialogForm.tsx
@@ -378,7 +378,7 @@ export function SourceControlAgentActionDialogForm({
                   {translate(
                     'auto.components.right.sidebar.SourceControlAgentActionDialogForm.1bc0bdbb5e',
                     'Launch:'
-                  )}
+                  )}{' '}
                   {deliveryPlan.commandLabel}
                 </div>
                 <div className="text-[11px]">{deliveryPlan.caveat}</div>
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-content.tsx b/src/renderer/src/components/right-sidebar/checks-panel-content.tsx
index 84798c944f8..0dd54d7b7dd 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel-content.tsx
+++ b/src/renderer/src/components/right-sidebar/checks-panel-content.tsx
@@ -735,7 +735,7 @@ function CheckRunDetails({
                 {translate(
                   'auto.components.right.sidebar.checks.panel.content.fd46a70f1a',
                   'Started'
-                )}
+                )}{' '}
                 {startedAt}
               </span>
             )}
@@ -744,7 +744,7 @@ function CheckRunDetails({
                 {translate(
                   'auto.components.right.sidebar.checks.panel.content.00e1c1658a',
                   'Completed'
-                )}
+                )}{' '}
                 {completedAt}
               </span>
             )}
diff --git a/src/renderer/src/components/settings/AccountsPane.tsx b/src/renderer/src/components/settings/AccountsPane.tsx
index 5268a890e36..4735f0b06c5 100644
--- a/src/renderer/src/components/settings/AccountsPane.tsx
+++ b/src/renderer/src/components/settings/AccountsPane.tsx
@@ -1501,14 +1501,14 @@ export function AccountsPane({
             {translate(
               'auto.components.settings.AccountsPane.0023cc336e',
               'Paste either the raw token value (e.g.'
-            )}
+            )}{' '}
             <code className="text-xs">
               {translate('auto.components.settings.AccountsPane.922b51e02d', 'Fe26.2**…')}
             </code>
             {translate(
               'auto.components.settings.AccountsPane.338820326a',
               ') or the full cookie header (e.g.'
-            )}
+            )}{' '}
             <code className="text-xs">
               {translate('auto.components.settings.AccountsPane.8951c5309f', 'auth=Fe26.2**…')}
             </code>
diff --git a/src/renderer/src/components/settings/AutoRenameBranchFromWorkSetting.tsx b/src/renderer/src/components/settings/AutoRenameBranchFromWorkSetting.tsx
index b8540cdefa9..c4d520cbdb7 100644
--- a/src/renderer/src/components/settings/AutoRenameBranchFromWorkSetting.tsx
+++ b/src/renderer/src/components/settings/AutoRenameBranchFromWorkSetting.tsx
@@ -159,7 +159,7 @@ export function AutoRenameBranchFromWorkSetting({
             {translate(
               'auto.components.settings.AutoRenameBranchFromWorkSetting.12ea4a408d',
               'When an agent starts working in a new workspace, Orca renames its auto-generated branch (e.g.'
-            )}
+            )}{' '}
             <code>
               {translate(
                 'auto.components.settings.AutoRenameBranchFromWorkSetting.1626524572',
@@ -223,7 +223,7 @@ export function AutoRenameBranchFromWorkSetting({
                   {translate(
                     'auto.components.settings.AutoRenameBranchFromWorkSetting.9241b59bf5',
                     'Use'
-                  )}
+                  )}{' '}
                   <code className="font-mono">
                     {translate(
                       'auto.components.settings.AutoRenameBranchFromWorkSetting.c71770c455',
@@ -261,7 +261,7 @@ export function AutoRenameBranchFromWorkSetting({
                   {translate(
                     'auto.components.settings.AutoRenameBranchFromWorkSetting.56580dcf60',
                     '. You can also reference'
-                  )}
+                  )}{' '}
                   <code className="font-mono">
                     {translate(
                       'auto.components.settings.AutoRenameBranchFromWorkSetting.2ee2779c05',
@@ -281,7 +281,7 @@ export function AutoRenameBranchFromWorkSetting({
                   {translate(
                     'auto.components.settings.AutoRenameBranchFromWorkSetting.5d569f5199',
                     '. Orca generates only the final segment, like'
-                  )}
+                  )}{' '}
                   <code className="font-mono">
                     {translate(
                       'auto.components.settings.AutoRenameBranchFromWorkSetting.800edb1e54',
diff --git a/src/renderer/src/components/settings/BaseRefPicker.tsx b/src/renderer/src/components/settings/BaseRefPicker.tsx
index b0c0b6e72ef..8bb96a508cc 100644
--- a/src/renderer/src/components/settings/BaseRefPicker.tsx
+++ b/src/renderer/src/components/settings/BaseRefPicker.tsx
@@ -195,14 +195,14 @@ export function BaseRefPicker({
               {translate(
                 'auto.components.settings.BaseRefPicker.a5c16712c1',
                 'Multiple remotes detected. Type a remote name (e.g.'
-              )}
+              )}{' '}
               <code>
                 {translate('auto.components.settings.BaseRefPicker.915ad97875', 'upstream')}
               </code>
               {translate(
                 'auto.components.settings.BaseRefPicker.80f7c82303',
                 ') or a full ref (e.g.'
-              )}
+              )}{' '}
               <code>
                 {translate('auto.components.settings.BaseRefPicker.b468f46726', 'upstream/main')}
               </code>
diff --git a/src/renderer/src/components/settings/BrowserSessionCookiesSection.tsx b/src/renderer/src/components/settings/BrowserSessionCookiesSection.tsx
index f1c39ca8fec..8fa1e6c9a60 100644
--- a/src/renderer/src/components/settings/BrowserSessionCookiesSection.tsx
+++ b/src/renderer/src/components/settings/BrowserSessionCookiesSection.tsx
@@ -72,7 +72,7 @@ export function BrowserSessionCookiesSection({
             {translate(
               'auto.components.settings.BrowserPane.cd47bc9622',
               'Select a default profile for new browser tabs. Import cookies and switch profiles per-tab via the'
-            )}
+            )}{' '}
             <strong>···</strong>{' '}
             {translate('auto.components.settings.BrowserPane.e4aaf8051b', 'toolbar menu.')}
           </p>
diff --git a/src/renderer/src/components/settings/CliSection.tsx b/src/renderer/src/components/settings/CliSection.tsx
index 5f61d1e8ef3..6f6eab2ee94 100644
--- a/src/renderer/src/components/settings/CliSection.tsx
+++ b/src/renderer/src/components/settings/CliSection.tsx
@@ -317,7 +317,7 @@ export function CliSection({
             {translate(
               'auto.components.settings.CliSection.b0c310ab46',
               'Existing launcher target:'
-            )}
+            )}{' '}
             <code>{status.currentTarget}</code>
           </p>
         ) : null}
diff --git a/src/renderer/src/components/settings/CommitMessageAiPane.tsx b/src/renderer/src/components/settings/CommitMessageAiPane.tsx
index 9b8ebc6d9ff..e24fc97ee40 100644
--- a/src/renderer/src/components/settings/CommitMessageAiPane.tsx
+++ b/src/renderer/src/components/settings/CommitMessageAiPane.tsx
@@ -273,7 +273,7 @@ export function CommitMessageAiPane({
             {translate(
               'auto.components.settings.CommitMessageAiPane.4f722a5f53',
               'Used by commit-message, pull-request, and branch-name recipes that select Custom command. Use'
-            )}
+            )}{' '}
             <code className="font-mono">
               {translate('auto.components.settings.CommitMessageAiPane.b8b6fd55b4', '{prompt}')}
             </code>{' '}
diff --git a/src/renderer/src/components/settings/GeneralEditorSettingsSection.tsx b/src/renderer/src/components/settings/GeneralEditorSettingsSection.tsx
index 9cccdf166ee..2a524600b07 100644
--- a/src/renderer/src/components/settings/GeneralEditorSettingsSection.tsx
+++ b/src/renderer/src/components/settings/GeneralEditorSettingsSection.tsx
@@ -170,7 +170,7 @@ export function GeneralEditorSettingsSection({
             {translate(
               'auto.components.settings.GeneralEditorSettingsSection.8112cd6dcf',
               'How long Orca waits after your last edit before saving automatically. First launch defaults to'
-            )}
+            )}{' '}
             {DEFAULT_EDITOR_AUTO_SAVE_DELAY_MS}{' '}
             {translate('auto.components.settings.GeneralEditorSettingsSection.fc5c5306ff', 'ms.')}
           </p>
diff --git a/src/renderer/src/components/settings/GeneralUpdateSettingsSection.tsx b/src/renderer/src/components/settings/GeneralUpdateSettingsSection.tsx
index 51668b1ac12..da1984cca0e 100644
--- a/src/renderer/src/components/settings/GeneralUpdateSettingsSection.tsx
+++ b/src/renderer/src/components/settings/GeneralUpdateSettingsSection.tsx
@@ -161,7 +161,7 @@ export function GeneralUpdateSettingsSection(): React.JSX.Element {
               {translate(
                 'auto.components.settings.GeneralUpdateSettingsSection.a6b37929dc',
                 'Version'
-              )}
+              )}{' '}
               {updateStatus.version}{' '}
               {translate(
                 'auto.components.settings.GeneralUpdateSettingsSection.8311da27ba',
@@ -199,7 +199,7 @@ export function GeneralUpdateSettingsSection(): React.JSX.Element {
               {translate(
                 'auto.components.settings.GeneralUpdateSettingsSection.a6b37929dc',
                 'Version'
-              )}
+              )}{' '}
               {updateStatus.version}{' '}
               {translate(
                 'auto.components.settings.GeneralUpdateSettingsSection.d89806cc89',
diff --git a/src/renderer/src/components/settings/GitPane.tsx b/src/renderer/src/components/settings/GitPane.tsx
index 6d346fb1de6..bdfff4a6967 100644
--- a/src/renderer/src/components/settings/GitPane.tsx
+++ b/src/renderer/src/components/settings/GitPane.tsx
@@ -236,11 +236,14 @@ export function GitPane({
             {translate(
               'auto.components.settings.GitPane.976afc6b3e',
               'When you create a workspace, Orca refreshes the remote base and safely fast-forwards your matching local branch, such as'
-            )}
+            )}{' '}
             <code>{translate('auto.components.settings.GitPane.ffba483bae', 'main')}</code>{' '}
-            {translate('auto.components.settings.GitPane.5bf885be48', 'or')}
+            {translate('auto.components.settings.GitPane.5bf885be48', 'or')}{' '}
             <code>{translate('auto.components.settings.GitPane.3ae3de8898', 'master')}</code>
-            {translate('auto.components.settings.GitPane.db3a127eb1', '. This keeps commands like')}
+            {translate(
+              'auto.components.settings.GitPane.db3a127eb1',
+              '. This keeps commands like'
+            )}{' '}
             <code>
               {translate('auto.components.settings.GitPane.d072a12995', 'git diff main...HEAD')}
             </code>{' '}
diff --git a/src/renderer/src/components/settings/ManageSessionKillDialog.tsx b/src/renderer/src/components/settings/ManageSessionKillDialog.tsx
index 56ddb9845ee..04c795f3748 100644
--- a/src/renderer/src/components/settings/ManageSessionKillDialog.tsx
+++ b/src/renderer/src/components/settings/ManageSessionKillDialog.tsx
@@ -66,7 +66,7 @@ export function ManageSessionKillDialog({
                 {translate(
                   'auto.components.settings.ManageSessionKillDialog.8401328fed',
                   'Force-quits'
-                )}
+                )}{' '}
                 <span className="font-medium text-foreground">{session.sessionId}</span>
                 {translate(
                   'auto.components.settings.ManageSessionKillDialog.ad9832aa26',
diff --git a/src/renderer/src/components/settings/NotificationSoundSection.tsx b/src/renderer/src/components/settings/NotificationSoundSection.tsx
index 0d0b92279e7..da1fe4e11cc 100644
--- a/src/renderer/src/components/settings/NotificationSoundSection.tsx
+++ b/src/renderer/src/components/settings/NotificationSoundSection.tsx
@@ -159,7 +159,7 @@ export function NotificationSoundSection({
           className="truncate font-mono text-[11px] text-muted-foreground"
           title={notificationSettings.customSoundPath}
         >
-          {translate('auto.components.settings.NotificationsPane.4aa5085cd7', 'Custom:')}
+          {translate('auto.components.settings.NotificationsPane.4aa5085cd7', 'Custom:')}{' '}
           {notificationSettings.customSoundPath}
         </p>
       ) : null}
diff --git a/src/renderer/src/components/settings/RepositoryHooksSection.tsx b/src/renderer/src/components/settings/RepositoryHooksSection.tsx
index 1ee7cfe19f8..bec7ba52a28 100644
--- a/src/renderer/src/components/settings/RepositoryHooksSection.tsx
+++ b/src/renderer/src/components/settings/RepositoryHooksSection.tsx
@@ -441,7 +441,7 @@ function ExampleTemplateCard({
   return (
     <div className="space-y-2">
       <p className="text-[10px] tracking-[0.18em] text-muted-foreground">
-        {translate('auto.components.settings.RepositoryHooksSection.175daba180', 'Example')}
+        {translate('auto.components.settings.RepositoryHooksSection.175daba180', 'Example')}{' '}
         <code className="rounded bg-muted px-1 py-0.5">
           {translate('auto.components.settings.RepositoryHooksSection.39da2ae12f', 'orca.yaml')}
         </code>{' '}
@@ -665,7 +665,7 @@ function ScriptEditor({
               </span>
             </span>
             <span className="text-[11px] text-muted-foreground">
-              {translate('auto.components.settings.RepositoryHooksSection.b113344b6a', 'Edit')}
+              {translate('auto.components.settings.RepositoryHooksSection.b113344b6a', 'Edit')}{' '}
               <code className="rounded bg-muted px-1 py-0.5">
                 {translate(
                   'auto.components.settings.RepositoryHooksSection.39da2ae12f',
@@ -1308,7 +1308,7 @@ export function RepositoryHooksSection({
                   {translate(
                     'auto.components.settings.RepositoryHooksSection.ac9038d2cc',
                     'When both'
-                  )}
+                  )}{' '}
                   <code className="rounded bg-muted px-1 py-0.5">
                     {translate(
                       'auto.components.settings.RepositoryHooksSection.39da2ae12f',
diff --git a/src/renderer/src/components/settings/RepositoryPane.tsx b/src/renderer/src/components/settings/RepositoryPane.tsx
index bb178d3c17f..a90c94e5ea8 100644
--- a/src/renderer/src/components/settings/RepositoryPane.tsx
+++ b/src/renderer/src/components/settings/RepositoryPane.tsx
@@ -226,7 +226,7 @@ export function RepositoryPane({
               )}
             </p>
             <p className="text-xs text-muted-foreground">
-              {translate('auto.components.settings.RepositoryPane.323debba71', 'Type:')}
+              {translate('auto.components.settings.RepositoryPane.323debba71', 'Type:')}{' '}
               <span className="text-foreground">{getRepoKindLabel(repo)}</span>
             </p>
             {isFolder ? (
diff --git a/src/renderer/src/components/settings/RepositorySourceControlAiHostedReviewDefaults.tsx b/src/renderer/src/components/settings/RepositorySourceControlAiHostedReviewDefaults.tsx
index 7d620ee7ace..07156b38388 100644
--- a/src/renderer/src/components/settings/RepositorySourceControlAiHostedReviewDefaults.tsx
+++ b/src/renderer/src/components/settings/RepositorySourceControlAiHostedReviewDefaults.tsx
@@ -82,7 +82,7 @@ export function RepositorySourceControlAiHostedReviewDefaults({
                   {translate(
                     'auto.components.settings.RepositorySourceControlAiHostedReviewDefaults.a68849a859',
                     'Global default is'
-                  )}
+                  )}{' '}
                   {inherited}.
                 </span>
               </span>
diff --git a/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx b/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx
index 116dc02c5be..af3e2be3ee0 100644
--- a/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx
+++ b/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx
@@ -813,7 +813,7 @@ export function RuntimeEnvironmentsPane({
                   className="h-8 min-w-0 font-mono text-xs"
                 />
                 <p id="runtime-server-pairing-code-help" className="text-xs text-muted-foreground">
-                  {translate('auto.components.settings.RuntimeEnvironmentsPane.163671f7b5', 'Run')}
+                  {translate('auto.components.settings.RuntimeEnvironmentsPane.163671f7b5', 'Run')}{' '}
                   <span className="font-mono">
                     {translate(
                       'auto.components.settings.RuntimeEnvironmentsPane.960e901ae4',
diff --git a/src/renderer/src/components/settings/SshPassphraseDialog.tsx b/src/renderer/src/components/settings/SshPassphraseDialog.tsx
index 7cfb4dbd0b8..56fd3c3d374 100644
--- a/src/renderer/src/components/settings/SshPassphraseDialog.tsx
+++ b/src/renderer/src/components/settings/SshPassphraseDialog.tsx
@@ -133,7 +133,7 @@ export function SshPassphraseDialog(): React.JSX.Element | null {
                 {translate(
                   'auto.components.settings.SshPassphraseDialog.dbf9b6f2d0',
                   'Enter the password for'
-                )}
+                )}{' '}
                 <span className="font-medium">{label}</span>
               </>
             ) : (
@@ -141,7 +141,7 @@ export function SshPassphraseDialog(): React.JSX.Element | null {
                 {translate(
                   'auto.components.settings.SshPassphraseDialog.ce4fdf7914',
                   'Enter the passphrase for'
-                )}
+                )}{' '}
                 <span className="font-medium">{label}</span>
               </>
             )}
diff --git a/src/renderer/src/components/settings/WslCliRegistration.tsx b/src/renderer/src/components/settings/WslCliRegistration.tsx
index 9d23dbeca93..7d01d96d58b 100644
--- a/src/renderer/src/components/settings/WslCliRegistration.tsx
+++ b/src/renderer/src/components/settings/WslCliRegistration.tsx
@@ -217,7 +217,7 @@ export function WslCliRegistration({
             {translate(
               'auto.components.settings.WslCliRegistration.1dbb0377d9',
               'Existing launcher target:'
-            )}
+            )}{' '}
             <code>{status.currentTarget}</code>
           </p>
         ) : null}
diff --git a/src/renderer/src/components/sidebar/DeleteWorktreeWarningPanels.tsx b/src/renderer/src/components/sidebar/DeleteWorktreeWarningPanels.tsx
index 89b22f6c841..b143148249c 100644
--- a/src/renderer/src/components/sidebar/DeleteWorktreeWarningPanels.tsx
+++ b/src/renderer/src/components/sidebar/DeleteWorktreeWarningPanels.tsx
@@ -21,7 +21,7 @@ export function DeleteWorktreeWarningPanels({
               {translate(
                 'auto.components.sidebar.DeleteWorktreeWarningPanels.e3be9eba15',
                 'This is the'
-              )}
+              )}{' '}
               <span className="font-semibold text-foreground">
                 {translate(
                   'auto.components.sidebar.DeleteWorktreeWarningPanels.c4f96a6e18',
@@ -32,7 +32,7 @@ export function DeleteWorktreeWarningPanels({
                 'auto.components.sidebar.DeleteWorktreeWarningPanels.026738155a',
                 '(the original clone directory).'
               )}
-              {mainWorktreeBlocker}
+              {mainWorktreeBlocker ? <> {mainWorktreeBlocker}</> : null}
             </div>
           </div>
         </div>
diff --git a/src/renderer/src/components/sidebar/SetupScriptPromptCardViews.tsx b/src/renderer/src/components/sidebar/SetupScriptPromptCardViews.tsx
index 45f2947d3ed..25a960bff8c 100644
--- a/src/renderer/src/components/sidebar/SetupScriptPromptCardViews.tsx
+++ b/src/renderer/src/components/sidebar/SetupScriptPromptCardViews.tsx
@@ -71,7 +71,7 @@ export function DetectedSetupPreview({
           {translate(
             'auto.components.sidebar.SetupScriptPromptCardViews.d02e6a42b1',
             'Detected from'
-          )}
+          )}{' '}
           <code className="rounded bg-muted px-1 py-0.5">{provenance}</code>
         </p>
       ) : null}
@@ -157,7 +157,7 @@ export function SetupScriptPromptBody({
         {translate(
           'auto.components.sidebar.SetupScriptPromptCardViews.bb879db364',
           'This repo ignores shared'
-        )}
+        )}{' '}
         <code>
           {translate('auto.components.sidebar.SetupScriptPromptCardViews.8f6be51aa1', 'orca.yaml')}
         </code>{' '}
@@ -184,7 +184,7 @@ export function SetupScriptPromptBody({
         {translate(
           'auto.components.sidebar.SetupScriptPromptCardViews.b56d1322f7',
           'Found a setup command in'
-        )}
+        )}{' '}
         <span className="break-words">{candidateSource}</span>
         {translate(
           'auto.components.sidebar.SetupScriptPromptCardViews.8349e3fa4c',
diff --git a/src/renderer/src/components/stats/ShareUsageCard.tsx b/src/renderer/src/components/stats/ShareUsageCard.tsx
index cb6eb5c92bf..dcd2f673cb2 100644
--- a/src/renderer/src/components/stats/ShareUsageCard.tsx
+++ b/src/renderer/src/components/stats/ShareUsageCard.tsx
@@ -233,7 +233,7 @@ function ChartHeader(props: {
       <div style={{ display: 'table-cell', verticalAlign: 'bottom', textAlign: 'right' }}>
         <span style={{ fontSize: 10, color: '#444' }}>
           {props.sessions}{' '}
-          {translate('auto.components.stats.ShareUsageCard.4a4c6c79a3', 'sessions ·')}
+          {translate('auto.components.stats.ShareUsageCard.4a4c6c79a3', 'sessions ·')}{' '}
           {props.turnsOrEvents.count} {props.turnsOrEvents.label}
         </span>
       </div>
diff --git a/src/renderer/src/components/stats/UsageOverviewPane.tsx b/src/renderer/src/components/stats/UsageOverviewPane.tsx
index 1f2080c995d..03001c2bec9 100644
--- a/src/renderer/src/components/stats/UsageOverviewPane.tsx
+++ b/src/renderer/src/components/stats/UsageOverviewPane.tsx
@@ -253,7 +253,7 @@ export function UsageOverviewPane(): React.JSX.Element {
             </h4>
             <p className="text-xs text-muted-foreground">
               {overview.enabledProviderCount}{' '}
-              {translate('auto.components.stats.UsageOverviewPane.ecb0cd8a4c', 'enabled -')}
+              {translate('auto.components.stats.UsageOverviewPane.ecb0cd8a4c', 'enabled -')}{' '}
               {overview.dataProviderCount}{' '}
               {translate('auto.components.stats.UsageOverviewPane.444585cb41', 'with data')}
             </p>
diff --git a/src/renderer/src/lib/i18n-jsx-spacing-guard.test.ts b/src/renderer/src/lib/i18n-jsx-spacing-guard.test.ts
new file mode 100644
index 00000000000..f2dde24571e
--- /dev/null
+++ b/src/renderer/src/lib/i18n-jsx-spacing-guard.test.ts
@@ -0,0 +1,140 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Guard against the i18n fragment glue-word class of bugs:
+ * `translate('…', 'word')}` immediately followed by `<code>` / `{value}` without
+ * an explicit `{' '}` space. Newline indentation alone is not reliable.
+ */
+const ROOT = path.resolve(__dirname, '..')
+
+type GuardCase = {
+  file: string
+  /** English fallback that must be followed by `{' '}` before the next token. */
+  afterFallback: string
+  /** Human-readable description for assertion messages. */
+  label: string
+}
+
+const CASES: GuardCase[] = [
+  {
+    file: 'components/sidebar/SetupScriptPromptCardViews.tsx',
+    afterFallback: 'This repo ignores shared',
+    label: 'shared orca.yaml'
+  },
+  {
+    file: 'components/sidebar/SetupScriptPromptCardViews.tsx',
+    afterFallback: 'Detected from',
+    label: 'Detected from provenance'
+  },
+  {
+    file: 'components/sidebar/SetupScriptPromptCardViews.tsx',
+    afterFallback: 'Found a setup command in',
+    label: 'Found a setup command in source'
+  },
+  {
+    file: 'components/settings/RepositoryHooksSection.tsx',
+    afterFallback: 'Example',
+    label: 'Example orca.yaml template'
+  },
+  {
+    file: 'components/settings/RepositoryHooksSection.tsx',
+    afterFallback: 'Edit',
+    label: 'Edit orca.yaml'
+  },
+  {
+    file: 'components/settings/RepositoryHooksSection.tsx',
+    afterFallback: 'When both',
+    label: 'When both orca.yaml'
+  },
+  {
+    file: 'components/settings/GitPane.tsx',
+    afterFallback: 'or',
+    label: 'main or master'
+  },
+  {
+    file: 'components/settings/GitPane.tsx',
+    afterFallback: 'such as',
+    label: 'such as main'
+  },
+  {
+    file: 'components/settings/RuntimeEnvironmentsPane.tsx',
+    afterFallback: 'Run',
+    label: 'Run orca serve'
+  },
+  {
+    file: 'components/settings/AutoRenameBranchFromWorkSetting.tsx',
+    afterFallback: 'Use',
+    label: 'Use {basePrompt}'
+  },
+  {
+    file: 'components/settings/CommitMessageAiPane.tsx',
+    afterFallback: 'Use',
+    label: 'Use {prompt}'
+  },
+  {
+    file: 'components/editor/RichMarkdownDocLinkMenu.tsx',
+    afterFallback: 'Showing',
+    label: 'Showing N of M'
+  },
+  {
+    file: 'components/editor/RichMarkdownDocLinkMenu.tsx',
+    afterFallback: 'of',
+    label: 'of totalMatches'
+  },
+  {
+    file: 'components/contextual-tours/ContextualTourProgressDots.tsx',
+    afterFallback: 'of',
+    label: 'tour of total'
+  },
+  {
+    file: 'components/github/PRFilterSections.tsx',
+    afterFallback: 'Filter',
+    label: 'Filter pull requests'
+  },
+  {
+    file: 'components/editor/ConflictComponents.tsx',
+    afterFallback: 'Renamed from',
+    label: 'Renamed from path'
+  },
+  {
+    file: 'components/settings/SshPassphraseDialog.tsx',
+    afterFallback: 'Enter the password for',
+    label: 'password for host'
+  },
+  {
+    file: 'components/settings/ManageSessionKillDialog.tsx',
+    afterFallback: 'Force-quits',
+    label: 'Force-quits session id'
+  },
+  {
+    file: 'components/sidebar/DeleteWorktreeWarningPanels.tsx',
+    afterFallback: 'This is the',
+    label: 'This is the main worktree'
+  }
+]
+
+function hasExplicitSpaceAfterFallback(source: string, fallback: string): boolean {
+  // Match translate fallbacks that end with (or equal) the given phrase, then
+  // require an explicit {' '} after the closing )} so JSX whitespace is not
+  // left to indentation alone.
+  const escaped = fallback.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const pattern = new RegExp(
+    String.raw`translate\(\s*'[^']+',\s*(?:'[^']*${escaped}'|"[^"]*${escaped}")\s*(?:,\s*\{[^}]*\})?\s*\)\s*\}\s*\{\s*['"]\s['"]\s*\}`,
+    'm'
+  )
+  return pattern.test(source)
+}
+
+describe('i18n JSX fragment spacing guard', () => {
+  for (const testCase of CASES) {
+    it(`keeps an explicit space after "${testCase.label}" in ${testCase.file}`, () => {
+      const source = readFileSync(path.join(ROOT, testCase.file), 'utf8')
+      expect(
+        hasExplicitSpaceAfterFallback(source, testCase.afterFallback),
+        `Expected {' '} immediately after translate fallback "${testCase.afterFallback}" in ${testCase.file}`
+      ).toBe(true)
+    })
+  }
+})

From 74e2cb702ca34f171cdef140358dbf14a49d57f6 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sun, 19 Jul 2026 21:30:01 -0700
Subject: [PATCH 26/54] perf(window): re-enable macOS main-window background
 throttling (#9395)

Co-authored-by: Orca <help@stably.ai>
---
 src/main/startup/configure-process.test.ts | 14 ++++
 src/main/startup/configure-process.ts      | 12 ++++
 src/main/window/createMainWindow.test.ts   | 74 ++++++++++++++++++++++
 src/main/window/createMainWindow.ts        | 65 +++++++++++++++----
 4 files changed, 151 insertions(+), 14 deletions(-)

diff --git a/src/main/startup/configure-process.test.ts b/src/main/startup/configure-process.test.ts
index 72a545a3988..08cd8139e93 100644
--- a/src/main/startup/configure-process.test.ts
+++ b/src/main/startup/configure-process.test.ts
@@ -297,6 +297,20 @@ describe('enableMainProcessGpuFeatures', () => {
     expect(app.commandLine.appendSwitch).not.toHaveBeenCalledWith('enable-unsafe-webgpu')
   })
 
+  it('opts hidden pages out of intensive wake-up throttling', async () => {
+    const { app } = await import('electron')
+    const { enableMainProcessGpuFeatures } = await import('./configure-process')
+
+    delete process.env.ORCA_E2E_USER_DATA_DIR
+    vi.mocked(app.commandLine.appendSwitch).mockClear()
+    enableMainProcessGpuFeatures()
+
+    expect(app.commandLine.appendSwitch).toHaveBeenCalledWith(
+      'disable-features',
+      'IntensiveWakeUpThrottling'
+    )
+  })
+
   it('raises the WebGL context budget above the 16-context Blink default', async () => {
     const { app } = await import('electron')
     const { enableMainProcessGpuFeatures } = await import('./configure-process')
diff --git a/src/main/startup/configure-process.ts b/src/main/startup/configure-process.ts
index e92c53e4b0d..e033e4e94de 100644
--- a/src/main/startup/configure-process.ts
+++ b/src/main/startup/configure-process.ts
@@ -344,4 +344,16 @@ export function enableMainProcessGpuFeatures(): void {
   if (features) {
     app.commandLine.appendSwitch('enable-features', features)
   }
+
+  const existingDisabledFeatures = app.commandLine.getSwitchValue('disable-features')
+  // Why: with main-window background throttling on, Chromium's intensive mode
+  // clamps hidden-page timers to 1/min after 5 minutes, delaying agent-done and
+  // bell notifications by up to 60s. Keep the normal 1s hidden clamp (rAF and
+  // rendering still stop) but opt out of the 1/min tier. Callers skip this
+  // function under GPU fallback (win32-only today); if throttling ever extends
+  // to Windows, this opt-out must move out of the GPU-gated path.
+  const disabledFeatures = ['IntensiveWakeUpThrottling', existingDisabledFeatures]
+    .filter(Boolean)
+    .join(',')
+  app.commandLine.appendSwitch('disable-features', disabledFeatures)
 }
diff --git a/src/main/window/createMainWindow.test.ts b/src/main/window/createMainWindow.test.ts
index 8899ba81bbf..3b69b9c1253 100644
--- a/src/main/window/createMainWindow.test.ts
+++ b/src/main/window/createMainWindow.test.ts
@@ -299,6 +299,80 @@ describe('createMainWindow', () => {
     }
   })
 
+  it('keeps main-window background throttling enabled while repainting macOS visibility transitions', () => {
+    vi.useFakeTimers()
+    const windowHandlers = new Map<string, ((...args: any[]) => void)[]>()
+    let windowSize: [number, number] = [1200, 800]
+    const webContents = {
+      on: vi.fn(),
+      setZoomLevel: vi.fn(),
+      setBackgroundThrottling: vi.fn(),
+      invalidate: vi.fn(),
+      isDestroyed: vi.fn(() => false),
+      setWindowOpenHandler: vi.fn(),
+      send: vi.fn(),
+      isDevToolsOpened: vi.fn(),
+      openDevTools: vi.fn(),
+      closeDevTools: vi.fn()
+    }
+    const browserWindowInstance = {
+      webContents,
+      on: vi.fn((event: string, handler: (...args: any[]) => void) => {
+        const handlers = windowHandlers.get(event) ?? []
+        handlers.push(handler)
+        windowHandlers.set(event, handlers)
+      }),
+      isDestroyed: vi.fn(() => false),
+      isMaximized: vi.fn(() => false),
+      isFullScreen: vi.fn(() => false),
+      getSize: vi.fn(() => windowSize),
+      setSize: vi.fn((width: number, height: number) => {
+        windowSize = [width, height]
+      }),
+      maximize: vi.fn(),
+      show: vi.fn(),
+      loadFile: vi.fn(),
+      loadURL: vi.fn()
+    }
+    browserWindowMock.mockImplementation(function () {
+      return browserWindowInstance
+    })
+
+    withPlatform('darwin', () => createMainWindow(null))
+
+    // Why: throttling-off pins visibilityState 'visible' and renders occluded
+    // windows at full rate; this guards against reintroducing it.
+    expect(webContents.setBackgroundThrottling).not.toHaveBeenCalledWith(false)
+
+    expect(webContents.setBackgroundThrottling).toHaveBeenCalledWith(true)
+    expect(windowHandlers.get('restore')).toHaveLength(1)
+    expect(windowHandlers.get('show')).toHaveLength(1)
+    expect(windowHandlers.get('focus')).toHaveLength(1)
+
+    windowHandlers.get('show')?.[0]?.()
+    windowHandlers.get('restore')?.[0]?.()
+
+    expect(webContents.invalidate).toHaveBeenCalledTimes(2)
+    expect(browserWindowInstance.setSize).toHaveBeenNthCalledWith(1, 1201, 800)
+    expect(browserWindowInstance.setSize).toHaveBeenCalledTimes(1)
+
+    vi.advanceTimersByTime(32)
+    expect(browserWindowInstance.setSize).toHaveBeenNthCalledWith(2, 1200, 800)
+
+    vi.advanceTimersByTime(217)
+    expect(webContents.invalidate).toHaveBeenCalledTimes(2)
+
+    vi.advanceTimersByTime(1)
+    expect(webContents.invalidate).toHaveBeenCalledTimes(3)
+
+    // Why: focus covers occlusion-uncover with invalidate only — no setSize
+    // jiggle that would resize terminals on every window focus.
+    const setSizeCalls = browserWindowInstance.setSize.mock.calls.length
+    windowHandlers.get('focus')?.[0]?.()
+    expect(webContents.invalidate).toHaveBeenCalledTimes(4)
+    expect(browserWindowInstance.setSize).toHaveBeenCalledTimes(setSizeCalls)
+  })
+
   it('supports all minus key variants for terminal zoom out', () => {
     const windowHandlers: Record<string, (...args: any[]) => void> = {}
     const webContents = {
diff --git a/src/main/window/createMainWindow.ts b/src/main/window/createMainWindow.ts
index 52c84ec6048..b12583377b1 100644
--- a/src/main/window/createMainWindow.ts
+++ b/src/main/window/createMainWindow.ts
@@ -50,23 +50,65 @@ import { buildEditableContextMenuTemplate } from './editable-context-menu'
 import { clearTrustedUIRendererWebContentsId, setTrustedUIRendererWebContentsId } from '../ipc/ui'
 import { resolveWindowCloseAction } from './window-close-decision'
 
+// Why: show/restore/resume can overlap before the size nudge resets; never
+// capture the temporary width as the next repaint's baseline.
+const activeRepaintJiggles = new WeakSet<BrowserWindow>()
+
 function forceRepaint(window: BrowserWindow): void {
-  if (window.isDestroyed()) {
+  // Why: webContents can be destroyed a beat before the BrowserWindow during
+  // close, and this runs from timers/focus events that can land in that gap.
+  if (window.isDestroyed() || window.webContents.isDestroyed()) {
     return
   }
   window.webContents.invalidate()
-  if (window.isMaximized() || window.isFullScreen()) {
+  if (window.isMaximized() || window.isFullScreen() || activeRepaintJiggles.has(window)) {
     return
   }
+  activeRepaintJiggles.add(window)
   const [width, height] = window.getSize()
   window.setSize(width + 1, height)
   setTimeout(() => {
     if (!window.isDestroyed()) {
       window.setSize(width, height)
     }
+    activeRepaintJiggles.delete(window)
   }, 32)
 }
 
+function installMacosVisibilityRepaint(window: BrowserWindow): void {
+  let delayedRepaintTimer: ReturnType<typeof setTimeout> | null = null
+  const repaintAfterVisibilityTransition = (): void => {
+    forceRepaint(window)
+    if (delayedRepaintTimer) {
+      clearTimeout(delayedRepaintTimer)
+    }
+    // Why: macOS can finish restoring webview compositor layers after Electron's
+    // show/restore event, so a second paint catches late black-surface recovery.
+    delayedRepaintTimer = setTimeout(() => {
+      delayedRepaintTimer = null
+      forceRepaint(window)
+    }, 250)
+  }
+  const clearDelayedRepaint = (): void => {
+    if (delayedRepaintTimer) {
+      clearTimeout(delayedRepaintTimer)
+      delayedRepaintTimer = null
+    }
+  }
+
+  window.on('restore', repaintAfterVisibilityTransition)
+  window.on('show', repaintAfterVisibilityTransition)
+  // Why: occlusion-uncover fires neither restore nor show; focus is the only
+  // signal. Invalidate only — the setSize jiggle would SIGWINCH every terminal
+  // on each Cmd+Tab.
+  window.on('focus', () => {
+    if (!window.isDestroyed() && !window.webContents.isDestroyed()) {
+      window.webContents.invalidate()
+    }
+  })
+  window.on('closed', clearDelayedRepaint)
+}
+
 function isMacAppPasteInput(input: Electron.Input): boolean {
   return (
     process.platform === 'darwin' &&
@@ -293,18 +335,13 @@ export function createMainWindow(
   setTrustedUIRendererWebContentsId(rendererWebContentsId)
 
   if (process.platform === 'darwin') {
-    // Why: persistent browser webviews use separate compositor layers, and on
-    // recent macOS releases those layers can fail to repaint after occlusion or
-    // restore. Disabling main-window throttling and forcing a repaint on
-    // visibility transitions hardens Orca against black-surface failures during
-    // browser-tab restore and tab switching.
-    mainWindow.webContents.setBackgroundThrottling(false)
-    mainWindow.on('restore', () => {
-      forceRepaint(mainWindow)
-    })
-    mainWindow.on('show', () => {
-      forceRepaint(mainWindow)
-    })
+    // Why: browser-guest surfaces are kept alive by their own per-guest
+    // unthrottle (browser-manager attach), so the main window can throttle
+    // normally while hidden/occluded instead of rendering at full rate.
+    // Toggling must happen only while visible: flipping it on a hidden window
+    // desyncs Chromium's frame evictor and blanks the surface (electron#42378).
+    mainWindow.webContents.setBackgroundThrottling(true)
+    installMacosVisibilityRepaint(mainWindow)
   }
 
   // Why: a focus-preserving system/display wake fires no window focus or

From e90dc38f01670ff2da0d1eb36fc051961efca09f Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sun, 19 Jul 2026 21:31:36 -0700
Subject: [PATCH 27/54] fix(dev): stabilize macOS safeStorage Keychain key name
 across dev branches (#9400)

Co-authored-by: Orca <help@stably.ai>
---
 src/main/index.ts                              |  7 ++++++-
 src/main/menu/register-app-menu.ts             |  5 ++++-
 src/main/startup/dev-instance-identity.test.ts | 13 +++++++++++++
 src/main/startup/dev-instance-identity.ts      | 10 ++++++++++
 4 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/src/main/index.ts b/src/main/index.ts
index 9278eb043ec..312b8bfd9cf 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1766,7 +1766,11 @@ app.whenReady().then(async () => {
     }
   )
   electronApp.setAppUserModelId(devInstanceIdentity.appUserModelId)
-  app.setName(devInstanceIdentity.name)
+  // Why: setName drives the macOS safeStorage Keychain item name. Use the stable
+  // appName (not the per-branch `name`) so dev branches share one key and don't
+  // re-prompt per branch; the per-branch label still shows via window title,
+  // renderer identity, and the app-menu label passed to registerAppMenu below.
+  app.setName(devInstanceIdentity.appName)
 
   // Why: managed WSL launchers live outside the Windows app bundle, so keep
   // their launcher and bridge contract synchronized across app updates.
@@ -2138,6 +2142,7 @@ app.whenReady().then(async () => {
   logStartupMilestone('i18n-ready')
 
   registerAppMenu({
+    appMenuLabel: devInstanceIdentity.name,
     onCheckForUpdates: (options) => runUserInitiatedUpdateCheck(options),
     onBeforeReload: ({ ignoreCache, webContentsId }) => {
       if (mainWindow?.webContents.id === webContentsId) {
diff --git a/src/main/menu/register-app-menu.ts b/src/main/menu/register-app-menu.ts
index c36aca6973a..2f3a3d70a97 100644
--- a/src/main/menu/register-app-menu.ts
+++ b/src/main/menu/register-app-menu.ts
@@ -37,6 +37,9 @@ type RegisterAppMenuOptions = {
   onToggleAppearance: (key: AppearanceMenuKey) => void
   getAppearanceState: () => AppearanceMenuState
   getKeybindings?: () => KeybindingOverrides | undefined
+  // Why: the macOS app-menu title. Passed the per-branch dev label since
+  // app.name is now pinned to a stable value for Keychain-key stability.
+  appMenuLabel?: string
 }
 
 function buildAndApplyMenu(options: RegisterAppMenuOptions): void {
@@ -130,7 +133,7 @@ function buildAndApplyMenu(options: RegisterAppMenuOptions): void {
   // redundant "Orca" entry with roles that don't apply, so we omit it there
   // and distribute its items across File / Help instead.
   const macAppMenu: Electron.MenuItemConstructorOptions = {
-    label: app.name,
+    label: options.appMenuLabel ?? app.name,
     submenu: [
       { role: 'about' },
       checkForUpdatesItem,
diff --git a/src/main/startup/dev-instance-identity.test.ts b/src/main/startup/dev-instance-identity.test.ts
index 2021dfed224..2b06e85dda4 100644
--- a/src/main/startup/dev-instance-identity.test.ts
+++ b/src/main/startup/dev-instance-identity.test.ts
@@ -5,6 +5,7 @@ describe('dev-instance-identity', () => {
   it('keeps packaged identity stable', () => {
     expect(getDevInstanceIdentity(false, {})).toMatchObject({
       name: 'Orca',
+      appName: 'Orca',
       isDev: false,
       devLabel: null,
       dockBadgeLabel: null,
@@ -12,6 +13,18 @@ describe('dev-instance-identity', () => {
     })
   })
 
+  it('pins a stable dev appName across branches so the safeStorage key does not churn', () => {
+    const a = getDevInstanceIdentity(true, { ORCA_DEV_BRANCH: 'feature/a' })
+    const b = getDevInstanceIdentity(true, { ORCA_DEV_BRANCH: 'feature/b' })
+
+    // Per-branch label differs (window title / app menu)...
+    expect(a.name).not.toBe(b.name)
+    // ...but the Keychain-driving appName is identical and distinct from prod.
+    expect(a.appName).toBe('Orca Dev')
+    expect(b.appName).toBe('Orca Dev')
+    expect(a.appName).not.toBe('Orca')
+  })
+
   it('derives a readable dev label from worktree and branch env', () => {
     const identity = getDevInstanceIdentity(true, {
       ORCA_DEV_REPO_ROOT: '/repo/worktrees/dev-indicator',
diff --git a/src/main/startup/dev-instance-identity.ts b/src/main/startup/dev-instance-identity.ts
index b375e88bba7..6d13541ea1f 100644
--- a/src/main/startup/dev-instance-identity.ts
+++ b/src/main/startup/dev-instance-identity.ts
@@ -8,6 +8,11 @@ const MAX_LABEL_LENGTH = 80
 
 export type DevInstanceIdentity = AppIdentity & {
   appUserModelId: string
+  // Why: drives app.setName → the macOS safeStorage Keychain item name
+  // ("<appName> Safe Storage"). Kept stable across dev branches (unlike the
+  // per-branch `name`) so every dev instance shares one Keychain key instead of
+  // creating a new one per branch and re-prompting. Distinct from prod's 'Orca'.
+  appName: string
 }
 
 function cleanEnvValue(value: string | undefined): string | null {
@@ -50,6 +55,7 @@ export function getDevInstanceIdentity(
   if (!isDev) {
     return {
       name: BASE_APP_NAME,
+      appName: BASE_APP_NAME,
       isDev: false,
       devLabel: null,
       devBranch: null,
@@ -71,6 +77,10 @@ export function getDevInstanceIdentity(
 
   return {
     name: dockTitle,
+    // Why: one stable Keychain key ('Orca Dev Safe Storage') for all dev
+    // branches; the per-branch identity still shows via `name` (window title,
+    // app menu, renderer label).
+    appName: `${BASE_APP_NAME} Dev`,
     isDev: true,
     devLabel,
     devBranch: branch,

From a02389cea809239c7d38409e62b957b2dcaf66e1 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sun, 19 Jul 2026 21:40:49 -0700
Subject: [PATCH 28/54] Update code comments section in AGENTS.md

Clarified guidelines for code comments, emphasizing the importance of explaining the 'why' behind non-obvious code.
---
 AGENTS.md | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 2c117478e84..1fd213f742e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,12 +5,7 @@
 All UI work — layout, color, typography, spacing, component selection, UX behavior — must follow [`docs/STYLEGUIDE.md`](./docs/STYLEGUIDE.md). Use the tokens defined in `src/renderer/src/assets/main.css` (the canonical source) and the shadcn primitives in `src/renderer/src/components/ui/`. Don't invent new color values, font sizes, or shadow tiers when a documented one already covers the role. When STYLEGUIDE.md is silent, follow the resolution order in its final section.
 
 ## Code Comments: Document the "Why", Briefly
-
-When writing or modifying code driven by a design doc or non-obvious constraint, add a comment explaining **why** the code behaves the way it does.
-
-Keep comments short — one or two lines. Capture only the non-obvious reason (safety constraint, compatibility shim, design-doc rule). Don't restate what the code does, narrate the mechanism, cite design-doc sections verbatim, or explain adjacent API choices unless they're the point.
-
-The comment's audience is the next person reading that line, not a PR description. If a comment lists call sites, recounts the crash/history, or re-describes the code below it, cut it to the one non-obvious fact:
+When code is non-obvious, Add code comments explaining **why** (not HOW). BE CONCISE — ideally 1 line.
 
 ```ts
 // 🚫 Over-explained — narrates the crash, the mechanism, where the helper lives, and every caller:

From 64dae13bc9b5bfb7d27ae42d8f593913344c064e Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Mon, 20 Jul 2026 01:18:27 -0400
Subject: [PATCH 29/54] fix(sidebar): stop agent 'working' spinner freezing as
 a broken ring under reduced motion (#9515)

Under prefers-reduced-motion (Windows 'Animation effects' off), the agent
'working' spinner froze mid-rotation as a partial (3/4) ring, reading as a
broken spinner in the terminal tab and worktree card. Fill the top border so
it becomes a complete static ring, and apply the same treatment to
StatusIndicator so the sidebar dot honors reduced motion consistently instead
of stepping. Mirrors the existing feature-tour-preview-glyphs pattern.

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
---
 src/renderer/src/components/AgentStateDot.test.ts         | 3 +++
 src/renderer/src/components/AgentStateDot.tsx             | 5 ++++-
 .../src/components/sidebar/StatusIndicator.test.ts        | 4 ++++
 src/renderer/src/components/sidebar/StatusIndicator.tsx   | 8 ++++++--
 4 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/src/renderer/src/components/AgentStateDot.test.ts b/src/renderer/src/components/AgentStateDot.test.ts
index 2e17d0423df..11297224433 100644
--- a/src/renderer/src/components/AgentStateDot.test.ts
+++ b/src/renderer/src/components/AgentStateDot.test.ts
@@ -24,6 +24,9 @@ describe('AgentStateDot', () => {
     expect(markup).toContain('border-t-transparent')
     expect(markup).toContain('[animation:spin_1s_steps(12,end)_infinite]')
     expect(markup).toContain('motion-reduce:animate-none')
+    // Why: under reduced motion the top border is filled so the frozen ring
+    // reads as a complete static marker, not a broken partial spinner.
+    expect(markup).toContain('motion-reduce:border-t-yellow-500')
     expect(markup).not.toContain('animate-spin')
   })
 
diff --git a/src/renderer/src/components/AgentStateDot.tsx b/src/renderer/src/components/AgentStateDot.tsx
index 9a4fe792e13..7543de46fac 100644
--- a/src/renderer/src/components/AgentStateDot.tsx
+++ b/src/renderer/src/components/AgentStateDot.tsx
@@ -78,7 +78,10 @@ export const AgentStateDot = React.memo(function AgentStateDot({
           className={cn(
             // Why: match the sidebar worktree spinner's stepped cadence so
             // long-running visible agents do not keep a full-frame-rate loop.
-            'block rounded-full border-2 border-yellow-500 border-t-transparent [animation:spin_1s_steps(12,end)_infinite] motion-reduce:animate-none',
+            // Why: under reduced motion the spin is disabled, so fill the top
+            // border too — a frozen transparent-top ring reads as a broken
+            // spinner; a complete ring reads as an intentional static marker.
+            'block rounded-full border-2 border-yellow-500 border-t-transparent [animation:spin_1s_steps(12,end)_infinite] motion-reduce:animate-none motion-reduce:border-t-yellow-500',
             inner
           )}
         />
diff --git a/src/renderer/src/components/sidebar/StatusIndicator.test.ts b/src/renderer/src/components/sidebar/StatusIndicator.test.ts
index 5f9061eb937..0179a0bac02 100644
--- a/src/renderer/src/components/sidebar/StatusIndicator.test.ts
+++ b/src/renderer/src/components/sidebar/StatusIndicator.test.ts
@@ -23,6 +23,10 @@ describe('StatusIndicator', () => {
     expect(classNames).toContain('border-yellow-500')
     expect(classNames).toContain('border-t-transparent')
     expect(classNames).toContain('[animation:spin_1s_steps(12,end)_infinite]')
+    // Why: under reduced motion the spin is disabled and the top border filled,
+    // so the dot stays a complete static ring rather than freezing mid-rotation.
+    expect(classNames).toContain('motion-reduce:animate-none')
+    expect(classNames).toContain('motion-reduce:border-t-yellow-500')
     expect(classNames).not.toContain('animate-spin')
   })
 
diff --git a/src/renderer/src/components/sidebar/StatusIndicator.tsx b/src/renderer/src/components/sidebar/StatusIndicator.tsx
index 34c1491095f..c181e0c297d 100644
--- a/src/renderer/src/components/sidebar/StatusIndicator.tsx
+++ b/src/renderer/src/components/sidebar/StatusIndicator.tsx
@@ -34,8 +34,12 @@ const StatusIndicator = React.memo(function StatusIndicator({
         {...rest}
       >
         {/* Why: a stepped spin preserves the worker-is-running affordance while
-            avoiding a full-refresh-rate compositor loop for long agent runs. */}
-        <span className="block size-2 rounded-full border-2 border-yellow-500 border-t-transparent [animation:spin_1s_steps(12,end)_infinite]" />
+            avoiding a full-refresh-rate compositor loop for long agent runs.
+            Why: honor reduced motion (Windows "Animation effects" off →
+            prefers-reduced-motion) by stopping the spin and filling the top
+            border, so the dot stays a complete static ring instead of a
+            partial ring frozen mid-rotation that reads as a broken spinner. */}
+        <span className="block size-2 rounded-full border-2 border-yellow-500 border-t-transparent [animation:spin_1s_steps(12,end)_infinite] motion-reduce:animate-none motion-reduce:border-t-yellow-500" />
       </span>
     )
   }

From 4d25de383e0c294c539b6101281e30a44c772120 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sun, 19 Jul 2026 22:53:32 -0700
Subject: [PATCH 30/54] perf(renderer): stop agent spinners from keeping the
 frame pipeline awake (one shared clock, hidden-window stop) (#9380)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* perf(renderer): drive agent working-spinners from one shared clock

Per-element infinite CSS spin animations kept Chromium's frame pipeline
awake for the whole agent run — measured live (interleaved A/B/A/B,
renderer+GPU): 86.0/76.0 ms CPU/s with the CSS animation vs 61.0/61.0
with the clock, one working agent, and the CSS cost scales per element
while the clock is one flat timer for N spinners.

The clock ticks 12 steps/s at 30° — frame-for-frame identical to the
retired animation — writes style.transform on registered elements, and
stops on document hidden (native visibilitychange post-#9395), under
prefers-reduced-motion (static ring keeps the filled top border from
#9515), and when the last spinner unmounts. The stale-visibility latch
keeps it spinning when proven user input contradicts the occlusion
tracker.

Co-authored-by: Orca <help@stably.ai>

* fix(github): restore explicit space after Filter fallback in PRFilterSections

Pre-existing failure on main: i18n-jsx-spacing-guard requires {' '} after
the 'Filter' translate fallback, but the file had a bare JSX space (which
oxfmt collapses). Wrap the subject in a span so the explicit {' '} survives
formatting, matching the pattern in the other guarded files.

Co-authored-by: Orca <help@stably.ai>

---------

Co-authored-by: Orca <help@stably.ai>
---
 .../src/components/AgentStateDot.test.ts      |  11 +-
 src/renderer/src/components/AgentStateDot.tsx |  13 +-
 .../src/components/AgentWorkingSpinner.tsx    |  23 +++
 .../components/github/PRFilterSections.tsx    |   3 +-
 .../sidebar/StatusIndicator.test.ts           |  22 +--
 .../components/sidebar/StatusIndicator.tsx    |   9 +-
 .../tab-bar/TerminalTabLeadingIcon.test.tsx   |   2 +-
 .../src/lib/agent-spinner-clock.test.ts       | 141 ++++++++++++++++++
 src/renderer/src/lib/agent-spinner-clock.ts   | 128 ++++++++++++++++
 9 files changed, 318 insertions(+), 34 deletions(-)
 create mode 100644 src/renderer/src/components/AgentWorkingSpinner.tsx
 create mode 100644 src/renderer/src/lib/agent-spinner-clock.test.ts
 create mode 100644 src/renderer/src/lib/agent-spinner-clock.ts

diff --git a/src/renderer/src/components/AgentStateDot.test.ts b/src/renderer/src/components/AgentStateDot.test.ts
index 11297224433..40c2bea60f3 100644
--- a/src/renderer/src/components/AgentStateDot.test.ts
+++ b/src/renderer/src/components/AgentStateDot.test.ts
@@ -22,12 +22,15 @@ describe('AgentStateDot', () => {
 
     expect(markup).toContain('border-yellow-500')
     expect(markup).toContain('border-t-transparent')
-    expect(markup).toContain('[animation:spin_1s_steps(12,end)_infinite]')
-    expect(markup).toContain('motion-reduce:animate-none')
-    // Why: under reduced motion the top border is filled so the frozen ring
-    // reads as a complete static marker, not a broken partial spinner.
+    // Why: rotation comes from the shared agent-spinner clock (which also
+    // honors prefers-reduced-motion), not a per-element CSS animation that
+    // would keep the compositor awake.
+    expect(markup).toContain('data-agent-spinner')
+    // Why: under reduced motion the top border is filled so the static ring
+    // reads as a complete marker, not a broken partial spinner (#9515).
     expect(markup).toContain('motion-reduce:border-t-yellow-500')
     expect(markup).not.toContain('animate-spin')
+    expect(markup).not.toContain('animation:spin')
   })
 
   it('renders done as an emerald check icon', () => {
diff --git a/src/renderer/src/components/AgentStateDot.tsx b/src/renderer/src/components/AgentStateDot.tsx
index 7543de46fac..a5c50dad1fe 100644
--- a/src/renderer/src/components/AgentStateDot.tsx
+++ b/src/renderer/src/components/AgentStateDot.tsx
@@ -1,6 +1,7 @@
 import React from 'react'
 import { CircleCheck } from 'lucide-react'
 import { cn } from '@/lib/utils'
+import { AgentWorkingSpinner } from '@/components/AgentWorkingSpinner'
 
 // Why: shared state-indicator primitive so the dashboard and the sidebar's
 // agent hover share a single state vocabulary. Most states render as a dot;
@@ -74,17 +75,7 @@ export const AgentStateDot = React.memo(function AgentStateDot({
         className={cn('inline-flex shrink-0 items-center justify-center', box, className)}
         aria-label={agentStateLabel(state)}
       >
-        <span
-          className={cn(
-            // Why: match the sidebar worktree spinner's stepped cadence so
-            // long-running visible agents do not keep a full-frame-rate loop.
-            // Why: under reduced motion the spin is disabled, so fill the top
-            // border too — a frozen transparent-top ring reads as a broken
-            // spinner; a complete ring reads as an intentional static marker.
-            'block rounded-full border-2 border-yellow-500 border-t-transparent [animation:spin_1s_steps(12,end)_infinite] motion-reduce:animate-none motion-reduce:border-t-yellow-500',
-            inner
-          )}
-        />
+        <AgentWorkingSpinner className={inner} />
       </span>
     )
   }
diff --git a/src/renderer/src/components/AgentWorkingSpinner.tsx b/src/renderer/src/components/AgentWorkingSpinner.tsx
new file mode 100644
index 00000000000..7e3d3302a7e
--- /dev/null
+++ b/src/renderer/src/components/AgentWorkingSpinner.tsx
@@ -0,0 +1,23 @@
+import React from 'react'
+import { cn } from '@/lib/utils'
+import { agentSpinnerRef } from '@/lib/agent-spinner-clock'
+
+// Why: the working-state ring must not carry its own infinite CSS animation —
+// that keeps the compositor awake per element for the whole agent run. The
+// shared agent-spinner clock rotates every mounted ring in phase and stops
+// cleanly when nothing can be seen. Callers size it via className (size-2 etc.).
+export function AgentWorkingSpinner({ className }: { className?: string }): React.JSX.Element {
+  return (
+    <span
+      ref={agentSpinnerRef}
+      data-agent-spinner=""
+      className={cn(
+        // Why: under reduced motion the clock never ticks, so fill the top
+        // border too — a frozen transparent-top ring reads as a broken
+        // spinner; a complete ring reads as an intentional static marker (#9515).
+        'block rounded-full border-2 border-yellow-500 border-t-transparent motion-reduce:border-t-yellow-500',
+        className
+      )}
+    />
+  )
+}
diff --git a/src/renderer/src/components/github/PRFilterSections.tsx b/src/renderer/src/components/github/PRFilterSections.tsx
index 6f65eee8e55..d704ea12754 100644
--- a/src/renderer/src/components/github/PRFilterSections.tsx
+++ b/src/renderer/src/components/github/PRFilterSections.tsx
@@ -208,7 +208,8 @@ export function SectionMenu({
   return (
     <div className="py-1 text-xs">
       <div className="px-3 py-1.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
-        {translate('auto.components.github.PRFilterSections.8177eda37e', 'Filter')} {subject}
+        {translate('auto.components.github.PRFilterSections.8177eda37e', 'Filter')}{' '}
+        <span>{subject}</span>
       </div>
       {rows.map((row) => (
         <button
diff --git a/src/renderer/src/components/sidebar/StatusIndicator.test.ts b/src/renderer/src/components/sidebar/StatusIndicator.test.ts
index 0179a0bac02..18ae2d1f154 100644
--- a/src/renderer/src/components/sidebar/StatusIndicator.test.ts
+++ b/src/renderer/src/components/sidebar/StatusIndicator.test.ts
@@ -17,17 +17,19 @@ function renderDotClassNames(status: Status): string[] {
 }
 
 describe('StatusIndicator', () => {
-  it('renders working as a stepped yellow spinner', () => {
-    const classNames = renderDotClassNames('working')
+  it('renders working as a clock-driven yellow spinner ring', () => {
+    const markup = renderMarkup('working')
 
-    expect(classNames).toContain('border-yellow-500')
-    expect(classNames).toContain('border-t-transparent')
-    expect(classNames).toContain('[animation:spin_1s_steps(12,end)_infinite]')
-    // Why: under reduced motion the spin is disabled and the top border filled,
-    // so the dot stays a complete static ring rather than freezing mid-rotation.
-    expect(classNames).toContain('motion-reduce:animate-none')
-    expect(classNames).toContain('motion-reduce:border-t-yellow-500')
-    expect(classNames).not.toContain('animate-spin')
+    expect(markup).toContain('border-yellow-500')
+    expect(markup).toContain('border-t-transparent')
+    // Why: rotation comes from the shared agent-spinner clock, not a
+    // per-element CSS animation that would keep the compositor awake.
+    expect(markup).toContain('data-agent-spinner')
+    // Why: under reduced motion the top border is filled so the static ring
+    // reads as a complete marker, not a broken partial spinner (#9515).
+    expect(markup).toContain('motion-reduce:border-t-yellow-500')
+    expect(markup).not.toContain('animate-spin')
+    expect(markup).not.toContain('animation:spin')
   })
 
   it('renders permission as an amber attention dot', () => {
diff --git a/src/renderer/src/components/sidebar/StatusIndicator.tsx b/src/renderer/src/components/sidebar/StatusIndicator.tsx
index c181e0c297d..ff4c4c25c89 100644
--- a/src/renderer/src/components/sidebar/StatusIndicator.tsx
+++ b/src/renderer/src/components/sidebar/StatusIndicator.tsx
@@ -1,5 +1,6 @@
 import React from 'react'
 import { cn } from '@/lib/utils'
+import { AgentWorkingSpinner } from '@/components/AgentWorkingSpinner'
 import { getWorktreeStatusLabel, type WorktreeStatus } from '@/lib/worktree-status'
 
 // Why: re-export WorktreeStatus under the existing `Status` alias so the
@@ -33,13 +34,7 @@ const StatusIndicator = React.memo(function StatusIndicator({
         title={resolvedTitle}
         {...rest}
       >
-        {/* Why: a stepped spin preserves the worker-is-running affordance while
-            avoiding a full-refresh-rate compositor loop for long agent runs.
-            Why: honor reduced motion (Windows "Animation effects" off →
-            prefers-reduced-motion) by stopping the spin and filling the top
-            border, so the dot stays a complete static ring instead of a
-            partial ring frozen mid-rotation that reads as a broken spinner. */}
-        <span className="block size-2 rounded-full border-2 border-yellow-500 border-t-transparent [animation:spin_1s_steps(12,end)_infinite] motion-reduce:animate-none motion-reduce:border-t-yellow-500" />
+        <AgentWorkingSpinner className="size-2" />
       </span>
     )
   }
diff --git a/src/renderer/src/components/tab-bar/TerminalTabLeadingIcon.test.tsx b/src/renderer/src/components/tab-bar/TerminalTabLeadingIcon.test.tsx
index 71508153243..58d57669fa1 100644
--- a/src/renderer/src/components/tab-bar/TerminalTabLeadingIcon.test.tsx
+++ b/src/renderer/src/components/tab-bar/TerminalTabLeadingIcon.test.tsx
@@ -23,7 +23,7 @@ describe('TerminalTabLeadingIcon', () => {
     expect(markup).toContain('data-testid="tab-agent-activity-indicator"')
     expect(markup).toContain('data-agent-activity-status="working"')
     expect(markup).toContain('aria-label="Working"')
-    expect(markup).toContain('[animation:spin_1s_steps(12,end)_infinite]')
+    expect(markup).toContain('data-agent-spinner')
     expect(markup).toContain('data-agent-icon="codex"')
   })
 
diff --git a/src/renderer/src/lib/agent-spinner-clock.test.ts b/src/renderer/src/lib/agent-spinner-clock.test.ts
new file mode 100644
index 00000000000..cdf496995e9
--- /dev/null
+++ b/src/renderer/src/lib/agent-spinner-clock.test.ts
@@ -0,0 +1,141 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  AGENT_SPINNER_TICK_MS,
+  registerAgentSpinnerElement,
+  resetAgentSpinnerClockForTesting
+} from './agent-spinner-clock'
+import { resetStaleDocumentVisibilityForTesting } from '@/components/terminal-pane/stale-document-visibility'
+
+type FakeElement = { style: { transform: string } }
+
+function makeElement(): HTMLElement {
+  return { style: { transform: '' } } as unknown as HTMLElement
+}
+
+function stubDom(visibilityState: () => DocumentVisibilityState): {
+  fireVisibilityChange: () => void
+} {
+  const documentListeners = new Map<string, Set<(event?: unknown) => void>>()
+  const addListener = (event: string, listener: (event?: unknown) => void): void => {
+    if (!documentListeners.has(event)) {
+      documentListeners.set(event, new Set())
+    }
+    documentListeners.get(event)!.add(listener)
+  }
+  vi.stubGlobal('document', {
+    get visibilityState() {
+      return visibilityState()
+    },
+    addEventListener: vi.fn(addListener),
+    removeEventListener: vi.fn((event: string, listener: (event?: unknown) => void) => {
+      documentListeners.get(event)?.delete(listener)
+    })
+  })
+  vi.stubGlobal('window', {
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    matchMedia: vi.fn(() => ({
+      matches: false,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn()
+    }))
+  })
+  return {
+    fireVisibilityChange: () => {
+      for (const listener of documentListeners.get('visibilitychange') ?? []) {
+        listener()
+      }
+    }
+  }
+}
+
+describe('agent-spinner-clock', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    resetAgentSpinnerClockForTesting()
+    resetStaleDocumentVisibilityForTesting()
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+  })
+
+  it('rotates every registered element in phase from one shared timer', () => {
+    stubDom(() => 'visible')
+    const a = makeElement()
+    const unregisterA = registerAgentSpinnerElement(a)
+
+    // Registration seeds the current dial position immediately.
+    expect((a as unknown as FakeElement).style.transform).toMatch(/^rotate\(\d+deg\)$/)
+
+    vi.advanceTimersByTime(AGENT_SPINNER_TICK_MS * 3)
+    const b = makeElement()
+    const unregisterB = registerAgentSpinnerElement(b)
+
+    // A late joiner starts at the shared dial position, not at zero.
+    expect((b as unknown as FakeElement).style.transform).toBe(
+      (a as unknown as FakeElement).style.transform
+    )
+
+    const before = (a as unknown as FakeElement).style.transform
+    vi.advanceTimersByTime(AGENT_SPINNER_TICK_MS)
+    expect((a as unknown as FakeElement).style.transform).not.toBe(before)
+    expect((b as unknown as FakeElement).style.transform).toBe(
+      (a as unknown as FakeElement).style.transform
+    )
+
+    unregisterA()
+    unregisterB()
+  })
+
+  it('stops ticking while the document is hidden and resumes on visibility', () => {
+    let visibility: DocumentVisibilityState = 'visible'
+    const { fireVisibilityChange } = stubDom(() => visibility)
+    const el = makeElement()
+    const unregister = registerAgentSpinnerElement(el)
+
+    visibility = 'hidden'
+    fireVisibilityChange()
+    const frozen = (el as unknown as FakeElement).style.transform
+    vi.advanceTimersByTime(AGENT_SPINNER_TICK_MS * 10)
+    expect((el as unknown as FakeElement).style.transform).toBe(frozen)
+
+    visibility = 'visible'
+    fireVisibilityChange()
+    // Resume advances immediately so the restored window visibly spins again.
+    expect((el as unknown as FakeElement).style.transform).not.toBe(frozen)
+
+    unregister()
+  })
+
+  it('clears its timer when the last element unregisters', () => {
+    stubDom(() => 'visible')
+    const el = makeElement()
+    const unregister = registerAgentSpinnerElement(el)
+    unregister()
+
+    const parked = (el as unknown as FakeElement).style.transform
+    vi.advanceTimersByTime(AGENT_SPINNER_TICK_MS * 5)
+    expect((el as unknown as FakeElement).style.transform).toBe(parked)
+    expect(vi.getTimerCount()).toBe(0)
+  })
+
+  it('does not tick when prefers-reduced-motion is set', () => {
+    stubDom(() => 'visible')
+    const windowStub = globalThis.window as unknown as { matchMedia: ReturnType<typeof vi.fn> }
+    windowStub.matchMedia = vi.fn(() => ({
+      matches: true,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn()
+    }))
+
+    const el = makeElement()
+    const unregister = registerAgentSpinnerElement(el)
+    const initial = (el as unknown as FakeElement).style.transform
+    vi.advanceTimersByTime(AGENT_SPINNER_TICK_MS * 5)
+    expect((el as unknown as FakeElement).style.transform).toBe(initial)
+
+    unregister()
+  })
+})
diff --git a/src/renderer/src/lib/agent-spinner-clock.ts b/src/renderer/src/lib/agent-spinner-clock.ts
new file mode 100644
index 00000000000..895d6a4f8c8
--- /dev/null
+++ b/src/renderer/src/lib/agent-spinner-clock.ts
@@ -0,0 +1,128 @@
+// Why: a per-element infinite CSS animation keeps Chromium's frame pipeline
+// awake the whole time any agent spinner is visible (~23.5ms CPU/s measured
+// live, nearly independent of cadence, scaling per element). Background
+// throttling only helps hidden windows — a visible sidebar full of working
+// agents pays continuously. One shared low-rate clock steps every registered
+// spinner element's transform directly, so the renderer idles between ticks
+// and costs the same whether one agent or fifty are working.
+import { isWindowVisible } from './window-visibility-interval'
+import {
+  isDocumentVisibilityProvenStale,
+  registerStaleDocumentVisibilityRecovery
+} from '@/components/terminal-pane/stale-document-visibility'
+
+const SPIN_STEP_DEGREES = 30
+const SPIN_STEPS = 360 / SPIN_STEP_DEGREES
+// Why: 12 steps/s at 30° matches the retired CSS animation exactly — slower
+// cadences read as sluggish next to it. The win over CSS is structural (idle
+// between ticks, one timer for N spinners), not the tick rate.
+export const AGENT_SPINNER_TICK_MS = 1000 / 12
+
+const elements = new Set<HTMLElement>()
+let timer: ReturnType<typeof setInterval> | null = null
+let step = 0
+let teardownGlobalListeners: (() => void) | null = null
+
+function currentTransform(): string {
+  return `rotate(${step * SPIN_STEP_DEGREES}deg)`
+}
+
+function tick(): void {
+  step = (step + 1) % SPIN_STEPS
+  const transform = currentTransform()
+  for (const el of elements) {
+    el.style.transform = transform
+  }
+}
+
+function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+    return false
+  }
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches
+}
+
+function shouldRun(): boolean {
+  // Why: the stale-visibility latch proves user input arrived while the macOS
+  // occlusion tracker still claims hidden — keep spinning for the user we know
+  // is watching instead of freezing until the tracker recovers.
+  const visible = isWindowVisible() || isDocumentVisibilityProvenStale()
+  return elements.size > 0 && visible && !prefersReducedMotion()
+}
+
+function reconcile(): void {
+  if (shouldRun()) {
+    if (timer === null) {
+      // Advance immediately so a just-restored window visibly resumes.
+      tick()
+      timer = setInterval(tick, AGENT_SPINNER_TICK_MS)
+    }
+    return
+  }
+  if (timer !== null) {
+    clearInterval(timer)
+    timer = null
+  }
+}
+
+function installGlobalListeners(): void {
+  if (
+    teardownGlobalListeners !== null ||
+    typeof document === 'undefined' ||
+    typeof document.addEventListener !== 'function'
+  ) {
+    return
+  }
+  const onSignal = (): void => {
+    reconcile()
+  }
+  document.addEventListener('visibilitychange', onSignal)
+  const reducedMotionQuery =
+    typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+      ? window.matchMedia('(prefers-reduced-motion: reduce)')
+      : null
+  reducedMotionQuery?.addEventListener?.('change', onSignal)
+  const unregisterStaleRecovery = registerStaleDocumentVisibilityRecovery(onSignal)
+  teardownGlobalListeners = () => {
+    document.removeEventListener('visibilitychange', onSignal)
+    reducedMotionQuery?.removeEventListener?.('change', onSignal)
+    unregisterStaleRecovery()
+  }
+}
+
+export function registerAgentSpinnerElement(el: HTMLElement): () => void {
+  elements.add(el)
+  // Join in phase with the shared dial so late-mounting spinners stay in sync.
+  el.style.transform = currentTransform()
+  installGlobalListeners()
+  reconcile()
+  return () => {
+    elements.delete(el)
+    reconcile()
+    if (elements.size === 0 && teardownGlobalListeners !== null) {
+      teardownGlobalListeners()
+      teardownGlobalListeners = null
+    }
+  }
+}
+
+/** Stable React ref callback: attach to a spinner element to spin it. */
+export function agentSpinnerRef(el: HTMLElement | null): (() => void) | undefined {
+  if (el === null) {
+    return undefined
+  }
+  return registerAgentSpinnerElement(el)
+}
+
+export function resetAgentSpinnerClockForTesting(): void {
+  if (timer !== null) {
+    clearInterval(timer)
+    timer = null
+  }
+  elements.clear()
+  if (teardownGlobalListeners !== null) {
+    teardownGlobalListeners()
+    teardownGlobalListeners = null
+  }
+  step = 0
+}

From 49149a05d45b963d730ba1f76a1832a7fd5b1f4c Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Mon, 20 Jul 2026 02:11:05 -0400
Subject: [PATCH 31/54] fix(agent-status): stamp renderer SSH ownership (#9505)

* fix(agent-status): stamp renderer SSH ownership

* fix(agent-status): block stale renderer reconnect writes

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
---
 .../terminal-pane/pty-connection.test.ts      | 121 +++++++++++++++---
 .../terminal-pane/pty-connection.ts           |  52 ++++++--
 .../agent-status-connection-ownership.test.ts |  94 ++++++++++++++
 .../lib/agent-status-connection-ownership.ts  |  95 ++++++++++++++
 .../lib/automation-session-observer.test.ts   | 119 ++++++++++++++++-
 .../src/lib/automation-session-observer.ts    |   9 +-
 .../lib/background-agent-status-consumer.ts   |  52 ++++++++
 .../lib/command-code-prompt-status-seed.ts    |  36 +++++-
 .../launch-agent-background-session.test.ts   |  79 ++++++------
 .../lib/launch-agent-background-session.ts    |  45 ++++---
 .../src/lib/launch-agent-in-new-tab.test.ts   |  71 +++++++++-
 .../src/lib/launch-agent-in-new-tab.ts        |   2 +-
 .../agent-status-ssh-connection-clear.test.ts |  64 +++++++++
 src/renderer/src/store/slices/agent-status.ts |  22 +++-
 .../src/store/slices/ssh-target-cleanup.ts    |  12 ++
 src/renderer/src/store/slices/ssh.test.ts     |  16 +++
 src/renderer/src/store/slices/ssh.ts          |  14 +-
 17 files changed, 783 insertions(+), 120 deletions(-)
 create mode 100644 src/renderer/src/lib/agent-status-connection-ownership.test.ts
 create mode 100644 src/renderer/src/lib/agent-status-connection-ownership.ts
 create mode 100644 src/renderer/src/lib/background-agent-status-consumer.ts

diff --git a/src/renderer/src/components/terminal-pane/pty-connection.test.ts b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
index 3f05c9a5371..1da9467b225 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
@@ -18,6 +18,7 @@ import { resolveWindowsShiftEnterEncodingForPane } from './terminal-windows-shif
 import type * as UseNotificationDispatchModule from './use-notification-dispatch'
 import { getEagerPtyBufferHandle } from './pty-dispatcher'
 import { makePaneKey } from '../../../../shared/stable-pane-id'
+import { toAppSshPtyId } from '../../../../shared/ssh-pty-id'
 import type { TerminalLayoutSnapshot, TuiAgent } from '../../../../shared/types'
 import { YOLO_TUI_AGENT_ARGS } from '../../../../shared/tui-agent-permissions'
 import { SETUP_AGENT_SEQUENCE_STARTUP_COMMAND_ENV } from '../../../../shared/setup-agent-sequencing'
@@ -148,6 +149,7 @@ type StoreState = {
       | { kind: 'wsl'; distro: string }
   }[]
   sshConnectionStates: Map<string, { status: string }>
+  transientClearedAgentStatusConnectionIds: Record<string, true>
   cacheTimerByKey: Record<string, number | null>
   settings: {
     theme?: 'system' | 'dark' | 'light'
@@ -546,7 +548,16 @@ function createDeps(overrides: Record<string, unknown> = {}) {
     updateTabTitle: vi.fn(),
     setRuntimePaneTitle: vi.fn(),
     clearRuntimePaneTitle: vi.fn(),
-    updateTabPtyId: vi.fn(),
+    updateTabPtyId: vi.fn((tabId: string, ptyId: string, replacedPtyId?: string) => {
+      const current = mockStoreState.ptyIdsByTabId?.[tabId] ?? []
+      const next =
+        replacedPtyId && current.includes(replacedPtyId)
+          ? current.map((candidate) => (candidate === replacedPtyId ? ptyId : candidate))
+          : current.includes(ptyId)
+            ? current
+            : [...current, ptyId]
+      mockStoreState.ptyIdsByTabId = { ...mockStoreState.ptyIdsByTabId, [tabId]: next }
+    }),
     markWorktreeUnread: vi.fn(),
     markTerminalTabUnread: vi.fn(),
     markTerminalPaneUnread: vi.fn(),
@@ -556,7 +567,12 @@ function createDeps(overrides: Record<string, unknown> = {}) {
     dispatchNotification: vi.fn(),
     onShowSessionRestoredBanner: vi.fn(),
     setCacheTimerStartedAt: vi.fn(),
-    syncPanePtyLayoutBinding: vi.fn(),
+    syncPanePtyLayoutBinding: vi.fn((paneId: number, ptyId: string) => {
+      const layout = mockStoreState.terminalLayoutsByTabId?.['tab-1']
+      if (layout) {
+        layout.ptyIdsByLeafId = { ...layout.ptyIdsByLeafId, [leafIdForPane(paneId)]: ptyId }
+      }
+    }),
     clearExitedPanePtyLayoutBinding: vi.fn(),
     ...overrides
   }
@@ -785,6 +801,7 @@ describe('connectPanePty', () => {
       repos: [{ id: 'repo1', connectionId: null, displayName: 'orca' }],
       projects: [],
       sshConnectionStates: new Map(),
+      transientClearedAgentStatusConnectionIds: {},
       cacheTimerByKey: {},
       // Why: terminalMainSideEffectAuthority false pins the legacy renderer
       // byte-parser wiring this suite asserts on (onTitleChange/onBell on the
@@ -826,11 +843,18 @@ describe('connectPanePty', () => {
       observeTerminalGitHubPullRequestLink: vi.fn(),
       recordTerminalInput: vi.fn(),
       setAgentStatus: vi.fn(
-        (paneKey: string, payload: Record<string, unknown>, terminalTitle?: string | null) => {
+        (
+          paneKey: string,
+          payload: Record<string, unknown>,
+          terminalTitle?: string | null,
+          _timing?: unknown,
+          routing?: { connectionId?: string | null }
+        ) => {
           mockStoreState.agentStatusByPaneKey[paneKey] = {
             ...payload,
             paneKey,
             ...(terminalTitle ? { terminalTitle } : {}),
+            ...(routing?.connectionId !== undefined ? { connectionId: routing.connectionId } : {}),
             updatedAt: Date.now(),
             stateStartedAt: Date.now(),
             stateHistory: []
@@ -1725,11 +1749,11 @@ describe('connectPanePty', () => {
     const paneKey = makePaneKey('tab-1', LEAF_1)
     const dataCallbackRef: { current: ((data: string) => void) | null } = { current: null }
     const pane = createPane(1)
-    const transport = createMockTransport('remote:web-env-1@@pty-command-finished')
+    const transport = createMockTransport('remote:env-1@@pty-command-finished')
     transport.connect.mockImplementation(
       async ({ callbacks }: { callbacks?: ConnectCallbacks }) => {
         dataCallbackRef.current = callbacks?.onData ?? null
-        return 'remote:web-env-1@@pty-command-finished'
+        return 'remote:env-1@@pty-command-finished'
       }
     )
     transportFactoryQueue.push(transport)
@@ -2662,12 +2686,15 @@ describe('connectPanePty', () => {
 
   it('seeds a working status for Command Code startup prompts after spawn', async () => {
     const { connectPanePty } = await import('./pty-connection')
-    const transport = createMockTransport('pty-command-code')
+    const sshPtyId = toAppSshPtyId('ssh-a', 'pty-command-code')
+    const transport = createMockTransport(sshPtyId)
+    transport.getConnectionId.mockReturnValue('ssh-a')
     transportFactoryQueue.push(transport)
     mockStoreState = {
       ...mockStoreState,
       tabsByWorktree: { 'wt-1': [{ id: 'tab-1', ptyId: null }] },
-      repos: [{ id: 'repo1', connectionId: null }]
+      repos: [{ id: 'repo1', connectionId: 'ssh-a' }],
+      sshConnectionStates: new Map([['ssh-a', { status: 'connected' }]])
     }
 
     const pane = createPane(1)
@@ -2685,7 +2712,7 @@ describe('connectPanePty', () => {
       | ((ptyId: string) => void)
       | undefined
     expect(onPtySpawn).toBeTypeOf('function')
-    onPtySpawn?.('pty-command-code')
+    onPtySpawn?.(sshPtyId)
 
     expect(mockStoreState.setAgentStatus).toHaveBeenCalledWith(
       makePaneKey('tab-1', LEAF_1),
@@ -2694,19 +2721,25 @@ describe('connectPanePty', () => {
         prompt: 'Fix the status',
         agentType: 'command-code'
       },
-      undefined
+      undefined,
+      undefined,
+      { connectionId: 'ssh-a' }
     )
   })
 
   it('seeds a working status from Command Code thinking output without a startup prompt', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const capturedDataCallback: { current: ((data: string) => void) | null } = { current: null }
-    const transport = createMockTransport()
+    const sshPtyId = toAppSshPtyId('ssh-a', 'pty-command-code')
+    const transport = createMockTransport(sshPtyId)
+    transport.getConnectionId.mockReturnValue('ssh-a')
     transport.connect.mockImplementation(async ({ callbacks }: { callbacks: ConnectCallbacks }) => {
       capturedDataCallback.current = callbacks.onData ?? null
-      return 'pty-command-code'
+      return sshPtyId
     })
     transportFactoryQueue.push(transport)
+    mockStoreState.repos = [{ id: 'repo1', connectionId: 'ssh-a' }]
+    mockStoreState.sshConnectionStates = new Map([['ssh-a', { status: 'connected' }]])
 
     const pane = createPane(1)
     const manager = createManager(1)
@@ -2730,15 +2763,47 @@ describe('connectPanePty', () => {
         prompt: 'Fix the spinner',
         agentType: 'command-code'
       },
-      undefined
+      undefined,
+      undefined,
+      { connectionId: 'ssh-a' }
     )
   })
 
+  it('ignores delayed Command Code output after the leaf rebinds to another SSH host', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+    const capturedDataCallback: { current: ((data: string) => void) | null } = { current: null }
+    const oldPtyId = toAppSshPtyId('ssh-a', 'pty-command-code')
+    const newPtyId = toAppSshPtyId('ssh-b', 'pty-command-code')
+    const transport = createMockTransport(oldPtyId)
+    transport.getConnectionId.mockReturnValue('ssh-a')
+    transport.connect.mockImplementation(async ({ callbacks }: { callbacks: ConnectCallbacks }) => {
+      capturedDataCallback.current = callbacks.onData ?? null
+      return oldPtyId
+    })
+    transportFactoryQueue.push(transport)
+    mockStoreState.repos = [{ id: 'repo1', connectionId: 'ssh-a' }]
+    mockStoreState.sshConnectionStates = new Map([['ssh-a', { status: 'connected' }]])
+
+    connectPanePty(
+      createPane(1) as never,
+      createManager(1) as never,
+      createDeps({ startup: { command: 'command-code --trust' } }) as never
+    )
+    await flushAsyncTicks()
+    mockStoreState.setAgentStatus.mockClear()
+    mockStoreState.ptyIdsByTabId = { 'tab-1': [oldPtyId, newPtyId] }
+    mockStoreState.terminalLayoutsByTabId!['tab-1'].ptyIdsByLeafId = { [LEAF_1]: newPtyId }
+
+    capturedDataCallback.current?.('❯ stale prompt\r\n\x1b[35m✻ Thinking...\x1b[0m')
+
+    expect(mockStoreState.setAgentStatus).not.toHaveBeenCalled()
+  })
+
   it('marks a Command Code no-tool turn done after the idle prompt settles', async () => {
     vi.useFakeTimers()
     const { connectPanePty } = await import('./pty-connection')
     const capturedDataCallback: { current: ((data: string) => void) | null } = { current: null }
-    const transport = createMockTransport()
+    const transport = createMockTransport('pty-command-code')
     transport.connect.mockImplementation(async ({ callbacks }: { callbacks: ConnectCallbacks }) => {
       capturedDataCallback.current = callbacks.onData ?? null
       return 'pty-command-code'
@@ -2788,7 +2853,7 @@ describe('connectPanePty', () => {
     vi.useFakeTimers()
     const { connectPanePty } = await import('./pty-connection')
     const capturedDataCallback: { current: ((data: string) => void) | null } = { current: null }
-    const transport = createMockTransport()
+    const transport = createMockTransport('pty-command-code')
     transport.connect.mockImplementation(async ({ callbacks }: { callbacks: ConnectCallbacks }) => {
       capturedDataCallback.current = callbacks.onData ?? null
       return 'pty-command-code'
@@ -2825,7 +2890,7 @@ describe('connectPanePty', () => {
   it('does not downgrade a completed Command Code turn back to working from stale TUI output', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const capturedDataCallback: { current: ((data: string) => void) | null } = { current: null }
-    const transport = createMockTransport()
+    const transport = createMockTransport('pty-command-code')
     transport.connect.mockImplementation(async ({ callbacks }: { callbacks: ConnectCallbacks }) => {
       capturedDataCallback.current = callbacks.onData ?? null
       return 'pty-command-code'
@@ -2866,7 +2931,7 @@ describe('connectPanePty', () => {
   it('starts a new Command Code turn after done when TUI output carries a different prompt', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const capturedDataCallback: { current: ((data: string) => void) | null } = { current: null }
-    const transport = createMockTransport()
+    const transport = createMockTransport('pty-command-code')
     transport.connect.mockImplementation(async ({ callbacks }: { callbacks: ConnectCallbacks }) => {
       capturedDataCallback.current = callbacks.onData ?? null
       return 'pty-command-code'
@@ -2905,7 +2970,9 @@ describe('connectPanePty', () => {
         prompt: 'Fix the green done state',
         agentType: 'command-code'
       },
-      undefined
+      undefined,
+      undefined,
+      { connectionId: null }
     )
   })
 
@@ -16377,6 +16444,8 @@ describe('connectPanePty', () => {
     const transport = createMockTransport('pty-hook')
     transportFactoryQueue.push(transport)
     enableActiveRuntimeEnvironment()
+    mockStoreState.ptyIdsByTabId = { 'tab-1': ['pty-hook'] }
+    mockStoreState.terminalLayoutsByTabId!['tab-1'].ptyIdsByLeafId = { [LEAF_1]: 'pty-hook' }
 
     vi.useFakeTimers()
     const pane = createPane(1)
@@ -16635,7 +16704,9 @@ describe('connectPanePty', () => {
         prompt: 'fix the remote title',
         agentType: 'omp'
       },
-      '\u280b OMP'
+      '\u280b OMP',
+      undefined,
+      { connectionId: null }
     )
 
     mockStoreState.tabsByWorktree = {
@@ -16654,7 +16725,9 @@ describe('connectPanePty', () => {
         prompt: 'keep the remote title',
         agentType: 'omp'
       },
-      '\u280b OMP'
+      '\u280b OMP',
+      undefined,
+      { connectionId: null }
     )
   })
 
@@ -16729,6 +16802,8 @@ describe('connectPanePty', () => {
     const transport = createMockTransport('pty-hook')
     transportFactoryQueue.push(transport)
     enableActiveRuntimeEnvironment()
+    mockStoreState.ptyIdsByTabId = { 'tab-1': ['pty-hook'] }
+    mockStoreState.terminalLayoutsByTabId!['tab-1'].ptyIdsByLeafId = { [LEAF_1]: 'pty-hook' }
 
     vi.useFakeTimers()
     const pane = createPane(1)
@@ -16795,9 +16870,11 @@ describe('connectPanePty', () => {
 
   it('restores a suppressed terminal bell when a delayed hook completion resumes work', async () => {
     const { connectPanePty } = await import('./pty-connection')
-    const transport = createMockTransport('pty-hook')
+    const transport = createMockTransport('tab-pty')
     transportFactoryQueue.push(transport)
     enableActiveRuntimeEnvironment()
+    mockStoreState.ptyIdsByTabId = { 'tab-1': ['tab-pty'] }
+    mockStoreState.terminalLayoutsByTabId!['tab-1'].ptyIdsByLeafId = { [LEAF_1]: 'tab-pty' }
 
     vi.useFakeTimers()
     const pane = createPane(1)
@@ -16856,6 +16933,8 @@ describe('connectPanePty', () => {
     const transport = createMockTransport('pty-hook')
     transportFactoryQueue.push(transport)
     enableActiveRuntimeEnvironment()
+    mockStoreState.ptyIdsByTabId = { 'tab-1': ['pty-hook'] }
+    mockStoreState.terminalLayoutsByTabId!['tab-1'].ptyIdsByLeafId = { [LEAF_1]: 'pty-hook' }
 
     vi.useFakeTimers()
     const pane = createPane(1)
@@ -17742,6 +17821,8 @@ describe('connectPanePty', () => {
     const transport = createMockTransport('pty-hook')
     transportFactoryQueue.push(transport)
     enableActiveRuntimeEnvironment()
+    mockStoreState.ptyIdsByTabId = { 'tab-1': ['pty-hook'] }
+    mockStoreState.terminalLayoutsByTabId!['tab-1'].ptyIdsByLeafId = { [LEAF_1]: 'pty-hook' }
     vi.useFakeTimers()
     mockStoreState.settings = {
       ...mockStoreState.settings,
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.ts b/src/renderer/src/components/terminal-pane/pty-connection.ts
index 0c1259d665e..8e4ce78c00c 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.ts
@@ -5,6 +5,7 @@ import type { IBuffer, IDisposable } from '@xterm/xterm'
 import { resolveCursorAgentImeAnchor } from '@/lib/pane-manager/terminal-ime-anchor'
 import { detectAgentStatusFromTitle, agentTypeToIconAgent, isClaudeAgent } from '@/lib/agent-status'
 import { resolvePaneTitleDecision } from './terminal-title-evidence'
+import { resolveLiveAgentStatusConnectionRouting } from '@/lib/agent-status-connection-ownership'
 import { scheduleRuntimeGraphSync } from '@/runtime/sync-runtime-graph'
 import { useAppStore } from '@/store'
 import { getWorktreeMapFromState } from '@/store/selectors'
@@ -2566,6 +2567,21 @@ export function connectPanePty(
   let hasConsideredInitialCacheTimerSeed = false
   let allowInitialIdleCacheSeed = false
 
+  const resolveCurrentAgentStatusRouting = () => {
+    const ptyId = activePanePtyBinding ?? transport.getPtyId()
+    const state = useAppStore.getState()
+    if (disposed || !ptyId) {
+      return undefined
+    }
+    return resolveLiveAgentStatusConnectionRouting({
+      state,
+      paneKey: cacheKey,
+      ptyId,
+      expectedConnectionId: worktreeConnectionId,
+      runtimeEnvironmentId: transport.getRuntimeEnvironmentId?.() ?? runtimeEnvironmentId
+    })
+  }
+
   const onTitleChange = (
     title: string,
     rawTitle: string,
@@ -2632,7 +2648,8 @@ export function connectPanePty(
 
   const applyInitialAgentStatus = (terminalTitle?: string): void => {
     const initialStatus = paneStartup?.initialAgentStatus
-    if (!initialStatus) {
+    const routing = resolveCurrentAgentStatusRouting()
+    if (!initialStatus || !routing) {
       return
     }
     const statusPayload = {
@@ -2646,17 +2663,23 @@ export function connectPanePty(
     if (paneStartup.launchConfig) {
       useAppStore
         .getState()
-        .setAgentStatus(cacheKey, statusPayload, terminalTitle, undefined, undefined, {
+        .setAgentStatus(cacheKey, statusPayload, terminalTitle, undefined, routing, {
           launchConfig: paneStartup.launchConfig,
           ...(launchToken ? { launchToken } : {})
         })
       return
     }
-    useAppStore.getState().setAgentStatus(cacheKey, statusPayload, terminalTitle)
+    useAppStore
+      .getState()
+      .setAgentStatus(cacheKey, statusPayload, terminalTitle, undefined, routing)
   }
 
   const seedCommandCodeOutputWorkingStatus = (prompt: string): void => {
     clearCommandCodeOutputDoneTimer()
+    const routing = resolveCurrentAgentStatusRouting()
+    if (!routing) {
+      return
+    }
     const currentState = useAppStore.getState()
     const currentEntry = currentState.agentStatusByPaneKey[cacheKey]
     const currentTitle = currentState.runtimePaneTitlesByTabId?.[deps.tabId]?.[pane.id]
@@ -2675,7 +2698,9 @@ export function connectPanePty(
         prompt: normalizedPrompt || (currentEntry?.state === 'working' ? currentEntry.prompt : ''),
         agentType: 'command-code'
       },
-      currentTitle
+      currentTitle,
+      undefined,
+      routing
     )
   }
 
@@ -2700,6 +2725,10 @@ export function connectPanePty(
         return
       }
       const currentState = useAppStore.getState()
+      const routing = resolveCurrentAgentStatusRouting()
+      if (!routing) {
+        return
+      }
       const currentEntry = currentState.agentStatusByPaneKey[cacheKey]
       if (currentEntry?.agentType !== 'command-code' || currentEntry.state !== 'working') {
         return
@@ -2716,7 +2745,9 @@ export function connectPanePty(
           prompt: currentPrompt || normalizedPrompt,
           agentType: 'command-code'
         },
-        currentTitle
+        currentTitle,
+        undefined,
+        routing
       )
     }, COMMAND_CODE_OUTPUT_DONE_SETTLE_MS)
   }
@@ -3137,7 +3168,8 @@ export function connectPanePty(
   // Why: folder workspaces can inherit their SSH target from child repos, so
   // use the shared resolver instead of only looking up repo-backed worktrees.
   const worktree = getWorktreeMapFromState(state).get(deps.worktreeId)
-  const connectionId = getConnectionId(deps.worktreeId) ?? null
+  const worktreeConnectionId = getConnectionId(deps.worktreeId)
+  const connectionId = worktreeConnectionId ?? null
   const tab = (state.tabsByWorktree[deps.worktreeId] ?? []).find((t) => t.id === deps.tabId)
   const shellOverride = tab?.shellOverride
   // Why: a serve/remote-runtime pane has no SSH connectionId and a Linux cwd, so
@@ -3351,6 +3383,10 @@ export function connectPanePty(
             // shift (OSC title update landing in between) and the status would
             // be stored against a title that was never paired with it.
             const currentState = useAppStore.getState()
+            const routing = resolveCurrentAgentStatusRouting()
+            if (!routing) {
+              return
+            }
             const title = currentState.runtimePaneTitlesByTabId?.[deps.tabId]?.[pane.id]
             const authoritativePaneAgent = getAuthoritativePaneAgent()
             const agentType = resolveCompatibleAgentTypeForOwner(
@@ -3372,13 +3408,13 @@ export function connectPanePty(
                 statusPayload,
                 statusTitle,
                 undefined,
-                undefined,
+                routing,
                 {
                   launchToken
                 }
               )
             } else {
-              currentState.setAgentStatus(cacheKey, statusPayload, statusTitle)
+              currentState.setAgentStatus(cacheKey, statusPayload, statusTitle, undefined, routing)
             }
             const trackingEnabled = syncAgentTaskCompleteTrackingEnabled()
             if (payload.state === 'working' && trackingEnabled) {
diff --git a/src/renderer/src/lib/agent-status-connection-ownership.test.ts b/src/renderer/src/lib/agent-status-connection-ownership.test.ts
new file mode 100644
index 00000000000..c3d6128195a
--- /dev/null
+++ b/src/renderer/src/lib/agent-status-connection-ownership.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest'
+
+import { toAppSshPtyId } from '../../../shared/ssh-pty-id'
+import { makePaneKey } from '../../../shared/stable-pane-id'
+import {
+  resolveAgentStatusConnectionRouting,
+  resolveLiveAgentStatusConnectionRouting
+} from './agent-status-connection-ownership'
+
+const LEAF = '11111111-1111-4111-8111-111111111111'
+const PANE = makePaneKey('tab-1', LEAF)
+
+describe('agent status connection ownership', () => {
+  it('uses exact SSH PTY ownership and rejects contradictory routing', () => {
+    const ptyId = toAppSshPtyId('ssh-a', 'pty-1')
+
+    expect(resolveAgentStatusConnectionRouting({ ptyId, expectedConnectionId: 'ssh-a' })).toEqual({
+      connectionId: 'ssh-a'
+    })
+    expect(
+      resolveAgentStatusConnectionRouting({ ptyId, expectedConnectionId: 'ssh-b' })
+    ).toBeUndefined()
+    expect(
+      resolveAgentStatusConnectionRouting({ ptyId, expectedConnectionId: null })
+    ).toBeUndefined()
+    expect(resolveAgentStatusConnectionRouting({ ptyId: 'ssh:ssh-a@broken' })).toBeUndefined()
+  })
+
+  it('marks known local, WSL, and remote-runtime PTYs as non-SSH', () => {
+    expect(
+      resolveAgentStatusConnectionRouting({ ptyId: 'pty-local-1', expectedConnectionId: null })
+    ).toEqual({ connectionId: null })
+    expect(
+      resolveAgentStatusConnectionRouting({ ptyId: 'pty-wsl-1', expectedConnectionId: null })
+    ).toEqual({ connectionId: null })
+    expect(
+      resolveAgentStatusConnectionRouting({
+        ptyId: 'remote:env-a@@terminal-1',
+        expectedConnectionId: null,
+        runtimeEnvironmentId: 'env-a'
+      })
+    ).toEqual({ connectionId: null })
+  })
+
+  it('fails closed for missing, malformed, and cross-runtime ownership', () => {
+    expect(resolveAgentStatusConnectionRouting({ ptyId: null })).toBeUndefined()
+    expect(resolveAgentStatusConnectionRouting({ ptyId: 'remote:' })).toBeUndefined()
+    expect(
+      resolveAgentStatusConnectionRouting({
+        ptyId: 'remote:env-a@@terminal-1',
+        expectedConnectionId: 'ssh-a',
+        runtimeEnvironmentId: 'env-a'
+      })
+    ).toBeUndefined()
+    expect(
+      resolveAgentStatusConnectionRouting({
+        ptyId: 'remote:env-a@@terminal-1',
+        expectedConnectionId: null,
+        runtimeEnvironmentId: 'env-b'
+      })
+    ).toBeUndefined()
+  })
+
+  it('requires one exact live pane binding', () => {
+    const ptyId = toAppSshPtyId('ssh-a', 'pty-1')
+    const state = {
+      terminalLayoutsByTabId: { 'tab-1': { ptyIdsByLeafId: { [LEAF]: ptyId } } },
+      ptyIdsByTabId: { 'tab-1': [ptyId] },
+      sshConnectionStates: new Map([['ssh-a', { status: 'connected' }]]),
+      transientClearedAgentStatusConnectionIds: {}
+    }
+
+    expect(resolveLiveAgentStatusConnectionRouting({ state, paneKey: PANE, ptyId })).toEqual({
+      connectionId: 'ssh-a'
+    })
+    state.terminalLayoutsByTabId['tab-1'].ptyIdsByLeafId[LEAF] = toAppSshPtyId('ssh-b', 'pty-1')
+    expect(resolveLiveAgentStatusConnectionRouting({ state, paneKey: PANE, ptyId })).toBeUndefined()
+  })
+
+  it('rejects stale SSH routing after clear and throughout transient reconnect', () => {
+    const ptyId = toAppSshPtyId('ssh-a', 'pty-1')
+    const state = {
+      terminalLayoutsByTabId: { 'tab-1': { ptyIdsByLeafId: { [LEAF]: ptyId } } },
+      ptyIdsByTabId: { 'tab-1': [ptyId] },
+      sshConnectionStates: new Map([['ssh-a', { status: 'connected' }]]),
+      transientClearedAgentStatusConnectionIds: { 'ssh-a': true } as Record<string, true>
+    }
+
+    expect(resolveLiveAgentStatusConnectionRouting({ state, paneKey: PANE, ptyId })).toBeUndefined()
+    state.transientClearedAgentStatusConnectionIds = {}
+    state.sshConnectionStates = new Map([['ssh-a', { status: 'reconnecting' }]])
+    expect(resolveLiveAgentStatusConnectionRouting({ state, paneKey: PANE, ptyId })).toBeUndefined()
+  })
+})
diff --git a/src/renderer/src/lib/agent-status-connection-ownership.ts b/src/renderer/src/lib/agent-status-connection-ownership.ts
new file mode 100644
index 00000000000..4caa0d36422
--- /dev/null
+++ b/src/renderer/src/lib/agent-status-connection-ownership.ts
@@ -0,0 +1,95 @@
+import { parseAppSshPtyId } from '../../../shared/ssh-pty-id'
+import { parsePaneKey } from '../../../shared/stable-pane-id'
+import { parseRemoteRuntimePtyId } from '@/runtime/runtime-terminal-stream'
+
+export type AgentStatusConnectionRouting = { connectionId: string | null }
+
+type AgentStatusRoutingState = {
+  terminalLayoutsByTabId:
+    | Record<string, { ptyIdsByLeafId?: Record<string, string | undefined> } | undefined>
+    | undefined
+  ptyIdsByTabId: Record<string, string[] | undefined> | undefined
+  sshConnectionStates: ReadonlyMap<string, { status: string }>
+  transientClearedAgentStatusConnectionIds: Record<string, true>
+}
+
+export function resolveAgentStatusConnectionRouting(args: {
+  ptyId: string | null | undefined
+  expectedConnectionId?: string | null
+  runtimeEnvironmentId?: string | null
+}): AgentStatusConnectionRouting | undefined {
+  const ptyId = args.ptyId?.trim()
+  if (!ptyId) {
+    return undefined
+  }
+  const expectedConnectionId = args.expectedConnectionId?.trim() || args.expectedConnectionId
+  const sshPty = parseAppSshPtyId(ptyId)
+  if (sshPty) {
+    if (
+      typeof args.runtimeEnvironmentId === 'string' ||
+      expectedConnectionId === null ||
+      (typeof expectedConnectionId === 'string' && expectedConnectionId !== sshPty.connectionId)
+    ) {
+      return undefined
+    }
+    return { connectionId: sshPty.connectionId }
+  }
+  if (ptyId.startsWith('ssh:')) {
+    return undefined
+  }
+
+  const runtimePty = parseRemoteRuntimePtyId(ptyId)
+  if (runtimePty?.handle) {
+    if (
+      typeof expectedConnectionId === 'string' ||
+      args.runtimeEnvironmentId === null ||
+      (typeof args.runtimeEnvironmentId === 'string' &&
+        runtimePty.environmentId !== null &&
+        runtimePty.environmentId !== args.runtimeEnvironmentId)
+    ) {
+      return undefined
+    }
+    return { connectionId: null }
+  }
+  if (ptyId.startsWith('remote:')) {
+    return undefined
+  }
+
+  // Why: app-wide SSH and remote-runtime PTY IDs are namespaced; a remaining
+  // concrete PTY is authoritative local/WSL ownership, never an SSH guess.
+  if (typeof expectedConnectionId === 'string') {
+    return undefined
+  }
+  return { connectionId: null }
+}
+
+export function resolveLiveAgentStatusConnectionRouting(args: {
+  state: AgentStatusRoutingState
+  paneKey: string
+  ptyId: string
+  expectedConnectionId?: string | null
+  runtimeEnvironmentId?: string | null
+}): AgentStatusConnectionRouting | undefined {
+  const pane = parsePaneKey(args.paneKey)
+  if (
+    !pane ||
+    !args.state.ptyIdsByTabId?.[pane.tabId]?.includes(args.ptyId) ||
+    args.state.terminalLayoutsByTabId?.[pane.tabId]?.ptyIdsByLeafId?.[pane.leafId] !== args.ptyId
+  ) {
+    return undefined
+  }
+  const routing = resolveAgentStatusConnectionRouting(args)
+  if (!routing) {
+    return undefined
+  }
+  // Why: transient relay reconnect clears statuses without dropping durable
+  // PTY bindings; old renderer callbacks must stay blocked until reconnect.
+  if (
+    routing.connectionId !== null &&
+    (args.state.sshConnectionStates.get(routing.connectionId)?.status !== 'connected' ||
+      routing.connectionId in args.state.transientClearedAgentStatusConnectionIds)
+  ) {
+    return undefined
+  }
+  return routing
+}
diff --git a/src/renderer/src/lib/automation-session-observer.test.ts b/src/renderer/src/lib/automation-session-observer.test.ts
index 6c8efbf81cf..69c75319fed 100644
--- a/src/renderer/src/lib/automation-session-observer.test.ts
+++ b/src/renderer/src/lib/automation-session-observer.test.ts
@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { toAppSshPtyId } from '../../../shared/ssh-pty-id'
 
 const mockSubscribeToPtyData = vi.fn()
 const mockSubscribeToPtyExit = vi.fn()
@@ -10,6 +11,13 @@ const state = {
     activeRuntimeEnvironmentId: null as string | null,
     terminalMainSideEffectAuthority: undefined as boolean | undefined
   },
+  terminalLayoutsByTabId: {} as Record<
+    string,
+    { ptyIdsByLeafId?: Record<string, string | undefined> }
+  >,
+  ptyIdsByTabId: {} as Record<string, string[]>,
+  sshConnectionStates: new Map<string, { status: string }>(),
+  transientClearedAgentStatusConnectionIds: {} as Record<string, true>,
   setAgentStatus: vi.fn()
 }
 
@@ -37,6 +45,8 @@ vi.mock('@/runtime/remote-runtime-terminal-multiplexer', () => ({
 }))
 
 const DONE_STATUS_OSC = '\x1b]9999;{"state":"done","prompt":"ok","agentType":"codex"}\x07'
+const LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const PANE_KEY = `tab-1:${LEAF_ID}`
 
 describe('observeExistingAutomationSession', () => {
   beforeEach(() => {
@@ -45,6 +55,10 @@ describe('observeExistingAutomationSession', () => {
       activeRuntimeEnvironmentId: null,
       terminalMainSideEffectAuthority: undefined
     }
+    state.terminalLayoutsByTabId = {}
+    state.ptyIdsByTabId = {}
+    state.sshConnectionStates = new Map()
+    state.transientClearedAgentStatusConnectionIds = {}
     mockSubscribeToPtyData.mockReturnValue(vi.fn())
     mockSubscribeToPtyExit.mockReturnValue(vi.fn())
     mockCallRuntimeRpc.mockReturnValue(new Promise(() => {}))
@@ -59,7 +73,7 @@ describe('observeExistingAutomationSession', () => {
 
     await observeExistingAutomationSession({
       ptyId: 'pty-local-1',
-      paneKey: 'tab-1:leaf-1',
+      paneKey: PANE_KEY,
       runId: 'run-1',
       onData: vi.fn(),
       onAgentStatus,
@@ -77,12 +91,16 @@ describe('observeExistingAutomationSession', () => {
 
   it('keeps the legacy OSC store write when the kill switch is off', async () => {
     state.settings.terminalMainSideEffectAuthority = false
+    state.terminalLayoutsByTabId = {
+      'tab-1': { ptyIdsByLeafId: { [LEAF_ID]: 'pty-local-1' } }
+    }
+    state.ptyIdsByTabId = { 'tab-1': ['pty-local-1'] }
     const onAgentStatus = vi.fn()
     const { observeExistingAutomationSession } = await import('./automation-session-observer')
 
     await observeExistingAutomationSession({
       ptyId: 'pty-local-1',
-      paneKey: 'tab-1:leaf-1',
+      paneKey: PANE_KEY,
       runId: 'run-1',
       onData: vi.fn(),
       onAgentStatus,
@@ -93,20 +111,26 @@ describe('observeExistingAutomationSession', () => {
     handleData(DONE_STATUS_OSC)
 
     expect(state.setAgentStatus).toHaveBeenCalledWith(
-      'tab-1:leaf-1',
+      PANE_KEY,
       expect.objectContaining({ state: 'done', prompt: 'ok', agentType: 'codex' }),
-      undefined
+      undefined,
+      undefined,
+      { connectionId: null }
     )
     expect(onAgentStatus).toHaveBeenCalledTimes(1)
   })
 
   it('keeps the OSC store write for remote-runtime PTYs (bytes never transit local main)', async () => {
+    state.terminalLayoutsByTabId = {
+      'tab-1': { ptyIdsByLeafId: { [LEAF_ID]: 'remote:env-1@@terminal-9' } }
+    }
+    state.ptyIdsByTabId = { 'tab-1': ['remote:env-1@@terminal-9'] }
     const onAgentStatus = vi.fn()
     const { observeExistingAutomationSession } = await import('./automation-session-observer')
 
     await observeExistingAutomationSession({
       ptyId: 'remote:env-1@@terminal-9',
-      paneKey: 'tab-1:leaf-1',
+      paneKey: PANE_KEY,
       runId: 'run-1',
       onData: vi.fn(),
       onAgentStatus,
@@ -120,10 +144,91 @@ describe('observeExistingAutomationSession', () => {
     callbacks.onData(DONE_STATUS_OSC)
 
     expect(state.setAgentStatus).toHaveBeenCalledWith(
-      'tab-1:leaf-1',
+      PANE_KEY,
       expect.objectContaining({ state: 'done', prompt: 'ok', agentType: 'codex' }),
-      undefined
+      undefined,
+      undefined,
+      { connectionId: null }
     )
     expect(onAgentStatus).toHaveBeenCalledTimes(1)
   })
+
+  it('stamps the exact SSH PTY in the legacy renderer fallback', async () => {
+    state.settings.terminalMainSideEffectAuthority = false
+    const ptyId = toAppSshPtyId('ssh-a', 'pty-1')
+    state.sshConnectionStates = new Map([['ssh-a', { status: 'connected' }]])
+    state.terminalLayoutsByTabId = {
+      'tab-1': { ptyIdsByLeafId: { [LEAF_ID]: ptyId } }
+    }
+    state.ptyIdsByTabId = { 'tab-1': [ptyId] }
+    const { observeExistingAutomationSession } = await import('./automation-session-observer')
+
+    await observeExistingAutomationSession({
+      ptyId,
+      paneKey: PANE_KEY,
+      runId: 'run-1',
+      onData: vi.fn(),
+      onAgentStatus: vi.fn(),
+      onExit: vi.fn()
+    })
+    const handleData = mockSubscribeToPtyData.mock.calls[0]?.[1] as (data: string) => void
+    handleData(DONE_STATUS_OSC)
+
+    expect(state.setAgentStatus).toHaveBeenCalledWith(
+      PANE_KEY,
+      expect.objectContaining({ state: 'done' }),
+      undefined,
+      undefined,
+      { connectionId: 'ssh-a' }
+    )
+  })
+
+  it('leaves the row unchanged after the pane rebinds to another SSH host', async () => {
+    state.settings.terminalMainSideEffectAuthority = false
+    const oldPtyId = toAppSshPtyId('ssh-a', 'pty-1')
+    state.terminalLayoutsByTabId = {
+      'tab-1': {
+        ptyIdsByLeafId: { [LEAF_ID]: toAppSshPtyId('ssh-b', 'pty-1') }
+      }
+    }
+    state.ptyIdsByTabId = { 'tab-1': [toAppSshPtyId('ssh-b', 'pty-1')] }
+    const { observeExistingAutomationSession } = await import('./automation-session-observer')
+
+    await observeExistingAutomationSession({
+      ptyId: oldPtyId,
+      paneKey: PANE_KEY,
+      runId: 'run-1',
+      onData: vi.fn(),
+      onAgentStatus: vi.fn(),
+      onExit: vi.fn()
+    })
+    const handleData = mockSubscribeToPtyData.mock.calls[0]?.[1] as (data: string) => void
+    handleData(DONE_STATUS_OSC)
+
+    expect(state.setAgentStatus).not.toHaveBeenCalled()
+  })
+
+  it('ignores a delayed callback after disconnect clears the live PTY index', async () => {
+    state.settings.terminalMainSideEffectAuthority = false
+    const ptyId = toAppSshPtyId('ssh-a', 'pty-1')
+    state.terminalLayoutsByTabId = {
+      'tab-1': { ptyIdsByLeafId: { [LEAF_ID]: ptyId } }
+    }
+    state.ptyIdsByTabId = { 'tab-1': [ptyId] }
+    const { observeExistingAutomationSession } = await import('./automation-session-observer')
+
+    await observeExistingAutomationSession({
+      ptyId,
+      paneKey: PANE_KEY,
+      runId: 'run-1',
+      onData: vi.fn(),
+      onAgentStatus: vi.fn(),
+      onExit: vi.fn()
+    })
+    const handleData = mockSubscribeToPtyData.mock.calls[0]?.[1] as (data: string) => void
+    state.ptyIdsByTabId = { 'tab-1': [] }
+    handleData(DONE_STATUS_OSC)
+
+    expect(state.setAgentStatus).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/renderer/src/lib/automation-session-observer.ts b/src/renderer/src/lib/automation-session-observer.ts
index 9976468ed69..768f13282ed 100644
--- a/src/renderer/src/lib/automation-session-observer.ts
+++ b/src/renderer/src/lib/automation-session-observer.ts
@@ -11,6 +11,7 @@ import { useAppStore } from '@/store'
 import { createAgentStatusOscProcessor } from '../../../shared/agent-status-osc'
 import type { ParsedAgentStatusPayload } from '../../../shared/agent-status-types'
 import { isMainTerminalSideEffectAuthorityForPty } from '@/components/terminal-pane/terminal-side-effect-facts-handler'
+import { resolveLiveAgentStatusConnectionRouting } from '@/lib/agent-status-connection-ownership'
 
 export async function observeExistingAutomationSession(args: {
   ptyId: string
@@ -38,7 +39,13 @@ export async function observeExistingAutomationSession(args: {
     const processed = processAgentStatus(data)
     for (const payload of processed.payloads) {
       if (!mainOwnsAgentStatusWrites) {
-        useAppStore.getState().setAgentStatus(paneKey, payload, undefined)
+        const state = useAppStore.getState()
+        const routing = resolveLiveAgentStatusConnectionRouting({ state, paneKey, ptyId })
+        // Why: a delayed reuse observer must not write into a pane that has
+        // since rebound to another host's colliding tab/pane identifiers.
+        if (routing) {
+          state.setAgentStatus(paneKey, payload, undefined, undefined, routing)
+        }
       }
       args.onAgentStatus(payload)
     }
diff --git a/src/renderer/src/lib/background-agent-status-consumer.ts b/src/renderer/src/lib/background-agent-status-consumer.ts
new file mode 100644
index 00000000000..6868280585c
--- /dev/null
+++ b/src/renderer/src/lib/background-agent-status-consumer.ts
@@ -0,0 +1,52 @@
+import { useAppStore } from '@/store'
+import { createAgentStatusOscProcessor } from '../../../shared/agent-status-osc'
+import type { ParsedAgentStatusPayload } from '../../../shared/agent-status-types'
+import {
+  resolveLiveAgentStatusConnectionRouting,
+  type AgentStatusConnectionRouting
+} from './agent-status-connection-ownership'
+
+export function createBackgroundAgentStatusConsumer(args: {
+  paneKey: string
+  launchToken: string
+  mainOwnsAgentStatusWrites: boolean
+  expectedConnectionId: string | null | undefined
+  runtimeEnvironmentId: string | null
+  getPtyId: () => string
+  onAgentStatus?: (payload: ParsedAgentStatusPayload) => void
+}): {
+  consume: (data: string) => void
+  resolveRouting: () => AgentStatusConnectionRouting | undefined
+} {
+  const processAgentStatus = createAgentStatusOscProcessor()
+  const resolveRouting = (): AgentStatusConnectionRouting | undefined => {
+    const ptyId = args.getPtyId()
+    const state = useAppStore.getState()
+    return resolveLiveAgentStatusConnectionRouting({
+      state,
+      paneKey: args.paneKey,
+      ptyId,
+      expectedConnectionId: args.expectedConnectionId,
+      runtimeEnvironmentId: args.runtimeEnvironmentId
+    })
+  }
+  const consume = (data: string): void => {
+    const processed = processAgentStatus(data)
+    for (const payload of processed.payloads) {
+      if (!args.mainOwnsAgentStatusWrites) {
+        const routing = resolveRouting()
+        // Why: hidden callbacks can outlive tab reuse; only the exact current
+        // pane-to-PTY binding may update its status ownership.
+        if (routing) {
+          useAppStore
+            .getState()
+            .setAgentStatus(args.paneKey, payload, undefined, undefined, routing, {
+              launchToken: args.launchToken
+            })
+        }
+      }
+      args.onAgentStatus?.(payload)
+    }
+  }
+  return { consume, resolveRouting }
+}
diff --git a/src/renderer/src/lib/command-code-prompt-status-seed.ts b/src/renderer/src/lib/command-code-prompt-status-seed.ts
index 50d72221910..e918d6bf988 100644
--- a/src/renderer/src/lib/command-code-prompt-status-seed.ts
+++ b/src/renderer/src/lib/command-code-prompt-status-seed.ts
@@ -1,23 +1,45 @@
 import { useAppStore } from '@/store'
 import { makePaneKey } from '../../../shared/stable-pane-id'
+import { getConnectionIdFromState } from './connection-owner-resolution'
+import { resolveLiveAgentStatusConnectionRouting } from './agent-status-connection-ownership'
 
 /**
  * Why: Command Code has no prompt-submit hook, so when Orca submits a generated
  * prompt after the TUI is ready, seed `working` at delivery time so sidebar and
  * activity surfaces don't stay idle until the first real hook event arrives.
  */
-export function seedCommandCodeSubmittedPromptStatus(tabId: string, prompt: string): void {
+export function seedCommandCodeSubmittedPromptStatus(
+  worktreeId: string,
+  tabId: string,
+  prompt: string
+): void {
   const state = useAppStore.getState()
   const leafId = state.terminalLayoutsByTabId[tabId]?.activeLeafId
-  if (!leafId) {
+  if (!leafId || !(state.tabsByWorktree[worktreeId] ?? []).some((tab) => tab.id === tabId)) {
+    return
+  }
+  const paneKey = makePaneKey(tabId, leafId)
+  const ptyId = state.terminalLayoutsByTabId[tabId]?.ptyIdsByLeafId?.[leafId]
+  if (!ptyId) {
+    return
+  }
+  const routing = resolveLiveAgentStatusConnectionRouting({
+    state,
+    paneKey,
+    ptyId,
+    expectedConnectionId: getConnectionIdFromState(state, worktreeId)
+  })
+  if (!routing) {
     return
   }
   try {
-    state.setAgentStatus(makePaneKey(tabId, leafId), {
-      state: 'working',
-      prompt,
-      agentType: 'command-code'
-    })
+    state.setAgentStatus(
+      paneKey,
+      { state: 'working', prompt, agentType: 'command-code' },
+      undefined,
+      undefined,
+      routing
+    )
   } catch {
     // Best-effort UI seed. Real hooks still own refinement/completion.
   }
diff --git a/src/renderer/src/lib/launch-agent-background-session.test.ts b/src/renderer/src/lib/launch-agent-background-session.test.ts
index a636cd147c0..3422f48f6f5 100644
--- a/src/renderer/src/lib/launch-agent-background-session.test.ts
+++ b/src/renderer/src/lib/launch-agent-background-session.test.ts
@@ -3,6 +3,7 @@ import { BACKGROUND_MOUNT_TERMINAL_WORKTREE_EVENT } from '@/constants/terminal'
 import { createCompatibleRuntimeStatusResponseIfNeeded } from '@/runtime/runtime-compatibility-test-fixture'
 import { clearRuntimeCompatibilityCacheForTests } from '@/runtime/runtime-rpc-client'
 import { resetRemoteRuntimeTerminalMultiplexersForTests } from '@/runtime/remote-runtime-terminal-multiplexer'
+import { toAppSshPtyId } from '../../../shared/ssh-pty-id'
 
 const mockSpawn = vi.fn()
 const mockKill = vi.fn()
@@ -69,6 +70,13 @@ const state = {
     ]
   },
   tabsByWorktree: { 'wt-1': [] as { id: string; title: string }[] },
+  terminalLayoutsByTabId: {} as Record<
+    string,
+    { ptyIdsByLeafId?: Record<string, string | undefined> }
+  >,
+  ptyIdsByTabId: {} as Record<string, string[]>,
+  sshConnectionStates: new Map<string, { status: string }>(),
+  transientClearedAgentStatusConnectionIds: {} as Record<string, true>,
   allWorktrees: vi.fn(() => state.worktreesByRepo['repo-1']),
   createTab: mockCreateTab,
   setTabCustomTitle: mockSetTabCustomTitle,
@@ -145,6 +153,10 @@ describe('launchAgentBackgroundSession', () => {
       ]
     }
     state.tabsByWorktree = { 'wt-1': [] }
+    state.terminalLayoutsByTabId = {}
+    state.ptyIdsByTabId = {}
+    state.sshConnectionStates = new Map()
+    state.transientClearedAgentStatusConnectionIds = {}
     mockCreateTab.mockImplementation(() => {
       const tab = { id: 'tab-1', title: 'Terminal 1' }
       state.tabsByWorktree['wt-1'].push(tab)
@@ -153,6 +165,12 @@ describe('launchAgentBackgroundSession', () => {
     mockCloseTab.mockImplementation((tabId: string) => {
       state.tabsByWorktree['wt-1'] = state.tabsByWorktree['wt-1'].filter((tab) => tab.id !== tabId)
     })
+    mockSetTabLayout.mockImplementation((tabId: string, layout) => {
+      state.terminalLayoutsByTabId[tabId] = layout
+    })
+    mockUpdateTabPtyId.mockImplementation((tabId: string, ptyId: string) => {
+      state.ptyIdsByTabId[tabId] = [ptyId]
+    })
     mockSpawn.mockResolvedValue({ id: 'pty-1' })
     mockRuntimeEnvironmentCall.mockResolvedValue({
       ok: true,
@@ -440,35 +458,29 @@ describe('launchAgentBackgroundSession', () => {
     expect(mockSpawn).toHaveBeenCalled()
   })
 
-  it('parses agent status from hidden PTY output when the kill switch is off', async () => {
+  it('stamps hidden SSH status from renderer fallback when the kill switch is off', async () => {
     // Why: with main side-effect authority disabled, this sidecar is the only
-    // OSC 9999 → store path for hidden local sessions.
+    // OSC 9999 → store path for hidden SSH sessions.
     state.settings.terminalMainSideEffectAuthority = false
-    const onAgentStatus = vi.fn()
+    state.repos = [{ id: 'repo-1', connectionId: 'ssh-a', path: '/repo' }]
+    state.sshConnectionStates = new Map([['ssh-a', { status: 'connected' }]])
+    mockSpawn.mockResolvedValue({ id: toAppSshPtyId('ssh-a', 'pty-1') })
     const { launchAgentBackgroundSession } = await import('./launch-agent-background-session')
 
     await launchAgentBackgroundSession({
       agent: 'claude',
       worktreeId: 'wt-1',
-      prompt: 'run the automation',
-      onAgentStatus
+      prompt: 'run the automation'
     })
 
     const dataSidecar = mockSubscribeToPtyData.mock.calls[0]?.[1] as (data: string) => void
     dataSidecar('\x1b]9999;{"state":"done","prompt":"ok","agentType":"codex"}\x07')
 
-    const paneKey = expectStablePaneSpawn()
-    expect(state.setAgentStatus).toHaveBeenCalledWith(
-      paneKey,
-      expect.objectContaining({ state: 'done', prompt: 'ok', agentType: 'codex' }),
-      undefined,
-      undefined,
-      undefined,
-      { launchToken: expect.stringMatching(UUID_RE) }
-    )
-    expect(onAgentStatus).toHaveBeenCalledWith(
-      expect.objectContaining({ state: 'done', prompt: 'ok', agentType: 'codex' })
-    )
+    expectStablePaneSpawn()
+    expect(state.setAgentStatus.mock.calls.at(-1)?.[4]).toEqual({ connectionId: 'ssh-a' })
+    expect(state.setAgentStatus.mock.calls.at(-1)?.[5]).toEqual({
+      launchToken: expect.stringMatching(UUID_RE)
+    })
   })
 
   it('skips the duplicate OSC store write under main side-effect authority', async () => {
@@ -494,7 +506,10 @@ describe('launchAgentBackgroundSession', () => {
     )
   })
 
-  it('seeds a working status for Command Code prompt launches', async () => {
+  it('stamps a working status for SSH Command Code prompt launches', async () => {
+    state.repos = [{ id: 'repo-1', connectionId: 'ssh-a', path: '/repo' }]
+    state.sshConnectionStates = new Map([['ssh-a', { status: 'connected' }]])
+    mockSpawn.mockResolvedValue({ id: toAppSshPtyId('ssh-a', 'pty-1') })
     const { launchAgentBackgroundSession } = await import('./launch-agent-background-session')
 
     await launchAgentBackgroundSession({
@@ -503,26 +518,16 @@ describe('launchAgentBackgroundSession', () => {
       prompt: 'check the status spinner'
     })
 
-    const paneKey = expectStablePaneSpawn()
-    expect(state.setAgentStatus).toHaveBeenCalledWith(
-      paneKey,
-      {
-        state: 'working',
-        prompt: 'check the status spinner',
-        agentType: 'command-code'
+    expectStablePaneSpawn()
+    expect(state.setAgentStatus.mock.calls.at(-1)?.[4]).toEqual({ connectionId: 'ssh-a' })
+    expect(state.setAgentStatus.mock.calls.at(-1)?.[5]).toEqual({
+      launchConfig: {
+        agentCommand: "command-code --trust '--yolo'",
+        agentArgs: '--yolo',
+        agentEnv: {}
       },
-      undefined,
-      undefined,
-      undefined,
-      {
-        launchConfig: {
-          agentCommand: "command-code --trust '--yolo'",
-          agentArgs: '--yolo',
-          agentEnv: {}
-        },
-        launchToken: expect.stringMatching(UUID_RE)
-      }
-    )
+      launchToken: expect.stringMatching(UUID_RE)
+    })
   })
 
   it('uses a sidecar exit watcher so completion survives terminal attachment', async () => {
diff --git a/src/renderer/src/lib/launch-agent-background-session.ts b/src/renderer/src/lib/launch-agent-background-session.ts
index 10f96825407..6ba76340cd9 100644
--- a/src/renderer/src/lib/launch-agent-background-session.ts
+++ b/src/renderer/src/lib/launch-agent-background-session.ts
@@ -33,13 +33,13 @@ import {
   subscribeToRuntimeTerminalData,
   toRemoteRuntimePtyId
 } from '@/runtime/runtime-terminal-stream'
-import { createAgentStatusOscProcessor } from '../../../shared/agent-status-osc'
 import type { RuntimeTerminalCreate } from '../../../shared/runtime-types'
 import { createSshBackgroundStartupDelivery } from '@/lib/ssh-background-startup-delivery'
 import { shouldUseShellReadyStartupDelivery } from '../../../shared/codex-startup-delivery'
 import { isMainTerminalSideEffectAuthorityForPty } from '@/components/terminal-pane/terminal-side-effect-facts-handler'
 import { resolveLocalWindowsAgentStartupShell } from '../../../shared/windows-terminal-shell'
 import { runBestEffortAgentBackgroundCleanups } from '@/lib/agent-background-session-cleanup'
+import { createBackgroundAgentStatusConsumer } from '@/lib/background-agent-status-consumer'
 
 export async function launchAgentBackgroundSession(
   args: LaunchAgentBackgroundSessionArgs
@@ -172,20 +172,20 @@ export async function launchAgentBackgroundSession(
     settings: store.settings,
     runtimeEnvironmentId: runtimeTarget.kind === 'environment' ? runtimeTarget.environmentId : null
   })
-  const processAgentStatus = createAgentStatusOscProcessor()
+  const agentStatusConsumer = createBackgroundAgentStatusConsumer({
+    paneKey,
+    launchToken,
+    mainOwnsAgentStatusWrites,
+    expectedConnectionId: repo ? (repo.connectionId ?? null) : undefined,
+    runtimeEnvironmentId: runtimeTarget.kind === 'environment' ? runtimeTarget.environmentId : null,
+    getPtyId: () => ptyId,
+    onAgentStatus
+  })
   const handleData = (data: string): void => {
     data = sshStartupDelivery.handleData(data)
     onData?.(data)
     sshStartupDelivery.schedule(ptyId)
-    const processed = processAgentStatus(data)
-    for (const payload of processed.payloads) {
-      if (!mainOwnsAgentStatusWrites) {
-        useAppStore.getState().setAgentStatus(paneKey, payload, undefined, undefined, undefined, {
-          launchToken
-        })
-      }
-      onAgentStatus?.(payload)
-    }
+    agentStatusConsumer.consume(data)
   }
   try {
     if (runtimeTarget.kind === 'environment') {
@@ -263,18 +263,17 @@ export async function launchAgentBackgroundSession(
     if (agent === 'command-code' && hasPrompt && !isFollowupPath) {
       // Why: Command Code does not expose a prompt-start hook; seed working for
       // hidden prompt launches so sidebar/activity surfaces do not stay idle.
-      store.setAgentStatus(
-        paneKey,
-        {
-          state: 'working',
-          prompt: trimmedPrompt,
-          agentType: agent
-        },
-        undefined,
-        undefined,
-        undefined,
-        { launchConfig: startupPlan.launchConfig, launchToken }
-      )
+      const routing = agentStatusConsumer.resolveRouting()
+      if (routing) {
+        store.setAgentStatus(
+          paneKey,
+          { state: 'working', prompt: trimmedPrompt, agentType: agent },
+          undefined,
+          undefined,
+          routing,
+          { launchConfig: startupPlan.launchConfig, launchToken }
+        )
+      }
     }
 
     if (runtimeTarget.kind === 'environment') {
diff --git a/src/renderer/src/lib/launch-agent-in-new-tab.test.ts b/src/renderer/src/lib/launch-agent-in-new-tab.test.ts
index c43f98ef969..547bbefed7e 100644
--- a/src/renderer/src/lib/launch-agent-in-new-tab.test.ts
+++ b/src/renderer/src/lib/launch-agent-in-new-tab.test.ts
@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { toAppSshPtyId } from '../../../shared/ssh-pty-id'
 
 const mockCreateTab = vi.fn()
 const mockQueueTabStartupCommand = vi.fn()
@@ -43,6 +44,8 @@ const store = {
       | { kind: 'wsl'; distro: string | null }
   }[],
   repos: [{ id: 'repo-1', connectionId: null as string | null, path: '/repo' }],
+  sshConnectionStates: new Map([['ssh-a', { status: 'connected' }]]),
+  transientClearedAgentStatusConnectionIds: {} as Record<string, true>,
   worktreesByRepo: {
     'repo-1': [
       {
@@ -61,7 +64,11 @@ const store = {
   openFiles: [] as { id: string; worktreeId: string }[],
   browserTabsByWorktree: {} as Record<string, { id: string }[]>,
   tabBarOrderByWorktree: {} as Record<string, string[]>,
-  terminalLayoutsByTabId: {} as Record<string, { activeLeafId: string | null }>,
+  terminalLayoutsByTabId: {} as Record<
+    string,
+    { activeLeafId: string | null; ptyIdsByLeafId?: Record<string, string> }
+  >,
+  ptyIdsByTabId: {} as Record<string, string[]>,
   createTab: mockCreateTab,
   closeTab: vi.fn(),
   queueTabStartupCommand: mockQueueTabStartupCommand,
@@ -132,6 +139,8 @@ describe('launchAgentInNewTab', () => {
       }
     ]
     store.repos = [{ id: 'repo-1', connectionId: null, path: '/repo' }]
+    store.sshConnectionStates = new Map([['ssh-a', { status: 'connected' }]])
+    store.transientClearedAgentStatusConnectionIds = {}
     store.worktreesByRepo = {
       'repo-1': [
         {
@@ -148,6 +157,7 @@ describe('launchAgentInNewTab', () => {
     store.browserTabsByWorktree = {}
     store.tabBarOrderByWorktree = {}
     store.terminalLayoutsByTabId = {}
+    store.ptyIdsByTabId = {}
     mockCreateTab.mockReturnValue({ id: 'tab-1' })
     mockPasteDraftWhenAgentReady.mockResolvedValue(true)
   })
@@ -678,6 +688,7 @@ describe('launchAgentInNewTab', () => {
   })
 
   it('seeds working after Command Code submit-after-ready prompt delivery', async () => {
+    store.repos = [{ id: 'repo-1', connectionId: 'ssh-a', path: '/repo' }]
     const { launchAgentInNewTab } = await import('./launch-agent-in-new-tab')
 
     const result = launchAgentInNewTab({
@@ -686,7 +697,13 @@ describe('launchAgentInNewTab', () => {
       prompt: 'large generated prompt',
       promptDelivery: 'submit-after-ready'
     })
-    store.terminalLayoutsByTabId = { 'tab-1': { activeLeafId: LEAF_ID } }
+    store.terminalLayoutsByTabId = {
+      'tab-1': {
+        activeLeafId: LEAF_ID,
+        ptyIdsByLeafId: { [LEAF_ID]: toAppSshPtyId('ssh-a', 'pty-1') }
+      }
+    }
+    store.ptyIdsByTabId = { 'tab-1': [toAppSshPtyId('ssh-a', 'pty-1')] }
     await expect(result?.promptDeliveryResult).resolves.toEqual({
       delivered: true,
       failureNotified: false
@@ -709,14 +726,54 @@ describe('launchAgentInNewTab', () => {
         forcePaste: true
       })
     )
-    expect(mockSetAgentStatus).toHaveBeenCalledWith(`tab-1:${LEAF_ID}`, {
-      state: 'working',
-      prompt: 'large generated prompt',
-      agentType: 'command-code'
-    })
+    expect(mockSetAgentStatus).toHaveBeenCalledWith(
+      `tab-1:${LEAF_ID}`,
+      {
+        state: 'working',
+        prompt: 'large generated prompt',
+        agentType: 'command-code'
+      },
+      undefined,
+      undefined,
+      { connectionId: 'ssh-a' }
+    )
     expect(mockTrack).not.toHaveBeenCalledWith('agent_prompt_sent', expect.anything())
   })
 
+  it('does not recreate SSH status when clear arrives before disconnect state', async () => {
+    let finishDelivery: ((delivered: boolean) => void) | undefined
+    mockPasteDraftWhenAgentReady.mockReturnValue(
+      new Promise<boolean>((resolve) => {
+        finishDelivery = resolve
+      })
+    )
+    store.repos = [{ id: 'repo-1', connectionId: 'ssh-a', path: '/repo' }]
+    const ptyId = toAppSshPtyId('ssh-a', 'pty-1')
+    const { launchAgentInNewTab } = await import('./launch-agent-in-new-tab')
+
+    const result = launchAgentInNewTab({
+      agent: 'command-code',
+      worktreeId: 'wt-1',
+      prompt: 'pending prompt',
+      promptDelivery: 'submit-after-ready'
+    })
+    store.terminalLayoutsByTabId = {
+      'tab-1': { activeLeafId: LEAF_ID, ptyIdsByLeafId: { [LEAF_ID]: ptyId } }
+    }
+    store.ptyIdsByTabId = { 'tab-1': [ptyId] }
+
+    // Why: explicit disconnect sends the transient clear before its state
+    // event, while the old connection can still appear connected and bound.
+    store.transientClearedAgentStatusConnectionIds = { 'ssh-a': true }
+    finishDelivery?.(true)
+    await expect(result?.promptDeliveryResult).resolves.toEqual({
+      delivered: true,
+      failureNotified: false
+    })
+
+    expect(mockSetAgentStatus).not.toHaveBeenCalled()
+  })
+
   it('does not track prompt-sent when submit-after-ready delivery fails', async () => {
     mockPasteDraftWhenAgentReady.mockResolvedValue(false)
     const { launchAgentInNewTab } = await import('./launch-agent-in-new-tab')
diff --git a/src/renderer/src/lib/launch-agent-in-new-tab.ts b/src/renderer/src/lib/launch-agent-in-new-tab.ts
index 44e1f204811..6dca4ecf4aa 100644
--- a/src/renderer/src/lib/launch-agent-in-new-tab.ts
+++ b/src/renderer/src/lib/launch-agent-in-new-tab.ts
@@ -324,7 +324,7 @@ export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentI
         if (agent === 'command-code' && submitPastedPrompt) {
           // Why: Command Code has no prompt-submit hook; when Orca submits a
           // generated prompt after readiness, seed working at delivery time.
-          seedCommandCodeSubmittedPromptStatus(tab.id, trimmedPrompt)
+          seedCommandCodeSubmittedPromptStatus(worktreeId, tab.id, trimmedPrompt)
         }
         onPromptDelivered?.()
       }
diff --git a/src/renderer/src/store/slices/agent-status-ssh-connection-clear.test.ts b/src/renderer/src/store/slices/agent-status-ssh-connection-clear.test.ts
index 774264c2c37..51e01e07702 100644
--- a/src/renderer/src/store/slices/agent-status-ssh-connection-clear.test.ts
+++ b/src/renderer/src/store/slices/agent-status-ssh-connection-clear.test.ts
@@ -17,6 +17,7 @@ describe('agent status cleanup for a lost SSH connection', () => {
     const newerA = 'tab-new:33333333-3333-4333-8333-333333333333'
     const siblingB = 'tab-b:44444444-4444-4444-8444-444444444444'
     const unstamped = 'tab-legacy:55555555-5555-4555-8555-555555555555'
+    const local = 'tab-local:66666666-6666-4666-8666-666666666666'
     for (const [paneKey, updatedAt, connectionId] of [
       [oldA, 10, 'ssh-a'],
       [secondA, 20, 'ssh-a'],
@@ -41,6 +42,15 @@ describe('agent status cleanup for a lost SSH connection', () => {
         undefined,
         { updatedAt: 5 }
       )
+    store
+      .getState()
+      .setAgentStatus(
+        local,
+        { state: 'working', prompt: 'local', agentType: 'codex' },
+        undefined,
+        { updatedAt: 6 },
+        { connectionId: null }
+      )
     store.setState({
       agentLaunchConfigByPaneKey: {
         [oldA]: {
@@ -66,6 +76,7 @@ describe('agent status cleanup for a lost SSH connection', () => {
     expect(store.getState().agentStatusByPaneKey[newerA]).toBeDefined()
     expect(store.getState().agentStatusByPaneKey[siblingB]).toBeDefined()
     expect(store.getState().agentStatusByPaneKey[unstamped]).toBeDefined()
+    expect(store.getState().agentStatusByPaneKey[local]?.connectionId).toBeNull()
     expect(store.getState().agentLaunchConfigByPaneKey[oldA]).toBeDefined()
     expect(store.getState().acknowledgedAgentsByPaneKey[oldA]).toBe(2)
     expect(store.getState().retentionSuppressedPaneKeys[oldA]).toBe(true)
@@ -94,4 +105,57 @@ describe('agent status cleanup for a lost SSH connection', () => {
 
     expect(store.getState().agentStatusByPaneKey[paneKey]?.connectionId).toBe('ssh-a')
   })
+
+  it('blocks renderer callbacks at clear time until a later reconnect', () => {
+    const store = createTestStore()
+
+    store.getState().clearTransientAgentStatuses('ssh-a', 10)
+
+    expect(store.getState().transientClearedAgentStatusConnectionIds['ssh-a']).toBe(true)
+    store.getState().setSshConnectionState('ssh-a', {
+      targetId: 'ssh-a',
+      status: 'disconnected',
+      error: null,
+      reconnectAttempt: 0
+    })
+    expect(store.getState().transientClearedAgentStatusConnectionIds['ssh-a']).toBe(true)
+
+    store.getState().setSshConnectionState('ssh-a', {
+      targetId: 'ssh-a',
+      status: 'connected',
+      error: null,
+      reconnectAttempt: 0
+    })
+    expect(store.getState().transientClearedAgentStatusConnectionIds['ssh-a']).toBeUndefined()
+  })
+
+  it('moves a colliding pane to newer authoritative ownership', () => {
+    const store = createTestStore()
+    const paneKey = 'tab-a:11111111-1111-4111-8111-111111111111'
+    store
+      .getState()
+      .setAgentStatus(
+        paneKey,
+        { state: 'working', prompt: 'host a', agentType: 'codex' },
+        undefined,
+        { updatedAt: 1 },
+        { connectionId: 'ssh-a' }
+      )
+    store
+      .getState()
+      .setAgentStatus(
+        paneKey,
+        { state: 'working', prompt: 'host b', agentType: 'codex' },
+        undefined,
+        { updatedAt: 2 },
+        { connectionId: 'ssh-b' }
+      )
+
+    store.getState().clearTransientAgentStatuses('ssh-a', 3)
+
+    expect(store.getState().agentStatusByPaneKey[paneKey]).toMatchObject({
+      prompt: 'host b',
+      connectionId: 'ssh-b'
+    })
+  })
 })
diff --git a/src/renderer/src/store/slices/agent-status.ts b/src/renderer/src/store/slices/agent-status.ts
index c6b34559fe3..f30164e8790 100644
--- a/src/renderer/src/store/slices/agent-status.ts
+++ b/src/renderer/src/store/slices/agent-status.ts
@@ -117,6 +117,9 @@ export type AgentStatusSlice = {
   migrationUnsupportedByPtyId: Record<string, MigrationUnsupportedPtyEntry>
   /** Monotonic tick that advances when agent-status freshness boundaries pass. */
   agentStatusEpoch: number
+  /** SSH connections whose transient rows were cleared and must reject renderer callbacks
+   *  until a later reconnect establishes a new connection lifecycle. */
+  transientClearedAgentStatusConnectionIds: Record<string, true>
   /** Arm the shared freshness timer after an external mirror writes live rows. */
   scheduleAgentStatusFreshness: () => void
 
@@ -1156,6 +1159,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
     runtimeAgentOrchestrationByPaneKey: {},
     migrationUnsupportedByPtyId: {},
     agentStatusEpoch: 0,
+    transientClearedAgentStatusConnectionIds: {},
     retainedAgentsByPaneKey: {},
     sleepingAgentSessionsByPaneKey: {},
     agentLaunchConfigByPaneKey: {},
@@ -2209,16 +2213,24 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           next ??= { ...s.agentStatusByPaneKey }
           delete next[paneKey]
         }
-        if (!next) {
+        const wasAlreadyBlocked = connectionId in s.transientClearedAgentStatusConnectionIds
+        if (!next && wasAlreadyBlocked) {
           return s
         }
-        removed = true
+        removed = next !== null
         // Why: transport loss is reversible. Keep launch, resume, retention,
         // and acknowledgement maps intact for same-pane relay replay.
         return {
-          agentStatusByPaneKey: next,
-          agentStatusEpoch: s.agentStatusEpoch + 1,
-          sortEpoch: s.sortEpoch + 1
+          ...(next
+            ? {
+                agentStatusByPaneKey: next,
+                agentStatusEpoch: s.agentStatusEpoch + 1,
+                sortEpoch: s.sortEpoch + 1
+              }
+            : {}),
+          transientClearedAgentStatusConnectionIds: wasAlreadyBlocked
+            ? s.transientClearedAgentStatusConnectionIds
+            : { ...s.transientClearedAgentStatusConnectionIds, [connectionId]: true }
         }
       })
       if (removed) {
diff --git a/src/renderer/src/store/slices/ssh-target-cleanup.ts b/src/renderer/src/store/slices/ssh-target-cleanup.ts
index 800e58cdd87..34331e8c9a0 100644
--- a/src/renderer/src/store/slices/ssh-target-cleanup.ts
+++ b/src/renderer/src/store/slices/ssh-target-cleanup.ts
@@ -141,6 +141,14 @@ export function buildRemovedSshTargetCleanupPatch(
   }
 
   const nextDeferredTargets = state.deferredSshReconnectTargets.filter((id) => id !== targetId)
+  const nextTransientClearedConnections = {
+    ...state.transientClearedAgentStatusConnectionIds
+  }
+  const removedTransientClearBlock = Object.prototype.hasOwnProperty.call(
+    nextTransientClearedConnections,
+    targetId
+  )
+  delete nextTransientClearedConnections[targetId]
   const nextConnectionStates = new Map(state.sshConnectionStates)
   const removedConnectionState = nextConnectionStates.delete(targetId)
   const nextLabels = new Map(state.sshTargetLabels)
@@ -170,6 +178,7 @@ export function buildRemovedSshTargetCleanupPatch(
   const removedDeferredTarget =
     nextDeferredTargets.length !== state.deferredSshReconnectTargets.length
   const changed =
+    removedTransientClearBlock ||
     removedConnectionState ||
     removedLabel ||
     removedHydrated ||
@@ -185,6 +194,9 @@ export function buildRemovedSshTargetCleanupPatch(
   }
 
   return {
+    ...(removedTransientClearBlock
+      ? { transientClearedAgentStatusConnectionIds: nextTransientClearedConnections }
+      : {}),
     ...(removedConnectionState ? { sshConnectionStates: nextConnectionStates } : {}),
     ...(removedLabel ? { sshTargetLabels: nextLabels } : {}),
     ...(removedHydrated ? { remoteWorkspaceHydratedTargetIds: nextHydrated } : {}),
diff --git a/src/renderer/src/store/slices/ssh.test.ts b/src/renderer/src/store/slices/ssh.test.ts
index bd5ca9321bb..0ad672c9177 100644
--- a/src/renderer/src/store/slices/ssh.test.ts
+++ b/src/renderer/src/store/slices/ssh.test.ts
@@ -98,6 +98,10 @@ describe('createSshSlice', () => {
         { requestId: 'req-2', targetId: otherTargetId, kind: 'password', detail: 'password' }
       ],
       deferredSshReconnectTargets: [targetId, otherTargetId],
+      transientClearedAgentStatusConnectionIds: {
+        [targetId]: true,
+        [otherTargetId]: true
+      },
       deferredSshSessionIdsByTabId: {
         'tab-ssh': 'legacy-session-without-target-prefix',
         'tab-stale-encoded': toAppSshPtyId(targetId, 'pty-1'),
@@ -116,6 +120,9 @@ describe('createSshSlice', () => {
     expect(state.detectedPortsByConnection[targetId]).toBeUndefined()
     expect(state.sshCredentialQueue.map((req) => req.targetId)).toEqual([otherTargetId])
     expect(state.deferredSshReconnectTargets).toEqual([otherTargetId])
+    expect(state.transientClearedAgentStatusConnectionIds).toEqual({
+      [otherTargetId]: true
+    })
     expect(state.deferredSshSessionIdsByTabId).toEqual({
       'tab-other': toAppSshPtyId(otherTargetId, 'pty-2')
     })
@@ -223,6 +230,15 @@ describe('createSshSlice', () => {
     expect(store.getState()).toBe(previousState)
   })
 
+  it("removes a transient-clear block when it is the target's only remaining state", () => {
+    const store = createTestStore()
+    store.setState({ transientClearedAgentStatusConnectionIds: { 'ssh-1': true } })
+
+    store.getState().clearRemovedSshTargetState('ssh-1')
+
+    expect(store.getState().transientClearedAgentStatusConnectionIds).toEqual({})
+  })
+
   it('preserves untouched cleanup slice references while removing deferred target metadata', () => {
     const store = createTestStore()
     const sshConnectionStates = new Map([
diff --git a/src/renderer/src/store/slices/ssh.ts b/src/renderer/src/store/slices/ssh.ts
index 6b80e054353..7f02a5becb5 100644
--- a/src/renderer/src/store/slices/ssh.ts
+++ b/src/renderer/src/store/slices/ssh.ts
@@ -92,12 +92,18 @@ export const createSshSlice: StateCreator<AppState, [], [], SshSlice> = (set) =>
         return s
       }
       next.set(targetId, state)
+      const didReconnect = previous?.status !== 'connected' && state.status === 'connected'
+      let blockedConnections = s.transientClearedAgentStatusConnectionIds
+      if (didReconnect && targetId in blockedConnections) {
+        blockedConnections = { ...blockedConnections }
+        delete blockedConnections[targetId]
+      }
       return {
         sshConnectionStates: next,
-        sshConnectedGeneration:
-          previous?.status !== 'connected' && state.status === 'connected'
-            ? s.sshConnectedGeneration + 1
-            : s.sshConnectedGeneration
+        sshConnectedGeneration: didReconnect
+          ? s.sshConnectedGeneration + 1
+          : s.sshConnectedGeneration,
+        transientClearedAgentStatusConnectionIds: blockedConnections
       }
     }),
 

From 5fcf777617213c1703817f279791b9feb22ac252 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Sun, 19 Jul 2026 23:42:31 -0700
Subject: [PATCH 32/54] feat(mobile): Quick Commands (terminal + agent-prompt
 presets) (#9298)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(mobile): add Quick Commands (terminal + agent-prompt presets)

Brings the desktop Terminal Quick Commands feature to mobile: saved
agent-prompt or terminal-command presets that launch a new terminal tab.

Entry point sits in the session tab strip next to the "+" new-terminal
button (with a divider) — quick commands spawn a tab, so they live with
tab creation, mirroring desktop's tab-bar split button.

- Launcher button + Quick Commands bottom sheet (search, This project /
  Global groups, run/edit/delete rows, add row).
- Add/Edit sheet mirroring desktop TerminalQuickCommandDialog: Label,
  Action toggle (Terminal Command | Agent Prompt), Agent select, Prompt /
  Command Text, Advanced (Append Enter, Scope Global/Project), validation
  and save-failure feedback.
- Launch reuses handleCreateTerminal (extended with enter + toast copy):
  agent prompts launch the agent then deliver the prompt; terminal
  commands run the (Enter-appended) command text.
- Expose terminalQuickCommands over the remote/mobile RPC surface
  (getClientSettings/updateClientSettings allowlists, RuntimeStore type,
  and the strict SettingsUpdate zod schema).
- Mirror the agent-prompt support predicate mobile-side (stdin-after-start
  agents are unsupported) with a parity test guarding drift from desktop.
- Mock server: sample quick commands + settings.update handler for QA.

* fix(mobile): harden quick command execution

* fix(mobile): harden quick command persistence and launch

* test(mobile): preserve unexpected quick command errors

* fix(mobile): harden quick command launch performance

* fix(runtime): reject malformed quick command updates

* refactor(mobile): reuse shared quick-command logic instead of mirroring

The mobile quick-commands mirror was built on a false premise — that
runtime-importing src/shared/terminal-quick-commands breaks the RN bundle
/ Vitest. It doesn't: tui-agent-config → orca-cli-command-name is a pure
leaf with no module-load Node APIs (verified via probe + bundle-graph).

- Mobile now reuses the canonical desktop helpers (action/agent/scope/
  matchesRepo/support/flatten) directly from src/shared; only genuinely
  mobile-specific pieces (agent-branded labels, native row truncation,
  the launch plan) stay local.
- Multiline runnable terminal commands now flatten via the shared
  flattenTerminalQuickCommand (";"-join) — unity with desktop, so a
  command saved on one runs identically on the other.
- Drop the MOBILE_TUI_AGENT_PROMPT_COMMAND_UNSUPPORTED mirror + its parity
  test; use the shared supportsTerminalAgentQuickCommand predicate.
- Export the shared MAX_QUICK_COMMAND_* length caps for reuse.

* fix(mobile): protect quick command data boundaries

* fix(mobile): enforce quick command limits

* fix(mobile): make quick command updates atomic

* fix(mobile): keep quick command filters recoverable

* fix(mobile): use filled play icon for quick commands

* Revert "fix(mobile): use filled play icon for quick commands"

This reverts commit 169bf053b060deabda489b92a8bba56c4a0a1ad6.

* fix(mobile): gate quick commands on host capability
---
 .../session/QuickCommandsTabButton.tsx        |  30 ++
 .../app/h/[hostId]/session/[worktreeId].tsx   | 103 ++++-
 .../session/mobile-session-frame-styles.ts    |   7 +
 mobile/scripts/mock-server-rpc-handlers.ts    |  39 ++
 mobile/src/session/QuickCommandEditorForm.tsx | 317 ++++++++++++++
 mobile/src/session/QuickCommandsList.test.ts  |  90 ++++
 mobile/src/session/QuickCommandsList.tsx      | 332 +++++++++++++++
 mobile/src/session/QuickCommandsSheet.test.ts | 225 ++++++++++
 mobile/src/session/QuickCommandsSheet.tsx     | 251 +++++++++++
 mobile/src/session/quick-command-draft.ts     | 116 ++++++
 mobile/src/session/use-quick-commands.test.ts | 391 ++++++++++++++++++
 mobile/src/session/use-quick-commands.ts      | 212 ++++++++++
 mobile/src/terminal/quick-commands.test.ts    |  89 ++++
 mobile/src/terminal/quick-commands.ts         | 105 +++++
 src/main/runtime/orca-runtime.test.ts         | 145 ++++++-
 src/main/runtime/orca-runtime.ts              |  41 +-
 .../runtime/rpc/methods/client-ui.test.ts     | 151 +++++++
 src/main/runtime/rpc/methods/client-ui.ts     |  17 +
 .../rpc/methods/session-tabs-schemas.ts       |  23 ++
 .../runtime/rpc/methods/session-tabs.test.ts  |  25 +-
 src/main/runtime/rpc/methods/session-tabs.ts  |   1 +
 .../terminal-quick-command-rpc-schema.ts      |  73 ++++
 src/main/runtime/runtime-rpc.ts               |   2 +
 src/shared/protocol-version.ts                |   4 +
 src/shared/terminal-quick-commands.test.ts    |  32 ++
 src/shared/terminal-quick-commands.ts         | 104 ++++-
 26 files changed, 2907 insertions(+), 18 deletions(-)
 create mode 100644 mobile/app/h/[hostId]/session/QuickCommandsTabButton.tsx
 create mode 100644 mobile/src/session/QuickCommandEditorForm.tsx
 create mode 100644 mobile/src/session/QuickCommandsList.test.ts
 create mode 100644 mobile/src/session/QuickCommandsList.tsx
 create mode 100644 mobile/src/session/QuickCommandsSheet.test.ts
 create mode 100644 mobile/src/session/QuickCommandsSheet.tsx
 create mode 100644 mobile/src/session/quick-command-draft.ts
 create mode 100644 mobile/src/session/use-quick-commands.test.ts
 create mode 100644 mobile/src/session/use-quick-commands.ts
 create mode 100644 mobile/src/terminal/quick-commands.test.ts
 create mode 100644 mobile/src/terminal/quick-commands.ts
 create mode 100644 src/main/runtime/rpc/methods/terminal-quick-command-rpc-schema.ts

diff --git a/mobile/app/h/[hostId]/session/QuickCommandsTabButton.tsx b/mobile/app/h/[hostId]/session/QuickCommandsTabButton.tsx
new file mode 100644
index 00000000000..5faebb7691d
--- /dev/null
+++ b/mobile/app/h/[hostId]/session/QuickCommandsTabButton.tsx
@@ -0,0 +1,30 @@
+import { Pressable, View } from 'react-native'
+import { SquareChevronRight } from 'lucide-react-native'
+
+import { colors } from '../../../../src/theme/mobile-theme'
+import { styles } from './mobile-session-styles'
+
+type Props = {
+  disabled: boolean
+  onPress: () => void
+}
+
+export function QuickCommandsTabButton({ disabled, onPress }: Props) {
+  return (
+    <>
+      <View style={styles.tabActionDivider} />
+      <Pressable
+        style={({ pressed }) => [
+          styles.newTerminalButton,
+          pressed && styles.newTerminalButtonPressed,
+          disabled && styles.newTerminalButtonDisabled
+        ]}
+        disabled={disabled}
+        onPress={onPress}
+        accessibilityLabel="Quick commands"
+      >
+        <SquareChevronRight size={16} color={colors.textSecondary} strokeWidth={2.2} />
+      </Pressable>
+    </>
+  )
+}
diff --git a/mobile/app/h/[hostId]/session/[worktreeId].tsx b/mobile/app/h/[hostId]/session/[worktreeId].tsx
index eaa04a7436a..08f1f16ae8a 100644
--- a/mobile/app/h/[hostId]/session/[worktreeId].tsx
+++ b/mobile/app/h/[hostId]/session/[worktreeId].tsx
@@ -75,6 +75,12 @@ import { useMobilePrBranchContext } from '../../../../src/session/use-mobile-pr-
 import { SessionDockColumn } from '../../../../src/session/SessionDockColumn'
 import { MobileSessionHeaderIconButton } from '../../../../src/session/MobileSessionHeaderIconButton'
 import { MobileSessionHeaderMoreActionsSheet } from '../../../../src/session/MobileSessionHeaderMoreActionsSheet'
+import { QuickCommandsSheet } from '../../../../src/session/QuickCommandsSheet'
+import {
+  buildMobileQuickCommandLaunch,
+  supportsMobileQuickCommands,
+  type MobileQuickCommandLaunch
+} from '../../../../src/terminal/quick-commands'
 import { MOBILE_AI_VAULT_CAPABILITY } from '../../../../src/agent-history/agent-history-capability'
 import type { ConnectionState, RpcFailure, RpcSuccess } from '../../../../src/transport/types'
 import { headlessActivationNeedsHostRenderer } from '../../../../src/worktree/worktree-activation-result'
@@ -233,7 +239,8 @@ import {
 } from '../../../../src/session/mobile-session-create-warning-state'
 import { colors, spacing } from '../../../../src/theme/mobile-theme'
 import { styles } from './mobile-session-styles'
-import type { DiffComment } from '../../../../../src/shared/types'
+import { QuickCommandsTabButton } from './QuickCommandsTabButton'
+import type { DiffComment, TerminalQuickCommand } from '../../../../../src/shared/types'
 import type {
   DiffCommentActions,
   DiffNotesDelivery,
@@ -812,7 +819,7 @@ export default function SessionScreen() {
     created?: string
     warning?: string
   }>()
-  const isFolderWorkspaceRoute = worktreeId.startsWith('folder:')
+  const isFolderWorkspaceRoute = worktreeId.startsWith('folder:') // Synthetic ids have no repo scope.
   const router = useRouter()
   const insets = useSafeAreaInsets()
   // Why: shared client per host owned by RpcClientProvider. See
@@ -924,6 +931,7 @@ export default function SessionScreen() {
     createMobileSessionCreateWarningState(initialCreateWarning)
   )
   const [showCreateTabDrawer, setShowCreateTabDrawer] = useState(false)
+  const [showQuickCommands, setShowQuickCommands] = useState(false)
   const [createTabAgentLoadState, setCreateTabAgentLoadState] =
     useState<MobileNewTabAgentLoadState>('idle')
   const [createTabAgentOptions, setCreateTabAgentOptions] = useState<MobileNewTabAgentOption[]>([])
@@ -1096,6 +1104,7 @@ export default function SessionScreen() {
   const [agentSessionHistorySupported, setAgentSessionHistorySupported] = useState<boolean | null>(
     null
   )
+  const [quickCommandsSupported, setQuickCommandsSupported] = useState<boolean | null>(null)
   // Why: stable callbacks (handleFileTap) read the live value via this ref, since
   // the capability probe resolves after the callbacks are created.
   const browserScreencastSupportedRef = useRef(browserScreencastSupported)
@@ -2448,9 +2457,15 @@ export default function SessionScreen() {
     if (!client || connState !== 'connected') {
       setBrowserScreencastSupported(null)
       setAgentSessionHistorySupported(null)
+      setQuickCommandsSupported(null)
+      setShowQuickCommands(false)
       hostQueryReplyInputSupportedRef.current = false
       return
     }
+    // Why: a client swap can keep the route connected while moving to an older
+    // host; clear the prior capability before exposing host-specific actions.
+    setQuickCommandsSupported(null)
+    setShowQuickCommands(false)
     let stale = false
     void client
       .sendRequest('status.get')
@@ -2465,6 +2480,7 @@ export default function SessionScreen() {
         setAgentSessionHistorySupported(
           status.capabilities?.includes(MOBILE_AI_VAULT_CAPABILITY) === true
         )
+        setQuickCommandsSupported(supportsMobileQuickCommands(status.capabilities))
         // Why: hosts without this capability strip inputKind from terminal.send,
         // so a forwarded xterm reply would become floor-stealing shell input.
         hostQueryReplyInputSupportedRef.current =
@@ -2474,6 +2490,8 @@ export default function SessionScreen() {
         if (!stale) {
           setBrowserScreencastSupported(false)
           setAgentSessionHistorySupported(false)
+          setQuickCommandsSupported(false)
+          setShowQuickCommands(false)
           hostQueryReplyInputSupportedRef.current = false
         }
       })
@@ -3939,7 +3957,10 @@ export default function SessionScreen() {
 
   async function handleCreateTerminal(
     agent?: MobileNewTabAgentOption['agent'],
-    options?: { initialPrompt?: string; onPromptSent?: () => void }
+    options?: MobileQuickCommandLaunch['options'] & {
+      onPromptSent?: () => void
+      errorToast?: string
+    }
   ) {
     if (!client || creatingTerminalRef.current) {
       return
@@ -3962,6 +3983,11 @@ export default function SessionScreen() {
         worktree: `id:${worktreeId}`,
         afterTabId: activeSessionTabId ?? undefined,
         clientMutationId,
+        ...(options?.startupCommand ? { command: options.startupCommand } : {}),
+        ...(options?.startupCommandDelivery
+          ? { startupCommandDelivery: options.startupCommandDelivery }
+          : {}),
+        ...(options?.agentPrompt ? { agentPrompt: options.agentPrompt } : {}),
         ...(agent ? { agent } : {})
       })
       if (response.ok) {
@@ -4019,7 +4045,7 @@ export default function SessionScreen() {
               .sendRequest('terminal.send', {
                 terminal: createdHandle,
                 text: options.initialPrompt,
-                enter: true,
+                enter: options.enter !== false,
                 ...(deviceTokenRef.current
                   ? { client: { id: deviceTokenRef.current, type: 'mobile' as const } }
                   : {})
@@ -4037,13 +4063,20 @@ export default function SessionScreen() {
                   throw new Error('Terminal input is locked by another client.')
                 }
                 triggerSuccess()
-                showToast('Notes sent')
+                showToast(options.successToast ?? 'Notes sent')
                 options.onPromptSent?.()
               })
               .catch((err) => {
                 triggerError()
-                showToast(err instanceof Error ? err.message : "Couldn't send notes", 1800)
+                showToast(
+                  options.errorToast ??
+                    (err instanceof Error ? err.message : "Couldn't send notes"),
+                  1800
+                )
               })
+          } else if (options?.successToast) {
+            triggerSuccess()
+            showToast(options.successToast)
           }
         } else {
           // Why: a prior pending handle must not outlive a create that returned
@@ -4054,16 +4087,53 @@ export default function SessionScreen() {
         }
         scheduleDelayedAction(() => void fetchSessionTabs(), 500)
       } else {
-        setCreateError('Failed to create terminal')
+        const message = options?.errorToast ?? 'Failed to create terminal'
+        setCreateError(message)
+        if (options?.errorToast) {
+          triggerError()
+          showToast(message, 1800)
+        }
       }
     } catch {
-      setCreateError('Failed to create terminal')
+      const message = options?.errorToast ?? 'Failed to create terminal'
+      setCreateError(message)
+      if (options?.errorToast) {
+        triggerError()
+        showToast(message, 1800)
+      }
     } finally {
       creatingTerminalRef.current = false
       setCreating(false)
     }
   }
 
+  // Quick commands spawn a fresh terminal tab, mirroring desktop's
+  // run-quick-command-in-new-tab: agent prompts and runnable terminal commands
+  // use the host's shell-ready startup path; insert-only commands stay drafts.
+  function launchQuickCommand(command: TerminalQuickCommand): boolean {
+    if (
+      !client ||
+      connState !== 'connected' ||
+      creatingTerminalRef.current ||
+      creatingBrowser ||
+      creatingMarkdown
+    ) {
+      return false
+    }
+    const launch = buildMobileQuickCommandLaunch(command)
+    if (!launch) {
+      triggerError()
+      showToast('Edit this quick command before running it', 1800)
+      return false
+    }
+    const label = command.label.trim() || 'Quick command'
+    void handleCreateTerminal(launch.agent, {
+      ...launch.options,
+      errorToast: `Couldn't run ${label}`
+    })
+    return true
+  }
+
   async function handleCreateMarkdownNote() {
     if (!client || creatingMarkdown) {
       return
@@ -4715,6 +4785,14 @@ export default function SessionScreen() {
               >
                 <Plus size={16} color={colors.textSecondary} strokeWidth={2.2} />
               </Pressable>
+              {quickCommandsSupported === true ? (
+                <QuickCommandsTabButton
+                  disabled={
+                    creating || creatingBrowser || creatingMarkdown || connState !== 'connected'
+                  }
+                  onPress={() => setShowQuickCommands(true)}
+                />
+              ) : null}
             </View>
           )}
         </SafeAreaView>
@@ -5261,6 +5339,15 @@ export default function SessionScreen() {
         onClose={() => setShowHeaderMoreActions(false)}
       />
 
+      <QuickCommandsSheet
+        visible={showQuickCommands && quickCommandsSupported === true}
+        onClose={() => setShowQuickCommands(false)}
+        client={client}
+        repoId={isFolderWorkspaceRoute ? null : getRepoIdFromMobileWorktreeId(worktreeId) || null}
+        repoName={worktreeName || null}
+        onLaunch={launchQuickCommand}
+      />
+
       <ActionSheetModal
         visible={showCreateTabDrawer}
         title="New Tab"
diff --git a/mobile/app/h/[hostId]/session/mobile-session-frame-styles.ts b/mobile/app/h/[hostId]/session/mobile-session-frame-styles.ts
index 875f48f68f6..738632ba495 100644
--- a/mobile/app/h/[hostId]/session/mobile-session-frame-styles.ts
+++ b/mobile/app/h/[hostId]/session/mobile-session-frame-styles.ts
@@ -135,6 +135,13 @@ export const mobileSessionFrameStyles = StyleSheet.create({
   newTerminalButtonDisabled: {
     opacity: 0.45
   },
+  // Divider between the + new-terminal button and the Quick Commands launcher,
+  // matching the tab strip's borderSubtle separators.
+  tabActionDivider: {
+    width: StyleSheet.hairlineWidth,
+    height: 18,
+    backgroundColor: colors.borderSubtle
+  },
   terminalFrame: {
     flex: 1,
     minHeight: 0,
diff --git a/mobile/scripts/mock-server-rpc-handlers.ts b/mobile/scripts/mock-server-rpc-handlers.ts
index 22b725ad129..6e889e5ac23 100644
--- a/mobile/scripts/mock-server-rpc-handlers.ts
+++ b/mobile/scripts/mock-server-rpc-handlers.ts
@@ -3,6 +3,11 @@ import {
   DESKTOP_PROTOCOL_VERSION,
   MIN_COMPATIBLE_MOBILE_VERSION
 } from '../../src/shared/protocol-version'
+import {
+  applyTerminalQuickCommandMutation,
+  type TerminalQuickCommandMutation
+} from '../../src/shared/terminal-quick-commands'
+import type { TerminalQuickCommand } from '../../src/shared/types'
 import { handleMockFilePreviewRequest } from './mock-server-file-preview-data'
 import { handleMockGitRequest } from './mock-server-git-state'
 import { FAKE_SCROLLBACK, STREAMING_CHUNKS } from './mock-server-terminal-fixtures'
@@ -15,6 +20,27 @@ const MOCK_RPC_DELAY_MS = readScenarioNumber('MOCK_RPC_DELAY_MS', 0)
 const FAKE_REPOS = createMockRepos(MOCK_REPO_COUNT)
 let fakeWorktrees = createMockWorktrees(FAKE_REPOS, MOCK_WORKTREE_COUNT)
 
+// Mutable quick-command list so the mobile Quick Commands sheet can add/edit/
+// delete against the mock the same way it does a paired desktop.
+let fakeQuickCommands: TerminalQuickCommand[] = [
+  {
+    id: 'qc-codex-review',
+    label: 'codex review',
+    action: 'agent-prompt',
+    agent: 'codex',
+    prompt: 'please review this diff for correctness and edge cases.',
+    scope: { type: 'global' }
+  },
+  {
+    id: 'qc-dev-server',
+    label: 'dev server',
+    action: 'terminal-command',
+    command: 'pnpm dev',
+    appendEnter: true,
+    scope: { type: 'global' }
+  }
+]
+
 const FAKE_TERMINALS = [
   {
     handle: 'term-1',
@@ -145,6 +171,19 @@ export function handleRequest(
       )
       break
 
+    case 'settings.getTerminalQuickCommands':
+      respond(success(request.id, { terminalQuickCommands: fakeQuickCommands }))
+      break
+
+    case 'settings.updateTerminalQuickCommands': {
+      const updates = (request.params ?? {}) as { mutation?: TerminalQuickCommandMutation }
+      if (updates.mutation) {
+        fakeQuickCommands = applyTerminalQuickCommandMutation(fakeQuickCommands, updates.mutation)
+      }
+      respond(success(request.id, { terminalQuickCommands: fakeQuickCommands }))
+      break
+    }
+
     case 'ui.get':
       respond(
         success(request.id, {
diff --git a/mobile/src/session/QuickCommandEditorForm.tsx b/mobile/src/session/QuickCommandEditorForm.tsx
new file mode 100644
index 00000000000..171bf8ef2ce
--- /dev/null
+++ b/mobile/src/session/QuickCommandEditorForm.tsx
@@ -0,0 +1,317 @@
+import { useState } from 'react'
+import { View, Text, Pressable, TextInput, StyleSheet, Switch } from 'react-native'
+import { ChevronDown, ChevronRight } from 'lucide-react-native'
+import { colors, spacing, radii, typography } from '../theme/mobile-theme'
+import { MobileAgentIcon } from '../components/MobileAgentIcon'
+import {
+  getQuickCommandAgentLabel,
+  MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH,
+  MAX_QUICK_COMMAND_LABEL_LENGTH,
+  MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH
+} from '../terminal/quick-commands'
+import type { QuickCommandDraft } from './quick-command-draft'
+import { isQuickCommandDraftValid } from './quick-command-draft'
+
+type Props = {
+  draft: QuickCommandDraft
+  mode: 'add' | 'edit'
+  saving: boolean
+  error: string | null
+  // A mobile session lives in one repo, so "Project" scope means the current
+  // worktree's repo — no cross-repo picker like desktop.
+  repoId: string | null
+  repoName: string | null
+  onChange: (patch: Partial<QuickCommandDraft>) => void
+  onOpenAgentPicker: () => void
+  onCancel: () => void
+  onSave: () => void
+}
+
+function ActionToggle({
+  value,
+  onChange
+}: {
+  value: QuickCommandDraft['action']
+  onChange: (action: QuickCommandDraft['action']) => void
+}) {
+  return (
+    <View style={styles.toggleGroup}>
+      {(['terminal-command', 'agent-prompt'] as const).map((action) => {
+        const selected = value === action
+        return (
+          <Pressable
+            key={action}
+            style={({ pressed }) => [
+              styles.toggleItem,
+              selected && styles.toggleItemSelected,
+              pressed && !selected && styles.pressed
+            ]}
+            onPress={() => onChange(action)}
+            accessibilityRole="button"
+            accessibilityState={{ selected }}
+          >
+            <Text style={[styles.toggleText, selected && styles.toggleTextSelected]}>
+              {action === 'terminal-command' ? 'Terminal Command' : 'Agent Prompt'}
+            </Text>
+          </Pressable>
+        )
+      })}
+    </View>
+  )
+}
+
+export function QuickCommandEditorForm({
+  draft,
+  mode,
+  saving,
+  error,
+  repoId,
+  repoName,
+  onChange,
+  onOpenAgentPicker,
+  onCancel,
+  onSave
+}: Props) {
+  const hasRepoScope = repoId !== null
+  const [advancedOpen, setAdvancedOpen] = useState(draft.scope.type === 'repo')
+  const isAgent = draft.action === 'agent-prompt'
+  const canSave = isQuickCommandDraftValid(draft) && !saving
+
+  return (
+    <View style={styles.form}>
+      <View style={styles.field}>
+        <Text style={styles.label}>Label</Text>
+        <TextInput
+          style={styles.input}
+          value={draft.label}
+          onChangeText={(label) => onChange({ label })}
+          placeholder="Start dev server"
+          placeholderTextColor={colors.textMuted}
+          autoCapitalize="none"
+          autoCorrect={false}
+          maxLength={MAX_QUICK_COMMAND_LABEL_LENGTH}
+        />
+      </View>
+
+      <View style={styles.field}>
+        <Text style={styles.label}>Action</Text>
+        <ActionToggle value={draft.action} onChange={(action) => onChange({ action })} />
+      </View>
+
+      {isAgent ? (
+        <View style={styles.field}>
+          <Text style={styles.label}>Agent</Text>
+          <Pressable
+            style={({ pressed }) => [styles.select, pressed && styles.pressed]}
+            onPress={onOpenAgentPicker}
+            accessibilityRole="button"
+          >
+            {draft.agent ? (
+              <View style={styles.selectValue}>
+                <MobileAgentIcon agentId={draft.agent} size={16} />
+                <Text style={styles.selectValueText}>{getQuickCommandAgentLabel(draft.agent)}</Text>
+              </View>
+            ) : (
+              <Text style={styles.selectPlaceholder}>Choose agent</Text>
+            )}
+            <ChevronDown size={16} color={colors.textMuted} />
+          </Pressable>
+        </View>
+      ) : null}
+
+      <View style={styles.field}>
+        <Text style={styles.label}>{isAgent ? 'Prompt' : 'Command Text'}</Text>
+        <TextInput
+          style={[styles.input, styles.textarea, !isAgent && styles.mono]}
+          value={isAgent ? draft.prompt : draft.command}
+          onChangeText={(text) => onChange(isAgent ? { prompt: text } : { command: text })}
+          placeholder={isAgent ? 'Ask the agent to investigate this workspace' : 'npm run dev'}
+          placeholderTextColor={colors.textMuted}
+          autoCapitalize="none"
+          autoCorrect={false}
+          multiline
+          maxLength={
+            isAgent ? MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH : MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH
+          }
+        />
+        {isAgent ? (
+          <Text style={styles.hint}>Supports skills, file paths, and built-in commands.</Text>
+        ) : null}
+      </View>
+
+      <View style={styles.field}>
+        <Pressable
+          style={({ pressed }) => [styles.advancedToggle, pressed && styles.pressed]}
+          onPress={() => setAdvancedOpen((open) => !open)}
+          accessibilityRole="button"
+          accessibilityState={{ expanded: advancedOpen }}
+        >
+          {advancedOpen ? (
+            <ChevronDown size={16} color={colors.textSecondary} />
+          ) : (
+            <ChevronRight size={16} color={colors.textSecondary} />
+          )}
+          <Text style={styles.advancedText}>Advanced</Text>
+        </Pressable>
+
+        {advancedOpen ? (
+          <View style={styles.advancedBody}>
+            {!isAgent ? (
+              <View style={styles.switchRow}>
+                <View style={styles.switchText}>
+                  <Text style={styles.switchTitle}>Append Enter</Text>
+                  <Text style={styles.switchDesc}>
+                    Submit immediately instead of only inserting text.
+                  </Text>
+                </View>
+                <Switch
+                  value={draft.appendEnter}
+                  onValueChange={(appendEnter) => onChange({ appendEnter })}
+                  trackColor={{ false: colors.bgRaised, true: colors.accentBlue }}
+                  thumbColor={colors.surfaceBright}
+                />
+              </View>
+            ) : null}
+
+            <View style={styles.field}>
+              <Text style={styles.label}>Scope</Text>
+              <View style={styles.toggleGroup}>
+                {(['global', 'repo'] as const).map((scopeType) => {
+                  const selected = draft.scope.type === scopeType
+                  const disabled = scopeType === 'repo' && !hasRepoScope
+                  return (
+                    <Pressable
+                      key={scopeType}
+                      disabled={disabled}
+                      style={({ pressed }) => [
+                        styles.toggleItem,
+                        selected && styles.toggleItemSelected,
+                        disabled && styles.toggleItemDisabled,
+                        pressed && !selected && !disabled && styles.pressed
+                      ]}
+                      onPress={() =>
+                        onChange({
+                          scope:
+                            scopeType === 'repo' && repoId
+                              ? { type: 'repo', repoId }
+                              : { type: 'global' }
+                        })
+                      }
+                      accessibilityRole="button"
+                      accessibilityState={{ selected, disabled }}
+                    >
+                      <Text style={[styles.toggleText, selected && styles.toggleTextSelected]}>
+                        {scopeType === 'global' ? 'Global' : 'Project'}
+                      </Text>
+                    </Pressable>
+                  )
+                })}
+              </View>
+              {draft.scope.type === 'repo' && repoName ? (
+                <Text style={styles.scopeRepoName}>{repoName}</Text>
+              ) : null}
+            </View>
+          </View>
+        ) : null}
+      </View>
+
+      {error ? <Text style={styles.error}>{error}</Text> : null}
+
+      <View style={styles.footer}>
+        <Pressable
+          style={({ pressed }) => [styles.button, styles.cancelButton, pressed && styles.pressed]}
+          onPress={onCancel}
+          accessibilityRole="button"
+        >
+          <Text style={styles.cancelText}>Cancel</Text>
+        </Pressable>
+        <Pressable
+          style={[styles.button, styles.saveButton, !canSave && styles.saveButtonDisabled]}
+          disabled={!canSave}
+          onPress={onSave}
+          accessibilityRole="button"
+        >
+          <Text style={[styles.saveText, !canSave && styles.saveTextDisabled]}>
+            {mode === 'edit' ? 'Save' : 'Add Quick Command'}
+          </Text>
+        </Pressable>
+      </View>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  form: { gap: spacing.md, paddingTop: spacing.xs, paddingBottom: spacing.sm },
+  field: { gap: spacing.sm },
+  label: { fontSize: 12, fontWeight: '600', color: colors.textSecondary },
+  input: {
+    backgroundColor: colors.bgPanel,
+    color: colors.textPrimary,
+    borderRadius: radii.input,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm + 2,
+    fontSize: 14,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle
+  },
+  textarea: { minHeight: 92, textAlignVertical: 'top' },
+  mono: { fontFamily: typography.monoFamily },
+  hint: { fontSize: 12, color: colors.textMuted },
+  error: { fontSize: 13, color: colors.statusRed, marginTop: spacing.xs },
+  pressed: { backgroundColor: colors.bgRaised },
+  toggleGroup: { flexDirection: 'row', gap: spacing.sm },
+  toggleItem: {
+    flex: 1,
+    height: 40,
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle,
+    backgroundColor: colors.bgPanel,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  toggleItemSelected: { backgroundColor: colors.bgRaised, borderColor: colors.textMuted },
+  toggleItemDisabled: { opacity: 0.4 },
+  toggleText: { fontSize: 13, fontWeight: '500', color: colors.textSecondary },
+  toggleTextSelected: { color: colors.textPrimary },
+  select: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    backgroundColor: colors.bgPanel,
+    borderRadius: radii.input,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm + 2
+  },
+  selectValue: { flexDirection: 'row', alignItems: 'center', gap: spacing.sm },
+  selectValueText: { fontSize: 14, color: colors.textPrimary },
+  selectPlaceholder: { fontSize: 14, color: colors.textMuted },
+  scopeRepoName: {
+    fontSize: 13,
+    color: colors.textSecondary,
+    fontFamily: typography.monoFamily,
+    paddingHorizontal: spacing.xs
+  },
+  advancedToggle: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.xs,
+    paddingVertical: spacing.xs
+  },
+  advancedText: { fontSize: 13, fontWeight: '600', color: colors.textSecondary },
+  advancedBody: { gap: spacing.md, paddingTop: spacing.xs },
+  switchRow: { flexDirection: 'row', alignItems: 'center', gap: spacing.md },
+  switchText: { flex: 1 },
+  switchTitle: { fontSize: 14, color: colors.textPrimary },
+  switchDesc: { fontSize: 12, color: colors.textMuted, marginTop: 1 },
+  footer: { flexDirection: 'row', gap: spacing.sm, marginTop: spacing.sm },
+  button: { flex: 1, borderRadius: 8, paddingVertical: spacing.md, alignItems: 'center' },
+  cancelButton: { borderWidth: 1, borderColor: colors.borderSubtle },
+  cancelText: { fontSize: 14, fontWeight: '600', color: colors.textPrimary },
+  saveButton: { backgroundColor: colors.textPrimary },
+  saveButtonDisabled: { backgroundColor: colors.bgRaised },
+  saveText: { fontSize: 14, fontWeight: '700', color: colors.bgBase },
+  saveTextDisabled: { color: colors.textMuted }
+})
diff --git a/mobile/src/session/QuickCommandsList.test.ts b/mobile/src/session/QuickCommandsList.test.ts
new file mode 100644
index 00000000000..eb2e2c787c0
--- /dev/null
+++ b/mobile/src/session/QuickCommandsList.test.ts
@@ -0,0 +1,90 @@
+import { createElement } from 'react'
+import { act, create, type ReactTestRenderer } from 'react-test-renderer'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { QUICK_COMMAND_SEARCH_QUERY_MAX_LENGTH, QuickCommandsList } from './QuickCommandsList'
+
+vi.mock('react-native', () => ({
+  ActivityIndicator: 'ActivityIndicator',
+  Pressable: 'Pressable',
+  StyleSheet: {
+    create: <T>(styles: T) => styles,
+    hairlineWidth: 1
+  },
+  Text: 'Text',
+  TextInput: 'TextInput',
+  View: 'View'
+}))
+
+vi.mock('lucide-react-native', () => ({
+  Check: 'Check',
+  Pencil: 'Pencil',
+  Play: 'Play',
+  Plus: 'Plus',
+  Search: 'Search',
+  Trash2: 'Trash2'
+}))
+
+vi.mock('../components/MobileAgentIcon', () => ({ MobileAgentIcon: 'MobileAgentIcon' }))
+
+describe('QuickCommandsList search', () => {
+  let renderer: ReactTestRenderer | null = null
+
+  beforeEach(() => {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true
+  })
+
+  afterEach(() => {
+    act(() => renderer?.unmount())
+    renderer = null
+  })
+
+  it('keeps an active filter clearable when only one command remains', async () => {
+    await act(async () => {
+      renderer = create(
+        createElement(QuickCommandsList, {
+          repoCommands: [],
+          globalCommands: [],
+          totalCount: 1,
+          query: 'missing',
+          loading: false,
+          disabled: false,
+          canAdd: true,
+          error: null,
+          onQueryChange: vi.fn(),
+          onLaunch: vi.fn(),
+          onEdit: vi.fn(),
+          onDelete: vi.fn(),
+          onAdd: vi.fn()
+        })
+      )
+    })
+
+    const search = renderer!.root.findByType('TextInput')
+    expect(search.props.value).toBe('missing')
+    expect(search.props.maxLength).toBe(QUICK_COMMAND_SEARCH_QUERY_MAX_LENGTH)
+  })
+
+  it('omits idle search chrome for a single command', async () => {
+    await act(async () => {
+      renderer = create(
+        createElement(QuickCommandsList, {
+          repoCommands: [],
+          globalCommands: [],
+          totalCount: 1,
+          query: '',
+          loading: false,
+          disabled: false,
+          canAdd: true,
+          error: null,
+          onQueryChange: vi.fn(),
+          onLaunch: vi.fn(),
+          onEdit: vi.fn(),
+          onDelete: vi.fn(),
+          onAdd: vi.fn()
+        })
+      )
+    })
+
+    expect(renderer!.root.findAllByType('TextInput')).toHaveLength(0)
+  })
+})
diff --git a/mobile/src/session/QuickCommandsList.tsx b/mobile/src/session/QuickCommandsList.tsx
new file mode 100644
index 00000000000..2c76884d335
--- /dev/null
+++ b/mobile/src/session/QuickCommandsList.tsx
@@ -0,0 +1,332 @@
+import { View, Text, Pressable, TextInput, StyleSheet, ActivityIndicator } from 'react-native'
+import { Pencil, Plus, Search, Trash2, Check, Play } from 'lucide-react-native'
+import { colors, spacing, typography } from '../theme/mobile-theme'
+import { MobileAgentIcon } from '../components/MobileAgentIcon'
+import { MOBILE_AGENT_CATALOG } from '../tasks/mobile-agent-catalog'
+import type { TerminalQuickCommand, TuiAgent } from '../../../src/shared/types'
+import {
+  getQuickCommandDisplayPreview,
+  isAgentQuickCommand,
+  supportsTerminalAgentQuickCommand
+} from '../terminal/quick-commands'
+
+export const QUICK_COMMAND_SUPPORTED_AGENTS = MOBILE_AGENT_CATALOG.filter((entry) =>
+  supportsTerminalAgentQuickCommand(entry.id)
+)
+
+export const QUICK_COMMAND_SEARCH_QUERY_MAX_LENGTH = 2048
+
+type ListProps = {
+  repoCommands: TerminalQuickCommand[]
+  globalCommands: TerminalQuickCommand[]
+  totalCount: number
+  query: string
+  loading: boolean
+  disabled: boolean
+  canAdd: boolean
+  error: string | null
+  onQueryChange: (value: string) => void
+  onLaunch: (command: TerminalQuickCommand) => void
+  onEdit: (command: TerminalQuickCommand) => void
+  onDelete: (command: TerminalQuickCommand) => void
+  onAdd: () => void
+}
+
+export function QuickCommandsList({
+  repoCommands,
+  globalCommands,
+  totalCount,
+  query,
+  loading,
+  disabled,
+  canAdd,
+  error,
+  onQueryChange,
+  onLaunch,
+  onEdit,
+  onDelete,
+  onAdd
+}: ListProps) {
+  const hasVisible = repoCommands.length + globalCommands.length > 0
+  const addDisabled = disabled || !canAdd
+  // Why: keep an active filter clearable if a delete or paired desktop edit
+  // leaves only one command while the sheet is open.
+  const showSearch = totalCount > 1 || query.length > 0
+  return (
+    <View style={styles.listBody}>
+      {showSearch ? (
+        <View style={styles.search}>
+          <Search size={16} color={colors.textMuted} />
+          <TextInput
+            style={styles.searchInput}
+            value={query}
+            onChangeText={onQueryChange}
+            placeholder="Search quick commands..."
+            placeholderTextColor={colors.textMuted}
+            autoCapitalize="none"
+            autoCorrect={false}
+            // Why: bound pasted text before it reaches the per-keystroke JS
+            // search path; useful queries are far smaller than this budget.
+            maxLength={QUICK_COMMAND_SEARCH_QUERY_MAX_LENGTH}
+          />
+        </View>
+      ) : null}
+
+      {error ? <Text style={styles.error}>{error}</Text> : null}
+
+      {loading && !hasVisible ? (
+        <ActivityIndicator style={styles.loading} color={colors.textSecondary} />
+      ) : null}
+
+      {!loading && totalCount === 0 ? (
+        <Text style={styles.empty}>No quick commands yet.</Text>
+      ) : null}
+
+      {!loading && totalCount > 0 && !hasVisible ? (
+        <Text style={styles.empty}>No matching quick commands.</Text>
+      ) : null}
+
+      {repoCommands.length > 0 ? (
+        <QuickCommandGroup
+          label="This project"
+          commands={repoCommands}
+          onLaunch={onLaunch}
+          onEdit={onEdit}
+          onDelete={onDelete}
+          disabled={disabled}
+        />
+      ) : null}
+
+      {globalCommands.length > 0 ? (
+        <QuickCommandGroup
+          label="Global"
+          commands={globalCommands}
+          onLaunch={onLaunch}
+          onEdit={onEdit}
+          onDelete={onDelete}
+          disabled={disabled}
+        />
+      ) : null}
+
+      <Pressable
+        style={({ pressed }) => [
+          styles.addRow,
+          addDisabled && styles.disabled,
+          pressed && !addDisabled && styles.pressed
+        ]}
+        disabled={addDisabled}
+        onPress={onAdd}
+        accessibilityRole="button"
+      >
+        <Plus size={18} color={colors.textSecondary} />
+        <Text style={styles.addText}>
+          {canAdd ? 'New quick command' : 'Quick command limit reached'}
+        </Text>
+      </Pressable>
+    </View>
+  )
+}
+
+function QuickCommandGroup({
+  label,
+  commands,
+  onLaunch,
+  onEdit,
+  onDelete,
+  disabled
+}: {
+  label: string
+  commands: TerminalQuickCommand[]
+  onLaunch: (command: TerminalQuickCommand) => void
+  onEdit: (command: TerminalQuickCommand) => void
+  onDelete: (command: TerminalQuickCommand) => void
+  disabled: boolean
+}) {
+  return (
+    <View>
+      <Text style={styles.groupLabel}>{label}</Text>
+      <View style={styles.group}>
+        {commands.map((command, index) => (
+          <QuickCommandRow
+            key={command.id}
+            command={command}
+            first={index === 0}
+            onLaunch={onLaunch}
+            onEdit={onEdit}
+            onDelete={onDelete}
+            disabled={disabled}
+          />
+        ))}
+      </View>
+    </View>
+  )
+}
+
+function QuickCommandRow({
+  command,
+  first,
+  onLaunch,
+  onEdit,
+  onDelete,
+  disabled
+}: {
+  command: TerminalQuickCommand
+  first: boolean
+  onLaunch: (command: TerminalQuickCommand) => void
+  onEdit: (command: TerminalQuickCommand) => void
+  onDelete: (command: TerminalQuickCommand) => void
+  disabled: boolean
+}) {
+  const isAgent = isAgentQuickCommand(command)
+  return (
+    <View style={[styles.row, !first && styles.rowBorder, disabled && styles.disabled]}>
+      <Pressable
+        style={({ pressed }) => [styles.rowMain, pressed && !disabled && styles.pressed]}
+        disabled={disabled}
+        onPress={() => onLaunch(command)}
+        accessibilityRole="button"
+        accessibilityLabel={`Run ${command.label}`}
+      >
+        <View style={styles.rowIcon}>
+          {isAgent ? (
+            <MobileAgentIcon agentId={command.agent} size={16} />
+          ) : (
+            <Play size={14} color={colors.textPrimary} fill={colors.textPrimary} />
+          )}
+        </View>
+        <View style={styles.rowText}>
+          <Text style={styles.rowLabel} numberOfLines={1}>
+            {command.label}
+          </Text>
+          <Text style={[styles.rowPreview, !isAgent && styles.mono]} numberOfLines={1}>
+            {getQuickCommandDisplayPreview(command)}
+          </Text>
+        </View>
+      </Pressable>
+      <Pressable
+        style={({ pressed }) => [styles.rowAction, pressed && !disabled && styles.pressed]}
+        disabled={disabled}
+        onPress={() => onEdit(command)}
+        accessibilityLabel={`Edit ${command.label}`}
+      >
+        <Pencil size={15} color={colors.textSecondary} />
+      </Pressable>
+      <Pressable
+        style={({ pressed }) => [styles.rowAction, pressed && !disabled && styles.pressed]}
+        disabled={disabled}
+        onPress={() => onDelete(command)}
+        accessibilityLabel={`Delete ${command.label}`}
+      >
+        <Trash2 size={15} color={colors.statusRed} />
+      </Pressable>
+    </View>
+  )
+}
+
+export function QuickCommandAgentPicker({
+  selected,
+  onSelect
+}: {
+  selected: TuiAgent | null
+  onSelect: (agent: TuiAgent) => void
+}) {
+  return (
+    <View style={styles.group}>
+      {QUICK_COMMAND_SUPPORTED_AGENTS.map((agent, index) => (
+        <Pressable
+          key={agent.id}
+          style={({ pressed }) => [
+            styles.row,
+            index > 0 && styles.rowBorder,
+            pressed && styles.pressed
+          ]}
+          onPress={() => onSelect(agent.id)}
+          accessibilityRole="button"
+          accessibilityState={{ selected: selected === agent.id }}
+        >
+          <View style={styles.rowIcon}>
+            <MobileAgentIcon agentId={agent.id} size={16} />
+          </View>
+          <Text style={styles.agentLabel}>{agent.label}</Text>
+          {selected === agent.id ? <Check size={16} color={colors.textPrimary} /> : null}
+        </Pressable>
+      ))}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  pressed: { backgroundColor: colors.bgRaised },
+  disabled: { opacity: 0.45 },
+  listBody: { gap: spacing.sm, paddingBottom: spacing.sm },
+  search: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm,
+    backgroundColor: colors.bgPanel,
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm
+  },
+  searchInput: { flex: 1, color: colors.textPrimary, fontSize: 14, padding: 0 },
+  error: { color: colors.statusRed, fontSize: 13, paddingHorizontal: spacing.xs },
+  loading: { paddingVertical: spacing.lg },
+  empty: {
+    color: colors.textMuted,
+    fontSize: 14,
+    textAlign: 'center',
+    paddingVertical: spacing.lg
+  },
+  groupLabel: {
+    fontSize: 11,
+    fontWeight: '600',
+    color: colors.textMuted,
+    textTransform: 'uppercase',
+    letterSpacing: 0.6,
+    paddingHorizontal: spacing.xs,
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs
+  },
+  group: { backgroundColor: colors.bgPanel, borderRadius: 12, overflow: 'hidden' },
+  row: { flexDirection: 'row', alignItems: 'center' },
+  rowBorder: { borderTopWidth: StyleSheet.hairlineWidth, borderTopColor: colors.borderSubtle },
+  rowMain: {
+    flex: 1,
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.md,
+    paddingVertical: spacing.md,
+    paddingLeft: spacing.md,
+    minWidth: 0
+  },
+  rowIcon: {
+    width: 26,
+    height: 26,
+    borderRadius: 6,
+    backgroundColor: colors.bgRaised,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  rowText: { flex: 1, minWidth: 0 },
+  rowLabel: { fontSize: 14, fontWeight: '600', color: colors.textPrimary },
+  rowPreview: { fontSize: 12, color: colors.textSecondary, marginTop: 1 },
+  mono: { fontFamily: typography.monoFamily },
+  rowAction: { width: 40, height: 44, alignItems: 'center', justifyContent: 'center' },
+  agentLabel: { flex: 1, fontSize: 14, color: colors.textPrimary },
+  addRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm,
+    backgroundColor: colors.bgPanel,
+    borderRadius: 12,
+    borderWidth: 1,
+    borderStyle: 'dashed',
+    borderColor: colors.borderSubtle,
+    paddingVertical: spacing.md,
+    paddingHorizontal: spacing.md,
+    marginTop: spacing.xs
+  },
+  addText: { fontSize: 14, fontWeight: '600', color: colors.textPrimary }
+})
diff --git a/mobile/src/session/QuickCommandsSheet.test.ts b/mobile/src/session/QuickCommandsSheet.test.ts
new file mode 100644
index 00000000000..654882cd2ad
--- /dev/null
+++ b/mobile/src/session/QuickCommandsSheet.test.ts
@@ -0,0 +1,225 @@
+import { createElement, type ReactNode } from 'react'
+import { act, create, type ReactTestRenderer } from 'react-test-renderer'
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from 'vitest'
+import type { TerminalQuickCommand } from '../../../src/shared/types'
+import type { RpcClient } from '../transport/rpc-client'
+import { MAX_QUICK_COMMANDS } from '../terminal/quick-commands'
+import { QuickCommandsSheet } from './QuickCommandsSheet'
+
+const mocks = vi.hoisted(() => ({
+  alert: vi.fn(),
+  commands: [] as TerminalQuickCommand[],
+  persist: vi.fn()
+}))
+const quickCommandEditorForm = 'QuickCommandEditorForm'
+const quickCommandsList = 'QuickCommandsList'
+const command: TerminalQuickCommand = {
+  id: 'command',
+  label: 'Test',
+  action: 'terminal-command',
+  command: 'pnpm test',
+  appendEnter: true,
+  scope: { type: 'global' }
+}
+
+vi.mock('react-native', () => ({
+  Alert: { alert: mocks.alert },
+  Pressable: 'Pressable',
+  StyleSheet: { create: <T>(styles: T) => styles },
+  Text: 'Text',
+  View: 'View'
+}))
+
+vi.mock('lucide-react-native', () => ({ ChevronLeft: 'ChevronLeft' }))
+
+vi.mock('../components/BottomDrawer', () => ({
+  BottomDrawer: ({ children }: { children: ReactNode }) => children
+}))
+
+vi.mock('./QuickCommandEditorForm', () => ({
+  QuickCommandEditorForm: 'QuickCommandEditorForm'
+}))
+
+vi.mock('./QuickCommandsList', () => ({
+  QuickCommandAgentPicker: 'QuickCommandAgentPicker',
+  QuickCommandsList: 'QuickCommandsList'
+}))
+
+vi.mock('./use-quick-commands', () => ({
+  useQuickCommands: () => ({
+    commands: mocks.commands,
+    loading: false,
+    ready: true,
+    error: null,
+    persist: mocks.persist
+  })
+}))
+
+function deferred<T>() {
+  let resolve: (value: T) => void = () => {}
+  const promise = new Promise<T>((done) => {
+    resolve = done
+  })
+  return { promise, resolve }
+}
+
+describe('QuickCommandsSheet', () => {
+  let renderer: ReactTestRenderer | null = null
+  let consoleSpy: MockInstance
+
+  beforeEach(() => {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true
+    mocks.alert.mockReset()
+    mocks.commands = []
+    mocks.persist.mockReset()
+    const originalConsoleError = console.error
+    consoleSpy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+      if (typeof args[0] === 'string' && args[0].includes('react-test-renderer is deprecated')) {
+        return
+      }
+      originalConsoleError(...args)
+    })
+  })
+
+  afterEach(() => {
+    act(() => renderer?.unmount())
+    renderer = null
+    consoleSpy.mockRestore()
+  })
+
+  it('keeps the sheet open when a launch is rejected', async () => {
+    const onClose = vi.fn()
+    const onLaunch = vi.fn(() => false)
+    await act(async () => {
+      renderer = create(
+        createElement(QuickCommandsSheet, {
+          visible: true,
+          onClose,
+          client: {} as RpcClient,
+          repoId: 'repo-1',
+          repoName: 'Repo',
+          onLaunch
+        })
+      )
+    })
+
+    act(() => renderer!.root.findByType(quickCommandsList).props.onLaunch(command))
+
+    expect(onLaunch).toHaveBeenCalledWith(command)
+    expect(onClose).not.toHaveBeenCalled()
+  })
+
+  it('submits one full-list mutation for a same-frame double tap', async () => {
+    const save = deferred<boolean>()
+    mocks.persist.mockReturnValue(save.promise)
+    await act(async () => {
+      renderer = create(
+        createElement(QuickCommandsSheet, {
+          visible: true,
+          onClose: vi.fn(),
+          client: {} as RpcClient,
+          repoId: 'repo-1',
+          repoName: 'Repo',
+          onLaunch: () => true
+        })
+      )
+    })
+
+    act(() => renderer!.root.findByType(quickCommandsList).props.onAdd())
+    const editor = renderer!.root.findByType(quickCommandEditorForm)
+    act(() => {
+      editor.props.onChange({ label: 'Test' })
+      editor.props.onChange({ command: 'pnpm test' })
+    })
+    const readyEditor = renderer!.root.findByType(quickCommandEditorForm)
+    act(() => {
+      readyEditor.props.onSave()
+      readyEditor.props.onSave()
+    })
+
+    expect(mocks.persist).toHaveBeenCalledTimes(1)
+    await act(async () => {
+      save.resolve(true)
+      await save.promise
+    })
+  })
+
+  it('keeps creation closed when the host command limit is reached', async () => {
+    mocks.commands = Array.from({ length: MAX_QUICK_COMMANDS }, (_, index) => ({
+      ...command,
+      id: `command-${index}`
+    }))
+    await act(async () => {
+      renderer = create(
+        createElement(QuickCommandsSheet, {
+          visible: true,
+          onClose: vi.fn(),
+          client: {} as RpcClient,
+          repoId: 'repo-1',
+          repoName: 'Repo',
+          onLaunch: () => true
+        })
+      )
+    })
+
+    const list = renderer!.root.findByType(quickCommandsList)
+    expect(list.props.canAdd).toBe(false)
+    act(() => list.props.onAdd())
+    expect(renderer!.root.findAllByType(quickCommandEditorForm)).toHaveLength(0)
+  })
+
+  it('shows only global commands and defaults new commands to global without a repo', async () => {
+    const repoCommand: TerminalQuickCommand = {
+      ...command,
+      id: 'repo-command',
+      scope: { type: 'repo', repoId: 'repo-1' }
+    }
+    mocks.commands = [command, repoCommand]
+    await act(async () => {
+      renderer = create(
+        createElement(QuickCommandsSheet, {
+          visible: true,
+          onClose: vi.fn(),
+          client: {} as RpcClient,
+          repoId: null,
+          repoName: 'Folder workspace',
+          onLaunch: () => true
+        })
+      )
+    })
+
+    const list = renderer!.root.findByType(quickCommandsList)
+    expect(list.props.globalCommands).toEqual([command])
+    expect(list.props.repoCommands).toEqual([])
+    act(() => list.props.onAdd())
+    expect(renderer!.root.findByType(quickCommandEditorForm).props.draft.scope).toEqual({
+      type: 'global'
+    })
+  })
+
+  it('does not delete a shared command until the destructive action is confirmed', async () => {
+    await act(async () => {
+      renderer = create(
+        createElement(QuickCommandsSheet, {
+          visible: true,
+          onClose: vi.fn(),
+          client: {} as RpcClient,
+          repoId: 'repo-1',
+          repoName: 'Repo',
+          onLaunch: () => true
+        })
+      )
+    })
+
+    act(() => renderer!.root.findByType(quickCommandsList).props.onDelete(command))
+    expect(mocks.persist).not.toHaveBeenCalled()
+
+    const actions = mocks.alert.mock.calls[0]?.[2] as
+      | Array<{ style?: string; onPress?: () => void }>
+      | undefined
+    act(() => actions?.find((action) => action.style === 'destructive')?.onPress?.())
+
+    expect(mocks.persist).toHaveBeenCalledTimes(1)
+    expect(mocks.persist).toHaveBeenCalledWith({ type: 'delete', id: command.id })
+  })
+})
diff --git a/mobile/src/session/QuickCommandsSheet.tsx b/mobile/src/session/QuickCommandsSheet.tsx
new file mode 100644
index 00000000000..c4dbff9473d
--- /dev/null
+++ b/mobile/src/session/QuickCommandsSheet.tsx
@@ -0,0 +1,251 @@
+import { useMemo, useRef, useState } from 'react'
+import { Alert, View, Text, Pressable, StyleSheet } from 'react-native'
+import { ChevronLeft } from 'lucide-react-native'
+import { colors, spacing } from '../theme/mobile-theme'
+import { BottomDrawer } from '../components/BottomDrawer'
+import type { RpcClient } from '../transport/rpc-client'
+import type { TerminalQuickCommand } from '../../../src/shared/types'
+import {
+  getQuickCommandPreview,
+  MAX_QUICK_COMMANDS,
+  quickCommandMatchesRepo
+} from '../terminal/quick-commands'
+import { useQuickCommands } from './use-quick-commands'
+import { QuickCommandEditorForm } from './QuickCommandEditorForm'
+import { QuickCommandAgentPicker, QuickCommandsList } from './QuickCommandsList'
+import {
+  createEmptyQuickCommandDraft,
+  draftToQuickCommand,
+  quickCommandToDraft,
+  type QuickCommandDraft
+} from './quick-command-draft'
+
+type Props = {
+  visible: boolean
+  onClose: () => void
+  client: RpcClient | null
+  repoId: string | null
+  repoName: string | null
+  onLaunch: (command: TerminalQuickCommand) => boolean
+}
+
+type SheetView = 'list' | 'editor' | 'agent'
+
+export function QuickCommandsSheet({
+  visible,
+  onClose,
+  client,
+  repoId,
+  repoName,
+  onLaunch
+}: Props) {
+  const { commands, loading, ready, error, persist } = useQuickCommands({
+    client,
+    enabled: visible
+  })
+  const [view, setView] = useState<SheetView>('list')
+  const [query, setQuery] = useState('')
+  const [draft, setDraft] = useState<QuickCommandDraft | null>(null)
+  const [saving, setSaving] = useState(false)
+  const savingRef = useRef(false)
+
+  const [wasVisible, setWasVisible] = useState(visible)
+  if (visible !== wasVisible) {
+    setWasVisible(visible)
+    if (visible) {
+      setView('list')
+      setQuery('')
+      setDraft(null)
+    }
+  }
+
+  // Why: prompt bodies can total ~240 KB. Lowercase them once per settings
+  // update instead of allocating the same search text on every keystroke.
+  const searchableCommands = useMemo(() => {
+    return commands
+      .filter((command) => quickCommandMatchesRepo(command, repoId))
+      .map((command) => ({
+        command,
+        searchText: `${command.label} ${getQuickCommandPreview(command)}`.toLowerCase()
+      }))
+  }, [commands, repoId])
+
+  const visibleCommands = useMemo(() => {
+    const trimmed = query.trim().toLowerCase()
+    return searchableCommands
+      .filter((entry) => !trimmed || entry.searchText.includes(trimmed))
+      .map((entry) => entry.command)
+  }, [query, searchableCommands])
+
+  const repoCommands = visibleCommands.filter((command) => command.scope?.type === 'repo')
+  const globalCommands = visibleCommands.filter((command) => command.scope?.type !== 'repo')
+
+  const openEditor = (command?: TerminalQuickCommand) => {
+    // Why: the host rejects full-list updates above this cap; existing rows
+    // must remain editable/deletable when creation is no longer possible.
+    if (!command && commands.length >= MAX_QUICK_COMMANDS) {
+      return
+    }
+    setDraft(
+      command
+        ? quickCommandToDraft(command)
+        : createEmptyQuickCommandDraft(repoId ? { type: 'repo', repoId } : { type: 'global' })
+    )
+    setView('editor')
+  }
+
+  const handleLaunch = (command: TerminalQuickCommand) => {
+    if (onLaunch(command)) {
+      onClose()
+    }
+  }
+
+  const handleDelete = (command: TerminalQuickCommand) => {
+    // Why: quick commands sync with desktop, so an accidental one-tap delete
+    // removes shared data rather than only dismissing a local row.
+    Alert.alert(
+      `Delete "${command.label || 'Untitled'}"?`,
+      'This quick command will be removed from your saved list.',
+      [
+        { text: 'Cancel', style: 'cancel' },
+        {
+          text: 'Delete',
+          style: 'destructive',
+          onPress: () => {
+            void persist({ type: 'delete', id: command.id })
+          }
+        }
+      ]
+    )
+  }
+
+  const handleSave = async () => {
+    if (!draft || savingRef.current) {
+      return
+    }
+    const built = draftToQuickCommand(draft)
+    if (!built) {
+      return
+    }
+    // Why: state cannot lock out a second tap until React commits the disabled UI.
+    savingRef.current = true
+    setSaving(true)
+    try {
+      const ok = await persist({ type: 'upsert', command: built })
+      if (ok) {
+        setView('list')
+        setDraft(null)
+      }
+    } finally {
+      savingRef.current = false
+      setSaving(false)
+    }
+  }
+
+  const title =
+    view === 'editor'
+      ? draft?.id
+        ? 'Edit Quick Command'
+        : 'Add Quick Command'
+      : view === 'agent'
+        ? 'Choose Agent'
+        : 'Quick Commands'
+
+  return (
+    <BottomDrawer visible={visible} onClose={onClose}>
+      <View style={styles.header}>
+        {view === 'list' ? (
+          <View style={styles.backSpacer} />
+        ) : (
+          <Pressable
+            style={({ pressed }) => [styles.backButton, pressed && styles.pressed]}
+            onPress={() => setView(view === 'agent' ? 'editor' : 'list')}
+            accessibilityLabel="Back"
+          >
+            <ChevronLeft size={18} color={colors.textSecondary} />
+          </Pressable>
+        )}
+        <Text style={styles.title}>{title}</Text>
+        <View style={styles.backSpacer} />
+      </View>
+
+      {view === 'editor' && draft ? (
+        <View style={styles.editorDesc}>
+          <Text style={styles.descText}>
+            Save terminal commands or agent prompts for quick access.
+          </Text>
+        </View>
+      ) : null}
+
+      {view === 'list' ? (
+        <QuickCommandsList
+          repoCommands={repoCommands}
+          globalCommands={globalCommands}
+          totalCount={searchableCommands.length}
+          query={query}
+          loading={loading}
+          disabled={!ready}
+          canAdd={commands.length < MAX_QUICK_COMMANDS}
+          error={error}
+          onQueryChange={setQuery}
+          onLaunch={handleLaunch}
+          onEdit={openEditor}
+          onDelete={handleDelete}
+          onAdd={() => openEditor()}
+        />
+      ) : null}
+
+      {view === 'editor' && draft ? (
+        <QuickCommandEditorForm
+          draft={draft}
+          mode={draft.id ? 'edit' : 'add'}
+          saving={saving || !ready}
+          error={error}
+          repoId={repoId}
+          repoName={repoName}
+          onChange={(patch) =>
+            setDraft((current) => (current ? { ...current, ...patch } : current))
+          }
+          onOpenAgentPicker={() => setView('agent')}
+          onCancel={() => {
+            setView('list')
+            setDraft(null)
+          }}
+          onSave={() => void handleSave()}
+        />
+      ) : null}
+
+      {view === 'agent' && draft ? (
+        <QuickCommandAgentPicker
+          selected={draft.agent}
+          onSelect={(agent) => {
+            setDraft((current) => (current ? { ...current, agent } : current))
+            setView('editor')
+          }}
+        />
+      ) : null}
+    </BottomDrawer>
+  )
+}
+
+const styles = StyleSheet.create({
+  header: { flexDirection: 'row', alignItems: 'center', paddingBottom: spacing.sm },
+  backButton: {
+    width: 30,
+    height: 30,
+    borderRadius: 15,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  backSpacer: { width: 30 },
+  title: {
+    flex: 1,
+    fontSize: 16,
+    fontWeight: '700',
+    color: colors.textPrimary,
+    textAlign: 'center'
+  },
+  pressed: { backgroundColor: colors.bgRaised },
+  editorDesc: { paddingHorizontal: spacing.xs, paddingBottom: spacing.sm },
+  descText: { fontSize: 12, color: colors.textMuted }
+})
diff --git a/mobile/src/session/quick-command-draft.ts b/mobile/src/session/quick-command-draft.ts
new file mode 100644
index 00000000000..2afdcf74620
--- /dev/null
+++ b/mobile/src/session/quick-command-draft.ts
@@ -0,0 +1,116 @@
+import type {
+  TerminalQuickCommand,
+  TerminalQuickCommandAction,
+  TerminalQuickCommandScope,
+  TuiAgent
+} from '../../../src/shared/types'
+import {
+  isAgentQuickCommand,
+  MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH,
+  MAX_QUICK_COMMAND_LABEL_LENGTH,
+  MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH,
+  supportsTerminalAgentQuickCommand
+} from '../terminal/quick-commands'
+
+// A single mutable draft covering both quick-command actions. Both the command
+// text and the agent/prompt are kept while editing so toggling Action back and
+// forth doesn't discard what the user already typed (mirrors desktop's draft).
+export type QuickCommandDraft = {
+  id: string | null
+  label: string
+  action: TerminalQuickCommandAction
+  command: string
+  appendEnter: boolean
+  agent: TuiAgent | null
+  prompt: string
+  scope: TerminalQuickCommandScope
+}
+
+export function createEmptyQuickCommandDraft(scope: TerminalQuickCommandScope): QuickCommandDraft {
+  return {
+    id: null,
+    label: '',
+    action: 'terminal-command',
+    command: '',
+    appendEnter: true,
+    agent: null,
+    prompt: '',
+    scope
+  }
+}
+
+export function quickCommandToDraft(command: TerminalQuickCommand): QuickCommandDraft {
+  const scope: TerminalQuickCommandScope =
+    command.scope?.type === 'repo' && command.scope.repoId
+      ? { type: 'repo', repoId: command.scope.repoId }
+      : { type: 'global' }
+  if (isAgentQuickCommand(command)) {
+    return {
+      id: command.id,
+      label: command.label,
+      action: 'agent-prompt',
+      command: '',
+      appendEnter: true,
+      agent: command.agent,
+      prompt: command.prompt,
+      scope
+    }
+  }
+  return {
+    id: command.id,
+    label: command.label,
+    action: 'terminal-command',
+    command: command.command,
+    appendEnter: command.appendEnter !== false,
+    agent: null,
+    prompt: '',
+    scope
+  }
+}
+
+export function isQuickCommandDraftValid(draft: QuickCommandDraft): boolean {
+  if (!draft.label.trim()) {
+    return false
+  }
+  if (draft.action === 'agent-prompt') {
+    return Boolean(
+      draft.agent &&
+      supportsTerminalAgentQuickCommand(draft.agent) &&
+      draft.prompt.trim().length > 0
+    )
+  }
+  return draft.command.trim().length > 0
+}
+
+// Build the persisted command from a draft. Returns null when incomplete so the
+// caller can keep the editor open. The server re-normalizes, but we trim/cap
+// here so optimistic local state matches what will be saved.
+export function draftToQuickCommand(draft: QuickCommandDraft): TerminalQuickCommand | null {
+  if (!isQuickCommandDraftValid(draft)) {
+    return null
+  }
+  // Why: timestamps alone collide when desktop and mobile add commands in the
+  // same millisecond, which would turn an atomic upsert into an overwrite.
+  const id =
+    draft.id ??
+    `quick-command-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+  const label = draft.label.trim().slice(0, MAX_QUICK_COMMAND_LABEL_LENGTH)
+  if (draft.action === 'agent-prompt' && draft.agent) {
+    return {
+      id,
+      label,
+      action: 'agent-prompt',
+      agent: draft.agent,
+      prompt: draft.prompt.trimEnd().slice(0, MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH),
+      scope: draft.scope
+    }
+  }
+  return {
+    id,
+    label,
+    action: 'terminal-command',
+    command: draft.command.trimEnd().slice(0, MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH),
+    appendEnter: draft.appendEnter,
+    scope: draft.scope
+  }
+}
diff --git a/mobile/src/session/use-quick-commands.test.ts b/mobile/src/session/use-quick-commands.test.ts
new file mode 100644
index 00000000000..6ab43487475
--- /dev/null
+++ b/mobile/src/session/use-quick-commands.test.ts
@@ -0,0 +1,391 @@
+import { createElement } from 'react'
+import { act, create, type ReactTestRenderer } from 'react-test-renderer'
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from 'vitest'
+import type { TerminalQuickCommand } from '../../../src/shared/types'
+import type { RpcClient } from '../transport/rpc-client'
+import type { RpcResponse } from '../transport/types'
+import { useQuickCommands } from './use-quick-commands'
+
+const FIRST: TerminalQuickCommand = {
+  id: 'first',
+  label: 'First',
+  action: 'terminal-command',
+  command: 'echo first',
+  appendEnter: true,
+  scope: { type: 'global' }
+}
+const SECOND: TerminalQuickCommand = {
+  id: 'second',
+  label: 'Second',
+  action: 'terminal-command',
+  command: 'echo second',
+  appendEnter: true,
+  scope: { type: 'global' }
+}
+
+function success(commands: TerminalQuickCommand[]): RpcResponse {
+  return {
+    ok: true,
+    result: { terminalQuickCommands: commands }
+  } as RpcResponse
+}
+
+function failure(message: string): RpcResponse {
+  return {
+    ok: false,
+    error: { code: 'internal_error', message }
+  } as RpcResponse
+}
+
+function deferred<T>() {
+  let resolve: (value: T) => void = () => {}
+  const promise = new Promise<T>((done) => {
+    resolve = done
+  })
+  return { promise, resolve }
+}
+
+describe('useQuickCommands', () => {
+  let renderer: ReactTestRenderer | null = null
+  let state: ReturnType<typeof useQuickCommands> | null = null
+  let consoleSpy: MockInstance
+
+  beforeEach(() => {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true
+    const original = console.error
+    consoleSpy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+      if (typeof args[0] === 'string' && args[0].includes('react-test-renderer is deprecated')) {
+        return
+      }
+      original(...args)
+    })
+  })
+
+  afterEach(() => {
+    act(() => renderer?.unmount())
+    renderer = null
+    state = null
+    consoleSpy.mockRestore()
+  })
+
+  async function mount(client: RpcClient, enabled = true): Promise<void> {
+    function Harness(): null {
+      state = useQuickCommands({ client, enabled })
+      return null
+    }
+    await act(async () => {
+      renderer = create(createElement(Harness))
+      await Promise.resolve()
+    })
+  }
+
+  it('does not fetch settings while the sheet is closed', async () => {
+    const client = { sendRequest: vi.fn() } as unknown as RpcClient
+
+    await mount(client, false)
+
+    expect(client.sendRequest).not.toHaveBeenCalled()
+    expect(state?.ready).toBe(false)
+  })
+
+  it('keeps mutations disabled when the remote list could not be loaded', async () => {
+    const client = {
+      sendRequest: vi.fn().mockResolvedValue(failure('load failed'))
+    } as unknown as RpcClient
+    await mount(client)
+
+    await act(async () => {
+      const persisted = await state!.persist({ type: 'delete', id: FIRST.id })
+      expect(persisted).toBe(false)
+    })
+
+    expect(state?.ready).toBe(false)
+    expect(state?.error).toBe('load failed')
+    expect(client.sendRequest).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps mutations disabled when a successful load has a malformed list', async () => {
+    const client = {
+      sendRequest: vi.fn().mockResolvedValue({ ok: true, result: {} } as RpcResponse)
+    } as unknown as RpcClient
+    await mount(client)
+
+    await act(async () => {
+      const persisted = await state!.persist({ type: 'delete', id: FIRST.id })
+      expect(persisted).toBe(false)
+    })
+
+    expect(state?.ready).toBe(false)
+    expect(state?.error).toBe('Failed to load quick commands')
+    expect(client.sendRequest).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps a later queued mutation after an earlier mutation fails', async () => {
+    const firstUpdate = deferred<RpcResponse>()
+    const secondUpdate = deferred<RpcResponse>()
+    const updateParams: unknown[] = []
+    const client = {
+      sendRequest: vi.fn((method: string, params?: unknown) => {
+        if (method === 'settings.getTerminalQuickCommands') {
+          return Promise.resolve(success([FIRST, SECOND]))
+        }
+        updateParams.push(params)
+        return updateParams.length === 1 ? firstUpdate.promise : secondUpdate.promise
+      })
+    } as unknown as RpcClient
+    await mount(client)
+    expect(state?.commands).toEqual([FIRST, SECOND])
+
+    let firstPersist: Promise<boolean> = Promise.resolve(false)
+    let secondPersist: Promise<boolean> = Promise.resolve(false)
+    await act(async () => {
+      firstPersist = state!.persist({ type: 'delete', id: FIRST.id })
+      secondPersist = state!.persist({ type: 'delete', id: SECOND.id })
+      await Promise.resolve()
+    })
+
+    expect(state?.commands).toEqual([])
+    expect(updateParams).toHaveLength(1)
+    expect(updateParams[0]).toEqual({ mutation: { type: 'delete', id: FIRST.id } })
+
+    await act(async () => {
+      firstUpdate.resolve(failure('first failed'))
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+    expect(updateParams).toEqual([
+      { mutation: { type: 'delete', id: FIRST.id } },
+      { mutation: { type: 'delete', id: SECOND.id } }
+    ])
+    expect(state?.commands).toEqual([FIRST])
+
+    await act(async () => {
+      secondUpdate.resolve(success([FIRST]))
+      await Promise.all([firstPersist, secondPersist])
+    })
+    expect(await firstPersist).toBe(false)
+    expect(await secondPersist).toBe(true)
+    expect(state?.commands).toEqual([FIRST])
+    expect(state?.error).toBeNull()
+  })
+
+  it('adopts the latest server-normalized list between queued mutations', async () => {
+    const normalizedFirst = { ...FIRST, label: 'Server normalized' }
+    const firstUpdate = deferred<RpcResponse>()
+    const secondUpdate = deferred<RpcResponse>()
+    const updateParams: unknown[] = []
+    const client = {
+      sendRequest: vi.fn((method: string, params?: unknown) => {
+        if (method === 'settings.getTerminalQuickCommands') {
+          return Promise.resolve(success([FIRST, SECOND]))
+        }
+        updateParams.push(params)
+        return updateParams.length === 1 ? firstUpdate.promise : secondUpdate.promise
+      })
+    } as unknown as RpcClient
+    await mount(client)
+
+    let firstPersist: Promise<boolean> = Promise.resolve(false)
+    let secondPersist: Promise<boolean> = Promise.resolve(false)
+    await act(async () => {
+      firstPersist = state!.persist({
+        type: 'upsert',
+        command: { ...FIRST, label: 'Local label' }
+      })
+      secondPersist = state!.persist({ type: 'delete', id: SECOND.id })
+      await Promise.resolve()
+    })
+
+    expect(updateParams[0]).toEqual({
+      mutation: { type: 'upsert', command: { ...FIRST, label: 'Local label' } }
+    })
+    await act(async () => {
+      firstUpdate.resolve(success([normalizedFirst, SECOND]))
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+    expect(updateParams[1]).toEqual({ mutation: { type: 'delete', id: SECOND.id } })
+
+    await act(async () => {
+      secondUpdate.resolve(success([normalizedFirst]))
+      await Promise.all([firstPersist, secondPersist])
+    })
+    expect(state?.commands).toEqual([normalizedFirst])
+  })
+
+  it('preserves unrelated commands added by another client while the sheet is open', async () => {
+    const edited = { ...FIRST, label: 'Edited on mobile' }
+    const client = {
+      sendRequest: vi
+        .fn()
+        .mockResolvedValueOnce(success([FIRST]))
+        // The host applies the targeted upsert to a list that desktop changed.
+        .mockResolvedValueOnce(success([edited, SECOND]))
+    } as unknown as RpcClient
+    await mount(client)
+
+    await act(async () => {
+      await state!.persist({ type: 'upsert', command: edited })
+    })
+
+    expect(client.sendRequest).toHaveBeenLastCalledWith('settings.updateTerminalQuickCommands', {
+      mutation: { type: 'upsert', command: edited }
+    })
+    expect(state?.commands).toEqual([edited, SECOND])
+  })
+
+  it('isolates an old client mutation from a replacement client', async () => {
+    const oldUpdate = deferred<RpcResponse>()
+    const oldClient = {
+      sendRequest: vi
+        .fn()
+        .mockResolvedValueOnce(success([FIRST]))
+        .mockReturnValueOnce(oldUpdate.promise)
+    } as unknown as RpcClient
+    const newClient = {
+      sendRequest: vi.fn().mockResolvedValue(success([SECOND]))
+    } as unknown as RpcClient
+
+    function Harness({ client }: { client: RpcClient }): null {
+      state = useQuickCommands({ client, enabled: true })
+      return null
+    }
+    await act(async () => {
+      renderer = create(createElement(Harness, { client: oldClient }))
+      await Promise.resolve()
+    })
+    let persisted: Promise<boolean> = Promise.resolve(false)
+    await act(async () => {
+      persisted = state!.persist({ type: 'delete', id: FIRST.id })
+      await Promise.resolve()
+      renderer!.update(createElement(Harness, { client: newClient }))
+      await Promise.resolve()
+    })
+
+    expect(newClient.sendRequest).toHaveBeenCalledWith('settings.getTerminalQuickCommands')
+    expect(state?.commands).toEqual([SECOND])
+
+    await act(async () => {
+      oldUpdate.resolve(success([]))
+      await persisted
+    })
+    expect(state?.commands).toEqual([SECOND])
+  })
+
+  it('rolls back the latest optimistic mutation when persistence fails', async () => {
+    const client = {
+      sendRequest: vi
+        .fn()
+        .mockResolvedValueOnce(success([FIRST]))
+        .mockResolvedValueOnce(failure('save failed'))
+    } as unknown as RpcClient
+    await mount(client)
+
+    await act(async () => {
+      await state!.persist({ type: 'delete', id: FIRST.id })
+    })
+
+    expect(state?.commands).toEqual([FIRST])
+    expect(state?.error).toBe('save failed')
+  })
+
+  it('rolls back when a successful update has a malformed authoritative list', async () => {
+    const client = {
+      sendRequest: vi
+        .fn()
+        .mockResolvedValueOnce(success([FIRST]))
+        .mockResolvedValueOnce({ ok: true, result: {} } as RpcResponse)
+    } as unknown as RpcClient
+    await mount(client)
+
+    let persisted = true
+    await act(async () => {
+      persisted = await state!.persist({ type: 'delete', id: FIRST.id })
+    })
+
+    expect(persisted).toBe(false)
+    expect(state?.commands).toEqual([FIRST])
+    expect(state?.error).toBe('Failed to save quick command')
+  })
+
+  it('waits for an in-flight save before reloading after reopen', async () => {
+    const update = deferred<RpcResponse>()
+    let loadCount = 0
+    const client = {
+      sendRequest: vi.fn((method: string) => {
+        if (method === 'settings.updateTerminalQuickCommands') {
+          return update.promise
+        }
+        loadCount += 1
+        return Promise.resolve(success(loadCount === 1 ? [FIRST] : []))
+      })
+    } as unknown as RpcClient
+
+    function Harness({ enabled }: { enabled: boolean }): null {
+      state = useQuickCommands({ client, enabled })
+      return null
+    }
+    await act(async () => {
+      renderer = create(createElement(Harness, { enabled: true }))
+      await Promise.resolve()
+    })
+
+    let persisted: Promise<boolean> = Promise.resolve(false)
+    await act(async () => {
+      persisted = state!.persist({ type: 'delete', id: FIRST.id })
+      await Promise.resolve()
+    })
+    await act(async () => {
+      renderer!.update(createElement(Harness, { enabled: false }))
+      await Promise.resolve()
+    })
+    await act(async () => {
+      renderer!.update(createElement(Harness, { enabled: true }))
+      await Promise.resolve()
+    })
+    expect(loadCount).toBe(1)
+
+    await act(async () => {
+      update.resolve(success([]))
+      await persisted
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+
+    expect(loadCount).toBe(2)
+    expect(state?.commands).toEqual([])
+    expect(state?.ready).toBe(true)
+  })
+
+  it('rolls back to the confirmed list when consecutive queued mutations fail', async () => {
+    const firstUpdate = deferred<RpcResponse>()
+    const secondUpdate = deferred<RpcResponse>()
+    const client = {
+      sendRequest: vi
+        .fn()
+        .mockResolvedValueOnce(success([FIRST, SECOND]))
+        .mockReturnValueOnce(firstUpdate.promise)
+        .mockReturnValueOnce(secondUpdate.promise)
+    } as unknown as RpcClient
+    await mount(client)
+
+    let firstPersist: Promise<boolean> = Promise.resolve(false)
+    let secondPersist: Promise<boolean> = Promise.resolve(false)
+    await act(async () => {
+      firstPersist = state!.persist({ type: 'delete', id: FIRST.id })
+      secondPersist = state!.persist({ type: 'delete', id: SECOND.id })
+      await Promise.resolve()
+    })
+
+    await act(async () => {
+      firstUpdate.resolve(failure('first failed'))
+      await Promise.resolve()
+      await Promise.resolve()
+      secondUpdate.resolve(failure('second failed'))
+      await Promise.all([firstPersist, secondPersist])
+    })
+
+    expect(state?.commands).toEqual([FIRST, SECOND])
+    expect(state?.error).toBe('second failed')
+  })
+})
diff --git a/mobile/src/session/use-quick-commands.ts b/mobile/src/session/use-quick-commands.ts
new file mode 100644
index 00000000000..5ce5a994cd0
--- /dev/null
+++ b/mobile/src/session/use-quick-commands.ts
@@ -0,0 +1,212 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { RpcClient } from '../transport/rpc-client'
+import type { RpcFailure, RpcSuccess } from '../transport/types'
+import type { TerminalQuickCommand } from '../../../src/shared/types'
+import {
+  applyTerminalQuickCommandMutation,
+  parseNormalizedTerminalQuickCommands,
+  type TerminalQuickCommandMutation
+} from '../terminal/quick-commands'
+
+type Args = {
+  client: RpcClient | null
+  // Fetch only while the sheet is open — quick commands are settings data we
+  // don't need to keep hydrated for every session screen.
+  enabled: boolean
+}
+
+type QuickCommandsState = {
+  commands: TerminalQuickCommand[]
+  loading: boolean
+  ready: boolean
+  error: string | null
+  // Optimistically apply against the latest local list, then serialize writes.
+  // The server re-normalizes and returns the canonical list, which we adopt.
+  persist: (mutation: TerminalQuickCommandMutation) => Promise<boolean>
+}
+
+type PendingMutation = {
+  id: number
+  mutation: TerminalQuickCommandMutation
+}
+
+type MutationContext = {
+  client: RpcClient
+  confirmed: TerminalQuickCommand[]
+  pending: PendingMutation[]
+  queue: Promise<void>
+  nextMutationId: number
+}
+
+function readQuickCommands(result: unknown): TerminalQuickCommand[] | null {
+  const list = (result as { terminalQuickCommands?: unknown } | null)?.terminalQuickCommands
+  return parseNormalizedTerminalQuickCommands(list)
+}
+
+export function useQuickCommands({ client, enabled }: Args): QuickCommandsState {
+  const [commands, setCommands] = useState<TerminalQuickCommand[]>([])
+  const [loading, setLoading] = useState(false)
+  const [ready, setReady] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const commandsRef = useRef<TerminalQuickCommand[]>([])
+  const operationIdRef = useRef(0)
+  const mutationContextRef = useRef<MutationContext | null>(null)
+
+  useEffect(() => {
+    if (!enabled || !client) {
+      setReady(false)
+      return
+    }
+    let mutationContext = mutationContextRef.current
+    if (mutationContext?.client !== client) {
+      // A request for an old host must not delay or update mutations on a new one.
+      mutationContext = {
+        client,
+        confirmed: [],
+        pending: [],
+        queue: Promise.resolve(),
+        nextMutationId: 0
+      }
+      mutationContextRef.current = mutationContext
+      commandsRef.current = []
+      setCommands([])
+    }
+    let stale = false
+    const operationId = operationIdRef.current + 1
+    operationIdRef.current = operationId
+    setLoading(true)
+    setReady(false)
+    setError(null)
+
+    void (async () => {
+      try {
+        // A close/reopen can overlap an in-flight save. Read only after that
+        // save settles so an older snapshot cannot replace its canonical result.
+        await mutationContext.queue
+        if (
+          stale ||
+          operationId !== operationIdRef.current ||
+          mutationContextRef.current !== mutationContext
+        ) {
+          return
+        }
+        const response = await client.sendRequest('settings.getTerminalQuickCommands')
+        if (
+          stale ||
+          operationId !== operationIdRef.current ||
+          mutationContextRef.current !== mutationContext
+        ) {
+          return
+        }
+        if (!response.ok) {
+          setError((response as RpcFailure).error.message || 'Failed to load quick commands')
+          return
+        }
+        const next = readQuickCommands((response as RpcSuccess).result)
+        if (!next) {
+          setError('Failed to load quick commands')
+          return
+        }
+        mutationContext.confirmed = next
+        commandsRef.current = next
+        setCommands(next)
+        setReady(true)
+      } catch (err) {
+        if (
+          !stale &&
+          operationId === operationIdRef.current &&
+          mutationContextRef.current === mutationContext
+        ) {
+          setError(err instanceof Error ? err.message : 'Failed to load quick commands')
+        }
+      } finally {
+        if (
+          !stale &&
+          operationId === operationIdRef.current &&
+          mutationContextRef.current === mutationContext
+        ) {
+          setLoading(false)
+        }
+      }
+    })()
+
+    return () => {
+      stale = true
+    }
+  }, [client, enabled])
+
+  const persist = useCallback(
+    async (commandMutation: TerminalQuickCommandMutation) => {
+      // Why: the loaded list is the optimistic/rollback baseline; mutating
+      // before it arrives would make failure recovery show invented state.
+      const mutationContext = mutationContextRef.current
+      if (!client || loading || !ready || mutationContext?.client !== client) {
+        return false
+      }
+      const mutation: PendingMutation = {
+        id: mutationContext.nextMutationId + 1,
+        mutation: commandMutation
+      }
+      mutationContext.nextMutationId = mutation.id
+      mutationContext.pending.push(mutation)
+      const optimistic = applyTerminalQuickCommandMutation(commandsRef.current, commandMutation)
+      commandsRef.current = optimistic
+      setCommands(optimistic)
+      setError(null)
+
+      const send = async (): Promise<boolean> => {
+        let succeeded = false
+        let failureMessage: string | null = null
+        try {
+          const response = await client.sendRequest('settings.updateTerminalQuickCommands', {
+            mutation: commandMutation
+          })
+          if (!response.ok) {
+            throw new Error(
+              (response as RpcFailure).error.message || 'Failed to save quick command'
+            )
+          }
+          const confirmed = readQuickCommands((response as RpcSuccess).result)
+          if (!confirmed) {
+            // Why: treating an invalid success payload as [] would let the next
+            // full-list mutation erase commands that still exist on the host.
+            throw new Error('Failed to save quick command')
+          }
+          mutationContext.confirmed = confirmed
+          succeeded = true
+          return true
+        } catch (err) {
+          failureMessage = err instanceof Error ? err.message : 'Failed to save quick command'
+          return false
+        } finally {
+          mutationContext.pending = mutationContext.pending.filter(
+            (pending) => pending.id !== mutation.id
+          )
+          if (mutationContextRef.current === mutationContext) {
+            const next = mutationContext.pending.reduce(
+              (current, pending) => applyTerminalQuickCommandMutation(current, pending.mutation),
+              mutationContext.confirmed
+            )
+            commandsRef.current = next
+            setCommands(next)
+            const hasNewerMutation = mutationContext.pending.some(
+              (pending) => pending.id > mutation.id
+            )
+            if (!hasNewerMutation) {
+              setError(succeeded ? null : failureMessage)
+            }
+          }
+        }
+      }
+      const request = mutationContext.queue.then(send, send)
+      mutationContext.queue = request.then(
+        () => undefined,
+        () => undefined
+      )
+      return await request
+    },
+    [client, loading, ready]
+  )
+
+  return { commands, loading, ready, error, persist }
+}
diff --git a/mobile/src/terminal/quick-commands.test.ts b/mobile/src/terminal/quick-commands.test.ts
new file mode 100644
index 00000000000..964fbc9b4d2
--- /dev/null
+++ b/mobile/src/terminal/quick-commands.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import type { TerminalQuickCommand } from '../../../src/shared/types'
+import {
+  buildMobileQuickCommandLaunch,
+  getQuickCommandDisplayPreview,
+  getQuickCommandPreview,
+  supportsMobileQuickCommands
+} from './quick-commands'
+
+function command(overrides: Partial<TerminalQuickCommand> = {}): TerminalQuickCommand {
+  return {
+    id: 'command',
+    label: 'Command',
+    action: 'terminal-command',
+    command: 'pnpm test',
+    appendEnter: true,
+    scope: { type: 'global' },
+    ...overrides
+  } as TerminalQuickCommand
+}
+
+describe('mobile quick-command launch', () => {
+  it('only exposes quick commands when the host advertises the complete contract', () => {
+    expect(supportsMobileQuickCommands(undefined)).toBe(false)
+    expect(supportsMobileQuickCommands([])).toBe(false)
+    expect(supportsMobileQuickCommands(['terminal.binary-stream.v1'])).toBe(false)
+    expect(supportsMobileQuickCommands(['terminal.quick-commands.v1'])).toBe(true)
+  })
+
+  it('joins multiline runnable commands with "; " to match desktop', () => {
+    // Parity with desktop flattenTerminalQuickCommand: the same saved command
+    // must run identically on desktop and mobile.
+    expect(
+      buildMobileQuickCommandLaunch(command({ command: 'cd app\nnpm install\nnpm test' }))
+    ).toEqual({
+      options: {
+        startupCommand: 'cd app; npm install; npm test',
+        startupCommandDelivery: 'shell-ready'
+      }
+    })
+  })
+
+  it('forces shell-ready delivery for commands that resemble bare agent launches', () => {
+    expect(buildMobileQuickCommandLaunch(command({ command: 'codex exec --full-auto' }))).toEqual({
+      options: {
+        startupCommand: 'codex exec --full-auto',
+        startupCommandDelivery: 'shell-ready'
+      }
+    })
+  })
+
+  it('keeps append-enter-off commands as unsubmitted terminal input', () => {
+    const multiline = 'printf "first\\nsecond"\n# leave this unsubmitted'
+    expect(
+      buildMobileQuickCommandLaunch(command({ command: multiline, appendEnter: false }))
+    ).toEqual({
+      options: { initialPrompt: multiline, enter: false, successToast: 'Command inserted' }
+    })
+  })
+
+  it('injects supported agent prompts into the host-built launch command', () => {
+    expect(
+      buildMobileQuickCommandLaunch(
+        command({
+          action: 'agent-prompt',
+          agent: 'codex',
+          prompt: 'Review this diff'
+        })
+      )
+    ).toEqual({ agent: 'codex', options: { agentPrompt: 'Review this diff' } })
+  })
+
+  it('bounds native row text without truncating searchable or executable content', () => {
+    const longPrompt = `Review ${'x'.repeat(5993)}`
+    const agentCommand = command({
+      action: 'agent-prompt',
+      agent: 'codex',
+      prompt: longPrompt
+    })
+
+    expect(getQuickCommandDisplayPreview(agentCommand)).toHaveLength(240)
+    expect(getQuickCommandDisplayPreview(agentCommand)).toMatch(/^Codex: Review .*…$/)
+    expect(getQuickCommandPreview(agentCommand)).toBe(`Codex: ${longPrompt}`)
+    expect(buildMobileQuickCommandLaunch(agentCommand)).toEqual({
+      agent: 'codex',
+      options: { agentPrompt: longPrompt }
+    })
+  })
+})
diff --git a/mobile/src/terminal/quick-commands.ts b/mobile/src/terminal/quick-commands.ts
new file mode 100644
index 00000000000..40f92a55439
--- /dev/null
+++ b/mobile/src/terminal/quick-commands.ts
@@ -0,0 +1,105 @@
+import type { TerminalQuickCommand, TuiAgent } from '../../../src/shared/types'
+import {
+  applyTerminalQuickCommandMutation,
+  flattenTerminalQuickCommand,
+  isTerminalAgentQuickCommand,
+  MAX_QUICK_COMMANDS,
+  MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH,
+  MAX_QUICK_COMMAND_LABEL_LENGTH,
+  MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH,
+  parseNormalizedTerminalQuickCommands,
+  supportsTerminalAgentQuickCommand,
+  terminalQuickCommandMatchesRepo,
+  type TerminalQuickCommandMutation
+} from '../../../src/shared/terminal-quick-commands'
+import { TERMINAL_QUICK_COMMANDS_RUNTIME_CAPABILITY } from '../../../src/shared/protocol-version'
+import { MOBILE_TUI_AGENT_LABELS } from '../tasks/mobile-tui-agents'
+
+// Reuse the canonical desktop quick-command logic (pure, no heavy deps) so
+// mobile behaves identically to desktop. Only genuinely mobile-specific pieces
+// — agent-branded labels, native row truncation, and the launch plan — live here.
+export {
+  isTerminalAgentQuickCommand as isAgentQuickCommand,
+  terminalQuickCommandMatchesRepo as quickCommandMatchesRepo,
+  supportsTerminalAgentQuickCommand,
+  MAX_QUICK_COMMANDS,
+  MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH,
+  MAX_QUICK_COMMAND_LABEL_LENGTH,
+  MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH,
+  parseNormalizedTerminalQuickCommands,
+  applyTerminalQuickCommandMutation,
+  type TerminalQuickCommandMutation
+}
+
+const MAX_QUICK_COMMAND_DISPLAY_PREVIEW_LENGTH = 240
+
+export function supportsMobileQuickCommands(capabilities: readonly string[] | undefined): boolean {
+  return capabilities?.includes(TERMINAL_QUICK_COMMANDS_RUNTIME_CAPABILITY) === true
+}
+
+export type MobileQuickCommandLaunch = {
+  agent?: TuiAgent
+  options: {
+    agentPrompt?: string
+    startupCommand?: string
+    startupCommandDelivery?: 'shell-ready'
+    initialPrompt?: string
+    enter?: boolean
+    successToast?: string
+  }
+}
+
+export function buildMobileQuickCommandLaunch(
+  command: TerminalQuickCommand
+): MobileQuickCommandLaunch | null {
+  if (isTerminalAgentQuickCommand(command)) {
+    if (!command.prompt.trim() || !supportsTerminalAgentQuickCommand(command.agent)) {
+      return null
+    }
+    return { agent: command.agent, options: { agentPrompt: command.prompt } }
+  }
+  if (!command.command.trim()) {
+    return null
+  }
+  return command.appendEnter === false
+    ? {
+        options: {
+          initialPrompt: command.command,
+          enter: false,
+          successToast: `${command.label.trim() || 'Quick command'} inserted`
+        }
+      }
+    : {
+        // Why: raw commands that resemble bare agent launches can otherwise
+        // select the fast path and race slow native, WSL, or SSH shell startup.
+        // flattenTerminalQuickCommand joins multiline bodies exactly as desktop
+        // does so the same saved command runs identically on both.
+        options: {
+          startupCommand: flattenTerminalQuickCommand(command).command,
+          startupCommandDelivery: 'shell-ready'
+        }
+      }
+}
+
+export function getQuickCommandAgentLabel(agent: TuiAgent): string {
+  return MOBILE_TUI_AGENT_LABELS[agent] ?? agent
+}
+
+// The subtitle desktop shows under each quick command: agent prompts read
+// "Codex: <prompt>", terminal commands show the raw command text.
+export function getQuickCommandPreview(command: TerminalQuickCommand): string {
+  if (isTerminalAgentQuickCommand(command)) {
+    return `${getQuickCommandAgentLabel(command.agent)}: ${command.prompt}`
+  }
+  return command.command
+}
+
+export function getQuickCommandDisplayPreview(command: TerminalQuickCommand): string {
+  const preview = getQuickCommandPreview(command)
+  if (preview.length <= MAX_QUICK_COMMAND_DISPLAY_PREVIEW_LENGTH) {
+    return preview
+  }
+  // Why: one-line rows should not send up to 6 KB each through native text
+  // layout; full command bodies remain available to search, edit, and launch.
+  return `${preview.slice(0, MAX_QUICK_COMMAND_DISPLAY_PREVIEW_LENGTH - 1)}…`
+}
diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index a3f6e0b2cc0..5c9c8ae0953 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -66,6 +66,7 @@ import {
   TERMINAL_INPUT_MAX_BYTES,
   TERMINAL_INPUT_TOO_LARGE_ERROR
 } from '../../shared/terminal-input'
+import { MAX_QUICK_COMMANDS } from '../../shared/terminal-quick-commands'
 import {
   AGENT_PROMPT_BRACKETED_PASTE_END,
   AGENT_PROMPT_BRACKETED_PASTE_START,
@@ -1500,6 +1501,16 @@ describe('OrcaRuntimeService.dedupeWorktreeCreate', () => {
 
 describe('OrcaRuntimeService', () => {
   it('projects runtime-backed settings to paired clients', () => {
+    const terminalQuickCommands = [
+      {
+        id: 'review',
+        label: 'Review',
+        action: 'agent-prompt' as const,
+        agent: 'codex' as const,
+        prompt: 'Review this diff',
+        scope: { type: 'global' as const }
+      }
+    ]
     const runtime = new OrcaRuntimeService({
       ...store,
       getSettings: () => ({
@@ -1507,7 +1518,8 @@ describe('OrcaRuntimeService', () => {
         experimentalNewWorktreeCardStyle: true,
         compactWorktreeCards: true,
         minimaxGroupId: 'group-42',
-        minimaxUsageModels: 'general,abab6.5'
+        minimaxUsageModels: 'general,abab6.5',
+        terminalQuickCommands
       })
     } as never)
 
@@ -1517,6 +1529,76 @@ describe('OrcaRuntimeService', () => {
       minimaxGroupId: 'group-42',
       minimaxUsageModels: 'general,abab6.5'
     })
+    expect(runtime.getClientSettings()).not.toHaveProperty('terminalQuickCommands')
+    expect(runtime.getClientTerminalQuickCommands()).toEqual(terminalQuickCommands)
+  })
+
+  it('updates quick commands without widening general paired settings payloads', () => {
+    const existing = {
+      id: 'review',
+      label: 'Review',
+      action: 'terminal-command' as const,
+      command: 'pnpm review',
+      appendEnter: true,
+      scope: { type: 'global' as const }
+    }
+    let settings = { ...store.getSettings(), terminalQuickCommands: [existing] }
+    const updateSettings = vi.fn((updates: Partial<typeof settings>) => {
+      settings = { ...settings, ...updates }
+    })
+    const runtime = new OrcaRuntimeService({
+      ...store,
+      getSettings: () => settings,
+      updateSettings
+    } as never)
+    const command = {
+      id: 'status',
+      label: 'Status',
+      action: 'terminal-command' as const,
+      command: 'git status',
+      appendEnter: true,
+      scope: { type: 'global' as const }
+    }
+    const commands = [existing, command]
+
+    expect(runtime.updateClientTerminalQuickCommands({ type: 'upsert', command })).toEqual(commands)
+    expect(updateSettings).toHaveBeenCalledWith(
+      { terminalQuickCommands: commands },
+      { notifyListeners: true }
+    )
+    expect(runtime.getClientSettings()).not.toHaveProperty('terminalQuickCommands')
+  })
+
+  it('rejects a concurrent add after the quick command limit is reached', () => {
+    const terminalQuickCommands = Array.from({ length: MAX_QUICK_COMMANDS }, (_, index) => ({
+      id: `command-${index}`,
+      label: `Command ${index}`,
+      action: 'terminal-command' as const,
+      command: 'true',
+      appendEnter: true,
+      scope: { type: 'global' as const }
+    }))
+    const updateSettings = vi.fn()
+    const runtime = new OrcaRuntimeService({
+      ...store,
+      getSettings: () => ({ ...store.getSettings(), terminalQuickCommands }),
+      updateSettings
+    } as never)
+
+    expect(() =>
+      runtime.updateClientTerminalQuickCommands({
+        type: 'upsert',
+        command: {
+          id: 'one-too-many',
+          label: 'One too many',
+          action: 'terminal-command',
+          command: 'true',
+          appendEnter: true,
+          scope: { type: 'global' }
+        }
+      })
+    ).toThrow('Quick command limit reached')
+    expect(updateSettings).not.toHaveBeenCalled()
   })
 
   it('accepts runtime-backed setting updates from paired clients', () => {
@@ -1610,6 +1692,7 @@ describe('OrcaRuntimeService', () => {
     expect(status.capabilities).toContain('terminal.binary-stream.v1')
     expect(status.capabilities).toContain('workspace-ports.v1')
     expect(status.capabilities).toContain('mobile.tasks.v1')
+    expect(status.capabilities).toContain('terminal.quick-commands.v1')
     expect(status.capabilities).toContain('worktree.create-idempotency.v1')
     expect(status.capabilities).toContain('project-host-setup.v1')
     expect(status.capabilities).toContain('linear.issue-attribute-filter.v1')
@@ -21765,6 +21848,66 @@ describe('OrcaRuntimeService', () => {
     )
   })
 
+  it('injects mobile quick-command prompts into the host-built agent startup command', async () => {
+    const spawn = vi.fn().mockResolvedValue({ id: 'pty-agent-prompt' })
+    const runtime = new OrcaRuntimeService({
+      ...store,
+      getSettings: () => ({
+        ...store.getSettings(),
+        disabledTuiAgents: [],
+        agentCmdOverrides: { codex: 'codex' },
+        agentDefaultArgs: {}
+      })
+    } as never)
+    runtime.setPtyController({
+      spawn,
+      write: () => true,
+      kill: () => true,
+      getForegroundProcess: async () => null
+    })
+    runtime.syncWindowGraph(0, { tabs: [], leaves: [] })
+
+    await runtime.createMobileSessionTerminal(`id:${TEST_WORKTREE_ID}`, {
+      agent: 'codex',
+      agentPrompt: 'Review this diff'
+    })
+
+    expect(spawn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        command: expect.stringMatching(/^codex .*'Review this diff'$/),
+        launchAgent: 'codex',
+        cwd: TEST_WORKTREE_PATH
+      })
+    )
+  })
+
+  it('rejects startup prompts for agents that require post-ready stdin', async () => {
+    const spawn = vi.fn().mockResolvedValue({ id: 'pty-agent-prompt' })
+    const runtime = new OrcaRuntimeService({
+      ...store,
+      getSettings: () => ({
+        ...store.getSettings(),
+        disabledTuiAgents: [],
+        agentCmdOverrides: {}
+      })
+    } as never)
+    runtime.setPtyController({
+      spawn,
+      write: () => true,
+      kill: () => true,
+      getForegroundProcess: async () => null
+    })
+    runtime.syncWindowGraph(0, { tabs: [], leaves: [] })
+
+    await expect(
+      runtime.createMobileSessionTerminal(`id:${TEST_WORKTREE_ID}`, {
+        agent: 'aider',
+        agentPrompt: 'Review this diff'
+      })
+    ).rejects.toThrow('does not support startup prompt quick commands')
+    expect(spawn).not.toHaveBeenCalled()
+  })
+
   it('uses POSIX quoting for mobile agent launch commands in WSL project runtimes', async () => {
     await withPlatform('win32', async () => {
       const spawn = vi.fn().mockResolvedValue({ id: 'pty-agent' })
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index b5e2f0df995..988e5dc21c9 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -135,6 +135,7 @@ import type {
   MemorySnapshot,
   Tab,
   TabGroupLayoutNode,
+  TerminalQuickCommand,
   TerminalLayoutSnapshot,
   TerminalPaneLayoutNode,
   TerminalTab,
@@ -212,6 +213,11 @@ 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, isValidTerminalTabId } from '../../shared/terminal-tab-id'
+import {
+  applyTerminalQuickCommandMutation,
+  MAX_QUICK_COMMANDS,
+  type TerminalQuickCommandMutation
+} from '../../shared/terminal-quick-commands'
 import { buildAgentDraftLaunchPlan, buildAgentStartupPlan } from '../../shared/tui-agent-startup'
 import { repoIsRemote } from '../../shared/agent-launch-remote'
 import {
@@ -895,6 +901,7 @@ type RuntimeStore = {
     minimaxGroupId?: GlobalSettings['minimaxGroupId']
     minimaxUsageModels?: GlobalSettings['minimaxUsageModels']
     prBotAuthorOverrides?: GlobalSettings['prBotAuthorOverrides']
+    terminalQuickCommands?: GlobalSettings['terminalQuickCommands']
     gitlabProjects?: GlobalSettings['gitlabProjects']
     mobileAutoRestoreFitMs?: number | null
     mobileEmulatorEnabled?: boolean
@@ -2877,6 +2884,32 @@ export class OrcaRuntimeService {
     return this.getClientSettings()
   }
 
+  getClientTerminalQuickCommands(): TerminalQuickCommand[] {
+    if (!this.store?.getSettings) {
+      throw new Error('runtime_unavailable')
+    }
+    return this.store.getSettings().terminalQuickCommands ?? []
+  }
+
+  updateClientTerminalQuickCommands(
+    mutation: TerminalQuickCommandMutation
+  ): TerminalQuickCommand[] {
+    if (!this.store?.getSettings || !this.store.updateSettings) {
+      throw new Error('runtime_unavailable')
+    }
+    const current = this.getClientTerminalQuickCommands()
+    if (
+      mutation.type === 'upsert' &&
+      !current.some((command) => command.id === mutation.command.id) &&
+      current.length >= MAX_QUICK_COMMANDS
+    ) {
+      throw new Error('Quick command limit reached')
+    }
+    const next = applyTerminalQuickCommandMutation(current, mutation)
+    this.store.updateSettings({ terminalQuickCommands: next }, { notifyListeners: true })
+    return this.getClientTerminalQuickCommands()
+  }
+
   updateClientPRBotAuthorOverride(args: { author: string; isBot: boolean }) {
     if (!this.store?.getSettings || !this.store.updateSettings) {
       throw new Error('runtime_unavailable')
@@ -19259,6 +19292,7 @@ export class OrcaRuntimeService {
       env?: Record<string, string>
       startupCommandDelivery?: WorktreeStartupLaunch['startupCommandDelivery']
       agent?: TuiAgent
+      agentPrompt?: string
       launchConfig?: SleepingAgentLaunchConfig
       launchAgent?: TuiAgent
       viewMode?: 'terminal' | 'chat'
@@ -19304,6 +19338,7 @@ export class OrcaRuntimeService {
       env?: Record<string, string>
       startupCommandDelivery?: WorktreeStartupLaunch['startupCommandDelivery']
       agent?: TuiAgent
+      agentPrompt?: string
       launchConfig?: SleepingAgentLaunchConfig
       launchAgent?: TuiAgent
       viewMode?: 'terminal' | 'chat'
@@ -19498,6 +19533,7 @@ export class OrcaRuntimeService {
       env?: Record<string, string>
       startupCommandDelivery?: WorktreeStartupLaunch['startupCommandDelivery']
       agent?: TuiAgent
+      agentPrompt?: string
       launchConfig?: SleepingAgentLaunchConfig
       launchAgent?: TuiAgent
     }
@@ -19537,7 +19573,7 @@ export class OrcaRuntimeService {
     })
     const startupPlan = buildAgentStartupPlan({
       agent: opts.agent,
-      prompt: '',
+      prompt: opts.agentPrompt ?? '',
       cmdOverrides: settings.agentCmdOverrides ?? {},
       agentArgs: resolveTuiAgentLaunchArgs(opts.agent, settings.agentDefaultArgs),
       agentEnv: resolveTuiAgentLaunchEnv(opts.agent, settings.agentDefaultEnv),
@@ -19549,6 +19585,9 @@ export class OrcaRuntimeService {
     if (!startupPlan) {
       throw new Error(`Could not build launch command for ${opts.agent}.`)
     }
+    if (opts.agentPrompt && startupPlan.followupPrompt) {
+      throw new Error(`Agent ${opts.agent} does not support startup prompt quick commands.`)
+    }
     if (workspace.connectionId) {
       await this.markRemoteWorkspaceTrustedForAgent(
         opts.agent,
diff --git a/src/main/runtime/rpc/methods/client-ui.test.ts b/src/main/runtime/rpc/methods/client-ui.test.ts
index bf55cfb07e7..44efc0d1ae2 100644
--- a/src/main/runtime/rpc/methods/client-ui.test.ts
+++ b/src/main/runtime/rpc/methods/client-ui.test.ts
@@ -1,5 +1,12 @@
 import { describe, expect, it, vi } from 'vitest'
 import { getDefaultUIState } from '../../../../shared/constants'
+import {
+  MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH,
+  MAX_QUICK_COMMAND_ID_LENGTH,
+  MAX_QUICK_COMMAND_LABEL_LENGTH,
+  MAX_QUICK_COMMAND_REPO_ID_LENGTH,
+  MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH
+} from '../../../../shared/terminal-quick-commands'
 import type { PersistedUIState } from '../../../../shared/types'
 import type { OrcaRuntimeService } from '../../orca-runtime'
 import type { RpcRequest } from '../core'
@@ -135,6 +142,150 @@ describe('client UI RPC methods', () => {
     })
   })
 
+  it('loads and normalizes quick commands through the targeted payload', async () => {
+    const commands = [
+      {
+        id: 'review',
+        label: 'Review',
+        action: 'agent-prompt' as const,
+        agent: 'codex' as const,
+        prompt: 'Review this diff',
+        scope: { type: 'global' as const }
+      }
+    ]
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getClientTerminalQuickCommands: vi.fn(() => commands),
+      updateClientTerminalQuickCommands: vi.fn(() => commands)
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: CLIENT_UI_METHODS })
+
+    const getResponse = await dispatcher.dispatch(makeRequest('settings.getTerminalQuickCommands'))
+    const updateResponse = await dispatcher.dispatch(
+      makeRequest('settings.updateTerminalQuickCommands', {
+        mutation: {
+          type: 'upsert',
+          command: {
+            id: ' review ',
+            label: ' Review ',
+            action: 'agent-prompt',
+            agent: 'codex',
+            prompt: 'Review this diff\n',
+            scope: { type: 'global' }
+          }
+        }
+      })
+    )
+
+    expect(getResponse).toMatchObject({ ok: true, result: { terminalQuickCommands: commands } })
+    expect(runtime.updateClientTerminalQuickCommands).toHaveBeenCalledWith({
+      type: 'upsert',
+      command: commands[0]
+    })
+    expect(updateResponse).toMatchObject({
+      ok: true,
+      result: { terminalQuickCommands: commands }
+    })
+
+    await dispatcher.dispatch(
+      makeRequest('settings.updateTerminalQuickCommands', {
+        mutation: { type: 'delete', id: 'review' }
+      })
+    )
+    expect(runtime.updateClientTerminalQuickCommands).toHaveBeenLastCalledWith({
+      type: 'delete',
+      id: 'review'
+    })
+  })
+
+  it('rejects malformed quick-command mutations instead of changing persisted commands', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      updateClientTerminalQuickCommands: vi.fn()
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: CLIENT_UI_METHODS })
+
+    for (const mutation of [
+      null,
+      'not-a-mutation',
+      { type: 'delete', id: '' },
+      { type: 'upsert', command: null },
+      { type: 'upsert', command: { id: 'incomplete' } },
+      {
+        type: 'upsert',
+        command: {
+          id: 'unsupported-agent',
+          label: 'Unsupported agent',
+          action: 'agent-prompt',
+          agent: 'aider',
+          prompt: 'Review this diff'
+        }
+      },
+      {
+        type: 'upsert',
+        command: {
+          id: 'oversized-command',
+          label: 'Oversized command',
+          action: 'terminal-command',
+          command: 'x'.repeat(MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH + 1),
+          appendEnter: true
+        }
+      },
+      {
+        type: 'upsert',
+        command: {
+          id: 'x'.repeat(MAX_QUICK_COMMAND_ID_LENGTH + 1),
+          label: 'Oversized id',
+          action: 'terminal-command',
+          command: 'true',
+          appendEnter: true
+        }
+      },
+      {
+        type: 'upsert',
+        command: {
+          id: 'oversized-label',
+          label: 'x'.repeat(MAX_QUICK_COMMAND_LABEL_LENGTH + 1),
+          action: 'terminal-command',
+          command: 'true',
+          appendEnter: true
+        }
+      },
+      {
+        type: 'upsert',
+        command: {
+          id: 'oversized-repo',
+          label: 'Oversized repo',
+          action: 'terminal-command',
+          command: 'true',
+          appendEnter: true,
+          scope: { type: 'repo', repoId: 'x'.repeat(MAX_QUICK_COMMAND_REPO_ID_LENGTH + 1) }
+        }
+      },
+      {
+        type: 'upsert',
+        command: {
+          id: 'oversized-prompt',
+          label: 'Oversized prompt',
+          action: 'agent-prompt',
+          agent: 'codex',
+          prompt: 'x'.repeat(MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH + 1)
+        }
+      },
+      { type: 'upsert', command: { id: 'default-pwd', label: 'Removed', command: 'pwd' } }
+    ]) {
+      const response = await dispatcher.dispatch(
+        makeRequest('settings.updateTerminalQuickCommands', { mutation })
+      )
+
+      expect(response).toMatchObject({
+        ok: false,
+        error: { code: 'invalid_argument' }
+      })
+    }
+    expect(runtime.updateClientTerminalQuickCommands).not.toHaveBeenCalled()
+  })
+
   it('caps oversized bot-author override payloads', async () => {
     const runtime = {
       getRuntimeId: () => 'test-runtime',
diff --git a/src/main/runtime/rpc/methods/client-ui.ts b/src/main/runtime/rpc/methods/client-ui.ts
index 7945203f958..4ec6b1c5b64 100644
--- a/src/main/runtime/rpc/methods/client-ui.ts
+++ b/src/main/runtime/rpc/methods/client-ui.ts
@@ -6,6 +6,7 @@ import {
   SettingsUpdate,
   UiUpdate
 } from './client-ui-schemas'
+import { TerminalQuickCommandsUpdate } from './terminal-quick-command-rpc-schema'
 
 export const CLIENT_UI_METHODS: RpcMethod[] = [
   defineMethod({
@@ -18,6 +19,22 @@ export const CLIENT_UI_METHODS: RpcMethod[] = [
     params: SettingsUpdate,
     handler: (params, { runtime }) => ({ settings: runtime.updateClientSettings(params) })
   }),
+  defineMethod({
+    name: 'settings.getTerminalQuickCommands',
+    params: null,
+    // Why: command bodies can total ~240 KB, so keep unrelated settings reads
+    // from carrying them over every paired/relay connection.
+    handler: (_params, { runtime }) => ({
+      terminalQuickCommands: runtime.getClientTerminalQuickCommands()
+    })
+  }),
+  defineMethod({
+    name: 'settings.updateTerminalQuickCommands',
+    params: TerminalQuickCommandsUpdate,
+    handler: (params, { runtime }) => ({
+      terminalQuickCommands: runtime.updateClientTerminalQuickCommands(params.mutation)
+    })
+  }),
   defineMethod({
     name: 'settings.updatePRBotAuthorOverride',
     params: PRBotAuthorOverrideUpdate,
diff --git a/src/main/runtime/rpc/methods/session-tabs-schemas.ts b/src/main/runtime/rpc/methods/session-tabs-schemas.ts
index 1b8afbd2f46..beab4b7460c 100644
--- a/src/main/runtime/rpc/methods/session-tabs-schemas.ts
+++ b/src/main/runtime/rpc/methods/session-tabs-schemas.ts
@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH } from '../../../../shared/terminal-quick-commands'
 import { isTuiAgent } from '../../../../shared/tui-agent-config'
 import type { TuiAgent } from '../../../../shared/types'
 import { sleepingAgentLaunchConfigSchema } from '../../../../shared/workspace-session-sleeping-agents'
@@ -123,6 +124,13 @@ export const CreateTerminalTab = WorktreeTabSelector.extend({
       message: 'Unknown agent preset'
     })
     .optional(),
+  // Why: agent prompts must be quoted and injected for the host shell (native,
+  // WSL, or SSH) instead of pasted from the mobile client before the TUI is ready.
+  agentPrompt: z
+    .string()
+    .max(MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH)
+    .refine((value) => value.trim().length > 0, { message: 'Agent prompt cannot be empty' })
+    .optional(),
   // Why: `agent` is the legacy preset field; `launchAgent` is the launch-plan
   // identity used when preserving resume config across runtime boundaries.
   launchAgent: z
@@ -135,6 +143,21 @@ export const CreateTerminalTab = WorktreeTabSelector.extend({
   // Why: idempotency key so a retried create (double-tap, reconnect replay)
   // returns the in-flight operation instead of spawning a duplicate terminal.
   clientMutationId: z.string().min(1).max(128).optional()
+}).superRefine((value, context) => {
+  if (value.agentPrompt !== undefined && value.agent === undefined) {
+    context.addIssue({
+      code: 'custom',
+      path: ['agentPrompt'],
+      message: 'Agent prompt requires an agent preset'
+    })
+  }
+  if (value.agentPrompt !== undefined && value.command !== undefined) {
+    context.addIssue({
+      code: 'custom',
+      path: ['agentPrompt'],
+      message: 'Agent prompt cannot be combined with a startup command'
+    })
+  }
 })
 
 const MoveTabBase = {
diff --git a/src/main/runtime/rpc/methods/session-tabs.test.ts b/src/main/runtime/rpc/methods/session-tabs.test.ts
index d81faa169cd..55818f3dedc 100644
--- a/src/main/runtime/rpc/methods/session-tabs.test.ts
+++ b/src/main/runtime/rpc/methods/session-tabs.test.ts
@@ -196,7 +196,8 @@ describe('session tab RPC methods', () => {
     const response = await dispatcher.dispatch(
       makeRequest('session.tabs.createTerminal', {
         worktree: 'id:wt-1',
-        agent: 'codex'
+        agent: 'codex',
+        agentPrompt: 'Review this diff'
       })
     )
 
@@ -207,10 +208,32 @@ describe('session tab RPC methods', () => {
       command: undefined,
       startupCommandDelivery: undefined,
       agent: 'codex',
+      agentPrompt: 'Review this diff',
       activate: undefined
     })
   })
 
+  it('rejects agent prompts without an agent preset', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      createMobileSessionTerminal: vi.fn()
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: SESSION_TAB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('session.tabs.createTerminal', {
+        worktree: 'id:wt-1',
+        agentPrompt: 'Review this diff'
+      })
+    )
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: 'invalid_argument', message: 'Agent prompt requires an agent preset' }
+    })
+    expect(runtime.createMobileSessionTerminal).not.toHaveBeenCalled()
+  })
+
   it('dispatches terminal creation with startup command delivery metadata', async () => {
     const runtime = {
       getRuntimeId: () => 'test-runtime',
diff --git a/src/main/runtime/rpc/methods/session-tabs.ts b/src/main/runtime/rpc/methods/session-tabs.ts
index 55be4d0b21e..63929afb2bd 100644
--- a/src/main/runtime/rpc/methods/session-tabs.ts
+++ b/src/main/runtime/rpc/methods/session-tabs.ts
@@ -50,6 +50,7 @@ export const SESSION_TAB_METHODS: RpcAnyMethod[] = [
         ...(params.env ? { env: params.env } : {}),
         startupCommandDelivery: params.startupCommandDelivery,
         agent: params.agent,
+        ...(params.agentPrompt !== undefined ? { agentPrompt: params.agentPrompt } : {}),
         ...(params.launchConfig ? { launchConfig: params.launchConfig } : {}),
         ...(params.launchToken ? { launchToken: params.launchToken } : {}),
         ...(params.launchAgent ? { launchAgent: params.launchAgent } : {}),
diff --git a/src/main/runtime/rpc/methods/terminal-quick-command-rpc-schema.ts b/src/main/runtime/rpc/methods/terminal-quick-command-rpc-schema.ts
new file mode 100644
index 00000000000..396710af3d3
--- /dev/null
+++ b/src/main/runtime/rpc/methods/terminal-quick-command-rpc-schema.ts
@@ -0,0 +1,73 @@
+import { z } from 'zod'
+import type { TerminalQuickCommand } from '../../../../shared/types'
+import {
+  MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH,
+  MAX_QUICK_COMMAND_ID_LENGTH,
+  MAX_QUICK_COMMAND_LABEL_LENGTH,
+  MAX_QUICK_COMMAND_REPO_ID_LENGTH,
+  MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH,
+  normalizeTerminalQuickCommands,
+  supportsTerminalAgentQuickCommand
+} from '../../../../shared/terminal-quick-commands'
+
+const TerminalQuickCommandScopeUpdate = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('global') }).strict(),
+  z
+    .object({
+      type: z.literal('repo'),
+      repoId: z.string().max(MAX_QUICK_COMMAND_REPO_ID_LENGTH)
+    })
+    .strict()
+])
+
+const TerminalQuickCommandUpdateItem = z.union([
+  z
+    .object({
+      id: z.string().max(MAX_QUICK_COMMAND_ID_LENGTH),
+      label: z.string().max(MAX_QUICK_COMMAND_LABEL_LENGTH),
+      action: z.literal('terminal-command').optional(),
+      command: z.string().max(MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH),
+      appendEnter: z.boolean(),
+      scope: TerminalQuickCommandScopeUpdate.optional()
+    })
+    .strict(),
+  z
+    .object({
+      id: z.string().max(MAX_QUICK_COMMAND_ID_LENGTH),
+      label: z.string().max(MAX_QUICK_COMMAND_LABEL_LENGTH),
+      action: z.literal('agent-prompt'),
+      agent: z.custom(supportsTerminalAgentQuickCommand, {
+        message: 'Agent does not support prompt commands'
+      }),
+      prompt: z.string().max(MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH),
+      scope: TerminalQuickCommandScopeUpdate.optional()
+    })
+    .strict()
+])
+
+export const TerminalQuickCommandsUpdate = z
+  .object({
+    // Why: a single host-side mutation preserves unrelated desktop/mobile edits
+    // and avoids retransmitting the full ~240 KB list for every small change.
+    mutation: z.union([
+      z
+        .object({
+          type: z.literal('upsert'),
+          command: TerminalQuickCommandUpdateItem.transform(
+            (value) => normalizeTerminalQuickCommands([value])[0]
+          ).pipe(
+            z.custom<TerminalQuickCommand>((value) => value !== undefined, {
+              message: 'Quick command cannot be normalized'
+            })
+          )
+        })
+        .strict(),
+      z
+        .object({
+          type: z.literal('delete'),
+          id: z.string().min(1).max(MAX_QUICK_COMMAND_ID_LENGTH)
+        })
+        .strict()
+    ])
+  })
+  .strict()
diff --git a/src/main/runtime/runtime-rpc.ts b/src/main/runtime/runtime-rpc.ts
index da0b9a0f626..7ab4f3c4882 100644
--- a/src/main/runtime/runtime-rpc.ts
+++ b/src/main/runtime/runtime-rpc.ts
@@ -362,7 +362,9 @@ const MOBILE_RPC_METHOD_ALLOWLIST = new Set([
   'nativeChat.subscribe',
   'nativeChat.unsubscribe',
   'settings.get',
+  'settings.getTerminalQuickCommands',
   'settings.update',
+  'settings.updateTerminalQuickCommands',
   'ssh.connect',
   'ssh.getState',
   'ssh.listRemovedTargetLabels',
diff --git a/src/shared/protocol-version.ts b/src/shared/protocol-version.ts
index a1fc0ae817f..a5ecb621370 100644
--- a/src/shared/protocol-version.ts
+++ b/src/shared/protocol-version.ts
@@ -44,6 +44,9 @@ export const BROWSER_CERTIFICATE_TRUST_RUNTIME_CAPABILITY = 'browser.certificate
 // floor-taking input. Mobile must not forward replies unless advertised.
 export const TERMINAL_QUERY_REPLY_INPUT_RUNTIME_CAPABILITY =
   'terminal.query-reply-input.v1' as const
+// Why: older hosts lack the targeted settings RPCs and strip agentPrompt from
+// terminal creation, so mobile must hide Quick Commands unless both are present.
+export const TERMINAL_QUICK_COMMANDS_RUNTIME_CAPABILITY = 'terminal.quick-commands.v1' as const
 // Why: older hosts strip worktree.create's clientMutationId, so mobile must only
 // replay ambiguous cutovers when the host advertises idempotent create support.
 export const WORKTREE_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY =
@@ -65,6 +68,7 @@ export const RUNTIME_CAPABILITIES = [
   LINEAR_ISSUE_ATTRIBUTE_FILTER_RUNTIME_CAPABILITY,
   AI_VAULT_RUNTIME_CAPABILITY,
   TERMINAL_QUERY_REPLY_INPUT_RUNTIME_CAPABILITY,
+  TERMINAL_QUICK_COMMANDS_RUNTIME_CAPABILITY,
   WORKTREE_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY
 ] as const
 
diff --git a/src/shared/terminal-quick-commands.test.ts b/src/shared/terminal-quick-commands.test.ts
index 4a59c4ae40a..3b07e72aef6 100644
--- a/src/shared/terminal-quick-commands.test.ts
+++ b/src/shared/terminal-quick-commands.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import {
+  applyTerminalQuickCommandMutation,
   buildTerminalQuickCommandInput,
   flattenTerminalQuickCommand,
   getTerminalQuickCommandAction,
@@ -7,6 +8,7 @@ import {
   getDefaultTerminalQuickCommands,
   isTerminalQuickCommandComplete,
   normalizeTerminalQuickCommands,
+  parseNormalizedTerminalQuickCommands,
   supportsTerminalAgentQuickCommand,
   terminalQuickCommandMatchesRepo
 } from './terminal-quick-commands'
@@ -214,6 +216,36 @@ describe('terminal quick commands', () => {
     ])
   })
 
+  it('accepts only complete canonical command lists at protocol boundaries', () => {
+    const canonical = normalizeTerminalQuickCommands([
+      { id: 'status', label: 'Status', command: 'git status', appendEnter: true }
+    ])
+
+    expect(parseNormalizedTerminalQuickCommands(canonical)).toEqual(canonical)
+    expect(parseNormalizedTerminalQuickCommands([{ ...canonical[0], command: 42 }])).toBeNull()
+    expect(
+      parseNormalizedTerminalQuickCommands([...canonical, ...canonical.slice(0, 1)])
+    ).toBeNull()
+  })
+
+  it('applies targeted mutations without replacing unrelated commands', () => {
+    const [first, second] = normalizeTerminalQuickCommands([
+      { id: 'first', label: 'First', command: 'echo first', appendEnter: true },
+      { id: 'second', label: 'Second', command: 'echo second', appendEnter: true }
+    ])
+    const edited = { ...first!, label: 'Edited' }
+
+    expect(
+      applyTerminalQuickCommandMutation([first!, second!], {
+        type: 'upsert',
+        command: edited
+      })
+    ).toEqual([edited, second])
+    expect(
+      applyTerminalQuickCommandMutation([first!, second!], { type: 'delete', id: first!.id })
+    ).toEqual([second])
+  })
+
   it('matches global commands everywhere and repo commands only in their repo', () => {
     expect(
       terminalQuickCommandMatchesRepo(
diff --git a/src/shared/terminal-quick-commands.ts b/src/shared/terminal-quick-commands.ts
index 2037a30b2b3..cee9cdc9fa9 100644
--- a/src/shared/terminal-quick-commands.ts
+++ b/src/shared/terminal-quick-commands.ts
@@ -7,17 +7,22 @@ import type {
   TerminalQuickCommandScope
 } from './types'
 
-const MAX_QUICK_COMMANDS = 40
-const MAX_QUICK_COMMAND_LABEL_LENGTH = 80
-const MAX_QUICK_COMMAND_REPO_ID_LENGTH = 200
-const MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH = 4000
+export const MAX_QUICK_COMMANDS = 40
+export const MAX_QUICK_COMMAND_ID_LENGTH = 80
+export const MAX_QUICK_COMMAND_LABEL_LENGTH = 80
+export const MAX_QUICK_COMMAND_REPO_ID_LENGTH = 200
+export const MAX_QUICK_COMMAND_TERMINAL_TEXT_LENGTH = 4000
 // Why: agent prompt quick commands still launch through startup commands for
 // argv/flag agents, so this must stay within Orca's Windows shell safety cap.
-const MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH = 6000
+export const MAX_QUICK_COMMAND_AGENT_PROMPT_LENGTH = 6000
 const REMOVED_PRESET_IDS = new Set(['default-pwd', 'default-git-status'])
 
 const DEFAULT_TERMINAL_QUICK_COMMANDS: TerminalQuickCommand[] = []
 
+export type TerminalQuickCommandMutation =
+  | { type: 'upsert'; command: TerminalQuickCommand }
+  | { type: 'delete'; id: string }
+
 export function getDefaultTerminalQuickCommands(): TerminalQuickCommand[] {
   return DEFAULT_TERMINAL_QUICK_COMMANDS.map((command) => ({ ...command }))
 }
@@ -111,10 +116,10 @@ export function normalizeTerminalQuickCommands(input: unknown): TerminalQuickCom
     const label = hasLabel ? String(record.label).trim() : ''
 
     const idBase = rawId || `quick-command-${normalized.length + 1}`
-    let id = idBase.slice(0, MAX_QUICK_COMMAND_LABEL_LENGTH)
+    let id = idBase.slice(0, MAX_QUICK_COMMAND_ID_LENGTH)
     let suffix = 2
     while (seenIds.has(id)) {
-      id = `${idBase.slice(0, MAX_QUICK_COMMAND_LABEL_LENGTH - 4)}-${suffix}`
+      id = `${idBase.slice(0, MAX_QUICK_COMMAND_ID_LENGTH - 4)}-${suffix}`
       suffix += 1
     }
     seenIds.add(id)
@@ -157,6 +162,91 @@ export function normalizeTerminalQuickCommands(input: unknown): TerminalQuickCom
   return normalized
 }
 
+function hasExactKeys(record: Record<string, unknown>, keys: readonly string[]): boolean {
+  const actual = Object.keys(record)
+  return actual.length === keys.length && keys.every((key) => Object.hasOwn(record, key))
+}
+
+function isNormalizedTerminalQuickCommandScope(
+  value: unknown,
+  expected: TerminalQuickCommandScope
+): boolean {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false
+  }
+  const scope = value as Record<string, unknown>
+  if (expected.type === 'global') {
+    return hasExactKeys(scope, ['type']) && scope.type === 'global'
+  }
+  return (
+    hasExactKeys(scope, ['type', 'repoId']) &&
+    scope.type === 'repo' &&
+    scope.repoId === expected.repoId
+  )
+}
+
+function isNormalizedTerminalQuickCommand(value: unknown, expected: TerminalQuickCommand): boolean {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false
+  }
+  const command = value as Record<string, unknown>
+  if (
+    command.id !== expected.id ||
+    command.label !== expected.label ||
+    !isNormalizedTerminalQuickCommandScope(command.scope, expected.scope ?? { type: 'global' })
+  ) {
+    return false
+  }
+  if (isTerminalAgentQuickCommand(expected)) {
+    return (
+      hasExactKeys(command, ['id', 'label', 'action', 'agent', 'prompt', 'scope']) &&
+      command.action === 'agent-prompt' &&
+      command.agent === expected.agent &&
+      command.prompt === expected.prompt
+    )
+  }
+  return (
+    hasExactKeys(command, ['id', 'label', 'action', 'command', 'appendEnter', 'scope']) &&
+    command.action === 'terminal-command' &&
+    command.command === expected.command &&
+    command.appendEnter === expected.appendEnter
+  )
+}
+
+// Why: a full-list client must reject any "authoritative" payload that would
+// change under normalization, or its next mutation could persist silent loss.
+export function parseNormalizedTerminalQuickCommands(
+  input: unknown
+): TerminalQuickCommand[] | null {
+  if (!Array.isArray(input) || input.length > MAX_QUICK_COMMANDS) {
+    return null
+  }
+  const normalized = normalizeTerminalQuickCommands(input)
+  if (
+    normalized.length !== input.length ||
+    normalized.some((command, index) => !isNormalizedTerminalQuickCommand(input[index], command))
+  ) {
+    return null
+  }
+  return normalized
+}
+
+// Why: paired clients can edit settings concurrently. Applying one command at
+// the host boundary preserves unrelated commands added by another client.
+export function applyTerminalQuickCommandMutation(
+  commands: readonly TerminalQuickCommand[],
+  mutation: TerminalQuickCommandMutation
+): TerminalQuickCommand[] {
+  if (mutation.type === 'delete') {
+    return commands.filter((command) => command.id !== mutation.id)
+  }
+  const existingIndex = commands.findIndex((command) => command.id === mutation.command.id)
+  if (existingIndex === -1) {
+    return [...commands, mutation.command]
+  }
+  return commands.map((command, index) => (index === existingIndex ? mutation.command : command))
+}
+
 export function buildTerminalQuickCommandInput(command: TerminalCommandQuickCommand): string {
   return command.appendEnter ? `${command.command}\r` : command.command
 }

From 936ec06e5ab550657dafe8bc56c765b701b8fd5e Mon Sep 17 00:00:00 2001
From: Mark Xian <mark-xian@foxmail.com>
Date: Mon, 20 Jul 2026 14:55:56 +0800
Subject: [PATCH 33/54] fix(search): bind content results to runtime owner
 (#9262)

Capture the worktree and runtime route that produced each committed content-search result set, then reuse that owner for opens and retries. This prevents active-worktree and ambient-runtime changes from retargeting remote matches while preserving explicit local and SSH routing. Closes #9185.
---
 .../right-sidebar/search-match-open.test.ts   |  98 +++++++++++
 .../right-sidebar/search-match-open.ts        |  47 +++--
 .../right-sidebar/useFileSearchPanel.ts       |  22 +--
 .../useFileSearchRunner.test.tsx              | 166 ++++++++++++++++++
 .../right-sidebar/useFileSearchRunner.ts      |  27 ++-
 .../src/lib/file-search-result-owner.test.ts  |  26 +++
 .../src/lib/file-search-result-owner.ts       |  16 ++
 src/renderer/src/store/slices/editor.ts       |   7 +
 .../src/store/slices/store-cascades.test.ts   |   3 +
 .../src/store/slices/worktrees.test.ts        |   8 +
 src/renderer/src/store/slices/worktrees.ts    |   4 +
 11 files changed, 392 insertions(+), 32 deletions(-)
 create mode 100644 src/renderer/src/components/right-sidebar/search-match-open.test.ts
 create mode 100644 src/renderer/src/components/right-sidebar/useFileSearchRunner.test.tsx
 create mode 100644 src/renderer/src/lib/file-search-result-owner.test.ts
 create mode 100644 src/renderer/src/lib/file-search-result-owner.ts

diff --git a/src/renderer/src/components/right-sidebar/search-match-open.test.ts b/src/renderer/src/components/right-sidebar/search-match-open.test.ts
new file mode 100644
index 00000000000..3724851aa9a
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/search-match-open.test.ts
@@ -0,0 +1,98 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { openMatchResult } from './search-match-open'
+
+type IntendedResultOwner = {
+  worktreeId: string
+  runtimeEnvironmentId: string | null
+}
+
+function openResult(resultOwner: IntendedResultOwner) {
+  const openFile = vi.fn()
+  const setPendingEditorReveal = vi.fn()
+  const params = {
+    resultOwner,
+    fileResult: {
+      filePath: '/owner/repo/src/example.ts',
+      relativePath: 'src/example.ts',
+      matches: []
+    },
+    match: {
+      line: 7,
+      column: 4,
+      matchLength: 6,
+      lineContent: 'const result = owner'
+    },
+    openFile,
+    setPendingEditorReveal,
+    revealRafRef: { current: null },
+    revealInnerRafRef: { current: null }
+  } satisfies Parameters<typeof openMatchResult>[0]
+
+  openMatchResult(params)
+  return { openFile, setPendingEditorReveal }
+}
+
+describe('openMatchResult', () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      vi.fn(() => 1)
+    )
+    vi.stubGlobal('cancelAnimationFrame', vi.fn())
+  })
+
+  it('opens with the remote owner captured by the search after the active worktree changes', () => {
+    const { openFile } = openResult({
+      worktreeId: 'worktree-that-produced-results',
+      runtimeEnvironmentId: 'runtime-that-produced-results'
+    })
+
+    expect(openFile).toHaveBeenCalledWith(
+      expect.objectContaining({
+        worktreeId: 'worktree-that-produced-results',
+        runtimeEnvironmentId: 'runtime-that-produced-results'
+      }),
+      { suppressActiveRuntimeFallback: false }
+    )
+  })
+
+  it('keeps an explicitly local result local when another runtime is active', () => {
+    const { openFile } = openResult({
+      worktreeId: 'local-worktree',
+      runtimeEnvironmentId: null
+    })
+
+    expect(openFile).toHaveBeenCalledWith(
+      expect.objectContaining({
+        worktreeId: 'local-worktree',
+        runtimeEnvironmentId: null
+      }),
+      { suppressActiveRuntimeFallback: true }
+    )
+  })
+
+  it('does not guess an owner for results without a committed search source', () => {
+    const openFile = vi.fn()
+
+    openMatchResult({
+      resultOwner: null,
+      fileResult: {
+        filePath: '/unresolved/repo/file.ts',
+        relativePath: 'file.ts',
+        matches: []
+      },
+      match: {
+        line: 1,
+        column: 1,
+        matchLength: 4,
+        lineContent: 'test'
+      },
+      openFile,
+      setPendingEditorReveal: vi.fn(),
+      revealRafRef: { current: null },
+      revealInnerRafRef: { current: null }
+    })
+
+    expect(openFile).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/components/right-sidebar/search-match-open.ts b/src/renderer/src/components/right-sidebar/search-match-open.ts
index 43c328a3606..0e2bf3b74ac 100644
--- a/src/renderer/src/components/right-sidebar/search-match-open.ts
+++ b/src/renderer/src/components/right-sidebar/search-match-open.ts
@@ -1,4 +1,5 @@
 import { detectLanguage } from '@/lib/language-detect'
+import type { FileSearchResultOwner } from '@/lib/file-search-result-owner'
 import type { SearchFileResult, SearchMatch } from '../../../../shared/types'
 
 export function cancelRevealFrame(frameRef: React.RefObject<number | null>): void {
@@ -9,16 +10,20 @@ export function cancelRevealFrame(frameRef: React.RefObject<number | null>): voi
 }
 
 export function openMatchResult(params: {
-  activeWorktreeId: string
+  resultOwner: FileSearchResultOwner | null
   fileResult: SearchFileResult
   match: SearchMatch
-  openFile: (file: {
-    filePath: string
-    relativePath: string
-    worktreeId: string
-    language: string
-    mode: 'edit'
-  }) => void
+  openFile: (
+    file: {
+      filePath: string
+      relativePath: string
+      worktreeId: string
+      language: string
+      mode: 'edit'
+      runtimeEnvironmentId: string | null
+    },
+    options: { suppressActiveRuntimeFallback: boolean }
+  ) => void
   setPendingEditorReveal: (
     reveal: {
       filePath: string
@@ -31,7 +36,7 @@ export function openMatchResult(params: {
   revealInnerRafRef: React.RefObject<number | null>
 }): void {
   const {
-    activeWorktreeId,
+    resultOwner,
     fileResult,
     match,
     openFile,
@@ -40,13 +45,23 @@ export function openMatchResult(params: {
     revealInnerRafRef
   } = params
 
-  openFile({
-    filePath: fileResult.filePath,
-    relativePath: fileResult.relativePath,
-    worktreeId: activeWorktreeId,
-    language: detectLanguage(fileResult.relativePath),
-    mode: 'edit'
-  })
+  if (!resultOwner) {
+    return
+  }
+
+  openFile(
+    {
+      filePath: fileResult.filePath,
+      relativePath: fileResult.relativePath,
+      worktreeId: resultOwner.worktreeId,
+      runtimeEnvironmentId: resultOwner.runtimeEnvironmentId,
+      language: detectLanguage(fileResult.relativePath),
+      mode: 'edit'
+    },
+    {
+      suppressActiveRuntimeFallback: resultOwner.runtimeEnvironmentId === null
+    }
+  )
 
   cancelRevealFrame(revealRafRef)
   cancelRevealFrame(revealInnerRafRef)
diff --git a/src/renderer/src/components/right-sidebar/useFileSearchPanel.ts b/src/renderer/src/components/right-sidebar/useFileSearchPanel.ts
index 3e315c34a7f..f0935b625a0 100644
--- a/src/renderer/src/components/right-sidebar/useFileSearchPanel.ts
+++ b/src/renderer/src/components/right-sidebar/useFileSearchPanel.ts
@@ -44,6 +44,7 @@ export function useFileSearchPanel(explorerView: 'files' | 'search'): FileSearch
   const fileSearchIncludePattern = searchState?.includePattern ?? ''
   const fileSearchExcludePattern = searchState?.excludePattern ?? ''
   const fileSearchResults = searchState?.results ?? null
+  const fileSearchResultOwner = searchState?.resultOwner ?? null
   const fileSearchLoading = searchState?.loading ?? false
   const fileSearchCollapsedFiles = searchState?.collapsedFiles ?? EMPTY_COLLAPSED_FILES
   const fileSearchSeedRequestId = searchState?.seedRequestId
@@ -127,18 +128,22 @@ export function useFileSearchPanel(explorerView: 'files' | 'search'): FileSearch
   useEffect(() => {
     if (!worktreePath) {
       cancelPendingSearch()
-      updateActiveSearchState({ results: null })
+      updateActiveSearchState({ results: null, resultOwner: null })
     }
   }, [worktreePath, cancelPendingSearch, updateActiveSearchState])
 
-  const deferredSearchResults = useDeferredValue(fileSearchResults)
+  const committedSearchResults = useMemo(
+    () => ({ results: fileSearchResults, owner: fileSearchResultOwner }),
+    [fileSearchResultOwner, fileSearchResults]
+  )
+  const deferredSearchResults = useDeferredValue(committedSearchResults)
   const searchRows = useMemo(
     () =>
       buildSearchRows(
-        fileSearchQuery.trim() && worktreePath ? deferredSearchResults : null,
+        fileSearchQuery.trim() && worktreePath ? deferredSearchResults.results : null,
         fileSearchCollapsedFiles
       ),
-    [deferredSearchResults, fileSearchCollapsedFiles, fileSearchQuery, worktreePath]
+    [deferredSearchResults.results, fileSearchCollapsedFiles, fileSearchQuery, worktreePath]
   )
 
   useEffect(() => {
@@ -218,11 +223,8 @@ export function useFileSearchPanel(explorerView: 'files' | 'search'): FileSearch
 
   const handleMatchClick = useCallback(
     (fileResult: SearchFileResult, match: SearchMatch) => {
-      if (!activeWorktreeId) {
-        return
-      }
       openMatchResult({
-        activeWorktreeId,
+        resultOwner: deferredSearchResults.owner,
         fileResult,
         match,
         openFile,
@@ -231,7 +233,7 @@ export function useFileSearchPanel(explorerView: 'files' | 'search'): FileSearch
         revealInnerRafRef
       })
     },
-    [activeWorktreeId, openFile, setPendingEditorReveal]
+    [deferredSearchResults.owner, openFile, setPendingEditorReveal]
   )
 
   return {
@@ -274,7 +276,7 @@ export function useFileSearchPanel(explorerView: 'files' | 'search'): FileSearch
       }
     },
     resultsProps: {
-      results: deferredSearchResults,
+      results: deferredSearchResults.results,
       hasCommittedResults: fileSearchResults !== null,
       query: fileSearchQuery,
       loading: fileSearchLoading,
diff --git a/src/renderer/src/components/right-sidebar/useFileSearchRunner.test.tsx b/src/renderer/src/components/right-sidebar/useFileSearchRunner.test.tsx
new file mode 100644
index 00000000000..62bbf4f9bec
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/useFileSearchRunner.test.tsx
@@ -0,0 +1,166 @@
+// @vitest-environment happy-dom
+
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { SearchResult } from '../../../../shared/types'
+import { useFileSearchRunner } from './useFileSearchRunner'
+
+const mocks = vi.hoisted(() => ({
+  getConnectionId: vi.fn(),
+  getState: vi.fn(),
+  searchRuntimeFiles: vi.fn()
+}))
+
+vi.mock('@/lib/connection-context', () => ({
+  getConnectionId: mocks.getConnectionId
+}))
+
+vi.mock('@/runtime/runtime-file-client', () => ({
+  searchRuntimeFiles: mocks.searchRuntimeFiles
+}))
+
+vi.mock('@/store', () => ({
+  useAppStore: Object.assign(vi.fn(), { getState: mocks.getState })
+}))
+
+const RESULTS: SearchResult = {
+  files: [],
+  totalMatches: 0,
+  truncated: false
+}
+
+function renderSearchRunner(state: Record<string, unknown>, worktreeId: string) {
+  const updates: Record<string, unknown>[] = []
+  mocks.getState.mockImplementation(() => state)
+  mocks.searchRuntimeFiles.mockResolvedValue(RESULTS)
+
+  const hook = renderHook(() =>
+    useFileSearchRunner({
+      activeWorktreeId: worktreeId,
+      worktreePath: '/repo',
+      updateActiveSearchState: (update) => updates.push(update)
+    })
+  )
+
+  return { hook, updates }
+}
+
+async function finishSearch(executeSearch: (query: string) => void): Promise<void> {
+  await act(async () => {
+    executeSearch('owner')
+    await vi.advanceTimersByTimeAsync(300)
+  })
+}
+
+describe('useFileSearchRunner result ownership', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    mocks.getConnectionId.mockReturnValue(null)
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.clearAllMocks()
+  })
+
+  it('commits the explicit remote owner used for the search, not the ambient runtime', async () => {
+    const worktreeId = 'repo-a::/repo'
+    const state = {
+      settings: { activeRuntimeEnvironmentId: 'ambient-runtime-b' },
+      repos: [{ id: 'repo-a', executionHostId: 'runtime:repo-runtime' }],
+      worktreesByRepo: {
+        'repo-a': [{ id: worktreeId, repoId: 'repo-a', hostId: 'runtime:search-runtime-a' }]
+      },
+      fileSearchStateByWorktree: { [worktreeId]: {} }
+    }
+    const { hook, updates } = renderSearchRunner(state, worktreeId)
+
+    await finishSearch(hook.result.current.executeSearch)
+
+    expect(mocks.searchRuntimeFiles).toHaveBeenCalledWith(
+      expect.objectContaining({
+        settings: { activeRuntimeEnvironmentId: 'search-runtime-a' },
+        worktreeId
+      }),
+      expect.any(Object)
+    )
+    expect(updates).toContainEqual({
+      results: RESULTS,
+      resultOwner: {
+        worktreeId,
+        runtimeEnvironmentId: 'search-runtime-a'
+      }
+    })
+  })
+
+  it('commits explicit local ownership without inheriting an ambient runtime', async () => {
+    const worktreeId = 'repo-a::/repo'
+    const state = {
+      settings: { activeRuntimeEnvironmentId: 'ambient-runtime-b' },
+      repos: [{ id: 'repo-a', executionHostId: 'runtime:repo-runtime' }],
+      worktreesByRepo: {
+        'repo-a': [{ id: worktreeId, repoId: 'repo-a', hostId: 'local' }]
+      },
+      fileSearchStateByWorktree: { [worktreeId]: {} }
+    }
+    const { hook, updates } = renderSearchRunner(state, worktreeId)
+
+    await finishSearch(hook.result.current.executeSearch)
+
+    expect(mocks.searchRuntimeFiles).toHaveBeenCalledWith(
+      expect.objectContaining({ settings: { activeRuntimeEnvironmentId: null }, worktreeId }),
+      expect.any(Object)
+    )
+    expect(updates).toContainEqual({
+      results: RESULTS,
+      resultOwner: { worktreeId, runtimeEnvironmentId: null }
+    })
+  })
+
+  it('preserves SSH routing through the worktree connection without a runtime owner', async () => {
+    const worktreeId = 'repo-a::/repo'
+    const state = {
+      settings: { activeRuntimeEnvironmentId: 'ambient-runtime-b' },
+      repos: [{ id: 'repo-a', connectionId: 'ssh-target' }],
+      worktreesByRepo: {
+        'repo-a': [{ id: worktreeId, repoId: 'repo-a', hostId: 'ssh:ssh-target' }]
+      },
+      fileSearchStateByWorktree: { [worktreeId]: {} }
+    }
+    mocks.getConnectionId.mockReturnValue('ssh-target')
+    const { hook, updates } = renderSearchRunner(state, worktreeId)
+
+    await finishSearch(hook.result.current.executeSearch)
+
+    expect(mocks.searchRuntimeFiles).toHaveBeenCalledWith(
+      expect.objectContaining({
+        settings: { activeRuntimeEnvironmentId: null },
+        worktreeId,
+        connectionId: 'ssh-target'
+      }),
+      expect.any(Object)
+    )
+    expect(updates).toContainEqual({
+      results: RESULTS,
+      resultOwner: { worktreeId, runtimeEnvironmentId: null }
+    })
+  })
+
+  it('keeps an unresolved owner local when no runtime actually handled the search', async () => {
+    const worktreeId = 'missing-repo::/repo'
+    const state = {
+      settings: { activeRuntimeEnvironmentId: null },
+      repos: [],
+      worktreesByRepo: {},
+      fileSearchStateByWorktree: { [worktreeId]: {} }
+    }
+    const { hook, updates } = renderSearchRunner(state, worktreeId)
+
+    await finishSearch(hook.result.current.executeSearch)
+
+    expect(updates).toContainEqual({
+      results: RESULTS,
+      resultOwner: { worktreeId, runtimeEnvironmentId: null }
+    })
+  })
+})
diff --git a/src/renderer/src/components/right-sidebar/useFileSearchRunner.ts b/src/renderer/src/components/right-sidebar/useFileSearchRunner.ts
index 4269d730342..20feac4a610 100644
--- a/src/renderer/src/components/right-sidebar/useFileSearchRunner.ts
+++ b/src/renderer/src/components/right-sidebar/useFileSearchRunner.ts
@@ -1,5 +1,9 @@
 import { useCallback, useEffect, useRef } from 'react'
 import { getConnectionId } from '@/lib/connection-context'
+import {
+  createFileSearchResultOwner,
+  type FileSearchResultOwner
+} from '@/lib/file-search-result-owner'
 import {
   createEmptyRuntimeFileSearchResult,
   getRuntimeFileSearchRejectedField
@@ -12,7 +16,11 @@ import { getRightSidebarWorktreeRuntimeSettings } from './file-explorer-runtime-
 const SEARCH_DEBOUNCE_MS = 300
 const SEARCH_MAX_RESULTS = 2000
 
-type UpdateSearchState = (updates: { loading?: boolean; results?: SearchResult | null }) => void
+type UpdateSearchState = (updates: {
+  loading?: boolean
+  results?: SearchResult | null
+  resultOwner?: FileSearchResultOwner | null
+}) => void
 
 type UseFileSearchRunnerArgs = {
   activeWorktreeId: string | null
@@ -53,7 +61,7 @@ export function useFileSearchRunner({
       }
 
       if (!worktreePath || !activeWorktreeId) {
-        updateActiveSearchState({ results: null, loading: false })
+        updateActiveSearchState({ results: null, resultOwner: null, loading: false })
         return
       }
 
@@ -65,21 +73,26 @@ export function useFileSearchRunner({
           excludePattern: currentSearchState?.excludePattern || undefined
         })
       ) {
+        const runtimeSettings = getRightSidebarWorktreeRuntimeSettings(activeWorktreeId)
         updateActiveSearchState({
           results: createEmptyRuntimeFileSearchResult(),
+          resultOwner: createFileSearchResultOwner(activeWorktreeId, runtimeSettings),
           loading: false
         })
         return
       }
 
       if (!query.trim()) {
-        updateActiveSearchState({ results: null, loading: false })
+        updateActiveSearchState({ results: null, resultOwner: null, loading: false })
         return
       }
 
       updateActiveSearchState({ loading: true })
       searchTimerRef.current = setTimeout(async () => {
         searchTimerRef.current = null
+        // Why: results can outlive the selected worktree; clicks must reuse the route that produced them.
+        const runtimeSettings = getRightSidebarWorktreeRuntimeSettings(activeWorktreeId)
+        const resultOwner = createFileSearchResultOwner(activeWorktreeId, runtimeSettings)
         try {
           const state = useAppStore.getState()
           const connectionId = getConnectionId(activeWorktreeId) ?? undefined
@@ -94,6 +107,7 @@ export function useFileSearchRunner({
             if (latestSearchIdRef.current === searchId) {
               updateActiveSearchState({
                 results: createEmptyRuntimeFileSearchResult(),
+                resultOwner,
                 loading: false
               })
             }
@@ -101,7 +115,7 @@ export function useFileSearchRunner({
           }
           const results = await searchRuntimeFiles(
             {
-              settings: getRightSidebarWorktreeRuntimeSettings(activeWorktreeId),
+              settings: runtimeSettings,
               worktreeId: activeWorktreeId,
               worktreePath,
               connectionId
@@ -118,13 +132,14 @@ export function useFileSearchRunner({
             }
           )
           if (latestSearchIdRef.current === searchId) {
-            updateActiveSearchState({ results })
+            updateActiveSearchState({ results, resultOwner })
           }
         } catch (err) {
           console.error('Search failed:', err)
           if (latestSearchIdRef.current === searchId) {
             updateActiveSearchState({
-              results: { files: [], totalMatches: 0, truncated: false }
+              results: { files: [], totalMatches: 0, truncated: false },
+              resultOwner
             })
           }
         } finally {
diff --git a/src/renderer/src/lib/file-search-result-owner.test.ts b/src/renderer/src/lib/file-search-result-owner.test.ts
new file mode 100644
index 00000000000..561e14a20c8
--- /dev/null
+++ b/src/renderer/src/lib/file-search-result-owner.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { createFileSearchResultOwner } from './file-search-result-owner'
+
+describe('createFileSearchResultOwner', () => {
+  it('captures the exact runtime used by the completed search', () => {
+    const settings = { activeRuntimeEnvironmentId: ' runtime-owner-a ' }
+    const owner = createFileSearchResultOwner('worktree-a', settings)
+    settings.activeRuntimeEnvironmentId = 'runtime-owner-b'
+
+    expect(owner).toEqual({
+      worktreeId: 'worktree-a',
+      runtimeEnvironmentId: 'runtime-owner-a'
+    })
+  })
+
+  it.each([null, '', '   '])('records %j as an explicit non-runtime owner', (environmentId) => {
+    expect(
+      createFileSearchResultOwner('local-or-ssh-worktree', {
+        activeRuntimeEnvironmentId: environmentId
+      })
+    ).toEqual({
+      worktreeId: 'local-or-ssh-worktree',
+      runtimeEnvironmentId: null
+    })
+  })
+})
diff --git a/src/renderer/src/lib/file-search-result-owner.ts b/src/renderer/src/lib/file-search-result-owner.ts
new file mode 100644
index 00000000000..b2c719f245a
--- /dev/null
+++ b/src/renderer/src/lib/file-search-result-owner.ts
@@ -0,0 +1,16 @@
+import type { GlobalSettings } from '../../../shared/types'
+
+export type FileSearchResultOwner = {
+  worktreeId: string
+  runtimeEnvironmentId: string | null
+}
+
+export function createFileSearchResultOwner(
+  worktreeId: string,
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'>
+): FileSearchResultOwner {
+  return {
+    worktreeId,
+    runtimeEnvironmentId: settings.activeRuntimeEnvironmentId?.trim() || null
+  }
+}
diff --git a/src/renderer/src/store/slices/editor.ts b/src/renderer/src/store/slices/editor.ts
index bd2bc1fddeb..5856c14039c 100644
--- a/src/renderer/src/store/slices/editor.ts
+++ b/src/renderer/src/store/slices/editor.ts
@@ -72,6 +72,7 @@ import {
 import { createUntitledMarkdownFileWithTemplateSelection } from '@/lib/create-untitled-markdown'
 import { extractIpcErrorMessage } from '@/lib/ipc-error'
 import { translate } from '@/i18n/i18n'
+import type { FileSearchResultOwner } from '@/lib/file-search-result-owner'
 
 export type {
   ActiveRightSidebarTab,
@@ -87,6 +88,7 @@ const DEFAULT_FILE_SEARCH_STATE = {
   includePattern: '',
   excludePattern: '',
   results: null,
+  resultOwner: null,
   loading: false,
   collapsedFiles: new Set<string>()
 } satisfies Omit<
@@ -723,6 +725,7 @@ export type EditorSlice = {
       includePattern: string
       excludePattern: string
       results: SearchResult | null
+      resultOwner: FileSearchResultOwner | null
       loading: boolean
       collapsedFiles: Set<string>
       seedRequestId?: number
@@ -1528,6 +1531,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         ...(shouldSeed
           ? {
               results: null,
+              resultOwner: null,
               loading: false,
               collapsedFiles: new Set<string>(),
               seedRequestId: (current.seedRequestId ?? 0) + 1
@@ -4106,6 +4110,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
             ...current,
             query,
             results: null,
+            resultOwner: null,
             loading: false,
             collapsedFiles: new Set(),
             seedRequestId: (current.seedRequestId ?? 0) + 1
@@ -4123,6 +4128,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
             ...current,
             includePattern,
             results: null,
+            resultOwner: null,
             loading: false,
             collapsedFiles: new Set(),
             seedRequestId: (current.seedRequestId ?? 0) + 1
@@ -4177,6 +4183,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
             ...current,
             query: '',
             results: null,
+            resultOwner: null,
             loading: false,
             collapsedFiles: new Set()
           }
diff --git a/src/renderer/src/store/slices/store-cascades.test.ts b/src/renderer/src/store/slices/store-cascades.test.ts
index 30a19084ec4..5e6e10f13fc 100644
--- a/src/renderer/src/store/slices/store-cascades.test.ts
+++ b/src/renderer/src/store/slices/store-cascades.test.ts
@@ -146,6 +146,7 @@ describe('removeWorktree cascade', () => {
           includePattern: '*.ts',
           excludePattern: 'dist/**',
           results: { files: [], totalMatches: 0, truncated: false },
+          resultOwner: null,
           loading: false,
           collapsedFiles: new Set(['/path/wt1/file.ts'])
         }
@@ -697,6 +698,7 @@ describe('removeWorktree cascade', () => {
           includePattern: '',
           excludePattern: '',
           results: { files: [], totalMatches: 0, truncated: false },
+          resultOwner: null,
           loading: false,
           collapsedFiles: new Set()
         },
@@ -708,6 +710,7 @@ describe('removeWorktree cascade', () => {
           includePattern: '*.md',
           excludePattern: '',
           results: { files: [], totalMatches: 1, truncated: false },
+          resultOwner: null,
           loading: false,
           collapsedFiles: new Set(['/path/wt2/notes.md'])
         }
diff --git a/src/renderer/src/store/slices/worktrees.test.ts b/src/renderer/src/store/slices/worktrees.test.ts
index 3b148562442..bb120d973db 100644
--- a/src/renderer/src/store/slices/worktrees.test.ts
+++ b/src/renderer/src/store/slices/worktrees.test.ts
@@ -6882,6 +6882,9 @@ describe('migrateWorktreeIdentity', () => {
       renamingWorktreeId: { worktreeId: OLD, rowKey: 'all:old' },
       tabsByWorktree: { [OLD]: [{ id: 'tab1', worktreeId: OLD }] },
       rightSidebarExplorerViewByWorktree: { [OLD]: 'search' },
+      fileSearchStateByWorktree: {
+        [OLD]: { resultOwner: { worktreeId: OLD, runtimeEnvironmentId: 'runtime-a' } }
+      },
       activeTabIdByWorktree: { [OLD]: 'tab1' },
       browserTabsByWorktree: { [OLD]: [{ id: 'browser1', worktreeId: OLD }] },
       browserPagesByWorkspace: { browser1: [{ id: 'page1', worktreeId: OLD }] },
@@ -6945,6 +6948,11 @@ describe('migrateWorktreeIdentity', () => {
     expect(s.gitBranchCompareRequestStatusHeadByWorktree[NEW]).toBe('head-old')
     expect(s.rightSidebarExplorerViewByWorktree[OLD]).toBeUndefined()
     expect(s.rightSidebarExplorerViewByWorktree[NEW]).toBe('search')
+    expect(s.fileSearchStateByWorktree[OLD]).toBeUndefined()
+    expect(s.fileSearchStateByWorktree[NEW]?.resultOwner).toEqual({
+      worktreeId: NEW,
+      runtimeEnvironmentId: 'runtime-a'
+    })
     expect(s.lastVisitedAtByWorktreeId[NEW]).toBe(123)
     expect(s.defaultTerminalTabsAppliedByWorktreeId[NEW]).toBe(true)
     // The two maps absent from the purge list are still re-keyed.
diff --git a/src/renderer/src/store/slices/worktrees.ts b/src/renderer/src/store/slices/worktrees.ts
index 49c9cdce963..298a18c965c 100644
--- a/src/renderer/src/store/slices/worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees.ts
@@ -1824,6 +1824,10 @@ function buildWorktreeRenameState(
         workspace: withNewWorktreeId(snapshot.workspace),
         pages: snapshot.pages.map(withNewWorktreeId)
       })),
+    fileSearchStateByWorktree: (searchState: AppState['fileSearchStateByWorktree'][string]) => ({
+      ...searchState,
+      resultOwner: searchState.resultOwner ? withNewWorktreeId(searchState.resultOwner) : null
+    }),
     unifiedTabsByWorktree: (tabs: { worktreeId: string }[]) => tabs.map(withNewWorktreeId),
     groupsByWorktree: (groups: { worktreeId: string }[]) => groups.map(withNewWorktreeId)
   }

From b3b5031883c616502a82b1b50572e76da40e859a Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Mon, 20 Jul 2026 03:04:28 -0400
Subject: [PATCH 34/54] test(e2e): deliver node burst via temp file so
 PowerShell quoting can't break OSC title (#8521) (#9391)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The e2e terminal helpers typed `node -e ${JSON.stringify(script)}` into the
PTY. JSON.stringify emits POSIX-style \" escapes, which PowerShell does not
honor: it re-splits the program on `;` inside the payload, node throws
'Expected unicode escape' before emitting a single byte, and the OSC-title
assertions fail deterministically on Windows (default shell = PowerShell).

Stage the program in a unique temp .cjs file instead and send
`node "<forward-slash path>"` — no shell ever parses the program source, so
delivery is byte-identical on PowerShell, cmd, bash, and zsh (verified with
hexdumps: 07 1b 5d 30 3b ... 07 matches exactly across shells). Forward
slashes keep the quoted path valid in both POSIX shells and PowerShell; the
Codex startup marker moves from argv into the script body so no argument
quoting remains. macOS/Linux payload bytes are unchanged — only the delivery
mechanism differs. Test infrastructure only; no product code touched.
---
 .../artificial-opencode-scroll-scenario.ts    | 15 ++++--
 .../helpers/run-node-script-in-terminal.ts    | 51 +++++++++++++++++++
 ...al-codex-hidden-startup-background.spec.ts |  7 ++-
 ...terminal-hidden-tui-visual-restore.spec.ts |  4 +-
 .../e2e/terminal-hidden-view-parking.spec.ts  | 11 +++-
 ...rminal-tab-switch-sigwinch-restore.spec.ts |  4 +-
 ...terminal-tab-switch-visual-restore.spec.ts |  4 +-
 7 files changed, 86 insertions(+), 10 deletions(-)
 create mode 100644 tests/e2e/helpers/run-node-script-in-terminal.ts

diff --git a/tests/e2e/artificial-opencode-scroll-scenario.ts b/tests/e2e/artificial-opencode-scroll-scenario.ts
index f9469af2ec5..b362a5a4340 100644
--- a/tests/e2e/artificial-opencode-scroll-scenario.ts
+++ b/tests/e2e/artificial-opencode-scroll-scenario.ts
@@ -12,7 +12,8 @@ import {
   getResponsiveScrollPath,
   type ScrollAttemptMeasurement
 } from './artificial-opencode-scroll-measurement'
-import { sendToTerminal, waitForTerminalOutput } from './helpers/terminal'
+import { runNodeScriptInTerminal } from './helpers/run-node-script-in-terminal'
+import { waitForTerminalOutput } from './helpers/terminal'
 
 export { getResponsiveScrollPath }
 
@@ -50,8 +51,16 @@ export async function seedActiveTerminalScrollback(
     `for (let i = 0; i < 420; i++) console.log('OPENCODE_SCROLL_${runId}_' + i)`,
     `console.log('${marker}')`
   ].join(';')
-  await sendToTerminal(page, ptyId, `node -e ${JSON.stringify(script)}\r`)
-  await waitForTerminalOutput(page, marker, 10_000)
+  // Why: delivered via a temp file — `node -e` quoting is not PowerShell-safe (#8521).
+  const staged = await runNodeScriptInTerminal(page, ptyId, script, {
+    prefix: 'orca-opencode-scroll-seed'
+  })
+  try {
+    await waitForTerminalOutput(page, marker, 10_000)
+  } finally {
+    // Why: the ready marker proves node already loaded the script.
+    staged.cleanup()
+  }
   await scrollActiveTerminalToBottom(page)
 }
 
diff --git a/tests/e2e/helpers/run-node-script-in-terminal.ts b/tests/e2e/helpers/run-node-script-in-terminal.ts
new file mode 100644
index 00000000000..5b227c68012
--- /dev/null
+++ b/tests/e2e/helpers/run-node-script-in-terminal.ts
@@ -0,0 +1,51 @@
+import { randomUUID } from 'node:crypto'
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import type { Page } from '@stablyai/playwright-test'
+import { sendToTerminal } from './terminal'
+
+export type StagedTerminalNodeScript = {
+  /**
+   * Shell-agnostic command (no trailing `\r`): `node "<forward-slash path>"`.
+   */
+  command: string
+  scriptPath: string
+  /** Removes the staged temp file. Only call after the script has started. */
+  cleanup: () => void
+}
+
+// Why: `node -e ${JSON.stringify(script)}` breaks under PowerShell PTYs on
+// Windows — PowerShell does not honor \" escapes, so it re-splits the program
+// on `;` and node throws before emitting the payload (#8521). Staging the
+// program in a temp .cjs file removes shell quoting from the picture entirely
+// while emitting byte-identical output on every shell.
+export function stageNodeScriptForTerminal(
+  source: string,
+  options: { dir?: string; prefix?: string } = {}
+): StagedTerminalNodeScript {
+  const dir = options.dir ?? tmpdir()
+  mkdirSync(dir, { recursive: true })
+  const prefix = options.prefix ?? 'orca-e2e-terminal-node'
+  const scriptPath = path.join(dir, `${prefix}-${randomUUID()}.cjs`)
+  writeFileSync(scriptPath, source)
+  // Why: forward slashes are valid for node on Windows and parse identically in
+  // PowerShell, cmd, and POSIX shells; raw backslashes would be eaten by bash.
+  const command = `node "${scriptPath.replaceAll('\\', '/')}"`
+  return {
+    command,
+    scriptPath,
+    cleanup: () => rmSync(scriptPath, { force: true })
+  }
+}
+
+export async function runNodeScriptInTerminal(
+  page: Page,
+  ptyId: string,
+  source: string,
+  options: { dir?: string; prefix?: string } = {}
+): Promise<StagedTerminalNodeScript> {
+  const staged = stageNodeScriptForTerminal(source, options)
+  await sendToTerminal(page, ptyId, `${staged.command}\r`)
+  return staged
+}
diff --git a/tests/e2e/terminal-codex-hidden-startup-background.spec.ts b/tests/e2e/terminal-codex-hidden-startup-background.spec.ts
index ff074c323de..72ddd64253a 100644
--- a/tests/e2e/terminal-codex-hidden-startup-background.spec.ts
+++ b/tests/e2e/terminal-codex-hidden-startup-background.spec.ts
@@ -2,6 +2,7 @@ import { Buffer } from 'node:buffer'
 import { PNG } from 'pngjs'
 import type { Page } from '@stablyai/playwright-test'
 import { test, expect } from './helpers/orca-app'
+import { stageNodeScriptForTerminal } from './helpers/run-node-script-in-terminal'
 import {
   ensureTerminalVisible,
   getActiveWorktreeId,
@@ -26,7 +27,8 @@ const COMPOSER_BG = { red: 72, green: 72, blue: 72 }
 
 function codexLikeStartupCommand(marker: string): string {
   const script = [
-    'const marker = process.argv[1];',
+    // Why: embedded as a literal — an argv marker would need per-shell quoting.
+    `const marker = ${JSON.stringify(marker)};`,
     'const width = Math.max(60, process.stdout.columns || 100);',
     'const pad = (text) => (text + " ".repeat(width)).slice(0, width);',
     'const bg = "\\x1b[48;2;72;72;72m\\x1b[38;2;235;235;235m";',
@@ -54,7 +56,8 @@ function codexLikeStartupCommand(marker: string): string {
     'setTimeout(render, 100);',
     'setInterval(() => {}, 1000);'
   ].join('')
-  return `node -e ${JSON.stringify(script)} ${JSON.stringify(marker)}`
+  // Why: delivered via a temp file — `node -e` quoting is not PowerShell-safe (#8521).
+  return stageNodeScriptForTerminal(script, { prefix: 'orca-codex-startup-bg' }).command
 }
 
 async function waitForHiddenTabPtyId(page: Page, tabId: string): Promise<string> {
diff --git a/tests/e2e/terminal-hidden-tui-visual-restore.spec.ts b/tests/e2e/terminal-hidden-tui-visual-restore.spec.ts
index 2dccaf2e87c..96476cb0cd2 100644
--- a/tests/e2e/terminal-hidden-tui-visual-restore.spec.ts
+++ b/tests/e2e/terminal-hidden-tui-visual-restore.spec.ts
@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto'
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { test, expect } from './helpers/orca-app'
+import { runNodeScriptInTerminal } from './helpers/run-node-script-in-terminal'
 import {
   ensureTerminalVisible,
   getActiveWorktreeId,
@@ -205,7 +206,8 @@ async function writeHiddenSideEffectBurst(
 ): Promise<void> {
   const payload = `\x07\x1b]0;${title}\x07${marker}\n`
   const script = `process.stdout.write(${JSON.stringify(payload)}); setTimeout(() => process.exit(0), 30000)`
-  await sendToTerminal(page, ptyId, `node -e ${JSON.stringify(script)}\r`)
+  // Why: delivered via a temp file — `node -e` quoting is not PowerShell-safe (#8521).
+  await runNodeScriptInTerminal(page, ptyId, script, { prefix: 'orca-hidden-side-effect' })
 }
 
 test.describe('Hidden terminal TUI visual restore', () => {
diff --git a/tests/e2e/terminal-hidden-view-parking.spec.ts b/tests/e2e/terminal-hidden-view-parking.spec.ts
index fe393656337..9f31d69321c 100644
--- a/tests/e2e/terminal-hidden-view-parking.spec.ts
+++ b/tests/e2e/terminal-hidden-view-parking.spec.ts
@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto'
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { test, expect } from './helpers/orca-app'
+import { runNodeScriptInTerminal } from './helpers/run-node-script-in-terminal'
 import {
   ensureTerminalVisible,
   getActiveTabId,
@@ -336,7 +337,10 @@ test.describe('Terminal hidden view parking', () => {
       // proves the revealed terminal accepts input end-to-end, not just echo.
       const typedMarker = `PARKED_TYPED_OK_${runId}`
       const typedProbeScript = `console.log('PARKED_TYPED_OK_' + '${runId}')`
-      await sendToTerminal(orcaPage, tabAPtyId, `node -e ${JSON.stringify(typedProbeScript)}\r`)
+      // Why: delivered via a temp file — `node -e` quoting is not PowerShell-safe (#8521).
+      await runNodeScriptInTerminal(orcaPage, tabAPtyId, typedProbeScript, {
+        prefix: 'orca-parked-typed-probe'
+      })
       await expect
         .poll(() => getTerminalContent(orcaPage, 12_000), {
           timeout: 10_000,
@@ -374,7 +378,10 @@ test.describe('Terminal hidden view parking', () => {
     // before the store assertion lands.
     const payload = `\x1b]0;${parkedTitle}\x07\x07${marker}\n`
     const sideEffectScript = `process.stdout.write(${JSON.stringify(payload)}); setTimeout(() => process.exit(0), 30000)`
-    await sendToTerminal(orcaPage, tabAPtyId, `node -e ${JSON.stringify(sideEffectScript)}\r`)
+    // Why: delivered via a temp file — `node -e` quoting is not PowerShell-safe (#8521).
+    await runNodeScriptInTerminal(orcaPage, tabAPtyId, sideEffectScript, {
+      prefix: 'orca-parked-side-effect'
+    })
 
     await expect
       .poll(() => getTerminalTabTitle(orcaPage, worktreeId, tabAId), {
diff --git a/tests/e2e/terminal-tab-switch-sigwinch-restore.spec.ts b/tests/e2e/terminal-tab-switch-sigwinch-restore.spec.ts
index 75d65bea2d9..5b3d1940f21 100644
--- a/tests/e2e/terminal-tab-switch-sigwinch-restore.spec.ts
+++ b/tests/e2e/terminal-tab-switch-sigwinch-restore.spec.ts
@@ -1,5 +1,6 @@
 import type { Page } from '@stablyai/playwright-test'
 import { test, expect } from './helpers/orca-app'
+import { stageNodeScriptForTerminal } from './helpers/run-node-script-in-terminal'
 import {
   ensureTerminalVisible,
   getActiveTabId,
@@ -56,7 +57,8 @@ function buildSigwinchResetProbeCommand(): string {
     "process.on('SIGWINCH',()=>{if(armed===false)return;page=0;paint(topLabel)})",
     'setInterval(()=>{},1000)'
   ].join(';')
-  return `node -e ${JSON.stringify(script)}`
+  // Why: delivered via a temp file — `node -e` quoting is not PowerShell-safe (#8521).
+  return stageNodeScriptForTerminal(script, { prefix: 'orca-sigwinch-probe' }).command
 }
 
 function buildSigwinchResetProbeSnapshot(label: string): string {
diff --git a/tests/e2e/terminal-tab-switch-visual-restore.spec.ts b/tests/e2e/terminal-tab-switch-visual-restore.spec.ts
index d154882ec23..36258bd3b96 100644
--- a/tests/e2e/terminal-tab-switch-visual-restore.spec.ts
+++ b/tests/e2e/terminal-tab-switch-visual-restore.spec.ts
@@ -1,5 +1,6 @@
 import type { Page, TestInfo } from '@stablyai/playwright-test'
 import { test, expect } from './helpers/orca-app'
+import { runNodeScriptInTerminal } from './helpers/run-node-script-in-terminal'
 import {
   ensureTerminalVisible,
   getActiveTabId,
@@ -360,7 +361,8 @@ async function startHiddenPtyOutputBurst(page: Page, ptyId: string, runId: strin
     '},1);',
     '},30);'
   ].join('')
-  await sendToTerminal(page, ptyId, `node -e ${JSON.stringify(script)}\r`)
+  // Why: delivered via a temp file — `node -e` quoting is not PowerShell-safe (#8521).
+  await runNodeScriptInTerminal(page, ptyId, script, { prefix: 'orca-tab-switch-burst' })
 }
 
 async function writeStaticTabContent(

From 2e67af82d2896ef9082f6d5053db1598b0936c17 Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Mon, 20 Jul 2026 03:16:26 -0400
Subject: [PATCH 35/54] fix(worktree): bound teardown RPCs so Windows workspace
 deletion can't hang (#9516)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(worktree): bound teardown RPCs so Windows workspace deletion can't hang

Native-Windows workspace deletion failed with "Timed out waiting for
physical PTY teardown". On win32 the daemon PTY adapter is the local
provider, and destructive teardown's kill/listSessions RPCs used the
DaemonClient 30s default — larger than the 10s sweep deadline — so a
slow/wedged daemon let the outer deadline fire with the confusing error
and blocked deletion.

Thread an optional `timeoutMs` through IPtyProvider.shutdown/listProcesses
and bound every RPC on the destructive-removal path (provider sweep,
registry sweep, and the runtime-graph sweep via stopAndWait) to the
remaining sweep budget minus a margin. The daemon adapter shares one
budget across ensureConnected + the RPC; the SSH provider forwards the
bound to the relay mux. stopAndWait splits the budget across its two
sequential RPCs and bounds the cold-start wait, failing closed.

Result: a wedged backend now fails fast with the accurate "Failed to
physically stop every PTY" (retry succeeds once the process is truly
gone), and the misleading deadline error no longer blocks deletion.
Fail-closed safety is preserved: a genuinely-live process still blocks
removal. Non-teardown callers pass no timeoutMs and keep the 30s default.

* refactor(worktree): thread an absolute teardown deadline instead of a relative timeout

Elegance pass on the teardown-RPC bounding. Instead of passing a relative
`timeoutMs` and reconstructing an absolute deadline + "remaining budget" at
three layers (stopAndWait, the daemon adapter's shutdown/listProcesses, and
per-RPC in the sweeps), thread one absolute `deadlineMs` (epoch ms) through
IPtyProvider.shutdown/listProcesses. Each RPC leaf converts to a relative
timeout exactly once, at the moment it issues (`max(1, deadlineMs - now)`).

Why this is cleaner:
- The threaded value's identity is a point in time, not a duration, matching
  the codebase's existing deadline-based shared-budget idiom.
- Sequential RPCs (kill then liveness verify) share the budget structurally:
  a later leaf converting the same deadline naturally gets less time, so the
  explicit recompute-after-shutdown bookkeeping disappears.
- Removes the per-layer deadline re-anchoring that let the effective deadline
  drift slightly later at each hop.
- The 500ms margin is now applied once (`teardownRpcDeadline`), and the dead
  `: opts.timeoutMs` else-arms in the adapter are gone.

No behavior change: non-teardown callers still pass nothing and keep the
30s default + original connect behavior; fail-closed safety is intact.
Tests strengthened to pin the exact leaf-observed budgets and the margin.

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
---
 src/main/daemon/daemon-pty-adapter.ts         |  44 ++++-
 src/main/daemon/daemon-pty-provider.ts        |  13 +-
 src/main/daemon/daemon-pty-router.ts          |  11 +-
 .../daemon/degraded-daemon-pty-provider.ts    |   9 +-
 src/main/ipc/pty.test.ts                      |  68 ++++++++
 src/main/ipc/pty.ts                           |  46 ++++-
 src/main/providers/ssh-pty-provider.test.ts   |  56 ++++--
 src/main/providers/ssh-pty-provider.ts        |  36 +++-
 src/main/providers/types.ts                   |  11 +-
 src/main/runtime/orca-runtime.test.ts         |  68 +++++++-
 src/main/runtime/orca-runtime.ts              |  17 +-
 src/main/runtime/worktree-teardown.test.ts    | 165 ++++++++++++++++--
 src/main/runtime/worktree-teardown.ts         |  22 ++-
 13 files changed, 489 insertions(+), 77 deletions(-)

diff --git a/src/main/daemon/daemon-pty-adapter.ts b/src/main/daemon/daemon-pty-adapter.ts
index 81e91f16c63..8b6e3151776 100644
--- a/src/main/daemon/daemon-pty-adapter.ts
+++ b/src/main/daemon/daemon-pty-adapter.ts
@@ -80,6 +80,13 @@ export type DaemonPtyAdapterOptions = {
 const MAX_TOMBSTONES = 1000
 const MAX_CONCURRENT_CHECKPOINTS = 4
 
+// Why: providers take an absolute teardown deadline, but the client RPC takes a
+// relative timeout — convert only here, at the request itself, so sequential RPCs
+// naturally share the remaining budget (undefined keeps the client's 30s default).
+function remainingRequestTimeoutMs(deadlineMs: number | undefined): number | undefined {
+  return deadlineMs === undefined ? undefined : Math.max(1, deadlineMs - Date.now())
+}
+
 export class TerminalKilledError extends Error {
   constructor(sessionId: string) {
     super(`Session "${sessionId}" was explicitly killed`)
@@ -573,10 +580,15 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.client.notify('setSessionBackground', { sessionId: id, background: safeBackground })
   }
 
-  async shutdown(id: string, opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void> {
+  async shutdown(
+    id: string,
+    opts: { immediate?: boolean; keepHistory?: boolean; deadlineMs?: number }
+  ): Promise<void> {
     // Why: shutdown can be the first lazy-client operation after restart; connect
-    // before killing so a healthy daemon session is not orphaned (#7742).
-    await this.ensureConnected()
+    // before killing so a healthy daemon session is not orphaned (#7742). Connect
+    // and kill share the caller's one absolute deadline, so a wedged handshake
+    // cannot burn the whole teardown budget before the kill even starts.
+    await this.ensureConnected(opts.deadlineMs)
     // Why: sleep/exact-stop kills the live PTY before the periodic checkpoint may run.
     // Force a final snapshot so wake can restore the pane users left.
     if (opts.keepHistory) {
@@ -606,7 +618,11 @@ export class DaemonPtyAdapter implements IPtyProvider {
         this.historyManager?.suspendSession(id)
       }
     }
-    await this.client.request('kill', { sessionId: id, immediate: opts.immediate ?? false })
+    await this.client.request(
+      'kill',
+      { sessionId: id, immediate: opts.immediate ?? false },
+      remainingRequestTimeoutMs(opts.deadlineMs)
+    )
     this.activeSessionIds.delete(id)
     this.dirtySessionVersions.delete(id)
     if (!opts.keepHistory) {
@@ -856,9 +872,15 @@ export class DaemonPtyAdapter implements IPtyProvider {
     return { alive, killed }
   }
 
-  async listProcesses(): Promise<PtyProcessInfo[]> {
-    await this.ensureConnected()
-    const result = await this.client.request<ListSessionsResult>('listSessions', undefined)
+  async listProcesses(opts?: { deadlineMs?: number }): Promise<PtyProcessInfo[]> {
+    // Why: connect + listSessions share the caller's one absolute deadline so a
+    // wedged handshake cannot burn the whole teardown budget before the list issues.
+    await this.ensureConnected(opts?.deadlineMs)
+    const result = await this.client.request<ListSessionsResult>(
+      'listSessions',
+      undefined,
+      remainingRequestTimeoutMs(opts?.deadlineMs)
+    )
     return result.sessions
       .filter((s) => s.isAlive)
       .map((s) => ({
@@ -1058,9 +1080,13 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.client.disconnect()
   }
 
-  private async ensureConnected(): Promise<void> {
+  private async ensureConnected(deadlineMs?: number): Promise<void> {
     try {
-      await this.client.ensureConnected()
+      // Why: destructive teardown bounds the handshake by its deadline so a wedged
+      // connect fails fast; undefined keeps the default connect behavior.
+      await (deadlineMs !== undefined
+        ? this.client.ensureConnectedWithin(Math.max(1, deadlineMs - Date.now()))
+        : this.client.ensureConnected())
     } finally {
       // Why: a respawn launcher holds a temporary full pair until this adapter
       // has attempted its permanent reconnect, preventing both gaps and leaks.
diff --git a/src/main/daemon/daemon-pty-provider.ts b/src/main/daemon/daemon-pty-provider.ts
index 7c569f755b3..b4bd2bd0284 100644
--- a/src/main/daemon/daemon-pty-provider.ts
+++ b/src/main/daemon/daemon-pty-provider.ts
@@ -64,8 +64,17 @@ export class DaemonPtyProvider {
     this.client.notify('resize', { sessionId: id, cols, rows })
   }
 
-  async shutdown(id: string, opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void> {
-    await this.client.request('kill', { sessionId: id, immediate: opts.immediate ?? false })
+  async shutdown(
+    id: string,
+    opts: { immediate?: boolean; keepHistory?: boolean; deadlineMs?: number }
+  ): Promise<void> {
+    // Why: convert the absolute teardown deadline to a relative timeout only here,
+    // at the RPC leaf; undefined keeps the DaemonClient 30s default.
+    await this.client.request(
+      'kill',
+      { sessionId: id, immediate: opts.immediate ?? false },
+      opts.deadlineMs !== undefined ? Math.max(1, opts.deadlineMs - Date.now()) : undefined
+    )
   }
 
   onData(callback: (payload: { id: string; data: string }) => void): () => void {
diff --git a/src/main/daemon/daemon-pty-router.ts b/src/main/daemon/daemon-pty-router.ts
index a726b4000d9..8400576eb32 100644
--- a/src/main/daemon/daemon-pty-router.ts
+++ b/src/main/daemon/daemon-pty-router.ts
@@ -101,7 +101,10 @@ export class DaemonPtyRouter implements IPtyProvider {
     this.adapterFor(id).setPtyBackgrounded(id, background)
   }
 
-  async shutdown(id: string, opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void> {
+  async shutdown(
+    id: string,
+    opts: { immediate?: boolean; keepHistory?: boolean; deadlineMs?: number }
+  ): Promise<void> {
     await this.adapterFor(id).shutdown(id, opts)
     // Why: sleep passes keepHistory=true and re-spawns against the same
     // sessionId on wake. If we delete the routing entry here, adapterFor()
@@ -173,10 +176,12 @@ export class DaemonPtyRouter implements IPtyProvider {
     await this.current.revive(state)
   }
 
-  async listProcesses(): Promise<PtyProcessInfo[]> {
+  async listProcesses(opts?: { deadlineMs?: number }): Promise<PtyProcessInfo[]> {
     // Why: runtime exact-stop/liveness flows must fail closed if any adapter
     // cannot provide a trustworthy process list.
-    const results = await Promise.all(this.allAdapters().map((adapter) => adapter.listProcesses()))
+    const results = await Promise.all(
+      this.allAdapters().map((adapter) => adapter.listProcesses(opts))
+    )
     return results.flat()
   }
 
diff --git a/src/main/daemon/degraded-daemon-pty-provider.ts b/src/main/daemon/degraded-daemon-pty-provider.ts
index 591c2cfa53d..82fb2c49e98 100644
--- a/src/main/daemon/degraded-daemon-pty-provider.ts
+++ b/src/main/daemon/degraded-daemon-pty-provider.ts
@@ -109,7 +109,10 @@ export class DegradedDaemonPtyProvider implements IPtyProvider {
     this.providerFor(id).setPtyBackgrounded?.(id, background)
   }
 
-  async shutdown(id: string, opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void> {
+  async shutdown(
+    id: string,
+    opts: { immediate?: boolean; keepHistory?: boolean; deadlineMs?: number }
+  ): Promise<void> {
     await this.providerFor(id).shutdown(id, opts)
     if (!opts.keepHistory) {
       this.sessionProviders.delete(id)
@@ -173,9 +176,9 @@ export class DegradedDaemonPtyProvider implements IPtyProvider {
     await this.fallback.revive(state)
   }
 
-  async listProcesses(): Promise<PtyProcessInfo[]> {
+  async listProcesses(opts?: { deadlineMs?: number }): Promise<PtyProcessInfo[]> {
     const results = await Promise.all(
-      this.allProviders().map((provider) => provider.listProcesses())
+      this.allProviders().map((provider) => provider.listProcesses(opts))
     )
     return results.flat()
   }
diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index 5fddd31c1f8..81090b63733 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -3013,6 +3013,74 @@ describe('registerPtyHandlers', () => {
         expect(runtime.onPtyExit).toHaveBeenCalledWith('remote-pty', -1)
       })
 
+      it('splits the teardown budget so the liveness RPC gets only what shutdown left', async () => {
+        // Why: sequential RPCs must share one absolute deadline; otherwise both get
+        // the full ~9.5s bound and their sum overruns the 10s sweep deadline (Finding 1).
+        // Fake timers freeze Date.now() at entry, then let the shutdown RPC burn a
+        // deterministic slice of the budget so the leaf-observed remainders are provable.
+        vi.useFakeTimers()
+        // Each provider call records the budget an RPC leaf would see at issue time.
+        const remainingAtLeaf: number[] = []
+        const shutdown = vi.fn(async (_id: string, opts?: { deadlineMs?: number }) => {
+          remainingAtLeaf.push((opts?.deadlineMs ?? 0) - Date.now())
+          await new Promise<void>((resolve) => setTimeout(resolve, 1000))
+        })
+        const listProcesses = vi.fn(async (opts?: { deadlineMs?: number }) => {
+          remainingAtLeaf.push((opts?.deadlineMs ?? 0) - Date.now())
+          return []
+        })
+        setLocalPtyProvider({
+          spawn: vi.fn(),
+          write: vi.fn(),
+          resize: vi.fn(),
+          shutdown,
+          sendSignal: vi.fn(),
+          getCwd: vi.fn(),
+          getInitialCwd: vi.fn(),
+          clearBuffer: vi.fn(),
+          acknowledgeDataEvent: vi.fn(),
+          hasChildProcesses: vi.fn(),
+          getForegroundProcess: vi.fn(),
+          serialize: vi.fn(),
+          revive: vi.fn(),
+          onData: vi.fn(() => () => {}),
+          onReplay: vi.fn(() => () => {}),
+          onExit: vi.fn(() => () => {}),
+          listProcesses,
+          attach: vi.fn(),
+          getDefaultShell: vi.fn(),
+          getProfiles: vi.fn()
+        } as never)
+        const runtime = {
+          setPtyController: vi.fn(),
+          onPtyExit: vi.fn()
+        }
+        handlers.clear()
+        registerPtyHandlers(mainWindow as never, runtime as never)
+        const controller = runtime.setPtyController.mock.calls[0]?.[0] as {
+          stopAndWait: (
+            ptyId: string,
+            opts?: { keepHistory?: boolean; deadlineMs?: number }
+          ) => Promise<boolean>
+        }
+
+        const deadlineMs = Date.now() + 4321
+        const stopPromise = controller.stopAndWait('local-pty', { deadlineMs })
+        await vi.advanceTimersByTimeAsync(1000)
+        await expect(stopPromise).resolves.toBe(true)
+
+        // Both calls carry the same absolute deadline...
+        expect(shutdown).toHaveBeenCalledWith(
+          'local-pty',
+          expect.objectContaining({ immediate: true, deadlineMs })
+        )
+        // ...so at the leaves the shutdown RPC sees the full 4321ms budget, while the
+        // SUBSEQUENT liveness list RPC sees only what shutdown left: the 1000ms it
+        // consumed is gone, so 4321 - 1000 = 3321 remain until the shared deadline.
+        expect(remainingAtLeaf).toEqual([4321, 3321])
+        vi.useRealTimers()
+      })
+
       it('runtime controller stopAndWait fails when keepHistory allows the PTY to revive', async () => {
         vi.useFakeTimers()
         const shutdown = vi.fn(async () => undefined)
diff --git a/src/main/ipc/pty.ts b/src/main/ipc/pty.ts
index 956383b7651..cd4242143a1 100644
--- a/src/main/ipc/pty.ts
+++ b/src/main/ipc/pty.ts
@@ -492,16 +492,24 @@ function delay(ms: number): Promise<void> {
   })
 }
 
-async function isProviderPtyLive(provider: IPtyProvider, ptyId: string): Promise<boolean> {
-  return (await provider.listProcesses()).some((session) => session.id === ptyId)
+async function isProviderPtyLive(
+  provider: IPtyProvider,
+  ptyId: string,
+  deadlineMs?: number
+): Promise<boolean> {
+  // Why: bound the liveness list RPC by the teardown deadline so a wedged daemon
+  // fails fast; undefined keeps the provider default for all other callers.
+  return (
+    await provider.listProcesses(deadlineMs !== undefined ? { deadlineMs } : undefined)
+  ).some((session) => session.id === ptyId)
 }
 
 async function verifyPtyStopped(
   provider: IPtyProvider,
   ptyId: string,
-  opts: { keepHistory?: boolean } | undefined
+  opts: { keepHistory?: boolean; deadlineMs?: number } | undefined
 ): Promise<boolean> {
-  if (await isProviderPtyLive(provider, ptyId)) {
+  if (await isProviderPtyLive(provider, ptyId, opts?.deadlineMs)) {
     return false
   }
   if (!opts?.keepHistory) {
@@ -510,7 +518,7 @@ async function verifyPtyStopped(
   const deadline = Date.now() + KEEP_HISTORY_STOP_SETTLE_MS
   while (Date.now() < deadline) {
     await delay(KEEP_HISTORY_STOP_POLL_MS)
-    if (await isProviderPtyLive(provider, ptyId)) {
+    if (await isProviderPtyLive(provider, ptyId, opts?.deadlineMs)) {
       return false
     }
   }
@@ -2612,7 +2620,7 @@ export function registerPtyHandlers(
   async function shutdownProviderAndDetectExit(
     provider: IPtyProvider,
     id: string,
-    opts: { immediate?: boolean; keepHistory?: boolean }
+    opts: { immediate?: boolean; keepHistory?: boolean; deadlineMs?: number }
   ): Promise<boolean> {
     let providerExitObserved = false
     const unsubscribe = provider.onExit((payload) => {
@@ -3509,11 +3517,32 @@ export function registerPtyHandlers(
       let connectionId: string | null | undefined = ptyOwnership.get(ptyId)
       const parsedSshId = connectionId === undefined ? parseAppSshPtyId(ptyId) : null
       connectionId ??= parsedSshId?.connectionId
+      // Why: destructive teardown threads one absolute deadline through every await
+      // below; each RPC leaf converts it to the remaining time when it issues, so
+      // sequential RPCs share the budget and cannot overrun the sweep deadline.
+      const deadlineMs = opts?.deadlineMs
       const startupPromise = getLocalPtyProviderStartupPromise(connectionId)
       if (startupPromise) {
         // Why: exact-stop must resolve the provider after daemon startup just
         // like renderer kills, or the fallback can falsely confirm teardown.
-        await startupPromise
+        if (deadlineMs !== undefined) {
+          // Why: bound the cold-start await by the teardown deadline instead of the
+          // 60s startup fail-open cap; fail closed so the sweep records the miss.
+          const won = await Promise.race([
+            // Why: () => false on rejection both fails closed on a startup error and
+            // keeps the losing branch's rejection from surfacing as unhandled.
+            startupPromise.then(
+              () => true,
+              () => false
+            ),
+            delay(Math.max(1, deadlineMs - Date.now())).then(() => false)
+          ])
+          if (!won) {
+            return false
+          }
+        } else {
+          await startupPromise
+        }
       }
       let provider: IPtyProvider
       try {
@@ -3534,7 +3563,8 @@ export function registerPtyHandlers(
       try {
         providerExitObserved = await shutdownProviderAndDetectExit(provider, ptyId, {
           immediate: true,
-          keepHistory: opts?.keepHistory ?? false
+          keepHistory: opts?.keepHistory ?? false,
+          deadlineMs
         })
       } catch (err) {
         if (!isPtyAlreadyGoneError(err)) {
diff --git a/src/main/providers/ssh-pty-provider.test.ts b/src/main/providers/ssh-pty-provider.test.ts
index ccbc60edcee..209218fa1f0 100644
--- a/src/main/providers/ssh-pty-provider.test.ts
+++ b/src/main/providers/ssh-pty-provider.test.ts
@@ -472,20 +472,44 @@ describe('SshPtyProvider', () => {
 
   it('shutdown sends pty.shutdown request', async () => {
     await provider.shutdown(scopedPty1, { immediate: true })
-    expect(mux.request).toHaveBeenCalledWith('pty.shutdown', {
-      id: 'pty-1',
-      immediate: true,
-      keepHistory: false
-    })
+    expect(mux.request).toHaveBeenCalledWith(
+      'pty.shutdown',
+      {
+        id: 'pty-1',
+        immediate: true,
+        keepHistory: false
+      },
+      undefined
+    )
   })
 
   it('shutdown forwards keepHistory: true over the relay', async () => {
     await provider.shutdown(scopedPty1, { immediate: true, keepHistory: true })
-    expect(mux.request).toHaveBeenCalledWith('pty.shutdown', {
-      id: 'pty-1',
-      immediate: true,
-      keepHistory: true
-    })
+    expect(mux.request).toHaveBeenCalledWith(
+      'pty.shutdown',
+      {
+        id: 'pty-1',
+        immediate: true,
+        keepHistory: true
+      },
+      undefined
+    )
+  })
+
+  it('shutdown bounds the relay RPC by the teardown deadline', async () => {
+    // Why: freeze Date.now() so the leaf conversion deadline -> remaining relative
+    // timeout is exact and the mux receives precisely the leftover budget.
+    vi.useFakeTimers()
+    try {
+      await provider.shutdown(scopedPty1, { immediate: true, deadlineMs: Date.now() + 4321 })
+      expect(mux.request).toHaveBeenCalledWith(
+        'pty.shutdown',
+        { id: 'pty-1', immediate: true, keepHistory: false },
+        { timeoutMs: 4321 }
+      )
+    } finally {
+      vi.useRealTimers()
+    }
   })
 
   it('sendSignal sends pty.sendSignal request', async () => {
@@ -546,6 +570,18 @@ describe('SshPtyProvider', () => {
     expect(result).toEqual([
       { id: scopedPty1, cwd: '/home', title: 'zsh', worktreeId: 'repo::/home' }
     ])
+    expect(mux.request).toHaveBeenCalledWith('pty.listProcesses', undefined, undefined)
+  })
+
+  it('listProcesses bounds the relay RPC by the teardown deadline', async () => {
+    vi.useFakeTimers()
+    try {
+      mux.request.mockResolvedValue([])
+      await provider.listProcesses({ deadlineMs: Date.now() + 4321 })
+      expect(mux.request).toHaveBeenCalledWith('pty.listProcesses', undefined, { timeoutMs: 4321 })
+    } finally {
+      vi.useRealTimers()
+    }
   })
 
   it('getDefaultShell returns shell path', async () => {
diff --git a/src/main/providers/ssh-pty-provider.ts b/src/main/providers/ssh-pty-provider.ts
index 1182104cefa..648799eac65 100644
--- a/src/main/providers/ssh-pty-provider.ts
+++ b/src/main/providers/ssh-pty-provider.ts
@@ -34,6 +34,15 @@ export function isSshPtyIdentityMismatchError(err: unknown): boolean {
   return message.includes(SSH_PTY_IDENTITY_MISMATCH_ERROR) || /identity mismatch/i.test(message)
 }
 
+// Why: providers take an absolute teardown deadline, but the mux takes a relative
+// timeout — convert only here, at the RPC itself, so sequential relay calls share
+// the remaining budget (undefined keeps the multiplexer default timeout).
+function relayTimeoutOptions(deadlineMs: number | undefined): { timeoutMs: number } | undefined {
+  return deadlineMs === undefined
+    ? undefined
+    : { timeoutMs: Math.max(1, deadlineMs - Date.now()) }
+}
+
 /**
  * Remote PTY provider that proxies all operations through the relay
  * via the JSON-RPC multiplexer. Implements the same IPtyProvider interface
@@ -256,12 +265,19 @@ export class SshPtyProvider implements IPtyProvider {
     this.mux.notify('pty.resize', { id: this.toRelayPtyId(id), cols, rows })
   }
 
-  async shutdown(id: string, opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void> {
-    await this.mux.request('pty.shutdown', {
-      id: this.toRelayPtyId(id),
-      immediate: opts.immediate ?? false,
-      keepHistory: opts.keepHistory ?? false
-    })
+  async shutdown(
+    id: string,
+    opts: { immediate?: boolean; keepHistory?: boolean; deadlineMs?: number }
+  ): Promise<void> {
+    await this.mux.request(
+      'pty.shutdown',
+      {
+        id: this.toRelayPtyId(id),
+        immediate: opts.immediate ?? false,
+        keepHistory: opts.keepHistory ?? false
+      },
+      relayTimeoutOptions(opts.deadlineMs)
+    )
   }
 
   async sendSignal(id: string, signal: string): Promise<void> {
@@ -314,8 +330,12 @@ export class SshPtyProvider implements IPtyProvider {
     await this.mux.request('pty.revive', { state })
   }
 
-  async listProcesses(): Promise<PtyProcessInfo[]> {
-    const result = await this.mux.request('pty.listProcesses')
+  async listProcesses(opts?: { deadlineMs?: number }): Promise<PtyProcessInfo[]> {
+    const result = await this.mux.request(
+      'pty.listProcesses',
+      undefined,
+      relayTimeoutOptions(opts?.deadlineMs)
+    )
     return (result as PtyProcessInfo[]).map((session) => ({
       ...session,
       id: this.toAppPtyId(session.id)
diff --git a/src/main/providers/types.ts b/src/main/providers/types.ts
index ea2ea2c57dc..6523736fd2b 100644
--- a/src/main/providers/types.ts
+++ b/src/main/providers/types.ts
@@ -161,7 +161,13 @@ export type IPtyProvider = {
    */
   getAppliedSize?: (id: string) => Promise<{ cols: number; rows: number } | null>
 
-  shutdown(id: string, opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void>
+  // Why: deadlineMs (absolute epoch ms) bounds the underlying RPCs so destructive
+  // teardown fails fast inside its sweep budget instead of tripping the outer sweep
+  // deadline; each RPC leaf converts to a relative timeout when it actually issues.
+  shutdown(
+    id: string,
+    opts: { immediate?: boolean; keepHistory?: boolean; deadlineMs?: number }
+  ): Promise<void>
   sendSignal(id: string, signal: string): Promise<void>
   getCwd(id: string): Promise<string>
   getInitialCwd(id: string): Promise<string>
@@ -175,7 +181,8 @@ export type IPtyProvider = {
   confirmForegroundProcess?: (id: string) => Promise<string | null>
   serialize(ids: string[]): Promise<string>
   revive(state: string): Promise<void>
-  listProcesses(): Promise<PtyProcessInfo[]>
+  // Why: deadlineMs bounds the underlying RPC exactly like shutdown's deadlineMs.
+  listProcesses(opts?: { deadlineMs?: number }): Promise<PtyProcessInfo[]>
   getDefaultShell(): Promise<string>
   getProfiles(): Promise<{ name: string; path: string }[]>
   onData(callback: (payload: PtyDataEvent) => void): () => void
diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index 5c9c8ae0953..df63ad52573 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -30,6 +30,10 @@ import {
   removeWorktree
 } from '../git/worktree'
 import * as gitRunner from '../git/runner'
+import {
+  WORKTREE_PROCESS_SWEEP_TIMEOUT_MS,
+  WORKTREE_TEARDOWN_RPC_MARGIN_MS
+} from './worktree-teardown'
 import { clearSubmodulePathsCacheForTests, listSubmodulePaths } from '../git/status'
 import {
   createSetupRunnerScript,
@@ -3287,9 +3291,10 @@ describe('OrcaRuntimeService', () => {
     ).rejects.toThrow('Cannot delete the project root workspace')
     deletedWorktreeId = result.worktree.id
     await expect(runtime.removeManagedWorktree(`id:${result.worktree.id}`)).resolves.toEqual({})
-    expect(localProvider.shutdown).toHaveBeenCalledWith(`${result.worktree.id}@@pty-1`, {
-      immediate: true
-    })
+    expect(localProvider.shutdown).toHaveBeenCalledWith(
+      `${result.worktree.id}@@pty-1`,
+      expect.objectContaining({ immediate: true })
+    )
     expect(metaById[result.worktree.id]).toBeUndefined()
     expect(deleteWorktreeHistoryDirMock).toHaveBeenCalledWith(result.worktree.id)
     expect(notifier.worktreesChanged).toHaveBeenCalledWith('folder-repo')
@@ -5140,7 +5145,10 @@ describe('OrcaRuntimeService', () => {
     }
 
     expect(gitProvider.removeWorktree).toHaveBeenCalledWith('/remote/feature', true)
-    expect(ptyProvider.shutdown).toHaveBeenCalledWith('pty-remote', { immediate: true })
+    expect(ptyProvider.shutdown).toHaveBeenCalledWith(
+      'pty-remote',
+      expect.objectContaining({ immediate: true })
+    )
     expect(ptyProvider.shutdown.mock.invocationCallOrder[0]).toBeLessThan(
       gitProvider.removeWorktree.mock.invocationCallOrder[0]
     )
@@ -25125,6 +25133,39 @@ describe('OrcaRuntimeService', () => {
     await expect(stopping).resolves.toEqual({ stopped: 1 })
   })
 
+  it('passes a margin-adjusted RPC deadline into stopAndWait for destructive teardown', async () => {
+    const runtime = new OrcaRuntimeService(store)
+    const stopAndWait = vi.fn(async () => true)
+    runtime.setPtyController({
+      write: () => true,
+      kill: vi.fn(() => true),
+      stopAndWait,
+      getForegroundProcess: async () => null
+    })
+    syncSinglePty(runtime)
+    const stopPty = vi.fn(async (_ptyId: string, stop: () => boolean | Promise<boolean>) => ({
+      stopped: await stop(),
+      owner: true
+    }))
+
+    // Why: the runtime-graph sweep must bound the underlying shutdown/list RPCs
+    // below the sweep deadline, or a wedged daemon trips the outer sweep deadline.
+    const deadline = Date.now() + WORKTREE_PROCESS_SWEEP_TIMEOUT_MS
+    await expect(
+      runtime.stopTerminalsForWorktree(`id:${TEST_WORKTREE_ID}`, { deadline, stopPty })
+    ).resolves.toEqual({ stopped: 1 })
+
+    expect(stopAndWait).toHaveBeenCalledTimes(1)
+    const [ptyId, opts] = stopAndWait.mock.calls[0] as unknown as [
+      string,
+      { deadlineMs?: number } | undefined
+    ]
+    expect(ptyId).toBe('pty-1')
+    // Pin the margin: RPCs must settle WORKTREE_TEARDOWN_RPC_MARGIN_MS before the
+    // sweep deadline so the accurate stop failure outruns the sweep-timeout error.
+    expect(opts?.deadlineMs).toBe(deadline - WORKTREE_TEARDOWN_RPC_MARGIN_MS)
+  })
+
   it('fails terminal listing closed if the graph reloads during selector resolution', async () => {
     const runtime = new OrcaRuntimeService(store)
 
@@ -31076,7 +31117,11 @@ describe('OrcaRuntimeService', () => {
     syncSinglePty(runtime, 'pty-1')
     vi.mocked(removeWorktree).mockResolvedValue({})
     removeWorktreeLinkedPathsMock.mockImplementationOnce(async () => {
-      expect(stopAndWait).toHaveBeenCalledWith('pty-1')
+      // Destructive teardown must bound the underlying RPCs below the sweep deadline.
+      expect(stopAndWait).toHaveBeenCalledWith(
+        'pty-1',
+        expect.objectContaining({ deadlineMs: expect.any(Number) })
+      )
     })
 
     await runtime.removeManagedWorktree(TEST_WORKTREE_ID)
@@ -32849,7 +32894,11 @@ describe('OrcaRuntimeService', () => {
 
       await runtime.removeManagedWorktree(TEST_WORKTREE_ID)
 
-      expect(stopAndWait).toHaveBeenCalledWith('pty-1')
+      // Destructive teardown must bound the underlying RPCs below the sweep deadline.
+      expect(stopAndWait).toHaveBeenCalledWith(
+        'pty-1',
+        expect.objectContaining({ deadlineMs: expect.any(Number) })
+      )
       // The provider-prefix sweep and the git removal must happen AFTER the
       // runtime-graph physical stop. Git removal must NOT start before it.
       const preflightIdx = callOrder.indexOf('preflight')
@@ -32908,9 +32957,10 @@ describe('OrcaRuntimeService', () => {
 
       // The post-daemon provider's prefix-matching session must have been
       // shut down, proving the thunk resolved lazily at call time.
-      expect(postDaemonProvider.shutdown).toHaveBeenCalledWith(`${TEST_WORKTREE_ID}@@aaaaaaaa`, {
-        immediate: true
-      })
+      expect(postDaemonProvider.shutdown).toHaveBeenCalledWith(
+        `${TEST_WORKTREE_ID}@@aaaaaaaa`,
+        expect.objectContaining({ immediate: true })
+      )
       expect(onPtyStopped).toHaveBeenCalledWith(`${TEST_WORKTREE_ID}@@aaaaaaaa`)
       // The pre-daemon provider must not have been consulted for the kill.
       expect(preDaemonProvider.shutdown).not.toHaveBeenCalled()
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 988e5dc21c9..112e5388bfd 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -750,7 +750,7 @@ import {
   getTerminalViewAttributes,
   registerTerminalViewAttributesApplier
 } from './terminal-view-attribute-store'
-import { killAllProcessesForWorktree } from './worktree-teardown'
+import { killAllProcessesForWorktree, teardownRpcDeadline } from './worktree-teardown'
 import {
   MobileNotificationReplayBuffer,
   type ReplayableMobileNotification
@@ -1259,7 +1259,10 @@ type RuntimePtyController = {
   }): Promise<{ id: string; wslDistro?: string }>
   write(ptyId: string, data: string): boolean
   kill(ptyId: string): boolean
-  stopAndWait?(ptyId: string, opts?: { keepHistory?: boolean }): Promise<boolean>
+  stopAndWait?(
+    ptyId: string,
+    opts?: { keepHistory?: boolean; deadlineMs?: number }
+  ): Promise<boolean>
   getCwd?(ptyId: string): Promise<string | null>
   getForegroundProcess(ptyId: string): Promise<string | null>
   confirmForegroundProcess?(ptyId: string): Promise<string | null>
@@ -20435,6 +20438,16 @@ export class OrcaRuntimeService {
         if (options.stopPty) {
           // Why: destructive worktree cleanup must not let its cross-surface
           // dedupe treat fire-and-forget controller.kill as physical exit.
+          // Why: the RPC deadline makes shutdown/list RPCs settle before the sweep
+          // deadline so a wedged daemon yields the accurate stop failure; no deadline
+          // (non-destructive) keeps the provider default RPC timeout.
+          if (options.deadline !== undefined) {
+            return (
+              this.ptyController?.stopAndWait?.(ptyId, {
+                deadlineMs: teardownRpcDeadline(options.deadline)
+              }) ?? false
+            )
+          }
           return this.ptyController?.stopAndWait?.(ptyId) ?? false
         }
         return Boolean(this.ptyController?.kill(ptyId))
diff --git a/src/main/runtime/worktree-teardown.test.ts b/src/main/runtime/worktree-teardown.test.ts
index 102c47465b4..d7b1af11849 100644
--- a/src/main/runtime/worktree-teardown.test.ts
+++ b/src/main/runtime/worktree-teardown.test.ts
@@ -10,6 +10,7 @@ vi.mock('../memory/pty-registry', () => ({
 
 import { killAllProcessesForWorktree, WORKTREE_PROCESS_SWEEP_TIMEOUT_MS } from './worktree-teardown'
 import type { IPtyProvider, PtyProcessInfo } from '../providers/types'
+import { DaemonPtyAdapter } from '../daemon/daemon-pty-adapter'
 
 function createProviderStub(listProcesses: () => Promise<PtyProcessInfo[]>): IPtyProvider {
   return {
@@ -59,10 +60,22 @@ describe('killAllProcessesForWorktree', () => {
     expect(result.providerStopped).toBe(1)
     expect(result.registryStopped).toBe(1)
 
-    expect(localProvider.shutdown).toHaveBeenCalledWith('w1@@abcd1234', { immediate: true })
-    expect(localProvider.shutdown).toHaveBeenCalledWith('w1-registry-1', { immediate: true })
-    expect(localProvider.shutdown).not.toHaveBeenCalledWith('w2@@efef5678', { immediate: true })
-    expect(localProvider.shutdown).not.toHaveBeenCalledWith('w2-registry-2', { immediate: true })
+    expect(localProvider.shutdown).toHaveBeenCalledWith(
+      'w1@@abcd1234',
+      expect.objectContaining({ immediate: true })
+    )
+    expect(localProvider.shutdown).toHaveBeenCalledWith(
+      'w1-registry-1',
+      expect.objectContaining({ immediate: true })
+    )
+    expect(localProvider.shutdown).not.toHaveBeenCalledWith(
+      'w2@@efef5678',
+      expect.objectContaining({ immediate: true })
+    )
+    expect(localProvider.shutdown).not.toHaveBeenCalledWith(
+      'w2-registry-2',
+      expect.objectContaining({ immediate: true })
+    )
     expect(onPtyStopped).toHaveBeenCalledWith('w1@@abcd1234')
     expect(onPtyStopped).toHaveBeenCalledWith('w1-registry-1')
     expect(onPtyStopped).not.toHaveBeenCalledWith('w2@@efef5678')
@@ -85,7 +98,10 @@ describe('killAllProcessesForWorktree', () => {
     // Prefix sweep must kill nothing; registry sweep must still fire.
     expect(result.providerStopped).toBe(0)
     expect(result.registryStopped).toBe(1)
-    expect(localProvider.shutdown).toHaveBeenCalledWith('1', { immediate: true })
+    expect(localProvider.shutdown).toHaveBeenCalledWith(
+      '1',
+      expect.objectContaining({ immediate: true })
+    )
     expect(localProvider.shutdown).toHaveBeenCalledTimes(1)
     expect(onPtyStopped).toHaveBeenCalledWith('1')
   })
@@ -103,11 +119,18 @@ describe('killAllProcessesForWorktree', () => {
       requirePhysicalStop: true
     })
 
-    expect(localProvider.shutdown).toHaveBeenCalledWith('floating-1', { immediate: true })
-    expect(localProvider.shutdown).toHaveBeenCalledWith('repo-1::/repo/app@@legacy-3', {
-      immediate: true
-    })
-    expect(localProvider.shutdown).not.toHaveBeenCalledWith('outside-2', { immediate: true })
+    expect(localProvider.shutdown).toHaveBeenCalledWith(
+      'floating-1',
+      expect.objectContaining({ immediate: true })
+    )
+    expect(localProvider.shutdown).toHaveBeenCalledWith(
+      'repo-1::/repo/app@@legacy-3',
+      expect.objectContaining({ immediate: true })
+    )
+    expect(localProvider.shutdown).not.toHaveBeenCalledWith(
+      'outside-2',
+      expect.objectContaining({ immediate: true })
+    )
     expect(result.providerStopped).toBe(2)
   })
 
@@ -146,9 +169,18 @@ describe('killAllProcessesForWorktree', () => {
       requirePhysicalStop: true
     })
 
-    expect(remoteProvider.shutdown).toHaveBeenCalledWith('pty-remote', { immediate: true })
-    expect(remoteProvider.shutdown).not.toHaveBeenCalledWith('pty-sibling', { immediate: true })
-    expect(remoteProvider.shutdown).not.toHaveBeenCalledWith('local-1', { immediate: true })
+    expect(remoteProvider.shutdown).toHaveBeenCalledWith(
+      'pty-remote',
+      expect.objectContaining({ immediate: true })
+    )
+    expect(remoteProvider.shutdown).not.toHaveBeenCalledWith(
+      'pty-sibling',
+      expect.objectContaining({ immediate: true })
+    )
+    expect(remoteProvider.shutdown).not.toHaveBeenCalledWith(
+      'local-1',
+      expect.objectContaining({ immediate: true })
+    )
     expect(listRegisteredPtysMock).not.toHaveBeenCalled()
     expect(result).toEqual({ runtimeStopped: 0, providerStopped: 1, registryStopped: 0 })
   })
@@ -197,12 +229,18 @@ describe('killAllProcessesForWorktree', () => {
     listRegisteredPtysMock.mockReturnValue([])
 
     const r1 = await killAllProcessesForWorktree('w1', { localProvider: providerA })
-    expect(providerA.shutdown).toHaveBeenCalledWith('w1@@aaaa', { immediate: true })
+    expect(providerA.shutdown).toHaveBeenCalledWith(
+      'w1@@aaaa',
+      expect.objectContaining({ immediate: true })
+    )
     expect(providerB.shutdown).not.toHaveBeenCalled()
     expect(r1.providerStopped).toBe(1)
 
     const r2 = await killAllProcessesForWorktree('w1', { localProvider: providerB })
-    expect(providerB.shutdown).toHaveBeenCalledWith('w1@@bbbb', { immediate: true })
+    expect(providerB.shutdown).toHaveBeenCalledWith(
+      'w1@@bbbb',
+      expect.objectContaining({ immediate: true })
+    )
     expect(providerB.shutdown).toHaveBeenCalledTimes(1)
     expect(r2.providerStopped).toBe(1)
   })
@@ -301,7 +339,10 @@ describe('killAllProcessesForWorktree', () => {
     const result = await killAllProcessesForWorktree('w1', { localProvider })
 
     expect(localProvider.shutdown).toHaveBeenCalledTimes(1)
-    expect(localProvider.shutdown).toHaveBeenCalledWith('w1@@same', { immediate: true })
+    expect(localProvider.shutdown).toHaveBeenCalledWith(
+      'w1@@same',
+      expect.objectContaining({ immediate: true })
+    )
     expect(result.providerStopped + result.registryStopped).toBe(1)
   })
 
@@ -422,6 +463,93 @@ describe('killAllProcessesForWorktree', () => {
     }
   })
 
+  // Why: on win32 the DaemonPtyAdapter is the local provider, so an unbounded
+  // kill RPC (30s default > the 10s sweep deadline) let the outer deadline win
+  // with the confusing "Timed out waiting for physical PTY teardown" instead of
+  // the accurate stop failure. The bound must fire first (native-Windows regression).
+  it('destructive teardown surfaces a bounded stop failure when the daemon kill RPC never replies (#9500 regression)', async () => {
+    vi.useFakeTimers()
+    try {
+      const worktreeId = 'w1'
+      const sessionId = 'w1@@dead0001'
+      let killRequests = 0
+
+      // A fake daemon RPC client standing in for a wedged daemon: it answers
+      // listSessions (so the session is discovered as owned) but never sends a
+      // reply to 'kill'. It faithfully models the real DaemonClient.request
+      // contract — a request is only bounded by its own timeoutMs, which
+      // defaults to REQUEST_TIMEOUT_MS (30_000). The adapter's shutdown passes
+      // no override, so the kill can only settle after 30s: long past the 10s
+      // sweep deadline.
+      const DAEMON_DEFAULT_REQUEST_TIMEOUT_MS = 30_000
+      const fakeClient = {
+        onDisconnected: () => () => {},
+        onEvent: () => () => {},
+        ensureConnected: async () => {},
+        // Why: bounded teardown connects via ensureConnectedWithin; model the real
+        // DaemonClient method so the shared connect+RPC budget path is exercised.
+        ensureConnectedWithin: async () => {},
+        isConnected: () => true,
+        disconnect: () => {},
+        notify: () => {},
+        request: (
+          type: string,
+          _payload?: unknown,
+          timeoutMs = DAEMON_DEFAULT_REQUEST_TIMEOUT_MS
+        ): Promise<unknown> => {
+          if (type === 'listSessions') {
+            return Promise.resolve({
+              sessions: [{ sessionId, isAlive: true, cwd: '/tmp/w1' }]
+            })
+          }
+          if (type === 'kill') {
+            killRequests += 1
+            // The daemon never replies; the request only rejects when its own
+            // timeout elapses, exactly like the real client.
+            return new Promise((_resolve, reject) => {
+              setTimeout(() => reject(new Error(`Request kill timed out after ${timeoutMs}ms`)), timeoutMs)
+            })
+          }
+          return Promise.resolve({})
+        }
+      }
+
+      const adapter = new DaemonPtyAdapter({ socketPath: '/tmp/sock', tokenPath: '/tmp/tok' })
+      ;(adapter as unknown as { client: typeof fakeClient }).client = fakeClient
+
+      listRegisteredPtysMock.mockReturnValue([])
+
+      // Capture the rejection as a value so a wrong error is a clean assertion
+      // failure below rather than a floating unhandled rejection while fake
+      // timers fire.
+      const outcome = killAllProcessesForWorktree(worktreeId, {
+        localProvider: adapter as unknown as IPtyProvider,
+        includeLocalRegistry: false,
+        requirePhysicalStop: true,
+        timeoutMs: WORKTREE_PROCESS_SWEEP_TIMEOUT_MS
+      }).then(
+        () => {
+          throw new Error('teardown unexpectedly resolved')
+        },
+        (error: Error) => error
+      )
+
+      // Advance past the daemon's 8s physical-exit budget AND the 10s sweep
+      // deadline. A bounded adapter shutdown would have rejected inside this
+      // window, letting the sweep report a clean stop failure. Today nothing
+      // settles before the deadline, so the sweep throws its deadline error.
+      await vi.advanceTimersByTimeAsync(WORKTREE_PROCESS_SWEEP_TIMEOUT_MS)
+
+      const error = await outcome
+      expect(killRequests).toBeGreaterThan(0)
+      // Why: the adapter bounds its kill RPC below the sweep deadline, so a wedged
+      // daemon yields the accurate stop failure — not the confusing deadline error.
+      expect(error.message).toContain('Failed to physically stop every PTY')
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it('tolerates runtime.stopTerminalsForWorktree throwing (headless assertGraphReady reject)', async () => {
     const stopTerminalsForWorktree = vi.fn().mockRejectedValue(new Error('runtime_unavailable'))
     const runtime = {
@@ -478,7 +606,10 @@ describe('killAllProcessesForWorktree', () => {
         providerStopped: 0,
         registryStopped: 1
       })
-      expect(localProvider.shutdown).toHaveBeenCalledWith('registry-1', { immediate: true })
+      expect(localProvider.shutdown).toHaveBeenCalledWith(
+        'registry-1',
+        expect.objectContaining({ immediate: true })
+      )
       expect(vi.getTimerCount()).toBe(0)
     } finally {
       vi.useRealTimers()
diff --git a/src/main/runtime/worktree-teardown.ts b/src/main/runtime/worktree-teardown.ts
index c54b6863208..77ebaa8737a 100644
--- a/src/main/runtime/worktree-teardown.ts
+++ b/src/main/runtime/worktree-teardown.ts
@@ -26,6 +26,18 @@ export type WorktreeTeardownResult = {
 
 export const WORKTREE_PROCESS_SWEEP_TIMEOUT_MS = 10_000
 
+// Why: margin so a bounded daemon RPC rejects BEFORE the sweep deadline and its
+// rejection can propagate — otherwise the outer deadline wins with a confusing
+// "Timed out waiting for physical PTY teardown" instead of the accurate stop failure.
+export const WORKTREE_TEARDOWN_RPC_MARGIN_MS = 500
+
+// Absolute deadline (epoch ms) threaded into provider RPCs on the destructive
+// path; each RPC leaf converts it to the remaining time when it actually issues,
+// so sequential RPCs share one budget without any relative-timeout bookkeeping.
+export function teardownRpcDeadline(sweepDeadline: number): number {
+  return sweepDeadline - WORKTREE_TEARDOWN_RPC_MARGIN_MS
+}
+
 /**
  * Kills every PTY we can prove belongs to `worktreeId`, across all three
  * registration surfaces (renderer graph, installed PTY provider session list,
@@ -197,9 +209,10 @@ async function sweepProviderByPrefix(
   failClosed = false
 ): Promise<number> {
   const prefix = `${worktreeId}@@`
+  const rpcDeadline = teardownRpcDeadline(deadline)
   const sessions = failClosed
-    ? await provider.listProcesses()
-    : await provider.listProcesses().catch(() => [])
+    ? await provider.listProcesses({ deadlineMs: rpcDeadline })
+    : await provider.listProcesses({ deadlineMs: rpcDeadline }).catch(() => [])
   const ownedSessions = sessions.filter((session) => {
     // Why: older daemon/relay process rows may omit cwd; their established ID
     // and authoritative worktree ownership must remain usable during teardown.
@@ -225,7 +238,7 @@ async function sweepProviderByPrefix(
           return false
         }
         try {
-          await provider.shutdown(session.id, { immediate: true })
+          await provider.shutdown(session.id, { immediate: true, deadlineMs: rpcDeadline })
           return Date.now() < deadline
         } catch {
           return false
@@ -251,6 +264,7 @@ async function sweepRegistryForWorktree(
   ) => Promise<{ stopped: boolean; owner: boolean }>,
   onPtyStopped?: (ptyId: string) => void
 ): Promise<number> {
+  const rpcDeadline = teardownRpcDeadline(deadline)
   const entries = listRegisteredPtys().filter((r) => r.worktreeId === worktreeId)
   const stopped = await mapWithConcurrency(
     entries,
@@ -264,7 +278,7 @@ async function sweepRegistryForWorktree(
           return false
         }
         try {
-          await localProvider.shutdown(entry.ptyId, { immediate: true })
+          await localProvider.shutdown(entry.ptyId, { immediate: true, deadlineMs: rpcDeadline })
           return Date.now() < deadline
         } catch {
           return false

From 904762fa96d8ecadf0b9f4a75402dc362f10ce7a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Mon, 20 Jul 2026 07:22:55 +0000
Subject: [PATCH 36/54] Update README downloads badge

---
 docs/assets/readme-downloads.svg | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/assets/readme-downloads.svg b/docs/assets/readme-downloads.svg
index 1825ee96d32..4fdfa604199 100644
--- a/docs/assets/readme-downloads.svg
+++ b/docs/assets/readme-downloads.svg
@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="113" height="20" role="img" aria-label="downloads: 6.5m">
-  <title>downloads: 6.5m</title>
+<svg xmlns="http://www.w3.org/2000/svg" width="113" height="20" role="img" aria-label="downloads: 6.6m">
+  <title>downloads: 6.6m</title>
   <linearGradient id="s" x2="0" y2="100%">
     <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
     <stop offset="1" stop-opacity=".1"/>
@@ -15,7 +15,7 @@
   <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="11">
     <text x="37" y="15" fill="#010101" fill-opacity=".3">downloads</text>
     <text x="37" y="14">downloads</text>
-    <text x="93.5" y="15" fill="#010101" fill-opacity=".3">6.5m</text>
-    <text x="93.5" y="14">6.5m</text>
+    <text x="93.5" y="15" fill="#010101" fill-opacity=".3">6.6m</text>
+    <text x="93.5" y="14">6.6m</text>
   </g>
 </svg>

From 4d49b9342dcadc935a9a27c2c11c7476c9f2b0bf Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Mon, 20 Jul 2026 03:26:40 -0400
Subject: [PATCH 37/54] fix(wsl): forward ORCA_ROOT_PATH/ORCA_WORKTREE_PATH
 setup vars across the wsl.exe boundary (#9206) (#9390)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(wsl): forward ORCA_ROOT_PATH/ORCA_WORKTREE_PATH and setup vars across the wsl.exe boundary (#9206)

Worktree setup scripts running under WSL saw empty ORCA_ROOT_PATH /
ORCA_WORKTREE_PATH ("cp: cannot stat /.env"): the vars were set on the
Windows-side spawn env, but wsl.exe only imports Windows env vars listed
in WSLENV, and the addOrcaWslInteropEnv allowlist omitted them.

Register ORCA_ROOT_PATH, ORCA_WORKTREE_PATH, and the CONDUCTOR/GHOSTX
compat aliases with a per-value flag (same pattern as
ORCA_AGENT_HOOK_ENDPOINT): /u when hooks.ts already Linux-translated the
value for a WSL worktree (a /p flag would double-translate and corrupt
it), /p when a wsl.exe terminal runs over a Windows worktree and the
value is still a C:\ path WSLENV must translate. ORCA_WORKSPACE_NAME is
a display name, never a path, so it is always /u.

* fix(wsl): populate WSLENV for runHook's direct wsl.exe invocations (#9206)

runHook spawns wsl.exe via execFile for archive hooks and for setup when
no renderer window exists (headless/CLI/RPC/mobile-created worktrees).
It set ORCA_ROOT_PATH etc. on the execFile env, but wsl.exe only imports
Windows env vars named in WSLENV, so the guest never saw them. Register
the setup vars in WSLENV via a helper factored out of the PTY path's
addOrcaWslInteropEnv, so the per-value /u-vs-/p flag decision stays in
one place. Also make the runHook WSL test assert on captured execFile
options after the promise resolves — expects thrown inside the mock were
swallowed by runHook's own error handling.
---
 src/main/hooks.test.ts            | 41 +++++++++++++----
 src/main/hooks.ts                 | 11 ++++-
 src/main/pty/wsl-orca-env.test.ts | 76 ++++++++++++++++++++++++++++++-
 src/main/pty/wsl-orca-env.ts      | 47 +++++++++++++++----
 4 files changed, 153 insertions(+), 22 deletions(-)

diff --git a/src/main/hooks.test.ts b/src/main/hooks.test.ts
index 9e945322fa4..d117470bffe 100644
--- a/src/main/hooks.test.ts
+++ b/src/main/hooks.test.ts
@@ -979,18 +979,12 @@ describe('runHook', () => {
   it('runs Windows-path hooks through WSL when the project runtime targets WSL', async () => {
     execMock.mockReset()
     execFileMock.mockReset()
+    // Why: assert on the captured options after runHook resolves — an expect()
+    // thrown inside the mock is swallowed by runHook's own error handling.
+    let capturedOptions: unknown
     execFileMock.mockImplementation((_file, _args, options, callback) => {
+      capturedOptions = options
       callback?.(null, '', '')
-      expect(options).toEqual(
-        expect.objectContaining({
-          env: expect.objectContaining({
-            ORCA_ROOT_PATH: '/mnt/c/Users/jinwo/git/orca',
-            ORCA_WORKTREE_PATH: '/mnt/c/Users/jinwo/git/orca-feature',
-            CONDUCTOR_ROOT_PATH: '/mnt/c/Users/jinwo/git/orca',
-            GHOSTX_ROOT_PATH: '/mnt/c/Users/jinwo/git/orca'
-          })
-        })
-      )
       return {} as never
     })
 
@@ -1003,6 +997,9 @@ describe('runHook', () => {
       configurable: true,
       value: 'win32'
     })
+    // Why: keep the WSLENV assertion hermetic on hosts that export WSLENV.
+    const originalWslenv = process.env.WSLENV
+    delete process.env.WSLENV
 
     try {
       const { runHook } = await import('./hooks')
@@ -1031,12 +1028,36 @@ describe('runHook', () => {
         expect.any(Object),
         expect.any(Function)
       )
+      expect(capturedOptions).toEqual(
+        expect.objectContaining({
+          env: expect.objectContaining({
+            ORCA_ROOT_PATH: '/mnt/c/Users/jinwo/git/orca',
+            ORCA_WORKTREE_PATH: '/mnt/c/Users/jinwo/git/orca-feature',
+            CONDUCTOR_ROOT_PATH: '/mnt/c/Users/jinwo/git/orca',
+            GHOSTX_ROOT_PATH: '/mnt/c/Users/jinwo/git/orca',
+            // Why: wsl.exe only imports Windows env vars named in WSLENV, so
+            // setting the vars on the execFile env alone is not enough (#9206).
+            // /u because runHook pre-translated the values to Linux paths.
+            // stringContaining, not exact: promptGuardShellEnv (#7652) appends
+            // its own guard keys (GIT_TERMINAL_PROMPT, …) after these — the
+            // setup vars must remain registered alongside them.
+            WSLENV: expect.stringContaining(
+              'ORCA_ROOT_PATH/u:ORCA_WORKTREE_PATH/u:CONDUCTOR_ROOT_PATH/u:GHOSTX_ROOT_PATH/u:ORCA_WORKSPACE_NAME/u'
+            )
+          })
+        })
+      )
       expect(execMock).not.toHaveBeenCalled()
     } finally {
       Object.defineProperty(process, 'platform', {
         configurable: true,
         value: originalPlatform
       })
+      if (originalWslenv === undefined) {
+        delete process.env.WSLENV
+      } else {
+        process.env.WSLENV = originalWslenv
+      }
     }
   })
 
diff --git a/src/main/hooks.ts b/src/main/hooks.ts
index e93fa2f033c..93a5b5424e1 100644
--- a/src/main/hooks.ts
+++ b/src/main/hooks.ts
@@ -10,6 +10,7 @@ import { TERMINAL_GIT_CREDENTIAL_GUARD_POLICY_ENV } from '../shared/terminal-git
 import { parseOrcaYaml } from '../shared/orca-yaml'
 import { gitExecFileSync, promptGuardShellEnv } from './git/runner'
 import { isWslPath, parseWslPath, toWindowsWslPath, toLinuxPath } from './wsl'
+import { addWorktreeSetupWslInteropEnv } from './pty/wsl-orca-env'
 import type {
   HookCommandSourcePolicy,
   OrcaHooks,
@@ -601,6 +602,10 @@ export function runHook(
     for (const [key, value] of Object.entries(envVars)) {
       wslEnv[key] = toLinuxPath(value)
     }
+    const hookEnv: NodeJS.ProcessEnv = { ...process.env, ...wslEnv }
+    // Why: wsl.exe only imports Windows env vars named in WSLENV; without
+    // registering them the setup vars never reach the guest (#9206).
+    addWorktreeSetupWslInteropEnv(hookEnv)
 
     return new Promise((resolve) => {
       let child: ReturnType<typeof execFile> | null = null
@@ -645,8 +650,10 @@ export function runHook(
             // Why: same unattended-git guard as the non-WSL branch below
             // (issue #7652) — WSL repos are the likeliest to hit the GCM
             // popup, and the guard's WSLENV registration is what carries it
-            // across the wsl.exe boundary into the distro.
-            env: promptGuardShellEnv({ ...process.env, ...wslEnv })
+            // across the wsl.exe boundary. Wrap hookEnv (not a fresh env) so
+            // the setup-var WSLENV entries registered above (#9206) are kept —
+            // promptGuardShellEnv appends its own keys to the existing WSLENV.
+            env: promptGuardShellEnv(hookEnv)
           },
           (error, stdout, stderr) => {
             finish(error ?? null, stdout, stderr)
diff --git a/src/main/pty/wsl-orca-env.test.ts b/src/main/pty/wsl-orca-env.test.ts
index fe0d94ab9cb..cffab00395c 100644
--- a/src/main/pty/wsl-orca-env.test.ts
+++ b/src/main/pty/wsl-orca-env.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { addOrcaWslInteropEnv } from './wsl-orca-env'
+import { addOrcaWslInteropEnv, addWorktreeSetupWslInteropEnv } from './wsl-orca-env'
 
 describe('addOrcaWslInteropEnv', () => {
   it('marks the Orca terminal handle for Windows to WSL env import', () => {
@@ -65,9 +65,83 @@ describe('addOrcaWslInteropEnv', () => {
     expect(guestEnv.WSLENV).not.toContain('ORCA_AGENT_HOOK_ENDPOINT/p')
   })
 
+  it('tags pre-translated Linux setup paths /u so WSLENV does not translate them again (#9206)', () => {
+    const env: Record<string, string> = {
+      ORCA_ROOT_PATH: '/home/jin/repo',
+      ORCA_WORKTREE_PATH: '/home/jin/repo-worktrees/fix-1',
+      ORCA_WORKSPACE_NAME: 'fix-1',
+      CONDUCTOR_ROOT_PATH: '/home/jin/repo',
+      GHOSTX_ROOT_PATH: '/home/jin/repo'
+    }
+
+    addOrcaWslInteropEnv(env)
+
+    // /u (not /p): hooks.ts already converted these to Linux paths before
+    // spawn, so a /p flag would make WSLENV double-translate them.
+    expect(env.WSLENV).toContain('ORCA_ROOT_PATH/u')
+    expect(env.WSLENV).toContain('ORCA_WORKTREE_PATH/u')
+    expect(env.WSLENV).toContain('CONDUCTOR_ROOT_PATH/u')
+    expect(env.WSLENV).toContain('GHOSTX_ROOT_PATH/u')
+    expect(env.WSLENV).not.toContain('ORCA_ROOT_PATH/p')
+    expect(env.WSLENV).not.toContain('ORCA_WORKTREE_PATH/p')
+    // The value itself must stay the already-Linux path.
+    expect(env.ORCA_ROOT_PATH).toBe('/home/jin/repo')
+    expect(env.ORCA_WORKTREE_PATH).toBe('/home/jin/repo-worktrees/fix-1')
+  })
+
+  it('tags untranslated Windows setup paths /p so WSLENV translates them (wsl.exe shell over a Windows worktree)', () => {
+    const env: Record<string, string> = {
+      ORCA_ROOT_PATH: 'C:\\Users\\jin\\repo',
+      ORCA_WORKTREE_PATH: 'C:\\Users\\jin\\repo-worktrees\\fix-1',
+      CONDUCTOR_ROOT_PATH: 'C:\\Users\\jin\\repo',
+      GHOSTX_ROOT_PATH: 'C:\\Users\\jin\\repo'
+    }
+
+    addOrcaWslInteropEnv(env)
+
+    expect(env.WSLENV).toContain('ORCA_ROOT_PATH/p')
+    expect(env.WSLENV).toContain('ORCA_WORKTREE_PATH/p')
+    expect(env.WSLENV).toContain('CONDUCTOR_ROOT_PATH/p')
+    expect(env.WSLENV).toContain('GHOSTX_ROOT_PATH/p')
+    expect(env.WSLENV).not.toContain('ORCA_ROOT_PATH/u')
+    expect(env.WSLENV).not.toContain('ORCA_WORKTREE_PATH/u')
+  })
+
+  it('always tags ORCA_WORKSPACE_NAME /u because it is a name, not a path', () => {
+    const env: Record<string, string> = { ORCA_WORKSPACE_NAME: 'fix-1' }
+
+    addOrcaWslInteropEnv(env)
+
+    expect(env.WSLENV).toBe('ORCA_WORKSPACE_NAME/u')
+  })
+
+  it('does not register setup vars that are absent from the env', () => {
+    const env: Record<string, string> = { ORCA_TERMINAL_HANDLE: 'term_wsl' }
+
+    addOrcaWslInteropEnv(env)
+
+    expect(env.WSLENV).toBe('ORCA_TERMINAL_HANDLE/u')
+  })
+
   it('marks the WSL hook relay version for import on relay spawn envs', () => {
     const env: Record<string, string> = { ORCA_WSL_HOOK_RELAY_VERSION: '0.1.0+abc' }
     addOrcaWslInteropEnv(env)
     expect(env.WSLENV).toBe('ORCA_WSL_HOOK_RELAY_VERSION/u')
   })
 })
+
+describe('addWorktreeSetupWslInteropEnv', () => {
+  it('registers only setup vars, sharing the /u-vs-/p flag logic with the PTY path (#9206)', () => {
+    const env: Record<string, string | undefined> = {
+      ORCA_ROOT_PATH: '/mnt/c/Users/jin/repo',
+      ORCA_WORKTREE_PATH: 'C:\\Users\\jin\\repo-worktrees\\fix-1',
+      ORCA_WORKSPACE_NAME: 'fix-1',
+      // Terminal-only vars must not leak into runHook's WSLENV.
+      ORCA_TERMINAL_HANDLE: 'term_wsl'
+    }
+
+    addWorktreeSetupWslInteropEnv(env)
+
+    expect(env.WSLENV).toBe('ORCA_ROOT_PATH/u:ORCA_WORKTREE_PATH/p:ORCA_WORKSPACE_NAME/u')
+  })
+})
diff --git a/src/main/pty/wsl-orca-env.ts b/src/main/pty/wsl-orca-env.ts
index 3f136e0a284..d053fbad948 100644
--- a/src/main/pty/wsl-orca-env.ts
+++ b/src/main/pty/wsl-orca-env.ts
@@ -14,8 +14,42 @@ function upsertWslenvEntry(entries: string[], entry: string): void {
   entries[existingIndex] = entry
 }
 
-export function addOrcaWslInteropEnv(env: Record<string, string>): void {
+function applyWslenvPassthrough(
+  env: Record<string, string | undefined>,
+  passthroughEntries: string[]
+): void {
   const entries = parseWslenvEntries(env.WSLENV)
+  for (const entry of passthroughEntries) {
+    const variableName = entry.split('/')[0]
+    if (env[variableName]) {
+      upsertWslenvEntry(entries, entry)
+    }
+  }
+  env.WSLENV = entries.join(WSLENV_ENTRY_SEPARATOR)
+}
+
+function worktreeSetupWslenvEntries(env: Record<string, string | undefined>): string[] {
+  return [
+    // Why: worktree setup/hook scripts read these (#9206). For WSL worktrees
+    // hooks.ts pre-translates the values to Linux paths (must cross untranslated,
+    // /u); a wsl.exe terminal over a Windows worktree still carries C:\ paths
+    // that WSLENV must translate (/p).
+    ...['ORCA_ROOT_PATH', 'ORCA_WORKTREE_PATH', 'CONDUCTOR_ROOT_PATH', 'GHOSTX_ROOT_PATH'].map(
+      (name) => `${name}/${env[name]?.startsWith('/') ? 'u' : 'p'}`
+    ),
+    // Why: a display name, never a path — never path-translate it.
+    'ORCA_WORKSPACE_NAME/u'
+  ]
+}
+
+// Why: runHook spawns wsl.exe directly (archive hooks, windowless setup), and
+// wsl.exe only imports Windows env vars named in WSLENV — so the setup vars
+// must be registered there too, with the same /u-vs-/p flags as the PTY path (#9206).
+export function addWorktreeSetupWslInteropEnv(env: Record<string, string | undefined>): void {
+  applyWslenvPassthrough(env, worktreeSetupWslenvEntries(env))
+}
+
+export function addOrcaWslInteropEnv(env: Record<string, string>): void {
   // Why: the endpoint is a Windows path (/p-translated so the guest reads it
   // via /mnt/c) until the WSL hook relay reports the guest home — then it is
   // already a guest-side POSIX path and must cross untranslated.
@@ -37,13 +71,8 @@ export function addOrcaWslInteropEnv(env: Record<string, string>): void {
     'ORCA_WSL_HOOK_RELAY_VERSION/u',
     'ORCA_WSL_HOOK_INSTANCE/u',
     'ORCA_OMP_SOURCE_AGENT_DIR/p',
-    'ORCA_OMP_STATUS_EXTENSION/p'
+    'ORCA_OMP_STATUS_EXTENSION/p',
+    ...worktreeSetupWslenvEntries(env)
   ]
-  for (const entry of passthroughEntries) {
-    const variableName = entry.split('/')[0]
-    if (env[variableName]) {
-      upsertWslenvEntry(entries, entry)
-    }
-  }
-  env.WSLENV = entries.join(WSLENV_ENTRY_SEPARATOR)
+  applyWslenvPassthrough(env, passthroughEntries)
 }

From f25fb9f400f95f477c8d369dc98a432234f6167f Mon Sep 17 00:00:00 2001
From: fsdwen <wen.xiaosong@xydigit.com>
Date: Mon, 20 Jul 2026 15:31:28 +0800
Subject: [PATCH 38/54] =?UTF-8?q?fix(i18n):=20=E6=93=8D=E4=BD=9C=E6=8C=89?=
 =?UTF-8?q?=E9=92=AE/=E6=8C=87=E4=BB=A4=E7=9A=84=E7=BF=BB=E8=AF=91"?=
 =?UTF-8?q?=E5=BC=80=E6=94=BE"=E6=94=B9=E4=B8=BA"=E6=89=93=E5=BC=80"=20(#9?=
 =?UTF-8?q?533)=20(#9534)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/renderer/src/i18n/locales/zh.json | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json
index 3938f0dad79..e54cec11c5b 100644
--- a/src/renderer/src/i18n/locales/zh.json
+++ b/src/renderer/src/i18n/locales/zh.json
@@ -1859,7 +1859,7 @@
         "ac037cfac2": "手机",
         "75499e01d9": "关闭",
         "66b5a67bee": "Esc键",
-        "45def60329": "开放",
+        "45def60329": "打开",
         "f65d992a11": "进入",
         "c5081f2814": "当前工作树",
         "52404f8096": "当前选项卡",
@@ -5355,7 +5355,7 @@
         "ComputerUsePane": {
           "1735461723": "使智能体能够检查和操作本地桌面应用程序。",
           "93255aaf18": "计算机控制技能",
-          "45f8e22c2e": "开放",
+          "45f8e22c2e": "打开",
           "d95d1cfab8": "刷新",
           "0c29da5805": "就绪",
           "3383ea1aab": "无法重置计算机使用权限",
@@ -9341,7 +9341,7 @@
             "37c875d827": "新文件",
             "b3e288bf41": "无法下载“{{value0}}”。",
             "f729bcd97d": "无法下载文件夹“{{value0}}”。",
-            "1a3df04ae1": "开放",
+            "1a3df04ae1": "打开",
             "bce4d4e44f": "下载“{{value0}}”",
             "a4029c996b": "已下载文件夹“{{value0}}”",
             "e26010014a": "被 .gitignore 忽略",
@@ -12298,7 +12298,7 @@
             "109a791e7b": "保存",
             "bb0a55f856": "保存…",
             "0203bed775": "取消",
-            "6978871a3d": "开放",
+            "6978871a3d": "打开",
             "cce596969e": "删除注释",
             "cad3384faa": "编辑备注",
             "508ee678a5": "在浏览器中打开"

From ddb5b930e12f006a2c905d91cf109994e053aa89 Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Mon, 20 Jul 2026 03:39:08 -0400
Subject: [PATCH 39/54] fix(rate-limits): surface Fable weekly usage when
 is_active is false (#8979) (#9389)

---
 .../8979-screenshots/after-fable-visible.png  | Bin 0 -> 30479 bytes
 .../8979-screenshots/before-fable-hidden.png  | Bin 0 -> 24212 bytes
 docs/claude-scoped-oauth-usage-limits.md      |  10 ++--
 src/main/rate-limits/claude-fetcher.test.ts   |  44 +++++++++++++++++-
 src/main/rate-limits/claude-fetcher.ts        |   3 +-
 5 files changed, 49 insertions(+), 8 deletions(-)
 create mode 100644 docs/bug-reproductions/8979-screenshots/after-fable-visible.png
 create mode 100644 docs/bug-reproductions/8979-screenshots/before-fable-hidden.png

diff --git a/docs/bug-reproductions/8979-screenshots/after-fable-visible.png b/docs/bug-reproductions/8979-screenshots/after-fable-visible.png
new file mode 100644
index 0000000000000000000000000000000000000000..0e8d49a8e34a75591b4a60bb417943393612b4da
GIT binary patch
literal 30479
zcmdSBRa72Pv?iF~?ivX0?(UG_4grEoAh-sC2l%nzPH+ek2u^T!hd^+5cX#G+yYH;-
zwPw2et~D?76ao}gf7LmAf3_=BMM)YJ=?&7WSFccIWu(+zy@En`_3HHz0u=bp7i&|V
zSFbQ$$x4Z9d`&w@hxfwywA4!~fk2&oO_Al2VDK(C6oG-_Pz<v;1a_W&X?K57NBLd1
ze_8>ZBKQXtCwF%&VJRkmToCei@ct8ty`3xXtWE5qS=>X*nGS8$=#UWS`Oxz<D`!;&
zEHWOKCAs}l6H_d!VM`NQMMVWWJNtVCaw!*wt)U<41xo3zeC}r(V?U*T$ozYA2BAZt
z6VH|iM8cuNz{j_MU`UveDy8u`PP|S>$n)Oo_(p|8uLdy(N31HxZ{M7*7r%X1+2C?@
zphF1>p*fgLfkr5Em%TQYRp*tMl`CRY_(Cl{)mF)q)M=3hJ^Qw?ufnt!jhOG-B2RlQ
zi4=jhR)tA-F;y14tgP$@tZ)p9h8Q*~c^1r|HtsBp+w<+HsHoneDzcu3mG*$ISM)5Y
zv24-Y45~RW*5X)L*w|6T{A*W1{KYYd_m&V0)gTDDj#Cs{Ip0*O@*13=@wVv+GCqq9
z>V1p%Jpx&*p^%QTjEoG~2crlXsE!V~U6=}}{a7pn%tsl5SnBEbDC}qxum=i7&{F8d
zuWcRDeOTQs_jr+I=|29U!}h#BsvaamoM7?qdMgp~i=r1n@@s!uCstyKnHTjE_Y6!F
zGvZH-8RudF)tCEsllaDOx$>#wTR0ht6x=U={p3$nh!SS3R4Dzi)`9Ka0|Du6HR>E<
zBnSE>OXeaSVy6ung=#&axW!btADi$bq{y*?%wpKINBI7}I?l{`ZJRZ-;ytzM+aboE
zV>4SRMR<RGEP9kBCLUt*9eipk6qaPS_-{N4Gig|X(6x4_qQ>B3-kq#=Ue#z6`eV%E
zBT81v5H!`fC1Rm(jAoMFALHdbe@%sTmgR}z6L8sy)(}S^cY;p#sFa0AC!z8XgTjCk
zd`34euO+9Zp_%hki@=Zw(QBiJ4{yCK!ysTpF-yWgy0@t!vB3l1hZTqJA$1o+IEb^|
zhWH`)D;FWF!IDGz0*xNV;MRrS*cP+R&<~)=Q6Q2_u|OQ!KV;aZIg}D8%Fc;Y8-X>p
zA$K6CcD^-CgpZGJdf9%w3r7yYs7In|Yf+CPRx5s7efu5VLofsU;>YM$kT$-uwwv`}
z{=;PnaLvqDZ)LW9R(qc+qn1Lcz+uEh<Z0M&MC>vI5DbbWQ^sK_<ccfrHy-do;CQEE
zwzT{H&-b+qqY?-)gN}h@JqX}jBvdHiZ+S(tf&ZL{caT9aI^YolFeDI2|Jx5j>eyV$
zbiXV$>u2uF^x6B=cfghvs?UPo4&k6+LGf*DG9H6+Y~I(h)~JYgdrDo@ZT_lwPLm)<
z1pfG#R9B$!?3K4`j^WR}qahR6b*m)$o-X$0?~(}QIpNya#s&|@x4pbIQT=h-10NFx
zhMDRpPw6=2@feI+7yq!1DQPggc|JZW8NjD^8Sd+!$Bs(APy;(x@VKeUcD@FeL8II`
zl9<2p>*<>6&-dQ9n@K(qq#irjVJr<h6NT!Ag2_zOMFNzNzF{dU6S}vCWFklC{W=w<
z%hK{Z1lx~9ygWt57I>`5nWM|-#7Y8=EGED7m{#L_lC&5#b5-;XG^<BBcQ?E74b%9Y
zx7z%mttX2#Z(8G-b!$NVAoV(F?+V3^LAAdhWNm#2BC^~0SD@S(gsS)fTQeO~V#Az*
z0>%Ei>0tZ5QTXd@w|hG81!`*Z*~w{~!otiikHQ=03W-pOZJ)OY!z)!PEi<c&AMu=X
z*Jk?F|4rF*@2)MnEjQmEHHP6aTcz>(P*GEZ1xX^}HPeE}z{6AHeSgK;e1WBA43<%@
zf)u1Z2-)q=uk)o#TSgpumzAB+Rp$@vw7xb=uZOKuoolIZ*PJ&;puI%q3uQ0We6`Qv
zTT*J>pN->ONqiqpNrXK%hEtOgia%B(wKkgd$L7f=v1k_Ic(9rFpltX>2jcwurz~pw
z-%qtVYB)Myca4FK%9wb!w#6tg@r%vw^zLo&h$h+{S6!CPs{bYuzM042Q9vzE$?R@x
z{ZFl@s<q&VdBwRxohtJ(gXV)MtupP39Q);#C8v&u+w<p(0?`-~2~L&Bk#s>``z4`^
zggEcL#YVSA*F%Lm<8+rswLCfUngZ&>-BwJA5E(2?W9<sl=P#x$r1$3n`N-Q*M6Qc@
zQGZIFw-zQJ2$Oh^+qSCZyECzaW`x|I78*+R&7SNVmwvSN<RY&HoR5lThC;)mHQjEd
z{?;nHvKCX?O?O+Gt+GJ>_h}&B5<KRjeJLRth2%C0oYLNK!t=x0<=BK2VNciI$hXbI
z<rAqqwsXy%*Tp(j4^t<*1(`>#UoR)Mpr@Pcmqn&-mpqS4^c!7gD?jlrdpXMqlV4v>
zs4Lqp)SV_7`eX|a#!~CnIT%O31N)RxYR`2tu3%J%*L2r5^P!G*m%#VRR-;*Zv8ZO;
z;oY!YH`0db+U$tpnLsOP?}Ie$WBidJ<n!DgOTC5q9N1Vkr;R?dc_U@^;^gVe{b_tA
zZMGYvveu_NbkPTlWg&9%_H@~V9LMz@Q*h;MM&ATE4O_haw7cRnX!O}r4^>Rs6Aft7
z1yHIM&)O<uNOqk+oR7xcARQovMG^7ZovgIKY%<Y8GyM9UoG=6T%>>_vbyCnqI~2|A
zwbHBHEvCoRGxit$T*7YdYtmU-sQI=W_@8a*A>N^f-QE@Bf<24FjG<NL6}m?qror?^
z`IE`rooyz|GS0vUh7ZM`(@3**8(b`-&2fkn5RCG{rV{t8-7nQ|?2{W#7sQubDADCz
zi#6%~j{1gcCz#YnyVfpUR`7bkS^08rJ7b&g%ihG<=3vb4o12^8Wi2U}Ra<RWQbaC9
zvV5)wGZ(x65II!1)pWtZMr);wM{_l{^C6g&;TRH-s1VWK^5ec!zs%vie_3;e^OFTP
z#4{^HvsK$kOlOnKZ>{;LKPNp@uxBGc|M2jn#mY~72=8apZ*VD8U0<-R{?*ZZy|kam
z*mAeW*b&H}S)@^__k#x%f=XFRf(shO6r;^T2-sS^wTrH)>CfZxtlk%6(jQ(m9U`)V
zz9Z)KjiKpk&f3oF<Zi#L_4(-@XMPN8iryGpS`r&_r^Tb7(X#KXvxCLj*rIH2AEoM<
zu;blO24!zXX2nH|JS&3%UF$LhyZf2ma#l+ElFv?GQTjc-D$`tpMSo2*4KuN*Pa0QD
zKikghNFi+9TDwa|6Z@I+*T!VrF72@R$$y;tsgtx(e`c~ao%jo8Vj;x-`=$DGtvk$f
zz7~{LvwmmesT6K&4D@5IOy4Jd3AG$4#5E$Q$WUzBH{=imY-7A2%=2js;+1Qfji?g6
zVvSu0)H|duSVOa;t#o9c<z|m*zr6Wt5<ZWP+@$1W0&7>!K2NkI{saci4rlv+`HEnV
zMV#l77&OTWf-l1ytr+%+n+z3GxOT^+NiVVC&g5};l4qLSIoZEoGj{F%&6Y%feit%V
zZ7mPln=#c;$I0Rx^Mm}=?}2WtrQI*H?%h}qTZU@YOwS*V7c#%5eZQQA?o~Rmw^)mD
z4CAE|=-yjdvC9;4FD3l4Vzytq+u8DQy>gI+(ou@AjkP~cM2~;AaaxqXg!SrpIaBR^
zpIGf9?INcH0;ULsfhpVeQh5AxsXWWUzZL%`c6Mo{GzOgQsxd7eJ)eV#-9*g+u2KyF
za$ga*r_D*mr`<=(!qSKBOy8c|wZY!*?%6ppITTWnCQ$qM=IXZF8DUskZcLt^9-B{l
z0RXMFUsn2vQnoAwr)Es=-94q8cT&@iO{)Z>qk=#_E^Zb`F2Zs(m0xXV`LW8VWd`)B
zjB=Cn^rVT~FTN%TYtNpn-2o;0XqnAtBcm4UafaG8Uw?k5{+-0|QJ_U^=eS3^#zrRq
z4%K0AfAY8Vi16%vpiF)ATI)#%GW$`xJZ1nqdduV0JTe~B&JrJ&_npf|aM_akc6vF2
zWTlAD4~|c2R?2xPC*1%$=VP=_+tvR5@O1xLYjN?cV<tJ7ce{A+dTeOvl9kVKZ>SG;
z8|C^yQP8GpbN+hCdH0=f>)HbAZSg|=bMw3XXZBC4i`eGAHD1mkL>&&Kd=5v4Zzdp%
zy50|DP+4|EQfg}BIq$;!i%Y)jPhE)z)2ruaQA-A)R1_JdQHaaQ<I<~j9oO@>`oFfB
z`-7;%p>*1IoS=vkEuX-!IZYBM=)8r3U2QdacK^Lwhw7prKM;e$1vKFbcK4^H?A6wW
zTCi!Jn+!*V2iUwuittOVKGZm5TjVp>6y_G>vn;u7EL7P)&;B_N!%Z!-S2@gMVLt25
zEfD3Kn6a~A`4p6D-*THBOmb%Zw@|$Rp498_-7W-wy(a>>l83jd)q0xc_(AZfF5p{d
z*(pH#Hi192D@>9--F%Lhnr-vukW=3$CjT;M7H|x`{tdRgNVyn?+tC8J`yB1Avkljb
zc+V%D=!o7vkC$3kBj9G=^jX`7pbTQaV!0eh^2#w?f0T|C1$Qv|#~>Q9FngVCvo%XG
zhvlVx*{H$n?<H7nd3<-{t;#M_+Ih{gzgZIf&-X_K%<yq{yrrtGUZI7pHiEl#{g(b5
z(19ikS5UA>e=PsygFb(NPc8vK1_`K7qR+RZQwQVWdma9;$OmcwV+cP#oST}M91M%@
z41nT!cd=_q2@Np|fIi|k31DVX&4K8j0JPoccHF~aKU<k+Jzcsvknppkz37)@dC+TU
zxQFHEM?=sFZP%&g6TQxdd3!=%3Ai2UWlO;RDFA&5-_VQw(Q>AI6`Wgn!Ix2{Kshsm
z(_#elueOVU1V%(1y0mh20J+TEX6VAIq-z(P<N?nJp`}qu+i|1)jnPx@HWKoRW4j#k
ziILDy_HN3kM2{r)tf#(e36k(JFU)Qs^|RswfO4Mo^2iF$Uw#%)rSo07Kci8vBmZ$f
zPb(q5ESO?0ir25bHyXXpH&Dwv_{%cPd%*8<enT3WA!Iv_pmYt;&s(ZSf83rRkHL|$
zmOF;`3#gdyqev7PGWm;pMS>M@Bow}l)gIe|{y;y{;;r0Mr1|>|w?NX92WSDLJ~zh4
zo~+@f%k29TLJN~~x4a7uozA1e+g3ryy5btqc;EY7&I$`MD$n;P3OPaNYWT7bcZBvx
zu0#=w;Kdt{!T+AX=89V{_r5&0kSN=RdJ;FkAr_^SJg@ukHz9?lsdnRimL@FDTK(^o
z3=!w8?6U1_q+8STDHe5`>s8a5S<~ewubZ3xl)SK|FS6;Rymqa|3*j7yu!r*X|BwoC
zp#n!mpC9@#pGm)U&W&V>KIf;}oi!37Vu!OHPy2L*V9wa3O0V^)*^A)<_9-iNc`$q4
zc-&%YyL2@wbdC}>lNJTb7{zVa^wrUbR;NEpJYcF+e_xo94iAgl^Xj1Oir~?1vBCSS
zpVlXRLmBI{mVRxtSNDHv0bddT3Bz=yz-8C|Md;<cpO6qnD|B_}kI3lr2`%&|`hCr_
zac7O7=yNC9)i2%4A4-bs@rs7e9Zy-haOCHb9>HpC86p{iKOVuh%<udbd)2PVs-BNR
zlggciD*gt$P^CJbK#b~iJxVmz1gYiB^>D7j=}dy|LlI-G;AFOBFdXU|0$N_&0SXG<
zpCRNrIPAF%brA#<j3|@xc(=LBo07hIPfIzXQ_E$lm%S|ZH?wDoQNGtz^EPH>Q!uF0
zkr|c8A$I-v6exgBzw3zJTl+vjaZlWN*Btz&MW9`<;KQzSz2`lPU6QWo?br)-LZi4L
zmaJ6JJHIdOl-_=77<~Dr9LIVBfx*^O!@s2{K<6j~`VT??H<gN~1egF}H2?zs13|}n
zVTd9x6i?!Y?0@|O$s6DH5^&pVmwh}R?=Gi{b(|l*a@fn;P8Llv*Dk0vdt93NR*)@9
zeXb_VmWiQ&hC|u;o89RL4gcUnHz9v}wt3vJUkWxooIQ=y&JO-U?7P;LM20K;1&(`t
zSydSciH^%@!_jTGW$z?)-|Kup&wcOyWhN7d`aA#>4~TPaIHbL+s|)b%R-<<RtE5a$
z(i{jVjTFbLkDIov2R|QARcQbig8_H#GEKz$qd^k}g+~aI@h`xy0MBzsqg6_qsdwH6
zn`zE)bD_#&G@Ow0Wob>fIIMPP8MuD}<^IHf(Y(L3UL{)splkkpS~9kgGWO@IdHZFb
zd*)fM`7FRPa2Y?CIoFMA>3_l1wb+^}(G|T}fu1J=`j9Pv(lh18US2{<!q(u6PCy(N
zx$7nXF91!b`#Y{_%unek0RBaNTM+%)^b&>1g3(EzK&ifU(dDsUN*npwxP4@LI9EL@
z?eX<&qaUEBG0FS$9M{ba)LH4LgXPxN$Ibi%MlGj5afeZ!0xzt>(R`T6b8mwF!_6@7
z^1))`beVUaT*9xP8oyM?0Y0}FN#p-|veFTVygi)STUfE|dc2h0Ias+wij-S9{#%Q6
zYN-BavtVY2LZ*l}U%2!3$m6K*lPLt_hmr;YG(U0pn=KMf{UQx|LF{um^CpYY3~=W%
z_?`3T2?9D4bjcl4jZL7^?G)6aNQBwgkBA|;=EEs~@{#b`5j&Y|YY&(I^TB44x5{Al
zn06R@hp$<xcUv_oat|K&p~8?OU=o1;$XOf^PtE>PrOaiFpHMVn86?3_Xj)#=HrQ%h
z<cuWT%u1kF@0rh+OJLw#`nsMg8<)teYpz97XFa4)DC)Y8VBG5S$XC-FMJl~rzJkC*
zL!@~2o#NwUi?`=*0awHC_^gpCnq>xWH3c2lU?e(d_xV95YVK%bX9B9!q4mVCRooz_
z%>hRz)iMoVUR?xC@*KJZ$YEQrUb#^_=xl7%bW+o$`i|S|!gaTR%5X(acEXtQm46U@
zx}jv@4>KxnaM|_m-P0#xE~{HZViH7SBKJoXw2{Z_O;io~Gy=+7m~D5|);Va^1}$Fo
zjc`N4PaH+xbfkXx-0jj9<676<?fu>*GK?S*PVpJXDinh&cbusN1OThQUB!eLoHAU)
zXj!pKEaGo{ZZ1_0s{bnwnPosi1R`|@6Pek&g3;c3tVi(9Am{pD9Rmh%bvQ4n!}(iL
zL4lalJbbbhnWZiZ0Qcet08`h+W_jo^e4TzRzP0eR)$Y`iGBWf!g_Vx_*V`|A+;q;D
zd&D}NgZ<%3n-)IPr(s{}PxS3uL01BDsSg<Xc`{h^1bo)E6&!VGR9p^Dsa%#OL`I6`
zjv=oTJ-|}q(W!7h-vV6?X?;f@mzn)N!6&mG#rI>e2QWIAAJ%$^=~cV^xD_&l2<t2H
zh8OW%&pVJ=|1isPWy826pv{Xx^!w60)1oDd5AzjMKNM>ld&<D~Q5r{{F7PAJG)Lp4
zaD4hsgiAiuMcNZOqXH#}jY?L2a>Qo=IrlgEM+il;;M>Rqp9@rn(yu>Zc3#s$`B|i_
z+iX{{?gTqlx*zysN|?c_QlaD?<1>HU@Q8QV=)>HHH4W@fNPTXIGovkzaccLu&5H%Q
z`g+c~3=;#W7z2Wt<^=Q~B&<Zf`pP&)tF|xQmaJYc`&v+M=(2hB)F0xr{RGe_uhWjR
zLGdBxAdc9$D~Ph@X?0}dbGXyZW|E<TM|RCBzAo7-8#Kf}{k&IiVh|P_wJXgKF<&)P
zjI1bIk-(552=xokziMBB9L?9F4~v->6A;jPkoB1|B9wz`##D`$>p(?kvWXq(DeDSR
z_iNKQ?H_u)zrNR@AUii2jviEnrz!uGOj0T4W#VDe|0Y=AE8e_am||Sl_5HvU^8xLf
z&O6N1wh8zg3Hb6T8WSV2{;i)$wM!n1m2$?!Vc|4~OU?6U;Z=ZEeg1YmN+uZDy=~^`
zWz!{=^cRi-j)Fip+U@+^MP?DYzn@SRd>R=VAMIj<1}GECf0j$X+g@(%RBZLgPQcWl
z3<=#Vs+d`rEJ}Eh{k8l3OETJ=E`r-iO325M+>&P&m%qG9TTM+MfjHdRp}b?mnFEUj
zA`$%-9p*LJx%nVs8a<9bWv4<1D^~`k!eiP6=Gw3hC6}W-nncJDty;%7)*s{Etd<^;
zD7A0pS5vffWe~b6|M?Nw)x92_SQ3-{0Fe?(>>F{b+7K_F|5#;?s(EBaq#Y1qt#G{)
z>nX2h?yoNDeRl!qld)@|pQ(YW_>eU~nX+c87+2?aoiZt|X_U%5p%<9!Fz|TPV(2P?
z!f0tU8WDT}PgP3C!}2dz@z5cb0k2Fr7=|mulWqJD*{9lMeL*(#e1Dr^t)`0M&HO^l
zV`47kQnQ(vp4;=eO9d?C7+6|`WHJBl^yB7hE<RUXI_$z&vMt<u8RZ@R_rt8bfo^G5
z)RX~6N&HfD%UJO1bUDrB-*Hgkc%Az1Rs`+#F^;Mh?uq*@$EeYmwo}Y7W83`Rm8)`?
zAV9&wKtHPZiH8(ZKXhB{!CVc{24mkaZ#4n~;_IoOteHaSvObq~^T%qd?yjzAm!2!a
zg7DBiGL)K=eTm2pW}A;QNZE)Co0_mjflJ%3{J)8Yt^VxVTjDeokGlf`xl!9UJm!xC
z1xWtPoz^WkYhjNPKLoz)LF!7(5W^cDu3|)i*zL8Q?$&TEO-P$?0pM+R$UzHpoD{<T
z0d3<tG5a6CkO9xc=@Q*u_k!<jIyG);I`!`~=*FDk=o8CZKS%(}VjrQEEn3{5-iaFV
z_5G_7-qCO5`%@)EQ%IhQM9-yNU4Lw5$C=4Y1p#N5mV=>oAZ2Z<BNNgdVl1uexO}{=
z0_?&k;T4fFMs=O?&}$`^I2y%=46x*@5Ql!De$oSNK5SL8w6y6=?jG&qJY&tfvSicD
za}&pg-Y1SKAZL|^n&|?`OL-X?EmXC<h$?Vzs$_qpSgR}})8QlP`(Fpx(??zs)D021
zuE(L3lW1u1%l}9SUstu*%yLW(MLOp%2yZe0u_MtymGk88DFlW#&t-R<E6da_x_u<)
z4gs-{ZK_Zx7DGo#$_hn8$`Qr!75#S}s|f^n49?)y8d&Iin~z3cFtG#p_vdR_EB!jd
ze%l>yw;!<RH%!#DSE_ty1`Xo&s%GA<D$i0uG=nA-;rJ&a4ASRUTW4FT_BA5(Td~E+
z^W7+8gdZf{KuUAWlG!8(DPDPm*;XE>wOwWixjT(!2xFo&0r7rb0)2<-z3Wnwdpzku
z4S2X3jjpx}W>eqj3#f%HbT1OUD|qMf5!D<(-;qL88F<5Ob+Aw$cVw*g<5(`<k!ywo
zHL^|kdZE*`xtH)~xR#yn$72%x-GzG2P#Wxu1cK~NcjNSfvrkF-J!ARMQZfg8y3*VQ
zim6+Q?G^aMsGb%@*SFl)h<v(Vjph)@E8|a|Ndg=*oWKIb72%t;P~b_#gtm=iNDcrn
zVdyxBFdT}IM1jZOPhQ^C2I4J>p1%#)^XU?ur7e;HgLyjly5*bRp%U#1D5CE<Gs~t%
zwhHTMb6I|he_z{d0(Y(ACYe?s2;F)ZW5DlMxxV?@o=L`mTr>t=wtV2*8NB6K-Ar~<
zIJ{YV-(61lxDqz;W$i1_sLgc*#ImqAg7IePDqu60%n_jVD{D`)6p9lSZw`NYavkVr
z969ET5=Vn(H*k*wd*8QfWa~=GzD6(XYoQE3=ycL-E#oTUnBdKb=wWHi5aK61auvhN
zdJ*jeRnct)?<V5i6JaEL5VjPBgLmPH(x0<zDucUkuuZ<+{!D?>>RcFi(vGJs4{4UU
z;*ruD0ZZXza;Czxf7%ok6ZZhwDd8Z!5Kl-QMJ{AGTpdN`y7P~=aO!XI-!}bRv*sa$
z!ILf4=*KgV_j1P@Cw9D(BUN>%<ru0S1iSNQk48y{I-G=pBNTcY1jY!*wqJHdm@N0+
z)9K272`nt73b2;3bkyU*-rXi(Q`RMxFr>N&u9EoElufilRyR5TOFLW8>~C}^VgXe(
zQgPNI!>u^atpte=ynYJaj1d4lBWu~TPwow`oek$xk1W!zcaB8JXEFxJYpo<b(ZchP
zmJlwaien$L4_R^wu!6OREr6ng+C+#W#8Ch0iDoK#VNE6MJNVxM|M%47zfNZUzdxda
zrWl7sZw8R6K0QEc6>n6!UhJ=6HffYqO=fbbyS_NusD8{eVb3W@lnZGh*B8q8lH7(4
z4K1uC%JpE1|8pYt|NXW97g*r`bn>p05Y;+|RUog|SWPmpup9vc3)qjTpf><?uHYhe
z4Wwxm0H6U%@x4E+1wubWG6U$qXRV;prk0<rg|PxKAJH9#e?1}uC<;))PNIAtDB0P^
z%(wvu@&r8v$oh3wlSS_%-Vl;IVF1URo!=kukCc;`qt4iTJ4j`MhF0>P97kPHJRY!u
z8bWc9OuYV63s7O${qMflqsHs+cz}TDyG0Q3qS-J02S@H;MFF&RZ=v29R6<!&@4MXs
zR3aWGm8@5pJMBP9#jF5)RpjYro#yu}&`=<V*gKQJg8|e?;vwl|ngA?sy<8bgnqPF$
zij|yNWd`2+CACLO&8adJfOn+}e4!|MaTxjqX6`!CMQvVKHr7)}HW2bEDz-1o0ip0Q
ze33D3b`|0owIT^R?ll2%10S{8``$I@JLpQlrYq5@qS5IbR%pp-XAkZSMhC=YblT9@
z`(vsqt|8EeK5|=66|V@-);X@LD+_NXJ(<uq+5kpnKAJInXS@DsFcH=j-1$n()hL4U
zC_n~7LqoHRBiJveey|Uti`<Y^2glJW1ByMJuKY^8q5+)#h?qlF^Y;huwNP5C=~8d-
z=o-&MIe}W&S^GTiH!~9k1ZTkB%Jk~bkXf5BJUF3}AP^W2?O!U{E5d~;*&QHfpjrt4
zS^MJKM3Y%8YB`m55x^@JdJZn5$t9K21p<+P?%x-*!K_nB^*mo|pNWW_JP4!|TqbRd
zX`*Gq-wlBH3VUA7*iV-kwtC&3fy;R-;L>L+YSM*J%%gb*D0tJu*&xuuRsq|I{1O=z
zwT=Db2d4!ZGf)qGo*%C{vG;{s547_E7xE0hzunGMCJY!JPUDY54V(!VEo;8|SZTob
zWZ!(5c-T*5-!zsb4xRtv723>{vzzv?iT}u`Cf8uPpVTs(wL>T7D+k>?{@?6B@X^<R
zY-_>@ydrvFYDUcd?IrcKf%H*04e86SQahu`YuCh{Cgj?q@-@<6VM1q|1>zgrv_YdA
zu{-7=VjeXfi=eRc<9%<Yl#aZx_U(P^_BR7jBir}+NrN&upQg$39}N~CfewnWfe<Gq
z`hg%e2wyZ^FL_2_`>XV4c`P)!I~QMRYUy{ck@FxQ+}hSIZWVRtyDf49b9ElO>j3zN
zH1DReCE+E$AGh3(*!woK4+AqxPNs{5+j1Oo_;Tazq&8e9X*0dffFuJXE_Yrf|2!bL
zXz4k21NpV0-X|ddfC4gdAeh_$L#g@djYVdiU+8ySMg#B5$)$InkIf$tk^A^mXIsuk
z1Zfph;v>yj;)i81Ftb+fbv4T|{sLYdf|&Cg>>m$&eutHBZng@?3-$l_+!+>Q86kc7
zQhWW|q{PWPz?4m5(FZjl$XlA6PVin6&0#eH`x1lj?|36t>K4W4EVi~TARhxCC90>K
zC(ZFp-o{_0&ALm{9xueZa=kBx(l6r)Y|dyHBwVxaP3QC~Rm|7Q8}Rz<AeoRJdeayy
zQ@sp|OuU)wicyMkrbvW)^Hz$r!;)<PaEgg~yWcbK-AQ0A`+TBB5D!9o+W?ezja;BJ
z;IKVC9{ZL7=XE%Rd#N!<!Uiwo5HSzUYTd_BH6S}<2!<M)5`w{>aw3gF>V2X5q8&8?
zcgy`)FvMYAwlADiG-I5LTlb8oX30qZ0BmN(3?Y7cdU}UI?F~@!=69zJJR|Zj5+dIU
zs>ze(ikZ_Pqmu|F<6iCl>s{i;G2s;T=ey5MHZd6q-C1h(1Pa*3XHc;=92~AHwt&!d
z>dF6h>jsnpZl$%p<|LQ<tHT+)EtPbit67VHvZlyRi%jpJUEUFIDPY&+bSO|a1BD)k
z2iVEYe^YObJtaQn7&LoKq%|9of002RAP4&2#@CKaxsP=Y*~9q8zKCcKEzIiq;f~|n
ze=3|4S@h-hg1D4^e<*2k&j3{(o9+Nqx^PiLc8jBh`XO?hy44^e8>0BF`t1x|z-<4)
zBH{3XV)gQ%4iSY5(pC;-feIJG8Geo>cD#-c9uFmAD_au?B><FZ=07p~;)o=*K6EE0
z0ZrlT>HgSl=dYh7QVr1W{~Q8|Enqm6m(y|fQ&I#0JCt&!We(~djK*6mEG&nO!_Iy>
z7!kq5$4J4Woyp%x`e`23-r@(qUp#m#4)#gcp)3$BU-%bk^3hy1BR{(watNXI)IUUt
z5Mt$<K;z53Nf3aD^(KXzJK2a+E;Ve;z=G;&211vkqodgm;J|K(5GdS(yZs2F8$5kk
zXpTF7$@ftCb~lo=U2jfSYc^Y-F3W&0_h$QjK2Rl(oU=Z+XKLF*L8U$;R_Ig;*9sdq
zcF|q<*#T7|&XHu;*^>gSp5%~)1TOQTWS_^o;Y?A|>jgp5#wM^<XfwWc+)E`plHhzj
zX@}P;`S=bxoMX+Hc-jXjjDK86={g<M8H{KQ$BLt&v2hyc%~d4IsW&lFsgZ?ums>@D
z(DD9Duu%rWFFbZ3>0U)NK82eUbCMdT-92d10ip_G4gFWWEeiB`nV!zRUc-FKSPJO^
z+&a3XCROnsc8zbFXeFd*@3J$@#?UVT6!T7FtOR+UJ}i*DqA-^Ea*FWep9-=}2VwtZ
zA^CrT5dRO-a|I1Y*EC)F_L*Goe7t}`brxm}t?P54KT#wNlLC{_{x=YY`3zdfmy4aT
z+}vEy5mON`e2hbwF_L^$9=k|3Bl@J2aHAA$)RKLJKjJY9I_Vx{#Jxv|kqnK9U_SW9
z1C}jOI-4=|Lt$>6G?6@RWpr-C>HKlgXOMdO2Au!OPlG8A*yhF|W%^eRz2ooA=%uak
z1ST4i!HJ=e@R($Fj5_4%D1)pSh%jNPYUr%MaRH$JVSnh*Gv!+<uESJqI~}-<z@Tu8
z7WGXob6YHB_zx(EEcpa`9}xm|_UyU<B3JOeQNgz!=v8cKZ(G|#=(2YHc!R4H<O4A>
zL`L9<Q??#5KFqpOR>ngDLmxO_f@7<l!Ev#%3fhRi5vv=igQk%g>=a=k{I2;!GjGAM
z$b8OQLm9%J3U!Fjaig@ckw31Mai$pAIq;jYBtsS?uRN)PsCSbVgM6Q-Y?Xh&uz!p_
zw=cl#*yxYz-9Q-05Vr1+Za|k$X}}!#pr&tJ#E5ttb1Lbo`(LyQ{&!C}#-p()52UPK
zuojSC|E2QUgF<u(HjSDUaPk5{HOFJn*a26?s8yQlU0H@69u>u^-*5r8bB+Bn$;P8U
z*pz?R!5w*@GNhCrBkKDEP)h={ZsIQ3pI<-%VC?Vj_>g!u5C+@?=F=J{&6clt|LJ<~
zOEdzQQwyV6{|*v$?F#kkEAR7XL15_s#B~m4Dh88S-BNMsRI&_PeL&d{ix8eZ1n4!2
zkkfp3Ja0)81P=CqIPMJcmhZy}D!!hY#CaQWiJtXQQp?2?a9d3@xu1vk!7e!VzD?3|
zl3jTK)&p?E?ZIVT#!|~GDCNEj!vheKvveNByuuT>j47n5Bm;s;JVHWU>>oip-Uk9l
zrD26SunDdVI%GN`c$a4WSgJQ^+L!UQ0#W1p&V1EBMJY8|0Q<aF{NP7KpS|+0j}}3+
zX%3)jQelsHXcv$kT6UecUFre1!V}aFeocV;W-CnLBkHN@*w{`%;su>!rKSlq!n*ID
z&!=?l6;pX4{`z(5w|KeNzHS(A_H^UA1p%2pgCa5rzFsC!kB$CjiEEF3zWEdgBo`Cl
zZRkzVe3y-z?I!~vC&UVB-2$y70}uKl2VnaEuLCqFL`@@~TDwIxwIn9m2TbVus4qPh
z$_ffyKMg^LNsnsv1!$Saay(Z&0Iu44+MvojBHed0K@01`u`dXnbVRj^Q#BAYt0V${
zd&d+EW3wz!B&8#XZ&w1)weiGR)N*BjUEVJeqh2XrZ8ICoA07ns@^OS1MWZf}`-7?_
z{_qFTH>V5L;g$O$UE}f`RGnYPZgCq!wb}w{iEr@6orW0l*;NG@8x0AcWoR4l0ATVQ
zw%Ip-Tmt4F5Ium4^v3WCSba68uZxU4U+g_@G@1bf->$aLJ&y%SY{nfh*B7r4t6vfr
z%Prn0tiSiZQE3!ugoc9k)L8UtBPL%tQ)xkrKU=TfX=pW`mWs+@%I)Z3op%6%34vf#
z@L1@cHXHi%t?unX)o2dCJFQd^Tg~a;{wUL92Oh;p=%ibqGcQ+uLY}Tegtz1nB!p=+
zEMKWNWD;>8OUNACyjUGE$!B{kWgxJ)UiLf|b|tN+?l#Mb0-yu{5{W$aWuIAJvf}k2
zN9~dlc(fmyS`x2Ydx!;N<-PV5@$+GZOIx2j#xIt=&Lgyp{J-Ty7n%6W1hVgq&~EJj
z9SS!5rQ-oO?@EIv0pz2?w~iFEc$g@sD*!!K8h64S3-rIz^E|9B(XFLP$tJvS1Ta!r
z^pWdiy5STilmapQ3_ykW_%0P1R4d30t2S3LVofm+=WmpcRLu0M0m=t{)6n*~5#7_-
zAZs|gMpq-BWCak@lk{B)C1cEI456&U^9{%RtE&MpcCfYEN*@F`!>-)59I(Q^1jq3m
zun4NIc)L(<{RDRmyl12Z<KmIEsI7ZiX^cAPb3He(Xp}P^01bp4?Jnp)s57c7lwGNJ
z)~^}^Cy$Ainf$hrJD%~hQUGT!`!N-Iko^`Q=!d(}O2!YxM!x-o4Q>M}lD11tw_1kY
z-RxaRjxfpfp4WC#f$Ja+wcPsr4qso&bBJ=&x~RPHyZRlFF#+=P0jY3>tZ^U13Q^#E
za*mYF@y|#xB6f}VL=XyaZF!Wpx(+{a`t5FOn^qrE&;?iT#*?x%ok)z(brWO1(KZ_?
zO+Oj2_&Ky)*XZB%p8oTEU(X^Y9K|K0S*FAI$e(wZEF`srN!SHH5&>q)7n~!=0*ZD$
zAViCYmHdAo=ZDkSF@uOrC1~?*fJ0CH)*4m(z=lJ}Pk?`{Vz%Xdz1WMp%G2p(8gSHd
ze+0^EL+A&rH}oZkkJrn!)>TOXB`G}uGe52*%th#zHF$AkDz!+JggM#&{fco!5m+`s
z^}N^-*K&MN9LViI(5`D^@6wz8%oY@)IFs>H^OtF~?JCW<au=Lr7hxfYs7RyiOZg0?
z&>Yk7aU>U-9Y_DkkE%8{wxNItYfqt1jK-_Vpl<G1LnY>m<{U55WUN%Xz(X}{1nr?~
zs|m=>g?s7(A$|I?pu{1i_4}+*Cef+-zjYRNiNr6g1)QWZ?m$R~EX^7XHK+x^b>hDu
zU#sml-!OR-96mq#pIQJ70=;QuoOt;AP|LBLckyKvRcQoxQC-YM#c3o?7yP^*Ze?{<
z2TdC5KK6+i>NrO+{8fI>CisriDTPib;?}A!nw+Qo-9|`MPY8LHkkf{Y9`p$NDuNwZ
zlAm1#F5Y{bfHXv6D_*@7q>f0_*nFk*?^=<J13MJD!zx|z7+f<RL`MicffW$TeClDg
zGGJm-lCzpd?e_`nE>*LCwhU6Xoqn$$pPUTUCItVzR@>tJ!Ape2o;H=+8gC#-0$x9x
z;2TZ0b8&=d{offREqE;f!Wy!{AUjv49Sr<k5JN16G4Tad*eCLp_%q121;Ee|(6MMn
z5>a@7n2c%Tp_c-73?6P|n-5%lz_)H&v8@iw8^DT}y|48nU%iGmptm4Im6X{b@Po3&
zK;#M5r?_VOG=PI`$FcjGHy-sl<<u&z0UHtTno;4o_4(0$$OEK&R9Zn&y7{z+NW(^@
zJ4)oPZ{H=F29P;C3pB)bZRcu-1MPAki^P+L;67jpuKF)fZzr5r7_~zQ>eW3U)Q)}Q
z_%vYj7=hi-(T;nz8cgaGIAfj*HS^ZQxCx6lPUi2h%8Ea^<|kIuAg0$$lI;kqVwL{l
zBOxXyY-tAyEEIZ{L3lymxblZbI3WOh`>xuXh%Z>dpdpEHn1)k@+xB#KOhTdpS6@7f
zACjJKwkYQFDAWjgx)>6(Dk<e?|8~ZH9?soJJtIJscklkffMFN>w%lLwrIYC@1(KjC
zo!Tjj=!)8%Bd=|N14WpX9}zd8<$@&`X=tyDCAPwiRS83ar0|{lt)BxP8^RSr`9})!
zh5^TX3~SAHzIQrkIKhLdIS7<7-fhEt?W{-(z>F>?Zw$7jX5G>>Eq!hF4JL2d{}&y#
zr_@q&%s0xw^zJj0NLz-uOBIKn3X0bj&KF*Rl;8f)?2F{0?|1(cPLr?QzCbz-JvHWq
zY<G*bf1=DiVUbrDs591H(R<hyeQswIf3T(6Kz*gd3_USb7~c2E!FC;`-j@Te&I%-c
zR7rRd`!OiCzm>ELpRtS(AHZ&*NSX%Ig{rLUd4$WRhH^)Sy6@&CC0kaF)0afpKThH0
zZfD!jl^7j25pCX?2qPpkW70{faR?fWrb|U!v(vA`SX{kV6UARbzkt&nokIxKF7YIH
ze#BZf8VFee`Ci-uxP}&wODi-QavX*=5~~Jrg~V94zo@B@a^JP%am^>t74znUN`9K9
zb*;Qfv;!%bIw~o#D@>_K%%f)zxNSx~IR88&=ZYmA&=K<%TZSc@QME|%)_qX?X4)<{
zD08HK`_5P=XawjVfhO}~3S<iAqUC$3Xn$WRxdVzo;(1U(>iZD0fSH7ynx(N>Bfb<K
z$71I8fM-D(v7SXJeMsPXAhBY~U55xEvwZVNVX?Ax^w=hQVQ>|Wn!@g5SHFqZn&>)X
zluj6oqO^eN#0mn;H~WUq-vuSGdh(~6Wv^7GdJ>2h>gM5L{q5;WZWaq%rrL7@HHIS_
z&Bw8p_#X%dYRczkU?MrcIF)$@-%_;HKi%#3vm3G45I)S?w|;tqEj^B?jISO<Vw!(L
z)zGnM7ABMA_UPj~XYe|BPH?#_1Ji(l8YP^6d>_Qts3s&J{q^(lzYIBpSe?G#`W#kI
zFZ5!DuYYa@_E4128G`g*lHoSR6`YHsMWWsJxO|W3LMN}b10X2S@h+%XiZ$^GW<u7=
zOdWYn-MCsBZfuc1|2VF{@36SWL-2f^<bqJi;5xPBx8fEVft?gx%|&r7o+WECCm1Z=
zQEq{v?zMJTt88uJ8-ZQFh7M~;e%Ox|qiYefgm$HBbwKG?SnZu%#vDL2pdi5|NVowX
zY}VRArU!D~RB(MHy6a*OQsXy(p_8!`9~coUb~sZ{D#T#9v0+WFqks&4n?*03IwxDC
z@+knMc^mbn7M2Rd8=A1lcHI2p5I@O-X8qB?aVR-9-zTpiGI7Fxe2Wvsd;>d3+gnZN
zBR}~%5!na>s$_Ihzq<jTOov<kG3Q;=t5P~1#q<C;I&5Y{W_k!!BbFyTlxI8Jr=%~?
zu@1&EH;Xn_#ML*0hEGl)$s8U0r^6`yS`62*z1HFF1AzT2<S|xc0e<WqqMtPN6gAMw
z)d_}GrtrRw!N%?dDVSq6%!U&8_weRQX1H$=qG1M_46MW}loL^r{2Kpf0U?*DO*4mt
zAV8Bqyc1vxo86Y&X+unO?|1M8>Sti%yyN{YInVgku5jsUh|QdxdoXe1;jW3@`|8;K
zzLvwMduD=Phhe-D$pN7<GIY9D;cA$(jSzo6xgGdvBD*(M+gc13U35`YdIYp6_Tj~;
z$L8UVc_*|#=}z($L__ps?^wUEMKUTPbOeSn203@KU6nFZ%7$w2nsJ2v9ae&CKU;Bh
zLRz?o(mUgWVewbgUR@a>SMKZQ9znj$Ir$>H%K9Z%tu~wZmh}3_Kfc_}!K9_REXk?D
zIH`GXMv%0utHpE!Xu*A1>TP^A^)koro6`$Fl+1zHQ-;SLeFv<4ZKzs(4qszUgIIV+
zLO9MX>{js}DDzME%g;*{rqb&h287Bs@zy=|uPUC{TAai-UfHyaF>|u@ga|s4od`dE
zj4k{M^znO;6D3Ap2i=O4!wjKcx%PDud8x2mXGk@)NZ%YB3c*PiwsJH+hxjUo*HQhp
z+M>!<G)+~UxXft`l!-H62oUVT|J3%(-MiHHAm+Y=X0Ao3@qe>OX&6+8kN{2X$`0N&
z8ON)rEML3Di$4#yQcOy7>1X(E*M)QZn3~n;lECZU6e=v5uU7}Nb#SgU&@nu9t5dsM
zahChed4DWzxRkJos9T(Exi;-u8!u#(F&T}PUleBD_cd8p8rvuJ2a_*zFaRWT1c&|e
zZi}5%lb{{$Cf1GoDZkM&^T~XCe38X-!1d?q7fT9{@<^d+|4R*-dzJI96(`HDkLX@#
z3JI6S5$6#6&WsAk_EEL8-Y31}qs|X}MMrZ4S9YAmO>VY$c*f#hWXGMIF0ApWpU_^&
z0wgTmiHtj7-mY<&X!9RD*Eh+53jJn}YDcI*;CmPgfSZ*86#T!ovhGbF9P~%3C+8ft
zVO5zLQ(~@>2}so~@pE;onJN6vH2oe!6q_a}TvOP*X(v;7mJ!a<(S}nQ<|uk-kAMrT
zjclZlf0E*HePM}90Q0M(N`8k{uVs-U-;o0l*l~$)fQlMXFL|cgI_Vk@GlhNPz}f0X
zdcMY15)mPjFtCpH_uFu6Nfqeri>jc4OrI2UJzORe(&|hQ_qnf`eyQS5&c@Edap>>9
z{?d*vq9C!j=KR->r5efIdu6VYU%?U14#%@@1%^znOpO1|={AG3+jfg)pa+3@*zHSY
z9Hzr%Q`~58GdG(PEK=7`<yDrbjHhCb#EgOA8S|!oPe(LB49XVe`*1eGpa+5vVPQ#h
zq>ZE0Lz|=2Hik(4jj}%TxZP2rPXq~@WG`~$6^0{01<4<(dCVIk7*&ZI${?-;O@6Nz
zj|NcwikdVHG*Y~OG|o3xAQt7dKj|Aue>SK^Y<KL1b_8_mP-X&BAWE*sS#H6I?#Q4`
z$9m@mhC~%(LXD(6T9MQcrD?cEw2VnM_|;oH0c~_Q@>L@6K<Mte=nDwFS3GJ)@4u4%
z`#Jv-AResLe~&ftMz>dxlJSjPiSh<X`2-3Uq<xs(L{4ULrtz4N2Zclk@jZ@KwA-IX
z$*~r)5X`}ZZm!aC#<HfhL;=J=^^fylWTR<%<Rv`z0>uz#;2Yao%>2DHz>R_7IJZN)
zZ{o@cne0$=tZ?43kt3`+2b9%g`IqsrT%~zC35DnST2BO#q0j9mS%&pgZ14M+n?V|R
zW44$F^0~^^l^`M|h3H7B>_>0j_vMB<6bO1>e+d_$HWD`>1&`=Pk!WVsrK?@rkcLxw
ziu;(4EZTh~?ZvKt?RJvOg=70M_IE$pJFmAr+H%(jo1>Y_`b1Cm0;P=@yzyuq`zi&3
zx~Vq2(X#h_P#l)a%ND~*mAc{_hpZYV7EsGY@sXwZ9%lY!FZt%Tw__A25+Q7{rhA%W
zOelo2a&W^9q2+8lu>b4P#sAlt#{ZxF0HKNvAOla}6@c8OZmW;?i=J-?<QF?IYv@(&
zcD&Sh)G%n@4q~!rlR$2KF*LAWFO;wXp-zt(j6g_ZnHwi_Sz>jxNu92B107}mu?Ua=
zAb%O<fY2-m;8$ET+Bkwik7S@^{sq<zh~$P8Qx0`RCntwA4okKB!-C1j&Br2;5(O54
z5ruMw5Wd0J>}y7?m#q3Jpr9|~o;uPu)+j)Z6LnmZQczF;8>RUi6OO7~DHHV2C8@aI
zgg_jW`uN}e_(MlINbrIgJT}!9uUjD2&-|bYW6&xc>H?adqF7G9RS&RplbCeYMws;K
zPJjmqvbIBB98X>x!^B(nw(J*)elB|xmLQ-D+(Q~|cR-oqY|p{0=3gU_u0$8Uh+fuG
z7P+M=<ZQ`{03(CM;=nUl>k0)$^HUCR27!E5%?YLz^ozCGX+D%0C<?7IbJnGZ7nhq4
zzY(kga&<i85g73T8Pi$50OkB2oOTO*W!>n_pU8kv<__v`5l9+EN1uS~lrT^e`+0sM
zr2|<L%qi-F4dr8~@3ET~q6a=45Eg*{Od*XCGq2f?K)B2S&GC(3We^x!>0di^%^kR*
z`NcI3hF&V@=K%AYCxvB?{Sq&``I-p+!}(f^xy27V%#UKK1|GZAB0$iQFS7%_O?;&`
z@PKP@zqrB^I&Wj!PW)002u&AsdkH23@7M{Zf(8l$FY7e|^!w!zak%mc87P`M;8FnP
zuOc)btdUtOxG8rqmr>&gq)6Qw8(GgvUI0AXK$_cPJMNs2$A)0gB<8R(yY^z=7<k;k
zXdB3%Wmy(^IO!C(B0Aq5EwBeeZ^nTzsGR0Q<>&NqGb#Mb<2@j;9!W-l30<EA@?Gq}
zW79m~fQz@Pa<mgj5%|JTX)F{<^P3Qef{w^2FA`Kxo0)Pd&v5nS2?$-5g5+kS%?@*O
zv>~_$5Y-PZ|EUGkg3-M}*O+K9VAJVJkKl3-T+iI_kAFU|j+mwJgDLu7VB|I=O+tzS
z&T9{7f+b*NaAT9TVTS?=3hQ*Mm7WG>CB?e5B9z7~;IH2gFhvgh{(Aj1STNiIYJEUX
z^xbvoEKPdf&3bD=VO|oDjwXws9D9C7iKG-UyxRN@V(~e~8<8Or805TBU2@UXFHT}0
zz==%y4PcC9OGW~0#|U+MvU)Q`HeB;F9-c9XV3hjk(6aBd_f)Zt>+H?VSCNVvpzq4N
zZi3elOdSO;jR&f6`o{w?eSLv9Pzn<@c_OP5L?!Y&!K{pw1_oTJG=;XYGDzWp7ZOku
zV9*<DH@Y&*eOoOB34=G^4r%Jm3^|PLbtw#$bAW8);T1L*<^Cl}*!zwv6Bu`QVDhA2
zgu2mZ$R*`tLsxhAX(&CY3ZKDK2UGpcK+gxZdGZ7q%HG&dc$2^RibUtjLgPR&y^zYl
zpa{mKHzup70>T-jy_ww->=e6MSFow2u&7dGsIv)^rvs7k8wO*8I<R{SmqFqhq|30)
z7{Pjx7%2kY_=~&+wEKQXFnswLl#oK2coASO0)&z(=C?2bwwCp|4Db;rut9YvexJKk
zdI#omO}QfCN<kpO|2m&?J)SUxR)%Y`P`#HgWwrTtaH57w;cGpoe(D;(z#R5*|0Rsb
zi@ixkMP_~AT3^++KB5wS1#B3BW``gl0BGSekT#(1D`g1D+7*FM3_*ht*vTZB#FN-y
zqqv!~E#{FWfr3K01~x`h=vORhcr@Y_Myppnjt|YtYP;18{w1V5Hpz;MY>(~mq+Hfh
zC_jBqR>V_1kec(5=c}(-jsNOEa`9gGewo(CCvYhL3T{!ebIa46wM(F#x(InxSJ482
z4A_e(m^g4w*LCNvbIfeozpfjoUw3s9DG>CUp%ZeLfnr66RG8WyM;m8tatfSflP*M7
zAg0>|Qe7nW`%8qA2)`Ml*nB5}=xm>+4bRU$f}H*maFLCpsXs)tK8Vo#44nz)eHm~6
zV?~DbAwl;O3o0tCZ0k|N<vJ=LmCf~-y;utbCT5*{xTXrCdFE5@ARyvt-JM;lkZ6(N
z4wsNatI_fNblr+gO~&&QmjJ4~N#k}eC`odDU3?z-1?hnp{INp7z~EBio{^&72;7_e
z9ef{EA}#M9A0lc0Lwsu_U4GMRdn6r{^a~M9TB(bbmVUm*xMJT#yK!&r@rekPn%F%g
zb$wa5>FDvb$=_PMW2`7+oge_CS*S+6Q2+*2;@^V?0~C9BN+}IsS>ho|7KP~=hfEw6
z@kd#g*7tayl76xn_>b~Nffb~Z9b%hVFb}8;KxPFBKTN<Dp`|cJND%S9BLImBSgDgz
zD$tf@G5^OG8vNIrf5=2*?3#7_h_id%x~<&XvX6feVsyHWL^T~c$AHZjXz`X!VngMB
zX>Vfu7%5z<2vtNnKUNvc`6O)@w&)C8kM)rM+uodi^7%w?OPLT)>(wPZr(Hx=nf9L+
zXWv*?Z*LN_?i3`IZJGdSlEJyo)RIyP$Kj88wq!{d$XIcKmz_|#0Dp9$dmC7s<T*iI
zc<&-G_|yL<i<82N&w#%blcFFFSe(7}c3QY#sz@?9ko?*I@qNfI@@M<rmt)p@JB3C%
znNTcx?b#%xP~R0Ca!PEtpuH6^>yS$hT-`aoNA|5*L;yZ2lfp(OCWW*!u+qVNL+g*1
zq!%IC19woIJxdh7M-M_wUKg>Ty7>VbrBoznf}CIyjD3~nL0KeI$Vq5)6B}8JHBZYV
zWJtQK3!~oe;93r4Fy_(|<#~z2Jp$uLuTD?KxqT8Qzu!xEj4dYSKyGId!I81Blx^}7
za@q%zGq3r75H*y{efgvzbmRe1ueT*|*nu;8B8~}OaRCV?#!jI#`5$Jh<fy@GI$UBl
z>FMA72ej<t!Gy;8SgKcFS62s8FQoiVRC(s0a)SxQ$Q@7kK#W=BA&H1L+%G@?)bQe7
zFo|AkAGLBE3bIbc#+^aHIs9}7>==E}1?5DWb+W|#K+;a5<YU4v82e-~X!`p6^y}u!
z#>>Xq@Fn7rx}xQ0t>1`!dc5Br&GZE!4M1&-lz?n&*K%u);vJm_;1;`CUo_ZcdS0j9
zOa@@a$K2!^pGA+)YJ#rSbP>Qpuv3DZPxgM7nX?+djHm$NzXI5BzE9_w?>9UE^=`Yw
z;(G>DPOZS^1jc5SSwB`Bc6){h05Lbdnci2kAa8Iugkmtr7ymLZm89M7|9o#uFjWtt
z6(H4Q4<J`|@kT{2iKNC3F1+a1K`{Kj;POw=tEcOMl`tUh4&*>UZewK;pK7m%$bLi0
z({=^Kyf9)xw{gf>{4u2g#wAAINFE!&?8-JQ&kbj!49QYE<~M%X4`N7mQLQxV2iFT`
zea%2{!oKy9M-6lrb+fj4IJYcd7K9vv%Kpnid_%^;leKQe-}9&*{vS4K?Yj>}8oT`P
zGzx$Gv)gX6khHe}!~?Hkz;naC2d@~|1=8KyM&k~6r7LK3A%~~iZO&%5V}qK&TDOZG
zRRz)k7vOC+F!Osq%r<<n)*z>+4>jj9$80e<1)bmILLm|BR09h>(9tH{oAsPHRv!{@
z2K3u{g&!OM3Q3c{%n)q>Z+s^JU1UYK_!*2qhLEe+r>dJ^e_eq2wB8%FT}(t?De8y0
z0Y<B*8{O<V(CdE8#Kf~?DnMuQiij*JB|C_*d;%^lkG@TZ-zC1|QUw)=gRzh&r5o1R
z%-$cjk_J};n@utpjeGT*9l-tRS+wlzj=%#q<38{z{s(epQy@|Zgr^BGP><a^1UNk>
zy!RbowqUr^c{-^Xyu#tAZaoq#Q!sdZ3t&61j&v9360!dR^n!1&T|U$6P>#$30`T%u
zgY~p`O3avvw&l*-N@&8jf?67mNC>`s*c*l682s@7)x2%2cRx3`Q2`wc*q-+?BHtK=
zWiZ(lSG<8|8Vw<jSTFK-{J+Zj?r<vO_kXgEJ&qaKdu1M5(#c*)vNH}*_AHXkA)92C
z2$jmr3gy_lRAx5WDzXaoy-(lI_j6sp>(@W&Iy&ch&hviW_kF+C<Bl-J5z~m3PDK+D
z=TUuxGB=U+f}*RJPdZMW5i%%9kzJQwf?Ci=6KdE^uUIGWb%6EGr3m_NLH&65j_{jN
z@7_NOJD3i_77p5xknuEvZ=H<`lyJJjx;zQ0(2UO;gv2N)7Vn$5YsD4_B1z3(m{ZI1
z@~jS_SI938d!M?^_y_0}ur`M&KAiC(?KlMKf}@Z1iC~m2dvsrg{^|rsBd^ta+B#b2
zR^|DBLC~MJ$bnnZ{@RZOopPDeTX&{J%1=!hEH7SssOYl*F2i5on6M4%Yn$uPe!E%S
zZ;|Da=%B^z(qG}4wmxZb3=Ca+2%o{qdt4OR7oTr-mw7yeQ(JGQ%E??6^LrKrMlY6o
zy5X9?W5U;<zuak}I>`pi<iKh_{bS^KkR&GEY4emeyQ~M2>A9v{>u@Wb1Xv2bi&g6)
zVp~GHh6<a{o26|AOUa0ML`L-vx2iJ4d<Zk55Q{fS=8tS^eO7dOKwbRW+x(viQpIl&
zD^H*ir$Vo*dgjD94dOJDwhD;ppmh^0MC;Mi3dMKy908B(5i7|k)fe45<CsaJd;M)a
zbF?0PvJ`r=z#S`5eOY)4#P#3I-#z!V1?Ko$B$bV_E=}5b6p(6H*;zjYO$V@CYaATE
zX4-Z4Y6ac-x%D4;?E-=S;V~str5GEhyv?OPd9n@;fINVuW&!17pYiAo2+5xB`jW)F
zMS+`$rY=Ioq2f8<1L6^5k6WxJl&|uJsswIkPb<epzNhEYDh8|%T;u8~iVd>cj=E%x
zBPN1BC@1{&4j6Cqq^S8V8!RrpIeF_Cgr&{ak-w<b4=Prvc?p@OhdeRKm%bt%-`fuq
zT*@(H^?XLIkj6k77&S?gjCypcnt7qOT^F|_bI5$wZgc1u$YdQx8Pjc+AEztZs1QSh
z*BQUF)0e8<7D9R|l9|Ox%@W7jFz{=z%>uS#A8zWrAhwa{P542;=ooyeAZv+HpUB0-
zWIzOJ#cg@dXJ&9~F?n+#1o0f>@}lz;*x(aY`Opaa8y@2=0UPEDHuf660dpBL&!G3B
z>|$aexl3NIfRkjpx?v`Bnyr47qI81h+``qO6?k`gE~%b+_X&oDNh#|TwSCsNlNV^!
zI(YHPBV&!^J{R0h5g7*lfjAqUq=ECTcbvp5cz(9j@m^_&-hL0&rz6rP9^yCrVzT;E
zDRb_P<%*+L?7law7rs=rY%=z;BwFT-;>2`I@8*M-A}hX~opqJ*tR2Uf9q|0Uw5}gg
zbm=zd`*B%2h0~+Wu=oZQNAN!Kiy=32(b<&y7__g6aL=t3**LXsNj$8?K^ZI3%hAPg
zy9_3L@0dH_g%><EH-yZsq}+{r#V&NrFQi2fZ6zh_Axlh9$orD-@67|ozm8K4KC5gu
zhJje#_{04jL!iUuQ&q*l-YawXfuZXSJ+Hh}MdDvj-SCl@&$osaCdMyboQ!r)IdgUV
zTiD6Qwdlz^Aut9^W`P9RS;H|8)CBH%(q+9}b6(ZUfPO0)-lWtNX4exF$J2f#2pchm
zUDoXnUSc<fi#mZR{SJ=lBbc48bBT;RzCKgN@67%tt`?6lc*Kv}edk!`UVAt<e&h<O
zi==R%c*HBIv(E6fYF)A<X8O4U5Syd%aqfg_!WEKM>W69}bv~Y{)OSCH{l@Bag!hL_
zN#UfO$uw;!nv4eyL1a$6E*iIZHtd%^$d#mV`-BR4PuqryC^Bo=cwtyC{0d@y&G;kD
zh&?IpAE!5?L?xdw(o3^<vOLz$4k7&j$yCR6`g9jgqUZ=CKvB;3l;bG@+s_xNH8*cr
zuQgerX-I!2yqN!^`zLz4J+&RZ@cvC~6hG}-{<V8xr@PJ4-RiS8f02h@JVv^9G2_1X
z{l=ikxxVJzkNN|z8}EG>`#(Mr+587-&QQ2OS5o0WAXzEiD_pMq#oGM^_0)5^!wIeg
zwuT_LX*%ZkU70-lQ?ikHta=N?DH(hQHeU}uMES^=nU~wF3U%W+S6YdkNI^tuU+sZP
z)yr&oCCsREp7&2(X{IT=g6U#2!1c&H6}ON4U1GeLde{8(x>6BCc~tF+DCFw@VF5nZ
z<vvwedp5>Ul79LNWxbHFC!Jj}gTT2dUvu64F0DYJaK20Vbw)~uN}_wi9Jhj)-=;*L
zKcwHFQ{=kN5!7*#@i@zcN>l6kHT|~>$QKT0972rM8u##O(2gl+wyIe&6$lxAPa5<^
zR~No!Sgm=w-g%_9K0m{i;-@PSu_?!MO7sw%rVdwf;$yz93tnBW=giDLG0c#nOG{O*
zp%Iur!|c|T$R;BHrwgZ8uVV{zngxSip8qCjTJ}&X8*>jcz9|Yawuw{iyIi)m;%207
zkwo_;rfJ_{x#f83{H5NdIl1{p<ip1l!U=}L^jbewAjnU~E}%8i&$B^ON3Sku&fxJE
z1ZSJmmP*JCF@21EhHd<drF};uR4)10;B8(ZT&<ML0PA-St<%g&Qj8Ud%g%lqb=ch0
zR1HDYA%)v}f!+}uZ_Am@C!Zm+EXb>XGSq`@%7nS?YivnZun85|L<xCR+pslbHggf>
z3VxBZM@uA@TVoYm=~0(^I*q8?N8Jn%k2Uybz(1$8_W9_;1?8T@pD7N^qzvD(Z!Ko(
zJ-W3({{8Cc6K#DFe&QL?1pQ>c!3Z6BL0;JliLv@SKn(e<Dpia-`<mBv_3MFA;WF64
zD>I+44dOw&^F%U6l8D)YTi8?dLXYyfo$hU9)EJc{E2fE?&z)wy5%^YuDVQshg%^?d
zqV>y2_Rk)^l+@k1;Hv*nf%B2oOfs!roiW!fefb(xY>Hnd*a+Vz3VC3gJIWjlY+7|L
zOrVR+3-5hw`KZQ`!7;m~?~5l(4m(ncvmNp)*Iw1nP@I_SviMqdP-mZ}x%wuCXEEB6
z72C7vl)6v4qOrhn?8)RjHD@BbY}#TQ;hc8akuvgZo{NNOF+ym>uu-N|2{&V*!dI!{
zo@PediBajE(MB^<&L$-}e)Hf+cuIF%emSJKid$?K`Ofw3lW?r4yXP6c4ZHJ+V)?Xx
zFv6w3|Hx0B=AAB~>GJW~vQ<zVf@Zc;z0}QvZ6Y;Z)y8#|PFihw<ftR3b8x^S<f4}}
zpTEiv#}4HQIjgd{%7v$=pT1oU{V++ZiQG*e`S?QPlb1?tSM<j1on3ktht|tFYb|C9
z)BZ>ju4EF_^!qii7fY>@KQS;-4&21HU9Q|~@)J38_|Tm{_wv_=vfgv8&`Z|50?-$i
z6sDAx81TlyFIn*nF|mI<!E8mDL2n^6re^i(zgPJ<$QbXnMmntj4rZnZ7AYx=Mi3u4
z|H;cCZbtgzC71R#zu2ZA7sl+R1^rmIxR_I(Nz{3xE1yD<99j1$nQ2*`&Ioo~u(3}4
z7Sm8@5Z<4(@!)30lv)7IJ4WWy_92dHsQq97!k?Y`Mdg04o=)dCPTiW0!`xL?CmRch
zF_|tGPX^$M%WY5fBiihfc<x=_8cc8)avyJVuO8=%*}FbjajR2Gb4G~`_r$F1)8QG8
z3W%Ed5b)-?>-=0p&?{+N0j}R>-1Vp<KeXoM_SDTyk63=Zs_;b;-`o&CkIQUY2n=D1
zJt|BRvD}OCJF)C>zJ!&Tp~i|Nw9Dd_)zN9)3-}z2sg>zpfS!G`{L?0$mIMr8SLaM|
z&q%ZnPu>l#3ZFdsVbi$w%rEoZrqQPpjmx>eOFXh6$@W#K=UkW+rwWn0(N%d=8uvjV
zlib^b*U3F?3H8;+D;X<BQ%{R~j9Qz~OmMn>b9rCwL!jUT(fBh*x2(K3scnnJN)2)t
zRIkSF)!a8bb^6`aJbRCEWv06{i;$&bI7-j-uG{{5%p98Zd5txD!mu_|Guu-@gL5>g
zwI<Y~BN_e7v)M3y=T3H!UvFx)!iZojN+<0^oIz7mG^c)z8q~@>Qv5;D@lONWyszJ}
z-`L7KZ5y@@6PdkFb0J_jc<fv5iIAfIA<azOQL38WXnufd<hzqCuMVx3(PByY?9W9H
zEN}BfMmc<yaTu3!%yIFjPnXFi*8)d!qCT1#EA4WYtT_wRoRcJAX2BY_-%$<DosXV~
z=qu@VT`H1FmZtXc=puhWj+MqjXS+50B<|ODF=@~Tp?&1T#mYfdYtyzLp{OdG%vu&s
zva-{$<rHL75E@U!;tL{!agjjky!Jwk;|5I;Inr5SOPLV92>>JWOxX{#$)2V7VikL!
z{;M?l9JO6Nb~+-Z7bg<f@c%5-ro%X*dCBX*VMt@M{}4eg-7)iPpBXXabDd1^Q1-Ar
zRTu`XcY~~7*UPNyCAS5i{>(5|-`2<Y1mhhzATC{GqYqfnm}jd(I6bURx1L(I3Wg53
zffdW+E_?H<?sMuh%AZ35*_eTioP{L9sC1t$9Zk3FwU+T{1P#4xX&*(@!**778B7lh
za7h_C7-AV3wxnV-^n_naO>~gb+}l^S^h2Z`unLy4J*#NmNnr1YYd|d~-oX%5<j3D4
zv;KwfxsXHfK<X+7Cugw6Y{T6(s)$ov4_;(fG=E?5K8wjJl71k>BBJGXe7IexTK2Fs
zoq#OoLI>e_T4AM1iR79=Bflv-Jnj(2<tlh$VqENV%_L?&_U^g-P)8aGhv#!j=gmEh
zRlgbQ@qIZ-Qd;D1h@6VPQGe6RA|X~q4n5SWz8pV7sb0($QirC$Lmb;s#~s~JI9I&5
zKiaBtZ=5CZ?8T6BM@a{9-&FUSkQP3nay9agNxRcMn5)=a#|V$WTnv#Y`x|eUN_|||
zGod&{6rSB;cEGwS$na9JSy}_Oxc6>O5RgE2dZy0nfC4HG|G4*5i3kq?qDhAN-0>LC
ze*mE3jQrf@bVxp}Rx6W?X2Ji;5?z}>D&Ab#6I>*^ng*|-gL`nl#Nahv_9yF_{2#W;
z@Oi2KtfC7Xo`(Wp!NKTPqv9E7Ud1_kIBcey>i&O$sw0rrGm$9%?xH*eCDr`Je<`cl
z1(|vb_*ftCk)rpx^-Luj=PhsIj{(CrEF$~w81|#D+CvO0)>T^<gwypm!w~JTjKEcd
zD1>An`r6g|la?`fH;1WE?iJC^&`*B<U@QE=VU=xI6t6!x_oVKbBpf2vtjA-727eY-
zCbddu&<l@s@gcF4SQn;D{1=cdOv|`x=Na-*AAfKY_YrPo@V;pzn0vmOOUi6tn<`fR
zB@R7?&rQ3Hd2*Cobj}9RADnI*kN<p`JmCtLxO4aY+o=`6t8rw}#{oXl?_qyKaz}r`
zUn;vK5Z!@Z1byi1n`4k|R-LQLnb<?~4}A;s)tyi(8A6+|0*H@-4W{)Ma2Hn1x2nLs
zVZz9U3E~x|0%*QrZ`2yj9mB<2c4OkAOwD272n6KdA#@mLfB>pHRRsVQIZ{v#EP)gI
z9AK!6^PGJ<?Qsmv21v?<c0KT#U=R?B_X~X*aCi$59pS2PS?O={2ItpQcZFYs_!}Dt
zWoZt{PEGv)bSk(SXdrbG7>l3Q#qi$HG6a43bXfMHyv(Y09dF<Z`*Y0wMN@SKH0Utk
zH1x|{0<;h>fUgkF77`RZ&4d0X$R0z<_O3!iC#+h=@fHj~Fc|8ucpqO2*^=Ke%3g!m
zo$7WlDZE)sRym%8u)vXLmz*Fmu1>l@+?C_WIWXDIeF+Ai>nl+@0ja@-JEkNKMzHPW
zpfs_mm$0d|=-=7eQjWsrFUJ7~Ct86Jw$7P=NjP>uRnkUopX`n4u8n&EfQ$n05TLrx
zV9x{?4M;nXB2F*#3KeijI}(3Fv$LbzTT9_Oy#@m+z@0*`GTn_26G%DqP$%GpY>4Oq
z;chH7yEzmXK)ZR^0aU7iOJrW`ElJN9OTi?XT11}z4t&MY5vmNHcLB)h-7|iuJaUqi
zNGCuRjgOf6+W+9dIuQ6ab0%?2+#d*i1<89tK0b=dl!25Hai5ni2j!8gptc8OV0x4$
ztKI|2X#oFV<wo?_#Kvp}u<{90!SZNZ1sjF$5~5&f_xfP2^Gd4X`p1&~k_UErnHo3(
zzDFM^fHYfC@B_XIL1ZaNK`KZBwq#Z$64n=+)gORwW-2!8c2?e}Fam%sAagRYfxu{b
z!JD&g!+uKQb;0o|a9D73eR&EMy42!LOiX7#lS3kSgcPx*l)CyO<JW}{e$a~o4Bt>U
z3An&KgUXr-qu`pI@?uDS`~y;)uF{O92?%!tjm2}-_uymg^VajKX>B+f6oH{JCgJfH
zX@HVZMy>d0vTx&6d=n^ux>1@-jEuxfW-==zcd82I5<2RDB)c;mFjh!`5A9gaxeg9&
z>I1RQyc6;t#zQK~Vkijx5Q4&vWS&DqzaXgg17{>d84EZFW!%2M0`X{?(t|txr?cjQ
znp`Hf$^h4bCWZfBBxso?_^*4!OJ17+h6e>h@4&c}o>h<rqAG!$&&;xd;7C(bhNmm(
z`jXGVGp<sQz6TP|ATW9ZNnUpowvdG0d~Y14PzvHkkHP+9kO?acuz^59fmQq@jc@o)
zlg*08J;1Mz@O3cqeFD!a3EY3b@i-dz$(to8nM9Y=>D7Q=e~nW#R;6M`y#zao!4o=s
z8f=ZrAXq&NJ_9Pu07=egFq4Zc6LPd^&TV+H^RfTpQY7T?C4G4dHz+85vVTkc9HtUK
z!pBtsAvkDDToDEich+6dI<LaLe=T(He!yR#ypNz-Bjv_j>Jm(vZ*9X~F)0;U5lh7e
zUNUAQQ_xrdYLLhPi0(6B&3kC`AbDBwBXCTO;Rdp!6ACI1o!i2z?n0z1Aoa%1iYOFw
zy_&i@r(X(c%C}#_Vyl&rHHKLH5E50VE3#W3gHQApAhn(~&_ffdRgzq1>6n9L5GTLP
z$4QsV=kkYRYo}osndt<<1{pHJ<}1(G`@bmnar<gS^Pk^)8{HipCTf2GS-0&zhxp9o
zUJvW)(Pm!Dg$WLs8viv@_F9P4&iL`?qvadhLw|q1!@7_4*Jc7rk9x-M7r(v*W=TUi
zD3_YWXx11WzW9f(bfoW?TuiJYDWmS<3?a|gAn@IRE#5FVkEzZ{?pT(&&4RBz9QPhs
z8FJyv5rSQb+eQk0LMQWgcThM?rG2=HFMmtI)g}zSiKp=uMJf7aZU3c5XuVHm)jJ9W
zK+m9g67bdUQ9g@U_Df2ZM0{C!)w}ch?(PdsWjq;IEii1dHpo1(?C)=i|9F?xs#=|&
zaZ=F-OtFx@8dzjV>szTV0z3^`<&tY8-(-n6mm1Z7pCd3kt3%#?k)<Q3Mee=)VDebG
zKN$6R+rM3?61yvL*xnbdOG(L|b`zfy4ATKv@k~z$^LE_^xZZVF-aQFM3Q{bkgzjV=
z6O|jtK}?Y2%$vg%b&00XcfJITl&>9Nq3p+r5Rn&A;KEXP251|;4zkNGSNtlb(8S0{
z+z@Q>?;kzoBg(uixv;nh+83_<&zG}f3OhSv%3V`2_&~O#o$jW3MOU;W9~6s=35?|V
z1@yIeO^>Ho+(oSTlf8@2|6<<s+@@2=u4GtF#N4wIm8VQ|HWLYL!%k`2*yPXVQwcuU
zWl+QC{=o=ZdUntYv^E`QzxWd_YbA5h`jrVn816nAx{Mwf^}MT}u~Xf!oSVa3js;5~
zNw`Zwd*+W3?Ie`*<4T$NI3{wfB^kKI^D}qfg`98q-M9g=o%hW_J3plFOGfvYC3B?Q
z-o7UTzXba<>_?nP&$hq$OY?j}qSw46-#o6gi|0WX4~t3r3W>BZ@Yxu@iTQh<RTC>N
z)ZKh2D|_uYKbb`b?dn%ZH(nz5O6pKd+VNAB7PM5ln74$9z8NpBdXn?_%A3Y$;MbRp
zUKZ=B`!@S9eqojKy|@z?)HE+)6&)Ice|73&)(g$u3UmCzV8VE~oC}$r!^a^mc~?&f
zYnKzv+txIp@NG>u1NGhDy2~X0Ueqb#56Cd&qR)Wk<;ytibdPT`qbG(^3;!;J=t8GQ
zp;vHt8|y^w>c9ww?}|>=xo95QSu=rXIyRvjpAK@KP|(XyrX{h$!yrBYzYJ7_bPGh4
zf>rpDazGy@e0+QyT5vyC7&QXmrsf_rDo~fGMe+*KpTyXFX$R?v!$AVG+QH3WAT>4s
z6gK_6W+;vUd3%}ptG-=e1z677HA8(d8{>*sKLVjes~q0(jyE8}6<3iJ5m^JAGFv&|
zMk<MtDadj(URl+`H3PfQS;#D$I4Oh42Z}fzZukUKQZ{hjkebsnTA;=uWv>An9=Heb
zG2}V!oqtbe|3Z-734TX}*rCLpPQ2IAMls^2PZ{hu^$->w+?y^SD1?vR#iMHaU%s~~
zILKo;zWhHtB*HnZn=?c_^Jaz-fO)^bq*(@9Cxd~%cVALnIs6ajCvV<s)dOG^FTYb)
z;{2zFZnXXIFW6Rn=UNGo=BCP(^uM0VqXL0ztMi=B4b`F=Rgt3S;(~$aJtUBjS~7p~
z3gc}{0dN-xE;Tq;Jd6wpI%!GZzHA2n*9?l|D^zG7gLA)@kbLN&Q<w27a4P82;N+4?
zXMcgPJY*(<9LctG%z_l`vGd;;rM@EN&>2__|4p$LYO}iE{y+Dn)#eQB2@_Kg7?GsA
zTX#^C`d`8?OY}+~`Vlu7ikH5f>8i~z1igc&eIQ$U5pOMA<5OU4STB2#b@tjL$hL0a
z&K(An7Sr?vR4|a>1tHe)+3kumct|Ui5aqz`EsU2IPf^#g^7r$j>j<2-@jA?vxg<D_
zya6Jb4`9FnfaQ8MW3!x%nu<dkVH#aiqIC;Y9vxvW($hieo2aosCS=Nr9s_xQ?8+PO
zdCj0F5G-yDPC9lu*YLdy1lhXgQA!p)z?bfWj3$UL9v*^#y_M#E8#Ea;s1<rhF@c&c
z%;WSGz5(cT^R3NVE&LFWESaP^Sr)}LTJ6U{{@|28J%G+iK;^^L*en2HsS2SLtPT&}
z6hA-;xkfea_HqXE__8jgK`W@0Ov3IDNP8|v^j<?_Q6p$HWG&(i$fpAHgX<O!{Ic0_
zOj1DmF`yDM)BeNyq3Q0vq81GIT<U+2@=!o}b@1$^n12H2e1eRU=yQ(Tlbv=>C%U^w
z_rsutI{;vhzlm|X1Ns^}U_n6;=QI_vx9<G$lr%+TV#XdIsxcoQ%^f@n`R3pVN`!pQ
zAaxm|+?3z%fw3}@=o#XV)~=Fl+LY;IFQ#Fu^=C-?slO+K*74xk+f*OK;^B%1;C}pk
z)|vt;GmnY|h*3rd8XSb-=?-LC*w3v^yymTMEgtloDdI_P@lL{^LcxDEKjSm8vjQf|
zt^4X=ZP-{LoiIr?2^VW?5w&GWMXUbV1N~Snm@Uf<#RZLomj9RNqp;QN(Xtm<6%stv
zJ@qHtdG17{@LJwo70pxmPpZIF38TR8TK>Ff`wue#SS39)Q*U{e6mJQ&kCbl4hYQWu
z1M@T5^swayZxEarG1piT4-_>L3n3hb!NSKhtq(5GVh<mc$g~J>`$9%c+NnDl)oiV>
zOZX@&IqVyYs|=1)jA=njt7AM*Qt6J>EzT^m$K?N_LevLF2X)D}_8!h|lsG!QDmTbi
z9A2(X<Z}n%=5^@Jr(DE!;?i_U37sW_kPs`$zvO?AM$Vt)A~IbMX5)d^v-x!0cC6Ym
zSG9S_zO+6Rwy3l(V=vOm{#Y&$a;4hHr8=N2#YWs_E^q@b;7Z22kFWw)x_$$gnJx19
zQD^Lf(mj}e*Rr`@kydYLGa#NZ?;ylgN}Ye(K^&6>E#!~#j%m7wh0W1se#9RxhNvLB
zZ-ZqSFDG&1A2F~!j3KNjFwR8Y)-GW~e!IF!z|h^eZ5<8iU&za)2A0jYq^}&djx2D?
zxqT$oCVh^kQXCwBlu*LBYUotS$;tD*?oc2-=}>nF%e6)!hi0}W;4{tH*c~m%<iWCe
zwBnw9wQ4&HyRm2*-=Geo={3#QtTzy>oXEkKu|CPaGA=|MbZ_I*e7@H)fJXZL=tyT_
zV0+B}ej_d$5N8jY_xgWHx)2s>wOvo_{Yp|^s_(H=uH61oA8utq)(#EZ9n^Vage&lM
zRjjxNwG)W_HamY2a^2N27d>-%VCS4h!yCIFlTG+2_vVxkVRCv(zE~@?u#4I?D~_z;
z8_R=9#k8bXTK434dhVm9@LnEd9&Mh-VCZxhgdsCMUbat&h-7-1>esaYQi76$3!PVF
zLwuQx*pl$U_gOBX$S!EN7fh<#fH}LkDru~B?#6pIfm5|UVo#G;nbVvaAat}dkfrCm
z^c)?EgX~M<Jb3s{C?n8I(}_|HJ*F?`A<q`G#P&47h%kXtUMiZgjWY1gTx$gAQq&<O
zA>@6~s?*tKJ|(P=kAmFo9ZVCc+<?~ww;1PFqO3xHFWlf{Yj?HRx@<e@!Uqp_(KHpt
z`km>k%^9^WR&>NGST5<6(pTaGlIn23L3xvqR8*ZUbL=Ae!y@b*wZpk{N1L)QD8f7Q
z)Iv~5MpUyxbEzKogx0U4HLVuM{X3R3Rm}gpx@Ky;Ku*de^3OOn+qR9Z%5mreIVaOl
zj%=JxR+n&NXlv5qc)6|0@dE&cQ=KP3EL=iQJIY-C`+gGduwNuY&^1;&{IgeNw>&!0
zrJF3%8qb>hW#WEnJEq;s`H36RwCKB2ojTJN>$6a3{>sYdD?1N|RE1abcI=VRFJu?{
zlb+b=@(6^_rcXeza=P2HZQfYqk5^5oV1{Gm0ELdd)vVjwfh`XVtj@bMA4of@(TUPr
zDtll6m&P4+>d44Vp~Qu?=!ab%miY?vj;+CCF@S3?r`mVMaGci8Zb%4DoV}XQ`0mRM
zML`a-kbEL!BHI$J17d8@f$DUVDCtzTv=b}yw_FjWRENz^PiZH#&}}!W_YRc4%DJqL
zcg+kD2M%;~cCp>&PdkLEPW8zWK9AveVt`3<1mq<;ayfK5ZhnE2Gx7N32RvzpS5`py
z5Qa!g!M)gWzAa`#l5Y;O8n&&Ku5I_`)DYd9DYED=zI)U;zYtmF!RzznQBPopGVxG%
zOY4yjnJ(5TW%&NO4vmk;=qr>6vM=_dp1tZBy=X%Me;9kKRLnY~FnozM*S^)R9WYG?
zRt(bdtn&uAcx87mSGgUO|JHcxQ`yq8(<i3;+6JK39=yhM!y|AMry_JliL}ClyxcS`
zcqhj{%)T+-KQ(kJYI^xSR4>yl2S*^D%E=g&mol+*N?)VtIrM0RbI&LCVmBcO8$=-~
zwHK2Ny0{6B0Wg?gezCP>&!tiF-hGVI28cuL#I}&sE7B&e?Q2w-LCfe>X0<d!p1hR$
zrH4^h_51Q(l)^}wEt+Rd>$90tnY@(fC5&uEr2ExPAbun7G{M=tlC_rAYZTbMiTuZ{
zS&G~VGne<6lq>tqBbnU7I{{{Ul>38&!Z>lBfwtCLwK%8h8(J6*wTH-7H(|49bQhjN
ztTyJZvSPy^LdE-@Vh5<oT<E{Ua{+8PiEW4}I&9=hsXB+Bn!8jmoA(Q#Lj@Px2%f1W
z(_TW+>jFM=Nxo<ZnuUTp8&E8V*6L}@=I(DsP74k8#TYuNGa<2N4yqxu_v{^p_)=8c
zemKcZ7IH3(*L<2k-76?>It@e=e@+!am+sAT+Z{*%R6?~6_xLw9CF&Gk?oaxAX&ZE3
z?BhjS?a#2al|pQ7zxqIaseEcbuct7?v&V@wx22Y<Q9v?7Rco5@e%58ZpTxz&Qj2GY
zaJRl)`WZE?p-PwCx*|%xp~LG#L5>^e2%DTL2`P{tqqW9aO3jB;Fx;sBj8ilslyO<S
z57EQvNzR{kk@CFmR68`{=52>g9^VY>B@=Dg%P8rI^Q^mjCfP3}@lh2fs_8dq`IZ&G
z;X&T6<Q(-MkCQl6CD_BM`@MGUx<<>G%a6*aGsVRY`Aq^M_n$HfSE7JJleB60aP#+8
zphq8e&0Ed*o9*q@=xeOrAC(Tw=${E3-uKCsb8DMuTjVZZ@&gf9@93xaLSYl936U{6
zQqt056Owg%zcU7;_RYMacJC6^Lz+5z+s|KUiN842^hj}55q(I~povP-N!SDwuZL4I
zefBXIbn>9J12^^wh!H-;hB_<(0{I<ChCTJWmS6-4`CCng!`<E1&B6U)TNtPOu0!*&
z1@trIm7O3!<UeBC)1ep}cMf(X;+A2{&P}w*GefwOl3Sk(-d*Kh;~OvnFG!U=B3z8B
zd|na|sXp97?^`+H&|<#d<bSuyKF<Qs)4BEzaMvwaYGz-ReKj3o%cWsO;r#e(8AM*4
zihaGorwUTuEv4(zWdrB-hA8uLKX3M}qkXHzDRKR~y%Lwn94Yl07^ut-o&l`c{@svB
z(NNJ<u61^MhV^QR9+M<Ny_H6R63%`2J9YS`jFP0}Qy6R}l!S9$^-mnAOy<}~5U1?Z
zv+_hbow=QOZ_i$nBgBELcllj!P;AvdcC1FQ@fiUDsW<+af|=y@8wyXu<wbU*-IU$E
zG#`Q}Q>)xC<O0jDXCOQy3meFim}F2G?RtCZv;6sv$bGvzlf;d2qDV*w3CES38u%v7
z_~`C$Hv_4UahmwY{hf4MkR2#SUU(TaC_iSBWiL=(#>ay_C#?s;A#6>r&#Ri;<MtBj
zlHi@<8$)|vI5#XB+(T@-6eQLI63StA<rJ=tx0P0<+heY=&4rP5L=ZYge<6X%l%<eO
z(>Z8DvA(G>=;2u(NC-!1G3<2FVa{ub4qsWCF%|Kp%9b4vQ>Vr$d@4+7`H_rSoZ{*s
zaAEbErte^1xzCD^4G?BeU}!G)C#^87#_VfVgP7`U3F<Hgub4!dX(^#OmSCwoG?k4f
z9ujfL3XMXnYxXL?+KV^Ym-gq~ne^B%NRYl5c+{laz)4KE368)1I4ZXEZ)aR+p|k3h
zdI&QmjIPbsr0vKFE?N1SFqW_lLINJupKyWpG4;Q?2HJhJwwCptkYaunCDg#F?EkC<
zmzh=ExOtX@zT_?J$KOIjHW`~-xYkQ^rky#+f+1~3SV6v*xK|rB*eKN4Ywy@PKMC0z
z>St1-5^NBj%u%DjaUuULWz>+p7O9Tpgf_NydE>&A$?G)SO<6+$LU+D6EKy{wu8xkq
zHOKW3ZSn3cF#QbJr%wq?A2cpi5jyeP37#+bfg83vC4J;6a_o=P{lG)YyCT1<QtCrN
zcf;)TJHf-$ugb6EZHELRF6srDH;D1S#L?@BjJP)S*|)7d$+_!pgu!>Tx3qofG^b3w
z+d|x;9fdPmP<%cylSen{j5dpX?D(SlVkPr&O_}SDN?$jGuILfR;HeND3vu5rFS_@4
zLiO%rDK22bep&*^75yyKN*Jk}wQYFJL#5{oxCH6&F@am13CR;Yr9y=LQ%{aDqHV8b
z!lN11=}C4H$ng=xl^VnBe;^szgbuk)wNpV7;AiwFn9DzN-KJ@dV(}QsGrm002z{6R
za|~bpky+WBl0<hgL0A4kbuQ`ca;+%_Gfh1nMgV^xWF6!zCKl*lh+k^Lddlqsm<!gG
zr1*H<?z3159$z7)FWbgQC0(XX+HoF=s(qo48g1O@Z)kJ%P|S$Wy{W)0702O7ix*_D
zT0W%=Q}UpNmsE8t$FDs(&*=D)v*BEX1Yp7lCB@cidZHpaznvxBjGgb!lswT=$($Aj
z%xUC#b?0iMg*(P)nS;Wp^+1gM;N?hErm{E6iNA?Qj2PS2h>bYy4<N|hL^}kJO|>f8
zyU9T&<_=8{t`Un<{B6%D2c+ER)rj6*9RX0y9$%#yB9A(e7zNN}ty~^3BmuqM*7ROA
z$jlV6Yi{^eA+?m0lqBH&c-cM*yL)0^4;0d6O>%mfUxb?jVYQ?Yg!JuT0HNVjb#?C`
zz*|6S(D4j!ysm&gzjqObMp}LpP_U^iv$t{35XLecf|B?n-eAQ$EJ7-2xfhruQ=;#5
z{EA{c=l0eU&#qxo&3JgU4#=`%-S7^fNZ~P}jDWAyd1z6qm#hKNK&&*e)%+zVs!64M
zT?qC&MAS?wfMajb9@RZ5;+s5Q1Q_tu@zb-&(D8|#a}H8N`g;f#I?^S=v{V$VB>IVq
zRLz(|QATl#N?>^S(?Csn-Al`No1PT3sl;2UX~2qY2ns-;Z^oI<*7VvcP59I3`?Yc(
zxGg;cgWa2RXQ{eGP;{5+6e{`eol)}bz<;Buq4-};CjhILDDVSe3}VD(ZH+D>E$U|_
zCClNYVW9}bj=u~03m(JwE^!5>44O-<Mcv=x`hUmxq<kC}s526M2A-n*=d}<6TAYdO
zLoT(Hy)1DZE_#V2U#EtzR)f>*7T~zpXGsJyl2i_}wQ>RR19Vv&Aw$HJj=fbY=SNe8
z4k_y`)0v=tB@U!dOEVb0%rx%%eBG!(DZomZCt62#LX0w#-U0jJ5veSwS(cKN4hke#
zFEdsKKDsDO%}suIfD5_*Mrxc~M&Fg_iaY-4BG^qLCc@@l;876V%>RLiq9lwCtztl$
zaUXuRmV@OQ%$;|^z<ZKVKrwjN)t;RDLYuwJ$<`&yhD&f=FxBf3D|6J2hGvdO61M?)
vG%ITC+xZJmv;F(GN~(|$ejvry9wLIW0^67$s!HHkBOuVdXoN1;w2%BBm|SnK

literal 0
HcmV?d00001

diff --git a/docs/bug-reproductions/8979-screenshots/before-fable-hidden.png b/docs/bug-reproductions/8979-screenshots/before-fable-hidden.png
new file mode 100644
index 0000000000000000000000000000000000000000..4100383237ec22b748ab62e9d63903860344d521
GIT binary patch
literal 24212
zcmb@ubyQU0`!7mJH%Li$w{#EPsephqqI5`yz|h?wr2-;|ba!{FGz=x7LwBE-?^(Zl
z&suk#d+xdG_!lxWd-l8cyPxM%4^i5hN;sI$FcA<Ca8#7#brBGd&=C+2ebJG?Z%%TA
ztq>6K5me-5^}Tc8xoG~xFIFz_=%6HGQ1(wAg`~2Dss#G!%vh1MB=YcYm*qE&6R&38
z_l2YQm{5EQp~Cvair)Biw@uYxR}wnu(=j?V-y}RVrs3x7mU7$vk41b`(tT?wOW*<4
zF*+K@ZCLq91<U7T%O=JD>iEz5$oTm9=xBZjIvsuJ$@WCPq~Cc?PnN(NLLwp~Wj#Ef
zkf*4rpR_+iP%xiHMn&;~_f_K+YvpTt$gqUG&2Q$V#ZZVLDKg5F@VR6ecK`c}%~vU@
zjN7!)r3)Mp!>?`&0b>7pI>2!Hd93+)^1Fx<Pr^@V^>s~@_x&P?%T?Jq5<bU+Nepw2
zMBWF8(BSrHQXVHJL`h|3<;rApD1K5Ll+MU4ikEQ@F>EkjI%usstm>~rB%ieJDQjLp
z^x{`WZ0k7HbWRl>Wr)B3Z4?p9(o|(QwNYhI96o(_A}^!bJ^`xGfbU60V;A?_8QCqp
zLbPE|;Lao+Qskzv)=M%=E2}8t9Rd{@!<|%Fe2&SCRGG*@rS3$|CLzm6w@=*W2D((V
zzMs%)yWU^7Z5EZl*cm??R#|dVN_bB?g)(ZlpyPXil}1xCV1H(E$5m54Pd?IYm7IH$
zz=ctOKj&U1rX%|q5_XyTEEraQ-~Az$7F!<mTgY;zBO?aHnuig4DA_)&t8X~ew6k81
zUxpfP`eVgbs$1r$*<*LQKZ>}FvG7$Z2}GWjFx)zc*Kk~X65$~K6Qbj%xz&J~wT^BX
z(Jv13)$-&Kcr;RfKFP>NIz)pj#)!?G>6Q9Hh;uH7FbuiD>B!82_NDpN<<Z7@y?#ju
z{yZs$T(vS;Yok{>A>QUhKF!Sm$(Nv@Y!rJHp(GJ8Pk5%jEIOSVa;9&!ic$hKldlXC
zK2poQmqld*UEjdKqMvRYJ|xnl(+DlL<4O)amKe2K4LvNN-Uv?!i%z~g<P+jXf&}f8
z^P&2fZkZ=tW~ErVD0I-lF!S3f)D4Mej%B=aOvAXU^cZyV+)$UUmwApkE>&b2DhpC|
z;HE=1RpH{gCtG6_L_|b3XI%%osB}>LCQQc8cD)2j-P*e~s%Si4@jURxSBVJFPLYbv
z%ex5Cy^gTQ-@wHax$nCZ?rdn<h*ZELM1>%Ytk^=9iM;6G+Xh~Kj3W86ck}!d7aN?>
zA47}A%ao~eSg8a!aqa=)5LO0o0^W~rh91gx(?apP(J(^sA?P%W*kJSf|MwT@;N6og
zfxq+j_l~?Xm;?Wf5VLs)<PIx>Z-5ebT3i|r^!H)*p4uD!Q0bdqIkWO>2;9FW8Dmd-
ze1PbqDzSP>mm}capO}9yr}bg=|BB}r?^bDxmIE)w+7a32W!GF6WS7Ser)+<Gl{P%a
z-N+)9lvadET$%4A{?wV2otWb`sLeQo=he=&*Vlu1X^UyKT(S52ttaE>dy59&w7beh
zUDtb$|BS!_E|z&ZZl^1b<nSatuKr{^KH&CfDMj+Xz=dwgs+7mJ!6ap+JZaf1n|I&o
zAvTUZxsS{K_^Xmb?dj+Q%q*T#OC*5L@|%god5SF6_cZQTtjyO73mKWG$4l-LV|kK(
zbCni#?|!o%quGq4?=95*L!<HMeg9YAx@WQ7Y9L;C#oOxP{*FS}$)WmV<g-|OdSN0G
zi^~ff$Mhwby?nN>Pp<H3o0#+7k=`4_#uAmY=`fytOeQST+xN83Lp#Eb6%uxTmo_pG
zvrOdVHeCs)aIXa3?6vGSe+N%tzt4se1oHUcA8icm*?<00P*Bl+{dYS*h`NLqTxnfq
z&TjLbF!5J2KF%^Xm<m`_DiV^m_hK`f3FG3m3Xbka>4lJ6)0PYLp#1%XGT&X;k1J%e
zyV|=$*A!1`KX{c?!1d->c82E6590`!X{mk*zs+zex9Ky<OhJ2+W0^rn^lnLU-edKA
z{Hnv%S!qW}@7S<@VznT?Ligfl#LV2V*6q2zVc7@8j5IFYN|U4zPUoed)0r*7mir`e
z-(6|@Er(^tY0a^Zf;Z=T_Cc+_;3s4>+|zU-5^j^rZRv-sr$irv-8}xy`~a1<%S-dT
z#H=HbO3Z`zbGQ__XOU`Jh=Z2ef<PeHw`+`?-IcZzYk3<T`IXj0BMQd@tqUimN(;i2
zE#{IBu|wHjhA|68SY}VdcO-nM9gJa4)h^rZ4J1yyyCIjW(`r06YoHi|+h*Dk*k*?8
zrs~{wHWQ4DW*8q6W53+|zBGWII)z2cmI!lpV<6#SE8BTcbu3%BLM?-P#n$kz<6`|D
ztRrZDsVPv>|9ZFhhDtGkI=6OPE&_LI+wY*Q!F8km#rKyu<ot|9Nr^YU$3rX)PRrLP
z6VgBP9EXy*Oq-u~GDFal2)f_5{LOOT&d;hluGb2bNOVaK!gbJX)4D6IpPp>8Em}u8
zt~&H+u=UA>C0N}R{3I#9A*K5$>`YDMUS$`|2%ZD+q57^oOGCbjY++~6^UPOq(Xh#Q
z-%d07pUlk}dNI9-{;H9!naOLhGx>Rc7_`DE)J4;8+H@V7hF0HULa9~Ss7haU<{h>0
z<$6ylg6?8^4W^SSuX>}1l;SCkKtH@mQT0q20nb)Z#_Q`F*n<-kpZ*v0!t?jl;>9`H
z#j?Qi$A-2t|4_^#xa!{tM{W*h?(|PV4Ve|ArZwXC@>NKDIKvrbuS@OvEW=9FZ!3Lf
zi@!IZ)MP{xb3EHt+Id-SLjH-o50&Ui<}Lw);#`aA#onUQ%XeKNC}iue+k6Q!p7OlD
z&GXv_y?PuhMSY>^X20dTLC2-Uz<kXcgNoO2Cd6O^HUBFw2=dij$g>NzV8CF}%DY{Q
zph4%?7SuJ4dnRaUae27b;<@L0GA0ZvIyAmgdcb9;x5OfUY!CKr!A$IV;bl&3*A*5i
zH`j~P@5ar)TvR8yuL=r62vGUY&NUg;xvt1lESkLzUKjNDExywU19y3r%fSEaw*eIE
z1$bagn)n@Gd#|CSDDv)ro!v96hw-pekl@s^C)9F(wVnTP*n{^2!F!SDwa4FIQI`lW
zyg`v#zFbW+c<u9WcfnR)z;w!H0ZuI)AFJn0sJI0zNXo^-*?;{WnzEV1dX*>Tb>A74
z^6;_lxcxgfj}B`Gj9JI$7~4*NjQc>!({g#GCzUn*&eOcFJd~L$N9=v{^Q0l(9mIGE
ztd6_$Y%>DCk#sI}<dV-L+%2Ppxf~U()9=VO{Lkm#ET5&yB<3({d`xB4>0WFPxH&IU
zHN~zGa+v$z?Ja$Mdon?goXn&~2*Y<#&lUR(N`EAJ6>n>k3vw4?ptHmM&TyYvMiiHJ
zt&IAr28jc#WhdkA-vyOX)6Hs9?@#77c?AWdnrzt>_rvlM{Sv}FKX4yPU;cQP!*X`G
zuCY+^^2e)GJ-zwO)jPX|+P4W(*WdDa6V1L<c6EaqAEnbuL#H_qPbEjj3i(xTY79CR
zIvpKJxU=y6aL`boev>!cIAGC4S7OHbF73t0G3>f6Vna)(s@-LC^X>g2MUdtCG1rl1
zl^Ad1;+t_32SqB8`D@4P%8D7gpI>pJ7={r7Rq{^PhKIUB@4N6}>xXMSY;^~_iMsjN
z6JV)3=zeisCjJ7t_iF|-d$67ARvjG{&3vw>8#O;O0!;#r;Y}}JtbcsTPLwU3-_mY%
z79A8AWLuicV^sYlC7OqZh{(zwnT^kOG?Sye5lM;SLc%3%wP`z#Lc+UJ_+D9EeW}e)
z_$^;+AQ824SkWngpLBNjBC1xt6qUIg9aI@@jX1oUZ>mA4;=S6*N0bwV2e-}3O~J*3
z*6Q*2o}(A4w-;?s85U+}1f2JB^Cx;(DvaypQ=*GXGq_)VbqQXD#Z|rgU8)%OZ0(n@
z-Q<THzv>IDBsaP~vj!*ASie=>UQh*{!TtzA!D<%9y#sr65RV3wLSs6DaO;5E#>U3f
z1-%kxf6&g8*q}#si&Uj)4}m*%UUj7uRK$Xw_sz02<NLFR)j!`%bkyv8S<7p1OmM9C
zz36JGXub^+H@juZuk*v}XmB`zbr}23Zu;c^SfSpG=Uq~YH}P*l6|}f`Nh2MJ@QtD-
zF)^_cAUuS&I>*Hsshz`RFW6_M0>!xMQu7>oSyf|Vu2;VfnnXK75FHllag6vik2(+1
zG@d4clDs!d9VQ-hFM$R6^YKmO*gWH9@z*eXdhc#}>?s|e`v$#@S-%Eu9o7deac-$$
zUfcWTHx+GP9FiapnN3Sylk;+_ZYQH+Cfe`bEUxg(IM7UfTR2%Z-ilG3@OJrDwLE7s
zj4c<A?X&Ya;`W)x-opFdNP-zHmex!WSIZA8OQZMTp=teh(71t%gxk>%YELb3{CZ!E
z)&BC?-St^b+B+WjGb78-zGr`XnN|`|vB?r^Wvb1)LJE`;syhScTP_%c@}IvY{5%m)
zC4T7%z!gO4wV#}|avp-qTkZB=8>SzrrCk3W9i+#9Z2POczMHg1VPe)WTze*Nmeo-2
z96ItYo$VS9e{sYz;qmSDXPq$Jhm*Z^vjk>rr&k3QSIGi_EARVVQ+__NLB;HA+yfNH
zZnoU?Vt@JSH58r8xZeMCN{Pn*P}bh_t>Sx&sV@qi-$5^Y?Ymo~qoZ@aMdM)u-hOv;
z(U61)sqRC(psea5$>21acJjWxJOaPB$_TnUo28cYP316%$3!#LiTD)pSuWy!;^9_n
zzS_odgP7x`dKQ152!RY}gY5d>KAb;yT&M-rJ+>Hh%7@!+Y1fAzw7KG5PWQK0?pvc4
zJ^)}rIiG4?>i&3DxBjnEPiUKB*=>X?43n5XFH`J&DJ-`PLbkmk%8;BW8o|WqH{{K-
z`>*R&lLX_RIQKVg7;JUJPZxc8S3X|a+nXIjF48ma^ETSmL;}uFx^h*CxhI|A3dUFa
z`HS^sx}HDp3xr#RH-_15%-}1QBf(a3Qh6!fTRAEWBFkEmXZj!Dm@mmF{&I;YP)j~z
z*bhhF=#OJan|O9zH9<!dhEHUEy60zXP;L@c;|xowa$0U?*5Lly@rbJ;XaeVMR<Jha
zyhg<Y@fwU<?)xd6{kO8-n2fnt@I+!xL-?{}rLHzpJOco(WmeDB?g+dqG>bUGXCY8w
z3=mGm7gZ#4I2Y6}ys0dFOV$Nv`i-l%#~3PESlbjJDA)K7o8p3|uJi*$!rk%2eS1Rs
z^i1m;<bJ2MZX^0YI&fO(=AW=ye7=}ojd~R*U{|jH_9<A#qhq-2%!YGcD*wP|^#{#~
zMf36jfpW$ZkWOKke+_I*In&(Vr{mnY{ffDMaVtrr`WJ<E*yW`+p|<dnOHTtVP|bPe
z{NZvydaifNpVQE%3^44G6x?LZeNfusD1?0{Fr&ld0bt^J>lYhX@wyExk*GuVSc}kZ
z_O;&+ec7LeJoNvi1)vkSbrbU$ej`_JI{P@xWchGC_GQT4vogGQsxa7KV!ry{_(V`c
zXuw~CJEhqzvf-@?e~X|=uF%9Qx;8mBGA){k+|m13a)D_J8I_yW(t*A{i|SoONA$@|
z<*-u0J_PzGnxNaHr+Ta7;vPFP+nZt9W%}X`W~F+?ngAK_YdW!KYREe&63A7vS}MPH
zr{IGckd<bzUk`nX=ecjZZnNpQkp8A}*5T=JJO9@)A)uw#@mv#D{{$!K*~Ri_qGl$u
zNPJogWfBaz(rjZ3^aFS7Y&>dv3EyfjjUW7^?ic5#OWX~C#{~osbOLhdk!ZMeR`Xg$
zzyJ{`eC`e4VDgMvN2=I7Sf22@3kD22Xrwy7xFsNB1Z&D<;N?qNfC|vpLZN`DLh%S6
z8KTtx;syL`GnemX9rt?;u$4-S9vljx9I>>~MP1_tr+^Wz2K|cHlJjPq%EA_Zg&3Z4
zz48Fi5bQoNx6McxUYIYNS^F*Mf{P8#G>uvKT?J+?Y9x0d#-(#+E+cR+CI#B6sw!ku
z?9~IX53==wF1~`Q9dv(^Z*+ONkpPN{JphO{jM&WV?Ce4Jw<uU7wH>!PSNKfonY@TT
zczZm~erw_jG&D9qIFXlO#5S5}a^K$U!=j^)h{O*Ud;b>{SmFVnzrRWV4*&kDuJrE3
zIN%AR9|i5fV;8s=^OVhPOmJ2oz-yj4$8?7YP!s;nRWaNV;gfC8W_s-}U5yFD62}^F
zP;n^%cT(_-;0V~Oo2~YGd4Im>4C-94W1_J0is#;fpwm*L%UZX{*=Z%<bmRiIjgpPe
z?Iu3~c;6R8`X;5fSH4;oK*Hy;iO(}^@CE_-V$t~6Yt~>BL&8NC>*c-gRc6{E1WO{w
z6Lq%*H8OVczV+K)PAeTODF~NZV(#AU=R%#m=)zF^fFu>*6I&ub1r`C7Ovf!&&vH9l
zmF+lBV}J1_UKc1Q0Gj7Y2i@;X6@ZR*w_BVqB6$9DrOnUXdw%9dE?EEN_4%IKM2`4E
z%Rjc!(*sz3Pa|j{kF`?~J!w}S%A45J_03|R?`M%(Mm+~#g>}Dk<61ZnzyNn$bc~g?
zDEg7uIL6DTlIx_dn=ci>%eVgwT4+1=5iq?h5m$OQ%UQ#*%8@`U2eo&3lD>Y8x5pzK
z2IaT&Z}Ru%s(Q+MDZO^5i@@=)`^!I10JunN+EwV3yj2ZH?CQO7jQ?ZPCN8m&se}8<
z#3ZLd1FXxbdH3tvpI<=*ANI^U{a(dibTrq-01ZXOS)a=jdykph6T&c;>F|7rBiiow
zZv!*O7XyJAgiNZm`oF&$DE-#Vmx@a~%n0OeJJqe=b-|7y=1{zOCiu=f?6XOeTaL*u
zj^D5`5(qR3U6si~{E&~7>(z7jEp>Ga%&7t;yd@uXJg0lWXXC8Sc)Q4O%YG+F-$$yA
zGn19=FSl$|`T7;uY>($w!9^;e=tA&Hu6ashMe=k(fQE$XiKRbwn1P=5_xJZ@YTk>>
zk#9)01U9c)z4>OMsmojT#rpe|z-F|{sg-9>M0B96hXaBn@5Y--HUKCJJ@K3uk&rfn
z2R9vEuw5wa2Lk?jaMRtEUe&z|qm%N4&)HYB^*6|{+dbUh92~5)iD%~R3Q0)?f^Pcq
zfx87>4LakLPqvVwh;}^=X0Np9uYJ<(n}y2ogvieJ%XO@H>f(eHzagd!7v*KMj|wbh
z@F^CweAngx`d5Ru;G2N>z!6!d%NX?(JEyMRklaL*@R>*xU?nv;mCSP@y$EWOLHGXI
zWpe<x7?=fwxt@9|sKpW}l4rT5=+rWb%f5taE@d(>m5NOEobLWi;;^4u3a}6c%-r5M
z*$#q1#*SPcjBZBfzV8abt*T$FcQmfCjiaJNrcHo~_PcM>W}ZTHcUlhG-3#cUS(iN`
z1Qe>~244`LkgV{GldrYX&S8gtz_@@pjUckUC{5*9VMX-qjFMS3+7ekj^Cvy+5t)~0
z4<Ue9qYyA+7anAA8E^Tfx~%tN{6nz{8%oQTUQ($hno({t@3_@f0hh@aP$>*_aId#b
zwFF|H<|cl`lc3h6wAQcm3X}xfn8yRsj?(icXE6{_pxNz@Dk@yaYOa@NNNR`x;vi!A
zk7i#rzP|-m`r)=lh3A*httHlz56g7HLRb9_ij2vDuAqvb5FixLkFVzcl0cWj_fGb!
zM-1u0ko4HW{}?=K$j7UBDw8<y8sD4&I!I5?ng*rFtF2TKqv#-H&_qGf>oa>vE#*Hq
zL5P@zW*=@sNM+cWZs9wKbVT~oN^M5uS8&aory2YsV>?W#-pS(O3*TwN9HT}6Eju>C
zja@e?YN~^jug||94fNli_E!zsP2b<$X!JL(u9}9TdOwh_##kMR8d1_v@bNO%21f>?
z_mgZc`x9&w{|z;##oIw-i9{Y(@nRsRliwoRZTN0!+$QQ<*5pbksA9}KCULo}ZEaw=
z9O6$qx&J*=?t?9BoZvfoi9i~<w?gy8Qk6A^y1HU%l(FtEmED`}{Dj<3<Ua7^J$>?F
zG@FaX<*PP&JT?bL$E0^W@0t6wQl#*kxXE5FQFJ=~d>0Jlc5Bs(w!&Re{v}V&F#Fez
zbaZ4R;|NZzM~V`9e#lHl1cXP1^ero6$!MMX_C4V^`b{a0<~a1_d_7jm`&=qn7@Bu@
z(zm=``zE8@f-a*R?2$e{0MU-(#Ow}y9fYp(lXQD9MT0&-9=j`80b>$bf9(TuF~$pq
zar4{L-8LT;^rS23YqG(URW>W1Dx@Li=MKJI6)zof#MxW}?@SbyJe$8%jZw{Osi+#7
z{a#Ggt+~i28wSEe_1fl8ib`eUzqX4!)c$=e8~PW7ovoHM<QNPC->&|AJ&f1;VQq~M
z=Z`@DW4vZgsZc8{pY)|`HJrzY<}zkc40^+PL5JoRfE|TA(!^{8Wpptoa7c|M3z0$W
zl9ARo$EUZ)2sp|T3vN3eT4TI>dSVKMme$Kc6>Ie<nCWxFHc%-P6cmy?`p?OWW264k
zV%H!3gT!}pIlP*~`i#N;=LO0qxdV3u#LoP_LmkWa2U%60R6^14sKq?&0L_onL+MIi
z6P*2SFu{{r0&q^^jcR(KP6o_tGoL{z{!ukrzA1=JQGKjv(Sx%MHp#pexp&qbB1+hf
zv|o<%{%B+ixvrGZyQJ^s>c4a%AXYuik&R~ZH{+lK&F1~%HKnaEZApiI2>39Q{iZV!
zR7x!Su(q#p587Y8fRq12l2}Crv^!d+5W>a;Qgai0YED~FZcSnNL9YYOeg~!@P*~vC
zHEN9_YI@Yzj@{-x>$$GM8vTZ2V<P0V6uBl>Uf#6z><0IhIQx0uH$$uZ6HE8-feRa(
z3~o~sqM`O@LJpbjq?CjO<}Xw*e^;2nOy@tzB1^B;K8w|!XDMGkgQ{XvaKKlHY`#-b
zvUU_p@*~*>{4RZQI!d~&-ULgnS!xgPQ&br1{CC4Zn3D?R&dCqKO|qzFB)^rEmBXfr
zkCh?Tq8255+5~-ky@-XZ3xz5~lrp1~;fo~L@S3+O-(xb#M&~<&k&|#JUz@!5lg6|4
z`ZJtXkCPr&{rCN>=|FMAvS&7zhSl}aa}{}S8Vy=)8D!oJKqIT9*tU|(ux|RW`N+iR
zaJsd1_|?fiV}k<ICp7P+x#|np|6MqRlML_Sa8)-POVT`%Y(78mI_fxddA8bS<lSs}
zT(&x1rrRrixAQ)`EADf}#pkk^PM|!qBB~kz%G~C6!7riC{?9auKOS|lpo^dpNM`dD
z7a~@vN5hV4|CS3l0JdV7vPNnrWbhW@IUO=^0%C|#HX=UVQQy3HsVL~9&Y1DeT~n1_
zUw!k<-19%wgrTJat4R&x?tqVMo2~f$znQhrlz@I~D{{U`p^^~MOL)!1ty5+fYvNj$
zH3L~=?el)cxr-BX->>Rf>uoyI3r}11N5v#J-aZ=`{b5vtN)i2K4rcX9INep#ak7(}
z459vbBSE@<-71faOsY&!juq`occ4+!_ZXk*Tv|GZ?!;)3N**bu1}Xa)PR?rBh0Q3X
z`gu2!mDOTJ$Nfh~a)e;b4>YgLi+f3K&xGX2$dcRQ&}_aKd#+tjEf-iE9D5`PY^;5F
z6zo=tSuf*raD8iF1Ppo8Ctl|sm0W1BMY-yKQQzUlDwAr)da~GX*ZPE39}8$IQ6$%l
zc;i2E0jDQ-ho+~2g^8bFR>~xI)N-YU7h-tic=tT&N8%Y`7&H#Sb@FpD*3NRhf8e00
z(`aP!2K!6S;Olg?(;5t|WWDPW===0!epICIgNL+w%<r0}XSKuW>M4%lnXZO=E$4^v
z8ZL#Wnz#pndQ=kGiwIZ*Hqf<pjTyZ5YDs%$s{teEf84jWAKc3kOd37twmc=CneSN0
z;dDh~u2brb`Bt40cYpD3nY*NOhztMVtjM5s2E63v9g^B3MzFsSCCYpspLU^8`gWnh
zmA;U(^+K94;THxS{S&a3m(#Ux^|FtIHFcE_h=?KbNCb4)jm?|aD!CD73WWrb0T;+s
zNG~ke=bHBZ0jQpGI0LweQOG;&p)bz>?^%2n8i;84|Cylt?^BxpgP*{6gs3LbE5rh0
zZ<I+&Y6Xg`@E^wu-L)70)o(&bVFIvfGby{mut?Q+lrJn)e)5LQtCdoHT~M)0h^2}C
z|4GXJ53b;U|4{gj-HKq%zNb4=&F}wZW@i2@)_OSosU=`LdU-Z$reWQA2$+|CrFmCR
z1YQsj$$<z3mCFO1>o^D)3qo{%0I_e`{hF<s%DQIi0}g{Hb-8*F^x)_3-#YY8%wy+p
z#@P8qnV~BvEE*r5^FcOgk2i;`+@6qfoA7>S_<wHL?*<i4-Kna+H+xWJalHT10vZmQ
z|8Yyd_+Z%=jYA{lzup_={qNCilqdAH*a3_b$VbOpV`|qsKeePCml|Dzkx(vUs2Q1=
z=`Hsb8-n0f1L`kN7M(jZ@+7i!G=Ss;mT?(6IZO6Y$njOJoes%2)<lhJj@b&cAb_X#
zVIBF(^k(h;rY)XKrE|4!Q-;LmZhG*f9Ugf%;dSI^@1ympDbh1rSbIPqO#rZQE_XQ}
zMJ}@L8y(<CtpL|?xy6g<1#tKI>F6u~gc*9~^zxVhM^lVaI?#V8nF%muWqX0rbwH)$
zzi*A_Qg|~y(r|F7yJ<5An+C_(^5s^alO34Q>$-O@rXNYM5dA3u^7+y2)d`T_QtSA>
zu80YI^#PjWFY56e(HiqEBri$CCw+eb7izR0lz;K#)!ESi4d}<`fbj2^vyAV+I;8XO
zFR<j500cMy4g+u}j%y~QDEtMGGJq?jX!uS0b0<TI_UCS(|LRmzIJZvSi8=JuGpVH)
zh6Dg&(HM6%0~(2#-#I6{9pLj6$qo7?y0<W(>ZwO|ns@@m0FckdmCJF%-{9g=iMVtI
zHUn-5h+Bnm!~R^AmD3H7l8C-*r1=Bh!P9!!U8s^0c=d<0%pIsqS23fb`O^96pi#90
z4rCPdK9AP|X#^JZAlZKh+_|FIu6^5yys`KYhkogY(_-nQv+kpyjW}Vr@@v1nI-qA)
zwE~|4aF_RhGjVEvEf$7GJ9b?E<q(I1n~=t)7w#qoJB{IK_Xe8n+@oi#n!&AM<@qRd
zlG9a3Qo0-H+70FO5GJ=-x2Bw)eW<bTCg59ToBd&Y5sXINX}PXSM8D((3m~&}<9zA|
z^Vz2AIQLp|McXryAx6ccRu>GhdDjhy4?}QhQs3l8Uk%|=XM0U0$TB<{Ln3tOY1pL$
zT(4?7-<g3EcA&PdDP-u_t6wyEK_=yYS!PrNSH`a?&hw3aYE-P5i_X@5cW&Hq@GtHy
zFcLMCdxhW4l#$;E0@ZyPePpjxOX5g=B2SX<ll4kmiaDEcy#v5f1F__xV`twfYaQkZ
zF+>BdPiM`7fX*Ru(~HBYUuJj&9I+E8h@bF=mZ404)bM$(*NP}mT|J(=e|FFei9|qw
z!Ae8IKG*_<mJ{E!&Kb7SGL*!i)Y?|n3T&>8%@Pl_a(w!1!g7}UZIQ~!3bPJCoXuSO
z0K0t}Qe9*A2Z3}&L<cVkk*h6t?m4L}au^~B2~d+R4=tXDuekIN@l;_!5Gx4q+KqJK
zDO4<)Im&-`ofm2`R6c3TejRMdLlV4kdx*OI!~vf0Y5|KN1HzK?Y^Ua^WKIl9^%I~9
z@m7E(NshNTCQ1hdZZyt)QwT6qUSCXrBhd|ld)w#?lhQ9#O=Ew`dw=k7?+h3@g^<JH
zir`alwdazw|9%qMzaS7K`#Z#`&Hw0N6kr7O9s*nNCD4vKZp<F8GcKs)8}}HkrS31S
zRDb?*7+Re34Sipwl_&9dJ)ux&A(drP29KFjhFRd1O+7>(gjFD1!HGy&pE)JmHkHNT
zu#S#4d)7hQz$Y%}DtrnGrcb8;4u1v`7gLWYd2JPLHMUr1zkT5*HhKi){n!){w*#hS
zVEWW&3+fjGShw4mJL~!go_O#2n-X?_)A_kuov95xOizVYz-C&_zOqn)*nE)<Mg5i2
zMnm^r8EcphNP?T*kbKow%^oFVq!vLKxVKVqF);#~&EZ0xW5a12D$9xeZ<m|vgeQJ}
zQNTh911f#W(Kf>jr(xv>K`0VPD-<|}PD`AO3UItEGjEa!M#^~Y`}S}w*;1){kd4J#
zX}ZqdU>$p-^~vPT<zw7L8N!48=oA5#ZAANC0Eie57Z3OOTs*?|Gw{0$*uk$7qLHT#
zZzl2_7lRJF&_J<%^BK^HM-4eoYDAvm7sfZS-v0je!NrIa9dv(B&KoMPrKtvIvlh{_
zcQ+w(pd&4chlDt!KlNgKR4hS7wK8u4p`6WLRxVoG)3RbBD86XkBv#M$*}wdtd!HLA
z?Ao;`mb|%E9|5K(u{SuvOZY@Ya_Mh@i?|=!RU7mt%^;pq)G`$NFFr633syd)Xa+_(
zg2%?nxc&b6pZ#pP;CP%m5wp6;rp#1GkYybPy2CxopzTonQatpIuz(jeJdW^_R=>~l
z392Y?3Cz3Q45mS}2o2|1t;-r@$^F0=ehlOm>Y!WK10sulA8m6`qyY>sKvX0@;*GbL
z1~B?nGhV7iBO7sLa)RB<!C(~3<);FybaTmWiDSuON!Zj9nd+(8yQ-dyV1I^U%;KFH
z4q_#Ve@Ry>A#Vr(B4{uTGwrhVfR)+T)ai+~Ch2zD92N{<CnlBsz^gV=WoYQZl^~>}
zC%V(ts@{q4)m>ha8Yg}Y_J=jbf09&%%|2v7T^gXRoGbj#Qa=CF_|O01g$O$$YRp;I
zlwzwQy*<_Z(pQs_heQFF4qaSPRcaeCqmq{3j(x0oGr<i0F*1UVxC9NJ#FFy}&b+;N
z9($m-5~;rF5Vdn@t8jT>_}$V5HcuR|8cP7#)CLKc7?DpnHx~y=Eb7Wvl4+?d9=#F^
z`lX3sjK6qV{k#=`)PnMq+oTbw&&<D|js4o+UM?MR+r$p)655l9&D1x7!ysXja4PSZ
zLsY-TOw1Yx(IZ7V8;ydf6dI7QnG3;(T>eHAD#{}ivu_JSB9~<EZ|T}s-nW!K#-Jda
z*jJ=f;4_0AC#m3AxSF|`M`zTQ7LA8TBn<Q)ECuk$>E!oUL9YXcG9)7m5;fVZSyr@W
z18ctm-mx3vKmv`HvhtyE7K;{j3L?bJN<_f(z5conLv`f0l<f^>INxKo?CNA2k5a@O
zqOp_jFXg_jpBJweqtElhz|xx8mnj^-DFS|>iaioFhKBvnW^w#1iQHs0Q~Y610J2F5
zmTwM`SFGmf!ebb0D_pQBy@MVOGAcBD$NYawb^Z6-8sV~B&JM*VfS}SKkB6~7S`KTW
z^uS+0#}Q?IuG9NJM8Z;42_cb#^dow@{~i6}ulxrZ0jG!iWf|FsxF_5Y7|I{=KXCvs
z1uRc2Vs?+M(X2ZA*=ecyS+wa-!2JVZ%9WZoS|2X3`g?mP`@!`gXHrdd8GB4}0X#-?
zY}T%h2CjwkbfF4pNn<qqhd_j3*2T!+)h{=>0uh{Y-6B=}UqPXSniChWAZedtYw1wU
z4P&RKuns4L-{APbCIBXb1ppjQ0`c%qvZ3XT>(M(qF+HH=^5TG`$?hIVYUl#!N*i(t
z@G6&C`;s*c*$G2}gl@I<5U?We047%4L<+~H@&(m{*)-@JJ`Ze3%`ASKzGz}*mTADh
z>Eyy!o7)b%u?$s+=y^rDGO3<PoKDJd7Wy54%o!Yr&($<XMYr4**s~hK%fDKE+*@B9
ze0!`oKnxE%+ne8I<}4`$;7#JN6B$%pwh<uQ04%$)HI@x>fTA+9re4cG8dm-~`p?^B
z#F6oZ=)J$c^$9_E=C0ym0a97l`z;5Gs7vXO&C!6s@&4{0Xae9u;ADUcz-dsPvxs22
zyWArDQR2;b4!j5x;@x$&)@*)nwMD;%J2;*z4uH~klV8jsB}O&2hqf%Cy?uQs^T}-j
zrQge&F<*#)+749gddJ0Z_R4k;uwg4vODDRH3_eJB-~SMokT6hS2HKA4L~tVjGyqsH
zeA6ianvd%O{JPw<h49pMus@dk1caRy(?sqsR{VJQ<bi7A@)6&HUl~+(36R(W*}2Yo
zbbe!kk4XU#cKFLd)H?x+_S<7M26>@i@|%gE`=2da$!grYU}pgEmO1TNpUoK-^GrI{
zeiDj)TMrAo!Fe;^<}DC83y-CdUJ(=rrnd47+&U5DUJt!Mcu1sV<xJ%T<xO~j|NfGw
z|2)W*4ECdu$w5oOqQM~-R?X>SCzY^AZI^=nKIwJZ-{sTX>HP>2TzqY1rE<Uo2aR#C
z8$ffD7rgPSkMW&eoKzx*m+^Yk6ci&yuokZhM>%Ze&Os*Y2bCQef2D<e0I_4BsbBDS
zw*X$~l4FsMZ?pehnl|L>5_U`l>;!{yS0c=5YfpaknGW-=m<~h#O=WiJf|1>x+&*=S
zYtt8%1-=Ju7nj$ATx`rlK2Rx3+D~#te6YazAlkBxQCGv|TfB(TcbuO;m|1;!lC0+c
zSA+EHlQ9q|keQ0AEi*7j(k{_ug1je*)EAN4_sxj`z&;77A7p(XlvV~`RDgMljEKpS
z9Ka{E-lZjVWes}OiqsH-2k;<(=Y>u^cG(U9{8w_Z?FKK2F6p~nt-=w&x3UuxJN21y
z-a#*s9nfZ;7%QHRdbkzSpOgaV5BQ#yWCp5U62=4YtginI@98@LEopHY`=-V3!b!c*
zY>NK(3jB}xo;i@;k~lU@vWZwUYtMxTsjiaXzm<kjq!aRvDljr#Fv+RS{I5@U!M$}{
zHIbN-IkX)>>Cvdhoyh(7F?WBVE(ZE!o|*_hM}I+p`d0tox^N9ilM5}~s@nU=vg4?R
z3q`-3M^x@Yll<K`fV?mNey<P--y9M}DqHFZlK#?t#HhsYeYgsonw)cWyy4kGYhB{v
zQvzR$PTX-|k%{zKbR=9#0Vi8v+@Q{0Q-rLTa&tCQIiw$8kh%`fv5Pl|KPRf{2fEXl
z4#f?bBOXiM_zqw>Rw2kSqw{rGD`)W3GfFRm#7wlOwOPX}Jl*nzfoH(tA<|q(8%5X>
zBTZP09f^8|p(+Xrra^h8r1~|0gv~cLUUnGUi_VPn87ZgrV!HTVD?V?4OJ+jRt8cw!
zZqllklxA(&M89O4>Fh8Gii04a>cUgc)Sb`WDqsAxLu;9SJt(`+$~N>mK;*2fSG_>7
zpKr%MS`hxT7*FnQJ%&ep7$iprX5jdgmjS82;D(Kze7z>Kh2$>db753X!o|6qn@MCW
zmZ4E{ais<o;{-ioNi-({KWC2m)S3Ju3IzjB!;Na9@HtT>t@xB<j3$zGERMo)DEi3(
z#1u4QQ;Z3(f&uWoVI+02<Q{naln@}LWEe)}p=3#IDyLC0&(<|MC6BJN9Rhi$_<mz3
zC;qtLNvN261TK}xCy>T(*cU=0z(avON%t)I{$E-ET~Vspk5_`s&uKtJCAKCc_fK!7
zkBE~_k-OsH)IfISaKb;?^<=(88AfLFS^pMbiWFdu^4jwH@P4GDW_=9(U)lZorX$p)
zuo;=qA4^wrJ1%~ZX!U1_D8AMimNz2PFo%gHfEm++)Z{H}vWjWBV3iDjRoC+#VjK44
zAGYkeLyXaNY<~aZc{6y&Y75D?&c0?l(Qn%9yHd?#@n)_Bx^*6Pi?RF&d(u>}Dr>-t
zVn>)o;=7S=Vh0cV9?B5_I2vO8a)Wce%04f%pg0K}n{+qZx&18@{*51q{JB3t|6}HV
z)Q5nGS)Z+zwh<nQOU@7dH(NgNoZzj_nzGn9f){>e6V9NC2$EVlr_aq^gDBFukeUPf
zvv3@1^Cy_KvW#<7o>5CZfTzBJXfR8z+ICRuB)k6A{QmNXoAi2F>rp?&+)O%`@t454
zVGz8)35{V7yj+Wrf8nI&p9lz++g2ietYFuZfp{Dc%2g{xt2<PKLop#l;~d*ok2#=b
zmo9v#0z_9=S4QEu6q)b9?KT($Og>R;F;;aJID8{7;tbYp2}KLkQMOo1*!{>E$e<JI
zC=5{Ktu&SKSj*!^QAKWgleb?<!awZ3sX0;q47wIoP>NPX^I!HwLNpYbEKx<mexVJ^
zwRd7Js|b=nvEb2YL!r&2D#G~33lPTmdB2%4T_;I#0px>RZt^_ht!D2iPR->EV_BKl
z0;Q(v;csou@ZP#u2raV7?o5zPBAlROrJk{{^E0EhiZ3fKTMo?nW}9<0bb&#pK^}sg
zwxLcpQyStLT}{b~n<1<~0O`J0#g3)LeAI?(I%j(}n0dBdSj8U;&YH-DOgqczrzT5g
z(F^|>NV4oV_u(7hTtr)PL31fn?sScR+e6+*AoD6E?$va}+4>aqc#*i9V%SCRZDk;4
z9w|}SyU+On+napOnIs~l-<~lj-8wQ_>sgaD_wm%cXJ>FDciLa+rli&Bw5~}wZhVXL
z6<-w10f%U)MRXSnj<SU<XI1<yPGc7;x~nOmJ_=guglhIadV2!`1D>tY+c35M7QJ$w
zYuRt`I2qaQ736HHjlxp&i#B_05kH2Ke5?aB-_Re$!VvoA_X48c*S*G>{DiVRZKs5u
z$fh7%Es2(bk4fx`Cy17w$;o74PWE~O1R+SmhnWF4dT&tel^UBuX4o^W;T?vU0d1U?
z3K`_1U&#@)Pj3jOU_D}DtJD^$X2CPo+KHyfd;aIm!JEpF=c`NZcdLc?T(~q+lzsIz
zSu&ZUfzzeVVx3f-)<onI*E<E$_m>Pz47ThopJX=cKjT{Dc&tSdFx(2gc{cC-j<U{b
zf#5fDKw0<-y6p7x8-?-CvE`fKl$|zs7R7U``z4S93*_3X?GkhU!6&+RcSFpse>q}y
zf1Lkt8^IWRmeRVSd)SthiUF=q-+@#S7A`ZFxu<gL6JBwri9)7U`^z`HHxP_U3_JGV
zcHxeMEBbbFUULLd)X^}mP`xv2aw4T^3@y?KLdkyhql_I)uM|mo)0O+X`?pFcl<z>(
zQCPw!<hC#$cXfI+>Ar=rv9wsGWCo5YQ_&Y2o`c3e@24a{<OC$r1c_sGrAqhh@u8WJ
z%%A$MNlyB~Kji`wPlCg(T1x)tX34hg3T+tqSrTv)hwChNiLA>nL?6!MXzrny4AaRN
zjN<vBg}_9GG)*8g(~(PP!OT%_51uh&oWzN$A7T7-$e-!Gf5zfg<VoBpw~#_bpJ|&C
zh<mQ{PSwm>vuqEmy#aflRiF#5{afuf07jy?LxE7T#D`BNvgdP{$n9(@R)nFwVQEyc
z1uEX<Ksec%`9ZO7KKOlrJcyN_v%9m>MeZ9p*+8!zM0v=4V0=2$kZsqUJI7#@yIUr>
z&#xs9s|Y349H@DW7MV+&KQWT1bjTnfUO_-U<TY#htKPrL83@8<`XWF@RxJ78M2`0w
zLEPqC@9F1YD(dRzAa-IcUgbsWk|dyUHQbD-(#Xq{te9BV#n%k49#JMWw5S~S(<OH8
zYUsqM8@U{8JakY)MYe(lsT!DQ=;K!EnV7u&%Y{&~KWI&2^71mID>K&xzQD~$0ZYWa
z8j!y4qWhw)ZW)@4;ThVCJpWWko~+wr<gFrl3~%CcO-1#mSN8V**y?J}r+7TvswkLm
zSds4pPDIu-9mbzzQRbis3lDfO3h0f~ZFF}cprecAo>0aTmCfBm4zeeY)0fv4r(3LY
zqqw9_;*|?8J*UL%&=nO>^kH1<may=(vR?KVc8}!<3*wK_)nLGHa^ouV;Em_dpza~r
zba7JlEG}t?g@f~k{}L1jlLzT$A6cR1K8G*)(Cf>0nG)otH7YUeDVGE{F+`jCj}Yh&
z->ZD)dC#xoz^WuP*49GH1iwLvYHh8^aI3--p6ow35{C0E^dQamV2h!QS{YNj(9s^^
zhNnbqoNT6O5pp+jIHnF0_s#by@W)4Vr^VuaCR$n9`TIG7`g##|uW0)rDEYaSRFz&i
zc?X941D*e$4}*wv{sqRiw76T4&fw0AQ+rVm5*wfi%2AJZUE#VO6_|*9COE7qij_fE
zE~(lRTQ_t;>xU(iC_YU2Z4<>AAlx)-T^V>hVFOI*DMMRBzgrxU@)>;oXPeegUny34
z?{|_Uxt*}CmAy{Vdq8J&aTp(y{FMv{fWmk<qY1^g^`C;oG6Gi-$-xgImogQ4ixAfp
zR~)!%vT|(~&H%Zv=2oiB&Aa_nPmKWV;wU{e`0j$;cs|V3_w>WLIY8$J`#)%C$@I4m
zo8Z6gVRzjh0YF&v^3Ifg{nwzy)6rOoFP=hqKc-?-m0QBAW0d7Q+bWRvCG^R^L3b`g
zEtJ{hxu>Bq_V6?5%8^X=e?1F7Dn~|{B)lpl*V#9^J!tANtA%3%a1gmuFV@y*y;4OR
zZ6k)w8qMCcS@vNL2miu;O#VBkJ_fCye~=rldK@%yMM8-s`w9o^-O_7d`g8Oc^C2XU
z8718bmr9dIe|u2f2<VdDJGtmR5Mg_+NgiP>X<G$EG{#llnZ`9}!>F_$AFtP4_4%AD
zGk3&&ik6hC!Le4fD6rpKw)6ZdTLJF<)coNons+hxK4CLNkZe1*Bz7c0_KgK_FjkD^
z?fUg=CQ8<5K)e=<Nro;ntdZp(RV<O5HuCoA&mKK3Nd<v&OrffTg@UC0#n&Zq0)c;t
zOq)H{T4*KoIoH?MBL}Xovv#ec&<8$R`IACa(yRDK`Iv=H-fa#hom*N=FBrF#)HY?|
z{I$sBn$auzL|%lH9wm`EH#!Oebrb`(DDxEB%tbQM2AYh)8Xjg*1f%i%XtVG~rJb$L
zbxaeLPCESe`a09_z`i>MgMvx-c@b@6_GW{r&Mg?G&^E$72Au*<x6W%RX%|&vC$PqR
zj2_UN__dln;sE$qkApgu^*Q>uG$bj6>22@dfH<*Lf9z2>m7(=!MuN!F${D3ebZ0Ng
zXabN^k1}kGNpOL~eFo$NXPUQk>i{=BL(-fG6vW#i>RBy3{!K=~u=&e!pL_+VJj>)V
z4)*{|f6>Zu`^bl?-z9ah5ul!60Ybqa9p`xjFy6$qZR92q<9wZAal@OlWR4<6Z3$mZ
z`xV!Av$Dl?#8|0nB74w&Q!c)^Tw-U2-y8d9*pl2}7tGbTspZO^+va3k1M4hGty5|a
z<(!EKAbO&~(H2qo$+RI}8A*C{Os?D;f$7X#pc*e61bo{3^24YyVvw1dm9HJB5#$vg
z!lNXFqL->|Vuo}x)pyvZ((h0J<-7Tg%^Wue^Rhx^3E(hOP3(s3i8{{x>D0?|cb4?k
zM--+jTASx1Q#wbw9nEQhO-jYHxFPRvVz{xd|HH>DPF=vMZa@GK*CP=(LX47a-Z~;!
zeL;yNQRU{o9l>_sE=(1UeHEIDdEbR6)tQ9xH6>N3!D~|~`f&_Vm)?kszq%z=Y_yU0
z$-JDo#U$2$>{I-6FD5V(x%KJh8WQ%HY^4twBoHb}e)QcwMS}lNt7vMxRsrvwr+z^S
ziFtgB8~SHL<;M|4Ye@p))5i!bz2xTVZ5ntjDNg4-9p#Sai^p*6f0Qg&0^!?aa0b;(
zM%nV1dn<C&#^@1+`pJ*V-v2n@C@Y8x3^#@mXPvlCBssgJ|BORUvHag>k|Y_Kn5yRF
zJ@e{OJvCCa9*%uHnQF<;#AM)P=%;lE*_JK?>R@4@6JkBurrJO`i!?k{-7AAUex!tG
zh@JSjYFG3>$=%13lcy}l%BdO2CotB}c)UpLoAvJ^z(EPvzAfb7cDqhKo?sG+d^M&j
zSfr6U6b%!br$KU;38=b}aMjG`FTimJk*XC$>HI@u4=XCR|8q?ruUnFjb-_(My|f9s
ziu8~t{o@BlnY+Kw(`hoD{hM_L>0B_KummJ2!2H{2-tSCWfVhyq$Kh(%T2I7{BS@4Y
zNr{0RV#oa%4-x888;@~4r#@F0epli^D8YO%7)`2u`x76P1lYhj9f1J{N?^mX8C5f4
zfe<cWj(Hah4z4C9lvqG-H?FlyB7j74GG(OZ>OE7B1j$D!YOm}tFlsVW`eNip2gr0-
zPg%_)bU}$cP%5{D&)00<9CQF77OqZh7CYz!y)Q2Wh9bzSim|ho0$*?C3_Vm_fxBsw
z(D}>I?^qx&(sMm}N0F7$MxIGSz#5n?QcIu|?S=sImn~>-Ymm%Y3i4uDz+&T9A=G#&
z0H(bS$_&@aIduyMfofIn3>)|5zrVG~5-ht|v^wNU0k+4iAaFE*Gi+`HpQ{?GzXFfE
z-QmBA4k;k=1=2_!^%511U#1EvMlMA|prb5h1EQzhU=Z{d&@JM^K#=IU^U6{=$OU^I
zt@jxj0+f9O3is+e)T(Yknc>60XV)%&tn(vj9B(?LgN$s)z_48#iS%W<%3ELt3rtAp
zwfUaS&CP+5DSbT1FeFrf`Irm_Yx9E7O&t_Gs&q*s89XrH5Q9igHqlFaiiL3=>)6f>
zj1gofYiO)<79zO}_TitP%Qduh4Ckz_-`JZ^bgDS=egCq3!TGp$Q{xZp?_)0zSuSe=
zVxW=d1+l-Hw00_(D9!7jWKet$yw<O&eIKO)ntyydd7sGVB{>CLS3$!$&{%Us-DB~a
zP{YuT)EX0f4D+mLIc1RXQDfUpL$MDv5}&BM0J#q|3x_XnfdT$fpmH44)#^Auu=`41
za4e*>`K$(`JsO@Zc{vl`E82(a4Xs-o54r9X4NG*3NX`6{Ol!=f0)`ZYR{l#10HhW9
zmk<~f9h?ISE+pa!4hW4^|6@y;`zV?}4aDSX0bP*{Fyy=W8kb6}7XqZFsu42n(y{)g
zT|1yg4u&5wek`-i5pnJ2;;nUDOeaH1kp%9{>`V_p>`hL~Vh8nI4X2R6-8kVDJ6OBq
zjRIsJ%=3sBBJje&1ZWEXyZP#(mSme5Mn=X@o{Eu_s(G8d^l{b|p(N>%i21&N>w_T|
zMxG!LMJ2*dj1&$k%*6iycFhX&$3z?m+G7CJ8?<RpccIwmXfZIX6b<<cTddI#OF9||
z($Z7o0mDG`r7}53pwE3R#gu8X1oOsrWK9fT@Z|@`7^X0)t)YYUgOhJ67!olGaArC9
zfSx@MygkOxK)3EM5l%FzX3oSE@S(`I>&_i0dGiO1Z1RKTWQ*f}4EMeYFlSettE8l4
z+(P58Myfi7uDjCe6Xy<lN~rMMTsIVPB3n2CF@yaDrj9I`19g;nm~->npUl8!$+Hg0
z9rK)~;I^1+bY)QeuvTtV!~E>S9&?km8NY?IF}<1AmlDuV{i8<`eBL)mdhJsN0k`@F
z#JQ3KRO^FAJwCo_?(OY8B-MLeW>^Iz^m9;)z#|GStZ<1e*{@<Pn%+;~f!Rusn69!K
zIF-+flzIAOQ=fku#eb^nxhfi?=lKCFfwxhZ8KgX%fhO;%1UzuMWZEftc8sykR&LYg
zUsT9%StVR^u7Qxb>^>pMwij{^?&y6=&hOQ(P~am40m&t0!?Fhq7dLqgf31Ctcs{00
zkWk$8z|&YU#^AWzd<JagNd;DUPe%9hrNLUfVAwioIn1ha(&~9!N;wEjgj{@O=u~0J
zqn*+()}-373%@9*ex*D0$L_VypS1k|4SWg;wXBSOvLg_!{#sHr0tE5<^M;NpK!oyH
zGR@8Paj63@Er^~-1E&E@v<_;V?Js9f2Fsw`6|g#jj&^IU*=XK<EhlN{m@M(+3HCZT
z%N2Qvr~;7NJR}fA*npxx#*}Z^(q4b3AM6KD&jLtaZ%FI|%az6inDYwJPepxCzqN(2
zU8Zxxy?~y|X+Aj*EhIry0{0{e^|pUvOVaoBu>9)!U&R!0xW*M!g3y!z8F*Qq3_tgO
z41e8)@?s*BkbA9gx1gYojAjWeCnKz{;V{QqRV&3kI|F;#O<iT#e4y&UVWmioG*-m5
zGn3D%Eb$49-^fndX-PyrCY2O}sTP_BRIATK8?BSOAX4Lz--OJsdEU=n8{7f>qDwGV
z3Tl^e(%XKq8|JJYR%|l6VQkN=%+84>MQn%U7^F~G?$>_4d61%{xMH&I5h1q1<twsv
z(*{!~H&6_s=_!7rJm8*#sSRF2_O*wbjt4bd%qqGOXbxj`=ne33z>J3jrR2|_<B&)P
zC0@6*VleB_UxJz)32oH|L7lxGOvX>iTm;2+HmF(BK~iZaAdP}cAv9`R1jV;lhbRZ_
zaxQcGi-i+-o9*7bUXl74VC}%d<_JLhd!nmud{GI|2_C06G9NpkDg)s8drM6<1P~|?
zRpb;2#gk~U1F3AaUm;<I2A+r-mUrCyUi1Z}=1O1hFn}5Mp`>MJiwxc;STE3SB$k1#
z{-}FP&N9n;(xr@fh<IiUnaOtJa{}WYbVP?RYAFqx$KfAza#30nUhtEAJmWwwCfzN4
zm)9dO*krBNCUlE^_K2B8p=EU=1bOnRdIlE$$3_5Rc*+w1tg@JLVu_OSel6q?=2QzB
z<;^7czfeYdJXk#=A$!~WmxY{o*+<YZk1bhG;uJ_4KH1)_4dxLw3wLF4XIMZ`E>f8V
zNyEi3BJ~eU*rZ##Q87z`iX-=(!L|PH5XHz*`s>5_5Mx5CjDFHAzh3ktIZ?lJ2TMy!
z@Yf4UJ4C@m2SyvOJZa=mkXFy7)So!~tnqomsiU#zLs-?zzTx&7j_Xcx2KjgfF|p=I
z<b}$hhrpYgG!+%EO@eE*B}-~Y_80g@nvlEhmI#CAkWD*G5HG8DFd}*f+}bev49S(E
zSOR(^<uaok!^L$_r8R&Pgh7>DKB4@X{ue>dSy~)Eft>${rD9}`rh`Kn1{+;DUrzHE
zC;`2t$P3X90{Y?<>5d19iPZoN-ze~RH~udh7$T2-<pur#!luWg4J?6I#cOiu9Rohb
zDs++vKIRUe<2#TRxc4`S3|s3Rms5~hbc9ACSZ4H}<P*><xr3Mz6#C>MpU&r<*r{N+
zfR%v~Q=TxynoWmgVnAcg3gks{K#vD`Vqj+94{iU%U>W<Z7rm24M$a+H!6)xTTV!Af
z{mZ1b=4+taJ#mBcaF_4oN0^0K^)BQD_B!SJ5FgL|=qRZ)nuy&RnIh_h&NN-vVWCn)
zs}jhfytZyfjCD!*KI?=<=O(BdR``gXn^HOXCg<0Mzc7KjYNGV=3cepGXIzVZHT$?d
z+(?beF_U0F9?><&;KFF&d2^T2Bko+YZqmVpAwU*u7PB8;w2FEnExB0opFQQqNRZq-
z^fe*!Kf5q`u&U33O69T}h2e37BG6CrO|+Mq19ThdpkclBt~!aGapa&oG0V9W*vqj*
zRl7H%I$@R1_8f@#TttR59;c^kzz#U5(7hy}q6z>$-fj-QXo3fY$tVPXkw?J!-%2>|
zcq;$*kK214^T<30N0D&|CnK}$5lV7o9Yo41BPwwmlsF=ejLJwwLJ5_9#1Yy?vZeSC
zk(Kqk&iD7P2akvQ-1oWP*Yz4t_>zO2Q~_Vg_1{(7g%l|-n7RPMfv-4)&4zJ_-p0(j
zdigm7Twp|de7aWY9oRYUO|hFW@H#CRO8TsMfFWqR8w^D$O#X|&uYoWOgAMHgS;*$S
zo#1|mS1o6|U1<HlJ{SmZP)Nm1T0r3ZUN6+NdadSnp&Ad?N96LfW$+Y)LC%2Bm!Ckl
zbz?Z0+kb-tQ#KC9m^OMKyi+O?52u9X0I*3SU|^s(jG$~_V^?C9A_!ukMMKz+BU|&&
z4>&!HGPJ5QCbYvp4|dNbR_@*PB(Exdc0S1{@CW-VT!m~DukHNjfw)srZ1w6H<bB3s
zS9$?MkaFYSB0t}KE=bbtz{$}V!I=UjtUTPuGZInYArlGk9ByB7Iqeh;WT4audfaQQ
zjX)`3e+gpdTSE7Hh4I;S$nu|1pJg&Y9y;p)CIFboo6uU7U3I~S9))H1&3SSi3|X?M
zOpL8#y=<6#ePfP$#E`-IcTGYU*`limA4XHy3-fFxCh1@E{PgbL?q9`J{wHylM!`~s
zk1ABBx*5d3hMl!xPC1+XRS6|^?9x&HgL3q?Ca@2Qjh^xLMnB~DeFZ)A#)VCPh}j)y
zU6wgijLlm@<nhBRTDNrq({i0RMk(bKC#UT{gKJ?H5kmV6H^vjdser;BwV&Qq1FIkI
z(G@uNH-&qrzddq!COvmP+-jaFJ+B!mp`jGC8A>C!1R+0q7FxGm`s02V2CGn|?-W0`
z{8Yi$SGlV{h_l{;Vp{F&BzeEgg(JJ@KE3Q|2w7sLYyN}9iSFVE-39k_r$fx+ka#=a
z9WR)1^W+@?)B;CTmCKrw^Tf;H3+Et_1kVjL@e>)UYG44VFuvCWiH7%vd*4@mVNMI1
zJgOg1B+0Zd^Agd(+eiuFIQ?x=@t0$Ku}yz+_{*~&i|A|{oPUOswZM6a`H|N-ruMsh
zwN>Ymr74X0De$;Tpu+a!nFf1dKJrPZ1aBoXA*7v2Qm<xz7NgDnmaVi~w-h){_jR6N
zof;G<X~P}a|L{A3!KFnYNW%hdu$M=r5>hdpx({MB4k!s51`HOG9L?Ly+$qMvBp;BA
z{u_9vlP2U@leKh=CreZ}@^_EU9@Hrjrah5Q^2i~O`cz$+0zrxsbHFU442HS<fM-i=
zB&zU@-kzn;(}4CMdu)Lv+qCstFH%7_T`rC!)K$C$iz40aH<eh_*R=Dl3?6IRuKgOU
zLCFszb_ZMZw1H?x2Nw)x`^DM{<{V2Nzh8N*BJN77a+^*OK48G7@LOGQdLHfan@99S
zGYl1ws5_uEIg(Ga3@oK9XMO>1CH>gKCN@M=92ai6kAcz@6-=Dn4hO|5qVV;AbDR__
zAFD;j;5l;18+TK5Vfh^`m@UO|A+n;G42jN+jGv*z{VP)Z-=6~08kuOFzh_F2GOE)M
zJNzS3HA|VLr%8sSx0^VIg3{PXXQ2afRfUE@Az%DV9@3IjD7ry--O*L@LXHpf@+Lws
zQT?hNR{>dEa~8dn!cnY#|Lv*hrgrEV{@Fp0oOMvH(O^PpB61TiTq^YGZ4Fb%Vkol6
zK*w5Hr3HS4gj-9`7VM){9T=Q?H?d{ZJB!uQzp+k~y1{8qL9gAL=Xlp=CHxyAzoF%0
zW=HXCzezTDHcLK)Vmw2CK?F`1;@v;x>cm&lUr_2k$eVfA>u&dZrUOvP?hWs{qrXyE
z!*Oy8gUYF@7WWjb&Wi2zqX8d3;zQw6TmSOdsUbdo@fP<3a>Ds>)xmR0OKCy-WEF0o
zNmvW?UBss#g;aH4NAj><qrZ&)eic@Be$?V&BDAQIMtJ&%X(Vtz_eSEp?ySL4%cn|d
z^RVu_T3mKRcqDDau{shkvM&z0)|Au<MVj-lxm|Y-XF)!1EJ&HMQ92m)S<G|$D$yE=
z)Txz{Jg?76Q0dA{%8dWvyG&2;xHo|RFPI3)5^ALEpBo~6CLw${UC3P<5d-W;X~ccR
zTXO<4!`V6(aT?8>ag_T}?6HIbL}f0tFtdf4;T;QCmy=02C%u6eriF&nE3x@bcJas)
zEmveIEhv)}aKmg-8M*#M4yH<fiHJRzoG;Y35UFWXnSB&&`;1Nf?<MPyMr?Tf=F270
zSnr#oF6zAz|3aUJ+G+)SB2w}!?fm4rM%CRQgmM;EQ<=-ZP}<QGiDLMlB*f)NGsV9~
z#EB6^f=&Pnvu(sKWPi}NdQ_2|FXQ=K7i&cxw<)Avi-68EIbht15LNkMnYDpj-P}(=
z<TecGRlfRTz)g!NtQaZ78hHN3{$gyx9ZS%B$IzwW6^NvarG><YCf>WUHU!@WamAYI
zuN>Q7U}MaEAz-tE!E2FVLs>RJ5SXfES$UOdsnhoz$bTyRMVEUUcz};)(I~ATo12he
zT1d~$K>l;sT;>X)%?Q#^oVFWWshy(=Z-xD%;i4X~W`5H4sg!djUYfqPpySK7^z@_V
zmm=s1_3s#u(iq4`yr(aE%ei7?PPgH8OiI`y@;Bf6njHDOk8i48Eejj^Cd4V^^un9A
z7mW~=B7VbBE@(07^%1Gs83VP8F%}sN41BzFc3>~%E5V2I0{I(w8l{ix7~Xb_e1w+j
zd4Bwxt9n+-LFZ1i;&Ns1$^;%c>Fx7J>3j=NGm_PT$AFz@<4P)Qn8*rU9_2~*(SR6+
zs?AF0YFhHE*@73N=ng~->`}+9vJvVw=AX1rMWiz59rZ;xFDu&{?i}hL3pVFK2KbkA
z#YyM}kLpiNqnO72E}E04_^qjNWvS{_E!fh0!ReD!5;YYl7S)9}#qtx)rK9ClRr!R1
zWI~=tE6pE#(sI!_crz;-4EL3oCe%m>h9VHfdv&)BlBH#~dB;==OndD9tmhhK32m=g
zH;FtW3S5`HTmJyocOF6UmA<1}Uzc8fimXkR<e6Em9XJ!dXSqw<Y|m;pn|%L@Ej~`f
zL-1z+kf}y{T@w~sZkkvOa`^<Vpe~vi^sgTMwE%mlzXDr^-{|NYQKJ3GDAIDACGNGH
zs{eYn&>QzibIgLQ=9#^eb3zX$1xlY?>~ZmN<KY`9ZVak^svS~hGVXtEzu)+1=_T`I
z(OKV!Rwh3d9V~^)DXnOZ^vJxNI%b|P9Aloz-ASDCOb`FW;={J-jx>pKJA?*UlRY1M
zcE;`Fp9(Wa#QKG5Uucy&%V|Btl(Gh?vfbUZatK&Sf18`dQng`*;c)zx;r>3<Ut3ds
z@~q<t$}XhviWsQ^7shRvvUb9n9zWkS$RZYn+!a@vtiJT$Nxf=H@5$qDRC1F~BGD5w
z7ZE5kJ$d(Z%`*>e#3P>weEF1W83pKrjoN9sU2iQ)48<qL-k@Q%dHaVN^*bEp&&9HI
z7zJ&D`=4qb5b8<$WcBHG&?l|yp^NE1mC3SbJ=^3st~8*3ly_SlJm|6xlgzd@VK8>=
z5GV6-vB#QQ)0z`fqO_UJOy3&`p>0}W_)~&4KX_7?OX`ML*%$A=kY=1Z=fza+oGix{
z^Zc=jih~hfld4&FYOZ-~&R?oL>rsVF(>2oR>??!3N2@s%+*FTT{N?brobOafAFm6?
zrNwe7oX{`r_@t#%E?rHf3Fp2ZQKbmG&>AScGJRPx4_+O%pO&u|O}1@3M+rD}sLkOG
z+U8F0(_yrdF#{@KoG;+L0_|%nW=C?q_>1B867%tjM(2b@l?1(RlPZyt@M>w8GR0;u
zEbBiKJC+~Z%lf;~<f(Y+cfpNOMYXOuNK%p|^G#meJsghN;tC5d(sBF%5T~Mxb60+$
ztN{k)5ZXbND05y007Q&ojkLjOD-`2!;JuUKC{jnmj8VxxA^L2J<jo<Ty=j`R?wLb#
z9dcv(RdQ`_*ZGO5W163~AuQ7@yj?g(-X_C80<35|{lmsHq63Ql1&>YhEku<A_-(Xa
zOLw;Nz2`u%^puy>l~<GUl`Q!y#guvaqwSxdRq+lNa`!ch$aTG(J{A&LZ!vr0lh~aE
zplc<TAD{<HzDng*kZhRyly@Zuv`jk+)s;#H8cjYUnx1oBmG9u0BHCshns4t3n7fV_
z4P|~vY8N@}W${^u3$Bj2D&6>-M1H2=)Ock1{uQ>QyN7e;7Px|L<_o$B#Cql23J+FO
z{HiM9Zx<f_G^Q|gLw7#I`8}w*3;PJMU1SuYdTC_vz)YdnXC8ahl6%?OZ68zJze0v3
zeQ+__b!i!wp2^OL^s(;|l-REB-3|Tp#_W}{RO-}d#M~F!5t(nG*Uxc**)6B1F_Fa0
z>xzC@c6<KHWY46ZUqz$$3krhN+wsfasM=2ZmY<__^AhVHC)XC`Qs+X)`$oY$sTaiW
z4E!D5`F6cp^2twHV*$H;aw4NWs&w6P1P*H9Se)qKMZ>c8BX?U$6jL=AVRGi?vj5S$
z*jIXSyfBDcu=nwDrMPww(hIY7na&I2Y)v6lYVzcTQ)gvmJuO%^uAcC<;)5Pk*{fA(
zS4`sWpJEZUaT*wS?(o6-0I!0XW0l8DdXM~g0r>`;@$xI(@5f<*cmX9Zm?{<D1&-Nw
z%HPwEuGzxi4vL8#lvcHCv`uCoa*LZ_Z78;hd)GUPv;JMEn{?0Czf>w^b+Ah<RHc|}
zTC+-Jbl?#AYSnvD782iiHclZd06iFH<p?z(0^&D#Xd-L_A#OfhGpIMNSgDWp$(j-`
z)$<OnS$OTZt|_0v-XcfZ9UI?I?-OlENj|g8#5CCHl%gah*DJL|H~hyn#I*O-J%UMZ
zt+(cF__OLd@!KJ=gjQ(hDuaE6-Acp9Xfl^&-w<^oZ<<B78!+M-f;t+0#vEVr?1jY+
zbjtP_IvHgoX?4RNGL|EeF&r66{TZG0gL%RYchyx1P770zRYsql3!#MR?F`;<NZ6!_
zOgDC9mNPi@{qR(KBpdU5a9S^X@XBY?CB1HzdhHDCnnl=f%=vwt$-`n_AF$J<b)5%c
zsNuT}SNLC?r<GcHcOEGeMaGzl&EA;(T*lsny=_WRek|YrL2wHDof<!1V1+v$-+WI~
z(u}%@9gIQYG8pIP`$^t^kFy59r7QNrfw(_w4;@P=;qBcFuic;{{^Oiq3v@i}l?1Rp
zY?*vTMJ<0X<@G{?tA+d>fhqjP`MF^8`qR4Lz>7PNp*vi4c+>%)KlJfI^H{uT(&G4)
zdj6qeLa%G5+y*^y5M-u^519ULaiZaUH#Y(qBc}D4B>qn0`Au>b%|;zSG!}StjZqIa
z=CJ4dcSY%kb_F-=+b`>1zB@r2O6e}`44N)dPs8%o=u8pcu~3mzpjEBSe(uE8opsXV
z@iWh5cEQ8S(m-5b4vq4Y#BQq}#N{Ynkn!kT9df~iprEpns@CDsJ`=KEz_9Xz^O&r4
zcF(9q1Pr;QU*7I~WSlFOMDs1fqGxyEd()E0-e8k4%R3{Q?$gzjEQ_(mG=wwv(Z=(M
z+OG5OHaIx3)X~*7QI5V)9d`OtlY~lf!5Q=%udIZkicoNvt|1+MWF}hX51AlP8QL|`
zbJXi?n%+V)y1oi^^}V%bM>1|Q>a=P<KUtXd4HW2K2Cr>yVtw99;zHsqY5G2x2Zt*D
zo(VExAtj4D`6jkjdZmH<5eRm|Tbhjqb8b@4F-J7rS<W*-*;0vAms+)jR=hXmlwVQP
z-%r*T1Y`)oZ*w=h7|tB#PLvAzA=f44%fyqX%*W4f;2DH(<{=p|PQ5$PV?MebUN5F0
zcH~xreuD+pioPVPrw5ijmXAY>3xpbdNPzO-T1V*1p@6hu(Aa<G<k;!VHZkw6%gjM!
z|0b=kUhR=dOhU5^pBky0Tg9uq<*>1Couc%*VrlOAPEY38hwgEC4hvToc&#%+l1N?R
z;}esYyjPj*17-?Uj<XbAH(nEslZ_OnkiU-xdf<$UNaYl3<V{K0;rTO*T`A}6+d^|x
zL=#MjCx^^fX>88gQ4>7+CC&;^fL_pZ2}`EyR`Oo|3Th6DldLVIeR<2(33+3&q9)1X
zDTC`Agtiuqrki7lsCP2v!Y0XN0ot={n&=ZxVJ!R|L&jcVb&t5$qcys1O0cf^XswvZ
zr)BdsNC-`rtmcii9hq{1{&f@nXZz9~&cH(}wJb%Kx)A2tCzx`2B(LGt=vpiRJLJx`
z-SzwbwXPodq<}b?-0g+7Iz9TIQi&fteQ%mq)R--_z54tMbmO6W7`slOfuX__4-fyb
z7dmVyGS5GV;`;c@_zWG&+aTn+`8VT4r%LQr?K7ae7Cn`o2LDeg*dDF|Z_$^@Vtw&%
z$0SpcfbXi2p`#iR{MrQOgA!O-uH&%WWBazc=@?_-t`&C7%`T$*@V(O}!bS7JH(xii
zDFFD_x_{2tin*SQy*-j4!eln#O*P`xg~|>^28hhbc$4fTj^FAw56SNt57#3hDIk*?
z4@z`0(m*{|`Z08H2Dee{Vu`K0qUS(-yEJfD06idxy6j1t&H(n~9iU2Xqj;i=i;FoW
z9~~Z)HEFh0BX*r&5keD|nFn+C0(qI3(IlWF0YL7{U@{|gw%W!(Rhw%%0V20zI=hf1
zfkyrw(h8Z)M8*fQC&#D2WkrIlnPT=3Sx@*ntTox4)w<y(Ql-4|&3q)an3pIBbpRZg
zZ12Dx4r4)7vSa@1me5Xdu80bq;{Y=#QqylwgzY3s?5ruEmju`vQKlRjS5gKE88WUo
zlQnC30Wq;ojVGQm5ihr0kf|$<25qcF#%Lq?5?&B5%_0!YYOasCfNgcqqe<Vg1X=?_
zc^UXvA|pVHZ1o5wu(H3hv;>3~!5mvfI9~y_kXt4GaK#STTa!~$JNq`c6GCtBQiZ9!
zK{P+8Mydnv3rp~TUw$fY1Shcd9i<M#6p`Cc+B*CWG#*jIU;v|_0i{3%5-xUQ2}o3G
zgrs|pf+o{Qbm#A+?th6(5~V&C^99ZhDS`^~PUk=?v^b!crPva4Vzv|jHW#T(t0XXy
zWcii!IZ$n8)ME_dVkGjl+C#i4Jp$R1F?~!D-n8nUjF-EFHWG(}EX~1wR(wuqMy6nN
zf2jG+t^Dk}XP{UhU{aDhe}}a@S)DkW$ENXL^z!trR~v?I>JRsOF6ieu>@yNvT4YXF
zy5v>GP00Sh_GIuN+$w<~b|t2$6;4jhgM(TR5Nu*h99!NBqK}N0T!KHsquF&mh!5L(
zm_17ti^T?T%9^%$YV0f=cdd7V+f1mLyZ*C<x5(DayHh0^lw@agL-+C?BLl<UUgO8H
hBfyqtqc4Wc41txnIX{oryYLeR%cFK?l_s9?{|Cfggi!zh

literal 0
HcmV?d00001

diff --git a/docs/claude-scoped-oauth-usage-limits.md b/docs/claude-scoped-oauth-usage-limits.md
index e5eb3c9e2d3..bac2679f86c 100644
--- a/docs/claude-scoped-oauth-usage-limits.md
+++ b/docs/claude-scoped-oauth-usage-limits.md
@@ -25,7 +25,7 @@ The OAuth response contract evolved from dedicated model fields to generic entri
 2. Select a Fable entry only when `kind` is `weekly_scoped`, the model display name is Fable (case-insensitive), and `percent` is finite.
 3. Map the scoped entry to the existing seven-day `fableWeekly` window, including its reset timestamp.
 4. Prefer the current scoped entry, then retain the three legacy top-level fields as fallbacks.
-5. Keep malformed, unrelated, inactive, or absent entries non-fatal. Treat `is_active: false` as unavailable so stale promotional limits disappear; accept a missing activity flag for compatibility.
+5. Keep malformed, unrelated, or absent entries non-fatal. Do NOT gate on `is_active`: it marks which limit is currently binding, not whether the entry's data is valid, so an `is_active: false` Fable entry with a finite `percent` must still render (#8979). Accept a missing activity flag for compatibility.
 
 ## Data Flow
 
@@ -40,7 +40,7 @@ The OAuth response contract evolved from dedicated model fields to generic entri
 - `limits` is missing, null, malformed, or contains null entries.
 - A scoped entry names another model.
 - Fable percent is missing, non-numeric, or non-finite.
-- Fable is inactive and should not be rendered.
+- Fable is inactive (`is_active: false`) but still carries a finite `percent`/reset, so it must render (#8979).
 - `is_active` is omitted by an older server response but the remaining scoped entry is valid.
 - Both current and legacy fields exist; the current scoped entry wins.
 - Reset timestamps may be ISO strings, epoch seconds, epoch milliseconds, or absent.
@@ -50,7 +50,7 @@ The OAuth response contract evolved from dedicated model fields to generic entri
 
 - Unit: reproduce a current real-response shape and assert Fable maps without a PTY attempt.
 - Unit: assert scoped data wins over a legacy field.
-- Unit: assert inactive, malformed, and unrelated scoped entries are ignored while legacy fallback remains available.
+- Unit: assert malformed and unrelated scoped entries are ignored while legacy fallback remains available; assert an inactive-but-valid Fable entry still surfaces (#8979).
 - Regression: retain existing legacy-field and bare-`fable` behavior tests.
 - Verification: focused Claude fetcher tests, typecheck, lint, and max-lines ratchet.
 - Electron: refresh Claude usage and confirm Session, Weekly, and Fable remain visible in the existing status-bar details surface.
@@ -76,8 +76,8 @@ No UI implementation changes. The existing Fable row must reappear with the same
 
 - Scope: Kept to the private OAuth mapper and tests; no shared-state or renderer generalization is required to restore Fable.
 - Architecture/data flow: OAuth remains authoritative, with structured scoped data preferred over legacy fields and PTY used only as the existing final supplement.
-- Failure modes covered: malformed optional data, unrelated models, inactive limits, missing activity flags, duplicate old/new representations, missing reset metadata, and platform-neutral execution.
-- Test coverage required: current-schema success without PTY, precedence, inactivity, malformed/unrelated entries, and legacy fallback.
+- Failure modes covered: malformed optional data, unrelated models, inactive-but-valid limits (still rendered, #8979), missing activity flags, duplicate old/new representations, missing reset metadata, and platform-neutral execution.
+- Test coverage required: current-schema success without PTY, precedence, inactive-but-valid rendering, malformed/unrelated entries, and legacy fallback.
 - Performance/blast radius: One bounded linear scan of the small response `limits` array per existing OAuth refresh; no new requests, polling, subprocesses, IPC, storage, or renderer work.
 - UI quality bar: Existing status-bar visuals must remain unchanged except for the restored Fable row.
 - Required review screenshots: Live Claude details with all three rows; surrounding status-bar context.
diff --git a/src/main/rate-limits/claude-fetcher.test.ts b/src/main/rate-limits/claude-fetcher.test.ts
index 96c1c1c75ae..95f7d607ac0 100644
--- a/src/main/rate-limits/claude-fetcher.test.ts
+++ b/src/main/rate-limits/claude-fetcher.test.ts
@@ -423,7 +423,7 @@ describe('fetchClaudeRateLimits', () => {
     expect(fetchViaPty).not.toHaveBeenCalled()
   })
 
-  it('ignores inactive scoped Fable usage and retains the legacy OAuth fallback', async () => {
+  it('surfaces inactive scoped Fable usage over the legacy OAuth fallback', async () => {
     const configDir = '/Users/test/.claude'
     const authPreparation: ClaudeRuntimeAuthPreparation = {
       configDir,
@@ -454,7 +454,47 @@ describe('fetchClaudeRateLimits', () => {
     )
 
     await expect(fetchClaudeRateLimits({ authPreparation })).resolves.toMatchObject({
-      fableWeekly: { usedPercent: 33 }
+      fableWeekly: { usedPercent: 90 }
+    })
+  })
+
+  it('surfaces an inactive scoped Fable entry when no legacy Fable field exists (#8979)', async () => {
+    const configDir = '/Users/test/.claude'
+    const authPreparation: ClaudeRuntimeAuthPreparation = {
+      configDir,
+      envPatch: { CLAUDE_CONFIG_DIR: configDir },
+      stripAuthEnv: false,
+      provenance: 'system'
+    }
+    vi.mocked(readActiveClaudeKeychainCredentialsStrict).mockResolvedValueOnce(
+      JSON.stringify({ claudeAiOauth: { accessToken: 'oauth-token' } })
+    )
+    netFetchMock.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          five_hour: { utilization: 11 },
+          seven_day: { utilization: 22 },
+          limits: [
+            {
+              kind: 'weekly_scoped',
+              percent: 64,
+              resets_at: '2026-07-24T20:00:00+00:00',
+              is_active: false,
+              scope: { model: { display_name: 'Fable' } }
+            }
+          ]
+        }),
+        { status: 200 }
+      )
+    )
+
+    await expect(fetchClaudeRateLimits({ authPreparation })).resolves.toMatchObject({
+      provider: 'claude',
+      status: 'ok',
+      fableWeekly: {
+        usedPercent: 64,
+        resetsAt: Date.parse('2026-07-24T20:00:00+00:00')
+      }
     })
   })
 
diff --git a/src/main/rate-limits/claude-fetcher.ts b/src/main/rate-limits/claude-fetcher.ts
index ba21d32decf..e1ea780dea2 100644
--- a/src/main/rate-limits/claude-fetcher.ts
+++ b/src/main/rate-limits/claude-fetcher.ts
@@ -408,8 +408,9 @@ function mapFableWeeklyWindow(data: OAuthUsageResponse): RateLimitWindow | null
   const scoped = Array.isArray(data.limits)
     ? data.limits.find(
         (limit) =>
+          // Why: is_active marks the currently-binding limit, not data validity;
+          // inactive Fable entries still carry a real percent/resets_at (#8979).
           limit?.kind === 'weekly_scoped' &&
-          limit.is_active !== false &&
           Number.isFinite(limit.percent) &&
           limit.scope?.model?.display_name?.trim().toLowerCase() === 'fable'
       )

From 257b0b441eca62161721c1463eaf4713d0b74af3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=8B=A0=EC=A3=BC=EC=95=88?= <ju4nshin@gmail.com>
Date: Mon, 20 Jul 2026 16:53:15 +0900
Subject: [PATCH 40/54] fix(new-workspace): ignore IME composition Enter in
 workspace name field (#9526)

Co-authored-by: Orca <help@stably.ai>
Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
---
 ...SmartWorkspaceNameField.ime-enter.test.tsx | 237 ++++++++++++++++++
 .../new-workspace/SmartWorkspaceNameField.tsx |   9 +
 2 files changed, 246 insertions(+)
 create mode 100644 src/renderer/src/components/new-workspace/SmartWorkspaceNameField.ime-enter.test.tsx

diff --git a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.ime-enter.test.tsx b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.ime-enter.test.tsx
new file mode 100644
index 00000000000..c0414ab484b
--- /dev/null
+++ b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.ime-enter.test.tsx
@@ -0,0 +1,237 @@
+// @vitest-environment happy-dom
+
+import React, { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import SmartWorkspaceNameField from './SmartWorkspaceNameField'
+
+vi.mock('@/store', () => {
+  const state = {
+    repos: [],
+    addRepo: vi.fn(),
+    checkLinearConnection: vi.fn(),
+    fetchWorkItems: vi.fn(),
+    fetchWorkItemsAcrossRepos: vi.fn(),
+    getCachedWorkItems: vi.fn(() => null),
+    linearStatus: { connected: false },
+    linearStatusChecked: false,
+    listLinearIssues: vi.fn(),
+    preflightStatus: null,
+    preflightStatusChecked: false,
+    preflightStatusContextKey: null,
+    refreshPreflightStatus: vi.fn(),
+    searchLinearIssues: vi.fn(),
+    settings: null
+  }
+  const useAppStore = (selector: (s: typeof state) => unknown): unknown => selector(state)
+  useAppStore.getState = () => state
+  return { useAppStore }
+})
+
+vi.mock('@/lib/local-preflight-context', () => ({
+  getLocalPreflightContext: () => ({}),
+  localPreflightContextKey: () => 'test-preflight-context'
+}))
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string, fallback?: string) => fallback ?? key })
+}))
+
+vi.mock('@/i18n/i18n', () => ({
+  translate: (_key: string, fallback: string) => fallback
+}))
+
+vi.mock('@/components/ui/popover', () => ({
+  Popover: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  PopoverAnchor: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  PopoverContent: ({ children }: { children: React.ReactNode }) => <div>{children}</div>
+}))
+
+vi.mock('@/components/ui/command', () => ({
+  Command: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  CommandGroup: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  CommandItem: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  CommandList: ({ children }: { children: React.ReactNode }) => <div>{children}</div>
+}))
+
+vi.mock('@/components/ui/tabs', () => ({
+  Tabs: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  TabsList: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  TabsTrigger: ({ children }: { children: React.ReactNode }) => <div>{children}</div>
+}))
+
+vi.mock('@/components/ui/tooltip', () => ({
+  Tooltip: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  TooltipContent: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  TooltipTrigger: ({ children }: { children: React.ReactNode }) => <>{children}</>
+}))
+
+vi.mock('@/components/ui/dialog', () => ({
+  Dialog: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  DialogContent: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  DialogDescription: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  DialogFooter: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  DialogHeader: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  DialogTitle: ({ children }: { children: React.ReactNode }) => <div>{children}</div>
+}))
+
+let container: HTMLDivElement
+let root: Root
+
+beforeEach(() => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => {
+    root.unmount()
+  })
+  container.remove()
+})
+
+function renderField(onPlainEnter: () => void): HTMLInputElement {
+  act(() => {
+    root.render(
+      <SmartWorkspaceNameField
+        repos={[]}
+        repoId="repo-1"
+        onRepoChange={vi.fn()}
+        value="배포"
+        onValueChange={vi.fn()}
+        onGitHubItemSelect={vi.fn()}
+        onBranchSelect={vi.fn()}
+        onLinearIssueSelect={vi.fn()}
+        selectedSource={null}
+        onClearSelectedSource={vi.fn()}
+        onPlainEnter={onPlainEnter}
+        textOnly
+      />
+    )
+  })
+  const input = container.querySelector<HTMLInputElement>('[data-workspace-name-input="true"]')
+  if (!input) {
+    throw new Error('workspace name input not rendered')
+  }
+  return input
+}
+
+function renderSmartField(spies: {
+  onValueChange: () => void
+  onBranchSelect: () => void
+  onPlainEnter: () => void
+}): HTMLInputElement {
+  act(() => {
+    root.render(
+      <SmartWorkspaceNameField
+        repos={[]}
+        repoId="repo-1"
+        onRepoChange={vi.fn()}
+        value="배포"
+        onValueChange={spies.onValueChange}
+        onGitHubItemSelect={vi.fn()}
+        onBranchSelect={spies.onBranchSelect}
+        onLinearIssueSelect={vi.fn()}
+        selectedSource={null}
+        onClearSelectedSource={vi.fn()}
+        onPlainEnter={spies.onPlainEnter}
+      />
+    )
+  })
+  const input = container.querySelector<HTMLInputElement>('[data-workspace-name-input="true"]')
+  if (!input) {
+    throw new Error('workspace name input not rendered')
+  }
+  return input
+}
+
+// Why: the guard must short-circuit before the `open && rows.length > 0`
+// row-select branch, so drive the field into that state — smart mode with a
+// typed value synchronously yields a highlighted "use this name" row.
+function openSourcePopover(input: HTMLInputElement): void {
+  const event = new Event('pointerdown', { bubbles: true, cancelable: true })
+  act(() => {
+    input.dispatchEvent(event)
+  })
+}
+
+function pressEnter(
+  input: HTMLInputElement,
+  init?: KeyboardEventInit & { keyCode?: number }
+): void {
+  const event = new KeyboardEvent('keydown', {
+    key: 'Enter',
+    bubbles: true,
+    cancelable: true,
+    ...init
+  })
+  if (init?.keyCode !== undefined) {
+    Object.defineProperty(event, 'keyCode', { value: init.keyCode })
+  }
+  act(() => {
+    input.dispatchEvent(event)
+  })
+}
+
+describe('SmartWorkspaceNameField IME Enter guard', () => {
+  it('ignores the Enter that commits a CJK IME composition (isComposing)', () => {
+    const onPlainEnter = vi.fn()
+    const input = renderField(onPlainEnter)
+
+    pressEnter(input, { isComposing: true })
+
+    expect(onPlainEnter).not.toHaveBeenCalled()
+  })
+
+  it('ignores the Enter reported as keyCode 229 by IMEs that skip isComposing', () => {
+    const onPlainEnter = vi.fn()
+    const input = renderField(onPlainEnter)
+
+    pressEnter(input, { keyCode: 229 })
+
+    expect(onPlainEnter).not.toHaveBeenCalled()
+  })
+
+  it('still forwards a plain Enter to onPlainEnter', () => {
+    const onPlainEnter = vi.fn()
+    const input = renderField(onPlainEnter)
+
+    pressEnter(input)
+
+    expect(onPlainEnter).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not select the highlighted source row on an IME-composition Enter', () => {
+    const onValueChange = vi.fn()
+    const onBranchSelect = vi.fn()
+    const onPlainEnter = vi.fn()
+    const input = renderSmartField({ onValueChange, onBranchSelect, onPlainEnter })
+    openSourcePopover(input)
+
+    pressEnter(input, { isComposing: true })
+
+    // The guard runs before the row-select branch, so neither the row commit
+    // (onValueChange) nor the fall-through (onPlainEnter) should fire.
+    expect(onValueChange).not.toHaveBeenCalled()
+    expect(onBranchSelect).not.toHaveBeenCalled()
+    expect(onPlainEnter).not.toHaveBeenCalled()
+  })
+
+  it('selects the highlighted source row on a plain Enter (control for the guard)', () => {
+    const onValueChange = vi.fn()
+    const onBranchSelect = vi.fn()
+    const onPlainEnter = vi.fn()
+    const input = renderSmartField({ onValueChange, onBranchSelect, onPlainEnter })
+    openSourcePopover(input)
+
+    pressEnter(input)
+
+    // With the popover open and a highlighted "use this name" row, a plain
+    // Enter commits that row (onValueChange) and does NOT fall through to
+    // onPlainEnter — proving the composition case above was really suppressed
+    // at the row-select branch, not merely inert.
+    expect(onValueChange).toHaveBeenCalledWith('배포')
+    expect(onPlainEnter).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
index c17ea30c173..1e019b0e0d1 100644
--- a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
+++ b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
@@ -47,6 +47,7 @@ import {
   lookupGitLabWorkItemByPathForSource
 } from '@/lib/gitlab-work-item-source-lookup'
 import { parseGitLabIssueOrMRLink } from '@/lib/gitlab-links'
+import { isImeCompositionKeyDown } from '@/lib/ime-composition-keyboard-event'
 import { getLocalPreflightContext, localPreflightContextKey } from '@/lib/local-preflight-context'
 import { getRepoOwnerRoutedSettings } from '@/lib/repo-runtime-owner'
 import { cn } from '@/lib/utils'
@@ -1504,6 +1505,14 @@ export default function SmartWorkspaceNameField({
                         !event.ctrlKey &&
                         !event.shiftKey
                       ) {
+                        // Why: an Enter that only commits a CJK IME candidate
+                        // must not select a row or advance focus — moving focus
+                        // mid-composition makes Chromium re-commit the composed
+                        // character into the controlled input, duplicating the
+                        // last syllable (e.g. 배포 → 배포포).
+                        if (isImeCompositionKeyDown(event)) {
+                          return
+                        }
                         if (open && rows.length > 0) {
                           const row = rows.find((entry) => entry.value === resolvedCommandValue)
                           if (row) {

From a69943432e201321e85921187d841062c570bc40 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Mon, 20 Jul 2026 01:10:03 -0700
Subject: [PATCH 41/54] Direct Windows users to v1.4.147-rc.3 for bug fixes

Updated README to guide Windows users to the latest RC release,
which includes critical Windows-specific bug fixes not yet in the
stable build. Added prominent notices at the top of the download
section and in the direct-download links.
---
 README.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 87ccc4995ff..f8a4ec06fa8 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,10 @@
 
 <h3 align="center"><a href="https://onorca.dev/download"><ins>Download Orca</ins></a></h3>
 
+<p align="center">
+  <strong>Windows users:</strong> download the <a href="https://github.com/stablyai/orca/releases#release-v1.4.147-rc.3">latest RC (v1.4.147-rc.3)</a> — it includes Windows-specific bug fixes not yet in stable.
+</p>
+
 <p align="center">
   <img src="docs/assets/readme-hero.jpg" alt="Orca desktop app running agents in parallel worktrees, with the Orca mobile companion app in the corner" width="960" />
 </p>
@@ -212,7 +216,8 @@ Works with **any CLI agent** — if it runs in a terminal, it runs in Orca.
 ### Desktop — macOS, Windows, Linux
 
 - **[Download from onOrca.dev](https://onorca.dev/download)**
-- Or grab a build directly: [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/latest/download/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [All builds](https://github.com/stablyai/orca/releases/latest)
+- Or grab a build directly: [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/download/v1.4.147-rc.3/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [All builds](https://github.com/stablyai/orca/releases/latest)
+- **Windows users:** use the [latest RC (`v1.4.147-rc.3`)](https://github.com/stablyai/orca/releases#release-v1.4.147-rc.3) — it includes Windows-specific bug fixes not yet in stable.
 - Running `orca serve` on a headless Linux server? See the [headless Linux server guide](docs/reference/headless-linux-server.md).
 
 _Or via a package manager:_

From 207db0279803e6a026a2f6eff7ab4ccd93705d64 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Mon, 20 Jul 2026 01:11:48 -0700
Subject: [PATCH 42/54] docs(readme): shorten Windows RC notice under Download
 Orca

Keep the callout secondary and clear that the RC has Windows-specific fixes.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f8a4ec06fa8..24e7126c783 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@
 <h3 align="center"><a href="https://onorca.dev/download"><ins>Download Orca</ins></a></h3>
 
 <p align="center">
-  <strong>Windows users:</strong> download the <a href="https://github.com/stablyai/orca/releases#release-v1.4.147-rc.3">latest RC (v1.4.147-rc.3)</a> — it includes Windows-specific bug fixes not yet in stable.
+  <sub>Windows? Grab the <a href="https://github.com/stablyai/orca/releases#release-v1.4.147-rc.3">latest RC</a> — has Windows fixes.</sub>
 </p>
 
 <p align="center">

From 7386ef28574ea6e93e6bb6d79883ee7867000053 Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Mon, 20 Jul 2026 04:14:17 -0400
Subject: [PATCH 43/54] perf(renderer): stop full durable-state save on every
 top-level view switch (#9002) (#9393)

* perf(renderer): stop full durable-state save on every top-level view switch (#9002)

Persist activeView in a tiny profile-scoped sidecar instead of mutating the monolithic recovery snapshot. Active-view-only updates now bypass the broad UI normalization and durable save scheduler, while a 100ms atomic writer coalesces rapid switches and a synchronous shutdown checkpoint closes the immediate-exit race. Legacy state remains a migration and downgrade fallback.

Coordinate renderer shutdown capture through one guarded checkpoint so workspace sessions and the active-view preference both survive graceful reloads, restarts, and quit cancellation.

Add a persistence-boundary test proving the sidecar stays below 64 bytes while orca-data.json remains byte-for-byte unchanged, plus repeated Windows Electron restart coverage and a path-normalization-safe restart fixture.

* harden active-view sidecar: prototype-safe validator, race-free async swap, independent shutdown flush

- isTopLevelView uses Object.hasOwn so a corrupt sidecar can't smuggle
  inherited keys (constructor/__proto__) through as a valid view.
- writeAsync guards the generation check and rename synchronously (renameSync)
  so a shutdown flushOrThrow can no longer interleave and let a stale async
  rename clobber the freshly-written view.
- shutdown checkpoint flushes the durable store and the active-view sidecar in
  independent try/catch blocks so one store's failure can't skip the other.
  Added regression tests for all three.

Co-authored-by: Orca <help@stably.ai>

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
Co-authored-by: Neil <4138956+nwparker@users.noreply.github.com>
Co-authored-by: Orca <help@stably.ai>
---
 .../active-view-persistence-boundary.test.ts  |  58 ++++++++
 src/main/active-view-preference.test.ts       |  91 ++++++++++++
 src/main/active-view-preference.ts            | 136 ++++++++++++++++++
 src/main/ipc/app.test.ts                      |  19 ++-
 src/main/ipc/app.ts                           |   3 +
 .../ipc/renderer-shutdown-checkpoint.test.ts  | 124 ++++++++++++++++
 src/main/ipc/renderer-shutdown-checkpoint.ts  |  41 ++++++
 src/main/persistence.ts                       |  50 +++++--
 src/main/window/createMainWindow.test.ts      |   1 +
 src/main/window/createMainWindow.ts           |   1 +
 src/preload/api-types.ts                      |   6 +
 src/preload/index.ts                          |  85 ++++-------
 .../renderer-restart-preparation.test.ts      |  90 ++++++++++++
 src/preload/renderer-restart-preparation.ts   |  89 ++++++++++++
 src/renderer/src/App.tsx                      |  97 ++++++++-----
 src/renderer/src/app-startup-routing.test.ts  |  67 +++++++++
 src/renderer/src/components/Terminal.tsx      |  74 +++++-----
 .../editor/editor-autosave-controller.test.ts |  10 +-
 .../editor/editor-autosave-controller.ts      |  19 +--
 .../src/lib/active-view-persist.test.ts       |  16 +++
 src/renderer/src/lib/active-view-persist.ts   |  14 ++
 .../src/lib/shutdown-checkpoint-guard.test.ts | 111 ++++++++++++++
 .../src/lib/shutdown-checkpoint-guard.ts      |  51 +++++++
 ...workspace-session-host-persistence.test.ts |  54 ++++++-
 .../lib/workspace-session-host-persistence.ts |  23 ++-
 src/renderer/src/store/slices/ui.ts           |  18 +--
 src/renderer/src/web/web-preload-api.test.ts  |  35 +++++
 src/renderer/src/web/web-preload-api.ts       |   8 ++
 src/shared/renderer-shutdown-events.ts        |   1 +
 src/shared/top-level-view.ts                  |  20 +++
 tests/e2e/active-view-restart-restore.spec.ts |  20 +--
 31 files changed, 1241 insertions(+), 191 deletions(-)
 create mode 100644 src/main/active-view-persistence-boundary.test.ts
 create mode 100644 src/main/active-view-preference.test.ts
 create mode 100644 src/main/active-view-preference.ts
 create mode 100644 src/main/ipc/renderer-shutdown-checkpoint.test.ts
 create mode 100644 src/main/ipc/renderer-shutdown-checkpoint.ts
 create mode 100644 src/preload/renderer-restart-preparation.test.ts
 create mode 100644 src/preload/renderer-restart-preparation.ts
 create mode 100644 src/renderer/src/lib/active-view-persist.test.ts
 create mode 100644 src/renderer/src/lib/active-view-persist.ts
 create mode 100644 src/renderer/src/lib/shutdown-checkpoint-guard.test.ts
 create mode 100644 src/renderer/src/lib/shutdown-checkpoint-guard.ts
 create mode 100644 src/shared/renderer-shutdown-events.ts
 create mode 100644 src/shared/top-level-view.ts

diff --git a/src/main/active-view-persistence-boundary.test.ts b/src/main/active-view-persistence-boundary.test.ts
new file mode 100644
index 00000000000..26bb25ac70e
--- /dev/null
+++ b/src/main/active-view-persistence-boundary.test.ts
@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { getActiveViewPreferenceFile } from './active-view-preference'
+
+const testState = { dir: '' }
+
+vi.mock('electron', () => ({
+  app: { getPath: () => testState.dir },
+  safeStorage: {
+    isEncryptionAvailable: () => true,
+    encryptString: (plaintext: string) => Buffer.from(`encrypted:${plaintext}`, 'utf-8'),
+    decryptString: (ciphertext: Buffer) => ciphertext.toString('utf-8').replace('encrypted:', '')
+  }
+}))
+
+vi.mock('./telemetry/client', () => ({ track: vi.fn() }))
+vi.mock('./telemetry/cohort-classifier', () => ({ getCohortAtEmit: vi.fn() }))
+vi.mock('./ssh/ssh-config-parser', () => ({
+  loadUserSshConfig: vi.fn(),
+  sshConfigHostsToTargets: vi.fn()
+}))
+
+describe('active-view persistence boundary', () => {
+  beforeEach(() => {
+    testState.dir = mkdtempSync(join(tmpdir(), 'orca-active-view-boundary-'))
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    rmSync(testState.dir, { recursive: true, force: true })
+  })
+
+  it('persists a view switch without changing the global durable snapshot', async () => {
+    vi.useFakeTimers()
+    vi.resetModules()
+    const { Store } = await import('./persistence')
+    const dataFile = join(testState.dir, 'orca-data.json')
+    const store = new Store({ dataFile })
+    store.flush()
+    const durableBefore = readFileSync(dataFile, 'utf-8')
+
+    store.updateUI({ activeView: 'settings' })
+    vi.advanceTimersByTime(1_000)
+    await store.waitForPendingWrite()
+
+    const preferenceFile = getActiveViewPreferenceFile(dataFile)
+    const preferencePayload = readFileSync(preferenceFile, 'utf-8')
+    expect(Buffer.byteLength(preferencePayload)).toBeLessThan(64)
+    expect(JSON.parse(preferencePayload)).toEqual({ activeView: 'settings' })
+    expect(readFileSync(dataFile, 'utf-8')).toBe(durableBefore)
+    expect(store.getUI().activeView).toBe('settings')
+
+    const reloaded = new Store({ dataFile })
+    expect(reloaded.getUI().activeView).toBe('settings')
+  })
+})
diff --git a/src/main/active-view-preference.test.ts b/src/main/active-view-preference.test.ts
new file mode 100644
index 00000000000..972009f722c
--- /dev/null
+++ b/src/main/active-view-preference.test.ts
@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ActiveViewPreference, getActiveViewPreferenceFile } from './active-view-preference'
+
+describe('ActiveViewPreference', () => {
+  let dir: string
+  let dataFile: string
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'orca-active-view-'))
+    dataFile = join(dir, 'orca-data.json')
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('migrates the legacy durable-state value into the profile sidecar', async () => {
+    vi.useFakeTimers()
+    const preference = new ActiveViewPreference(dataFile, 'tasks')
+
+    expect(preference.get()).toBe('tasks')
+    expect(existsSync(getActiveViewPreferenceFile(dataFile))).toBe(false)
+
+    // The renderer reasserts its hydrated value once persistence is ready.
+    expect(preference.set('tasks')).toBe(false)
+    vi.advanceTimersByTime(100)
+    await preference.waitForPendingWrite()
+
+    expect(JSON.parse(readFileSync(getActiveViewPreferenceFile(dataFile), 'utf-8'))).toEqual({
+      activeView: 'tasks'
+    })
+  })
+
+  it('coalesces rapid switches into one tiny preference write', async () => {
+    vi.useFakeTimers()
+    const preference = new ActiveViewPreference(dataFile, 'terminal')
+
+    preference.set('settings')
+    vi.advanceTimersByTime(50)
+    preference.set('automations')
+    vi.advanceTimersByTime(50)
+    expect(existsSync(getActiveViewPreferenceFile(dataFile))).toBe(false)
+
+    vi.advanceTimersByTime(50)
+    await preference.waitForPendingWrite()
+
+    expect(JSON.parse(readFileSync(getActiveViewPreferenceFile(dataFile), 'utf-8'))).toEqual({
+      activeView: 'automations'
+    })
+  })
+
+  it('flushes synchronously for an immediate graceful exit', () => {
+    vi.useFakeTimers()
+    const preference = new ActiveViewPreference(dataFile, 'terminal')
+
+    preference.set('settings')
+    preference.flushOrThrow()
+
+    expect(JSON.parse(readFileSync(getActiveViewPreferenceFile(dataFile), 'utf-8'))).toEqual({
+      activeView: 'settings'
+    })
+    vi.advanceTimersByTime(100)
+    expect(JSON.parse(readFileSync(getActiveViewPreferenceFile(dataFile), 'utf-8'))).toEqual({
+      activeView: 'settings'
+    })
+  })
+
+  it('ignores an invalid sidecar and invalid updates', () => {
+    writeFileSync(getActiveViewPreferenceFile(dataFile), '{"activeView":"unknown"}', 'utf-8')
+    const preference = new ActiveViewPreference(dataFile, 'not-a-view')
+
+    expect(preference.get()).toBe('terminal')
+    expect(preference.set('also-not-a-view')).toBe(false)
+    expect(preference.get()).toBe('terminal')
+  })
+
+  it('rejects inherited object keys from a corrupt sidecar', () => {
+    // Why: `constructor`/`__proto__` are truthy under `in`; the sidecar must not
+    // treat them as a valid view and leave the main surface blank.
+    writeFileSync(getActiveViewPreferenceFile(dataFile), '{"activeView":"constructor"}', 'utf-8')
+    const preference = new ActiveViewPreference(dataFile, 'tasks')
+
+    expect(preference.get()).toBe('tasks')
+    expect(preference.set('__proto__')).toBe(false)
+    expect(preference.get()).toBe('tasks')
+  })
+})
diff --git a/src/main/active-view-preference.ts b/src/main/active-view-preference.ts
new file mode 100644
index 00000000000..beed983aef4
--- /dev/null
+++ b/src/main/active-view-preference.ts
@@ -0,0 +1,136 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { mkdir, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { TopLevelView } from '../shared/types'
+import { isTopLevelView } from '../shared/top-level-view'
+
+const ACTIVE_VIEW_FILE_NAME = 'active-view.json'
+const SAVE_DEBOUNCE_MS = 100
+
+type ActiveViewFile = {
+  activeView: TopLevelView
+}
+
+export function getActiveViewPreferenceFile(dataFile: string): string {
+  return join(dirname(dataFile), ACTIVE_VIEW_FILE_NAME)
+}
+
+function readActiveView(file: string): TopLevelView | null {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as Partial<ActiveViewFile>
+    return isTopLevelView(parsed.activeView) ? parsed.activeView : null
+  } catch {
+    return null
+  }
+}
+
+function serializeActiveView(activeView: TopLevelView): string {
+  return `${JSON.stringify({ activeView } satisfies ActiveViewFile)}\n`
+}
+
+export class ActiveViewPreference {
+  private readonly file: string
+  private activeView: TopLevelView
+  private persistedActiveView: TopLevelView | null
+  private writeTimer: ReturnType<typeof setTimeout> | null = null
+  private pendingWrite: Promise<void> | null = null
+  private writeGeneration = 0
+
+  constructor(dataFile: string, legacyActiveView: unknown) {
+    this.file = getActiveViewPreferenceFile(dataFile)
+    const storedActiveView = readActiveView(this.file)
+    const fallbackActiveView = isTopLevelView(legacyActiveView) ? legacyActiveView : 'terminal'
+    this.activeView = storedActiveView ?? fallbackActiveView
+    this.persistedActiveView = storedActiveView
+  }
+
+  get(): TopLevelView {
+    return this.activeView
+  }
+
+  set(value: unknown): boolean {
+    if (!isTopLevelView(value)) {
+      return false
+    }
+    const changed = value !== this.activeView
+    this.activeView = value
+    if (
+      value !== this.persistedActiveView ||
+      this.writeTimer !== null ||
+      this.pendingWrite !== null
+    ) {
+      this.scheduleSave()
+    }
+    return changed
+  }
+
+  private scheduleSave(): void {
+    this.writeGeneration += 1
+    if (this.writeTimer) {
+      clearTimeout(this.writeTimer)
+    }
+    this.writeTimer = setTimeout(() => {
+      this.writeTimer = null
+      const generation = this.writeGeneration
+      const activeView = this.activeView
+      const previousWrite = this.pendingWrite ?? Promise.resolve()
+      const nextWrite = previousWrite
+        .then(() => this.writeAsync(activeView, generation))
+        .catch((error) => {
+          console.error('[active-view] Failed to persist preference:', error)
+        })
+        .finally(() => {
+          if (this.pendingWrite === nextWrite) {
+            this.pendingWrite = null
+          }
+        })
+      this.pendingWrite = nextWrite
+    }, SAVE_DEBOUNCE_MS)
+  }
+
+  private async writeAsync(activeView: TopLevelView, generation: number): Promise<void> {
+    const tmpFile = `${this.file}.${process.pid}.${generation}.tmp`
+    let renamed = false
+    try {
+      await mkdir(dirname(this.file), { recursive: true })
+      await writeFile(tmpFile, serializeActiveView(activeView), 'utf-8')
+      // Why: keep the generation guard and the swap synchronous (no await between),
+      // or a concurrent flushOrThrow could rename a newer view that this stale write
+      // then clobbers, restoring the prior view on next launch.
+      if (generation !== this.writeGeneration) {
+        return
+      }
+      renameSync(tmpFile, this.file)
+      renamed = true
+      this.persistedActiveView = activeView
+    } finally {
+      if (!renamed) {
+        await rm(tmpFile).catch(() => {})
+      }
+    }
+  }
+
+  flushOrThrow(): void {
+    if (this.writeTimer) {
+      clearTimeout(this.writeTimer)
+      this.writeTimer = null
+    }
+    const asyncWriteWasInFlight = this.pendingWrite !== null
+    this.writeGeneration += 1
+    this.pendingWrite = null
+    if (!asyncWriteWasInFlight && this.activeView === this.persistedActiveView) {
+      return
+    }
+    mkdirSync(dirname(this.file), { recursive: true })
+    const tmpFile = `${this.file}.${process.pid}.${this.writeGeneration}.tmp`
+    writeFileSync(tmpFile, serializeActiveView(this.activeView), 'utf-8')
+    renameSync(tmpFile, this.file)
+    this.persistedActiveView = this.activeView
+  }
+
+  async waitForPendingWrite(): Promise<void> {
+    if (this.pendingWrite) {
+      await this.pendingWrite
+    }
+  }
+}
diff --git a/src/main/ipc/app.test.ts b/src/main/ipc/app.test.ts
index de9a13753db..7702dcd6349 100644
--- a/src/main/ipc/app.test.ts
+++ b/src/main/ipc/app.test.ts
@@ -10,7 +10,8 @@ const {
   destroySystemTrayMock,
   relaunchAppMock,
   showOpenDialogMock,
-  grantFloatingWorkspaceDirectoryMock
+  grantFloatingWorkspaceDirectoryMock,
+  registerRendererShutdownCheckpointHandlerMock
 } = vi.hoisted(() => ({
   handlers: new Map<string, (_event: unknown, args?: unknown) => unknown>(),
   appExitMock: vi.fn(),
@@ -20,7 +21,8 @@ const {
   destroySystemTrayMock: vi.fn(),
   relaunchAppMock: vi.fn(),
   showOpenDialogMock: vi.fn(),
-  grantFloatingWorkspaceDirectoryMock: vi.fn()
+  grantFloatingWorkspaceDirectoryMock: vi.fn(),
+  registerRendererShutdownCheckpointHandlerMock: vi.fn()
 }))
 
 vi.mock('node:child_process', () => ({
@@ -103,6 +105,10 @@ vi.mock('./floating-workspace-directory', () => ({
   resolveFloatingTerminalCwd: vi.fn()
 }))
 
+vi.mock('./renderer-shutdown-checkpoint', () => ({
+  registerRendererShutdownCheckpointHandler: registerRendererShutdownCheckpointHandlerMock
+}))
+
 import { registerAppHandlers } from './app'
 
 describe('registerAppHandlers', () => {
@@ -123,6 +129,7 @@ describe('registerAppHandlers', () => {
     relaunchAppMock.mockImplementation(() => appRelaunchMock())
     showOpenDialogMock.mockReset()
     grantFloatingWorkspaceDirectoryMock.mockReset()
+    registerRendererShutdownCheckpointHandlerMock.mockReset()
     processKillSpy = vi.spyOn(process, 'kill').mockReturnValue(true)
     Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true })
   })
@@ -133,6 +140,14 @@ describe('registerAppHandlers', () => {
     Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true })
   })
 
+  it('registers the combined renderer shutdown checkpoint', () => {
+    const store = {}
+
+    registerAppHandlers(store as never)
+
+    expect(registerRendererShutdownCheckpointHandlerMock).toHaveBeenCalledWith(store)
+  })
+
   it('marks relaunch as expected shutdown before exiting', async () => {
     const onBeforeRelaunch = vi.fn()
     registerAppHandlers({} as never, { onBeforeRelaunch })
diff --git a/src/main/ipc/app.ts b/src/main/ipc/app.ts
index f97ae1e2c24..d943d18dc04 100644
--- a/src/main/ipc/app.ts
+++ b/src/main/ipc/app.ts
@@ -21,6 +21,7 @@ import {
   resolveFloatingTerminalCwd
 } from './floating-workspace-directory'
 import { isMarkdownDocumentName, markdownDocumentFromFilePath } from './markdown-documents'
+import { registerRendererShutdownCheckpointHandler } from './renderer-shutdown-checkpoint'
 
 const KEYBOARD_INPUT_SOURCE_TIMEOUT_MS = 500
 const MAC_HITOOLBOX_DOMAIN = 'com.apple.HIToolbox'
@@ -253,6 +254,8 @@ async function readKeyboardInputSourceId(): Promise<string | null> {
 }
 
 export function registerAppHandlers(store: Store, options: RegisterAppHandlersOptions = {}): void {
+  registerRendererShutdownCheckpointHandler(store)
+
   ipcMain.handle('app:getFeatureWallAssetBaseUrl', (): string => getFeatureWallAssetBaseUrl())
 
   ipcMain.handle('app:getIdentity', (): AppIdentity => {
diff --git a/src/main/ipc/renderer-shutdown-checkpoint.test.ts b/src/main/ipc/renderer-shutdown-checkpoint.test.ts
new file mode 100644
index 00000000000..ca6e335f055
--- /dev/null
+++ b/src/main/ipc/renderer-shutdown-checkpoint.test.ts
@@ -0,0 +1,124 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { syncHandlers } = vi.hoisted(() => ({
+  syncHandlers: new Map<
+    string,
+    (event: { returnValue?: unknown }, args: Record<string, unknown>) => void
+  >()
+}))
+
+vi.mock('electron', () => ({
+  ipcMain: {
+    on: vi.fn(
+      (
+        channel: string,
+        handler: (event: { returnValue?: unknown }, args: Record<string, unknown>) => void
+      ) => {
+        syncHandlers.set(channel, handler)
+      }
+    )
+  }
+}))
+
+import { registerRendererShutdownCheckpointHandler } from './renderer-shutdown-checkpoint'
+
+describe('registerRendererShutdownCheckpointHandler', () => {
+  beforeEach(() => {
+    syncHandlers.clear()
+  })
+
+  it('commits every shutdown state mutation before flushing both stores', () => {
+    const callOrder: string[] = []
+    const store = {
+      setWorkspaceSession: vi.fn((_state, hostId?: string) => {
+        callOrder.push(`session:${hostId ?? 'local'}`)
+      }),
+      updateUI: vi.fn(() => callOrder.push('ui')),
+      flushOrThrow: vi.fn(() => callOrder.push('flush')),
+      flushActiveViewPreferenceOrThrow: vi.fn(() => callOrder.push('active-view'))
+    }
+    registerRendererShutdownCheckpointHandler(store as never)
+
+    const handler = syncHandlers.get('app:persist-before-unload-sync')
+    expect(handler).toBeDefined()
+    const event: { returnValue?: unknown } = {}
+    const localSession = { activeWorktreeId: 'local-worktree' }
+    const remoteSession = { activeWorktreeId: 'remote-worktree' }
+    handler?.(event, {
+      sessions: [{ state: localSession }, { state: remoteSession, hostId: 'runtime:host-1' }],
+      ui: { activeView: 'settings' }
+    })
+
+    expect(store.setWorkspaceSession).toHaveBeenNthCalledWith(1, localSession, undefined)
+    expect(store.setWorkspaceSession).toHaveBeenNthCalledWith(2, remoteSession, 'runtime:host-1')
+    expect(store.updateUI).toHaveBeenCalledWith({ activeView: 'settings' })
+    expect(store.flushOrThrow).toHaveBeenCalledTimes(1)
+    expect(store.flushActiveViewPreferenceOrThrow).toHaveBeenCalledTimes(1)
+    expect(callOrder).toEqual([
+      'session:local',
+      'session:runtime:host-1',
+      'ui',
+      'flush',
+      'active-view'
+    ])
+    expect(event.returnValue).toEqual({ ok: true })
+  })
+
+  it('reports a failed durable checkpoint so the renderer can retry', () => {
+    const store = {
+      setWorkspaceSession: vi.fn(),
+      updateUI: vi.fn(),
+      flushOrThrow: vi.fn(() => {
+        throw new Error('disk full')
+      }),
+      flushActiveViewPreferenceOrThrow: vi.fn()
+    }
+    registerRendererShutdownCheckpointHandler(store as never)
+
+    const handler = syncHandlers.get('app:persist-before-unload-sync')
+    const event: { returnValue?: unknown } = {}
+    handler?.(event, { sessions: [], ui: { activeView: 'settings' } })
+
+    expect(event.returnValue).toEqual({ ok: false })
+  })
+
+  it('still flushes the active-view sidecar when the durable flush throws', () => {
+    // Why: the two stores are independent; a durable-state failure must not drop
+    // the tiny active-view checkpoint (and vice versa).
+    const store = {
+      setWorkspaceSession: vi.fn(),
+      updateUI: vi.fn(),
+      flushOrThrow: vi.fn(() => {
+        throw new Error('disk full')
+      }),
+      flushActiveViewPreferenceOrThrow: vi.fn()
+    }
+    registerRendererShutdownCheckpointHandler(store as never)
+
+    const handler = syncHandlers.get('app:persist-before-unload-sync')
+    const event: { returnValue?: unknown } = {}
+    handler?.(event, { sessions: [], ui: { activeView: 'settings' } })
+
+    expect(store.flushActiveViewPreferenceOrThrow).toHaveBeenCalledTimes(1)
+    expect(event.returnValue).toEqual({ ok: false })
+  })
+
+  it('flushes the durable store even when the active-view flush throws', () => {
+    const store = {
+      setWorkspaceSession: vi.fn(),
+      updateUI: vi.fn(),
+      flushOrThrow: vi.fn(),
+      flushActiveViewPreferenceOrThrow: vi.fn(() => {
+        throw new Error('disk full')
+      })
+    }
+    registerRendererShutdownCheckpointHandler(store as never)
+
+    const handler = syncHandlers.get('app:persist-before-unload-sync')
+    const event: { returnValue?: unknown } = {}
+    handler?.(event, { sessions: [], ui: { activeView: 'settings' } })
+
+    expect(store.flushOrThrow).toHaveBeenCalledTimes(1)
+    expect(event.returnValue).toEqual({ ok: false })
+  })
+})
diff --git a/src/main/ipc/renderer-shutdown-checkpoint.ts b/src/main/ipc/renderer-shutdown-checkpoint.ts
new file mode 100644
index 00000000000..d268d388dd0
--- /dev/null
+++ b/src/main/ipc/renderer-shutdown-checkpoint.ts
@@ -0,0 +1,41 @@
+import { ipcMain } from 'electron'
+import type { ExecutionHostId } from '../../shared/execution-host'
+import type { PersistedUIState, WorkspaceSessionState } from '../../shared/types'
+import type { Store } from '../persistence'
+
+type PersistBeforeUnloadSyncArgs = {
+  sessions: { state: WorkspaceSessionState; hostId?: ExecutionHostId }[]
+  ui: Partial<PersistedUIState>
+}
+
+export function registerRendererShutdownCheckpointHandler(store: Store): void {
+  ipcMain.on('app:persist-before-unload-sync', (event, args: PersistBeforeUnloadSyncArgs) => {
+    let ok = true
+    // Why: apply both renderer-owned snapshots before synchronously flushing
+    // each owning store, so an immediate exit cannot outrun either update.
+    try {
+      for (const { state, hostId } of args.sessions) {
+        store.setWorkspaceSession(state, hostId)
+      }
+      store.updateUI(args.ui)
+    } catch (error) {
+      console.error('[app] Failed to stage renderer state before unload:', error)
+      ok = false
+    }
+    // Why: the durable snapshot and the active-view sidecar are independent stores;
+    // flush each on its own so one store's failure can't skip the other's checkpoint.
+    try {
+      store.flushOrThrow()
+    } catch (error) {
+      console.error('[app] Failed to flush durable state before unload:', error)
+      ok = false
+    }
+    try {
+      store.flushActiveViewPreferenceOrThrow()
+    } catch (error) {
+      console.error('[app] Failed to flush active-view preference before unload:', error)
+      ok = false
+    }
+    event.returnValue = { ok }
+  })
+}
diff --git a/src/main/persistence.ts b/src/main/persistence.ts
index e8ae1a7bdda..3810763057a 100644
--- a/src/main/persistence.ts
+++ b/src/main/persistence.ts
@@ -217,6 +217,7 @@ import { normalizeTerminalLineHeight } from '../shared/terminal-line-height-sett
 import { normalizeUiLanguage } from '../shared/ui-language'
 import { normalizeBrowserPageZoomLevel } from '../shared/browser-page-zoom'
 import { persistedUIValuesEqual } from '../shared/persisted-ui-equality'
+import { ActiveViewPreference } from './active-view-preference'
 import {
   normalizeFolderWorkspaceName,
   normalizeFolderWorkspaces
@@ -2627,6 +2628,7 @@ export type StoreOptions = {
 export class Store {
   private state: PersistedState
   private readonly dataFile: string
+  private readonly activeViewPreference: ActiveViewPreference
   private readonly terminalScrollbackSnapshotStorage: TerminalScrollbackSnapshotStorage
   private writeTimer: ReturnType<typeof setTimeout> | null = null
   private pendingWrite: Promise<void> | null = null
@@ -2667,6 +2669,9 @@ export class Store {
     const loaded = this.load()
     const normalized = normalizePersistedPaneIdentityState(loaded)
     this.state = normalized.state
+    // Why: activeView is a frequent, tiny preference; keeping it beside the
+    // profile avoids serializing the multi-MB recovery store on navigation.
+    this.activeViewPreference = new ActiveViewPreference(this.dataFile, this.state.ui?.activeView)
     const adaptedProjectGroups = this.adaptFlatFolderScanProjectGroups()
     for (const entry of normalized.migrationUnsupportedEntries) {
       setMigrationUnsupportedPty(entry)
@@ -3698,9 +3703,7 @@ export class Store {
 
   /** Wait for any in-flight async disk write to complete. Used in tests. */
   async waitForPendingWrite(): Promise<void> {
-    if (this.pendingWrite) {
-      await this.pendingWrite
-    }
+    await Promise.all([this.pendingWrite, this.activeViewPreference.waitForPendingWrite()])
   }
 
   // Why githubCache is omitted: it is memory-only during the session (see
@@ -3857,6 +3860,10 @@ export class Store {
     this.writeToDiskSync({ force: asyncWriteWasInFlight })
   }
 
+  flushActiveViewPreferenceOrThrow(): void {
+    this.activeViewPreference.flushOrThrow()
+  }
+
   // ── Repos ──────────────────────────────────────────────────────────
 
   getRepos(): Repo[] {
@@ -5490,17 +5497,31 @@ export class Store {
       ),
       featureTipsSeenIds: normalizeFeatureTipIds(this.state.ui?.featureTipsSeenIds),
       contextualToursSeenIds: normalizeContextualTourIds(this.state.ui?.contextualToursSeenIds),
-      featureInteractions: normalizeFeatureInteractions(this.state.ui?.featureInteractions)
+      featureInteractions: normalizeFeatureInteractions(this.state.ui?.featureInteractions),
+      activeView: this.activeViewPreference.get()
     }
   }
 
   updateUI(updates: Partial<PersistedState['ui']>): void {
     const sanitizedUpdates = stripMainOwnedTelemetryMarkerFromUI(updates)
-    const previousUI = this.getUI()
+    const { activeView, ...durableUpdates } = sanitizedUpdates
+    const activeViewChanged = this.activeViewPreference.set(activeView)
+    if (Object.keys(durableUpdates).length === 0) {
+      if (activeViewChanged) {
+        this.notifyUIChanged()
+      }
+      return
+    }
     const currentUI = {
       ...getDefaultUIState(),
       ...stripMainOwnedTelemetryMarkerFromUI(this.state.ui)
     }
+    const previousUI = {
+      ...this.getUI(),
+      // Why: the legacy field stays unchanged as a migration/downgrade
+      // fallback; the profile sidecar is authoritative in current builds.
+      activeView: currentUI.activeView
+    }
     const nextRightSidebarTab =
       sanitizedUpdates.rightSidebarTab !== undefined
         ? normalizeRightSidebarTab(sanitizedUpdates.rightSidebarTab)
@@ -5519,16 +5540,17 @@ export class Store {
             )
     const nextUI = {
       ...currentUI,
-      ...sanitizedUpdates,
-      groupBy: sanitizedUpdates.groupBy
-        ? normalizeGroupBy(sanitizedUpdates.groupBy)
+      ...durableUpdates,
+      groupBy: durableUpdates.groupBy
+        ? normalizeGroupBy(durableUpdates.groupBy)
         : normalizeGroupBy(this.state.ui?.groupBy),
-      sortBy: sanitizedUpdates.sortBy
-        ? normalizeSortBy(sanitizedUpdates.sortBy)
+      sortBy: durableUpdates.sortBy
+        ? normalizeSortBy(durableUpdates.sortBy)
         : normalizeSortBy(this.state.ui?.sortBy),
       projectOrderBy: updates.projectOrderBy
         ? normalizeProjectOrderBy(updates.projectOrderBy)
         : normalizeProjectOrderBy(this.state.ui?.projectOrderBy),
+      activeView: currentUI.activeView,
       rightSidebarTab: nextRightSidebarTab,
       rightSidebarExplorerView: nextRightSidebarExplorerView,
       worktreeCardProperties:
@@ -5603,6 +5625,9 @@ export class Store {
           : normalizeFeatureInteractions(this.state.ui?.featureInteractions)
     }
     if (persistedUIValuesEqual(previousUI, nextUI)) {
+      if (activeViewChanged) {
+        this.notifyUIChanged()
+      }
       return
     }
     this.state.ui = nextUI
@@ -6595,6 +6620,11 @@ export class Store {
     } catch (err) {
       console.error('[persistence] Failed to flush state:', err)
     }
+    try {
+      this.flushActiveViewPreferenceOrThrow()
+    } catch (err) {
+      console.error('[active-view] Failed to flush preference:', err)
+    }
     this.writeGithubCacheSnapshotSync()
   }
 
diff --git a/src/main/window/createMainWindow.test.ts b/src/main/window/createMainWindow.test.ts
index 3b69b9c1253..5b84fd1f020 100644
--- a/src/main/window/createMainWindow.test.ts
+++ b/src/main/window/createMainWindow.test.ts
@@ -1484,6 +1484,7 @@ describe('createMainWindow', () => {
 
     windowHandlers['will-prevent-unload']()
     expect(onQuitAborted).toHaveBeenCalledTimes(1)
+    expect(webContents.send).toHaveBeenCalledWith('window:unload-prevented')
   })
 
   it('allows close after the renderer process is gone', () => {
diff --git a/src/main/window/createMainWindow.ts b/src/main/window/createMainWindow.ts
index b12583377b1..c07ed455461 100644
--- a/src/main/window/createMainWindow.ts
+++ b/src/main/window/createMainWindow.ts
@@ -1148,6 +1148,7 @@ export function createMainWindow(
     // aborting Cmd+Q still gets their size saved.
     windowClosing = false
     opts?.onQuitAborted?.()
+    mainWindow.webContents.send('window:unload-prevented')
   })
 
   const onConfirmClose = (): void => {
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 487f7b2e0dd..2e0d86ab3b2 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -928,6 +928,12 @@ export type AppApi = {
   /** Reloads the current app renderer through main so expected renderer
    *  teardown can be classified before Electron emits process-gone events. */
   reload: () => Promise<void>
+  /** Commits the renderer's final locally durable state before unload and
+   *  throws when the blocking durable write fails. */
+  persistBeforeUnloadSync: (args: {
+    sessions: { state: WorkspaceSessionState; hostId?: ExecutionHostId }[]
+    ui: Partial<PersistedUIState>
+  }) => void
   /** Resolves when the daemon PTY provider and hook receiver have either
    *  started or failed open for the first BrowserWindow. */
   awaitFirstWindowStartupServices: () => Promise<void>
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 5571f9349b9..da24ff26aa7 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -184,16 +184,13 @@ import type {
   NativeChatReadSessionResult,
   NativeChatSubscriptionFrame
 } from './api-types'
-import {
-  ORCA_EDITOR_PREPARE_HOT_EXIT_EVENT,
-  type EditorPrepareHotExitDetail
-} from '../shared/editor-save-events'
 import {
   ORCA_APP_RESTART_ABORTED_EVENT,
   ORCA_APP_RESTART_STARTED_EVENT,
   ORCA_UPDATER_QUIT_AND_INSTALL_ABORTED_EVENT,
   ORCA_UPDATER_QUIT_AND_INSTALL_STARTED_EVENT
 } from '../shared/updater-renderer-events'
+import { ORCA_RENDERER_UNLOAD_PREVENTED_EVENT } from '../shared/renderer-shutdown-events'
 import {
   ORCA_INTERNAL_FILE_DRAG_TYPE,
   createNativeFileDropPayload,
@@ -228,11 +225,26 @@ import type {
   ReactErrorBoundaryReportResult
 } from '../shared/crash-reporting'
 import type { PreloadApi } from './api-types'
+import {
+  createUpdaterQuitAbortRelay,
+  prepareRendererForAppRestart
+} from './renderer-restart-preparation'
 
 type NativeFileDropCallback = (data: NativeFileDropPayload) => void
 
 const nativeFileDropCallbacks: NativeFileDropCallback[] = []
 let nativeFileDropListenerRegistered = false
+const updaterQuitAbortRelay = createUpdaterQuitAbortRelay(
+  window,
+  ORCA_UPDATER_QUIT_AND_INSTALL_ABORTED_EVENT
+)
+
+ipcRenderer.on('updater:status', (_event, status: UpdateStatus) => {
+  updaterQuitAbortRelay.handleStatus(status)
+})
+ipcRenderer.on('window:unload-prevented', () => {
+  window.dispatchEvent(new Event(ORCA_RENDERER_UNLOAD_PREVENTED_EVENT))
+})
 
 function getLinuxDisplayServer(): 'wayland' | 'x11' | null {
   if (process.platform !== 'linux') {
@@ -248,54 +260,6 @@ function getLinuxDisplayServer(): 'wayland' | 'x11' | null {
   return process.env.DISPLAY ? 'x11' : null
 }
 
-type AppRestartPrepOptions = {
-  startedEventName: string
-  abortedEventName: string
-}
-
-function requestEditorHotExitBackup(): Promise<void> {
-  return new Promise<void>((resolve, reject) => {
-    let claimed = false
-    window.dispatchEvent(
-      new CustomEvent<EditorPrepareHotExitDetail>(ORCA_EDITOR_PREPARE_HOT_EXIT_EVENT, {
-        detail: {
-          claim: () => {
-            claimed = true
-          },
-          resolve,
-          reject: (message) => {
-            reject(new Error(message))
-          }
-        }
-      })
-    )
-
-    // Why: restart paths can run before the editor autosave controller mounts.
-    // With no claimant, there are no renderer-owned dirty buffers to back up.
-    if (!claimed) {
-      resolve()
-    }
-  })
-}
-
-async function prepareRendererForAppRestart({
-  startedEventName,
-  abortedEventName
-}: AppRestartPrepOptions): Promise<void> {
-  window.dispatchEvent(new Event(startedEventName))
-
-  try {
-    await requestEditorHotExitBackup()
-  } catch (error) {
-    window.dispatchEvent(new Event(abortedEventName))
-    throw error
-  }
-
-  // Dispatch beforeunload now so terminal buffers are captured while panes are
-  // still mounted; update installs later bypass the ordinary close sequence.
-  window.dispatchEvent(new Event('beforeunload'))
-}
-
 const onNativeFileDrop = (_event: Electron.IpcRendererEvent, data: NativeFileDropPayload): void => {
   for (const callback of Array.from(nativeFileDropCallbacks)) {
     callback(data)
@@ -474,7 +438,7 @@ const api = {
       ipcRenderer.invoke('app:getFeatureWallAssetBaseUrl'),
     relaunch: (): Promise<void> => ipcRenderer.invoke('app:relaunch'),
     restart: async (): Promise<void> => {
-      await prepareRendererForAppRestart({
+      await prepareRendererForAppRestart(window, {
         startedEventName: ORCA_APP_RESTART_STARTED_EVENT,
         abortedEventName: ORCA_APP_RESTART_ABORTED_EVENT
       })
@@ -486,6 +450,16 @@ const api = {
       }
     },
     reload: (): Promise<void> => ipcRenderer.invoke('app:reload'),
+    persistBeforeUnloadSync: (
+      args: Parameters<PreloadApi['app']['persistBeforeUnloadSync']>[0]
+    ) => {
+      const result = ipcRenderer.sendSync('app:persist-before-unload-sync', args) as {
+        ok?: unknown
+      }
+      if (result?.ok !== true) {
+        throw new Error('Failed to persist renderer state before unload.')
+      }
+    },
     awaitFirstWindowStartupServices: (): Promise<void> =>
       ipcRenderer.invoke('app:awaitFirstWindowStartupServices'),
     startupDiagnostic: (event: string, details?: Record<string, unknown>): Promise<void> =>
@@ -2766,14 +2740,15 @@ const api = {
     download: () => ipcRenderer.invoke('updater:download'),
     dismissNudge: () => ipcRenderer.invoke('updater:dismissNudge'),
     quitAndInstall: async (): Promise<void> => {
-      await prepareRendererForAppRestart({
+      await prepareRendererForAppRestart(window, {
         startedEventName: ORCA_UPDATER_QUIT_AND_INSTALL_STARTED_EVENT,
         abortedEventName: ORCA_UPDATER_QUIT_AND_INSTALL_ABORTED_EVENT
       })
+      updaterQuitAbortRelay.markPrepared()
       try {
         return await ipcRenderer.invoke('updater:quitAndInstall')
       } catch (error) {
-        window.dispatchEvent(new Event(ORCA_UPDATER_QUIT_AND_INSTALL_ABORTED_EVENT))
+        updaterQuitAbortRelay.abort()
         throw error
       }
     },
diff --git a/src/preload/renderer-restart-preparation.test.ts b/src/preload/renderer-restart-preparation.test.ts
new file mode 100644
index 00000000000..c216ef93f35
--- /dev/null
+++ b/src/preload/renderer-restart-preparation.test.ts
@@ -0,0 +1,90 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import type { UpdateStatus } from '../shared/types'
+import {
+  createUpdaterQuitAbortRelay,
+  prepareRendererForAppRestart
+} from './renderer-restart-preparation'
+
+describe('prepareRendererForAppRestart', () => {
+  it('aborts when the dispatched shutdown checkpoint prevents unload', async () => {
+    const eventTarget = new EventTarget()
+    const started = vi.fn()
+    const aborted = vi.fn()
+    const checkpoint = vi.fn((event: Event) => event.preventDefault())
+    eventTarget.addEventListener('restart-started', started)
+    eventTarget.addEventListener('restart-aborted', aborted)
+    eventTarget.addEventListener('beforeunload', checkpoint)
+
+    await expect(
+      prepareRendererForAppRestart(eventTarget, {
+        startedEventName: 'restart-started',
+        abortedEventName: 'restart-aborted'
+      })
+    ).rejects.toThrow('Renderer shutdown checkpoint was not completed.')
+
+    expect(started).toHaveBeenCalledTimes(1)
+    expect(checkpoint).toHaveBeenCalledTimes(1)
+    expect(aborted).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('createUpdaterQuitAbortRelay', () => {
+  it('resets a prepared update restart when async updater status reports failure', () => {
+    const eventTarget = new EventTarget()
+    const aborted = vi.fn()
+    eventTarget.addEventListener('update-restart-aborted', aborted)
+    const relay = createUpdaterQuitAbortRelay(eventTarget, 'update-restart-aborted')
+    relay.markPrepared()
+
+    relay.handleStatus({ state: 'error', message: 'install failed' } satisfies UpdateStatus)
+    relay.handleStatus({ state: 'error', message: 'duplicate failure' } satisfies UpdateStatus)
+
+    expect(aborted).toHaveBeenCalledTimes(1)
+  })
+
+  it('ignores updater errors when no update restart was prepared', () => {
+    const eventTarget = new EventTarget()
+    const aborted = vi.fn()
+    eventTarget.addEventListener('update-restart-aborted', aborted)
+    const relay = createUpdaterQuitAbortRelay(eventTarget, 'update-restart-aborted')
+
+    relay.handleStatus({ state: 'error', message: 'check failed' } satisfies UpdateStatus)
+
+    expect(aborted).not.toHaveBeenCalled()
+  })
+})
+
+describe('preload restart wiring', () => {
+  const source = readFileSync(join(process.cwd(), 'src/preload/index.ts'), 'utf8')
+
+  it('relays prevented unload and async updater failure IPC into renderer lifecycle events', () => {
+    expect(source).toContain("ipcRenderer.on('updater:status'")
+    expect(source).toContain('updaterQuitAbortRelay.handleStatus(status)')
+    expect(source).toContain("ipcRenderer.on('window:unload-prevented'")
+    expect(source).toContain(
+      'window.dispatchEvent(new Event(ORCA_RENDERER_UNLOAD_PREVENTED_EVENT))'
+    )
+  })
+
+  it('marks updater preparation before invoking main and aborts it on immediate IPC failure', () => {
+    const start = source.indexOf('quitAndInstall: async (): Promise<void> => {')
+    const end = source.indexOf('onStatus: (callback) => {', start)
+    expect(start).toBeGreaterThanOrEqual(0)
+    expect(end).toBeGreaterThan(start)
+    const block = source.slice(start, end)
+    const prepare = block.indexOf('await prepareRendererForAppRestart(window, {')
+    const markPrepared = block.indexOf('updaterQuitAbortRelay.markPrepared()')
+    const invoke = block.indexOf("ipcRenderer.invoke('updater:quitAndInstall')")
+    const abort = block.indexOf('updaterQuitAbortRelay.abort()')
+
+    expect(prepare).toBeGreaterThanOrEqual(0)
+    expect(markPrepared).toBeGreaterThan(prepare)
+    expect(invoke).toBeGreaterThan(markPrepared)
+    expect(abort).toBeGreaterThan(invoke)
+    expect(block).toMatch(
+      /try \{\s*return await ipcRenderer\.invoke\('updater:quitAndInstall'\)\s*\} catch \(error\) \{\s*updaterQuitAbortRelay\.abort\(\)\s*throw error\s*\}/
+    )
+  })
+})
diff --git a/src/preload/renderer-restart-preparation.ts b/src/preload/renderer-restart-preparation.ts
new file mode 100644
index 00000000000..4f526844bd8
--- /dev/null
+++ b/src/preload/renderer-restart-preparation.ts
@@ -0,0 +1,89 @@
+import {
+  ORCA_EDITOR_PREPARE_HOT_EXIT_EVENT,
+  type EditorPrepareHotExitDetail
+} from '../shared/editor-save-events'
+import type { UpdateStatus } from '../shared/types'
+
+export type AppRestartPrepOptions = {
+  startedEventName: string
+  abortedEventName: string
+}
+
+function requestEditorHotExitBackup(eventTarget: EventTarget): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    let claimed = false
+    eventTarget.dispatchEvent(
+      new CustomEvent<EditorPrepareHotExitDetail>(ORCA_EDITOR_PREPARE_HOT_EXIT_EVENT, {
+        detail: {
+          claim: () => {
+            claimed = true
+          },
+          resolve,
+          reject: (message) => {
+            reject(new Error(message))
+          }
+        }
+      })
+    )
+
+    // Why: restart paths can run before the editor autosave controller mounts.
+    // With no claimant, there are no renderer-owned dirty buffers to back up.
+    if (!claimed) {
+      resolve()
+    }
+  })
+}
+
+export async function prepareRendererForAppRestart(
+  eventTarget: EventTarget,
+  { startedEventName, abortedEventName }: AppRestartPrepOptions
+): Promise<void> {
+  eventTarget.dispatchEvent(new Event(startedEventName))
+
+  try {
+    await requestEditorHotExitBackup(eventTarget)
+    // Why: update installs can bypass native close. A cancelable synthetic
+    // unload both captures mounted terminals and reports checkpoint failure.
+    const accepted = eventTarget.dispatchEvent(new Event('beforeunload', { cancelable: true }))
+    if (!accepted) {
+      throw new Error('Renderer shutdown checkpoint was not completed.')
+    }
+  } catch (error) {
+    eventTarget.dispatchEvent(new Event(abortedEventName))
+    throw error
+  }
+}
+
+export type UpdaterQuitAbortRelay = {
+  markPrepared: () => void
+  abort: () => void
+  handleStatus: (status: UpdateStatus) => void
+}
+
+export function createUpdaterQuitAbortRelay(
+  eventTarget: EventTarget,
+  abortedEventName: string
+): UpdaterQuitAbortRelay {
+  let prepared = false
+  const abort = (): void => {
+    if (!prepared) {
+      return
+    }
+    prepared = false
+    eventTarget.dispatchEvent(new Event(abortedEventName))
+  }
+
+  return {
+    markPrepared(): void {
+      prepared = true
+    },
+    abort,
+    handleStatus(status): void {
+      // Why: quitAndInstall IPC resolves after scheduling; a later updater
+      // error is the authoritative signal that the app will remain open.
+      if (status.state === 'error') {
+        abort()
+      }
+    }
+  }
+}
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 6a150add541..977b32d30f6 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -110,16 +110,26 @@ import { useWebSessionTabsSync } from './runtime/web-session-tabs-sync'
 import { useGlobalFileDrop } from './hooks/useGlobalFileDrop'
 import { useRadixBodyPointerEventsRecovery } from './hooks/useRadixBodyPointerEventsRecovery'
 import { registerUpdaterBeforeUnloadBypass } from './lib/updater-beforeunload'
+import {
+  ORCA_APP_RESTART_ABORTED_EVENT,
+  ORCA_UPDATER_QUIT_AND_INSTALL_ABORTED_EVENT
+} from '../../shared/updater-renderer-events'
+import { ORCA_RENDERER_UNLOAD_PREVENTED_EVENT } from '../../shared/renderer-shutdown-events'
 import {
   buildWorkspaceSessionPayload,
   shouldPersistWorkspaceSession
 } from './lib/workspace-session'
 import { createSessionWriteSubscriber } from './lib/session-write-subscriber'
+import { buildActiveViewUnloadPatch } from './lib/active-view-persist'
 import {
+  buildWorkspaceSessionHostSnapshots,
   fetchWorkspaceSessionWithRuntimeHostOwners,
-  patchWorkspaceSessionByHost,
-  persistWorkspaceSessionByHostSync
+  patchWorkspaceSessionByHost
 } from './lib/workspace-session-host-persistence'
+import {
+  createShutdownCheckpointBeforeUnloadHandler,
+  createShutdownCheckpointGuard
+} from './lib/shutdown-checkpoint-guard'
 import { collectFolderWorkspaceKeysFromSession } from './lib/workspace-session-hydration-keys'
 import {
   getStartupErrorFallbackUI,
@@ -1342,8 +1352,8 @@ function App(): React.JSX.Element {
     })
   }, [])
 
-  // On shutdown, capture terminal scrollback buffers and flush to disk.
-  // Runs synchronously in beforeunload: capture → Zustand set → sendSync → flush.
+  // On shutdown, capture terminal scrollback buffers and flush all durable
+  // renderer state through one synchronous main-process checkpoint.
   useEffect(() => {
     // Why: beforeunload fires twice during a manual quit — once from the
     // synthetic dispatch in the onWindowCloseRequested handler (captures
@@ -1352,39 +1362,50 @@ function App(): React.JSX.Element {
     // two firings, PTY exit events can arrive and unmount TerminalPanes,
     // emptying shutdownBufferCaptures. The guard prevents the second call
     // from overwriting the good session data with an empty snapshot.
-    let shutdownBuffersCaptured = false
-    const captureAndFlush = (): void => {
-      if (shutdownBuffersCaptured) {
-        return
-      }
-      if (!shouldPersistWorkspaceSession(useAppStore.getState())) {
-        return
-      }
-      for (const capture of shutdownBufferCaptures.values()) {
-        try {
-          capture({ includeLocalBuffers: false })
-        } catch {
-          // Don't let one pane's failure block the rest.
+    const shutdownCheckpoint = createShutdownCheckpointGuard(() => {
+      const shouldCaptureSession = shouldPersistWorkspaceSession(useAppStore.getState())
+      if (shouldCaptureSession) {
+        for (const capture of shutdownBufferCaptures.values()) {
+          try {
+            capture({ includeLocalBuffers: false })
+          } catch {
+            // Don't let one pane's failure block the rest.
+          }
         }
+        // Why: agent provider session ids live only in agentStatusByPaneKey,
+        // which is in-memory. Capture them into the persisted sleeping-session
+        // map so a daemon/session death while the app is closed can still
+        // cold-restore via the agent's resume command (#5232).
+        useAppStore.getState().captureAllSleepingAgentSessions('quit')
       }
-      // Why: agent provider session ids live only in agentStatusByPaneKey,
-      // which is in-memory. Capture them into the persisted sleeping-session
-      // map so a daemon/session death while the app is closed can still
-      // cold-restore via the agent's resume command (#5232).
-      useAppStore.getState().captureAllSleepingAgentSessions('quit')
       // Why: re-read state after capture() calls populated scrollback buffers
       // into the store via Zustand setters. The earlier read is only for the
       // gating flags and would miss those updates.
       const freshState = useAppStore.getState()
-      persistWorkspaceSessionByHostSync(
-        window.api.session,
-        buildWorkspaceSessionPayload(freshState),
-        freshState
+      const sessionSnapshots = shouldCaptureSession
+        ? buildWorkspaceSessionHostSnapshots(buildWorkspaceSessionPayload(freshState), freshState)
+        : []
+      // Why: one blocking checkpoint closes the immediate-quit race for both
+      // the narrow view preference and the larger session recovery snapshots.
+      window.api.app.persistBeforeUnloadSync({
+        sessions: sessionSnapshots,
+        ui: buildActiveViewUnloadPatch(freshState)
+      })
+    })
+    const persistBeforeUnload = createShutdownCheckpointBeforeUnloadHandler(shutdownCheckpoint)
+    window.addEventListener('beforeunload', persistBeforeUnload)
+    window.addEventListener(ORCA_APP_RESTART_ABORTED_EVENT, shutdownCheckpoint.reset)
+    window.addEventListener(ORCA_UPDATER_QUIT_AND_INSTALL_ABORTED_EVENT, shutdownCheckpoint.reset)
+    window.addEventListener(ORCA_RENDERER_UNLOAD_PREVENTED_EVENT, shutdownCheckpoint.reset)
+    return () => {
+      window.removeEventListener('beforeunload', persistBeforeUnload)
+      window.removeEventListener(ORCA_APP_RESTART_ABORTED_EVENT, shutdownCheckpoint.reset)
+      window.removeEventListener(
+        ORCA_UPDATER_QUIT_AND_INSTALL_ABORTED_EVENT,
+        shutdownCheckpoint.reset
       )
-      shutdownBuffersCaptured = true
+      window.removeEventListener(ORCA_RENDERER_UNLOAD_PREVENTED_EVENT, shutdownCheckpoint.reset)
     }
-    window.addEventListener('beforeunload', captureAndFlush)
-    return () => window.removeEventListener('beforeunload', captureAndFlush)
   }, [])
 
   // Why: beforeunload never fires on a hard kill (crash, forced update
@@ -1448,10 +1469,10 @@ function App(): React.JSX.Element {
         hideAutomationGeneratedWorkspaces,
         showDotfilesByWorktree,
         filterRepoIds,
-        // Why: persist the active view so a reload restores it. openTaskPage etc.
-        // mutate activeView directly (not via setActiveView), so the value-keyed
-        // writer is what catches every transition.
-        activeView,
+        // Why (#9002): activeView is deliberately NOT included here. It used to
+        // ride this same 150ms writer (#8265), which meant every top-level view
+        // switch scheduled a full durable-state save. The narrow preference
+        // effect below persists it without touching the recovery snapshot.
         // Why: rides the same debounced save so dashboard auto-acks (which fire
         // on focus/visibility) and the in-memory ack cleanup paths in
         // agent-status.ts (close/dismiss) both flow to disk through map
@@ -1478,10 +1499,18 @@ function App(): React.JSX.Element {
     hideAutomationGeneratedWorkspaces,
     showDotfilesByWorktree,
     filterRepoIds,
-    activeView,
     acknowledgedAgentsByPaneKey
   ])
 
+  // Why (#9002): activeView has its own tiny profile preference, so it can track
+  // every switch without scheduling the multi-MB durable-state writer.
+  useEffect(() => {
+    if (!persistedUIReady) {
+      return
+    }
+    void window.api.ui.set({ activeView })
+  }, [activeView, persistedUIReady])
+
   // Apply theme to document
   useEffect(() => {
     if (!settings) {
diff --git a/src/renderer/src/app-startup-routing.test.ts b/src/renderer/src/app-startup-routing.test.ts
index 119ac5f77e0..62f9040d31c 100644
--- a/src/renderer/src/app-startup-routing.test.ts
+++ b/src/renderer/src/app-startup-routing.test.ts
@@ -254,4 +254,71 @@ describe('renderer startup runtime routing', () => {
     expect(source).toContain('statusBarVisible ? (')
     expect(source).toContain('h-6 min-h-[24px] shrink-0 border-t border-border')
   })
+
+  it('keeps activeView off the 150ms debounced UI writer hot path (#9002)', () => {
+    const source = readFileSync(join(process.cwd(), 'src/renderer/src/App.tsx'), 'utf8')
+    const writerStart = source.indexOf('const timer = window.setTimeout(() => {')
+    const writerEnd = source.indexOf('}, 150)', writerStart)
+    const writerBlock = source.slice(writerStart, writerEnd)
+
+    expect(writerStart).toBeGreaterThanOrEqual(0)
+    expect(writerEnd).toBeGreaterThan(writerStart)
+    // Why: this field riding the writer's payload (#8265) is exactly the
+    // #9002 regression — every switch scheduled a full durable-state save. It
+    // must persist through its narrow preference or unload path instead. Matched as
+    // a standalone object-literal property (not the surrounding prose, which
+    // legitimately references the field name) so the assertion is precise.
+    expect(writerBlock).not.toMatch(/^\s*activeView,\s*$/m)
+
+    const depsStart = source.indexOf('}, [', writerEnd)
+    const depsEnd = source.indexOf('])', depsStart)
+    const depsBlock = source.slice(depsStart, depsEnd)
+    expect(depsBlock).not.toMatch(/^\s*activeView,?\s*$/m)
+  })
+
+  it('persists activeView through its narrow preference on every switch (#9002)', () => {
+    const source = readFileSync(join(process.cwd(), 'src/renderer/src/App.tsx'), 'utf8')
+
+    const preferenceEffect = [
+      '// Why (#9002): activeView has its own tiny profile preference',
+      'void window.api.ui.set({ activeView })',
+      '}, [activeView, persistedUIReady])'
+    ]
+    for (const marker of preferenceEffect) {
+      expect(source).toContain(marker)
+    }
+    expect(source).not.toContain('createActiveViewIdleFlush')
+    expect(source).not.toContain("window.addEventListener('blur', handleBlur)")
+  })
+
+  it('checkpoints activeView and all session snapshots through one beforeunload handler (#9002)', () => {
+    const source = readFileSync(join(process.cwd(), 'src/renderer/src/App.tsx'), 'utf8')
+    const checkpointStart = source.indexOf(
+      'const shutdownCheckpoint = createShutdownCheckpointGuard(() => {'
+    )
+    const checkpointEnd = source.indexOf(
+      'const persistBeforeUnload = createShutdownCheckpointBeforeUnloadHandler(shutdownCheckpoint)',
+      checkpointStart
+    )
+    expect(checkpointStart).toBeGreaterThanOrEqual(0)
+    expect(checkpointEnd).toBeGreaterThan(checkpointStart)
+    const checkpointBlock = source.slice(checkpointStart, checkpointEnd)
+
+    expect(checkpointBlock).toContain('const sessionSnapshots = shouldCaptureSession')
+    expect(checkpointBlock).toContain(
+      'buildWorkspaceSessionHostSnapshots(buildWorkspaceSessionPayload(freshState), freshState)'
+    )
+    expect(checkpointBlock).toContain('window.api.app.persistBeforeUnloadSync({')
+    expect(checkpointBlock).toContain('sessions: sessionSnapshots')
+    expect(checkpointBlock).toContain('ui: buildActiveViewUnloadPatch(freshState)')
+    expect(source).toContain(
+      'window.addEventListener(ORCA_APP_RESTART_ABORTED_EVENT, shutdownCheckpoint.reset)'
+    )
+    expect(source).toContain(
+      'window.addEventListener(ORCA_RENDERER_UNLOAD_PREVENTED_EVENT, shutdownCheckpoint.reset)'
+    )
+    expect(source).toContain("window.addEventListener('beforeunload', persistBeforeUnload)")
+    expect(source.match(/window\.addEventListener\('beforeunload'/g) ?? []).toHaveLength(1)
+    expect(source).not.toContain('window.api.ui.setSync')
+  })
 })
diff --git a/src/renderer/src/components/Terminal.tsx b/src/renderer/src/components/Terminal.tsx
index 14df288fd16..5c2b0830aff 100644
--- a/src/renderer/src/components/Terminal.tsx
+++ b/src/renderer/src/components/Terminal.tsx
@@ -34,6 +34,7 @@ import {
   requestEditorSaveQuiesce
 } from './editor/editor-autosave'
 import { isIntentionalAppRestartInProgress } from '@/lib/updater-beforeunload'
+import { preventUnloadAndScheduleShutdownCheckpointReset } from '@/lib/shutdown-checkpoint-guard'
 import EditorAutosaveController from './editor/EditorAutosaveController'
 import type { Tab, TabContentType, TabGroupLayoutNode, TuiAgent } from '../../../shared/types'
 import { hasFeatureInteraction } from '../../../shared/feature-interactions'
@@ -448,40 +449,49 @@ function Terminal(): React.JSX.Element | null {
   // dirty, so an immediate confirm would leave the window open with no UI.
   const windowCloseAfterDirtyRef = useRef<{ isQuitting: boolean } | null>(null)
 
-  const proceedToNativeWindowClose = useCallback((isQuitting: boolean) => {
-    // Why: defer this synthetic unload until we are actually ready to close so
-    // a dirty-tab preventDefault() does not fire during the initial quit IPC
-    // (that path can emit will-prevent-unload and clear isQuitting in main).
-    window.dispatchEvent(new Event('beforeunload'))
-    if (!isQuitting) {
-      const state = useAppStore.getState()
-      const localPtyIds = Object.entries(state.tabsByWorktree).flatMap(
-        ([worktreeId, worktreeTabs]) => {
-          const connectionId = getConnectionId(worktreeId)
-          if (connectionId !== null) {
-            return []
-          }
-          return worktreeTabs
-            .flatMap((tab) => state.ptyIdsByTabId[tab.id] ?? [])
-            .filter((ptyId) => !isRemoteRuntimePtyId(ptyId))
-        }
-      )
-      if (localPtyIds.length > 0) {
-        void Promise.all(localPtyIds.map((id) => window.api.pty.hasChildProcesses(id))).then(
-          (results) => {
-            if (results.some(Boolean)) {
-              setWindowCloseDialogOpen(true)
-            } else {
-              window.api.ui.confirmWindowClose()
-            }
-          }
-        )
-        return
-      }
+  const confirmNativeWindowClose = useCallback(() => {
+    // Why: capture only after every close guard has committed. A canceled child-
+    // process prompt must not consume App's synthetic/native unload guard.
+    const accepted = window.dispatchEvent(new Event('beforeunload', { cancelable: true }))
+    if (!accepted) {
+      return
     }
     window.api.ui.confirmWindowClose()
   }, [])
 
+  const proceedToNativeWindowClose = useCallback(
+    (isQuitting: boolean) => {
+      if (!isQuitting) {
+        const state = useAppStore.getState()
+        const localPtyIds = Object.entries(state.tabsByWorktree).flatMap(
+          ([worktreeId, worktreeTabs]) => {
+            const connectionId = getConnectionId(worktreeId)
+            if (connectionId !== null) {
+              return []
+            }
+            return worktreeTabs
+              .flatMap((tab) => state.ptyIdsByTabId[tab.id] ?? [])
+              .filter((ptyId) => !isRemoteRuntimePtyId(ptyId))
+          }
+        )
+        if (localPtyIds.length > 0) {
+          void Promise.all(localPtyIds.map((id) => window.api.pty.hasChildProcesses(id))).then(
+            (results) => {
+              if (results.some(Boolean)) {
+                setWindowCloseDialogOpen(true)
+              } else {
+                confirmNativeWindowClose()
+              }
+            }
+          )
+          return
+        }
+      }
+      confirmNativeWindowClose()
+    },
+    [confirmNativeWindowClose]
+  )
+
   const waitForFileClosed = useCallback((fileId: string, timeoutMs: number): Promise<boolean> => {
     if (!useAppStore.getState().openFiles.some((f) => f.id === fileId)) {
       return Promise.resolve(true)
@@ -2061,7 +2071,7 @@ function Terminal(): React.JSX.Element | null {
       }
       const dirtyFiles = useAppStore.getState().openFiles.filter((f) => f.isDirty)
       if (dirtyFiles.length > 0) {
-        e.preventDefault()
+        preventUnloadAndScheduleShutdownCheckpointReset(e, window)
       }
     }
     window.addEventListener('beforeunload', handler)
@@ -2545,7 +2555,7 @@ function Terminal(): React.JSX.Element | null {
               autoFocus
               onClick={() => {
                 setWindowCloseDialogOpen(false)
-                window.api.ui.confirmWindowClose()
+                confirmNativeWindowClose()
               }}
             >
               {translate('auto.components.Terminal.73768427cf', 'Close')}
diff --git a/src/renderer/src/components/editor/editor-autosave-controller.test.ts b/src/renderer/src/components/editor/editor-autosave-controller.test.ts
index 9d50997d947..70abf77c657 100644
--- a/src/renderer/src/components/editor/editor-autosave-controller.test.ts
+++ b/src/renderer/src/components/editor/editor-autosave-controller.test.ts
@@ -384,7 +384,7 @@ describe('attachEditorAutosaveController', () => {
     }
   })
 
-  it('backs up dirty editor drafts for hot exit without writing files', async () => {
+  it('leaves dirty editor drafts ready for the combined hot-exit checkpoint', async () => {
     const writeFile = vi.fn().mockResolvedValue(undefined)
     const setSync = vi.fn()
     const eventTarget = new EventTarget()
@@ -422,13 +422,7 @@ describe('attachEditorAutosaveController', () => {
       await vi.advanceTimersByTimeAsync(1000)
 
       expect(writeFile).not.toHaveBeenCalled()
-      expect(setSync).toHaveBeenCalledTimes(1)
-      expect(setSync.mock.calls[0][0].openFilesByWorktree['wt-1'][0]).toEqual(
-        expect.objectContaining({
-          filePath: '/repo/file.md',
-          dirtyDraftContent: ''
-        })
-      )
+      expect(setSync).not.toHaveBeenCalled()
       expect(store.getState().openFiles[0]?.isDirty).toBe(true)
       expect(store.getState().editorDrafts['/repo/file.md']).toBe('')
     } finally {
diff --git a/src/renderer/src/components/editor/editor-autosave-controller.ts b/src/renderer/src/components/editor/editor-autosave-controller.ts
index 8c8e7ec16a0..09763e148e2 100644
--- a/src/renderer/src/components/editor/editor-autosave-controller.ts
+++ b/src/renderer/src/components/editor/editor-autosave-controller.ts
@@ -5,11 +5,7 @@ import type { StoreApi } from 'zustand'
 import type { AppState } from '@/store'
 import type { OpenFile } from '@/store/slices/editor'
 import { getConnectionIdForFile } from '@/lib/connection-context'
-import {
-  buildWorkspaceSessionPayload,
-  shouldPersistWorkspaceSession
-} from '@/lib/workspace-session'
-import { persistWorkspaceSessionByHostSync } from '@/lib/workspace-session-host-persistence'
+import { shouldPersistWorkspaceSession } from '@/lib/workspace-session'
 import { findWorktreeById } from '@/store/slices/worktree-helpers'
 import { writeRuntimeFile } from '@/runtime/runtime-file-client'
 import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
@@ -340,17 +336,8 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
         return
       }
 
-      // Why: restart/update may quit before the debounced session writer fires.
-      // Write the full session now so dirty drafts restore as unsaved tabs.
-      if (shouldPersistWorkspaceSession(state)) {
-        // Why: runtime-owned worktree slices persist under their host
-        // partition, mirroring the debounced writer's split.
-        persistWorkspaceSessionByHostSync(
-          window.api.session,
-          buildWorkspaceSessionPayload(state),
-          state
-        )
-      }
+      // Why: preload dispatches beforeunload immediately after this resolves;
+      // App owns the one combined session/UI checkpoint for restart and update.
       detail.resolve()
     } catch (error) {
       detail.reject(String((error as Error)?.message ?? error))
diff --git a/src/renderer/src/lib/active-view-persist.test.ts b/src/renderer/src/lib/active-view-persist.test.ts
new file mode 100644
index 00000000000..37df61d2e20
--- /dev/null
+++ b/src/renderer/src/lib/active-view-persist.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+import { buildActiveViewUnloadPatch } from './active-view-persist'
+
+describe('buildActiveViewUnloadPatch', () => {
+  it('does not overwrite persisted UI before startup hydration completes', () => {
+    expect(buildActiveViewUnloadPatch({ activeView: 'terminal', persistedUIReady: false })).toEqual(
+      {}
+    )
+  })
+
+  it('checkpoints the latest view after startup hydration completes', () => {
+    expect(buildActiveViewUnloadPatch({ activeView: 'tasks', persistedUIReady: true })).toEqual({
+      activeView: 'tasks'
+    })
+  })
+})
diff --git a/src/renderer/src/lib/active-view-persist.ts b/src/renderer/src/lib/active-view-persist.ts
new file mode 100644
index 00000000000..79f965b33aa
--- /dev/null
+++ b/src/renderer/src/lib/active-view-persist.ts
@@ -0,0 +1,14 @@
+import type { PersistedUIState, TopLevelView } from '../../../shared/types'
+
+type ActiveViewUnloadState = {
+  activeView: TopLevelView
+  persistedUIReady: boolean
+}
+
+export function buildActiveViewUnloadPatch(
+  state: ActiveViewUnloadState
+): Partial<PersistedUIState> {
+  // Why: unloading during startup must not overwrite the saved view with the
+  // renderer default before persisted UI hydration finishes.
+  return state.persistedUIReady ? { activeView: state.activeView } : {}
+}
diff --git a/src/renderer/src/lib/shutdown-checkpoint-guard.test.ts b/src/renderer/src/lib/shutdown-checkpoint-guard.test.ts
new file mode 100644
index 00000000000..516b60354e0
--- /dev/null
+++ b/src/renderer/src/lib/shutdown-checkpoint-guard.test.ts
@@ -0,0 +1,111 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  createShutdownCheckpointBeforeUnloadHandler,
+  createShutdownCheckpointGuard,
+  preventUnloadAndScheduleShutdownCheckpointReset
+} from './shutdown-checkpoint-guard'
+import { ORCA_RENDERER_UNLOAD_PREVENTED_EVENT } from '../../../shared/renderer-shutdown-events'
+
+describe('createShutdownCheckpointGuard', () => {
+  it('dedupes the synthetic and native unload events in one close attempt', () => {
+    const persist = vi.fn()
+    const guard = createShutdownCheckpointGuard(persist)
+
+    expect(guard.persistOnce()).toBe(true)
+    expect(guard.persistOnce()).toBe(true)
+
+    expect(persist).toHaveBeenCalledTimes(1)
+  })
+
+  it('allows a new checkpoint after an aborted restart resets the attempt', () => {
+    const persist = vi.fn()
+    const guard = createShutdownCheckpointGuard(persist)
+
+    expect(guard.persistOnce()).toBe(true)
+    guard.reset()
+    expect(guard.persistOnce()).toBe(true)
+
+    expect(persist).toHaveBeenCalledTimes(2)
+  })
+
+  it('retries when the blocking checkpoint throws', () => {
+    const persist = vi.fn().mockImplementationOnce(() => {
+      throw new Error('disk full')
+    })
+    const guard = createShutdownCheckpointGuard(persist)
+
+    expect(guard.persistOnce()).toBe(false)
+    expect(guard.persistOnce()).toBe(true)
+
+    expect(persist).toHaveBeenCalledTimes(2)
+  })
+
+  it('retries after a prevented reload resets the completed checkpoint', () => {
+    const eventTarget = new EventTarget()
+    const persist = vi.fn()
+    const guard = createShutdownCheckpointGuard(persist)
+    const checkpoint = createShutdownCheckpointBeforeUnloadHandler(guard)
+    const preventReload = (event: Event): void => event.preventDefault()
+    eventTarget.addEventListener('beforeunload', checkpoint)
+    eventTarget.addEventListener('beforeunload', preventReload)
+
+    expect(eventTarget.dispatchEvent(new Event('beforeunload', { cancelable: true }))).toBe(false)
+    guard.reset()
+    eventTarget.removeEventListener('beforeunload', preventReload)
+    expect(eventTarget.dispatchEvent(new Event('beforeunload', { cancelable: true }))).toBe(true)
+
+    expect(persist).toHaveBeenCalledTimes(2)
+  })
+
+  it('cancels unload when persistence fails and remains retryable', () => {
+    const eventTarget = new EventTarget()
+    const persist = vi.fn().mockImplementationOnce(() => {
+      throw new Error('disk full')
+    })
+    const guard = createShutdownCheckpointGuard(persist)
+    const checkpoint = createShutdownCheckpointBeforeUnloadHandler(guard)
+    eventTarget.addEventListener('beforeunload', checkpoint)
+
+    expect(eventTarget.dispatchEvent(new Event('beforeunload', { cancelable: true }))).toBe(false)
+    expect(eventTarget.dispatchEvent(new Event('beforeunload', { cancelable: true }))).toBe(true)
+
+    expect(persist).toHaveBeenCalledTimes(2)
+  })
+
+  it('resets after a paired-web dirty-file veto regardless of listener order', async () => {
+    const eventTarget = new EventTarget()
+    const persist = vi.fn()
+    const guard = createShutdownCheckpointGuard(persist)
+    const preventReload = (event: Event): void => {
+      preventUnloadAndScheduleShutdownCheckpointReset(event, eventTarget)
+    }
+    eventTarget.addEventListener('beforeunload', preventReload)
+    eventTarget.addEventListener('beforeunload', createShutdownCheckpointBeforeUnloadHandler(guard))
+    eventTarget.addEventListener(ORCA_RENDERER_UNLOAD_PREVENTED_EVENT, guard.reset)
+
+    expect(eventTarget.dispatchEvent(new Event('beforeunload', { cancelable: true }))).toBe(false)
+    await Promise.resolve()
+    eventTarget.removeEventListener('beforeunload', preventReload)
+    expect(eventTarget.dispatchEvent(new Event('beforeunload', { cancelable: true }))).toBe(true)
+
+    expect(persist).toHaveBeenCalledTimes(2)
+  })
+
+  it('wires dirty editor unload vetoes to the paired-web checkpoint reset', () => {
+    const source = readFileSync(
+      join(process.cwd(), 'src/renderer/src/components/Terminal.tsx'),
+      'utf8'
+    )
+    const dirtyGuardStart = source.indexOf(
+      'const dirtyFiles = useAppStore.getState().openFiles.filter((f) => f.isDirty)'
+    )
+    const dirtyGuardEnd = source.indexOf("window.addEventListener('beforeunload', handler)")
+    expect(dirtyGuardStart).toBeGreaterThanOrEqual(0)
+    expect(dirtyGuardEnd).toBeGreaterThan(dirtyGuardStart)
+    expect(source.slice(dirtyGuardStart, dirtyGuardEnd)).toContain(
+      'preventUnloadAndScheduleShutdownCheckpointReset(e, window)'
+    )
+  })
+})
diff --git a/src/renderer/src/lib/shutdown-checkpoint-guard.ts b/src/renderer/src/lib/shutdown-checkpoint-guard.ts
new file mode 100644
index 00000000000..b2f81eed832
--- /dev/null
+++ b/src/renderer/src/lib/shutdown-checkpoint-guard.ts
@@ -0,0 +1,51 @@
+import { ORCA_RENDERER_UNLOAD_PREVENTED_EVENT } from '../../../shared/renderer-shutdown-events'
+
+export type ShutdownCheckpointGuard = {
+  persistOnce: () => boolean
+  reset: () => void
+}
+
+export function createShutdownCheckpointGuard(persist: () => void): ShutdownCheckpointGuard {
+  let persisted = false
+  return {
+    persistOnce(): boolean {
+      if (persisted) {
+        return true
+      }
+      try {
+        persist()
+      } catch {
+        // Why: browser event targets swallow listener exceptions. Returning a
+        // failure lets the caller cancel unload and keep this attempt retryable.
+        return false
+      }
+      persisted = true
+      return true
+    },
+    reset(): void {
+      persisted = false
+    }
+  }
+}
+
+export function createShutdownCheckpointBeforeUnloadHandler(
+  guard: ShutdownCheckpointGuard
+): (event: Event) => void {
+  return (event): void => {
+    if (!guard.persistOnce()) {
+      event.preventDefault()
+    }
+  }
+}
+
+export function preventUnloadAndScheduleShutdownCheckpointReset(
+  event: Event,
+  eventTarget: EventTarget
+): void {
+  event.preventDefault()
+  // Why: paired web has no Electron will-prevent-unload callback. Defer until
+  // all beforeunload listeners finish so their successful checkpoint is reset.
+  queueMicrotask(() => {
+    eventTarget.dispatchEvent(new Event(ORCA_RENDERER_UNLOAD_PREVENTED_EVENT))
+  })
+}
diff --git a/src/renderer/src/lib/workspace-session-host-persistence.test.ts b/src/renderer/src/lib/workspace-session-host-persistence.test.ts
index 6c6db493341..e44ffa76130 100644
--- a/src/renderer/src/lib/workspace-session-host-persistence.test.ts
+++ b/src/renderer/src/lib/workspace-session-host-persistence.test.ts
@@ -4,10 +4,13 @@ import type { WorkspaceSessionState } from '../../../shared/types'
 import { folderWorkspaceKey, worktreeWorkspaceKey } from '../../../shared/workspace-scope'
 import {
   buildHostIdByWorktreeId,
+  buildWorkspaceSessionHostSnapshots,
   fetchWorkspaceSessionFromHosts,
   fetchWorkspaceSessionWithRuntimeHostOwners,
   patchWorkspaceSessionByHost,
-  persistWorkspaceSessionByHost
+  persistWorkspaceSessionByHost,
+  persistWorkspaceSessionByHostSync,
+  type HostPersistenceState
 } from './workspace-session-host-persistence'
 
 describe('fetchWorkspaceSessionFromHosts', () => {
@@ -384,6 +387,55 @@ describe('fetchWorkspaceSessionFromHosts', () => {
 
     expect(owner(worktreeWorkspaceKey(worktreeId))).toBe('runtime:env-1')
   })
+
+  it('builds local-first host snapshots reused by synchronous persistence', () => {
+    const localWorktreeId = 'local-repo::C:\\src\\local'
+    const remoteWorktreeId = 'remote-repo::/srv/remote'
+    const makeTab = (id: string, worktreeId: string) => ({
+      id,
+      ptyId: null,
+      worktreeId,
+      title: id,
+      customTitle: null,
+      color: null,
+      sortOrder: 0,
+      createdAt: 1
+    })
+    const payload: WorkspaceSessionState = {
+      ...getDefaultWorkspaceSession(),
+      tabsByWorktree: {
+        [localWorktreeId]: [makeTab('local-tab', localWorktreeId)],
+        [remoteWorktreeId]: [makeTab('remote-tab', remoteWorktreeId)]
+      }
+    }
+    const state = {
+      repos: [
+        { id: 'local-repo', connectionId: null, executionHostId: 'local' },
+        { id: 'remote-repo', connectionId: null, executionHostId: 'runtime:env-1' }
+      ],
+      worktreesByRepo: {
+        'local-repo': [{ id: localWorktreeId, repoId: 'local-repo' }],
+        'remote-repo': [{ id: remoteWorktreeId, repoId: 'remote-repo', hostId: 'runtime:env-1' }]
+      }
+    } satisfies HostPersistenceState
+
+    const snapshots = buildWorkspaceSessionHostSnapshots(payload, state)
+
+    expect(snapshots.map((snapshot) => snapshot.hostId)).toEqual([undefined, 'runtime:env-1'])
+    expect(snapshots[0].state.tabsByWorktree).toEqual({
+      [localWorktreeId]: [expect.objectContaining({ id: 'local-tab' })]
+    })
+    expect(snapshots[1].state.tabsByWorktree).toEqual({
+      [remoteWorktreeId]: [expect.objectContaining({ id: 'remote-tab' })]
+    })
+
+    const setSync = vi.fn()
+    persistWorkspaceSessionByHostSync({ get: vi.fn(), patch: vi.fn(), setSync }, payload, state)
+
+    expect(setSync.mock.calls).toEqual(
+      snapshots.map((snapshot) => [snapshot.state, snapshot.hostId])
+    )
+  })
 })
 
 describe('persistWorkspaceSessionByHost', () => {
diff --git a/src/renderer/src/lib/workspace-session-host-persistence.ts b/src/renderer/src/lib/workspace-session-host-persistence.ts
index ab7b04c2fed..767db0cf991 100644
--- a/src/renderer/src/lib/workspace-session-host-persistence.ts
+++ b/src/renderer/src/lib/workspace-session-host-persistence.ts
@@ -43,6 +43,11 @@ export type WorkspaceSessionHostRead = {
   runtimeHostIdByWorkspaceSessionKey: Record<string, ExecutionHostId>
 }
 
+export type WorkspaceSessionHostSnapshot = {
+  state: WorkspaceSessionState
+  hostId?: ExecutionHostId
+}
+
 const WORKSPACE_SESSION_KEYED_FIELDS = [
   'tabsByWorktree',
   'openFilesByWorktree',
@@ -245,16 +250,26 @@ export async function persistWorkspaceSessionByHost(
   await api.flush()
 }
 
+/** Build local-first full-session snapshots for the beforeunload / quit paths. */
+export function buildWorkspaceSessionHostSnapshots(
+  payload: WorkspaceSessionState,
+  state: HostPersistenceState
+): WorkspaceSessionHostSnapshot[] {
+  const slices = splitWorkspaceSessionByHost(payload, buildHostIdByWorktreeId(state))
+  return [
+    { state: slices[LOCAL_EXECUTION_HOST_ID] ?? payload },
+    ...nonLocalEntries(slices).map(([hostId, hostState]) => ({ state: hostState, hostId }))
+  ]
+}
+
 /** Synchronous full-session split for the beforeunload / quit paths. */
 export function persistWorkspaceSessionByHostSync(
   api: SessionApi,
   payload: WorkspaceSessionState,
   state: HostPersistenceState
 ): void {
-  const slices = splitWorkspaceSessionByHost(payload, buildHostIdByWorktreeId(state))
-  api.setSync(slices[LOCAL_EXECUTION_HOST_ID] ?? payload)
-  for (const [hostId, slice] of nonLocalEntries(slices)) {
-    api.setSync(slice, hostId)
+  for (const snapshot of buildWorkspaceSessionHostSnapshots(payload, state)) {
+    api.setSync(snapshot.state, snapshot.hostId)
   }
 }
 
diff --git a/src/renderer/src/store/slices/ui.ts b/src/renderer/src/store/slices/ui.ts
index 4be3cc90b3c..713c204669d 100644
--- a/src/renderer/src/store/slices/ui.ts
+++ b/src/renderer/src/store/slices/ui.ts
@@ -35,6 +35,7 @@ import {
   applyManualRepoOrder,
   normalizeManualRepoOrder
 } from '../../../../shared/manual-repo-order'
+import { isTopLevelView } from '../../../../shared/top-level-view'
 import type { UsagePercentageDisplay } from '../../../../shared/usage-percentage-display'
 import {
   DEFAULT_USAGE_PERCENTAGE_DISPLAY,
@@ -503,26 +504,13 @@ function hydratedUIPartialMatchesState(state: AppState, hydrated: Partial<UISlic
   )
 }
 
-// Record keys are exhaustive over TopLevelView, so a new view can't be silently missed.
-const TOP_LEVEL_VIEW_LOOKUP: Record<TopLevelView, true> = {
-  terminal: true,
-  settings: true,
-  tasks: true,
-  activity: true,
-  automations: true,
-  space: true,
-  skills: true,
-  mobile: true
-}
-const KNOWN_TOP_LEVEL_VIEWS = new Set<string>(Object.keys(TOP_LEVEL_VIEW_LOOKUP))
-
 function sanitizeHydratedActiveView(
   value: PersistedUIState['activeView'],
   experimentalActivityEnabled: boolean
 ): TopLevelView {
   // Why: older data (pre-activeView) or a view a different build doesn't have
   // falls back to terminal rather than rendering nothing.
-  if (typeof value !== 'string' || !KNOWN_TOP_LEVEL_VIEWS.has(value)) {
+  if (!isTopLevelView(value)) {
     return 'terminal'
   }
   // Why: activity is hidden when its setting is off, so restoring it lands on a
@@ -531,7 +519,7 @@ function sanitizeHydratedActiveView(
   if (value === 'activity' && !experimentalActivityEnabled) {
     return 'terminal'
   }
-  return value as TopLevelView
+  return value
 }
 
 let agentSendTargetModeInstanceCounter = 0
diff --git a/src/renderer/src/web/web-preload-api.test.ts b/src/renderer/src/web/web-preload-api.test.ts
index bb95dcad904..68cf1f1000b 100644
--- a/src/renderer/src/web/web-preload-api.test.ts
+++ b/src/renderer/src/web/web-preload-api.test.ts
@@ -140,6 +140,41 @@ function installClipboardImageBase64(contentBase64: string): void {
   })
 }
 
+describe('web before-unload persistence', () => {
+  beforeEach(() => {
+    vi.resetModules()
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('persists final UI and host-partitioned sessions synchronously', async () => {
+    const { api, storage } = await installApi('Linux')
+
+    api.app.persistBeforeUnloadSync({
+      sessions: [
+        { state: { activeWorktreeId: 'local-worktree' } as never },
+        {
+          state: { activeWorktreeId: 'remote-worktree' } as never,
+          hostId: 'runtime:web-env-1'
+        }
+      ],
+      ui: { activeView: 'settings' }
+    })
+
+    expect(JSON.parse(storage.getItem('orca.web.workspaceSession.v1') ?? '{}')).toMatchObject({
+      activeWorktreeId: 'local-worktree'
+    })
+    expect(
+      JSON.parse(storage.getItem('orca.web.workspaceSession.v1.runtime:web-env-1') ?? '{}')
+    ).toMatchObject({ activeWorktreeId: 'remote-worktree' })
+    expect(JSON.parse(storage.getItem('orca.web.ui.v1') ?? '{}')).toMatchObject({
+      activeView: 'settings'
+    })
+  })
+})
+
 function installClipboardImageBlob(blob: Blob): {
   getType: ReturnType<typeof vi.fn>
   read: ReturnType<typeof vi.fn>
diff --git a/src/renderer/src/web/web-preload-api.ts b/src/renderer/src/web/web-preload-api.ts
index 41fb9833684..b899324a48f 100644
--- a/src/renderer/src/web/web-preload-api.ts
+++ b/src/renderer/src/web/web-preload-api.ts
@@ -495,6 +495,14 @@ function createWebPreloadApi(): Partial<PreloadApi> {
       relaunch: () => Promise.resolve(window.location.reload()),
       restart: () => Promise.resolve(window.location.reload()),
       reload: () => Promise.resolve(window.location.reload()),
+      persistBeforeUnloadSync: ({ sessions, ui }) => {
+        // Why: beforeunload cannot await the paired runtime, so the web adapter
+        // guarantees immediate browser-local durability for the final snapshot.
+        for (const { state, hostId } of sessions) {
+          writeJson(sessionStorageKeyForHost(hostId), sanitizeWebRuntimeWorkspaceSession(state))
+        }
+        writeJson(UI_STORAGE_KEY, mergeWebUIState(readLocalWebUIState(), ui))
+      },
       awaitFirstWindowStartupServices: () => Promise.resolve(),
       startupDiagnostic: () => Promise.resolve(),
       getKeyboardInputSourceId: () => Promise.resolve(null),
diff --git a/src/shared/renderer-shutdown-events.ts b/src/shared/renderer-shutdown-events.ts
new file mode 100644
index 00000000000..6d679e33bdb
--- /dev/null
+++ b/src/shared/renderer-shutdown-events.ts
@@ -0,0 +1 @@
+export const ORCA_RENDERER_UNLOAD_PREVENTED_EVENT = 'orca:renderer-unload-prevented'
diff --git a/src/shared/top-level-view.ts b/src/shared/top-level-view.ts
new file mode 100644
index 00000000000..574d644758c
--- /dev/null
+++ b/src/shared/top-level-view.ts
@@ -0,0 +1,20 @@
+import type { TopLevelView } from './types'
+
+// Record keys are exhaustive so adding a top-level view also updates every
+// persistence boundary that validates values loaded from disk or IPC.
+const TOP_LEVEL_VIEW_LOOKUP: Record<TopLevelView, true> = {
+  terminal: true,
+  settings: true,
+  tasks: true,
+  activity: true,
+  automations: true,
+  space: true,
+  skills: true,
+  mobile: true
+}
+
+export function isTopLevelView(value: unknown): value is TopLevelView {
+  // Why: hasOwn (not `in`) so inherited keys like "constructor"/"__proto__" from a
+  // corrupt sidecar can't pass as a view and leave the main surface blank.
+  return typeof value === 'string' && Object.hasOwn(TOP_LEVEL_VIEW_LOOKUP, value)
+}
diff --git a/tests/e2e/active-view-restart-restore.spec.ts b/tests/e2e/active-view-restart-restore.spec.ts
index 093e5774d76..28b64ce8048 100644
--- a/tests/e2e/active-view-restart-restore.spec.ts
+++ b/tests/e2e/active-view-restart-restore.spec.ts
@@ -3,11 +3,11 @@
  *
  * Reproduces the reported bug (renderer reload / relaunch always snapped back
  * to the terminal, discarding whichever top-level view — Tasks, Automations,
- * etc. — the user had open) and asserts the fix: activeView now rides the
- * PersistedUIState pipeline and is restored on the first (startup) hydration.
+ * etc. — the user had open) and asserts the fix: activeView now rides its
+ * profile preference pipeline and is restored on the first startup hydration.
  *
  * Restart-persistence lives in E2E, not a store unit test: it needs the real
- * write -> orca-data.json -> ui.get() -> hydratePersistedUI round-trip across
+ * write -> active-view.json -> ui.get() -> hydratePersistedUI round-trip across
  * two Electron launches sharing one userDataDir, then the render layer proving
  * the page actually came back — with a real repo/worktree attached so the
  * relaunch also exercises the startup worktree hydration path (which must not
@@ -15,7 +15,7 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs'
-import type { ElectronApplication, Page } from '@stablyai/playwright-test'
+import type { ElectronApplication } from '@stablyai/playwright-test'
 import { test, expect } from './helpers/orca-app'
 import { getStoreState, waitForSessionReady } from './helpers/store'
 import { attachRepoAndOpenTerminal, createRestartSession } from './helpers/orca-restart'
@@ -29,10 +29,6 @@ function seededRepoPathOrSkip(): string {
   return repoPath
 }
 
-async function readPersistedActiveView(page: Page): Promise<string | undefined> {
-  return page.evaluate(() => window.api.ui.get().then((ui) => ui.activeView))
-}
-
 test('restores the active top-level view (Tasks) after an app restart', async (// oxlint-disable-next-line no-empty-pattern -- Playwright's second fixture arg is testInfo; the first must be an object destructure to opt out of the default fixture set.
 {}, testInfo) => {
   test.setTimeout(300_000)
@@ -72,12 +68,8 @@ test('restores the active top-level view (Tasks) after an app restart', async (/
     // And the terminal grid is not the active surface.
     await expect(first.page.locator('.xterm')).not.toBeVisible({ timeout: 10_000 })
 
-    // The debounced writer must flush the view to the main-process UI state
-    // before we quit, so the relaunch reads it back from disk.
-    await expect
-      .poll(async () => readPersistedActiveView(first.page), { timeout: 10_000 })
-      .toBe('tasks')
-
+    // Closing also exercises the synchronous checkpoint that covers the race
+    // where exit starts before the tiny asynchronous preference write finishes.
     await session.close(firstApp)
     firstApp = null
 

From 24cfb97d394ede5805c186571301db2ceec9ea76 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Mon, 20 Jul 2026 01:06:46 -0700
Subject: [PATCH 44/54] fix(readme): stop star/license badges showing 429 from
 badgen

badgen.net rate-limits against GitHub and paints "429" into the badge.
Switch stars to shields.io (repo stargazers_count), use a static MIT
license badge, and drop /stargazers links which now 404 for the public
after GitHub's July 2026 stargazer access restrictions.
---
 README.md                   | 4 ++--
 docs/readme/README.es.md    | 4 ++--
 docs/readme/README.ja.md    | 4 ++--
 docs/readme/README.ko.md    | 4 ++--
 docs/readme/README.pt.md    | 4 ++--
 docs/readme/README.zh-CN.md | 4 ++--
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 24e7126c783..7d2c24f403d 100644
--- a/README.md
+++ b/README.md
@@ -3,9 +3,9 @@
 </h1>
 
 <p align="center">
-  <a href="https://github.com/stablyai/orca/stargazers"><img src="https://badgen.net/github/stars/stablyai/orca?label=%E2%98%85" alt="GitHub stars" /></a>
+  <a href="https://github.com/stablyai/orca"><img src="https://img.shields.io/github/stars/stablyai/orca?style=flat&amp;label=%E2%98%85&amp;color=08C" alt="GitHub stars" /></a>
   <a href="https://github.com/stablyai/orca/releases"><img src="docs/assets/readme-downloads.svg" alt="Total downloads across all releases" /></a>
-  <img src="https://badgen.net/github/license/stablyai/orca" alt="License" />
+  <img src="https://img.shields.io/badge/license-MIT-08C?style=flat" alt="License: MIT" />
   <a href="https://discord.gg/fzjDKHxv8Q"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Join the Orca Discord" /></a>
   <a href="https://x.com/orca_build"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="Follow Orca on X" /></a>
   <img src="https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-4493F8?style=flat-square" alt="Supported platforms: macOS, Windows, and Linux" />
diff --git a/docs/readme/README.es.md b/docs/readme/README.es.md
index 5e6638196da..22d34b33541 100644
--- a/docs/readme/README.es.md
+++ b/docs/readme/README.es.md
@@ -3,9 +3,9 @@
 </h1>
 
 <p align="center">
-  <a href="https://github.com/stablyai/orca/stargazers"><img src="https://badgen.net/github/stars/stablyai/orca?label=%E2%98%85" alt="Estrellas en GitHub" /></a>
+  <a href="https://github.com/stablyai/orca"><img src="https://img.shields.io/github/stars/stablyai/orca?style=flat&amp;label=%E2%98%85&amp;color=08C" alt="Estrellas en GitHub" /></a>
   <a href="https://github.com/stablyai/orca/releases"><img src="../assets/readme-downloads.svg" alt="Descargas totales en todas las versiones" /></a>
-  <img src="https://badgen.net/github/license/stablyai/orca" alt="Licencia" />
+  <img src="https://img.shields.io/badge/license-MIT-08C?style=flat" alt="Licencia: MIT" />
   <a href="https://discord.gg/fzjDKHxv8Q"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Únete al Discord de Orca" /></a>
   <a href="https://x.com/orca_build"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="Sigue a Orca en X" /></a>
   <img src="https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-4493F8?style=flat-square" alt="Plataformas compatibles: macOS, Windows y Linux" />
diff --git a/docs/readme/README.ja.md b/docs/readme/README.ja.md
index e2516f34d12..729697512f9 100644
--- a/docs/readme/README.ja.md
+++ b/docs/readme/README.ja.md
@@ -3,9 +3,9 @@
 </h1>
 
 <p align="center">
-  <a href="https://github.com/stablyai/orca/stargazers"><img src="https://badgen.net/github/stars/stablyai/orca?label=%E2%98%85" alt="GitHub スター数" /></a>
+  <a href="https://github.com/stablyai/orca"><img src="https://img.shields.io/github/stars/stablyai/orca?style=flat&amp;label=%E2%98%85&amp;color=08C" alt="GitHub スター数" /></a>
   <a href="https://github.com/stablyai/orca/releases"><img src="../assets/readme-downloads.svg" alt="全リリースの合計ダウンロード数" /></a>
-  <img src="https://badgen.net/github/license/stablyai/orca" alt="ライセンス" />
+  <img src="https://img.shields.io/badge/license-MIT-08C?style=flat" alt="ライセンス: MIT" />
   <a href="https://discord.gg/fzjDKHxv8Q"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Orca の Discord に参加" /></a>
   <a href="https://x.com/orca_build"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="X で Orca をフォロー" /></a>
   <img src="https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-4493F8?style=flat-square" alt="対応プラットフォーム: macOS、Windows、Linux" />
diff --git a/docs/readme/README.ko.md b/docs/readme/README.ko.md
index c03089e9091..6836bfaab81 100644
--- a/docs/readme/README.ko.md
+++ b/docs/readme/README.ko.md
@@ -3,9 +3,9 @@
 </h1>
 
 <p align="center">
-  <a href="https://github.com/stablyai/orca/stargazers"><img src="https://badgen.net/github/stars/stablyai/orca?label=%E2%98%85" alt="GitHub 스타" /></a>
+  <a href="https://github.com/stablyai/orca"><img src="https://img.shields.io/github/stars/stablyai/orca?style=flat&amp;label=%E2%98%85&amp;color=08C" alt="GitHub 스타" /></a>
   <a href="https://github.com/stablyai/orca/releases"><img src="../assets/readme-downloads.svg" alt="전체 릴리스 누적 다운로드 수" /></a>
-  <img src="https://badgen.net/github/license/stablyai/orca" alt="라이선스" />
+  <img src="https://img.shields.io/badge/license-MIT-08C?style=flat" alt="라이선스: MIT" />
   <a href="https://discord.gg/fzjDKHxv8Q"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Orca Discord 참여" /></a>
   <a href="https://x.com/orca_build"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="X에서 Orca 팔로우" /></a>
   <img src="https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-4493F8?style=flat-square" alt="지원 플랫폼: macOS, Windows, Linux" />
diff --git a/docs/readme/README.pt.md b/docs/readme/README.pt.md
index 3f61245ff8c..e09f7a1eec7 100644
--- a/docs/readme/README.pt.md
+++ b/docs/readme/README.pt.md
@@ -3,9 +3,9 @@
 </h1>
 
 <p align="center">
-  <a href="https://github.com/stablyai/orca/stargazers"><img src="https://badgen.net/github/stars/stablyai/orca?label=%E2%98%85" alt="Estrelas no GitHub" /></a>
+  <a href="https://github.com/stablyai/orca"><img src="https://img.shields.io/github/stars/stablyai/orca?style=flat&amp;label=%E2%98%85&amp;color=08C" alt="Estrelas no GitHub" /></a>
   <a href="https://github.com/stablyai/orca/releases"><img src="../assets/readme-downloads.svg" alt="Total de downloads em todas as versões" /></a>
-  <img src="https://badgen.net/github/license/stablyai/orca" alt="Licença" />
+  <img src="https://img.shields.io/badge/license-MIT-08C?style=flat" alt="Licença: MIT" />
   <a href="https://discord.gg/fzjDKHxv8Q"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Entre no Discord do Orca" /></a>
   <a href="https://x.com/orca_build"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="Siga o Orca no X" /></a>
   <img src="https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-4493F8?style=flat-square" alt="Plataformas compatíveis: macOS, Windows e Linux" />
diff --git a/docs/readme/README.zh-CN.md b/docs/readme/README.zh-CN.md
index c2323d8ebf2..6b7eb433cd1 100644
--- a/docs/readme/README.zh-CN.md
+++ b/docs/readme/README.zh-CN.md
@@ -3,9 +3,9 @@
 </h1>
 
 <p align="center">
-  <a href="https://github.com/stablyai/orca/stargazers"><img src="https://badgen.net/github/stars/stablyai/orca?label=%E2%98%85" alt="GitHub Star 数" /></a>
+  <a href="https://github.com/stablyai/orca"><img src="https://img.shields.io/github/stars/stablyai/orca?style=flat&amp;label=%E2%98%85&amp;color=08C" alt="GitHub Star 数" /></a>
   <a href="https://github.com/stablyai/orca/releases"><img src="../assets/readme-downloads.svg" alt="所有版本的总下载量" /></a>
-  <img src="https://badgen.net/github/license/stablyai/orca" alt="许可证" />
+  <img src="https://img.shields.io/badge/license-MIT-08C?style=flat" alt="许可证: MIT" />
   <a href="https://discord.gg/fzjDKHxv8Q"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="加入 Orca Discord" /></a>
   <a href="https://x.com/orca_build"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="在 X 上关注 Orca" /></a>
   <img src="https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-4493F8?style=flat-square" alt="支持的平台：macOS、Windows 和 Linux" />

From c240271c72a8376ce51b05361d66bdc4e68a65ab Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Mon, 20 Jul 2026 01:18:47 -0700
Subject: [PATCH 45/54] docs(readme): add French translation and reorder
 language links

Add a native French README and put Chinese, Japanese, and Korean first in the language switcher.
---
 README.md                   |   2 +-
 docs/readme/README.es.md    |   2 +-
 docs/readme/README.fr.md    | 274 ++++++++++++++++++++++++++++++++++++
 docs/readme/README.ja.md    |   2 +-
 docs/readme/README.ko.md    |   2 +-
 docs/readme/README.pt.md    |   2 +-
 docs/readme/README.zh-CN.md |   2 +-
 7 files changed, 280 insertions(+), 6 deletions(-)
 create mode 100644 docs/readme/README.fr.md

diff --git a/README.md b/README.md
index 7d2c24f403d..f640b09612d 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@
 </p>
 
 <p align="center">
-  <sub><a href="docs/readme/README.es.md">Español</a> · <a href="docs/readme/README.pt.md">Português</a> · <a href="docs/readme/README.zh-CN.md">中文</a> · <a href="docs/readme/README.ja.md">日本語</a> · <a href="docs/readme/README.ko.md">한국어</a></sub>
+  <sub><a href="docs/readme/README.zh-CN.md">中文</a> · <a href="docs/readme/README.ja.md">日本語</a> · <a href="docs/readme/README.ko.md">한국어</a> · <a href="docs/readme/README.es.md">Español</a> · <a href="docs/readme/README.fr.md">Français</a> · <a href="docs/readme/README.pt.md">Português</a></sub>
 </p>
 
 <p align="center">
diff --git a/docs/readme/README.es.md b/docs/readme/README.es.md
index 22d34b33541..e29c91a7972 100644
--- a/docs/readme/README.es.md
+++ b/docs/readme/README.es.md
@@ -12,7 +12,7 @@
 </p>
 
 <p align="center">
-  <sub><a href="../../README.md">English</a> · <a href="README.pt.md">Português</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a></sub>
+  <sub><a href="../../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.fr.md">Français</a> · <a href="README.pt.md">Português</a></sub>
 </p>
 
 <p align="center">
diff --git a/docs/readme/README.fr.md b/docs/readme/README.fr.md
new file mode 100644
index 00000000000..a6e4e50b773
--- /dev/null
+++ b/docs/readme/README.fr.md
@@ -0,0 +1,274 @@
+<h1 align="center">
+  <a href="https://onOrca.dev"><img src="../../resources/build/icon.png" alt="Orca" width="64" valign="middle" /></a> Orca
+</h1>
+
+<p align="center">
+  <a href="https://github.com/stablyai/orca/stargazers"><img src="https://badgen.net/github/stars/stablyai/orca?label=%E2%98%85" alt="Étoiles GitHub" /></a>
+  <a href="https://github.com/stablyai/orca/releases"><img src="../assets/readme-downloads.svg" alt="Téléchargements totaux sur toutes les versions" /></a>
+  <img src="https://badgen.net/github/license/stablyai/orca" alt="Licence" />
+  <a href="https://discord.gg/fzjDKHxv8Q"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Rejoindre le Discord Orca" /></a>
+  <a href="https://x.com/orca_build"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="Suivre Orca sur X" /></a>
+  <img src="https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-4493F8?style=flat-square" alt="Plateformes prises en charge : macOS, Windows et Linux" />
+</p>
+
+<p align="center">
+  <sub><a href="../../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.es.md">Español</a> · <a href="README.pt.md">Português</a></sub>
+</p>
+
+<p align="center">
+  <strong>L'orchestrateur d'IA pour les builders 100x.</strong><br/>
+  Lancez Codex, Claude Code, OpenCode ou Pi côte à côte — chacun dans son propre worktree, le tout suivi au même endroit.
+</p>
+
+<h3 align="center"><a href="https://onorca.dev/download"><ins>Télécharger Orca</ins></a></h3>
+
+<p align="center">
+  <sub>Sous Windows ? Prenez la <a href="https://github.com/stablyai/orca/releases#release-v1.4.147-rc.3">dernière RC</a> — elle inclut des correctifs Windows.</sub>
+</p>
+
+<p align="center">
+  <img src="../assets/readme-hero.jpg" alt="Application de bureau Orca exécutant des agents dans des worktrees parallèles, avec l'app companion mobile Orca dans le coin" width="960" />
+</p>
+
+## Fonctionnalités
+
+<table>
+<tr>
+<td width="50%" valign="middle">
+
+### Companion mobile
+
+Surveillez et pilotez vos agents depuis votre téléphone — soyez notifié quand un agent termine, et envoyez des instructions de suivi où que vous soyez.
+
+[App Store iOS](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [APK Android 0.0.31](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.31/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
+
+</td>
+<td width="50%">
+  <a href="https://www.onorca.dev/docs/mobile"><picture><source srcset="../assets/feature-wall/mobile-companion-app-showcase.gif" type="image/gif"><img src="../assets/feature-wall/mobile-companion-app-showcase.jpg" alt="Orca desktop avec l'app companion mobile" width="100%" /></picture></a>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Worktrees parallèles
+
+Lancez un même prompt sur cinq agents, chacun dans son propre worktree git isolé — comparez les résultats et mergez le gagnant.
+
+[Docs →](https://www.onorca.dev/docs/model/worktrees)
+
+</td>
+<td width="50%">
+  <a href="https://www.onorca.dev/docs/model/worktrees"><picture><source srcset="../assets/feature-wall/parallel-worktrees.gif" type="image/gif"><img src="../assets/feature-wall/parallel-worktrees.jpg" alt="Orchestration de worktrees parallèles" width="100%" /></picture></a>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Splits de terminal
+
+Terminaux de niveau Ghostty avec rendu WebGL, splits infinis et un scrollback qui survit aux redémarrages.
+
+[Docs →](https://www.onorca.dev/docs/terminal)
+
+</td>
+<td width="50%">
+  <a href="https://www.onorca.dev/docs/terminal"><picture><source srcset="../assets/feature-wall/terminal-splits.gif" type="image/gif"><img src="../assets/feature-wall/terminal-splits.jpg" alt="Splits de terminal" width="100%" /></picture></a>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Mode Design
+
+Cliquez sur n'importe quel élément d'UI dans une vraie fenêtre Chromium pour envoyer son HTML, son CSS et une capture recadrée directement dans le prompt de votre agent.
+
+[Docs →](https://www.onorca.dev/docs/browser/design-mode)
+
+</td>
+<td width="50%">
+  <a href="https://www.onorca.dev/docs/browser/design-mode"><picture><source srcset="../assets/feature-wall/design-mode.gif" type="image/gif"><img src="../assets/feature-wall/design-mode.jpg" alt="Navigateur intégré et Mode Design" width="100%" /></picture></a>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### GitHub &amp; Linear, natifs
+
+Parcourez PRs, issues et boards de projet dans l'app — ouvrez un worktree depuis n'importe quelle tâche et reviewz sans changer de contexte.
+
+[Docs →](https://www.onorca.dev/docs/review/linear)
+
+</td>
+<td width="50%">
+  <a href="https://www.onorca.dev/docs/review/linear"><picture><source srcset="../assets/feature-wall/github-linear.gif" type="image/gif"><img src="../assets/feature-wall/github-linear.jpg" alt="Workflows GitHub et Linear dans Orca" width="100%" /></picture></a>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Worktrees SSH
+
+Faites tourner des agents sur une machine distante costaude, avec édition de fichiers, git et terminaux complets — reconnexion auto et port forwarding inclus.
+
+[Docs →](https://www.onorca.dev/docs/ssh)
+
+</td>
+<td width="50%">
+  <a href="https://www.onorca.dev/docs/ssh"><picture><source srcset="../assets/feature-wall/ssh-worktrees.gif" type="image/gif"><img src="../assets/feature-wall/ssh-worktrees.jpg" alt="Worktrees distants via SSH" width="100%" /></picture></a>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Annoter les diffs IA
+
+Posez des commentaires sur n'importe quelle ligne de diff et renvoyez-les à l'agent — review, édition et commit sans quitter Orca.
+
+[Docs →](https://www.onorca.dev/docs/review/annotate-ai-diff)
+
+</td>
+<td width="50%">
+  <a href="https://www.onorca.dev/docs/review/annotate-ai-diff"><picture><source srcset="../assets/feature-wall/annotate-diff.gif" type="image/gif"><img src="../assets/feature-wall/annotate-diff.jpg" alt="Annoter les diffs générés par l'IA" width="100%" /></picture></a>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Glisser-déposer vers les agents
+
+L'éditeur VS Code avec autosave partout — glissez fichiers ou images directement dans le prompt d'un agent.
+
+[Docs →](https://www.onorca.dev/docs/editing/file-explorer)
+
+</td>
+<td width="50%">
+  <a href="https://www.onorca.dev/docs/editing/file-explorer"><picture><source srcset="../assets/feature-wall/file-drag.gif" type="image/gif"><img src="../assets/feature-wall/file-drag.jpg" alt="Glisser des fichiers et images dans le prompt d'un agent" width="100%" /></picture></a>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Orca CLI
+
+Les agents pilotent aussi Orca — scriptez n'importe quel workflow avec `orca worktree create`, `snapshot`, `click` et `fill`.
+
+[Docs →](https://www.onorca.dev/docs/cli/overview)
+
+</td>
+<td width="50%">
+  <a href="https://www.onorca.dev/docs/cli/overview"><picture><source srcset="../assets/feature-wall/orca-cli.gif" type="image/gif"><img src="../assets/feature-wall/orca-cli.jpg" alt="Scripter Orca depuis la CLI" width="100%" /></picture></a>
+</td>
+</tr>
+</table>
+
+**Aussi dans la boîte :**
+
+- **[Quick open](https://www.onorca.dev/docs/model/quick-open)** — Cherchez parmi worktrees, fichiers, agents, commandes et contexte du repo sans quitter votre flow.
+- **[Sélecteur de comptes &amp; suivi d'usage](https://www.onorca.dev/docs/agents/usage-tracking)** — Suivez l'usage Claude et Codex et les resets de rate limit, et basculez de compte à chaud sans vous reconnecter.
+- **[Aperçus riches du repo](https://www.onorca.dev/docs/editing/markdown)** — Prévisualisez Markdown, images, PDF et docs du repo dans le workspace.
+- **[Computer Use](https://www.onorca.dev/docs/cli/computer-use)** — Laissez les agents piloter des apps desktop et l'UI visible quand un workflow demande une vraie interaction.
+- **[Notifications et non-lus](https://www.onorca.dev/docs/notifications)** — Sachez quand un agent termine ou a besoin d'attention, puis marquez des fils comme non lus pour y revenir plus tard.
+- **Et bien plus encore** — on ship tous les jours, donc cette liste est toujours en retard. Le [changelog](https://github.com/stablyai/orca/releases) est la vraie liste des features.
+
+---
+
+## Agents pris en charge
+
+Fonctionne avec **n'importe quel agent CLI** — s'il tourne dans un terminal, il tourne dans Orca.
+
+<p>
+  <a href="https://docs.anthropic.com/claude/docs/claude-code"><kbd><img src="../assets/claude-logo.svg" alt="Logo Claude Code" width="16" valign="middle" /> Claude Code</kbd></a> &nbsp;
+  <a href="https://github.com/openai/codex"><kbd><img src="https://www.google.com/s2/favicons?domain=openai.com&sz=64" alt="Logo Codex" width="16" valign="middle" /> Codex</kbd></a> &nbsp;
+  <a href="https://x.ai/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=x.ai&sz=64" alt="Logo Grok" width="16" valign="middle" /> Grok</kbd></a> &nbsp;
+  <a href="https://cursor.com/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=cursor.com&sz=64" alt="Logo Cursor" width="16" valign="middle" /> Cursor</kbd></a> &nbsp;
+  <a href="https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli"><kbd><img src="https://www.google.com/s2/favicons?domain=github.com&sz=64" alt="Logo GitHub Copilot" width="16" valign="middle" /> GitHub Copilot</kbd></a> &nbsp;
+  <a href="https://opencode.ai/docs/cli/"><kbd><img src="https://www.google.com/s2/favicons?domain=opencode.ai&sz=64" alt="Logo OpenCode" width="16" valign="middle" /> OpenCode</kbd></a> &nbsp;
+  <a href="https://mimo.xiaomi.com/coder"><kbd><img src="https://www.google.com/s2/favicons?domain=mimo.xiaomi.com&sz=64" alt="Logo MiMo Code" width="16" valign="middle" /> MiMo Code</kbd></a> &nbsp;
+  <a href="https://ampcode.com/manual#install"><kbd><img src="https://www.google.com/s2/favicons?domain=ampcode.com&sz=64" alt="Logo Amp" width="16" valign="middle" /> Amp</kbd></a> &nbsp;
+  <a href="https://openclaude.gitlawb.com/"><kbd><img src="../../resources/openclaude-logo.png" alt="Logo OpenClaude" width="16" valign="middle" /> OpenClaude</kbd></a> &nbsp;
+  <a href="https://antigravity.google/docs/cli-overview"><kbd><img src="https://www.google.com/s2/favicons?domain=antigravity.google&sz=64" alt="Logo Antigravity" width="16" valign="middle" /> Antigravity</kbd></a> &nbsp;
+  <a href="https://pi.dev"><kbd><img src="https://pi.dev/favicon.svg" alt="Logo Pi" width="16" valign="middle" /> Pi</kbd></a> &nbsp;
+  <a href="https://omp.sh"><kbd><img src="https://omp.sh/favicon.svg" alt="Logo oh-my-pi" width="16" valign="middle" /> oh-my-pi</kbd></a> &nbsp;
+  <a href="https://hermes-agent.nousresearch.com/docs/"><kbd><img src="https://www.google.com/s2/favicons?domain=nousresearch.com&sz=64" alt="Logo Hermes Agent" width="16" valign="middle" /> Hermes Agent</kbd></a> &nbsp;
+  <a href="https://devin.ai/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=devin.ai&sz=64" alt="Logo Devin" width="16" valign="middle" /> Devin</kbd></a> &nbsp;
+  <a href="https://block.github.io/goose/docs/quickstart/"><kbd><img src="https://www.google.com/s2/favicons?domain=goose-docs.ai&sz=64" alt="Logo Goose" width="16" valign="middle" /> Goose</kbd></a> &nbsp;
+  <a href="https://docs.augmentcode.com/cli/overview"><kbd><img src="https://www.google.com/s2/favicons?domain=augmentcode.com&sz=64" alt="Logo Auggie" width="16" valign="middle" /> Auggie</kbd></a> &nbsp;
+  <a href="https://github.com/autohandai/code-cli"><kbd><img src="https://www.google.com/s2/favicons?domain=autohand.ai&sz=64" alt="Logo Autohand Code" width="16" valign="middle" /> Autohand Code</kbd></a> &nbsp;
+  <a href="https://github.com/charmbracelet/crush"><kbd><img src="https://www.google.com/s2/favicons?domain=charm.sh&sz=64" alt="Logo Charm" width="16" valign="middle" /> Charm</kbd></a> &nbsp;
+  <a href="https://docs.cline.bot/cline-cli/overview"><kbd><img src="https://www.google.com/s2/favicons?domain=cline.bot&sz=64" alt="Logo Cline" width="16" valign="middle" /> Cline</kbd></a> &nbsp;
+  <a href="https://www.codebuff.com/docs/help/quick-start"><kbd><img src="https://www.google.com/s2/favicons?domain=codebuff.com&sz=64" alt="Logo Codebuff" width="16" valign="middle" /> Codebuff</kbd></a> &nbsp;
+  <a href="https://commandcode.ai/docs/quickstart"><kbd><img src="https://www.google.com/s2/favicons?domain=commandcode.ai&sz=64" alt="Logo Command Code" width="16" valign="middle" /> Command Code</kbd></a> &nbsp;
+  <a href="https://docs.continue.dev/guides/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=continue.dev&sz=64" alt="Logo Continue" width="16" valign="middle" /> Continue</kbd></a> &nbsp;
+  <a href="https://docs.factory.ai/cli/getting-started/quickstart"><kbd><img src="../assets/droid-logo.svg" alt="Logo Droid" width="16" valign="middle" /> Droid</kbd></a> &nbsp;
+  <a href="https://kilo.ai/docs/cli"><kbd><img src="https://raw.githubusercontent.com/Kilo-Org/kilocode/main/packages/kilo-vscode/assets/icons/kilo-light.svg" alt="Logo Kilocode" width="16" valign="middle" /> Kilocode</kbd></a> &nbsp;
+  <a href="https://www.kimi.com/code/docs/en/kimi-code-cli/getting-started.html"><kbd><img src="https://www.google.com/s2/favicons?domain=moonshot.cn&sz=64" alt="Logo Kimi" width="16" valign="middle" /> Kimi</kbd></a> &nbsp;
+  <a href="https://kiro.dev/docs/cli/"><kbd><img src="https://www.google.com/s2/favicons?domain=kiro.dev&sz=64" alt="Logo Kiro" width="16" valign="middle" /> Kiro</kbd></a> &nbsp;
+  <a href="https://github.com/mistralai/mistral-vibe"><kbd><img src="https://www.google.com/s2/favicons?domain=mistral.ai&sz=64" alt="Logo Mistral Vibe" width="16" valign="middle" /> Mistral Vibe</kbd></a> &nbsp;
+  <a href="https://github.com/QwenLM/qwen-code"><kbd><img src="https://www.google.com/s2/favicons?domain=qwenlm.github.io&sz=64" alt="Logo Qwen Code" width="16" valign="middle" /> Qwen Code</kbd></a> &nbsp;
+  <a href="https://support.atlassian.com/rovo/docs/install-and-run-rovo-dev-cli-on-your-device/"><kbd><img src="https://www.google.com/s2/favicons?domain=atlassian.com&sz=64" alt="Logo Rovo Dev" width="16" valign="middle" /> Rovo Dev</kbd></a> &nbsp;
+  <kbd>+ n'importe quel agent CLI</kbd>
+</p>
+
+---
+
+## Installation
+
+### Desktop — macOS, Windows, Linux
+
+- **[Télécharger depuis onOrca.dev](https://onorca.dev/download)**
+- Ou récupérez un build directement : [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/download/v1.4.147-rc.3/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [Tous les builds](https://github.com/stablyai/orca/releases/latest)
+- **Sous Windows :** utilisez la [dernière RC (`v1.4.147-rc.3`)](https://github.com/stablyai/orca/releases#release-v1.4.147-rc.3) — elle inclut des correctifs Windows absents de la stable.
+- Vous lancez `orca serve` sur un serveur Linux headless ? Consultez le [guide serveur Linux headless](../reference/headless-linux-server.md).
+
+_Ou via un gestionnaire de paquets :_
+
+```bash
+# macOS (Homebrew)
+brew install --cask stablyai/orca/orca
+
+# Arch Linux (AUR) — ou stably-orca-git pour compiler depuis les sources
+yay -S stably-orca-bin
+```
+
+### Companion mobile — iOS, Android
+
+Associez-la à l'app de bureau pour surveiller et piloter vos agents depuis votre téléphone.
+
+- **iOS :** [Télécharger sur l'App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) ou [rejoindre TestFlight](https://testflight.apple.com/join/YjeGMQBA)
+- **Android :** [Télécharger l'APK 0.0.31](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.31/app-release.apk)
+
+---
+
+## Communauté &amp; support
+
+- **Discord :** Rejoignez la communauté sur **[Discord](https://discord.gg/fzjDKHxv8Q)**.
+- **Twitter / X :** Suivez **[@orca_build](https://x.com/orca_build)** pour les news et annonces.
+- **WeChat :** Les groupes 1 et 2 sont complets — vous pouvez rejoindre le troisième.
+
+  <img src="../assets/wechat-qr.jpg" alt="QR code WeChat de la communauté Orca" width="160" />
+
+- **Feedback &amp; idées :** On ship vite. Il manque quelque chose ? [Demandez une feature](https://github.com/stablyai/orca/issues).
+- **Confidentialité :** Voir la [doc confidentialité &amp; télémétrie](https://www.onorca.dev/docs/telemetry) pour ce qu'Orca collecte en anonyme et comment désactiver la télémétrie.
+- **Soutenez-nous :** [Mettez une star](https://github.com/stablyai/orca) sur ce repo pour suivre nos ships quotidiens.
+
+---
+
+## Développement
+
+Envie de contribuer ou de lancer le projet en local ? Consultez notre guide [CONTRIBUTING.md](../../.github/CONTRIBUTING.md).
+
+<a href="https://github.com/stablyai/orca/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=stablyai/orca" alt="Contributeurs Orca" />
+</a>
+
+<p align="center">
+  <img src="../assets/star-history.png" alt="Graphique d'historique des étoiles GitHub pour stablyai/orca" width="880" />
+</p>
+
+## Builds signés
+
+Signature de code Windows sponsorisée / fournie par [SignPath.io](https://signpath.io), certificat par [SignPath Foundation](https://signpath.org).
+
+## Licence
+
+Orca est libre et open source sous la [licence MIT](../../LICENSE).
diff --git a/docs/readme/README.ja.md b/docs/readme/README.ja.md
index 729697512f9..6da07e51cd2 100644
--- a/docs/readme/README.ja.md
+++ b/docs/readme/README.ja.md
@@ -12,7 +12,7 @@
 </p>
 
 <p align="center">
-  <sub><a href="../../README.md">English</a> · <a href="README.es.md">Español</a> · <a href="README.pt.md">Português</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ko.md">한국어</a></sub>
+  <sub><a href="../../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ko.md">한국어</a> · <a href="README.es.md">Español</a> · <a href="README.fr.md">Français</a> · <a href="README.pt.md">Português</a></sub>
 </p>
 
 <p align="center">
diff --git a/docs/readme/README.ko.md b/docs/readme/README.ko.md
index 6836bfaab81..1194226915a 100644
--- a/docs/readme/README.ko.md
+++ b/docs/readme/README.ko.md
@@ -12,7 +12,7 @@
 </p>
 
 <p align="center">
-  <sub><a href="../../README.md">English</a> · <a href="README.es.md">Español</a> · <a href="README.pt.md">Português</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a></sub>
+  <sub><a href="../../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.es.md">Español</a> · <a href="README.fr.md">Français</a> · <a href="README.pt.md">Português</a></sub>
 </p>
 
 <p align="center">
diff --git a/docs/readme/README.pt.md b/docs/readme/README.pt.md
index e09f7a1eec7..d0d95b38b9f 100644
--- a/docs/readme/README.pt.md
+++ b/docs/readme/README.pt.md
@@ -12,7 +12,7 @@
 </p>
 
 <p align="center">
-  <sub><a href="../../README.md">English</a> · <a href="README.es.md">Español</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a></sub>
+  <sub><a href="../../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.es.md">Español</a> · <a href="README.fr.md">Français</a></sub>
 </p>
 
 <p align="center">
diff --git a/docs/readme/README.zh-CN.md b/docs/readme/README.zh-CN.md
index 6b7eb433cd1..595ca2461d1 100644
--- a/docs/readme/README.zh-CN.md
+++ b/docs/readme/README.zh-CN.md
@@ -12,7 +12,7 @@
 </p>
 
 <p align="center">
-  <sub><a href="../../README.md">English</a> · <a href="README.es.md">Español</a> · <a href="README.pt.md">Português</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a></sub>
+  <sub><a href="../../README.md">English</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.es.md">Español</a> · <a href="README.fr.md">Français</a> · <a href="README.pt.md">Português</a></sub>
 </p>
 
 <p align="center">

From f98eaeb8a29d064601e1215573bd6edac26b593d Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Mon, 20 Jul 2026 08:24:22 +0000
Subject: [PATCH 46/54] release: v1.4.147-rc.4

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index e5734083688..77b11ed0f1c 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.4.146-rc.0",
+  "version": "1.4.147-rc.4",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",

From 53aeeb710c45aa22738f891ad60ba3886163e67b Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Mon, 20 Jul 2026 01:43:22 -0700
Subject: [PATCH 47/54] docs(readme): point Windows users to v1.4.147-rc.4

Bump the Windows RC download notice and installer link to the newer RC.
---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index f640b09612d..98a1e21b4a1 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@
 <h3 align="center"><a href="https://onorca.dev/download"><ins>Download Orca</ins></a></h3>
 
 <p align="center">
-  <sub>Windows? Grab the <a href="https://github.com/stablyai/orca/releases#release-v1.4.147-rc.3">latest RC</a> — has Windows fixes.</sub>
+  <sub>Windows? Grab the <a href="https://github.com/stablyai/orca/releases#release-v1.4.147-rc.4">latest RC</a> — has Windows fixes.</sub>
 </p>
 
 <p align="center">
@@ -216,8 +216,8 @@ Works with **any CLI agent** — if it runs in a terminal, it runs in Orca.
 ### Desktop — macOS, Windows, Linux
 
 - **[Download from onOrca.dev](https://onorca.dev/download)**
-- Or grab a build directly: [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/download/v1.4.147-rc.3/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [All builds](https://github.com/stablyai/orca/releases/latest)
-- **Windows users:** use the [latest RC (`v1.4.147-rc.3`)](https://github.com/stablyai/orca/releases#release-v1.4.147-rc.3) — it includes Windows-specific bug fixes not yet in stable.
+- Or grab a build directly: [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/download/v1.4.147-rc.4/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [All builds](https://github.com/stablyai/orca/releases/latest)
+- **Windows users:** use the [latest RC (`v1.4.147-rc.4`)](https://github.com/stablyai/orca/releases#release-v1.4.147-rc.4) — it includes Windows-specific bug fixes not yet in stable.
 - Running `orca serve` on a headless Linux server? See the [headless Linux server guide](docs/reference/headless-linux-server.md).
 
 _Or via a package manager:_

From 98b00d3a64ab9b1e114c084a683972577a233ee8 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Mon, 20 Jul 2026 03:18:24 -0700
Subject: [PATCH 48/54] refactor(comments): slim verbose comments in main core
 (runtime/ipc/daemon/pty) (#9542)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Collapse multi-line explanatory comment blocks into single-line "why" statements
per AGENTS.md ("Document the Why, Briefly"): drop restatements of the code and
mechanism narration; keep the non-obvious reason, external refs, and directives.

Comments-only — verified no code changed via a Babel/esbuild comment-strip
token-equality gate against origin/main; typecheck and oxlint clean.

Area: main — core runtime, ipc, daemon, pty, providers. 73 files changed, 3206 insertions(+), 10475 deletions(-).

Co-authored-by: Orca <help@stably.ai>
---
 .../agent-hooks/first-work-branch-rename.ts   |   84 +-
 src/main/agent-hooks/installer-utils.ts       |   97 +-
 src/main/agent-hooks/server.test.ts           |  151 +--
 src/main/agent-hooks/server.ts                |  345 ++---
 src/main/daemon/daemon-host-relocation.ts     |  112 +-
 src/main/daemon/daemon-init.test.ts           |  225 +--
 src/main/daemon/daemon-init.ts                |  297 +---
 src/main/daemon/daemon-pty-adapter.test.ts    |  127 +-
 src/main/daemon/daemon-pty-adapter.ts         |  392 ++----
 src/main/daemon/daemon-server.ts              |  125 +-
 src/main/daemon/daemon-stream-data-batcher.ts |   89 +-
 .../headless-emulator-fidelity.fuzz.test.ts   |  121 +-
 src/main/daemon/headless-emulator.ts          |  148 +-
 .../hibernation-cold-restore-repro.test.ts    |   65 +-
 src/main/daemon/history-manager.ts            |   88 +-
 src/main/daemon/pty-subprocess.ts             |  223 +--
 src/main/daemon/session.ts                    |  206 +--
 src/main/daemon/shell-ready.test.ts           |   90 +-
 src/main/daemon/terminal-host.ts              |   65 +-
 src/main/hooks.ts                             |   92 +-
 src/main/index.ts                             |  555 ++------
 src/main/ipc/app.ts                           |   66 +-
 src/main/ipc/filesystem-auth.ts               |   83 +-
 src/main/ipc/filesystem-watcher.ts            |  216 +--
 src/main/ipc/filesystem.ts                    |  110 +-
 src/main/ipc/notifications.ts                 |  149 +-
 src/main/ipc/pet.ts                           |  102 +-
 src/main/ipc/pty-management.ts                |   56 +-
 src/main/ipc/pty.test.ts                      |  527 ++-----
 src/main/ipc/pty.ts                           | 1208 ++++-------------
 src/main/ipc/repos-remote.test.ts             |   67 +-
 src/main/ipc/repos.ts                         |  265 +---
 src/main/ipc/ssh-browse.ts                    |   89 +-
 src/main/ipc/ssh.ts                           |  226 +--
 src/main/ipc/telemetry.test.ts                |   83 +-
 src/main/ipc/telemetry.ts                     |  182 +--
 src/main/ipc/worktree-remote.ts               |  247 +---
 src/main/ipc/worktrees.test.ts                |   77 +-
 src/main/ipc/worktrees.ts                     |  208 +--
 src/main/memory/hydrate-local-pty-registry.ts |   95 +-
 src/main/observability/bundle.ts              |  103 +-
 src/main/observability/local-file-sink.ts     |   76 +-
 src/main/observability/redactor.ts            |  167 +--
 src/main/persistence.test.ts                  |  120 +-
 src/main/persistence.ts                       |  710 +++-------
 src/main/providers/local-pty-provider.ts      |  250 +---
 .../providers/local-pty-shell-ready.test.ts   |  127 +-
 src/main/providers/local-pty-shell-ready.ts   |   73 +-
 src/main/rate-limits/claude-fetcher.ts        |   81 +-
 src/main/rate-limits/codex-fetcher.ts         |   94 +-
 src/main/rate-limits/service.ts               |  153 +--
 src/main/runtime/mobile-presence-lock.test.ts |  102 +-
 .../mobile-subscribe-integration.test.ts      |  131 +-
 src/main/runtime/orca-runtime-browser.ts      |  156 +--
 src/main/runtime/orca-runtime-files.ts        |   96 +-
 src/main/runtime/orca-runtime.test.ts         |  458 ++-----
 src/main/runtime/orca-runtime.ts              |  610 +++------
 src/main/runtime/orchestration/coordinator.ts |  119 +-
 src/main/runtime/orchestration/db.ts          |  136 +-
 src/main/runtime/rpc/core.ts                  |   52 +-
 src/main/runtime/rpc/methods/orchestration.ts |  113 +-
 src/main/runtime/rpc/methods/terminal.ts      |  363 ++---
 src/main/runtime/rpc/ws-transport.ts          |  141 +-
 src/main/runtime/runtime-rpc.ts               |  191 +--
 src/main/startup/configure-process.ts         |   95 +-
 src/main/telemetry/burst-cap.ts               |   83 +-
 src/main/telemetry/client.ts                  |  246 +---
 .../telemetry/onboarding-cohort-classifier.ts |   55 +-
 src/main/updater-events.ts                    |   63 +-
 src/main/updater.test.ts                      |   83 +-
 src/main/updater.ts                           |  240 +---
 .../window/attach-main-window-services.ts     |   73 +-
 src/main/window/createMainWindow.ts           |  366 ++---
 73 files changed, 3205 insertions(+), 10474 deletions(-)

diff --git a/src/main/agent-hooks/first-work-branch-rename.ts b/src/main/agent-hooks/first-work-branch-rename.ts
index d669192907f..02ff623f52f 100644
--- a/src/main/agent-hooks/first-work-branch-rename.ts
+++ b/src/main/agent-hooks/first-work-branch-rename.ts
@@ -1,8 +1,4 @@
-// Why: when first-message auto-name is on, the first time an agent starts
-// working in a freshly-created workspace we replace the auto-generated creature
-// branch (e.g. `you/Nautilus`) with a short, work-derived name. This module
-// owns the orchestration: gate on the signal, enforce the safety guardrails,
-// summarize the prompt via the configured agent, and rename.
+// On first agent work in a fresh workspace, replace the auto-generated creature branch (e.g. `you/Nautilus`) with a short work-derived name.
 import type { GlobalSettings, Repo } from '../../shared/types'
 import { getRepoIdFromWorktreeId, splitWorktreeIdForFilesystem } from '../../shared/worktree-id'
 import { parseWorkspaceKey } from '../../shared/workspace-scope'
@@ -59,10 +55,7 @@ export type FirstWorkBranchRenameDeps = {
   setDisplayName: (worktreeId: string, displayName: string) => void
   /** Align the on-disk folder with the new branch leaf (best-effort, local-only). */
   renameWorktreeFolder?: (worktreeId: string, newLeaf: string) => Promise<boolean>
-  /** Record (or clear with null) a user-facing auto-rename generation failure
-   *  so the sidebar can show a "rename failed" badge instead of silent retries.
-   *  `failureOutput` carries the bounded full CLI output for local on-demand
-   *  display; omitted/null replaces any stale capture. */
+  /** Record (or clear with null) an auto-rename failure for the sidebar "rename failed" badge; `failureOutput` carries bounded CLI output for on-demand display. */
   setRenameError: (
     worktreeId: string,
     error: string | null,
@@ -74,12 +67,7 @@ export type FirstWorkBranchRenameDeps = {
   onRenamed: (repoId: string) => void
 }
 
-// Why: `inFlight` guards against concurrent runs while generation (seconds) is
-// pending; `settled` short-circuits worktrees we've reached a definitive verdict
-// on (renamed, or permanently ineligible) so we never re-probe git on later
-// `working` events — important because the hook fires every turn for every pane.
-// A *transient* failure (agent not reachable yet, brief detached HEAD) is NOT
-// settled, so the real first prompt can still succeed on a later event.
+// inFlight blocks concurrent generation; settled caches definitive verdicts (transient bails stay unsettled to retry later).
 const inFlightWorktreeIds = new Set<string>()
 const settledWorktreeIds = new Set<string>()
 export const FIRST_WORK_BRANCH_RENAME_SETTLED_CACHE_LIMIT = 500
@@ -91,8 +79,7 @@ export function resetFirstWorkBranchRenameState(): void {
 }
 
 function rememberSettledWorktreeId(worktreeId: string): void {
-  // Why: the app can see unbounded worktree ids over a long session; evicting
-  // oldest entries trades a rare re-probe for bounded process memory.
+  // Why: worktree ids are unbounded over a long session; evict oldest to bound memory (costs a rare re-probe).
   settledWorktreeIds.delete(worktreeId)
   settledWorktreeIds.add(worktreeId)
   while (settledWorktreeIds.size > FIRST_WORK_BRANCH_RENAME_SETTLED_CACHE_LIMIT) {
@@ -115,8 +102,7 @@ export async function maybeAutoRenameBranchOnFirstWork(
   if (!deps.getSettings().autoRenameBranchFromWork) {
     return
   }
-  // Resolve the worktree from the tab (authoritative) rather than the
-  // agent-echoed worktreeId, which is not present on every hook event.
+  // Resolve from the tab (authoritative); the agent-echoed worktreeId isn't present on every event.
   const tabId = parsePaneKey(event.paneKey)?.tabId ?? event.tabId
   const worktreeId = (tabId ? deps.resolveWorktreeIdForTab(tabId) : undefined) ?? event.worktreeId
   if (!worktreeId) {
@@ -132,37 +118,27 @@ export async function maybeAutoRenameBranchOnFirstWork(
   }
   inFlightWorktreeIds.add(worktreeId)
   try {
-    // `settled` true means a definitive verdict (renamed or permanently
-    // ineligible); false means a transient bail that should retry later.
+    // settled = definitive verdict (renamed/ineligible); false = transient bail to retry later.
     const settled = await runAutoRename(worktreeId, prompt, event.assistantMessage, deps)
     if (settled) {
       rememberSettledWorktreeId(worktreeId)
     }
   } catch (error) {
-    // Why: best-effort, opt-in convenience. A failure must never disrupt the
-    // agent the user actually launched, so swallow after logging.
+    // Why: best-effort convenience; a failure must never disrupt the user's agent, so swallow after logging.
     console.warn('[auto-branch-rename] rename attempt failed:', error)
   } finally {
     inFlightWorktreeIds.delete(worktreeId)
   }
 }
 
-/**
- * Returns true when a definitive verdict was reached (renamed, or permanently
- * ineligible — so stop re-probing), false for a transient bail worth retrying.
- */
+/** Returns true for a definitive verdict (renamed or permanently ineligible → stop re-probing), false for a transient bail worth retrying. */
 async function runAutoRename(
   worktreeId: string,
   prompt: string,
   assistantMessage: string | undefined,
   deps: FirstWorkBranchRenameDeps
 ): Promise<boolean> {
-  // Why: when the feature appears not to fire, the question is always "which
-  // gate bailed?" — this names the gate so a single log line answers it.
-  // `stop` = permanent (don't retry); `retry` = transient (try again later).
-  // `clearError` clears a stale "rename failed" badge when the worktree reaches
-  // a benign final state (ineligible, user-renamed, or pushed) after an earlier
-  // transient generation failure raised one — otherwise it would stick forever.
+  // `stop` = permanent skip (logs which gate bailed); `retry` = transient; `clearError` drops a stale "rename failed" badge on a benign final state.
   const stop = (reason: string, clearError = false): true => {
     if (clearError) {
       deps.setRenameError(worktreeId, null)
@@ -188,9 +164,7 @@ async function runAutoRename(
   }
 
   const repo = deps.getRepo(getRepoIdFromWorktreeId(worktreeId))
-  // Why: worktreePath is a Git subprocess cwd. Folder-workspace instance IDs
-  // carry a synthetic `::workspace:<uuid>` suffix that is not a real directory,
-  // so resolve to the backing folder or Git spawns against a nonexistent cwd.
+  // Why: folder-workspace ids carry a synthetic `::workspace:<uuid>` suffix that's not a real dir; resolve to the backing folder for Git's cwd.
   const parsed = splitWorktreeIdForFilesystem(worktreeId)
   if (!repo || !parsed) {
     return stop('unresolved repo or worktree id')
@@ -223,8 +197,7 @@ async function runAutoRename(
     return stop(`branch "${currentBranch}" already has an upstream`, true)
   }
   if (upstreamProbe.outcome === 'probe-failed') {
-    // Why: settling an unreadable probe as "has upstream" made this failure
-    // silent and permanent via the settled cache (issue #7808).
+    // Why: settling an unreadable probe as "has upstream" made this silent + permanent via the settled cache (issue #7808).
     const probeError = upstreamProbe.message.replace(/\s+/g, ' ').trim()
     deps.setRenameError(
       worktreeId,
@@ -237,8 +210,7 @@ async function runAutoRename(
   const hostKey = getCommitMessageModelDiscoveryHostKey(repo.connectionId ?? null)
   const resolvedParams = resolveTextGenerationParams(settings, hostKey, 'branchName', repo)
   if (!resolvedParams.ok) {
-    // Why: a generation-step failure (vs a benign skip) is user-actionable, so
-    // surface it on the card rather than leaving a silent "rename pending".
+    // Why: a generation-step failure (vs a benign skip) is user-actionable, so surface it on the card.
     deps.setRenameError(worktreeId, resolvedParams.error)
     return stop(`no generation agent: ${resolvedParams.error}`)
   }
@@ -256,17 +228,14 @@ async function runAutoRename(
     target
   )
   if (!generated.success) {
-    // Transient: the agent may be momentarily busy/unreachable — let a later
-    // event retry rather than permanently leaving the creature name.
-    // A user-canceled generation isn't a failure to surface, so skip the badge.
+    // Transient failure: retry on a later event; skip the badge for a user-canceled generation.
     if (!generated.canceled) {
       deps.setRenameError(worktreeId, generated.error, generated.failureOutput ?? null)
     }
     return retry(`generation failed: ${generated.error}`)
   }
 
-  // Re-validate after generation (it can take seconds): the branch must be the
-  // same unpublished creature branch we started from, or we leave it alone.
+  // Re-validate after generation (takes seconds): bail if the branch changed or was published meanwhile.
   const branchNow = (await exec(['rev-parse', '--abbrev-ref', 'HEAD'])).stdout.trim()
   if (branchNow !== currentBranch) {
     return retry(`branch changed during generation (${currentBranch} -> ${branchNow})`)
@@ -283,14 +252,12 @@ async function runAutoRename(
   const username = provider
     ? (await getSshGitUsername(provider, repo.path)) || null
     : (await resolveLocalGitUsername(repo.path)) || null
-  // The model sometimes echoes the configured prefix (e.g. `tmchow/...`); strip
-  // it so it doesn't double-prefix the branch or leak into the display name.
+  // The model sometimes echoes the configured prefix (e.g. `tmchow/...`); strip it to avoid double-prefixing.
   const slug = stripConfiguredBranchPrefix(
     generated.slug,
     getConfiguredBranchPrefix(settings, username)
   )
-  // Prefix-only model output strips to empty; renaming with it would just
-  // re-add the prefix (`tmchow/tmchow`), so treat it as a benign skip.
+  // Prefix-only output strips to empty; renaming would just re-add the prefix (`tmchow/tmchow`), so skip.
   if (!slug) {
     return stop('model produced only the configured prefix', true)
   }
@@ -301,8 +268,7 @@ async function runAutoRename(
     currentBranch
   )
   if (!newBranch || newBranch === currentBranch) {
-    // Generation succeeded but yielded no distinct name — terminal and benign,
-    // so clear any stale failure badge a prior transient attempt left behind.
+    // No distinct name is terminal and benign, so clear any stale failure badge from a prior transient attempt.
     return stop(`no distinct unique branch name for slug "${slug}"`, true)
   }
 
@@ -310,12 +276,9 @@ async function runAutoRename(
     ? provider.renameCurrentBranch(worktreePath, newBranch)
     : renameCurrentBranch(exec, newBranch))
 
-  // resolveUniqueBranchName may have appended a collision suffix (`-2`, …), so
-  // derive the sidebar name and on-disk folder from the *resolved* branch leaf,
-  // not the pre-suffix slug, to keep branch, display, and folder aligned.
+  // resolveUniqueBranchName may append a collision suffix (`-2`, …), so derive names from the resolved leaf, not the slug.
   const newBranchLeaf = newBranch.slice(newBranch.lastIndexOf('/') + 1)
-  // Keep the sidebar name in sync with the branch — but only when it is still
-  // the auto-generated creature name, so a name the user typed is left alone.
+  // Only sync the sidebar name when it's still the auto-generated creature name, so a user-typed name is left alone.
   const currentDisplayName = deps.getCurrentDisplayName(worktreeId)
   const newDisplayName = deriveWorkspaceDisplayName({ prompt, slug, resolvedLeaf: newBranchLeaf })
   const updateDisplay = !currentDisplayName || isAutoGeneratedCreatureBranchName(currentDisplayName)
@@ -326,10 +289,7 @@ async function runAutoRename(
   // A successful rename clears any stale generation-failure surfaced earlier.
   deps.setRenameError(worktreeId, null)
 
-  // Align the on-disk folder with the new branch leaf. Best-effort and local-only:
-  // a skip or failure (remote, Windows lock, dest taken) leaves the folder as-is
-  // and must never undo the branch/display rename that already landed. Runs after
-  // setDisplayName so the new display name rides along into the migrated identity.
+  // Best-effort local-only folder align, after setDisplayName so the new name rides into the migrated identity; a failure must never undo the landed rename.
   let folderRenamed = false
   if (deps.renameWorktreeFolder) {
     try {
@@ -339,9 +299,7 @@ async function runAutoRename(
     }
   }
 
-  // A successful folder rename already invalidated caches and pushed a
-  // worktrees:changed carrying the id mapping; a second onRenamed would only
-  // trigger a redundant renderer re-list. Otherwise notify for the branch rename.
+  // A folder rename already notified the renderer, so a second onRenamed would just re-list redundantly.
   if (!folderRenamed) {
     deps.onRenamed(repo.id)
   }
diff --git a/src/main/agent-hooks/installer-utils.ts b/src/main/agent-hooks/installer-utils.ts
index 893cb53d465..2c1da487a7f 100644
--- a/src/main/agent-hooks/installer-utils.ts
+++ b/src/main/agent-hooks/installer-utils.ts
@@ -38,16 +38,11 @@ export type HooksConfig = {
   [key: string]: unknown
 }
 
-// Why: host-level backstop (seconds) for Orca-managed status hooks. The shell
-// wrapper's curl `--max-time 1.5` is the normal dead-endpoint bound; this caps a
-// hook the agent host itself runs in case that transport budget is bypassed.
-// Intentionally independent of Copilot's `timeoutSec: 5` — both managed budgets
-// coexist by design (#4633).
+// Why: host-level backstop timeout for status hooks, independent of the curl --max-time and Copilot's timeoutSec (#4633).
 export const MANAGED_HOOK_TIMEOUT_SECONDS = 10
 export const MANAGED_HOOK_TIMEOUT_MILLISECONDS = MANAGED_HOOK_TIMEOUT_SECONDS * 1000
 
-// Nested command hook used by the Claude-shaped `hooks: [...]` schema (Claude,
-// Codex, Gemini, Droid, Grok, Command Code, Devin).
+// Nested command hook for the Claude-shaped `hooks: [...]` schema (Claude, Codex, Gemini, Droid, Grok, Command Code, Devin).
 export function buildManagedCommandHook(
   command: string,
   timeout = MANAGED_HOOK_TIMEOUT_SECONDS
@@ -55,8 +50,7 @@ export function buildManagedCommandHook(
   return { type: 'command', command, timeout }
 }
 
-// Direct command definition used by schemas that put `command` on the
-// definition itself (Cursor's documented top-level shape).
+// Direct command definition for schemas that put `command` on the definition itself (Cursor's top-level shape).
 export function buildManagedCommandDefinition(command: string): HookDefinition {
   return { command, timeout: MANAGED_HOOK_TIMEOUT_SECONDS }
 }
@@ -78,18 +72,12 @@ export function readHooksJson(configPath: string): HooksConfig | null {
   }
 }
 
-// Why: callers in install/remove need to match not just the exact current
-// managed command, but also stale entries pointing at old script paths — e.g.
-// from a previous dev build with a different Electron userData dir, or a
-// parallel dev/prod install. Matching by the managed script's file name
-// (under any `agent-hooks/` directory) lets a fresh install sweep those
-// without touching unrelated user-authored hooks.
+// Why: match by script file name, not exact command, so a fresh install sweeps stale entries from old/parallel installs.
 export function createManagedCommandMatcher(
   scriptFileName: string
 ): (command: string | undefined) => boolean {
   const scriptStem = scriptFileName.replace(/\.(?:cmd|ps1|sh)$/, '')
-  // Why: local Windows installs use .cmd or Copilot's .ps1, while SSH/POSIX
-  // installs use .sh. A platform switch must still sweep stale Orca hooks.
+  // Why: installs use .cmd/.ps1 (Windows) or .sh (SSH/POSIX); match all so a platform switch still sweeps stale hooks.
   const needles = [
     `agent-hooks/${scriptFileName}`,
     `agent-hooks/${scriptStem}.cmd`,
@@ -119,8 +107,7 @@ function decodePowerShellEncodedCommand(command: string): string | null {
   }
 }
 
-// Why: prod, dev, and parallel Orca instances must write the same managed
-// settings entry instead of racing between per-userData script paths.
+// Why: prod/dev/parallel Orca instances must write the same managed entry, not race between per-userData script paths.
 export function getSharedManagedScriptPath(scriptFileName: string): string {
   return join(homedir(), '.orca', 'agent-hooks', scriptFileName)
 }
@@ -129,16 +116,9 @@ function quotePosixShellString(value: string): string {
   return `'${value.replaceAll("'", "'\\''")}'`
 }
 
-// Why: a stale managed hook entry (left over after the user wiped userData,
-// switched dev↔prod installs, or had a partial install fail) used to fire
-// `/bin/sh "<missing path>"` on every tool call, which exits 127 and surfaces
-// as `PreToolUse hook (failed) error: hook exited with code 127` in the agent
-// transcript. Guarding for a regular readable executable file makes a broken
-// install a silent no-op without hiding failures from a script that starts.
+// Why: guard for a readable executable so a stale entry at a missing script becomes a silent no-op, not an exit-127 failure on every tool call.
 export function wrapPosixHookCommand(scriptPath: string, env: Record<string, string> = {}): string {
-  // Why: POSIX single-quote escape so $, `, ", and \ in scriptPath are taken
-  // literally — avoids a shell-injection footgun if a future caller passes an
-  // arbitrary path.
+  // Why: single-quote escape so $, `, ", \ in scriptPath stay literal — avoids shell injection from an arbitrary path.
   const quoted = quotePosixShellString(scriptPath)
   const envPrefix = Object.entries(env)
     .map(([key, value]) => `${key}='${value.replaceAll("'", "'\\''")}'`)
@@ -162,8 +142,7 @@ export function wrapWindowsHookCommand(
   scriptPath: string,
   env: Record<string, string> = {}
 ): string {
-  // Why: the encoded launcher protects paths across Windows hook shells and
-  // owns stdin when a stale config points at a missing managed script.
+  // Why: the encoded launcher protects paths across Windows shells and drains stdin when the config points at a missing script.
   const quoted = quotePowerShellString(scriptPath)
   const envPrefix = Object.entries(env)
     .map(([key, value]) => `$env:${key} = ${quotePowerShellString(value)}; `)
@@ -176,14 +155,7 @@ export function wrapWindowsHookCommand(
 export const WINDOWS_CMD_SAFE_PATH = /^[A-Za-z0-9_.:\\~-]+$/
 
 export function wrapWindowsCmdHookCommand(scriptPath: string): string {
-  // Why: Codex/Antigravity/Devin launch the hook command as a program (argv[0]),
-  // NOT through cmd.exe, so the launcher must be a single directly-spawnable
-  // token. The bare .cmd path is exactly that. A cmd-builtin `if exist …`
-  // launcher is unspawnable — its argv[0] is `if` — so it fails every hook with
-  // exit 1 (#8430 regression). A stale/missing script therefore surfaces a normal
-  // launch failure here; the missing-script stdin drain lives on the encoded
-  // fallback below, which needs a real interpreter for spaces/metacharacters
-  // anyway and cannot be reached by a cmd-builtin drain without breaking spawn.
+  // Why: Codex/Antigravity/Devin spawn the hook as argv[0], not via cmd.exe, so it must be one spawnable token; a cmd `if exist` launcher isn't (#8430).
   return WINDOWS_CMD_SAFE_PATH.test(scriptPath) ? scriptPath : wrapWindowsHookCommand(scriptPath)
 }
 
@@ -191,17 +163,15 @@ export const WINDOWS_GIT_BASH_SAFE_PATH = /^[A-Za-z0-9_.:/~-]+$/
 
 export function wrapWindowsGitBashHookCommand(scriptPath: string): string {
   const bashPath = scriptPath.replaceAll('\\', '/')
-  // Why: Claude's Git Bash runner can execute a forward-slash .cmd directly;
-  // unsafe paths stay encoded and the fast path gains a missing-file drain.
+  // Why: Claude's Git Bash runner can execute a forward-slash .cmd directly; unsafe paths stay encoded.
   return WINDOWS_GIT_BASH_SAFE_PATH.test(bashPath)
     ? `if [ -f ${quotePosixShellString(bashPath)} ]; then ${quotePosixShellString(bashPath)}; else ${POSIX_HOOK_STDIN_DRAIN_COMMAND}; fi`
     : wrapWindowsHookCommand(scriptPath)
 }
 
 export function buildWindowsAgentHookPostCommand(source: AgentHookSource): string {
-  // Why: Codex runs these hooks inline on every turn. PowerShell startup alone
-  // makes trusted Windows hooks visibly slow, so mirror the POSIX curl path.
-  // Qualify curl so a repo-local curl.exe cannot hijack hook payloads.
+  // Why: PowerShell startup makes inline per-turn Codex hooks visibly slow, so mirror the POSIX curl path.
+  // Why: fully-qualify curl so a repo-local curl.exe can't hijack hook payloads.
   return [
     `"%SystemRoot%\\System32\\curl.exe" -sS -X POST "http://127.0.0.1:%ORCA_AGENT_HOOK_PORT%/hook/${source}" ^`,
     '  --connect-timeout 0.5 --max-time 1.5 ^',
@@ -217,12 +187,7 @@ export function buildWindowsAgentHookPostCommand(source: AgentHookSource): strin
   ].join('\r\n')
 }
 
-// Why: status hooks fire up to 6× per turn; spawning PowerShell per post adds
-// ~300ms of interpreter startup each, which Codex 0.140's synchronous "Running
-// <event> hook" rows make visible. curl.exe (Windows 10 1803+) posts the same
-// form fields as the POSIX hook and reads the raw payload from stdin via
-// `--data-urlencode payload@-`, so UTF-8 (e.g. CJK prompts) survives byte-for-
-// byte without the code-page translation that previously forced PowerShell.
+// Why: PowerShell per-post costs ~300ms startup and mangles UTF-8 via code-page translation; curl.exe (Win10 1803+) avoids both.
 export function buildWindowsAgentHookCurlPostCommand(source: AgentHookSource): string {
   return [
     '"%SystemRoot%\\System32\\curl.exe" -sS -X POST',
@@ -294,8 +259,7 @@ export function hookDefinitionHasManagedCommand(
   )
 }
 
-// Why: temp+rename so concurrent Orca instances writing this shared path can't
-// produce a torn script that an in-flight `/bin/sh <scriptPath>` would source.
+// Why: temp+rename so concurrent writers can't leave a torn script for an in-flight /bin/sh to source.
 export function writeManagedScript(scriptPath: string, content: string): void {
   const dir = dirname(scriptPath)
   mkdirSync(dir, { recursive: true })
@@ -316,9 +280,7 @@ export function writeManagedScript(scriptPath: string, content: string): void {
   const tmpPath = join(dir, `.${Date.now()}-${randomUUID()}.tmp`)
   try {
     writeScriptWithAclRetry(tmpPath, content)
-    // Why: chmod before rename so the canonical path is never visible in a
-    // unreadable/non-executable state; wrapPosixHookCommand's guards would
-    // silently skip the hook in that window.
+    // Why: chmod before rename so the canonical path is never visible non-executable, else the POSIX guard skips the hook.
     if (process.platform !== 'win32') {
       chmodSync(tmpPath, 0o755)
     }
@@ -334,8 +296,7 @@ export function writeManagedScript(scriptPath: string, content: string): void {
   }
 }
 
-// Why: on Windows, write may fail with EPERM if the target directory has a
-// restrictive DACL. Grant an explicit ACL on EPERM and retry once.
+// Why: a restrictive directory DACL makes writes fail with EPERM on Windows; grant an ACL and retry once.
 function writeScriptWithAclRetry(scriptPath: string, content: string): void {
   try {
     writeFileSync(scriptPath, content, 'utf-8')
@@ -357,39 +318,25 @@ export function writeHooksJson(configPath: string, config: HooksConfig): void {
   const dir = dirname(configPath)
   mkdirSync(dir, { recursive: true })
 
-  // Why: write to a temp file then rename so a crash or disk-full mid-write
-  // leaves the original untouched. This is the only safe way to update a
-  // config file the user may have hand-edited.
-  //
-  // Why randomUUID: Date.now() alone collides when two install() calls fire in
-  // the same millisecond targeting the same dir (e.g. a future caller that
-  // installs multiple agents sharing a config dir, or rapid reinstalls from
-  // the settings UI). A collision would corrupt one of the two writes. The
-  // UUID suffix makes the tmp path unique per call.
+  // Why: temp+rename leaves the original untouched on a crash/disk-full mid-write.
+  // Why randomUUID: avoids tmp-path collisions when two install() calls fire in the same millisecond.
   const tmpPath = join(dir, `.${Date.now()}-${randomUUID()}.tmp`)
   const serialized = `${JSON.stringify(config, null, 2)}\n`
 
-  // Why: skip the write (and therefore the .bak rotation) when the on-disk
-  // content is already identical. Without this, every install() rewrites the
-  // file and rolls the backup forward, which can silently destroy the last
-  // recoverable copy if install() is called repeatedly (e.g. on app start).
+  // Why: skip identical writes so repeated install() calls don't roll the .bak forward and destroy the last recoverable copy.
   if (existsSync(configPath)) {
     try {
       if (readFileSync(configPath, 'utf-8') === serialized) {
         return
       }
     } catch {
-      // Fall through to the normal write path — a read error here is not
-      // worth failing the install for; the atomic write below will either
-      // succeed or throw loudly.
+      // Fall through to the normal write path; a read error isn't worth failing the install for.
     }
   }
 
   try {
     writeFileSync(tmpPath, serialized, 'utf-8')
-    // Why: single rolling backup — one file, no accumulation in ~/.claude.
-    // Protects against a merge-logic bug producing bad JSON; the original is
-    // always recoverable from <configPath>.bak until the next write.
+    // Why: single rolling backup so a merge-logic bug producing bad JSON stays recoverable from <configPath>.bak until the next write.
     if (existsSync(configPath)) {
       copyFileSync(configPath, `${configPath}.bak`)
     }
diff --git a/src/main/agent-hooks/server.test.ts b/src/main/agent-hooks/server.test.ts
index f1aba1cb09f..0a75205623c 100644
--- a/src/main/agent-hooks/server.test.ts
+++ b/src/main/agent-hooks/server.test.ts
@@ -157,9 +157,7 @@ describe('AgentHookServer listener replay', () => {
             state: 'working',
             prompt: 'review loop',
             agentType: 'claude',
-            // Why: a working pane can be child-driven (lead already idle).
-            // Ctrl+C does not stop background children, so no terminal done
-            // may be inferred while one is still running.
+            // Why: a working pane can be child-driven while the lead is idle; Ctrl+C doesn't stop children, so no terminal-done may be inferred here.
             subagents: [{ id: 'a1', state: 'working', startedAt: 900 }]
           }
         },
@@ -2571,9 +2569,7 @@ describe('AgentHookServer listener replay', () => {
     }
   })
 
-  // Why: agent-status-over-SSH §3 — ingestRemote must run the same warn-once
-  // cross-build diagnostics the local HTTP path runs, so a remote source of
-  // genuinely stale hooks emits the same signal locally.
+  // Why (agent-status-over-SSH §3): ingestRemote must run the same warn-once diagnostics as the local HTTP path so stale remote hooks signal locally.
   it('runs warn-once env/version diagnostics on relay-forwarded events', async () => {
     const server = new AgentHookServer()
     await server.start({ env: 'production' })
@@ -2631,9 +2627,7 @@ describe('AgentHookServer listener replay', () => {
         'conn-1'
       )
       expect(warn.mock.calls.length).toBe(warnsAfterFirst)
-      // Why: pin both invariants — warn-once dedupe AND fanout still fires for
-      // the second event. Without the second assertion, a future refactor that
-      // drops the second event silently would still leave warn-count unchanged.
+      // Why: assert fanout still fires on the second event too, else a refactor that drops it would pass on warn-count alone.
       expect(listener).toHaveBeenCalledTimes(2)
     } finally {
       server.stop()
@@ -3843,9 +3837,7 @@ describe('Claude hook normalization', () => {
   })
 
   it('PostToolUse for an unknown tool surfaces the name without input', () => {
-    // Why: we use a per-tool allowlist to decide which field to preview.
-    // Tools we do not recognize render as name-only rather than guessing at
-    // a field, which avoids noisy/misleading previews (e.g. an opaque ID).
+    // Why: a per-tool allowlist picks the preview field; unrecognized tools render name-only to avoid guessing a misleading field (e.g. an opaque ID).
     const result = _internals.normalizeHookPayload(
       'claude',
       buildBody({
@@ -3860,9 +3852,7 @@ describe('Claude hook normalization', () => {
   })
 
   it('PostToolUse for TaskUpdate does not produce a misleading input preview', () => {
-    // Why: TaskUpdate's tool_input (e.g. { task_id: "3", status: "in_progress" })
-    // has no meaningful preview — rendering "3" is actively confusing. The
-    // allowlist approach leaves toolInput undefined for unlisted tools.
+    // Why: TaskUpdate's tool_input has no meaningful preview (rendering "3" is confusing), so the allowlist leaves toolInput undefined.
     const result = _internals.normalizeHookPayload(
       'claude',
       buildBody({
@@ -4144,9 +4134,7 @@ describe('Claude hook normalization', () => {
     })
 
     it('finds an assistant reply that sits past the first chunk boundary', () => {
-      // Why: a turn with many large tool_result entries pushes the final text
-      // reply well past the first 64 KB chunk; the chunked scan should keep
-      // reading backward until it finds it.
+      // Why: large tool_result entries push the final reply past the first 64 KB chunk; the scan must keep reading backward to find it.
       const filler = 'x'.repeat(70_000)
       const lines = [
         { role: 'assistant', message: { role: 'assistant', content: 'deeply buried reply' } },
@@ -4208,8 +4196,7 @@ describe('Claude hook normalization', () => {
       }),
       'production'
     )
-    // Stop event has no tool fields of its own — merged snapshot should still
-    // carry the earlier PreToolUse values.
+    // Stop event has no tool fields, so the merged snapshot must keep the earlier PreToolUse values.
     const stop = _internals.normalizeHookPayload(
       'claude',
       buildBody({ hook_event_name: 'Stop' }),
@@ -4236,10 +4223,7 @@ describe('Codex hook normalization', () => {
   })
 
   it('PreToolUse surfaces tool name + input preview and stays in working state', () => {
-    // Why: Codex's PreToolUse is NOT an approval prompt — it fires for every
-    // tool call. We map it to `working` (never `waiting`) and use it only to
-    // give the dashboard a live readout during the gap between prompt and
-    // Stop. Real approval signals flow through PermissionRequest.
+    // Why: Codex's PreToolUse fires for every tool call (not an approval), so map it to `working` not `waiting`; approvals flow through PermissionRequest.
     const result = _internals.normalizeHookPayload(
       'codex',
       buildBody({
@@ -4255,10 +4239,7 @@ describe('Codex hook normalization', () => {
   })
 
   it('PermissionRequest maps to waiting and surfaces the pending tool input', () => {
-    // Why: Codex asks for user attention through PermissionRequest. Orca's
-    // sidebar red dot depends on this becoming `waiting`; treating it like
-    // PreToolUse would leave the pane looking busy while it is blocked on the
-    // user.
+    // Why: PermissionRequest must map to `waiting` (sidebar red dot); treating it like PreToolUse would leave the pane looking busy while blocked on the user.
     const result = _internals.normalizeHookPayload(
       'codex',
       buildBody({
@@ -4275,9 +4256,7 @@ describe('Codex hook normalization', () => {
   })
 
   it('UserPromptSubmit does not extract tool fields even when the payload carries them', () => {
-    // Why: UserPromptSubmit is a turn-boundary event; any tool_name on it
-    // would be leftover noise and should not leak into the working-state
-    // preview. Tool extraction is gated to PreToolUse/PostToolUse.
+    // Why: UserPromptSubmit is a turn boundary; tool extraction is gated to Pre/PostToolUse so stray tool_name can't leak into the preview.
     const result = _internals.normalizeHookPayload(
       'codex',
       buildBody({
@@ -4419,11 +4398,7 @@ describe('OpenCode hook normalization', () => {
   })
 
   it('SessionBusy does NOT clear the cached user prompt', () => {
-    // Why: OpenCode emits the user's MessagePart (message.updated) *before*
-    // SessionBusy fires — the session goes idle→busy only after OpenCode begins
-    // processing the prompt. So the cached prompt at SessionBusy is the current
-    // turn's prompt, not the previous turn's. Clearing on SessionBusy would
-    // clobber the data the dashboard needs to render for this turn.
+    // Why: OpenCode caches the user's MessagePart before SessionBusy fires, so the cached prompt is this turn's; clearing it would clobber the dashboard.
     _internals.normalizeHookPayload(
       'opencode',
       buildBody({ hook_event_name: 'MessagePart', role: 'user', text: 'new prompt' }),
@@ -4458,12 +4433,7 @@ describe('OpenCode hook normalization', () => {
   })
 
   it('AskUserQuestion maps to waiting', () => {
-    // Why: OpenCode emits `question.asked` when the agent uses an ask-the-user
-    // tool (distinct from `permission.asked`, which blocks on tool approval).
-    // Both leave the agent idle-but-waiting on a human, so both must render
-    // the same red "needs attention" indicator. Without this mapping the pane
-    // silently stays in `working` and the user has no visual cue that the
-    // agent is waiting on them.
+    // Why: AskUserQuestion leaves the agent idle-but-waiting on a human, so it must map to `waiting` (red dot) like permission.asked, not stay `working`.
     const result = _internals.normalizeHookPayload(
       'opencode',
       buildBody({ hook_event_name: 'AskUserQuestion' }),
@@ -4514,10 +4484,7 @@ describe('OpenCode hook normalization', () => {
   })
 
   it('caps oversized MessagePart text from stale (pre-throttle) plugin builds', () => {
-    // Why: plugin builds installed before the throttle/cap fix re-post the
-    // full accumulated reply on every streamed part update. The listener must
-    // bound the text so each event's status compare, IPC fanout, and renderer
-    // store update stay O(cap) instead of O(reply length).
+    // Why: stale plugin builds re-post the full reply on every part update, so the listener must cap the text to keep per-event work O(cap).
     const assistant = _internals.normalizeHookPayload(
       'opencode',
       buildBody({
@@ -4529,9 +4496,7 @@ describe('OpenCode hook normalization', () => {
     )
     expect(assistant?.payload.lastAssistantMessage?.length).toBe(8_000)
 
-    // Why: prompt has always been single-line-capped at 200 by
-    // normalizeAgentStatusObject; this asserts the oversized input still
-    // flows through without blowing past that bound.
+    // Why: prompt is capped at 200 by normalizeAgentStatusObject; assert oversized input still stays within that bound.
     const user = _internals.normalizeHookPayload(
       'opencode',
       buildBody({
@@ -4656,8 +4621,7 @@ describe('Cursor hook normalization', () => {
       }),
       'production'
     )
-    // Why: keeping toolName set would let the compact sidebar show the tool
-    // instead of the failure text, hiding the error from the user.
+    // Why: keeping toolName would let the compact sidebar show the tool instead of the failure text, hiding the error.
     expect(failed?.payload).toMatchObject({
       state: 'working',
       lastAssistantMessage: 'file not found'
@@ -5193,8 +5157,7 @@ describe('Pi hook normalization', () => {
       buildBody({ hook_event_name: 'message_end', role: 'user', text: 'hi' }),
       'production'
     )
-    // Why: pi captures the user prompt via before_agent_start, not via
-    // message_end. A user-role message_end should not flip lastAssistantMessage.
+    // Why: pi captures the user prompt via before_agent_start, so a user-role message_end must not flip lastAssistantMessage.
     expect(result?.payload.lastAssistantMessage).toBeUndefined()
   })
 
@@ -5214,8 +5177,7 @@ describe('Pi hook normalization', () => {
       buildBody({ hook_event_name: 'session_shutdown' }),
       'production'
     )
-    // Why: Pi also emits shutdown when reloading or replacing its in-process
-    // session while the PTY stays alive; only agent_end proves turn completion.
+    // Why: Pi emits shutdown on reload/replace while the PTY stays alive; only agent_end proves turn completion.
     expect(result).toBeNull()
   })
 
@@ -5324,8 +5286,7 @@ describe('Copilot hook normalization', () => {
       }),
       'production'
     )
-    // Why: keeping toolName set would let the compact sidebar show the tool
-    // instead of the failure text, hiding the error from the user.
+    // Why: keeping toolName would let the compact sidebar show the tool instead of the failure text, hiding the error.
     expect(failed?.payload).toMatchObject({
       state: 'working',
       lastAssistantMessage: 'command not found'
@@ -5715,9 +5676,7 @@ describe('Endpoint file lifecycle', () => {
     await server.start({ env: 'production', userDataPath })
     try {
       const filePath = server.endpointFilePath!
-      // Why: mask off type/setuid bits so we assert only the rwx octet that
-      // writeFileSync(mode:0o600) sets. A leaky umask at dir-create time can
-      // leave group/other bits on the *parent* dir but not on the file itself.
+      // Why: mask to the rwx octet so we assert only the file's mode:0o600, not umask-leaked bits on the parent dir.
       const mode = statSync(filePath).mode & 0o777
       expect(mode).toBe(0o600)
     } finally {
@@ -5739,19 +5698,11 @@ describe('Endpoint file lifecycle', () => {
       const secondToken = server.buildPtyEnv().ORCA_AGENT_HOOK_TOKEN
       // Path is stable (so PTYs stamped before restart can still find the file)
       expect(secondPath).toBe(firstPath)
-      // But contents are refreshed with the new token (and port) — that is the
-      // whole point of the design: survivors reading a stale-env file reach the
-      // live server. Why token-first: the token is randomUUID()-minted per
-      // start(), so it is guaranteed to differ across restarts. The port comes
-      // from listen(0) and the kernel can legitimately reassign the same
-      // ephemeral port, so asserting port-inequality would be a latent flake.
+      // Contents refresh with a new token so stale-env survivors reach the live server.
       expect(secondToken).toBeTruthy()
       expect(secondToken).not.toBe(firstToken)
       const contents = readFileSync(secondPath!, 'utf8')
-      // Why: token-based content check is the rewrite signal. A strict
-      // "contents does NOT contain firstPort" assertion would flake on the
-      // (rare but legitimate) case where listen(0) reuses the same ephemeral
-      // port across restarts. The token is randomUUID() and cannot collide.
+      // Why: assert on token (randomUUID, can't collide), not port — listen(0) may legitimately reuse the ephemeral port and flake a port check.
       expect(contents).toContain(`ORCA_AGENT_HOOK_PORT=${secondPort}`)
       expect(contents).toContain(`ORCA_AGENT_HOOK_TOKEN=${secondToken}`)
       expect(contents).not.toContain(`ORCA_AGENT_HOOK_TOKEN=${firstToken}`)
@@ -5761,13 +5712,7 @@ describe('Endpoint file lifecycle', () => {
   })
 
   it('leaves the endpoint file in place on stop()', async () => {
-    // Why: stop() deliberately does NOT unlink the endpoint file. A stale file
-    // points at a dead port — the fail-open path (hook POSTs silently fail,
-    // same as pre-endpoint-file). Unlinking would introduce a TOCTOU race with a
-    // concurrent Orca instance sharing userData that could rewrite the file
-    // between our token check and unlink. The next successful start()
-    // overwrites the file atomically; tmp-file orphan hygiene is handled by
-    // the sweep inside writeEndpointFile().
+    // Why: stop() leaves the file (stale = fail-open); unlinking would race a concurrent Orca instance rewriting it between token-check and unlink (TOCTOU).
     const server = new AgentHookServer()
     await server.start({ env: 'production', userDataPath })
     const filePath = server.endpointFilePath!
@@ -5825,9 +5770,7 @@ describe('Endpoint file lifecycle', () => {
   })
 
   it('buildPtyEnv omits ORCA_AGENT_HOOK_ENDPOINT when no userDataPath was provided', async () => {
-    // Why: the endpoint file is opt-in via start({ userDataPath }). In tests
-    // and in the packaged main-process path where userData is unset for any
-    // reason, hooks should fall back to the v1 behavior (no ENDPOINT key).
+    // Why: the endpoint file is opt-in via userDataPath; without it, hooks fall back to v1 behavior (no ENDPOINT key).
     const server = new AgentHookServer()
     await server.start({ env: 'production' })
     try {
@@ -5846,10 +5789,7 @@ describe('Endpoint file lifecycle', () => {
   })
 
   it('sweeps stale .endpoint-*.tmp orphans older than 5 minutes on start', async () => {
-    // Why: writeEndpointFile() writes to a unique tmp path then renames. A crash
-    // between write and rename leaves an orphan tmp; the sweep inside
-    // writeEndpointFile() must drop ones older than 5 min without touching
-    // fresh ones (a concurrent writer's in-flight tmp).
+    // Why: a crash between tmp-write and rename orphans a tmp; sweep must drop stale ones (>5min) but spare a concurrent writer's fresh in-flight tmp.
     const dir = join(userDataPath, 'agent-hooks')
     mkdirSync(dir, { recursive: true })
     const staleTmp = join(dir, '.endpoint-999-stale.tmp')
@@ -5870,12 +5810,7 @@ describe('Endpoint file lifecycle', () => {
   })
 
   it('refuses to write the endpoint file when a value contains shell metacharacters', async () => {
-    // Why: every value written is sourced as shell. The isShellSafeEndpointValue
-    // allowlist must reject a metacharacter-bearing value so a future caller
-    // cannot command-inject via the sourced file. `env` is the only caller-
-    // provided field we can easily poison from a test — feed it a semicolon
-    // and assert the file is not written and buildPtyEnv() omits the ENDPOINT
-    // key (gated on endpointFileWritten).
+    // Why: written values are sourced as shell, so isShellSafeEndpointValue must reject metacharacters to prevent command injection.
     const server = new AgentHookServer()
     await server.start({ env: 'bad;value', userDataPath })
     try {
@@ -5960,10 +5895,7 @@ describe('Endpoint file lifecycle', () => {
     try {
       const filePath = server.endpointFilePath!
       const expectedPort = server.buildPtyEnv().ORCA_AGENT_HOOK_PORT
-      // Why: sources the file in a subshell and echoes the resulting env var,
-      // exactly as the managed hook script does at runtime. If the file shape
-      // ever drifts from `KEY=VALUE` (e.g. someone adds shell metacharacters
-      // without quoting), this test catches it before users do.
+      // Why: source the file exactly as the managed hook script does, catching drift from the KEY=VALUE shape before users do.
       const out = execFileSync('/bin/sh', ['-c', `. "${filePath}" && echo "$ORCA_AGENT_HOOK_PORT"`])
         .toString()
         .trim()
@@ -5989,9 +5921,7 @@ describe('Last-status persistence', () => {
     return join(userDataPath, 'agent-hooks', 'last-status.json')
   }
 
-  // Why: hydrate now drops entries older than 7d (HYDRATE_MAX_AGE_MS). Use
-  // a recent-but-not-Date.now() timestamp in fixtures so the tests assert
-  // hydration behavior rather than racing the wall clock.
+  // Why: use a recent-but-not-now timestamp so fixtures survive hydrate's 7d drop (HYDRATE_MAX_AGE_MS) without racing the wall clock.
   function recentTs(offsetMs = 0): number {
     return Date.now() - 60 * 60 * 1000 + offsetMs
   }
@@ -6305,8 +6235,7 @@ describe('Last-status persistence', () => {
           subagents: undefined
         })
       ])
-      // Why: make the migration one-time; otherwise every launch reparses and
-      // re-prunes the same persisted idle rows.
+      // Why: migration must be one-time, else every launch re-prunes the same persisted idle rows.
       const persisted = JSON.parse(readFileSync(lastStatusPath(), 'utf8'))
       expect(persisted.entries[PANE].payload.subagents).toBeUndefined()
     } finally {
@@ -6614,9 +6543,7 @@ describe('Last-status persistence', () => {
         entries: {
           [TAB_A_PANE]: {
             paneKey: TAB_A_PANE,
-            // Why: deliberately divergent — paneKey says tab-A, the entry
-            // claims tab-B. Sanitizer must drop rather than hydrate this
-            // inconsistent row.
+            // Why: paneKey says tab-A but entry claims tab-B; sanitizer must drop the inconsistent row, not hydrate it.
             tabId: 'tab-B',
             receivedAt: recentTs(),
             stateStartedAt: recentTs(-1000),
@@ -6676,14 +6603,10 @@ describe('Last-status persistence', () => {
       server.flushStatusPersistSync()
       const firstMtime = statSync(lastStatusPath()).mtimeMs
 
-      // Why: a no-op clearPaneState on a paneKey not in the cache is a
-      // mutation site that should NOT trigger a redundant write. (clear was
-      // designed to bail when nothing was evicted.)
+      // Why: clearPaneState on a paneKey not in the cache must not trigger a redundant write (clear bails when nothing was evicted).
       server.clearPaneState(makePaneKey('non-existent', LEAF_5))
       server.flushStatusPersistSync()
-      // Touch back to the same mtime would let the test pass spuriously, so
-      // assert no rewrite happened by checking that mtime is unchanged after
-      // a forced sync flush.
+      // Assert no rewrite happened: mtime unchanged after a forced sync flush.
       const secondMtime = statSync(lastStatusPath()).mtimeMs
       expect(secondMtime).toBe(firstMtime)
     } finally {
@@ -6706,8 +6629,7 @@ describe('Last-status persistence', () => {
     } finally {
       server.stop()
     }
-    // Why: file written even though we never explicitly flushed before stop —
-    // stop() must synchronously drain the pending trailing-debounced timer.
+    // Why: stop() must synchronously drain the pending trailing-debounced timer even though we never explicitly flushed.
     expect(existsSync(lastStatusPath())).toBe(true)
     const parsed = JSON.parse(readFileSync(lastStatusPath(), 'utf8'))
     expect(parsed.entries[PANE]?.payload?.prompt).toBe('flush me')
@@ -7114,9 +7036,7 @@ describe('AgentHookServer ingestRemote', () => {
     const server = new AgentHookServer()
     const listener = vi.fn()
     server.setListener(listener)
-    // Why: bypass parseAgentStatusPayload (which itself rejects bad states) by
-    // constructing an obviously-invalid payload — `ingestRemote` is the trust
-    // boundary we're testing, not the parser.
+    // Why: bypass parseAgentStatusPayload with an invalid payload — ingestRemote is the trust boundary under test, not the parser.
     server.ingestRemote(
       {
         paneKey: PANE,
@@ -7281,10 +7201,7 @@ describe('AgentHookServer ingestRemote', () => {
   })
 
   it('normalizes inner payload via normalizeAgentStatusPayload — clamps oversized prompt', () => {
-    // Why: the relay normally normalizes the payload on the wire, but a buggy
-    // or malicious relay could forward an over-cap field. ingestRemote must
-    // re-run the canonical normalizer so the AGENT_STATUS_MAX_FIELD_LENGTH
-    // cap (200 chars) is enforced at the trust boundary.
+    // Why: a buggy/malicious relay could forward an over-cap field, so ingestRemote re-runs the normalizer to enforce the AGENT_STATUS_MAX_FIELD_LENGTH cap at the trust boundary.
     const server = new AgentHookServer()
     const listener = vi.fn()
     server.setListener(listener)
diff --git a/src/main/agent-hooks/server.ts b/src/main/agent-hooks/server.ts
index 4c5d4c80cc1..d02642b1111 100644
--- a/src/main/agent-hooks/server.ts
+++ b/src/main/agent-hooks/server.ts
@@ -1,15 +1,5 @@
 /* eslint-disable max-lines -- Why: this file owns the loopback HTTP adapter, the on-disk last-status persistence layer (hydrate, sanitize, TTL, atomic write, drop), and the relay ingest path in one place so the cache lifecycle (set → schedule → drain) lives next to the surfaces that mutate it. Splitting would force mutual `private` accessor scaffolding for a single class. */
-// Why: this module is the Orca-main-process adapter for the shared
-// agent-hook listener pipeline (`src/shared/agent-hook-listener.ts`). The
-// listener internals (request parsing, payload normalization, endpoint-file
-// writing, validation) live in `shared/` so the relay can host the same
-// pipeline on the remote without dragging Electron in. This file owns:
-//   - the loopback HTTP socket + bearer-token auth
-//   - the IPC fanout (setListener / lastStatusByPaneKey replay)
-//   - the `ingestRemote` entry point that bypasses HTTP for relay-forwarded
-//     events (see docs/design/agent-status-over-ssh.md §5)
-//   - the on-disk last-status cache (`last-status.json`) that survives
-//     Orca restart so retained dashboard rows reappear on relaunch
+// Why: this main-process adapter keeps listener internals in shared/ (`src/shared/agent-hook-listener.ts`) so the relay can host the same pipeline without Electron. See docs/design/agent-status-over-ssh.md §5.
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
 import { createHash, randomBytes, randomUUID } from 'node:crypto'
 import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
@@ -74,14 +64,7 @@ import { isCommandCodeNewTurnWhileWorking } from '../../shared/command-code-turn
 
 export type { AgentHookSource }
 
-// Why: server-process-only enrichment of the shared event payload. The shared
-// listener emits `AgentHookEventPayload` (the bare event shape). For
-// persistence and the dashboard's "did the agent transition since I last
-// looked?" comparison, we attach `receivedAt` (when the latest event arrived
-// for this pane) and `stateStartedAt` (when the current state first appeared).
-// Stored in `state.lastStatusByPaneKey` via assignability — `AgentHookEventPayload`
-// is the declared map value, and the extra fields ride along untouched because
-// the shared module only writes/clears, never reads.
+// Why: server-side enrichment — receivedAt = latest event arrival, stateStartedAt = when the current state first appeared; extra fields ride the shared map untouched (it only writes/clears).
 type EnrichedAgentHookEventPayload = AgentHookEventPayload & {
   receivedAt: number
   stateStartedAt: number
@@ -103,42 +86,24 @@ type PaneKeyAliasEntry = {
   authorityVerified: boolean
 }
 
-// Why: name of the on-disk cache that survives Orca restart. Lives next to
-// the endpoint file in userData/agent-hooks/ so all hook-server-owned cross-
-// restart artifacts stay co-located.
+// Why: co-located with the endpoint file in userData/agent-hooks/ so hook-server cross-restart artifacts stay together.
 const LAST_STATUS_FILE_NAME = 'last-status.json'
 const ASSISTANT_MESSAGE_RETRY_ATTEMPTS = 5
 const ASSISTANT_MESSAGE_RETRY_MS = 50
 const INTERRUPTED_DONE_LATE_WORKING_SUPPRESSION_MS = 15_000
 
-// Why: starts at 2 (not 1) because pre-merge dev iterations of this branch
-// wrote a v1 shape with no receivedAt / stateStartedAt. Bumping to 2 means a
-// developer who upgrades from an in-flight branch sees an empty hydration
-// once instead of partially-typed legacy entries. New file format; never
-// shipped to users at v1. A mismatched version is treated as a corrupt file
-// (silent empty hydration).
+// Why: starts at 2 — pre-merge v1 lacked receivedAt/stateStartedAt (never shipped); a mismatched version hydrates empty (treated as corrupt).
 const LAST_STATUS_FILE_VERSION = 2
 
-// Why: trailing-edge debounce so a burst of hook events from a multi-agent
-// run produces one disk write instead of N. The latency budget matches other
-// hook-server batching; quit-time uses flushStatusPersistSync() for the
-// guaranteed final flush.
+// Why: trailing-edge debounce so a burst of hook events yields one disk write, not N; quit-time flushStatusPersistSync() guarantees the final flush.
 const STATUS_PERSIST_DEBOUNCE_MS = 250
 const TOOL_PROGRESS_HOOK_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'PostToolUseFailure'])
 const AGENT_PROMPT_SENT_AGENT_KINDS = new Set<AgentKind>(AGENT_KIND_VALUES)
 
-// Why: bound the on-disk file's growth across many sessions. PTY-teardown
-// eviction handles closed panes, but daemon-restored PTYs that never re-attach
-// and crash-recovery paths where teardown never fires can leave entries
-// pinned forever. 7 days matches the user-visible "still relevant?" horizon —
-// older entries have almost certainly been resolved or abandoned and should
-// not resurrect on hydrate.
+// Why: bound file growth from PTYs that never re-attach; 7 days is the "still relevant?" horizon beyond which entries shouldn't resurrect on hydrate.
 const HYDRATE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
 
-// Why: closed-tab suppression only needs to cover recently closed tabs — a
-// status event for a long-closed tab cannot arrive once its process/hooks are
-// gone. Bound the set so it can't grow one entry per tab close for the whole
-// session (it is otherwise only cleared at app quit).
+// Why: a long-closed tab can't receive status events; bound the set so it can't grow one entry per close for the whole session.
 export const CLOSED_AGENT_STATUS_TAB_IDS_MAX = 1024
 export const CLOSED_AGENT_STATUS_PANE_KEYS_MAX = 1024
 export const PANE_KEY_ALIASES_MAX = 1024
@@ -176,8 +141,7 @@ function equivalentInterruptAgentType(
   return normalizedActual === normalizedBaseline
 }
 
-// Why: paneKey is `${tabId}:${leafUuid}` — validate the durable leaf suffix
-// at write/hydrate time so legacy numeric rows fail closed.
+// Why: validate the durable `${tabId}:${leafUuid}` leaf suffix at write/hydrate so legacy numeric rows fail closed.
 export function isValidPaneKey(value: unknown): value is string {
   return (
     typeof value === 'string' && value.length <= MAX_PANE_KEY_LEN && parsePaneKey(value) !== null
@@ -194,16 +158,14 @@ function dropHydratedIdleClaudeSubagents(
     return payload
   }
   const workingSubagents = payload.subagents.filter((subagent) => subagent.state === 'working')
-  // Why: older builds persisted finished Claude children as idle rows. Prune
-  // them from the replay payload itself so restart cannot resurrect the pile.
+  // Why: older builds persisted finished Claude children as idle rows; prune them so restart can't resurrect the pile.
   return {
     ...payload,
     subagents: workingSubagents.length > 0 ? workingSubagents : undefined
   }
 }
 
-// Why: the sole gate deciding whether a providerSessionOnly row is trustworthy
-// enough to keep. Shared so the hydrate and relay-ingest paths can't drift.
+// Why: the sole gate for keeping a providerSessionOnly row; shared so hydrate and relay-ingest can't drift.
 function isValidPiProviderSessionOnly(
   providerSession: AgentProviderSessionMetadata | undefined,
   agentType: AgentType | undefined
@@ -230,9 +192,7 @@ function sanitizeHydratedEntry(
   if (tabId !== undefined && (typeof tabId !== 'string' || tabId.length === 0)) {
     return null
   }
-  // Why: paneKey is `${tabId}:${leafUuid}`; a stored entry whose tabId field
-  // diverges from the key's tab segment is corruption (renamer bug, manual
-  // edit, future shape drift). Drop instead of hydrating an inconsistent row.
+  // Why: a stored tabId that diverges from the paneKey's tab segment is corruption; drop instead of hydrating an inconsistent row.
   if (typeof tabId === 'string' && tabId !== parsedPaneKey.tabId) {
     return null
   }
@@ -252,8 +212,7 @@ function sanitizeHydratedEntry(
   ) {
     return null
   }
-  // Why: connectionId is allowed to be null (local) or string (relay). Any
-  // other shape is rejected so the post-merge typed surface stays honest.
+  // Why: connectionId is null (local) or string (relay); any other shape is rejected to keep the typed surface honest.
   const connectionIdRaw = record.connectionId
   let connectionId: string | null
   if (connectionIdRaw === null || connectionIdRaw === undefined) {
@@ -307,10 +266,7 @@ function toAgentStatusIpcPayload(entry: EnrichedAgentHookEventPayload): AgentSta
   }
 }
 
-// Why: OSC-only dedupe (ingestTerminalStatus). Deliberately omits `subagents`:
-// OSC payloads never carry them, and including the field would make every
-// hook-cached entry with child rows non-equivalent — the OSC ping would then
-// apply and wipe the roster. Do not reuse this for hook-path comparisons.
+// Why: OSC-only dedupe; omits `subagents` (OSC never carries them) so an OSC ping can't wipe the hook-cached roster. Don't reuse for hook comparisons.
 function equivalentParsedAgentStatusPayload(
   a: ParsedAgentStatusPayload,
   b: ParsedAgentStatusPayload
@@ -345,8 +301,7 @@ function isToolProgressWorkingAfterInterrupt(next: AgentHookEventPayload): boole
   if (next.payload.agentType !== 'claude') {
     return false
   }
-  // Why: a same-prompt retry is another UserPromptSubmit, while late Claude
-  // progress after Ctrl+C arrives as tool lifecycle work for the old turn.
+  // Why: a same-prompt retry is another UserPromptSubmit, while late post-Ctrl+C progress arrives as tool lifecycle work.
   return next.hookEventName !== undefined && TOOL_PROGRESS_HOOK_EVENTS.has(next.hookEventName)
 }
 
@@ -378,10 +333,7 @@ function shouldKeepClaudePermissionVisible(
   if (isClaudePermissionResumingApprovedTool(previous, next)) {
     return false
   }
-  // Why: only real permission requests stay sticky across concurrent subagent
-  // activity; interactive questions clear on the next working hook. Newer
-  // Claude reports the AskUserQuestion wait AS a PermissionRequest, so the
-  // tool name — not the event name — decides which rule applies.
+  // Why: only real permission requests stay sticky; newer Claude reports AskUserQuestion as a PermissionRequest, so tool name (not event) decides.
   if (isAskUserQuestionTool(previous.payload.toolName)) {
     return false
   }
@@ -427,10 +379,7 @@ function isClaudePermissionResumingApprovedTool(
     (next.hookEventName === 'PreToolUse' || next.hookEventName === 'PostToolUse') &&
     nextToolUseId !== undefined &&
     !hasConflictingToolUseId &&
-    // Why: subagents can share `agent_type`; a concrete agent id is the
-    // strongest available signal that the permission owner resumed execution.
-    // Claude's approval path omits identity but preserves the original
-    // tool_use_id on PostToolUse, so that exact id is also a safe clear signal.
+    // Why: subagents share agent_type, so a concrete agent id (or the preserved PostToolUse tool_use_id) is the safest resume signal.
     (hasMatchingConcreteAgentId || hasSameExplicitAgentType || hasMatchingToolUseId) &&
     sameToolName &&
     (sameKnownToolInput || sameUnknownInputFromConcreteAgent || sameUnknownInputFromToolUseId)
@@ -484,8 +433,7 @@ function attachClaudePermissionToolUseId(
   }
   return {
     ...next,
-    // Why: Claude emits PermissionRequest without tool_use_id, then reports the
-    // approved command as PostToolUse with the original PreToolUse id.
+    // Why: Claude emits PermissionRequest without tool_use_id, then PostToolUse carries the original PreToolUse id.
     toolUseId: inheritedToolUseId
   }
 }
@@ -494,35 +442,24 @@ export class AgentHookServer {
   private server: ReturnType<typeof createServer> | null = null
   private port = 0
   private token = ''
-  // Why: identifies this Orca instance so hook scripts can stamp requests and
-  // the server can detect dev vs. prod cross-talk. Set at start() from the
-  // caller's knowledge of whether this is a packaged build.
+  // Why: identifies this Orca instance so the server can detect dev vs. prod cross-talk; set at start() from packaged-build knowledge.
   private env = 'production'
   private onAgentStatus: ((payload: EnrichedAgentHookEventPayload) => void) | null = null
   private onPaneStatusCleared: PaneStatusClearListener | null = null
   private statusChangeListeners = new Set<StatusChangeListener>()
-  // Why: directory that holds the on-disk endpoint file. Set via start()'s
-  // `userDataPath` option so the class has no direct Electron dependency
-  // (keeps it mockable in the vitest node environment).
+  // Why: set via start()'s userDataPath so the class has no direct Electron dependency (mockable in vitest node env).
   private endpointDir: string | null = null
   private endpointFilePathCache: string | null = null
   private endpointFileWritten = false
-  // Why: per-instance caches (warn-once Sets, lastPrompt/lastTool/lastStatus
-  // by paneKey). Held on the instance instead of as module-level Maps so
-  // tests can spin up multiple servers without state cross-contamination.
+  // Why: per-instance (not module-level) so tests can spin up multiple servers without state cross-contamination.
   private state: HookListenerState = createHookListenerState()
-  // Why: hydrated last-status rows are useful UI continuity, but they are not
-  // evidence of live agent work in this main-process runtime.
+  // Why: hydrated rows give UI continuity but aren't evidence of live agent work in this runtime.
   private runtimeObservedStatusPaneKeys = new Set<string>()
   private legacyPaneKeyAliases = new Map<string, PaneKeyAliasEntry>()
   private paneKeyAliasPersistenceListener: PaneKeyAliasPersistenceListener | null = null
-  // Why: full path to the on-disk last-status cache. Set in start() from
-  // userDataPath. Null when the server runs without a userDataPath (e.g.
-  // tests that skip the userDataPath option) — in that case, persistence is
-  // a no-op and only in-memory replay applies.
+  // Why: on-disk last-status cache path; null without a userDataPath (tests), where persistence is a no-op and only in-memory replay applies.
   private lastStatusFilePath: string | null = null
-  // Why: trailing-edge debounce timer. Captured per-instance so multiple
-  // server instances in the same process (tests) don't share state.
+  // Why: trailing-edge debounce timer, per-instance so test servers in one process don't share state.
   private statusPersistTimer: ReturnType<typeof setTimeout> | null = null
   private assistantMessageRetryTimers = new Map<string, ReturnType<typeof setTimeout>>()
   private promptSentDedupeByPaneKey = new Map<string, AgentPromptSentDedupeEntry>()
@@ -530,9 +467,7 @@ export class AgentHookServer {
   private closedAgentStatusTabIds = new Set<string>()
   private closedAgentStatusPaneKeys = new Set<string>()
   private connectionTimestampWatermarkById = new Map<string, number>()
-  // Why: identity check — skip writes when the JSON-stringified contents
-  // exactly match the last successful disk write. Cheap protection against
-  // re-firing trailing timers when nothing changed.
+  // Why: skip disk writes when the JSON exactly matches the last write; guards against re-firing trailing timers when nothing changed.
   private lastWrittenJson: string | null = null
 
   setListener(listener: ((payload: EnrichedAgentHookEventPayload) => void) | null): void {
@@ -540,15 +475,10 @@ export class AgentHookServer {
     if (!listener) {
       return
     }
-    // Why: replay is best-effort per pane so one throwing listener call can't
-    // starve subsequent panes from being replayed.
+    // Why: replay is best-effort per pane so one throwing listener can't starve the rest.
     for (const payload of this.state.lastStatusByPaneKey.values()) {
       try {
-        // Why: cache values are stored as enriched payloads (with receivedAt /
-        // stateStartedAt). The map's declared element type from the shared
-        // listener is the bare AgentHookEventPayload because the shared module
-        // never reads from this map; only this class does, and only enriched
-        // values are ever inserted.
+        // Why: cache always holds enriched payloads; the map's declared type is the bare shape only because the shared module never reads it.
         listener({ ...(payload as EnrichedAgentHookEventPayload), isReplay: true })
       } catch (err) {
         console.error('[agent-hooks] replay listener threw', err)
@@ -567,10 +497,8 @@ export class AgentHookServer {
     this.onPaneStatusCleared = listener
   }
 
-  /** Snapshot of the current cached statuses, in the IPC-shaped form the
-   *  renderer consumes. Used by the `agentStatus:getSnapshot` IPC after
-   *  workspace tabs have hydrated, so the dashboard catches up on any
-   *  hook events that fired during startup. */
+  /** Snapshot of cached statuses in IPC shape. Used by `agentStatus:getSnapshot` after tabs hydrate so the
+   *  dashboard catches up on hook events that fired during startup. */
   getStatusSnapshot(): AgentStatusIpcPayload[] {
     return Array.from(this.state.lastStatusByPaneKey.values(), (entry) =>
       toAgentStatusIpcPayload(entry as EnrichedAgentHookEventPayload)
@@ -595,14 +523,11 @@ export class AgentHookServer {
     }
     const payload = existing.payload
     const agentType: AgentType | undefined = payload.agentType
-    // Why: Droid's Ctrl+C does not interrupt the current turn; repeated Ctrl+C
-    // exits the CLI, which is handled by process/PTY lifecycle cleanup.
+    // Why: Droid's Ctrl+C exits the CLI (handled by PTY lifecycle) rather than interrupting the current turn.
     if (agentType === 'droid' && request.intent === 'ctrl-c') {
       return false
     }
-    // Why: these agents use the first Escape as a TUI/editor cancel. A single
-    // Escape can leave the turn running, so only a deliberate double Escape
-    // may infer an interrupted turn.
+    // Why: these agents use the first Escape as a TUI cancel that can leave the turn running; only a double Escape infers an interrupt.
     if (
       (agentType === 'opencode' || agentType === 'copilot') &&
       request.intent === 'plain-escape' &&
@@ -610,9 +535,7 @@ export class AgentHookServer {
     ) {
       return false
     }
-    // Why: input-intent inference is a fallback for a missing final hook. A strict
-    // baseline match keeps a delayed timer from overwriting any newer hook,
-    // including same-millisecond prompt or agent identity changes.
+    // Why: inference is a fallback for a missing final hook; a strict baseline match keeps a delayed timer from clobbering any newer hook.
     if (
       payload.state !== 'working' ||
       !equivalentInterruptAgentType(agentType, request.baselineAgentType) ||
@@ -623,17 +546,12 @@ export class AgentHookServer {
     ) {
       return false
     }
-    // Why: a 'working' pane can be child-driven (lead already idle, background
-    // subagent running). Ctrl+C at the TUI does not stop background children,
-    // so inferring a terminal done here would wrongly retire live child rows;
-    // their own hook events keep the row truthful instead.
+    // Why: a 'working' pane can be child-driven; Ctrl+C doesn't stop background children, so inferring done would retire live child rows.
     if (payload.subagents?.some((subagent) => subagent.state === 'working')) {
       return false
     }
 
-    // Why: keep the listener's Claude lead-turn record in sync — a later
-    // child lifecycle event would otherwise re-emit the stale pre-interrupt
-    // 'working' lead state and resurrect the cancelled pane.
+    // Why: keep the Claude lead-turn record in sync, or a later child event re-emits the stale 'working' state and resurrects the cancelled pane.
     if (agentType === 'claude') {
       markClaudeLeadTurnInterrupted(this.state, existing.paneKey)
     }
@@ -648,8 +566,7 @@ export class AgentHookServer {
         prompt: payload.prompt,
         agentType,
         interrupted: true,
-        // Why: idle children are display state; dropping them on an inferred
-        // interrupt would blank the child rows a later hook would restore.
+        // Why: idle children are display state; dropping them on an inferred interrupt blanks rows a later hook would restore.
         ...(payload.subagents ? { subagents: payload.subagents } : {})
       }
     })
@@ -661,11 +578,8 @@ export class AgentHookServer {
     return true
   }
 
-  /** Guarded fallback for a hook Claude never sends: answering AskUserQuestion
-   *  produces no event, so the amber wait would otherwise linger until the
-   *  agent's next tool or turn end. The renderer reports the submit keystroke;
-   *  this re-validates its baseline against the cached status (a racing real
-   *  hook wins) and synthesizes the post-answer state. */
+  /** Guarded fallback for a hook Claude never sends: answering AskUserQuestion produces no event, so re-validate the
+   *  renderer's baseline against the cached status (a racing real hook wins) and synthesize the post-answer state. */
   inferQuestionAnswered(request: AgentQuestionAnsweredInferenceRequest): boolean {
     if (!isValidPaneKey(request.paneKey)) {
       return false
@@ -677,12 +591,7 @@ export class AgentHookServer {
       return false
     }
     const payload = existing.payload
-    // Why: only Claude's interactive question may clear on typed input. The
-    // tool name is the discriminator, not the hook event — Claude versions
-    // differ on whether the AskUserQuestion wait arrives as PreToolUse or
-    // PermissionRequest. Real permission waits (other tools) stay sticky until
-    // the approved tool resumes — a denied or ignored permission must keep
-    // demanding attention even though approving is also a keystroke.
+    // Why: only Claude's interactive question clears on typed input — tool name (not hook event) discriminates; real permission waits stay sticky.
     if (
       payload.agentType !== 'claude' ||
       payload.state !== 'waiting' ||
@@ -699,9 +608,7 @@ export class AgentHookServer {
     ) {
       return false
     }
-    // Why: sync the listener's lead-turn record too — a later child lifecycle
-    // event would otherwise re-emit the stale waiting state and resurrect the
-    // dismissed question card.
+    // Why: sync the listener's lead-turn record too, or a later child event re-emits the stale waiting state and resurrects the card.
     const restored = clearClaudeAnsweredQuestionWait(this.state, existing.paneKey)
     const inferred = this.applyNormalizedStatus({
       paneKey: existing.paneKey,
@@ -754,8 +661,7 @@ export class AgentHookServer {
   }
 
   private markTabClosedForAgentStatus(tabId: string): void {
-    // Delete-then-add keeps recently closed tabs most-recent so eviction only
-    // sheds the oldest ids, which can no longer receive status events.
+    // Delete-then-add keeps recently closed tabs most-recent so eviction sheds only the oldest ids.
     this.closedAgentStatusTabIds.delete(tabId)
     this.closedAgentStatusTabIds.add(tabId)
     while (this.closedAgentStatusTabIds.size > CLOSED_AGENT_STATUS_TAB_IDS_MAX) {
@@ -881,8 +787,7 @@ export class AgentHookServer {
       promptInteractionKey
     })
     try {
-      // Why: hooks prove the user submitted a turn, but do not know which UI
-      // launched the terminal; keep attribution low-cardinality and conservative.
+      // Why: hooks prove a turn was submitted but not which UI launched the terminal; keep attribution low-cardinality.
       track('agent_prompt_sent', {
         agent_kind: agentKind,
         launch_source: 'unknown',
@@ -901,15 +806,13 @@ export class AgentHookServer {
     const connectionClearWatermark = payload.connectionId
       ? this.connectionTimestampWatermarkById.get(payload.connectionId)
       : undefined
-    // Why: Date.now() can repeat across disconnect and reconnect. A remote
-    // replay must sort strictly after its connection's transient clear.
+    // Why: Date.now() can repeat across reconnect; a remote replay must sort strictly after its connection's transient clear.
     const now = Math.max(Date.now(), (connectionClearWatermark ?? -1) + 1)
     if (payload.connectionId) {
       this.connectionTimestampWatermarkById.set(payload.connectionId, now)
     }
     if (payload.providerSessionOnly) {
-      // Why: Pi session_start must replace stale turn state and survive snapshot
-      // replay, but it must not emit prompt telemetry or a fabricated status.
+      // Why: Pi session_start replaces stale turn state and survives replay, but must not emit prompt telemetry or a fabricated status.
       const enriched = this.attachStatusTiming(payload, now)
       this.clearAssistantMessageRetry(enriched.paneKey)
       this.runtimeObservedStatusPaneKeys.delete(enriched.paneKey)
@@ -953,8 +856,7 @@ export class AgentHookServer {
     if (previous && shouldKeepClaudePermissionVisible(previous, effectivePayload)) {
       return previous
     }
-    // Why: some TUIs can emit a delayed tool/working hook after Ctrl+C already
-    // stopped the turn. Do not let that stale same-turn event resurrect the row.
+    // Why: some TUIs emit a delayed tool/working hook after Ctrl+C stopped the turn; don't let it resurrect the row.
     if (
       previous?.payload.state === 'done' &&
       previous.payload.interrupted === true &&
@@ -1023,8 +925,7 @@ export class AgentHookServer {
     if (!discoveryReady) {
       const discovery = preparePendingGrokResultDiscovery(source, body)
       if (discovery) {
-        // Why: slug-group discovery can outlive the bounded transcript-flush
-        // timers. Its completion must drive the first retry deterministically.
+        // Why: slug-group discovery can outlive the bounded flush timers; its completion must drive the first retry deterministically.
         void discovery
           .then(() => {
             if (this.server) {
@@ -1075,8 +976,7 @@ export class AgentHookServer {
       this.scheduleAssistantMessageRetry(source, body, original, nextAttempt, requireExactOriginal)
       return
     }
-    // Why: some agents POST Stop before their transcript/chat-history line is
-    // flushed. Discovery is event-driven; subsequent content retries stay timed.
+    // Why: some agents POST Stop before their transcript line is flushed; discovery is event-driven, later content retries stay timed.
     this.applyNormalizedStatus(normalized)
   }
 
@@ -1105,8 +1005,7 @@ export class AgentHookServer {
 
   private boundPaneKeyAliases(): void {
     while (this.legacyPaneKeyAliases.size > PANE_KEY_ALIASES_MAX) {
-      // Why: renderer-originated aliases are untrusted process-lifetime state;
-      // insertion-order eviction bounds both memory and per-message cleanup.
+      // Why: renderer-originated aliases are untrusted; insertion-order eviction bounds memory and per-message cleanup.
       const oldestKey = this.legacyPaneKeyAliases.keys().next().value
       if (!oldestKey) {
         break
@@ -1150,8 +1049,7 @@ export class AgentHookServer {
         (ownerPaneKey !== physicalPaneKey && ownsPty(ownerPaneKey, ptyId))
       )
     }
-    // Why: hook status is renderer-originated evidence, not PTY ownership.
-    // ID-less moves are safe only after a prior verified transfer minted an alias.
+    // Why: hook status is renderer evidence, not PTY ownership; ID-less moves are safe only after a verified transfer minted an alias.
     return alias?.authorityVerified === true
   }
 
@@ -1233,8 +1131,7 @@ export class AgentHookServer {
       this.promptSentDedupeByPaneKey.set(toPaneKey, promptDedupe)
     }
     this.clearAssistantMessageRetry(previousOwnerPaneKey)
-    // Why: the live process keeps posting the physical source key after detach;
-    // persist one chain-safe mapping to whichever surface currently owns it.
+    // Why: the live process keeps posting the physical source key after detach; persist a chain-safe mapping to the current owner.
     this.legacyPaneKeyAliases.set(physicalPaneKey, {
       stablePaneKey: toPaneKey,
       ptyId: normalizedPtyId,
@@ -1298,9 +1195,7 @@ export class AgentHookServer {
           clearedStatusPaneKeys.add(entry.stablePaneKey)
         }
         if (shouldClearStablePaneKey) {
-          // Why: after hydrate, legacy rows are stored under the stable key. If
-          // this PTY is later proven dead before ptyPaneKey is rebuilt, alias
-          // cleanup is the only path that can evict that retained status.
+          // Why: hydrated rows live under the stable key; if this PTY dies before ptyPaneKey rebuilds, alias cleanup is the only evictor.
           clearPaneCacheState(this.state, entry.stablePaneKey)
           this.runtimeObservedStatusPaneKeys.delete(entry.stablePaneKey)
           this.promptSentDedupeByPaneKey.delete(entry.stablePaneKey)
@@ -1334,8 +1229,7 @@ export class AgentHookServer {
     if (!stablePaneKey) {
       return body
     }
-    // Why: migrated and detached shells keep posting an immutable physical
-    // pane key; normalize both pane and tab identity to the current owner.
+    // Why: detached shells keep posting the immutable physical pane key; normalize pane and tab identity to the current owner.
     return { ...record, paneKey: stablePaneKey, tabId: parsePaneKey(stablePaneKey)?.tabId }
   }
 
@@ -1388,8 +1282,7 @@ export class AgentHookServer {
     ) {
       return
     }
-    // Why: OSC terminal status is a runtime/model observation, not a hook
-    // prompt boundary. Keep prompt-sent telemetry tied to native hooks.
+    // Why: OSC status is a runtime observation, not a prompt boundary; keep prompt-sent telemetry tied to native hooks.
     this.applyNormalizedStatus({
       paneKey,
       tabId,
@@ -1399,15 +1292,7 @@ export class AgentHookServer {
     })
   }
 
-  /** Ingest a payload that arrived over the relay JSON-RPC channel rather
-   *  than the local HTTP server. `connectionId` is the SshChannelMultiplexer
-   *  identity Orca holds (the wire envelope carries connectionId: null and
-   *  Orca stamps the real value here). The relay has already normalized the
-   *  payload via the shared listener module, but main is still the SSH trust
-   *  boundary: re-run the canonical status normalizer before caching or
-   *  persisting anything. The `env`/`version` fields are forwarded verbatim
-   *  from the agent CLI's POST body on the remote and validated here so the
-   *  warn-once diagnostics fire for real cross-build mismatches. */
+  /** Ingest a payload from the relay JSON-RPC channel (not the local HTTP server); connectionId is stamped here. Main is still the SSH trust boundary, so re-run the canonical normalizer before caching. */
   ingestRemote(
     envelope: {
       paneKey: string
@@ -1429,9 +1314,7 @@ export class AgentHookServer {
     },
     connectionId: string
   ): void {
-    // Why: signature says non-empty, but the wire crosses a trust boundary —
-    // re-check at runtime (and trim) so a whitespace-only or empty
-    // connectionId can't poison caches.
+    // Why: wire crosses a trust boundary — re-check/trim so an empty connectionId can't poison caches.
     if (typeof connectionId !== 'string') {
       return
     }
@@ -1442,9 +1325,7 @@ export class AgentHookServer {
     if (!envelope || typeof envelope.paneKey !== 'string') {
       return
     }
-    // Why: match the listener's HTTP path — `normalizeHookPayload` trims and
-    // length-caps paneKey before caching, so the cache key here must follow
-    // the same rule or remote-vs-local events for the same pane would diverge.
+    // Why: trim paneKey to match the HTTP path, else remote-vs-local events for one pane diverge.
     const physicalPaneKey = envelope.paneKey.trim()
     const paneKey = this.resolvePaneKeyAlias(physicalPaneKey)
     const parsedPaneKey = parsePaneKey(paneKey)
@@ -1464,9 +1345,7 @@ export class AgentHookServer {
     if (envelope.worktreeId !== undefined && typeof envelope.worktreeId !== 'string') {
       return
     }
-    // Why: mirror the HTTP path's `readStringField` behavior — trim and treat
-    // empty-after-trim as undefined rather than letting a literal "" leak
-    // into the event.
+    // Why: mirror the HTTP path's readStringField — trim and treat empty-after-trim as undefined.
     const reportedTabId =
       envelope.tabId !== undefined && envelope.tabId.trim().length > 0
         ? envelope.tabId.trim()
@@ -1508,12 +1387,7 @@ export class AgentHookServer {
         ? envelope.toolAgentType.trim()
         : undefined
     const providerSession = normalizeAgentProviderSession(envelope.providerSession) ?? undefined
-    // Why: the relay is across a trust boundary; re-run the canonical
-    // normalizer on the inner payload so prompt/agentType/toolName/toolInput
-    // length caps, embedded-newline collapse, and the `interrupted`-only-on-
-    // done invariant are enforced here too. Returns null on malformed input
-    // (including invalid state), which subsumes the prior explicit state
-    // check.
+    // Why: relay crosses a trust boundary — re-run the canonical normalizer to enforce caps/invariants (returns null on malformed).
     const normalizedPayload = normalizeAgentStatusPayload(envelope.payload)
     if (!normalizedPayload) {
       return
@@ -1524,9 +1398,7 @@ export class AgentHookServer {
     ) {
       return
     }
-    // Why: run the same warn-once diagnostics the HTTP path runs (cross-build
-    // version mismatch, dev-vs-prod env mismatch). Use `this.env` as the
-    // expected env so the messages match what the local server produces.
+    // Why: run the HTTP path's warn-once version/env-mismatch diagnostics with this.env as expected.
     warnOnHookEnvOrVersionMismatch(this.state, {
       version: envelope.version,
       env: envelope.env,
@@ -1565,9 +1437,7 @@ export class AgentHookServer {
       this.env = options.env
     }
     if (options?.userDataPath) {
-      // Why: dev builds share one userData path, so callers can namespace the
-      // endpoint file by dev instance while packaged builds keep the stable path
-      // that lets long-lived PTYs reconnect after app restart.
+      // Why: dev builds share one userData path; namespace per instance while packaged keeps the stable path for PTY reconnect.
       this.endpointDir = options.endpointNamespace
         ? join(options.userDataPath, 'agent-hooks', options.endpointNamespace)
         : join(options.userDataPath, 'agent-hooks')
@@ -1577,10 +1447,7 @@ export class AgentHookServer {
     this.token = randomUUID()
     this.endpointFileWritten = false
     this.lastWrittenJson = null
-    // Why: hydrate before binding the HTTP listener so any new hook POST
-    // (which goes through state.lastStatusByPaneKey.set) runs against an
-    // already-populated map. The renderer later pulls this map as a snapshot
-    // after workspace tabs are hydrated.
+    // Why: hydrate before binding the listener so an early hook POST runs against a populated map.
     if (this.lastStatusFilePath) {
       this.hydrateLastStatusFromDisk()
     }
@@ -1597,9 +1464,7 @@ export class AgentHookServer {
         return
       }
 
-      // Why: bound request time so a slow/stalled client cannot hold a socket
-      // open indefinitely (slowloris-style). The hook endpoints are local and
-      // should complete in well under a second.
+      // Why: bound request time so a stalled client can't hold a socket open (slowloris).
       req.setTimeout(HOOK_REQUEST_SLOWLORIS_MS, () => {
         req.destroy()
       })
@@ -1625,17 +1490,14 @@ export class AgentHookServer {
         res.writeHead(204)
         res.end()
       } catch {
-        // Why: agent hooks must fail open. The receiver returns success for
-        // malformed payloads so a newer or broken hook never blocks the agent.
+        // Why: fail open — return success on malformed payloads so a broken hook never blocks the agent.
         res.writeHead(204)
         res.end()
       }
     })
 
     await new Promise<void>((resolve, reject) => {
-      // Why: swap the startup error handler on success so a later runtime
-      // error (e.g. EADDRINUSE during rebind, socket errors) doesn't reject
-      // an already-settled promise or crash the main process as unhandled.
+      // Why: swap the startup reject-handler for a logging one so a later runtime 'error' can't crash main as an unhandled event.
       const onStartupError = (err: Error): void => {
         this.server?.off('listening', onListening)
         reject(err)
@@ -1658,11 +1520,7 @@ export class AgentHookServer {
   }
 
   stop(): void {
-    // Why: flush any pending debounced write to disk BEFORE we clear the
-    // in-memory map. Quit-time state must be captured even if the trailing
-    // timer was scheduled but had not yet fired; otherwise a multi-agent
-    // run that ended its last hook event <250 ms before quit would lose
-    // that final delta on relaunch.
+    // Why: flush the pending debounced write before clearing the map, else a hook <250ms before quit is lost on relaunch.
     this.flushStatusPersistSync()
     this.server?.close()
     this.server = null
@@ -1675,9 +1533,7 @@ export class AgentHookServer {
       clearTimeout(timer)
     }
     this.assistantMessageRetryTimers.clear()
-    // Why: intentionally do NOT delete the endpoint file on stop(). A stale
-    // file points at a dead port, which matches the fail-open policy. Unlink
-    // would introduce a TOCTOU race vs. a concurrent Orca instance.
+    // Why: don't unlink the endpoint file — a stale file matches fail-open and avoids a TOCTOU race with a concurrent Orca.
     this.endpointDir = null
     this.endpointFilePathCache = null
     this.endpointFileWritten = false
@@ -1693,13 +1549,7 @@ export class AgentHookServer {
     this.notifyStatusChangeListeners()
   }
 
-  /** Why: invoked from the renderer-driven agentStatus:drop IPC when a user
-   *  dismisses a still-active pane's status row. We must NOT wipe
-   *  lastPromptByPaneKey or lastToolByPaneKey here — the pane's agent may
-   *  still be alive, and the next hook event would otherwise arrive with an
-   *  empty prompt and missing tool snapshot until a fresh UserPromptSubmit
-   *  lands. clearPaneState (which wipes all three caches) is the right shape
-   *  only for PTY-teardown. */
+  /** Drop only the status row (user dismissal); do NOT wipe prompt/tool caches since the pane's agent may still be alive. Use clearPaneState for PTY-teardown. */
   dropStatusEntry(paneKey: string): void {
     if (!this.deleteStatusEntry(paneKey)) {
       return
@@ -1722,8 +1572,7 @@ export class AgentHookServer {
     let statusChanged = false
     for (const [paneKey, rawEntry] of this.state.lastStatusByPaneKey) {
       const entry = rawEntry as EnrichedAgentHookEventPayload
-      // Why: legacy/unstamped rows cannot be safely attributed to one host.
-      // Leave them for normal pane teardown instead of risking cross-host loss.
+      // Why: unstamped rows can't be attributed to one host; leave them for normal pane teardown.
       if (entry.connectionId !== normalizedConnectionId) {
         continue
       }
@@ -1732,14 +1581,11 @@ export class AgentHookServer {
       }
     }
     if (statusChanged) {
-      // Why: one disconnect can own many panes; persist and notify subscribers
-      // once so cleanup cost does not fan out with the pane count.
+      // Why: persist/notify once — one disconnect can own many panes.
       this.scheduleStatusPersist()
       this.notifyStatusChangeListeners()
     }
-    // Why: another host can overwrite the same pane key in main's cache while
-    // renderer still shows this connection's older row. Always send the
-    // connection cutoff, even when no current main entry matched.
+    // Why: always send the cutoff even with no matched entry — another host may have overwritten this pane's row.
     this.onPaneStatusCleared?.({
       transient: true,
       connectionId: normalizedConnectionId,
@@ -1837,10 +1683,7 @@ export class AgentHookServer {
 
   clearPaneState(paneKey: string): void {
     const resolvedPaneKey = this.resolvePaneKeyAlias(paneKey)
-    // Why: only schedule a write when we actually evicted a status entry —
-    // dropping prompt/tool caches for a pane that never produced a hook
-    // event does not change the on-disk file, and skipping the write avoids
-    // re-stat'ing on every dead-pane teardown.
+    // Why: only persist when a status entry was actually evicted; dropping prompt/tool caches doesn't change the file.
     const hadStatus = this.state.lastStatusByPaneKey.has(resolvedPaneKey)
     this.clearAssistantMessageRetry(resolvedPaneKey)
     clearPaneCacheState(this.state, resolvedPaneKey)
@@ -1876,9 +1719,7 @@ export class AgentHookServer {
       ORCA_AGENT_HOOK_ENV: this.env,
       ORCA_AGENT_HOOK_VERSION: ORCA_HOOK_PROTOCOL_VERSION
     }
-    // Why: managed hooks source this file at invocation time. Packaged builds
-    // use a stable file for restart handoff; dev callers pass a per-instance
-    // namespace so parallel `pnpm dev` runs do not steal each other's hooks.
+    // Why: hooks source this file at invocation; dev namespaces it so parallel `pnpm dev` runs don't steal each other's hooks.
     if (this.endpointFileWritten && this.endpointFilePathCache) {
       env.ORCA_AGENT_HOOK_ENDPOINT = this.endpointFilePathCache
     }
@@ -1912,17 +1753,13 @@ export class AgentHookServer {
     if (!this.lastStatusFilePath) {
       return
     }
-    // Why: defensive — keeps hydrate idempotent against repeated start()
-    // calls; production callers always have an empty map here, but a future
-    // re-start path must not silently merge prior-session state.
+    // Why: keep hydrate idempotent so a future re-start path can't merge prior-session state.
     this.state.lastStatusByPaneKey.clear()
     let raw: string
     try {
       raw = readFileSync(this.lastStatusFilePath, 'utf8')
     } catch (err) {
-      // Why: missing file is the common case (first launch).
-      // Other errors (EACCES, etc.) degrade to empty hydration with a single
-      // warn so the dashboard renders normally.
+      // Why: missing file is normal (first launch); other errors degrade to empty hydration + one warn.
       if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
         console.warn('[agent-hooks] failed to read last-status file:', err)
       }
@@ -1956,10 +1793,7 @@ export class AgentHookServer {
     let hydrated = 0
     let dropped = 0
     let prunedLegacyClaudeSubagents = 0
-    // Why: bound disk growth — drop anything older than HYDRATE_MAX_AGE_MS so
-    // entries from worktrees archived weeks ago do not pile up forever. Use
-    // Date.now() once to keep the cutoff consistent across all entries this
-    // tick.
+    // Why: drop entries older than HYDRATE_MAX_AGE_MS to bound disk growth (one Date.now() for a consistent cutoff).
     const ttlCutoff = Date.now() - HYDRATE_MAX_AGE_MS
     for (const [paneKey, rawEntry] of Object.entries(entries)) {
       const resolvedPaneKey = this.resolvePaneKeyAlias(paneKey)
@@ -1977,16 +1811,14 @@ export class AgentHookServer {
         }
         this.state.lastStatusByPaneKey.set(resolvedPaneKey, entry)
         if (entry.connectionId) {
-          // Why: a restarted process can observe an earlier wall clock; seed
-          // transport ordering so new events and clears stay after disk state.
+          // Why: a restart can see an earlier wall clock; seed ordering so new events stay after disk state.
           const previousWatermark = this.connectionTimestampWatermarkById.get(entry.connectionId)
           this.connectionTimestampWatermarkById.set(
             entry.connectionId,
             Math.max(previousWatermark ?? -1, entry.receivedAt)
           )
         }
-        // Why: preserve only working children across restart. Live activity
-        // confirms them; a later complete inventory may reap stale seeds.
+        // Why: seed only working children across restart; a later full inventory reaps stale ones.
         if (entry.payload.subagents) {
           seedClaudeSubagentRosterFromSnapshots(
             this.state,
@@ -2005,14 +1837,10 @@ export class AgentHookServer {
       )
     }
     if (dropped > 0 || prunedLegacyClaudeSubagents > 0) {
-      // Why: persist load-time pruning once so legacy idle rows do not consume
-      // parse/filter work again on every launch.
+      // Why: persist load-time pruning once so legacy idle rows aren't re-parsed every launch.
       this.runStatusPersist()
     } else if (hydrated > 0) {
-      // Why: prime from the raw on-disk bytes (not a re-serialization) so the
-      // dedup is robust against future shape drift in serializeStatusFile.
-      // Only prime when hydration was lossless — if entries were dropped
-      // during sanitize, the in-memory map diverges from the on-disk bytes.
+      // Why: prime dedup from raw bytes (not re-serialized) only when hydration was lossless.
       this.lastWrittenJson = raw
     }
   }
@@ -2020,9 +1848,7 @@ export class AgentHookServer {
   private serializeStatusFile(): string {
     const entries: Record<string, EnrichedAgentHookEventPayload> = {}
     for (const [paneKey, payload] of this.state.lastStatusByPaneKey) {
-      // Why: defensive — never persist invalid keys even if they slipped
-      // into the in-memory map somehow. Same invariant the hydrate path
-      // enforces.
+      // Why: never persist invalid keys (matches the hydrate-path invariant).
       if (!isValidPaneKey(paneKey)) {
         continue
       }
@@ -2037,8 +1863,7 @@ export class AgentHookServer {
     if (!this.lastStatusFilePath) {
       return
     }
-    // Why: each call resets the timer; the disk write fires
-    // STATUS_PERSIST_DEBOUNCE_MS after the LAST event in the burst.
+    // Why: reset the timer each call so the write fires only after the last event in a burst.
     if (this.statusPersistTimer) {
       clearTimeout(this.statusPersistTimer)
     }
@@ -2046,9 +1871,7 @@ export class AgentHookServer {
       this.statusPersistTimer = null
       this.runStatusPersist()
     }, STATUS_PERSIST_DEBOUNCE_MS)
-    // Why: don't keep the event loop alive just for a status flush — quit
-    // already triggers flushStatusPersistSync(). On Node 12+ unref() is a
-    // no-op when called on an already-unref'd timer.
+    // Why: don't keep the event loop alive just for a status flush — quit already flushes sync.
     if (typeof this.statusPersistTimer.unref === 'function') {
       this.statusPersistTimer.unref()
     }
@@ -2100,10 +1923,7 @@ export class AgentHookServer {
     }
   }
 
-  /** Test-only accessor for the per-instance listener state. The `_internals`
-   *  shim needs to reach this without exposing `state` on the public surface
-   *  to renderer/main callers. AGENTS.md disallows `as unknown as X` escapes,
-   *  so we expose a narrow getter rather than casting the private field. */
+  /** Test-only accessor for the per-instance listener state (narrow getter avoids an `as unknown` cast). */
   _getStateForTests(): HookListenerState {
     return this.state
   }
@@ -2121,8 +1941,7 @@ export const agentHookServer = new AgentHookServer()
 
 // Why: exported for test coverage of the per-agent field extractors.
 export const _internals = {
-  // Why: bind the test-helper to the singleton's state so existing tests keep
-  // exercising the same caches the live server uses.
+  // Why: bind the test-helper to the singleton's state so tests exercise the live caches.
   normalizeHookPayload: (
     source: AgentHookSource,
     body: unknown,
diff --git a/src/main/daemon/daemon-host-relocation.ts b/src/main/daemon/daemon-host-relocation.ts
index ac674fdd290..4618fdbdfe5 100644
--- a/src/main/daemon/daemon-host-relocation.ts
+++ b/src/main/daemon/daemon-host-relocation.ts
@@ -14,26 +14,11 @@ import { app } from 'electron'
 import { parseDaemonPidFile, startTimeMatches } from './daemon-health'
 
 /**
- * Relocates the terminal daemon's process image out of the app install
- * directory into userData so it survives Windows auto-updates.
- *
- * Why: the daemon is forked as plain Node via ELECTRON_RUN_AS_NODE, so its
- * image is the install-dir Orca.exe and its loaded modules (node-pty native,
- * ConPTY runtime) map from the install dir. On update, electron-builder's NSIS
- * installer deletes the old install and force-closes every process whose image
- * lives under it — killing the daemon and every live terminal it owns. Copying
- * the daemon's whole file closure to a version-keyed userData dir and forking
- * from that copy takes its image + loaded modules out of the installer's reach.
- *
- * The copy keeps the ELECTRON binary run as node (not stock node.exe): a copy
- * of Orca.exe (renamed to a distinct image name) is byte-identical, so
- * run-as-node behavior — no console flashing, asar-correct — matches the in-dir
- * fork exactly. The win-unpacked layout is mirrored verbatim so
- * require('node-pty') and node-pty's native loader resolve the relocated tree
- * identically to the packaged app.
- *
- * Fail-open everywhere: any failure returns null and the caller forks the
- * install-dir host — the pre-relocation behavior, byte-identical off win32.
+ * Relocate the terminal daemon's process image out of the app install dir into LOCAL userData so it
+ * survives Windows auto-updates: the NSIS installer deletes the old install and force-kills every process
+ * imaged under it, which would otherwise kill the daemon and its live terminals. The relocated exe is a
+ * run-as-node Orca.exe copy (not node.exe) so there's no console flash and asar still resolves. Fail-open:
+ * any failure returns null and the caller forks the install-dir host (pre-relocation behavior).
  */
 
 export type RelocatedDaemonHost = {
@@ -46,22 +31,13 @@ export type RelocatedDaemonHost = {
 const HOST_SUBDIR = 'daemon-host'
 const MARKER_NAME = '.materialized.json'
 
-// The relocated host is machine-specific runtime (~260MB). It must live under
-// LOCAL appData, not the roaming userData dir, so a roaming profile or OneDrive
-// Known-Folder-Move never syncs it (slow login/logout, sync bloat). This folder
-// name is shared verbatim with the NSIS uninstall cleanup
-// (config/nsis/daemon-host-uninstall.nsh), which removes
-// %LOCALAPPDATA%\<LOCAL_HOST_ROOT_NAME>\daemon-host — keep the two in sync.
+// LOCAL appData (not roaming) so OneDrive/roaming never syncs this ~260MB runtime. Shared with NSIS uninstall (config/nsis/daemon-host-uninstall.nsh) — keep in sync.
 const LOCAL_HOST_ROOT_NAME = 'Orca'
 
-// The relocated host exe is a copy of Orca.exe renamed to a distinct image
-// name. The NSIS updater's name-based kill (`taskkill /IM Orca.exe`) matches by
-// image name, so a distinct name spares the daemon from that branch, while the
-// userData path (outside $INSTDIR) spares it from the path-based branch.
+// Copy of Orca.exe renamed to a distinct image name so the NSIS updater's `taskkill /IM Orca.exe` can't match it.
 const DAEMON_HOST_EXE_NAME = 'orca-terminal-daemon.exe'
 
-// V8 snapshots + ICU data the Electron bootstrap reads even under
-// ELECTRON_RUN_AS_NODE; siblings of Orca.exe in win-unpacked.
+// V8 snapshots + ICU data the Electron bootstrap reads even under ELECTRON_RUN_AS_NODE; siblings of Orca.exe.
 const RUNTIME_DATA_FILES = ['icudtl.dat', 'snapshot_blob.bin', 'v8_context_snapshot.bin']
 
 type CopyOp = {
@@ -89,9 +65,7 @@ type MaterializeMarker = {
   entryRelPath: string
 }
 
-// Uses win32 path semantics so Windows layout paths (drive letters, `\`)
-// decompose correctly regardless of host OS — needed for cross-platform unit
-// tests; production runs this on win32 only.
+// win32 path semantics so Windows paths decompose correctly off-win32 in cross-platform unit tests; production runs on win32 only.
 function toPosixRelative(fromDir: string, absPath: string): string {
   return winPath.relative(fromDir, absPath).split(winPath.sep).join('/')
 }
@@ -100,8 +74,7 @@ function destPath(root: string, destRel: string): string {
   return join(root, ...destRel.split('/'))
 }
 
-// Mirror getDaemonEntryPath()'s resolution order (unpacked root first, then
-// out/main) so the copied entry is the exact file the in-dir fork would run.
+// Mirror getDaemonEntryPath()'s resolution order so the copied entry is the exact file the in-dir fork would run.
 function resolveEntrySourcePath(resourcesPath: string): string {
   const unpackedRoot = join(resourcesPath, 'app.asar.unpacked')
   const direct = join(unpackedRoot, 'daemon-entry.js')
@@ -111,8 +84,7 @@ function resolveEntrySourcePath(resourcesPath: string): string {
   return join(unpackedRoot, 'out', 'main', 'daemon-entry.js')
 }
 
-// Discover the relocation inputs from the live packaged process, or null when
-// relocation does not apply (non-win32, dev, or missing resourcesPath).
+// Relocation inputs from the live packaged process, or null when it doesn't apply (non-win32, dev, or missing resourcesPath).
 function collectDaemonHostSources(): DaemonHostSources | null {
   if (process.platform !== 'win32' || !app.isPackaged) {
     return null
@@ -133,12 +105,7 @@ function collectDaemonHostSources(): DaemonHostSources | null {
   }
 }
 
-// node-pty ships debug symbols (.pdb) and a win32 prebuild dir per CPU arch; the
-// run-as-node daemon loads neither the symbols nor any non-host-arch prebuild
-// (verified against the live daemon's loaded module list), so they are filtered
-// out of the copy — the bulk of node-pty's on-disk size. Keyed on the host arch
-// rather than dropping arm64 outright so a future Windows-arm64 build keeps the
-// `win32-arm64` prebuild it actually needs and prunes `win32-x64` instead.
+// Drop node-pty's .pdb symbols and non-host-arch prebuilds (its bulk); keyed on host arch so a future win32-arm64 build keeps the prebuild it needs.
 const HOST_WIN_PREBUILD_DIR = `win32-${process.arch}`.toLowerCase()
 function isRuntimeNodePtyPath(sourcePath: string): boolean {
   const p = sourcePath.toLowerCase()
@@ -151,29 +118,20 @@ function isRuntimeNodePtyPath(sourcePath: string): boolean {
 }
 
 /**
- * The ordered copy plan. Every destRel mirrors the source's win-unpacked
- * relative path so require() and node-pty's native loader resolve the mirror
- * identically to the packaged app. Pure over its inputs so tests can assert the
- * layout without a real build.
+ * The ordered copy plan. Every destRel mirrors the source's win-unpacked relative path so require()
+ * and node-pty's loader resolve the mirror identically to the packaged app. Pure so tests can assert layout.
  */
 export function buildDaemonHostManifest(sources: DaemonHostSources): CopyOp[] {
   const { appDir, execPath, resourcesPath, entrySourcePath, entryRelPath } = sources
   const ops: CopyOp[] = []
 
-  // Electron host binary + V8/ICU data blobs at the dest root. The exe is
-  // renamed to a distinct image name so the NSIS updater's name-based
-  // `taskkill /IM Orca.exe` can't match it; the blobs beside it are read by the
-  // Electron bootstrap by fixed name. Top-level DLLs are deliberately NOT copied
-  // — they are all GPU/graphics/media (swiftshader, vulkan, d3d, dxcompiler,
-  // ffmpeg) that a windowless run-as-node host never loads (verified empirically
-  // against the live daemon's module list), so copying them only wastes ~48MB.
+  // Host exe (renamed) + V8/ICU blobs at dest root. Top-level DLLs omitted: GPU/media libs a windowless run-as-node host never loads (~48MB saved).
   ops.push({ sourcePath: execPath, destRel: DAEMON_HOST_EXE_NAME, kind: 'file' })
   for (const name of RUNTIME_DATA_FILES) {
     ops.push({ sourcePath: join(appDir, name), destRel: name, kind: 'file', optional: true })
   }
 
-  // Daemon bundle: entry + its sibling chunks/ + the unpacked out/package.json
-  // (CJS/ESM loader resolution), mirrored verbatim.
+  // Daemon bundle: entry + sibling chunks/ + out/package.json (CJS/ESM loader resolution), mirrored verbatim.
   ops.push({ sourcePath: entrySourcePath, destRel: entryRelPath, kind: 'file' })
   const chunksDir = join(winPath.dirname(entrySourcePath), 'chunks')
   ops.push({
@@ -190,10 +148,7 @@ export function buildDaemonHostManifest(sources: DaemonHostSources): CopyOp[] {
     optional: true
   })
 
-  // node-pty package tree (native conpty.node + conpty/ runtime dir). It is a
-  // sibling of app.asar.unpacked; require('node-pty') resolves it by walking up
-  // from the mirrored daemon-entry dir to resources/node_modules. Filtered to
-  // drop .pdb debug symbols and other-arch prebuilds the host never loads.
+  // node-pty tree, mirrored so require('node-pty') resolves it; filtered to drop unused .pdb/other-arch prebuilds.
   const nodePtyDir = join(resourcesPath, 'node_modules', 'node-pty')
   ops.push({
     sourcePath: nodePtyDir,
@@ -245,9 +200,7 @@ function readMarker(dir: string): MaterializeMarker | null {
 }
 
 function hostRootDir(): string {
-  // Prefer LOCAL appData (see LOCAL_HOST_ROOT_NAME). Fall back to userData only
-  // if LOCALAPPDATA is somehow unset — a no-op off win32, where relocation never
-  // runs anyway; on win32 packaged the env var is always present.
+  // Prefer LOCAL appData (see LOCAL_HOST_ROOT_NAME); fall back to userData only if LOCALAPPDATA is unset.
   const localAppData = process.env.LOCALAPPDATA
   const base =
     typeof localAppData === 'string' && localAppData.length > 0
@@ -257,9 +210,8 @@ function hostRootDir(): string {
 }
 
 /**
- * Cheap idempotency check: the relocated host for the current version, or null.
- * Valid only when the marker matches this version AND the exe + entry exist, so
- * a partial or stale copy never reports ready.
+ * The relocated host for the current version, or null. Valid only when the marker matches this version
+ * AND the exe + entry exist, so a partial or stale copy never reports ready.
  */
 export function getRelocatedDaemonHost(): RelocatedDaemonHost | null {
   const sources = collectDaemonHostSources()
@@ -281,11 +233,8 @@ export function getRelocatedDaemonHost(): RelocatedDaemonHost | null {
 }
 
 /**
- * Ensure the current version's daemon host is materialized under
- * userData/daemon-host/<version>, returning its fork paths or null (fail-open).
- * Idempotent: a valid marker for this version short-circuits without recopying.
- * The copy stages into a temp sibling and is published by atomic rename, so a
- * crash mid-copy never leaves a half-populated dest.
+ * Materialize the current version's daemon host, returning its fork paths or null (fail-open). Idempotent
+ * via marker; stages into a temp sibling and publishes by atomic rename, so a crash mid-copy never leaves a half-populated dest.
  */
 export function materializeRelocatedDaemonHost(): RelocatedDaemonHost | null {
   const existing = getRelocatedDaemonHost()
@@ -304,8 +253,7 @@ export function materializeRelocatedDaemonHost(): RelocatedDaemonHost | null {
     mkdirSync(root, { recursive: true })
     rmSync(staging, { recursive: true, force: true })
     executeManifest(buildDaemonHostManifest(sources), staging)
-    // Marker written LAST: an interrupted copy leaves a marker-less staging dir
-    // that the next launch discards, never a dest the cheap check trusts.
+    // Marker written LAST so an interrupted copy leaves a marker-less staging dir the next launch discards.
     const marker: MaterializeMarker = {
       version,
       completedAt: new Date().toISOString(),
@@ -336,10 +284,8 @@ function isDaemonPidAlive(pid: number, startedAtMs: number | null): boolean {
 }
 
 /**
- * App versions still pinned by a live daemon, read from the daemon-v<N>.pid
- * files under `runtimeDir`. A surviving daemon runs from its version's host dir,
- * so its dir must never be reclaimed while the process is alive. On win32 the
- * start-time check cannot verify, so a matching pid pins conservatively.
+ * App versions still pinned by a live daemon (from daemon-v<N>.pid files under `runtimeDir`), whose
+ * host dir must not be reclaimed while alive. On win32 start-time can't verify, so a matching pid pins conservatively.
  */
 export function collectPinnedDaemonVersions(runtimeDir: string): Set<string> {
   const pinned = new Set<string>()
@@ -359,8 +305,7 @@ export function collectPinnedDaemonVersions(runtimeDir: string): Set<string> {
     } catch {
       continue
     }
-    // appVersion null => a pre-relocation daemon forked from the install dir,
-    // which pins no host dir here.
+    // appVersion null => pre-relocation daemon forked from the install dir; pins no host dir here.
     if (parsed && parsed.appVersion !== null && isDaemonPidAlive(parsed.pid, parsed.startedAtMs)) {
       pinned.add(parsed.appVersion)
     }
@@ -369,9 +314,8 @@ export function collectPinnedDaemonVersions(runtimeDir: string): Set<string> {
 }
 
 /**
- * Reclaim daemon-host/<ver> dirs whose ver is neither the current version nor
- * pinned by a live daemon. Best-effort — never throws; a still-locked or
- * concurrently-staging dir is simply retried on a future launch.
+ * Reclaim daemon-host/<ver> dirs that are neither the current version nor pinned by a live daemon.
+ * Best-effort — never throws; a locked/staging dir is retried on a future launch.
  */
 export function pruneOldDaemonHosts(pinnedVersions: ReadonlySet<string>): void {
   if (process.platform !== 'win32' || !app.isPackaged) {
diff --git a/src/main/daemon/daemon-init.test.ts b/src/main/daemon/daemon-init.test.ts
index 9bc78a4da75..d6b0da6327f 100644
--- a/src/main/daemon/daemon-init.test.ts
+++ b/src/main/daemon/daemon-init.test.ts
@@ -1,9 +1,4 @@
-/* eslint-disable max-lines -- Why: this file covers the entire restart flow
-   of daemon-init — construction, the 7-step sequence from
-   docs/daemon-staleness-ux.md §Phase 1, and the concurrency coalescer. A
-   single describe block with shared mocks keeps setup in one place; splitting
-   across files would duplicate the vi.hoisted boundary mocks with no cleaner
-   ownership seam. */
+/* eslint-disable max-lines -- Why: covers daemon-init's full restart flow (7-step sequence per docs/daemon-staleness-ux.md §Phase 1 + coalescer); one describe block keeps shared mocks in one place. */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from './types'
@@ -15,11 +10,7 @@ const FAKE_APP_PATH = '/fake/app'
 const FAKE_APP_OUT_MAIN_PATH = join(FAKE_APP_PATH, 'out', 'main')
 const FAKE_DAEMON_ENTRY_PATH = join(FAKE_APP_OUT_MAIN_PATH, 'daemon-entry.js')
 
-// Why: the restart flow touches many boundary modules (electron app paths, fs
-// for dir creation, net for socket probe, DaemonClient over that socket, the
-// spawner's launcher, ipc/pty listener binders). We only care here about the
-// observable sequencing and identity invariants of runRestartDaemon, so every
-// non-daemon-init dependency is replaced by a minimal stub that records calls.
+// Why: we only care about runRestartDaemon's observable sequencing/identity invariants, so every non-daemon-init dependency is a minimal stub.
 const {
   getPathMock,
   getAppPathMock,
@@ -61,21 +52,14 @@ const {
 
   const probeSocketExistsMock = vi.fn((_path?: string) => false)
   const writeFileSyncMock = vi.fn()
-  // Why: readFileSync throws by default so legacyDaemonProcessMayBeAlive's
-  // catch treats every legacy pid file as unreadable — matching the pre-fix
-  // cleanup behavior every existing test was written against.
+  // Why: readFileSync throws by default so legacyDaemonProcessMayBeAlive treats every legacy pid file as unreadable (pre-fix cleanup behavior).
   const readFileSyncMock = vi.fn((): string => {
     throw new Error('ENOENT')
   })
   const unlinkSyncMock = vi.fn()
   const forkMock = vi.fn()
   const netConnectMock = vi.fn(() => {
-    // Why: the real probeSocket() in daemon-init connects to the socket and
-    // resolves true on 'connect', false on 'error'. Our launcher never runs
-    // in these tests (healthCheckDaemon short-circuits), but probeSocket is
-    // also invoked by cleanupDaemonForProtocol — stub the socket object so
-    // the 'error' path fires synchronously and cleanupDaemonForProtocol's
-    // alive=false branch runs without side effects.
+    // Why: stub the socket so probeSocket's 'error' path fires and cleanupDaemonForProtocol's alive=false branch runs without side effects.
     const handlers: Record<string, (() => void)[]> = { connect: [], error: [] }
     return {
       on(event: string, cb: () => void) {
@@ -114,8 +98,7 @@ const {
     }
   })
 
-  // Why: every DaemonSpawner constructed under test pushes into this array so
-  // assertions can check "was the *same* spawner reused across restart?".
+  // Why: every DaemonSpawner pushes here so assertions can check the *same* spawner was reused across restart.
   const spawnerInstances: MockSpawner[] = []
   const ensureRunningOverrides: (() => Promise<{
     socketPath: string
@@ -126,11 +109,9 @@ const {
   const lifecycleLeaseErrors: Error[] = []
   const disconnectOnlyErrors: Error[] = []
   const routerSubscriptionError: { current: Error | null } = { current: null }
-  // Same for DaemonPtyAdapter. The test asserts the replacement adapter is a
-  // fresh instance whose respawn closure targets the *original* spawner.
+  // Same for DaemonPtyAdapter — tests assert the replacement adapter is fresh but its respawn closure targets the *original* spawner.
   const adapterInstances: MockAdapter[] = []
-  // Why: adapters are constructed inside initDaemonPtyProvider, so tests that
-  // need listSessions to report live sessions set this before calling init.
+  // Why: adapters are built inside initDaemonPtyProvider, so tests set this before init to make listSessions report live sessions.
   const defaultListSessionsSessions: { sessionId: string }[] = []
   const listProcessesControl: {
     current: null | (() => Promise<{ sessionId: string }[]>)
@@ -231,10 +212,7 @@ type MockAdapter = {
   disconnectOnly: ReturnType<typeof vi.fn>
   onData: ReturnType<typeof vi.fn>
   onExit: ReturnType<typeof vi.fn>
-  // Why: MockAdapter is fed through `new DaemonPtyRouter({ current, legacy })`
-  // during the "legacy preservation" test. The real router calls onData/onExit
-  // on each adapter; our stub returns a no-op unsubscribe so the router can
-  // subscribe without exploding.
+  // Why: the router calls onData/onExit on each adapter; the stub returns a no-op unsubscribe so router subscription doesn't explode.
   callOrder: string[]
 }
 
@@ -291,9 +269,7 @@ vi.mock('./daemon-spawner', () => ({
       this.launcher = opts.launcher
       this.socketCounter = 0
       this.handle = null
-      // Why: each ensureRunning bumps a counter into the returned socketPath
-      // so the test can verify the *replacement* adapter is constructed with
-      // info from the second ensureRunning call, not stale info from the first.
+      // Why: each ensureRunning bumps a counter into socketPath so tests can tell the replacement adapter used the second call, not the first.
       this.ensureRunning = vi.fn(async () => {
         const override = ensureRunningOverrides.shift()
         if (override) {
@@ -451,10 +427,7 @@ async function importFresh() {
   unlinkOwnedDaemonPidFileMock.mockReturnValue(true)
   getProcessStartedAtMsMock.mockReset()
   getProcessStartedAtMsMock.mockReturnValue(1_000_000)
-  // Why: importing daemon-init *after* resetModules means the module-level
-  // `spawner`/`adapter`/`restartInFlight` start fresh for every test, which is
-  // the only way to reliably exercise the "first-time init" path and the
-  // coalescer independently.
+  // Why: import after resetModules so module-level spawner/adapter/restartInFlight start fresh — needed to test first-init and the coalescer.
   return import('./daemon-init')
 }
 
@@ -552,8 +525,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
 
   it('prunes seeded Claude live-PTY ids against daemon sessions after init', async () => {
     const mod = await importFresh()
-    // Why: live-pty-gate is intentionally unmocked — import from the same fresh
-    // module registry so the module-level gate state matches daemon-init's.
+    // Why: live-pty-gate is intentionally unmocked — import from the same fresh registry so gate state matches daemon-init's.
     const gate = await import('../claude-accounts/live-pty-gate')
     defaultListSessionsSessions.push({ sessionId: 'claude-alive' })
     gate.seedLiveClaudePtysFromPersistence(['claude-alive', 'claude-dead'])
@@ -563,8 +535,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       expect(gate.hasLiveClaudePtys()).toBe(true)
 
       gate.markClaudePtyExited('claude-alive')
-      // Why: proves 'claude-dead' was released by the daemon reconcile — the
-      // surviving session was the only id still holding the gate.
+      // Why: proves 'claude-dead' was released by the daemon reconcile — the surviving session held the gate alone.
       expect(gate.hasLiveClaudePtys()).toBe(false)
     } finally {
       gate.markClaudePtyExited('claude-alive')
@@ -714,11 +685,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     const mod = await importFresh()
     await mod.initDaemonPtyProvider()
 
-    // Why: seed the original adapter with active sessions so
-    // fanoutSyntheticExits has something to do. The real adapter snapshots
-    // activeSessionIds then clears it; the mock emulates that so a regression
-    // that measures killedCount *after* fanout (when the set is empty) would
-    // surface as `killedCount === 0` here.
+    // Why: seed active sessions and mock the snapshot-then-clear so a regression measuring killedCount *after* fanout surfaces as 0.
     const originalAdapter = adapterInstances[0]
     let activeIds = ['sess-a', 'sess-b', 'sess-c']
     originalAdapter.getActiveSessionIds.mockImplementation(() => [...activeIds])
@@ -734,13 +701,10 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
 
     const result = await mod.restartDaemon()
 
-    // killedCount must be 3 — proves the count was taken *before* the fanout
-    // cleared the set. A bug that swapped these two lines in source would
-    // report 0 here.
+    // killedCount must be 3 — proves the count was taken *before* fanout cleared the set (a swapped-order bug reports 0).
     expect(result.killedCount).toBe(3)
     expect(originalAdapter.fanoutSyntheticExits).toHaveBeenCalledWith(-1)
-    // The load-bearing ordering invariant: the synthetic exits must reach
-    // the renderer *before* listeners are torn down. Step 1 before Step 2.
+    // Ordering invariant: synthetic exits must reach the renderer *before* listeners are torn down (Step 1 before 2).
     expect(order).toEqual(['fanout', 'unbind'])
   })
 
@@ -835,9 +799,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     expect(replacementAdapter.options.socketPath).toBe('/fake/socket-2')
     expect(replacementAdapter.options.tokenPath).toBe('/fake/token-2')
 
-    // Invoking the replacement adapter's respawn closure must drive the
-    // *same* original spawner (matches the crash-respawn closure baked into
-    // the first adapter — see daemon-init.ts step 5 comment).
+    // The replacement adapter's respawn closure must drive the *same* original spawner (see daemon-init.ts step 5).
     originalSpawner.resetHandle.mockClear()
     originalSpawner.ensureRunning.mockClear()
     await replacementAdapter.options.respawn?.()
@@ -865,8 +827,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     expect(setLocalPtyProviderMock.mock.calls[1][0]).toBe(replacementAdapter)
     expect(mod.getDaemonProvider()).toBe(replacementAdapter)
 
-    // Step 7: rebind must run *after* Step 6. The last rebind call index
-    // must be greater than the last setLocalPtyProvider call index.
+    // Step 7: rebind must run *after* Step 6 (the provider swap).
     const rebindOrder = rebindLocalProviderListenersMock.mock.invocationCallOrder.at(-1) ?? -1
     const swapOrder = setLocalPtyProviderMock.mock.invocationCallOrder.at(-1) ?? -1
     expect(rebindOrder).toBeGreaterThan(swapOrder)
@@ -875,19 +836,12 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
   it('preserves legacy adapter instances by identity, drains outgoing router via disposeRouterOnly, and re-discovers legacy sessions on the new router', async () => {
     const mod = await importFresh()
 
-    // Why: initDaemonPtyProvider only constructs legacy adapters when
-    // probeSocket returns true for a legacy socket path. The real flow runs
-    // createLegacyDaemonAdapters which calls probeSocket per previous version.
-    // Simplest seam for this test: directly construct a router with a legacy
-    // adapter and install it via replaceDaemonProvider, bypassing
-    // createLegacyDaemonAdapters' socket-probe machinery.
+    // Why: bypass createLegacyDaemonAdapters' socket-probe machinery — directly construct a router with a legacy adapter and install it.
     await mod.initDaemonPtyProvider()
 
     const { DaemonPtyRouter } = await import('./daemon-pty-router')
     const { DaemonPtyAdapter } = await import('./daemon-pty-adapter')
     const currentAtConstruction = adapterInstances[0]
-    // Construct a legacy adapter using the mocked constructor (pushes into
-    // adapterInstances) — index 1.
     const legacyAdapter = new DaemonPtyAdapter({
       socketPath: '/fake/legacy.sock',
       tokenPath: '/fake/legacy.token',
@@ -897,9 +851,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       current: currentAtConstruction as unknown as InstanceType<typeof DaemonPtyAdapter>,
       legacy: [legacyAdapter as unknown as InstanceType<typeof DaemonPtyAdapter>]
     })
-    // Why: spy on the *outgoing* router's disposeRouterOnly so we can prove it
-    // was invoked (not just that legacy adapters survived — a no-op
-    // disposeRouterOnly would leak listeners but still leave adapters alive).
+    // Why: spy on the outgoing router's disposeRouterOnly — adapter survival alone wouldn't catch a no-op that leaks listeners.
     const disposeRouterOnlySpy = vi.spyOn(routerWithLegacy, 'disposeRouterOnly')
     const oldRouterDispose = vi.spyOn(routerWithLegacy, 'dispose')
     mod.replaceDaemonProvider(routerWithLegacy)
@@ -911,22 +863,18 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     const newRouter = provider as InstanceType<typeof DaemonPtyRouter>
     expect(newRouter).not.toBe(routerWithLegacy)
 
-    // Legacy adapter instance is preserved by identity — not reconstructed,
-    // not defensively copied, not disposed.
+    // Legacy adapter is preserved by identity — not reconstructed, copied, or disposed.
     const legacies = newRouter.getLegacyAdapters()
     expect(legacies).toHaveLength(1)
     expect(legacies[0]).toBe(legacyAdapter)
     expect(legacyAdapter.dispose).not.toHaveBeenCalled()
-    // The outgoing router was drained via disposeRouterOnly (router-only
-    // teardown), so legacy adapters' underlying connections are untouched.
+    // Router drained via disposeRouterOnly (router-only teardown), so legacy adapters' connections are untouched.
     expect(legacyAdapter.disconnectOnly).not.toHaveBeenCalled()
-    // The outgoing router's subscriptions were drained but the adapters
-    // behind it were NOT disposed — that's the whole point of disposeRouterOnly.
+    // disposeRouterOnly drained subscriptions but did NOT dispose the adapters behind it.
     expect(disposeRouterOnlySpy).toHaveBeenCalledTimes(1)
     expect(oldRouterDispose).not.toHaveBeenCalled()
 
-    // The replacement router must re-run discovery so spawns targeting a
-    // surviving legacy sessionId still route to the legacy adapter.
+    // The replacement router re-runs discovery so spawns for a surviving legacy sessionId still route to the legacy adapter.
     expect(legacyAdapter.listProcesses).toHaveBeenCalled()
   })
 
@@ -962,8 +910,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     const mod = await importFresh()
     await mod.initDaemonPtyProvider()
 
-    // initDaemonPtyProvider sets up a bare adapter when createLegacyDaemonAdapters
-    // finds nothing — confirm that shape persists across restart.
+    // initDaemonPtyProvider yields a bare adapter when no legacy adapters exist — confirm that shape persists across restart.
     const { DaemonPtyAdapter } = await import('./daemon-pty-adapter')
     const { DaemonPtyRouter } = await import('./daemon-pty-router')
     expect(mod.getDaemonProvider()).toBeInstanceOf(DaemonPtyAdapter)
@@ -981,15 +928,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     const originalSpawner = spawnerInstances[0]
     const originalAdapter = adapterInstances[0]
 
-    // Build an ordered trace by stamping each step as it fires. Cleanup is
-    // the tricky one — it's the `cleanupDaemonForProtocol` call, observable
-    // via the probeSocket→healthCheckDaemon→killStaleDaemon branch. We use
-    // healthCheckDaemon as the cleanup-start marker because it's the first
-    // call inside createOutOfProcessLauncher → and also fires inside
-    // cleanupDaemonForProtocol's alive branch… actually in the default
-    // (probeSocket=false) path cleanup is a no-op beyond pid-unlink. The
-    // load-bearing observable is `resetHandle` — it fires *after* cleanup
-    // returns. So we instrument the spawner instead.
+    // Build an ordered trace by stamping each step; cleanup has no observable in the default probeSocket=false path, so instrument resetHandle instead.
     const trace: string[] = []
     originalAdapter.fanoutSyntheticExits.mockImplementation(() => trace.push('fanout'))
     unbindLocalProviderListenersMock.mockImplementation(() => trace.push('unbind'))
@@ -1008,11 +947,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     await mod.restartDaemon()
     void originalEnsureRunning // keep ref so tslint doesn't complain
 
-    // The full 7-step sequence in order. Step 3 (cleanupDaemonForProtocol)
-    // has no unique observable in the dead-socket branch, so it's implicitly
-    // ordered by the fact that resetHandle runs after unbind; if cleanup
-    // ever moved *after* resetHandle, we'd see `resetHandle` precede its
-    // expected position.
+    // Full 7-step order; Step 3 (cleanup) has no observable in the dead-socket branch, so it's pinned implicitly by resetHandle running after unbind.
     expect(trace).toEqual([
       'fanout',
       'unbind',
@@ -1022,10 +957,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       'rebind'
     ])
 
-    // A fresh adapter must have been constructed *between* ensureRunning
-    // and replaceProvider (Step 5 before Step 6). adapterInstances[1] is
-    // the replacement — its socketPath comes from the Step-4 ensureRunning
-    // result, so its existence proves the ordering.
+    // A fresh adapter built between ensureRunning and replaceProvider (Step 5 before 6); its Step-4 socketPath proves the ordering.
     expect(adapterInstances).toHaveLength(2)
     expect(adapterInstances[1].options.socketPath).toBe('/fake/socket-2')
     expect(adapterInstances[1].establishLifecycleLease).toHaveBeenCalledOnce()
@@ -1035,12 +967,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
   })
 
   it('exercises the alive-daemon cleanup path: issues shutdown RPC via DaemonClient before spawning a replacement', async () => {
-    // Why: the default mock has probeSocket returning false, so Step 3's
-    // DaemonClient-based shutdown path is normally skipped. This test flips
-    // the socket to "alive" so cleanupDaemonForProtocol takes the
-    // client.ensureConnected → listSessions → shutdown RPC branch. Without
-    // this, the design doc's Risks section ("verify under both 'shutdown
-    // RPC succeeded' and 'fell back to killStaleDaemon' paths") is uncovered.
+    // Why: default probeSocket=false skips Step 3's shutdown RPC; flip the socket "alive" to cover the shutdown-RPC-succeeded branch.
 
     const requestMock = vi.fn(async (method: string) => {
       if (method === 'listSessions') {
@@ -1061,8 +988,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       }
     })
 
-    // Make probeSocket return true for the current-version path by toggling
-    // both the fs.existsSync proxy AND net.connect resolving "alive".
+    // Make probeSocket return true: needs both the fs.existsSync proxy AND net.connect resolving "alive".
     probeSocketExistsMock.mockReturnValue(true)
     netConnectMock.mockImplementationOnce(() => {
       const handlers: Record<string, (() => void)[]> = { connect: [], error: [] }
@@ -1139,13 +1065,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
 
     const originalSpawner = spawnerInstances[0]
 
-    // Why: without an explicit gate, `Promise.all([restartDaemon(),
-    // restartDaemon()])` evaluates arguments left-to-right *synchronously* —
-    // the first call's promise could resolve before the second invocation
-    // begins if all internal awaits resolved in a single microtask, which
-    // would leave the coalescer untested. The deferred gate holds the first
-    // restart inside `ensureRunning` until we release it, guaranteeing the
-    // second call enters while the first is genuinely mid-flight.
+    // Why: the deferred gate holds the first restart inside ensureRunning so the second call provably enters while the first is mid-flight.
     let markEnsureRunningEntered: (() => void) | undefined
     const ensureRunningEntered = new Promise<void>((resolve) => {
       markEnsureRunningEntered = resolve
@@ -1164,33 +1084,21 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     await ensureRunningEntered
     const call2 = mod.restartDaemon()
 
-    // Why: `async function restartDaemon` wraps each return in a fresh
-    // Promise, so `call1 === call2` does *not* hold even when the coalescer
-    // is working. The load-bearing proof is behavioral: while call1 is
-    // blocked on the ensureRunning barrier, call2 must NOT fork a parallel
-    // run of the 7-step sequence. If the coalescer fails, a second
-    // `runRestartDaemon` starts, which means a second `resetHandle` fires
-    // before we release the barrier. Check that counter at this exact
-    // moment — a non-coalescing implementation would already be at 2.
+    // Why: restartDaemon wraps each return in a fresh Promise, so call1===call2 can't prove coalescing; instead assert resetHandle stayed at 1 mid-flight.
     expect(originalSpawner.resetHandle).toHaveBeenCalledTimes(1)
     expect(adapterInstances).toHaveLength(1)
 
     releaseEnsureRunning?.()
     const [r1, r2] = await Promise.all([call1, call2])
-    // Both resolved values must be structurally identical (same result
-    // object bubbled up through the shared runRestartDaemon promise).
+    // Both resolved values are structurally identical — same result bubbled up through the shared runRestartDaemon promise.
     expect(r1).toEqual(r2)
 
-    // resetHandle fires once per restart; ensureRunning fires once during
-    // init + once during restart. A second, un-coalesced restart would push
-    // these counters to 2 and 3 respectively.
+    // resetHandle=1/restart, ensureRunning=1 init+1 restart; an un-coalesced second restart would push these to 2 and 3.
     expect(originalSpawner.resetHandle).toHaveBeenCalledTimes(1)
     expect(originalSpawner.ensureRunning).toHaveBeenCalledTimes(2)
     expect(adapterInstances).toHaveLength(2)
 
-    // After the in-flight promise settles, a fresh restart is allowed to run
-    // — proves `.finally(() => restartInFlight = null)` actually cleared the
-    // slot. A stale restartInFlight would skip the work entirely.
+    // After the in-flight promise settles, a fresh restart runs — proves .finally cleared restartInFlight (a stale slot would skip work).
     await mod.restartDaemon()
     expect(originalSpawner.resetHandle).toHaveBeenCalledTimes(2)
     expect(adapterInstances).toHaveLength(3)
@@ -2077,8 +1985,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       on(event: string, cb: (arg?: unknown) => void) {
         handlers[event]?.push(cb)
         if (event === 'exit') {
-          // Why: deliver the stderr tail before the exit so the failure path
-          // sees the captured crash reason, mirroring a module-load crash.
+          // Why: deliver the stderr tail before exit so the failure path sees the crash reason (mirrors a module-load crash).
           queueMicrotask(() => {
             for (const dataCb of stderrDataCbs.slice()) {
               dataCb(Buffer.from("Error: Cannot find module 'electron'\n"))
@@ -2103,8 +2010,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     expect(error).toBeInstanceOf(Error)
     expect((error as Error).message).toMatch(/Cannot find module 'electron'/)
     expect((error as Error).message).toMatch(/Daemon stderr \(tail\)/)
-    // Why: the piped stderr must be released so the detached daemon does not
-    // keep the parent event loop alive after the failure.
+    // Why: release the piped stderr so the detached daemon can't keep the parent event loop alive after failure.
     expect(stderrDestroy).toHaveBeenCalled()
   })
 
@@ -2277,8 +2183,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     expect(forkMock).toHaveBeenCalled()
   })
 
-  // Why: a net.connect stub whose 'connect' fires — makes probeSocket() report
-  // the wedged daemon's pipe as alive on every grace re-check.
+  // Why: net.connect stub whose 'connect' fires, so probeSocket() reports the pipe alive on every grace re-check.
   function stubAliveSocketConnect() {
     const handlers: Record<string, (() => void)[]> = { connect: [], error: [] }
     return {
@@ -2298,15 +2203,11 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
   }
 
   it('adopts a transiently wedged daemon that drains and reports live sessions within the grace window', async () => {
-    // Why: the Windows update-relaunch case — post-install disk/AV load wedges
-    // the daemon past the first hello budget, but it drains within seconds and
-    // still owns live sessions. The launcher must give it a bounded grace and
-    // ADOPT it rather than killing its live sessions.
+    // Why: Windows update-relaunch — post-install load wedges the daemon briefly; it still owns live sessions, so grace-adopt not kill.
     const mod = await importFresh()
     await mod.initDaemonPtyProvider()
 
-    // First probe times out (still draining); the retry within the grace
-    // window succeeds and reports a live session.
+    // First probe times out (still draining); the retry within grace succeeds with a live session.
     daemonClientMock.mockImplementationOnce(function MockDaemonClient() {
       return {
         ensureConnected: vi.fn(async () => {
@@ -2339,11 +2240,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
   })
 
   it('replaces a permanently wedged daemon after the grace window is exhausted (#8689)', async () => {
-    // Why: a daemon whose socket keeps accepting connections but whose event
-    // loop never answers hello would, under the old code, be preserved forever
-    // — every terminal spawn then failed with "Hello response timed out" with
-    // no recovery. After the bounded grace it must be replaced so the app gets
-    // working terminals again.
+    // Why: a socket that accepts connections but never answers hello was preserved forever (#8689); after grace it must be replaced.
     const mod = await importFresh()
     await mod.initDaemonPtyProvider()
 
@@ -2354,8 +2251,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
         disconnect: vi.fn()
       }
     }
-    // Every probe across the whole grace window times out (permanent wedge),
-    // then the freshly spawned daemon accepts the temporary adoption lease.
+    // Permanent wedge: every probe times out, then the freshly spawned daemon accepts the temporary adoption lease.
     let daemonClientConstructionCount = 0
     daemonClientMock.mockImplementation(function MockDaemonClient() {
       daemonClientConstructionCount++
@@ -2404,30 +2300,21 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
         '/fake/token'
       )
       expect(forkMock).toHaveBeenCalled()
-      // The launcher probes the full grace budget before giving up: 1 initial
-      // probe + WEDGED_DAEMON_GRACE_RETRIES retries.
+      // The launcher probes the full grace budget: 1 initial probe + WEDGED_DAEMON_GRACE_RETRIES retries.
       expect(daemonClientMock).toHaveBeenCalledTimes(3 + WEDGED_DAEMON_GRACE_RETRIES)
     } finally {
-      // Restore the answering default so the persistent throwing impl above
-      // does not leak into later tests (clearAllMocks clears calls, not impls).
+      // Restore the answering default: clearAllMocks clears calls not impls, so the throwing impl would leak into later tests.
       daemonClientMock.mockImplementation(answeringDefault)
     }
   })
 
   it('grace budget is generous enough to ride out a ~60s transient wedge', () => {
-    // Why: pins the magnitude. Each probe waits out the client's 5s hello
-    // timeout, so 1 + 11 probes ≈ 60s of drain grace. Shrinking this narrows
-    // the window in which a transiently wedged daemon's live sessions are
-    // preserved instead of replaced — don't cut it without field telemetry.
+    // Why: each probe waits the client's 5s hello timeout, so 1 + 11 probes ≈ 60s of drain grace; don't cut without telemetry.
     expect(WEDGED_DAEMON_GRACE_RETRIES).toBeGreaterThanOrEqual(11)
   })
 
   it('preserves a daemon that stays wedged until the LAST allowed grace retry', async () => {
-    // Why: exercises the full grace loop end-to-end. The daemon throws on every
-    // probe except the final allowed one (1 + WEDGED_DAEMON_GRACE_RETRIES), on
-    // which it drains and reports a live session — so it must be preserved, not
-    // replaced. Cutting the retry budget below the drain point would replace a
-    // still-live daemon, which this test catches.
+    // Why: daemon drains only on the last allowed probe (1 + WEDGED_DAEMON_GRACE_RETRIES) — must be preserved, not replaced.
     const mod = await importFresh()
     await mod.initDaemonPtyProvider()
 
@@ -2474,9 +2361,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
   })
 
   it('replaces a hello-rejected daemon even though its pipe accepts connections', async () => {
-    // Why: 'rejected' means the daemon answered and refused the handshake —
-    // it can never be adopted, so keeping it alive would strand the app with
-    // no terminals forever. Replacement stays the only recovery.
+    // Why: 'rejected' = daemon refused the handshake; it can never be adopted, so replacement is the only recovery.
     const mod = await importFresh()
     await mod.initDaemonPtyProvider()
 
@@ -2521,17 +2406,12 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
       '/fake/token'
     )
     expect(forkMock).toHaveBeenCalled()
-    // Pins the 'rejected' fast-path: a daemon that actively refuses the
-    // handshake is never worth a grace window, so it is probed exactly once
-    // (no retries) before replacement. The other clients are the initial
-    // adoption attempt and the fresh daemon's temporary adoption lease.
+    // 'rejected' gets no grace window (probed once): count = initial adoption + rejected probe + fresh daemon lease.
     expect(daemonClientMock).toHaveBeenCalledTimes(3)
   })
 
   it('adopts a healthy daemon whose pid-file identity cannot be verified (null startedAtMs metadata)', async () => {
-    // Why: the regression contract — a pid file with startedAtMs null (all
-    // pre-fix Windows pid files) resolves launch identity to 'unknown'. With
-    // a live daemon answering on the pipe, that must ADOPT, never replace.
+    // Why: startedAtMs null (all pre-fix Windows pid files) → identity 'unknown'; a live daemon must ADOPT, not replace.
     const mod = await importFresh()
     await mod.initDaemonPtyProvider()
 
@@ -2549,8 +2429,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
   })
 
   it('writes the daemon self-reported start time to the pid file when the OS query returns null', async () => {
-    // Why: getProcessStartedAtMs has no cheap Windows implementation, so the
-    // pid file's pid-recycling guard depends on the ready-message fallback.
+    // Why: getProcessStartedAtMs has no cheap Windows impl, so the pid-recycling guard uses the ready-message fallback.
     const mod = await importFresh()
     await mod.initDaemonPtyProvider()
 
@@ -2590,8 +2469,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
   })
 
   it('keeps legacy daemon pid/token files when the probe fails but the pid-file process is alive', async () => {
-    // Why: deleting a live-but-wedged legacy daemon's token file makes its
-    // sessions permanently unadoptable — no future launch could authenticate.
+    // Why: deleting a live legacy daemon's token file makes its sessions permanently unadoptable.
     const mod = await importFresh()
     readFileSyncMock.mockReturnValue('{"pid":123}')
     // process.pid is guaranteed alive, so the liveness probe succeeds.
@@ -2608,8 +2486,7 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
   it('cleans up legacy daemon pid/token files when the probe fails and the process is gone', async () => {
     const mod = await importFresh()
     readFileSyncMock.mockReturnValue('{"pid":123}')
-    // Why: spy on process.kill so the liveness probe deterministically reports
-    // "no such process" without depending on an unallocated real pid.
+    // Why: spy process.kill to force a deterministic ESRCH instead of relying on an unallocated real pid.
     const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => {
       throw new Error('ESRCH')
     })
diff --git a/src/main/daemon/daemon-init.ts b/src/main/daemon/daemon-init.ts
index 093cb7a00f7..0f0c9efad64 100644
--- a/src/main/daemon/daemon-init.ts
+++ b/src/main/daemon/daemon-init.ts
@@ -1,11 +1,5 @@
-/* eslint-disable max-lines -- Why: this module owns the complete daemon
-lifecycle for the Electron main process — init, out-of-process launch,
-current+legacy adapter wiring, restart orchestration (the 7-step sequence
-from docs/daemon-staleness-ux.md §Phase 1), and teardown on app quit. Splitting
-it would scatter the "swap the running provider atomically" invariant across
-files with no cleaner ownership seam: restart, replaceDaemonProvider, and the
-module-level spawner/adapter singletons must stay co-located so a future
-change cannot leave them drifting out of sync. */
+/* eslint-disable max-lines -- Why: owns the full daemon lifecycle (init, launch, adapter wiring,
+restart, teardown); the "swap the provider atomically" invariant keeps restart + singletons co-located. */
 import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { app } from 'electron'
@@ -58,31 +52,14 @@ import {
   hasSeededUnconfirmedClaudePtys
 } from '../claude-accounts/live-pty-gate'
 
-// Why: daemon init runs concurrently with window load, so harness-side stderr
-// arrival times are useless — in-process `t` lets the startup benchmark derive
-// how long the daemon cold-start path actually took.
+// Why: daemon init runs concurrent with window load, so an in-process t timestamp (not harness stderr timing) measures cold-start.
 function logDaemonMilestone(event: string, details: Record<string, unknown> = {}): void {
   if (isStartupDiagnosticsEnabled()) {
     logStartupDiagnostic(event, { t: Math.round(performance.now()), ...details })
   }
 }
 
-// Why: how many extra hello+listSessions probes to make against a wedged-but-
-// connectable daemon before replacing it. Each probe waits out the client's 5s
-// hello timeout, so this spaces re-checks ~5s apart: 1 initial + 11 retries ≈
-// 60s of grace for a transiently wedged daemon (Windows update-relaunch drain)
-// to answer and be preserved WITH its live sessions, before a permanent wedge
-// (#8689) is replaced. Deliberately generous to keep live-session loss on the
-// transient path as close to zero as possible.
-//
-// A transient wedge drains early (well under the 60s local-PTY fail-open cap),
-// so its startup is short. Only a *permanent* wedge runs the full window; it can
-// then approach/exceed the fail-open cap, at which point restored panes fail
-// open to the in-process provider for the session and adopt the freshly forked
-// daemon on the next launch — a rare path that still recovers, versus the old
-// forever-broken behavior. Trade-off: a transient wedge owning live sessions
-// that takes longer than ~60s to drain is replaced (live processes lost, though
-// scrollback cold-restores). Raise this only alongside the fail-open cap.
+// Why: extra hello+listSessions probes (~5s each) giving a wedged-but-connectable daemon ~60s grace to answer and keep its live sessions before a permanent wedge (#8689) is replaced; raise only alongside the fail-open cap.
 export const WEDGED_DAEMON_GRACE_RETRIES = 11
 const DAEMON_SELF_SHUTDOWN_WAIT_MS = 5_000
 const DAEMON_CHILD_TERMINATION_GRACE_MS = 5_000
@@ -92,10 +69,7 @@ let spawner: DaemonSpawner | null = null
 type DaemonProvider = DaemonPtyRouter | DaemonPtyAdapter | DegradedDaemonPtyProvider
 
 let adapter: DaemonProvider | null = null
-// Why: coalesce concurrent restartDaemon() calls so two clicks (or a UI
-// click racing an internal caller) can't both enter the 7-step sequence —
-// the second entry would read the already-disposed current adapter and
-// race cleanupDaemonForProtocol against a half-spawned replacement.
+// Why: coalesce concurrent restartDaemon() calls so two entries can't race the 7-step sequence against a half-spawned replacement.
 let restartInFlight: Promise<RestartDaemonResult> | null = null
 
 function getRuntimeDir(): string {
@@ -112,9 +86,7 @@ function getHistoryDir(): string {
 
 function getDaemonEntryPath(): string {
   const appPath = app.getAppPath()
-  // Why: electron-builder unpacks daemon-entry.js so child_process.fork() can
-  // execute it from disk. In packaged apps app.getAppPath() points at
-  // app.asar, so redirect to the unpacked sibling before joining the script.
+  // Why: packaged app.getAppPath() points at app.asar, so redirect to app.asar.unpacked where daemon-entry.js is fork-executable.
   const basePath = app.isPackaged ? appPath.replace('app.asar', 'app.asar.unpacked') : appPath
   const directEntryPath = join(basePath, 'daemon-entry.js')
   if (existsSync(directEntryPath)) {
@@ -123,10 +95,7 @@ function getDaemonEntryPath(): string {
   return join(basePath, 'out', 'main', 'daemon-entry.js')
 }
 
-// Why: the detached daemon writes lifecycle events to a rotated file so field
-// failures are diagnosable from a bundle. Honor the same hard privacy switch
-// the local trace sink honors (ORCA_DIAGNOSTICS_DISABLED); absence of the arg
-// is fully supported, so gating it off is safe and adoption-neutral.
+// Why: pass a log-file arg so field failures are diagnosable, but honor the ORCA_DIAGNOSTICS_DISABLED privacy switch.
 function daemonLogArgs(): string[] {
   const disabled = (process.env.ORCA_DIAGNOSTICS_DISABLED ?? '').trim().toLowerCase()
   if (disabled === '1' || disabled === 'true') {
@@ -135,9 +104,7 @@ function daemonLogArgs(): string[] {
   return ['--log-file', getDaemonLogFilePath()]
 }
 
-// Why: before spawning a new daemon, check if an existing one is alive by
-// attempting a TCP connection to the socket. If it connects, the daemon
-// survived from a previous app session — reuse it instead of spawning.
+// Why: a socket that accepts a connection proves a daemon survived a previous app session and can be reused.
 function probeSocket(socketPath: string): Promise<boolean> {
   return new Promise((resolve) => {
     if (process.platform !== 'win32' && !existsSync(socketPath)) {
@@ -253,8 +220,7 @@ async function cleanupFailedDaemonAdoption(
     ...legacy.map((entry) => entry.disconnectOnly()),
     (async () => {
       try {
-        // Why: endpoint publication allows other authenticated clients to win;
-        // only daemon-side shutdownIfIdle may prove a failed adoption is killable.
+        // Why: other authenticated clients may win, so only daemon-side shutdownIfIdle can prove a failed adoption is killable.
         await current.disconnectOnly()
       } catch (error) {
         current.dispose()
@@ -362,8 +328,7 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
     const launchNonce = suppliedLaunchNonce ?? randomUUID()
     let adoptionClient: DaemonClient | null = new DaemonClient({ socketPath, tokenPath })
     try {
-      // Why: acquire the full pair before any control-only probes so an expired
-      // inherited deadline cannot fire in the probe-to-adoption gap.
+      // Why: acquire the full pair before control-only probes so an expired inherited deadline can't fire in the probe-to-adoption gap.
       await adoptionClient.ensureConnected()
     } catch {
       adoptionClient.disconnect()
@@ -398,10 +363,7 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
           console.warn('[daemon] Replacing daemon with unavailable macOS system resolver')
           await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
         } else {
-          // Why: a protocol-healthy daemon can outlive the app bundle that
-          // launched it. In dev this happens after deleting/rebuilding a
-          // worktree; in packaged apps it happens when the stable
-          // /Applications/Orca.app path is replaced during update.
+          // Why: a protocol-healthy daemon can outlive its launching app bundle (dev worktree rebuild, or packaged update replacing the app path).
           const identity = await getDaemonLaunchIdentity(
             runtimeDir,
             socketPath,
@@ -417,8 +379,7 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
               app.getVersion()
             ))
           if (identity === 'mismatch' || stalePackagedBundle) {
-            // Why: replacing a healthy daemon kills its child PTYs; defer code
-            // freshness until no live terminal sessions would be lost.
+            // Why: replacing a healthy daemon kills its child PTYs; defer code freshness until no live sessions would be lost.
             const replacementLabel = stalePackagedBundle
               ? 'launched before the current app bundle was installed'
               : 'launched from a different app path'
@@ -434,28 +395,14 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
             )
             await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
           } else {
-            // Why: daemon is already running from a previous app session and
-            // responded to a protocol-level ping. Safe to reuse.
+            // Why: healthy daemon from a previous session answered a protocol ping — safe to reuse.
             return preserveDaemon()
           }
         }
       } else {
-        // Why: a busy machine (e.g. right after an update) can time out the
-        // health check while the daemon is alive and owning terminals. Killing
-        // it would destroy every live session, so re-verify with a session list
-        // first.
+        // Why: a busy machine can time out the health check on a live daemon; re-verify with a session list before killing its sessions.
         let liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
-        // Why: on a Windows update relaunch the daemon can be transiently wedged
-        // past every RPC budget (final checkpoint flush + installer/AV disk
-        // pressure) while its sessions are still alive — replacing it here is what
-        // killed those sessions. A pipe that still accepts connections proves a
-        // live daemon, so give a wedged-but-connectable daemon a bounded grace to
-        // drain and answer before deciding. A PERMANENTLY wedged daemon (accepts
-        // connections but its event loop never answers hello — #8689) exhausts the
-        // grace and falls through to replacement below, instead of being preserved
-        // forever, which strands the app with zero working terminals. 'rejected'
-        // means the daemon answered and refused the handshake — it can never be
-        // adopted, so it skips the grace and replacement stays the only recovery.
+        // Why: a wedged-but-connectable daemon (Windows update relaunch) may still own live sessions, so grace-retry before replacing; a permanent wedge (#8689) exhausts the grace, and 'rejected' skips it (handshake refused = never adoptable).
         let graceRetry = 0
         while (
           liveSessionCount === null &&
@@ -480,18 +427,13 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
         }
       }
 
-      // Why: a raw socket can outlive a broken or wedged daemon. Kill by PID
-      // before respawn so the new daemon does not race the stale process.
+      // Why: a raw socket can outlive a broken daemon; kill by PID before respawn so the new daemon doesn't race the stale one.
       adoptionClient?.disconnect()
       adoptionClient = null
       await killStaleDaemon(runtimeDir, socketPath, tokenPath)
 
       const userDataPath = app.getPath('userData')
-      // Why: on win32 packaged, fork from a copy of the Electron runtime staged
-      // in userData so the daemon's image + loaded modules escape the install dir
-      // the NSIS updater deletes and force-closes. Staged here (not at app start)
-      // so the one-time copy stays off the first-paint path and is skipped on
-      // launches that adopt a live daemon. Fail-open: null → in-dir host, below.
+      // Why: on win32 packaged, stage a daemon-host copy in userData so its image escapes the NSIS updater's kill zone; lazy so it's off first-paint. Fail-open: null → in-dir host.
       const relocatedHost = materializeRelocatedDaemonHost()
       // Fork the relocated entry when available; otherwise the install-dir entry.
       const forkEntryPath = relocatedHost ? relocatedHost.entryPath : entryPath
@@ -509,37 +451,24 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
           ...daemonLogArgs()
         ],
         {
-          // Why: detached daemons can outlive dev worktrees. Starting from
-          // userData keeps process.cwd() valid after a repo/worktree is deleted.
+          // Why: detached daemons outlive dev worktrees; userData keeps process.cwd() valid after a repo/worktree is deleted.
           cwd: userDataPath,
-          // Why: detached + unref lets the daemon outlive the Electron process.
-          // stdout stays 'ignore' so the child never holds the parent's stdout
-          // open (which would block Electron exit); stderr is 'pipe' so a
-          // module-load crash during startup is captured instead of discarded
-          // (v1.4.129-rc.1 shipped a daemon that only logged "exited with code 1"
-          // because stderr was thrown away). The pipe is destroyed on readiness.
+          // Why: detached+unref outlives Electron; stdout 'ignore' (else blocks exit), stderr 'pipe' captures startup crashes lost in v1.4.129-rc.1.
           detached: true,
           stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
-          // Why: run the relocated Orca.exe copy instead of the install-dir one.
-          // It is byte-identical, so run-as-node behavior is unchanged; only the
-          // image path moves out of the updater's kill zone.
+          // Why: run the byte-identical relocated Orca.exe so the image path sits outside the updater's kill zone.
           ...(relocatedHost ? { execPath: relocatedHost.execPath } : {}),
-          // Why: ELECTRON_RUN_AS_NODE makes the forked process run as a plain
-          // Node.js process instead of an Electron renderer/main process. Without
-          // it, Electron's GPU/display initialization can interfere with native
-          // module operations like node-pty's posix_spawn of the spawn-helper.
+          // Why: run the fork as plain Node so Electron's GPU/display init can't interfere with node-pty's posix_spawn of the spawn-helper.
           env: {
             ...process.env,
             ELECTRON_RUN_AS_NODE: '1',
-            // Why: the detached daemon is plain Node and cannot call Electron's
-            // app.getPath(), but shell-ready rcfiles must live outside swept tmp.
+            // Why: the detached plain-Node daemon can't call app.getPath(), but shell rcfiles must live outside swept tmp.
             ORCA_USER_DATA_PATH: userDataPath
           }
         }
       )
 
-      // Why: keep only the startup-window stderr tail so a crash cause is
-      // visible without unbounded memory if the daemon spews before dying.
+      // Why: keep only the startup-window stderr tail so a crash cause is visible without unbounded memory.
       const STARTUP_STDERR_MAX_BYTES = 8192
       let startupStderr = ''
       let collectingStderr = true
@@ -553,9 +482,7 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
         }
       }
       child.stderr?.on('data', onStartupStderr)
-      // Why: once the daemon is up (or has failed) the parent must not keep a
-      // live handle on the detached daemon's stderr — a piped stream would ref
-      // the parent event loop and prevent Electron from exiting cleanly.
+      // Why: release the detached daemon's stderr once up/failed — a live piped stream refs the parent loop and blocks Electron exit.
       const releaseStderr = (): void => {
         collectingStderr = false
         child.stderr?.off('data', onStartupStderr)
@@ -580,9 +507,7 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
           }
           settled = true
           cleanupStartupListeners()
-          // Why: stderr was previously discarded, so a startup crash surfaced only
-          // as "exited with code 1". Attach the captured tail to the thrown error
-          // (which the fallback path reports) and log it so the real cause shows.
+          // Why: attach the captured stderr tail to the thrown error and log it so a startup crash isn't just "exited with code 1".
           const stderrTail = startupStderr.trim()
           if (stderrTail) {
             console.warn(`[daemon] startup failed; captured stderr tail:\n${stderrTail}`)
@@ -621,8 +546,7 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
               return
             }
             try {
-              // Why: hello and the PID record must share the daemon's self time
-              // and nonce so cleanup can identify this exact process incarnation.
+              // Why: pid record shares the daemon's self time and nonce so cleanup can identify this exact process incarnation.
               writeFileSync(
                 pidPath,
                 serializeDaemonPidFile({
@@ -639,12 +563,9 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
               return
             }
             settled = true
-            // Why: the daemon process is detached after readiness; leaving
-            // startup listeners attached retains this launch promise closure.
+            // Why: daemon is detached after readiness; detach startup listeners so the launch promise closure isn't retained.
             cleanupStartupListeners()
-            // Why: disconnect IPC channel, release the stderr pipe, and unref so
-            // Electron can exit without waiting for the daemon. The daemon keeps
-            // running detached.
+            // Why: release IPC/stderr and unref so Electron can exit without waiting; the daemon keeps running detached.
             releaseStderr()
             child.disconnect()
             child.unref()
@@ -678,8 +599,7 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
           tokenPath
         )
       } catch (error) {
-        // Why: another client may have adopted this still-live process. Keep its
-        // valid identity until exit, but remove a record published after an early exit.
+        // Why: another client may have adopted this live process; keep its pid record until exit, but remove one published after an early exit.
         let pidRecordRemoved = false
         const removeExitedPidRecord = (): void => {
           if (pidRecordRemoved) {
@@ -707,10 +627,7 @@ function createOutOfProcessLauncher(runtimeDir: string): DaemonLauncher {
 
 export async function initDaemonPtyProvider(signal?: AbortSignal): Promise<void> {
   logDaemonMilestone('daemon-init-start')
-  // Why: e2e coverage for the startup PTY gate (#5232) needs a daemon init
-  // that deterministically outlasts the first-window timeout. Real triggers
-  // (stale-daemon cleanup, legacy probes on a busy disk) are not controllable
-  // from a test.
+  // Why: e2e coverage for the startup PTY gate (#5232) needs a daemon init that deterministically outlasts the first-window timeout.
   const e2eInitDelayMs = Number(process.env.ORCA_E2E_DAEMON_INIT_DELAY_MS)
   if (Number.isFinite(e2eInitDelayMs) && e2eInitDelayMs > 0) {
     await new Promise((resolve) => setTimeout(resolve, e2eInitDelayMs))
@@ -722,20 +639,14 @@ export async function initDaemonPtyProvider(signal?: AbortSignal): Promise<void>
     launcher: createOutOfProcessLauncher(runtimeDir)
   })
 
-  // Why: assign spawner/adapter only after both succeed. If ensureRunning()
-  // throws, a stale spawner would prevent shutdownDaemon() from cleaning up
-  // correctly on retry.
+  // Why: assign the module-level spawner/adapter only after both succeed, so a failed ensureRunning() leaves no stale spawner.
   const info = await newSpawner.ensureRunning()
-  // Reclaim superseded daemon-host copies on EVERY launch, not just on a fresh
-  // spawn: surviving daemons make spawns rare, so a spawn-only sweep would let
-  // old-version copies accumulate. Current + live-daemon-pinned versions stay.
+  // Why: reclaim superseded daemon-host copies on EVERY launch (spawns are rare), keeping current + live-daemon-pinned versions.
   pruneOldDaemonHosts(collectPinnedDaemonVersions(runtimeDir))
   const launchMode = newSpawner.getHandle()?.mode
   logDaemonMilestone('daemon-current-ready')
   if (signal?.aborted) {
-    // Why: startup fail-open may already have allowed fallback LocalPtyProvider
-    // PTYs to spawn. Do not install late, but give an empty daemon one bounded
-    // authenticated retirement attempt; live adopted sessions reject it and survive.
+    // Why: fail-open may already have spawned fallback PTYs; don't install late, but retire an empty daemon (live sessions reject it and survive).
     const abortedStartupAdapter = new DaemonPtyAdapter({
       socketPath: info.socketPath,
       tokenPath: info.tokenPath
@@ -749,10 +660,7 @@ export async function initDaemonPtyProvider(signal?: AbortSignal): Promise<void>
     socketPath: info.socketPath,
     tokenPath: info.tokenPath,
     historyPath: getHistoryDir(),
-    // Why: when the daemon process dies (e.g. killed by a signal, OOM, or
-    // cascading from a force-quit of child processes), the adapter's
-    // ensureConnected() detects the dead socket and calls this to fork a
-    // replacement daemon before retrying the connection.
+    // Why: on daemon death, ensureConnected() detects the dead socket and calls this to fork a replacement before retrying.
     respawn: async () => {
       console.warn('[daemon] Daemon process died — respawning')
       newSpawner.resetHandle()
@@ -763,8 +671,7 @@ export async function initDaemonPtyProvider(signal?: AbortSignal): Promise<void>
   let legacyAdapters: DaemonPtyAdapter[] = []
   let routedAdapter: DaemonProvider = newAdapter
   try {
-    // Why: the launcher's temporary pair closes only after this permanent
-    // adapter pair is established, leaving no retirement gap during adoption.
+    // Why: the launcher's temporary pair closes only after this permanent pair is established, leaving no adoption gap.
     await newAdapter.establishLifecycleLease()
     releaseDaemonAdoptionLease(newSpawner.getHandle())
 
@@ -783,17 +690,13 @@ export async function initDaemonPtyProvider(signal?: AbortSignal): Promise<void>
             })
           : newAdapter
     if (routedAdapter instanceof DegradedDaemonPtyProvider) {
-      // Why: the preserved daemon cannot create fresh terminals, but its live
-      // sessions may still be writable. Discover those ids so only known old
-      // sessions route to the degraded daemon; fresh panes fall back locally.
+      // Why: preserved daemon can't create fresh terminals; discover its live session ids so only they route to it (fresh panes fall back locally).
       await routedAdapter.discoverDaemonSessions()
     } else if (routedAdapter instanceof DaemonPtyRouter) {
       await routedAdapter.discoverLegacySessions()
     }
     if (signal?.aborted) {
-      // Why: same late-swap guard after legacy discovery, which can also exceed
-      // the first-window startup timeout on slow or stale daemon state. Release
-      // every uninstalled adapter lease without killing its live sessions.
+      // Why: same late-swap guard after legacy discovery; release uninstalled adapter leases without killing live sessions.
       await routedAdapter.disconnectOnly()
       return
     }
@@ -808,19 +711,13 @@ export async function initDaemonPtyProvider(signal?: AbortSignal): Promise<void>
   spawner = newSpawner
   adapter = routedAdapter
   setLocalPtyProvider(routedAdapter)
-  // Why: desktop startup now lets the first window register PTY listeners
-  // before daemon init finishes. Rebind here so daemon PTYs still fan out
-  // data/exit events through the renderer and runtime listeners.
+  // Why: the first window may register PTY listeners before daemon init finishes; rebind so daemon PTYs still fan out events.
   rebindLocalProviderListeners()
   logDaemonMilestone('daemon-init-done', { legacyAdapters: legacyAdapters.length })
   await reconcileSeededClaudeLivePtys(routedAdapter)
 }
 
-// Why: the Claude live-PTY gate is seeded pessimistically from persistence at
-// store load. Once the daemon is up we know which of those sessions actually
-// survived — release dead ids so they cannot defer OAuth refresh forever.
-// Listing failures keep the seeds: over-holding the gate only delays a usage
-// refresh, while releasing it early can rotate a live CLI's refresh token.
+// Why: release gate ids only for daemon-confirmed-dead sessions; keep seeds on listing failure since releasing early can rotate a live CLI's refresh token.
 async function reconcileSeededClaudeLivePtys(provider: DaemonProvider): Promise<void> {
   if (!hasSeededUnconfirmedClaudePtys()) {
     return
@@ -841,24 +738,17 @@ async function reconcileSeededClaudeLivePtys(provider: DaemonProvider): Promise<
       )
     )
   } catch (error) {
-    // Why: gate bookkeeping must never fail daemon init; stale seeds only
-    // defer a usage refresh until the next restart.
+    // Why: gate bookkeeping must never fail daemon init; stale seeds only defer a usage refresh until next restart.
     console.warn('[daemon] Failed to reconcile seeded Claude live-PTY gate:', error)
   }
 }
 
-// Why: the Manage Sessions IPC handlers need read access to the current
-// adapter/router to list sessions, kill them, etc. Exposed as a narrow getter
-// rather than exporting the module-level variable to keep the "swap on
-// restart" invariant in one place (replaceDaemonProvider).
+// Why: a narrow getter (not a raw export) keeps the "swap on restart" invariant in one place (replaceDaemonProvider).
 export function getDaemonProvider(): DaemonProvider | null {
   return adapter
 }
 
-// Why: the "Restart daemon" flow rebuilds the current-protocol adapter and
-// must update both the module-level `adapter` singleton here and the
-// `localProvider` reference inside ipc/pty.ts. Without this helper they could
-// drift — app-quit would dispose a stale adapter reference.
+// Why: keep the module-level adapter and ipc/pty.ts's localProvider in sync so app-quit can't dispose a stale reference.
 export function replaceDaemonProvider(newAdapter: DaemonProvider): void {
   adapter = newAdapter
   setLocalPtyProvider(newAdapter)
@@ -892,11 +782,7 @@ export type RestartDaemonResult = {
   killedCount: number
 }
 
-// Why: the 7-step sequence from docs/daemon-staleness-ux.md §Phase 1 restart.
-// Current-protocol only — legacy adapters are preserved and route to their
-// original daemons with no respawn path. See the design doc for rationale on
-// each step, notably why synthetic exits must fan out *before* the listener
-// unsubscribe.
+// Why: the 7-step restart sequence from docs/daemon-staleness-ux.md §Phase 1; current-protocol only (legacy adapters preserved).
 export async function restartDaemon(): Promise<RestartDaemonResult> {
   if (restartInFlight) {
     return restartInFlight
@@ -918,11 +804,7 @@ async function runRestartDaemon(): Promise<RestartDaemonResult> {
   const currentOnly = getCurrentDaemonAdapter(currentAdapter)
   const legacyAdapters = getLegacyDaemonAdapters(currentAdapter)
 
-  // Step 1: synthesize pty:exit for every active session on the current
-  // adapter BEFORE any teardown. The daemon's kill-all-and-shutdown path
-  // explicitly does not fan onExit to clients (session.ts:246-252), so
-  // without this the renderer would never see exits and would black-hole
-  // writes against the disposed adapter.
+  // Step 1: synthesize pty:exit for every active session BEFORE teardown — the daemon's shutdown path never fans onExit to clients (session.ts:246-252), so the renderer would otherwise never see exits.
   const fallbackKilledCount =
     currentAdapter instanceof DegradedDaemonPtyProvider
       ? await currentAdapter.shutdownFallbackSessions()
@@ -939,31 +821,24 @@ async function runRestartDaemon(): Promise<RestartDaemonResult> {
     currentAdapter.fanoutCurrentDaemonSyntheticExits(-1)
   }
 
-  // Step 2: detach renderer listeners from the current adapter. Must happen
-  // AFTER step 1 so the synthesized exits actually reach the renderer, and
-  // BEFORE step 6 so the new provider isn't bound with stale listeners.
+  // Step 2: detach renderer listeners — after step 1 (so synthesized exits land) and before step 6 (no stale binding).
   unbindLocalProviderListeners()
 
-  // Step 3: kill the current-protocol daemon process (shutdown RPC → fallback
-  // killStaleDaemon → socket/pid unlink). Legacy adapters untouched.
+  // Step 3: kill the current-protocol daemon process; legacy adapters untouched.
   let info: Awaited<ReturnType<DaemonSpawner['ensureRunning']>>
   try {
     await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
 
-    // Step 4: reuse the existing spawner so the respawn closure baked into
-    // long-lived adapters stays valid. Do NOT construct a new DaemonSpawner.
+    // Step 4: reuse the existing spawner so the respawn closure baked into long-lived adapters stays valid (do NOT new one).
     currentSpawner.resetHandle()
     info = await currentSpawner.ensureRunning()
   } catch (error) {
-    // Why: the old provider remains authoritative until the final swap, even
-    // if cleanup or replacement launch fails after listener teardown.
+    // Why: old provider stays authoritative until the final swap; rebind since relaunch failed after teardown.
     rebindLocalProviderListeners()
     throw error
   }
 
-  // Step 5: build a fresh current adapter against the respawned daemon. Its
-  // respawn callback closes over the same spawner instance (identical to the
-  // crash-respawn closure in initDaemonPtyProvider).
+  // Step 5: build a fresh current adapter against the respawned daemon.
   const newCurrent = new DaemonPtyAdapter({
     socketPath: info.socketPath,
     tokenPath: info.tokenPath,
@@ -977,14 +852,11 @@ async function runRestartDaemon(): Promise<RestartDaemonResult> {
   })
   let newProvider: DaemonProvider = newCurrent
   try {
-    // Why: the temporary launcher lease overlaps this permanent pair so manual
-    // restart cannot strand a newly spawned daemon during adoption.
+    // Temporary launcher lease overlaps this permanent pair so a manual restart can't strand a newly spawned daemon during adoption.
     await newCurrent.establishLifecycleLease()
     releaseDaemonAdoptionLease(currentSpawner.getHandle())
 
-    // Re-wrap in router if there were legacy adapters at startup; otherwise
-    // point straight at the new adapter. Legacy instances are preserved by
-    // reference — they still route to the same pre-upgrade daemons.
+    // Re-wrap in a router only if legacy adapters exist; they're preserved by reference and still route to their pre-upgrade daemons.
     newProvider =
       legacyAdapters.length > 0
         ? new DaemonPtyRouter({ current: newCurrent, legacy: legacyAdapters })
@@ -1002,8 +874,7 @@ async function runRestartDaemon(): Promise<RestartDaemonResult> {
     } catch (caught) {
       cleanupError = caught
     }
-    // Why: the previous provider remains module-authoritative until the swap;
-    // restore its renderer bindings when replacement adoption fails.
+    // Previous provider stays module-authoritative until the swap; restore its renderer bindings when adoption fails.
     rebindLocalProviderListeners()
     if (cleanupError) {
       throw new AggregateError([error, cleanupError], 'Daemon restart and cleanup both failed')
@@ -1011,12 +882,7 @@ async function runRestartDaemon(): Promise<RestartDaemonResult> {
     throw error
   }
 
-  // Why: drain the outgoing router's subscriptions from the shared legacy
-  // adapters before installing the new router (which subscribes fresh). Must
-  // run *after* the new provider exists so no adapter event is unhandled in
-  // the narrow window, and *before* replaceDaemonProvider so the swap is
-  // atomic from the renderer's perspective. Plain dispose() would also tear
-  // down the legacy adapters themselves — use the router-only variant.
+  // Drain the old router's subscriptions via the router-only variant (plain dispose() would tear down the shared legacy adapters), after the new provider exists (no unhandled events) and before the swap (atomic for the renderer).
   disposeProviderSubscriptionsOnly(currentAdapter)
 
   // Step 6: swap module state (adapter + localProvider) atomically.
@@ -1028,10 +894,8 @@ async function runRestartDaemon(): Promise<RestartDaemonResult> {
   return { killedCount }
 }
 
-// Why: disconnect from the daemon without killing it. The daemon runs as a
-// separate process and survives app quit — sessions stay alive for warm
-// reattach on next launch. Leave history sessions marked "unclean" here so a
-// later daemon crash while Orca is closed is still recoverable on next launch.
+// Disconnect without killing: the daemon survives app quit so sessions stay warm for reattach.
+// Leave history sessions marked "unclean" so a daemon crash while Orca is closed stays recoverable.
 export async function disconnectDaemon(): Promise<void> {
   await adapter?.disconnectOnly()
   adapter = null
@@ -1046,11 +910,9 @@ export async function shutdownDaemon(): Promise<void> {
 }
 
 export type OrphanedDaemonCleanupResult = {
-  /** True when we detected a live daemon socket and connected to tear it down.
-   *  False when no daemon was running (fresh install or clean previous quit). */
+  /** True when a live daemon socket was found and torn down; false when none was running. */
   cleaned: boolean
-  /** Number of live PTY sessions killed during cleanup. The caller surfaces this
-   *  to the user so they know what background work was stopped. */
+  /** Number of live PTY sessions killed during cleanup (surfaced to the user). */
   killedCount: number
 }
 
@@ -1065,12 +927,10 @@ export async function cleanupDaemonForProtocol(
   const alive = await probeSocket(socketPath)
   if (!alive) {
     if (protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
-      // Why: endpoint absence does not prove a canonical PID record still
-      // belongs to the current protocol; the exact daemon owns its artifact cleanup.
+      // Endpoint absence doesn't prove the PID record belongs to the current protocol; leave artifact cleanup to the owning daemon.
       return { cleaned: false, killedCount: 0 }
     }
-    // Why: still best-effort remove a stale socket file so a future opt-in
-    // launch doesn't hit EADDRINUSE when the daemon tries to bind.
+    // Best-effort remove a stale socket so a future launch doesn't hit EADDRINUSE on bind.
     if (process.platform !== 'win32' && existsSync(socketPath)) {
       try {
         unlinkSync(socketPath)
@@ -1097,18 +957,13 @@ export async function cleanupDaemonForProtocol(
       .catch(() => ({ sessions: [] }))
     killedCount = sessions.sessions.filter((s) => s.isAlive).length
 
-    // Why: the daemon exposes a single-shot `shutdown` RPC (daemon-server.ts)
-    // that kills every session and then terminates its own process. Using it
-    // avoids the race between per-session `kill` calls and the daemon exiting.
+    // Use the single-shot `shutdown` RPC (kills all sessions then exits) to avoid racing per-session `kill` calls against the daemon exiting.
     await client.request('shutdown', { killSessions: true }).catch(() => {
-      // Daemon exits immediately after handling the RPC — the socket may close
-      // before the reply round-trips. Treat that as success.
+      // Daemon exits immediately after the RPC, so the socket may close before the reply arrives; treat as success.
     })
     didRequestShutdown = true
   } catch {
-    // Why: previous-protocol daemons may be wedged or too old to complete the
-    // RPC cleanup path. Fall back to PID cleanup, but daemon-health only
-    // unlinks a live socket after proving it killed the matching process.
+    // Previous-protocol daemons may be wedged or too old for the RPC path; fall back to PID cleanup (only unlinks a live socket after proving the process is killed).
     didKillStaleDaemon = await killStaleDaemon(runtimeDir, socketPath, tokenPath, protocolVersion)
   } finally {
     client.disconnect()
@@ -1116,16 +971,13 @@ export async function cleanupDaemonForProtocol(
 
   if (didRequestShutdown && protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
     if (!(await waitForDaemonEndpointExit(socketPath))) {
-      // Why: never fork a replacement while the old incarnation may still
-      // own the endpoint or be disposing terminal children.
+      // Never fork a replacement while the old incarnation may still own the endpoint or be disposing terminal children.
       throw new Error('Timed out waiting for daemon self-shutdown')
     }
     return { cleaned: true, killedCount }
   }
 
-  // Why: after `shutdown`, the daemon unlinks its socket itself — but on some
-  // crash paths the file lingers. Clean up defensively so a later opt-in
-  // relaunch can bind cleanly.
+  // Defensively unlink the socket: the daemon normally removes it after `shutdown`, but on some crash paths it lingers and blocks a later rebind.
   if (didRequestShutdown && process.platform !== 'win32' && existsSync(socketPath)) {
     try {
       unlinkSync(socketPath)
@@ -1174,13 +1026,7 @@ async function createLegacyDaemonAdapters(runtimeDir: string): Promise<DaemonPty
     const socketPath = getDaemonSocketPath(runtimeDir, protocolVersion)
     const tokenPath = getDaemonTokenPath(runtimeDir, protocolVersion)
     if (!(await probeSocket(socketPath))) {
-      // Why: dead legacy daemons leave pid/token files behind forever (one per
-      // protocol bump). A stale pid eventually gets recycled by an unrelated
-      // process, turning any future identity check into a PowerShell spawn.
-      // Only clean up when the pid-file process is provably gone: a live
-      // legacy daemon can transiently fail the 1s probe right after an update
-      // (wedged event loop, exhausted pipe backlog), and deleting its token
-      // file would make its sessions permanently unadoptable.
+      // Why: a recycled stale pid later turns an identity check into a PowerShell spawn, so delete leaked pid/token files — but only when the pid-process is provably gone (a live daemon can transiently fail the probe, and dropping its token makes its sessions permanently unadoptable).
       if (!legacyDaemonProcessMayBeAlive(runtimeDir, protocolVersion)) {
         for (const stalePath of [
           getDaemonPidPath(runtimeDir, protocolVersion),
@@ -1202,17 +1048,8 @@ async function createLegacyDaemonAdapters(runtimeDir: string): Promise<DaemonPty
       }
       continue
     }
-    // Why: old daemon PTYs can be running long-lived agents during an app
-    // upgrade. Keep those sessions routed to their original daemon while new
-    // terminals use the current protocol, instead of killing background work.
-    // Legacy adapters intentionally do not respawn: respawning an old protocol
-    // daemon from new code would recreate stale env semantics and can be less
-    // predictable than letting the session fail if that old daemon dies.
-    // Why historyPath is still passed: checkpoint writes will fail silently
-    // (pre-v4 daemons don't support getSnapshot), but the HistoryManager is
-    // still needed for cleanup — close/exit events must remove history dirs
-    // and mark meta.json as ended. Without it, a later v4 session reusing
-    // the same ID could false-restore stale scrollback.bin.
+    // Keep old-protocol PTYs routed to their original daemon during upgrade; legacy adapters never respawn (new code would recreate stale env semantics).
+    // historyPath is still needed for cleanup — without it a later v4 session reusing the same ID could false-restore stale scrollback.bin.
     adapters.push(
       new DaemonPtyAdapter({
         socketPath,
diff --git a/src/main/daemon/daemon-pty-adapter.test.ts b/src/main/daemon/daemon-pty-adapter.test.ts
index 707d2800e15..9b022a44211 100644
--- a/src/main/daemon/daemon-pty-adapter.test.ts
+++ b/src/main/daemon/daemon-pty-adapter.test.ts
@@ -42,8 +42,7 @@ function createMockSubprocess(dataOnSubscribe?: string): SubprocessHandle & {
   let onDataCb: ((data: string) => void) | null = null
   let onExitCb: ((code: number) => void) | null = null
   return {
-    // Why: getCwd falls back to OS pid lookup; a plausible fake pid can
-    // collide with an unrelated local process and leak its cwd into tests.
+    // Why: getCwd falls back to OS pid lookup; an implausibly-high fake pid can't collide with a real process' cwd.
     pid: 999_999_999,
     getForegroundProcess: vi.fn(() => null),
     write: vi.fn(),
@@ -341,8 +340,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       adapter.pauseProducer(id)
       await waitFor(() => lastSubprocess.pause.mock.calls.length > 0)
 
-      // Drop the daemon out from under the adapter: the in-flight pause has no
-      // matching resume anymore.
+      // Drop the daemon out from under the adapter: the in-flight pause now has no matching resume.
       await server.shutdown()
       await waitFor(() => !(adapter as unknown as { client: DaemonClient }).client.isConnected())
 
@@ -487,27 +485,18 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       expect(await adapter.getAppliedSize(id)).toEqual({ cols: 120, rows: 40 })
     })
 
-    // Why: this is the regression the fix targets. resize() is a fire-and-forget
-    // notify; a resize that arrives after the session exited is silently dropped
-    // daemon-side. getAppliedSize must keep reporting the last size the PTY
-    // genuinely took (the stale pre-exit dims) rather than the dropped request —
-    // so the renderer can tell its requested size never landed. The old
-    // requested-size cache would have masked the drop.
+    // Why: a resize after exit is a dropped fire-and-forget notify; getAppliedSize must report the PTY's last real size, not the drop.
     it('does not advance when a resize is dropped after the session exited', async () => {
       const { id } = await adapter.spawn({ cols: 200, rows: 50 })
 
-      // Simulate the child exiting, then a late narrow resize racing in. The
-      // daemon Session.resize early-returns for an exited session, so the child
-      // is never resized and the applied size never becomes the requested 80×24.
+      // Child exits, then a late narrow resize races in; daemon Session.resize early-returns for an exited session so 80×24 never lands.
       lastSubprocess._simulateExit(0)
       await new Promise((r) => setTimeout(r, 50))
 
       adapter.resize(id, 80, 24)
       await new Promise((r) => setTimeout(r, 50))
 
-      // The drop must be visible: the subprocess was never resized to the narrow
-      // dims the renderer requested, and getAppliedSize never reports 80 cols —
-      // it stays wide (or null once reaped), never masking the drop as "applied".
+      // The drop must stay visible: never resized to 80 cols, and getAppliedSize never reports 80 (stays wide, or null once reaped).
       expect(lastSubprocess.resize).not.toHaveBeenCalledWith(80, 24)
       const applied = await adapter.getAppliedSize(id)
       expect(applied?.cols).not.toBe(80)
@@ -545,8 +534,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       expect(lastSubprocess.forceKill).toHaveBeenCalled()
     })
 
-    // Why: shutdown can be the first lazy-client operation after restart; it
-    // must connect before killing so a healthy session is not orphaned (#7742).
+    // Why: shutdown can be the first lazy-client op after restart; connect before killing or a healthy session is orphaned (#7742).
     it('kills a live session from a fresh adapter that has not connected yet', async () => {
       const { id } = await adapter.spawn({ cols: 80, rows: 24 })
 
@@ -583,9 +571,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
   })
 
   describe('sessionsNeedingFullCheckpoint cleanup (leak regression)', () => {
-    // Why: the cold-restore path flags a session for a full checkpoint. If the
-    // session exits before that checkpoint lands, the flag was never cleared and
-    // leaked a permanent Set entry for the daemon's lifetime.
+    // Why: cold-restore flags a session for a full checkpoint; exiting before it lands leaked a permanent Set entry for the daemon's life.
     it('clears the pending full-checkpoint flag when a session exits', async () => {
       const { id } = await adapter.spawn({ cols: 80, rows: 24 })
       const internals = adapter as unknown as { sessionsNeedingFullCheckpoint: Set<string> }
@@ -834,11 +820,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
     })
 
     it('evicts oldest tombstone when exceeding limit', async () => {
-      // Why: MAX_TOMBSTONES is 1000, but spawning that many real sessions is
-      // slow. Instead verify the eviction logic by spawning a small batch and
-      // checking the oldest tombstone is gone after crossing the cap. We access
-      // the private map size via the public API: the oldest session should
-      // become spawnable again once evicted.
+      // Why: MAX_TOMBSTONES is 1000; spawning that many is slow, so verify eviction with a small batch via the public spawn API.
       const ids: string[] = []
       for (let i = 0; i < 5; i++) {
         const id = `evict-${i}`
@@ -859,8 +841,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       await adapter.spawn({ cols: 80, rows: 24, sessionId: ids[0] })
       await adapter.shutdown(ids[0], { immediate: true })
 
-      // First tombstone was re-added at the end of the Map, so eviction
-      // order is now [evict-1, evict-2, evict-3, evict-4, evict-0]
+      // First tombstone was re-added at the Map's end, so eviction order is now [evict-1, evict-2, evict-3, evict-4, evict-0]
       await expect(adapter.spawn({ cols: 80, rows: 24, sessionId: ids[0] })).rejects.toThrow(
         'was explicitly killed'
       )
@@ -909,13 +890,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
     })
 
     it('kills sessions whose id does not match the minted format, even if id is in valid set', async () => {
-      // Why: parsePtySessionId rejects bare UUIDs (no `@@`) and ids without
-      // the `::` worktree shape. Such sessions can't be attributed to any
-      // current worktree and must be treated as orphans regardless of
-      // valid-set membership. Passing the bare-uuid as a member of
-      // validWorktreeIds proves the new strict parser short-circuits the
-      // membership check — under the old loose parser this session would
-      // have been kept.
+      // Why: parsePtySessionId rejects ids with no worktree shape, so they're orphaned regardless of valid-set membership.
       const sessionId = 'bare-uuid-no-separators'
       await adapter.spawn({ cols: 80, rows: 24, sessionId })
 
@@ -963,8 +938,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       lastSubprocess._simulateData('hello from pty\r\n')
       await new Promise((r) => setTimeout(r, 50))
 
-      // Why: checkpoint-based persistence does not write on every data event.
-      // No scrollback.bin should exist — checkpoints write checkpoint.json on a timer.
+      // Why: checkpoint-based persistence writes checkpoint.json on a timer, never scrollback.bin per data event.
       expect(existsSync(join(historyDir, getHistorySessionDirName(id), 'scrollback.bin'))).toBe(
         false
       )
@@ -988,8 +962,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
 
         await new Promise((r) => setTimeout(r, 80))
 
-        // Why: idle terminals can be numerous. A periodic pass with no data
-        // must not serialize every live daemon session just because it exists.
+        // Why: idle terminals can be numerous; a periodic pass with no data must not serialize every live session.
         expect(appendSpy).not.toHaveBeenCalled()
 
         lastSubprocess._simulateData('new output\r\n')
@@ -997,8 +970,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
         expect(appendSpy).toHaveBeenCalledWith(id, expect.any(Number), [
           { kind: 'output', data: 'new output\r\n' }
         ])
-        // Why: the periodic tick must persist increments, never re-serialize
-        // the full emulator buffer (the issue #5096 stall).
+        // Why: the periodic tick must persist increments, never re-serialize the full emulator buffer (the issue #5096 stall).
         expect(checkpointSpy).not.toHaveBeenCalled()
         const logPath = join(historyDir, getHistorySessionDirName(id), 'output.log')
         await waitFor(() => {
@@ -1125,15 +1097,13 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
         await expect(internals.checkpointSessions(['hot'])).resolves.toEqual(new Set(['hot']))
         expect(internals.historyManager.checkpoint).toHaveBeenCalledTimes(1)
 
-        // Second tick inside the cooldown: the overflow defers and flags the
-        // session; no snapshot write.
+        // Second tick inside the cooldown: the overflow defers and flags the session; no snapshot write.
         await expect(internals.checkpointSessions(['hot'])).resolves.toEqual(new Set())
         expect(internals.historyManager.checkpoint).toHaveBeenCalledTimes(1)
         expect(internals.sessionsNeedingFullCheckpoint.has('hot')).toBe(true)
         const requestsAfterSecondTick = internals.client.request.mock.calls.length
 
-        // Ticks 3..24 (a hot session over ~2 minutes): flagged + cooling down
-        // short-circuits with ZERO daemon RPCs and zero disk writes.
+        // Ticks 3..24 (a hot session over ~2 minutes): flagged + cooling down short-circuits with zero daemon RPCs and zero disk writes.
         for (let i = 0; i < 22; i++) {
           await expect(internals.checkpointSessions(['hot'])).resolves.toEqual(new Set())
         }
@@ -1152,8 +1122,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
         await internals.checkpointSessions(['hot'])
         expect(internals.historyManager.checkpoint).toHaveBeenCalledTimes(1)
 
-        // Cooldown is active, but quit/sleep-time persistence must not be
-        // deferred — stale-on-crash is acceptable, stale-on-clean-exit is not.
+        // Cooldown is active, but quit/sleep persistence must not defer — stale-on-crash is acceptable, stale-on-clean-exit is not.
         await expect(internals.checkpointSessions(['hot'], { final: true })).resolves.toEqual(
           new Set(['hot'])
         )
@@ -1297,8 +1266,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
         await historyAdapter.shutdown(id, { immediate: true, keepHistory: true })
         const metaPath = join(historyDir, getHistorySessionDirName(id), 'meta.json')
         const checkpointPath = join(historyDir, getHistorySessionDirName(id), 'checkpoint.json')
-        // Why: keep-history sleep stays unclean so cold restore remains eligible;
-        // the final checkpoint is the deterministic handoff signal.
+        // Why: keep-history sleep stays unclean so cold restore stays eligible; the final checkpoint is the deterministic handoff signal.
         expect(JSON.parse(readFileSync(metaPath, 'utf-8')).endedAt).toBeNull()
         expect(JSON.parse(readFileSync(checkpointPath, 'utf-8')).snapshotAnsi).toContain(
           'first cycle content'
@@ -1532,11 +1500,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
     })
 
     it('cold-restores an alt-screen agent snapshot as scrollback on wake (hibernation)', async () => {
-      // Why: agent hibernation force-kills Claude/Codex while still in their
-      // alt-screen TUI, so scrollbackAnsi is empty. The fix falls back to the
-      // saved snapshot so the pane repaints the agent's last frame instead of
-      // coming back blank. (The payload is snapshotAnsi alone — no
-      // rehydrateSequences — so it never re-enters alt-screen.)
+      // Why: hibernation force-kills the agent in alt-screen (empty scrollbackAnsi); fall back to the snapshot so the pane repaints instead of blanking.
       const sessionId = 'cold-restore-alt-screen'
       const sessionDir = join(historyDir, getHistorySessionDirName(sessionId))
       mkdirSync(sessionDir, { recursive: true })
@@ -1578,14 +1542,12 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       const result = await historyAdapter.spawn({ cols: 80, rows: 24, sessionId })
       expect(result.coldRestore).toBeDefined()
       expect(result.coldRestore!.scrollback).toContain('Claude Code')
-      // The payload must NOT re-enter alt-screen — that would fight the
-      // relaunched agent's repaint and the renderer's POST_REPLAY_MODE_RESET.
+      // The payload must NOT re-enter alt-screen — it would fight the relaunched agent's repaint and the renderer's POST_REPLAY_MODE_RESET.
       expect(result.coldRestore!.scrollback).not.toContain('\x1b[?1049h')
     })
 
     it('skips cold restore for an alt-screen session with an empty snapshot', async () => {
-      // Why: alt-screen entered before any content → nothing to show. Keep the
-      // no-op (blank) rather than fabricate a payload.
+      // Why: alt-screen entered before any content → nothing to show; keep the no-op rather than fabricate a payload.
       const sessionId = 'cold-restore-alt-screen-empty'
       const sessionDir = join(historyDir, getHistorySessionDirName(sessionId))
       mkdirSync(sessionDir, { recursive: true })
@@ -1661,10 +1623,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
         lastSubprocess._simulateData('revived session output\r\n')
         await waitFor(() => checkpointSpy.mock.calls.length === 1)
 
-        // Why: appending the fresh session's records to the pre-crash log
-        // would be rejected by the sequence check on a second crash, reverting
-        // the restore to pre-crash content. The full checkpoint resets the log
-        // to a new generation.
+        // Why: appending fresh records to the pre-crash log would fail the sequence check on a second crash; a full checkpoint resets the log to a new generation.
         expect(appendSpy).not.toHaveBeenCalled()
         expect(checkpointSpy).toHaveBeenCalledWith(
           sessionId,
@@ -1703,14 +1662,12 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
         lastFullCheckpointAt: Map<string, number>
         sessionsNeedingFullCheckpoint: Set<string>
       }
-      // A daemon respawn inside one adapter keeps this map: seed a fresh
-      // cooldown as if the pre-crash generation just snapshotted.
+      // A daemon respawn inside one adapter keeps this map, so seed a fresh cooldown as if the pre-crash generation just snapshotted.
       internals.lastFullCheckpointAt.set(sessionId, Date.now())
 
       await historyAdapter.spawn({ cols: 80, rows: 24, sessionId })
 
-      // The revived generation has no checkpoint of its own — the re-anchor
-      // must not inherit the previous generation's cooldown.
+      // The revived generation has no checkpoint of its own — the re-anchor must not inherit the previous generation's cooldown.
       expect(internals.sessionsNeedingFullCheckpoint.has(sessionId)).toBe(true)
       expect(internals.lastFullCheckpointAt.has(sessionId)).toBe(false)
     })
@@ -1721,10 +1678,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       await first.spawn({ cols: 80, rows: 24, sessionId })
       first.dispose()
 
-      // A fresh adapter (app relaunch) attaches to the still-live daemon
-      // session. The old adapter may have drained records it never persisted
-      // (deferred hot-session tick), so appends must not resume until a full
-      // snapshot re-anchors the log.
+      // The old adapter may have drained records it never persisted (deferred hot-session tick), so appends must wait for a full snapshot to re-anchor the log.
       historyAdapter = new DaemonPtyAdapter({ socketPath, tokenPath, historyPath: historyDir })
       const internals = historyAdapter as unknown as {
         sessionsNeedingFullCheckpoint: Set<string>
@@ -1740,9 +1694,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       const sessionId = 'warm-reattach-skip-replay'
       const first = new DaemonPtyAdapter({ socketPath, tokenPath, historyPath: historyDir })
       await first.spawn({ cols: 80, rows: 24, cwd: '/home/user', sessionId })
-      // Why disconnectOnly: the production app-quit path leaves meta.endedAt
-      // null so the session stays crash-recoverable — the state every app
-      // relaunch with a live daemon sees.
+      // Why disconnectOnly: the app-quit path leaves meta.endedAt null, keeping the session crash-recoverable like every relaunch with a live daemon.
       await first.disconnectOnly()
 
       historyAdapter = new DaemonPtyAdapter({ socketPath, tokenPath, historyPath: historyDir })
@@ -1800,12 +1752,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
         }
       ).client
       const originalRequest = client.request.bind(client)
-      // Why: simulates the probe→createOrAttach race — the probe sees the
-      // session alive, but it is gone by the time createOrAttach runs. The
-      // meta rewrite mimics the dying session's exit event beating the
-      // createOrAttach reply and writing endedAt via closeSession; the
-      // fallback detect must still restore instead of falling through to
-      // openSession (which would delete the checkpoint).
+      // Why: simulates the probe→createOrAttach race (session dies mid-call, writing endedAt); fallback detect must still restore, not fall through to openSession which deletes the checkpoint.
       vi.spyOn(client, 'request').mockImplementation(async (type: string, payload?: unknown) => {
         if (type === 'getSize') {
           return { size: { cols: 100, rows: 30 } }
@@ -1831,8 +1778,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
 
       expect(result.coldRestore).toBeDefined()
       expect(result.coldRestore!.scrollback).toContain('raced output')
-      // The unseeded race winner is replaced before exposure, so the retained
-      // shell uses the recovered dimensions as well as the recovered history.
+      // The unseeded race winner is replaced before exposure, so the retained shell uses recovered dimensions as well as history.
       expect(lastSpawnOpts).toMatchObject({ sessionId, cols: 100, rows: 30 })
       // The recovery data must survive — openSession would have deleted it.
       expect(existsSync(join(sessionDir, 'scrollback.bin'))).toBe(true)
@@ -1868,8 +1814,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
         }
       ).client
       const originalRequest = client.request.bind(client)
-      // Why: an old daemon rejects the unknown getSize method; the spawn must
-      // behave exactly like the unprobed path.
+      // Why: an old daemon rejects the unknown getSize method; the spawn must behave exactly like the unprobed path.
       vi.spyOn(client, 'request').mockImplementation((type: string, payload?: unknown) => {
         if (type === 'getSize') {
           return Promise.reject(new Error('Unknown request type'))
@@ -2005,9 +1950,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
 
       await new Promise((r) => setTimeout(r, 50))
 
-      // Why: checkpoint-based persistence opens the session for future
-      // checkpointing but does not seed scrollback.bin. New data is persisted
-      // via periodic checkpoint timer, not per-chunk appendData.
+      // Why: checkpoint-based persistence doesn't seed scrollback.bin — new data lands via the periodic checkpoint timer, not per-chunk appendData.
       const meta = JSON.parse(
         readFileSync(join(historyDir, getHistorySessionDirName(sessionId), 'meta.json'), 'utf-8')
       )
@@ -2184,10 +2127,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
     })
 
     it('treats a hello handshake timeout as daemon-gone and respawns (#8689)', async () => {
-      // Why: a wedged daemon accepts the socket connection but never answers
-      // hello, so ensureConnected() rejects with "Hello response timed out".
-      // That must be classified as daemon-gone so withDaemonRetry respawns and
-      // retries — otherwise every terminal spawn fails against the wedge forever.
+      // Why: a wedged daemon accepts the socket but never answers hello; classify as daemon-gone so withDaemonRetry respawns, else every spawn fails forever.
       const realEnsureConnected = DaemonClient.prototype.ensureConnected
       const ensureConnectedSpy = vi
         .spyOn(DaemonClient.prototype, 'ensureConnected')
@@ -2355,12 +2295,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
     })
   })
 
-  // Why: the restart flow (docs/daemon-staleness-ux.md §Phase 1 step 1) relies
-  // on these two primitives to fan synthetic pty:exit out to every attached
-  // session *before* tearing the adapter down. The design doc calls out
-  // session.ts:246-252 as the reason — the daemon's kill-all-and-shutdown
-  // explicitly does NOT fan exits back through onExit. Without the fanout the
-  // renderer would black-hole writes against a disposed adapter.
+  // Why: daemon kill-all-and-shutdown doesn't fan exits through onExit, so these primitives synthesize pty:exit before dispose, else the renderer black-holes writes (docs/daemon-staleness-ux.md §Phase 1).
   describe('fanoutSyntheticExits / getActiveSessionIds (restart primitives)', () => {
     it('reports every live spawn in getActiveSessionIds', async () => {
       const { id: id1 } = await adapter.spawn({ cols: 80, rows: 24 })
diff --git a/src/main/daemon/daemon-pty-adapter.ts b/src/main/daemon/daemon-pty-adapter.ts
index 8b6e3151776..8acd5fac2fb 100644
--- a/src/main/daemon/daemon-pty-adapter.ts
+++ b/src/main/daemon/daemon-pty-adapter.ts
@@ -1,6 +1,4 @@
-/* oxlint-disable max-lines -- Why: history error-logging .catch() chains add ~10 lines of
-safety wiring spread across spawn/event-routing; splitting would scatter tightly coupled
-adapter ↔ history lifecycle logic. */
+/* oxlint-disable max-lines -- Why: history .catch() safety wiring spread across spawn/event-routing is tightly coupled to the adapter↔history lifecycle. */
 import { basename } from 'node:path'
 import { existsSync } from 'node:fs'
 import { DaemonClient } from './client'
@@ -47,8 +45,7 @@ type ColdRestorePayload = {
 }
 
 function getRecoveredHistorySeed(restoreInfo: ColdRestoreInfo): string | null {
-  // Why: alt-screen snapshots represent the TUI buffer; prefer its normal
-  // scrollback so a dead TUI is not revived as the fresh shell's active screen.
+  // Why: alt-screen snapshots are the TUI buffer; prefer its normal scrollback so a dead TUI isn't revived as the fresh shell's active screen.
   return restoreInfo.modes.alternateScreen
     ? restoreInfo.scrollbackAnsi || restoreInfo.snapshotAnsi || null
     : restoreInfo.rehydrateSequences + restoreInfo.snapshotAnsi
@@ -69,11 +66,9 @@ export type DaemonPtyAdapterOptions = {
   socketPath: string
   tokenPath: string
   protocolVersion?: number
-  /** Directory for disk-based terminal history. When set, the adapter writes
-   *  raw PTY output to disk for cold restore on daemon crash. */
+  /** Directory for disk-based terminal history; when set, raw PTY output is written to disk for cold restore on daemon crash. */
   historyPath?: string
-  /** Called when the daemon socket is unreachable (process died). Expected to
-   *  fork a fresh daemon so the next connection attempt can succeed. */
+  /** Called when the daemon socket is unreachable; forks a fresh daemon so the next connect can succeed. */
   respawn?: () => Promise<void | (() => void)>
 }
 
@@ -104,10 +99,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
   private respawnFn: (() => Promise<void | (() => void)>) | null
   private pendingRespawnAdoptionRelease: (() => void) | null = null
   private respawnAdoptionClosed = false
-  // Why: multiple pane mounts can call spawn() concurrently. If the daemon is
-  // dead, all calls enter withDaemonRetry's catch block at once. Without a
-  // lock, each would fork its own daemon process. This promise coalesces
-  // concurrent respawns so only the first caller forks; the rest await it.
+  // Why: concurrent spawn() calls hitting a dead daemon would each fork their own; this promise coalesces respawns so only the first forks and the rest await it.
   private respawnPromise: Promise<void> | null = null
   private dataListeners: ((payload: {
     id: string
@@ -121,54 +113,32 @@ export class DaemonPtyAdapter implements IPtyProvider {
   private removeEventListener: (() => void) | null = null
   private initialCwds = new Map<string, string>()
   private wslDistrosBySessionId = new Map<string, string>()
-  // Why: React re-renders and StrictMode double-mounts can call createOrAttach
-  // for a session the user just killed. Without tombstones, the daemon would
-  // create a fresh session — resurrecting a terminal the user explicitly closed.
-  // Uses a Map<id, timestamp> so eviction removes the oldest by insertion order,
-  // matching terminal-host.ts tombstone semantics.
+  // Why: StrictMode/re-render remounts can call createOrAttach for a just-killed session; tombstones stop the daemon resurrecting it (Map evicts oldest-first, per terminal-host.ts).
   private killedSessionTombstones = new Map<string, number>()
-  // Why: React StrictMode double-mounts: mount → cold restore → unmount →
-  // mount → ??? The sticky cache returns the same cold restore data on the
-  // second mount until the renderer explicitly acknowledges it.
+  // Why: React StrictMode double-mounts; this sticky cache returns the same cold restore data on remount until the renderer acknowledges it.
   private coldRestoreCache = new Map<string, ColdRestorePayload>()
   private sleepRestoreSessionIds = new Set<string>()
   private activeSessionIds = new Set<string>()
   private dirtySessionVersions = new Map<string, number>()
-  // Why: a cold-restored session is a fresh shell whose on-disk checkpoint and
-  // log belong to the pre-crash session. Incremental appends would land on
-  // that stale log (and be rejected by its sequence check on restore), so the
-  // first tick must re-anchor with a full snapshot checkpoint, which resets
-  // the log to a new generation.
+  // Why: a cold-restored session is a fresh shell atop a pre-crash log; incremental appends would be rejected on restore, so the first tick re-anchors with a full snapshot.
   private sessionsNeedingFullCheckpoint = new Set<string>()
   private checkpointTimer: ReturnType<typeof setTimeout> | null = null
   private checkpointInFlight: Promise<void> | null = null
-  // Why: checkpoint-based persistence requires the getSnapshot RPC (v4+).
-  // Legacy daemons reject it, causing noisy log spam every 5 seconds.
+  // Why: checkpoint persistence needs the getSnapshot RPC (v4+); legacy daemons reject it, spamming logs every 5s.
   private supportsCheckpoints: boolean
-  // Why: incremental checkpoints require the takePendingOutput RPC (v13+).
-  // Against older daemons the tick falls back to full-snapshot checkpoints.
+  // Why: incremental checkpoints need the takePendingOutput RPC (v13+); older daemons fall back to full-snapshot checkpoints.
   private supportsIncrementalCheckpoints: boolean
-  // Why: producer pause/resume notifications require v19+; legacy daemons
-  // must never see them, so gating makes them silent no-ops there.
+  // Why: producer pause/resume notifications require v19+; gate them to silent no-ops on legacy daemons.
   private supportsProducerFlowControl: boolean
   private supportsAuthoritativeBufferSnapshots: boolean
   private supportsStartupIngress: boolean
   private pausedProducerSessionIds = new Set<string>()
-  // Why tracked here: the daemon's background set (keep-tail stream thinning
-  // + transient-fact scan authority) dies with the daemon process/socket;
-  // re-sync it on a fresh connection so hidden panes stay thinned.
+  // Why tracked here: the daemon's background set dies with the daemon process/socket; re-sync on a fresh connection so hidden panes stay thinned.
   private backgroundedSessionIds = new Set<string>()
-  // Why: a daemon that survives a socket drop can still hold a pause whose
-  // resume died with the connection. Owe those sessions a resume on the next
-  // connect; the daemon's 5s failsafe covers the window in between.
+  // Why: a daemon surviving a socket drop can hold a pause whose resume died with the connection; owe a resume on reconnect (daemon's 5s failsafe covers the gap).
   private producerResumesOwedOnReconnect = new Set<string>()
   private static CHECKPOINT_INTERVAL_MS = 5_000
-  // Why: a streaming session (build logs, `yes`) re-triggers a full multi-MB
-  // snapshot checkpoint on every 5s tick via pending-buffer overflow or the
-  // log-size cap — hundreds of MB/min of disk writes from one busy terminal.
-  // Bounding cap/overflow-triggered snapshots per session trades bounded
-  // cold-crash scrollback staleness (warm reattach and final checkpoints are
-  // unaffected and bypass this) for a ~9x cut in worst-case write volume.
+  // Why: streaming sessions re-trigger full multi-MB checkpoints every tick; this cooldown caps cap/overflow snapshots per session (~9x less writes, bounded cold-crash staleness).
   private static FULL_CHECKPOINT_COOLDOWN_MS = 45_000
   private lastFullCheckpointAt = new Map<string, number>()
 
@@ -247,22 +217,13 @@ export class DaemonPtyAdapter implements IPtyProvider {
     }
 
     await this.ensureConnected()
-    // Why before createOrAttach: a preserved v19 daemon may remember this
-    // session as backgrounded. Ordered control delivery clears it before any
-    // newly attached stream bytes can be thinned without a recoverable seq.
+    // Why before createOrAttach: a preserved v19 daemon may still think this session is backgrounded; clear it before attached bytes get thinned without a recoverable seq.
     if (!this.supportsAuthoritativeBufferSnapshots) {
       this.setPtyBackgrounded(sessionId, false)
     }
 
-    // Why: detect crash-recovery history before spawning a replacement PTY so
-    // the revived shell inherits the recovered cwd and dimensions instead of
-    // whatever the current renderer happened to request on mount.
-    // Why probe aliveness first: detectColdRestore synchronously replays the
-    // full checkpoint + log (up to ~5MB) through a scratch emulator on the
-    // main process, but a live daemon session ignores spawn params and its
-    // own snapshot supersedes disk — the replay result would be discarded.
-    // getSize is a read-only probe; on error/unsupported it degrades to the
-    // full detect.
+    // Why detect crash-recovery history before spawning: the revived shell should inherit the recovered cwd/dims, not the renderer's mount-time request.
+    // Why probe aliveness first: detectColdRestore replays up to ~5MB on the main process, but a live session's snapshot supersedes disk, so the replay would be wasted.
     let restoreInfo: ColdRestoreInfo | null = null
     let restoreSkippedForLiveSession = false
     if (this.historyReader?.hasRestorableHistory(sessionId)) {
@@ -301,11 +262,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
         command: opts.command,
         startupCommandDelivery: opts.startupCommandDelivery,
         launchAgent: opts.launchAgent,
-        // Why: without this, the daemon always spawns cmd.exe (COMSPEC) or
-        // PowerShell as a fallback — regardless of which shell the renderer
-        // asked for in the "+" menu or persisted as the default. Forwarding
-        // the override makes the daemon path behave the same as the in-process
-        // LocalPtyProvider.
+        // Why: without forwarding the override, the daemon falls back to cmd.exe/PowerShell, ignoring the shell the renderer chose; this matches LocalPtyProvider.
         shellOverride: opts.shellOverride,
         terminalWindowsWslDistro: opts.terminalWindowsWslDistro,
         terminalWindowsPowerShellImplementation: opts.terminalWindowsPowerShellImplementation,
@@ -320,8 +277,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
     let scrollback = restoreInfo ? getRecoveredHistorySeed(restoreInfo) : null
     let result = await createOrAttach(scrollback)
     let providerWslDistro = result.wslDistro === undefined ? wslDistro : result.wslDistro
-    // Why: explicit null from a current daemon overrides the caller's WSL
-    // preference; undefined preserves compatibility with older daemons.
+    // Why: explicit null from a current daemon overrides the caller's WSL preference; undefined keeps compatibility with older daemons.
     wslDistro = providerWslDistro ?? undefined
     if (wslDistro) {
       this.wslDistrosBySessionId.set(sessionId, wslDistro)
@@ -335,20 +291,13 @@ export class DaemonPtyAdapter implements IPtyProvider {
       this.initialCwds.set(sessionId, effectiveCwd)
     }
 
-    // Why: the daemon RPC returns the shell pid of the backing subprocess.
-    // Surfacing it through PtySpawnResult lets ipc/pty register with the
-    // memory collector without a provider-specific accessor.
+    // Why: surface the daemon's shell pid via PtySpawnResult so ipc/pty registers with the memory collector without a provider-specific accessor.
     let pid = typeof result.pid === 'number' && result.pid > 0 ? result.pid : null
 
-    // Why: check sticky cache first — StrictMode double-mounts call spawn
-    // twice. The second call finds an existing daemon session (isNew=false)
-    // but should still return the cached cold restore data.
+    // Why: check sticky cache first — StrictMode double-mounts call spawn twice; the second call (isNew=false) must still return cached cold restore data.
     const cachedRestore = this.coldRestoreCache.get(sessionId)
     if (cachedRestore) {
-      // Why: wake after sleep also lands here, and the slept session's active
-      // tracking and history writer were dropped when sleep killed the PTY.
-      // Without re-registering both, checkpoints stop after wake and the
-      // second sleep/wake cycle restores a blank terminal.
+      // Why: wake-after-sleep lands here too; sleep dropped active tracking + the history writer, so re-register both or the next sleep/wake restores a blank terminal.
       this.activeSessionIds.add(sessionId)
       if (this.historyManager) {
         this.historyManager.reopenSession(sessionId)
@@ -363,20 +312,13 @@ export class DaemonPtyAdapter implements IPtyProvider {
       }
     }
 
-    // Why: the probe→createOrAttach gap is racy — the session can exit (or
-    // enter termination) in between, so the daemon spawned a fresh shell.
-    // Detect now so scrollback restore matches the unprobed path; only the
-    // new shell's cwd/dims came from the renderer request in this rare case.
-    // Why ignoreCleanEnd: the raced session's exit event (stream socket) can
-    // beat the createOrAttach reply and write endedAt via closeSession; that
-    // must not null the restore here, or the openSession branch below would
-    // delete the checkpoint instead of restoring it.
+    // Why: the probe→createOrAttach gap is racy — the session can exit in between, so re-detect to match the unprobed restore path.
+    // Why ignoreCleanEnd: the raced exit event can write endedAt before the reply; nulling the restore here would delete the checkpoint instead of restoring it.
     if (result.isNew && restoreSkippedForLiveSession) {
       restoreInfo = detectColdRestore({ ignoreCleanEnd: true })
       scrollback = restoreInfo ? getRecoveredHistorySeed(restoreInfo) : null
       if (restoreInfo && scrollback) {
-        // Why: the aliveness probe raced with session death, so the first
-        // create lacked recovery bytes. Replace it before exposing the PTY.
+        // Why: the aliveness probe raced with session death, so the first create lacked recovery bytes; replace it before exposing the PTY.
         await this.client.request('kill', { sessionId, immediate: true })
         effectiveCwd = restoreInfo.cwd
         effectiveCols = restoreInfo.cols
@@ -401,26 +343,19 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.activeSessionIds.add(sessionId)
     const providerSequence = providerSequenceForSpawn(result)
 
-    // Cold restore: daemon created a new session but disk history shows
-    // an unclean shutdown → return saved scrollback so the renderer can
-    // display the previous terminal content.
+    // Cold restore: daemon made a new session but disk history shows an unclean shutdown → return saved scrollback.
     if (restoreInfo && (result.isNew || result.historySeeded === false)) {
       const coldRestore = this.buildColdRestorePayload(restoreInfo)
       const canReanchorHistory = !scrollback || result.historySeeded === true
-      // Why: use registerWriter (not openSession) to avoid deleting the
-      // existing checkpoint.json. If the revived daemon crashes again before
-      // the next 5s tick, the checkpoint is the only recovery data available.
+      // Why: registerWriter (not openSession) avoids deleting checkpoint.json — the only recovery data if the revived daemon crashes before the next tick.
       if (this.historyManager) {
         if (canReanchorHistory) {
           this.historyManager.registerWriter(sessionId)
           this.sessionsNeedingFullCheckpoint.add(sessionId)
-          // Why: the revived generation has no valid checkpoint of its own; a
-          // cooldown inherited from the pre-crash generation (daemon respawn
-          // within one adapter) must not defer this re-anchor.
+          // Why: the revived generation has no valid checkpoint yet; a cooldown inherited from the pre-crash generation must not defer this re-anchor.
           this.lastFullCheckpointAt.delete(sessionId)
         } else {
-          // Preserve the old recovery files when the new daemon cannot include
-          // them; a fresh-only checkpoint would make the data loss permanent.
+          // Preserve old recovery files when the new daemon can't include them; a fresh-only checkpoint would make the data loss permanent.
           this.historyManager.suspendSession(sessionId)
         }
       }
@@ -454,21 +389,13 @@ export class DaemonPtyAdapter implements IPtyProvider {
         })
         .catch((err) => console.warn('[history] openSession failed:', sessionId, err))
     } else if (this.historyManager && result.historySeeded === false) {
-      // Why: the daemon keeps this failure bit with the live session, so a new
-      // adapter cannot promote its fresh-only snapshot after an app restart.
+      // Why: the daemon keeps this failure bit with the live session, so a new adapter can't promote its fresh-only snapshot after restart.
       this.historyManager.suspendSession(sessionId)
     } else if (this.historyManager) {
-      // Why: on warm reattach after app relaunch, the HistoryManager is a
-      // fresh instance with no writers. registerWriter adds the writer
-      // without overwriting meta.json or deleting the existing checkpoint
-      // (which is the only valid recovery data until the next tick).
+      // Why: on warm reattach after relaunch the HistoryManager is fresh; registerWriter adds a writer without deleting the still-only-valid checkpoint.
       this.historyManager.registerWriter(sessionId)
       if (!wasAlreadyManaged) {
-        // Why: a previous adapter may have drained daemon records it never
-        // persisted (a deferred hot-session tick) before the app died.
-        // Appending increments past that unknown drain point would put a seq
-        // gap in the log, which the restore reader rejects wholesale. Force a
-        // full snapshot to re-anchor before any further appends.
+        // Why: a previous adapter may have drained records it never persisted, so appending would leave a seq gap the reader rejects; force a full snapshot to re-anchor.
         this.sessionsNeedingFullCheckpoint.add(sessionId)
         this.lastFullCheckpointAt.delete(sessionId)
       }
@@ -491,10 +418,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       result.snapshot.scrollbackAnsi +
       result.snapshot.rehydrateSequences +
       result.snapshot.snapshotAnsi
-    // Why kitty flags ride beside the payload, not inside it: the snapshot
-    // string reaches renderer xterms too, where POST_REPLAY_REATTACH_RESET's
-    // deliberate kitty reset must win. Only the runtime emulator re-seed
-    // consumes the flags (terminal-query-authority.md §kitty).
+    // Why kitty flags ride beside the payload, not inside it: the snapshot reaches renderer xterms where POST_REPLAY_REATTACH_RESET's kitty reset must win (terminal-query-authority.md §kitty).
     const kittyKeyboardFlags = result.snapshot.modes.kittyKeyboardFlags
     return {
       id: sessionId,
@@ -510,9 +434,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
         : {}),
       isReattach: true,
       isAlternateScreen: isAltScreen,
-      // Why: carry the mid-escape tail so the renderer can write it after the
-      // reattach reset — without it the local daemon reattach path renders a
-      // split escape's continuation literally, unlike the remote path (#7329).
+      // Why: carry the mid-escape tail so the renderer writes it after the reattach reset, else a split escape renders literally (#7329).
       ...(result.snapshot.pendingEscapeTailAnsi
         ? { pendingEscapeTailAnsi: result.snapshot.pendingEscapeTailAnsi }
         : {})
@@ -563,14 +485,12 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.client.notify('resumePty', { sessionId: id })
   }
 
-  // Why fire-and-forget (like pausePty): a delivery hint for the daemon's
-  // keep-tail stream thinning.
+  // Why fire-and-forget (like pausePty): just a delivery hint for the daemon's keep-tail stream thinning.
   setPtyBackgrounded(id: string, background: boolean): void {
     if (!this.supportsProducerFlowControl) {
       return
     }
-    // Why: preserved v19 daemons can thin but cannot return the absolute
-    // snapshot sequence needed to recover a gap. Clear their stale hint too.
+    // Why: preserved v19 daemons can thin but can't return the absolute snapshot sequence to recover a gap; clear their stale hint too.
     const safeBackground = this.supportsAuthoritativeBufferSnapshots && background
     if (safeBackground) {
       this.backgroundedSessionIds.add(id)
@@ -613,8 +533,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       if (coldRestore) {
         this.coldRestoreCache.set(id, coldRestore)
         this.sleepRestoreSessionIds.add(id)
-        // Why: physical exit must not mark intentional sleep as a clean end;
-        // the final checkpoint remains the wake-time recovery authority.
+        // Why: physical exit must not mark intentional sleep as a clean end; the final checkpoint stays the wake-time recovery authority.
         this.historyManager?.suspendSession(id)
       }
     }
@@ -629,28 +548,20 @@ export class DaemonPtyAdapter implements IPtyProvider {
       this.coldRestoreCache.delete(id)
       this.sleepRestoreSessionIds.delete(id)
     }
-    // Why: the !keepHistory close path doesn't take a final checkpoint, so a
-    // session stranded in sessionsNeedingFullCheckpoint would never be cleared.
-    // (Under keepHistory the final checkpoint above already cleared the flag, so
-    // this is a harmless no-op there — kept unconditional to cover both paths.)
+    // Why: the !keepHistory path takes no final checkpoint, so clear sessionsNeedingFullCheckpoint here or it stays stranded (no-op under keepHistory).
     this.sessionsNeedingFullCheckpoint.delete(id)
     this.lastFullCheckpointAt.delete(id)
     this.stopCheckpointTimerIfIdle()
     this.initialCwds.delete(id)
     this.wslDistrosBySessionId.delete(id)
-    // Why: history removal is for the "user explicitly closed this terminal"
-    // path. Sleep also calls shutdown but expects scrollback to survive — wake
-    // re-spawns and the cold-restore reader needs the dir intact. Caller
-    // indicates intent via opts.keepHistory.
+    // Why: only remove history on explicit close; sleep also calls shutdown but wake needs the dir intact for cold restore (opts.keepHistory).
     if (this.historyManager && !opts.keepHistory) {
       void this.historyManager
         .removeSession(id)
         .catch((err) => console.warn('[history] removeSession failed:', id, err))
     }
 
-    // Why: tombstone rejects reattach against a session the user explicitly
-    // killed. Sleep legitimately reattaches on wake, so skip both the LRU bump
-    // and the size-cap eviction under keepHistory.
+    // Why: the tombstone rejects reattach to a user-killed session; sleep legitimately reattaches on wake, so skip it under keepHistory.
     if (!opts.keepHistory) {
       this.killedSessionTombstones.delete(id)
       this.killedSessionTombstones.set(id, Date.now())
@@ -673,13 +584,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
   }
 
   private buildColdRestorePayload(restoreInfo: ColdRestoreInfo): ColdRestorePayload | null {
-    // Why prefer scrollbackAnsi for alt-screen: snapshotAnsi is the alt buffer
-    // (vim/less/htop); normal sessions use the full snapshot + rehydrate.
-    // Why the snapshotAnsi fallback: a hibernated TUI agent (empty scrollback)
-    // would otherwise get `|| null` → blank pane on wake. snapshotAnsi *alone*
-    // (no rehydrateSequences — they start with \x1b[?1049h, which the
-    // renderer's POST_REPLAY_MODE_RESET does NOT undo) lands the last frame as
-    // normal scrollback. An empty snapshot still yields null → no-op.
+    // Why: alt-screen prefers normal scrollback, else snapshotAnsi alone — not rehydrate, which starts with \x1b[?1049h that POST_REPLAY_MODE_RESET won't undo — so a hibernated TUI's last frame isn't blank on wake.
     const scrollback = restoreInfo.modes.alternateScreen
       ? restoreInfo.scrollbackAnsi || restoreInfo.snapshotAnsi || null
       : restoreInfo.rehydrateSequences + restoreInfo.snapshotAnsi
@@ -714,12 +619,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
     return this.initialCwds.get(id) ?? ''
   }
 
-  // Why: resize() is a fire-and-forget notify, so a resize can be dropped
-  // daemon-side (session not yet alive, exited, invalid dims, cold-restore
-  // snapshot-col coercion) without the renderer knowing. This reads the size
-  // the daemon actually applied so the renderer can detect that drift on resume
-  // and re-assert. Null (RPC failure / unknown session) means "cannot confirm",
-  // which the renderer treats as a cue to re-forward once.
+  // Why: resize() is fire-and-forget and can be dropped daemon-side; read the actually-applied size so the renderer can detect drift and re-assert.
   async getAppliedSize(id: string): Promise<{ cols: number; rows: number } | null> {
     try {
       const result = await this.client.request<{ size: { cols: number; rows: number } | null }>(
@@ -745,8 +645,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
         ...(typeof opts.scrollbackRows === 'number' ? { scrollbackRows: opts.scrollbackRows } : {})
       })
       const snapshot = result.snapshot
-      // Why: older v19 daemons have no absolute output sequence. Their snapshot
-      // cannot safely reconcile stream bytes still queued on the other socket.
+      // Why: older v19 daemons lack an absolute output sequence, so their snapshot can't reconcile bytes queued on the other socket.
       if (!snapshot || typeof snapshot.outputSequence !== 'number') {
         return null
       }
@@ -781,8 +680,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
 
   async hasChildProcesses(id: string): Promise<boolean> {
     const foregroundProcess = await this.getForegroundProcess(id)
-    // Why: daemon-backed PTYs can host long-lived agents while the renderer is
-    // detached. Cleanup prompts must not treat those sessions like idle shells.
+    // Why: daemon-backed PTYs can host long-lived agents while detached; cleanup prompts must not treat them as idle shells.
     return foregroundProcess !== null && !isShellProcess(foregroundProcess)
   }
 
@@ -822,16 +720,13 @@ export class DaemonPtyAdapter implements IPtyProvider {
     // Sessions already live in the daemon — no revival needed
   }
 
-  /** Called on app launch. Lists daemon sessions, kills orphans whose
-   *  workspaceId no longer exists, and caches alive session IDs.
+  /** Called on app launch. Lists daemon sessions, kills orphans whose workspaceId
+   *  no longer exists, and caches alive session IDs.
    *
-   *  IMPORTANT: a session id embeds the worktree id it was minted under, which is
-   *  the worktree's *path* at spawn time. When a worktree folder is renamed, its
-   *  id changes but live sessions keep the old id. Callers MUST therefore seed
-   *  `validWorktreeIds` with each live worktree's `WorktreeMeta.priorWorktreeIds`
-   *  (the pre-rename aliases) or those sessions will be reaped as false orphans.
-   *  This reconcile has no production caller yet; wire the alias in when it gains
-   *  one. */
+   *  IMPORTANT: a session id embeds the worktree's path at spawn time, so a renamed
+   *  worktree keeps its old id. Callers MUST seed `validWorktreeIds` with each live
+   *  worktree's `WorktreeMeta.priorWorktreeIds` or those sessions get reaped as false
+   *  orphans. No production caller yet; wire the alias in when it gains one. */
   async reconcileOnStartup(validWorktreeIds: Set<string>): Promise<{
     alive: string[]
     killed: string[]
@@ -846,9 +741,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       if (!session.isAlive) {
         continue
       }
-      // Why: session IDs use the format `${worktreeId}@@${shortUuid}`. Sessions
-      // whose id does not match the minted format (worktreeId === null) cannot
-      // be tied to a live worktree and are treated as orphans.
+      // Why: an unminted session id (worktreeId === null) can't be tied to a live worktree, so it's treated as an orphan.
       const { worktreeId } = parsePtySessionId(session.sessionId)
 
       if (worktreeId === null || !validWorktreeIds.has(worktreeId)) {
@@ -860,10 +753,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
         killed.push(session.sessionId)
       } else {
         alive.push(session.sessionId)
-        // Why: background sessions discovered here may produce output before
-        // the user reattaches their pane. Without adding them to the checkpoint
-        // set, disconnectOnly()'s final checkpoint would skip them, leaving
-        // stale recovery data if the daemon later crashes.
+        // Why: track background sessions in the checkpoint set so disconnectOnly's final checkpoint doesn't leave stale recovery data.
         this.activeSessionIds.add(session.sessionId)
         this.historyManager?.registerWriter(session.sessionId)
       }
@@ -885,18 +775,14 @@ export class DaemonPtyAdapter implements IPtyProvider {
       .filter((s) => s.isAlive)
       .map((s) => ({
         id: s.sessionId,
-        // Why: OSC 7 may not arrive before destructive cleanup. Spawn cwd is
-        // still authoritative ownership until the daemon reports a live cwd.
+        // Why: OSC 7 may not arrive before cleanup; spawn cwd is authoritative until the daemon reports a live cwd.
         cwd: s.cwd ?? this.initialCwds.get(s.sessionId) ?? '',
         title: 'shell',
         ...(s.terminalHandle ? { terminalHandle: s.terminalHandle } : {})
       }))
   }
 
-  // Why: the Manage Sessions panel needs the full SessionInfo (pid, state,
-  // createdAt) per session for display; listProcesses drops that detail for
-  // the IPtyProvider contract. Keep both in parallel rather than widening
-  // the provider surface.
+  // Why keep both: the Manage Sessions panel needs full SessionInfo (pid/state/createdAt) that listProcesses drops for the IPtyProvider contract.
   async listSessions(): Promise<SessionInfo[]> {
     await this.ensureConnected()
     const result = await this.client.request<ListSessionsResult>('listSessions', undefined)
@@ -907,13 +793,8 @@ export class DaemonPtyAdapter implements IPtyProvider {
     return [...this.activeSessionIds]
   }
 
-  // Why: used by the "Restart daemon" handler to synthesize pty:exit for every
-  // live session *before* tearing down the adapter. The daemon's own
-  // kill-all-and-shutdown path explicitly suppresses onExit fanout
-  // (session.ts:246-252), so without this the renderer panes would black-hole
-  // writes to a disposed adapter forever. Reuses the existing exitListeners
-  // path so downstream cleanup (clearProviderPtyState, markClaudePtyExited,
-  // renderer pty:exit) runs exactly as it does on natural exit.
+  // Why: the daemon's kill-all-and-shutdown path suppresses onExit fanout (session.ts:246-252), so synthesize pty:exit
+  // for every live session before teardown or renderer panes black-hole writes to a disposed adapter forever.
   fanoutSyntheticExits(code: number): void {
     const ids = [...this.activeSessionIds]
     this.activeSessionIds.clear()
@@ -925,10 +806,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.stopCheckpointTimer()
     for (const id of ids) {
       this.coldRestoreCache.delete(id)
-      // Why: listener throws are intentionally *not* caught — matches the
-      // natural onExit fanout in setupEventRouting, so synthetic exits don't
-      // diverge in error semantics from real ones. A throwing listener is a
-      // bug that should surface loudly, not be silently swallowed.
+      // Why: don't catch listener throws — matches the natural onExit fanout so synthetic exits keep the same error semantics.
       // oxlint-disable-next-line unicorn/no-useless-spread -- copy-safe: listeners may unsubscribe during iteration
       for (const listener of [...this.exitListeners]) {
         listener({ id, code })
@@ -1008,9 +886,8 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.producerResumesOwedOnReconnect.clear()
     this.removeEventListener?.()
     this.removeEventListener = null
-    // Why: final checkpoints are written daemon-side in TerminalHost.dispose()
-    // which has direct access to sessions. The adapter only marks sessions as
-    // cleanly ended here so they don't trigger false cold restores.
+    // Why: final checkpoints are written daemon-side (TerminalHost.dispose); here the adapter only marks sessions
+    // cleanly ended so they don't trigger false cold restores.
     if (this.historyManager) {
       void this.historyManager
         .dispose()
@@ -1023,39 +900,28 @@ export class DaemonPtyAdapter implements IPtyProvider {
     if (this.protocolVersion < CLEAN_DISCONNECT_PROTOCOL_VERSION) {
       return
     }
-    // Why: an authenticated pair cancels the launch-adoption watchdog and gives
-    // a never-used adapter authority to retire its empty daemon during clean quit.
+    // Why: an authenticated pair cancels the adoption watchdog and lets a never-used adapter retire its empty daemon on quit.
     await this.client.ensureConnected()
   }
 
-  // Why: for in-process daemon mode, disconnect without flushing history.
-  // dispose() writes endedAt for all sessions, which would prevent cold
-  // restore. disconnectOnly() leaves history files in unclean state so
-  // the next launch detects them as crash-recoverable.
-  // We write a final checkpoint before disconnecting so that if the daemon
-  // later crashes while Orca is closed, checkpoint.json has recovery data.
+  // Why: unlike dispose(), leave history files unclean (no endedAt) so the next launch treats them as crash-recoverable,
+  // but still write a final checkpoint so a daemon crash while Orca is closed has recovery data.
   async disconnectOnly(): Promise<void> {
     this.respawnAdoptionClosed = true
     this.releasePendingRespawnAdoptionLease()
     this.stopCheckpointTimer()
-    // Why: wait for any in-flight timer pass to finish before starting
-    // the final checkpoint. Otherwise both passes race on the shared tmp
-    // file, risking ENOENT on rename and disabling future writes.
+    // Why: wait out an in-flight timer pass; racing on the shared tmp file risks ENOENT on rename, disabling future writes.
     if (this.checkpointInFlight) {
       await this.checkpointInFlight
     }
-    // Why: without a final checkpoint, sessions opened after the last timer
-    // tick have no checkpoint.json on disk. If the detached daemon later
-    // dies, detectColdRestore finds nothing to restore from. Must await
-    // before disconnecting — fire-and-forget would race with client.disconnect()
-    // and the pending getSnapshot RPCs would be rejected.
+    // Why: a final checkpoint covers sessions opened since the last tick (else cold restore finds nothing if the daemon
+    // later dies). Await it — fire-and-forget would race client.disconnect() and reject the pending getSnapshot RPCs.
     await this.checkpointAllSessions()
     this.dirtySessionVersions.clear()
     this.lastFullCheckpointAt.clear()
     this.coldRestoreCache.clear()
     this.wslDistrosBySessionId.clear()
-    // Why: the detached daemon keeps these PTYs alive for warm reattach; a
-    // pause left behind would block their shells for a failsafe window.
+    // Why: the detached daemon keeps these PTYs alive for warm reattach; a leftover pause would stall shells for a failsafe window.
     for (const id of this.pausedProducerSessionIds) {
       this.client.notify('resumePty', { sessionId: id })
     }
@@ -1065,16 +931,14 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.removeEventListener = null
     if (this.protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
       try {
-        // Why: only the authenticated daemon can atomically prove it is empty;
-        // one shared budget keeps a first connection plus retirement off quit's critical path.
+        // Why: only the authenticated daemon can atomically prove it's empty; a shared budget keeps this off quit's critical path.
         const deadlineMs = Date.now() + 250
         if (!this.client.isConnected()) {
           await this.client.ensureConnectedWithin(Math.max(1, deadlineMs - Date.now()))
         }
         await this.client.request('shutdownIfIdle', undefined, Math.max(1, deadlineMs - Date.now()))
       } catch {
-        // An unreachable daemon falls back to event-driven retirement when its
-        // authenticated sockets close and it can prove itself empty.
+        // An unreachable daemon falls back to event-driven retirement once its auth sockets close and it proves itself empty.
       }
     }
     this.client.disconnect()
@@ -1088,14 +952,11 @@ export class DaemonPtyAdapter implements IPtyProvider {
         ? this.client.ensureConnectedWithin(Math.max(1, deadlineMs - Date.now()))
         : this.client.ensureConnected())
     } finally {
-      // Why: a respawn launcher holds a temporary full pair until this adapter
-      // has attempted its permanent reconnect, preventing both gaps and leaks.
+      // Why: a respawn launcher holds a temporary pair until this adapter's permanent reconnect, preventing both gaps and leaks.
       this.releasePendingRespawnAdoptionLease()
     }
-    // Why sampled before setupEventRouting: routing is (re)installed exactly
-    // once per connection, so "no listener yet" identifies a fresh connect —
-    // the only time the daemon-side backgrounded set needs a resync (it is
-    // process state that died with the previous daemon/socket).
+    // Why sampled before setupEventRouting: "no listener yet" identifies a fresh connect — the only time the
+    // daemon-side backgrounded set (process state lost with the old daemon) needs a resync.
     const isFreshConnection = this.removeEventListener === null
     this.setupEventRouting()
     this.scheduleCheckpointTimer()
@@ -1117,8 +978,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       return
     }
     for (const id of this.producerResumesOwedOnReconnect) {
-      // Why: resuming a session the fresh daemon doesn't know is a harmless
-      // no-op; leaving a survivor paused would waste 5s of failsafe latency.
+      // Why: resuming an unknown session is a harmless no-op; leaving a survivor paused would waste 5s of failsafe latency.
       this.client.notify('resumePty', { sessionId: id })
     }
     this.producerResumesOwedOnReconnect.clear()
@@ -1147,14 +1007,10 @@ export class DaemonPtyAdapter implements IPtyProvider {
     ) {
       return
     }
-    // Why: checkpointing is only needed after terminal data/resize/write marks
-    // a session dirty. A permanent interval woke the main process every 5s for
-    // idle daemon-backed terminals just to discover there was nothing to write.
+    // Why: dirty-gate the timer — a permanent 5s interval woke the main process for idle terminals with nothing to write.
     this.checkpointTimer = setTimeout(() => {
       this.checkpointTimer = null
-      // Why: if the previous pass is still in-flight (slow RPC or disk),
-      // retry later instead of overlapping checkpoint() writes to the same tmp
-      // file, which can lose a rename and disable future history writes.
+      // Why: don't overlap checkpoint passes — concurrent tmp-file writes can lose a rename and disable future history writes.
       if (this.checkpointInFlight) {
         this.scheduleCheckpointTimer()
         return
@@ -1178,10 +1034,8 @@ export class DaemonPtyAdapter implements IPtyProvider {
     if (!this.historyManager || this.dirtySessionVersions.size === 0) {
       return
     }
-    // Why: getSnapshot serializes the daemon's terminal buffer. On large
-    // workspaces, checkpointing every live idle session every 5s burns CPU and
-    // disk for identical payloads; dirty versions keep retries precise without
-    // dropping writes that arrive during an in-flight checkpoint.
+    // Why: dirty-version filtering avoids re-serializing every idle session every 5s (CPU/disk on large workspaces)
+    // while not dropping writes that arrive mid-checkpoint.
     const versions = new Map(
       [...this.dirtySessionVersions].filter(([sessionId]) => this.activeSessionIds.has(sessionId))
     )
@@ -1199,14 +1053,8 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.stopCheckpointTimerIfIdle()
   }
 
-  // Why: the adapter runs in the Electron main process and does not have direct
-  // access to daemon Session objects. It calls checkpoint RPCs over the daemon
-  // socket per session. Returns a promise that resolves when all checkpoint
-  // writes complete (callers that don't need to wait can void it).
-  // Why final=true here: this runs on clean disconnect, where the full-depth
-  // snapshot (not the increment log) must be the restore source. It is not a
-  // teardown snapshot: the detached daemon and its PTYs keep running for warm
-  // reattach, so shell-ready scanner state must remain intact.
+  // Why final=true not teardown: clean disconnect needs the full-depth snapshot as the restore source, but the
+  // detached daemon's PTYs keep running for warm reattach, so shell-ready scanner state must stay intact.
   private async checkpointAllSessions(): Promise<void> {
     const completed = await this.checkpointSessions(this.activeSessionIds, { final: true })
     for (const sessionId of completed) {
@@ -1238,8 +1086,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
           teardown: opts?.teardown === true
         })
           .then((result) => {
-            // Why: deferred sessions stay dirty so the checkpoint timer keeps
-            // retrying until their full-snapshot cooldown expires.
+            // Why: deferred sessions stay dirty so the checkpoint timer keeps retrying until their full-snapshot cooldown expires.
             if (result === 'done') {
               completed.add(sessionId)
             }
@@ -1247,9 +1094,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
           .catch((err) => console.warn('[history] checkpoint failed:', sessionId, err))
       }
     }
-    // Why: snapshot serialization and checkpoint writes are CPU/disk heavy.
-    // Dirty-session filtering keeps idle terminals out; this cap prevents one
-    // tick from snapshotting every active dirty terminal at once.
+    // Why: snapshot/checkpoint writes are CPU/disk heavy; cap prevents one tick snapshotting every dirty terminal at once.
     const workers = Array.from({ length: Math.min(MAX_CONCURRENT_CHECKPOINTS, ids.length) }, () =>
       checkpointNext()
     )
@@ -1257,27 +1102,19 @@ export class DaemonPtyAdapter implements IPtyProvider {
     return completed
   }
 
-  // Why cooldown starts only after a session's FIRST full snapshot: a session
-  // with no checkpoint on disk yet must be able to write one immediately or a
-  // cold restore would find nothing.
+  // Why cooldown starts only after the first full snapshot: a checkpoint-less session must be able to write one immediately.
   private isFullCheckpointCoolingDown(sessionId: string): boolean {
     const last = this.lastFullCheckpointAt.get(sessionId)
     if (last === undefined) {
       return false
     }
     const elapsed = Date.now() - last
-    // Why elapsed < 0 counts as expired: a backward wall-clock jump must not
-    // extend the deferral window.
+    // Why elapsed < 0 counts as expired: a backward wall-clock jump must not extend the deferral window.
     return elapsed >= 0 && elapsed < DaemonPtyAdapter.FULL_CHECKPOINT_COOLDOWN_MS
   }
 
-  // Why 'deferred' exists: a cap/overflow-triggered full snapshot inside the
-  // cooldown window is postponed, and the session must STAY dirty so the 5s
-  // timer keeps retrying until the cooldown expires. While deferred, no
-  // takePendingOutput/append runs for the session — appending past a dropped
-  // range would leave a hole in the log, whereas skipping keeps the on-disk
-  // state a consistent (merely stale) prefix that the eventual full snapshot
-  // re-anchors.
+  // Why 'deferred' exists: a full snapshot inside the cooldown is postponed and the session stays dirty for retry;
+  // skipping append meanwhile keeps the on-disk log a consistent (stale) prefix instead of punching a hole.
   private async checkpointSession(
     sessionId: string,
     opts: { final: boolean; teardown: boolean }
@@ -1293,12 +1130,8 @@ export class DaemonPtyAdapter implements IPtyProvider {
       if (!opts.final && this.isFullCheckpointCoolingDown(sessionId)) {
         return 'deferred'
       }
-      // Why take-with-snapshot instead of plain getSnapshot: the take clears
-      // the daemon's pending records in the same synchronous turn as the
-      // serialize. A plain snapshot would leave pre-snapshot records pending;
-      // a later warm reattach would append them to the fresh log and cold
-      // restore would replay them on top of a checkpoint that already
-      // contains them.
+      // Why take-with-snapshot not plain getSnapshot: it clears pending records in the same turn as the serialize,
+      // so a warm reattach won't re-append records the checkpoint already contains (double-replay on cold restore).
       await this.takeSnapshotAndCheckpoint(sessionId, { teardown: opts.teardown })
       this.sessionsNeedingFullCheckpoint.delete(sessionId)
       return 'done'
@@ -1310,8 +1143,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       return 'done'
     }
     if (take.overflowed) {
-      // Why: overflow dropped records, so the log has a hole — only a full
-      // snapshot (which reflects everything ever written) can re-anchor it.
+      // Why: overflow dropped records (log has a hole); only a full snapshot can re-anchor it.
       if (this.isFullCheckpointCoolingDown(sessionId)) {
         this.sessionsNeedingFullCheckpoint.add(sessionId)
         return 'deferred'
@@ -1331,8 +1163,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       take.records
     )
     if (appendResult === 'needs-checkpoint') {
-      // Why dropping take.records is lossless: they were applied to the live
-      // emulator before the take, so the snapshot below contains them.
+      // Why dropping take.records is lossless: applied to the emulator before the take, so the snapshot below contains them.
       if (this.isFullCheckpointCoolingDown(sessionId)) {
         this.sessionsNeedingFullCheckpoint.add(sessionId)
         return 'deferred'
@@ -1355,27 +1186,18 @@ export class DaemonPtyAdapter implements IPtyProvider {
       await this.historyManager.checkpoint(sessionId, take.snapshot)
       this.lastFullCheckpointAt.set(sessionId, Date.now())
       if (take.records.length > 0) {
-        // Why: take-with-snapshot usually returns no records because the
-        // snapshot subsumes them. Held parser-state bytes, such as an
-        // incomplete shell-ready marker prefix, are not representable in the
-        // snapshot and must remain as a post-checkpoint log tail.
+        // Why: held parser-state bytes (an incomplete shell-ready marker) aren't in the snapshot; keep them as a post-checkpoint log tail.
         await this.historyManager.appendIncrements(sessionId, take.seq, take.records)
       }
     }
   }
 
-  // Why: when the daemon process dies, operations fail with ENOENT (socket
-  // gone), ECONNREFUSED, or "Connection lost" (socket closed mid-request).
-  // Rather than leaving all terminals permanently broken until app restart,
-  // this wrapper detects daemon-death errors, tears down the stale client
-  // state, forks a fresh daemon via respawnFn, reconnects, and retries the
-  // operation once. If respawn itself fails, the error propagates normally.
+  // Why: on daemon-death errors, respawn a fresh daemon and retry once rather than leaving terminals broken until app restart.
   private async withDaemonRetry<T>(fn: () => Promise<T>): Promise<T> {
     try {
       return await fn()
     } catch (err) {
-      // Why: self-retirement removes the token only after an authenticated
-      // endpoint dropped; an initial missing token may still hide a live daemon.
+      // Why: the token is removed only after an authenticated drop; an initial missing token may still hide a live daemon.
       const missingRetiredEndpointToken =
         isMissingTokenFileError(err) && this.client.hasObservedAuthenticatedDisconnect()
       if (
@@ -1394,8 +1216,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       try {
         return await fn()
       } finally {
-        // Why: the retried operation may reject before it reaches a connection
-        // attempt (for example, a tombstone racing respawn).
+        // Why: the retried op may reject before any connection attempt (e.g. a tombstone racing respawn).
         this.releasePendingRespawnAdoptionLease()
       }
     }
@@ -1426,8 +1247,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
       return
     }
 
-    // Why: replacing the daemon kills its sessions without daemon-side exit
-    // fanout. Emit exits first so renderer panes do not write to dead PTYs.
+    // Why: replacing the daemon kills its sessions without exit fanout; emit exits first so panes don't write to dead PTYs.
     this.fanoutSyntheticExits(-1)
     if (!this.respawnPromise) {
       this.respawnPromise = this.doRespawn(
@@ -1463,8 +1283,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.client.disconnect()
     const releaseAdoptionLease = await this.respawnFn!()
     if (this.respawnAdoptionClosed) {
-      // Why: app teardown may win while the launcher is still acquiring its
-      // temporary pair; a late result must not reinstall a lease nobody owns.
+      // Why: app teardown may win mid-respawn; a late result must not reinstall a lease nobody owns.
       releaseAdoptionLease?.()
       throw new Error('Daemon adapter closed during respawn')
     }
@@ -1529,21 +1348,16 @@ export class DaemonPtyAdapter implements IPtyProvider {
       } else if (event.event === 'exit') {
         this.activeSessionIds.delete(event.sessionId)
         this.dirtySessionVersions.delete(event.sessionId)
-        // Why: an exited session must not be owed a resume on reconnect — a
-        // reused sessionId would receive a stray resumePty. Same for the
-        // background set: a reused id must start un-thinned.
+        // Why: a reused sessionId must not inherit the dead session's owed resume (stray resumePty) or backgrounded/thinned state.
         this.pausedProducerSessionIds.delete(event.sessionId)
         this.producerResumesOwedOnReconnect.delete(event.sessionId)
         this.backgroundedSessionIds.delete(event.sessionId)
         if (!this.sleepRestoreSessionIds.has(event.sessionId)) {
           this.coldRestoreCache.delete(event.sessionId)
         }
-        // Why: an exited session can never be checkpointed again, so its pending
-        // full-checkpoint flag is dead state. Without this, a cold-restored
-        // session that exits before its first checkpoint leaks a permanent entry.
+        // Why: an exited session can't be checkpointed again; clearing its pending-full flag prevents a permanent leak.
         this.sessionsNeedingFullCheckpoint.delete(event.sessionId)
-        // Why: a reused sessionId (renderer respawns a persisted ptyId) must
-        // not inherit the dead session's snapshot cooldown.
+        // Why: a reused sessionId (renderer respawns a persisted ptyId) must not inherit the dead session's snapshot cooldown.
         this.lastFullCheckpointAt.delete(event.sessionId)
         this.stopCheckpointTimerIfIdle()
         if (this.historyManager) {
@@ -1572,16 +1386,8 @@ export class DaemonPtyAdapter implements IPtyProvider {
   }
 }
 
-// Why: ENOENT/ECONNREFUSED with syscall 'connect' mean the socket is
-// unreachable (daemon died). Checking syscall avoids false positives from
-// token-file ENOENT (readFileSync), which has no syscall or syscall='open'.
-// "Connection lost" / "Not connected" mean the daemon died while we had an
-// active or stale connection. "Hello response timed out" means we reconnected
-// to a daemon whose socket accepts connections but whose event loop never
-// answers the handshake (a wedged daemon, #8689) — respawning re-enters the
-// grace-bounded launcher, which drains a transient wedge or replaces a
-// permanent one instead of failing every terminal forever. All indicate the
-// daemon is unusable and a respawn should be attempted.
+// Why: syscall='connect' distinguishes a dead-socket ENOENT/ECONNREFUSED from token-file ENOENT (no syscall);
+// message strings incl. wedged-daemon "Hello response timed out" (#8689) also warrant a respawn.
 function isDaemonGoneError(err: unknown): boolean {
   if (!(err instanceof Error)) {
     return false
diff --git a/src/main/daemon/daemon-server.ts b/src/main/daemon/daemon-server.ts
index 93ee537c126..0226977a1ec 100644
--- a/src/main/daemon/daemon-server.ts
+++ b/src/main/daemon/daemon-server.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: this class owns the daemon socket protocol,
-   request routing, stream fanout, and session lifecycle in one place so
-   renderer/daemon request semantics stay auditable across platform branches. */
+/* eslint-disable max-lines -- Why: one class owns the daemon socket protocol, routing, stream fanout, and session lifecycle. */
 import { createServer, type Server, type Socket } from 'node:net'
 import { randomUUID } from 'node:crypto'
 import { performance } from 'node:perf_hooks'
@@ -84,8 +82,7 @@ type PendingShutdownReply = {
 }
 
 export class DaemonServer {
-  // Why: a new daemon must survive long enough for its first client pair, but
-  // a parent crash between launch and adoption must not orphan it forever.
+  // Why: survive long enough to adopt a first client pair, but don't orphan forever if the parent crashes first.
   private static readonly INITIAL_ADOPTION_TIMEOUT_MS = 2 * 60 * 1000
   private static readonly SHUTDOWN_REPLY_FLUSH_TIMEOUT_MS = 1_000
   private server: Server | null = null
@@ -130,10 +127,7 @@ export class DaemonServer {
       }
     }
   )
-  // Fact scan authority for backgrounded sessions — facts ride the stream
-  // queue as control entries so they hold byte order with the data around
-  // them (a fact jumping the queue could arrive after the reveal snapshot
-  // that already reflects it).
+  // Facts ride the stream queue as control entries so they hold byte order (else a fact could arrive after the reveal snapshot).
   private transientFactRelay = new BackgroundTransientFactRelay((sessionId, fact) => {
     const clientId = this.streamClientIdBySessionId.get(sessionId)
     if (clientId) {
@@ -150,10 +144,7 @@ export class DaemonServer {
   private pendingPtySpawnPreparations = new Map<string, Set<PendingPtySpawnPreparation>>()
   private stopStreamBacklogProbe: () => void = () => {}
 
-  // Why: main-process PTY IPC has the same recent-input bypass, but daemon
-  // output reaches main only after this stream layer. Keeping the window here
-  // removes the daemon's fixed batch delay from keystroke echo/redraws while
-  // preserving batching for background and large output.
+  // Why: bypass batching within this window so keystroke echo/redraws skip the daemon's fixed batch delay.
   private static readonly INTERACTIVE_OUTPUT_WINDOW_MS = 100
   private static readonly INTERACTIVE_OUTPUT_MAX_CHARS = 1024
 
@@ -207,8 +198,7 @@ export class DaemonServer {
       this.server.once('error', onListenError)
 
       this.server.listen(this.socketPath, () => {
-        // Why: after bind, steady-state socket errors are handled per client;
-        // the startup promise listener would otherwise retain this closure.
+        // Why: drop the startup error listener after bind so it doesn't retain this closure.
         this.server?.off('error', onListenError)
         writeFileSync(this.tokenPath, this.token, { mode: 0o600 })
         try {
@@ -217,8 +207,7 @@ export class DaemonServer {
           // Best-effort on platforms that support it
         }
         if (this.protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
-          // Why: a parent crash before the first full client pair must not leave
-          // a freshly published, empty daemon alive forever.
+          // Why: a parent crash before the first full client pair must not leave an empty daemon alive forever.
           this.armInitialAdoptionTimeout()
         }
         resolve()
@@ -249,8 +238,7 @@ export class DaemonServer {
   }
 
   private unlinkOwnedEndpointArtifacts(): void {
-    // Why: close has already fenced this endpoint, but ownership checks still
-    // prevent a late replacement's canonical token or PID record from removal.
+    // Why: ownership checks prevent removing a late replacement's token or PID record.
     unlinkOwnedDaemonTokenFile(this.tokenPath, this.token)
     if (this.pidPath && this.launchNonce) {
       unlinkOwnedDaemonPidFile(this.pidPath, process.pid, this.launchNonce)
@@ -264,8 +252,7 @@ export class DaemonServer {
     try {
       await this.host.dispose()
     } catch (err) {
-      // Why: an unreapable child must not block daemon exit — after exit it
-      // reparents to init, while a blocked daemon would orphan alongside it.
+      // Why: an unreapable child must not block daemon exit — post-exit it reparents to init anyway.
       this.log.log('shutdown-dispose-failed', {
         error: err instanceof Error ? err.message : String(err)
       })
@@ -291,11 +278,9 @@ export class DaemonServer {
       return Promise.resolve()
     }
     return new Promise<void>((resolve) => {
-      // Why: call close synchronously before any awaited cleanup so no new
-      // transport can enter after the idle fence is proven empty.
+      // Why: close synchronously before any awaited cleanup so no new transport enters after the empty proof.
       server.close(() => {
-        // Node owns unlinking its Unix listener. An extra check-then-unlink here could
-        // delete a replacement endpoint installed concurrently after close.
+        // Node owns unlinking its Unix listener; an extra unlink here could delete a concurrent replacement.
         resolve()
       })
     })
@@ -363,16 +348,14 @@ export class DaemonServer {
     }
     this.idleShutdownState = 'idle-shutdown-pending'
     if (!this.isIdle()) {
-      // Why: work admitted before the fence wins. Clearing the pending state
-      // keeps that already-started client/session fully usable.
+      // Why: work admitted before the fence wins; clear pending state to keep it usable.
       this.idleShutdownState = 'running'
       this.reevaluateIdleShutdown()
       return
     }
 
     this.idleShutdownState = 'shutting-down'
-    // beginServerClose() runs synchronously up to server.close(), before host
-    // disposal or file cleanup can yield to a racing connection.
+    // beginServerClose() runs synchronously up to server.close() before any yield to a racing connection.
     const serverClose = this.beginServerClose()
     this.shutdownPromise = this.finishIdleShutdown(serverClose)
   }
@@ -395,8 +378,7 @@ export class DaemonServer {
     socket.on('error', () => socket.destroy())
 
     if (this.idleShutdownState !== 'running') {
-      // Why: an accepted connection queued just before server.close() must get
-      // an explicit retry signal instead of appearing authenticated then dying.
+      // Why: a connection accepted just before close() gets an explicit retry signal instead of dying mid-auth.
       socket.end(
         encodeNdjson({
           type: 'hello',
@@ -407,8 +389,7 @@ export class DaemonServer {
       )
       return
     }
-    // Why: clients can send multibyte prompt/input text split across socket
-    // chunks; keep UTF-8 sequences intact before NDJSON parsing.
+    // Why: keep UTF-8 sequences intact across socket chunks before NDJSON parsing.
     const decoder = new StringDecoder('utf8')
     const parser = createNdjsonParser(
       (msg) => this.handleFirstMessage(socket, msg, parser),
@@ -479,24 +460,20 @@ export class DaemonServer {
       this.setupControlSocket(socket, hello.clientId)
       if (previous) {
         this.recordFullyAuthenticatedDisconnect(previous.authenticatedPairEstablished)
-        // Why: a reconnect can reuse a clientId before the old sockets notice
-        // their close. Tear them down after installing the new owner so stale
-        // close events cannot delete the replacement client entry.
+        // Why: tear down the old sockets after installing the new owner so a stale close can't delete the replacement.
         previous.streamSocket?.destroy()
         previous.controlSocket.destroy()
       }
     } else if (hello.role === 'stream') {
       const client = this.clients.get(hello.clientId)
       if (!client) {
-        // Why: stream sockets are only meaningful beside a control socket; an
-        // orphan stream would otherwise stay open with no tracked owner.
+        // Why: a stream socket is meaningless without its control socket; drop the orphan.
         socket.destroy()
         return
       }
       this.setupStreamSocket(socket, client)
       client.authenticatedPairEstablished = true
-      // A complete app connection, unlike a health or raw socket probe, owns
-      // the endpoint again and cancels pending event-driven retirement.
+      // A complete app connection (unlike a probe) re-owns the endpoint and cancels pending retirement.
       this.initialAdoptionDeadlineMs = null
       this.retirementRequested = false
       this.cancelInitialAdoptionTimer()
@@ -504,8 +481,7 @@ export class DaemonServer {
   }
 
   private setupControlSocket(socket: Socket, clientId: string): void {
-    // Why: terminal writes and startup commands can contain emoji/Unicode.
-    // Decoding per Buffer would corrupt split multibyte sequences.
+    // Why: decode as a UTF-8 stream so emoji/Unicode split across chunks isn't corrupted.
     const decoder = new StringDecoder('utf8')
     const parser = createNdjsonParser(
       (msg) => this.handleRequest(socket, clientId, msg as DaemonRequest),
@@ -538,8 +514,7 @@ export class DaemonServer {
     ) {
       return
     }
-    // Why: once the last full client is gone, exact daemon-side emptiness is
-    // sufficient; incomplete transports may block but never erase this request.
+    // Why: once the last full client is gone, incomplete transports may block retirement but never erase it.
     this.retirementRequested = true
   }
 
@@ -566,8 +541,7 @@ export class DaemonServer {
     socket.on('error', cleanup)
 
     if (previous && previous !== socket) {
-      // Why: replacing a stream socket must not leave the old receive-only
-      // channel alive and untracked.
+      // Why: replacing a stream socket must not leave the old channel alive and untracked.
       previous.destroy()
     }
   }
@@ -628,8 +602,7 @@ export class DaemonServer {
         this.shutdownPromise = finish()
       }
     }
-    // Why: a non-reading authenticated peer must not pin a fenced daemon by
-    // holding its acknowledgement behind permanent socket backpressure.
+    // Why: a non-reading peer must not pin a fenced daemon by holding its ack behind permanent socket backpressure.
     timer = setTimeout(start, DaemonServer.SHUTDOWN_REPLY_FLUSH_TIMEOUT_MS)
     timer.unref()
     socket.once('close', start)
@@ -643,8 +616,7 @@ export class DaemonServer {
     pending.add(preparation)
     this.pendingPtySpawnPreparations.set(sessionId, pending)
     try {
-      // Why: registration precedes the async capability probe so a concurrent
-      // close can cancel this exact creation before a subprocess exists.
+      // Why: register before the async probe so a concurrent close can cancel this creation before a subprocess exists.
       await this.preparePtySpawn()
       if (preparation.canceled) {
         throw new TerminalAttachCanceledError(sessionId)
@@ -683,8 +655,7 @@ export class DaemonServer {
           throw new Error('Daemon temporarily unavailable; reconnect')
         }
         if (!client?.authenticatedPairEstablished || client.streamSocket === null) {
-          // Why: a control-only replacement cannot own terminal admission or
-          // erase the prior full client's monotonic retirement request.
+          // Why: a control-only replacement can't own terminal admission or erase the prior client's retirement request.
           throw new Error('Daemon client connection is incomplete; reconnect')
         }
         this.createOrAttachInFlight++
@@ -701,8 +672,7 @@ export class DaemonServer {
             envToDelete: p.envToDelete,
             command: p.command,
             startupCommandDelivery: p.startupCommandDelivery,
-            // Why: daemon RPC payloads are untrusted JSON. Persist only the
-            // allowlisted enum used for byte routing, never arbitrary identity.
+            // Why: RPC payloads are untrusted JSON; persist only the allowlisted routing enum, never arbitrary identity.
             ...(isTuiAgent(p.launchAgent) ? { launchAgent: p.launchAgent } : {}),
             shellOverride: p.shellOverride,
             terminalWindowsWslDistro: p.terminalWindowsWslDistro,
@@ -721,8 +691,7 @@ export class DaemonServer {
               : {}),
             streamClient: {
               onData: (data, rawLength = data.length, transformed = false, seq) => {
-                // Scan BEFORE enqueue: the batcher may keep-tail drop this
-                // chunk, but its facts must be captured regardless.
+                // Scan BEFORE enqueue: the batcher may drop this chunk, but its facts must be captured regardless.
                 this.transientFactRelay.onSessionData(p.sessionId, data)
                 const lastInputAt = this.lastInputAtBySessionId.get(p.sessionId)
                 const isInteractiveOutput =
@@ -738,9 +707,7 @@ export class DaemonServer {
                 })
               },
               onExit: (code) => {
-                // Why: exit tears down renderer handlers, so it must ride the
-                // ordered queue behind final output even when the shallow socket
-                // gate holds that output for a later drain pass.
+                // Why: exit tears down renderer handlers, so it must ride the ordered queue behind final output.
                 this.log.log('session-exited', { sessionId: p.sessionId, code })
                 this.streamDataBatcher.enqueueControlEvent(clientId, p.sessionId, {
                   type: 'event',
@@ -764,9 +731,7 @@ export class DaemonServer {
           this.reevaluateIdleShutdown()
         }
         this.streamClientIdBySessionId.set(p.sessionId, clientId)
-        // Why an attach-time marker: the adapter resyncs the background set on
-        // a fresh connection, which can precede this attach — main's scan
-        // suppression must still start at the head of the new stream.
+        // Why an attach-time marker: background resync can precede this attach, so scan suppression must start at the new stream's head.
         if (this.transientFactRelay.isBackgrounded(p.sessionId)) {
           this.streamDataBatcher.enqueueControlEvent(clientId, p.sessionId, {
             type: 'event',
@@ -837,9 +802,7 @@ export class DaemonServer {
           return {}
         }
         if (background) {
-          // Prime the fresh relay tracker with the emulator's dangling
-          // incomplete escape so a sequence split across the handoff parses
-          // exactly as if the relay had seen the whole stream.
+          // Seed the fresh relay tracker with the emulator's dangling escape so a handoff-split sequence still parses.
           this.transientFactRelay.seedSessionScanState(
             sessionId,
             this.host.getPartialEscapeTailAnsi(sessionId)
@@ -850,11 +813,7 @@ export class DaemonServer {
           // Not attached yet — the attach-time marker covers the handoff.
           return {}
         }
-        // Reveal deliberately does NOT discard or force-flush the queued
-        // tail: main's model (hidden-output recovery buffer, tail previews)
-        // needs those bytes — a finished program's last output lives there —
-        // and the normal flush/drain loop delivers them within milliseconds
-        // (bounded ≤ the keep-tail drop cap), in order, ahead of the marker.
+        // Reveal intentionally keeps the queued tail: main needs those bytes, and the normal flush/drain delivers them in order ahead of the marker.
         const scanSeedAnsi = background ? '' : this.host.getPartialEscapeTailAnsi(sessionId)
         this.streamDataBatcher.enqueueControlEvent(streamClientId, sessionId, {
           type: 'event',
@@ -880,8 +839,7 @@ export class DaemonServer {
         try {
           await this.host.kill(request.payload.sessionId, { immediate: request.payload.immediate })
         } catch (error) {
-          // Why: a kill that wins before session registration has already
-          // canceled the pending spawn and therefore completed its intent.
+          // Why: a kill that wins before session registration already canceled the pending spawn, so its intent is done.
           if (!(canceledPendingSpawn && error instanceof SessionNotFoundError)) {
             throw error
           }
@@ -894,8 +852,7 @@ export class DaemonServer {
         return {}
 
       case 'detach':
-        // Note: detach token handling is simplified here — full implementation
-        // would track tokens per client
+        // Note: detach token handling simplified — full impl would track tokens per client
         this.log.log('session-detached', { sessionId: request.payload.sessionId })
         return {}
 
@@ -937,8 +894,7 @@ export class DaemonServer {
         this.initialAdoptionDeadlineMs = null
         this.retirementRequested = false
         this.cancelInitialAdoptionTimer()
-        // Why: close before acknowledging retirement so no new terminal can
-        // race between the empty proof and daemon disposal.
+        // Why: close before acknowledging retirement so no new terminal races between the empty proof and disposal.
         const serverClose = this.beginServerClose()
         this.deferShutdownUntilReply(clientId, request.id, authenticatedClient.controlSocket, () =>
           this.finishIdleShutdown(serverClose)
@@ -956,9 +912,7 @@ export class DaemonServer {
         const snapshot = this.host.getSnapshot(request.payload.sessionId, { scrollbackRows })
         const snapshotMs = performance.now() - snapshotStart
         if (snapshotMs >= 25) {
-          // Serialize stalls block the daemon's single thread — every pty's
-          // echo included. Surfaced here so multi-second typing stalls can be
-          // attributed to checkpoint storms (issue #5096 family) in the field.
+          // Serialize stalls block the daemon's single thread; surface them to attribute field typing stalls (issue #5096 family).
           recordDaemonStreamBacklogEvent('slowGetSnapshot', {
             sessionIdSuffix: request.payload.sessionId.slice(-10),
             snapshotMs: Math.round(snapshotMs)
@@ -971,10 +925,7 @@ export class DaemonServer {
         return { size: this.host.getAppliedSize(request.payload.sessionId) }
 
       case 'takePendingOutput':
-        // Why no await before this call: with includeSnapshot, drain and
-        // serialize must share one synchronous turn — an intervening await
-        // would let PTY data land in between, and cold restore would replay
-        // those bytes on top of a snapshot that already contains them.
+        // Why no await: with includeSnapshot, drain+serialize must share one sync turn or cold restore replays doubled PTY bytes.
         return this.host.takePendingOutput(
           request.payload.sessionId,
           request.payload.includeSnapshot === true,
@@ -1001,9 +952,7 @@ export class DaemonServer {
           try {
             await this.host.dispose()
           } catch (err) {
-            // Why: the shutdown RPC contract is that the daemon always
-            // self-terminates; dispose keeps failed owners retryable, and the
-            // follow-up shutdown() below retries them once more before exit.
+            // Why: shutdown must always self-terminate; failed owners stay retryable for the follow-up shutdown() below.
             this.log.log('shutdown-dispose-failed', {
               error: err instanceof Error ? err.message : String(err)
             })
@@ -1031,9 +980,7 @@ export class DaemonServer {
     if (!client?.streamSocket) {
       return
     }
-    // Why: write/resize are notification-heavy and intentionally do not wait
-    // for replies. If their target session is gone, this synthetic exit is the
-    // only signal the renderer gets to clear stale terminal pane bindings.
+    // Why: write/resize don't wait for replies, so this synthetic exit is the renderer's only signal to clear stale pane bindings.
     this.streamDataBatcher.enqueueControlEvent(client.clientId, sessionId, {
       type: 'event',
       event: 'exit',
diff --git a/src/main/daemon/daemon-stream-data-batcher.ts b/src/main/daemon/daemon-stream-data-batcher.ts
index b27c4020217..83e1b6c0c31 100644
--- a/src/main/daemon/daemon-stream-data-batcher.ts
+++ b/src/main/daemon/daemon-stream-data-batcher.ts
@@ -19,58 +19,27 @@ type StreamDataClient = {
   streamSocket: Socket | null
 }
 
-// Why 2ms: under continuous agent output every chunk waits an expected
-// half-window here AND again in main's PTY batch — at 8ms each that was
-// ~8ms of the measured ~19ms DSR-under-load latency. 2ms keeps burst
-// coalescing (~500 socket writes/s worst case, ~100B framing overhead per
-// write against MB/s payloads) while cutting the fixed latency tax 4x.
+// 2ms: each chunk waits a half-window here AND again in main's PTY batch; a smaller interval still coalesces bursts while cutting the fixed latency tax (~8ms of the measured ~19ms DSR-under-load latency).
 const STREAM_DATA_BATCH_INTERVAL_MS = 2
 
-// Why a shallow socket: the stream socket is one FIFO for every session, and
-// bytes already written can never be overtaken — a deep user-space buffer
-// buries a visible pane's keystroke echo behind bulk output for other panes
-// (measured 192MB / 6+s under 12 flooding hidden agents). Bulk writes stop at
-// this depth and the remainder is HELD here, where the interactive
-// flushSession path can still jump it; socket 'drain' refills. Echo latency
-// is then bounded by the shallow depth, not by how much bulk is in flight.
-// 128KB must stay above the socket's ~16KB highWaterMark so a held state
-// implies a false write() and therefore a guaranteed 'drain' wake-up.
-// Kill switch: ORCA_DAEMON_SHALLOW_SOCKET_GATE=0 restores pre-gate unbounded
-// socket writes for field debugging and true fix-off A/B benches.
+// Shallow socket: the stream is one FIFO, so a deep buffer buries a visible pane's echo behind other panes' bulk; bulk stops here and is HELD (flushSession can jump it), bounding echo latency.
+// 128KB stays above the socket's ~16KB highWaterMark so a held state implies a false write() and thus a guaranteed 'drain' wake-up.
 const SHALLOW_SOCKET_WRITE_GATE_BYTES =
   process.env.ORCA_DAEMON_SHALLOW_SOCKET_GATE === '0' ? Number.POSITIVE_INFINITY : 128 * 1024
-// Why sliced writes: enqueue coalesces per-session entries, so a held entry
-// can grow to megabytes; writing it whole would re-deepen the socket past the
-// gate in one call.
+// Sliced writes: a coalesced entry can grow to megabytes; writing it whole would re-deepen the socket past the gate in one call.
 const BULK_WRITE_SLICE_CHARS = 64 * 1024
-// Safety valve: if held bulk ever exceeds this, write through to the socket
-// (exactly the pre-gate behavior) — bounded daemon memory beats bounded echo
-// latency in the extreme. Must sit FAR above the pacer's pause watermark plus
-// its overshoot (observed ~5MB with 17 paused sessions' in-flight pty reads):
-// an engaged valve deepens the socket and buries interactive echo behind the
-// whole backlog (measured as bimodal ~2.4s key medians when this was 8MB).
+// Safety valve: past this, write through — bounded daemon memory beats bounded echo latency in the extreme. Must sit FAR above the pacer's pause watermark + overshoot (~5MB) or an engaged valve buries interactive echo behind the whole backlog.
 const HELD_WRITE_THROUGH_TOTAL_CHARS = 32 * 1024 * 1024
-// Why a small-session bypass: the hold is there to stop FLOODS from burying
-// everyone else; a session with only a few KB queued (keystroke echo, prompt
-// redraws, query replies) is never the flood and must not wait FIFO behind
-// other sessions' megabytes. The daemon's 100ms interactive fast-path is a
-// heuristic that misses under event-loop load (measured: echo classified
-// non-interactive rode the held queue for ~2.4s); this bypass is the
-// deterministic backstop. Worst socket over-deepening per flush is
-// sessions × this ≈ tens of KB.
+// Small-session bypass: a few-KB session (echo, redraws, query replies) is never the flood, so it must not wait FIFO behind others' megabytes; backstops the 100ms interactive fast-path, which misses under event-loop load.
 const SMALL_SESSION_HOLD_BYPASS_CHARS = 4 * 1024
 
 type DaemonStreamDataBatcherOptions = {
   maxLineBytes?: number
-  /** Fires after each stream-socket write — the only place backlog grows, so
-   *  the backlog pacer checks its watermark here. */
+  /** Fires after each stream-socket write — the only place backlog grows, so the backlog pacer checks its watermark here. */
   onAfterSocketWrite?: () => void
-  /** True for sessions whose queued output may be keep-tail dropped
-   *  (main-marked background sessions). */
+  /** True for sessions whose queued output may be keep-tail dropped (main-marked background sessions). */
   isSessionDroppable?: (sessionId: string) => boolean
-  /** Carve reply-eliciting query bytes (DSR/DA/DECRQM/OSC color probes) out
-   *  of dropped data — the hidden program blocks on the reply, so those few
-   *  bytes must still be delivered even when their flood is not. */
+  /** Carve reply-eliciting query bytes (DSR/DA/DECRQM/OSC probes) out of dropped data — the hidden program blocks on the reply, so they must still be delivered even when their flood is not. */
   salvageDroppedData?: (dropped: string) => string
 }
 
@@ -108,8 +77,7 @@ export class DaemonStreamDataBatcher {
     appendDaemonStreamData(batch, sessionId, data, options)
 
     if (this.isSessionDroppable(sessionId)) {
-      // Keep-tail scales down as more backgrounded sessions queue, bounding
-      // the AGGREGATE a reveal must drain (see daemon-stream-keep-tail-drop).
+      // Keep-tail scales down as more backgrounded sessions queue, bounding the aggregate a reveal must drain (see daemon-stream-keep-tail-drop).
       const droppableQueued = this.countDroppableSessionsWithQueuedData(batch)
       const dropCap = backgroundSessionDropCapChars(droppableQueued)
       const keepTail = backgroundSessionKeepTailChars(droppableQueued)
@@ -117,8 +85,7 @@ export class DaemonStreamDataBatcher {
         dropOldestQueuedForSession(batch, sessionId, keepTail, this.salvageDroppedData)
       }
       if (droppableQueued > (batch.lastDroppableSessionCount ?? 0)) {
-        // The shared budget tightened: re-trim sessions that already finished
-        // producing — they never re-enter this path on their own.
+        // Shared budget tightened: re-trim sessions that already finished producing — they never re-enter this path on their own.
         for (const [queuedSessionId, queued] of Array.from(batch.queuedCharsBySession)) {
           if (
             queued > dropCap &&
@@ -145,8 +112,7 @@ export class DaemonStreamDataBatcher {
     }
   }
 
-  /** Append a pre-shaped stream event at the current position in the
-   *  session's byte order (scan handoff markers, gaps, transient facts). */
+  /** Append a pre-shaped stream event at the current position in the session's byte order (scan handoff markers, gaps, transient facts). */
   enqueueControlEvent(clientId: string, sessionId: string, control: DaemonEvent): void {
     const client = this.getClient(clientId)
     if (!client?.streamSocket || client.streamSocket.destroyed) {
@@ -195,23 +161,19 @@ export class DaemonStreamDataBatcher {
 
     const client = this.getClient(clientId)
     if (!client?.streamSocket || client.streamSocket.destroyed) {
-      // Same as pre-gate behavior: a vanished stream socket drops the batch —
-      // the model owns the bytes and reconnect restores from a snapshot.
+      // A vanished stream socket drops the batch — the model owns the bytes and reconnect restores from a snapshot.
       this.pendingByClient.delete(clientId)
       return
     }
 
     const socket = client.streamSocket
-    // Sessions that held an entry must hold ALL their later entries in this
-    // pass — writing around a held entry would reorder that session's bytes.
+    // A session that held an entry must hold all its later entries this pass — writing around a held entry would reorder that session's bytes.
     const heldSessions = new Set<string>()
     const retained: PendingStreamDataBatch['queue'] = []
     while (batch.queue.length > 0) {
       const entry = batch.queue[0]
       if (entry.control) {
-        // Control entries only respect the held-session order latch — they
-        // are ~100B, so writing them onto a deep socket is as harmless as the
-        // small-session bypass.
+        // Control entries only respect the held-session order latch; at ~100B, writing them onto a deep socket is as harmless as the small-session bypass.
         if (heldSessions.has(entry.sessionId)) {
           retained.push(entry)
           batch.queue.shift()
@@ -226,19 +188,14 @@ export class DaemonStreamDataBatcher {
       if (socketDeep && batch.queuedChars <= HELD_WRITE_THROUGH_TOTAL_CHARS) {
         const sessionHeld = batch.queuedCharsBySession.get(entry.sessionId) ?? 0
         if (heldSessions.has(entry.sessionId) || sessionHeld > SMALL_SESSION_HOLD_BYPASS_CHARS) {
-          // Hold this flooding session's entry; small talkers keep flowing.
-          // The socket's 'drain' (routed back to flush by the server)
-          // resumes held bulk. No timer: a deep socket implies a prior
-          // false write(), so 'drain' is guaranteed.
+          // Hold this flooding session's entry; small talkers keep flowing. No timer: a deep socket implies a prior false write(), so 'drain' (routed back to flush) is guaranteed to resume held bulk.
           heldSessions.add(entry.sessionId)
           retained.push(entry)
           batch.queue.shift()
           continue
         }
       } else if (socketDeep) {
-        // Valve engaged: held bulk exceeded the memory cap and is being
-        // written through onto a deep socket — echo protection is off until
-        // it drains. Rare enough to be worth a diagnostics event every time.
+        // Valve engaged: held bulk exceeded the memory cap, so echo protection is off until it drains — rare enough to log every time.
         recordDaemonStreamBacklogEvent('heldWriteThrough', {
           heldChars: batch.queuedChars,
           socketBufferedBytes: socket.writableLength ?? 0
@@ -284,16 +241,7 @@ export class DaemonStreamDataBatcher {
     }
     if (retained.length > 0) {
       batch.queue = retained
-      // Held entries must not wait for the socket's 'drain' alone: drain only
-      // fires when the user-space buffer fully EMPTIES, so bulk would advance
-      // one gate-depth per daemon event-loop turn — seconds of dead time for
-      // a multi-MB hidden backlog on a busy daemon (measured: hidden-restore
-      // 2.5s vs the 1.5s budget). Arm ONE ~90B empty data event whose
-      // kernel-flush callback re-flushes while bytes are still in flight, so
-      // main never starves. (An empty socket write's callback fires
-      // immediately — verified — so the sentinel must be a real protocol
-      // no-op line.) Event-driven, no timers; the per-client latch stops
-      // sentinel stacking; 'drain' remains the backstop.
+      // 'drain' only fires when the buffer fully empties (one gate-depth/turn = seconds for multi-MB backlogs); arm a no-op data event whose flush callback re-flushes while bytes are still in flight.
       this.armHeldQueueRefill(socket, clientId, retained[0].sessionId)
       return
     }
@@ -307,6 +255,7 @@ export class DaemonStreamDataBatcher {
       return
     }
     this.refillArmedClients.add(clientId)
+    // Must be a real protocol no-op line, not an empty write: an empty write's callback fires immediately, defeating the in-flight re-flush.
     socket.write(encodeStreamDataEvent(sessionId, ''), () => {
       this.refillArmedClients.delete(clientId)
       this.flush(clientId)
diff --git a/src/main/daemon/headless-emulator-fidelity.fuzz.test.ts b/src/main/daemon/headless-emulator-fidelity.fuzz.test.ts
index 77db320650c..3eb708b3cf2 100644
--- a/src/main/daemon/headless-emulator-fidelity.fuzz.test.ts
+++ b/src/main/daemon/headless-emulator-fidelity.fuzz.test.ts
@@ -19,27 +19,19 @@ import {
   writeChunksToTerminal
 } from '../../shared/terminal-restore-parity-fixture'
 
-// Differential garble gate for the hidden-terminal model/view contract:
-// with the hidden-delivery
-// gate on, a hidden pane receives NOTHING — main's HeadlessEmulator is the
-// source of truth and reveal repaints the renderer xterm from
-// preamble + rehydrateSequences + snapshotAnsi (applyMainBufferSnapshot).
-// This fuzz feeds seeded agent-TUI byte streams to the production emulator
-// and to an always-visible renderer-parity terminal, then asserts the
-// serialize→replay round trip reproduces the exact screen the renderer would
-// have shown. Any diff = a garble bug on reveal.
+// Differential garble gate for the hidden-terminal contract: a hidden pane gets nothing, so main's
+// HeadlessEmulator is source of truth and reveal repaints from the snapshot. This fuzz asserts the
+// serialize→replay round trip matches an always-visible renderer twin — any diff = a garble bug on reveal.
 //
 // Runtime knobs:
-//   FUZZ_ITERATIONS=5000  deep/nightly mode (default 300, <60s combined with
-//                         the reveal-reconciliation suite)
+//   FUZZ_ITERATIONS=5000  deep/nightly mode (default 300, keeps combined suite runtime <60s)
 //   FUZZ_SEED=1234        re-run exactly one seed (repro from a failure log)
 
 const DEFAULT_ITERATIONS = 300
 const FIXED_SEED = readPositiveIntEnv('FUZZ_SEED')
 const ITERATIONS =
   FIXED_SEED !== null ? 1 : (readPositiveIntEnv('FUZZ_ITERATIONS') ?? DEFAULT_ITERATIONS)
-// Matches HIDDEN_OUTPUT_RESTORE_SCROLLBACK_ROWS in pty-connection.ts — the
-// scrollback budget the reveal restore actually requests from main.
+// Matches HIDDEN_OUTPUT_RESTORE_SCROLLBACK_ROWS in pty-connection.ts — the reveal restore's scrollback budget.
 const HIDDEN_OUTPUT_RESTORE_SCROLLBACK_ROWS = 5000
 
 function readPositiveIntEnv(name: string): number | null {
@@ -64,9 +56,7 @@ type FidelityDiff = {
   stage: string
   expected: unknown
   actual: unknown
-  /** True when the always-visible buffer matches the known upstream
-   *  @xterm/addon-serialize blank-leading-wrapped-row bug predicate — see
-   *  bufferHasSerializeHostileWrappedRow and the skipped repro test below. */
+  /** True when the buffer trips the known upstream addon-serialize blank-leading-wrapped-row bug (see bufferHasSerializeHostileWrappedRow). */
   knownSerializeWrapBug?: boolean
 }
 
@@ -103,8 +93,7 @@ async function runFidelityCase(testCase: FidelityCase): Promise<FidelityDiff | n
     }
     await writeChunksToTerminal(control.terminal, chunks)
 
-    // Stage 1 — model fidelity: the emulator's screen must already match the
-    // renderer twin before any serialization enters the picture.
+    // Stage 1 — model fidelity: the emulator's screen must match the renderer twin before any serialization.
     const modelDiff = firstDiff(
       'model-visible (HeadlessEmulator vs renderer twin)',
       visibleRows(control.terminal),
@@ -114,9 +103,7 @@ async function runFidelityCase(testCase: FidelityCase): Promise<FidelityDiff | n
       return modelDiff
     }
 
-    // Stage 2 — reveal round trip: serialize exactly like
-    // serializeHiddenOutputRecoveryBuffer, replay exactly like
-    // applyMainBufferSnapshot, then compare against the always-visible twin.
+    // Stage 2 — reveal round trip: serialize like serializeHiddenOutputRecoveryBuffer, replay like applyMainBufferSnapshot, compare to the always-visible twin.
     const alt = emulator.isAlternateScreen
     const snapshot = emulator.getSnapshot({
       scrollbackRows: alt ? 0 : HIDDEN_OUTPUT_RESTORE_SCROLLBACK_ROWS
@@ -148,13 +135,7 @@ async function runFidelityCase(testCase: FidelityCase): Promise<FidelityDiff | n
         control.terminal.modes.bracketedPasteMode,
         restored.terminal.modes.bracketedPasteMode
       ),
-      // Why alt is excluded from the two comparisons below:
-      // - scrollback: serializeHeadlessTerminalBuffer (orca-runtime.ts)
-      //   deliberately forces scrollbackRows=0 while an alt-screen TUI is
-      //   active, so normal-buffer history is not part of the alt contract.
-      // - application cursor: HeadlessEmulator.getModes reports
-      //   applicationCursor false on the alternate buffer, so rehydrate omits
-      //   ?1h there by design.
+      // alt excludes both comparisons below by design: alt forces scrollbackRows=0 (no normal-buffer history) and reports applicationCursor=false (rehydrate omits ?1h).
       alt
         ? null
         : firstDiff(
@@ -185,9 +166,7 @@ async function runFidelityCase(testCase: FidelityCase): Promise<FidelityDiff | n
   }
 }
 
-/** Greedy op-drop minimizer: re-runs the full differential pipeline on
- *  smaller op lists so a failure report carries the smallest byte stream that
- *  still diverges (plus its seed for exact replay via FUZZ_SEED). */
+/** Greedy op-drop minimizer: shrinks a failing case to the smallest still-diverging op list (with its seed for FUZZ_SEED replay). */
 async function minimizeFailure(testCase: FidelityCase): Promise<FidelityCase> {
   let current = { ...testCase, chunked: false }
   if ((await runFidelityCase(current)) === null) {
@@ -221,12 +200,7 @@ function formatFailure(minimized: FidelityCase, diff: FidelityDiff | null): stri
 }
 
 describe('headless emulator snapshot fidelity fuzz', () => {
-  // Known-legitimate divergence, pinned so it cannot silently regress into a
-  // real one: xterm marks OSC 8 hyperlink cells underlined, SerializeAddon
-  // never re-emits OSC 8, and production compensates by shipping the ranges
-  // out-of-band in snapshot.oscLinks (collectHeadlessOscLinkRanges) for the
-  // renderer link provider to re-register. Byte-replay therefore keeps the
-  // TEXT but not the link underline — the metadata must carry the range.
+  // Known-legitimate divergence: SerializeAddon never re-emits OSC 8, so byte-replay drops the link underline; production carries the ranges out-of-band in snapshot.oscLinks.
   it('drops OSC 8 underline from byte replay but preserves the range in snapshot metadata', async () => {
     const emulator = new HeadlessEmulator({ cols: 60, rows: 10 })
     const restored = createRendererParityTerminal({ cols: 60, rows: 10 })
@@ -252,11 +226,7 @@ describe('headless emulator snapshot fidelity fuzz', () => {
   })
 
   it(`matches an always-visible renderer twin across ${ITERATIONS} seeded agent-TUI streams`, async () => {
-    // The known-and-pinned serialize wrap bug (A) is tolerated + counted so
-    // deep mode (FUZZ_ITERATIONS) surfaces only GENUINELY NEW divergences.
-    // Bugs B (bold-reset, fixed by the addon patch) and C (margin cursor,
-    // fixed by the absolute-cursor epilogue) are no longer tolerated — a
-    // regression fails the corpus loudly and the unskipped repros below.
+    // Bug A (serialize wrap) is tolerated + counted so deep mode surfaces only new divergences; B and C are fixed, so their regressions fail loudly.
     let knownSerializeWrapBugHits = 0
     for (let i = 0; i < ITERATIONS; i++) {
       const seed = FIXED_SEED ?? 1 + i
@@ -272,44 +242,14 @@ describe('headless emulator snapshot fidelity fuzz', () => {
         expect.fail(formatFailure(minimized, minimizedDiff ?? diff))
       }
     }
-    // Guard the tolerance from swallowing the suite: the predicate tripping
-    // on most seeds means the gate has gone degenerate.
+    // Guard the tolerance: the predicate tripping on most seeds means the gate has gone degenerate.
     expect(knownSerializeWrapBugHits).toBeLessThan(Math.max(3, ITERATIONS * 0.5))
   }, 600_000)
 
-  // ── HEADLINE FINDING (do not delete while unfixed upstream) ──────────────
-  // @xterm/addon-serialize 0.15.0-beta.287 does not round-trip null cells
-  // that touch a soft-wrap boundary. Two variants, both found by this fuzz
-  // and minimized below. Every Orca snapshot consumer is affected: hidden
-  // reveal, parked-tab reveal, sleep/wake restore, and mobile subscribe
-  // replay paint lost/shifted characters or stray '-' fillers whenever a TUI
-  // erased inside a soft-wrapped line (shell line editing, status lines wider
-  // than the pane, Claude Code in-place prompt redraws).
-  //
-  // V1 — cell loss (found by seed 31, minimized to 2 ops):
-  // Root cause: the wrap-validity ternary in SerializeAddon.ts (~L214)
-  //   nextRowFirstChar.getChars() && isNextRowFirstCharDoubleWidth
-  //     ? this._nullCellCount <= 1 : this._nullCellCount <= 0
-  // binds as `(chars && doubleWidth) ? ...`, so a null-leading wrapped row
-  // passes as a "natural" wrap. The serializer then emits the previous row as
-  // full-width text (leaving xterm in wrap-pending) and skips the null cell
-  // with CUF (`ESC[1C`) — but CUF clamps at the right margin instead of
-  // crossing the wrap boundary, so the next character overwrites the previous
-  // row's last cell and the whole tail shifts left by one.
-  //   cols=20: write 'ABCDEFGHIJKLMNOPQRSTUVWXYZ12\r\n' then '\x1b[1A\x1b[1K'
-  //   live rows:     ['ABCDEFGHIJKLMNOPQRST', ' VWXYZ12']
-  //   serialize():   'ABCDEFGHIJKLMNOPQRST\x1b[1CVWXYZ12\x1b[8D'
-  //   replayed rows: ['ABCDEFGHIJKLMNOPQRSV', 'WXYZ12']   ← 'T' eaten, tail shifted
-  //
-  // V2 — stray filler '-' (found by seed 157, minimized below): when the
-  // SOURCE row of a wrapped pair is entirely null (a TUI erased the whole
-  // first half of a wrapped line), the addon's forced-wrap "magic" writes
-  // nullCellCount+1 dashes and then cleans up with
-  //   ESC[A ESC[(length-nullCellCount)C ESC[(nullCellCount)X ...
-  // With length === nullCellCount that cursor-forward becomes `ESC[0C`, and
-  // CSI param 0 means 1, so the ECH erase lands one cell right and the first
-  // '-' stays visible on the restored row.
-  // Unskip once the upstream fix (or a local serialize post-processor) lands.
+  // HEADLINE FINDING (do not delete while unfixed upstream): @xterm/addon-serialize 0.15.0-beta.287
+  // doesn't round-trip null cells at a soft-wrap boundary, garbling every snapshot restore of a TUI that
+  // erased inside a soft-wrapped line. Repros below — V1 cell loss (seed 31, SerializeAddon.ts ~L214
+  // wrap-validity ternary), V2 stray '-' filler (seed 157). Unskip once the upstream fix lands.
   it.skip('round-trips a wrapped line whose continuation row starts with an erased cell', async () => {
     const emulator = new HeadlessEmulator({ cols: 20, rows: 6 })
     const control = createRendererParityTerminal({ cols: 20, rows: 6 })
@@ -334,15 +274,13 @@ describe('headless emulator snapshot fidelity fuzz', () => {
     }
   })
 
-  // V2 repro of the headline finding above (stray '-' filler on a fully
-  // erased wrapped source row). Unskip alongside the V1 repro.
+  // V2 repro of the headline finding (stray '-' on a fully erased wrapped source row); unskip with V1.
   it.skip('round-trips a wrapped line whose source row was fully erased', async () => {
     const emulator = new HeadlessEmulator({ cols: 20, rows: 6 })
     const control = createRendererParityTerminal({ cols: 20, rows: 6 })
     const restored = createRendererParityTerminal({ cols: 20, rows: 6 })
     try {
-      // Wrap a 28-char line, then erase the entire first (source) row of the
-      // wrapped pair: cursor up twice onto it, EL 2.
+      // Wrap a 28-char line, then erase its entire first (source) row: cursor up twice, EL 2.
       const bytes = ['ABCDEFGHIJKLMNOPQRSTUVWXYZ12\r\n', '\x1b[2A\x1b[2K']
       for (const chunk of bytes) {
         await emulator.write(chunk)
@@ -363,20 +301,13 @@ describe('headless emulator snapshot fidelity fuzz', () => {
     }
   })
 
-  // ── Bug B regression guard: SGR bold on a dim→bold-only cell transition ──
-  // Upstream @xterm/addon-serialize emitted `\x1b[1;22m` for this transition;
-  // SGR 22 (normalIntensity) clears BOTH bold and dim, so the restored cell
-  // lost its bold. FIXED by the intensity-group reorder in
-  // config/patches/@xterm__addon-serialize@0.15.0-beta.287.patch (22 before
-  // 1/2). Found by fuzz seeds 435, 770, 1321; mechanism in
-  // notes/garble-fuzz-divergences.md (Bug B).
+  // Bug B guard: upstream emitted 1;22m and SGR 22 clears both bold and dim, dropping bold; fixed by the intensity-group reorder in the addon-serialize patch. notes/garble-fuzz-divergences.md
   it('preserves bold when serializing a dim cell followed by a bold-only cell', async () => {
     const emulator = new HeadlessEmulator({ cols: 20, rows: 4 })
     const control = createRendererParityTerminal({ cols: 20, rows: 4 })
     const restored = createRendererParityTerminal({ cols: 20, rows: 4 })
     try {
-      // 'A' dim, 'B' bold-only. Live: A=dim, B=bold. The patched serializer
-      // emits 22;1 for the B transition (clear before re-set).
+      // 'A' dim, 'B' bold-only; patched serializer emits 22;1 for B (clear before re-set).
       const bytes = ['\x1b[2mA\x1b[22m\x1b[1mB\x1b[0m']
       for (const chunk of bytes) {
         await emulator.write(chunk)
@@ -396,19 +327,13 @@ describe('headless emulator snapshot fidelity fuzz', () => {
     }
   })
 
-  // ── Bug C regression guard: cursor exact when the last row fills the margin ──
-  // Upstream @xterm/addon-serialize computes its relative cursor-restore from
-  // a wrap-pending position and lands one column short. FIXED Orca-side: the
-  // emulator snapshot appends an absolute CUP from the source's authoritative
-  // cursor (serializeWithAbsoluteCursor). Found by fuzz seeds 454, 1696;
-  // mechanism in notes/garble-fuzz-divergences.md (Bug C).
+  // Bug C guard: upstream serialize lands the cursor one col short (wrap-pending); fixed by absolute-CUP epilogue (serializeWithAbsoluteCursor). notes/garble-fuzz-divergences.md
   it('restores the cursor exactly when the last content row fills the right margin', async () => {
     const emulator = new HeadlessEmulator({ cols: 10, rows: 4 })
     const control = createRendererParityTerminal({ cols: 10, rows: 4 })
     const restored = createRendererParityTerminal({ cols: 10, rows: 4 })
     try {
-      // Fill row 0 to exactly 10 cols (wrap-pending), then CUP the cursor to a
-      // known lower-row column. Live cursor is (x=4, y=2).
+      // Fill row 0 to the margin (wrap-pending), then CUP to a lower row; live cursor is (x=4, y=2).
       const bytes = ['0123456789\x1b[3;5H']
       for (const chunk of bytes) {
         await emulator.write(chunk)
diff --git a/src/main/daemon/headless-emulator.ts b/src/main/daemon/headless-emulator.ts
index e1950d9caf5..7cd36fe80f3 100644
--- a/src/main/daemon/headless-emulator.ts
+++ b/src/main/daemon/headless-emulator.ts
@@ -25,13 +25,7 @@ export type HeadlessEmulatorOptions = {
   cols: number
   rows: number
   scrollback?: number
-  /** Phase-5 model query responder sink (terminal-query-authority.md).
-   *  When set, xterm-core auto-replies generated while parsing a write
-   *  flagged `forwardQueryReplies` are forwarded here; all other emissions
-   *  (seeds, hydration, snapshot replay, unsolicited core pushes) are
-   *  discarded. The daemon Session must NEVER pass this — its emulator
-   *  stays write-only forever (contract invariant: the daemon never
-   *  answers). */
+  /** Query reply sink (terminal-query-authority.md); only `forwardQueryReplies` writes emit here. The daemon Session must never pass this. */
   onQueryReply?: (reply: string) => void
   pathFlavor?: 'posix' | 'win32'
   remotePosixFileUriAuthority?: boolean
@@ -39,17 +33,14 @@ export type HeadlessEmulatorOptions = {
 }
 
 export type HeadlessEmulatorWriteOptions = {
-  /** Reply ownership captured at ingestion for this exact chunk. Default
-   *  false is the main-side replay guard (twin of the renderer's
-   *  replay-guard.ts): seed/hydration/snapshot writes never forward. */
+  /** Reply ownership for this exact chunk; default false so seed/hydration/snapshot writes never forward (main-side replay guard; twin of renderer replay-guard.ts). */
   forwardQueryReplies?: boolean
 }
 
 type TerminalWithSynchronousWrite = Terminal & {
   _core?: {
     writeSync?: (data: string) => void
-    // Why: kitty keyboard flags are not on the public IModes; read the core
-    // service state the CSI =/>/< u handlers mutate.
+    // Why: kitty keyboard flags aren't on the public IModes; read the core service the CSI u handlers mutate.
     coreService?: {
       kittyKeyboard?: { flags?: number }
     }
@@ -57,18 +48,12 @@ type TerminalWithSynchronousWrite = Terminal & {
 }
 
 const DEFAULT_SCROLLBACK = 5000
-// Keep in sync with the renderer twin in terminal-capability-replies.ts
-// (main must not import renderer modules).
+// Keep in sync with the renderer twin terminal-capability-replies.ts (main must not import renderer modules).
 const CONPTY_DA1_RESPONSE = '\x1b[?61;4c'
 
 export class HeadlessEmulator {
   private terminal: Terminal
   private serializer: SerializeAddon
-  // Why: our restructure owns cwd/title via TerminalOscCwdTitleScanner and the
-  // DECSET mouse modes via TerminalMouseModeMirror (functionally identical to
-  // main's inline cwd/lastTitle/oscScanTail + TerminalPrivateModeTracker, which
-  // only tracks the same mouse modes). restoredOscLinks/disposed/partialEscapeTail
-  // are declared below.
   private oscText: TerminalOscCwdTitleScanner
   private mouseModes = new TerminalMouseModeMirror()
   private readonly pathFlavor?: 'posix' | 'win32'
@@ -78,15 +63,9 @@ export class HeadlessEmulator {
   private onQueryReply: ((reply: string) => void) | null
   private conptyDa1OverrideInstalled = false
   private viewAttributeResponder: TerminalViewAttributeResponder | null = null
-  // Why: replies must be scoped to the exact write that carried the query.
-  // The window opens around the parse of a forward-flagged chunk and closes
-  // with it, so seeds/snapshots and unsolicited core emissions (e.g. native
-  // 997 pushes from option mutations) can never leak to the PTY.
+  // Why: replies must be scoped to the exact write that carried the query, so seeds/snapshots and unsolicited emissions never leak to the PTY.
   private queryReplyForwardingDepth = 0
-  // Why: a chunk ending mid-escape leaves the sequence in xterm's parser, not
-  // the buffer, so serialize() drops it and the next chunk's continuation
-  // renders literal after a restore (Bug E, notes/garble-fuzz-divergences.md).
-  // Committed alongside mouseModes: only after xterm parsed the same bytes.
+  // Why: a mid-escape chunk tail lives in xterm's parser, not the buffer, so serialize() drops it and it renders literal after restore (Bug E).
   private partialEscapeTail = ''
 
   constructor(opts: HeadlessEmulatorOptions) {
@@ -103,51 +82,27 @@ export class HeadlessEmulator {
       scrollback: opts.scrollback ?? DEFAULT_SCROLLBACK,
       allowProposedApi: true,
       logLevel: 'off',
-      // Why: parity with the renderer's buildDefaultTerminalOptions — parse
-      // CSI =/>/< u pushes so CSI ? u answers with the flags the hidden app
-      // actually pushed. Write-only daemon use is unaffected: keyboard state
-      // never alters serialization (terminal-query-authority.md §kitty).
+      // Why: parse CSI =/>/< u pushes so CSI ? u answers with the flags the hidden app pushed (renderer parity).
       vtExtensions: { kittyKeyboard: true }
     })
 
     this.serializer = new SerializeAddon()
     this.terminal.loadAddon(this.serializer)
 
-    // Why: this mirror must measure character widths exactly like the
-    // renderer's xterm (Unicode 11 + ZWJ emoji joining). With the default v6
-    // tables, emoji-dense rows (agent status lines) advance the cursor
-    // differently here than on screen, so the mirrored buffer accumulates
-    // cell-shifted tears that snapshot restores then paint back as garbage.
+    // Why Unicode 11: must match the renderer's char-width measurement, else emoji rows mismeasure and the mirror accumulates cell-shifted tears.
     this.terminal.loadAddon(new Unicode11Addon())
     activateOrcaTerminalUnicodeProvider(this.terminal)
 
-    // Why onData is gated behind onQueryReply: by default this emulator is
-    // pure state tracking and MUST NOT respond to terminal query sequences
-    // (DA1/DA2, DSR, OSC 10/11/12, DECRPM). The daemon emulator parses data
-    // in-process synchronously before `handleSubprocessData` forwards it to
-    // the renderer over IPC, so any reply it emitted would land on the
-    // shell's stdin ahead of the renderer's xterm reply and win the race —
-    // a double-reply with default-xterm values (OSC 11 default-black was
-    // the visible casualty). Only main's runtime per-PTY emulators pass a
-    // sink, and even then replies flow only for chunks the hidden-delivery
-    // gate DROPPED, where the renderer never sees the bytes and main is the
-    // single answerer under main's terminal query authority.
+    // Why gated: an emulator query reply would beat the renderer's to the shell's stdin (OSC 11 default-black was the casualty).
     this.onQueryReply = opts.onQueryReply ?? null
     if (this.onQueryReply) {
       this.terminal.onData((reply) => this.emitQueryReply(reply))
     }
   }
 
-  /** Main-side twin of the renderer's terminal-capability-replies.ts:
-   *  ConPTY 1.22+ blocks at spawn waiting for a DA1 reply, and the override
-   *  variant (`CSI ?61;4c`) must win. Returning true consumes the query so
-   *  xterm core's default `?1;2c` cannot double-reply (custom CSI handlers
-   *  run before core's; false falls through). The reply still routes through
-   *  the forwarding window, so replayed/seeded bytes never answer. */
+  /** ConPTY 1.22+ blocks at spawn awaiting a DA1 reply; answers `CSI ?61;4c` and consumes the query so xterm's default `?1;2c` can't double-reply. */
   installConptyPrimaryDeviceAttributesOverride(): void {
-    // Why idempotent: the spawn mark can land after daemon stream data
-    // already created the emulator, so the override is installed both at
-    // creation and retrofitted at mark time — never stacked.
+    // Why idempotent: installed at creation and again at spawn-mark time (which can land later), so it's never stacked.
     if (this.conptyDa1OverrideInstalled) {
       return
     }
@@ -162,11 +117,7 @@ export class HeadlessEmulator {
     })
   }
 
-  /** Phase-5 slice-2 view-attribute bridge: the headless core has no theme
-   *  service, so OSC 4/10/11/12 queries and DSR ?996n are answered from the
-   *  renderer's pushed attributes via these parser handlers — never from
-   *  emulator defaults. Runtime-only, like onQueryReply: the daemon Session
-   *  must NEVER call this (its emulator stays write-only forever). */
+  /** Headless core has no theme service, so OSC 4/10/11/12 and DSR ?996n answer from the renderer's pushed attributes; daemon Session must never call this. */
   installViewAttributeResponder(getBaseAttributes: () => TerminalViewAttributes | null): void {
     if (this.viewAttributeResponder) {
       return
@@ -174,18 +125,12 @@ export class HeadlessEmulator {
     this.viewAttributeResponder = installTerminalViewAttributeResponder({
       parser: this.terminal.parser,
       getBaseAttributes,
-      // emitQueryReply keeps replies inside the per-chunk forwarding window,
-      // so seeded/replayed view-attribute queries answer no one.
+      // emitQueryReply keeps replies in the per-chunk forwarding window, so seeded/replayed queries answer no one.
       emitReply: (reply) => this.emitQueryReply(reply)
     })
   }
 
-  /** Applies a renderer view-attribute push: cursor options make xterm core
-   *  answer DECRQSS DECSCUSR / DECRQM 12 renderer-true, and the per-PTY OSC
-   *  color overrides are dropped because a theme apply overwrites mutated
-   *  colors on visible panes too (ThemeService._setTheme parity). Option
-   *  writes happen outside any forwarding window, so any core emission they
-   *  trigger is discarded (main-side replay guard). */
+  /** Sets cursor options so xterm answers DECSCUSR / DECRQM 12 renderer-true; per-PTY color overrides are dropped (a theme apply overwrites them anyway). */
   applyPushedViewAttributes(attributes: TerminalViewAttributes): void {
     if (this.disposed) {
       return
@@ -195,13 +140,7 @@ export class HeadlessEmulator {
     this.viewAttributeResponder?.clearColorOverrides()
   }
 
-  /** Re-seed parity for snapshot `modes.kittyKeyboardFlags`
-   *  (terminal-query-authority.md §kitty): replays the persisted flags
-   *  through the same `CSI = flags ; 1 u` parse a live push uses, so hidden
-   *  `CSI ? u` reports them instead of `?0u`. Routed as an UNFLAGGED write —
-   *  outside any forwarding window, it can never answer anything — and never
-   *  into renderer rehydrateSequences (POST_REPLAY_REATTACH_RESET's kitty
-   *  reset stays authoritative). */
+  /** Re-seeds snapshot kitty flags via the live-push parse, routed unflagged so it can never answer a query (terminal-query-authority.md). */
   applyKittyKeyboardFlags(flags: number): Promise<void> {
     if (!Number.isInteger(flags) || flags <= 0) {
       return Promise.resolve()
@@ -215,9 +154,7 @@ export class HeadlessEmulator {
     }
   }
 
-  /** Severs the reply sink at PTY teardown. Queued writeChain links may
-   *  still parse after dispose is requested, and daemon respawns reuse
-   *  session ids — a late reply must never reach a successor PTY. */
+  /** Severs the reply sink so a post-dispose reply can't reach a successor PTY (respawns reuse session ids). */
   disableQueryReplyForwarding(): void {
     this.onQueryReply = null
   }
@@ -232,12 +169,7 @@ export class HeadlessEmulator {
       return Promise.resolve()
     }
     this.oscText.scan(data)
-    // Why the sentinel: xterm parses queued writes asynchronously, so opening
-    // the window at enqueue time would leak it over earlier queued unflagged
-    // chunks (seed/hydration bytes parsing while depth > 0). Write callbacks
-    // fire in FIFO parse order, so a zero-byte write whose callback opens the
-    // window brackets the parse of exactly this chunk; the data callback
-    // closes it.
+    // Why the sentinel: xterm parses writes async, so its zero-byte callback fires in FIFO order to open the window at exactly this chunk.
     if (forwardQueryReplies) {
       this.terminal.write('', () => {
         this.queryReplyForwardingDepth += 1
@@ -248,8 +180,7 @@ export class HeadlessEmulator {
         if (forwardQueryReplies) {
           this.queryReplyForwardingDepth -= 1
         }
-        // Why: snapshots combine serialized xterm state with mirrored mouse
-        // modes. Commit the mirror only after xterm has parsed the same bytes.
+        // Why: commit the mouse-mode mirror only after xterm has parsed the same bytes (snapshots combine both).
         this.mouseModes.scan(data)
         this.partialEscapeTail = advancePartialEscapeTail(this.partialEscapeTail, data)
         resolve()
@@ -257,10 +188,7 @@ export class HeadlessEmulator {
     })
   }
 
-  /** Synchronous write used by cold-restore log replay, where a snapshot is
-   *  taken immediately after the last record and queued async writes would
-   *  serialize a half-applied stream. Returns false when xterm's synchronous
-   *  write path is unavailable — callers must then abandon the replay. */
+  /** Synchronous write for cold-restore replay (async would snapshot a half-applied stream); false when writeSync is unavailable. */
   writeSync(data: string): boolean {
     if (this.disposed) {
       return false
@@ -278,8 +206,7 @@ export class HeadlessEmulator {
     if (forwardQueryReplies) {
       this.queryReplyForwardingDepth += 1
     }
-    // Why: hidden renderer restore snapshots are requested immediately after
-    // PTY bursts; queued headless writes can snapshot half-cleared TUI rows.
+    // Why: restore snapshots are requested right after PTY bursts; queued writes could snapshot half-cleared TUI rows.
     try {
       writeSync.call((this.terminal as TerminalWithSynchronousWrite)._core, data)
     } finally {
@@ -300,21 +227,14 @@ export class HeadlessEmulator {
     this.terminal.resize(cols, rows)
   }
 
-  // Why: Session.resize applies this emulator and the node-pty subprocess
-  // together behind the same dead/invalid-size gate, so the emulator's dims are
-  // an accurate proxy for the size the child actually took — and stay stale
-  // when a resize is dropped, which is exactly the drop the renderer must detect.
+  // Why: these dims proxy the child's real size, so they stay stale on a dropped resize the renderer must detect.
   getAppliedSize(): { cols: number; rows: number } {
     return { cols: this.terminal.cols, rows: this.terminal.rows }
   }
 
   getSnapshot(opts: { scrollbackRows?: number } = {}): TerminalSnapshot {
     const modes = this.getModes()
-    // Why serializeWithAbsoluteCursor: SerializeAddon's relative cursor
-    // restore lands one column short after a margin-filling final row leaves
-    // replay wrap-pending; the trailing CUP survives the alt-marker slice.
-    // The saved-cursor register rides along so a post-restore DECRC lands
-    // where the hidden TUI saved, not at home.
+    // Why absolute: relative cursor restore is off by a column after a wrap-pending final row; saved-cursor rides along for DECRC.
     const serializedAnsi = serializeWithAbsoluteCursor(
       this.serializer,
       this.terminal,
@@ -337,20 +257,13 @@ export class HeadlessEmulator {
       rows: this.terminal.rows,
       scrollbackLines: this.terminal.buffer.normal.length - this.terminal.rows,
       lastTitle: this.oscText.lastTitle ?? undefined,
-      // Why: written LAST by the restorer (after any reset) so the next live
-      // chunk completes this dangling sequence instead of rendering it literally
-      // (Bug E / #7329). Its bytes are already counted by the snapshot seq.
+      // Why written LAST by the restorer: the next live chunk must complete this dangling sequence, not render it literally (Bug E / #7329).
       ...(this.partialEscapeTail.length > 0
         ? { pendingEscapeTailAnsi: this.partialEscapeTail }
         : {})
     }
     if (this.partialEscapeTail.length > 0) {
-      // Why a separate field, not part of snapshotAnsi: consumers write their
-      // own reset sequences after the snapshot body, and any ESC written after
-      // a dangling partial would abort it. The restorer must write this LAST,
-      // immediately before post-snapshot live chunks. Its bytes are already
-      // counted by the snapshot seq (they were ingested), so tail-slicing
-      // arithmetic is unchanged.
+      // Why a separate field: consumers write their own reset sequences after the body, and any ESC after a dangling partial would abort it.
       snapshot.pendingEscapeTailAnsi = this.partialEscapeTail
     }
     return snapshot
@@ -360,21 +273,12 @@ export class HeadlessEmulator {
     return this.terminal.buffer.active.type === 'alternate'
   }
 
-  /** The dangling incomplete escape at the current stream position (empty
-   *  when none). Scan-authority handoffs seed the other side's fact scanners
-   *  with it so a sequence split across the handoff neither mints a phantom
-   *  bell (unseen OSC terminator) nor loses its fact. Contains no complete
-   *  sequence by construction, so seeding can never double-fire. */
+  /** Dangling incomplete escape at the stream position; handoffs seed the other side so a split sequence isn't lost. */
   get partialEscapeTailAnsi(): string {
     return this.partialEscapeTail
   }
 
-  /** Why: PSReadLine's Ctrl+L repaint is only safe at an empty prompt — with
-   *  pending input it re-renders at a cached buffer row that ConPTY's fixed
-   *  viewport doesn't track, painting the input well below the prompt. The
-   *  cursor line counts as an empty prompt when everything before the cursor
-   *  ends with a single '>' and nothing follows it ('>>' is PowerShell's
-   *  continuation prompt, i.e. a multiline edit in flight). */
+  /** PSReadLine's Ctrl+L repaint is only safe at an empty prompt; '>>' is PowerShell's continuation prompt, not empty. */
   isCursorOnEmptyPromptLine(): boolean {
     const buffer = this.terminal.buffer.active
     const line = buffer.getLine(buffer.baseY + buffer.cursorY)
diff --git a/src/main/daemon/hibernation-cold-restore-repro.test.ts b/src/main/daemon/hibernation-cold-restore-repro.test.ts
index 4d5281364d9..e80fb6f8a80 100644
--- a/src/main/daemon/hibernation-cold-restore-repro.test.ts
+++ b/src/main/daemon/hibernation-cold-restore-repro.test.ts
@@ -6,38 +6,14 @@ import { HistoryManager } from './history-manager'
 import { HistoryReader } from './history-reader'
 import { HeadlessEmulator } from './headless-emulator'
 
-// Reproduction for the "blank pane after agent hibernation" bug.
-//
-// Verified root cause (NOT the meta.endedAt gate — see below):
-// Agent hibernation force-kills the agent PTY via the immediate path
-// (pty:kill -> shutdown({ immediate: true, keepHistory: true }) ->
-// TerminalHost.kill(immediate) -> forceKillAndDisposeSubprocess), which reaps
-// synchronously WITHOUT firing onExit. So closeSession never runs and
-// meta.endedAt stays null — detectColdRestore does NOT reject the session.
-//
-// The actual blank comes from cold-restore CONTENT, not eligibility:
-// Claude/Codex TUIs run in terminal alternate-screen mode. For an alt-screen
-// snapshot, HistoryReader.coldRestoreInfoFromSnapshot returns scrollbackAnsi=''
-// (history-reader.ts:190-191), and DaemonPtyAdapter then skips the cold-restore
-// payload entirely on `if (scrollback)` (daemon-pty-adapter.ts:230) — "no
-// content is better than a confusing empty restore." Result: the daemon sends
-// nothing back on wake and the preserved pane repaints blank, even though a
-// full snapshotAnsi of the agent's last screen is intact on disk.
-//
-// This test drives a real HeadlessEmulator into alt-screen mode, checkpoints it
-// through the real HistoryManager, and asserts the empty-scrollback outcome the
-// adapter treats as "no cold restore".
-//
-// Scope note: this file documents the bug MECHANISM at the emulator/reader layer
-// and replicates the adapter's payload decision inline, so its post-fix
-// assertions would still pass if the production line were reverted. The actual
-// regression guard that exercises DaemonPtyAdapter.spawn() end-to-end lives in
-// daemon-pty-adapter.test.ts ("cold-restores an alt-screen agent snapshot…").
+// Reproduces the "blank pane after agent hibernation" bug: alt-screen TUI snapshots have scrollbackAnsi='', so the adapter's
+// `if (scrollback)` gate (daemon-pty-adapter.ts:230) dropped the cold-restore payload and repainted blank despite an intact snapshotAnsi.
+// Not the meta.endedAt gate: hibernation's immediate kill never fires onExit, so endedAt stays null (session not rejected).
+// This test inlines the adapter's decision, so it'd pass even if the fix were reverted; the real end-to-end guard is daemon-pty-adapter.test.ts.
 
 const ALT_SCREEN_ON = '\x1b[?1049h'
 
-// Note: HistoryManager.checkpoint() takes the emulator's TerminalSnapshot directly
-// and stamps generation / checkpointedAt itself, so em.getSnapshot() is passed as-is.
+// Note: checkpoint() stamps generation/checkpointedAt itself, so em.getSnapshot() is passed as-is.
 
 describe('agent hibernation cold-restore (alt-screen TUI)', () => {
   let dir: string
@@ -65,8 +41,7 @@ describe('agent hibernation cold-restore (alt-screen TUI)', () => {
     expect(info).not.toBeNull()
     // Adapter uses rehydrateSequences + snapshotAnsi for non-alt-screen → non-empty.
     expect(info!.modes.alternateScreen).toBe(false)
-    // Normal-screen restores carry their buffer as scrollback; assert both so a
-    // regression that empties scrollbackAnsi can't slip past this control.
+    // Normal-screen restores carry their buffer as scrollback; assert both so a regression emptying scrollbackAnsi can't slip past.
     expect(info!.scrollbackAnsi).toContain('hello')
     expect(info!.snapshotAnsi).toContain('hello')
   })
@@ -75,8 +50,7 @@ describe('agent hibernation cold-restore (alt-screen TUI)', () => {
     const manager = new HistoryManager(dir)
     const reader = new HistoryReader(dir)
     const em = new HeadlessEmulator({ cols: 80, rows: 24 })
-    // Why: Claude/Codex enter the alternate screen. Once in alt-screen, the
-    // serialized snapshot is the TUI buffer and scrollbackAnsi is empty.
+    // Why: in alt-screen (Claude/Codex TUIs) the serialized snapshot is the TUI buffer and scrollbackAnsi is empty.
     em.writeSync(ALT_SCREEN_ON)
     em.writeSync('\x1b[2J\x1b[H Claude Code — Opus 4.8\r\n > ')
     expect(em.isAlternateScreen).toBe(true)
@@ -86,20 +60,15 @@ describe('agent hibernation cold-restore (alt-screen TUI)', () => {
     em.dispose()
 
     const info = reader.detectColdRestore(sessionId)
-    // The session IS eligible (endedAt is null — hibernation's immediate kill
-    // never stamps it), and the snapshot of the agent's screen is intact...
+    // Session is eligible (endedAt null) and the agent's snapshot is intact.
     expect(info).not.toBeNull()
     expect(info!.modes.alternateScreen).toBe(true)
     expect(info!.snapshotAnsi.length).toBeGreaterThan(0)
 
-    // scrollbackAnsi is empty for alt-screen (the bug's trigger). Pre-fix the
-    // adapter's `isAltScreen ? scrollbackAnsi || null : ...` dropped the
-    // payload here, leaving the pane blank.
+    // scrollbackAnsi is empty for alt-screen — the bug's trigger; pre-fix the adapter dropped the payload here, leaving the pane blank.
     expect(info!.scrollbackAnsi).toBe('')
 
-    // Replicate the adapter's POST-FIX payload decision: alt-screen falls
-    // back to snapshotAnsi (the agent's last frame) when scrollbackAnsi is
-    // empty, so the pane is no longer blank on wake.
+    // Replicate the adapter's post-fix decision: alt-screen falls back to snapshotAnsi when scrollbackAnsi is empty, so the pane isn't blank.
     const isAltScreen = info!.modes.alternateScreen
     const adapterScrollback = isAltScreen
       ? info!.scrollbackAnsi || info!.snapshotAnsi || null
@@ -125,13 +94,8 @@ describe('agent hibernation cold-restore (alt-screen TUI)', () => {
       : info!.rehydrateSequences + info!.snapshotAnsi
     expect(adapterScrollback).not.toBeNull()
 
-    // Drive the renderer's cold-restore branch into a FRESH shell emulator:
-    // clear, write the payload, then POST_REPLAY_MODE_RESET. The pane must end
-    // in the normal buffer (no \x1b[?1049h fed) so it won't fight the agent's
-    // own repaint when the resume command relaunches it.
-    // Keep in sync with POST_REPLAY_MODE_RESET in
-    // src/renderer/src/components/terminal-pane/layout-serialization.ts (copied
-    // as a literal because a main-process test must not import a renderer module).
+    // Must end in the normal buffer (no alt-screen re-entry) so it won't fight the agent's own repaint when resume relaunches it.
+    // POST_REPLAY_MODE_RESET copied literally from renderer layout-serialization.ts (main-process test can't import renderer) — keep in sync.
     const POST_REPLAY_MODE_RESET =
       '\x1b[0 q\x1b[<99u\x1b[=0u\x1b[?25h\x1b[?9l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?1016l\x1b[?1004l\x1b[?2004l'
     const fresh = new HeadlessEmulator({ cols: 80, rows: 24 })
@@ -147,10 +111,7 @@ describe('agent hibernation cold-restore (alt-screen TUI)', () => {
     const manager = new HistoryManager(dir)
     const reader = new HistoryReader(dir)
     const em = new HeadlessEmulator({ cols: 80, rows: 24 })
-    // Alt-screen entered but nothing drawn. SerializeAddon still emits a bare
-    // cursor-home (\x1b[H), so the payload is non-null but visually empty —
-    // safe to write into the fresh shell and crucially never re-enters
-    // alt-screen (rehydrateSequences is omitted).
+    // Alt-screen but nothing drawn: SerializeAddon emits only a bare cursor-home, so the payload never re-enters alt-screen.
     em.writeSync(ALT_SCREEN_ON)
 
     await manager.openSession(sessionId, { cwd: '/home/user/project', cols: 80, rows: 24 })
diff --git a/src/main/daemon/history-manager.ts b/src/main/daemon/history-manager.ts
index 47b96b14547..1af27025182 100644
--- a/src/main/daemon/history-manager.ts
+++ b/src/main/daemon/history-manager.ts
@@ -21,10 +21,7 @@ import {
 } from './terminal-history-log'
 import type { PendingOutputRecord, TerminalCheckpointFile, TerminalSnapshot } from './types'
 
-// Why 5MB: bounds both cold-restore replay time and disk usage per session.
-// Reaching the cap triggers one full snapshot checkpoint (which subsumes and
-// resets the log) — one O(buffer) serialize per ~5MB of output instead of one
-// per 5-second tick.
+// Why 5MB: bounds cold-restore replay time and per-session disk; hitting the cap triggers one checkpoint that resets the log.
 const LOG_MAX_BYTES = 5 * 1024 * 1024
 
 export type SessionMeta = {
@@ -46,8 +43,7 @@ type SessionWriter = {
   dir: string
   checkpointPath: string
   logPath: string
-  /** Generation of the on-disk log header. Null until lazily resolved on the
-   *  first append after a warm registerWriter (the file may predate us). */
+  /** Generation of the on-disk log header. Null until lazily resolved on first append after a warm registerWriter. */
   logGeneration: number | null
   /** Current log file size. Null until lazily resolved alongside generation. */
   logBytes: number | null
@@ -84,13 +80,7 @@ export class HistoryManager {
       }
       writeFileSync(join(dir, 'meta.json'), JSON.stringify(meta, null, 2))
 
-      // Why: if a session ID is reused after a previous clean exit, stale
-      // recovery files may still be on disk. Without removing them, a crash
-      // before the first 5s checkpoint tick would cause detectColdRestore to
-      // replay stale terminal content from the previous session. Both
-      // checkpoint.json and scrollback.bin (legacy) must be cleaned up
-      // because the reader falls back to scrollback.bin when no checkpoint
-      // exists.
+      // Why: clear stale recovery files (incl. legacy scrollback.bin) so a crash before the first checkpoint can't replay a prior session's content.
       const checkpointPath = join(dir, 'checkpoint.json')
       const logPath = join(dir, 'output.log')
       for (const staleFile of [checkpointPath, join(dir, 'scrollback.bin'), logPath]) {
@@ -113,11 +103,7 @@ export class HistoryManager {
     }
   }
 
-  // Why: on warm reattach after app relaunch, the HistoryManager is a fresh
-  // instance with no in-memory writers. This registers the writer so
-  // checkpoint() calls work, without overwriting meta.json or deleting the
-  // existing checkpoint.json (which is the only valid recovery data until
-  // the next checkpoint tick writes a fresh one).
+  // Why: warm reattach has no in-memory writers; re-register without touching meta.json or checkpoint.json (only recovery data until the next tick).
   registerWriter(sessionId: string): void {
     if (this.writers.has(sessionId)) {
       return
@@ -132,10 +118,7 @@ export class HistoryManager {
     })
   }
 
-  // Why: wake after sleep re-spawns a session whose history was closed by the
-  // sleep-time kill. Re-register the writer without deleting checkpoint.json
-  // (still the only recovery data until the next tick) and clear endedAt so
-  // the next sleep can cold-restore this session again.
+  // Why: wake re-spawns a sleep-killed session; re-register without deleting checkpoint.json, clear endedAt so it can cold-restore again.
   reopenSession(sessionId: string): void {
     this.disabledSessions.delete(sessionId)
     this.registerWriter(sessionId)
@@ -151,16 +134,12 @@ export class HistoryManager {
   }
 
   suspendSession(sessionId: string): void {
-    // Why: if a fresh daemon cannot accept recovered scrollback, leaving its
-    // writer active would let the next checkpoint overwrite the only good copy.
+    // Why: leaving the writer active would let the next checkpoint overwrite the only good recovered-scrollback copy.
     this.writers.delete(sessionId)
     this.disabledSessions.delete(sessionId)
   }
 
-  /** Appends one take batch to the incremental log. Returns 'needs-checkpoint'
-   *  when the log is at capacity — the caller must take a full snapshot, which
-   *  subsumes the un-appended records (they were already applied to the live
-   *  emulator) and resets the log via checkpoint(). */
+  /** Appends one batch to the incremental log; returns 'needs-checkpoint' at capacity, signalling the caller to checkpoint() (which resets the log). */
   async appendIncrements(
     sessionId: string,
     seq: number,
@@ -176,16 +155,13 @@ export class HistoryManager {
     try {
       this.resolveLogState(writer)
       const batch = encodeLogBatch(seq, records)
-      // Why max(..., header): a fresh log gets its header written below, so
-      // the projected size must include it or the cap can be overshot.
+      // Why max(..., header): a fresh log's header (written below) must count toward the projected size or the cap overshoots.
       const projectedBytes = Math.max(writer.logBytes ?? 0, LOG_HEADER_BYTES) + batch.length
       if (projectedBytes > LOG_MAX_BYTES) {
         return 'needs-checkpoint'
       }
       if (writer.logBytes === 0) {
-        // Why: header carries the generation that ties this log to its base
-        // checkpoint; written lazily so warm reattaches never clobber a log
-        // that already has appended batches.
+        // Why: header ties this log to its base checkpoint; written lazily so warm reattaches don't clobber an appended log.
         await fsPromises.writeFile(writer.logPath, encodeLogHeader(writer.logGeneration ?? 0))
         writer.logBytes = LOG_HEADER_BYTES
       }
@@ -198,9 +174,7 @@ export class HistoryManager {
     }
   }
 
-  // Why: replaces the old appendData (which wrote every PTY chunk to disk).
-  // Full checkpoints are now rare (clean disconnect, pending-buffer overflow,
-  // log cap); the 5s tick appends increments via appendIncrements instead.
+  // Full checkpoints are rare (clean disconnect, pending-buffer overflow, log cap); the 5s tick appends increments instead.
   async checkpoint(sessionId: string, snapshot: TerminalSnapshot): Promise<void> {
     if (this.disabledSessions.has(sessionId)) {
       return
@@ -211,10 +185,7 @@ export class HistoryManager {
     }
 
     try {
-      // Why: shells that haven't emitted OSC-7 have snapshot.cwd = null.
-      // Persisting null would overwrite the usable cwd from meta.json,
-      // breaking cold restore cwd recovery. Fall back to the meta cwd
-      // so the revived shell inherits the original working directory.
+      // Why: snapshot.cwd is null until OSC-7; persisting null would clobber meta.json's usable cwd and break cold-restore recovery.
       let effectiveCwd = snapshot.cwd
       if (effectiveCwd === null) {
         const meta = this.readMetaFromDir(writer.dir)
@@ -237,19 +208,12 @@ export class HistoryManager {
         checkpointedAt: new Date().toISOString()
       }
       const data = JSON.stringify(checkpointFile)
-      // Why: atomic write via tmp+rename prevents half-written checkpoints
-      // on crash. Reading a corrupt checkpoint is worse than reading a
-      // slightly stale one. Async IO — a sync ~MB write (worse under
-      // antivirus scanning on Windows) would stall input/IPC for its
-      // duration. Overlap is prevented by the adapter's checkpointInFlight
-      // guard, which awaits this promise before the next tick.
+      // Why: tmp+rename is atomic (corrupt checkpoint > stale); async so a sync ~MB write can't stall IPC (worse under Windows AV).
+      // The adapter's checkpointInFlight guard serializes checkpoints, so concurrent async writes can't collide on the fixed .tmp path.
       const tmpPath = `${writer.checkpointPath}.tmp`
       await fsPromises.writeFile(tmpPath, data)
       await fsPromises.rename(tmpPath, writer.checkpointPath)
-      // Why: the snapshot subsumes every logged record, so the log resets to
-      // the new generation. Crash between rename and this reset is safe: the
-      // stale log's generation no longer matches the checkpoint's, so the
-      // restore reader ignores it.
+      // Why: snapshot subsumes logged records, so reset the log to the new generation; a stale-generation log is ignored on restore.
       await fsPromises.writeFile(writer.logPath, encodeLogHeader(generation))
       writer.logGeneration = generation
       writer.logBytes = LOG_HEADER_BYTES
@@ -258,10 +222,7 @@ export class HistoryManager {
     }
   }
 
-  // Why: a warm registerWriter may attach to a session dir that already has a
-  // log (app relaunch while the daemon kept running). Generation and size are
-  // read from disk once so appends continue the existing stream instead of
-  // clobbering it.
+  // Why: a warm registerWriter may attach to an existing log; read generation/size once so appends continue it, not clobber it.
   private resolveLogState(writer: SessionWriter): void {
     if (writer.logBytes !== null && writer.logGeneration !== null) {
       return
@@ -287,9 +248,7 @@ export class HistoryManager {
       writer.logBytes = size
       return
     }
-    // Missing or unreadable header: logBytes = 0 makes the next append rewrite
-    // the file from scratch (writeFile truncates), so a garbage file cannot be
-    // extended.
+    // Missing/unreadable header: logBytes = 0 makes the next append truncate-rewrite, so a garbage file can't be extended.
     writer.logBytes = 0
     writer.logGeneration = this.readCheckpointGeneration(writer) ?? 0
   }
@@ -310,16 +269,12 @@ export class HistoryManager {
     }
 
     this.writers.delete(sessionId)
-    // Why: the session is dead, so its disabled flag is dead state. Without this
-    // a session poisoned by a transient mid-life write error leaks its id in
-    // disabledSessions forever (sessionIds are fresh per PTY, never reused).
+    // Why: session is dead; without this a transient-error-poisoned id leaks forever (sessionIds never reused).
     this.disabledSessions.delete(sessionId)
     try {
       this.updateMeta(writer.dir, { endedAt: new Date().toISOString(), exitCode })
     } catch (err) {
-      // Why: if endedAt can't be written, the session looks like an unclean
-      // shutdown and triggers a false cold restore on next launch. Disable
-      // further writes and report, but don't crash the app.
+      // Why: an unwritten endedAt looks like an unclean shutdown → false cold restore next launch.
       this.handleWriteError(sessionId, err)
     }
   }
@@ -358,8 +313,7 @@ export class HistoryManager {
   }
 
   async dispose(): Promise<void> {
-    // Why: mark all open sessions as cleanly ended so they don't trigger
-    // false cold-restores on next launch.
+    // Why: mark open sessions cleanly ended so they don't trigger false cold-restores next launch.
     for (const [sessionId, writer] of this.writers) {
       try {
         this.updateMeta(writer.dir, { endedAt: new Date().toISOString(), exitCode: null })
@@ -370,9 +324,7 @@ export class HistoryManager {
     this.writers.clear()
   }
 
-  // Why: history is best-effort — any error should disable the session
-  // rather than crash the app. Callers use fire-and-forget `void` promises,
-  // so a re-thrown error would become an unhandled rejection.
+  // Why: history is best-effort; callers fire-and-forget so a throw would be an unhandled rejection — disable instead.
   private handleWriteError(sessionId: string, err: unknown): void {
     this.disabledSessions.add(sessionId)
     this.onWriteError?.(sessionId, err as Error)
diff --git a/src/main/daemon/pty-subprocess.ts b/src/main/daemon/pty-subprocess.ts
index 60a8af8ac70..fbb2b268df0 100644
--- a/src/main/daemon/pty-subprocess.ts
+++ b/src/main/daemon/pty-subprocess.ts
@@ -1,5 +1,4 @@
-/* eslint-disable max-lines -- Why: daemon PTY spawning centralizes platform launch setup,
-   preflight validation, and lifecycle guards that must stay in one execution path. */
+/* eslint-disable max-lines -- Why: daemon PTY spawning must keep platform launch setup, preflight, and lifecycle guards in one execution path. */
 import * as pty from 'node-pty'
 import { statSync } from 'node:fs'
 import { delimiter, win32 as pathWin32 } from 'node:path'
@@ -74,18 +73,12 @@ const PANE_IDENTITY_ENV_KEYS = [
 ] as const
 const FOREGROUND_AGENT_CACHE_TTL_MS = 1000
 const SHELL_FOREGROUND_REFRESH_RETRY_MS = 5_000
-// Why: a Windows refresh forks a powershell.exe whole-process-table CIM scan
-// (~10-40x heavier than POSIX `ps`). An idle shell with no agent identity and
-// no recent output retries far slower; output re-arms the 5s retry so an agent
-// start (which always prints) is still resolved promptly.
+// Why: a Windows refresh forks a heavy powershell.exe CIM scan (~10-40x POSIX `ps`); idle shells retry slower, output re-arms the fast retry.
 const WINDOWS_IDLE_SHELL_FOREGROUND_REFRESH_RETRY_MS = 15_000
 const SHELL_FOREGROUND_OUTPUT_HOT_WINDOW_MS = 10_000
 const STARTUP_AGENT_FOREGROUND_BOOTSTRAP_MS = 5_000
 const PTY_SPAWN_HEALTH_TIMEOUT_MS = 4_000
-// Why: a busy machine right after an upgrade can make one short-lived shell
-// spawn slow. Retry once before declaring the daemon unable to spawn PTYs, so
-// a transient stall does not silently route every fresh terminal to the local
-// fallback (losing daemon persistence) until a manual restart.
+// Why: retry once so a transient slow spawn doesn't route every terminal to the local fallback, losing daemon persistence.
 const PTY_SPAWN_HEALTH_RETRY_ATTEMPTS = 2
 const PENDING_PRE_LISTENER_DATA_MAX_CHARS = 512 * 1024
 
@@ -99,9 +92,7 @@ function composeGuardedDaemonGitConfigEnv(
   if (policy !== 'guard' && launchAgent === undefined) {
     return
   }
-  // Why: the daemon can outlive Electron, so only its process.env is the
-  // authoritative inherited config. The raw env merge already gives an
-  // explicit wire protocol normal override semantics; append only the guard.
+  // Why: the daemon can outlive Electron, so its process.env is the authoritative inherited config; append only the guard.
   Object.assign(env, gitCredentialPromptGuardEnv(env, process.platform))
 }
 
@@ -170,9 +161,7 @@ function removeInheritedDevAgentHookEndpoint(
   explicitEnv: Record<string, string> | undefined
 ): void {
   if (explicitEnv?.ORCA_AGENT_HOOK_ENV === 'development' && !explicitEnv.ORCA_AGENT_HOOK_ENDPOINT) {
-    // Why: the daemon inherits the app process env before per-PTY env is
-    // merged. Strip only stale parent endpoints; a fresh explicit endpoint is
-    // needed by hooks whose runners scrub token-like env vars before exec.
+    // Why: strip only stale inherited endpoints; a fresh explicit one is needed by hooks that scrub token-like env vars before exec.
     delete env.ORCA_AGENT_HOOK_ENDPOINT
   }
 }
@@ -181,8 +170,7 @@ function removeInheritedDevAgentHookEndpoint(
  * Strips Electron's internal run-as-node flag from user shell environments.
  */
 function removeInheritedElectronRunAsNode(env: Record<string, string>): void {
-  // Why: the daemon needs ELECTRON_RUN_AS_NODE=1 internally, but user shells
-  // must not inherit it or nested Electron commands run as plain Node.
+  // Why: user shells must not inherit ELECTRON_RUN_AS_NODE or nested Electron commands run as plain Node.
   delete env.ELECTRON_RUN_AS_NODE
 }
 
@@ -251,9 +239,7 @@ function preflightDaemonCwd(): void {
     // Recover below; process.cwd() throws after the original cwd is deleted.
   }
 
-  // Why: older detached daemons were launched from the repo cwd. If that
-  // worktree disappears, node-pty's macOS spawn-helper can fail even when the
-  // requested terminal cwd is valid.
+  // Why: if the daemon's launch worktree disappears, node-pty's macOS spawn-helper fails even when the terminal cwd is valid.
   if (repairDaemonCwd()) {
     return
   }
@@ -296,8 +282,7 @@ function preflightUnixPtySpawnEnvironment(): void {
     return
   }
 
-  // Why: detached daemons can outlive their launch cwd; repair before every
-  // PTY spawn so Linux/macOS do not wait for startup health recovery.
+  // Why: detached daemons can outlive their launch cwd; repair before every spawn so Linux/macOS don't wait for health recovery.
   preflightDaemonCwd()
   preflightMacNodePtySpawnEnvironment()
 }
@@ -404,8 +389,7 @@ function runSinglePtySpawnHealthProbe(): Promise<void> {
       })
     }, PTY_SPAWN_HEALTH_TIMEOUT_MS)
 
-    // Why: ping only proves the daemon protocol is alive. A real short-lived
-    // PTY spawn catches stale node-pty helper paths captured by this process.
+    // Why: ping only proves the protocol is alive; a real spawn catches stale node-pty helper paths.
     exitDisposable = proc.onExit(({ exitCode }) => {
       if (exitCode === 0) {
         finish()
@@ -426,9 +410,7 @@ export async function checkPtySpawnHealth(): Promise<void> {
     return
   }
 
-  // Why: Linux/macOS daemons can outlive an app update with a deleted cwd or
-  // stale native PTY path. A real short-lived spawn catches that before the
-  // main process routes fresh panes to a daemon that cannot create terminals.
+  // Why: a real short-lived spawn catches a deleted cwd or stale native PTY path before panes are routed to a daemon that can't spawn.
   if (process.platform === 'darwin') {
     ensureNodePtySpawnHelperExecutable()
   }
@@ -474,8 +456,7 @@ function resolveFallbackForegroundProcess(
   if (normalized || process.platform !== 'win32') {
     return normalized
   }
-  // Why: Windows node-pty can report the terminal name instead of the shell.
-  // Use the spawned shell so shell-rooted foreground enrichment still runs.
+  // Why: Windows node-pty can report the terminal name instead of the shell; fall back to the spawned shell.
   return normalizeForegroundProcessName(pathWin32.basename(shellPath))
 }
 
@@ -483,10 +464,7 @@ function resolveFallbackForegroundProcess(
  * Spawns the daemon PTY, walking the Windows PowerShell -> cmd.exe fallback
  * chain when ConPTY rejects the primary shell with ERROR_ACCESS_DENIED.
  *
- * Why: the daemon spawns node-pty directly (no LocalPtyProvider), so it needs
- * its own chain walk. The first attempt must match the already-resolved
- * shellPath/shellArgs/spawnCwd; later attempts carry their own recomputed args
- * so the cmd.exe fallback still gets `chcp 65001`.
+ * Why: the daemon has no LocalPtyProvider, so it owns its chain walk; later attempts recompute args so the cmd.exe fallback still gets `chcp 65001`.
  */
 function spawnDaemonPtyWithWindowsFallback(args: {
   shellPath: string
@@ -510,8 +488,7 @@ function spawnDaemonPtyWithWindowsFallback(args: {
       rows: args.rows,
       cwd,
       env: args.env,
-      // Why: bundled ConPTY has the modern wrap-marker behavior xterm expects;
-      // legacy system ConPTY can corrupt full-width TUI rows in scrollback.
+      // Why: legacy system ConPTY can corrupt full-width TUI rows in scrollback; bundled ConPTY has the wrap-marker behavior xterm expects.
       ...(process.platform === 'win32' ? { useConptyDll: true } : {})
     })
   }
@@ -561,17 +538,9 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
     TERM: 'xterm-256color',
     COLORTERM: 'truecolor',
     TERM_PROGRAM: 'Orca',
-    // Why: TUIs feature-gate on TERM_PROGRAM_VERSION. The daemon is forked
-    // by main (daemon-init.ts:93) with the parent's env, so ORCA_APP_VERSION
-    // — set in src/main/index.ts from app.getVersion() — is inherited here.
+    // Why: TUIs feature-gate on TERM_PROGRAM_VERSION; ORCA_APP_VERSION is inherited from the forking main process.
     TERM_PROGRAM_VERSION: process.env.ORCA_APP_VERSION ?? '0.0.0-dev',
-    // Why: opt tools (Claude Code, ls --hyperlink, etc.) into emitting OSC 8
-    // hyperlinks. The `supports-hyperlinks` npm package gates on a hard-coded
-    // TERM_PROGRAM allowlist (iTerm.app / WezTerm / vscode) and returns false
-    // for TERM_PROGRAM=Orca, so callers drop OSC 8 output entirely and emit
-    // bare text instead. xterm.js in Orca parses OSC 8 and the pane's
-    // linkHandler routes clicks, so forcing the advertisement is safe and
-    // restores clickable refs like `owner/repo#123` / `PR#123`.
+    // Why: `supports-hyperlinks` gates OSC 8 on a TERM_PROGRAM allowlist excluding Orca; force it since xterm.js parses OSC 8 for clickable links.
     FORCE_HYPERLINK: '1'
   } as Record<string, string>
   composeGuardedDaemonGitConfigEnv(env, opts.env, opts.launchAgent)
@@ -581,8 +550,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
   if (opts.env?.TERM) {
     env.TERM = opts.env.TERM
   }
-  // Why: the daemon is forked from Electron and can inherit the pane identity
-  // of the terminal that launched `pn dev`; each PTY must opt into its own.
+  // Why: the daemon can inherit the pane identity of the terminal that launched `pn dev`; each PTY must opt into its own.
   removeUnspecifiedPaneIdentityEnv(env, opts.env)
   removeInheritedDevAgentHookEndpoint(env, opts.env)
   removeInheritedElectronRunAsNode(env)
@@ -591,14 +559,9 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
 
   env.LANG ??= 'en_US.UTF-8'
 
-  // Why: the shellOverride from the "+" menu (or persisted default shell
-  // setting, relayed by main) takes priority over env.COMSPEC — otherwise
-  // Windows always resolves to cmd.exe (COMSPEC) or PowerShell by fallback,
-  // no matter which shell the user actually picked.
+  // Why: shellOverride must win over env.COMSPEC, or Windows always resolves to cmd.exe/PowerShell regardless of the user's pick.
   const resolvedWslContext = resolveWslSessionContext(opts)
-  // Why: WSL worktree cwd is the repo's execution environment. Older persisted
-  // tabs can carry a PowerShell/cmd shellOverride; ignore it so reconnects and
-  // daemon-backed terminals enter the WSL distro just like LocalPtyProvider.
+  // Why: older persisted tabs can carry a PowerShell/cmd shellOverride; ignore it so WSL reconnects still enter the distro.
   let shellPath = resolvedWslContext ? 'wsl.exe' : opts.shellOverride || resolvePtyShellPath(env)
   let shellArgs: string[]
   let startupCommandDeliveredInShellArgs = false
@@ -615,11 +578,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
   if (process.platform === 'win32') {
     const normalizedShellFamily = pathWin32.basename(shellPath).toLowerCase()
     const resolvedGitBashPath = resolveWindowsGitBashShellPath(shellPath)
-    // Why: daemon spawn requests can carry either a canonical shell family
-    // (`powershell.exe`) or a concrete PowerShell executable path from a
-    // one-off override. Normalize both forms back to the PowerShell family so
-    // the shared resolver can still fall back to inbox powershell.exe when
-    // pwsh.exe was requested but is unavailable.
+    // Why: normalize concrete PowerShell paths to the family so the resolver can fall back to powershell.exe when pwsh.exe is unavailable.
     const resolvedShellFamily: WindowsPowerShellShellFamily =
       normalizedShellFamily === 'powershell.exe' || normalizedShellFamily === 'pwsh.exe'
         ? normalizedShellFamily
@@ -646,11 +605,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
           }) ?? shellPath)
         : shellPath
     }
-    // Why: when the selected shell is a PowerShell family, resolve it to a real
-    // absolute executable and build a PowerShell -> cmd.exe fallback chain. A
-    // bare `pwsh.exe` lets ConPTY resolve the Store App Execution Alias stub,
-    // whose CreateProcessW launch fails with ERROR_ACCESS_DENIED (error code 5).
-    // Mirrors LocalPtyProvider so daemon-backed terminals keep arg parity.
+    // Why: a bare `pwsh.exe` resolves to the Store App Execution Alias stub whose launch fails with ERROR_ACCESS_DENIED (5).
     windowsFallbackAttempts = buildWindowsPowerShellSpawnAttempts({
       shellPath,
       cwd: spawnCwd,
@@ -679,8 +634,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
       startupCommandDeliveredInShellArgs = resolved.startupCommandDeliveredInShellArgs === true
     }
     if (isWindowsGitBashShellPath(shellPath)) {
-      // Why: Git for Windows login startup files otherwise cd to $HOME,
-      // ignoring node-pty's cwd for repo-scoped terminals.
+      // Why: Git for Windows login startup files otherwise cd to $HOME, ignoring node-pty's cwd.
       env.CHERE_INVOKING ??= '1'
     }
     const codexHomeWslInfo = env.CODEX_HOME ? parseWslPath(env.CODEX_HOME) : null
@@ -713,27 +667,22 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
           }
         }
       } else if (isHostCodexHomeForWsl(env.CODEX_HOME)) {
-        // Why: Orca's selected Codex runtime home is host-local. WSL Codex
-        // must use its Linux-side ~/.codex instead of a Windows path.
+        // Why: host-local Codex home is unusable in WSL; let WSL Codex use its Linux-side ~/.codex.
         delete env.CODEX_HOME
         delete env.ORCA_CODEX_HOME
       } else if (env.CODEX_HOME) {
         addWslEnvKeys(env, ['CODEX_HOME', 'ORCA_CODEX_HOME'])
       }
       if (env.CLAUDE_CONFIG_DIR) {
-        // Why: managed WSL Claude accounts pass a Linux CLAUDE_CONFIG_DIR
-        // through Windows wsl.exe; non-default env vars need WSLENV import.
+        // Why: non-default env vars need WSLENV import to cross Windows wsl.exe into the Linux side.
         addWslEnvKeys(env, ['CLAUDE_CONFIG_DIR'])
       }
       if (env[ORCA_HERMES_STARTUP_QUERY_ENV] !== undefined) {
-        // Why: the startup wrapper expands this only inside WSL; wsl.exe
-        // otherwise drops custom Windows environment variables.
+        // Why: wsl.exe drops custom Windows env vars unless named in WSLENV.
         addWslEnvKeys(env, [ORCA_HERMES_STARTUP_QUERY_ENV])
       }
     } else if (codexHomeWslInfo || isWslCodexHomeForHost(env.CODEX_HOME)) {
-      // Why: WSL-managed Codex homes are Linux paths. Windows Codex cannot use
-      // them. ORCA_CODEX_HOME must go too because shell-ready scripts restore
-      // CODEX_HOME from it after user profiles run.
+      // Why: WSL Codex homes are Linux paths; also drop ORCA_CODEX_HOME since shell-ready restores CODEX_HOME from it.
       delete env.CODEX_HOME
       delete env.ORCA_CODEX_HOME
     }
@@ -741,17 +690,14 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
       addOrcaWslInteropEnv(env)
     }
   } else {
-    // Why: relay-side launch modes can ask for host defaults to stay scrubbed
-    // even after environment normalization above.
+    // Why: relay-side launch modes can ask for host defaults to stay scrubbed even after normalization above.
     for (const key of opts.envToDelete ?? []) {
       delete env[key]
     }
     if (opts.env?.TERM) {
       env.TERM = opts.env.TERM
     }
-    // Why after the scrub: SHELL must reflect the shell that actually spawns,
-    // matching LocalPtyProvider; and before the launch-config derivation below
-    // so shell-ready wrappers target the resolved shell, not a missing one.
+    // Why: set SHELL after the scrub and before launch-config derivation so shell-ready wrappers target the resolved shell.
     const preferredShellPath = shellPath
     shellPath = resolveUnixShellPath(shellPath)
     if (shellPath !== preferredShellPath) {
@@ -760,16 +706,14 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
         `[daemon/pty] Preferred shell "${preferredShellPath}" is unavailable, fell back to "${shellPath}"`
       )
     }
-    // Why: OpenCode/Codex path restoration and OMP's typed-command status
-    // wrapper need shell-ready code after user startup files run.
+    // Why: OpenCode/Codex path restoration and OMP's typed-command status wrapper need shell-ready code after user startup files run.
     let shellLaunch: ReturnType<typeof getShellReadyLaunchConfig> | null = null
     if (opts.command && isCodexStartupCommand) {
       const shouldWaitForShellReady = shouldUseShellReadyStartupDelivery({
         command: opts.command,
         startupCommandDelivery: opts.startupCommandDelivery
       })
-      // Why: payload-bearing Codex startup text can be dropped by rc-file noise;
-      // plain Codex stays markerless to preserve the startup-speed path.
+      // Why: payload-bearing Codex startup text can be dropped by rc-file noise; plain Codex stays markerless for the startup-speed path.
       shellLaunch = shouldWaitForShellReady
         ? getShellReadyLaunchConfig(shellPath)
         : getAttributionShellLaunchConfig(shellPath)
@@ -801,9 +745,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
   }
   promoteAgentTeamsShimPath(env, opts.env?.PATH)
 
-  // Why: asar packaging can strip the +x bit from node-pty's spawn-helper
-  // binary. The main process fixes this via LocalPtyProvider, but the daemon
-  // runs in a separate forked process with its own code path.
+  // Why: asar packaging can strip +x from node-pty's spawn-helper; the daemon is a separate forked process from the main-process fix.
   ensureNodePtySpawnHelperExecutable()
   preflightUnixPtySpawnEnvironment()
   preflightPosixPtySpawnEnvironment(validationCwd)
@@ -824,8 +766,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
       windowsFallbackAttempts
     })
     proc = spawned.process
-    // Why: a Windows fallback (e.g. cmd.exe) carries its own argv-embedded
-    // startup command, so adopt the winning shell's identity + delivery flag.
+    // Why: a Windows fallback (e.g. cmd.exe) carries its own argv-embedded startup command; adopt the winning shell's identity + delivery flag.
     shellPath = spawned.shellPath
     spawnCwd = spawned.spawnCwd
     if (spawned.startupCommandDeliveredInShellArgs !== undefined) {
@@ -845,8 +786,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
   let pendingPreListenerExitCode: number | null = null
 
   const bufferPreListenerData = (data: string): void => {
-    // Why: Windows shell-arg startup commands can print before Session wires
-    // this subprocess into the daemon. Preserve that spawn-time race window.
+    // Why: Windows shell-arg startup commands can print before Session wires this subprocess in; preserve that spawn-time race window.
     pendingPreListenerData.push(data)
     pendingPreListenerDataChars += data.length
     while (pendingPreListenerDataChars > PENDING_PRE_LISTENER_DATA_MAX_CHARS) {
@@ -891,11 +831,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
     }
   })
 
-  // Why: node-pty's native NAPI layer throws a C++ Napi::Error when
-  // write/resize/kill is called on a PTY whose underlying fd is already
-  // closed. This happens in the race window between the child process
-  // exiting and the JS onExit callback firing. An uncaught Napi::Error
-  // propagates to std::terminate, killing the entire daemon process.
+  // Why: node-pty throws Napi::Error if write/resize/kill hit a closed fd (child-exit vs onExit race); uncaught it std::terminates the daemon.
   let dead = false
   let disposed = false
   let nodePtyKillIssued = false
@@ -931,8 +867,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
     fallbackProcess !== null &&
     (isShellProcess(fallbackProcess) ||
       isAgentForegroundWrapperProcess(fallbackProcess) ||
-      // Why: agent-spawned helper processes can become the PTY foreground
-      // child; the Unix process tree can still identify the parent agent.
+      // Why: agent-spawned helpers can become the PTY foreground child, but the Unix process tree still identifies the parent agent.
       process.platform !== 'win32')
   const scheduleAgentForegroundRefresh = (fallbackProcess: string | null): void => {
     if (dead || !proc.pid) {
@@ -949,9 +884,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
     const now = Date.now()
     const idleNoEvidenceShell =
       fallbackIsShell && !getActiveStartupAgentForeground(now) && !cachedAgentForeground
-    // Why: on Windows each refresh is a whole-table CIM scan; only shells with
-    // no agent evidence and no recent output relax, so agent-identity refresh
-    // (cached identity → 1s TTL) and post-output starts keep the fast retry.
+    // Why: on Windows each refresh is a whole-table CIM scan, so only shells with no agent evidence and no recent output relax the retry.
     const retryMs = !idleNoEvidenceShell
       ? FOREGROUND_AGENT_CACHE_TTL_MS
       : process.platform === 'win32' && now - lastOutputAt > SHELL_FOREGROUND_OUTPUT_HOT_WINDOW_MS
@@ -962,11 +895,8 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
     }
     foregroundRefreshInFlight = true
     lastForegroundRefreshStartedAt = now
-    // Why: daemon foreground reads are sync and run on the IPC hot path.
-    // Refresh derived identities (shell/wrapper/helper -> codex/claude/etc.)
-    // in the background and serve them from a short cache on later reads.
-    // Why: Windows may need an async membership check before this shared
-    // shell/wrapper retirement policy is safe to apply.
+    // Why: daemon foreground reads are sync on the IPC hot path; refresh derived identities in the background and serve from a short cache.
+    // Why: Windows may need an async membership check before this shell/wrapper retirement policy is safe.
     const retireStaleForegroundIdentity = (): void => {
       const currentFallbackProcess = getFallbackForegroundProcess()
       if (
@@ -983,9 +913,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
         currentFallbackProcess !== null &&
         isAgentForegroundWrapperProcess(currentFallbackProcess)
       ) {
-        // Why: the wrapper's tree no longer resolves to an agent — an expired
-        // identity must not transfer to an unrelated wrapper (e.g. npm right
-        // after an agent exit). Fresh identities survive one-off scan hiccups.
+        // Why: an expired wrapper identity must not transfer to an unrelated wrapper (e.g. npm after an agent exit); fresh ones survive scan hiccups.
         cachedAgentForeground = null
       }
     }
@@ -996,14 +924,12 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
         if (dead) {
           return
         }
-        // Why: a degraded scan is not exit evidence; retiring here fires false
-        // completion while an agent is still working under CIM load.
+        // Why: a degraded scan isn't exit evidence — retiring would fire false completion while the agent works under CIM load.
         if (!available) {
           return
         }
         if (!processName || !recognizeAgentProcess(processName)) {
-          // Why: a Windows snapshot can omit a live agent; only verified
-          // shell-only membership may retire its cached identity.
+          // Why: a Windows snapshot can omit a live agent; only verified shell-only membership may retire cached identity.
           if (process.platform === 'win32' && fallbackIsShell && cachedAgentForeground !== null) {
             return readWindowsConptyProcessIds(proc.pid).then((consoleProcessIds) => {
               if (dead || consoleProcessIds === null || consoleProcessIds.size > 1) {
@@ -1030,15 +956,8 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
     dead = true
     cachedAgentForeground = null
     startupAgentForeground = null
-    // Why: UnixTerminal.destroy() registers `_socket.once('close', () => this.kill('SIGHUP'))`
-    // (unixTerminal.js:219-229). After the child exits, the master socket's
-    // 'close' event can fire before our dispose() path gets to neutralize
-    // proc.kill — the child's pid may have already been recycled, so SIGHUP
-    // lands on an unrelated process. Neutralizing here, synchronously inside
-    // the onExit callback, closes that window: once the child is reaped,
-    // proc.kill is a no-op no matter which teardown ordering wins.
-    // Windows is excluded because WindowsTerminal.destroy relies on kill() to
-    // close the ConPTY agent — neutralizing would leak the agent + fds.
+    // Why: neutralize proc.kill synchronously in onExit so UnixTerminal's async socket-close SIGHUP can't land on a recycled pid.
+    // Windows excluded: WindowsTerminal.destroy needs kill() to close the ConPTY agent.
     if (process.platform !== 'win32') {
       ;(proc as unknown as { kill: (sig?: string) => void }).kill = () => {}
     }
@@ -1049,10 +968,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
     shellPath,
     ...(startupCommandDeliveredInShellArgs ? { startupCommandDeliveredInShellArgs: true } : {}),
     getForegroundProcess: () => {
-      // Why: node-pty's `.process` getter reports the PTY's live foreground
-      // process name (the agent running in the shell, or the shell itself) and
-      // updates as it changes. Null once the child is gone — `.process` on a
-      // reaped pty can read a recycled pid.
+      // Why: node-pty's `.process` reports the live foreground name but reads a recycled pid on a reaped pty, so bail when dead.
       if (dead) {
         return null
       }
@@ -1071,14 +987,8 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
         ) {
           return cachedAgentForeground.processName
         }
-        // Why: a wrapper foreground (node/python) can never identify itself, and
-        // readers poll slower than the cache TTL — returning the raw fallback here
-        // would hide the resolved identity forever. Serve the last resolved agent
-        // while the scheduled refresh revalidates. On Windows a shell fallback is
-        // also an unreliable exit signal (ConPTY lag under load surfaces the shell
-        // while the agent is alive), so trust the cache there too; the background
-        // refresh retires the identity only after a console-presence read confirms
-        // the agent left the console.
+        // Why: a wrapper (node/python) can't self-identify and readers poll slower than the cache TTL, so serve the last resolved agent.
+        // On Windows a shell fallback is an unreliable exit signal under ConPTY lag; trust the cache until a console-presence read confirms exit.
         if (
           cachedAgentForeground &&
           fallbackProcess !== null &&
@@ -1109,8 +1019,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
         ) {
           return fallbackProcess
         }
-        // Why: cached/in-flight scans may predate the OSC command boundary.
-        // Confirmation requires one shared process snapshot started afterward.
+        // Why: cached/in-flight scans may predate the OSC command boundary; confirmation needs a snapshot started afterward.
         const resolution = await resolveAgentForegroundProcessWithAvailability(
           proc.pid,
           fallbackProcess,
@@ -1137,8 +1046,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
           startupAgentForeground = null
           return recognized.processName
         }
-        // Why: a successful post-boundary scan that resolves no agent is the
-        // authority that retires stale cached/startup identity.
+        // Why: a post-boundary scan resolving no agent is the authority that retires stale cached/startup identity.
         cachedAgentForeground = null
         startupAgentForeground = null
         return resolution.processName
@@ -1169,10 +1077,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
         dead = true
       }
     },
-    // Why pause/resume work on Windows too: node-pty's base Terminal
-    // implements both as socket pause/resume (lib/terminal.js), and
-    // WindowsTerminal wires _socket to the ConPTY conout pipe — pausing stops
-    // conout reads so ConPTY's bounded buffer backpressures the child.
+    // Why pause/resume work on Windows too: WindowsTerminal wires _socket to the ConPTY conout pipe, so pausing backpressures the child.
     pause: () => {
       if (dead) {
         return
@@ -1211,19 +1116,14 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
       try {
         proc.kill()
       } catch (error) {
-        // Why: a rejected native kill is not proof of exit. Keep the wrapper
-        // live and let Session retain/retry the physical owner.
+        // Why: a rejected native kill isn't proof of exit — keep the wrapper live so Session can retry the owner.
         nodePtyKillIssued = false
         throw error
       }
     },
     forceKill: () => {
-      // Why: once the child has been reaped (dead=true via onExit) or dispose
-      // has run, proc.pid refers to a recycled pid. Sending SIGKILL would
-      // terminate an unrelated process. The fd release is handled by
-      // dispose()/destroy(); forceKill is strictly for signalling a live child.
-      // Why: Windows node-pty kill already closes ConPTY; retrying it through
-      // forceKill can double-close the native handle during workspace teardown.
+      // Why: after reap/dispose proc.pid is a recycled pid, so SIGKILL would hit an unrelated process (forceKill only signals a live child).
+      // Why: Windows node-pty kill already closed ConPTY; forcing again can double-close the native handle.
       if (dead || (process.platform === 'win32' && nodePtyKillIssued)) {
         return
       }
@@ -1243,8 +1143,7 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
       }
     },
     signal: (sig) => {
-      // Why: same recycled-pid hazard as forceKill. Once dead, silently drop
-      // the signal rather than risk sending it to an unrelated process.
+      // Why: same recycled-pid hazard as forceKill — once dead, dropping avoids signalling an unrelated process.
       if (dead) {
         return
       }
@@ -1278,24 +1177,12 @@ export function createPtySubprocess(opts: PtySubprocessOptions): SubprocessHandl
       pendingPreListenerData = []
       pendingPreListenerDataChars = 0
       pendingPreListenerExitCode = null
-      // Why: UnixTerminal.destroy() registers `_socket.once('close', () => this.kill('SIGHUP'))`
-      // (unixTerminal.js:219-229). The socket close fires asynchronously; by then
-      // the child may have exited and its pid been recycled to an unrelated
-      // process. Without this neutralization, SIGHUP can be delivered to a
-      // Chrome tab, editor, or other user process — silent cross-app corruption.
-      // `_socket.destroy()` still releases the fd; only the dangerous SIGHUP is
-      // removed.
-      //
-      // Platform guard: WindowsTerminal.destroy implements the ConPTY close by
-      // CALLING `this.kill()` via `_deferNoArgs` (windowsTerminal.js:141-146).
-      // Neutralizing kill on Windows turns destroy() into a no-op and leaks the
-      // ConPTY agent. The SIGHUP hazard is POSIX-only, so the guard is too.
+      // Why: UnixTerminal.destroy()'s async socket-close SIGHUP can land on a recycled pid, hitting an unrelated user process; neutralize kill on POSIX.
+      // Windows destroy() uses kill() to close the ConPTY agent, so the guard is POSIX-only.
       if (process.platform !== 'win32') {
         ;(proc as unknown as { kill: (sig?: string) => void }).kill = () => {}
       } else if (nodePtyKillIssued) {
-        // Why: WindowsTerminal.destroy() calls kill() internally. If this
-        // daemon handle already used node-pty's kill(), destroying here can
-        // close the same ConPTY handle twice and trip Windows heap corruption.
+        // Why: WindowsTerminal.destroy() calls kill(); destroying after node-pty's kill() double-closes the ConPTY handle (heap corruption).
         return
       }
       try {
diff --git a/src/main/daemon/session.ts b/src/main/daemon/session.ts
index 1c414046cb3..c88061403a4 100644
--- a/src/main/daemon/session.ts
+++ b/src/main/daemon/session.ts
@@ -26,26 +26,17 @@ import type {
 } from './types'
 
 const SHELL_READY_TIMEOUT_MS = 15_000
-// Why: Codex startup skips marker-gated command delivery; this only bounds
-// older daemon/local paths that still report shell-ready support for Codex.
+// Why: Codex skips marker-gated command delivery; this only bounds older daemon/local paths that still report shell-ready for Codex.
 export const CODEX_SHELL_READY_TIMEOUT_MS = 300
 const KILL_TIMEOUT_MS = 5_000
 export const IMMEDIATE_KILL_PHYSICAL_EXIT_TIMEOUT_MS = 8_000
 export const SESSION_FORCE_KILL_RETRY_MS = 250
 const SESSION_FORCE_KILL_MAX_ATTEMPTS = 2
-// Why: pending records exist so the 5s checkpoint can persist increments
-// instead of re-serializing the whole buffer. If no client drains them (main
-// process gone, history disabled), memory must stay bounded — past the cap we
-// drop the records and flag overflow so the next take falls back to one full
-// snapshot, which subsumes everything dropped.
-// Counted in UTF-16 code units (string .length), which tracks JS heap cost.
-// Worst-case wire size for a full take is ~6x this (each control char
-// JSON-escapes to six bytes) and must stay under NDJSON_MAX_LINE_BYTES (16MB).
+// Why: bounds in-memory pending output when no client drains it; past the cap we drop records and flag
+// overflow so the next take falls back to one full snapshot. UTF-16 units; worst-case wire is ~6x, under NDJSON_MAX_LINE_BYTES (16MB).
 const PENDING_OUTPUT_MAX_BYTES = 2 * 1024 * 1024
-// Why: producer pause is requested over a fire-and-forget notification, so the
-// matching resume can be lost (main crash, dropped socket). A lost resume must
-// never wedge a shell: auto-resume after this window; a still-flooded main
-// re-asserts the pause on its next watermark check.
+// Why: pause is a fire-and-forget notify, so a resume can be lost (main crash, dropped socket); a lost
+// resume must never wedge a shell, so auto-resume after this window — a still-flooded main re-pauses.
 export const PRODUCER_PAUSE_FAILSAFE_MS = 5_000
 
 export type SubprocessHandle = {
@@ -55,32 +46,26 @@ export type SubprocessHandle = {
   getForegroundProcess(): string | null
   /** Await process-table evidence captured after this confirmation request. */
   confirmForegroundProcess?(): Promise<string | null>
-  /** True when shell launch args already delivered the startup command, so the
-   *  terminal host must skip its stdin fallback write. */
+  /** True when shell launch args already delivered the startup command, so the host skips its stdin fallback write. */
   startupCommandDeliveredInShellArgs?: boolean
-  /** Shell the subprocess actually spawned, after Unix/Windows fallbacks. The
-   *  host reconciles the caller's shell-ready assumption against it so a
-   *  fallback shell without a ready marker never gates startup commands. */
+  /** Shell the subprocess actually spawned, after fallbacks. The host reconciles the caller's shell-ready
+   *  assumption against it so a fallback shell without a ready marker never gates startup commands. */
   shellPath?: string
   write(data: string): void
   resize(cols: number, rows: number): void
-  /** Stop reading the PTY fd (node-pty pause()) so the kernel/ConPTY buffer
-   *  fills and a flooding child blocks on write. Optional: handles that
-   *  cannot pause simply omit it and flow control degrades to a no-op. */
+  /** Stop reading the PTY fd (node-pty pause()) so a flooding child blocks on write. Optional:
+   *  handles that cannot pause omit it and flow control degrades to a no-op. */
   pause?(): void
   resume?(): void
-  /** Resync the native PTY's own screen state after a frontend clear.
-   *  No-op except on Windows/ConPTY, where a stale ConPTY cursor row makes
-   *  the next prompt repaint land below a blank gap. */
+  /** Resync the native PTY's screen state after a frontend clear. No-op except on Windows/ConPTY,
+   *  where a stale cursor row makes the next prompt repaint below a blank gap. */
   clear?(): void
   kill(): void
   forceKill(): void
   signal(sig: string): void
   onData(cb: (data: string) => void): void
   onExit(cb: (code: number) => void): void
-  /** Release the native PTY handle via node-pty's own destroy() path.
-   *  Idempotent. Safe to call after exit. Called by Session on every teardown
-   *  path (natural exit, kill, force-kill, native throw, session dispose). */
+  /** Release the native PTY handle via node-pty's destroy(). Idempotent; safe to call after exit. */
   dispose(): void
 }
 
@@ -96,11 +81,8 @@ export type SessionOptions = {
   historySeed?: string
   scrollback?: number
   wslDistro?: string
-  // Why: fired once the session reaches a terminal state (natural exit or
-  // kill-timeout force-dispose) so the owner (TerminalHost) can reap it —
-  // dispose the headless emulator and drop it from its session map. Without a
-  // reaper, dead sessions (and their ~5000-row scrollback emulators) accumulate
-  // for the lifetime of the long-lived daemon process.
+  // Fired once the session reaches a terminal state so the owner (TerminalHost) can reap it; without
+  // a reaper, dead sessions and their scrollback emulators accumulate for the daemon's lifetime.
   onExit?: (code: number) => void
   startupIngress?: PtyStartupIngressIntent
 }
@@ -156,13 +138,10 @@ export class Session {
       rows: size.rows,
       scrollback: opts.scrollback,
       wslDistro: opts.wslDistro
-      // No onData wiring: the daemon-side emulator must never reply to
-      // terminal query sequences. The renderer's xterm is the authoritative
-      // responder; any daemon reply races ahead via in-process parsing and
-      // clobbers the renderer's answer. See the comment in HeadlessEmulator.
+      // No onData: the daemon emulator must never reply to query sequences — the renderer's xterm is
+      // the authoritative responder and a daemon reply would race ahead and clobber it. See HeadlessEmulator.
     })
-    // Why: recovery must precede listener registration; shells can emit their
-    // prompt synchronously as soon as onData subscribes.
+    // Why: seed recovery must precede listener registration; shells can emit their prompt synchronously once onData subscribes.
     this._historySeeded =
       opts.historySeed === undefined ? undefined : this.emulator.writeSync(opts.historySeed)
 
@@ -217,8 +196,7 @@ export class Session {
       return false
     }
     this._isTerminating = true
-    // Why: a paused child can be blocked inside write(); resume before any
-    // async snapshot so it can handle termination promptly.
+    // Why: a paused child can be blocked inside write(); resume before any async snapshot so it handles termination promptly.
     this.releaseProducerPause({ resume: true })
     return true
   }
@@ -232,10 +210,8 @@ export class Session {
       return
     }
 
-    // Why: during the post-ready flush gate window (shellState is already
-    // 'ready' but the queue hasn't flushed yet) we must keep queuing. Writing
-    // directly would let fresh input race ahead of the buffered startup
-    // command, changing execution order.
+    // Why: keep queuing during the post-ready flush-gate window ('ready' but not yet flushed); a
+    // direct write would race fresh input ahead of the buffered startup command.
     if (this._shellState === 'pending' || this.postReadyFlushGate.isPending) {
       this.preReadyStdinQueue.push(data)
       return
@@ -252,15 +228,13 @@ export class Session {
       return
     }
     this.emulator.resize(cols, rows)
-    // Why: the record stream must mirror the order operations were applied to
-    // the emulator, or cold-restore replay reflows at the wrong point.
+    // Why: the record stream must mirror the emulator's apply order, or cold-restore replay reflows at the wrong point.
     this.recordPendingOutput({ kind: 'resize', cols, rows })
     this.subprocess.resize(cols, rows)
   }
 
-  /** Producer-side flow control: stop reading the PTY fd so the flooding
-   *  child blocks on write (kernel backpressure). Arms the lost-resume
-   *  failsafe; re-pausing re-arms it (main re-asserts during long floods). */
+  /** Producer-side flow control: stop reading the PTY fd so a flooding child blocks on write.
+   *  Arms the lost-resume failsafe; re-pausing re-arms it. */
   pauseProducer(): void {
     if (this._state === 'exited' || this._disposed) {
       return
@@ -302,10 +276,7 @@ export class Session {
     if (!this.launchAgent) {
       this.signalTerminationRoot()
     } else {
-      // Why: agent tool children live in detached process groups a dying
-      // shell's SIGHUP never reaches. The bounded snapshot briefly defers the
-      // signal; the kill timer below starts now, so force-dispose timing is
-      // unaffected.
+      // Why: agent tool children live in detached process groups a dying shell's SIGHUP never reaches, so sweep them.
       void Promise.resolve(
         killWithDescendantSweep(
           this.subprocess.pid,
@@ -313,8 +284,7 @@ export class Session {
             this.signalTerminationRoot()
           },
           {
-            // Why: if the root exits during ps, its numeric PID can be recycled.
-            // Never apply that stale snapshot to a different process tree.
+            // Why: if the root exits during ps its PID can be recycled; never apply that stale snapshot to a different process tree.
             ownsRoot: () => this.isAlive
           }
         )
@@ -336,15 +306,13 @@ export class Session {
     try {
       this.subprocess.kill()
     } catch (error) {
-      // Why: rejected signalling is not termination. Reopen the session so a
-      // later graceful or destructive retry can still target the live child.
+      // Why: a rejected signal is not termination; reopen the session so a later retry can still target the live child.
       this.resetTerminationAfterSignalFailure()
       throw error
     }
   }
 
-  /** Starts the existing graceful-kill deadline when a coordinator owns the
-   * snapshot-first portion of teardown. */
+  /** Starts the graceful-kill deadline when a coordinator owns the snapshot-first portion of teardown. */
   scheduleForceDisposeFallback(): void {
     if (this.killTimer) {
       return
@@ -368,8 +336,7 @@ export class Session {
           this.requestForceKill()
         } catch (error) {
           console.warn('[Session] failed to force-kill terminating subprocess:', error)
-          // Why: a transient SIGKILL rejection must not consume the only
-          // fallback owner after graceful shutdown has already returned.
+          // Why: a transient SIGKILL rejection must not consume the only fallback owner after graceful shutdown returned.
           if (attemptsRemaining > 1) {
             this.armForceKillFallback(SESSION_FORCE_KILL_RETRY_MS, attemptsRemaining - 1)
           }
@@ -388,8 +355,7 @@ export class Session {
       this._isTerminating = true
       this.releaseProducerPause({ resume: true })
     }
-    // Why: destructive cleanup joins a graceful termination but escalates it
-    // now; waiting for the 5s timer would spend most of the physical-exit budget.
+    // Why: escalate a graceful termination now; waiting for the 5s timer would spend most of the physical-exit budget.
     await this.requestForceKillWithRetry()
     await this.waitForPhysicalExit(timeoutMs)
   }
@@ -412,8 +378,7 @@ export class Session {
     if (idx !== -1) {
       this.attachedClients.splice(idx, 1)
     }
-    // Why: with no attached client, nobody will ever send resumePty — a
-    // paused shell would sit wedged until the failsafe. Resume eagerly.
+    // Why: with no attached client nobody will send resumePty, so a paused shell would wedge until the failsafe; resume eagerly.
     if (this.attachedClients.length === 0) {
       this.releaseProducerPause({ resume: true })
     }
@@ -439,10 +404,8 @@ export class Session {
     return this.emulator.partialEscapeTailAnsi
   }
 
-  // Why: the size the PTY actually applied (emulator dims, which Session.resize
-  // advances atomically with the subprocess), so the renderer can detect a
-  // resize that was dropped here (exited/disposed/invalid) instead of trusting
-  // its own last-requested size. Null on a disposed session.
+  // Why: returns the size the PTY actually applied (emulator dims) so the renderer can detect a
+  // resize dropped here (exited/disposed/invalid) instead of trusting its last-requested size.
   getAppliedSize(): { cols: number; rows: number } | null {
     if (this._disposed) {
       return null
@@ -450,10 +413,8 @@ export class Session {
     return this.emulator.getAppliedSize()
   }
 
-  /** Drains the records accumulated since the last take. Runs synchronously —
-   *  when includeSnapshot is set, the serialize happens in the same turn so no
-   *  PTY data can land between the drain and the snapshot (which would later
-   *  be replayed twice on cold restore). */
+  /** Drains records accumulated since the last take. When includeSnapshot is set it serializes in
+   *  the same turn so no PTY data lands between drain and snapshot (which would replay twice on cold restore). */
   takePendingOutput(
     includeSnapshot: boolean,
     opts: { teardownSnapshot?: boolean } = {}
@@ -503,21 +464,16 @@ export class Session {
     this.#nudgePowerShellPromptRepaint()
   }
 
-  /** Why: ConPTY's buffer clear cannot reach PSReadLine's cached cursor row,
-   *  so PowerShell's first Enter after a clear would still repaint the prompt
-   *  at the stale row, leaving a blank gap. A form feed (Ctrl+L) makes
-   *  PSReadLine itself repaint at the true origin. Gated to a PowerShell
-   *  foreground so a running command or TUI never gets a stray 0x0C, and to
-   *  an empty prompt because PSReadLine repaints pending input at a stale
-   *  cached row that ConPTY's fixed viewport doesn't track. */
+  /** Why: ConPTY's buffer clear leaves PSReadLine's cached cursor row stale, so the next prompt
+   *  repaints below a blank gap; a form feed (Ctrl+L) forces a repaint at the true origin. Gated to a
+   *  PowerShell foreground (else a running command/TUI gets a stray 0x0C) and an empty prompt (PSReadLine
+   *  repaints pending input at a stale cached row ConPTY's fixed viewport doesn't track). */
   #nudgePowerShellPromptRepaint(): void {
     if (process.platform !== 'win32') {
       return
     }
-    // Why: before shell-ready, write() would queue the form feed behind the
-    // buffered startup command and deliver it at an arbitrary later moment,
-    // when the foreground/prompt gates below no longer hold. The nudge is
-    // cosmetic — skip it rather than defer it.
+    // Why: before shell-ready, write() would queue this form feed behind the startup command and
+    // fire it later when the gates below are stale; the nudge is cosmetic, so skip rather than defer.
     if (this._shellState === 'pending' || this.postReadyFlushGate.isPending) {
       return
     }
@@ -541,13 +497,8 @@ export class Session {
       return
     }
 
-    // Why: captured BEFORE the `_state = 'exited'` flip below. This check
-    // guards the "dispose while kill() was already in flight" case — if true,
-    // the child hasn't reaped yet and we need to forceKill it here (the 5s
-    // killTimer is also about to be cleared by #teardownSubprocess). Do NOT
-    // move this capture below #teardownSubprocess or the `_state = 'exited'`
-    // assignment — #teardownSubprocess flips `_disposed` but the invariant
-    // depends on the PRE-flip value of `_state`.
+    // Why: `wasTerminating` below must be read BEFORE the `_state = 'exited'` flip — it guards the
+    // "dispose while kill() in flight" case and the invariant needs the pre-flip `_state`; do NOT move it down.
     this.releaseHeldShellReadyBytes()
     this.startupIngress.drainAndClose()
     const wasTerminating = this._isTerminating && this._state !== 'exited'
@@ -575,48 +526,31 @@ export class Session {
     }
   }
 
-  /** Public: fd-release-only teardown for sessions that have ALREADY exited
-   *  (state === 'exited') but are still retained in the host's map. Callers
-   *  MUST NOT use this on live sessions — it skips SIGKILL.
-   *
-   *  Why a separate method: after handleSubprocessExit fires, proc.pid refers
-   *  to a child that has been reaped; on POSIX that pid is eligible for reuse
-   *  and may now belong to an unrelated process. forceKillAndDisposeSubprocess
-   *  would send SIGKILL to that recycled pid. This method only releases the
-   *  PTY master fd via node-pty's destroy() (which is neutralized against the
-   *  SIGHUP-to-pid hazard by the onExit handler in pty-subprocess.ts). */
+  /** fd-release-only teardown for ALREADY-exited sessions still retained in the host map; skips
+   *  SIGKILL, so callers MUST NOT use it on live sessions. Separate method because a reaped pid is
+   *  eligible for POSIX reuse, so SIGKILL could otherwise hit an unrelated process. */
   disposeSubprocess(): void {
     this.#teardownSubprocess()
     this._state = 'exited'
   }
 
-  /** Public: orderly-shutdown path used by TerminalHost.dispose() for sessions
-   *  that are still live. Force-kills the child (SIGKILL is not ignorable),
-   *  then releases the PTY master fd synchronously via node-pty's destroy().
-   *  Bypasses the 5s KILL_TIMEOUT_MS fallback so daemon shutdown reaps
-   *  stubborn children AND frees the ptmx fd on the same tick. Does NOT fan
-   *  out onExit to attached clients — renderer reconnects cold after daemon
-   *  exit. Callers MUST check isAlive first; see disposeSubprocess() for the
-   *  already-exited case. */
+  /** Orderly-shutdown path (TerminalHost.dispose()) for live sessions: force-kills the child, then
+   *  synchronously frees the ptmx fd, bypassing the 5s KILL_TIMEOUT_MS fallback. Does NOT fan out
+   *  onExit (renderer reconnects cold after daemon exit). Callers MUST check isAlive first. */
   async forceKillAndDisposeSubprocess(): Promise<void> {
-    // Why: daemon exit cannot neutralize the native handle until a bounded
-    // retry is accepted and onExit proves the child was physically reaped.
+    // Why: daemon exit can't neutralize the native handle until a bounded retry lands and onExit proves the child was reaped.
     await this.forceKillAndWaitForExit()
     this.dispose()
   }
 
-  /** Private: shared teardown helper called by dispose() and
-   *  forceKillAndDisposeSubprocess(). Flips `_disposed`, clears pending timers,
-   *  and forwards to subprocess.dispose() exactly once. Does NOT set `_state` —
-   *  the caller owns the state transition AFTER capturing any invariants that
-   *  depend on the pre-flip value (see the wasTerminating capture in dispose). */
+  /** Shared teardown for dispose()/forceKillAndDisposeSubprocess(). Does NOT set `_state` — the
+   *  caller owns that after capturing pre-flip invariants (see the wasTerminating capture in dispose). */
   #teardownSubprocess(): void {
     if (this._disposed) {
       return
     }
     this._disposed = true
-    // Why: never leave a paused fd behind on any teardown path — the handle's
-    // own dead-guard makes this a no-op when the child is already reaped.
+    // Why: never leave a paused fd behind on teardown; the handle's dead-guard makes this a no-op once the child is reaped.
     this.releaseProducerPause({ resume: true })
     if (this.killTimer) {
       clearTimeout(this.killTimer)
@@ -640,8 +574,7 @@ export class Session {
     try {
       this.subprocess.dispose()
     } catch (err) {
-      // Why: dispose() is documented never to throw, but if it does we must not
-      // prevent callers from completing their own cleanup (fanout, map removal).
+      // Why: dispose() should never throw, but if it does, callers must still complete their own cleanup (fanout, map removal).
       console.warn('[Session] subprocess.dispose() threw:', err)
     }
   }
@@ -657,9 +590,7 @@ export class Session {
       this.pendingOutputOverflowed = true
       return
     }
-    // Why: TUIs emit thousands of tiny chunks between checkpoint ticks;
-    // coalescing adjacent output keeps the take RPC and log frames compact.
-    // The 64KB segment cap bounds per-chunk string-append cost.
+    // Why: coalesce the thousands of tiny TUI chunks per tick to keep take RPC/log frames compact; 64KB cap bounds append cost.
     const last = this.pendingOutputRecords.at(-1)
     if (record.kind === 'output' && last?.kind === 'output' && last.data.length < 64 * 1024) {
       last.data += record.data
@@ -690,11 +621,8 @@ export class Session {
   private emitSubprocessOutput(emission: PtyIngressEmission): void {
     const { data } = emission
     const rawLength = emission.rawEndSeq - emission.rawStartSeq
-    // Why: daemon stream thinning can omit bytes before main sees them. The
-    // absolute count lets an authoritative snapshot cover those gaps while
-    // renderer reconciliation deduplicates any queued post-snapshot tail.
+    // Why: absolute raw count (daemon stream thinning can drop bytes) lets a snapshot cover the gaps while the renderer dedups the tail.
     this.outputSequence += rawLength
-    // Feed data to headless emulator for state tracking
     if (data.length > 0) {
       this.emulator.write(data)
       this.recordPendingOutput({ kind: 'output', data })
@@ -721,8 +649,7 @@ export class Session {
     this._exitCode = code
     this._state = 'exited'
     this._isTerminating = false
-    // Why resume:false — the child is reaped, so there is nothing to unblock;
-    // only the failsafe timer must not outlive the session.
+    // Why resume:false — the child is reaped (nothing to unblock); only the failsafe timer must not outlive the session.
     this.releaseProducerPause({ resume: false })
 
     if (this.killTimer) {
@@ -735,20 +662,15 @@ export class Session {
     }
     this.postReadyFlushGate.clear()
 
-    // Why: release the ptmx fd on the natural-exit path. Without this, the
-    // node-pty wrapper's _socket stays alive until GC and the master fd leaks
-    // (see docs/fix-pty-fd-leak.md). Do NOT route through #teardownSubprocess:
-    // that helper flips `_disposed = true`, which would short-circuit the later
-    // Session.dispose() call from TerminalHost.reapSession (wired via onExit
-    // below) — skipping attachedClients/emulator/postReadyFlushGate cleanup.
+    // Why: release the ptmx fd here or node-pty's _socket leaks the master fd until GC (docs/fix-pty-fd-leak.md).
+    // Not via #teardownSubprocess: it flips `_disposed`, short-circuiting the later Session.dispose() reaper.
     this.disposeSubprocessHandle()
 
     for (const client of this.attachedClients) {
       client.onExit(code)
     }
 
-    // Why: hand off to the owner's reaper so the emulator is disposed and the
-    // session dropped from the host map; otherwise dead sessions accumulate.
+    // Why: hand off to the owner's reaper (disposes emulator, drops session from host map); else dead sessions accumulate.
     this.onSessionExit?.(code)
   }
 
@@ -758,10 +680,7 @@ export class Session {
     }
     const heldBytes = drainShellReadyHeldBytes(this.shellReadyScanState)
     this.shellReadyScanState = null
-    // Why: daemon scanning now runs before emulator/client fan-out so marker
-    // bytes can be stripped. If readiness never completes, preserve the
-    // previous behavior by releasing any held prefix before timeout or exit
-    // state changes discard it.
+    // Why: scanning strips marker bytes before fan-out; if readiness never completes, release any held prefix before timeout/exit discards it.
     this.startupIngress.accept(heldBytes)
     return heldBytes
   }
@@ -839,8 +758,7 @@ export class Session {
   }
 
   private waitForPhysicalExit(timeoutMs: number): Promise<void> {
-    // Why: timed-out destructive retries must detach from an unkillable child;
-    // otherwise every retry stays retained until the process eventually exits.
+    // Why: timed-out destructive retries must detach from an unkillable child, else each retry stays retained until it exits.
     return this.physicalExit.waitForExit(
       timeoutMs,
       () => new Error(`Timed out waiting for PTY process exit: ${this.sessionId}`)
diff --git a/src/main/daemon/shell-ready.test.ts b/src/main/daemon/shell-ready.test.ts
index b741ef057d0..3b62b6d3fca 100644
--- a/src/main/daemon/shell-ready.test.ts
+++ b/src/main/daemon/shell-ready.test.ts
@@ -19,18 +19,14 @@ const itWithZsh = hasZsh ? it : it.skip
 
 const SHELL_READY_MARKER_OUTPUT = '\x1b]777;orca-shell-ready\x07'
 
-// Why: the shell-ready marker is emitted from zle-line-init, which only fires
-// on a real TTY — spawn through node-pty instead of spawnSync.
+// Why: the shell-ready marker fires from zle-line-init only on a real TTY, so spawn through node-pty not spawnSync.
 async function runInteractiveZshLogin(args: {
   tempHome: string
   wrapperZdotdir: string
   isDone: (output: string) => boolean
 }): Promise<string> {
   const pty = await import('node-pty')
-  // Why: -o noglobalrcs skips /etc/zsh/* on CI runners, whose insecure (group-
-  // writable) fpath dirs make the global compinit block on an interactive
-  // "insecure directories" [y/n] prompt before zle-line-init ever fires. The
-  // marker contract lives entirely in our ZDOTDIR files, which still load.
+  // Why: -o noglobalrcs skips /etc/zsh/*, whose insecure fpath dirs make compinit block on a [y/n] prompt before the marker fires.
   const proc = pty.spawn('zsh', ['-o', 'noglobalrcs', '-l'], {
     name: 'xterm-256color',
     cols: 80,
@@ -64,16 +60,13 @@ async function runInteractiveZshLogin(args: {
   return output
 }
 
-// Why: exercise an arbitrary interactive zsh rc (its own ZDOTDIR, no wrapper)
-// so a test can source the marker block directly — e.g. twice, to check the
-// registration is idempotent and keeps chaining the user's prior widget.
+// Why: exercise an arbitrary interactive zsh rc (own ZDOTDIR, no wrapper) so a test can source the marker block directly.
 async function runInteractiveZshRc(args: {
   zdotdir: string
   isDone: (output: string) => boolean
 }): Promise<string> {
   const pty = await import('node-pty')
-  // Why: -o noglobalrcs skips /etc/zsh/* so the CI runner's global compinit
-  // can't block on an insecure-directory [y/n] prompt before our marker fires.
+  // Why: -o noglobalrcs skips /etc/zsh/* so the CI runner's global compinit can't block on an insecure-directory [y/n] prompt.
   const proc = pty.spawn('zsh', ['-o', 'noglobalrcs', '-i'], {
     name: 'xterm-256color',
     cols: 80,
@@ -217,10 +210,7 @@ describePosix('daemon shell-ready launch config', () => {
   })
 
   it('falls back to HOME for ORCA_ORIG_ZDOTDIR when inherited ZDOTDIR points at a wrapper dir', async () => {
-    // Why: guards against the zsh recursion loop that happens when the daemon
-    // was forked from a shell which was itself an Orca PTY. Such a shell has
-    // ZDOTDIR=<some>/shell-ready/zsh; propagating that unchanged would make
-    // the wrapper `source "$ORCA_ORIG_ZDOTDIR/.zshenv"` source itself.
+    // Why: an Orca-PTY parent has ZDOTDIR=.../shell-ready/zsh; propagating it makes the wrapper source itself (recursion loop).
     const previousZdotdir = process.env.ZDOTDIR
     const previousHome = process.env.HOME
     process.env.ZDOTDIR = '/some/other/orca/shell-ready/zsh'
@@ -334,19 +324,13 @@ describePosix('daemon shell-ready launch config', () => {
     expect(zlogin).toContain('zle -N zle-line-init __orca_prompt_mark')
     expect(zlogin).toContain('__orca_prev_line_init_fn="${widgets[zle-line-init]#user:}"')
     expect(zlogin).toContain('printf "\\033]777;orca-shell-ready\\007"')
-    // Why: add-zle-hook-widget aborts its hook chain when an earlier hook
-    // exits non-zero, so the marker must not be registered through it.
+    // Why: add-zle-hook-widget aborts its chain when an earlier hook exits non-zero, so don't register the marker through it.
     expect(zlogin).not.toContain('add-zle-hook-widget line-init')
-    // Why: re-source guard — skip re-capturing when we are already the bound
-    // widget so the prior widget chain survives a second source.
+    // Why: re-source guard — skip re-capturing when already the bound widget so the prior chain survives a second source.
     expect(zlogin).toContain('== "user:__orca_prompt_mark"')
   })
 
-  // Why: regression guard — oh-my-zsh vi-mode installs a raw zle-line-init
-  // that returns non-zero when VI_MODE_SET_CURSOR is unset. Registering the
-  // marker via add-zle-hook-widget let that failing widget abort the hook
-  // chain, so the marker never fired and every queued startup command sat on
-  // the daemon's pre-ready timeout (a 15s "bare shell" before the agent).
+  // Why: oh-my-zsh vi-mode's zle-line-init returns non-zero; add-zle-hook-widget then aborts the chain and the marker never fires.
   itWithZsh(
     'emits the shell-ready marker even when a user zle-line-init widget fails (oh-my-zsh vi-mode shape)',
     async () => {
@@ -401,8 +385,7 @@ describePosix('daemon shell-ready launch config', () => {
           isDone: (current) =>
             current.includes(SHELL_READY_MARKER_OUTPUT) && current.includes(userHookOutput)
         })
-        // Why: the marker widget chains to the previously installed widget, so
-        // an azhw dispatcher registered by user config must keep dispatching.
+        // Why: the marker widget chains to the prior widget, so a user-registered azhw dispatcher must keep dispatching.
         expect(output).toContain(SHELL_READY_MARKER_OUTPUT)
         expect(output).toContain(userHookOutput)
         expect(output.indexOf(SHELL_READY_MARKER_OUTPUT)).toBeLessThan(
@@ -415,10 +398,7 @@ describePosix('daemon shell-ready launch config', () => {
     15_000
   )
 
-  // Why: the marker block is normally sourced once per shell, but a re-source
-  // (nested Orca, manual re-source) must stay idempotent — it must keep
-  // chaining the user's original zle-line-init instead of clobbering the
-  // captured function to empty and silently dropping it on later prompts.
+  // Why: a re-source (nested Orca, manual) must stay idempotent — keep chaining the user's original zle-line-init.
   itWithZsh(
     'keeps chaining the prior zle-line-init widget when the marker block is sourced twice',
     async () => {
@@ -448,8 +428,7 @@ describePosix('daemon shell-ready launch config', () => {
         expect(output.indexOf(SHELL_READY_MARKER_OUTPUT)).toBeLessThan(
           output.indexOf(userHookOutput)
         )
-        // Why: idempotent — the marker must fire exactly once per prompt, not
-        // duplicated by the second registration.
+        // Why: idempotent — the marker must fire exactly once per prompt, not duplicated by the second registration.
         expect(output.split(SHELL_READY_MARKER_OUTPUT)).toHaveLength(2)
       } finally {
         rmSync(zdotdir, { recursive: true, force: true })
@@ -498,9 +477,7 @@ describePosix('daemon shell-ready launch config', () => {
     expect(bashRc).toContain(ompWrapperLine)
   })
 
-  // Why: regression guard for issue #2422. The daemon-side bash wrapper must
-  // emit OSC 133 C/D so SSH/remote bash sessions also clear stale 'working'
-  // agent rows when the foreground command exits.
+  // Why: regression guard for issue #2422 — bash wrapper must emit OSC 133 C/D so SSH sessions clear stale 'working' agent rows.
   it('emits OSC 133 C/D markers in the daemon bash wrapper', async () => {
     const { getShellReadyLaunchConfig } = await importFreshShellReady()
 
@@ -512,14 +489,11 @@ describePosix('daemon shell-ready launch config', () => {
 
     expect(bashRc).toContain('printf "\\033]133;D;%s\\007"')
     expect(bashRc).toContain('printf "\\033]133;C\\007"')
-    // precmd is prepended (captures $? first) and the epilogue is appended last,
-    // so a framework that must be last in PROMPT_COMMAND stays between them.
+    // precmd is prepended (captures $? first), epilogue appended last, so a framework needing last position stays between them.
     expect(bashRc).toContain(
       'PROMPT_COMMAND="__orca_osc133_precmd${PROMPT_COMMAND:+;${PROMPT_COMMAND}};__orca_osc133_epilogue"'
     )
-    // The final DEBUG arming runs after PROMPT_COMMAND setup so the rcfile's own
-    // commands are not mistaken for a foreground command (lastIndexOf skips the
-    // identical re-arm inside __orca_osc133_epilogue).
+    // DEBUG is armed after PROMPT_COMMAND setup so rcfile commands aren't seen as foreground; lastIndexOf skips the epilogue's re-arm.
     expect(bashRc.lastIndexOf("trap '__orca_osc133_preexec' DEBUG")).toBeGreaterThan(
       bashRc.indexOf('PROMPT_COMMAND="__orca_osc133_precmd')
     )
@@ -562,9 +536,7 @@ describePosix('daemon shell-ready launch config', () => {
     'still emits 133;C when bash-preexec re-arms the DEBUG trap at first prompt',
     async () => {
       const { getDaemonBashShellReadyRcfileContent } = await importFreshShellReady()
-      // Minimal bash-preexec imitation (iTerm2/starship setups): re-arms its own
-      // DEBUG trap from PROMPT_COMMAND at the first prompt — silencing Orca's
-      // trap — and dispatches preexec_functions with the command as $1.
+      // Minimal bash-preexec imitation: re-arms its own DEBUG trap from PROMPT_COMMAND at first prompt, silencing Orca's trap.
       writeFileSync(
         join(userDataPath, '.bash_profile'),
         [
@@ -590,13 +562,7 @@ describePosix('daemon shell-ready launch config', () => {
     'dispatches a non-empty preexec_functions against the real command, not Orca hooks',
     async () => {
       const { getDaemonBashShellReadyRcfileContent } = await importFreshShellReady()
-      // Why: Orca's epilogue captures bash-preexec's re-armed DEBUG trap and
-      // chains it. A real preexec callback must fire against the user's command —
-      // not __orca_osc133_epilogue. Mirror upstream bash-preexec faithfully: it
-      // enables `functrace` (so Orca's `trap -p DEBUG` capture sees its trap),
-      // defers that install to the first prompt via PROMPT_COMMAND, and reads the
-      // command from `history` (so DEBUG fires on prompt hooks never dispatch a
-      // phantom). The naive `$BASH_COMMAND` imitation does none of these.
+      // Why: the epilogue chains bash-preexec's re-armed DEBUG trap, so a real preexec callback must fire against the user's command.
       writeFileSync(
         join(userDataPath, '.bash_profile'),
         [
@@ -648,9 +614,7 @@ describePosix('daemon shell-ready launch config', () => {
   })
 
   it('preserves a real inherited ZDOTDIR as ORCA_ORIG_ZDOTDIR', async () => {
-    // Why: users who run a custom zsh dotfiles directory legitimately set
-    // ZDOTDIR before launching Orca. We only want to reject the self-loop
-    // case — any real user ZDOTDIR must round-trip so their configs load.
+    // Why: only the wrapper self-loop should be rejected; a real user ZDOTDIR must round-trip so their configs load.
     const previousZdotdir = process.env.ZDOTDIR
     process.env.ZDOTDIR = '/Users/alice/.config/zsh'
     try {
@@ -668,9 +632,7 @@ describePosix('daemon shell-ready launch config', () => {
   })
 
   it('rejects inherited ZDOTDIR ending in /shell-ready/zsh even with a trailing slash', async () => {
-    // Why: `endsWith('/shell-ready/zsh')` without normalization is bypassed by
-    // a trailing slash, which some shell startup scripts add. Pinning this case
-    // guards against a regression that would reintroduce the recursion loop.
+    // Why: a trailing slash bypasses `endsWith('/shell-ready/zsh')`, reintroducing the recursion loop if unguarded.
     const previousZdotdir = process.env.ZDOTDIR
     const previousHome = process.env.HOME
     process.env.ZDOTDIR = '/some/other/orca/shell-ready/zsh/'
@@ -694,10 +656,7 @@ describePosix('daemon shell-ready launch config', () => {
   })
 
   it('falls back to HOME when ZDOTDIR is only slashes (e.g. "/")', async () => {
-    // Why: a bare `/` (or `////`) normalizes to empty and is never a user's
-    // real zsh config root; sourcing `/.zshenv` would silently no-op. Falling
-    // back to HOME matches what the wrapper already assumes when ZDOTDIR is
-    // unset.
+    // Why: a bare `/` normalizes to empty (never a real config root), so fall back to HOME as when ZDOTDIR is unset.
     const previousZdotdir = process.env.ZDOTDIR
     const previousHome = process.env.HOME
     process.env.ZDOTDIR = '/'
@@ -721,9 +680,7 @@ describePosix('daemon shell-ready launch config', () => {
   })
 
   it('preserves ZDOTDIR that contains /shell-ready/zsh as a substring but does not end with it', async () => {
-    // Why: the guard must match the suffix, not a substring — a user directory
-    // like `/Users/alice/shell-ready/zsh-custom` should round-trip unchanged.
-    // Pinning this case prevents an over-eager `includes` swap in the future.
+    // Why: guard must match suffix not substring — `/Users/alice/shell-ready/zsh-custom` must round-trip unchanged.
     const previousZdotdir = process.env.ZDOTDIR
     process.env.ZDOTDIR = '/Users/alice/shell-ready/zsh-custom'
     try {
@@ -740,9 +697,7 @@ describePosix('daemon shell-ready launch config', () => {
   })
 
   it('sources user .zshenv at wrapper top level before repinning ZDOTDIR', async () => {
-    // Why: PR #1737 sourced .zshenv inside a wrapper function, which broke
-    // common patterns like "typeset -U path". The fix must keep .zshenv at
-    // zsh top level while still capturing the ZDOTDIR it resolved.
+    // Why: PR #1737 sourced .zshenv in a wrapper function, breaking "typeset -U path"; keep it at zsh top level.
     const { getShellReadyLaunchConfig } = await importFreshShellReady()
 
     getShellReadyLaunchConfig('/bin/zsh')
@@ -760,8 +715,7 @@ describePosix('daemon shell-ready launch config', () => {
   })
 
   it('preserves spawn-env ORCA_ORIG_ZDOTDIR as fallback when discovery yields nothing', async () => {
-    // Why: if user .zshenv returns early or doesn't set ZDOTDIR, the wrapper
-    // should fall back to the spawn-env ORCA_ORIG_ZDOTDIR (if present), then HOME.
+    // Why: when user .zshenv sets no ZDOTDIR, the wrapper falls back to spawn-env ORCA_ORIG_ZDOTDIR, then HOME.
     const { getShellReadyLaunchConfig } = await importFreshShellReady()
 
     getShellReadyLaunchConfig('/bin/zsh')
diff --git a/src/main/daemon/terminal-host.ts b/src/main/daemon/terminal-host.ts
index d8458aa81ad..ea1093572aa 100644
--- a/src/main/daemon/terminal-host.ts
+++ b/src/main/daemon/terminal-host.ts
@@ -49,9 +49,7 @@ export class TerminalHost {
     }
     const existing = this.sessions.get(opts.sessionId)
 
-    // Why: async descendant capture must finish before anyone can attach or
-    // dispose/recreate this id. Disposing here would kill the root before the
-    // snapshot and reattaching would hand out a doomed session.
+    // Why: async descendant capture must finish before attach/recreate, or we hand out a doomed session.
     if (this.sessionTeardown.get(opts.sessionId) || existing?.isTerminating) {
       throw new SessionNotFoundError(opts.sessionId)
     }
@@ -71,12 +69,10 @@ export class TerminalHost {
     }
 
     if (existing?.isAlive && existing.isTerminating) {
-      // Why: replacing a SIGKILLed-but-unreaped child would lose ownership of
-      // its native handles and let the same session id hide two generations.
+      // Why: replacing a SIGKILLed-but-unreaped child would leak its native handles and hide two generations under one id.
       throw new Error(`Session "${opts.sessionId}" is terminating`)
     }
 
-    // Clean up dead session if present
     if (existing) {
       existing.dispose()
       this.sessions.delete(opts.sessionId)
@@ -102,11 +98,7 @@ export class TerminalHost {
       terminalWindowsPowerShellImplementation: opts.terminalWindowsPowerShellImplementation
     })
 
-    // Why: the caller computed shellReadySupported from the preferred shell,
-    // before spawn. A Unix fallback (e.g. /bin/sh) never emits the ready
-    // marker, so keeping the stale flag would queue startup commands until the
-    // shell-ready timeout and bracketed-paste-wrap them for a line editor
-    // without paste mode.
+    // Why: the pre-spawn flag goes stale if spawn fell back to a shell (e.g. /bin/sh) that never emits the ready marker.
     const shellReadySupported =
       (opts.shellReadySupported ?? false) &&
       (subprocess.shellPath === undefined ||
@@ -123,10 +115,7 @@ export class TerminalHost {
       historySeed: opts.historySeed,
       ...(opts.startupIngress ? { startupIngress: opts.startupIngress } : {}),
       wslDistro,
-      // Why: reap the dead session (dispose emulator + drop from the map) the
-      // moment its subprocess exits, instead of retaining it for the daemon's
-      // lifetime. Nothing reads a dead session's emulator (getSnapshot/
-      // takePendingOutput/listSessions all skip !isAlive sessions).
+      // Why: reap the dead session (dispose emulator + drop from map) on subprocess exit, not at daemon shutdown.
       onExit: () => this.reapSession(opts.sessionId),
       ...(opts.shellReadyTimeoutMs !== undefined
         ? { shellReadyTimeoutMs: opts.shellReadyTimeoutMs }
@@ -138,18 +127,10 @@ export class TerminalHost {
     const token = session.attachClient(opts.streamClient)
 
     if (opts.command && !subprocess.startupCommandDeliveredInShellArgs) {
-      // Why: startup commands must run inside the long-lived interactive shell
-      // the daemon keeps for the pane. Session.write() handles the shell-ready
-      // barrier for supported shells and falls back to an immediate write for
-      // unsupported ones.
-      // Why CR on Windows: PowerShell's PSReadLine and cmd.exe submit the line
-      // on CR (`\r`); a bare LF leaves the command typed but unsubmitted, so
-      // the user would need to press Enter after Orca launches the agent or
-      // setup script. POSIX shells accept CR as Enter under ICRNL.
+      // Why: startup commands must run inside the long-lived interactive shell the daemon keeps for the pane.
+      // Why CR on Windows: PSReadLine/cmd.exe submit on CR; a bare LF leaves it unsubmitted (POSIX accepts CR via ICRNL).
       const submit = process.platform === 'win32' ? '\r' : '\n'
-      // Why: multiline startup prompts are pasted literally via bracketed paste
-      // only for Orca-wrapped bash/zsh, which is exactly when the shell-ready
-      // barrier is supported; other shells keep the raw submit path.
+      // Why: bracketed-paste only for Orca-wrapped bash/zsh (== shell-ready supported); other shells use the raw submit path.
       session.write(
         buildStartupCommandSubmission(opts.command, {
           submit,
@@ -180,9 +161,7 @@ export class TerminalHost {
     this.getAliveSession(sessionId).resize(cols, rows)
   }
 
-  // Why null-not-throw (unlike write/resize): pause/resume are best-effort
-  // flow-control hints; a session that exited while the notify was in flight
-  // must not surface an error or a synthetic exit.
+  // Why null-not-throw (unlike write/resize): pause/resume are best-effort hints against a session that may have exited.
   pauseProducer(sessionId: string): void {
     const session = this.sessions.get(sessionId)
     if (!session || !session.isAlive) {
@@ -208,10 +187,7 @@ export class TerminalHost {
     return Promise.resolve(killed)
   }
 
-  // Why: dispose a dead session's headless emulator and drop it from the map so
-  // exited terminals don't pin ~5000 rows of scrollback for the daemon's life.
-  // No-ops on live sessions (a live session must never be disposed here) and on
-  // already-reaped/unknown ids. Wired as the Session onExit hook.
+  // Why: dispose a dead session's emulator so exited terminals don't pin ~5000 rows of scrollback for the daemon's life.
   private reapSession(sessionId: string): void {
     const session = this.sessions.get(sessionId)
     if (!session || session.isAlive) {
@@ -236,17 +212,12 @@ export class TerminalHost {
     if (tracked) {
       return tracked
     }
-    // Why: the emulator's cwd is null until the shell emits OSC 7. Orca's
-    // bash/zsh rcfiles ship with OSC 133 markers but not OSC 7, so the
-    // tracked value stays null through the entire session for most users.
-    // Fall back to the live process cwd via /proc/<pid>/cwd (Linux) or
-    // lsof (macOS). Matches the LocalPtyProvider.getCwd fallback.
+    // Why: emulator cwd stays null (Orca rcfiles emit OSC 133 not OSC 7), so fall back to the live process cwd.
     const resolved = await resolveProcessCwd(session.pid)
     return resolved || null
   }
 
-  // Why: returns null (not throws) for a dead/missing session — this is fetched
-  // for the tab-bar icon, so a vanished pane should quietly yield "no agent".
+  // Why: null-not-throw — fetched for the tab-bar icon, so a vanished pane should quietly yield "no agent".
   getForegroundProcess(sessionId: string): string | null {
     const session = this.sessions.get(sessionId)
     if (!session || !session.isAlive) {
@@ -267,9 +238,7 @@ export class TerminalHost {
     this.getAliveSession(sessionId).clearScrollback()
   }
 
-  // Why: unlike getAliveSession (which throws), this returns null for dead/missing
-  // sessions. Checkpoint is best-effort — a session that exited between the timer
-  // firing and the RPC arriving should not throw.
+  // Why: null-not-throw (unlike getAliveSession) — checkpoint is best-effort against a session that may have just exited.
   getSnapshot(sessionId: string, opts: { scrollbackRows?: number } = {}): TerminalSnapshot | null {
     const session = this.sessions.get(sessionId)
     if (!session || !session.isAlive) {
@@ -278,8 +247,7 @@ export class TerminalHost {
     return session.getSnapshot(opts)
   }
 
-  // Why: scan-authority handoff seed (null-not-throw like getSnapshot) — the
-  // emulator's dangling incomplete escape at the current stream position.
+  // Why: scan-authority handoff seed (null-not-throw like getSnapshot) — emulator's dangling incomplete escape at the stream position.
   getPartialEscapeTailAnsi(sessionId: string): string {
     const session = this.sessions.get(sessionId)
     if (!session || !session.isAlive) {
@@ -288,9 +256,7 @@ export class TerminalHost {
     return session.getPartialEscapeTailAnsi()
   }
 
-  // Why: read-only readback of the size the PTY actually applied (null-not-throw
-  // like getSnapshot). The renderer compares this against xterm to detect a
-  // resize that was dropped/coerced daemon-side and re-assert it.
+  // Why: renderer diffs this against xterm to detect a dropped/coerced daemon-side resize; null-not-throw like getSnapshot.
   getAppliedSize(sessionId: string): { cols: number; rows: number } | null {
     const session = this.sessions.get(sessionId)
     if (!session || !session.isAlive) {
@@ -299,8 +265,7 @@ export class TerminalHost {
     return session.getAppliedSize()
   }
 
-  // Why: same null-not-throw semantics as getSnapshot — incremental
-  // checkpoints are best-effort against sessions that may have just exited.
+  // Why: null-not-throw like getSnapshot — incremental checkpoints are best-effort against a just-exited session.
   takePendingOutput(
     sessionId: string,
     includeSnapshot: boolean,
diff --git a/src/main/hooks.ts b/src/main/hooks.ts
index 93a5b5424e1..ef5aaf1e5ea 100644
--- a/src/main/hooks.ts
+++ b/src/main/hooks.ts
@@ -62,11 +62,7 @@ export function hasHooksFile(repoPath: string): boolean {
   return existsSync(join(repoPath, 'orca.yaml'))
 }
 
-// Why: when a newer Orca release adds a top-level key to `orca.yaml` (like
-// `issueCommand` was added here), older versions that don't recognise it will
-// return `null` from `parseOrcaYaml` and show a confusing "could not be parsed"
-// error.  Detecting well-formed but unrecognised keys lets the UI suggest an
-// update instead of implying the file is broken.
+// Why: detect unrecognised keys so the UI can suggest an update instead of showing a "could not be parsed" error.
 const RECOGNIZED_ORCA_YAML_KEYS = new Set([
   'scripts',
   'issueCommand',
@@ -74,17 +70,12 @@ const RECOGNIZED_ORCA_YAML_KEYS = new Set([
   'environmentRecipes'
 ])
 
-/**
- * Return true when `orca.yaml` contains at least one top-level key that this
- * version of Orca does not handle.
- */
+/** True when `orca.yaml` has a top-level key this version of Orca does not handle. */
 export function hasUnrecognizedOrcaYamlKeys(repoPath: string): boolean {
   try {
     const content = readFileSync(join(repoPath, 'orca.yaml'), 'utf-8')
     for (const line of iterateLfScriptLines(content)) {
-      // Why: bare `key:` at end-of-line (no trailing space) is valid YAML for
-      // a mapping with a block value on the next line. Match both forms so
-      // newer keys like `futureFeature:\n  nested` are still detected.
+      // Why: match bare `key:` at end-of-line too, since a mapping with a block value on the next line is valid YAML.
       const m = line.match(/^([A-Za-z][A-Za-z0-9_-]*):(\s|$)/)
       if (m != null && !RECOGNIZED_ORCA_YAML_KEYS.has(m[1])) {
         return true
@@ -97,9 +88,7 @@ export function hasUnrecognizedOrcaYamlKeys(repoPath: string): boolean {
 }
 
 // ─── Issue command files ────────────────────────────────────────────────
-// Why: `orca.yaml` is the tracked, project-wide defaults surface, while
-// `.orca/issue-command` remains the per-user override. Keeping the local file in
-// `.orca/` lets users customize agent automation without editing committed config.
+// Why: `.orca/issue-command` is the per-user override; `orca.yaml` is the tracked project default.
 
 const ORCA_DIR = '.orca'
 const ISSUE_COMMAND_FILENAME = 'issue-command'
@@ -150,9 +139,7 @@ export function readIssueCommand(repoPath: string): ResolvedIssueCommand {
 
 /**
  * Write the per-user issue command override to `{repoRoot}/.orca/issue-command`.
- * Creates `.orca/` and ensures it is in `.gitignore` on first write.
- * If content is empty, deletes only the override so the shared `orca.yaml`
- * command becomes effective again.
+ * Empty content deletes the override so the shared `orca.yaml` command applies again.
  */
 export function writeIssueCommand(repoPath: string, content: string): void {
   const filePath = getIssueCommandFilePath(repoPath)
@@ -172,16 +159,12 @@ export function writeIssueCommand(repoPath: string, content: string): void {
     writeFileSync(filePath, `${trimmed}\n`, 'utf-8')
   } catch (err) {
     console.error('[hooks] Failed to write issue command:', err)
-    // Why: re-throw so the error propagates through the IPC handler to the
-    // renderer, which already has .catch() ready to surface write failures.
+    // Why: re-throw so the IPC handler surfaces the write failure to the renderer's .catch().
     throw err
   }
 }
 
-/**
- * Ensure `.orca` is listed in the repo's `.gitignore` so the per-user
- * directory is never accidentally committed.
- */
+/** Ensure `.orca` is in `.gitignore` so the per-user directory is never committed. */
 function ensureOrcaDirIgnored(repoPath: string): void {
   const gitignorePath = join(repoPath, '.gitignore')
   try {
@@ -239,9 +222,7 @@ export function getEffectiveHooksFromConfig(
     return null
   }
 
-  // Why: committed `orca.yaml` and local Settings commands can intentionally
-  // coexist, but the source policy defines whether the committed file is an
-  // authoritative boundary, local settings are authoritative, or both run.
+  // Why: committed `orca.yaml` and local Settings can coexist; the source policy decides which is authoritative.
   return {
     scripts: {
       ...(setup ? { setup } : {}),
@@ -305,8 +286,7 @@ export function getDefaultTabsLaunch(
       hasLocalScript: Boolean(repo.hookSettings?.scripts.setup?.trim())
     }
   )
-  // Why: default tab commands come from committed `orca.yaml`; a repo set to
-  // local-only may still use shared titles/colors, but must not execute them.
+  // Why: local-only repos may use shared tab titles/colors but must not run the committed orca.yaml commands.
   const canRunSharedCommands = sharedCommandPolicy !== 'local-only'
   const runCommands =
     hasCommands && canRunSharedCommands ? shouldRunSetupForCreate(repo, decision) : false
@@ -394,8 +374,7 @@ function getHookWslContext(
     return null
   }
 
-  // Why: project runtime can route a normal Windows checkout through WSL; hooks
-  // must cd to the Linux view of that path rather than running in cmd.exe.
+  // Why: project runtime can route a Windows checkout through WSL, so hooks need the Linux view of the path.
   return {
     distro: wslDistro,
     linuxPath: toLinuxPath(cwd)
@@ -412,11 +391,7 @@ export function buildWindowsRunnerScript(script: string): string {
       continue
     }
 
-    // Why: setup commands often invoke `npm`/`pnpm`, which are batch files on
-    // Windows. Calling one batch file from another without `call` never returns
-    // to later lines, and plain newline-separated commands also keep running
-    // after failures. Wrap each line in `call` and bail on non-zero exit codes
-    // so the generated runner matches the fail-fast behavior of `set -e`.
+    // Why: npm/pnpm are Windows batch files; `call` each line and bail on errorlevel for set -e fail-fast behavior.
     runnerScript += `call ${command}\r\nif errorlevel 1 exit /b %errorlevel%\r\n`
   }
 
@@ -459,8 +434,7 @@ export function createSetupRunnerScript(
 export function getSetupRunnerEnvVars(repo: Repo, worktreePath: string): Record<string, string> {
   return {
     ...getSetupEnvVars(repo, worktreePath),
-    // Why: the visible Setup terminal is still unattended automation; user
-    // terminal opt-out must not let its git commands open credential UI.
+    // Why: the Setup terminal is unattended automation, so force the credential guard regardless of user opt-out.
     [TERMINAL_GIT_CREDENTIAL_GUARD_POLICY_ENV]: 'guard'
   }
 }
@@ -496,11 +470,7 @@ export function createIssueCommandRunnerScript(
   command: string,
   projectRuntime?: ProjectExecutionRuntimeResolution | HookRuntimeTarget
 ): WorktreeSetupLaunch {
-  // Why: long issue-automation commands are user-visible shell input when
-  // written directly to the PTY, so terminal line editors can wrap or truncate
-  // them before execution. Writing the real command into a runner script keeps
-  // the shell startup path short and mirrors the already-stable setup runner
-  // flow instead of inventing a second launch mechanism.
+  // Why: writing long commands into a runner script avoids the PTY line editor wrapping/truncating them.
   return createWorktreeRunnerScript(
     repo,
     worktreePath,
@@ -519,19 +489,14 @@ function createWorktreeRunnerScript(
   waitForAgentStartup?: boolean
 ): WorktreeSetupLaunch {
   const envVars = getSetupRunnerEnvVars(repo, worktreePath)
-  // Why: WSL worktrees run on a Linux filesystem even though process.platform
-  // is 'win32'. Use bash scripts for WSL, .cmd for native Windows.
+  // Why: WSL worktrees are Linux fs even though process.platform is 'win32'; use bash for WSL, .cmd for native Windows.
   const wslWorktree = isWslPath(worktreePath) || Boolean(runtimeTarget?.wslDistro)
   const useWindowsFormat = process.platform === 'win32' && !wslWorktree
-  // Why: linked git worktrees use a `.git` file that points at the real gitdir,
-  // so writing under `${worktreePath}/.git/...` fails. `git rev-parse --git-path`
-  // resolves the actual per-worktree git storage path safely across platforms.
+  // Why: linked worktrees use a `.git` file, so resolve the real per-worktree gitdir via git rev-parse --git-path.
   const gitRelPath = useWindowsFormat ? `orca/${runnerBaseName}.cmd` : `orca/${runnerBaseName}.sh`
   let runnerScriptPath = getGitPath(worktreePath, gitRelPath, runtimeTarget)
 
-  // Why: for WSL worktrees, getGitPath returns a Linux path (e.g. /home/user/...)
-  // because git runs inside WSL. Convert it to a Windows UNC path so mkdirSync
-  // and writeFileSync (which run on Windows) can access it.
+  // Why: git runs inside WSL and returns a Linux path; convert to a UNC path so the Windows fs calls can reach it.
   if (wslWorktree) {
     const wslInfo = getHookWslContext(worktreePath, runtimeTarget)
     if (wslInfo?.distro) {
@@ -545,14 +510,11 @@ function createWorktreeRunnerScript(
     writeFileSync(runnerScriptPath, buildWindowsRunnerScript(script), 'utf-8')
   } else {
     writeFileSync(runnerScriptPath, buildPosixRunnerScript(script), 'utf-8')
-    // Why: chmod via UNC paths to WSL filesystem is supported by Windows and
-    // sets the execute bit correctly inside WSL.
+    // Why: chmod over a UNC path to the WSL filesystem sets the execute bit correctly inside WSL.
     chmodSync(runnerScriptPath, 0o755)
   }
 
-  // Why: when the worktree is on WSL, env vars like ORCA_ROOT_PATH and
-  // ORCA_WORKTREE_PATH contain Windows UNC paths. The setup script runs
-  // inside WSL bash, so translate them to Linux paths.
+  // Why: setup script runs inside WSL bash, so translate the Windows UNC env-var paths to Linux paths.
   if (wslWorktree) {
     for (const key of Object.keys(envVars)) {
       envVars[key] = toLinuxPath(envVars[key])
@@ -587,16 +549,11 @@ export function runHook(
   const wslInfo = getHookWslContext(cwd, runtimeTarget)
 
   if (wslInfo) {
-    // Why: use execFile('wsl.exe', [...]) instead of exec() to bypass the
-    // Windows shell (cmd.exe). exec() always routes through a shell, and
-    // cmd.exe doesn't understand single-quote escaping — it would mangle
-    // paths/scripts containing %, ^, &, |, etc.
+    // Why: use execFile to bypass cmd.exe, which mangles single-quote escaping of %, ^, &, |, etc.
     const escapedCwd = wslInfo.linuxPath.replace(/'/g, "'\\''")
     const escapedScript = script.replace(/'/g, "'\\''")
     const bashCmd = `cd '${escapedCwd}' && ${escapedScript}`
-    // Why: translate ORCA_ROOT_PATH / ORCA_WORKTREE_PATH to Linux paths so
-    // hook scripts that reference $ORCA_WORKTREE_PATH get usable paths
-    // inside WSL, not Windows UNC paths.
+    // Why: hook scripts run inside WSL, so translate the ORCA_* Windows UNC paths to Linux paths.
     const envVars = getSetupEnvVars(repo, cwd)
     const wslEnv: Record<string, string> = {}
     for (const [key, value] of Object.entries(envVars)) {
@@ -632,8 +589,7 @@ export function runHook(
         }
       }
 
-      // Why: Node's execFile timeout only signals wsl.exe; if no callback
-      // arrives, hook setup/archive must still unblock after HOOK_TIMEOUT.
+      // Why: execFile's timeout only signals wsl.exe; force-unblock after HOOK_TIMEOUT if no callback arrives.
       const timeout = setTimeout(() => {
         child?.kill()
         finish(new Error(`Hook timed out after ${HOOK_TIMEOUT}ms.`))
@@ -672,11 +628,7 @@ export function runHook(
         cwd,
         timeout: HOOK_TIMEOUT,
         shell: getHookShell(),
-        // Why: setup/archive hooks run unattended, so a `git fetch`/`submodule
-        // update` inside one must never make Git Credential Manager pop its
-        // "Connect to GitHub" OAuth window on Windows and loop when the network
-        // can't complete it (issue #7652). The guard keeps the credential
-        // helper, so cached auth still works; only the interactive prompt dies.
+        // Why: hooks run unattended; block Git Credential Manager's interactive prompt while keeping cached auth (issue #7652).
         env: promptGuardShellEnv({
           ...process.env,
           ...getSetupEnvVars(repo, cwd)
diff --git a/src/main/index.ts b/src/main/index.ts
index 312b8bfd9cf..bcc3e13c59a 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: this is Orca's main-process entry point;
-   it owns app lifecycle, service wiring, window creation, and hook/daemon
-   startup. Splitting by line count would fragment tightly coupled startup
-   logic across files without a cleaner ownership seam. */
+/* eslint-disable max-lines -- main-process entry point; owns app lifecycle, service wiring, window creation, and hook/daemon startup with no cleaner split seam. */
 import { existsSync, statSync } from 'node:fs'
 import { isAbsolute, join } from 'node:path'
 import os from 'node:os'
@@ -214,9 +211,7 @@ import { reconcileManagedWslCliRegistrations } from './cli/wsl-cli-registration-
 import { selfHealRuntimeEnvironmentFocus } from './runtime-environment-focus-self-heal'
 
 let mainWindow: BrowserWindow | null = null
-/** Whether a manual app.quit() (Cmd+Q, etc.) is in progress. Shared with the
- *  window close handler so it can tell the renderer to skip the running-process
- *  confirmation dialog and proceed directly to buffer capture + close. */
+/** Whether a manual app.quit() (Cmd+Q) is in progress; lets the close handler skip the running-process confirmation and go straight to close. */
 let isQuitting = false
 let store: Store | null = null
 let stats: StatsCollector | null = null
@@ -232,8 +227,7 @@ let rateLimits: RateLimitService | null = null
 let runtimeRpc: OrcaRuntimeRpcServer | null = null
 let desktopRelayService: DesktopRelayService | null = null
 let desktopRelayStatus: RelayBrokerStatus = 'offline'
-// Why: set during early startup; gates whether headless serve installs the
-// offscreen browser backend (and thus advertises browser pane support).
+// Why: gates whether headless serve installs the offscreen browser backend (and advertises browser pane support).
 let headlessBrowserDisplayAvailable = false
 
 let starNag: StarNagService | null = null
@@ -245,23 +239,17 @@ let watcherShutdownPromise: Promise<void> | null = null
 let watcherShutdownDone = false
 let automations: AutomationService | null = null
 let keybindings: KeybindingService | null = null
-// Why: a reload/teardown intent set for one renderer must not leak to a later load.
-// The recovery reload re-fires did-finish-load, so its flag lets the local-PTY orphan
-// sweep spare live sessions across that one reload (#5787).
+// Why: a reload intent must not leak to a later load; the recovery reload re-fires did-finish-load, so its flag spares live PTYs from the orphan sweep (#5787).
 const expectedRendererReload = createWebContentsTimedFlag()
 const recoveryReloadInFlight = createWebContentsTimedFlag()
-// Why: a tray/menu-bar "Settings…" click can precede the renderer attaching
-// its ui:openSettings listener; the renderer pulls this one-shot on mount.
+// Why: a tray "Settings…" click can precede the renderer's ui:openSettings listener; it pulls this one-shot on mount.
 const pendingOpenSettings = createWebContentsTimedFlag()
 let firstWindowStartupServicesReady: Promise<void> = Promise.resolve()
 let managedWslCliReconciliationReady: Promise<void> = Promise.resolve()
 let managedWslCliStartupBarrierReady: Promise<void> = Promise.resolve()
-// Why: the serve barrier fails open at its budget, so headless clients need the
-// reconciliation state at ready time to know a WSL PTY launch may still race an
-// un-migrated registration. 'settled' covers the off-Windows no-op fast path.
+// Why: the serve barrier fails open, so this state tells headless clients a WSL PTY launch may still race an un-migrated registration ('settled' = off-Windows no-op).
 let managedWslCliReconciliationStatus: 'pending' | 'settled' | 'failed' = 'settled'
-// Why: GPU child crashes clustered right after launch indicate a broken driver;
-// track them so Orca can move this build onto software rendering.
+// Why: GPU child crashes clustered right after launch indicate a broken driver; track them to switch this build to software rendering.
 const gpuLaunchTimeMs = Date.now()
 const gpuCrashFallbackTracker = new GpuCrashFallbackTracker({
   windowMs: DEFAULT_GPU_CRASH_FALLBACK_WINDOW_MS,
@@ -282,10 +270,7 @@ const desktopActivationGate = createServeDesktopActivationGate({
   },
   onBlocked: (reason) => console.error(`[serve] Desktop activation blocked: ${reason}`)
 })
-// Why: on Windows a CLI-shaped launch (Orca.exe <unpacked CLI entry>) that lost
-// ELECTRON_RUN_AS_NODE would otherwise boot the GUI, lose the single-instance
-// lock to a running window, and exit silently. Redirect it to node mode here,
-// before the lock gate below can bounce it.
+// Why: on Windows a CLI launch that lost ELECTRON_RUN_AS_NODE would boot the GUI and exit silently; redirect to node mode before the lock gate below.
 const packagedCliEntryRedirect = maybeRedirectPackagedCliEntryLaunch({
   isPackaged: app.isPackaged,
   resourcesPath: process.resourcesPath,
@@ -303,14 +288,10 @@ if (appImageCliRedirect.redirected) {
   app.exit(appImageCliRedirect.status)
 }
 
-// Kill switch for the first-work on-disk folder rename. The renderer reconciles a
-// worktree id change via migrateWorktreeIdentity + a rename-aware worktrees:changed
-// handler, so an old->new id change is no longer mistaken for a deletion. Flip off
-// to disable the on-disk move (branch + display rename still happen) if needed.
+// Kill switch for the first-work on-disk folder rename; the renderer reconciles the id change (migrateWorktreeIdentity) so it isn't mistaken for a deletion.
 const ENABLE_FIRST_WORK_FOLDER_RENAME = false
 
-// Why: the store/runtime singletons live here in index.ts; injecting them keeps
-// the rename orchestrator free of module-level state and unit-testable.
+// Why: inject the index.ts store/runtime singletons so the rename orchestrator stays module-state-free and unit-testable.
 function maybeAutoRenameBranchOnFirstWorkFromHook(event: {
   paneKey: string
   tabId: string | undefined
@@ -362,8 +343,7 @@ function maybeAutoRenameBranchOnFirstWorkFromHook(event: {
       },
       canRenameOrcaCreatedBranch: (worktreeId) => {
         const meta = currentStore.getWorktreeMeta(worktreeId)
-        // Why: a user/imported branch can coincidentally be named after a creature.
-        // Only worktrees Orca stamped at creation are safe to auto-rename.
+        // Why: a user branch could coincidentally match a creature name; only Orca-stamped worktrees are safe to auto-rename.
         return !!meta?.orcaCreationSource && meta.preserveBranchOnDelete !== true
       },
       setDisplayName: (worktreeId, displayName) => {
@@ -381,8 +361,7 @@ function maybeAutoRenameBranchOnFirstWorkFromHook(event: {
         currentStore.setWorktreeMeta(worktreeId, {
           displayName,
           pendingFirstAgentMessageRename: false,
-          // Success always clears the failure badge, even if the explicit
-          // setRenameError(null) clear is redundant.
+          // Success clears the failure badge (redundant with the explicit setRenameError(null)).
           firstAgentMessageRenameError: null
         })
       },
@@ -400,11 +379,9 @@ function maybeAutoRenameBranchOnFirstWorkFromHook(event: {
             })
         : undefined,
       setRenameError: (worktreeId, error, failureOutput) => {
-        // Refresh the local-only full-output capture before the dedupe below:
-        // a repeat of the same error string still comes from a fresh run.
+        // Refresh the full-output capture before the dedupe below — a repeat error string is still a fresh run.
         rememberBranchRenameFailureOutput(worktreeId, error === null ? null : failureOutput)
-        // Skip the write + renderer push when nothing changes — benign skips
-        // clear the error on every settled worktree, most of which never had one.
+        // Skip the write + push when unchanged — most settled worktrees never had an error to clear.
         const scope = parseWorkspaceKey(worktreeId)
         if (scope?.type === 'folder') {
           const current = currentStore.getFolderWorkspace(
@@ -424,8 +401,7 @@ function maybeAutoRenameBranchOnFirstWorkFromHook(event: {
           return
         }
         currentStore.setWorktreeMeta(worktreeId, { firstAgentMessageRenameError: error })
-        // Push to the renderer so the badge updates — the hook only knows the
-        // worktreeId, so derive the repoId the same way notifyBranchRenamed expects.
+        // Why: the hook only knows the worktreeId, so derive the repoId notifyBranchRenamed expects.
         currentRuntime.notifyBranchRenamed(getRepoIdFromWorktreeId(worktreeId))
       },
       resolveWorktreeIdForTab: (tabId) => currentStore.getWorktreeIdForTab(tabId),
@@ -446,20 +422,10 @@ const devAgentHookEndpointNamespace = devInstanceIdentity.isDev
   : undefined
 
 installUncaughtPipeErrorGuard()
-// Why: propagate the Orca app version into `process.env` so PTY-env
-// construction in both main (local-pty-provider) and the forked daemon
-// (pty-subprocess) can set `TERM_PROGRAM_VERSION` without re-importing
-// electron. The daemon inherits `process.env` via fork (daemon-init.ts:93).
+// Why: expose the app version via process.env so main and the forked daemon can set TERM_PROGRAM_VERSION without importing electron.
 process.env.ORCA_APP_VERSION = app.getVersion()
 patchPackagedProcessPath()
-// Why: patchPackagedProcessPath seeds a minimal list of well-known system
-// dirs synchronously so early IPC (e.g. preflight before the shell spawn
-// completes) doesn't miss homebrew/nix. Kick off the login-shell probe in
-// parallel for packaged runs — when it resolves, its PATH is prepended and
-// detectInstalledAgents picks up whatever the user's rc files put on PATH
-// (cargo/pyenv/volta/custom tool install dirs) without hardcoding each one.
-// Dev runs already inherit a complete PATH from the launching terminal, so
-// the spawn cost is only paid where it's needed.
+// Why: the sync seed above covers early IPC (homebrew/nix); the async login-shell probe below (packaged only) then adds the user's rc PATH.
 if (app.isPackaged && process.platform !== 'win32') {
   void hydrateShellPath().then((result) => {
     if (result.ok) {
@@ -470,8 +436,7 @@ if (app.isPackaged && process.platform !== 'win32') {
 configureDevUserDataPath(is.dev)
 configureOrcaUserDataPathEnv()
 
-// Why: just past createMainWindow's 10s ready-to-show reveal fallback,
-// so a window revealed on that path still gets its tray icon.
+// Why: just past createMainWindow's 10s ready-to-show fallback, so a window revealed that way still gets its tray icon.
 const TRAY_CREATE_FALLBACK_MS = 12_000
 
 const startupDiagnosticsEnabled = isStartupDiagnosticsEnabled()
@@ -486,8 +451,7 @@ if (startupDiagnosticsEnabled) {
   })
   startEventLoopStallProbe()
 }
-// Self-gated on ORCA_MAIN_THREAD_DIAGNOSTICS; unlike the startup probe it
-// runs for the whole session to catch steady-state churn (issue #7576).
+// Self-gated on ORCA_MAIN_THREAD_DIAGNOSTICS; runs the whole session to catch steady-state churn (issue #7576).
 startMainThreadChurnProbe()
 
 function focusExistingWindow(): void {
@@ -516,9 +480,7 @@ function settleServeDesktopActivation(): void {
   desktopActivationGate.markReady()
 }
 
-// Why: a webContents-scoped flag that auto-expires so an intent set for one renderer
-// can't leak to a later load. `consume` clears on a positive match for one-shot
-// signals (the recovery reload fires exactly one did-finish-load).
+// Why: webContents-scoped auto-expiring flag so an intent can't leak to a later renderer load; `consume` clears on match for one-shot signals.
 function createWebContentsTimedFlag(defaultDurationMs = 10_000): {
   mark: (webContentsId: number, durationMs?: number) => void
   clear: (webContentsId?: number) => void
@@ -573,15 +535,12 @@ function markRecoveryReloadInFlight(webContentsId: number, durationMs = 10_000):
 }
 
 function isRecoveryReloadInFlight(webContentsId: number): boolean {
-  // Why: consume on read — the recovery reload fires exactly one did-finish-load,
-  // so a later genuine reload still sweeps orphaned local PTYs.
+  // Why: consume on read — the recovery reload fires exactly one did-finish-load, so a later genuine reload still sweeps orphaned PTYs.
   return recoveryReloadInFlight.matches(webContentsId, { consume: true })
 }
 
 function recordAgentStateCrashBreadcrumb(agentType: string, state: string): void {
-  // Why: hook pings can arrive many times per second while an agent works.
-  // Coalescing preserves crash-report room for renderer errors and memory
-  // samples instead of filling all 30 breadcrumbs with identical state pings.
+  // Why: hook pings arrive many times/sec; coalesce so identical state pings don't fill all 30 breadcrumbs, leaving room for renderer errors.
   recordCoalescedCrashBreadcrumb({
     name: 'agent_state_changed',
     data: { agentType, state },
@@ -590,18 +549,8 @@ function recordAgentStateCrashBreadcrumb(agentType: string, state: string): void
   })
 }
 
-// Why: the lock must be acquired AFTER configureDevUserDataPath — Electron
-// derives the lock identity from the `userData` path, so this placement lets
-// dev (`orca-dev`) and packaged (`orca`) runs lock in separate namespaces
-// instead of serialising against each other.
-//
-// Why skip in dev: engineers routinely run `pnpm dev` in parallel from
-// multiple worktrees while shipping features, and the lock makes the second
-// `pnpm dev` exit silently. In dev we accept that `orca-runtime.json` may race
-// (the bundled `orca-dev` CLI routes to whichever instance wrote last). Agent
-// hook endpoint files are namespaced per dev instance when the hook server
-// starts below. Packaged Orca keeps the lock to protect against the corruption
-// documented in PR #1326 / issue #1312.
+// Why: acquire AFTER configureDevUserDataPath — Electron derives lock identity from `userData`, so dev/packaged lock in separate namespaces.
+// Why skip in dev: parallel `pnpm dev` from multiple worktrees would make the second exit silently; packaged keeps the lock (corruption PR #1326 / #1312).
 const bypassSingleInstanceLock = shouldBypassSingleInstanceLock({
   isDev: is.dev,
   isServeMode
@@ -611,8 +560,7 @@ const skipSingleInstanceLock = shouldSkipSingleInstanceLock({
   isServeMode
 })
 if (bypassSingleInstanceLock) {
-  // Why: this is an explicit diagnostic escape hatch for macOS builds where
-  // Electron reports a false lock loss before any normal app logs exist.
+  // Why: diagnostic escape hatch for macOS builds where Electron reports a false lock loss before any app logs exist.
   logSingleInstanceLockBypass()
 }
 const hasSingleInstanceLock = skipSingleInstanceLock
@@ -628,39 +576,27 @@ if (startupDiagnosticsEnabled) {
   })
 }
 if (!hasSingleInstanceLock) {
-  // Why: if Electron returns a false negative here, packaged macOS launches
-  // otherwise look like silent crashes. `open --stderr` can capture this line.
+  // Why: a false-negative lock loss otherwise looks like a silent crash on packaged macOS; `open --stderr` can capture this line.
   logSingleInstanceLockFailure()
   app.quit()
 }
 
-// Why: when the lock is held by another process, we've already called
-// app.quit() above. Skip every remaining file-writing side effect so this
-// transient process never touches userData, and let handler registration
-// below happen — those handlers only fire after whenReady, which app.quit()
-// prevents from ever dispatching.
+// Why: when another process holds the lock we've already quit; skip file-writing side effects so this transient process never touches userData.
 if (hasSingleInstanceLock) {
-  // Why: dev parent shutdown coupling is only for electron-vite desktop runs.
-  // `orca serve` may be launched through a CLI shim or background shell whose
-  // parent lifetime is not the intended server lifetime.
+  // Why: couple to dev-parent only for electron-vite desktop runs; `orca serve`'s parent (CLI shim/background shell) isn't the intended server lifetime.
   const shouldCoupleToDevParent = is.dev && !isServeMode
   installDevParentDisconnectQuit(shouldCoupleToDevParent)
   installDevParentWatchdog(shouldCoupleToDevParent)
   installDevParentSignalQuit(shouldCoupleToDevParent)
-  // Why: must run after configureDevUserDataPath (which redirects userData to
-  // orca-dev in dev mode) but before app.setName('Orca') inside whenReady
-  // (which would change the resolved path on case-sensitive filesystems).
+  // Why: run after configureDevUserDataPath but before app.setName('Orca') (whenReady), which changes the resolved path on case-sensitive filesystems.
   initDataPath()
-  // Why: the parse cache file must live under the canonical userData path
-  // captured above — late app.getPath('userData') can resolve differently
-  // across restarts, silently defeating persistence (reused=0 forever).
+  // Why: use the canonical userData path — late app.getPath('userData') can resolve differently across restarts, defeating persistence.
   initSessionParseCachePersistence({
     filePath: join(getCanonicalUserDataPath(), 'ai-vault', 'session-parse-cache.json'),
     appVersion: app.getVersion()
   })
   initOrcaProfilePaths()
-  // Why: same timing constraint as initDataPath — capture the userData path
-  // before app.setName changes it. See persistence.ts:20-28.
+  // Why: same timing as initDataPath — capture userData before app.setName changes it. See persistence.ts:20-28.
   initStatsPath()
   initClaudeUsagePath()
   initCodexUsagePath()
@@ -677,20 +613,16 @@ if (hasSingleInstanceLock) {
   if (!gpuFallbackActiveThisLaunch) {
     enableMainProcessGpuFeatures()
   }
-  // Why: headless serve backs browser panes with offscreen BrowserWindows, which
-  // need an X display on Linux. Ensure one (Xvfb) before whenReady; the result
-  // gates whether the offscreen backend is installed so capability stays honest.
+  // Why: headless serve's offscreen BrowserWindows need an X display (Xvfb) on Linux; the result gates whether the offscreen backend is installed.
   headlessBrowserDisplayAvailable = ensureVirtualDisplayForHeadlessServe({ isServeMode })
 }
 
 ipcMain.handle('app:awaitFirstWindowStartupServices', async () => {
-  // Why: window rendering and local RPC startup stay independent, but restored
-  // WSL terminals get a bounded chance to receive launcher repairs first.
+  // Why: restored WSL terminals get a bounded chance to receive launcher repairs before window rendering proceeds.
   await Promise.all([firstWindowStartupServicesReady, managedWslCliStartupBarrierReady])
 })
 
-// Why: the renderer pulls this once its ui:openSettings listener is attached so
-// a tray/menu-bar Settings request queued before mount is not lost to a race.
+// Why: the renderer pulls this once its ui:openSettings listener attaches, so a Settings request queued before mount isn't lost.
 ipcMain.handle('ui:consumePendingOpenSettings', (event) =>
   pendingOpenSettings.matches(event.sender.id, { consume: true })
 )
@@ -708,15 +640,13 @@ ipcMain.handle(
 function startTerminalRuntimeStartupServices(): Promise<void> {
   logStartupMilestone('first-window-startup-services-start')
   const startupServices = startFirstWindowStartupServices({
-    // Why: desktop and headless serve must adopt the same persistent provider
-    // before either path is allowed to create terminals or a renderer.
+    // Why: both desktop and headless serve must adopt the same persistent provider before creating terminals or a renderer.
     startDaemonPtyProvider: async (signal) => {
       logStartupMilestone('startup-service-start', { service: 'daemon-pty-provider' })
       await initDaemonPtyProvider(signal)
       logStartupMilestone('startup-service-done', { service: 'daemon-pty-provider' })
     },
-    // Why: PTY spawn env reads ORCA_AGENT_HOOK_* from the live server state, so
-    // the renderer awaits this barrier before restored terminals reconnect.
+    // Why: PTY spawn env reads ORCA_AGENT_HOOK_* from live server state, so the renderer awaits this before restored terminals reconnect.
     startAgentHookServer: async () => {
       if (!isAgentStatusHooksEnabled(store?.getSettings())) {
         return
@@ -724,20 +654,14 @@ function startTerminalRuntimeStartupServices(): Promise<void> {
       logStartupMilestone('startup-service-start', { service: 'agent-hook-server' })
       await agentHookServer.start({
         env: app.isPackaged ? 'production' : 'development',
-        // Why: hooks source this endpoint file at invocation time, so old PTY
-        // env still reaches the current Orca process after an app restart.
-        // Dev uses a namespace because all worktrees share `orca-dev`.
+        // Why: hooks source this endpoint file at invocation time so old PTY env reaches the current process after restart; dev namespaces it (worktrees share `orca-dev`).
         userDataPath: app.getPath('userData'),
         endpointNamespace: devAgentHookEndpointNamespace
       })
       logStartupMilestone('startup-service-done', { service: 'agent-hook-server' })
     },
     onDaemonError: (error) => {
-      // Why: daemon startup failure silently dropped terminals onto the local
-      // provider (killed on quit, no persistence) — the v1.4.129-rc.1 outage was
-      // invisible in the field. Log loudly (error.message carries the captured
-      // daemon stderr tail from the fork) and emit a low-cardinality telemetry
-      // signal so a fleet-wide daemon failure is observable without a bug report.
+      // Why: daemon failure silently falls back to non-persistent local PTYs; log + telemetry so a fleet-wide outage is observable (was invisible in v1.4.129-rc.1).
       const reason = error instanceof Error ? error.message : String(error)
       console.error(
         `[daemon] STARTUP FAILED — falling back to local PTYs; terminals will not persist across quit. Reason: ${reason}`
@@ -745,8 +669,7 @@ function startTerminalRuntimeStartupServices(): Promise<void> {
       track('daemon_start_failed', classifyError(error))
     },
     onAgentHookServerError: (error) => {
-      // Why: Claude/Codex/Gemini/OpenCode/Cursor hook callbacks are sidebar
-      // enrichment only. Orca must still boot if the loopback receiver fails.
+      // Why: hook callbacks are sidebar enrichment only; Orca must still boot if the loopback receiver fails.
       console.error('[agent-hooks] Failed to start local hook server:', error)
     }
   })
@@ -773,8 +696,7 @@ function prepareCodexRuntimeHomeForLaunch(target?: CodexAccountSelectionTarget):
       : target
   const hooksEnabled = isAgentStatusHooksEnabled(store?.getSettings())
   try {
-    // Why: launch prep is reachable after startup via PTY/runtime paths; honor
-    // the persisted off switch so those launches cannot reinstall removed hooks.
+    // Why: honor the persisted off switch so post-startup launches can't reinstall removed hooks.
     const status = hooksEnabled
       ? (codexHookService.installForRuntimeHome(runtimeHomePath, hookTarget) ??
         codexHookService.install())
@@ -789,8 +711,7 @@ function prepareCodexRuntimeHomeForLaunch(target?: CodexAccountSelectionTarget):
       )
     }
   } catch (error) {
-    // Why: hook install/removal is best-effort launch prep. A malformed hooks file
-    // should not block the Codex process from starting with its prepared auth.
+    // Why: hook install is best-effort launch prep; a malformed hooks file must not block Codex from starting.
     console.warn(
       `[codex-hook-service] failed to ${
         hooksEnabled ? 'refresh' : 'refresh user'
@@ -801,9 +722,7 @@ function prepareCodexRuntimeHomeForLaunch(target?: CodexAccountSelectionTarget):
   return runtimeHomePath
 }
 
-// Why: tray "Open Orca" / left-click restores the window the close handler may
-// have hidden to the tray; if the window was fully torn down, reopen it the
-// same way macOS dock re-activation does (guarded against update relaunch).
+// Why: restore the window the close handler may have hidden to tray, or reopen it (dock-reactivation style) if fully torn down.
 function showMainWindowFromTray(): void {
   if (mainWindow && !mainWindow.isDestroyed()) {
     if (mainWindow.isMinimized()) {
@@ -826,30 +745,23 @@ function openSettingsFromSystemMenu(): void {
   }
   recordCrashBreadcrumb('settings_opened')
 
-  // Why: no main-side signal proves the renderer listener is attached, so push
-  // and leave a one-shot intent — a mounted renderer acts on the push, an
-  // unmounted one pulls the intent at mount; only one fires per renderer life.
+  // Why: no signal proves the renderer listener is attached — push, and also leave a one-shot intent the unmounted renderer pulls at mount.
   targetWindow.webContents.send('ui:openSettings')
-  // Why: leave an untimed intent — any TTL can be outrun by a slow cold start and
-  // would silently drop the Settings click. webContents-id scoping plus consume-on-
-  // read still prevents the intent from leaking to a later, unrelated renderer.
+  // Why: untimed — any TTL can be outrun by a slow cold start; id-scoping + consume-on-read still prevent leaking to a later renderer.
   pendingOpenSettings.mark(targetWindow.webContents.id, Number.POSITIVE_INFINITY)
 }
 
 function quitFromSystemTray(): void {
   if (mainWindow && !mainWindow.isDestroyed()) {
-    // Why: a real quit can still surface renderer save/discard prompts; the
-    // window must be visible if a hidden session vetoes shutdown.
+    // Why: a hidden session may veto shutdown with a save/discard prompt, so make the window visible.
     showMainWindowFromTray()
   }
-  // Why: set the quit latch before app.quit() so the window 'close' handler
-  // proceeds to teardown instead of re-hiding to the Windows tray.
+  // Why: set the quit latch before app.quit() so the 'close' handler tears down instead of re-hiding to tray.
   isQuitting = true
   app.quit()
 }
 
-// Why: a manual check must run against a configured updater; the menu and
-// tray are both clickable before anything else configures it.
+// Why: menu/tray are clickable before anything else configures the updater.
 function runUserInitiatedUpdateCheck(options?: UpdateCheckOptions): void {
   ensureAutoUpdaterConfigured()
   checkForUpdatesFromMenu(options)
@@ -866,8 +778,7 @@ function getSystemTrayOptions(): SystemTrayOptions | null {
     onOpen: showMainWindowFromTray,
     onOpenSettings: openSettingsFromSystemMenu,
     onCheckForUpdates: () => {
-      // Why: updater status renders in the main window; with every window
-      // closed a bare check would complete invisibly.
+      // Why: updater status renders in the main window, so a bare check would complete invisibly.
       showMainWindowFromTray()
       runUserInitiatedUpdateCheck()
     },
@@ -927,12 +838,7 @@ function openMainWindow(): BrowserWindow {
     throw new Error('Keybinding service must be initialized before opening the main window')
   }
 
-  // Why: Chromium's BrowserWindow constructor resets the userData DACL to a
-  // Protected DACL, breaking writes in pre-existing subdirs. Explicit ACEs on
-  // userData + immediate children fix the tree permanently; the grant runs in
-  // the background on first launch only (marker-gated) because the previous
-  // synchronous recursive walk blocked startup ~60s on large profiles. See
-  // startup/windows-user-data-acl.ts; per-write EPERM retries are the backstop.
+  // Why: Chromium's BrowserWindow ctor resets userData to a Protected DACL, breaking writes; re-grant ACEs (marker-gated to avoid a ~60s startup stall).
   if (process.platform === 'win32') {
     logStartupMilestone('acl-grant-start')
     ensureWindowsUserDataAclGrant(app.getPath('userData'), {
@@ -985,8 +891,7 @@ function openMainWindow(): BrowserWindow {
       }
       recordCrashBreadcrumb('manual_reload_requested', { ignoreCache })
     },
-    // Why: the in-place recovery reload re-fires did-finish-load; flag it so the
-    // local-PTY orphan sweep is skipped for that one reload (#5787).
+    // Why: the recovery reload re-fires did-finish-load; flag it so the local-PTY orphan sweep skips that reload (#5787).
     onBeforeRecoveryReload: (webContentsId) => {
       markRecoveryReloadInFlight(webContentsId)
       recordDurableCrashBreadcrumb('renderer_recovery_reload')
@@ -994,8 +899,7 @@ function openMainWindow(): BrowserWindow {
   })
   recordCrashBreadcrumb('main_window_created')
   logStartupMilestone('window-created')
-  // Why: Windows Tray construction can synchronously block on Shell_NotifyIcon,
-  // so both desktop status-item platforms defer creation to after first paint.
+  // Why: Windows Tray construction can block synchronously on Shell_NotifyIcon, so both platforms defer creation to after first paint.
   let trayCreated = false
   const createSystemTrayDeferred = (): void => {
     if (trayCreated || window.isDestroyed() || isQuitting || !store) {
@@ -1003,8 +907,7 @@ function openMainWindow(): BrowserWindow {
     }
     trayCreated = true
     if (process.platform === 'darwin') {
-      // Why: route through syncMacMenuBarIcon so startup and the live toggle
-      // share one serve-mode/visibility policy.
+      // Why: route through syncMacMenuBarIcon so startup and the live toggle share one serve-mode/visibility policy.
       if (syncMacMenuBarIcon(store.getSettings().showMenuBarIcon !== false)) {
         logStartupMilestone('tray-created')
       }
@@ -1022,10 +925,7 @@ function openMainWindow(): BrowserWindow {
   const trayCreateFallback = setTimeout(createSystemTrayDeferred, TRAY_CREATE_FALLBACK_MS)
   trayCreateFallback.unref?.()
 
-  // Why: telemetry-plan.md§First-launch experience anchors default-on
-  // `app_opened` to the first main-window load. Existing users in the
-  // pending-banner cohort resolve through telemetry/client.ts; this load
-  // path only fires once consent is already enabled.
+  // Why: telemetry-plan.md anchors default-on app_opened to the first main-window load; this path fires only once consent is already enabled.
   const rendererWebContentsId = window.webContents.id
   const onFirstWindowLoad = (): void => {
     clearExpectedRendererReload(rendererWebContentsId)
@@ -1090,17 +990,14 @@ function openMainWindow(): BrowserWindow {
         }
         recordCrashBreadcrumb('renderer_reload_requested', { ignoreCache })
       },
-      // Why: let the PTY layer skip its orphan sweep on the one recovery reload
-      // that re-fires did-finish-load, so live local sessions survive it (#5787).
+      // Why: let the PTY layer skip its orphan sweep on the recovery reload that re-fires did-finish-load, so live local sessions survive (#5787).
       isRecoveryReloadInFlight,
       onBeforeUpdateQuit: () =>
         preserveAgentAuthBeforeRestart({ codexRuntimeHome, claudeRuntimeAuth, store })
     }
   )
   rateLimits.attach(window)
-  // Why: quota probes can spawn CLIs and hit network. The attached show/focus
-  // listeners refresh as soon as the window can present quota UI, so do not
-  // compete with first paint.
+  // Why: quota probes spawn CLIs and hit network, so don't fetch immediately and compete with first paint; show/focus listeners refresh later.
   rateLimits.start({ fetchImmediately: false })
   window.on('closed', () => {
     if (mainWindow === window) {
@@ -1108,18 +1005,11 @@ function openMainWindow(): BrowserWindow {
     }
     clearExpectedRendererReload(rendererWebContentsId)
     automations?.setWebContents(null)
-    // Why: detach the agent hook listener on window close so the server
-    // never fires into a destroyed webContents during the gap before
-    // reopen (e.g. macOS dock re-activation). This also ensures the
-    // replay-loop through lastStatusByPaneKey runs only on deliberate
-    // window recreations instead of stacking on top of stale listeners.
+    // Why: detach the hook listener on close so the server never fires into destroyed webContents before reopen, and replay runs only on deliberate recreations.
     agentHookServer.setListener(null)
     agentHookServer.setPaneStatusClearListener(null)
     setMigrationUnsupportedPtyListener(null)
-    // Why: any running synthesized-title spinner timer would fire into a
-    // destroyed webContents; stop it here instead of deferring to per-pane
-    // teardown, which may never run for restored-but-never-torn-down panes
-    // when the window goes away.
+    // Why: stop the spinner timer here — it would fire into destroyed webContents, and per-pane teardown may never run for restored-but-untorn panes.
     stopAllSyntheticTitleSpinners()
   })
   mainWindow = window
@@ -1127,13 +1017,10 @@ function openMainWindow(): BrowserWindow {
   window.on('restore', resumeSyntheticTitleSpinnerTimer)
   window.on('hide', stopSyntheticTitleSpinnerTimer)
   window.on('minimize', stopSyntheticTitleSpinnerTimer)
-  // Why: visibility-gated main-process pollers (SSH port scanner) park while
-  // hidden and rely on this signal to resume; re-wired per window because
-  // macOS dock re-activation recreates the BrowserWindow.
+  // Why: visibility-gated pollers (SSH port scanner) park while hidden and resume on this signal; re-wired per window since dock re-activation recreates it.
   window.on('show', notifyMainWindowBecameVisible)
   window.on('restore', notifyMainWindowBecameVisible)
-  // Why: showing/restoring the window means the user is back, so clear the
-  // tray attention dot set while it was minimized/hidden (see notifications.ts).
+  // Why: user is back on show/restore, so clear the tray attention dot set while hidden (see notifications.ts).
   window.on('show', () => setTrayAttention(false))
   window.on('restore', () => setTrayAttention(false))
   agentHookServer.setListener(
@@ -1155,8 +1042,7 @@ function openMainWindow(): BrowserWindow {
         return
       }
       if (providerSessionOnly) {
-        // Why: session_start refreshes durable resume identity while Pi is
-        // idle; forward it without driving titles, telemetry, or status UI.
+        // Why: session_start just refreshes durable resume identity while Pi is idle; forward it without titles, telemetry, or status UI.
         mainWindow?.webContents.send('agentStatus:set', {
           ...payload,
           paneKey,
@@ -1189,8 +1075,7 @@ function openMainWindow(): BrowserWindow {
         ...(orchestration ? { orchestration } : {})
       })
       recordAgentStateCrashBreadcrumb(payload.agentType ?? 'unknown', payload.state)
-      // Why: some native OSC titles miss terminal idle/permission frames.
-      // Inject hook-derived frames so the renderer title tracker updates too.
+      // Why: native OSC titles miss some idle/permission frames, so inject hook-derived ones to keep the renderer title tracker in sync.
       const profile = getSyntheticAgentTitleProfile(payload.agentType)
       const suppressSyntheticCodexAutoApprovalTitle =
         payload.agentType === 'codex' &&
@@ -1251,9 +1136,7 @@ function sendOpenCrashReport(targetWindow?: BrowserWindow | null): void {
   webContents?.send('ui:openCrashReport')
 }
 
-// Why: when the renderer crash-loops, the breaker stops auto-reloading and the
-// window is left blank. The renderer is dead, so a main-process dialog is the
-// only surface that can offer a retry or a clean quit instead of a silent loop.
+// Why: on renderer crash-loop the breaker stops auto-reloading and the window goes blank, so a main-process dialog is the only retry/quit surface.
 async function presentRendererRecoveryPrompt(recentRecoveryCount: number): Promise<void> {
   if (isQuitting) {
     return
@@ -1296,9 +1179,7 @@ function getWindowsGpuFallbackEnvironment(): WindowsGpuFallbackEnvironment | nul
   return { ...environment, platform: 'win32' }
 }
 
-// Why: the GPU-fallback marker must be read before app.whenReady() resolves so
-// app.disableHardwareAcceleration() can take effect. Windows desktop only -
-// headless serve already runs software rendering on the platforms that need it.
+// Why: read the GPU-fallback marker before app.whenReady() so app.disableHardwareAcceleration() takes effect. Windows desktop only.
 function maybeApplyGpuFallbackForThisLaunch(): void {
   if (isServeMode || process.platform !== 'win32') {
     return
@@ -1315,9 +1196,7 @@ function maybeApplyGpuFallbackForThisLaunch(): void {
   })
 }
 
-// Why: a burst of crash-shaped Windows GPU child failures right after launch
-// means hardware acceleration is unusable on this machine. Persist a build-
-// scoped marker and relaunch into software rendering instead of looping crashes.
+// Why: a burst of GPU child crashes right after launch means HW acceleration is unusable — persist a build-scoped marker and relaunch into software rendering.
 function handleGpuChildCrash(reason: string, exitCode: number | null): void {
   // Software rendering already active or shutting down: nothing more to do.
   if (gpuFallbackActiveThisLaunch || isQuitting || isServeMode) {
@@ -1382,8 +1261,7 @@ function shutdownWatchersOnce(): Promise<void> {
     return Promise.resolve()
   }
   if (!watcherShutdownPromise) {
-    // Why: @parcel/watcher tears down native async work during unsubscribe.
-    // Electron must wait for that cleanup before Node's environment exits.
+    // Why: @parcel/watcher tears down native async work on unsubscribe; Electron must await it before Node's environment exits.
     watcherShutdownPromise = Promise.allSettled([
       closeAllWatchers(),
       disposeWorktreeBaseDirectoryWatchers()
@@ -1402,17 +1280,8 @@ function shutdownWatchersOnce(): Promise<void> {
   return watcherShutdownPromise
 }
 
-// Why: Pi-style persistent spinner — cursor-agent re-emits its own
-// "Cursor Agent" OSC title on every internal redraw, so a single synthesized
-// "⠋ Cursor Agent" frame gets silently overwritten in the renderer within
-// milliseconds and the sidebar dot snaps back to solid. Keep asserting a
-// fresh working frame on an interval until the hook reports a non-working
-// state. Interval matches Pi's 80ms cadence — fast enough for a smooth
-// spinner, slow enough to stay well under the per-flush IPC budget.
-// Why: opencode emits a single literal "OpenCode" title at startup and
-// nothing thereafter, so a one-shot working frame would suffice for it. We
-// reuse the same persistent-spinner mechanism rather than branching because
-// the animated spinner is also nicer UX (matches every other working agent).
+// Why: cursor-agent re-emits its own OSC title on every redraw, overwriting a one-shot frame — so re-assert a working frame on an interval.
+// 80ms matches Pi's cadence (smooth but under the IPC budget). opencode needs only one frame but reuses this for consistent animated UX.
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
 const SPINNER_INTERVAL_MS = 80
 
@@ -1525,8 +1394,7 @@ async function printServeReady(options: ServeOptions): Promise<void> {
         type: 'orca_server_ready',
         runtimeId: runtime.getRuntimeId(),
         endpoint,
-        // Why: the WSL reconciliation barrier fails open, so 'pending' warns clients
-        // it outlived the startup budget and a WSL PTY launch may still race a repair.
+        // Why: the WSL reconciliation barrier fails open, so 'pending' warns a WSL PTY launch may still race a repair.
         managedWslCliReconciliation: managedWslCliReconciliationStatus,
         pairing: pairing.available
           ? {
@@ -1556,18 +1424,14 @@ async function printServeReady(options: ServeOptions): Promise<void> {
 
 function installServeSignalHandlers(): void {
   const quit = (): void => {
-    // Why: foreground `orca serve` is controlled by the parent CLI/terminal,
-    // so POSIX termination signals should follow Electron's normal quit path
-    // and flush runtime metadata, daemon checkpoints, and telemetry.
+    // Why: route SIGINT/SIGTERM through Electron's normal quit so runtime metadata, daemon checkpoints, and telemetry flush.
     app.quit()
   }
   process.once('SIGINT', quit)
   process.once('SIGTERM', quit)
 }
 
-// Why: on PTY teardown the paneKey mapping is dropped, so the spinner tick
-// would keep firing but sendSyntheticTitle would no-op forever. Drop the
-// entry explicitly so the shared timer shuts down once no panes are active.
+// Why: on PTY teardown drop the spinner entry explicitly, else the shared timer keeps ticking with sendSyntheticTitle no-oping forever.
 registerPaneKeyTeardownListener((paneKey) => {
   stopSyntheticTitleSpinner(paneKey)
 })
@@ -1576,8 +1440,7 @@ function sendSyntheticTitle(ptyId: string, data: string, options: { force?: bool
   if (!mainWindow || mainWindow.isDestroyed()) {
     return
   }
-  // Why: repeated working-spinner frames are decorative and can arrive every
-  // 80ms per agent. Final/permission frames are forced because they drive BEL.
+  // Why: throttle decorative spinner frames (up to 80ms/agent); final/permission frames are forced because they drive BEL.
   if (
     !shouldSendSyntheticTitleFrame({
       force: options.force === true,
@@ -1586,14 +1449,9 @@ function sendSyntheticTitle(ptyId: string, data: string, options: { force?: bool
   ) {
     return
   }
-  // Why: feed the per-PTY tracker directly (never onPtyData — emulator state,
-  // tails, transcripts, and stats must not see fabricated bytes) so synthetic
-  // titles/BELs reach pty:sideEffect consumers when main holds side-effect
-  // authority.
+  // Why: feed the per-PTY tracker directly, never onPtyData — emulator/tails/transcripts/stats must not see fabricated bytes.
   runtime?.ingestSyntheticTitleFrame(ptyId, data)
-  // Why: only the kill-switch-off renderer still byte-parses synthetic frames;
-  // under main authority the copy would just mint phantom ACKs for unmetered
-  // bytes (see synthetic-title-frame-routing.ts).
+  // Why: only the kill-switch-off renderer byte-parses synthetic frames; under main authority the copy mints phantom ACKs (see synthetic-title-frame-routing.ts).
   if (shouldCopySyntheticTitleFrameToPtyData(store?.getSettings())) {
     mainWindow.webContents.send('pty:data', { id: ptyId, data })
   }
@@ -1667,8 +1525,7 @@ function ensureSyntheticTitleSpinnerTimer(): void {
   ) {
     return
   }
-  // Why: a single process timer covers all synthesized title spinners; per-pane
-  // intervals multiplied idle wakeups when several retained agents were working.
+  // Why: one shared timer for all spinners — per-pane intervals multiplied idle wakeups when several agents were working.
   syntheticTitleSpinnerTimer = setInterval(tickSyntheticTitleSpinners, SPINNER_INTERVAL_MS)
 }
 
@@ -1686,16 +1543,12 @@ function driveSyntheticTitleFromHook(
     return
   }
   if (state === 'working') {
-    // Why: immediately emit the first frame so the spinner starts visible at
-    // this hook event even if the interval's next tick is 80ms away. Subsequent
-    // frames come from the interval below.
+    // Why: emit the first frame immediately so the spinner is visible now, not up to 80ms later at the next interval tick.
     const existing = syntheticTitleSpinnerByPaneKey.get(paneKey)
     const frame = existing ? existing.frame : 0
     sendSyntheticTitle(ptyId, `\x1b]0;${SPINNER_FRAMES[frame]} ${profile.workingLabel}\x07`)
     if (existing) {
-      // Why: refresh the profile so an agent-type change mid-pane (rare, but
-      // possible if a hook reports a different agentType than the previous
-      // event) lands on the right idle/permission labels at terminal state.
+      // Why: refresh the profile so a mid-pane agent-type change lands on the right idle/permission labels at terminal state.
       existing.profile = profile
       return
     }
@@ -1703,16 +1556,8 @@ function driveSyntheticTitleFromHook(
     ensureSyntheticTitleSpinnerTimer()
     return
   }
-  // Why: leaving the spinner running after a `blocked`/`waiting`/`done` event
-  // would immediately race the terminal state back to "working" on the next
-  // tick. Stop first, then inject the terminal frame. Idle/done uses a
-  // decorated "<Agent> ready" label rather than the bare native title — which
-  // for cursor the detector deliberately treats as a no-op so cursor's own
-  // per-turn re-emissions cannot clobber our synthesized state. The
-  // Permission frames also carry a trailing BEL (0x07 outside of any OSC
-  // sequence) so user-input-required states light up immediately. Done frames
-  // intentionally avoid the extra BEL: hook/status completion notifications
-  // own final-task attention and can cancel milestone noise during loops.
+  // Why: stop the spinner first so the next tick can't race the state back to "working", then inject the terminal frame.
+  // Permission frames add a trailing BEL to light up user-input states; done frames omit it (completion notifications own that attention).
   stopSyntheticTitleSpinner(paneKey)
   const needsUserInput = state === 'blocked' || state === 'waiting'
   const label = needsUserInput ? profile.permissionLabel : profile.idleLabel
@@ -1749,8 +1594,7 @@ function shouldSuppressCodexAutoApprovalSyntheticTitleFromHook(args: {
 
 app.whenReady().then(async () => {
   logStartupMilestone('app-ready')
-  // Why: certificate decisions must be installed before either desktop
-  // webviews or headless browser windows can issue their first TLS request.
+  // Why: install certificate decisions before any webview or headless window issues its first TLS request.
   app.on(
     'certificate-error',
     (event, webContents, url, error, certificate, callback, isMainFrame) => {
@@ -1766,14 +1610,10 @@ app.whenReady().then(async () => {
     }
   )
   electronApp.setAppUserModelId(devInstanceIdentity.appUserModelId)
-  // Why: setName drives the macOS safeStorage Keychain item name. Use the stable
-  // appName (not the per-branch `name`) so dev branches share one key and don't
-  // re-prompt per branch; the per-branch label still shows via window title,
-  // renderer identity, and the app-menu label passed to registerAppMenu below.
+  // Why: setName drives the macOS safeStorage Keychain item name; use the stable appName (not per-branch `name`) so dev branches share one key and don't re-prompt.
   app.setName(devInstanceIdentity.appName)
 
-  // Why: managed WSL launchers live outside the Windows app bundle, so keep
-  // their launcher and bridge contract synchronized across app updates.
+  // Why: managed WSL launchers live outside the Windows app bundle, so keep their launcher/bridge contract synced across app updates.
   managedWslCliReconciliationStatus = 'pending'
   managedWslCliReconciliationReady = reconcileManagedWslCliRegistrations({
     isPackaged: app.isPackaged,
@@ -1808,15 +1648,11 @@ app.whenReady().then(async () => {
   logStartupMilestone('store-loaded')
   store.onSettingsChanged((updates, settings) => {
     if ('showMenuBarIcon' in updates) {
-      // Why: Store is the mutation authority for renderer, RPC, and future
-      // settings writes, so every macOS toggle updates the native item live.
+      // Why: Store is the mutation authority for all settings writes, so every macOS toggle updates the native item live.
       syncMacMenuBarIcon(settings.showMenuBarIcon !== false)
     }
   })
-  // Why: must run before ClaudeRuntimeAuthService's constructor sync — a Claude
-  // CLI that survived the restart inside the daemon still holds the current
-  // single-use refresh token, and an unguarded early refresh would rotate it
-  // out from under that process (it then shows "Not logged in" mid-session).
+  // Why: run before ClaudeRuntimeAuthService's constructor sync — a surviving daemon Claude CLI holds the single-use refresh token; early refresh rotates it out mid-session.
   attachClaudeLivePtyPersistence(store)
   const persistedClaudePtyIds = store.getClaudeLivePtySessionIds()
   seedLiveClaudePtysFromPersistence(persistedClaudePtyIds)
@@ -1831,14 +1667,12 @@ app.whenReady().then(async () => {
     suppressDevEducationForStore(store)
   }
   try {
-    // Why: Dock/Launchpad launches do not inherit shell proxy env vars, so the
-    // persisted proxy must be applied before any app-owned network fetchers run.
+    // Why: Dock/Launchpad launches don't inherit shell proxy env vars, so apply the persisted proxy before any app-owned network fetchers run.
     await applyElectronProxySettings(store.getSettings())
   } catch {
     console.warn('[proxy] Failed to apply network proxy settings')
   }
-  // Why: browser sessions are used by desktop webviews and runtime profile
-  // commands, so initialize them at app startup instead of a renderer IPC path.
+  // Why: browser sessions serve desktop webviews and runtime profile commands, so init at app startup rather than via a renderer IPC path.
   initializeBrowserSessionsForApp({
     orcaProfileId: activeOrcaProfile.profile.id,
     profileDirectory: activeOrcaProfile.profileDirectory
@@ -1846,37 +1680,20 @@ app.whenReady().then(async () => {
   unsubscribeSystemResumeBroadcast = registerSystemResumeBroadcast()
   agentAwakeService = new AgentAwakeService()
   agentAwakeService.setEnabled(store.getSettings().keepComputerAwakeWhileAgentsRun)
-  // Why: disk-hydrated status rows are UI continuity only. The service starts
-  // from an empty snapshot; only hook events observed in this runtime can keep
-  // the local computer awake.
+  // Why: start from empty — disk-hydrated status rows are UI continuity only; only this runtime's hook events keep the computer awake.
   agentAwakeService.setStatuses([])
   unsubscribeAgentAwakeStatusChanges = agentHookServer.subscribeStatusChanges((statuses) => {
     agentAwakeService?.setStatuses(statuses)
   })
-  // Why: telemetry must initialize before any IPC handler / renderer can
-  // call `track()`. The client is a no-op in dev/contributor builds
-  // (`IS_OFFICIAL_BUILD === false`) and a no-op while `TELEMETRY_ENABLED`
-  // is false in PR 2 — so this call is safe to run early; it only records
-  // the Store reference, seeds common props, and resets per-session burst
-  // caps. Actual transport initialization is still gated by both flags.
+  // Why: telemetry must init before any IPC handler/renderer can call track(); it's a no-op in dev and while TELEMETRY_ENABLED is false, so it's safe early.
   initTelemetry(store)
-  // Why: the error-tracking lane (telemetry-error-tracking.md) is its own
-  // composition root — independent of product telemetry — and must
-  // initialize before any IPC handler / runtime span is created so the
-  // tracer's active sink is populated at the moment the first span fires.
-  // Honors DO_NOT_TRACK / ORCA_TELEMETRY_DISABLED / ORCA_DIAGNOSTICS_DISABLED
-  // / CI internally; those gates do not need to be re-checked here.
+  // Why: the error-tracking lane (telemetry-error-tracking.md) is its own root and must init before any span is created so the tracer's sink is populated first.
   initObservability()
   recordDurableCrashBreadcrumb('main_process_lifecycle_started', {
     packaged: app.isPackaged,
     platform: process.platform
   })
-  // Why: cohort-classifier reads the repo count synchronously at every emit
-  // for cohort-extended events. The Store has been sync-loaded above, and
-  // this init runs before any IPC handler is registered and before any
-  // window loads — so the classifier is hydrated before any `track()` call,
-  // regardless of whether it originates from the renderer, an IPC handler,
-  // or `trackAppOpenedOnce` / `did-finish-load`.
+  // Why: cohort-classifier reads repo count synchronously at every emit, so hydrate it here — before any IPC handler or window can trigger track().
   initCohortClassifier(store)
   initOnboardingCohortClassifier(store)
   stats = new StatsCollector()
@@ -1955,34 +1772,25 @@ app.whenReady().then(async () => {
       .map((account) => ({ id: account.id, managedHomePath: account.managedHomePath }))
   })
   const runtimeService = new OrcaRuntimeService(store, stats, {
-    // Why: resolve the PTY provider lazily. initDaemonPtyProvider() runs later
-    // inside attachMainWindowServices and calls setLocalPtyProvider(routedAdapter)
-    // to swap the in-process provider for the daemon-routed one. Capturing the
-    // provider reference eagerly here would freeze the pre-daemon LocalPtyProvider
-    // and defeat the teardown helper's prefix sweep (design §4.3 wire-up).
+    // Why: resolve the PTY provider lazily — a daemon swap happens later, so an eager reference would freeze the pre-daemon provider (design §4.3).
     getLocalProvider: () => getLocalPtyProvider(),
-    // Why: SSH relay providers are registered after runtime construction and
-    // may reconnect; destructive cleanup must resolve the current generation.
+    // Why: SSH relay providers register after construction and may reconnect, so destructive cleanup must resolve the current generation.
     getSshProvider: (connectionId) => getSshPtyProvider(connectionId),
     onPtyStopped: clearProviderPtyState,
     onTerminalAgentStatus: (event) => {
       agentHookServer.ingestTerminalStatus(event)
     },
-    // Why: serve can be promoted in place, so keep the listener wired from
-    // startup; runtime enables desktop-only scanners only for a ready renderer.
+    // Why: serve can be promoted in place, so wire the listener from startup; runtime enables desktop-only scanners only for a ready renderer.
     onTerminalSideEffects: (batch: TerminalSideEffectBatch) => {
       if (mainWindow && !mainWindow.isDestroyed()) {
         mainWindow.webContents.send('pty:sideEffect', batch)
       }
     },
     getDesktopWindowStatus: getDesktopWindowStatus,
-    // Why: hook-reported agent status is the same source the desktop sidebar
-    // reads. worktree.ps pulls it at query time so mobile shows the same agents.
+    // Why: worktree.ps pulls hook-reported agent status (same source as the desktop sidebar) at query time so mobile shows the same agents.
     getAgentStatusSnapshot: () =>
       agentHookServer.getStatusSnapshot().filter((entry) => entry.providerSessionOnly !== true),
-    // Why: source codex-home here (runs in BOTH window and serve modes) so the
-    // aiVault.listSessions RPC includes managed-Codex sessions on remote/SSH
-    // hosts; the window-only registerCoreHandlers path never runs under serve.
+    // Why: source codex-home here (runs in window AND serve) so aiVault.listSessions includes managed-Codex sessions; registerCoreHandlers is window-only.
     getAdditionalAiVaultCodexHomePaths: () =>
       codexRuntimeHome ? [codexRuntimeHome.getHostRuntimeHomePath()] : [],
     buildAgentHookPtyEnv: () =>
@@ -1995,8 +1803,7 @@ app.whenReady().then(async () => {
   automations = new AutomationService(store, {
     claudeUsage,
     codexUsage,
-    // Why: desktop clients may mirror remote-host automations, but only a
-    // server process should execute schedules owned by `remote_host_service`.
+    // Why: desktop clients mirror remote-host automations, but only a server process should execute remote_host_service-owned schedules.
     allowRemoteHostScheduling: isServeMode,
     headlessDispatcher: isServeMode
       ? async ({ automation, run, target }) => {
@@ -2088,9 +1895,7 @@ app.whenReady().then(async () => {
   runtimeService.setAutomationService(automations)
   runtimeService.setAccountServices({ claudeAccounts, codexAccounts, rateLimits })
   runtimeService.setCommitMessageAgentEnvironmentResolvers({
-    // Why: local Codex hooks and auth now live in Orca's managed runtime home
-    // even for the system-default path, so every Orca-launched Codex process
-    // must resolve CODEX_HOME through the runtime-home service.
+    // Why: Codex hooks/auth live in Orca's managed runtime home even for the default path, so every launch must resolve CODEX_HOME via runtime-home.
     prepareForCodexLaunch: prepareCodexRuntimeHomeForLaunch,
     prepareForClaudeLaunch: (target) => claudeRuntimeAuth!.prepareForClaudeLaunch(target)
   })
@@ -2104,14 +1909,12 @@ app.whenReady().then(async () => {
   )
 
   // Emulator bridge (serve-sim). macOS-only feature (gated in CLI/runtime); always ship like agent-browser.
-  // Why: only Orca-managed or explicitly attached helpers belong to a workspace;
-  // externally started serve-sim processes must remain independent from Orca.
+  // Why: externally started serve-sim processes must stay independent — only Orca-managed/attached helpers belong to a workspace.
   const emulatorBridge = new EmulatorBridge()
   runtimeService.setEmulatorBridge(emulatorBridge)
   nativeTheme.themeSource = store.getSettings().theme ?? 'system'
   if (shouldInstallManagedHooks(is.dev)) {
-    // Why: the persisted off switch must run before any auto-install path so
-    // users who removed Orca-managed hooks do not see them silently reappear on launch.
+    // Why: check the persisted off switch before any auto-install so removed hooks don't silently reappear on launch.
     if (isAgentStatusHooksEnabled(store.getSettings())) {
       runManagedHookInstallers(MANAGED_AGENT_HOOK_INSTALLERS)
     } else {
@@ -2163,9 +1966,7 @@ app.whenReady().then(async () => {
     },
     onOpenFeatureTour: (targetWindow) => {
       recordCrashBreadcrumb('feature_tour_opened')
-      // Why: menu clicks provide the BrowserWindow that invoked the item. Use it
-      // first so hidden/headless E2E windows and future multi-window flows route
-      // the tour to the correct renderer instead of relying on global focus.
+      // Why: use the invoking BrowserWindow so hidden/E2E and multi-window flows route to the right renderer, not global focus.
       const targetBrowserWindow = targetWindow instanceof BrowserWindow ? targetWindow : null
       sendOpenFeatureTour(targetBrowserWindow)
     },
@@ -2189,16 +1990,12 @@ app.whenReady().then(async () => {
         return
       }
       if (key === 'statusBarVisible') {
-        // Why: status bar visibility lives under the persisted UI state
-        // (ui:set/ui:get), not settings. The renderer owns the authoritative
-        // toggle logic (it knows the current value and persists it back), so
-        // we forward the event and let it flip + store.
+        // Why: status bar visibility lives in persisted UI state (not settings) and the renderer owns the toggle — forward the event, let it flip + store.
         mainWindow?.webContents.send('ui:toggleStatusBar')
         return
       }
       const current = store.getSettings()
-      // Why: these appearance settings are default-on for older profiles, so
-      // a missing persisted value must toggle from visible -> hidden.
+      // Why: these appearance settings are default-on, so a missing persisted value must toggle from visible -> hidden.
       const next = getNextDefaultOnAppearanceSettingValue(current[key])
       store.updateSettings({ [key]: next }, { notifyListeners: true })
       rebuildAppMenu()
@@ -2216,19 +2013,9 @@ app.whenReady().then(async () => {
     },
     getKeybindings: () => keybindings?.getOverrides()
   })
-  // Why: E2E tests launch parallel Electron instances that would all race to
-  // bind the default fixed port, crashing on EADDRINUSE. Port 0 lets the OS
-  // assign a random available port per instance while still exercising the
-  // full WebSocket startup path.
+  // Why: parallel E2E Electron instances would race the fixed port (EADDRINUSE); port 0 gives each a random OS-assigned port.
   const isE2E = Boolean(process.env.ORCA_E2E_USER_DATA_DIR)
-  // Why: a developer running `pnpm dev` while the packaged Orca is also open
-  // would otherwise race the packaged app for 6768 and silently fall back to
-  // a random OS-assigned port — breaking deterministic mobile pairing/repro
-  // scripts against the dev instance. Pin the first dev instance to 6769 so
-  // ws://127.0.0.1:6769 is stable; a second dev instance still falls back via
-  // ws-transport's EADDRINUSE handler. Note: once an instance has ever fallen
-  // back, the persisted fallback port is re-bound in preference to 6769
-  // (STA-1511) until mobile-ws-fallback-port.json is removed from userData.
+  // Why: pin dev to 6769 so `pnpm dev` doesn't race packaged Orca on 6768 and fall back to a random port, breaking deterministic mobile pairing/repro (STA-1511).
   const devWsPort = is.dev && !isE2E ? 6769 : undefined
   let serveOptions: ServeOptions | null = null
   try {
@@ -2238,16 +2025,11 @@ app.whenReady().then(async () => {
     app.exit(1)
     return
   }
-  // Why: existing installs may have already written mobile pairing credentials
-  // under the late app.getPath('userData') directory. Copy any missing files
-  // forward before the runtime switches exclusively to the canonical path.
+  // Why: existing installs may have pairing creds under the late app.getPath('userData'); copy them forward before switching to the canonical path.
   migrateMobilePairingDataToCanonicalUserDataPath(app.getPath('userData'))
   runtimeRpc = new OrcaRuntimeRpcServer({
     runtime,
-    // Why: mobile pairing (DeviceRegistry + E2EE keypair + runtime metadata)
-    // must share the stable path captured before app.setName(), not a late
-    // app.getPath('userData') that resolves elsewhere and drops paired devices
-    // across restarts/updates. See persistence.ts:getCanonicalUserDataPath.
+    // Why: mobile pairing needs the stable pre-setName() path (getCanonicalUserDataPath), not a late app.getPath('userData') that drops paired devices across restarts.
     userDataPath: getCanonicalUserDataPath(),
     enableWebSocket: true,
     ...(isE2E ? { wsPort: 0 } : {}),
@@ -2255,9 +2037,7 @@ app.whenReady().then(async () => {
     ...(serveOptions?.wsPort !== undefined
       ? {
           wsPort: serveOptions.wsPort,
-          // Why: only an explicit `orca serve --port` pin prefers the requested
-          // port over a stale STA-1511 fallback (issue #8535). Default 6768 /
-          // dev 6769 keep fallback-first so mobile pairings stay stable.
+          // Why: only explicit `orca serve --port` overrides a stale STA-1511 fallback (issue #8535); default/dev stay fallback-first for pairing stability.
           preferPinnedWsPort: true
         }
       : {}),
@@ -2269,15 +2049,13 @@ app.whenReady().then(async () => {
   app.on('activate', requestDesktopActivation)
 
   if (serveOptions) {
-    // Why: give managed WSL launchers a brief chance to migrate before headless
-    // PTYs become reachable without letting slow repairs withhold all RPC readiness.
+    // Why: give managed WSL launchers a brief chance to migrate before headless PTYs go live, without slow repairs withholding all RPC readiness.
     logStartupMilestone('wsl-cli-barrier-start')
     await managedWslCliStartupBarrierReady
     logStartupMilestone('wsl-cli-barrier-resolved', {
       reconciliation: managedWslCliReconciliationStatus
     })
-    // Why: headless PTYs must never start on the fallback provider and then be
-    // swept when an activated renderer registers desktop lifecycle handlers.
+    // Why: headless PTYs must not start on the fallback provider, then get swept when an activated renderer registers desktop lifecycle handlers.
     await localPtyStartupReady
     registerHeadlessPtyRuntime(
       runtime,
@@ -2286,16 +2064,11 @@ app.whenReady().then(async () => {
       (target) => claudeRuntimeAuth!.prepareForClaudeLaunch(target),
       store
     )
-    // Why: headless servers have no renderer to mount <webview> browser panes.
-    // Back them with main-process offscreen WebContents instead, so this host can
-    // own browser pages and advertise browser.headless.v1 — but only when a
-    // display is actually available (set up above), so the capability stays honest.
+    // Why: headless servers can't mount <webview> panes; use offscreen WebContents, gated on a real display so browser.headless.v1 stays honest.
     if (headlessBrowserDisplayAvailable) {
       runtime.setOffscreenBrowserBackend(new OffscreenBrowserBackend(browserManager))
     }
-    // Why: headless servers have no renderer graph publisher. Publish an
-    // explicit empty graph so status clients see a ready server while
-    // renderer-only operations still fail at their own window boundary.
+    // Why: headless servers have no renderer graph publisher; publish an explicit empty graph so status clients see a ready server.
     runtime.syncWindowGraph(HEADLESS_RUNTIME_WINDOW_ID, { tabs: [], leaves: [] })
     await runtimeRpc.start().catch((error) => {
       console.error('[runtime] Failed to start headless RPC transport:', error)
@@ -2303,20 +2076,10 @@ app.whenReady().then(async () => {
     })
     settleServeDesktopActivation()
     installServeSignalHandlers()
-    // Why: the orca CLI command is normally installed by the renderer onboarding /
-    // Settings "Install CLI" flow via the cli:install IPC. Headless serve has no
-    // renderer, so the command is never created and an in-terminal `orca …` fails
-    // with command-not-found. Run the idempotent installer here for the platforms
-    // where it puts a resolvable command on the managed-terminal PATH: macOS (bare
-    // `orca` in /usr/local/bin or ~/.local/bin) and Linux (`orca-ide`; bare `orca`
-    // is added by the dispatcher below). Windows is excluded — there install() would
-    // only mutate the persistent user-registry PATH without helping the current
-    // serve's child terminals. Best-effort: a failure must not block serve start.
+    // Why: headless serve has no renderer to run the normal cli:install flow; do it here for macOS/Linux only (Windows-excluded: install() only mutates registry PATH, not child terminals).
     if (process.platform === 'darwin' || process.platform === 'linux') {
       try {
-        // Why: serve is headless — never let a missing-write-permission fallback
-        // pop an osascript admin prompt (it would hang serve on a GUI host). Skip
-        // instead; the user-writable ~/.local/bin path needs no elevation anyway.
+        // Why: serve is headless — a fallback osascript admin prompt would hang it; skip elevation since ~/.local/bin needs none.
         const cliStatus = await new CliInstaller({
           privilegedRunner: async () => {
             throw new Error('serve CLI auto-install must not request administrator privileges')
@@ -2332,11 +2095,7 @@ app.whenReady().then(async () => {
         )
       }
     }
-    // Why: on Linux the CLI installs as `orca-ide`, NOT bare `orca` (above), but the
-    // Claude Team launcher typed into the initial managed terminal invokes bare `orca`.
-    // Drop a bare-`orca` dispatcher on ~/.local/bin (ahead of /usr/bin on the managed
-    // terminal PATH) so `orca claude-teams` resolves. Best-effort: a failure must not
-    // block serve startup. See installLinuxBareOrcaDispatcher for the full rationale.
+    // Why: Linux CLI installs as `orca-ide`, but the Claude Team launcher invokes bare `orca`; drop a ~/.local/bin dispatcher (ahead of /usr/bin) so it resolves. Best-effort.
     if (process.platform === 'linux' && app.isPackaged && process.resourcesPath) {
       try {
         const dispatcher = await installLinuxBareOrcaDispatcher({
@@ -2359,9 +2118,7 @@ app.whenReady().then(async () => {
     return
   }
 
-  // Why: window creation and runtime RPC startup are independent. Local PTY
-  // spawns are gated inside registerPtyHandlers so RPC can bind immediately
-  // without racing the daemon provider swap.
+  // Why: window and RPC startup run in parallel; registerPtyHandlers gates PTY spawns so RPC binds without racing the daemon provider swap.
   const [win] = await Promise.all([
     Promise.resolve(openMainWindow()),
     runtimeRpc.start().catch((error) => {
@@ -2399,13 +2156,9 @@ app.whenReady().then(async () => {
     }
   }
 
-  // Why: the macOS notification permission dialog must fire after the window
-  // is visible and focused. If it fires before the window exists, the system
-  // dialog either doesn't appear or gets immediately covered by the maximized
-  // window, making it impossible for the user to click "Allow".
+  // Why: macOS notification permission dialog must fire after the window is shown, else it's hidden behind the maximized window.
   win.once('show', () => {
-    // Why: store can be null if init failed earlier; bail rather than risk a
-    // throw inside an Electron event listener.
+    // Why: store can be null if init failed earlier; bail rather than throw inside an Electron event listener.
     if (!store) {
       return
     }
@@ -2431,18 +2184,11 @@ app.on('before-quit', () => {
   unsubscribeAgentAwakeStatusChanges = null
   agentAwakeService?.dispose()
   agentAwakeService = null
-  // Why: PTY cleanup is deferred to will-quit so the renderer has a chance to
-  // capture terminal scrollback buffers before PTY exit events race in and
-  // unmount TerminalPane components (removing their capture callbacks).
-  // The window close handler passes isQuitting to the renderer so it skips the
-  // child-process confirmation dialog and proceeds directly to buffer capture.
+  // Why: defer PTY cleanup to will-quit so the renderer captures scrollback before PTY-exit events unmount TerminalPane (dropping its capture callbacks).
   rateLimits?.stop()
 })
 
-// Why: will-quit fires twice when daemon disconnect needs an async flush.
-// First pass: run all sync cleanup, then preventDefault to await the final
-// checkpoint writes. Second pass (after disconnect resolves): skip the
-// async work and let Electron exit.
+// Why: will-quit fires twice — first pass runs sync cleanup + preventDefault to await checkpoint writes; second pass exits.
 let daemonDisconnectDone = false
 app.on('will-quit', (e) => {
   const updateQuitInProgress = isQuittingForUpdate()
@@ -2453,27 +2199,19 @@ app.on('will-quit', (e) => {
       { message: 'will-quit cleanup for update install; daemonTeardown=disconnect' }
     )
   }
-  // Why: before-quit can still be aborted by renderer beforeunload; wait until
-  // the committed quit path before removing the Windows notification icon.
+  // Why: before-quit can still be aborted by renderer beforeunload; only remove the Windows tray icon on the committed quit path.
   destroySystemTray()
-  // Why: stats.flush() must run before killAllPty() so it can read the
-  // live agent state and emit synthetic agent_stop events for agents that
-  // are still running. killAllPty() does not call runtime.onPtyExit(),
-  // so without this ordering, running agents would produce orphaned
-  // agent_start events with no matching stops.
+  // Why: stats.flush() must precede killAllPty() so still-running agents emit synthetic agent_stop events (killAllPty skips runtime.onPtyExit()).
   starNag?.stop()
   automations?.stop()
   setUnreadDockBadgeCount(0)
   agentHookServer.stop()
-  // Why: cancels relay restart/reinstall timers and kills wsl.exe children
-  // deterministically instead of relying on stdio-pipe teardown.
+  // Why: cancels relay restart/reinstall timers and kills wsl.exe children deterministically, not via stdio-pipe teardown.
   wslHookRelayManager.disposeAll()
   stats?.flush()
-  // Why: agent-browser daemon processes would otherwise linger after Orca quits,
-  // holding ports and leaving stale session state on disk.
+  // Why: agent-browser daemon processes would otherwise linger after quit, holding ports and stale session state on disk.
   runtime?.getAgentBrowserBridge()?.destroyAllSessions()
-  // Why: headless offscreen browser windows are main-process owned; tear them
-  // down explicitly on quit alongside the other browser/session shutdowns.
+  // Why: headless offscreen browser windows are main-process owned; tear them down explicitly on quit.
   runtime?.getOffscreenBrowserBackend()?.destroyAll?.()
   browserManager.setBrowserGuestStateChangedListener(null)
   const emulatorShutdown = runtime?.getEmulatorBridge()?.destroyAllSessions() ?? Promise.resolve()
@@ -2481,32 +2219,20 @@ app.on('will-quit', (e) => {
   const watcherShutdown = shutdownWatchersOnce()
   store?.flush()
 
-  // Why: disconnectDaemon writes final checkpoints via async getSnapshot RPCs.
-  // Without preventDefault, Electron exits before the RPCs complete and the
-  // checkpoint data is lost. The guard prevents an infinite quit loop —
-  // app.quit() re-fires will-quit, but the second pass skips straight through.
+  // Why: preventDefault to await disconnectDaemon's async checkpoint writes (else data lost); guard prevents an infinite quit loop on the re-fired will-quit.
   if (!daemonDisconnectDone) {
     e.preventDefault()
-    // Why: capture ownership synchronously (before any await) so the guard
-    // still has the right pid/runtimeId to compare against if shutdown
-    // partially clears global state. Evaluating these inside .then() would
-    // let a later teardown path null them out mid-chain.
+    // Why: capture pid/runtimeId synchronously (before any await) so a later teardown path can't null them out mid-chain.
     const ownedPid = process.pid
     const ownedRuntimeId = runtime?.getRuntimeId()
-    // Why: the construction of rpcStopAndClear AND the allSettled() below must
-    // both live inside the `!daemonDisconnectDone` guard. will-quit re-fires
-    // after app.quit() below; without this guard, the second pass would
-    // re-invoke runtimeRpc.stop() (redundant rmSync on an already-removed
-    // socket) and re-run the ownership-guarded clear against a metadata file
-    // that may now belong to the auto-updater's replacement process.
+    // Why: keep inside the !daemonDisconnectDone guard so the re-fired will-quit doesn't re-run RPC.stop()/metadata-clear against the updater's replacement process.
     const rpcStopAndClear = runtimeRpc
       ? runtimeRpc
           .stop()
           .then(() => awaitRuntimeFileWatcherUnsubscribes())
           .then(() => {
             if (ownedRuntimeId) {
-              // Why: must match the path the runtime server wrote metadata to
-              // (getCanonicalUserDataPath), not late app.getPath('userData').
+              // Why: must match the path the runtime server wrote metadata to (getCanonicalUserDataPath), not late app.getPath('userData').
               clearRuntimeMetadataIfOwned(getCanonicalUserDataPath(), ownedPid, ownedRuntimeId)
             }
           })
@@ -2514,18 +2240,9 @@ app.on('will-quit', (e) => {
             console.error('[runtime] Failed to stop local RPC transport:', error)
           })
       : Promise.resolve()
-    // Why: Promise.allSettled — we need BOTH the daemon disconnect and the
-    // RPC stop + owned-metadata clear to complete before Electron exits.
-    // Using allSettled (not all) preserves the existing fail-open posture:
-    // if disconnectDaemon rejects, we still quit instead of hanging the app.
-    //
-    // Telemetry shutdown folds in after the daemon/RPC teardown and BEFORE
-    // app.quit(): the PostHog client has up to 2s of bounded flush. Errors
-    // inside `shutdownTelemetry()` are caught by the client itself — we
-    // catch again here defensively so a flush failure cannot cancel the
-    // quit chain.
-    // Why: normal quits preserve the detached daemon for warm reattach, but a
-    // dev parent dying means the temp/dev profile has no owner left to reattach.
+    // Why: allSettled (not all) keeps fail-open — a daemon-disconnect rejection still quits instead of hanging.
+    // Why: telemetry flush folds in before app.quit() (bounded 2s); catch defensively so a flush failure can't cancel the quit chain.
+    // Why: normal quits keep the detached daemon for warm reattach, but a dead dev parent leaves the temp/dev profile ownerless.
     const daemonTeardown = isDevParentShutdownRequested() ? shutdownDaemon() : disconnectDaemon()
     Promise.allSettled([daemonTeardown, rpcStopAndClear, watcherShutdown, emulatorShutdown])
       .then(() => shutdownTelemetry())
@@ -2541,16 +2258,8 @@ app.on('will-quit', (e) => {
 })
 
 app.on('window-all-closed', () => {
-  // Why: headless `orca serve` has no desktop window, and offscreen browser
-  // windows are disposable implementation details. Closing/crashing the last
-  // one must not take down terminal/runtime RPC for the VM workspace — the
-  // policy fn returns false for serve mode so the app stays alive.
-  //
-  // Why: on macOS, closing all windows normally keeps the app alive (dock
-  // stays active). But when a quit is in progress (Cmd+Q), the window close
-  // handler defers to the renderer for buffer capture, which cancels the
-  // original quit sequence. Re-trigger quit here so the app actually exits
-  // instead of requiring a second Cmd+Q.
+  // Why: serve mode / disposable offscreen browser windows must not take down runtime RPC — the policy fn keeps the app alive.
+  // Why: on macOS a quit-in-progress (Cmd+Q) is canceled by the renderer buffer-capture deferral; re-trigger quit so it actually exits.
   if (
     shouldQuitWhenAllWindowsClosed({
       platform: process.platform,
diff --git a/src/main/ipc/app.ts b/src/main/ipc/app.ts
index d943d18dc04..7485c03b5f0 100644
--- a/src/main/ipc/app.ts
+++ b/src/main/ipc/app.ts
@@ -25,10 +25,7 @@ import { registerRendererShutdownCheckpointHandler } from './renderer-shutdown-c
 
 const KEYBOARD_INPUT_SOURCE_TIMEOUT_MS = 500
 const MAC_HITOOLBOX_DOMAIN = 'com.apple.HIToolbox'
-// Why: macOS 15's `plutil -extract <key> json` aborts on the (pure-string)
-// input-source array and the on-disk plist lags cfprefsd; read live prefs via
-// `defaults export`, extract as xml1 (dodges the json bug), then convert to JSON.
-// Absolute paths so a GUI-launched app's minimal PATH can't shadow the tools.
+// Why: defaults export reads live prefs (on-disk plist lags cfprefsd); xml1 dodges plutil's json abort on macOS 15 input-source arrays; absolute paths so a minimal PATH can't shadow the tools.
 const MAC_SELECTED_INPUT_SOURCES_JSON_COMMAND = [
   `/usr/bin/defaults export ${MAC_HITOOLBOX_DOMAIN} -`,
   '/usr/bin/plutil -extract AppleSelectedInputSources xml1 -o - -',
@@ -69,8 +66,7 @@ async function pickFloatingWorkspaceDirectory(
 ): Promise<string | null> {
   const parentWindow = BrowserWindow.fromWebContents(event.sender)
   const options = {
-    // Why: this picker grants access to an existing workspace directory.
-    // Creation belongs to explicit file/write actions, not typeahead input.
+    // Why: this picker only grants access to an existing directory; creation belongs to explicit file actions.
     properties: ['openDirectory']
   } satisfies Electron.OpenDialogOptions
   const result = parentWindow
@@ -80,8 +76,7 @@ async function pickFloatingWorkspaceDirectory(
     return null
   }
   const selectedDir = result.filePaths[0]
-  // Why: a user-approved picker selection is a trust grant for later Floating
-  // Workspace markdown creation, unlike arbitrary typed settings text.
+  // Why: a user-approved picker selection is a trust grant for later markdown creation, unlike typed settings text.
   await grantFloatingWorkspaceDirectory(store, selectedDir)
   return selectedDir
 }
@@ -94,8 +89,7 @@ function getFeatureWallAssetBaseUrl(): string {
   if (!app.isPackaged && process.env.ELECTRON_RENDERER_URL) {
     const vitePath = assetDir.split(path.sep).join('/')
     const absoluteVitePath = vitePath.startsWith('/') ? vitePath : `/${vitePath}`
-    // Why: the dev renderer is served from http://localhost, where Chromium
-    // blocks file:// image loads. Vite's /@fs route serves the same local media.
+    // Why: Chromium blocks file:// image loads from the http dev origin; Vite's /@fs route serves the same local media.
     return new URL(`/@fs${absoluteVitePath}/`, process.env.ELECTRON_RENDERER_URL).toString()
   }
 
@@ -110,8 +104,7 @@ function resolveDevFeatureWallAssetDir(): string {
     path.join(process.cwd(), relativeDir)
   ]
 
-  // Why: E2E launches out/main/index.js, so app.getAppPath() can point at
-  // out/main even though development resources still live at the repo root.
+  // Why: E2E launches out/main, so app.getAppPath() can point there while dev resources live at the repo root.
   return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0]
 }
 
@@ -124,10 +117,7 @@ function readCommandStdout(
     let settled = false
     let child: ReturnType<typeof spawn> | undefined
 
-    // Why: the probe runs a `/bin/sh -c` pipeline, so signaling only the shell
-    // orphans wedged `defaults`/`plutil` stages on a stuck cfprefsd. Spawning
-    // detached makes the child a process-group leader, so one negative-pid
-    // SIGKILL reaps the shell and every stage; child.kill() covers the fallback.
+    // Why: killing only the shell orphans pipeline stages; detached spawn lets one negative-pid SIGKILL reap the whole group.
     const killTree = (): void => {
       if (!child?.pid) {
         return
@@ -139,9 +129,7 @@ function readCommandStdout(
       }
     }
 
-    // Why: short timeout so a wedged macOS preference probe (corporate-managed
-    // config, sandbox policy, ...) never holds the handle indefinitely. This
-    // manual timer is the only timeout guard, so it owns the process-group kill.
+    // Why: short timeout so a wedged macOS probe never hangs; this timer owns the process-group kill.
     const timer = setTimeout(() => {
       if (settled) {
         return
@@ -171,8 +159,7 @@ function readCommandStdout(
         killTree()
         settle(() => reject(error))
       }
-      // Why: an unhandled Readable 'error' would crash the main process; treat a
-      // stdout read failure the same as a child spawn error.
+      // Why: an unhandled Readable 'error' would crash the main process; treat stdout errors like spawn errors.
       child.stdout?.on('error', failWith)
       child.on('error', failWith)
       child.on('close', (code, signal) => {
@@ -276,47 +263,27 @@ export function registerAppHandlers(store: Store, options: RegisterAppHandlersOp
   ipcMain.handle('pwsh:isAvailable', (): boolean => isPwshAvailable())
   ipcMain.handle('gitBash:isAvailable', (): boolean => isGitBashAvailable())
 
-  // Why: ABC, Polish Pro, US Extended, ABC Extended, and every CJK Roman
-  // IME all report a US-QWERTY base layer to navigator.keyboard.getLayoutMap()
-  // — the layout-fingerprint probe in the renderer therefore classifies
-  // them as 'us' and flips macOptionIsMeta=true, silently swallowing every
-  // Option+letter composition (#1205: Option+A → å / ą is dropped). The
-  // macOS-shipped `com.apple.HIToolbox` preferences name the actual input
-  // mode when one is selected, falling back to the keyboard layout ID
-  // (e.g. `com.apple.keylayout.ABC` vs `com.apple.keylayout.US`), which
-  // the renderer uses as an authoritative override. Non-Darwin platforms
-  // have no equivalent and return null so the fingerprint stays the only
-  // signal.
+  // Why: renderer layout fingerprint tags ABC/CJK-Roman as 'us', breaking Option+letter (#1205); HIToolbox prefs override it.
   ipcMain.handle('app:getKeyboardInputSourceId', async (): Promise<string | null> => {
     if (process.platform !== 'darwin') {
       return null
     }
     try {
-      // Why: async so the probe never blocks the main-process event loop.
-      // The probe re-runs on every window focus-in (see option-as-alt-probe.ts),
-      // and a blocking execFileSync would briefly stall unrelated IPC each
-      // time the user Alt-Tabbed back into the app.
+      // Why: async so the focus-in probe (see option-as-alt-probe.ts) never blocks the main event loop.
       const stdout = await readKeyboardInputSourceId()
       const trimmed = stdout?.trim() ?? ''
       return trimmed.length > 0 ? trimmed : null
     } catch {
-      // Why: macOS preference probes can fail when keys are absent (first boot
-      // before any input-source interaction), or when sandboxed. Treat that as
-      // "no signal" — the fingerprint still runs as fallback.
+      // Why: probe can fail (missing keys on first boot, sandbox) — treat as "no signal" and fall back to the fingerprint.
       return null
     }
   })
 
   ipcMain.handle('app:relaunch', async () => {
-    // Why: small delay lets the renderer finish painting any "Restarting…"
-    // UI state before the window tears down. `app.relaunch()` schedules a
-    // spawn; `app.exit(0)` triggers the actual quit without invoking
-    // before-quit handlers that could block on confirmation dialogs.
-    // Mark shutdown first because app.exit() can bypass the usual quit latch.
+    // Why: brief delay lets the renderer paint "Restarting…" before the window tears down.
     await runBeforeRelaunchCleanup(options.onBeforeRelaunch)
     setTimeout(() => {
-      // Why: app.exit(0) skips before-quit/will-quit, so clean the Windows tray
-      // explicitly before relaunching to avoid a stale notification-area icon.
+      // Why: app.exit(0) skips before-quit, so destroy the Windows tray manually to avoid a stale icon.
       destroySystemTray()
       relaunchApp('renderer-request')
       app.exit(0)
@@ -324,9 +291,7 @@ export function registerAppHandlers(store: Store, options: RegisterAppHandlersOp
   })
 
   ipcMain.handle('app:restart', async () => {
-    // Why: the hidden admin restart should mirror the update relaunch path:
-    // schedule a new Orca process, then use the normal quit pipeline so daemon
-    // checkpoints, runtime metadata, and telemetry flush before exit.
+    // Why: use the normal quit pipeline so daemon checkpoints and telemetry flush before exit.
     await runBeforeRelaunchCleanup(options.onBeforeRelaunch)
     setTimeout(() => {
       relaunchApp('admin-restart')
@@ -357,8 +322,7 @@ async function runBeforeRelaunchCleanup(
   try {
     await onBeforeRelaunch?.()
   } catch (error) {
-    // Why: restart/relaunch must not get trapped if best-effort shutdown
-    // cleanup fails; the cleanup path logs without exposing secret contents.
+    // Why: best-effort cleanup must never block relaunch; log only error.name to avoid leaking secrets.
     console.warn(
       '[app] Pre-relaunch cleanup failed; continuing relaunch:',
       error instanceof Error ? error.name : typeof error
diff --git a/src/main/ipc/filesystem-auth.ts b/src/main/ipc/filesystem-auth.ts
index 7fee4ca1990..b172c2c1894 100644
--- a/src/main/ipc/filesystem-auth.ts
+++ b/src/main/ipc/filesystem-auth.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: filesystem authorization keeps root
-discovery, canonicalization, and registered-worktree cache checks together so
-the security boundary is auditable end to end. */
+/* eslint-disable max-lines -- Why: keeps the filesystem-auth security boundary auditable end to end. */
 import { resolve, relative, dirname, basename, isAbsolute, sep } from 'node:path'
 import { realpathSync } from 'node:fs'
 import { realpath } from 'node:fs/promises'
@@ -13,13 +11,7 @@ import type { FolderWorkspace, ProjectGroup, Repo } from '../../shared/types'
 
 export const PATH_ACCESS_DENIED_MESSAGE =
   'Access denied: path resolves outside allowed directories. If this blocks a legitimate workflow, please file a GitHub issue.'
-// Why: authorized external paths accumulate for the whole session (file drops,
-// terminal link opens, editor/composer/notebook opens). Bound the set with LRU
-// eviction — mirrors rememberUnwatchableRoot in filesystem-watcher.ts — so a long
-// session touching many distinct external files cannot grow it (or the O(n) auth
-// scan in isPathAllowed) without limit. Every caller re-authorizes a path right
-// before operating on it, so evicting a stale entry is self-healing and does not
-// weaken the security boundary.
+// Why: authorized external paths accumulate all session; LRU-bound the set. Safe to evict because every caller re-authorizes before operating.
 export const AUTHORIZED_EXTERNAL_PATHS_MAX = 4096
 const authorizedExternalPaths = new Set<string>()
 const registeredWorktreeRoots = new Set<string>()
@@ -32,8 +24,7 @@ type FolderScopeStore = Pick<Store, 'getRepos'> &
   Partial<Pick<Store, 'getProjectGroups' | 'getFolderWorkspaces'>>
 
 function rememberAuthorizedExternalPath(path: string): void {
-  // Delete-then-add keeps re-authorized (actively used) paths most-recent so
-  // eviction only sheds the oldest never-re-touched entries.
+  // Delete-then-add makes re-authorized paths most-recent so LRU eviction sheds only the oldest untouched entries.
   authorizedExternalPaths.delete(path)
   authorizedExternalPaths.add(path)
   while (authorizedExternalPaths.size > AUTHORIZED_EXTERNAL_PATHS_MAX) {
@@ -56,17 +47,14 @@ export function authorizeExternalPath(targetPath: string): void {
 
 export function invalidateAuthorizedRootsCache(): void {
   registeredWorktreeRootsDirty = true
-  // Why: dirty roots cannot be trusted for auth short-circuits. Fresh
-  // worktrees:list results will seed safe per-repo roots before a full rebuild.
+  // Why: dirty roots can't be trusted for auth short-circuits; fresh worktrees:list seeds safe per-repo roots before a full rebuild.
   registeredWorktreeRoots.clear()
   registeredWorktreeRootsByRepo.clear()
   registeredWorktreeRootRepoIds.clear()
 }
 
 function getLocalRepos(store: Store) {
-  // Why: SSH repo paths are meaningful on the remote host. Treating them as
-  // local roots can both authorize unrelated local folders and probe paths
-  // that Orca should only touch through the SSH provider.
+  // Why: SSH repo paths are remote-host paths; treating them as local roots could authorize unrelated local folders or probe SSH-only paths.
   return store.getRepos().filter((repo) => !repo.connectionId)
 }
 
@@ -148,11 +136,8 @@ export function isDescendantOrEqual(resolvedTarget: string, resolvedBase: string
     return true
   }
   const rel = relative(resolvedBase, resolvedTarget)
-  // rel must not be ".."/"../..." or an absolute path (e.g. different drive on Windows)
-  // [Security Fix]: Added !isAbsolute(rel) to prevent drive traversal bypasses on Windows
-  // where relative('D:\\repo', 'C:\\etc\\passwd') returns absolute path 'C:\\etc\\passwd'
-  // Why: Windows path.relative() already treats drive/root casing as equivalent;
-  // rejoining and comparing strings would deny valid `c:\repo` descendants of `C:\Repo`.
+  // Security: reject "..", "../…" or an absolute rel — on Windows relative() returns absolute across drives, which would bypass drive-traversal checks.
+  // Use isAbsolute, not rejoin+compare: Windows path.relative() ignores drive/root casing, so rejoining would deny valid c:\repo under C:\Repo.
   return rel !== '' && !(rel === '..' || rel.startsWith(`..${sep}`)) && !isAbsolute(rel)
 }
 
@@ -191,15 +176,8 @@ export function isPathAllowed(targetPath: string, store: Store): boolean {
 }
 
 export async function rebuildAuthorizedRootsCache(store: Store): Promise<void> {
-  // Why: repos are processed with bounded parallelism so the cache rebuild
-  // keeps the Windows speedup without spawning one git process per repo.
-  //
-  // Why no realpath() here: this rebuild runs on repo/worktree invalidation,
-  // so canonicalizing every repo root would repeatedly touch TCC-protected
-  // folders on macOS even when the user is idle. The actual
-  // file handlers still canonicalize the specific target path before any
-  // destructive or read/write operation, so the security boundary remains
-  // enforced where it matters.
+  // Why: bounded parallelism keeps the Windows speedup without one git process per repo.
+  // Why no realpath here: canonicalizing every root on invalidation would trigger macOS TCC prompts; handlers still canonicalize the target before any operation.
   const repos = getLocalRepos(store)
   const perProjectResults = await mapWithConcurrency(
     repos,
@@ -213,10 +191,7 @@ export async function rebuildAuthorizedRootsCache(store: Store): Promise<void> {
           roots.push(resolve(worktree.path))
         }
       } catch (error) {
-        // Why: a single inaccessible repo (EACCES, EIO, etc.) must not break
-        // the entire cache rebuild — that would disable File Explorer and
-        // Quick Open for all other repos. We skip the failing repo and let
-        // the rest proceed.
+        // Why: one inaccessible repo (EACCES/EIO) must not break the whole rebuild and disable File Explorer/Quick Open for the rest; skip it.
         console.warn(`[filesystem-auth] skipping repo ${repo.path} during cache rebuild:`, error)
       }
       return { repoId: repo.id, roots }
@@ -306,11 +281,7 @@ export function isENOENT(error: unknown): boolean {
 
 export type ResolveAuthorizedPathOptions = {
   /**
-   * When true, canonicalize the parent directory but preserve the leaf so
-   * operations target the symlink itself rather than its destination. Required
-   * for delete and rename — following the symlink would trash or rename the
-   * target file (which can live outside allowed roots, or be another tracked
-   * file a symlink inside the worktree happens to point at).
+   * Canonicalize the parent but preserve the leaf so delete/rename target the symlink itself, not its destination (which may live outside allowed roots).
    */
   preserveSymlink?: boolean
 }
@@ -326,9 +297,7 @@ export async function resolveAuthorizedPath(
   }
 
   if (options.preserveSymlink) {
-    // Canonicalize the parent so symlinks in ancestors cannot redirect us
-    // outside allowed roots, but keep the final segment untouched so callers
-    // (delete/rename) act on the link itself.
+    // Canonicalize the parent so ancestor symlinks can't redirect outside allowed roots, but keep the leaf so delete/rename act on the link itself.
     let realParent: string
     try {
       realParent = await realpath(dirname(resolvedTarget))
@@ -350,8 +319,7 @@ export async function resolveAuthorizedPath(
   }
 
   try {
-    // Why: Windows/WSL realpath can return UNC-shaped paths that still need to
-    // compare against the resolved allow-list roots used by this module.
+    // Why: Windows/WSL realpath can return UNC-shaped paths; re-resolve to compare against this module's allow-list roots.
     const realTarget = resolve(await realpath(resolvedTarget))
     if (
       !(await isPathAllowedIncludingRegisteredWorktrees(realTarget, store, {
@@ -393,9 +361,7 @@ async function resolveAuthorizedMissingPath(resolvedTarget: string, store: Store
       if (parent === existingAncestor) {
         throw error
       }
-      // Why: create/copy callers intentionally create missing parents after
-      // auth. Canonicalize the nearest existing ancestor so symlink escapes are
-      // still caught without rejecting legitimate nested paths.
+      // Why: create/copy make missing parents after auth; canonicalize nearest existing ancestor to catch symlink escapes without rejecting nested paths.
       missingSegments.unshift(basename(existingAncestor))
       existingAncestor = parent
     }
@@ -425,9 +391,7 @@ async function isPathAllowedIncludingRegisteredWorktrees(
 
   await ensureAuthorizedRootsCache(store)
 
-  // Why: external linked worktrees are already trusted for git operations.
-  // Cache their normalized roots once and reuse that index so quick-open and
-  // file explorer do not spawn `git worktree list` on every filesystem read.
+  // Why: linked worktrees are already git-trusted; reuse the cached root index so reads don't spawn `git worktree list` each time.
   return (
     isRegisteredWorktreePath(targetPath) ||
     (await isPathAllowedByCanonicalRegisteredRoot(targetPath, options.canonicalSourcePath))
@@ -437,16 +401,13 @@ async function isPathAllowedIncludingRegisteredWorktrees(
 /**
  * Resolve and verify that a worktree path belongs to a registered repo.
  *
- * Why this doesn't use resolveAuthorizedPath: linked worktrees can live outside
- * repo/workspace roots. Git operations trust exact worktree registration from
- * `git worktree list`, not directory containment.
+ * Why not resolveAuthorizedPath: linked worktrees can live outside repo/workspace roots; git trusts exact `git worktree list` registration, not containment.
  */
 export async function resolveRegisteredWorktreePath(
   worktreePath: string,
   store: Store
 ): Promise<string> {
-  // Reject obviously malformed paths early — mirrors the null-byte check in
-  // validateGitRelativeFilePath and prevents probing via realpath.
+  // Reject malformed paths (null byte) early to prevent probing via realpath.
   if (!worktreePath || worktreePath.includes('\0')) {
     throw new Error('Access denied: invalid worktree path')
   }
@@ -464,8 +425,7 @@ export async function resolveRegisteredWorktreePath(
     return resolvedTarget
   }
 
-  // Resolve through symlinks only after the cheap registered-root check.
-  // On macOS, realpath() can itself trigger TCC prompts for protected roots.
+  // Resolve symlinks only after the cheap registered-root check: on macOS realpath() can trigger TCC prompts.
   const normalizedTarget = await normalizeExistingPath(resolvedTarget)
   if (registeredWorktreeRoots.has(normalizedTarget)) {
     return normalizedTarget
@@ -505,8 +465,7 @@ async function isPathAllowedByCanonicalAllowedRoot(
     if (!isDescendantOrEqual(sourcePath, resolvedRoot)) {
       continue
     }
-    // Why: active file operations may resolve `/var` to `/private/var` on
-    // macOS. Canonicalize only the matched root instead of the whole repo set.
+    // Why: macOS resolves /var→/private/var; canonicalize only the matched root, not the whole repo set.
     const canonicalRoot = await normalizeExistingPath(resolvedRoot)
     if (isDescendantOrEqual(targetPath, canonicalRoot)) {
       return true
@@ -539,9 +498,7 @@ async function isPathAllowedByCanonicalRegisteredRoot(
   if (!isDescendantOrEqual(targetPath, canonicalRoot)) {
     return false
   }
-  // Why: #1524 stopped realpath'ing every worktree root during background
-  // refreshes to avoid macOS privacy prompts. Cache only the root the user is
-  // actively accessing so /var→/private/var aliases work without broad probes.
+  // Why: #1524 stopped realpath'ing every root (macOS privacy prompts); cache only the actively-accessed root so /var→/private/var aliases resolve.
   registeredWorktreeRoots.add(canonicalRoot)
   return true
 }
diff --git a/src/main/ipc/filesystem-watcher.ts b/src/main/ipc/filesystem-watcher.ts
index 6e5876e9add..2e2a27cb3f6 100644
--- a/src/main/ipc/filesystem-watcher.ts
+++ b/src/main/ipc/filesystem-watcher.ts
@@ -1,8 +1,4 @@
-/* eslint-disable max-lines -- Why: filesystem-watcher centralizes native
-(@parcel/watcher), WSL-native snapshot, and SSH remote watcher lifecycles in
-one module so subscription/cleanup invariants stay auditable from a single
-file. Splitting by transport would scatter the shared debounce/coalesce
-helpers and the common batch-flush path across three files. */
+/* eslint-disable max-lines -- Why: one module keeps native (@parcel/watcher), WSL-snapshot, and SSH watcher lifecycle invariants and shared debounce/coalesce helpers auditable in one file. */
 import { ipcMain, type WebContents } from 'electron'
 import * as path from 'node:path'
 import { stat } from 'node:fs/promises'
@@ -24,10 +20,7 @@ import {
   WatcherChildCapacityError
 } from './parcel-watcher-child-registry'
 import { beginWatcherInstall, isWatcherRemovalInProgressError } from './watcher-removal-gate'
-// Why: high-churn directories are suppressed at the native watcher level so
-// events never leave the OS/daemon. This list is separate from the File
-// Explorer display filter (which only hides rows). Directories like `dist`
-// and `build` remain visible in the tree but will not auto-refresh.
+// Why: suppress high-churn dirs at the watcher level (separate from the File Explorer display filter, which only hides rows).
 import { WATCHER_IGNORE_DIRS, buildParcelWatcherIgnoreOptions } from './filesystem-watcher-ignore'
 
 // ── Debounce helpers ─────────────────────────────────────────────────
@@ -36,23 +29,18 @@ const DEBOUNCE_TRAILING_MS = 150
 const DEBOUNCE_MAX_WAIT_MS = 500
 
 // ── Per-root watcher state ───────────────────────────────────────────
-// WatchedRoot and WatcherSubscription are defined in filesystem-watcher-wsl.ts
-// and re-used here so both native and WSL watchers share the same shape.
+// WatchedRoot/WatcherSubscription live in filesystem-watcher-wsl.ts so native and WSL watchers share one shape.
 
 // ── Module state ─────────────────────────────────────────────────────
 
 const watchedRoots = new Map<string, WatchedRoot>()
 
-// Why: roots that failed watcher creation (e.g. WSL UNC paths where
-// @parcel/watcher's ReadDirectoryChangesW doesn't work) are cached so
-// we don't retry on every worktree switch and spam the console with
-// repeated "Failed to read changes" / "watchman not found" errors.
+// Why: cache roots that failed watcher creation (e.g. WSL UNC paths) so we don't retry every worktree switch and spam the console with errors.
 const UNWATCHABLE_ROOT_CACHE_MAX = 256
 const unwatchableRoots = new Set<string>()
 
 function rememberUnwatchableRoot(rootKey: string): void {
-  // Why: missing/deleted worktrees can churn through unique paths during a long
-  // session; keep retry suppression useful without retaining every failed path.
+  // Why: deleted worktrees churn through unique paths; cap the set so retry suppression stays useful without retaining every failed path.
   unwatchableRoots.delete(rootKey)
   unwatchableRoots.add(rootKey)
   while (unwatchableRoots.size > UNWATCHABLE_ROOT_CACHE_MAX) {
@@ -64,28 +52,20 @@ function rememberUnwatchableRoot(rootKey: string): void {
   }
 }
 
-// Why: watcher cleanup is keyed to the renderer WebContents, not to a specific
-// watched root. One listener per sender avoids MaxListeners warnings when a
-// workspace has many local and SSH-backed worktrees open.
+// Why: key cleanup by sender WebContents (not per root) to avoid MaxListeners warnings when a workspace has many worktrees open.
 const senderCleanupRegistered = new Set<number>()
 
-// Why: on Windows, tearing down and recreating @parcel/watcher subscriptions
-// is expensive (ReadDirectoryChangesW setup + antivirus scanning can take
-// 500 ms+).  A 30 s grace period lets rapid worktree switches reuse the
-// existing watcher instead of paying the creation cost on every switch.
-// Key: rootKey, Value: pending teardown timer.
+// Why: recreating @parcel/watcher on Windows is expensive (ReadDirectoryChangesW + AV, 500ms+); a 30s grace lets rapid switches reuse the watcher.
 const WATCHER_TEARDOWN_GRACE_MS = 30_000
 const pendingTeardowns = new Map<string, ReturnType<typeof setTimeout>>()
-// Why: @parcel/watcher unsubscribe completes native async work. Sender-destroy
-// cleanup can start it before app shutdown, so will-quit must still await it.
+// Why: @parcel/watcher unsubscribe does native async work that sender-destroy can start before shutdown, so will-quit must still await it.
 const pendingLocalUnsubscribes = new Set<Promise<void>>()
 const pendingLocalUnsubscribesByRoot = new Map<string, Set<Promise<void>>>()
 const suspendedLocalWatcherListeners = new Map<
   string,
   { worktreePath: string; listeners: Map<number, WebContents> }
 >()
-// Why: an install cancelled by shutdown cannot be revived by a waiter that
-// resumes after a later handler call reopens the watcher subsystem.
+// Why: an install cancelled by shutdown can't be revived by a waiter that resumes after a later call reopens the subsystem.
 let localWatchersClosed = false
 let localWatcherLifecycleGeneration = 0
 const failedLocalUnsubscribes = new Map<string, unknown>()
@@ -99,8 +79,7 @@ type LocalWatcherCapacityRetry = {
   listeners: Map<number, WebContents>
   cancelWait: () => void
 }
-// Why: native watcher creation is async. Concurrent local watch requests for
-// the same root must share one install or later resolves can orphan listeners.
+// Why: watcher creation is async; concurrent watch requests for the same root must share one install or later resolves orphan listeners.
 const inFlightLocalInstalls = new Map<string, LocalWatcherInstallToken>()
 const pendingLocalInstallPromises = new Map<string, Promise<LocalWatcherInstallResult>>()
 const pendingLocalCapacityRetries = new Map<string, LocalWatcherCapacityRetry>()
@@ -122,8 +101,7 @@ function cleanupInFlightLocalInstallsForSender(senderId: number): void {
     token.listeners.delete(senderId)
     if (token.listeners.size === 0) {
       token.cancelled = true
-      // Why: match closeLocalWatcherForWorktreePath / closeAllWatchers — abort
-      // so a pending native/forked subscription stops early, not at completion.
+      // Why: abort so a pending native/forked subscription stops early (matches closeLocalWatcherForWorktreePath / closeAllWatchers).
       token.abortController.abort()
     }
   }
@@ -205,9 +183,7 @@ function normalizeRootPath(rootPath: string): string {
   let resolved = isWindowsAbsolutePathLike(rootPath)
     ? path.win32.resolve(rootPath)
     : path.resolve(rootPath)
-  // Why: on Windows, watcher events may report lowercase drive letters while
-  // stored worktree paths use uppercase. Normalizing here ensures the renderer's
-  // POSIX normalization produces casing-consistent results (see design §4.4).
+  // Why: Windows watcher events may use lowercase drive letters vs stored uppercase; normalize so renderer casing stays consistent (§4.4).
   if (/^[a-zA-Z]:/.test(resolved)) {
     resolved = resolved.charAt(0).toUpperCase() + resolved.slice(1)
   }
@@ -217,8 +193,7 @@ function normalizeRootPath(rootPath: string): string {
 function localWatcherRoot(rootPath: string): { key: string; path: string } {
   const normalizedPath = normalizeRootPath(rootPath)
   return {
-    // Why: Windows drive and UNC paths are case-insensitive; destructive
-    // cleanup must find the owner even when Git returns a different spelling.
+    // Why: Windows drive/UNC paths are case-insensitive; cleanup must match the owner even when Git returns a different spelling.
     key: normalizeRuntimePathForComparison(normalizedPath),
     path: normalizedPath
   }
@@ -233,10 +208,7 @@ function normalizeEventPath(eventPath: string): string {
 }
 
 // ── Event coalescing ─────────────────────────────────────────────────
-// Why: within a single flush window the same path can appear multiple times.
-// Keep the last event per path, except: delete→create emits both (the delete
-// triggers subtree cleanup, the create triggers parent refresh); create→delete
-// is dropped entirely (net no-op). See design §4.4.
+// Why: keep the last event per path in a flush window; delete→create emits both (delete cleans the subtree, create refreshes the parent), create→delete is dropped (§4.4).
 
 function coalesceEvents(
   raw: WatcherEvent[]
@@ -264,10 +236,7 @@ function coalesceEvents(
 
     lastByPath.set(p, { type: evt.type, index: i })
 
-    // Why: if a later event (e.g. update) supersedes a delete→create sequence,
-    // the stale delete must be dropped. Otherwise the final output would include
-    // a spurious delete + the new event type (e.g. delete→create→update would
-    // emit delete+update, but the file exists so the delete is wrong). See §4.4.
+    // Why: drop the stale delete when a later event supersedes delete→create, else output has a spurious delete for a file that still exists (§4.4).
     if (evt.type !== 'create' && deleteBeforeCreate.has(p)) {
       deleteBeforeCreate.delete(p)
     }
@@ -295,9 +264,7 @@ async function tryStatIsDirectory(filePath: string): Promise<boolean | undefined
     const s = await stat(filePath)
     return s.isDirectory()
   } catch {
-    // Why: if stat fails (EPERM, vanished temp file), return undefined.
-    // The renderer treats undefined the same as a file event (parent-only
-    // invalidation), which is the safe default. See design §4.4.
+    // Why: stat failure (EPERM, vanished file) → undefined; renderer treats it as a file event, the safe default (§4.4).
     return undefined
   }
 }
@@ -329,20 +296,16 @@ async function flushBatch(rootKey: string, root: WatchedRoot): Promise<void> {
   }
 
   if (overflowed || rawEvents.length > MAX_BATCHED_WATCHER_EVENTS) {
-    // Why: deletion storms can be valid but too large to coalesce/stat/send
-    // per path. One overflow asks the renderer for the same conservative refresh.
+    // Why: deletion storms can be too large to coalesce/stat per path; one overflow asks the renderer for the same conservative refresh.
     emitOverflowPayload(rootKey, root)
     return
   }
 
   const coalesced = coalesceEvents(rawEvents)
 
-  // Build the payload with isDirectory info
   const events: FsChangeEvent[] = await Promise.all(
     coalesced.map(async (evt) => {
-      // Why: for delete events the path no longer exists on disk, so stat is
-      // not possible. Set isDirectory to undefined and let the renderer infer
-      // from dirCache (if the deleted path is a dirCache key, it's a directory).
+      // Why: a deleted path can't be stat'd; leave isDirectory undefined and let the renderer infer from dirCache.
       const isDirectory = evt.type === 'delete' ? undefined : await tryStatIsDirectory(evt.path)
 
       return {
@@ -403,17 +366,12 @@ async function createWatcher(
   }
 
   try {
-    // Why: track whether the error callback already ran cleanup before
-    // subscribe() resolved.  If it did, the subscription object returned
-    // by subscribe() would be orphaned (never stored in watchedRoots and
-    // therefore never unsubscribed), leaking a native file-watcher handle.
+    // Why: if the error callback cleaned up before subscribe() resolved, its returned subscription is orphaned and leaks a native handle.
     let errorCleanedUp = false
 
     const watcherOptions = {
       ...buildParcelWatcherIgnoreOptions(WATCHER_IGNORE_DIRS),
-      // Why: Parcel checks Watchman before the native Windows backend by
-      // default, and Windows prints a shell-level "watchman not recognized"
-      // error for that probe. Pinning the backend keeps local watches quiet.
+      // Why: Parcel probes Watchman first, which prints a shell-level "watchman not recognized" error on Windows; pin the backend to suppress it.
       ...(process.platform === 'win32' ? { backend: 'windows' as const } : {})
     }
 
@@ -422,30 +380,19 @@ async function createWatcher(
       scheduleBatchFlush(rootKey, root)
     }
 
-    // Why: subscriptions run in a forked watcher process (issue #7547 —
-    // watcher.node teardown races fail-fast the hosting process). A watcher
-    // crash there is recovered by resubscribing; onInterruption marks the
-    // batch overflowed so the renderer refreshes past the event gap.
+    // Why: fork the watcher process (issue #7547 — watcher.node teardown races crash the host); onInterruption marks overflow to refresh past the gap.
     root.subscription = await subscribeViaWatcherProcess(
       rootPath,
       (err, events) => {
         if (err) {
-          // Why: watcher errors (including watched-root deletion) are treated
-          // as overflow so the renderer conservatively refreshes all visible
-          // tree state rather than trusting possibly-invalid caches (§7.2, §7.3).
+          // Why: treat watcher errors as overflow so the renderer conservatively refreshes rather than trusting possibly-invalid caches (§7.2, §7.3).
           console.error(`[filesystem-watcher] error for ${rootKey}:`, err)
           emitOverflowPayload(rootKey, root)
-          // Why: after a watcher error the native subscription may be invalid
-          // (e.g. watched root was deleted). Tear down the dead watcher so we
-          // don't leave a dangling subscription for a root that no longer
-          // exists on disk (§7.3).
+          // Why: after an error the native subscription may be invalid (deleted root); tear down the dead watcher so it doesn't dangle (§7.3).
           if (root.batch.timer) {
             clearTimeout(root.batch.timer)
           }
-          // Why: the error callback can fire before `watcher.subscribe()`
-          // resolves and assigns root.subscription (e.g. the watched root
-          // is deleted or inaccessible at startup).  Guard against null so
-          // the cleanup path doesn't crash the main process.
+          // Why: error callback can fire before subscribe() assigns root.subscription; guard against null so cleanup doesn't crash.
           if (root.subscription) {
             retainLocalWatcherPhysicalFailure(rootKey, err)
             void trackLocalUnsubscribe(rootKey, root)
@@ -461,25 +408,20 @@ async function createWatcher(
       watcherOptions,
       {
         delivery: { maxEventsPerBatch: MAX_BATCHED_WATCHER_EVENTS },
-        // A child restart or bounded-queue overflow loses path precision; both
-        // require the same conservative renderer refresh.
+        // A child restart or bounded-queue overflow loses path precision; both need the same conservative renderer refresh.
         onInterruption: markWatcherInterrupted,
         onOverflow: markWatcherInterrupted,
         signal
       }
     )
 
-    // Why: if the error callback already fired and cleaned up watchedRoots
-    // before subscribe() resolved, the subscription we just received is
-    // orphaned.  Unsubscribe it immediately to avoid leaking a native
-    // file-watcher handle that no code path would ever clean up.
+    // Why: error callback already cleaned up watchedRoots before subscribe() resolved; unsubscribe this orphaned subscription so it doesn't leak.
     if (errorCleanedUp) {
       void trackLocalUnsubscribe(rootKey, root)
       throw new Error(`Watcher for ${rootKey} errored during subscribe`)
     }
   } catch (err) {
-    // Why: if the watcher backend throws synchronously on a deleted root
-    // or permission error, log rather than crashing the main process (§7.3).
+    // Why: watcher backend can throw synchronously on a deleted root/permission error; log rather than crash the main process (§7.3).
     console.error(`[filesystem-watcher] failed to subscribe ${rootKey}:`, err)
     throw err
   }
@@ -531,8 +473,7 @@ function trackLocalUnsubscribe(rootKey: string, root: WatchedRoot): Promise<void
     })
   pendingLocalUnsubscribes.add(unsubscribePromise)
   rootUnsubscribes.add(unsubscribePromise)
-  // Why: background cleanup must not create unhandled rejections, but the
-  // original promise stays rejected so later destructive cleanup can fail closed.
+  // Why: swallow here to avoid unhandled rejections, but keep the original promise rejected so later destructive cleanup can fail closed.
   void unsubscribePromise.catch((error: unknown) => {
     retainLocalWatcherPhysicalFailure(rootKey, error)
     console.error(`[filesystem-watcher] unsubscribe error for ${rootKey}:`, error)
@@ -631,8 +572,7 @@ async function subscribeWhileRemovalAllowed(
     const inFlight = inFlightLocalInstalls.get(rootKey)
     const canJoinInstall = inFlight && !inFlight.abortController.signal.aborted
     if (canJoinInstall) {
-      // Why: an unwatch may cancel an install while another renderer is still
-      // awaiting the same root; a new live listener should keep it alive.
+      // Why: an unwatch may cancel an install while another renderer awaits the same root; a new live listener keeps it alive.
       addInFlightLocalInstallListener(inFlight, sender)
       for (const listener of capacityRetryListeners) {
         addInFlightLocalInstallListener(inFlight, listener)
@@ -645,8 +585,7 @@ async function subscribeWhileRemovalAllowed(
       !localWatchersClosed &&
       generation === localWatcherLifecycleGeneration
     ) {
-      // Why: AbortSignal cannot be revived. Listeners arriving after physical
-      // cancellation wait out that generation, then own a fresh install.
+      // Why: AbortSignal can't be revived; listeners arriving after cancellation wait out that generation, then own a fresh install.
       if (pendingLocalInstallPromises.get(rootKey) === pendingInstall) {
         pendingLocalInstallPromises.delete(rootKey)
       }
@@ -727,8 +666,7 @@ async function doInstallLocalWatcher(
   }
 
   try {
-    // Why: WSL paths use one snapshot subprocess inside the Linux distro so
-    // `wsl --shutdown` can kill it; native Windows paths use @parcel/watcher.
+    // Why: WSL paths use one snapshot subprocess inside the distro so `wsl --shutdown` can kill it; native Windows uses @parcel/watcher.
     root = isWslPath(worktreePath)
       ? await createWslWatcher(
           rootKey,
@@ -742,8 +680,7 @@ async function doInstallLocalWatcher(
         )
       : await createWatcher(rootKey, rootPath, cancelToken.abortController.signal)
   } catch (error) {
-    // Why: setup may fail after its child misses the exit deadline; retain that
-    // owner even when the ordinary renderer-facing setup error is swallowed.
+    // Why: setup can fail after its child misses the exit deadline; retain that owner even when the renderer-facing error is swallowed.
     retainLocalWatcherPhysicalFailure(rootKey, error)
     if (cancelToken.cancelled) {
       if (isWatcherProcessFailure(error) && error.code === 'process_unavailable') {
@@ -751,8 +688,7 @@ async function doInstallLocalWatcher(
       }
       return 'cancelled'
     }
-    // Why: capacity is transient; once another physical child exits this root
-    // must be allowed to retry instead of entering the permanent-failure cache.
+    // Why: capacity is transient — allow retry once another child exits instead of caching this root as permanently failed.
     if (error instanceof WatcherChildCapacityError) {
       scheduleLocalCapacityRetry(rootKey, worktreePath, cancelToken.listeners)
       return 'capacity'
@@ -802,8 +738,7 @@ function unsubscribe(worktreePath: string, senderId: number): void {
   if (inFlight) {
     inFlight.listeners.delete(senderId)
     inFlight.cancelled = inFlight.listeners.size === 0
-    // Why: same early-cancel as closeLocalWatcherForWorktreePath — last normal
-    // disconnect must abort the pending native/forked install, not let it finish.
+    // Why: last normal disconnect must abort the pending native/forked install (same early-cancel as closeLocalWatcherForWorktreePath).
     if (inFlight.cancelled) {
       inFlight.abortController.abort()
     }
@@ -816,15 +751,13 @@ function unsubscribe(worktreePath: string, senderId: number): void {
 
   root.listeners.delete(senderId)
 
-  // Defer watcher teardown when the last subscriber leaves so rapid
-  // worktree switches can reuse the existing native watcher.
+  // Defer teardown when the last subscriber leaves so rapid worktree switches reuse the native watcher.
   if (root.listeners.size === 0) {
     if (root.batch.timer) {
       clearTimeout(root.batch.timer)
     }
 
-    // Why: duplicate renderer cleanup can call unwatch more than once for a
-    // root; keep one tracked grace timer instead of leaking overwritten timers.
+    // Why: duplicate unwatch calls for a root would leak overwritten grace timers; keep just one.
     if (pendingTeardowns.has(rootKey)) {
       return
     }
@@ -873,8 +806,7 @@ export async function closeLocalWatcherForWorktreePath(worktreePath: string): Pr
 
   const inFlight = inFlightLocalInstalls.get(rootKey)
   if (inFlight) {
-    // Why: Windows keeps watched directories locked; deletion must be able to
-    // cancel an in-flight subscription before Git tries to remove the tree.
+    // Why: Windows locks watched directories; deletion must cancel an in-flight subscription before Git removes the tree.
     inFlight.listeners.clear()
     inFlight.cancelled = true
     inFlight.abortController.abort()
@@ -963,22 +895,13 @@ const pendingRemoteWatcherRetryListeners = new Map<
   string,
   { listeners: Map<number, WebContents>; startedAt: number }
 >()
-// Why: last-listener cleanup aborts relay setup, while late success is still
-// unwatched instead of being installed after the renderer stopped watching.
+// Why: last-listener cleanup aborts relay setup; late success is unwatched rather than installed after the renderer stopped watching.
 const inFlightRemoteInstalls = new Map<string, RemoteWatcherInstallToken>()
-// Why: dedupe concurrent installRemoteWatcher calls for the same key so
-// overlapping fs:watchWorktree IPCs share one native watcher and one listener
-// map, instead of each call independently invoking provider.watch() and
-// overwriting the per-key state on resolution.
+// Why: dedupe concurrent installRemoteWatcher calls per key so overlapping watches share one watcher instead of clobbering per-key state.
 const pendingRemoteInstallPromises = new Map<string, Promise<RemoteWatcherInstallResult>>()
-// Why: block installs that begin AFTER closeAllWatchers — an in-flight joiner
-// recursion or a fired retry tick calls installRemoteWatcher directly, bypassing
-// the token-abort loop. A genuine new fs:watchWorktree clears the latch.
+// Why: block installs beginning after closeAllWatchers (joiner recursion / retry tick bypass the abort loop); a new fs:watchWorktree clears it.
 let remoteWatchersClosed = false
-// Why: the boolean latch alone can't tell a pre-shutdown waiter apart from a
-// fresh call once a genuine new watch reopens the subsystem. Each call captures
-// the generation at entry; closeAllWatchers bumps it, so a joiner that awaited
-// across a shutdown+reopen recurses on a stale generation and is refused.
+// Why: closeAllWatchers bumps this so a joiner that awaited across shutdown+reopen is refused (the latch alone can't tell it from a fresh call).
 let remoteWatcherLifecycleGeneration = 0
 const REMOTE_WATCH_RETRY_MS = 1_000
 const REMOTE_WATCH_RETRY_TIMEOUT_MS = 60_000
@@ -1077,8 +1000,7 @@ function cancelInFlightRemoteInstallIfUnowned(token: RemoteWatcherInstallToken):
     return
   }
   token.abortScheduled = true
-  // Why: a replacement sender can synchronously revive the shared install
-  // during a renderer handoff; otherwise stop the relay crawl next microtask.
+  // Why: a replacement sender can synchronously revive the shared install during a renderer handoff; otherwise stop the relay crawl next microtask.
   queueMicrotask(() => {
     token.abortScheduled = false
     if (token.cancelled && token.listeners.size === 0) {
@@ -1148,10 +1070,7 @@ async function installRemoteWatcher(
   worktreePath: string,
   generation = remoteWatcherLifecycleGeneration
 ): Promise<RemoteWatcherInstallResult> {
-  // Why: refuse installs racing in after teardown (joiner recursion, fired retry
-  // tick) so provider.watch() is never called and registered post-shutdown. The
-  // generation guard also refuses a waiter that captured an earlier lifecycle,
-  // even after a new watch reopened the subsystem.
+  // Why: refuse installs racing in after teardown (or a waiter from an earlier lifecycle) so provider.watch() isn't called post-shutdown.
   if (remoteWatchersClosed || generation !== remoteWatcherLifecycleGeneration) {
     return 'cancelled'
   }
@@ -1185,19 +1104,13 @@ async function installRemoteWatcherWhileRemovalAllowed(
     addRemoteWatchListener(key, sender)
     return 'installed'
   }
-  // Why: a second concurrent fs:watchWorktree for the same key must share the
-  // first call's provider.watch() instead of starting its own. Without this,
-  // both calls would create distinct native watchers and the second's resolve
-  // would overwrite the per-key state, dropping the first's unwatch handle
-  // and erasing its sender from the listener map.
+  // Why: concurrent same-key watches must share the first provider.watch(); separate watchers would clobber per-key state and drop the unwatch handle.
   const pendingInstall = pendingRemoteInstallPromises.get(key)
   if (pendingInstall) {
     const inFlight = inFlightRemoteInstalls.get(key)
     const canJoinInstall = inFlight && !inFlight.abortController.signal.aborted
     if (canJoinInstall) {
-      // Why: a new watcher can join after all previous pending listeners
-      // unwatched but before provider.watch() resolves; revive that install
-      // instead of inheriting the stale cancellation.
+      // Why: a new watcher joining before provider.watch() resolves should revive the install instead of inheriting the stale cancellation.
       addInFlightRemoteInstallListener(inFlight, sender)
     }
     const result = await pendingInstall
@@ -1215,8 +1128,7 @@ async function installRemoteWatcherWhileRemovalAllowed(
       !sender.isDestroyed() &&
       generation === remoteWatcherLifecycleGeneration
     ) {
-      // Why: AbortSignal cannot be revived. A listener arriving after physical
-      // cancellation waits out that generation, then owns a fresh install.
+      // Why: AbortSignal can't be revived; a listener arriving after cancellation waits out that generation, then owns a fresh install.
       if (pendingRemoteInstallPromises.get(key) === pendingInstall) {
         pendingRemoteInstallPromises.delete(key)
       }
@@ -1358,10 +1270,7 @@ function scheduleRemoteWatcherRetry(
     pendingRemoteWatcherRetries.delete(key)
     pendingRemoteWatcherRetryListeners.delete(key)
     loggedUnavailableRemoteWatchers.delete(key)
-    // Why: the original `fs:watchWorktree` handler resolved successfully
-    // when the retry was first scheduled, so the renderer believes the
-    // watch is live. After giving up, emit a one-shot overflow so the
-    // renderer falls back to a manual refresh instead of waiting forever.
+    // Why: handler already resolved so the renderer thinks the watch is live; emit overflow to force a manual refresh instead of waiting forever.
     for (const listener of retry.listeners.values()) {
       if (listener.isDestroyed()) {
         continue
@@ -1387,10 +1296,7 @@ function scheduleRemoteWatcherRetry(
       listeners.map((listener) => installRemoteWatcher(listener, connectionId, worktreePath))
     )
       .then((results) => {
-        // Why: 'cancelled' means an unwatch/shutdown raced with this install
-        // attempt. Re-arming the retry would reschedule for a worktree the
-        // renderer explicitly stopped watching, eventually firing a stale
-        // overflow when the 60s window expires.
+        // Why: don't re-arm on 'cancelled' (renderer stopped watching) — it would fire a stale overflow when the 60s window expires.
         if (results.some((result) => result === 'unavailable')) {
           for (const listener of listeners) {
             scheduleRemoteWatcherRetry(listener, connectionId, worktreePath, retry.startedAt)
@@ -1416,8 +1322,7 @@ export function registerFilesystemWatcherHandlers(): void {
     'fs:watchWorktree',
     async (event, args: { worktreePath: string; connectionId?: string }): Promise<void> => {
       if (args.connectionId) {
-        // Why: a real new watch reopens the subsystem after closeAllWatchers
-        // latched it shut (also how tests reset between cases).
+        // Why: a real new watch reopens the subsystem after closeAllWatchers latched it shut (also resets tests between cases).
         remoteWatchersClosed = false
         const key = remoteWatcherKey(args.connectionId, args.worktreePath)
         const result = await installRemoteWatcher(
@@ -1437,8 +1342,7 @@ export function registerFilesystemWatcherHandlers(): void {
         }
         return
       }
-      // Why: tests and post-shutdown renderer reattachment reopen the local
-      // subsystem, while stale callers retain the prior generation.
+      // Why: reopen the local subsystem for tests and post-shutdown reattachment; stale callers keep the prior generation.
       localWatchersClosed = false
       await subscribe(args.worktreePath, event.sender)
     }
@@ -1462,10 +1366,7 @@ export function registerFilesystemWatcherHandlers(): void {
           pendingRemoteWatcherRetries.delete(key)
           pendingRemoteWatcherRetryListeners.delete(key)
         }
-        // Why: a `provider.watch()` call may still be in flight from a
-        // retry tick. Mark it cancelled so installRemoteWatcher discards
-        // the unwatch handle when the promise finally resolves, instead
-        // of leaving the renderer with a watcher it asked to stop.
+        // Why: a retry-tick provider.watch() may still be in flight; mark cancelled so its resolved unwatch handle is discarded.
         const inFlight = inFlightRemoteInstalls.get(key)
         if (inFlight) {
           inFlight.listeners.delete(_event.sender.id)
@@ -1508,15 +1409,13 @@ export async function closeAllWatchers(): Promise<void> {
   pendingRemoteWatcherRetries.clear()
   pendingRemoteWatcherRetryListeners.clear()
   loggedUnavailableRemoteWatchers.clear()
-  // Why: latch both watcher subsystems shut so late installs cannot register
-  // post-shutdown. Generation bumps also reject waiters from an older lifecycle.
+  // Why: latch both subsystems shut so late installs can't register; generation bumps reject older-lifecycle waiters.
   remoteWatchersClosed = true
   remoteWatcherLifecycleGeneration += 1
   localWatchersClosed = true
   localWatcherLifecycleGeneration += 1
   pendingRemoteInstallPromises.clear()
-  // Why: cancel any in-flight provider.watch() calls so their resolved
-  // unwatch handles are discarded instead of being installed after shutdown.
+  // Why: cancel in-flight provider.watch() calls so their resolved unwatch handles aren't installed post-shutdown.
   for (const token of inFlightRemoteInstalls.values()) {
     token.listeners.clear()
     token.cancelled = true
@@ -1537,15 +1436,10 @@ export async function closeAllWatchers(): Promise<void> {
   watchedRoots.clear()
   await Promise.allSettled(Array.from(pendingLocalUnsubscribes))
   failedLocalUnsubscribes.clear()
-  // Why: with every local subscription released, drop the forked watcher
-  // process outright — process death frees any remaining native handles
-  // without running watcher.node's crash-prone async teardown in this process.
+  // Why: kill the forked watcher process instead of watcher.node's crash-prone async teardown; process death frees native handles.
   disposeWatcherProcess()
 
-  // Why: remote watchers are tracked separately from local @parcel/watcher
-  // subscriptions. Without cleaning them up here, their unwatch callbacks
-  // would never fire, leaving the relay polling for FS changes after the
-  // app has shut down.
+  // Why: remote watchers are separate from local @parcel/watcher subs; unwatch here or the relay keeps polling FS after shutdown.
   for (const [key, state] of remoteWatchers) {
     try {
       state.unwatch()
diff --git a/src/main/ipc/filesystem.ts b/src/main/ipc/filesystem.ts
index aff1a0b6592..725b01c64d4 100644
--- a/src/main/ipc/filesystem.ts
+++ b/src/main/ipc/filesystem.ts
@@ -126,18 +126,11 @@ import { sanitizeLocalDownloadFilename } from '../local-download-filename'
 import { registerFilesystemDownloadFolderHandlers } from './filesystem-download-folder'
 import { createSenderScopedRequestCancellations } from './sender-scoped-request-cancellation'
 
-// Why: Monaco has large-file optimizations like VS Code; blocking at 5MB makes
-// ordinary JSON/log files inaccessible before the editor can degrade features.
+// Why: Monaco degrades features on large files like VS Code, so a 5MB block would needlessly lock out ordinary JSON/log files.
 const MAX_TEXT_FILE_SIZE = 50 * 1024 * 1024 // 50MB
 const BINARY_PROBE_BYTES = 8192
 const FULL_GIT_OBJECT_ID_PATTERN = /^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$/
-// Why: previewable binaries (PDFs, images) are rendered by the viewer as
-// base64 blobs, not parsed as text — 5MB is tight for real-world PDFs, and
-// raising this cap only affects binary preview, not text/search paths.
-// The relay (SSH) uses a smaller 10MB cap because its JSON-RPC frames are
-// bounded by MAX_MESSAGE_SIZE = 16MB; the local IPC path has no such limit,
-// so 50MB covers real-world PDFs (specs, datasheets, image-heavy contracts).
-// See src/relay/fs-handler-utils.ts for the remote-side reasoning.
+// Why: previewable binaries are base64 blobs (not parsed as text), and local IPC has no frame limit (unlike the relay's 10MB), so 50MB is safe.
 const MAX_PREVIEWABLE_BINARY_SIZE = 50 * 1024 * 1024 // 50MB
 const PREVIEWABLE_BINARY_MIME_TYPES: Record<string, string> = {
   '.png': 'image/png',
@@ -210,8 +203,7 @@ type DownloadSession = {
 const DOWNLOAD_SESSION_TTL_MS = 30 * 60 * 1000
 
 function createSiblingTransferPath(destinationPath: string, suffix: string): string {
-  // Why: promotion uses rename/no-clobber operations that must stay on the
-  // destination volume, so transfer paths intentionally remain siblings.
+  // Why: promotion renames must stay on the destination volume, so transfer paths remain siblings.
   return join(dirname(destinationPath), `.${randomUUID()}.${suffix}`)
 }
 
@@ -388,8 +380,7 @@ async function getRepoForSourceControlAi(
     if (repo.connectionId !== args.connectionId) {
       return null
     }
-    // Why: a single SSH connection can host several repos; repo-scoped AI
-    // overrides only apply when the requested worktree belongs to that repo.
+    // Why: one SSH connection can host several repos; repo-scoped AI overrides apply only when the worktree belongs to that repo.
     return (await remoteRepoOwnsWorktree(store, repo, args.worktreePath, args.connectionId))
       ? repo
       : null
@@ -397,8 +388,7 @@ async function getRepoForSourceControlAi(
   if (repo.connectionId) {
     return null
   }
-  // Why: renderer-supplied repoId is advisory; only apply repo overrides when
-  // the requested local worktree is known to belong to that repo.
+  // Why: renderer-supplied repoId is advisory; apply repo overrides only when the local worktree belongs to that repo.
   return (await localRepoOwnsWorktree(store, repo, args.worktreePath)) ? repo : null
 }
 
@@ -459,9 +449,7 @@ async function isDirectoryEntry(
   entry: { name: string; isDirectory(): boolean; isSymbolicLink(): boolean },
   _resolveEntryPath: (entryPath: string) => Promise<string>
 ): Promise<boolean> {
-  // Why: following a symlink just to decorate readDir can touch macOS
-  // TCC-protected app containers. Treat links as file-like until the user
-  // explicitly opens them.
+  // Why: following a symlink in readDir can touch macOS TCC-protected containers; treat links as file-like until explicitly opened.
   void _resolveEntryPath
   if (entry.isSymbolicLink()) {
     void dirPath
@@ -509,10 +497,7 @@ export function registerFilesystemHandlers(
   ipcMain.handle(
     'fs:readDir',
     async (_event, args: { dirPath: string; connectionId?: string }): Promise<DirEntry[]> => {
-      // Why: a thrown fs:readDir reaches the renderer as the opaque "Error
-      // invoking remote method 'fs:readDir'" (Windows WSL/UNC realpath/readdir
-      // failures, dropped SSH providers). Record which throw site fired plus a
-      // redacted path shape so these are diagnosable without the raw path.
+      // Why: fs:readDir throws surface as opaque IPC errors; record the throw site + redacted path shape to keep them diagnosable.
       let throwSite: ReadDirThrowSite = 'authorize'
       try {
         if (args.connectionId) {
@@ -588,17 +573,13 @@ export function registerFilesystemHandlers(
         return {
           content: buffer.toString('base64'),
           isBinary: true,
-          // Why: the renderer/store contract already keys previewable binary
-          // rendering off `isImage`. Keep that legacy flag for PDFs too so the
-          // new preview path stays compatible with existing callers.
+          // Why: the renderer keys previewable-binary rendering off `isImage`, so set it for PDFs too to stay compatible.
           isImage: true,
           mimeType
         }
       }
 
-      // Why: the text cap is intentionally larger than the old binary cap.
-      // Probe unknown large files first so archives do not get fully buffered
-      // just to discover they are not editable text.
+      // Why: probe large unknown files first so archives aren't fully buffered only to discover they aren't editable text.
       if (stats.size > BINARY_PROBE_BYTES && (await isBinaryFilePrefix(filePath))) {
         return { content: '', isBinary: true }
       }
@@ -859,25 +840,17 @@ export function registerFilesystemHandlers(
         const provider = requireSshFilesystemProvider(args.connectionId)
         return provider.deletePath(args.targetPath, args.recursive)
       }
-      // Why: deleting must operate on the symlink itself, not its target.
-      // Following the link with realpath() would trash the real file — which
-      // could be another file inside the worktree, or a path outside all
-      // allowed roots that we would never be able to delete again.
+      // Why: preserve the symlink so we delete the link, not its target (realpath would trash the real file, possibly outside all roots).
       const targetPath = await resolveAuthorizedPath(args.targetPath, store, {
         preserveSymlink: true
       })
 
-      // Why: WSL UNC targets (\\wsl.localhost\<distro>\...) have no Recycle Bin,
-      // so shell.trashItem throws. Hard-delete via `rm` inside the distro instead
-      // (true delete, honors Linux perms). Returns false for normal local paths,
-      // which still go to the Recycle Bin (issue #6415).
+      // Why: WSL UNC targets have no Recycle Bin (shell.trashItem throws), so hard-delete via `rm` inside the distro (issue #6415).
       if (await tryDeleteWslUncPath(targetPath, { recursive: args.recursive })) {
         return
       }
 
-      // Why: once auto-refresh exists, an external delete can race with a
-      // UI-initiated delete. Swallowing ENOENT keeps the action idempotent
-      // from the user's perspective (design §7.1).
+      // Why: swallow ENOENT so an external delete racing this UI delete stays idempotent (design §7.1).
       try {
         await shell.trashItem(targetPath)
       } catch (error) {
@@ -957,10 +930,7 @@ export function registerFilesystemHandlers(
       )
       const searchKey = `${event.sender.id}:${rootPath}`
 
-      // Why: checking rg availability upfront avoids a race condition where
-      // spawn('rg') emits 'close' before 'error' on some platforms, causing
-      // the handler to resolve with empty results before the git-grep
-      // fallback can run. The result is cached after the first check.
+      // Why: probe rg upfront; on some platforms spawn emits 'close' before 'error', resolving empty before the git-grep fallback runs.
       const rgAvailable = await checkRgAvailable(rootPath, localGitOptions.wslDistro)
       if (!rgAvailable) {
         return searchWithGitGrep(rootPath, args, maxResults, localGitOptions)
@@ -969,11 +939,7 @@ export function registerFilesystemHandlers(
       return new Promise((resolvePromise) => {
         const rgArgs = buildRgArgs(args.query, rootPath, args)
 
-        // Why: search requests are fired on each query/options change. If the
-        // previous ripgrep process keeps running, it can continue streaming and
-        // parsing thousands of matches on the Electron main thread after the UI
-        // no longer cares about that result, which is exactly the freeze users
-        // experience in large repos.
+        // Why: kill the prior rg so it stops parsing thousands of matches on the main thread (the large-repo freeze) after the UI moved on.
         activeTextSearches.get(searchKey)?.kill()
 
         const acc = createAccumulator()
@@ -982,8 +948,7 @@ export function registerFilesystemHandlers(
         let child: ChildProcess | null = null
         let killTimeout: ReturnType<typeof setTimeout>
 
-        // Why: WSL-routed rg emits Linux-native paths. UNC repos carry their
-        // distro in the path; Windows-path repos carry it in project runtime.
+        // Why: WSL-routed rg emits Linux paths; UNC repos carry the distro in the path, Windows-path repos in project runtime.
         const wslDistroForOutput = parseWslPath(rootPath)?.distro ?? localGitOptions.wslDistro
         const transformAbsPath = wslDistroForOutput
           ? (p: string): string => (p.startsWith('/') ? toWindowsWslPath(p, wslDistroForOutput) : p)
@@ -998,8 +963,7 @@ export function registerFilesystemHandlers(
             activeTextSearches.delete(searchKey)
           }
           clearTimeout(killTimeout)
-          // Why: child.kill() is advisory. If rg ignores it, detach our
-          // closures so repeated local searches do not retain old scans.
+          // Why: child.kill() is advisory; detach our closures so repeated searches don't retain old scans if rg ignores it.
           child?.stdout?.off('data', handleStdoutData)
           child?.stderr?.off('data', handleStderrData)
           child?.off('error', handleError)
@@ -1049,8 +1013,7 @@ export function registerFilesystemHandlers(
         nextChild.once('error', handleError)
         nextChild.once('close', handleClose)
 
-        // Why: if the timeout fires, the child is killed and results are partial.
-        // We must mark them as truncated so the UI can indicate incomplete results.
+        // Why: timeout kills the child mid-scan; mark truncated so the UI shows incomplete results.
         killTimeout = setTimeout(() => {
           acc.truncated = true
           child?.kill()
@@ -1061,9 +1024,7 @@ export function registerFilesystemHandlers(
   )
 
   // ─── List all files (for quick-open) ─────────────────────
-  // Why #7721: keyed by renderer-generated token so a workspace switch can
-  // abort the previous workspace's full-tree scan (SSH relays otherwise stack
-  // scans that starve interactive fs.readDir/fs.stat past their 30s timeout).
+  // Why #7721: token-keyed so a workspace switch aborts the prior full-tree scan (SSH otherwise stacks scans past the 30s timeout).
   const listFilesCancellations = createSenderScopedRequestCancellations()
   ipcMain.handle(
     'fs:listFiles',
@@ -1080,16 +1041,11 @@ export function registerFilesystemHandlers(
       try {
         if (args.connectionId) {
           const provider = getSshFilesystemProvider(args.connectionId)
-          // Why: when the SSH connection is not yet established (cold start) or
-          // temporarily disconnected, return [] so quick-open shows "No matching
-          // files" instead of an error banner. The file list will repopulate when
-          // the user re-opens quick-open after the connection is restored.
+          // Why: no provider (cold start / disconnected) → return [] so quick-open shows "No matching files" instead of an error.
           if (!provider) {
             return []
           }
-          // Why: forward excludePaths through to the remote provider.
-          // Dropping it here would silently double-scan nested linked worktrees
-          // over SSH and contribute to timeout-induced partial results.
+          // Why: forward excludePaths or nested linked worktrees get double-scanned over SSH, causing timeout-induced partial results.
           return await provider.listFiles(args.rootPath, {
             excludePaths: args.excludePaths,
             signal: controller?.signal
@@ -1136,8 +1092,7 @@ export function registerFilesystemHandlers(
           if (!provider) {
             throw new Error(SSH_GIT_PROVIDER_UNAVAILABLE_MESSAGE)
           }
-          // Why: awaiting here keeps the cancellation token registered until
-          // the remote request settles instead of running finally immediately.
+          // Why: await keeps the cancellation token registered until the remote request settles (an early finally would free it).
           return await provider.getStatus(args.worktreePath, options)
         }
         const worktreePath = await resolveRegisteredWorktreePath(args.worktreePath, store)
@@ -1157,9 +1112,7 @@ export function registerFilesystemHandlers(
     gitStatusCancellations.cancel(event, args.requestToken)
   })
 
-  // Why: the parent status only reports one gitlink row per submodule. When the
-  // user expands a dirty submodule, this fetches the inner per-file changes by
-  // running a plain status inside the submodule's own worktree (read-only).
+  // Why: parent status reports only one gitlink row per submodule; fetch inner per-file changes from the submodule's own worktree.
   ipcMain.handle(
     'git:submoduleStatus',
     async (
@@ -1216,10 +1169,7 @@ export function registerFilesystemHandlers(
     }
   )
 
-  // Why: when status hits the entry limit, the SCM view offers to .gitignore the
-  // folder that's flooding it. These two handlers back that flow. Local-only:
-  // the huge-untracked-folder case is a local-dev pathology, and routing a
-  // .gitignore write through the SSH provider isn't worth the surface here.
+  // Why: backs the SCM "ignore the flooding folder" flow; local-only since huge untracked folders are a local-dev pathology.
   ipcMain.handle(
     'git:findHugeFoldersToIgnore',
     async (_event, args: { worktreePath: string }): Promise<string[]> => {
@@ -1265,9 +1215,7 @@ export function registerFilesystemHandlers(
     }
   )
 
-  // Why: lightweight fs-only check for conflict operation state. Used to poll
-  // non-active worktrees so their "Rebasing"/"Merging" badges clear when the
-  // operation finishes, without running a full `git status`.
+  // Why: fs-only conflict-state check so non-active worktrees can clear their Rebasing/Merging badges without a full git status.
   ipcMain.handle(
     'git:conflictOperation',
     async (
@@ -1854,9 +1802,7 @@ export function registerFilesystemHandlers(
         pushTarget?: GitPushTarget
       }
     ): Promise<void> => {
-      // Why: coerce to strict boolean at the IPC boundary so a malformed
-      // renderer payload (e.g. string 'false') can't silently enable
-      // --set-upstream mode. Mirrors the relay handler in src/relay/git-handler.ts.
+      // Why: coerce to strict boolean so a malformed payload (e.g. string 'false') can't enable --set-upstream; mirror in src/relay/git-handler.ts.
       const publish = args.publish === true
       if (args.connectionId) {
         if (args.pushTarget) {
@@ -2227,8 +2173,7 @@ export function registerFilesystemHandlers(
       _event,
       args: { worktreePath: string; relativePath: string; line: number; connectionId?: string }
     ): Promise<string | null> => {
-      // Why: remote repos can't read relay-side .git/config locally. Delegate
-      // URL construction to the SSH provider, which can fetch remote metadata.
+      // Why: remote repos can't read relay-side .git/config locally; delegate URL construction to the SSH provider.
       if (args.connectionId) {
         const provider = getSshGitProvider(args.connectionId)
         if (!provider) {
@@ -2248,8 +2193,7 @@ export function registerFilesystemHandlers(
       args: { worktreePath: string; sha: string; connectionId?: string }
     ): Promise<string | null> => {
       const sha = validateFullGitObjectId(args.sha, 'sha')
-      // Why: remote repos can't read relay-side .git/config locally. Delegate
-      // URL construction to the SSH provider, which can fetch remote metadata.
+      // Why: remote repos can't read relay-side .git/config locally; delegate URL construction to the SSH provider.
       if (args.connectionId) {
         const provider = getSshGitProvider(args.connectionId)
         if (!provider) {
diff --git a/src/main/ipc/notifications.ts b/src/main/ipc/notifications.ts
index 9d6c825498d..95e9e3e3a47 100644
--- a/src/main/ipc/notifications.ts
+++ b/src/main/ipc/notifications.ts
@@ -58,11 +58,7 @@ const BUILT_IN_NOTIFICATION_SOUNDS: ReadonlyMap<string, string> = new Map([
 ])
 type NotificationSoundId = NotificationSettings['customSoundId']
 
-// Why: Electron Notification objects are normal JS objects — if the only
-// reference is a local variable inside the ipcMain handler, the GC can
-// collect them (and their click handlers) before the user interacts with
-// the notification in macOS Notification Center. Prevent this by keeping a
-// strong reference until the notification is clicked or closed.
+// Why: keep a strong reference so GC can't collect notifications (and their click handlers) before the user interacts with them.
 const activeNotifications = new Set<Notification>()
 const activeNotificationsById = new Map<
   string,
@@ -103,30 +99,18 @@ function retainNotificationUntilRelease(
 const NOTIFICATION_PROBE_RESULT_TIMEOUT_MS = 3000
 const NOTIFICATION_PROBE_BANNER_CLOSE_DELAY_MS = 4000
 
-// Why: Electron has no API to read macOS UNUserNotificationCenter
-// authorization, so the freshest signal we have is what happened to the last
-// notification we scheduled. Session-scoped on purpose: OS-level permission
-// can change between runs, and a stale positive renders a false green card.
+// Why: no API to read macOS auth, so track the last scheduled notification's outcome; session-scoped since permission can change between runs.
 let lastObservedDeliveryOutcome: 'delivered' | 'failed' | null = null
 let deliveryProbeInFlight: Promise<NotificationDeliveryProbeResult> | null = null
-// Why: firing one probe notification is what instantiates Electron's
-// presenter and pops the macOS permission dialog. Once per session is enough
-// while the authorization readout reports the decision as pending.
+// Why: firing one probe instantiates Electron's presenter and pops the macOS permission dialog; once per session is enough.
 let permissionDialogTriggeredThisSession = false
 
 /**
- * Fallback signal for hosts without the native helper. Schedules a silent
- * probe notification and reports whether macOS accepted it. 'failed' means
- * the request was rejected (permission denied, or an unsigned build). On a
- * fresh install the probe also instantiates Electron's notification
- * presenter, which is what makes macOS pop the "Allow notifications?" dialog.
+ * Fallback for hosts without the native helper: schedules a silent probe and reports whether macOS accepted it.
+ * On a fresh install the probe also instantiates Electron's presenter, which pops the macOS permission dialog.
  *
- * Known ambiguity with no public API to resolve it (verified on macOS 26):
- * while the dialog is unanswered — and when notifications are toggled off in
- * System Settings after being authorized — macOS still accepts requests and
- * silently swallows them, so 'delivered' can over-report. 'failed' fires for
- * hard rejections (unsigned builds, dialog-level denial). The bundled
- * notification-status helper exists precisely to avoid this ambiguity.
+ * Known ambiguity (verified macOS 26): while undecided, or when notifications are toggled off after being
+ * authorized, macOS silently swallows accepted requests, so 'delivered' can over-report; only 'failed' is definitive.
  */
 function probeNotificationDelivery(): Promise<NotificationDeliveryProbeResult> {
   if (deliveryProbeInFlight) {
@@ -167,9 +151,7 @@ function probeNotificationDelivery(): Promise<NotificationDeliveryProbeResult> {
 
     function onShow(): void {
       settle('delivered')
-      // Why: when delivery works the probe banner is visible, so it doubles
-      // as the user-facing confirmation — let it linger briefly instead of
-      // vanishing the instant it appears.
+      // Why: the probe banner doubles as the user-facing confirmation, so let it linger briefly instead of vanishing instantly.
       const closeTimer = setTimeout(releaseProbe, NOTIFICATION_PROBE_BANNER_CLOSE_DELAY_MS)
       if (typeof closeTimer.unref === 'function') {
         closeTimer.unref()
@@ -177,17 +159,14 @@ function probeNotificationDelivery(): Promise<NotificationDeliveryProbeResult> {
     }
 
     function onFailed(_event: unknown, _error?: string): void {
-      // Why: a rejected probe is an expected outcome (denied permission), not
-      // an anomaly — logging it would spam the console on every poll while
-      // the onboarding card waits for the user to allow notifications.
+      // Why: a rejected probe is expected (denied permission); don't log — it would spam the console on every poll.
       settle('blocked')
       releaseProbe()
     }
 
     probe.once('show', onShow)
     probe.once('failed', onFailed)
-    // Why: don't record a 'failed' outcome on timeout — a missing callback is
-    // ambiguous, while the 'failed' event is a definitive rejection.
+    // Why: don't record 'failed' on timeout — a missing callback is ambiguous, only the 'failed' event is definitive.
     timeoutTimer = setTimeout(() => {
       if (!settled) {
         settled = true
@@ -330,8 +309,7 @@ function reserveNotificationCooldown(
 export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntimeService): void {
   const recentDesktopNotifications = new Map<string, number>()
   const recentMobileNotifications = new Map<string, number>()
-  // Why: handler registration marks a fresh session — permission evidence
-  // from a previous registration must not leak into the new one.
+  // Why: handler registration marks a fresh session; permission evidence from a previous one must not leak in.
   lastObservedDeliveryOutcome = null
   deliveryProbeInFlight = null
   permissionDialogTriggeredThisSession = false
@@ -343,13 +321,7 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
     openNotificationSystemSettings()
   })
 
-  // Why: Electron's main-process `Notification` class exposes no synchronous
-  // way to read macOS auth status — the renderer-side `Notification.permission`
-  // does not exist here. We expose what we can reliably observe: whether the
-  // platform supports notifications and whether we've already kicked off the
-  // first-permission prompt. A 'denied' OS result is invisible to us; the
-  // dispatch path simply won't deliver in that case, which the user can
-  // diagnose via the System Settings deep-link.
+  // Why: Electron's main process can't read macOS auth status; expose only what we can observe (platform support + whether we've prompted).
   const getPermissionStatus = (): NotificationPermissionStatusResult => ({
     supported: Notification.isSupported(),
     platform: process.platform,
@@ -360,20 +332,15 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
   ipcMain.handle(
     'notifications:probeDelivery',
     async (_event, args?: { force?: boolean }): Promise<NotificationDeliveryProbeResult> => {
-      // Why: macOS-only. Windows/Linux have no equivalent first-use permission
-      // dialog, so the onboarding card that consumes this never renders there.
+      // Why: macOS-only — Windows/Linux have no first-use permission dialog, so the onboarding card never renders there.
       if (process.platform !== 'darwin' || !Notification.isSupported()) {
         return { state: 'unsupported', authoritative: false }
       }
-      // Why: probes (and the native helper's first-launch path) surface the
-      // macOS permission dialog — mark the one-shot startup registration as
-      // done so it can't fire a second prompt later.
+      // Why: probes surface the macOS permission dialog, so mark startup registration done to avoid a second prompt later.
       if (store.getUI().notificationPermissionRequested !== true) {
         store.updateUI({ notificationPermissionRequested: true })
       }
-      // Preferred source: the bundled helper reads the real
-      // UNUserNotificationCenter authorization. Silent, so polling with it
-      // tracks System Settings changes live without flashing banners.
+      // Preferred source: the bundled helper reads real auth silently, so polling tracks System Settings changes without banners.
       const authorization = await readNotificationAuthorizationStatus()
       if (authorization === 'authorized') {
         lastObservedDeliveryOutcome = 'delivered'
@@ -384,16 +351,13 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
         return { state: 'blocked', authoritative: true }
       }
       if (authorization === 'not-determined') {
-        // Why: the dialog only appears once something asks — fire a single
-        // probe per session to trigger it, then report the pending decision.
+        // Why: the dialog only appears once something asks; fire one probe per session to trigger it, then report pending.
         if (!permissionDialogTriggeredThisSession) {
           void probeNotificationDelivery()
         }
         return { state: 'awaiting-decision', authoritative: true }
       }
-      // Helper unavailable ('unknown' status is also unusable evidence):
-      // fall back to scheduling-based probes with session caching, which
-      // avoids repeated probe banners when delivery works.
+      // Helper unavailable or 'unknown': fall back to scheduling-based probes with session caching to avoid repeated banners.
       if (!args?.force && lastObservedDeliveryOutcome !== null) {
         return {
           state: lastObservedDeliveryOutcome === 'delivered' ? 'delivered' : 'blocked',
@@ -429,15 +393,7 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
       _event,
       args: NotificationDispatchRequest
     ): NotificationDispatchResult | Promise<NotificationDispatchResult> => {
-      // Why: a terminal bell or agent completion that arrives while the window
-      // is minimized/hidden lights the tray attention dot — a passive cue that
-      // clears on window show/restore (see index.ts). Placed before the
-      // focus-suppression, cooldown, and enabled gates below so those do not
-      // hold back the dot. It rides the notification dispatch, so it follows the
-      // renderer's per-source decision to notify: bells always reach here, while
-      // an agent completion is suppressed upstream when its notification is
-      // disabled. The status item exists on Windows and macOS, so
-      // setTrayAttention lights its attention dot there and no-ops on Linux.
+      // Why: light the tray attention dot before the cooldown/focus/enabled gates so they can't hold it back (clears on window show/restore; see index.ts).
       if (args.source === 'agent-task-complete' || args.source === 'terminal-bell') {
         const activeWindow = BrowserWindow.getAllWindows().find((win) => !win.isDestroyed()) ?? null
         if (!isMainWindowVisible(activeWindow)) {
@@ -459,8 +415,7 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
 
       const notificationOptions = buildNotificationOptions(args)
 
-      // Why: desktop focus only means this computer has the worktree visible;
-      // the paired phone may be locked or elsewhere and still needs the alert.
+      // Why: desktop focus only means this computer sees the worktree; the paired phone may still need the alert.
       if (runtime && args.source !== 'test') {
         const dedupeKey = args.worktreeId ?? args.worktreeLabel ?? 'global'
         if (reserveNotificationCooldown(recentMobileNotifications, dedupeKey, Date.now())) {
@@ -486,11 +441,9 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
         return { delivered: false, reason: 'suppressed-focus' }
       }
 
-      // Why: the Settings test button is an explicit user action, often
-      // clicked repeatedly while tuning sounds, so it must bypass burst dedupe.
+      // Why: the Settings test button is an explicit, often-repeated user action, so it bypasses burst dedupe.
       if (args.source !== 'test') {
-        // Dedupe by worktree, not by source — an agent finishing and a terminal bell
-        // often fire within the same data chunk so only the first one should surface.
+        // Dedupe by worktree, not source — agent-finish and terminal-bell often fire in one chunk; surface only the first.
         const dedupeKey = args.worktreeId ?? args.worktreeLabel ?? 'global'
         if (!reserveNotificationCooldown(recentDesktopNotifications, dedupeKey, Date.now())) {
           return { delivered: false, reason: 'cooldown' }
@@ -507,8 +460,7 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
         if (getEffectiveNotificationSoundId(settings) !== 'system') {
           notificationOptions.silent = true
         } else if (process.platform === 'darwin') {
-          // Why: macOS treats an unset notification sound as silent. When Orca is
-          // using the OS sound, ask Electron for the default notification sound.
+          // Why: macOS treats an unset sound as silent, so request Electron's default when using the OS sound.
           notificationOptions.sound = 'default'
         }
         const notification = new Notification(notificationOptions)
@@ -520,8 +472,7 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
           }
         }
 
-        // Why: prevent GC from collecting the notification (and its click
-        // handler) while it's still visible in macOS Notification Center.
+        // Why: prevent GC from collecting the notification and its click handler while it's still visible.
         let clickHandler: (() => void) | null = null
         let failedHandler: ((_event: unknown, error?: string) => void) | null = null
         const entryForId: { notification: Notification; release: () => void } | null =
@@ -548,24 +499,15 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
         }
 
         failedHandler = (_event, error) => {
-          // Why: Electron 42's macOS UNNotification backend reports unsigned
-          // apps and native delivery errors here; release immediately instead
-          // of retaining a dead notification until the fallback timer.
+          // Why: Electron 42's macOS backend reports unsigned/delivery failures here; release now, not after the fallback timer.
           logNativeNotificationFailure(args.source, error)
-          // A definitive rejection — feeds the permission card's evidence.
+          // Why: feeds the permission card's evidence.
           lastObservedDeliveryOutcome = 'failed'
           release()
         }
         notification.on('failed', failedHandler)
 
-        // Why: clicking a notification should bring Orca to the foreground and
-        // switch to the worktree/pane that triggered it. Worktree activation owns
-        // repo/sidebar state; the optional focusTerminal follow-up uses the stable
-        // pane leaf id so split-pane notifications land on the exact pane.
-        // Why: worktreeId is formatted as "repoId::worktreePath".  If the
-        // separator is missing we cannot reliably extract a repoId, so skip
-        // the click-to-navigate binding — the notification still fires but
-        // clicking it will not attempt to switch to an unknown worktree.
+        // Why: worktreeId is formatted "repoId::worktreePath"; without the separator we can't extract a repoId, so skip the click-to-navigate binding.
         if (args.worktreeId && args.worktreeId.includes('::')) {
           const repoId = getRepoIdFromWorktreeId(args.worktreeId)
           clickHandler = () => {
@@ -585,6 +527,7 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
               repoId,
               worktreeId: args.worktreeId
             })
+            // Why: focusTerminal targets the pane by stable leafId so split-pane notifications land on the exact pane.
             const paneTarget = args.paneKey ? parsePaneKey(args.paneKey) : null
             if (paneTarget) {
               win.webContents.send('ui:focusTerminal', {
@@ -622,12 +565,7 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
       if (process.platform !== 'darwin') {
         return deliverNativeNotification()
       }
-      // Why: macOS silently swallows accepted notifications while permission
-      // is denied or the permission dialog is unanswered (verified on macOS
-      // 26). Skip the doomed native notification and tell the caller, so the
-      // renderer can surface an in-app fallback pointing at System Settings.
-      // The mobile dispatch above is unaffected — paired devices have their
-      // own notification channel.
+      // Why: macOS silently swallows notifications while permission is denied/undecided (verified macOS 26); skip so the renderer can show a fallback.
       return readNotificationAuthorizationStatus().then((authorization) => {
         if (authorization === 'denied' || authorization === 'not-determined') {
           lastObservedDeliveryOutcome = 'failed'
@@ -638,10 +576,7 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
     }
   )
 
-  // Why: the preload caches the decoded blob keyed by path. Returning just
-  // the validated path lets it skip the 10MB IPC round-trip on every dispatch
-  // when the user's selection hasn't changed — terminal-bell bursts can fire
-  // many notifications in seconds.
+  // Why: return the path so the preload's path-keyed cache skips the 10MB IPC round-trip on repeat dispatches.
   ipcMain.removeHandler('notifications:resolveSoundPath')
   ipcMain.handle(
     'notifications:resolveSoundPath',
@@ -692,20 +627,15 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
 }
 
 /**
- * On first launch, when macOS notification permission is 'not-determined',
- * show a welcome notification to trigger the system permission dialog.
+ * On first launch (macOS permission 'not-determined'), show a welcome notification to trigger the system prompt.
  *
- * Why: macOS requires at least one notification attempt before the system
- * will prompt the user to allow/deny. Doing this at startup with meaningful
- * content avoids a confusing blank notification later. The notification is
- * closed shortly after to avoid lingering in Notification Center.
+ * Why: macOS requires at least one notification attempt before it will prompt to allow/deny.
  */
 export function triggerStartupNotificationRegistration(store: Store): void {
   if (process.platform !== 'darwin' || !Notification.isSupported()) {
     return
   }
-  // Why: only fire once per install — not on every launch where status stays
-  // not-determined (e.g. if the user dismisses the macOS dialog without choosing).
+  // Why: fire once per install, not on every launch where status stays not-determined (e.g. user dismisses the dialog).
   const ui = store.getUI()
   if (ui.notificationPermissionRequested) {
     return
@@ -717,8 +647,7 @@ export function triggerStartupNotificationRegistration(store: Store): void {
     body: 'Allow notifications so Orca can alert you when agents finish or terminals need attention.'
   })
 
-  // Why: prevent GC from collecting the notification (and its click handler)
-  // while it's still visible in macOS Notification Center.
+  // Why: prevent GC from collecting the notification and its click handler while it's still visible.
   activeNotifications.add(notification)
 
   let handled = false
@@ -749,19 +678,14 @@ export function triggerStartupNotificationRegistration(store: Store): void {
     notification.close()
   }
 
-  // Why: clicking the startup notification should take the user to macOS
-  // Notification Settings so they can verify/enable notifications for Orca.
-  // Without this, the notification reads like an actionable prompt ("Allow
-  // notifications…") but clicking it does nothing, which is confusing.
+  // Why: the body reads like an actionable "Allow notifications…" prompt, so clicking opens macOS Notification Settings.
   function onClick(): void {
     cleanup()
     openNotificationSystemSettings()
   }
 
   function onShow(): void {
-    // Why: close after a short delay so the notification doesn't linger in
-    // Notification Center. The macOS permission dialog is a system-level sheet
-    // that appears independently and is not dismissed by closing this notification.
+    // Why: close after a delay so the banner doesn't linger; the macOS permission sheet is separate and unaffected.
     closeTimer = setTimeout(cleanup, 8000)
     if (typeof closeTimer.unref === 'function') {
       closeTimer.unref()
@@ -769,8 +693,7 @@ export function triggerStartupNotificationRegistration(store: Store): void {
   }
 
   function onFailed(_event: unknown, error?: string): void {
-    // Why: Electron 42 requires code-signed macOS apps for UNNotification
-    // delivery. Unsigned builds fail here instead of producing the permission UI.
+    // Why: Electron 42 requires code-signed macOS apps for UNNotification delivery; unsigned builds fail here.
     logNativeNotificationFailure('startup registration', error)
     lastObservedDeliveryOutcome = 'failed'
     cleanup()
diff --git a/src/main/ipc/pet.ts b/src/main/ipc/pet.ts
index 8e4b0d60ea0..df48249f001 100644
--- a/src/main/ipc/pet.ts
+++ b/src/main/ipc/pet.ts
@@ -14,9 +14,7 @@ import {
   type ResolvedPetManifest
 } from './pet-bundle'
 
-// Why: image-only pet uploads. Static + animated variants render natively
-// via <img>, so no 3D engine is needed. Main owns the accepted-format table as
-// the single source of truth for what the renderer will try to display.
+// Why: pets are image-only — render natively via <img> (no 3D engine); main owns this format allowlist.
 const IMAGE_FORMATS: Record<string, string> = {
   '.png': 'image/png',
   '.apng': 'image/apng',
@@ -36,9 +34,7 @@ function classifyFile(src: string): { mimeType: string; ext: string } | null {
   return { mimeType: mime, ext }
 }
 
-// Why: keep using the legacy sidekicks folder so existing user-uploaded pets
-// keep rendering after the product rename. The renderer only knows CustomPet.id;
-// main resolves it to an absolute path inside this folder.
+// Why: keep the legacy `sidekicks` folder so existing user-uploaded pets keep rendering after the product rename.
 function getPetsDir(): string {
   return join(app.getPath('userData'), 'sidekicks', 'custom')
 }
@@ -47,9 +43,7 @@ const MAX_BYTES = 64 * 1024 * 1024 // 64 MB — generous but bounded so a user c
 const MAX_MANIFEST_BYTES = 64 * 1024 // pet.json is tiny by spec; cap to defend against a malicious bundle stuffing megabytes into the manifest.
 
 function isSafeId(id: string): boolean {
-  // UUIDs only; blocks path traversal and unexpected characters. Storage ids
-  // are always generated in main (never sourced from the bundle's manifest.id),
-  // so this regex is the canonical gate for any fs path that includes the id.
+  // UUIDs only — canonical path-traversal gate; storage ids are always main-generated, never from manifest.id.
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)
 }
 
@@ -61,9 +55,7 @@ function resolvePetFile(id: string, fileName: string, kind: 'image' | 'bundle'):
   const root = normalize(getPetsDir())
   let filePath: string
   if (kind === 'bundle') {
-    // Bundle layout: custom/<id>/<fileName>. fileName is just the spritesheet
-    // basename (e.g. "spritesheet.webp"); pet.json is read by main only and
-    // never served to the renderer.
+    // Bundle layout custom/<id>/<fileName>; fileName is the spritesheet basename — pet.json is main-only, never served.
     filePath = normalize(join(root, id, safeName))
     const bundleDir = normalize(join(root, id)) + sep
     if (!filePath.startsWith(bundleDir)) {
@@ -71,8 +63,7 @@ function resolvePetFile(id: string, fileName: string, kind: 'image' | 'bundle'):
     }
     return filePath
   }
-  // Legacy image layout: custom/<id>.<ext>. Filename must start with the id
-  // so the prefix check catches any edge case that slipped the regex.
+  // Legacy image layout custom/<id>.<ext>; filename must start with the id so the prefix check backstops the regex.
   if (!safeName.startsWith(`${id}.`)) {
     return null
   }
@@ -92,8 +83,7 @@ const PetManifestSchema = z
       .string()
       .min(1)
       .max(255)
-      // Why: belt-and-suspenders against malicious manifests — downstream
-      // resolve+prefix check still runs as defense in depth.
+      // Why: belt-and-suspenders vs malicious manifests — downstream resolve+prefix check still runs as defense in depth.
       .refine(
         (p) => !p.includes('\0') && !p.startsWith('/') && !p.startsWith('\\') && !p.includes('..'),
         'invalid spritesheetPath'
@@ -119,16 +109,12 @@ const PetManifestSchema = z
       )
       .optional()
   })
-  // Why: tolerate unknown top-level fields. Pet-bundle generators may emit
-  // descriptive metadata (e.g. "kind": "person") we don't consume yet, and
-  // strict mode would reject those imports with a confusing "unrecognized
-  // key" error instead of just ignoring the extras.
+  // Why: .loose() ignores unknown manifest fields — generators emit metadata we don't consume; strict would reject imports.
   .loose()
 
 type PetManifest = z.infer<typeof PetManifestSchema> & PetManifestLike
 
-// Why: renderer-supplied IPC inputs are untrusted — validate shape before any
-// path resolution. resolvePetFile still gates the actual filesystem path.
+// Why: renderer IPC inputs are untrusted — validate shape here; resolvePetFile still gates the actual filesystem path.
 const PetFileRequestSchema = z.object({
   id: z.string(),
   fileName: z.string(),
@@ -138,17 +124,13 @@ const PetFileRequestSchema = z.object({
 async function readSheetDimensions(
   buffer: Buffer
 ): Promise<{ width: number; height: number } | null> {
-  // Why: Electron's nativeImage can fail to decode some valid WebP variants
-  // even though Chromium can render them. Sprite sheets only need the canvas
-  // size, so read WebP dimensions from the container header before falling
-  // back to native decoding.
+  // Why: nativeImage can fail on some valid WebP that Chromium renders — read WebP dims from the header before native decode.
   const webpDims = readWebpDimensionsFromBuffer(buffer)
   if (webpDims) {
     return webpDims
   }
 
-  // Why: nativeImage decodes PNG/JPEG/GIF/WebP/BMP. SVG isn't supported here
-  // (vector → no integer pixel grid), so pet bundles must use a raster sheet.
+  // Why: nativeImage can't decode SVG (vector → no pixel grid) — pet bundles must use a raster sheet.
   const image = nativeImage.createFromBuffer(buffer)
   if (image.isEmpty()) {
     return null
@@ -160,12 +142,7 @@ async function readSheetDimensions(
   return { width: size.width, height: size.height }
 }
 
-// Why: TOCTOU defense — between the `isSymlink` check and `copyFile`, a local
-// attacker with write access to the bundle dir could swap the file with a
-// symlink (copyFile follows symlinks). Open with O_NOFOLLOW so the open fails
-// outright if the path is a symlink at the moment of open, then stream from
-// the fd. On platforms without O_NOFOLLOW (Windows), the constant is undefined
-// and we fall back to copyFile — symlinks aren't a meaningful threat there.
+// Why: TOCTOU symlink-swap defense — O_NOFOLLOW makes open() fail on a symlink; Windows lacks it, so fall back to copyFile.
 async function copyFileNoFollow(src: string, dest: string): Promise<void> {
   const noFollow = typeof fsConstants.O_NOFOLLOW === 'number' ? fsConstants.O_NOFOLLOW : 0
   if (noFollow === 0) {
@@ -196,11 +173,7 @@ export function registerPetHandlers(): void {
     const options: Electron.OpenDialogOptions = {
       title: 'Pick pet',
       properties: ['openFile'],
-      // Why: single filter and no `apng` extension. macOS file dialogs map
-      // filter extensions to UTIs; `apng` has no registered UTI, so including
-      // it can drop sibling extensions (notably `webp`) from the allowed set.
-      // APNG files carry the `.png` extension and are detected from magic
-      // bytes by the browser.
+      // Why: omit `apng` — macOS maps dialog extensions to UTIs, and apng's missing UTI can drop siblings like webp (APNG uses .png anyway).
       filters: [
         {
           name: 'Pet image',
@@ -237,9 +210,7 @@ export function registerPetHandlers(): void {
     const dir = getPetsDir()
     await mkdir(dir, { recursive: true })
     const id = randomUUID()
-    // Why: preserve original extension in the on-disk name so pet:read can
-    // rebuild the right Blob MIME via resolvePetFile without a separate
-    // lookup. The extension is only ever written by main (never the renderer).
+    // Why: keep the original extension in the on-disk name so pet:read can rebuild the Blob MIME without a separate lookup.
     const fileName = `${id}${classified.ext}`
     const dest = join(dir, fileName)
     try {
@@ -263,9 +234,7 @@ export function registerPetHandlers(): void {
   ipcMain.handle('pet:importPetBundle', async (event): Promise<CustomPet | null> => {
     const senderWindow =
       BrowserWindow.fromWebContents(event.sender) ?? BrowserWindow.getFocusedWindow()
-    // Why: the bundle is a folder. macOS users may also pick `pet.json` itself
-    // when Finder is set to show package contents — the post-pick logic walks
-    // up to the parent directory in that case.
+    // Why: the bundle is a folder, but Finder may let users pick `pet.json` inside it — post-pick logic walks up to the parent.
     const options: Electron.OpenDialogOptions = {
       title: 'Pick a .codex-pet bundle',
       properties: ['openFile', 'openDirectory', 'treatPackageAsDirectory']
@@ -302,8 +271,7 @@ export function registerPetHandlers(): void {
     let manifest: ResolvedPetManifest<PetManifest>
     try {
       const raw = await readFile(manifestPath, 'utf8')
-      // Why: defend against TOCTOU between stat and read — the file could have
-      // grown after the stat check.
+      // Why: defend against TOCTOU — the file may have grown between the stat check and this read.
       if (Buffer.byteLength(raw, 'utf8') > MAX_MANIFEST_BYTES) {
         throw new Error('pet.json exceeded the manifest size limit.')
       }
@@ -312,11 +280,7 @@ export function registerPetHandlers(): void {
       throw new Error(`Invalid pet.json: ${error instanceof Error ? error.message : 'parse error'}`)
     }
 
-    // Why: spritesheetPath is bundle-relative. Codex pet.json files omit this
-    // path and use a fixed `spritesheet.webp`; applyCodexPetDefaults fills
-    // that shape before path validation. Reject absolute paths and any resolved
-    // path that escapes the bundle directory. Also reject symlinks so a
-    // malicious bundle can't reach outside via a sibling link.
+    // Why: spritesheetPath is bundle-relative and attacker-controlled — reject absolute/escaping paths (and symlinks) so a bundle can't reach outside.
     const normalizedSpritePath = manifest.spritesheetPath.replace(/[\\/]+/g, sep)
     if (
       isAbsolute(manifest.spritesheetPath) ||
@@ -325,17 +289,14 @@ export function registerPetHandlers(): void {
     ) {
       throw new Error('spritesheetPath must be relative to the bundle.')
     }
-    // Why: pet bundles may be exported on Windows and imported on macOS/Linux;
-    // normalize manifest separators before Node resolves the bundle-relative path.
+    // Why: bundles exported on Windows may be imported on macOS/Linux; normalize separators before resolving.
     const sheetSrc = resolve(bundleDir, normalizedSpritePath)
     const bundleResolved = resolve(bundleDir)
     if (sheetSrc === bundleResolved) {
       throw new Error('spritesheetPath must point to a file, not the bundle root.')
     }
     const bundleRoot = bundleResolved + sep
-    // Why: NTFS/macOS HFS+ default volumes are case-insensitive — a path like
-    // `BUNDLE\sheet.png` is still inside `bundle\`. Compare lowercased on
-    // Windows so the prefix check isn't bypassed by case differences.
+    // Why: Windows volumes are case-insensitive; lowercase the prefix compare so case differences can't bypass the escape check.
     const cmp = process.platform === 'win32' ? (s: string) => s.toLowerCase() : (s: string) => s
     if (!cmp(sheetSrc + sep).startsWith(cmp(bundleRoot))) {
       throw new Error('spritesheetPath escapes the bundle.')
@@ -365,10 +326,7 @@ export function registerPetHandlers(): void {
 
     let sprite: NonNullable<CustomPet['sprite']> | undefined
     if (manifest.frame) {
-      // Why: only decode the sheet when we need to validate frame layout.
-      // nativeImage may fail on some WebP variants in headless contexts, and
-      // bundles without `frame` render as a static image where dimensions
-      // don't matter.
+      // Why: only decode when a frame layout needs validating — nativeImage can fail on some WebP variants in headless contexts.
       const sheetBuf = await readFile(sheetSrc)
       // Why: defend against TOCTOU — file may have grown between stat and read.
       if (sheetBuf.byteLength > MAX_BYTES) {
@@ -419,19 +377,14 @@ export function registerPetHandlers(): void {
       }
     }
 
-    // Why: storage id is always a fresh UUID — the manifest's `id` is purely
-    // a display hint. This guards against (a) collisions with bundled
-    // pet ids, (b) failing isSafeId, and (c) re-import clobbering an
-    // earlier copy of the same bundle.
+    // Why: always a fresh UUID (not the manifest's display-hint id) to avoid collisions, unsafe ids, and re-import clobbering.
     const id = randomUUID()
     const root = getPetsDir()
     await mkdir(root, { recursive: true })
     const destDir = join(root, id)
     const sheetExt = sheetClass.ext
     const sheetFileName = `spritesheet${sheetExt}`
-    // Why: stage the bundle into a sibling .tmp directory and atomically rename
-    // into place so destDir only appears once both files are written. Avoids
-    // half-imported bundles if a copy fails midway.
+    // Why: stage into a sibling .tmp then atomically rename, so a mid-copy failure can't leave a half-imported bundle.
     const tmpDir = `${destDir}.tmp`
     try {
       await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
@@ -453,8 +406,7 @@ export function registerPetHandlers(): void {
       mimeType: sheetClass.mimeType,
       kind: 'bundle',
       sprite,
-      // Why: carries manifest.fps for detected-frame bundles where `sprite`
-      // is undefined — renderer falls back to this when sprite is absent.
+      // Why: renderer falls back to spriteFps when sprite is undefined (detected-frame bundles).
       ...(manifest.fps !== undefined ? { spriteFps: manifest.fps } : {})
     }
   })
@@ -467,16 +419,14 @@ export function registerPetHandlers(): void {
       fileName: string,
       kind?: 'image' | 'bundle'
     ): Promise<ArrayBuffer | null> => {
-      // Why: validate IPC inputs before any path logic — renderer is not
-      // trusted to send strings of the right shape.
+      // Why: renderer inputs are untrusted; validate shape before any path logic.
       let parsed: z.infer<typeof PetFileRequestSchema>
       try {
         parsed = PetFileRequestSchema.parse({ id, fileName, kind })
       } catch {
         throw new Error('Invalid pet:read arguments')
       }
-      // Why: missing kind defaults to 'image' for backwards compatibility with
-      // pre-bundle persisted state.
+      // Why: default 'image' for backwards compat with pre-bundle persisted state.
       const filePath = resolvePetFile(parsed.id, parsed.fileName, parsed.kind ?? 'image')
       if (!filePath) {
         return null
@@ -505,9 +455,7 @@ export function registerPetHandlers(): void {
         return
       }
       if ((parsed.kind ?? 'image') === 'bundle') {
-        // Why: bundle imports own a whole directory. isSafeId already gates id;
-        // we still build the path under the pets root and verify the
-        // prefix before recursive removal as defense in depth.
+        // Why: defense in depth — verify path stays under pets root before recursive removal.
         const root = normalize(getPetsDir())
         const target = normalize(join(root, parsed.id))
         if (!target.startsWith(root + sep)) {
diff --git a/src/main/ipc/pty-management.ts b/src/main/ipc/pty-management.ts
index 9459984c5e3..f188fb3aad5 100644
--- a/src/main/ipc/pty-management.ts
+++ b/src/main/ipc/pty-management.ts
@@ -5,15 +5,7 @@ import type { DaemonPtyAdapter } from '../daemon/daemon-pty-adapter'
 import { getDaemonProvider, restartDaemon } from '../daemon/daemon-init'
 import type { DaemonSessionInfo } from '../daemon/types'
 
-// Why: the daemon's session.kill() sends SIGTERM first and escalates to
-// SIGKILL after a 5s grace window (KILL_TIMEOUT_MS in session.ts). We have
-// to poll past that ladder, or well-behaved-but-slow shells (zsh hosting a
-// long-running agent) look like they "refused to exit" when they're actually
-// still inside their SIGTERM handler waiting for SIGKILL. 65 polls at 100ms
-// each (≈6.5s) covers the 5s ladder plus ~1.5s of slack for the final
-// SIGKILL reap and the adapter's listSessions IPC roundtrip. The user waits
-// during this window with a spinner; the alternative — reporting fake
-// "refused" numbers — is worse.
+// Why: poll past the daemon's 5s SIGTERM→SIGKILL ladder (KILL_TIMEOUT_MS in session.ts), else slow-exiting shells falsely look "refused".
 const MAX_POLL_ATTEMPTS = 65
 const POLL_INTERVAL_MS = 100
 
@@ -32,9 +24,7 @@ function getDaemonAdapters(): DaemonPtyAdapter[] {
   return [provider]
 }
 
-// Why: surface degraded mode (daemon alive but cannot spawn fresh PTYs) so the
-// session-management UI can warn that new terminals lack daemon persistence
-// until the daemon is restarted, instead of it being a silent console.warn.
+// Why: surface degraded mode (daemon alive but cannot spawn fresh PTYs) so the UI can warn new terminals lack persistence.
 function isDaemonDegraded(): boolean {
   return getDaemonProvider() instanceof DegradedDaemonPtyProvider
 }
@@ -66,12 +56,7 @@ export function registerDaemonManagementHandlers(): void {
     }
   )
 
-  // Why: killAll operates on *sessions* (user-facing concept), not daemons, so
-  // it fans across every adapter — current + legacy — to match the user's
-  // "kill everything I might be attached to" mental model. The daemon
-  // processes themselves survive; only sessions are torn down. See
-  // docs/daemon-staleness-ux.md §Phase 1 "Scope rationale" for why legacy
-  // daemons aren't killed here.
+  // Why: tears down sessions across all adapters (current + legacy); daemon processes survive. See docs/daemon-staleness-ux.md §Phase 1.
   ipcMain.handle(
     'pty:management:killAll',
     async (): Promise<{
@@ -80,12 +65,7 @@ export function registerDaemonManagementHandlers(): void {
       killedSessionIds: string[]
     }> => {
       const adapters = getDaemonAdapters()
-      // Why: snapshot the initial session set once, up front. All subsequent
-      // accounting is relative to these IDs. If the renderer respawns panes
-      // with *fresh* session IDs while we're polling (e.g. a remount fires
-      // pty:spawn mid-kill), those new sessions must not count as
-      // "remaining" — the user asked to kill what was alive at the moment
-      // they clicked the button, not to chase new spawns.
+      // Why: snapshot session IDs up front so mid-kill respawns aren't counted as "remaining".
       const initial = await collectSessions(adapters)
       const initialIds = new Set(initial.map((s) => s.sessionId))
       const initialCount = initial.length
@@ -94,40 +74,20 @@ export function registerDaemonManagementHandlers(): void {
         return { killedCount: 0, remainingCount: 0, killedSessionIds: [] }
       }
 
-      // Why: fire one shutdown per initial session, in parallel, once — no
-      // per-session retry. The daemon's session.kill() is idempotent and
-      // schedules its own SIGTERM→SIGKILL ladder; firing the RPC repeatedly
-      // in a tight retry loop before the grace window expires just races our
-      // own polling. Promise.allSettled ensures a single adapter failure (or
-      // rejected RPC — e.g. session already exiting) does not short-circuit
-      // the remaining shutdowns.
+      // Why: no retry — session.kill() is idempotent and runs its own kill ladder; allSettled so one rejection doesn't abort the rest.
       await Promise.allSettled(
         initial.map(async (session) => {
-          // Why: protocolVersion is unique across adapters by construction —
-          // PROTOCOL_VERSION is always distinct from every entry in
-          // PREVIOUS_DAEMON_PROTOCOL_VERSIONS (see types.ts). If a future
-          // bump forgets to rotate the retired version into the previous
-          // list, this find() would silently route legacy sessions to the
-          // current adapter. Keep the two constants in lockstep.
+          // Why: assumes PROTOCOL_VERSION stays distinct from PREVIOUS_DAEMON_PROTOCOL_VERSIONS (types.ts), else legacy sessions misroute here.
           const owner = adapters.find((a) => a.protocolVersion === session.protocolVersion)
           if (!owner) {
             return
           }
-          // Why: immediate=true is the adapter's "kill it now" signal. The
-          // current adapter ignores the flag (the daemon's SIGTERM→SIGKILL
-          // ladder handles escalation) but preserve it for legacy adapters
-          // and so a future adapter could honor it. Rejections are swallowed
-          // per-session — remainingCount surfaces truly-stuck sessions in
-          // the toast.
+          // Why: immediate=true only matters to legacy/future adapters; swallow rejections since remainingCount reports stuck sessions.
           await owner.shutdown(session.sessionId, { immediate: true }).catch(() => {})
         })
       )
 
-      // Why: poll listSessions every POLL_INTERVAL_MS until none of the
-      // *initial* IDs are still alive, or we've exhausted MAX_POLL_ATTEMPTS.
-      // Counting only the initial-snapshot intersection (not the total
-      // session count) is what keeps the math honest when the renderer
-      // respawns panes with fresh IDs mid-kill.
+      // Why: count only the initial-snapshot intersection so renderer respawns mid-kill aren't counted as remaining.
       let remainingOriginalCount = initialCount
       let remainingOriginalIds = initialIds
       for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index 81090b63733..41d3ac568ad 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: PTY spawn env behavior is easiest to verify in
-one focused file because the registration helper is stateful and each spawn-path
-assertion reuses the same mocked IPC and node-pty harness. */
+/* eslint-disable max-lines -- Why: stateful registration helper + shared mocked IPC/node-pty harness keep spawn-env assertions in one focused file. */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { userInfo } from 'node:os'
 import { delimiter, join, posix } from 'node:path'
@@ -131,8 +129,7 @@ vi.mock('node-pty', () => ({
   spawn: spawnMock
 }))
 
-// Why: this suite forces darwin on non-macOS hosts; isolate the PAM probe
-// while preserving every other child_process API used by the IPC graph.
+// Why: this suite forces darwin on non-macOS hosts; isolate the PAM probe while preserving other child_process APIs.
 vi.mock('node:child_process', async (importOriginal) => ({
   ...(await importOriginal<Record<string, unknown>>()),
   execFile: loginPreflightExecFileMock
@@ -179,8 +176,7 @@ vi.mock('../telemetry/classify-error', () => ({
   classifyError: classifyErrorMock
 }))
 
-// Why: the real ensure writes to disk from process.resourcesPath, which does
-// not exist under vitest; env assembly only needs the returned dir path.
+// Why: the real ensure writes to process.resourcesPath (absent under vitest); env assembly only needs the returned dir path.
 vi.mock('../cli/linux-terminal-orca-cli-shim', () => ({
   ensureLinuxTerminalOrcaCliShimDir: (options: { userDataPath: string }) =>
     join(options.userDataPath, 'linux-orca-cli-shim')
@@ -240,10 +236,7 @@ const POWERSHELL_OSC133_ARGS = [
   '-EncodedCommand',
   encodePowerShellCommand(getPowerShellOsc133Bootstrap())
 ]
-// Why: on Windows the spawn path resolves a bare PowerShell family name to a
-// real absolute executable before handing it to ConPTY (PR #6537 / issue
-// #5161) — a bare/alias `pwsh.exe` makes CreateProcessW fail with error code 5.
-// These match the deterministic install roots pinned in the win32 beforeEach.
+// Why: Windows resolves a bare PowerShell name to an absolute exe before ConPTY, else CreateProcessW fails with error 5 (PR #6537 / #5161).
 const RESOLVED_WINDOWS_POWERSHELL = 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
 const RESOLVED_PWSH7 = 'C:\\Program Files\\PowerShell\\7\\pwsh.exe'
 const TEST_CODEX_HOME =
@@ -274,9 +267,7 @@ describe('registerPtyHandlers', () => {
       on: vi.fn(),
       send: vi.fn(),
       removeListener: vi.fn(),
-      // Why: the did-start-loading reset handler filters to main-frame loads via
-      // isLoadingMainFrame; default true so lifecycle-reset tests still reset. A
-      // subframe-load case overrides it to false.
+      // Why: the did-start-loading reset handler filters to main-frame loads; default true so lifecycle-reset tests reset (a subframe case overrides false).
       isLoadingMainFrame: vi.fn(() => true)
     }
   }
@@ -301,15 +292,12 @@ describe('registerPtyHandlers', () => {
   const savedOrcaUserDataPath = process.env.ORCA_USER_DATA_PATH
 
   beforeEach(() => {
-    // Why: most PTY spawn tests assert POSIX shell behavior; Windows-specific
-    // cases opt into win32 explicitly below.
+    // Why: most PTY spawn tests assert POSIX shell behavior; Windows cases opt into win32 explicitly below.
     Object.defineProperty(process, 'platform', {
       configurable: true,
       value: 'darwin'
     })
-    // Why: with platform forced to darwin, the TCC login(1) wrapper would
-    // rewrite every spawn argv these tests assert. Its own integration test
-    // below re-enables it.
+    // Why: forced darwin makes the TCC login(1) wrapper rewrite every asserted argv; its own test below re-enables it.
     process.env.ORCA_DISABLE_MACOS_LOGIN_SHELL = '1'
     delete process.env.OPENCODE_CONFIG_DIR
     delete process.env.ORCA_OPENCODE_SOURCE_CONFIG_DIR
@@ -358,13 +346,10 @@ describe('registerPtyHandlers', () => {
     mainWindow.webContents.on.mockReset()
     mainWindow.webContents.send.mockReset()
     mainWindow.webContents.removeListener.mockReset()
-    // Why: hidden-delivery gate state is module-level by design (PTY-keyed,
-    // not window-keyed); tests must not leak hidden bits across cases.
+    // Why: hidden-delivery gate state is module-level (PTY-keyed), so tests must not leak hidden bits across cases.
     _resetHiddenRendererPtyDeliveryGateForTest()
 
-    // Why: mirror real Electron — ipcMain.handle throws on a duplicate channel
-    // unless removeHandler cleared it first. This catches a re-registration
-    // (macOS re-activate / new window) that forgets to remove a handle channel.
+    // Why: mirror real Electron — ipcMain.handle throws on a duplicate channel, catching re-registration that forgot removeHandler.
     handleMock.mockImplementation((channel: string, handler: (...a: unknown[]) => unknown) => {
       if (handlers.has(channel)) {
         throw new Error(`Attempted to register a second handler for '${channel}'`)
@@ -374,25 +359,18 @@ describe('registerPtyHandlers', () => {
     removeHandlerMock.mockImplementation((channel: string) => {
       handlers.delete(channel)
     })
-    // Why: production holds PTY sends until the renderer's pty:data dispatcher
-    // registers and sends pty:rendererDispatcherReady (the §1b boot-window gate).
-    // These tests model a live page whose dispatcher is already listening, so
-    // fire the handshake as soon as it registers. Lifecycle-reset tests re-close
-    // the gate via did-start-loading and re-open it with an explicit handshake.
+    // Why: production gates PTY sends on pty:rendererDispatcherReady; model a live page by firing the handshake as soon as it registers.
     onMock.mockImplementation((channel: string, listener: (...args: unknown[]) => void) => {
       if (channel === 'pty:rendererDispatcherReady') {
         listener(mainWindowIpcEvent)
-        // Drain the empty flush the handshake schedules so it can't fire later
-        // (once real output is pending) and perturb send-timing assertions.
+        // Drain the handshake's empty flush so it can't later perturb send-timing assertions.
         if (vi.isFakeTimers()) {
           vi.advanceTimersByTime(0)
         }
       }
     })
     getPathMock.mockReturnValue('/tmp/orca-user-data')
-    // Why: shell-ready wrapper roots resolve from ORCA_USER_DATA_PATH (main
-    // canonicalizes it to app.getPath('userData') at startup before any spawn);
-    // mirror that here so ZDOTDIR/wrapper assertions match the mocked userData.
+    // Why: wrapper roots resolve from ORCA_USER_DATA_PATH; mirror the mocked userData so ZDOTDIR/wrapper assertions match.
     process.env.ORCA_USER_DATA_PATH = '/tmp/orca-user-data'
     existsSyncMock.mockReturnValue(true)
     statSyncMock.mockReturnValue({ isDirectory: () => true, mode: 0o755 })
@@ -439,8 +417,7 @@ describe('registerPtyHandlers', () => {
     _resetLocalPtyProviderStateForTest()
     _resetWslCachesForTests()
     vi.useRealTimers()
-    // Why: sshProviders is module-level state; any id left registered leaks
-    // into later tests (pty:listSessions sweeps every registered provider).
+    // Why: sshProviders is module-level state; a leftover id leaks into later tests (pty:listSessions sweeps every provider).
     for (const leakedConnectionId of [
       'ssh-1',
       'ssh-a',
@@ -706,8 +683,7 @@ describe('registerPtyHandlers', () => {
       throw new Error('missing pty:rendererDispatcherReady listener')
     }
     const listener = readyCall[1] as (event: unknown) => void
-    // Why: the production handler sender-guards its destructive reconcile, so
-    // tests must present as the main window.
+    // Why: the production handler sender-guards its destructive reconcile, so tests must present as the main window.
     return () => listener(mainWindowIpcEvent)
   }
 
@@ -772,10 +748,7 @@ describe('registerPtyHandlers', () => {
       httpProxyUrl?: string
       httpProxyBypassRules?: string
     },
-    // Why: PR #2662 finding 2 — the threading from IPC `args.command` through
-    // buildPtyHostEnv to piTitlebarExtensionService.buildPtyEnv was untested
-    // for the OMP case because this helper never forwarded a command. Accept
-    // an optional `command` so callers can exercise OMP target resolution.
+    // Why: PR #2662 finding 2 — accept an optional `command` so callers can exercise OMP target resolution (was untested).
     command?: string,
     launchAgent?: TuiAgent
   ): Promise<Record<string, string>> {
@@ -792,8 +765,7 @@ describe('registerPtyHandlers', () => {
     }
 
     try {
-      // Clear previously registered handlers so re-registration doesn't
-      // accumulate stale state across calls within one test.
+      // Clear previously registered handlers so re-registration doesn't accumulate stale state.
       handlers.clear()
       registerPtyHandlers(
         mainWindow as never,
@@ -930,11 +902,7 @@ describe('registerPtyHandlers', () => {
     })
 
     it('advertises OSC 8 hyperlink support via FORCE_HYPERLINK', async () => {
-      // Why: the supports-hyperlinks npm package hard-codes a TERM_PROGRAM
-      // allowlist (iTerm.app / WezTerm / vscode) and reports false for
-      // TERM_PROGRAM=Orca, so tools like Claude Code emit plain text instead
-      // of ESC]8;; wrappers. Setting FORCE_HYPERLINK=1 forces the detector to
-      // return true; xterm.js + our linkHandler handle the sequences natively.
+      // Why: supports-hyperlinks allowlists TERM_PROGRAM and reports false for Orca, so FORCE_HYPERLINK=1 forces detection on (xterm.js handles OSC 8 natively).
       const env = await spawnAndGetEnv()
       expect(env.FORCE_HYPERLINK).toBe('1')
     })
@@ -1090,8 +1058,7 @@ describe('registerPtyHandlers', () => {
     posixOnlyIt(
       'reproduces issue #1534: GUI-launched Orca mirrors zshrc-only OpenCode config',
       async () => {
-        // Why: the reporter's app process did not inherit OPENCODE_CONFIG_DIR;
-        // their interactive zsh startup later exported a company config repo.
+        // Why: the reporter's app didn't inherit OPENCODE_CONFIG_DIR; their interactive zsh later exported a company config repo.
         readFileSyncMock.mockImplementation((path: string) => {
           if (path.endsWith('.zshrc')) {
             return [
@@ -1135,11 +1102,7 @@ describe('registerPtyHandlers', () => {
     })
 
     it('threads command: "omp" through to piBuildPtyEnv and emits OMP status metadata', async () => {
-      // Why: OMP launches must emit OMP-named Orca shadow vars (ORCA_OMP_*),
-      // not Pi-named ones. The PI_CODING_AGENT_DIR binary var is unavoidable
-      // (OMP's own binary reads it — see C:\tmp\pr-workspace\oh-my-pi
-      // packages/utils/src/dirs.ts), but every other Orca-owned env name
-      // stays kind-scoped so an OMP PTY never accumulates Pi shadow state.
+      // Why: OMP launches emit ORCA_OMP_* shadow vars, not Pi-named ones; only PI_CODING_AGENT_DIR stays (OMP's own binary reads it).
       const env = await spawnAndGetEnv(
         undefined,
         { PI_CODING_AGENT_DIR: '/tmp/user-omp-agent' },
@@ -1282,11 +1245,7 @@ describe('registerPtyHandlers', () => {
 
     it('injects the agent hook receiver env into Orca terminal PTYs', async () => {
       const env = await spawnAndGetEnv()
-      // Why: after the daemon-parity refactor, buildAgentHookEnv runs exactly
-      // once for a local spawn — inside the shared buildPtyHostEnv helper,
-      // which LocalPtyProvider.buildSpawnEnv and the daemon-active fallback
-      // both route through. The handler's separate ad-hoc injection (which
-      // used to cause a double-call for local spawns) is gone.
+      // Why: buildAgentHookEnv must run exactly once per local spawn (inside shared buildPtyHostEnv); the old ad-hoc double-call is gone.
       expect(buildAgentHookEnvMock).toHaveBeenCalledTimes(1)
       expect(env.ORCA_AGENT_HOOK_PORT).toBe('5678')
       expect(env.ORCA_AGENT_HOOK_TOKEN).toBe('agent-token')
@@ -1406,13 +1365,7 @@ describe('registerPtyHandlers', () => {
     })
 
     describe('daemon-active provider (parity with LocalPtyProvider)', () => {
-      // Why: these tests guard the regression the daemon-parity refactor was
-      // written to fix — under the daemon, LocalPtyProvider.buildSpawnEnv is
-      // never invoked, so every host-local env injection must happen inside
-      // the pty:spawn IPC handler instead. Before the refactor, only the
-      // hook server env and attribution shims were injected on this path;
-      // OpenCode plugin dir, Pi managed extension env, Codex home, and dev-mode CLI
-      // overrides were silently missing for daemon users (the common case).
+      // Why: under the daemon, LocalPtyProvider.buildSpawnEnv never runs, so host-local env injection must happen in the pty:spawn handler instead.
 
       function setupDaemonAdapter(
         supportsGitCredentialGuardHost = true,
@@ -1499,8 +1452,7 @@ describe('registerPtyHandlers', () => {
           httpProxyBypassRules?: string
         },
         processEnvOverrides?: Record<string, string | undefined>,
-        // Why: daemon spawn tests need to exercise both WSL launch metadata
-        // from main and PR #2662 command threading for OMP target selection.
+        // Why: daemon spawn tests exercise both WSL launch metadata from main and PR #2662 command threading for OMP.
         spawnArgs?: {
           cwd?: string
           worktreeId?: string
@@ -1583,8 +1535,7 @@ describe('registerPtyHandlers', () => {
 
       it('mirrors a user-provided OPENCODE_CONFIG_DIR into a source-scoped overlay on the daemon path', async () => {
         const env = await daemonSpawnAndGetEnv({ OPENCODE_CONFIG_DIR: '/user/custom/opencode' })
-        // Why: OpenCode loads config from a single dir, so the user's path is
-        // mirrored into a source-scoped overlay rather than passed through literally.
+        // Why: OpenCode loads config from a single dir, so the user's path is mirrored into a source-scoped overlay, not passed through.
         expect(openCodeBuildPtyEnvMock).toHaveBeenCalledWith(
           expect.any(String),
           '/user/custom/opencode'
@@ -1620,9 +1571,7 @@ describe('registerPtyHandlers', () => {
       })
 
       it('threads command: "omp" through to piBuildPtyEnv on the daemon path with OMP status metadata', async () => {
-        // Why: mirror of the local-spawn OMP threading assertion. The
-        // daemon path's `command` forwarding could silently regress and
-        // Pi-only tests would still pass.
+        // Why: mirror of the local-spawn OMP threading assertion; the daemon path's `command` forwarding could silently regress otherwise.
         const env = await daemonSpawnAndGetEnv(
           { PI_CODING_AGENT_DIR: '/user/.omp/agent' },
           undefined,
@@ -1756,15 +1705,13 @@ describe('registerPtyHandlers', () => {
           value: 'linux'
         })
         try {
-          // Why: overriding process.platform does not change the already-loaded
-          // node:path dialect; keep this synthetic PATH internally consistent.
+          // Why: overriding process.platform doesn't change the loaded node:path dialect; keep this synthetic PATH consistent.
           const env = await daemonSpawnAndGetEnv({
             PATH: ['/usr/local/bin', '/usr/bin'].join(delimiter)
           })
           const entries = env.PATH.split(delimiter)
           const shimDir = join('/tmp/orca-user-data', 'linux-orca-cli-shim')
-          // Why: bare `orca` must resolve to the Orca CLI before /usr/bin/orca
-          // (the GNOME screen reader) inside Orca-managed terminals (#7904).
+          // Why: bare `orca` must resolve to the Orca CLI before /usr/bin/orca (the GNOME screen reader) in Orca terminals (#7904).
           expect(entries.indexOf(shimDir)).toBeGreaterThanOrEqual(0)
           expect(entries.indexOf(shimDir)).toBeLessThan(entries.indexOf('/usr/bin'))
           expect(env.ORCA_CLI_COMMAND).toBeUndefined()
@@ -1864,9 +1811,7 @@ describe('registerPtyHandlers', () => {
           leafId
         })
 
-        // Why: runtime-created spawns (e.g. the mobile-create materialize path)
-        // must thread the same {tabId, leafId} so the catch-path rescue can find
-        // and keep their live PTY (#7587).
+        // Why: runtime-created spawns must thread {tabId, leafId} so the catch-path rescue can keep their live PTY (#7587).
         expect(runtime.registerPty).toHaveBeenCalledWith(
           expect.any(String),
           'wt-runtime',
@@ -2154,8 +2099,7 @@ describe('registerPtyHandlers', () => {
       })
 
       it('injects dev-mode ORCA_USER_DATA_PATH + dev CLI PATH on the daemon path', async () => {
-        // Why: the mocked `app` (see vi.mock at the top of the file) is a
-        // plain object, so we can flip isPackaged for the scope of the test.
+        // Why: the mocked `app` is a plain object, so we can flip isPackaged for the test's scope.
         const { app } = await import('electron')
         const mockedApp = app as unknown as { isPackaged: boolean }
         const prev = mockedApp.isPackaged
@@ -2261,10 +2205,7 @@ describe('registerPtyHandlers', () => {
       })
 
       it('prefixes a minted sessionId with the worktreeId when provided', async () => {
-        // Why: daemon reconnect keys live-shell survival on the sessionId.
-        // Prefixing with worktreeId lets the daemon scope sessions by worktree
-        // while still minting a unique tail. The format contract is
-        // `${worktreeId}@@${8-char-hex}` and must not regress.
+        // Why: daemon reconnect keys live-shell survival on the sessionId; prefixing with worktreeId scopes sessions by worktree with a unique tail.
         const daemonSpawn = setupDaemonAdapter()
         handlers.clear()
         registerPtyHandlers(mainWindow as never)
@@ -2280,11 +2221,7 @@ describe('registerPtyHandlers', () => {
       })
 
       it('falls back to process.env.PI_CODING_AGENT_DIR when baseEnv lacks it on the daemon path', async () => {
-        // Why: buildPtyHostEnv reads `baseEnv.X ?? process.env.X` so the
-        // existing-agent-dir guard stays consistent whether Pi's env was
-        // carried on the IPC wire or inherited by the daemon via fork. The
-        // fallback must reach piTitlebarExtensionService.buildPtyEnv as the
-        // second arg so Orca installs managed extensions in the user's root.
+        // Why: buildPtyHostEnv reads `baseEnv.X ?? process.env.X` so the agent-dir guard works whether Pi's env came over IPC or via daemon fork.
         const env = await daemonSpawnAndGetEnv({}, undefined, undefined, {
           PI_CODING_AGENT_DIR: '/ambient/pi/agent'
         })
@@ -2307,10 +2244,7 @@ describe('registerPtyHandlers', () => {
       })
 
       it('does not mutate the caller-provided args.env on the daemon path', async () => {
-        // Why: the handler clones baseEnv before calling buildPtyHostEnv so
-        // IPC-provided env stays pristine. A regression would silently leak
-        // Orca host env (hook tokens, overlay paths) back into the renderer's
-        // copy of the object, which it may reuse for unrelated IPC calls.
+        // Why: the handler clones baseEnv so IPC-provided env stays pristine; a regression would leak Orca host env back into the renderer's reused copy.
         const daemonSpawn = setupDaemonAdapter()
         const argsEnv: Record<string, string> = { FOO: 'bar' }
         handlers.clear()
@@ -2321,17 +2255,14 @@ describe('registerPtyHandlers', () => {
           env: argsEnv
         })
         expect(argsEnv).toEqual({ FOO: 'bar' })
-        // Sanity: the spawn did receive the injected env, proving the test
-        // isn't passing because buildPtyHostEnv never ran.
+        // Sanity: the spawn did receive the injected env, so the test isn't passing vacuously.
         const spawnEnv = daemonSpawn.mock.calls.at(-1)![0].env
         expect(spawnEnv.ORCA_AGENT_HOOK_PORT).toBe('5678')
         expect(spawnEnv).not.toBe(argsEnv)
       })
 
       it('rejects a caller-supplied sessionId that escapes userData via ..', async () => {
-        // Why: effectiveSessionId reaches filesystem side-effects for provider
-        // hook state and stale pre-migration Pi overlay cleanup. A crafted IPC
-        // payload with traversal must be refused before those side-effects run.
+        // Why: effectiveSessionId reaches filesystem side-effects, so a traversal payload must be refused before they run.
         const daemonSpawn = setupDaemonAdapter()
         handlers.clear()
         registerPtyHandlers(mainWindow as never)
@@ -2348,10 +2279,7 @@ describe('registerPtyHandlers', () => {
       })
 
       it('sweeps per-PTY state when provider.spawn fails for a MINTED sessionId', async () => {
-        // Why: buildPtyHostEnv has filesystem side-effects (Pi/OMP managed
-        // extension installation and legacy overlay cleanup). If provider.spawn
-        // later fails, per-PTY state for the minted id should be cleared so it
-        // isn't orphaned.
+        // Why: buildPtyHostEnv has filesystem side-effects, so a minted id's per-PTY state must be cleared if provider.spawn later fails.
         const daemonSpawn = vi.fn(async () => {
           throw new Error('spawn boom')
         })
@@ -2387,10 +2315,7 @@ describe('registerPtyHandlers', () => {
       })
 
       it('does NOT sweep per-PTY state on provider.spawn failure for CALLER-supplied sessionId', async () => {
-        // Why: a caller-supplied sessionId may refer to an existing PTY whose
-        // state (OpenCode hooks, legacy Pi overlay cleanup, agent-hook pane
-        // caches) must not be clobbered on a retry/attach failure. Only minted
-        // ids get swept.
+        // Why: a caller-supplied sessionId may refer to an existing PTY whose state must survive a retry/attach failure; only minted ids get swept.
         const daemonSpawn = vi.fn(async () => {
           throw new Error('spawn boom')
         })
@@ -2486,11 +2411,7 @@ describe('registerPtyHandlers', () => {
         })
         const spawnOptions = sshSpawn.mock.calls.at(-1)![0]
         const env = spawnOptions.env
-        // Why: every host-local var must be absent over SSH — the hook
-        // server is on the Orca host's 127.0.0.1, dev CLI / attribution /
-        // overlay / plugin-dir paths only exist on the local disk, so
-        // shipping any of them to a remote shell is at best useless and at
-        // worst a credential leak.
+        // Why: host-local vars must be absent over SSH (they point at the local host/disk) — shipping them is useless or a credential leak.
         expect(env.ORCA_AGENT_HOOK_PORT).toBeUndefined()
         expect(env.ORCA_AGENT_HOOK_TOKEN).toBeUndefined()
         expect(env.ORCA_ENABLE_GIT_ATTRIBUTION).toBeUndefined()
@@ -2831,8 +2752,7 @@ describe('registerPtyHandlers', () => {
         }
 
         expect(controller.kill('remote-pty')).toBe(true)
-        // Why: kill's shutdown now runs through the exit-detection wrapper,
-        // which adds async hops; a single microtask flush is no longer enough.
+        // Why: kill's shutdown runs through the exit-detection wrapper (extra async hops), so one microtask flush isn't enough.
         await new Promise((resolve) => setImmediate(resolve))
 
         expect(shutdown).toHaveBeenCalledWith('remote-pty', { immediate: false })
@@ -3440,8 +3360,7 @@ describe('registerPtyHandlers', () => {
           expect(env.ORCA_TAB_ID).toBeUndefined()
           expect(env.ORCA_WORKTREE_ID).toBeUndefined()
           expect(env.ORCA_AGENT_HOOK_TOKEN).toBeUndefined()
-          // Why: the local hook server's userData-relative endpoint file path
-          // is meaningless on the remote box; assert it does not leak.
+          // Why: the local hook server's userData-relative endpoint path is meaningless on the remote box; assert no leak.
           expect(env.ORCA_AGENT_HOOK_ENDPOINT).toBeUndefined()
         } finally {
           if (prevFlag === undefined) {
@@ -3502,8 +3421,7 @@ describe('registerPtyHandlers', () => {
           expect(env.ORCA_PANE_KEY).toBe(paneKey)
           expect(env.ORCA_TAB_ID).toBe('tab-2')
           expect(env.ORCA_WORKTREE_ID).toBe('wt-2')
-          // Local hook server coords still must NOT cross the wire — the
-          // relay is the source of truth for those.
+          // Local hook server coords must NOT cross the wire — the relay is the source of truth.
           expect(env.ORCA_AGENT_HOOK_TOKEN).toBeUndefined()
           expect(env.ORCA_AGENT_HOOK_PORT).toBeUndefined()
           expect(env.ORCA_AGENT_HOOK_ENDPOINT).toBeUndefined()
@@ -3763,8 +3681,7 @@ describe('registerPtyHandlers', () => {
     expect(spawnMock).not.toHaveBeenCalled()
   })
 
-  // Why: cold-start teardown must select the daemon after startup; fallback
-  // shutdown can falsely succeed and orphan the restored daemon PTY (#7742).
+  // Why: cold-start teardown must select the daemon after startup, else fallback shutdown orphans the restored daemon PTY (#7742).
   it('waits for the desktop startup barrier before renderer local kills resolve the provider', async () => {
     const barrier = makeDeferred()
     const awaitLocalPtyStartup = vi.fn(() => new Promise<void>(() => {}))
@@ -3939,8 +3856,7 @@ describe('registerPtyHandlers', () => {
     }
   })
 
-  // Why: the cap and its flag must never fire in the common case (renderer keeps
-  // up), so ordinary small output carries no droppedBacklog.
+  // Why: the cap/flag must never fire in the common case (renderer keeps up), so small output carries no droppedBacklog.
   it('does not flag droppedBacklog for ordinary small output under the cap', async () => {
     vi.useFakeTimers()
     const runtime = {
@@ -4542,14 +4458,7 @@ describe('registerPtyHandlers', () => {
     expect(provider.confirmForegroundProcess).not.toHaveBeenCalled()
   })
 
-  // Why: regression for the Claude-Code split-pane garbled-render desync. resize
-  // is fire-and-forget for daemon-backed PTYs, so a corrective narrow resize can
-  // be dropped while the renderer believes it landed. pty:getSize must report the
-  // size the PTY ACTUALLY applied (so the renderer's resume drift-check re-asserts
-  // the dropped resize) rather than the size last requested. This models a daemon
-  // provider whose resize is dropped but whose getAppliedSize stays at the wide
-  // spawn size; pty:getSize must surface the wide (applied) size, not the narrow
-  // (requested) one.
+  // Why: daemon resize is fire-and-forget, so pty:getSize must report the APPLIED size, not the requested one (Claude-Code split-pane desync).
   describe('pty:getSize reports applied size, not requested size', () => {
     function setupProviderWithAppliedSize(args: {
       applied: { cols: number; rows: number } | null
@@ -4583,8 +4492,7 @@ describe('registerPtyHandlers', () => {
     }
 
     it('returns the applied (wide) size after a dropped narrow resize', async () => {
-      // The daemon keeps the PTY at its wide spawn size; the narrow resize is
-      // silently dropped (provider.resize is a no-op fire-and-forget).
+      // The daemon keeps the PTY at its wide spawn size; the narrow resize is silently dropped (fire-and-forget).
       setupProviderWithAppliedSize({ applied: { cols: 200, rows: 50 } })
       handlers.clear()
       registerPtyHandlers(mainWindow as never)
@@ -4594,15 +4502,13 @@ describe('registerPtyHandlers', () => {
       // Renderer forwards a corrective narrow resize; it is dropped daemon-side.
       resizeListener()(mainWindowIpcEvent, { id, cols: 80, rows: 24 })
 
-      // pty:getSize must surface the applied wide size so the renderer detects
-      // drift (xterm=80 vs PTY=200) and re-asserts — NOT the requested 80.
+      // getSize must surface the applied wide size so the renderer detects drift and re-asserts — NOT requested 80.
       const reported = await handlers.get('pty:getSize')!(null, { id })
       expect(reported).toEqual({ cols: 200, rows: 50 })
     })
 
     it('falls back to the requested size when the provider cannot report applied size', async () => {
-      // No getAppliedSize (e.g. SSH relay): the requested-size cache is the only
-      // signal, so getSize returns it — preserving prior behavior, not a regression.
+      // No getAppliedSize (e.g. SSH relay): requested-size cache is the only signal, so getSize returns it.
       setupProviderWithAppliedSize({ applied: null, getAppliedSize: undefined })
       setLocalPtyProvider({
         spawn: vi.fn(async (opts: { sessionId?: string }) => ({
@@ -4708,8 +4614,7 @@ describe('registerPtyHandlers', () => {
         createPreAllocatedTerminalHandle: vi.fn(() => null),
         registerPty: vi.fn(),
         getDriver: vi.fn(() => ({ kind: 'idle' })),
-        // The whole point of the fix: a PTY with a remote viewer reports true,
-        // even though the presence-lock driver state stays idle/desktop.
+        // The fix: a PTY with a remote viewer reports true even though driver state stays idle/desktop.
         isRemoteDesktopResizeDriven: vi.fn(() => true),
         isResizeSuppressed: vi.fn(() => false),
         onPtySpawned: vi.fn(),
@@ -4973,8 +4878,7 @@ describe('registerPtyHandlers', () => {
       worktreeId: 'wt-1'
     })
 
-    // Why: this is the load-bearing wiring for #7587 — the runtime can only back a
-    // stalled mobile create from a live spawn if the spawn threads {tabId, leafId}.
+    // Why: #7587 — the runtime can only back a stalled mobile create if the spawn threads {tabId, leafId}.
     expect(runtime.registerPty).toHaveBeenCalledWith(
       expect.any(String),
       'wt-1',
@@ -5007,9 +4911,7 @@ describe('registerPtyHandlers', () => {
       worktreeId: 'wt-1'
     })
 
-    // Why: legacy numeric pane ids (`pane:N`) are not terminal leaf ids, so the
-    // spawn seam must not fabricate a binding for them (registerPty would ignore
-    // it anyway); this pins that the seam passes a clean `undefined`.
+    // Why: legacy numeric pane ids (`pane:N`) aren't leaf ids, so the seam passes a clean `undefined` (no fabricated binding).
     expect(runtime.registerPty).toHaveBeenCalledWith(
       expect.any(String),
       'wt-1',
@@ -5338,8 +5240,7 @@ describe('registerPtyHandlers', () => {
     })
     await Promise.resolve()
 
-    // Why: SSH can strip ORCA_PANE_KEY before spawn; tab/leaf metadata must
-    // still dedupe against runtime materialization.
+    // Why: SSH can strip ORCA_PANE_KEY before spawn; tab/leaf metadata must still dedupe against runtime materialization.
     const rendererSpawn = handlers.get('pty:spawn')!(null, {
       cols: 80,
       rows: 24,
@@ -5485,10 +5386,7 @@ describe('registerPtyHandlers', () => {
   })
 
   it('settles the pane reservation when a post-spawn step throws so later spawns do not hang', async () => {
-    // Why: regression for the reservation leak — if a post-spawn helper throws
-    // after provider.spawn resolves (here registerPty), the reservation must be
-    // rejected and cleared. Otherwise every later spawn for the same pane key
-    // awaits a promise that never settles and the tab hangs forever.
+    // Why: reservation-leak regression — a post-spawn throw after provider.spawn resolves must reject/clear the reservation, else later spawns for the same pane key hang forever.
     registerPtyHandlers(mainWindow as never)
     const leafId = '44444444-4444-4444-8444-444444444444'
     const spawnArgs = { cols: 80, rows: 24, tabId: 'tab-reservation', leafId }
@@ -5499,8 +5397,7 @@ describe('registerPtyHandlers', () => {
 
     await expect(handlers.get('pty:spawn')!(null, spawnArgs)).rejects.toThrow('boom')
 
-    // A second spawn for the same pane must run a fresh spawn rather than await
-    // the leaked (never-settled) reservation promise.
+    // A second spawn for the same pane must run a fresh spawn rather than await the leaked (never-settled) reservation promise.
     let hangTimer: ReturnType<typeof setTimeout> | undefined
     const second = handlers.get('pty:spawn')!(null, spawnArgs) as Promise<{ id: string }>
     const result = await Promise.race([
@@ -5518,11 +5415,7 @@ describe('registerPtyHandlers', () => {
   })
 
   it('settles the runtime-owned pane reservation when a post-spawn step throws so later spawns do not hang', async () => {
-    // Why: symmetry with the renderer-path regression — the runtime-controller
-    // spawn path keeps its own reservation, so it must also reject and clear it
-    // when a post-spawn helper (here runtime.registerPty) throws after
-    // provider.spawn resolves. Otherwise the next materialization for the same
-    // pane awaits a promise that never settles.
+    // Why: like the renderer-path regression, the runtime spawn path must clear its own reservation when a post-spawn step throws, else the next materialization hangs forever.
     type RuntimeSpawnController = {
       spawn(args: {
         cols: number
@@ -5603,8 +5496,7 @@ describe('registerPtyHandlers', () => {
 
     await expect(spawnController.spawn(spawnArgs)).rejects.toThrow('boom')
 
-    // The reservation must be gone, so a second materialization runs a fresh
-    // provider.spawn instead of awaiting the leaked promise.
+    // The reservation must be gone, so a second materialization runs a fresh provider.spawn instead of awaiting the leaked promise.
     let hangTimer: ReturnType<typeof setTimeout> | undefined
     const second = spawnController.spawn(spawnArgs)
     const result = await Promise.race([
@@ -6663,10 +6555,7 @@ describe('registerPtyHandlers', () => {
         value: 'win32'
       })
       process.env.USERPROFILE = 'C:\\Users\\test'
-      // Why: the production spawn path resolves a bare PowerShell family name to
-      // a real absolute executable (PR #6537 / issue #5161). Pin the install
-      // roots it probes so the resolved path is deterministic regardless of the
-      // host OS the suite runs on (CI verify runs on Linux, devs on Windows).
+      // Why: the spawn path resolves a bare PowerShell name to an absolute exe (PR #6537 / issue #5161); pin the probed install roots for deterministic resolution across host OS.
       for (const key of ['SystemRoot', 'ProgramW6432', 'ProgramFiles', 'ProgramFiles(x86)']) {
         savedWindowsResolutionEnv[key] = process.env[key]
       }
@@ -6674,11 +6563,7 @@ describe('registerPtyHandlers', () => {
       process.env.ProgramW6432 = 'C:\\Program Files'
       process.env.ProgramFiles = 'C:\\Program Files'
       delete process.env['ProgramFiles(x86)']
-      // Why: the resolver treats any existing, non-zero-size `.exe` outside the
-      // Microsoft Store WindowsApps alias dir as a real executable. Directories
-      // (cwd validation) must still report isDirectory(); the default mock omits
-      // isFile()/size, which would make every PowerShell candidate fail to
-      // resolve and collapse the chain to cmd.exe.
+      // Why: .exe candidates must report isFile()/size (default mock omits them, collapsing every PowerShell candidate to cmd.exe); dirs must still report isDirectory().
       statSyncMock.mockImplementation((target: string) => {
         const isExe = /\.exe$/i.test(String(target))
         return {
@@ -6789,8 +6674,7 @@ describe('registerPtyHandlers', () => {
     })
 
     it('uses terminalWindowsShell setting over COMSPEC when provided', async () => {
-      // Why: COMSPEC always points to cmd.exe on stock Windows, so without the
-      // setting the terminal would ignore the user's shell preference.
+      // Why: COMSPEC always points to cmd.exe on stock Windows, so without the setting the terminal would ignore the user's shell preference.
       process.env.COMSPEC = 'C:\\Windows\\system32\\cmd.exe'
 
       registerPtyHandlers(
@@ -7079,8 +6963,7 @@ describe('registerPtyHandlers', () => {
   })
 
   it('passes floating terminal cwds through to the spawned shell', async () => {
-    // Why: the floating sentinel has no worktree root; its cwd is validated
-    // against trusted-directory grants before it reaches pty:spawn.
+    // Why: the floating sentinel has no worktree root; its cwd is validated against trusted-directory grants before reaching pty:spawn.
     registerPtyHandlers(mainWindow as never)
 
     await handlers.get('pty:spawn')!(null, {
@@ -7175,8 +7058,7 @@ describe('registerPtyHandlers', () => {
 
   it('falls back to the worktree root when a saved local cwd no longer exists', async () => {
     registerPtyHandlers(mainWindow as never)
-    // Why: issue #7239 reproduced in a Japanese-named worktree; the fallback
-    // must return the selected worktree path verbatim.
+    // Why: issue #7239 reproduced in a Japanese-named worktree; the fallback must return the selected worktree path verbatim.
     const worktreePath = '/Users/motoki/orca/workspaces/nakamuramotoki/Fableと議論'
     const missingCwd = `${worktreePath}/deleted-folder`
     statSyncMock.mockImplementation((target: string) => {
@@ -7209,8 +7091,7 @@ describe('registerPtyHandlers', () => {
       return { isDirectory: () => true, mode: 0o755 }
     })
 
-    // Why: without the renderer opt-in the provider still surfaces its normal
-    // missing-directory error — API/runtime callers keep exact cwd semantics.
+    // Why: without the renderer opt-in the provider surfaces its normal missing-directory error — API/runtime callers keep exact cwd semantics.
     await expect(
       handlers.get('pty:spawn')!(null, {
         cols: 80,
@@ -7249,8 +7130,7 @@ describe('registerPtyHandlers', () => {
       return { isDirectory: () => true, mode: 0o755 }
     })
 
-    // Why: a reattach must keep the session's exact cwd; remapping it would
-    // silently detach the restored terminal from its recorded state.
+    // Why: a reattach must keep the session's exact cwd; remapping would silently detach the restored terminal from its recorded state.
     await expect(
       handlers.get('pty:spawn')!(null, {
         cols: 80,
@@ -7275,8 +7155,7 @@ describe('registerPtyHandlers', () => {
     })
     process.env.USERPROFILE = 'C:\\Users\\jinwo'
 
-    // Why: the startup-cwd guard normalizes separators, so the provider sees
-    // the forward-slash UNC form.
+    // Why: the startup-cwd guard normalizes separators, so the provider sees the forward-slash UNC form.
     existsSyncMock.mockImplementation((targetPath: string) => {
       if (targetPath === '//wsl.localhost/Ubuntu/home/jin/missing') {
         return false
@@ -7827,8 +7706,7 @@ describe('registerPtyHandlers', () => {
       })) as { id: string }
       const handleRendererLoading = getMainWindowWebContentsListener('did-start-loading')
       const handleRendererDispatcherReady = getPtyRendererDispatcherReadyListener()
-      // Drain the initial dispatcher-ready flush (beforeEach fires the handshake
-      // to model a live page) so the flood timing below starts from a clean slate.
+      // Drain the initial dispatcher-ready flush (beforeEach fires the handshake to model a live page) so flood timing starts clean.
       vi.advanceTimersByTime(1)
       mainWindow.webContents.send.mockClear()
 
@@ -7852,8 +7730,7 @@ describe('registerPtyHandlers', () => {
         lastLifecycleResetClearedChars: 0
       })
 
-      // Renderer reload: the dead page never ACKs, so its in-flight/pending
-      // accounting must clear or the surviving PTY stays delivery-gated forever.
+      // Renderer reload: the dead page never ACKs, so its in-flight/pending accounting must clear or the surviving PTY stays gated forever.
       handleRendererLoading()
       expect(getPtyRendererDeliveryDebugSnapshot()).toMatchObject({
         rendererInFlightChars: 0,
@@ -7864,10 +7741,7 @@ describe('registerPtyHandlers', () => {
         lastLifecycleResetClearedChars: 512 * 1024
       })
 
-      // Boot window (§1b): the reloaded page's dispatcher has not re-registered
-      // yet, so main must hold sends — bytes sent into the listener-less page are
-      // dropped but still counted in-flight, which would re-pin the gate. The
-      // output must accrue in pending, unsent and NOT counted in-flight.
+      // Boot window (§1b): dispatcher not re-registered, so sends must be held — bytes into the listener-less page drop yet count in-flight, re-pinning the gate.
       mainWindow.webContents.send.mockClear()
       mockProc.emitData('post-reload output')
       vi.advanceTimersByTime(8)
@@ -7878,10 +7752,7 @@ describe('registerPtyHandlers', () => {
         pendingPtyCount: 1
       })
 
-      // The reloaded page's dispatcher-ready handshake releases the held backlog.
-      // Counters-zero alone is insufficient — prove delivery actually resumes and
-      // the pending backlog drains (bytes now correctly counted in-flight, the
-      // mirror image of the NOT-counted boot-window hold above).
+      // The dispatcher-ready handshake releases the held backlog; assert delivery actually resumes and pending drains, not just counters-zero.
       handleRendererDispatcherReady()
       vi.advanceTimersByTime(8)
       expect(mainWindow.webContents.send).toHaveBeenCalledWith('pty:data', {
@@ -7924,11 +7795,7 @@ describe('registerPtyHandlers', () => {
       }
       expect(mainWindow.webContents.send).toHaveBeenCalledTimes(32)
 
-      // A sandboxed srcDoc iframe (notebook HTML output) loading fires
-      // did-start-loading with isLoadingMainFrame() === false. This is NOT a
-      // renderer lifecycle reset: the still-alive page keeps its dispatcher, so
-      // clearing accounting or dropping the ready flag here would freeze every
-      // pane for the whole watchdog window. Nothing must change.
+      // A subframe load (isLoadingMainFrame() === false, e.g. notebook srcDoc iframe) is NOT a lifecycle reset — resetting here would freeze every pane for the watchdog window.
       mainWindow.webContents.isLoadingMainFrame.mockReturnValueOnce(false)
       handleRendererLoading()
       expect(getPtyRendererDeliveryDebugSnapshot()).toMatchObject({
@@ -7940,9 +7807,7 @@ describe('registerPtyHandlers', () => {
         rendererPtyDispatcherReady: true
       })
 
-      // The gate is still open: ACKing the in-flight cap drains the held backlog
-      // (a spurious reset would have cleared pending and dropped ready, so this
-      // send would never fire).
+      // Gate still open: ACKing the in-flight cap drains the held backlog (a spurious reset would have cleared pending/ready, so this send would never fire).
       mainWindow.webContents.send.mockClear()
       ackData(null, { id: spawnResult.id, charCount: 512 * 1024 })
       vi.advanceTimersByTime(8)
@@ -7983,13 +7848,7 @@ describe('registerPtyHandlers', () => {
         rendererPtyDispatcherReady: true
       })
 
-      // A main-frame reload overlapped by an in-page subframe load emits no
-      // did-start-loading, so the lifecycle reset never ran: the gate stayed open
-      // holding the dead page's in-flight accounting. The reloaded page's fresh
-      // dispatcher now sends its one-shot handshake. Receiving it while the gate is
-      // already open is proof a reset was missed, so it must reconcile — clear the
-      // stale accounting and count the reset — before re-opening. Without that
-      // reconcile the survivors stay pinned at the cap forever (this turns red).
+      // Handshake arriving while the gate is already open proves a missed lifecycle reset (subframe-overlapped reload emits no did-start-loading); it must reconcile stale accounting or survivors stay pinned at the cap forever.
       mainWindow.webContents.send.mockClear()
       handleRendererDispatcherReady()
       const reconciled = getPtyRendererDeliveryDebugSnapshot()
@@ -8002,8 +7861,7 @@ describe('registerPtyHandlers', () => {
       })
       expect(reconciled.lastLifecycleResetClearedChars).toBeGreaterThan(0)
 
-      // Delivery has resumed: fresh output flows immediately instead of piling up
-      // behind the stale cap.
+      // Delivery has resumed: fresh output flows immediately instead of piling up behind the stale cap.
       mockProc.emitData('post-reconcile output')
       vi.advanceTimersByTime(8)
       expect(mainWindow.webContents.send).toHaveBeenCalledWith('pty:data', {
@@ -8011,8 +7869,7 @@ describe('registerPtyHandlers', () => {
         data: 'post-reconcile output'
       })
 
-      // A straggler ACK from the dead page is clamped and cannot underflow the
-      // reconciled counters below zero.
+      // A straggler ACK from the dead page is clamped and cannot underflow the reconciled counters below zero.
       ackData(null, { id: spawnResult.id, charCount: 512 * 1024 })
       expect(getPtyRendererDeliveryDebugSnapshot().rendererInFlightChars).toBe(0)
     } finally {
@@ -8042,11 +7899,7 @@ describe('registerPtyHandlers', () => {
       handleRendererLoading()
       mainWindow.webContents.send.mockClear()
 
-      // Prime the interactive window with a keystroke, then emit a small redraw:
-      // shouldSendInteractiveOutputNow() is true here, so ONLY the
-      // `&& rendererPtyDispatcherReady` guard on the interactive fast path keeps this
-      // echo from being sent into the still-listener-less page (removing that flag
-      // check turns this red). It must accrue in pending, unsent and NOT in-flight.
+      // With shouldSendInteractiveOutputNow() true, only the `&& rendererPtyDispatcherReady` guard keeps the interactive echo out of the still-listener-less page.
       const redraw = '\x1b[20;2Hredraw'
       writeListener(mainWindowIpcEvent, { id: spawnResult.id, data: 'a' })
       mockProc.emitData(redraw)
@@ -8084,8 +7937,7 @@ describe('registerPtyHandlers', () => {
       const handleRendererLoading = getMainWindowWebContentsListener('did-start-loading')
       vi.advanceTimersByTime(1)
 
-      // Reload closes the gate and arms the ~10s watchdog; the reloaded page never
-      // sends the handshake (dropped IPC), so output stays held in pending.
+      // Reload closes the gate and arms the ~10s watchdog; the reloaded page never sends the handshake (dropped IPC), so output stays held.
       handleRendererLoading()
       mainWindow.webContents.send.mockClear()
       mockProc.emitData('post-reload output')
@@ -8096,9 +7948,7 @@ describe('registerPtyHandlers', () => {
         rendererDispatcherReadyForcedCount: 0
       })
 
-      // Past the watchdog window (10s) the gate self-heals: ready is forced, the
-      // counter increments, and the held backlog drains — degrading to pre-handshake
-      // behavior instead of a permanent freeze.
+      // Past the 10s watchdog window the gate self-heals (ready forced, backlog drains) instead of freezing permanently.
       vi.advanceTimersByTime(10_000)
       vi.advanceTimersByTime(8)
       expect(mainWindow.webContents.send).toHaveBeenCalledWith('pty:data', {
@@ -8133,8 +7983,7 @@ describe('registerPtyHandlers', () => {
       const rawReadyListener = readyCall[1] as (event: unknown) => void
       vi.advanceTimersByTime(1)
 
-      // Why: a straggler handshake from a dying window's webContents must not
-      // reopen the gate (or trigger the destructive reconcile) for the new page.
+      // Why: a straggler handshake from a dying window must not reopen the gate (or trigger the destructive reconcile) for the new page.
       handleRendererLoading()
       mainWindow.webContents.send.mockClear()
       rawReadyListener({ sender: { isDestroyed: () => false } })
@@ -8172,10 +8021,7 @@ describe('registerPtyHandlers', () => {
       const handleRendererDispatcherReady = getPtyRendererDispatcherReadyListener()
       vi.advanceTimersByTime(1)
 
-      // Reload arms the watchdog; a timely handshake must cancel it so no orphaned
-      // ~10s timer lingers. Draining the handshake's empty flush must leave zero
-      // pending timers — a surviving watchdog would show up here (the forced-count
-      // guard alone can't catch it, since the watchdog no-ops once ready is true).
+      // A timely handshake must cancel the reload watchdog so no orphaned ~10s timer lingers (forced-count guard can't catch it — the watchdog no-ops once ready).
       handleRendererLoading()
       handleRendererDispatcherReady()
       vi.advanceTimersByTime(0)
@@ -8209,21 +8055,15 @@ describe('registerPtyHandlers', () => {
       vi.advanceTimersByTime(1)
       expect(vi.getTimerCount()).toBe(0)
 
-      // A reload closes the gate and arms the ~10s self-heal watchdog on THIS
-      // registration's closure.
+      // A reload closes the gate and arms the ~10s self-heal watchdog on THIS registration's closure.
       handleRendererLoading()
       expect(vi.getTimerCount()).toBe(1)
 
-      // Re-registering handlers (macOS re-activate / new window owns delivery) must
-      // cancel that armed watchdog via the cross-registration bridge at the top of
-      // registerPtyHandlers — otherwise the prior closure's timer survives and later
-      // force-opens a dead window's gate. The re-registration's own dispatcher-ready
-      // handshake schedules and drains one 0ms flush; nothing else may remain.
+      // Re-registering must cancel the prior closure's watchdog (cross-registration bridge) or it later force-opens a dead window's gate.
       registerPtyHandlers(mainWindow as never)
       expect(vi.getTimerCount()).toBe(0)
 
-      // And no orphaned ~10s watchdog fires later (removing the bridge cancel turns
-      // this red: the prior closure's timer would still be pending here).
+      // And no orphaned ~10s watchdog fires later (removing the bridge cancel turns this red).
       vi.advanceTimersByTime(20_000)
       expect(vi.getTimerCount()).toBe(0)
     } finally {
@@ -8983,16 +8823,14 @@ describe('registerPtyHandlers', () => {
       const ackData = getPtyAckDataListener()
       mainWindow.webContents.send.mockClear()
 
-      // Saturate the renderer in-flight window (512 KB) with no ACKs — the
-      // frozen/starved-renderer shape from the field reports.
+      // Saturate the renderer in-flight window (512 KB) with no ACKs — the frozen/starved-renderer shape from field reports.
       mockProc.emitData('x'.repeat(600 * 1024))
       vi.advanceTimersByTime(2)
       for (let index = 0; index < 32; index++) {
         vi.advanceTimersByTime(1)
       }
 
-      // Keep flooding well past the 2 MB per-PTY pending cap. Main must not
-      // buffer this unboundedly (previously: unbounded string concat).
+      // Keep flooding past the 2 MB per-PTY pending cap; main must not buffer unboundedly (previously: unbounded string concat).
       mockProc.emitData('y'.repeat(3 * 1024 * 1024))
       expect(getPtyRendererDeliveryDebugSnapshot()).toMatchObject({
         pendingPtyCount: 1,
@@ -9006,8 +8844,7 @@ describe('registerPtyHandlers', () => {
         pendingChars: 0
       })
 
-      // Renderer recovers and ACKs: the flush must deliver the droppedOutput
-      // sentinel so the pane repaints from the main-owned snapshot.
+      // On recover+ACK, the flush must deliver the droppedOutput sentinel so the pane repaints from the main-owned snapshot.
       mainWindow.webContents.send.mockClear()
       ackData(null, { id: spawn.id, charCount: 512 * 1024 })
       vi.advanceTimersByTime(2)
@@ -9054,8 +8891,7 @@ describe('registerPtyHandlers', () => {
         vi.advanceTimersByTime(1)
       }
 
-      // Flood past the pending cap WITH an embedded DSR probe — the program
-      // that wrote it blocks on the reply (the bench DSR timeout).
+      // Flood past the pending cap WITH an embedded DSR probe — the writing program blocks on the reply (bench DSR timeout).
       mockProc.emitData(`${'y'.repeat(2 * 1024 * 1024)}\x1b[6n${'y'.repeat(1024 * 1024)}`)
       // While latched, a later probe must also be carved out (bounded).
       mockProc.emitData(`${'z'.repeat(32 * 1024)}\x1b[0c${'z'.repeat(32 * 1024)}`)
@@ -9088,8 +8924,7 @@ describe('registerPtyHandlers', () => {
       await handlers.get('pty:spawn')!(null, { cols: 80, rows: 24, cwd: '/tmp' })
       mainWindow.webContents.send.mockClear()
 
-      // Saturate the in-flight window with no ACKs, then buffer 3 MB — over
-      // the floor, under the scaled cap: it must be retained, not dropped.
+      // Saturate the in-flight window with no ACKs, then buffer 3 MB — over the floor, under the scaled cap: retain, don't drop.
       mockProc.emitData('x'.repeat(600 * 1024))
       vi.advanceTimersByTime(2)
       for (let index = 0; index < 32; index++) {
@@ -9117,8 +8952,7 @@ describe('registerPtyHandlers', () => {
       registerPtyHandlers(mainWindow as never)
       mainWindow.webContents.send.mockClear()
 
-      // Flood in 64KB chunks like a `yes`-style producer that honors pause —
-      // node-pty pause() stops the fd read, so a real producer stops emitting.
+      // Flood in 64KB chunks like a `yes`-style producer honoring pause — node-pty pause() stops the fd read, so it stops emitting.
       const chunk = 'x'.repeat(64 * 1024)
       let chunks = 0
       while (provider.pauseProducer.mock.calls.length === 0 && chunks < 100) {
@@ -9126,8 +8960,7 @@ describe('registerPtyHandlers', () => {
         chunks++
       }
 
-      // Pause fires exactly once, on the first chunk past the 256KB high
-      // watermark (the 5th 64KB chunk), not once per chunk.
+      // Pause fires exactly once, on the first chunk past the 256KB high watermark (the 5th 64KB chunk), not per chunk.
       expect(provider.pauseProducer).toHaveBeenCalledTimes(1)
       expect(provider.pauseProducer).toHaveBeenCalledWith('flood-pty')
       expect(chunks).toBe(5)
@@ -9138,9 +8971,7 @@ describe('registerPtyHandlers', () => {
         peakPendingChars: 320 * 1024
       })
 
-      // Drain to the renderer. Resume must fire exactly once — when pending
-      // drops below the 32KB low watermark — with no pause/resume flapping
-      // while pending crosses the 32-256KB hysteresis band.
+      // Resume must fire exactly once at the 32KB low watermark, with no flapping across the 32-256KB hysteresis band.
       vi.runAllTimers()
       expect(provider.resumeProducer).toHaveBeenCalledTimes(1)
       expect(provider.resumeProducer).toHaveBeenCalledWith('flood-pty')
@@ -9161,8 +8992,7 @@ describe('registerPtyHandlers', () => {
       provider.emitData('flood-pty', 'x'.repeat(320 * 1024))
       expect(provider.pauseProducer).toHaveBeenCalledTimes(1)
 
-      // Exit while pending is still above the low watermark: the exit path
-      // must release the pause instead of leaving a stale mark behind.
+      // Exit while pending is above the low watermark: the exit path must release the pause, not leave a stale mark.
       provider.emitExit('flood-pty', 0)
       expect(provider.resumeProducer).toHaveBeenCalledTimes(1)
       expect(provider.resumeProducer).toHaveBeenCalledWith('flood-pty')
@@ -9207,8 +9037,7 @@ describe('registerPtyHandlers', () => {
     ) => void
   }
 
-  /** Saturates one PTY to its 512 KiB in-flight cap so delivery is fully
-   *  gated for that PTY. Leaves 88 KiB pending and no timers scheduled. */
+  /** Saturates one PTY to its 512 KiB in-flight cap; leaves 88 KiB pending and no timers scheduled. */
   async function spawnAndSaturateRendererDeliveryGate(
     mockProc: ReturnType<typeof createMockProc>
   ): Promise<{ id: string }> {
@@ -9240,8 +9069,7 @@ describe('registerPtyHandlers', () => {
         rendererInFlightPtyCount: 1
       })
 
-      // Every per-chunk ACK was lost, but the next ACK carries the renderer's
-      // full cumulative total — the debt clears without any timer or reset.
+      // Every per-chunk ACK was lost, but the next ACK carries the full cumulative total — the debt clears without any timer or reset.
       const ackData = getPtyAckDataListener()
       ackData(null, { id: spawnResult.id, processedChars: 512 * 1024 })
 
@@ -9353,9 +9181,7 @@ describe('registerPtyHandlers', () => {
       mockProc.emitData('remote-output')
       vi.advanceTimersByTime(8)
 
-      // Why: cumulative totals are clamped to what main actually sent, and a
-      // replayed total must credit SSH/relay flow control with zero, not
-      // duplicate bytes.
+      // Why: cumulative totals clamp to what main sent; a replayed total credits SSH/relay flow control 0, not duplicate bytes.
       ackData(null, { id: 'cumulative-pty', processedChars: 1024 })
       ackData(null, { id: 'cumulative-pty', processedChars: 1024 })
 
@@ -9397,8 +9223,7 @@ describe('registerPtyHandlers', () => {
         rendererInFlightPtyCount: 0
       })
 
-      // The reconciled gate lets the held pendingData flush again (one 2ms
-      // batch window = one 16KB slice).
+      // Reconciled gate lets held pendingData flush again (one 2ms batch window = one 16KB slice).
       vi.advanceTimersByTime(2)
       expect(getPtyDataSendCalls()).toHaveLength(33)
     } finally {
@@ -9461,8 +9286,7 @@ describe('registerPtyHandlers', () => {
       })
       expect(getPtyDataSendCalls()).toHaveLength(32)
 
-      // The cleared flag lets the next gated arrival probe again, but a
-      // still-silent renderer does not spam a second warn.
+      // Cleared flag lets the next gated arrival probe again, but a still-silent renderer won't spam a second warn.
       mockProc.emitData('still-stuck')
       expect(getDeliveryResyncProbeCalls()).toHaveLength(2)
       vi.advanceTimersByTime(5_000)
@@ -9500,8 +9324,7 @@ describe('registerPtyHandlers', () => {
         vi.advanceTimersByTime(1)
       }
       mockProc.emitData('stuck-output')
-      // The outstanding probe's hygiene timeout is the only remaining timer;
-      // the dispatcher-ready handshake already drained the pending flush.
+      // Only the probe's hygiene timeout remains; the dispatcher-ready handshake already drained the pending flush.
       expect(vi.getTimerCount()).toBe(1)
 
       destroyed = true
@@ -9517,9 +9340,7 @@ describe('registerPtyHandlers', () => {
   })
 
   // ── Renderer-initiated delivery health/heal (pty:reportRendererDeliveryState) ──
-  // Field wedge repro (v1.4.121-rc.0 snapshot): push delivery dead, invoke
-  // alive. The solicited-resync probe above rides push and can never be
-  // answered in that state; this invoke lane is the recovery that can.
+  // Field wedge (v1.4.121-rc.0): push dead but invoke alive, so the push-riding resync probe can't answer; this invoke lane recovers.
 
   function reportRendererDeliveryState(args: {
     receivedCharsByPty: Record<string, number>
@@ -9576,8 +9397,7 @@ describe('registerPtyHandlers', () => {
     try {
       const spawnResult = await spawnAndSaturateRendererDeliveryGate(mockProc)
 
-      // Lost-ACK variant: renderer processed everything; only the ACK
-      // messages vanished. A plain report (no heal) must drain the debt.
+      // Lost-ACK variant: renderer processed everything, only ACKs vanished; a plain report (no heal) must drain the debt.
       const health = reportRendererDeliveryState({
         receivedCharsByPty: { [spawnResult.id]: 512 * 1024 },
         processedCharsByPty: { [spawnResult.id]: 512 * 1024 }
@@ -9609,9 +9429,7 @@ describe('registerPtyHandlers', () => {
         rendererPtyDataListenerCount: 1
       })
 
-      // The 512 KiB the renderer provably never received is written off; the
-      // 88 KiB still pending is dropped because the snapshot restore covers
-      // everything at or before the marker (hidden-drop parity).
+      // 512 KiB never-received is written off; the 88 KiB pending is dropped too (snapshot restore covers everything at/before the marker).
       expect(healed.writtenOff).toEqual([{ id: spawnResult.id, writtenOffChars: 512 * 1024 }])
       expect(healed).toMatchObject({ inFlightTotalChars: 0, inFlightPtyCount: 0 })
       expect(getPtyRendererDeliveryDebugSnapshot()).toMatchObject({
@@ -9642,8 +9460,7 @@ describe('registerPtyHandlers', () => {
     try {
       const spawnResult = await spawnAndSaturateRendererDeliveryGate(mockProc)
 
-      // Parse backpressure, not a wedge: every byte arrived, ACK credit is
-      // deferred to the scheduler consume point and will still repay this.
+      // Parse backpressure, not a wedge: ACK credit is deferred to the scheduler consume point and still repays.
       const health = reportRendererDeliveryState({
         receivedCharsByPty: { [spawnResult.id]: 512 * 1024 },
         processedCharsByPty: {},
@@ -9671,8 +9488,7 @@ describe('registerPtyHandlers', () => {
       const ackData = getPtyAckDataListener()
       ackData(null, { id: spawnResult.id, processedChars: 16 * 1024 })
 
-      // Some pty still round-trips ACKs — whatever the renderer thinks, the
-      // channel is not dead, so a heal request must not destroy accounting.
+      // A pty still round-trips ACKs, so the channel isn't dead — a heal must not destroy accounting.
       const blocked = reportRendererDeliveryState({
         receivedCharsByPty: {},
         processedCharsByPty: {},
@@ -9684,8 +9500,6 @@ describe('registerPtyHandlers', () => {
       })
 
       // Once main-side ACK silence crosses the floor, the same heal proceeds.
-      // (The ACK freed a 16K window slot, so one more pending slice shipped
-      // during the advance — the write-off covers 512K un-received again.)
       vi.advanceTimersByTime(10_000)
       const healed = reportRendererDeliveryState({
         receivedCharsByPty: {},
@@ -9713,14 +9527,12 @@ describe('registerPtyHandlers', () => {
 
       handleRendererLoading()
 
-      // Why: reload kills the renderer dispatcher that would have ACKed, so
-      // keeping the counters would gate PTYs in the fresh renderer forever.
+      // Why: reload kills the dispatcher that would ACK, so stale counters would gate PTYs in the fresh renderer forever.
       expect(getPtyRendererDeliveryDebugSnapshot()).toMatchObject({
         rendererInFlightPtyCount: 0,
         rendererInFlightChars: 0
       })
-      // Main now holds sends until the replacement page confirms its dispatcher
-      // is installed; the lifecycle reset arms a bounded handshake watchdog.
+      // Main holds sends until the replacement page confirms its dispatcher; the reset arms a bounded handshake watchdog.
       expect(vi.getTimerCount()).toBe(1)
 
       mockProc.emitData('after-reload')
@@ -9780,8 +9592,7 @@ describe('registerPtyHandlers', () => {
         data: 'remote-output'
       })
 
-      // Why: stale or duplicated renderer ACKs must not over-credit SSH/relay
-      // flow control beyond the bytes main actually sent to the renderer.
+      // Why: stale/duplicated renderer ACKs must not over-credit SSH/relay flow control beyond bytes main sent.
       ackData(null, { id: 'remote-like-pty', charCount: 1024 })
       ackData(null, { id: 'remote-like-pty', charCount: 1024 })
 
@@ -9859,8 +9670,7 @@ describe('registerPtyHandlers', () => {
         data: 'a'
       })
       interactiveProc.emitData(reserveChunk)
-      // Why: the reserve-exhausted send stays gated, and the fully gated
-      // arrival now also emits one delivery resync probe (not pty:data).
+      // Why: reserve-exhausted send stays gated, and the fully gated arrival emits one delivery resync probe (not pty:data).
       expect(getPtyDataSendCalls()).toHaveLength(529)
       expect(getDeliveryResyncProbeCalls()).toHaveLength(1)
     } finally {
@@ -9945,8 +9755,7 @@ describe('registerPtyHandlers', () => {
       setActiveRendererPty(null, { id: spawns[activeIndex]!.id, active: true })
       vi.advanceTimersByTime(2)
 
-      // Why: the fully gated arrival also emits one delivery resync probe, so
-      // count pty:data sends rather than raw webContents.send calls.
+      // Why: the fully gated arrival also emits a delivery resync probe, so count pty:data sends not raw webContents.send.
       expect(getPtyDataSendCalls()).toHaveLength(513)
       expect(getPtyDataSendCalls()[512]).toEqual([
         'pty:data',
@@ -10052,8 +9861,7 @@ describe('registerPtyHandlers', () => {
           undefined
         )
         expect(mainWindow.webContents.send).toHaveBeenCalledTimes(1)
-        // Why out-of-band: an in-band empty pty:data chunk is ambiguous with
-        // chunks fully consumed by renderer OSC-9999 stripping.
+        // Why out-of-band: an in-band empty pty:data chunk is ambiguous with chunks fully consumed by renderer OSC-9999 stripping.
         expect(mainWindow.webContents.send).toHaveBeenCalledWith('pty:modelRestoreNeeded', {
           id: result.id,
           reason: 'hidden-drop',
@@ -10079,10 +9887,7 @@ describe('registerPtyHandlers', () => {
     })
 
     it('surfaces the hidden-yet-visible contradiction in the snapshot and warns on drop', async () => {
-      // Why: v1.4.124-rc.2.perf field snapshot — blank terminal with 2 ptys
-      // hidden-gated and 78MB dropped. The aggregate counts could not say
-      // whether the pane the user was staring at was one of them; this
-      // overlap counter + warn makes the next occurrence decisive.
+      // Why: field snapshot v1.4.124-rc.2.perf — aggregates couldn't tell if the visible pane was hidden-gated; overlap counter + warn makes it decisive.
       vi.useFakeTimers()
       const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
       const daemon = installObservableDaemonTestProvider()
@@ -10096,8 +9901,7 @@ describe('registerPtyHandlers', () => {
         const setHidden = getPtySetHiddenRendererPtyListener()
         const setVisible = getPtySetRendererPtyVisibleListener()
 
-        // The two renderer visibility signals contradict: the pane reports
-        // itself visible while the hidden-delivery gate still holds it.
+        // The two visibility signals contradict: pane reports visible while the hidden-delivery gate still holds it.
         setVisible(null, { id: result.id, visible: true })
         setHidden(null, { id: result.id, hidden: true })
         daemon.emitData(result.id, 'starved visible output')
@@ -10156,8 +9960,7 @@ describe('registerPtyHandlers', () => {
           inFlightChars: 0,
           pendingChars: 0
         })
-        // Why redaction is pinned here: daemon session ids embed worktree
-        // paths; the report must never carry the raw id.
+        // Why redaction is pinned: daemon session ids embed worktree paths, so the report must never carry the raw id.
         expect(diagnostics.perPty.some((candidate) => candidate.id === result.id)).toBe(false)
         const breadcrumbKinds = diagnostics.breadcrumbs.map((crumb) => crumb.kind)
         expect(breadcrumbKinds).toContain('gate-mark')
@@ -10325,8 +10128,7 @@ describe('registerPtyHandlers', () => {
         vi.advanceTimersByTime(2)
         expect(mainWindow.webContents.send).toHaveBeenCalledTimes(1)
 
-        // Why: a renderer reload can replace the view that latched
-        // restore-needed; unhide repeats the marker so the live view heals.
+        // Why: a renderer reload can replace the view that latched restore-needed; unhide repeats the marker so the live view heals.
         setHidden(null, { id: spawnResult.id, hidden: false })
         expect(mainWindow.webContents.send).toHaveBeenCalledTimes(2)
         expect(mainWindow.webContents.send).toHaveBeenLastCalledWith('pty:modelRestoreNeeded', {
@@ -10418,9 +10220,7 @@ describe('registerPtyHandlers', () => {
         vi.advanceTimersByTime(2)
         expect(mainWindow.webContents.send).toHaveBeenCalledTimes(1)
 
-        // Why: a hidden remount (tab move, parking handoff) re-marks the PTY
-        // without an unhide in between. The fresh view never saw the first
-        // marker, so re-marking must NOT erase the drop memory.
+        // Why: a hidden remount (tab move, parking handoff) re-marks without an unhide, so re-marking must NOT erase drop memory.
         setHidden(null, { id: spawnResult.id, hidden: true })
         setHidden(null, { id: spawnResult.id, hidden: false })
 
@@ -10451,9 +10251,7 @@ describe('registerPtyHandlers', () => {
       const daemon = installObservableDaemonTestProvider()
       try {
         registerPtyHandlers(mainWindow as never, runtime as never)
-        // Why daemon provider: it survives renderer reloads (the scenario
-        // under test) and keeps the LocalPtyProvider orphan-kill handler off
-        // this webContents, so 'did-finish-load' maps to the gate reset only.
+        // Why daemon provider: survives reloads and keeps orphan-kill off this webContents, so 'did-finish-load' means gate reset only.
         const reloadHandlers = mainWindow.webContents.on.mock.calls
           .filter((call: unknown[]) => call[0] === 'did-finish-load')
           .map((call: unknown[]) => call[1] as () => void)
@@ -10471,8 +10269,7 @@ describe('registerPtyHandlers', () => {
         vi.advanceTimersByTime(50)
         expect(mainWindow.webContents.send).toHaveBeenCalledTimes(1)
 
-        // Renderer reload: hidden marks die with the old renderer, but the
-        // dropped bytes were never restored — memory must survive.
+        // Renderer reload: hidden marks die with the old renderer, but dropped bytes were never restored — memory must survive.
         reloadHandlers[0]()
         expect(getPtyRendererDeliveryDebugSnapshot()).toMatchObject({
           hiddenDeliveryGatedPtyCount: 0
@@ -10531,8 +10328,7 @@ describe('registerPtyHandlers', () => {
           expect.objectContaining({ id: result.id, data: 'sidecar bytes' })
         )
 
-        // Why: the renderer reload killed the sidecar's ref count without a
-        // release IPC — the leaked hold must not force-feed the PTY forever.
+        // Why: the renderer reload killed the sidecar's ref count without a release IPC — the leaked hold must not force-feed the PTY forever.
         reloadHandlers[0]()
         mainWindow.webContents.send.mockClear()
         setHidden(null, { id: result.id, hidden: true })
@@ -10552,10 +10348,7 @@ describe('registerPtyHandlers', () => {
   })
 
   describe('hidden-at-spawn mark (initiallyHidden)', () => {
-    // terminal-query-authority.md §races: the renderer declares hidden-at-
-    // spawn so main marks the PTY before its first byte — the spawn-time
-    // query window where neither side replied (the non-codex DA1 loss) is
-    // closed by the gate + responder owning queries from byte one.
+    // terminal-query-authority.md §races: hidden-at-spawn marks the PTY before byte one, closing the spawn-time DA1-loss window.
     function createRuntimeMock() {
       return {
         setPtyController: vi.fn(),
@@ -10592,8 +10385,7 @@ describe('registerPtyHandlers', () => {
         await Promise.resolve()
         mainWindow.webContents.send.mockClear()
 
-        // Daemon PTYs can emit prompt bytes before spawn() resolves — the
-        // pre-spawn mark must already gate them.
+        // Daemon PTYs can emit prompt bytes before spawn() resolves, so the pre-spawn mark must already gate them.
         expect(isHiddenRendererPty('daemon-session')).toBe(true)
         daemon.emitData('daemon-session', 'pre-spawn prompt\x1b[c')
         vi.advanceTimersByTime(50)
@@ -10692,9 +10484,7 @@ describe('registerPtyHandlers', () => {
     })
 
     it('answers DA1 from the model on the first chunk of a hidden-at-spawn PTY', async () => {
-      // End-to-end through a REAL runtime: spawn-marked → first chunk dropped
-      // → runtime emulator parses the query → reply written to the provider
-      // input path (the renderer never saw the bytes; main is the answerer).
+      // End-to-end through a REAL runtime: spawn-marked → first chunk dropped → emulator parses query → replies; main answers, the renderer never saw the bytes.
       const daemon = installObservableDaemonTestProvider()
       const runtime = new OrcaRuntimeService({
         getRepo: () => undefined,
@@ -10748,10 +10538,7 @@ describe('registerPtyHandlers', () => {
       })) as { id: string }
       mainWindow.webContents.send.mockClear()
 
-      // 3 MB in one starved pending entry: the scrollback-scaled cap (2 MB at
-      // default settings) drops the buffered bytes to O(1) memory. One
-      // out-of-band restore marker fires; the droppedOutput sentinel then
-      // routes the pane through the main-owned snapshot repaint.
+      // 3 MB in one entry: the scrollback-scaled cap (2 MB default) drops to O(1) memory; one restore marker fires, droppedOutput routes to the snapshot repaint.
       mockProc.emitData('x'.repeat(1024 * 1024) + 'y'.repeat(2 * 1024 * 1024))
 
       expect(mainWindow.webContents.send).toHaveBeenCalledTimes(1)
@@ -10782,10 +10569,7 @@ describe('registerPtyHandlers', () => {
   ])(
     'keeps the pending cap active without a restore marker when the %s kill switch is off',
     async (_name, settings) => {
-      // Why: the scrollback-scaled pending cap ships independently of the gate
-      // (#7150) — the droppedOutput sentinel repaints the pane from the
-      // main-owned snapshot even with the model/view kill switches off. Only the
-      // gate's out-of-band pty:modelRestoreNeeded marker is switch-scoped.
+      // Why: the pending cap ships independently of the gate (#7150) — droppedOutput repaint survives kill switches; only the restore marker is switch-scoped.
       vi.useFakeTimers()
       const mockProc = createMockProc()
       spawnMock.mockReturnValue(mockProc.proc)
@@ -11002,16 +10786,12 @@ describe('registerPtyHandlers', () => {
     write(mainWindowIpcEvent, { id: result.id, data: 'alive' })
     expect(mockProc.proc.write).toHaveBeenCalledWith('alive')
 
-    // Field failure shape (Discord #performance / #2836): a pane can keep
-    // rendering with a ptyId whose ownership entry is gone while the provider
-    // still holds the live PTY — every keystroke then vanishes with no error,
-    // no log, and no signal back to the renderer.
+    // Field failure (Discord #performance / #2836): a pane can render with a ptyId whose ownership is gone while the PTY lives, so keystrokes vanish silently.
     deletePtyOwnership(result.id)
     write(mainWindowIpcEvent, { id: result.id, data: 'dropped' })
     expect(mockProc.proc.write).not.toHaveBeenCalledWith('dropped')
 
-    // pty:listSessions rebuilds ownership from provider sessions — the
-    // revival lever the frozen-pane e2e probes depend on.
+    // pty:listSessions rebuilds ownership from provider sessions — the revival lever the frozen-pane e2e probes depend on.
     await handlers.get('pty:listSessions')!(null, undefined)
     write(mainWindowIpcEvent, { id: result.id, data: 'revived' })
     expect(mockProc.proc.write).toHaveBeenCalledWith('revived')
@@ -11380,10 +11160,7 @@ describe('registerPtyHandlers', () => {
     const onDataDisposable = makeDisposable()
     const onExitDisposable = makeDisposable()
     let exitCb: ((info: { exitCode: number }) => void) | undefined
-    // Why: hold a stable reference to the kill spy. On POSIX, destroyPtyProcess
-    // in local-pty-provider reassigns proc.kill to a no-op to defuse the
-    // SIGHUP-to-recycled-pid hazard (see docs/fix-pty-fd-leak.md). Reading
-    // proc.kill.mock after that runs would yield a non-mock and crash.
+    // Why: hold a stable ref to the kill spy — destroyPtyProcess reassigns proc.kill to a no-op (docs/fix-pty-fd-leak.md), so reading proc.kill.mock later would crash.
     const killSpy = vi.fn()
     const proc = {
       onData: vi.fn(() => onDataDisposable),
@@ -11492,8 +11269,7 @@ describe('registerPtyHandlers', () => {
     spawnMock.mockReturnValue(proc)
 
     registerPtyHandlers(mainWindow as never, runtime as never)
-    // Why both: a reload fires the hidden-delivery gate reset AND the orphan
-    // cleanup; invoke every registered listener like a real did-finish-load.
+    // Why both: a reload fires the gate reset AND the orphan cleanup, so invoke every registered listener like a real did-finish-load.
     const didFinishLoadHandlers = mainWindow.webContents.on.mock.calls
       .filter(([eventName]) => eventName === 'did-finish-load')
       .map(([, handler]) => handler as () => void)
@@ -11505,8 +11281,7 @@ describe('registerPtyHandlers', () => {
     }
     await handlers.get('pty:spawn')!(null, { cols: 80, rows: 24 })
 
-    // The first load after spawn only advances generation. The second one sees
-    // this PTY as belonging to a prior page load and kills it as orphaned.
+    // First load after spawn only advances generation; the second sees this PTY as from a prior load and kills it as orphaned.
     didFinishLoad()
     didFinishLoad()
 
@@ -11544,8 +11319,7 @@ describe('registerPtyHandlers', () => {
     }
 
     registerPtyHandlers(firstWindow as never)
-    // Two listeners on the first (LocalPtyProvider) window: the renderer-gate
-    // reset and the orphan cleanup.
+    // Two listeners on the first (LocalPtyProvider) window: the renderer-gate reset and the orphan cleanup.
     const firstWindowLoadHandlers = firstWindow.webContents.on.mock.calls.filter(
       ([eventName]) => eventName === 'did-finish-load'
     )
@@ -11571,8 +11345,7 @@ describe('registerPtyHandlers', () => {
         handler
       )
     }
-    // The non-Local provider keeps orphan cleanup off the second window —
-    // only the renderer-gate reset listener remains.
+    // The non-Local provider keeps orphan cleanup off the second window — only the renderer-gate reset listener remains.
     expect(
       secondWindow.webContents.on.mock.calls.filter(
         ([eventName]) => eventName === 'did-finish-load'
@@ -11580,9 +11353,7 @@ describe('registerPtyHandlers', () => {
     ).toHaveLength(1)
   })
 
-  // Why (#5787): a crash/freeze-recovery reload re-fires did-finish-load on the
-  // single window. The orphan sweep must be suppressed for it so live LOCAL PTYs
-  // stay attached until session restore re-adopts them.
+  // Why (#5787): a recovery reload re-fires did-finish-load; suppress the orphan sweep so live LOCAL PTYs survive until session restore re-adopts them.
   it('does not sweep local PTYs during a recovery reload', async () => {
     const killSpy = vi.fn()
     const proc = {
@@ -11614,9 +11385,7 @@ describe('registerPtyHandlers', () => {
       undefined,
       { isRecoveryReloadInFlight }
     )
-    // This branch registers two did-finish-load listeners (renderer delivery-gate
-    // reset first, orphan sweep second); a real reload fires both, so must we —
-    // otherwise the suppression assertion passes vacuously without reaching the sweep.
+    // Fire both did-finish-load listeners as a real reload does, else the suppression assertion passes vacuously without reaching the sweep.
     const didFinishLoadHandlers = mainWindow.webContents.on.mock.calls
       .filter(([eventName]) => eventName === 'did-finish-load')
       .map(([, handler]) => handler as () => void)
@@ -11627,8 +11396,7 @@ describe('registerPtyHandlers', () => {
       id: string
     }
 
-    // Without the guard the second load would sweep this PTY as a prior-generation
-    // orphan. Under recovery-in-flight neither load may touch it.
+    // Without the guard the second load would sweep this PTY as a prior-generation orphan; under recovery-in-flight neither load may touch it.
     didFinishLoad()
     didFinishLoad()
 
@@ -11641,8 +11409,7 @@ describe('registerPtyHandlers', () => {
     markClaudePtyExitedSpy.mockRestore()
   })
 
-  // Why: guard against over-suppression — when no recovery reload is in flight the
-  // sweep MUST still reclaim genuinely orphaned local PTYs.
+  // Why: guard against over-suppression — with no recovery reload in flight the sweep MUST still reclaim genuinely orphaned local PTYs.
   it('still sweeps orphaned local PTYs when no recovery reload is in flight', async () => {
     let exitCb: ((info: { exitCode: number }) => void) | undefined
     const killSpy = vi.fn(() => {
@@ -11679,8 +11446,7 @@ describe('registerPtyHandlers', () => {
       undefined,
       { isRecoveryReloadInFlight }
     )
-    // This branch registers two did-finish-load listeners (renderer delivery-gate
-    // reset first, orphan sweep second); a real reload fires both, so must we.
+    // Fire both did-finish-load listeners (gate reset + orphan sweep) as a real reload does.
     const didFinishLoadHandlers = mainWindow.webContents.on.mock.calls
       .filter(([eventName]) => eventName === 'did-finish-load')
       .map(([, handler]) => handler as () => void)
@@ -11690,8 +11456,7 @@ describe('registerPtyHandlers', () => {
       id: string
     }
 
-    // First load only advances the generation; the second sees this PTY as a
-    // prior-load orphan. With the flag false the guard must NOT suppress the sweep.
+    // First load only advances generation; the second sees this PTY as a prior-load orphan — with the flag false the guard must NOT suppress the sweep.
     didFinishLoad()
     didFinishLoad()
     await Promise.resolve()
@@ -11702,8 +11467,7 @@ describe('registerPtyHandlers', () => {
     expect(listed.some((info) => info.id === spawnResult.id)).toBe(false)
   })
 
-  // Why (#5787): two PTYs spawned in different load generations must BOTH survive a
-  // recovery reload — even the older one that a normal sweep would reclaim.
+  // Why (#5787): two PTYs in different load generations must BOTH survive a recovery reload — even the older one a normal sweep would reclaim.
   it('keeps local PTYs from different generations alive across recovery reloads', async () => {
     const killSpyA = vi.fn()
     const killSpyB = vi.fn()
@@ -11725,8 +11489,7 @@ describe('registerPtyHandlers', () => {
       undefined,
       { isRecoveryReloadInFlight }
     )
-    // Fire ALL did-finish-load listeners (gate reset + orphan sweep), as a
-    // real reload does — the sweep listener is the one under test.
+    // Fire ALL did-finish-load listeners (gate reset + orphan sweep) as a real reload does; the sweep listener is under test.
     const didFinishLoadHandlers = mainWindow.webContents.on.mock.calls
       .filter(([eventName]) => eventName === 'did-finish-load')
       .map(([, handler]) => handler as () => void)
@@ -11743,8 +11506,7 @@ describe('registerPtyHandlers', () => {
     })
     const ptyA = (await handlers.get('pty:spawn')!(null, { cols: 80, rows: 24 })) as { id: string }
 
-    // Advance the generation without sweeping (recovery-in-flight), then spawn a
-    // second PTY so the two live in different load generations.
+    // Advance the generation without sweeping (recovery-in-flight), then spawn a second PTY so the two live in different generations.
     didFinishLoad()
 
     spawnMock.mockReturnValue({
@@ -11811,10 +11573,7 @@ describe('registerPtyHandlers', () => {
   })
 
   describe('agent_started telemetry', () => {
-    // Why: telemetry-plan.md§Agent launch semantics — agent_started must
-    // fire only after provider.spawn resolves. The renderer threads
-    // launch metadata through `pty:spawn`; a missing or malformed
-    // payload must not produce a silently-malformed event.
+    // Why: telemetry-plan.md§Agent launch semantics — agent_started fires only after provider.spawn resolves; a malformed payload must not emit a silent event.
     it('emits agent_started after a successful spawn when telemetry is supplied', async () => {
       handlers.clear()
       registerPtyHandlers(mainWindow as never)
@@ -11857,9 +11616,7 @@ describe('registerPtyHandlers', () => {
     })
 
     it('does not emit agent_started when provider.spawn throws', async () => {
-      // Why: telemetry-plan contract is that agent_started fires only on
-      // confirmed launch. Inject a provider whose spawn throws so we hit
-      // the catch path with no race against the real LocalPtyProvider.
+      // Why: agent_started fires only on confirmed launch — inject a throwing provider to hit the catch path with no race against the real LocalPtyProvider.
       setLocalPtyProvider({
         spawn: vi.fn(async () => {
           throw new Error('spawn boom')
@@ -11950,8 +11707,7 @@ describe('registerPtyHandlers', () => {
         controller.serializeBuffer('pty-11'),
         controller.serializeBuffer('pty-12')
       ]
-      // Why: the bug being fixed registered one listener per request, so 12
-      // concurrent calls would register 12 listeners and trip Node's MaxListeners.
+      // Why: the bug registered one listener per request, so 12 concurrent calls would trip Node's MaxListeners.
       const responseChannelRegistrations = onMock.mock.calls.filter(
         (call: unknown[]) => call[0] === 'pty:serializeBuffer:response'
       )
@@ -12093,10 +11849,7 @@ describe('registerPtyHandlers', () => {
       expect(runtime.serializeHiddenOutputRecoveryBuffer).toHaveBeenCalledWith('pty-1', {
         scrollbackRows: 50_000
       })
-      // Why pendingDeliveryStartSeq === seq: the pending renderer-delivery
-      // queue is empty, so the renderer's post-restore duplicate window is
-      // empty too — low-seq live chunks (fresh seq domain) must not be
-      // dropped against the snapshot baseline.
+      // Why pendingDeliveryStartSeq === seq: pending delivery queue is empty, so low-seq live chunks must not be dropped against the snapshot baseline.
       expect(result).toEqual({
         data: 'snapshot\r\n',
         cols: 120,
@@ -12150,8 +11903,7 @@ describe('registerPtyHandlers', () => {
         rows: 30,
         seq: 900,
         source: 'headless',
-        // Bytes between main's current absolute seq and the daemon snapshot
-        // may still be queued on the stream socket and must dedupe on arrival.
+        // Bytes between main's absolute seq and the daemon snapshot may still be queued on the stream socket and must dedupe on arrival.
         pendingDeliveryStartSeq: 640
       })
       provider.emitExit('daemon-pty')
@@ -12221,8 +11973,7 @@ describe('registerPtyHandlers', () => {
           cwd: '/tmp'
         })) as { id: string }
 
-        // Starved pending entry: bytes ingested up to seq 2_472 but not yet
-        // flushed to the renderer — they can still arrive after the snapshot.
+        // Starved pending entry: bytes ingested but not yet flushed to the renderer — they can still arrive after the snapshot.
         mockProc.emitData('frame-bytes')
 
         const result = (await handlers.get('pty:getMainBufferSnapshot')!(null, {
diff --git a/src/main/ipc/pty.ts b/src/main/ipc/pty.ts
index cd4242143a1..2f470170d6f 100644
--- a/src/main/ipc/pty.ts
+++ b/src/main/ipc/pty.ts
@@ -1,8 +1,4 @@
-/* eslint-disable max-lines -- Why: PTY IPC is intentionally centralized in one
-main-process module so spawn-time environment scoping, lifecycle cleanup,
-foreground-process inspection, and renderer IPC stay behind a single audited
-boundary. Splitting it by line count would scatter tightly coupled terminal
-process behavior across files without a cleaner ownership seam. */
+/* eslint-disable max-lines -- Why: PTY IPC is centralized in one main-process module so spawn env scoping, lifecycle cleanup, process inspection, and renderer IPC stay behind one audited boundary. */
 import { join, delimiter } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { statSync } from 'node:fs'
@@ -158,8 +154,7 @@ import { getSshFilesystemProvider } from '../providers/ssh-filesystem-dispatch'
 import { resolveLocalProjectRuntimeForWorktreeId } from '../local-project-runtime-resolution'
 
 // ─── Provider Registry ──────────────────────────────────────────────
-// Routes PTY operations by connectionId. null = local provider.
-// SSH providers will be registered here in Phase 1.
+// Routes PTY operations by connectionId (null = local provider).
 
 let localProvider: IPtyProvider = new LocalPtyProvider()
 type FreshLocalFallbackProvider = IPtyProvider & {
@@ -167,21 +162,13 @@ type FreshLocalFallbackProvider = IPtyProvider & {
 }
 const sshProviders = new Map<string, IPtyProvider>()
 const SYNTHETIC_KILL_EXIT_DUPLICATE_WINDOW_MS = 30_000
-// Why: producer flow control changes terminal physics — a flooding shell now
-// blocks on write instead of buffering in main. Kill switch: flip this one
-// line to disable pause/resume entirely without untangling the wiring.
+// Why: kill switch — flip to disable producer flow control (pause/resume) without untangling the wiring.
 const PRODUCER_FLOW_CONTROL_ENABLED = true
-// Why: PTY IDs are assigned at spawn time with a connectionId, but subsequent
-// write/resize/kill calls only carry the PTY ID. This map lets us route
-// post-spawn operations to the correct provider without the renderer needing
-// to track connectionId per-PTY.
+// Why: post-spawn write/resize/kill calls carry only the PTY ID; map it to its connectionId so ops route to the right provider.
 const ptyOwnership = new Map<string, string | null>()
-// Why: mobile clients must mirror desktop PTY geometry even when the renderer
-// cannot provide an xterm snapshot yet, such as immediately after tab creation.
+// Why: mobile clients must mirror desktop PTY geometry even before the renderer can provide an xterm snapshot (e.g. right after tab creation).
 const ptySizes = new Map<string, { cols: number; rows: number }>()
-// Why: PTY data batching is window-bound, but the "recent user input" signal
-// is PTY-scoped and must be cleared by every teardown path, including SSH and
-// daemon shutdowns that do not flow through the local provider exit listener.
+// Why: the "recent user input" signal is PTY-scoped and must be cleared by every teardown path, incl. SSH/daemon shutdowns that skip the local exit listener.
 const lastInputAtByPty = new Map<string, number>()
 const interactiveOutputCharsByPty = new Map<string, number>()
 const activeRendererPtys = new Set<string>()
@@ -191,16 +178,9 @@ const pendingHiddenRendererResizeOutputPtys = new Set<string>()
 const deliveredHiddenRendererResizeOutputPtys = new Set<string>()
 const KEEP_HISTORY_STOP_SETTLE_MS = 1_000
 const KEEP_HISTORY_STOP_POLL_MS = 100
-// Why: the agent-hooks server caches per-paneKey state (last prompt, last
-// tool) that otherwise grows unbounded as panes come and go. Track the
-// spawn-time paneKey so clearProviderPtyState can clear that cache on PTY
-// teardown — the renderer knows the paneKey but the PTY lifecycle does not
-// without this mapping.
+// Why: track spawn-time paneKey so teardown can clear the agent-hooks server's per-paneKey cache, which otherwise grows unbounded as panes come and go.
 const ptyPaneKey = new Map<string, string>()
-// Why: reverse of ptyPaneKey — callers that receive a paneKey from outside the
-// PTY lifecycle (e.g. the agent-hook server routing a cursor-agent status event
-// back into the pane's data stream) need to find the ptyId for that paneKey.
-// Kept in lock-step with ptyPaneKey via the same spawn and teardown sites.
+// Why: reverse of ptyPaneKey — callers with a paneKey from outside the PTY lifecycle (e.g. agent-hook status routing) need the ptyId; kept in lock-step via the same sites.
 const paneKeyPtyId = new Map<string, string>()
 
 const AGENT_HOOK_RUNTIME_ENV_KEYS = [
@@ -209,8 +189,7 @@ const AGENT_HOOK_RUNTIME_ENV_KEYS = [
   'ORCA_AGENT_HOOK_ENV',
   'ORCA_AGENT_HOOK_VERSION',
   'ORCA_AGENT_HOOK_ENDPOINT',
-  // Why: PR 2778 briefly exported this scoped Claude settings path. Keep
-  // deleting stale inherited values so older PTYs cannot leak the reverted path.
+  // Why: PR 2778 briefly exported this path; keep deleting stale inherited values so older PTYs can't leak the reverted path.
   'ORCA_CLAUDE_AGENT_STATUS_SETTINGS'
 ] as const
 
@@ -218,12 +197,7 @@ export function getPtyIdForPaneKey(paneKey: string): string | undefined {
   return paneKeyPtyId.get(paneKey)
 }
 
-// Why: consumers (currently the cursor-agent synthesized-spinner loop in
-// main/index.ts) need to tear down paneKey-scoped state when a PTY exits so
-// intervals / timers cannot leak for the process lifetime. A callback
-// registry keeps the cross-module dependency narrow — clearProviderPtyState
-// only has to know about "things to notify", not about every consumer's
-// internals.
+// Why: let consumers tear down paneKey-scoped state on PTY exit so their timers can't leak; a callback registry keeps the cross-module dependency narrow.
 type PaneKeyTeardownListener = (paneKey: string) => void
 const paneKeyTeardownListeners = new Set<PaneKeyTeardownListener>()
 
@@ -232,13 +206,7 @@ export function registerPaneKeyTeardownListener(listener: PaneKeyTeardownListene
   return () => paneKeyTeardownListeners.delete(listener)
 }
 
-// Why: pre-signal handshake — the renderer declares it will own the serializer
-// for a paneKey BEFORE issuing pty:spawn. The cooperation gate at provider.spawn
-// return consults this map to suppress the daemon-snapshot seed when a renderer
-// is taking over. Generation tokens prevent paneKey-reuse races during teardown:
-// a paneKeyTeardownListener cleanup only fires settle when the captured gen
-// still matches, so a remount that pre-signals before the old PTY's teardown
-// runs is preserved. See docs/mobile-prefer-renderer-scrollback.md.
+// Why: renderer pre-declares serializer ownership before pty:spawn to suppress the daemon-snapshot seed; gen tokens prevent paneKey-reuse races on teardown. See docs/mobile-prefer-renderer-scrollback.md.
 let pendingSerializerGenSeq = 0
 const pendingByPaneKey = new Map<string, { gen: number; ownerWebContentsId: number | null }>()
 const pendingPaneSerializerCleanupRegistered = new Set<number>()
@@ -251,16 +219,11 @@ type PaneSpawnReservationResult = {
   id: string
   launchConfig?: SleepingAgentLaunchConfig
 } & Partial<PtySpawnResult>
-// Why: mobile runtime materialization and a newly-focused renderer pane can
-// race to spawn the same tab/leaf. Key by stable paneKey so the loser adopts
-// the winner's PTY instead of creating a duplicate shell.
+// Why: mobile materialization and a newly-focused pane can race to spawn the same leaf; key by paneKey so the loser adopts the winner's PTY.
 const paneSpawnReservationsByPaneKey = new Map<string, PaneSpawnReservation>()
-// Why: bind the declaration generation directly to its spawn result. PTY ids
-// are reusable and teardown callbacks carry no incarnation token, so teardown
-// must never guess which pending renderer generation it owns.
+// Why: PTY ids are reusable and teardown callbacks carry no incarnation token; bind the generation to its spawn result so teardown never guesses.
 const pendingPtyIdBySerializerGeneration = new Map<number, string>()
-// Why: the runtime's hasRendererSerializer probe needs a ptyId-keyed signal.
-// A later spawn starts a fresh incarnation; subscription abort owns waiter cleanup.
+// Why: hasRendererSerializer probe needs a ptyId-keyed signal; a later spawn starts a fresh incarnation, subscription abort owns waiter cleanup.
 const rendererSerializerReadiness = new RendererTerminalSerializerReadiness()
 
 function parseValidPaneKey(paneKey: unknown): ReturnType<typeof parsePaneKey> {
@@ -407,8 +370,7 @@ function getProviderForPty(ptyId: string): IPtyProvider {
 }
 
 function hasPtyProviderForInspection(ptyId: string): boolean {
-  // Why: process inspection is background polling; disconnected SSH hosts should
-  // read as idle instead of surfacing repeated IPC errors.
+  // Why: process inspection is background polling; disconnected SSH hosts should read as idle, not raise repeated IPC errors.
   const connectionId = ptyOwnership.get(ptyId)
   return connectionId == null || sshProviders.has(connectionId)
 }
@@ -470,8 +432,7 @@ function normalizeNodePtySpawnError(err: unknown): Error {
     return err
   }
   if (err instanceof Error) {
-    // Why: preserve the original stack/name/custom fields while returning the
-    // same recovery guidance as the renderer-driven pty:spawn path.
+    // Why: preserve the original stack/name/custom fields while adding the same recovery hint as the pty:spawn path.
     err.message = hintedMessage
     return err
   }
@@ -539,17 +500,7 @@ function finishPtyShutdown(
 }
 
 // ─── Host PTY env assembly ──────────────────────────────────────────
-// Why: both the LocalPtyProvider.buildSpawnEnv closure and the daemon-active
-// fallback in pty:spawn need the same set of host-local env injections
-// (OpenCode plugin dir, agent-hook server coordinates, Pi/OMP managed
-// extensions, Codex account home, dev-mode CLI overrides, GitHub attribution
-// shims). They used to be implemented twice, which silently drifted —
-// daemon-backed PTYs never got the OpenCode plugin, Pi integration, Codex
-// home, or dev CLI PATH prepend, so status dots, Pi state, Codex switching, and CLI→dev
-// routing were all broken for daemon users (the common case).
-//
-// Centralizing the injections here makes future additions fail-safe: a new
-// variable added to this function lands in BOTH spawn paths or NEITHER.
+// Why: centralize host-local env injections so both spawn paths (local + daemon) get them; implemented twice they drifted, silently breaking daemon PTYs.
 
 export type BuildPtyHostEnvOptions = {
   isPackaged: boolean
@@ -557,24 +508,19 @@ export type BuildPtyHostEnvOptions = {
   selectedCodexHomePath: string | null
   skipCodexHomeEnv?: boolean
   githubAttributionEnabled: boolean
-  /** The launch command the renderer chose for this PTY (e.g. 'pi', 'omp',
-   *  'claude'). Used to resolve the per-agent managed extension target for
-   *  Pi / OMP - both consume `PI_CODING_AGENT_DIR` but default to different
-   *  `~/.<kind>/agent` paths. Undefined for bare-shell spawns; defaults
-   *  resolve to Pi for back-compat. NEVER infer from disk presence; that's
-   *  the bug this option fixes (cross-agent shadowing when both dirs exist). */
+  /** Launch command the renderer chose (e.g. 'pi', 'omp', 'claude'); resolves the per-agent
+   *  extension target for Pi/OMP. Undefined for bare shells → defaults to Pi. NEVER infer from
+   *  disk presence (cross-agent shadowing when both dirs exist). */
   launchCommand?: string
   /** Trusted agent identity for wrapped commands that cannot be recognized from text. */
   launchAgent?: TuiAgent
   shellPath?: string
   isWsl?: boolean
-  /** Distro for WSL spawns (null = Windows default distro). Drives the WSL
-   *  hook relay ensure + guest endpoint repoint; only read when isWsl. */
+  /** Distro for WSL spawns (null = Windows default distro); drives the WSL hook relay + endpoint repoint. Only read when isWsl. */
   wslDistro?: string | null
   agentStatusHooksEnabled: boolean
   networkProxySettings?: NetworkProxySettings
-  /** Keep indexed Git config off the sparse daemon wire; the daemon appends
-   *  guard entries after merging its authoritative inherited environment. */
+  /** Keep indexed Git config off the sparse daemon wire; the daemon appends guard entries after merging its inherited env. */
   deferGitConfigGuardToDaemon?: boolean
 }
 
@@ -603,8 +549,7 @@ function promoteAgentTeamsShimPath(
   const remaining = currentPath
     .split(delimiter)
     .filter((entry) => entry.length > 0 && entry !== shimPath)
-  // Why: host env injection can prepend Orca's attribution/dev shims. Claude
-  // Agent Teams must still resolve our fake tmux before any real tmux.
+  // Why: host env injection prepends Orca's shims; Claude Agent Teams must still resolve our fake tmux before any real tmux.
   env[currentPathKey] = [shimPath, ...remaining].join(delimiter)
 }
 
@@ -684,9 +629,7 @@ function resolvePiAgentSourceDir(
   const publicDir = readEnvWithProcessFallback(baseEnv, 'PI_CODING_AGENT_DIR')
   const ownOverlayDir = readEnvWithProcessFallback(baseEnv, overlayKey)
   const otherOverlayDir = readEnvWithProcessFallback(baseEnv, otherOverlayKey)
-  // Why: if PI_CODING_AGENT_DIR is just a restored Orca overlay from either
-  // kind and the matching source shadow is absent, remirroring it would leak
-  // another agent's overlay tree into this launch. Fall through to defaults.
+  // Why: if PI_CODING_AGENT_DIR is a restored Orca overlay with no source shadow, remirroring leaks another agent's overlay tree; fall through to defaults.
   if (publicDir && publicDir !== ownOverlayDir && publicDir !== otherOverlayDir) {
     return publicDir
   }
@@ -758,16 +701,11 @@ function getInheritedAgentHookEnvKeysToDelete(
   spawnEnv: Record<string, string> | undefined
 ): string[] {
   const env = spawnEnv ?? {}
-  // Why: daemon/local providers merge process.env after main-process cleanup.
-  // Delete reverted or unavailable hook env keys there without dropping fresh
-  // receiver coordinates that buildPtyHostEnv intentionally set.
+  // Why: providers merge process.env after cleanup; delete stale hook keys without dropping fresh coordinates buildPtyHostEnv set.
   return AGENT_HOOK_RUNTIME_ENV_KEYS.filter((key) => env[key] === undefined)
 }
 
-// Why: when agent status is disabled, a nested Orca terminal can still pass
-// through prior OpenCode or legacy Pi/OMP overlay env. Restore the user's
-// original source dir when Orca recorded one, otherwise strip only values
-// known to be ours.
+// Why: a nested terminal can inherit prior OpenCode/Pi/OMP overlay env; restore the user's recorded source dir, else strip only Orca-owned values.
 function restoreOrStripOverlayEnv(
   baseEnv: Record<string, string>,
   keys: {
@@ -816,10 +754,7 @@ function resolveOpenCodeSourceConfigDir(baseEnv: Record<string, string>): string
 
   const configDir = baseEnv.OPENCODE_CONFIG_DIR ?? process.env.OPENCODE_CONFIG_DIR
   const orcaConfigDir = baseEnv.ORCA_OPENCODE_CONFIG_DIR ?? process.env.ORCA_OPENCODE_CONFIG_DIR
-  // Why: nested Orca terminals inherit OPENCODE_CONFIG_DIR from the parent
-  // PTY. If there is no recorded source dir, that value is Orca-owned, not a
-  // user config. Treating it as user config makes child Orcas mirror Orca's
-  // hook dir and can create large OpenCode runtime trees per terminal.
+  // Why: with no recorded source dir, an inherited OPENCODE_CONFIG_DIR is Orca-owned, not user config; treating it as user config makes child Orcas mirror the hook dir.
   if (configDir && orcaConfigDir && configDir === orcaConfigDir) {
     return undefined
   }
@@ -837,13 +772,8 @@ function resolveOpenCodeSourceConfigDir(baseEnv: Record<string, string>): string
 /**
  * Mutates `baseEnv` in place with all host-local PTY env vars and returns it.
  *
- * This is the single source of truth for the env shape an Orca PTY needs
- * BEFORE the provider-specific wrapper (LocalPtyProvider's TERM/LANG defaults,
- * DaemonPtyAdapter's subprocess env). Callers are responsible for the SSH
- * guard — if `args.connectionId` is set, do NOT call this function, because
- * every injection here is either host-loopback (hook server, attribution
- * shims) or references paths on the local filesystem that would be meaningless
- * to a remote shell.
+ * Do NOT call when `args.connectionId` is set (SSH): every injection is host-loopback
+ * or references local filesystem paths meaningless to a remote shell.
  */
 export function buildPtyHostEnv(
   id: string,
@@ -853,21 +783,14 @@ export function buildPtyHostEnv(
   mergePersistedWindowsPath(baseEnv)
   Object.assign(baseEnv, buildConfiguredProxyEnv(opts.networkProxySettings))
 
-  // Why: the Local path passes a baseEnv that already includes process.env
-  // (LocalPtyProvider.spawn merges it before calling buildSpawnEnv). The
-  // daemon path passes only args.env since process.env propagates to the
-  // daemon subprocess via fork inheritance, not the IPC wire. Checking both
-  // sources when reading a potentially-user-provided value keeps the guards
-  // in lock-step across spawn paths without pushing process.env onto the
-  // IPC wire unnecessarily.
+  // Why: local path's baseEnv includes process.env but the daemon path doesn't (fork inheritance, not IPC); check both sources so guards stay in lock-step across spawn paths.
   const preexistingOpenCodeConfigDir = resolveOpenCodeSourceConfigDir(baseEnv)
   const launchCommandHint = resolveSetupAgentSequenceLaunchCommand(baseEnv, opts.launchCommand)
   const piAgentKind = detectPiAgentKindFromCommand(launchCommandHint)
   const hasLaunchCommand =
     typeof launchCommandHint === 'string' && launchCommandHint.trim().length > 0
 
-  // Why: unattended agents must fail instead of opening OS credential UI and
-  // retrying auth in a loop; ordinary user terminals keep normal Git behavior.
+  // Why: unattended agents must fail instead of looping on OS credential prompts; user terminals keep normal Git behavior.
   applyTerminalGitCredentialPromptGuard(baseEnv, {
     launchCommand: launchCommandHint,
     isUnattended: opts.launchAgent !== undefined,
@@ -875,8 +798,7 @@ export function buildPtyHostEnv(
   })
 
   const shouldPrepareOmpShadow = piAgentKind === 'omp' || !hasLaunchCommand
-  // Why: source shadows are agent-scoped. Trusting the other kind's source
-  // would reintroduce the exact Pi/OMP extension-state shadowing this PR fixes.
+  // Why: source shadows are agent-scoped; trusting the other kind's source reintroduces Pi/OMP extension-state shadowing.
   const preexistingPiAgentDir = resolvePiAgentSourceDir(baseEnv, 'pi')
   const preexistingOmpAgentDir =
     piAgentKind === 'omp'
@@ -884,20 +806,13 @@ export function buildPtyHostEnv(
       : resolveScopedPiAgentSourceDir(baseEnv, 'omp')
 
   if (opts.agentStatusHooksEnabled) {
-    // Why: OPENCODE_CONFIG_DIR is a singular path, not a colon-list, so a user
-    // value cannot coexist with an Orca-only injection. Hand the user's value
-    // (when present) to the hook service and let it materialize a source-scoped
-    // mirror overlay that lets the user's plugins and Orca's status plugin
-    // load together. See docs/opencode-config-dir-collision.md.
+    // Why: OPENCODE_CONFIG_DIR is a single path, not a colon-list; mirror the user's value into an overlay so their plugins and Orca's status plugin coexist. See docs/opencode-config-dir-collision.md.
     Object.assign(baseEnv, openCodeHookService.buildPtyEnv(id, preexistingOpenCodeConfigDir))
     if (baseEnv.OPENCODE_CONFIG_DIR) {
-      // Why: ~/.zshrc can re-export the user's default after spawn; shell-ready
-      // wrappers restore this PTY-scoped value after user startup files run.
+      // Why: ~/.zshrc can re-export the user's default after spawn; shell-ready wrappers restore this PTY-scoped value.
       baseEnv.ORCA_OPENCODE_CONFIG_DIR = baseEnv.OPENCODE_CONFIG_DIR
       if (preexistingOpenCodeConfigDir) {
-        // Why: terminals launched from another Orca terminal inherit the overlay
-        // as OPENCODE_CONFIG_DIR; keep the original source so overlays do not
-        // mirror overlays and drop the user's real config.
+        // Why: nested Orca terminals inherit the overlay as OPENCODE_CONFIG_DIR; keep the real source so overlays don't mirror overlays.
         baseEnv.ORCA_OPENCODE_SOURCE_CONFIG_DIR = preexistingOpenCodeConfigDir
       } else {
         delete baseEnv.ORCA_OPENCODE_SOURCE_CONFIG_DIR
@@ -928,24 +843,14 @@ export function buildPtyHostEnv(
     })
   }
 
-  // Why: Claude/Codex native hooks run inside the shell process, so Orca
-  // must inject the loopback receiver coordinates before the agent starts.
-  // Without these env vars the global hook config cannot map callbacks back
-  // to the correct Orca pane.
-  // Why: nested Orca terminals can inherit another process's hook endpoint or
-  // token. Strip all hook runtime coordinates before injecting this PTY's fresh
-  // server values so callbacks route to the owning app/runtime.
+  // Why: strip inherited hook coordinates before injecting this PTY's fresh loopback receiver, so nested-terminal callbacks route to the owning pane.
   for (const key of AGENT_HOOK_RUNTIME_ENV_KEYS) {
     delete baseEnv[key]
   }
   if (opts.agentStatusHooksEnabled) {
     Object.assign(baseEnv, agentHookServer.buildPtyEnv())
     if (opts.isWsl === true) {
-      // Why: hook POSTs to 127.0.0.1 die inside WSL's NAT namespace. Ensure
-      // the guest-resident relay for this distro (covers fresh spawns and
-      // post-restart reattach re-spawns), and once the relay has reported the
-      // guest home, point restart re-coordination at the relay-written
-      // guest-side endpoint file instead of the /p-translated Windows one.
+      // Why: hook POSTs to 127.0.0.1 die inside WSL's NAT namespace; use the guest-resident relay's endpoint instead of the Windows one.
       const distro = opts.wslDistro ?? null
       wslHookRelayManager.ensureForDistro(distro)
       const guestEndpoint = wslHookRelayManager.getGuestEndpointFilePath(distro)
@@ -955,9 +860,7 @@ export function buildPtyHostEnv(
     }
   }
 
-  // Why: PI_CODING_AGENT_DIR owns Pi's / OMP's full config/session root. Keep
-  // that home as the user's normal source of truth and install only Orca-owned,
-  // env-guarded extension files into the selected agent's extension dir.
+  // Why: PI_CODING_AGENT_DIR is the user's config/session root; install only Orca-owned extension files, don't override it.
   if (opts.agentStatusHooksEnabled) {
     clearPiAgentShadowEnv(baseEnv, 'pi')
     clearPiAgentShadowEnv(baseEnv, 'omp')
@@ -973,8 +876,7 @@ export function buildPtyHostEnv(
       exposePiManagedExtensionEnv(baseEnv, 'omp', ompEnv)
     }
   } else {
-    // Why: when agent status is disabled we must strip BOTH kinds' shadow vars
-    // so a nested PTY does not inherit a stale overlay from either agent.
+    // Why: strip BOTH kinds' shadow vars so a nested PTY can't inherit a stale overlay from either agent.
     restoreOrStripOverlayEnv(baseEnv, {
       primary: 'PI_CODING_AGENT_DIR',
       overlay: 'ORCA_PI_CODING_AGENT_DIR',
@@ -988,25 +890,20 @@ export function buildPtyHostEnv(
     delete baseEnv.ORCA_OMP_STATUS_EXTENSION
   }
 
-  // Why: Codex account switching now materializes auth into an Orca-scoped
-  // runtime home, and Codex launched inside Orca terminals must use that same
-  // prepared home as quota fetches and other entry points. Keep the override
-  // PTY-scoped so dev/prod Orcas do not share hooks through ~/.codex.
+  // Why: keep the Codex home override PTY-scoped so dev/prod Orcas don't share hooks through ~/.codex.
   if (opts.skipCodexHomeEnv) {
     delete baseEnv.CODEX_HOME
     delete baseEnv.ORCA_CODEX_HOME
   } else if (opts.selectedCodexHomePath) {
     baseEnv.CODEX_HOME = opts.selectedCodexHomePath
-    // Why: user startup files may re-export CODEX_HOME; shell-ready wrappers
-    // restore this runtime home before Codex can be launched from the prompt.
+    // Why: user startup files may re-export CODEX_HOME; shell-ready wrappers restore this runtime home before Codex launches.
     baseEnv.ORCA_CODEX_HOME = opts.selectedCodexHomePath
   }
 
   // Why: WSL shells need the managed userData root for shell-ready wrappers; dev-mode terminals need the same export so `orca` targets the live dev instance.
   if (opts.isWsl) {
     baseEnv.ORCA_USER_DATA_PATH = opts.userDataPath
-    // Why: managed WSL registration deliberately uses `orca-ide`; exposing
-    // that literal keeps agent guidance scoped to WSL without a bare-orca shim.
+    // Why: managed WSL registration uses `orca-ide`; exposing that literal scopes agent guidance to WSL without a bare-orca shim.
     baseEnv.ORCA_CLI_COMMAND = opts.isPackaged ? 'orca-ide' : 'orca-dev'
   } else {
     if (!opts.isPackaged) {
@@ -1018,16 +915,10 @@ export function buildPtyHostEnv(
   if (!opts.isPackaged) {
     const devCliBin = join(opts.userDataPath, 'cli', 'bin')
     const inheritedPath = readInheritedPath(baseEnv)
-    // Why: avoid a trailing delimiter when PATH is empty — some shells
-    // treat an empty segment as `.`, which would let commands resolve from
-    // the current working directory (a foot-gun we don't want to create
-    // for dev terminals).
+    // Why: an empty PATH segment resolves as `.` in some shells (commands run from cwd); avoid a trailing delimiter.
     baseEnv.PATH = inheritedPath ? `${devCliBin}${delimiter}${inheritedPath}` : devCliBin
   } else if (process.platform === 'linux') {
-    // Why: the Linux CLI installs as `orca-ide` (never shadowing GNOME's
-    // /usr/bin/orca screen reader), but agent-facing guidance invokes bare
-    // `orca`. Scope a bare-`orca` shim to Orca-managed PTYs so agents reach
-    // the Orca CLI instead of the screen reader (stablyai/orca#7904).
+    // Why: bare-`orca` shim scoped to Orca PTYs — Linux CLI installs as `orca-ide` to avoid shadowing GNOME's /usr/bin/orca screen reader (stablyai/orca#7904).
     const shimDir = ensureLinuxTerminalOrcaCliShimDir({ userDataPath: opts.userDataPath })
     if (shimDir) {
       const inheritedEntries = readInheritedPath(baseEnv)
@@ -1037,10 +928,7 @@ export function buildPtyHostEnv(
     }
   }
 
-  // Why: GitHub attribution should only affect commands launched from
-  // Orca's own PTYs. Injecting lightweight PATH shims at spawn-time keeps
-  // the behavior local to Orca instead of rewriting user git config or
-  // touching external shells.
+  // Why: PATH shims keep GitHub attribution scoped to Orca's own PTYs without rewriting user git config.
   if (!opts.githubAttributionEnabled) {
     delete baseEnv.ORCA_ENABLE_GIT_ATTRIBUTION
     delete baseEnv.ORCA_GIT_COMMIT_TRAILER
@@ -1095,8 +983,7 @@ function beginPtySpawnForWorktree(
       finishes.push(beginTerminalInstall(candidate, connectionId ?? undefined))
     }
   } catch (error) {
-    // Why: the worktree ID and actual cwd can belong to different roots. If
-    // either is deleting, release any earlier admission before rejecting.
+    // Why: worktree ID and cwd can be different roots; release earlier admissions before rejecting.
     finishes.toReversed().forEach((finish) => finish())
     throw error
   }
@@ -1119,13 +1006,8 @@ export function getSshPtyProvider(connectionId: string): IPtyProvider | undefine
 }
 
 /** Get the installed PTY provider (for direct access in tests/runtime).
- *
- * Returns the installed PTY provider — after `setLocalPtyProvider()` runs
- * during daemon init this may be the routed adapter (specifically either
- * `DaemonPtyAdapter` or its `DaemonPtyRouter` wrapper). Callers needing
- * `LocalPtyProvider`-specific methods (`killOrphanedPtys`,
- * `advanceGeneration`, `getPtyProcess`) must type-narrow or import the
- * concrete class directly. */
+ *  After daemon init this may be a DaemonPtyAdapter/DaemonPtyRouter, not LocalPtyProvider;
+ *  callers needing LocalPtyProvider-specific methods must type-narrow or import the class. */
 export function getLocalPtyProvider(): IPtyProvider {
   return localProvider
 }
@@ -1149,17 +1031,12 @@ export function getPtyIdsForConnection(connectionId: string): string[] {
 
 /**
  * Remove all PTY ownership entries for a given connectionId.
- * Why: when an SSH connection is closed, the remote PTYs are gone but their
- * ownership entries linger. Without cleanup, subsequent spawn calls could
- * look up a stale provider for those PTY IDs, and the map grows unboundedly.
+ * Why: SSH close leaves stale ownership entries that route later spawns to a dead provider and grow unbounded.
  */
 export function clearPtyOwnershipForConnection(connectionId: string): void {
   for (const [ptyId, connId] of ptyOwnership) {
     if (connId === connectionId) {
-      // Why: remote PTYs are gone after the SSH connection closes — their
-      // paneKey-scoped caches (agent-hooks server, OpenCode, Pi) must be swept
-      // the same way a local onExit would, otherwise they leak indefinitely
-      // for the process lifetime.
+      // Why: SSH close bypasses the local onExit, so sweep paneKey-scoped caches manually or they leak.
       clearProviderPtyState(ptyId)
       ptyOwnership.delete(ptyId)
     }
@@ -1169,13 +1046,10 @@ export function clearPtyOwnershipForConnection(connectionId: string): void {
 // ─── Provider-scoped PTY state cleanup ──────────────────────────────
 
 export function clearProviderPtyState(id: string): void {
-  // Why: OpenCode and Pi both allocate PTY-scoped runtime state outside the
-  // node-pty process table. Centralizing provider cleanup avoids drift where a
-  // new teardown path forgets to remove one provider's overlay/hook state.
+  // Why: OpenCode and Pi allocate PTY-scoped state outside the node-pty process table; centralizing cleanup avoids a teardown path forgetting one provider's overlay/hook state.
   openCodeHookService.clearPty(id)
   piTitlebarExtensionService.clearPty(id)
-  // Why: SSH exit and connection-teardown paths bypass pty.ts's local onExit
-  // callback but still need to release Claude account-switch guards.
+  // Why: SSH exit/teardown paths bypass pty.ts's local onExit but still must release Claude account-switch guards.
   markClaudePtyExited(id)
   ptySizes.delete(id)
   lastInputAtByPty.delete(id)
@@ -1185,9 +1059,7 @@ export function clearProviderPtyState(id: string): void {
   rendererVisibilityKnownPtys.delete(id)
   pendingHiddenRendererResizeOutputPtys.delete(id)
   deliveredHiddenRendererResizeOutputPtys.delete(id)
-  // Why: every PTY teardown path funnels through here (local exit, daemon
-  // shutdown, SSH exit/connection teardown) — hidden/interest gate bits must
-  // not outlive the PTY or a reused map entry could silently gate a new one.
+  // Why: every teardown path funnels through here — hidden/interest gate bits must not outlive the PTY or a reused map entry could silently gate a new one.
   clearHiddenRendererPtyDeliveryState(id)
   clearBackgroundedDeliverySyncForPty(id)
   providerSnapshotRequiredPtys.delete(id)
@@ -1195,21 +1067,14 @@ export function clearProviderPtyState(id: string): void {
   clearNativeWindowsConptyPty(id)
   const paneKey = ptyPaneKey.get(id)
   const stillOwnsPaneKey = paneKey ? paneKeyPtyId.get(paneKey) === id : false
-  // Why: drop the memory-collector registration so a dead PTY does not keep
-  // trying to resolve its (now-dead) pid on every snapshot. Safe no-op for
-  // PTYs that were never registered (SSH-owned).
+  // Why: drop the memory-collector registration so a dead PTY doesn't resolve its dead pid on every snapshot; no-op for never-registered (SSH-owned) PTYs.
   unregisterPty(id)
-  // Why: cover lifecycle paths that bypass runtime.onPtyExit — SSH reattach
-  // failures, SSH connection shutdown (clearPtyOwnershipForConnection), and
-  // daemon spawn-failure cleanup all funnel through here. Without this the
-  // watcher's per-PTY buffer and worktree binding outlive the PTY.
+  // Why: cover paths that bypass runtime.onPtyExit (SSH reattach/shutdown, daemon spawn-failure) — else the watcher's per-PTY buffer and worktree binding outlive the PTY.
   advertisedUrlWatcher.unbindPty(id)
   clearMigrationUnsupportedPty(id)
   agentHookServer.clearPaneKeyAliasesForPty(id, {
     shouldClearStablePaneKey: (stablePaneKey) => {
-      // Why: when this PTY never rebuilt ptyPaneKey after restart, alias
-      // ownership is our only proof. Once a newer PTY owns the same stable
-      // paneKey, alias teardown must not erase that newer status.
+      // Why: when this PTY never rebuilt ptyPaneKey after restart, alias ownership is our only proof — don't erase a newer PTY that now owns the same stable paneKey.
       const stablePaneOwner = paneKeyPtyId.get(stablePaneKey)
       if (stablePaneOwner && stablePaneOwner !== id) {
         return false
@@ -1217,10 +1082,7 @@ export function clearProviderPtyState(id: string): void {
       return !paneKey || (stillOwnsPaneKey && stablePaneKey === paneKey)
     }
   })
-  // Why: the hook server's per-paneKey caches (lastPrompt / lastTool) would
-  // otherwise accumulate entries for dead panes over the process lifetime.
-  // Use the spawn-time paneKey mapping since the server has no other way to
-  // correlate a ptyId back to its paneKey.
+  // Why: clear the hook server's per-paneKey caches (via the spawn-time paneKey mapping, its only ptyId→paneKey correlation) so dead panes don't accumulate over process lifetime.
   if (paneKey) {
     if (stillOwnsPaneKey) {
       agentHookServer.clearPaneState(paneKey)
@@ -1228,9 +1090,7 @@ export function clearProviderPtyState(id: string): void {
     }
     ptyPaneKey.delete(id)
     if (stillOwnsPaneKey) {
-      // Why: notify registered consumers AFTER we've dropped the paneKey↔ptyId
-      // entries so a listener that re-reads the map sees the post-teardown
-      // state. Wrap each call so one throwing listener cannot block the rest.
+      // Why: notify AFTER dropping the paneKey↔ptyId entries so a listener re-reading the map sees post-teardown state; wrap each so one throw can't block the rest.
       for (const listener of paneKeyTeardownListeners) {
         try {
           listener(paneKey)
@@ -1250,10 +1110,7 @@ export function setPtyOwnership(id: string, connectionId: string | null): void {
   ptyOwnership.set(id, connectionId)
 }
 
-// Why: localProvider.onData/onExit return unsubscribe functions. Without
-// storing and calling these on re-registration, macOS app re-activation
-// creates a new BrowserWindow and re-calls registerPtyHandlers, leaking
-// duplicate listeners that forward every event twice.
+// Why: store onData/onExit unsubscribers so macOS re-activation re-calling registerPtyHandlers doesn't leak duplicate listeners forwarding every event twice.
 let localDataUnsub: (() => void) | null = null
 let localExitUnsub: (() => void) | null = null
 let localBackgroundStreamUnsub: (() => void) | null = null
@@ -1261,32 +1118,18 @@ let didFinishLoadHandler: (() => void) | null = null
 let didFinishLoadWebContents: WebContents | null = null
 let rendererLifecycleResetWebContents: WebContents | null = null
 let rendererLifecycleResetHandler: (() => void) | null = null
-// Why: the hidden-delivery gate's interest/hidden registries mirror renderer
-// state (ref-counted holds, per-pane hidden marks). A reload or renderer
-// crash destroys the owners without unregistering, so the registries are
-// reset whenever the renderer process is replaced
-// (resetRendererScopedHiddenPtyDeliveryState preserves drop memory).
+// Why: the hidden-delivery gate registries mirror renderer state; a reload/crash destroys owners without unregistering, so they reset when the renderer is replaced (drop memory preserved).
 let rendererGateResetLoadHandler: (() => void) | null = null
 let rendererGateResetGoneHandler: (() => void) | null = null
 let rendererGateResetWebContents: WebContents | null = null
-// Why: the backgrounded-delivery dedupe map lives in the registerPtyHandlers
-// closure but teardown funnels through module-scope clearProviderPtyState.
+// Why: the backgrounded-delivery dedupe map lives in the registerPtyHandlers closure but teardown funnels through module-scope clearProviderPtyState.
 let clearBackgroundedDeliverySyncForPty: (id: string) => void = () => {}
-// Why: after daemon keep-tail thinning, main's mirror contains only the kept
-// tail. Recovery must keep consulting the daemon's complete model until exit.
+// Why: after daemon keep-tail thinning main's mirror holds only the kept tail, so recovery must keep consulting the daemon's complete model until exit.
 const providerSnapshotRequiredPtys = new Set<string>()
-// Why: did-start-loading also fires for in-page subframe loads (e.g. the
-// sandboxed srcDoc iframes notebook HTML output renders), which are not renderer
-// lifecycle resets. A dedicated handler filters those via isLoadingMainFrame so a
-// subframe load cannot reset delivery accounting on the still-alive page.
+// Why: did-start-loading also fires for in-page subframe loads (notebook srcDoc iframes); a dedicated handler filters those via isLoadingMainFrame.
 let rendererDidStartLoadingHandler: (() => void) | null = null
 
-// Why: the "Restart daemon" path needs to re-bind provider→renderer listeners
-// against the freshly-created adapter after replaceDaemonProvider swaps the
-// module-level `localProvider` pointer. Without this, old subscribers stay
-// bound to the disposed adapter and new PTY data silently drops. Saved at
-// module scope so the restart flow (src/main/daemon/daemon-init.ts) can
-// trigger a rebind without re-running the full registerPtyHandlers setup.
+// Why: Restart daemon must re-bind provider→renderer listeners after replaceDaemonProvider swaps localProvider, else subscribers stay bound to the disposed adapter and new PTY data silently drops.
 let rebindProviderListeners: (() => void) | null = null
 
 export function rebindLocalProviderListeners(): void {
@@ -1308,9 +1151,7 @@ export type PtyRendererDeliveryDebugSnapshot = {
   peakMaxRendererInFlightCharsByPty: number
   ackGatedFlushSkipCount: number
   hiddenDeliveryGatedPtyCount: number
-  /** Hidden-gated ptys the renderer ALSO reports visible/active — a
-   *  contradiction that should be zero; nonzero means the user may be staring
-   *  at a pane main is deliberately starving (v1.4.124-rc.2.perf field lead). */
+  /** Hidden-gated ptys the renderer ALSO reports visible/active — a contradiction that should be zero (v1.4.124-rc.2.perf field lead). */
   hiddenDeliveryGatedVisiblePtyCount: number
   hiddenDeliveryGatedActivePtyCount: number
   deliveryInterestPtyCount: number
@@ -1319,27 +1160,21 @@ export type PtyRendererDeliveryDebugSnapshot = {
   pendingDroppedChars: number
   /** One-paste freeze diagnostics: per-pty delivery table + event history. */
   diagnostics: PtyMainDeliveryDiagnostics
-  // Why: a nonzero lastLifecycleResetClearedChars is the exact signature of the
-  // leaked-delivery-accounting freeze this reset fixes; the count tracks how
-  // many renderer lifecycle resets have run since launch.
+  // Why: a nonzero lastLifecycleResetClearedChars is the exact signature of the leaked-accounting freeze this reset fixes.
   rendererLifecycleResetCount: number
   lastLifecycleResetClearedChars: number
-  // Why: the boot-window hold early-returns before ackGatedFlushSkipCount++, so
-  // without these a held gate is invisible in the snapshot; forcedCount > 0 flags
-  // that the watchdog self-healed a lost handshake.
+  // Why: the boot-window hold early-returns before ackGatedFlushSkipCount++, so these expose an otherwise-invisible held gate; forcedCount > 0 flags a watchdog self-heal.
   rendererPtyDispatcherReady: boolean
   rendererDispatcherReadyForcedCount: number
 }
 
-// Why module scope: breadcrumb writers live both inside registerPtyHandlers
-// (gate marks, heals) and outside it (renderer lifecycle resets).
+// Why module scope: breadcrumb writers live both inside registerPtyHandlers and outside it (renderer lifecycle resets).
 const mainDeliveryBreadcrumbs = createPtyDeliveryBreadcrumbRing()
 let lastPowerSuspendAtMs: number | null = null
 let lastPowerResumeAtMs: number | null = null
 let powerSignalBreadcrumbsInstalled = false
 
-// Why: both field freeze variants correlate with display sleep; suspend/resume
-// timestamps in the report let us line breadcrumbs up against the wake.
+// Why: both field freeze variants correlate with display sleep; suspend/resume timestamps let breadcrumbs line up against the wake.
 function installPowerSignalBreadcrumbs(): void {
   if (powerSignalBreadcrumbsInstalled) {
     return
@@ -1387,12 +1222,9 @@ let readPtyRendererDeliveryDebugSnapshot = (): PtyRendererDeliveryDebugSnapshot
   ...EMPTY_PTY_RENDERER_DELIVERY_DEBUG_SNAPSHOT
 })
 let resetPtyRendererDeliveryDebugSnapshot = (): void => {}
-// Bridged into the registerPtyHandlers closure (like readPtyRendererDeliveryDebugSnapshot)
-// so the module-scope lifecycle-reset handler can zero the closure-owned delivery
-// accounting on a renderer reload/crash.
+// Bridged into the registerPtyHandlers closure so the module-scope lifecycle-reset handler can zero closure-owned delivery accounting on renderer reload/crash.
 let resetRendererDeliveryAccountingForLifecycleReset = (): void => {}
-// Bridged so a re-registration (new window) can cancel the prior closure's
-// dispatcher-ready watchdog before wiring up its own.
+// Bridged so a re-registration can cancel the prior closure's dispatcher-ready watchdog before wiring its own.
 let clearRendererDispatcherReadyWatchdog = (): void => {}
 
 export function getPtyRendererDeliveryDebugSnapshot(): PtyRendererDeliveryDebugSnapshot {
@@ -1412,15 +1244,12 @@ function clearDidFinishLoadHandler(): void {
 }
 
 function markRendererPtysHiddenForRendererLifecycleReset(): void {
-  // A reload/crash in the history is load-bearing context for any freeze
-  // report ("did the user already reload before capturing?").
+  // A reload/crash in the breadcrumb history is load-bearing context for any freeze report.
   mainDeliveryBreadcrumbs.record('renderer-lifecycle-reset')
-  // Why: renderer-owned hints die with the page; keep known-visibility state so
-  // surviving daemon/SSH PTYs fail closed until the new renderer reports again.
+  // Why: renderer-owned hints die with the page; clear visibility so surviving daemon/SSH PTYs fail closed until the new renderer reports.
   activeRendererPtys.clear()
   visibleRendererPtys.clear()
-  // Why: the dead page never ACKs its in-flight bytes, so leaked in-flight/pending
-  // accounting would delivery-gate surviving PTYs forever after a reload/crash.
+  // Why: the dead page never ACKs its in-flight bytes, so leaked accounting would delivery-gate surviving PTYs forever after a reload/crash.
   resetRendererDeliveryAccountingForLifecycleReset()
 }
 
@@ -1451,11 +1280,7 @@ function registerRendererLifecycleResetHandlers(webContents: WebContents): void
   markRendererPtysHiddenForRendererLifecycleReset()
   rendererLifecycleResetWebContents = webContents
   rendererLifecycleResetHandler = markRendererPtysHiddenForRendererLifecycleReset
-  // Why: did-start-loading also fires for in-page subframe loads (sandboxed
-  // srcDoc iframes in notebook HTML output), where isLoadingMainFrame() is false.
-  // Only a main-frame load is a real renderer lifecycle reset; filtering here
-  // stops a subframe load from clearing pendingData and holding the send gate
-  // (a spurious multi-second freeze) on the otherwise-alive page.
+  // Why: did-start-loading also fires for in-page subframe loads (notebook srcDoc iframes); filter via isLoadingMainFrame so a subframe load can't clear pendingData and freeze the alive page.
   rendererDidStartLoadingHandler = () => {
     if (!webContents.isLoadingMainFrame()) {
       return
@@ -1484,11 +1309,7 @@ function clearRendererGateResetHandlers(): void {
   rendererGateResetWebContents = null
 }
 
-// Why: the "Restart daemon" flow needs to detach listeners from the current
-// adapter *after* synthetic pty:exit events fan out (so the renderer receives
-// them) but *before* replaceDaemonProvider swaps in the new adapter (so the
-// new provider isn't missing bindings). This export narrows that window to
-// the caller.
+// Why: Restart daemon must detach listeners AFTER synthetic pty:exit events fan out but BEFORE replaceDaemonProvider swaps the adapter; this export narrows that window to the caller.
 export function unbindLocalProviderListeners(): void {
   localDataUnsub?.()
   localExitUnsub?.()
@@ -1510,15 +1331,11 @@ export function registerPtyHandlers(
   options?: {
     awaitLocalPtyStartup?: () => Promise<void>
     awaitLocalPtyProviderStartup?: () => Promise<void>
-    // Why: returns true (once, consuming the flag) for the crash-recovery reload
-    // so its did-finish-load skips the orphan sweep and keeps live PTYs (#5787).
+    // Why: returns true once for the crash-recovery reload so its did-finish-load skips the orphan sweep and keeps live PTYs (#5787).
     isRecoveryReloadInFlight?: (webContentsId: number) => boolean
   }
 ): void {
-  // Why: a re-registration means a new window owns delivery. Cancel any watchdog the
-  // prior closure armed, and neutralize its bridged reset so the registration-time
-  // mark-hidden below can't arm a timer against the now-dead closure — the fresh
-  // closure re-installs both bridges once its state is set up.
+  // Why: a re-registration means a new window owns delivery — cancel the prior closure's watchdog and neutralize its bridged reset so mark-hidden below can't arm a timer against the dead closure.
   clearRendererDispatcherReadyWatchdog()
   resetRendererDeliveryAccountingForLifecycleReset = () => {}
   registerRendererLifecycleResetHandlers(mainWindow.webContents)
@@ -1527,9 +1344,7 @@ export function registerPtyHandlers(
     if (connectionId) {
       return undefined
     }
-    // Why: during desktop cold start the daemon provider swap now overlaps
-    // first paint. Local spawns must wait before resolving getProvider(), while
-    // SSH/headless paths do not use the desktop daemon.
+    // Why: during cold start the daemon provider swap overlaps first paint, so local spawns must wait; SSH/headless don't use the desktop daemon.
     return options?.awaitLocalPtyStartup?.()
   }
 
@@ -1542,8 +1357,7 @@ export function registerPtyHandlers(
     return options?.awaitLocalPtyProviderStartup?.() ?? options?.awaitLocalPtyStartup?.()
   }
 
-  // Remove any previously registered handlers so we can re-register them
-  // (e.g. when macOS re-activates the app and creates a new window).
+  // Remove prior handlers so re-registration (e.g. macOS re-activate creating a new window) doesn't double-register.
   ipcMain.removeHandler('pty:spawn')
   ipcMain.removeHandler('pty:kill')
   ipcMain.removeHandler('pty:listSessions')
@@ -1570,11 +1384,7 @@ export function registerPtyHandlers(
   ipcMain.removeAllListeners('pty:deliveryResyncResponse')
   ipcMain.removeAllListeners('pty:serializeBuffer:response')
 
-  // Configure the local provider with app-specific hooks.
-  // Why: only LocalPtyProvider has the configure() method — daemon-backed
-  // providers handle subprocess spawning internally and don't need main-process
-  // hook injection. The hooks (buildSpawnEnv, onSpawned, etc.) only make sense
-  // when the PTY lives in the Electron main process.
+  // Why: only LocalPtyProvider needs main-process hook injection; daemon-backed providers spawn subprocesses internally.
   if (localProvider instanceof LocalPtyProvider) {
     localProvider.configure({
       isHistoryEnabled: () => getSettings?.()?.terminalScopeHistoryByWorktree ?? true,
@@ -1607,8 +1417,7 @@ export function registerPtyHandlers(
           agentStatusHooksEnabled: isAgentStatusHooksEnabled(getSettings?.()),
           networkProxySettings: getSettings?.()
         })
-        // Why: agents need their own terminal handle at process start so they
-        // can self-identify in orchestration messages without an extra RPC.
+        // Why: agents need their terminal handle at process start to self-identify in orchestration messages without an extra RPC.
         const requestedHandle = baseEnv.ORCA_TERMINAL_HANDLE
         const preAllocatedHandle =
           requestedHandle && trustedTerminalHandleEnv.has(requestedHandle)
@@ -1637,21 +1446,14 @@ export function registerPtyHandlers(
     })
   }
 
-  // Why: batching PTY data into short flush windows (8ms ≈ half a frame)
-  // reduces IPC round-trips from hundreds/sec to ~120/sec under high
-  // throughput. Keystroke echo/redraws bypass this below because agent TUIs
-  // already spend tens of ms producing their redraw.
+  // Why: batching PTY data into short flush windows cuts IPC round-trips from hundreds/sec to ~120/sec; keystroke echo/redraws bypass it below.
   type PendingPtyData = {
     data: string
     startSeq?: number
     rawLength?: number
     transformed?: true
     containsBackgroundOutput?: boolean
-    // Why droppedOutput (not main's droppedBacklog trim): this branch bounds
-    // the unsent backlog with the O(1) drop-to-sentinel + query-salvage +
-    // snapshot-restore mechanism below, which strictly supersedes main's
-    // #7630 keep-2MB-tail trim — carrying both would race two cap policies
-    // over the same buffer.
+    // Why droppedOutput (not main's droppedBacklog trim): this branch's drop-to-sentinel + snapshot-restore supersedes #7630's 2MB-tail trim; both would race two cap policies over one buffer.
     droppedOutput?: true
   }
 
@@ -1666,13 +1468,9 @@ export function registerPtyHandlers(
   }
 
   const pendingData = new Map<string, PendingPtyData>()
-  // Why: one restore marker per overflow episode — cleared when the entry
-  // fully drains so a later overflow re-marks the renderer exactly once.
+  // Why: one restore marker per overflow episode — cleared on full drain so a later overflow re-marks exactly once.
   const pendingOverflowMarkedPtys = new Set<string>()
-  // Why: TCP-style cumulative delivery accounting. Relative in-flight counters
-  // make every lost ACK a permanent debt; monotonic sent/acked totals self-heal
-  // as soon as any later ACK (or resync reply) reports the renderer's full
-  // processed count.
+  // Why: TCP-style cumulative accounting — monotonic sent/acked totals self-heal on any later ACK, where relative in-flight counters would make each lost ACK a permanent debt.
   type RendererPtyDeliveryAccounting = {
     sentChars: number
     ackedChars: number
@@ -1689,45 +1487,27 @@ export function registerPtyHandlers(
   let deliveryResyncTimer: ReturnType<typeof setTimeout> | null = null
   let deliveryResyncUnansweredWarnLogged = false
   let lastAckReceivedAtMs: number | null = null
-  // Why 2ms: pairs with the daemon stream batcher (see
-  // daemon-stream-data-batcher.ts) — both hops charged an expected
-  // half-window per chunk; 2ms keeps flood coalescing at negligible IPC
-  // overhead while cutting the pipeline's fixed latency tax.
+  // Why 2ms: pairs with the daemon stream batcher (daemon-stream-data-batcher.ts); keeps flood coalescing at negligible IPC overhead while cutting the pipeline's latency tax.
   const PTY_BATCH_INTERVAL_MS = 2
   const PTY_BATCH_DRAIN_CONTINUE_MS = 1
   const PTY_BATCH_FLUSH_CHUNK_CHARS = 16 * 1024
   const PTY_BATCH_FLUSH_MAX_WRITES = 2
   const PTY_RENDERER_IN_FLIGHT_HIGH_WATER_CHARS = 512 * 1024
   const PTY_RENDERER_TOTAL_IN_FLIGHT_HIGH_WATER_CHARS = 8 * 1024 * 1024
-  // Why: while the renderer cannot receive (frozen, starved, mid-reload), a
-  // chatty PTY used to grow its pendingData string without bound — main-process
-  // heap ballooning that a renderer reload cannot clear (main's #7630 fixed the
-  // same Win/Linux background-throttled-renderer leak with a 2MB tail trim;
-  // this branch's sentinel mechanism supersedes it). Beyond this cap the
-  // buffered bytes are dropped and the pane heals from the main-owned buffer
-  // snapshot via the droppedOutput sentinel (renderer hidden-output restore).
-  // Why read settings live: the cap scales with the user's scrollback setting
-  // so power users don't lose lines their scrollback would have retained.
+  // Why: cap unbounded pendingData growth when the renderer can't receive (frozen/reloading); beyond it bytes drop and the pane heals from the main buffer snapshot via the droppedOutput sentinel (#7630).
+  // Why read settings live: the cap scales with the user's scrollback so power users don't lose lines their scrollback would have retained.
   const pendingDataCapChars = (): number =>
     terminalOutputBacklogCapChars(getSettings?.().terminalScrollbackRows)
-  // Why: self-heal bound for the dispatcher-ready gate — if a reloaded page never
-  // sends pty:rendererDispatcherReady (lost IPC), force sends back on after this
-  // window so a dropped handshake can't itself become a permanent hold.
+  // Why: self-heal bound — if a reloaded page never sends pty:rendererDispatcherReady, force sends on after this window so a lost handshake can't become a permanent hold.
   const PTY_DISPATCHER_READY_WATCHDOG_MS = 10_000
   const PTY_RENDERER_INTERACTIVE_RESERVE_CHARS = 256 * 1024
-  // Why: active panes need a bounded lane through old hidden bulk output so a
-  // keystroke redraw can reach the renderer before every background ACK lands.
+  // Why: reserve a bounded lane so an active pane's keystroke redraw reaches the renderer ahead of hidden bulk output's ACKs.
   const PTY_RENDERER_ACTIVE_PTY_IN_FLIGHT_RESERVE_CHARS = 512 * 1024
-  // Why: request/response hygiene only — this timeout never mutates delivery
-  // state. It clears the outstanding-probe flag so a later gated arrival can
-  // probe again, and logs once per silent streak for field diagnosis.
+  // Why: request/response hygiene only (never mutates delivery state) — clears the outstanding-probe flag so a later arrival can re-probe, logs once per silent streak.
   const PTY_DELIVERY_RESYNC_TIMEOUT_MS = 5_000
-  // Why: a heal write-off destroys delivery accounting; require main to have
-  // seen zero ACKs for this long too, independent of the renderer's own
-  // two-silent-ticks evidence, before believing the channel is dead.
+  // Why: a heal write-off destroys delivery accounting; require this much main-side ACK silence (independent of renderer evidence) before declaring the channel dead.
   const PTY_DELIVERY_HEAL_MIN_ACK_SILENCE_MS = 10_000
-  // Why: keep the immediate path bounded to keystroke-sized TUI redraws;
-  // large output and non-interactive output must still use the batcher.
+  // Why: keep the immediate path to keystroke-sized TUI redraws; large/non-interactive output must use the batcher.
   const INTERACTIVE_OUTPUT_WINDOW_MS = 100
   const INTERACTIVE_OUTPUT_MAX_CHARS = 1024
   const INTERACTIVE_REDRAW_MAX_CHARS = PTY_BATCH_FLUSH_CHUNK_CHARS
@@ -1739,24 +1519,13 @@ export function registerPtyHandlers(
   let ackGatedFlushSkipCount = 0
   let rendererLifecycleResetCount = 0
   let lastLifecycleResetClearedChars = 0
-  // Why: how many times the watchdog force-opened the gate because no handshake
-  // arrived; nonzero flags a dropped-handshake self-heal (degrades to pre-§1b
-  // behavior, observable + recoverable at the next reset, never a freeze).
+  // Why: count of watchdog gate force-opens (no handshake arrived); nonzero flags a dropped-handshake self-heal.
   let rendererDispatcherReadyForcedCount = 0
-  // Why: gate sends until the current page's pty:data listener is registered.
-  // A reloaded/first-load page has no listener yet, so webContents.send drops
-  // the bytes but still counts them in-flight, permanently pinning the gate.
-  // Flipped true by the pty:rendererDispatcherReady handshake, reset false on
-  // every lifecycle reset (below); starts false so nothing sends pre-handshake.
+  // Why: gate sends until the page's pty:data listener exists; else webContents.send drops bytes but still counts them in-flight, permanently pinning the gate.
   let rendererPtyDispatcherReady = false
   let dispatcherReadyWatchdogTimer: ReturnType<typeof setTimeout> | null = null
 
-  // Why: watermark-driven producer pause/resume (terminal-performance
-  // initiative §5). Signal source is per-PTY pendingData only — renderer
-  // in-flight is already bounded by the ACK window above, while pendingData
-  // is what grows without bound when the renderer cannot keep up. Providers
-  // without support (SSH, legacy daemon protocol) surface no pauseProducer
-  // and the call chain no-ops; the pending cap still bounds memory then.
+  // Why: watermark producer pause/resume keyed on per-PTY pendingData (in-flight is already ACK-bounded); providers without pauseProducer no-op, memory still bounded by the pending cap.
   const producerFlowControl = new PtyProducerFlowController({
     pauseProducer: (id) => tryGetProviderForPty(id)?.pauseProducer?.(id),
     resumeProducer: (id) => tryGetProviderForPty(id)?.resumeProducer?.(id)
@@ -1769,20 +1538,8 @@ export function registerPtyHandlers(
     producerFlowControl.update(id, pendingData.get(id)?.data.length ?? 0)
   }
 
-  // Why this exists: hidden ptys are exempt from pendingData flow control
-  // (their bytes are dropped after model ingestion, so pendingData never
-  // grows), which let background agents run 100MB+ ahead of main in the
-  // daemon's stream-socket buffer and bury the visible pane's echo. The
-  // provider transport keep-tail thins backgrounded ptys' monitoring stream
-  // under backlog; this sync tells it which ptys qualify.
-  // Why keyed on the visibility registry (NOT gate marks or gate-effective
-  // shouldDrop): delivery claims and raw-byte sidecars describe transport
-  // ownership, while thinning asks the semantic question "does any visible
-  // view show this PTY?" Remote view subscribers (mobile/web live terminals)
-  // consume raw bytes from main's fan-out, so their presence vetoes thinning
-  // outright. Dedupe keeps visibility-sync churn off the wire; `?? false`
-  // also swallows the initial
-  // not-background state.
+  // Why: hidden ptys are exempt from pendingData flow control, so background agents can run 100MB+ ahead in the daemon stream buffer; this sync tells the provider transport which ptys to keep-tail thin.
+  // Why keyed on the visibility registry (not gate marks): thinning asks "does any visible view show this PTY?"; remote-view subscribers consume raw bytes, so their presence vetoes thinning.
   const backgroundedDeliverySyncByPty = new Map<string, boolean>()
   function syncPtyBackgroundedDelivery(id: string, caller: string): void {
     const background =
@@ -1840,9 +1597,7 @@ export function registerPtyHandlers(
       }
       maxRendererInFlightCharsByPty = Math.max(maxRendererInFlightCharsByPty, inFlight)
     }
-    // Why: the two renderer visibility signals must agree; a pty both
-    // hidden-gated and reported visible means main is starving a pane the
-    // user can see (v1.4.124-rc.2.perf blank-terminal field lead).
+    // Why: a pty both hidden-gated and reported visible means main is starving a visible pane (v1.4.124-rc.2.perf field lead).
     let hiddenDeliveryGatedVisiblePtyCount = 0
     for (const id of visibleRendererPtys) {
       if (isHiddenRendererPty(id)) {
@@ -1883,14 +1638,10 @@ export function registerPtyHandlers(
 
   const DELIVERY_DIAGNOSTICS_MAX_PTYS = 30
 
-  // Built only when the debug snapshot is actually read — never on the data
-  // path. Aggregate counters can't say WHICH pty is wedged or WHEN the state
-  // arose; this per-pty table + both-process breadcrumb history can.
+  // Built only when the debug snapshot is read (never on the data path): the per-pty table + breadcrumb history says WHICH pty is wedged and WHEN, unlike aggregate counters.
   function buildMainDeliveryDiagnostics(): PtyMainDeliveryDiagnostics {
     const now = Date.now()
-    // Hidden/visible/active set members are included even with no accounting
-    // entry: a pty gated before its first byte is exactly the wedge case the
-    // table must surface.
+    // Include hidden/visible/active members even without an accounting entry: a pty gated before its first byte is exactly the wedge case to surface.
     const ids = new Set([
       ...rendererDeliveryAccountingByPty.keys(),
       ...pendingData.keys(),
@@ -1929,15 +1680,13 @@ export function registerPtyHandlers(
     }
   }
 
-  // Why rate-limited: the contradiction persists chunk after chunk while
-  // latched; one line per minute keeps field logs readable but present.
+  // Why rate-limited: the contradiction persists chunk after chunk while latched; one line per minute keeps field logs readable but present.
   let lastHiddenDropContradictionWarnAtMs = 0
   function warnIfDroppingHiddenBytesForVisiblePty(id: string, droppedChars: number): void {
     if (!visibleRendererPtys.has(id) && !activeRendererPtys.has(id)) {
       return
     }
-    // Recorded before the warn rate limit: the ring coalesces repeats itself,
-    // and the contradiction must appear in the freeze report either way.
+    // Recorded before the warn rate limit: the ring coalesces repeats, and the contradiction must appear in the freeze report either way.
     mainDeliveryBreadcrumbs.record('hidden-drop-visible', {
       id: redactPtyIdForDiagnostics(id),
       droppedChars
@@ -1957,11 +1706,7 @@ export function registerPtyHandlers(
   }
 
   function recordPtyRendererDeliveryPressure(): void {
-    // Why: this fires on every PTY delivery event (per send, per flush, per
-    // onData append). Update the four diagnostic peaks directly instead of
-    // allocating a full 13-field debug snapshot object per call — that object
-    // is only needed when the debug getter is actually read. Peak values are
-    // computed identically to readCurrentPtyRendererDeliveryDebugSnapshot.
+    // Why update peaks directly: this fires on every delivery event, so avoid allocating a full 13-field snapshot object per call (only needed when the debug getter is read).
     let pendingChars = 0
     let maxPendingCharsByPty = 0
     for (const pending of pendingData.values()) {
@@ -1972,8 +1717,7 @@ export function registerPtyHandlers(
     peakPendingChars = Math.max(peakPendingChars, pendingChars)
     peakMaxPendingCharsByPty = Math.max(peakMaxPendingCharsByPty, maxPendingCharsByPty)
     peakRendererInFlightChars = Math.max(peakRendererInFlightChars, rendererInFlightTotalChars)
-    // Why derived per entry: this branch tracks cumulative sent/acked totals
-    // (TCP-style), not a per-pty in-flight map — in-flight is the difference.
+    // Why derived per entry: this tracks cumulative sent/acked totals (TCP-style), not a per-pty in-flight map — in-flight is the difference.
     let maxRendererInFlightCharsByPty = 0
     for (const accounting of rendererDeliveryAccountingByPty.values()) {
       maxRendererInFlightCharsByPty = Math.max(
@@ -1999,14 +1743,10 @@ export function registerPtyHandlers(
     recordPtyRendererDeliveryPressure()
   }
   resetRendererDeliveryAccountingForLifecycleReset = () => {
-    // Why: clearing pendingData is lossless — its bytes were only ever bound for
-    // the dead page, and the replacement page repaints each pane from main's
-    // authoritative sources (daemon snapshot / headless buffer / cold-restore),
-    // which are fed before the pendingData append so they always superset it.
+    // Why lossless: pendingData bytes were bound for the dead page; the replacement repaints from main's authoritative sources, which superset it.
     lastLifecycleResetClearedChars = rendererInFlightTotalChars
     rendererLifecycleResetCount += 1
-    // Why: pending bytes and outstanding credits belonged to the dead page.
-    // Release producer pauses before clearing them so no shell stays wedged.
+    // Why release before clearing: pending bytes and credits belonged to the dead page; releasing producer pauses first keeps no shell wedged.
     producerFlowControl.releaseAll()
     clearDeliveryResyncProbe()
     deliveryResyncUnansweredWarnLogged = false
@@ -2014,26 +1754,20 @@ export function registerPtyHandlers(
     rendererInFlightTotalChars = 0
     pendingData.clear()
     pendingOverflowMarkedPtys.clear()
-    // Why: the reloading page's pty:data listener is gone until it re-registers
-    // and re-sends the handshake; hold sends until then so the boot window can't
-    // re-pin the gate with bytes dropped into a listener-less page.
+    // Why hold sends: the reloading page's pty:data listener is gone until it re-registers/handshakes, so bytes would drop into a listener-less page and re-pin the gate.
     rendererPtyDispatcherReady = false
-    // Why: arm the self-heal watchdog so a never-arriving handshake can't leave the
-    // gate held forever; the real handshake cancels it.
+    // Why: arm the self-heal watchdog so a never-arriving handshake can't hold the gate forever; the real handshake cancels it.
     armDispatcherReadyWatchdog()
     recordPtyRendererDeliveryPressure()
   }
-  // Why: let a later re-registration cancel this closure's watchdog (armed via a
-  // hoisted fn, so this bridge assignment can precede its definition).
+  // Why the bridge: let a later re-registration cancel this closure's watchdog (armed via a hoisted fn, so this assignment can precede its definition).
   clearRendererDispatcherReadyWatchdog = clearDispatcherReadyWatchdog
 
   function isLikelyInteractiveRedraw(data: string): boolean {
     if (data.length <= INTERACTIVE_OUTPUT_MAX_CHARS) {
       return true
     }
-    // Why: Codex-style TUIs can repaint more than 1 KB per keypress. ANSI
-    // control redraws are still latency-sensitive, while plain command output
-    // should stay on the throughput batch path.
+    // Why the ANSI check: Codex-style TUIs repaint >1 KB per keypress (latency-sensitive), while plain command output should stay on the throughput batch path.
     return data.length <= INTERACTIVE_REDRAW_MAX_CHARS && data.includes('\x1b[')
   }
 
@@ -2088,19 +1822,14 @@ export function registerPtyHandlers(
     const totalLimit =
       PTY_RENDERER_TOTAL_IN_FLIGHT_HIGH_WATER_CHARS +
       (options.interactive === true ? PTY_RENDERER_INTERACTIVE_RESERVE_CHARS : 0)
-    // Why: the reserve is per active PTY, not global; one active pane should
-    // stay responsive without letting every background pane burst past the cap.
+    // Why per-PTY (not global) reserve: keep one active pane responsive without letting every background pane burst past the cap.
     const ptyLimit =
       PTY_RENDERER_IN_FLIGHT_HIGH_WATER_CHARS +
       (options.interactive === true ? PTY_RENDERER_ACTIVE_PTY_IN_FLIGHT_RESERVE_CHARS : 0)
     return getRendererInFlightCharsForPty(id) < ptyLimit && rendererInFlightTotalChars < totalLimit
   }
 
-  // Why: max-merge on cumulative totals is idempotent and reorder-tolerant —
-  // a replayed or out-of-order ACK can never double-credit, and a lost ACK
-  // self-heals when any later ACK reports the full processed count. Returns
-  // the newly acknowledged delta so provider (SSH/daemon) backpressure is only
-  // credited for bytes main actually tracked in flight, never negative.
+  // Why max-merge cumulative totals: idempotent and reorder-tolerant — replayed/out-of-order ACKs can't double-credit and a lost ACK self-heals. Returns the newly acknowledged delta.
   function applyCumulativeAck(id: string, processedChars: number): number {
     const accounting = rendererDeliveryAccountingByPty.get(id)
     if (!accounting) {
@@ -2128,10 +1857,7 @@ export function registerPtyHandlers(
     }
   }
 
-  // Why: event-triggered verified-state recovery. Data arriving for a fully
-  // gated PTY is the deterministic signal that delivery may be stuck on lost
-  // ACKs (e.g. dropped across a system suspend); ask the renderer for its
-  // authoritative processed totals instead of resetting on a wall-clock guess.
+  // Why: data for a fully gated PTY signals delivery may be stuck on lost ACKs (e.g. dropped across suspend); ask the renderer for authoritative totals instead of a wall-clock guess.
   function requestDeliveryResyncForGatedPty(): void {
     if (deliveryResyncOutstandingRequestId !== null || mainWindow.isDestroyed()) {
       return
@@ -2144,9 +1870,7 @@ export function registerPtyHandlers(
         return
       }
       clearDeliveryResyncProbe()
-      // Why: no state mutation on timeout — a renderer that cannot answer has
-      // dead IPC, and only a reload cures that. Log once per silent streak so
-      // field diagnosis is captured without spamming every probe cycle.
+      // Why no mutation on timeout: unanswered means dead IPC that only a reload cures; log once per silent streak to avoid spamming every probe.
       if (deliveryResyncUnansweredWarnLogged) {
         return
       }
@@ -2160,11 +1884,7 @@ export function registerPtyHandlers(
     mainWindow.webContents.send('pty:requestDeliveryResync', { requestId })
   }
 
-  // Why: bytes sent but never counted received by the renderer after a
-  // confirmed wedge are gone — no ACK message can ever repay them (unlike a
-  // lost ACK, which any later cumulative total heals). Write the debt off and
-  // hand back restore markers so panes repaint from the main-owned snapshot;
-  // the caller routes them locally because push markers cannot arrive.
+  // Why write off: bytes sent but never received after a confirmed wedge are gone (no ACK can repay them); hand back restore markers so panes repaint from the snapshot.
   function writeOffLostRendererDelivery(
     report: PtyRendererDeliveryStateReport
   ): PtyDeliveryWriteOff[] {
@@ -2176,8 +1896,7 @@ export function registerPtyHandlers(
       const received = report.receivedCharsByPty?.[id]
       const receivedChars =
         typeof received === 'number' && Number.isFinite(received) ? Math.max(0, received) : 0
-      // Why skip a parse-pending window: received-but-unparsed bytes sit alive
-      // in the renderer write queue; their deferred ACK still repays this debt.
+      // Why skip: received-but-unparsed bytes are alive in the renderer write queue; their deferred ACK still repays this debt.
       if (receivedChars > accounting.ackedChars) {
         continue
       }
@@ -2186,9 +1905,7 @@ export function registerPtyHandlers(
         continue
       }
       tryGetProviderForPty(id)?.acknowledgeDataEvent(id, acknowledged)
-      // Why drop pending: everything at or before markerSeq comes from the
-      // snapshot (hidden-drop parity); flushing pre-marker bytes afterward
-      // would double-paint what the restore already covers.
+      // Why drop pending: everything at/before markerSeq comes from the snapshot, so flushing pre-marker bytes would double-paint the restore.
       const pending = pendingData.get(id)
       if (pending) {
         pendingDroppedChars += pending.data.length
@@ -2266,11 +1983,7 @@ export function registerPtyHandlers(
     deliveredHiddenRendererResizeOutputPtys.delete(id)
   }
 
-  // Why: when main drops renderer delivery (hidden gate / pending cap), an
-  // explicit out-of-band pty:modelRestoreNeeded signal tells the renderer to
-  // latch model-restore-needed. It must NOT ride pty:data: an in-band empty
-  // chunk is indistinguishable from a chunk fully consumed by renderer-side
-  // OSC-9999 stripping, which spuriously restored visible panes.
+  // Why out-of-band (not pty:data): an in-band empty chunk is indistinguishable from one fully consumed by renderer-side OSC-9999 stripping, which spuriously restored visible panes.
   function sendModelRestoreNeededMarker(
     id: string,
     reason: PtyModelRestoreReason,
@@ -2302,16 +2015,10 @@ export function registerPtyHandlers(
 
   const pendingDataDropWarnedPtys = new Set<string>()
 
-  // Why capped: the drop path guarantees O(1) memory per PTY; salvaged query
-  // bytes are tiny (a DSR probe is 4 chars) and anything past the cap means a
-  // pathological stream, where degrading to the plain sentinel is fine.
+  // Why capped: keeps O(1) memory per PTY; salvaged query bytes are tiny, so past the cap a pathological stream can degrade to the plain sentinel.
   const DROPPED_QUERY_SALVAGE_MAX_CHARS = 4096
 
-  // Why: a bulk drop must not swallow reply-eliciting queries embedded in the
-  // flood (DSR 6n / CPR, DA1/DA2, DECRQM, OSC 10/11 probes). The program that
-  // wrote them blocks on the reply (the bench DSR timeout). Carve just the
-  // query bytes out and let them ride the droppedOutput sentinel — content is
-  // healed by the snapshot restore, so replies cannot double-fire.
+  // Why carve out queries: a bulk drop must not swallow reply-eliciting probes (DSR/CPR, DA1/DA2, DECRQM, OSC 10/11) the program blocks on; snapshot heals content so replies can't double-fire.
   function extractDroppedPtyQueryBytes(data: string): string {
     if (!data.includes('\x1b')) {
       return ''
@@ -2330,28 +2037,19 @@ export function registerPtyHandlers(
       console.error(
         `[pty] dropped ${pending.data.length} buffered chars for ${id}: renderer not receiving and per-PTY pending cap exceeded; pane will restore from the main-owned snapshot`
       )
-      // Why: field visibility for cap tuning — drop frequency and size decide
-      // whether the cap is too small (issue #2836 / #7017). No pty id: session
-      // ids can embed workspace paths.
+      // Why: field visibility for cap tuning (issue #2836 / #7017); no pty id since session ids can embed workspace paths.
       recordCrashBreadcrumb('terminal_pending_output_dropped', {
         droppedChars: pending.data.length,
         capChars
       })
     }
-    // Why: with the hidden-delivery gate rolled out, the model snapshot can
-    // recover the dropped middle — emit the out-of-band restore marker once
-    // per overflow episode alongside the droppedOutput sentinel so a fresh
-    // or reloaded view latches restore too.
+    // Why the marker: the snapshot can recover the dropped middle; emit it once per overflow episode so a fresh or reloaded view latches restore too.
     if (isHiddenPtyDeliveryGateEnabled(getSettings?.()) && !pendingOverflowMarkedPtys.has(id)) {
       pendingOverflowMarkedPtys.add(id)
       sendModelRestoreNeededMarker(id, 'pending-cap', runtime?.getPtyOutputSequence(id))
     }
     pendingDroppedChars += pending.data.length
-    // Why no trimmed content tail: a mid-stream gap would silently corrupt
-    // the pane. The droppedOutput sentinel routes the pane through
-    // hidden-output restore, which repaints from the authoritative main-owned
-    // buffer and realigns with the live stream by sequence. Only carved-out
-    // query bytes ride along so their replies survive the drop.
+    // Why no trimmed content tail: a mid-stream gap would corrupt the pane; the droppedOutput sentinel repaints from the snapshot and realigns by sequence (only query bytes ride along).
     return {
       data: extractDroppedPtyQueryBytes(pending.data).slice(0, DROPPED_QUERY_SALVAGE_MAX_CHARS),
       droppedOutput: true
@@ -2368,10 +2066,7 @@ export function registerPtyHandlers(
     rawLength = data.length,
     transformed = false
   ): PendingPtyData {
-    // Why: once over the cap, stay dropped at O(1) memory until the renderer
-    // can receive again — the restore sentinel supersedes any interim bytes.
-    // Queries arriving while latched still get carved out (bounded) so their
-    // replies survive the whole drop episode, not just the first burst.
+    // Why stay dropped at O(1): once over the cap the restore sentinel supersedes interim bytes; queries still get carved out (bounded) so replies survive the whole episode.
     if (existing?.droppedOutput === true) {
       if (existing.data.length >= DROPPED_QUERY_SALVAGE_MAX_CHARS) {
         return existing
@@ -2423,10 +2118,7 @@ export function registerPtyHandlers(
     if (mainWindow.isDestroyed()) {
       return
     }
-    // Why: one-shot self-heal — if the reloaded page never signals ready, force the
-    // gate open so a dropped handshake degrades to pre-handshake behavior (bounded
-    // duplicate/overwrite at worst) instead of a permanent hold. Unref'd so it can
-    // never keep the process alive.
+    // Why: one-shot self-heal — force the gate open if the reloaded page never signals ready, so a dropped handshake can't hold it forever. Unref'd so it can't keep the process alive.
     dispatcherReadyWatchdogTimer = setTimeout(() => {
       dispatcherReadyWatchdogTimer = null
       if (rendererPtyDispatcherReady || mainWindow.isDestroyed()) {
@@ -2442,8 +2134,7 @@ export function registerPtyHandlers(
   function flushPendingData(): void {
     flushTimer = null
     if (mainWindow.isDestroyed()) {
-      // Why: the bookkeeping is being wiped, so no future drain can ever
-      // resume these producers — release them now or local shells wedge.
+      // Why release now: bookkeeping is being wiped, so no future drain can resume these producers — local shells would wedge.
       producerFlowControl.releaseAll()
       clearDeliveryResyncProbe()
       pendingData.clear()
@@ -2454,9 +2145,7 @@ export function registerPtyHandlers(
       recordPtyRendererDeliveryPressure()
       return
     }
-    // Why: hold sends until the page's pty:data listener is registered. Bytes
-    // keep accruing in pendingData (2 MB cap + droppedBacklog rebuild it
-    // losslessly); the ready handshake reschedules this flush.
+    // Why hold: the page's pty:data listener isn't registered yet; bytes accrue in pendingData (rebuilt losslessly) and the ready handshake reschedules this flush.
     if (!rendererPtyDispatcherReady) {
       return
     }
@@ -2466,8 +2155,7 @@ export function registerPtyHandlers(
       if (writes >= PTY_BATCH_FLUSH_MAX_WRITES) {
         break
       }
-      // Why: hidden-gated bytes are dropped, never re-queued — the model
-      // already ingested them; reveal restores from the snapshot+seq machinery.
+      // Why drop, never re-queue: the model already ingested hidden-gated bytes; reveal restores from the snapshot+seq machinery.
       if (shouldDropHiddenRendererPtyData(id, settings)) {
         pendingData.delete(id)
         pendingOverflowMarkedPtys.delete(id)
@@ -2485,10 +2173,7 @@ export function registerPtyHandlers(
       pendingData.delete(id)
       if (pending.droppedOutput === true) {
         updateProducerFlowControl(id)
-        // Why: the buffered bytes were dropped at the pending cap; tell the
-        // renderer so the pane repaints from the main-owned buffer snapshot
-        // instead of continuing a stream with a silent gap. data carries only
-        // the carved-out query bytes (see extractDroppedPtyQueryBytes).
+        // Why droppedOutput sentinel: pending-cap drop means the pane must repaint from the snapshot, not continue a gapped stream (data = carved query bytes only).
         sendPtyDataToRenderer(id, { id, data: pending.data, droppedOutput: true })
         writes++
         continue
@@ -2528,8 +2213,7 @@ export function registerPtyHandlers(
     }
     recordPtyRendererDeliveryPressure()
     if (pendingData.size > 0 && writes > 0) {
-      // Why: a background terminal can dump megabytes at once. Yield between
-      // small IPC slices so keystroke writes are not stuck behind one flush.
+      // Why yield between slices: a background terminal can dump megabytes at once, and keystroke writes must not stall behind one flush.
       schedulePendingDataFlush(PTY_BATCH_DRAIN_CONTINUE_MS)
     }
   }
@@ -2549,8 +2233,7 @@ export function registerPtyHandlers(
     if (existing) {
       clearTimeout(existing)
     }
-    // Why: some providers can report the real exit after kill has already
-    // completed; skip only that late duplicate, not a future reused id forever.
+    // Why a timed window: providers may report the real exit after kill completes; skip only that late duplicate, not a future reused id forever.
     const cleanupTimer = setTimeout(() => {
       syntheticKillExitPtyIds.delete(id)
     }, SYNTHETIC_KILL_EXIT_DUPLICATE_WINDOW_MS)
@@ -2572,14 +2255,11 @@ export function registerPtyHandlers(
     if (mainWindow.isDestroyed()) {
       return
     }
-    // Why: flush any batched data for this PTY before sending the exit event,
-    // otherwise the last <=8ms of output is silently lost because the renderer
-    // tears down the terminal on pty:exit before the batch timer fires.
+    // Why flush before exit: the renderer tears down the terminal on pty:exit, so any batched output not yet flushed would be silently lost.
     const remaining = pendingData.get(payload.id)
     if (remaining) {
       if (remaining.droppedOutput === true) {
-        // Sentinel entry: only salvaged query bytes remain; keep the flag so
-        // the renderer knows the span was dropped (same as the flush loop).
+        // Sentinel entry: only salvaged query bytes remain; keep the flag so the renderer knows the span was dropped.
         sendPtyDataToRenderer(payload.id, {
           id: payload.id,
           data: remaining.data,
@@ -2600,8 +2280,7 @@ export function registerPtyHandlers(
       }
       pendingData.delete(payload.id)
     }
-    // Why: exit drops this PTY's bookkeeping; resume (no-op on a dead PTY)
-    // rather than leave a stale paused mark behind for a reused id.
+    // Why resume a dead PTY (no-op): avoid leaving a stale paused mark behind for a reused id.
     producerFlowControl.release(payload.id)
     pendingOverflowMarkedPtys.delete(payload.id)
     lastInputAtByPty.delete(payload.id)
@@ -2610,8 +2289,7 @@ export function registerPtyHandlers(
       0,
       rendererInFlightTotalChars - getRendererInFlightCharsForPty(payload.id)
     )
-    // Why: the renderer also drops its cumulative total on pty:exit, so a
-    // reused id restarts aligned at zero on both sides.
+    // Why: the renderer also drops its cumulative total on pty:exit, so a reused id restarts aligned at zero on both sides.
     rendererDeliveryAccountingByPty.delete(payload.id)
     recordPtyRendererDeliveryPressure()
     mainWindow.webContents.send('pty:exit', payload)
@@ -2636,20 +2314,13 @@ export function registerPtyHandlers(
     return providerExitObserved
   }
 
-  // Why: extracted so the "Restart daemon" flow can rebind against the fresh
-  // adapter after replaceDaemonProvider runs. Both the startup registration
-  // and the post-restart rebind go through the same code path — no risk of
-  // drift between the two entry points.
+  // Why extracted: the "Restart daemon" flow rebinds against the fresh adapter after replaceDaemonProvider, sharing this code path with startup registration.
   const bindProviderListeners = (): void => {
     localDataUnsub?.()
     localExitUnsub?.()
     localBackgroundStreamUnsub?.()
 
-    // Keep-tail thinning facts from the daemon, in byte order with onData.
-    // The marker flips scan authority for the four transient-fact scanners;
-    // a gap resets main's cross-chunk parse state and forces the renderer to
-    // restore from the model snapshot (same seq-guard path as hidden drops)
-    // in case any view — eager buffer included — was receiving bytes.
+    // Daemon keep-tail thinning facts, in byte order with onData: markers flip transient-fact scan authority; a gap forces renderer restore from the snapshot.
     localBackgroundStreamUnsub =
       localProvider.onBackgroundStreamEvent?.((payload) => {
         if (payload.kind === 'backgroundMarker') {
@@ -2673,12 +2344,7 @@ export function registerPtyHandlers(
         runtime?.emitDaemonPtyTransientFact(payload.id, payload.fact)
       }) ?? null
 
-    // Why: LocalPtyProvider routes data to the runtime via configure().onData,
-    // but daemon-backed providers don't have configure(). Without this, daemon
-    // PTY data never reaches the runtime's tail buffer, so terminal.read returns
-    // empty and agent-detection from raw data never fires. Runtime tails also
-    // power mobile read/stream, so they must be notified regardless of window
-    // state.
+    // Why: daemon providers lack configure().onData, so feed the runtime here or their tail buffer (terminal.read, agent-detection, mobile stream) stays empty.
     const isLocalProvider = localProvider instanceof LocalPtyProvider
 
     localDataUnsub = localProvider.onData((payload) => {
@@ -2691,9 +2357,7 @@ export function registerPtyHandlers(
       const startSeq =
         typeof outputSeq === 'number' ? Math.max(0, outputSeq - rawLength) : undefined
       if (mainWindow.isDestroyed()) {
-        // Why: clear the pending flush timer so it doesn't fire after the window
-        // is gone. Without this, macOS app re-activation leaks orphaned timers
-        // from the previous window's registration.
+        // Why clear the flush timer: macOS app re-activation otherwise leaks orphaned timers from the previous window's registration.
         if (flushTimer) {
           clearTimeout(flushTimer)
           flushTimer = null
@@ -2709,11 +2373,7 @@ export function registerPtyHandlers(
         return
       }
       const settings = getSettings?.()
-      // Why: hidden-delivery gate — runtime ingestion above already consumed
-      // the chunk; gated renderer delivery is DROPPED (never queued) and the
-      // reveal path restores from the model snapshot via the seq guard. The
-      // drop sits before the interactive bypass so gated PTYs take neither
-      // the immediate nor the batched renderer path.
+      // Why drop before the interactive bypass: runtime already ingested the chunk, so gated PTYs skip both renderer paths and reveal restores from the snapshot.
       if (shouldDropHiddenRendererPtyData(payload.id, settings)) {
         const drop = recordHiddenRendererPtyDataDrop(payload.id, payload.data.length)
         warnIfDroppingHiddenBytesForVisiblePty(payload.id, payload.data.length)
@@ -2747,13 +2407,9 @@ export function registerPtyHandlers(
         nextData,
         performance.now()
       )
-      // Why: gate the interactive fast path on the dispatcher handshake too, so
-      // boot-window keystroke echo accrues in pendingData instead of being sent
-      // into a listener-less page and pinning the gate.
+      // Why gate the fast path on the handshake too: else boot-window keystroke echo is sent into a listener-less page and pins the gate.
       if (isInteractiveOutput && rendererPtyDispatcherReady) {
-        // Why: user-input echo should not be pinned behind unrelated bulk
-        // terminal output already handed to the renderer. The reserve is
-        // bounded, and the per-PTY cap still prevents an active TUI runaway.
+        // Why the reserve: keep input echo from being pinned behind unrelated bulk output; it's bounded and the per-PTY cap still prevents an active TUI runaway.
         if (!canSendPtyDataToRenderer(payload.id, { interactive: true })) {
           requestDeliveryResyncForGatedPty()
           pendingData.set(payload.id, pending)
@@ -2765,8 +2421,7 @@ export function registerPtyHandlers(
         updateProducerFlowControl(payload.id)
         pendingOverflowMarkedPtys.delete(payload.id)
         clearFlushTimerIfIdle()
-        // Why: agent TUIs redraw small prompt regions after every keystroke.
-        // Waiting for the throughput batch timer adds visible input latency.
+        // Why immediate: agent TUIs redraw small prompt regions per keystroke; the throughput batch timer would add visible input latency.
         sendPtyDataToRenderer(payload.id, {
           id: payload.id,
           data: nextData,
@@ -2785,8 +2440,7 @@ export function registerPtyHandlers(
       pendingData.set(payload.id, pending)
       updateProducerFlowControl(payload.id)
       recordPtyRendererDeliveryPressure()
-      // Why: probe on data arrival, not on flush skips — new output for a
-      // fully gated PTY is the moment stuck delivery becomes observable.
+      // Why probe on data arrival (not flush skips): new output for a fully gated PTY is the moment stuck delivery becomes observable.
       if (
         !canSendPtyDataToRenderer(payload.id, { interactive: activeRendererPtys.has(payload.id) })
       ) {
@@ -2813,11 +2467,7 @@ export function registerPtyHandlers(
   bindProviderListeners()
   rebindProviderListeners = bindProviderListeners
 
-  // Why: a persistent ipcMain listener with a request-ID dispatch table
-  // (instead of one listener per call) so concurrent serialize requests do
-  // not stack listeners and trip Node's MaxListeners=10 warning. Many
-  // sleeping PTYs waking at once (e.g. on relaunch) routinely fan out 10+
-  // concurrent calls.
+  // Why: one persistent listener with a request-ID dispatch table instead of one per call, so concurrent serialize requests don't trip Node's MaxListeners=10 warning.
   type SerializeResult = {
     data: string
     cols: number
@@ -2915,18 +2565,11 @@ export function registerPtyHandlers(
     })
   }
 
-  // Why: a reload (did-finish-load) or renderer crash replaces the process
-  // that owned every delivery-interest hold and hidden mark; surviving
-  // daemon/SSH PTYs would otherwise stay force-fed (leaked interest defeats
-  // the gate) or stay gated against a renderer that never marked them. Drop
-  // memory is preserved — each pane's first sync re-marks/unmarks and the
-  // unmark path re-emits the restore marker for unrestored drops.
+  // Why: reload/crash orphans delivery-interest holds and hidden marks; reset so surviving PTYs aren't stuck force-fed or gated — each pane's first sync re-marks.
   clearRendererGateResetHandlers()
   rendererGateResetLoadHandler = () => {
     resetRendererScopedHiddenPtyDeliveryState()
-    // Why: the daemon pacer must not keep throttling ptys whose hidden marks
-    // died with the renderer; the fresh renderer's first visibility sync
-    // re-marks the ones that are still hidden.
+    // Why: the daemon pacer must not keep throttling ptys whose hidden marks died with the renderer; the fresh renderer's sync re-marks the still-hidden ones.
     resyncBackgroundedDeliveriesAfterGateReset()
   }
   rendererGateResetGoneHandler = () => {
@@ -2937,25 +2580,17 @@ export function registerPtyHandlers(
   mainWindow.webContents.on('did-finish-load', rendererGateResetLoadHandler)
   mainWindow.webContents.on('render-process-gone', rendererGateResetGoneHandler)
 
-  // Kill orphaned PTY processes from previous page loads when the renderer reloads.
-  // Why: only applies to LocalPtyProvider where PTYs live in the Electron main
-  // process and can become orphaned on page reload. Daemon-backed sessions
-  // survive renderer restarts by design — orphan cleanup would kill them.
+  // Why: only LocalPtyProvider PTYs (main-process) can be orphaned on reload; daemon sessions survive by design and cleanup would kill them.
   clearDidFinishLoadHandler()
   if (localProvider instanceof LocalPtyProvider) {
     const lp = localProvider
     didFinishLoadHandler = () => {
-      // Why: always advance so the load generation stays monotonic, but skip the
-      // sweep (and its per-PTY cleanup) on the crash/freeze-recovery reload — it
-      // would kill live LOCAL PTYs across the single window before session
-      // restore re-attaches them (#5787). The getter consumes the flag, so the
-      // next genuine reload still reclaims genuinely-orphaned PTYs.
+      // Why: always advance to keep the generation monotonic, but skip the sweep on crash/freeze-recovery reload — it would kill live local PTYs before session restore (#5787).
       const generation = lp.advanceGeneration()
       if (options?.isRecoveryReloadInFlight?.(mainWindow.webContents.id)) {
         return
       }
-      // Why: the retained provider onExit callback is the only physical-exit
-      // proof; it clears ownership and notifies runtime after the OS reaps it.
+      // Why: the retained provider onExit callback is the only physical-exit proof; it clears ownership after the OS reaps it.
       lp.killOrphanedPtys(generation - 1)
     }
     didFinishLoadWebContents = mainWindow.webContents
@@ -2991,9 +2626,7 @@ export function registerPtyHandlers(
     })
 
   const localStartupCwdDirectoryExists = (path: string): boolean => {
-    // Why: Win32 statSync on \\wsl.localhost 9P shares can falsely report
-    // ENOENT for directories that exist on the Linux side; never fall back on
-    // that signal — the provider's WSL-aware validation decides instead.
+    // Why: Win32 statSync on \\wsl.localhost 9P shares can falsely report ENOENT; defer to the provider's WSL-aware validation.
     if (isWslUncPath(path)) {
       return true
     }
@@ -3004,9 +2637,7 @@ export function registerPtyHandlers(
     }
   }
 
-  // Why: the runtime controller must route through getProviderForPty() so that
-  // CLI commands (terminal.send, terminal.stop) work for both local and remote PTYs.
-  // Hardcoding localProvider.getPtyProcess() would silently fail for remote PTYs.
+  // Why: route through getProviderForPty() so CLI commands work for remote PTYs too; localProvider would silently fail for them.
   runtime?.setPtyController({
     spawn: async (args) => {
       const startupPromise = getLocalPtyStartupPromise(args.connectionId)
@@ -3020,8 +2651,7 @@ export function registerPtyHandlers(
       if (isClaudeLaunch && isClaudeAuthSwitchInProgress()) {
         throw new Error('A Claude account switch is in progress. Try again after it finishes.')
       }
-      // Why: runtime-created terminals do not carry renderer-computed
-      // projectRuntime, so resolve from worktreeId to honor project Windows runtime.
+      // Why: runtime-created terminals carry no renderer-computed projectRuntime; resolve from worktreeId to honor the project's Windows runtime.
       const terminalRuntimeOptions =
         process.platform === 'win32' && !args.connectionId
           ? resolveLocalWindowsTerminalRuntimeOptions({
@@ -3297,9 +2927,7 @@ export function registerPtyHandlers(
           }
         }
         ptyOwnership.set(result.id, args.connectionId ?? null)
-        // Why: Phase-5 ConPTY DA1 — record the native-Windows-local-PTY
-        // determination from the spawn record before any byte reaches the
-        // runtime emulator, so its DA1 override exists from byte zero.
+        // Why: record the native-Windows-local-PTY determination before any byte reaches the emulator, so its ConPTY DA1 override exists from byte zero.
         if (
           isNativeWindowsLocalPtySpawn({
             connectionId: args.connectionId,
@@ -3314,8 +2942,7 @@ export function registerPtyHandlers(
           if (!store || !args.connectionId) {
             return
           }
-          // Why: workspace-session bindings keep app-facing PTY ids for hydration,
-          // while SSH leases keep relay ids for remote lease reconciliation.
+          // Why: SSH leases keep relay ids for remote reconciliation, while session bindings keep app-facing ids for hydration.
           store.upsertSshRemotePtyLease({
             targetId: args.connectionId,
             ptyId: relayResultId,
@@ -3367,9 +2994,7 @@ export function registerPtyHandlers(
             result.id,
             args.worktreeId,
             args.connectionId ?? null,
-            // Why: thread the validated pane identity so main can back a pending
-            // mobile create from this live spawn even if graph-sync stalls (#7587).
-            // Bound tabId like the sibling metadataPaneKey/spawnOptions.tabId here.
+            // Why: thread validated pane identity so main can back a pending mobile create even if graph-sync stalls (#7587).
             typeof args.tabId === 'string' &&
               isValidTerminalTabId(args.tabId) &&
               args.tabId.length <= 512 &&
@@ -3381,9 +3006,7 @@ export function registerPtyHandlers(
               : undefined
           )
         }
-        // Why: arms main's per-PTY Command Code output detector from the launch
-        // command (renderer startupCommand parity); banner detection covers
-        // PTYs spawned without one.
+        // Why: arms main's per-PTY Command Code output detector from the launch command (renderer startupCommand parity).
         runtime?.noteTerminalSpawnCommand?.(result.id, args.command ?? null)
         if (isClaudeLaunch) {
           markClaudePtySpawned(result.id)
@@ -3401,9 +3024,7 @@ export function registerPtyHandlers(
             })
           }
         }
-        // Why: runtime-owned CLI PTYs bypass the renderer `pty:spawn` handler,
-        // so record their spawn-time paneKey here too. Synthetic hook titles and
-        // paneKey-scoped cache cleanup both depend on this reverse lookup.
+        // Why: runtime-owned CLI PTYs bypass the renderer pty:spawn handler; record paneKey here too since hook titles and cache cleanup need this reverse lookup.
         const paneKey = rememberPaneKeyForPty(result.id, env?.ORCA_PANE_KEY)
         const pendingSerializer = paneKey ? pendingByPaneKey.get(paneKey) : undefined
         const inheritRendererReadiness =
@@ -3429,12 +3050,7 @@ export function registerPtyHandlers(
         const response = { id: result.id }
         return resolvePaneSpawnReservation(materializedPaneKey, paneSpawnReservation, response)
       } catch (err) {
-        // Why: once the reservation is created, any later throw — spawn
-        // failure, persist failure, or a post-spawn helper such as
-        // registerPty/rememberPaneKeyForPty/track — must settle it. Otherwise
-        // it lingers in paneSpawnReservationsByPaneKey and every future spawn
-        // for this pane awaits a promise that never resolves. reject is a
-        // no-op once the reservation has already resolved.
+        // Why: any later throw must settle the reservation, or it lingers and every future spawn for this pane awaits a promise that never resolves (reject no-ops if already resolved).
         rejectPaneSpawnReservation(materializedPaneKey, paneSpawnReservation, err)
         throw err
       } finally {
@@ -3460,9 +3076,7 @@ export function registerPtyHandlers(
           provider = connectionId ? getProvider(connectionId) : getProviderForPty(ptyId)
         } catch {
           if (connectionId) {
-            // Why: runtime/CLI close can target a detached SSH PTY after its
-            // provider was unregistered. Tombstone the lease so reconnect does
-            // not revive a terminal the user explicitly closed.
+            // Why: runtime/CLI close can target a detached SSH PTY after its provider was unregistered; tombstone the lease so reconnect can't revive it.
             finishPtyShutdown(ptyId, connectionId, store)
             runtime?.onPtyExit(ptyId, -1)
             rememberSyntheticKillExit(ptyId)
@@ -3471,8 +3085,7 @@ export function registerPtyHandlers(
           }
           return false
         }
-        // Why: the controller is synchronous, but ownership must remain until
-        // asynchronous shutdown proves whether the provider emitted an exit.
+        // Why: controller is synchronous, but keep ownership until async shutdown proves whether the provider emitted an exit.
         void shutdownProviderAndDetectExit(provider, ptyId, { immediate: false })
           .then((providerExitObserved) => {
             finishPtyShutdown(ptyId, connectionId, store)
@@ -3493,16 +3106,14 @@ export function registerPtyHandlers(
             console.warn(
               `[pty] Failed to stop PTY ${ptyId}: ${err instanceof Error ? err.message : String(err)}`
             )
-            // Why: close runtime tails without clearing provider ownership, so
-            // a retry can still target a PTY that survived the failed shutdown.
+            // Why: close runtime tails but keep provider ownership so a retry can still target a PTY that survived the failed shutdown.
             runtime?.onPtyExit(ptyId, -1)
           })
         return true
       }
       const startupPromise = getLocalPtyProviderStartupPromise(connectionId)
       if (startupPromise) {
-        // Why: provider selection must happen after the daemon swap; selecting
-        // the fallback first can report success while orphaning a daemon PTY.
+        // Why: select the provider after the daemon swap; the fallback first can report success while orphaning a daemon PTY.
         void startupPromise.then(killWithCurrentProvider).catch((err) => {
           console.warn(
             `[pty] Failed to stop PTY ${ptyId}: ${err instanceof Error ? err.message : String(err)}`
@@ -3549,8 +3160,7 @@ export function registerPtyHandlers(
         provider = connectionId ? getProvider(connectionId) : getProviderForPty(ptyId)
       } catch {
         if (connectionId) {
-          // Why: an absent SSH provider means there is no live target left to
-          // await, but the relay lease must still be tombstoned.
+          // Why: an absent SSH provider means no live target to await, but the relay lease must still be tombstoned.
           finishPtyShutdown(ptyId, connectionId, store)
           runtime?.onPtyExit(ptyId, -1)
           rememberSyntheticKillExit(ptyId)
@@ -3626,9 +3236,7 @@ export function registerPtyHandlers(
       }
     },
     clearBuffer: async (ptyId) => {
-      // Why: desktop xterm owns local scrollback, while daemon/SSH providers
-      // own their own retained buffers. Clear both surfaces so mobile
-      // resubscribe snapshots do not resurrect cleared history.
+      // Why: desktop xterm and daemon/SSH providers hold separate buffers; clear both so mobile resubscribe can't resurrect cleared history.
       mainWindow.webContents.send('pty:clearBuffer:request', { ptyId })
       try {
         await getProviderForPty(ptyId).clearBuffer(ptyId)
@@ -3644,25 +3252,19 @@ export function registerPtyHandlers(
       return providerSessions.flat()
     },
     serializeBuffer: (ptyId, opts) => {
-      // Why: mobile xterm must start from the desktop xterm's exact screen
-      // state and dimensions before live TUI chunks can render correctly.
+      // Why: mobile xterm must start from the desktop's exact screen state/dimensions before live TUI chunks render correctly.
       return requestSerializedBuffer(ptyId, opts)
     },
     serializeProviderBuffer: async (ptyId, opts) => {
       try {
-        // Why: restored daemon PTYs can be live while their desktop pane stays
-        // unmounted; query the provider model so phone-local navigation works.
+        // Why: restored daemon PTYs can be live while their desktop pane is unmounted; query the provider model so phone-local navigation works.
         return (await getProviderForPty(ptyId).getBufferSnapshot?.(ptyId, opts)) ?? null
       } catch {
         return null
       }
     },
     hasRendererSerializer: (ptyId) => {
-      // Why: the runtime needs a synchronous probe so it can decide whether to
-      // skip the daemon-snapshot seed (the renderer will hydrate it) or run the
-      // seed (no renderer authoritative for this PTY). A registry write happens
-      // when the renderer calls registerPtySerializer; we check via the same
-      // pendingByPaneKey + ptyId pairing that the cooperation gate uses.
+      // Why: a synchronous probe lets the runtime decide whether to skip the daemon-snapshot seed (renderer will hydrate) or run it (no renderer authoritative).
       return rendererSerializerReadiness.has(ptyId)
     },
     getRendererSerializerGeneration: (ptyId) => {
@@ -3722,8 +3324,7 @@ export function registerPtyHandlers(
               scrollbackRows
             })
           : null
-        // Why: after a data gap, main's model contains only the retained tail.
-        // Returning it as a full snapshot would silently erase older scrollback.
+        // Why: after a data gap main holds only the retained tail; returning it as a full snapshot would erase older scrollback.
         if (providerSnapshotRequired && !providerSnapshot) {
           return null
         }
@@ -3735,11 +3336,7 @@ export function registerPtyHandlers(
         if (!snapshot || typeof snapshot.seq !== 'number') {
           return snapshot
         }
-        // Why: sampled after serialize — every byte at or below snapshot.seq
-        // that can still reach the renderer sits in this pending queue. The
-        // renderer's post-restore dedupe bounds its duplicate window with it;
-        // without the bound a stale baseline silently swallows genuinely-new
-        // chunks whose seq domain sits below the snapshot counter.
+        // Why: the renderer's post-restore dedupe needs this pending-queue bound, or a stale baseline swallows new chunks whose seq sits below the snapshot counter.
         const pending = pendingData.get(args.id)
         if (pending && typeof pending.startSeq !== 'number') {
           // Why: a seq-less backlog cannot be bounded — stay conservative.
@@ -3758,10 +3355,7 @@ export function registerPtyHandlers(
     }
   )
 
-  // Why: with main holding side-effect authority the renderer no longer
-  // derives titles from replayed bytes on (re)attach. This title-only replay
-  // snapshot restores title state — never historical bells/completions (the
-  // no-attention-replay rule, terminal-side-effect-authority.md).
+  // Why: main owns side effects, so this replay restores title state only — never historical bells/completions (no-attention-replay rule, terminal-side-effect-authority.md).
   ipcMain.handle('pty:sideEffectSnapshot', (_event, args: { id: string }) => {
     if (!runtime || typeof args?.id !== 'string' || args.id.length === 0) {
       return null
@@ -3785,9 +3379,7 @@ export function registerPtyHandlers(
         cols: number
         rows: number
         cwd?: string
-        // Why: fresh local renderer spawns opt into recovering a saved cwd
-        // whose directory was deleted (#7239); reattach/remote callers must
-        // keep exact cwd semantics, so the flag alone is not sufficient.
+        // Why: fresh local spawns opt into recovering a saved cwd whose dir was deleted (#7239); reattach/remote need exact cwd, so the flag alone isn't sufficient.
         cwdFallback?: 'worktree'
         env?: Record<string, string>
         envToDelete?: string[]
@@ -3805,25 +3397,12 @@ export function registerPtyHandlers(
           foreground?: unknown
           background?: unknown
         }
-        // Why: hidden-at-spawn declaration (terminal-query-authority.md
-        // §races) — the renderer knows at spawn time that no visible view
-        // will consume this PTY's bytes, so main marks it hidden BEFORE the
-        // first byte and the gate + model responder own spawn-time queries.
+        // Why: hidden-at-spawn declaration (terminal-query-authority.md §races) — main marks hidden before byte zero so the gate owns spawn-time queries.
         initiallyHidden?: boolean
-        // Why: closes the SIGKILL race documented in INVESTIGATION.md by
-        // letting main patch + sync-flush the (worktreeId, tabId, leafId →
-        // ptyId) binding before pty:spawn returns. Only the renderer's
-        // user-typing-Ctrl+T daemon-host path threads these; mobile/runtime
-        // CLI/SSH spawns leave them undefined and the main-side guard
-        // short-circuits.
+        // Why: closes the SIGKILL race (INVESTIGATION.md) by letting main sync-flush the binding before pty:spawn returns; only the Ctrl+T daemon-host path threads these.
         tabId?: string
         leafId?: string
-        // Why: telemetry-plan.md§Agent launch semantics. The renderer
-        // threads what Orca was *asked* to launch through this field; main
-        // fires `agent_started` only after `provider.spawn` resolves. Loose
-        // typing on the IPC boundary because the main-side schema
-        // validator is the single enforcement point — `track()` will drop
-        // the event if any field is outside its closed enum.
+        // Why: renderer-threaded launch telemetry (telemetry-plan.md§Agent launch semantics); loosely typed because the main-side schema validator is the single enforcement point.
         telemetry?: {
           agent_kind?: unknown
           launch_source?: unknown
@@ -3837,9 +3416,7 @@ export function registerPtyHandlers(
         await startupPromise
       }
       await assertFolderWorkspacePtyPathUsable(args.worktreeId)
-      // Why: honor the fallback only for fresh local spawns even if a caller
-      // sends the flag — reattach must keep the session's exact cwd and
-      // remote/SSH paths cannot probe the local filesystem meaningfully.
+      // Why: honor the fallback only for fresh local spawns — reattach needs exact cwd and SSH can't probe the local filesystem.
       const allowMissingCwdFallback =
         !args.connectionId && !args.sessionId && args.cwdFallback === 'worktree'
       let didFallbackToWorkspaceRootCwd = false
@@ -3889,38 +3466,15 @@ export function registerPtyHandlers(
           'This Claude launch defines explicit Anthropic auth environment variables. Remove those overrides before using a managed Claude account.'
         )
       }
-      // Why: the daemon-backed provider replaces LocalPtyProvider and therefore
-      // never runs its buildSpawnEnv closure. We must assemble the same
-      // host-local env (OpenCode plugin, agent-hook server, Pi/OMP managed
-      // extensions, Codex home, dev CLI overrides, GitHub attribution shims)
-      // here so both spawn paths behave identically. buildPtyHostEnv is the
-      // shared helper that encapsulates the full set of injections and guards.
-      //
-      // Safety: skip the entire injection when a remote (SSH) connection is in
-      // play. Every injection here is either host-loopback (the agent-hook
-      // server binds 127.0.0.1, so shipping its token to an SSH host would
-      // leak a loopback secret for no functional benefit) or a path on the
-      // local filesystem (OpenCode plugin dir, Pi/OMP extension paths, Codex
-      // home, dev CLI bin, attribution shim dir) that would resolve to
-      // nothing — or something misleading — on the remote machine.
+      // Why: the daemon-backed provider skips LocalPtyProvider's buildSpawnEnv, so assemble the same host-local env here for parity.
+      // Safety: skip entirely for SSH — every injection is a loopback secret or a local path that leaks or misleads on the remote host.
       const isDaemonHostSpawn =
         !args.connectionId &&
         !(provider instanceof LocalPtyProvider) &&
         !routesFreshSpawnsToLocalProvider(provider)
-      // Why: daemon host-env setup needs a stable id BEFORE provider.spawn so
-      // provider hooks and legacy Pi overlay cleanup can run in buildPtyHostEnv.
-      // DaemonPtyAdapter.doSpawn mints an id the same way when sessionId is
-      // absent — lifting the mint here gives pty.ts the id up-front without
-      // changing daemon semantics (the daemon still honors opts.sessionId ?? mint()).
-      //
-      // Note: the sessionId is STABLE across daemon restarts by design —
-      // DaemonPtyAdapter.reconcileOnStartup reuses it so that users' live
-      // shells survive crashes. Do NOT "simplify" id allocation back to a
-      // fresh UUID per spawn; that would orphan reconnectable terminal state.
-      // Why: only state for ids we minted in THIS request should be cleared on
-      // spawn failure. If the caller supplied args.sessionId it may refer to
-      // an existing PTY whose state (OpenCode hooks, legacy Pi overlay cleanup,
-      // agent-hook pane caches) we must not clobber on a retry/attach failure.
+      // Why: daemon host-env setup needs a stable id BEFORE provider.spawn so buildPtyHostEnv hooks/Pi cleanup can run; daemon still honors opts.sessionId ?? mint().
+      // Note: sessionId is STABLE across daemon restarts by design — do NOT simplify to a fresh UUID per spawn; that orphans reconnectable state.
+      // Why: only clear ids minted in THIS request on failure — a caller-supplied args.sessionId may name an existing PTY we must not clobber.
       const isMintedSessionId = args.sessionId === undefined && isDaemonHostSpawn
       const effectiveSessionId =
         args.sessionId ?? (isDaemonHostSpawn ? mintPtySessionId(args.worktreeId) : undefined)
@@ -3941,9 +3495,7 @@ export function registerPtyHandlers(
           })?.distro ?? null)
         : null
       const startupTerminalColorQueryReplyColors = getStartupTerminalColorQueryReplyColors(args)
-      // Why: the renderer sets pane env for SSH too. Only forward it to the
-      // remote when the relay hook path is enabled; otherwise a newer relay
-      // could emit statuses this Orca build is not prepared to route.
+      // Why: forward pane env to SSH only when the relay hook path is enabled, or a newer relay could emit statuses this build can't route.
       const sshSourceEnv = stripRemotePaneEnvWhenHooksDisabled(args.connectionId, args.env)
       const baseEnvWithAuth = claudeAuth
         ? { ...sshSourceEnv, ...claudeAuth.envPatch }
@@ -3996,9 +3548,7 @@ export function registerPtyHandlers(
         ? runtime.createPreAllocatedTerminalHandle()
         : null
       if (shouldRefreshAgentTeamsEnv && preAllocatedHandle) {
-        // Why: native Agent Teams team ids/tokens are process-local. A sleeping
-        // record preserves the user's native launch shape, but the team env
-        // itself must be regenerated for the new leader PTY.
+        // Why: Agent Teams ids/tokens are process-local, so the team env must be regenerated for the new leader PTY.
         const prepared = await runtime.prepareClaudeAgentTeamsLeaderForHandle({
           handle: preAllocatedHandle,
           baseEnv: baseEnv ?? {}
@@ -4034,16 +3584,14 @@ export function registerPtyHandlers(
           delete baseEnv.ORCA_WORKTREE_ID
         }
       } else if (baseEnv) {
-        // Why: ORCA_PANE_KEY crosses into shells and hook registries. Only the
-        // key proven to match this spawn's tab+leaf may leave the IPC boundary.
+        // Why: ORCA_PANE_KEY crosses into shells/hook registries; only a key proven to match this spawn's tab+leaf may cross the IPC boundary.
         delete baseEnv.ORCA_PANE_KEY
         delete baseEnv.ORCA_TAB_ID
         delete baseEnv.ORCA_WORKTREE_ID
         delete baseEnv.ORCA_AGENT_LAUNCH_TOKEN
       }
       const validatedPaneKey = stablePaneKey
-      // Why: SSH can strip ORCA_PANE_KEY when remote hooks are disabled; the
-      // IPC tab/leaf metadata still names the pane and matches runtime fallback.
+      // Why: SSH can strip ORCA_PANE_KEY when remote hooks are off; IPC tab/leaf metadata still names the pane.
       const reservationPaneKey = metadataPaneKey ?? validatedPaneKey
       const validatedLeafId = verifiedLeafId ?? metadataLeafId
       let env: Record<string, string> | undefined = baseEnv
@@ -4070,21 +3618,15 @@ export function registerPtyHandlers(
         !selectedCodexHomePath
       if (isDaemonHostSpawn) {
         if (effectiveSessionId === undefined) {
-          // Should be unreachable: the expression above returns a string when
-          // isDaemonHostSpawn is true. Defense-in-depth in case future edits
-          // break this invariant.
+          // Should be unreachable: effectiveSessionId is a string when isDaemonHostSpawn; defense-in-depth.
           throw new Error('Invariant violation: daemon spawn without sessionId')
         }
         const sessionIdForEnv = effectiveSessionId
-        // Why: this id still reaches filesystem side-effects for provider
-        // hook state and stale pre-migration Pi overlay cleanup; reject
-        // traversal/path separators before a crafted IPC payload can escape
-        // the expected roots.
+        // Why: this id reaches filesystem paths; reject traversal/separators so a crafted IPC payload can't escape the expected roots.
         if (!isSafePtySessionId(sessionIdForEnv, app.getPath('userData'))) {
           throw new Error('Invalid PTY session id')
         }
-        // Why: clone before mutating so we don't leak injections back into
-        // args.env (which the renderer may reuse for other IPC calls).
+        // Why: clone before mutating so injections don't leak back into args.env (renderer may reuse it).
         env = { ...baseEnv }
         try {
           buildPtyHostEnv(sessionIdForEnv, env, {
@@ -4106,14 +3648,7 @@ export function registerPtyHandlers(
           })
           promoteAgentTeamsShimPath(env, requestedAgentTeamsPath)
         } catch (err) {
-          // Why: buildPtyHostEnv has filesystem side-effects (Pi/OMP managed
-          // extension installation). If it throws before we reach provider.spawn,
-          // clear per-PTY state so the next attempt starts clean.
-          //
-          // Only sweep state for ids we MINTED in this request — caller-
-          // supplied ids may refer to existing PTYs whose overlay/hook state
-          // must not be clobbered by a transient overlay-mkdir failure on a
-          // retry/attach path.
+          // Why: buildPtyHostEnv has fs side-effects (Pi/OMP install); clear per-PTY state on throw, but only minted ids — caller ids may name existing PTYs.
           if (isMintedSessionId) {
             clearProviderPtyState(sessionIdForEnv)
           }
@@ -4173,13 +3708,7 @@ export function registerPtyHandlers(
       if (effectiveSessionId !== undefined) {
         spawnOptions.sessionId = effectiveSessionId
       }
-      // Why: on Windows, fall back to the persisted default-shell setting
-      // when the renderer didn't send a per-tab override. Without this, the
-      // daemon path ignores the user's "Default Shell" preference entirely —
-      // it just calls resolvePtyShellPath(env) which reads COMSPEC (cmd.exe)
-      // or falls back to PowerShell. The LocalPtyProvider already consults
-      // getWindowsShell(); this mirrors that on the daemon path so users who
-      // set WSL as default actually get WSL when pressing Ctrl+T.
+      // Why: without this, the Windows daemon path ignores the user's Default Shell preference (LocalPtyProvider already honors it via getWindowsShell()).
       if (effectiveShellOverride !== undefined) {
         spawnOptions.shellOverride = effectiveShellOverride
       }
@@ -4188,19 +3717,14 @@ export function registerPtyHandlers(
       const sessionSizeBeforeAttach =
         effectiveSessionAppId !== undefined ? ptySizes.get(effectiveSessionAppId) : undefined
       if (effectiveSessionId !== undefined) {
-        // Why: daemon PTYs can emit prompt/startup bytes before spawn()
-        // resolves. Runtime headless snapshots need the real pane geometry
-        // for those early bytes; otherwise they default to 80x24 and wrap TUIs.
+        // Why: daemon PTYs can emit before spawn() resolves; set real geometry now or early bytes default to 80x24 and wrap TUIs.
         ptySizes.set(effectiveSessionAppId ?? effectiveSessionId, {
           cols: args.cols,
           rows: args.rows
         })
       }
       if (process.platform === 'win32' && !args.connectionId) {
-        // Why: the renderer only models PowerShell as one shell family. Thread
-        // the persisted implementation choice through spawnOptions so both the
-        // in-process and daemon-backed PTY paths can resolve the same effective
-        // executable without inventing a fourth top-level shell.
+        // Why: the renderer models PowerShell as one shell family; thread the implementation choice so both PTY paths resolve the same executable.
         spawnOptions.terminalWindowsWslDistro =
           terminalRuntimeOptions.terminalWindowsWslDistro ?? null
         spawnOptions.terminalWindowsPowerShellImplementation = getSettings
@@ -4229,12 +3753,7 @@ export function registerPtyHandlers(
       )
       const paneSpawnReservation = reservationPaneKey ? reservePaneSpawn(reservationPaneKey) : null
       const initiallyHidden = args.initiallyHidden === true
-      // Why pre-spawn for daemon-host sessions (id minted up front): daemon
-      // PTYs can emit prompt bytes before spawn() resolves, and the hidden
-      // mark must beat the first byte so the gate + model responder own
-      // spawn-time queries (terminal-query-authority.md §races). Other
-      // providers cannot emit until spawn resolves; the post-spawn mark
-      // below is byte-zero-safe for them.
+      // Why: daemon PTYs can emit before spawn() resolves, so the hidden mark must beat byte zero (terminal-query-authority.md §races); other providers are safe with the post-spawn mark below.
       const preSpawnHiddenMarkId =
         initiallyHidden && isDaemonHostSpawn && effectiveSessionAppId !== undefined
           ? effectiveSessionAppId
@@ -4284,8 +3803,7 @@ export function registerPtyHandlers(
               resetIncarnation: true
             })
           }
-          // Why: a failed spawn must not leave a stale hidden mark on a session
-          // id a later visible attach may reuse.
+          // Why: a stale hidden mark on this session id would gate a later visible attach that reuses it.
           if (preSpawnHiddenMarkId !== null) {
             unmarkHiddenRendererPty(preSpawnHiddenMarkId)
           }
@@ -4306,9 +3824,7 @@ export function registerPtyHandlers(
             (spawnError.message.includes(SSH_SESSION_EXPIRED_ERROR) ||
               rawMessage.includes(SSH_SESSION_EXPIRED_ERROR))
           ) {
-            // Why: expired remote reattach means the relay has already dropped
-            // the backing PTY. Clear the durable lease so later session writes
-            // cannot restore the stale pane binding.
+            // Why: expired remote reattach = relay already dropped the PTY; clear the lease so writes can't restore the stale binding.
             if (effectiveSessionAppId !== undefined && !isIdentityMismatch) {
               clearProviderPtyState(effectiveSessionAppId)
               deletePtyOwnership(effectiveSessionAppId)
@@ -4317,19 +3833,11 @@ export function registerPtyHandlers(
               store?.markSshRemotePtyLease(args.connectionId, effectiveSessionRelayId, 'expired')
             }
           }
-          // Why: if buildPtyHostEnv materialized provider state for this minted
-          // id but provider.spawn failed, that state would otherwise leak.
+          // Why: provider state buildPtyHostEnv materialized for this minted id leaks if spawn failed.
           if (isMintedSessionId && effectiveSessionId !== undefined) {
             clearProviderPtyState(effectiveSessionId)
           }
-          // Why: telemetry-plan.md§agent_error — when the renderer threaded
-          // agent_kind through args.telemetry, attribute the error to that agent.
-          // Otherwise fall back to sniffing the command for `claude` (the one
-          // agent the main process can identify on its own via the existing
-          // `isClaudeLaunchCommand` regex used for auth gating). Bare-shell
-          // catches and unknown-agent catches without renderer telemetry remain
-          // unattributed. The event still emits with a classified `error_class`;
-          // raw error messages are dropped at the telemetry validator boundary.
+          // Why: telemetry-plan.md§agent_error — attribute the error to the renderer-threaded agent_kind, else sniff the command for `claude`; raw messages are dropped at the validator boundary.
           const rendererAgentKindParse =
             args.telemetry?.agent_kind !== undefined
               ? agentKindSchema.safeParse(args.telemetry.agent_kind)
@@ -4359,33 +3867,23 @@ export function registerPtyHandlers(
         })
         ptyOwnership.set(result.id, args.connectionId ?? null)
         if (initiallyHidden) {
-          // Why marked synchronously before any await below: local/SSH provider
-          // data events dispatch on later tasks, so this is still ahead of the
-          // first byte's delivery decision. Idempotent for daemon hosts already
-          // marked pre-spawn; the renderer's first visibility sync re-marks or
-          // unmarks (emitting the restore marker) through the Phase-4 path.
+          // Why marked synchronously here: provider data events dispatch on later tasks, so this still lands ahead of the first byte's delivery decision (idempotent if already marked pre-spawn).
           markHiddenRendererPty(result.id)
           if (preSpawnHiddenMarkId !== null && preSpawnHiddenMarkId !== result.id) {
             // Defense: never strand a mark on an id the provider renamed.
             unmarkHiddenRendererPty(preSpawnHiddenMarkId)
           }
-          // Why after ptyOwnership.set: the provider lookup routes by
-          // ownership, and a hidden-spawned agent should be paceable from its
-          // first flood, not from its first visibility transition.
+          // Why after ptyOwnership.set: provider lookup routes by ownership, and a hidden-spawned agent should be paceable from its first flood.
           syncPtyBackgroundedDelivery(result.id, 'spawn')
           closeStartupQueryAuthorityForPty(result.id)
         }
-        // Why: Phase-5 ConPTY DA1 — record the native-Windows-local-PTY
-        // determination from the spawn record before the headless seed below,
-        // so the runtime emulator's DA1 override exists from byte zero.
+        // Why: record the native-Windows-ConPTY determination before the headless seed so the emulator's DA1 override exists from byte zero.
         if (nativeWindowsConptySpawn) {
           markNativeWindowsConptyPty(result.id)
         }
         const relayResultId = getRelayPtyId(args.connectionId, result.id)
         if (store && args.connectionId) {
-          // Why: remote PTYs live in the SSH relay grace window after Orca
-          // detaches. Persist their IDs immediately so reconnect can reattach
-          // instead of treating the tab as a fresh shell.
+          // Why: remote PTYs live in the SSH relay grace window after Orca detaches; persist IDs immediately so reconnect reattaches instead of spawning a fresh shell.
           store.upsertSshRemotePtyLease({
             targetId: args.connectionId,
             ptyId: relayResultId,
@@ -4400,12 +3898,7 @@ export function registerPtyHandlers(
           runtime?.registerPreAllocatedHandleForPty(result.id, preAllocatedHandle)
         }
         ptySizes.set(result.id, { cols: args.cols, rows: args.rows })
-        // Why: closes the SIGKILL-between-spawn-and-persist race (Issue #217)
-        // for local daemon PTYs and the equivalent remote-relay race for SSH.
-        // The renderer's debounced session writer runs in parallel for every
-        // other field; patch the load-bearing (tab.ptyId, ptyIdsByLeafId)
-        // binding synchronously so a force-quit in the ~450 ms debounce window
-        // cannot orphan either daemon history or a remote relay PTY lease.
+        // Why: patch the load-bearing ptyId binding synchronously so a force-quit in the renderer's ~450 ms debounce window can't orphan daemon history or an SSH relay lease (Issue #217).
         if (
           (isDaemonHostSpawn || args.connectionId) &&
           store &&
@@ -4438,12 +3931,7 @@ export function registerPtyHandlers(
             throw new Error(createTerminalSessionStateSaveFailureMessage())
           }
         }
-        // Why: pre-signal cooperation gate — when the renderer has declared it
-        // will own the serializer for this paneKey, suppress the daemon-snapshot
-        // seed so the renderer's hydration path (maybeHydrateHeadlessFromRenderer)
-        // is the sole authority. The pre-signal is keyed on paneKey because at
-        // spawn time the renderer doesn't yet know the new ptyId. See
-        // docs/mobile-prefer-renderer-scrollback.md.
+        // Why: when the renderer has declared it will own the serializer for this paneKey, suppress the daemon-snapshot seed so its hydration path is sole authority (keyed on paneKey since the ptyId isn't known yet). See docs/mobile-prefer-renderer-scrollback.md.
         const rendererPreSignaled = validatedPaneKey
           ? pendingByPaneKey.has(validatedPaneKey)
           : false
@@ -4452,9 +3940,7 @@ export function registerPtyHandlers(
           !rendererPreSignaled &&
           rendererSerializerReadiness.has(result.id)
         rendererSerializerReadiness.beginIncarnation(result.id, rendererAlreadyRegistered)
-        // Why: capture the pending gen at spawn time so teardown for THIS PTY
-        // only settles its own generation. A remount that replaces the entry
-        // with a new gen must not be stomped by the old PTY's teardown.
+        // Why: capture the pending gen at spawn time so this PTY's teardown only settles its own generation, not a remount that replaced the entry.
         if (validatedPaneKey && rendererPreSignaled) {
           const pending = pendingByPaneKey.get(validatedPaneKey)
           if (pending) {
@@ -4462,27 +3948,15 @@ export function registerPtyHandlers(
           }
         }
 
-        // Why: hydrate the runtime's headless emulator with the adapter's
-        // restore data BEFORE registerPty so any live PTY data that arrives
-        // concurrently lands on top of the seed instead of replacing it. Mobile
-        // subscribers then see the same scrollback the desktop xterm received
-        // via coldRestore/snapshot. Without this, mobile snapshots after a
-        // daemon-restored attach contain only bytes emitted since the relaunch
-        // and the prior agent output silently disappears.
-        //
-        // Skip when the renderer is or will be authoritative for this PTY:
-        // its hydration path will seed the emulator from xterm's live buffer,
-        // which is richer than the daemon snapshot.
+        // Why: seed the headless emulator before registerPty so concurrent live PTY data lands on top of the seed, not replacing it (mobile keeps the daemon-restored scrollback).
+        // Skip when the renderer will be authoritative — its xterm buffer is richer than the daemon snapshot.
         if (runtime && !rendererPreSignaled && !rendererAlreadyRegistered) {
           const snapshotSeedSize =
             typeof result.snapshotCols === 'number' && typeof result.snapshotRows === 'number'
               ? { cols: result.snapshotCols, rows: result.snapshotRows }
               : undefined
           if (typeof result.snapshot === 'string' && result.snapshot.length > 0) {
-            // Why kitty flags ride seed metadata: the snapshot string omits
-            // them by design (renderer kitty reset stays authoritative), but
-            // the re-seeded emulator must answer hidden `CSI ? u` with the
-            // flags the still-running app pushed (terminal-query-authority.md).
+            // Why kitty flags ride seed metadata: the snapshot omits them, but the re-seeded emulator must answer hidden `CSI ? u` with the running app's flags (terminal-query-authority.md).
             runtime.seedHeadlessTerminal(
               result.id,
               result.snapshot,
@@ -4522,10 +3996,7 @@ export function registerPtyHandlers(
             result.id,
             args.worktreeId,
             args.connectionId ?? null,
-            // Why: pass the validated pane identity so a mobile create waiting on
-            // this renderer tab can publish its surface main-side when graph-sync
-            // is throttled, instead of destroying the live PTY (#7587). Bound the
-            // untrusted tabId like the sibling metadataPaneKey/spawnOptions.tabId.
+            // Why: pass validated pane identity so a throttled mobile create publishes its surface main-side instead of destroying the live PTY (#7587); bound the untrusted tabId.
             typeof args.tabId === 'string' &&
               isValidTerminalTabId(args.tabId) &&
               args.tabId.length <= 512 &&
@@ -4537,9 +4008,7 @@ export function registerPtyHandlers(
               : undefined
           )
         }
-        // Why: arms main's per-PTY Command Code output detector from the launch
-        // command (renderer startupCommand parity); banner detection covers
-        // PTYs spawned without one.
+        // Why: arm main's per-PTY Command Code output detector from the launch command (startupCommand parity); banner detection covers PTYs without one.
         runtime?.noteTerminalSpawnCommand?.(
           result.id,
           typeof args.command === 'string' ? args.command : null
@@ -4547,14 +4016,8 @@ export function registerPtyHandlers(
         if (isClaudeLaunch) {
           markClaudePtySpawned(result.id)
         }
-        // Why: renderer sets ORCA_PANE_KEY in `args.env` for every pane-owned
-        // spawn (see pty-connection.ts). Recording the mapping here lets
-        // clearProviderPtyState clear the agent-hooks server's per-paneKey
-        // caches when the PTY exits.
-        // Why: args.env arrives as untrusted JSON over IPC — the static
-        // Record<string, string> type is not actually enforced at the boundary.
-        // Narrow to a bounded string so malformed or oversized values cannot
-        // pollute ptyPaneKey or the downstream clearPaneState call.
+        // Why: record the paneKey mapping so clearProviderPtyState can clear the agent-hooks server's per-paneKey caches on exit.
+        // Why: args.env is untrusted IPC JSON (type unenforced); bound the paneKey so malformed/oversized values can't pollute ptyPaneKey or clearPaneState.
         const rememberedPaneKey = validatedPaneKey
           ? rememberPaneKeyForPty(result.id, validatedPaneKey)
           : null
@@ -4572,22 +4035,11 @@ export function registerPtyHandlers(
             clearMigrationUnsupportedPtysForPaneKey(validatedPaneKey)
           }
         }
-        // Why: register local PTYs (connectionId falsy) with the memory
-        // collector so it can walk each PTY's process subtree and attribute
-        // memory back to its worktree. SSH PTYs execute remotely and their
-        // process tree is not visible to our local `ps`, so we skip them.
+        // Why: register only local PTYs with the memory collector — SSH PTYs run remotely and their process tree is invisible to our local `ps`.
         if (!args.connectionId) {
-          // Why: providers publish the OS pid on the spawn result (both
-          // LocalPtyProvider and DaemonPtyAdapter). Recording it once here keeps
-          // the memory module from reaching back into ipc/pty on a hot path, and
-          // works uniformly whether the PTY is hosted in-process or by the
-          // daemon subprocess.
+          // Why: record the spawn-result pid once here so the memory module needn't reach back into ipc/pty on a hot path (works for in-process and daemon-hosted PTYs).
           const spawnedPid = result.pid ?? null
-          // Why: args.worktreeId and args.sessionId arrive as untrusted IPC
-          // payload strings — the static type is not enforced at the boundary.
-          // Narrow them to bounded strings here to match the paneKey defense
-          // above so malformed or oversized values cannot pollute registerPty's
-          // maps or downstream memory-attribution lookups.
+          // Why: args.worktreeId/sessionId arrive as untrusted IPC strings (type unenforced at the boundary); bound them so malformed/oversized values can't pollute registerPty's maps.
           registerPty({
             ptyId: result.id,
             worktreeId:
@@ -4609,16 +4061,7 @@ export function registerPtyHandlers(
                 : null
           })
         }
-        // Why: telemetry-plan.md§Agent launch semantics — fire `agent_started`
-        // only after `provider.spawn` resolved. The renderer threads
-        // `args.telemetry` through the spawn IPC for every launch we want to
-        // attribute; bare-shell tabs (no agent) leave the field undefined and
-        // do not produce an event. Each field is parsed against its closed
-        // enum here so a malformed renderer payload (or a spoofed IPC) does
-        // not poison the event — `safeParse` failure drops that field, and
-        // if any required field is missing we skip the event entirely. The
-        // main-side `track()` validator re-runs the schema on the full
-        // payload as a second defense-in-depth check.
+        // Why: telemetry-plan.md§Agent launch semantics — fire agent_started only after spawn resolved; safeParse each field so a spoofed IPC payload can't poison the event (missing required field skips it).
         if (args.telemetry) {
           const agentKindParse = agentKindSchema.safeParse(args.telemetry.agent_kind)
           const launchSourceParse = launchSourceSchema.safeParse(args.telemetry.launch_source)
@@ -4637,18 +4080,12 @@ export function registerPtyHandlers(
           ...(!result.isReattach && effectiveLaunchConfig
             ? { launchConfig: effectiveLaunchConfig }
             : {}),
-          // Why: a daemon-retry race can surface isReattach even for a minted
-          // session id, and a reattach must never claim its cwd was remapped.
+          // Why: a daemon-retry race can surface isReattach even for a minted session id, and a reattach must never claim its cwd was remapped.
           ...(startupCwdFallback && !result.isReattach ? { startupCwdFallback } : {})
         }
         return resolvePaneSpawnReservation(reservationPaneKey, paneSpawnReservation, response)
       } catch (err) {
-        // Why: once the reservation is created, any later throw —
-        // spawn failure, persist failure, or a post-spawn helper such as
-        // seedHeadlessTerminal/registerPty/track — must settle it. Otherwise
-        // it lingers in paneSpawnReservationsByPaneKey and every future spawn
-        // for this pane awaits a promise that never resolves. reject is a
-        // no-op once the reservation has already resolved.
+        // Why: any later throw must settle the reservation, else it lingers and every future spawn for this pane awaits a promise that never resolves (reject no-ops if already resolved).
         rejectPaneSpawnReservation(reservationPaneKey, paneSpawnReservation, err)
         throw err
       } finally {
@@ -4749,12 +4186,7 @@ export function registerPtyHandlers(
     !(typeof mainWebContents.isDestroyed === 'function' && mainWebContents.isDestroyed())
 
   const writePtyInput = (args: PtyWritePayload): boolean | Promise<boolean> => {
-    // Why: defense-in-depth for the mobile-presence lock. The renderer's
-    // xterm.onData guard already drops desktop keystrokes when mobile is
-    // driving, but a stale view between the main-side state flip and the
-    // IPC arriving in the renderer can let one keystroke slip through.
-    // This server-side check catches it. See
-    // docs/mobile-presence-lock.md.
+    // Why: mobile-presence-lock defense-in-depth — the renderer's onData guard can let one keystroke slip during the state-flip lag, so catch it server-side. See docs/mobile-presence-lock.md.
     if (runtime?.getDriver(args.id).kind === 'mobile') {
       return false
     }
@@ -4779,10 +4211,7 @@ export function registerPtyHandlers(
     if (runtime?.getDriver(args.id).kind === 'mobile') {
       return false
     }
-    // Why: the acknowledgement is used to infer Ctrl+C/Escape actually reached
-    // the local PTY. SSH providers are fire-and-forget relay notifications, so
-    // they cannot truthfully acknowledge until the relay protocol grows a write
-    // request/response.
+    // Why: the ack infers Ctrl+C/Escape reached the local PTY; SSH providers are fire-and-forget relay notifications and can't truthfully acknowledge yet.
     if (ptyOwnership.get(args.id) !== null) {
       return false
     }
@@ -4836,8 +4265,7 @@ export function registerPtyHandlers(
       return
     }
     const prior = hostViewportClaimTails.get(args.id)
-    // Why: two panes can mirror one PTY. Never let a later no-op claim replace
-    // the in-flight resize that the following host input must await.
+    // Why: two panes can mirror one PTY — never let a later no-op claim replace the in-flight resize that the following host input must await.
     const claim = (
       prior
         ? prior.then(
@@ -4854,29 +4282,14 @@ export function registerPtyHandlers(
     })
   })
 
-  // Why: resize is fire-and-forget — the renderer doesn't need a reply.
-  // Using ipcMain.on (not .handle) halves IPC traffic by avoiding the
-  // empty acknowledgement message back to the renderer.
+  // Why: resize is fire-and-forget — ipcMain.on (not .handle) halves IPC traffic by skipping the empty acknowledgement reply.
   ipcMain.removeAllListeners('pty:resize')
   ipcMain.on('pty:resize', (_event, args: { id: string; cols: number; rows: number }) => {
-    // Why: after a desktop-fit override change, the desktop renderer's
-    // re-render cascade 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. Suppressing ALL pty:resize during
-    // this window prevents the cascade from corrupting PTY dimensions.
+    // Why: after a desktop-fit override change the renderer's safeFit cascade re-measures ALL panes (background ones at full width), so suppress every pty:resize in this window to avoid corrupting PTY dimensions.
     if (runtime?.isResizeSuppressed()) {
       return
     }
-    // Why: presence-lock defense-in-depth. While a phone OR a remote desktop
-    // viewer drives the PTY width, the host's own desktop-side resizes
-    // (auto-fit on window resize, split drag, tab reveal, "+"-new-tab
-    // re-render) must not reach the PTY — otherwise they overwrite the remote
-    // viewer's grid and its alt-screen TUI garbles ("porridge"). The renderer
-    // guard checks the driver state too, but this is the load-bearing layer
-    // because the renderer mirror lags by one IPC hop. Note: BOTH guards apply
-    // — isResizeSuppressed handles the safeFit cascade after take-back; this
-    // driver check handles the ongoing locked state. See
-    // docs/mobile-presence-lock.md.
+    // Why: presence-lock defense-in-depth — while a phone or remote-desktop viewer drives the width, host-side resizes must not reach the PTY or its alt-screen grid garbles; load-bearing because the renderer mirror lags one IPC hop. See docs/mobile-presence-lock.md.
     const mobileOwnsResize = runtime?.getDriver(args.id).kind === 'mobile'
     const remoteDesktopOwnsResize = runtime?.isRemoteDesktopResizeDriven?.(args.id) === true
     if (mobileOwnsResize || remoteDesktopOwnsResize) {
@@ -4891,14 +4304,11 @@ export function registerPtyHandlers(
     }
     const markedHiddenResizeOutput = rendererPtyIsKnownHidden(args.id)
     if (markedHiddenResizeOutput) {
-      // Why: alternate-screen TUIs repaint on SIGWINCH. If that hidden repaint
-      // is read after the user switches back, it must not masquerade as live
-      // foreground output and overwrite the correctly-sized screen.
+      // Why: alt-screen TUIs repaint on SIGWINCH; a hidden repaint read after switch-back must not masquerade as live output and overwrite the correctly-sized screen.
       pendingHiddenRendererResizeOutputPtys.add(args.id)
       deliveredHiddenRendererResizeOutputPtys.delete(args.id)
     } else if (visibleRendererPtys.has(args.id)) {
-      // Why: after the stale hidden-resize repaint has been observed, the
-      // renderer's visible resize pulse owns the next repaint.
+      // Why: after the stale hidden-resize repaint is observed, the renderer's visible resize pulse owns the next repaint.
       clearDeliveredHiddenRendererResizeOutput(args.id)
     }
     try {
@@ -4913,25 +4323,13 @@ export function registerPtyHandlers(
     runtime?.onExternalPtyResize(args.id, args.cols, args.rows)
   })
 
-  // Why: pty:reportGeometry is a measurement-only sibling of pty:resize.
-  // pty:resize means "I want the PTY at this size" (a write/intent — gated
-  // by mobile-driver and cascade suppress). pty:reportGeometry means "the
-  // desktop pane I'm rendering currently measures this many cells" (a
-  // read/observation). Mobile-fit hold needs the latter even while the
-  // former is intentionally blocked: when a previously-hidden desktop
-  // tab becomes visible while a phone is driving, the server has no way
-  // to learn the real desktop dims, and resolveDesktopRestoreTarget
-  // returns the stale spawn default (e.g. 80×24) on Take Back. Splitting
-  // the channels keeps each guard simple — pty:resize keeps its mobile-
-  // driver gate; pty:reportGeometry never resizes the PTY, only refreshes
-  // the restore-target cache. See docs/mobile-fit-hold.md.
+  // Why: pty:reportGeometry is a measurement-only sibling of pty:resize — it refreshes the restore-target cache (never resizes) so mobile-fit hold learns real desktop dims even while resize is blocked. See docs/mobile-fit-hold.md.
   ipcMain.removeAllListeners('pty:reportGeometry')
   ipcMain.on('pty:reportGeometry', (_event, args: { id: string; cols: number; rows: number }) => {
     runtime?.recordRendererGeometry(args.id, args.cols, args.rows)
   })
 
-  // Why: fire-and-forget — clears the DaemonPtyAdapter's sticky cold restore
-  // cache after the renderer has consumed the data. No-op for non-daemon providers.
+  // Why: fire-and-forget — clears the DaemonPtyAdapter's sticky cold-restore cache after the renderer consumed it; no-op for non-daemon providers.
   ipcMain.on('pty:ackColdRestore', (_event, args: { id: string }) => {
     const provider = tryGetProviderForPty(args.id)
     if (provider && 'ackColdRestore' in provider && typeof provider.ackColdRestore === 'function') {
@@ -4939,22 +4337,18 @@ export function registerPtyHandlers(
     }
   })
 
-  // Why: renderer ACKs bound main→renderer terminal delivery without stopping
-  // PTY ingestion. Agent/status consumers still see every chunk through the
-  // provider/runtime path while background renderer writes wait their turn.
+  // Why: renderer ACKs bound main→renderer delivery without stopping PTY ingestion — agent/status consumers still see every chunk via the provider/runtime path.
   ipcMain.on(
     'pty:ackData',
     (_event, args: { id: string; charCount?: number; processedChars?: number }) => {
       lastAckReceivedAtMs = Date.now()
-      // Why: a live ACK channel means a future unanswered probe is a fresh
-      // diagnostic event, not a continuation of the last silent streak.
+      // Why: a live ACK channel means a future unanswered probe is a fresh diagnostic event, not a continuation of the last silent streak.
       deliveryResyncUnansweredWarnLogged = false
       let acknowledged = 0
       if (typeof args.processedChars === 'number' && Number.isFinite(args.processedChars)) {
         acknowledged = applyCumulativeAck(args.id, Math.max(0, args.processedChars))
       } else {
-        // Why: tolerate legacy per-chunk delta payloads — dev hot-reload can
-        // pair an old renderer with a new main. Keyed by field presence.
+        // Why: tolerate legacy per-chunk delta payloads — dev hot-reload can pair an old renderer with a new main.
         const accounting = rendererDeliveryAccountingByPty.get(args.id)
         const delta = Number.isFinite(args.charCount) ? Math.max(0, args.charCount ?? 0) : 0
         acknowledged = accounting ? applyCumulativeAck(args.id, accounting.ackedChars + delta) : 0
@@ -4978,9 +4372,7 @@ export function registerPtyHandlers(
       }
       clearDeliveryResyncProbe()
       deliveryResyncUnansweredWarnLogged = false
-      // Why: max-merge — the renderer's cumulative totals are authoritative
-      // for what it processed; reconciling them drains exactly the in-flight
-      // debt left by lost ACKs, nothing more.
+      // Why max-merge: the renderer's cumulative totals are authoritative for what it processed, draining exactly the in-flight debt from lost ACKs.
       for (const [id, processedChars] of Object.entries(args.processedCharsByPty ?? {})) {
         if (typeof processedChars !== 'number' || !Number.isFinite(processedChars)) {
           continue
@@ -4997,16 +4389,11 @@ export function registerPtyHandlers(
     }
   )
 
-  // Why invoke + renderer-initiated: the field wedge (v1.4.121-rc.0 snapshot,
-  // 2026-07-06) kills every main→renderer push channel while invoke stays
-  // alive, so the solicited-resync probe above can never be answered there.
-  // This is the same reconcile, ridden over the direction proven to work, plus
-  // a write-off lane for bytes the renderer provably never received.
+  // Why invoke + renderer-initiated: the field wedge (v1.4.121-rc.0) kills every main→renderer push channel while invoke survives, so the resync rides here plus a write-off lane.
   ipcMain.handle(
     'pty:reportRendererDeliveryState',
     (_event, args: PtyRendererDeliveryStateReport): PtyRendererDeliveryHealthReply => {
-      // Extra repair lane for the lost-ACK variant: identical max-merge to the
-      // resync response, so a heal is only reached when merging cannot drain.
+      // Extra repair lane for the lost-ACK variant: identical max-merge to the resync response, so a heal is only reached when merging cannot drain.
       for (const [id, processedChars] of Object.entries(args?.processedCharsByPty ?? {})) {
         if (typeof processedChars !== 'number' || !Number.isFinite(processedChars)) {
           continue
@@ -5017,9 +4404,7 @@ export function registerPtyHandlers(
         }
       }
       let writtenOff: PtyDeliveryWriteOff[] = []
-      // Why the main-side ACK-silence check: the renderer's two silent ticks
-      // already argue for a wedge; requiring main to have seen no ACK either
-      // keeps a buggy/foreign caller from writing off live delivery.
+      // Why the main-side ACK-silence check: requiring main to have also seen no ACK stops a buggy/foreign caller from writing off live delivery.
       if (
         args?.heal === true &&
         rendererInFlightTotalChars > 0 &&
@@ -5047,28 +4432,18 @@ export function registerPtyHandlers(
     }
   )
 
-  // Why: the renderer sends this once its pty:data listener is live (per page
-  // load / reload). Until it arrives, sends are held so boot-window bytes can't
-  // drop into a listener-less page and pin the delivery gate; on arrival, flush
-  // the backlog that accrued during the boot window.
+  // Why: renderer signals its pty:data listener is live; until then sends are held so boot-window bytes can't drop into a listener-less page and pin the gate.
   ipcMain.removeAllListeners('pty:rendererDispatcherReady')
   ipcMain.on('pty:rendererDispatcherReady', (event) => {
-    // Why: the reconcile below destructively clears delivery accounting, so a
-    // straggler handshake from a dying window must not reset the new window.
+    // Why: the reconcile below destructively clears delivery accounting, so a straggler handshake from a dying window must not reset the new window.
     if (!isPtyWriteEventFromMainWindow(event, mainWindow.webContents)) {
       return
     }
-    // Why: the handshake is one-shot per page load, so receiving it while the gate
-    // is already open means a fresh page loaded but its lifecycle reset was missed —
-    // a main-frame reload overlapped by an in-page subframe load emits no
-    // did-start-loading, and the watchdog may have force-opened the gate — leaving
-    // main holding the dead page's in-flight accounting, which permanently gates the
-    // survivors. Reconcile by clearing that stale accounting before re-opening.
+    // Why: a handshake while the gate is already open means a page load whose lifecycle reset was missed; clear the dead page's stale accounting so it can't permanently gate survivors.
     if (rendererPtyDispatcherReady) {
       resetRendererDeliveryAccountingForLifecycleReset()
     }
-    // Why: real handshake landed — cancel the self-heal watchdog so it can't later
-    // force-open the gate and inflate rendererDispatcherReadyForcedCount.
+    // Why: real handshake landed — cancel the self-heal watchdog so it can't later force-open the gate.
     clearDispatcherReadyWatchdog()
     rendererPtyDispatcherReady = true
     schedulePendingDataFlush(0)
@@ -5079,9 +4454,7 @@ export function registerPtyHandlers(
     if (typeof args.id !== 'string' || !args.id) {
       return
     }
-    // Why: this is a renderer scheduling hint only. PTY reads, runtime state,
-    // and notifications continue for inactive terminals; active panes merely
-    // get first chance at the bounded renderer output reserve.
+    // Why: renderer scheduling hint only — active panes just get first chance at the bounded output reserve; reads/state/notifications continue for inactive terminals.
     if (args.active) {
       activeRendererPtys.add(args.id)
     } else {
@@ -5097,8 +4470,7 @@ export function registerPtyHandlers(
     if (typeof args.id !== 'string' || !args.id) {
       return
     }
-    // Why: data produced while no renderer can see this PTY must keep that origin
-    // through batching, even if the user switches back before the flush lands.
+    // Why: data produced while no renderer can see this PTY must keep that origin through batching, even if the user switches back before the flush lands.
     rendererVisibilityKnownPtys.add(args.id)
     if (args.visible) {
       visibleRendererPtys.add(args.id)
@@ -5120,9 +4492,7 @@ export function registerPtyHandlers(
     if (args.hidden === true) {
       markHiddenRendererPty(args.id)
       closeStartupQueryAuthorityForPty(args.id)
-      // Why: bytes already queued for a newly hidden PTY are model-owned
-      // state; drop them now instead of holding them under ACK starvation.
-      // Reveal restores from the snapshot.
+      // Why: drop bytes queued for a newly hidden PTY instead of holding them under ACK starvation; reveal restores from the snapshot.
       const pending = pendingData.get(args.id)
       if (pending && shouldDropHiddenRendererPtyData(args.id, getSettings?.())) {
         pendingData.delete(args.id)
@@ -5143,12 +4513,7 @@ export function registerPtyHandlers(
     }
     const { droppedWhileHidden } = unmarkHiddenRendererPty(args.id)
     syncPtyBackgroundedDelivery(args.id, 'gate-unmark')
-    // Why: a renderer reload or remount can replace the view that latched
-    // restore-needed from the first-drop marker. Re-emit on unhide so the
-    // (possibly fresh) visible view still pulls the model snapshot covering
-    // the dropped bytes. If the original view is still alive this can trigger
-    // a redundant second restore — accepted: a snapshot replay is cheap and
-    // idempotent, while a missed restore leaves a corrupt pane.
+    // Why: a reload/remount may have replaced the view that latched restore-needed, so re-emit on unhide; a redundant replay is cheap/idempotent, a missed restore corrupts the pane.
     if (droppedWhileHidden) {
       sendModelRestoreNeededMarker(args.id, 'unhide', runtime?.getPtyOutputSequence(args.id))
     }
@@ -5156,9 +4521,7 @@ export function registerPtyHandlers(
 
   ipcMain.removeAllListeners('pty:terminalViewAttributes')
   ipcMain.on('pty:terminalViewAttributes', (_event, args: unknown) => {
-    // Why validate-or-drop: the responder must never store a malformed
-    // palette — a wrong color reply breaks TUI theme detection worse than
-    // the documented silent-until-first-push behavior.
+    // Why validate-or-drop: a malformed palette gives a wrong color reply that breaks TUI theme detection worse than the silent-until-first-push default.
     const attributes = validateTerminalViewAttributes(args)
     if (attributes) {
       setTerminalViewAttributes(attributes)
@@ -5170,11 +4533,7 @@ export function registerPtyHandlers(
     if (typeof args.id !== 'string' || !args.id) {
       return
     }
-    // Why: explicit delivery-interest signal from renderer byte sidecars —
-    // any interest suppresses the hidden-delivery gate so
-    // raw-byte consumers keep receiving while the view is hidden or parked.
-    // Deliberately NOT synced to the daemon backlog pacer: interest consumers
-    // tolerate paced data, and interest churn must not un-pace a flood.
+    // Why: any delivery interest suppresses the hidden-delivery gate (raw-byte consumers keep receiving while hidden); not synced to the daemon pacer so interest churn can't un-pace a flood.
     setRendererPtyDeliveryInterest(args.id, args.interested === true)
   })
 
@@ -5187,9 +4546,7 @@ export function registerPtyHandlers(
 
   ipcMain.removeAllListeners('pty:clearBuffer')
   ipcMain.on('pty:clearBuffer', (_event, args: { id: string }) => {
-    // Why: the renderer already cleared its own xterm buffer. This clears the
-    // PTY-side state (ConPTY screen buffer, daemon emulator, SSH host buffer)
-    // so the next prompt repaint doesn't land at a stale cursor row.
+    // Why: clear PTY-side state (ConPTY/daemon/SSH buffer) so the next prompt repaint doesn't land at a stale cursor row.
     tryGetProviderForPty(args.id)
       ?.clearBuffer(args.id)
       .catch(() => {})
@@ -5198,24 +4555,20 @@ export function registerPtyHandlers(
 
   ipcMain.handle('pty:kill', async (_event, args: { id: string; keepHistory?: boolean }) => {
     if (typeof args?.id !== 'string' || !args.id || args.id.startsWith('remote:')) {
-      // Why: runtime terminal handles belong to terminal.close; allowing them
-      // to fall through unowned PTY routing could target the local provider.
+      // Why: runtime terminal handles belong to terminal.close; unowned PTY routing could target the local provider.
       throw new Error('Invalid PTY provider id')
     }
     const ownedConnectionId = ptyOwnership.get(args.id)
     const parsedSshId = ownedConnectionId === undefined ? parseAppSshPtyId(args.id) : null
     const connectionId = ownedConnectionId ?? parsedSshId?.connectionId
-    // Why: select the local provider only after daemon startup; fallback shutdown
-    // can otherwise falsely succeed and orphan a restored daemon PTY (#7742).
+    // Why: wait for daemon startup before selecting the local provider, else a fallback shutdown falsely succeeds and orphans a restored daemon PTY (#7742).
     const startupPromise = getLocalPtyProviderStartupPromise(connectionId)
     if (startupPromise) {
       await startupPromise
     }
     const provider = connectionId ? sshProviders.get(connectionId) : tryGetProviderForPty(args.id)
     if (!provider && connectionId) {
-      // Why: detached SSH PTYs intentionally keep ownership after their
-      // provider is unregistered; hydrated app-scoped ids can also arrive
-      // before ownership is rebuilt. Tombstone instead of falling back local.
+      // Why: detached SSH PTYs keep ownership after provider unregister, and hydrated app-scoped ids may arrive pre-ownership; tombstone instead of falling back local.
       finishPtyShutdown(args.id, connectionId, store)
       runtime?.onPtyExit(args.id, -1)
       rememberSyntheticKillExit(args.id)
@@ -5231,15 +4584,12 @@ export function registerPtyHandlers(
       })
     } catch (err) {
       if (!isPtyAlreadyGoneError(err)) {
-        // Why: a failed SSH shutdown can leave the remote process alive in
-        // the relay grace window; daemon failures have the same risk locally.
-        // Keep ownership/lease state so the user can retry.
+        // Why: a failed shutdown can leave the process alive (SSH relay grace window / local daemon); keep ownership/lease state so the user can retry.
         throw err
       }
       /* session already dead — cleanup below handles the rest */
     }
-    // Why: some shutdown paths do not emit onExit through the provider listener.
-    // Explicit cleanup is idempotent and covers already-dead PTYs.
+    // Why: some shutdown paths don't emit onExit via the provider listener; this cleanup is idempotent and covers already-dead PTYs.
     finishPtyShutdown(args.id, connectionId, store)
     if (!providerExitObserved) {
       runtime?.onPtyExit(args.id, -1)
@@ -5264,9 +4614,7 @@ export function registerPtyHandlers(
       const deduped = new Map<string, { id: string; cwd: string; title: string }>()
       for (const { connectionId, sessions } of providerSessions) {
         for (const session of sessions) {
-          // Why: SessionsStatusSegment kill actions only send the PTY id back
-          // through IPC. Rebuild ownership while listing so remote sessions
-          // discovered after reconnect still route to their original provider.
+          // Why: kill actions only send back the PTY id, so rebuild ownership while listing to keep reconnect-discovered remote sessions routed to their provider.
           ptyOwnership.set(session.id, connectionId)
           deduped.set(session.id, session)
         }
@@ -5292,8 +4640,7 @@ export function registerPtyHandlers(
         }
         seen.add(value)
         const provider = tryGetProviderForPty(value)
-        // Why: degraded routing mixes preserved daemons with an in-process
-        // fallback. Keep all of its panes mounted rather than guess ownership.
+        // Why: degraded routing mixes preserved daemons with an in-process fallback; keep all panes mounted rather than guess ownership.
         capabilities.push({
           id: value,
           authoritative: provider?.canProvideAuthoritativeBufferSnapshot
@@ -5303,8 +4650,7 @@ export function registerPtyHandlers(
               : null
         })
       }
-      // Why: cold deferral runs during render, before hidden panes mount. This
-      // batch is an in-memory route lookup so legacy PTYs can mount in that pass.
+      // Why: cold deferral runs during render before hidden panes mount; this in-memory route lookup lets legacy PTYs mount in that pass.
       event.returnValue = capabilities
     }
   )
@@ -5353,18 +4699,12 @@ export function registerPtyHandlers(
         return null
       }
       const provider = getProviderForPty(args.id)
-      // Why: falling back to the cached foreground API would turn stale
-      // process identity into shell/agent authority at a command boundary.
+      // Why: the cached foreground API would turn stale process identity into shell/agent authority at a command boundary.
       return provider.confirmForegroundProcess?.(args.id) ?? null
     }
   )
 
-  // Why: renderer needs the live shell cwd when the user presses Cmd+D so
-  // the new split pane inherits the source pane's cwd instead of the
-  // worktree root. Routed through getProviderForPty so local and SSH PTYs
-  // use the same code path. Providers return '' when the id is unknown or
-  // the platform cannot resolve a cwd (Windows); the renderer treats ''
-  // as "fall through to the next fallback layer".
+  // Why: Cmd+D split needs the live shell cwd so the new pane inherits it (not the worktree root); '' means unknown/unresolvable (Windows) → renderer falls through.
   ipcMain.handle('pty:getCwd', async (_event, args: { id: string }): Promise<string> => {
     try {
       return await getProviderForPty(args.id).getCwd(args.id)
@@ -5373,19 +4713,7 @@ export function registerPtyHandlers(
     }
   })
 
-  // Why: the renderer forwards resizes fire-and-forget and otherwise has no way
-  // to learn the PTY's actual size. A resize dropped main-side (suppression
-  // window, mobile-driver gate, or a provider no-op) OR daemon/SSH-side (the
-  // remote resize notify is unacked and can be silently dropped — session not
-  // yet alive, exited, invalid dims, cold-restore snapshot-col coercion) leaves
-  // the renderer believing it synced when it did not, so a later same-cols
-  // layout never re-forwards and the TUI stays garbled. ptySizes records only
-  // the REQUESTED size, so it cannot reveal such a drop. Prefer the provider's
-  // APPLIED size (node-pty's cached winsize / the daemon emulator's dims, which
-  // track the subprocess resize) so the renderer's resume drift-check sees the
-  // truth; fall back to ptySizes only when the provider can't report (no
-  // getAppliedSize, e.g. SSH relay, or an unknown id) — a null then reads as
-  // "cannot confirm", which the renderer treats as a cue to re-forward once.
+  // Why: prefer the provider's APPLIED size over the requested ptySizes so the renderer's resume drift-check can spot a dropped resize; null means "cannot confirm" → re-forward once.
   ipcMain.handle(
     'pty:getSize',
     async (_event, args: { id: string }): Promise<{ cols: number; rows: number } | null> => {
@@ -5395,19 +4723,13 @@ export function registerPtyHandlers(
           return applied
         }
       } catch {
-        // Fall through to the requested-size cache on any provider/RPC failure
-        // so a dead daemon/relay never blocks or throws across the IPC boundary.
+        // Fall through to the requested-size cache so a dead daemon/relay can't throw across the IPC boundary.
       }
       return ptySizes.get(args.id) ?? null
     }
   )
 
-  // Why: pre-signal handshake handlers. See
-  // docs/mobile-prefer-renderer-scrollback.md and the rationale on
-  // `pendingByPaneKey` above. The IPC contract is: renderer awaits declare
-  // (capturing the returned gen), awaits pty:spawn, then registers its
-  // serializer locally and calls settle (echoing the gen). On spawn rejection
-  // or pane unmount before settle, renderer calls clear with the same gen.
+  // Pre-signal handshake handlers (declare→spawn→settle/clear); see docs/mobile-prefer-renderer-scrollback.md and `pendingByPaneKey` above.
   ipcMain.handle(
     'pty:declarePendingPaneSerializer',
     async (event, args: { paneKey?: unknown }): Promise<number> => {
@@ -5426,8 +4748,7 @@ export function registerPtyHandlers(
       }
       const ptyId = pendingPtyIdBySerializerGeneration.get(args.gen)
       const settledCurrentGeneration = settlePendingPaneSerializer(args.paneKey, args.gen)
-      // Why: the generation-to-PTY binding survives late teardown of a reused
-      // id; paneKey reverse maps are provider lifecycle state and may already be gone.
+      // Why: the generation-to-PTY binding survives late teardown of a reused id; paneKey reverse maps may already be gone.
       pendingPtyIdBySerializerGeneration.delete(args.gen)
       if (settledCurrentGeneration && ptyId) {
         rendererSerializerReadiness.markReady(ptyId)
@@ -5456,8 +4777,7 @@ export function registerPtyHandlers(
       ) {
         return
       }
-      // Why: remote-runtime panes do not pass through the local spawn
-      // cooperation gate, so their exact PTY id is the only readiness key.
+      // Why: remote-runtime panes skip the local spawn cooperation gate, so their exact PTY id is the only readiness key.
       rendererSerializerReadiness.markReady(args.ptyId)
     }
   )
@@ -5470,9 +4790,7 @@ export function registerHeadlessPtyRuntime(
   prepareClaudeAuth?: PrepareClaudeAuth,
   store?: Store
 ): void {
-  // Why: headless `orca serve` has no renderer window, but the runtime still
-  // needs the same PTY controller and provider listeners as desktop so remote
-  // clients can create, stream, inspect, and stop terminals.
+  // Why: headless `orca serve` has no renderer window but still needs the same PTY handlers so remote clients can drive terminals.
   const headlessWindow = {
     isDestroyed: () => true,
     webContents: {
diff --git a/src/main/ipc/repos-remote.test.ts b/src/main/ipc/repos-remote.test.ts
index eee64eff2eb..d7786b7ca4e 100644
--- a/src/main/ipc/repos-remote.test.ts
+++ b/src/main/ipc/repos-remote.test.ts
@@ -1,8 +1,4 @@
-/* eslint-disable max-lines -- Why: this file groups all repos IPC handler
-tests (addRemote, getBaseRefDefault envelope, searchBaseRefs SSH relay) so
-fixture setup and mock plumbing can be shared. Splitting by line count would
-duplicate the hoisted mocks and the `../git/repo` partial-real/partial-stub
-setup. */
+/* eslint-disable max-lines -- groups all repos IPC handler tests so shared fixture setup and hoisted mocks aren't duplicated */
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import { EventEmitter } from 'node:events'
 import { existsSync } from 'node:fs'
@@ -88,10 +84,7 @@ vi.mock('electron', () => ({
 }))
 
 vi.mock('../git/repo', async () => {
-  // Why: pull real implementations of pure helpers so SSH parity tests
-  // exercise the actual probe list and query sanitizer, not frozen copies.
-  // Drift in DEFAULT_BASE_REF_PROBES or normalizeRefSearchQuery now surfaces
-  // as test failure, not silent test-passes against stale behavior.
+  // Why: use real pure helpers so SSH parity tests catch drift in DEFAULT_BASE_REF_PROBES / normalizeRefSearchQuery.
   const actual = await vi.importActual<typeof RepoModule>('../git/repo')
   return {
     ...actual,
@@ -106,9 +99,7 @@ vi.mock('../git/repo', async () => {
 })
 
 vi.mock('../git/runner', async () => ({
-  // Why: keep the real env builders (nonInteractiveGitEnv,
-  // gitOptionalLocksDisabledEnv) so the clone regression test (#7652) asserts
-  // the actual guard's markers, not a mock echoing itself.
+  // Why: keep the real env builders so the clone regression test (#7652) asserts real markers, not a mock echoing itself.
   ...(await vi.importActual<typeof GitRunner>('../git/runner')),
   gitExecFileAsync: gitExecFileAsyncMock,
   gitExecFileAsyncBuffer: vi.fn(),
@@ -2127,9 +2118,7 @@ describe('repos:add + repos:clone', () => {
       destination
     })
 
-    // Without this env, a clone that needs GitHub auth makes Git Credential
-    // Manager pop its "Connect to GitHub" OAuth window on Windows and loop it
-    // when the network cannot complete the flow.
+    // Without this env, a clone needing auth makes Git Credential Manager pop and loop its OAuth window on Windows.
     expect(gitSpawnMock).toHaveBeenCalledWith(
       ['clone', '--progress', '--', 'https://example.com/orca.git', join(destination, 'orca')],
       expect.objectContaining({
@@ -2437,9 +2426,7 @@ describe('repos:getBaseRefDefault envelope', () => {
     mockStore.getRepos.mockReset().mockReturnValue([])
     mockStore.getRepo.mockReset()
     prepareLocalWorktreeRootForRepoMock.mockReset().mockResolvedValue(undefined)
-    // Reset exec to default: later SSH tests replace this with custom mocks, and
-    // without this reset any future test added to this block would inherit the
-    // last test's exec mock — latent fragility we guard against here.
+    // Reset exec so a newly added test doesn't inherit the previous test's exec mock.
     mockGitProvider.exec = vi.fn().mockResolvedValue({ stdout: '', stderr: '' })
     registerRepoHandlers(mockWindow as never, mockStore as never)
   })
@@ -2481,10 +2468,7 @@ describe('repos:getBaseRefDefault envelope', () => {
     expect(result.remoteCount).toBe(1)
   })
 
-  // Why: the SSH handler resolves default-ref and remote-count in parallel
-  // (Promise.all) so the order of calls into provider.exec is not stable.
-  // Dispatch on argv instead of `mockResolvedValueOnce` chains so tests remain
-  // independent of which Promise in the Promise.all resolves first.
+  // Why: the handler resolves default-ref and remote-count in parallel, so dispatch on argv (not call order) to stay stable.
   type ExecResponse = { stdout: string; stderr: string }
   type ExecRule = {
     matches: (argv: string[]) => boolean
@@ -2515,8 +2499,7 @@ describe('repos:getBaseRefDefault envelope', () => {
           matches: isSymbolicRef,
           respond: () => Promise.resolve({ stdout: 'refs/remotes/origin/main\n', stderr: '' })
         },
-        // The origin/HEAD target is verified before it is trusted, so the
-        // symbolic-ref result must also resolve via rev-parse.
+        // origin/HEAD is verified before trusted, so it must also resolve via rev-parse.
         {
           matches: isRevParseFor('refs/remotes/origin/main'),
           respond: () => Promise.resolve({ stdout: '', stderr: '' })
@@ -2551,8 +2534,7 @@ describe('repos:getBaseRefDefault envelope', () => {
           matches: isSymbolicRef,
           respond: () => Promise.resolve({ stdout: 'refs/remotes/origin/main\n', stderr: '' })
         },
-        // The origin/HEAD target is verified before it is trusted, so the
-        // symbolic-ref result must also resolve via rev-parse.
+        // origin/HEAD is verified before trusted, so it must also resolve via rev-parse.
         {
           matches: isRevParseFor('refs/remotes/origin/main'),
           respond: () => Promise.resolve({ stdout: '', stderr: '' })
@@ -2576,8 +2558,7 @@ describe('repos:getBaseRefDefault envelope', () => {
       remoteCount: number
     }
 
-    // Why: default detection must be independent of remote-count lookup.
-    // A failing count falls back to 0, but the default still resolves.
+    // Why: default detection is independent of remote-count; a failing count falls back to 0 while the default still resolves.
     expect(result.defaultBaseRef).toBe('origin/main')
     expect(result.remoteCount).toBe(0)
   })
@@ -2616,9 +2597,7 @@ describe('repos:getBaseRefDefault envelope', () => {
       remoteCount: number
     }
 
-    // Why: when symbolic-ref fails, the probe chain should find
-    // refs/remotes/origin/master and return 'origin/master', matching
-    // the local path's getDefaultBaseRefAsync behavior.
+    // Why: when symbolic-ref fails, the probe chain resolves origin/master, matching the local path.
     expect(result.defaultBaseRef).toBe('origin/master')
     expect(result.remoteCount).toBe(1)
   })
@@ -2711,8 +2690,7 @@ describe('repos:searchBaseRefs SSH relay', () => {
       query: '***'
     })
 
-    // Why: normalizeRefSearchQuery still strips glob metacharacters before
-    // building argv; the resulting empty query now intentionally lists refs.
+    // Why: glob metacharacters are stripped, so the empty query intentionally lists refs.
     const [argv] = mockGitProvider.exec.mock.calls.find(
       (call) => (call[0] as string[])[0] === 'for-each-ref'
     )!
@@ -2791,10 +2769,7 @@ describe('repos:searchBaseRefs SSH relay', () => {
   })
 
   it('sends the widened `**` argv so all remotes and slash-named branches are discoverable', async () => {
-    // Why: this is the core issue-624 behavior — the SSH path must glob all
-    // remotes, not just origin. The `**` globs additionally span ref segments
-    // so slash-named branches (`user/feature`) are found by a single-word
-    // query; a single `*` would not cross `/`.
+    // Why: SSH globs all remotes and `**` crosses `/` so slash-named branches match a single-word query (issue #624).
     mockGitProvider.exec = vi.fn().mockResolvedValue({ stdout: '', stderr: '' })
 
     mockStore.getRepo.mockReturnValue({
@@ -2822,11 +2797,7 @@ describe('repos:searchBaseRefs SSH relay', () => {
   })
 
   it('sends segmented argv for display-format queries like `upstream/main`', async () => {
-    // Why: guards against the SSH path drifting from the local path for
-    // multi-segment queries. The picker shows results as `<remote>/<branch>`
-    // and users retype that format; if the SSH argv reverts to a single
-    // `*<q>*` glob containing the literal `/`, SSH users silently see no
-    // matches for valid refs — the same shape of bug as issue #624.
+    // Why: a single `*<q>*` glob with a literal `/` makes SSH multi-segment queries silently match nothing (issue #624 shape).
     mockGitProvider.exec = vi.fn().mockResolvedValue({ stdout: '', stderr: '' })
 
     mockStore.getRepo.mockReturnValue({
@@ -2849,18 +2820,14 @@ describe('repos:searchBaseRefs SSH relay', () => {
     expect(segmentedArgv).toContain('refs/heads/*upstream*/*main*')
     expect(branchRootArgv).toContain('refs/remotes/*/upstream/main*')
     expect(branchRootArgv).toContain('refs/heads/upstream/main*')
-    // Regression guard: the literal slash must never appear inside a
-    // single segmented glob (would be `refs/remotes/*upstream/main*`),
-    // which fnmatch cannot match because `*` doesn't cross `/`.
+    // Regression guard: a literal slash must never appear inside a single segmented glob (`*` doesn't cross `/`).
     expect(segmentedArgv).not.toContain('refs/remotes/*upstream/main*/*')
     expect(segmentedArgv).not.toContain('refs/remotes/*/*upstream/main*')
     expect(mockGitProvider.exec).toHaveBeenCalledWith(['remote'], '/remote/repo')
   })
 
   it('parses NUL-delimited stdout and filters <remote>/HEAD pseudo-refs', async () => {
-    // Why: exercises the shared parseAndFilterSearchRefs pipeline end-to-end
-    // on the SSH path — confirms the HEAD filter works for any remote (not
-    // just origin) when results come from the relay.
+    // Why: confirms the HEAD filter works for any remote, not just origin, on the SSH path.
     const stdout = [
       'refs/remotes/origin/main\0origin/main',
       'refs/remotes/upstream/main\0upstream/main',
@@ -2901,9 +2868,7 @@ describe('repos:searchBaseRefs SSH relay', () => {
       query: 'main'
     })
 
-    // Why: transport failure must fall back to an empty result set — mirrors
-    // the local path's catch, so SSH users see "no matches" instead of a
-    // crashed picker when the relay drops.
+    // Why: transport failure falls back to an empty result set so the picker doesn't crash.
     expect(result).toEqual([])
   })
 
diff --git a/src/main/ipc/repos.ts b/src/main/ipc/repos.ts
index 007af79b5d2..54e440dba74 100644
--- a/src/main/ipc/repos.ts
+++ b/src/main/ipc/repos.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: repo IPC is intentionally centralized so SSH
-routing, clone lifecycle, and store persistence stay behind a single audited
-boundary. Splitting by line count would scatter tightly coupled repo behavior. */
+/* eslint-disable max-lines -- Why: repo IPC is centralized so SSH routing, clone lifecycle, and store persistence stay behind one audited boundary. */
 import type { BrowserWindow, IpcMainInvokeEvent } from 'electron'
 import { dialog, ipcMain } from 'electron'
 import { randomUUID } from 'node:crypto'
@@ -103,31 +101,15 @@ import { getGitCloneFailureMessage } from '../../shared/git-clone-failure-messag
 import { prepareLocalWorktreeRootForRepo } from '../worktree-root-preparation'
 import { runWithGitReadCacheInvalidation } from '../git/status'
 
-// Why: `method` answers "which entry point did the user take?", not "what did
-// they add?" — so the IPC the renderer invoked IS the method. We never send
-// the path, URL, or display name. `repos:create` collapses into
-// `folder_picker` because the user's entry was the folder picker, even
-// though main also `git init`s. `drag_drop` is reserved for a future call
-// site; no current renderer surface produces it.
-//
-// Why `isGitRepo`: low-cardinality, non-identifying git-vs-folder signal.
-// Callers pass it because they already have the git-detection result in scope
-// (avoids re-running git I/O here). Pass `undefined` when a call site genuinely
-// can't determine git-ness (e.g. some SSH/remote edges) — never default-guess
-// `false`. This replaced the now-removed `onboarding_completed.is_git_repo`,
-// which became meaningless once repo selection left onboarding (1.4.46).
+// Why: `method` is the IPC entry point the user took, not what they added (never path/URL/name); repos:create → 'folder_picker'.
+// Why: `isGitRepo` is a non-identifying git-vs-folder signal from the caller's detection; pass undefined when unknown, never default false.
+// Why: it replaced onboarding_completed.is_git_repo, which lost meaning once repo selection left onboarding (1.4.46).
 function emitRepoAdded(method: RepoMethod, alreadyExisted: boolean, isGitRepo?: boolean): void {
-  // Why: re-adding an existing repo (matched by path inside the handler)
-  // is not a new activation event. Suppressing the duplicate keeps the
-  // funnel honest and avoids inflating `repo_added` for users who
-  // re-pick the same folder.
+  // Why: re-adding an existing repo isn't a new activation; suppress so re-picking a folder doesn't inflate repo_added.
   if (alreadyExisted) {
     return
   }
-  // Why: cohort must read AFTER `store.addRepo()` lands so the just-added
-  // repo is counted — every call site below already emits post-addRepo, so
-  // `getCohortAtEmit()` here returns the user's Nth `repo_added` as `N`.
-  // See docs/onboarding-funnel-cohort-addendum.md §Read-vs-write ordering.
+  // Why: read cohort AFTER store.addRepo() so the just-added repo is counted (docs/onboarding-funnel-cohort-addendum.md §Read-vs-write ordering).
   const props = {
     method,
     ...(isGitRepo === undefined ? {} : { is_git_repo: isGitRepo }),
@@ -157,9 +139,7 @@ function alignRepoWithRequestedProject(
     if (!project?.providerIdentity || project.providerIdentity.provider !== 'github') {
       throw new Error('Imported folder does not match the selected project identity.')
     }
-    // Why: setup-on-host is an explicit user action for this project. When the
-    // folder lacks upstream metadata but the selected project has provider
-    // identity, stamp that identity so compatibility projection can merge it.
+    // Why: stamp the selected project's provider identity when the folder lacks upstream, so projection can merge it.
     const updated = store.updateRepo(repo.id, {
       upstream: {
         owner: project.providerIdentity.owner,
@@ -227,8 +207,7 @@ async function addLocalRepoFromPath(
       ? {
           externalWorktreeVisibility: 'hide' as const,
           externalWorktreeVisibilityLegacy: false,
-          // Why: new Add Project imports should become explicit ready host
-          // setups; `legacy-repo` is reserved for older records/projection.
+          // Why: new Add Project imports are explicit ready host setups; 'legacy-repo' is reserved for older records/projection.
           projectHostSetupMethod: 'imported-existing-folder' as const
         }
       : {})
@@ -404,12 +383,9 @@ async function cloneRemoteRepo(
   activeRemoteClone = metadata
   remoteCloneInFlightByPath.add(remoteCloneKey)
   try {
-    // Why: local clone creates the typed parent before spawning git. SSH clone
-    // must match that behavior or a fresh remote parent surfaces as spawn ENOENT.
+    // Why: match local clone by creating the parent first, or a fresh remote parent surfaces as spawn ENOENT.
     await fsProvider.createDir(trimmedDestination)
-    // Why: the SSH relay exposes argv-based git execution, not a shell. Use
-    // the repo folder name as the target so git creates it inside the chosen
-    // parent, and keep the same flag separator safety as local clone.
+    // Why: the SSH relay runs git argv, not a shell; use the repo folder name so git creates it under the chosen parent.
     await gitProvider.clone(
       ['clone', '--progress', '--', args.url.trim(), repoName],
       trimmedDestination,
@@ -615,8 +591,7 @@ async function resolveRemoteHomePath(connectionId: string, path: string): Promis
     const result = (await mux.request('session.resolveHome', { path })) as { resolvedPath: string }
     return result.resolvedPath
   } catch {
-    // Why: older relays may not support this yet; callers will surface the
-    // original path validation error instead of failing during resolution.
+    // Why: older relays may not support this; return the original path so callers surface their own validation error.
     return path
   }
 }
@@ -638,9 +613,7 @@ type ActiveRemoteCloneMetadata = {
   controller: AbortController
 }
 
-// Why: module-scoped so the abort handle survives window re-creation on macOS.
-// registerRepoHandlers is called again when a new BrowserWindow is created,
-// and a function-scoped variable would lose the reference to an in-flight clone.
+// Why: module-scoped so the abort handle survives macOS window re-creation, when registerRepoHandlers re-runs.
 let activeClone: ActiveCloneMetadata | null = null
 let activeRemoteClone: ActiveRemoteCloneMetadata | null = null
 let nextCloneGeneration = 1
@@ -923,8 +896,7 @@ async function cleanupOwnedCloneTarget(metadata: ActiveCloneMetadata): Promise<v
   if (latestCloneGenerationByPath.get(metadata.pathKey) !== metadata.generation) {
     return
   }
-  // Why: an immediate retry can attach a newer process to the same target
-  // before the aborted process closes; the old close handler must not delete it.
+  // Why: a fast retry may attach a newer process before the aborted one closes; the old close handler must not delete it.
   if (
     activeClone &&
     activeClone.process !== metadata.process &&
@@ -1120,8 +1092,7 @@ async function runNestedRepoScanForIpc(
 }
 
 export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): void {
-  // Remove any previously registered handlers so we can re-register them
-  // (e.g. when macOS re-activates the app and creates a new window).
+  // Remove previously registered handlers so we can re-register on macOS app re-activation (new window).
   ipcMain.removeHandler('repos:list')
   ipcMain.removeHandler('repos:add')
   ipcMain.removeHandler('repos:remove')
@@ -1172,9 +1143,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
     enrichMissingRepoGitRemoteIdentities(store, {
       onChanged: () => notifyReposChanged(mainWindow)
     })
-    // Why: username resolution spawns git/gh and must stay off this handler's
-    // synchronous path (issue #7225); the background pass notifies the
-    // renderer to re-list once values land.
+    // Why: username resolution spawns git/gh, so keep it off this sync handler (issue #7225); it re-lists when values land.
     enrichRepoGitUsernames(store, {
       onChanged: () => notifyReposChanged(mainWindow)
     })
@@ -1614,8 +1583,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
           }
           importedProjectIdsByRepoPath.set(normalizedImportRepoPath, repo.id)
           results.push({ path: repoPath, projectId: repo.id, status: 'imported' })
-          // Why: nested-repo import only reaches here after the isGitRepo /
-          // isGitRepoAsync guard above confirmed a git repo, so always `true`.
+          // Why: reaches here only after the isGitRepo guard above confirmed a git repo, so always true.
           emitRepoAdded('folder_picker', false, true)
         } catch (error) {
           results.push({
@@ -1708,9 +1676,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
     }
   )
 
-  // Creates a new repo or folder from scratch (orca#763). An empty initial
-  // commit is required for git repos so HEAD has a branch ref — Orca's
-  // worktree features all need one.
+  // Create a repo/folder from scratch (orca#763); git repos need an empty initial commit so HEAD has a branch ref for worktrees.
   ipcMain.handle(
     'repos:create',
     async (
@@ -1719,62 +1685,44 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
     ): Promise<{ repo: Repo } | { error: string }> => {
       const name = args.name?.trim() ?? ''
       const parentPath = args.parentPath?.trim() ?? ''
-      // Why: IPC input is untrusted — coerce to the narrow union so a bogus
-      // string (e.g. "x") can't skip git init yet persist as kind: "x" in the
-      // store. Mirrors the coercion in repos:add above.
+      // Why: IPC input is untrusted — coerce to the narrow union so a bogus kind can't skip git init yet persist in the store.
       const repoKind: 'git' | 'folder' = args.kind === 'folder' ? 'folder' : 'git'
 
       if (!name) {
         return { error: 'Name cannot be empty' }
       }
-      // Block slashes and ./.. so the name can't escape the chosen parent.
-      // The UI already disables submit in these cases; this guards direct IPC use.
+      // Block slashes and ./.. so the name can't escape the chosen parent (guards direct IPC use).
       if (/[\\/]/.test(name) || name === '.' || name === '..') {
         return { error: 'Name cannot contain slashes or be "." / ".."' }
       }
       if (!parentPath) {
         return { error: 'Parent directory is required' }
       }
-      // Why: blocks CWD-relative paths from slipping through the IPC boundary;
-      // the UI uses pickDirectory which returns absolute paths, this guards
-      // direct IPC use (and keeps targetPath stable across process cwd changes).
+      // Why: block CWD-relative paths at the IPC boundary — keeps targetPath stable across process cwd changes.
       if (!isAbsolute(parentPath)) {
         return { error: 'Parent directory must be an absolute path' }
       }
 
       const targetPath = join(parentPath, name)
 
-      // Dedup by path (same as repos:add) so a double-click on Create doesn't
-      // produce two sidebar entries pointing at the same folder. This is the
-      // first of three dedup checks; see the pre-addRepo check below for why
-      // the race matters even after this one passes.
+      // Dedup by path so a double-click on Create doesn't make two entries for one folder (first of three dedup checks).
       const existing = store.getRepos().find((r) => r.path === targetPath)
       if (existing) {
         emitRepoAdded('folder_picker', true, repoKind === 'git')
         return { repo: existing }
       }
 
-      // Empty pre-existing directories are allowed (e.g. one the user made in
-      // Finder first). Non-empty ones are rejected so we don't overwrite files.
+      // Empty pre-existing dirs are allowed (e.g. made in Finder first); non-empty ones are rejected so we don't overwrite files.
       let createdDir = false
       let targetExists = false
       try {
-        // Why: the name-first default points at ~/orca/projects, which may not
-        // exist yet on a fresh install; create only the parent before probing target.
+        // Why: the default parent (~/orca/projects) may not exist on a fresh install; create only the parent before probing the target.
         await mkdir(parentPath, { recursive: true })
         await access(targetPath)
         targetExists = true
       } catch (err) {
-        // Why: only ENOENT means "the path is free to use". Other codes
-        // (EACCES, ENOTDIR, EPERM, ELOOP, ...) mean something is in the way
-        // that mkdir can't fix — surface a precise error instead of falling
-        // through to mkdir and returning a misleading "Failed to create
-        // directory" message.
-        //
-        // Why the message fallback: fs.promises.access always attaches a
-        // NodeJS.ErrnoException code in production, but plain Error objects
-        // thrown in tests / non-Node contexts won't — treat a message that
-        // reads like ENOENT as one so we don't over-reject.
+        // Why: only ENOENT means the path is free; other codes are something mkdir can't fix, so surface a precise error.
+        // Why: tests/non-Node errors lack a code, so treat an ENOENT-looking message as ENOENT to avoid over-rejecting.
         const code =
           err && typeof err === 'object' && 'code' in err
             ? (err as NodeJS.ErrnoException).code
@@ -1797,9 +1745,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
             }
           }
         } catch (err) {
-          // Why: access succeeded but readdir failed — the path exists but we
-          // can't inspect it (e.g. it's a file, not a directory; or perms).
-          // mkdir would definitely fail here too, so return a distinct error.
+          // Why: access ok but readdir failed — path exists but isn't an inspectable dir (file or perms); return a distinct error.
           const message = err instanceof Error ? err.message : String(err)
           return { error: `Failed to read directory: ${message}` }
         }
@@ -1808,11 +1754,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
           await mkdir(targetPath, { recursive: false })
           createdDir = true
         } catch (err) {
-          // Why: EEXIST here means another concurrent repos:create for the
-          // same path won the mkdir race. If they already added the repo to
-          // the store, return that entry instead of a confusing error. This
-          // is the second dedup check; see the pre-addRepo check below for
-          // the full race explanation.
+          // Why: EEXIST means a concurrent repos:create won the mkdir race; return its store entry instead of a confusing error.
           const code =
             err && typeof err === 'object' && 'code' in err
               ? (err as NodeJS.ErrnoException).code
@@ -1830,9 +1772,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
       }
 
       if (repoKind === 'git') {
-        // Why: track which git step is running so the catch can attribute the
-        // failure correctly. The identity-hint regex is only meaningful during
-        // commit — git init itself never produces "Please tell me who you are".
+        // Why: track which git step ran so catch can attribute failure; the identity-hint regex only applies during commit.
         let step: 'init' | 'commit' = 'init'
         try {
           await gitExecFileAsync(['init'], { cwd: targetPath })
@@ -1841,12 +1781,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
             cwd: targetPath
           })
         } catch (err) {
-          // Only remove the directory if we made it. A pre-existing folder the
-          // user picked must survive so they can retry after fixing git config.
-          // Why: if we didn't make the directory but `git init` created `.git/`
-          // inside it, strip just `.git/` so the user's folder looks the way
-          // they left it. Retrying works either way, but leaving a half-init'd
-          // repo behind is confusing if they choose to skip the retry.
+          // Only rm the dir if we made it (pre-existing folders must survive retry); otherwise strip just the .git/ that git init created.
           if (createdDir) {
             await rm(targetPath, { recursive: true, force: true }).catch(() => {})
           } else if (step === 'commit') {
@@ -1870,16 +1805,10 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
         }
       }
 
-      // Why: ipcMain.handle doesn't serialize concurrent calls; re-running the
-      // dedup lookup here closes the window between the first check and
-      // addRepo. A second repos:create for the same path that raced past the
-      // initial dedup now returns the entry the first call persisted.
+      // Why: ipcMain.handle doesn't serialize calls, so re-check dedup here to close the race between the first check and addRepo.
       const raceWinner = store.getRepos().find((r) => r.path === targetPath)
       if (raceWinner) {
-        // Why: do NOT rm even if this invocation created the directory — the
-        // other invocation is using it. Leaking a freshly-made empty folder on
-        // a rare race is strictly safer than deleting a directory the winning
-        // call (and the user) now owns.
+        // Why: don't rm even if we made the dir — the race winner owns it; leaking an empty folder beats deleting a dir in use.
         emitRepoAdded('folder_picker', true, repoKind === 'git')
         return { repo: raceWinner }
       }
@@ -1906,8 +1835,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
       await prepareLocalWorktreeRootForRepo(store, repo)
       invalidateAuthorizedRootsCache()
       notifyReposChanged(mainWindow)
-      // Why: `repos:create` git-inits when kind is 'git', so `repoKind` is the
-      // true git-vs-folder signal for the just-created project.
+      // Why: repos:create git-inits when kind is 'git', so repoKind is the true git-vs-folder signal.
       emitRepoAdded('folder_picker', false, repoKind === 'git')
       return { repo }
     }
@@ -1916,9 +1844,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
   ipcMain.handle(
     'repos:reorder',
     (_event, args: { orderedIds: string[] }): { status: 'applied' | 'rejected' } => {
-      // Why: validate at the IPC boundary — IPC input is untrusted and a
-      // permutation mismatch means the renderer's drag was stale relative to
-      // a concurrent add/remove. Reject so the renderer can resync.
+      // Why: a permutation mismatch means the renderer's drag was stale vs a concurrent add/remove; reject so it can resync.
       const ids = Array.isArray(args?.orderedIds) ? args.orderedIds : []
       const applied = store.reorderRepos(ids)
       if (applied) {
@@ -1955,9 +1881,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
     notifyReposChanged(mainWindow)
   })
 
-  // Why: forget a project on a single execution host without disturbing the
-  // same repo id on other hosts (local or a re-added SSH target). Used by the
-  // SSH-workspace forget flow when a host is removed/disconnected.
+  // Why: forget a project on one execution host without disturbing the same repo id on other hosts (SSH-workspace forget flow).
   ipcMain.handle(
     'repos:removeForHost',
     async (_event, args: { repoId: string; hostId: string }) => {
@@ -2006,12 +1930,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
         }
       }
     ) => {
-      // Why: validate the persisted preference string at the IPC boundary
-      // — the TypeScript signature is erased at runtime, and a preload
-      // version skew or renderer bug could otherwise persist a garbage
-      // string that silently collapses to 'auto' in `resolveIssueSource`
-      // (see gh-utils.ts#resolveIssueSource). Strip rather than throw so
-      // other valid fields in the same call still persist.
+      // Why: TS is erased at runtime, so a garbage preference would silently collapse to 'auto' in resolveIssueSource; strip it, keeping other fields.
       const updates = { ...args.updates }
       if (
         'issueSourcePreference' in updates &&
@@ -2031,12 +1950,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
       ) {
         delete updates.forkSyncMode
       }
-      // Why: `symlinkPaths` is consumed by worktree path materialization, which
-      // calls `.trim()` on each entry. A renderer bug or preload-version skew
-      // that persists a non-`string[]` value (e.g. `[42, null]`, a bare
-      // string) would throw inside the worktree-create path with no UI
-      // signal. Strip invalid shapes at the boundary the same way
-      // `issueSourcePreference` is validated above.
+      // Why: worktree materialization calls .trim() per entry, so strip non-string[] at the boundary to avoid a silent throw later.
       if ('symlinkPaths' in updates && updates.symlinkPaths !== undefined) {
         const v = updates.symlinkPaths as unknown
         if (!Array.isArray(v) || !v.every((e) => typeof e === 'string')) {
@@ -2115,8 +2029,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
           delete updates.importedExternalWorktreePaths
         }
       }
-      // Why: null is the transport sentinel for clearing Source Control AI.
-      // Other invalid fields are deleted; this one must flow as undefined.
+      // Why: null is the transport sentinel for clearing Source Control AI, so flow it through as undefined instead of deleting.
       if ('sourceControlAi' in updates && updates.sourceControlAi === null) {
         updates.sourceControlAi = undefined
       } else if ('sourceControlAi' in updates && updates.sourceControlAi !== undefined) {
@@ -2142,10 +2055,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
   )
 
   // ── Sparse presets ─────────────────────────────────────────────
-  // Why: presets are repo-scoped reusable directory lists used by the
-  // new-workspace composer. Persisted via Store and broadcast back to the
-  // renderer so any open composer reflects new/edited/deleted presets
-  // immediately.
+  // Why: repo-scoped reusable directory lists for the new-workspace composer; broadcast on change so open composers refresh.
 
   ipcMain.handle('sparsePresets:list', (_event, args: { repoId: string }) => {
     return store.getSparsePresets(args.repoId)
@@ -2210,13 +2120,10 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
     return result.filePaths
   })
 
-  // Why: pickDirectory is a generic "choose a folder" picker, separate from
-  // pickFolder which is specifically the "add project" flow. Clone needs a
-  // destination directory that may not be a git repo yet.
+  // Why: generic folder picker, separate from pickFolder's add-project flow; a clone destination may not be a git repo yet.
   ipcMain.handle('repos:pickDirectory', async () => {
     const result = await dialog.showOpenDialog(mainWindow, {
-      // Why: macOS can materialize typed partial paths when directory creation
-      // is enabled; clone/create actions already create the final path on submit.
+      // Why: macOS materializes typed partial paths with directory creation on; clone/create make the final path on submit.
       properties: ['openDirectory']
     })
     if (result.canceled || result.filePaths.length === 0) {
@@ -2242,10 +2149,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
   ipcMain.handle(
     'repos:clone',
     async (_event, args: { url: string; destination: string }): Promise<Repo> => {
-      // Why: the user picks a parent directory (e.g. ~/projects) and we derive
-      // the repo folder name from the URL (e.g. "orca" from .../orca.git).
-      // This matches the default git clone behavior where the last path segment
-      // of the URL becomes the directory name.
+      // Why: derive the repo folder name from the URL's last segment, matching default git clone behavior.
       const clonePath = deriveValidatedClonePath(args)
       const clonePathKey = getClonePathComparisonKey(clonePath)
       return runWithClonePathLock(clonePathKey, async () => {
@@ -2258,35 +2162,21 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
           emitRepoAdded('clone_url', true, true)
           return existingAfterPendingClone
         }
-        // Why: gitSpawn uses args.destination as cwd, so it must exist before
-        // spawn — fresh installs may have a defaulted parent dir that does not
-        // exist yet (e.g. ~/orca). recursive: true is a no-op when present.
+        // Why: gitSpawn cwd is args.destination, so it must exist before spawn (fresh installs may lack the defaulted parent).
         await mkdir(args.destination, { recursive: true })
         const claimedTarget = await claimCloneTarget(clonePath)
 
-        // Why: use spawn instead of execFile so there is no maxBuffer limit.
-        // git clone writes progress to stderr which can exceed Node's default
-        // 1 MB buffer on large or submodule-heavy repos. We only keep the tail
-        // of stderr for error reporting and discard stdout entirely.
-        // Why: use --progress to force git to emit progress even when stderr
-        // is not a TTY. Without it, git suppresses progress output when piped.
+        // Why: spawn (not execFile) avoids the maxBuffer limit — clone progress on stderr can exceed Node's 1 MB default.
+        // Why: --progress forces git to emit progress even when stderr isn't a TTY.
         const cloneMetadataRef: { current: ActiveCloneMetadata | null } = { current: null }
         await new Promise<void>((resolve, reject) => {
-          // Why: clone destination may be a WSL path (e.g. user picks a WSL
-          // directory). Use the parent destination as the cwd so the runner
-          // detects WSL and routes through wsl.exe.
-          // Why: use the '--' separator to isolate the URL argument and prevent
-          // malicious URLs from being interpreted as git flags (command injection).
+          // Why: use the parent destination as cwd so the runner detects a WSL path and routes through wsl.exe.
+          // Why: '--' isolates the URL so a malicious URL can't be read as git flags (command injection).
           let proc: ReturnType<typeof gitSpawn>
           try {
             proc = gitSpawn(['clone', '--progress', '--', args.url, clonePath], {
               cwd: args.destination,
-              // Why: without the non-interactive guard, a clone that needs
-              // GitHub auth makes Git Credential Manager pop its "Connect to
-              // GitHub" OAuth window on Windows; in a network-restricted env the
-              // browser/device flow can never complete and git's credential
-              // retry re-pops it (issue #7652). Fail fast with a clear error and
-              // let Orca's non-intrusive GitHub state stand instead.
+              // Why: without this, an auth-needing clone pops Git Credential Manager's OAuth window on Windows, unclosable in a restricted env (issue #7652).
               env: nonInteractiveGitEnv(),
               stdio: ['ignore', 'ignore', 'pipe']
             })
@@ -2318,8 +2208,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
             const text = chunk.toString()
             stderrTail = (stderrTail + text).slice(-4096)
 
-            // Why: git progress lines use \r to overwrite in-place; parse
-            // fragments the same way for local and SSH clone flows.
+            // Why: git progress lines use \r to overwrite in-place; parse fragments the same as SSH clone.
             emitCloneProgressFromText(mainWindow, text)
           })
 
@@ -2332,18 +2221,14 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
               return
             }
             settled = true
-            // Why: only clear the ref if it still points to this process.
-            // A quick abort-and-retry can reassign activeClone to a new
-            // spawn before this handler fires, and nulling it would make the
-            // new clone unabortable.
+            // Why: only null activeClone if it still points to this proc; abort-and-retry may have reassigned it, stranding the new clone.
             if (activeClone?.process === proc) {
               activeClone = null
             }
 
             const cloneSucceeded = !err && code === 0 && !signal
             if (!cloneSucceeded) {
-              // Why: only the process that created this target may remove it,
-              // and only after git reports the clone did not complete.
+              // Why: only the process that created this target may remove it, and only after git reports failure.
               await cleanupOwnedCloneTarget(metadata)
             }
             if (metadata.abortRequested && !cloneSucceeded) {
@@ -2376,10 +2261,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
         })
 
         try {
-          // Why: check after clone (not before) because the path didn't exist
-          // before cloning. But if the user somehow had a folder repo at this path
-          // that git clone succeeded into (empty dir), reuse that entry and upgrade
-          // its kind to 'git' instead of creating a duplicate.
+          // Why: check after clone (path didn't exist before); reuse+upgrade a folder repo clone landed into instead of duplicating.
           const existing = store
             .getRepos()
             .find((r) => getClonePathComparisonKey(r.path) === clonePathKey)
@@ -2449,8 +2331,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
     if (!repo || isFolderRepo(repo)) {
       return ''
     }
-    // Why: remote repos have their git config on the remote host. Keep this
-    // to explicit username config; user.email/name are author identity.
+    // Why: remote repos keep their git config on the remote host, so resolve the username there.
     if (repo.connectionId) {
       const provider = getSshGitProvider(repo.connectionId)
       if (!provider) {
@@ -2469,30 +2350,16 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
     ): Promise<BaseRefDefaultResult> => {
       const repo = getRepoForExecutionHost(store, args.repoId, args.hostId)
       if (!repo || isFolderRepo(repo)) {
-        // Why: folder-mode repos have no git state to resolve a base ref from.
-        // Return null + 0 so the renderer can decline to use a fabricated default
-        // and suppress the multi-remote hint.
+        // Why: folder repos have no git state for a base ref; return null + 0 so the renderer skips a fabricated default.
         return { defaultBaseRef: null, remoteCount: 0 }
       }
-      // Why: remote repos need the relay to resolve symbolic-ref on the
-      // remote host where the git data lives.
+      // Why: remote repos need the relay to resolve symbolic-ref where the git data lives.
       if (repo.connectionId) {
         const provider = getSshGitProvider(repo.connectionId)
         if (!provider) {
           return { defaultBaseRef: null, remoteCount: 0 }
         }
-        // Why: run default-ref resolution and remote-count concurrently to
-        // match the local path's latency characteristics (see Promise.all
-        // below). The two lookups are independent — neither depends on the
-        // other's result — so serializing them only adds SSH round-trip
-        // latency on slow relays.
-        //
-        // Why: delegate to the shared resolveDefaultBaseRefViaExec so SSH and
-        // local repos return identical defaults for equivalent states. We
-        // log in the exec callback for the symbolic-ref call to preserve the
-        // SSH-specific transport-failure diagnostic (connection drops,
-        // permission issues) that the shared helper otherwise swallows
-        // together with the expected "origin/HEAD unset" non-zero exit.
+        // Why: delegate to shared resolveDefaultBaseRefViaExec; log symbolic-ref failures here to keep the SSH transport diagnostic it otherwise swallows.
         const resolveDefault = async (): Promise<string | null> => {
           return resolveDefaultBaseRefViaExec(async (argv) => {
             try {
@@ -2514,8 +2381,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
             const remotesResult = await provider.exec(['remote'], repo.path)
             return parseRemoteCount(remotesResult.stdout)
           } catch (err) {
-            // Why: fall back to 0 (the "unknown / do not render the multi-remote
-            // hint" sentinel). Log so diagnostic signal isn't lost.
+            // Why: 0 = unknown sentinel that suppresses the multi-remote hint.
             console.warn('[repos:getBaseRefDefault] SSH git remote count failed', {
               path: repo.path,
               err
@@ -2530,9 +2396,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
         ])
         return { defaultBaseRef, remoteCount }
       }
-      // Why: compute default and remote count independently. A failure
-      // counting remotes must not break default detection. Run in parallel
-      // since the two lookups don't depend on each other.
+      // Why: run in parallel; a remote-count failure must not break default detection.
       const [defaultBaseRef, remoteCount] = await Promise.all([
         getBaseRefDefault(repo.path),
         getRemoteCount(repo.path)
@@ -2580,13 +2444,10 @@ async function searchBaseRefDetailsForRepo(
     if (!provider) {
       return []
     }
-    // Why: mirror the local path's sanitization (normalizeRefSearchQuery
-    // in ../git/repo.ts) — strip glob metacharacters to prevent glob
-    // injection via the SSH branch while preserving empty-query branch lists.
+    // Why: strip glob metacharacters to prevent glob injection (mirrors local normalizeRefSearchQuery).
     const normalizedQuery = normalizeRefSearchQuery(args.query)
     try {
-      // Why: argv (including the two-remote-glob rationale) lives in
-      // buildSearchBaseRefsArgv so the SSH and local paths cannot drift.
+      // Why: argv lives in buildSearchBaseRefsArgv so SSH and local paths cannot drift.
       const remotesResult = await provider.exec(['remote'], repo.path).catch(() => ({ stdout: '' }))
       const remotes = remotesResult.stdout
         .split('\n')
@@ -2620,10 +2481,7 @@ async function searchBaseRefDetailsForRepo(
           isForEachRefExcludeUnsupportedError
         )
       }
-      // Why: delegate the NUL-parse + HEAD filter + dedup + limit pipeline
-      // to the shared helper so the SSH and local paths cannot diverge.
-      // See parseAndFilterSearchRefs in ../git/repo.ts for the dedup +
-      // HEAD-filter rationale.
+      // Why: delegate the parse/filter/dedup/limit pipeline to the shared helper so SSH and local paths cannot diverge.
       const searchTokens = normalizedQuery.split('/').filter((token) => token.length > 0)
       if (searchTokens.length > 1) {
         const results = await Promise.all([runSearch('segmented'), runSearch('branchRoot')])
@@ -2652,8 +2510,7 @@ function getRepoForExecutionHost(
   if (!hostId) {
     return store.getRepo(repoId) ?? null
   }
-  // Why: repo ids can collide across local and SSH hosts; base-ref reads must
-  // use the same host selected by the Settings pane as the subsequent write.
+  // Why: repo ids can collide across local and SSH hosts; read must use the same host the Settings pane selected for the write.
   return (
     store
       .getRepos()
diff --git a/src/main/ipc/ssh-browse.ts b/src/main/ipc/ssh-browse.ts
index 2729cd59ab7..964c877a557 100644
--- a/src/main/ipc/ssh-browse.ts
+++ b/src/main/ipc/ssh-browse.ts
@@ -10,23 +10,10 @@ export type RemoteDirEntry = {
 
 const SSH_BROWSE_TIMEOUT_MS = 15_000
 
-// Why: a POSIX login shell that can't find powershell.exe exits 127 (the POSIX
-// "command not found" convention, identical across sh/bash/zsh and locales). It's
-// the locale-independent signal that the Windows fallback never actually ran, so
-// the original POSIX failure — not the doomed retry — is the real error.
-//
-// Note: cmd.exe's ERRORLEVEL for an unrecognized command is 9009, but that value
-// never crosses cmd.exe's process boundary. sshd forwards cmd.exe's *process* exit
-// code, which is 1 — verified on real Windows OpenSSH + cmd.exe over both the ssh2
-// and system-ssh transports. So a Windows host rejecting Orca's POSIX `exec`
-// wrapper is detected by "the remote command ran and exited non-zero"
-// (RemoteBrowseError), not by a magic exit code or localized stderr text.
+// Why: 127 = POSIX "command not found" (locale-independent) — the Windows fallback never ran, so the original POSIX error is the real one.
 const POSIX_COMMAND_NOT_FOUND_EXIT = 127
 
-// Carries the raw exit code so the fallback can (a) recognize that the remote
-// command actually ran and failed — the locale-independent trigger for the
-// Windows retry — and (b) tell a POSIX "powershell.exe not found" (127) apart
-// from a genuine PowerShell error, without parsing localized shell prose.
+// Carries the raw exit code so the fallback can distinguish 127 (no powershell.exe → not Windows) from a genuine PowerShell error.
 class RemoteBrowseError extends Error {
   constructor(
     message: string,
@@ -37,10 +24,7 @@ class RemoteBrowseError extends Error {
   }
 }
 
-// Why: the relay's fs.readDir enforces workspace root ACLs, which aren't
-// registered until a repo is added. This handler uses a raw SSH exec channel
-// to list directories, allowing the user to browse the remote filesystem
-// during the "add remote project" flow before any roots exist.
+// Why: relay fs.readDir needs workspace-root ACLs that don't exist until a repo is added, so browse over raw SSH exec.
 export function registerSshBrowseHandler(
   getConnectionManager: () => SshConnectionManager | null
 ): void {
@@ -64,22 +48,14 @@ export function registerSshBrowseHandler(
       try {
         return await browseWithPosixShell(conn, args.dirPath)
       } catch (posixError) {
-        // Why: a Windows login shell (cmd.exe/PowerShell) rejects Orca's POSIX
-        // `exec` wrapper, and the only locale-independent signal for that is "the
-        // remote command executed and exited non-zero" (RemoteBrowseError). Its
-        // stderr prose is localized, and cmd.exe's 9009 ERRORLEVEL never reaches
-        // us (sshd forwards process exit 1). Transport errors/timeouts aren't
-        // RemoteBrowseErrors, so a dropped connection is never retried as Windows.
+        // Why: only a RemoteBrowseError (ran, non-zero exit) signals a Windows shell; don't retry transport errors/timeouts as Windows.
         if (!(posixError instanceof RemoteBrowseError)) {
           throw posixError
         }
         try {
           return await browseWithWindowsPowerShell(conn, args.dirPath)
         } catch (fallbackError) {
-          // Why: if the login shell couldn't find powershell.exe (exit 127) the
-          // host isn't Windows — surface the original POSIX failure rather than a
-          // misleading "powershell.exe: not found". Otherwise PowerShell genuinely
-          // ran and its error (e.g. "Cannot find path") is the real cause.
+          // Why: exit 127 (no powershell.exe) → host isn't Windows, surface the original POSIX failure; otherwise PowerShell's own error is the real cause.
           throw isPosixCommandNotFound(fallbackError) ? posixError : fallbackError
         }
       }
@@ -93,13 +69,7 @@ function browseWithPosixShell(
   conn: SshBrowseConnection,
   dirPath: string
 ): Promise<{ entries: RemoteDirEntry[]; resolvedPath: string }> {
-  // Why: using one line per entry preserves filenames containing spaces.
-  // `command ls` bypasses user aliases/functions like `ls='eza ...'`.
-  // The -1 flag outputs one entry per line. The -p flag appends / to directories.
-  // We resolve ~ and get the absolute path via `cd <path> && pwd`.
-  // `cd` and `ls` are chained with `&&` so a failing `ls` (e.g. permission
-  // denied after a readable `cd ... && pwd`) propagates as a non-zero exit
-  // code rather than being indistinguishable from an empty directory.
+  // Why: `command ls` skips aliases; `&&` makes a failing ls exit non-zero (not look empty); -1Ap = one-per-line + trailing / on dirs.
   return runBrowseCommand(conn, `cd ${shellEscape(dirPath)} && pwd && command ls -1Ap`)
 }
 
@@ -109,17 +79,12 @@ function browseWithWindowsPowerShell(
 ): Promise<{ entries: RemoteDirEntry[]; resolvedPath: string }> {
   const script = [
     "$ErrorActionPreference = 'Stop'",
-    // Why: Windows PowerShell 5.1 writes redirected stdout in the legacy OEM
-    // code page, but runBrowseCommand decodes as UTF-8; pin UTF-8 output so
-    // non-ASCII names (e.g. C:\Users\José, CJK, Cyrillic) don't come back mojibake.
+    // Why: PowerShell 5.1 emits redirected stdout in the OEM code page; pin UTF-8 so non-ASCII names aren't mojibake.
     '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8',
     `$dir = ${powerShellPathExpression(dirPath)}`,
     'Set-Location -LiteralPath $dir',
     '$resolved = (Get-Location).ProviderPath',
-    // Why: the renderer's parentPath/joinPath only split on `/`, so a native
-    // backslash path (C:\Users\alice) breaks "Up" and mixes separators. Emit a
-    // forward-slash resolvedPath (matching the POSIX branch) while keeping the
-    // native $resolved for Get-ChildItem -LiteralPath.
+    // Why: the renderer's parentPath/joinPath split only on `/`, so emit a forward-slash resolvedPath while keeping native $resolved for Get-ChildItem.
     "Write-Output ($resolved -replace '\\\\', '/')",
     'Get-ChildItem -LiteralPath $resolved -Force | ForEach-Object {',
     "  if ($_.PSIsContainer) { Write-Output ($_.Name + '/') } else { Write-Output $_.Name }",
@@ -176,9 +141,7 @@ async function runBrowseCommand(
       }
     }
     const onTimeout = (): void => {
-      // Why: remote browsing runs before a relay workspace root exists, so
-      // it cannot rely on relay request deadlines. Bound this raw exec
-      // channel directly to keep Add Remote Project from hanging forever.
+      // Why: no relay deadline exists during add-project browsing, so bound this raw exec channel or Add Remote Project hangs forever.
       rejectOnce(new Error('Remote directory listing timed out'))
       closeChannel()
     }
@@ -197,8 +160,7 @@ async function runBrowseCommand(
     const onStderrData = (data: Buffer): void => {
       stderr += data.toString()
     }
-    // `exit` fires before `close`; capture the code so we can distinguish
-    // a failed `ls` that still produced `pwd` output from an empty listing.
+    // `exit` fires before `close`; capture the code to tell a failed `ls` (that still printed `pwd`) from an empty listing.
     const onExit = (code: number | null): void => {
       exitCode = code
     }
@@ -206,13 +168,7 @@ async function runBrowseCommand(
       rejectOnce(error)
     }
     const onClose = (): void => {
-      // A null exitCode means the server closed the channel without
-      // sending an exit-status message (or signalled termination). We
-      // can't assume success — falling back to "empty stdout = empty
-      // directory" is exactly the bug the exit-code branch was added to
-      // fix. Treat any non-zero OR null exit as a failure when stderr
-      // has content, and otherwise require stdout to contain at least
-      // the resolved `pwd` line before accepting the result.
+      // Why: a null exitCode (channel closed without exit status) isn't success; don't treat empty stdout as an empty dir.
       if (exitCode !== 0) {
         const msg =
           stderr.trim() ||
@@ -227,9 +183,7 @@ async function runBrowseCommand(
         return
       }
 
-      // Why: Windows OpenSSH exec emits CRLF, so split on \r?\n — otherwise a
-      // trailing \r defeats the endsWith('/') dir check and leaves a stray CR
-      // in every name.
+      // Why: Windows OpenSSH exec emits CRLF; split on \r?\n so a trailing \r doesn't defeat the endsWith('/') dir check or leave a stray CR in names.
       const lines = stdout.trim().split(/\r?\n/)
       if (lines.length === 0) {
         rejectOnce(new Error('Empty response from remote'))
@@ -266,8 +220,7 @@ async function runBrowseCommand(
     channel.stderr.on('data', onStderrData)
     channel.on('exit', onExit)
     channel.on('close', onClose)
-    // Why: SSH exec streams emit `error` on transport loss; without a
-    // scoped listener, a disappearing remote can become process-fatal.
+    // Why: SSH exec streams emit `error` on transport loss; without a scoped listener a disappearing remote can become process-fatal.
     channel.on('error', onError)
     channel.stderr.on('error', onError)
     timeout = setTimeout(onTimeout, SSH_BROWSE_TIMEOUT_MS)
@@ -277,17 +230,12 @@ async function runBrowseCommand(
   })
 }
 
-// Why: a POSIX login shell that can't find powershell.exe exits 127, marking the
-// Windows fallback as "never ran" — the host isn't Windows, so the original POSIX
-// failure, not the doomed retry, is the error worth surfacing.
+// Why: exit 127 means powershell.exe wasn't found — the host isn't Windows, so surface the original POSIX failure instead.
 function isPosixCommandNotFound(error: unknown): boolean {
   return error instanceof RemoteBrowseError && error.exitCode === POSIX_COMMAND_NOT_FOUND_EXIT
 }
 
-// Why: prevent shell injection in the directory path. Single-quote wrapping
-// with escaped internal single quotes is the safest approach for sh/bash.
-// Tilde must be expanded by the shell, so paths starting with ~ use $HOME
-// substitution instead of literal quoting (single quotes suppress expansion).
+// Why: single-quote to block shell injection; ~ needs $HOME since single quotes suppress tilde expansion.
 function shellEscape(s: string): string {
   if (s === '~') {
     return '"$HOME"'
@@ -312,12 +260,7 @@ function powerShellPathExpression(s: string): string {
   return powerShellLiteral(normalizeWindowsDrivePath(s))
 }
 
-// Why: browse emits forward-slash Windows paths, so the renderer rebuilds them
-// with POSIX helpers — the breadcrumb prepends a spurious leading '/' before the
-// drive (/C:/Users) and "Up" from a first-level dir yields a bare drive letter
-// (C:). Both are wrong for Set-Location: a leading '/' means the current drive's
-// root, and 'C:' is drive-relative (the process cwd), not 'C:\'. Normalize both
-// back to a rooted drive path here so navigation lands where the user clicked.
+// Why: renderer's POSIX path rebuild yields '/C:/…' or bare 'C:' (drive-relative), both mis-resolved by Set-Location; re-root to a proper drive path.
 function normalizeWindowsDrivePath(s: string): string {
   const stripped = s.replace(/^\/(?=[A-Za-z]:(?:[/\\]|$))/, '')
   return /^[A-Za-z]:$/.test(stripped) ? `${stripped}/` : stripped
diff --git a/src/main/ipc/ssh.ts b/src/main/ipc/ssh.ts
index ee2c0752c28..d1c3e51c3fd 100644
--- a/src/main/ipc/ssh.ts
+++ b/src/main/ipc/ssh.ts
@@ -1,5 +1,4 @@
-/* oxlint-disable max-lines -- Why: co-locates SSH IPC handlers, port-forward
-broadcasting, and session lifecycle in one file to keep the data flow obvious. */
+/* oxlint-disable max-lines -- Why: co-locates SSH IPC handlers, port-forward broadcasting, and session lifecycle to keep the data flow obvious. */
 import { ipcMain, powerMonitor, type BrowserWindow } from 'electron'
 import type { Store } from '../persistence'
 import { SshConnectionStore } from '../ssh/ssh-connection-store'
@@ -71,9 +70,7 @@ const SSH_IPC_CHANNELS = [
   'ssh:listDetectedPorts'
 ] as const
 
-// Why: connection callbacks are process-lifetime; keeping this set outside
-// registerSshHandlers prevents in-flight connects from splitting credential
-// tracking when a BrowserWindow is recreated.
+// Why: keep this outside registerSshHandlers so a BrowserWindow recreation mid-connect doesn't split credential tracking.
 const credentialRequestedForTarget = new Set<string>()
 
 function getCurrentMainWindow(): BrowserWindow | null {
@@ -113,15 +110,12 @@ export async function removeRegisteredSshTarget(targetId: string): Promise<void>
   if (!sshStore) {
     return
   }
-  // Why: removing a target is destructive — dispose() (not detach()) so the
-  // relay shuts down and remote PTY leases are terminated rather than preserved
-  // for a reattach to a target that will no longer exist.
+  // Why: removal is destructive — dispose() (not detach()) so the relay shuts down and remote PTY leases are terminated, not preserved for a reattach.
   await disposeActiveSshSession(targetId)
   try {
     await connectionManager?.disconnect(targetId)
   } catch (err) {
-    // Why: a failed disconnect must not block metadata removal; otherwise the
-    // target lingers in the store and its leases are never cleaned up.
+    // Why: a failed disconnect must not block metadata removal, else the target lingers in the store with uncleaned leases.
     console.warn(
       `[ssh] Failed to disconnect removed target ${targetId}: ${err instanceof Error ? err.message : String(err)}`
     )
@@ -130,9 +124,7 @@ export async function removeRegisteredSshTarget(targetId: string): Promise<void>
   sshStore.removeTarget(targetId)
 }
 
-// Why: one session per SSH target encapsulates the entire relay lifecycle
-// (multiplexer, providers, abort controller, state machine). Eliminates the
-// scattered Maps/Sets that previously tracked this state independently.
+// One session per SSH target owns the whole relay lifecycle (mux, providers, abort controller, state machine).
 const activeSessions = new Map<string, SshRelaySession>()
 
 export function getActiveSshAiVaultHostInfo(targetId: string): SshRelayAiVaultHostInfo | null {
@@ -168,8 +160,7 @@ async function teardownActiveSshSession(
   if (!session) {
     return
   }
-  // Why: await port teardown so local listeners are fully released before
-  // disconnect/remove completes; otherwise immediate reconnect can hit EADDRINUSE.
+  // Why: await port teardown so local listeners are released before disconnect/remove completes, else an immediate reconnect hits EADDRINUSE.
   await portForwardManager?.removeAllForwards(targetId)
   teardown(session)
   activeSessions.delete(targetId)
@@ -181,31 +172,16 @@ function relayGracePeriodForTarget(target: SshTarget | null | undefined): number
   return target?.relayGracePeriodSeconds
 }
 
-// Why: multiple renderer tabs for the same SSH target can fire ssh:connect
-// concurrently. Without serialization, the second call interleaves with the
-// first — both see no existing session, both create one, and the first one
-// leaks. This map holds the in-flight connect promise so the second call
-// awaits the first rather than racing.
+// Why: concurrent ssh:connect from multiple tabs would each create a session (leaking the first); hold the in-flight promise so the second awaits it.
 const connectInFlight = new Map<string, Promise<SshConnectionState>>()
 
-// Why: reset tears down and force-stops the relay, then disconnects SSH.
-// Publish that lifecycle so new connects and duplicate resets cannot race it.
+// Why: publish reset's teardown/force-stop/disconnect lifecycle so new connects and duplicate resets can't race it.
 const resetRelayInFlight = new Map<string, Promise<void>>()
 
-// Why: ssh:testConnection calls connect() then disconnect(), which fires
-// state-change events to the renderer. This causes worktree cards to briefly
-// flash "connected" then "disconnected". Suppressing broadcasts during tests
-// avoids that visual glitch.
+// Why: ssh:testConnection connects then disconnects; suppressing broadcasts during the test avoids worktree cards flashing connected → disconnected.
 const testingTargets = new Set<string>()
 
-// Why: when a relay channel keeps dying (e.g. a stale --connect bridge keeps
-// being replaced, a remote-side bug closes the channel right after handshake,
-// or a mismatched relay binary refuses every handshake), the unguarded
-// _onRelayLost handler reconnects as fast as the network allows, hammering
-// both the local main process and the remote sshd in a tight loop. Track
-// per-target reconnect attempts and apply exponential backoff so the loop
-// terminates with a recoverable error instead of running forever. Successful
-// post-ready uptime resets the attempt counter for the next genuine drop.
+// Why: without backoff, a relay channel that keeps dying reconnects as fast as the network allows, hammering local + remote sshd; track attempts and back off to end the loop recoverably.
 type RelayLostBackoffState = {
   attempts: number
   reconnectTimer: ReturnType<typeof setTimeout> | null
@@ -216,12 +192,7 @@ const relayStateOverrides = new Map<string, SshConnectionState>()
 const RELAY_LOST_MAX_ATTEMPTS = 6
 const RELAY_LOST_BASE_DELAY_MS = 500
 const RELAY_LOST_MAX_DELAY_MS = 15_000
-// Why: if a fresh reconnect's mux dies within this window, the new session
-// never stabilized (a flap, not a real recovery). Without this clamp the
-// attempt counter would be reset prematurely by a mux that "reached ready"
-// only on paper. 5 seconds covers normal post-deploy provider registration
-// and PTY reattach without being so generous that a real long-lived session
-// looks like a flap.
+// Why: a reconnect whose mux dies within this window was a flap, not a recovery — don't reset the attempt counter. 5s covers provider re-registration + PTY reattach.
 const RELAY_LOST_STABILIZED_MS = 5_000
 
 function clearRelayLostBackoff(targetId: string): void {
@@ -240,9 +211,7 @@ function broadcastSshState(
   targetId: string,
   state: SshConnectionState
 ): void {
-  // Why: runtime-owned (ephemeral-VM) targets are hidden from the renderer, which
-  // has no surface for them. Broadcasting their state would make the renderer fire
-  // a listTargets() lookup per event (incl. each relay-lost reconnect) for nothing.
+  // Why: runtime-owned (ephemeral-VM) targets are hidden from the renderer, so broadcasting their state only triggers wasted listTargets() lookups.
   if (isRuntimeOwnedSshTargetId(targetId)) {
     currentRuntime?.invalidateSshWorktreeScanCache?.(targetId)
     return
@@ -252,8 +221,7 @@ function broadcastSshState(
   if (win && !win.isDestroyed()) {
     win.webContents.send('ssh:state-changed', { targetId, state: enrichedState })
   }
-  // Why: paired remote clients have no ssh:state-changed IPC; without this
-  // their terminals keep a stale reconnect overlay after the host connects.
+  // Why: paired remote clients have no ssh:state-changed IPC; without this their terminals keep a stale reconnect overlay.
   currentRuntime?.notifySshStateChanged?.(targetId, enrichedState)
 }
 
@@ -279,8 +247,7 @@ function clearRelayStateOverride(targetId: string): void {
 }
 
 function connectionSupportsFolderDownload(targetId: string): boolean {
-  // Why: ready legacy/test connections without an explicit transport are ssh2-shaped;
-  // only a confirmed system-SSH transport must remove the SFTP-only capability.
+  // Why: connections without an explicit transport are ssh2-shaped; only a confirmed system-SSH transport lacks the SFTP-only capability.
   return connectionManager?.getConnection(targetId)?.usesSystemSshTransport?.() !== true
 }
 
@@ -340,10 +307,7 @@ function enrichDetected(
   )
 }
 
-// Why: after user-initiated add/remove/update the runtime manager is the
-// single source of truth — write exactly its entries and nothing else.
-// A separate helper (persistPortForwardsWithUnrestored) preserves entries
-// that failed to restore so they retry on next reconnect.
+// Why: after user add/remove/update the runtime manager is the source of truth — persist exactly its entries (unrestored ones handled by a separate helper).
 function persistPortForwards(targetId: string): void {
   const active = portForwardManager!.listForwards(targetId)
   const saved: SavedPortForward[] = active.map((f) => ({
@@ -355,9 +319,7 @@ function persistPortForwards(targetId: string): void {
   sshStore!.updateTarget(targetId, { portForwards: saved.length > 0 ? saved : undefined })
 }
 
-// Why: called after restorePortForwards so that forwards which failed to
-// restore (e.g. port temporarily busy) are kept in the persisted list and
-// retried on next reconnect, rather than being silently dropped.
+// Why: keep forwards that failed to restore in the persisted list so they retry on next reconnect instead of being silently dropped.
 function persistPortForwardsWithUnrestored(targetId: string): void {
   const active = portForwardManager!.listForwards(targetId)
   const activeKeys = new Set(active.map((f) => `${f.localPort}:${f.remoteHost}:${f.remotePort}`))
@@ -392,14 +354,9 @@ async function restorePortForwards(
     return
   }
 
-  // Why: don't prune failed restores from persisted state. A failure may
-  // be transient (e.g. port temporarily busy at startup) and the forward
-  // should be retried on the next reconnect rather than silently deleted.
+  // Why: keep failed restores in persisted state — a failure may be transient (port temporarily busy), so retry on next reconnect.
   for (const saved of target.portForwards) {
-    // Why: if the session disconnects/reconnects while this loop is running,
-    // a new connection object is created. Checking identity avoids adding
-    // forwards against a stale connection, which would leak local listeners
-    // that the next reconnect's removeAllForwards() doesn't know about.
+    // Why: a reconnect mid-loop swaps the connection object; bail on identity change so we don't add forwards to a stale conn (leaking listeners).
     if (connectionManager!.getConnection(targetId) !== conn) {
       return
     }
@@ -425,9 +382,7 @@ async function restorePortForwards(
 
 function registerAdvertisedUrlRefresh(getMainWindow: () => BrowserWindow | null): void {
   advertisedUrlWatcherUnsubscribe?.()
-  // Why: SSH port scans only emit when raw host/port/PID data changes. A
-  // terminal can print the advertised URL after the raw port row is already
-  // visible, so the watcher must also trigger a renderer refresh.
+  // Why: SSH port scans only emit on raw host/port/PID changes, but a terminal can print the advertised URL later, so the watcher must also refresh the renderer.
   advertisedUrlWatcherUnsubscribe = advertisedUrlWatcher.onDidChange(({ worktreeId }) => {
     if (!persistedStore) {
       return
@@ -439,8 +394,7 @@ function registerAdvertisedUrlRefresh(getMainWindow: () => BrowserWindow | null)
       }
       const scanner = session.getPortScanner()
       if (scanner) {
-        // Why: watcher changes can arrive before the next SSH scan refreshes
-        // listener PIDs; cached scanner rows must not pin a fresh URL stale.
+        // Why: watcher changes can arrive before the next SSH scan refreshes listener PIDs, so don't validate PIDs against cached scanner rows.
         broadcastDetectedPorts(getMainWindow, targetId, scanner.getDetectedPorts(targetId), {
           validatePid: false
         })
@@ -450,8 +404,7 @@ function registerAdvertisedUrlRefresh(getMainWindow: () => BrowserWindow | null)
   })
 }
 
-// Why: macOS can resume the process before the network stack is back up, so
-// a failed first probe gets one retry before the link is declared dead (#7773).
+// Why: macOS can resume before the network is back, so a failed first probe gets one retry before the link is declared dead (#7773).
 const RESUME_PROBE_TIMEOUT_MS = 5_000
 const RESUME_PROBE_ATTEMPTS = 2
 
@@ -483,15 +436,11 @@ function registerPowerMonitorReconnect(): void {
         continue
       }
       void (async () => {
-        // Why: unconditional reconnect on every wake tore down live sessions
-        // and flashed the reconnect overlay (#7773). Only reconnect targets
-        // whose relay link actually died during sleep.
+        // Why: unconditional reconnect on wake tore down live sessions and flashed the overlay (#7773); only reconnect if the relay link actually died during sleep.
         if (await isRelayLinkAliveAfterResume(session)) {
           return
         }
-        // Why: the probe can take ~10s. If the user disconnected or the
-        // session/connection was replaced meanwhile, reconnecting would
-        // resurrect a connection that was intentionally torn down.
+        // Why: the probe can take ~10s; bail if the session/connection was replaced or torn down meanwhile, else we'd resurrect it.
         if (activeSessions.get(targetId) !== session || manager?.getConnection(targetId) !== conn) {
           return
         }
@@ -526,10 +475,7 @@ function createSshConnectionCallbacks(): SshConnectionCallbacks {
         return
       }
 
-      // Why: when SSH reconnects after a network blip, we must re-deploy the
-      // relay and rebuild the full provider stack. The session's state machine
-      // ensures this only triggers when appropriate — 'deploying' state from
-      // an explicit ssh:connect is not 'ready', so this branch won't fire.
+      // Why: an SSH reconnect must re-deploy the relay and rebuild providers; the guard below fires only for real reconnects, not an explicit connect's 'deploying'.
       const session = activeSessions.get(targetId)
       const sessionState = session?.getState()
       const shouldReconnectRelay =
@@ -539,8 +485,7 @@ function createSshConnectionCallbacks(): SshConnectionCallbacks {
         (sessionState === 'ready' || sessionState === 'reconnecting')
 
       if (shouldReconnectRelay) {
-        // Why: SSH is connected before the relay providers are rebuilt. Keep
-        // renderer actions gated until SshRelaySession reaches ready again.
+        // Why: SSH connects before the relay providers rebuild; keep renderer actions gated until SshRelaySession reaches ready again.
         publishRelayOverride(
           getCurrentMainWindow,
           targetId,
@@ -556,10 +501,7 @@ function createSshConnectionCallbacks(): SshConnectionCallbacks {
       if (!session) {
         return
       }
-      // Why: allow reconnect from both 'ready' (normal network blip) and
-      // 'reconnecting' (previous reconnect attempt failed, e.g. relay deploy
-      // error on a working SSH connection). Without the 'reconnecting' check,
-      // a failed relay deploy would permanently brick the session.
+      // Why: allow reconnect from both 'ready' and 'reconnecting'; without the latter, a failed relay deploy would permanently brick the session.
       if (shouldReconnectRelay) {
         const target = sshStore?.getTarget(targetId)
         const conn = connectionManager?.getConnection(targetId)
@@ -599,9 +541,7 @@ function configureRelaySessionCallbacks(session: SshRelaySession): void {
     }
     const t = sshStore?.getTarget(tid)
 
-    // Why: bounded exponential backoff. Without this, a remote-side bug
-    // that closes every fresh --connect channel turns into an infinite
-    // tight loop spawning relay deploys until the user force-quits.
+    // Why: bounded exponential backoff — without it, a remote bug that closes every fresh --connect channel becomes an infinite relay-deploy loop.
     const state = relayLostBackoff.get(tid) ?? {
       attempts: 0,
       reconnectTimer: null,
@@ -619,9 +559,7 @@ function configureRelaySessionCallbacks(session: SshRelaySession): void {
         `[ssh] Relay channel for ${tid} kept dying across ${state.attempts} attempts; giving up. User must reconnect manually.`
       )
       relayLostBackoff.delete(tid)
-      // Why: surface the failure so the renderer can prompt the user.
-      // A still-live SSH connection with a dead relay is otherwise an
-      // invisible failure — typing in remote terminals just stops working.
+      // Why: surface the failure — a live SSH connection with a dead relay is otherwise invisible (typing in remote terminals just stops working).
       publishRelayOverride(
         getCurrentMainWindow,
         tid,
@@ -655,17 +593,14 @@ function configureRelaySessionCallbacks(session: SshRelaySession): void {
     )
   })
 
-  // Why: fires after both establish() and reconnect() reach 'ready'.
-  // Re-creates persisted port forwards so they survive app restarts
-  // and network blips without manual re-configuration.
+  // Why: fires after both establish() and reconnect() reach 'ready'; re-create persisted port forwards so they survive restarts and blips.
   session.setOnReady((tid) => {
     const state = relayLostBackoff.get(tid)
     if (state) {
       if (state.stabilizedTimer) {
         clearTimeout(state.stabilizedTimer)
       }
-      // Why: stabilization is post-ready uptime. Slow deployment time before
-      // `ready` does not prove the new relay survived user-visible work.
+      // Why: stabilization counts post-ready uptime; slow deploy time before `ready` doesn't prove the new relay survived real work.
       state.stabilizedTimer = setTimeout(() => {
         const current = relayLostBackoff.get(tid)
         if (current === state && !current.reconnectTimer) {
@@ -709,9 +644,7 @@ export function registerSshHandlers(
   getMainWindow: () => BrowserWindow | null,
   runtime?: OrcaRuntimeService
 ): { connectionManager: SshConnectionManager; sshStore: SshConnectionStore } {
-  // Why: on macOS, app re-activation creates a new BrowserWindow and re-calls
-  // this function. ipcMain.handle() throws if a handler is already registered,
-  // so we must remove any prior handlers before re-registering.
+  // Why: macOS re-activation re-calls this with a new BrowserWindow; ipcMain.handle() throws on a duplicate channel, so remove prior handlers first.
   for (const ch of SSH_IPC_CHANNELS) {
     ipcMain.removeHandler(ch)
   }
@@ -750,9 +683,7 @@ export function registerSshHandlers(
 
   // ── Target CRUD ────────────────────────────────────────────────────
 
-  // Why: SSH target add/import can re-adopt workspaces orphaned on a removed
-  // target id (see ssh-target-readoption). When that re-points repos, the
-  // renderer must refresh its repo list to surface the reattached workspaces.
+  // Why: add/import can re-adopt workspaces orphaned on a removed target id (see ssh-target-readoption); the renderer must refresh its repo list to surface them.
   function takeRepoReadoptions(): SshRepoReadoption[] {
     if (!sshStore || sshStore.lastRepoReadoptions.length === 0) {
       return []
@@ -776,9 +707,7 @@ export function registerSshHandlers(
 
   ipcMain.handle('ssh:addTarget', (_event, args: { target: Omit<SshTarget, 'id'> }) => {
     const target = sshStore!.addTarget(args.target)
-    // Why: re-adding a removed host can re-adopt orphaned workspaces (re-point
-    // repos/worktrees off the dead id). Refresh the renderer's repo list so the
-    // reattached workspaces move from grey ghosts back onto the live host.
+    // Why: re-adding a removed host can re-adopt orphaned workspaces; refresh the renderer's repo list so they move back onto the live host.
     const repoReadoptions = takeRepoReadoptions()
     return { target, repoReadoptions }
   })
@@ -808,9 +737,7 @@ export function registerSshHandlers(
       await reset
     }
 
-    // Why: serialize concurrent ssh:connect calls for the same target.
-    // Multiple tabs can fire connect simultaneously; without this, they
-    // interleave and the first session leaks.
+    // Why: serialize concurrent ssh:connect for the same target; interleaved connects otherwise leak the first session.
     const existing = connectInFlight.get(targetId)
     if (existing) {
       return existing
@@ -850,22 +777,16 @@ export function registerSshHandlers(
       !relayStateOverrides.has(targetId) &&
       !relayLostBackoff.has(targetId)
     ) {
-      // Why: BrowserWindow reactivation reruns renderer startup, which calls
-      // ssh:connect for already-live targets. Treat that as a refresh instead
-      // of tearing down the relay and stranding active port forwards.
+      // Why: BrowserWindow reactivation re-fires ssh:connect for already-live targets; treat as a refresh instead of tearing down the relay and its forwards.
       broadcastSshState(getCurrentMainWindow, targetId, existingState)
       return existingState
     }
 
     clearRelayStateOverride(targetId)
     let conn
-    // Why: dispose any existing session to avoid leaking the old multiplexer,
-    // providers, and timers. This handles double-connect (user clicks connect
-    // while already connected) and reconnect-after-error.
+    // Why: tear down any existing session first to avoid leaking its multiplexer, providers, and timers (double-connect / reconnect-after-error).
     if (existingSession) {
-      // Why: await port teardown before disposing so the OS fully releases
-      // local ports. Without this, restorePortForwards in the new session
-      // can hit EADDRINUSE on the same ports the old session was using.
+      // Why: await port teardown before disposing, else the new session's restorePortForwards can hit EADDRINUSE on not-yet-released ports.
       await portForwardManager!.removeAllForwards(targetId)
       existingSession.detach()
       activeSessions.delete(targetId)
@@ -873,8 +794,7 @@ export function registerSshHandlers(
       clearRelayStateOverride(targetId)
     }
 
-    // Why: create the session early so onStateChange sees it in 'deploying'
-    // state and knows not to trigger reconnect logic.
+    // Why: create the session early so onStateChange sees it in 'deploying' and skips reconnect logic.
     const session = new SshRelaySession(
       targetId,
       getCurrentMainWindow,
@@ -889,16 +809,10 @@ export function registerSshHandlers(
     try {
       conn = await connectionManager!.connect(target)
     } catch (err) {
-      // Why: SshConnection.connect() sets its internal state, but the
-      // onStateChange callback may not have propagated to the renderer.
-      // Explicitly broadcast so the UI leaves 'connecting'.
+      // Why: connect()'s internal state may not have reached the renderer; broadcast explicitly so the UI leaves 'connecting'.
       const errObj = err instanceof Error ? err : new Error(String(err))
       const status: SshConnectionStatus = isAuthError(errObj) ? 'auth-failed' : 'error'
-      // Why: if a credential prompt was shown before the failure, the target
-      // would stay in credentialRequestedForTarget. A later successful connect
-      // that doesn't prompt would then incorrectly persist lastRequiredPassphrase
-      // = true, causing startup to defer this target even though it no longer
-      // needs a passphrase.
+      // Why: clear this failed connect's credential flag so a later non-prompting connect can't persist lastRequiredPassphrase=true.
       credentialRequestedForTarget.delete(targetId)
       activeSessions.delete(targetId)
       clearRelayLostBackoff(targetId)
@@ -913,7 +827,6 @@ export function registerSshHandlers(
     }
 
     try {
-      // Deploy relay and establish multiplexer
       callbacks.onStateChange(targetId, {
         targetId,
         status: 'deploying-relay',
@@ -923,10 +836,7 @@ export function registerSshHandlers(
 
       await session.establish(conn, relayGracePeriodForTarget(target))
 
-      // Why: we manually pushed `deploying-relay` above, so the renderer's
-      // state is stuck there. Send `connected` directly to the renderer
-      // instead of going through callbacks.onStateChange, which would
-      // trigger the reconnection logic.
+      // Why: we manually pushed `deploying-relay`, so send `connected` straight to the renderer — routing through onStateChange would trigger reconnect logic.
       clearRelayStateOverride(targetId)
       broadcastSshState(getCurrentMainWindow, targetId, {
         targetId,
@@ -936,17 +846,13 @@ export function registerSshHandlers(
         supportsFolderDownload: conn.usesSystemSshTransport?.() !== true
       })
     } catch (err) {
-      // Relay deployment failed — disconnect SSH
       activeSessions.delete(targetId)
       clearRelayLostBackoff(targetId)
       await connectionManager!.disconnect(targetId)
       throw err
     }
 
-    // Why: persist whether this connection required a credential prompt so
-    // startup reconnect can partition targets into eager vs deferred without
-    // re-probing keys. Updated on every successful connect so the flag stays
-    // current as users add/remove passphrases from their keys.
+    // Why: persist whether this connect needed a credential so startup can partition targets into eager vs deferred without re-probing keys.
     const requiredPassphrase = credentialRequestedForTarget.has(targetId)
     credentialRequestedForTarget.delete(targetId)
     sshStore!.updateTarget(targetId, { lastRequiredPassphrase: requiredPassphrase })
@@ -1008,8 +914,7 @@ export function registerSshHandlers(
       persistedStore!.markSshRemotePtyLease(args.targetId, relayPtyId, 'terminated')
     }
     if (shutdownFailures.length > 0) {
-      // Why: a failed relay shutdown can leave the remote process alive in the
-      // grace window. Keep the lease/session intact so the user can retry.
+      // Why: a failed relay shutdown can leave the remote process alive in the grace window; keep the lease/session so the user can retry.
       throw new Error(`Failed to terminate SSH host sessions: ${shutdownFailures.join('; ')}`)
     }
     if (session) {
@@ -1026,8 +931,7 @@ export function registerSshHandlers(
     const inFlightConnect = connectInFlight.get(targetId)
     if (inFlightConnect) {
       try {
-        // Why: reset tears down activeSessions; doing that while doConnect is
-        // still deploying can dispose the session doConnect is about to use.
+        // Why: await the in-flight connect first; tearing down activeSessions mid-deploy would dispose the session doConnect is about to use.
         await inFlightConnect
       } catch {
         // The reset can still recover a stale remote relay after a failed connect.
@@ -1037,8 +941,7 @@ export function registerSshHandlers(
     const session = activeSessions.get(targetId)
     if (session) {
       await portForwardManager!.removeAllForwards(targetId)
-      // Why: reset has its own stale-relay lease semantics below. dispose()
-      // records clean PTY termination, which hides reset-affected leases.
+      // Why: detach() not dispose() — reset has its own stale-lease semantics below that dispose()'s clean-termination recording would hide.
       session.detach()
       activeSessions.delete(targetId)
       clearRelayLostBackoff(targetId)
@@ -1056,17 +959,13 @@ export function registerSshHandlers(
           persistedStore!.markSshRemotePtyLease(targetId, lease.ptyId, 'expired')
         }
       }
-      // Why: reset force-kills the remote relay daemon, so every local PTY
-      // handle owned by that relay is stale even if the reset command failed
-      // after the remote process accepted SIGTERM.
+      // Why: reset force-kills the remote relay, so every local PTY handle it owned is stale even if the reset command failed after SIGTERM.
       for (const ptyId of ptyIds) {
         const appPtyId = toAppSshPtyId(targetId, ptyId)
         clearProviderPtyState(appPtyId)
         deletePtyOwnership(appPtyId)
       }
-      // Why: reset's connect() can trip onCredentialRequest, which adds to
-      // credentialRequestedForTarget. Without this delete, a later doConnect
-      // that doesn't prompt would still persist lastRequiredPassphrase=true.
+      // Why: reset's connect() may trip onCredentialRequest; clear so a later non-prompting doConnect doesn't persist lastRequiredPassphrase=true.
       credentialRequestedForTarget.delete(targetId)
       await connectionManager!.disconnect(targetId)
     }
@@ -1099,12 +998,7 @@ export function registerSshHandlers(
     return getPublicSshState(args.targetId)
   })
 
-  // Why: callers that want to auto-connect (Cmd+J jump, terminal reattach) need
-  // to know whether doing so will pop a passphrase/password dialog. Auto-firing
-  // the connect is fine when no prompt is needed, but surprising otherwise —
-  // the user expects to enter the credential before the app starts connecting.
-  // Returns true if the target's last successful connect required a credential
-  // AND the live SshConnection (if any) does not already have one cached.
+  // Why: auto-connect callers need to know whether connecting will prompt; true when the last connect required a credential and no live conn has it cached.
   ipcMain.handle('ssh:needsPassphrasePrompt', (_event, args: { targetId: string }) => {
     const target = sshStore!.getTarget(args.targetId)
     if (!target?.lastRequiredPassphrase) {
@@ -1120,12 +1014,7 @@ export function registerSshHandlers(
       throw new Error(`SSH target "${args.targetId}" not found`)
     }
 
-    // Why: testConnection calls connect() then disconnect(). If the target
-    // already has an active relay session, connect() would reuse the connection
-    // but disconnect() would tear down the entire relay stack — killing all
-    // active PTYs and file watchers for a "test" that was supposed to be safe.
-    // Also guard 'reconnecting' — disconnect() would kill the SSH connection
-    // that the in-flight reconnect is using for relay deployment.
+    // Why: with a live/reconnecting session, testConnection's disconnect() would tear down the relay stack (PTYs, watchers), so skip.
     const existingSession = activeSessions.get(args.targetId)
     const sessionState = existingSession?.getState()
     if (
@@ -1136,9 +1025,7 @@ export function registerSshHandlers(
       return { success: true, state: connectionManager!.getState(args.targetId) }
     }
 
-    // Why: if a real ssh:connect is in flight for this target, testConnection's
-    // disconnect() call would tear down the connection that doConnect is using
-    // for relay deployment. Wait for the in-flight connect to finish instead.
+    // Why: testConnection's disconnect() would tear down an in-flight connect's relay deployment; await it instead.
     const inFlight = connectInFlight.get(args.targetId)
     if (inFlight) {
       try {
@@ -1165,10 +1052,7 @@ export function registerSshHandlers(
       }
     } finally {
       testingTargets.delete(args.targetId)
-      // Why: the shared onCredentialRequest callback adds to this set for
-      // any connect() call, including testConnection. Without clearing it,
-      // a later real connect that doesn't prompt would persist
-      // lastRequiredPassphrase=true, causing startup to defer this target.
+      // Why: clear so a test's credential prompt doesn't leave lastRequiredPassphrase=true and defer this target at startup.
       credentialRequestedForTarget.delete(args.targetId)
     }
   })
@@ -1235,9 +1119,7 @@ export function registerSshHandlers(
         broadcastPortForwards(getCurrentMainWindow, entry.connectionId)
         return entry
       } catch (err) {
-        // Why: if the edit failed (and rollback may also have failed),
-        // sync the renderer with the actual runtime state so it doesn't
-        // show a forward that no longer exists.
+        // Why: edit/rollback may have failed, so resync renderer to actual runtime state.
         persistPortForwards(args.targetId)
         broadcastPortForwards(getCurrentMainWindow, args.targetId)
         throw err
@@ -1257,9 +1139,7 @@ export function registerSshHandlers(
   ipcMain.handle('ssh:listPortForwards', (_event, args?: { targetId?: string }) => {
     const all = portForwardManager!.listForwards(args?.targetId)
     if (!persistedStore || !args?.targetId) {
-      // Why: the cross-target list is rare and we cannot map every entry to
-      // worktrees in a single call; serve the raw list. Per-target callers
-      // get full enrichment.
+      // Why: cross-target entries can't be mapped to worktrees in one call, so serve the raw list.
       return all
     }
     return enrichSshForwardEntries(all, getWorktreeIdsForConnection(persistedStore, args.targetId))
diff --git a/src/main/ipc/telemetry.test.ts b/src/main/ipc/telemetry.test.ts
index 40679160f93..1f412a6d0e9 100644
--- a/src/main/ipc/telemetry.test.ts
+++ b/src/main/ipc/telemetry.test.ts
@@ -1,10 +1,4 @@
-// IPC boundary behavior for the telemetry surface. Strict type narrows must
-// drop obviously-malformed calls before they reach the validator (the
-// renderer is in the threat model). Pins the consent-mutation rate limit:
-// ≤5 consent-related IPC calls per session. Pins the main-side `via`
-// derivation: both `OptInVia` branches are reachable from renderer input,
-// and the one path that must NOT emit (`acknowledgeBanner`) has its own
-// channel and handler rather than being a flag on `setOptIn`.
+// Telemetry IPC boundary tests: the renderer is in the threat model, so handlers drop malformed calls, cap consent mutations, and derive `via` main-side.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { GlobalSettings } from '../../shared/types'
@@ -58,9 +52,7 @@ function captureHandlers(): void {
   }
 }
 
-// Build a fake Store with a settable `telemetry` block. Tests reassign
-// `settings.telemetry` between handler invocations to seed the two
-// derivation states.
+// Fake Store whose `telemetry` block tests reassign between invocations to seed derivation states.
 type FakeStoreState = { settings: GlobalSettings }
 function makeFakeStore(telemetry: GlobalSettings['telemetry']): {
   store: Store
@@ -125,10 +117,7 @@ describe('telemetry IPC handlers', () => {
     expect(trackMock).toHaveBeenCalledWith('app_opened', { nth_repo_added: 2 })
   })
 
-  // The IPC handler's selectivity is load-bearing: schemas are `.strict()`,
-  // so injecting `nth_repo_added` on a non-cohort event would silently
-  // drop the entire event at the validator. Events outside `COHORT_EXTENDED`
-  // must reach `track()` unmodified.
+  // Schemas are `.strict()`, so injecting `nth_repo_added` on a non-cohort event would drop the whole event at the validator.
   it('does NOT inject cohort on events outside COHORT_EXTENDED', () => {
     registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     const handler = handlers.get('telemetry:track')!
@@ -141,9 +130,7 @@ describe('telemetry IPC handlers', () => {
     expect(getCohortAtEmitMock).not.toHaveBeenCalled()
   })
 
-  // The renderer-only Setup-step events fire from React `onClick` and
-  // depend on the IPC handler injecting cohort — call sites stay
-  // synchronous and pass only their own props.
+  // Renderer-only Setup-step events depend on the handler injecting cohort so call sites stay synchronous.
   it('injects cohort for add_repo_setup_step_action (renderer-only event)', () => {
     registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     getCohortAtEmitMock.mockReturnValue({ nth_repo_added: 1 })
@@ -213,8 +200,7 @@ describe('telemetry IPC handlers', () => {
     })
   })
 
-  // Fail-soft: a degraded classifier returns `{ nth_repo_added: undefined }`.
-  // The schemas declare the field optional, so the event still validates.
+  // Fail-soft: `nth_repo_added` is optional, so an undefined cohort still validates.
   it('forwards undefined cohort when the classifier returns undefined', () => {
     registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     getCohortAtEmitMock.mockReturnValue({ nth_repo_added: undefined })
@@ -223,11 +209,7 @@ describe('telemetry IPC handlers', () => {
     expect(trackMock).toHaveBeenCalledWith('app_opened', { nth_repo_added: undefined })
   })
 
-  // Threat-model parity with the cohort override test: a compromised
-  // renderer must NOT be able to forge `nth_repo_added` either. The same
-  // spread-order invariant applies — `{ ...baseProps, ...getCohortAtEmit() }`
-  // — and the same future-refactor regression risk exists. Pinning both
-  // fields keeps the threat model symmetric.
+  // Security: same spread-order invariant as cohort — main-derived `nth_repo_added` overrides any renderer-forged value.
   it('main-derived nth_repo_added overrides renderer-supplied value', () => {
     registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     getCohortAtEmitMock.mockReturnValue({ nth_repo_added: 2 })
@@ -265,11 +247,7 @@ describe('telemetry IPC handlers', () => {
     expect(trackMock).toHaveBeenCalledWith('onboarding_started', { cohort: undefined })
   })
 
-  // Threat-model invariant: a compromised renderer must NOT be able to forge
-  // `cohort` by including it in the props payload. The IPC handler spreads
-  // the main-derived cohort AFTER the caller-supplied props, so the main
-  // value wins. This test pins that invariant — flipping the spread order
-  // would silently let a compromised renderer fake any cohort value.
+  // Security: main spreads cohort after caller props so main wins; flipping the order would let a renderer forge `cohort`.
   it('main-derived cohort overrides renderer-supplied cohort', () => {
     registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     getOnboardingCohortAtEmitMock.mockReturnValue({ cohort: 'fresh_install' })
@@ -281,20 +259,12 @@ describe('telemetry IPC handlers', () => {
     })
   })
 
-  // Threat-model invariant under degraded classifier: a compromised
-  // renderer must NOT be able to forge `cohort` even when the classifier
-  // fails soft to `{ cohort: undefined }`. The IPC handler spreads the
-  // classifier output AFTER the caller-supplied props, so an explicit
-  // `undefined` from the classifier still overwrites a forged value. A
-  // future refactor that switches the spread to a conditional assign
-  // (`if (c.cohort !== undefined) baseProps.cohort = c.cohort`) would
-  // silently regress this — pinning it here.
+  // Security: a fail-soft undefined cohort must still overwrite a forged value; a conditional-assign refactor would regress this.
   it('main-derived undefined cohort overrides renderer-supplied cohort (degraded classifier)', () => {
     registerWith({ installId: 'x', existedBeforeTelemetryRelease: true, optedIn: true })
     getOnboardingCohortAtEmitMock.mockReturnValue({ cohort: undefined })
     const handler = handlers.get('telemetry:track')!
-    // Compromised renderer attempts to forge cohort='upgrade_backfill';
-    // main strips it via the explicit-undefined spread.
+    // Forged cohort='upgrade_backfill' is stripped by the explicit-undefined spread.
     handler({}, 'onboarding_started', { cohort: 'upgrade_backfill' })
     expect(trackMock).toHaveBeenCalledWith('onboarding_started', {
       cohort: undefined
@@ -354,9 +324,7 @@ describe('telemetry IPC handlers', () => {
   // ── telemetry:setOptIn — `via` derivation ────────────────────────────
 
   it("derives via='first_launch_banner' for an existing user with optedIn=null clicking Turn off", () => {
-    // Existing-user notice is the only path where an existing user (cohort
-    // marker true) with optedIn=null flips to false. That is the contract
-    // the notice's "Turn off" button routes through.
+    // Only path where an existing user (optedIn=null) flips to false: the notice's "Turn off" button.
     registerWith({
       installId: 'x',
       existedBeforeTelemetryRelease: true,
@@ -368,12 +336,7 @@ describe('telemetry IPC handlers', () => {
   })
 
   it("derives via='settings' (not 'first_launch_banner') for a defensive opt-in call from the pre-notice state", () => {
-    // Defensive: the notice's opt-in path is the ✕ (silent acknowledge),
-    // which does NOT route through setOptIn. A compromised renderer
-    // could try to call telemetrySetOptIn(true) in the pre-notice state
-    // and synthesize a spurious telemetry_opted_in { via:
-    // 'first_launch_banner' }. The derivation must refuse that tag for
-    // the true-incoming case and fall through to 'settings'.
+    // Security: refuse via='first_launch_banner' on a forged setOptIn(true) pre-notice; fall through to 'settings'.
     registerWith({
       installId: 'x',
       existedBeforeTelemetryRelease: true,
@@ -385,10 +348,7 @@ describe('telemetry IPC handlers', () => {
   })
 
   it("derives via='settings' for a new user toggling off from Settings (no first-launch surface exists)", () => {
-    // New users (existedBeforeTelemetryRelease=false) are initialized with
-    // optedIn=true at migration and see no first-launch surface. Any
-    // opt-out from this cohort routes through Settings → Privacy and
-    // must tag as `via: 'settings'`.
+    // New users (existed=false) see no first-launch surface, so any opt-out routes through Settings.
     registerWith({
       installId: 'x',
       existedBeforeTelemetryRelease: false,
@@ -400,8 +360,7 @@ describe('telemetry IPC handlers', () => {
   })
 
   it("derives via='settings' for an opt-in toggle flip after a prior opt-out", () => {
-    // User flipped off in Settings, flipping back on in Settings. Neither
-    // cohort marker nor notice state triggers a first-launch tag.
+    // Re-opt-in from Settings: neither cohort marker nor notice state triggers a first-launch tag.
     registerWith({
       installId: 'x',
       existedBeforeTelemetryRelease: true,
@@ -424,8 +383,7 @@ describe('telemetry IPC handlers', () => {
   })
 
   it("derives via='settings' when the telemetry block is missing (defensive)", () => {
-    // Should never happen post-migration, but if it does the handler must
-    // fall through to 'settings' rather than throwing or mis-tagging.
+    // Should never happen post-migration; handler must fall through to 'settings', not throw.
     registerWith(undefined)
     const handler = handlers.get('telemetry:setOptIn')!
     handler({}, true)
@@ -435,10 +393,7 @@ describe('telemetry IPC handlers', () => {
   // ── telemetry:acknowledgeBanner — silent-persist path ────────────────
 
   it('routes banner ✕ through persistBannerAcknowledgeWithoutEmitting without invoking setOptIn', () => {
-    // This is the whole point of the separate channel: the silent-persist
-    // path MUST NOT reach setOptIn, which would derive a `via` and fire
-    // `telemetry_opted_in`. The client primitive may unlock `app_opened`,
-    // but the acknowledge channel itself must not emit an opt-in event.
+    // Why the separate channel: reaching setOptIn would derive a `via` and fire `telemetry_opted_in`; acknowledge must persist silently.
     registerWith({
       installId: 'x',
       existedBeforeTelemetryRelease: true,
@@ -464,13 +419,7 @@ describe('telemetry IPC handlers', () => {
   })
 
   // ── telemetry:acknowledgeBanner — state-precondition guard ───────────
-  // These tests pin the guard, which rejects any cohort/optedIn
-  // combination other than (existed=true, optedIn=null). The guard is
-  // the defense against a compromised renderer silently flipping
-  // optedIn=true for a user who already resolved consent — a future
-  // refactor that weakens it must fail here. The guard also runs BEFORE
-  // consumeConsentMutationToken, so a rejected call must not burn a
-  // token either.
+  // Security: guard passes only (existed=true, optedIn=null) and runs before token consumption, blocking a compromised renderer from flipping resolved consent.
 
   it('acknowledgeBanner rejects an existing user who already opted in', () => {
     registerWith({
diff --git a/src/main/ipc/telemetry.ts b/src/main/ipc/telemetry.ts
index 03cc50e7026..78f47fbbd41 100644
--- a/src/main/ipc/telemetry.ts
+++ b/src/main/ipc/telemetry.ts
@@ -1,39 +1,13 @@
-// IPC surface for the telemetry transport. Four handlers, all renderer-
-// facing: one pipe (`telemetry:track`), one consent-mutation
-// (`telemetry:setOptIn`), one silent-persist for the banner ✕ path
-// (`telemetry:acknowledgeBanner`), and one read-only getter for effective
-// consent state (`telemetry:getConsentState`, used by the Privacy pane to
-// render env-var blocked-state helper text). Every track call from the
-// renderer lands here and funnels into the same `track()` the main-
-// originated events go through — the validator is the single enforcement
-// point, not this file.
+// IPC surface for telemetry: `track`, `setOptIn`, `acknowledgeBanner`, and read-only
+// `getConsentState`. Renderer track calls funnel into the same `track()` as main-originated
+// events; the validator there is the single enforcement point, not this file.
 //
-// Threat model: the renderer renders attacker-controllable content (agent
-// output, MCP responses, file contents, markdown, diff views). An
-// XSS-equivalent rendering bug in any of those surfaces gives an attacker
-// the ability to invoke `window.api.telemetry*` at will. The handlers
-// below are designed to fail closed under that model:
-//
-//   - Strict main-side type narrows. TypeScript types do not survive IPC
-//     serialization; the renderer can pass anything across the wire, so we
-//     narrow at the boundary. Non-string `name` or non-object `props` on
-//     `track` → drop silently. Non-boolean `optedIn` on `setOptIn` → drop.
-//   - Consent-mutation rate limit. A real user flips the Privacy pane
-//     toggle a handful of times at most; beyond 5 per session it is either
-//     a UI bug or a compromised renderer. Drop silently past the cap.
-//     Applies to `acknowledgeBanner` as well — that path also mutates
-//     persisted consent, so it lives under the same per-session ceiling.
-//
-// `via` derivation: the renderer does NOT pass `via` across the wire. That
-// design was rejected specifically because a compromised renderer could
-// misreport `via`, muddying the one signal we use to distinguish
-// first-launch interactions from settings flips. Main derives `via` from
-// fields main already owns (`existedBeforeTelemetryRelease`, current
-// `optedIn`) before any state mutation. The two product paths map cleanly
-// to the two schema values (`first_launch_banner` for the existing-user
-// notice's "Turn off" button; `settings` for everything else — new users
-// have no first-launch surface, so their opt-outs always come through
-// Settings).
+// Threat model: the renderer displays attacker-controllable content (agent output, MCP
+// responses, markdown, diffs), so an XSS-equivalent bug lets an attacker call
+// `window.api.telemetry*`. These handlers fail closed: strict main-side type narrows (TS
+// types don't survive IPC), a ≤5/session consent-mutation cap (covers `acknowledgeBanner`
+// too), and `via` derived from main-owned state — never passed over the wire, so a
+// compromised renderer can't misreport it.
 
 import { ipcMain } from 'electron'
 import { consumeConsentMutationToken } from '../telemetry/burst-cap'
@@ -46,11 +20,7 @@ import { isCohortExtendedEvent, isOnboardingEvent } from '../../shared/telemetry
 import type { EventName, EventProps } from '../../shared/telemetry-events'
 import type { OptInVia } from '../../shared/telemetry-events'
 
-// Module-level store reference, populated by `registerTelemetryHandlers`.
-// The handlers need a synchronous read of `settings.telemetry` at call time
-// to derive `via` before any mutation runs — threading the store through
-// every handler closure is the least-surprising shape for that, and it
-// mirrors how other core-handlers accept the store explicitly.
+// Module-level store ref: handlers need a synchronous `settings.telemetry` read to derive `via` before any mutation.
 let storeRef: Store | null = null
 
 const MAIN_OWNED_TELEMETRY_EVENTS = new Set<EventName>([
@@ -60,44 +30,18 @@ const MAIN_OWNED_TELEMETRY_EVENTS = new Set<EventName>([
 ])
 
 /**
- * Derive the `via` discriminator for a `telemetry:setOptIn` call from
- * main-owned state. Called BEFORE any state mutation so the cohort + opt-in
- * snapshot reflects the pre-click world.
- *
- * Two cases (mirrors the product surfaces defined in telemetry-plan.md):
- *   - existing-user notice "Turn off" → `'first_launch_banner'`
- *     (existedBeforeTelemetryRelease=true, optedIn=null, incoming false)
- *   - any other flip → `'settings'`
- *     (Privacy pane, post-first-launch mutations, etc.)
- *
- * New users never reach a `'first_launch_banner'` tag — their cohort marker
- * is false and they see no first-launch surface at all (see telemetry-plan.md
- * §First-launch experience). Any consent flip they make routes through
- * Settings → Privacy and tags as `'settings'`.
- *
- * Note: the notice's ✕ (silent acknowledge) path does NOT come through this
- * function — it routes through `telemetry:acknowledgeBanner` and
- * `persistBannerAcknowledgeWithoutEmitting`, which intentionally does not
- * emit. Derivation here would tag it as `'first_launch_banner'` and emit
- * `telemetry_opted_in`, which the ✕-as-silent-acknowledge semantics
- * forbid.
+ * Derive the `via` discriminator for `telemetry:setOptIn` from main-owned state.
+ * Called BEFORE any mutation so the snapshot reflects the pre-click world.
+ * Existing-user notice "Turn off" → `first_launch_banner`; any other flip → `settings`
+ * (new users have no first-launch surface, so their opt-outs always tag `settings`; see telemetry-plan.md).
+ * (The ✕ silent-acknowledge path routes through `telemetry:acknowledgeBanner`, not here.)
  */
 function deriveOptInVia(store: Store, incomingOptedIn: boolean): OptInVia {
   const telemetry = store.getSettings().telemetry
   const existedBefore = telemetry?.existedBeforeTelemetryRelease === true
   const currentOptedIn = telemetry?.optedIn
 
-  // Existing-user cohort, notice still pending. The only surface that calls
-  // `setOptIn` in this state is the FirstLaunchBanner's "Turn off" click;
-  // the ✕ path does not route here (it goes through
-  // `telemetry:acknowledgeBanner`). We additionally narrow on
-  // `incomingOptedIn === false` as a defensive guard: a compromised
-  // renderer could otherwise call `telemetrySetOptIn(true)` in this
-  // pre-notice state and synthesize a spurious
-  // `telemetry_opted_in { via: 'first_launch_banner' }`, which the
-  // ✕-as-silent-acknowledge contract forbids. Falling through to
-  // 'settings' for the true case keeps the forbidden tag unreachable
-  // from IPC.
+  // The `incomingOptedIn === false` narrow stops a compromised renderer synthesizing a spurious first_launch_banner opt-in.
   if (existedBefore && currentOptedIn === null && incomingOptedIn === false) {
     return 'first_launch_banner'
   }
@@ -109,40 +53,20 @@ export function registerTelemetryHandlers(store: Store): void {
   storeRef = store
 
   ipcMain.handle('telemetry:track', (_event, name: unknown, props: unknown): void => {
-    // Strict input typing: non-string names are dropped at the boundary
-    // before the validator even sees them. The validator would also drop
-    // (unknown event name), but the main-side narrow keeps the attack
-    // surface minimal — a flood of bogus payloads does not exercise the
-    // Zod parser for no reason.
+    // Drop non-string names at the boundary so a flood of bogus payloads never reaches the Zod validator.
     if (typeof name !== 'string') {
       return
     }
-    // `props` may legitimately be omitted; treat `undefined`/`null` as an
-    // empty object before the validator. Anything else non-object (e.g.
-    // a string, a number) is a boundary violation.
+    // `props` is optional (undefined/null → {} below); reject any other non-object at the boundary.
     if (props !== null && props !== undefined && typeof props !== 'object') {
       return
     }
     const eventName = name as EventName
-    // Why: some event schemas are registered for main-owned emissions only.
-    // Letting renderer IPC emit them would let compromised content spoof
-    // product outcomes that must be tied to a successful main-side action.
+    // Why: these events are main-owned; renderer IPC emitting them would let compromised content spoof product outcomes.
     if (MAIN_OWNED_TELEMETRY_EVENTS.has(eventName)) {
       return
     }
-    // Inject cohort here, at the IPC entry, only for events whose schemas
-    // declare `nth_repo_added` (see `COHORT_EXTENDED` in telemetry-events.ts).
-    // The selectivity is load-bearing: schemas are `.strict()`, so adding
-    // `nth_repo_added` to an event that does not declare it would fail Zod
-    // validation and silently drop the entire event. The renderer call sites
-    // stay synchronous (matching the existing fire-and-forget shape) and
-    // avoid an extra IPC round-trip to fetch cohort.
-    //
-    // Onboarding events get the same treatment for the `cohort` property,
-    // gated by `isOnboardingEvent` (events whose schema declares `cohort`).
-    // The two injection sets are disjoint by construction today — no schema
-    // declares both `nth_repo_added` and `cohort` — but combining them via
-    // spread keeps that an additive change rather than a structural one.
+    // Inject cohort props only for schemas that declare them: schemas are `.strict()`, so an extra prop on any other event fails Zod and drops it.
     const baseProps = (props ?? {}) as Record<string, unknown>
     const withRepoCohort = isCohortExtendedEvent(eventName)
       ? { ...baseProps, ...getCohortAtEmit() }
@@ -150,11 +74,7 @@ export function registerTelemetryHandlers(store: Store): void {
     const finalProps = isOnboardingEvent(eventName)
       ? { ...withRepoCohort, ...getOnboardingCohortAtEmit() }
       : withRepoCohort
-    // The casts to `EventName` / `EventProps<EventName>` here are
-    // pass-through only — this file does NOT pretend the renderer's
-    // name/props are type-safe. The validator inside `track()` is the
-    // single enforcement point at runtime; these casts only feed the
-    // typed channel that the validator will re-check.
+    // Casts are pass-through only; `track()`'s validator is the single runtime enforcement point, not these casts.
     track(eventName, finalProps as EventProps<EventName>)
   })
 
@@ -163,79 +83,39 @@ export function registerTelemetryHandlers(store: Store): void {
     if (typeof optedIn !== 'boolean') {
       return
     }
-    // Check storeRef BEFORE consuming a consent-mutation token. If the store
-    // isn't ready (pre-registration race, test harness misuse, a future
-    // refactor), consuming a token here would burn budget for a no-op and
-    // eventually block legitimate mutations from the same session.
+    // Check storeRef before consuming a token — burning one on a no-op would eventually block legitimate mutations this session.
     if (!storeRef) {
       return
     }
-    // Consent-mutation bucket: ≤5 per session. See `burst-cap.ts`. Does not
-    // apply to main-originated consent mutations that bypass IPC (none
-    // today; this is future-proofing rather than a current code path).
+    // Consent-mutation bucket: ≤5 per session (see `burst-cap.ts`).
     if (!consumeConsentMutationToken()) {
       return
     }
-    // Read settings BEFORE any state mutation. The derivation must see the
-    // pre-mutation world so an existing user clicking "Turn off" on the
-    // notice still presents as (optedIn=null → false) at the moment `via`
-    // is computed, not (optedIn=false → false) after the write lands.
+    // Derive `via` BEFORE the write so it sees the pre-mutation state (optedIn still null for an existing user's "Turn off").
     const via = deriveOptInVia(storeRef, optedIn)
     return setOptIn(via, optedIn)
   })
 
-  // Read-only view of the effective consent state. The Privacy pane needs
-  // this to render the correct helper text when an env var
-  // (DO_NOT_TRACK / ORCA_TELEMETRY_DISABLED / CI) blocks transmission —
-  // those variables are main-side process state and the renderer has no
-  // way to read them directly. No rate limit: this is a synchronous getter
-  // with no mutation, bounded in work by one `resolveConsent` call.
+  // Read-only getter: lets the Privacy pane see env-var blocks (DO_NOT_TRACK/ORCA_TELEMETRY_DISABLED/CI), which are main-side state the renderer can't read.
   ipcMain.handle('telemetry:getConsentState', (): ConsentState => {
     if (!storeRef) {
-      // Fail closed — a missing store means we cannot honor the user's
-      // stored preference, so surface pending_banner rather than a
-      // misleading 'enabled'. The renderer treats pending_banner like a
-      // disabled state in the UI.
+      // Fail closed: no store means we can't honor the stored preference, so surface pending_banner, not a misleading 'enabled'.
       return { effective: 'pending_banner' }
     }
     return resolveConsent(storeRef.getSettings())
   })
 
   ipcMain.handle('telemetry:acknowledgeBanner', (_event): Promise<void> | void => {
-    // Banner ✕ — persist `optedIn = true` without emitting a telemetry opt-in
-    // event. The acknowledge still unlocks `app_opened`, but this outcome
-    // cannot route through `telemetry:setOptIn` because the derivation above
-    // would tag it `first_launch_banner` and fire `telemetry_opted_in`.
-    //
-    // Check storeRef BEFORE consuming a consent-mutation token, mirroring
-    // the setOptIn handler's guard above — see that comment for why
-    // burning a token on a no-op blocks legitimate mutations later in
-    // the same session.
+    // Banner ✕: persist optedIn=true WITHOUT emitting — routing through setOptIn would fire telemetry_opted_in, which the silent-acknowledge contract forbids.
     if (!storeRef) {
       return
     }
-    // State-precondition guard: this channel is ONLY valid when the notice
-    // is pending resolution — i.e. existing-user cohort
-    // (existedBeforeTelemetryRelease=true) with optedIn still null. Any
-    // other state is either a UI bug (the notice should not be reachable
-    // post-resolution) or a compromised renderer trying to silently flip
-    // optedIn=true after the user already opted out, which would bypass
-    // the audit signal entirely. `deriveOptInVia` already applies the
-    // symmetric guard on `telemetry:setOptIn` (it refuses to tag a true
-    // flip as `first_launch_banner`); this narrows the silent-persist
-    // attack surface on the acknowledge channel to exactly the state the
-    // notice contract covers. Must run BEFORE the token consume — same
-    // "don't burn a token on a no-op" reasoning as the !storeRef guard
-    // above.
+    // Only valid while the notice is pending (existedBefore=true, optedIn=null); any other state is a renderer silently flipping optedIn after opt-out.
     const telemetry = storeRef.getSettings().telemetry
     if (telemetry?.existedBeforeTelemetryRelease !== true || telemetry?.optedIn !== null) {
       return
     }
-    // This path still goes through `consumeConsentMutationToken` — a
-    // compromised renderer could otherwise burn through the
-    // acknowledgeBanner channel to force unbounded settings-file writes,
-    // which is a CPU/disk amplification vector even without any event
-    // emission.
+    // Rate-limit even this silent path: unbounded acknowledge calls are a disk-write amplification vector.
     if (!consumeConsentMutationToken()) {
       return
     }
@@ -243,9 +123,7 @@ export function registerTelemetryHandlers(store: Store): void {
   })
 }
 
-// Test-only reset for the module-level store reference. Tests can
-// re-register handlers against a fresh mock store without leaking state
-// between describes.
+// Test-only reset so tests can re-register handlers without leaking store state between describes.
 export function _resetStoreForTests(): void {
   storeRef = null
 }
diff --git a/src/main/ipc/worktree-remote.ts b/src/main/ipc/worktree-remote.ts
index 8c8d4580d24..014e04a583a 100644
--- a/src/main/ipc/worktree-remote.ts
+++ b/src/main/ipc/worktree-remote.ts
@@ -1,11 +1,5 @@
 /* eslint-disable max-lines */
-// Why: extracted from worktrees.ts to keep the main IPC module under the
-// max-lines threshold. Worktree creation helpers (local and remote) live
-// here so the IPC dispatch file stays focused on handler wiring. The
-// sparse-checkout flow plus the post-create setup-runner wiring pushed
-// this file marginally over the per-file limit; matches the
-// eslint-disable pattern other files in src/renderer use when a
-// cohesive flow would split awkwardly.
+// Why: worktree create helpers (local + remote) split out of worktrees.ts; the cohesive create flow runs this file just over the per-file line limit.
 
 import type { BrowserWindow } from 'electron'
 import { posix, win32 } from 'node:path'
@@ -128,8 +122,7 @@ import {
 
 const SSH_WORKTREE_CREATE_FETCH_FRESHNESS_MS = 30_000
 const SSH_WORKTREE_CREATE_FETCH_CACHE_MAX = 512
-// Why: bound the create-path fallback `git fetch origin` so a Windows
-// credential-manager GUI hang (STA-1292) can't wedge worktree creation forever.
+// Why: bound the fallback `git fetch origin` so a Windows credential-manager GUI hang (STA-1292) can't wedge worktree creation forever.
 const CREATE_BASE_FALLBACK_FETCH_TIMEOUT_MS = 60_000
 const sshWorktreeCreateFetchInflight = new Map<string, Promise<void>>()
 const sshWorktreeCreateFetchCompletedAt = new Map<string, number>()
@@ -276,9 +269,7 @@ async function spawnLocalStartupAndSetupTerminals(args: {
   }
 
   try {
-    // Why: after `git worktree add` and metadata registration, a runtime-owned
-    // PTY can begin booting the selected agent while setup runs in a sibling
-    // terminal. Earlier than this, the worktree path is not yet safe for agents.
+    // Why: only after `git worktree add` + metadata registration is the path safe for a runtime PTY to boot the agent while setup runs alongside.
     if (isTuiAgent(createdWithAgent)) {
       const preset = TUI_AGENT_CONFIG[createdWithAgent].preflightTrust
       try {
@@ -462,8 +453,7 @@ async function getOrStartSshWorktreeCreateFetch(
       return
     }
     await fetch()
-    // Why: SSH creation has no OrcaRuntimeService instance to share, but
-    // repeated creates on the same target should still reuse recent fetches.
+    // Why: SSH creation has no OrcaRuntimeService to share; still reuse recent fetches for repeated creates on the same target.
     rememberSshWorktreeCreateFetchCompletedAt(key)
   }).finally(() => {
     if (sshWorktreeCreateFetchInflight.get(key) === promise) {
@@ -520,8 +510,7 @@ async function unsetRemoteWorktreeCreationBase(
       worktreePath
     )
   } catch {
-    // Best-effort SSH sparse cleanup; keep the sparse setup error as the
-    // actionable failure and let removeWorktree handle the partial checkout.
+    // Best-effort cleanup; keep the sparse setup error as the actionable failure.
   }
 }
 
@@ -686,10 +675,7 @@ async function hasRemoteWorktreeBaseRef(
   return hasRemoteCommitObject(provider, repoPath, baseRef)
 }
 
-// Why: hasRemoteCommitObject only resolves full SHAs; a remote-tracking base is
-// a symbolic ref (refs/remotes/origin/main), so detect its presence directly so
-// SSH creates can fall back to an existing local base ref when the refresh
-// fetch fails. Require a resolved object id: a missing ref exits non-zero.
+// Why: hasRemoteCommitObject resolves only SHAs, not symbolic remote-tracking refs; detect those directly for the fetch-failed local fallback.
 async function hasRemoteTrackingRefSsh(
   provider: SshGitProvider,
   repoPath: string,
@@ -798,8 +784,7 @@ async function hasSshRemoteBranchConflict(
       if (isAllowedSshRemoteBaseRef(refName, allowedBaseRef)) {
         return false
       }
-      // Why: `git branch --all --list feature/x` does not match
-      // `remotes/origin/feature/x`; parse remote refs directly instead.
+      // Why: `git branch --all --list feature/x` doesn't match `remotes/origin/feature/x`; parse remote refs directly.
       return resolveSshRemoteBranchName(refName, remoteNames) === branchName
     })
   } catch {
@@ -1126,8 +1111,7 @@ async function prepareWorktreePushTargetSsh(
     const existingRemote = await findRemoteForUrlSsh(provider, repoPath, target.remoteUrl)
     if (existingRemote) {
       remoteName = existingRemote
-      // Why: if a later PR worktree reuses an Orca-created fork remote, it
-      // must inherit ownership so deleting the final user can remove it.
+      // Why: a reused Orca-created fork remote must inherit ownership so deleting the final user can remove it.
       remoteCreated = store
         ? isPushTargetRemoteCreatedByKnownWorktree(
             store,
@@ -1338,8 +1322,7 @@ export async function prefetchRemoteWorktreeCreateBase(
   repo: Repo,
   args: { baseBranch?: string }
 ): Promise<void> {
-  // Why: the shared base-plan probes use generic git.exec, and some relays
-  // require the repo root to be registered before those probes can see refs.
+  // Why: base-plan probes use generic git.exec, and some relays require the repo root registered before probes can see refs.
   await registerOptionalSshWorktreeCreateRoots(repo.connectionId!, [repo.path])
   const basePlan = await getOrStartRemoteWorktreeCreateBasePlan(provider, repo, args.baseBranch)
   if (!basePlan) {
@@ -1355,13 +1338,11 @@ export async function prefetchRemoteWorktreeCreateBase(
     }
   }
   if (await hasRemoteWorktreeBaseRef(provider, repo.path, basePlan.baseBranch)) {
-    // Why: PR/MR resolvers already fetched verified SHA start points. A broad
-    // remote fetch only updates unrelated refs when the commit object exists.
+    // Why: PR/MR resolvers already fetched verified SHA start points; a broad fetch only updates unrelated refs.
     return
   }
 
-  // Why: mirrors createRemoteWorktree's legacy local-base fallback so
-  // prefetch and create share one process-local SSH fetch cache.
+  // Why: mirrors createRemoteWorktree's legacy local-base fallback so prefetch and create share one process-local SSH fetch cache.
   await fetchRemoteForWorktreeCreate(provider, repo, 'origin')
 }
 
@@ -1411,8 +1392,7 @@ async function evaluateRemoteLocalBaseRefRefreshability(
 
   let behind = 0
   try {
-    // Why: SSH generic git.exec is allowlisted. `merge-base` and `log` are
-    // allowed read-only probes; `rev-list` is intentionally not exposed there.
+    // Why: SSH generic git.exec is allowlisted — merge-base and log are permitted read-only probes; rev-list is intentionally not exposed.
     await provider.exec(['merge-base', '--is-ancestor', fullRef, remoteTrackingBase.ref], repoPath)
     const { stdout } = await provider.exec(
       ['log', '--format=%H', `${fullRef}..${remoteTrackingBase.ref}`],
@@ -1420,8 +1400,7 @@ async function evaluateRemoteLocalBaseRefRefreshability(
     )
     behind = countNonEmptyGitOutputLines(stdout)
     if (!shouldInspectOwner(behind)) {
-      // Why: no behind commits means the advisory cannot offer an update;
-      // avoid remote worktree/status round trips that cannot change that.
+      // Why: no behind commits means no update to advise; skip remote worktree/status round trips.
       return {
         refreshable: true,
         ...resultBase,
@@ -1462,8 +1441,7 @@ async function evaluateRemoteLocalBaseRefRefreshability(
       }
     }
 
-    // Why: not checked out anywhere — a bare ref fast-forward is safe. Omitting
-    // ownerWorktreePath tells the relay to update-ref instead of reset --hard.
+    // Why: not checked out anywhere, so a bare-ref fast-forward is safe; omitting ownerWorktreePath tells the relay to update-ref, not reset --hard.
     return {
       refreshable: true,
       ...resultBase,
@@ -1509,8 +1487,7 @@ async function getRemoteLocalBaseRefUpdateSuggestionForWorktreeCreate(
 }
 
 export function notifyWorktreesChanged(mainWindow: BrowserWindow, repoId: string): void {
-  // Why: invalidate detected-worktree caches before renderer observers react,
-  // so follow-up listDetected reads post-change state.
+  // Why: invalidate detected-worktree caches before renderer observers react, so follow-up listDetected sees post-change state.
   runWorktreeChangeInvalidators(repoId)
   if (!mainWindow.isDestroyed()) {
     mainWindow.webContents.send('worktrees:changed', { repoId })
@@ -1521,8 +1498,7 @@ export function notifyWorktreeGitStatusMetadataChanged(
   mainWindow: BrowserWindow,
   repoId: string
 ): void {
-  // Why: index churn is a Source Control freshness hint, not a worktree graph
-  // mutation; keep structural caches and runtime/mobile events untouched.
+  // Why: index churn is a Source Control freshness hint, not a graph mutation; leave structural caches and runtime/mobile events untouched.
   if (!mainWindow.isDestroyed()) {
     mainWindow.webContents.send('worktrees:gitStatusMetadataChanged', { repoId })
   }
@@ -1533,18 +1509,13 @@ export function notifyWorktreeHeadIdentitiesChanged(
   repoId: string,
   identities: WorktreeHeadIdentity[]
 ): void {
-  // Why: background worktrees have no active-scoped status refresh, so head
-  // moves detected from metadata files ride this targeted desktop event
-  // instead of re-entering the structural fanout or runtime/mobile events.
+  // Why: background worktrees have no active status refresh, so metadata-detected head moves ride this targeted event instead of the structural fanout.
   if (!mainWindow.isDestroyed()) {
     mainWindow.webContents.send('worktrees:headIdentitiesChanged', { repoId, identities })
   }
 }
 
-// Why: two-phase spinner. Main process fires `'fetching'` before waiting on
-// pre-create fetch work and `'creating'` immediately before `git worktree add`.
-// Renderer swaps its spinner label in response; fallback is the static
-// "Creating worktree..." label if no event arrives.
+// Why: two-phase spinner — fire 'fetching' before pre-create fetch and 'creating' before git worktree add so the renderer can swap its label.
 export function emitCreateWorktreeProgress(
   mainWindow: BrowserWindow,
   phase: 'fetching' | 'creating',
@@ -1574,24 +1545,17 @@ export async function createRemoteWorktree(
     ? sanitizeWorktreeDisplayName(args.displayName)
     : undefined
 
-  // Why: resolving the create base can probe repo refs through generic git.exec.
-  // Register the repo root first so relays do not report a valid base as stale.
+  // Why: base resolution probes refs via generic git.exec; register the repo root first so relays don't report a valid base as stale.
   await registerRequiredSshWorktreeCreateRoots(repo.connectionId!, [repo.path])
 
-  // Why: explicit branches and non-username prefix modes never consume this
-  // value; skipping the remote config probes preserves the exact branch name.
+  // Why: explicit branches and non-username prefix modes never consume this; skipping the remote probe preserves the exact branch name.
   const username =
     !args.branchNameOverride && settings.branchPrefix === 'git-username'
       ? await getSshGitUsername(provider, repo.path)
       : ''
 
   const branchConflictSubject = args.branchNameOverride ? 'branch name' : 'worktree name'
-  // Determine base branch
-  // Why: previously fell back to a hardcoded 'origin/main' when
-  // symbolic-ref failed. That silently handed addWorktree a ref that may
-  // not exist on the remote (e.g. repos whose primary branch is master or
-  // develop), producing an opaque git error. Fail here with a clear
-  // message so the UI can surface it and prompt the user to pick a base.
+  // Why: don't fall back to hardcoded 'origin/main'; it may not exist (master/develop) and yields an opaque git error, so fail clearly and let the UI prompt.
   const basePlan = await getOrStartRemoteWorktreeCreateBasePlan(provider, repo, args.baseBranch)
   if (!basePlan) {
     throw new Error(
@@ -1607,8 +1571,7 @@ export async function createRemoteWorktree(
   let selectedExistingLocalBranchName: string | null = null
   let lastBranchConflictKind: 'local' | 'remote' | null = null
   let remotePathResolved = false
-  // Why: duplicate PR/MR checkouts still need a workspace; suffix the local
-  // branch/path while preserving the review metadata and push target.
+  // Why: duplicate PR/MR checkouts still need a workspace; suffix branch/path while preserving review metadata and push target.
   for (let suffix = 1; suffix <= WORKTREE_CREATE_MAX_SUFFIX_ATTEMPTS; suffix += 1) {
     effectiveSanitizedName = getWorktreeCreateCandidate(sanitizedName, suffix)
     effectiveRequestedName = args.name.trim()
@@ -1630,8 +1593,7 @@ export async function createRemoteWorktree(
       baseBranch
     )
     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.
+      // Why: once a user-selected branch is safe to reuse, path retries keep it exact instead of creating a sibling.
       selectedExistingLocalBranchName = branchName
     }
     lastBranchConflictKind = checkoutExistingBranch
@@ -1705,8 +1667,7 @@ export async function createRemoteWorktree(
     }
   }
 
-  // Why: addWorktree and setup probes run inside the new worktree path; older
-  // relays need that root registered before accepting git/fs operations there.
+  // Why: addWorktree/setup probes run inside the new path; older relays need that root registered before accepting git/fs ops there.
   await registerRequiredSshWorktreeCreateRoots(repo.connectionId!, [remotePath])
 
   if (remoteTrackingBase) {
@@ -1726,13 +1687,7 @@ export async function createRemoteWorktree(
     try {
       await refreshRemoteTrackingBaseForWorktreeCreate(provider, repo, remoteTrackingBase)
     } catch {
-      // Why: a failed refresh must not block creation when a usable local base
-      // ref already exists — `git worktree add` can still create from that
-      // (possibly stale but valid) ref, so a transient offline/auth failure does
-      // not make the workspace uncreatable. Probe AFTER registerRoot so relays
-      // that gate generic git.exec accept it; only hard-fail when there is no
-      // local ref to fall back on. Drift is reflected by the compare-to-base
-      // view once the remote is reachable again.
+      // Why: a refresh failure shouldn't block create if a usable (stale) local base ref exists; probe after registerRoot and hard-fail only when none does.
       if (!(await hasRemoteTrackingRefSsh(provider, repo.path, remoteTrackingBase.ref))) {
         throw new Error(
           `Could not refresh base ref "${baseBranch}" from "${remoteTrackingBase.remote}". Check your network and try again.`
@@ -1740,9 +1695,7 @@ export async function createRemoteWorktree(
       }
     }
   } else if (!(await hasRemoteWorktreeBaseRef(provider, repo.path, baseBranch))) {
-    // Why: local or otherwise non-remote-tracking bases preserve legacy
-    // best-effort fetch behavior. Verified PR/MR SHA bases already have the
-    // commit object locally, so a broad remote fetch only updates unrelated refs.
+    // Why: non-remote-tracking bases keep the legacy best-effort fetch; verified PR/MR SHA bases already have the object, so a broad fetch is wasted.
     try {
       await fetchRemoteForWorktreeCreate(provider, repo, 'origin')
     } catch {
@@ -1775,8 +1728,7 @@ export async function createRemoteWorktree(
 
   let preparedPushTarget: GitPushTarget | undefined
   if (args.pushTarget) {
-    // Why: fork-PR SSH worktrees need the same contributor-remote setup as
-    // local worktrees before creation, otherwise Push/Sync can target origin.
+    // Why: fork-PR SSH worktrees need contributor-remote setup before create, else Push/Sync target origin.
     preparedPushTarget = await prepareWorktreePushTargetSsh(
       provider,
       repo.path,
@@ -1786,7 +1738,6 @@ export async function createRemoteWorktree(
     )
   }
 
-  // Create worktree via relay
   try {
     await timing.time('git_worktree_add', async () =>
       provider.addWorktree(
@@ -1804,12 +1755,7 @@ export async function createRemoteWorktree(
       (err.message.includes('No workspace roots registered yet') ||
         err.message.includes('Path outside authorized workspace'))
     ) {
-      // Why: only an OLD relay binary (pre-allowlist-removal) can produce
-      // these errors. New relays no-op session.registerRoot. Translate the
-      // raw error into an actionable upgrade-window message while still
-      // preserving the original string for bug reports. Tracked for removal
-      // once the relay-version floor moves past the cutover (see
-      // docs/relay-fs-allowlist-removal.md).
+      // Why: only OLD relays (pre-allowlist-removal) throw these; surface an upgrade message. Remove after version floor moves (docs/relay-fs-allowlist-removal.md).
       throw new Error(
         `Older relay reported an authorization error; please reconnect to deploy the latest relay. (${err.message})`
       )
@@ -1818,8 +1764,7 @@ export async function createRemoteWorktree(
   }
   if (sparseDirectories.length > 0) {
     try {
-      // Why: SSH providers expose generic git exec, so the remote sparse flow
-      // can mirror local addSparseWorktree without adding a relay method.
+      // Why: SSH providers expose generic git exec, so remote sparse mirrors local addSparseWorktree without a new relay method.
       await provider.exec(['sparse-checkout', 'init', '--cone'], remotePath)
       await provider.exec(['sparse-checkout', 'set', '--', ...sparseDirectories], remotePath)
       await provider.exec(['checkout', branchName], remotePath)
@@ -1830,8 +1775,7 @@ export async function createRemoteWorktree(
       await provider
         .removeWorktree(remotePath, true, {
           deleteBranch: !checkoutExistingBranch,
-          // Why: sparse setup failed before the user could work in the new
-          // branch, so rollback should remove the just-created remote branch.
+          // Why: sparse setup failed before any work happened, so rollback removes the just-created remote branch.
           forceBranchDelete: !checkoutExistingBranch
         })
         .catch(() => undefined)
@@ -1852,8 +1796,7 @@ export async function createRemoteWorktree(
 
   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.
+  // Why: PR/MR worktrees start from a head ref/SHA but Source Control must compare against the review target branch.
   const metadataBaseRef = args.compareBaseRef ?? remoteTrackingBase?.ref ?? baseBranch
   let configuredPushTarget: GitPushTarget | undefined
   if (preparedPushTarget) {
@@ -1865,20 +1808,13 @@ export async function createRemoteWorktree(
     )
   }
   const metaUpdates: Partial<WorktreeMeta> = {
-    // Why: path-derived worktree IDs can be reused after external deletion.
-    // Fresh creations must rotate instance identity so stale lineage cannot
-    // attach to the new occupant of the same path.
+    // Why: path-derived IDs get reused after external deletion; rotate instance identity so stale lineage can't attach to the new occupant.
     instanceId: randomUUID(),
     ...(store.getProjectHostSetups
       ? getProjectHostSetupWorktreeMeta(store.getProjectHostSetups(), repo)
       : {}),
     lastActivityAt: now,
-    // Why: grants the new worktree a short grace window at the top of the
-    // Recent sort. During worktree creation (git fetch + add can take several
-    // seconds) other worktrees get ambient PTY bumps that would otherwise
-    // leave the newly-created one below them; the Recent comparator uses
-    // max(lastActivityAt, createdAt + GRACE_MS) to keep it on top until the
-    // window elapses. See smart-sort.ts `CREATE_GRACE_MS`.
+    // Why: grace window atop Recent so ambient PTY bumps on others during create don't bury the new worktree. See smart-sort.ts `CREATE_GRACE_MS`.
     createdAt: now,
     orcaCreatedAt: now,
     orcaCreationSource: 'ssh',
@@ -1928,11 +1864,7 @@ export async function createRemoteWorktree(
   })
   const workspaceLineage = recordWorkspaceLineageForCreatedWorktree(store, args, worktree, now)
 
-  // Why: shared paths are intentionally not wired up for remote (SSH)
-  // worktrees. Creating symlinks on the remote host would
-  // require a new relay method and authorization surface; the feature is
-  // local-only until that protocol work is in scope. Remote repos with
-  // `symlinkPaths` configured have them silently ignored here.
+  // Why: shared/symlink paths are local-only; remote (SSH) support needs a new relay method + auth surface, so configured symlinkPaths are ignored here.
 
   let setup: CreateWorktreeResult['setup']
   let defaultTabs: CreateWorktreeResult['defaultTabs']
@@ -1943,8 +1875,7 @@ export async function createRemoteWorktree(
       try {
         defaultTabs = getDefaultTabsLaunch(yamlHooks, repo, args.setupDecision)
       } catch (error) {
-        // Why: default tab commands share setup's run policy. If the target branch
-        // adds commands without a renderer decision, create the tabs but don't run them.
+        // Why: default tab commands share setup's run policy; without a renderer decision, create the tabs but don't run them.
         console.warn(`[hooks] default tab commands skipped for ${created.path}:`, error)
         defaultTabs = yamlHooks?.defaultTabs
           ? { tabs: yamlHooks.defaultTabs, runCommands: false }
@@ -1956,9 +1887,7 @@ export async function createRemoteWorktree(
         try {
           shouldLaunchSetup = shouldRunSetupForCreate(repo, args.setupDecision)
         } catch (error) {
-          // Why: the remote worktree already exists. If the created branch adds
-          // a setup hook without a renderer decision, skip setup instead of
-          // reporting successful git creation as failed.
+          // Why: worktree already exists; skip setup rather than fail a successful git create when the branch adds a hook without a renderer decision.
           console.warn(`[hooks] setup hook skipped for ${created.path}:`, error)
         }
       }
@@ -2018,8 +1947,7 @@ export async function createLocalWorktree(
   const requestedDisplayName = args.displayName
     ? sanitizeWorktreeDisplayName(args.displayName)
     : undefined
-  // Why: explicit branches and non-username prefix modes never consume this
-  // value; skipping the probes preserves the exact generated branch name.
+  // Why: explicit branches and non-username prefix modes never consume this; skipping the probe preserves the exact generated branch name.
   const username =
     !args.branchNameOverride && settings.branchPrefix === 'git-username'
       ? await resolveLocalGitUsername(repo.path)
@@ -2057,11 +1985,7 @@ export async function createLocalWorktree(
     }
   })
   if (!baseBranch) {
-    // Why: resolveDefaultBaseRefViaExec may return null when none of origin/HEAD,
-    // origin/main, origin/master, local main, or local master exist. Don't
-    // fall back to a hardcoded 'origin/main' — passing a non-existent ref to
-    // `git worktree add` produces an opaque error. Fail here with a clear
-    // message so the UI can prompt the user to pick a base branch explicitly.
+    // Why: no default base resolved; fail clearly rather than pass a hardcoded non-existent ref to git worktree add (opaque error) so the UI can prompt.
     throw new Error(
       'Could not resolve a default base ref for this repo. Pick a base branch explicitly and try again.'
     )
@@ -2107,10 +2031,7 @@ export async function createLocalWorktree(
     } else if (
       !(await hasLocalWorktreeBaseRefWithOptions(repo.path, baseBranch, localWorktreeGitOptions))
     ) {
-      // Why: when the base branch does not match a configured remote prefix
-      // (e.g. plain `main`, `master`, or any local branch), the legacy path
-      // still ran a best-effort `git fetch origin`. Verified PR SHA bases
-      // already have the needed commit object, so skip that broad fetch.
+      // Why: non-remote-prefix bases (plain main/master/local) keep the legacy best-effort fetch; verified PR SHA bases already have the object.
       legacyFetchPromise = runtime
         .fetchRemoteWithCache(repo.path, 'origin', ...localWorktreeGitOptionArgs)
         .then(() => undefined)
@@ -2132,8 +2053,7 @@ export async function createLocalWorktree(
   }
   const workspaceRoot = computeWorkspaceRoot(repo.path, worktreePathSettings)
 
-  // Why: this validation does not depend on remote refs, so it can overlap a
-  // required remote-tracking base refresh.
+  // Why: this validation doesn't depend on remote refs, so it can overlap a required remote-tracking base refresh.
   const primarySetupScript = getEffectiveHooks(repo)?.scripts.setup
   if (primarySetupScript) {
     shouldRunSetupForCreate(repo, args.setupDecision)
@@ -2152,8 +2072,7 @@ export async function createLocalWorktree(
     if (preset?.repoId === repo.id) {
       try {
         const presetDirectories = normalizeSparseDirectories(preset.directories)
-        // Why: use Set-based comparison so directory order does not affect
-        // attribution — matches the renderer's sparseDirectoriesMatch logic.
+        // Why: Set-based compare so directory order doesn't affect attribution — matches renderer's sparseDirectoriesMatch.
         const presetSet = new Set(presetDirectories)
         const directoriesMatch =
           presetDirectories.length === sparseDirectories.length &&
@@ -2177,8 +2096,7 @@ export async function createLocalWorktree(
   let lastBranchConflictKind: 'local' | 'remote' | null = null
   let lastExistingPR: Awaited<ReturnType<typeof getPRForBranch>> | null = null
   let lastExistingReviewNumber: number | null = null
-  // Why: create-from-review can provide an exact branch override that already
-  // exists locally; suffix both branch and path instead of blocking the user.
+  // Why: a create-from-review branch override may already exist locally; suffix both branch and path instead of blocking the user.
   for (let suffix = 1; suffix <= WORKTREE_CREATE_MAX_SUFFIX_ATTEMPTS; suffix += 1) {
     effectiveSanitizedName = getWorktreeCreateCandidate(sanitizedName, suffix)
     effectiveRequestedName = requestedName.trim()
@@ -2203,8 +2121,7 @@ export async function createLocalWorktree(
       localWorktreeGitOptions
     )
     if (checkoutExistingBranch && !selectedExistingLocalBranchName) {
-      // Why: suffix retries may need a new path, but an existing branch checkout
-      // must keep using the user-selected branch instead of creating a sibling.
+      // Why: suffix retries may need a new path, but an existing-branch checkout must keep the user-selected branch, not a sibling.
       selectedExistingLocalBranchName = branchName
     }
     lastBranchConflictKind = checkoutExistingBranch
@@ -2252,12 +2169,7 @@ export async function createLocalWorktree(
       continue
     }
 
-    // Why: `gh pr list` is a network round-trip that previously ran on every
-    // create, adding ~1–3s to the happy path even when no conflict exists. We
-    // only probe PR conflicts once a local/remote branch collision has already
-    // forced us past the first suffix — at that point uniqueness matters
-    // enough to justify the GitHub call. The common case (brand-new branch
-    // name, no collisions) skips the network entirely.
+    // Why: gh pr list is a ~1–3s network call; only probe PR conflicts after a branch collision (suffix > 1) so the common no-collision path skips it.
     if (suffix > 1 && !checkoutExistingBranch) {
       lastExistingPR = null
       try {
@@ -2288,9 +2200,7 @@ export async function createLocalWorktree(
   }
 
   if (!resolved) {
-    // Why: if every suffix in range collides, fall back to the original
-    // "reject with a specific reason" behavior so the user sees why creation
-    // failed instead of a generic error or (worse) an infinite spinner.
+    // Why: every suffix collided; reject with a specific reason so the user sees why create failed instead of a generic error or hung spinner.
     if (lastExistingReviewNumber !== null) {
       throw new Error(
         `Branch "${branchName}" already has PR #${lastExistingReviewNumber}. Pick a different ${branchConflictSubject}.`
@@ -2316,12 +2226,7 @@ export async function createLocalWorktree(
     await timing.time('refresh_base_ref', async () => {
       const result = await remoteTrackingRefresh.promise
       if (!result.ok && !remoteTrackingRefresh.hadLocalBaseRef) {
-        // Why: only block creation when the refresh failed AND there is no local
-        // base ref to fall back on. An existing local remote-tracking ref lets
-        // `git worktree add` proceed from a possibly stale but valid base, so a
-        // transient offline/auth failure must not make the workspace
-        // uncreatable. The compare-to-base view reflects any drift once the
-        // remote is reachable again.
+        // Why: only block create when the refresh failed AND there's no local base ref; an existing (possibly stale) ref keeps worktree add viable.
         throw new Error(
           `Could not refresh base ref "${baseBranch}" from "${remoteTrackingRefresh.base.remote}". Check your network and try again.`
         )
@@ -2348,9 +2253,7 @@ export async function createLocalWorktree(
 
   let preparedPushTarget: GitPushTarget | undefined
   if (args.pushTarget) {
-    // Why: validate and fetch the contributor remote before creating the
-    // worktree. If this fails, retrying won't hit branch/path conflicts from a
-    // half-created worktree.
+    // Why: validate/fetch the contributor remote before create so a failure doesn't leave a half-created worktree with conflicts on retry.
     preparedPushTarget = await prepareWorktreePushTarget(
       repo.path,
       args.pushTarget,
@@ -2460,10 +2363,7 @@ export async function createLocalWorktree(
 
   let configuredPushTarget: GitPushTarget | undefined
   if (preparedPushTarget) {
-    // Why: fork-PR review worktrees should publish commits back to the PR
-    // author's branch. Configure the branch upstream immediately so the
-    // existing Push/Pull/Sync controls use the contributor remote instead of
-    // silently defaulting to origin.
+    // Why: fork-PR review worktrees publish back to the PR author's branch; set upstream so Push/Sync use the contributor remote, not origin.
     configuredPushTarget = await configureCreatedWorktreePushTarget(
       worktreePath,
       branchName,
@@ -2485,23 +2385,17 @@ export async function createLocalWorktree(
 
   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.
+  // Why: PR/MR worktrees start from a head ref/SHA but Source Control must compare against the review target branch.
   const metadataBaseRef = args.compareBaseRef ?? remoteTrackingBase?.ref ?? baseBranch
   const metaUpdates: Partial<WorktreeMeta> = {
-    // Why: path-derived worktree IDs can be reused after external deletion.
-    // Fresh creations must rotate instance identity so stale lineage cannot
-    // attach to the new occupant of the same path.
+    // Why: path-derived IDs can be reused after external deletion; rotate instance identity so stale lineage can't attach to the new occupant.
     instanceId: randomUUID(),
     ...(store.getProjectHostSetups
       ? getProjectHostSetupWorktreeMeta(store.getProjectHostSetups(), repo)
       : {}),
-    // Stamp activity so the worktree sorts into its final position
-    // immediately — prevents scroll-to-reveal racing with a later
-    // bumpWorktreeActivity that would re-sort the list.
+    // Stamp activity so the worktree sorts into its final position immediately, avoiding a re-sort race with scroll-to-reveal.
     lastActivityAt: now,
-    // See createRemoteWorktree above: createdAt protects the newly-created
-    // worktree from ambient PTY bumps in other worktrees for CREATE_GRACE_MS.
+    // createdAt protects the new worktree from ambient PTY bumps for CREATE_GRACE_MS (see createRemoteWorktree above).
     createdAt: now,
     orcaCreatedAt: now,
     orcaCreationSource: 'desktop',
@@ -2550,17 +2444,13 @@ export async function createLocalWorktree(
     return { worktree: mergeWorktree(repo.id, created, meta) }
   })
   const workspaceLineage = recordWorkspaceLineageForCreatedWorktree(store, args, worktree, now)
-  // Why: creation already paid for `git worktree list`; seed the exact roots
-  // now so the next file/git IPC does not lazily rescan and trip macOS privacy
-  // prompts for the newly-created workspace.
+  // Why: reuse the roots creation already paid for via `git worktree list` so later IPC doesn't lazily rescan and trip macOS privacy prompts.
   registerWorktreeRootsForRepo(store, repo.id, [
     repo.path,
     ...gitWorktrees.map((worktree) => worktree.path)
   ])
 
-  // Why: materialize user-configured paths from the primary checkout into the
-  // new worktree before any setup script runs, so scripts that reuse shared
-  // state (e.g. `node_modules`, `.env`) see those paths already in place.
+  // Why: link user-configured shared paths (e.g. `node_modules`, `.env`) before setup runs so setup scripts see them in place.
   const symlinkPaths = repo.symlinkPaths ?? []
   if (symlinkPaths.length > 0) {
     await timing.time('create_symlinks', async () => {
@@ -2568,15 +2458,7 @@ export async function createLocalWorktree(
     })
   }
 
-  // Why: the worktree's own `orca.yaml` (at the tip of the base branch) is
-  // authoritative for what runs post-creation. The repo-level trust already
-  // granted by the user in the pre-create flow covers execution of that
-  // script; we intentionally do not re-gate on content equality with the
-  // primary checkout's preview, because benign divergence (whitespace,
-  // comments, or any setup-script edit that has landed on the base branch
-  // but not yet been pulled into the primary checkout) was silently
-  // disabling setup with no UI signal. See #1280 for the original gate and
-  // the regression this replaced.
+  // Why: the worktree's base-branch `orca.yaml` is authoritative; we don't re-gate on content parity with the primary checkout since benign divergence silently disabled setup (#1280).
   let setup: CreateWorktreeResult['setup']
   let defaultTabs: CreateWorktreeResult['defaultTabs']
   await timing.time('prepare_setup', async () => {
@@ -2585,8 +2467,7 @@ export async function createLocalWorktree(
     try {
       defaultTabs = getDefaultTabsLaunch(createdYamlHooks, repo, args.setupDecision)
     } catch (error) {
-      // Why: default tab commands share setup's run policy. If the target branch
-      // adds commands without a renderer decision, create the tabs but don't run them.
+      // Why: default tab commands share setup's run policy; if the target branch adds commands without a renderer decision, create the tabs but don't run them.
       console.warn(`[hooks] default tab commands skipped for ${worktreePath}:`, error)
       defaultTabs = createdYamlHooks?.defaultTabs
         ? { tabs: createdYamlHooks.defaultTabs, runCommands: false }
@@ -2598,24 +2479,14 @@ export async function createLocalWorktree(
       try {
         shouldLaunchSetup = shouldRunSetupForCreate(repo, args.setupDecision)
       } catch (error) {
-        // Why: if the target branch introduces setup hooks that the primary
-        // checkout did not expose, the renderer may not have collected an ask
-        // decision. The worktree already exists, so skip setup instead of
-        // turning successful git creation into an IPC failure.
+        // Why: target branch may add setup hooks the renderer never collected a decision for; worktree exists, so skip setup rather than fail creation.
         console.warn(`[hooks] setup hook skipped for ${worktreePath}:`, error)
       }
     }
     if (setupScript && shouldLaunchSetup) {
       try {
-        // Why: setup now runs in a visible terminal owned by the renderer so users
-        // can inspect failures, answer prompts, and rerun it. The main process only
-        // resolves policy and writes the runner script; it must not execute setup
-        // itself anymore or we would reintroduce the hidden background-hook behavior.
-        //
-        // Why: the git worktree already exists at this point. If runner generation
-        // fails, surfacing the error as a hard create failure would lie to the UI
-        // about the underlying git state and strand a real worktree on disk.
-        // Degrade to "created without setup launch" instead.
+        // Why: main only writes the runner script and must not execute setup itself, or we reintroduce the old hidden background-hook behavior.
+        // Why: worktree already exists, so a runner-gen failure degrades to "created without setup launch" rather than failing creation.
         setup = createSetupRunnerScript(
           repo,
           worktreePath,
diff --git a/src/main/ipc/worktrees.test.ts b/src/main/ipc/worktrees.test.ts
index 201a85c35aa..3dcf1d46593 100644
--- a/src/main/ipc/worktrees.test.ts
+++ b/src/main/ipc/worktrees.test.ts
@@ -432,9 +432,7 @@ describe('registerWorktreeHandlers', () => {
     getHostedReviewForBranchMock.mockResolvedValue(null)
     getWorkItemMock.mockResolvedValue(null)
     getPullRequestPushTargetMock.mockResolvedValue(null)
-    // Why: createLocalWorktree can still hit legacy git fetch fallback in
-    // narrow unit harnesses. Return a resolved promise so catch/then chains
-    // don't trip on undefined.
+    // Why: createLocalWorktree can still hit the legacy git fetch fallback here; resolve so catch/then chains don't trip on undefined.
     gitExecFileAsyncMock.mockResolvedValue({ stdout: '', stderr: '' })
     getEffectiveHooksMock.mockReturnValue(null)
     getEffectiveHooksFromConfigMock.mockImplementation(() => getEffectiveHooksMock())
@@ -489,10 +487,7 @@ describe('registerWorktreeHandlers', () => {
     listWorktreesMock.mockResolvedValue([])
     forceDeleteLocalBranchMock.mockResolvedValue(undefined)
 
-    // Why: createLocalWorktree routes `git fetch` through
-    // `runtime.fetchRemoteWithCache` (§3.3 Lifecycle). A minimal stub
-    // keeps these tests focused on create-flow semantics; the full
-    // cache behavior is covered by fetch-remote-cache.test.ts.
+    // Why: minimal stub keeps these tests on create-flow semantics; full fetchRemoteWithCache behavior is covered by fetch-remote-cache.test.ts.
     runtimeStub = {
       resolveRemoteTrackingBase: vi.fn().mockResolvedValue(null),
       hasRemoteTrackingRef: vi.fn().mockResolvedValue(false),
@@ -795,8 +790,7 @@ describe('registerWorktreeHandlers', () => {
       worktreeId: 'repo-1::/workspace/feature-wt',
       updates: { isUnread: false }
     })
-    // Why: per-click isUnread writes must stay event-free (PR #209), while a
-    // rename must reach paired remote clients that no longer poll for titles.
+    // Why: per-click isUnread writes must stay event-free (PR #209), while a rename must reach paired remote clients that no longer poll for titles.
     expect(runtimeStub.notifyWorktreesChangedForRemoteClients).not.toHaveBeenCalled()
 
     handlers['worktrees:updateMeta'](null, {
@@ -842,8 +836,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('auto-suffixes the branch name when the first choice collides with a remote branch', async () => {
-    // Why: new-workspace flow should silently try improve-dashboard-2, -3, ...
-    // rather than failing and forcing the user back to the name picker.
+    // Why: new-workspace flow should silently try improve-dashboard-2, -3, … rather than failing back to the name picker.
     getBranchConflictKindMock.mockImplementation(async (_repoPath: string, branch: string) =>
       branch === 'improve-dashboard' ? 'remote' : null
     )
@@ -1236,9 +1229,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('reuses an existing local branch when the worktree folder is renamed (#5181)', async () => {
-    // Why: the reuse checkbox keeps branchNameOverride pinned to the selected
-    // branch while the worktree folder is named independently. The backend must
-    // still check out that exact branch (no -b) into the renamed folder.
+    // Why: reuse keeps branchNameOverride on the selected branch though the folder is renamed; backend must check out that branch (no -b).
     listWorktreesMock
       .mockResolvedValueOnce([
         {
@@ -4026,8 +4017,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('creates an SSH worktree from the detected default base when the persisted base is stale', async () => {
-    // Regression: a stale persisted repo base must fall back to the detected
-    // primary default instead of blocking creation.
+    // Regression: a stale persisted repo base must fall back to the detected primary default instead of blocking creation.
     const repo = {
       id: 'repo-ssh',
       path: '/remote/repo',
@@ -4901,8 +4891,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('creates from the detected default base when the persisted base is stale', async () => {
-    // Regression: a stale persisted repo base must fall back to the detected
-    // primary default instead of blocking creation.
+    // Regression: a stale persisted repo base must fall back to the detected primary default instead of blocking creation.
     const remoteBase = {
       remote: 'origin',
       branch: 'main',
@@ -5206,11 +5195,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('throws a clear error when no default base ref can be resolved', async () => {
-    // Why: guard against regressing to a silent 'origin/main' fallback. When
-    // default-base resolution returns null (e.g. a fresh repo with no origin/HEAD,
-    // no origin/main, no origin/master, and no local main/master), we must
-    // fail loudly with a message that prompts the user to pick a base
-    // branch, not hand a non-existent ref to `git worktree add`.
+    // Why: guard against regressing to a silent 'origin/main' fallback; an unresolved default base must fail loudly, not hand a non-existent ref to `git worktree add`.
     resolveDefaultBaseRefWithLocalGitMock.mockResolvedValue(null)
     store.getRepo.mockReturnValue({
       id: 'repo-1',
@@ -5588,10 +5573,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('stamps lastActivityAt on first discovery so newly-added worktrees sort to the top of Recent', async () => {
-    // Why: a worktree that exists on disk but has no persisted WorktreeMeta
-    // (e.g. a folder repo just added, or a pre-existing worktree in a
-    // newly-added git repo) would otherwise fall back to `lastActivityAt: 0`
-    // and rank dead last in the Recent sort.
+    // Why: a worktree on disk with no persisted WorktreeMeta would otherwise fall back to lastActivityAt: 0 and rank dead last in Recent.
     listWorktreesMock.mockResolvedValue([
       {
         path: '/workspace/discovered-wt',
@@ -5631,9 +5613,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('backfills project-host ownership without re-stamping lastActivityAt for existing meta', async () => {
-    // Why: only the *first* discovery should stamp. Re-stamping on every list
-    // would overwrite real activity and reshuffle the sidebar on refresh. Host
-    // ownership can still be filled because it is derived from the repo setup.
+    // Why: only first discovery stamps (re-stamping would reshuffle the sidebar); host ownership is still backfilled since it derives from repo setup.
     listWorktreesMock.mockResolvedValue([
       {
         path: '/workspace/existing-wt',
@@ -5685,9 +5665,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('repairs legacy project ids when discovery now resolves the same host setup to a logical project', async () => {
-    // Why: provider identity can become available after metadata was written.
-    // Existing workspaces should move from repo-scoped IDs to the logical
-    // project ID without losing activity ordering.
+    // Why: provider identity can arrive after metadata was written; existing workspaces must move to the logical project ID without losing activity ordering.
     listWorktreesMock.mockResolvedValue([
       {
         path: '/workspace/existing-wt',
@@ -5948,9 +5926,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('stamps lastActivityAt on first discovery for folder-mode repos', async () => {
-    // Why: folder repos produce a synthetic worktree that flows through the
-    // same list path. Without the stamp, adding a folder puts its card at the
-    // bottom of Recent even though the user just added it.
+    // Why: folder repos produce a synthetic worktree; without the stamp a just-added folder sorts to the bottom of Recent.
     store.getRepos.mockReturnValue([
       {
         id: 'repo-1',
@@ -5991,9 +5967,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('stamps lastActivityAt on first discovery via worktrees:listAll', async () => {
-    // Why: the stamping logic lives in both worktrees:list and worktrees:listAll.
-    // Without a dedicated test, a regression in the listAll loop would silently
-    // bury newly-discovered worktrees from the multi-repo sidebar view.
+    // Why: stamping logic is duplicated in worktrees:list and worktrees:listAll; a listAll regression would silently bury newly-discovered worktrees.
     listWorktreesMock.mockResolvedValue([
       {
         path: '/workspace/discovered-wt',
@@ -6022,9 +5996,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('omits prunable worktrees from worktrees:listAll', async () => {
-    // Why: a prunable registration has no working directory (issue #8389), so
-    // surfacing it as a workspace yields repeated pty:spawn/fs:readDir
-    // failures and a blank pane.
+    // Why: a prunable registration has no working directory (issue #8389), so surfacing it yields repeated pty/fs failures and a blank pane.
     listWorktreesMock.mockResolvedValue([
       {
         path: '/workspace/repo',
@@ -6138,13 +6110,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('skips past a suffix that already belongs to a PR after an initial branch conflict', async () => {
-    // Why: `gh pr list` is network-bound and previously fired on every single
-    // create, adding 1–3s to the happy path. We now only probe PR conflicts
-    // from suffix=2 onward — once a local/remote branch collision has already
-    // forced us past the first candidate and uniqueness matters enough to
-    // justify the GitHub round-trip. This test covers that delayed path:
-    // suffix=1 is a branch conflict, suffix=2 is owned by an old PR, so the
-    // loop lands on suffix=3.
+    // Why: the PR-conflict probe (network-bound, 1–3s) only runs from suffix=2 onward, after a branch collision already forced past the first candidate.
     getBranchConflictKindMock.mockImplementation(async (_repoPath: string, branch: string) =>
       branch === 'improve-dashboard' ? 'remote' : null
     )
@@ -6192,10 +6158,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('does not call `gh pr list` on the happy path (no branch conflict)', async () => {
-    // Why: guards the speed optimization. If a future refactor accidentally
-    // reintroduces the PR probe on the first iteration, the happy path will
-    // silently regain a 1–3s GitHub round-trip per click; this test fails
-    // loudly instead.
+    // Why: guard against a refactor reintroducing the PR probe on the happy path (1–3s GitHub round-trip per click).
     listWorktreesMock.mockResolvedValue([
       {
         path: '/workspace/improve-dashboard',
@@ -6317,10 +6280,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('launches setup even when primary and worktree orca.yaml scripts diverge', async () => {
-    // Why: regression for a silent skip introduced by the #1280 content-equality
-    // gate. Benign divergence (whitespace, comments, or any setup edit that
-    // landed on the base branch but not yet in the primary checkout) must not
-    // disable setup — repo-level trust already gates execution.
+    // Why: benign orca.yaml divergence must not disable setup (regression from #1280 content-equality gate); repo trust already gates execution.
     listWorktreesMock.mockResolvedValue(createdWorktreeList)
     getEffectiveHooksMock.mockImplementation((_repo, worktreePath?: string) => ({
       scripts: {
@@ -8748,8 +8708,7 @@ describe('registerWorktreeHandlers', () => {
       const worktreeId = 'repo-1::/workspace/feature-wt'
       store.getRepo.mockReturnValue(repo)
       getLocalPtyProviderMock.mockReturnValue(ptyProvider)
-      // Why: a removed/disconnected SSH target has no live provider; forgetLocal
-      // must not reach for one.
+      // Why: a removed/disconnected SSH target has no live provider; forgetLocal must not reach for one.
       getSshGitProviderMock.mockReturnValue(undefined)
 
       const result = await handlers['worktrees:forgetLocal'](null, { worktreeId })
diff --git a/src/main/ipc/worktrees.ts b/src/main/ipc/worktrees.ts
index 9e7ff509b88..f3256b5b171 100644
--- a/src/main/ipc/worktrees.ts
+++ b/src/main/ipc/worktrees.ts
@@ -146,8 +146,7 @@ function getRepoForWorktreeRemoval(
   const matches = store
     .getRepos()
     .filter((repo) => repo.id === repoId && (!hostId || getRepoExecutionHostId(repo) === hostId))
-  // Why: deletion must never guess between host owners. Legacy unscoped calls
-  // remain compatible only while the repo id still has one unique owner.
+  // Why: deletion must never guess between host owners; legacy unscoped calls work only while the repo id has one unique owner.
   if (matches.length === 1) {
     return matches[0]
   }
@@ -219,16 +218,13 @@ async function mapWithConcurrency<T, R>(
 }
 
 function removeWorktreeMetadataAndTransientState(store: Store, worktreeId: string): void {
-  // Why: worktree IDs are path-derived and can be recreated, so removal must
-  // drop process-local caches before the same ID can point at a new workspace.
+  // Why: worktree IDs are path-derived and reusable; drop process-local caches before the same ID can map to a new workspace.
   store.removeWorktreeMeta(worktreeId)
   advertisedUrlWatcher.forgetWorktree(worktreeId)
-  // Why: drop this worktree's localhost label routes so they don't accumulate
-  // in the proxy's route maps for the rest of the session.
+  // Why: drop this worktree's localhost label routes so they don't accumulate in the proxy's route maps all session.
   localhostWorktreeLabelProxy.unregisterWorktree(worktreeId)
   deleteWorktreeHistoryDir(worktreeId)
-  // Why: release the removed worktree's PR-refresh aliases so coalesced queue
-  // entries do not retain it for the rest of the session (memory creep).
+  // Why: release the removed worktree's PR-refresh aliases so coalesced queue entries don't retain it all session (memory creep).
   pruneWorktreePRRefreshAliases(worktreeId)
 }
 
@@ -242,8 +238,7 @@ function getProjectHostSetupMetaUpdates(
     existing?.projectHostSetupId === undefined ||
     existing.projectHostSetupId === ownership.projectHostSetupId
   return {
-    // Why: project IDs can be upgraded from legacy repo IDs to provider-backed
-    // logical IDs. If the host setup is the same, repair ownership on discovery.
+    // Why: project IDs can upgrade from legacy repo IDs to provider-backed ones; repair ownership on discovery when the host setup matches.
     ...(sameSetup && existing?.projectId !== ownership.projectId
       ? { projectId: ownership.projectId }
       : {}),
@@ -254,11 +249,7 @@ function getProjectHostSetupMetaUpdates(
   }
 }
 
-// Why: worktrees discovered on disk (not created via Orca's UI) have no
-// persisted WorktreeMeta, so mergeWorktree falls back to `lastActivityAt: 0`.
-// That makes them sort to the bottom of "Recent" even though the user just
-// added the repo / folder. The same authoritative discovery pass is also the
-// safest time to backfill project-host setup ownership for upgraded profiles.
+// Why: disk-discovered worktrees have no WorktreeMeta, so lastActivityAt=0 sinks them to the bottom of "Recent"; also backfill host-setup ownership here.
 function resolveWorktreeMetaWithDiscoveryBackfill(
   store: Store,
   repo: Repo,
@@ -272,9 +263,7 @@ function resolveWorktreeMetaWithDiscoveryBackfill(
       ...ownershipUpdates
     }
     if (Object.keys(updates).length > 0) {
-      // Why: profiles created before lineage shipped already have WorktreeMeta
-      // rows. Backfill on authoritative discovery so upgraded workspaces can
-      // immediately participate in instance-validated lineage and host routing.
+      // Why: pre-lineage profiles already have WorktreeMeta rows; backfill on discovery so upgraded workspaces get lineage and host routing.
       return store.setWorktreeMeta(worktreeId, updates)
     }
     return existing
@@ -479,8 +468,7 @@ function getPreservedBranchCleanupTarget(
 const loggedUnavailableSshGitProviders = new Set<string>()
 const loggedWorktreeListFailures = new Set<string>()
 const loggedMalformedWorktreeMetaKeys = new Set<string>()
-// Why: absorb renderer polling bursts while keeping external worktree-change
-// lag bounded to one short refresh window.
+// Why: absorb renderer polling bursts while bounding external worktree-change lag to one short refresh window.
 const DETECTED_WORKTREE_SCAN_CACHE_TTL_MS = 5_000
 
 type DetectedWorktreeScanCacheEntry = {
@@ -513,8 +501,7 @@ function invalidateDetectedWorktreeScanCache(repoId: string): void {
     detectedWorktreeScanCache.delete(key)
     const inFlight = detectedWorktreeScanInFlight.get(key)
     if (inFlight) {
-      // Why: the detached scan keeps this token, so later scans can settle
-      // without making an older result fresh again.
+      // Why: the detached scan keeps this token so later scans settle without making an older result fresh again.
       inFlight.invalidated = true
       detectedWorktreeScanInFlight.delete(key)
     }
@@ -524,8 +511,7 @@ function invalidateDetectedWorktreeScanCache(repoId: string): void {
 registerWorktreeChangeInvalidator(invalidateDetectedWorktreeScanCache)
 
 export function __resetDetectedWorktreeScanCacheForTests(): void {
-  // Why: scans still pending across a test reset must not repopulate the
-  // cache afterward and leak state into the next test.
+  // Why: pending scans across a test reset must not repopulate the cache and leak state into the next test.
   for (const scan of detectedWorktreeScanInFlight.values()) {
     scan.invalidated = true
   }
@@ -573,8 +559,7 @@ async function listDetectedGitWorktrees(
   detectedWorktreeScanInFlight.set(cacheKey, scan)
   try {
     const gitWorktrees = await scan.promise
-    // Why: a create/remove notification can invalidate while the git scan is
-    // still running. Do not let that stale scan repopulate the cache afterward.
+    // Why: a create/remove notification can invalidate mid-scan; don't let that stale scan repopulate the cache afterward.
     if (!scan.invalidated) {
       detectedWorktreeScanCache.set(cacheKey, {
         worktrees: gitWorktrees,
@@ -615,9 +600,7 @@ function rememberLocalWorktreeRoots(
   if (repo.connectionId) {
     return
   }
-  // Why: worktrees:list already paid the `git worktree list` cost. Reusing
-  // that result keeps later git/file IPC validation from doing a second
-  // background scan that can trigger macOS folder-permission prompts.
+  // Why: reuse the `git worktree list` result so later git/file IPC validation skips a second scan that can trigger macOS folder-permission prompts.
   registerWorktreeRootsForRepo(store, repo.id, [
     repo.path,
     ...gitWorktrees.map((worktree) => worktree.path)
@@ -651,20 +634,14 @@ function pruneLineageForMissingRepoWorktrees(
   }
   for (const [childId, lineage] of Object.entries(store.getAllWorktreeLineage())) {
     if (childId.startsWith(repoPrefix) && !liveIds.has(childId)) {
-      // Why: path-derived IDs can disappear and later be reused by a different
-      // checkout. Once a successful scan proves the child is gone, drop its
-      // lineage so a future same-path worktree cannot inherit it. Missing
-      // parents stay readable so the UI can show the repairable "Missing
-      // parent" state.
+      // Why: path-derived IDs can be reused; once a scan proves the child is gone, drop its lineage so a future same-path worktree can't inherit it.
       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: keep the child lineage so the UI can show "Missing parent", but
-        // rotate the absent parent's stale identity once. If a different
-        // checkout later reuses that path, the old lineage stays invalid.
+        // Why: keep child lineage for the "Missing parent" UI, but rotate the absent parent's identity once so a path reuse can't inherit it.
         store.setWorktreeMeta(lineage.parentWorktreeId, { instanceId: randomUUID() })
       }
     }
@@ -751,8 +728,7 @@ function buildDetectedGitWorktrees(
   const settings = store.getSettings()
   const knownOrcaLayouts = buildKnownOrcaWorkspaceLayouts(settings, repo)
   const isLegacyRepoForVisibility = isLegacyRepoForExternalWorktreeVisibility(repo)
-  // Why: a prunable registration has no working directory (issue #8389); only
-  // this listing omits it — removal/cleanup flows list worktrees separately.
+  // Why: a prunable registration has no working directory (issue #8389); only this listing omits it — cleanup flows list separately.
   const liveWorktrees = gitWorktrees.filter((gitWorktree) => !gitWorktree.prunable)
   return dedupeWorktreesByPath(liveWorktrees).map((gitWorktree) => {
     const worktreeId = `${repo.id}::${gitWorktree.path}`
@@ -992,8 +968,7 @@ export function registerWorktreeHandlers(
   store: Store,
   runtime: OrcaRuntimeService
 ): void {
-  // Remove any previously registered handlers so we can re-register them
-  // (e.g. when macOS re-activates the app and creates a new window).
+  // Remove previously registered handlers so re-register works when macOS re-activates and creates a new window.
   ipcMain.removeHandler('worktrees:listAll')
   ipcMain.removeHandler('worktrees:list')
   ipcMain.removeHandler('worktrees:listDetected')
@@ -1021,8 +996,7 @@ export function registerWorktreeHandlers(
       ? createSshWorktreeMetaIndex(Object.entries(store.getAllWorktreeMeta()))
       : new Map()
 
-    // Why: each local repo listing can spawn `git worktree list`; cap fan-out
-    // so large repo fleets don't start unbounded subprocesses at once.
+    // Why: each local repo listing can spawn `git worktree list`; cap fan-out so large fleets don't start unbounded subprocesses.
     const results = await mapWithConcurrency(repos, WORKTREE_LIST_ALL_CONCURRENCY, async (repo) => {
       try {
         let gitWorktrees
@@ -1071,13 +1045,7 @@ export function registerWorktreeHandlers(
           `[worktrees] failed to list worktrees for repo "${repo.displayName}" (${repo.id}) at ${repo.path}`,
           err
         )
-        // Why: do NOT seed an empty success here. registerWorktreeRootsForRepo
-        // would mark this repo as registered and flip
-        // registeredWorktreeRootsDirty to false, which causes
-        // resolveRegisteredWorktreePath to permanently deny access to
-        // legitimate linked worktrees of this repo until something invalidates
-        // the cache. Leaving it unregistered keeps the cache dirty so the
-        // next access path can rebuild.
+        // Why: do NOT seed empty success — it flags the repo registered, blocking access to legit linked worktrees until the cache is invalidated.
         return []
       }
     })
@@ -1141,8 +1109,7 @@ export function registerWorktreeHandlers(
         `[worktrees] failed to list worktrees for repo "${repo.displayName}" (${repo.id}) at ${repo.path}`,
         err
       )
-      // Why: see worktrees:listAll catch — seeding an empty-success result
-      // would poison the auth cache and block linked worktrees.
+      // Why: see worktrees:listAll catch — seeding an empty-success result would poison the auth cache and block linked worktrees.
       return []
     }
   })
@@ -1232,8 +1199,7 @@ export function registerWorktreeHandlers(
       try {
         await prefetchWorktreeCreateBase({ repo, baseBranch: args.baseBranch, runtime })
       } catch {
-        // Why: this is an optimistic warm-up. The actual create path still
-        // awaits the same refresh and reports user-visible failures there.
+        // Why: optimistic warm-up; the real create path awaits the same refresh and reports failures there.
       }
     }
   )
@@ -1241,14 +1207,7 @@ export function registerWorktreeHandlers(
   ipcMain.handle(
     'worktrees:create',
     async (_event, args: CreateWorktreeArgs): Promise<CreateWorktreeResult> => {
-      // Why span here: worktree creation chains a clone-or-checkout, an
-      // install hook, and several git invocations. Wrapping the IPC entry
-      // gives every child git span a parent to attach to, so a failure in
-      // step 3 of 5 still shows up in the trace tree alongside steps 1–2.
-      // The branch name and remote URL are intentionally not added as
-      // attributes — branch names can carry user-content (e.g. an issue
-      // title) and the redactor would have to learn yet another rule;
-      // the repo ID is the safer correlator for the bundle.
+      // Why span here: parent the child git spans for the trace tree; don't attach branch name/remote URL (user content) — repo ID is the safer correlator.
       return withWorktreeSpan({ stage: 'create' }, async () => {
         const repo = store.getRepo(args.repoId)
         if (!repo) {
@@ -1271,11 +1230,7 @@ export function registerWorktreeHandlers(
 
         let result: CreateWorktreeResult
         try {
-          // Why: only wrap the helpers themselves. The pre-validation throws
-          // above (`Repo not found`, `Folder mode does not support creating
-          // worktrees`) signal IPC-shape bugs, not the user-visible
-          // git/filesystem failures the funnel cares about — bucketing them
-          // into `unknown` would pollute the failure taxonomy.
+          // Why: wrap only the helpers; the pre-validation throws above are IPC-shape bugs, not the git/filesystem failures the funnel tracks.
           result = isFolderRepo(repo)
             ? createFolderWorkspace(createArgs, repo, store)
             : repo.connectionId
@@ -1292,14 +1247,7 @@ export function registerWorktreeHandlers(
         }
         finishAutomationWorkspaceProvenanceRequest(args.automationProvenanceRequest)
 
-        // Why: emit `workspace_created` only after the underlying create has
-        // resolved (the helpers throw on failure, so reaching this line means
-        // git-add succeeded — we deliberately do not also emit a separate
-        // `workspace_initialized`, see telemetry-plan.md§Deferred events).
-        // `from_existing_branch` is true iff the caller specified a non-empty
-        // baseBranch; an unspecified baseBranch means "branch from default
-        // HEAD", which is the not-from-existing-branch case. We never send
-        // the branch name itself.
+        // Why: reaching here means create succeeded (helpers throw); skip a separate workspace_initialized (telemetry-plan.md§Deferred); never send the branch name.
         track('workspace_created', {
           source,
           from_existing_branch:
@@ -1349,8 +1297,7 @@ export function registerWorktreeHandlers(
         }
         return provider.exec(args, repo.path)
       }
-      // 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.
+      // Why: SSH repos can't fetch over the relay's read-only git.exec channel; route the PR-head fetch through the write-capable helper.
       const fetchRemoteTrackingRef = (remote: string, branch: string): Promise<void> =>
         fetchPrHeadTrackingRef(
           repo,
@@ -1386,8 +1333,7 @@ export function registerWorktreeHandlers(
     }
   )
 
-  // Why: keep desktop IPC and mobile/runtime RPC on the same MR base
-  // resolution path so SSH repos do not regress differently by surface.
+  // Why: keep desktop IPC and mobile/runtime RPC on the same MR-base path so SSH repos don't regress differently per surface.
   ipcMain.handle(
     'worktrees:resolveMrBase',
     async (
@@ -1436,9 +1382,7 @@ export function registerWorktreeHandlers(
         throw new Error(`Worktree deletion already in progress: ${args.worktreeId}`)
       }
 
-      // Why: stale toast actions, double-clicks, and Space/sidebar races can
-      // target the same worktree concurrently. Share the destructive backend
-      // operation so only one path touches Git and the filesystem.
+      // Why: concurrent stale-toast/double-click/sidebar races can hit the same worktree; share the op so only one path touches Git and disk.
       const removal = (async (): Promise<RemoveWorktreeResult> => {
         if (isFolderRepo(repo)) {
           if (args.worktreeId === getFolderWorkspaceRootId(repo)) {
@@ -1446,8 +1390,7 @@ export function registerWorktreeHandlers(
               'Cannot delete the project root workspace. Remove the folder project instead.'
             )
           }
-          // Why: folder workspaces share one filesystem root, so there is no Git
-          // remove step to close shells; sweep PTYs before dropping metadata.
+          // Why: folder workspaces share one root, so there's no Git remove step to close shells; sweep PTYs before dropping metadata.
           await killAllProcessesForWorktree(args.worktreeId, {
             runtime,
             localProvider: getLocalPtyProvider(),
@@ -1461,8 +1404,7 @@ export function registerWorktreeHandlers(
           return {}
         }
 
-        // Why: the renderer-supplied worktreeId contains a filesystem path.
-        // Re-derive the canonical path from git before any destructive action.
+        // Why: renderer-supplied worktreeId embeds a path; re-derive the canonical path from git before any destructive action.
         const provider = repo.connectionId ? requireSshGitProvider(repo.connectionId) : null
         const localWorktreeGitOptions = repo.connectionId
           ? {}
@@ -1614,13 +1556,10 @@ export function registerWorktreeHandlers(
           }
           if (await isAlreadyRemovedWorktreePath(repo, worktreePath, localWorktreeGitOptions)) {
             if (!args.force && !removedMeta) {
-              // Why: without persisted metadata, require the renderer recovery
-              // path before deleting Orca-only state for an unregistered path.
+              // 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.
-            // The sidebar delete action has persisted metadata proving this was
-            // an Orca-known row, so no force confirmation is needed.
+            // Why: a manually deleted worktree is already gone; persisted metadata proves it was an Orca-known row, so no force is needed.
             if (repo.connectionId) {
               await cleanupUnusedWorktreePushTargetRemoteSsh(
                 provider!,
@@ -1650,8 +1589,7 @@ export function registerWorktreeHandlers(
         const canonicalWorktreePath = registeredWorktree.path
         const deleteBranch = removedMeta?.preserveBranchOnDelete !== true
 
-        // Why: a Git lock must block before archive hooks or linked-path cleanup
-        // mutate the workspace; dirty-file force is a separate permission.
+        // Why: a Git lock must block before archive hooks or linked-path cleanup mutate the workspace; dirty-file force is separate.
         try {
           assertWorktreeUnlockedForRemoval(registeredWorktree)
         } catch (error) {
@@ -1660,8 +1598,7 @@ export function registerWorktreeHandlers(
           )
         }
 
-        // Why: a prior forced Windows recovery can delete the directory but leave
-        // Git's stale registration; recover and verify it before clearing metadata.
+        // Why: a prior forced Windows recovery can delete the dir but leave a stale Git registration; verify before clearing metadata.
         if (
           !repo.connectionId &&
           args.force === true &&
@@ -1719,8 +1656,7 @@ export function registerWorktreeHandlers(
         }
 
         if (repo.connectionId) {
-          // Why: SSH deletion mirrors the local flow: hooks run while the
-          // directory is intact, then the clean check guards destructive removal.
+          // Why: SSH deletion mirrors the local flow — hooks run while the directory is intact, then the clean check guards removal.
           if (!args.force) {
             const { clean, stdout } = await provider!.worktreeIsClean(canonicalWorktreePath)
             if (!clean) {
@@ -1783,8 +1719,7 @@ export function registerWorktreeHandlers(
           )
         }
         try {
-          // Why: an archive hook can race another Git client that locks the row;
-          // recheck before linked-path, watcher, or terminal teardown side effects.
+          // Why: an archive hook can race another Git client that locks the row; recheck before linked-path/watcher/terminal teardown.
           assertWorktreeUnlockedForRemoval(refreshedRegisteredWorktree)
         } catch (error) {
           throw new Error(
@@ -1815,30 +1750,25 @@ export function registerWorktreeHandlers(
               formatWorktreeRemovalError(error, canonicalWorktreePath, args.force ?? false)
             )
           }
-          // Why: Git can still classify this as an orphan after preflight;
-          // retain strict PTY teardown before any recursive fallback deletion.
+          // Why: Git can still classify this as an orphan after preflight; keep strict PTY teardown before any recursive fallback deletion.
         }
 
         let removalResult: RemoveWorktreeResult | undefined
         const removalGate = await runtime.acquireFileWatcherRemoval(canonicalWorktreePath)
         let removalCompleted = false
         try {
-          // Why: preflight ignores only these configured paths without mutating
-          // the worktree; keep new watcher installs fenced through Git removal.
+          // Why: preflight only ignored these paths, not mutated them; keep watcher installs fenced through Git removal.
           if (linkedPaths.length > 0) {
             await removeWorktreeLinkedPaths(canonicalWorktreePath, linkedPaths)
           }
 
-          // Why: hold the watcher/terminal gate until Git and any recursive
-          // fallback complete, so no late spawn can recreate a native handle.
+          // Why: hold the watcher/terminal gate through Git and any recursive fallback so no late spawn recreates a native handle.
           await stopPtysForDestructiveWorktreeRemoval(runtime, args.worktreeId)
 
           try {
             const removeOptions = {
               ...(!deleteBranch ? { deleteBranch } : {}),
-              // Why: this handler already paid for an authoritative worktree
-              // list to validate the target; reuse it instead of rescanning
-              // every sibling worktree during the hot delete path.
+              // Why: reuse the authoritative worktree list already computed here instead of rescanning siblings on the hot delete path.
               knownRemovedWorktree: refreshedRegisteredWorktree,
               ...(hasLocalWorktreeGitOptions ? localWorktreeGitOptions : {})
             }
@@ -1852,8 +1782,7 @@ export function registerWorktreeHandlers(
               refreshedRegisteredWorktree.head
             )
           } catch (error) {
-            // Why: Git for Windows can deregister a clean worktree before its
-            // recursive filesystem deletion fails transiently.
+            // Why: Git for Windows can deregister a clean worktree before its recursive filesystem deletion fails transiently.
             const recoveredRemovalResult = await recoverLocalWindowsWorktreeRemoval({
               error,
               force: args.force ?? false,
@@ -1890,10 +1819,7 @@ export function registerWorktreeHandlers(
                   `[worktrees] Refusing recursive cleanup for unproven worktree directory: ${canonicalWorktreePath}`
                 )
               }
-              // Why: `git worktree remove` failed, so git's internal worktree tracking
-              // (`.git/worktrees/<name>`) 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.
+              // Why: remove failed so git still tracks it (.git/worktrees/<name>); prune or the stale entry keeps its branch locked.
               await gitExecFileAsync(['worktree', 'prune'], {
                 cwd: repo.path,
                 ...localWorktreeGitOptions
@@ -1953,12 +1879,7 @@ export function registerWorktreeHandlers(
     }
   )
 
-  // Why: forget-locally drops a workspace from Orca without any remote Git or
-  // filesystem work. It exists so a workspace pinned to a removed/disconnected
-  // SSH target — whose provider is gone and whose `worktrees:remove` therefore
-  // throws at requireSshGitProvider before any cleanup runs — can still be
-  // cleared from the app. It never touches the remote: no worktree registration,
-  // no branches, no files are deleted there.
+  // Why: drop a workspace locally with no remote work, so one pinned to a dead SSH target (where worktrees:remove throws) can still be cleared.
   ipcMain.handle(
     'worktrees:forgetLocal',
     async (
@@ -1970,9 +1891,7 @@ export function registerWorktreeHandlers(
       if (!repo) {
         throw new Error(`Repo not found: ${repoId}`)
       }
-      // Why: share the removal in-flight map (not a separate one) so a concurrent
-      // worktrees:remove and worktrees:forgetLocal on the same id cannot both
-      // mutate metadata. A forget takes no force/skipArchive options.
+      // Why: share the removal in-flight map so concurrent remove and forgetLocal on the same id can't both mutate metadata.
       const inFlightKey = getWorktreeRemovalInFlightKey(
         args.worktreeId,
         getRepoExecutionHostId(repo)
@@ -1993,9 +1912,7 @@ export function registerWorktreeHandlers(
           )
         }
 
-        // Why: best-effort PTY sweep. killAllProcessesForWorktree resolves
-        // synchronously for a dead SSH relay (the provider tombstones the lease
-        // and returns without awaiting the remote), so this never hangs.
+        // Why: best-effort PTY sweep; resolves synchronously for a dead SSH relay (tombstoned lease) so it never hangs.
         await killAllProcessesForWorktree(args.worktreeId, {
           runtime,
           localProvider: getLocalPtyProvider(),
@@ -2043,9 +1960,7 @@ export function registerWorktreeHandlers(
 
       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.
+        // Why: SSH needs the write-capable relay RPC; the read-only git.exec allowlist rejects these worktree/update-ref/config writes.
         await provider.forceDeletePreservedBranch(
           repo.path,
           cleanupTarget.branchName,
@@ -2095,18 +2010,9 @@ export function registerWorktreeHandlers(
             }
           : args.updates
       const meta = store.setWorktreeMeta(args.worktreeId, stripOrcaProvenanceMetaUpdates(updates))
-      // Do NOT call notifyWorktreesChanged here. The renderer applies meta
-      // updates optimistically before calling this IPC, so a notification
-      // would trigger a redundant fetchWorktrees round-trip that bumps
-      // sortEpoch and reorders the sidebar — the exact bug PR #209 tried
-      // to fix (clicking a card would clear isUnread → updateMeta →
-      // worktrees:changed → fetchWorktrees → sortEpoch++ → re-sort).
+      // Do NOT notify here: renderer already applied this optimistically; a notification would re-sort the sidebar (bug PR #209).
       if (args.updates.displayName !== undefined) {
-        // Why: paired remote clients have no optimistic copy of the rename and
-        // no longer poll for titles, so push the remote-only invalidation.
-        // Gated on displayName to keep isUnread-per-click updates event-free.
-        // getRepoIdFromWorktreeId matches the mobile client's event filter and
-        // never throws after the meta write already succeeded.
+        // Why: remote clients have no optimistic rename and stopped polling titles, so push a remote-only invalidation; gate on displayName so per-click isUnread updates stay event-free.
         runtime.notifyWorktreesChangedForRemoteClients(getRepoIdFromWorktreeId(args.worktreeId))
       }
       return meta
@@ -2137,27 +2043,19 @@ export function registerWorktreeHandlers(
     }
   )
 
-  // Why: the renderer continuously snapshots the computed sidebar order into
-  // sortOrder so that it can be restored on cold start (when ephemeral signals
-  // like running jobs and live terminals are gone). A single batch call avoids
-  // N individual updateMeta IPC round-trips; the persistence layer debounces
-  // the actual disk write.
+  // Why: snapshot sidebar order for cold-start restore (ephemeral signals gone); one batch call avoids N updateMeta IPCs.
   ipcMain.handle('worktrees:persistSortOrder', (_event, args: { orderedIds: string[] }) => {
-    // Defensive: guard against malformed or missing input from the renderer.
     if (!Array.isArray(args?.orderedIds) || args.orderedIds.length === 0) {
       return
     }
     const now = Date.now()
     for (let i = 0; i < args.orderedIds.length; i++) {
-      // Descending timestamps so that the first item has the highest
-      // sortOrder value (most recent), making b.sortOrder - a.sortOrder
-      // a natural "first wins" comparator on cold start.
+      // Descending timestamps: first item gets highest sortOrder so b - a sorts first-wins on cold start.
       store.setWorktreeMeta(args.orderedIds[i], { sortOrder: now - i * 1000 })
     }
   })
 
-  // Why: the full generation-failure output is main-memory only (never in
-  // worktree metadata), so the rename-failed dialog pulls it on demand.
+  // Why: full failure output lives only in main memory (not worktree metadata), so the dialog pulls it on demand.
   ipcMain.handle(
     'worktrees:getBranchRenameFailureOutput',
     (_event, args: { worktreeId: string }) => {
@@ -2174,8 +2072,7 @@ export function registerWorktreeHandlers(
       const repo = getRepoForWorktreeRemoval(store, args.repoId, args.hostId)
       if (!repo) {
         const repoIdExists = store.getRepos().some((candidate) => candidate.id === args.repoId)
-        // Why: a requested or ambiguous host must not be reported as hook-free;
-        // callers treat inspection errors as "skip", which keeps hook execution fail closed.
+        // Why: callers treat inspection errors as "skip", so a requested/ambiguous host must report error (fail closed), not hook-free.
         return {
           status: args.hostId || repoIdExists ? 'error' : 'ok',
           hasHooks: false,
@@ -2212,10 +2109,7 @@ export function registerWorktreeHandlers(
 
       const has = hasHooksFile(repo.path)
       const hooks = has ? loadHooks(repo.path) : null
-      // Why: when a newer Orca version adds a top-level key to `orca.yaml`, older
-      // versions that don't recognise it return null and show "could not be parsed".
-      // Detecting well-formed but unrecognised keys lets the UI suggest updating
-      // instead of implying the file is broken.
+      // Why: unrecognised top-level keys mean the file is well-formed but from a newer Orca; suggest updating rather than "could not be parsed".
       const mayNeedUpdate = has && !hooks && hasUnrecognizedOrcaYamlKeys(repo.path)
       return {
         status: 'ok',
diff --git a/src/main/memory/hydrate-local-pty-registry.ts b/src/main/memory/hydrate-local-pty-registry.ts
index f6563049318..ec672d7e9c8 100644
--- a/src/main/memory/hydrate-local-pty-registry.ts
+++ b/src/main/memory/hydrate-local-pty-registry.ts
@@ -1,20 +1,11 @@
 /**
  * Boot-time hydration of `pty-registry` from the live daemon.
  *
- * Why: the registry is normally populated by the `pty:spawn` IPC
- * handler. On warm reattach (a fresh Orca process bound to a
- * still-running daemon), the renderer hasn't re-mounted every pane
- * yet, so `pty:spawn` hasn't fired for those sessions and the memory
- * collector's snapshot omits them. The renderer then unions in
- * `pty.listSessions()` results with `hasLocalSamples: false`, which
- * the chip predicate rendered as "REMOTE" — even though the sessions
- * are local.
- *
- * This module fills the gap once at boot: ask the daemon for every live
- * session, reattribute each one to its repo via the minted session-id
- * format, and only register sessions whose repo has no `connectionId`
- * (i.e. truly local). Truly remote (SSH) sessions stay out of the
- * registry, mirroring the spawn-time gate (the `if (!args.connectionId)` block around the `registerPty` call in `src/main/ipc/pty.ts`).
+ * Why: on warm reattach (fresh Orca process, still-running daemon) the renderer
+ * hasn't re-mounted every pane, so `pty:spawn` never fired for those sessions
+ * and they surfaced as "REMOTE" despite being local. Fill the gap once at boot,
+ * registering only sessions whose repo has no `connectionId` — mirroring the
+ * spawn-time gate in `src/main/ipc/pty.ts`.
  */
 
 import { getDaemonProvider } from '../daemon/daemon-init'
@@ -28,31 +19,15 @@ import { parsePtySessionId } from '../../shared/pty-session-id-format'
 import { splitWorktreeId } from '../../shared/worktree-id'
 import type { Store } from '../persistence'
 
-// Why: `attachMainWindowServices` runs on every macOS dock re-activation
-// (see `app.on('activate', ...)` in src/main/index.ts), so this module
-// guards against re-running git I/O + daemon RPC after the first pass.
-// Stays false until we actually have a daemon provider, so a boot where
-// the daemon socket isn't up yet remains retry-eligible on later
-// re-activations.
+// Why: attachMainWindowServices reruns on every macOS dock re-activation; guard against re-running git I/O + daemon RPC.
 let hasHydrated = false
 
 /**
- * Read the live daemon session list and register every local session
- * the registry doesn't already know about.
+ * Read the live daemon session list and register every local session the
+ * registry doesn't already know about.
  *
- * Once-per-process when the daemon is reachable on first call:
- * `attachMainWindowServices` fires on every macOS dock re-activation, so
- * the module-level `hasHydrated` guard ensures the git-worktree
- * enumeration and `listSessions` daemon RPC only run on the first
- * successful invocation. If the daemon is offline at first call (no
- * provider yet), the function returns without flipping the flag so a
- * later macOS re-activation can retry; once a provider is obtained the
- * flag flips and subsequent calls are a no-op.
- *
- * Wrapped in `try/catch` because the daemon socket may be unreachable
- * at boot (process not yet started, or just died); the renderer-side
- * union still covers that case until the daemon comes back. Any failure
- * here is a coverage degradation, not a correctness regression.
+ * Why: failures here are a coverage degradation (the renderer-side union still
+ * covers the gap), not a correctness regression, so they're swallowed.
  */
 export async function hydrateLocalPtyRegistryAtBoot(store: Pick<Store, 'getRepos'>): Promise<void> {
   try {
@@ -61,36 +36,22 @@ export async function hydrateLocalPtyRegistryAtBoot(store: Pick<Store, 'getRepos
     }
     const provider = getDaemonProvider()
     if (!provider) {
-      // Why: leave hasHydrated false so a later activation (after the
-      // daemon comes up) can retry.
+      // Why: leave hasHydrated false so a later activation can retry once the daemon is up.
       return
     }
-    // Why: flip only once we have a provider — committed to either
-    // succeeding or failing on a daemon RPC. Retrying after an RPC
-    // throw uses the same socket and is unlikely to help; the
-    // renderer-side union still covers that case.
+    // Why: flip only after a provider exists; retrying a failed RPC on the same socket won't help.
     hasHydrated = true
 
-    // Why: ask the daemon which repos matter before launching Git worktree
-    // enumeration. Most configured repos have no preserved session at boot,
-    // so scanning all of them creates pure background subprocess churn.
+    // Why: defer git worktree enumeration to only repos with a live session; scanning all repos is background subprocess churn.
     const reposById = new Map(store.getRepos().map((repo) => [repo.id, repo]))
-    // Why: live git enumeration verifies that a referenced local worktree
-    // still exists instead of resurrecting removed worktrees.
+    // Why: verify via live git that a referenced worktree still exists, to avoid resurrecting removed ones.
     const liveLocalWorktreeIds = new Set<string>()
     const resolvedRepoIds = new Set<string>()
 
     let sessionInfos = await collectSessionInfos(provider)
     let alreadyRegistered = new Set(listRegisteredPtys().map((p) => p.ptyId))
 
-    // Why: repo selection and registration must come from the same daemon
-    // snapshot. Git enumeration can take seconds, so after each scan pass we
-    // re-read daemon and registry state; sessions that exited or were
-    // authoritatively registered meanwhile are not resurrected or overwritten,
-    // and a session that only became visible during a slow scan (e.g. a
-    // briefly unreachable legacy adapter) gets its repo scanned on the next
-    // pass instead of being silently dropped. Terminates because every pass
-    // permanently resolves at least one new repo id.
+    // Why: git enumeration is slow, so re-read daemon+registry each pass to avoid resurrecting exited sessions; terminates as each pass resolves >=1 new repo.
     for (;;) {
       const newlyReferencedRepos = new Map<string, ReturnType<(typeof store)['getRepos']>[number]>()
       for (const info of sessionInfos) {
@@ -104,9 +65,7 @@ export async function hydrateLocalPtyRegistryAtBoot(store: Pick<Store, 'getRepos
         }
         const repo = reposById.get(parsedWorktreeId.repoId)
         if (!repo || (repo.connectionId ?? null)) {
-          // Why: unknown repos can't be proven local, and SSH PTYs are never
-          // registered for local process sampling — resolve without git
-          // enumeration so neither can extend the loop.
+          // Why: unknown or SSH repos can't be proven local; resolve without git enumeration so they can't extend the loop.
           resolvedRepoIds.add(parsedWorktreeId.repoId)
           continue
         }
@@ -128,10 +87,7 @@ export async function hydrateLocalPtyRegistryAtBoot(store: Pick<Store, 'getRepos
       alreadyRegistered = new Set(listRegisteredPtys().map((p) => p.ptyId))
     }
     for (const info of sessionInfos) {
-      // Why: pid-write ordering — `pty:spawn` is the authoritative
-      // writer for in-session sessions; if that fired before this loop
-      // started, we must not overwrite a known-good pid with a stale one
-      // from listSessions(). Skip if the entry already exists.
+      // Why: pty:spawn is the authoritative pid writer; don't overwrite its entry with a stale listSessions() pid.
       if (alreadyRegistered.has(info.sessionId)) {
         continue
       }
@@ -139,11 +95,7 @@ export async function hydrateLocalPtyRegistryAtBoot(store: Pick<Store, 'getRepos
       if (!worktreeId) {
         continue
       }
-      // Why: SSH sessions must stay out of the registry — mirrors the
-      // spawn-time `if (!args.connectionId)` gate around `registerPty` in
-      // `src/main/ipc/pty.ts`. If the repo isn't in the store, skip the
-      // session: we can't prove it's local, and the renderer-side union
-      // still surfaces the session at the cost of a missing pid sample.
+      // Why: only register proven-local worktrees, mirroring the spawn-time !connectionId gate in src/main/ipc/pty.ts.
       if (!liveLocalWorktreeIds.has(worktreeId)) {
         continue
       }
@@ -169,9 +121,7 @@ export async function hydrateLocalPtyRegistryAtBoot(store: Pick<Store, 'getRepos
 async function collectSessionInfos(
   provider: DaemonPtyRouter | DaemonPtyAdapter | DegradedDaemonPtyProvider
 ): Promise<SessionInfo[]> {
-  // Why: the router fans `listSessions` out across current + legacy adapters
-  // so we get every protocol-version daemon's sessions; the bare-adapter
-  // fallback is only the in-process restart edge case.
+  // Why: fan listSessions across current + legacy adapters so no daemon protocol version is missed.
   const adapters: readonly DaemonPtyAdapter[] =
     provider instanceof DaemonPtyRouter || provider instanceof DegradedDaemonPtyProvider
       ? provider.getAllAdapters()
@@ -180,15 +130,12 @@ async function collectSessionInfos(
   for (const adapter of adapters) {
     try {
       const sessions = await adapter.listSessions()
-      // Why: warm reattach can discover many daemon sessions at once; spreading
-      // listSessions() into push can exceed JavaScript's argument limit.
+      // Why: session count can exceed the JS argument limit, so avoid push(...sessions).
       for (const session of sessions) {
         out.push(session)
       }
     } catch (err) {
-      // Why: a single adapter failing should not abort hydration of the
-      // others — the current adapter and any legacy daemons each have
-      // their own socket and one being unreachable is normal.
+      // Why: one adapter's socket being unreachable is normal; don't abort the others.
       console.warn(
         '[memory] listSessions failed for one adapter during hydration:',
         err instanceof Error ? err.message : String(err)
diff --git a/src/main/observability/bundle.ts b/src/main/observability/bundle.ts
index 34011d9e4aa..750f41fead9 100644
--- a/src/main/observability/bundle.ts
+++ b/src/main/observability/bundle.ts
@@ -1,32 +1,10 @@
-// Diagnostic bundle collection + upload (Mode 3 from
-// telemetry-error-tracking.md). The single user-initiated network path from
-// the error-tracking lane to Orca infrastructure. Every step here implements
-// a hardening requirement from §Endpoint contract — the comments name the
-// requirement number when they apply.
-//
-// Lifecycle:
-//   1. `collectBundle()` — read the last N minutes of NDJSON across the
-//      rotated family, run the redactor a second time over the merged
-//      payload (belt-and-suspenders), embed the per-bundle
-//      `bundle_submission_id`. NEVER carries `install_id` (Issue 8 in the
-//      security review).
-//   2. (renderer) — preview the bundle as plain text. User can copy or cancel.
-//      Main retains the uploadable payload so renderer cannot substitute
-//      arbitrary bytes after preview.
-//   3. `uploadBundle()` — two-step:
-//      a) POST `/diagnostics/token` → token + upload_url
-//      b) POST `<upload_url>` with `Authorization: Bearer <token>` and the
-//         collected NDJSON payload. Returns ticket ID.
-//   4. (renderer) — surface the support reference ID; offer copy/delete
-//      controls. Delete posts only the server-issued ID.
-//
-// Server-side endpoint contract is fully specified in
-// telemetry-error-tracking.md §Endpoint contract. Implementation of those
-// endpoints (token issuance, rate limit, storage, server-side redaction,
-// retention, deletion) is operational TBD — flagged as an open question to
-// the human dispatching this task. We ship the *client* of that contract
-// with all hardening invariants the client controls (content-type pinning,
-// body-size cap on upload, token-handling discipline).
+// Diagnostic bundle collection + upload (Mode 3, telemetry-error-tracking.md): the one
+// user-initiated network path from the error-tracking lane to Orca infra. The per-bundle
+// submission ID NEVER carries install_id (security-review Issue 8), and main retains the
+// uploadable payload so a compromised renderer can't substitute bytes after preview.
+// Server endpoint contract lives in telemetry-error-tracking.md §Endpoint contract; we
+// ship only the client, with the hardening invariants it controls (content-type pinning,
+// upload body-size cap, token-handling discipline).
 
 import { randomBytes } from 'node:crypto'
 import { readFileSync, statSync } from 'node:fs'
@@ -39,8 +17,7 @@ const DEFAULT_LOOKBACK_MINUTES = 30
 export type CollectBundleOptions = {
   readonly traceFilePath: string
   readonly maxFiles: number
-  /** Detached-daemon lifecycle log. Its rotated family is merged into the
-   *  bundle so daemon-side failures are diagnosable from a field report. */
+  /** Detached-daemon lifecycle log; its rotated family is merged in so daemon failures are diagnosable from a field report. */
   readonly daemonLogFilePath?: string
   readonly daemonLogMaxFiles?: number
   readonly lookbackMinutes?: number
@@ -52,8 +29,7 @@ export type CollectBundleOptions = {
 }
 
 export type CollectedBundle = {
-  /** 128-bit unguessable random ID, base64url. NOT the install_id —
-   *  bundles are deliberately join-incompatible with the PostHog lane. */
+  /** 128-bit unguessable base64url ID. NOT the install_id — bundles are join-incompatible with the PostHog lane. */
   readonly bundleSubmissionId: string
   /** UTF-8 NDJSON payload — header line + N redacted span lines. */
   readonly payload: string
@@ -91,11 +67,8 @@ function* readLinesNewestFirst(text: string): Iterable<string> {
 }
 
 /**
- * Read the last N minutes of NDJSON across the rotated family and produce
- * a redacted bundle payload. Caller renders this as preview text; main keeps
- * the uploadable payload and `uploadBundle()` ships only those collected
- * bytes. This keeps compromised renderer code from substituting arbitrary
- * upload content after preview.
+ * Read the last N minutes of NDJSON across the rotated family into a redacted bundle payload.
+ * Main keeps the uploadable payload so a compromised renderer can't substitute bytes after preview.
  */
 export function collectBundle(opts: CollectBundleOptions): CollectedBundle {
   const lookbackMs = (opts.lookbackMinutes ?? DEFAULT_LOOKBACK_MINUTES) * 60 * 1000
@@ -116,21 +89,11 @@ export function collectBundle(opts: CollectBundleOptions): CollectedBundle {
   const headerLine = JSON.stringify({ type: 'bundle-header', ...header })
   const lines: string[] = [headerLine]
   let spanCount = 0
-  // Running byte counter for the eventual payload. Starts with the header
-  // plus its final newline; each pushed span adds its line plus newline.
-  // Avoids re-running `lines.join('\n').length` every iteration — that's
-  // O(N²) in span count and dominates collection time for large backlogs.
+  // Track bytes incrementally to avoid an O(N²) `lines.join('\n').length` per span.
   let currentBytes = Buffer.byteLength(`${headerLine}\n`)
   const maxRecordBytes = MAX_BUNDLE_BYTES - currentBytes
 
-  // Files from listRotatedFiles are newest → oldest. Reading newest first
-  // means the cutoff filter naturally bounds our work — once we hit a span
-  // older than the cutoff in an older file we can stop entirely. We don't
-  // optimize that yet; the worst case (10 × 10 MB = 100 MB scan) takes
-  // <1 s on a modern SSD and bundles are user-initiated, not hot-path.
-  // Trace spans first (the primary payload), then the daemon lifecycle log.
-  // Daemon records carry an ISO `ts` instead of `endTimeUnixNano`; both are
-  // filtered by the same lookback below.
+  // Trace files then daemon log, each newest → oldest so the byte cap keeps the most recent spans.
   const files = [
     ...listRotatedFiles(opts.traceFilePath, opts.maxFiles),
     ...(opts.daemonLogFilePath
@@ -140,10 +103,7 @@ export function collectBundle(opts: CollectBundleOptions): CollectedBundle {
   outer: for (const file of files) {
     let text: string
     try {
-      // statSync first to skip absurdly-large files defensively. The sink
-      // caps at 10 MB per file; a tampered file could theoretically be
-      // bigger, in which case we want to abort the bundle rather than
-      // panic-allocate.
+      // stat first: the sink caps at 10 MB/file, so a tampered oversize file could panic-allocate on read.
       const size = statSync(file).size
       if (size > 50 * 1024 * 1024) {
         continue
@@ -153,9 +113,7 @@ export function collectBundle(opts: CollectBundleOptions): CollectedBundle {
       continue
     }
 
-    // NDJSON parsing — one record per line. Process each file newest-first
-    // so the size cap preserves the spans closest to the support action.
-    // Skip malformed lines silently; a crash can leave a half-line.
+    // Newest-first so the size cap preserves the most recent spans; skip malformed lines (a crash can leave a half-line).
     for (const raw of readLinesNewestFirst(text)) {
       let parsed: unknown
       try {
@@ -171,40 +129,32 @@ export function collectBundle(opts: CollectBundleOptions): CollectedBundle {
         endTimeUnixNano?: string
         ts?: string
       }
-      // Filter by end-time, not start-time. A long-lived span started 35
-      // minutes ago but ending inside the lookback is exactly what we want
-      // in the bundle for diagnosing "session crashed at minute 32."
+      // Filter by end-time, not start-time, so long-lived spans that ended inside the lookback are still included.
       if (typeof record.endTimeUnixNano === 'string') {
         try {
           if (BigInt(record.endTimeUnixNano) < cutoffNanos) {
             continue
           }
         } catch {
-          // Non-numeric end-time — keep it; better to over-include than to
-          // drop a record we couldn't classify.
+          // Non-numeric end-time: keep it — better to over-include than drop an unclassifiable record.
         }
       } else if (typeof record.ts === 'string') {
-        // Daemon lifecycle lines timestamp with an ISO `ts`; bound them by the
-        // same lookback window. Unparseable timestamps are kept (over-include).
+        // Daemon lifecycle lines use an ISO `ts`; unparseable timestamps are kept (over-include).
         const tsMs = Date.parse(record.ts)
         if (Number.isFinite(tsMs) && tsMs < cutoffMs) {
           continue
         }
       }
 
-      // Run the redactor a SECOND TIME over the parsed shape, in server mode.
-      // This catches nested auth-bearing fields and strips product-telemetry
-      // identity keys before the user's eyes hit the preview window.
+      // Second redaction pass (server mode) catches nested auth fields and strips identity keys before preview.
       const redacted = JSON.stringify(redactValue(parsed, 'server'))
       const redactedBytes = Buffer.byteLength(redacted) + 1
       if (redactedBytes > maxRecordBytes) {
-        // One pathological record should not suppress every smaller recent
-        // span behind it. Skip records that cannot fit in an empty payload.
+        // Skip a single oversized record so it can't suppress every smaller span behind it.
         continue
       }
       if (currentBytes + redactedBytes > MAX_BUNDLE_BYTES) {
-        // Hard ceiling at the same 4 MiB the upload endpoint enforces.
-        // Check before appending so the preview can be uploaded as-is.
+        // Hard ceiling matches the upload endpoint's 4 MiB; check before appending so the preview uploads as-is.
         break outer
       }
       lines.push(redacted)
@@ -224,16 +174,9 @@ export function collectBundle(opts: CollectBundleOptions): CollectedBundle {
 
 // ── Bundle submission ID ─────────────────────────────────────────────────
 
-/**
- * 128-bit cryptographic random, URL-safe base64. Generated per bundle —
- * NOT persisted. A user submitting two bundles produces two unrelated IDs.
- * This is the primary structural mitigation for Issue 8 (bundle ↔
- * install_id correlation).
- */
+/** 128-bit URL-safe-base64 random, per-bundle and NOT persisted — mitigation for Issue 8 (bundle ↔ install_id correlation). */
 export function generateBundleSubmissionId(): string {
-  // 16 bytes = 128 bits → base64url is 22 chars (no padding). Matches the
-  // §Endpoint contract requirement that ticket IDs be unguessable and
-  // non-enumerable; we use the same shape for the submission ID.
+  // 16 bytes = 128 bits, base64url = 22 chars; unguessable/non-enumerable per §Endpoint contract.
   return randomBytes(16)
     .toString('base64')
     .replace(/\+/g, '-')
diff --git a/src/main/observability/local-file-sink.ts b/src/main/observability/local-file-sink.ts
index 7e239cbfeca..b2a74bbbb40 100644
--- a/src/main/observability/local-file-sink.ts
+++ b/src/main/observability/local-file-sink.ts
@@ -1,25 +1,8 @@
-// NDJSON sink with size-based file rotation. Spans are serialized one per
-// line to a primary file, and when that file's byte budget is exceeded the
-// sink rolls it forward (`main.trace.ndjson` → `main.trace.ndjson.1` →
-// `main.trace.ndjson.2` → … → `main.trace.ndjson.N`, oldest deleted).
-//
-// Defaults match the local-first trace sink design: 10 MB × 10 files. 100 MB
-// is the worst-case footprint on a user's disk, keeping the sizing bounded
-// without adding a network dependency.
-//
-// Two design constraints worth calling out:
-//
-//   1. Synchronous writes by default. The error-tracking lane has to be
-//      durable on crash — if the renderer or main process is about to die,
-//      a buffered async flush is exactly what we don't want. We use the
-//      `appendFileSync` path (cheap on modern fs at this volume) and
-//      explicitly do a final `flush()` on shutdown.
-//
-//   2. Buffered batches with a flush threshold. Batches of up to
-//      `FLUSH_BUFFER_THRESHOLD` lines are coalesced into one syscall to
-//      keep the per-span cost low; a periodic interval flushes the partial
-//      batch every `batchWindowMs` so a sparse-trace session still ends up
-//      on disk. Both knobs are configurable for tests.
+// NDJSON trace sink with size-based rotation (`main.trace.ndjson` → `.1` → … → `.N`, oldest deleted).
+// Defaults 10 MB × 10 files bound the on-disk footprint at ~100 MB with no network dependency.
+// Writes are synchronous so the error-tracking lane survives a crash — an async buffered flush is
+// exactly what we don't want when main/renderer is about to die. Lines batch into one syscall, with
+// a periodic `batchWindowMs` flush so sparse-trace sessions still land on disk.
 
 import {
   chmodSync,
@@ -84,19 +67,13 @@ export function createLocalFileSink(opts: LocalFileSinkOptions): LocalFileSink {
   const batchWindowMs = opts.batchWindowMs ?? DEFAULT_BATCH_WINDOW_MS
   const flushThreshold = opts.flushBufferThreshold ?? DEFAULT_FLUSH_BUFFER_THRESHOLD
 
-  // Local traces can contain paths and crash context; keep them readable only
-  // by the current user even on systems with permissive default umasks.
+  // Traces hold paths and crash context; lock to current-user regardless of umask.
   const traceDirectory = dirname(filePath)
   mkdirSync(traceDirectory, { recursive: true, mode: PRIVATE_DIRECTORY_MODE })
   chmodPathIfPresent(traceDirectory, PRIVATE_DIRECTORY_MODE)
   tightenTraceFamilyPermissions(filePath, maxFiles)
 
-  // The sink owns one open fd. The fd is recreated on rotation; the rotation
-  // routine closes the old fd, renames the file, and opens a fresh one. We
-  // use the fd directly (rather than `appendFileSync(filePath, ...)`) so
-  // rotation is a clean swap and so we can rely on `fstatSync` for the
-  // current-file size — `statSync(filePath)` would race against another
-  // process truncating the file under us.
+  // Hold the fd directly (not `appendFileSync`) so fstatSync sizing can't race another process truncating the file.
   let fd: number = openAppend(filePath)
   let currentBytes: number = safeFstatSize(fd)
 
@@ -118,23 +95,19 @@ export function createLocalFileSink(opts: LocalFileSinkOptions): LocalFileSink {
     try {
       return fstatSync(handle).size
     } catch {
-      // Fresh-open or fd-out-of-band — start from zero. The next write will
-      // size correctly via `currentBytes += chunk.length`.
+      // fstat failed (fresh-open / out-of-band fd); start at 0 — the next write re-sizes.
       return 0
     }
   }
 
   function rotate(): void {
-    // Close the active fd before renaming. Some filesystems (notably CIFS)
-    // refuse to rename an open file; we close, rename, then reopen.
+    // Close fd before rename: some filesystems (notably CIFS) refuse to rename an open file.
     try {
       closeSync(fd)
     } catch {
       /* swallow — best-effort */
     }
-    // Cascade rename: `.N-1` → `.N`, `.N-2` → `.N-1`, …, base → `.1`.
-    // Walking from highest index down ensures we never overwrite a file we
-    // are about to rotate.
+    // Cascade base → `.1` → … → `.N`, walking highest index down so we never overwrite a file we still need.
     for (let i = maxFiles - 1; i >= 1; i--) {
       const src = i === 1 ? filePath : `${filePath}.${i - 1}`
       const dst = `${filePath}.${i}`
@@ -143,9 +116,7 @@ export function createLocalFileSink(opts: LocalFileSinkOptions): LocalFileSink {
       }
       try {
         if (existsSync(dst)) {
-          // The destination shouldn't exist after a clean rotation, but if
-          // we're recovering from a crashed prior session, drop stale
-          // intermediate files rather than failing the rename.
+          // Stale dst left by a crashed prior session; drop it rather than fail the rename.
           unlinkSync(dst)
         }
         renameSync(src, dst)
@@ -176,8 +147,7 @@ export function createLocalFileSink(opts: LocalFileSinkOptions): LocalFileSink {
         writeSync(fd, chunk)
         currentBytes += chunkBytes
       } catch {
-        // Reopen and retry once. If the second write also fails, drop this
-        // chunk — the error-tracking lane must never crash main.
+        // Reopen + retry once; if that also fails, drop the chunk — telemetry must never crash main.
         try {
           // Best-effort close of the prior fd to prevent fd-leak on transient errors.
           try {
@@ -203,17 +173,13 @@ export function createLocalFileSink(opts: LocalFileSinkOptions): LocalFileSink {
     for (const line of lines) {
       const lineBytes = Buffer.byteLength(line, 'utf8')
       if (lineBytes > maxBytes) {
-        // A single pathological span should not violate the documented
-        // maxFiles × maxBytes disk envelope. Drop only that record, not the
-        // rest of the buffered batch.
+        // Oversized single span would blow the maxFiles × maxBytes envelope; drop just this record.
         continue
       }
       if (pendingChunkBytes > 0 && currentBytes + pendingChunkBytes + lineBytes > maxBytes) {
         flushPendingChunk()
       }
-      // Rotation point: if writing this line would exceed the cap and we
-      // already have something in the file, rotate first. Empty-file rotations
-      // are skipped (would just produce zero-byte `.N` files on a new install).
+      // Skip empty-file rotations (currentBytes > 0) so a new install never produces zero-byte `.N` files.
       if (currentBytes > 0 && currentBytes + lineBytes > maxBytes) {
         rotate()
       }
@@ -231,9 +197,7 @@ export function createLocalFileSink(opts: LocalFileSinkOptions): LocalFileSink {
       timer = null
       flushBuffer()
     }, batchWindowMs)
-    // Don't keep the event loop alive purely for the flush timer — quitting
-    // is the path that already triggers a final synchronous flush via
-    // `close()`, and the periodic flush is a "while running" optimization.
+    // unref so the flush timer can't keep the process alive; close() does the final flush on quit.
     if (typeof timer.unref === 'function') {
       timer.unref()
     }
@@ -249,9 +213,7 @@ export function createLocalFileSink(opts: LocalFileSinkOptions): LocalFileSink {
       try {
         line = `${JSON.stringify(record)}\n`
       } catch {
-        // Circular reference / non-serializable. The redactor handles cycles
-        // for us; a stray here means the caller pushed something pre-redact.
-        // Drop rather than crash — the local file is best-effort.
+        // Redactor handles cycles upstream; a throw here means pre-redact data slipped in — drop rather than crash (best-effort).
         return
       }
       buffer.push(line)
@@ -287,8 +249,7 @@ export function createLocalFileSink(opts: LocalFileSinkOptions): LocalFileSink {
   }
 }
 
-/** Total byte usage across the rotated file family. Used by `bundle.ts` to
- *  size the read buffer and by the Privacy pane to display a footprint hint. */
+/** Total byte usage across the rotated file family (read-buffer sizing + Privacy footprint hint). */
 export function getRotatedFamilySize(
   filePath: string,
   maxFiles: number = DEFAULT_MAX_FILES
@@ -307,8 +268,7 @@ export function getRotatedFamilySize(
   return total
 }
 
-/** List rotated files in age order (newest → oldest) for `bundle.ts` to
- *  iterate when collecting the last N minutes of traces. */
+/** Rotated files in age order (newest → oldest) for `bundle.ts` trace collection. */
 export function listRotatedFiles(filePath: string, maxFiles: number = DEFAULT_MAX_FILES): string[] {
   const out: string[] = []
   for (let i = 0; i < maxFiles; i++) {
diff --git a/src/main/observability/redactor.ts b/src/main/observability/redactor.ts
index 4787abcd5f1..173382bde58 100644
--- a/src/main/observability/redactor.ts
+++ b/src/main/observability/redactor.ts
@@ -1,59 +1,19 @@
-// Secrets scrubber for the error-tracking lane. Runs synchronously at three
-// well-defined locations (see telemetry-error-tracking.md §The redactor):
+// Secrets scrubber for the error-tracking lane (see telemetry-error-tracking.md
+// §The redactor). Runs at three locations — sink-write, bundle-collection, and
+// server-ingest; the server pass is defense-in-depth since the client runs on an
+// attacker-controllable binary, and it additionally drops PostHog identity keys.
 //
-//   1. Sink-write time — every span is redacted before NDJSON serialization.
-//   2. Bundle-collection time — a second pass before the user-preview window
-//      renders. Belt-and-suspenders against a sink-write bug.
-//   3. Server-side ingest — a third pass. The client-side redactor runs on
-//      an attacker-controllable binary; server-side redaction is the
-//      defense-in-depth guarantee on the one path where bundle bytes reach
-//      Orca infrastructure. We expose `serverSideRedact()` separately so
-//      the server can additionally drop `install_id`/`installId`/
-//      `distinct_id` keys (which are valid in product telemetry but must not
-//      ride along on a bundle — see "Why bundles do not carry install_id").
+// The five rule families run in order; the string passes are idempotent, which
+// is what makes the three-location placement safe.
 //
-// Five rule families, applied in this order:
-//   1. labeled key-value (`api_key:`, `Authorization=Bearer …`)
-//   2. provider-key fingerprints (8 shapes)
-//   3. URL userinfo strip (`https://user:pass@host` → `https://[redacted]@host`)
-//   4. .env-shape line redaction (`FOO_SECRET=…`)
-//   5. attribute-key block-list (drop key entirely)
-//
-// Rules 1–4 operate on string values; rule 5 drops attribute *keys* before
-// the values are even examined. The string passes are idempotent — running
-// the redactor twice in a row produces the same output as running it once,
-// which is what makes the three-location placement safe.
-//
-// Per-attribute length capping is deliberately NOT applied here. The spec
-// argues against it (see §The redactor "No per-attribute length cap"):
-// envelope-level bounds (10 MB × 10 file rotation; 4 MiB bundle upload cap)
-// already cover the worst case, and a per-attribute truncation would eat the
-// tail of long stack chains, which is the most diagnostic part. Spans that
-// dump a multi-MB blob into one attribute are a call-site bug to fix at the
-// call site, not at the sink.
+// No per-attribute length cap: envelope bounds already cap size, and truncation
+// would eat the tail of long stack chains — the most diagnostic part.
 
-// Word boundaries (`\b`) on the keyword alternation prevent the rule from
-// firing inside compound identifiers — e.g. `FOO_SECRET=…` (an .env-shape
-// line redacted by Rule 4) and `DB_PASSWORD=…` should NOT match the
-// `secret`/`password` keyword here, otherwise this rule would steal the
-// match from rule 4 and produce `FOO_[redacted:labeled-kv]` rather than
-// preserving the key name.
-//
-// The value alternation `(?:Bearer\s+\S+|Token\s+\S+|\S+)` lets the rule
-// consume the *whole* secret-bearing segment for the common
-// `Authorization=Bearer <jwt>` / `Authorization: Token <pat>` shapes — a
-// plain `\S+` would only eat `Bearer` and leave the JWT exposed.
+// `\b` stops this from stealing rule-4's `FOO_SECRET=` matches; the value alternation eats the whole `Bearer <jwt>`/`Token <pat>` segment.
 const LABELED_KV =
   /\b(?:api[-_]?key|token|secret|password|bearer|authorization)\b\s*[:=]\s*(?:Bearer\s+\S+|Token\s+\S+|\S+)/gi
 
-// Each provider shape replaced with a tagged token so triage can see WHAT
-// was redacted (e.g. `[redacted:anthropic-key]` is a strong hint that the
-// failing call was a Claude auth error) without exposing the key itself.
-//
-// Order: longest / most-specific patterns first. `sk-ant-…` must be tried
-// before the bare `sk-…` OpenAI shape, otherwise the Anthropic key would be
-// partially matched by the OpenAI rule and the `[redacted:anthropic-key]`
-// triage signal would be lost.
+// Tagged tokens let triage see what was redacted without the key. Order is most-specific-first: `sk-ant-` before `sk-`, or the Anthropic tag is lost.
 const PROVIDER_PATTERNS: { tag: string; re: RegExp }[] = [
   { tag: 'anthropic-key', re: /sk-ant-[a-zA-Z0-9_-]{40,}/g },
   { tag: 'openai-key', re: /sk-(?:proj-)?[a-zA-Z0-9_-]{32,}/g },
@@ -70,43 +30,18 @@ const PROVIDER_PATTERNS: { tag: string; re: RegExp }[] = [
   { tag: 'slack-token', re: /xox[baprsoe]-[A-Za-z0-9-]{10,}/g },
   {
     tag: 'pem',
-    // Greedy intentionally bounded by the matching END marker; PEM blocks are
-    // multi-line. The `[\s\S]+?` keeps it minimal so a buffer with two PEM
-    // blocks back-to-back redacts each one independently rather than gobbling
-    // text between them.
+    // Lazy `[\s\S]+?` so two back-to-back PEM blocks redact independently, not as one gobbled span.
     re: /-----BEGIN [A-Z ]+-----[\s\S]+?-----END [A-Z ]+-----/g
   }
 ]
 
-// Userinfo strip — preserves host + path so the debug context (`failed to
-// fetch from github.com/foo/bar`) is intact while removing the credential.
-// Two shapes are valid in practice and both leak credentials:
-//   - `https://user:pass@host/...`  (classic basic-auth URL)
-//   - `https://<token>@github.com/...` (GitHub PAT-in-URL — exactly what
-//     `git clone` emits when push/pull fails. No colon, just a token before
-//     the `@`.)
-// The pattern matches either: any non-empty `[^/@\s]+@` after the scheme is
-// userinfo and gets stripped. Spec mentions only the colon-bearing form,
-// but the bare-token form is the one we actually see in failing git stderr.
+// Strip URL userinfo — both `user:pass@` and bare-token `<pat>@` (seen in failing git stderr); keep host+path for debug context.
 const URL_USERINFO = /(https?:\/\/)([^/@\s]+)@/g
 
-// Per-line .env shape. The `m` flag is required so `^` anchors at line
-// starts inside multi-line strings (a stack frame, a captured stderr
-// dump, etc.). The pattern intentionally requires the equals sign on the
-// same line — `FOO=\n  bar` is a different pattern (continuation) and not
-// commonly how secrets show up.
-//
-// The value pattern (`\S.*`) consumes to end of line so multi-token values
-// like `FOO_TOKEN=Bearer <jwt>` are redacted whole rather than leaking the
-// trailing token. The leading `\S` requires the value to start with a
-// non-whitespace char so a bare `FOO=` followed by nothing on the same
-// line doesn't get an empty redact-token.
+// Per-line .env shape. `m` anchors `^` in multi-line strings; `\S.*` redacts the whole value (so `FOO=Bearer <jwt>` can't leak its tail), leading `\S` skips empty `FOO=`.
 const ENV_LINE = /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*\S.*/gm
 
-// Attribute keys that must never carry through, regardless of value. Match
-// is case-insensitive — HTTP headers vary in case and we want all forms.
-// `Object.hasOwn` semantics: presence in this set drops the attribute
-// entirely, the value is never examined.
+// Attribute keys dropped regardless of value. Matched case-insensitively since HTTP headers vary in case.
 const CLIENT_ATTR_BLOCKLIST = new Set([
   'env',
   'environment',
@@ -127,11 +62,7 @@ const CLIENT_ATTR_BLOCKLIST = new Set([
   'headers.authorization'
 ])
 
-// Mode-3 server-side pass adds the PostHog-lane identity keys. These are
-// valid in product telemetry but must not ride along inside a bundle —
-// otherwise an Orca staff member opening the bundle could re-identify all
-// PostHog history for that user (see telemetry-error-tracking.md §"Why
-// bundles do not carry install_id").
+// Identity keys: valid in telemetry but stripped from bundles to prevent re-identifying PostHog history (see telemetry-error-tracking.md).
 const SERVER_ATTR_BLOCKLIST_EXTRA = new Set([
   'install_id',
   'installid',
@@ -147,9 +78,7 @@ function shouldDropAttributeKey(key: string, mode: RedactorMode): boolean {
   if (CLIENT_ATTR_BLOCKLIST.has(k)) {
     return true
   }
-  // Structured span attributes often carry secret labels in the key itself
-  // (`ANTHROPIC_API_KEY`, `clientSecret`, `x-api-key`) with plain values that
-  // string redaction cannot classify. Drop by key family before value redaction.
+  // Drop by key family: keys like `ANTHROPIC_API_KEY`/`x-api-key` carry plain values string redaction can't classify.
   if (
     /\b(api[-_]?key|token|secret|password|bearer|authorization|private[-_]?key)\b/i.test(key) ||
     /(apikey|token|secret|password|authorization|bearer|privkey|privatekey)/.test(normalized)
@@ -162,54 +91,34 @@ function shouldDropAttributeKey(key: string, mode: RedactorMode): boolean {
   return false
 }
 
-/**
- * Apply rules 1–4 to a string. Idempotent — running this twice yields the
- * same output as once, which is what makes triple-application safe.
- */
+/** Apply rules 1–4 to a string. Idempotent, which makes triple-application safe. */
 export function redactString(input: string): string {
   if (typeof input !== 'string' || input.length === 0) {
     return input
   }
   let out = input
 
-  // Rule 1 — labeled key-value. Replace the entire `key: value` segment with
-  // a tagged token. We deliberately blow away the labeled-key alongside the
-  // value because the label name itself ("api_key", "Authorization") leaks
-  // no useful debug context once the value is gone.
+  // Rule 1 — labeled key-value. Drop the key alongside the value; the label name adds no debug context once the value is gone.
   out = out.replace(LABELED_KV, '[redacted:labeled-kv]')
 
-  // Rule 2 — provider-key fingerprints. Each shape is tried independently,
-  // so a string carrying multiple keys gets all of them redacted. The tag
-  // names (e.g. `anthropic-key`) are stable wire identifiers — third-party
-  // tools that read our NDJSON can grep for them.
+  // Rule 2 — provider-key fingerprints. Tag names (`anthropic-key`) are stable wire identifiers third-party NDJSON tools grep for.
   for (const { tag, re } of PROVIDER_PATTERNS) {
     out = out.replace(re, `[redacted:${tag}]`)
   }
 
-  // Rule 3 — URL userinfo. Preserves scheme + host + path; replaces only the
-  // `user:pass@` segment with `[redacted]@`. Done after rule 2 so a userinfo
-  // value that happens to look like a provider key gets the more specific
-  // redaction first.
+  // Rule 3 — URL userinfo. After rule 2 so a key-shaped userinfo value gets the more specific redaction first.
   out = out.replace(URL_USERINFO, '$1[redacted]@')
 
-  // Rule 4 — .env-shape line redaction. Keep the key name (`FOO_SECRET=`),
-  // replace only the value with `[redacted:env-value]`. Done last among the
-  // string passes so a labeled-kv match (rule 1) wins over a coincidentally
-  // .env-shaped substring inside a longer line.
+  // Rule 4 — .env-shape line: keep key, redact value. Last so rule 1 wins over a coincidentally .env-shaped substring.
   out = out.replace(ENV_LINE, (_match, key) => `${String(key)}=[redacted:env-value]`)
 
   return out
 }
 
 /**
- * Recursively redact a value of unknown shape — strings get rules 1–4;
- * objects/arrays/maps recurse; primitives pass through. Designed for the
- * span-attribute and span-event use cases where attribute *values* can be
- * any JSON-shaped thing.
- *
- * Loop guard: we track visited references in a `WeakSet` so a self-referential
- * cycle does not stack-overflow. Cycles are unusual in span attributes but
- * span-event payloads occasionally get serialized error objects with cycles.
+ * Recursively redact a value of unknown shape (strings get rules 1–4; containers
+ * recurse; primitives pass through). The `seen` WeakSet guards against cycles,
+ * which serialized error objects in span-event payloads occasionally contain.
  */
 export function redactValue(
   value: unknown,
@@ -242,8 +151,7 @@ export function redactValue(
     seen.add(value)
     const out: Record<string, unknown> = {}
     for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      // Why: bundle collection re-redacts parsed NDJSON, where secrets can
-      // appear below attributes as nested HTTP headers or identity payloads.
+      // Why: re-redacting parsed NDJSON can surface secrets nested below attributes (headers, identity payloads).
       if (shouldDropAttributeKey(k, mode)) {
         continue
       }
@@ -251,15 +159,11 @@ export function redactValue(
     }
     return out
   }
-  // Functions / symbols — coerce to a string label rather than carrying the
-  // value through. These do not show up in legitimate spans.
+  // Functions / symbols: coerce to a label; they don't appear in legitimate spans.
   return `[unsupported:${typeof value}]`
 }
 
-/**
- * Redact an attributes record: drop blocked keys, recursively redact values
- * of remaining keys.
- */
+/** Redact an attributes record: drop blocked keys, recursively redact the rest. */
 export function redactAttributes(
   attrs: Readonly<Record<string, unknown>>,
   mode: RedactorMode = 'client'
@@ -302,17 +206,9 @@ export type RedactableSpan = {
 }
 
 /**
- * Redact a complete span record. Returns a new record — the input is not
- * mutated, which keeps the redactor safe to run mid-pipeline (e.g. the sink
- * holds a reference to the live span until end()) and idempotent.
- *
- * The exit `cause` string carries the formatted stack trace and is one of
- * the most-likely places for a leaked secret (provider SDKs routinely echo
- * the auth token back in the error message). Apply rules 1–4 there.
- *
- * Span event attribute keys are redacted with the same blocklist as span
- * attributes; an `authorization` event-attribute is just as leaky as an
- * `authorization` span-attribute.
+ * Redact a complete span record into a fresh record (input not mutated) so the
+ * redactor stays safe to run mid-pipeline and idempotent. The exit `cause` holds
+ * the stack trace — a likely secret-leak site — so rules 1–4 run there too.
  */
 export function redactSpan(span: RedactableSpan, mode: RedactorMode = 'client'): RedactableSpan {
   const redactedAttrs = redactAttributes(span.attributes, mode)
@@ -339,8 +235,7 @@ export function redactSpan(span: RedactableSpan, mode: RedactorMode = 'client'):
   }
 }
 
-// ── Test-only introspection (kept here so tests can verify the rule set
-// without re-deriving it from external assertions). ─────────────────────────
+// Test-only introspection: lets tests verify the rule set without re-deriving it.
 
 export const _internalsForTests = {
   PROVIDER_PATTERNS,
diff --git a/src/main/persistence.test.ts b/src/main/persistence.test.ts
index 4c3af4b485b..ed2508be9f0 100644
--- a/src/main/persistence.test.ts
+++ b/src/main/persistence.test.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: this persistence suite keeps defaulting,
-migration, mutation, and flush behavior in one file so schema changes are
-reviewed against the full storage contract instead of being scattered. */
+/* eslint-disable max-lines -- Why: one file keeps the full storage contract (defaults, migration, mutation, flush) reviewable together. */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import {
   writeFileSync,
@@ -47,9 +45,7 @@ import { closeTerminalTabInWorkspaceSession } from '../shared/workspace-session-
 // Shared mutable state so the electron mock can reference a per-test directory
 const testState = { dir: '' }
 
-// Stub the ~/.ssh/config parser so the SSH-import integration test below drives
-// the real Store (real normalizeSshTarget + disk round-trip) with deterministic
-// config hosts instead of the operator's actual ~/.ssh/config.
+// Stub the ~/.ssh/config parser so the SSH-import test drives the real Store with deterministic hosts, not the operator's actual ~/.ssh/config.
 const { loadUserSshConfigMock, sshConfigHostsToTargetsMock } = vi.hoisted(() => ({
   loadUserSshConfigMock: vi.fn(),
   sshConfigHostsToTargetsMock: vi.fn()
@@ -717,8 +713,7 @@ describe('Store', () => {
 
   it('coerces non-boolean minimizeToTrayOnClose payloads to a strict boolean', async () => {
     const store = await createStore()
-    // Why: a renderer-supplied non-bool must never persist as a truthy non-bool
-    // that would later read as "tray-minimize on".
+    // Why: a renderer-supplied non-bool must never persist as truthy and later read as "tray-minimize on".
     store.updateSettings({ minimizeToTrayOnClose: 'true' as unknown as boolean })
     expect(store.getSettings().minimizeToTrayOnClose).toBe(false)
     store.updateSettings({ minimizeToTrayOnClose: 1 as unknown as boolean })
@@ -779,8 +774,7 @@ describe('Store', () => {
       store.flush()
     })
 
-    // Why: a profile opened on another OS must not rewrite the mac preference
-    // on its next flush; only the darwin consumers act on the value.
+    // Why: a profile opened on another OS must not rewrite the mac-only preference on flush.
     await withPlatform('win32', async () => {
       const store = await createStore()
       store.updateSettings({ minimizeToTrayOnClose: true })
@@ -821,10 +815,7 @@ describe('Store', () => {
   })
 
   it('persists the existing-user onboarding backfill back to disk', async () => {
-    // Why: the upgrade-cohort backfill is derived at load; this asserts the
-    // backfilled onboarding+gate state round-trips through a write intact (the
-    // load-time scheduleSave that triggers it without a manual flush is wired
-    // via loadNeedsSave at the no-onboarding-block branch).
+    // Why: the upgrade-cohort backfill is derived at load; assert it round-trips through a write intact (load-time scheduleSave via loadNeedsSave, no manual flush).
     writeDataFile({
       schemaVersion: 1,
       ui: {}
@@ -987,9 +978,7 @@ describe('Store', () => {
   })
 
   it('recovers a close timestamp when closed onboarding omits the closedAt key', async () => {
-    // Why: a persisted block missing `closedAt` entirely (vs an explicit null)
-    // must still stay closed via outcome recovery, guarding the
-    // `'closedAt' in raw` sanitizer branch separately from the null case.
+    // Why: a block missing `closedAt` entirely (vs explicit null) must still stay closed via outcome recovery, guarding the `'closedAt' in raw` branch.
     writeDataFile({
       onboarding: {
         flowVersion: ONBOARDING_FLOW_VERSION,
@@ -1007,9 +996,7 @@ describe('Store', () => {
   })
 
   it('does not mutate gate fields for a consistent closed-onboarding existing user', async () => {
-    // Why: the gate must be idempotent. A user already persisted as
-    // closed+completed must round-trip unchanged — the backfill path must not
-    // fire and stomp the real closedAt with a fresh Date.now() each launch.
+    // Why: the gate must be idempotent — a closed+completed user round-trips unchanged, and the backfill must not stomp closedAt with a fresh Date.now().
     const consistent = {
       onboarding: {
         flowVersion: ONBOARDING_FLOW_VERSION,
@@ -1242,8 +1229,7 @@ describe('Store', () => {
   // ── 2. Load from existing valid file ─────────────────────────────────
 
   it('reads repos from an existing data file', async () => {
-    // Why: hydration must serve the persisted username without spawning
-    // git/gh (issue #7225); resolution happens in background enrichment.
+    // Why: hydration serves the persisted username without spawning git/gh (issue #7225); resolution happens in background enrichment.
     const repo = makeRepo({ gitUsername: 'testuser' })
     writeDataFile({
       schemaVersion: 1,
@@ -1384,8 +1370,7 @@ describe('Store', () => {
       source: 'ssh-config'
     })
 
-    // normalizeSshTarget must not strip `source` on update, and the new port
-    // must take effect — this is the persistence-layer guard for #4684 item #1.
+    // normalizeSshTarget must not strip `source` on update and the new port must take effect (persistence-layer guard for #4684 item #1).
     const updated = store.updateSshTarget('ssh-src-1', { port: 2222, source: 'ssh-config' })
     expect(updated?.port).toBe(2222)
     expect(updated?.source).toBe('ssh-config')
@@ -1455,17 +1440,14 @@ describe('Store', () => {
     expect(inserted[0]?.source).toBe('ssh-config')
     expect(inserted[0]?.port).toBe(2200)
 
-    // Rotated port: the upsert must update the SAME target in place — and the
-    // real normalizeSshTarget must keep `source` and not falsely re-derive
-    // configHost into a permanently-dirty state.
+    // Rotated port: upsert updates the same target in place and normalizeSshTarget must keep `source` (no false re-derive into a permanently-dirty state).
     sshConfigHostsToTargetsMock.mockReturnValue(candidate(2222, 'ssh-cfg-2'))
     const changed = sshStore.importFromSshConfig()
     expect(changed).toHaveLength(1)
     expect(changed[0]?.port).toBe(2222)
     expect(changed[0]?.source).toBe('ssh-config')
 
-    // A third identical sync is a no-op (dirty-check against the real persisted
-    // fields) — proving repeated auto-sync on every pane open writes nothing.
+    // A third identical sync is a no-op — repeated auto-sync on every pane open writes nothing.
     expect(sshStore.importFromSshConfig()).toHaveLength(0)
 
     // Exactly one cluster target on disk with the rotated port and source kept.
@@ -1909,8 +1891,7 @@ describe('Store', () => {
     seed.createAutomationRun(automation, new Date('2026-05-13T09:00:00Z').getTime())
     seed.flush()
 
-    // Why: a fresh store never stamps the one-shot UI migration flags, so a
-    // second load+flush settles them — otherwise they, not the prune, mark dirty.
+    // Why: a second load+flush settles the one-shot UI migration flags first, so they (not the prune) don't mark the store dirty.
     const warm = await createStore()
     warm.flush()
 
@@ -1925,8 +1906,7 @@ describe('Store', () => {
         createdAt: 1_000 + i,
         scheduledFor: 1_000 + i
       }
-      // A real legacy file predates runNumber; backfill must run BEFORE the prune
-      // so survivors keep their true ordinals instead of restarting at 1.
+      // Legacy files predate runNumber; backfill must run BEFORE the prune so survivors keep their true ordinals.
       delete legacy.runNumber
       return legacy
     })
@@ -2003,9 +1983,7 @@ describe('Store', () => {
 
     const runs = store.listAutomationRuns(automation.id)
     expect(runs.some((run) => run.id === inFlight.id)).toBe(true)
-    // Final runs beyond the cap were still evicted. The store can briefly hold
-    // cap + 2: the last-created run finalizes after the prune at its creation,
-    // and the late completion lands without a prune of its own.
+    // Store can briefly hold cap+2: the last-created run finalizes after its creation-time prune, and the late completion lands without a prune of its own.
     expect(runs.some((run) => run.id === firstCompletedId)).toBe(false)
     expect(runs.length).toBeLessThanOrEqual(102)
   })
@@ -3534,8 +3512,7 @@ describe('Store', () => {
       displayName: 'remote-wt',
       hostId: 'ssh:ssh-old'
     })
-    // A hostId-less meta under the same id is treated as local and left behind
-    // (conservative: never deletes the wrong host's meta).
+    // A hostId-less meta is treated as local and left behind (never delete the wrong host's meta).
     store.setWorktreeMeta('shared::/local/repo/wt', { displayName: 'local-wt' })
 
     store.removeProjectForHost('shared', 'ssh:ssh-old')
@@ -3606,8 +3583,7 @@ describe('Store', () => {
 
   it('reassignSshTargetId persists a worktree-meta-only re-point (no matching repo)', async () => {
     const store = await createStore()
-    // A meta on the old SSH host with no corresponding repo row — the re-point
-    // must still be saved, not left in memory only.
+    // A meta on the old SSH host with no repo row — the re-point must still be persisted, not memory-only.
     store.setWorktreeMeta('r1::/remote/wt', { displayName: 'wt', hostId: 'ssh:ssh-old' })
 
     const repoIds = store.reassignSshTargetId('ssh-old', 'ssh-new')
@@ -3717,8 +3693,7 @@ describe('Store', () => {
       setupMethod: 'provisioned'
     })
 
-    // Meta-only re-adoption (no repo pinned to the old id) must still migrate
-    // the provisioned setup, or new worktrees would be born on a dead host id.
+    // Meta-only re-adoption must still migrate the provisioned setup, or new worktrees would be born on a dead host id.
     store.reassignSshTargetId('ssh-old', 'ssh-new')
 
     const setups = store.getProjectHostSetups()
@@ -4171,9 +4146,7 @@ describe('Store', () => {
     store.addRepo(makeRepo({ issueSourcePreference: 'origin' }))
     expect(store.getRepo('r1')!.issueSourcePreference).toBe('origin')
 
-    // Why: passing the key with value `undefined` must clear the preference.
-    // Plain `Object.assign` skips undefined values, so without the explicit
-    // delete branch in updateRepo, the persisted record would keep 'origin'.
+    // Why: `Object.assign` skips undefined, so updateRepo needs an explicit delete branch or the key with value undefined wouldn't clear.
     store.updateRepo('r1', { issueSourcePreference: undefined })
     expect(store.getRepo('r1')!.issueSourcePreference).toBeUndefined()
 
@@ -5226,8 +5199,7 @@ describe('Store', () => {
   })
 
   // ── Content-hash write skipping ────────────────────────────────────
-  // Why inode comparison: every real write is a tmp+rename, which allocates a
-  // new inode. An unchanged inode proves no write happened.
+  // Why inode comparison: every real write is a tmp+rename (new inode), so an unchanged inode proves no write happened.
 
   it('skips the disk write when a mutation burst nets out to already-persisted state', async () => {
     vi.useFakeTimers()
@@ -5270,8 +5242,7 @@ describe('Store', () => {
     vi.useFakeTimers()
     try {
       const store = await createStore()
-      // Mutations every 500ms keep resetting the 1s trailing debounce; the
-      // 5s max-wait must force a write anyway.
+      // Mutations every 500ms reset the 1s debounce; the 5s max-wait must force a write anyway.
       let width = 400
       for (let i = 0; i < 11; i++) {
         store.updateUI({ sidebarWidth: width++ })
@@ -5325,8 +5296,7 @@ describe('Store', () => {
     store.persistPtyBinding(binding)
     const inoBefore = statSync(dataFile()).ino
 
-    // The warm-restart re-bind storm: every restored terminal re-asserts an
-    // identical binding with a sync flush. Identical state must not rewrite.
+    // Warm-restart re-bind storm: an identical binding re-asserted with a sync flush must not rewrite.
     store.persistPtyBinding(binding)
 
     expect(statSync(dataFile()).ino).toBe(inoBefore)
@@ -6118,9 +6088,7 @@ describe('Store', () => {
   })
 
   it('uses recent as the default sort for a fresh install (no persisted sortBy)', async () => {
-    // Why: the legacy-recent→smart migration must gate on the *raw* persisted
-    // value, not the normalized default. Otherwise, changing the default sort
-    // to 'recent' would cause every fresh install to be mis-migrated to 'smart'.
+    // Why: the legacy-recent→smart migration must gate on the raw persisted value, not the normalized default, or fresh installs get mis-migrated to 'smart'.
     writeDataFile({
       schemaVersion: 1,
       repos: [],
@@ -6299,11 +6267,7 @@ describe('Store', () => {
   // ── terminalMacOptionAsAlt migration (issue #903) ───────────────────
 
   it('migrates legacy "true" terminalMacOptionAsAlt to "auto" on first load', async () => {
-    // Why: before the 'auto' mode shipped, 'true' was the global default.
-    // A persisted 'true' on an un-migrated install is indistinguishable
-    // from an explicit choice, so we flip to 'auto' and let detection pick
-    // the right value per keyboard layout. Non-US users stop losing their
-    // @ / € / [ ] characters.
+    // Why: legacy 'true' (old default) is indistinguishable from an explicit choice; flip un-migrated installs to 'auto' so non-US layouts keep @ / € / [ ].
     writeDataFile({
       schemaVersion: 1,
       repos: [],
@@ -6439,8 +6403,7 @@ describe('Store', () => {
   })
 
   it('respects already-migrated settings with explicit "true"', async () => {
-    // After migration, if a user deliberately picks 'Both' in the UI,
-    // their choice is preserved on subsequent launches.
+    // A deliberate 'true' ('Both') choice post-migration is preserved on later launches.
     writeDataFile({
       schemaVersion: 1,
       repos: [],
@@ -6456,21 +6419,15 @@ describe('Store', () => {
   })
 
   it('fresh install defaults terminalMacOptionAsAlt to "auto" and marks migrated', async () => {
-    // No data file at all: auto is the new default; migration is considered
-    // complete since there's nothing legacy to migrate.
+    // No data file: 'auto' is the new default and migration is complete (nothing legacy to migrate).
     const store = await createStore()
     expect(store.getSettings().terminalMacOptionAsAlt).toBe('auto')
-    // Fresh install: default is migrated=false (nothing loaded, so the
-    // migration code didn't run). On first persisted write, the flag stays
-    // false, which is fine — next load with legacy 'true' would still
-    // migrate correctly. Only loaded files flip the flag.
+    // Fresh install: migrated stays false (migration code never ran); a later load with legacy 'true' still migrates correctly.
     expect(store.getSettings().terminalMacOptionAsAltMigrated).toBe(false)
   })
 
   it('missing terminalMacOptionAsAlt in persisted file defaults to "auto" and flags migrated', async () => {
-    // Existing file predates the setting entirely. Treat like upgrade from
-    // pre-Option-as-Alt Orca: land on 'auto' and mark migrated so we don't
-    // re-examine.
+    // Existing file predates the setting: land on 'auto' and mark migrated so we don't re-examine.
     writeDataFile({
       schemaVersion: 1,
       repos: [],
@@ -9728,12 +9685,7 @@ describe('Store', () => {
   })
 
   // ── Telemetry cohort migration ─────────────────────────────────────
-  //
-  // The migration keys on `existsSync(dataFile)` rather than field-based
-  // inference because the `telemetry` field is new in this release: keying
-  // on its presence would misclassify every pre-telemetry install as fresh,
-  // silently flipping existing users to default-on and violating the social
-  // contract they installed Orca under.
+  // Why: keys on `existsSync(dataFile)`, not the new `telemetry` field, so pre-telemetry installs aren't misclassified as fresh and flipped default-on.
 
   it('classifies a truly fresh install as new-user cohort (file absent → optedIn=true)', async () => {
     // No data file written — truly fresh install of the telemetry release.
@@ -9771,10 +9723,7 @@ describe('Store', () => {
   })
 
   it('still classifies as existing-user cohort when the data file is corrupt', async () => {
-    // Load-bearing: `fileExistedOnLoad` stays true even when the parse
-    // throws, so the corrupt-file catch path must also apply the migration.
-    // Otherwise a user whose `orca-data.json` got corrupted would be
-    // silently opted in as if they were a fresh install.
+    // Load-bearing: the corrupt-file catch path keeps `fileExistedOnLoad` true so a corrupted install isn't silently opted in as fresh.
     mkdirSync(testState.dir, { recursive: true })
     writeFileSync(dataFile(), '{{{corrupt json', 'utf-8')
     const store = await createStore()
@@ -9814,9 +9763,7 @@ describe('Store', () => {
 })
 
 describe('Store.migrateTabSwitchKeybindings', () => {
-  // Freezes the install cohort for the tab-switch convention swap on first load.
-  // Keys on `fileExistedOnLoad` (not field presence) so the verdict is stable
-  // even after a fresh install writes its own data file on later launches.
+  // Freezes the tab-switch cohort on first load, keying on `fileExistedOnLoad` (not field presence) so the verdict survives later launches.
 
   beforeEach(() => {
     testState.dir = mkdtempSync(join(tmpdir(), 'orca-test-'))
@@ -9864,8 +9811,7 @@ describe('Store.migrateTabSwitchKeybindings', () => {
       workspaceSession: {}
     })
     const store = await createStore()
-    // Existing file but cohort already resolved to 'done' — must not flip to
-    // 'pending' just because the data file happens to exist.
+    // Existing file, cohort already 'done' — must not flip to 'pending' just because the file exists.
     expect(store.getSettings().tabSwitchKeybindingSeed).toBe('done')
   })
 })
@@ -10194,9 +10140,7 @@ describe('Store native-chat tab viewMode persistence', () => {
     rmSync(testState.dir, { recursive: true, force: true })
   })
 
-  // Why: a tab persisted in 'chat' must restore to 'chat' (R1), and a tab
-  // persisted before the field existed must default to 'terminal' — i.e. the
-  // field is absent on restore — so older sessions stay backward-compatible.
+  // Why: tabs persisted before viewMode existed default to 'terminal' so older sessions stay backward-compatible.
   it('round-trips viewMode for unified tabs and defaults legacy tabs to terminal', async () => {
     const WORKTREE = 'repo1::/worktree'
     writeDataFile({
diff --git a/src/main/persistence.ts b/src/main/persistence.ts
index 3810763057a..2e5b8255367 100644
--- a/src/main/persistence.ts
+++ b/src/main/persistence.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: persistence keeps schema defaults, migration,
-load/save, and flush logic in one file so the full storage contract is reviewable
-as a unit instead of being scattered across modules. */
+/* eslint-disable max-lines -- Why: persistence keeps schema defaults, migration, and load/save/flush in one file so the storage contract reviews as a unit. */
 import { app, safeStorage } from 'electron'
 import {
   readFileSync,
@@ -259,9 +257,7 @@ function decrypt(ciphertext: string): string {
   try {
     return safeStorage.decryptString(Buffer.from(ciphertext, 'base64'))
   } catch {
-    // Why: if decryption fails, it likely means the value was stored as
-    // plaintext (pre-encryption build) or the OS keychain changed. Fall
-    // back to the raw string so users don't lose their cookie after upgrade.
+    // Why: decrypt failure usually means plaintext (pre-encryption) or a changed keychain; return raw so the cookie survives upgrade.
     console.warn(
       '[persistence] safeStorage decryption failed — returning ciphertext as-is. Possible keychain reset.'
     )
@@ -309,8 +305,7 @@ function retireLegacyInstructionsForClearedTextActionRecipes(
     if (instructionsByOperation?.[actionId] === '') {
       continue
     }
-    // Why: `{basePrompt}` is the explicit clear state; an empty instruction
-    // shadows rollback `commitMessageAi.customPrompt` during normalize/project.
+    // Why: {basePrompt} is the explicit clear state; an empty instruction shadows rollback commitMessageAi.customPrompt on normalize/project.
     instructionsByOperation = { ...instructionsByOperation, [actionId]: '' }
     changed = true
   }
@@ -318,19 +313,8 @@ function retireLegacyInstructionsForClearedTextActionRecipes(
   return changed ? { ...sourceControlAi, instructionsByOperation } : sourceControlAi
 }
 
-// Why: the data-file path must not be a module-level constant. Module-level
-// code runs at import time — before configureDevUserDataPath() redirects the
-// userData path in index.ts — so a constant would capture the default (non-dev)
-// path, causing dev and production instances to share the same file and silently
-// overwrite each other.
-//
-// It also must not be resolved lazily on every call, because app.setName('Orca')
-// runs before the Store constructor and would change the resolved path from
-// lowercase 'orca' to uppercase 'Orca'. On case-sensitive filesystems (Linux)
-// this would look in the wrong directory and lose existing user data.
-//
-// Solution: index.ts calls initDataPath() right after configureDevUserDataPath()
-// but before app.setName(), capturing the correct path at the right moment.
+// Why capture once (not a module const, not per-call): a const resolves before configureDevUserDataPath() redirects userData (dev/prod collide);
+// per-call resolves after app.setName('Orca') flips path case and loses data on case-sensitive FS. index.ts calls initDataPath() at the right moment.
 let _dataFile: string | null = null
 let _userDataDir: string | null = null
 
@@ -350,38 +334,25 @@ function getDataFile(): string {
   return _dataFile
 }
 
-// Why a sidecar: githubCache is a refetchable 5-min-TTL poll cache whose
-// fetchedAt stamps change on every refresh — keeping it inside orca-data.json
-// made every poll cycle rewrite the whole multi-MB durable state (defeating
-// the content-hash guard by design). It lives in memory during the session
-// and is snapshotted here best-effort at quit so PR/issue badges still paint
-// instantly on the next launch. Loss of this file costs nothing.
+// Why a sidecar: githubCache refreshes every poll and would rewrite the whole multi-MB orca-data.json each cycle.
+// Snapshotted best-effort at quit for instant badges next launch; safe to lose.
 function getGithubCacheFile(dataFile = getDataFile()): string {
   return join(dirname(dataFile), 'orca-github-cache.json')
 }
 
-// Why: worktrees deleted outside Orca (git CLI worktree remove, rm -rf,
-// agent scripts) purge renderer session state but nothing removed their
-// worktreeMeta, so the map grew monotonically (63% dead entries measured on
-// a heavy install). GC is deliberately narrow: local-host entries only
-// (SSH/runtime metas embed remote paths a local existsSync would falsely
-// condemn; WSL UNC paths are skipped the same way), and only after a
-// 30-day idle grace so pushTarget cleanup for recently-vanished worktrees
-// and quick recreations keep their metadata.
+// Why: worktrees deleted outside Orca orphan their worktreeMeta, so the map grew monotonically (63% dead on a heavy install).
+// GC stays narrow: local-host entries only (a local existsSync would falsely condemn SSH/WSL remote paths) and only after a 30-day idle grace.
 const WORKTREE_META_GC_GRACE_MS = 30 * 24 * 60 * 60 * 1000
 
 function gcStaleWorktreeMeta(state: PersistedState): number {
-  // Why: a hand-corrupted file with `"worktreeMeta": null` overrides the
-  // defaults merge; normalize instead of throwing outside the parse guard.
+  // Why: a hand-corrupted "worktreeMeta": null overrides the defaults merge; normalize here instead of throwing.
   state.worktreeMeta ??= {}
   const repoById = new Map(state.repos.map((repo) => [repo.id, repo]))
   const projectIds = new Set((state.projects ?? []).map((project) => project.id))
   const now = Date.now()
   let removed = 0
   for (const key of Object.keys(state.worktreeMeta)) {
-    // Why: folder-project workspace instances are keyed
-    // `repoId::path::workspace:<uuid>` and their meta IS the workspace
-    // record — never a filesystem-checkout row. Skip them entirely.
+    // Why: folder-project workspace instances (keyed repoId::path::workspace:<uuid>) ARE the workspace record, not a checkout row; skip them.
     if (key.includes(FOLDER_WORKSPACE_INSTANCE_SEPARATOR)) {
       continue
     }
@@ -398,29 +369,22 @@ function gcStaleWorktreeMeta(state: PersistedState): number {
         continue
       }
     } else if (projectIds.has(ownerId)) {
-      // Project-owned metas keep project/host semantics on the entry itself;
-      // stay conservative and leave them to their own lifecycle.
+      // Project-owned metas keep their own project/host lifecycle; leave them alone.
       continue
     }
-    // Unowned entries (repo removed before removeProject pruned metas) fall
-    // through to the same missing-path + idle-grace gate.
+    // Unowned entries (repo removed before metas were pruned) fall through to the same missing-path + idle-grace gate.
     if (meta?.hostId && meta.hostId !== LOCAL_EXECUTION_HOST_ID) {
       continue
     }
     if (!isAbsolute(worktreePath) || isWslUncPath(worktreePath)) {
       continue
     }
-    // Why: WSL linked worktrees on Windows carry Linux-style paths from git
-    // porcelain; a Windows existsSync cannot probe those and would falsely
-    // condemn live worktrees.
+    // Why: WSL worktrees on Windows carry Linux-style paths that Windows existsSync can't probe and would falsely condemn.
     if (process.platform === 'win32' && !isWindowsAbsolutePathLike(worktreePath)) {
       continue
     }
-    // Why keep timestamp-less entries: without lastActivityAt/createdAt we
-    // cannot prove the 30-day idle grace elapsed; the measured dead entries
-    // all carry timestamps, so this costs almost nothing in reclaimed bytes.
-    // Grace runs before the stat so healthy profiles skip the existsSync
-    // fan-out (and its slow-NFS tail) for active entries entirely.
+    // Why keep timestamp-less entries: without timestamps we can't prove the 30-day grace elapsed (measured dead entries all had them).
+    // Grace is checked before existsSync so active entries skip the stat fan-out (and its slow-NFS tail).
     const newestTouch = Math.max(meta?.lastActivityAt ?? 0, meta?.createdAt ?? 0)
     if (newestTouch === 0 || now - newestTouch < WORKTREE_META_GC_GRACE_MS) {
       continue
@@ -455,13 +419,9 @@ function readGithubCacheSnapshot(dataFile: string): PersistedState['githubCache'
 }
 
 /**
- * Return the userData directory captured at initDataPath() time, before
- * app.setName() can change how app.getPath('userData') resolves.
+ * Return the userData directory captured at initDataPath() time, before app.setName() can change how app.getPath('userData') resolves.
  *
- * Subsystems that must share storage with orca-data.json (mobile pairing's
- * DeviceRegistry, E2EE keypair, runtime metadata) read this instead of
- * resolving the path late, which on case-sensitive filesystems can land in a
- * different directory and lose paired devices across restarts/updates.
+ * Subsystems sharing storage with orca-data.json read this instead of resolving late, which on case-sensitive FS can lose paired devices.
  */
 export function getCanonicalUserDataPath(): string {
   if (!_userDataDir) {
@@ -474,10 +434,7 @@ export function getCanonicalUserDataPath(): string {
 /**
  * Copy legacy mobile pairing credentials into the canonical userData directory.
  *
- * Existing installs may already have credentials in the late app.getPath('userData')
- * directory. Before switching the runtime server to the canonical path, copy the
- * registry and E2EE keypair forward as a pair so an update does not force one
- * last re-pair or mix devices with the wrong key.
+ * Copies the registry and E2EE keypair forward as a pair so an update doesn't force a re-pair or mix devices with the wrong key.
  */
 export function migrateMobilePairingDataToCanonicalUserDataPath(sourceUserDataDir: string): void {
   const targetUserDataDir = getCanonicalUserDataPath()
@@ -499,16 +456,12 @@ export function migrateMobilePairingDataToCanonicalUserDataPath(sourceUserDataDi
   mkdirSync(targetUserDataDir, { recursive: true })
   for (const { sourcePath, targetPath } of migrations) {
     copyFileSync(sourcePath, targetPath)
-    // Why: these are credential files (device tokens, E2EE secret key). copyFileSync
-    // does not carry Windows ACLs, so re-assert the current-user-only restriction on
-    // the copy instead of relying on the runtime's later lazy re-harden on read.
+    // Why: copyFileSync drops Windows ACLs, so re-assert current-user-only on these credential copies (device tokens, E2EE key).
     hardenExistingSecureFile(targetPath)
   }
 }
 
-// Why (issue #1158): keep 5 rolling backups of orca-data.json so a corrupt or
-// empty write leaves at least one earlier copy recoverable. Five snapshots at
-// >=1-hour spacing cover recent work without churning disk on every debounce.
+// Why (issue #1158): keep 5 rolling backups at >=1h spacing so a corrupt/empty write leaves an earlier copy recoverable.
 const BACKUP_COUNT = 5
 const BACKUP_MIN_INTERVAL_MS = 60 * 60 * 1000
 const WORKSPACE_SESSION_PATCH_FULL_NORMALIZATION_KEYS = new Set<keyof WorkspaceSessionState>([
@@ -531,11 +484,8 @@ function workspaceSessionPatchNeedsFullNormalization(patch: WorkspaceSessionPatc
   )
 }
 
-/** Normalize the persisted non-'local' host partitions. 'local' is intentionally
- *  dropped here — it is the legacy workspaceSession blob — so the two surfaces
- *  never diverge. Each partition is zod-validated independently: a corrupt host
- *  drops to defaults without taking out the others. Idempotent: re-running on an
- *  already-normalized map yields the same shape. */
+/** Normalize non-'local' host partitions; 'local' (the legacy workspaceSession blob) is dropped so the two surfaces never diverge.
+ *  Each partition is zod-validated independently, so one corrupt host drops to defaults without taking out the others. Idempotent. */
 function parseWorkspaceSessionsByHostId(
   raw: unknown,
   defaults: WorkspaceSessionState
@@ -546,8 +496,7 @@ function parseWorkspaceSessionsByHostId(
   const partitions: Partial<Record<ExecutionHostId, WorkspaceSessionState>> = {}
   for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
     const hostId = normalizeExecutionHostId(key)
-    // Why: 'local' belongs in workspaceSession; an invalid/local key here is
-    // legacy noise and must not shadow the canonical local partition.
+    // Why: 'local' lives in workspaceSession; a local/invalid key here is legacy noise that must not shadow the canonical partition.
     if (!hostId || hostId === LOCAL_EXECUTION_HOST_ID) {
       continue
     }
@@ -706,8 +655,7 @@ function migrateAgentYoloDefaults(
   }
 
   return {
-    // Why: legacy users could only customize per-agent launch defaults via
-    // command overrides, so those agents are treated as already user-owned.
+    // Why: legacy users could only customize launch defaults via command overrides, so those agents count as already user-owned.
     agentDefaultArgs: migratedArgs,
     agentDefaultEnv: migratedEnv,
     agentYoloDefaultsMigrated: true
@@ -1092,8 +1040,7 @@ function backfillLegacyAutomationContexts(
     )
     const next: Automation = { ...automation }
     if (!Object.hasOwn(next, 'runContext')) {
-      // Why: pre-host-context automations only stored a repo id. Backfill the
-      // explicit run target once so dispatch/precheck no longer infer it later.
+      // Why: pre-host-context automations only stored a repo id; backfill the run target once so dispatch/precheck stop inferring it.
       next.runContext = contexts.runContext
       changed = true
     }
@@ -1146,22 +1093,19 @@ type LegacySshTarget = SshTarget & {
   remoteWorkspaceSyncGracePeriodSeconds?: unknown
 }
 
-// Why: old persisted targets predate configHost. Default to label-based lookup
-// so imported SSH aliases keep resolving through ssh -G after upgrade.
+// Why: old targets predate configHost; default to label-based lookup so imported SSH aliases still resolve via ssh -G.
 function normalizeSshTarget(t: SshTarget): SshTarget {
   const target = { ...(t as LegacySshTarget) }
   const legacySyncEnabled = target.remoteWorkspaceSyncEnabled
   const currentGracePeriodSeconds = target.relayGracePeriodSeconds
   const legacyGracePeriodSeconds = target.remoteWorkspaceSyncGracePeriodSeconds
   const systemSshConnectionReuse = target.systemSshConnectionReuse
-  // Why: remote workspace sync now follows the SSH relay lifecycle, so the
-  // retired per-target sync opt-out and grace-period fields stop at disk load.
+  // Why: remote sync now follows the SSH relay lifecycle, so retired per-target sync/grace fields are dropped at disk load.
   delete target.remoteWorkspaceSyncEnabled
   delete target.remoteWorkspaceSyncGracePeriodSeconds
   delete target.relayGracePeriodSeconds
   delete target.systemSshConnectionReuse
-  // Why: synced legacy targets ignored stale relayGracePeriodSeconds values.
-  // Prefer the synced grace so a user's "unlimited" (0) survives migration.
+  // Why: prefer the synced grace over stale relayGracePeriodSeconds so a user's "unlimited" (0) survives migration.
   const relayGracePeriodSeconds =
     legacySyncEnabled === true && typeof legacyGracePeriodSeconds === 'number'
       ? legacyGracePeriodSeconds
@@ -1170,8 +1114,7 @@ function normalizeSshTarget(t: SshTarget): SshTarget {
     ...target,
     configHost: target.configHost ?? target.label ?? target.host
   }
-  // Why: the old SSH form eagerly persisted 10800 even when the user had not
-  // chosen a timeout; treat that legacy default as the new implicit default.
+  // Why: old SSH form persisted 10800 even without a user choice; treat that legacy default as the new implicit default.
   if (
     relayGracePeriodSeconds !== undefined &&
     relayGracePeriodSeconds !== LEGACY_DEFAULT_SSH_RELAY_GRACE_PERIOD_SECONDS
@@ -1184,14 +1127,7 @@ function normalizeSshTarget(t: SshTarget): SshTarget {
   return normalized
 }
 
-// Why: shared by load-time merge and the IPC update handler so the same
-// strict whitelist guards every entry into onboarding state — arbitrary
-// renderer/disk input cannot inject unknown keys or wrong-typed values.
-// Returns only validated fields; unknown keys are dropped silently.
-// Why: returns Partial<...> with a partial checklist so the IPC update path
-// merges over current state without wiping previously-true keys. Invalid
-// top-level fields are OMITTED (not coerced to fallbacks) so partial updates
-// don't clobber valid persisted state; the load-path caller spreads defaults.
+// Why: strict whitelist rejects unknown/bad-typed keys; returns Partial so partial updates don't clobber valid persisted state.
 type SanitizeOnboardingUpdateOptions = {
   migrateLegacyProgress?: boolean
 }
@@ -1203,14 +1139,11 @@ function remapLegacyOnboardingLastCompletedStep(
   if (raw.outcome === 'completed' && lastCompletedStep >= 4) {
     return ONBOARDING_FINAL_STEP
   }
-  // Why: v3 was the four-step flow before the Windows terminal preference
-  // page. Step 4 already meant notifications, so open progress should resume
-  // there rather than treating it as the newly inserted Windows step.
+  // Why: v3 (pre-Windows-terminal-page) step 4 already meant notifications, so resume there, not the inserted Windows step.
   if (raw.flowVersion === 3) {
     return Math.min(4, lastCompletedStep)
   }
-  // Why: v2 was the five-step flow; missing/older versions were seven-step
-  // data where step 4 was removed agent setup, not completed integrations.
+  // Why: v2's five-step flow had step 4 = removed agent setup, not completed integrations.
   if (raw.flowVersion === 2) {
     if (lastCompletedStep === 3) {
       return 2
@@ -1245,10 +1178,7 @@ export function sanitizeOnboardingUpdate(
   } = {}
 
   if ('closedAt' in raw) {
-    // Why: `typeof raw.closedAt === 'number'` would let NaN/Infinity through;
-    // JSON.stringify writes those as `null` on save, which silently reverts
-    // closedAt and re-opens the wizard on next load. Require a finite,
-    // non-negative timestamp so live state matches what disk can persist.
+    // Why: NaN/Infinity serialize to null on save, reverting closedAt and reopening the wizard; require a finite timestamp.
     if (typeof raw.closedAt === 'number' && Number.isFinite(raw.closedAt) && raw.closedAt >= 0) {
       out.closedAt = raw.closedAt
     } else if (raw.closedAt === null) {
@@ -1277,8 +1207,7 @@ export function sanitizeOnboardingUpdate(
     if (typeof v === 'number' && Number.isInteger(v) && v >= -1) {
       const isLegacyFlow =
         options.migrateLegacyProgress && raw.flowVersion !== ONBOARDING_FLOW_VERSION
-      // Why: removing two wizard pages changed numeric meanings. Migrate raw
-      // legacy disk values before the new final-step bound can drop them.
+      // Why: removing two wizard pages changed step numbering; migrate legacy values before the final-step bound drops them.
       const normalized = isLegacyFlow ? remapLegacyOnboardingLastCompletedStep(v, raw) : v
       if (normalized <= ONBOARDING_FINAL_STEP) {
         out.lastCompletedStep = normalized
@@ -1289,8 +1218,7 @@ export function sanitizeOnboardingUpdate(
   if ('checklist' in raw) {
     const rawChecklist = raw.checklist
     if (rawChecklist && typeof rawChecklist === 'object' && !Array.isArray(rawChecklist)) {
-      // Why: copy ONLY caller-sent boolean keys so partial updates (e.g.
-      // `{ addedRepo: true }`) don't reset other checklist items to false.
+      // Why: copy ONLY caller-sent boolean keys so partial updates don't reset other checklist items to false.
       const defaults = getDefaultOnboardingState().checklist
       const rc = rawChecklist as Record<string, unknown>
       const checklist: Partial<OnboardingChecklistState> = {}
@@ -1312,12 +1240,7 @@ function normalizeLoadedOnboardingState(
   input: unknown,
   defaults: OnboardingState
 ): OnboardingState {
-  // Why: if we successfully parsed an existing orca-data.json that lacks an
-  // onboarding block, this is an upgrade-cohort user — backfill as completed
-  // (not dismissed) so they don't get dropped into the wizard regardless of
-  // whether they currently have repos, SSH targets, or just non-default
-  // settings. Analytics still distinguish this from users who explicitly
-  // bailed mid-funnel.
+  // Why: an existing file with no onboarding block is an upgrade user; backfill as completed so they skip the wizard.
   if (!input) {
     return {
       ...defaults,
@@ -1326,16 +1249,11 @@ function normalizeLoadedOnboardingState(
       lastCompletedStep: ONBOARDING_FINAL_STEP
     }
   }
-  // Why: validate every persisted onboarding key explicitly via the shared
-  // sanitizer instead of spreading raw values. A type-flipped field on disk
-  // (string where number expected, unknown checklist key) is dropped or
-  // coerced to the default rather than poisoning in-memory state.
+  // Why: sanitize persisted onboarding keys so a type-flipped field on disk can't poison in-memory state.
   const sanitized = sanitizeOnboardingUpdate(input, {
     migrateLegacyProgress: true
   })
-  // Why: a persisted completed/dismissed outcome means the user left
-  // onboarding. Recover from a bad/missing/null closedAt instead of reopening
-  // the new-user sidebar checklist.
+  // Why: a completed/dismissed outcome means the user left; recover a bad closedAt instead of reopening the checklist.
   const recoveredClosedAt =
     typeof sanitized.closedAt === 'number'
       ? sanitized.closedAt
@@ -1357,13 +1275,11 @@ function resolveSetupGuideSidebarDismissedOnLoad(
   persistedDismissed: unknown,
   onboarding: OnboardingState
 ): boolean {
-  // Why: the sidebar checklist is a new-user prompt. Once onboarding is
-  // closed, persisted false is just the old default value, not a user opt-in.
+  // Why: once onboarding is closed, persisted false is just the old default, not a user opt-in to the sidebar checklist.
   return onboarding.closedAt !== null || persistedDismissed === true
 }
 
-// Why: read a settings field that was removed from GlobalSettings but can
-// still exist on disk. One-shot use for the inline-agents migration.
+// Why: read a settings field removed from GlobalSettings but still on disk; one-shot for the inline-agents migration.
 function readDeprecatedExperimentFlag(parsed: PersistedState | undefined): boolean {
   return (
     (parsed?.settings as { experimentalAgentDashboard?: boolean } | undefined)
@@ -1758,8 +1674,7 @@ function collectMigrationUnsupportedPtyEntries(args: {
     if (!numeric) {
       return false
     }
-    // Why: persisted PaneManager ids are 1-based. A zero-based alias in split
-    // layouts would make tab:1 ambiguous and can route the first pane to the second.
+    // Why: PaneManager ids are 1-based; a zero-based alias in split layouts makes tab:1 ambiguous and misroutes panes.
     const legacyPaneKey = `${args.tabId}:${numeric}`
     agentHookServer.registerPaneKeyAlias(legacyPaneKey, paneKey, ptyId)
     registeredLegacyPaneKeys.add(legacyPaneKey)
@@ -1810,9 +1725,7 @@ function collectMigrationUnsupportedPtyEntries(args: {
       }
     }
   }
-  // Why: legacy numeric pane keys are now bridged by aliases instead of
-  // persisted as restart-required rows. Existing saved rows are pruned during
-  // normalizePersistedPaneIdentityState.
+  // Why: legacy numeric pane keys are now bridged by aliases, not persisted as restart-required rows.
   return { migrationUnsupportedEntries: [], legacyPaneKeyAliasEntries }
 }
 
@@ -1839,9 +1752,7 @@ function legacyMigrationUnsupportedRowsToAliasEntries(
     if (!entry.paneKey) {
       continue
     }
-    // Why: pre-stable dev/RC migration rows did not store the old numeric
-    // key. Only synthesize the single-pane aliases when the row is unambiguous
-    // for its tab; split rows need layout-derived aliases instead of a guess.
+    // Why: pre-stable rows lack the old numeric key; only synthesize single-pane aliases when the row is unambiguous.
     for (const legacyPaneKey of [`${tabId}:0`, `${tabId}:1`]) {
       aliasEntries.push({
         ptyId: entry.ptyId,
@@ -1882,8 +1793,7 @@ function normalizeTerminalLayoutSnapshotForPersistence(
         ? preferredLayout.expandedLeafId
         : null)
     inputSnapshot = { ...inputSnapshot, root, activeLeafId, expandedLeafId }
-    // Why: a debounced renderer writer can still hold the createTab-era empty
-    // layout after persistPtyBinding has already sync-flushed the UUID root.
+    // Why: a debounced renderer writer can still hold the createTab-era empty layout after the UUID root was sync-flushed.
     changed = true
   }
   const inputRoot = inputSnapshot.root
@@ -2014,8 +1924,7 @@ function normalizeWorkspaceSessionPaneIdentities(
       normalizedLayout: normalized.snapshot,
       leafIdByInputLeafId: normalized.leafIdByInputLeafId
     })
-    // Why: old persisted split layouts can generate enough alias rows to
-    // exceed V8's argument limit if the arrays are spread into push().
+    // Why: old split layouts can generate enough alias rows to exceed V8's argument limit if spread into push().
     for (const entry of migrationEntries.migrationUnsupportedEntries) {
       migrationUnsupportedEntries.push(entry)
     }
@@ -2070,8 +1979,7 @@ function remapSshRemotePtyLeaseLeafIds(
       return { ...lease, leafId: nextLeafId }
     }
     const next = { ...lease }
-    // Why: unmatched legacy leaf ids are ambiguous after migration; do not
-    // re-persist them as durable pane identity.
+    // Why: unmatched legacy leaf ids are ambiguous after migration; don't re-persist them as durable pane identity.
     delete next.leafId
     return next
   })
@@ -2180,9 +2088,7 @@ function remapAcknowledgedAgentPaneKeys(
     }
 
     try {
-      // Why: UI acks are keyed by paneKey just like hook rows. When a legacy
-      // numeric/pane:* leaf is promoted to a UUID, carry the read marker over
-      // so already-seen Activity/sidebar rows do not come back unread.
+      // Why: when a legacy leaf is promoted to a UUID, carry the read marker over so seen rows don't come back unread.
       setAcknowledgement(makePaneKey(tabId, remappedLeafId), acknowledgedAt)
       changed = true
     } catch {
@@ -2193,21 +2099,17 @@ function remapAcknowledgedAgentPaneKeys(
   return { acknowledgements: next, changed }
 }
 
-// Why: bounds a corrupt/bloated persisted list — the gate only ever needs the
-// handful of Claude sessions a daemon can realistically keep alive.
+// Why: bounds a corrupt/bloated persisted list — the gate only needs the few Claude sessions a daemon can keep alive.
 const MAX_CLAUDE_LIVE_PTY_SESSION_IDS = 200
 
-// Why: bound the removed-SSH-target history so remove/re-add churn can't grow
-// the state file without limit. Re-adoption only needs recent removals.
+// Why: bound removed-SSH-target history so remove/re-add churn can't grow the file unbounded.
 const MAX_REMOVED_SSH_TARGET_TOMBSTONES = 50
 
 function normalizeClaudeLivePtySessionIds(value: unknown): string[] {
   if (!Array.isArray(value)) {
     return []
   }
-  // Why: scan newest-first so the cap keeps the most recent ids, matching
-  // addClaudeLivePtySessionId's eviction policy while bounding the work done
-  // on an oversized/corrupt list.
+  // Why: scan newest-first so the cap keeps the most recent ids, matching addClaudeLivePtySessionId's eviction policy.
   const ids: string[] = []
   for (let index = value.length - 1; index >= 0; index -= 1) {
     const entry = value[index]
@@ -2283,8 +2185,7 @@ function registerPersistedPaneKeyAlias(entry: LegacyPaneKeyAliasEntry): void {
     )
     return
   }
-  // Why: detached agents keep their original UUID pane key across restarts;
-  // restore the physical-to-current-owner mapping before hook replay begins.
+  // Why: detached agents keep their UUID pane key across restarts; restore the physical-to-owner mapping before hook replay.
   agentHookServer.transferPaneAuthority(
     entry.legacyPaneKey,
     entry.stablePaneKey,
@@ -2364,8 +2265,7 @@ function mergeProjectHostSetupCompatibilityState(
   const currentRepoIds = new Set(repos.map((repo) => repo.id))
   const projectedProjectIds = new Set(projection.projects.map((project) => project.id))
   const projectedSetupIds = new Set(projection.setups.map((setup) => setup.id))
-  // Why: legacy/repo-backed setup rows use the repo id as the setup id. Keep
-  // only independent setup rows here so repo deletion does not leave ghosts.
+  // Why: legacy/repo-backed setup rows reuse the repo id; keep only independent rows so repo deletion leaves no ghosts.
   const independentSetups = (state.projectHostSetups ?? []).filter((setup) => {
     if (projectedSetupIds.has(setup.id)) {
       return false
@@ -2633,15 +2533,9 @@ export class Store {
   private writeTimer: ReturnType<typeof setTimeout> | null = null
   private pendingWrite: Promise<void> | null = null
   private writeGeneration = 0
-  // Why: after a profile transfer rewrites this store's file on disk behind
-  // its back, the stale in-memory state must never be persisted again — a
-  // late sync flush before the relaunch would resurrect the moved project.
+  // Why: after a profile transfer rewrites this file on disk, a late flush of stale in-memory state would resurrect the moved project.
   private writesFrozen = false
-  // Why: hash of the plaintext state as of the last successful write. Saves
-  // triggered by mutations that net out to identical state skip the full
-  // multi-MB serialize + tmp write + rename. Hashing plaintext (not the
-  // written payload) because encrypt() uses a random IV per call, so the
-  // on-disk bytes differ even for identical state.
+  // Plaintext hash at last write, to skip no-op writes; not the payload, since encrypt() uses a random IV per call.
   private lastWrittenStateHash: string | null = null
   private firstPendingSaveAt: number | null = null
   private githubCacheDirty = false
@@ -2657,8 +2551,7 @@ export class Store {
   private uiChangeListeners = new Set<(ui: PersistedState['ui']) => void>()
 
   constructor(options: StoreOptions = {}) {
-    // Why: profile switching creates more than one possible state path. Capture
-    // the path per Store instance so late async writes cannot follow a global path.
+    // Why: profile switching yields multiple state paths; capture per Store so late async writes can't follow a global path.
     this.dataFile = options.dataFile ?? getDataFile()
     const profileSnapshotRoot = getProfileTerminalScrollbackSnapshotRoot(this.dataFile)
     const legacySnapshotRoot = getProfileTerminalScrollbackSnapshotRoot(getDataFile())
@@ -2688,17 +2581,13 @@ export class Store {
       this.scheduleSave()
     })
     if (normalized.changed || this.loadNeedsSave || adaptedProjectGroups) {
-      // Why: upgraded sessions may contain legacy pane:1 leaves. Rewrite them at
-      // the main persistence boundary so older renderer writes cannot revive them.
-      // Other one-shot load migrations also set loadNeedsSave to persist their
-      // guard flags before the next restart.
+      // Why: rewrite legacy pane:1 leaves so older renderer writes can't revive them; other migrations also set loadNeedsSave.
       this.scheduleSave()
     }
   }
 
   private adaptFlatFolderScanProjectGroups(): boolean {
-    // Why: older folder imports persisted a real parent path but kept all repos
-    // flat. Upgrade that shape into v1 sparse folder scopes on load.
+    // Why: older folder imports kept a real parent path but flat repos; upgrade that shape into v1 sparse folder scopes.
     const groups = this.state.projectGroups ?? []
     const repos = this.state.repos
     if (groups.length === 0 || repos.length === 0) {
@@ -2776,9 +2665,7 @@ export class Store {
     return changed
   }
 
-  // Why (issue #1158): debounced writes fire as often as every 300ms during
-  // active use. The backup ring should capture meaningfully different moments,
-  // not five near-identical snapshots from one burst of store updates.
+  // Why (#1158): debounced writes fire ~every 300ms; throttle backups to distinct moments, not near-identical snapshots.
   private shouldRotateBackups(now: number, dataFile: string): boolean {
     try {
       const mtime = statSync(backupPath(dataFile, 0)).mtimeMs
@@ -2788,9 +2675,7 @@ export class Store {
     }
   }
 
-  // Why: rotate oldest to discarded and shift .bak.i to .bak.i+1 by rename;
-  // then copy the current data file to .bak.0 so load() has a JSON recovery
-  // source even if a later primary write is truncated or corrupted.
+  // Why: rotate current file into the .bak ring so load() can recover if a later primary write is truncated or corrupt.
   private async rotateBackupsAsync(dataFile: string): Promise<void> {
     if (!existsSync(dataFile)) {
       return
@@ -2864,13 +2749,7 @@ export class Store {
   }
 
   private load(allowBackupRecovery = true): PersistedState {
-    // Capture once, at the top: this is the unambiguous "has the user run
-    // Orca before?" signal used by the telemetry cohort migration below.
-    // Field-based inference (e.g., `settings.telemetry` presence) does not
-    // work on the telemetry release itself — `telemetry` is new here, so it
-    // would be absent on every pre-telemetry install and misclassify existing
-    // users as fresh, flipping them to default-on in violation of the
-    // social contract we installed them under.
+    // Capture "has run Orca before?" for telemetry cohort; the telemetry field is new, so field inference misclassifies old users as fresh.
     const dataFile = this.dataFile
     const fileExistedOnLoad = existsSync(dataFile)
     logPersistenceStartupMilestone('persistence-load-start', {
@@ -2890,8 +2769,7 @@ export class Store {
         const parsed = JSON.parse(raw) as PersistedState
         logPersistenceStartupMilestone('persistence-json-parse-done')
 
-        // Why: secret settings are stored encrypted on disk via safeStorage.
-        // Decrypt at the load boundary so the rest of the app sees plaintext.
+        // Why: secrets are stored encrypted via safeStorage; decrypt at the load boundary so the app sees plaintext.
         if (parsed.settings?.opencodeSessionCookie) {
           parsed.settings.opencodeSessionCookie = decrypt(parsed.settings.opencodeSessionCookie)
         }
@@ -2931,19 +2809,7 @@ export class Store {
               parsed.settings?.sourceControlAi,
               legacyCommitMessageAi
             )
-        // Why: before the layout-aware 'auto' mode shipped (issue #903),
-        // terminalMacOptionAsAlt defaulted to 'true' globally. That silently
-        // broke Option-layer characters (@ on Turkish via Option+Q, @ on
-        // German via Option+L, € on French via Option+E) for non-US users.
-        // We can't distinguish a persisted 'true' that the user chose
-        // explicitly from one they inherited from the old default — so on
-        // first launch after upgrade, flip 'true' back to 'auto' and let
-        // the renderer's keyboard-layout probe pick the right value per
-        // layout. US users land on 'true' via detection (no change); non-US
-        // users land on 'false' (correct). 'false'/'left'/'right' are
-        // definitionally explicit choices (they never matched the old
-        // default) so we carry those forward unchanged. The migrated flag
-        // guards against re-running this on subsequent launches.
+        // Why (issue #903): old 'true' default broke non-US Option-layer chars; flip 'true'→'auto' once so the layout probe decides.
         const rawOptionAsAlt = parsed.settings?.terminalMacOptionAsAlt
         const alreadyMigrated = parsed.settings?.terminalMacOptionAsAltMigrated === true
         const migratedOptionAsAlt: 'auto' | 'true' | 'false' | 'left' | 'right' = alreadyMigrated
@@ -2953,17 +2819,13 @@ export class Store {
             : rawOptionAsAlt
         const floatingTerminalDefaultedForAllUsers =
           parsed.settings?.floatingTerminalDefaultedForAllUsers === true
-        // Why: early floating-terminal builds persisted the old off-by-default
-        // value into user profiles. Flip only unmigrated profiles so a later
-        // deliberate opt-out still survives reload.
+        // Why: early builds persisted the old off default; flip only unmigrated profiles so a later opt-out survives reload.
         const migratedFloatingTerminalEnabled = floatingTerminalDefaultedForAllUsers
           ? (parsed.settings?.floatingTerminalEnabled ?? true)
           : true
         const floatingTerminalCwdMigrated =
           parsed.settings?.floatingTerminalCwdMigratedToAppWorkspace === true
-        // Why: an earlier migration wrote '' for the default app-owned notes
-        // directory. Floating terminals should still open at home by default;
-        // markdown notes resolve their app-owned directory through a separate IPC.
+        // Why: an earlier migration wrote '' for the notes dir; floating terminals still open at home, notes use a separate IPC.
         const migratedFloatingTerminalCwd = floatingTerminalCwdMigrated
           ? !parsed.settings?.floatingTerminalCwd
             ? defaults.settings.floatingTerminalCwd
@@ -2996,8 +2858,7 @@ export class Store {
             canonicalLegacyCwd &&
             !migratedFloatingTerminalTrustedCwds.includes(canonicalLegacyCwd)
           ) {
-            // Why: pre-grant profiles with an explicit Floating Workspace cwd
-            // already represented user intent; migrate only that legacy value.
+            // Why: pre-grant profiles with an explicit Floating Workspace cwd already showed intent; migrate only that legacy value.
             migratedFloatingTerminalTrustedCwds.push(canonicalLegacyCwd)
             normalizedFloatingTerminalTrustedCwds.changed = true
           }
@@ -3007,15 +2868,13 @@ export class Store {
         }
         const experimentalActivityDefaultedOffForAllUsers =
           parsed.settings?.experimentalActivityDefaultedOffForAllUsers === true
-        // Why: the Agents view moved back behind Experimental. Flip every
-        // pre-migration profile off once, then preserve future user opt-ins.
+        // Why: the Agents view moved back behind Experimental; flip pre-migration profiles off once, then preserve opt-ins.
         const migratedExperimentalActivity = experimentalActivityDefaultedOffForAllUsers
           ? (parsed.settings?.experimentalActivity ?? false)
           : false
         const autoRenameBranchFromWorkDefaultedOn =
           parsed.settings?.autoRenameBranchFromWorkDefaultedOn === true
-        // Why: default-on rollout should activate old profiles once, but a
-        // later Settings opt-out must survive reloads.
+        // Why: default-on rollout activates old profiles once, but a later Settings opt-out survives reloads.
         const migratedAutoRenameBranchFromWork = normalizeAutoRenameBranchFromWorkDefaultOn(
           parsed.settings
         )
@@ -3141,23 +3000,15 @@ export class Store {
           ),
           settings: {
             ...defaults.settings,
-            // Why (#7977): a persisted experimentalNewWorktreeCardStyle:true is
-            // kept even though the default is now false. The v1.4.130 open-
-            // onboarding auto-default wrote the same plain boolean as a real
-            // opt-in, so a rollback migration would also revert genuine opt-ins;
-            // product intent was only to change the default, and the setting
-            // stays user-toggleable.
+            // Why (#7977): keep persisted experimentalNewWorktreeCardStyle:true — v1.4.130's onboarding auto-wrote it as a plain boolean, so it's indistinguishable from a real opt-in; only the default changed.
             ...stripLegacyTerminalScrollbackBytes(parsed.settings),
             prBotAuthorOverrides: normalizePRBotAuthorOverrides(
               parsed.settings?.prBotAuthorOverrides
             ),
-            // Why: v1.3.42 renamed the cosmetic sidekick setting to pet. Carry
-            // the old persisted flag forward once so enabled users don't lose it.
+            // Why: v1.3.42 renamed the sidekick setting to pet; carry the old flag forward once so enabled users don't lose it.
             experimentalPet:
               parsed.settings?.experimentalPet ?? readLegacySidekickFlag(parsed) ?? false,
-            // Why: early primary-selection builds saved the disabled default.
-            // Flip Linux/macOS profiles once so terminal-style defaults match
-            // platform convention; the guards preserve future opt-outs.
+            // Why: early builds saved the disabled default; flip Linux/macOS profiles once to match platform, guards keep opt-outs.
             primarySelectionMiddleClickPaste: migratePrimarySelectionPlatformDefault
               ? true
               : (parsed.settings?.primarySelectionMiddleClickPaste ??
@@ -3170,8 +3021,7 @@ export class Store {
             ...migratedAutoRenameBranchFromWork,
             ...migratedTerminalCursorStyle,
             terminalLineHeight: migratedTerminalLineHeight,
-            // Why: the old global true default was inherited, while false was
-            // always an explicit opt-out and must survive this one-shot reset.
+            // Why: the old true default was inherited, but false was always an explicit opt-out and must survive this one-shot reset.
             terminalRightClickToPaste: terminalRightClickToPasteDefaultedForPlatform
               ? (parsed.settings?.terminalRightClickToPaste ??
                 defaults.settings.terminalRightClickToPaste)
@@ -3182,8 +3032,7 @@ export class Store {
             ...migratedTerminalTuiScrollSensitivity.settings,
             experimentalActivity: migratedExperimentalActivity,
             experimentalActivityDefaultedOffForAllUsers: true,
-            // Why: compact worktree cards graduated from Experimental; preserve
-            // the old opt-in for profiles written during the rollout.
+            // Why: compact worktree cards graduated from Experimental; preserve the old opt-in for rollout-era profiles.
             compactWorktreeCards: loadedCompactWorktreeCards,
             experimentalCompactWorktreeCards: undefined,
             terminalMacOptionAsAlt: migratedOptionAsAlt,
@@ -3202,11 +3051,9 @@ export class Store {
               parsed.settings?.terminalCustomThemes
             ),
             appIcon: normalizeAppIconId(parsed.settings?.appIcon),
-            // Why: persisted settings can be user-edited or written by older
-            // builds; keep tray-minimize false unless the stored value is true.
+            // Why: persisted settings may be hand-edited or from older builds; keep tray-minimize false unless stored value is true.
             minimizeToTrayOnClose: parsed.settings?.minimizeToTrayOnClose === true,
-            // Why: missing means default-on, and the value must round-trip
-            // unchanged on non-mac hosts; the darwin consumers gate the effect.
+            // Why: missing means default-on; round-trips unchanged on non-mac since darwin consumers gate the effect.
             showMenuBarIcon: parsed.settings?.showMenuBarIcon !== false,
             uiLanguage: normalizeUiLanguage(parsed.settings?.uiLanguage),
             defaultTaskSource: taskProviderSettings.defaultTaskSource,
@@ -3224,9 +3071,7 @@ export class Store {
             notifications: normalizeNotificationSettings(parsed.settings?.notifications),
             sourceControlAi: migratedSourceControlAi,
             sourceControlGroupOrder: normalizedSourceControlGroupOrder,
-            // Why: new builds read sourceControlAi, but rollback builds still
-            // write commitMessageAi; after merging those writes, refresh the
-            // legacy projection for continued rollback compatibility.
+            // Why: rollback builds still read commitMessageAi, so refresh the legacy projection from sourceControlAi for compat.
             commitMessageAi: projectSourceControlAiToLegacyCommitMessageAi(
               migratedSourceControlAi,
               parsed.settings?.commitMessageAi ?? defaults.settings.commitMessageAi
@@ -3236,12 +3081,7 @@ export class Store {
               ...parsed.settings?.voice
             }
           },
-          // Why: 'recent' used to mean the weighted smart sort. One-shot
-          // migration moves it to 'smart'; the flag prevents re-firing after
-          // a user intentionally selects the new last-activity 'recent' sort.
-          // Gate on the *raw* persisted value, not the normalized one: the
-          // default sortBy is now 'recent', so a fresh install with no
-          // persisted sortBy would otherwise be mis-migrated to 'smart'.
+          // Why: legacy 'recent' meant the smart sort; migrate once on the raw value so a fresh 'recent' default isn't remigrated.
           ui: (() => {
             const rawSort = parsed.ui?.sortBy
             const sort = normalizeSortBy(rawSort)
@@ -3257,16 +3097,13 @@ export class Store {
             }
             const workspaceStatusesDefaultOrderMigrated =
               parsed.ui?._workspaceStatusesDefaultOrderMigrated === true
-            // Why: a short-lived default put Done on the left. Repair only
-            // the exact raw payload once; user-authored reorders then survive.
+            // Why: a short-lived default put Done on the left; repair only the exact raw payload once so user reorders survive.
             const workspaceStatusesReorderedDefaultRepaired =
               parsed.ui?._workspaceStatusesReorderedDefaultRepaired === true
-            // Why: only exact legacy default payloads are migrated; users who
-            // customized status labels, colors, icons, or order keep theirs.
+            // Why: only exact legacy default payloads migrate; customized status labels/colors/icons/order are kept.
             const workspaceStatusesDefaultWorkflowMigrated =
               parsed.ui?._workspaceStatusesDefaultWorkflowMigrated === true
-            // Why: visual migration has its own guard so later user choices
-            // of valid legacy color/icon IDs are preserved by runtime writes.
+            // Why: visual migration has its own guard so later user choices of valid legacy color/icon IDs are preserved.
             const workspaceStatusesDefaultVisualsMigrated =
               parsed.ui?._workspaceStatusesDefaultVisualsMigrated === true
             const workspaceStatuses = normalizePersistedWorkspaceStatuses(
@@ -3318,9 +3155,7 @@ export class Store {
                   return candidate
                 }
                 const next = [...candidate]
-                // Why: Linear used to be controlled by the generic issue
-                // property and Ports were always visible. Add the split-out
-                // properties once so existing cards keep their prior surface.
+                // Why: Linear rode the 'issue' property and Ports were always shown; split them out once to preserve existing cards.
                 if (candidate.includes('issue') && !candidate.includes('linear-issue')) {
                   next.push('linear-issue' as const)
                 }
@@ -3352,9 +3187,7 @@ export class Store {
             ) {
               this.loadNeedsSave = true
             }
-            // Why: only upgraded profiles that still use the new default get
-            // the one-time usage-display change notice; brand-new profiles and
-            // users who already chose remaining stay quiet.
+            // Why: only upgraded profiles still on the new default get the one-time usage-display notice; fresh profiles stay quiet.
             const usagePercentageDisplayChangeNoticeDismissed =
               resolveUsagePercentageDisplayChangeNoticeDismissed({
                 rawDismissed: parsed.ui?.usagePercentageDisplayChangeNoticeDismissed,
@@ -3373,14 +3206,12 @@ export class Store {
             }
             return {
               ...defaults.ui,
-              // Why: missing card properties should follow the persisted card
-              // layout mode; explicit property choices are preserved below.
+              // Why: missing card properties follow the persisted layout mode; explicit choices are preserved below.
               worktreeCardProperties: getWorktreeCardModeProperties(
                 loadedCompactWorktreeCards ? 'Compact' : 'Default'
               ),
               ...stripMainOwnedTelemetryMarkerFromUI(parsed.ui),
-              // Why: migrate once from the retired Appearance setting only
-              // when no explicit persisted chrome preference exists yet.
+              // Why: migrate once from the retired Appearance setting only when no explicit chrome preference exists yet.
               rightSidebarOpen,
               rightSidebarTab: normalizeRightSidebarTab(parsed.ui?.rightSidebarTab),
               setupGuideSidebarDismissed,
@@ -3404,21 +3235,13 @@ export class Store {
               ...(migratedCardProps !== undefined
                 ? { worktreeCardProperties: migratedCardProps }
                 : {}),
-              // Why: keep stamping the legacy flag for forward-compat with
-              // a rollback to a pre-default-on build that still reads it.
-              // The new flag is the one that actually gates the migration.
+              // Why: keep stamping the legacy flag for rollback forward-compat; the new flag actually gates the migration.
               _inlineAgentsDefaultedForExperiment: true,
               _inlineAgentsDefaultedForAllUsers: true,
               _expandedWorktreeCardPropertiesDefaulted: true
             }
           })(),
-          // Why: the workspace session is the most volatile persisted surface
-          // (schema evolves per release, daemon session IDs embedded in it).
-          // Zod-validate at the read boundary so a field-type flip from an
-          // older build — or a truncated write from a crash — gets rejected
-          // cleanly instead of poisoning Zustand state and crashing the
-          // renderer on mount. On validation failure, fall back to defaults
-          // and log; a corrupt session file shouldn't trap the user out.
+          // Why: volatile schema; zod-validate workspaceSession at read so a bad payload falls to defaults, not a renderer crash.
           workspaceSession: (() => {
             if (parsed.workspaceSession === undefined) {
               return defaults.workspaceSession
@@ -3433,11 +3256,7 @@ export class Store {
             }
             return { ...defaults.workspaceSession, ...result.value }
           })(),
-          // Why: per-host session partitions for non-'local' hosts. 'local'
-          // stays in workspaceSession (legacy field) so a downgrade still
-          // reads the user's workspace. Each entry is zod-validated the same
-          // way as the legacy blob — a corrupt partition drops to that host's
-          // defaults without poisoning the others.
+          // Why: per-host session partitions, validated independently; 'local' stays in workspaceSession for downgrade compat.
           workspaceSessionsByHostId: parseWorkspaceSessionsByHostId(
             parsed.workspaceSessionsByHostId,
             defaults.workspaceSession
@@ -3464,8 +3283,7 @@ export class Store {
               return []
             }
             const runs = pruneAutomationRuns(backfillAutomationRunNumbers(parsed.automationRuns))
-            // Why: nothing else on the load path marks state dirty, so without
-            // this an oversized legacy file only shrinks at the next unrelated save.
+            // Why: nothing else marks dirty, so an oversized legacy file would otherwise only shrink at the next unrelated save.
             if (runs.length !== parsed.automationRuns.length) {
               this.loadNeedsSave = true
             }
@@ -3478,11 +3296,7 @@ export class Store {
       console.error('[persistence] Failed to load primary state, trying backups:', err)
     }
 
-    // Corrupt-file catch path and "no file on disk" path converge here. The
-    // telemetry migration below runs on whichever branch produced `result`,
-    // because a user whose `orca-data.json` got corrupted is not a fresh
-    // install of the telemetry release — they still count as existing and
-    // must see the opt-in banner, not the default-on toast.
+    // Corrupt-file and no-file paths converge here; a corrupted install counts as existing, so it sees the opt-in banner.
     if (result === null && allowBackupRecovery) {
       let hasBackup = false
       for (let i = 0; i < BACKUP_COUNT; i++) {
@@ -3554,18 +3368,14 @@ export class Store {
       fileExistedOnLoad
     )
 
-    // githubCache lives in a sidecar file now (see getGithubCacheFile). A
-    // legacy in-file cache (pre-sidecar build, or a downgrade round-trip) is
-    // kept as this session's seed and stripped from the durable file by the
-    // save scheduled below; otherwise seed from the sidecar snapshot.
+    // githubCache is a sidecar file now (see getGithubCacheFile); legacy in-file caches seed the session, then get stripped.
     const legacyCache = migrated.githubCache
     const hasLegacyCache =
       Object.keys(legacyCache?.pr ?? {}).length > 0 ||
       Object.keys(legacyCache?.issue ?? {}).length > 0
     if (hasLegacyCache) {
       this.loadNeedsSave = true
-      // Why: mark dirty so the first flush writes the sidecar even if no
-      // poll refresh happens this session — the seed survives the migration.
+      // Why: mark dirty so the first flush writes the sidecar even without a poll refresh this session, preserving the seed.
       this.githubCacheDirty = true
     } else {
       migrated.githubCache = readGithubCacheSnapshot(this.dataFile) ?? migrated.githubCache
@@ -3578,21 +3388,8 @@ export class Store {
     return migrated
   }
 
-  // One-shot telemetry cohort migration. Runs on every `load()` but is a
-  // no-op once `existedBeforeTelemetryRelease` is set, so subsequent launches
-  // pay only the property lookup. Populates:
-  //   - `existedBeforeTelemetryRelease` — cohort discriminator (drives
-  //     whether the existing-user opt-in banner is shown in PR 3;
-  //     new users get no first-launch surface).
-  //   - `optedIn` — new users start opted in; existing users are `null` until
-  //     the banner resolves (the consent resolver returns `pending_banner`
-  //     until then, so nothing transmits).
-  //   - `installId` — anonymous UUID v4. Stable across launches; not surfaced in the UI.
-  // One-shot cohort freeze for the tab-switch keybinding convention swap. Runs
-  // on every `load()` but is a no-op once `tabSwitchKeybindingSeed` is set. The
-  // decision must be frozen on the first post-swap launch: `fileExistedOnLoad`
-  // only distinguishes existing vs fresh on that first run (a fresh install's
-  // data file exists on every subsequent launch), so persist the verdict now.
+  // One-shot telemetry cohort migration: seeds existedBeforeTelemetryRelease, optedIn, and installId (no-op once set).
+  // One-shot tab-switch cohort freeze: fileExistedOnLoad tells existing vs fresh only on the first launch, so persist now.
   private migrateTabSwitchKeybindings(
     state: PersistedState,
     fileExistedOnLoad: boolean
@@ -3601,16 +3398,13 @@ export class Store {
     if (existing === 'pending' || existing === 'done') {
       return state
     }
-    // Why: mark dirty so the frozen cohort survives the next restart even if no
-    // other setting changes this session; without this a fresh install could be
-    // re-read as "existing" once its data file lands on disk.
+    // Why: mark dirty so the frozen cohort persists; else a fresh install re-reads as "existing" after its file lands.
     this.loadNeedsSave = true
     return {
       ...state,
       settings: {
         ...state.settings,
-        // Existing installs pin the old chords via a keybindings.json seed;
-        // fresh installs need nothing beyond the new registry defaults.
+        // Existing installs pin old chords via a keybindings.json seed; fresh installs use the new registry defaults.
         tabSwitchKeybindingSeed: fileExistedOnLoad ? 'pending' : 'done'
       }
     }
@@ -3618,10 +3412,7 @@ export class Store {
 
   private migrateTelemetry(state: PersistedState, fileExistedOnLoad: boolean): PersistedState {
     const existing = state.settings?.telemetry
-    // Why: the one-shot is complete only when all three invariants hold.
-    // Keying on `existedBeforeTelemetryRelease` alone would let a partially-
-    // written telemetry block (crash mid-save, hand-edit, future bug) short-
-    // circuit migration and leave `installId` undefined or `optedIn` wiped.
+    // Why: require all three invariants; keying on existedBeforeTelemetryRelease alone lets a partial block skip migration.
     if (
       typeof existing?.existedBeforeTelemetryRelease === 'boolean' &&
       typeof existing.installId === 'string' &&
@@ -3630,11 +3421,7 @@ export class Store {
     ) {
       return state
     }
-    // Why: cohort is the authoritative discriminator per invariant #8, so
-    // resolve it once and reuse it below — the `optedIn` fallback must not
-    // re-infer cohort from `fileExistedOnLoad` or field presence, or a
-    // partially-written telemetry block could land a new user in the
-    // existing-user `pending_banner` state.
+    // Why: resolve cohort once; re-inferring it in the optedIn fallback could misclassify a partially-written new user.
     const resolvedExistedBefore =
       typeof existing?.existedBeforeTelemetryRelease === 'boolean'
         ? existing.existedBeforeTelemetryRelease
@@ -3646,10 +3433,7 @@ export class Store {
         telemetry: {
           ...existing,
           existedBeforeTelemetryRelease: resolvedExistedBefore,
-          // Why: preserve an explicit opt-in/out if the user has ever resolved
-          // it. Only fall back to the cohort default (new users: on; existing
-          // users: undecided until the first-launch banner resolves) when
-          // optedIn is truly unset (undefined), never when it is `false`.
+          // Why: preserve any explicit opt-in/out; fall back to cohort default only when optedIn is undefined, never when false.
           optedIn:
             existing?.optedIn === true || existing?.optedIn === false || existing?.optedIn === null
               ? existing.optedIn
@@ -3665,11 +3449,7 @@ export class Store {
     }
   }
 
-  // Why 1s trailing + 5s max-wait (previously 300ms trailing, unbounded):
-  // sustained sub-interval mutation bursts used to either rewrite the full
-  // multi-MB state ~3x/sec or postpone the write indefinitely by resetting
-  // the timer. The max-wait bounds crash staleness at 5s while bursts
-  // coalesce; the content-hash guard in the writers skips no-op payloads.
+  // Why 1s trailing + 5s max-wait (was 300ms unbounded): coalesce mutation bursts; max-wait bounds crash staleness at 5s.
   private static SAVE_DEBOUNCE_MS = 1_000
   private static SAVE_MAX_WAIT_MS = 5_000
 
@@ -3684,8 +3464,7 @@ export class Store {
     this.writeTimer = setTimeout(() => {
       this.writeTimer = null
       this.firstPendingSaveAt = null
-      // Why (issue #1158): serialize async writes so backup rotation never has
-      // two callers racing over the same dataFile/tmp/.bak paths.
+      // Why (issue #1158): serialize async writes so backup rotation can't race two callers over the same paths.
       const prev = this.pendingWrite ?? Promise.resolve()
       const next = prev
         .then(() => this.writeToDiskAsync())
@@ -3706,9 +3485,7 @@ export class Store {
     await Promise.all([this.pendingWrite, this.activeViewPreference.waitForPendingWrite()])
   }
 
-  // Why githubCache is omitted: it is memory-only during the session (see
-  // getGithubCacheFile) — excluding it from both the payload and the hash
-  // keeps cache refreshes from ever touching the durable file.
+  // Why githubCache is omitted: memory-only this session (see getGithubCacheFile), so refreshes never touch the durable file.
   private getDurableState(): Omit<PersistedState, 'githubCache'> {
     const { githubCache: _memoryOnly, ...durable } = this.state
     return durable
@@ -3718,12 +3495,9 @@ export class Store {
     return createHash('sha1').update(JSON.stringify(this.getDurableState())).digest('hex')
   }
 
-  // Why: builds the on-disk payload synchronously so the hash and the
-  // serialized bytes reflect the same state tick (no mutation can interleave
-  // before an await).
+  // Why: build payload synchronously so hash and serialized bytes reflect the same state tick (no await interleave).
   private buildStateToSave(): string {
-    // Why: secrets must be encrypted on disk. Clone state so the in-memory
-    // this.state stays plaintext for the rest of the app.
+    // Why: clone before encrypting secrets so in-memory this.state stays plaintext.
     const stateToSave = {
       ...this.getDurableState(),
       settings: {
@@ -3736,22 +3510,18 @@ export class Store {
         browserKagiSessionLink: encryptOptionalSecret(this.state.ui.browserKagiSessionLink)
       }
     }
-    // Why compact: ~20-30% fewer bytes (state-shape dependent; measured 21% on
-    // real state) and less serialize time on the sync-flush path; all readers
-    // JSON.parse, so on-disk formatting is irrelevant.
+    // Why compact: ~20% fewer bytes and less serialize time; all readers JSON.parse so formatting is irrelevant.
     return JSON.stringify(stateToSave)
   }
 
-  // Why: async writes avoid blocking the main Electron thread on every
-  // debounced save during active use.
+  // Why: async writes avoid blocking the main Electron thread on every debounced save.
   private async writeToDiskAsync(): Promise<void> {
     if (this.writesFrozen) {
       return
     }
     const gen = this.writeGeneration
     const stateHash = this.computeStateHash()
-    // Why: a mutation burst that nets out to already-persisted state (or a
-    // flush that raced ahead) must not rewrite a byte-identical multi-MB file.
+    // Why: don't rewrite a byte-identical multi-MB file when state nets out to already-persisted.
     if (stateHash === this.lastWrittenStateHash) {
       return
     }
@@ -3761,24 +3531,17 @@ export class Store {
     await mkdir(dir, { recursive: true }).catch(() => {})
     const tmpFile = `${dataFile}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`
 
-    // Why: wrap write+rename in try/finally-on-error so any failure (ENOSPC,
-    // ENFILE, EIO, permission) removes the tmp file rather than leaving a
-    // multi-megabyte orphan behind. Successful rename consumes the tmp file.
+    // Why: on any write/rename failure, remove the tmp file so it doesn't leave a multi-MB orphan.
     let renamed = false
     try {
       await writeFile(tmpFile, payload, 'utf-8')
-      // Why: if flush() ran while this async write was in-flight, it bumped
-      // writeGeneration and already wrote the latest state synchronously.
-      // Renaming this stale tmp file would overwrite the fresh data.
+      // Why: if flush() bumped writeGeneration mid-write, it already wrote fresher state; don't overwrite it.
       if (this.writeGeneration !== gen) {
         return
       }
       await rename(tmpFile, dataFile)
       renamed = true
-      // Why the gen re-check: a sync flush can interleave during the rename
-      // await, write fresher state, and record its own hash. Recording this
-      // stale hash over it would make later saves skip against content that
-      // is not what the file holds.
+      // Why re-check gen: a sync flush during the rename await may have written fresher state; don't record a stale hash over it.
       if (this.writeGeneration === gen) {
         this.lastWrittenStateHash = stateHash
       }
@@ -3787,8 +3550,7 @@ export class Store {
         await rm(tmpFile).catch(() => {})
       }
     }
-    // Why (issue #1158): rotate only after the atomic rename succeeded; then
-    // re-check the generation so a concurrent flush owns any backup rotation.
+    // Why (issue #1158): rotate backups only after rename succeeded, and let a concurrent flush own rotation.
     if (this.writeGeneration !== gen) {
       return
     }
@@ -3798,18 +3560,13 @@ export class Store {
     }
   }
 
-  // Why: synchronous variant kept only for flush() at shutdown, where the
-  // process may exit before an async write completes.
+  // Why: sync variant only for flush() at shutdown, where the process may exit before an async write completes.
   private writeToDiskSync(opts: { force?: boolean } = {}): void {
     if (this.writesFrozen) {
       return
     }
     const stateHash = this.computeStateHash()
-    // Why: skipping is safe under flushOrThrow's durability contract — a
-    // matching hash means this exact state is already the file's content.
-    // Except when an async write was in flight at flush entry (force): its
-    // rename may already be dispatched past the generation check, and only
-    // an unconditional sync write afterwards reliably out-orders it.
+    // Why: matching hash means the file already holds this state; force overrides when an async rename may be racing past the gen check.
     if (!opts.force && stateHash === this.lastWrittenStateHash) {
       return
     }
@@ -3822,9 +3579,7 @@ export class Store {
 
     const payload = this.buildStateToSave()
 
-    // Why: mirror the async path — on any failure between writeFileSync and
-    // renameSync, remove the tmp file so crashes during shutdown don't leak
-    // orphans into userData.
+    // Why: on any write/rename failure, remove the tmp file so shutdown crashes don't leak orphans.
     let renamed = false
     try {
       writeFileSync(tmpFile, payload, 'utf-8')
@@ -3853,8 +3608,7 @@ export class Store {
     }
     this.firstPendingSaveAt = null
     const asyncWriteWasInFlight = this.pendingWrite !== null
-    // Why: bump writeGeneration so any in-flight async writeToDiskAsync skips
-    // its rename, preventing a stale snapshot from overwriting this sync write.
+    // Why: bump writeGeneration so an in-flight async write skips its rename and can't overwrite this sync write.
     this.writeGeneration++
     this.pendingWrite = null
     this.writeToDiskSync({ force: asyncWriteWasInFlight })
@@ -3929,8 +3683,7 @@ export class Store {
       createdAt: now,
       updatedAt: now
     }
-    // Why: this is the first non-repo-backed setup creation path; it must
-    // persist independently so future repo projection sync does not erase it.
+    // Why: persist independently so future repo projection sync doesn't erase this non-repo-backed setup.
     this.state.projectHostSetups.push(setup)
     this.scheduleSave()
     return { project, setup }
@@ -3984,11 +3737,7 @@ export class Store {
     return { project, setup }
   }
 
-  /**
-   * O(1) read of the persisted repo count. Use this when you only need the
-   * count (e.g. cohort-classifier) — `getRepos()` hydrates each repo, which
-   * is wasteful when the caller only reads `.length`.
-   */
+  /** O(1) repo count; unlike `getRepos()` this skips per-repo hydration. */
   getRepoCount(): number {
     return this.state.repos.length
   }
@@ -3999,9 +3748,8 @@ export class Store {
   }
 
   /**
-   * Record a background-resolved git username (repo-git-username-enrichment).
-   * Kept out of updateRepo's whitelist so the renderer-facing update surface
-   * cannot write it directly. Returns true when the hydrated value changed.
+   * Record a background-resolved git username; kept out of updateRepo's whitelist so the renderer can't write it directly.
+   * @returns true when the hydrated value changed.
    */
   setResolvedRepoGitUsername(id: string, username: string): boolean {
     const repo = this.state.repos.find((r) => r.id === id)
@@ -4014,8 +3762,7 @@ export class Store {
       return false
     }
     if (username) {
-      // Why: persisting the resolved value lets the next launch hydrate repos
-      // with the right branch prefix before enrichment has re-run.
+      // Why: persist so the next launch hydrates repos with the right branch prefix before enrichment re-runs.
       repo.gitUsername = username
     } else {
       delete repo.gitUsername
@@ -4085,8 +3832,7 @@ export class Store {
     if ((this.state.projectGroups?.length ?? 0) === before) {
       return false
     }
-    // Why: groups are sidebar organization only. Deleting one must not delete
-    // repos or worktrees, so contained repos from the full subtree are ungrouped.
+    // Why: groups are sidebar organization only, so deleting one ungroups its repos rather than deleting them.
     this.state.repos = this.state.repos.map((repo) =>
       repo.projectGroupId && deletedGroupIds.has(repo.projectGroupId)
         ? { ...repo, projectGroupId: null }
@@ -4282,9 +4028,7 @@ export class Store {
     this.scheduleSave()
   }
 
-  // Why: returns false on a stale permutation (concurrent add/remove races
-  // the renderer's drag) so the caller can tell the renderer to resync rather
-  // than persist an order that drops or duplicates ids.
+  // Why: return false on a stale permutation (concurrent add/remove) so the caller resyncs instead of persisting an order that drops/duplicates ids.
   reorderRepos(orderedIds: string[]): boolean {
     const current = this.state.repos
     if (orderedIds.length !== current.length) {
@@ -4315,8 +4059,7 @@ export class Store {
     return true
   }
 
-  // Why: repo ids are unique only within an execution host, and renderer drags
-  // persist one complete permutation per host when local and SSH repos coexist.
+  // Why: repo ids are unique only within an execution host; drags persist one permutation per host when local and SSH repos coexist.
   reorderReposForHost(orderedIds: string[], hostId: ExecutionHostId): boolean {
     const current = this.state.repos
     const hostRepos = current.filter((repo) => getRepoExecutionHostId(repo) === hostId)
@@ -4349,44 +4092,32 @@ export class Store {
   removeProject(id: string): void {
     this.state.repos = this.state.repos.filter((r) => r.id !== id)
     this.syncProjectHostSetupCompatibilityState()
-    // Why: presets are repo-scoped, so removing the repo means the presets
-    // can never be referenced again — drop them with the parent.
+    // Why: presets are repo-scoped and unreachable once the repo is gone, so drop them with it.
     delete this.state.sparsePresetsByRepo[id]
     this.pruneWorktreeStateForRepo(id, null)
     this.scheduleSave()
   }
 
-  // Why: the same repo id can exist on more than one execution host (local, an
-  // SSH target, a re-added SSH target). Forgetting one host's copy must remove
-  // only that host's repo row and worktree metadata — never the local or
-  // another host's records that happen to share the id.
+  // Why: the same repo id can exist on multiple execution hosts; remove only this host's row and metadata, never another host's.
   removeProjectForHost(id: string, hostId: ExecutionHostId): void {
     this.state.repos = this.state.repos.filter(
       (r) => !(r.id === id && getRepoExecutionHostId(r) === hostId)
     )
     const idStillPresent = this.state.repos.some((r) => r.id === id)
-    // Why: presets are repo-id-scoped (not host-scoped); only drop them once the
-    // last host's copy of this repo is gone, or a surviving host loses its presets.
+    // Why: presets are repo-id-scoped (not host-scoped); drop them only when the last host's copy is gone.
     if (!idStillPresent) {
       delete this.state.sparsePresetsByRepo[id]
     }
     this.syncProjectHostSetupCompatibilityState()
-    // Why: if the id survives on another host, prune only this host's worktree
-    // metas; otherwise prune everything for the id (matches removeProject).
+    // Why: prune only this host's worktree metas if the id survives elsewhere; otherwise prune everything (matches removeProject).
     this.pruneWorktreeStateForRepo(id, idStillPresent ? hostId : null)
     this.scheduleSave()
   }
 
-  // Clean up worktree meta, lineage, and workspace lineage for a repo id.
-  // When hostId is null, prune all of the repo's entries; when a hostId is
-  // given, prune only entries whose meta.hostId resolves to that host (a
-  // missing hostId is treated as local).
+  // Prune worktree meta/lineage for a repo id; hostId null prunes all entries, else only that host's (missing meta.hostId = local).
   private pruneWorktreeStateForRepo(id: string, hostId: ExecutionHostId | null): void {
     const prefix = `${id}::`
-    // Why: snapshot host membership up front. Lineage pruning below checks the
-    // meta.hostId of worktree keys that may already have been deleted from
-    // worktreeMeta in the first loop, so reading hostId live would misclassify
-    // an SSH worktree as local once its meta is gone.
+    // Why snapshot up front: the first loop deletes metas, so reading meta.hostId live later would misclassify an SSH worktree as local.
     const hostMembership = new Map<string, boolean>()
     const belongsToHost = (key: string): boolean => {
       if (!key.startsWith(prefix)) {
@@ -4399,11 +4130,7 @@ export class Store {
       if (cached !== undefined) {
         return cached
       }
-      // Why default to local: worktree metas created on/after host-ownership
-      // stamping carry hostId. A metas without it predates that and is treated as
-      // local, so a host-scoped (non-local) prune conservatively leaves it — it
-      // may leak a stale entry for a legacy SSH worktree sharing a repo id with a
-      // local repo, but it never deletes the wrong host's live meta.
+      // Why default to local: metas without hostId predate host stamping, so a host-scoped prune skips them rather than risk deleting another host's live meta.
       const metaHostId = this.state.worktreeMeta[key]?.hostId ?? LOCAL_EXECUTION_HOST_ID
       const result = metaHostId === hostId
       hostMembership.set(key, result)
@@ -4490,8 +4217,7 @@ export class Store {
       repo.externalWorktreeVisibilityLegacy === undefined
         ? isLegacyRepoForExternalWorktreeVisibility(repo)
         : undefined
-    // Why: selected repo fields use `undefined` as an explicit clear signal,
-    // so delete them before assigning the rest of the patch.
+    // Why: selected repo fields use `undefined` as an explicit clear signal, so delete them before assigning the patch.
     if (
       'issueSourcePreference' in sanitizedUpdates &&
       sanitizedUpdates.issueSourcePreference === undefined
@@ -4507,8 +4233,7 @@ export class Store {
       'externalWorktreeVisibility' in sanitizedUpdates &&
       repo.externalWorktreeVisibilityLegacy === undefined
     ) {
-      // Why: old persisted repos have no explicit marker. Stamp it the first
-      // time visibility changes so later hide/show choices keep legacy safety.
+      // Why: old persisted repos have no marker; stamp it on first visibility change so later hide/show keeps legacy safety.
       repo.externalWorktreeVisibilityLegacy = externalWorktreeVisibilityLegacy
     }
     if (
@@ -4643,12 +4368,7 @@ export class Store {
     const sourceControlAi = normalizeRepoSourceControlAiOverrides(rawSourceControlAi)
     const projectHostSetupMethod = sanitizeRepoProjectHostSetupMethod(rawProjectHostSetupMethod)
     const forkSyncMode = sanitizeForkSyncMode(rawForkSyncMode)
-    // Why: username resolution spawns git/gh subprocesses, so it must never
-    // run inside hydration — the first getRepos() of a launch executes on the
-    // Electron main thread and a stuck probe froze startup for minutes on
-    // Windows (issue #7225). Hydration only reads the enrichment cache or the
-    // value persisted by a previous launch; repo-git-username-enrichment.ts
-    // refreshes both in the background.
+    // Why: never spawn git/gh username resolution in hydration — a stuck probe froze Windows startup for minutes (issue #7225); read only cache/persisted value.
     const gitUsername = isFolderRepo(repo)
       ? ''
       : (this.gitUsernameCache.get(repo.path) ?? repo.gitUsername ?? '')
@@ -4851,8 +4571,7 @@ export class Store {
       return existing
     }
     const now = Date.now()
-    // Why: retention prunes old runs, so the count of retained runs is no longer
-    // the run's ordinal — carry the number forward from the newest survivor.
+    // Why: retention prunes old runs, so the retained count isn't the ordinal — carry the number forward from the newest survivor.
     const runNumber = nextAutomationRunNumber(
       (this.state.automationRuns ?? []).filter((run) => run.automationId === automation.id)
     )
@@ -5034,15 +4753,10 @@ export class Store {
   }
 
   /**
-   * Move every worktreeId-keyed record from `oldWorktreeId` to `newWorktreeId`
-   * after the worktree's folder (and thus its `${repoId}::${path}` id) was
-   * renamed on disk, so a post-move refresh re-binds the worktree's state under
-   * the new id instead of orphaning it. Records the old id on the new meta's
-   * `priorWorktreeIds` so the session GC/hydration can still recognize PTY
-   * sessions minted under the old (path-derived) id. No-op when the ids match.
-   *
-   * Renderer counterpart: `buildWorktreeRenameState` in store/slices/worktrees.ts
-   * re-keys the renderer's own worktree-scoped maps for the same id change.
+   * Re-key every worktreeId-keyed record from `oldWorktreeId` to `newWorktreeId` after the worktree folder (and its
+   * `${repoId}::${path}` id) was renamed on disk, so a refresh re-binds state instead of orphaning it. Records the old id on
+   * the new meta's `priorWorktreeIds` so session GC/hydration still recognizes PTY sessions minted under it. No-op when ids match.
+   * Renderer counterpart: `buildWorktreeRenameState` in store/slices/worktrees.ts.
    */
   migrateWorktreeIdentity(oldWorktreeId: string, newWorktreeId: string): void {
     if (oldWorktreeId === newWorktreeId) {
@@ -5178,9 +4892,7 @@ export class Store {
     if (movedLineage && movedLineage.worktreeId === oldWorktreeId) {
       movedLineage.worktreeId = newWorktreeId
     }
-    // Why: other worktrees created from this one carry it as parentWorktreeId;
-    // the stable parentWorktreeInstanceId is unaffected, but keep the denormalized
-    // path-derived id consistent too.
+    // Why: children carry this as parentWorktreeId; keep the denormalized path-derived id consistent (parentWorktreeInstanceId is stable).
     for (const lineage of Object.values(this.state.worktreeLineageById)) {
       if (lineage.parentWorktreeId === oldWorktreeId) {
         lineage.parentWorktreeId = newWorktreeId
@@ -5277,10 +4989,7 @@ export class Store {
     }
   }
 
-  // Why: UI view-state (group/sort/filters etc.) is written from both the
-  // desktop renderer and mobile (via the ui.set RPC) into one shared store.
-  // Without this, a mobile change persisted but the desktop renderer — which
-  // hydrates UI state once — never learned of it, breaking bi-directional sync.
+  // Why: UI view-state is written from both desktop and mobile (ui.set RPC), so notify to keep bi-directional sync (desktop hydrates UI only once).
   onUIChanged(listener: (ui: PersistedState['ui']) => void): () => void {
     this.uiChangeListeners.add(listener)
     return () => {
@@ -5303,9 +5012,7 @@ export class Store {
     options: { notifyListeners?: boolean; originWebContentsId?: number } = {}
   ): GlobalSettings {
     const sanitizedUpdates = stripLegacyTerminalScrollbackBytes(updates)
-    // Why: coerce strictly to boolean here (not at the IPC edge) so every write
-    // path is covered and a non-bool renderer payload can never persist a
-    // truthy non-bool that later reads as "tray-minimize on".
+    // Why: coerce to boolean here (not the IPC edge) so every write path is covered and a truthy non-bool can't persist as "tray-minimize on".
     if ('minimizeToTrayOnClose' in updates) {
       sanitizedUpdates.minimizeToTrayOnClose = updates.minimizeToTrayOnClose === true
     }
@@ -5384,8 +5091,7 @@ export class Store {
       sanitizedUpdates.uiLanguage = normalizeUiLanguage(updates.uiLanguage)
     }
     if ('prBotAuthorOverrides' in updates) {
-      // Why: every writer (desktop IPC, paired web RPC, and migrations) reaches
-      // this boundary, so the persisted list stays bounded and well-formed.
+      // Why: every writer (desktop IPC, web RPC, migrations) hits this boundary, so the persisted list stays bounded and well-formed.
       sanitizedUpdates.prBotAuthorOverrides = normalizePRBotAuthorOverrides(
         updates.prBotAuthorOverrides
       )
@@ -5397,12 +5103,7 @@ export class Store {
     if (historyWithPreviousLayout) {
       sanitizedUpdates.workspaceDirHistory = historyWithPreviousLayout
     }
-    // Why: `telemetry` is deep-merged for the same reason `notifications` is —
-    // partial updates from the Privacy pane / consent flow (e.g., flipping
-    // only `optedIn`) must not clobber sibling fields like `installId` or
-    // `existedBeforeTelemetryRelease`. The field is optional, so we only
-    // synthesize a `telemetry` key on the result when at least one side has
-    // one.
+    // Why deep-merge telemetry: a partial update (e.g. flipping only `optedIn`) must not clobber siblings like `installId`.
     const mergedTelemetry =
       sanitizedUpdates.telemetry !== undefined
         ? { ...this.state.settings.telemetry, ...sanitizedUpdates.telemetry }
@@ -5480,8 +5181,7 @@ export class Store {
       usagePercentageDisplay: normalizeUsagePercentageDisplay(
         this.state.ui?.usagePercentageDisplay
       ),
-      // Why: strict boolean coercion so a missing/legacy value reads as false
-      // (first-run notice still fires) rather than leaking a non-bool through.
+      // Why: strict boolean coercion so a missing/legacy value reads as false (first-run notice still fires).
       trayMinimizeNoticeShown: this.state.ui?.trayMinimizeNoticeShown === true,
       markdownTocPanelWidth: clampMarkdownTocPanelWidth(this.state.ui?.markdownTocPanelWidth),
       visibleWorkspaceHostIds: normalizeVisibleExecutionHostIds(
@@ -5604,8 +5304,7 @@ export class Store {
         sanitizedUpdates.featureTipsSeenIds !== undefined
           ? normalizeFeatureTipIds(sanitizedUpdates.featureTipsSeenIds)
           : normalizeFeatureTipIds(this.state.ui?.featureTipsSeenIds),
-      // Why: renderer and paired clients can mark different tours seen from
-      // stale UI snapshots; union them so completed tours stay suppressed.
+      // Why: renderer and paired clients can mark different tours seen from stale snapshots; union so completed tours stay suppressed.
       contextualToursSeenIds:
         updates.contextualToursSeenIds !== undefined
           ? mergeContextualTourSeenIds(
@@ -5613,9 +5312,7 @@ export class Store {
               updates.contextualToursSeenIds
             )
           : normalizeContextualTourIds(this.state.ui?.contextualToursSeenIds),
-      // Why: runtime RPCs and the renderer can both record education state.
-      // Merge instead of replacing so a stale renderer snapshot cannot erase
-      // runtime-only feature interactions.
+      // Why: runtime RPCs and the renderer both record education state; merge so a stale renderer snapshot can't erase runtime-only interactions.
       featureInteractions:
         sanitizedUpdates.featureInteractions !== undefined
           ? mergeFeatureInteractions(
@@ -5719,19 +5416,14 @@ export class Store {
   }
 
   setGitHubCache(cache: PersistedState['githubCache']): void {
-    // Why no scheduleSave: the cache is memory-only during the session and
-    // snapshotted to its sidecar file at flush (quit/reload) time. Every poll
-    // refresh restamps fetchedAt, so persisting here rewrote the whole
-    // durable state file once per poll cycle for refetchable data.
+    // Why no scheduleSave: cache is memory-only and snapshotted to a sidecar at flush; persisting here rewrote the whole state file every poll cycle.
     this.state.githubCache = cache
     this.githubCacheDirty = true
   }
 
   // ── Workspace Session ─────────────────────────────────────────────
 
-  /** Resolve an execution host argument to a canonical id. Unknown/empty
-   *  values fall back to 'local' so legacy callers without a hostId keep
-   *  reading and writing the local partition exactly as before. */
+  /** Resolve an execution host argument to a canonical id; unknown/empty falls back to 'local' for legacy callers. */
   private resolveHostId(hostId?: string | null): ExecutionHostId {
     return normalizeExecutionHostId(hostId) ?? LOCAL_EXECUTION_HOST_ID
   }
@@ -5748,8 +5440,7 @@ export class Store {
     return readTerminalScrollbackSnapshotSync(ref, this.terminalScrollbackSnapshotStorage)
   }
 
-  /** Resolve the worktree a terminal tab belongs to, from the session's
-   *  tab→worktree map. More reliable than agent-echoed hook fields. */
+  /** Resolve the worktree a terminal tab belongs to; more reliable than agent-echoed hook fields. */
   getWorktreeIdForTab(tabId: string): string | undefined {
     return findWorktreeIdForTab(this.getWorkspaceSession(), tabId)
   }
@@ -5763,9 +5454,7 @@ export class Store {
     this.setHostWorkspaceSession(resolved, session)
   }
 
-  /** Persist a non-'local' host partition. The PTY-binding race protections in
-   *  setLocalWorkspaceSession only apply to the local daemon, so remote hosts
-   *  take the lighter prune-and-store path. */
+  /** Persist a non-'local' host partition; remote hosts skip setLocalWorkspaceSession's local-daemon PTY-binding race guards. */
   private setHostWorkspaceSession(hostId: ExecutionHostId, session: WorkspaceSessionState): void {
     const pruned = pruneWorkspaceSessionBrowserHistory(
       pruneLocalTerminalScrollbackBuffers(session, this.state.repos)
@@ -5782,13 +5471,7 @@ export class Store {
       pruneLocalTerminalScrollbackBuffers(session, this.state.repos)
     )
 
-    // Why: closes the second half of the SIGKILL race (Issue #217). The
-    // renderer's debounced session writer captures its state BEFORE pty:spawn
-    // returns, so the snapshot it later flushes via session:set has no
-    // tab.ptyId / ptyIdsByLeafId for the just-spawned PTY. If that stale
-    // snapshot lands AFTER persistPtyBinding's sync flush, it would overwrite
-    // the durable binding and re-open the orphan window. Merge in any
-    // existing bindings whenever the incoming snapshot's binding is empty.
+    // Why (Issue #217): merge existing bindings when the incoming binding is empty, so a stale pre-spawn snapshot can't overwrite the durable PTY binding.
     const prior = this.state.workspaceSession
     const normalized = normalizeWorkspaceSessionPaneIdentities(
       session,
@@ -5868,8 +5551,7 @@ export class Store {
             ([leafId, ptyId]) =>
               liveLeafIds.has(leafId) &&
               incoming[leafId] === undefined &&
-              // Why: an empty layout map can be a stale pre-spawn snapshot; a
-              // partial map is intentional unless a durable SSH lease proves it.
+              // Why: an empty layout map may be a stale pre-spawn snapshot; a partial map is intentional unless a durable SSH lease proves it.
               (incomingHasAnyBinding
                 ? this.hasRestorableSshRemotePtyLease({
                     ptyId,
@@ -5883,8 +5565,7 @@ export class Store {
         )
         if (Object.keys(restorableBindings).length > 0) {
           layout.ptyIdsByLeafId = { ...restorableBindings, ...incoming }
-          // Why: the same stale session write that drops ptyIdsByLeafId can
-          // also be from an older renderer that lacks UUID-keyed metadata.
+          // Why: the same stale write that drops ptyIdsByLeafId may come from an older renderer lacking UUID-keyed metadata.
           const buffersByLeafId = preserveMissingLeafRecordEntries(
             priorLayout.buffersByLeafId,
             layout.buffersByLeafId,
@@ -5925,9 +5606,7 @@ export class Store {
 
   patchWorkspaceSession(patch: WorkspaceSessionPatch, hostId?: string | null): void {
     const resolved = this.resolveHostId(hostId)
-    // Why: the renderer's debounced hot path sends only changed top-level
-    // session slices. Scalar/UI patches avoid the terminal normalization path;
-    // terminal topology/layout patches still reuse the stale-PTY protections.
+    // Why: the debounced hot path sends only changed slices; scalar/UI patches skip terminal normalization, topology patches keep stale-PTY protections.
     let next: WorkspaceSessionState = {
       ...this.getWorkspaceSession(resolved),
       ...patch
@@ -6008,10 +5687,7 @@ export class Store {
     if (lease.ptyId !== bindingPtyId) {
       return false
     }
-    // Why: remote PTY ids are scoped to a relay target. Workspace PTY bindings
-    // only store the id, so derive target/context when possible and require
-    // stored lease context to match instead of treating missing fields as
-    // wildcards that can tombstone unrelated panes.
+    // Why: remote PTY ids are scoped to a relay target; require stored lease context to match so missing fields don't tombstone unrelated panes.
     return (
       (binding.targetId === undefined ||
         binding.targetId === null ||
@@ -6053,9 +5729,7 @@ export class Store {
     if (lease.targetId !== binding.targetId || lease.ptyId !== bindingPtyId) {
       return false
     }
-    // Why: target removal is destructive. Legacy/contextless leases should
-    // scrub matching workspace bindings before the lease record is deleted,
-    // otherwise removing the tombstone can let stale PTY ids revive later.
+    // Why: target removal is destructive; scrub matching bindings before deleting the lease, else removing the tombstone can revive stale PTY ids.
     return (
       (binding.worktreeId === undefined ||
         lease.worktreeId === undefined ||
@@ -6072,12 +5746,7 @@ export class Store {
     return this.state.repos.find((repo) => repo.id === repoId)?.connectionId ?? null
   }
 
-  // Why: closes the SIGKILL-between-spawn-and-persist race (Issue #217). The
-  // renderer's debounced session writer (~450 ms total) is normally the only
-  // path that writes tab.ptyId / ptyIdsByLeafId; a force-quit inside that
-  // window orphans the daemon's history dir. Patching + sync flushing here
-  // before pty:spawn returns guarantees the renderer cannot observe a
-  // spawn-success without the binding already being durable on disk.
+  // Why: sync-flush the pty binding before pty:spawn returns to close the spawn/persist SIGKILL race (Issue #217).
   persistPtyBinding(args: {
     worktreeId: string
     tabId: string
@@ -6095,9 +5764,7 @@ export class Store {
     if (tab) {
       tab.ptyId = args.ptyId
     } else {
-      // Why: pty:spawn can beat the debounced session writer for a newly
-      // created tab. Persist a minimal tab so hydration does not prune the
-      // crash-safe layout binding below as an orphaned tab id.
+      // Why: pty:spawn can beat the debounced writer; persist a minimal tab so hydration won't prune the binding as orphaned.
       const nextTabs = [
         ...(tabs ?? []),
         createMinimalPersistedTerminalTab({
@@ -6117,8 +5784,7 @@ export class Store {
       }
     }
     if (!isTerminalLeafId(args.leafId)) {
-      // Why: legacy renderer-local pane ids may arrive from older callers; keep
-      // them out of durable leaf-keyed layout state after the UUID migration.
+      // Why: keep legacy renderer-local pane ids out of durable leaf-keyed layout state after the UUID migration.
       try {
         this.flushOrThrow()
       } catch (err) {
@@ -6130,15 +5796,12 @@ export class Store {
     const layout = session.terminalLayoutsByTabId?.[args.tabId]
     if (layout) {
       if (!layout.root) {
-        // Why: createTab can persist an empty layout before TerminalPane mounts.
-        // The sync spawn binding must still leave a durable UUID root behind.
+        // Why: createTab can persist an empty layout before TerminalPane mounts; the sync binding still needs a durable root.
         layout.root = { type: 'leaf', leafId: args.leafId }
         layout.activeLeafId = args.leafId
         layout.expandedLeafId = null
       } else if (!layoutContainsLeafId(layout.root, args.leafId)) {
-        // Why: splitPane publishes the new pane and starts pty:spawn before the
-        // debounced full layout snapshot reaches main. Add a minimal leaf so a
-        // crash in that window cannot make the new pane's binding unreachable.
+        // Why: splitPane spawns before its snapshot reaches main; add a minimal leaf so a crash can't strand the pane's binding.
         layout.root = {
           type: 'split',
           direction: 'vertical',
@@ -6155,12 +5818,7 @@ export class Store {
         [args.leafId]: args.ptyId
       }
     } else {
-      // Why: first-spawn-ever for a new tab — the renderer's debounced writer
-      // creates the layout entry on PaneManager init, but the binding has to
-      // be on disk before pty:spawn returns or a SIGKILL inside the same
-      // window would lose ptyIdsByLeafId for split-pane cold restore. The
-      // renderer will overwrite this minimal layout once persistLayoutSnapshot
-      // fires.
+      // Why: first tab spawn — persist a minimal layout so a SIGKILL before the renderer snapshot can't lose ptyIdsByLeafId.
       session.terminalLayoutsByTabId = {
         ...session.terminalLayoutsByTabId,
         [args.tabId]: {
@@ -6235,11 +5893,9 @@ export class Store {
     if (ids.includes(sessionId)) {
       return
     }
-    // Why: drop the oldest entry at the cap — stale ids are pruned against the
-    // daemon at startup anyway, so recency is the only thing worth keeping.
+    // Why: drop oldest at the cap — stale ids get pruned against the daemon at startup, so only recency matters.
     this.state.claudeLivePtySessionIds = [...ids, sessionId].slice(-MAX_CLAUDE_LIVE_PTY_SESSION_IDS)
-    // Why: flush synchronously — a force-quit right after a Claude spawn must
-    // still seed the live-PTY gate on the next launch.
+    // Why: flush sync so a force-quit right after a Claude spawn still seeds the live-PTY gate next launch.
     this.flush()
   }
 
@@ -6286,8 +5942,7 @@ export class Store {
 
   addRemovedSshTargetTombstone(tombstone: RemovedSshTargetTombstone): void {
     const existing = this.state.removedSshTargetTombstones ?? []
-    // Why: dedupe by oldTargetId so a remove/re-remove of the same id can't
-    // stack duplicate tombstones. Newest wins.
+    // Why: dedupe by oldTargetId so re-removing the same id can't stack duplicate tombstones; newest wins.
     const filtered = existing.filter((t) => t.oldTargetId !== tombstone.oldTargetId)
     // Cap the history so pathological churn can't grow the state file unbounded.
     this.state.removedSshTargetTombstones = [...filtered, tombstone].slice(
@@ -6306,10 +5961,8 @@ export class Store {
   }
 
   /**
-   * Re-point every repo and worktree meta pinned to a removed SSH target id
-   * onto a re-added target's id, so orphaned workspaces reattach to the live
-   * host instead of remaining un-removable ghosts. Returns the ids of repos
-   * re-pointed (empty when nothing referenced the old id).
+   * Re-point every repo and worktree meta pinned to a removed SSH target id onto
+   * a re-added target's id so orphaned workspaces reattach. Returns re-pointed repo ids.
    */
   reassignSshTargetId(oldTargetId: string, newTargetId: string): string[] {
     if (oldTargetId === newTargetId) {
@@ -6327,10 +5980,7 @@ export class Store {
       if (matchesConnection) {
         repo.connectionId = newTargetId
       }
-      // Why: only rewrite executionHostId when it was actually set to the old
-      // SSH host. SSH repos created via addRemoteRepoFromPath leave it unset and
-      // derive the host from connectionId, so we must not stamp a value where
-      // there wasn't one.
+      // Why: don't stamp executionHostId where it was unset — addRemoteRepoFromPath repos derive the host from connectionId.
       if (matchesHost) {
         repo.executionHostId = newHostId
       }
@@ -6344,9 +5994,7 @@ export class Store {
         metaChanged = true
       }
     }
-    // Why: the old id also survives in session pty ids, the startup reconnect
-    // list, sleeping-agent records, host setups, host-scope UI, and pty leases;
-    // any un-migrated carrier later throws `SSH target not found` (STA-1468).
+    // Why: any carrier still holding the old id later throws `SSH target not found` (STA-1468); migrate them all.
     let carrierChanged = migrateWorkspaceSessionSshTargetId(
       this.state.workspaceSession,
       oldTargetId,
@@ -6357,10 +6005,7 @@ export class Store {
         carrierChanged = true
       }
     }
-    // Why: partitions are read by host id, so one stored under the removed id
-    // would be orphaned. No writer keys partitions by ssh host today, but the
-    // schema tolerates it — re-key rather than strand it. If the new key
-    // already has a partition, that one is live; drop the dead old one.
+    // Why: partitions are read by host id; re-key from the removed id to the new one (keep new if it already exists).
     const partitions = this.state.workspaceSessionsByHostId
     const oldPartition = partitions?.[oldHostId]
     if (partitions && oldPartition) {
@@ -6388,8 +6033,7 @@ export class Store {
         (entry) =>
           entry !== setup && entry.projectId === setup.projectId && entry.hostId === newHostId
       )
-      // Why: a setup already exists for the re-added host — the old row is a
-      // stale ghost that would violate the (projectId, hostId) uniqueness.
+      // Why: drop the old ghost row that would violate (projectId, hostId) uniqueness with the re-added host's setup.
       if (duplicate) {
         setupsChanged = true
         continue
@@ -6402,9 +6046,7 @@ export class Store {
     if (setupsChanged) {
       this.state.projectHostSetups = keptSetups
     }
-    // Why: repo-row and host-setup rewrites can affect host-setup compatibility,
-    // but meta-only rewrites cannot — keep that sync under this gate. Persist
-    // whenever anything changed, so partial re-points aren't lost on quit.
+    // Why: repo-row and host-setup rewrites affect host-setup compatibility; meta-only rewrites don't, so gate the sync here.
     if (repoIds.size > 0 || setupsChanged) {
       this.syncProjectHostSetupCompatibilityState()
     }
@@ -6430,8 +6072,7 @@ export class Store {
     if (normalizedLease.leafId !== undefined && !isTerminalLeafId(normalizedLease.leafId)) {
       delete normalizedLease.leafId
     }
-    // Why: app-facing SSH PTY ids are globally scoped; durable relay leases
-    // stay target-local so reconnect can call relay pty.attach with raw ids.
+    // Why: store target-local pty ids in leases so reconnect can call relay pty.attach with raw ids (app ids are global).
     normalizedLease.ptyId = this.getRelayPtyIdForSshLeaseStorage(
       normalizedLease.targetId,
       normalizedLease.ptyId
@@ -6628,9 +6269,7 @@ export class Store {
     this.writeGithubCacheSnapshotSync()
   }
 
-  // Why: called after a project move rewrote this store's data file directly.
-  // From that point until relaunch, the in-memory state is stale and any
-  // write (debounced, sync, or shutdown flush) would undo the transfer.
+  // Why: a project move rewrote the data file directly; in-memory state is now stale and any write would undo the transfer.
   freezeWrites(): void {
     this.writesFrozen = true
     if (this.writeTimer) {
@@ -6639,8 +6278,7 @@ export class Store {
     }
   }
 
-  // Why best-effort: the sidecar is a refetchable cache — a failed write only
-  // costs a cold badge paint on next launch, never data.
+  // Why best-effort: the sidecar is a refetchable cache; a failed write only costs a cold badge paint next launch, never data.
   private writeGithubCacheSnapshotSync(): void {
     if (!this.githubCacheDirty) {
       return
diff --git a/src/main/providers/local-pty-provider.ts b/src/main/providers/local-pty-provider.ts
index 4cc456bd799..b1907a2bdfb 100644
--- a/src/main/providers/local-pty-provider.ts
+++ b/src/main/providers/local-pty-provider.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: shell-ready startup command integration adds
-~70 lines of scanner/promise wiring to spawn(). Splitting the method would scatter
-tightly coupled PTY lifecycle logic (scan → ready → write → exit cleanup) across
-files without a cleaner ownership seam. */
+/* eslint-disable max-lines -- Why: splitting spawn() would scatter tightly coupled PTY lifecycle logic (scan → ready → write → exit) with no cleaner ownership seam. */
 import { basename, delimiter } from 'node:path'
 import { win32 as pathWin32 } from 'node:path'
 import { resolveWindowsShellLaunchArgs } from './windows-shell-args'
@@ -79,13 +76,9 @@ const PANE_IDENTITY_ENV_KEYS = [
 
 let ptyCounter = 0
 const ptyProcesses = new Map<string, pty.IPty>()
-// Why: only agent sessions get descendant tree-kill on shutdown. Agent CLIs
-// spawn tool children in detached process groups the PTY's SIGHUP can never
-// reach; plain user terminals keep classic semantics where deliberately
-// detached (nohup-style) children survive the pane.
+// Why: only agent sessions get descendant tree-kill (tool children run in detached groups SIGHUP can't reach); plain terminals skip it so nohup-detached children survive.
 const ptyAgentSessionIds = new Set<string>()
-// Why: descendant capture is async. Reattach and duplicate shutdown must wait
-// for the original owner instead of returning a PTY that is about to die.
+// Why: descendant capture is async, so reattach/duplicate shutdown must wait for the original owner, not return a dying PTY.
 type PtyShutdownOperation = {
   promise: Promise<void>
   immediate: boolean
@@ -99,16 +92,13 @@ type PendingLocalPtySpawn = {
 const pendingLocalPtySpawns = new Map<string, Set<PendingLocalPtySpawn>>()
 const ptyShellName = new Map<string, string>()
 const ptyAgentForegroundContextPaths = new Map<string, string[]>()
-// Why: remembers the last positively-recognized agent foreground per PTY so a
-// degraded/timed-out scan does not report the shell and look like an exit.
+// Why: remember the last recognized agent foreground so a degraded scan doesn't report the shell and look like an exit.
 const ptyLastRecognizedForeground = new Map<string, string>()
 const ptyTerminalHandle = new Map<string, string>()
 const ptyInitialCwd = new Map<string, string>()
-// Why: reattach requests carry current settings, not the live process's launch
-// context. Keep the first creator's WSL/native identity for the PTY incarnation.
+// Why: reattach carries current settings, not the live process's launch context; keep the first creator's WSL/native identity.
 const ptyWslDistroById = new Map<string, string | null>()
-// Why: node-pty callbacks must be disposed before environment teardown, but
-// onExit separately owns physical process-exit proof during termination.
+// Why: node-pty callbacks dispose before env teardown, but onExit separately owns physical-exit proof during termination.
 const ptyDisposables = new Map<string, { dispose: () => void }[]>()
 const ptyExitDisposables = new Map<string, { dispose: () => void }>()
 const ptyCleanupCallbacks = new Map<string, () => void>()
@@ -216,8 +206,7 @@ function runPtyCleanup(id: string): void {
 function getWslContextFromWorktreeId(
   worktreeId: string | undefined
 ): { distro: string; treatPosixCwdAsWsl: true } | undefined {
-  // Why: strip any synthetic `::workspace:<uuid>` folder-workspace suffix so WSL
-  // detection parses the real path, not a nonexistent identifier.
+  // Why: strip any synthetic `::workspace:<uuid>` suffix so WSL detection parses the real path, not a nonexistent identifier.
   const worktreePath = worktreeId
     ? splitWorktreeIdForFilesystem(worktreeId)?.worktreePath
     : undefined
@@ -302,8 +291,7 @@ function armLocalPtyForceKill(
     } catch (error) {
       ptyTerminationMode.set(id, 'graceful')
       console.error('[pty] failed to force-kill PTY after graceful deadline', { id, error })
-      // Why: a transient native rejection must not consume the only SIGKILL
-      // owner while the logical shutdown continues waiting for physical exit.
+      // Why: a transient native rejection must not consume the only SIGKILL owner while shutdown still awaits physical exit.
       if (attemptsRemaining > 1) {
         armLocalPtyForceKill(id, proc, {
           delayMs: LOCAL_PTY_FORCE_KILL_RETRY_MS,
@@ -337,8 +325,7 @@ async function prepareLocalPtySpawn(id: string): Promise<void> {
   pending.add(pendingSpawn)
   pendingLocalPtySpawns.set(id, pending)
   try {
-    // Why: shutdown must be able to cancel a stable session id while the
-    // asynchronous macOS capability probe runs and before node-pty exists.
+    // Why: shutdown must be able to cancel a stable session id during the async macOS capability probe, before node-pty exists.
     await prepareMacosTccLoginShell()
     if (pendingSpawn.canceled) {
       throw new Error(`PTY spawn canceled: ${id}`)
@@ -399,16 +386,12 @@ function resolveForegroundFallbackProcess(
   if (process.platform !== 'win32' || normalizeForegroundProcessName(processName)) {
     return processName || null
   }
-  // Why: Windows node-pty can expose only the terminal name (`xterm-256color`).
-  // The spawned shell is the best fallback for agent foreground enrichment.
+  // Why: Windows node-pty may expose only the terminal name (`xterm-256color`); the spawned shell is the best foreground fallback.
   return shellName ?? processName ?? null
 }
 
-/** Basename of the spawned shell path, parsed for the *target* platform rather
- *  than the host's native separator. Why: on Windows the shell path uses `\`,
- *  but the POSIX `basename` (used when orchestrating from a non-Windows host or
- *  CI) would not split it and would store the whole `C:\...\powershell.exe`
- *  path as the shell name — breaking the foreground/child-process comparison. */
+/** Basename of the spawned shell path, parsed for the *target* platform.
+ *  Why: POSIX `basename` won't split a Windows `\` path (non-Windows host/CI), so it'd break the foreground comparison. */
 function getSpawnedShellName(shellPath: string): string {
   return process.platform === 'win32' ? pathWin32.basename(shellPath) : basename(shellPath)
 }
@@ -417,15 +400,7 @@ function getSpawnedShellName(shellPath: string): string {
  * Disposes the native PTY handle while avoiding recycled-pid signals on POSIX.
  */
 function destroyPtyProcess(proc: pty.IPty, options: { alreadyKilled?: boolean } = {}): void {
-  // Why: node-pty's UnixTerminal.destroy() closes the master socket, which
-  // releases the ptmx fd to the OS — without this call the fd leaks until GC
-  // (see docs/fix-pty-fd-leak.md). destroy() also registers a close listener
-  // that fires `this.kill('SIGHUP')` AFTER the socket closes. On POSIX, by
-  // the time that listener runs the child may have exited and its pid been
-  // recycled to an unrelated user process — SIGHUP would land on a Chrome tab,
-  // editor, etc. Neutralize proc.kill on this instance before calling
-  // destroy() to defuse the hazard. On Windows, destroy() is itself kill();
-  // skip it only after we have already killed the ConPTY.
+  // Why: neutralize proc.kill before destroy(), whose close-listener SIGHUPs a possibly-recycled POSIX pid; destroy() frees the ptmx fd (docs/fix-pty-fd-leak.md); on Windows destroy() is itself kill().
   if (process.platform === 'win32' && options.alreadyKilled) {
     return
   }
@@ -446,8 +421,7 @@ function requestPtyTermination(id: string, proc: pty.IPty): void {
   runPtyCleanup(id)
   disposePtyListeners(id)
   const previousMode = ptyTerminationMode.get(id)
-  // Why: destructive cleanup neutralizes proc.kill below, so an outstanding
-  // graceful request must be escalated before its deadline can be disabled.
+  // Why: cleanup neutralizes proc.kill below, so escalate an outstanding graceful request before its deadline is disabled.
   if (previousMode !== 'force') {
     clearLocalPtyForceKillTimer(id)
     ptyTerminationMode.set(id, 'force')
@@ -467,16 +441,12 @@ function requestPtyTermination(id: string, proc: pty.IPty): void {
       return
     }
   }
-  // Why: shutdown and orphan cleanup can race; node-pty's onExit listener and
-  // tracker must remain installed until the OS proves the child was reaped.
+  // Why: shutdown and orphan cleanup can race; keep onExit + tracker installed until the OS proves the child was reaped.
   destroyPtyProcess(proc, { alreadyKilled: true })
 }
 
 export type LocalPtyProviderOptions = {
-  /** Why: `ctx.command` carries the renderer-chosen launch command (e.g. `pi`,
-   *  `omp`, `claude`). Pi vs OMP must drive overlay source-dir selection in
-   *  `buildPtyHostEnv` — a cross-agent disk-presence fallback silently
-   *  shadows the other agent's user extensions when both are installed. */
+  /** Why: `ctx.command` (pi/omp/claude) must drive overlay source-dir selection — a disk-presence fallback shadows the other agent's extensions. */
   buildSpawnEnv?: (
     id: string,
     baseEnv: Record<string, string>,
@@ -488,13 +458,9 @@ export type LocalPtyProviderOptions = {
       wslDistro?: string | null
     }
   ) => Record<string, string>
-  /** Whether worktree-scoped shell history is enabled. When true (or absent)
-   *  and a worktreeId is provided, HISTFILE is scoped per-worktree. */
+  /** Whether worktree-scoped shell history is enabled; when true (or absent) with a worktreeId, HISTFILE is scoped per-worktree. */
   isHistoryEnabled?: () => boolean
-  /** Why: COMSPEC is always cmd.exe on a stock Windows machine, so reading it
-   *  directly would ignore the user's shell preference. This callback lets the
-   *  IPC layer inject the persisted setting without coupling the provider to the
-   *  settings store. Returns undefined when no preference is set. */
+  /** Why: COMSPEC is always cmd.exe, so this callback injects the user's persisted shell preference. Undefined when none set. */
   getWindowsShell?: () => string | undefined
   getWindowsPowerShellImplementation?: () => 'auto' | 'powershell.exe' | 'pwsh.exe' | undefined
   pwshAvailable?: () => boolean
@@ -524,8 +490,7 @@ export class LocalPtyProvider implements IPtyProvider {
   /**
    * Spawns or reattaches a local PTY session for the renderer process.
    *
-   * Windows shell launches can pre-deliver short startup commands in argv; this
-   * method preserves that state so the stdin fallback only runs when needed.
+   * Windows launches can pre-deliver startup commands in argv, so the stdin fallback only runs when needed.
    */
   async spawn(args: PtySpawnOptions): Promise<PtySpawnResult> {
     const reattachId = normalizeLocalCallerSessionId(args.sessionId)
@@ -558,9 +523,7 @@ export class LocalPtyProvider implements IPtyProvider {
 
     const defaultCwd = getDefaultCwd()
     const cwd = args.cwd || defaultCwd
-    // Why: gate on the effective cwd (post default-cwd fallback), not the raw
-    // args.cwd — an omitted cwd resolves to a safe default and must not be
-    // rejected as if it were a root-like path.
+    // Why: gate on the effective cwd, not raw args.cwd — an omitted cwd becomes a safe default and must not be rejected as root-like.
     if (args.command && startupAgentRecognition) {
       assertSafeAgentStartupCwd(cwd, args.command)
     }
@@ -589,9 +552,7 @@ export class LocalPtyProvider implements IPtyProvider {
       effectiveCwd = resolved.effectiveCwd
       validationCwd = resolved.validationCwd
     } else if (process.platform === 'win32') {
-      // Why: shellOverride lets a single tab open in a different shell than the
-      // persisted default (e.g. "New WSL terminal" from the "+" submenu) without
-      // changing the user's setting. It takes priority over the setting.
+      // Why: shellOverride opens one tab in a non-default shell without changing the user's setting; it wins over the setting.
       const requestedShellFamily =
         args.shellOverride ||
         this.opts.getWindowsShell?.() ||
@@ -600,11 +561,7 @@ export class LocalPtyProvider implements IPtyProvider {
       const shellFamily = worktreeWslContext ? 'wsl.exe' : requestedShellFamily
       const normalizedShellFamily = pathWin32.basename(shellFamily).toLowerCase()
       const resolvedGitBashPath = resolveWindowsGitBashShellPath(shellFamily)
-      // Why: shell selection can arrive either as a canonical setting value
-      // ('powershell.exe') or as a concrete PowerShell executable path from a
-      // one-off override. Normalize both forms back to the PowerShell family so
-      // the shared resolver can still fall back to inbox powershell.exe when
-      // pwsh.exe was requested but is unavailable.
+      // Why: normalize setting-value and path forms to the PowerShell family so the resolver can fall back to inbox powershell.exe.
       const powerShellImplementation = this.opts.getWindowsPowerShellImplementation?.()
       const resolvedShellFamily: WindowsPowerShellShellFamily =
         normalizedShellFamily === 'powershell.exe' || normalizedShellFamily === 'pwsh.exe'
@@ -631,12 +588,7 @@ export class LocalPtyProvider implements IPtyProvider {
             }) ?? shellFamily)
           : shellFamily
       }
-      // Why: when the selected shell is a PowerShell family, resolve it to a
-      // real absolute executable and build a PowerShell -> cmd.exe fallback
-      // chain. Handing ConPTY a bare `pwsh.exe` lets Windows resolve it to the
-      // Store App Execution Alias stub, whose spawn fails with error code 5.
-      // The shared launch-args helper inside keeps both this path and the
-      // daemon path producing identical args (chcp 65001 / $PROFILE / wsl cwd).
+      // Why: bare `pwsh.exe` resolves to the Store App Execution Alias stub whose spawn fails (code 5); use an absolute exe + cmd.exe fallback.
       windowsFallbackAttempts = buildWindowsPowerShellSpawnAttempts({
         shellPath,
         cwd,
@@ -679,22 +631,12 @@ export class LocalPtyProvider implements IPtyProvider {
       TERM: 'xterm-256color',
       COLORTERM: 'truecolor',
       TERM_PROGRAM: 'Orca',
-      // Why: TUIs feature-gate on TERM_PROGRAM_VERSION (Neovim's termcap
-      // autodetection, bat/delta paging hints). Sourced from ORCA_APP_VERSION
-      // which main/index.ts seeds from app.getVersion() at startup; the
-      // fallback keeps tests and non-Electron runs working.
+      // Why: TUIs feature-gate on TERM_PROGRAM_VERSION; the fallback keeps tests and non-Electron runs working.
       TERM_PROGRAM_VERSION: process.env.ORCA_APP_VERSION ?? '0.0.0-dev',
-      // Why: opt tools (Claude Code, ls --hyperlink, etc.) into emitting OSC 8
-      // hyperlinks. The `supports-hyperlinks` npm package gates on a hard-coded
-      // TERM_PROGRAM allowlist (iTerm.app / WezTerm / vscode) and returns false
-      // for TERM_PROGRAM=Orca, so callers drop OSC 8 output entirely and emit
-      // bare text instead. xterm.js in Orca parses OSC 8 and the pane's
-      // linkHandler routes clicks, so forcing the advertisement is safe and
-      // restores clickable refs like `owner/repo#123` / `PR#123`.
+      // Why: supports-hyperlinks rejects TERM_PROGRAM=Orca, so tools drop OSC 8 links; force it since xterm.js parses them.
       FORCE_HYPERLINK: '1'
     } as Record<string, string>
-    // Why: Orca can be launched from an Orca terminal while developing. Pane
-    // identity belongs to the child PTY, not the parent shell that spawned app.
+    // Why: Orca can be launched from an Orca terminal; pane identity belongs to the child PTY, not the parent shell.
     removeUnspecifiedPaneIdentityEnv(spawnEnv, args.env)
     removeAppImageRuntimeEnv(spawnEnv)
     removeInheritedNoColor(spawnEnv)
@@ -707,16 +649,11 @@ export class LocalPtyProvider implements IPtyProvider {
 
     spawnEnv.LANG ??= 'en_US.UTF-8'
 
-    // Why: On Windows, LANG alone does not control the console code page.
-    // Programs like Python and Node.js check their own encoding env vars
-    // independently. PYTHONUTF8=1 makes Python use UTF-8 for stdio regardless
-    // of the Windows console code page, preventing garbled CJK output from
-    // Python scripts run inside the terminal.
+    // Why: on Windows LANG doesn't set the console code page; PYTHONUTF8=1 forces Python UTF-8 stdio to avoid garbled CJK.
     if (process.platform === 'win32') {
       spawnEnv.PYTHONUTF8 ??= '1'
       if (isWindowsGitBashShellPath(shellPath)) {
-        // Why: Git for Windows login startup files otherwise cd to $HOME,
-        // ignoring node-pty's cwd for repo-scoped terminals.
+        // Why: Git for Windows login files otherwise cd to $HOME, ignoring node-pty's cwd for repo-scoped terminals.
         spawnEnv.CHERE_INVOKING ??= '1'
       }
     }
@@ -733,9 +670,7 @@ export class LocalPtyProvider implements IPtyProvider {
           wslDistro: launchWslDistro
         })
       : spawnEnv
-    // Why: app-level env hooks can reintroduce vars that special launch modes
-    // explicitly scrubbed. Apply deletions last so shims like Claude Agent
-    // Teams keep their PATH and terminal-detection contract.
+    // Why: app-level env hooks can re-add scrubbed vars; delete last so shims like Claude Agent Teams keep their PATH.
     for (const key of args.envToDelete ?? []) {
       delete finalEnv[key]
     }
@@ -766,27 +701,22 @@ export class LocalPtyProvider implements IPtyProvider {
             }
           }
         } else if (isHostCodexHomeForWsl(finalEnv.CODEX_HOME)) {
-          // Why: Orca's selected Codex runtime home is host-local. WSL Codex
-          // must use its Linux-side ~/.codex instead of a Windows path.
+          // Why: Orca's Codex home is host-local; WSL Codex must use its Linux-side ~/.codex, not a Windows path.
           delete finalEnv.CODEX_HOME
           delete finalEnv.ORCA_CODEX_HOME
         } else if (finalEnv.CODEX_HOME) {
           addWslEnvKeys(finalEnv, ['CODEX_HOME', 'ORCA_CODEX_HOME'])
         }
         if (finalEnv.CLAUDE_CONFIG_DIR) {
-          // Why: managed WSL Claude accounts pass a Linux CLAUDE_CONFIG_DIR
-          // through Windows wsl.exe; non-default env vars need WSLENV import.
+          // Why: managed WSL Claude passes a Linux CLAUDE_CONFIG_DIR through wsl.exe; non-default vars need WSLENV import.
           addWslEnvKeys(finalEnv, ['CLAUDE_CONFIG_DIR'])
         }
         if (finalEnv[ORCA_HERMES_STARTUP_QUERY_ENV] !== undefined) {
-          // Why: the startup wrapper expands this only inside WSL; wsl.exe
-          // otherwise drops custom Windows environment variables.
+          // Why: wsl.exe drops custom Windows env vars; the startup wrapper needs this imported inside WSL.
           addWslEnvKeys(finalEnv, [ORCA_HERMES_STARTUP_QUERY_ENV])
         }
       } else if (codexHomeWslInfo || isWslCodexHomeForHost(finalEnv.CODEX_HOME)) {
-        // Why: WSL-managed Codex homes are Linux paths. Windows Codex cannot use
-        // them. ORCA_CODEX_HOME must go too because shell-ready scripts restore
-        // CODEX_HOME from it after user profiles run.
+        // Why: WSL Codex homes are Linux paths Windows can't use; also drop ORCA_CODEX_HOME (shell-ready restores CODEX_HOME from it).
         delete finalEnv.CODEX_HOME
         delete finalEnv.ORCA_CODEX_HOME
       }
@@ -800,8 +730,7 @@ export class LocalPtyProvider implements IPtyProvider {
       addWslEnvKeys(finalEnv, [POWERLEVEL10K_WIZARD_DISABLE_ENV])
     }
     if (!wslInfo && process.platform !== 'win32') {
-      // Why: OpenCode/Codex path restoration and OMP's typed-command status
-      // wrapper need shell-ready code after user startup files run.
+      // Why: OpenCode/Codex PATH restoration and OMP's status wrapper need shell-ready code after user startup files run.
       const needsNoMarkerWrapper =
         finalEnv.ORCA_ATTRIBUTION_SHIM_DIR ||
         finalEnv.ORCA_OPENCODE_CONFIG_DIR ||
@@ -816,8 +745,7 @@ export class LocalPtyProvider implements IPtyProvider {
           command: args.command,
           startupCommandDelivery: args.startupCommandDelivery
         })
-        // Why: payload-bearing Codex startup text can be dropped by rc-file noise;
-        // plain Codex stays markerless to preserve the startup-speed path.
+        // Why: payload-bearing Codex startup can be lost to rc-file noise; plain Codex stays markerless for startup speed.
         getFallbackShellReadyConfig = (shell) =>
           shouldWaitForShellReady
             ? getShellReadyLaunchConfig(shell)
@@ -842,13 +770,10 @@ export class LocalPtyProvider implements IPtyProvider {
     }
     promoteAgentTeamsShimPath(finalEnv, args.env?.PATH)
 
-    // ── Worktree-scoped shell history (§7–§10 of terminal-history-scope-design) ──
-    // Why: without this, all worktree terminals share a single global HISTFILE
-    // so ArrowUp in worktree B surfaces commands from worktree A.
+    // Why: worktree-scoped HISTFILE — without it worktrees share one global history (terminal-history-scope-design §7–§10).
     const worktreeId = args.worktreeId
     const historyEnabled = worktreeId && (this.opts.isHistoryEnabled?.() ?? true)
-    // Resolve the effective shell kind for history injection. For WSL, the
-    // outer executable is wsl.exe but the inner login shell is bash.
+    // Effective shell for history injection: WSL's outer exe is wsl.exe but the inner login shell is bash.
     const isWslTerminal =
       Boolean(wslInfo || worktreeWslContext || preferredWslContext) ||
       pathWin32.basename(shellPath).toLowerCase() === 'wsl.exe'
@@ -872,17 +797,14 @@ export class LocalPtyProvider implements IPtyProvider {
       termName: finalEnv.TERM,
       ptySpawn: pty.spawn,
       getShellReadyConfig: getFallbackShellReadyConfig,
-      // Why: if zsh failed and bash took over, HISTFILE still points to
-      // zsh_history. Update it *before* spawn so the child inherits the
-      // correct filename (see design doc §8).
+      // Why: on zsh→bash fallback HISTFILE still points to zsh_history; update before spawn so the child inherits it (design doc §8).
       onBeforeFallbackSpawn: historyResult?.histFile
         ? (env, fallbackShell) => updateHistFileForFallback(env, fallbackShell)
         : undefined,
       windowsFallbackAttempts
     })
     shellPath = spawnResult.shellPath
-    // Why: a Windows fallback (e.g. cmd.exe) embeds its own startup command in
-    // argv, so honor the winning shell's delivery flag to avoid a double write.
+    // Why: a Windows fallback embeds its startup command in argv; honor the winning shell's delivery flag to avoid a double write.
     if (spawnResult.startupCommandDeliveredInShellArgs !== undefined) {
       startupCommandDeliveredInShellArgs = spawnResult.startupCommandDeliveredInShellArgs
     }
@@ -904,9 +826,7 @@ export class LocalPtyProvider implements IPtyProvider {
     if (spawnedWslDistro !== undefined) {
       ptyWslDistroById.set(id, spawnedWslDistro)
     }
-    // Why both signals: launchAgent is the caller's explicit intent and
-    // survives command rewriting (e.g. auth env prefixes); recognition covers
-    // callers that pass a bare agent command line without the flag.
+    // Why both: launchAgent is explicit intent that survives command rewrites; recognition catches bare agent command lines.
     if (args.launchAgent || startupAgentRecognition) {
       ptyAgentSessionIds.add(id)
     }
@@ -1025,15 +945,7 @@ export class LocalPtyProvider implements IPtyProvider {
     const onExitDisposable = proc.onExit(({ exitCode }) => {
       const wasTerminationRequested = ptyTerminationMode.has(id)
       ptyPhysicalExits.get(id)?.markExited()
-      // Why: neutralize proc.kill the instant the child is reaped, before any
-      // other work in this callback. node-pty's UnixTerminal installs a
-      // `_socket.once('close', () => this.kill('SIGHUP'))` handler at destroy
-      // time, but the master socket can also emit 'close' on natural exit
-      // between this onExit callback starting and destroyPtyProcess() running
-      // below. If 'close' wins, SIGHUP is dispatched to proc.pid — which on
-      // POSIX has already been reaped and may have been recycled to an
-      // unrelated process. Synchronous neutralization here closes that window.
-      // Windows is exempt: WindowsTerminal.destroy is implemented via kill().
+      // Why: neutralize proc.kill before destroy — node-pty SIGHUPs on socket 'close', which can race here and signal a reaped/recycled pid.
       if (process.platform !== 'win32') {
         ;(proc as unknown as { kill: (sig?: string) => void }).kill = () => {}
       }
@@ -1045,9 +957,7 @@ export class LocalPtyProvider implements IPtyProvider {
       clearPtyState(id)
       startupIngress.drainAndClose()
       startupIngressByPty.delete(id)
-      // Why: release the master ptmx fd on the natural-exit path — without
-      // this, a shell that exits cleanly (the common case) never releases its
-      // fd until the next GC. See docs/fix-pty-fd-leak.md.
+      // Why: release the master ptmx fd on natural exit, else a clean exit leaks the fd until GC. See docs/fix-pty-fd-leak.md.
       destroyPtyProcess(proc, { alreadyKilled: wasTerminationRequested })
       this.opts.onExit?.(id, exitCode)
       for (const cb of exitListeners) {
@@ -1060,9 +970,7 @@ export class LocalPtyProvider implements IPtyProvider {
     ptyDisposables.set(id, disposables)
 
     if (args.command && !startupCommandDeliveredInShellArgs) {
-      // Why: only Orca-wrapped POSIX bash/zsh have bracketed-paste mode armed
-      // (bash via `bind`, zsh on by default), so multiline startup prompts can
-      // be pasted literally there; other shells keep the raw submit path.
+      // Why: only POSIX bash/zsh have bracketed-paste armed so multiline startup prompts paste literally; others use raw submit.
       const spawnedShellName = getSpawnedShellName(shellPath).toLowerCase()
       const bracketedPasteSafe =
         process.platform !== 'win32' && (spawnedShellName === 'bash' || spawnedShellName === 'zsh')
@@ -1077,9 +985,7 @@ export class LocalPtyProvider implements IPtyProvider {
       )
     }
 
-    // Why: publish the OS pid so ipc/pty can register the PTY with the memory
-    // collector without reaching back into the provider. `proc.pid` may be
-    // briefly 0/undefined if node-pty hasn't observed the forked child yet.
+    // Why: publish the OS pid for the memory collector; proc.pid can be briefly 0/undefined before node-pty sees the child.
     const rawPid = proc.pid
     const pid = typeof rawPid === 'number' && Number.isFinite(rawPid) && rawPid > 0 ? rawPid : null
     return {
@@ -1101,10 +1007,7 @@ export class LocalPtyProvider implements IPtyProvider {
     ptyProcesses.get(id)?.resize(cols, rows)
   }
 
-  // Why: node-pty pause() stops reading the pty master fd, so the kernel
-  // buffer fills and a flooding child blocks on write — true producer
-  // backpressure. Best-effort: a PTY torn down mid-call must never throw
-  // into the flow-control path.
+  // Why: node-pty pause() stops reading the master fd, so a flooding child blocks on write — true producer backpressure.
   pauseProducer(id: string): void {
     try {
       ptyProcesses.get(id)?.pause()
@@ -1121,11 +1024,7 @@ export class LocalPtyProvider implements IPtyProvider {
     }
   }
 
-  // Why: node-pty caches the last winsize it applied on the IPty handle, so its
-  // cols/rows are the authoritative applied size (node-pty clamps invalid dims
-  // and a resize on a dead handle is a no-op, neither of which the requested
-  // size in ptySizes would reflect). The renderer's resume drift-check compares
-  // against this to re-assert a resize the PTY never actually took.
+  // Why: proc.cols/rows are node-pty's authoritative applied size (post-clamp/no-op), used by the renderer drift-check.
   async getAppliedSize(id: string): Promise<{ cols: number; rows: number } | null> {
     const proc = ptyProcesses.get(id)
     if (!proc || proc.cols <= 0 || proc.rows <= 0) {
@@ -1174,19 +1073,16 @@ export class LocalPtyProvider implements IPtyProvider {
     operation: PtyShutdownOperation
   ): Promise<void> {
     const physicalExit = ptyPhysicalExits.get(id)
-    // Why: the snapshot must precede any signal — once the shell dies,
-    // surviving descendants reparent to pid 1 and a ppid walk can't find them.
+    // Why: snapshot before signaling — once the shell dies, descendants reparent to pid 1 and a ppid walk can't find them.
     const descendants = ptyAgentSessionIds.has(id)
       ? await captureDescendantSnapshot(proc.pid)
       : null
-    // Why: a natural exit can race the snapshot. Never signal descendants or
-    // a root PID after this exact PTY has lost ownership.
+    // Why: a natural exit can race the snapshot — never signal descendants or the root PID after this PTY loses ownership.
     if (ptyProcesses.get(id) === proc) {
       if (descendants) {
         terminateDescendantSnapshot(descendants)
       }
-      // Cancel startup delivery now, but preserve the exit listener and all
-      // ownership maps until node-pty reports the physical process exit.
+      // Cancel startup delivery now, but keep the exit listener and ownership maps until node-pty reports physical exit.
       runPtyCleanup(id)
       operation.rootSignalled = true
       this.requestTrackedPtyShutdown(id, proc, operation.immediate)
@@ -1196,8 +1092,7 @@ export class LocalPtyProvider implements IPtyProvider {
 
   private requestTrackedPtyShutdown(id: string, proc: pty.IPty, immediate: boolean): void {
     const previousMode = ptyTerminationMode.get(id)
-    // Why: ConPTY has no graceful signal; its first bare node-pty kill closes
-    // the pseudoconsole and must be treated as the final force request.
+    // Why: ConPTY has no graceful signal — its first bare kill closes the pseudoconsole, so treat it as a final force request.
     const requestedMode = immediate || process.platform === 'win32' ? 'force' : 'graceful'
     if (!previousMode || (requestedMode === 'force' && previousMode !== 'force')) {
       ptyTerminationMode.set(id, requestedMode)
@@ -1233,30 +1128,19 @@ export class LocalPtyProvider implements IPtyProvider {
 
   async getCwd(id: string): Promise<string> {
     const proc = ptyProcesses.get(id)
-    // Why: return '' (not throw) on unknown id — the renderer treats empty
-    // as "no result, try the next fallback layer". Throwing would surface a
-    // noisy rejection for a non-exceptional case (PTY just exited, pane
-    // still has its old id).
+    // Why: '' not throw on unknown id — renderer reads empty as "try next fallback"; throwing is noisy for a normal case.
     if (!proc) {
       return ''
     }
-    // Why: resolveProcessCwd returns '' when it can't resolve — let that
-    // empty surface so the renderer's fallback chain decides what to do.
-    // Handing back a fabricated initialCwd here would lie to the renderer
-    // and short-circuit that chain.
+    // Why: let resolveProcessCwd's '' surface for the renderer fallback chain; a fabricated cwd would short-circuit it.
     return resolveProcessCwd(proc.pid)
   }
   async getInitialCwd(_id: string): Promise<string> {
     return ''
   }
   async clearBuffer(id: string): Promise<void> {
-    // Why: xterm.js clear() only resets the renderer. ConPTY keeps its own
-    // screen buffer, so without this its stale cursor row makes the next
-    // prompt repaint land below a blank gap. No-op on POSIX.
-    //
-    // Unlike the daemon session, no PSReadLine form-feed nudge here: it is
-    // only safe at an empty prompt, and without a headless emulator this
-    // provider cannot tell whether input is pending.
+    // Why: ConPTY keeps its own screen buffer, so xterm clear() alone leaves a stale-cursor gap on the next prompt; POSIX no-op.
+    // No PSReadLine form-feed nudge here (unlike the daemon): safe only at an empty prompt, which this provider can't detect.
     try {
       startupIngressByPty.get(id)?.snapshotBarrier()
       ptyProcesses.get(id)?.clear()
@@ -1300,8 +1184,7 @@ export class LocalPtyProvider implements IPtyProvider {
     )
     const cachedAgent = ptyLastRecognizedForeground.get(id) ?? null
     let consoleMembershipUnavailable = false
-    // Why: exact console membership can preserve a live cached agent without
-    // trusting the whole-table scan that becomes incomplete under Windows load.
+    // Why: console membership preserves a live cached agent without the whole-table scan (incomplete under Windows load).
     if (
       process.platform === 'win32' &&
       canConfirmAgentFromConsolePresence(cachedAgent, fallbackProcess)
@@ -1327,21 +1210,16 @@ export class LocalPtyProvider implements IPtyProvider {
           contextPaths: ptyAgentForegroundContextPaths.get(id)
         }
       )
-      // Why: the scan can outlive PTY teardown or id reuse; stale results must
-      // not resurrect cache state for a process that no longer owns this id.
+      // Why: the scan can outlive PTY teardown/id reuse; stale results must not resurrect cache for a foreign id.
       if (ptyProcesses.get(id) !== proc) {
         return null
       }
-      // Why: a degraded/timed-out scan must not report the shell as the
-      // foreground — the completion coordinator reads that as an exit and fires
-      // a false "agent done" while the agent is still working. Prefer the last
-      // recognized agent across a transient failure (e.g. a Windows CIM timeout).
+      // Why: a degraded scan reporting shell-as-foreground fires a false "agent done"; keep last recognized agent instead.
       const lastRecognizedAgent = ptyLastRecognizedForeground.get(id) ?? null
       const resolvedAgent = resolution.processName
         ? recognizeAgentProcessFromCommandLine(resolution.processName)
         : null
-      // Why: an incomplete global snapshot plus an unavailable console probe is
-      // not exit proof; only verified shell-only membership may clear the cache.
+      // Why: incomplete snapshot + unavailable console probe isn't exit proof; only shell-only membership may clear the cache.
       const stable = resolveStableForegroundProcess(
         consoleMembershipUnavailable && resolvedAgent === null
           ? { ...resolution, available: false }
@@ -1358,8 +1236,7 @@ export class LocalPtyProvider implements IPtyProvider {
       if (ptyProcesses.get(id) !== proc) {
         return null
       }
-      // Why: an inspection error is itself a degraded read; fall back to the
-      // last recognized agent rather than null (which also reads as an exit).
+      // Why: an inspection error is a degraded read; fall back to last recognized agent (null reads as an exit).
       return ptyLastRecognizedForeground.get(id) ?? null
     }
   }
@@ -1384,8 +1261,7 @@ export class LocalPtyProvider implements IPtyProvider {
             : {})
         }
       )
-      // Why: a fresh scan can outlive this PTY id; never publish identity from
-      // an exited process or a replacement session that reused the same id.
+      // Why: a fresh scan can outlive this PTY id; never publish identity from an exited or same-id-reusing session.
       if (ptyProcesses.get(id) !== proc) {
         return null
       }
@@ -1490,11 +1366,9 @@ export class LocalPtyProvider implements IPtyProvider {
           /* Process may already be dead. */
         }
       }
-      // Why: app quit cannot retain NAPI callbacks into FreeEnvironment; the
-      // process exit itself is the final physical handle boundary here.
+      // Why: app quit can't retain NAPI callbacks into FreeEnvironment; process exit is the final handle boundary here.
       destroyPtyProcess(proc, { alreadyKilled: true })
-      // Why: app quit replaces node-pty's onExit callback as the final owner;
-      // overlapping shutdown waiters must join that same terminal boundary.
+      // Why: app quit replaces node-pty's onExit as final owner; overlapping shutdown waiters must join this boundary.
       ptyPhysicalExits.get(id)?.markExited()
       clearPtyState(id)
     }
diff --git a/src/main/providers/local-pty-shell-ready.test.ts b/src/main/providers/local-pty-shell-ready.test.ts
index 4f42e866a9b..88a7debd9c3 100644
--- a/src/main/providers/local-pty-shell-ready.test.ts
+++ b/src/main/providers/local-pty-shell-ready.test.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: shell-ready wrapper coverage keeps zsh,
-   bash, marker scanning, and env restoration cases in one suite so the
-   generated wrapper contract is reviewed as a unit. */
+/* eslint-disable max-lines -- Why: keeps the whole generated-wrapper contract (zsh, bash, marker scanning, env restore) in one suite. */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { spawnSync } from 'node:child_process'
 import { tmpdir } from 'node:os'
@@ -14,11 +12,7 @@ import {
   writeStartupCommandWhenShellReady
 } from './local-pty-shell-ready'
 
-// Why: the wrapper root is resolved from ORCA_USER_DATA_PATH (main
-// canonicalizes it at startup; the daemon fork sets it explicitly). This
-// module must not import electron because it is bundled into the plain-node
-// daemon-entry fork, so tests point the root through the env var rather than
-// mocking electron's app.
+// Why: can't import electron (bundled into the plain-node daemon-entry fork), so tests set the wrapper root via ORCA_USER_DATA_PATH instead of mocking app.
 function setTestUserDataPath(path: string): void {
   process.env.ORCA_USER_DATA_PATH = path
 }
@@ -170,11 +164,7 @@ describe('writeStartupCommandWhenShellReady', () => {
     expect(proc._writes).toEqual(['codex\n'])
   })
 
-  // Why: regression for the multiline agent-prompt bug. A startup command with
-  // embedded newlines must be wrapped in bracketed paste (ESC[200~ … ESC[201~)
-  // followed by a single submit byte, so bash readline / zsh zle insert the
-  // whole prompt literally instead of reading each LF as Enter and mangling it
-  // into PS2 continuation.
+  // Why: multiline startup commands must be bracketed-paste wrapped (ESC[200~ … ESC[201~) so shells insert them literally instead of treating each LF as Enter.
   it('wraps a multiline startup command in bracketed paste when the shell supports it', async () => {
     Object.defineProperty(process, 'platform', { value: 'darwin' })
     const proc = createMockProc()
@@ -213,8 +203,7 @@ describe('writeStartupCommandWhenShellReady', () => {
     const proc = createMockProc()
     const ready = Promise.resolve()
     const command = 'echo one\necho two'
-    // Default options: bracketedPasteSafe is false, so the raw path is kept to
-    // avoid echoing the ESC[200~ markers on shells without bracketed paste.
+    // Why: bracketedPasteSafe defaults false, so keep the raw path to avoid echoing ESC[200~ on shells without bracketed paste.
     writeStartupCommandWhenShellReady(ready, proc, command, () => {})
 
     await ready
@@ -284,9 +273,7 @@ describe('scanForShellReady', () => {
 })
 
 describe('shell-ready wrapper root resolution', () => {
-  // Why: regression guard — the daemon-entry fork runs as plain Node and cannot
-  // import electron, so the wrapper root must resolve from ORCA_USER_DATA_PATH
-  // (set by main at startup and by the daemon fork) rather than app.getPath.
+  // Why: daemon-entry fork is plain Node (no electron), so the wrapper root resolves from ORCA_USER_DATA_PATH, not app.getPath.
   it('resolves the wrapper root from ORCA_USER_DATA_PATH', async () => {
     const root = mkdtempSync(join(tmpdir(), 'orca-userdata-env-'))
     try {
@@ -377,9 +364,7 @@ describePosix('local PTY shell-ready launch config', () => {
   })
 
   it('falls back to HOME for ORCA_ORIG_ZDOTDIR when inherited ZDOTDIR points at a wrapper dir', async () => {
-    // Why: mirrors the daemon path — guards the same zsh recursion loop for
-    // PTYs spawned by the renderer/local provider when Orca is launched from
-    // inside an Orca terminal (e.g. `pn dev`).
+    // Why: mirrors the daemon path — guards the same zsh recursion loop for renderer/local PTYs spawned inside an Orca terminal.
     const previousZdotdir = process.env.ZDOTDIR
     const previousHome = process.env.HOME
     process.env.ZDOTDIR = '/some/other/orca/shell-ready/zsh'
@@ -493,12 +478,9 @@ describePosix('local PTY shell-ready launch config', () => {
     expect(zlogin).toContain('zle -N zle-line-init __orca_prompt_mark')
     expect(zlogin).toContain('__orca_prev_line_init_fn="${widgets[zle-line-init]#user:}"')
     expect(zlogin).toContain('printf "\\033]777;orca-shell-ready\\007"')
-    // Why: add-zle-hook-widget aborts its hook chain when an earlier hook
-    // exits non-zero (e.g. oh-my-zsh vi-mode's raw zle-line-init), so the
-    // marker must not be registered through it.
+    // Why: add-zle-hook-widget aborts its chain on a non-zero earlier hook (e.g. oh-my-zsh vi-mode); don't register the marker through it.
     expect(zlogin).not.toContain('add-zle-hook-widget line-init')
-    // Why: re-source guard — skip re-capturing when we are already the bound
-    // widget so the prior widget chain survives a second source.
+    // Why: re-source guard — skip re-capturing when already the bound widget so the prior chain survives a second source.
     expect(zlogin).toContain('== "user:__orca_prompt_mark"')
   })
 
@@ -542,10 +524,7 @@ describePosix('local PTY shell-ready launch config', () => {
     expect(bashRc).toContain(ompWrapperLine)
   })
 
-  // Why: regression guard for issue #2422. Without OSC 133 C/D markers in the
-  // bash rc, Linux/bash sessions kept the worktree spinner "working" for up to
-  // 30 min after the agent CLI exited, because the renderer's command
-  // lifecycle never observed a 'D' marker to drop the stale agent row.
+  // Why: issue #2422 — without OSC 133 C/D markers, bash sessions kept the worktree spinner "working" ~30min after the agent exited.
   it('emits OSC 133 C/D markers in the bash wrapper so agent exit cleanup fires', async () => {
     const { getBashShellReadyRcfileContent, getZshShellReadyRcfileContent } =
       await importFreshLocalPtyShellReady()
@@ -553,8 +532,7 @@ describePosix('local PTY shell-ready launch config', () => {
     const bashRc = getBashShellReadyRcfileContent()
     const zshRc = getZshShellReadyRcfileContent()
 
-    // The exact escape sequences the renderer's terminal-command-lifecycle
-    // parses (133;D for command-finished, 133;C for command-start).
+    // The exact escape sequences terminal-command-lifecycle parses (133;D = finished, 133;C = start).
     expect(bashRc).toContain('printf "\\033]133;D;%s\\007"')
     expect(bashRc).toContain('printf "\\033]133;C\\007"')
     expect(bashRc).toContain(
@@ -563,8 +541,7 @@ describePosix('local PTY shell-ready launch config', () => {
     expect(bashRc.indexOf("trap '__orca_osc133_preexec' DEBUG")).toBeGreaterThan(
       bashRc.indexOf('if [[ "${ORCA_SHELL_READY_MARKER:-0}" == "1" ]]; then')
     )
-    // Sanity: zsh wrapper still emits the same markers — both branches must
-    // stay in sync.
+    // Sanity: zsh wrapper emits the same markers — both branches must stay in sync.
     expect(zshRc).toContain('printf "\\033]133;D;%s\\007"')
     expect(zshRc).toContain('printf "\\033]133;C\\007"')
   })
@@ -690,9 +667,7 @@ describePosix('local PTY shell-ready launch config', () => {
   })
 
   it('sources user .zshenv at wrapper top level before repinning ZDOTDIR', async () => {
-    // Why: PR #1737 sourced .zshenv inside a wrapper function, which broke
-    // common patterns like "typeset -U path". The fix must keep .zshenv at
-    // zsh top level while still capturing the ZDOTDIR it resolved.
+    // Why: PR #1737 sourced .zshenv in a wrapper function, breaking "typeset -U path"; keep it at top level.
     const { getShellReadyLaunchConfig } = await importFreshLocalPtyShellReady()
 
     getShellReadyLaunchConfig('/bin/zsh')
@@ -710,8 +685,7 @@ describePosix('local PTY shell-ready launch config', () => {
   })
 
   it('preserves spawn-env ORCA_ORIG_ZDOTDIR as fallback when discovery yields nothing', async () => {
-    // Why: if user .zshenv returns early or doesn't set ZDOTDIR, the wrapper
-    // should fall back to the spawn-env ORCA_ORIG_ZDOTDIR (if present), then HOME.
+    // Why: if user .zshenv returns early or doesn't set ZDOTDIR, fall back to spawn-env ORCA_ORIG_ZDOTDIR, then HOME.
     const { getShellReadyLaunchConfig } = await importFreshLocalPtyShellReady()
 
     getShellReadyLaunchConfig('/bin/zsh')
@@ -726,29 +700,22 @@ describePosix('local PTY shell-ready launch config', () => {
   })
 
   it('restores wrapper ZDOTDIR from the runtime sourced path, not the baked literal', async () => {
-    // Why: issue #8003 — WSL sources Windows-generated wrappers via /mnt/c,
-    // so the generation-time path baked into .zshenv does not exist there.
+    // Why: issue #8003 — WSL sources Windows-generated wrappers via /mnt/c, so the baked generation-time path is absent.
     const { getShellReadyLaunchConfig } = await importFreshLocalPtyShellReady()
 
     getShellReadyLaunchConfig('/bin/zsh')
 
     const zshenv = readFileSync(join(userDataPath, 'shell-ready', 'zsh', '.zshenv'), 'utf8')
 
-    // Why: derive the wrapper dir from %x (zsh's internal script name), not the
-    // env-imported $ZDOTDIR — zsh corrupts environment values whose UTF-8 bytes
-    // fall in its 0x84-0x9D token range (non-ASCII Windows usernames), which
-    // would fail the self-check and fall back to the unusable baked literal.
+    // Why: derive wrapper dir from %x, not env $ZDOTDIR — zsh corrupts non-ASCII usernames in its 0x84-0x9D token range.
     expect(zshenv).toContain('_orca_wrapper_zdotdir_self="${${(%):-%x}:h}"')
-    // Keep $ZDOTDIR only as a fallback when %x expansion yields nothing. The
-    // final restore below re-validates with -f before trusting the value, so no
-    // stat is needed here.
+    // Keep $ZDOTDIR only as a fallback when %x yields nothing; the final restore re-validates with -f, so no stat here.
     expect(zshenv).toContain(
       'if [[ -z "${_orca_wrapper_zdotdir_self:-}" ]]; then\n' +
         '  _orca_wrapper_zdotdir_self="${ZDOTDIR:-}"\n' +
         'fi'
     )
-    // The runtime path is only trusted when it still holds a wrapper .zshenv;
-    // otherwise the generation-time literal remains as the fallback.
+    // Trust the runtime path only when it still holds a wrapper .zshenv; else fall back to the generation-time literal.
     expect(zshenv).toContain(
       'if [[ -n "${_orca_wrapper_zdotdir_self:-}" && -f "${_orca_wrapper_zdotdir_self:-}/.zshenv" ]]; then\n' +
         '  export ZDOTDIR="${_orca_wrapper_zdotdir_self:-}"\n' +
@@ -763,9 +730,7 @@ describePosix('local PTY shell-ready launch config', () => {
   })
 })
 
-// Why: end-to-end validation that wrapper ZDOTDIR discovery preserves top-level
-// zsh semantics. These tests spawn real zsh subprocesses, so they're gated on
-// zsh availability and skipped on platforms where zsh is not found.
+// End-to-end validation that wrapper ZDOTDIR discovery preserves top-level zsh semantics (spawns real zsh; gated on availability).
 describePosix('live zsh subprocess tests', () => {
   const hasZsh = (() => {
     const result = spawnSync('which', ['zsh'], { encoding: 'utf8' })
@@ -790,9 +755,7 @@ describePosix('live zsh subprocess tests', () => {
     })
 
     it('preserves typeset -U path scoping when user .zshrc uses it', async () => {
-      // Why: this was the breakage pattern in PR #1737. The function-wrapper
-      // approach made "typeset -U path" function-scoped. User rcfiles must
-      // still be sourced at the wrapper's top level, preserving scoping.
+      // Why: PR #1737's function-wrapper made "typeset -U path" function-scoped; user rcfiles must source at top level.
 
       // Create XDG-style config: .zshenv sets ZDOTDIR, .zshrc modifies PATH
       const xdgZshDir = join(testHome, '.config', 'zsh')
@@ -813,11 +776,7 @@ path=(/custom/bin $path)
       const { getShellReadyLaunchConfig } = await importFreshLocalPtyShellReady()
       const config = getShellReadyLaunchConfig('/bin/zsh')
 
-      // Spawn interactive zsh with the wrapper and verify:
-      // 1. Wrapper discovered XDG ZDOTDIR from .zshenv
-      // 2. User's .zshrc was sourced from discovered ZDOTDIR
-      // 3. typeset -U path modification persisted (proving top-level scoping)
-      // Build clean env: use wrapper ZDOTDIR but let wrapper discover ORCA_ORIG_ZDOTDIR at runtime
+      // Verify the wrapper discovered XDG ZDOTDIR, sourced user .zshrc, and kept typeset -U path (proves top-level scoping).
       const cleanEnv: Record<string, string | undefined> = {
         ...process.env,
         HOME: testHome,
@@ -825,8 +784,7 @@ path=(/custom/bin $path)
       }
       delete cleanEnv.ZDOTDIR
       delete cleanEnv.ORCA_ORIG_ZDOTDIR
-      // Why: attribution shims are intentionally restored after user rcfiles;
-      // this test isolates zsh top-level path scoping, not attribution ordering.
+      // Why: this test isolates zsh top-level path scoping, not attribution shim ordering.
       delete cleanEnv.ORCA_ATTRIBUTION_SHIM_DIR
       cleanEnv.ZDOTDIR = config.env.ZDOTDIR // Point to Orca wrapper dir
 
@@ -850,11 +808,7 @@ path=(/custom/bin $path)
     })
 
     it('loads user .zshrc when wrappers are sourced from a different runtime path (WSL simulation)', async () => {
-      // Why: issue #8003 — on Windows the wrappers are generated under the
-      // native userData path but WSL sources them via /mnt/c, where the baked
-      // generation-time path does not exist. Renaming the userData dir after
-      // generation reproduces that split: runtime ZDOTDIR resolves, the baked
-      // literal does not.
+      // Why: issue #8003 — WSL sources Windows-generated wrappers via /mnt/c where the baked path is absent; renaming userData reproduces that split.
       writeFileSync(join(testHome, '.zshrc'), 'export USER_ZSHRC_LOADED=yes\n')
 
       const { getShellReadyLaunchConfig } = await importFreshLocalPtyShellReady()
@@ -874,10 +828,7 @@ path=(/custom/bin $path)
         delete cleanEnv.USER_ZSHRC_LOADED
         cleanEnv.ZDOTDIR = join(movedUserData, 'shell-ready', 'zsh')
 
-        // Production WSL launches a login shell (`exec zsh -l`); also cover the
-        // non-login flow used by local panes so both restore paths stay pinned.
-        // Login must still load user .zshrc (via wrapper .zshrc after .zprofile)
-        // and leave final ZDOTDIR at the user home after .zlogin restore.
+        // Cover both the WSL login shell (`exec zsh -l`) and the non-login local-pane flow so both restore paths stay pinned.
         for (const args of [['-i'], ['-l', '-i']] as const) {
           const result = spawnSync(
             'zsh',
@@ -895,8 +846,7 @@ path=(/custom/bin $path)
           expect(result.status, `zsh ${args.join(' ')} failed: ${result.stderr}`).toBe(0)
           expect(result.stdout).toContain('USER_ZSHRC_LOADED=yes')
           expect(result.stdout).toContain(`FINAL_ZDOTDIR=${testHome}`)
-          // Why: `as const` makes .includes('-l') reject the union of tuple
-          // element types; check the login flag by position instead.
+          // Why: `as const` makes .includes('-l') reject the tuple union type; check by position instead.
           expect(result.stdout).toContain(args[0] === '-l' ? 'IS_LOGIN=yes' : 'IS_LOGIN=no')
         }
       } finally {
@@ -905,19 +855,13 @@ path=(/custom/bin $path)
     })
 
     it('loads user .zshrc when the wrapper dir contains a non-ASCII (token-range) path', async () => {
-      // Why: issue #8003 second trigger — a non-ASCII Windows username (e.g. a
-      // Korean login) puts UTF-8 bytes in zsh's 0x84-0x9D token range into the
-      // wrapper path. zsh corrupts the env-imported $ZDOTDIR while processing
-      // startup files, so deriving the wrapper dir from $ZDOTDIR fails the
-      // self-check and falls back to the unusable baked literal, leaving the
-      // user's .zshrc unloaded. Deriving from %x sidesteps the corruption.
+      // Why: issue #8003 — non-ASCII usernames put UTF-8 bytes in zsh's 0x84-0x9D token range, corrupting env-imported $ZDOTDIR; derive from %x instead.
       writeFileSync(join(testHome, '.zshrc'), 'export USER_ZSHRC_LOADED=yes\n')
 
       const { getShellReadyLaunchConfig } = await importFreshLocalPtyShellReady()
       getShellReadyLaunchConfig('/bin/zsh')
 
-      // Move the generated wrappers under a non-ASCII runtime root so the baked
-      // literal is unusable and the runtime $ZDOTDIR gets corrupted on import.
+      // Move wrappers under a non-ASCII root so the baked literal is unusable and runtime $ZDOTDIR corrupts on import.
       const nonAsciiUserData = join(dirname(userDataPath), '홍길동-wsl-view')
       renameSync(userDataPath, nonAsciiUserData)
       try {
@@ -951,8 +895,7 @@ path=(/custom/bin $path)
     })
 
     it('preserves top-level .zshenv path and function side effects', async () => {
-      // Why: .zshenv is the normal place for always-on zsh env/path setup.
-      // Dropping those side effects regresses non-Orca zsh startup semantics.
+      // Why: .zshenv is the normal place for always-on env/path setup; dropping side effects regresses zsh startup.
       const xdgZshDir = join(testHome, '.config', 'zsh')
       mkdirSync(xdgZshDir, { recursive: true })
       writeFileSync(
@@ -997,8 +940,7 @@ export ZDOTDIR="$HOME/.config/zsh"
     })
 
     it('sources user startup files with their own ZDOTDIR in scope', async () => {
-      // Why: plugin managers such as Antidote resolve files from $ZDOTDIR
-      // while .zprofile/.zshrc/.zlogin are sourced.
+      // Why: plugin managers such as Antidote resolve files from $ZDOTDIR while startup files are sourced.
       const xdgZshDir = join(testHome, '.config', 'zsh')
       const zdotdirLog = join(testHome, 'zdotdir.log')
       mkdirSync(xdgZshDir, { recursive: true })
@@ -1047,8 +989,7 @@ export ZDOTDIR="$HOME/.config/zsh"
     })
 
     it('survives early return in user .zshenv without crashing', async () => {
-      // Why: common pattern to skip non-interactive sourcing. A direct source
-      // at zsh top level must keep the wrapper running, matching normal zsh.
+      // Why: early return is a common non-interactive-skip pattern; top-level sourcing must keep the wrapper running.
       writeFileSync(
         join(testHome, '.zshenv'),
         `[[ -o interactive ]] || return 0
@@ -1081,8 +1022,7 @@ export ZDOTDIR="$HOME/.config/zsh"
     })
 
     it('falls back to HOME when user .zshenv does not set ZDOTDIR', async () => {
-      // Why: vanilla zsh users don't set ZDOTDIR. The fallback chain should
-      // land on HOME after preserving the rest of .zshenv behavior.
+      // Why: vanilla zsh users don't set ZDOTDIR, so the fallback chain must land on HOME.
       writeFileSync(
         join(testHome, '.zshenv'),
         `# Vanilla zsh config, no ZDOTDIR
@@ -1333,8 +1273,7 @@ export MY_VAR=foo
     })
 
     it('does not source /.zshenv when HOME is empty', async () => {
-      // Create /.zshenv to verify it's NOT sourced
-      // (can't actually create in test but we verify the wrapper logic)
+      // Can't create /.zshenv in the test, so verify the wrapper logic guards against it.
       const { getShellReadyLaunchConfig } = await importFreshLocalPtyShellReady()
       getShellReadyLaunchConfig('/bin/zsh')
 
@@ -1848,9 +1787,7 @@ export MY_VAR=foo
     })
 
     it('handles unset HOME gracefully', async () => {
-      // When HOME is unset at spawn, zsh initializes it from /etc/passwd before
-      // running the wrapper, so the wrapper can discover ZDOTDIR normally.
-      // This verifies the wrapper doesn't crash when HOME is initially unset.
+      // Why: zsh initializes HOME from /etc/passwd when unset at spawn, so the wrapper can still discover ZDOTDIR.
       const { getShellReadyLaunchConfig } = await importFreshLocalPtyShellReady()
       const config = getShellReadyLaunchConfig('/bin/zsh')
 
diff --git a/src/main/providers/local-pty-shell-ready.ts b/src/main/providers/local-pty-shell-ready.ts
index e7b5c618f4d..7fc84d85ca0 100644
--- a/src/main/providers/local-pty-shell-ready.ts
+++ b/src/main/providers/local-pty-shell-ready.ts
@@ -1,14 +1,9 @@
-/* eslint-disable max-lines -- Why: this module owns both shell wrapper file
-   generation and the matching startup-command readiness scanner; splitting
-   them would make the wrapper/marker contract harder to audit. */
+/* eslint-disable max-lines -- Why: owns both wrapper-file generation and the matching readiness scanner; splitting would fragment the wrapper/marker contract. */
 /**
  * Shell-ready startup command support for local PTYs.
  *
- * Why: when Orca needs to inject a startup command (e.g. issue command runner),
- * it must wait until the shell has fully initialized before writing. This module
- * provides shell wrapper rcfiles that emit an OSC 777 marker after startup,
- * and a data scanner that detects that marker so the command can be written at
- * the right time.
+ * Why: startup commands must wait until the shell has fully initialized. Provides shell wrapper
+ * rcfiles that emit an OSC 777 marker after startup, plus a scanner that detects it.
  */
 import { tmpdir } from 'node:os'
 import { basename, win32 as pathWin32 } from 'node:path'
@@ -49,10 +44,7 @@ export type ShellReadySignal = {
 // ── Shell wrapper files ─────────────────────────────────────────────
 
 function getShellReadyWrapperRoot(): string {
-  // Why: bundled into daemon-entry.js (a plain-node fork with no electron
-  // require), so this must not import electron. Main canonicalizes
-  // ORCA_USER_DATA_PATH to its own userData at startup (configureOrcaUserDataPathEnv)
-  // and the daemon fork sets it explicitly, so the env value matches this root.
+  // Why: bundled into the daemon fork (no electron), so read ORCA_USER_DATA_PATH rather than electron's userData; main and the fork both set it to the same path.
   const userDataPath = process.env.ORCA_USER_DATA_PATH ?? tmpdir()
   return `${userDataPath}/shell-ready`
 }
@@ -71,27 +63,12 @@ function shellReadyWrappersExist(root = getShellReadyWrapperRoot()): boolean {
   return getRequiredShellReadyWrapperPaths(root).every((path) => existsSync(path))
 }
 
-// Why: if our own process inherited ZDOTDIR from a parent shell that was
-// itself an Orca PTY (e.g. the user launched `pn dev` from a terminal inside
-// a running Orca), that ZDOTDIR points at an Orca shell-ready wrapper dir.
-// Propagating it as the new PTY's ORCA_ORIG_ZDOTDIR makes the wrapper's
-// `source "$ORCA_ORIG_ZDOTDIR/.zshenv"` line source itself recursively —
-// zsh gives "job table full or recursion limit exceeded" and the shell
-// never reaches a usable prompt.
-//
-// Any path component ending in `/shell-ready/zsh` is an Orca wrapper dir
-// (regardless of whether it came from this app's userData, a packaged Orca,
-// or a different dev build). Treat it as if ZDOTDIR were unset so the caller
-// falls back to HOME for the user's real config root.
+// Why: an inherited ZDOTDIR pointing at an Orca wrapper dir (`.../shell-ready/zsh`) makes the wrapper source itself recursively (zsh recursion limit); treat it as unset so the caller falls back to HOME.
 function normalizeOriginalZdotdirCandidate(value: string | undefined): string | null {
   if (!value) {
     return null
   }
-  // Why: tolerate trailing slashes — some shell startup scripts export
-  // `ZDOTDIR="$dir/"`, and without normalization the suffix check would
-  // miss the self-loop path and restore the recursion bug. Also collapses
-  // a pathological `ZDOTDIR=/` to empty so we fall back to HOME rather than
-  // sourcing `/.zshenv` (which is never the user's real config).
+  // Why: strip trailing slashes so `ZDOTDIR="$dir/"` still matches the self-loop suffix check; `/` collapses to empty → HOME fallback.
   const normalized = value.replace(/\/+$/, '')
   if (!normalized || normalized.endsWith('/shell-ready/zsh')) {
     return null
@@ -349,10 +326,7 @@ ${getZshFinalZdotdirRestoreBlock()}
       chmodSync(path, 0o644)
     }
   } catch (error) {
-    // Why: wrapper file creation can fail due to read-only filesystems, permission
-    // issues, or disk space. Rather than crashing, log the error and continue.
-    // The shell will launch without the wrapper, which means no shell-ready marker
-    // but at least the PTY is usable.
+    // Why: degrade gracefully — a failed wrapper (read-only FS, perms, disk) just means no ready marker, PTY stays usable.
     const errorMessage =
       error instanceof Error
         ? `${error.message} (${(error as NodeJS.ErrnoException).code || 'unknown'})`
@@ -445,9 +419,7 @@ export function writeStartupCommandWhenShellReady(
   proc: pty.IPty,
   startupCommand: string,
   onExit: (cleanup: () => void) => void,
-  // Why: only Orca-wrapped bash/zsh have bracketed-paste mode active, so
-  // multiline startup commands are wrapped in ESC[200~/ESC[201~ only there;
-  // other shells keep the raw submit path to avoid echoing the markers.
+  // Why: only Orca-wrapped bash/zsh have bracketed-paste active; other shells use the raw path to avoid echoing the ESC[200~ markers.
   options: { bracketedPasteSafe?: boolean } = {}
 ): void {
   let sent = false
@@ -475,22 +447,10 @@ export function writeStartupCommandWhenShellReady(
       clearTimeout(postReadyTimer)
       postReadyTimer = null
     }
-    // Why: run startup commands inside the same interactive shell Orca keeps
-    // open for the pane. Spawning `shell -c <command>; exec shell -l` would
-    // avoid the race, but it would also replace the session after the agent
-    // exits and break "stay in this terminal" workflows.
-    // Why CR on Windows: PowerShell's PSReadLine and cmd.exe submit the line
-    // on CR (`\r`) — a bare LF leaves the command typed at the prompt but
-    // unsubmitted, forcing the user to press Enter after Orca launches the
-    // agent or setup script. POSIX shells (bash/zsh) treat either CR or LF as
-    // Enter under ICRNL, so CR works there too, but this code path is reached
-    // on Windows as well as POSIX via writeStartupCommandWhenShellReady.
+    // Why: run in the same interactive shell (not `shell -c`) so the session survives after the agent exits.
+    // Why CR on Windows: PSReadLine/cmd.exe submit on `\r`, not LF; POSIX treats either as Enter under ICRNL.
     const submit = process.platform === 'win32' ? '\r' : '\n'
-    // Why: startup commands are usually long, quoted agent launches. Writing
-    // them in one PTY call after the shell-ready barrier avoids the incremental
-    // paste behavior that still dropped characters in practice. Multiline
-    // prompts are additionally wrapped in bracketed paste (see the helper) so
-    // embedded newlines are inserted literally instead of submitting early.
+    // Why: single write after the ready barrier avoids incremental-paste char drops; multiline is bracketed-paste wrapped so newlines don't submit early.
     proc.write(
       buildStartupCommandSubmission(startupCommand, {
         submit,
@@ -507,16 +467,7 @@ export function writeStartupCommandWhenShellReady(
     if (sent) {
       return
     }
-    // Why: the shell-ready marker fires from precmd/PROMPT_COMMAND,
-    // before the prompt is drawn and before zle/readline switches the PTY into
-    // raw mode. Writing the command while the kernel still has ECHO enabled
-    // causes the characters to be echoed once by the kernel and then redisplayed
-    // by the line editor after the prompt — producing a visible duplicate.
-    //
-    // Strategy: if the marker-completing scan already observed post-marker
-    // bytes, use the short settle delay directly. Otherwise, wait for the next
-    // PTY data event after the ready marker, with a conservative fallback for
-    // ambiguous marker-only or markerless cases.
+    // Why: marker fires from precmd before the line editor takes the PTY out of ECHO; writing now double-echoes the command, so settle first.
     if (signal?.postMarkerBytesObserved === true) {
       schedulePostReadyFlush()
       return
diff --git a/src/main/rate-limits/claude-fetcher.ts b/src/main/rate-limits/claude-fetcher.ts
index e1ea780dea2..e37e831d54d 100644
--- a/src/main/rate-limits/claude-fetcher.ts
+++ b/src/main/rate-limits/claude-fetcher.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: this module keeps Claude credential source
-ordering, OAuth usage fetch semantics, and PTY fallback behavior together so
-subscription usage state cannot drift across code paths. */
+/* eslint-disable max-lines -- Why: keep Claude credential ordering, OAuth usage fetch, and PTY fallback together so usage state can't drift across paths. */
 import { existsSync, lstatSync, readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
@@ -53,13 +51,7 @@ const LIVE_CLAUDE_REFRESH_DEFERRED_MESSAGE =
 
 /**
  * Bridge standard HTTP proxy env vars into Electron's session proxy config.
- *
- * Why: Electron's net.fetch uses Chromium's networking stack which respects
- * OS-level proxy settings but ignores HTTP_PROXY / HTTPS_PROXY env vars.
- * Users in regions where api.anthropic.com is only reachable via proxy (see
- * #521, #800) often set these env vars rather than configuring system proxy.
- * Without this bridge, the usage indicator silently fails and the app may hit
- * Anthropic from an unexpected IP, risking rate-limit signals on the account.
+ * Why: net.fetch ignores HTTP_PROXY/HTTPS_PROXY; users behind a proxy for api.anthropic.com set those env vars (#521, #800).
  */
 async function ensureProxyFromEnv(): Promise<void> {
   await ensureElectronProxyFromEnvironment({
@@ -94,8 +86,6 @@ type OAuthCredentialReadOptions = {
 
 type OAuthCredentialSource = 'scoped-keychain' | 'legacy-keychain' | 'credentials-file' | 'none'
 
-// Why: factored out so both the active-account Keychain reader and the
-// managed-account reader share the same JSON parsing + refreshability check.
 function parseOAuthCredentialsJson(
   raw: string,
   source: OAuthCredentialSource
@@ -113,9 +103,7 @@ function parseOAuthCredentialsJson(
         source
       }
     }
-    // Why: Claude's local expiresAt metadata is not authoritative for the
-    // /api/oauth/usage endpoint. Real Claude Code 2.1 credentials have been
-    // observed authenticating there after expiresAt, so let the server decide.
+    // Why: local expiresAt isn't authoritative for /api/oauth/usage (creds authenticate there after expiry); let the server decide.
     return {
       token,
       hasRefreshableCredentials,
@@ -145,8 +133,7 @@ function keychainUnavailableOAuthCredentialReadResult(): OAuthCredentialReadResu
 
 /**
  * Read OAuth token from macOS Keychain.
- * Why: Claude Code 2.1+ scopes OAuth Keychain services by CLAUDE_CONFIG_DIR;
- * older builds used the legacy unsuffixed service. The shared reader handles both.
+ * Why: Claude Code 2.1+ scopes Keychain services by CLAUDE_CONFIG_DIR; older builds used the legacy unsuffixed service.
  */
 async function readFromKeychain(configDir?: string): Promise<OAuthCredentialReadResult> {
   if (process.platform !== 'darwin') {
@@ -159,9 +146,7 @@ async function readFromKeychain(configDir?: string): Promise<OAuthCredentialRead
       return scopedCredentials
     }
     const legacyCredentials = await readCredentialsFromStrictKeychain(undefined, 'legacy-keychain')
-    // Why: Orca cannot refresh tokens itself, so an actual access token from
-    // either item beats refresh-only credentials. A scoped item the CLI stopped
-    // maintaining must not shadow a still-working legacy token.
+    // Why: a real access token beats refresh-only creds (Orca can't refresh), so a stale scoped item can't shadow a working legacy token.
     if (legacyCredentials.token) {
       return legacyCredentials
     }
@@ -202,8 +187,7 @@ async function readCredentialsFromStrictKeychain(
 
 /**
  * Read OAuth token from ~/.claude/.credentials.json (legacy path).
- * Why: older Claude CLI versions store credentials in this plain JSON
- * file. We keep it as a fallback for compatibility.
+ * Why: older Claude CLI versions store credentials here; kept as a fallback.
  */
 async function readFromCredentialsFile(configDir?: string): Promise<OAuthCredentialReadResult> {
   const credPath = path.join(configDir ?? path.join(homedir(), '.claude'), '.credentials.json')
@@ -217,9 +201,7 @@ async function readFromCredentialsFile(configDir?: string): Promise<OAuthCredent
 
 /**
  * Try credential sources that yield a genuine OAuth bearer token.
- * Why: we intentionally do NOT read ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY
- * here — those are API keys which return 401 on the OAuth usage endpoint.
- * API-key users are served by the PTY fallback instead.
+ * Why: skip ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY — those are API keys that 401 on the OAuth usage endpoint (PTY fallback serves them).
  */
 async function readOAuthCredentials(
   options?: OAuthCredentialReadOptions
@@ -255,8 +237,7 @@ function resolveOAuthCredentialReadOptions(
   if (!authPreparation) {
     return undefined
   }
-  // Why: Claude Code 2.1+ can scope even the default config dir's macOS
-  // Keychain item. Try scoped first, with legacy still handled as fallback.
+  // Why: Claude Code 2.1+ can scope even the default config dir's Keychain item; try scoped first, legacy as fallback.
   const readOptions: OAuthCredentialReadOptions = {
     credentialsFileConfigDir: authPreparation.configDir,
     keychainConfigDir: authPreparation.configDir
@@ -403,8 +384,7 @@ function mapWindow(
 }
 
 function mapFableWeeklyWindow(data: OAuthUsageResponse): RateLimitWindow | null {
-  // Why: model quotas moved into structured scoped limits; prefer that current
-  // contract while retaining explicit legacy weekly fields for older responses.
+  // Why: model quotas moved to structured scoped limits; prefer them but keep legacy weekly fields for older responses.
   const scoped = Array.isArray(data.limits)
     ? data.limits.find(
         (limit) =>
@@ -435,21 +415,18 @@ async function fetchViaOAuth(token: string, signal?: AbortSignal): Promise<Provi
     return abortedClaudeRateLimitResult()
   }
 
-  // Compose the caller's cancel signal with the request timeout so a timeout
-  // and an external cancel both abort the fetch.
+  // Compose caller cancel with the request timeout so either aborts the fetch.
   const requestSignal = signal
     ? AbortSignal.any([signal, AbortSignal.timeout(API_TIMEOUT_MS)])
     : AbortSignal.timeout(API_TIMEOUT_MS)
 
   try {
-    // Why: net.fetch uses Chromium's networking stack which respects OS proxy
-    // settings and certificates. Env var proxies are bridged by ensureProxyFromEnv.
+    // Why: net.fetch uses Chromium's stack for OS proxy/certs; env-var proxies are bridged by ensureProxyFromEnv.
     const res = await net.fetch(OAUTH_USAGE_URL, {
       headers: {
         Authorization: `Bearer ${token}`,
         'anthropic-beta': OAUTH_BETA_HEADER,
-        // Why: Claude's OAuth usage endpoint is the Claude Code usage API;
-        // matching the CLI user-agent keeps Orca aligned with that contract.
+        // Why: match the Claude Code CLI user-agent to stay aligned with the OAuth usage API contract.
         'User-Agent': CLAUDE_CODE_USER_AGENT
       },
       signal: requestSignal
@@ -588,9 +565,7 @@ function canSupplementOAuthUsageFromCli(input: {
   authPreparation?: ClaudeRuntimeAuthPreparation
   allowUsagePanelSupplement: boolean
 }): boolean {
-  // Why: Fable is visible in Claude's interactive /usage panel even when the
-  // OAuth usage endpoint only reports documented 5h/7d windows. This runs only
-  // after OAuth succeeds, so it must not become a broad auth-recovery fallback.
+  // Why: Fable shows in Claude's /usage panel even when the OAuth endpoint reports only 5h/7d windows; supplement only after OAuth already succeeded.
   return Boolean(
     input.allowUsagePanelSupplement &&
     !input.authPreparation?.managedRefreshDeferredByLivePty &&
@@ -677,11 +652,7 @@ function canRetryWithLegacyKeychainToken(input: {
   oauthCredentials: OAuthCredentialReadResult
   authPreparation?: ClaudeRuntimeAuthPreparation
 }): boolean {
-  // Why: the CLI only maintains the legacy keychain item for the default config
-  // dir, so a scoped item can hold a token that expired long ago and will 401
-  // on every fetch with no recovery path. Host system-default auth may retry
-  // with the legacy item; managed/WSL credentials must never be answered with
-  // the host user's legacy keychain account.
+  // Why: only host auth may fall back to the legacy keychain item when a scoped item holds a dead token that 401s forever; managed/WSL must never use the host's legacy account.
   return (
     input.classification.failureKind === 'stale-token' &&
     input.oauthCredentials.source === 'scoped-keychain' &&
@@ -1071,9 +1042,7 @@ type ManagedCredentialsLocation =
   | { kind: 'keychain'; accountId: string; managedAuthPath: string }
   | { kind: 'file'; managedAuthPath: string }
 
-// Why: resolves where an inactive account's credentials live without
-// materializing them into the shared runtime location. Using
-// ClaudeRuntimeAuthService would overwrite the active account's auth.
+// Why: resolve where inactive credentials live without materializing them — ClaudeRuntimeAuthService would overwrite the active account's auth.
 function resolveManagedCredentialsLocation(
   account: InactiveClaudeAccountInfo
 ): ManagedCredentialsLocation | null {
@@ -1087,8 +1056,7 @@ function resolveManagedCredentialsLocation(
   if (!managedAuthPath) {
     return null
   }
-  // macOS stores host managed credentials in the Keychain; everything else
-  // (and WSL, handled above) stores them as a file under the managed dir.
+  // macOS stores host managed credentials in the Keychain; other platforms use a file under the managed dir.
   if (process.platform === 'darwin') {
     return { kind: 'keychain', accountId: account.id, managedAuthPath }
   }
@@ -1201,9 +1169,7 @@ function canTrustManagedUsagePanelSupplement(
       ? windowsAgree(oauthLimits.weekly, cliLimits.weekly)
       : null
   ].filter((match): match is boolean => match !== null)
-  // Why: macOS inactive previews temporarily stage managed credentials in a
-  // scoped Keychain item. If an older Claude build ignores scoped Keychains,
-  // matching OAuth windows prevent active-account Fable data from leaking in.
+  // Why: an older Claude build may ignore the scoped Keychain, so require matching OAuth windows to keep active-account Fable data from leaking in.
   return sharedWindowMatches.length > 0 && sharedWindowMatches.every(Boolean)
 }
 
@@ -1298,11 +1264,7 @@ export async function fetchManagedAccountUsage(
     }
   }
 
-  // Why: own the refresh for inactive accounts (claude-swap's model) — when the
-  // stored token is expiring, refresh and persist the rotated token back to
-  // managed storage before fetching usage. This keeps inactive accounts'
-  // single-use refresh tokens fresh so a later switch-in never materializes a
-  // stale token. Persistence failure is non-fatal: we still try the fetch.
+  // Why: refresh+persist an expiring token now so inactive accounts' single-use refresh tokens stay fresh for a later switch-in (persist failure is non-fatal).
   let token = parseOAuthCredentialsJson(credentialsJson, 'credentials-file').token
   if (isOauthTokenExpiring(credentialsJson)) {
     const refreshed = await refreshClaudeOauthCredentials(credentialsJson)
@@ -1313,8 +1275,7 @@ export async function fetchManagedAccountUsage(
       try {
         await writeManagedCredentialsJson(location, refreshed)
       } catch {
-        // Keep going with the refreshed token in memory even if the write
-        // failed; worst case the next poll refreshes again.
+        // Keep the refreshed token in memory; next poll refreshes again if the write failed.
       }
       credentialsJson = refreshed
       token = parseOAuthCredentialsJson(refreshed, 'credentials-file').token
@@ -1332,9 +1293,7 @@ export async function fetchManagedAccountUsage(
     }
   }
 
-  // Why: PTY fallback is intentionally omitted for inactive accounts. The PTY
-  // path is used only as a supplement after OAuth succeeds, and it points
-  // directly at the managed account's isolated config so selection is unchanged.
+  // Why: no PTY fallback for inactive accounts — PTY only supplements after OAuth succeeds.
   const oauthLimits = await fetchViaOAuth(token, options.signal)
   if (options.signal?.aborted) {
     return abortedClaudeRateLimitResult()
diff --git a/src/main/rate-limits/codex-fetcher.ts b/src/main/rate-limits/codex-fetcher.ts
index f7ce2a5db08..77eef555a68 100644
--- a/src/main/rate-limits/codex-fetcher.ts
+++ b/src/main/rate-limits/codex-fetcher.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: keeping both Codex RPC and PTY fallback
-paths together in one file makes it easier to audit the protocol/parsing
-differences and ensure account-scoped env handling stays identical. */
+/* eslint-disable max-lines -- Why: keep Codex RPC and PTY fallback paths together to audit protocol/parsing differences and shared account-scoped env handling. */
 import type {
   CodexRateLimitResetOutcome,
   ProviderRateLimits,
@@ -35,8 +33,7 @@ const RPC_TIMEOUT_MS = 10_000
 const WSL_RPC_TIMEOUT_MS = 25_000
 const PTY_TIMEOUT_MS = 15_000
 const BACKEND_TIMEOUT_MS = 10_000
-// Why: redeeming a reset credit is an explicit user action, not a background
-// poll — give it more room before failing so a slow backend can still finish.
+// Why: redeeming a reset credit is an explicit user action, not a poll — allow more time for a slow backend.
 const REDEEM_BACKEND_TIMEOUT_MS = 30_000
 const MAX_DIAGNOSTIC_OUTPUT_LENGTH = 100_000
 
@@ -78,8 +75,7 @@ type RpcRateLimitsResult = {
   secondary?: RpcRateWindow
 }
 
-// Why: the Codex app-server wraps rate limit data inside a `rateLimits` key.
-// The actual response shape is `{ rateLimits: { primary, secondary, ... } }`.
+// Why: the Codex app-server wraps rate limit data as { rateLimits: { primary, secondary, ... } }.
 type RpcRateLimitsResponse = {
   rateLimits?: RpcRateLimitsResult
   rateLimitResetCredits?: {
@@ -166,14 +162,11 @@ function buildWslCodexCommand(
   const execSuffix = `${args.map(shellQuote).join(' ')}${
     options?.isolateRpcStdio ? ' <&3 >&4 3<&- 4>&-' : ''
   }`
-  // Why: npm/nvm Codex launchers use `#!/usr/bin/env node`. Resolving an
-  // absolute launcher in a login shell and later execing it from plain `sh`
-  // loses the PATH that supplies Node and also pins obsolete installations.
+  // Why: npm/nvm launchers use `#!/usr/bin/env node`; exec'ing them from plain sh loses Node's PATH and pins stale installs.
   const loginShellCommand = buildWslLoginShellCommand(
     [setupCommands, `exec codex ${execSuffix}`].join(' && ')
   )
-  // Why: keep the outer sh non-login and hide RPC pipes before the configured
-  // shell startup can read input or print banners.
+  // Why: keep the outer sh non-login and hide RPC pipes before shell startup can read input or print banners.
   const command = options?.isolateRpcStdio
     ? ['exec 3<&0', 'exec 4>&1', 'exec </dev/null', 'exec >/dev/null', loginShellCommand].join('\n')
     : loginShellCommand
@@ -308,9 +301,7 @@ function getBackendAuthRead(
   if (existing) {
     return existing
   }
-  // Why: the caller deadline must settle promptly, but Node cannot guarantee
-  // cancellation of an already-issued UNC read. Keep one raw read per auth
-  // path until the OS finishes so repeated quota refreshes cannot stack them.
+  // Why: Node can't cancel an in-flight UNC read; keep one read per auth path so repeated refreshes don't stack them.
   const read = createAuthFilesystemOperation(authPath, () =>
     readFile(authPath, 'utf8').then(
       (content) => ({ content }),
@@ -375,8 +366,7 @@ async function fetchBackendRateLimitResetCredits(
   if (signal.aborted) {
     return null
   }
-  // Why: published Codex 0.140 can read windows through app-server but strips
-  // reset-credit metadata that the backend already returns.
+  // Why: Codex 0.140's app-server strips the reset-credit metadata this backend endpoint still returns.
   const response = await fetch('https://chatgpt.com/backend-api/wham/rate-limit-reset-credits', {
     ...auth,
     signal
@@ -486,8 +476,7 @@ function mapRpcWindow(
 
   return {
     usedPercent: Math.min(100, Math.max(0, raw.usedPercent)),
-    // Why: Codex currently reports remaining minutes in `windowDurationMins`.
-    // Orca's UI needs the fixed bucket duration so labels stay "5h" / "wk".
+    // Why: windowDurationMins reports remaining minutes, but the UI needs the fixed bucket duration for "5h"/"wk" labels.
     windowMinutes: expectedWindowMinutes,
     resetsAt,
     resetDescription
@@ -499,8 +488,7 @@ function mapBackendUsageWindow(
   fallbackWindowMinutes: number
 ): RateLimitWindow | null {
   const limitWindowSeconds = raw?.limit_window_seconds
-  // Match Codex backend-client's `window_minutes_from_seconds`: the backend
-  // field is the actual bucket duration and rounds partial minutes upward.
+  // Why: match Codex backend-client's window_minutes_from_seconds — actual bucket duration, rounding partial minutes up.
   const windowMinutes =
     typeof limitWindowSeconds === 'number' &&
     Number.isFinite(limitWindowSeconds) &&
@@ -526,9 +514,7 @@ async function fetchViaBackend(
   if (!auth || signal.aborted) {
     return null
   }
-  // Why: Codex itself reads this endpoint in backend-client's
-  // `get_rate_limit_status`; using the same contract avoids launching a hidden
-  // app-server (and a WSL login shell) for every routine quota refresh.
+  // Why: reuse Codex's own get_rate_limit_status endpoint, avoiding a hidden app-server (and WSL login shell) per refresh.
   const response = await fetch('https://chatgpt.com/backend-api/wham/usage', {
     ...auth,
     signal
@@ -538,9 +524,7 @@ async function fetchViaBackend(
     return null
   }
   const payload = (await response.json()) as BackendUsageResponse
-  // `plan_type` is required by Codex's RateLimitStatusPayload. Reject a
-  // superficially successful but unrelated/malformed JSON response so the
-  // established app-server fallback still gets a chance.
+  // Why: plan_type is required by Codex's RateLimitStatusPayload; reject malformed JSON so the app-server fallback still runs.
   if (typeof payload.plan_type !== 'string') {
     return null
   }
@@ -578,26 +562,18 @@ async function fetchViaRpc(options?: FetchCodexRateLimitsOptions): Promise<Provi
     const wslCodex = options?.codexHomePath
       ? buildWslCodexCommand(options.codexHomePath, codexArgs, { isolateRpcStdio: true })
       : null
-    // Why: cold WSL process startup plus Codex app-server initialization can
-    // exceed the host RPC budget, causing a false "unavailable" on app launch.
+    // Why: cold WSL startup + app-server init can exceed the host RPC budget, causing a false "unavailable" on launch.
     const rpcTimeoutMs = wslCodex ? WSL_RPC_TIMEOUT_MS : RPC_TIMEOUT_MS
     const codexCommand = wslCodex ? 'codex' : resolveCodexCommand()
-    // Why: on Windows, resolveCodexCommand() may return a .cmd/.bat file.
-    // spawn() cannot execute batch scripts directly without shell:true, but
-    // shell:true with an args array triggers DEP0190 (args are concatenated,
-    // not escaped). Fix: detect batch scripts and route through cmd.exe /c.
+    // Why: .cmd/.bat launchers can't be spawned directly and shell:true triggers DEP0190 — route them through cmd.exe /c.
     const { spawnCmd, spawnArgs } = wslCodex
       ? { spawnCmd: wslCodex.command, spawnArgs: wslCodex.args }
       : getSpawnArgsForWindows(codexCommand, codexArgs)
     const child = spawn(spawnCmd, spawnArgs, {
       stdio: ['pipe', 'pipe', 'pipe'],
       cwd: resolveHiddenRateLimitPtyCwd(),
-      // Why: the selected Codex rate-limit account must only affect this fetch
-      // subprocess. Never mutate process.env globally or other Codex features
-      // would inherit the managed account unintentionally.
-      // Why windowsHide: this fetch runs periodically in the background;
-      // without the flag, cmd.exe /c would flash a console window for each
-      // poll on Windows.
+      // Why: scope the selected account to this subprocess only; never mutate process.env globally.
+      // Why windowsHide: without it, background cmd.exe /c polls flash a console window on Windows.
       windowsHide: true,
       env: {
         ...(wslCodex ? cloneProcessEnvWithoutCodexHome() : process.env),
@@ -663,11 +639,7 @@ async function fetchViaRpc(options?: FetchCodexRateLimitsOptions): Promise<Provi
       return id
     }
 
-    // Why: the Codex RPC server follows the JSON-RPC/LSP initialization
-    // handshake: client sends `initialize` request, waits for the response,
-    // then sends an `initialized` notification. Only after that will the
-    // server accept other methods. Skipping the notification causes "Not
-    // initialized" errors on subsequent requests.
+    // Why: JSON-RPC/LSP handshake — send `initialized` after initialize or the server rejects methods as "Not initialized".
     let rateLimitsId: number | null = null
 
     const initId = sendRpc('initialize', {
@@ -699,8 +671,7 @@ async function fetchViaRpc(options?: FetchCodexRateLimitsOptions): Promise<Provi
           }
 
           if (msg.id === initId) {
-            // Initialize succeeded — send `initialized` notification, then
-            // request rate limits.
+            // Initialize succeeded — send `initialized`, then request rate limits.
             sendNotification('initialized')
             rateLimitsId = sendRpc('account/rateLimits/read')
             continue
@@ -800,8 +771,7 @@ async function fetchViaRpc(options?: FetchCodexRateLimitsOptions): Promise<Provi
 // PTY fallback — spawn `codex`, send `/status`, parse rendered output
 // ---------------------------------------------------------------------------
 
-// Why: these patterns match the Codex CLI's /status output format.
-// "5h limit" and "Weekly limit" lines contain a percent and optional reset text.
+// Why: match the Codex CLI /status output ("5h limit"/"Weekly limit" lines with a percent and optional reset text).
 const FIVE_HOUR_RE = /5h\s+limit[:\s]*(\d+)%/i
 const WEEKLY_RE = /weekly\s+limit[:\s]*(\d+)%/i
 const RESET_TEXT_RE = /resets?\s+(?:at\s+|in\s+)?(.+)/i
@@ -851,13 +821,7 @@ async function fetchViaPty(options?: FetchCodexRateLimitsOptions): Promise<Provi
   const wslCodex = options?.codexHomePath ? buildWslCodexCommand(options.codexHomePath, []) : null
   const codexCommand = wslCodex ? 'codex' : resolveCodexCommand()
 
-  // Why: node-pty cannot spawn .cmd/.bat batch scripts directly on Windows —
-  // those need cmd.exe as an interpreter. resolveCodexCommand() may also fall
-  // back to bare 'codex' when it can't locate the binary on disk, yet cmd.exe
-  // can still find codex.cmd via PATHEXT. Always route through cmd.exe on win32.
-  // Why not getSpawnArgsForWindows: the PTY path must route through cmd.exe
-  // even for bare 'codex' (not just .cmd/.bat) to let PATHEXT resolution
-  // succeed under a minimal Electron PATH. /d matches the rest of the codebase.
+  // Why: on win32 route through cmd.exe (even bare 'codex') so PATHEXT resolves codex.cmd under a minimal Electron PATH.
   const isWin32 = process.platform === 'win32'
   const spawnFile = wslCodex ? wslCodex.command : isWin32 ? getCmdExePath() : codexCommand
   const spawnArgs = wslCodex ? wslCodex.args : isWin32 ? ['/d', '/c', codexCommand] : []
@@ -931,8 +895,7 @@ async function fetchViaPty(options?: FetchCodexRateLimitsOptions): Promise<Provi
 
     const onDataDisposable = term.onData((data) => {
       output += data
-      // Why: this background fallback only needs recent status output for
-      // parsing and diagnostics; cap noisy TUI output like the Claude fallback.
+      // Why: only recent status output is needed; cap noisy TUI output like the Claude fallback.
       if (output.length > MAX_DIAGNOSTIC_OUTPUT_LENGTH) {
         output = output.slice(-MAX_DIAGNOSTIC_OUTPUT_LENGTH)
       }
@@ -946,8 +909,7 @@ async function fetchViaPty(options?: FetchCodexRateLimitsOptions): Promise<Provi
 
       // Check if we have parseable output
       if (sentStatus && !settleTimer && (FIVE_HOUR_RE.test(output) || WEEKLY_RE.test(output))) {
-        // Why: after status text is parseable the TUI may continue streaming
-        // chunks; one settle timer is enough to let the panel finish flushing.
+        // Why: the TUI keeps streaming after status is parseable; one settle timer lets the panel finish flushing.
         settleTimer = setTimeout(() => {
           settleTimer = null
           if (resolved) {
@@ -1027,9 +989,7 @@ export async function fetchCodexRateLimits(
   if (options?.signal?.aborted) {
     return abortedCodexRateLimitResult()
   }
-  // Why: never spawn the `codex` binary unless the user has signed in. Without
-  // auth the RPC/PTY paths can only error, and spawning them shows up as an
-  // unexpected background Codex process for users who don't use Codex.
+  // Why: don't spawn `codex` unless signed in — otherwise non-Codex users see an unexpected background process that can only error.
   const authPresence = await probeCodexAuthPresence(options?.codexHomePath, {
     signal: options?.signal
   })
@@ -1060,9 +1020,7 @@ export async function fetchCodexRateLimits(
     }
   }
 
-  // Path A (WSL): use Codex's own backend usage contract. Host accounts retain
-  // app-server's token-refresh/custom-CA behavior; WSL avoids starting a login
-  // shell just to reconstruct the CLI environment for a routine poll.
+  // Path A (WSL): use Codex's backend usage contract so a routine poll skips spawning a login shell to rebuild the CLI env.
   if (options?.codexHomePath && parseWslUncPath(options.codexHomePath)) {
     try {
       const backendResult = await fetchViaBackend(options)
@@ -1077,8 +1035,7 @@ export async function fetchCodexRateLimits(
       if (options?.signal?.aborted) {
         return abortedCodexRateLimitResult()
       }
-      // Token refresh, network routing, and custom-CA behavior can differ from
-      // the host fetch stack. Preserve the CLI paths as compatibility fallbacks.
+      // Why: token refresh, network routing, and custom-CA behavior can differ from the host fetch stack; keep CLI paths as fallbacks.
     }
   }
 
@@ -1098,8 +1055,7 @@ export async function fetchCodexRateLimits(
     if (options?.allowPtyFallback === false) {
       return rpcResult
     }
-    // Why: app-server can fail independently of the interactive CLI. Keep the
-    // status-bar useful by trying the older /status PTY reader on RPC errors.
+    // Why: app-server can fail independently of the interactive CLI; fall back to the /status PTY reader on RPC errors.
   } catch {
     if (options?.signal?.aborted) {
       return abortedCodexRateLimitResult()
diff --git a/src/main/rate-limits/service.ts b/src/main/rate-limits/service.ts
index db7c9ca5218..13dfd7a62c4 100644
--- a/src/main/rate-limits/service.ts
+++ b/src/main/rate-limits/service.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: this service centralizes polling, stale-data
-handling, account-switch fetch semantics, and renderer push coordination so the
-fetch ordering rules stay in one place. */
+/* eslint-disable max-lines -- Why: centralizes polling, stale-data handling, account-switch fetch semantics, and renderer push coordination in one place */
 import type { BrowserWindow } from 'electron'
 import { randomUUID } from 'node:crypto'
 import type {
@@ -69,23 +67,16 @@ type ActiveWindowRefreshPlan =
   | { kind: 'full' }
   | { kind: 'providers'; providers: ActiveRateLimitProvider[] }
 
-// Why: Claude's subscription usage endpoint has a tight request budget. Quota
-// state is informational, so prefer keeping a recent snapshot over polling it
-// into 429s during long focused Orca sessions.
+// Why: Claude's usage endpoint has a tight budget and quota is only informational; prefer a recent snapshot over polling into 429s.
 const DEFAULT_POLL_MS = 15 * 60 * 1000 // 15 minutes
 const MIN_POLL_MS = 30 * 1000 // 30 seconds — renderer input should never create a tight loop.
 const MAX_POLL_MS = 2_147_483_647 // Max safe setInterval delay before Node clamps back to 1ms.
 const MIN_REFETCH_MS = 5 * 60 * 1000 // 5 minutes — debounce resume/manual refresh bursts
 const ACTIVE_FAILURE_REFETCH_MS = MIN_POLL_MS
-// Why: a persistent failure (bad auth, unsupported plan) retried at the 30s
-// floor hammers provider endpoints — Claude's tight-budget usage endpoint
-// starts returning 429s — without ever recovering. Back off per consecutive
-// failure, capped at the background poll cadence.
+// Why: retrying a persistent failure at the 30s floor hammers endpoints into 429s; back off per failure, capped at the poll cadence.
 const MAX_ACTIVE_FAILURE_REFETCH_MS = DEFAULT_POLL_MS
 const MAX_ACTIVE_FAILURE_STREAK = 8
-// Why: these providers have a dedicated fetch cycle, so an activation retry can
-// refresh just the failing one. Providers without one force a full fetchAll, so
-// their error retries stay on the 5-minute cadence to protect Claude's budget.
+// Why: these providers have a dedicated fetch cycle, so an activation retry refreshes just the failing one; others force a full fetchAll.
 const INDIVIDUALLY_REFRESHABLE_PROVIDERS: ReadonlySet<ActiveRateLimitProvider> = new Set([
   'claude',
   'codex',
@@ -95,8 +86,7 @@ const STALE_THRESHOLD_MS = 30 * 60 * 1000 // 30 minutes — after this, stale da
 const INACTIVE_FETCH_DEBOUNCE_MS = 60 * 1000 // 60 seconds — debounce fetch-on-open
 const DEFERRED_STARTUP_ACTIVE_REFRESH_MS = 1000
 
-// Why: inactive account arrays are derived from provider-specific caches on
-// demand in getState() and pushToRenderer().
+// Why: inactive account arrays are derived from provider caches on demand in getState()/pushToRenderer().
 type InternalRateLimitState = {
   claude: ProviderRateLimits | null
   codex: ProviderRateLimits | null
@@ -118,8 +108,7 @@ function normalizePollingInterval(ms: number): number {
 function isSystemDefaultClaudeAuth(
   authPreparation: ClaudeRuntimeAuthPreparation | undefined
 ): boolean {
-  // Why: fetch cycles classify missing Claude auth as system-default; keep the
-  // PTY fallback gate aligned so background refresh cannot trigger auth flows.
+  // Why: fetch cycles treat missing Claude auth as system-default; align the PTY gate so refresh can't trigger auth flows.
   if (!authPreparation) {
     return true
   }
@@ -146,8 +135,7 @@ export class RateLimitService {
   private pollInterval: number = DEFAULT_POLL_MS
   private timer: ReturnType<typeof setInterval> | null = null
   private deferredStartupRefreshTimer: ReturnType<typeof setTimeout> | null = null
-  // Why: after the first recovery attempt, repeated focus/show/restore events
-  // during the same outage should not create a tight provider retry loop.
+  // Why: throttle repeated focus/show/restore events so one outage doesn't create a tight provider retry loop.
   private lastActiveFailureRetryAtByProvider: Record<ActiveRateLimitProvider, number> = {
     claude: 0,
     codex: 0,
@@ -158,8 +146,7 @@ export class RateLimitService {
     grok: 0,
     antigravity: 0
   }
-  // Why: consecutive applied failures per provider drive exponential backoff of
-  // the fast activation-retry lane; reset on any successful/unavailable result.
+  // Why: consecutive failures drive exponential backoff of the fast activation-retry lane; reset on any success/unavailable result.
   private activeFailureStreakByProvider: Record<ActiveRateLimitProvider, number> = {
     claude: 0,
     codex: 0,
@@ -269,8 +256,7 @@ export class RateLimitService {
     const refreshOnResume = (): void => {
       void this.refreshIfWindowActive()
     }
-    // Why: attach() can replace windows; the previous closed listener also
-    // captures this service and must be removed with the focus listeners.
+    // Why: attach() can replace windows; remove the previous closed listener too, not only the focus listeners.
     const detachWindowListeners = (): void => {
       mainWindow.removeListener('focus', refreshOnResume)
       mainWindow.removeListener('show', refreshOnResume)
@@ -320,9 +306,7 @@ export class RateLimitService {
     this.pruneInactiveCodexState()
     return {
       ...this.state,
-      // Why: the cookie lives in the file system, not GlobalSettings. Surface
-      // its presence on the pushed state so the renderer keeps the MiniMax
-      // bar visible across reloads and between snapshot refreshes.
+      // Why: the cookie lives on the filesystem, not GlobalSettings; surface its presence so the renderer keeps the MiniMax bar across reloads.
       minimaxCookieConfigured: hasMiniMaxSessionCookie(),
       grokAuthConfigured: this.grokAuthConfigured,
       claudeTarget: this.claudeFetchTarget,
@@ -339,17 +323,13 @@ export class RateLimitService {
   }
 
   async refresh(): Promise<RateLimitState> {
-    // Why: the explicit refresh button is a user-directed recovery action.
-    // Debouncing it behind the background poll throttle makes the UI feel
-    // broken after wake/focus transitions because the click can no-op even
-    // though the user is asking for a fresh read right now.
+    // Why: this user-directed refresh must bypass the poll throttle, else the click can no-op after wake/focus and feel broken.
     await this.fetchAll({ force: true })
     return this.getState()
   }
 
   async refreshIfStale(): Promise<RateLimitState> {
-    // Why: reconnecting mobile subscribers need fresh backgrounded-desktop data,
-    // but replaying a subscription must not queue another forced provider fetch.
+    // Why: reconnecting mobile subscribers need fresh backgrounded-desktop data, but replaying a subscription must not queue another forced fetch.
     const plan = this.getActiveWindowRefreshPlan(Date.now())
     await this.runActiveWindowRefreshPlan(plan)
     return this.getState()
@@ -362,8 +342,7 @@ export class RateLimitService {
 
   invalidateMiniMaxCredentialState(): void {
     this.minimaxFetchGeneration += 1
-    // Why: saving or forgetting the browser cookie can race an in-flight usage
-    // fetch; clear the visible snapshot before any old-cookie result returns.
+    // Why: saving/forgetting the cookie can race an in-flight fetch; clear the visible snapshot before any old-cookie result returns.
     this.updateState({
       ...this.state,
       minimax: this.withFetchingStatus(null, 'minimax')
@@ -389,9 +368,7 @@ export class RateLimitService {
     this.inactiveCodexAccountsGeneration += 1
     this.pruneInactiveCodexState()
     this.lastInactiveCodexFetchAt = 0
-    // Why: switching the selected Codex account must immediately clear the old
-    // Codex quota view. Keeping stale values visible would show the previous
-    // account's limits under the newly selected identity until the next poll.
+    // Why: clear the old Codex view immediately, else the previous account's limits show under the newly selected identity until the next poll.
     this.updateState({
       ...this.state,
       codex: this.withFetchingStatus(null, 'codex')
@@ -442,8 +419,7 @@ export class RateLimitService {
     target?: ClaudeAccountSelectionTarget
   ): Promise<RateLimitState> {
     const nextTarget = normalizeClaudeAccountSelectionTarget(target)
-    // Why: snapshot the outgoing account's usage before clearing it so the
-    // inline usage bars in the switcher can show last-known data immediately.
+    // Why: snapshot the outgoing account's usage before clearing so the switcher's inline bars can show last-known data immediately.
     if (
       outgoingAccountId &&
       this.state.claude?.session &&
@@ -536,8 +512,7 @@ export class RateLimitService {
           const cached = this.inactiveClaudeCache.get(account.id) ?? null
           this.inactiveClaudeCache.set(account.id, this.applyStalePolicy(fresh, cached))
         } catch {
-          // Why: per-account try/catch prevents one Keychain rejection or
-          // network error from aborting the remaining accounts in the batch.
+          // Why: per-account try/catch keeps one Keychain/network error from aborting the remaining accounts in the batch.
           if (
             signal.aborted ||
             fetchGeneration !== this.inactiveClaudeAccountsGeneration ||
@@ -570,8 +545,7 @@ export class RateLimitService {
     if (accounts.length === 0) {
       return
     }
-    // Why: account switching can make a previewed account active while its
-    // RPC-only usage fetch is still in flight; stale results must be ignored.
+    // Why: account switching can activate a previewed account while its RPC-only fetch is still in flight; ignore stale results.
     const fetchGeneration = this.inactiveCodexAccountsGeneration
     const controller = this.beginFetchCycle()
     const signal = controller.signal
@@ -596,12 +570,8 @@ export class RateLimitService {
           continue
         }
         try {
-          // Why: fetchCodexRateLimits already accepts codexHomePath, so we can
-          // point it at the managed account's home directory directly without
-          // materializing credentials into the shared runtime location.
-          // Why: opening the account switcher should never start hidden PTYs for
-          // every inactive account. On Windows that fallback can crash inside
-          // ConPTY; RPC-only is enough for this non-critical preview surface.
+          // Why: point fetchCodexRateLimits at the managed home directly, avoiding materializing credentials into the shared runtime location.
+          // Why: no PTY fallback — the switcher preview shouldn't spawn hidden PTYs per account (can crash ConPTY on Windows); RPC-only is enough.
           const fresh = await fetchCodexRateLimits({
             codexHomePath: account.managedHomePath,
             allowPtyFallback: false,
@@ -695,11 +665,7 @@ export class RateLimitService {
   }
 
   evictInactiveCodexCache(accountId: string): void {
-    // Why: only the evicted account's state should be cleared. The per-account
-    // isCurrentInactiveCodexAccount guard in fetchInactiveCodexAccountsOnOpen
-    // already catches a removed account when its resolver entry disappears,
-    // so bumping the generation here would also invalidate sibling fetches
-    // still in flight and discard their fresh results.
+    // Why: clear only this account, not the generation — bumping it would discard sibling fetches still in flight and their fresh results.
     this.inactiveCodexCache.delete(accountId)
     this.inactiveCodexFetching.delete(accountId)
     this.pushToRenderer()
@@ -753,9 +719,7 @@ export class RateLimitService {
     if (!this.mainWindow || this.mainWindow.isDestroyed()) {
       return false
     }
-    // Why: these quota fetches only power in-app UI. When Orca is hidden,
-    // minimized, or unfocused, polling only burns CLI/API budget without any
-    // visible benefit. We refresh again as soon as the window becomes active.
+    // Why: these fetches only power in-app UI; skip polling when hidden/minimized/unfocused to save CLI/API budget (refresh on activate).
     if (!this.mainWindow.isVisible() || this.mainWindow.isMinimized()) {
       return false
     }
@@ -763,9 +727,7 @@ export class RateLimitService {
   }
 
   private getActiveProviderState(): ActiveProviderState[] {
-    // Why: key by provider so a newly added provider is compile-forced to have
-    // an active-refresh entry — a missing one silently never recovers from a
-    // startup error (antigravity was omitted once and needed a fix-up).
+    // Why: key by provider so a new provider is compile-forced an entry — a missing one silently never recovers from a startup error.
     const byProvider: Record<ActiveRateLimitProvider, ProviderRateLimits | null> = {
       claude: this.state.claude,
       codex: this.state.codex,
@@ -794,8 +756,7 @@ export class RateLimitService {
         }
         continue
       }
-      // Why: a failed startup read is not fresh data. Keep it eligible for
-      // activation recovery while throttling repeated events per provider.
+      // Why: a failed startup read is not fresh data; keep it eligible for activation recovery, throttled per provider.
       if (limits.status === 'error') {
         const lastRetryAt = this.lastActiveFailureRetryAtByProvider[provider]
         const throttleMs = INDIVIDUALLY_REFRESHABLE_PROVIDERS.has(provider)
@@ -822,10 +783,8 @@ export class RateLimitService {
       return
     }
     if (plan.kind === 'full') {
-      // Why: a full fetch retries failing providers too. Restart their retry
-      // clocks so the individual failure lane doesn't fire again right after,
-      // ahead of its backoff window. Skip when a fetch is already in flight —
-      // fetchAll would no-op and the throttle must not be consumed for free.
+      // Why: a full fetch retries failing providers too; restart their retry clocks so the individual failure lane doesn't fire ahead of backoff.
+      // Why: gated on !isFetching — the fetchAll below no-ops mid-flight, so don't consume the retry throttle for free.
       if (!this.isFetching) {
         const now = Date.now()
         for (const { provider, limits } of this.getActiveProviderState()) {
@@ -838,8 +797,7 @@ export class RateLimitService {
       return
     }
 
-    // Why: a fetch already in flight will refresh these providers; skip without
-    // consuming the per-provider retry throttle so the next activation retries.
+    // Why: an in-flight fetch will refresh these; skip without consuming the per-provider retry throttle so the next activation retries.
     if (this.isFetching) {
       return
     }
@@ -857,8 +815,7 @@ export class RateLimitService {
       return
     }
 
-    // Why: partial failures of providers with a dedicated fetch cycle should
-    // recover without re-reading healthy providers still inside their debounce.
+    // Why: recover partial failures of dedicated-fetch providers without re-reading healthy providers still inside their debounce.
     if (plan.providers.includes('claude')) {
       await this.fetchClaudeOnly()
     }
@@ -1124,9 +1081,7 @@ export class RateLimitService {
     ) {
       return Promise.resolve()
     }
-    // Why: explicit refresh callers need to await the queued follow-up cycle
-    // when a poll is already in flight, otherwise the UI stops spinning before
-    // the user-requested refresh actually runs.
+    // Why: explicit-refresh callers must await the queued follow-up cycle when a poll is in flight, else the UI stops spinning early.
     return new Promise((resolve) => {
       this.fetchIdleResolvers.push(resolve)
     })
@@ -1232,28 +1187,23 @@ export class RateLimitService {
   }
 
   private shouldAllowCodexPtyFallback(): boolean {
-    // Why: quota UI refreshes run in the background. On Windows, hidden PTY
-    // fallback can crash inside ConPTY, so prefer RPC-only degradation there.
+    // Why: hidden PTY fallback can crash inside ConPTY on Windows; prefer RPC-only degradation there for background quota refresh.
     return process.platform !== 'win32'
   }
 
   private shouldAllowClaudePtyFallback(
     authPreparation: ClaudeRuntimeAuthPreparation | undefined
   ): boolean {
-    // Why: automatic recovery uses Claude CLI as the next source, but Windows
-    // hidden PTY support remains less reliable than host/WSL shells.
+    // Why: Windows hidden PTY support is less reliable than host/WSL shells.
     if (process.platform === 'win32') {
       return false
     }
-    // Why: system-default Claude is not an Orca-managed account. Background
-    // quota refresh may read existing OAuth, but must not launch Claude and
-    // trigger auth/browser flows for users who never configured Claude in Orca.
+    // Why: system-default Claude isn't Orca-managed; refresh may read existing OAuth but must not launch Claude and trigger auth/browser flows.
     return !isSystemDefaultClaudeAuth(authPreparation)
   }
 
   private shouldAllowClaudeUsagePanelSupplement(): boolean {
-    // Why: this supplement runs only after OAuth has already returned usage
-    // data. Keep it off on Windows where hidden PTYs are still less reliable.
+    // Why: keep this supplement off on Windows where hidden PTYs are still less reliable.
     return process.platform !== 'win32'
   }
 
@@ -1268,8 +1218,7 @@ export class RateLimitService {
         error: null
       }
     } catch (error) {
-      // Why: one unreadable browser cookie must not abort every provider's
-      // quota refresh; surface it as MiniMax-only state instead.
+      // Why: one unreadable cookie must not abort every provider's refresh; surface it as MiniMax-only state instead.
       return {
         config: {
           sessionCookie: '',
@@ -1331,10 +1280,7 @@ export class RateLimitService {
         status: 'fetching'
       }
     }
-    // Why: repainting a settled chip as "fetching" on every background refetch
-    // makes the status bar flash "…" → error each retry cycle when a provider
-    // is persistently failing. Keep the settled state visible until the new
-    // result lands; only providers with no settled state show a loading chip.
+    // Why: keep a settled chip visible during background refetch so a persistently failing provider doesn't flash "…" → error each cycle.
     if (current.status === 'ok' || current.status === 'error' || current.status === 'unavailable') {
       return current
     }
@@ -1365,13 +1311,11 @@ export class RateLimitService {
     const miniMaxGroupId = miniMaxConfigResult.config.groupId
     const miniMaxModels = miniMaxConfigResult.config.models
     const geminiCliOAuthEnabled = this.geminiCliOAuthEnabledResolver?.() ?? false
-    // Why: getState() is used by renderer pushes and mobile snapshots; keep
-    // Grok's sync auth-file probe on fetch cycles instead of every state read.
+    // Why: getState() is hot (renderer pushes + mobile snapshots); keep Grok's sync auth-file probe on fetch cycles instead.
     const grokAuthReadResult = readGrokAuthSession()
     this.grokAuthConfigured = grokAuthReadResult.status === 'ok'
 
-    // Detect if configuration changed — if it did, we must discard any stale
-    // data because it belongs to a different session/workspace.
+    // Discard stale data on config change — it belongs to a different session/workspace.
     const currentConfigHash = `${cookie}|${workspaceIdOverride}`
     const opencodeConfigChanged = currentConfigHash !== this.lastOpencodeConfigHash
     if (opencodeConfigChanged) {
@@ -1388,9 +1332,7 @@ export class RateLimitService {
     }
     const miniMaxGeneration = this.minimaxFetchGeneration
 
-    // Mark all providers as fetching while keeping previous data visible.
-    // Codex account changes clear Codex separately before this method is
-    // called, so ordinary refreshes still preserve the current values.
+    // Mark all providers fetching while keeping previous data visible (Codex is cleared separately on account change).
     this.updateState({
       ...previousState,
       claude: this.withFetchingStatus(previousState.claude, 'claude'),
@@ -1488,9 +1430,7 @@ export class RateLimitService {
             status: 'error'
           } satisfies ProviderRateLimits)
 
-    // Why: Antigravity shares Google/Gemini usage credentials today; mirror the
-    // Gemini snapshot under provider 'antigravity' so status-bar UI that checks
-    // antigravity state receives a real fetch lifecycle instead of staying null.
+    // Why: Antigravity shares Gemini credentials today; mirror the Gemini snapshot so its status-bar UI gets a real lifecycle instead of null.
     const antigravity: ProviderRateLimits = {
       ...gemini,
       provider: 'antigravity'
@@ -1571,10 +1511,7 @@ export class RateLimitService {
       this.trackActiveFailureStreak('minimax', miniMax)
     }
 
-    // Why: account switches can race in-flight Codex fetches. Only apply a
-    // Codex result if both the selected-account provenance and the request
-    // generation still match, otherwise an old account could overwrite the
-    // newly selected account's quota state.
+    // Why: apply a Codex result only when provenance and generation still match, else a raced in-flight fetch overwrites the new account.
     this.updateState({
       ...this.state,
       claude: shouldApplyClaude
@@ -1789,8 +1726,7 @@ export class RateLimitService {
       }
     }
 
-    // Explicitly unavailable — user likely cleared a setting. Discard any stale
-    // data so the UI reflects that the provider is now disabled/unconfigured.
+    // Explicitly unavailable (e.g. setting cleared): discard stale data so the UI shows the provider as disabled/unconfigured.
     if (fresh.status === 'unavailable') {
       return fresh
     }
@@ -1813,11 +1749,7 @@ export class RateLimitService {
       return fresh
     }
 
-    // Why: once we have a recent successful snapshot, repeated transient
-    // failures should keep showing that same snapshot until it ages out of the
-    // stale window. Otherwise the bar flaps from "stale but useful" to empty
-    // after the second failure even though the last known quota is still fresh
-    // enough to be actionable.
+    // Why: keep showing a recent snapshot through repeated transient failures until it ages out, so the bar doesn't flap to empty.
     return {
       ...previous,
       error: fresh.error,
@@ -1844,8 +1776,7 @@ export class RateLimitService {
         isFetching: fetching.has(accountId)
       })
     }
-    // Why: include accounts that are fetching but have no cache yet so the
-    // renderer can show a loading indicator for newly added accounts.
+    // Why: include fetching-but-uncached accounts so the renderer shows a loading indicator for newly added accounts.
     for (const accountId of fetching) {
       if (!cache.has(accountId)) {
         result.push({
diff --git a/src/main/runtime/mobile-presence-lock.test.ts b/src/main/runtime/mobile-presence-lock.test.ts
index b10a268ac79..87568e3e9d7 100644
--- a/src/main/runtime/mobile-presence-lock.test.ts
+++ b/src/main/runtime/mobile-presence-lock.test.ts
@@ -1,16 +1,5 @@
 /**
- * Tests for the presence-based mobile driver lock.
- *
- * Covers (per docs/mobile-presence-lock.md):
- *   - State machine transitions (idle | desktop | mobile{clientId})
- *   - Most-recent-actor wins for active phone-fit dims
- *   - Earliest-by-subscribe-time wins for desktop-restore target
- *   - Subscribe-in-desktop-mode is a passive watch (does NOT take floor)
- *   - mobileTookFloor → re-applies phone-fit when transitioning from desktop
- *   - reclaimTerminalForDesktop → idempotent, drops banner, restores dims
- *   - Multi-mobile sequencing: A subscribes / B subscribes / B unsubscribes /
- *     A unsubscribes leaves the runtime cleanly idle without dim regressions
- *   - terminalDriverChanged notifications fire at the right transitions
+ * Tests for the presence-based mobile driver lock (see docs/mobile-presence-lock.md).
  */
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import type * as GitUsernameModule from '../git/git-username'
@@ -66,17 +55,12 @@ const store = {
     refreshLocalBaseRefOnWorktreeCreate: false,
     branchPrefix: 'none',
     branchPrefixCustom: '',
-    // Why: legacy mobile tests pre-date the fit-hold preference. Default
-    // to MIN (the new clamp floor) so the auto-restore behavior they assert
-    // continues to fire after a finite delay. Real getDefaultSettings()
-    // is null/indefinite. See docs/mobile-fit-hold.md.
+    // Why: default to a finite 5s (not the real null/indefinite) so legacy auto-restore tests still fire. See docs/mobile-fit-hold.md.
     mobileAutoRestoreFitMs: 5_000
   })
 }
 
-// Why (#7588): the held-modal repro needs indefinite hold (null) while the
-// legacy tests rely on the finite 5s default. Wrap getSettings per-test so a
-// caller can pick the hold without mutating the shared stub.
+// Why (#7588): held-modal repro needs indefinite hold (null); legacy tests need the finite 5s default. Wrap per-test without mutating the shared stub.
 function createRuntime(mobileAutoRestoreFitMs: number | null = 5_000) {
   const effectiveStore = {
     ...store,
@@ -159,8 +143,7 @@ describe('mobile presence lock — driver state machine', () => {
 
     await runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
 
-    // Driver stays idle (the desktop banner was already gone). Phone is
-    // "passively watching" at desktop dims.
+    // Driver stays idle — the phone is passively watching at desktop dims.
     expect(runtime.getDriver('pty-1')).toEqual({ kind: 'idle' })
     expect(driverEvents.find((e) => e.driver.kind === 'mobile')).toBeUndefined()
   })
@@ -173,8 +156,7 @@ describe('mobile presence lock — driver state machine', () => {
     expect(await runtime.reclaimTerminalForDesktop('pty-1')).toBe(true)
     expect(runtime.getDriver('pty-1')).toEqual({ kind: 'desktop' })
 
-    // Idempotent — second call is a no-op (no active mobile subscriber to
-    // reclaim from).
+    // Idempotent — second call is a no-op (no active mobile subscriber left to reclaim from).
     expect(await runtime.reclaimTerminalForDesktop('pty-1')).toBe(true)
     expect(runtime.getDriver('pty-1')).toEqual({ kind: 'desktop' })
   })
@@ -280,9 +262,7 @@ describe('mobile presence lock — driver state machine', () => {
 
     runtime.handleMobileUnsubscribe('pty-1', 'phone-A')
 
-    // Why: soft-leave grace keeps driver=mobile{phone-A} for ~250ms so a
-    // re-subscribe (e.g. mobile keyboard show/hide on legacy clients)
-    // doesn't cause a desktop banner flash.
+    // Why: soft-leave grace holds driver=mobile ~250ms so a keyboard show/hide re-subscribe doesn't flash the desktop banner.
     expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
 
     await vi.advanceTimersByTimeAsync(250)
@@ -297,8 +277,7 @@ describe('mobile presence lock — driver state machine', () => {
     runtime.handleMobileUnsubscribe('pty-1', 'phone-A')
     expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
 
-    // Same client re-subscribes inside the grace window — no idle should
-    // ever be observed by the renderer.
+    // Same client re-subscribes inside the grace window — renderer must never observe idle.
     await vi.advanceTimersByTimeAsync(100)
     await runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
     await vi.advanceTimersByTimeAsync(500)
@@ -412,8 +391,7 @@ describe('mobile presence lock — multi-mobile semantics', () => {
   it('terminal.send by phone-B updates lastActedAt — applyMobileDisplayMode picks B viewport', async () => {
     const { runtime, ptySizes } = createRuntime()
     await runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
-    // Advance the fake clock so phone-B's subscribe records a strictly
-    // later subscribedAt/lastActedAt — keeps tie-break deterministic.
+    // Advance so phone-B's subscribe records a strictly later timestamp — keeps tie-break deterministic.
     await vi.advanceTimersByTimeAsync(10)
     await runtime.handleMobileSubscribe('pty-1', 'phone-B', { cols: 38, rows: 18 })
     // Switch to desktop, then phone-B types — its viewport wins on re-fit.
@@ -421,8 +399,7 @@ describe('mobile presence lock — multi-mobile semantics', () => {
     await runtime.applyMobileDisplayMode('pty-1')
     expect(ptySizes.get('pty-1')).toEqual({ cols: 150, rows: 40 })
 
-    // Simulate B taking the floor by typing (advance again so lastActedAt
-    // is unambiguously the most recent).
+    // Advance so B's lastActedAt is unambiguously the most recent before it takes the floor.
     await vi.advanceTimersByTimeAsync(10)
     await runtime.mobileTookFloor('pty-1', 'phone-B')
 
@@ -464,12 +441,9 @@ describe('mobile presence lock — multi-mobile semantics', () => {
 
     expect(ptySizes.get('pty-1')).toEqual({ cols: 49, rows: 16 })
     expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
-    // Why: a viewport update may re-emit driver to refresh listener
-    // wiring, but it must never go through `idle` (no banner flash).
+    // Why: a viewport update may re-emit driver but must never pass through idle (no banner flash).
     expect(driverEvents.slice(before).every((e) => e.driver.kind === 'mobile')).toBe(true)
-    // Why: phone→phone dim ticks (keyboard show/hide) are the hottest layout
-    // path and must not wake the renderer's fit-override listeners — the
-    // emit gate opens only when layout kind or override presence changes.
+    // Why: phone→phone dim ticks (keyboard show/hide) are the hottest path — must not wake fit-override listeners (gate opens only on layout-kind/override-presence change).
     expect(fitOverrideEvents.length).toBe(fitEventsBefore)
   })
 
@@ -564,8 +538,7 @@ describe('mobile presence lock — multi-mobile semantics', () => {
     // onClientDisconnected enqueues fire-and-forget; flush microtasks + 0ms timers.
     await vi.advanceTimersByTimeAsync(0)
 
-    // PTY must restore to the original 150x40 baseline, not the last
-    // phone-fit dim. This was the stuck-dim bug.
+    // Must restore to the original 150x40 baseline, not the last phone-fit dim (the stuck-dim bug).
     expect(ptySizes.get('pty-1')).toEqual({ cols: 150, rows: 40 })
     expect(runtime.getDriver('pty-1')).toEqual({ kind: 'idle' })
   })
@@ -599,8 +572,7 @@ describe('mobile presence lock — multi-mobile semantics', () => {
     await vi.advanceTimersByTimeAsync(10)
     await runtime.handleMobileSubscribe('pty-1', 'phone-B', { cols: 38, rows: 18 })
 
-    // A leaves, B leaves — final restore must use A's earliest baseline (150x40),
-    // NOT B's (which captured 45x20 when it joined a phone-fitted PTY).
+    // Final restore must use A's earliest baseline (150x40), not B's (it captured 45x20 joining a phone-fitted PTY).
     runtime.handleMobileUnsubscribe('pty-1', 'phone-A')
     runtime.handleMobileUnsubscribe('pty-1', 'phone-B')
     await vi.advanceTimersByTimeAsync(5_000)
@@ -609,20 +581,14 @@ describe('mobile presence lock — multi-mobile semantics', () => {
   })
 })
 
-// Why (#7588): drive the runtime into the reported held-modal state — a phone
-// fit that an indefinite hold left behind, followed by a null-viewport
-// resubscribe (app update / WebView reload) that re-registers an active
-// subscriber with wasResizedToPhone=false while the override is still held.
-// This is the state where the desktop "Your phone left this at phone size"
-// modal's Restore buttons used to silently no-op.
+// Why (#7588): reproduce the held-modal state — a null-viewport resubscribe re-registers an active subscriber while the phone-fit override is still held (where Restore used to no-op).
 async function reachHeldModalWithNullViewportResubscribe(
   runtime: OrcaRuntimeService
 ): Promise<void> {
   await runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
   runtime.handleMobileUnsubscribe('pty-1', 'phone-A')
   await vi.advanceTimersByTimeAsync(300)
-  // Production RPC passes `params.viewport` straight through, so a client
-  // that hasn't measured yet arrives here as `undefined`.
+  // Production RPC passes params.viewport straight through, so an unmeasured client arrives as undefined.
   await runtime.handleMobileSubscribe('pty-1', 'phone-A', undefined)
 }
 
@@ -630,9 +596,7 @@ describe('mobile presence lock — issue #7588 held-modal restore convergence',
   beforeEach(() => vi.useFakeTimers())
   afterEach(() => vi.useRealTimers())
 
-  // Scenario 1: the reported repro end-to-end. Restore must converge and
-  // notify BOTH the renderer notifier and a runtime listener (paired), since
-  // remote/web viewers ride the listener channel.
+  // Scenario 1: reported repro end-to-end — restore must notify both channels since remote/web viewers ride the listener channel.
   it('reclaim after a null-viewport resubscribe restores dims, clears override, notifies both channels', async () => {
     const { runtime, ptySizes, fitOverrideEvents } = createRuntime(null)
     const listenerEvents: { mode: string; cols: number; rows: number }[] = []
@@ -655,10 +619,7 @@ describe('mobile presence lock — issue #7588 held-modal restore convergence',
     expect(listenerEvents.slice(listenerBefore).some((e) => e.mode === 'desktop-fit')).toBe(true)
   })
 
-  // Scenario 2: a second click after success is an idempotent no-op. The
-  // persistent null-viewport subscriber keeps reclaim in the active-subscriber
-  // branch; assert only "returns true, no new PTY resize, no new fit-override
-  // event" — a benign mobile-facing mode-change notify is acceptable.
+  // Scenario 2: second reclaim is an idempotent no-op — the persistent null-viewport subscriber keeps it in the active-subscriber branch (benign mode-change notify OK).
   it('second Restore click after success returns true with no new resize or fit-override event', async () => {
     const { runtime, resizes, fitOverrideEvents } = createRuntime(null)
     const listenerEvents: { mode: string; cols: number; rows: number }[] = []
@@ -677,9 +638,7 @@ describe('mobile presence lock — issue #7588 held-modal restore convergence',
     expect(listenerEvents.length).toBe(listenerCount)
   })
 
-  // Scenario 3: the existing driving take-back is unregressed — a phone that is
-  // actively driving (wasResizedToPhone=true) still flips to desktop, clears
-  // the override, and notifies both channels.
+  // Scenario 3: regression guard — an actively-driving phone (wasResizedToPhone=true) still converges to desktop.
   it('driving take-back still converges: driver → desktop, override cleared, both channels notified', async () => {
     const { runtime, ptySizes, fitOverrideEvents } = createRuntime()
     const listenerEvents: { mode: string; cols: number; rows: number }[] = []
@@ -699,12 +658,7 @@ describe('mobile presence lock — issue #7588 held-modal restore convergence',
     expect(listenerEvents.some((e) => e.mode === 'desktop-fit')).toBe(true)
   })
 
-  // Scenario 4: an explicit take-back on a HELD (no-subscriber) override must
-  // ALWAYS release, even when the desktop resize fails. The override is cleared
-  // optimistically with a paired desktop-fit 0×0 so the banner can't linger; the
-  // desktop renderer refits the PTY on its next settled frame. (The gesture
-  // deliberately overrides #7588's keep-lock-on-failed-resize rule, which still
-  // governs the auto-restore and phone-initiated paths.)
+  // Scenario 4: explicit held-override take-back always releases, even on failed resize — overrides #7588's keep-lock rule (which still governs the auto-restore/phone paths).
   it('held restore with a failing resize still releases and clears the override', async () => {
     const { runtime, fitOverrideEvents, setResizeSucceeds } = createRuntime(null)
     const listenerEvents: { mode: string; cols: number; rows: number }[] = []
@@ -729,10 +683,7 @@ describe('mobile presence lock — issue #7588 held-modal restore convergence',
     expect(listenerEvents.slice(listenerBefore).some((e) => e.mode === 'desktop-fit')).toBe(true)
   })
 
-  // Scenario 5: an explicit ACTIVE-SUBSCRIBER take-back with a failing resize
-  // must still release — driver → desktop, override cleared, banner dismissed,
-  // mode reset to 'auto'. This is the "take back all terminals" guarantee: a
-  // background PTY that can't converge must not strand its banner.
+  // Scenario 5: "take back all terminals" guarantee — an active-subscriber take-back with a failing resize must still release so a background PTY can't strand its banner.
   it('active-subscriber take-back with a failing resize still releases the lock', async () => {
     const { runtime, fitOverrideEvents, setResizeSucceeds } = createRuntime()
     const listenerEvents: { mode: string; cols: number; rows: number }[] = []
@@ -756,10 +707,7 @@ describe('mobile presence lock — issue #7588 held-modal restore convergence',
     expect(listenerEvents.slice(listenerBefore).some((e) => e.mode === 'desktop-fit')).toBe(true)
   })
 
-  // Scenario 5b: the failed-resize take-back leaves NO stranded phone-fit —
-  // driver released to desktop, override cleared, mode reset to 'auto'. (The
-  // pre-revision behavior kept the lock and relied on a later auto-restore; the
-  // explicit gesture now releases unconditionally.)
+  // Scenario 5b: explicit take-back releases unconditionally (pre-revision kept the lock for a later auto-restore).
   it('failed take-back leaves no stranded override or lock', async () => {
     const { runtime, setResizeSucceeds } = createRuntime()
 
@@ -773,8 +721,7 @@ describe('mobile presence lock — issue #7588 held-modal restore convergence',
     expect(runtime.getMobileDisplayMode('pty-1')).toBe('auto')
   })
 
-  // Scenario 6: a phone-initiated setDisplayMode('desktop') against a stale
-  // held override converges through the shared applyMobileDisplayMode seam.
+  // Scenario 6: phone-initiated desktop switch converges a stale held override via the shared applyMobileDisplayMode seam.
   it('phone-initiated setDisplayMode(desktop) against a stale held override converges', async () => {
     const { runtime, ptySizes, fitOverrideEvents } = createRuntime(null)
     const listenerEvents: { mode: string; cols: number; rows: number }[] = []
@@ -796,10 +743,7 @@ describe('mobile presence lock — issue #7588 held-modal restore convergence',
     expect(listenerEvents.slice(listenerBefore).some((e) => e.mode === 'desktop-fit')).toBe(true)
   })
 
-  // Scenario 7 (white-box): a held override whose `layouts` entry is gone is
-  // unreachable via public APIs (onPtyExit deletes both in lockstep), so seed
-  // it directly. Reclaim must still delete the override and emit a paired
-  // desktop-fit 0×0 rather than stranding the modal on the next hydrate.
+  // Scenario 7 (white-box): a held override with no `layouts` entry is unreachable via public APIs (onPtyExit deletes both in lockstep), so seed it directly.
   it('orphan cleanup: reclaim on a held override with no layout entry converges', async () => {
     const { runtime, fitOverrideEvents } = createRuntime(null)
     const listenerEvents: { mode: string; cols: number; rows: number }[] = []
diff --git a/src/main/runtime/mobile-subscribe-integration.test.ts b/src/main/runtime/mobile-subscribe-integration.test.ts
index 6c319271088..ceb178ee362 100644
--- a/src/main/runtime/mobile-subscribe-integration.test.ts
+++ b/src/main/runtime/mobile-subscribe-integration.test.ts
@@ -1,7 +1,5 @@
 /**
  * Integration tests for the server-authoritative mobile subscribe lifecycle.
- * Tests handleMobileSubscribe, handleMobileUnsubscribe, applyMobileDisplayMode,
- * debounced restore, inline restore on timer cancel, and cleanup paths.
  */
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import type * as GitUsernameModule from '../git/git-username'
@@ -50,11 +48,7 @@ vi.mock('../git/git-username', async () => {
   return { ...actual, resolveLocalGitUsername: vi.fn(async () => '') }
 })
 
-// Why: many tests pre-date the mobileAutoRestoreFitMs preference. Default
-// the mock store to MIN (5_000ms — the new clamp floor) so legacy
-// assertions about "restore fires after the configured delay" keep their
-// shape while new tests can override per-test. Indefinite/null is the
-// real-world default and is exercised by a dedicated test below.
+// Why: default the mock store to the clamp floor (5_000ms) so legacy "restore fires after delay" assertions hold; the real default is indefinite/null.
 const LEGACY_RESTORE_MS = 5_000
 const settingsState = {
   mobileAutoRestoreFitMs: LEGACY_RESTORE_MS as number | null
@@ -233,8 +227,7 @@ describe('mobile subscribe integration', () => {
       rows: 30,
       seq: 17,
       source: 'headless',
-      // Non-alt-screen buffer reports alternateScreen=false so the renderer
-      // keeps its destructive scrollback clear on restore.
+      // Non-alt-screen reports alternateScreen=false so the renderer keeps its destructive scrollback clear on restore.
       alternateScreen: false
     })
     await expect(runtime.serializeTerminalBuffer('pty-empty')).resolves.toBeNull()
@@ -292,9 +285,7 @@ describe('mobile subscribe integration', () => {
     expect(ptySizes.get('pty-1')).toEqual({ cols: 150, rows: 40 })
   })
 
-  // Why: 'phone' (sticky-fit) mode was removed — there are now only 'auto'
-  // and 'desktop'. Auto-mode always restores on last unsubscribe. Test
-  // kept and inverted to lock in the new contract.
+  // Why: 'phone' sticky-fit mode was removed; auto-mode now always restores on last unsubscribe.
   it('handleMobileUnsubscribe restores after auto-mode last unsubscribe', async () => {
     const { runtime, ptySizes } = createRuntime()
     // mode defaults to 'auto'
@@ -363,8 +354,7 @@ describe('mobile subscribe integration', () => {
     await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
     expect(ptySizes.get('pty-1')).toEqual({ cols: 45, rows: 20 })
 
-    // Re-subscribe to the same terminal (e.g., after reconnect)
-    // The PTY is already at 45x20, but previousDims should still be 150x40
+    // Re-subscribe (e.g. after reconnect): PTY is already 45x20 but previousDims must stay 150x40.
     await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
 
     // Unsubscribe and let restore fire
@@ -376,13 +366,7 @@ describe('mobile subscribe integration', () => {
   })
 
   it('preserves held-override baseline across resubscribe-after-indefinite-hold', async () => {
-    // Why: when the last mobile subscriber leaves under indefinite hold,
-    // the inner-subscribers map is wiped but `terminalFitOverrides` retains
-    // the original desktop dims as previousCols/previousRows. A fresh
-    // resubscribe must inherit those — otherwise rendererSize/currentSize
-    // (both phone dims because the override held them) would replace the
-    // baseline with phone dims, and any subsequent desktop "Restore" would
-    // be a no-op (restore-target == current dims).
+    // Why: a fresh resubscribe under indefinite hold must inherit the override's retained desktop baseline, or a later desktop Restore becomes a no-op.
     settingsState.mobileAutoRestoreFitMs = null // indefinite hold
     const { runtime, ptySizes } = createRuntime()
 
@@ -390,8 +374,7 @@ describe('mobile subscribe integration', () => {
     await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
     expect(ptySizes.get('pty-1')).toEqual({ cols: 45, rows: 20 })
 
-    // Phone leaves; indefinite hold keeps PTY at phone dims with no
-    // subscribers. Override baseline still carries 150x40.
+    // Phone leaves; indefinite hold keeps PTY phone-fit while the override baseline still carries 150x40.
     runtime.handleMobileUnsubscribe('pty-1', 'client-a')
     await vi.advanceTimersByTimeAsync(60_000)
     expect(ptySizes.get('pty-1')).toEqual({ cols: 45, rows: 20 })
@@ -568,9 +551,7 @@ describe('mobile subscribe integration', () => {
       await runtime.applyMobileDisplayMode('pty-1')
       expect(ptySizes.get('pty-1')).toEqual({ cols: 150, rows: 40 })
 
-      // Phone→desktop arms the 500ms renderer-cascade suppress window per
-      // docs/mobile-terminal-layout-state-machine.md. Wait it out before the
-      // renderer's correcting fit is allowed to update lastRendererSizes.
+      // Wait out the 500ms cascade-suppress armed by phone→desktop before the renderer's fit can update lastRendererSizes. See docs/mobile-terminal-layout-state-machine.md.
       await vi.advanceTimersByTimeAsync(500)
 
       // Simulate desktop renderer's safeFit correcting to split-pane width
@@ -605,30 +586,21 @@ describe('mobile subscribe integration', () => {
     })
 
     it('ignores reports while a mobile-fit override is in place', async () => {
-      // Why: while a mobile-fit override is in place, the PTY is parked at
-      // phone dims and the desktop renderer's safeFit will report those
-      // phone dims back to us. Treating that as "external" geometry would
-      // overwrite the subscriber's previousCols/Rows baseline with phone
-      // dims; resolveDesktopRestoreTarget would then return phone dims on
-      // the next "Restore" click, leaving xterm stuck at phone dims after
-      // a no-op desktop-restore. See docs/mobile-fit-hold.md.
+      // Why: while an override holds phone dims the renderer echoes them back; treating that echo as external geometry would poison the restore baseline. See docs/mobile-fit-hold.md.
       const { runtime, ptySizes } = createRuntime()
       await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
 
       // Renderer reports phone dims back (echo of override). Must be ignored.
       runtime.onExternalPtyResize('pty-1', 45, 20)
 
-      // Toggle to desktop — restore lands on the original desktop baseline,
-      // not the phone-dim echo.
+      // Toggle to desktop — restore lands on the original baseline, not the phone-dim echo.
       runtime.setMobileDisplayMode('pty-1', 'desktop')
       await runtime.applyMobileDisplayMode('pty-1')
       expect(ptySizes.get('pty-1')).toEqual({ cols: 150, rows: 40 })
     })
 
     it('still updates baseline once the override is cleared (real desktop resize)', async () => {
-      // Counterpart to the above: after the user takes back, the renderer's
-      // pty:resize events ARE legitimate geometry reports and must update
-      // the baseline used by the next phone-fit cycle.
+      // Counterpart: once the override is cleared, pty:resize reports are legitimate and must update the baseline.
       const { runtime, ptySizes } = createRuntime()
       await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
 
@@ -643,8 +615,7 @@ describe('mobile subscribe integration', () => {
       // User resizes the desktop window. Renderer fires pty:resize.
       runtime.onExternalPtyResize('pty-1', 130, 35)
 
-      // Toggle back to phone, then take back again — should restore to the
-      // updated desktop geometry, not the original 150x40.
+      // Toggle to phone then take back — should restore the updated geometry, not the original 150x40.
       runtime.setMobileDisplayMode('pty-1', 'auto')
       await runtime.applyMobileDisplayMode('pty-1')
       expect(ptySizes.get('pty-1')).toEqual({ cols: 45, rows: 20 })
@@ -655,23 +626,14 @@ describe('mobile subscribe integration', () => {
     })
 
     it('updates baseline mid-fit when desktop reports dims that differ from the override', async () => {
-      // Why: a previously-hidden desktop tab can become visible while the
-      // phone is still phone-fitting (e.g. user activates the tab on
-      // desktop). The pane's container goes 0×0 → real geometry, fitAddon
-      // measures, and pty:resize fires with REAL dims (not the override's
-      // phone dims). That report is legitimate and must refresh the
-      // restore baseline so take-back lands on the visible desktop
-      // geometry instead of whatever stale baseline the subscriber
-      // captured at first subscribe.
+      // Why: a desktop tab becoming visible mid-fit fires pty:resize with real dims (not the override's); that legit report must refresh the restore baseline.
       const { runtime, ptySizes } = createRuntime()
-      // Pre-populate with an old/stale baseline (e.g. spawn default 80×24)
-      // by first reporting it before subscribe, then subscribing.
+      // Seed a stale baseline (spawn default 80×24) before subscribing.
       ptySizes.set('pty-1', { cols: 80, rows: 24 })
       runtime.onExternalPtyResize('pty-1', 80, 24)
       await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
 
-      // Desktop tab gets activated mid-fit; renderer reports real dims.
-      // These differ from the override (45×20), so they must pass through.
+      // Desktop tab activated mid-fit reports real dims differing from the override (45×20), so they pass through.
       runtime.onExternalPtyResize('pty-1', 200, 60)
 
       // Take back — should land on 200×60, not 80×24.
@@ -683,19 +645,13 @@ describe('mobile subscribe integration', () => {
 
   describe('recordRendererGeometry (pty:reportGeometry IPC)', () => {
     it('refreshes subscriber baseline while a mobile-fit override is active', async () => {
-      // Why: backs the partial-restore-width fix. When phone subscribes to
-      // a never-desktop-active terminal, the subscriber baseline is the
-      // PTY spawn default (e.g. 80×24). The renderer's measurement-only
-      // report (sent when the desktop pane finally measures real geometry)
-      // must update the baseline so Take Back restores to real dims.
+      // Why: for a never-desktop-active terminal the baseline is the spawn default; the measurement-only report must update it so Take Back restores real dims.
       const { runtime, ptySizes } = createRuntime()
       ptySizes.set('pty-1', { cols: 80, rows: 24 })
       runtime.onExternalPtyResize('pty-1', 80, 24)
       await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
 
-      // Override is now in place (phone-fit). Desktop pane becomes visible
-      // and measures real geometry. The renderer reports it via the
-      // measurement-only channel.
+      // Override in place; desktop pane becomes visible and reports real geometry via the measurement-only channel.
       runtime.recordRendererGeometry('pty-1', 214, 72)
 
       // Take back — should restore to the reported dims, not 80×24.
@@ -705,10 +661,7 @@ describe('mobile subscribe integration', () => {
     })
 
     it('updates lastRendererSizes for a never-subscribed PTY', () => {
-      // Why: handleMobileSubscribe's previousCols fallback chain reads
-      // lastRendererSizes. A geometry report fired before the first
-      // subscribe must populate that cache so the subscriber's baseline
-      // captures real dims, not the spawn default.
+      // Why: a geometry report before first subscribe must populate lastRendererSizes so the baseline captures real dims, not the spawn default.
       const { runtime } = createRuntime()
       runtime.recordRendererGeometry('pty-99', 180, 50)
 
@@ -725,11 +678,7 @@ describe('mobile subscribe integration', () => {
     })
 
     it('bypasses the cascade-suppress window (it is measurement-only)', async () => {
-      // Why: pty:resize is gated by a 500ms suppress to absorb the safeFit
-      // cascade after a mode flip. The measurement-only channel must not
-      // be gated — its whole purpose is to deliver a fresh measurement
-      // when the renderer detects the pane container has finally settled
-      // to real geometry, including potentially right after a flip.
+      // Why: the measurement-only channel must bypass the 500ms cascade-suppress that gates pty:resize, since it can carry a fresh measurement right after a flip.
       const { runtime } = createRuntime()
       // Arm cascade-suppress.
       runtime.setMobileDisplayMode('pty-1', 'desktop')
@@ -792,19 +741,13 @@ describe('mobile subscribe integration', () => {
       await vi.advanceTimersByTimeAsync(30_000)
       await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
 
-      // The pending timer should have been cancelled by the new subscribe.
-      // Wait long past what would've been the restore moment.
+      // The new subscribe should have cancelled the pending restore timer.
       await vi.advanceTimersByTimeAsync(120_000)
       expect(ptySizes.get('pty-1')).toEqual({ cols: 45, rows: 20 })
     })
 
     it('reclaimTerminalForDesktop with active subscriber resets mode so next subscribe re-fits', async () => {
-      // Why: desktop "Take back" while the phone is actively driving sets
-      // mobileDisplayMode='desktop' to drive the layout transition. Without
-      // resetting it, the next mobile subscribe (e.g. user switches tabs
-      // back on the phone) sees mode='desktop' and enters passive watch,
-      // never re-fitting the PTY to phone dims. The phone then renders the
-      // desktop-dim scrollback echoed back at it. See docs/mobile-fit-hold.md.
+      // Why: reclaim must reset mode to 'auto', else the next subscribe stays in passive watch and never re-fits to phone dims. See docs/mobile-fit-hold.md.
       const { runtime, ptySizes } = createRuntime()
       await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
       expect(ptySizes.get('pty-1')).toEqual({ cols: 45, rows: 20 })
@@ -822,12 +765,7 @@ describe('mobile subscribe integration', () => {
     })
 
     it('reclaim with WS disconnect between cycles — held branch restores correctly each time', async () => {
-      // Why: regression for "subsequent take-back stuck on phone dims" with
-      // indefinite hold. The realistic flow is:
-      //   subscribe → desktop reclaim → WS disconnect (background app) →
-      //   phone re-subscribes → WS disconnect → desktop reclaim (held branch)
-      // The held branch must restore to real desktop dims every time, not
-      // get stuck reading current PTY size (= phone dims).
+      // Why: regression — under indefinite hold the held-branch reclaim must restore real desktop dims every cycle, not the current (phone) PTY size.
       settingsState.mobileAutoRestoreFitMs = null
       const { runtime, ptySizes } = createRuntime()
 
@@ -836,9 +774,7 @@ describe('mobile subscribe integration', () => {
         await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
         expect(ptySizes.get('pty-1'), `iter ${i}: phone-fit`).toEqual({ cols: 45, rows: 20 })
 
-        // Phone WS disconnects (e.g. backgrounding). With indefinite hold,
-        // PTY stays at phone dims and override persists; subscriber is
-        // removed from inner.
+        // WS disconnect under indefinite hold: PTY stays phone-fit, override persists, subscriber removed.
         runtime.onClientDisconnected('client-a')
         await vi.advanceTimersByTimeAsync(0)
         await vi.advanceTimersByTimeAsync(60_000)
@@ -861,8 +797,7 @@ describe('mobile subscribe integration', () => {
     })
 
     it('reclaim → re-subscribe → reclaim cycle works repeatedly', async () => {
-      // Why: regression for "subsequent take-back doesn't change dims, stuck
-      // at phone dims". The full ping-pong must work N times, not just once.
+      // Why: regression — the reclaim/re-subscribe ping-pong must work N times, not just once.
       const { runtime, ptySizes } = createRuntime()
 
       for (let i = 0; i < 3; i++) {
@@ -882,11 +817,7 @@ describe('mobile subscribe integration', () => {
     })
 
     it('null (indefinite) keeps PTY at phone dims when WS connection closes (onClientDisconnected)', async () => {
-      // Why: backgrounding the mobile app eventually closes the WebSocket,
-      // which routes through onClientDisconnected (NOT handleMobileUnsubscribe).
-      // The disconnect path predates indefinite-hold; without explicit gates
-      // it would unconditionally restore the PTY to desktop dims and clear
-      // the override, unmounting the desktop banner.
+      // Why: WS close routes through onClientDisconnected (not handleMobileUnsubscribe), which must honor indefinite-hold rather than unconditionally restore.
       settingsState.mobileAutoRestoreFitMs = null
       const { runtime, ptySizes } = createRuntime()
       await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
@@ -918,9 +849,7 @@ describe('mobile subscribe integration', () => {
     })
 
     it('reclaimTerminalForDesktop prefers fresh desktop geometry for a held PTY', async () => {
-      // Why: the held override can carry the first phone-fit baseline, but
-      // desktop can measure newer real geometry while the phone-sized PTY is
-      // held. Manual restore must honor that fresh desktop measurement.
+      // Why: manual restore must honor fresh desktop geometry measured while the PTY was phone-held, not the stale baseline.
       settingsState.mobileAutoRestoreFitMs = null
       const { runtime, ptySizes } = createRuntime()
       await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
@@ -955,9 +884,7 @@ describe('mobile subscribe integration', () => {
       await runtime.handleMobileSubscribe('pty-1', 'client-a', { cols: 45, rows: 20 })
       runtime.handleMobileUnsubscribe('pty-1', 'client-a')
 
-      // Indefinite hold — no timer scheduled at unsubscribe.
-      // Switch preference → 60s. The already-held PTY is NOT auto-restored;
-      // the new value applies to the *next* unsubscribe.
+      // A finite value applies to the next unsubscribe only; the already-held PTY is not retroactively restored.
       runtime.setMobileAutoRestoreFitMs(60_000)
       await vi.advanceTimersByTimeAsync(120_000)
       expect(ptySizes.get('pty-1')).toEqual({ cols: 45, rows: 20 })
@@ -1062,8 +989,7 @@ describe('mobile subscribe integration', () => {
       priv.notifyMobileSessionTabsChanged('worktree-a')
       expect(emits).toHaveLength(1)
 
-      // The pending coalesced notify was cancelled by the immediate emit, so no
-      // duplicate trailing emit fires.
+      // The immediate emit cancelled the pending coalesced notify — no duplicate trailing emit.
       vi.advanceTimersByTime(50)
       expect(emits).toHaveLength(1)
 
@@ -1083,8 +1009,7 @@ describe('mobile subscribe integration', () => {
       priv.touchMobileSessionSnapshotsForPty('pty-1')
       expect(emits).toHaveLength(0)
 
-      // Closing the subscription flushes the pending window so the final state
-      // still reaches the listener before it is dropped.
+      // Closing the subscription flushes the pending window so the final state reaches the listener.
       unsubscribe()
       expect(emits).toHaveLength(1)
     })
diff --git a/src/main/runtime/orca-runtime-browser.ts b/src/main/runtime/orca-runtime-browser.ts
index c7da17da95d..9070f90bef8 100644
--- a/src/main/runtime/orca-runtime-browser.ts
+++ b/src/main/runtime/orca-runtime-browser.ts
@@ -144,15 +144,9 @@ export type RuntimeBrowserCommandHost = {
   resolveWorktreeSelector(selector: string): Promise<{ id: string }>
   getAuthoritativeWindow(): BrowserWindow
   getAvailableAuthoritativeWindow(): BrowserWindow | null
-  // Why: headless serve has no renderer window; browser pages are backed by a
-  // main-process offscreen backend instead. Null when offscreen browsing is
-  // unavailable (e.g. environment can't support it), which keeps capability
-  // reporting honest.
+  // Why: headless serve backs pages with a main-process offscreen backend; null when the environment can't support offscreen browsing.
   getOffscreenBrowserBackend(): BrowserBackend | null
-  // Why: the session-tab snapshot is the source of truth for which tab is
-  // focused. A headless browser create must mark itself active there so paired
-  // clients keep focus on the new tab instead of the reconcile snapping back to
-  // a terminal (whose activeTabType the snapshot still reports).
+  // Why: the session-tab snapshot owns focus, so a headless create must mark itself active or paired clients snap back to a terminal.
   markHeadlessBrowserSessionTabActive?(
     worktreeId: string | undefined,
     browserPageId: string,
@@ -201,15 +195,10 @@ export class RuntimeBrowserCommands {
     return Boolean(guest && !guest.isDestroyed())
   }
 
-  // Why: the CLI sends worktree selectors (e.g. "path:/Users/...") but the
-  // bridge stores worktreeIds in "repoId::path" format (from the renderer's
-  // Zustand store). This helper resolves the selector to the store-compatible
-  // ID so the bridge can filter tabs correctly.
+  // Why: the CLI sends selectors (e.g. "path:/...") but the bridge keys tabs by "repoId::path"; resolve to that store-compatible id.
   private async resolveBrowserWorktreeId(selector?: string): Promise<string | undefined> {
     if (!selector) {
-      // Why: after app restart, webviews only mount when the browser pane is visible.
-      // Without --worktree, we still need to activate the view so persisted tabs
-      // become operable via registerGuest.
+      // Why: after restart, webviews mount only when the pane is visible; activate the view so persisted tabs become operable via registerGuest.
       const bridge = this.host.getAgentBrowserBridge()
       if (bridge && !this.hasLiveRegisteredBrowserTab(bridge, undefined)) {
         try {
@@ -222,17 +211,13 @@ export class RuntimeBrowserCommands {
     }
 
     const worktreeId = (await this.host.resolveWorktreeSelector(selector)).id
-    // Why: explicit worktree selectors are user intent, so resolution errors
-    // must surface instead of silently widening browser routing scope. Only the
-    // activation step remains best-effort because missing windows during tests
-    // or startup should not erase the validated worktree target itself.
+    // Why: explicit selectors are user intent, so resolution errors surface (not silently widen scope); only activation stays best-effort.
     const bridge = this.host.getAgentBrowserBridge()
     if (bridge && !this.hasLiveRegisteredBrowserTab(bridge, worktreeId)) {
       try {
         await this.ensureBrowserWorktreeActive(worktreeId)
       } catch {
-        // Fall through with the validated worktree id so downstream routing
-        // still stays scoped to the caller's explicit selector.
+        // Fall through with the validated worktree id so routing stays scoped to the caller's explicit selector.
       }
     }
     return worktreeId
@@ -257,14 +242,11 @@ export class RuntimeBrowserCommands {
       try {
         await this.ensureBrowserPageActive(worktreeId, browserPageId)
       } catch {
-        // Fall through with the explicit page target so downstream routing
-        // returns the existing clear "tab not found" error if wake fails.
+        // Fall through with the explicit page target; downstream routing surfaces a clear "tab not found" error if wake fails.
       }
     }
     return {
-      // Why: explicit browserPageId is already a stable tab identity, so we do
-      // not auto-resolve cwd worktree scoping on top of it. Only honor an
-      // explicit --worktree when the caller asked for that extra validation.
+      // Why: an explicit browserPageId is already a stable tab identity, so don't auto-resolve cwd worktree scoping on top of it.
       worktreeId,
       browserPageId
     }
@@ -297,16 +279,11 @@ export class RuntimeBrowserCommands {
     return { browserPageId: resolvedPageId, webContents: guest }
   }
 
-  // Why: browser tabs must become paintable before their webview guest starts
-  // and registerGuest fires, but automation must not steal the user's visible
-  // worktree/browser pane. Ask the renderer to background-mount the worktree and
-  // acquire a hidden automation visibility lease instead of activating the UI.
+  // Why: background-mount the worktree via a hidden visibility lease so the webview guest can register without stealing the user's visible pane.
   private async ensureBrowserWorktreeActive(worktreeId: string | undefined): Promise<void> {
     const win = this.host.getAuthoritativeWindow()
     win.webContents.send('browser:activateView', worktreeId ? { worktreeId } : {})
-    // Why: hidden/restored browser panes become operable only after the
-    // renderer's webview mounts and calls registerGuest. Waiting on that IPC is
-    // both faster and less flaky than sleeping for an arbitrary fixed delay.
+    // Why: the pane is operable only after the webview mounts and calls registerGuest; wait on that IPC rather than a flaky fixed sleep.
     await waitForWorktreeTabRegistration(worktreeId)
   }
 
@@ -322,11 +299,7 @@ export class RuntimeBrowserCommands {
     await waitForTabRegistration(browserPageId)
   }
 
-  // Why: agent-browser drives navigation via CDP, which bypasses Electron's
-  // webview event system. The renderer's did-navigate / page-title-updated
-  // listeners never fire, leaving the Zustand store (and thus the Orca UI's
-  // address bar and tab title) stale. Push updates from main → renderer after
-  // any navigation-causing command so the UI stays in sync.
+  // Why: CDP navigation bypasses Electron's webview events, so the renderer's did-navigate listeners never fire; push updates to keep the UI in sync.
   private notifyRendererNavigation(browserPageId: string, url: string, title: string): void {
     try {
       const win = this.host.getAuthoritativeWindow()
@@ -336,18 +309,7 @@ export class RuntimeBrowserCommands {
     }
   }
 
-  // Why: `tabSwitch` only flips the bridge's `activeWebContentsId` — it
-  // does not surface the browser pane in the renderer. Without --focus, the
-  // switch is invisible to the user. With --focus, we send a dedicated IPC
-  // so the renderer can update its per-worktree active-tab state.
-  //
-  // Why this IPC carries `worktreeId` instead of letting the renderer
-  // dispatch `setActiveWorktree`: multiple agents drive browsers in parallel
-  // worktrees. A global focus call from agent X would steal the user's
-  // screen from agent Y's worktree. The renderer-side handler
-  // (focusBrowserTabInWorktree) updates per-worktree state unconditionally
-  // and only flips globals when the user is already on the targeted
-  // worktree. Cross-worktree --focus calls pre-stage silently.
+  // Why: carry worktreeId (not a global setActiveWorktree) so one agent's --focus can't steal the screen from another agent's parallel worktree.
   private notifyRendererBrowserPaneFocus(
     worktreeId: string | undefined,
     browserPageId: string
@@ -374,9 +336,7 @@ export class RuntimeBrowserCommands {
     const target = await this.resolveBrowserCommandTarget(params)
     const bridge = this.requireAgentBrowserBridge()
     const result = await bridge.click(params.element, target.worktreeId, target.browserPageId)
-    // Why: clicks can trigger navigation (e.g. submitting a form, clicking a link).
-    // Read the target tab's live URL/title after the click and push to the
-    // renderer so the UI updates even when automation targeted a non-active page.
+    // Why: clicks can trigger navigation, so push the tab's live URL/title to the renderer even when automation targeted a non-active page.
     const page = bridge.getPageInfo(target.worktreeId, target.browserPageId)
     if (page) {
       this.notifyRendererNavigation(page.browserPageId, page.url, page.title)
@@ -503,9 +463,7 @@ export class RuntimeBrowserCommands {
     }
     let active = this.activeScreencastsByPageId.get(browserPageId)
     while (active) {
-      // Why: CDP only allows one Page.startScreencast per page. Treat a new
-      // subscriber as taking over from a stale/hidden paired client instead of
-      // surfacing an already-active error in the browser pane.
+      // Why: CDP allows one Page.startScreencast per page, so a new subscriber takes over a stale/hidden client instead of erroring.
       active.stop()
       await active.done
       stopping = this.stoppingScreencastPageIds.get(browserPageId)
@@ -581,8 +539,7 @@ export class RuntimeBrowserCommands {
       if (stoppingPromise || !session) {
         return
       }
-      // Why: mobile can unsubscribe and immediately resubscribe on rotation.
-      // New streams wait for CDP teardown instead of failing with already-active.
+      // Why: mobile can unsubscribe and instantly resubscribe on rotation; new streams wait for CDP teardown instead of failing already-active.
       stoppingPromise = session.done.finally(clearPageGate)
       this.stoppingScreencastPageIds.set(browserPageId, stoppingPromise)
     }
@@ -668,11 +625,7 @@ export class RuntimeBrowserCommands {
     const bridge = this.requireAgentBrowserBridge()
     const result = await bridge.tabSwitch(params.index, target.worktreeId, target.browserPageId)
     if (params.focus) {
-      // Why: prefer the explicit --worktree the caller passed; fall back to
-      // the bridge's owning-worktree map for the just-switched tab. The
-      // owning worktree is what the renderer needs to scope the focus to.
-      // The renderer NEVER yanks the user across worktrees on this signal
-      // (see focusBrowserTabInWorktree).
+      // Why: scope focus to the tab's owning worktree; the renderer never yanks the user across worktrees on this signal (see focusBrowserTabInWorktree).
       const worktreeId =
         target.worktreeId ?? browserManager.getWorktreeIdForTab(result.browserPageId) ?? undefined
       this.notifyRendererBrowserPaneFocus(worktreeId, result.browserPageId)
@@ -1353,9 +1306,7 @@ export class RuntimeBrowserCommands {
         `Browser profile ${params.profileId} was not found`
       )
     }
-    // Why: a desktop renderer mounts a <webview>; a headless serve has none and
-    // backs the page with a main-process offscreen WebContents instead. Both
-    // register into BrowserManager so all downstream commands resolve uniformly.
+    // Why: headless serve has no renderer <webview>, so back the page with a main-process offscreen WebContents instead.
     if (!this.host.getAvailableAuthoritativeWindow()) {
       const offscreen = this.host.getOffscreenBrowserBackend()
       if (!offscreen) {
@@ -1378,35 +1329,23 @@ export class RuntimeBrowserCommands {
       params.activate
     )
 
-    // Why: the renderer creates the Zustand tab immediately, but the webview must
-    // mount and fire dom-ready before registerGuest runs. Waiting here ensures the
-    // tab is operable by subsequent CLI commands (snapshot, click, etc.).
-    // If registration doesn't complete within timeout, return the ID anyway — the
-    // tab exists in the UI but may not be ready for automation commands yet.
+    // Why: the webview must mount and register before the tab is operable, so wait here (returning the ID anyway on timeout).
     if (params.waitForRegistration !== false) {
       try {
         await waitForTabRegistration(browserPageId)
       } catch {
-        // Tab was created in the renderer but the webview hasn't finished mounting.
-        // Return success since the tab exists; subsequent commands will fail with a
-        // clear "tab not available" error if the webview never loads.
+        // Tab exists in the renderer even if the webview hasn't mounted; subsequent commands surface a clear error if it never loads.
       }
     }
 
-    // Why: newly created tabs should be auto-activated so subsequent commands
-    // (snapshot, click, goto) target the new tab without requiring an explicit
-    // tab switch. Without this, the bridge's active tab still points at the
-    // previously active tab and the new tab shows active: false in tab list.
+    // Why: auto-activate the new tab so subsequent commands target it without an explicit switch.
     const bridge = this.requireAgentBrowserBridge()
     const wcId = bridge.getRegisteredTabs(worktreeId).get(browserPageId)
     if (wcId != null) {
       bridge.setActiveTab(wcId, worktreeId)
     }
 
-    // Why: the renderer sets webview.src=url on mount, but agent-browser connects
-    // via CDP after the webview loads about:blank. Without an explicit goto, the
-    // page stays blank from agent-browser's perspective. Navigate via the bridge
-    // so agent-browser's CDP session tracks the correct page state.
+    // Why: the webview loads about:blank first, so navigate via the bridge to make agent-browser's CDP session track the real URL.
     if (url && url !== 'about:blank') {
       try {
         const result = await bridge.goto(url, worktreeId, browserPageId)
@@ -1441,8 +1380,7 @@ export class RuntimeBrowserCommands {
       )
     }
 
-    // Why: short-circuit no-op switches so the renderer doesn't tear down and
-    // remount the webview when the tab is already on the requested profile.
+    // Why: short-circuit no-op switches so the renderer doesn't needlessly tear down and remount the webview.
     const currentProfileId = browserManager.getSessionProfileIdForTab(browserPageId) ?? 'default'
     if (currentProfileId === profile.id) {
       return {
@@ -1484,17 +1422,11 @@ export class RuntimeBrowserCommands {
       })
     })
 
-    // Why: the renderer destroys the old webview and remounts on the new
-    // partition. Wait for the re-register so a follow-up tab list
-    // --show-profile reads the updated sessionProfileId from BrowserManager
-    // instead of stale data, and so subsequent CLI ops (snapshot, click, etc.)
-    // hit a guest that's already attached.
+    // Why: profile change remounts the webview; wait for re-register so follow-up commands see the new profile and an attached guest.
     try {
       await waitForTabRegistration(browserPageId)
     } catch {
-      // Best-effort: re-register won't fire if the worktree is hidden. The
-      // store already reflects the new profile; downstream commands retry
-      // once the pane re-mounts.
+      // Best-effort: re-register won't fire while the worktree is hidden; downstream commands retry once the pane re-mounts.
     }
 
     return {
@@ -1543,8 +1475,7 @@ export class RuntimeBrowserCommands {
       profile.id,
       profile.partition
     )
-    // Why: parity with browserTabCreate. Wait for the cloned tab's webview to
-    // register so the returned browserPageId is operable by the next CLI call.
+    // Why: wait for the cloned tab's webview to register so the returned browserPageId is operable by the next CLI call.
     try {
       await waitForTabRegistration(created.browserPageId)
     } catch {
@@ -1580,8 +1511,7 @@ export class RuntimeBrowserCommands {
 
   async browserProfileDetectBrowsers(): Promise<BrowserDetectProfilesResult> {
     return {
-      // Why: clients only need display metadata for the picker; filesystem
-      // paths and keychain identifiers stay on the runtime server.
+      // Why: expose only display metadata; filesystem paths and keychain identifiers stay on the runtime server.
       browsers: detectInstalledBrowsers().map((browser) => ({
         family: browser.family,
         label: browser.label,
@@ -1675,9 +1605,7 @@ export class RuntimeBrowserCommands {
       }
       tabId = entries[params.index][0]
     } else {
-      // Why: try the bridge first (registered tabs with webviews), then fall back
-      // to asking the renderer to close its active browser tab (handles cases where
-      // the webview hasn't mounted yet, e.g. tab was just created).
+      // Why: try the bridge first; fall back to the renderer for tabs whose webview hasn't mounted yet (e.g. just created).
       const tabs = bridge.getRegisteredTabs(worktreeId)
       const entries = [...tabs.entries()]
       const activeEntry = entries.find(([, wcId]) => wcId === bridge.getActiveWebContentsId())
@@ -1686,15 +1614,12 @@ export class RuntimeBrowserCommands {
       }
     }
 
-    // Why: headless serve owns its pages via the offscreen backend, with no
-    // renderer to ask. Destroy the offscreen page directly when that backend is
-    // the one serving this host (no renderer window).
+    // Why: headless serve has no renderer to ask, so destroy the offscreen page directly.
     const offscreen = this.host.getAvailableAuthoritativeWindow()
       ? null
       : this.host.getOffscreenBrowserBackend()
     if (offscreen) {
-      // Why: for implicit close (no --page/--index) resolve the active page like
-      // the renderer path does, so we don't report success while closing nothing.
+      // Why: resolve the active page for implicit close so we don't report success while closing nothing.
       const resolvedTabId = tabId ?? bridge.getActivePageId(worktreeId)
       if (!resolvedTabId) {
         return { closed: false }
@@ -1727,11 +1652,7 @@ export class RuntimeBrowserCommands {
         }
       }
       ipcMain.on('browser:tabCloseReply', handler)
-      // Why: when main cannot resolve a concrete tab id itself (for example if a
-      // browser workspace exists in the renderer before its guest mounts), the
-      // renderer still needs the intended worktree scope. Otherwise it falls
-      // back to the globally active browser tab and can close a tab in the
-      // wrong worktree.
+      // Why: pass worktreeId so the renderer scopes the close correctly instead of falling back to the globally active tab in the wrong worktree.
       win.webContents.send('browser:requestTabClose', { requestId, tabId, worktreeId })
     })
 
@@ -1771,10 +1692,7 @@ export class RuntimeBrowserCommands {
     return this.enrichBrowserTabInfo(tab)
   }
 
-  // Why: headless serve path. The offscreen backend registers the page
-  // synchronously, so there is no webview-mount wait. The page already loaded the
-  // URL during createTab, so we only sync the bridge's active tab and notify the
-  // (absent) renderer is skipped — nav state is read from the live WebContents.
+  // Why: headless serve path — the offscreen backend registers synchronously, so there is no webview-mount wait.
   private async createBrowserTabOffscreen(
     offscreen: BrowserBackend,
     url: string,
@@ -1789,11 +1707,7 @@ export class RuntimeBrowserCommands {
     if (bridge && wcId != null) {
       bridge.setActiveTab(wcId, worktreeId)
     }
-    // Why: only a user-initiated create (activate:true, e.g. the UI or a mobile
-    // HTML-link tap) should steal focus by marking the tab active in the session
-    // snapshot. Background/agent creates (CLI `tab create`, automation) must NOT,
-    // or they'd yank a connected client/mobile to the new tab. Mirrors the
-    // renderer path, which forwards `activate` and never force-focuses otherwise.
+    // Why: only user-initiated creates (activate:true) mark the tab active; agent/background creates must not yank a connected client to it.
     if (activate === true) {
       this.host.markHeadlessBrowserSessionTabActive?.(worktreeId, browserPageId, targetGroupId)
     }
@@ -1836,11 +1750,7 @@ export class RuntimeBrowserCommands {
         requestId,
         url,
         worktreeId,
-        // Why: leave sessionProfileId/sessionPartition undefined when no explicit
-        // profile was chosen so the renderer still applies the user's configured
-        // default-profile inheritance. Only thread the resolved partition when a
-        // profile is named — sending null here would suppress inheritance and
-        // force the shared default partition.
+        // Why: keep these undefined (not null) when no profile is chosen so the renderer still applies default-profile inheritance.
         sessionProfileId: profileId,
         sessionPartition,
         activate
diff --git a/src/main/runtime/orca-runtime-files.ts b/src/main/runtime/orca-runtime-files.ts
index 822006701fd..36bf393b157 100644
--- a/src/main/runtime/orca-runtime-files.ts
+++ b/src/main/runtime/orca-runtime-files.ts
@@ -97,8 +97,7 @@ const WINDOWS_RUNTIME_FILE_WATCH_DEBOUNCE_MS = 150
 export const WINDOWS_RUNTIME_FILE_WATCH_CLOSE_DEADLINE_MS = 10_000
 const TERMINAL_FILE_GRANT_TTL_MS = 10 * 60 * 1000
 const OPEN_NOFOLLOW = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0
-// Why: runtime files.watch subscriptions are cleaned up through synchronous RPC
-// callbacks. Track native Parcel unsubscribe work so app shutdown can drain it.
+// Why: files.watch cleanup is synchronous RPC; track native Parcel unsubscribes so shutdown can drain them.
 const pendingRuntimeFileWatcherUnsubscribes = new Set<Promise<void>>()
 type RuntimeFileWatcherLease = {
   suspend(): Promise<void>
@@ -122,9 +121,7 @@ const MOBILE_BINARY_EXTENSIONS = new Set([
   '.webp',
   '.zip'
 ])
-// Raster image extensions the mobile client can render from a base64 data URI
-// via files.readPreview. Mirrors mobile's classifyMobileArtifact image set;
-// SVG/PDF are intentionally excluded (RN <Image> can't decode those data URIs).
+// Mirror of mobile classifyMobileArtifact's image set; SVG/PDF excluded because RN <Image> can't decode those data URIs.
 const MOBILE_PREVIEWABLE_IMAGE_EXTENSIONS = new Set([
   '.png',
   '.jpg',
@@ -203,8 +200,7 @@ function runtimeWatcherReleaseKey(
   connectionId: string | undefined,
   rootPath: string
 ): string {
-  // Why: identical absolute paths are valid on local and multiple SSH hosts;
-  // destructive teardown must stay scoped to the execution host that owns it.
+  // Why: identical absolute paths exist on local and multiple SSH hosts; scope teardown to the host that owns it.
   return JSON.stringify([runtimeId, connectionId ?? null, normalizeRuntimeWatcherRoot(rootPath)])
 }
 
@@ -269,8 +265,7 @@ function registerRuntimeFileWatcherRelease(
           })
           physicalExitPromise = physicalExit
         } else {
-          // Why: a synchronous close failure retains the native owner so a
-          // later removal or logical unsubscribe can retry the same handle.
+          // Why: a synchronous close failure retains the native owner so a later removal or unsubscribe can retry the same handle.
           releasePromise = null
         }
       }
@@ -286,8 +281,7 @@ function registerRuntimeFileWatcherRelease(
       if (resumePromise) {
         return physicalExitPromise ? Promise.resolve() : resumePromise
       }
-      // Why: a timed-out child still owns native handles until its physical
-      // exit; restoration must join that owner before starting a replacement.
+      // Why: a timed-out child still owns native handles until physical exit; join that owner before starting a replacement.
       const resumesAfterPhysicalExit = physicalExitPromise !== null
       const attempt = Promise.resolve(physicalExitPromise ?? releasePromise)
         .then(async () => {
@@ -502,8 +496,7 @@ export class RuntimeFileCommands {
     if (!isSafeMobileRelativePath(relativePath)) {
       throw new Error('invalid_relative_path')
     }
-    // Previewable images open like text (the mobile viewer renders them via
-    // files.readPreview); other binaries stay unavailable on mobile.
+    // Previewable images open like text (mobile renders via files.readPreview); other binaries stay unavailable on mobile.
     const kind = isMobilePreviewableImagePath(relativePath)
       ? 'image'
       : isMobileBinaryPath(relativePath)
@@ -515,15 +508,9 @@ export class RuntimeFileCommands {
       return { worktree: worktree.id, relativePath, kind, opened: false }
     }
     const filePath = joinWorktreeRelativePath(worktree.path, relativePath)
-    // Why: CLI/agents treat opened:true as success. Stat first so missing paths
-    // fail the RPC instead of creating a ghost editor tab that only errors on read.
+    // Why: CLI/agents treat opened:true as success; stat first so missing paths fail the RPC instead of opening a ghost tab.
     await this.assertMobileOpenTargetExists(filePath, connectionId)
-    // Why: the service's internal runtimeId is not a registered runtime env selector
-    // (those live in orca-environments.json). Passing it caused Unknown environment
-    // errors on content load for CLI-initiated opens (via files.open from orca cli
-    // used by agents). Instead pass undefined so the renderer openFile falls back to
-    // the current activeRuntimeEnvironmentId (or null), matching sidebar opens and
-    // allowing correct routing for local vs remote envs.
+    // Why: the internal runtimeId isn't a valid env selector; pass undefined so openFile falls back to activeRuntimeEnvironmentId.
     this.host.openFile(worktree.id, filePath, relativePath, undefined)
     return { worktree: worktree.id, relativePath, kind, opened: true }
   }
@@ -596,10 +583,7 @@ export class RuntimeFileCommands {
     }
   }
 
-  // Resolves a path tapped in the mobile terminal (absolute, relative, or ~/…)
-  // to a worktree-relative path the file RPCs can open, plus existence.
-  // Relative paths resolve against `cwd` when the caller supplies it, else
-  // against the worktree root.
+  // Resolves a mobile terminal tap to a worktree-relative path; relatives resolve against cwd, else the worktree root.
   async resolveTerminalPath(
     worktreeSelector: string,
     pathText: string,
@@ -610,8 +594,7 @@ export class RuntimeFileCommands {
     const store = this.host.requireStore()
     const target = await this.host.resolveRuntimeFileTarget(worktreeSelector)
     const { worktree, connectionId } = target
-    // Why: mobile may attach after OSC7 cwd metadata was emitted; the runtime
-    // still owns the terminal's latest cwd and can resolve the tap correctly.
+    // Why: mobile may attach after OSC7 cwd was emitted; the runtime still owns the terminal's latest cwd to resolve the tap.
     const normalizedTerminalHandle =
       terminalHandle && terminalHandle.trim().length > 0 ? terminalHandle.trim() : null
     const terminalCwd = normalizedTerminalHandle
@@ -630,9 +613,7 @@ export class RuntimeFileCommands {
       isDirectory: false
     }
 
-    // `~/…` is home-relative. The local home is known (os.homedir); the remote
-    // home is not, so don't guess — a tapped `~/…` on a remote worktree would
-    // mis-resolve under cwd/worktree-root, so treat it as not-openable instead.
+    // Why: remote home is unknown (only local os.homedir), so a tapped ~/… on a remote worktree is not-openable, not guessed.
     const isTilde = pathText.startsWith('~/') || pathText.startsWith('~\\')
     if (isTilde && connectionId) {
       return empty
@@ -669,9 +650,7 @@ export class RuntimeFileCommands {
         }
       }
 
-      // Why: mobile taps can point at agent-created artifacts outside the
-      // worktree. Authorize and grant the exact existing path instead of
-      // widening worktree-relative file RPCs to arbitrary absolute paths.
+      // Why: mobile taps may hit agent artifacts outside the worktree; grant the exact path, not arbitrary absolute paths.
       if (!normalizedTerminalHandle || !terminalCwd) {
         return { ...empty, relativePath, absolutePath }
       }
@@ -733,9 +712,7 @@ export class RuntimeFileCommands {
           : undefined
       }
     } catch (error) {
-      // A genuine "not found" → the path simply doesn't exist (report it, not an
-      // error). Transport/permission/provider failures must surface so a remote
-      // session doesn't silently report every tapped path as missing.
+      // Report genuine not-found as missing; let transport/permission errors surface so remote taps aren't all reported missing.
       if (
         isENOENT(error) ||
         (connectionId && RuntimeFileCommands.isRemoteNotFoundErrorMessage(error))
@@ -746,9 +723,7 @@ export class RuntimeFileCommands {
     }
   }
 
-  // A remote stat failure that means "the file isn't there" vs a transport /
-  // permission / provider error. The mux drops the ErrnoException `code`, so the
-  // message is the only signal — match the not-found shapes the relay surfaces.
+  // The mux drops ErrnoException.code, so match not-found by message shape (vs transport/permission/provider errors).
   private static isRemoteNotFoundErrorMessage(error: unknown): boolean {
     const message = error instanceof Error ? error.message : String(error)
     return /\bENOENT\b|no such file|not found|does not exist/i.test(message)
@@ -797,8 +772,7 @@ export class RuntimeFileCommands {
       provider.realpath(absolutePath),
       ...roots.map((root) => provider.realpath(root).catch(() => root))
     ])
-    // Why: SSH reads and writes follow symlinks on the relay. Grant the
-    // canonical target so a /tmp link cannot escape the temp-artifact boundary.
+    // Why: SSH I/O follows symlinks on the relay; grant the canonical target so a /tmp link can't escape the temp boundary.
     return realRoots.some((root) => isPathInsideOrEqual(root, realArtifactPath))
       ? realArtifactPath
       : null
@@ -1153,8 +1127,7 @@ export class RuntimeFileCommands {
       grant.absolutePath,
       grant.connectionId
     )
-    // Why: relay stat/read/write follow symlinks, so a remote temp artifact
-    // grant must be re-canonicalized after the terminal process can mutate it.
+    // Why: relay I/O follows symlinks, so re-canonicalize a remote temp-artifact grant after the process can mutate it.
     if (allowedPath !== grant.absolutePath) {
       throw new Error('terminal_file_grant_stale')
     }
@@ -1209,8 +1182,7 @@ export class RuntimeFileCommands {
           if (!provider) {
             throw new Error(SSH_FILESYSTEM_PROVIDER_UNAVAILABLE_MESSAGE)
           }
-          // Why: the RPC layer already threads AbortSignal for local watches; SSH
-          // must cancel the remote fs.watch request instead of waiting it out.
+          // Why: the RPC layer already threads AbortSignal for local watches; SSH must cancel the remote fs.watch, not wait it out.
           const close = await provider.watch(target.path, callback, { signal, onTerminalError })
           return { unsubscribe: async () => close(), rootPaths: [target.path] }
         }
@@ -1224,8 +1196,7 @@ export class RuntimeFileCommands {
           const close = watchWindowsRuntimeFileExplorer(rootPath, callback, onTerminalError)
           return { unsubscribe: close, rootPaths: [target.path, rootPath] }
         }
-        // Why: the forked watcher keeps the blocking crawl and native faults out
-        // of the main/`serve` process (issues #5308 and #8212).
+        // Why: the forked watcher keeps the blocking crawl and native faults out of the main/`serve` process (issues #5308, #8212).
         const dispose = await watchFileExplorerInWatcherProcess(
           rootPath,
           callback,
@@ -1255,8 +1226,7 @@ export class RuntimeFileCommands {
       await Promise.all(Array.from(leases, (lease) => lease.suspend()))
     }
     if (!connectionId) {
-      // Why: setup can fail before registerRuntimeFileWatcherRelease publishes
-      // its callback, while the host still retains an unkillable child owner.
+      // Why: setup can fail before registerRuntimeFileWatcherRelease publishes its callback while the child owner still lives.
       const resolvedRootPath = await resolveAuthorizedPath(rootPath, this.host.requireStore())
       await closeFileExplorerWatcherInWatcherProcess(resolvedRootPath)
     }
@@ -1587,8 +1557,7 @@ export class RuntimeFileCommands {
       preserveSymlink: true
     })
     await mkdir(dirname(destinationPath), { recursive: true })
-    // Why: duplicate/copy operations are deconflicted by the caller. COPYFILE_EXCL
-    // preserves the same no-clobber invariant as the local shell copy IPC.
+    // Why: COPYFILE_EXCL preserves the no-clobber invariant of the local shell copy IPC (caller already deconflicts names).
     await copyFile(sourcePath, destinationPath, constants.COPYFILE_EXCL)
     return { ok: true }
   }
@@ -1611,8 +1580,7 @@ export class RuntimeFileCommands {
     const targetPath = await resolveAuthorizedPath(target.path, this.host.requireStore(), {
       preserveSymlink: true
     })
-    // Why: a non-local runtime has no client OS Trash/Recycling Bin; server-side
-    // file mutations are permanent and the renderer confirms before calling this.
+    // Why: a non-local runtime has no client Trash; this delete is permanent, so the renderer confirms before calling.
     await rm(targetPath, { recursive: recursive === true, force: true })
     return { ok: true }
   }
@@ -1827,8 +1795,7 @@ export class RuntimeFileCommands {
       throw new Error(SSH_FILESYSTEM_PROVIDER_UNAVAILABLE_MESSAGE)
     }
     const fileStat = await provider.stat(filePath)
-    // Why: the SSH filesystem API does not expose ranged reads here, so reject
-    // oversized remote previews instead of streaming a large file just to trim it.
+    // Why: no ranged reads over SSH here, so reject oversized previews instead of streaming a whole file just to trim it.
     if (fileStat.size > MOBILE_FILE_READ_MAX_BYTES) {
       throw new Error('file_too_large')
     }
@@ -1868,9 +1835,7 @@ function watchWindowsRuntimeFileExplorer(
     timer = setTimeout(emitOverflow, WINDOWS_RUNTIME_FILE_WATCH_DEBOUNCE_MS)
   }
 
-  // Why: Parcel probes Watchman before the Windows backend and its native
-  // watcher can abort the headless server process. For remote Windows runtimes,
-  // a conservative overflow refresh is safer than a process-wide native crash.
+  // Why: Parcel's Watchman probe can crash the headless server on Windows; use a conservative overflow refresh instead.
   const watcher = watchFs(rootPath, { recursive: true }, scheduleOverflow)
   const onClose = (): void => {
     watcher.removeListener('error', onError)
@@ -1884,8 +1849,7 @@ function watchWindowsRuntimeFileExplorer(
     }
     watcher.removeListener('close', onClose)
     watcher.removeListener('error', onError)
-    // Why: Node closes and nulls FSWatcher's native handle on error without a
-    // close event; that error is positive physical-exit proof for deletion.
+    // Why: Node nulls FSWatcher's native handle on error without a close event; treat the error as physical-exit proof.
     physicalClose.markExited()
     if (!disposed) {
       try {
@@ -1919,8 +1883,7 @@ function watchWindowsRuntimeFileExplorer(
         () => new Error('Windows watcher did not close before deletion deadline')
       )
     } catch (error) {
-      // Why: late Windows close still owns native directory handles; expose its
-      // exact completion so destructive cleanup retains and then clears the root.
+      // Why: late Windows close still owns native dir handles; expose its completion so cleanup retains then clears the root.
       throw new WatcherProcessFailure(
         error instanceof Error ? error.message : String(error),
         'supervisor',
@@ -1961,8 +1924,7 @@ async function isRuntimeDirectoryEntry(
   entry: { isDirectory(): boolean; isSymbolicLink(): boolean },
   _entryPath: string
 ): Promise<boolean> {
-  // Why: runtime-backed file explorer listings are still passive UI reads.
-  // Do not stat symlink targets here; explicit open/expand can resolve them.
+  // Why: listings are passive UI reads; don't stat symlink targets here (explicit open/expand resolves them).
   if (entry.isSymbolicLink()) {
     void _entryPath
     return false
@@ -2013,8 +1975,7 @@ function rethrowRuntimeFileCreateError(error: unknown, targetPath: string): neve
 async function readLocalMobileFile(filePath: string, store: Store): Promise<string> {
   const authorizedPath = await resolveAuthorizedPath(filePath, store)
   const fileStat = await stat(authorizedPath)
-  // Why: mobile file previews are read-only convenience views; cap the read so
-  // opening a generated log or bundle cannot block the WebSocket like oversized scrollback.
+  // Why: cap the read so opening a large file can't block the WebSocket (previews are read-only convenience views).
   const readLimit = Math.min(fileStat.size, MOBILE_FILE_READ_MAX_BYTES + 1)
   const handle = await open(authorizedPath, 'r')
   try {
@@ -2143,8 +2104,7 @@ function normalizeTerminalFileUriAuthorityPath(
   if (isLoopbackFileUriHostname(host) && (connectionId || process.platform !== 'win32')) {
     return normalizeLeadingSlashDrivePath(match[2]!, worktreePath)
   }
-  // Why: a file URI authority names a host. Without a verified host match,
-  // stripping it could open a same-path local or SSH artifact on the wrong machine.
+  // Why: without a verified host match, stripping the file-URI authority could open a same-path artifact on the wrong machine.
   return pathText
 }
 
diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index df63ad52573..4939d056a46 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -258,8 +258,7 @@ const {
   getIssueMock,
   deleteWorktreeHistoryDirMock
 } = vi.hoisted(() => {
-  // Why: SSH runtime tests register providers through the public dispatcher API,
-  // so the mock needs the same registry semantics as the real module.
+  // Why: SSH runtime tests register providers via the public dispatcher API, so the mock needs the same registry semantics as the real module.
   const sshGitProviders = new Map<string, unknown>()
   const sshProviderGenerations = new Map<string, number>()
 
@@ -562,8 +561,7 @@ vi.mock('../github/issues', async (importOriginal) => {
   }
 })
 
-// Why: CLI worktree creation resolves a default against fabricated repo paths
-// in these tests, so keep the async resolver deterministic.
+// Why: CLI worktree creation resolves a default against fabricated repo paths, so keep the async resolver deterministic.
 vi.mock('../git/repo', async (importOriginal) => {
   const actual = (await importOriginal()) as Record<string, unknown>
   const actualGetBaseRefDefault = actual.getBaseRefDefault as (
@@ -572,8 +570,7 @@ vi.mock('../git/repo', async (importOriginal) => {
   ) => Promise<string | null>
   return {
     ...actual,
-    // Why: fabricated local test repos need a deterministic default, while
-    // WSL coverage must still exercise the real async Git-options path.
+    // Why: fabricated local test repos need a deterministic default, while WSL coverage must still exercise the real async Git-options path.
     getBaseRefDefault: vi
       .fn()
       .mockImplementation((path: string, options?: { wslDistro?: string }) =>
@@ -941,10 +938,7 @@ function antigravityPromptBeforeModelReadyScreen(model = 'Gemini 3.5 Flash (High
   ].join('\n')
 }
 
-// Why: verbatim shape of a real cursor-agent 2026.07 idle screen. The fresh
-// input prompt is "→ Plan, search, build anything" (not "→ Add a follow-up",
-// which only appears after the first turn), so the matcher keys on the "→"
-// glyph, not a specific placeholder.
+// Why: verbatim cursor-agent 2026.07 idle screen; the matcher keys on the "→" glyph, not the placeholder (which changes after the first turn).
 function cursorReadyScreen(): string {
   return [
     'Cursor Agent',
@@ -967,8 +961,7 @@ function cursorBusyScreen(): string {
   ].join('\n')
 }
 
-// Why: these runtime feature tests only need message-queue semantics; using
-// SQLite here makes them fail on unrelated native runtime ABI drift.
+// Why: these tests only need message-queue semantics; real SQLite would make them fail on unrelated native runtime ABI drift.
 class InMemoryOrchestrationMessages {
   private sequence = 0
 
@@ -1863,8 +1856,7 @@ describe('OrcaRuntimeService', () => {
     runtime.setOffscreenBrowserBackend({ createTab: vi.fn(), closeTab: vi.fn() })
 
     expect(runtime.getStatus().capabilities).not.toContain('browser.headless.v1')
-    // Desktop webviews still host certificate trust, so the proceed capability
-    // remains advertised for remote clients controlling those pages.
+    // Desktop webviews still host certificate trust, so the proceed capability stays advertised for remote clients controlling those pages.
     expect(runtime.getStatus().capabilities).toContain('browser.certificate-trust.v1')
   })
 
@@ -2139,8 +2131,7 @@ describe('OrcaRuntimeService', () => {
     const staleHandle = beforeSleep.terminals[0]?.handle ?? ''
     expect(staleHandle).toBeTruthy()
 
-    // Why: `terminal.show` is read-only; only the later renderer wake/rebind
-    // graph publish can repair the CLI handle surface for this pane.
+    // Why: `terminal.show` is read-only; only a later renderer wake/rebind graph publish can repair this pane's CLI handle surface.
     runtime.syncWindowGraph(1, {
       tabs: [
         {
@@ -2204,8 +2195,7 @@ describe('OrcaRuntimeService', () => {
   it('drops a stale leaf when a woken agent PTY is re-keyed to a new leaf on renderer reload', async () => {
     const runtime = createRuntime()
     const tabId = 'tab-1'
-    // Why: the agent holds a pre-allocated ORCA_TERMINAL_HANDLE, so its PTY has a
-    // handleByPtyId entry — the exact condition the reload preservation loop keys on.
+    // Why: the agent's pre-allocated ORCA_TERMINAL_HANDLE gives its PTY a handleByPtyId entry — the condition the reload preservation loop keys on.
     runtime.preAllocateHandleForPty('pty-agent')
     runtime.attachWindow(TEST_WINDOW_ID)
     runtime.syncWindowGraph(TEST_WINDOW_ID, {
@@ -2231,8 +2221,7 @@ describe('OrcaRuntimeService', () => {
     const before = await runtime.listTerminals(`id:${TEST_WORKTREE_ID}`)
     expect(before.terminals).toHaveLength(1)
 
-    // Simulate agent sleep + mobile wake: the renderer reloads and cold-restores
-    // the pane under a NEW leafId while the SAME agent PTY stays live.
+    // Simulate agent sleep + mobile wake: the renderer cold-restores the pane under a NEW leafId while the SAME agent PTY stays live.
     runtime.markRendererReloading(TEST_WINDOW_ID)
     runtime.syncWindowGraph(TEST_WINDOW_ID, {
       tabs: [
@@ -2256,9 +2245,7 @@ describe('OrcaRuntimeService', () => {
     })
 
     const after = await runtime.listTerminals(`id:${TEST_WORKTREE_ID}`)
-    // Before the fix the stale leaf-old survived beside leaf-new — two leaves on
-    // ONE PTY — so both adopted the same ptyId-keyed handle and paired clients
-    // crashed with a duplicate React key (`term_…`). Now only the live leaf remains.
+    // Before the fix two leaves shared one PTY, so both adopted the same ptyId-keyed handle and paired clients crashed on a duplicate React key.
     expect(after.terminals).toHaveLength(1)
     expect(after.terminals[0].ptyId).toBe('pty-agent')
     // The shared handle must NOT have been invalidated — it belongs to leaf-new now.
@@ -2294,8 +2281,7 @@ describe('OrcaRuntimeService', () => {
     })
     expect((await runtime.listTerminals(`id:${TEST_WORKTREE_ID}`)).terminals).toHaveLength(1)
 
-    // Renderer reloads but has NOT yet rebound the pane (empty graph). The live
-    // CLI agent PTY + exported handle must survive (the original preserve intent).
+    // Renderer reloads but hasn't rebound the pane (empty graph); the live CLI agent PTY + exported handle must survive.
     runtime.markRendererReloading(TEST_WINDOW_ID)
     runtime.syncWindowGraph(TEST_WINDOW_ID, { tabs: [], leaves: [] })
 
@@ -2307,8 +2293,7 @@ describe('OrcaRuntimeService', () => {
   it('invalidates a re-keyed leaf-unique handle so in-flight waiters fail fast', async () => {
     const runtime = createRuntime()
     const tabId = 'tab-1'
-    // No preAllocateHandleForPty: a plain terminal's handle is leaf-unique, so a
-    // re-key leaves it with no next owner and it must go stale immediately.
+    // No preAllocateHandleForPty: a plain terminal's handle is leaf-unique, so a re-key leaves it with no next owner and it goes stale immediately.
     runtime.attachWindow(TEST_WINDOW_ID)
     runtime.syncWindowGraph(TEST_WINDOW_ID, {
       tabs: [
@@ -2335,8 +2320,7 @@ describe('OrcaRuntimeService', () => {
     const staleHandle = before.terminals[0].handle
     const waiting = runtime.waitForTerminal(staleHandle, { condition: 'exit', timeoutMs: 30_000 })
 
-    // Re-key WITHOUT a renderer reload (e.g. a pane moved across tabs) while the
-    // same PTY stays live under a new leaf.
+    // Re-key WITHOUT a renderer reload (e.g. a pane moved across tabs) while the same PTY stays live under a new leaf.
     runtime.syncWindowGraph(TEST_WINDOW_ID, {
       tabs: [
         {
@@ -2368,13 +2352,7 @@ describe('OrcaRuntimeService', () => {
   it('keeps a live CLI waiter pending when a re-keyed shared handle transfers to the live leaf', async () => {
     const runtime = createRuntime()
     const tabId = 'tab-1'
-    // The counterpart to the leaf-unique case above: a pre-allocated
-    // ORCA_TERMINAL_HANDLE is ptyId-keyed and shared, so re-keying its live PTY to
-    // a new leaf (a pane moved across tabs, no renderer reload) must hand the
-    // handle to the live leaf WITHOUT rejecting the agent's in-flight waiter. This
-    // pins the shared-handle branch so collapsing it into a blanket
-    // invalidateLeafHandle can't silently strand a CLI `terminal wait`. (A renderer
-    // reload is a separate path — markRendererReloading stales every waiter itself.)
+    // Unlike the leaf-unique case, a shared ptyId-keyed handle re-keyed to a live leaf must transfer WITHOUT rejecting the in-flight CLI waiter.
     runtime.preAllocateHandleForPty('pty-agent')
     runtime.attachWindow(TEST_WINDOW_ID)
     runtime.syncWindowGraph(TEST_WINDOW_ID, {
@@ -2416,8 +2394,7 @@ describe('OrcaRuntimeService', () => {
         }
       )
 
-    // Re-key WITHOUT a renderer reload while the same agent PTY stays live under a
-    // new leaf.
+    // Re-key WITHOUT a renderer reload while the same agent PTY stays live under a new leaf.
     runtime.syncWindowGraph(TEST_WINDOW_ID, {
       tabs: [
         {
@@ -2441,8 +2418,7 @@ describe('OrcaRuntimeService', () => {
 
     // Let any synchronous stale-handle rejection propagate.
     await new Promise<void>((resolve) => setImmediate(resolve))
-    // The shared handle belongs to leaf-new now, so the CLI's live waiter must stay
-    // pending — a blanket invalidateLeafHandle would reject it here as stale.
+    // The shared handle belongs to leaf-new now, so the CLI's live waiter must stay pending (a blanket invalidateLeafHandle would reject it as stale).
     expect(settled).toBeNull()
     // The same handle still resolves to the live PTY under the new leaf.
     await expect(runtime.showTerminal(sharedHandle)).resolves.toMatchObject({
@@ -2468,8 +2444,7 @@ describe('OrcaRuntimeService', () => {
         tabs: { type: string; terminal?: string | null }[]
       }
     }
-    // Two unclaimed live PTYs on the worktree; the worktree-only fallback binds
-    // either to a leafless tab that references it.
+    // Two unclaimed live PTYs on the worktree; the worktree-only fallback binds either to a leafless tab that references it.
     internals.recordPtyWorktree('pty-shared', TEST_WORKTREE_ID, { connected: true })
     internals.recordPtyWorktree('pty-other', TEST_WORKTREE_ID, { connected: true })
 
@@ -2483,8 +2458,7 @@ describe('OrcaRuntimeService', () => {
       isActive: leafId === 'leaf-new'
     })
 
-    // Two records (a stale headless leaf + the live leaf) that both resolve to
-    // the SAME live PTY — the renderer-graph origin the leaf fix can't reach.
+    // Two records (stale headless leaf + live leaf) both resolve to the SAME live PTY — the renderer-graph origin the leaf fix can't reach.
     internals.mobileSessionTabsByWorktree.set(TEST_WORKTREE_ID, {
       worktree: TEST_WORKTREE_ID,
       publicationEpoch: 'renderer:test:1',
@@ -4901,9 +4875,7 @@ describe('OrcaRuntimeService', () => {
         startup: { command: 'claude' }
       })
 
-      // Why: runtime now provisions setup itself (fire-and-forget) and omits it
-      // from the RPC result so the caller does not double-spawn. The async spawn
-      // means we wait for both the agent and setup PTYs before asserting.
+      // Why: runtime provisions setup itself (fire-and-forget) and omits it from the RPC result so the caller doesn't double-spawn.
       expect(result.setup).toBeUndefined()
       await vi.waitFor(() => expect(spawn).toHaveBeenCalledTimes(2))
       expect(spawn).toHaveBeenNthCalledWith(
@@ -6434,8 +6406,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('does not hijack a legacy SSH repo at the same path into a runtime host', async () => {
-    // A legacy SSH repo resolves to `ssh:<connectionId>` even with a null executionHostId,
-    // so a same-path runtime import must create a new repo instead of adopting it.
+    // A legacy SSH repo resolves to `ssh:<connectionId>` even with null executionHostId, so a same-path runtime import creates a new repo instead of adopting it.
     const repos: Record<string, unknown>[] = [
       {
         id: 'repo-ssh-1',
@@ -6476,9 +6447,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('only a runtime host adopts an unstamped repo; local/ssh imports never stamp it', async () => {
-    // A genuine local repo is indistinguishable from a legacy runtime repo (both have null
-    // executionHostId and connectionId). Only a runtime host may backfill it — a local or ssh
-    // import at the same path must leave it untouched rather than re-attribute it to that host.
+    // Local and legacy runtime repos both have null executionHostId/connectionId, so only a runtime host may backfill; local/ssh imports leave it untouched.
     for (const importHostId of ['local', 'ssh:ssh-target-9'] as const) {
       const repos: Record<string, unknown>[] = [
         {
@@ -7228,9 +7197,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('resolves tui-idle when a completion title is coalesced with the next working title', async () => {
-    // Why: node-pty + the main batch window can coalesce "task done" and the
-    // next task's working title into one chunk. A last-title reader never
-    // sees the intermediate idle and the waiter hangs (issue #1083 class).
+    // Why: batching can coalesce "task done" + next working title into one chunk; a last-title reader misses the idle and hangs (#1083 class).
     const runtime = createRuntime()
     syncSinglePty(runtime)
     runtime.onPtyData('pty-1', '\x1b]0;Codex working\x07', 100)
@@ -7262,8 +7229,7 @@ describe('OrcaRuntimeService', () => {
     runtime.markGraphReady(1)
 
     runtime.onPtyData(ptyId, '\x1b]0;⠋ Cursor Agent\x07', 100)
-    // cursor-agent re-emits its bare native title on internal redraws while
-    // still working; it must not stomp the synthesized working title.
+    // cursor-agent re-emits its bare native title on internal redraws while still working; it must not stomp the synthesized working title.
     runtime.onPtyData(ptyId, '\x1b]0;Cursor Agent\x07', 101)
 
     expect((await runtime.listTerminals()).terminals[0]).toMatchObject({
@@ -7321,8 +7287,7 @@ describe('OrcaRuntimeService', () => {
 
       await vi.advanceTimersByTimeAsync(4_000)
 
-      // The dead session keeps its factual last title — the disposed tracker's
-      // stale-title rewrite must not fire into the retained record.
+      // The dead session keeps its factual last title; the disposed tracker's stale-title rewrite must not fire into the retained record.
       expect((await runtime.listTerminals()).terminals[0]).toMatchObject({
         title: 'Codex working'
       })
@@ -7447,8 +7412,7 @@ describe('OrcaRuntimeService', () => {
       const { runtime, batches } = createSideEffectRuntime()
       syncSinglePty(runtime)
 
-      // Plain output, a BEL-terminated non-title OSC split across chunks, and
-      // an Orca status payload: none of these is a title/bell/agent fact.
+      // Plain output, a BEL-terminated non-title OSC split across chunks, and an Orca status payload — none is a title/bell/agent fact.
       runtime.onPtyData('pty-1', 'plain output\r\n', 100)
       runtime.onPtyData('pty-1', '\x1b]7;file://host', 101)
       runtime.onPtyData('pty-1', '/tmp\x07', 102)
@@ -7469,10 +7433,7 @@ describe('OrcaRuntimeService', () => {
 
         await vi.advanceTimersByTimeAsync(3_000)
 
-        // Timer facts fire outside a chunk, so each emits immediately —
-        // still strictly ordered per PTY. They carry staleWorkingTitleClear:
-        // the renderer must clear state without scheduling a task-complete
-        // notification main's unthrottled timer did not earn.
+        // staleWorkingTitleClear tells the renderer to clear state without scheduling a task-complete notification the unthrottled timer didn't earn.
         expect(batches.flatMap((batch) => batch.facts)).toEqual([
           {
             kind: 'title',
@@ -7496,12 +7457,10 @@ describe('OrcaRuntimeService', () => {
       expect(batches).toHaveLength(1)
       expect(batches[0].facts).toEqual([
         { kind: 'title', normalizedTitle: '⠋ Cursor Agent', rawTitle: '⠋ Cursor Agent' },
-        // The synthesized spinner classifies as working — agent facts derive
-        // from synthetic frames the same as from real bytes.
+        // Synthesized spinner classifies as working — agent facts derive from synthetic frames the same as from real bytes.
         { kind: 'agent-working' }
       ])
-      // Synthetic frames are fabricated by main: they must not advance the
-      // metered output sequence the renderer ACK budget is based on.
+      // Synthetic frames are fabricated by main, so they must not advance the metered output sequence the renderer ACK budget uses.
       expect(runtime.getPtyOutputSequence('pty-1')).toBe(0)
     })
 
@@ -7713,8 +7672,7 @@ describe('OrcaRuntimeService', () => {
     })
 
     it('emits 2031-subscribe facts across chunk splits', () => {
-      // Why: hidden-delivery-gated views never receive the bytes — this fact
-      // is their only signal to send the DECSET 2031 color-scheme reply.
+      // Why: hidden-delivery-gated views never get the bytes, so this fact is their only cue to send the DECSET 2031 color-scheme reply.
       const { runtime, batches } = createSideEffectRuntime()
       syncSinglePty(runtime)
 
@@ -7731,8 +7689,7 @@ describe('OrcaRuntimeService', () => {
         data: 'visible content',
         cols: 80,
         rows: 24,
-        // The renderer xterm never saw the synthetic frame (it no longer
-        // rides pty:data), so its serializer reports a stale title.
+        // Renderer xterm never saw the synthetic frame (no longer rides pty:data), so its serializer reports a stale title.
         lastTitle: 'stale shell title'
       })
       runtime.setPtyController({
@@ -8069,8 +8026,7 @@ describe('OrcaRuntimeService', () => {
       syncSinglePty(runtime)
 
       runtime.onPtyData('pty-1', '\x1b]0;Codex working\x07real output\r\n', 100)
-      // The hook-driven idle frame lands only in main's tracker — the
-      // emulator never sees fabricated bytes (invariant 5).
+      // Hook-driven idle frame lands only in main's tracker; the emulator never sees fabricated bytes (invariant 5).
       runtime.ingestSyntheticTitleFrame('pty-1', '\x1b]0;Codex ready\x07')
 
       const snapshot = await runtime.serializeMainTerminalBuffer('pty-1', { scrollbackRows: 10 })
@@ -8097,8 +8053,7 @@ describe('OrcaRuntimeService', () => {
       syncSinglePty(runtime)
 
       runtime.onPtyData('pty-1', 'plain output\n', 100)
-      // Simulate a record title restored by a path that bypassed the tracker
-      // (the tracker itself refuses to store the bare native title).
+      // Simulate a record title restored by a path that bypassed the tracker (which itself refuses to store the bare native title).
       const records = (
         runtime as unknown as {
           ptysById: Map<string, { lastOscTitle: string | null }>
@@ -8146,8 +8101,7 @@ describe('OrcaRuntimeService', () => {
       expect(batches[0].facts).toEqual([
         { kind: 'title', normalizedTitle: 'Codex working', rawTitle: 'Codex working' }
       ])
-      // The next chunk's batch carries only its own facts (the throw aborted
-      // the first chunk's agent-tracker pass, so no working state was kept).
+      // Next chunk's batch carries only its own facts: the throw aborted the first chunk's tracker pass, so no working state kept.
       expect(batches[1].seq).toBeGreaterThan(batches[0].seq)
       expect(batches[1].facts).toEqual([
         { kind: 'title', normalizedTitle: 'Codex done', rawTitle: 'Codex done' }
@@ -8218,16 +8172,14 @@ describe('OrcaRuntimeService', () => {
       })
       syncSinglePty(runtime)
 
-      // First live chunk creates the tracker cold and kicks off hydration;
-      // the snapshot seed must land in the already-created tracker.
+      // First live chunk creates the tracker cold and kicks off hydration; the snapshot seed must land in that tracker.
       runtime.onPtyData('pty-1', 'plain output without a title\n', 100)
       await runtime.serializeMainTerminalBuffer('pty-1', { scrollbackRows: 10 })
       batches.length = 0
 
       runtime.onPtyData('pty-1', '\x1b]0;Codex done\x07', 101)
 
-      // Without the seed the tracker never saw 'working', so this idle title
-      // could not produce a completion fact.
+      // Without the seed the tracker never saw 'working', so this idle title could not produce a completion fact.
       expect(batches.flatMap((batch) => batch.facts)).toContainEqual({
         kind: 'agent-idle',
         title: 'Codex done'
@@ -8316,8 +8268,7 @@ describe('OrcaRuntimeService', () => {
       const { runtime, batches } = createSideEffectRuntime()
       syncSinglePty(runtime)
 
-      // Mirrors the renderer detector's startupCommand fast-arm: no banner
-      // needed when main saw the launch command at spawn time.
+      // Mirrors the renderer detector's startupCommand fast-arm: no banner needed when main saw the launch command at spawn.
       runtime.noteTerminalSpawnCommand('pty-1', 'command-code --trust')
       runtime.onPtyData('pty-1', '❯ Fix the spinner\r\n✻ Thinking...', 100)
 
@@ -8333,8 +8284,7 @@ describe('OrcaRuntimeService', () => {
         data: 'renderer scrollback\n',
         cols: 80,
         rows: 24,
-        // The renderer xterm never saw the synthetic hook frame (it no longer
-        // rides pty:data), so its serializer reports the pre-agent title.
+        // Renderer xterm never saw the synthetic hook frame (no longer rides pty:data), so its serializer reports the pre-agent title.
         lastTitle: 'stale shell title'
       })
       runtime.setPtyController({
@@ -8348,16 +8298,14 @@ describe('OrcaRuntimeService', () => {
       syncSinglePty(runtime)
 
       runtime.ingestSyntheticTitleFrame('pty-1', '\x1b]0;⠋ Claude working\x07')
-      // First live chunk kicks off renderer hydration; awaiting the snapshot
-      // below settles the seed write chain.
+      // First live chunk kicks off renderer hydration; awaiting the snapshot below settles the seed write chain.
       runtime.onPtyData('pty-1', 'plain output\n', 100)
       await runtime.serializeMainTerminalBuffer('pty-1', { scrollbackRows: 10 })
 
       const leaves = (
         runtime as unknown as { leaves: Map<string, { lastOscTitle: string | null }> }
       ).leaves
-      // The seed must not stomp the leaf record (worktree ps status source)
-      // back to the renderer's stale title.
+      // The seed must not stomp the leaf record (worktree ps status source) back to the renderer's stale title.
       expect([...leaves.values()][0]?.lastOscTitle).toBe('⠋ Claude working')
     })
   })
@@ -8635,8 +8583,7 @@ describe('OrcaRuntimeService', () => {
       rows: 30,
       seq: 17,
       source: 'headless',
-      // Non-alt-screen buffer reports alternateScreen=false so the renderer
-      // keeps its destructive scrollback clear on restore.
+      // Non-alt-screen reports alternateScreen=false so the renderer keeps its destructive scrollback clear on restore.
       alternateScreen: false
     })
     expect(serializeBuffer).not.toHaveBeenCalled()
@@ -10251,10 +10198,7 @@ describe('OrcaRuntimeService', () => {
     })
     expect(result.handle).toMatch(/^term_/)
     expect(createTerminal).not.toHaveBeenCalled()
-    // Why: hook-based agent status keys off `${tabId}:${leafId}`, so main must
-    // pre-allocate the tabId and stamp ORCA_PANE_KEY/TAB_ID/WORKTREE_ID into
-    // the PTY env before spawn. The same tabId is then handed to the renderer
-    // via `revealTerminalSession` so adoption preserves attribution.
+    // Why: agent status keys off `${tabId}:${leafId}`; main pre-allocates the tabId, env-stamps it before spawn, and reuses it for adoption.
     const spawnCall = spawn.mock.calls[0]?.[0] as { env?: Record<string, string> } | undefined
     const spawnedEnv = spawnCall?.env ?? {}
     expectStablePaneKeyEnv(spawnedEnv)
@@ -11300,10 +11244,7 @@ describe('OrcaRuntimeService', () => {
       splitDirection: 'vertical'
     })
 
-    // Why: regression for "Split Right renders as a down split". The published
-    // mobile-session snapshot must carry the requested direction on EVERY
-    // sibling surface — the client picks one surface's parentLayout to render
-    // the whole tab, so a stale single-leaf sibling would flip the orientation.
+    // Why: client renders the tab from one sibling's parentLayout, so all siblings must carry the direction or Split Right flips down.
     const publishedTabs = runtime['mobileSessionTabsByWorktree'].get(TEST_WORKTREE_ID)!.tabs
     const siblingSurfaces = publishedTabs.filter(
       (tab): tab is Extract<typeof tab, { type: 'terminal' }> =>
@@ -12174,13 +12115,11 @@ describe('OrcaRuntimeService', () => {
       getForegroundProcess: async () => 'cursor-agent'
     })
     const { handle } = await runtime.createTerminal(`path:${TEST_WORKTREE_PATH}`)
-    // Cursor's dismissed trust dialog stays in the scrollback tail; the idle
-    // ready prompt after it must both clear the stale trust hit and satisfy idle.
+    // Cursor's dismissed trust dialog stays in scrollback; the later idle prompt must clear that stale hit and satisfy idle.
     runtime.onPtyData(
       'pty-bg',
       [
-        // Trust dialog body can mention "Cursor Agent" before the ready banner;
-        // lastIndexOf must pick the later banner, not this earlier hit.
+        // Trust dialog mentions "Cursor Agent" before the ready banner; lastIndexOf must pick the later banner, not this hit.
         'Cursor Agent\n',
         '⚠ Workspace Trust Required\n',
         'Do you trust the contents of this directory?\n',
@@ -12224,8 +12163,7 @@ describe('OrcaRuntimeService', () => {
       Date.now()
     )
 
-    // Busy Cursor is neither blocked nor idle: the wait must keep polling, then
-    // time out honestly rather than return a stale trust block.
+    // Busy Cursor is neither blocked nor idle, so the wait times out honestly instead of returning a stale trust block.
     await expect(
       runtime.waitForTerminal(handle, { condition: 'tui-idle', timeoutMs: 200 })
     ).rejects.toThrow('timeout')
@@ -12651,9 +12589,7 @@ describe('OrcaRuntimeService', () => {
       tabId: 'tab-adopted',
       worktreeId: TEST_WORKTREE_ID
     })
-    // Why: createTerminal first reveal stamps activate/tabId; the focus reveal
-    // is the second call and must reuse that pre-minted tabId so a retry after
-    // an earlier reveal failure still adopts under the paneKey baked into env.
+    // Why: focus reveal must reuse createTerminal's pre-minted tabId so a retry adopts under the paneKey baked into env.
     expect(revealTerminalSession).toHaveBeenLastCalledWith(TEST_WORKTREE_ID, {
       ptyId: 'pty-bg',
       title: 'worker',
@@ -12955,9 +12891,7 @@ describe('OrcaRuntimeService', () => {
 
     runtime.onPtyData('pty-1', 'lo', 101)
 
-    // Cursor-based reads exclude partial lines to prevent duplication:
-    // without this, the consumer would see "hello" now as a partial, then
-    // see "hello" again as a completed line on the next read.
+    // Cursor reads exclude partial lines to prevent duplication (partial now, then completed line next read).
     const secondRead = await runtime.readTerminal(terminal.handle, {
       cursor: Number(firstRead.nextCursor)
     })
@@ -13062,9 +12996,7 @@ describe('OrcaRuntimeService', () => {
     expect(futureCursorRead.limited).toBe(false)
   })
 
-  // Why: PR #2553 fixed Orca CLI terminal reads so older retained output stays
-  // reachable by cursor; this guards that pagination without allowing previews
-  // to regress into full-transcript RPC payloads.
+  // Why: PR #2553 keeps retained output cursor-reachable while previews stay bounded (not full-transcript payloads).
   it('keeps terminal read payloads bounded while retained output remains pageable', async () => {
     const runtime = new OrcaRuntimeService(store)
     syncSinglePty(runtime)
@@ -13114,8 +13046,7 @@ describe('OrcaRuntimeService', () => {
     const [terminal] = (await runtime.listTerminals()).terminals
     const lines = Array.from({ length: 120 }, (_, index) => `line-${index}-${'x'.repeat(400)}`)
     runtime.onPtyData('pty-1', `${lines.join('\n')}\n`, 100)
-    // Why: xterm-headless uses Array.shift internally while draining writes;
-    // this test guards read-preview trimming, not emulator parsing.
+    // Why: xterm-headless uses Array.shift while draining writes; this test guards read-preview trimming, not emulator parsing.
     await runtime.serializeMainTerminalBuffer('pty-1')
 
     const originalShift = Array.prototype.shift
@@ -13873,8 +13804,7 @@ describe('OrcaRuntimeService', () => {
     const elapsed = performance.now() - start
 
     expect(candidates).toEqual([])
-    // Why: the extension regex is quadratic per line; unbounded this took
-    // seconds on the main-process PTY hot path. Loose bound to avoid CI flake.
+    // Why: the extension regex is quadratic per line; unbounded it took seconds on the PTY hot path. Loose bound to avoid CI flake.
     expect(elapsed).toBeLessThan(500)
   })
 
@@ -14587,8 +14517,7 @@ describe('OrcaRuntimeService', () => {
     expect(pty?.lastOscTitle).toBe('⠋ Grok')
     expect(pty?.lastAgentStatus).toBe('working')
 
-    // A different rotating frame must store an identical title — title
-    // equality is what stops per-frame session-tab and mobile-snapshot touch.
+    // A different rotating frame must store an identical title — title equality is what stops per-frame session-tab and mobile-snapshot touch.
     runtime.onPtyData('pty-1', '\x1b]0;⠴ - Thinking - grok\x07', 101)
     expect(pty?.lastOscTitle).toBe('⠋ Grok')
     expect(pty?.lastAgentStatus).toBe('working')
@@ -14629,9 +14558,7 @@ describe('OrcaRuntimeService', () => {
     unsubscribe()
   })
 
-  // #7970: on a headless serve there is no renderer syncing tab.agentStatus, so
-  // hook-only transitions must republish the PTY-backed snapshot themselves and
-  // the snapshot must carry the retained hook payload, not just title evidence.
+  // #7970: headless serve has no renderer syncing tab.agentStatus, so hook-only transitions must republish the snapshot carrying the retained hook payload.
   it('republishes mobile session tabs with hook payloads for title-less OSC 9999 transitions', async () => {
     const spawn = vi.fn().mockResolvedValue({ id: 'hook-only-pty' })
     const runtime = new OrcaRuntimeService(store)
@@ -14736,8 +14663,7 @@ describe('OrcaRuntimeService', () => {
       '\x1b]9999;{"state":"working","prompt":"long task","agentType":"codex"}\x07',
       100
     )
-    // Agent exits without a hook done event; the shell takes the title back.
-    // The stuck-spinner guard (#1437) must win over the retained hook row.
+    // Agent exits without a hook done event and the shell takes the title back; the stuck-spinner guard (#1437) must win over the retained hook row.
     runtime.onPtyData('hook-exit-pty', '\x1b]0;zsh\x07', 101)
 
     await waitForMobileSessionTabsEvents(events, 1)
@@ -14760,8 +14686,7 @@ describe('OrcaRuntimeService', () => {
     ).ptysById.get('pty-1')
     expect(pty?.lastOscTitle).toBe('Pi')
     expect(pty?.lastAgentStatus).toBe('idle')
-    // Why: worktree.ps / mobile re-detect from stored lastOscTitle, not the
-    // raw OSC frame. Bare "Pi" must still classify as idle after normalize.
+    // Why: worktree.ps / mobile re-detect from stored lastOscTitle, not the raw OSC frame; bare "Pi" must still classify as idle after normalize.
     expect(detectAgentStatusFromTitle(pty?.lastOscTitle ?? '')).toBe('idle')
   })
 
@@ -14780,8 +14705,7 @@ describe('OrcaRuntimeService', () => {
       }
     ).ptysById.get('pty-1')
     expect(pty?.lastOscTitle).toBe('⠋ Grok')
-    // Seed writes leaf status only; re-detect from the stored title must still
-    // report working so later live frames compare equal and do not thrash.
+    // Seed writes leaf status only; re-detect from the stored title must still report working so later live frames compare equal and don't thrash.
     expect(detectAgentStatusFromTitle(pty?.lastOscTitle ?? '')).toBe('working')
 
     ;(
@@ -14945,16 +14869,11 @@ describe('OrcaRuntimeService', () => {
       runtime.deliverPendingMessagesForHandle(terminal.handle)
 
       expect(write).toHaveBeenCalledWith('pty-1', expect.stringContaining('Subject: hello'))
-      // Why: the split Enter write lands after the 500ms delay, so we advance
-      // past it before asserting on delivered_at.
+      // Why: the split Enter write lands after the 500ms delay; advance past it before asserting on delivered_at.
       await vi.advanceTimersByTimeAsync(500)
       expect(write).toHaveBeenCalledWith('pty-1', '\r')
 
-      // Why: design doc §3.2 splits delivered vs. read — push-on-idle stamps
-      // `delivered_at` but must *not* flip `read`, since only the check caller
-      // (the agent) is authorized to consume messages from its queue. The
-      // injected banner is a courtesy; the rows stay unread so the agent can
-      // still observe them via `check` and resolve the consumption race.
+      // Why: design doc §3.2 splits delivered vs. read — push-on-idle stamps delivered_at but must not flip read; only the agent's check consumes, so rows stay unread.
       const unread = db.getUnreadMessages(terminal.handle)
       expect(unread).toHaveLength(1)
       expect(unread[0].read).toBe(0)
@@ -15039,9 +14958,7 @@ describe('OrcaRuntimeService', () => {
       )
       expect(submitWrites).toHaveLength(0)
 
-      // Why: Cursor Agent treats injected PTY text as editable prompt input.
-      // The user must submit it manually, but the banner should not replay on
-      // the next idle transition.
+      // Why: Cursor Agent treats injected PTY text as editable prompt input, so the user submits manually but the banner must not replay on the next idle transition.
       const unread = db.getUnreadMessages(terminal.handle)
       expect(unread).toHaveLength(1)
       expect(unread[0].read).toBe(0)
@@ -15109,9 +15026,7 @@ describe('OrcaRuntimeService', () => {
       ).length
       expect(firstInjections).toBe(1)
 
-      // Second idle transition: the row is still unread (no check caller has
-      // consumed it), but it has been delivered. Push-on-idle must skip it to
-      // avoid the replay bug.
+      // Second idle transition: the row is unread but already delivered, so push-on-idle must skip it to avoid the replay bug.
       runtime.deliverPendingMessagesForHandle(terminal.handle)
       await vi.advanceTimersByTimeAsync(500)
 
@@ -16847,9 +16762,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('skips the foreground-process probe when the PTY launch agent is already known', async () => {
-    // Why: foregroundAgent is only the owner fallback when launchAgent is unknown,
-    // so probing a launched agent (e.g. omp) would burn a relay round-trip on every
-    // status transition without ever changing the resolved owner.
+    // Why: foregroundAgent is only a fallback when launchAgent is unknown, so probing a launched agent burns a relay round-trip without changing the resolved owner.
     const getForegroundProcess = vi.fn(async () => 'omp')
     const runtime = new OrcaRuntimeService(store)
     runtime.setPtyController({
@@ -16881,8 +16794,7 @@ describe('OrcaRuntimeService', () => {
       getForegroundProcess
     })
     syncSinglePty(runtime, 'pty-bg')
-    // Why: each probe dedups while in-flight, so settle it before the next frame
-    // to prove the gate (not the dedup) is what suppresses extra probes.
+    // Why: each probe dedups while in-flight; settle it before the next frame to prove the gate, not the dedup, suppresses extra probes.
     const settleProbe = (): Promise<void> => new Promise((resolve) => setImmediate(resolve))
 
     // Two working frames (spinner churn) collapse to a single status transition.
@@ -17322,8 +17234,7 @@ describe('OrcaRuntimeService', () => {
         title: 'claude agents'
       })
     )
-    // The stale "working" status is suppressed (no spinner), but agent identity
-    // is retained so native chat can still address the idle agent's transcript.
+    // Stale "working" status is suppressed (no spinner), but agent identity is retained so native chat can still address the idle agent's transcript.
     const suppressed = result.tabs[0]
     expect(suppressed?.type === 'terminal' && suppressed.agentStatus?.state).toBe('done')
     expect(suppressed?.type === 'terminal' && suppressed.agentStatus?.agentType).toBe('claude')
@@ -18199,8 +18110,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('wakes slept agents on the host renderer when a phone activates a worktree', async () => {
-    // Seed isUnread:false so the unread-clear branch stays quiet and the
-    // assertions isolate the mobile slept-agent wake.
+    // Seed isUnread:false so the unread-clear branch stays quiet, isolating the mobile slept-agent wake.
     const metaById: Record<string, WorktreeMeta> = {
       [TEST_WORKTREE_ID]: makeWorktreeMeta({ isUnread: false })
     }
@@ -18243,8 +18153,7 @@ describe('OrcaRuntimeService', () => {
       terminalFitOverrideChanged: vi.fn(),
       terminalDriverChanged: vi.fn()
     })
-    // A renderer must be attached to receive the wake — headless serve reports
-    // the explicit 'unsupported-headless' outcome instead (see below).
+    // A renderer must be attached to receive the wake; headless serve reports 'unsupported-headless' instead.
     electronMocks.BrowserWindow.fromId.mockReturnValue({ isDestroyed: () => false } as never)
     runtime.attachWindow(TEST_WINDOW_ID)
     runtime.markGraphReady(TEST_WINDOW_ID)
@@ -18254,17 +18163,14 @@ describe('OrcaRuntimeService', () => {
       clientKind: 'mobile'
     })
 
-    // INV-2: mobile wake never navigates the desktop (no activateWorktree); it
-    // routes exclusively through the renderer's own navigation-free wake.
+    // INV-2: mobile wake never navigates the desktop (no activateWorktree); it routes through the renderer's navigation-free wake.
     expect(resumeSleepingAgents).toHaveBeenCalledWith(TEST_WORKTREE_ID)
     expect(activateWorktree).not.toHaveBeenCalled()
     expect(result.sleepingAgentWake).toBe('requested')
   })
 
   it('reports the wake as unsupported when a phone activates a worktree on headless serve', async () => {
-    // Why: without an attached renderer nothing holds the sleeping records, so
-    // no agent actually wakes. The result must say so explicitly — activating
-    // silently would let the phone present slept agents as resumed (#7906).
+    // Why: without a renderer nothing holds the sleeping records so nothing wakes; the result must say so or the phone shows slept agents as resumed (#7906).
     const metaById: Record<string, WorktreeMeta> = {
       [TEST_WORKTREE_ID]: makeWorktreeMeta({ isUnread: false })
     }
@@ -18307,8 +18213,7 @@ describe('OrcaRuntimeService', () => {
       terminalFitOverrideChanged: vi.fn(),
       terminalDriverChanged: vi.fn()
     })
-    // Headless/no-live-renderer: the graph is ready but no BrowserWindow backs
-    // the authoritative id, so getAvailableAuthoritativeWindow() is null.
+    // Headless: graph ready but no BrowserWindow backs the authoritative id, so getAvailableAuthoritativeWindow() is null.
     electronMocks.BrowserWindow.fromId.mockReturnValue(null as never)
     runtime.attachWindow(TEST_WINDOW_ID)
     runtime.markGraphReady(TEST_WINDOW_ID)
@@ -18320,8 +18225,7 @@ describe('OrcaRuntimeService', () => {
 
     expect(result.activated).toBe(true)
     expect(result.sleepingAgentWake).toBe('unsupported-headless')
-    // Why: sleeping records are host-partitioned; the check must read the
-    // repo's execution host partition, not always the local one.
+    // Why: sleeping records are host-partitioned; the check must read the repo's execution host partition, not always the local one.
     expect(getWorkspaceSession).toHaveBeenCalledWith('local')
     expect(resumeSleepingAgents).not.toHaveBeenCalled()
   })
@@ -18369,8 +18273,7 @@ describe('OrcaRuntimeService', () => {
     runtime.attachWindow(TEST_WINDOW_ID)
     runtime.markGraphReady(TEST_WINDOW_ID)
 
-    // INV-3: web/desktop runtime clients keep their existing wake-on-activation
-    // paths untouched — the renderer notifier wake is mobile-scoped.
+    // INV-3: web/desktop runtime clients keep their existing wake-on-activation paths; the renderer notifier wake is mobile-scoped.
     const result = await runtime.activateManagedWorktree(`id:${TEST_WORKTREE_ID}`, {
       notifyClients: false,
       clientKind: 'runtime'
@@ -18381,8 +18284,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('does not rewrite unread metadata when a mobile activation finds the worktree already read', async () => {
-    // Why: seed instanceId so worktree resolution does not emit its own
-    // metadata-stamp write, isolating the assertion to the unread clear.
+    // Why: seed instanceId so worktree resolution doesn't emit its own metadata-stamp write, isolating the assertion to the unread clear.
     const metaById: Record<string, WorktreeMeta> = {
       [TEST_WORKTREE_ID]: makeWorktreeMeta({ isUnread: false, instanceId: 'wt-instance' })
     }
@@ -19763,9 +19665,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('keeps a headless tab-group split alive when a new tab is created', async () => {
-    // Regression: drag-to-split-group was a client-only change the headless host
-    // rejected (renderer_unavailable), so creating a new tab coalesced the
-    // groups back into one. The host must model + persist the split.
+    // Regression: drag-to-split-group was client-only and the headless host rejected it, coalescing groups on new-tab; the host must model + persist the split.
     let ptyCounter = 0
     const runtime = new OrcaRuntimeService(store)
     runtime.setPtyController({
@@ -19817,8 +19717,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('restores a persisted multi-group split on a cold headless rehydrate', async () => {
-    // Regression (#1): hydrate must read back session.tabGroups/tabGroupLayouts,
-    // or a server restart coalesces the user's split into one group.
+    // Regression: hydrate must read back session.tabGroups/tabGroupLayouts, or a server restart coalesces the split into one group.
     const session = makeWorkspaceSessionWithHeadlessTerminal({
       tabsByWorktree: {
         [TEST_WORKTREE_ID]: [
@@ -20107,9 +20006,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('still persists tab props in serve mode after syncWindowGraph(0) (gate does not fire)', async () => {
-    // Why: the renderer-authoritative gate uses getAvailableAuthoritativeWindow,
-    // and serve startup calls syncWindowGraph(0,...) which sets authoritativeWindowId=0.
-    // BrowserWindow.fromId(0) is null, so the gate must NOT fire in serve mode.
+    // Why: serve's syncWindowGraph(0,...) sets authoritativeWindowId=0, but BrowserWindow.fromId(0) is null, so the renderer-authoritative gate must not fire.
     const session = makeWorkspaceSessionWithHeadlessTerminal()
     const { runtimeStore, getSession } = makeRuntimeStoreWithWorkspaceSession(session)
     const runtime = new OrcaRuntimeService(runtimeStore as never)
@@ -20165,8 +20062,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('creates a new headless terminal in the targeted split group, not the active one', async () => {
-    // Regression: a per-group "+" passes targetGroupId, but the headless create
-    // ignored it and funneled every new tab into the active group.
+    // Regression: a per-group "+" passes targetGroupId, but the headless create ignored it and funneled every new tab into the active group.
     let ptyCounter = 0
     const runtime = new OrcaRuntimeService(store)
     runtime.setPtyController({
@@ -20175,8 +20071,7 @@ describe('OrcaRuntimeService', () => {
       kill: () => true,
       getForegroundProcess: async () => null
     })
-    // Why: createMobileSessionTerminal asserts the graph is ready; serve mode
-    // marks it ready via syncWindowGraph(0,...) (windowId 0 ≠ a real renderer).
+    // Why: createMobileSessionTerminal asserts the graph is ready; serve marks it ready via syncWindowGraph(0,...) (windowId 0 ≠ a real renderer).
     runtime.syncWindowGraph(0, { tabs: [], leaves: [] })
     await runtime.createTerminal(`id:${TEST_WORKTREE_ID}`, { activate: true })
     const second = await runtime.createTerminal(`id:${TEST_WORKTREE_ID}`, { activate: true })
@@ -20222,8 +20117,7 @@ describe('OrcaRuntimeService', () => {
     expect(afterCreate.find((g) => g.id === 'right')!.tabOrder).toContain('browser-1')
     expect(afterCreate.find((g) => g.id === 'left')!.tabOrder).not.toContain('browser-1')
 
-    // Rebuild: the terminal distributor drops the browser id (terminal-only), so
-    // appendBrowserTabOrder must restore it to its prior group, not group[0].
+    // Rebuild: the terminal distributor drops the browser id, so appendBrowserTabOrder must restore it to its prior group, not group[0].
     const rebuiltGroups = [
       { id: 'left', activeTabId: 'web-terminal-a', tabOrder: ['web-terminal-a'] },
       { id: 'right', activeTabId: 'web-terminal-b', tabOrder: ['web-terminal-b'] }
@@ -20435,8 +20329,7 @@ describe('OrcaRuntimeService', () => {
       status: 'pending-handle'
     })
 
-    // Why notifyClients false: this mirrors the phone tapping the tab, which is
-    // the path that materializes pending tabs headlessly (#7587 aftermath).
+    // Why notifyClients false: mirrors the phone tapping the tab, the path that materializes pending tabs headlessly (#7587).
     const activated = await runtime.activateMobileSessionTab(
       `id:${TEST_WORKTREE_ID}`,
       `host-tab::${HEADLESS_LEAF_ID}`,
@@ -20522,8 +20415,7 @@ describe('OrcaRuntimeService', () => {
       expect.objectContaining({ sessionId: 'serve-dead-pty', worktreeId: TEST_WORKTREE_ID })
     )
     expect(spawn.mock.calls[0]![0].command).toBeUndefined()
-    // Why: the disabled-agent fallback keeps the tab's agent identity; only the
-    // startup command is skipped.
+    // Why: the disabled-agent fallback keeps the tab's agent identity; only the startup command is skipped.
     expect(activated.tabs[0]).toMatchObject({
       type: 'terminal',
       status: 'ready',
@@ -20796,8 +20688,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('durably tears down a runtime-owned SSH headless tab when renderer cleanup fails', async () => {
-    // #8958 regression: the acknowledged renderer relay cannot see headless tabs;
-    // its advisory fallback must not prevent authoritative teardown or flushing.
+    // #8958: the renderer relay can't see headless tabs, so its advisory fallback must not block authoritative teardown/flush.
     const persistedPtyId = 'ssh:ssh-1@@relay-pty'
     const { runtimeStore, getSession } = makeRuntimeStoreWithWorkspaceSession(
       makeWorkspaceSessionWithHeadlessTerminal({
@@ -20853,8 +20744,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('keeps the renderer close transaction for an adopted runtime-owned tab', async () => {
-    // The renderer pin state can be newer than the debounced workspace session.
-    // Once adopted, its live close guard must win over stale persisted metadata.
+    // The renderer pin state can be newer than the debounced session, so once adopted its live close guard must win over stale persisted metadata.
     const servePtyId = 'serve-adopted-1'
     const { runtimeStore, getSession } = makeRuntimeStoreWithWorkspaceSession(
       makeWorkspaceSessionWithHeadlessTerminal({
@@ -21098,8 +20988,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('keeps the activated headless tab active across PTY republishes (serve focus-jump regression)', async () => {
-    // Why: in `orca serve`, focusTerminal has no renderer to persist the remote
-    // client's tab choice before PTY republishes.
+    // Why: in `orca serve`, focusTerminal has no renderer to persist the remote client's tab choice before PTY republishes.
     let nextPty = 0
     const spawn = vi.fn().mockImplementation(async () => ({ id: `headless-pty-${++nextPty}` }))
     const runtime = new OrcaRuntimeService(store)
@@ -21139,8 +21028,7 @@ describe('OrcaRuntimeService', () => {
       false
     )
 
-    // PTY title updates republish snapshots, so the client's chosen tab must
-    // survive after activation.
+    // PTY title updates republish snapshots, so the client's chosen tab must survive activation.
     events.length = 0
     runtime.onPtyData('headless-pty-2', '\x1b]0;tab-other running\x07', 200)
 
@@ -21174,8 +21062,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('does not persist active server-side when an authoritative renderer is attached', async () => {
-    // Why: when a renderer window is authoritative it re-syncs the snapshot itself,
-    // so the headless persist must NOT fire — the renderer stays the source of truth.
+    // Why: an authoritative renderer re-syncs the snapshot itself, so the headless persist must not fire — the renderer stays source of truth.
     let nextPty = 0
     const spawn = vi.fn().mockImplementation(async () => ({ id: `attached-pty-${++nextPty}` }))
     const runtime = new OrcaRuntimeService(store)
@@ -21209,8 +21096,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('does not persist active server-side for a `:headless-merge:` snapshot after renderer detach', async () => {
-    // Why: after renderer detach, merged snapshots have no authoritative window
-    // but still carry renderer-owned group state.
+    // Why: after renderer detach, merged snapshots have no authoritative window but still carry renderer-owned group state.
     let nextPty = 0
     const spawn = vi.fn().mockImplementation(async () => ({ id: `merge-pty-${++nextPty}` }))
     const runtime = new OrcaRuntimeService(store)
@@ -21504,8 +21390,7 @@ describe('OrcaRuntimeService', () => {
       getForegroundProcess: async () => null,
       listProcesses: async () => []
     })
-    // Why: an attached renderer means closeTerminal exists, so the close goes
-    // down the renderer-attached path that historically leaked serve-owned tabs.
+    // Why: an attached renderer (closeTerminal exists) sends the close down the renderer-attached path that historically leaked serve-owned tabs.
     runtime.setNotifier({ closeTerminal } as never)
     runtime.syncWindowGraph(1, {
       tabs: [
@@ -21540,11 +21425,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('delegates a renderer-owned daemon-session (worktreeId@@uuid) local terminal to the renderer', async () => {
-    // Why: the daemon mints <worktreeId>@@<uuid> for ORDINARY renderer-owned
-    // local terminals too — so a tab carrying that id which the renderer graph
-    // publishes must NOT be torn down/de-persisted by the runtime; the renderer
-    // owns its teardown. (Classifying it as runtime-owned by id shape was a
-    // regression that killed/de-persisted normal local terminals.)
+    // Why: the daemon mints <worktreeId>@@<uuid> for ordinary renderer-owned terminals too, so id shape alone must not mark it runtime-owned (regression: killed normal locals).
     const daemonPtyId = `${TEST_WORKTREE_ID}@@d9213842`
     const { runtimeStore, getSession } = makeRuntimeStoreWithWorkspaceSession(
       makeWorkspaceSessionWithHeadlessTerminal({
@@ -21610,9 +21491,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('tears down a leaked daemon-session headless tab the renderer never published', async () => {
-    // Why: same <worktreeId>@@<uuid> id, but the renderer graph does NOT list it
-    // (host materialized it, renderer never showed it) — a real leak that must be
-    // de-persisted so syncMobileSessionTabs cannot re-hydrate and resurrect it.
+    // Why: same <worktreeId>@@<uuid> id but absent from the renderer graph — a real leak that must be de-persisted so syncMobileSessionTabs can't resurrect it.
     const daemonPtyId = `${TEST_WORKTREE_ID}@@77e25ca0`
     const { runtimeStore, getSession } = makeRuntimeStoreWithWorkspaceSession(
       makeWorkspaceSessionWithHeadlessTerminal({
@@ -21669,10 +21548,7 @@ describe('OrcaRuntimeService', () => {
       listProcesses: async () => []
     })
     runtime.setNotifier({ closeTerminal } as never)
-    // Renderer published a pending tab from a saved layout leaf — it is in the
-    // renderer graph but its PTY has not bound yet. The renderer owns its
-    // teardown, so the runtime must NOT de-persist/prune it from under the
-    // renderer; it just forwards the close.
+    // Pending tab in the renderer graph (PTY not bound yet) is renderer-owned, so the runtime forwards the close but must not de-persist it.
     runtime.syncWindowGraph(1, {
       tabs: [
         {
@@ -21710,8 +21586,7 @@ describe('OrcaRuntimeService', () => {
 
     expect(closeTerminal).toHaveBeenCalledWith('host-tab')
     expect(kill).not.toHaveBeenCalled()
-    // Not torn down by the runtime: the renderer-owned tab is left for the
-    // renderer's own close to prune.
+    // Not torn down by the runtime: the renderer-owned tab is left for the renderer's own close to prune.
     expect(getSession().tabsByWorktree[TEST_WORKTREE_ID]).toHaveLength(1)
     expect(getSession().terminalLayoutsByTabId['host-tab']).toBeDefined()
   })
@@ -21730,9 +21605,7 @@ describe('OrcaRuntimeService', () => {
       listProcesses: async () => []
     })
     runtime.setNotifier({ closeTerminal } as never)
-    // The renderer graph never published this parent (empty graph), so the
-    // persisted headless shell with no live PTY is runtime-owned and must be
-    // torn down authoritatively or it re-hydrates on the next publish.
+    // Empty graph → this persisted headless shell (no live PTY) is runtime-owned and must be torn down or it re-hydrates on next publish.
     runtime.syncWindowGraph(0, { tabs: [], leaves: [] })
 
     await runtime.closeMobileSessionTab(`id:${TEST_WORKTREE_ID}`, 'host-tab')
@@ -21812,8 +21685,7 @@ describe('OrcaRuntimeService', () => {
       `host-tab::${HEADLESS_SECOND_LEAF_ID}`
     )
 
-    // Exact split leaf: kill only that leaf's PTY, keep the sibling, and do not
-    // tear down / de-persist the whole parent.
+    // Exact split leaf: kill only that leaf's PTY, keep the sibling, don't tear down the parent.
     expect(kill).toHaveBeenCalledWith('serve-right')
     expect(kill).not.toHaveBeenCalledWith('serve-left')
     expect(closeTerminal).not.toHaveBeenCalled()
@@ -22398,8 +22270,7 @@ describe('OrcaRuntimeService', () => {
       activate: false,
       clientMutationId: 'mutation-lost-response'
     })
-    // Why: the phone retries with the same key when the create response was
-    // lost in transit; within the retention window it must reuse the terminal.
+    // Why: the phone retries the same key when the create response was lost; within the retention window it must reuse the terminal.
     const retried = await runtime.createMobileSessionTerminal(`id:${TEST_WORKTREE_ID}`, {
       activate: false,
       clientMutationId: 'mutation-lost-response'
@@ -22689,8 +22560,7 @@ describe('OrcaRuntimeService', () => {
         terminalFitOverrideChanged: vi.fn(),
         terminalDriverChanged: vi.fn()
       })
-      // Why: reply with a tabId but never sync a matching surface graph, so
-      // waitForMobileTerminalSurface times out and the rollback path runs.
+      // Why: reply with a tabId but never sync a surface graph, so waitForMobileTerminalSurface times out and rollback runs.
       const webContents = { send: vi.fn() }
       const send = vi.fn((_channel: string, payload: { requestId: string }) => {
         ipcMain.emit(
@@ -22724,9 +22594,7 @@ describe('OrcaRuntimeService', () => {
     }
   })
 
-  // Why: the five #7587 mobile-create tests need an identical full notifier where
-  // only closeTerminal is observed; one factory keeps notifier-interface changes
-  // in a single place.
+  // Why: the five #7587 mobile-create tests share one notifier factory so interface changes live in one place.
   function createMobileCreateTestNotifier(
     closeTerminal: (tabId: string, paneRuntimeId?: number) => void
   ) {
@@ -22752,10 +22620,7 @@ describe('OrcaRuntimeService', () => {
     try {
       const pendingLeafId = '99999999-9999-4999-8999-999999999999'
       const closeTerminal = vi.fn()
-      // Why: the renderer publishes a handle-less shell surface (no ptyId) and the
-      // runtime materialize spawn then fails, so NO live PTY ever backs the tab.
-      // The catch must roll back — the #7587 rescue is gated on a live PTY, not on
-      // the mere presence of a surface, or a dead shell would resolve as success.
+      // Why: #7587 rescue is gated on a live PTY, not on a mere surface — else this handle-less failed-spawn dead shell would resolve as success.
       const spawn = vi.fn().mockRejectedValue(new Error('spawn failed'))
       const runtime = new OrcaRuntimeService(store)
       runtime.setPtyController({
@@ -22834,9 +22699,7 @@ describe('OrcaRuntimeService', () => {
       const closeTerminal = vi.fn()
       const runtime = new OrcaRuntimeService(store)
       runtime.setNotifier(createMobileCreateTestNotifier(closeTerminal))
-      // Why: reply with a tabId but NEVER sync a matching mobileSessionTabs graph,
-      // reproducing a throttled/hidden renderer that spawns the PTY yet stalls its
-      // graph-sync publication past the surface timeout (#7587).
+      // Why: reply with a tabId but never sync a matching graph, reproducing a renderer that spawns the PTY but stalls graph-sync past the surface timeout (#7587).
       const webContents = { send: vi.fn() }
       const send = vi.fn((_channel: string, payload: { requestId: string }) => {
         ipcMain.emit(
@@ -22863,8 +22726,7 @@ describe('OrcaRuntimeService', () => {
       })
       await vi.waitFor(() => expect(send).toHaveBeenCalledTimes(1))
 
-      // A shell-only renderer snapshot can win the first race but still omit
-      // launch props. The later PTY rescue must fill the explicit mode.
+      // A shell-only snapshot can win the first race but omit launch props; the later PTY rescue must fill the explicit mode.
       runtime.syncWindowGraph(1, {
         tabs: [],
         leaves: [],
@@ -22890,8 +22752,7 @@ describe('OrcaRuntimeService', () => {
         ]
       })
 
-      // The renderer's own PTY spawn registers with the tab binding — the same
-      // call the pty IPC layer now makes — after the shell-only snapshot.
+      // The renderer's PTY spawn registers with the tab binding (as the pty IPC layer now does) after the shell-only snapshot.
       runtime.registerPty('pty-alive', TEST_WORKTREE_ID, null, {
         tabId: 'tab-alive',
         leafId
@@ -22923,10 +22784,7 @@ describe('OrcaRuntimeService', () => {
       const closeTerminal = vi.fn()
       const runtime = new OrcaRuntimeService(store)
       runtime.setNotifier(createMobileCreateTestNotifier(closeTerminal))
-      // Why: the spawn and the tabCreate reply travel independent IPC channels;
-      // here the renderer registers the live PTY before it replies, so only the
-      // create's immediate pre-wait check can resolve it — asserting it settles
-      // well under the surface timeout pins that site, not the catch backstop.
+      // Why: spawn and tabCreate reply are independent IPC channels; here the PTY registers before the reply, so the pre-wait check resolves it.
       const webContents = { send: vi.fn() }
       const send = vi.fn((_channel: string, payload: { requestId: string }) => {
         runtime.registerPty('pty-early', TEST_WORKTREE_ID, null, {
@@ -22956,8 +22814,7 @@ describe('OrcaRuntimeService', () => {
       })
       await vi.waitFor(() => expect(send).toHaveBeenCalledTimes(1))
 
-      // Resolves via the immediate pre-wait rescue, well under the 10s timeout;
-      // reverting that site would only resolve later through the catch path.
+      // Resolves via the immediate pre-wait rescue, well under the 10s timeout (not the catch path).
       await vi.advanceTimersByTimeAsync(50)
       expect(settled).toBe(true)
       const result = await settledCreate
@@ -22996,9 +22853,7 @@ describe('OrcaRuntimeService', () => {
         isDestroyed: () => false,
         webContents
       })
-      // Why: seed an inflated stored version under a stable epoch (no headless /
-      // serve-owned tabs, so the preserve-merge can't lift the version via
-      // Math.max) — this is the state prior renderer publications leave behind.
+      // Why: seed an inflated stored version under a stable epoch (the state prior renderer publications leave behind).
       runtime.syncWindowGraph(1, {
         tabs: [],
         leaves: [],
@@ -23024,9 +22879,7 @@ describe('OrcaRuntimeService', () => {
       })
       await vi.waitFor(() => expect(send).toHaveBeenCalledTimes(1))
 
-      // The renderer publishes the new tab, but with a stale (lower) version
-      // under the same epoch, so syncMobileSessionTabs rejects it and the surface
-      // never lands via graph-sync — the reporter's exact stall variant (#7587).
+      // Renderer republishes with a stale (lower) version under the same epoch, so syncMobileSessionTabs rejects it — the reporter's stall variant (#7587).
       runtime.syncWindowGraph(1, {
         tabs: [],
         leaves: [],
@@ -23089,11 +22942,7 @@ describe('OrcaRuntimeService', () => {
       const closeTerminal = vi.fn()
       const runtime = new OrcaRuntimeService(store)
       runtime.setNotifier(createMobileCreateTestNotifier(closeTerminal))
-      // Why: the renderer pane identity can reach the runtime via leaf graph-sync
-      // (recordPtyWorktree) without registerPty, and leaf-sync never calls the
-      // pty-backed rescue; so when the mobileSessionTabs publication stalls past
-      // the surface timeout, only the catch-path rescue saves the live session —
-      // this pins the third #7587 rescue site, which the other tests never reach.
+      // Why (#7587): leaf graph-sync lands identity without registerPty, so only the catch-path rescue saves the stalled live session.
       const webContents = { send: vi.fn() }
       const send = vi.fn((_channel: string, payload: { requestId: string }) => {
         ipcMain.emit(
@@ -23119,12 +22968,10 @@ describe('OrcaRuntimeService', () => {
       })
       await vi.waitFor(() => expect(send).toHaveBeenCalledTimes(1))
 
-      // Let the create clear its immediate pre-wait check (no live PTY yet) and
-      // park in waitForMobileTerminalSurface before any identity arrives.
+      // Let the create clear its pre-wait check and park in waitForMobileTerminalSurface before any identity arrives.
       await vi.advanceTimersByTimeAsync(50)
 
-      // Renderer pane identity arrives via leaf graph-sync — NOT registerPty — so
-      // no rescue fires here, and the mobileSessionTabs surface is never published.
+      // Identity arrives via leaf graph-sync, NOT registerPty, so no rescue fires and the surface is never published.
       runtime.syncWindowGraph(1, {
         tabs: [],
         leaves: [
@@ -23141,8 +22988,7 @@ describe('OrcaRuntimeService', () => {
       // Surface still unpublished, so the create is still pending.
       expect(settled).toBe(false)
 
-      // Cross MOBILE_TERMINAL_SURFACE_TIMEOUT_MS (10s): the catch path must rescue
-      // from the live PTY instead of rolling the session back destructively.
+      // Cross the 10s surface timeout: the catch path must rescue from the live PTY, not roll the session back destructively.
       await vi.advanceTimersByTimeAsync(11_000)
       const result = await settledCreate
 
@@ -23767,8 +23613,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('reads the linked-PR state from the renderer repoId-keyed GitHub cache', async () => {
-    // Regression: the renderer keys the PR cache by `repoId::branch`, so reading
-    // only by `path::branch` missed every entry and left mobile's badge muted.
+    // Regression: renderer keys the PR cache by repoId::branch; reading by path::branch missed every entry (muted mobile badge).
     const runtimeStore = {
       ...store,
       getGitHubCache: () => ({
@@ -23811,8 +23656,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('emits only instance-validated lineage parents in mobile summaries', async () => {
-    // Regression: shipped mobile clients trust parentWorktreeId without instance
-    // checks, so worktree.ps must not emit stale same-path lineage from the store.
+    // Regression: shipped mobile clients trust parentWorktreeId blindly, so worktree.ps must not emit stale same-path lineage.
     const parentPath = '/tmp/worktree-parent'
     const validChildPath = '/tmp/worktree-child-valid'
     const staleChildPath = '/tmp/worktree-child-stale'
@@ -23939,8 +23783,7 @@ describe('OrcaRuntimeService', () => {
 
       await runtime.getWorktreePs()
 
-      // Why: the cache already owns the batch-resolved platforms for its 101
-      // worktree repos; newly persisted repos must not trigger another scan.
+      // Why: the cache already owns the batch-resolved platforms; newly persisted repos must not trigger another scan.
       expect(getProjects).not.toHaveBeenCalled()
       expect(getSettings).toHaveBeenCalledTimes(1)
     })
@@ -23983,8 +23826,7 @@ describe('OrcaRuntimeService', () => {
       staleScan.resolve(MOCK_GIT_WORKTREES)
       const staleResult = await stalePoll
 
-      // Why: invalidation can let a newer scan finish first. Each result must
-      // retain the platform map computed with its own worktree generation.
+      // Why: invalidation can let a newer scan finish first; each result keeps the platform map from its own generation.
       expect(staleResult.worktrees[0]).toMatchObject({ terminalPlatform: 'linux' })
       expect(freshPoll.worktrees[0]).toMatchObject({ terminalPlatform: 'win32' })
     })
@@ -24250,8 +24092,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('attaches inline agent rows from hook-reported status (not just OSC)', async () => {
-    // Why: agent status normally arrives via hooks, not OSC terminal output;
-    // worktree.ps reads the hook snapshot so mobile surfaces those agents too.
+    // Why: agent status arrives via hooks, not OSC; worktree.ps reads the hook snapshot so mobile surfaces those agents.
     const leafId = '33333333-3333-4333-8333-333333333333'
     const paneKey = `tab-1:${leafId}`
     const now = Date.now()
@@ -24556,8 +24397,7 @@ describe('OrcaRuntimeService', () => {
     })
     const summaries = await runtime.getWorktreePs()
 
-    // Why: worktree.ps is polled; equal keys prove projected rows can share the
-    // per-request index instead of repeating compatibility path scans.
+    // Why: equal keys prove polled worktree.ps rows can share the per-request index instead of repeating path scans.
     expect(worktreePathComparison.worktreePathComparisonKey(remoteWorktree.path, 'linux')).toBe(
       worktreePathComparison.worktreePathComparisonKey(`${remoteWorktree.path}/`, 'linux')
     )
@@ -24726,8 +24566,7 @@ describe('OrcaRuntimeService', () => {
 
     expect(summaries.worktrees).toHaveLength(100)
     expect(summaries.worktrees.every((worktree) => worktree.agents?.length === 1)).toBe(true)
-    // Why: property reads make the scaling assertion mutation-sensitive without
-    // relying on a wall-clock threshold that varies across CI machines.
+    // Why: property reads make the scaling assertion mutation-sensitive without a flaky wall-clock threshold.
     expect(pathReadCount).toBeLessThan(2_000)
   })
 
@@ -24786,8 +24625,7 @@ describe('OrcaRuntimeService', () => {
     expect(summaries).toMatchObject({ totalCount: 2_000, truncated: true })
     expect(summaries.worktrees.every((worktree) => worktree.agents?.length === 0)).toBe(true)
     expect(getRepo).toHaveBeenCalledTimes(remoteWorktrees.length)
-    // Why: the prior fallback read every worktree path for every distinct miss,
-    // exceeding the three-second worktree.ps polling interval at this scale.
+    // Why: the prior fallback read every worktree path per distinct miss, exceeding the 3s worktree.ps poll interval at this scale.
     expect(pathReadCount).toBeLessThan(40_000)
   })
 
@@ -24838,8 +24676,7 @@ describe('OrcaRuntimeService', () => {
       const summaries = await runtime.getWorktreePs()
 
       expect(summaries.worktrees[0]?.agents).toEqual([])
-      // Why: resolving a relative comparison key consults cwd. A raw miss must
-      // do that once per poll, not once for every agent row carrying the ID.
+      // Why: resolving a relative comparison key consults cwd; a raw miss must do that once per poll, not per agent row.
       expect(cwdSpy.mock.calls.length).toBeLessThan(50)
     } finally {
       cwdSpy.mockRestore()
@@ -24995,10 +24832,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('clears stale working status after the agent exits and the shell takes over the title', async () => {
-    // Why: regression test for issue #1437 — the mobile worktree-list spinner
-    // kept playing forever because lastAgentStatus was sticky on 'working'
-    // once an agent exited without emitting an idle/agent-shaped final OSC
-    // title. worktree.ps must recompute from the live OSC title each call.
+    // Why (#1437): sticky lastAgentStatus left the spinner on 'working' after agent exit; recompute from the live OSC title each call.
     const runtime = new OrcaRuntimeService(store)
 
     runtime.attachWindow(1)
@@ -25027,8 +24861,7 @@ describe('OrcaRuntimeService', () => {
     const working = await runtime.getWorktreePs()
     expect(working.worktrees[0].status).toBe('working')
 
-    // Agent exits, shell title takes over — desktop's getWorktreeStatus would
-    // immediately flip back to 'active'. Mobile must do the same.
+    // Agent exits, shell title takes over — mobile must flip to 'active' like desktop's getWorktreeStatus.
     runtime.onPtyData('pty-1', '\x1b]0;bash\x07', 200)
     const afterExit = await runtime.getWorktreePs()
     expect(afterExit.worktrees[0].status).toBe('active')
@@ -28095,9 +27928,7 @@ describe('OrcaRuntimeService', () => {
       expect.objectContaining({
         cwd: '/tmp/workspaces/runtime-hook-skip',
         command: 'bash /tmp/repo/.git/orca/setup-runner.sh',
-        // Why: createTerminal stamps ORCA_PANE_KEY/TAB_ID/WORKTREE_ID into the
-        // PTY env on top of the caller-supplied env so hook-based agent status
-        // can attribute hook events to a stable pane.
+        // Why: createTerminal stamps ORCA_PANE_KEY/TAB_ID/WORKTREE_ID so hook-based agent status can attribute events to a stable pane.
         env: expect.objectContaining({
           ORCA_ROOT_PATH: '/tmp/repo',
           ORCA_WORKTREE_PATH: '/tmp/workspaces/runtime-hook-skip',
@@ -28198,9 +28029,7 @@ describe('OrcaRuntimeService', () => {
 
     expect(createSetupRunnerScript).toHaveBeenCalled()
     expect(runHook).not.toHaveBeenCalled()
-    // Why: runtime now provisions setup fire-and-forget, so the setup PTY spawns
-    // on a later tick. The wait-for-setup guarantee is enforced by the shell
-    // nonce/marker in the wrapped commands below, not by JS spawn ordering.
+    // Why: setup is provisioned fire-and-forget; the wait-for-setup guarantee comes from the shell nonce/marker, not JS spawn ordering.
     await vi.waitFor(() => expect(spawn).toHaveBeenCalledTimes(2))
     const startupCommand = (spawn.mock.calls[0]![0] as { command: string }).command
     const setupCommand = (spawn.mock.calls[1]![0] as { command: string }).command
@@ -30590,9 +30419,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('keeps the MR source base when the optional compare-base fetch fails', async () => {
-    // Why (#6263): a merged MR may have had its target ref deleted. A failed
-    // compare-base fetch must not abort and silently drop the worktree onto
-    // the repo default branch — keep the verified source base, drop compareBaseRef.
+    // Why (#6263): a merged MR's target ref may be deleted; a failed compare-base fetch must not drop the worktree onto the default branch.
     const localRepo = {
       id: TEST_REPO_ID,
       path: TEST_REPO_PATH,
@@ -30868,9 +30695,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('stamps createdAt alongside lastActivityAt so CLI-created worktrees get the Recent-sort grace window', async () => {
-    // Why: parity with createLocalWorktree / createRemoteWorktree. Without
-    // createdAt, ambient PTY bumps in OTHER worktrees during the few seconds
-    // after creation can push the new worktree below them in Recent sort.
+    // Why: without createdAt, ambient PTY bumps in other worktrees can push the new one below them in Recent sort.
     const runtime = new OrcaRuntimeService(store)
     runtime.setNotifier({
       worktreesChanged: vi.fn(),
@@ -30910,8 +30735,7 @@ describe('OrcaRuntimeService', () => {
     expect(result.worktree.createdAt).toBeDefined()
     expect(result.worktree.createdAt).toBeGreaterThanOrEqual(before)
     expect(result.worktree.createdAt).toBeLessThanOrEqual(after)
-    // Both fields must be stamped from the same `now` so the grace-window
-    // math (max(lastActivityAt, createdAt + GRACE_MS)) is well-defined.
+    // Both fields must share the same now so grace-window math (max(lastActivityAt, createdAt + GRACE_MS)) is well-defined.
     expect(result.worktree.createdAt).toBe(result.worktree.lastActivityAt)
   })
 
@@ -32236,9 +32060,7 @@ describe('OrcaRuntimeService', () => {
 
     await expect(runtime.removeManagedWorktree(TEST_WORKTREE_ID)).resolves.toEqual({})
 
-    // Regression (#8882): the orphan-cleanup removal path must also drop the
-    // bounded raw scan cache, or the removed worktree lingers in listings until
-    // the 30s TTL. Git tracking is now gone, so a fresh scan is empty.
+    // Regression (#8882): orphan-cleanup removal must also drop the raw scan cache, or the worktree lingers in listings until the 30s TTL.
     vi.mocked(listWorktrees).mockResolvedValue([])
     await expect(runtime.listDetectedManagedWorktrees(`id:${TEST_REPO_ID}`)).resolves.toMatchObject(
       { worktrees: [] }
@@ -32502,9 +32324,7 @@ describe('OrcaRuntimeService', () => {
   })
 
   it('invalidates the filesystem-auth cache after CLI worktree creation', async () => {
-    // Reproduces: CLI-created worktrees fail with "Access denied: unknown
-    // repository or worktree path" because the filesystem-auth cache was
-    // not invalidated, so git:branchCompare could not resolve the new path.
+    // Reproduces: stale filesystem-auth cache made git:branchCompare fail with "Access denied" for CLI-created worktree paths.
     const runtime = new OrcaRuntimeService(store)
     runtime.setNotifier({
       worktreesChanged: vi.fn(),
@@ -32724,8 +32544,7 @@ describe('OrcaRuntimeService', () => {
         switched: 0,
         browserPageId: 'page-1'
       })
-      // Bridge is unchanged — focus is delivered to the renderer via IPC
-      // (notifyRendererBrowserPaneFocus), not threaded through bridge state.
+      // Bridge is unchanged — focus is delivered to the renderer via IPC, not threaded through bridge state.
       expect(tabSwitchMock).toHaveBeenCalledWith(undefined, undefined, 'page-1')
     })
 
@@ -32931,9 +32750,7 @@ describe('OrcaRuntimeService', () => {
     })
 
     it('thunk resolves the installed provider lazily, not at construction time', async () => {
-      // Simulates the daemon adapter being installed AFTER OrcaRuntimeService
-      // construction (setLocalPtyProvider(routedAdapter) in daemon-init).
-      // A capture-at-construction refactor would break this test.
+      // Simulates the daemon adapter being installed AFTER construction; a capture-at-construction refactor would break this.
       const preDaemonProvider = createProviderStub(async () => [
         { id: '1', cwd: '/tmp', title: 'shell' },
         { id: '2', cwd: '/tmp', title: 'shell' }
@@ -33011,10 +32828,7 @@ describe('OrcaRuntimeService', () => {
       })
     }
 
-    // Why: session-tab mirrors travel as PTY handles, but client-created
-    // terminals (terminal.create) hold LEAF handles — the kind that can
-    // diverge from the pane's current PTY across reconnects. Issue one
-    // directly from the leaf record to pin the resolver semantics.
+    // Why: client-created terminals (terminal.create) hold LEAF handles that can diverge from the pane's current PTY across reconnects.
     function issueLeafHandle(runtime: OrcaRuntimeService, ptyId: string): string {
       const internals = runtime as unknown as {
         leaves: Map<string, { ptyId: string | null }>
@@ -33035,9 +32849,7 @@ describe('OrcaRuntimeService', () => {
       syncSingleTerminalGraph(runtime, 'pty-a')
       const handle = issueLeafHandle(runtime, 'pty-a')
 
-      // Simulate the pane's PTY being replaced while the remote client still
-      // holds the old handle (the record missed the swap, e.g. across a
-      // renderer graph reload that preserved live PTY records).
+      // Simulate the pane's PTY being replaced while the remote client still holds the old handle.
       const internals = runtime as unknown as {
         leaves: Map<string, { ptyId: string | null }>
       }
@@ -33059,8 +32871,7 @@ describe('OrcaRuntimeService', () => {
       syncSingleTerminalGraph(runtime, 'pty-a')
       const handle = issueLeafHandle(runtime, 'pty-a')
 
-      // Simulate the mobile pre-spawn flow: the handle record predates the
-      // PTY (ptyId null); the pane's first PTY must still resolve.
+      // Simulate the mobile pre-spawn flow: the handle record predates the PTY (ptyId null); its first PTY must still resolve.
       const internals = runtime as unknown as {
         handles: Map<string, { ptyId: string | null }>
       }
@@ -33108,9 +32919,7 @@ describe('OrcaRuntimeService', () => {
         )
         await vi.waitFor(() => expect(send).toHaveBeenCalledTimes(1))
 
-        // The client's socket dies mid-wait. The create must settle right away
-        // (not run down the 10s surface timeout) and must NOT close the tab —
-        // the renderer spawned a real terminal the host user can see.
+        // Client socket dies mid-wait: create must settle right away (not the 10s timeout) and must NOT close the tab (real terminal exists).
         abort.abort()
         await vi.advanceTimersByTimeAsync(0)
         const outcome = await settled
@@ -33156,9 +32965,7 @@ describe('OrcaRuntimeService', () => {
         )
         await vi.waitFor(() => expect(send).toHaveBeenCalledTimes(1))
 
-        // A live shell backs the tab, but its leaf id is not a terminal UUID
-        // so no pane key registers: the surface rescue can't publish it, and
-        // the surface itself never publishes (stalled renderer publication).
+        // A live shell backs the tab but its leaf id isn't a terminal UUID, so no pane key registers (stalled renderer publication).
         runtime.syncWindowGraph(1, {
           tabs: [],
           leaves: [
@@ -33176,8 +32983,7 @@ describe('OrcaRuntimeService', () => {
         await vi.advanceTimersByTimeAsync(11_000)
         const outcome = await settled
 
-        // The create still fails (nothing to return), but the timeout must not
-        // kill the live terminal — that is the "tab dies after ~10s" symptom.
+        // The create fails, but the timeout must not kill the live terminal (the "tab dies after ~10s" symptom).
         expect(outcome.ok).toBe(false)
         if (outcome.ok === false) {
           expect(outcome.error.message).toContain('Timed out')
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 112e5388bfd..fe9eb66574d 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -19470,17 +19470,14 @@ export class OrcaRuntimeService {
         return readySurface
       }
       if (opts.signal?.aborted) {
-        // Why: nobody is waiting for this create anymore; do not materialize
-        // or roll back — the renderer's own publication settles the tab.
+        // Why: nobody awaits this create anymore; don't materialize or roll back — the renderer's own publication settles the tab.
         throw new Error('client_disconnected')
       }
       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.
+      // Why: a hidden renderer can publish the tab shell before the PTY spawns; reuse the same identity so later focus adopts instead of creating another tab.
       return await this.createHeadlessMobileSessionTerminal(
         worktreeId,
         opts.activate !== false,
@@ -19498,30 +19495,21 @@ export class OrcaRuntimeService {
         }
       )
     } catch (error) {
-      // Why: publication latency (throttled/hidden renderer), not spawn failure,
-      // can trip the surface timeout. Rescue only when a live PTY actually backs
-      // the tab — gating on a surface would let a handle-less shell (or a failed
-      // materialize) resolve as success and skip the ghost-tab rollback (#7587).
+      // Why: publication latency (hidden renderer) can trip the surface timeout; rescue only when a live PTY backs the tab, else a ghost tab skips rollback (#7587).
       if (this.findLiveRegisteredPtyForRendererTab(worktreeId, reply.tabId)) {
         const rescued = this.ensurePtyBackedMobileSurfaceForRendererTab(worktreeId, reply.tabId)
         if (rescued) {
           return rescued
         }
       }
-      // Why: don't roll back when (a) the client connection died — the wait
-      // was cancelled, not the spawn — or (b) a live shell already backs the
-      // tab (its pane key may simply not be registered yet). Killing a real
-      // terminal the host user can see is the "tab dies after ~10s" bug (#7718).
+      // Why: don't roll back on a client disconnect or a live shell already backing the tab — that would kill a visible terminal ("tab dies after ~10s", #7718).
       if (
         isClientDisconnectedError(error) ||
         this.hasLiveShellForRendererTab(worktreeId, reply.tabId)
       ) {
         throw error
       }
-      // Why: the renderer created the tab but no live PTY backs it (true 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.
+      // Why: renderer made the tab but no live PTY backs it (real spawn/handle failure); roll it back so it can't linger as a ghost in mobile snapshots.
       this.notifier?.closeTerminal(reply.tabId)
       throw error
     } finally {
@@ -19563,11 +19551,9 @@ export class OrcaRuntimeService {
     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.
+    // Why: mobile may be iOS while the shell host is Windows/macOS/Linux or SSH Linux; 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.
+    // Why: SSH runs the CLI through the relay shim (plain `orca`), so the Linux-only `orca-ide` rename must not apply.
     const isRemote = workspace.repo ? repoIsRemote(workspace.repo) : repoIsRemote(workspace)
     const queuedShell = resolveLocalWindowsAgentStartupShell({
       platform,
@@ -19627,8 +19613,7 @@ export class OrcaRuntimeService {
   ): Promise<RuntimeMobileSessionCreateTerminalResult> {
     const workspace = await this.resolveTerminalWorkspaceLaunchScope(`id:${worktreeId}`)
     const cwd = this.resolveWorkspaceTerminalStartupCwd(workspace, opts.cwd)
-    // Why: SshPtyProvider treats sessionId as a relay reattach request. Only
-    // synthesize local serve ids; SSH fresh terminals must call pty.spawn.
+    // Why: SshPtyProvider treats sessionId as a relay reattach; only synthesize local serve ids so SSH fresh terminals still call pty.spawn.
     const stableSessionId =
       opts.identity?.sessionId ?? (workspace.connectionId ? undefined : `serve-${randomUUID()}`)
     const terminal = await this.createTerminal(`id:${worktreeId}`, {
@@ -19650,8 +19635,7 @@ export class OrcaRuntimeService {
           ? { 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.
+      // Why: this method publishes the authoritative snapshot below; skip the intermediate publish to avoid a wrong-group flash.
       deferMobileSessionPublish: true
     })
     const livePty = this.getLivePtyForHandle(terminal.handle)
@@ -19661,8 +19645,7 @@ export class OrcaRuntimeService {
     const parentTabId = livePty.pty.tabId ?? `pty:${livePty.pty.ptyId}`
     const leafId = parsePaneKey(livePty.pty.paneKey ?? '')?.leafId ?? randomUUID()
     if (opts.viewMode) {
-      // Why: the runtime-owned binding must survive a serve restart with the
-      // same initial mode, not fall back to a later client's local default.
+      // Why: the runtime-owned binding must survive a serve restart with the same initial mode, not a later client's local default.
       this.persistHeadlessSessionTabProps(worktreeId, parentTabId, { viewMode: opts.viewMode })
     }
     const existing = this.mobileSessionTabsByWorktree.get(worktreeId)
@@ -19710,8 +19693,7 @@ export class OrcaRuntimeService {
       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.
+      // Why: activating the new tab also focuses its group, so a "+" targeting a specific split group makes that group active too.
       activeGroupId:
         activate && opts.targetGroupId
           ? opts.targetGroupId
@@ -19725,8 +19707,7 @@ export class OrcaRuntimeService {
         existing?.tabGroups,
         opts.targetGroupId ? { tabId: parentTabId, groupId: opts.targetGroupId } : undefined
       ),
-      // Why: keep the group split geometry when a new tab is created, otherwise
-      // opening a terminal while split loses the groups' arrangement.
+      // Why: keep group split geometry on new-tab creation, else opening a terminal while split loses the arrangement.
       ...(existing?.tabGroupLayout ? { tabGroupLayout: existing.tabGroupLayout } : {}),
       tabs
     }
@@ -19773,8 +19754,7 @@ export class OrcaRuntimeService {
         cleanup()
         reject(new Error('Timed out waiting for terminal surface after creation'))
       }, timeoutMs)
-      // Why: a dead client connection cancels the wait immediately instead of
-      // running down the timeout and triggering rollback (#7718).
+      // Why: a dead client connection cancels the wait immediately instead of running down the timeout into rollback (#7718).
       const onAbort = (): void => {
         cleanup()
         reject(new Error('client_disconnected'))
@@ -19821,10 +19801,7 @@ export class OrcaRuntimeService {
     return surface
   }
 
-  // Why: for an in-flight mobile create whose surface hasn't published yet,
-  // publish it main-side from the live renderer PTY so the create doesn't wait
-  // on a stalled graph sync and destroy the session (#7587). No-op unless a
-  // matching create is pending and a live bound PTY exists; never double-inserts.
+  // Why: publish an in-flight mobile create main-side from the live PTY so it can't stall on graph sync and destroy the session (#7587).
   private ensurePtyBackedMobileSurfaceForRendererTab(
     worktreeId: string,
     tabId: string
@@ -19839,8 +19816,7 @@ export class OrcaRuntimeService {
       this.isReadyMobileTerminalSurface(existing) &&
       (pending.viewMode === undefined || existing.tab.viewMode === pending.viewMode)
     ) {
-      // Why: the renderer's ready publication already landed with the intended
-      // mode; only a pending shell still needs the main-side PTY rescue.
+      // Why: the renderer's ready publication already landed with the intended mode; only a pending shell needs the main-side rescue.
       return existing
     }
     const pty = this.findLiveRegisteredPtyForRendererTab(worktreeId, tabId)
@@ -19856,9 +19832,7 @@ export class OrcaRuntimeService {
       selectIfNoActiveTab: pending.selectIfNoActiveTab,
       ...(pending.viewMode ? { viewMode: pending.viewMode } : {})
     })
-    // Why: waitForMobileTerminalSurface's check closures are drained only inside
-    // syncWindowGraph; a main-side publish must drain them too or the pending
-    // wait won't observe the insertion (mirrors syncWindowGraph's drain).
+    // Why: check closures normally drain only inside syncWindowGraph; a main-side publish must drain them too or the pending wait misses the insertion.
     for (const cb of [...this.graphSyncCallbacks]) {
       cb()
     }
@@ -19882,9 +19856,7 @@ export class OrcaRuntimeService {
     return null
   }
 
-  // Why: rollback guard, looser than findLiveRegisteredPtyForRendererTab — a
-  // shell whose pane key hasn't registered yet can't be surface-rescued, but
-  // it is still a real terminal the create timeout must not kill (#7718).
+  // Why: looser rollback guard than findLiveRegisteredPtyForRendererTab — a shell without a registered pane key is still a real terminal the timeout must not kill (#7718).
   private hasLiveShellForRendererTab(worktreeId: string, tabId: string): boolean {
     for (const pty of this.ptysById.values()) {
       if (pty.worktreeId === worktreeId && pty.tabId === tabId && pty.connected) {
@@ -19931,24 +19903,19 @@ export class OrcaRuntimeService {
         }
       }
       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.
+      // Why: graph sync may have fired between the initial check and registration; re-check 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.
+  // Why: mobile may subscribe before the PTY spawns; wait for it so subscribe proceeds with phone-fit instead of a bare scrollback+end.
   waitForLeafPtyId(handle: string, timeoutMs = 10_000, signal?: AbortSignal): Promise<string> {
     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.
+    // Why: ptyId null→real invalidates the old handle; capture tabId+leafId now for direct leaf lookup afterward.
     const record = this.handles.get(handle)
     const savedTabId = record?.tabId ?? null
     const savedLeafId = record?.leafId ?? null
@@ -19990,8 +19957,7 @@ export class OrcaRuntimeService {
       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.
+        // Why: ptyId null→real invalidates the old handle; fall back to direct leaf lookup by saved coordinates.
         if (!ptyId && savedTabId && savedLeafId) {
           const directLeaf = this.leaves.get(this.getLeafKey(savedTabId, savedLeafId))
           ptyId = directLeaf?.ptyId ?? null
@@ -20005,8 +19971,7 @@ export class OrcaRuntimeService {
     })
   }
 
-  // Why: never-mounted tabs have no attached PTY or mobile snapshot; synthetic
-  // handles need the ptyId so the renderer can mount the exact owning tab.
+  // Why: never-mounted tabs have no PTY or snapshot; synthetic handles need the ptyId to mount the exact owning tab.
   requestRendererTerminalTabMount(handle: string): boolean {
     const record = this.handles.get(handle)
     if (!record?.worktreeId) {
@@ -20025,8 +19990,7 @@ export class OrcaRuntimeService {
       })
       return true
     } catch {
-      // No authoritative window (shutdown/headless): the subscribe keeps its
-      // existing empty-snapshot fallback.
+      // No authoritative window (shutdown/headless): subscribe keeps its empty-snapshot fallback.
       return false
     }
   }
@@ -20054,8 +20018,7 @@ export class OrcaRuntimeService {
     if (!snapshot.data) {
       return
     }
-    // Why: a redraw byte can create a suffix-only model before the restored
-    // renderer settles. Replace it with the exact snapshot already sent mobile.
+    // Why: a redraw byte can create a suffix-only model before the renderer settles; replace it with the exact snapshot already sent mobile.
     this.providerSnapshotPreferredPtys.add(ptyId)
     this.disposeHeadlessTerminal(ptyId)
     this.seedHeadlessTerminal(
@@ -20067,8 +20030,7 @@ export class OrcaRuntimeService {
     for (const chunk of trailingOutput) {
       this.trackHeadlessTerminalData(ptyId, chunk.data, chunk.seq)
     }
-    // The seed's write chain already owns subsequent live bytes; suppress the
-    // ordinary on-data hydration path from replacing this known-good seed.
+    // The seed's write chain owns subsequent live bytes; suppress on-data hydration from replacing this known-good seed.
     this.headlessHydrationState.set(ptyId, 'done')
   }
 
@@ -20084,10 +20046,7 @@ export class OrcaRuntimeService {
     )
   }
 
-  // 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.
+  // Why: a leaf exists before its PTY spawns; a handle issued while ptyId is null gets invalidated on the next sync, so wait for a connected PTY.
   private countLeavesInTab(tabId: string): number {
     let count = 0
     for (const leaf of this.leaves.values()) {
@@ -20150,13 +20109,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: in a multi-pane tab, killing the PTY is enough (renderer's exit handler closes the pane); an extra IPC close would race it and close the whole tab.
     const siblingCount = this.countLeavesInTab(leaf.tabId)
     if (!ptyKilled || siblingCount <= 1) {
       this.notifier?.closeTerminal(leaf.tabId, leaf.paneRuntimeId)
@@ -20201,8 +20154,7 @@ export class OrcaRuntimeService {
     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.
+    // Snapshot current leaf keys so the post-split graph-sync delta reveals the new pane.
     const leafKeysBefore = new Set<string>()
     for (const [key, l] of this.leaves) {
       if (l.tabId === leaf.tabId) {
@@ -20293,8 +20245,7 @@ export class OrcaRuntimeService {
         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.
+      // Why: persist the split so a later snapshot rebuild keeps it instead of collapsing to a single pane.
       this.persistHeadlessTerminalSplit({
         tabId: parentTabId,
         leafId,
@@ -20406,8 +20357,7 @@ export class OrcaRuntimeService {
       ) => Promise<{ stopped: boolean; owner: boolean }>
     } = {}
   ): 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.
+    // Why: this mutates live PTYs, so reject while the graph is reloading rather than act on cached leaf ownership.
     const graphEpoch = this.captureReadyGraphEpoch()
     const worktree = await this.resolveWorktreeSelector(worktreeSelector)
     this.assertStableReadyGraph(graphEpoch)
@@ -20474,8 +20424,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: worktree sleep needs proof of the complete live set; pane hibernation only needs its one target PTY gone.
     const graphEpoch = this.captureReadyGraphEpoch()
     const worktree = await this.resolveWorktreeSelector(worktreeSelector)
     this.assertStableReadyGraph(graphEpoch)
@@ -20595,19 +20544,14 @@ export class OrcaRuntimeService {
     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.
+    // Why: a renderer reload tears down the live graph, so live handles must go stale immediately, not be reused against the rebuild.
     this.rendererGraphEpoch += 1
     this.graphStatus = 'reloading'
     this.setTerminalSideEffectConsumerAvailable(false)
     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.
+    // Why: handleByPtyId (pre-allocated CLI handles) survives reloads so CLI agents keep control; adoptPreAllocatedHandle re-links on the new graph.
     this.rejectAllWaiters('terminal_handle_stale')
     this.refreshWritableFlags()
   }
@@ -20625,8 +20569,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: once the authoritative renderer graph disappears, fail closed for live-terminal ops instead of guessing from old state.
     if (this.graphStatus !== 'unavailable') {
       this.rendererGraphEpoch += 1
     }
@@ -20639,8 +20582,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: pre-allocated CLI handles must survive graph unavailability so they can be re-adopted on reconnect.
     this.rejectAllWaiters('terminal_handle_stale')
   }
 
@@ -20672,8 +20614,7 @@ export class OrcaRuntimeService {
       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.
+      // Why: a PTY spawns 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
@@ -20742,8 +20683,7 @@ export class OrcaRuntimeService {
       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.
+      // Why: the floating sentinel is terminal-only — no backing repo/worktree record for other workspace APIs.
       return {
         id: FLOATING_TERMINAL_WORKTREE_ID,
         path: homedir(),
@@ -20809,8 +20749,7 @@ export class OrcaRuntimeService {
       !worktreeId.includes(WORKTREE_ID_SEPARATOR) &&
       this.store?.getRepo(worktreeId)
     ) {
-      // Why: registered repo ids are known-invalid worktree ids, so reject them
-      // before exact-id fast paths or Git/SSH worktree scans can hide the mistake.
+      // Why: a registered repo id is a known-invalid worktree id; reject early before fast paths or Git/SSH scans hide the mistake.
       throw new WorktreeIdRequiresFullPathError()
     }
     return worktreeId
@@ -20844,10 +20783,7 @@ export class OrcaRuntimeService {
         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.
+        // Why: the same physical path can appear under multiple repo IDs; a path selector is exact, so take the first row over a dup-registration ambiguity.
         candidates = [candidates[0]]
       }
     } else if (selector.startsWith('branch:')) {
@@ -20856,8 +20792,7 @@ export class OrcaRuntimeService {
         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.
+      // Keep display-name matching exact so duplicate names hit the same ambiguity path as other selectors.
       candidates = worktrees.filter((worktree) => worktree.displayName === selector.slice(5))
     } else if (selector.startsWith('issue:')) {
       candidates = worktrees.filter(
@@ -21104,9 +21039,7 @@ export class OrcaRuntimeService {
         }
         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.
+        // Why: a stale terminal handle (reload/SSH reconnect) shouldn't drop lineage; keep resolving other inferred candidates.
         warnings.push({
           code: 'LINEAGE_PARENT_CONTEXT_MISSING',
           message:
@@ -21200,8 +21133,7 @@ export class OrcaRuntimeService {
   ): Promise<WorktreeLineageCandidate | null> {
     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.
+    // Why: agent-created tasks may never be dispatched, but the creating terminal still identifies the parent workspace.
     const parentHandle =
       dispatch?.assignee_handle ?? db?.getTask(taskId)?.created_by_terminal_handle
     if (!parentHandle) {
@@ -21451,8 +21383,7 @@ export class OrcaRuntimeService {
             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.
+        // Why: mobile startup shares this path, so a slow repo scan degrades one repo's metadata instead of blocking all session loading.
         const scan = await withTimeout(
           this.listRepoWorktreesForResolution(repo, projectRuntimeByRepoId),
           RESOLVED_WORKTREE_REPO_TIMEOUT_MS,
@@ -21464,8 +21395,7 @@ export class OrcaRuntimeService {
         }
         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.
+          // Why: lineage validation needs a durable instance ID even when the runtime sees a workspace before renderer discovery-stamp.
           const existingMeta = metaById[worktreeId]
           const meta =
             existingMeta && existingMeta.instanceId
@@ -21491,9 +21421,7 @@ export class OrcaRuntimeService {
       })
     )
     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.
+    // Why: short TTL avoids shelling out on every frequent poll while still catching worktree changes made outside Orca.
     if (generation === this.resolvedWorktreeGeneration) {
       this.resolvedWorktreeCache = {
         worktrees,
@@ -21519,8 +21447,7 @@ export class OrcaRuntimeService {
         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.
+        // Why: worktree IDs are path-derived, so instance checks keep replacement checkouts off stale same-path lineage.
         continue
       }
       validLineageByChildId.set(childId, lineage)
@@ -21565,9 +21492,7 @@ export class OrcaRuntimeService {
     }
     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.
+        // Why: once a scan proves the child gone, purge stale lineage so it can't survive into a same-path replacement checkout.
         store.removeWorktreeLineage(childId)
         store.removeWorkspaceLineage?.(worktreeWorkspaceKey(childId))
       }
@@ -21577,9 +21502,7 @@ export class OrcaRuntimeService {
       ) {
         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.
+          // Why: a missing parent path needs one fresh identity so same-path replacement checkouts can't validate old lineage.
           store.setWorktreeMeta(lineage.parentWorktreeId, { instanceId: randomUUID() })
         }
       }
@@ -21675,9 +21598,7 @@ export class OrcaRuntimeService {
       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.
+      // Why: mirror worktrees:list's disconnected-SSH fallback — keep persisted SSH worktrees while the provider reconnects instead of zero rows.
       byWorktreeId.set(worktreeId, {
         path: parsed.worktreePath,
         head: '',
@@ -21725,18 +21646,14 @@ export class OrcaRuntimeService {
     }
   }
 
-  /** 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. */
+  /** Invalidate the worktree cache and tell the renderer to re-list after an out-of-band branch change so the new name surfaces immediately. */
   notifyBranchRenamed(repoId: string): void {
     this.invalidateResolvedWorktreeCache()
     this.invalidateWorktreeScanCacheForRepo(repoId)
     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. */
+  /** Like {@link notifyBranchRenamed} but carries old->new worktree id so the renderer re-keys instead of treating the id change as a deletion. */
   notifyWorktreeFolderRenamed(repoId: string, oldWorktreeId: string, newWorktreeId: string): void {
     this.invalidateResolvedWorktreeCache()
     this.invalidateWorktreeScanCacheForRepo(repoId)
@@ -21822,12 +21739,10 @@ export class OrcaRuntimeService {
       if (wslDistro) {
         this.wslDistroByPtyId.set(ptyId, wslDistro)
       } else if (connectionId !== null) {
-        // Why: restored SSH IDs can collide with stale local parser state;
-        // connection ownership must win before their first output is parsed.
+        // Why: restored SSH IDs can collide with stale local parser state; connection ownership must win before their first output is parsed.
         this.wslDistroByPtyId.delete(ptyId)
       }
-      // Why: restored/controller-discovered PTYs learn their worktree here
-      // without registerPty(), so URL enrichment must bind at this source.
+      // Why: restored/controller-discovered PTYs learn their worktree here without registerPty(), so URL enrichment must bind at this source.
       advertisedUrlWatcher.bindPty(ptyId, worktreeId)
       return pty
     }
@@ -21873,8 +21788,7 @@ export class OrcaRuntimeService {
       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.
+    // Why: recordPtyWorktree is the common lifecycle point for every path that resolves a PTY's worktree (renderer restore, controller list).
     advertisedUrlWatcher.bindPty(ptyId, worktreeId)
     return pty
   }
@@ -21896,15 +21810,11 @@ export class OrcaRuntimeService {
     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.
+    // Why: daemon-backed PTY session IDs are prefixed with the worktree ID so mobile summaries survive renderer graph gaps and reloads.
     return this.recordPtyWorktree(ptyId, inferredWorktreeId)
   }
 
-  /**
-   * Synchronizes PTY tracking records with the running daemon sessions,
-   * querying their foreground agent states.
-   */
+  /** Synchronizes PTY tracking records with running daemon sessions, querying their foreground agent states. */
   private async refreshPtyWorktreeRecordsFromController(
     resolvedWorktrees: ResolvedWorktree[],
     targetWorktreeId: string | null = null
@@ -21927,8 +21837,7 @@ export class OrcaRuntimeService {
     const livePtyIds = new Set(sessions.map((session) => session.id))
     for (const session of sessions) {
       this.adoptControllerTerminalHandle(session.id, session.terminalHandle)
-      // Why: workspace identity migration rekeys persisted ownership while a
-      // running daemon PTY keeps the worktree id minted into its session id.
+      // Why: workspace identity migration rekeys persisted ownership, but a running daemon PTY keeps the worktree id minted into its session id.
       const worktreeId =
         persistedWorktreeIdByPtyId.get(session.id) ??
         inferWorktreeIdFromPtyId(session.id) ??
@@ -21941,9 +21850,7 @@ export class OrcaRuntimeService {
           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.
+      // Why: fire-and-forget so this listing hot path doesn't serialize a relay round-trip per session and a throw can't abort the sweep below.
       this.refreshPtyForegroundAgent(session.id)
     }
     for (const pty of this.ptysById.values()) {
@@ -21960,8 +21867,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: disconnected PTY records stay addressable for status/exit reads, but their transcripts must not accumulate after the process dies.
     pty.tailBuffer = []
     pty.tailTranscriptBuffer = []
     pty.tailTranscriptChars = 0
@@ -21971,9 +21877,7 @@ export class OrcaRuntimeService {
     pty.tailTruncated = false
     pty.tailLinesTotal = 0
     pty.waitBlockedAt = null
-    // Why: the tail is now empty, so the memoized wait scan must not be reused as
-    // the next chunk's "previous" state — clear it so onPtyData recomputes from
-    // the reset tail if this record resumes output (adoption/reattach).
+    // Why: tail is now empty, so clear the memoized wait scan; onPtyData must recompute from the reset tail if this record resumes output.
     pty.tailWaitState = undefined
   }
 
@@ -21983,8 +21887,7 @@ export class OrcaRuntimeService {
       .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.
+      // Why: exited runtime-owned PTYs stay readable, but long-lived runtimes churn through many sessions; bound the archive.
       this.dropDisconnectedPtyRecord(stale.ptyId)
     }
   }
@@ -22016,8 +21919,7 @@ export class OrcaRuntimeService {
     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.
+      // Why: pruning can remove a PTY without onPtyExit firing; release this leader's agent team so it doesn't leak.
       this.claudeAgentTeams.removeTeamForLeaderHandle(handle)
       this.handleByPtyId.delete(ptyId)
       const record = this.handles.get(handle)
@@ -22110,8 +22012,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: renderer graphs own renderer tabs, but headless serve terminals never enter that graph unless we preserve their bindings.
     this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(undefined, {
       allowAttachedWindow: true,
       onlyServeOwnedTerminals: true
@@ -22137,8 +22038,7 @@ export class OrcaRuntimeService {
           nextWorktrees.add(worktreeId)
         } else {
           this.mobileSessionTabsByWorktree.delete(worktreeId)
-          // Why: drop any pending coalesced notify so a stale snapshot can't
-          // land after the removed frame.
+          // Why: drop any pending coalesced notify so a stale snapshot can't land after the removed frame.
           this.mobileSessionTabsNotifyCoalescer.cancel(worktreeId)
           this.notifyMobileSessionTabsRemoved(worktreeId)
         }
@@ -22245,9 +22145,7 @@ export class OrcaRuntimeService {
     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".
+    // Why: headless offscreen browser tabs exist only server-side, so a renderer-graph merge must keep them, not prune as "not in the graph".
     if (tab.type === 'browser') {
       return (
         Boolean(this.offscreenBrowserBackend) &&
@@ -22275,8 +22173,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: preserved snapshots can merge repeatedly; strip the prior merge suffix first so the publication epoch stays idempotent.
     const normalizedPublicationEpoch = snapshot.publicationEpoch.split(':headless-merge:')[0]
     const signature = createHash('sha1')
       .update(
@@ -22316,8 +22213,7 @@ export class OrcaRuntimeService {
     }
     if (this.offscreenBrowserBackend) {
       const reconciled = this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(worktreeId)
-      // Why: hydrate already reconciles an existing snapshot in place; only
-      // reconcile here when it didn't (fresh build or an early-returned hydrate).
+      // Why: hydrate already reconciles an existing snapshot in place; only reconcile here when it didn't (fresh build or early-returned hydrate).
       if (!reconciled.has(worktreeId)) {
         const existing = this.mobileSessionTabsByWorktree.get(worktreeId)
         if (existing) {
@@ -22325,9 +22221,7 @@ export class OrcaRuntimeService {
         }
       }
     }
-    // Why: structural changes (tab add/remove/activate) must propagate promptly,
-    // so cancel any pending coalesced title/status notify — this immediate emit
-    // already reflects the latest snapshot and supersedes it.
+    // Why: structural changes must propagate promptly; cancel any pending coalesced notify since this immediate emit supersedes it.
     this.mobileSessionTabsNotifyCoalescer.cancel(worktreeId)
     this.notifyMobileSessionTabsChangedNow(worktreeId)
   }
@@ -22340,8 +22234,7 @@ export class OrcaRuntimeService {
     if (!snapshot) {
       return
     }
-    // Why: browser bridge lifecycle events are already scoped by worktree; avoid
-    // fanning out every active workspace snapshot during navigation/tab churn.
+    // Why: browser bridge events are already worktree-scoped; don't fan out every workspace snapshot during navigation/tab churn.
     const result = this.toMobileSessionTabsResult(snapshot)
     for (const listener of this.mobileSessionTabListeners) {
       listener(result)
@@ -22465,23 +22358,13 @@ export class OrcaRuntimeService {
     return first ?? second
   }
 
-  /**
-   * Transforms an internal mobile session tab snapshot into a sanitized client payload,
-   * resolving launch agent ownership and normalizing titles.
-   */
+  /** 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)
-    // Why: a live PTY backs exactly one terminal surface, so it must map to a
-    // single emitted tab. After agent sleep + mobile wake, a stale
-    // headless-hydrated leaf can survive beside the renderer's live leaf and both
-    // resolve to the freshly-woken agent PTY (same issuePtyHandle handle) — which
-    // renders two panes with the same React key and crashes the client. Claim
-    // each live PTY once. Split siblings never collide because distinct leaves own
-    // distinct PTYs; renderer tabs precede preserved headless tabs, so the live
-    // one wins.
+    // Why: a live PTY backs one surface; claim each once so two leaves resolving to it can't emit duplicate React keys and crash the client.
     const claimedLivePtyIds = new Set<string>()
     for (const tab of snapshot.tabs) {
       if (tab.type === 'browser') {
@@ -22491,15 +22374,12 @@ export class OrcaRuntimeService {
         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.
+        // Why: renderer snapshots lag BrowserView teardown/process swaps; only surface pages the browser bridge can still route 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.
+          // Why: bridge "active" means active BrowserView/webContents, not active Orca tab; preserve the renderer's session focus.
           isActive: tab.isActive
         })
         continue
@@ -22519,12 +22399,7 @@ export class OrcaRuntimeService {
             allowWorktreeOnlyMatch: !snapshot.publicationEpoch.startsWith('headless')
           })
       const livePty = pty?.connected ? pty : null
-      // Why: enforce the one-live-PTY-per-tab invariant. A later tab resolving to
-      // a PTY an earlier tab already claimed is a duplicate surface (e.g. a stale
-      // headless-hydrated leaf re-bound to a woken agent PTY) — drop it so the
-      // client never sees two tabs sharing a terminal handle. Handles derive purely
-      // from the PTY id (issuePtyHandle), so the id is a faithful proxy for the
-      // emitted handle. Pending tabs (no live PTY) are left untouched.
+      // Why: enforce one-live-PTY-per-tab; drop a later tab resolving to an already-claimed PTY so no two tabs share a handle.
       const resolvedLivePtyId = liveLeafPtyId ?? livePty?.ptyId ?? null
       if (resolvedLivePtyId !== null) {
         if (claimedLivePtyIds.has(resolvedLivePtyId)) {
@@ -22559,12 +22434,7 @@ export class OrcaRuntimeService {
       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).
+      // Why: keep rich hook status on a live prompt/tool (authoritative even under a non-agent title), else interactivePrompt is lost.
       const hasLiveAgentSignal =
         normalizedTabAgentStatus?.interactivePrompt != null ||
         normalizedTabAgentStatus?.toolName != null
@@ -22575,11 +22445,7 @@ export class OrcaRuntimeService {
           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'.
+        : // Why: idle live title → drop stale "working" (no spinner) but keep agent identity so native chat can still address the transcript.
           normalizedTabAgentStatus?.agentType != null
           ? {
               agentStatus: {
@@ -22596,8 +22462,7 @@ export class OrcaRuntimeService {
               }
             }
           : null
-      // Why: web/mobile clients hold these handles across renderer graph syncs;
-      // leaf handles are graph-epoch-bound, but PTY handles remain streamable.
+      // Why: web/mobile clients hold handles across renderer graph syncs; leaf handles are epoch-bound but PTY handles stay streamable.
       const terminalHandle = liveLeafPtyId
         ? this.issuePtyHandle(
             this.recordPtyWorktree(liveLeafPtyId, snapshot.worktree, {
@@ -22669,10 +22534,7 @@ export class OrcaRuntimeService {
     }
   }
 
-  /**
-   * Generates a mobile-friendly status entry for a PTY, aligning agentType
-   * and titles with the active owner.
-   */
+  /** Mobile-friendly status entry for a PTY, aligning agentType and titles with the active owner. */
   private buildPtyMobileAgentStatus(
     pty: RuntimePtyWorktreeRecord | null,
     tab: RuntimeMobileSessionTerminalTab,
@@ -22697,11 +22559,7 @@ export class OrcaRuntimeService {
         : null
     const ptyTitleClassification = classifyAgentTitle(ptyTitle)
     if (ptyTitle !== null && ptyTitleClassification !== 'agent') {
-      // Why: a non-agent title means the shell owns the pane again (the agent
-      // exited or was replaced) — suppressing here is what clears stuck
-      // spinners (#1437). A live hook signal (question card / active tool) is
-      // authoritative agent activity even under a task-named title, so it
-      // survives the suppression, mirroring the renderer-synced branch above.
+      // Why: non-agent title = shell reclaimed the pane; suppress to clear stuck spinners (#1437), though a live hook signal survives.
       const hasLiveHookSignal =
         retained?.payload.interactivePrompt != null || retained?.payload.toolName != null
       if (!hasLiveHookSignal) {
@@ -22713,10 +22571,7 @@ export class OrcaRuntimeService {
       (pty ? getLatestPtyTitle(pty) : null) ?? tab.title,
       ownerAgent
     )
-    // Why: hook (OSC 9999) payloads carry the real state, prompt, and agent
-    // identity; the title heuristic below is a fallback with none of that.
-    // Without this, headless-serve clients only ever saw title-derived rows
-    // and hook-only transitions (e.g. opencode waiting) never surfaced (#7970).
+    // Why: OSC 9999 hook payload carries real state/prompt/agent; without preferring it, hook-only transitions never surfaced (#7970).
     if (retained) {
       return {
         agentStatus: normalizeCompatibleAgentStatusEntryForOwner(
@@ -22761,9 +22616,7 @@ export class OrcaRuntimeService {
     }
   }
 
-  /** The retained OSC 9999 hook row for this mobile tab, when fresh enough to
-   *  trust. Looked up by pane identity first, then by PTY ownership because
-   *  legacy `pane:N` leaf ids can drift from the hook-side pane key. */
+  /** Retained OSC 9999 hook row for this mobile tab if still fresh; looked up by pane identity, then PTY ownership (legacy `pane:N` ids can drift). */
   private getFreshRetainedAgentStatusForMobileTab(
     paneKey: string,
     pty: RuntimePtyWorktreeRecord | null,
@@ -22801,8 +22654,7 @@ export class OrcaRuntimeService {
       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.
+      // Why: persisted PTY ids can collide with unrelated provider ids after restart; only a matching spawn-time pane identity is safe to expose.
       if (this.mobileTerminalTabMatchesPty(worktreeId, tab, pty, paneKey)) {
         return pty
       }
@@ -22845,8 +22697,7 @@ export class OrcaRuntimeService {
     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.
+  // Why: group address resolution (Section 4.5) queries per-handle status and must not throw on stale handles; return null on any error.
   getAgentStatusForHandle(handle: string): string | null {
     try {
       const ptyId = this.getTerminalAgentStatusPtyId(handle)
@@ -22919,9 +22770,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: active dispatch is authoritative for reused terminals; completed context stale-groups future work once its done row is gone.
     const dispatch =
       db?.getActiveDispatchForTerminal?.(handle) ??
       this.getRecentCompletedDispatchForTerminal(handle, db)
@@ -23054,10 +22903,7 @@ export class OrcaRuntimeService {
     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.
+  // Why: title is the tightest agent-presence signal, but a Claude management title is negative evidence for task activity.
   async isTerminalRunningAgent(handle: string): Promise<boolean> {
     try {
       const pty = this.getLivePtyForHandle(handle)
@@ -23066,10 +22912,7 @@ export class OrcaRuntimeService {
         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.
+      // Why: check the leaf pane title and the tab title, which already carries OSC-enriched agent indicators (e.g. ✳ prefix).
       const paneTitle = getLatestLeafTitle(leaf, null)
       const paneTitleClassification = classifyAgentTitle(paneTitle)
       if (paneTitleClassification === 'agent') {
@@ -23095,16 +22938,13 @@ export class OrcaRuntimeService {
       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.
+      // Why: Claude's management UI runs under the Claude process but isn't a task-capable session; suppress only that process.
       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.
+      // Why: review-note delivery auto-submits with Enter, so only known agent processes are safe (not arbitrary focused TUIs).
       return await this.isRecognizedForegroundAgentProcess(leaf.ptyId, fg, {
         suppressClaude: shouldSuppressClaudeForeground
       })
@@ -23143,8 +22983,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: stale status is a fallback only when no current title evidence exists; neutral titles (shells) clear it.
     if (
       pty.lastAgentStatus !== null &&
       leafTitle === null &&
@@ -23167,8 +23006,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: review-note delivery auto-submits with Enter, so only known agent processes are safe (not arbitrary focused TUIs).
     return await this.isRecognizedForegroundAgentProcess(pty.ptyId, fg, {
       suppressClaude: shouldSuppressClaudeForeground
     })
@@ -23210,9 +23048,7 @@ export class OrcaRuntimeService {
   }
 
   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.
+    // Why: daemon/SSH PTYs can report the interpreter before the async cmdline cache resolves; retry only known wrappers.
     return isAgentForegroundWrapperProcess(processName)
   }
 
@@ -23227,22 +23063,18 @@ export class OrcaRuntimeService {
         this.deliverPendingMessages(leaf)
       }
     } catch {
-      // Unknown or stale handles cannot be pushed immediately; the persisted
-      // message remains available via explicit check or future idle delivery.
+      // Unknown/stale handles can't be pushed now; the persisted message stays 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.
+  // Why: wake blocking orchestration.check --wait calls on this handle so they 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.
+      // Why: don't wake a coordinator waiting for worker_done/escalation on heartbeat noise it would misread as idleness.
       if (messageType && waiter.typeFilter && !waiter.typeFilter.includes(messageType)) {
         continue
       }
@@ -23265,10 +23097,7 @@ export class OrcaRuntimeService {
         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.
+      // Why: on caller abort (RPC socket closed — design doc §3.1), resolve now to release the long-poll slot instead of waiting out timeoutMs.
       const signal = options?.signal
       const onAbort = (): void => {
         this.removeMessageWaiter(waiter)
@@ -23373,8 +23202,7 @@ export class OrcaRuntimeService {
       )?.[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.
+        // Why: graph reload clears renderer handle records, but runtime-owned PTY handles remain the caller's control identity.
         this.issuePtyHandle(pty)
         record = this.handles.get(handle)
       }
@@ -23389,9 +23217,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: renderer adoption can race with CLI reads; keep ptyId → handle populated so summaries don't mint a second handle for the same terminal.
     this.handleByPtyId.set(record.ptyId, handle)
     return { record, pty }
   }
@@ -23561,8 +23387,7 @@ export class OrcaRuntimeService {
   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.
+        // Why: ORCA_TERMINAL_HANDLE is an agent identity, so CLI control survives renderer graph loss while the PTY is alive.
         this.detachedPreAllocatedLeaves.set(leaf.ptyId, leaf)
       }
     }
@@ -23581,9 +23406,7 @@ export class OrcaRuntimeService {
       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.
+        // Why: after exit, conditions like tui-idle can never be satisfied — reject now instead of spinning the poll until timeout on a dead process.
         this.removeWaiter(waiter)
         waiter.reject(new Error('terminal_exited'))
       }
@@ -23641,12 +23464,7 @@ export class OrcaRuntimeService {
     }
   }
 
-  // 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.
+  // Why: the primary OSC-title signal can't fire for daemon-hosted terminals (no PTY data through the runtime), so this fallback polls the renderer-synced tab title + foreground-process quiescence; self-cancels when the OSC path fires.
   private startTuiIdleFallbackPoll(waiter: TerminalWaiter, leaf: RuntimeLeafRecord): void {
     let foregroundPollInFlight = false
     waiter.pollInterval = setInterval(async () => {
@@ -23663,8 +23481,7 @@ export class OrcaRuntimeService {
           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.
+        // Why: the renderer-synced title is the only path where OSC titles are visible for daemon-hosted terminals.
         const pollTitle = leaf.paneTitle ?? this.tabs.get(leaf.tabId)?.title
         if (pollTitle) {
           const titleStatus = detectExplicitIdleStatusFromTitle(pollTitle)
@@ -23702,8 +23519,7 @@ export class OrcaRuntimeService {
           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.
+        // Foreground fallback: a reported non-shell process with quiet output is treated as idle.
         if (
           leaf.lastAgentStatus === null &&
           leaf.ptyId &&
@@ -23763,8 +23579,7 @@ export class OrcaRuntimeService {
           )
           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.
+        // Why: adopted background PTY handles use their live xterm title as the same readiness signal as leaf handles.
         if (
           this.getAdoptedPtyExplicitIdleStatus(pty) === 'idle' ||
           isKnownReadyPromptPreview(ptyWaitText)
@@ -23818,10 +23633,7 @@ export class OrcaRuntimeService {
     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.
+  // Why: push-on-idle delivery 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
@@ -23855,24 +23667,13 @@ export class OrcaRuntimeService {
 
     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.
+      // Why: Cursor Agent treats injected PTY text as editable prompt input, so submitting 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.
+    // Why: Claude Code treats a large PTY write as a paste and swallows a \r in the same write; send Enter separately after a delay, stamping delivered_at only once \r is confirmed.
+    // Important (design doc §3.2, feedback #2): stamp delivered_at, not read — read means "a check-caller consumed this"; flipping it would hide the message from check --unread.
     const ptyId = leaf.ptyId
     setTimeout(() => {
       try {
@@ -23884,9 +23685,7 @@ export class OrcaRuntimeService {
           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.
+        // Terminal may have closed during the delay — messages stay queued (delivered_at NULL) and re-deliver on next idle.
       }
     }, 500)
   }
@@ -24974,8 +24773,7 @@ export class OrcaRuntimeService {
     }
     let teams: NonNullable<LinearProjectSummary['teams']> = []
     try {
-      // Why: summary reads cap project teams, so large cross-team projects need
-      // a paged membership check before we reject an otherwise valid create.
+      // Why: summary reads cap project teams, so large cross-team projects need a paged membership check before rejecting a valid create.
       teams = await listLinearProjectTeams(project.id, workspaceId, true)
     } catch (error) {
       throw this.mapLinearReadFailure(error)
@@ -25355,8 +25153,7 @@ export class OrcaRuntimeService {
     unconfirmed: (cause?: string) => LinearAgentAccessError
   ): Promise<NonNullable<Awaited<ReturnType<typeof getLinearCommentByUuidForAgent>>>> {
     try {
-      // Why: a duplicate-id response can mean the original write landed; only
-      // the exact target relationship proves this pinned retry.
+      // 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,
@@ -25387,8 +25184,7 @@ export class OrcaRuntimeService {
     unconfirmed: (cause?: string) => LinearAgentAccessError
   ): Promise<NonNullable<Awaited<ReturnType<typeof getLinearAttachmentByUuidForAgent>>>> {
     try {
-      // Why: a duplicate-id response can mean the original write landed; only
-      // the exact target relationship proves this pinned retry.
+      // 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,
@@ -25420,8 +25216,7 @@ export class OrcaRuntimeService {
     unconfirmed: (cause?: string) => LinearAgentAccessError
   ): Promise<NonNullable<Awaited<ReturnType<typeof getLinearIssueByUuidForAgent>>>> {
     try {
-      // Why: a duplicate-id response can mean the original write landed; only
-      // the exact target relationship proves this pinned retry.
+      // 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,
@@ -25755,8 +25550,7 @@ export class OrcaRuntimeService {
     } = {}
   ): 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.
+    // Why: the retry preserves id and target so duplicate recovery can prove intent without matching mutable content.
     const pinned =
       verb === 'create'
         ? [
@@ -26050,9 +25844,7 @@ export class OrcaRuntimeService {
     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.
+    // Why: bind directly, not a wrapper arrow — a hand-listed wrapper dropped targetGroupId, so a right-split browser landed in the left.
     markHeadlessBrowserSessionTabActive: this.markHeadlessBrowserSessionTabActive.bind(this)
   })
 
@@ -26123,9 +25915,7 @@ export class OrcaRuntimeService {
       ? 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.
+      // Why: CDP allows only one screencast per page; cancel a stale stream so the next tab activation isn't stuck on an already-active error or old viewport.
       existingPageStream.cancel(existingPageStream.connectionKey !== connectionKey)
       await existingPageStream.done
       existingPageStream = requestedPageId
@@ -26172,17 +25962,13 @@ export class OrcaRuntimeService {
     const abortScreencast = (): void => cancel()
     const sendBinaryAfterReady = (bytes: Uint8Array<ArrayBufferLike>): 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.
+        // Why: clients learn the owning subscription from ready, so CDP frames must stay unacked until the JSON ready event is 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.
+    // Why: a phone can rotate before the first stream reaches ready (no subscriptionId yet), so a same-socket replacement cancels and waits here instead of racing.
     this.activeBrowserScreencastsByConnection.set(connectionKey, {
       cancel,
       done: activeDone,
@@ -26207,9 +25993,7 @@ export class OrcaRuntimeService {
       })
       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.
+      // Why: screencast frames are connection-scoped; tie Page.stopScreencast to the exact socket so dropped connections don't leave Chromium streaming.
       this.registerSubscriptionCleanup(
         screencast.subscriptionId,
         () => end(true),
@@ -26536,10 +26320,7 @@ export class OrcaRuntimeService {
 }
 
 const WAIT_BLOCKED_CHECK_MIN_INTERVAL_MS = 50
-// Why: chunks that can complete an actionable prompt bypass the throttle so
-// blocked stamps stay per-chunk-immediate; the pattern heads mirror
-// findTerminalWaitBlockedSignal. Scanned over the new chunk plus a short
-// carry only — never the accumulated window.
+// Why: chunks that could complete an actionable prompt bypass the throttle so blocked stamps stay immediate; scanned over the new chunk + short carry, never the whole window.
 const WAIT_BLOCKED_KEYWORD_PATTERN =
   /press enter|press t to trust|do you trust|trust this|trusted workspace|update available|choose working directory|codex just got an upgrade|hooks need review/
 const WAIT_BLOCKED_KEYWORD_CARRY_CHARS = 31
@@ -26570,15 +26351,9 @@ const RESOLVED_WORKTREE_CACHE_TTL_MS = 1000
 const WORKTREE_SCAN_CACHE_TTL_MS = 30_000
 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.
+// Why (§3.3): 30s freshness window reuses a recent fetch for repeat create/dispatch on the same repo+remote; short enough a changed remote is seen next action.
 const FETCH_FRESHNESS_MS = 30_000
-// Why: bound create-path remote fetches so a Windows credential-manager GUI hang
-// (STA-1292) can't wedge worktree creation forever; parity with the exact-base
-// refresh sibling's timeout.
+// Why: bound fetches so a Windows credential-manager GUI hang (STA-1292) can't wedge worktree creation; parity with the exact-base refresh sibling.
 const REMOTE_FETCH_TIMEOUT_MS = 60_000
 const REMOTE_FETCH_CACHE_MAX = 512
 const DRIFT_PROBE_SUBJECT_LIMIT = 5
@@ -26639,8 +26414,7 @@ export function appendRecentPtyPathCandidates(
 ): string[] {
   const extractedCandidates = extractTerminalOutputPathCandidates(data)
   if (extractedCandidates.length === 0) {
-    // Why: pathless output is the common hot path. Reuse immutable history so
-    // each PTY chunk does not clone and byte-scan up to 1,024 old candidates.
+    // Why: pathless output is the hot path; reuse immutable history so each chunk doesn't clone and byte-scan up to 1,024 old candidates.
     return previous ?? []
   }
   const next = previous ? previous.slice() : []
@@ -26779,12 +26553,7 @@ function decodeTerminalOutputPercentEscapes(value: string): string {
   })
 }
 
-// Why: extraction runs on the PTY hot path for every chunk, and the extension
-// regex backtracks quadratically on pathological separator runs. No candidate
-// can cross a newline (the regex classes exclude \r\n), so scan per line and
-// skip lines already too long to yield a storable candidate —
-// appendRecentPtyPathCandidates drops oversized candidates anyway, and the raw
-// recent-output buffer still covers provenance inside oversized lines.
+// Why: the extension regex backtracks quadratically on the PTY hot path; candidates can't cross a newline, so scan per line and skip over-long lines (dropped anyway).
 function extractTerminalOutputPathCandidates(data: string): string[] {
   const candidates: string[] = []
   const add = (value: string): void => {
@@ -26851,9 +26620,7 @@ function trimTerminalOutputPathCandidate(value: string): string {
     if (countTerminalOutputPathStarts(text) > 1) {
       continue
     }
-    // Same rule as the tap parsers: a line-end extension token only extends
-    // the candidate when the added segment is path-like, so trailing prose
-    // ending in a filename is not swallowed into the candidate.
+    // Same as the tap parsers: a line-end token extends the candidate only when the added segment is path-like, so trailing prose isn't swallowed.
     if (
       end < candidate.length ||
       selected === null ||
@@ -26936,25 +26703,18 @@ function buildTerminalWaitText(lines: string[], partialLine: string, preview: st
     .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.
+  // Why: the preview is intentionally short, but wait readiness needs the retained tail so ready headers aren't truncated away.
   return waitText.length > 0 ? waitText : preview
 }
 
 export type TerminalTailWaitState = {
   waitText: string
   signal: { reason: RuntimeTerminalWaitBlockedReason; index: number } | null
-  // Why: the retained tail is authoritative; `preview` is only a fallback for an
-  // empty tail. A preview-derived state depends on a value that is recomputed
-  // after each append, so it must not be reused as the next chunk's previous
-  // state — reuse is gated on fromTail.
+  // Why: preview is only an empty-tail fallback, recomputed each append, so a preview-derived state can't be reused as the next previous state (gated on fromTail).
   fromTail: boolean
 }
 
-// Why: onPtyData runs per raw PTY chunk (hundreds/sec under load). Ordinary
-// tails take one no-join sentinel pass; only candidate-bearing tails
-// build, lowercase, and parse the full 256 KiB text. The cached post-append
-// state also avoids repeating that work for the next chunk's previous state.
+// Why: runs per PTY chunk (hundreds/sec); only candidate-bearing tails parse the full 256 KiB, and the cached state avoids repeating that work next chunk.
 export function computeTerminalTailWaitState(
   lines: string[],
   partialLine: string,
@@ -26969,8 +26729,7 @@ export function computeTerminalTailWaitState(
     }
   }
   if (!tailShape.mayContainBlockedSignal) {
-    // Why: tailGainedNewerBlockedReason reads waitText only when signal exists;
-    // avoid retaining a rebuilt 256 KiB string for the overwhelmingly common case.
+    // Why: reads waitText only when a signal exists; avoid retaining a rebuilt 256 KiB string in the common case.
     return { waitText: '', signal: null, fromTail: true }
   }
   const tailText = buildTailLines(lines, partialLine)
@@ -27009,9 +26768,7 @@ function inspectTerminalWaitTail(
   return { fromTail, mayContainBlockedSignal }
 }
 
-// Why: decides whether the appended chunk introduced a newer actionable blocked
-// prompt, consuming precomputed wait states so the full-tail scans are not
-// repeated per chunk (replaces the former inline double full-tail scan).
+// Why: consumes precomputed wait states so full-tail scans aren't repeated per chunk (replaces the former inline double full-tail scan).
 export function tailGainedNewerBlockedReason(
   previous: TerminalTailWaitState,
   next: TerminalTailWaitState,
@@ -27020,9 +26777,7 @@ export function tailGainedNewerBlockedReason(
   if (next.signal === null) {
     return false
   }
-  // Why: permission prompts can arrive split across PTY chunks. Stamp when the
-  // accumulated tail first becomes blocked, or when a later prompt appears after
-  // stale blocked text already in the tail.
+  // Why: permission prompts can split across PTY chunks; stamp when the tail first becomes blocked, or a later prompt follows stale blocked text.
   if (previous.signal === null) {
     return true
   }
@@ -27056,8 +26811,7 @@ export function appendNormalizedToTailBuffer(
     }
   }
 
-  // Why: fullscreen TUIs often emit long, newline-free redraw streams. Keep the
-  // larger line transcript for pagination, but keep partial-line work bounded.
+  // Why: fullscreen TUIs emit long newline-free redraw streams; keep the line transcript for pagination but bound partial-line work.
   const previousPartialWasCapped = previousPartialLine.length > MAX_TAIL_PARTIAL_CHARS
   const boundedPreviousPartialLine = previousPartialLine.slice(-MAX_TAIL_PARTIAL_CHARS)
   const combinedChunk = `${boundedPreviousPartialLine}${normalizedChunk}`
@@ -27071,9 +26825,7 @@ export function appendNormalizedToTailBuffer(
     )
   }
 
-  // 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.
+  // Why: status UIs redraw one line via CR/backspace/erase; retain the latest redraw segment instead of appending every spinner frame.
   const segments = splitRetainedTerminalTailSegments(combinedChunk)
   const pieces = processTerminalTailCompleteSegments(segments.completeSegments)
   const newlyCompletedLines = pieces.map((line) => trimTerminalLineRight(line))
@@ -27143,15 +26895,7 @@ function trimTerminalLineRight(line: string): string {
   return end === line.length ? line : line.slice(0, end)
 }
 
-// Why a window: the unwindowed implementation below materializes a row object
-// per retained tail line and finalize re-allocates + regex-trims every row —
-// O(tail) per chunk (~0.9ms at the 2,000-line cap), measured at ~93% of the
-// main-process event loop under an agent-TUI flood (findings log 2026-07-03).
-// A redraw can only touch rows the cursor can reach, so run the algorithm on
-// a suffix window sized by the chunk's maximum upward cursor excursion and
-// share the untouched prefix by reference. Equality with the unwindowed
-// implementation is fuzz-verified in
-// retained-tail-redraw-window.equivalence.test.ts.
+// Why a window: the unwindowed impl below is O(tail) per chunk (~93% of the event loop under TUI flood, findings log 2026-07-03); a redraw only touches rows the cursor reaches, so window the suffix and share the prefix by reference. Equivalence fuzz-verified in retained-tail-redraw-window.equivalence.test.ts.
 const REDRAW_WINDOW_SAFETY_ROWS = 8
 
 function maxUpwardCursorReach(
@@ -27202,8 +26946,7 @@ function appendNormalizedToMultilineTailBuffer(
     previousRedrawCursor
   )
   let lines = previousLines.slice(0, prefixLength)
-  // Why: the unwindowed finalize trims trailing spaces/tabs on every row; the
-  // shared prefix must match without paying a regex per untouched row.
+  // Why: the shared prefix must match the unwindowed finalize's trailing-space trim without paying a regex per untouched row.
   for (let index = 0; index < lines.length; index += 1) {
     const line = lines[index]!
     const lastChar = line.charCodeAt(line.length - 1)
@@ -27280,8 +27023,7 @@ export function appendNormalizedToMultilineTailBufferUnwindowed(
       newlyCompletedLineCharacters -= newlyCompletedLines[newlyCompletedLineStart]!.length
       newlyCompletedLineStart += 1
     }
-    // Why: a single PTY chunk can contain unbounded newlines; compact in batches
-    // while retaining the suffix needed for stable transcript pagination.
+    // Why: a single PTY chunk can carry unbounded newlines; compact in batches while retaining the suffix needed for stable pagination.
     if (newlyCompletedLineStart >= MAX_TAIL_LINES) {
       newlyCompletedLines.splice(0, newlyCompletedLineStart)
       newlyCompletedLineStart = 0
@@ -27872,9 +27614,7 @@ function readTerminalTail(args: {
         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.
+    // Why: cursor reads return completed lines only, so a partial isn't delivered once as "hel" then again as "hello" after the newline.
     const startCursor = Math.max(args.cursor, oldestCursor)
     const startIndex = startCursor - oldestCursor
     const available = args.completedLines.slice(startIndex)
@@ -27893,9 +27633,7 @@ function readTerminalTail(args: {
     }
   }
 
-  // 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.
+  // Why: un-cursored reads are preview reads — return the latest bounded view; the larger buffer stays available via cursor reads + --limit.
   const limit = terminalReadLimit(args.limit, DEFAULT_TERMINAL_READ_LIMIT)
   const allLines = buildTailLines(args.previewLines, args.partialLine)
   const lineBoundedTail = allLines.slice(-limit)
@@ -27908,9 +27646,7 @@ function readTerminalTail(args: {
   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.
+  // Why: a long partial line trimmed by the char budget can't be recovered via nextCursor, since cursor reads only page completed lines.
   const truncatedByNonPageablePartial = charBoundedTail.limited && !hasPageableOmittedCompletedLines
   return {
     handle: args.handle,
@@ -28001,10 +27737,7 @@ async function assertTerminalInputWithinLimitWithYield(text: string | undefined)
   }
 }
 
-// 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.
+// Why: tui-idle needs OSC title transitions; an unsupported CLI/plain shell never fires one, so cap at 5min to avoid indefinite hangs.
 const TUI_IDLE_DEFAULT_TIMEOUT_MS = 5 * 60 * 1000
 const TUI_IDLE_POLL_INTERVAL_MS = 2000
 const TUI_IDLE_QUIESCENCE_MS = 3000
@@ -28014,11 +27747,7 @@ 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.
+// Clamp for mobileAutoRestoreFitMs: floor above the legacy 300ms debounce, 1h ceiling (a held PTY beyond that is "I forgot", not intentional).
 const MOBILE_AUTO_RESTORE_FIT_MIN_MS = 5_000
 const MOBILE_AUTO_RESTORE_FIT_MAX_MS = 60 * 60 * 1000
 
@@ -28027,8 +27756,7 @@ function detectExplicitIdleStatusFromTitle(title: string): AgentStatus | null {
   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.
+  // Why: launch titles like "Codex YOLO" contain an agent name but aren't readiness signals; terminal.wait needs explicit idle evidence.
   if (
     EXPLICIT_IDLE_TITLE_RE.test(title) ||
     title.startsWith(CLAUDE_IDLE_PREFIX) ||
@@ -28067,18 +27795,13 @@ function findActionableTerminalWaitBlockedSignal(
     return null
   }
   const dismissedModalIndex = findDismissedStartupModalIndex(normalized)
-  // Why: retained terminal tails can include stale startup modals. If a known
-  // agent's live prompt appears after that modal, the modal was dismissed and
-  // the signal is no longer actionable — even if the agent is still mid-run
-  // (Cursor never reports idle via OSC title, so its busy prompt clears too).
+  // Why: a live prompt after the modal means it was dismissed → signal no longer actionable, even mid-run (Cursor never reports idle via OSC title).
   return dismissedModalIndex !== null && dismissedModalIndex > blockedSignal.index
     ? null
     : blockedSignal
 }
 
-// Why: a recognized agent's live prompt (idle OR busy) proves its startup modal
-// was dismissed. Broader than the idle-only ready set so a mid-run Cursor lane
-// stops reporting a stale trust hit for the rest of the session.
+// Why: a live prompt (idle OR busy) proves the startup modal was dismissed, so a mid-run Cursor lane stops reporting stale trust hits.
 function findDismissedStartupModalIndex(normalized: string): number | null {
   const indexes = [
     findCodexReadyPromptIndex(normalized),
@@ -28097,12 +27820,7 @@ function findKnownReadyPromptIndex(normalized: string): number | null {
   return indexes.length > 0 ? Math.max(...indexes) : null
 }
 
-// Why: cursor-agent keeps a persistent TUI — a printed "Cursor Agent" banner and
-// a "→" input-prompt line appear once its trust dialog is dismissed, in both
-// busy and idle states. The banner is matched by its last occurrence so the
-// trust dialog's own "Cursor Agent" body text (which precedes the banner) does
-// not win. The "→" glyph is cursor-agent's input prompt marker ("→ Plan,
-// search, build anything" fresh, "→ Add a follow-up" after the first turn).
+// Why: match the banner's last occurrence to skip the trust dialog's own "Cursor Agent" text; "→" is cursor-agent's persistent input prompt.
 function findCursorActivePromptIndex(normalized: string): number | null {
   const headerIndex = normalized.lastIndexOf('cursor agent')
   if (headerIndex === -1) {
@@ -28111,9 +27829,7 @@ function findCursorActivePromptIndex(normalized: string): number | null {
   return normalized.includes('→', headerIndex) ? headerIndex : null
 }
 
-// Why: cursor-agent never emits an idle OSC title (its bare title is dropped),
-// so tui-idle can only resolve from the tail. Busy frames draw a braille
-// spinner in the on-screen status line; its absence past the banner is idle.
+// Why: cursor-agent emits no idle OSC title; infer idle from the tail (braille spinner = busy, its absence = idle).
 const CURSOR_BUSY_SPINNER_RE = /[⠁-⣿]/
 
 function findCursorReadyPromptIndex(normalized: string): number | null {
@@ -28130,8 +27846,7 @@ function findCodexReadyPromptIndex(normalized: string): number | null {
     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.
+  // Why: 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
 }
 
@@ -28144,8 +27859,7 @@ function findAntigravityReadyPromptIndex(normalized: string): number | null {
   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.
+  // Why: ready previews can include echoed paste after the header; scan line bounds directly instead of splitting the whole tail.
   for (let cursor = headerIndex; cursor <= normalized.length; cursor += 1) {
     if (cursor < normalized.length && normalized.charCodeAt(cursor) !== 10) {
       continue
@@ -28187,8 +27901,7 @@ const TERMINAL_WAIT_BLOCKED_SENTINEL_RE =
 function findTerminalWaitBlockedSignal(
   normalized: string
 ): { reason: RuntimeTerminalWaitBlockedReason; index: number } | null {
-  // Why: this runs once per PTY chunk over a tail up to 256 KiB. One combined
-  // negative scan avoids a dozen full-tail searches when no prompt can match.
+  // Why: one combined negative scan over the up-to-256 KiB tail avoids a dozen full-tail searches when no prompt can match.
   if (!TERMINAL_WAIT_BLOCKED_SENTINEL_RE.test(normalized)) {
     return null
   }
@@ -28328,10 +28041,7 @@ function getPtyTerminalState(pty: RuntimePtyWorktreeRecord): RuntimeTerminalStat
 }
 
 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.
+  // Why: Git can report a local branch as `refs/heads/foo` or `foo` depending on the plumbing path; accept either.
   return normalizeLocalBranchName(branch) === normalizeLocalBranchName(selector)
 }
 
@@ -28354,8 +28064,7 @@ function indexPersistedPtyWorktreeBindings(
     }
     const existingWorktreeId = worktreeIdByPtyId.get(ptyId)
     if (existingWorktreeId && existingWorktreeId !== worktreeId) {
-      // Why: corrupt/stale duplicate bindings must not attribute a live PTY to
-      // whichever workspace happened to be visited first.
+      // Why: a corrupt/stale duplicate binding must not attribute a live PTY to whichever workspace was visited first.
       worktreeIdByPtyId.delete(ptyId)
       ambiguousPtyIds.add(ptyId)
       return
@@ -28479,9 +28188,7 @@ function findRuntimeWorktreeSummaryByPath(
     runtimeWorktreeSummaryPathKey(repoId, worktreePath, platform)
   )
   const windowsCandidate = index.windowsAbsolute.get(windowsKey)
-  // Why: a malformed relative path can compare as POSIX against another
-  // relative path or as Windows against an absolute Windows path. Preserve the
-  // old pairwise scan's first-match result without rescanning every worktree.
+  // Why: a malformed path can match both the POSIX and Windows indexes; keep the old pairwise scan's first-match order.
   if (!posixCandidate) {
     return windowsCandidate?.summary ?? null
   }
@@ -28540,11 +28247,7 @@ 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.
+  // Why: recompute from the live title each call (no sticky state) so worktree.ps mirrors the desktop sidebar's getWorktreeStatus.
   const titleCandidates = [
     { title: leaf.paneTitle, updatedAt: leaf.paneTitleUpdatedAt },
     { title: leaf.lastOscTitle, updatedAt: leaf.lastOscTitleAt },
@@ -28658,8 +28361,7 @@ 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.
+  // Why: skip full ANSI/OSC scanning for the common plain-text PTY chunk (perf on high-throughput streams).
   if (pendingAnsi.length === 0 && !terminalChunkNeedsNormalization(chunk)) {
     return { text: chunk, pendingAnsi: '' }
   }
@@ -28681,8 +28383,7 @@ function normalizeTerminalChunk(
         }
       }
       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.
+        // Why: Codex redraws status text with ANSI controls but no CR; keep them so the tail overwrites the prior frame.
         parts.push(combined.slice(index, parsed.endIndex + 1))
       }
       index = parsed.endIndex
@@ -28793,8 +28494,7 @@ function compareWorktreePs(
   if (left.unread !== right.unread) {
     return left.unread ? -1 : 1
   }
-  // Why: worktree.ps is truncated for mobile, so host-visible activity must
-  // survive ahead of ordinary inactive rows without displacing pinned/unread.
+  // Why: worktree.ps is truncated for mobile, so host-visible activity must sort above inactive rows.
   if (left.hasHostSidebarActivity !== right.hasHostSidebarActivity) {
     return left.hasHostSidebarActivity ? -1 : 1
   }
diff --git a/src/main/runtime/orchestration/coordinator.ts b/src/main/runtime/orchestration/coordinator.ts
index 04f0788577c..d0e56b7e40a 100644
--- a/src/main/runtime/orchestration/coordinator.ts
+++ b/src/main/runtime/orchestration/coordinator.ts
@@ -20,39 +20,23 @@ export type CoordinatorRuntime = {
     handle: string,
     options?: { condition?: string; timeoutMs?: number }
   ): Promise<{ handle: string; condition: string }>
-  // Why (§3.1): dispatch pre-flight drift check lives on the runtime because
-  // it needs to resolve a worktree selector, load the repo, and fetch. The
-  // coordinator only knows about handles + specs; resolving a git worktree
-  // from this layer would leak transport details here.
+  // Why (§3.1): lives on the runtime because it must resolve a worktree, load the repo, and fetch — the coordinator only knows handles + specs.
   probeWorktreeDrift(worktreeSelector: string): Promise<{
     base: string
     behind: number
     recentSubjects: string[]
   } | null>
-  // Why: optional so lightweight runtime fakes keep compiling; when present,
-  // dispatch records the remint-stable pane identity of the assignee.
+  // Why: optional so lightweight runtime fakes keep compiling; when present, dispatch records the assignee's remint-stable pane identity.
   getTerminalPaneKey?(handle: string): string | null
-  // Why: Windows can host native and WSL workers concurrently, so the
-  // worker pane—not the coordinator process—selects the packaged CLI name.
+  // Why: Windows can host native and WSL workers at once, so the worker pane (not the coordinator) picks the packaged CLI name.
   getTerminalOrchestrationCliCommand?(handle: string): 'orca' | 'orca-ide'
 }
 
-// Why (§3.1): single threshold, no warn/refuse split. Coordinator picked 20
-// in msg_eff3a646110d — lets normal day-of-velocity on active monorepos pass
-// while still tripping on the 168-commit harm observed in ORCHESTRATOR_FEEDBACK.md.
+// Why (§3.1): 20 lets normal monorepo day-velocity pass but trips the 168-commit harm from ORCHESTRATOR_FEEDBACK.md (chosen in msg_eff3a646110d).
 export const DISPATCH_STALE_THRESHOLD = 20
 
-// Why (§3.4): the flag is stashed in the task spec text rather than a DB
-// column in v1. The regex is intentionally narrow — only the canonical form
-// matches, so typos fail closed (dispatch refuses). Returning the stripped
-// spec alongside the boolean keeps this infra line out of the worker's
-// `--- TASK ---` block (workers would otherwise read it as an instruction).
-//
-// Trade-off (§7.9): the regex matches any line of the spec including lines
-// inside fenced code blocks. Acceptable v1 limitation — the failure mode is
-// "dispatches through when the author didn't intend to," which the preamble
-// drift section surfaces to the worker. Skill doc directs authors to place
-// the flag as the last line and avoid the literal flag in code examples.
+// Why (§3.4): the flag lives in the spec text (no DB column in v1); the regex is narrow so typos fail closed, and stripping keeps the infra line out of the worker's `--- TASK ---` block.
+// Trade-off (§7.9): matches any spec line, even inside fenced code — fails open, but the preamble drift section still surfaces staleness to the worker.
 const ALLOW_STALE_BASE_RE = /^[ \t]*allow-stale-base:[ \t]*true[ \t]*\r?$/im
 const ALLOW_STALE_BASE_STRIP_RE = /^[ \t]*allow-stale-base:[ \t]*true[ \t]*\r?\n?/im
 
@@ -87,11 +71,7 @@ type CoordinatorState = {
 const DEFAULT_POLL_MS = 2000
 const MAX_CONCURRENT_DEFAULT = 4
 
-// Why: 10 min matches the preamble's documented heartbeat cadence (5 min) ×
-// 2, so a single missed heartbeat is the earliest a dispatch can look stale.
-// Keeping this in one place (not a per-call arg) ensures the preamble copy
-// and the detector logic stay aligned; moving it to a config would multiply
-// the places this constant must be kept in sync.
+// Why: 10 min = documented heartbeat cadence (5 min) × 2, so one missed heartbeat is the earliest a dispatch can look stale.
 const HUNG_THRESHOLD_MS = 10 * 60 * 1000
 
 export class Coordinator {
@@ -139,9 +119,7 @@ export class Coordinator {
     return this.executeLoop(run.id)
   }
 
-  // Why: the RPC handler creates the coordinator_runs record itself so it can
-  // return the run ID immediately, then starts the loop in the background.
-  // This method skips the DB insert and uses the pre-created run ID.
+  // Why: the RPC handler pre-creates the run record to return the ID immediately, so this method skips the DB insert.
   async runFromExistingRun(runId: string): Promise<{
     runId: string
     status: CoordinatorStatus
@@ -173,8 +151,7 @@ export class Coordinator {
         await this.sleep(this.opts.pollIntervalMs)
       }
 
-      // Why: if stopped early, treat it as failed since tasks are incomplete.
-      // Also failed if any task explicitly failed.
+      // Why: an early stop leaves tasks incomplete, so the run counts as failed.
       const tasks = this.db.listTasks()
       const allDone = tasks.every((t) => t.status === 'completed' || t.status === 'failed')
       const failedTasks = [
@@ -205,11 +182,7 @@ export class Coordinator {
     this.stopped = true
   }
 
-  // Why: the coordinator decomposes the top-level spec into a task DAG.
-  // For now, tasks must be pre-created before calling run(). The spec is
-  // stored for context but decomposition is the caller's responsibility —
-  // AI-driven decomposition belongs in a future phase where the coordinator
-  // itself is an LLM agent.
+  // Why: decomposition isn't implemented yet — tasks must be pre-created before run(); AI-driven decomposition is a future phase.
   private async decompose(): Promise<void> {
     this.state.phase = 'decomposing'
     const existing = this.db.listTasks()
@@ -231,11 +204,7 @@ export class Coordinator {
     return this.checkConvergence()
   }
 
-  // Why: emit a single warning per stale dispatch per tick. This intentionally
-  // does NOT auto-fail the dispatch — the false-positive cost (a slow worker
-  // producing correct output) is higher than the false-negative cost (a hung
-  // worker keeps its terminal slot until a human notices). Auto-fail policy
-  // is a separate decision documented in R6 of DESIGN_DOC_PREAMBLE_FIX.md.
+  // Why: warn only, never auto-fail — a false positive (slow but correct worker) costs more than a false negative (hung worker holding a slot); see R6 of DESIGN_DOC_PREAMBLE_FIX.md.
   private warnStaleDispatches(): void {
     const thresholdIso = new Date(Date.now() - HUNG_THRESHOLD_MS).toISOString()
     const stale = this.db.getStaleDispatches(thresholdIso)
@@ -317,9 +286,7 @@ export class Coordinator {
       return
     }
 
-    // Why: fail the dispatch so the circuit breaker increments. If under
-    // the threshold, the task returns to 'pending' and will be re-dispatched
-    // to a (potentially different) terminal on the next tick.
+    // Why: fail the dispatch to increment the circuit breaker; under threshold the task returns to 'pending' for re-dispatch next tick.
     const updated = this.db.failDispatch(dispatch.id, msg.subject)
     if (updated?.status === 'circuit_broken') {
       this.opts.onLog(`Task ${taskId} circuit broken after repeated failures`)
@@ -357,22 +324,16 @@ export class Coordinator {
   }
 
   private processEscalations(): void {
-    // Why: escalation processing is handled inline in processMessages via
-    // handleEscalation. This method exists as a hook for future escalation
-    // policies (e.g., auto-reassign after N minutes, notify external systems).
+    // Why: escalations are handled inline via handleEscalation; this stays a hook for future policies (auto-reassign, external notify).
   }
 
   private processDecisionGates(): void {
-    // Why: pending gates that haven't been resolved externally are surfaced
-    // here. In production, the coordinator UI or a human operator resolves
-    // gates via orchestration.gateResolve. The coordinator does not auto-
-    // resolve gates — that would defeat their purpose as approval checkpoints.
+    // Why: the coordinator never auto-resolves gates (humans do, via orchestration.gateResolve) — that would defeat them as approval checkpoints.
     const pendingGates = this.db.listGates({ status: 'pending' })
     for (const gate of pendingGates) {
       const task = this.db.getTask(gate.task_id)
       if (task && task.status !== 'blocked') {
-        // Why: gate exists but task isn't blocked — inconsistent state.
-        // Re-block the task to maintain the invariant.
+        // Why: gate exists but task isn't blocked — re-block to restore the invariant.
         this.db.updateTaskStatus(gate.task_id, 'blocked')
       }
     }
@@ -385,7 +346,6 @@ export class Coordinator {
       return
     }
 
-    // Why: count currently dispatched tasks to enforce concurrency limit.
     const dispatched = this.db.listTasks({ status: 'dispatched' })
     let slotsAvailable = this.opts.maxConcurrent - dispatched.length
     if (slotsAvailable <= 0) {
@@ -394,8 +354,7 @@ export class Coordinator {
 
     const terminals = await this.getAvailableTerminals()
     if (terminals.length === 0 && slotsAvailable > 0) {
-      // Why: no idle terminals exist — create one for the next task.
-      // Only create one per tick to avoid spawning many terminals at once.
+      // Why: create at most one terminal per tick to avoid spawning many at once.
       try {
         const created = await this.runtime.createTerminal(this.opts.worktree, {
           title: `Worker: ${readyTasks[0].spec.slice(0, 40)}`
@@ -425,14 +384,7 @@ export class Coordinator {
   }
 
   private async dispatchTask(task: TaskRow, targetHandle: string): Promise<void> {
-    // Why (§3.1): pre-flight drift check BEFORE `createDispatchContext` so a
-    // refusal does NOT increment failure_count. createDispatchContext carries
-    // `MAX(failure_count)` forward across contexts (db.ts:301-306), so burning
-    // the circuit-breaker budget here would convert a recoverable "fetch and
-    // retry" into a hard `failed` task within ~6s of polling. Silent return
-    // leaves the task in `ready`; the next `dispatchReadyTasks` tick retries
-    // naturally, and once the coordinator's worktree has been refreshed
-    // dispatch proceeds cleanly.
+    // Why (§3.1): drift check runs before createDispatchContext so a refusal doesn't bump failure_count (carried forward as MAX in db.ts:301-306) and burn the circuit-breaker budget; the task stays `ready` and retries next tick.
     const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(task.spec)
     let baseDrift: {
       base: string
@@ -441,10 +393,7 @@ export class Coordinator {
     } | null = null
 
     if (!this.opts.worktree) {
-      // Why (§7.4): CoordinatorOptions.worktree is optional. When undefined,
-      // probeWorktreeDrift cannot resolve a selector; log once so operators
-      // can see the guard did not run for this task and proceed. v2 may
-      // always resolve a worktree via the coordinator-terminal handle.
+      // Why (§7.4): worktree is optional; with none we can't probe drift, so log that the guard is inert and proceed.
       this.opts.onLog(`stale-base guard inert for ${task.id}: coordinator has no worktree selector`)
     } else {
       baseDrift = await this.runtime.probeWorktreeDrift(this.opts.worktree).catch((err) => {
@@ -453,9 +402,7 @@ export class Coordinator {
       })
 
       if (baseDrift && baseDrift.behind > DISPATCH_STALE_THRESHOLD && !allowStale) {
-        // Why (§3.1): silent-return, NOT failDispatch (which would burn the
-        // circuit-breaker budget). The message lists three remediations so
-        // the operator can recover via any of them.
+        // Why (§3.1): silent-return, not failDispatch — failing a recoverable stale-base here would burn the circuit-breaker budget.
         this.opts.onLog(
           `Skipping dispatch of ${task.id}: worktree is ${baseDrift.behind} commits ` +
             `behind ${baseDrift.base}. Pull/rebase the worktree, recreate it with ` +
@@ -473,18 +420,11 @@ export class Coordinator {
       this.runtime.getTerminalPaneKey?.(targetHandle) ?? undefined
     )
 
-    // Why: agents dispatched by the coordinator must use orca-dev in dev mode
-    // so they talk to the dev runtime's socket, not production (Section 6.4).
-    // Why (§3.4): `strippedSpec` drops the `allow-stale-base: true` line so
-    // the worker's `--- TASK ---` block does not contain the infra flag (which
-    // the worker would otherwise read as part of its instructions).
+    // Why: dispatched agents use orca-dev in dev mode to reach the dev runtime's socket, not production (Section 6.4).
     const preamble = buildDispatchPreamble({
       taskId: task.id,
       dispatchId: dispatch.id,
-      // Why (§3.4, stale-base PR): use `strippedSpec` not `task.spec` so the
-      // `allow-stale-base: true` line isn't rendered into the worker's
-      // --- TASK --- block (worker would otherwise treat the infra flag as
-      // part of its instructions).
+      // Why (§3.4): strippedSpec drops the allow-stale-base line so the worker doesn't read the infra flag as an instruction.
       taskSpec: strippedSpec,
       coordinatorHandle: this.opts.coordinatorHandle,
       workerHandle: targetHandle,
@@ -492,15 +432,11 @@ export class Coordinator {
       ...(this.runtime.getTerminalOrchestrationCliCommand
         ? { cliCommand: this.runtime.getTerminalOrchestrationCliCommand(targetHandle) }
         : {}),
-      // Why (§3.2): drift section fires only when behind > 0. The preamble
-      // builder gates on this itself; passing the object unconditionally lets
-      // the coordinator stay dumb about the display rule.
+      // Why (§3.2): pass baseDrift unconditionally — the preamble builder itself gates the drift section on behind > 0.
       ...(baseDrift ? { baseDrift } : {})
     })
 
-    // Why: check if the task was previously blocked by a decision gate that
-    // has since been resolved. Include the resolution in the preamble so the
-    // worker knows the decision outcome.
+    // Why: surface a since-resolved decision gate's outcome to the worker via the preamble.
     const gates = this.db.listGates({ taskId: task.id, status: 'resolved' })
     let gateContext = ''
     if (gates.length > 0) {
@@ -538,11 +474,7 @@ export class Coordinator {
         }
       }
 
-      // Why: exclude the coordinator's own terminal, terminals with active
-      // dispatches, and disconnected terminals. The dispatch-lock in
-      // createDispatchContext prevents double-dispatch even if a terminal
-      // looks available here — this filter is an optimization, not a
-      // correctness constraint.
+      // Why: createDispatchContext's dispatch-lock guarantees correctness; this filter is only an optimization to skip busy/disconnected terminals.
       return result.terminals
         .filter(
           (t) =>
@@ -569,8 +501,7 @@ export class Coordinator {
       return true
     }
 
-    // Why: detect stuck state — no ready or dispatched tasks, but some are
-    // still pending/blocked. This means deps can never be satisfied.
+    // Why: no active tasks but some blocked → dependencies can never be satisfied (stuck).
     const active = tasks.filter(
       (t) => t.status === 'ready' || t.status === 'dispatched' || t.status === 'pending'
     )
diff --git a/src/main/runtime/orchestration/db.ts b/src/main/runtime/orchestration/db.ts
index 5e8a46738fa..1c4b68f9d10 100644
--- a/src/main/runtime/orchestration/db.ts
+++ b/src/main/runtime/orchestration/db.ts
@@ -17,8 +17,7 @@ import type {
 import { buildOrchestrationTaskDisplayMetadata } from '../../../shared/orchestration-task-display'
 import { parsePaneKey } from '../../../shared/stable-pane-id'
 
-// Why: leaf UUID is the remint-stable pane identity; the tab half changes on
-// break-out. Exact string match covers legacy/unparseable keys.
+// Why: leaf UUID is the remint-stable pane identity (tab half changes on break-out); exact match covers legacy/unparseable keys.
 function isEquivalentPaneKey(a: string, b: string): boolean {
   if (a === b) {
     return true
@@ -72,8 +71,7 @@ function exposeUtcTimestamp(timestamp: string | null): string | null {
 }
 
 function exposeMessageTimestamps(message: MessageRow): MessageRow {
-  // Why: SQLite stores UTC as a timezone-less space format for internal SQL
-  // ordering, but RPC/CLI consumers need an explicit offset to interpret it.
+  // Why: SQLite stores UTC as timezone-less space format for SQL ordering, but RPC/CLI consumers need an explicit offset.
   return {
     ...message,
     created_at: exposeUtcTimestamp(message.created_at) ?? message.created_at,
@@ -85,16 +83,7 @@ function exposeMessageListTimestamps(messages: MessageRow[]): MessageRow[] {
   return messages.map(exposeMessageTimestamps)
 }
 
-// Why: v1 → v2 added `'heartbeat'` to messages.type CHECK + `last_heartbeat_at`
-// column (preamble-hardening PR). v2 → v3 adds `delivered_at` column so
-// push-on-idle can distinguish queued-but-undelivered from user-acknowledged
-// messages without touching the `read` bit (check-wait PR). v3 → v4 records
-// the terminal that created a task so task-record worktree creation can infer
-// the parent workspace even when no dispatch context exists. v4 → v5 adds
-// explicit task_title/display_name fields for orchestration worker UI labels.
-// v5 → v6 adds pane-identity columns (dispatch_contexts.assignee_pane_key,
-// messages.sender_pane_key) so worker_done ownership survives terminal handle
-// remints without accepting completions from unrelated panes.
+// Schema versions: v2 'heartbeat'+last_heartbeat_at, v3 delivered_at, v4 task-creator terminal, v5 task_title/display_name, v6 pane-identity columns.
 const SCHEMA_VERSION = 6
 
 export class OrchestrationDb {
@@ -205,12 +194,7 @@ export class OrchestrationDb {
     this.createUndeliveredInboxIndexIfPossible()
   }
 
-  // Why: `CREATE TABLE IF NOT EXISTS` is a no-op against an existing on-disk
-  // DB, so new schema shapes (added columns, widened CHECK constraints) do
-  // not reach an upgraded user unless we migrate explicitly. The transaction
-  // guarantees atomicity — a mid-migration crash leaves the DB at the prior
-  // version because `user_version` is bumped only on success. Idempotent
-  // re-invocation is a no-op (current >= SCHEMA_VERSION short-circuit).
+  // Why: CREATE TABLE IF NOT EXISTS won't alter existing DBs; migrate in a txn that bumps user_version only on success (atomic all-or-nothing).
   private migrate(): void {
     const current = this.db.pragma('user_version', { simple: true }) as number
     if (current >= SCHEMA_VERSION) {
@@ -219,24 +203,14 @@ export class OrchestrationDb {
 
     this.db.exec('BEGIN')
     try {
-      // v1 → v2: add last_heartbeat_at column; widen messages.type CHECK to
-      // include 'heartbeat'. SQLite cannot ALTER a CHECK constraint, so we
-      // rebuild the messages table. We also include `delivered_at` in the
-      // rebuilt schema so DBs migrating from v1 pick up the v3 column in a
-      // single table-rewrite pass (avoids a second messages-rebuild later).
+      // v1 → v2: SQLite can't ALTER a CHECK, so rebuild messages to allow 'heartbeat'; fold in v3's delivered_at to skip a second rebuild.
       if (current < 2) {
         if (!this.hasColumn('dispatch_contexts', 'last_heartbeat_at')) {
           this.db.exec(`ALTER TABLE dispatch_contexts ADD COLUMN last_heartbeat_at TEXT`)
         }
 
         if (!this.messagesTypeCheckAllowsHeartbeat()) {
-          // Why — index list is not optional. createTables() already attached
-          // idx_messages_id / idx_inbox / idx_messages_undelivered_inbox /
-          // idx_thread to the old messages table; DROP TABLE removes those
-          // indexes with it. CREATE INDEX IF NOT EXISTS in createTables() only
-          // runs on the next process startup, so skipping explicit recreation
-          // here would leave message lookups full-scanning for the rest of this
-          // process's lifetime — a silent O(N) perf regression.
+          // Why: recreate indexes here — DROP TABLE drops them; createTables re-runs only next startup, so skipping full-scans until restart.
           this.db.exec(`
             CREATE TABLE messages_new (
               id            TEXT NOT NULL,
@@ -278,12 +252,7 @@ export class OrchestrationDb {
         }
       }
 
-      // v2 → v3: add `delivered_at` column to messages. A DB that reached v2
-      // via the v1 → v2 rebuild above already has the column (we included
-      // it in messages_new); this handles DBs that were at v2 before this
-      // release shipped (preamble PR deployed standalone, then check-wait
-      // merged). ALTER TABLE is idempotent via the hasColumn probe — a
-      // duplicate-column error would abort the whole transaction.
+      // v2 → v3: add messages.delivered_at. hasColumn probe skips DBs that already got it via the v1→v2 rebuild (else a dup-column error aborts the txn).
       if (current < 3) {
         if (!this.hasColumn('messages', 'delivered_at')) {
           this.db.exec(`ALTER TABLE messages ADD COLUMN delivered_at TEXT`)
@@ -335,10 +304,7 @@ export class OrchestrationDb {
     `)
   }
 
-  // Why: sqlite_master stores the original CREATE TABLE SQL including the
-  // CHECK clause. Inspecting that text is the cheapest reliable way to tell
-  // whether the pre-rebuild schema already knows about 'heartbeat' without
-  // needing a dedicated schema_meta row.
+  // Why: sqlite_master holds the table's CREATE SQL incl. the CHECK — cheapest reliable probe for whether it already allows 'heartbeat'.
   private messagesTypeCheckAllowsHeartbeat(): boolean {
     const row = this.db
       .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'messages'")
@@ -408,8 +374,7 @@ export class OrchestrationDb {
     const originalBody = message.body ? `\n\nOriginal body:\n${message.body}` : ''
     const body = `Orca rejected this ${message.type}: ${reason}${originalBody}`
     const payload = addLifecycleRejectionMarker(message.payload, reason)
-    // Why: rejected lifecycle signals must remain auditable without reaching
-    // later read paths as actionable completion or liveness events.
+    // Why: rejected lifecycle signals stay auditable but must not reach read paths as actionable completion/liveness events.
     this.db
       .prepare(
         `UPDATE messages
@@ -420,12 +385,7 @@ export class OrchestrationDb {
     return this.getMessageById(messageId)
   }
 
-  // Why: push-on-idle delivery must not replay messages that were already
-  // injected into the PTY. `read` flips only when a check-caller consumes a
-  // message, so delivered-but-unread rows would otherwise be re-injected on
-  // every later idle transition (the replay bug). Filter on
-  // `delivered_at IS NULL` so each row is auto-pushed at most once; explicit
-  // `check` still sees them via getUnreadMessages.
+  // Why: delivered_at IS NULL filter — push-on-idle delivers each row at most once; read (set only by check) wouldn't prevent replay.
   getUndeliveredUnreadMessages(toHandle: string, types?: MessageType[]): MessageRow[] {
     if (types && types.length > 0) {
       const placeholders = types.map(() => '?').join(',')
@@ -469,11 +429,7 @@ export class OrchestrationDb {
     this.db.prepare(`UPDATE messages SET read = 1 WHERE id IN (${placeholders})`).run(...ids)
   }
 
-  // Why: `delivered_at` is stamped via SQLite's datetime('now') rather than a
-  // JS ISO string so it uses the same 'YYYY-MM-DD HH:MM:SS' UTC shape as the
-  // other SQL-default timestamps on this table. A future ORDER BY or
-  // comparison against created_at relies on this format consistency.
-  // See design doc §3.2.
+  // Why: use datetime('now') so delivered_at matches the space-format UTC shape of the table's other timestamps for correct ordering (§3.2).
   markAsDelivered(ids: string[]): void {
     if (ids.length === 0) {
       return
@@ -489,8 +445,7 @@ export class OrchestrationDb {
       return
     }
     const placeholders = ids.map(() => '?').join(',')
-    // Why: superseded lifecycle messages stay queryable through history but
-    // must not be consumed or injected after their dispatch has finished.
+    // Why: superseded lifecycle messages stay in history but must not be consumed or injected after their dispatch finished.
     this.db
       .prepare(
         `UPDATE messages SET read = 1, delivered_at = COALESCE(delivered_at, datetime('now')) WHERE id IN (${placeholders})`
@@ -506,10 +461,7 @@ export class OrchestrationDb {
     )
   }
 
-  // Why: used by `check --all` and `inbox --terminal <handle>` — returns every
-  // message for a handle regardless of read/delivered state; never touches the
-  // read bit. Stale-handle safe: if the handle no longer exists, the query
-  // just returns whatever historical rows remain (§3.3).
+  // Why: read-only history for a handle — returns every message regardless of read/delivered state, never flips the read bit (§3.3).
   getAllMessagesForHandle(toHandle: string, limit = 100, types?: MessageType[]): MessageRow[] {
     if (types && types.length > 0) {
       const placeholders = types.map(() => '?').join(',')
@@ -528,12 +480,7 @@ export class OrchestrationDb {
     )
   }
 
-  // Why: thread-scoped read for the `orchestration.ask` wait loop. Filtered
-  // by `to_handle` so a worker only sees replies addressed to it (not
-  // messages it sent), and ordered by `sequence` so the first post-ask
-  // reply is returned first. `afterSequence` lets the caller resume past an
-  // already-seen marker without re-reading the outbound ask itself. Uses
-  // the existing idx_thread index (see createTables) — no new index.
+  // Why: ask wait-loop read — to_handle filter shows only replies to the worker; afterSequence resumes past its own outbound ask.
   getThreadMessagesFor(threadId: string, toHandle: string, afterSequence?: number): MessageRow[] {
     if (afterSequence !== undefined) {
       return exposeMessageListTimestamps(
@@ -607,12 +554,7 @@ export class OrchestrationDb {
     return this.db.prepare('SELECT * FROM tasks ORDER BY created_at').all() as TaskRow[]
   }
 
-  // Why: surfaces the active dispatch (assignee handle + dispatch context id)
-  // alongside each task so coordinators can answer "who is working on task X?"
-  // from a single query. The LEFT JOIN keeps non-dispatched tasks in the result
-  // with NULL assignee/dispatch fields so non-dispatched output stays stable.
-  // The inner subquery picks the most recent active dispatch per task to match
-  // the semantics of getDispatchContext for dispatched tasks.
+  // Why: LEFT JOIN keeps non-dispatched tasks (NULL assignee); the MAX(rowid) subquery matches getDispatchContext's most-recent-active-dispatch semantics.
   listTasksWithDispatch(filter?: { status?: TaskStatus; ready?: boolean }): (TaskRow & {
     assignee_handle: string | null
     dispatch_id: string | null
@@ -668,11 +610,7 @@ export class OrchestrationDb {
     return this.getTask(id)
   }
 
-  // Why: when a task completes, check if any pending tasks that depended on it
-  // now have all deps satisfied. If so, promote them to 'ready'. This is the
-  // DAG resolution step — it runs synchronously inside the same transaction as
-  // the status update, so there's no window where a task is completable but its
-  // children haven't been promoted.
+  // Why: runs in the status-update transaction, so a completed task never leaves its ready children unpromoted.
   private promoteReadyTasks(completedTaskId: string): void {
     const candidates = this.db
       .prepare("SELECT * FROM tasks WHERE status = 'pending'")
@@ -699,9 +637,7 @@ export class OrchestrationDb {
   createDispatchContext(
     taskId: string,
     assigneeHandle: string,
-    // Why: the pane key is the remint-stable identity behind the handle;
-    // recording it at dispatch time lets worker_done ownership survive
-    // restarts that reissue the handle.
+    // Why: pane key is the remint-stable identity behind the handle — lets worker_done ownership survive handle reissue.
     assigneePaneKey?: string
   ): DispatchContextRow {
     const task = this.getTask(taskId)
@@ -712,10 +648,7 @@ export class OrchestrationDb {
       throw new Error(`Task ${taskId} is ${task.status}; only ready tasks can be dispatched`)
     }
 
-    // Why: handle match covers legacy rows without pane keys; when both the
-    // new assignee and an active row have usable pane keys, also lock on
-    // equivalent pane identity so a reminted handle cannot open a second
-    // concurrent dispatch on the same pane.
+    // Why: lock on pane identity too, so a reminted handle can't open a second concurrent dispatch on the same pane.
     const existing = this.findActiveDispatchForAssignee(assigneeHandle, assigneePaneKey)
 
     if (existing) {
@@ -724,8 +657,7 @@ export class OrchestrationDb {
       )
     }
 
-    // Carry forward failure_count from prior contexts so the circuit breaker
-    // accumulates across retries for the same task.
+    // Carry forward failure_count so the circuit breaker accumulates across retries for the same task.
     const prior = this.db
       .prepare('SELECT MAX(failure_count) as max_failures FROM dispatch_contexts WHERE task_id = ?')
       .get(taskId) as { max_failures: number | null } | undefined
@@ -829,12 +761,7 @@ export class OrchestrationDb {
     return active ? this.failDispatch(active.id, error) : undefined
   }
 
-  // Why: only touch rows that are currently dispatched. A straggler heartbeat
-  // from a dispatch that already transitioned to `completed` / `failed` /
-  // `circuit_broken` MUST NOT retroactively bump `last_heartbeat_at`, because
-  // the stale-dispatch detector is the signal the coordinator uses to know a
-  // newer dispatch for the same task has hung. Silently no-op'ing keeps the
-  // zombie-heartbeat race from masking a hung retry (§5.3.4).
+  // Why: only bump status='dispatched' — a zombie heartbeat from a finished dispatch would mask a hung retry from the stale detector (§5.3.4).
   recordHeartbeat(dispatchId: string, at: string): void {
     this.db
       .prepare(
@@ -843,17 +770,7 @@ export class OrchestrationDb {
       .run(at, dispatchId)
   }
 
-  // Why: the query restricts to currently-dispatched contexts AND respects a
-  // dispatched-at grace. Without `status = 'dispatched'`, every completed /
-  // failed / circuit_broken row with an old-or-null last_heartbeat_at would
-  // warn every tick (warning storm). Without `dispatched_at < :threshold`,
-  // a freshly-dispatched worker would trip the warning during its first
-  // heartbeat interval (false positive). The stored columns are space-format
-  // (datetime('now'), "2026-07-12 12:00:00") while the threshold is ISO-Z, so
-  // raw TEXT ordering compares ' ' (0x20) below 'T' (0x54) at index 10 and
-  // flags fresh same-date rows as stale (#8452). julianday() parses both
-  // formats as UTC for a correct numeric comparison; a malformed timestamp
-  // yields NULL, so that row simply isn't flagged.
+  // Why: dispatched_at grace skips workers still within their first heartbeat interval; julianday() vs raw-TEXT compare avoids misflagging space-format timestamps as stale (#8452).
   getStaleDispatches(thresholdIso: string): DispatchContextRow[] {
     return this.db
       .prepare(
@@ -883,10 +800,7 @@ export class OrchestrationDb {
       )
       .run(newStatus, newFailureCount, error, ctxId)
 
-    // Why: set the task back to 'ready' (not 'pending') so the coordinator can
-    // re-dispatch it on the next tick. The task's deps are already satisfied —
-    // setting it to 'pending' would strand it since promoteReadyTasks only runs
-    // when a dep completes.
+    // Why: back to 'ready' not 'pending' — 'pending' would strand it since promoteReadyTasks only runs when a dep completes.
     const taskStatus: TaskStatus = newStatus === 'circuit_broken' ? 'failed' : 'ready'
     this.db.prepare('UPDATE tasks SET status = ? WHERE id = ?').run(taskStatus, ctx.task_id)
 
@@ -924,9 +838,7 @@ export class OrchestrationDb {
       )
       .run(resolution, gateId)
 
-    // Why: unblock the task so the coordinator can re-dispatch it with the
-    // resolution context. Setting to 'ready' rather than the previous status
-    // because the worker needs to be re-engaged with the decision outcome.
+    // Why: set to 'ready' (not the previous status) so the coordinator re-dispatches the worker with the resolution context.
     this.db.prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(gate.task_id)
 
     return this.db.prepare('SELECT * FROM decision_gates WHERE id = ?').get(gateId) as
@@ -1018,8 +930,6 @@ export class OrchestrationDb {
   // ── Queries for Coordinator ──
 
   getIdleTerminals(excludeHandles: string[] = []): string[] {
-    // Why: returns terminal handles that have no active dispatch, so the
-    // coordinator knows which terminals are available for new task assignments.
     const active = this.db
       .prepare(
         "SELECT DISTINCT assignee_handle FROM dispatch_contexts WHERE status IN ('pending', 'dispatched')"
diff --git a/src/main/runtime/rpc/core.ts b/src/main/runtime/rpc/core.ts
index 3552b680caf..3a01789f157 100644
--- a/src/main/runtime/rpc/core.ts
+++ b/src/main/runtime/rpc/core.ts
@@ -1,7 +1,4 @@
-// Why: this is the single boundary between raw RPC frames and the OrcaRuntimeService.
-// Keeping the schema, handler, and result type attached to one object makes the
-// CLI-facing contract greppable and lets the dispatcher verify every payload
-// against the same shape the handler consumed during development.
+// Why: single boundary between raw RPC frames and OrcaRuntimeService; keeps schema, handler, and result type on one object.
 import { ZodError, type ZodType } from 'zod'
 import type { TerminalStreamFrame } from '../../../shared/terminal-stream-protocol'
 import type { OrcaRuntimeService } from '../orca-runtime'
@@ -51,38 +48,20 @@ export type RpcRequest = {
 
 export type RpcContext = {
   runtime: OrcaRuntimeService
-  // Why: long-poll handlers (e.g. orchestration.check with wait=true) need to
-  // observe the underlying socket's lifetime so they can release their slot
-  // and resolve their inner waiters immediately when a client disconnects
-  // instead of running down the configured timeoutMs. Undefined outside the
-  // runtime-rpc transport (direct in-process callers don't need it).
-  // See design doc §3.1 counter-lifecycle.
+  // Why: lets long-poll handlers release immediately on client disconnect instead of running down timeoutMs. See design doc §3.1.
   signal?: AbortSignal
-  // Why: streaming handlers (notifications/accounts/terminal subscribe)
-  // register cleanup callbacks against the runtime so reconnects don't leak
-  // listeners. Keying those cleanups by per-WebSocket connectionId lets the
-  // server reap all subscriptions for a closing socket, even when other
-  // sockets for the same deviceToken stay alive (multi-screen mobile).
+  // Why: per-WebSocket key so the server reaps a closing socket's subscriptions without touching sibling sockets sharing the deviceToken.
   connectionId?: string
-  // Why: shared-control multiplexes many logical streams over one socket. Some
-  // handlers need the frame id to register cleanup at logical-stream granularity.
+  // Why: shared-control multiplexes many logical streams over one socket; the frame id lets handlers register cleanup per logical stream.
   requestId?: string
-  // Why: WebSocket RPCs authenticate by mobile device token. State-owning
-  // handlers use this to clean up when that paired device disconnects.
+  // Why: paired mobile device token; state-owning handlers use it to clean up when that device disconnects.
   clientId?: string
-  // Why: payload windowing/truncation tuned for the constrained mobile payload
-  // (e.g. native-chat block char cap) must not clip full-screen web/desktop
-  // clients. Carries the paired device's scope so handlers can gate the diet to
-  // phones only. Undefined for in-process callers → treat as full-class (no clip).
+  // Why: lets handlers gate mobile payload truncation to phones only; undefined for in-process callers → treat as full-class (no clip).
   clientKind?: 'mobile' | 'runtime'
   pairing?: PairingRpcContext
-  // Why: mobile terminal traffic is byte-oriented and bypasses JSON streaming
-  // responses after the binary terminal cutover. Undefined on Unix/socket
-  // transports and non-E2EE WebSocket paths.
+  // Why: mobile terminal traffic bypasses JSON streaming; undefined on Unix/socket and non-E2EE WebSocket paths.
   sendBinary?: (bytes: Uint8Array<ArrayBufferLike>) => boolean | void
-  // Why: binary terminal input/resize frames arrive outside JSON-RPC after a
-  // stream is established. The WebSocket transport owns the connection-scoped
-  // stream table; handlers register only the stream IDs they created.
+  // Why: binary terminal frames arrive outside JSON-RPC once a stream is established; handlers register only the stream IDs they created.
   registerBinaryStreamHandler?: (
     streamId: number,
     handler: (frame: TerminalStreamFrame) => void
@@ -91,11 +70,7 @@ export type RpcContext = {
 
 export type RpcHandler<TParams> = (params: TParams, ctx: RpcContext) => Promise<unknown> | unknown
 
-// Why: defineMethod preserves the inferred param type locally so each handler
-// is fully typed, but the erased `RpcMethod` form is what the dispatcher
-// actually stores. The erasure lives in one cast inside defineMethod rather
-// than in every method file, which is the tradeoff for the variance problem
-// of `RpcHandler` being contravariant in its param type.
+// Why: RpcMethod erases the param type; centralizing the cast in defineMethod sidesteps RpcHandler's contravariance.
 export type RpcMethod = {
   readonly name: string
   readonly params: ZodType | null
@@ -124,9 +99,7 @@ export type RpcStreamingHandler<TParams> = (
   emit: (result: unknown) => void
 ) => Promise<void>
 
-// Why: streaming methods emit multiple responses over a long-lived connection.
-// The `stream` flag lets the dispatcher distinguish them from one-shot methods
-// and route them to the emit-based call path instead of the Promise-based one.
+// Why: the `stream` flag lets the dispatcher route these to the emit-based path instead of the one-shot Promise path.
 export type RpcStreamingMethod = {
   readonly name: string
   readonly params: ZodType | null
@@ -181,10 +154,7 @@ export class InvalidArgumentError extends Error {
   }
 }
 
-// Why: zod aggregates all failing fields into `issues`, but the CLI surfaces
-// a single string to users. Pick the first issue's message so callers see a
-// message that matches the original handler's `Missing terminal handle`-style
-// phrasing (each schema supplies that literal message on its own constraint).
+// Why: CLI surfaces one string; take the first issue's message, which each schema authors as the user-facing phrasing.
 export function formatZodError(error: ZodError): string {
   const first = error.issues[0]
   return first?.message ?? 'invalid_argument'
diff --git a/src/main/runtime/rpc/methods/orchestration.ts b/src/main/runtime/rpc/methods/orchestration.ts
index bd2721d1b99..7a731f91774 100644
--- a/src/main/runtime/rpc/methods/orchestration.ts
+++ b/src/main/runtime/rpc/methods/orchestration.ts
@@ -55,8 +55,7 @@ const SendParams = z
     priority: z.enum(['normal', 'high', 'urgent']).optional(),
     threadId: OptionalString,
     payload: OptionalString,
-    // Why: the sender's pane key is the remint-stable identity used to verify
-    // worker_done/heartbeat ownership; the from handle stays routing metadata.
+    // Why: pane key is the remint-stable identity used to verify worker_done/heartbeat ownership; the from handle stays routing metadata.
     senderPaneKey: OptionalString,
     devMode: OptionalBoolean
   })
@@ -67,8 +66,7 @@ const SendParams = z
     ) {
       return
     }
-    // Why: dispatch lifecycle messages are authority/liveness signals for one
-    // coordinator. Fanout creates lifecycle mail in unrelated terminals.
+    // Why: dispatch lifecycle messages are authority/liveness signals for one coordinator; fanout would create lifecycle mail in unrelated terminals.
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
       message: getLifecycleGroupRecipientError(params.type),
@@ -81,9 +79,7 @@ const CheckParams = z
     terminal: OptionalString,
     unread: OptionalBoolean,
     peek: OptionalBoolean,
-    // Why: `all` surfaces every message for the handle and skips mark-read.
-    // Previously the only way to ask for "all" was the hidden RPC trick
-    // `{unread: false}`. See design doc §3.2 / §3.3.
+    // Why: `all` surfaces every message and skips mark-read; legacy encoding was the `{unread: false}` trick (design doc §3.2/§3.3).
     all: OptionalBoolean,
     types: OptionalString,
     inject: OptionalBoolean,
@@ -91,9 +87,7 @@ const CheckParams = z
     timeoutMs: OptionalFiniteNumber
   })
   .superRefine((params, ctx) => {
-    // Why: the CLI encodes --peek as {peek:true, unread:false} so pre-peek
-    // runtimes degrade to the non-consuming all mode; that pair is one mode,
-    // not a conflict.
+    // Why: CLI encodes --peek as {peek:true, unread:false} for pre-peek runtimes, so that pair is one mode, not a conflict.
     const modes = [
       params.unread === true,
       params.peek === true,
@@ -115,9 +109,7 @@ const ReplyParams = z.object({
 
 const InboxParams = z.object({
   limit: OptionalFiniteNumber,
-  // Why: filters the inbox listing to a specific handle so coordinators can
-  // ask "everything for this handle" with either `inbox` or `check --all`
-  // and get agreeing results. See design doc §3.3.
+  // Why: filters the inbox to a handle so inbox and check --all give agreeing results (design doc §3.3).
   terminal: OptionalString
 })
 
@@ -133,8 +125,7 @@ const TaskCreateParams = z.object({
 const TaskListParams = z.object({
   status: z.enum(['pending', 'ready', 'dispatched', 'completed', 'failed', 'blocked']).optional(),
   ready: OptionalBoolean,
-  // Why: truncating specs server-side keeps `--brief` cheap over SSH/relay
-  // transports instead of shipping full specs the CLI then throws away.
+  // Why: server-side truncation keeps --brief cheap over SSH/relay instead of shipping full specs the CLI throws away.
   brief: OptionalBoolean
 })
 
@@ -158,9 +149,7 @@ const TaskUpdateParams = z.object({
 
 const DispatchParams = z.object({
   task: requiredString('Missing --task'),
-  // Why: --to is only required for real dispatches. When --dry-run is set the
-  // caller is previewing the preamble and no terminal is targeted, so allow it
-  // to be absent. The handler enforces presence before any side-effecting work.
+  // Why: --to is optional so --dry-run can preview without a target; the handler enforces presence before any side-effecting work.
   to: OptionalString,
   from: OptionalString,
   inject: OptionalBoolean,
@@ -209,8 +198,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
     handler: async (params, { runtime }) => {
       const db = runtime.getOrchestrationDb()
       const from = params.from ?? 'unknown'
-      // Why: older live shells may lack ORCA_PANE_KEY, but the runtime still
-      // knows the pane behind their resolved handle; persist that authority.
+      // Why: older shells may lack ORCA_PANE_KEY, but the runtime still knows the pane behind their handle; persist that authority.
       const senderPaneKey = params.senderPaneKey ?? runtime.getTerminalPaneKey(from) ?? undefined
 
       if (!isGroupAddress(params.to)) {
@@ -226,14 +214,10 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
           payload: params.payload,
           senderPaneKey
         })
-        // Why: worker_done/heartbeat sent via `send` must release the dispatch
-        // lock before waking recipients — a coordinator woken by delivery may
-        // immediately dispatch to the same terminal, which fails if the lock
-        // is still held.
+        // Why: reconcile releases the dispatch lock before waking recipients, else a woken coordinator re-dispatches while the lock is still held.
         if (msg.type === 'worker_done' || msg.type === 'heartbeat') {
           const reconciled = reconcileLifecycleMessage(db, msg)
-          // Why: a suppressed message is already read; waking a `check --wait`
-          // waiter for it would return an empty result before the deadline.
+          // Why: a suppressed message is already read, so skip the notify that would wake a check --wait waiter to an empty result.
           if (reconciled.action === 'suppressed') {
             return { message: msg }
           }
@@ -249,9 +233,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         return { message: msg }
       }
 
-      // Why: group addresses fan out to one message per recipient so each gets
-      // independent read-tracking, but they share a thread_id so the conversation
-      // can be correlated (Section 4.5).
+      // Why: fan out one message per recipient (independent read-tracking) but share a thread_id for correlation (Section 4.5).
       const { terminals } = await runtime.listTerminals()
       const handles = resolveGroupAddress(params.to, from, terminals, (handle: string) =>
         runtime.getAgentStatusForHandle(handle)
@@ -301,10 +283,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         throw new Error(`Invalid --types: ${invalidTypes.join(',')}`)
       }
 
-      // Why: `all` short-circuits to "everything for the handle, no marking."
-      // Explicit `unread: false` is also honored for one release as a compat
-      // shim so in-flight callers don't break (see design doc §5). Otherwise
-      // today's behavior is preserved: default is unread-only + mark-read.
+      // Why: unread:false is honored for one release as a compat shim so in-flight callers don't break (design doc §5).
       const showAll = params.all === true || (params.unread === false && params.peek !== true)
       const consumeUnread = !showAll && params.peek !== true
 
@@ -315,9 +294,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
 
         let visibleMessages = messages
         if (consumeUnread && messages.length > 0) {
-          // Why: manual coordinators can consume lifecycle messages before
-          // the coordinator loop sees them, but unread `check` is still an
-          // authoritative read path for worker_done/heartbeat.
+          // Why: unread check is an authoritative read path for worker_done/heartbeat, so reconcile lifecycle messages here too.
           visibleMessages = messages.map((message) => {
             const reconciled = reconcileLifecycleMessage(db, message)
             return reconciled.action === 'rejected'
@@ -343,12 +320,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         return result
       }
 
-      // Why: blocking wait lets coordinators replace sleep+poll loops with a
-      // single call that resolves when a message arrives or the timeout
-      // expires. The `signal` plumbed from the RPC transport aborts this
-      // waiter the moment the client socket closes, so a killed client
-      // releases its long-poll slot immediately rather than after the full
-      // timeoutMs. See design doc §3.1 counter-lifecycle.
+      // Why: signal aborts this waiter when the client socket closes, freeing the long-poll slot immediately rather than after timeoutMs (design doc §3.1).
       await runtime.waitForMessage(handle, {
         typeFilter: typeFilter as string[] | undefined,
         timeoutMs: params.timeoutMs ?? undefined,
@@ -391,10 +363,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
     params: InboxParams,
     handler: (params, { runtime }) => {
       const db = runtime.getOrchestrationDb()
-      // Why: when `terminal` is provided, mirror `check --all` output for that
-      // handle (same rows in the same sequence order). Stale/unknown handles
-      // return an empty list instead of erroring, matching the "historical
-      // rows survive handle deletion" rule in design doc §3.3.
+      // Why: stale/unknown handles return empty rather than error — historical rows survive handle deletion (design doc §3.3).
       const messages = params.terminal
         ? db.getAllMessagesForHandle(params.terminal, params.limit)
         : db.getInbox(params.limit)
@@ -436,10 +405,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
     params: TaskListParams,
     handler: (params, { runtime }) => {
       const db = runtime.getOrchestrationDb()
-      // Why: listTasksWithDispatch returns the same rows as listTasks plus
-      // assignee_handle + dispatch_id joined in for tasks that currently have an
-      // active dispatch. Non-dispatched tasks get NULL for those fields, so
-      // consumers reading the legacy shape are unaffected.
+      // Why: listTasksWithDispatch adds assignee_handle + dispatch_id (NULL for non-dispatched), so legacy-shape consumers are unaffected.
       const joined = db.listTasksWithDispatch({
         status: params.status as TaskStatus,
         ready: params.ready
@@ -481,13 +447,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         throw new Error(`Task not found: ${params.task}`)
       }
 
-      // Why: --inject --dry-run lets a coordinator preview the exact preamble
-      // text that would be injected without mutating task state or touching the
-      // target terminal. Skips the ready-status check so coordinators can inspect
-      // the preamble for already-dispatched or blocked tasks too. No dispatch
-      // context exists yet (that happens after the ready-status check), so
-      // dispatchId is a placeholder — the real injected preamble gets a real
-      // ctx.id below.
+      // Why: dry-run previews the preamble without mutating state, so it skips the ready-status check and uses a placeholder dispatchId.
       if (params.dryRun) {
         const preamble = buildDispatchPreamble({
           taskId: task.id,
@@ -512,10 +472,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         throw new Error(`Task ${params.task} is ${task.status}; only ready tasks can be dispatched`)
       }
 
-      // Why: dispatching with --inject to a bare shell (zsh/bash) dumps the
-      // preamble as shell commands, producing gibberish. Check both OSC title
-      // status and foreground process — Claude Code doesn't emit recognized OSC
-      // titles on startup, so title-only detection misses freshly spawned agents.
+      // Why: injecting the preamble into a bare shell dumps it as shell commands (gibberish), so require a detected agent first.
       if (params.inject) {
         const hasAgent = await runtime.isTerminalRunningAgent(to)
         if (!hasAgent) {
@@ -533,10 +490,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         runtime.getTerminalPaneKey(to) ?? undefined
       )
 
-      // Why: preamble is built here (not before ctx) so `dispatchId` can be
-      // the real ctx.id — the preamble-hardening PR made dispatchId required
-      // so heartbeats can attribute liveness to a specific dispatch context,
-      // not just a task.
+      // Why: built after ctx so dispatchId is the real ctx.id, letting heartbeats attribute liveness to a specific dispatch context, not just a task.
       const preamble = buildDispatchPreamble({
         taskId: task.id,
         dispatchId: ctx.id,
@@ -558,9 +512,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         }
       }
 
-      // Why: returnPreamble is opt-in because the preamble is several hundred
-      // bytes and most callers don't need it in the response. Exposing it
-      // supports coordinators that want to log what was injected for auditing.
+      // Why: returnPreamble is opt-in because the preamble is several hundred bytes most callers don't need in the response.
       if (params.returnPreamble) {
         return { dispatch: ctx, injected, preamble }
       }
@@ -578,10 +530,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
       }
       const ctx = db.getDispatchContext(params.task)
 
-      // Why: --preamble lets callers inspect the exact preamble text that was
-      // (or would be) injected for this task. The preamble is derived from the
-      // current task spec, so even after dispatch completes the text can be
-      // regenerated deterministically.
+      // Why: the preamble is derived from the current task spec, so it can be regenerated deterministically even after dispatch completes.
       if (params.preamble) {
         const task = db.getTask(params.task)
         if (!task) {
@@ -590,9 +539,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         const workerHandle = ctx?.assignee_handle ?? 'worker'
         const preamble = buildDispatchPreamble({
           taskId: task.id,
-          // Why: prefer the existing dispatch context's id if we have one
-          // (so the preview matches what was actually injected); fall back
-          // to a placeholder when no dispatch has occurred yet.
+          // Why: use the real ctx.id when present so the preview matches what was injected; placeholder when no dispatch has occurred yet.
           dispatchId: ctx?.id ?? 'ctx_preview',
           taskSpec: task.spec,
           coordinatorHandle: params.from ?? 'coordinator',
@@ -611,12 +558,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
     name: 'orchestration.ask',
     params: AskParams,
     handler: async (params, { runtime, signal }) => {
-      // Why: group addresses have no unambiguous answer semantics (whose
-      // reply wins? first? consensus?) and the ~60-LOC scope is not the
-      // place to design that. Rejecting here closes the silent-timeout
-      // footgun where a worker passing `--to @reviewers` would have the
-      // decision_gate inserted against a literal string no one subscribes
-      // to. Workers that need fan-out fall back to `send --type decision_gate`.
+      // Why: group addresses have no unambiguous answer semantics; rejecting avoids a silent timeout on a decision_gate no one subscribes to.
       if (isGroupAddress(params.to)) {
         throw new Error(
           'ask does not support group addresses; use send --type decision_gate for fan-out questions'
@@ -648,11 +590,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
       const deadline = Date.now() + timeoutMs
       const afterSequence = outbound.sequence
 
-      // Why: loop with a remaining-budget guard so an unrelated distractor
-      // message that wakes waitForMessage does not cause indefinite iteration.
-      // waitForMessage is handle-scoped, so we re-query by thread on every
-      // wake-up to separate "reply in my thread arrived" from "something
-      // else was delivered to this handle."
+      // Why: waitForMessage is handle-scoped, so re-query by thread each wake and bound by remaining budget so distractor messages can't loop forever.
       while (true) {
         const replies = db.getThreadMessagesFor(threadId, from, afterSequence)
         if (replies.length > 0) {
@@ -672,8 +610,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         if (remainingMs <= 0) {
           return { answer: null, messageId: null, threadId, timedOut: true }
         }
-        // Why: if the asking client disconnects, release the waiter immediately
-        // while leaving the already-sent decision gate visible to the recipient.
+        // Why: signal releases the waiter on client disconnect while the already-sent decision gate stays visible to the recipient.
         await runtime.waitForMessage(from, { timeoutMs: remainingMs, signal })
       }
     }
diff --git a/src/main/runtime/rpc/methods/terminal.ts b/src/main/runtime/rpc/methods/terminal.ts
index 05c5045c50b..a4cc24a5776 100644
--- a/src/main/runtime/rpc/methods/terminal.ts
+++ b/src/main/runtime/rpc/methods/terminal.ts
@@ -47,12 +47,10 @@ const TERMINAL_OUTPUT_BATCH_MAX_BYTES = 64 * 1024
 // Why: remote clients can apply output pressure without pausing runtime PTY ingestion.
 const TERMINAL_MULTIPLEX_ACK_STREAM_HIGH_WATER_BYTES = 512 * 1024
 const TERMINAL_MULTIPLEX_ACK_TOTAL_HIGH_WATER_BYTES = 2 * 1024 * 1024
-// Why: pending output is held for later binary frames, so cap the encoded
-// payload bytes rather than UTF-16 code units.
+// Why: pending output becomes binary frames, so cap encoded payload bytes, not UTF-16 code units.
 const TERMINAL_MULTIPLEX_PENDING_MAX_BYTES = 256 * 1024
 const TERMINAL_QUERY_REPLAY_MAX_CHARS = 16 * 1024
-// Why: keep initial subscribe latency bounded; readiness remains observed after
-// this deadline and triggers an in-stream recovery snapshot when it arrives.
+// Why: bound initial subscribe latency; readiness after this deadline triggers an in-stream recovery snapshot.
 const MOBILE_RENDERER_MOUNT_READY_TIMEOUT_MS = 3_000
 let nextTerminalStreamId = 1
 
@@ -102,9 +100,7 @@ type TerminalMultiplexStream = {
   ackInFlightBytes: number
   supportsDesktopViewportClaims: boolean
   desktopClaimTail: Promise<boolean>
-  // Why: whether THIS stream registered a remote-desktop width driver, so
-  // detach only unregisters what it registered — a passive (viewport-less)
-  // stream sharing a client id must not release another stream's width floor.
+  // Whether THIS stream registered the width driver, so detach won't release a peer stream's floor.
   registeredRemoteDesktopDriver: boolean
   remoteDesktopSubscriptionKey: string
   pendingRemoteDesktopViewport: { cols: number; rows: number } | null
@@ -116,8 +112,7 @@ type TerminalMultiplexStream = {
   pendingOutput: TerminalOutputChunk[]
   pendingOutputBytes: number
   pendingOutputOverflowed: boolean
-  // Why: the cols the mobile client last rewrapped to. Re-stream the full
-  // scrollback only when a reflow actually changes the width.
+  // Cols the mobile client last rewrapped to; re-stream full scrollback only when width actually changes.
   lastResizeCols: number | undefined
   resizeGeneration: number
   outputBatcher: ReturnType<typeof createTerminalOutputBatcher>
@@ -126,11 +121,7 @@ type TerminalMultiplexStream = {
   unsubscribeFit: () => void
   unsubscribeDriver: () => void
   unregisterBinaryHandler: () => void
-  // Why: the exit-wait promise for this slot is only removed from the runtime's
-  // waiter set on real PTY exit. Aborting this on detach releases it on slot
-  // unsubscribe, tab-switch re-subscribe, and connection close instead of
-  // leaking a waiter (and the closed-connection handler context it captures)
-  // for the life of a never-exiting agent terminal.
+  // Why: the runtime drops the exit-waiter only on real PTY exit; abort on detach so a never-exiting agent terminal doesn't leak the waiter.
   exitWaiterAbort: AbortController
 }
 
@@ -224,8 +215,7 @@ function createTerminalOutputBatcher(onFlush: (data: string, meta?: TerminalOutp
         return
       }
       if (!timer) {
-        // Why: terminal stream output should be coalesced before crossing the
-        // network. Desktop runtime subscribers need the same burst boundary.
+        // Why: coalesce stream output before it crosses the network; desktop subscribers share the same burst boundary.
         timer = setTimeout(flush, TERMINAL_OUTPUT_FLUSH_MS)
         if (typeof timer.unref === 'function') {
           timer.unref()
@@ -301,8 +291,7 @@ function* iterateTerminalOutputFrameChunks(
   }
   const finalChunk = takeChunk()
   if (shouldDelayFinalSeq) {
-    // Why: if a future caller reports rawLength that cannot be mapped back to
-    // UTF-16 offsets, only the final frame can safely carry the high-water mark.
+    // Why: only the final frame can safely carry the high-water mark when rawLength can't map back to UTF-16 offsets.
     if (finalChunk) {
       if (delayedChunk) {
         yield { bytes: encodeTerminalStreamText(delayedChunk.text) }
@@ -327,9 +316,7 @@ function isTerminalInputLockedForClient(
   if (client?.type === 'mobile') {
     return false
   }
-  // Why: pre-refactor mobile builds did not send client metadata. Desktop
-  // callers we control now identify as desktop, so keep legacy mobile input
-  // working without opening the new desktop path.
+  // Why: pre-refactor mobile builds sent no client metadata, so treat a missing client as legacy mobile (unlocked).
   if (!client) {
     return false
   }
@@ -340,8 +327,7 @@ async function assertTerminalSendTextWithinLimit(text: string | undefined): Prom
   if (!text) {
     return
   }
-  // Why: runtime/mobile sends can be paste-sized; validate outside Zod so
-  // accepted large input yields before terminal runtime dispatch.
+  // Why: sends can be paste-sized; validate outside Zod so large input yields before runtime dispatch.
   if (await isTerminalInputTooLargeWithYield(text, TERMINAL_INPUT_MAX_BYTES)) {
     throw new InvalidArgumentError(TERMINAL_INPUT_TOO_LARGE_ERROR)
   }
@@ -407,8 +393,7 @@ async function commitMobileInputFloorClaim(claim: MobileInputFloorClaimHolder):
   try {
     await current.commit()
   } finally {
-    // Why: the runtime may yield before the next chunk/suffix, so that write
-    // needs a fresh reservation if desktop reclaimed the floor meanwhile.
+    // Why: the runtime may yield before the next write, which then needs a fresh reservation if desktop reclaimed the floor.
     if (claim.current === current) {
       claim.current = null
     }
@@ -610,8 +595,7 @@ function* iterateTerminalStreamTextPayloads(data: string): Generator<Uint8Array<
 }
 
 function isTerminalReadPayloadIncomplete(read: { truncated: boolean; limited?: boolean }): boolean {
-  // Why: uncursored terminal reads are bounded previews; limited previews are
-  // incomplete stream payloads even when the retained buffer was not truncated.
+  // Why: a limited preview is an incomplete payload even when the retained buffer wasn't truncated.
   return read.truncated || read.limited === true
 }
 
@@ -730,8 +714,7 @@ async function serializeStableMobileRendererSnapshot(
   const candidates = [MOBILE_SUBSCRIBE_SCROLLBACK_ROWS, 500, 250, 100, 25, 0]
   let candidateIndex = 0
   for (let attempt = 0; attempt < candidates.length; attempt += 1) {
-    // Why: stability retries share the six-call snapshot budget. Advance
-    // toward zero scrollback so the final attempt always has a bounded payload.
+    // Why: advance toward zero scrollback each retry so the final attempt always has a bounded payload.
     candidateIndex = Math.max(candidateIndex, attempt)
     const rows = candidates[candidateIndex]
     const outputSequenceBefore = runtime.getPtyOutputSequence(ptyId)
@@ -761,12 +744,7 @@ async function serializeStableMobileRendererSnapshot(
   return null
 }
 
-// Why: mobile xterm can only re-wrap SOFT-wrapped lines on a client-side
-// term.resize(); the restored scrollback snapshot contains HARD newlines from
-// the host serialization, so a width change leaves prior output wrapped at the
-// old column count. On a real reflow we re-serialize the FULL buffer at the new
-// cols and replay it, so scrollback rewraps. Alt-screen TUIs are PTY-repainted
-// and have no scrollback, so they keep the geometry-only Resized frame.
+// Why: mobile xterm can't rewrap the HARD newlines baked into a restored snapshot, so a real reflow re-serializes and replays the FULL buffer at the new cols.
 async function sendMobileResizeRestream(
   runtime: OrcaRuntimeService,
   ptyId: string,
@@ -774,8 +752,7 @@ async function sendMobileResizeRestream(
   event: { cols: number; rows: number; displayMode: string; reason: string; seq?: number },
   shouldSend?: () => boolean
 ): Promise<boolean> {
-  // Why: only a true PTY geometry reflow rewraps scrollback; mode-change ticks
-  // that did not change dims would re-send the whole buffer for nothing.
+  // Why: only a true geometry reflow rewraps scrollback; a dimensionless mode-change would re-send the whole buffer for nothing.
   if (event.reason !== 'apply-layout' || runtime.isTerminalAlternateScreen(ptyId)) {
     return false
   }
@@ -810,9 +787,7 @@ async function updateViewportForClient(
   client: TerminalViewportClient,
   viewport: { cols: number; rows: number },
   defaultType: 'mobile' | 'desktop',
-  // Why: the one-shot `terminal.updateViewport` RPC has no disconnect hook, so
-  // it must only refresh a floor the client already owns via its stream (never
-  // create a leak-prone standalone one). Stream paths that own cleanup register.
+  // Why: the one-shot RPC has no disconnect hook, so 'refresh' only updates a stream-owned floor; stream paths that own cleanup 'register'.
   registration: 'register' | 'refresh' = 'register',
   claim = false
 ): Promise<{ updated: boolean; applied: boolean }> {
@@ -820,8 +795,7 @@ async function updateViewportForClient(
   if (type === 'mobile') {
     return runtime.updateMobileViewport(ptyId, client.id, viewport)
   }
-  // Why: stream attachment observes geometry without taking control. Only a
-  // later activity/claim frame may make this desktop authoritative.
+  // Why: stream attachment observes geometry without taking control; a later claim frame makes it authoritative.
   const updated =
     registration === 'refresh'
       ? await runtime.refreshRemoteDesktopViewer(
@@ -884,9 +858,7 @@ const TerminalRead = TerminalHandle.extend({
   limit: OptionalFiniteNumber
 })
 
-// Why: the legacy handler allowed `title: string | null` and rejected every
-// other shape (including `undefined`) with a specific message, which is how
-// the CLI signals an intentional "reset". Preserve that distinction exactly.
+// Why: preserve the legacy contract — `title: string | null` only, `undefined` rejected, so the CLI's "reset" signal stays distinct.
 const TerminalRename = TerminalHandle.extend({
   title: z.custom<string | null>((value) => value === null || typeof value === 'string', {
     message: 'Missing --title (pass empty string or null to reset)'
@@ -898,14 +870,9 @@ const TerminalSend = TerminalHandle.extend({
   enter: z.unknown().optional(),
   interrupt: z.unknown().optional(),
   requireAgentStatus: z.enum(['sendable']).optional(),
-  // Why: terminal-generated replies are valid input bytes but are not a user
-  // action that should transfer the shared terminal floor.
+  // Why: terminal-generated replies are valid input but must not transfer the shared terminal floor.
   inputKind: z.enum(['query-reply']).optional(),
-  // Why: identifies the caller for the driver state machine. Optional for
-  // backward compatibility with older mobile clients (server falls back to
-  // the most recent mobile actor when absent). New mobile builds populate
-  // this so multi-mobile semantics resolve correctly. See
-  // docs/mobile-presence-lock.md.
+  // Why: identifies the caller for the driver state machine; when absent (older clients) the server falls back to the most recent mobile actor (docs/mobile-presence-lock.md).
   client: z
     .object({
       id: requiredString('Missing client ID'),
@@ -1051,25 +1018,16 @@ const TerminalMultiplexSnapshotRequestFrame = z.object({
 })
 
 const TerminalSetDisplayMode = TerminalHandle.extend({
-  // Why: 'phone' was previously a "stay at phone dims after unsubscribe"
-  // mode that the toggle UI never produced and nothing in product
-  // depended on. Removed in favor of two clean modes: 'auto' (mobile
-  // drives dims while subscribed, desktop restores on last-leave) and
-  // 'desktop' (no resize, mobile scales the wide canvas down to fit).
+  // Why: 'auto' = mobile drives dims while subscribed (desktop restores on last-leave); 'desktop' = no resize, mobile scales to fit.
   mode: z.enum(['auto', 'desktop']),
-  // Why: identifies the caller for the driver state machine. Optional for
-  // backward compatibility with older mobile clients.
+  // Why: identifies the caller for the driver state machine; optional for older mobile clients.
   client: z
     .object({
       id: requiredString('Missing client ID'),
       type: z.enum(['mobile', 'desktop']).default('desktop').optional()
     })
     .optional(),
-  // Why: subscribers that registered before viewport was measured have
-  // a null viewport on their record. Toggling to 'auto' would no-op
-  // because applyMobileDisplayMode skips phone-fit when viewport is
-  // missing. Allow the toggle to carry the latest measured viewport so
-  // the server can store it on the subscriber record before fitting.
+  // Why: carries the measured viewport so an 'auto' toggle on a viewport-less record can phone-fit instead of no-op'ing.
   viewport: z
     .object({
       cols: z.number().int().positive(),
@@ -1080,10 +1038,7 @@ const TerminalSetDisplayMode = TerminalHandle.extend({
 
 const TerminalUnsubscribe = z.object({
   subscriptionId: requiredString('Missing subscription ID'),
-  // Why: required when subscribe registered the cleanup under the composite
-  // key `${terminal}:${clientId}`. If the caller passes a bare-handle
-  // subscriptionId (older clients), the server reconstructs the composite
-  // key from `client.id`. See docs/mobile-presence-lock.md.
+  // Why: lets the server rebuild the composite `${terminal}:${clientId}` cleanup key when older clients pass a bare subscriptionId (docs/mobile-presence-lock.md).
   client: z
     .object({
       id: requiredString('Missing client ID')
@@ -1091,14 +1046,7 @@ const TerminalUnsubscribe = z.object({
     .optional()
 })
 
-// Why: in-place viewport update for an existing mobile subscription. Used
-// when the keyboard opens/closes on the mobile client and the visible
-// terminal area changes — without this, the mobile app had to
-// unsubscribe → resubscribe, which (a) flashed the desktop lock banner
-// during the brief idle gap and (b) caused the new subscribe to capture
-// the already-phone-fitted PTY size as its restore baseline, leaving the
-// PTY stuck at phone dims after the phone disconnected. See
-// docs/mobile-presence-lock.md.
+// Why: in-place update avoids an unsubscribe→resubscribe that flashed the lock banner and stranded the PTY at phone dims (docs/mobile-presence-lock.md).
 const TerminalUpdateViewport = TerminalHandle.extend({
   client: z.object({
     id: requiredString('Missing client ID'),
@@ -1111,9 +1059,7 @@ const TerminalUpdateViewport = TerminalHandle.extend({
   claim: z.boolean().optional()
 })
 
-// Why: phone-fit auto-restore preference (docs/mobile-fit-hold.md). `null`
-// means Indefinite; finite millisecond values are clamped server-side
-// into [5_000, 60min] before persistence.
+// Why: phone-fit auto-restore preference (docs/mobile-fit-hold.md); `null` = Indefinite, finite ms clamped to [5_000, 60min] server-side.
 const TerminalSetAutoRestoreFit = z.object({
   ms: z.number().nullable()
 })
@@ -1212,9 +1158,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       ) {
         throw new InvalidArgumentError('Invalid terminal query reply')
       }
-      // Why: guarded resolution — a stale handle must fail with
-      // terminal_handle_stale (clients recover by re-deriving the handle)
-      // instead of evaluating driver/lock state against the wrong PTY (#7718).
+      // Why: a stale handle must fail with terminal_handle_stale, not evaluate driver/lock state against the wrong PTY (#7718).
       const leaf = runtime.resolveLiveLeafForHandle(params.terminal)
       const driver = leaf?.ptyId ? runtime.getDriver(leaf.ptyId) : null
       if (
@@ -1255,8 +1199,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           'refresh',
           true
         )
-        // Why: a stream-less request has no lifecycle cleanup and cannot safely
-        // create ownership. Never write at stale geometry if no stream exists.
+        // Why: a stream-less request can't safely create ownership, so never write at stale geometry.
         if (!claim.updated || isTerminalInputLockedForClient(runtime, leaf.ptyId, params.client)) {
           return {
             send: {
@@ -1270,8 +1213,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       const hasText = typeof params.text === 'string' && params.text.length > 0
       const hasSuffix = params.enter === true || params.interrupt === true
       if (params.requireAgentStatus === 'sendable' && hasText && hasSuffix) {
-        // Why: guarded sends are two-phase writes. Reject combined payload +
-        // submit so guard flips cannot create ambiguous partial delivery.
+        // Why: guarded sends are two-phase; reject combined payload + submit so a guard flip can't cause partial delivery.
         return {
           send: {
             handle: params.terminal,
@@ -1280,8 +1222,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           }
         }
       }
-      // Why: selected note sends submit with Enter. The runtime must recheck
-      // permission/no-agent state immediately before accepting the PTY write.
+      // Why: recheck permission/no-agent state immediately before accepting the PTY write.
       const assertSendPreconditions =
         params.requireAgentStatus === 'sendable'
           ? async (ptyId?: string): Promise<void> => {
@@ -1381,11 +1322,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       if (result.accepted !== true) {
         mobileFloorClaim.current?.rollback()
       }
-      // Why: deliberate mobile input is a take-floor action. Drives the
-      // `* → mobile{clientId}` driver transition so the desktop banner
-      // remounts (if previously reclaimed) and active phone-fit dims follow
-      // the most recent actor. Clientless sends are old mobile builds, so use
-      // the current mobile driver as their compatibility identity.
+      // Why: deliberate mobile input takes the floor (drives `* → mobile{clientId}`); clientless sends fall back to the current mobile driver.
       return { send: result }
     }
   }),
@@ -1451,9 +1388,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
     name: 'terminal.resizeForClient',
     params: TerminalResizeForClient,
     handler: async (params, { runtime }) => {
-      // Why: guarded resolution — a stale handle (pane's PTY replaced under it)
-      // must fail with terminal_handle_stale instead of resizing the wrong PTY
-      // (#7718). Clients recover by re-deriving the handle.
+      // Why: a stale handle must fail with terminal_handle_stale, not resize the wrong PTY (#7718).
       const leaf = runtime.resolveLiveLeafForHandle(params.terminal)
       if (!leaf?.ptyId) {
         throw new Error('no_connected_pty')
@@ -1515,16 +1450,12 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
     name: 'terminal.setDisplayMode',
     params: TerminalSetDisplayMode,
     handler: async (params, { runtime }) => {
-      // Why: guarded resolution — a stale handle must fail with
-      // terminal_handle_stale instead of mutating the wrong PTY's display
-      // mode/viewport (#7718). Clients recover by re-deriving the handle.
+      // Why: a stale handle must fail with terminal_handle_stale, not mutate the wrong PTY's display mode/viewport (#7718).
       const leaf = runtime.resolveLiveLeafForHandle(params.terminal)
       if (!leaf?.ptyId) {
         throw new Error('no_connected_pty')
       }
-      // Why: late-bind viewport for callers that subscribed in desktop
-      // mode (no viewport stored). Without this, a 'auto' toggle on a
-      // viewport-less record skips phone-fit and the user sees no resize.
+      // Why: late-bind viewport for desktop-subscribed callers; otherwise an 'auto' toggle skips phone-fit and nothing resizes.
       if (params.viewport && params.client?.id) {
         runtime.updateMobileSubscriberViewport(leaf.ptyId, params.client.id, params.viewport)
       }
@@ -1540,9 +1471,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
     name: 'terminal.restoreFit',
     params: TerminalHandle,
     handler: async (params, { runtime }) => {
-      // Why: guarded resolution — a stale handle must fail with
-      // terminal_handle_stale instead of reclaiming the wrong PTY back to
-      // desktop dims (#7718). Clients recover by re-deriving the handle.
+      // Why: a stale handle must fail with terminal_handle_stale, not reclaim the wrong PTY to desktop dims (#7718).
       const leaf = runtime.resolveLiveLeafForHandle(params.terminal)
       if (!leaf?.ptyId) {
         throw new Error('no_connected_pty')
@@ -1564,9 +1493,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
     name: 'terminal.updateViewport',
     params: TerminalUpdateViewport,
     handler: async (params, { runtime }) => {
-      // Why: guarded resolution — a stale handle must fail with
-      // terminal_handle_stale instead of writing viewport state to the wrong
-      // PTY (#7718). Clients recover by re-deriving the handle.
+      // Why: a stale handle must fail with terminal_handle_stale, not write viewport state to the wrong PTY (#7718).
       const leaf = runtime.resolveLiveLeafForHandle(params.terminal)
       if (!leaf?.ptyId) {
         throw new Error('no_connected_pty')
@@ -1578,17 +1505,14 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         params.client,
         params.viewport,
         'mobile',
-        // Why: one-shot RPC with no disconnect hook — refresh the client's
-        // existing stream-owned floor only, never create a leak-prone one.
+        // Why: one-shot RPC with no disconnect hook — refresh the existing stream-owned floor, never create a leak-prone one.
         'refresh',
         params.claim === true
       )
       return { ...viewportUpdate, seq: runtime.getLayout(leaf.ptyId)?.seq }
     }
   }),
-  // Why: desktop remote sessions can have dozens of panes. One streaming RPC
-  // owns the binary socket and routes terminal slots by streamId while keeping
-  // legacy subscribe as the compatibility fallback.
+  // Why: one streaming RPC owns the binary socket and routes many panes by streamId; legacy subscribe stays as fallback.
   defineStreamingMethod({
     name: 'terminal.multiplex',
     params: TerminalMultiplex,
@@ -1619,10 +1543,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         if (closed) {
           return false
         }
-        // Why: Output `seq` is a UTF-16 high-water the client uses for frame-drop
-        // gap detection, so a seq-less Output chunk must carry the sentinel 0
-        // (== "no seq") rather than the cursor value that orders control frames;
-        // a cursor value would poison the client's expected-seq tracker.
+        // Why: a seq-less Output chunk must carry sentinel 0, not the control-frame cursor, or it poisons the client's frame-drop tracker.
         const resolvedSeq =
           typeof seq === 'number' ? seq : opcode === TerminalStreamOpcode.Output ? 0 : cursor++
         const sent = sendBinary(
@@ -1708,11 +1629,8 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           }
           const size = runtime.getTerminalSize(stream.ptyId)
           const displayMode = runtime.getMobileDisplayMode(stream.ptyId)
-          // Why: dropped ACK-pending output means live frames are no longer a
-          // complete replay. Send a fresh model snapshot before resuming output.
-          // Why: truncated marks an unusable snapshot, and clients discard
-          // those. The recovery snapshot must be applied to cover dropped
-          // output, so it is only truncated when serialization failed.
+          // Why: dropped ACK-pending output breaks live replay; send a fresh snapshot before resuming output.
+          // Why: clients discard truncated snapshots, so mark truncated only when serialization actually failed.
           sendSnapshotFrames((opcode, payload) => sendFrame(stream.streamId, opcode, payload), {
             kind: 'scrollback',
             cols: serialized?.cols ?? size?.cols ?? 80,
@@ -1726,8 +1644,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
             data: serialized?.data ?? ''
           })
           if (serialized && typeof serialized.seq === 'number') {
-            // Why: retained chunks queued before the snapshot serialized are
-            // already contained in it; replaying them would duplicate output.
+            // Why: chunks queued before the snapshot serialized are already in it; replaying them would duplicate output.
             const snapshotSeq = serialized.seq
             const retained = stream.ackPendingOutput.filter(
               (chunk) => !(typeof chunk.seq === 'number' && chunk.seq <= snapshotSeq)
@@ -1810,8 +1727,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         stream.unregisterBinaryHandler()
         streams.delete(streamId)
         flushAllAckPendingOutput()
-        // Why: release the runtime exit-waiter for this slot (see the field's
-        // note). The .catch below no-ops because the stream is already deleted.
+        // Why: release the runtime exit-waiter for this slot (see the field's note); delete before abort so its .catch no-ops instead of re-detaching.
         stream.exitWaiterAbort.abort()
         if (stream.isMobile && stream.client?.id) {
           runtime.handleMobileUnsubscribe(stream.ptyId, stream.client.id)
@@ -1820,9 +1736,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           stream.registeredRemoteDesktopDriver &&
           stream.client?.id
         ) {
-          // Why: release the remote-desktop width floor so the host can reclaim
-          // its own width once the last remote viewer leaves — but only if THIS
-          // stream took it (a passive stream must not release a peer's floor).
+          // Why: release the width floor only if THIS stream took it, so a passive stream can't release a peer's floor.
           runtime.unregisterRemoteDesktopViewer(stream.ptyId, stream.remoteDesktopSubscriptionKey)
         }
         if (emitEnd) {
@@ -1861,8 +1775,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           }
           detachStream(streamId, false, false)
         }
-        // Why: one connection can own many panes backed by the same PTY.
-        // Remove those floors together so close scans each PTY registry once.
+        // Why: one connection can own many panes on the same PTY; remove floors together so close scans each registry once.
         for (const [ptyId, subscriptionKeys] of remoteDesktopKeysByPty) {
           void runtime.unregisterRemoteDesktopViewers(ptyId, subscriptionKeys)
         }
@@ -1898,8 +1811,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           if (isTerminalInputLockedForClient(runtime, stream.ptyId, stream.client)) {
             return
           }
-          // Mobile already has the higher-priority floor; a rejected desktop
-          // viewport claim must never suppress later phone input.
+          // Mobile already has the higher-priority floor, so a rejected desktop claim must not suppress later phone input.
           const inputClaimTail = stream.isMobile ? Promise.resolve(true) : stream.desktopClaimTail
           void inputClaimTail.then((claimed) => {
             if (!claimed || isTerminalInputLockedForClient(runtime, stream.ptyId, stream.client)) {
@@ -1923,8 +1835,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           }
           const cols = viewport.cols
           const rows = viewport.rows
-          // Why: resize registers stream-scoped geometry so detach can release
-          // it. Older clients lack explicit claims, so Resize remains control.
+          // Why: resize registers stream-scoped geometry so detach can release it; older clients lack explicit claims.
           if (!stream.isMobile && stream.client?.id) {
             stream.registeredRemoteDesktopDriver = true
             if (stream.buffering) {
@@ -2020,8 +1931,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           let size = runtime.getTerminalSize(stream.ptyId)
           let displayMode = runtime.getMobileDisplayMode(stream.ptyId)
           if (stream.pendingOutputOverflowed) {
-            // Why: the overflowed tail is newer than the first snapshot. Retry
-            // so hidden restore receives a current terminal image instead of null.
+            // Why: the overflowed tail is newer than the first snapshot, so retry for a current image instead of null.
             stream.pendingOutput.splice(0)
             stream.pendingOutputBytes = 0
             stream.pendingOutputOverflowed = false
@@ -2082,9 +1992,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
             stream.pendingOutputBytes = 0
             stream.pendingOutputOverflowed = false
             stream.outputBatcher.flush()
-            // Why: a viewer resize that arrived during the snapshot buffering
-            // window is parked in pendingRemoteDesktopViewport; apply it now or
-            // it is silently dropped until the viewer's next resize.
+            // Why: a resize parked during snapshot buffering must be applied now, or it is dropped until the viewer's next resize.
             if (
               !stream.isMobile &&
               stream.client?.id &&
@@ -2119,10 +2027,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         const isMobile = request.client?.type === 'mobile'
         let leaf: { ptyId: string | null } | null
         try {
-          // Why: guarded resolution — binding the output stream to whatever
-          // PTY now occupies a stale handle's pane silently mirrors the wrong
-          // terminal after a reconnect (#7718). terminal_handle_stale lets the
-          // client re-derive the handle from the current session snapshot.
+          // Why: binding the stream to whatever PTY now occupies a stale handle's pane would mirror the wrong terminal (#7718).
           leaf = runtime.resolveLiveLeafForHandle(request.terminal)
         } catch {
           sendStreamError(request.streamId, 'terminal_handle_stale')
@@ -2130,8 +2035,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           return
         }
         if (!leaf?.ptyId && request.client) {
-          // Why: a never-mounted tab has no graph leaf to await; mounting the
-          // exact tab lets its PTY attach without activating the worktree.
+          // Why: a never-mounted tab has no graph leaf to await; mounting the exact tab attaches its PTY without activating the worktree.
           runtime.requestRendererTerminalTabMount(request.terminal)
           const waitController = new AbortController()
           const pendingControllers = pendingPtyWaitControllers.get(request.streamId) ?? new Set()
@@ -2140,8 +2044,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           if (signal?.aborted) {
             waitController.abort()
           }
-          // Why: the live slot handler does not exist until the PTY attaches;
-          // retain cancellation ownership while the pane is still pending.
+          // Why: the live slot handler does not exist until the PTY attaches; retain cancellation ownership while the pane is still pending.
           const unregisterPendingHandler = registerBinaryStreamHandler(
             request.streamId,
             (frame) => {
@@ -2180,12 +2083,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         if (closed) {
           return
         }
-        // Why: a competing subscribe for the same streamId can fully register
-        // while this one awaited the PTY id above. Overwriting it in
-        // `streams` would orphan its data/view-subscriber registrations — a
-        // leaked view subscriber permanently silences the model query
-        // responder (terminal-query-authority.md). Detach it so every
-        // registration stays release-balanced.
+        // Why: a competing subscribe may own this streamId after the PTY await; detach it so an orphaned view subscriber can't silence the model responder (terminal-query-authority.md).
         detachStream(request.streamId, false)
 
         const ptyId = leaf.ptyId
@@ -2200,10 +2098,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           supportsDesktopViewportClaims: request.capabilities?.desktopViewportClaims === 1,
           desktopClaimTail: Promise.resolve(true),
           registeredRemoteDesktopDriver: false,
-          // Why: streamId is client-local, so two remote connections can both
-          // use stream 1 for the same PTY. Scope the width-floor key by
-          // connectionId (guaranteed present above) so they can't
-          // overwrite/release each other's floor.
+          // Why: streamId is client-local, so key the width floor by connectionId or two connections sharing stream 1 for one PTY clobber each other's floor.
           remoteDesktopSubscriptionKey: `multiplex:${connectionId}:${request.streamId}`,
           pendingRemoteDesktopViewport: null,
           buffering: true,
@@ -2252,10 +2147,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
             }
             stream.outputBatcher.push(data, meta)
           })
-          // Why: a multiplexed stream feeds a remote xterm view that answers
-          // terminal queries with view authority; the main model responder
-          // yields while it is attached (terminal-query-authority.md).
-          // Wrapped into unsubscribeData so every detach path releases it.
+          // Why: a multiplexed stream feeds a remote xterm view with query authority, so the main model responder yields while attached (terminal-query-authority.md).
           const releaseViewSubscriber = runtime.registerRemoteTerminalViewSubscriber(ptyId)
           stream.unsubscribeData = () => {
             releaseViewSubscriber()
@@ -2265,8 +2157,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           if (isMobile && request.client?.id) {
             await runtime.handleMobileSubscribe(ptyId, request.client.id, request.viewport)
           } else if (request.client?.id && request.viewport) {
-            // Why: subscribe records this stream's geometry and cleanup key,
-            // but does not claim ownership. Activity frames claim later.
+            // Why: subscribe records this stream's geometry and cleanup key but doesn't claim ownership; activity frames claim later.
             stream.registeredRemoteDesktopDriver = true
             stream.pendingRemoteDesktopViewport = request.viewport
           }
@@ -2348,8 +2239,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
             pendingEscapeTailAnsi: serialized?.pendingEscapeTailAnsi,
             data: serialized?.data ?? (read.tail.length > 0 ? `${read.tail.join('\r\n')}\r\n` : '')
           })
-          // Why: baseline for resize re-stream gating; the client already
-          // rewrapped to these cols via the initial snapshot replay.
+          // Why: baseline for resize re-stream gating; the client already rewrapped to these cols via the initial snapshot replay.
           stream.lastResizeCols = serialized?.cols ?? size?.cols
           stream.buffering = false
           const pendingOutput = stream.pendingOutput.splice(0)
@@ -2411,9 +2301,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
             const widthChanged = stream.isMobile && event.cols !== stream.lastResizeCols
             if (widthChanged) {
               stream.lastResizeCols = event.cols
-              // Why: re-serialize+replay the full scrollback at the new cols so
-              // restored hard-wrapped lines rewrap; the await means later live
-              // output still flows on this stream after the snapshot lands.
+              // Why: re-serialize+replay the full scrollback at the new cols so restored hard-wrapped lines rewrap; live output resumes after the snapshot lands.
               void sendMobileResizeRestream(
                 runtime,
                 ptyId,
@@ -2436,8 +2324,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
                     sendResizedFrame(stream, event)
                   }
                 })
-                // Why: if re-stream serialization/runtime throws, still emit the
-                // geometry-only Resized frame so the client never misses the resize.
+                // Why: on re-stream failure, still emit the geometry-only Resized frame so the client never misses the resize.
                 .catch(() => {
                   if (
                     closed ||
@@ -2452,8 +2339,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
             }
             sendResizedFrame(stream, event)
           })
-          // Install the resize listener before draining the parked viewport;
-          // applyLayout emits synchronously and the stream must observe it.
+          // Install the resize listener before draining the parked viewport, since applyLayout emits synchronously.
           if (
             !stream.isMobile &&
             stream.client?.id &&
@@ -2489,10 +2375,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
               }
             })
         } catch (error) {
-          // Why the ownership check: a newer subscribe may own this streamId
-          // now (it detached and released this stream on arrival). Detaching
-          // or erroring the slot here would tear down the successor's live
-          // registrations instead of this stream's.
+          // Why the ownership check: a newer subscribe may already own this streamId; tearing down the slot here would kill the successor's live registrations.
           if (streams.get(request.streamId) !== stream) {
             return
           }
@@ -2518,9 +2401,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       await multiplexClosed
     }
   }),
-  // Why: terminal.subscribe streams live terminal output over WebSocket.
-  // It sends initial scrollback, then live data chunks as they arrive.
-  // Mobile clients pass client+viewport params for server-side auto-fit.
+  // terminal.subscribe: streams live terminal output over WebSocket; mobile clients pass client+viewport for server-side auto-fit.
   defineStreamingMethod({
     name: 'terminal.subscribe',
     params: TerminalSubscribe,
@@ -2536,19 +2417,14 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         : 0
       let rendererMountRequestedBeforePty = false
       const useBinaryStream = params.capabilities?.terminalBinaryStream === 1 && Boolean(sendBinary)
-      // Why: a closed stream must not allocate listeners, mobile-fit state, or
-      // a hidden renderer surface that no client remains to consume.
+      // Why: a closed stream must not allocate listeners, mobile-fit state, or a hidden renderer surface no client will consume.
       if (signal?.aborted) {
         return
       }
 
-      // Why: the left pane's PTY spawns asynchronously after the tab is created.
-      // Clients that subscribe before the PTY is ready would get a bare
-      // scrollback+end with no live stream or phone-fit. Wait for the PTY so
-      // the subscribe can proceed normally.
+      // Why: the PTY spawns asynchronously after tab creation; wait for it so an early subscribe gets a live stream instead of a bare scrollback+end.
       if (!leaf?.ptyId && params.client) {
-        // Why: a never-mounted tab has no graph leaf to await; mounting the
-        // exact tab lets its PTY attach without activating the worktree.
+        // Why: a never-mounted tab has no graph leaf to await; mounting the exact tab attaches its PTY without activating the worktree.
         rendererMountRequestedBeforePty = runtime.requestRendererTerminalTabMount(params.terminal)
         try {
           const ptyId = await runtime.waitForLeafPtyId(params.terminal, 10_000, signal)
@@ -2581,8 +2457,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       const clientId = params.client?.id
       const mobileInputLeaseOnly =
         isMobile && params.capabilities?.mobileInputLeaseOnly === 1 && Boolean(clientId)
-      // Why: the initial mount/PTY wait and phone-fit can both emit a redraw
-      // that creates suffix-only state, so preserve the pre-mount absence signal.
+      // Why: mount/PTY wait and phone-fit can each emit a redraw creating suffix-only state, so capture the pre-mount absence signal first.
       const missingHeadlessStateBeforeMobileFit =
         isMobile &&
         (rendererMountRequestedBeforePty || runtime.hasHeadlessTerminalState?.(ptyId) === false)
@@ -2599,8 +2474,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           resolveStream = resolve
         })
         const subscriptionId = `${params.terminal}:${clientId}`
-        // Why: chat needs the input-floor acknowledgement without registering
-        // a view subscriber or transporting duplicate PTY output.
+        // Why: chat needs the input-floor ack without registering a view subscriber or transporting duplicate PTY output.
         runtime.registerSubscriptionCleanup(
           subscriptionId,
           () => {
@@ -2618,8 +2492,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         try {
           await runtime.handleMobileSubscribe(ptyId, clientId, params.viewport)
           if (closed || signal?.aborted) {
-            // Why: a disconnect can win the awaited subscribe and otherwise
-            // resurrect mobile presence after cleanup already released it.
+            // Why: a disconnect can win the awaited subscribe and resurrect mobile presence after cleanup already released it.
             runtime.handleMobileUnsubscribe(ptyId, clientId)
             if (!closed) {
               runtime.cleanupSubscription(subscriptionId)
@@ -2634,13 +2507,10 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         }
         return
       }
-      // Why: only unregister the width floor this subscription took (see the
-      // multiplex stream's registeredRemoteDesktopDriver note).
+      // Why: only unregister the width floor this subscription took (see the multiplex stream's registeredRemoteDesktopDriver note).
       let registeredRemoteDesktopDriver = false
       if (!useBinaryStream) {
-        // Why: desktop can have both a hidden automation watcher and a visible
-        // pane subscribed to the same terminal. Key by client when provided so
-        // one stream cannot evict the other.
+        // Why: a hidden watcher and a visible pane can subscribe to one terminal, so key by client so neither stream evicts the other.
         const subscriptionId = clientId ? `${params.terminal}:${clientId}` : params.terminal
         const remoteDesktopSubscriptionKey = `json:${nextTerminalStreamId++}`
         let closed = false
@@ -2651,8 +2521,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         const streamClosed = new Promise<void>((resolve) => {
           resolveStream = resolve
         })
-        // Why: register before viewport/snapshot awaits so a socket close cannot
-        // orphan either the stream listeners or its remote-desktop width floor.
+        // Why: register before viewport/snapshot awaits so a socket close can't orphan the stream listeners or its remote-desktop width floor.
         runtime.registerSubscriptionCleanup(
           subscriptionId,
           () => {
@@ -2714,11 +2583,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           const unsubscribeStreamData = runtime.subscribeToTerminalData(ptyId, (data) => {
             outputBatcher?.push(data)
           })
-          // Why: this legacy JSON stream can feed a live xterm view too
-          // (older web/desktop subscribers), so it conservatively registers
-          // as a remote view subscriber. For read-only watchers the cost is
-          // a withheld model reply — the pre-Phase-5 status quo — which is
-          // strictly safer than a double reply under a view consumer.
+          // Why: the legacy JSON stream can feed a live xterm view, so register as a view subscriber; worst case is a withheld model reply, safer than a double reply.
           const releaseViewSubscriber = runtime.registerRemoteTerminalViewSubscriber(ptyId)
           unsubscribeData = () => {
             releaseViewSubscriber()
@@ -2738,8 +2603,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
               rows: event.rows
             })
           })
-          // Why: bind the exit-waiter to the connection dispatch signal so it is
-          // removed on socket close/error instead of leaking until real exit.
+          // Why: bind the exit-waiter to the connection signal so socket close/error removes it instead of leaking until real exit.
           void runtime
             .waitForTerminal(params.terminal, { condition: 'exit', signal })
             .then(() => runtime.cleanupSubscription(subscriptionId))
@@ -2758,8 +2622,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       let closed = false
       let buffering = true
       let pendingRemoteDesktopViewport: { cols: number; rows: number } | null = null
-      // Why: the cols the mobile client last rewrapped to; gate the
-      // resize re-stream so it only fires on an actual width change.
+      // Why: cols the mobile client last rewrapped to; gates the resize re-stream to fire only on an actual width change.
       let lastResizeCols: number | undefined
       let resizeGeneration = 0
       let pendingOutput: TerminalOutputChunk[] = []
@@ -2781,9 +2644,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       const streamClosed = new Promise<void>((resolve) => {
         resolveStream = resolve
       })
-      // Why: register cleanup before any mobile-fit or snapshot await. A phone
-      // can disconnect mid-subscribe; cleanup must still remove mobile
-      // presence. Client-scoped ids also allow parallel desktop subscribers.
+      // Why: register cleanup before any await so a mid-subscribe disconnect still removes mobile presence; client-scoped ids also allow parallel desktop subscribers.
       const subscriptionId = clientId ? `${params.terminal}:${clientId}` : params.terminal
       runtime.registerSubscriptionCleanup(
         subscriptionId,
@@ -2806,8 +2667,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         },
         connectionId
       )
-      // Why: bind the exit-waiter to the connection dispatch signal so it is
-      // removed on socket close/error instead of leaking until real exit.
+      // Why: bind the exit-waiter to the connection signal so socket close/error removes it instead of leaking until real exit.
       void runtime
         .waitForTerminal(params.terminal, { condition: 'exit', signal })
         .then(() => runtime.cleanupSubscription(subscriptionId))
@@ -2986,8 +2846,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         }
         outputBatcher?.push(data, meta)
       })
-      // Why: live bytes must be captured before mobile fit awaits. Registering
-      // mobile presence first would suppress main while no view held the query.
+      // Why: capture live bytes before mobile-fit awaits; registering presence first would suppress main while no view held the query.
       const releaseViewSubscriber = runtime.registerRemoteTerminalViewSubscriber(ptyId)
       unsubscribeData = () => {
         releaseViewSubscriber()
@@ -2998,8 +2857,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         if (isMobile && clientId) {
           await runtime.handleMobileSubscribe(ptyId, clientId, params.viewport)
         } else if (clientId && params.viewport) {
-          // Why: legacy subscribe records geometry without taking ownership;
-          // only an explicit activity/claim frame may suppress the host.
+          // Why: legacy subscribe records geometry without taking ownership; only an explicit activity/claim frame may suppress the host.
           registeredRemoteDesktopDriver = true
           pendingRemoteDesktopViewport = params.viewport
         }
@@ -3012,18 +2870,14 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         if (closed) {
           return
         }
-        // Why: missing model state—not snapshot text—is the signal that this
-        // PTY may never have attached; avoid remounting legitimate blank panes.
-        // A renderer-sourced snapshot also proves the exact pane is already
-        // attached, so waiting for a fresh mount generation would only stall.
+        // Why: missing model state (not blank snapshot text) signals a never-attached PTY; a renderer-sourced snapshot already proves attachment, so skip the remount.
         const mountRequested =
           missingHeadlessStateBeforeMobileFit &&
           serialized?.source !== 'renderer' &&
           (rendererMountRequestedBeforePty ||
             runtime.requestRendererTerminalTabMount(params.terminal))
         if (missingHeadlessStateBeforeMobileFit && mountRequested) {
-          // Why: an idle legacy PTY emits no later byte; a fresh settle proves
-          // this exact remount completed before we replay its restored screen.
+          // Why: an idle legacy PTY emits no later byte, so wait for a settle proving this remount completed before replaying its screen.
           const mountWaitController = new AbortController()
           const abortMountWait = (): void => mountWaitController.abort()
           abortRendererMountWait = abortMountWait
@@ -3084,8 +2938,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
               )
             }
           } else {
-            // Why: a renderer can settle after the bounded initial response.
-            // Keep observing it so an idle PTY still self-heals without bytes.
+            // Why: a renderer can settle after the bounded initial response; keep observing so an idle PTY self-heals without bytes.
             lateRendererReadyPromise = rendererReadyPromise
           }
         }
@@ -3108,16 +2961,10 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         }
         const size = runtime.getTerminalSize(ptyId)
         const displayMode = runtime.getMobileDisplayMode(ptyId)
-        // Why: emit the current layout seq with the initial scrollback so
-        // the mobile client's stale-event filter knows the high-water mark.
-        // Undefined when the PTY has never transitioned (filter is fail-open).
-        // See docs/mobile-terminal-layout-state-machine.md.
+        // Why: layout seq is the mobile stale-event filter's high-water mark (undefined pre-transition is fail-open). See docs/mobile-terminal-layout-state-machine.md.
         const layoutSeq = runtime.getLayout(ptyId)?.seq
         const snapshotFrameSeq = serialized?.seq ?? layoutSeq
-        // Why: recovery snapshots advance output coverage past the initial
-        // snapshot seq; query replay and boundary trims must track the seq
-        // that actually covered the buffered chunks or a query absorbed by a
-        // recovery snapshot gets zero replies.
+        // Why: track the seq that actually covered the buffered chunks (recovery snapshots advance it) or an absorbed query gets zero replies.
         let snapshotOutputSeq = serialized?.seq
         emit({
           type: 'subscribed',
@@ -3154,12 +3001,10 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           scrollbackRows: serialized?.scrollbackRows,
           truncatedByByteBudget: serialized?.truncatedByByteBudget === true
         })
-        // Why: baseline for resize re-stream gating; the client already
-        // rewrapped to these cols via the initial snapshot replay.
+        // Why: baseline for resize re-stream gating; the client already rewrapped to these cols via the initial snapshot replay.
         lastResizeCols = serialized?.cols ?? size?.cols
         let recoveryAttempts = 0
-        // Why: if the bounded pre-subscribe tail overflowed, only a fresh
-        // model snapshot can cover the dropped middle without replay gaps.
+        // Why: if the bounded pre-subscribe tail overflowed, only a fresh model snapshot covers the dropped middle without replay gaps.
         while (pendingOutputOverflowed && recoveryAttempts < 2) {
           pendingOutputOverflowed = false
           recoveryAttempts += 1
@@ -3170,18 +3015,11 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           if (!recovery) {
             break
           }
-          // Why: without an output seq (renderer-source fallback) covered
-          // chunks cannot be trimmed exactly, and the renderer view may lag
-          // the queued chunks under backpressure. Keep the bounded replay
-          // instead of applying an unverifiable snapshot.
+          // Why: without an output seq (renderer fallback) covered chunks can't be trimmed exactly, so keep the bounded replay over an unverifiable snapshot.
           if (typeof recovery.seq !== 'number') {
             break
           }
-          // Why: shipped mobile clients drop a second scrollback snapshot for
-          // an initialized handle but apply a resized snapshot inline by
-          // re-initializing xterm with fresh scrollback. Omit seq on the wire
-          // so the client's layout-seq staleness filter is not polluted with
-          // output-byte sequences.
+          // Why: clients drop a repeat scrollback snapshot but apply 'resized' inline; omit seq so output-byte seqs don't pollute the layout-seq filter.
           const recoveryStats = sendSnapshotFrames(sendFrame, {
             kind: 'resized',
             cols: recovery.cols,
@@ -3220,9 +3058,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
               .map((query) => query.data)
               .join('')
         if (queryReplayData) {
-          // Why: serialized snapshots omit control queries, yet their output seq
-          // can trim the live chunk. Replay only the query after snapshot so the
-          // mobile xterm answers once while ordinary output stays deduplicated.
+          // Why: snapshots omit control queries but their seq trims the live chunk; replay the post-snapshot query so the mobile xterm answers once.
           outputBatcher.push(queryReplayData)
         }
         if (!initialOutputOverflowed) {
@@ -3269,14 +3105,12 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
               if (!recovery?.data.length) {
                 return
               }
-              // Why: late recovery has no buffered-output gate. Only an exact
-              // renderer high-water may reset mobile without erasing live bytes.
+              // Why: late recovery has no buffered-output gate, so only an exact renderer high-water may reset mobile without erasing live bytes.
               if (recovery.seq !== runtime.getPtyOutputSequence(ptyId)) {
                 return
               }
               runtime.replaceHeadlessTerminalFromRendererSnapshotForRecovery(ptyId, recovery)
-              // Why: shipped mobile clients apply resized snapshots in place,
-              // allowing a blank initialized xterm to recover without resubscribe.
+              // Why: shipped mobile clients apply resized snapshots in place, so a blank xterm recovers without resubscribe.
               const recoveryStats = sendSnapshotFrames(sendFrame, {
                 kind: 'resized',
                 cols: recovery.cols,
@@ -3324,11 +3158,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           outputBatcher?.flush()
           const eventGeneration = resizeGeneration + 1
           resizeGeneration = eventGeneration
-          // Why: a width reflow rewraps scrollback. xterm can only re-wrap
-          // soft-wrapped lines, so a geometry-only Resized frame leaves the
-          // hard-wrapped restored snapshot at the old cols. Re-serialize and
-          // replay the full buffer at the new width instead. Non-mobile and
-          // alt-screen TUIs keep the geometry-only frame + TUI redraw.
+          // Why: xterm only re-wraps soft-wrapped lines, so a width change needs a full re-serialize+replay to rewrap restored hard-wrapped scrollback.
           const widthChanged = isMobile && event.cols !== lastResizeCols
           if (widthChanged) {
             lastResizeCols = event.cols
@@ -3347,8 +3177,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
                   sendResizedFrame(event)
                 }
               })
-              // Why: if re-stream serialization/runtime throws, still emit the
-              // geometry-only Resized frame so the client never misses the resize.
+              // Why: on re-stream failure, still emit the geometry-only Resized frame so the client never misses the resize.
               .catch(() => {
                 if (closed || resizeGeneration !== eventGeneration) {
                   return
@@ -3360,8 +3189,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           sendResizedFrame(event)
         })
 
-        // Install the resize listener before draining the parked viewport;
-        // applyLayout emits synchronously and the stream must observe it.
+        // Install the resize listener before draining the parked viewport, since applyLayout emits synchronously.
         if (
           clientId &&
           params.client &&
@@ -3410,12 +3238,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
     name: 'terminal.unsubscribe',
     params: TerminalUnsubscribe,
     handler: async (params, { runtime }) => {
-      // Why: the subscribe handler now registers cleanup under a composite
-      // key `${terminal}:${clientId}`. New mobile builds emit the composite
-      // key directly. Older builds emit a bare-handle subscriptionId; if
-      // they additionally provide `client.id`, reconstruct the composite
-      // key server-side. We always try the as-sent value first, then fall
-      // back to the reconstructed composite, so both wire formats work.
+      // Why: older builds send a bare-handle subscriptionId, so also try the reconstructed `${terminal}:${clientId}` composite key.
       runtime.cleanupSubscription(params.subscriptionId)
       if (params.client && !params.subscriptionId.includes(':')) {
         runtime.cleanupSubscription(`${params.subscriptionId}:${params.client.id}`)
diff --git a/src/main/runtime/rpc/ws-transport.ts b/src/main/runtime/rpc/ws-transport.ts
index ec106a63327..b5c74de7492 100644
--- a/src/main/runtime/rpc/ws-transport.ts
+++ b/src/main/runtime/rpc/ws-transport.ts
@@ -1,8 +1,4 @@
-// Why: the WebSocket transport enables mobile clients to connect to the Orca
-// runtime over the local network. When TLS cert/key are provided it uses wss://
-// to prevent passive sniffing; otherwise it falls back to plain ws://. Per-device
-// tokens (validated by the message handler in OrcaRuntimeRpcServer) provide auth
-// regardless of transport encryption.
+// WebSocket transport letting mobile clients reach the Orca runtime over LAN (wss:// with TLS, else ws://); auth is per-device tokens, independent of transport encryption.
 import { createServer as createHttpsServer, type Server as HttpsServer } from 'node:https'
 import { createServer as createHttpServer, type Server as HttpServer } from 'node:http'
 import { WebSocketServer, type WebSocket } from 'ws'
@@ -10,14 +6,9 @@ import type { RpcTransport } from './transport'
 import { createStaticWebClientHandler } from './static-web-client-handler'
 
 const MAX_WS_MESSAGE_BYTES = 1024 * 1024
-// Why: desktop remote-host clients can legitimately hold many concurrent
-// streams (session tabs, terminals, file watches, browser streams). Keep the
-// cap high enough that leaked/stale streams do not starve short control RPCs.
+// Why: one desktop remote-host client can hold many concurrent streams, so keep the cap high enough that stale streams don't starve control RPCs.
 const MAX_WS_CONNECTIONS = 128
-// Why: hard-bound this listener's descriptor use above the WS-upgrade cap.
-// Node accepts then drops sockets beyond maxConnections, so raw/pre-upgrade
-// clients cannot grow without bound while the existing WS budget remains
-// available to legitimate long-lived streams.
+// Why: bound pre-upgrade descriptor use above the WS cap so raw sockets can't grow without bound.
 const MAX_TCP_CONNECTIONS = MAX_WS_CONNECTIONS * 2
 const PRE_AUTH_TIMEOUT_MS = 10_000
 type WebSocketMessagePayload = string | Uint8Array<ArrayBufferLike>
@@ -29,16 +20,7 @@ type WebSocketMessageHandler = {
   ): void
 }['bivarianceHack']
 
-// Why: mobile clients (iOS/Android) regularly background-suspend their
-// sockets without the OS sending a TCP FIN/RST, leaving the server with
-// half-open WebSockets that count toward MAX_WS_CONNECTIONS. Without this
-// heartbeat the only thing that ever reaps them is the OS's TCP keepalive
-// (default macOS: ~2 hours idle + 11 min of probes), which is the
-// "connection randomly turns green again after a long delay" symptom.
-// Pinging every 15s and terminating any client that hasn't pong'd by the
-// next tick collapses that worst case to ~30s. RN/browser WebSocket
-// runtimes auto-respond to server pings with pongs at the protocol layer,
-// so this works for any client that speaks RFC 6455.
+// Why: mobile clients background-suspend sockets with no TCP FIN, leaving half-opens that otherwise only the OS keepalive (~2h) reaps; a 15s ping/pong sweep bounds that to ~30s (clients auto-pong per RFC 6455).
 const HEARTBEAT_INTERVAL_MS = 15_000
 
 export type WebSocketTransportOptions = {
@@ -50,19 +32,11 @@ export type WebSocketTransportOptions = {
   heartbeatIntervalMs?: number
   // Why: test-only override. Production uses PRE_AUTH_TIMEOUT_MS.
   preAuthTimeoutMs?: number
-  // Why: the pairing server can also serve the browser client, so users do
-  // not need a second dev/static server once the web bundle is built.
+  // Why: the pairing server can also serve the browser client, avoiding a second static server.
   staticRoot?: string
-  // Why: paired mobile devices store the full ws://ip:port endpoint. Once a
-  // fallback port has been assigned and persisted, devices paired while it was
-  // active point at it, so it must be bound FIRST on later launches — binding
-  // the (now free) preferred port instead would strand those pairings
-  // (STA-1511). Callers pass the previously assigned fallback port here.
+  // Why: devices paired while the fallback port was active point at it, so it must bind first on later launches or those pairings strand (STA-1511).
   fallbackPort?: number
-  // Why: `orca serve --port <P>` clients dial the pinned port. Prefer that port
-  // first (fallback second) so a stale mobile-ws-fallback-port.json cannot
-  // silently steal the pin (issue #8535). Default auto/desktop keeps
-  // fallback-first for STA-1511 pairing stability.
+  // Why: serve --port clients dial the pinned port; prefer it first so a stale fallback can't steal the pin (issue #8535). Default keeps fallback-first (STA-1511).
   preferPinnedPort?: boolean
 }
 
@@ -79,16 +53,13 @@ export class WebSocketTransport implements RpcTransport {
   private httpServer: HttpsServer | HttpServer | null = null
   private wss: WebSocketServer | null = null
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null
-  // Why: tracks whether each socket has pong'd since the last heartbeat
-  // sweep. A socket missing from the set when the next sweep fires is
-  // assumed dead and terminated.
+  // Why: a socket absent from this set at the next heartbeat sweep is presumed dead and terminated.
   private wsAlive = new WeakSet<WebSocket>()
   private messageHandler: WebSocketMessageHandler | null = null
   private connectionCloseHandler:
     | ((clientId: string | null, ws: WebSocket, hasOtherConnections: boolean) => void)
     | null = null
-  // Why: maps each WebSocket to the clientId (deviceToken) that authenticated it,
-  // so ws.on('close') can notify the runtime which mobile client disconnected.
+  // Why: maps each socket to its authenticated clientId so close can report which device disconnected.
   private wsClientIds = new Map<WebSocket, string>()
   private preAuthTimers = new WeakMap<WebSocket, ReturnType<typeof setTimeout>>()
 
@@ -118,12 +89,7 @@ export class WebSocketTransport implements RpcTransport {
     this.messageHandler = handler
   }
 
-  // Why: handlers receive the closing `ws` so per-connection state can be
-  // targeted exactly (one paired device may hold multiple concurrent sockets,
-  // e.g. host screen + accounts screen). `hasOtherConnections` tells the
-  // runtime whether other sockets for the same deviceToken are still alive,
-  // so client-scoped teardown (mobile-fit overrides, etc.) only fires on the
-  // last disconnect.
+  // Why: pass the closing `ws` and whether other sockets share its deviceToken, so client-scoped teardown fires only on the last disconnect.
   onConnectionClose(
     handler: (clientId: string | null, ws: WebSocket, hasOtherConnections: boolean) => void
   ): void {
@@ -140,16 +106,13 @@ export class WebSocketTransport implements RpcTransport {
       .filter(([, candidateClientId]) => candidateClientId === clientId)
       .map(([ws]) => ws)
     for (const ws of sockets) {
-      // Why: revocation is a security boundary; terminate skips the close
-      // handshake so a revoked mobile stream stops immediately.
+      // Why: revocation is a security boundary; terminate() skips the handshake so a revoked stream stops immediately.
       ws.terminate()
     }
     return sockets.length
   }
 
-  // Why: when port 0 is passed the OS assigns a random available port. The
-  // runtime metadata and mobile QR code need the real port, so callers read
-  // it here after start() resolves.
+  // Why: with port 0 the OS assigns a random port; callers read the real bound port here for metadata and the mobile QR.
   get resolvedPort(): number {
     const addr = this.httpServer?.address()
     if (addr && typeof addr === 'object') {
@@ -163,16 +126,7 @@ export class WebSocketTransport implements RpcTransport {
       return
     }
 
-    // Why: default order binds a persisted fallback FIRST — devices paired
-    // while it was active store ws://ip:<fallback> and would be stranded if a
-    // later launch grabbed the (now free) preferred port instead (STA-1511).
-    // Explicit serve --port flips the order so the pinned port wins when free
-    // (issue #8535); fallback remains a secondary candidate for EADDRINUSE.
-    // Without a persisted fallback only the preferred port is tried. On
-    // EADDRINUSE each candidate falls through to the next, ending at port 0
-    // (OS-assigned) so mobile pairing still works when everything is taken.
-    // The QR code reads resolvedPort after start, so it always advertises the
-    // port that actually bound.
+    // Why: bind a persisted fallback first so devices paired to it aren't stranded (STA-1511); serve --port flips to pinned-first (issue #8535); on failure each candidate falls through to OS-assigned port 0.
     const persistedFallbackPort =
       this.fallbackPort !== undefined && this.fallbackPort !== 0 && this.fallbackPort !== this.port
         ? this.fallbackPort
@@ -188,12 +142,7 @@ export class WebSocketTransport implements RpcTransport {
         await this.tryListen(port)
         return
       } catch (error: unknown) {
-        // Why: a persisted fallback can become unbindable for reasons beyond
-        // EADDRINUSE (e.g. Windows reserves dynamic-range ports for Hyper-V
-        // after a reboot → EACCES). Any fallback failure must degrade to the
-        // next candidate — aborting would disable the transport every launch
-        // while the store still names that port. Only preferred-port failures
-        // other than EADDRINUSE are fatal.
+        // Why: any fallback-port failure must degrade to the next candidate (Windows can reserve the port → EACCES, not just EADDRINUSE); only non-EADDRINUSE preferred-port failures are fatal.
         if (port !== persistedFallbackPort && (!isEAddressInUse(error) || port === 0)) {
           throw error
         }
@@ -215,9 +164,7 @@ export class WebSocketTransport implements RpcTransport {
       : createHttpServer(requestListener)
   }
 
-  // Why: the WebSocketServer is attached only after listen succeeds. If we
-  // attached it before, the WSS would re-emit the EADDRINUSE error from the
-  // httpServer as an uncatchable exception, preventing the fallback from working.
+  // Why: attach the WSS only after listen succeeds; earlier it re-emits httpServer's EADDRINUSE as an uncatchable exception and breaks the fallback.
   private async tryListen(port: number): Promise<void> {
     const httpServer = this.createHttpServer()
 
@@ -229,8 +176,7 @@ export class WebSocketTransport implements RpcTransport {
       })
     })
 
-    // Why: the WS cap applies only after upgrade. A separate TCP cap prevents
-    // raw and pre-upgrade sockets from consuming an unbounded descriptor budget.
+    // Why: the WS cap applies only post-upgrade; a separate TCP cap bounds raw/pre-upgrade descriptor use.
     httpServer.maxConnections = MAX_TCP_CONNECTIONS
 
     const wss = new WebSocketServer({
@@ -251,26 +197,16 @@ export class WebSocketTransport implements RpcTransport {
     this.startHeartbeat()
   }
 
-  // Why: over the WS-upgrade cap, request a graceful 1013 close but force the
-  // socket down shortly after. A backgrounded/half-open phone may never ack the
-  // close frame, so a bare ws.close() can retain the descriptor until the next
-  // heartbeat. Under a reconnect flood, shortening that window bounds the
-  // number of rejected sockets that can accumulate behind the WS cap. The
-  // 'error' listener prevents a reset while closing from becoming unhandled.
+  // Why: force-terminate soon after the 1013 close since a half-open phone may never ack and would hold the descriptor past the WS cap; the 'error' listener absorbs a reset while closing.
   private rejectOverCapacity(ws: WebSocket): void {
     ws.on('error', () => {})
     ws.close(1013, 'Maximum connections reached')
-    // Why: give the 1013 close a brief window, then hard-terminate so the
-    // descriptor is freed even if the client never acks the close frame.
     const terminateTimer = setTimeout(() => ws.terminate(), 1_000)
     terminateTimer.unref?.()
     ws.once('close', () => clearTimeout(terminateTimer))
   }
 
-  // Why: ping every live socket on a fixed cadence and terminate any that
-  // didn't pong since the previous tick. This is the only thing that
-  // reliably reaps half-open mobile sockets stranded by background
-  // suspension without a TCP FIN. See HEARTBEAT_INTERVAL_MS comment.
+  // Why: the only reliable reaper of half-open mobile sockets stranded by background suspension without a TCP FIN.
   private startHeartbeat(): void {
     if (this.heartbeatTimer) {
       return
@@ -283,9 +219,7 @@ export class WebSocketTransport implements RpcTransport {
       let reaped = 0
       for (const ws of wss.clients) {
         if (!this.wsAlive.has(ws)) {
-          // Why: terminate() (vs close()) skips the close handshake and
-          // immediately fires the 'close' event, freeing the slot. close()
-          // on an already-dead socket can hang for the OS-level TCP timeout.
+          // Why: terminate() frees the slot immediately; close() on a dead socket can hang for the OS-level TCP timeout.
           ws.terminate()
           reaped++
           continue
@@ -294,12 +228,10 @@ export class WebSocketTransport implements RpcTransport {
         try {
           ws.ping()
         } catch {
-          // Why: ping() can throw on a socket that's mid-tear-down; the
-          // close handler will run regardless, so swallow the throw.
+          // Why: ping() can throw on a mid-teardown socket; the close handler runs regardless, so swallow it.
         }
       }
-      // Why: steady reaping or a client count riding the cap are early overload
-      // signals; surface them without logging on healthy heartbeat ticks.
+      // Why: steady reaping or riding the cap are early overload signals; stay quiet on healthy ticks.
       if (reaped > 0 || wss.clients.size >= MAX_WS_CONNECTIONS) {
         console.warn(
           `[ws-transport] heartbeat reaped ${reaped}; ${wss.clients.size} tracked sockets`
@@ -327,8 +259,7 @@ export class WebSocketTransport implements RpcTransport {
 
     if (wss) {
       for (const client of wss.clients) {
-        // Why: stop() is a teardown path. A half-open mobile socket may never
-        // answer a graceful close frame, which keeps httpServer.close pending.
+        // Why: a half-open mobile socket may never answer a close frame, which keeps httpServer.close pending.
         client.terminate()
       }
       wss.close()
@@ -347,20 +278,14 @@ export class WebSocketTransport implements RpcTransport {
     }
   }
 
-  // Why: WebSocket connections are long-lived (unlike Unix socket which is
-  // one-per-request). Multiple requests can be multiplexed on the same
-  // connection via the RPC `id` field. The transport delegates all auth
-  // and dispatch logic to the message handler set by OrcaRuntimeRpcServer.
+  // Why: WS connections are long-lived and multiplex many RPCs by `id`; auth and dispatch are delegated to the message handler.
   private handleConnection(ws: WebSocket): void {
     let finalized = false
     const onPong = (): void => {
       this.wsAlive.add(ws)
     }
     const onMessage = (data: WebSocket.RawData, isBinary: boolean): void => {
-      // Why: any inbound traffic counts as proof of life, not just pongs.
-      // RN's WebSocket runtime auto-pongs server pings transparently, but
-      // app-level frames also count toward liveness so an actively-talking
-      // client doesn't get terminated mid-request.
+      // Why: any inbound frame counts as proof of life, so an actively-talking client isn't reaped mid-request.
       this.wsAlive.add(ws)
       const msg =
         typeof data === 'string'
@@ -371,8 +296,7 @@ export class WebSocketTransport implements RpcTransport {
       this.messageHandler?.(
         msg,
         (response) => {
-          // Why: mobile clients disconnect frequently (backgrounding, network
-          // switch, phone locked). Guard writes to avoid errors on dead sockets.
+          // Why: mobile clients disconnect often; guard the write so we don't throw on a dead socket.
           if (ws.readyState === ws.OPEN) {
             ws.send(response)
           }
@@ -381,8 +305,7 @@ export class WebSocketTransport implements RpcTransport {
       )
     }
     const onError = (): void => {
-      // Why: close is not guaranteed after every ws error path; finalize here
-      // too so pre-auth E2EE channels and connection ids cannot leak.
+      // Why: close isn't guaranteed after every error path; finalize here too so pre-auth E2EE state and connection ids can't leak.
       finalizeConnection()
       ws.close()
     }
@@ -405,9 +328,7 @@ export class WebSocketTransport implements RpcTransport {
 
     const preAuthTimer = setTimeout(() => {
       if (!this.wsClientIds.has(ws)) {
-        // Why: a silent client that only auto-pongs can otherwise occupy one
-        // of the finite mobile WebSocket slots forever without ever starting
-        // the E2EE handshake.
+        // Why: a silent auto-ponging client would otherwise hold a finite mobile slot forever without starting the E2EE handshake.
         ws.terminate()
       }
     }, this.preAuthTimeoutMs)
@@ -416,17 +337,13 @@ export class WebSocketTransport implements RpcTransport {
     }
     this.preAuthTimers.set(ws, preAuthTimer)
 
-    // Why: seed alive=true so the first heartbeat tick after connect doesn't
-    // treat a fresh socket as dead. Subsequent pongs (or any inbound traffic)
-    // re-arm it.
+    // Why: seed alive so the first heartbeat tick doesn't reap a fresh socket before its first pong.
     this.wsAlive.add(ws)
 
     ws.on('pong', onPong)
     ws.on('message', onMessage)
 
-    // Why: mobile clients disconnect when the phone locks, loses wifi, or
-    // backgrounds the app. The runtime must clean up connection-scoped state
-    // (e.g., mobile-fit overrides) to prevent orphaned phone-fit on desktop.
+    // Why: clean up connection-scoped state (e.g. mobile-fit overrides) so a dropped phone doesn't leave orphaned phone-fit on desktop.
     ws.on('close', finalizeConnection)
     ws.on('error', onError)
   }
diff --git a/src/main/runtime/runtime-rpc.ts b/src/main/runtime/runtime-rpc.ts
index 7ab4f3c4882..21dde39f93d 100644
--- a/src/main/runtime/runtime-rpc.ts
+++ b/src/main/runtime/runtime-rpc.ts
@@ -1,9 +1,5 @@
 /* eslint-disable max-lines -- Why: this file is the single security boundary for the bundled CLI — transport setup, auth-token enforcement, admission control, keepalive framing, and orphan-socket sweeping all co-locate deliberately so a reviewer can audit the boundary in one sitting. Splitting this across files would scatter the invariants without reducing complexity. */
-// Why: this is the single security boundary for the bundled CLI. It owns
-// auth-token enforcement, bootstrap-metadata publication, and transport
-// orchestration so a running runtime is always discoverable via exactly
-// one on-disk file. Method handling lives in `rpc/` and transport specifics
-// live in `rpc/unix-socket-transport.ts` and `rpc/ws-transport.ts`.
+// Why: the single security boundary for the bundled CLI — auth-token enforcement, metadata publication, transport orchestration.
 import { randomBytes } from 'node:crypto'
 import { readdirSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
@@ -53,15 +49,10 @@ type OrcaRuntimeRpcServerOptions = {
   platform?: NodeJS.Platform
   enableWebSocket?: boolean
   wsPort?: number
-  // Why: true when the caller set an explicit port (e.g. `orca serve --port`).
-  // Distinguishes that pin from the DEFAULT_WS_PORT default so transport bind
-  // order can prefer the pin over a stale STA-1511 fallback (issue #8535).
+  // Why: true when the caller pinned a port (`orca serve --port`) so bind order prefers it over a stale STA-1511 fallback (#8535).
   preferPinnedWsPort?: boolean
   webClientRoot?: string
-  // Why: test-only overrides for the two time-bound constants below.
-  // Production callers must not pass these — defaults are set by the design
-  // doc (§3.1) and changing them in production would weaken the admission
-  // fence or flood the socket with keepalive frames.
+  // Why: test-only overrides for the two constants below; production must not pass these (defaults set by §3.1).
   keepaliveIntervalMs?: number
   longPollCap?: number
 }
@@ -88,22 +79,10 @@ export type MobilePairingConnectionContext = Readonly<{
   transport: MobileSocketTransportMetadata
 }>
 
-// Why: after 10 s of a pending dispatch we emit a tiny `{"_keepalive":true}`
-// frame every 10 s until the handler resolves. Each write resets both the
-// server's own socket idle timer (30 s) and — once §3.1 ships on the client —
-// the client's idle timer, because any byte counts as socket activity. This
-// is the transport-layer fix for feedback #1: long-poll RPCs (i.e.
-// orchestration.check --wait) can now run past the 30 s/60 s idle caps
-// without either end tearing the socket down. See design doc §3.1.
+// Why: keepalive frames count as socket activity, resetting both idle timers so long-polls outlive the 30s/60s idle caps. See §3.1.
 const KEEPALIVE_INTERVAL_MS = 10_000
 
-// Why: long-poll slot cap. With keepalives a `check --wait --timeout-ms
-// 600000` can hold a connection for up to 10 minutes; unbounded that would
-// saturate MAX_RUNTIME_RPC_CONNECTIONS (32) with 32 waiting coordinators
-// and lock out normal short RPCs. Capping at half the connection budget
-// leaves the other half for short traffic. On overflow the server responds
-// immediately with `runtime_busy` (CLI exit 75) — fail fast, not silent
-// queuing. See design doc §3.1 + §7 risk #2.
+// Why: cap long-polls at half the 32-slot connection budget so they can't starve short RPCs; overflow → runtime_busy. See §7 risk #2.
 const LONG_POLL_CAP = 16
 
 function resolvePairingEndpoint(rawEndpoint: string, address: string | null | undefined): string {
@@ -148,8 +127,7 @@ function createWebClientUrl(endpoint: string, pairingUrl: string): string {
   url.protocol = url.protocol === 'wss:' ? 'https:' : 'http:'
   url.pathname = webClientPathForEndpoint(url.pathname)
   url.search = ''
-  // Why: pairing URLs include full runtime credentials. Keeping them in the
-  // fragment avoids proxy logs and Referer headers while the web app loads.
+  // Why: pairing URLs carry full credentials; the fragment keeps them out of proxy logs and Referer headers.
   url.hash = `pairing=${encodeURIComponent(pairingUrl)}`
   return url.toString()
 }
@@ -276,16 +254,14 @@ const MOBILE_RPC_METHOD_ALLOWLIST = new Set([
   'github.updatePRState',
   'github.repoSlug',
   'github.workItem',
-  // Cross-repo GitHub work-item lookup: lets the mobile create-workspace Smart
-  // picker resolve a pasted github.com URL that points at a different repo.
+  // Cross-repo lookup: lets the mobile Smart picker resolve a pasted github.com URL for a different repo.
   'github.workItemByOwnerRepo',
   'github.workItemDetails',
   'gitlab.createIssue',
   'gitlab.addIssueComment',
   'gitlab.addMRComment',
   'gitlab.listWorkItems',
-  // Mobile create-workspace Smart picker: resolve a pasted GitLab URL to an exact
-  // issue/MR. (MR listing reuses gitlab.listWorkItems, which returns issues + MRs.)
+  // Mobile Smart picker: resolve a pasted GitLab URL to an exact issue/MR (MR listing reuses gitlab.listWorkItems).
   'gitlab.workItemByPath',
   'gitlab.mergeMR',
   'gitlab.resolveMRDiscussion',
@@ -416,10 +392,7 @@ const MOBILE_RPC_METHOD_ALLOWLIST = new Set([
   'worktree.sleep'
 ])
 
-// Why: a long-poll request is one whose handler blocks waiting for an external
-// event. This function is the single place that classifies it — the long-poll
-// counter, abort wiring, keepalives, and runtime_busy admission check all
-// share this decision. See §3.1.
+// Why: single classifier for long-poll requests (handlers that block on an external event), shared by counter/abort/keepalive. See §3.1.
 function isLongPollRequest(request: RpcRequest): boolean {
   if (request.method === 'terminal.wait') {
     return true
@@ -431,10 +404,7 @@ function isLongPollRequest(request: RpcRequest): boolean {
   return false
 }
 
-// Why: stamp the authenticated connection's scope onto the status.get success
-// envelope. status.get has no per-connection context inside the dispatcher, so
-// the scope is added here at the transport boundary where the device is known.
-// Failures fall back to the untouched reply rather than dropping the response.
+// Why: status.get has no per-connection context in the dispatcher, so stamp the scope here at the transport boundary.
 function injectDeviceScope(response: string, scope: DeviceScope): string {
   try {
     const parsed = JSON.parse(response) as RpcResponse
@@ -477,9 +447,7 @@ export class OrcaRuntimeRpcServer {
     WebSocket,
     { controllers: Set<AbortController>; abortOnClose: () => void }
   >()
-  // Why: separate from Node's server.maxConnections because we need to count
-  // only long-running dispatches, not every in-flight short RPC. See §3.1 +
-  // §7 risk #2.
+  // Why: separate from server.maxConnections — count only long-running dispatches, not short RPCs. See §3.1 + §7 risk #2.
   private activeLongPolls = 0
 
   constructor({
@@ -545,8 +513,7 @@ export class OrcaRuntimeRpcServer {
       (current.relayBinding.relayHostId !== binding.relayHostId ||
         current.relayBinding.ownerIdentityKey !== binding.ownerIdentityKey)
     ) {
-      // Why: switching the account/host that owns this local pairing cannot
-      // strand the old cloud credential family even if that account is offline.
+      // Why: switching the owning account/host must not strand the old cloud credential family, even if that account is offline.
       this.queueRelayDeviceRevoke(current.relayBinding)
     }
     const updated = this.deviceRegistry?.setRelayBinding(deviceId, binding) ?? false
@@ -646,26 +613,20 @@ export class OrcaRuntimeRpcServer {
         endpoint: string
         deviceId: string
         webClientUrl: string | null
-        /** Mode the returned offer actually encodes — 'local-only' when an
-         *  automatic request degraded because Relay could not be attached. */
+        /** Mode the offer actually encodes — 'local-only' when an automatic request degraded (Relay couldn't attach). */
         connectionMode: MobilePairingConnectionMode
       }
   > {
-    // Why: the renderer is outside the trust boundary; only the explicit
-    // local-only value may suppress Relay provisioning.
+    // Why: the renderer is outside the trust boundary, so only an explicit local-only value may suppress Relay provisioning.
     const connectionMode = args.connectionMode === 'local-only' ? 'local-only' : 'automatic'
     const pending = this.deviceRegistry?.getPendingDevice('mobile')
-    // Why: an offer's connection policy is part of its credential. Rotating on
-    // any policy switch here (not in the renderer) means a QR displayed under
-    // the old policy cannot pair under the new one, and windows reminting after
-    // a preference sync converge on one token instead of racing rotations.
+    // Why: connection policy is part of the credential, so rotate on any policy switch — an old-policy QR must not pair under the new one.
     const switchingPendingMode =
       pending != null &&
       this.deviceRegistry?.getMobilePairingConnectionMode(pending.deviceId) !== connectionMode
     if (args.rotate || switchingPendingMode) {
       if (pending?.relayBinding) {
-        // Why: the durable cloud revoke is recorded before rotating the local
-        // token, so a previously displayed relay invite cannot outlive the QR.
+        // Why: record the durable cloud revoke before rotating the local token so an old relay invite can't outlive the QR.
         this.queueRelayDeviceRevoke(pending.relayBinding)
       }
     }
@@ -705,8 +666,7 @@ export class OrcaRuntimeRpcServer {
         })
       }
     } catch {
-      // Why: relay is additive. A transient auth/director/control outage must
-      // still yield the valid LAN/Tailscale pairing offer.
+      // Why: relay is additive — a transient outage must still yield the valid LAN/Tailscale pairing offer.
       return { ...direct, connectionMode: 'local-only' }
     }
   }
@@ -771,8 +731,7 @@ export class OrcaRuntimeRpcServer {
         abortOnClose: () => this.abortWebSocketDispatches(ws)
       }
       this.wsDispatchAbortStates.set(ws, state)
-      // Why: many streaming RPCs can share one WebSocket. A single socket-level
-      // abort fan-out avoids MaxListenersExceededWarning while preserving cleanup.
+      // Why: many streaming RPCs share one WebSocket; one socket-level abort fan-out avoids MaxListenersExceededWarning.
       ws.on('close', state.abortOnClose)
       ws.on('error', state.abortOnClose)
     }
@@ -815,12 +774,7 @@ export class OrcaRuntimeRpcServer {
       return
     }
 
-    // Why: processes killed by SIGKILL / OOM-kill / forced-shutdown skip
-    // stop() and leave behind `o-<pid>-*.sock` files in userData. Sweeping
-    // dead-pid sockets at startup keeps the directory from accumulating
-    // orphans over the app's lifetime. Named-pipe transports on Windows do
-    // not leave filesystem entries in userData, so the sweep is a no-op
-    // there.
+    // Why: SIGKILL/OOM skip stop(), orphaning `o-<pid>-*.sock` files; sweep them. Skipped on Windows: named pipes leave no filesystem entries.
     if (this.platform !== 'win32') {
       sweepOrphanedRuntimeSockets(this.userDataPath, this.pid)
     }
@@ -838,15 +792,7 @@ export class OrcaRuntimeRpcServer {
       keepaliveIntervalMs: this.keepaliveIntervalMs
     })
 
-    // Why: Unix socket transport uses the shared runtime auth token. This is
-    // the existing security model for CLI connections — the token lives in a
-    // 0o600-permissioned file on disk.
-    // Why: the `.catch` guarantees `reply()` always fires even if
-    // `handleMessage` (or `JSON.stringify` on a pathological response) throws.
-    // Without it, a throw would leave the client waiting for a terminal frame
-    // that never arrives AND leak the dispatch's AbortController in the
-    // transport's in-flight set until the 30 s socket idle timer closes the
-    // connection.
+    // Why: the `.catch` guarantees reply() always fires so a throw can't strand the client or leak the AbortController.
     socketTransport.onMessage((msg, reply, context) => {
       void this.handleMessage(msg, context)
         .then((response) => {
@@ -854,10 +800,7 @@ export class OrcaRuntimeRpcServer {
         })
         .catch((error) => {
           const message = error instanceof Error ? error.message : String(error)
-          // Why: best-effort id recovery so the client can correlate the
-          // error frame to its pending request. A malformed message would
-          // have been caught by handleMessage and returned an envelope
-          // instead of throwing, so in practice the id is always present.
+          // Why: best-effort id recovery so the client can correlate the error frame to its pending request.
           let id = 'unknown'
           try {
             const parsed = JSON.parse(msg) as { id?: unknown }
@@ -876,9 +819,7 @@ export class OrcaRuntimeRpcServer {
     const activeTransports: RpcTransport[] = [socketTransport]
     const transportsMeta: RuntimeTransportMetadata[] = [transportMeta]
 
-    // Why: WebSocket transport is opt-in and starts alongside the Unix socket.
-    // It uses per-device tokens and E2EE (application-layer encryption via
-    // tweetnacl) rather than TLS, since React Native can't pin self-signed certs.
+    // Why: WebSocket uses per-device tokens + E2EE (tweetnacl) instead of TLS since React Native can't pin self-signed certs.
     if (this.enableWebSocket) {
       try {
         this.deviceRegistry = new DeviceRegistry(this.userDataPath)
@@ -888,11 +829,7 @@ export class OrcaRuntimeRpcServer {
           host: '0.0.0.0',
           port: this.wsPort,
           staticRoot: this.webClientRoot,
-          // Why: keep the fallback port stable across restarts so paired
-          // devices' stored endpoints stay valid (STA-1511) — the transport
-          // binds a persisted fallback before the preferred port unless the
-          // caller explicitly pinned a port (serve --port). wsPort 0 means
-          // the caller wants a random port (E2E) — don't pin it.
+          // Why: stable fallback port across restarts keeps paired devices' endpoints valid (STA-1511); wsPort 0 = random (E2E).
           ...(this.wsPort !== 0 ? { fallbackPort: readWsFallbackPort(this.userDataPath) } : {}),
           ...(this.preferPinnedWsPort ? { preferPinnedPort: true } : {})
         })
@@ -917,8 +854,7 @@ export class OrcaRuntimeRpcServer {
               return
             }
             this.abortWebSocketDispatches(socket.ws)
-            // Why: subscriptions and binary streams are socket-scoped, while
-            // client disconnect state is device-scoped across both transports.
+            // Why: subscriptions and binary streams are socket-scoped, but disconnect state is device-scoped across transports.
             this.runtime.cleanupSubscriptionsForConnection(socket.connectionId)
             this.runtime.cancelMobileDictationForConnection(socket.connectionId)
             this.binaryStreamHandlers.delete(socket.connectionId)
@@ -940,26 +876,20 @@ export class OrcaRuntimeRpcServer {
           endpoint: `ws://0.0.0.0:${wsTransport.resolvedPort}`
         })
       } catch (error) {
-        // Why: WebSocket transport is supplementary — the runtime must still
-        // function if it fails to start (e.g., port in use). Log and continue
-        // with Unix socket only.
+        // Why: WebSocket transport is supplementary; on failure (e.g. port in use) continue with Unix socket only.
         console.error('[runtime] Failed to start WebSocket transport:', error)
         this.mobileSocketWiring = null
       }
     }
 
-    // Why: publish the transport into in-memory state before writing metadata
-    // so the bootstrap file always contains the real endpoint/token pair. The
-    // CLI only discovers the runtime through that file.
+    // Why: set in-memory transport state before writing metadata so the bootstrap file has the real endpoint/token pair.
     this.activeTransports = activeTransports
     this.transports = transportsMeta
 
     try {
       this.writeMetadata()
     } catch (error) {
-      // Why: a runtime that cannot publish bootstrap metadata is invisible to
-      // the `orca` CLI. Close all transports immediately instead of leaving
-      // behind a live but undiscoverable control plane.
+      // Why: a runtime that can't publish metadata is invisible to the CLI — close transports rather than run undiscoverable.
       this.activeTransports = []
       this.transports = []
       await Promise.all(activeTransports.map((t) => t.stop().catch(() => {}))).catch(() => {})
@@ -976,25 +906,15 @@ export class OrcaRuntimeRpcServer {
       return
     }
     await Promise.all(transports.map((t) => t.stop()))
-    // Why: we intentionally leave the last metadata file behind instead of
-    // deleting it on shutdown. Shared userData paths can briefly host multiple
-    // Orca processes during restarts, updates, or development, and stale
-    // metadata is safer than letting one process erase another live runtime's
-    // bootstrap file.
+    // Why: leave the metadata file on shutdown — shared userData may host another live runtime whose bootstrap file we'd erase.
   }
 
-  // Why: Unix socket messages use one-shot dispatch (single response per
-  // request) and the shared runtime auth token from the 0o600 metadata file.
-  // The transport layer owns socket lifecycle, keepalive writes, and the
-  // per-connection abort signal — this method just parses, auths, and
-  // dispatches. See design doc §3.1.
+  // Why: Unix socket dispatch is one-shot and auths via the shared token from the 0o600 metadata file. See §3.1.
   private async handleMessage(
     rawMessage: string,
     context?: RpcMessageContext
   ): Promise<RpcResponse> {
-    // Why: empty messages are sent by the Unix socket transport layer when a
-    // client exceeds the max message size. The transport closes the connection
-    // after this response.
+    // Why: the transport sends an empty message when a client exceeds max size, then closes the connection.
     if (!rawMessage) {
       return this.buildError('unknown', 'request_too_large', 'RPC request exceeds the maximum size')
     }
@@ -1005,8 +925,7 @@ export class OrcaRuntimeRpcServer {
     }
     const request = parsed.request
 
-    // Why: long-poll admission fence. Short RPCs bypass the counter entirely
-    // — it only guards handlers that can block for minutes. See §7 risk #2.
+    // Why: long-poll admission fence; short RPCs bypass the counter. See §7 risk #2.
     const longPoll = isLongPollRequest(request)
     if (longPoll && this.activeLongPolls >= this.longPollCap) {
       return this.buildError(
@@ -1017,8 +936,7 @@ export class OrcaRuntimeRpcServer {
     }
     if (longPoll) {
       this.activeLongPolls += 1
-      // Why: arm the keepalive timer only for long-polls. Short RPCs never
-      // touch it so the `setInterval` is never created. See §3.1.
+      // Why: arm keepalive only for long-polls; short RPCs never create the setInterval. See §3.1.
       context?.startKeepalive()
     }
 
@@ -1057,8 +975,7 @@ export class OrcaRuntimeRpcServer {
     return { request }
   }
 
-  // Why: WebSocket messages go through streaming dispatch which can emit
-  // multiple responses. Auth uses per-device tokens from the device registry.
+  // Why: WebSocket dispatch is streaming (multiple responses) and auths via per-device tokens, not the shared token.
   private async handleWebSocketMessage(
     rawMessage: string,
     reply: (response: string) => void,
@@ -1093,8 +1010,7 @@ export class OrcaRuntimeRpcServer {
       reply(JSON.stringify(this.buildError(request.id, 'unauthorized', 'Device token mismatch')))
       return
     }
-    // Why: E2EE already authenticated the WebSocket channel. Use that bound
-    // identity for authorization instead of trusting a repeated request field.
+    // Why: E2EE already authenticated the channel; authorize by that bound identity, not a repeated request field.
     const token = authenticatedDeviceToken ?? requestToken
     if (!token) {
       reply(JSON.stringify(this.buildError(request.id, 'unauthorized', 'Missing device token')))
@@ -1118,8 +1034,7 @@ export class OrcaRuntimeRpcServer {
       return
     }
 
-    // Why: associate the deviceToken with this WebSocket so ws.on('close')
-    // can notify the runtime which mobile client disconnected.
+    // Why: bind deviceToken to this socket so ws.on('close') knows which mobile client disconnected.
     if (wsTransport && ws) {
       wsTransport.setClientId(ws, token)
     }
@@ -1143,8 +1058,7 @@ export class OrcaRuntimeRpcServer {
       this.activeLongPolls += 1
     }
 
-    // Why: older/saved WebSocket pairings may not carry scope metadata, so
-    // stamp the authenticated scope onto the one method that probes the runtime.
+    // Why: older pairings may lack scope metadata, so stamp the authenticated scope onto status.get.
     const replyForRequest =
       request.method === 'status.get'
         ? (response: string): void => reply(injectDeviceScope(response, device.scope))
@@ -1179,8 +1093,7 @@ export class OrcaRuntimeRpcServer {
       await this.dispatcher.dispatchStreaming(request, replyForRequest, {
         connectionId,
         clientId: token,
-        // Why: gates the mobile-only payload diet (native-chat char clipping) so
-        // full-screen web/desktop runtime clients aren't truncated.
+        // Why: gates the mobile-only payload diet so full-screen web/desktop clients aren't truncated.
         clientKind: device.scope,
         pairing: pairingContext,
         signal: abortRegistration?.signal,
@@ -1212,13 +1125,7 @@ export class OrcaRuntimeRpcServer {
   }
 }
 
-/**
- * Why: the regex MUST stay in lockstep with createRuntimeTransportMetadata()
- * below, which emits `o-${pid}-${endpointSuffix}.sock` where endpointSuffix
- * is `[A-Za-z0-9_-]{1,4}` (derived from a sanitised runtimeId prefix, or
- * `'rt'` as the fallback). The invariant is covered by a unit test so any
- * future change to the transport-name shape trips CI.
- */
+/** Why: MUST stay in lockstep with createRuntimeTransportMetadata()'s `o-${pid}-${suffix}.sock` shape (unit-test enforced). */
 export const RUNTIME_SOCKET_NAME_REGEX = /^o-(\d+)-[A-Za-z0-9_-]+\.sock$/
 
 export function sweepOrphanedRuntimeSockets(userDataPath: string, ownPid: number): void {
@@ -1226,8 +1133,7 @@ export function sweepOrphanedRuntimeSockets(userDataPath: string, ownPid: number
   try {
     entries = readdirSync(userDataPath)
   } catch {
-    // Why: first-launch userData may not exist yet; the cold-start path
-    // below will create it. Nothing to sweep in that case.
+    // Why: first-launch userData may not exist yet; nothing to sweep.
     return
   }
   for (const entry of entries) {
@@ -1239,28 +1145,19 @@ export function sweepOrphanedRuntimeSockets(userDataPath: string, ownPid: number
     if (!Number.isFinite(pid)) {
       continue
     }
-    // Why: never touch the current process's socket. start() already
-    // rmSync's it if it exists, but belt-and-braces — a bug in the own-pid
-    // path here would rmSync a socket we're about to bind to.
+    // Why: never delete our own socket — a bug here would rmSync one we're about to bind.
     if (pid === ownPid) {
       continue
     }
     try {
-      // Why: signal 0 is the POSIX liveness probe — it delivers no signal
-      // but returns success iff the pid resolves AND the caller has
-      // permission to signal it. ESRCH = no such process; EPERM = pid
-      // exists but owned by another user, which is extremely unusual on a
-      // desktop app's userData dir but we conservatively leave those
-      // sockets alone.
+      // Why: signal 0 is the POSIX liveness probe (sends nothing); ESRCH = dead pid, EPERM = foreign owner (left alone).
       process.kill(pid, 0)
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code === 'ESRCH') {
         try {
           rmSync(join(userDataPath, entry), { force: true })
         } catch {
-          // Why: best-effort sweep — a permission error on unlink is fine
-          // to ignore; the socket will be cleaned by a later start() or
-          // by the OS on reboot.
+          // Why: best-effort sweep; a later start() or OS reboot cleans any socket we can't unlink.
         }
       }
     }
@@ -1277,9 +1174,7 @@ export function createRuntimeTransportMetadata(
   if (platform === 'win32') {
     return {
       kind: 'named-pipe',
-      // Why: Windows named pipes do not get the same chmod hardening path as
-      // Unix sockets, so include a per-runtime suffix to avoid exposing a
-      // stable, guessable control endpoint name across launches.
+      // Why: named pipes lack the chmod hardening of Unix sockets; a per-runtime suffix avoids a stable, guessable endpoint name.
       endpoint: `\\\\.\\pipe\\orca-${pid}-${endpointSuffix}`
     }
   }
diff --git a/src/main/startup/configure-process.ts b/src/main/startup/configure-process.ts
index e033e4e94de..37f772f2ece 100644
--- a/src/main/startup/configure-process.ts
+++ b/src/main/startup/configure-process.ts
@@ -61,8 +61,7 @@ export function configureElectronNetworkCompatibility(
   if (!shouldDisableHttp2ForElectronNetworking(options)) {
     return
   }
-  // Why: Chromium's HTTP/2 switch is process-wide and only works before the
-  // first session exists, so read the persisted setting during early startup.
+  // Why: Chromium's HTTP/2 switch is process-wide and only applies before the first session exists, so set it during early startup.
   app.commandLine.appendSwitch('disable-http2')
 }
 
@@ -75,11 +74,7 @@ function requestDevParentShutdown(): void {
   app.quit()
 
   const forceExitTimer = setTimeout(() => {
-    // Why: in dev, losing the supervising parent means this Electron process is
-    // already orphaned from the terminal session. We try app.quit() first so
-    // normal cleanup still runs, but fall back to app.exit() when macOS quit
-    // handlers or window-close guards stall and would otherwise leave Orca
-    // hanging after Ctrl+C ends `pnpm dev`.
+    // Why: app.quit() may stall on macOS quit handlers or window-close guards, so force-exit after a grace period to avoid a hung dev app.
     app.exit(0)
   }, DEV_PARENT_SHUTDOWN_GRACE_MS)
 
@@ -107,9 +102,7 @@ export function installUncaughtPipeErrorGuard(): void {
     }
 
     process.off('uncaughtException', onUncaughtException)
-    // Why: throwing inside an uncaughtException handler makes Node exit with
-    // status 7, hiding the original fault. Re-throw on the next tick so the
-    // default fatal-exception path reports the real status and stack.
+    // Why: throwing inside an uncaughtException handler exits with status 7 and hides the fault; re-throw next tick for the real stack.
     setImmediate(() => {
       throw error
     })
@@ -142,25 +135,14 @@ export function patchPackagedProcessPath(): void {
         join(home, 'bin'),
         join(home, '.local/bin'),
         join(home, '.nix-profile/bin'),
-        // Why: several agent CLIs ship install scripts that drop binaries into
-        // tool-specific ~/.<name>/bin directories (opencode's documented fallback,
-        // Pi's vite-plus installer). GUI-launched Electron inherits a minimal PATH
-        // without shell rc files, so these stay invisible to `which` probes — and
-        // the Agents settings page reports them as "Not installed" even when the
-        // user can run them from Terminal. See stablyai/orca#829.
+        // Why: some agent CLIs install into ~/.<name>/bin; GUI-launched Electron's minimal PATH misses them (stablyai/orca#829).
         join(home, '.opencode/bin'),
         join(home, '.vite-plus/bin')
       )
     }
   }
 
-  // Why: CLI tools installed via Node version managers (nvm, volta, asdf, fnm,
-  // pnpm, yarn, bun) use #!/usr/bin/env node shebangs that need `node` in PATH.
-  // resolveCodexCommand() can locate the codex binary in these directories, but
-  // spawning it still fails if node itself isn't in PATH. Adding version manager
-  // bin paths here fixes all spawn sites (login, rate limits, usage tracking).
-  // On Windows this also seeds user-local installer dirs, since shell hydration
-  // is POSIX-only and Start Menu launches can miss user-level PATH updates.
+  // Why: version-manager CLIs use env-node shebangs, so node must be on PATH or spawns fail (also seeds Windows user-local dirs).
   extraPaths.push(...getVersionManagerBinPaths())
 
   const pathKey = process.platform === 'win32' && process.env.Path !== undefined ? 'Path' : 'PATH'
@@ -179,10 +161,7 @@ export function patchPackagedProcessPath(): void {
 export function configureDevUserDataPath(isDev: boolean): void {
   const e2eConfig = getMainE2EConfig()
   if (e2eConfig.userDataDir) {
-    // Why: the E2E suite launches a fresh Electron app for each spec. A
-    // dedicated userData path per launch prevents persisted repos, worktrees,
-    // and session state from leaking between tests through the shared dev
-    // profile while still leaving the user's real packaged profile untouched.
+    // Why: a per-launch userData path stops E2E specs leaking persisted repos/worktrees/session state through the shared dev profile.
     app.setPath('userData', e2eConfig.userDataDir)
     return
   }
@@ -192,34 +171,22 @@ export function configureDevUserDataPath(isDev: boolean): void {
   }
   const overrideUserDataPath = process.env.ORCA_DEV_USER_DATA_PATH
   if (overrideUserDataPath) {
-    // Why: automated Electron repros need an isolated profile so persisted
-    // tabs/worktrees from the developer's normal `orca-dev` session do not
-    // change startup behavior and hide or create window-management bugs.
+    // Why: automated repros need an isolated profile so the dev's persisted tabs/worktrees don't skew startup and hide window bugs.
     app.setPath('userData', overrideUserDataPath)
     return
   }
-  // Why: development runs share the same machine as packaged Orca, and both
-  // publish runtime bootstrap files under userData. Without a dev-only path,
-  // `pnpm dev` can overwrite the packaged app's runtime pointer and make the
-  // public `orca` CLI look broken even though the packaged app is still open.
+  // Why: without a dev-only path, pnpm dev overwrites the packaged app's runtime pointer under userData and breaks the orca CLI.
   app.setPath('userData', join(app.getPath('appData'), 'orca-dev'))
 }
 
 export function configureOrcaUserDataPathEnv(): void {
-  // Why: app relaunches can inherit an ORCA_USER_DATA_PATH from an older CLI or
-  // updater process. Main must canonicalize it before CLI-shared modules build
-  // runtime-home paths, or migrations can bridge two Orca app-data directories.
+  // Why: relaunches can inherit a stale ORCA_USER_DATA_PATH; canonicalize before CLI-shared modules build runtime-home paths.
   process.env.ORCA_USER_DATA_PATH = app.getPath('userData')
 }
 
 export function shouldInstallManagedHooks(isDev: boolean): boolean {
   void isDev
-  // Why: managed hook installation now targets Orca-owned, environment-scoped
-  // homes for Codex rather than the user's default ~/.codex state, so plain
-  // dev runs need the install path enabled to keep hook-backed agent statuses
-  // accurate without an opt-in flag. The remaining agents still rely on the
-  // shared startup installer loop, so keep the policy uniformly on until
-  // they are migrated to more granular ownership seams.
+  // Why: managed hooks now target Orca-owned Codex homes, not ~/.codex, so keep install on for all agents until each gets its own seam.
   return true
 }
 
@@ -228,10 +195,7 @@ export function installDevParentDisconnectQuit(isDev: boolean): void {
     return
   }
 
-  // Why: electron-vite dev controls the Electron app over Node IPC so it can
-  // hot-restart the main process. On macOS, Ctrl+C can stop that parent process
-  // without terminating the app window, so in dev we quit explicitly when the
-  // supervising IPC channel disconnects instead of leaving a stray Electron app.
+  // Why: on macOS Ctrl+C can stop the electron-vite parent without closing the window, so quit when the IPC channel disconnects.
   process.once('disconnect', () => {
     requestDevParentShutdown()
   })
@@ -268,11 +232,7 @@ export function installDevParentWatchdog(isDev: boolean): void {
 
     if (parentPidChanged || parentMissing) {
       clearInterval(timer)
-      // Why: electron-vite's dev runner starts Electron with plain spawn() and
-      // inherited stdio, not an IPC channel. On macOS that means Ctrl+C can end
-      // the dev runner while leaving Orca open. Watching the original parent PID
-      // keeps dev shutdown coupled to the terminal session without affecting the
-      // packaged app, which is not supervised by electron-vite.
+      // Why: the dev runner spawns Electron without IPC, so on macOS Ctrl+C leaves Orca open; watch the parent PID to couple shutdown.
       requestDevParentShutdown()
     }
   }, 1000)
@@ -286,9 +246,7 @@ export function installDevParentSignalQuit(isDev: boolean): void {
   }
 
   const onSignal = (): void => {
-    // Why: run-electron-vite-dev forwards terminal shutdown signals to the
-    // Electron process group; those are dev-supervisor shutdowns too, so the
-    // detached daemon should not be preserved for warm reattach.
+    // Why: run-electron-vite-dev forwards terminal shutdown signals here, so don't preserve the detached daemon for warm reattach.
     requestDevParentShutdown()
   }
 
@@ -298,19 +256,14 @@ export function installDevParentSignalQuit(isDev: boolean): void {
 
 export function enableMainProcessGpuFeatures(): void {
   if (process.platform === 'linux' && getMainE2EConfig().userDataDir) {
-    // Why: Ubuntu/Xvfb runners can fail Electron startup with
-    // "GPU process isn't usable" before Playwright sees the first window.
-    // E2E coverage does not depend on GPU compositing, so keep CI on the
-    // software path instead of retrying around a crashed app process.
+    // Why: Ubuntu/Xvfb runners fail Electron startup with "GPU process isn't usable"; E2E needs no GPU, so use the software path.
     app.disableHardwareAcceleration()
     app.commandLine.appendSwitch('disable-gpu')
     return
   }
 
-  // Why: Blink force-loses the oldest WebGL context past 16 per renderer, and
-  // each attached terminal pane holds one — a busy worktree (tabs × splits)
-  // can exceed that, silently downgrading evicted panes to the DOM renderer.
-  // 128 covers real layouts while keeping a bound so context leaks surface.
+  // Why: Blink evicts the oldest WebGL context past 16/renderer and each terminal pane holds one, silently downgrading panes to DOM.
+  // 128 raises the ceiling for real layouts while staying bounded so context leaks still surface.
   app.commandLine.appendSwitch('max-active-webgl-contexts', '128')
 
   const ozonePlatform = (app.commandLine.getSwitchValue('ozone-platform') ?? '').toLowerCase()
@@ -325,17 +278,13 @@ export function enableMainProcessGpuFeatures(): void {
       ozonePlatformHint === 'wayland' ||
       ozonePlatform === 'wayland')
   if (isLinuxWaylandSession) {
-    // Why: #5319 reproduces when Wayland loses the eager GPU channel. Keep
-    // acceleration available, but drop the GPU sandbox and let Chromium open
-    // the GPU channel lazily on this compositor path.
+    // Why: #5319 — Wayland loses the eager GPU channel; drop the GPU sandbox so Chromium opens it lazily.
     app.commandLine.appendSwitch('disable-gpu-sandbox')
   }
 
   const existingFeatures = app.commandLine.getSwitchValue('enable-features')
   const features = [
-    // Why: mirror VS Code's conservative Electron GPU-channel startup flags
-    // instead of opting into Vulkan/SkiaGraphite/unsafe WebGPU globally.
-    // Terminal acceleration is controlled by xterm WebGL in the renderer.
+    // Why: mirror VS Code's conservative GPU-channel flags instead of global Vulkan/SkiaGraphite/WebGPU; terminal accel is xterm WebGL.
     ...(isLinuxWaylandSession ? [] : ['EarlyEstablishGpuChannel', 'EstablishGpuChannelAsync']),
     existingFeatures
   ]
@@ -346,12 +295,8 @@ export function enableMainProcessGpuFeatures(): void {
   }
 
   const existingDisabledFeatures = app.commandLine.getSwitchValue('disable-features')
-  // Why: with main-window background throttling on, Chromium's intensive mode
-  // clamps hidden-page timers to 1/min after 5 minutes, delaying agent-done and
-  // bell notifications by up to 60s. Keep the normal 1s hidden clamp (rAF and
-  // rendering still stop) but opt out of the 1/min tier. Callers skip this
-  // function under GPU fallback (win32-only today); if throttling ever extends
-  // to Windows, this opt-out must move out of the GPU-gated path.
+  // Why: IntensiveWakeUpThrottling clamps hidden-page timers to 1/min after 5min, delaying agent-done/bell notifications ~60s.
+  // This opt-out is skipped under GPU fallback (win32-only today); if throttling ever reaches Windows it must move out of this path.
   const disabledFeatures = ['IntensiveWakeUpThrottling', existingDisabledFeatures]
     .filter(Boolean)
     .join(',')
diff --git a/src/main/telemetry/burst-cap.ts b/src/main/telemetry/burst-cap.ts
index 382e6600dfa..234ca350ea2 100644
--- a/src/main/telemetry/burst-cap.ts
+++ b/src/main/telemetry/burst-cap.ts
@@ -1,33 +1,10 @@
-// Burst caps for the telemetry transport. Three independent buckets — all
-// must be satisfied for an event to transmit or a consent mutation to apply.
-//
-//   (1) Per-event-name token bucket — defends against runaway-`useEffect`
-//       bugs and repeated error serializations. `agent_error` is rate-limited
-//       slightly tighter (20/min) than the default (30/min).
-//
-//   (2) Per-session global ceiling (1,000 events) — defends against a
-//       compromised renderer. A renderer rendering attacker-controllable
-//       content can invoke `window.api.telemetryTrack` at any rate the
-//       per-event-name bucket allows; without a global ceiling, 24h of
-//       abuse at the per-event cap could emit ~650K events and blow the
-//       PostHog billing cap in one session.
-//
-//   (3) Consent-mutation bucket (≤5 per session, shared across `setOptIn`
-//       and `acknowledgeBanner`) — a real user flips the Privacy pane
-//       toggle a handful of times at most; beyond that it is either a bug
-//       or a compromised renderer.
-//
-// All buckets reset when `resetBurstCapsForSession()` is called at the start
-// of a fresh telemetry session (on `initTelemetry`). Within a session, the
-// per-event token bucket refills continuously at its `capacity / 60_000` ms
-// rate; the global ceiling and the consent-mutation bucket do not refill
-// within a session by design — the whole point of the global ceiling is to
-// cap aggregate per-session volume.
-//
-// Overflow is silent past the first crossing: each bucket logs exactly one
-// `console.warn` the first time it rejects an attempt in a given session,
-// then drops quietly until the next session reset. Rate-limiting the logs
-// themselves is what keeps a pathological caller from DoSing stderr.
+// Three independent burst caps; all must pass to transmit an event or apply a consent mutation:
+//   (1) Per-event token bucket (30/min, agent_error 20/min) — caps runaway useEffects/error spam.
+//   (2) Per-session ceiling (1,000) — backstops a compromised renderer to protect the PostHog billing cap.
+//   (3) Consent-mutation bucket (≤5/session, shared setOptIn+acknowledgeBanner) — more is a bug or attack.
+// resetBurstCapsForSession() (on initTelemetry) clears all. Per-event refills continuously; the ceiling
+// and consent bucket intentionally don't — the point is to cap aggregate per-session volume.
+// Overflow logs once per bucket per session then drops silently, so a pathological caller can't DoS stderr.
 
 import { eventSchemas, type EventName } from '../../shared/telemetry-events'
 
@@ -45,9 +22,7 @@ type TokenBucket = {
   warned: boolean
 }
 
-// Module-level state. One Store instance / one telemetry session per main
-// process; there is no multi-tenant reuse to worry about. `initTelemetry`
-// calls `resetBurstCapsForSession()` to start fresh on each session.
+// Module-level singleton state — one telemetry session per main process, no multi-tenant reuse.
 const perEventBuckets = new Map<string, TokenBucket>()
 let perSessionCount = 0
 let perSessionWarned = false
@@ -66,9 +41,7 @@ function getOrCreateBucket(name: string, now: number): TokenBucket {
     perEventBuckets.set(name, bucket)
     return bucket
   }
-  // Continuous refill — `capacity` tokens per `WINDOW_MS` ms. Computed
-  // lazily on each access so we do not need a timer; equivalent to the
-  // standard token-bucket formula used by most rate limiters.
+  // Lazy refill on access (avoids a timer): `capacity` tokens per `WINDOW_MS`.
   const elapsed = now - bucket.lastRefill
   if (elapsed > 0) {
     const refill = (elapsed / WINDOW_MS) * bucket.capacity
@@ -79,29 +52,13 @@ function getOrCreateBucket(name: string, now: number): TokenBucket {
 }
 
 /**
- * Consume one token for the given event name. Returns `true` if the event is
- * allowed to proceed, `false` if any of the buckets rejected it.
- *
- * Ordering rationale: per-event bucket first, per-session ceiling second.
- * The per-event bucket is the attention-conserving check (drops runaway
- * useEffects early, before counting against the session ceiling); the global
- * ceiling is the correctness backstop against a compromised renderer that
- * cycles through event names to evade the per-event caps.
+ * Consume one token for `name`; `true` if allowed, `false` if any bucket rejected it.
+ * Order matters: the per-event bucket drops runaway useEffects before they count against the
+ * per-session ceiling, which backstops a renderer cycling names to evade the per-event caps.
  */
 export function consumeBurstToken(name: EventName): boolean {
-  // Reject unknown event names here so renderer-controlled strings cannot
-  // grow `perEventBuckets` past the fixed `eventSchemas` size. The IPC
-  // `telemetry:track` handler casts any string to `EventName`, so a
-  // compromised renderer could otherwise flood unique bogus names and
-  // unboundedly grow the Map before the validator rejects them. Downstream
-  // validator still rejects with the proper "unknown event" reason.
-  //
-  // Use `Object.hasOwn` rather than `in` — the latter walks the prototype
-  // chain, so a compromised renderer could pass `'toString'`, `'__proto__'`,
-  // `'constructor'`, etc. to bypass the guard and seed buckets for every
-  // `Object.prototype` key. Growth would be bounded (~12 keys) but the whole
-  // point of this check is to keep the Map size pinned to the compile-time
-  // `eventSchemas` surface.
+  // Bound `perEventBuckets`: the IPC handler casts any string to EventName, so reject unknown
+  // names a compromised renderer could flood. `Object.hasOwn` (not `in`) skips prototype-chain keys.
   if (!Object.hasOwn(eventSchemas, name)) {
     return false
   }
@@ -129,11 +86,8 @@ export function consumeBurstToken(name: EventName): boolean {
 }
 
 /**
- * Consume one token from the consent-mutation bucket. Returns `true` if the
- * caller is allowed to apply a consent mutation, `false` if the per-session
- * ceiling has been reached. Renderer-triggered IPC calls are the only
- * callers of this bucket — main-originated consent mutations bypass IPC and
- * are not rate-limited here.
+ * Consume one consent-mutation token; returns `false` once the per-session ceiling is hit.
+ * Only renderer IPC calls reach here — main-originated mutations bypass IPC and stay uncapped.
  */
 export function consumeConsentMutationToken(): boolean {
   if (consentMutationCount >= CONSENT_MUTATION_CEILING) {
@@ -149,10 +103,7 @@ export function consumeConsentMutationToken(): boolean {
   return true
 }
 
-/**
- * Reset every bucket. Called at the start of each telemetry session from
- * `initTelemetry`. Tests also call it to get a clean slate between cases.
- */
+/** Reset every bucket; called on each telemetry session start (`initTelemetry`), and by tests. */
 export function resetBurstCapsForSession(): void {
   perEventBuckets.clear()
   perSessionCount = 0
diff --git a/src/main/telemetry/client.ts b/src/main/telemetry/client.ts
index c346bd41b5f..d1f2b2fa057 100644
--- a/src/main/telemetry/client.ts
+++ b/src/main/telemetry/client.ts
@@ -1,30 +1,9 @@
-// Main-process telemetry transport. One `posthog-node` client per process,
-// one source of truth for common props, one `track()` entry that every event
-// (main-originated AND IPC-arrived) funnels through. The validator in
-// `validator.ts` is the single gate that protects the wire from malformed
-// or over-sized payloads; the burst cap in `burst-cap.ts` protects against
-// runaway useEffects and a compromised renderer.
-//
-// Ordering inside `track()` — MUST be preserved:
-//   1. shutdown gate        — will-quit already set `shuttingDown = true`;
-//                             late IPC arrivals drop, never crash.
-//   2. burst cap            — O(1). Runs BEFORE consent resolve so an
-//                             opted-out user whose renderer is compromised
-//                             cannot burn handler CPU by forcing a
-//                             settings read + consent evaluation on every
-//                             attempt.
-//   3. consent resolve      — reads the live settings, never a cached
-//                             boolean. Env-var / CI / opt-out all funnel
-//                             through here.
-//   4. validator            — schema-level safeParse. Fail-closed.
-//   5. posthog.capture      — the only place this module calls into the
-//                             vendor SDK.
-//
-// `$process_person_profile: false` is attached on every capture because
-// posthog-node has no init-time equivalent of posthog-js's
-// `person_profiles: 'identified_only'` — without the per-capture flag, the
-// server SDK would materialize a PostHog person per install_id, which we
-// explicitly do not want for anonymous-only events.
+// Main-process telemetry transport: one posthog-node client, one `track()` entry that every
+// event (main + IPC) funnels through. The ordering inside `track()` — shutdown gate, burst cap,
+// consent, validator, capture — MUST be preserved: burst cap runs before consent so a compromised
+// opted-out renderer can't force a settings read per event.
+// `$process_person_profile: false` is attached per capture because posthog-node has no init-time
+// equivalent of posthog-js's `person_profiles: 'identified_only'` (no PostHog person per install_id).
 
 import { randomUUID } from 'node:crypto'
 import { arch as osArch, platform as osPlatform, release as osRelease } from 'node:os'
@@ -37,31 +16,12 @@ import { getCohortAtEmit } from './cohort-classifier'
 import { resolveConsent, type ConsentState } from './consent'
 import { commonPropsSchema, validate } from './validator'
 
-// Compile-time feature flag. PR 2 shipped with this `false` so the SDK was
-// wired but no event transmitted. PR 3 flips it to `true`. Independent of
-// the build-identity gate below: both must be satisfied to transmit, so
-// flipping the flag alone still leaves contributor builds silent.
-//
-// NOTE: config/scripts/verify-telemetry-constants.mjs greps this declaration
-// shape (`const TELEMETRY_ENABLED = true|false`) to gate release verification.
-// If you refactor this (e.g. let, export, computed-from-env, moved into a
-// config object), update the regex in that script too.
+// Compile-time feature flag, independent of the build-identity gate — both must be satisfied to transmit.
+// NOTE: config/scripts/verify-telemetry-constants.mjs greps `const TELEMETRY_ENABLED = true|false`; keep that shape or update its regex.
 const TELEMETRY_ENABLED = true
 
-// Eligible-to-transmit only if the CI release pipeline injected BOTH the
-// build-identity constant and a write key. One without the other is treated
-// as a pipeline misconfiguration and fails closed. Contributor / `pnpm dev`
-// / third-party rebuilds get literal `null` from electron-vite's `define`,
-// so `IS_OFFICIAL_BUILD` evaluates `false` at module load. There is no
-// runtime env-var fallback.
-//
-// The `globalThis` dance exists for the vitest harness. `declare const`
-// lets TypeScript type-check against the substituted symbols, but vitest
-// does not run electron-vite's `define` pass, so the identifiers are
-// undefined at test-runtime. Routing the read through `globalThis` gives
-// us the compile-time substitution in production and a safe `undefined`
-// in tests — both of which resolve to `IS_OFFICIAL_BUILD === false`, which
-// is the fail-closed default we want anywhere outside an official CI build.
+// Eligible to transmit only if CI injected BOTH build-identity and write key; either alone fails closed, with no runtime env-var override (dev/contributor builds get `null`).
+// The `globalThis` reads are for vitest, which skips electron-vite's `define` pass — resolving to `IS_OFFICIAL_BUILD === false` there.
 const BUILD_IDENTITY: 'stable' | 'rc' | null =
   typeof ORCA_BUILD_IDENTITY !== 'undefined'
     ? ORCA_BUILD_IDENTITY
@@ -75,9 +35,7 @@ const IS_OFFICIAL_BUILD: boolean =
   typeof WRITE_KEY === 'string' &&
   WRITE_KEY.length > 0
 
-// Module-level singletons. There is exactly one Store / one main process /
-// one telemetry session at a time; threading `store` through every export
-// is verbose without buying anything.
+// Module-level singletons — one Store / process / telemetry session; threading `store` everywhere buys nothing.
 let posthog: PostHog | null = null
 let sessionId: string | null = null
 let commonProps: CommonProps | null = null
@@ -86,24 +44,14 @@ let storeRef: Store | null = null
 
 const OPT_OUT_CAPTURE_ENQUEUE_TIMEOUT_MS = 1_000
 
-// Test-only override for the transport gate. Set by `_enableTransportForTests`
-// so the client.test.ts suite can exercise the full pipeline (burst cap,
-// consent, validator, capture) without waiting on a real CI build. Left
-// `false` in production; an accidental call from non-test code would still
-// be bounded by `resolveConsent` + the validator.
+// Test-only transport-gate override (`_enableTransportForTests`) so tests exercise the full pipeline without a real CI build.
 let testTransportEnabled = false
 
-// First-launch `app_opened` session gate. The existing-user banner contract is:
-// no events transmit until the notice resolves. Keep "mark" and "emit"
-// atomic so no path can accidentally suppress the event without firing it.
+// First-launch `app_opened` gate: no events transmit until the banner resolves; keep mark+emit atomic.
 let appOpenedTrackedThisSession = false
 
 function buildCommonProps(installId: string, sid: string, channel: 'stable' | 'rc'): CommonProps {
-  // `.max(64)` on every free-form string field in `commonPropsSchema` is the
-  // upper bound; node's platform / arch / release strings are always well
-  // under that in practice. We do not truncate here because the validator's
-  // schema cap is the authoritative check — truncating pre-validator would
-  // silently mask an unexpected-long-string case we want to see as a drop.
+  // Don't truncate here; the validator's `.max(64)` is authoritative, so an over-long string drops rather than being silently masked.
   return {
     app_version: app.getVersion(),
     platform: osPlatform(),
@@ -116,14 +64,11 @@ function buildCommonProps(installId: string, sid: string, channel: 'stable' | 'r
 }
 
 export function initTelemetry(store: Store): void {
-  // Set `storeRef` unconditionally so `setOptIn` can persist consent
-  // changes even in console-mirror builds — opt-out must still write to
-  // disk on a contributor laptop, not just on official builds.
+  // Set unconditionally so `setOptIn` can persist opt-out to disk even on contributor / non-official builds.
   storeRef = store
   resetBurstCapsForSession()
   shuttingDown = false
-  // Gate reset per session: the "no app_opened until banner resolution"
-  // invariant is per-launch, not across the lifetime of the install.
+  // Reset per session: the "no app_opened until banner resolution" invariant is per-launch, not per-install.
   appOpenedTrackedThisSession = false
 
   if (!TELEMETRY_ENABLED || !IS_OFFICIAL_BUILD) {
@@ -133,8 +78,7 @@ export function initTelemetry(store: Store): void {
   const settings = store.getSettings()
   const installId = settings.telemetry?.installId
   if (!installId) {
-    // Migration guarantees this is set; if it isn't, we're in an invariant-
-    // violation state and must not transmit with a missing distinct_id.
+    // Migration guarantees installId; if missing, don't transmit with an absent distinct_id.
     console.warn('[telemetry] installId missing after migration; skipping transport init')
     return
   }
@@ -143,23 +87,12 @@ export function initTelemetry(store: Store): void {
   commonProps = buildCommonProps(
     installId,
     sessionId,
-    // Non-null at this point: `IS_OFFICIAL_BUILD` gated this branch and
-    // narrows the identity constant to the `'stable' | 'rc'` arm.
+    // Non-null here: `IS_OFFICIAL_BUILD` gated this branch to the `'stable' | 'rc'` arm.
     BUILD_IDENTITY as 'stable' | 'rc'
   )
 
-  // Fail-closed on bad common props — the validator is the single enforcement
-  // point for wire shape, including common props. A bad `install_id` (e.g.
-  // empty string from a migration bug) would collapse all events into one
-  // distinct_id, so we must refuse to initialize transport rather than ship
-  // malformed identity on every capture.
-  //
-  // Validated once here at init — NOT on every `track()` call — because
-  // `commonProps` is a module-level singleton built exactly once from inputs
-  // that do not change across the session (app version, OS, install_id,
-  // session_id, channel). Re-validating per event would be wasted work on
-  // a value that cannot drift. If a future refactor makes `commonProps`
-  // mutable mid-session, move this check accordingly.
+  // Fail-closed: a bad `install_id` (e.g. empty from a migration bug) would collapse all events into one distinct_id.
+  // Validated once here (not per `track()`): `commonProps` is a session-lifetime singleton that can't drift.
   const parsedCommon = commonPropsSchema.safeParse(commonProps)
   if (!parsedCommon.success) {
     console.warn('[telemetry] common props failed schema validation; skipping transport init')
@@ -171,15 +104,9 @@ export function initTelemetry(store: Store): void {
     host: 'https://us.i.posthog.com',
     flushAt: 20,
     flushInterval: 10_000,
-    // Strip every auto-attached property we do not want on our wire: no
-    // GeoIP, no client IP enrichment. Our wire is exactly
-    // `CommonProps ∪ EventProps ∪ a small allow-list of SDK auto-props`.
+    // Strip SDK-auto GeoIP / client-IP enrichment; our wire is exactly CommonProps ∪ EventProps ∪ a small allow-list.
     disableGeoip: true,
-    // Default is 1000; past that, the SDK drops oldest-first. Bumped to
-    // 5000 to tolerate long-offline sessions (flights, VPN-down, tunnels).
-    // The per-session 1,000-event ceiling in `track()` caps normal
-    // operation well below this; the 5000 slots are the absolute ceiling
-    // across any conceivable offline duration.
+    // Bumped from the default 1000 (drops oldest-first past cap) to 5000 to tolerate long-offline sessions.
     maxQueueSize: 5000
   })
 
@@ -189,27 +116,12 @@ export function initTelemetry(store: Store): void {
 }
 
 /**
- * Decide whether to flip the PostHog SDK's in-memory `optedOut` flag at boot.
+ * Whether to flip the PostHog SDK's in-memory `optedOut` flag at boot.
  *
- * Applied to DISABLED cohorts only (`user_opt_out` / CI / DO_NOT_TRACK /
- * ORCA_TELEMETRY_DISABLED). The SDK flag does not persist across process
- * restarts, so we re-apply on every boot as defense-in-depth: any direct
- * `posthog.capture()` that bypasses `track()` (and therefore bypasses the
- * consent gate in this module) must still drop at the SDK boundary for a
- * user who has opted out.
- *
- * Intentionally NOT applied to `pending_banner`: the existing-user Turn-off
- * path in `setOptIn(_, false)` does a direct `posthog.capture()` for the
- * `telemetry_opted_out { via: 'first_launch_banner' }` signal, bypassing
- * `track()` (see the long comment in the opt-out branch below explaining
- * why). If the SDK were already opted-out at that point, the capture would
- * silently drop inside posthog-core's `enqueue()` — losing the one signal
- * that tells us the opt-out flow works. `track()`'s own consent gate
- * (`resolveConsent() !== 'enabled'`) still drops every other event while
- * the cohort is `pending_banner`, so there is no risk of stray transmission
- * during the pre-banner window.
- *
- * Exported for tests; production has exactly one call site above.
+ * True for DISABLED cohorts only, re-applied every boot (the flag doesn't persist) so any direct
+ * `posthog.capture()` bypassing `track()` still drops for an opted-out user. Deliberately excludes
+ * `pending_banner`: the direct `telemetry_opted_out` capture in `setOptIn(_, false)` must not drop,
+ * or we'd lose the one signal that the opt-out flow works.
  */
 export function shouldOptOutSdkAtInit(consent: ConsentState): boolean {
   return consent.effective === 'disabled'
@@ -233,8 +145,7 @@ function waitForCaptureEnqueue(client: PostHog, event: EventName, uuid: string):
       resolve(enqueued)
     }
 
-    // Why: posthog-node's capture() prepares/enqueues asynchronously; this
-    // public SDK event is the durable boundary we need before calling optOut().
+    // Why: posthog-node capture() enqueues async; this SDK event is the durable boundary before optOut().
     stopListening = client.on('capture', (payload: unknown) => {
       if (!payload || typeof payload !== 'object') {
         return
@@ -249,18 +160,13 @@ function waitForCaptureEnqueue(client: PostHog, event: EventName, uuid: string):
   })
 }
 
-// In `pnpm dev` and any contributor / non-official build, `track()` is a
-// no-op: it returns immediately without transmitting, logging, or running
-// the burst-cap / consent / validator pipeline. Telemetry only flows in
-// official stable/rc builds where CI injects `ORCA_BUILD_IDENTITY` and
-// `ORCA_POSTHOG_WRITE_KEY`.
+// No-op in contributor / non-official builds; only official stable/rc builds (CI-injected `ORCA_BUILD_IDENTITY` + `ORCA_POSTHOG_WRITE_KEY`) transmit.
 export function track<N extends EventName>(name: N, props: EventProps<N>): void {
   if (!testTransportEnabled && (!IS_OFFICIAL_BUILD || !TELEMETRY_ENABLED)) {
     return
   }
 
-  // (1) Shutdown gate. Late IPC arrivals should not attempt to enqueue
-  // against a client that is actively flushing.
+  // (1) Shutdown gate: late IPC arrivals must not enqueue against a flushing client.
   if (shuttingDown) {
     return
   }
@@ -268,37 +174,24 @@ export function track<N extends EventName>(name: N, props: EventProps<N>): void
     return
   }
 
-  // (2) Burst cap BEFORE consent. A compromised renderer of an opted-out
-  // user should not be able to burn CPU by forcing a settings read and a
-  // `resolveConsent` evaluation on every attempt — the cap is O(1), the
-  // consent resolve reads the live settings object. This ordering is the
-  // difference between "opt-out is a free drop" and "opt-out is a cheap
-  // drop at the cost of a settings read per event."
+  // (2) Burst cap before consent: the O(1) cap drops floods before the costly settings read, so a compromised opted-out renderer can't burn CPU.
   if (!consumeBurstToken(name)) {
     return
   }
 
-  // (3) Consent resolve — reads live settings every call; never a cached
-  // module-level boolean that could drift from the persisted state or the
-  // env-var precedence.
+  // (3) Consent resolve — reads live settings every call so it can't drift from persisted state / env-var precedence.
   const consent = resolveConsent(storeRef.getSettings())
   if (consent.effective !== 'enabled') {
     return
   }
 
-  // (4) Validator — single enforcement point for schema, enum, strict key
-  // set, and per-string length caps.
+  // (4) Validator — single enforcement point for schema, enum, key set, and length caps.
   const result = validate(name, props)
   if (!result.ok) {
     return
   }
 
-  // (5) Capture. `$process_person_profile: false` is the server-SDK
-  // equivalent of posthog-js's `person_profiles: 'identified_only'` —
-  // attached per-event because posthog-node has no init-time option.
-  // Without this, posthog-node materializes a PostHog person per
-  // `install_id`, which we explicitly do not want for anonymous-only
-  // events.
+  // (5) Capture. `$process_person_profile: false` stops posthog-node creating a person per install_id (no init-time equivalent).
   posthog.capture({
     distinctId: commonProps.install_id,
     event: name,
@@ -319,10 +212,7 @@ export async function setOptIn(via: OptInVia, optedIn: boolean): Promise<void> {
   const wasPendingBanner =
     telemetryBeforeUpdate?.existedBeforeTelemetryRelease === true &&
     telemetryBeforeUpdate.optedIn === null
-  // `updateSettings` is a partial-merge (see persistence.ts:552). The Store's
-  // `telemetry` field is deep-merged there specifically so an `optedIn` flip
-  // from the Privacy pane / consent flow does not clobber `installId` or
-  // `existedBeforeTelemetryRelease`.
+  // Deep-merge (persistence.ts:552) so flipping `optedIn` won't clobber `installId` / `existedBeforeTelemetryRelease`.
   storeRef.updateSettings({
     telemetry: {
       ...(settings.telemetry ?? { installId: '', existedBeforeTelemetryRelease: true }),
@@ -343,23 +233,8 @@ export async function setOptIn(via: OptInVia, optedIn: boolean): Promise<void> {
     if (!client) {
       return
     }
-    // Fire opt-out event BEFORE disabling the SDK. This is the one event
-    // that transmits against the user's new preference — the user chose to
-    // tell us they are opting out, and that single signal is what tells us
-    // the opt-out flow is working.
-    //
-    // Capture directly (not via `track()`) because `updateSettings` above
-    // just flipped `optedIn` to `false`; `track()` would re-read settings,
-    // call `resolveConsent`, and drop on `user_opt_out` — at which point the
-    // one signal that tells us the opt-out flow works would be silent.
-    // Burst cap + validator still run; consent is the only gate bypassed,
-    // and it is bypassed exactly once per user per session at most (IPC
-    // consent-mutation cap is 5/session).
-    //
-    // posthog-node prepares capture() asynchronously, so "call capture
-    // before optOut" is not enough; wait until the SDK confirms enqueue.
-    // We do not wait for network flush here — the SDK queue and shutdown
-    // flush own delivery, while the enqueue boundary owns the optOut race.
+    // Fire before disabling the SDK — the one event that must transmit against the new preference. Capture directly (not
+    // `track()`, which would drop it on `user_opt_out`); await enqueue since posthog-node captures async and must confirm before optOut().
     try {
       if (!shuttingDown && commonProps && consumeBurstToken('telemetry_opted_out')) {
         const validated = validate('telemetry_opted_out', { via })
@@ -389,35 +264,15 @@ export async function setOptIn(via: OptInVia, optedIn: boolean): Promise<void> {
   }
 }
 
-// Banner ✕ path. Writes `optedIn = true` permanently without emitting a
-// telemetry opt-in event. `app_opened` still fires because resolving the
-// banner is the first point where this session is eligible to transmit.
-// That outcome cannot route through `setOptIn()` — `setOptIn()` always
-// fires a `telemetry_opted_in/out` event and the IPC handler always
-// derives a non-`null` `via` value, which would tag a ✕ click as
-// `first_launch_banner` + `telemetry_opted_in`. The ✕-as-silent-
-// acknowledge contract is explicit: the user did not explicitly opt in,
-// they declined to intervene, so no opt-in event transmits.
-//
-// So this primitive exists as a named, non-overloaded code path: persist
-// the opt-in, unlock the SDK, and fire the once-per-session app-opened event.
-// The corresponding `telemetry:acknowledgeBanner` IPC channel
-// routes renderer ✕ clicks here instead of through `telemetry:setOptIn`.
-//
-// Do NOT extend this with a `via` parameter or emission flag. If a future
-// surface also needs a silent persisted opt-in, give it its own named
-// function rather than overloading this one — the grep'ability of
-// `persistBannerAcknowledgeWithoutEmitting` is the whole point.
+// Banner ✕: silent persisted opt-in. Separate from `setOptIn` because that always emits a
+// `telemetry_opted_in/out` event; here `app_opened` fires but no opt-in event does. Don't add a
+// `via`/emit param — give a new silent-opt-in surface its own named function.
 export async function persistBannerAcknowledgeWithoutEmitting(): Promise<void> {
   if (!storeRef) {
     return
   }
   const settings = storeRef.getSettings()
-  // Defensive merge mirrors `setOptIn`: updateSettings deep-merges the
-  // telemetry block (persistence.ts:560), so the fallback object here only
-  // matters if the migration invariant has been violated and `telemetry`
-  // is somehow absent — in which case we still want to persist an opt-in
-  // rather than no-op.
+  // Fallback only used if the `telemetry` block is absent (migration invariant broken); updateSettings deep-merges it (persistence.ts:560).
   storeRef.updateSettings({
     telemetry: {
       ...(settings.telemetry ?? { installId: '', existedBeforeTelemetryRelease: true }),
@@ -427,8 +282,7 @@ export async function persistBannerAcknowledgeWithoutEmitting(): Promise<void> {
   if (posthog) {
     await posthog.optIn()
   }
-  // Why: resolving the banner is the first eligible moment for app_opened.
-  // Re-enable the SDK first so capture sees the new consent state.
+  // Why: banner resolution is the first eligible moment for app_opened; SDK re-enabled above so capture sees the new consent.
   trackAppOpenedOnce()
 }
 
@@ -437,23 +291,19 @@ export function trackAppOpenedOnce(): void {
     return
   }
   appOpenedTrackedThisSession = true
-  // Why: `nth_repo_added: 0` on `app_opened` is the canonical session-zero
-  // / pre-repo cohort signal — a user who has launched but never added a
-  // repo. See docs/onboarding-funnel-cohort-addendum.md.
+  // Why: `nth_repo_added: 0` marks the session-zero / pre-repo cohort. See docs/onboarding-funnel-cohort-addendum.md.
   track('app_opened', { ...getCohortAtEmit() })
 }
 
 export async function shutdownTelemetry(): Promise<void> {
-  // Setting the shutdown gate is synchronous and cheap — it matters that
-  // late IPC-arrived tracks hit it before the bounded flush starts.
+  // Set the gate before flush so late IPC-arrived tracks drop instead of enqueuing mid-flush.
   shuttingDown = true
   const instance = posthog
   if (!instance) {
     return
   }
   try {
-    // PostHog's bounded flush caps at 2s. Observed quit delay goes up by at
-    // most that on top of the current daemon-teardown budget.
+    // Bounded flush caps at 2s, so quit delay rises by at most that.
     await instance.shutdown(2_000)
   } catch (err) {
     // Telemetry must never crash the app on quit. Swallow.
@@ -461,11 +311,7 @@ export async function shutdownTelemetry(): Promise<void> {
   }
 }
 
-// ── Test-only introspection ─────────────────────────────────────────────
-//
-// The test suite needs to inject a fake PostHog and observe capture calls
-// without touching the network. Kept under a `_`-prefixed name so it is
-// obvious in code review that this is not a runtime API.
+// Test-only introspection: `_`-prefixed helpers inject a fake PostHog and observe captures; not a runtime API.
 
 export function _setPostHogClientForTests(client: PostHog | null): void {
   posthog = client
diff --git a/src/main/telemetry/onboarding-cohort-classifier.ts b/src/main/telemetry/onboarding-cohort-classifier.ts
index d065eb65989..8b840dc0e17 100644
--- a/src/main/telemetry/onboarding-cohort-classifier.ts
+++ b/src/main/telemetry/onboarding-cohort-classifier.ts
@@ -1,36 +1,6 @@
-// Cohort discriminator for onboarding-wizard telemetry events. See
-// docs/onboarding-telemetry-extensions.md §2.
-//
-// `'fresh_install'` ⇔ `existedBeforeTelemetryRelease === false`. New users
-// land on the wizard on first launch; the cohort never moves.
-//
-// `'upgrade_backfill'` ⇔ `existedBeforeTelemetryRelease === true` AND the
-// onboarding state was backfilled at load time as a completed wizard run
-// (the persistence migration at `src/main/persistence.ts:362-369` writes
-// `outcome: 'completed'` and `lastCompletedStep: ONBOARDING_FINAL_STEP` for
-// existing users that lack an onboarding block). A pre-existing user who is
-// dropped into the wizard via the upgrade-backfill surface emits this
-// cohort on every wizard event.
-//
-// Known limitation: the discriminator infers the migration-backfilled state
-// from its canonical shape (`outcome === 'completed'` AND
-// `lastCompletedStep === ONBOARDING_FINAL_STEP`). That shape is *also* what
-// a live wizard completion writes via `closeWith('completed', ...)`. As a
-// result, a real existing-user (`existedBeforeTelemetryRelease === true`)
-// who goes through the wizard live will be classified as `fresh_install`
-// during the wizard, then *flip* to `upgrade_backfill` on the very next
-// event after `closeWith` persists the completion. Dashboard-side
-// workaround: filter `cohort` on the `_started` event and forward-fill
-// across the session, rather than re-reading the cohort on terminal
-// events. Structural follow-up (out of scope here): add a sentinel
-// `wasBackfilledByMigration: true` field at migration time so the
-// classifier can disambiguate without dashboard-side gymnastics.
-//
-// Failure mode: this module never throws. On any read error or
-// store-not-yet-initialized condition, `getOnboardingCohortAtEmit` returns
-// `{ cohort: undefined }`. The schemas declare the field `.optional()`, so
-// an event with an undefined cohort still validates and emits — it just
-// lands without the cohort property. Mirrors `getCohortAtEmit`.
+// Cohort discriminator for onboarding-wizard telemetry. See docs/onboarding-telemetry-extensions.md §2.
+// Known limitation: upgrade_backfill's "completed" shape (persistence.ts:362-369) is also written by live completion, so an existing live-completer flips fresh_install→upgrade_backfill; dashboards forward-fill cohort from _started. TODO: a wasBackfilledByMigration sentinel would disambiguate.
+// Never throws: returns { cohort: undefined } on any read/uninit error, which the schema's .optional() cohort still validates. Mirrors sibling getCohortAtEmit's never-crash contract.
 
 import { ONBOARDING_FINAL_STEP } from '../../shared/constants'
 import type { OnboardingCohort } from '../../shared/telemetry-events'
@@ -51,29 +21,14 @@ export function getOnboardingCohortAtEmit(): { cohort: OnboardingCohort | undefi
     return { cohort: undefined }
   }
   try {
-    // Why: fresh_install classification depends only on the settings flag,
-    // so we read settings first and skip getOnboarding() entirely on that
-    // branch — a failing onboarding read must not demote a fresh-install
-    // user to `{ cohort: undefined }`.
+    // Why: read settings first so a failing getOnboarding() can't demote a fresh_install user to undefined.
     const settings = storeRef.getSettings()
     const existedBefore = settings.telemetry?.existedBeforeTelemetryRelease
     if (existedBefore === false) {
       return { cohort: 'fresh_install' }
     }
     if (existedBefore === true) {
-      // Why: an existing-user cohort marker can coexist with a fresh
-      // wizard run (the migration only backfills when there's no
-      // onboarding block on disk). The `upgrade_backfill` cohort is
-      // specifically the user who was force-completed by the migration —
-      // detected by the canonical `outcome === 'completed'` AND
-      // `lastCompletedStep === ONBOARDING_FINAL_STEP` shape that
-      // persistence.ts:362-369 writes. Caveat: the same canonical shape is
-      // produced by `closeWith('completed', ...)` after a live wizard run,
-      // so an existing user who completes the wizard live will be
-      // classified as `fresh_install` during the wizard and then flip to
-      // `upgrade_backfill` on the next event after completion is
-      // persisted. See the top-of-file "Known limitation" block for the
-      // dashboard-side workaround and the proposed sentinel-field fix.
+      // Why: this canonical completed shape is written by both migration backfill and live completion, so it's ambiguous (see top-of-file "Known limitation").
       const onboarding = storeRef.getOnboarding()
       if (
         onboarding.outcome === 'completed' &&
diff --git a/src/main/updater-events.ts b/src/main/updater-events.ts
index 27936f988ce..ca3f2986c7d 100644
--- a/src/main/updater-events.ts
+++ b/src/main/updater-events.ts
@@ -88,16 +88,12 @@ export function registerAutoUpdaterHandlers({
   setAvailableVersion,
   setUserInitiatedCheck
 }: UpdaterHandlerContext): void {
-  // On macOS, electron-updater's MacUpdater downloads the ZIP from GitHub,
-  // then serves it to Squirrel.Mac via a localhost proxy. The electron-updater
-  // 'update-downloaded' event fires BEFORE Squirrel finishes its download.
-  // Track Squirrel readiness so we don't show "ready to install" prematurely.
+  // Why: electron-updater fires 'update-downloaded' before Squirrel.Mac finishes; track readiness to avoid a premature "ready".
   if (process.platform === 'darwin') {
     nativeUpdater.on('update-downloaded', () => {
       const hasNewerVersion = hasNewerDownloadedVersion()
       handleMacInstallerReady(hasNewerVersion, performQuitAndInstall, () => {
-        // If we were holding the 'downloaded' status, send it now — but only
-        // when the staged version is actually newer than what's running.
+        // Send the held 'downloaded' status now, only if the staged version is newer.
         sendStatus({
           state: 'downloaded',
           version: getPendingInstallVersion(),
@@ -116,11 +112,7 @@ export function registerAutoUpdaterHandlers({
       return
     }
 
-    // On macOS the user can quit while Squirrel.Mac is still pulling the ZIP
-    // from electron-updater's localhost proxy. If we let that quit finish,
-    // autoInstallOnAppQuit has nothing staged to apply and the next launch
-    // comes back on the old version. Hold the quit, then resume install when
-    // nativeUpdater confirms ShipIt is actually ready.
+    // Why: quitting before Squirrel.Mac finishes staging leaves nothing to install; hold the quit until it's ready.
     if (
       deferMacQuitUntilInstallerReady(
         getCurrentStatus(),
@@ -165,8 +157,7 @@ export function registerAutoUpdaterHandlers({
     if (compareVersions(info.version, app.getVersion()) <= 0) {
       clearAvailableUpdateContext()
       if (missingManifestFallback || publishingWindowLastGoodCheck) {
-        // Why: a fallback manifest at the current version is still the result of
-        // a transient missing primary manifest, so keep the short retry cadence.
+        // Why: a current-version fallback manifest means the primary is transiently missing; keep the short retry cadence.
         scheduleAutomaticUpdateCheck(AUTO_UPDATE_RETRY_INTERVAL_MS)
       } else {
         recordCompletedUpdateCheck()
@@ -178,18 +169,13 @@ export function registerAutoUpdaterHandlers({
       return
     }
 
-    // Why: fetching changelog in the main process avoids CORS issues that
-    // would block a renderer-side fetch to onorca.dev, and ensures the
-    // card can render immediately without an async loading gap.
+    // Why: fetch the changelog in main to avoid renderer-side CORS on onorca.dev.
     markUpdateAvailableEventPending(attemptId)
     void (async () => {
       try {
         const changelog = await fetchChangelog(info.version, app.getVersion()).catch(() => null)
 
-        // Why: the handler is now async, so up to 5 seconds may pass during the
-        // fetch. If another autoUpdater event (e.g., 'error') fired and updated
-        // the attempt during that window, broadcasting 'available' here would
-        // overwrite a more recent check. Guard on the attempt before state.
+        // Why: async fetch may take seconds; bail if a newer event superseded this attempt to avoid a stale 'available' broadcast.
         if (!isActiveUpdateCheckAttempt(attemptId)) {
           return
         }
@@ -197,18 +183,11 @@ export function registerAutoUpdaterHandlers({
           return
         }
 
-        // --- post-await side effects (only run if the guard passed) ---
-        // Why: these must live AFTER the guard, not before the await. If the
-        // fetch times out and a concurrent 'error' event advanced the status,
-        // bailing out above avoids orphaned side effects — e.g., availableVersion
-        // set without a matching 'available' broadcast, or a completed-check
-        // timestamp persisted for a check that never showed a result.
+        // Why: side effects must run after the guard so a concurrent 'error' during the fetch can't leave orphaned state.
         setAvailableVersion(info.version)
         setAvailableReleaseUrl(null)
         if (missingManifestFallback || publishingWindowLastGoodCheck) {
-          // Why: offering a previous/last-good release is only a temporary
-          // fallback; keep probing soon so users can move to the newest tag once
-          // its platform manifest finishes publishing.
+          // Why: last-good release is a temporary fallback; keep probing so users can move to the newest tag once it publishes.
           scheduleAutomaticUpdateCheck(AUTO_UPDATE_RETRY_INTERVAL_MS)
         } else {
           recordCompletedUpdateCheck()
@@ -236,9 +215,7 @@ export function registerAutoUpdaterHandlers({
     setUserInitiatedCheck(false)
     clearAvailableUpdateContext()
     if (missingManifestFallback || publishingWindowLastGoodCheck) {
-      // Why: the primary/newest release manifest/assets were missing, so a
-      // last-good not-available result is still a transient release-transition
-      // outcome and must not suppress the next retry for 24 hours.
+      // Why: last-good not-available is a transient release-transition outcome; keep the short retry, don't suppress for 24h.
       scheduleAutomaticUpdateCheck(AUTO_UPDATE_RETRY_INTERVAL_MS)
     } else {
       recordCompletedUpdateCheck()
@@ -260,9 +237,7 @@ export function registerAutoUpdaterHandlers({
 
   autoUpdater.on('update-downloaded', (info) => {
     clearBackgroundCheckLaunchPending()
-    // Don't show the banner if the downloaded version isn't actually newer
-    // than what's running. This catches the exact-same-version case as well
-    // as stale cached updates from an older release.
+    // Skip the banner for non-newer versions (same-version or stale cached updates).
     if (compareVersions(info.version, app.getVersion()) <= 0) {
       clearAvailableUpdateContext()
       sendStatus({ state: 'not-available' })
@@ -270,12 +245,9 @@ export function registerAutoUpdaterHandlers({
     }
     const macInstallerReady = process.platform === 'darwin' ? isMacInstallerReady() : true
     recordUpdaterLifecycle('update_downloaded', { version: info.version, macInstallerReady })
-    // On macOS, defer the 'downloaded' status until Squirrel.Mac has finished
-    // processing the update via the localhost proxy. On other platforms,
-    // the update is ready immediately after electron-updater downloads it.
+    // On macOS, defer 'downloaded' until Squirrel.Mac finishes processing; other platforms are ready immediately.
     if (process.platform === 'darwin' && !macInstallerReady) {
-      // Squirrel is still processing. Keep the UI at 100% downloaded so the
-      // user sees the handoff instead of a misleading "ready to install".
+      // Keep the UI at 100% downloaded while Squirrel processes, to avoid a premature "ready to install".
       recordUpdaterLifecycle('macos_waiting_for_squirrel', { version: info.version })
       sendStatus({ state: 'downloading', percent: 100, version: info.version })
       return
@@ -285,20 +257,15 @@ export function registerAutoUpdaterHandlers({
 
   autoUpdater.on('error', (err) => {
     const message = err?.message ?? 'Unknown error'
-    // Why: quitAndInstall reports the common "no staged update" failure through
-    // this event (often sync on Win/Linux, async on macOS/spawn). Recover
-    // quit-for-update flags before any suppression guard can early-return, but
-    // only after native invoke and only when install is not yet committed.
+    // Why: quitAndInstall reports "no staged update" via this error event (async on macOS); recover quit flags before suppression guards run.
     if (handleQuitAndInstallFailure()) {
       return
     }
-    // Why: handoff still owns the process (cleanup, native in-flight, or
-    // post-commit). Do not treat as check/download error or reset mac install.
+    // Why: handoff still owns the process; don't treat as a check/download error.
     if (isQuitAndInstallHandoffActive()) {
       return
     }
-    // Why: primary/fallback promise handlers may already own this failure; do
-    // not let their delayed paired error event consume fallback context.
+    // Why: fallback promise handlers may already own this failure; don't consume fallback context here.
     if (shouldSuppressMissingManifestPrereleaseFallbackEvent(message, err)) {
       return
     }
diff --git a/src/main/updater.test.ts b/src/main/updater.test.ts
index e516951d51e..837d1af4b9e 100644
--- a/src/main/updater.test.ts
+++ b/src/main/updater.test.ts
@@ -187,8 +187,7 @@ describe('updater', () => {
 
     setupAutoUpdater(mainWindow as never)
 
-    // Why: E2E launches use dev mode and Electron's direct script runner, whose
-    // default app version makes electron-updater throw during module load.
+    // Why: E2E dev-mode launches use a default app version that makes electron-updater throw during module load.
     expect(autoUpdaterMock.updateConfigPath).toBeUndefined()
     expect(autoUpdaterMock.setFeedURL).not.toHaveBeenCalled()
     expect(autoUpdaterMock.checkForUpdates).not.toHaveBeenCalled()
@@ -260,8 +259,7 @@ describe('updater', () => {
       .map(([, status]) => status)
 
     expect(statuses).toContainEqual({ state: 'checking', userInitiated: true })
-    // Why: the raw electron-updater message is replaced with a user-friendly
-    // one so we never surface "net::ERR_FAILED" directly to the UI.
+    // Why: the raw electron-updater message is replaced so we never surface "net::ERR_FAILED" to the UI.
     expect(statuses).not.toContainEqual(
       expect.objectContaining({ state: 'error', message: 'net::ERR_FAILED' })
     )
@@ -1001,9 +999,7 @@ describe('updater', () => {
 
     const { setupAutoUpdater, checkForUpdatesFromMenu } = await import('./updater')
 
-    // Why: pass a recent timestamp so the startup background check is
-    // deferred. We want to observe the state of the updater *before* any
-    // RC-mode call, not race with the startup check.
+    // Why: recent timestamp defers the startup check so we observe updater state before any RC-mode call, without racing.
     setupAutoUpdater(mainWindow as never, { getLastUpdateCheckAt: () => Date.now() })
     const setupFeedUrlCalls = autoUpdaterMock.setFeedURL.mock.calls.length
     expect(autoUpdaterMock.allowPrerelease).not.toBe(true)
@@ -1304,8 +1300,7 @@ describe('updater', () => {
     vi.useFakeTimers()
 
     autoUpdaterMock.quitAndInstall.mockImplementation(() => {
-      // Why: BaseUpdater dispatches 'error' synchronously inside install() for
-      // the common "no staged update filepath" path.
+      // Why: BaseUpdater dispatches 'error' synchronously inside install() for the common "no staged update filepath" path.
       autoUpdaterMock.emit(
         'error',
         new Error("No update filepath provided, can't quit and install")
@@ -1323,8 +1318,7 @@ describe('updater', () => {
 
     expect(autoUpdaterMock.quitAndInstall).toHaveBeenCalledTimes(1)
     expect(isQuittingForUpdate()).toBe(false)
-    // Why: destructive prep runs only after quitAndInstall returns still in
-    // progress; sync recovery clears flags first so PTYs stay alive.
+    // Why: destructive prep runs only after quitAndInstall returns still in progress; sync recovery clears flags first so PTYs stay alive.
     expect(killAllPtyMock).not.toHaveBeenCalled()
     expect(sendMock).toHaveBeenCalledWith(
       'updater:status',
@@ -1353,8 +1347,7 @@ describe('updater', () => {
     setupAutoUpdater(mainWindow as never, { getLastUpdateCheckAt: () => Date.now() })
     checkForUpdatesFromMenu()
 
-    // Why: put status in downloaded so a naive error handler would otherwise
-    // treat a late post-commit error as a download/install UI failure.
+    // Why: reach the downloaded state so a late post-commit error isn't mistaken for a download/install UI failure.
     await vi.waitFor(() => {
       expect(sendMock).toHaveBeenCalledWith('updater:status', {
         state: 'available',
@@ -1365,9 +1358,7 @@ describe('updater', () => {
 
     autoUpdaterMock.emit('update-downloaded', { version: '1.0.61' })
 
-    // Why: on macOS install is only "committed" once Squirrel is ready; mark
-    // it ready so this test covers the post-commit path on all platforms and
-    // the UI can leave the "waiting for Squirrel" downloading state.
+    // Why: on macOS install commits only once Squirrel is ready; mark it ready so this test covers the post-commit path on all platforms.
     if (process.platform === 'darwin') {
       const nativeDownloadedHandler = nativeUpdaterMock.on.mock.calls.find(
         ([eventName]) => eventName === 'update-downloaded'
@@ -1394,8 +1385,7 @@ describe('updater', () => {
     autoUpdaterMock.emit('error', new Error('late post-commit install error'))
 
     expect(isQuittingForUpdate()).toBe(true)
-    // Why: handoff still owns the process after commit — no recovery message
-    // and no general check/download error status either.
+    // Why: handoff still owns the process after commit — no recovery message or check/download error status.
     expect(sendMock).not.toHaveBeenCalled()
   })
 
@@ -1425,8 +1415,7 @@ describe('updater', () => {
     })
 
     autoUpdaterMock.emit('update-downloaded', { version: '1.0.61' })
-    // Why: on macOS install only commits once Squirrel is ready; mark it ready
-    // so this test covers the committed path on all platforms.
+    // Why: on macOS install commits only once Squirrel is ready; mark it ready so this test covers the committed path on all platforms.
     if (process.platform === 'darwin') {
       const nativeDownloadedHandler = nativeUpdaterMock.on.mock.calls.find(
         ([eventName]) => eventName === 'update-downloaded'
@@ -1442,8 +1431,7 @@ describe('updater', () => {
       expect(autoUpdaterMock.quitAndInstall).toHaveBeenCalledTimes(1)
     })
 
-    // Why: the installer (ShipIt/NSIS) waits for this process to exit; the
-    // watchdog guarantees a wedged async shutdown cannot strand the update.
+    // Why: the installer (ShipIt/NSIS) waits for this process to exit; the watchdog prevents a wedged async shutdown from stranding the update.
     expect(armExitWatchdogMock).toHaveBeenCalledTimes(1)
   })
 
@@ -1466,8 +1454,7 @@ describe('updater', () => {
     await vi.advanceTimersByTimeAsync(100)
 
     expect(isQuittingForUpdate()).toBe(false)
-    // Why: recovery leaves the app running — a live watchdog would force-exit
-    // a healthy session 20s later.
+    // Why: recovery leaves the app running; a live watchdog would force-exit a healthy session 20s later.
     expect(armExitWatchdogMock).not.toHaveBeenCalled()
     expect(disarmExitWatchdogMock).toHaveBeenCalled()
   })
@@ -1498,8 +1485,7 @@ describe('updater', () => {
     expect(isQuittingForUpdate()).toBe(true)
 
     sendMock.mockClear()
-    // Why: an unrelated error during pre-quit cleanup must not clear
-    // quittingForUpdate or emit the install-recovery status (native not invoked).
+    // Why: unrelated error during pre-quit cleanup must not clear quittingForUpdate or emit install-recovery status (native not invoked).
     autoUpdaterMock.emit('error', new Error('pre-native concurrent error'))
 
     expect(isQuittingForUpdate()).toBe(true)
@@ -1722,8 +1708,7 @@ describe('updater', () => {
 
     const { setupAutoUpdater, checkForUpdatesFromMenu } = await import('./updater')
 
-    // Why: pass a recent timestamp so the normal startup check is deferred,
-    // letting the nudge check run without hitting the 'checking' guard.
+    // Why: recent timestamp defers the startup check so the nudge check runs without hitting the 'checking' guard.
     setupAutoUpdater(mainWindow as never, {
       getLastUpdateCheckAt: () => Date.now()
     })
@@ -1818,10 +1803,7 @@ describe('updater', () => {
     // Wait for the startup nudge check to run
     await new Promise((resolve) => setTimeout(resolve, 0))
 
-    // The normal startup check is in progress (status is 'checking').
-    // The nudge fetch completed but the guard should have prevented
-    // calling runBackgroundUpdateCheck because currentStatus is 'checking'.
-    // Only the startup check should have called checkForUpdates.
+    // The 'checking' guard should block runBackgroundUpdateCheck while the startup check is in progress.
     expect(autoUpdaterMock.checkForUpdates).toHaveBeenCalledTimes(1)
   })
 
@@ -1843,8 +1825,7 @@ describe('updater', () => {
     // Wait for the startup nudge check to complete
     await vi.advanceTimersByTimeAsync(0)
 
-    // The startup check already set lastNudgeCheckAt. Triggering
-    // browser-window-focus should be blocked by the 5-minute cooldown.
+    // Startup check set lastNudgeCheckAt, so browser-window-focus is blocked by the 5-minute cooldown.
     fetchNudgeMock.mockClear()
     appMock.emit('browser-window-focus')
     await vi.advanceTimersByTimeAsync(0)
@@ -1891,8 +1872,7 @@ describe('updater', () => {
     // Now simulate the updater finding no update
     autoUpdaterMock.emit('update-not-available')
 
-    // Pending should be cleared and campaign should be auto-dismissed
-    // so it doesn't re-fire on the next poll cycle
+    // Pending cleared and campaign auto-dismissed so it doesn't re-fire next poll cycle.
     expect(setPendingUpdateNudgeId).toHaveBeenCalledWith(null)
     expect(setDismissedUpdateNudgeId).toHaveBeenCalledWith('campaign-1')
   })
@@ -2038,13 +2018,7 @@ describe('updater', () => {
     expect(setPendingUpdateNudgeId).toHaveBeenCalledWith(null)
   })
 
-  // Why: the Windows auto-updater must keep electron-updater's built-in
-  // Authenticode verification, which checks the downloaded installer against
-  // the SignPath Foundation publisherName that electron-builder embeds in
-  // app-update.yml. A no-op verifyUpdateCodeSignature override would silently
-  // accept every installer, so setup must NOT install one. (The issue #631
-  // stale-publisherName problem that once justified an override is resolved now
-  // that SignPath builds embed the correct publisherName.)
+  // Why: a no-op verifyUpdateCodeSignature override would silently accept every installer; keep electron-updater's Authenticode check (issue #631 resolved).
   it('does not disable Windows Authenticode verification on win32', async () => {
     vi.stubGlobal('process', { ...process, platform: 'win32' })
 
@@ -2071,12 +2045,7 @@ describe('updater', () => {
     expect((autoUpdaterMock as Record<string, unknown>).verifyUpdateCodeSignature).toBeUndefined()
   })
 
-  // Why: a prerelease user (e.g. 1.3.17-rc.1) must be able to upgrade to BOTH
-  // a newer RC (1.3.17-rc.2) and a newer stable (1.3.18). We solve this by
-  // resolving the newest tag ourselves from the atom feed and pinning the
-  // generic feed at /releases/download/<tag>/. Using electron-updater's
-  // native github provider with allowPrerelease would filter out stable
-  // releases for RC users, trapping them on the RC channel.
+  // Why: native github provider + allowPrerelease traps RC users on the RC channel, so resolve the newest tag ourselves and pin the generic feed to it.
   it('repins the generic feed to the newest RC tag for a prerelease user', async () => {
     appMock.getVersion.mockReturnValue('1.3.17-rc.1')
     fetchNewerReleaseTagsMock.mockResolvedValue(['v1.3.17-rc.2'])
@@ -2108,9 +2077,7 @@ describe('updater', () => {
     })
   })
 
-  // Why: the original bug in PR #1053 was that RC users couldn't upgrade to a
-  // newer stable release. The resolver must pick that stable tag for a
-  // prerelease user so the 'update-available' event fires against it.
+  // Why: RC users couldn't upgrade to newer stable (PR #1053); resolver must pick the stable tag for a prerelease user.
   it('repins the generic feed to a newer stable tag for a prerelease user', async () => {
     appMock.getVersion.mockReturnValue('1.3.19-rc.6')
     fetchNewerReleaseTagsMock.mockResolvedValue(['v1.3.19'])
@@ -2132,9 +2099,7 @@ describe('updater', () => {
     expect(autoUpdaterMock.allowPrerelease).not.toBe(true)
   })
 
-  // Why: if the atom-feed resolver fails or finds nothing newer, we must
-  // fall back to the default /releases/latest/download/ feed so the check
-  // can still complete and report "not-available" (rather than error out).
+  // Why: if the atom resolver fails or finds nothing newer, fall back to /releases/latest/download so the check completes as "not-available" instead of erroring.
   it('falls back to /releases/latest/download when the atom resolver returns null', async () => {
     appMock.getVersion.mockReturnValue('1.3.19-rc.6')
     fetchNewerReleaseTagsMock.mockResolvedValue([])
@@ -3231,9 +3196,7 @@ describe('updater', () => {
     })
   })
 
-  // Why: /releases/latest/download is a moving redirect. If a new stable
-  // release publishes between check and manual download, a relative ZIP URL
-  // from the old manifest can resolve against the new release and 404.
+  // Why: /releases/latest/download is a moving redirect; a relative ZIP URL from an old manifest can resolve against a newer release and 404.
   it('pins the generic feed to a concrete stable tag for a stable user', async () => {
     appMock.getVersion.mockReturnValue('1.3.17')
     fetchNewerReleaseTagsMock.mockResolvedValue(['v1.3.18'])
@@ -3258,9 +3221,7 @@ describe('updater', () => {
     })
   })
 
-  // Why: Shift-click opts into RC updates, but the native GitHub provider can
-  // still select cancelled prerelease tags with missing manifests. Keep the
-  // manifest-probed generic feed path so those tags are skipped.
+  // Why: native GitHub provider can pick cancelled prerelease tags with missing manifests, so keep the manifest-probed generic feed.
   it('uses the manifest-probed generic feed after a Shift-click RC opt-in', async () => {
     appMock.getVersion.mockReturnValue('1.3.17')
     fetchNewerReleaseTagsMock.mockResolvedValue(['v1.3.18-rc.1'])
diff --git a/src/main/updater.ts b/src/main/updater.ts
index 2ec8da1ec22..f2006195371 100644
--- a/src/main/updater.ts
+++ b/src/main/updater.ts
@@ -42,11 +42,7 @@ type ReleaseFeedPreflightResult = 'ready' | 'not-available'
 
 const AUTO_UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
 const AUTO_UPDATE_RETRY_INTERVAL_MS = 60 * 60 * 1000
-// Why: a persistently-failing feed (blocked domain, proxy, GHE mirror) used
-// to re-arm the retry at an exact 1h cadence forever — the recurring hourly
-// macOS Performance Diagnostics signature in issue #7576. Double the retry
-// delay per consecutive failure up to this cap; any completed check resets.
-// Release-publishing windows resolve within the first (still 1h) retry.
+// Why: a persistently-failing feed used to re-arm the retry at a fixed 1h cadence forever (issue #7576); backoff doubles per failure up to this cap, any completed check resets.
 const MAX_AUTO_UPDATE_RETRY_INTERVAL_MS = 6 * 60 * 60 * 1000
 const NUDGE_POLL_INTERVAL_MS = 30 * 60 * 1000
 const NUDGE_ACTIVATION_COOLDOWN_MS = 5 * 60 * 1000
@@ -60,9 +56,7 @@ let currentStatus: UpdateStatus = { state: 'idle' }
 let userInitiatedCheck = false
 let onBeforeQuitCleanup: (() => void | Promise<void>) | null = null
 let autoUpdaterInitialized = false
-// Why: modifier-clicking "Check for Updates" can target prerelease manifests.
-// The generic feed still gets pinned to a concrete tag on every check so
-// cancelled prereleases without manifests are skipped.
+// Why: modifier-clicking "Check for Updates" targets prerelease manifests; the feed still pins a concrete tag so cancelled prereleases without manifests are skipped.
 let includePrereleaseActive = false
 let availableVersion: string | null = null
 let availableReleaseUrl: string | null = null
@@ -72,19 +66,14 @@ let autoUpdateCheckTimer: ReturnType<typeof setTimeout> | null = null
 let nudgeCheckTimer: ReturnType<typeof setTimeout> | null = null
 let pendingQuitAndInstallTimer: ReturnType<typeof setTimeout> | null = null
 let quitAndInstallInProgress = false
-// Why: once quitAndInstall has committed (Win/Linux install, or macOS with
-// Squirrel ready), late autoUpdater 'error' events must not clear
-// quittingForUpdate — that would re-enable dock activate mid-installer.
+// Why: once install has committed, late 'error' events must not clear quittingForUpdate — that would re-enable dock activate mid-installer.
 let updateInstallCommitted = false
-// Why: quit-and-install recovery must only run after the native
-// quitAndInstall call. Pre-native cleanup-time autoUpdater errors must not
-// clear quittingForUpdate or look like install recovery.
+// Why: recovery must only run after the native quitAndInstall call; pre-native errors must not clear quittingForUpdate or look like install recovery.
 let quitAndInstallNativeInvoked = false
 let persistLastUpdateCheckAt: ((timestamp: number) => void) | null = null
 let _getLastUpdateCheckAt: (() => number | null) | null = null
 let backgroundCheckLaunchPending = false
-// Why: a manually promoted background check can emit an error event before the
-// paired promise catch runs; keep the promotion attached to that launch.
+// Why: a promoted background check can emit an error event before its promise catch runs; keep the promotion attached to that launch.
 let backgroundCheckPromotedToUserInitiated = false
 let updateCheckStallTimer: ReturnType<typeof setTimeout> | null = null
 let updateCheckSilentSettleTimer: ReturnType<typeof setTimeout> | null = null
@@ -102,8 +91,7 @@ let publishingWindowLastGoodCheck: { lastGoodTag: string } | null = null
 let pendingPrereleaseFallback: {
   primaryTag: string
   fallbackTag: string
-  // Why: the primary promise cleanup can run after fallback starts; fallback
-  // events need the attempt-scoped initiation state, not the mutable global.
+  // Why: primary promise cleanup can run after fallback starts; fallback events need this attempt-scoped state, not the mutable global.
   userInitiated: boolean
   suppressedPrimaryPromiseFailureKey: string | null
   suppressedPrimaryEventFailure: PrimaryEventSuppression | null
@@ -118,11 +106,9 @@ let _getPendingUpdateNudgeId: (() => string | null) | null = null
 let _getDismissedUpdateNudgeId: (() => string | null) | null = null
 let _setPendingUpdateNudgeId: ((id: string | null) => void) | null = null
 let _setDismissedUpdateNudgeId: ((id: string | null) => void) | null = null
-// Why: guards against duplicate download() calls while an accepted request
-// transitions the authoritative status to 'downloading'.
+// Why: guards against duplicate download() calls while an accepted request transitions status to 'downloading'.
 let downloadInFlight = false
-/** Guards against the macOS `activate` handler re-opening the old version
- *  while Squirrel's ShipIt is replacing the .app bundle. */
+/** Guards the macOS `activate` handler from reopening the old version while ShipIt replaces the .app bundle. */
 let quittingForUpdate = false
 let autoUpdater: ElectronAutoUpdater | null = null
 
@@ -166,9 +152,7 @@ function getPersistedPendingUpdateNudgeId(): string | null {
 }
 
 function decorateStatusWithActiveNudge(status: UpdateStatus): UpdateStatus {
-  // Why: only actionable/error states carry the nudge marker so the renderer
-  // can tell whether a dismiss should also acknowledge the campaign. Cycle-
-  // boundary states (idle, checking, not-available) never need it.
+  // Why: only actionable/error states carry the nudge marker so the renderer knows a dismiss should ack the campaign; cycle-boundary states never need it.
   if (!activeUpdateNudgeId) {
     return status
   }
@@ -195,8 +179,7 @@ function sendStatus(status: UpdateStatus): void {
   if (awaitingNudgeCheckOutcome) {
     if (status.state === 'available') {
       if (shouldPreserveNudgeForPublishingWindow) {
-        // Why: a last-good available update is only a temporary fallback; don't
-        // let dismissing that card consume the newest-release nudge campaign.
+        // Why: a last-good available update is only a temporary fallback; dismissing it must not consume the newest-release nudge campaign.
         deferPendingUpdateNudgeUntilRetry()
       } else {
         awaitingNudgeCheckOutcome = false
@@ -207,16 +190,10 @@ function sendStatus(status: UpdateStatus): void {
       status.state === 'error'
     ) {
       if (shouldPreserveNudgeForPublishingWindow) {
-        // Why: last-good checks can legitimately say "not available" while
-        // the campaign's newest release is still publishing.
+        // Why: last-good checks can say "not available" while the campaign's newest release is still publishing.
         deferPendingUpdateNudgeUntilRetry()
       } else {
-        // Why: when a nudge-triggered check finds no update (or errors out),
-        // move the campaign to dismissed so it doesn't re-fire on the next
-        // poll cycle. Without this, a nudge whose version range includes
-        // already-up-to-date users would loop every 30 minutes, each time
-        // triggering a redundant checkForUpdates() and clearing the persisted
-        // dismissedUpdateVersion.
+        // Why: on no-update, mark the campaign dismissed so a nudge covering already-up-to-date users doesn't re-fire every 30-min poll.
         if (activeUpdateNudgeId) {
           _setDismissedUpdateNudgeId?.(activeUpdateNudgeId)
         }
@@ -240,8 +217,7 @@ function sendStatus(status: UpdateStatus): void {
     clearPublishingWindowLastGoodCheck()
   }
 
-  // Why: reset the in-flight guard when the status moves past the
-  // window where duplicate download() calls are possible.
+  // Why: reset the in-flight guard once status moves past the window where duplicate download() calls are possible.
   if (
     decoratedStatus.state === 'downloading' ||
     decoratedStatus.state === 'error' ||
@@ -284,9 +260,7 @@ function getUpdateCheckVariant(options?: UpdateCheckOptions): UpdateCheckVariant
 function launchPendingUserInitiatedCheckAfterInFlight(variant: UpdateCheckVariant): void {
   pendingUserInitiatedCheckAfterInFlight = null
   setTimeout(() => {
-    // Why: electron-updater clears its in-flight promise after emitting the
-    // terminal event. Deferring one tick lets the queued modifier check start
-    // fresh instead of being deduped into the just-finished stable check.
+    // Why: defer one tick after electron-updater clears its in-flight promise so the queued modifier check starts fresh instead of deduping into the stable one.
     if (currentStatus.state === 'checking') {
       currentStatus = { state: 'idle' }
     }
@@ -405,8 +379,7 @@ function beginUpdateCheckAttempt(): number {
   updateCheckAttemptSequence += 1
   activeUpdateCheckAttemptId = updateCheckAttemptSequence
   armUpdateCheckStallTimer(activeUpdateCheckAttemptId)
-  // Why: issue #7576's warnings recurred at the retry cadence; field captures
-  // need a timestamp for each check attempt to confirm or rule the updater out.
+  // Why: issue #7576 warnings recurred at retry cadence; timestamp each attempt to confirm or rule out the updater.
   writeMainThreadDiagnosticMarker('updater-check-attempt')
   return activeUpdateCheckAttemptId
 }
@@ -444,8 +417,7 @@ function completeSilentUpdateCheck(userInitiated: boolean | undefined): boolean
   const shouldRetrySoon = consumeSilentCheckShortRetryReason()
   clearAvailableUpdateContext()
   if (shouldRetrySoon) {
-    // Why: a silent result against a temporary last-good feed is still part of
-    // a release transition, so it must not suppress the short publish retry.
+    // Why: a silent result against a temporary last-good feed is still a release transition, so it must not suppress the short publish retry.
     scheduleAutomaticUpdateCheck(AUTO_UPDATE_RETRY_INTERVAL_MS)
     return true
   }
@@ -493,9 +465,7 @@ function handleSettledUpdateCheckPromise(attemptId: number): void {
     return
   }
   clearUpdateCheckSilentSettleTimer()
-  // Why: electron-updater can resolve its promise before the terminal event
-  // reaches our handlers. Give that event a short grace period, then unstick
-  // checks that genuinely resolved without one.
+  // Why: electron-updater can resolve before the terminal event arrives; grace-period it, then unstick checks that resolved without one.
   updateCheckSilentSettleTimer = setTimeout(() => {
     updateCheckSilentSettleTimer = null
     settleSilentUpdateCheck(attemptId, getSettledCheckUserInitiated())
@@ -506,8 +476,7 @@ function shouldHandleUpdaterErrorEvent(): boolean {
   if (getActiveUpdateCheckEventAttemptId() !== null) {
     return true
   }
-  // Why: electron-updater emits check errors globally. Once a check has
-  // settled, only active download/install flows should keep consuming errors.
+  // Why: electron-updater emits check errors globally; once a check settles, only active download/install flows should consume them.
   return (
     downloadInFlight ||
     currentStatus.state === 'downloading' ||
@@ -523,8 +492,7 @@ function sendErrorStatus(message: string, userInitiated?: boolean): void {
   ) {
     return
   }
-  // Why: counts AV/EDR-blocked Windows signature checks in the field so we can
-  // size the affected cohort before investing in bigger updater changes.
+  // Why: count AV/EDR-blocked Windows signature checks in the field to size the affected cohort before bigger updater changes.
   if (isWindowsSignatureCheckUnavailableFailure(message)) {
     recordUpdaterLifecycle('windows_signature_check_blocked', undefined, {
       level: 'warn',
@@ -582,12 +550,7 @@ async function performQuitAndInstall(): Promise<void> {
 
   markMacQuitAndInstallInFlight()
 
-  // Set this BEFORE anything else so the `activate` handler in index.ts
-  // won't re-open the old version while Squirrel's ShipIt is replacing
-  // the .app bundle.  Without this guard the quit triggers window
-  // destruction → BrowserWindow.getAllWindows().length === 0 → activate
-  // fires → openMainWindow() resurrects the old process and ShipIt
-  // either can't replace it or the user ends up on the old version.
+  // Set BEFORE anything else so the `activate` handler doesn't reopen the old version while ShipIt replaces the .app bundle.
   quittingForUpdate = true
 
   const pendingVersion = getPendingInstallVersion()
@@ -610,23 +573,17 @@ async function performQuitAndInstall(): Promise<void> {
       recordUpdaterLifecycle('quit_and_install_invoking_native', {
         version: pendingVersion || null
       })
-      // Why: defensive — state should stay in-progress until native invoke, but
-      // never call quitAndInstall if recovery/reset already cleared the handoff.
+      // Why: defensive — never call quitAndInstall if recovery/reset already cleared the handoff.
       if (!quitAndInstallInProgress) {
         return
       }
-      // Why: mark before the call so a sync 'error' during quitAndInstall can
-      // recover; pre-native errors must not look like install failure.
+      // Why: mark before the call so a sync 'error' during quitAndInstall can recover; pre-native errors must not look like install failure.
       quitAndInstallNativeInvoked = true
-      // Why: invoke quitAndInstall before killAllPty/remove close listeners so a
-      // sync 'error' (common "no filepath" path) recovers while windows and
-      // local PTYs are still intact.
+      // Why: invoke before killAllPty/removing close listeners so a sync 'error' (the "no filepath" path) can recover while windows and PTYs are intact.
       getAutoUpdater().quitAndInstall(false, true)
       span.addEvent('native_quit_and_install_invoked')
 
-      // Why: handleQuitAndInstallFailure may clear quitAndInstallInProgress
-      // synchronously during quitAndInstall (Win/Linux dispatchError). Skip
-      // destructive prep if recovery already ran.
+      // Why: quitAndInstall can synchronously clear quitAndInstallInProgress via recovery (Win/Linux dispatchError); skip destructive prep if it already ran.
       if (!quitAndInstallInProgress) {
         return
       }
@@ -641,15 +598,10 @@ async function performQuitAndInstall(): Promise<void> {
         windowCount: BrowserWindow.getAllWindows().length
       })
 
-      // Why: committed installs must keep quittingForUpdate true so dock
-      // activate cannot reopen the old process mid-ShipIt/installer. macOS
-      // without Squirrel ready stays uncommitted so late native errors can
-      // still recover flags (PTYs may already be dead — residual OK).
+      // Why: committed installs keep quittingForUpdate so dock activate can't reopen the old process; macOS without Squirrel stays uncommitted so late native errors can still recover.
       if (process.platform !== 'darwin' || isMacInstallerReady()) {
         updateInstallCommitted = true
-        // Why: past this point recovery is forbidden and the installer waits
-        // for this process to exit; a wedged async shutdown would otherwise
-        // strand the user with no app and no update (#4438).
+        // Why: past commit the installer waits for this process to exit; a wedged async shutdown would strand the user with no app and no update (#4438).
         armUpdateInstallExitWatchdog()
       }
     })
@@ -678,12 +630,7 @@ function resetQuitForUpdateState(): void {
   resetMacInstallState()
 }
 
-// Why: electron-updater often reports quitAndInstall failures via the 'error'
-// event. On Win/Linux this is frequently synchronous (dispatchError inside
-// install()); on macOS/spawn it can be async. Recover only after native invoke
-// and only when install has not been committed — after commit, clearing
-// quittingForUpdate would allow dock activate to reopen the old process
-// mid-installer.
+// Why: quitAndInstall failures arrive via 'error'; recover only after native invoke and before commit, else clearing quittingForUpdate lets dock activate reopen the old process mid-installer.
 function handleQuitAndInstallFailure(): boolean {
   if (!quitAndInstallInProgress || !quitAndInstallNativeInvoked || updateInstallCommitted) {
     return false
@@ -697,8 +644,7 @@ function handleQuitAndInstallFailure(): boolean {
   return true
 }
 
-// Why: while quit-and-install owns the process (pre-native cleanup through
-// post-commit handoff), general check/download error UI must not run.
+// Why: while quit-and-install owns the process, general check/download error UI must not run.
 function isQuitAndInstallHandoffActive(): boolean {
   return quitAndInstallInProgress
 }
@@ -785,27 +731,16 @@ async function sendCheckFailureStatus(
 
   const handleFailure = async (): Promise<void> => {
     if (isBenignCheckFailure(message)) {
-      // Why: release transition failures (missing latest.yml while a new
-      // release is being published) and network blips are transient. Schedule
-      // a background retry so the notification arrives once the release
-      // finishes, and intentionally skip persistLastUpdateCheckAt — the check
-      // didn't truly complete, and recording a timestamp would suppress the
-      // next startup check.
+      // Why: benign failures (publishing latest.yml, network blips) are transient — retry, and skip persisting the timestamp (would suppress the next startup check).
       console.warn('[updater] benign check failure:', message)
       clearAvailableUpdateContext()
       scheduleAutomaticUpdateCheck(AUTO_UPDATE_RETRY_INTERVAL_MS)
       if (userInitiated) {
-        // Why: a user-initiated click expects visible feedback — silently
-        // dropping to 'idle' makes the button look broken. The card already
-        // prefixes "Could not check for updates." and Settings prefixes
-        // "Update check failed.", so the message here only carries the
-        // actionable cause.
+        // Why: a user click needs visible feedback (idle looks broken); the UI already prefixes context, so this carries only the actionable cause.
         sendErrorStatus("Couldn't reach the update server. Try again in a few minutes.", true)
       } else {
         if (isReleaseAssetsPublishingFailure(message)) {
-          // Why: a nudge-triggered check can land during the brief window where
-          // GitHub exposes a release before its updater assets are reachable.
-          // Keep the campaign pending so the short retry can still show it.
+          // Why: a nudge check can land while GitHub exposes a release before its assets; keep the campaign pending so the short retry can show it.
           deferPendingUpdateNudgeUntilRetry()
         }
         sendStatus({ state: 'idle' })
@@ -839,9 +774,7 @@ let consecutiveAutomaticRetrySchedules = 0
 
 function scheduleAutomaticUpdateCheck(delayMs: number): void {
   let effectiveDelayMs = delayMs
-  // All retry-cadence callers (here and updater-events) pass exactly this
-  // constant, so keying the backoff on it keeps one choke point instead of
-  // threading a flag through seven schedule sites.
+  // All retry-cadence callers pass exactly this constant, so keying backoff on it keeps one choke point instead of threading a flag through every schedule site.
   if (delayMs === AUTO_UPDATE_RETRY_INTERVAL_MS) {
     effectiveDelayMs = Math.min(
       AUTO_UPDATE_RETRY_INTERVAL_MS * 2 ** consecutiveAutomaticRetrySchedules,
@@ -853,10 +786,7 @@ function scheduleAutomaticUpdateCheck(delayMs: number): void {
     clearTimeout(autoUpdateCheckTimer)
   }
   autoUpdateCheckTimer = setTimeout(() => {
-    // Why: Orca is often left running for days. A one-shot startup check means
-    // users can miss fresh releases entirely, so we always keep the next
-    // background attempt scheduled in the main process instead of tying checks
-    // to relaunches or renderer lifetime.
+    // Why: Orca runs for days, so keep the next background check scheduled in the main process rather than tying it to relaunches or renderer lifetime.
     runBackgroundUpdateCheck()
   }, effectiveDelayMs)
 }
@@ -923,8 +853,7 @@ function shouldSuppressMissingManifestPrereleaseFallbackEvent(
   const primaryEventSuppression = pendingPrereleaseFallback.suppressedPrimaryEventFailure
   if (primaryEventSuppression?.failureKey === failureKey) {
     const isPrimaryPromisePair = primaryEventSuppression.error === error
-    // Why: after fallback checking starts, same-message errors may belong to
-    // the fallback attempt, so message matching alone is not safe.
+    // Why: after fallback checking starts, same-message errors may be the fallback's, so message matching alone isn't safe.
     if (isPrimaryPromisePair || !pendingPrereleaseFallback.fallbackCheckingForUpdateSeen) {
       pendingPrereleaseFallback.suppressedPrimaryEventFailure = null
       clearPrereleaseFallbackContextIfSettled()
@@ -956,12 +885,7 @@ async function pinDefaultReleaseFeed(
   variant: UpdateCheckVariant = 'default'
 ): Promise<ReleaseFeedPreflightResult> {
   const autoUpdater = getAutoUpdater()
-  // Why: the /releases/latest/download/ redirect can move between the update
-  // check and the later manual download click. Pinning to the concrete tag
-  // keeps the manifest and ZIP asset on the same release.
-  //
-  // Prerelease users still need any-channel resolution so they can move to a
-  // newer RC or the next stable. Stable users should only resolve stable tags.
+  // Why: the latest/download redirect can move between check and download, so pin the concrete tag (prerelease users resolve any channel, stable only stable).
   const currentVersion = app.getVersion()
   const isPerfCheck = variant === 'perf'
   const includePrerelease =
@@ -991,10 +915,7 @@ async function pinDefaultReleaseFeed(
           retryLaunched: false
         }
       : null
-  // Why: console.info goes to stdout and is captured by Console.app on macOS
-  // and by --enable-logging elsewhere. This is the only window we have into
-  // the updater on a user's machine when something goes wrong. Cheap to keep,
-  // invaluable when triaging.
+  // Why: console.info is captured by Console.app/--enable-logging — our only field visibility into the updater.
   if (newerTag) {
     clearPublishingWindowLastGoodCheck()
     const url = getReleaseDownloadUrl(newerTag)
@@ -1006,8 +927,7 @@ async function pinDefaultReleaseFeed(
   } else if (releaseTagsResult.state === 'not-ready') {
     clearPrereleaseFallbackContext()
     if (releaseTagsResult.lastGoodTag) {
-      // Why: during a publish window the newest tag is unsafe, but a verified
-      // last-good concrete feed lets electron-updater emit a real result.
+      // Why: during a publish window the newest tag is unsafe; a verified last-good concrete feed lets electron-updater emit a real result.
       const url = getReleaseDownloadUrl(releaseTagsResult.lastGoodTag)
       console.info(
         `[updater] release feed pinned to last-good: current=${currentVersion} includePrerelease=${includePrerelease} → ${url}`
@@ -1062,9 +982,7 @@ function retryPrereleaseFallbackAfterMissingManifest(
     return false
   }
 
-  // Why: a published tag can briefly point at a missing platform manifest
-  // during GitHub release transitions. Walk back once to the previous feed
-  // entry so users on the last good build see a normal not-available result.
+  // Why: a published tag can briefly lack its platform manifest mid-release; walk back once to the previous feed for a normal not-available result.
   pendingPrereleaseFallback.retryLaunched = true
   pendingPrereleaseFallback.userInitiated = Boolean(userInitiated)
   pendingPrereleaseFallback.suppressedPrimaryPromiseFailureKey =
@@ -1113,21 +1031,13 @@ function runBackgroundUpdateCheck(
     sendStatus({ state: 'not-available' })
     return
   }
-  // Why: scope the nudge marker to the updater cycle being launched right now.
-  // Setting it here, before any updater events or rejected promises can arrive,
-  // prevents later ordinary checks from inheriting an older campaign id. Use
-  // the persisted pending id for ordinary background checks so a nudge-driven
-  // card can still be dismissed correctly after relaunch or a later 24h check.
+  // Why: set the nudge marker before any events arrive so later checks can't inherit a stale campaign id; persisted id keeps a nudge card dismissable after relaunch.
   activeUpdateNudgeId = nudgeId
-  // Why: autoUpdater.checkForUpdates() is async and 'checking-for-update'
-  // arrives on a later tick, so a second focus/resume event can slip in before
-  // currentStatus flips to 'checking'. Track the launch in memory to dedupe
-  // that gap without persisting a successful-check timestamp before the result.
+  // Why: 'checking-for-update' arrives a tick later, so a second focus/resume can slip in before status flips; track launch in memory to dedupe that gap.
   backgroundCheckLaunchPending = true
   backgroundCheckPromotedToUserInitiated = false
   const attemptId = beginUpdateCheckAttempt()
-  // Don't send 'checking' here — the 'checking-for-update' event handler does it,
-  // and sending it from both places causes duplicate notifications (issue #35).
+  // Don't send 'checking' here — the 'checking-for-update' handler does; sending from both dupes notifications (issue #35).
   const autoUpdater = getAutoUpdater()
   const launch = (): Promise<unknown> | undefined => {
     if (!isActiveUpdateCheckAttempt(attemptId)) {
@@ -1154,18 +1064,7 @@ function runBackgroundUpdateCheck(
 }
 
 export function checkForUpdates(): void {
-  // Fire-and-forget the span so the public function signature stays
-  // synchronous (callers do not await this). The span ALWAYS records
-  // Success — it captures only the launch of the check, not its outcome.
-  // The actual check runs through autoUpdater event handlers; failure is
-  // surfaced via sendCheckFailureStatus on a separate code path.
-  // Dashboards: do not group on this span's outcome attribute — the
-  // success rate here reflects launch dispatch, not check success, and
-  // will read ~100% by construction. Instead, filter on
-  // `updater.outcome === 'launched'` to count check-launch dispatches; the
-  // attribute makes the always-success semantics explicit and queryable
-  // (so a dashboard tile can't accidentally treat this span's success rate
-  // as the actual update-check success rate).
+  // Why: span records only check launch (always Success), not outcome; dashboards must filter `updater.outcome === 'launched'`, not this span's success rate.
   void withUpdaterSpan({ stage: 'check' }, async (span) => {
     span.setAttribute('updater.outcome', 'launched')
     runBackgroundUpdateCheck()
@@ -1180,10 +1079,7 @@ function enableIncludePrerelease(): void {
   if (includePrereleaseActive) {
     return
   }
-  // Why: generic-provider checks still need this flag so electron-updater will
-  // accept a prerelease manifest for users who intentionally Shift-clicked.
-  // We keep using the manifest-probed generic feed instead of the native
-  // GitHub provider because cancelled RC releases can appear without assets.
+  // Why: this flag makes electron-updater accept prerelease manifests; we keep the manifest-probed generic feed over the native GitHub provider because cancelled RCs can appear without assets.
   enablePrereleaseManifestChecks()
   includePrereleaseActive = true
 }
@@ -1201,27 +1097,21 @@ export function checkForUpdatesFromMenu(options?: UpdateCheckOptions): void {
     enableIncludePrerelease()
   } else if (checkVariant === 'perf') {
     clearPrereleaseFallbackContext()
-    // Why: perf checks need prerelease manifests for this check, but must not
-    // opt future default/background checks into the RC channel.
+    // Why: perf checks need prerelease manifests now, but must not opt future default/background checks into the RC channel.
     enablePrereleaseManifestChecks()
   }
 
   const checkAlreadyInFlight = backgroundCheckLaunchPending || currentStatus.state === 'checking'
   userInitiatedCheck = true
-  // Why: a manual check is independent of any active nudge campaign. Reset the
-  // nudge marker so the resulting status is not decorated with activeNudgeId,
-  // which would cause a later dismiss to consume the campaign by accident.
+  // Why: manual checks are nudge-independent; clear the marker so a later dismiss can't consume the campaign by accident.
   activeUpdateNudgeId = null
-  // Why: manual checks should visibly respond before feed pinning or the
-  // electron-updater event fires; duplicate event broadcasts are suppressed by
-  // status equality below.
+  // Why: respond visibly before feed pinning/updater events; duplicate broadcasts are suppressed by status equality below.
   sendStatus({ state: 'checking', userInitiated: true })
   if (checkAlreadyInFlight) {
     backgroundCheckPromotedToUserInitiated = true
     rearmActiveUpdateCheckStallTimer()
     if (checkVariant !== 'default') {
-      // Why: the in-flight check may have already pinned the stable feed. Queue
-      // a fresh modifier check so it doesn't inherit a stale-channel result.
+      // Why: in-flight check may have pinned the stable feed; queue a fresh modifier check to avoid a stale-channel result.
       pendingUserInitiatedCheckAfterInFlight = checkVariant
     }
     return
@@ -1285,10 +1175,7 @@ export function quitAndInstall(): void {
     return
   }
 
-  // Why: every renderer entrypoint reaches this IPC handler from an in-flight
-  // click or toast callback. Deferring the actual quit here gives the renderer
-  // a moment to flush dismissals/state updates before windows start closing,
-  // and centralizing it avoids drift between the toast flow and settings UI.
+  // Why: defer the quit a tick so the renderer can flush dismissals/state before windows start closing.
   pendingQuitAndInstallTimer = setTimeout(() => {
     void performQuitAndInstall()
   }, QUIT_AND_INSTALL_DELAY_MS)
@@ -1391,12 +1278,7 @@ export function setupAutoUpdater(
   autoUpdater.autoDownload = false
   autoUpdater.autoInstallOnAppQuit = true
 
-  // Why: the only on-machine window we have into electron-updater. Without
-  // this, an unexpected `update-not-available` (e.g. RC user not offered
-  // newer stable) is invisible — we can't tell whether the manifest fetch
-  // got the wrong version, the request failed, or a stale in-flight check
-  // was deduped. Logs go to main-process stdout, captured on macOS by
-  // Console.app under the app bundle, and on Win/Linux by --enable-logging.
+  // Why: our only on-machine window into electron-updater; otherwise an unexpected update-not-available or failed fetch is invisible.
   autoUpdater.logger = {
     info: (m: unknown) => console.info('[autoUpdater]', m),
     warn: (m: unknown) => console.warn('[autoUpdater]', m),
@@ -1404,21 +1286,9 @@ export function setupAutoUpdater(
     debug: (m: unknown) => console.debug('[autoUpdater]', m)
   } as never
 
-  // Why: Windows update integrity is enforced by electron-updater's built-in
-  // Authenticode check against the `publisherName` (SignPath Foundation) that
-  // electron-builder embeds in app-update.yml. Do NOT re-add a
-  // `verifyUpdateCodeSignature` override — a no-op override silently accepts
-  // every downloaded installer, disabling signature verification entirely.
+  // Security: never re-add a verifyUpdateCodeSignature override — a no-op disables electron-updater's built-in Authenticode check and accepts any installer.
 
-  // Use the generic provider with GitHub's /releases/latest/download/ URL as
-  // the startup fallback so electron-updater can fetch the manifest
-  // (latest-mac.yml, latest.yml, latest-linux.yml) from the latest
-  // non-prerelease release.
-  //
-  // Why: before each default-channel check we repin this URL to a concrete
-  // /releases/download/<tag>/ URL. Keeping the generic provider avoids the
-  // native GitHub provider's RC channel filtering, and pinning avoids the
-  // moving /latest redirect changing between check and download.
+  // Why: generic provider avoids the native GitHub provider's RC-channel filtering; per-check repinning to a concrete /releases/download/<tag>/ URL avoids /latest redirect drift between check and download.
   autoUpdater.setFeedURL({
     provider: 'generic',
     url: 'https://github.com/stablyai/orca/releases/latest/download'
@@ -1508,10 +1378,7 @@ export function downloadUpdate(): void {
   if (downloadInFlight) {
     return
   }
-  // Why: permit retry from 'error' when we still have a cached availableVersion —
-  // a failed download leaves the status at 'error' but availableVersion intact,
-  // and the error card's "Retry Download" button must be able to restart the
-  // download. Without this, the button would appear to do nothing.
+  // Why: allow retry from 'error' (availableVersion stays cached) so the error card's Retry Download button works.
   const canStart =
     currentStatus.state === 'available' ||
     (currentStatus.state === 'error' && hasNewerDownloadedVersion())
@@ -1524,8 +1391,7 @@ export function downloadUpdate(): void {
   }
   downloadInFlight = true
   beginMacUpdateDownload()
-  // Why: retries may spend seconds in setup before electron-updater emits
-  // progress; surface acceptance immediately so the action never looks inert.
+  // Why: setup can take seconds before progress emits; surface acceptance now so the action never looks inert.
   sendStatus({ state: 'downloading', percent: 0, version })
   getAutoUpdater()
     .downloadUpdate()
diff --git a/src/main/window/attach-main-window-services.ts b/src/main/window/attach-main-window-services.ts
index f38bd40d438..062e848c31d 100644
--- a/src/main/window/attach-main-window-services.ts
+++ b/src/main/window/attach-main-window-services.ts
@@ -50,10 +50,7 @@ import { logStartupMilestone } from '../startup/startup-diagnostics'
 
 const UPDATER_SETUP_FALLBACK_MS = 15_000
 
-// Why: updater setup is deferred past first paint, but a manual check (app
-// menu or updater:check IPC) can arrive inside that window — it must run
-// against a configured updater (listeners, autoDownload=false, window ref),
-// so those entry points force the pending setup first.
+// Why: a manual check can arrive before deferred setup runs, so entry points force this pending setup to configure the updater first.
 let pendingAutoUpdaterSetup: (() => void) | null = null
 
 export function ensureAutoUpdaterConfigured(): void {
@@ -102,28 +99,13 @@ export function attachMainWindowServices(
       isRecoveryReloadInFlight: options?.isRecoveryReloadInFlight
     }
   )
-  // Why: the Manage Sessions settings panel (docs/daemon-staleness-ux.md §Phase 1)
-  // uses a narrow `pty:management:*` IPC surface that reads the live
-  // DaemonPtyRouter via getDaemonProvider(). Registering here — after
-  // registerPtyHandlers — keeps this wiring alongside the rest of the PTY IPC
-  // and ensures the handlers are re-installed on macOS app re-activation when
-  // the main window is recreated.
+  // Why: register after registerPtyHandlers so pty:management:* IPC re-installs on macOS re-activation (docs/daemon-staleness-ux.md §Phase 1).
   registerDaemonManagementHandlers()
-  // Why: do not enumerate repo paths from background GC. `git worktree list`
-  // can re-touch protected folders on macOS and trigger folder-access prompts.
+  // Why: don't enumerate repo paths in background GC — `git worktree list` can touch protected macOS folders and trigger access prompts.
   scheduleHistoryGc(async () => {
     return getKnownWorktreeIdsForHistoryGc(store)
   })
-  // Why: warm-reattach gap.
-  // Daemon-hosted PTYs survive renderer restarts on purpose, so on a fresh
-  // Orca launch the daemon's `listSessions()` returns sessions that
-  // `pty:spawn` hasn't re-registered yet. Without this hydration, the
-  // memory snapshot omits those PTYs and the renderer mislabels their
-  // workspaces as `· REMOTE` while showing `—` for CPU/Memory.
-  // `hydrateLocalPtyRegistryAtBoot` is idempotent (no-op after the first
-  // call), so calling it on every macOS dock re-activation — when this
-  // function re-runs as the main window is recreated — does not redo the
-  // git I/O or daemon RPC.
+  // Why: daemon PTYs survive renderer restarts, so at boot they're unregistered; hydrate so they aren't mislabeled REMOTE (idempotent, safe to re-run).
   void hydrateLocalPtyRegistryAtBoot(store)
   const localPtyStartupReady = options?.awaitLocalPtyStartup?.()
   if (localPtyStartupReady) {
@@ -139,11 +121,7 @@ export function attachMainWindowServices(
   registerSshHandlers(store, () => mainWindow, runtime)
   registerRemoteWorkspaceHandlers(store, () => mainWindow)
   registerFileDropRelay(mainWindow)
-  // Why: setupAutoUpdater's first getAutoUpdater() call synchronously
-  // require()s electron-updater in packaged builds — seconds on a cold
-  // Windows disk under Defender scanning (part of issue #7225's pre-paint
-  // stall) — so defer it past first paint. The timer fallback keeps update
-  // checks alive for renderers that crash-loop before ever painting.
+  // Why: setupAutoUpdater sync-require()s electron-updater (slow on cold Windows w/ Defender, #7225), so defer past first paint; timer fallback covers crash-looping renderers.
   let updaterSetupDone = false
   const setupAutoUpdaterDeferred = (): void => {
     if (updaterSetupDone || mainWindow.isDestroyed()) {
@@ -165,12 +143,7 @@ export function attachMainWindowServices(
       getPendingUpdateNudgeId: () => store.getUI().pendingUpdateNudgeId ?? null,
       getDismissedUpdateNudgeId: () => store.getUI().dismissedUpdateNudgeId ?? null,
       setPendingUpdateNudgeId: (id) => {
-        // Why: the nudge lifecycle is owned by the main process. When applying a
-        // new campaign, persist the pending id AND clear the version dismissal
-        // together so relaunches cannot resurrect the old hidden-card state
-        // between nudge apply and renderer sync. When clearing (id is null),
-        // only touch pendingUpdateNudgeId — clearing dismissedUpdateVersion here
-        // would silently un-dismiss an update if the flow ever changes.
+        // Why: only the apply branch also nulls dismissedUpdateVersion so relaunch can't resurrect the old hidden card; clearing must not, or it un-dismisses.
         if (id) {
           store.updateUI({ pendingUpdateNudgeId: id, dismissedUpdateVersion: null })
         } else {
@@ -212,9 +185,7 @@ export function attachMainWindowServices(
   )
 
   mainWindow.on('closed', () => {
-    // Why: browser webviews are renderer-owned guest surfaces. Clearing
-    // main-owned guest registrations on window close prevents stale
-    // tab→webContents ids from leaking across app relaunch or hot-reload cycles.
+    // Why: clear main-owned guest registrations on close so stale tab→webContents ids don't leak across relaunch/hot-reload.
     browserManager.unregisterAll()
   })
 }
@@ -223,8 +194,7 @@ function registerAppReloadHandler(
   mainWindow: BrowserWindow,
   onBeforeRendererReload?: (args: { webContentsId: number; ignoreCache: boolean }) => void
 ): void {
-  // Why: the process-global IPC handler can outlive the BrowserWindow, so keep
-  // the registered WebContents and guard both lifetimes before using it.
+  // Why: the process-global IPC handler can outlive the window, so guard both lifetimes before using the WebContents.
   const handlerToken = ++appReloadHandlerTokenCounter
   activeAppReloadHandlerToken = handlerToken
   const mainWebContents = mainWindow.webContents
@@ -244,8 +214,7 @@ function registerAppReloadHandler(
     if (activeAppReloadHandlerToken !== handlerToken) {
       return
     }
-    // Why: macOS can keep the process alive with no window, and this global
-    // handler otherwise keeps the closed BrowserWindow reachable until reopen.
+    // Why: macOS keeps the process alive with no window; this handler would otherwise retain the closed window until reopen.
     ipcMain.removeHandler('app:reload')
     activeAppReloadHandlerToken = null
   })
@@ -265,8 +234,7 @@ function registerRuntimeWindowLifecycle(
   }
   runtime.setNotifier({
     worktreesChanged: (repoId, renamed) => {
-      // Why: clear detected-worktree scan caches before renderer listeners
-      // handle this event, preventing stale TTL reads after mutations.
+      // Why: clear scan caches before the renderer handles this event, so it can't read stale TTL entries after a mutation.
       runWorktreeChangeInvalidators(repoId)
       send('worktrees:changed', renamed ? { repoId, renamed } : { repoId })
     },
@@ -308,8 +276,7 @@ function registerRuntimeWindowLifecycle(
           event: Electron.IpcMainEvent,
           reply: { requestId: string; tabId?: string; title?: string; error?: string }
         ): void => {
-          // Why: requestId is renderer-supplied; only the targeted main window
-          // may satisfy the reveal and provide the tab handle.
+          // Why: requestId is renderer-supplied, so only the targeted main window may satisfy the reveal.
           if (event.sender !== mainWindow.webContents || reply.requestId !== requestId) {
             return
           }
@@ -334,9 +301,7 @@ function registerRuntimeWindowLifecycle(
           ...(opts.viewMode ? { viewMode: opts.viewMode } : {}),
           activate: opts.activate !== false,
           ...(opts.presentation ? { presentation: opts.presentation } : {}),
-          // Why: pre-minted tabId from main keeps the renderer's tab id aligned
-          // with the paneKey baked into the PTY env at spawn time, so hook
-          // events route to the right slot.
+          // Why: pre-minted tabId aligns the renderer tab id with the paneKey baked into the PTY env, so hook events route right.
           ...(opts.tabId !== undefined ? { tabId: opts.tabId } : {}),
           ...(opts.leafId !== undefined ? { leafId: opts.leafId } : {}),
           ...(opts.splitFromLeafId !== undefined ? { splitFromLeafId: opts.splitFromLeafId } : {}),
@@ -402,18 +367,14 @@ function registerRuntimeWindowLifecycle(
     browserDriverChanged: (browserPageId, driver) =>
       send('runtime:browserDriverChanged', { browserPageId, driver })
   })
-  // Why: the runtime must fail closed while the renderer graph is being torn
-  // down or rebuilt, otherwise future CLI calls could act on stale terminal
-  // mappings during reload transitions.
+  // Why: fail closed during renderer reload so CLI calls can't act on stale terminal mappings.
   mainWindow.webContents.on('did-start-loading', () => {
     runtime.markRendererReloading(mainWindow.id)
   })
   mainWindow.on('closed', () => {
     runtime.markGraphUnavailable(mainWindow.id)
     if (activeRuntimeNotifierToken === notifierToken) {
-      // Why: the notifier closes over the BrowserWindow for mobile/CLI UI
-      // relays; clear it during the no-window gap so the runtime does not
-      // retain destroyed window graphs.
+      // Why: the notifier closes over the window; clear it in the no-window gap so the runtime can't retain destroyed graphs.
       runtime.setNotifier(null)
       activeRuntimeNotifierToken = null
     }
@@ -436,14 +397,12 @@ function registerFileDropRelay(mainWindow: BrowserWindow): void {
       return
     }
 
-    // Why: relay exactly one IPC event per drop gesture so the renderer
-    // receives the full batch of paths without timer-based reconstruction.
+    // Why: one IPC event per drop gesture so the renderer gets the full path batch without timer-based reconstruction.
     mainWindow.webContents.send('terminal:file-drop', args)
   }
   ipcMain.on(channel, relayFileDrop)
   mainWindow.on('closed', () => {
-    // Why: macOS can keep the app process alive after the window closes; drop
-    // the relay closure so a destroyed BrowserWindow is not retained.
+    // Why: macOS keeps the process alive after window close; drop the closure so the destroyed window isn't retained.
     ipcMain.removeListener(channel, relayFileDrop)
   })
 }
diff --git a/src/main/window/createMainWindow.ts b/src/main/window/createMainWindow.ts
index c07ed455461..3be600cb56b 100644
--- a/src/main/window/createMainWindow.ts
+++ b/src/main/window/createMainWindow.ts
@@ -50,13 +50,11 @@ import { buildEditableContextMenuTemplate } from './editable-context-menu'
 import { clearTrustedUIRendererWebContentsId, setTrustedUIRendererWebContentsId } from '../ipc/ui'
 import { resolveWindowCloseAction } from './window-close-decision'
 
-// Why: show/restore/resume can overlap before the size nudge resets; never
-// capture the temporary width as the next repaint's baseline.
+// Why: show/restore/resume can overlap before the size nudge resets; never capture the temporary width as the next baseline.
 const activeRepaintJiggles = new WeakSet<BrowserWindow>()
 
 function forceRepaint(window: BrowserWindow): void {
-  // Why: webContents can be destroyed a beat before the BrowserWindow during
-  // close, and this runs from timers/focus events that can land in that gap.
+  // Why: webContents can be destroyed a beat before the BrowserWindow during close, and this runs from timers/focus events in that gap.
   if (window.isDestroyed() || window.webContents.isDestroyed()) {
     return
   }
@@ -82,8 +80,7 @@ function installMacosVisibilityRepaint(window: BrowserWindow): void {
     if (delayedRepaintTimer) {
       clearTimeout(delayedRepaintTimer)
     }
-    // Why: macOS can finish restoring webview compositor layers after Electron's
-    // show/restore event, so a second paint catches late black-surface recovery.
+    // Why: macOS may restore compositor layers after the show/restore event; a second paint catches late black-surface recovery.
     delayedRepaintTimer = setTimeout(() => {
       delayedRepaintTimer = null
       forceRepaint(window)
@@ -98,9 +95,7 @@ function installMacosVisibilityRepaint(window: BrowserWindow): void {
 
   window.on('restore', repaintAfterVisibilityTransition)
   window.on('show', repaintAfterVisibilityTransition)
-  // Why: occlusion-uncover fires neither restore nor show; focus is the only
-  // signal. Invalidate only — the setSize jiggle would SIGWINCH every terminal
-  // on each Cmd+Tab.
+  // Why: occlusion-uncover fires no restore/show, only focus; invalidate only — the setSize jiggle would SIGWINCH every terminal on Cmd+Tab.
   window.on('focus', () => {
     if (!window.isDestroyed() && !window.webContents.isDestroyed()) {
       window.webContents.invalidate()
@@ -121,10 +116,7 @@ function isMacAppPasteInput(input: Electron.Input): boolean {
   )
 }
 
-// Why: the titlebar is 36px (border-box, 1px border-bottom).  The visual
-// center of the CSS-centered content sits at ~18 CSS px from the top.
-// At zoom factor z that becomes 18·z window px.  Traffic lights are
-// ~12px tall, so we position their top edge at (center − 6).
+// Why: titlebar content center sits ~18 CSS px from top (×zoom); traffic lights are ~12px tall, so top edge = center − 6.
 const TITLEBAR_CSS_CENTER = 18
 const TRAFFIC_LIGHT_RADIUS = 6
 const TRAFFIC_LIGHT_X = 16
@@ -140,44 +132,31 @@ function syncTrafficLightPosition(win: BrowserWindow, zoomFactor: number): void
 }
 
 type CreateMainWindowOptions = {
-  /** Returns true when a manual app.quit() (Cmd+Q) is in progress. The close
-   *  handler sends this to the renderer so it can skip the running-process
-   *  confirmation dialog and proceed directly to buffer capture + close. */
+  /** Returns true when a manual app.quit() (Cmd+Q) is in progress, so the renderer skips the running-process confirm dialog. */
   getIsQuitting?: () => boolean
-  /** Notifies the caller when the renderer vetoes unload. Why: a prevented
-   *  beforeunload cancels the in-flight app.quit(), so the app-level quit
-   *  latch must be cleared or later window closes will be misclassified as
-   *  quit attempts. */
+  /** Notifies the caller when the renderer vetoes unload, so the quit latch clears — a prevented beforeunload cancels the in-flight app.quit(). */
   onQuitAborted?: () => void
   onRendererProcessGone?: (
     details: Electron.RenderProcessGoneDetails,
     webContentsId: number
   ) => void
-  /** Returns true when Orca should reload after an unexpected renderer loss.
-   *  Why: update relaunch and app quit intentionally tear down child
-   *  processes; recovering those paths can fight Electron's shutdown. */
+  /** Returns true when Orca should reload after renderer loss; update-relaunch/quit tear down children intentionally, so don't fight shutdown. */
   shouldRecoverRenderer?: (
     details: Electron.RenderProcessGoneDetails,
     webContentsId: number
   ) => boolean
-  /** Called when consecutive auto-recoveries hit the circuit-breaker limit, so
-   *  the host can record diagnostics and surface a recovery prompt instead of
-   *  letting Orca crash-loop. */
+  /** Called when consecutive auto-recoveries hit the circuit-breaker limit so the host can prompt instead of crash-looping. */
   onRendererRecoveryExhausted?: (info: {
     details: Electron.RenderProcessGoneDetails
     webContentsId: number
     recentRecoveryCount: number
   }) => void
-  /** Why: main-process startup must register IPC handlers before the renderer
-   *  begins booting, or eager renderer calls can race into missing channels. */
+  /** Defer renderer load until IPC handlers are registered, or eager renderer calls race into missing channels. */
   deferLoad?: boolean
   title?: string
   getKeybindings?: () => KeybindingOverrides | undefined
   onBeforeReload?: (options: { ignoreCache: boolean; webContentsId: number }) => void
-  /** Why: the in-place renderer-recovery reload re-fires did-finish-load, whose
-   *  local-PTY orphan sweep would kill live sessions across the single window
-   *  before session restore re-attaches them (#5787). This callback lets the host
-   *  mark that one reload so the sweep can be skipped for it. */
+  /** Marks the in-place recovery reload so did-finish-load's PTY orphan sweep spares live sessions until restore re-attaches (#5787). */
   onBeforeRecoveryReload?: (webContentsId: number) => void
 }
 
@@ -194,19 +173,8 @@ export function createMainWindow(
   opts?: CreateMainWindowOptions
 ): BrowserWindow {
   const rawSavedBounds = store?.getUI().windowBounds
-  // Why: defense in depth — if a previous quit/update path persisted
-  // shrink-to-min bounds (see freezeBoundsOnQuit), discard them on restore
-  // rather than resurrecting a tiny window. Anything at or below the min
-  // dimensions is treated as corrupt and falls back to defaultBounds. The
-  // position must also land on a currently-attached display with a
-  // *meaningful* visible area — not just any >0 overlap, since a 1-pixel
-  // sliver (or a sub-pixel shaving after DPI scaling) would still leave
-  // the titlebar unreachable. Require at least MIN_WIDTH/2 of horizontal
-  // and MIN_HEIGHT/2 of vertical overlap with some display's workArea
-  // (workArea excludes menu bar / dock, so a rect entirely hidden under
-  // the dock is also correctly discarded). A rect saved while an external
-  // monitor was connected would otherwise be restored off-screen and
-  // macOS would silently shrink/reposition the window.
+  // Why: discard persisted bounds that are shrink-to-min (corrupt, see freezeBoundsOnQuit) or off-screen, falling back to defaultBounds.
+  // Require ~half MIN_WIDTH/HEIGHT of workArea overlap so a 1px sliver or dock-hidden rect isn't treated as visible.
   const rectHasVisibleAreaOnAnyDisplay = (b: {
     x: number
     y: number
@@ -242,9 +210,7 @@ export function createMainWindow(
     )
   }
   const savedMaximized = store?.getUI().windowMaximized ?? false
-  // Why: on first launch (no saved bounds), fill the primary display work area
-  // so the window feels spacious without calling maximize(). Saved bounds still
-  // win on subsequent launches.
+  // Why: on first launch fill the primary display work area so the window feels spacious without maximize(); saved bounds win later.
   const defaultBounds = (() => {
     try {
       const { width, height } = screen.getPrimaryDisplay().workAreaSize
@@ -256,16 +222,11 @@ export function createMainWindow(
 
   const settings = store?.getSettings()
   browserManager.setDictationShortcutForwardingPredicate(() => {
-    // Why: focused webview guests do not expose a safe transcript insertion
-    // target yet. Let Cmd/Ctrl+E continue to the page instead of starting a
-    // dictation session whose final text would be dropped.
+    // Why: webview guests expose no safe transcript insertion target; let Cmd/Ctrl+E reach the page instead of dropping dictation text.
     return false
   })
   const blur = settings?.windowBackgroundBlur ?? false
-  // Why: native blur requires platform-specific Electron APIs. macOS uses
-  // vibrancy (needs transparent: true), Windows uses backgroundMaterial.
-  // Linux has no native equivalent. Blur only applies at window creation;
-  // changing the setting requires a restart.
+  // Why: blur uses platform APIs (macOS vibrancy+transparent, Windows backgroundMaterial, Linux none) and only applies at creation, needs restart.
   const platformBlurOptions = blur
     ? process.platform === 'darwin'
       ? { vibrancy: 'under-window' as const, transparent: true }
@@ -282,37 +243,21 @@ export function createMainWindow(
     minHeight: MIN_HEIGHT,
     title: opts?.title ?? 'Orca',
     show: false,
-    // Why: macOS swallows the app-activating click by default, so clicking
-    // back into Orca (e.g. the floating workspace) needed a second click.
-    // macOS-only option; Windows/Linux already deliver that click.
+    // Why: macOS swallows the app-activating click by default, so clicking back into Orca needed a second click (Windows/Linux already deliver it).
     acceptFirstMouse: true,
-    // Why: on macOS the menu lives in the system menu bar, so the in-window
-    // menu bar is irrelevant. On Windows/Linux we auto-hide so the menu bar
-    // doesn't consume a dedicated row of vertical space on every launch —
-    // users can still reveal the (properly restructured) File/Edit/View/
-    // Window/Help menus by pressing Alt, matching native Windows/Linux
-    // conventions (File Explorer, Firefox, etc.).
+    // Why: auto-hide the Windows/Linux menu bar to save a row (Alt reveals it); macOS uses the system menu bar anyway.
     autoHideMenuBar: true,
     backgroundColor: nativeTheme.shouldUseDarkColors ? '#0a0a0a' : '#ffffff',
-    // Why: on macOS 'hiddenInset' keeps the native traffic lights positioned
-    // inside our custom 42px titlebar. On Windows 'hidden' removes the default
-    // OS title bar (which would otherwise stack on top of our renderer titlebar
-    // and waste vertical space) while still allowing our renderer to draw its
-    // own drag region and window controls.
+    // Why: macOS 'hiddenInset' keeps native traffic lights in our custom titlebar; Windows 'hidden' removes the OS title bar so it doesn't double up.
     titleBarStyle:
       process.platform === 'darwin'
         ? 'hiddenInset'
         : process.platform === 'win32'
           ? 'hidden'
           : undefined,
-    // Why: Linux ignores titleBarStyle: 'hidden', so without this the native
-    // WM title bar stays and stacks on top of our renderer titlebar (double
-    // title bar). frame: false drops the native frame; the renderer draws its
-    // own titlebar + window controls (see WindowControls in App.tsx), matching
-    // the Windows custom-titlebar path.
+    // Why: Linux ignores titleBarStyle 'hidden'; frame:false drops the native frame so we don't get a double title bar (renderer draws its own).
     ...(process.platform === 'linux' ? { frame: false } : {}),
-    // Why: initial position for 1x zoom; syncTrafficLightPosition() adjusts
-    // dynamically when the user changes UI zoom.
+    // Why: initial position for 1x zoom; syncTrafficLightPosition() adjusts on zoom change.
     ...(process.platform === 'darwin'
       ? {
           trafficLightPosition: {
@@ -330,24 +275,16 @@ export function createMainWindow(
     }
   })
   const rendererWebContentsId = mainWindow.webContents.id
-  // Why: native paste fallback is privileged IPC; only the real top-level
-  // renderer should be allowed to request Electron's native paste operation.
+  // Why: native paste fallback is privileged IPC; only the top-level renderer may request it.
   setTrustedUIRendererWebContentsId(rendererWebContentsId)
 
   if (process.platform === 'darwin') {
-    // Why: browser-guest surfaces are kept alive by their own per-guest
-    // unthrottle (browser-manager attach), so the main window can throttle
-    // normally while hidden/occluded instead of rendering at full rate.
-    // Toggling must happen only while visible: flipping it on a hidden window
-    // desyncs Chromium's frame evictor and blanks the surface (electron#42378).
+    // Why: throttle the main window while hidden (guests self-unthrottle); toggle only while visible or Chromium blanks the surface (electron#42378).
     mainWindow.webContents.setBackgroundThrottling(true)
     installMacosVisibilityRepaint(mainWindow)
   }
 
-  // Why: a focus-preserving system/display wake fires no window focus or
-  // visibility events in the renderer, so terminal wake recovery would never
-  // run. Relay powerMonitor resume explicitly (supported on mac/win/linux)
-  // and force a repaint so stale compositor surfaces recover too.
+  // Why: a focus-preserving wake fires no focus/visibility events; relay resume so terminal wake recovery runs and force a repaint so stale compositor surfaces recover.
   const onSystemResume = (): void => {
     if (mainWindow.isDestroyed() || mainWindow.webContents.isDestroyed?.() === true) {
       return
@@ -360,25 +297,18 @@ export function createMainWindow(
   mainWindow.webContents.on('dom-ready', () => {
     const level = store?.getUI().uiZoomLevel ?? 0
     mainWindow.webContents.setZoomLevel(level)
-    // Why: the native traffic lights sit at a fixed position in the window
-    // while CSS content scales with zoom.  We must reposition the buttons
-    // on startup so they stay vertically aligned with the zoomed titlebar.
+    // Why: native traffic lights don't scale with CSS zoom; reposition on startup to stay aligned with the zoomed titlebar.
     if (process.platform === 'darwin') {
       syncTrafficLightPosition(mainWindow, Math.pow(1.2, level))
     }
   })
 
-  // Why: on macOS + Electron 41, creating a webview guest process can re-emit
-  // ready-to-show on the same BrowserWindow. Without a one-shot guard the
-  // handler re-runs maximize() from the persisted savedMaximized flag, snapping
-  // the window back to full-screen after the user already resized it (#591).
+  // Why: macOS+Electron 41 re-emits ready-to-show on webview-guest creation; a one-shot guard stops re-running maximize() after resize (#591).
   let handledInitialReadyToShow = false
   let initialRevealFallbackTimer: ReturnType<typeof setTimeout> | null =
     process.platform === 'win32' || process.platform === 'linux'
       ? setTimeout(() => {
-          // Why: GPU/driver failures on Windows and Linux/X11 can prevent
-          // ready-to-show forever, leaving the only app window hidden while the
-          // main process stays alive (#8421).
+          // Why: GPU/driver failures on Windows/Linux can prevent ready-to-show forever, hiding the only app window (#8421).
           initialRevealFallbackTimer = null
           revealInitialWindow()
         }, 10_000)
@@ -403,9 +333,7 @@ export function createMainWindow(
     handledInitialReadyToShow = true
     clearInitialRevealFallbackTimer()
 
-    // Why: in E2E headless mode, the window stays hidden to avoid stealing
-    // focus and screen real estate during test runs. Playwright interacts
-    // with the renderer via CDP, which works without a visible window.
+    // Why: in E2E headless mode keep the window hidden (Playwright drives via CDP) so tests don't steal focus.
     const e2eConfig = getMainE2EConfig()
     if (e2eConfig.headless) {
       return
@@ -417,17 +345,9 @@ export function createMainWindow(
   }
   mainWindow.on('ready-to-show', revealInitialWindow)
 
-  // Why: persist window bounds so the app restores to the user's last
-  // position/size instead of maximizing on every launch. Debounce to avoid
-  // hammering the persistence layer during continuous resize drags.
+  // Why: persist window bounds to restore last position/size; debounce to avoid hammering persistence during resize drags.
   let boundsTimer: ReturnType<typeof setTimeout> | null = null
-  // Why: once close has been initiated (user Cmd+Q, auto-updater relaunch,
-  // app.quit during quitAndInstall), Electron can still emit resize/move/
-  // unmaximize events while the OS tears the window down — persisting those
-  // intermediate, often near-minimum bounds would clobber the user's real
-  // last-used size and cause the next launch (especially post-update
-  // relaunch) to come up at minWidth × minHeight. Freeze persistence as soon
-  // as 'close' is observed.
+  // Why: teardown still emits resize/move/unmaximize at near-min bounds; freeze persistence once closing so they can't clobber the saved size.
   let windowClosing = false
   const saveBounds = (): void => {
     if (boundsTimer) {
@@ -438,25 +358,14 @@ export function createMainWindow(
       if (windowClosing || mainWindow.isDestroyed() || mainWindow.isFullScreen()) {
         return
       }
-      // Why: windowMaximized and windowBounds must be sampled and persisted
-      // atomically — writing windowMaximized first and then deciding whether
-      // to write bounds can leave the store with `windowMaximized: false`
-      // paired with stale/absent windowBounds if the near-min guard trips,
-      // which violates the pairing invariant subsequent launches rely on.
+      // Why: persist windowMaximized and windowBounds atomically; the near-min guard must not leave them a mismatched pair.
       const isMaximized = mainWindow.isMaximized()
       if (isMaximized) {
         store?.updateUI({ windowMaximized: true })
         return
       }
       const bounds = mainWindow.getBounds()
-      // Why: never persist shrink-to-min bounds. The user cannot want these
-      // saved — the window hit the enforced minimum, so either the teardown
-      // race from PR #1269 slipped past the freeze (e.g. dev-mode Ctrl+C
-      // where will-prevent-unload re-opens the freeze), or a transient
-      // OS resize fired. Dropping the bounds write here makes the next
-      // launch fall back to defaultBounds instead of resurrecting a tiny
-      // window. We still record windowMaximized: false so subsequent
-      // launches don't incorrectly restore maximized state.
+      // Why: never persist shrink-to-min bounds (teardown race past the freeze, PR #1269); fall back to defaultBounds next launch.
       if (bounds.width <= MIN_WIDTH || bounds.height <= MIN_HEIGHT) {
         console.warn('[window] Skipping persist of near-minimum windowBounds:', bounds)
         store?.updateUI({ windowMaximized: false })
@@ -468,12 +377,7 @@ export function createMainWindow(
   mainWindow.on('resize', saveBounds)
   mainWindow.on('move', saveBounds)
 
-  // Why: the auto-updater install path calls
-  // `win.removeAllListeners('close')` before quitting, so the per-window
-  // 'close' handler below never runs for update-triggered relaunches.
-  // Listen to app-level 'before-quit' as a second latch so resize/move
-  // events emitted during window teardown don't persist shrink-to-min
-  // bounds that would be restored on next launch.
+  // Why: the auto-updater calls removeAllListeners('close') before quitting, so latch on app 'before-quit' too to freeze bounds during teardown.
   const freezeBoundsOnQuit = (): void => {
     windowClosing = true
     if (boundsTimer) {
@@ -496,9 +400,7 @@ export function createMainWindow(
     }
     mainWindow.webContents.send('window:maximize-changed', false)
     const bounds = mainWindow.getBounds()
-    // Why: mirror the saveBounds guard — unmaximize during teardown can land
-    // at MIN_WIDTH × MIN_HEIGHT and we must not persist those as the user's
-    // remembered size.
+    // Why: mirror the saveBounds guard — unmaximize during teardown can land at min size; don't persist that as remembered size.
     if (bounds.width <= MIN_WIDTH || bounds.height <= MIN_HEIGHT) {
       console.warn('[window] Skipping unmaximize-time persist of near-min bounds:', bounds)
       store?.updateUI({ windowMaximized: false })
@@ -528,23 +430,14 @@ export function createMainWindow(
     const normalizedSrc = normalizeBrowserNavigationUrl(src)
     const partition = typeof webPreferences.partition === 'string' ? webPreferences.partition : ''
 
-    // Why: arbitrary sites must stay inside an unprivileged guest surface. We
-    // fail closed here so a renderer bug cannot smuggle preload, Node, or a
-    // non-browser partition into the guest and widen the app privilege boundary.
-    // The one allowed data URL is Orca's inert blank-tab bootstrap page; deny
-    // every other data URL so the renderer cannot inject arbitrary inline HTML.
-    // Why: session profiles use per-profile partitions (e.g.
-    // persist:orca-browser-session-<uuid>). The registry is the sole authority
-    // for which partitions are valid — renderer-provided strings that are not
-    // in the allowlist are rejected.
+    // Why: fail closed — deny any src or partition not in the registry allowlist so a renderer bug can't smuggle preload/Node into an unprivileged guest.
     if (!normalizedSrc || !browserSessionRegistry.isAllowedPartition(partition)) {
       event.preventDefault()
       return
     }
 
     delete webPreferences.preload
-    // Why: older Electron builds expose preloadURL alongside preload; delete
-    // both so the guest surface cannot inherit the main preload bridge.
+    // Why: older Electron builds expose preloadURL alongside preload; delete both so the guest can't inherit the main preload bridge.
     delete (webPreferences as Record<string, unknown>).preloadURL
     webPreferences.nodeIntegration = false
     webPreferences.nodeIntegrationInSubFrames = false
@@ -554,26 +447,18 @@ export function createMainWindow(
     webPreferences.allowRunningInsecureContent = false
     webPreferences.contextIsolation = true
     webPreferences.sandbox = true
-    // Why: keep renderer-created webviews aligned with the browser guest policy
-    // even if the host markup omits or misspells a preference.
+    // Why: force the browser guest policy even if host markup omits or misspells a preference.
     Object.assign(webPreferences, ORCA_BROWSER_GUEST_WEB_PREFERENCES)
-    // Why: preserve the registry-validated partition instead of forcing the
-    // legacy constant. This lets imported/isolated session profiles use their
-    // own cookie/storage partition while keeping all other hardening intact.
+    // Why: keep the registry-validated partition so isolated session profiles use their own storage while other hardening stays intact.
     webPreferences.partition = partition
   })
 
   mainWindow.webContents.on('did-attach-webview', (_event, guest) => {
-    // Why: popup and navigation policy must attach as soon as Chromium creates
-    // the guest webContents. Waiting until renderer-driven registration leaves
-    // a race where target=_blank or early redirects can bypass Orca's intended
-    // fallback behavior.
+    // Why: attach guest popup/nav policy at creation; waiting for renderer registration races target=_blank/early redirects past it.
     browserManager.attachGuestPolicies(guest)
   })
 
-  // Block ALL in-window navigations to prevent remote pages from inheriting
-  // the privileged preload bridge (PTY, filesystem, etc.).
-  // In dev mode, allow navigations to the local dev server (e.g. HMR reloads).
+  // Why: block in-window navigations so remote pages can't inherit the privileged preload bridge (dev server allowed for HMR).
   mainWindow.webContents.on('will-navigate', (event, url) => {
     const externalUrl = normalizeExternalBrowserUrl(url)
 
@@ -596,23 +481,14 @@ export function createMainWindow(
     event.preventDefault()
   })
 
-  // Why: mirrors the renderer's markdown-editor focus state so the main-process
-  // before-input-event handler can skip Cmd/Ctrl+B interception while TipTap
-  // owns focus. See docs/markdown-cmd-b-bold-design.md. We only carve out
-  // Cmd+B so browser guests and other editable surfaces keep the existing
-  // global shortcut behavior.
+  // Why: mirror markdown-editor focus so before-input-event skips Cmd/Ctrl+B while TipTap owns focus (docs/markdown-cmd-b-bold-design.md).
   let markdownEditorFocused = false
   let terminalInputFocused = false
   let floatingTerminalInputFocused = false
   let shortcutRecorderFocused = false
 
   const markdownFocusChannel = 'ui:setMarkdownEditorFocused'
-  // Why: coerce to strict boolean and verify the sender. A renderer bug or
-  // compromised IPC payload must not set the flag to a truthy non-bool (e.g.
-  // an object) and silently disable the sidebar toggle — default-deny on any
-  // non-bool. Additionally, only this main window's top-level webContents may
-  // mutate the flag, so a guest/webview or unrelated sender can't disable the
-  // Cmd+B sidebar carve-out.
+  // Why: strict-bool + sender check so a guest/webview or malformed IPC payload can't disable the Cmd+B sidebar carve-out.
   const onMarkdownEditorFocused = (event: Electron.IpcMainEvent, focused: unknown): void => {
     if (event.sender !== mainWindow.webContents) {
       return
@@ -621,8 +497,7 @@ export function createMainWindow(
   }
   ipcMain.on(markdownFocusChannel, onMarkdownEditorFocused)
   const terminalInputFocusChannel = 'ui:setTerminalInputFocused'
-  // Why: before-input-event resolves shortcuts before renderer keydown. Mirror
-  // regular xterm focus so Terminal-first can let shells/TUIs own app chords.
+  // Why: before-input-event resolves shortcuts before renderer keydown; mirror xterm focus so Terminal-first lets shells own app chords.
   const onTerminalInputFocused = (event: Electron.IpcMainEvent, focused: unknown): void => {
     if (event.sender !== mainWindow.webContents) {
       return
@@ -631,8 +506,7 @@ export function createMainWindow(
   }
   ipcMain.on(terminalInputFocusChannel, onTerminalInputFocused)
   const floatingTerminalInputFocusChannel = 'ui:setFloatingTerminalInputFocused'
-  // Why: main before-input-event runs before renderer keydown handlers. Mirror
-  // floating xterm focus so Ctrl+B/L and related shell chords can reach SSH/tmux.
+  // Why: before-input-event runs before renderer keydown; mirror floating xterm focus so Ctrl+B/L reach SSH/tmux.
   const onFloatingTerminalInputFocused = (event: Electron.IpcMainEvent, focused: unknown): void => {
     if (event.sender !== mainWindow.webContents) {
       return
@@ -641,8 +515,7 @@ export function createMainWindow(
   }
   ipcMain.on(floatingTerminalInputFocusChannel, onFloatingTerminalInputFocused)
   const shortcutRecorderFocusChannel = 'ui:setShortcutRecorderFocused'
-  // Why: the Settings recorder must receive existing app shortcuts so users can
-  // rebind them; before-input-event would otherwise consume the key first.
+  // Why: the Settings recorder must receive app shortcuts to rebind them; before-input-event would otherwise consume the key first.
   const onShortcutRecorderFocused = (event: Electron.IpcMainEvent, focused: unknown): void => {
     if (event.sender !== mainWindow.webContents) {
       return
@@ -656,16 +529,12 @@ export function createMainWindow(
     if (template.length === 0) {
       return
     }
-    // Why: right-click can produce a Chromium context-menu event before our
-    // renderer focus mirror updates, so trust Electron's editable/spellcheck
-    // params here instead of gating on markdownEditorFocused.
+    // Why: the context-menu event can precede our focus-mirror update; trust Electron's editable params, not markdownEditorFocused.
     Menu.buildFromTemplate(template).popup({ window: mainWindow, x: params.x, y: params.y })
   }
   mainWindow.webContents.on('context-menu', onMainContextMenu)
 
-  // Why: renderer can't mirror focus state across a crash/reload/close.
-  // Default-deny the carve-outs so focus context from a dead renderer cannot
-  // disable app shortcuts in a later lifecycle state.
+  // Why: a dead renderer can't clear its focus mirror; default-deny carve-outs so it can't disable app shortcuts in a later lifecycle.
   const resetMarkdownEditorFocus = (): void => {
     markdownEditorFocused = false
   }
@@ -680,10 +549,7 @@ export function createMainWindow(
   }
   let rendererProcessGone = false
   let rendererRecoveryTimer: ReturnType<typeof setTimeout> | null = null
-  // Why: stop a deterministic per-load renderer fault (bad GPU driver, corrupt
-  // chunk, AV interference) from auto-reloading every ~0.25-1.3s forever
-  // (Windows crash-loop clusters). The breaker opens after too many recoveries
-  // inside a rolling window and hands off to the host's recovery surface.
+  // Why: stop a deterministic per-load renderer fault from auto-reloading forever; breaker opens after too many recoveries in a rolling window.
   const rendererRecoveryCircuitBreaker = new RendererRecoveryCircuitBreaker({
     windowMs: DEFAULT_RENDERER_RECOVERY_WINDOW_MS,
     maxRecoveries: DEFAULT_RENDERER_RECOVERY_MAX_RECOVERIES
@@ -718,8 +584,7 @@ export function createMainWindow(
       }
       const recovery = rendererRecoveryCircuitBreaker.registerRecoveryAttempt(Date.now())
       if (!recovery.allowed) {
-        // Why: too many reloads in the window means reloading again will just
-        // crash again. Stop the loop and let the host surface a recovery prompt.
+        // Why: too many reloads means it will just crash again; stop and let the host surface a recovery prompt.
         opts?.onRendererRecoveryExhausted?.({
           details,
           webContentsId: rendererWebContentsId,
@@ -727,11 +592,8 @@ export function createMainWindow(
         })
         return
       }
-      // Why: a transient Network Service / renderer loss can leave Chromium
-      // showing a blank shell. Reload the app document once so the user gets
-      // back to a usable window instead of needing a full relaunch.
-      // Why: mark this one in-place reload so the did-finish-load orphan sweep
-      // spares live local PTYs until session restore re-attaches them (#5787).
+      // Why: a transient renderer/Network Service loss can blank Chromium; reload the app document once to recover.
+      // Why: mark this in-place reload so the did-finish-load orphan sweep spares live PTYs until session restore (#5787).
       opts?.onBeforeRecoveryReload?.(mainWindow.webContents.id)
       loadMainWindow(mainWindow)
     }, 250)
@@ -742,11 +604,9 @@ export function createMainWindow(
     resetTerminalInputFocus()
     resetFloatingTerminalInputFocus()
     resetShortcutRecorderFocus()
-    // Why: macOS can report BrowserWindow teardown as renderer `killed`/SIGKILL
-    // after a confirmed close; that is window lifecycle noise, not a crash.
+    // Why: macOS reports BrowserWindow teardown as renderer killed/SIGKILL after close — window noise, not a crash.
     if (!windowClosing) {
-      // Why: the recorder owns crash classification and durable suppression
-      // diagnostics; filtering here made expected-teardown evidence unreachable.
+      // Why: the recorder owns crash classification; filtering here made expected-teardown evidence unreachable.
       opts?.onRendererProcessGone?.(details, rendererWebContentsId)
     }
     if (!windowClosing) {
@@ -775,12 +635,10 @@ export function createMainWindow(
 
   const doubleTapDetector = new ModifierDoubleTapDetector()
 
-  // Why: one place maps a resolved window-shortcut action to its IPC/side effect,
-  // reused by the normal keydown path and the double-tap path so they cannot drift.
+  // Why: one mapping of action → IPC/side effect, shared by the keydown and double-tap paths so they can't drift.
   const sendResolvedWindowShortcutAction = (action: WindowShortcutAction): void => {
     switch (action.type) {
-      // The renderer's DictationController re-checks enabled/sttModel and ignores
-      // hold mode, so this path needs no voice guards.
+      // The renderer's DictationController re-checks enabled/sttModel and ignores hold mode, so this path needs no voice guards.
       case 'dictationKeyDown':
         mainWindow.webContents.send('ui:dictationKeyDown')
         return
@@ -861,8 +719,7 @@ export function createMainWindow(
         ? getWindowShortcutActionId(action)
         : null
 
-    // Why: hold-mode dictation needs renderer keyup events, so the main process
-    // may only consume shortcuts that toggle dictation from a single keydown.
+    // Why: hold-mode dictation needs renderer keyup events, so main only consumes single-keydown dictation toggles.
     if (action.type === 'dictationKeyDown') {
       const voiceSettings = store?.getSettings().voice
       if (!voiceSettings?.enabled || !voiceSettings.sttModel) {
@@ -918,8 +775,7 @@ export function createMainWindow(
     }
 
     if (isMacAppPasteInput(input)) {
-      // Why: native chat/terminal panes can own focus without being native
-      // editable controls, so route Cmd+V through Orca's paste ownership first.
+      // Why: chat/terminal panes hold focus without native editable controls, so route Cmd+V through Orca's paste ownership.
       event.preventDefault()
       mainWindow.webContents.send('ui:appMenuPaste')
       return
@@ -937,8 +793,7 @@ export function createMainWindow(
       terminalShortcutPolicy: terminalShortcutContext.terminalShortcutPolicy
     }
 
-    // Why: detect double-tap-modifier gestures on the raw key stream. A bare
-    // modifier emits no terminal bytes, so this never steals readline input.
+    // Why: bare modifiers emit no terminal bytes, so double-tap detection on the raw key stream never steals readline input.
     if (input.type === 'keyDown' || input.type === 'keyUp') {
       const detected = doubleTapDetector.process(
         toModifierDoubleTapEvent({
@@ -967,13 +822,10 @@ export function createMainWindow(
             focusedShortcutContext: terminalShortcutContext
           })
         ) {
-          // Only preventDefault the emitting keydown — never the first tap's
-          // down/up. This suppresses the renderer DOM keydown so the renderer
-          // detector cannot also fire for the same gesture.
+          // preventDefault only the emitting keydown so the renderer detector can't also fire for the same gesture.
           return
         }
-        // No allowlisted action: let the keydown reach the renderer, whose
-        // detector completes and dispatches inline.
+        // No allowlisted action: let the keydown reach the renderer, whose detector completes and dispatches inline.
       }
     }
 
@@ -981,15 +833,11 @@ export function createMainWindow(
       input.type === 'keyDown' &&
       matchesRecentTabSwitcherChord(input, process.platform, keybindings, terminalShortcutContext)
     ) {
-      // Why: the held switcher commits on modifier keyup. If main prevents the
-      // keydown, Electron can suppress the renderer keyup and strand the overlay.
+      // Why: the held switcher commits on modifier keyup; preventing the keydown here can suppress the keyup and strand the overlay.
       return
     }
 
-    // Why: TipTap owns bare Cmd/Ctrl+B for bold while the markdown editor is
-    // focused — skip interception so its keymap runs. Scoped to the bare chord
-    // (no Shift/Alt): any extra modifier signals different intent and must
-    // still resolve through the policy allowlist.
+    // Why: TipTap owns bare Cmd/Ctrl+B for bold in the markdown editor; skip interception for the bare chord only.
     // See docs/markdown-cmd-b-bold-design.md.
     const modForBold = process.platform === 'darwin' ? input.meta : input.control
     if (
@@ -1002,9 +850,7 @@ export function createMainWindow(
       return
     }
 
-    // Why: keep the main-process interception surface as an explicit allowlist.
-    // Anything outside this helper must continue to the renderer/PTTY so
-    // readline control chords are not silently stolen above the terminal.
+    // Why: keep interception an explicit allowlist so readline control chords reach the PTY instead of being silently stolen.
     const action = resolveWindowShortcutAction(
       input,
       process.platform,
@@ -1025,14 +871,11 @@ export function createMainWindow(
     })
   })
 
-  // Why: a mid-gesture focus loss must not leave the detector armed so the next
-  // unrelated modifier press completes a phantom double-tap.
+  // Why: mid-gesture focus loss must not leave the detector armed, or the next modifier press completes a phantom double-tap.
   mainWindow.on('blur', () => doubleTapDetector.reset())
 
   mainWindow.webContents.on('zoom-changed', (event, zoomDirection) => {
-    // Why: Some keyboard layouts/platforms consume Ctrl/Cmd+Minus before
-    // before-input-event fires, but still emit Electron's zoom command. Keep
-    // that fallback only while the matching zoom action is still bound.
+    // Why: some layouts fire Electron's zoom command without before-input-event; honor it only while the zoom action is still bound.
     if (zoomDirection !== 'in' && zoomDirection !== 'out') {
       return
     }
@@ -1055,17 +898,11 @@ export function createMainWindow(
     mainWindow.webContents.send('terminal:zoom', zoomDirection)
   })
 
-  // Intercept window close so the renderer can show a confirmation dialog
-  // when terminals with running processes would be killed. The renderer
-  // replies with 'window:confirm-close' to proceed, or does nothing to cancel.
+  // Intercept close so the renderer can confirm killing running-process terminals (replies window:confirm-close to proceed).
   let windowCloseConfirmed = false
   const confirmCloseChannel = 'window:confirm-close'
 
-  // Why: Windows minimize-to-tray. Hides the window instead of closing when the
-  // setting is on, this isn't a real quit (Ctrl+Q / tray "Quit" set
-  // getIsQuitting), and the renderer is alive. Returns true when it handled the
-  // close by hiding, so callers skip their normal close path. Shared by BOTH the
-  // renderer-drawn X (window:request-close) and the native close event (Alt+F4).
+  // Windows minimize-to-tray: hide instead of close when enabled; returns true when it hid so callers skip their close path.
   const hideToTrayIfEnabled = (): boolean => {
     const isRendererCrashed = mainWindow.webContents.isCrashed?.() ?? false
     if (
@@ -1078,8 +915,7 @@ export function createMainWindow(
       return false
     }
     mainWindow.hide()
-    // Why: tell the user once that closing only hid the window; the persisted
-    // flag stops the notice from repeating on every later minimize.
+    // Why: notify once that closing only hid the window; the persisted flag stops it repeating on every later minimize.
     if (store.getUI().trayMinimizeNoticeShown !== true) {
       try {
         new Notification({
@@ -1098,35 +934,25 @@ export function createMainWindow(
   }
 
   mainWindow.on('close', (e) => {
-    // Why: Alt+F4 and programmatic closes reach the native event; apply the same
-    // minimize-to-tray guard the renderer-drawn X uses via onRequestClose.
+    // Why: Alt+F4/programmatic closes hit the native event; apply the same minimize-to-tray guard the renderer-drawn X uses.
     if (!windowCloseConfirmed && hideToTrayIfEnabled()) {
       e.preventDefault()
       return
     }
     const isRendererCrashed = mainWindow.webContents.isCrashed?.() ?? false
-    // Why: a hung-but-ALIVE renderer (neither gone nor crashed) must still hit
-    // the renderer's save/running-process confirmation; only a genuinely gone or
-    // crashed renderer — which cannot answer window:close-requested — may bypass
-    // it. Routing this through the pure decision locks that invariant (#5787).
+    // Why: only a gone/crashed renderer (can't answer) may bypass close confirmation; a hung-but-alive one still must (#5787).
     const closeAction = resolveWindowCloseAction({
       windowCloseConfirmed,
       rendererProcessGone,
       isRendererCrashed
     })
     if (closeAction !== 'request-confirmation') {
-      // allow-confirmed: the renderer already replied and re-entered close().
-      // bypass-gone: after a native renderer crash the renderer cannot answer
-      // window:close-requested, so let Cmd+Q / OS close complete instead of
-      // trapping the user in a blank, unquittable window.
+      // allow-confirmed: renderer already replied and re-entered close().
+      // bypass-gone: a gone renderer can't answer window:close-requested, so let OS close complete rather than trap a blank window.
       if (closeAction === 'allow-confirmed') {
         windowCloseConfirmed = false
       }
-      // Why: past this point Electron/OS may emit resize/move/unmaximize as
-      // the window is destroyed. Freeze bounds persistence so those
-      // teardown events can't clobber the user's saved window size — which
-      // would otherwise make the post-update relaunch come up at minWidth ×
-      // minHeight (issue surfaced in v1.3.26-rc2).
+      // Why: window teardown emits resize/move/unmaximize; freeze bounds persistence so they can't clobber saved size (v1.3.26-rc2).
       windowClosing = true
       if (boundsTimer) {
         clearTimeout(boundsTimer)
@@ -1135,17 +961,13 @@ export function createMainWindow(
       return
     }
     e.preventDefault()
-    // Why: the renderer owns the close decision (dirty-file save dialogs,
-    // running-process confirmation). The subscription lives at the always-
-    // mounted App root, so even pre-workspace states reply — see #5144.
+    // Why: renderer owns the close decision; the always-mounted App root subscription lets even pre-workspace states reply (#5144).
     mainWindow.webContents.send('window:close-requested', {
       isQuitting: opts?.getIsQuitting?.() ?? false
     })
   })
   mainWindow.webContents.on('will-prevent-unload', () => {
-    // Why: a prevented beforeunload cancels the in-flight quit. Release the
-    // bounds-persistence freeze so a user who keeps using the window after
-    // aborting Cmd+Q still gets their size saved.
+    // Why: a prevented beforeunload cancels the quit; release the bounds-persistence freeze so later resizing still saves.
     windowClosing = false
     opts?.onQuitAborted?.()
     mainWindow.webContents.send('window:unload-prevented')
@@ -1163,8 +985,7 @@ export function createMainWindow(
   }
   ipcMain.on(trafficLightChannel, onSyncTrafficLights)
 
-  // Why: renderer-drawn window controls on Windows/Linux desktop send these to
-  // replicate the native title bar buttons hidden by custom chrome.
+  // Why: renderer-drawn window controls on Windows/Linux replicate the native title-bar buttons hidden by custom chrome.
   const minimizeChannel = 'window:minimize'
   const onMinimize = (): void => {
     if (!mainWindow.isDestroyed()) {
@@ -1182,39 +1003,24 @@ export function createMainWindow(
       mainWindow.maximize()
     }
   }
-  // Why: send window:close-requested directly rather than calling
-  // mainWindow.close() and letting the 'close' event re-send it. Calling
-  // mainWindow.close() from within an IPC message handler on Windows can cause
-  // the 'close' event to misfire (e.preventDefault() doesn't suppress the OS
-  // close in all Windows configurations). Going straight to the renderer's
-  // close guard (Terminal.tsx onWindowCloseRequested) keeps the flow identical
-  // to what happens when confirmWindowClose() ultimately calls mainWindow.close()
-  // with windowCloseConfirmed = true.
+  // Why: mainWindow.close() from an IPC handler on Windows can make 'close' misfire, so send window:close-requested directly.
   const requestCloseChannel = 'window:request-close'
   const onRequestClose = (): void => {
     if (mainWindow.isDestroyed()) {
       return
     }
-    // Why: the renderer-drawn X on Windows routes here (not the native close
-    // event), so the minimize-to-tray guard must run on this path too — hide
-    // instead of asking the renderer to close.
+    // Why: renderer-drawn X routes here (not the native close event), so the minimize-to-tray guard must also run here.
     if (hideToTrayIfEnabled()) {
       return
     }
     mainWindow.webContents.send('window:close-requested', { isQuitting: false })
   }
-  // Why: the ··· button in the renderer-drawn title bar on Windows/Linux
-  // desktop pops up the application menu at the cursor position, replicating
-  // the Alt-key reveal that autoHideMenuBar normally provides.
+  // Why: renderer-drawn title-bar ··· menu button replicates the Alt-key reveal autoHideMenuBar provides (Windows/Linux).
   const popupMenuChannel = 'menu:popup'
   const onPopupMenu = (): void => {
     Menu.getApplicationMenu()?.popup({ window: mainWindow })
   }
-  // Why: the renderer's WindowControls mounts after ready-to-show, which is
-  // also when savedMaximized is restored — so window:maximize-changed has
-  // already fired (or not fired, if maximize() was called pre-mount) before
-  // the listener attaches. Expose a synchronous getter so the button can
-  // initialize its icon to match the current state on mount.
+  // Why: WindowControls mounts after window:maximize-changed already fired, so expose a synchronous getter to init its icon.
   const isMaximizedChannel = 'window:isMaximized'
   const onIsMaximized = (): boolean => {
     return !mainWindow.isDestroyed() && mainWindow.isMaximized()
@@ -1228,9 +1034,7 @@ export function createMainWindow(
   ipcMain.on(confirmCloseChannel, onConfirmClose)
   mainWindow.on('closed', () => {
     clearInitialRevealFallbackTimer()
-    // Why: default-deny the Cmd+B carve-out after the window is gone so a
-    // stale-true flag can't leak past subsequent state transitions. Paired
-    // with the webContents lifecycle resets above.
+    // Why: default-deny the Cmd+B carve-out after the window is gone so a stale-true flag can't leak into later state.
     markdownEditorFocused = false
     terminalInputFocused = false
     floatingTerminalInputFocused = false
@@ -1248,14 +1052,10 @@ export function createMainWindow(
     ipcMain.removeListener(terminalInputFocusChannel, onTerminalInputFocused)
     ipcMain.removeListener(floatingTerminalInputFocusChannel, onFloatingTerminalInputFocused)
     ipcMain.removeListener(shortcutRecorderFocusChannel, onShortcutRecorderFocused)
-    // Why: powerMonitor is app-global; without this the closed window's
-    // resume relay would leak and fire against a destroyed webContents.
+    // Why: powerMonitor is app-global; without this the resume relay leaks and fires against a destroyed webContents.
     powerMonitor.removeListener('resume', onSystemResume)
     clearTrustedUIRendererWebContentsId(rendererWebContentsId)
-    // Why: on updater-triggered shutdown, BrowserWindow can emit `closed`
-    // after its webContents has already been destroyed. The destroyed
-    // webContents owns its listeners, so do not touch `mainWindow.webContents`
-    // here or the quit path can crash before Squirrel.Mac relaunches Orca.
+    // Why: on updater shutdown 'closed' can fire after webContents is destroyed, so don't touch mainWindow.webContents here.
     app.removeListener('before-quit', freezeBoundsOnQuit)
   })
 

From 190de8223e21c3700c2b28b13260de52460999a8 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Mon, 20 Jul 2026 03:18:28 -0700
Subject: [PATCH 49/54] =?UTF-8?q?refactor(comments):=20slim=20verbose=20co?=
 =?UTF-8?q?mments=20in=20main=20integrations=20(git/providers/=E2=80=A6)?=
 =?UTF-8?q?=20(#9543)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Collapse multi-line explanatory comment blocks into single-line "why" statements
per AGENTS.md ("Document the Why, Briefly"): drop restatements of the code and
mechanism narration; keep the non-obvious reason, external refs, and directives.

Comments-only — verified no code changed via a Babel/esbuild comment-strip
token-equality gate against origin/main; typecheck and oxlint clean.

Area: main — git, source-control, providers & integrations. 40 files changed, 1432 insertions(+), 4473 deletions(-).

Co-authored-by: Orca <help@stably.ai>
---
 src/main/browser/agent-browser-bridge.ts      | 240 ++++--------
 src/main/browser/browser-cookie-import.ts     | 160 +++-----
 src/main/browser/browser-guest-ui.ts          | 123 ++-----
 src/main/browser/browser-manager.ts           | 342 +++++-------------
 src/main/browser/browser-session-registry.ts  | 112 ++----
 src/main/browser/cdp-bridge.ts                | 161 +++------
 src/main/browser/grab-guest-script.ts         |  44 +--
 .../claude-accounts/runtime-auth-service.ts   | 103 ++----
 src/main/claude/hook-service.ts               |  79 +---
 src/main/cli/cli-installer.ts                 |  94 ++---
 .../codex-accounts/runtime-home-service.ts    | 138 ++-----
 src/main/codex-accounts/service.ts            |  80 +---
 src/main/codex/config-settings-promotion.ts   |  77 ++--
 src/main/codex/config-toml-trust.test.ts      | 133 ++-----
 src/main/codex/config-toml-trust.ts           | 151 ++------
 src/main/codex/hook-service.ts                | 220 +++--------
 src/main/cursor/hook-service.ts               |  85 +----
 src/main/devin/hook-service.ts                |  71 +---
 src/main/gemini/hook-service.ts               |  70 +---
 src/main/git/repo.test.ts                     |  49 +--
 src/main/git/repo.ts                          | 245 +++----------
 src/main/git/runner.ts                        | 314 ++++------------
 src/main/git/status.ts                        | 254 ++++---------
 src/main/git/worktree.ts                      | 244 ++++---------
 src/main/github/client.ts                     | 341 +++++------------
 src/main/github/pr-refresh-coordinator.ts     | 114 ++----
 src/main/github/project-view.ts               | 138 ++-----
 src/main/github/rate-limit.ts                 |  76 +---
 src/main/github/work-item-details.ts          | 136 ++-----
 src/main/gitlab/client.ts                     | 157 ++------
 src/main/opencode/hook-service.test.ts        | 100 ++---
 src/main/opencode/hook-service.ts             | 123 +------
 src/main/ports/advertised-url-watcher.ts      | 125 ++-----
 .../source-control/hosted-review-creation.ts  |  80 +---
 src/main/speech/model-manager.ts              |  96 ++---
 src/main/ssh/ssh-connection.ts                | 129 ++-----
 src/main/ssh/ssh-relay-deploy.ts              | 241 +++---------
 .../ssh/ssh-relay-native-deps-install.test.ts | 130 ++-----
 src/main/ssh/ssh-relay-session.ts             | 240 +++---------
 src/main/ssh/ssh-relay-versioned-install.ts   |  90 ++---
 40 files changed, 1432 insertions(+), 4473 deletions(-)

diff --git a/src/main/browser/agent-browser-bridge.ts b/src/main/browser/agent-browser-bridge.ts
index 0bec7bf68fa..0ce3b7f1342 100644
--- a/src/main/browser/agent-browser-bridge.ts
+++ b/src/main/browser/agent-browser-bridge.ts
@@ -50,9 +50,7 @@ import type {
 import { assertClipboardTextWriteWithinLimitWithYield } from '../../shared/clipboard-text'
 import { iterateBrowserTextInsertionChunks } from './browser-text-insertion'
 
-// Why: must exceed agent-browser's internal per-command timeouts (goto defaults to 30s,
-// wait can be up to 60s). Using 90s ensures the bridge never kills a command before
-// agent-browser's own timeout fires and returns a proper error.
+// Why: must exceed agent-browser's internal timeouts (goto 30s, wait 60s) so the bridge never kills a command before its own timeout fires.
 const EXEC_TIMEOUT_MS = 90_000
 const CONSECUTIVE_TIMEOUT_LIMIT = 3
 const WAIT_PROCESS_TIMEOUT_GRACE_MS = 1_000
@@ -68,8 +66,7 @@ type SessionState = {
   // Why: track active interception patterns so they can be re-enabled after session restart
   activeInterceptPatterns: string[]
   activeCapture: boolean
-  // Why: store the webContentsId so we can verify the tab is still alive at execution time,
-  // not just at enqueue time. The queue delay can allow the tab to be destroyed in between.
+  // Why: verify the tab is alive at execution time, not just enqueue time — queue delay can destroy it in between.
   webContentsId: number
   activeProcess: ChildProcess | null
 }
@@ -118,8 +115,7 @@ function focusedValueSetExpression(
   ].join('')
 }
 
-// Why: rich editors reconcile only browser editing transactions; direct DOM
-// fallback can look correct while leaving their model stale.
+// Why: rich editors reconcile only real browser edit transactions; a direct-DOM fallback can leave their model stale.
 function focusedRichTextEditExpression(
   valueExpression: string,
   options?: { selectAll?: boolean }
@@ -166,8 +162,7 @@ type AgentBrowserExecOptions = {
 type EnqueueTargetedCommandOptions = {
   ensureSession?: boolean
   ensureVisible?: boolean
-  // Why: text-mutating commands must never fall back to the global active tab,
-  // which can point at a different worktree the user is currently viewing.
+  // Why: text-mutating commands must never fall back to the global tab (may be a worktree the user is viewing).
   requireScopedTarget?: boolean
 }
 
@@ -181,10 +176,7 @@ function agentBrowserNativeName(): string {
 }
 
 function resolveAgentBrowserBinary(): string {
-  // Why: production builds copy the platform-specific binary into resources/
-  // via electron-builder extraResources. Use Electron's resolved resourcesPath
-  // instead of hand-rolling ../resources so packaged macOS builds keep working
-  // on case-sensitive filesystems where Contents/Resources casing matters.
+  // Why: use Electron's resourcesPath (not hand-rolled ../resources) so packaged macOS case-sensitive builds resolve the binary.
   const bundledResourcesPath =
     process.resourcesPath ??
     (process.platform === 'darwin'
@@ -195,9 +187,7 @@ function resolveAgentBrowserBinary(): string {
     return bundled
   }
 
-  // Why: in dev mode, resolve directly to the native binary inside node_modules.
-  // Use app.getAppPath() for a stable project root — __dirname is unreliable after
-  // electron-vite bundles main process code into out/main/index.js.
+  // Why: dev mode — resolve from node_modules via app.getAppPath(); __dirname is unreliable after electron-vite bundling.
   const nmBin = join(
     app.getAppPath(),
     'node_modules',
@@ -220,9 +210,7 @@ function resolveAgentBrowserBinary(): string {
   return 'agent-browser'
 }
 
-// Why: exec commands arrive as a single string (e.g. 'keyboard inserttext "hello world"').
-// Naive split on whitespace breaks quoted arguments. This parser respects double and
-// single quotes so the value arrives as a single argument without surrounding quotes.
+// Why: exec commands arrive as one string; split on whitespace but respect quotes so quoted args stay intact.
 function parseShellArgs(input: string): string[] {
   const args: string[] = []
   let current = ''
@@ -266,8 +254,7 @@ function stripAgentBrowserTargetArgs(args: string[]): string[] {
   return stripped
 }
 
-// Why: agent-browser returns generic error messages for stale/unknown refs.
-// Map them to a specific code so agents can reliably detect and re-snapshot.
+// Why: agent-browser returns generic errors for stale/unknown refs; map to a specific code so agents can detect and re-snapshot.
 function classifyErrorCode(message: string): string {
   if (/unknown ref|ref not found|element not found: @e/i.test(message)) {
     return 'browser_stale_ref'
@@ -511,29 +498,20 @@ function translateResult(
 }
 
 export class AgentBrowserBridge {
-  // Why: per-worktree active tab prevents one worktree's tab switch from
-  // affecting another worktree's command targeting.
+  // Why: per-worktree active tab so one worktree's tab switch can't affect another's command targeting.
   private readonly activeWebContentsPerWorktree = new Map<string, number>()
   private activeWebContentsId: number | null = null
   private readonly sessions = new Map<string, SessionState>()
   private readonly commandQueues = new Map<string, QueuedCommand[]>()
   private readonly processingQueues = new Set<string>()
-  // Why: screenshot prep temporarily changes shared renderer paintability state.
-  // Per-session queues only serialize commands within one browser tab, so
-  // concurrent screenshots on different tabs can otherwise interleave hidden
-  // surface leases and blank each other's capture.
+  // Why: screenshot prep mutates shared paintability across tabs; serialize globally so concurrent captures don't blank each other.
   private screenshotTurn: Promise<void> = Promise.resolve()
   private readonly agentBrowserBin: string
-  // Why: when a process swap destroys a session that had active intercept patterns,
-  // store them here keyed by sessionName so the next ensureSession + first successful
-  // command can restore them automatically.
+  // Why: stash intercept patterns from a swap-destroyed session, keyed by name, so the next session restores them.
   private readonly pendingInterceptRestore = new Map<string, string[]>()
-  // Why: two concurrent CLI calls can both enter ensureSession before either creates
-  // the session entry. This promise-based lock ensures only one creation proceeds.
+  // Why: promise-lock so two concurrent ensureSession calls don't both create the session entry.
   private readonly pendingSessionCreation = new Map<string, Promise<void>>()
-  // Why: session destruction shells out to `agent-browser close`, which is async
-  // and keyed by session name. Recreating the same session before that close
-  // finishes can let the old teardown close the new daemon session.
+  // Why: `agent-browser close` is async, keyed by session name — recreating before it finishes lets the old teardown close the new session.
   private readonly pendingSessionDestruction = new Map<string, Promise<void>>()
   private readonly cancelledProcesses = new WeakSet<ChildProcess>()
 
@@ -634,14 +612,12 @@ export class AgentBrowserBridge {
     newWebContentsId: number,
     previousWebContentsId?: number
   ): Promise<void> {
-    // Why: Electron process swaps give same browserPageId but new webContentsId.
-    // Old proxy's webContents is destroyed, so destroy session and let next command recreate.
+    // Why: an Electron process swap keeps browserPageId but gives a new webContentsId — destroy the session so the next command recreates it.
     const sessionName = `orca-tab-${browserPageId}`
     const session = this.sessions.get(sessionName)
     const oldWebContentsId = previousWebContentsId ?? session?.webContentsId
     const owningWorktreeId = this.browserManager.getWorktreeIdForTab(browserPageId)
-    // Why: save active intercept patterns before destroying so they can be restored
-    // on the new session after the next successful init command.
+    // Why: save intercept patterns before destroy so the new session can restore them after init.
     if (session && session.activeInterceptPatterns.length > 0) {
       this.pendingInterceptRestore.set(sessionName, [...session.activeInterceptPatterns])
     }
@@ -680,10 +656,7 @@ export class AgentBrowserBridge {
 
   tabList(worktreeId?: string): BrowserTabListResult {
     const tabs = this.getRegisteredTabs(worktreeId)
-    // Why: use per-worktree active tab for the "active" flag so tab-list is
-    // consistent with what resolveActiveTab would pick for command routing.
-    // Keep this read-only though: discovery commands must not mutate the
-    // active-tab state that later bare commands rely on.
+    // Why: use the per-worktree active tab so listing matches command routing, but read-only — discovery must not mutate active-tab state.
     let activeWcId =
       (worktreeId && this.activeWebContentsPerWorktree.get(worktreeId)) ?? this.activeWebContentsId
     const result: BrowserTabInfo[] = []
@@ -703,8 +676,7 @@ export class AgentBrowserBridge {
       result.push({
         browserPageId: tabId,
         index: index++,
-        // Why: failed WebContents report chrome-error://, which is neither
-        // actionable nor the address the user asked to load.
+        // Why: failed WebContents report chrome-error://, not the address the user asked to load.
         url: loadError?.validatedUrl ?? wc.getURL() ?? '',
         title: wc.getTitle() ?? '',
         active: wcId === activeWcId,
@@ -712,10 +684,7 @@ export class AgentBrowserBridge {
         certificateFailure
       })
     }
-    // Why: if no tab has been explicitly activated yet, surface the first live
-    // tab as active in the listing without mutating bridge state. That keeps
-    // `tab list` side-effect free while still showing users which tab a bare
-    // command would select next.
+    // Why: with no active tab yet, show the first live tab as active without mutating state — keeps `tab list` side-effect free.
     if (activeWcId == null && firstLiveWcId !== null) {
       activeWcId = firstLiveWcId
       if (result.length > 0) {
@@ -725,8 +694,7 @@ export class AgentBrowserBridge {
     return { tabs: result }
   }
 
-  // Why: tab switch must go through the command queue to prevent race conditions
-  // with in-flight commands that target the previously active tab.
+  // Why: route tab switch through the command queue so it can't race in-flight commands targeting the old tab.
   async tabSwitch(
     index: number | undefined,
     worktreeId?: string,
@@ -734,9 +702,7 @@ export class AgentBrowserBridge {
   ): Promise<BrowserTabSwitchResult> {
     return this.enqueueCommand(worktreeId, async () => {
       const tabs = this.getRegisteredTabs(worktreeId)
-      // Why: queue delay means the tab list can change between RPC arrival and
-      // execution time. Recompute against live webContents here so we never
-      // activate a tab index that disappeared while earlier commands were running.
+      // Why: queue delay can change the tab list before execution — recompute against live webContents so no vanished index is activated.
       const liveEntries = [...tabs.entries()].filter(([, wcId]) => this.getWebContents(wcId))
       let switchedIndex = index ?? -1
       let resolvedPageId = browserPageId
@@ -753,14 +719,9 @@ export class AgentBrowserBridge {
       }
       const [tabId, wcId] = liveEntries[switchedIndex]
       this.activeWebContentsId = wcId
-      // Why: resolveActiveTab prefers the per-worktree map over the global when
-      // worktreeId is provided. Without this update, subsequent commands would
-      // still route to the previous tab despite tabSwitch reporting success.
+      // Why: resolveActiveTab prefers the per-worktree map, so update it or later commands keep routing to the old tab.
       const owningWorktreeId = worktreeId ?? this.browserManager.getWorktreeIdForTab(tabId)
-      // Why: `tab switch --page <id>` may omit --worktree because the page id is
-      // already a stable target. We still need to update the owning worktree's
-      // active-tab slot so later worktree-scoped commands follow the tab that was
-      // just activated instead of the previously active one.
+      // Why: `tab switch --page` may omit --worktree, so still update the owning worktree's active slot for later scoped commands.
       if (owningWorktreeId) {
         this.activeWebContentsPerWorktree.set(owningWorktreeId, wcId)
       }
@@ -817,8 +778,7 @@ export class AgentBrowserBridge {
     browserPageId?: string
   ): Promise<BrowserFillResult> {
     await assertClipboardTextWriteWithinLimitWithYield(value)
-    // Why: agent-browser's CDP text insertion loses focus in Electron guests.
-    // Resolve the ref first, then edit through the browser's input pipeline.
+    // Why: agent-browser's CDP text insertion loses focus in Electron guests; edit through the browser's input pipeline instead.
     return this.enqueueTargetedCommand(
       worktreeId,
       browserPageId,
@@ -1016,15 +976,11 @@ export class AgentBrowserBridge {
           wc.focus()
           const point =
             cdpButton === 'left'
-              ? // Why: DOM activation cannot carry Cmd/Ctrl/Alt/Shift, so modifier
-                // clicks use only the adjusted point and let CDP dispatch the event.
+              ? // Why: DOM activation can't carry Cmd/Ctrl/Alt/Shift, so modifier clicks use the adjusted point and let CDP dispatch the event.
                 await resolveMobileTouchClickPoint(wc.debugger, x, y, radius, cdpModifiers === 0)
               : { x, y, adjusted: false, handled: false }
-          // Why: mobile taps should land as one atomic input operation. Sending
-          // move/down/up through separate CLI calls visibly hovers targets and can
-          // miss small controls before the click lands.
-          // Runtime may already activate DOM controls because mobile-emulated
-          // BrowserViews can ignore CDP mouse clicks for regular page taps.
+          // Why: land the tap as one atomic op — separate move/down/up CLI calls visibly hover and can miss small controls.
+          // Why: mobile-emulated BrowserViews can ignore CDP mouse clicks, so the runtime may already have activated DOM controls.
           if (!point.handled) {
             await wc.debugger.sendCommand('Input.dispatchMouseEvent', {
               type: 'mousePressed',
@@ -1292,10 +1248,7 @@ export class AgentBrowserBridge {
   }
 
   async reload(worktreeId?: string, browserPageId?: string): Promise<BrowserReloadResult> {
-    // Why: reload can trigger a process swap in Electron (site-isolation), which
-    // destroys the session mid-command. Use the webContents directly for reload
-    // instead of going through agent-browser to avoid the session lifecycle issue.
-    // Routed through enqueueCommand so it serializes with other in-flight commands.
+    // Why: reload can trigger an Electron process swap that destroys the session mid-command — reload via webContents directly instead.
     return this.enqueueTargetedCommand(worktreeId, browserPageId, async (_sessionName, target) => {
       const wc = this.getWebContents(target.webContentsId)
       if (!wc) {
@@ -1324,8 +1277,7 @@ export class AgentBrowserBridge {
 
         wc.on('did-finish-load', onFinish)
         wc.on('did-fail-load', onFail)
-        // Why: successful reloads must clear the fallback timer; otherwise each
-        // reload retains the webContents and listeners until the 10s timeout fires.
+        // Why: clear the fallback timer on load; otherwise each reload leaks the webContents + listeners until the 10s timeout.
         fallbackTimer = setTimeout(finish, 10_000)
         if (typeof fallbackTimer.unref === 'function') {
           fallbackTimer.unref()
@@ -1340,8 +1292,7 @@ export class AgentBrowserBridge {
     worktreeId?: string,
     browserPageId?: string
   ): Promise<BrowserScreenshotResult> {
-    // Why: agent-browser writes the screenshot to a temp file and returns
-    // { "path": "/tmp/screenshot-xxx.png" }. We read the file and return base64.
+    // Why: agent-browser writes the screenshot to a temp file and returns its path; read it and return base64.
     return this.enqueueTargetedCommand(
       worktreeId,
       browserPageId,
@@ -1396,10 +1347,7 @@ export class AgentBrowserBridge {
         ? await this.browserManager.acquireAutomationVisibility(session.webContentsId)
         : () => {}
       try {
-        // Why: after acquiring the hidden paintability lease, the compositor
-        // needs a short settle period to produce a painted frame. Waiting inside
-        // the global screenshot lock prevents another tab from changing lease
-        // state before the current capture actually hits CDP.
+        // Why: let the compositor settle to a painted frame after the lease, inside the screenshot lock so another tab can't change lease state first.
         await new Promise((r) => setTimeout(r, settleMs))
         const raw = await this.execAgentBrowser(sessionName, commandArgs)
         return this.readScreenshotFromResult(raw, format)
@@ -1421,9 +1369,7 @@ export class AgentBrowserBridge {
         ? await this.browserManager.acquireAutomationVisibility(session.webContentsId)
         : () => {}
       try {
-        // Why: full-page capture still depends on the guest compositor producing
-        // a fresh frame. Wait after the target webview is paintable so the direct
-        // CDP capture sees the live page instead of a stale surface.
+        // Why: the guest compositor needs a beat to paint a fresh frame after becoming paintable, or CDP captures a stale surface.
         await new Promise((r) => setTimeout(r, settleMs))
         const wc = this.getWebContents(webContentsId)
         if (!wc) {
@@ -1536,11 +1482,7 @@ export class AgentBrowserBridge {
       if (normalizedState) {
         args.push('--state', normalizedState)
       }
-      // Why: agent-browser's selector wait surface does not support `--state visible`
-      // or a documented per-command `--timeout`. Orca normalizes "visible" back
-      // to the default selector wait semantics and enforces the requested timeout
-      // at the bridge layer so missing selectors fail as browser_timeout instead
-      // of hanging until the generic runtime RPC timeout fires.
+      // Why: agent-browser's selector wait lacks a per-command timeout — enforce it here so a missing selector fails as browser_timeout, not a hang.
       return (await this.execAgentBrowser(sessionName, args, {
         timeoutMs:
           options?.timeout != null && hasCondition
@@ -1589,8 +1531,7 @@ export class AgentBrowserBridge {
       browserPageId,
       async (sessionName) => {
         if (!(await this.isExplicitContentEditableTarget(sessionName, element))) {
-          // Why: agent-browser resolves this ref directly, preserving iframe,
-          // shadow-root, and unfocusable-target semantics for ordinary fields.
+          // Why: agent-browser resolves the ref directly, preserving iframe/shadow-root/unfocusable semantics for ordinary fields.
           await this.execAgentBrowser(sessionName, ['fill', element, ''])
           return { cleared: element }
         }
@@ -1628,9 +1569,7 @@ export class AgentBrowserBridge {
   }
 
   async pdf(worktreeId?: string, browserPageId?: string): Promise<BrowserPdfResult> {
-    // Why: agent-browser's pdf command via CDP Page.printToPDF hangs in Electron
-    // webviews. Use Electron's native webContents.printToPDF() which is reliable.
-    // Routed through enqueueCommand so it serializes with other in-flight commands.
+    // Why: agent-browser's CDP printToPDF hangs in Electron webviews — use the native webContents.printToPDF().
     return this.enqueueTargetedCommand(worktreeId, browserPageId, async (_sessionName, target) => {
       const wc = this.getWebContents(target.webContentsId)
       if (!wc) {
@@ -1727,17 +1666,14 @@ export class AgentBrowserBridge {
         throw new BrowserError('browser_error', 'Debugger not attached')
       }
 
-      // Why: agent-browser only supports width/height/scale for `set viewport`;
-      // it has no `mobile` flag. Orca's CLI exposes `--mobile`, so apply the
-      // emulation directly through CDP to keep the public CLI contract honest.
+      // Why: agent-browser's `set viewport` has no `mobile` flag, so apply the emulation directly via CDP to honor Orca's --mobile.
       await dbg.sendCommand('Emulation.setDeviceMetricsOverride', {
         width,
         height,
         deviceScaleFactor: scale,
         mobile
       })
-      // Why: BrowserView's compositor surface can keep the previous host size
-      // after metrics-only resize, which crops remote screencast clients.
+      // Why: BrowserView's compositor can keep the old host size after a metrics-only resize, cropping remote screencast clients.
       await Promise.resolve(dbg.sendCommand('Emulation.setVisibleSize', { width, height })).catch(
         () => {}
       )
@@ -1821,9 +1757,7 @@ export class AgentBrowserBridge {
     })
   }
 
-  // TODO: Add interceptContinue/interceptBlock once agent-browser supports per-request
-  // interception decisions. Currently agent-browser only operates on URL pattern-level
-  // routing, not individual request IDs, so the RPC/CLI interface doesn't map cleanly.
+  // TODO: Add interceptContinue/interceptBlock once agent-browser supports per-request decisions, not just URL-pattern routing.
 
   // ── Capture commands ──
 
@@ -1890,8 +1824,7 @@ export class AgentBrowserBridge {
 
   async exec(command: string, worktreeId?: string, browserPageId?: string): Promise<unknown> {
     return this.enqueueTargetedCommand(worktreeId, browserPageId, async (sessionName) => {
-      // Why: strip target/session flags from raw passthrough commands so a
-      // caller cannot override Orca's selected browser page or CDP proxy.
+      // Why: strip target/session flags from passthrough so a caller can't override Orca's selected page or CDP proxy.
       const args = stripAgentBrowserTargetArgs(parseShellArgs(command.trim()))
       return await this.execAgentBrowser(sessionName, args)
     })
@@ -1968,8 +1901,7 @@ export class AgentBrowserBridge {
       return execute(sessionName, target)
     }
 
-    // Why: inactive browser panes are display:none in the renderer; the
-    // automation lease makes only this target paintable without selecting it.
+    // Why: inactive panes are display:none; the automation lease makes only this target paintable without selecting it.
     const restore = await this.browserManager.acquireAutomationVisibility(target.webContentsId)
     try {
       const visibleTarget = await this.refreshTargetAfterAutomationVisibility(
@@ -2002,10 +1934,7 @@ export class AgentBrowserBridge {
       this.activeWebContentsPerWorktree.set(worktreeId, visibleTarget.webContentsId)
     }
 
-    // Why: making a parked webview paintable can re-register the same browser
-    // page with a new guest webContents. Tear down any stale named session now;
-    // DOM commands recreate immediately, direct-CDP commands let the next DOM
-    // command recreate against the live guest.
+    // Why: making a parked webview paintable can re-register the page with a new guest webContents; tear down the stale session.
     await this.restartSessionForTarget(
       sessionName,
       visibleTarget.browserPageId,
@@ -2086,8 +2015,7 @@ export class AgentBrowserBridge {
       throw new BrowserError('browser_no_tab', 'No browser tab open in this worktree')
     }
 
-    // Why: prefer per-worktree active tab to prevent cross-worktree interference.
-    // Fall back to global activeWebContentsId for callers that don't pass worktreeId.
+    // Why: prefer per-worktree active tab to avoid cross-worktree interference; fall back to global for callers without worktreeId.
     const preferredWcId =
       (worktreeId && this.activeWebContentsPerWorktree.get(worktreeId)) ?? this.activeWebContentsId
 
@@ -2108,10 +2036,7 @@ export class AgentBrowserBridge {
       }
     }
 
-    // Why: persisted store state can leave ghost tabs whose webContents no longer exist.
-    // Skip those and pick the first live tab. Also activate it so tabList and
-    // subsequent resolveActiveTab calls are consistent without requiring an
-    // explicit tab switch after app startup.
+    // Why: persisted state can leave ghost tabs (dead webContents); skip them and activate the first live tab for consistency.
     for (const [tabId, wcId] of tabs) {
       if (this.getWebContents(wcId)) {
         this.activeWebContentsId = wcId
@@ -2129,14 +2054,7 @@ export class AgentBrowserBridge {
     )
   }
 
-  // Why: text-mutating commands (inserttext/type/fill) must not silently fall
-  // back to the global active tab when no worktree was resolved — that tab can
-  // belong to a worktree the user is currently viewing, so a goal-loop agent in
-  // another worktree would inject text into the user's foreground webview and
-  // steal OS focus. A scoped (worktreeId-bearing) call is already safe because
-  // the candidate set is pre-filtered to that worktree, so defer to the lenient
-  // resolver. An unscoped call instead requires an unambiguous target: scope to
-  // the lone worktree with live tabs, or refuse rather than guess.
+  // Why: don't fall back to the global tab for text mutation — it could inject into another worktree's foreground webview and steal focus.
   private resolveScopedActiveTab(worktreeId?: string): ResolvedBrowserCommandTarget {
     if (worktreeId) {
       return this.resolveActiveTab(worktreeId)
@@ -2177,9 +2095,7 @@ export class AgentBrowserBridge {
       return
     }
 
-    // Why: two concurrent CLI calls can both reach here before either finishes
-    // creating the session. Without this lock, both would create proxies and the
-    // second would overwrite the first, leaking the first proxy's server/debugger.
+    // Why: without this lock, two concurrent calls both create proxies and the second leaks the first's server/debugger.
     const pending = this.pendingSessionCreation.get(sessionName)
     if (pending) {
       await pending
@@ -2189,19 +2105,14 @@ export class AgentBrowserBridge {
     const createSession = async (): Promise<void> => {
       const wc = this.getWebContents(webContentsId)
       if (!wc) {
-        // Why: the renderer can unregister/destroy a webview between target
-        // resolution and session creation. Preserve the explicit page identity
-        // so callers get the same error shape as a settled closed tab.
+        // Why: the webview can be destroyed between target resolution and session creation — keep the same closed-tab error shape.
         throw new BrowserError(
           'browser_tab_not_found',
           `Browser page ${browserPageId} is no longer available`
         )
       }
 
-      // Why: agent-browser's daemon persists session state (including the CDP port)
-      // across Orca restarts. A stale session ignores --cdp (already initialized) and
-      // connects to the dead port. Must await close so the daemon forgets the session
-      // before we pass --cdp with the new port.
+      // Why: the daemon persists sessions (incl. CDP port) across restarts; close the stale one first or it ignores --cdp and hits the dead port.
       await this.closeStaleAgentBrowserSession(sessionName)
 
       const proxy = new CdpWsProxy(wc)
@@ -2286,13 +2197,11 @@ export class AgentBrowserBridge {
 
     const pendingCreation = this.pendingSessionCreation.get(sessionName)
     if (pendingCreation) {
-      // Why: tab close can race with stale-session cleanup before sessions.set().
-      // Wait for creation to settle so a late proxy cannot survive the close.
+      // Why: tab close can race session creation before sessions.set(); await it so no late proxy survives the close.
       try {
         await pendingCreation
       } catch {
-        // Creation failures are handled by the original caller; teardown still
-        // needs to reject queued work and clear any partial state below.
+        // Creation failures are handled by the original caller; teardown still rejects queued work below.
       }
     }
 
@@ -2305,14 +2214,11 @@ export class AgentBrowserBridge {
     this.sessions.delete(sessionName)
     this.pendingSessionCreation.delete(sessionName)
 
-    // Why: queued commands would hang forever if we just delete the queue —
-    // their promises would never resolve or reject. Drain and reject them.
+    // Why: queued commands would hang forever if we just delete the queue — drain and reject them.
     this.rejectQueuedCommandsForClosedSession(sessionName)
 
     if (session.activeProcess) {
-      // Why: queued command rejection is not enough when a daemon command is
-      // already running. Kill the active process so callers do not wait for the
-      // generic exec timeout after the session/tab has already been destroyed.
+      // Why: rejecting the queue isn't enough for an in-flight command — kill the process so callers don't wait out the exec timeout.
       this.cancelledProcesses.add(session.activeProcess)
       try {
         session.activeProcess.kill()
@@ -2324,9 +2230,7 @@ export class AgentBrowserBridge {
 
     const destroy = (async (): Promise<void> => {
       try {
-        // Why: each browser tab uses its own named agent-browser session. Closing
-        // without --session only tears down the default session and leaves the tab
-        // session's daemon process running.
+        // Why: each tab has its own named session — close without --session leaves this tab's daemon running.
         await this.runAgentBrowserRaw(sessionName, ['--session', sessionName, 'close'])
       } catch {
         // Session may already be dead
@@ -2365,15 +2269,11 @@ export class AgentBrowserBridge {
   ): Promise<unknown> {
     const session = this.sessions.get(sessionName)
     if (!session) {
-      // Why: queued commands can reach execution after a concurrent tab close
-      // deletes the session. Surface this as a tab lifecycle error, not an
-      // opaque internal bridge failure.
+      // Why: a queued command can run after a concurrent close deleted the session — surface a tab-lifecycle error, not an opaque failure.
       throw this.createPageUnavailableError(sessionName)
     }
 
-    // Why: between enqueue time and execution time (queue delay), the webContents
-    // could be destroyed. Check here to give a clear error instead of letting the
-    // proxy fail with cryptic Electron debugger errors.
+    // Why: the webContents can be destroyed during queue delay — check here to avoid cryptic Electron debugger errors.
     if (!this.getWebContents(session.webContentsId)) {
       await this.destroySession(sessionName)
       throw this.createPageUnavailableError(sessionName)
@@ -2383,18 +2283,14 @@ export class AgentBrowserBridge {
     const managesInterceptRoutes =
       commandArgs[0] === 'network' && (commandArgs[1] === 'route' || commandArgs[1] === 'unroute')
 
-    // Why: --cdp is session-initialization only — first command needs it, subsequent don't.
-    // Pass as port number (not ws:// URL) so agent-browser hits the proxy's HTTP /json
-    // endpoint for target discovery. The proxy only exposes the webview, preventing
-    // agent-browser from picking the host renderer page.
+    // Why: --cdp is init-only; pass the port (not a ws:// URL) so agent-browser's /json discovery sees only the proxy's webview, not the host renderer page.
     const needsInit = !session.initialized
     if (needsInit) {
       const port = session.proxy.getPort()
       args.push('--cdp', String(port))
     }
 
-    // Why: exec passthrough can produce a large argv array; spreading it into
-    // push risks V8 argument limits before execFile receives the command.
+    // Why: exec passthrough can produce a large argv; spreading into push risks V8 argument limits.
     for (const commandArg of commandArgs) {
       args.push(commandArg)
     }
@@ -2412,14 +2308,11 @@ export class AgentBrowserBridge {
       )
     }
 
-    // Why: only mark initialized after a successful command — if the first --cdp
-    // connection fails, the next attempt should retry with --cdp.
+    // Why: mark initialized only after success, so a failed first --cdp connection retries with --cdp.
     if (needsInit) {
       session.initialized = true
 
-      // Why: after a process swap, intercept patterns are lost because the session
-      // was destroyed and recreated. Restore them now that the new session is live,
-      // unless the caller's first command explicitly reconfigured routing.
+      // Why: a process swap loses intercept patterns — restore them now unless the caller's first command reconfigured routing.
       const pendingPatterns = managesInterceptRoutes
         ? undefined
         : this.pendingInterceptRestore.get(sessionName)
@@ -2437,8 +2330,7 @@ export class AgentBrowserBridge {
           ])
           session.activeInterceptPatterns = pendingPatterns
         } catch {
-          // Why: intercept restore is best-effort — don't fail the user's command
-          // if the new page doesn't support the same interception setup.
+          // Why: intercept restore is best-effort — don't fail the user's command if the new page can't support it.
         }
       }
     }
@@ -2465,8 +2357,7 @@ export class AgentBrowserBridge {
     value: string
   ): Promise<void> {
     await this.execAgentBrowser(sessionName, ['focus', element])
-    // Why: stdin avoids argv limits while keeping replacement atomic; chunked
-    // editor transactions can move focus and split one fill across controls.
+    // Why: stdin avoids argv limits and keeps replacement atomic; chunked edits can move focus and split a fill across controls.
     await this.execAgentBrowser(sessionName, ['eval', '--stdin'], {
       stdinText: focusedRichTextEditExpression(JSON.stringify(value), { selectAll: true })
     })
@@ -2490,8 +2381,7 @@ export class AgentBrowserBridge {
         resolve()
       }
 
-      // Why: this is best-effort daemon cleanup before creating a fresh session;
-      // a wedged close command must not block the real browser action.
+      // Why: best-effort daemon cleanup — a wedged close must not block the real browser action.
       const timeout = setTimeout(() => {
         child?.kill()
         finish()
@@ -2516,8 +2406,7 @@ export class AgentBrowserBridge {
     fallbackCode: string,
     webContentsId?: number
   ): BrowserError {
-    // Why: CDP "connection refused" can also mean a real proxy failure. Only
-    // convert it to a closed-page error when bridge state confirms the target is gone.
+    // Why: CDP "connection refused" can also mean a real proxy failure — only map to closed-page when the target is confirmed gone.
     if (
       fallbackCode === 'browser_error' &&
       isTabClosedTransportError(message) &&
@@ -2548,8 +2437,7 @@ export class AgentBrowserBridge {
       child = execFile(
         this.agentBrowserBin,
         args,
-        // Why: screenshots return large base64 strings that exceed Node's default
-        // 1MB maxBuffer, causing ENOBUFS and a timeout-like failure.
+        // Why: screenshots return large base64 that exceeds Node's default 1MB maxBuffer (ENOBUFS).
         {
           timeout: execOptions?.timeoutMs ?? EXEC_TIMEOUT_MS,
           maxBuffer: 50 * 1024 * 1024,
@@ -2592,9 +2480,7 @@ export class AgentBrowserBridge {
           }
 
           if (error) {
-            // Why: agent-browser exits non-zero for command failures (e.g. clipboard
-            // NotAllowedError) but still writes structured JSON to stdout. Parse it
-            // so callers get the real error message instead of generic "Command failed".
+            // Why: agent-browser exits non-zero on failure but still writes structured JSON to stdout — parse it for the real error.
             if (stdout) {
               try {
                 const parsed = JSON.parse(stdout)
diff --git a/src/main/browser/browser-cookie-import.ts b/src/main/browser/browser-cookie-import.ts
index 3191509d30c..7bcfd4ea247 100644
--- a/src/main/browser/browser-cookie-import.ts
+++ b/src/main/browser/browser-cookie-import.ts
@@ -1,5 +1,4 @@
-/* eslint-disable max-lines -- Why: cookie import is a single pipeline (detect → decrypt → stage → swap)
-   that must stay together so the encryption, schema, and staging steps remain in sync. */
+/* eslint-disable max-lines -- Why: cookie import is one pipeline (detect → decrypt → stage → swap) that must stay together to keep encryption/schema/staging in sync. */
 import { app, type BrowserWindow, dialog, session } from 'electron'
 import { execFileSync } from 'node:child_process'
 import { createDecipheriv, pbkdf2Sync, randomUUID } from 'node:crypto'
@@ -19,8 +18,7 @@ import { DatabaseSync } from 'node:sqlite'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
-// Why: writing to userData instead of tmpdir() so the diag log is only
-// readable by the current user, not world-readable in /tmp.
+// Why: write the diag log to userData, not world-readable /tmp, so only the current user can read it.
 let _diagLog: string | null = null
 function getDiagLogPath(): string {
   if (!_diagLog) {
@@ -38,8 +36,7 @@ function reasonWithDiagLog(reason: string): string {
 const COOKIE_IMPORT_ERROR_SUMMARY_MAX_CHARS = 180
 const COOKIE_IMPORT_ERROR_SCAN_MAX_CHARS = 512
 
-// Why: imported cookie errors can include pasted or file-derived payloads;
-// diagnostics only need a short preview, not a full-string whitespace pass.
+// Why: error messages can embed large pasted/file payloads; cap the scan since diagnostics only need a short preview.
 export function summarizeCookieImportError(err: unknown): string {
   const raw = err instanceof Error && err.message ? err.message : String(err)
   let summary = ''
@@ -108,8 +105,7 @@ type ChromiumBrowserDef = {
   label: string
   keychainService: string
   keychainAccount: string
-  // Why: each platform stores browser data in a different location. The per-platform
-  // root paths are resolved at detection time via browserRootPath().
+  // Per-platform data-dir roots, resolved at detection time via browserRootPath().
   macRoot?: string
   winRoot?: string
   linuxRoot?: string
@@ -161,8 +157,7 @@ const CHROMIUM_BROWSERS: ChromiumBrowserDef[] = [
   },
   {
     family: 'helium',
-    // Why: Helium deviates from the '<Browser> Safe Storage'/'<Browser>' convention —
-    // its Keychain entry is literally service 'Helium Storage Key', account 'Helium'.
+    // Why: Helium breaks the '<Browser> Safe Storage' convention — its Keychain service is literally 'Helium Storage Key'.
     label: 'Helium',
     keychainService: 'Helium Storage Key',
     keychainAccount: 'Helium',
@@ -208,9 +203,7 @@ function isSafeBrowserProfileDirectory(directory: string): boolean {
   )
 }
 
-// Why: Chrome's Local State JSON contains profile.info_cache which maps profile
-// directory names (e.g. "Default", "Profile 1") to metadata including the
-// user-visible display name. This lets us show human-readable names in the picker.
+// Why: Chrome's Local State profile.info_cache maps profile dirs to display names for the picker.
 function discoverProfiles(browserRoot: string): BrowserProfile[] {
   try {
     const localStatePath = join(browserRoot, 'Local State')
@@ -267,8 +260,7 @@ function discoverFirefoxProfiles(): BrowserProfile[] {
     const entries = readdirSync(profilesRoot, { withFileTypes: true })
       .filter((e) => e.isDirectory())
       .map((e) => e.name)
-    // Why: Firefox profile dirs are named <random>.<name> (e.g. "abc123.default-release").
-    // Prefer 'default-release' as it's the primary user profile on most installs.
+    // Why: Firefox dirs are named <random>.<name>; prefer 'default-release' as the primary profile on most installs.
     const sorted = entries.sort((a, b) => {
       if (a.includes('default-release')) {
         return -1
@@ -360,8 +352,7 @@ export function detectInstalledBrowsers(): DetectedBrowser[] {
       continue
     }
     const profiles = discoverProfiles(root)
-    // Why: a browser is "detected" if at least one profile has a cookies DB.
-    // Use the first profile with a valid cookies path as the default selection.
+    // Why: a browser counts as detected once a profile has a cookies DB; use the first such profile as default.
     for (const profile of profiles) {
       const profileDir = join(root, profile.directory)
       const cookiesPath = resolveChromiumCookiesPath(profileDir)
@@ -393,10 +384,6 @@ export function detectInstalledBrowsers(): DetectedBrowser[] {
   return detected
 }
 
-// Why: when the user selects a different profile from the picker, we need to
-// resolve the cookies path for that profile. Returns a new DetectedBrowser
-// with the updated cookiesPath and selectedProfile, or null if the profile
-// has no cookies DB.
 export function selectBrowserProfile(
   browser: DetectedBrowser,
   profileDirectory: string
@@ -463,9 +450,7 @@ type ValidatedCookie = {
   expirationDate: number | undefined
 }
 
-// Why: Chromium's SQLite schema uses CookieSameSiteForStorage enum:
-// 0=UNSPECIFIED, 1=NO_RESTRICTION(None), 2=LAX, 3=STRICT.
-// This differs from Firefox (0=None, 1=Lax, 2=Strict).
+// Why: Chromium's CookieSameSiteForStorage enum (0=Unspecified,1=None,2=Lax,3=Strict) differs from Firefox's numbering.
 function chromiumSameSite(raw: number): 'unspecified' | 'no_restriction' | 'lax' | 'strict' {
   switch (raw) {
     case 1:
@@ -512,9 +497,7 @@ function normalizeSameSite(raw: unknown): 'unspecified' | 'no_restriction' | 'la
   return 'unspecified'
 }
 
-// Why: Electron's cookies.set() requires a url field to determine the cookie's
-// scope. Derive it from the domain + secure flag so the caller doesn't need
-// to supply it.
+// Why: cookies.set() needs a url to scope the cookie; derive it from domain + secure flag.
 function deriveUrl(domain: string, secure: boolean): string | null {
   const cleanDomain = domain.startsWith('.') ? domain.slice(1) : domain
   if (!cleanDomain || cleanDomain.includes(' ')) {
@@ -578,8 +561,7 @@ async function importValidatedCookies(
   let skipped = totalInput - cookies.length
   const domainSet = new Set<string>()
 
-  // Why: Electron's cookies.set() rejects any non-printable-ASCII byte.
-  // Strip from all string fields as a safety net.
+  // Why: Electron's cookies.set() rejects any non-printable-ASCII byte; strip as a safety net.
   const stripNonPrintable = (s: string): string => s.replace(/[^\x20-\x7E]/g, '')
 
   for (const cookie of cookies) {
@@ -596,8 +578,7 @@ async function importValidatedCookies(
         expirationDate: cookie.expirationDate
       })
       importedCount++
-      // Why: surface only the domain — never name, value, or path — so the
-      // renderer can show a useful summary without leaking secret cookie data.
+      // Why: surface only the domain (never name/value/path) so the summary doesn't leak secret cookie data.
       const cleanDomain = cookie.domain.startsWith('.') ? cookie.domain.slice(1) : cookie.domain
       domainSet.add(cleanDomain)
     } catch (err) {
@@ -638,8 +619,7 @@ async function importValidatedCookies(
 // Import from JSON file
 // ---------------------------------------------------------------------------
 
-// Why: source selection must be main-owned via a native open dialog so a
-// compromised renderer cannot turn cookie import into arbitrary file reads.
+// Why: use a main-owned native dialog so a compromised renderer can't turn import into arbitrary file reads.
 export async function pickCookieFile(parentWindow: BrowserWindow | null): Promise<string | null> {
   const opts = {
     title: 'Import Cookies',
@@ -714,14 +694,11 @@ export async function importCookiesFromFile(
 // Direct import from installed Chromium browser
 // ---------------------------------------------------------------------------
 
-// Why: Google and other services bind auth cookies to the User-Agent that
-// created them. We read the source browser's real version from its plist
-// and construct a matching UA string so imported sessions aren't invalidated.
+// Why: services bind auth cookies to the creating User-Agent, so build a UA matching the source browser's real version.
 export function getUserAgentForBrowser(
   family: BrowserSessionProfileSource['browserFamily']
 ): string | null {
-  // Why: UA spoofing uses macOS-specific plist reading. On other platforms,
-  // skip UA override — the default Electron UA is acceptable.
+  // Why: UA version comes from macOS-only plist reading; elsewhere the default Electron UA is acceptable.
   if (process.platform !== 'darwin') {
     return null
   }
@@ -763,14 +740,12 @@ export function getUserAgentForBrowser(
       return v ? `Mozilla/5.0 (${platform}) ${chromeBase} Chrome/${v} Safari/537.36` : null
     }
     case 'comet': {
-      // Why: Comet is Chromium-based and ships a Chrome-shaped version in its plist.
-      // Use the same UA shape as Chrome itself so Google-bound auth cookies survive import.
+      // Why: Comet is Chromium-based; use Chrome's UA shape so Google-bound auth cookies survive import.
       const v = readBrowserVersion('/Applications/Comet.app')
       return v ? `Mozilla/5.0 (${platform}) ${chromeBase} Chrome/${v} Safari/537.36` : null
     }
     case 'helium': {
-      // Why: Helium is Chromium-based and ships a Chrome-shaped version in its plist.
-      // Use the same UA shape as Chrome itself so Google-bound auth cookies survive import.
+      // Why: Helium is Chromium-based; use Chrome's UA shape so Google-bound auth cookies survive import.
       const v = readBrowserVersion('/Applications/Helium.app')
       return v ? `Mozilla/5.0 (${platform}) ${chromeBase} Chrome/${v} Safari/537.36` : null
     }
@@ -805,16 +780,12 @@ function chromiumTimestampToUnix(chromiumTs: bigint | number | string): number {
   }
 }
 
-// Why: each platform uses a different mechanism to protect the Chromium cookie encryption key.
-// macOS: PBKDF2(keychain password, "saltysalt", 1003 iterations) → AES-128-CBC
-// Linux: PBKDF2(keyring password or "peanuts", "saltysalt", 1 iteration) → AES-128-CBC
-// Windows: DPAPI-encrypted master key from Local State → AES-256-GCM
+// Why: each platform protects the Chromium key differently: macOS/Linux PBKDF2→AES-128-CBC, Windows DPAPI→AES-256-GCM.
 
 type EncryptionKeyResult = {
   key: Buffer
   mode: 'aes-128-cbc' | 'aes-256-gcm'
-  // Why: Linux v10 cookies use a hardcoded "peanuts" password while v11 uses the
-  // keyring password. We need both keys to decrypt the full cookie set.
+  // Why: Linux v10 cookies use "peanuts" and v11 the keyring password; both keys are needed to decrypt the full set.
   fallbackKey?: Buffer
 }
 
@@ -926,8 +897,7 @@ export function buildChromiumCookieInsertParams(
       return null
     }
 
-    // Why: Chromium cookie DB columns drift across Chrome/Electron versions.
-    // Missing NOT NULL target columns must get safe Chromium defaults, not NULL.
+    // Why: cookie columns drift across Chrome/Electron versions; missing NOT NULL columns need Chromium defaults, not NULL.
     return fallbackChromiumCookieColumnValue(column, sourceRow)
   })
 }
@@ -972,9 +942,7 @@ function getLinuxEncryptionKey(
   keychainService: string,
   keychainAccount: string
 ): EncryptionKeyResult | null {
-  // Why: Linux v10 cookies use the hardcoded password "peanuts" with 1 PBKDF2
-  // iteration. v11 cookies use the actual keyring password. We derive both keys
-  // so the decrypt function can try each based on the version prefix.
+  // Why: v10 cookies use hardcoded "peanuts", v11 the keyring password; derive both so decrypt can pick by version prefix.
   const v10Key = pbkdf2Sync('peanuts', PBKDF2_SALT, 1, PBKDF2_KEY_LENGTH, 'sha1')
 
   let keyringPassword = ''
@@ -1031,8 +999,7 @@ function getWindowsEncryptionKey(browser: DetectedBrowser): EncryptionKeyResult
       return null
     }
 
-    // Why: PowerShell DPAPI decrypt is the only way to access the master key
-    // without native addons. The key is passed via stdin to prevent injection.
+    // Why: PowerShell DPAPI decrypt is the only native-addon-free path to the master key; pass via stdin to avoid injection.
     const dpapiData = encryptedKey.subarray(dpapiPrefix.length).toString('base64')
     const script = [
       'try { Add-Type -AssemblyName System.Security.Cryptography.ProtectedData -ErrorAction Stop }',
@@ -1056,12 +1023,7 @@ function getWindowsEncryptionKey(browser: DetectedBrowser): EncryptionKeyResult
   }
 }
 
-// Why: Chromium 127+ prepends a 32-byte per-host HMAC to the cookie value
-// before encrypting. After AES-CBC decryption, the raw output is:
-//   [32-byte HMAC] [actual cookie value]
-// Detection: the HMAC is a hash, so roughly half its bytes are non-printable
-// ASCII. Real cookie values are overwhelmingly printable. If ≥8 of the first
-// 32 bytes are non-printable, it's an HMAC prefix.
+// Why: Chromium 127+ prepends a 32-byte HMAC before the value; a hash is ~half non-printable, so ≥8 non-printable of the first 32 bytes flags the prefix.
 const CHROMIUM_COOKIE_HMAC_LEN = 32
 
 function hasHmacPrefix(buf: Buffer): boolean {
@@ -1103,8 +1065,7 @@ function decryptCookieValueRaw(
     return Buffer.alloc(0)
   }
 
-  // Why: Linux v10 uses "peanuts" key, v11 uses keyring key. Try the primary
-  // key first, then fallback. macOS uses the same key for both versions.
+  // Why: Linux v10 uses the "peanuts" key, v11 the keyring key; try primary then fallback (macOS uses one key).
   const keysToTry =
     version === 'v10' && keyResult.fallbackKey
       ? [keyResult.fallbackKey, keyResult.key]
@@ -1175,8 +1136,7 @@ function decodeSafariBinaryCookies(buffer: Buffer): ValidatedCookie[] {
 }
 
 function appendSafariCookies(target: ValidatedCookie[], cookies: readonly ValidatedCookie[]): void {
-  // Why: Safari binary cookie pages can contain generated-size cookie lists;
-  // spreading a decoded page into push can exceed JavaScript's argument limit.
+  // Why: pages can hold large cookie lists; push per-item to avoid exceeding the spread argument limit.
   for (const cookie of cookies) {
     target.push(cookie)
   }
@@ -1215,8 +1175,7 @@ function decodeSafariCookie(buf: Buffer): ValidatedCookie | null {
   if (buf.length < 48) {
     return null
   }
-  // Why: size is read from the binary file and could be attacker-controlled.
-  // Clamp to buf.length so readCString cannot escape the cookie's subarray.
+  // Why: size comes from the file and could be attacker-controlled; clamp so readCString can't escape the subarray.
   const size = Math.min(buf.readUInt32LE(0), buf.length)
   if (size < 48) {
     return null
@@ -1402,8 +1361,7 @@ async function importCookiesFromSafari(
     data = readFileSync(browser.cookiesPath)
   } catch (err) {
     diag(`  Safari read failed: ${err}`)
-    // Why: Safari's Cookies.binarycookies lives inside a macOS sandbox container.
-    // Reading it requires Full Disk Access in System Settings → Privacy & Security.
+    // Why: Safari's Cookies.binarycookies is in a sandbox container; reading it needs Full Disk Access.
     const isPermError =
       err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'EPERM'
     if (isPermError) {
@@ -1459,19 +1417,9 @@ export async function importCookiesFromBrowser(
     return importCookiesFromSafari(browser, targetPartition)
   }
 
-  // Why: Electron's cookies.set() API rejects many valid cookie values (binary
-  // bytes > 0x7F etc). Instead, decrypt from the source browser and write
-  // plaintext directly to the SQLite `value` column. CookieMonster reads
-  // `value` as a raw byte string when `encrypted_value` is empty, bypassing
-  // all API-level validation. This works because Electron's CookieMonster in
-  // dev mode does not use os_crypt encryption — it stores cookies as plaintext.
-  // In packaged builds where os_crypt IS active, CookieMonster will re-encrypt
-  // plaintext cookies on its next flush, so this approach is safe in both modes.
+  // Why: cookies.set() rejects many valid values (bytes > 0x7F); instead write plaintext to the `value` column, which CookieMonster reads raw when `encrypted_value` is empty and re-encrypts on flush in packaged builds.
 
-  // Why: CookieMonster holds the live DB's data in memory and overwrites it
-  // on flush/shutdown. Writing directly to the live DB is futile. Instead,
-  // copy the live DB to a staging location, populate it there, and let the
-  // next cold start swap it in before CookieMonster initializes.
+  // Why: CookieMonster overwrites the live DB on flush, so stage a populated copy and swap it in at next cold start.
   const targetSession = session.fromPartition(targetPartition)
   await targetSession.cookies.flushStore()
 
@@ -1479,10 +1427,7 @@ export async function importCookiesFromBrowser(
   const partitionDir = join(app.getPath('userData'), 'Partitions', partitionName)
   let liveCookiesPath = resolveChromiumCookiesPath(partitionDir)
 
-  // Why: Electron only creates the partition's Cookies SQLite file after the
-  // session has actually stored a cookie. For newly created profiles that have
-  // never been used by a webview, the file won't exist yet. Setting and
-  // removing a throwaway cookie forces Electron to initialize the database.
+  // Why: Electron creates the Cookies file only after a cookie is stored; a throwaway set/remove forces DB init for unused profiles.
   if (!liveCookiesPath) {
     try {
       await targetSession.cookies.set({ url: 'https://localhost', name: '__init', value: '1' })
@@ -1508,8 +1453,7 @@ export async function importCookiesFromBrowser(
     mkdirSync(stagingDir, { recursive: true })
     copyFileSync(liveCookiesPath, stagingCookiesPath)
   } catch {
-    // Why: copyFile is not atomic and can leave a partial database after an
-    // I/O failure, so failed imports must not retain sensitive cookie data.
+    // Why: copyFile is non-atomic and can leave a partial DB; delete it so failed imports retain no cookie data.
     try {
       unlinkSync(stagingCookiesPath)
     } catch {
@@ -1520,8 +1464,7 @@ export async function importCookiesFromBrowser(
 
   let sourceSnapshot: ChromiumCookieSnapshot
   try {
-    // Why: the browser can commit cookies only to WAL while it remains open;
-    // snapshot retries prevent pairing the main DB with a racing WAL generation.
+    // Why: an open browser may hold cookies in WAL only; snapshot retries avoid pairing the main DB with a racing WAL.
     sourceSnapshot = createChromiumCookieSnapshot(browser.cookiesPath)
   } catch (err) {
     try {
@@ -1540,8 +1483,7 @@ export async function importCookiesFromBrowser(
   let stagingDb: InstanceType<typeof DatabaseSync> | null = null
 
   try {
-    // Why: Chromium stores timestamps as microseconds since 1601, which can exceed
-    // Number.MAX_SAFE_INTEGER (~9e15). readBigInts ensures no precision loss.
+    // Why: Chromium timestamps (µs since 1601) can exceed Number.MAX_SAFE_INTEGER; readBigInts avoids precision loss.
     sourceDb = new DatabaseSync(sourceSnapshot.databasePath, {
       readOnly: true,
       readBigInts: true
@@ -1586,8 +1528,7 @@ export async function importCookiesFromBrowser(
     if (needsSourceKey && !sourceKey) {
       stagingDb.close()
       stagingDb = null
-      // Why: key denial happens after staging, so failed retries must not leave
-      // one full target database copy behind each time.
+      // Why: key denial happens after staging, so clean up the target DB copy or retries pile up.
       try {
         unlinkSync(stagingCookiesPath)
       } catch {
@@ -1599,11 +1540,7 @@ export async function importCookiesFromBrowser(
       }
     }
 
-    // Why: Google's integrity cookies (SIDCC, __Secure-*PSIDCC, __Secure-STRP)
-    // are cryptographically bound to the source browser's TLS fingerprint and
-    // environment. Importing them into a different browser causes
-    // accounts.google.com to reject the session with CookieMismatch. Skipping
-    // them lets Google regenerate fresh integrity cookies on the first request.
+    // Why: Google integrity cookies are bound to the source browser's TLS/env; importing them triggers CookieMismatch, so skip and let Google reissue.
     const INTEGRITY_COOKIE_NAMES = new Set([
       'SIDCC',
       '__Secure-1PSIDCC',
@@ -1649,9 +1586,7 @@ export async function importCookiesFromBrowser(
 
     for (const sourceRow of sourceRows) {
       const encRaw = sourceRow.encrypted_value
-      // Why: node:sqlite returns BLOB columns as Uint8Array. Any other truthy type
-      // means the schema is unexpected — treat it as missing rather than creating
-      // an empty buffer that would silently produce a blank cookie value.
+      // Why: node:sqlite returns BLOBs as Uint8Array; treat any other type as missing, not an empty buffer that would silently blank the cookie value.
       const encBuf = encRaw instanceof Uint8Array ? Buffer.from(encRaw) : null
       const plainRaw = sourceRow.value
 
@@ -1687,9 +1622,7 @@ export async function importCookiesFromBrowser(
       const httpOnly = sourceRow.is_httponly === 1n
       const sameSite = chromiumSameSite(Number(sourceRow.samesite ?? 0))
       const expiresUtc = chromiumTimestampToUnix(sourceRow.expires_utc as bigint)
-      // Why: cookie values are raw byte strings, not UTF-8 text. Using latin1
-      // (ISO-8859-1) preserves all byte values 0x00–0xFF without replacement
-      // characters that UTF-8 decoding would insert for invalid sequences.
+      // Why: cookie values are raw bytes, not UTF-8; latin1 preserves 0x00–0xFF without lossy replacement.
       const value = decryptedValue.toString('latin1')
 
       decryptedCookies.push({
@@ -1716,18 +1649,13 @@ export async function importCookiesFromBrowser(
 
     diag(`  SQLite staging complete: ${imported} cookies, ${domainSet.size} domains`)
 
-    // Why: clearing the session's in-memory cookie store before loading imported
-    // cookies prevents stale cookies from a previous Orca browsing session from
-    // mixing with the imported set. Mixed state (some old, some imported) causes
-    // sites like Google to detect inconsistent session cookies and reject them.
+    // Why: clear stale cookies first; mixing them with the imported set makes sites like Google reject the session.
     await targetSession.clearStorageData({ storages: ['cookies'] })
     diag(
       `  cleared existing session cookies before loading ${decryptedCookies.length} imported cookies`
     )
 
-    // Why: loading cookies into memory via cookies.set() makes them available
-    // immediately without requiring a restart. The staging DB is kept as a
-    // fallback for any cookies that fail the cookies.set() validation.
+    // Why: load into memory via cookies.set() so imported cookies work without a restart.
     for (const cookie of decryptedCookies) {
       const url = deriveUrl(cookie.domain, cookie.secure)
       if (!url) {
@@ -1735,8 +1663,7 @@ export async function importCookiesFromBrowser(
         continue
       }
       try {
-        // Why: __Host- prefixed cookies must not have a domain attribute and
-        // must have path=/. Chromium rejects them otherwise.
+        // Why: Chromium rejects __Host- cookies unless they omit domain and use path=/.
         const isHostPrefixed = cookie.name.startsWith('__Host-')
         await targetSession.cookies.set({
           url,
@@ -1758,9 +1685,7 @@ export async function importCookiesFromBrowser(
     diag(`  memory load: ${memoryLoaded} OK, ${memoryFailed} failed`)
 
     if (memoryFailed > 0) {
-      // Why: some cookies couldn't be loaded via cookies.set() (non-ASCII values
-      // or other validation failures). Keep the staging DB so the next cold start
-      // picks them up from SQLite where CookieMonster reads them without validation.
+      // Why: keep the staging DB so the failed cookies load from SQLite on next cold start, where CookieMonster skips validation.
       browserSessionRegistry.setPendingCookieImport(targetPartition, stagingCookiesPath)
       diag(`  staged at ${stagingCookiesPath} for ${memoryFailed} cookies that need restart`)
     } else {
@@ -1799,8 +1724,7 @@ export async function importCookiesFromBrowser(
     } catch {
       /* may already be closed */
     }
-    // Why: if the import fails after the staging DB was created, clean it up
-    // to avoid a stale staged import being applied on the next cold start.
+    // Why: drop the staging DB so a stale staged import isn't applied on the next cold start.
     try {
       unlinkSync(stagingCookiesPath)
     } catch {
diff --git a/src/main/browser/browser-guest-ui.ts b/src/main/browser/browser-guest-ui.ts
index 1185e48d48e..997b81f4fe6 100644
--- a/src/main/browser/browser-guest-ui.ts
+++ b/src/main/browser/browser-guest-ui.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: browser guest UI policy is the single
-privileged bridge for context menus, grab-mode shortcuts, and app-shortcut
-forwarding from webContents guests. Splitting this rebase-only integration
-would make the security boundary harder to audit. */
+/* eslint-disable max-lines -- Why: single privileged bridge for guest context menus, grab-mode, and app-shortcut forwarding; splitting would blur the security boundary. */
 import { screen, webContents } from 'electron'
 import {
   normalizeBrowserNavigationUrl,
@@ -101,23 +98,15 @@ export function setupGuestContextMenu(args: {
     if (!renderer) {
       return
     }
-    // Why: redact Kagi session tokens before the URL leaves main; the renderer
-    // pipes pageUrl into clipboard writes and shell.openExternal, both of which
-    // would otherwise expose the bearer token outside Orca.
+    // Why: redact the Kagi session token before pageUrl leaves main — the renderer pipes it into clipboard and shell.openExternal.
     const pageUrl = redactKagiSessionToken(guest.getURL())
-    // Why: params.linkURL is empty when the user right-clicks non-link
-    // content. Normalizing an empty string through normalizeBrowserNavigationUrl
-    // produces the blank-page constant (a truthy string), which would trick the
-    // renderer into showing "Open Link…" items for every right-click.
+    // Why: empty linkURL normalized would yield the truthy blank-page constant, showing "Open Link…" on every non-link right-click.
     const rawLinkUrl = params.linkURL || ''
     const linkUrl =
       rawLinkUrl.length > 0
         ? (normalizeExternalBrowserUrl(rawLinkUrl) ?? normalizeBrowserNavigationUrl(rawLinkUrl))
         : null
-    // Why: send BOTH the guest viewport coordinates AND the OS screen cursor
-    // position. The renderer will try the screen cursor approach (which is
-    // immune to guest/renderer coordinate space mismatches) and fall back to
-    // guest coords if the screen API is unavailable.
+    // Why: send both viewport and screen-cursor coords; screen cursor avoids coordinate-space mismatch, guest coords are the fallback.
     const cursor = screen.getCursorScreenPoint()
     const navigationState = readGuestNavigationState(guest)
     renderer.send('browser:context-menu-requested', {
@@ -128,18 +117,13 @@ export function setupGuestContextMenu(args: {
       screenY: cursor.y,
       pageUrl,
       linkUrl,
-      // Why: forward the native selection so the renderer can offer a Copy that
-      // writes it to the clipboard directly, bypassing pages that suppress copy
-      // via oncopy handlers (the reported bug — the selection is never re-read
-      // through a page-visible copy event).
+      // Why: forward the native selection so the renderer can Copy it directly, bypassing pages that suppress copy via oncopy handlers.
       selectionText: params.selectionText ?? '',
       ...navigationState
     })
   }
 
-  // Why: `before-mouse-event` fires for every mouse event (move, down, up,
-  // scroll) on the guest. Installing the dismiss listener only while a context
-  // menu is open avoids an IPC dispatch per mouse event on idle guests.
+  // Why: before-mouse-event fires on every move/scroll; install the dismiss listener only while a menu is open to avoid per-event IPC.
   let dismissHandler: ((_event: Electron.Event, mouse: Electron.MouseInputEvent) => void) | null =
     null
 
@@ -162,10 +146,7 @@ export function setupGuestContextMenu(args: {
       if (mouse.type !== 'mouseDown') {
         return
       }
-      // Why: a right-click mouseDown will be followed by a new context-menu
-      // event with updated coordinates. Sending a dismiss here would cause
-      // the renderer to briefly close the menu (trigger snaps to 0,0) then
-      // reopen it, producing a visible flash at the top-left corner.
+      // Why: a right-click mouseDown precedes a new context-menu event; dismissing here flashes the menu closed then reopens it at 0,0.
       if (mouse.button === 'right') {
         return
       }
@@ -185,20 +166,12 @@ export function setupGuestContextMenu(args: {
       guest.off('context-menu', contextMenuHandler)
       removeDismissListener()
     } catch {
-      // Why: browser tabs can outlive the guest webContents briefly during
-      // teardown. Cleanup should be best-effort instead of throwing while the
-      // IDE is closing a tab.
+      // Why: browser tabs can briefly outlive the guest webContents during teardown, so cleanup is best-effort.
     }
   }
 }
 
-// Why: browser grab mode intentionally uses Cmd/Ctrl+C as its entry
-// gesture, but a focused webview guest is a separate Chromium process so
-// the renderer's window-level keydown handler never sees that shortcut.
-// Only forward the chord when Chromium would not perform a normal copy:
-// no editable element is focused and there is no selected text. That keeps
-// native page copy working while still making the grab shortcut reachable
-// from focused web content.
+// Why: a focused guest never surfaces Cmd/Ctrl+C to the renderer; forward only when it wouldn't do a normal copy (no editable focus, no selection).
 export function setupGrabShortcutForwarding(args: {
   browserTabId: string
   guest: Electron.WebContents
@@ -224,9 +197,7 @@ export function setupGrabShortcutForwarding(args: {
       if (!renderer) {
         return
       }
-      // Why: a focused guest swallows bare keys before the renderer sees them.
-      // While grab mode is actively awaiting a pick, plain C/S belong to Orca's
-      // copy/screenshot shortcuts rather than the page's typing behavior.
+      // Why: a focused guest swallows bare keys; during an active grab pick, plain C/S are Orca's copy/screenshot, not page typing.
       event.preventDefault()
       renderer.send('browser:grabActionShortcut', { browserPageId: browserTabId, key: bareKey })
       return
@@ -268,8 +239,7 @@ export function setupGrabShortcutForwarding(args: {
         renderer.send('browser:grabModeToggle', browserTabId)
       })
       .catch(() => {
-        // Why: shortcut forwarding is best-effort. Guest teardown or a
-        // transient executeJavaScript failure should not break normal copy.
+        // Why: shortcut forwarding is best-effort — guest teardown or a transient executeJavaScript failure must not break normal copy.
       })
   }
 
@@ -278,17 +248,12 @@ export function setupGrabShortcutForwarding(args: {
     try {
       guest.off('before-input-event', handler)
     } catch {
-      // Why: browser tabs can outlive the guest webContents briefly during
-      // teardown. Cleanup should be best-effort.
+      // Why: browser tabs can briefly outlive the guest webContents during teardown, so cleanup is best-effort.
     }
   }
 }
 
-// Why: a focused webview guest is a separate Chromium process — keyboard
-// events go to the guest's own webContents and never fire the renderer's
-// window-level keydown handler or the main window's before-input-event.
-// Intercept common app shortcuts on the guest and forward them to the
-// renderer so they work consistently regardless of which surface has focus.
+// Why: a focused webview guest is its own Chromium process whose key events never reach the renderer; forward shortcuts from here.
 export function setupGuestShortcutForwarding(args: {
   browserTabId: string
   guest: Electron.WebContents
@@ -326,8 +291,7 @@ export function setupGuestShortcutForwarding(args: {
   ): boolean => {
     const keybindings = getKeybindings?.()
     if (action?.type === 'zoom') {
-      // Why: focused browser guests own page zoom, but their key events never
-      // reach the renderer-owned webview ref that can apply Orca's page zoom.
+      // Why: focused guest key events never reach the renderer-owned webview ref that applies Orca's page zoom.
       forwardBrowserPageZoom(event, action.direction)
       return true
     }
@@ -339,12 +303,7 @@ export function setupGuestShortcutForwarding(args: {
       return false
     }
     if (action?.type === 'worktreeHistoryNavigate') {
-      // Why: preventDefault unconditionally — if we cannot resolve the
-      // renderer (torn-down tab or teardown race), dropping the keystroke
-      // into the guest's webContents would let Chromium / the guest page
-      // handle Cmd+Alt+Arrow as their own chord (e.g. guest-side text
-      // navigation). Consistency with the main-window path is preserved
-      // only by suppressing the event here too.
+      // Why: preventDefault unconditionally so the guest never handles Cmd+Alt+Arrow itself, even when the renderer can't be resolved.
       event.preventDefault()
       const renderer = resolveRenderer(browserTabId)
       renderer?.send('ui:worktreeHistoryNavigate', action.direction)
@@ -358,9 +317,7 @@ export function setupGuestShortcutForwarding(args: {
       return true
     }
 
-    // Why: match this action outside the main-process shortcut allowlist so
-    // both the fresh Shift binding and upgrading users' seeded Alt binding
-    // reach the renderer instead of the focused guest page.
+    // Why: match outside the allowlist so both the new Shift binding and upgraders' seeded Alt binding reach the renderer.
     const switchAllTypesDirection = keybindingMatchesAction(
       'tab.nextAllTypes',
       input,
@@ -385,8 +342,7 @@ export function setupGuestShortcutForwarding(args: {
       return true
     }
 
-    // Why: terminal-only tab switching defaults to Ctrl+PageUp/PageDown on every
-    // platform, but still goes through the registry so disable/rebind is real.
+    // Why: terminal-tab switching defaults to Ctrl+PageUp/PageDown but goes through the registry so disable/rebind still works.
     const terminalTabDirection = keybindingMatchesAction(
       'tab.nextTerminal',
       input,
@@ -419,45 +375,29 @@ export function setupGuestShortcutForwarding(args: {
     } else if (keybindingMatchesAction('tab.newMarkdown', input, process.platform, keybindings)) {
       renderer.send('ui:newMarkdownTab')
     } else if (keybindingMatchesAction('tab.newTerminal', input, process.platform, keybindings)) {
-      // Why: Cmd/Ctrl+T opens a terminal in the user's active terminal surface
-      // even when focus is inside a browser guest. Cmd/Ctrl+Shift+B is the
-      // dedicated shortcut for new browser tabs.
+      // Why: Cmd/Ctrl+T opens a terminal even when a browser guest is focused (Shift+B is the new-browser-tab shortcut).
       renderer.send('ui:newTerminalTab')
     } else if (
       keybindingMatchesAction('browser.focusAddressBar', input, process.platform, keybindings)
     ) {
-      // Why: the address bar lives in the renderer chrome, not the guest
-      // page. Forward Cmd/Ctrl+L out of the guest so the active BrowserPane
-      // can focus its own input just like a standalone browser would.
+      // Why: the address bar lives in renderer chrome, not the guest page; forward so the active BrowserPane can focus its input.
       renderer.send('ui:focusBrowserAddressBar')
     } else if (
       keybindingMatchesAction('browser.hardReload', input, process.platform, keybindings)
     ) {
-      // Why: Cmd/Ctrl+Shift+R is the browser convention for hard reload
-      // (bypass cache). The guest would handle it natively, but Orca's webview
-      // reloadIgnoringCache() call must come from the renderer side so it goes
-      // through the same parked-webview ref that owns the guest surface.
+      // Why: forward hard reload so reloadIgnoringCache() runs on the renderer's parked-webview ref that owns the guest surface.
       renderer.send('ui:hardReloadBrowserPage')
     } else if (keybindingMatchesAction('browser.reload', input, process.platform, keybindings)) {
-      // Why: same as above for soft reload — Cmd/Ctrl+R must be forwarded so
-      // the renderer can call reload() on its own webview ref rather than
-      // relying on the guest's built-in shortcut, which may not reach the
-      // parked-webview eviction logic.
+      // Why: forward soft reload so the renderer's reload() hits the parked-webview eviction the guest's built-in shortcut skips.
       renderer.send('ui:reloadBrowserPage')
     } else if (keybindingMatchesAction('browser.find', input, process.platform, keybindings)) {
-      // Why: Cmd/Ctrl+F must be forwarded out of the guest so the renderer can
-      // open its own find-in-page bar and call webview.findInPage(). Letting the
-      // guest handle it natively would open Chromium's built-in find UI inside
-      // the guest frame, which is invisible behind Orca's chrome.
+      // Why: guest-native find UI is invisible behind Orca's chrome; forward so the renderer opens its own find-in-page bar.
       renderer.send('ui:findInBrowserPage')
     } else if (keybindingMatchesAction('browser.back', input, process.platform, keybindings)) {
-      // Why: macOS Logitech side-button remaps arrive as browser history
-      // keystrokes, not mouse/app-command events. Forward out of the guest so
-      // the renderer-owned webview ref can call goBack().
+      // Why: macOS Logitech side-button remaps arrive as history keystrokes, not mouse events; forward so the renderer can goBack().
       renderer.send('ui:browserHistoryNavigate', 'back')
     } else if (keybindingMatchesAction('browser.forward', input, process.platform, keybindings)) {
-      // Why: same as browser.back; the focused guest cannot call the
-      // renderer-owned parked webview's goForward() path directly.
+      // Why: same as browser.back; the focused guest cannot call the renderer-owned webview's goForward() directly.
       renderer.send('ui:browserHistoryNavigate', 'forward')
     } else if (keybindingMatchesAction('tab.close', input, process.platform, keybindings)) {
       renderer.send('ui:closeActiveTab')
@@ -495,8 +435,7 @@ export function setupGuestShortcutForwarding(args: {
     } else {
       return false
     }
-    // Why: preventDefault stops the guest page from also processing the chord
-    // (e.g. Cmd+T opening a browser-internal new-tab page).
+    // Why: preventDefault stops the guest page from also processing the chord (e.g. Cmd+T opening a browser-internal new-tab page).
     event.preventDefault()
     return true
   }
@@ -552,11 +491,7 @@ export function setupGuestShortcutForwarding(args: {
     if (input.type !== 'keyDown') {
       return
     }
-    // Why: resolve the policy action once per keystroke. The history-navigate
-    // chord (Cmd/Ctrl+Alt+Arrow) is the only allowlisted chord that carries
-    // Alt and must be handled before the generic modifier-chord gate below,
-    // which rejects Alt. Every other chord handled further down can reuse
-    // the same `action` rather than re-running the full predicate chain.
+    // Why: Cmd/Ctrl+Alt+Arrow is the only allowlisted chord carrying Alt, so resolve it before the Alt-rejecting chord gate below.
     const action = resolveWindowShortcutAction(input, process.platform, keybindings)
     forwardShortcutInput(event, input, action)
   }
@@ -568,8 +503,7 @@ export function setupGuestShortcutForwarding(args: {
     if (zoomDirection !== 'in' && zoomDirection !== 'out') {
       return
     }
-    // Why: some keyboard layouts/platforms turn Ctrl/Cmd +/- into Electron's
-    // native zoom command before `before-input-event` reaches the guest.
+    // Why: some layouts/platforms turn Ctrl/Cmd +/- into Electron's native zoom before before-input-event reaches the guest.
     if (consumeRecentGuestWheelZoom(guest, zoomDirection)) {
       event.preventDefault()
       return
@@ -605,8 +539,7 @@ export function setupGuestMouseWheelZoomForwarding(args: {
     if (!direction) {
       return
     }
-    // Why: wheel input over a focused webview does not reach renderer DOM
-    // handlers, so consume it here and forward to the existing page-zoom path.
+    // Why: wheel input over a focused webview never reaches renderer DOM handlers, so consume and forward here.
     event.preventDefault()
     markGuestWheelZoom(guest, direction)
     resolveRenderer(browserTabId)?.send('ui:zoomBrowserPage', direction)
diff --git a/src/main/browser/browser-manager.ts b/src/main/browser/browser-manager.ts
index 33104ad9f7d..bd0e5698cd8 100644
--- a/src/main/browser/browser-manager.ts
+++ b/src/main/browser/browser-manager.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: BrowserManager intentionally remains the
-single privileged facade for guest registration, authorization, and lifecycle
-cleanup even after extracting the grab/session helpers. Keeping that ownership
-in one file avoids scattering the browser security boundary across modules. */
+/* eslint-disable max-lines -- Why: single privileged facade for guest registration, authorization, and lifecycle cleanup; keeps the browser security boundary in one file. */
 import { randomUUID } from 'node:crypto'
 
 import { shell, webContents } from 'electron'
@@ -108,9 +105,7 @@ function cleanupLateAutomationVisibilityToken(
       if (typeof lateToken !== 'string' || lateToken.length === 0) {
         return
       }
-      // Why: the renderer creates the lease before waiting for paint; if main's
-      // acquire timeout wins, release the eventual token so hidden webviews do
-      // not stay paintable indefinitely.
+      // Why: the lease is created before paint; if main's acquire timed out, release the late token so hidden webviews don't stay paintable.
       releaseAutomationVisibilityToken(renderer, lateToken)
     })
     .catch(() => {})
@@ -131,10 +126,7 @@ function isAutomationVisibilityToken(token: unknown): token is string {
   return typeof token === 'string' && token.length > 0
 }
 
-// Why: mobile presets need a touch-capable UA or responsive sites serve the
-// desktop variant based on UA sniffing. This is the Chrome DevTools default
-// iPhone UA template; we splice in the guest session's real Chrome major so
-// sec-ch-ua headers (see setupClientHintsOverride) stay consistent.
+// Why: responsive sites UA-sniff; this is Chrome DevTools' default iPhone UA template with the real Chrome major spliced in to keep sec-ch-ua consistent (see setupClientHintsOverride).
 function buildMobileUserAgent(chromeMajor: string): string {
   return `Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/${chromeMajor}.0.0.0 Mobile/15E148 Safari/604.1`
 }
@@ -176,9 +168,7 @@ const SAFE_POPUP_WINDOW_OPTIONS = {
   skipTaskbar: false,
   titleBarStyle: 'default',
   transparent: false,
-  // Why: applied by Electron when it creates the popup's WebContents, before
-  // createWindow runs. Feature strings and opener inheritance must not be able
-  // to relax the child's process isolation.
+  // Why: Electron applies these before createWindow; feature strings/opener inheritance must not relax the child's isolation.
   webPreferences: {
     allowRunningInsecureContent: false,
     contextIsolation: true,
@@ -226,20 +216,14 @@ export class BrowserManager {
       })
     | null = null
   private readonly webContentsIdByTabId = new Map<string, number>()
-  // Why: reverse map enables O(1) guest→tab lookups instead of O(N) linear
-  // scans on every mouse event, load failure, permission, and popup event.
+  // Why: reverse map gives O(1) guest→tab lookups on every mouse/load/permission/popup event.
   private readonly tabIdByWebContentsId = new Map<number, string>()
   private readonly popupOwnerContextByGuestId = new Map<number, PopupOwnerContext>()
-  // Why: guest registration is keyed by browser page id, but renderer
-  // visibility/focus state is keyed by browser workspace id. Screenshot prep
-  // has to bridge that mismatch to activate the right tab before capture.
+  // Why: guests are keyed by page id but renderer visibility by workspace id; bridge the mismatch to activate the right tab before capture.
   private readonly workspaceIdByPageId = new Map<string, string>()
   private readonly sessionProfileIdByPageId = new Map<string, string | null>()
   private readonly rendererWebContentsIdByTabId = new Map<string, number>()
-  // Why: chain setViewportOverride calls per tab so rapid toggles don't
-  // interleave CDP commands. Without serialization, two concurrent calls can
-  // race (e.g. clearDeviceMetricsOverride landing after a later mobile
-  // setDeviceMetricsOverride), leaving emulation in an unexpected state.
+  // Why: serialize per-tab setViewportOverride so rapid toggles don't interleave CDP commands and leave emulation in a wrong state.
   private readonly viewportOpsByTabId = new Map<string, Promise<unknown>>()
   private readonly contextMenuCleanupByTabId = new Map<string, () => void>()
   private readonly grabShortcutCleanupByTabId = new Map<string, () => void>()
@@ -252,9 +236,7 @@ export class BrowserManager {
   private readonly policyCleanupByGuestId = new Map<number, () => void>()
   private readonly clickedLinkFrameNameByGuestId = new Map<number, string>()
   private readonly loadErrorsByGuestId = new Map<number, BrowserLoadError>()
-  // Why: did-start-navigation optimistically hides the overlay, but an aborted
-  // nav never commits — stash the cleared error so did-fail-load(-3) can restore
-  // it instead of stranding the user on a blank surface.
+  // Why: did-start-navigation hides the overlay optimistically; stash the cleared error so did-fail-load(-3) can restore an aborted nav.
   private readonly clearedLoadErrorsByGuestId = new Map<number, BrowserLoadError>()
   private browserGuestStateChangedListener: ((worktreeId: string) => void) | null = null
   private certificateTrustController: BrowserCertificateTrustController | null = null
@@ -298,14 +280,7 @@ export class BrowserManager {
     this.settingsResolver = resolver
   }
 
-  // Why: Page.addScriptToEvaluateOnNewDocument (via the CDP debugger) is the
-  // only reliable way to run JS before page scripts on every navigation.
-  // The previous approach — executeJavaScript on did-start-navigation — ran
-  // on the OLD page context during navigation, so overrides were never
-  // present when the new page's Turnstile script executed.
-  //
-  // Returns a cleanup function that removes the detach listener and prevents
-  // further re-attach attempts.
+  // Why: addScriptToEvaluateOnNewDocument (CDP) is the only reliable pre-page-script hook per nav; executeJavaScript ran on the old page context.
   private injectAntiDetection(guest: Electron.WebContents): () => void {
     let disposed = false
     let reattachTimer: ReturnType<typeof setTimeout> | null = null
@@ -331,11 +306,7 @@ export class BrowserManager {
       }
     }
 
-    // Why: the CDP proxy and bridge detach the debugger when they stop,
-    // which removes addScriptToEvaluateOnNewDocument injections. Re-attach
-    // so manual browsing retains anti-detection overrides after agent
-    // sessions end. The 500ms delay avoids racing with the proxy/bridge if
-    // it is mid-restart (detach → re-attach).
+    // Why: proxy/bridge stop detaches the debugger and drops injections; re-attach (500ms delay to avoid racing a mid-restart) to keep overrides.
     const onDetach = (): void => {
       if (!disposed && !guest.isDestroyed() && reattachTimer === null) {
         reattachTimer = setTimeout(() => {
@@ -398,10 +369,7 @@ export class BrowserManager {
     return renderer
   }
 
-  // Why: screenshot sessions target guest page ids, but Orca's visible browser
-  // chrome is keyed by workspace ids. If we activate the page id directly, the
-  // webview stays hidden under the terminal pane and Page.captureScreenshot
-  // times out even though the guest still exists.
+  // Why: screenshots target page ids but visible chrome is keyed by workspace id; activate by workspace or the webview stays hidden and capture times out.
   async ensureWebviewVisible(guestWebContentsId: number): Promise<() => void> {
     const browserPageId = this.resolveBrowserTabIdForGuestWebContentsId(guestWebContentsId)
     if (!browserPageId) {
@@ -622,8 +590,7 @@ export class BrowserManager {
       return () => {}
     }
 
-    // Why: agent browser commands need a paintable webview for lazy-loading
-    // sites, but must not steal the user's visible Orca tab/worktree.
+    // Why: agent commands need a paintable webview for lazy-loading sites without stealing the user's visible tab.
     const acquirePromise = renderer
       .executeJavaScript(
         `(async function() {
@@ -659,8 +626,7 @@ export class BrowserManager {
     if (inheritedOwnerContext) {
       this.popupOwnerContextByGuestId.set(guest.id, inheritedOwnerContext)
     }
-    // Why: OAuth child windows must retain normal link/window relationships;
-    // only the primary embedded browser converts new-tab clicks to Orca tabs.
+    // Why: only the primary embedded browser converts new-tab clicks to Orca tabs; OAuth child windows keep native link behavior.
     const clickedLinkFrameName = inheritedOwnerContext
       ? null
       : `__orca_clicked_link_foreground_${randomUUID()}`
@@ -669,30 +635,22 @@ export class BrowserManager {
     }
     let clickedLinkRoutingActive = Boolean(clickedLinkFrameName)
 
-    // Why: Cloudflare Turnstile and similar bot detectors probe browser APIs
-    // (navigator.webdriver, plugins, window.chrome) that differ in Electron
-    // webviews vs real Chrome. Inject overrides on every page load so manual
-    // browsing passes challenges even without the CDP debugger attached.
+    // Why: bot detectors probe APIs that differ in Electron webviews; inject overrides each load so manual browsing passes.
     const disposeAntiDetection = this.injectAntiDetection(guest)
 
-    // Why: background throttling must be disabled so agent-driven screenshots
-    // (Page.captureScreenshot via CDP proxy) can capture frames even when the
-    // Orca window is not the focused foreground app. With throttling enabled,
-    // the compositor stops producing frames and capturePage() returns empty.
+    // Why: disable throttling so background screenshots still get frames; else the compositor stalls and capture returns empty.
     guest.setBackgroundThrottling(false)
     const installClickedLinkRouting = (): void => {
       if (!clickedLinkRoutingActive || !clickedLinkFrameName || guest.isDestroyed()) {
         return
       }
-      // Why: an isolated-world click listener can label real anchor clicks
-      // without exposing the private frame name to untrusted page scripts.
+      // Why: an isolated-world listener labels real anchor clicks without exposing the frame name to page scripts.
       void guest
         .executeJavaScriptInIsolatedWorld(
           BROWSER_CLICKED_LINK_ROUTING_WORLD_ID,
           [
             {
-              // Why: mobile emulation spoofs the guest UA as iOS, so modifier
-              // routing must use the actual desktop host platform from main.
+              // Why: mobile emulation spoofs the UA as iOS, so use the real host platform from main for modifier routing.
               code: buildBrowserClickedLinkRoutingScript(
                 clickedLinkFrameName,
                 process.platform === 'darwin'
@@ -725,8 +683,7 @@ export class BrowserManager {
       const name = `__orca_clicked_link_iframe_foreground_${randomUUID()}`
       iframeFrameNameByFrame.set(frame, name)
       iframeFrameByFrameName.set(name, frame)
-      // Why: child-frame tokens live in the page world, so they are consumed
-      // after one trusted click and replaced before another can be routed.
+      // Why: child-frame tokens live in the page world, so consume after one trusted click and replace before the next.
       void frame
         .executeJavaScript(
           buildBrowserIframeClickedLinkRoutingScript(name, process.platform === 'darwin'),
@@ -761,8 +718,7 @@ export class BrowserManager {
       guest.on('frame-created', handleFrameCreated)
     }
     const handleDidCreateWindow = (window: Electron.BrowserWindow): void => {
-      // Why: popup descendants inherit the opener's owner context for routing,
-      // but must not replace its primary guest registration.
+      // Why: popup descendants inherit the opener's owner context but must not replace its primary registration.
       this.attachGuestPolicies(window.webContents, this.resolvePopupOwnerContext(guest.id))
     }
     guest.on('did-create-window', handleDidCreateWindow)
@@ -788,39 +744,30 @@ export class BrowserManager {
             action: 'opened-in-orca'
           })
         }
-        // Why: a recognized user gesture must never fall through to a native
-        // popup merely because its renderer disappeared during the click.
+        // Why: a recognized gesture must never fall through to a native popup if its renderer vanished mid-click.
         return { action: 'deny' }
       }
 
-      // Why: file URLs are valid for user-opened in-pane previews, but remote
-      // content must not create native child windows targeting local paths.
+      // Why: file URLs are fine for in-pane previews, but must not spawn native child windows targeting local paths.
       const canOpenAsChild = Boolean(externalUrl || browserUrl === ORCA_BROWSER_BLANK_URL)
       if (browserTabId && canOpenAsChild) {
-        // Why: OAuth may request ordinary size/position features, but browser
-        // content must not create deceptive or inescapable native chrome.
+        // Why: OAuth may request size/position, but content must not create deceptive or inescapable native chrome.
         return {
           action: 'allow',
           overrideBrowserWindowOptions: SAFE_POPUP_WINDOW_OPTIONS,
-          // Why: a default child window has no address bar, so users cannot
-          // verify a popup's destination. Host it in an Orca window with an
-          // origin bar while keeping the shared session + window.opener.
+          // Why: default child windows lack an address bar; host in an Orca origin-bar window so the destination is verifiable.
           createWindow: (options: PopupChildWindowOptions) =>
             this.createPopupChildWindowWithOriginBar(guest, url, options)
         }
       } else if (externalUrl) {
-        // Why: a target=_blank click on a Kagi search result page produces a
-        // popup URL that still contains the bearer token; redact before
-        // handing the URL to the OS default browser.
+        // Why: Kagi target=_blank popup URLs still contain the bearer token; redact before handing to the OS browser.
         void shell.openExternal(redactKagiSessionToken(externalUrl))
         this.forwardOrQueuePopupEvent(guest.id, {
           origin: safeOrigin(externalUrl),
           action: 'opened-external'
         })
       } else {
-        // Why: popup attempts can carry auth redirects and one-time tokens.
-        // Surface only sanitized origin metadata so the renderer can explain
-        // the blocked action without persisting sensitive URL details.
+        // Why: popup URLs can carry auth redirects/one-time tokens; surface only sanitized origin metadata.
         this.forwardOrQueuePopupEvent(guest.id, {
           origin: safeOrigin(url),
           action: 'blocked'
@@ -830,26 +777,17 @@ export class BrowserManager {
     })
 
     const navigationGuard = (event: Electron.Event, url: string): void => {
-      // Why: blob: URLs are same-origin (inherit the creator's origin) and are
-      // used by Cloudflare Turnstile to load challenge resources inside iframes.
-      // Blocking them triggers error 600010 ("bot behavior detected"). Only
-      // allow blobs whose embedded origin is http(s) to maintain defense-in-depth
-      // against blob:null or other opaque-origin blobs.
+      // Why: Turnstile loads challenge resources via blob:; blocking them trips error 600010. Allow only http(s) blobs, not opaque ones.
       if (url.startsWith('blob:https://') || url.startsWith('blob:http://')) {
         return
       }
-      // Why: file:// is permitted at `will-attach-webview` so the preview pane
-      // can render local HTML the user explicitly opened. After that initial
-      // load, a page must not be able to redirect the guest to file:// — that
-      // would let a remote page probe the local filesystem. Keep the in-guest
-      // navigation guard strict even though initial attach is permissive.
+      // Why: initial file:// attach is allowed for user-opened previews, but block later file:// redirects so remote pages can't probe the FS.
       if (url.startsWith('file:')) {
         event.preventDefault()
         return
       }
       if (!normalizeBrowserNavigationUrl(url)) {
-        // Why: `will-attach-webview` only validates the initial src. Main must
-        // keep enforcing the same allowlist for later guest navigations too.
+        // Why: will-attach-webview only validates the initial src; keep enforcing the allowlist on later navs.
         event.preventDefault()
       }
     }
@@ -873,14 +811,11 @@ export class BrowserManager {
         toSecureCertificateEndpoint(validatedURL || guest.getURL()) ===
           toSecureCertificateEndpoint(certificateFailure.origin)
       ) {
-        // Why: a request-guard cancellation is the transport for the existing
-        // certificate warning; do not replace it with ERR_ABORTED/blocked copy.
+        // Why: this cancellation carries the existing cert warning; don't overwrite it with ERR_ABORTED copy.
         return
       }
       if (errorCode === -3) {
-        // Why: an aborted main-frame nav never committed, so restore the error
-        // did-start-navigation optimistically cleared — otherwise a retry that
-        // aborts leaves the failed page with no overlay.
+        // Why: an aborted nav never committed; restore the error did-start-navigation cleared so it isn't lost.
         const clearedError = this.clearedLoadErrorsByGuestId.get(guest.id)
         if (clearedError !== undefined) {
           this.clearedLoadErrorsByGuestId.delete(guest.id)
@@ -911,14 +846,11 @@ export class BrowserManager {
         return
       }
       this.certificateTrustController?.onMainFrameNavigationStarted(guest.id)
-      // Why: a failure queued before renderer registration belongs only to the
-      // navigation that produced it. A replacement navigation must not replay
-      // that stale failure when its later dom-ready registers the guest.
+      // Why: a pre-registration failure belongs only to its own nav; a replacement nav must not replay it.
       this.pendingLoadFailuresByGuestId.delete(guest.id)
       const activeError = this.loadErrorsByGuestId.get(guest.id)
       if (activeError === undefined) {
-        // Why: no error to hide; drop any stale stash so a later abort cannot
-        // resurrect an error from a navigation that already succeeded.
+        // Why: no error to hide; drop any stale stash so a later abort can't resurrect an old failure.
         this.clearedLoadErrorsByGuestId.delete(guest.id)
         return
       }
@@ -928,9 +860,7 @@ export class BrowserManager {
     }
 
     const didNavigateHandler = (_event: Electron.Event, url: string): void => {
-      // Why: a committed navigation means the optimistic stash from
-      // did-start-navigation is obsolete — drop it so a later ERR_ABORTED
-      // cannot restore a failure over the already-committed page.
+      // Why: a committed nav makes the did-start-navigation stash obsolete; drop it so a later ERR_ABORTED can't restore an error over it.
       this.clearedLoadErrorsByGuestId.delete(guest.id)
       this.certificateTrustController?.onMainFrameNavigationCommitted(guest.id, url)
     }
@@ -941,15 +871,12 @@ export class BrowserManager {
     guest.on('did-navigate', didNavigateHandler)
     guest.on('did-fail-load', didFailLoadHandler)
     const handleDestroyed = (): void => {
-      // Why: guests can be destroyed before renderer registration. Without
-      // this, attach-time policy closures remain retained until app shutdown.
+      // Why: guests can die before renderer registration, else attach-time closures leak until shutdown.
       this.cleanupGuestPolicyAttachment(guest.id)
     }
     guest.on('destroyed', handleDestroyed)
 
-    // Why: store cleanup so unregisterGuest can remove these listeners when the
-    // guest surface is torn down, preventing the callbacks from preventing GC of
-    // the underlying WebContents wrapper.
+    // Why: store cleanup so unregisterGuest can drop these listeners on teardown and let the WebContents wrapper GC.
     this.policyCleanupByGuestId.set(guest.id, () => {
       disposeAntiDetection()
       try {
@@ -987,8 +914,7 @@ export class BrowserManager {
     options: PopupChildWindowOptions
   ): Electron.WebContents {
     const popup = openPopupWithOriginBar(options, targetUrl)
-    // Why: Electron does not emit did-create-window for createWindow-created
-    // children, so the opener's policies and routing context attach here.
+    // Why: Electron emits no did-create-window for createWindow children, so attach the opener's policies here.
     this.attachGuestPolicies(
       popup.contentWebContents,
       this.resolvePopupOwnerContext(openerGuest.id)
@@ -997,8 +923,7 @@ export class BrowserManager {
       origin: safeOrigin(targetUrl),
       action: 'opened-in-orca'
     })
-    // Why: parity with Electron's default child-window lifecycle — closing the
-    // owning browser tab must not leave orphaned session-bearing popups.
+    // Why: match Electron's child-window lifecycle so closing the owning tab doesn't orphan session-bearing popups.
     const closePopupWithOpener = (): void => popup.close()
     openerGuest.once('destroyed', closePopupWithOpener)
     popup.onClosed(() => {
@@ -1010,10 +935,7 @@ export class BrowserManager {
   }
 
   private retireStaleGuestWebContents(previousWebContentsId: number): void {
-    // Why: a browser page can re-register with a new guest id after Chromium
-    // swaps renderer processes. Late events from the dead guest must stop
-    // resolving to the live page, or stale download/popup/permission callbacks
-    // can be delivered to the wrong session after the swap.
+    // Why: after a renderer-process swap, stop the dead guest id resolving to the live page so stale callbacks don't hit the wrong session.
     this.cleanupGuestPolicyAttachment(previousWebContentsId)
     this.tabIdByWebContentsId.delete(previousWebContentsId)
   }
@@ -1030,8 +952,7 @@ export class BrowserManager {
     this.clickedLinkFrameNameByGuestId.delete(guestWebContentsId)
     this.offscreenGuestIds.delete(guestWebContentsId)
     this.popupOwnerContextByGuestId.delete(guestWebContentsId)
-    // Why: a popup must stop inheriting authorization as soon as its primary
-    // owner is retired, even if Chromium has not destroyed the child yet.
+    // Why: a popup must stop inheriting authorization the moment its owner retires, before Chromium destroys the child.
     if (isPrimaryGuest) {
       for (const [popupGuestId, owner] of this.popupOwnerContextByGuestId) {
         if (owner.rootGuestWebContentsId === guestWebContentsId) {
@@ -1060,10 +981,7 @@ export class BrowserManager {
     if (!browserTabId) {
       return false
     }
-    // Why: re-registering the same browser tab can happen when Chromium swaps
-    // or recreates the underlying guest surface. Any active grab is bound to
-    // the old guest's listeners and teardown path, so keeping it alive would
-    // leave the session attached to a stale webContents until timeout.
+    // Why: on guest-surface swap, cancel any grab bound to the old guest's listeners so it doesn't strand on a stale webContents.
     this.cancelGrabOp(browserTabId, 'evicted')
 
     const previousCleanup = this.contextMenuCleanupByTabId.get(browserTabId)
@@ -1077,18 +995,12 @@ export class BrowserManager {
       return false
     }
 
-    // Why: the renderer sends webContentsId, which we must not blindly trust.
-    // A compromised renderer could send the main window's own webContentsId,
-    // causing us to overwrite its setWindowOpenHandler or attach unintended
-    // context menus. Only accept genuine webview guest surfaces.
+    // Why: don't trust the renderer-sent id blindly — a compromised renderer could pass the main window's id; only accept webview guests.
     if (guest.getType() !== 'webview') {
       return false
     }
     if (!this.policyAttachedGuestIds.has(webContentsId)) {
-      // Why: renderer registration is only the second half of the guest setup.
-      // Main must only trust guests that already passed attach-time policy
-      // installation; otherwise a trusted renderer could point us at some other
-      // arbitrary webview and bypass the intended host-window attach boundary.
+      // Why: only trust guests that passed attach-time policy install, or a renderer could point us at an arbitrary webview.
       return false
     }
 
@@ -1120,14 +1032,10 @@ export class BrowserManager {
   }
 
   unregisterGuest(browserTabId: string): void {
-    // Why: unregistering a guest while a grab is active means the guest is
-    // being torn down. Cancel the grab so the renderer gets a clean signal
-    // instead of a dangling Promise.
+    // Why: teardown mid-grab must cancel it so the renderer gets a signal, not a dangling Promise.
     this.cancelGrabOp(browserTabId, 'evicted')
 
-    // Why: remove the policy listeners attached in attachGuestPolicies so the
-    // callbacks (which close over the guest WebContents) do not prevent GC of
-    // the underlying Chromium surface after the guest is destroyed.
+    // Why: remove attachGuestPolicies listeners so their guest-WebContents closures don't block GC.
     const guestWebContentsId = this.webContentsIdByTabId.get(browserTabId)
     if (guestWebContentsId !== undefined) {
       this.cleanupGuestPolicyAttachment(guestWebContentsId)
@@ -1153,8 +1061,7 @@ export class BrowserManager {
       mouseWheelZoomCleanup()
       this.mouseWheelZoomCleanupByTabId.delete(browserTabId)
     }
-    // Why: browser downloads are transient per-tab chrome. Closing the owning
-    // tab must cancel active writes instead of hiding them behind no UI.
+    // Why: downloads are per-tab chrome; closing the tab must cancel active writes, not orphan them.
     for (const [downloadId, download] of this.downloadsById.entries()) {
       if (download.browserTabId === browserTabId && !download.terminalEvent) {
         this.cancelDownloadInternal(downloadId, 'Tab closed before download completed.')
@@ -1169,17 +1076,12 @@ export class BrowserManager {
     this.workspaceIdByPageId.delete(browserTabId)
     this.sessionProfileIdByPageId.delete(browserTabId)
     this.worktreeIdByTabId.delete(browserTabId)
-    // Why: drop any pending viewport-op chain for this tab so the Map doesn't
-    // retain a resolved promise keyed to a destroyed guest.
+    // Why: drop the viewport-op chain so the Map doesn't retain a promise keyed to a destroyed guest.
     this.viewportOpsByTabId.delete(browserTabId)
     this.annotationViewportBridgeOpsByTabId.delete(browserTabId)
   }
 
-  // Why: headless orca serve has no renderer window to mount a <webview>, so its
-  // browser pages are backed by main-process offscreen WebContents instead. This
-  // registers such a page into the same resolution maps the bridge/screencast/
-  // input handlers read, but skips the webview-only guards and the renderer setup
-  // (context menu, grab shortcut, etc.) that assume a renderer-hosted guest.
+  // Why: headless orca serve has no <webview> window; back pages with offscreen WebContents and skip the webview-only setup.
   registerOffscreenGuest({
     browserPageId,
     worktreeId,
@@ -1195,8 +1097,7 @@ export class BrowserManager {
     if (!guest || guest.isDestroyed()) {
       return
     }
-    // Why: offscreen pages have no renderer webview listeners, so main owns
-    // their load-failure lifecycle for remote browser chrome.
+    // Why: offscreen pages have no renderer webview listeners, so main owns their load-failure lifecycle.
     this.offscreenGuestIds.add(webContentsId)
     this.attachGuestPolicies(guest)
     const previousWebContentsId = this.webContentsIdByTabId.get(browserPageId)
@@ -1224,10 +1125,7 @@ export class BrowserManager {
     }
     this.policyAttachedGuestIds.clear()
     this.offscreenGuestIds.clear()
-    // Why: unregisterGuest only cleans up guests that were registered (have an
-    // entry in webContentsIdByTabId). Guests that went through
-    // attachGuestPolicies but were never registered still have cleanup closures
-    // here — invoke them so their event listeners are removed before clearing.
+    // Why: unregisterGuest skips guests that were policy-attached but never registered; invoke their cleanup closures here.
     for (const cleanup of this.policyCleanupByGuestId.values()) {
       cleanup()
     }
@@ -1299,9 +1197,7 @@ export class BrowserManager {
     }
   }
 
-  // Why: both the did-fail-load path and the synthesized certificate failure
-  // build a load error from an untrusted URL; centralize the redaction so a
-  // future third site cannot forget to strip Kagi session tokens.
+  // Why: centralize Kagi session-token redaction so every load-error path (did-fail-load, cert failure) strips it.
   private buildLoadError(code: number, description: string, rawUrl: string): BrowserLoadError {
     return {
       code,
@@ -1339,9 +1235,7 @@ export class BrowserManager {
     const browserPageId = this.tabIdByWebContentsId.get(webContentsId)
     const worktreeId = browserPageId ? this.worktreeIdByTabId.get(browserPageId) : null
     if (worktreeId) {
-      // Why: this runs inside an Electron guest event dispatch; the listener
-      // synchronously reconciles mobile-session tabs, and an escaping throw would
-      // become a fatal uncaught exception (no catch-all main-process guard).
+      // Why: runs inside an Electron guest event dispatch, so an escaping throw would be a fatal uncaught exception.
       try {
         this.browserGuestStateChangedListener?.(worktreeId)
       } catch (error) {
@@ -1440,8 +1334,7 @@ export class BrowserManager {
       try {
         item.cancel()
       } catch {
-        // Why: without a destination, Chromium must not keep writing invisibly;
-        // cancellation remains best-effort after surfacing the failure.
+        // Why: with no destination Chromium must not keep writing invisibly; cancel is best-effort after surfacing the failure.
       }
       return
     }
@@ -1454,8 +1347,7 @@ export class BrowserManager {
       try {
         item.cancel()
       } catch {
-        // Why: failing setSavePath can leave Electron in a partially finalized
-        // state; cancellation is best-effort after Orca has made the UI terminal.
+        // Why: a failed setSavePath can leave Electron partially finalized; cancel is best-effort after the UI is made terminal.
       }
       return
     }
@@ -1489,8 +1381,7 @@ export class BrowserManager {
         download.item.off('updated', updatedHandler)
         download.item.off('done', doneHandler)
       } catch {
-        // Why: completed DownloadItems can already be finalized when cleanup
-        // runs. Cleanup must stay best-effort so UI teardown never crashes main.
+        // Why: a completed DownloadItem may already be finalized; keep cleanup best-effort so teardown never crashes main.
       }
     }
     item.on('updated', updatedHandler)
@@ -1510,9 +1401,7 @@ export class BrowserManager {
     return true
   }
 
-  // Why: guest browser surfaces are intentionally isolated from Orca's preload
-  // bridge, so renderer code cannot directly call Electron WebContents APIs on
-  // them. Main owns the devtools escape hatch and only after tab→guest lookup.
+  // Why: guests are isolated from Orca's preload bridge, so main owns the devtools escape hatch after a tab→guest lookup.
   async openDevTools(browserTabId: string): Promise<boolean> {
     const webContentsId = this.webContentsIdByTabId.get(browserTabId)
     if (!webContentsId) {
@@ -1520,8 +1409,7 @@ export class BrowserManager {
     }
     const guest = webContents.fromId(webContentsId)
     if (!guest || guest.isDestroyed()) {
-      // Why: stale guest discovery must clear every per-tab registry entry,
-      // not just the forward/reverse WebContents maps.
+      // Why: a stale guest must clear every per-tab registry entry, not just the WebContents maps.
       this.unregisterGuest(browserTabId)
       return false
     }
@@ -1529,20 +1417,12 @@ export class BrowserManager {
     return true
   }
 
-  // Why: Electron <webview> guests do not expose Chrome DevTools' device
-  // toolbar (Cmd+Shift+M) to the embedding app, so viewport emulation must be
-  // driven through CDP directly. We reuse the debugger attachment that
-  // injectAntiDetection already established and never detach it here — doing
-  // so would clear Page.addScriptToEvaluateOnNewDocument and other per-guest
-  // overrides. Passing override=null clears emulation.
+  // Why: emulate viewport via CDP; never detach the debugger here or per-guest overrides (addScriptToEvaluateOnNewDocument) are cleared.
   async setViewportOverride(
     browserTabId: string,
     override: BrowserViewportOverride | null
   ): Promise<boolean> {
-    // Why: chain per-tab so rapid toggles (e.g. user clicking presets quickly)
-    // don't interleave CDP commands. Each call waits for the previous one to
-    // settle, guaranteeing the last-requested override wins rather than whichever
-    // sendCommand sequence happens to finish last.
+    // Why: chain per-tab so rapid toggles don't interleave CDP commands and the last-requested override wins.
     const prev = this.viewportOpsByTabId.get(browserTabId) ?? Promise.resolve()
     const next = prev
       .catch(() => {})
@@ -1551,9 +1431,7 @@ export class BrowserManager {
     try {
       return await next
     } finally {
-      // Why: only clear if this call's promise is still the tail. A concurrent
-      // later call may have already replaced the entry; deleting would drop the
-      // chain and break serialization for the next invocation.
+      // Why: only clear if we're still the tail; a later call may have replaced the entry, and deleting would break serialization.
       if (this.viewportOpsByTabId.get(browserTabId) === next) {
         this.viewportOpsByTabId.delete(browserTabId)
       }
@@ -1588,15 +1466,13 @@ export class BrowserManager {
     }
     const guest = webContents.fromId(webContentsId)
     if (!guest || guest.isDestroyed()) {
-      // Why: stale guest discovery must clear every per-tab registry entry,
-      // not just the forward/reverse WebContents maps.
+      // Why: a stale guest must clear every per-tab registry entry, not just the WebContents maps.
       this.unregisterGuest(browserTabId)
       return false
     }
 
     try {
-      // Why: the scroll bridge runs outside the page world so page monkey
-      // patches cannot read the per-tab token or tamper with bridge state.
+      // Why: run the scroll bridge in an isolated world so page scripts can't read the per-tab token or tamper with it.
       await guest.executeJavaScriptInIsolatedWorld(
         BROWSER_ANNOTATION_VIEWPORT_BRIDGE_WORLD_ID,
         [{ code: buildBrowserAnnotationViewportBridgeScript(options) }],
@@ -1618,8 +1494,7 @@ export class BrowserManager {
     }
     const guest = webContents.fromId(webContentsId)
     if (!guest || guest.isDestroyed()) {
-      // Why: stale guest discovery must clear every per-tab registry entry,
-      // not just the forward/reverse WebContents maps.
+      // Why: a stale guest must clear every per-tab registry entry, not just the WebContents maps.
       this.unregisterGuest(browserTabId)
       return false
     }
@@ -1629,10 +1504,7 @@ export class BrowserManager {
         guest.debugger.attach('1.3')
       }
     } catch (err) {
-      // Why: DevTools being open on the guest causes attach to throw with
-      // "Another debugger is already attached". Silently returning false made
-      // this failure mode undiagnosable — surface it via the logger with enough
-      // context (tab + webContents ids) to correlate with user reports.
+      // Why: attach throws if DevTools is open on the guest; log context so this failure mode is diagnosable.
       console.warn('[browser-manager] setViewportOverride: failed to attach debugger', {
         browserTabId,
         webContentsId,
@@ -1656,10 +1528,7 @@ export class BrowserManager {
         })
         if (override.mobile) {
           const chromeMajor = extractChromeMajor(cleanElectronUserAgent(guest.getUserAgent()))
-          // Why: pass userAgentMetadata alongside the mobile UA string so
-          // sec-ch-ua-mobile / sec-ch-ua-platform client hints match. Without
-          // it, session-level desktop client-hints leak through and create a
-          // UA/CH mismatch that bot-detection (Cloudflare, Turnstile) flags.
+          // Why: userAgentMetadata must accompany the mobile UA so client hints match, or bot-detection flags the desktop-hint leak.
           await dbg.sendCommand('Emulation.setUserAgentOverride', {
             userAgent: buildMobileUserAgent(chromeMajor),
             userAgentMetadata: {
@@ -1682,9 +1551,7 @@ export class BrowserManager {
             }
           })
         } else {
-          // Why: desktop presets still need the clean (non-Electron) UA so
-          // Cloudflare/Turnstile don't flag the session. Passing the cleaned
-          // real UA keeps sec-ch-ua consistent with the override.
+          // Why: desktop presets still need the clean (non-Electron) UA so Cloudflare/Turnstile don't flag the session.
           await dbg.sendCommand('Emulation.setUserAgentOverride', {
             userAgent: cleanElectronUserAgent(guest.getUserAgent())
           })
@@ -1704,14 +1571,9 @@ export class BrowserManager {
     }
   }
 
-  // ---------------------------------------------------------------------------
-  // Browser Context Grab — main-owned operations
-  // ---------------------------------------------------------------------------
+  // --- Browser Context Grab — main-owned operations ---
 
-  /**
-   * Validates that a caller (identified by sender webContentsId) owns the
-   * given browserTabId. Returns the guest WebContents or null.
-   */
+  /** Validate that the sender owns browserTabId; returns the guest WebContents or null. */
   getAuthorizedGuest(
     browserTabId: string,
     senderWebContentsId: number
@@ -1726,8 +1588,7 @@ export class BrowserManager {
     }
     const guest = webContents.fromId(guestId)
     if (!guest || guest.isDestroyed()) {
-      // Why: stale guest discovery must clear every per-tab registry entry,
-      // not just the forward/reverse WebContents maps.
+      // Why: a stale guest must clear every per-tab registry entry, not just the WebContents maps.
       this.unregisterGuest(browserTabId)
       return null
     }
@@ -1739,10 +1600,7 @@ export class BrowserManager {
     return this.grabSessionController.hasActiveGrabOp(browserTabId)
   }
 
-  /**
-   * Enable or disable grab mode for a browser tab. When enabled, injects the
-   * overlay runtime into the guest. When disabled, cancels any active grab op.
-   */
+  /** Enable/disable grab mode for a tab: on enable inject the overlay runtime, on disable cancel any active grab op. */
   async setGrabMode(
     browserTabId: string,
     enabled: boolean,
@@ -1752,10 +1610,7 @@ export class BrowserManager {
       this.cancelGrabOp(browserTabId, 'user')
       return true
     }
-    // Why: injecting the overlay runtime eagerly on arm lets the hover UI
-    // appear instantly when the user starts moving the pointer, rather than
-    // adding a visible delay between "click Grab" and "overlay appears".
-    // The runtime is idempotent — re-injection on the same page is safe.
+    // Why: inject the overlay runtime eagerly on arm so the hover UI appears instantly; re-injection is idempotent/safe.
     try {
       await guest.executeJavaScript(buildGuestOverlayScript('arm'))
       return true
@@ -1765,18 +1620,9 @@ export class BrowserManager {
   }
 
   /**
-   * Await a single grab selection on the given tab. Returns a Promise that
-   * resolves exactly once when the user clicks, cancels, or an error occurs.
+   * Await a single grab selection on the given tab; resolves once on click, cancel, or error.
    *
-   * Why the click is handled in-guest rather than via main-side interception:
-   * Electron's `before-input-event` only fires for keyboard events, not mouse
-   * events on guest webContents. The design doc anticipated a main-owned
-   * interceptor, but the spike showed this API gap. The fallback (documented
-   * in the design doc) is to let the guest overlay's full-viewport hit-catcher
-   * consume the click. The overlay calls `stopPropagation()` and
-   * `preventDefault()` so the page underneath does not receive the event.
-   * This is not a perfect guarantee (capture-phase listeners on window may
-   * still fire), but it covers the vast majority of sites.
+   * Why in-guest: before-input-event fires only for keyboard (not mouse) on guests, so the overlay hit-catcher consumes the click.
    */
   awaitGrabSelection(
     browserTabId: string,
@@ -1786,17 +1632,12 @@ export class BrowserManager {
     return this.grabSessionController.awaitGrabSelection(browserTabId, opId, guest)
   }
 
-  /**
-   * Cancel an active grab operation for the given tab.
-   */
+  /** Cancel an active grab operation for the given tab. */
   cancelGrabOp(browserTabId: string, reason: BrowserGrabCancelReason): void {
     this.grabSessionController.cancelGrabOp(browserTabId, reason)
   }
 
-  /**
-   * Capture a screenshot of the guest surface and optionally crop it to
-   * the given CSS-pixel rect.
-   */
+  /** Capture a screenshot of the guest surface, optionally cropped to the given CSS-pixel rect. */
   async captureSelectionScreenshot(
     _browserTabId: string,
     rect: BrowserGrabRect,
@@ -1805,11 +1646,7 @@ export class BrowserManager {
     return captureGrabSelectionScreenshot(rect, guest)
   }
 
-  /**
-   * Extract the payload for the currently hovered element without disrupting
-   * the active grab overlay or awaitClick listener. Used by keyboard shortcuts
-   * that let the user copy content while hovering, before clicking.
-   */
+  /** Extract the hovered element's payload without disrupting the active grab overlay/awaitClick listener. */
   async extractHoverPayload(
     _browserTabId: string,
     guest: Electron.WebContents
@@ -1836,13 +1673,7 @@ export class BrowserManager {
     )
   }
 
-  // Why: browser grab mode intentionally uses Cmd/Ctrl+C as its entry
-  // gesture, but a focused webview guest is a separate Chromium process so
-  // the renderer's window-level keydown handler never sees that shortcut.
-  // Only forward the chord when Chromium would not perform a normal copy:
-  // no editable element is focused and there is no selected text. That keeps
-  // native page copy working while still making the grab shortcut reachable
-  // from focused web content.
+  // Why: forward grab's Cmd/Ctrl+C from a focused guest only when no edit field/selection is active, so native copy still works.
   private setupGrabShortcut(browserTabId: string, guest: Electron.WebContents): void {
     const previousCleanup = this.grabShortcutCleanupByTabId.get(browserTabId)
     if (previousCleanup) {
@@ -1863,11 +1694,7 @@ export class BrowserManager {
     )
   }
 
-  // Why: a focused webview guest is a separate Chromium process — keyboard
-  // events go to the guest's own webContents and never fire the renderer's
-  // window-level keydown handler or the main window's before-input-event.
-  // Intercept common app shortcuts on the guest and forward them to the
-  // renderer so they work consistently regardless of which surface has focus.
+  // Why: a focused webview guest is a separate process, so its key events never reach the renderer; intercept and forward app shortcuts.
   private setupShortcutForwarding(browserTabId: string, guest: Electron.WebContents): void {
     const previousCleanup = this.shortcutForwardingCleanupByTabId.get(browserTabId)
     if (previousCleanup) {
@@ -1913,9 +1740,7 @@ export class BrowserManager {
   ): void {
     const browserTabId = this.tabIdByWebContentsId.get(guestWebContentsId)
     if (!browserTabId) {
-      // Why: some localhost failures happen before the renderer finishes
-      // registering which tab owns this guest. Queue the failure by guest ID so
-      // registerGuest can replay it instead of silently losing the error state.
+      // Why: a failure can arrive before the tab is registered; queue by guest ID so registerGuest can replay it.
       this.pendingLoadFailuresByGuestId.set(guestWebContentsId, loadError)
       return
     }
@@ -2110,9 +1935,7 @@ export class BrowserManager {
     try {
       download.item.cancel()
     } catch {
-      // Why: DownloadItem.cancel can throw after the item has already
-      // finalized. Cleanup here is best-effort because the UI state is the
-      // source of truth for whether Orca still considers the request active.
+      // Why: cancel() can throw on an already-finalized item; best-effort since UI state is authoritative.
     }
 
     if (shouldSendCancel) {
@@ -2203,9 +2026,7 @@ export class BrowserManager {
       return
     }
 
-    // Why: redact Kagi session tokens before the validated URL is persisted
-    // by the renderer into BrowserPage.loadError (saved to disk via the
-    // workspace session writer).
+    // Why: redact Kagi session tokens before the renderer persists validatedUrl to disk.
     renderer.send('browser:guest-load-failed', {
       browserPageId: browserTabId,
       loadError: {
@@ -2224,8 +2045,7 @@ export class BrowserManager {
     if (!normalizedUrl || normalizedUrl === ORCA_BROWSER_BLANK_URL) {
       return false
     }
-    // Why: only the renderer owns Orca's worktree/tab model. Main forwards a
-    // validated URL instead of letting arbitrary guest content mutate it.
+    // Why: only the renderer owns Orca's worktree/tab model; main forwards a validated URL, never letting guest content mutate it.
     renderer.send('browser:open-link-in-orca-tab', {
       browserPageId: browserTabId,
       url: normalizedUrl
diff --git a/src/main/browser/browser-session-registry.ts b/src/main/browser/browser-session-registry.ts
index a70aff4e6b2..72a888edb62 100644
--- a/src/main/browser/browser-session-registry.ts
+++ b/src/main/browser/browser-session-registry.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: the registry is the single source of truth for
-   browser session profiles, partition allowlisting, cookie import staging, and
-   per-partition permission/download policies. Splitting further would scatter the
-   security boundary across modules. */
+/* eslint-disable max-lines -- Why: single source of truth for browser session profiles, partition allowlisting, cookie staging, and per-partition policies; splitting scatters the security boundary. */
 import { app, session } from 'electron'
 import type { Session } from 'electron'
 import { randomUUID } from 'node:crypto'
@@ -52,10 +49,7 @@ const BROWSER_SESSION_META_FILE_NAME = 'browser-session-meta.json'
 const LEGACY_BROWSER_SESSION_PARTITION_RE =
   /^persist:orca-browser-session-[\da-f-]{8}-[\da-f-]{4}-[\da-f-]{4}-[\da-f-]{4}-[\da-f-]{12}$/
 
-// Why: the registry is the single source of truth for which Electron partitions
-// are valid. will-attach-webview consults it to decide whether a guest's
-// requested partition is allowed. This prevents a compromised renderer from
-// smuggling an arbitrary partition string into a guest surface.
+// Why: source of truth for valid partitions; will-attach-webview consults it so a compromised renderer can't smuggle in an arbitrary partition.
 
 class BrowserSessionRegistry {
   private readonly profiles = new Map<string, BrowserSessionProfile>()
@@ -86,10 +80,7 @@ class BrowserSessionRegistry {
     })
   }
 
-  // Why: the default profile's source metadata (what browser was imported,
-  // when) must survive app restarts so the Settings UI can show the import
-  // status. Cookies themselves persist in the Electron partition's SQLite DB,
-  // but the registry is in-memory only.
+  // Why: source metadata must persist across restarts (for the Settings import status) since the registry is in-memory only.
   private get metadataPath(): string {
     return (
       this.metadataPathOverride ?? join(app.getPath('userData'), BROWSER_SESSION_META_FILE_NAME)
@@ -103,13 +94,11 @@ class BrowserSessionRegistry {
   private static partitionCookiesPath(partition: string): string {
     const partitionName = partition.replace('persist:', '')
     const partitionDir = join(app.getPath('userData'), 'Partitions', partitionName)
-    // Why: replay must overwrite the same modern or legacy database that the
-    // importing Electron partition already uses.
+    // Why: replay must overwrite the same (modern or legacy) DB the importing partition already uses.
     return resolveChromiumCookiesPath(partitionDir) ?? join(partitionDir, 'Cookies')
   }
 
-  // Why: write-to-temp-then-rename is atomic on all supported platforms.
-  // A crash mid-write would only lose the temp file, not corrupt the live one.
+  // Why: write-temp-then-rename is atomic, so a crash mid-write can't corrupt the live file.
   private persistMeta(updates: Partial<BrowserSessionMeta>): void {
     try {
       const existing = this.loadPersistedMeta()
@@ -129,8 +118,7 @@ class BrowserSessionRegistry {
     })
   }
 
-  // Why: non-default profiles are in-memory only unless explicitly persisted.
-  // Without this, created profiles vanish on app restart.
+  // Why: non-default profiles are in-memory only; without this they vanish on restart.
   private persistProfiles(): void {
     const nonDefault = [...this.profiles.values()].filter((p) => p.id !== 'default')
     this.persistMeta({ profiles: nonDefault })
@@ -178,16 +166,8 @@ class BrowserSessionRegistry {
     }
   }
 
-  // Why: browser sessions must be initialized BEFORE any webview loads.
-  // Permission/download policies must exist before sites request capabilities,
-  // and the User-Agent must be set before the first request so imported session
-  // cookies are not invalidated by Electron's default UA.
-  //
-  // Why this also refreshes defaultSource: the singleton constructor runs at
-  // module-import time, which may be before app.isReady(). app.getPath('userData')
-  // is not guaranteed before ready, so the constructor's loadPersistedSource()
-  // silently returns null. Re-reading here after app readiness ensures the
-  // default profile's source is populated.
+  // Why: run before any webview loads, and set the UA before the first request or Electron's default UA invalidates imported cookies.
+  // Why re-read defaultSource: the constructor may run before app.isReady() (userData path unavailable), so loadPersistedSource() returned null.
   initializeBrowserSessionsFromPersistedState(): void {
     const meta = this.loadPersistedMeta()
     if (meta.defaultSource) {
@@ -200,11 +180,7 @@ class BrowserSessionRegistry {
       this.hydrateFromPersisted(meta.profiles)
     }
 
-    // Why: the default partition is created in the constructor but never gets
-    // session policies (permission handlers, download handlers, etc.) because
-    // hydrateFromPersisted skips the default partition and createProfile never
-    // targets it. Without this, clipboard permissions and other guest policies
-    // are denied by default in the default browser partition.
+    // Why: nothing else installs policies on the default partition (hydrate skips it), so without this its guest permissions would be denied.
     this.setupSessionPolicies(this.defaultPartition)
 
     const partitions = new Set([
@@ -221,8 +197,7 @@ class BrowserSessionRegistry {
           continue
         }
 
-        // Why: even without an imported session, the default Electron UA contains
-        // "Electron/X.X.X" and the app name which trip Cloudflare Turnstile.
+        // Why: the default Electron UA leaks "Electron/X.X.X" + app name, which trips Cloudflare Turnstile.
         const cleanUA = cleanElectronUserAgent(sess.getUserAgent())
         sess.setUserAgent(cleanUA)
         setupClientHintsOverride(sess, cleanUA)
@@ -232,10 +207,7 @@ class BrowserSessionRegistry {
     }
   }
 
-  // Why: the import writes cookies to a staging DB because CookieMonster holds
-  // the live DB's data in memory and would overwrite our changes on its next
-  // flush. This method MUST run before any session.fromPartition() call so
-  // CookieMonster reads the staged cookies instead of the stale live DB.
+  // Why: must run before any session.fromPartition() so CookieMonster reads the staged cookies instead of overwriting them from its in-memory DB.
   applyPendingCookieImport(): void {
     try {
       const meta = this.loadPersistedMeta()
@@ -243,8 +215,7 @@ class BrowserSessionRegistry {
       if (pendingEntries.length === 0) {
         return
       }
-      // Why: replay writes to partition-derived file paths, so corrupted
-      // metadata must pass the same validation as the webview allowlist.
+      // Why: replay writes to partition-derived paths, so corrupted metadata must pass the same validation as the webview allowlist.
       const knownPartitions = new Set([this.defaultPartition])
       for (const profile of meta.profiles) {
         if (this.isValidPersistedProfile(profile)) {
@@ -267,9 +238,7 @@ class BrowserSessionRegistry {
         try {
           mkdirSync(join(liveCookiesPath, '..'), { recursive: true })
           copyFileSync(stagedPath, liveCookiesPath)
-          // Why: SQLite WAL mode stores uncommitted data in sidecar files.
-          // Stale WAL/SHM from a previous session could corrupt CookieMonster's
-          // read of the freshly swapped DB.
+          // Why: stale WAL/SHM sidecars would corrupt CookieMonster's read of the freshly swapped DB.
           let sidecarCopyFailed = false
           for (const suffix of ['-wal', '-shm']) {
             try {
@@ -288,8 +257,7 @@ class BrowserSessionRegistry {
             }
           }
           if (sidecarCopyFailed) {
-            // Why: sidecar copy failures can leave an inconsistent replay state.
-            // Keep this entry for retry and preserve unrelated entries.
+            // Why: sidecar copy failed → inconsistent replay; keep this entry for retry.
             continue
           }
           for (const ext of ['', '-wal', '-shm']) {
@@ -301,8 +269,7 @@ class BrowserSessionRegistry {
           }
           delete remainingEntries[partition]
         } catch {
-          // Why: failed replay for one partition should not drop unrelated entries.
-          // Keep this entry for retry next launch.
+          // Why: keep this entry for retry — one partition's failed replay shouldn't drop unrelated entries.
         }
       }
       this.persistMeta({
@@ -365,26 +332,19 @@ class BrowserSessionRegistry {
 
   resolveKnownPartition(profileId: string | null | undefined): string | null {
     if (!profileId) {
-      // Why: must track the active Orca profile's default partition, not the
-      // legacy constant, or non-default profiles would resolve local-default's
-      // cookie jar.
+      // Why: use the active Orca profile's default partition, not the legacy constant, or profiles resolve local-default's cookie jar.
       return this.defaultPartition
     }
     return this.profiles.get(profileId)?.partition ?? null
   }
 
   createProfile(scope: BrowserSessionProfileScope, label: string): BrowserSessionProfile | null {
-    // Why: only the constructor may create the default profile. Allowing the
-    // renderer to pass scope:'default' would create a second profile sharing
-    // the active default partition, causing confusion on delete (clearing storage
-    // for the shared partition).
+    // Why: block scope:'default' here — only the constructor makes the default profile; a second one sharing the partition breaks delete.
     if (scope === 'default') {
       return null
     }
     const id = randomUUID()
-    // Why: partition names are deterministic from the profile id so main can
-    // reconstruct the allowlist on restart from persisted profile metadata
-    // without needing a separate partition→profile mapping.
+    // Why: deterministic partition-from-id lets main rebuild the allowlist on restart without a separate partition→profile map.
     const partition = getOrcaProfileBrowserSessionPartition(this.activeOrcaProfileId, id)
     const profile: BrowserSessionProfile = {
       id,
@@ -436,27 +396,22 @@ class BrowserSessionRegistry {
       userAgent: userAgentByPartition[this.defaultPartition] ?? null
     })
 
-    // Why: clearing the partition's storage prevents orphaned cookies/cache from
-    // lingering after the user deletes an imported or isolated session profile.
+    // Why: clear the partition's storage so deleting a profile doesn't leave orphaned cookies/cache behind.
     try {
       const sess = session.fromPartition(profile.partition)
       this.clearSessionPolicies(profile.partition, sess)
       await sess.clearStorageData()
       await sess.clearCache()
     } catch {
-      // Why: partition cleanup is best-effort. The profile is already removed
-      // from the registry so it won't be allowed by will-attach-webview.
+      // Why: cleanup is best-effort — the profile is already out of the registry, so will-attach-webview blocks it regardless.
     }
     return true
   }
 
-  // Why: clearing cookies from the default partition lets users undo a cookie
-  // import without deleting the default profile itself.
+  // Why: lets users undo a cookie import without deleting the default profile itself.
   async clearDefaultSessionCookies(): Promise<boolean> {
     try {
-      // Why: persist metadata BEFORE clearing storage so that if the app quits
-      // mid-clear, the next launch won't show a stale "imported from X" badge
-      // for cookies that were partially or fully removed.
+      // Why: persist metadata before clearing storage so a mid-clear quit doesn't leave a stale "imported from X" badge.
       const defaultProfile = this.profiles.get('default')
       if (defaultProfile) {
         this.profiles.set('default', { ...defaultProfile, source: null })
@@ -482,13 +437,7 @@ class BrowserSessionRegistry {
     }
   }
 
-  // Why: on startup, main must reconstruct the set of valid partitions from
-  // persisted session profiles so restored webviews are not denied by
-  // will-attach-webview before the renderer mounts them.
-  // Why: profiles are deserialized from a JSON file on disk. A corrupted or
-  // tampered file could inject an arbitrary partition into the allowlist that
-  // will-attach-webview trusts, so we validate the expected shape before
-  // registering anything.
+  // Why: validate on-disk profile shape so a tampered JSON file can't inject an arbitrary partition into the will-attach-webview allowlist.
   private isValidPersistedProfile(profile: unknown): profile is BrowserSessionProfile {
     if (!profile || typeof profile !== 'object') {
       return false
@@ -533,9 +482,7 @@ class BrowserSessionRegistry {
     }
   }
 
-  // Why: every browser partition needs the same deny-by-default permission
-  // and download policies. Keeping the installer here prevents the default
-  // partition and imported/isolated partitions from drifting apart.
+  // Why: one shared installer keeps every partition's deny-by-default permission/download policies from drifting apart.
   private readonly configuredPartitions = new Set<string>()
   private readonly handleWillDownload = (
     _event: Electron.Event,
@@ -558,12 +505,7 @@ class BrowserSessionRegistry {
       setupClientHintsOverride(sess, cleanUA)
     }
     sess.setPermissionRequestHandler((webContents, permission, callback, details) => {
-      // Why: `media` (camera/mic) must defer to macOS TCC instead of being
-      // denied outright. Denying at the session layer would make pages inside
-      // isolated browser profiles throw NotAllowedError even after the user
-      // granted Camera/Microphone to Orca — the same bug we fixed for the
-      // default partition. macOS TCC still gates the actual stream, so
-      // granting here only forwards what the OS has already authorized.
+      // Why: defer media to macOS TCC; denying at the session layer throws NotAllowedError even after the user granted Camera/Mic to the OS.
       if (permission === 'media') {
         void requestSystemMediaAccess(
           details as Electron.MediaAccessPermissionRequest | undefined
@@ -619,9 +561,7 @@ class BrowserSessionRegistry {
   }
 
   private clearSessionPolicies(partition: string, sess: Session): void {
-    // Why: isolated/imported browser partitions can be deleted while the
-    // Electron Session object survives; clear policy callbacks and listener
-    // bookkeeping so removed profiles do not leave retained closures behind.
+    // Why: the Electron Session survives partition deletion; clear callbacks/listeners so removed profiles don't retain closures.
     this.configuredPartitions.delete(partition)
     browserManager.removeCertificateRequestGuard(sess)
     sess.removeListener('will-download', this.handleWillDownload)
diff --git a/src/main/browser/cdp-bridge.ts b/src/main/browser/cdp-bridge.ts
index bda4831a790..47d263ac371 100644
--- a/src/main/browser/cdp-bridge.ts
+++ b/src/main/browser/cdp-bridge.ts
@@ -67,18 +67,15 @@ type TabState = {
   debuggerDetachListener: (() => void) | null
   debuggerMessageListener: ((_event: unknown, method: string, params: unknown) => void) | null
   iframeSessions: Map<string, string>
-  // Why: capture state is per-tab so console/network events from one tab
-  // don't pollute another's capture buffer.
+  // Why: capture state is per-tab so one tab's console/network events don't pollute another's buffer.
   capturing: boolean
   consoleLog: BrowserConsoleEntry[]
   networkLog: BrowserNetworkEntry[]
-  // Why: interception state tracks patterns and paused requests so the
-  // agent can selectively continue or block individual requests.
+  // Why: interception state lets the agent selectively continue or block individual requests.
   intercepting: boolean
   interceptPatterns: string[]
   pausedRequests: Map<string, BrowserInterceptedRequest>
-  // Why: maps CDP requestId to the networkLog entry so loadingFinished
-  // can attribute size to the correct response when requests overlap.
+  // Why: maps CDP requestId → networkLog entry so loadingFinished attributes size to the right overlapping response.
   networkRequestMap: Map<string, BrowserNetworkEntry>
 }
 
@@ -123,9 +120,7 @@ export class CdpBridge {
     _worktreeId?: string,
     browserPageId?: string
   ): { browserPageId: string; url: string; title: string } | null {
-    // Why: OrcaRuntimeService pushes navigation/title updates after commands
-    // using a bridge-agnostic contract. The CDP bridge only routes one active
-    // tab at a time, but it still needs to expose the same metadata lookup.
+    // Why: expose the same metadata lookup as other bridges, though the CDP bridge routes only one active tab.
     const resolvedPageId = browserPageId ?? this.getActivePageId()
     if (!resolvedPageId) {
       return null
@@ -185,10 +180,7 @@ export class CdpBridge {
       const localCenter = await this.getElementCenter(refSender, node.backendDOMNodeId)
       const { cx, cy } = await this.getPageCoordinates(guest, node, localCenter.cx, localCenter.cy)
 
-      // Why: mouseMoved fires mouseenter/mouseover which some sites need to
-      // reveal hover-dependent menus or clickable areas before the click lands.
-      // Input events go to the parent session — Chrome routes them to the
-      // correct frame based on coordinates.
+      // Why: mouseMoved fires mouseenter/mouseover so sites reveal hover-dependent menus/targets before the click lands.
       await sender('Input.dispatchMouseEvent', { type: 'mouseMoved', x: cx, y: cy })
       await sender('Input.dispatchMouseEvent', {
         type: 'mousePressed',
@@ -244,9 +236,7 @@ export class CdpBridge {
       const toLocal = await this.getElementCenter(toSender, toNode.backendDOMNodeId)
       const to = await this.getPageCoordinates(guest, toNode, toLocal.cx, toLocal.cy)
 
-      // Why: 10-step interpolation with delays simulates human-like drag and
-      // triggers dragenter/dragover events on intermediate elements, which many
-      // drag-and-drop libraries rely on.
+      // Why: interpolate the drag so intermediate elements fire dragenter/dragover, which many drag-and-drop libs require.
       await sender('Input.dispatchMouseEvent', { type: 'mouseMoved', x: from.cx, y: from.cy })
       await sender('Input.dispatchMouseEvent', {
         type: 'mousePressed',
@@ -323,8 +313,7 @@ export class CdpBridge {
 
       await refSender('DOM.focus', { backendNodeId: node.backendDOMNodeId })
 
-      // Why: select-all then delete clears any existing value before typing,
-      // matching the behavior of Playwright's fill() and agent-browser's fill.
+      // Why: select-all + delete clears the existing value before typing, matching Playwright/agent-browser fill().
       await sender('Input.dispatchKeyEvent', {
         type: 'keyDown',
         key: 'a',
@@ -340,11 +329,8 @@ export class CdpBridge {
 
       await insertTextThroughCdp(sender, value)
 
-      // Why: React and other frameworks use synthetic event listeners that may not
-      // detect native keyboard events. Explicitly dispatching input/change ensures
-      // controlled components update their state. Uses refSender so that in iframe
-      // contexts, document.activeElement resolves to the iframe's focused element
-      // rather than the <iframe> element on the parent page.
+      // Why: React's synthetic listeners ignore native key events, so dispatch input/change so controlled components update.
+      // Why: use refSender for iframe sessions so document.activeElement is the focused element inside the iframe, not the parent <iframe>.
       const eventSender = node.sessionId ? refSender : sender
       await eventSender('Runtime.evaluate', {
         expression: `(() => {
@@ -388,11 +374,7 @@ export class CdpBridge {
         object: { objectId: string }
       }
 
-      // Why: agent-browser matches by both .value AND .textContent.trim() so
-      // the agent can select options by their displayed label, not just the
-      // underlying value attribute which may be an opaque ID.
-      // Also handles custom combobox elements (role="combobox" on non-<select>)
-      // by falling back to click-based selection on child options.
+      // Why: match on label (textContent) and value so opaque option IDs still select; also handles combobox via click.
       await refSender('Runtime.callFunctionOn', {
         objectId: object.objectId,
         functionDeclaration: `function(val) {
@@ -433,9 +415,7 @@ export class CdpBridge {
       const sender = this.makeCdpSender(guest)
       await this.ensureDebuggerAttached(guest)
 
-      // Why: JS scrollBy is deterministic and doesn't require page focus,
-      // unlike Input.dispatchMouseEvent mouseWheel which is unreliable in
-      // Electron webviews and can timeout.
+      // Why: JS scrollBy needs no focus and is deterministic, unlike mouseWheel which is unreliable in Electron webviews.
       const expr = amount
         ? `window.scrollBy(0, ${direction === 'down' ? amount : -amount})`
         : `window.scrollBy(0, ${direction === 'down' ? 'window.innerHeight' : '-window.innerHeight'})`
@@ -501,10 +481,7 @@ export class CdpBridge {
           clickCount: 1
         })
 
-        // Why: custom checkbox patterns (label wrapping hidden input, overlays)
-        // may not toggle from coordinate-based clicking. Verify state changed
-        // and fall back to programmatic .click() if needed. Wrapped in try/catch
-        // because the click may have triggered a re-render that invalidated objectId.
+        // Why: custom checkboxes may not toggle from a coordinate click; verify state and fall back to programmatic .click().
         try {
           const { result: afterState } = (await refSender('Runtime.callFunctionOn', {
             objectId: object.objectId,
@@ -639,10 +616,7 @@ export class CdpBridge {
         cssContentSize?: { width: number; height: number }
         contentSize?: { width: number; height: number }
       }
-      // Why: Page.captureScreenshot clip coordinates are CSS pixels. On HiDPI
-      // displays, Electron can report device-pixel `contentSize`, which causes
-      // Chromium to tile the page into duplicated quadrants. Prefer
-      // `cssContentSize` so the clip matches the page's CSS layout size.
+      // Why: screenshot clip uses CSS pixels; on HiDPI, device-pixel contentSize tiles duplicates, so prefer cssContentSize.
       const contentSize = metrics.cssContentSize ?? metrics.contentSize
       if (!contentSize) {
         throw new BrowserError('browser_error', 'Unable to determine full-page screenshot bounds')
@@ -699,10 +673,7 @@ export class CdpBridge {
       const sender = this.makeCdpSender(guest)
       await this.ensureDebuggerAttached(guest)
 
-      // Why: Network.setCookie requires either domain or url to scope the cookie.
-      // If the caller doesn't provide a domain, infer it from the current page URL
-      // so the cookie is usable on the active page without forcing callers to
-      // know the domain upfront.
+      // Why: Network.setCookie needs a domain or url to scope the cookie; infer the domain from the current page when omitted.
       let domain = cookie.domain
       if (!domain) {
         const { result: urlResult } = (await sender('Runtime.evaluate', {
@@ -747,8 +718,7 @@ export class CdpBridge {
       if (url) {
         params.url = url
       }
-      // Why: Network.deleteCookies requires at least one of domain or url.
-      // Infer from current page if neither was provided.
+      // Why: Network.deleteCookies needs a domain or url; infer from the current page if neither was given.
       if (!domain && !url) {
         const { result: urlResult } = (await sender('Runtime.evaluate', {
           expression: 'location.href',
@@ -781,8 +751,7 @@ export class CdpBridge {
         deviceScaleFactor,
         mobile
       })
-      // Why: BrowserView's compositor surface can keep the previous host size
-      // after metrics-only resize, which crops remote screencast clients.
+      // Why: metrics-only resize can leave the compositor surface at the old size, cropping remote screencast clients.
       await Promise.resolve(sender('Emulation.setVisibleSize', { width, height })).catch(() => {})
 
       return { width, height, deviceScaleFactor, mobile }
@@ -852,9 +821,7 @@ export class CdpBridge {
     return { requests: [...state.pausedRequests.values()] }
   }
 
-  // TODO: Add interceptContinue/interceptBlock once agent-browser supports per-request
-  // interception decisions. The CDP Fetch domain supports it, but the agent-browser CLI
-  // only operates on URL pattern-level routing, creating a design mismatch.
+  // TODO: Add interceptContinue/interceptBlock once agent-browser supports per-request decisions (CLI is URL-pattern-only).
 
   // ── Console/network capture ──
 
@@ -975,8 +942,7 @@ export class CdpBridge {
 
       const valueStr =
         result.value !== undefined ? String(result.value) : (result.description ?? '')
-      // Why: agent-browser returns { result, origin } — match that shape so both
-      // bridges satisfy the same BrowserEvalResult contract.
+      // Why: include origin to match agent-browser's BrowserEvalResult shape across both bridges.
       const { result: urlResult } = (await sender('Runtime.evaluate', {
         expression: 'location.origin',
         returnByValue: true
@@ -1011,8 +977,7 @@ export class CdpBridge {
   }
 
   async tabSwitch(index: number): Promise<BrowserTabSwitchResult> {
-    // Why: filter to live tabs so indices match what tabList() presents.
-    // Destroyed-but-not-yet-cleaned entries must be skipped.
+    // Why: filter to live tabs so indices match tabList(), skipping destroyed-but-uncleaned entries.
     const liveEntries = [...this.getRegisteredTabs()].filter(([_, wcId]) => {
       const guest = webContents.fromId(wcId)
       return guest && !guest.isDestroyed()
@@ -1061,10 +1026,7 @@ export class CdpBridge {
       if (guest && !guest.isDestroyed()) {
         return guest
       }
-      // Why: the stored webContentsId may be stale after a Chromium process swap
-      // (navigation to a different-origin page, crash recovery). Fall through to
-      // the auto-select logic rather than immediately failing, since the tab may
-      // still be alive under a new webContentsId.
+      // Why: webContentsId goes stale after a process swap; fall through to auto-select since the tab may have a new id.
       this.activeWebContentsId = null
     }
 
@@ -1096,11 +1058,7 @@ export class CdpBridge {
   }
 
   private getRegisteredTabs(): Map<string, number> {
-    // Why: BrowserManager's tab maps are private. We access the singleton's
-    // state via the public getGuestWebContentsId method by iterating known tabs.
-    // This method provides the tab enumeration the CDP bridge needs without
-    // modifying BrowserManager's encapsulation. In the future a public
-    // listTabs() method on BrowserManager would be cleaner.
+    // Why: reach into BrowserManager's private tab map since it exposes no public listTabs().
     return (this.browserManager as unknown as { webContentsIdByTabId: Map<string, number> })
       .webContentsIdByTabId
   }
@@ -1176,9 +1134,7 @@ export class CdpBridge {
     }
 
     try {
-      // Why: browser tabs are already debugger-attached by BrowserManager's
-      // anti-detection injection. Reusing that attachment lets CDP commands
-      // run instead of failing with "another debugger is already attached."
+      // Why: BrowserManager already attached the debugger; reuse it to avoid "another debugger is already attached."
       if (!guest.debugger.isAttached()) {
         guest.debugger.attach('1.3')
       }
@@ -1194,24 +1150,19 @@ export class CdpBridge {
     await sender('DOM.enable')
     await sender('Network.enable')
 
-    // Why: cross-origin iframes run in separate renderer processes (OOPIFs) and
-    // are invisible to the parent's CDP session. setAutoAttach with flatten:true
-    // gives each OOPIF its own sessionId that we can target with sendCommand.
+    // Why: OOPIF iframes are invisible to the parent CDP session; flatten:true gives each a targetable sessionId.
     await sender('Target.setAutoAttach', {
       autoAttach: true,
       waitForDebuggerOnStart: false,
       flatten: true
     })
 
-    // Why: attaching the CDP debugger sets navigator.webdriver = true and
-    // exposes other automation signals that Cloudflare Turnstile checks.
-    // Override them on every new document load so challenges succeed.
+    // Why: CDP attach exposes automation signals (navigator.webdriver) that Cloudflare checks; override per new document.
     await sender('Page.addScriptToEvaluateOnNewDocument', {
       source: ANTI_DETECTION_SCRIPT
     })
 
-    // Why: only remove CDP bridge listeners from the previous attach cycle.
-    // Screencast/proxy sessions share this debugger and own their teardown hooks.
+    // Why: only remove this bridge's listeners; screencast/proxy sessions share the debugger and own their teardown.
     this.removeDebuggerListeners(guest, state)
 
     const detachListener = (): void => {
@@ -1226,8 +1177,7 @@ export class CdpBridge {
         state.snapshotResult = null
         state.navigationId = null
       }
-      // Why: an unhandled alert/confirm/prompt blocks ALL subsequent CDP commands.
-      // Auto-dismissing prevents the session from hanging indefinitely.
+      // Why: an unhandled JS dialog blocks all subsequent CDP commands; auto-dismiss to avoid hanging.
       if (method === 'Page.javascriptDialogOpening') {
         const dialog = params as { type: string; message: string } | undefined
         guest.debugger
@@ -1236,8 +1186,7 @@ export class CdpBridge {
           })
           .catch(() => {})
       }
-      // Why: track cross-origin iframe sessions so we can route CDP commands
-      // and accessibility tree queries to the correct session.
+      // Why: track iframe sessions so CDP commands and AX queries route to the correct session.
       if (method === 'Target.attachedToTarget') {
         const p = params as
           | {
@@ -1247,7 +1196,6 @@ export class CdpBridge {
           | undefined
         if (p?.sessionId && p.targetInfo?.type === 'iframe' && p.targetInfo.targetId) {
           state.iframeSessions.set(p.targetInfo.targetId, p.sessionId)
-          // Enable domains on iframe session
           guest.debugger.sendCommand('DOM.enable', {}, p.sessionId).catch(() => {})
           guest.debugger.sendCommand('Accessibility.enable', {}, p.sessionId).catch(() => {})
           guest.debugger.sendCommand('Runtime.enable', {}, p.sessionId).catch(() => {})
@@ -1264,8 +1212,7 @@ export class CdpBridge {
           }
         }
       }
-      // Why: console and network events are buffered per-tab so the agent can
-      // retrieve them on demand via the capture commands.
+      // Why: buffer console/network events per-tab so the agent can retrieve them on demand.
       if (state.capturing) {
         if (method === 'Runtime.consoleAPICalled') {
           const p = params as
@@ -1314,8 +1261,7 @@ export class CdpBridge {
               timestamp: p.timestamp ?? Date.now()
             }
             state.networkLog.push(entry)
-            // Why: track requestId→entry so loadingFinished can attribute
-            // size to the correct response, not just the most recent one.
+            // Why: map requestId→entry so loadingFinished attributes size to the right response, not the latest one.
             if (p.requestId) {
               state.networkRequestMap.set(p.requestId, entry)
             }
@@ -1343,8 +1289,7 @@ export class CdpBridge {
           }
         }
       }
-      // Why: request interception buffers paused requests so the agent can
-      // inspect and decide to continue or block them.
+      // Why: buffer paused requests so the agent can later inspect and continue or block them.
       if (state.intercepting && method === 'Fetch.requestPaused') {
         const p = params as
           | {
@@ -1376,10 +1321,7 @@ export class CdpBridge {
   private makeCdpSender(guest: Electron.WebContents, sessionId?: string): CdpCommandSender {
     return (method: string, params?: Record<string, unknown>) => {
       const command = guest.debugger.sendCommand(method, params, sessionId) as Promise<unknown>
-      // Why: Electron's CDP sendCommand can hang indefinitely if the debugger
-      // session is stale (e.g. after a renderer process swap that wasn't detected).
-      // A 10s timeout prevents the RPC from blocking until the CLI's socket timeout.
-      // The timer is cancelled on success/failure to avoid dangling timer accumulation.
+      // Why: Electron's CDP sendCommand can hang on a stale debugger session, so a 10s timeout bounds the RPC.
       let timer: ReturnType<typeof setTimeout>
       return Promise.race([
         command.finally(() => clearTimeout(timer)),
@@ -1421,9 +1363,7 @@ export class CdpBridge {
       )
     }
 
-    // Why: iframe refs use a child session whose navigation history is independent
-    // of the parent page. Checking the parent's navId against an iframe session
-    // would always mismatch and falsely reject valid refs.
+    // Why: iframe refs use a child session with independent nav history, so a parent-navId check would falsely reject them.
     if (!entry.sessionId) {
       const currentNavId = await this.getNavigationId(sender)
       if (state.navigationId && currentNavId !== state.navigationId) {
@@ -1441,10 +1381,7 @@ export class CdpBridge {
       await refSender('DOM.describeNode', { backendNodeId: entry.backendDOMNodeId })
       return entry
     } catch {
-      // Why: dynamic pages (React, Vue) re-render DOM nodes frequently. A ref
-      // from a snapshot taken seconds ago may point to a detached node even though
-      // an identical element exists. Re-query the AX tree to find the fresh node
-      // by matching role + name, avoiding a wasted retry for the agent.
+      // Why: dynamic pages re-render nodes, detaching snapshot refs; re-query the AX tree by role+name for the fresh node.
       const recovered = await this.tryRecoverRef(refSender, entry)
       if (recovered) {
         entry.backendDOMNodeId = recovered
@@ -1480,10 +1417,7 @@ export class CdpBridge {
     return { cx: (x1 + x3) / 2, cy: (y1 + y3) / 2 }
   }
 
-  // Why: elements inside cross-origin iframes report coordinates relative to
-  // the iframe viewport, but Input.dispatchMouseEvent operates on the parent
-  // page's coordinate space. We find the iframe element on the parent page and
-  // add its top-left offset to translate iframe-local coords to page coords.
+  // Why: cross-origin iframes report iframe-local coords, but Input events use parent-page space; add the iframe offset.
   private async getIframeOffset(
     guest: Electron.WebContents,
     sessionId: string
@@ -1495,9 +1429,7 @@ export class CdpBridge {
     for (const [targetId, sid] of state.iframeSessions) {
       if (sid === sessionId) {
         try {
-          // Why: use Target.getTargetInfo to get the iframe's URL, then match it
-          // against DOM iframe src attributes to find the correct element's position.
-          // This correctly handles pages with multiple iframes.
+          // Why: match the iframe's target URL against DOM iframe src to pick the right element on multi-iframe pages.
           const { targetInfo } = (await parentSender('Target.getTargetInfo', {
             targetId
           })) as { targetInfo: { url?: string } }
@@ -1526,8 +1458,7 @@ export class CdpBridge {
                 return { offsetX: rect.x, offsetY: rect.y }
               }
             }
-            // Why: iframe may have redirected after load, making src differ
-            // from the actual target URL. Match by origin as a fallback.
+            // Why: iframe may redirect after load so src differs from target URL; match by origin as a fallback.
             try {
               const targetOrigin = new URL(targetUrl).origin
               for (const rect of rects) {
@@ -1554,8 +1485,7 @@ export class CdpBridge {
     return { offsetX: 0, offsetY: 0 }
   }
 
-  // Why: for elements inside iframes, translates iframe-local coordinates to
-  // page-level coordinates that Input.dispatchMouseEvent expects.
+  // Why: Input.dispatchMouseEvent uses parent-page coords, so translate iframe-local coords for iframe elements.
   private async getPageCoordinates(
     guest: Electron.WebContents,
     refEntry: RefEntry,
@@ -1569,9 +1499,7 @@ export class CdpBridge {
     return { cx: localCx + offsetX, cy: localCy + offsetY }
   }
 
-  // Why: uses nth-index to pick the correct duplicate when multiple elements
-  // share the same role+name. Without this, recovery always returns the first
-  // match which may not be the element the ref originally pointed to.
+  // Why: nth-index disambiguates duplicate role+name matches so recovery hits the original element, not the first match.
   private async tryRecoverRef(sender: CdpCommandSender, entry: RefEntry): Promise<number | null> {
     try {
       const { nodes } = (await sender('Accessibility.getFullAXTree')) as {
@@ -1626,9 +1554,7 @@ export class CdpBridge {
   }
 
   private async waitForLoad(sender: CdpCommandSender, guest: Electron.WebContents): Promise<void> {
-    // Why: wait for document.readyState=complete first, then wait for network
-    // idle (no pending requests for 500ms). This handles SPAs that fire 'load'
-    // before async content is rendered.
+    // Why: SPAs fire 'load' before async content renders, so also wait for 500ms of network idle.
     const TIMEOUT_MS = 25_000
     const IDLE_MS = 500
     const startedAt = Date.now()
@@ -1792,9 +1718,7 @@ export class CdpBridge {
   }
 }
 
-// Why: CDP's Input.dispatchKeyEvent requires `windowsVirtualKeyCode` (not `keyCode`)
-// and `text` for keys that produce default browser actions (Enter submits forms,
-// Tab moves focus). Without `text`, Chrome fires the event but doesn't perform the action.
+// Why: Input.dispatchKeyEvent needs `text` for keys with default actions (Enter/Tab), or Chrome skips the action.
 type KeyDefinition = {
   key: string
   code: string
@@ -1823,10 +1747,7 @@ function resolveKeyDefinition(key: string): KeyDefinition {
   if (KEY_DEFINITIONS[key]) {
     return KEY_DEFINITIONS[key]
   }
-  // Why: single characters need proper code values — digits use "DigitN",
-  // letters use "KeyX", and other characters use their char code for the
-  // windowsVirtualKeyCode. Invalid codes cause events to be dropped by sites
-  // that check event.code.
+  // Why: sites that check event.code drop events with invalid code values.
   if (key.length === 1) {
     const charCode = key.charCodeAt(0)
     if (charCode >= 48 && charCode <= 57) {
diff --git a/src/main/browser/grab-guest-script.ts b/src/main/browser/grab-guest-script.ts
index 0613d7319eb..8841fb6cf97 100644
--- a/src/main/browser/grab-guest-script.ts
+++ b/src/main/browser/grab-guest-script.ts
@@ -1,20 +1,6 @@
-/* eslint-disable max-lines -- Why: the guest overlay runtime is a single
-self-contained JS string template that must be injected atomically into the
-guest page. Splitting it across modules would require a string concatenation
-build step that adds complexity without improving auditability. */
-// ---------------------------------------------------------------------------
-// Browser Context Grab — guest overlay runtime builder
-//
-// This module produces self-contained JavaScript strings that main injects into
-// browser guests via executeJavaScript(). The guest runtime is intentionally
-// ephemeral: it installs on arm, resolves once on finalize, and fully removes
-// itself on teardown.
-//
-// Why a string builder rather than a bundled file: Orca's browser guests have
-// no preload and no Node access. The injected code must be a plain JS string
-// that runs in the page's own world. Keeping it as a template here lets main
-// version it alongside the rest of the grab lifecycle.
-// ---------------------------------------------------------------------------
+/* eslint-disable max-lines -- the guest overlay runtime is one self-contained JS string injected atomically; splitting it adds a concat build step for no auditability gain. */
+// Browser Context Grab — builds self-contained JS strings injected into guests via executeJavaScript().
+// Why a string builder not a bundle: guests have no preload/Node; injected code must be plain JS in the page's own world.
 
 type GuestScriptAction = 'arm' | 'awaitClick' | 'finalize' | 'extractHover' | 'teardown'
 
@@ -42,10 +28,7 @@ export function buildGuestOverlayScript(action: GuestScriptAction): string {
   }
 }
 
-// ---------------------------------------------------------------------------
-// The arm script installs the overlay container and hover tracking.
-// It stores state on window.__orcaGrab so finalize/teardown can access it.
-// ---------------------------------------------------------------------------
+// arm: install the overlay + hover tracking; state lives on window.__orcaGrab so finalize/teardown can reach it.
 const ARM_SCRIPT = `(function() {
   'use strict';
 
@@ -839,11 +822,7 @@ const ARM_SCRIPT = `(function() {
   return true;
 })()`
 
-// ---------------------------------------------------------------------------
-// The awaitClick script returns a Promise that resolves when the user clicks
-// on the full-viewport overlay. The click never reaches the page because the
-// overlay host has pointer-events:all and the handler calls stopPropagation.
-// ---------------------------------------------------------------------------
+// awaitClick: resolve when the user clicks the overlay; stopPropagation + pointer-events:all keep the click off the page.
 const AWAIT_CLICK_SCRIPT = `new Promise(function(resolve, reject) {
   'use strict';
   var grab = window.__orcaGrab;
@@ -919,9 +898,6 @@ const AWAIT_CLICK_SCRIPT = `new Promise(function(resolve, reject) {
   };
 })`
 
-// ---------------------------------------------------------------------------
-// The finalize script extracts the payload for the currently hovered element.
-// ---------------------------------------------------------------------------
 const FINALIZE_SCRIPT = `(function() {
   'use strict';
   var grab = window.__orcaGrab;
@@ -939,12 +915,7 @@ const FINALIZE_SCRIPT = `(function() {
   return payload;
 })()`
 
-// ---------------------------------------------------------------------------
-// The extractHover script reads the payload for the currently hovered element
-// WITHOUT cleaning up. The overlay and awaitClick listener stay active so the
-// user can continue picking elements. Used by keyboard shortcuts (C/S) that
-// copy the hovered element without requiring a click first.
-// ---------------------------------------------------------------------------
+// extractHover: read payload but keep overlay/listeners active so the user can keep picking (C/S shortcut copy, no click).
 const EXTRACT_HOVER_SCRIPT = `(function() {
   'use strict';
   var grab = window.__orcaGrab;
@@ -958,9 +929,6 @@ const EXTRACT_HOVER_SCRIPT = `(function() {
   }
 })()`
 
-// ---------------------------------------------------------------------------
-// The teardown script removes the overlay and cleans up all state.
-// ---------------------------------------------------------------------------
 const TEARDOWN_SCRIPT = `(function() {
   'use strict';
   var grab = window.__orcaGrab;
diff --git a/src/main/claude-accounts/runtime-auth-service.ts b/src/main/claude-accounts/runtime-auth-service.ts
index 72a29cfa6a9..3d901f872c0 100644
--- a/src/main/claude-accounts/runtime-auth-service.ts
+++ b/src/main/claude-accounts/runtime-auth-service.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: Claude account switching has one safety
-boundary: runtime auth materialization. Keeping file, Keychain, snapshot, and
-env-patch semantics together prevents PTY launch and quota fetch paths drifting. */
+/* eslint-disable max-lines -- Why: keeps file/Keychain/snapshot/env-patch auth semantics together so PTY launch and quota-fetch paths can't drift. */
 import { execFileSync } from 'node:child_process'
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { dirname, join } from 'node:path'
@@ -98,10 +96,7 @@ export class ClaudeRuntimeAuthService {
   private readonly pathResolver = new ClaudeRuntimePathResolver()
   private mutationQueue: Promise<unknown> = Promise.resolve()
   private lastSyncedAccountId: string | null = null
-  // Why: tracks the credentials Orca last wrote to the shared credentials file.
-  // On managed→system-default transition, if the file differs from this value,
-  // an external login (e.g. `claude auth login`) overwrote it — so Orca adopts
-  // the file as the new system default instead of restoring a stale snapshot.
+  // Why: creds Orca last wrote to the shared file; a mismatch on managed→default transition means an external login overwrote it, so adopt it as the new default.
   private lastWrittenCredentialsJson: string | null = null
   private hasMaterializedRuntimeAuth = false
   private hasLastWrittenOauthAccount = false
@@ -217,17 +212,13 @@ export class ClaudeRuntimeAuthService {
               previousManagedOauthAccount
             )
           ) {
-            // Why: switching away while Claude is live must preserve verified
-            // token refreshes before replacing the shared runtime credentials.
+            // Why: switching away while Claude is live must preserve verified token refreshes before replacing shared runtime credentials.
             await this.writeManagedCredentials(
               previousAccount,
               outgoingReadBackResult.runtimeCredentialsJson
             )
           } else {
-            // Why: Claude's runtime credential blob can lack enough identity
-            // proof to attribute a live-session refresh. Do not persist that
-            // unverified blob, but also do not block the user from moving new
-            // terminals to the selected managed account.
+            // Why: the runtime blob may lack identity proof for a live-session refresh; skip persisting it, but still let new terminals move to the account.
             console.warn(
               '[claude-runtime-auth] Skipping unverified live Claude auth read-back while switching accounts'
             )
@@ -297,9 +288,7 @@ export class ClaudeRuntimeAuthService {
         })
         return
       }
-      // Why: WSL managed Claude accounts are already isolated by their Linux
-      // CLAUDE_CONFIG_DIR. Materializing them into Windows ~/.claude would mix
-      // two runtime auth stores and break the Terminal-default runtime contract.
+      // Why: WSL managed accounts are isolated by their Linux CLAUDE_CONFIG_DIR; materializing into Windows ~/.claude would mix two auth stores.
       this.clearLastWrittenRuntimeState()
       return
     }
@@ -364,10 +353,7 @@ export class ClaudeRuntimeAuthService {
       )
     }
 
-    // Why: Claude CLI refreshes expired OAuth tokens and writes them back to
-    // .credentials.json. If we detect the runtime file differs from what Orca
-    // last wrote, the CLI must have refreshed — so we preserve those tokens
-    // back to managed storage before overwriting runtime with managed state.
+    // Why: the CLI writes refreshed tokens to .credentials.json; if runtime differs from our last write, preserve them to managed storage before overwriting.
     if (this.lastSyncedAccountId === activeAccount.id) {
       if (this.skipNextReadBackForAccountId === activeAccount.id) {
         this.skipNextReadBackForAccountId = null
@@ -383,9 +369,7 @@ export class ClaudeRuntimeAuthService {
         } else if (
           readBackResult.status === 'rejected' &&
           readBackResult.runtimeCredentialsChanged &&
-          // Why: a live Claude that lost a refresh-token race wipes its runtime
-          // blob (empty tokens). Preserving that wreckage would leave every new
-          // session logged out — rematerialize managed credentials instead.
+          // Why: a live Claude that lost a refresh race can wipe its runtime blob (empty tokens); preserving that would log out every new session.
           readBackResult.hasValidChangedRuntimeCredentials &&
           hasLiveClaudePtys()
         ) {
@@ -398,13 +382,11 @@ export class ClaudeRuntimeAuthService {
               this.readManagedOauthAccount(activeAccount)
             )
           ) {
-            // Why: this Claude process was launched under the active managed
-            // account, but persistence still needs positive account proof.
+            // Why: this Claude launched under the active managed account, but persistence still needs positive account proof.
             await this.writeManagedCredentials(activeAccount, readBackResult.runtimeCredentialsJson)
             credentialsJson = readBackResult.runtimeCredentialsJson
           } else {
-            // Why: while Claude is running, an unknown refresh can still belong
-            // to a live session. Rewriting stale managed auth logs that session out.
+            // Why: while Claude runs, an unknown refresh may belong to a live session; rewriting stale managed auth logs it out.
             console.warn(
               '[claude-runtime-auth] Preserving changed Claude runtime credentials while live Claude terminals are running'
             )
@@ -420,14 +402,7 @@ export class ClaudeRuntimeAuthService {
       this.skipNextReadBackForAccountId = null
     }
 
-    // Why: own the OAuth refresh whenever no live `claude` owns these
-    // credentials — both switching into an account and re-syncing the active
-    // account with an expired token. A single-use refresh token is rotated and
-    // persisted to managed storage atomically before we materialize it, so the
-    // runtime never gets a stale token that fails with invalid_grant. Skipped
-    // entirely while a Claude PTY is live: that process owns the credentials
-    // and refreshing here would race its own rotation (double-rotation
-    // invalidates one copy) — the read-back above preserves its refresh instead.
+    // Why: rotate+persist the single-use token to managed storage before materializing (else runtime gets a stale token that fails invalid_grant); skip while a live PTY owns the creds since refreshing would double-rotate it (invalidating one copy) — read-back preserves its refresh instead.
     const liveClaudePtys = hasLiveClaudePtys()
     if (liveClaudePtys && isOauthTokenExpiring(credentialsJson)) {
       this.managedRefreshDeferredByLivePtyAccountId = activeAccount.id
@@ -445,8 +420,7 @@ export class ClaudeRuntimeAuthService {
     const paths = this.pathResolver.getRuntimePaths()
     this.writeRuntimeCredentials(credentialsJson)
     if (process.platform === 'darwin') {
-      // Why: Claude Code 2.1+ reads the scoped service, while older builds read
-      // the legacy unsuffixed service. Runtime switching must satisfy both.
+      // Why: Claude Code 2.1+ reads the scoped service, older builds the legacy unsuffixed one; runtime switching must satisfy both.
       try {
         await writeActiveClaudeKeychainCredentialsForRuntime(credentialsJson, paths.configDir)
       } catch (error) {
@@ -469,10 +443,7 @@ export class ClaudeRuntimeAuthService {
     this.hasMaterializedRuntimeAuth = true
   }
 
-  // Why: called by ClaudeAccountService before syncForCurrentSelection() after
-  // re-auth or add-account. Those flows write fresh tokens to managed storage,
-  // so the read-back must be skipped to avoid overwriting them with stale
-  // runtime tokens.
+  // Why: re-auth/add-account write fresh managed tokens; skip the next read-back so stale runtime tokens can't overwrite them.
   clearLastWrittenCredentialsJson(
     accountId = this.store.getSettings().activeClaudeManagedAccountId
   ): void {
@@ -526,14 +497,7 @@ export class ClaudeRuntimeAuthService {
         if (match.kind !== 'matched') {
           continue
         }
-        // Why: on cold app start we cannot tell whether matching runtime
-        // credentials are a fresh CLI refresh or stale state. Adopt when the
-        // token expiry proves runtime is newer, OR the refresh token rotated
-        // and runtime is not provably older. A rotated refresh token with
-        // equal/missing expiry is a genuine CLI refresh we'd otherwise drop
-        // (stranding a stale managed token); but if expiry proves runtime is
-        // older, managed already holds the newer token (e.g. a prior read-back
-        // or proactive refresh), so reject it.
+        // Why: on cold start we can't tell a fresh CLI refresh from stale runtime creds; adopt only when expiry or a rotated refresh token proves runtime is newer than managed.
         if (this.lastWrittenCredentialsJson === null) {
           const fresher = this.runtimeCredentialsAreFresher(
             runtimeContents.credentialsJson,
@@ -587,16 +551,13 @@ export class ClaudeRuntimeAuthService {
       }
       return { status: 'persisted' }
     } catch (error) {
-      // Why: read-back is best-effort. A transient fs error must not block the
-      // forward sync path — the worst case is one more stale-token cycle, which
-      // is strictly better than failing the entire sync.
+      // Why: read-back is best-effort; a transient fs error must not block forward sync (worst case: one more stale-token cycle).
       console.warn('[claude-runtime-auth] Failed to read back refreshed tokens:', error)
       return {
         status: 'rejected',
         runtimeCredentialsChanged:
           this.runtimeCredentialsChangedSinceLastWrite(baselineCredentialsJson),
-        // Why: an fs error hides whether a live session's refresh is present,
-        // so err toward preserving runtime state like before.
+        // Why: an fs error hides whether a live session's refresh is present, so err toward preserving runtime state.
         hasValidChangedRuntimeCredentials: true
       }
     }
@@ -723,8 +684,7 @@ export class ClaudeRuntimeAuthService {
     settings = this.store.getSettings()
   ): ClaudeAccountSelectionTarget {
     if (process.platform === 'win32' && settings.localAccountRuntime === 'wsl') {
-      // Why: account auth defaults follow account runtime settings, not hidden
-      // legacy terminal WSL settings that can outlive the Terminal UI control.
+      // Why: auth defaults follow account runtime settings, not legacy terminal WSL settings that can outlive the Terminal UI.
       return { runtime: 'wsl', wslDistro: settings.localAccountWslDistro ?? null }
     }
     return { runtime: 'host' }
@@ -799,9 +759,7 @@ export class ClaudeRuntimeAuthService {
       return 'mismatch'
     }
 
-    // Why: this mirrors the Codex runtime-home guard. If another Claude login
-    // or missed live process rewrites shared runtime credentials, do not
-    // persist those credentials into the selected managed account.
+    // Why: mirrors the Codex runtime-home guard; don't persist shared runtime creds into the managed account if another login rewrote them.
     const selectedOrganizationUuid = this.normalizeField(
       account.organizationUuid ??
         managedIdentity?.organizationUuid ??
@@ -1075,14 +1033,11 @@ export class ClaudeRuntimeAuthService {
 
   /**
    * Proactively refresh an account's OAuth token and persist the rotation to
-   * managed storage. Returns the refreshed credentials JSON when a rotation was
-   * stored, or null when no refresh happened (token still valid, no refresh
-   * token, or the network call failed — in which case the caller keeps the
-   * existing credentials, never worse than before).
+   * managed storage. Returns the refreshed credentials JSON, or null when no
+   * refresh happened (token valid, no refresh token, or network failure).
    *
-   * Caller guarantees this account is not the live/active one and runs inside
-   * the serialized mutation queue, so a single-use refresh token can't be
-   * rotated concurrently.
+   * Caller guarantees this account isn't the live/active one and runs inside the
+   * serialized mutation queue, so the single-use refresh token can't rotate concurrently.
    */
   private async refreshManagedAccountTokenIfNeeded(
     account: ClaudeManagedAccount,
@@ -1271,9 +1226,7 @@ export class ClaudeRuntimeAuthService {
       previouslyWrittenCredentialsJson
     )
     let hasCredentialSurfaceOwnership = fileCredentialsOwned
-    // Why: runtime auth restore is two-phase: prove ownership before mutating
-    // any surface, then restore OAuth first. If OAuth fails, the credential
-    // proof remains intact for retry.
+    // Why: prove ownership before mutating anything, and restore OAuth first so a failure leaves the credential proof intact for retry.
     this.lastWrittenCredentialsJson = previouslyWrittenCredentialsJson
     let scopedSnapshot: ClaudeKeychainSnapshotValue | null = null
     let legacySnapshot: ClaudeKeychainSnapshotValue | null = null
@@ -1326,9 +1279,7 @@ export class ClaudeRuntimeAuthService {
     if (this.hasLastWrittenOauthAccount) {
       return this.lastWrittenOauthAccount
     }
-    // Why: persisted managed metadata is an account identity hint, not proof
-    // that Orca wrote .claude.json. Use it only after another surface proves
-    // the current runtime auth still belongs to the managed account.
+    // Why: managed metadata hints identity but isn't proof Orca wrote .claude.json; use only after a credential surface proves ownership.
     if (hasCredentialSurfaceOwnership && ownedOauthAccount !== undefined) {
       return ownedOauthAccount
     }
@@ -1779,10 +1730,7 @@ export class ClaudeRuntimeAuthService {
   private writeRuntimeCredentials(contents: string): void {
     const credentialsPath = this.pathResolver.getRuntimePaths().credentialsPath
     mkdirSync(dirname(credentialsPath), { recursive: true })
-    // Why: repeated Claude spawns sync auth, but credentials rarely change.
-    // Skipping unchanged rewrites avoids Windows EPERM contention in #1507.
-    // Still verify the file because another Claude process may have rewritten
-    // runtime credentials since Orca last materialized them.
+    // Why: skip unchanged rewrites to dodge Windows EPERM contention (#1507); re-verify the file since another Claude may have rewritten it.
     if (
       this.lastWrittenCredentialsJson === contents &&
       this.fileContentsEqual(credentialsPath, contents)
@@ -1838,8 +1786,7 @@ export class ClaudeRuntimeAuthService {
         return parsed as Record<string, unknown>
       }
     } catch {
-      // Why: invalid config is an unknown external state. Replacing it with a
-      // fresh object could silently erase user or Claude-owned settings.
+      // Why: invalid config is unknown external state; return null so we don't erase user or Claude-owned settings.
       return null
     }
     return null
diff --git a/src/main/claude/hook-service.ts b/src/main/claude/hook-service.ts
index 980c9604bec..95304f19fc6 100644
--- a/src/main/claude/hook-service.ts
+++ b/src/main/claude/hook-service.ts
@@ -54,24 +54,14 @@ function getManagedScript(
       'setlocal',
       ...(options.skipWhenDevinImportsClaude
         ? [
-            // Why: Devin imports .claude hooks by default. Skip Orca's managed
-            // Claude hook there so status posts stay attributed to Devin.
+            // Why: Devin imports .claude hooks by default; skip Orca's managed hook there so status posts stay attributed to Devin.
             `if not "%DEVIN_PROJECT_DIR%"=="" goto :${WINDOWS_HOOK_STDIN_DRAIN_LABEL}`
           ]
         : []),
-      // Why: the endpoint file holds the *live* port/token for this Orca
-      // install. A PTY that survived an Orca restart has stale PORT/TOKEN
-      // baked into its env from the old instance — loading `endpoint.cmd`
-      // (`set KEY=VALUE` lines) via `call` refreshes them so the hook
-      // reaches the current server. Falls through to PTY env if the file
-      // is missing (first run / pre-endpoint-file / running outside Orca).
+      // Why: call the endpoint file to refresh port/token — a PTY that survived an Orca restart carries stale env; falls through to PTY env if missing.
       'if defined ORCA_AGENT_HOOK_ENDPOINT if exist "%ORCA_AGENT_HOOK_ENDPOINT%" call "%ORCA_AGENT_HOOK_ENDPOINT%" 2>nul',
       ...buildWindowsHookEnvironmentGuardLines(),
-      // Why: post via curl.exe, not a second PowerShell. Claude's launcher is
-      // already an encoded PowerShell command (Git Bash needs it to survive
-      // spaces); a PowerShell post on top of that meant two interpreter
-      // startups per hook. The post runs inside the .cmd (cmd.exe context), so
-      // curl works the same here as for the POSIX/Codex hooks.
+      // Why: post via curl.exe, not PowerShell — Claude's launcher is already encoded PowerShell, so a PS post would double interpreter startups per hook.
       buildWindowsAgentHookCurlPostCommand('claude'),
       'exit /b 0',
       ...buildWindowsHookStdinDrainEpilogue(),
@@ -84,40 +74,22 @@ function getManagedScript(
     ...buildPosixHookPayloadCapture(),
     ...(options.skipWhenDevinImportsClaude
       ? [
-          // Why: Devin imports .claude hooks by default. Skip Orca's managed
-          // Claude hook there so status posts stay attributed to Devin.
+          // Why: Devin imports .claude hooks by default; skip Orca's managed hook there so status posts stay attributed to Devin.
           'if [ -n "$DEVIN_PROJECT_DIR" ]; then',
           '  exit 0',
           'fi'
         ]
       : []),
-    // Why: the endpoint file holds the *live* port/token for this Orca
-    // install. PTYs that survive an Orca restart have stale PORT/TOKEN
-    // baked into their env from the old instance — sourcing the file here
-    // lets us reach the new server. Falls back to PTY env if the file is
-    // missing (first-run / pre-endpoint-file scripts / running outside Orca).
-    // Why: suppress stderr on the `.` builtin. A TOCTOU race (endpoint unlinked
-    // between the `[ -r ]` test and the source) or a malformed line (e.g. CRLF
-    // bled in from a cross-platform userData copy) would otherwise print a
-    // parse error that agent transcripts could surface. Stale coords → dead
-    // port → silent-fail is the documented fail-open path anyway — the env-var
-    // guards below handle the empty PORT/TOKEN case — so swallowing the noise
-    // here is strictly better than leaking shell errors into the hook output.
-    // `|| :` defends against an eventual `set -e` in an outer script context
-    // (not present today) aborting the hook on a parse error.
+    // Why: source the endpoint file to refresh port/token — a PTY that survived an Orca restart carries stale env; falls back to PTY env if missing.
+    // Why: suppress stderr / || : so a stray parse error (TOCTOU or CRLF) can't leak into hook output or trip an outer set -e.
     'if [ -n "$ORCA_AGENT_HOOK_ENDPOINT" ] && [ -r "$ORCA_AGENT_HOOK_ENDPOINT" ]; then',
     '  . "$ORCA_AGENT_HOOK_ENDPOINT" 2>/dev/null || :',
     'fi',
     'if [ -z "$ORCA_AGENT_HOOK_PORT" ] || [ -z "$ORCA_AGENT_HOOK_TOKEN" ] || [ -z "$ORCA_PANE_KEY" ]; then',
     '  exit 0',
     'fi',
-    // Why: worktreeId embeds a filesystem path, so hand-building JSON in POSIX
-    // shell is not safe once a path contains quotes or newlines. Post the raw
-    // hook payload plus metadata as form fields and let the receiver parse it.
-    // Timeout caps best-effort hook posts if the local listener stalls.
-    // Why: pipe payload to curl's stdin (`payload@-`) instead of an inline
-    // `payload=$VALUE` arg, so tens-of-KB tool output stays off the curl
-    // command line (EDR command-line false positives). Wire body is identical.
+    // Why: paths can hold quotes/newlines, so hand-building JSON in shell is unsafe; post the raw payload + metadata as form fields for the receiver to parse.
+    // Why: pipe payload to curl stdin (`payload@-`), not an inline arg, so large tool output stays off the command line (EDR false positives).
     'printf \'%s\' "$payload" | curl -sS -X POST "http://127.0.0.1:${ORCA_AGENT_HOOK_PORT}/hook/claude" \\',
     '  --connect-timeout 0.5 --max-time 1.5 \\',
     '  -H "Content-Type: application/x-www-form-urlencoded" \\',
@@ -155,10 +127,7 @@ export class ClaudeHookService {
       }
     }
 
-    // Why: Report `partial` when only some managed events are registered so the
-    // sidebar surfaces a degraded install rather than a false-positive
-    // `installed`. Each CLAUDE_EVENTS entry must contain the managed command for
-    // the integration to function end-to-end.
+    // Why: report `partial` when only some events are registered so the sidebar shows a degraded install, not a false-positive `installed`.
     const command = getManagedCommand(scriptPath)
     const missing: string[] = []
     let presentCount = 0
@@ -219,24 +188,13 @@ export class ClaudeHookService {
     return this.getStatus()
   }
 
-  // Why: install Orca's Claude hook settings on the remote box rather than the
-  // local machine. Caller passes the user's SFTP handle plus the resolved
-  // remote `$HOME`; POSIX-only by design (Windows-remote deferred).
+  // Why: install the Claude hook on the remote box (via SFTP); POSIX-only by design (Windows-remote deferred).
   async installRemote(sftp: SFTPWrapper, remoteHome: string): Promise<AgentHookInstallStatus> {
-    // Why: remote-Windows is out of scope for v1 — we ship POSIX-shaped paths
-    // and a `.sh` managed script body. The remote platform is gated by the
-    // relay's capability RPC at a higher layer; we cannot detect it from
-    // `process.platform` here (that's the local box).
+    // Why: remote-Windows is out of scope; ship POSIX paths. process.platform here is the local box, not the remote, so it can't gate this.
     const remoteConfigPath = getRemoteConfigPath(remoteHome, this.options.settings)
     const remoteScriptFileName = getPosixManagedScriptFileName(this.options.settings)
     const remoteScriptPath = `${remoteHome.replace(/\/$/, '')}/.orca/agent-hooks/${remoteScriptFileName}`
-    // Why: SFTP reads/writes fail far more often than local fs (network drops,
-    // EACCES on remote dirs, disk full, channel closed). Wrap the entire
-    // install flow in try/catch so a transient I/O failure surfaces as a
-    // structured `state: 'error'` result for the UI, not an unstructured
-    // rejection the caller has to remember to handle. A `null` config
-    // specifically means "file present but unparseable" — keep that branch
-    // distinct so the user sees an actionable message.
+    // Why: SFTP I/O fails often (network/EACCES/disk); wrap install so transient failures surface as structured state:'error' rather than an unhandled rejection.
     try {
       const config = await readHooksJsonRemote(sftp, remoteConfigPath)
       if (!config) {
@@ -249,19 +207,12 @@ export class ClaudeHookService {
         }
       }
 
-      // Why: the POSIX wrapper is identical regardless of where the script
-      // lands; only the path differs. Reuse the same wrapper helper.
+      // Why: the POSIX wrapper is identical regardless of where the script lands; only the path differs.
       const command = getRemoteManagedCommand(remoteScriptPath)
       const nextConfig = applyManagedHooks(config, command, remoteScriptFileName)
 
-      // Why: write the script first, then the settings — settings.json
-      // referencing a missing script body would fire `command not found` on
-      // every tool call until the user re-runs install. Doing it in this
-      // order means a partial-failure mid-install at worst leaves the user
-      // with a working script no settings.json points at (a no-op), instead
-      // of broken settings.json.
-      // Why: SSH remotes use POSIX `.sh` hook paths even when Orca itself is
-      // running on Windows; never derive remote script syntax from local OS.
+      // Why: write script before settings — a mid-install failure then leaves a harmless orphan script, not settings.json pointing at a missing one.
+      // Why: SSH remotes use POSIX `.sh` paths even when Orca runs on Windows; never derive remote script syntax from the local OS.
       await writeManagedScriptRemote(
         sftp,
         remoteScriptPath,
diff --git a/src/main/cli/cli-installer.ts b/src/main/cli/cli-installer.ts
index 431c04e917b..18d2fcc8f18 100644
--- a/src/main/cli/cli-installer.ts
+++ b/src/main/cli/cli-installer.ts
@@ -105,13 +105,7 @@ export class CliInstaller {
     this.processPathEnv = options.processPathEnv ?? process.env.PATH ?? process.env.Path ?? null
     this.commandPathOverride =
       options.commandPathOverride ?? process.env.ORCA_CLI_INSTALL_PATH ?? null
-    // Why: resolved once at construction — existsSync must not run on every
-    // getStatus() call (hot path). /usr/local/bin is absent by default on Apple
-    // Silicon Macs (Homebrew moved to /opt/homebrew); fall back to ~/.local/bin
-    // which is user-writable, requires no elevated permissions, and is the
-    // XDG-standard user bin dir already on PATH via shell init on arm64.
-    // defaultMacCommandPath is a test seam: it feeds into the existence check
-    // so tests can simulate arm64 without relying on the real /usr/local/bin.
+    // Why: resolved once here (getStatus is hot); /usr/local/bin is absent on Apple Silicon, so fall back to user-writable ~/.local/bin.
     const candidateMacPath = options.defaultMacCommandPath ?? DEFAULT_MAC_COMMAND_PATH
     this.macCommandPath = existsSync(dirname(candidateMacPath))
       ? candidateMacPath
@@ -202,21 +196,15 @@ export class CliInstaller {
       await this.installAppImageWrapper(status.commandPath, status.launcherPath)
       await this.removeLegacyLinuxCommandIfManaged(status.launcherPath)
     } else if (this.isWindowsPackagedBundledCommand(status.commandPath, status.launcherPath)) {
-      // Why: packaged Windows already ships resources/bin/orca.exe. Registration
-      // only owns the user PATH entry; rewriting the asset makes it recurse.
+      // Why: packaged Windows already ships resources/bin/orca.exe; registration only owns the PATH entry.
     } else {
-      // Why: mkdir stays here for the Windows wrapper path — the target dir is
-      // user-writable (%LOCALAPPDATA%) so EACCES cannot occur. The symlink path
-      // handles its own mkdir inside installSymlink so EACCES triggers the
-      // privileged-runner instead of propagating as an unhandled rejection.
+      // Why: the Windows wrapper dir is user-writable (%LOCALAPPDATA%), so mkdir here can't hit EACCES.
       await mkdir(dirname(status.commandPath), { recursive: true })
       await this.installWindowsWrapper(status.commandPath, status.launcherPath)
     }
 
     if (this.platform === 'win32') {
-      // Why: Windows shells discover commands via the user PATH, not by walking
-      // arbitrary app install directories. The CLI installer therefore owns the
-      // user-scoped PATH entry instead of assuming the desktop installer did it.
+      // Why: Windows shells find commands via user PATH, so the installer owns that entry, not the desktop installer.
       await this.ensureWindowsPathEntry(dirname(status.commandPath))
     }
 
@@ -319,12 +307,10 @@ export class CliInstaller {
       const status = await this.inspectSymlink(commandPath, launcherPath)
       if (status.state !== 'not_installed') {
         if (reachedDefaultCommandPath && !isDefaultCommandPath && status.state === 'conflict') {
-          // Why: a non-Orca command after an empty/default install slot can be
-          // shadowed safely by installing there; no user file needs replacing.
+          // Why: a non-Orca command after an empty default slot can be shadowed by installing there; no user file replaced.
           continue
         }
-        // Why: PATH lookup is first-match-wins; use the executable command the
-        // shell will actually run, while preserving conflicts that shadow Orca.
+        // Why: PATH lookup is first-match-wins; return the command the shell will actually run, preserving shadowing conflicts.
         return commandPath
       }
     }
@@ -345,8 +331,7 @@ export class CliInstaller {
     }
 
     if (!this.isPackaged) {
-      // Why: default dev registration is a separate command, while tests and
-      // diagnostics can still exercise production paths via commandPathOverride.
+      // Why: dev uses a separate command; tests/diagnostics still reach production paths via commandPathOverride.
       if (this.platform === 'darwin') {
         return `/usr/local/bin/${DEV_COMMAND_NAME}`
       }
@@ -363,18 +348,13 @@ export class CliInstaller {
     }
 
     if (this.platform === 'linux') {
-      // Why: Linux does not have a single privileged global shell-command flow
-      // equivalent to macOS's /usr/local/bin integration. ~/.local/bin is the
-      // least surprising user-scoped location that many distros already expose.
-      // Why `orca-ide`: GNOME Orca (the screen reader) ships /usr/bin/orca on
-      // most Linux distros. Using `orca-ide` avoids shadowing that system
-      // command, matching the executableName already used for the Electron binary.
+      // Why: Linux lacks a privileged global command flow; ~/.local/bin is the least-surprising user-scoped dir.
+      // Why `orca-ide`: GNOME Orca ships /usr/bin/orca, so avoid shadowing that screen reader.
       return join(this.homePath, '.local', 'bin', LINUX_COMMAND_NAME)
     }
 
     if (this.platform === 'win32') {
-      // Why: NSIS /D installs can live outside LOCALAPPDATA. The packaged
-      // resources directory is the authoritative native launcher location.
+      // Why: NSIS /D installs can live outside LOCALAPPDATA, so use the packaged resources dir as authoritative.
       return getBundledLauncherPath(this.platform, this.resourcesPath)
     }
 
@@ -412,10 +392,7 @@ export class CliInstaller {
       if (status.state === 'stale') {
         await unlink(status.commandPath as string)
       }
-      // Why: mkdir is placed here (not in install()) so that an EACCES/EPERM
-      // failure — e.g. /usr/local/bin absent on Intel Mac — falls into the
-      // privileged-runner catch below instead of surfacing as an unhandled
-      // rejection that leaves Settings silently showing "not installed".
+      // Why: mkdir stays here (not install()) so an EACCES falls into the privileged-runner catch below.
       await mkdir(dirname(status.commandPath as string), { recursive: true })
       await symlink(status.launcherPath as string, status.commandPath as string)
     } catch (error) {
@@ -423,10 +400,7 @@ export class CliInstaller {
         throw error
       }
 
-      // Why: macOS shell-command registration should behave like VS Code and
-      // place a stable symlink in /usr/local/bin instead of rewriting shell rc
-      // files. Fallback to an elevated shell command keeps the public command
-      // stable even when the app lacks direct write access to that directory.
+      // Why: fall back to an elevated shell to place the /usr/local/bin symlink (VS Code-style) when direct write is denied.
       await this.privilegedRunner(
         `mkdir -p ${quoteShell(dirname(status.commandPath as string))} && ` +
           `ln -sfn ${quoteShell(status.launcherPath as string)} ${quoteShell(status.commandPath as string)}`
@@ -465,8 +439,7 @@ export class CliInstaller {
         return
       }
 
-      // Why: after the Linux command rename, the old Orca-owned `orca` symlink
-      // would keep shadowing GNOME Orca even though the new command is installed.
+      // Why: after the Linux command rename, the old `orca` symlink would keep shadowing GNOME Orca.
       await unlink(legacyCommandPath)
     } catch (error) {
       if (isMissingError(error)) {
@@ -492,8 +465,7 @@ export class CliInstaller {
       return true
     }
 
-    // Why: AppImage upgrades can leave a legacy symlink into a now-gone FUSE
-    // mount; the stable AppImage path is not a sibling of that old target.
+    // Why: AppImage upgrades can strand a legacy symlink into a now-gone FUSE mount that isn't a sibling of the stable path.
     return /(?:^|[/\\])resources[/\\]bin[/\\]orca$/.test(resolvedTarget)
   }
 
@@ -502,8 +474,7 @@ export class CliInstaller {
   }
 
   private async installAppImageWrapper(commandPath: string, appImagePath: string): Promise<void> {
-    // Why: unlike macOS symlink install, AppImage uses the user-writable Linux
-    // command dir and must create it before writing the wrapper file.
+    // Why: the AppImage command dir is user-writable, so create it before writing the wrapper.
     await mkdir(dirname(commandPath), { recursive: true })
     await writeFile(commandPath, buildAppImageCliWrapper(appImagePath), {
       encoding: 'utf8',
@@ -644,8 +615,7 @@ export class CliInstaller {
     }
 
     if (this.platform === 'darwin') {
-      // Why: prior packaged installs can leave a symlink to an older Orca.app
-      // resources launcher, but arbitrary user-owned symlinks must not be replaced.
+      // Why: reclaim symlinks to an older Orca.app launcher, but never replace arbitrary user-owned symlinks.
       return /(?:^|[/\\])[^/\\]+\.app[/\\]Contents[/\\]Resources[/\\]bin[/\\][^/\\]+$/.test(
         resolvedTarget
       )
@@ -670,8 +640,7 @@ export class CliInstaller {
     const siblingDevUserDataPath = `${packagedUserDataPath}-dev`
     const siblingDevLauncherDir = resolve(siblingDevUserDataPath, ...DEV_LAUNCHER_DIR)
 
-    // Why: development builds generate launchers under the sibling `*-dev`
-    // profile; packaged Orca must be able to reclaim that public command.
+    // Why: dev builds generate launchers under the sibling `*-dev` profile; packaged Orca must reclaim that command.
     return (
       basename(siblingDevUserDataPath) === `${basename(packagedUserDataPath)}-dev` &&
       isPathInsideOrEqual(siblingDevLauncherDir, resolvedTarget)
@@ -901,13 +870,11 @@ export class CliInstaller {
     if (result.state === 'success') {
       return { value: result.value, expandable: result.expandable }
     }
-    // Why: PATH updates are read-modify-write; continuing after an unknown read
-    // could replace the user's existing PATH with an incomplete value.
+    // Why: PATH is read-modify-write; continuing after a failed read could clobber the user's PATH with a partial value.
     throw new Error(`${result.detail} No PATH changes were made.`)
   }
 
-  // Why: raw PowerShell errors reach the UI, so translate denied PATH writes
-  // while preserving the original diagnostic as the error cause.
+  // Why: raw PowerShell errors reach the UI, so translate denied PATH writes (keeping the original as cause).
   private async writeWindowsUserPathEntry(
     value: string,
     pathDirectory: string,
@@ -954,10 +921,7 @@ async function ensureDevLauncher(args: {
   )
   await mkdir(dirname(launcherPath), { recursive: true })
 
-  // Why: packaged Orca ships real platform launchers under resources/bin, but
-  // development builds do not have that stable asset layout. Generating a
-  // launcher in userData lets us validate the shell-command flow without
-  // changing the packaged registration contract.
+  // Why: dev builds lack the packaged resources/bin launcher, so generate one in userData to validate the flow.
   const content =
     args.platform === 'win32'
       ? buildWindowsDevLauncher(args.execPath, args.cliEntryPath, args.userDataPath)
@@ -967,9 +931,7 @@ async function ensureDevLauncher(args: {
     mode: args.platform === 'win32' ? undefined : 0o755
   })
   if (args.commandName === DEV_COMMAND_NAME && args.platform !== 'win32') {
-    // Why: dev PTYs prepend userData/cli/bin to PATH, and product-owned
-    // commands are documented as `orca ...`. Keep that local alias fresh
-    // without claiming the global production command.
+    // Why: dev PTYs prepend this dir to PATH, so keep a local `orca` alias without claiming the global command.
     await writeFile(join(dirname(launcherPath), 'orca'), content, {
       encoding: 'utf8',
       mode: 0o755
@@ -1045,9 +1007,7 @@ function extractManagedUnixLauncherTarget(content: string): string | null {
     return null
   }
 
-  // Why: older dev installs wrote a generated shell launcher directly to
-  // /usr/local/bin/orca. Treat only Orca's compiled CLI entrypoints as managed;
-  // arbitrary user scripts that happen to launch Electron must stay conflicts.
+  // Why: only Orca's compiled CLI entrypoints count as managed; arbitrary Electron-launching scripts stay conflicts.
   return /(?:^|[/\\])(?:out|app\.asar\.unpacked[/\\]out)[/\\]cli[/\\]index\.js$/.test(cliPath)
     ? cliPath
     : null
@@ -1153,8 +1113,7 @@ function isMissingError(error: unknown): boolean {
   )
 }
 
-// Why: localized permission errors retain these .NET/ACL markers even when
-// their human-readable PowerShell text is mojibake.
+// Why: localized permission errors keep these .NET/ACL markers even when the PowerShell text is mojibake.
 function isWindowsUserPathPermissionError(error: unknown): boolean {
   if (!(error instanceof Error)) {
     return false
@@ -1199,9 +1158,7 @@ async function writeWindowsUserPath(value: string): Promise<void> {
   await runWindowsPathCommand([
     '-NoProfile',
     '-Command',
-    // Why: PATH registration must stay user-scoped on Windows so the Orca
-    // desktop app can manage the public shell command without requiring
-    // elevation or mutating machine-wide environment state.
+    // Why: user-scoped PATH avoids requiring elevation or mutating machine-wide state.
     `[Environment]::SetEnvironmentVariable('Path', ${quotePowerShell(value)}, 'User')`
   ])
 }
@@ -1224,8 +1181,7 @@ function runWindowsPathCommand(args: string[]): Promise<string> {
       resolve(stdout)
     }
 
-    // Why: Windows PATH reads/writes back CLI Settings; wedged PowerShell must
-    // not keep command registration status or install/remove pending forever.
+    // Why: bound wedged PowerShell so PATH reads/writes can't leave CLI registration pending forever.
     const timeout = setTimeout(() => {
       child?.kill()
       finish(new Error(`Windows PATH command timed out after ${WINDOWS_PATH_WRITE_TIMEOUT_MS}ms.`))
diff --git a/src/main/codex-accounts/runtime-home-service.ts b/src/main/codex-accounts/runtime-home-service.ts
index 29e181bd775..5c6e42f63d4 100644
--- a/src/main/codex-accounts/runtime-home-service.ts
+++ b/src/main/codex-accounts/runtime-home-service.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: this service owns the single runtime-home
-contract for Codex inside Orca. Keeping path resolution, system-default
-snapshots, auth materialization, and recovery together prevents account-switch
-semantics from drifting across PTY launch, login, and quota fetch paths. */
+/* eslint-disable max-lines -- Why: keeps Codex's whole runtime-home contract in one place so account-switch semantics don't drift across launch/login/quota paths. */
 import {
   appendFileSync,
   copyFileSync,
@@ -92,20 +89,11 @@ type CodexReadBackMatch =
   | { kind: 'none' | 'ambiguous' }
 
 export class CodexRuntimeHomeService {
-  // Why: tracks whether the runtime auth.json currently mirrors a managed
-  // account. When null, runtime auth follows the user's system-default
-  // ~/.codex/auth.json instead of being written back to a managed account.
+  // Which managed account runtime auth.json mirrors; null means it follows system-default ~/.codex instead of a managed account.
   private lastSyncedAccountId: string | null = null
-  // Why: tracks the auth.json content Orca last wrote to the runtime CODEX_HOME.
-  // Between syncs, if the file differs, Codex CLI refreshed the token — so
-  // Orca writes back the refreshed token to managed storage before overwriting.
-  // On managed→system-default transition, if the file differs, an external
-  // login (e.g. `codex auth login`) overwrote it — so Orca adopts the file as
-  // the new system default instead of restoring a stale snapshot.
+  // Last auth.json Orca wrote to the runtime home; a later diff signals an out-of-band change (Codex token refresh, or external login to adopt).
   private lastWrittenAuthJson: string | null = null
-  // Why: WSL terminals have their own stable runtime homes per distro. They
-  // cannot share the host baseline or host sync can make stale WSL auth look
-  // newer than managed storage.
+  // Why: WSL terminals have per-distro runtime homes; sharing the host baseline can make stale WSL auth look newer than managed storage.
   private readonly lastWrittenWslAuthJsonByDistro = new Map<string, string | null>()
   private readonly lastSyncedWslAccountIdByDistro = new Map<string, string | null>()
   private readonly wslRuntimeHomePathByDistro = new Map<string, string>()
@@ -124,20 +112,13 @@ export class CodexRuntimeHomeService {
       settings.codexManagedAccounts,
       normalizeCodexRuntimeSelection(settings).host
     )
-    // Why: WSL-managed homes are never materialized into host ~/.codex.
-    // Treating one as "last synced" makes cold start look like a host-account
-    // transition and can restore/delete host auth that Orca never touched.
+    // Why: WSL-managed homes never touch host ~/.codex; treating one as "last synced" makes cold start mangle host auth Orca never touched.
     this.lastSyncedAccountId = this.getWslManagedHomePath(activeAccount)
       ? null
       : normalizeCodexRuntimeSelection(settings).host
   }
 
-  /**
-   * Materializes the runtime home needed before launching the CLI.
-   *
-   * Historical session bridging is requested in the background so launch setup
-   * returns as soon as the active runtime home is ready.
-   */
+  /** Materializes the runtime home needed before launching the CLI (session bridging runs in the background so setup returns once it's ready). */
   prepareForCodexLaunch(target?: CodexAccountSelectionTarget): string | null {
     if (target?.runtime === 'wsl') {
       const wslTarget = this.resolveWslDefaultTarget(target)
@@ -150,8 +131,7 @@ export class CodexRuntimeHomeService {
     this.syncForCurrentSelection()
     syncSystemCodexResourcesIntoManagedHome()
     syncSystemConfigIntoManagedCodexHome()
-    // Why: historical Codex sessions can be large; bridge them after launch
-    // setup so starting a fresh Codex TUI never waits on a full tree walk.
+    // Why: sessions can be large; bridge them after launch so starting a fresh TUI never waits on a full tree walk.
     void startSystemCodexSessionBridgeInBackground(
       {},
       resolveHostCodexSessionSourceHome(this.store.getSettings())
@@ -171,16 +151,14 @@ export class CodexRuntimeHomeService {
     if (!distro) {
       return
     }
-    // Why: history-only override lets custom-CODEX_HOME users bridge from their
-    // real home; falls back to <wslHome>/.codex, which auth/config still use.
+    // Why: history-only override lets custom-CODEX_HOME users bridge from their real home; falls back to <wslHome>/.codex.
     const systemCodexHomePath =
       resolveWslCodexSessionSourceHome(this.store.getSettings(), distro) ??
       this.getWslSystemCodexHomePath({ runtime: 'wsl', wslDistro: distro })
     if (!systemCodexHomePath || systemCodexHomePath === runtimeHomePath) {
       return
     }
-    // Why: WSL history must be hardlinked inside the distro; host-side links
-    // cannot bridge Windows and WSL filesystems in a resume-visible way.
+    // Why: WSL history must be hardlinked inside the distro; host-side links can't bridge Windows and WSL filesystems in a resume-visible way.
     void startWslCodexSessionBridgeInBackground({
       distro,
       systemCodexHomePath,
@@ -240,8 +218,7 @@ export class CodexRuntimeHomeService {
     if (!systemHomePath || systemHomePath === runtimeHomePath) {
       return
     }
-    // Why: WSL uses a distro-local CODEX_HOME, so host resource mirroring
-    // cannot provide the distro user's global instructions.
+    // Why: WSL uses a distro-local CODEX_HOME, so host resource mirroring can't provide the distro user's global instructions.
     syncCodexGlobalInstructionsIntoManagedHome({
       systemHomePath,
       managedHomePath: runtimeHomePath
@@ -313,10 +290,7 @@ export class CodexRuntimeHomeService {
           }
         })
       }
-      // Why: only restore the system-default mirror when transitioning FROM a
-      // managed account. When no managed account was ever active, later syncs
-      // should mirror the user's current ~/.codex/auth.json instead of
-      // replaying an old snapshot on every PTY launch / rate-limit fetch.
+      // Why: only restore the system-default mirror when leaving a managed account; otherwise later syncs mirror current ~/.codex instead of replaying an old snapshot.
       if (this.lastSyncedAccountId !== null) {
         this.restoreSystemDefaultSnapshot({
           detectExternalLogin: outgoingReadBackResult !== 'rejected'
@@ -332,16 +306,12 @@ export class CodexRuntimeHomeService {
         ) {
           this.restoreSystemDefaultSnapshot({ detectExternalLogin: false })
         } else if (logoutMarkerStatus.kind === 'system-default-changed') {
-          // Why: a real ~/.codex logout after a local runtime logout should
-          // keep runtime auth absent instead of restoring the stale snapshot.
+          // Why: a real ~/.codex logout after a local runtime logout should keep runtime auth absent, not restore the stale snapshot.
           this.captureSystemDefaultSnapshot({ force: true })
           this.persistRuntimeLogoutMarker(null)
           this.lastWrittenAuthJson = null
         } else if (this.lastWrittenAuthJson === null) {
-          // Why: Orca-launched Codex sessions now use an Orca-owned CODEX_HOME
-          // even when no managed account is selected. Seed that runtime home
-          // from the user's current system-default auth once so dev/prod Orca
-          // terminals stay logged in without mutating ~/.codex on startup.
+          // Why: unmanaged sessions use an Orca-owned CODEX_HOME; seed it once from system-default auth so terminals stay logged in without mutating ~/.codex.
           this.restoreSystemDefaultSnapshot({ detectExternalLogin: false })
         } else {
           this.persistRuntimeLogoutMarker()
@@ -376,10 +346,7 @@ export class CodexRuntimeHomeService {
       this.captureSystemDefaultSnapshot({ force: true })
     }
 
-    // Why: Codex CLI refreshes expired OAuth tokens in CODEX_HOME/auth.json.
-    // If we detect the runtime file differs from what Orca last wrote, the CLI
-    // must have refreshed — so we preserve those tokens back to managed
-    // storage before overwriting runtime with managed state.
+    // Why: Codex refreshes OAuth tokens in the runtime auth.json; if it differs from Orca's last write, read those back to managed storage before overwriting.
     if (this.lastSyncedAccountId === activeAccount.id) {
       if (this.skipNextReadBackForAccountId === activeAccount.id) {
         this.skipNextReadBackForAccountId = null
@@ -397,10 +364,7 @@ export class CodexRuntimeHomeService {
     this.writeRuntimeAuth(readFileSync(activeAuthPath, 'utf-8'))
   }
 
-  // Why: called by CodexAccountService before syncForCurrentSelection() after
-  // re-auth or add-account. Those flows write fresh tokens to managed storage,
-  // so the read-back must be skipped to avoid overwriting them with stale
-  // runtime tokens.
+  // Why: re-auth/add-account write fresh managed tokens, so skip the next read-back to avoid clobbering them with stale runtime tokens.
   clearLastWrittenAuthJson(
     accountId = normalizeCodexRuntimeSelection(this.store.getSettings()).host
   ): void {
@@ -463,8 +427,7 @@ export class CodexRuntimeHomeService {
         }
         return 'rejected'
       }
-      // Why: after app restart, Orca has no last-written baseline. Identity
-      // alone cannot prove runtime auth is newer than managed storage.
+      // Why: after restart there's no last-written baseline, so identity alone can't prove runtime auth is newer than managed storage.
       if (
         lastWrittenAuthJson === null &&
         !this.runtimeAuthIsFresher(runtimeContents, match.managedAuthContents)
@@ -482,9 +445,7 @@ export class CodexRuntimeHomeService {
       }
       return 'persisted'
     } catch (error) {
-      // Why: read-back is best-effort. A transient fs error must not block the
-      // forward sync path — the worst case is one more stale-token cycle, which
-      // is strictly better than failing the entire sync.
+      // Why: read-back is best-effort; a transient fs error must not block the forward sync — worst case is one more stale-token cycle.
       console.warn('[codex-runtime-home] Failed to read back refreshed tokens:', error)
       return 'rejected'
     }
@@ -534,9 +495,7 @@ export class CodexRuntimeHomeService {
       const settings = this.store.getSettings()
       const selectedAccountId = getSelectedCodexAccountIdForTarget(settings, target)
       if (selectedAccountId === null) {
-        // Why: the system-default account changes outside Orca (login, logout,
-        // token refresh). Read its real home directly so a cached runtime copy
-        // cannot stay stale; filesystem probing in the fetcher is asynchronous.
+        // Why: the system-default account changes outside Orca, so read its real home directly to avoid a stale cached runtime copy.
         return this.getWslSystemCodexHomePath(target)
       }
       const cachedRuntimeHomePath = this.wslRuntimeHomePathByDistro.get(distro)
@@ -545,9 +504,7 @@ export class CodexRuntimeHomeService {
         this.lastSyncedWslAccountIdByDistro.has(distro) &&
         this.lastSyncedWslAccountIdByDistro.get(distro) === selectedAccountId
       ) {
-        // Why: RateLimitService resolves provenance twice per poll. Account
-        // changes sync explicitly, so repeated resolution must stay path-only
-        // instead of blocking main on UNC reads and a wsl.exe migration probe.
+        // Why: RateLimitService resolves provenance twice per poll; stay path-only so it doesn't block main on UNC reads and a wsl.exe probe.
         return cachedRuntimeHomePath
       }
     }
@@ -640,9 +597,7 @@ export class CodexRuntimeHomeService {
           (mirroredSystemDefaultAuth === null &&
             this.runtimeAuthIsFresher(runtimeAuth, systemAuth)))
       ) {
-        // Why: WSL runtime homes are per-distro and their in-memory baseline is
-        // lost on app restart. A same-identity fresher runtime auth is a Codex
-        // token refresh and should be copied back before we mirror ~/.codex.
+        // Why: WSL baselines are lost on restart, so a same-identity fresher runtime auth is a token refresh; copy it back before mirroring ~/.codex.
         this.writeRuntimeAuthAtPath(systemAuthPath, runtimeAuth)
         this.lastWrittenWslAuthJsonByDistro.set(distro, runtimeAuth)
         this.lastSyncedWslAccountIdByDistro.set(distro, null)
@@ -722,8 +677,7 @@ export class CodexRuntimeHomeService {
     )
     const nextLinuxPath = `${activeLinuxPath}.next-${process.pid}-${Date.now()}`
     const activeLinuxParentPath = this.dirnameLinuxPath(activeLinuxPath)
-    // Why: WSL drops bash argv here and login-shell cleanup can turn explicit
-    // `exit 0` into status 1, so keep this script literal and fall-through.
+    // Why: WSL drops bash argv, so keep the script literal; login-shell cleanup turns `exit 0` into status 1, so fall through.
     execFileSync(
       'wsl.exe',
       [
@@ -844,10 +798,7 @@ export class CodexRuntimeHomeService {
     }
     const managedIdentity = this.readIdentityFromAuthContents(managedAuthContents)
 
-    // Why: old live Codex PTYs can still write refreshed tokens into the
-    // shared runtime home after the user switches accounts. Never persist
-    // that write into the newly active managed account unless the auth claims
-    // still match the account Orca believes is selected.
+    // Why: old PTYs may write refreshed tokens into the shared runtime after an account switch; only persist when the auth still matches the selected account.
     const selectedEmail = this.firstNonNull(
       this.normalizeField(activeAccount.email),
       managedIdentity?.email
@@ -893,9 +844,7 @@ export class CodexRuntimeHomeService {
       return false
     }
 
-    // Why: stale managed Codex PTYs share the same runtime home. Only read a
-    // runtime refresh back into ~/.codex when the auth still claims the same
-    // system-default identity Orca mirrored earlier.
+    // Why: stale PTYs share the runtime home; only read a refresh back to ~/.codex when the auth still claims the mirrored system-default identity.
     if (
       systemDefaultIdentity.email &&
       runtimeIdentity.email &&
@@ -1238,9 +1187,7 @@ export class CodexRuntimeHomeService {
       this.migrateLegacySessions(managedHomePath, accountId)
     }
 
-    // Why: migration is intentionally one-shot. Re-importing every startup
-    // would keep replaying stale managed-home state back into the shared
-    // runtime and make it feel nondeterministic.
+    // Why: migration is one-shot; re-importing every startup would replay stale managed-home state into the shared runtime.
     writeFileAtomically(
       this.getMigrationMarkerPath(),
       `${JSON.stringify({ completedAt: Date.now(), migratedHomeCount: managedHomes.length })}\n`
@@ -1348,8 +1295,7 @@ export class CodexRuntimeHomeService {
   }
 
   private appendListedFiles(target: string[], source: readonly string[]): void {
-    // Why: migrating legacy session trees must tolerate directories larger than
-    // V8's argument limit for spread calls.
+    // Why: tolerate directories larger than V8's argument limit for spread calls.
     for (const filePath of source) {
       target.push(filePath)
     }
@@ -1366,8 +1312,7 @@ export class CodexRuntimeHomeService {
     try {
       appendFileSync(diagnosticsPath, `${JSON.stringify(record)}\n`, { encoding: 'utf-8' })
     } catch (error) {
-      // Why: conflict diagnostics are useful, but must not make the one-shot
-      // migration fail after the session file has already been preserved.
+      // Why: diagnostics must not fail the one-shot migration after the session file is already preserved.
       console.warn('[codex-runtime-home] Failed to append migration diagnostic:', error)
     }
   }
@@ -1418,17 +1363,13 @@ export class CodexRuntimeHomeService {
           systemDefaultAuth === mirroredSystemDefaultAuth &&
           this.runtimeAuthMatchesSystemDefaultIdentity(runtimeAuth, mirroredSystemDefaultAuth)
         ) {
-          // Why: system-default Codex now refreshes tokens inside Orca's
-          // runtime CODEX_HOME. Read that refresh back to ~/.codex so the next
-          // sync does not overwrite fresh runtime credentials with stale ones.
+          // Why: Codex refreshes tokens in the runtime CODEX_HOME; read that back to ~/.codex so the next sync won't clobber fresh creds with stale ones.
           this.writeSystemDefaultAuth(runtimeAuth)
           this.captureSystemDefaultSnapshot({ force: true })
           this.lastWrittenAuthJson = runtimeAuth
           return
         }
-        // Why: the unmanaged path used to read ~/.codex directly. Mirror later
-        // external logins/logouts into Orca's runtime home so ordinary Orca
-        // Codex sessions keep matching the user's current system-default state.
+        // Why: mirror external logins/logouts into Orca's runtime home so unmanaged Codex sessions keep matching the current system-default state.
         this.captureSystemDefaultSnapshot({ force: true })
         this.writeRuntimeAuth(systemDefaultAuth)
       }
@@ -1449,18 +1390,14 @@ export class CodexRuntimeHomeService {
     }
 
     if (options.detectExternalLogin && !existsSync(runtimeAuthPath)) {
-      // Why: once Orca owns the runtime CODEX_HOME, deleting auth.json there is
-      // a local logout signal for Orca-launched Codex sessions, not a reason to
-      // rewrite the user's real ~/.codex snapshot back into place.
+      // Why: with Orca owning CODEX_HOME, a deleted runtime auth.json is a local logout, not a cue to restore the user's real ~/.codex snapshot.
       this.persistRuntimeLogoutMarker()
       this.lastWrittenAuthJson = null
       return
     }
 
     if (options.detectExternalLogin) {
-      // Why: while a managed account is selected, the runtime auth file exists
-      // with managed credentials. If ~/.codex/auth.json vanished meanwhile,
-      // switching back must preserve that external system-default logout.
+      // Why: if ~/.codex/auth.json vanished while a managed account was selected, switching back must preserve that external system-default logout.
       rmSync(runtimeAuthPath, { force: true })
       this.captureSystemDefaultSnapshot({ force: true })
       this.persistRuntimeLogoutMarker()
@@ -1507,9 +1444,7 @@ export class CodexRuntimeHomeService {
   }
 
   private clearRuntimeAuthAfterSystemDefaultLogout(runtimeAuthPath: string): void {
-    // Why: when the real ~/.codex auth disappears, Orca should treat that as an
-    // external logout for unmanaged sessions, even if runtime auth had already
-    // refreshed inside Orca's CODEX_HOME.
+    // Why: a vanished ~/.codex auth means external logout for unmanaged sessions, even if runtime auth already refreshed in Orca's CODEX_HOME.
     rmSync(runtimeAuthPath, { force: true })
     this.captureSystemDefaultSnapshot({ force: true })
     this.persistRuntimeLogoutMarker()
@@ -1522,8 +1457,7 @@ export class CodexRuntimeHomeService {
   }
 
   private writeRuntimeAuth(contents: string): void {
-    // Why: auth.json contains sensitive credentials. Restrict to owner-only
-    // so other users on a shared Linux/macOS machine cannot read it.
+    // Why: auth.json holds credentials; restrict to owner-only so other users on a shared machine cannot read it.
     this.clearRuntimeLogoutMarker()
     if (this.fileContentsEqual(this.getRuntimeAuthPath(), contents)) {
       this.ensureOwnerOnlyMode(this.getRuntimeAuthPath())
@@ -1634,9 +1568,7 @@ export class CodexRuntimeHomeService {
       ) {
         return parsed as CodexSystemDefaultSnapshot
       }
-      // Why: pre-PR snapshots wrote raw auth.json contents verbatim. Treat any
-      // valid JSON object without an authJson wrapper as the legacy format so
-      // upgraders do not lose their system-default auth on first deselect.
+      // Why: pre-PR snapshots stored raw auth.json; treat objects lacking an authJson wrapper as legacy so upgraders don't lose their auth.
       if (
         parsed &&
         typeof parsed === 'object' &&
@@ -1656,9 +1588,7 @@ export class CodexRuntimeHomeService {
   }
 }
 
-// Why: the seed config is read over UNC but consumed by Codex inside WSL, so
-// relative path-valued settings must anchor to the Linux-side source home; a
-// verbatim copy breaks Codex config load (os error 2).
+// Why: Codex reads this config inside WSL, so relative path settings must anchor to the Linux-side home (verbatim copy breaks load, os error 2).
 export function prepareWslRuntimeSeedConfig(
   configContents: string,
   sourceHomePath: string
diff --git a/src/main/codex-accounts/service.ts b/src/main/codex-accounts/service.ts
index 2a0fb54bdc4..1eb3dedf561 100644
--- a/src/main/codex-accounts/service.ts
+++ b/src/main/codex-accounts/service.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: this service intentionally keeps Codex
-account lifecycle, path safety, login, and identity parsing in one audited
-main-process module so the managed-account boundary stays explicit. */
+/* eslint-disable max-lines -- Why: keeps Codex account lifecycle, path safety, login, and identity parsing in one audited main-process module. */
 import { randomUUID } from 'node:crypto'
 import { execFileSync, spawn } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
@@ -55,8 +53,7 @@ type ResolvedCodexIdentity = {
 
 type CanonicalCodexConfig = {
   contents: string
-  /** Home the config was read from, in the path style Codex sees at runtime
-   *  (Linux-side for WSL); relative path-valued settings resolve against it. */
+  /** Home the config was read from, in the path style Codex sees (Linux-side for WSL); relative settings resolve against it. */
   sourceHomePath: string
 }
 
@@ -77,9 +74,7 @@ function shellQuote(value: string): string {
 }
 
 export class CodexAccountService {
-  // Why: account mutations read settings, do async work (login, rate-limit
-  // refresh), then write settings. Without serialization, overlapping calls
-  // (e.g. double-click "Add Account") can cause lost updates.
+  // Why: serialize the read-modify-write of settings; overlapping calls (e.g. double-click Add) would lose updates.
   private mutationQueue: Promise<unknown> = Promise.resolve()
 
   constructor(
@@ -170,8 +165,7 @@ export class CodexAccountService {
       this.runtimeHome.clearLastWrittenAuthJson(account.id)
       this.runtimeHome.syncForCurrentSelection()
 
-      // Why: the new account becomes active, so the previous active account is
-      // now inactive and its last-known usage should be cached for the switcher.
+      // Why: switching activates the new account, so cache the outgoing account's usage for the switcher.
       const outgoingAccountId = getSelectedCodexAccountIdForTarget(settings, targetSelection)
       await this.rateLimits.refreshForCodexAccountChange(outgoingAccountId, targetSelection)
       return this.getSnapshot()
@@ -215,9 +209,7 @@ export class CodexAccountService {
     this.runtimeHome.clearLastWrittenAuthJson(accountId)
     this.runtimeHome.syncForCurrentSelection(getCodexSelectionTargetForAccount(account))
 
-    // Why: re-auth can change which actual Codex identity the managed home
-    // points at. Force a fresh read immediately so the status bar cannot keep
-    // showing the previous account's quota under the updated label.
+    // Why: re-auth can change the underlying Codex identity, so force a fresh read to avoid showing stale quota.
     await this.rateLimits.refreshForCodexAccountChange(
       undefined,
       getCodexSelectionTargetForAccount(account)
@@ -244,8 +236,7 @@ export class CodexAccountService {
     this.runtimeHome.syncForCurrentSelection()
 
     this.safeRemoveManagedHome(account.managedHomePath)
-    // Why: a removed account can no longer appear in the switcher dropdown,
-    // so purge its cached usage to avoid stale entries.
+    // Why: removed accounts can't appear in the switcher, so purge cached usage to avoid stale entries.
     this.rateLimits.evictInactiveCodexCache(accountId)
     await this.rateLimits.refreshForCodexAccountChange(
       getSelectedCodexAccountIdForTarget(settings, getCodexSelectionTargetForAccount(account)) ===
@@ -358,9 +349,7 @@ export class CodexAccountService {
 
     const managedHomePath = join(this.getManagedAccountsRoot(), accountId, 'home')
     mkdirSync(managedHomePath, { recursive: true })
-    // Why: Codex expects CODEX_HOME to be a concrete directory it can own. We
-    // pre-create the directory and leave a marker so future cleanup code can
-    // prove the path belongs to Orca before deleting anything.
+    // Why: marker lets future cleanup prove the path belongs to Orca before deleting anything.
     writeFileSync(join(managedHomePath, '.orca-managed-home'), `${accountId}\n`, 'utf-8')
     return {
       managedHomePath: this.assertManagedHomePath(managedHomePath),
@@ -462,12 +451,7 @@ export class CodexAccountService {
     }
 
     const trustedManagedHomePath = this.assertManagedHomePath(managedHomePath)
-    // Why: Orca account switching is meant to swap Codex credentials and quota
-    // identity, not silently fork the user's sandbox/config defaults. Syncing
-    // one canonical config into every managed home keeps auth isolated per
-    // account while preserving consistent Codex behavior. Managed homes are
-    // real CODEX_HOMEs for `codex login`, so relative path-valued settings
-    // must keep resolving against the home the config was read from.
+    // Why: sync one canonical config per home so switching swaps only auth/quota; rewrite relative paths to resolve against the source home.
     this.writeManagedConfig(
       trustedManagedHomePath,
       rewriteRelativePathConfigValues(canonicalConfig.contents, canonicalConfig.sourceHomePath)
@@ -507,8 +491,7 @@ export class CodexAccountService {
     }
 
     try {
-      // Why: the config is read over UNC but consumed by Codex inside WSL, so
-      // path rewrites must anchor to the Linux-side ~/.codex, not the UNC path.
+      // Why: read over UNC but consumed inside WSL, so path rewrites must anchor to the Linux-side ~/.codex, not the UNC path.
       return { contents: readFileSync(configPath, 'utf-8'), sourceHomePath: `${wslHome}/.codex` }
     } catch (error) {
       console.warn('[codex-accounts] Failed to read WSL canonical config:', error)
@@ -523,8 +506,7 @@ export class CodexAccountService {
         return
       }
     } catch {
-      // Why: read errors should not make a stale config look current; the
-      // atomic write path owns Windows ACL repair and persistent error surfacing.
+      // Why: a read error must not make a stale config look current; atomic write owns ACL repair and error surfacing.
     }
     writeFileAtomically(configPath, contents)
   }
@@ -561,8 +543,7 @@ export class CodexAccountService {
       throw originalError
     }
 
-    // Why: explicit re-auth is allowed to recover from a lost empty container,
-    // but only at the exact Orca-owned account path persisted for this account.
+    // Why: re-auth may recreate a lost empty home, but only at the exact Orca-owned path persisted for this account.
     mkdirSync(expectedManagedHomePath, { recursive: true })
     writeFileSync(join(expectedManagedHomePath, '.orca-managed-home'), `${account.id}\n`, 'utf-8')
     return this.assertManagedHomePath(expectedManagedHomePath)
@@ -687,18 +668,11 @@ export class CodexAccountService {
       throw new Error('Managed Codex home directory does not exist on disk.')
     }
 
-    // realpath() requires the leaf to exist. For pre-login add flow we create
-    // the home directory first so the containment check still verifies the
-    // canonical on-disk target rather than trusting persisted text blindly.
+    // realpath() requires the leaf to exist; verify the canonical on-disk target rather than trusting persisted text.
     const canonicalCandidate = realpathSync(resolvedCandidate)
     const canonicalRoot = realpathSync(resolvedRoot)
 
-    // Why: the prefix check must compare canonical paths on both sides. On
-    // macOS, userData sits under /var/folders/... which realpath resolves to
-    // /private/var/folders/...; comparing a canonical candidate against a
-    // non-canonical root would spuriously reject every managed home. In dev
-    // mode (orca-dev/ vs orca/) this check also filters out production-rooted
-    // paths before downstream sync runs.
+    // Why: both sides must be canonical — macOS /var/folders realpaths to /private/var, else every managed home is rejected.
     if (
       canonicalCandidate !== canonicalRoot &&
       !canonicalCandidate.startsWith(canonicalRoot + sep)
@@ -727,8 +701,7 @@ export class CodexAccountService {
     linuxHomePath: string,
     expectedAccountId: string
   ): void {
-    // Why: WSL home creation can fail after mkdir/marker write but before the
-    // path is trusted. Cleanup must prove the marker/account ID inside WSL.
+    // Why: creation can fail after mkdir/marker but before trust, so cleanup must verify the marker/account ID inside WSL.
     try {
       execFileSync(
         'wsl.exe',
@@ -784,13 +757,10 @@ export class CodexAccountService {
       return
     }
 
-    // Why: managed homes live at <accounts-root>/<uuid>/home. Removing
-    // just the home/ leaf leaves an empty <uuid>/ directory behind.
+    // Why: homes live at <accounts-root>/<uuid>/home; removing the home/ leaf leaves an empty <uuid>/ behind.
     try {
       const parentDir = resolve(managedHomePath, '..')
-      // Why: managedHomePath is already canonicalized by assertManagedHomePath,
-      // so the root must be canonicalized too for the prefix check to work on
-      // macOS where userData resolves through /private/var.
+      // Why: canonicalize the root too so the prefix check works on macOS where userData resolves through /private/var.
       const root = realpathSync(this.getManagedAccountsRoot())
       if (parentDir.startsWith(root + sep) && parentDir !== root) {
         rmSync(parentDir, { recursive: true, force: true })
@@ -816,11 +786,7 @@ export class CodexAccountService {
           }
         : (() => {
             const codexCommand = resolveCodexCommand()
-            // Why: on Windows, resolveCodexCommand() may return a .cmd/.bat file
-            // (e.g. codex.cmd from npm). Node's child_process.spawn cannot execute
-            // batch scripts directly without shell:true, but shell:true with an args
-            // array causes DEP0190 because args are concatenated, not escaped.
-            // Fix: detect batch scripts and invoke cmd.exe /c explicitly.
+            // Why: Windows codex may be a .cmd/.bat; spawn+shell:true would trigger DEP0190, so invoke cmd.exe /c explicitly.
             const { spawnCmd, spawnArgs } = getSpawnArgsForWindows(codexCommand, ['login'])
             return {
               command: spawnCmd,
@@ -834,8 +800,7 @@ export class CodexAccountService {
           })()
       const child = spawn(spawnConfig.command, spawnConfig.args, {
         stdio: ['ignore', 'pipe', 'pipe'],
-        // Why: route through cmd.exe for .cmd/.bat entrypoints would otherwise
-        // flash a console window in the packaged GUI app on Windows.
+        // Why: prevents a console window flash for .cmd/.bat entrypoints routed through cmd.exe on Windows.
         windowsHide: true,
         env: spawnConfig.env
       })
@@ -881,9 +846,7 @@ export class CodexAccountService {
       const onError = (error: Error): void => {
         settle(() => {
           const isEnoent = (error as NodeJS.ErrnoException).code === 'ENOENT'
-          // Why: ENOENT can mean either the codex binary doesn't exist OR the
-          // script's shebang interpreter (node) isn't in PATH. When we resolved
-          // codex to a full path, ENOENT almost certainly means node is missing.
+          // Why: ENOENT is ambiguous — missing codex binary or missing node in PATH; a resolved full path implies node is missing.
           const isBareCommand = spawnConfig.codexCommand === 'codex'
           const message = isEnoent
             ? isBareCommand
@@ -963,10 +926,7 @@ export class CodexAccountService {
     const authFilePath = join(this.assertManagedHomePath(managedHomePath), 'auth.json')
     const raw = JSON.parse(readFileSync(authFilePath, 'utf-8')) as Record<string, unknown>
 
-    // Why: API-key-based auth files have no OAuth tokens or JWT identity
-    // claims. Returning nulls causes the caller to fail with a clear
-    // "could not resolve the account email" error rather than crashing
-    // on missing nested token fields.
+    // Why: API-key auth files have no OAuth/JWT claims; return nulls so the caller fails cleanly instead of crashing.
     if (typeof raw.OPENAI_API_KEY === 'string' && raw.OPENAI_API_KEY.trim() !== '') {
       return {
         idToken: null,
diff --git a/src/main/codex/config-settings-promotion.ts b/src/main/codex/config-settings-promotion.ts
index 7e8552bb9b6..a7a1add6857 100644
--- a/src/main/codex/config-settings-promotion.ts
+++ b/src/main/codex/config-settings-promotion.ts
@@ -19,16 +19,9 @@ import {
   updateTomlLineScanState
 } from './config-toml-line-scan'
 
-// Why: the config mirror rewrites the runtime config.toml from ~/.codex on
-// every launch (and on background rate-limit fetches), so settings the user
-// changes inside Orca-launched Codex silently revert. Promotion diffs the
-// runtime file against a baseline of what Orca last wrote — anything that
-// differs is a change Codex persisted for the user and belongs in ~/.codex.
+// Why: the mirror reverts in-Codex config changes each launch; promotion salvages them by diffing the last baseline.
 
-// Why: only the user-preference scalars the Codex TUI itself persists
-// (/model writes model + model_reasoning_effort, /approvals writes
-// approval_policy + sandbox_mode). Every key added here gets written into the
-// user's real ~/.codex/config.toml, so grow this list deliberately.
+// Why: only scalars the Codex TUI persists; each key here is written to the user's real ~/.codex, so grow deliberately.
 export const PROMOTED_CODEX_SETTING_KEYS = [
   'model',
   'model_reasoning_effort',
@@ -38,8 +31,7 @@ export const PROMOTED_CODEX_SETTING_KEYS = [
 
 type TopLevelSettingValue = {
   raw: string
-  // Why: a value that opens a multiline string/array cannot be replaced or
-  // copied line-by-line safely, so it is excluded from promotion entirely.
+  // Why: a multiline string/array value can't be replaced line-by-line, so it's excluded from promotion.
   multiline: boolean
 }
 
@@ -78,9 +70,7 @@ function readSettingsBaseline(runtimeHomePath: string): Map<string, string> | nu
   }
 }
 
-// Why: only keys in the top-level preamble are scanned — Codex writes profile
-// overrides into [profiles.*] tables, and rewriting nested tables surgically
-// is not worth the risk for stage-1 promotion.
+// Why: only top-level preamble keys are scanned; rewriting nested [profiles.*] tables isn't worth the risk here.
 function readTopLevelSettingValues(configPath: string): Map<string, TopLevelSettingValue> {
   const result = new Map<string, TopLevelSettingValue>()
   if (!existsSync(configPath)) {
@@ -108,19 +98,16 @@ function readTopLevelSettingValues(configPath: string): Map<string, TopLevelSett
 }
 
 /**
- * Records the promotable top-level settings the runtime config.toml holds
- * after a mirror, so the next promotion can tell "value Orca mirrored" apart
- * from "value Codex wrote for the user". Call after a successful mirror only —
- * advancing the baseline past an unpromoted change would strand it forever.
+ * Records the promotable settings the runtime config.toml holds after a mirror, so the next
+ * promotion can tell "value Orca mirrored" from "value Codex wrote for the user".
+ * Call after a successful mirror only — advancing past an unpromoted change strands it forever.
  */
 export function snapshotCodexRuntimeSettingsBaseline(
   runtimeHomePath = getOrcaManagedCodexHomePath()
 ): void {
   try {
     const runtimeTomlPath = join(runtimeHomePath, 'config.toml')
-    // Why: a missing runtime config still records an empty baseline — when
-    // Codex later creates the file for a user with no ~/.codex/config.toml,
-    // that first change must diff against "Orca left nothing" and promote.
+    // Why: record an empty baseline even for a missing runtime config, so Codex's first write still diffs and promotes.
     const settings: Record<string, string> = {}
     for (const [key, value] of readTopLevelSettingValues(runtimeTomlPath)) {
       if (!value.multiline) {
@@ -130,8 +117,7 @@ export function snapshotCodexRuntimeSettingsBaseline(
     const file: SettingsBaselineFile = { version: 1, settings }
     const baselinePath = getSettingsBaselinePath(runtimeHomePath)
     const serialized = `${JSON.stringify(file, null, 2)}\n`
-    // Why: launch preparation can run repeatedly; skip byte-identical rewrites
-    // so an unchanged pass does no disk writes.
+    // Why: launch prep runs repeatedly; skip byte-identical rewrites to avoid needless disk writes.
     if (existsSync(baselinePath) && readFileSync(baselinePath, 'utf-8') === serialized) {
       return
     }
@@ -157,19 +143,16 @@ function getHostPromotionHomes(): CodexSettingsPromotionHomes {
 }
 
 /**
- * Promotes setting changes the user made inside Orca-launched Codex (written
- * by Codex into the runtime config.toml) into ~/.codex/config.toml. Runs
- * before the config mirror so the promoted values survive the same mirror
- * pass instead of reverting. WSL callers pass explicit per-distro homes; the
- * default is the host runtime home and host ~/.codex.
+ * Promotes in-Codex setting changes from the runtime config.toml into ~/.codex/config.toml.
+ * Runs before the config mirror so promoted values survive it instead of reverting.
+ * WSL callers pass explicit per-distro homes; default is the host runtime home and ~/.codex.
  */
 export function promoteCodexRuntimeSettingsToSystem(homes?: CodexSettingsPromotionHomes): boolean {
   try {
     promoteCodexRuntimeSettingsToSystemUnsafe(homes ?? getHostPromotionHomes())
     return true
   } catch (error) {
-    // Why: promotion is best-effort launch prep; callers preserve the runtime
-    // for retry, while a malformed file must not block Codex launch itself.
+    // Why: promotion is best-effort launch prep; a malformed file must not block Codex launch.
     console.warn('[codex-settings-promotion] failed to promote runtime settings', error)
     return false
   }
@@ -185,11 +168,7 @@ function promoteCodexRuntimeSettingsToSystemUnsafe(homes: CodexSettingsPromotion
   if (!existsSync(runtimeTomlPath)) {
     return
   }
-  // Why: without a baseline of what Orca last mirrored (first launch after
-  // upgrading to a build with promotion, or a corrupted snapshot), a stale
-  // runtime value is indistinguishable from a fresh in-Codex change. Skip
-  // this pass — the mirror writes the first baseline and promotion starts on
-  // the next one.
+  // Why: without a baseline, a stale runtime value looks like a fresh in-Codex change; skip until the mirror writes one.
   const baseline = readSettingsBaseline(runtimeHomePath)
   if (!baseline) {
     return
@@ -210,8 +189,7 @@ function promoteCodexRuntimeSettingsToSystemUnsafe(homes: CodexSettingsPromotion
     if (system?.multiline) {
       continue
     }
-    // Why: ~/.codex stays source of truth — if the user also edited it there
-    // since the baseline, the outside edit wins over the in-Codex change.
+    // Why: ~/.codex is source of truth — an outside edit since the baseline wins over the in-Codex change.
     if (system?.raw !== baseline.get(key)) {
       continue
     }
@@ -220,23 +198,16 @@ function promoteCodexRuntimeSettingsToSystemUnsafe(homes: CodexSettingsPromotion
   if (updates.size === 0) {
     return
   }
-  // Why: a genuinely fresh host has no ~/.codex yet; without the directory
-  // the atomic write ENOENTs and the following mirror wipes the setting.
-  // Owner-only: the directory holds auth.json and the full user config.
+  // Why: a fresh host has no ~/.codex; create it owner-only (holds auth.json) or the atomic write ENOENTs and the mirror wipes it.
   mkdirSync(systemHomePath, { recursive: true, mode: 0o700 })
   const writeTarget = resolvePromotionWriteTarget(systemTomlPath)
-  // Why: a dangling dotfile-manager symlink can point into a directory tree
-  // that has not been materialized yet; preserve the link and create its real
-  // parent so the atomic temp file can be written beside the target.
+  // Why: a dangling symlink may target an unmade dir tree; create its real parent so the atomic temp write has a home.
   mkdirSync(dirname(writeTarget.path), { recursive: true, mode: 0o700 })
   const targetExists = existsSync(writeTarget.path)
   const systemContent = targetExists ? readFileSync(writeTarget.path, 'utf-8') : ''
   const nextContent = upsertTopLevelSettingsInContent(systemContent, updates)
   if (targetExists && parseWslUncPath(writeTarget.path)) {
-    // Why: symlink metadata through the \\wsl$ 9P provider is not reliable
-    // enough for realpath/lstat detection, and an atomic rename would replace
-    // a WSL-side dotfile symlink with a plain file. Writing through the
-    // existing file preserves the Linux-side inode (and its mode).
+    // Why: \\wsl$ 9P symlink metadata is unreliable; write through the existing file to preserve the WSL-side inode.
     writeFileSync(writeTarget.path, nextContent, 'utf-8')
     return
   }
@@ -245,11 +216,7 @@ function promoteCodexRuntimeSettingsToSystemUnsafe(homes: CodexSettingsPromotion
   })
 }
 
-// Why: promotion rewrites the user's real config.toml. Follow an existing
-// symlink (dotfile managers) instead of replacing the link with a plain file,
-// and carry the real file's mode forward — an atomic write without a mode
-// would widen a user-restricted 0600 config to the process umask default.
-// A new or unreadable target is created owner-only.
+// Why: follow an existing dotfile-manager symlink and carry its mode forward so an atomic write can't widen a 0600 config.
 function resolvePromotionWriteTarget(systemTomlPath: string): { path: string; mode: number } {
   try {
     const realPath = realpathSync(systemTomlPath)
@@ -282,8 +249,7 @@ function resolveDanglingSymlinkTarget(linkPath: string): string {
       return currentPath
     }
   }
-  // Why: replacing any link in a cycle would destroy dotfile-manager state;
-  // abort promotion and leave the runtime/baseline intact for manual repair.
+  // Why: replacing any link in a cycle would destroy dotfile-manager state; abort instead.
   throw new Error(`Codex config symlink cycle at ${linkPath}`)
 }
 
@@ -310,8 +276,7 @@ export function upsertTopLevelSettingsInContent(
     state = updateTomlLineScanState(state, line)
   }
 
-  // Why: CRLF configs keep a trailing \r after the split; new lines must use
-  // the file's existing endings or a Windows-owned config becomes mixed-EOL.
+  // Why: match the file's existing EOL (CRLF split leaves a trailing \r) so a Windows config doesn't go mixed-EOL.
   const usesCrlf = content.includes('\r\n')
   const insertions: string[] = []
   for (const [key, raw] of updates) {
diff --git a/src/main/codex/config-toml-trust.test.ts b/src/main/codex/config-toml-trust.test.ts
index 9f8efbea403..0b661a3d590 100644
--- a/src/main/codex/config-toml-trust.test.ts
+++ b/src/main/codex/config-toml-trust.test.ts
@@ -28,10 +28,7 @@ import {
   type CodexTrustEntry
 } from './config-toml-trust'
 
-// Why: this hash was captured from a real Codex 0.129 `/hooks` approval. If
-// Codex changes its serialization or normalization rules, this test fails
-// loudly instead of silently shipping bad trust entries that put hooks back
-// into the review pile.
+// Why: captured from a real Codex 0.129 `/hooks` approval; fails loudly if Codex's serialization drifts.
 const REAL_APPROVED_COMMAND = '/bin/sh "/tmp/orca-case-b-mCmCe6/agent-hooks/codex-hook.sh"'
 const REAL_APPROVED_HASH = 'sha256:bc013489dba495431d3790fda62ee5a7d907a7c491e29ad26238c3a5d6d2b163'
 
@@ -153,12 +150,7 @@ describe('computeTrustedHash', () => {
   })
 
   it('drops the matcher on user_prompt_submit/stop like matcher_pattern_for_event', () => {
-    // Why: Codex ignores matchers on these two events and hashes the
-    // identity WITHOUT the matcher field. A definition carrying
-    // `"matcher": ""` (common in third-party installers) must therefore
-    // hash identically to one without a matcher, or the system-trust
-    // mirror misses and the stale-entry sweep deletes the trust Codex
-    // wrote — re-prompting the user on every launch.
+    // Why: Codex hashes these two events WITHOUT the matcher, so `"matcher": ""` must hash like no matcher.
     for (const eventLabel of ['user_prompt_submit', 'stop'] as const) {
       const base: CodexTrustEntry = {
         sourcePath: '/x/hooks.json',
@@ -174,12 +166,7 @@ describe('computeTrustedHash', () => {
   })
 
   it('pins the matcher-omitted hash for a Stop entry that carries an empty matcher', () => {
-    // Why: regression pin for the shape observed in the wild (a real
-    // Codex 0.140 config.toml, path anonymized): Codex stores the
-    // matcher-omitted hash for Stop even when hooks.json carries
-    // `"matcher": ""`, so we must never fold the matcher into this
-    // identity. If serialization or normalization drifts, this constant
-    // fails loudly.
+    // Why: regression pin (real Codex 0.140 config) — Stop uses the matcher-omitted hash even with `"matcher": ""`.
     expect(
       computeTrustedHash({
         sourcePath: '/home/user/.codex/hooks.json',
@@ -291,8 +278,7 @@ describe('computeTrustKey', () => {
   })
 
   it('uses native Windows backslashes in the trust key Codex looks up', () => {
-    // Why: Codex 0.140 writes approved Windows hook trust keys as raw native
-    // paths under [hooks.state].
+    // Why: Codex 0.140 writes approved Windows hook trust keys as raw native paths under [hooks.state].
     const winPath = 'C:\\Users\\Rod\\AppData\\Roaming\\orca\\hooks.json'
     const key = computeTrustKey({
       sourcePath: winPath,
@@ -306,8 +292,7 @@ describe('computeTrustKey', () => {
   })
 
   it('preserves literal backslashes in non-Windows-style fallback paths', () => {
-    // Why: SSH/POSIX paths can legally contain `\` as a filename character;
-    // only Windows-style separators should be normalized.
+    // Why: POSIX/SSH paths can contain `\` as a filename char; only Windows separators get normalized.
     expect(getCodexCanonicalTrustPath('/tmp/with\\literal/hooks.json')).toBe(
       '/tmp/with\\literal/hooks.json'
     )
@@ -387,8 +372,7 @@ describe('upsertHookTrustEntries', () => {
     expect(written).not.toContain('STALE')
     expect(written).toContain('[unrelated]')
     expect(written).toContain('value = 42')
-    // Why: we only own the [hooks.state."<key>"] block — the [features]
-    // block must be unchanged.
+    // Why: we only own the [hooks.state."<key>"] block — [features] must be untouched.
     expect(written).toContain('[features]\nhooks = true')
   })
 
@@ -507,8 +491,7 @@ describe('upsertHookTrustEntries', () => {
     }
     upsertHookTrustEntries(configPath, [entry])
     const firstWrite = readFileSync(configPath, 'utf-8')
-    // Why: a no-op upsert must not roll the .bak forward — repeated calls
-    // (e.g. from app start) would otherwise destroy the last recoverable copy.
+    // Why: a no-op upsert must not roll .bak forward, or repeated calls destroy the last recoverable copy.
     rmSync(`${configPath}.bak`, { force: true })
     upsertHookTrustEntries(configPath, [entry])
     expect(existsSync(`${configPath}.bak`)).toBe(false)
@@ -516,8 +499,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('replaces a stale block written with CRLF line endings without duplicating', () => {
-    // Why: regression — Windows-style \r\n in the existing config previously
-    // caused the header pattern to miss and append a duplicate block.
+    // Why: regression — \r\n in the existing config made the header pattern miss and append a duplicate.
     const key = '/x/hooks.json:pre_tool_use:0:0'
     const original = [
       '[features]',
@@ -598,8 +580,7 @@ describe('upsertHookTrustEntries', () => {
     expect(written).toContain('foo = 1')
   })
 
-  // Why: TOML supports both basic-string and literal-string quoted keys;
-  // header detection must respect `]` inside `'...'` too.
+  // Why: TOML allows literal-string quoted keys, so header detection must respect `]` inside `'...'`.
   it('preserves an unrelated table whose literal-string key contains a `]`', () => {
     const key = '/x/hooks.json:pre_tool_use:0:0'
     const original = [
@@ -749,8 +730,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('treats `\\"""` inside a multi-line basic string as an escaped quote, not a close', () => {
-    // Why: a basic multi-line string with `\"` escapes must not be misread as
-    // closing early — content and any following real header must survive intact.
+    // Why: `\"` escapes in a multi-line basic string must not be misread as closing early.
     const original = [
       'prompt = """',
       'use \\"\\"\\" carefully',
@@ -779,8 +759,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('escapes literal `"` and `\\` in non-Windows source paths inside the trust block header', () => {
-    // Why: a backslash in a POSIX path can be a literal filename character, so
-    // it must still be escaped instead of normalized away.
+    // Why: a backslash in a POSIX path is a literal filename char, so escape it instead of normalizing.
     const entry: CodexTrustEntry = {
       sourcePath: '/x/with"quote\\and\\back/hooks.json',
       eventLabel: 'pre_tool_use',
@@ -797,9 +776,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('overwrites an existing block whose header has leading whitespace (TOML allows indent)', () => {
-    // Why: regression — buildHeaderPattern used to require column-0 headers,
-    // but the reader accepts indented ones. That mismatch caused upsert to
-    // append a duplicate `[hooks.state."<key>"]` block, producing invalid TOML.
+    // Why: regression — buildHeaderPattern required column-0 headers but the reader accepts indented ones.
     const key = '/x/hooks.json:pre_tool_use:0:0'
     const original = ` [hooks.state."${key}"]\nenabled = true\ntrusted_hash = "sha256:OLD"\n`
     writeFileSync(configPath, original, 'utf-8')
@@ -821,9 +798,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('preserves `enabled = false` when the user hand-edited it before reinstall', () => {
-    // Why: regression — auto-install on app start used to clobber a
-    // hand-disabled hook back to enabled = true, removing the only way to
-    // mute Orca's hook short of full uninstall.
+    // Why: regression — auto-install used to clobber a hand-disabled hook back to enabled = true.
     const key = '/x/hooks.json:pre_tool_use:0:0'
     const original = `[hooks.state."${key}"]\nenabled = false\ntrusted_hash = "sha256:OLD"\n`
     writeFileSync(configPath, original, 'utf-8')
@@ -844,9 +819,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('overwrites an existing block when the file ends without a trailing newline', () => {
-    // Why: regression — buildHeaderPattern used to require a trailing
-    // `\r?\n`, missing it caused the upsert path to take the no-match branch
-    // and append a duplicate block at EOF.
+    // Why: regression — buildHeaderPattern required a trailing newline, appending a duplicate at EOF.
     const key = '/x/hooks.json:pre_tool_use:0:0'
     const original = `[hooks.state."${key}"]\nenabled = true\ntrusted_hash = "sha256:OLD"`
     writeFileSync(configPath, original, 'utf-8')
@@ -868,10 +841,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('overwrites an existing block whose header has an inline comment', () => {
-    // Why: regression — buildHeaderPattern used to require the header line
-    // to end at \r?\n or EOF, missing TOML-valid trailing comments. The
-    // upsert path then took the no-match branch and appended a duplicate
-    // `[hooks.state."<key>"]` block, producing invalid TOML.
+    // Why: regression — buildHeaderPattern missed TOML-valid trailing comments and appended a duplicate block.
     const key = '/x/hooks.json:pre_tool_use:0:0'
     const original = `[hooks.state."${key}"] # user note\nenabled = true\ntrusted_hash = "sha256:OLD"\n`
     writeFileSync(configPath, original, 'utf-8')
@@ -893,8 +863,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('finds and replaces a legacy forward-slash block when Orca upserts with native backslash key', () => {
-    // Why: Codex 0.140 can expose Windows trust keys with either separator
-    // shape depending on startup cwd, so Orca replaces stale blocks with both.
+    // Why: Codex 0.140 exposes Windows keys with either separator depending on cwd, so replace both.
     const backslashPath = 'C:\\Users\\Rod\\AppData\\Roaming\\orca\\hooks.json'
     const legacyKey = `${backslashPath.replace(/\\/g, '/')}:session_start:0:0`
     const original = [
@@ -923,8 +892,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('produces exactly one Windows separator pair after two consecutive upserts', () => {
-    // Why: idempotency guard — repeated auto-install on app start must not
-    // accumulate duplicate trust blocks and produce invalid TOML.
+    // Why: idempotency guard — repeated auto-install must not accumulate duplicate blocks.
     const entry: CodexTrustEntry = {
       sourcePath: 'C:\\Users\\Rod\\AppData\\Roaming\\orca\\hooks.json',
       eventLabel: 'session_start',
@@ -941,8 +909,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('falls back to TOML basic-string headers when a Windows path contains an apostrophe', () => {
-    // Why: TOML literal-string table keys cannot contain apostrophes, but
-    // Windows user/profile paths can.
+    // Why: TOML literal-string keys can't hold apostrophes, but Windows profile paths can.
     const entry: CodexTrustEntry = {
       sourcePath: "C:\\Users\\O'Connor\\AppData\\Roaming\\orca\\hooks.json",
       eventLabel: 'session_start',
@@ -964,10 +931,7 @@ describe('upsertHookTrustEntries', () => {
   })
 
   it('finds a Codex-written block with lowercased username when Orca key has mixed-case username', () => {
-    // Why: realpathSync.native casing can differ between what Codex wrote
-    // (C:\Users\rod\...) and what Orca resolves (C:\Users\Rod\...).
-    // normalizeHookTrustKeyForLookup case-folds Windows-shaped paths so the
-    // existing block is replaced rather than a duplicate appended.
+    // Why: realpathSync.native casing can differ from what Codex wrote, so case-fold to replace not duplicate.
     const lowercasePath = 'C:\\Users\\rod\\AppData\\Roaming\\orca\\hooks.json'
     const mixedCasePath = 'C:\\Users\\Rod\\AppData\\Roaming\\orca\\hooks.json'
     const literalKey = `${lowercasePath}:session_start:0:0`
@@ -1057,8 +1021,7 @@ describe('upsertProjectTrustLevel', () => {
   })
 
   it('preserves CRLF endings and writes native Windows path separators in the header', () => {
-    // Why: local project trust still follows Codex's realpath display, while
-    // remote project trust preserves the SSH provider's canonical path string.
+    // Why: local trust follows Codex's realpath; remote trust preserves the SSH provider's canonical path.
     const original = ['[profiles.default]', 'model = "gpt-5"', ''].join('\r\n')
 
     const updated = upsertProjectTrustLevelInContent(original, 'C:\\Users\\nw\\repo', 'trusted')
@@ -1070,8 +1033,7 @@ describe('upsertProjectTrustLevel', () => {
   })
 
   it('updates an existing Windows backslash project block after separator normalization', () => {
-    // Why: hook trust now writes paired Windows variants, but project trust
-    // must still repair an existing single project table in place.
+    // Why: hook trust writes paired Windows variants, but project trust still repairs a single table in place.
     const original = [
       '[projects."C:\\\\Users\\\\nw\\\\repo"]',
       'notes = "keep"',
@@ -1089,8 +1051,7 @@ describe('upsertProjectTrustLevel', () => {
   })
 
   it('updates an existing legacy Windows forward-slash project block', () => {
-    // Why: older Orca builds normalized Windows project paths to forward
-    // slashes; native-backslash hook fixes must not duplicate those blocks.
+    // Why: older Orca builds normalized to forward slashes; backslash fixes must not duplicate them.
     const original = [
       '[projects."C:/Users/nw/repo"]',
       'notes = "keep"',
@@ -1149,8 +1110,7 @@ describe('upsertProjectTrustLevel', () => {
   })
 
   it('keeps case-distinct WSL Linux project paths as separate trust blocks', () => {
-    // Why: the \\wsl$\<distro> share is case-insensitive on Windows, but the
-    // Linux path underneath is not — .../Repo and .../repo are two projects.
+    // Why: \\wsl$\<distro> is case-insensitive but the Linux path under it is not — two distinct projects.
     const existingPath = '\\\\wsl$\\Ubuntu\\home\\u\\Repo'
     const incomingPath = '\\\\wsl$\\Ubuntu\\home\\u\\repo'
     const original = [`[projects.'${existingPath}']`, 'trust_level = "untrusted"', ''].join('\n')
@@ -1161,16 +1121,14 @@ describe('upsertProjectTrustLevel', () => {
 
     expect(updated.match(/\[projects\./g)).toHaveLength(2)
     expect(updated).toContain(`[projects.'${existingPath}']`)
-    // Why: serializer writes basic-string headers via escapeTomlString; assert
-    // that form so the fixture can't drift from real header matching.
+    // Why: serializer writes basic-string headers via escapeTomlString; assert that exact form.
     expect(updated).toContain(`[projects."${escapeTomlString(incomingPath)}"]`)
     expect(updated).toContain('trust_level = "untrusted"')
     expect(updated).toContain('trust_level = "trusted"')
   })
 
   it('updates the same WSL project block across wsl$ and wsl.localhost spellings', () => {
-    // Why: the two share spellings alias the same distro filesystem, so a
-    // revoked project must not be re-trusted under the other spelling.
+    // Why: the two share spellings alias the same distro, so a revoke must not survive under the other.
     const original = [
       "[projects.'\\\\wsl$\\Ubuntu\\home\\u\\proj']",
       'trust_level = "untrusted"',
@@ -1204,8 +1162,7 @@ describe('upsertProjectTrustLevel', () => {
   })
 
   it('preserves an already-canonical remote Windows project path', () => {
-    // Why: SSH project paths are resolved on the remote; local realpath would
-    // canonicalize the wrong machine if the same path happens to exist locally.
+    // Why: SSH paths resolve on the remote; local realpath would canonicalize the wrong machine.
     const updated = upsertProjectTrustLevelInContent('', 'C:/Users/nw/repo', 'trusted', {
       alreadyCanonical: true
     })
@@ -1241,8 +1198,7 @@ describe('normalizeCodexProjectPathForLookup', () => {
   })
 
   it('merges separator and distro-casing variants of the same WSL path', () => {
-    // Why: separators and the case-insensitive \\wsl$\<distro> share may drift,
-    // but the same Linux path must still resolve to one trust key.
+    // Why: separator and \\wsl$\<distro> casing may drift, but the same Linux path is one trust key.
     expect(normalizeCodexProjectPathForLookup('\\\\wsl$\\Ubuntu\\home\\u\\proj')).toBe(
       normalizeCodexProjectPathForLookup('//WSL$/ubuntu/home/u/proj')
     )
@@ -1451,9 +1407,7 @@ describe('removeHookTrustEntries', () => {
   })
 
   it('preserves the line separator when no blank line precedes the removed block', () => {
-    // Why: regression — removeTrustBlock used to cut from match.index (the
-    // captured leading newline) and fused the previous content into the next
-    // header, producing invalid TOML like `a = 1[other]`.
+    // Why: regression — removeTrustBlock cut the leading newline, fusing prior content into the next header.
     const key = '/x/hooks.json:pre_tool_use:0:0'
     const original = [
       'a = 1',
@@ -1498,8 +1452,7 @@ describe('removeHookTrustEntries', () => {
   })
 
   it('removes a block whose header has an inline comment', () => {
-    // Why: paired with the upsert regression; the same pattern mismatch
-    // would silently leave the dead block in place during uninstall.
+    // Why: same pattern mismatch as the upsert regression would leave the dead block during uninstall.
     const key = '/x/hooks.json:pre_tool_use:0:0'
     const original = `[hooks.state."${key}"] # user note\nenabled = true\ntrusted_hash = "sha256:K"\n`
     writeFileSync(configPath, original, 'utf-8')
@@ -1574,10 +1527,7 @@ describe('readHookTrustEntries', () => {
   })
 
   it('normalizes backslash block key to forward-slash at ingestion', () => {
-    // Why: a real Windows path on disk like C:\foo gets written escaped as
-    // `C:\\foo` inside the TOML key. The Map key is normalized (backslash ->
-    // forward-slash) so computeTrustKey lookups match regardless of how Codex
-    // encoded the path separator.
+    // Why: normalize the Map key (backslash -> forward-slash) so computeTrustKey lookups match either encoding.
     const original = [
       '[hooks.state."C:\\\\foo\\\\hooks.json:pre_tool_use:0:0"]',
       'enabled = true',
@@ -1608,8 +1558,7 @@ describe('readHookTrustEntries', () => {
   })
 
   it('supports case-insensitive lookups for Windows hook trust keys read from config', () => {
-    // Why: Codex and realpathSync.native can disagree on user-path casing;
-    // status checks still need Map.get(computeTrustKey(...)) to find the row.
+    // Why: Codex and realpathSync.native can disagree on path casing, but lookups must still match.
     const rawKey = 'C:\\Users\\rod\\AppData\\Roaming\\orca\\hooks.json:session_start:0:0'
     const lookupKey = 'C:/Users/Rod/AppData/Roaming/orca/hooks.json:session_start:0:0'
     const original = [
@@ -1651,8 +1600,7 @@ describe('readHookTrustEntries', () => {
   })
 
   it('keeps case-distinct WSL UNC hook paths distinct', () => {
-    // Why: the \\wsl$\<distro> share is case-insensitive, but the Linux tail
-    // is not — folding the whole path would merge two distinct hook sources.
+    // Why: \\wsl$\<distro> is case-insensitive but the Linux tail is not — don't fold two distinct sources.
     const upperKey = '\\\\wsl$\\Ubuntu\\home\\u\\Repo\\hooks.json:session_start:0:0'
     const lowerKey = '\\\\wsl$\\Ubuntu\\home\\u\\repo\\hooks.json:session_start:0:0'
     writeFileSync(
@@ -1720,8 +1668,7 @@ describe('readHookTrustEntries', () => {
   })
 
   it('does not extract a fake [hooks.state."<key>"] header from inside a """ block', () => {
-    // Why: a header-shaped line embedded in a multi-line basic string must not
-    // be parsed as a real trust entry.
+    // Why: a header-shaped line inside a multi-line basic string must not parse as a real entry.
     const original = [
       'description = """',
       '[hooks.state."fake-key"]',
@@ -1753,9 +1700,7 @@ describe('readHookTrustEntries', () => {
   })
 
   it('reads a block whose header has an inline comment', () => {
-    // Why: regression — headerLineRegex used to reject TOML-valid trailing
-    // comments, hiding existing trust entries from getStatus and causing
-    // it to misreport hooks as untrusted.
+    // Why: regression — headerLineRegex rejected TOML-valid trailing comments, hiding trust entries.
     const key = '/x/hooks.json:pre_tool_use:0:0'
     const original = `[hooks.state."${key}"] # user note\nenabled = true\ntrusted_hash = "sha256:CMT"\n`
     writeFileSync(configPath, original, 'utf-8')
@@ -1777,8 +1722,7 @@ describe('parseTrustKey', () => {
   })
 
   it('parses a Windows-style sourcePath whose drive letter contains a colon', () => {
-    // Why: validates the "anchor on the LAST three colons" approach so colons
-    // inside the sourcePath itself round-trip correctly.
+    // Why: anchor on the LAST three colons so colons inside sourcePath round-trip.
     expect(parseTrustKey('C:\\Users\\x\\.codex\\hooks.json:session_start:2:3')).toEqual({
       sourcePath: 'C:\\Users\\x\\.codex\\hooks.json',
       eventLabel: 'session_start',
@@ -1825,8 +1769,7 @@ describe('parseTrustKey', () => {
     })
   })
 
-  // Why: Number('') === 0 silently passes Number.isInteger; without strict
-  // canonical-form validation, malformed keys would coerce into valid ones.
+  // Why: Number('') === 0 passes Number.isInteger, so empty segments need explicit rejection.
   it('returns null for empty group/handler segments', () => {
     expect(parseTrustKey('/x/hooks.json:pre_tool_use::0')).toBeNull()
     expect(parseTrustKey('/x/hooks.json:pre_tool_use:0:')).toBeNull()
@@ -1841,9 +1784,7 @@ describe('parseTrustKey', () => {
 })
 
 describe('upsertHookTrustEntries with array-of-tables boundaries', () => {
-  // Why: findNextTableHeader must treat `[[array.of.tables]]` as a block
-  // boundary; otherwise an upsert/remove can consume past array entries
-  // into unrelated user content.
+  // Why: [[array.of.tables]] must count as a block boundary, else upsert/remove eats past array entries.
   it('stops the replacement at a following [[array.of.tables]] header', () => {
     const key = '/x/hooks.json:pre_tool_use:0:0'
     const original = [
diff --git a/src/main/codex/config-toml-trust.ts b/src/main/codex/config-toml-trust.ts
index eede0efea32..1313c4d1195 100644
--- a/src/main/codex/config-toml-trust.ts
+++ b/src/main/codex/config-toml-trust.ts
@@ -17,13 +17,8 @@ import {
   updateTomlLineScanState
 } from './config-toml-line-scan'
 
-// Why: Codex 0.129+ gates each hook on a `trusted_hash` entry in
-// ~/.codex/config.toml under [hooks.state."<key>"]. Without it the hook is in
-// the "review required" pile and never fires, so the agent-status sidebar
-// silently goes blank. We reproduce Codex's hash so install() can register
-// trust the same way `/hooks` would. Algorithm reverse-engineered from
-// codex-rs/hooks/src/engine/discovery.rs (command_hook_hash) +
-// codex-rs/config/src/fingerprint.rs (version_for_toml).
+// Why: Codex 0.129+ gates each hook on a `trusted_hash` in config.toml under [hooks.state."<key>"]; without it the hook never fires (agent-status goes blank).
+// Hash algorithm reverse-engineered from codex-rs/hooks/src/engine/discovery.rs (command_hook_hash) + config/src/fingerprint.rs (version_for_toml).
 
 export type CodexEventLabel =
   | 'pre_tool_use'
@@ -46,8 +41,7 @@ export type CodexTrustEntry = {
   handlerIndex: number
   /** The exact `command` string written to hooks.json. */
   command: string
-  /** Effective timeout in seconds. When undefined, defaults to 600.
-   *  Explicit values are clamped to a minimum of 1. */
+  /** Effective timeout in seconds; defaults to 600 when undefined, explicit values clamped to a minimum of 1. */
   timeoutSec?: number
   /** Whether the handler is async. Defaults to false. */
   async?: boolean
@@ -55,12 +49,9 @@ export type CodexTrustEntry = {
   matcher?: string
   /** Optional statusMessage field. */
   statusMessage?: string
-  /** Verbatim hash to write instead of computing one. Used when carrying a
-   *  Codex-written approval across files, so trust survives even if Codex's
-   *  hash algorithm drifts from computeTrustedHash. Never fed into hashing. */
+  /** Verbatim hash to write instead of computing one (survives Codex hash-algorithm drift). Never fed into hashing. */
   trustedHash?: string
-  /** Explicit enabled state to write. When absent, a pre-existing
-   *  `enabled = false` on the target block is preserved. */
+  /** Explicit enabled state to write; when absent, a pre-existing `enabled = false` is preserved. */
   enabled?: boolean
 }
 
@@ -71,8 +62,7 @@ export type CodexHookTrustState = {
 
 export type CodexProjectTrustLevel = 'trusted' | 'untrusted'
 
-// Why: callers use computeTrustKey() for lookups, while existing TOML can carry
-// Codex-written separator/casing variants. Normalize both sides at the Map edge.
+// Why: normalize keys at the Map edge so Codex-written separator/casing variants match computeTrustKey() lookups.
 class HookTrustEntryMap extends Map<string, CodexHookTrustState> {
   override get(key: string): CodexHookTrustState | undefined {
     return super.get(normalizeHookTrustKeyForLookup(key))
@@ -91,8 +81,7 @@ class HookTrustEntryMap extends Map<string, CodexHookTrustState> {
   }
 }
 
-// Why: matches Codex's canonical_json. Sorts object keys recursively before
-// SHA-256ing; arrays preserve order.
+// Why: matches Codex's canonical_json — recursively sorts object keys before hashing; arrays keep order.
 function canonicalize(value: unknown): unknown {
   if (Array.isArray(value)) {
     return value.map(canonicalize)
@@ -107,14 +96,7 @@ function canonicalize(value: unknown): unknown {
   return value
 }
 
-// Why: reproduces matcher_pattern_for_event (codex-rs
-// hooks/src/events/common.rs). Codex ignores matchers on
-// UserPromptSubmit/Stop and drops them from the hook identity BEFORE
-// hashing, so a hooks.json entry carrying `"matcher": ""` on those
-// events must hash the same as one without it. Including it computes a
-// hash Codex never writes: system trust then looks stale, and
-// removeStaleRuntimeHookTrustEntries deletes the entry Codex wrote on
-// every launch — an endless re-trust prompt for those two events.
+// Why: mirrors codex-rs matcher_pattern_for_event (hooks/src/events/common.rs) — Codex drops matchers on user_prompt_submit/stop before hashing, so including one yields a hash it never writes → endless re-trust.
 function matcherPatternForEvent(
   eventLabel: CodexEventLabel,
   matcher: string | undefined
@@ -133,12 +115,7 @@ function matcherPatternForEvent(
   }
 }
 
-// Why: reproduces command_hook_hash. NormalizedHookIdentity has `group:
-// MatcherGroup` flattened in, so the wire shape is { event_name, matcher?,
-// hooks: [<normalized handler>] }. `matcher` is omitted (not null) when
-// absent — Rust's Option<String>=None drops through the TOML→JSON path —
-// and normalized per event first (see matcherPatternForEvent).
-// Handler is normalized to timeout=600 (or explicit, min 1) and async=false.
+// Why: reproduces Codex's command_hook_hash; wire shape is { event_name, matcher?, hooks:[handler] } with matcher omitted (not null) when absent.
 export function computeTrustedHash(entry: CodexTrustEntry): string {
   const handler: Record<string, unknown> = {
     type: 'command',
@@ -167,10 +144,7 @@ export function computeTrustKey(entry: CodexTrustEntry): string {
 
 export function getCodexCanonicalTrustPath(sourcePath: string): string {
   try {
-    // Why: Codex canonicalizes trust paths before building config keys. On
-    // macOS, /var is a symlink to /private/var; trusting the raw path still
-    // leaves the TUI in review/trust prompts. On Windows, Codex 0.140 writes
-    // hook state keys with native raw backslashes under an explicit parent table.
+    // Why: Codex canonicalizes trust paths (e.g. macOS /var→/private/var symlink); a raw path leaves the TUI stuck in trust prompts.
     return realpathSync.native(sourcePath)
   } catch {
     return normalizeWindowsPathForCodexLookup(sourcePath)
@@ -179,8 +153,7 @@ export function getCodexCanonicalTrustPath(sourcePath: string): string {
 
 function getCodexCanonicalProjectPath(projectPath: string): string {
   try {
-    // Why: local project trust still needs Codex's realpath shape, but remote
-    // SSH callers pass an already-canonical remote path string.
+    // Why: local trust needs Codex's realpath shape, but remote SSH callers already pass a canonical path.
     return realpathSync.native(projectPath)
   } catch {
     return projectPath
@@ -209,20 +182,17 @@ function usesWindowsPathSeparators(sourcePath: string): boolean {
   )
 }
 
-// Why: Codex and Orca can disagree on quote style, separators, and casing for
-// the same Windows project, including when the caller targets a remote host.
+// Why: Codex and Orca can disagree on quote style, separators, and casing for the same Windows project.
 export function normalizeCodexProjectPathForLookup(projectPath: string): string {
   if (!usesWindowsPathSeparators(projectPath)) {
     return projectPath
   }
-  // Why: the Linux path under a WSL share is case-sensitive, so folding it would
-  // conflate distinct dirs (e.g. .../Repo vs .../repo) onto one trust key.
+  // Why: the Linux tail under a WSL share is case-sensitive, so folding it would conflate distinct dirs onto one key.
   const slashedPath = normalizeWindowsPathSeparators(projectPath)
   return foldWslUncPathCaseInsensitiveParts(slashedPath) ?? slashedPath.toLowerCase()
 }
 
-// Why: trust revocations recorded before WSL tails compared case-sensitively
-// can carry drifted casing; fold fully so matching errs toward revoked.
+// Why: old revocations can carry drifted casing; fold fully so matching errs toward revoked.
 export function normalizeCodexProjectPathForRevocationLookup(projectPath: string): string {
   const normalized = normalizeCodexProjectPathForLookup(projectPath)
   return usesWindowsPathSeparators(projectPath) ? normalized.toLowerCase() : normalized
@@ -234,9 +204,7 @@ export function parseTrustKey(key: string): {
   groupIndex: number
   handlerIndex: number
 } | null {
-  // Why: keys have shape `<sourcePath>:<eventLabel>:<groupIdx>:<handlerIdx>`.
-  // sourcePath itself may contain `:` (Windows drive letters), so anchor the
-  // parse at the LAST three colons rather than the first.
+  // Why: sourcePath may contain `:` (Windows drive letters), so anchor the parse at the last three colons.
   const lastColon = key.lastIndexOf(':')
   if (lastColon === -1) {
     return null
@@ -273,8 +241,7 @@ export function parseTrustKey(key: string): {
   }
 }
 
-// Why: Number('') === 0 and Number('1e2') === 100 both pass Number.isInteger,
-// so reject any non-canonical decimal form before numeric conversion.
+// Why: Number('') === 0 and Number('1e2') === 100 both pass Number.isInteger, so reject non-canonical decimal forms first.
 function isCanonicalNonNegativeInt(value: string): boolean {
   return /^(0|[1-9]\d*)$/.test(value)
 }
@@ -292,25 +259,14 @@ function isCodexEventLabel(value: string): value is CodexEventLabel {
   )
 }
 
-// Why: TOML 1.0 forbids BOMs but real-world editors (especially on Windows) sometimes
-// write them. A leading  would break header regexes anchored at `^[ \t]*\[`, so
-// strip it once at the file boundary and let the rest of the parser stay simple.
+// Why: strip a leading BOM (some Windows editors write one) so header regexes anchored at `^[ \t]*\[` still match.
 function readTomlFile(configPath: string): string {
   const raw = readFileSync(configPath, 'utf-8')
   return raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw
 }
 
-// Why: regex-edit ~/.codex/config.toml rather than parse + reserialize. The
-// file is hand-edited by users (and other tools) and a round-trip through
-// any TOML library would lose comments, key ordering, and inline-table
-// style. We only ever (a) replace an existing [hooks.state."<key>"] block
-// keyed by *our* known hook keys, or (b) append a new block at EOF. Other
-// content is byte-preserved.
-// Why: this is a read-modify-write with no inter-process lock. Codex CLI's
-// /hooks flow also writes [hooks.state.*] blocks in this file, so two
-// concurrent writers can lose each other's edits. writeConfigAtomically
-// prevents partial writes but not lost updates. install() is idempotent
-// (deterministic hashes), so the next install() repairs drift.
+// Why: regex-edit config.toml (not parse+reserialize) to byte-preserve user comments, key ordering, and inline-table style.
+// Why: this read-modify-write has no lock and races Codex's /hooks writer, but idempotent install() repairs any lost update.
 export function upsertHookTrustEntries(
   configPath: string,
   entries: readonly CodexTrustEntry[]
@@ -402,10 +358,7 @@ export function upsertProjectTrustLevelInContent(
   return `${existing.slice(0, headerLineEnd)}${eol}${trustLine}${existing.slice(headerLineEnd)}`
 }
 
-// Why: build the canonical block we own. The two field names mirror what
-// Codex itself writes when the user approves via /hooks (HookStateToml
-// fields). `enabled` is plumbed through so an existing user-set
-// `enabled = false` survives reinstall.
+// Why: field names mirror Codex's HookStateToml (/hooks approval); `enabled` is plumbed so a user-set `enabled = false` survives reinstall.
 function buildTrustBlock(key: string, hash: string, enabled: boolean): string {
   return [
     `[hooks.state.${formatHookStateTableKey(key)}]`,
@@ -417,8 +370,7 @@ function buildTrustBlock(key: string, hash: string, enabled: boolean): string {
 function formatHookStateTableKey(key: string): string {
   const parsed = parseTrustKey(key)
   if (parsed && usesWindowsPathSeparators(parsed.sourcePath) && !key.includes("'")) {
-    // Why: Codex 0.140 trusts Windows hooks only when the state table keys
-    // match the raw native path shape it writes after /hooks approval.
+    // Why: Codex 0.140 trusts Windows hooks only when state table keys match the raw native path shape it writes.
     return `'${key}'`
   }
   return `"${escapeTomlString(key)}"`
@@ -436,8 +388,7 @@ function getTrustKeyWriteVariants(key: string): string[] {
   ].filter((variant, index, variants) => variants.indexOf(variant) === index)
 }
 
-// Why: TOML basic strings forbid raw control chars; escape backslash first so
-// later substitutions don't double-escape the inserted backslashes.
+// Why: escape backslash first so later substitutions don't double-escape the inserted backslashes.
 export function escapeTomlString(value: string): string {
   return value
     .replaceAll('\\', '\\\\')
@@ -469,19 +420,12 @@ function upsertTrustBlocks(
     if (content.length === 0) {
       return `${block}\n`
     }
-    // Why: leave one blank line before our appended block so the file stays
-    // readable, but don't compound separators when the file already ends in
-    // a blank line.
+    // Why: one blank line before the appended block, without compounding separators when the file already ends blank.
     const separator = content.endsWith('\n\n') ? '' : content.endsWith('\n') ? '\n' : '\n\n'
     return `${content}${separator}${block}\n`
   }
 
-  // Why: preserve a user-set `enabled = false` so a hand-disabled hook is not
-  // silently re-enabled by the next auto-install on app start.
-  // If duplicate blocks already exist, treat any disabled copy as authoritative
-  // while collapsing the malformed TOML back to one table.
-  // An explicit enabled state (write-back promotion of an in-Orca /hooks
-  // toggle) overrides that preservation: it IS the user's latest decision.
+  // Why: preserve a user-set `enabled = false` (any disabled duplicate wins) unless an explicit state overrides it.
   const enabled =
     explicitEnabled ??
     !ranges.some((range) => {
@@ -505,8 +449,7 @@ function upsertTrustBlocks(
 }
 
 function buildTrustBlocks(keys: readonly string[], hash: string, enabled: boolean): string {
-  // Why: Codex 0.140 can expose Windows hook-state keys with either native
-  // backslashes or forward slashes depending on the cwd string used at startup.
+  // Why: Codex 0.140 exposes Windows hook-state keys with either backslashes or forward slashes depending on startup cwd.
   return keys.map((key) => buildTrustBlock(key, hash, enabled)).join('\n\n')
 }
 
@@ -533,13 +476,10 @@ type TrustBlockRange = {
   end: number
 }
 
-// Why: separator and casing drift between Codex-written keys (raw backslash,
-// potentially lowercased) and Orca-built keys (forward-slash, realpathSync.native
-// casing) must not prevent findTrustBlockRanges from matching an existing block.
+// Why: separator/casing drift between Codex-written and Orca-built keys must not stop findTrustBlockRanges from matching.
 export function normalizeHookTrustKeyForLookup(key: string): string {
   const parsed = parseTrustKey(key)
-  // Why: fold by path shape, not host platform — hook sources on WSL and SSH
-  // Windows remotes need the same folding when Orca runs on macOS or Linux.
+  // Why: fold by path shape, not host platform — WSL/SSH Windows remotes need folding even when Orca runs on macOS/Linux.
   const foldedPath = normalizeCodexProjectPathForLookup(parsed ? parsed.sourcePath : key)
   return parsed
     ? `${foldedPath}:${parsed.eventLabel}:${parsed.groupIndex}:${parsed.handlerIndex}`
@@ -578,8 +518,7 @@ type ParsedTomlString = {
   endIndex: number
 }
 
-// Why: Codex can write hook-state dotted keys as TOML basic strings while
-// users/Codex TUI may leave equivalent literal-string keys behind.
+// Why: hook-state keys appear as both TOML basic strings and equivalent literal-string keys.
 function parseHookStateHeaderKey(line: string): string | null {
   const trimmed = line.trimStart()
   const prefixMatch = /^\[[ \t]*hooks[ \t]*\.[ \t]*state[ \t]*\.[ \t]*/.exec(trimmed)
@@ -599,8 +538,7 @@ function parseHookStateHeaderKey(line: string): string | null {
 }
 
 export function parseCodexProjectHeaderPath(line: string): string | null {
-  // Why: mirror section headers come from split CRLF files and retain the
-  // terminal carriage return, while direct upserts scan CR-stripped lines.
+  // Why: mirror section headers retain a terminal CR (split CRLF files) while direct upserts scan CR-stripped lines.
   const trimmed = line.replace(/\r$/, '').trimStart()
   const prefixMatch = /^\[[ \t]*projects[ \t]*\.[ \t]*/.exec(trimmed)
   if (!prefixMatch) {
@@ -688,9 +626,7 @@ function skipTomlInlineWhitespace(line: string, startIndex: number): number {
   }
   return index
 }
-// Why: quoted keys can contain `]` (e.g. `[hooks.state."a]b"]`) and `[` lines
-// inside multi-line strings aren't headers, so we need a stateful scanner —
-// a flat regex misclassifies both cases.
+// Why: quoted keys can contain `]` and `[` lines inside multi-line strings aren't headers, so a flat regex misclassifies both — need a stateful scan.
 function findNextTableHeader(text: string): number {
   let cursor = 0
   let scanState = createTomlLineScanState()
@@ -701,9 +637,7 @@ function findNextTableHeader(text: string): number {
     const line = rawLine.replace(/\r$/, '')
     if (isTomlStructuralLine(scanState)) {
       const trimmed = line.trimStart()
-      // Why: stop at both `[table]` and `[[array.of.tables]]` — both end our
-      // block. Skipping `[[ ]]` here would let our slice consume past array
-      // entries into unrelated user content.
+      // Why: stop at both `[table]` and `[[array.of.tables]]`; skipping `[[ ]]` would let the slice consume unrelated content.
       if (trimmed.startsWith('[') && isCompleteTableHeader(trimmed)) {
         return cursor
       }
@@ -717,10 +651,7 @@ function findNextTableHeader(text: string): number {
   return -1
 }
 
-// Why: walk the header byte-by-byte so `]` inside a quoted key segment
-// doesn't terminate us early. Basic strings honor `\` escapes; literal
-// strings (single quotes) don't allow escapes per TOML spec.
-// Accepts both `[table]` and `[[array.of.tables]]` since either ends a block.
+// Why: walk byte-by-byte so a `]` inside a quoted key segment doesn't terminate the header early.
 function isCompleteTableHeader(line: string): boolean {
   if (!line.startsWith('[')) {
     return false
@@ -775,10 +706,7 @@ function isCompleteTableHeader(line: string): boolean {
   return false
 }
 
-// Why: same atomic-rename + .bak rotation pattern as writeHooksJson — a
-// half-written config.toml can brick a user's Codex install, so write to
-// tmp and rename. Random-suffix tmp name avoids cross-process races on
-// rapid reinstalls.
+// Why: a half-written config.toml can brick Codex, so write to a random-suffix tmp then rename (.bak rotation), avoiding cross-process races.
 export function writeConfigAtomically(configPath: string, contents: string): void {
   const dir = dirname(configPath)
   mkdirSync(dir, { recursive: true })
@@ -838,8 +766,7 @@ export function readHookTrustEntries(configPath: string): Map<string, CodexHookT
     return result
   }
   const content = readTomlFile(configPath)
-  // Why: walk line-by-line so `[hooks.state."..."]` inside a `"""..."""` or
-  // `'''...'''` multi-line string isn't mistaken for a real header.
+  // Why: walk line-by-line so a `[hooks.state."..."]` inside a multi-line string isn't mistaken for a real header.
   let cursor = 0
   let scanState = createTomlLineScanState()
   while (cursor < content.length) {
@@ -850,13 +777,11 @@ export function readHookTrustEntries(configPath: string): Map<string, CodexHookT
     const nextCursor = newlineIdx === -1 ? content.length : newlineIdx + 1
     const key = isTomlStructuralLine(scanState) ? parseHookStateHeaderKey(line) : null
     if (key !== null) {
-      // Why: block ends at the next *real* header (multi-line aware).
       const after = content.slice(nextCursor)
       const nextHeaderRel = findNextTableHeader(after)
       const blockEnd = nextHeaderRel === -1 ? content.length : nextCursor + nextHeaderRel
       const block = content.slice(nextCursor, blockEnd)
-      // Why: we own this block's shape (only `enabled` + `trusted_hash`), so
-      // a line scan beats pulling in a full TOML value parser.
+      // Why: we own this block's shape (only `enabled` + `trusted_hash`), so a line scan beats a full TOML parser.
       const hashMatch = /^[ \t]*trusted_hash[ \t]*=[ \t]*"((?:[^"\\]|\\.)*)"/m.exec(block)
       const enabledMatch = /^[ \t]*enabled[ \t]*=[ \t]*(true|false)[ \t\r]*(?:#.*)?$/m.exec(block)
       const normalizedKey = normalizeHookTrustKeyForLookup(key)
@@ -864,8 +789,7 @@ export function readHookTrustEntries(configPath: string): Map<string, CodexHookT
       const enabled = enabledMatch ? enabledMatch[1] === 'true' : undefined
       result.set(normalizedKey, {
         trustedHash: hashMatch ? unescapeTomlString(hashMatch[1]) : existingState?.trustedHash,
-        // Why: Windows writes both slash variants for one hook; a disabled copy
-        // must remain authoritative regardless of which variant appears last.
+        // Why: Windows writes both slash variants for one hook; a disabled copy stays authoritative.
         enabled:
           existingState?.enabled === false || enabled === false
             ? false
@@ -902,8 +826,7 @@ function unescapeTomlBasicStringEscape(next: string): string {
   if (next === '\\') {
     return '\\'
   }
-  // Why: unknown escapes round-trip — preserve the backslash so we don't
-  // silently drop information.
+  // Why: unknown escapes round-trip — preserve the backslash so info isn't dropped.
   return `\\${next}`
 }
 
diff --git a/src/main/codex/hook-service.ts b/src/main/codex/hook-service.ts
index b09a94f5ede..59dcf14c16a 100644
--- a/src/main/codex/hook-service.ts
+++ b/src/main/codex/hook-service.ts
@@ -67,11 +67,7 @@ import {
   snapshotCodexRuntimeHookTrustProvenance
 } from './hook-trust-promotion'
 
-// Why: PreToolUse/PostToolUse give the dashboard a live readout of the
-// in-flight tool (name + input preview) between UserPromptSubmit and Stop.
-// PermissionRequest is the human-input boundary: the managed script exits
-// without a decision so Codex still shows its normal approval UI, while Orca
-// can flip the pane to the red waiting state.
+// Why: Pre/PostToolUse feed the live in-flight-tool readout; PermissionRequest exits with no decision so Codex still shows its approval UI while Orca flips the pane to waiting.
 const CODEX_EVENTS = [
   'SessionStart',
   'UserPromptSubmit',
@@ -86,8 +82,7 @@ function getConfigPath(): string {
 }
 
 function writeCodexHooksJson(configPath: string, hooks: Record<string, HookDefinition[]>): void {
-  // Why: Codex rejects unknown top-level hooks.json fields, so plugin manager
-  // bookkeeping such as `_managed` must not survive Orca's rewrite.
+  // Why: Codex rejects unknown top-level hooks.json fields, so plugin bookkeeping like `_managed` must not survive Orca's rewrite.
   writeHooksJson(configPath, { hooks })
 }
 
@@ -95,8 +90,7 @@ function getCodexConfigTomlPath(): string {
   return join(getOrcaManagedCodexHomePath(), 'config.toml')
 }
 
-// Why: the managed-event subset of the shared PascalCase→label map; the
-// full mapping lives in codex-hook-identity.ts so promotion can't drift.
+// Why: managed-event subset of the shared label map; full mapping lives in codex-hook-identity.ts so promotion can't drift.
 const CODEX_EVENT_LABEL: Record<(typeof CODEX_EVENTS)[number], CodexEventLabel> = {
   SessionStart: CODEX_HOOK_EVENT_LABEL.SessionStart!,
   UserPromptSubmit: CODEX_HOOK_EVENT_LABEL.UserPromptSubmit!,
@@ -141,8 +135,7 @@ export type { CodexWslRuntimeHookInstallPlan }
 
 function wrapReadablePosixHookCommand(scriptPath: string): string {
   const quoted = `'${scriptPath.replaceAll("'", "'\\''")}'`
-  // Why: WSL runtime hooks are written from Windows through UNC, where the
-  // executable bit is not reliable; a missing script must still own stdin.
+  // Why: WSL hooks are written from Windows over UNC where the exec bit is unreliable; a missing script must still own stdin.
   return `if [ -f ${quoted} ] && [ -r ${quoted} ]; then /bin/sh ${quoted}; else ${POSIX_HOOK_STDIN_DRAIN_COMMAND}; fi`
 }
 
@@ -240,9 +233,7 @@ function commandUsesCodexPluginOnlyPlaceholder(command: string | undefined): boo
 }
 
 function removeCodexPluginEnvironmentCommands(definitions: HookDefinition[]): HookDefinition[] {
-  // Why: Orca mirrors system hooks into a plain runtime hooks.json. Plugin
-  // placeholders only work for Codex plugin hook sources, so copying those
-  // commands here strips the environment they require and turns them into 127s.
+  // Why: plugin placeholders only resolve for Codex plugin hook sources; mirroring them into a plain runtime hooks.json turns them into 127s.
   return removeManagedCommands(definitions, commandUsesCodexPluginOnlyPlaceholder)
 }
 
@@ -282,9 +273,7 @@ function getRuntimeHooksWithSystemUserHooks(
       continue
     }
 
-    // Why: runtime hooks are derived from the user's system hooks plus Orca's
-    // managed hooks. Reusing old runtime user-hook copies would keep deleted or
-    // edited ~/.codex/hooks.json entries alive for new Orca-launched sessions.
+    // Why: rebuild from system hooks; reusing old runtime copies would keep deleted/edited ~/.codex/hooks.json entries alive for new sessions.
     nextHooks[eventName] = dedupeHookDefinitions(systemUserDefinitions)
   }
 
@@ -314,8 +303,7 @@ function getTrustedSystemUserHookSignatures(
   try {
     trustEntries = readHookTrustEntries(getSystemCodexConfigTomlPath())
   } catch (error) {
-    // Why: a hand-broken system config.toml should only disable user-hook
-    // trust mirroring; Orca's managed runtime hooks can still be installed.
+    // Why: a hand-broken system config.toml should only disable user-hook trust mirroring, not block Orca's managed runtime hooks.
     console.warn('[codex-hook-service] failed to read system hook trust entries', error)
     return signatures
   }
@@ -346,8 +334,7 @@ function getTrustedSystemUserHookSignatures(
           return
         }
         const signature = getCodexHookTrustSignature(entry)
-        // Why: runtime deduping collapses identical system hook definitions;
-        // if any duplicate remains enabled, keep the mirrored hook enabled.
+        // Why: runtime deduping collapses identical definitions; if any duplicate stays enabled, keep the mirrored hook enabled.
         if (state.enabled || !signatures.has(signature)) {
           signatures.set(signature, state)
         }
@@ -372,11 +359,7 @@ function resolveTrustedSystemHookState(
     return { enabled: reorderedEnabled, trustedHash: expectedHash }
   }
   if (state?.trustedHash) {
-    // Why: carry a key-matched system hash verbatim instead of dropping it as
-    // stale. Codex is the authority on its own hash algorithm; recomputing
-    // here is what turned #7110-style hash drift into an endless re-approval
-    // loop. If the hash is genuinely stale (edited hook), Codex prompts —
-    // exactly what a plain ~/.codex session would do.
+    // Why: carry a key-matched system hash verbatim — recomputing caused #7110 re-approval loops since Codex owns its hash algorithm.
     return { enabled: state.enabled !== false, trustedHash: state.trustedHash }
   }
   return null
@@ -402,8 +385,7 @@ function getTrustedSystemHookHashesByEvent(
       trustedHashesByEvent.set(parsed.eventLabel, hashes)
     }
     const enabled = state.enabled !== false
-    // Why: Codex trust keys include hook indices. If a user reorders hooks,
-    // the hash still proves the same event+command identity was approved.
+    // Why: Codex trust keys include hook indices, but the hash still proves the same event+command identity was approved after a reorder.
     if (enabled || !hashes.has(state.trustedHash)) {
       hashes.set(state.trustedHash, enabled)
     }
@@ -488,8 +470,7 @@ function buildHookTrustHeaderKeyPattern(key: string): string {
   const alternatives = [...new Set(keyVariants)].flatMap((variant) => {
     const quoted = [`"${escapeRegex(escapeTomlString(variant))}"`]
     if (!variant.includes("'")) {
-      // Why: tolerate raw-backslash literal keys left by Codex/manual approval
-      // while Orca repairs mirrored runtime trust across both Windows variants.
+      // Why: tolerate raw-backslash literal keys from Codex/manual approval while repairing mirrored runtime trust across both Windows variants.
       quoted.push(`'${escapeRegex(variant)}'`)
     }
     return quoted
@@ -573,11 +554,9 @@ function cleanupLegacySystemManagedHooks(): void {
     }
   }
 
-  // Why: Codex hooks moved to Orca's managed CODEX_HOME; old entries in
-  // ~/.codex would keep external Codex sessions reporting into Orca.
+  // Why: Codex hooks moved to Orca's managed CODEX_HOME; stale ~/.codex entries would keep external Codex sessions reporting into Orca.
   if (removedManagedHook) {
-    // Why: this is the user's system hooks file, not Orca's runtime copy.
-    // Remove only stale Orca hook entries and preserve other managers' metadata.
+    // Why: this is the user's system hooks file, not Orca's runtime copy; remove only stale Orca entries and preserve other managers' metadata.
     writeHooksJson(legacyConfigPath, { ...config, hooks: nextHooks })
   }
   removeMatchingTrustEntries(getSystemCodexConfigTomlPath(), trustEntries)
@@ -612,8 +591,7 @@ function cleanupLegacyCodexProfileHooks(): void {
   if (next === existing) {
     return
   }
-  // Why: #2778 wrote Orca hooks into a Codex profile file. Runtime CODEX_HOME
-  // supersedes that representation, so remove only Orca's marked block.
+  // Why: #2778 wrote Orca hooks into a Codex profile file; runtime CODEX_HOME supersedes it, so remove only Orca's marked block.
   if (next.trim().length === 0) {
     unlinkSync(profilePath)
   } else {
@@ -639,10 +617,7 @@ function removeRuntimeManagedHookTrustEntries(configPath: string): void {
     const managedEventLabels = new Set<CodexEventLabel>(
       CODEX_EVENTS.map((event) => CODEX_EVENT_LABEL[event])
     )
-    // Why: only drop entries WE wrote. The same config.toml can contain
-    // user-approved trust entries for non-Orca commands, so match by hash
-    // equivalence to our managed command — a sourcePath-only filter would
-    // wipe the user's manually-approved entries.
+    // Why: drop only entries we wrote — match by hash to our managed command, since a sourcePath-only filter would wipe user-approved non-Orca entries.
     const ourKeys: string[] = []
     const canonicalConfigPath = getCodexCanonicalTrustPath(configPath)
     for (const [key, state] of existingEntries) {
@@ -662,8 +637,7 @@ function removeRuntimeManagedHookTrustEntries(configPath: string): void {
         groupIndex: parts.groupIndex,
         handlerIndex: parts.handlerIndex,
         command,
-        // Why: match the timeout install() wrote, or remove() would fail to
-        // recognize (and clean up) its own managed trust entries.
+        // Why: match the timeout install() wrote, or remove() can't recognize and clean up its own managed trust entries.
         timeoutSec: MANAGED_HOOK_TIMEOUT_SECONDS
       }
       const recognizedHashes = new Set([
@@ -679,8 +653,7 @@ function removeRuntimeManagedHookTrustEntries(configPath: string): void {
       removeHookTrustEntries(tomlPath, ourKeys)
     }
   } catch (error) {
-    // Best effort — stale trust entries are harmless once hooks.json no
-    // longer references the hook. Log so a programmer error doesn't disappear silently.
+    // Best effort — stale trust is harmless once hooks.json no longer references the hook; log so a programmer error isn't silent.
     console.warn('[codex-hook-service] failed to clean trust entries', error)
   }
 }
@@ -725,8 +698,7 @@ function removeWslRuntimeManagedHookTrustEntries(plan: CodexWslRuntimeHookInstal
       removeHookTrustEntries(plan.tomlPath, ourKeys)
     }
   } catch (error) {
-    // Why: removing disabled WSL status hooks should be best-effort like the
-    // host cleanup path; stale trust is inert once hooks.json no longer points at us.
+    // Why: best-effort like host cleanup; stale trust is inert once hooks.json no longer points at us.
     console.warn('[codex-hook-service] failed to clean WSL trust entries', error)
   }
 }
@@ -749,8 +721,7 @@ function removeStaleWslRuntimeManagedHookTrustEntries(
       continue
     }
     const sourcePath = parts.sourcePath
-    // Why: this cleanup owns only guest-side WSL trust. A runtime config can
-    // still contain user Windows/remote hooks, which must remain untouched.
+    // Why: this cleanup owns only guest-side WSL trust; leave any user Windows/remote hooks in the runtime config untouched.
     if (!sourcePath.startsWith('/') || !sourcePath.endsWith('/hooks.json')) {
       continue
     }
@@ -782,10 +753,7 @@ function getManagedScript(target: 'local' | 'posix' = 'local'): string {
     return [
       '@echo off',
       'setlocal',
-      // Why: see claude/hook-service.ts for rationale. The endpoint file holds
-      // the live port/token for this Orca install; sourcing it here lets a
-      // surviving PTY reach the current server even though its env points at
-      // the prior Orca's coordinates.
+      // Why: the endpoint file holds this install's live port/token; sourcing it lets a surviving PTY reach the current server (see claude/hook-service.ts).
       'if defined ORCA_AGENT_HOOK_ENDPOINT if exist "%ORCA_AGENT_HOOK_ENDPOINT%" call "%ORCA_AGENT_HOOK_ENDPOINT%" 2>nul',
       ...buildWindowsHookEnvironmentGuardLines(),
       buildWindowsAgentHookCurlPostCommand('codex'),
@@ -798,15 +766,12 @@ function getManagedScript(target: 'local' | 'posix' = 'local'): string {
   return [
     '#!/bin/sh',
     ...buildPosixHookPayloadCapture(),
-    // Why: see claude/hook-service.ts for rationale. Sourcing refreshes
-    // PORT/TOKEN/ENV/VERSION from the current Orca so a surviving PTY keeps
-    // reporting after a restart.
+    // Why: sourcing refreshes PORT/TOKEN/ENV/VERSION from the current Orca so a surviving PTY keeps reporting after a restart (see claude/hook-service.ts).
     'load_hook_endpoint() {',
     '  endpoint_path="$1"',
     '  case "$endpoint_path" in',
     '    *.cmd)',
-    // Why: Windows passes endpoint.cmd into WSL through WSLENV path translation.
-    // Parse only Orca's known assignments; cmd.exe `set` lines are not shell syntax.
+    // Why: Windows passes endpoint.cmd into WSL via WSLENV; parse only Orca's known assignments since cmd.exe `set` lines aren't shell syntax.
     '      endpoint_cr=$(printf "\\r")',
     '      while IFS= read -r endpoint_line || [ -n "$endpoint_line" ]; do',
     '        endpoint_line=${endpoint_line%"$endpoint_cr"}',
@@ -833,13 +798,8 @@ function getManagedScript(target: 'local' | 'posix' = 'local'): string {
     '  curl_bin="$1"',
     '  connect_timeout="${2:-0.5}"',
     '  max_time="${3:-1.5}"',
-    // Why: worktreeId embeds a filesystem path, so hand-building JSON in POSIX
-    // shell is not safe once a path contains quotes or newlines. Post the raw
-    // hook payload plus metadata as form fields and let the receiver parse it.
-    // Timeout caps best-effort hook posts if the local listener stalls.
-    // Why: pipe payload to curl's stdin (`payload@-`) instead of an inline
-    // `payload=$VALUE` arg, so tens-of-KB tool output stays off the curl
-    // command line (EDR command-line false positives). Wire body is identical.
+    // Why: worktreeId embeds a path, so hand-building JSON in shell is unsafe with quotes/newlines; post raw payload plus metadata as form fields instead.
+    // Why: pipe payload to curl's stdin (`payload@-`) not an inline arg, so tens-of-KB tool output stays off the command line (EDR false positives).
     '  printf \'%s\' "$payload" | "$curl_bin" -sS -X POST "http://127.0.0.1:${ORCA_AGENT_HOOK_PORT}/hook/codex" \\',
     '    --connect-timeout "$connect_timeout" --max-time "$max_time" \\',
     '    --noproxy "127.0.0.1" \\',
@@ -923,8 +883,7 @@ function installManagedHooksIntoWslRuntime(
   writeManagedScript(plan.scriptPath, getManagedScript('posix'))
   writeCodexHooksJson(plan.configPath, nextHooks)
   try {
-    // Why: WSL runtime homes may carry user hook approvals we did not rebuild
-    // here; only upsert Orca's entries instead of sweeping the whole source.
+    // Why: WSL runtime homes may carry user hook approvals we didn't rebuild; upsert only Orca's entries instead of sweeping the whole source.
     upsertHookTrustEntries(plan.tomlPath, trustEntries)
     removeStaleWslRuntimeManagedHookTrustEntries(plan.tomlPath, trustEntries)
   } catch (error) {
@@ -974,8 +933,7 @@ function refreshWslRuntimeUserHooks(plan: CodexWslRuntimeHookInstallPlan): Agent
   writeCodexHooksJson(plan.configPath, nextHooks)
   removeWslRuntimeManagedHookTrustEntries(plan)
   try {
-    // Why: the disabled path may be reached after the WSL mount root changed,
-    // so cleanup cannot be scoped only to the plan's current source path.
+    // Why: the disabled path may run after the WSL mount root changed, so cleanup can't be scoped to the plan's current source path.
     removeStaleWslRuntimeManagedHookTrustEntries(plan.tomlPath, [])
   } catch (error) {
     console.warn('[codex-hook-service] failed to clean stale WSL trust entries', error)
@@ -989,8 +947,7 @@ function refreshWslRuntimeUserHooks(plan: CodexWslRuntimeHookInstallPlan): Agent
   }
 }
 
-// Why: transport failures preserve the last known-good identity, while a
-// successful absence probe is strong enough to revoke trust immediately.
+// Why: transport failures preserve last known-good identity; a successful absence probe is strong enough to revoke trust immediately.
 function getWslHookReconciliationAction(args: {
   settlement: WslCanonicalPathSettlement
   isCurrentGeneration: boolean
@@ -1013,8 +970,7 @@ function getWslHookReconciliationAction(args: {
   return 'reinstall'
 }
 
-// Why: fold only the Windows-case-insensitive portion — a full lowercase would
-// let case-distinct WSL runtime homes share one reconciliation generation slot.
+// Why: fold only the Windows-case-insensitive portion; a full lowercase would let case-distinct WSL homes share one reconciliation slot.
 function getWslReconciliationKey(runtimeHomePath: string): string {
   return normalizeCodexProjectPathForLookup(runtimeHomePath)
 }
@@ -1114,15 +1070,10 @@ export class CodexHookService {
       }
     }
 
-    // Why: Report `partial` when managed events are missing OR when their
-    // trust entries are missing/stale. Codex 0.129+ silently drops untrusted
-    // hooks, so a green status without trust verification is misleading.
+    // Why: Codex 0.129+ silently drops untrusted hooks, so report `partial` when managed events OR their trust entries are missing/stale.
     const command = getManagedCommand(scriptPath)
     const tomlPath = getCodexConfigTomlPath()
-    // Why: an unreadable config.toml (EACCES/EIO) is distinct from "file
-    // absent" (which returns an empty Map without throwing). Hooks.json may
-    // still be fine, so report partial with a specific reason rather than
-    // collapsing to a generic error or masking it as universally-stale trust.
+    // Why: an unreadable config.toml (EACCES/EIO) differs from "absent" (empty Map); hooks.json may be fine, so report partial with a specific reason.
     let trustEntries: Map<string, CodexHookTrustState>
     let trustReadError: string | null = null
     try {
@@ -1138,16 +1089,12 @@ export class CodexHookService {
     let presentCount = 0
     for (const eventName of CODEX_EVENTS) {
       const definitions = Array.isArray(config.hooks?.[eventName]) ? config.hooks![eventName]! : []
-      // Why: older installs appended this command, while current installs
-      // prepend it. Picking the last match keeps status repair conservative
-      // if duplicate managed definitions survive from a stale hooks.json.
+      // Why: older installs appended, current ones prepend; last-match keeps status repair conservative when stale duplicate definitions survive.
       let foundGroupIndex = -1
       let foundHandlerIndex = -1
       definitions.forEach((definition, idx) => {
         const hooks = definition.hooks ?? []
-        // Why: mirror the LAST-match-wins rule at the group level — if a user
-        // merged hook arrays and ended up with our command at multiple indices
-        // in one group, the surviving runtime entry is the last one.
+        // Why: last-match-wins at the group level — if merged hook arrays repeat our command, the surviving runtime entry is the last one.
         const handlerIdx = hooks.findLastIndex((hook) => hook.command === command)
         if (handlerIdx !== -1) {
           foundGroupIndex = idx
@@ -1159,14 +1106,9 @@ export class CodexHookService {
         continue
       }
       presentCount += 1
-      // Why: a stale hash blocks firing the same as a missing entry, so
-      // compare against the canonical hash we would write.
-      // Why: capture the actual handler index — Codex's hook_key uses the
-      // positional handlerIndex, and a user-merged hook array can put our
-      // command at a non-zero slot, so hardcoding 0 would misreport trust.
-      // Why: the managed hook is written with `timeout` (see install()), and
-      // Codex folds the handler timeout into its trust hash. Hash the same
-      // timeout here or status would report every managed hook as stale-trust.
+      // Why: a stale hash blocks firing like a missing entry, so compare against the canonical hash we would write.
+      // Why: Codex's hook_key is positional, so hardcoding handlerIndex 0 misreports trust for user-merged hook arrays.
+      // Why: hash the same `timeout` install() writes, since Codex folds it into the trust hash or every managed hook reports stale-trust.
       const trustInput: CodexTrustEntry = {
         sourcePath: configPath,
         eventLabel: CODEX_EVENT_LABEL[eventName],
@@ -1188,8 +1130,7 @@ export class CodexHookService {
     let detail: string | null
     if (presentCount === 0) {
       state = 'not_installed'
-      // Why: surface the trust read error even when not_installed so the user
-      // has actionable info if config.toml is broken.
+      // Why: surface the trust read error even when not_installed, so a broken config.toml gives actionable info.
       detail = trustReadError !== null ? `Trust entries unverifiable: ${trustReadError}` : null
     } else if (
       missing.length === 0 &&
@@ -1221,10 +1162,7 @@ export class CodexHookService {
   install(): AgentHookInstallStatus {
     const configPath = getConfigPath()
     const scriptPath = getManagedScriptPath()
-    // Why: must run before this install rewrites hooks.json/config.toml —
-    // approvals the user made inside Orca-launched Codex are keyed to the
-    // previous launch's runtime layout, and stale-trust cleanup below would
-    // delete them once the system config stops backing them.
+    // Why: run before install rewrites hooks.json/config.toml, since stale-trust cleanup would delete in-Orca approvals keyed to the prior layout.
     promoteCodexRuntimeHookApprovalsToSystem()
     const config = readHooksJson(configPath)
     if (!config) {
@@ -1237,29 +1175,20 @@ export class CodexHookService {
       }
     }
 
-    // Why: match by script filename (not exact command string) so a fresh
-    // install sweeps stale entries left by older builds or a different
-    // Electron userData path (dev vs. prod). Without this, repeated installs
-    // accumulate duplicate hook entries pointing at defunct scripts.
+    // Why: match by script filename (not exact command) so a fresh install sweeps stale entries from older builds or a different userData path.
     const isManagedCommand = createManagedCommandMatcher(getCodexManagedScriptFileName())
     const command = getManagedCommand(scriptPath)
     const hookPlan = getRuntimeHooksWithSystemUserHooks(config.hooks, isManagedCommand)
     const nextHooks = hookPlan.hooks
     const managedEvents = new Set<string>(CODEX_EVENTS)
 
-    // Why: sweep managed entries out of events we no longer subscribe to
-    // (e.g., PreToolUse from a prior install). Without this, users who
-    // already had PreToolUse registered would keep firing stale hooks on
-    // every auto-approved tool call after the app upgrade.
+    // Why: sweep managed entries from events we no longer subscribe to (e.g. a prior install's PreToolUse), else they keep firing stale hooks after upgrade.
     for (const [eventName, definitions] of Object.entries(nextHooks)) {
       if (managedEvents.has(eventName)) {
         continue
       }
       if (!Array.isArray(definitions)) {
-        // Why: a malformed hooks.json entry (non-array value for an event name)
-        // would make removeManagedCommands throw. Skip instead — we aren't
-        // going to sweep something we can't parse, and the install() for
-        // managed events below still runs.
+        // Why: a non-array event value would make removeManagedCommands throw; skip the unparsable entry, managed events below still install.
         continue
       }
       const cleaned = removeManagedCommands(definitions, isManagedCommand)
@@ -1270,10 +1199,7 @@ export class CodexHookService {
       }
     }
 
-    // Why: Codex 0.129+ requires a per-hook trust entry in config.toml or the
-    // hook sits in the "review required" pile. We compute the trust hash for
-    // each managed entry as we install it and persist it alongside hooks.json
-    // so the user does not have to /hooks-approve after every install.
+    // Why: Codex 0.129+ requires a per-hook config.toml trust entry or the hook needs manual /hooks-approve; precompute the hash to avoid that.
     const mirroredUserTrustEntries = moveMirroredRuntimeUserTrustAfterManagedStatusHook(
       hookPlan.trustEntries
     )
@@ -1285,11 +1211,8 @@ export class CodexHookService {
         hooks: [buildManagedCommandHook(command)]
       }
       nextHooks[eventName] = [definition, ...cleaned]
-      // Why: the status hook must run before user hooks so a slow
-      // PostToolUse/Stop hook cannot leave the sidebar stuck on the previous
-      // state while Codex visibly reports that hooks are still running.
-      // timeoutSec mirrors the hook's `timeout` so the trust hash matches the
-      // entry actually written to hooks.json.
+      // Why: status hook runs before user hooks so a slow PostToolUse/Stop hook can't leave the sidebar stuck on the previous state.
+      // Why: timeoutSec mirrors the hook's `timeout` so the trust hash matches the entry written to hooks.json.
       trustEntries.push({
         sourcePath: configPath,
         eventLabel: CODEX_EVENT_LABEL[eventName],
@@ -1303,17 +1226,12 @@ export class CodexHookService {
     config.hooks = nextHooks
     writeManagedScript(scriptPath, getManagedScript())
     writeCodexHooksJson(configPath, nextHooks)
-    // Why: trust entries write last so a half-write can't leave a hash
-    // pointing at a hook that doesn't exist. Surface failures — without this,
-    // getStatus would report green for a hook Codex won't actually fire.
+    // Why: trust entries write last so a half-write can't leave a hash pointing at a nonexistent hook.
+    // Why: surface trust-write failures — otherwise getStatus reports green for a hook Codex won't fire.
     try {
       const tomlPath = getCodexConfigTomlPath()
       syncSystemConfigIntoManagedCodexHome()
-      // Why: system user hook approvals are mirrored into runtime CODEX_HOME.
-      // If the user later revokes approval in ~/.codex/config.toml, preserving
-      // all old runtime [hooks.state.*] blocks would keep Orca Codex trusted.
-      // Upsert first so duplicate repair can preserve a disabled managed copy
-      // before stale cleanup removes old managed hook keys.
+      // Why: don't let revoked ~/.codex approvals survive as stale runtime trust; upsert before cleanup to preserve a disabled managed copy.
       upsertHookTrustEntries(tomlPath, trustEntries)
       removeStaleRuntimeHookTrustEntries(tomlPath, configPath, trustEntries)
       applyMirroredRuntimeUserHookTrustStates(tomlPath, mirroredUserTrustEntries)
@@ -1340,14 +1258,9 @@ export class CodexHookService {
     sftp: SFTPWrapper,
     remoteHome: string,
     options?: {
-      /** Explicit CODEX_HOME dir (flat layout: hooks.json/config.toml at its
-       *  root). WSL sessions read Orca's managed runtime home, not ~/.codex —
-       *  installing to the default location leaves those sessions hookless. */
+      /** Explicit CODEX_HOME dir (flat layout). WSL sessions read Orca's managed runtime home, not ~/.codex, so the default location leaves them hookless. */
       codexHomeDir?: string
-      /** Skip the trust write when config.toml doesn't exist yet. The WSL
-       *  runtime home's config.toml is seeded only-if-absent by the launch
-       *  path; creating it here first would silently cancel that seed. A
-       *  later (idempotent) reinstall upserts trust once the seed lands. */
+      /** Skip the trust write when config.toml is absent — the WSL launch path seeds it only-if-absent, so creating it here would cancel that seed. */
       deferTrustUntilConfigToml?: boolean
     }
   ): Promise<AgentHookInstallStatus> {
@@ -1404,13 +1317,10 @@ export class CodexHookService {
       }
 
       config.hooks = nextHooks
-      // Why: script/settings first, trust TOML last. A partial trust write
-      // leaves Codex asking for approval rather than executing a missing script.
-      // Why: SSH remotes use POSIX `.sh` hook paths even when Orca itself is
-      // running on Windows; never derive remote script syntax from local OS.
+      // Why: write script/settings before trust TOML; a partial trust write leaves Codex asking approval instead of running a missing script.
+      // Why: SSH remotes use POSIX `.sh` paths even when Orca runs on Windows; never derive remote script syntax from local OS.
       await writeManagedScriptRemote(sftp, remoteScriptPath, getManagedScript('posix'))
-      // Why: SSH installs edit the user's remote ~/.codex/hooks.json directly.
-      // Preserve non-Orca top-level metadata while replacing the hooks tree.
+      // Why: SSH edits the user's remote ~/.codex/hooks.json directly, so preserve non-Orca top-level metadata while replacing the hooks tree.
       await writeHooksJsonRemote(sftp, remoteConfigPath, { ...config, hooks: nextHooks })
       try {
         const existingTomlRaw = await readTextFileRemote(sftp, remoteTomlPath)
@@ -1460,13 +1370,11 @@ export class CodexHookService {
 
   refreshRuntimeUserHooks(): AgentHookInstallStatus {
     const configPath = getConfigPath()
-    // Why: same as install() — capture in-Orca approvals before this refresh
-    // rewrites the runtime files they are keyed against.
+    // Why: capture in-Orca approvals before this refresh rewrites the runtime files they are keyed against.
     promoteCodexRuntimeHookApprovalsToSystem()
     const config = readHooksJson(configPath)
     if (!config) {
-      // Why: disabled launch prep used to call remove(); preserve its legacy
-      // cleanup behavior even when runtime hooks.json is malformed.
+      // Why: disabled launch prep once called remove(); preserve that legacy cleanup even when runtime hooks.json is malformed.
       cleanupLegacyManagedHookRepresentations()
       return {
         agent: 'codex',
@@ -1486,10 +1394,7 @@ export class CodexHookService {
       const tomlPath = getCodexConfigTomlPath()
       const trustEntries = hookPlan.trustEntries.map(({ entry }) => entry)
       syncSystemConfigIntoManagedCodexHome()
-      // Why: this path is used when Orca status hooks are disabled. The
-      // runtime CODEX_HOME should keep user hooks, but not Orca-managed trust.
-      // Write current mirrored user trust first so stale cleanup compares
-      // against current hashes while deleting old managed hook keys.
+      // Why: disabled path keeps user hooks but not managed trust; write mirrored trust first so stale cleanup compares against current hashes.
       upsertHookTrustEntries(tomlPath, trustEntries)
       removeStaleRuntimeHookTrustEntries(tomlPath, configPath, trustEntries)
       applyMirroredRuntimeUserHookTrustStates(tomlPath, hookPlan.trustEntries)
@@ -1513,8 +1418,7 @@ export class CodexHookService {
     const configExists = existsSync(configPath)
     const config = readHooksJson(configPath)
     if (!config) {
-      // Why: a malformed runtime hooks.json should not strand old hooks in
-      // ~/.codex or the legacy profile after the user disables Codex hooks.
+      // Why: a malformed hooks.json shouldn't strand old hooks in ~/.codex or the legacy profile after disabling.
       cleanupLegacyManagedHookRepresentations()
       return {
         agent: 'codex',
@@ -1526,14 +1430,11 @@ export class CodexHookService {
     }
 
     const nextHooks = { ...config.hooks }
-    // Why: same broad matcher as install(), so remove() also cleans up stale
-    // entries from older builds even if the current scriptPath has moved.
+    // Why: same broad matcher as install() so stale entries from older builds get cleaned even if scriptPath moved.
     const isManagedCommand = createManagedCommandMatcher(getCodexManagedScriptFileName())
     for (const [eventName, definitions] of Object.entries(nextHooks)) {
       if (!Array.isArray(definitions)) {
-        // Why: a malformed hooks.json entry (non-array value for an event name)
-        // would make removeManagedCommands throw. Skip instead — we have no
-        // managed commands to remove from something we can't parse.
+        // Why: a non-array event value would make removeManagedCommands throw; skip it.
         continue
       }
       const cleaned = removeManagedCommands(definitions, isManagedCommand)
@@ -1544,14 +1445,11 @@ export class CodexHookService {
       }
     }
     if (configExists) {
-      // Why: remove() can be the only repair path for a parseable runtime file
-      // whose top-level plugin metadata makes Codex reject hooks.json.
+      // Why: remove() may be the only repair path for a file whose top-level plugin metadata makes Codex reject hooks.json.
       writeCodexHooksJson(configPath, nextHooks)
     }
 
-    // Why: also drop our trust entries so config.toml doesn't accumulate dead
-    // [hooks.state."..."] blocks across install/remove cycles. Best-effort —
-    // a stale entry is harmless once hooks.json no longer references it.
+    // Why: drop trust entries so config.toml doesn't accumulate dead [hooks.state] blocks across install/remove cycles.
     removeRuntimeManagedHookTrustEntries(configPath)
 
     cleanupLegacyManagedHookRepresentations()
diff --git a/src/main/cursor/hook-service.ts b/src/main/cursor/hook-service.ts
index b1ccdbf126d..9ce9172f8fb 100644
--- a/src/main/cursor/hook-service.ts
+++ b/src/main/cursor/hook-service.ts
@@ -26,22 +26,8 @@ import {
   buildWindowsHookStdinDrainEpilogue
 } from '../agent-hooks/hook-stdin-contract'
 
-// Why: cursor-agent exposes a declarative hooks.json surface at
-// ~/.cursor/hooks.json (https://cursor.com/docs/hooks) with camelCase event
-// names. We subscribe to the minimum set that drives the sidebar spinner and
-// turn-boundary detection:
-//   - beforeSubmitPrompt: new turn starts (carries the user's prompt)
-//   - stop:               turn ends (→ done)
-//   - preToolUse/postToolUse/postToolUseFailure: in-flight tool preview
-//     between submit and stop — without these the pane appears idle for the
-//     entire duration of a long tool-heavy turn
-//   - beforeShellExecution / beforeMCPExecution: shell/MCP tool preview (→ working)
-//   - afterAgentResponse: carries the final composed reply text so the
-//     dashboard can surface it on done
-// sessionStart / sessionEnd are intentionally NOT subscribed — cursor-agent
-// fires them at process lifetime boundaries rather than at turn boundaries,
-// and sessionStart's fire-time can race the first beforeSubmitPrompt in a
-// way that would reset the prompt cache for the just-submitted turn.
+// cursor-agent's declarative hooks surface (https://cursor.com/docs/hooks); subscribe to the minimum set for spinner + turn detection.
+// sessionStart/sessionEnd are NOT subscribed: they fire at process (not turn) boundaries and can race/reset the just-submitted turn's prompt cache.
 const CURSOR_EVENTS = [
   'beforeSubmitPrompt',
   'stop',
@@ -76,10 +62,7 @@ function getManagedScript(target: 'local' | 'posix' = 'local'): string {
     return [
       '@echo off',
       'setlocal',
-      // Why: see claude/hook-service.ts for rationale. The endpoint file holds
-      // the live port/token for this Orca install; sourcing it here lets a
-      // surviving PTY reach the current server even though its env points at
-      // the prior Orca's coordinates.
+      // Why: source the endpoint file so a surviving PTY reaches the current server, not the prior Orca's coordinates (see claude/hook-service.ts).
       'if defined ORCA_AGENT_HOOK_ENDPOINT if exist "%ORCA_AGENT_HOOK_ENDPOINT%" call "%ORCA_AGENT_HOOK_ENDPOINT%" 2>nul',
       ...buildWindowsHookEnvironmentGuardLines(),
       buildWindowsAgentHookPostCommand('cursor'),
@@ -92,22 +75,15 @@ function getManagedScript(target: 'local' | 'posix' = 'local'): string {
   return [
     '#!/bin/sh',
     ...buildPosixHookPayloadCapture(),
-    // Why: see claude/hook-service.ts for rationale. Sourcing refreshes
-    // PORT/TOKEN/ENV/VERSION from the current Orca so a surviving PTY keeps
-    // reporting after a restart.
+    // Why: sourcing refreshes PORT/TOKEN/ENV from the current Orca so a surviving PTY keeps reporting after a restart (see claude/hook-service.ts).
     'if [ -n "$ORCA_AGENT_HOOK_ENDPOINT" ] && [ -r "$ORCA_AGENT_HOOK_ENDPOINT" ]; then',
     '  . "$ORCA_AGENT_HOOK_ENDPOINT" 2>/dev/null || :',
     'fi',
     'if [ -z "$ORCA_AGENT_HOOK_PORT" ] || [ -z "$ORCA_AGENT_HOOK_TOKEN" ] || [ -z "$ORCA_PANE_KEY" ]; then',
     '  exit 0',
     'fi',
-    // Why: worktreeId embeds a filesystem path, so hand-building JSON in POSIX
-    // shell is not safe once a path contains quotes or newlines. Post the raw
-    // hook payload plus metadata as form fields and let the receiver parse it.
-    // Timeout caps best-effort hook posts if the local listener stalls.
-    // Why: pipe payload to curl's stdin (`payload@-`) instead of an inline
-    // `payload=$VALUE` arg, so tens-of-KB tool output stays off the curl
-    // command line (EDR command-line false positives). Wire body is identical.
+    // Why: worktreeId embeds a path, so hand-building JSON in shell is unsafe (quotes/newlines); post raw payload as form fields instead.
+    // Why: pipe payload via curl stdin (`payload@-`), not an inline arg, so large tool output stays off the command line (EDR false positives).
     'printf \'%s\' "$payload" | curl -sS -X POST "http://127.0.0.1:${ORCA_AGENT_HOOK_PORT}/hook/cursor" \\',
     '  --connect-timeout 0.5 --max-time 1.5 \\',
     '  -H "Content-Type: application/x-www-form-urlencoded" \\',
@@ -144,9 +120,7 @@ export class CursorHookService {
     let presentCount = 0
     for (const eventName of CURSOR_EVENTS) {
       const definitions = Array.isArray(config.hooks?.[eventName]) ? config.hooks![eventName]! : []
-      // Why: Cursor's schema places the command directly on the definition
-      // (not nested under a `hooks` array as Claude does), so match both
-      // shapes to stay robust against future schema changes.
+      // Why: Cursor puts command directly on the definition (Claude nests under `hooks`); match both shapes.
       const hasCommand = definitions.some(
         (definition) =>
           definition.command === command ||
@@ -189,22 +163,14 @@ export class CursorHookService {
     }
 
     const command = getManagedCommand(scriptPath)
-    // Why: Cursor's hooks.json wraps the map under a top-level "hooks" key
-    // (same as Claude/Codex). A fresh file with no prior hook install will
-    // have config.hooks === undefined.
+    // Why: config.hooks is undefined on a fresh file with no prior hook install.
     const nextHooks = { ...config.hooks }
     const managedEvents = new Set<string>(CURSOR_EVENTS)
 
-    // Why: match by script filename (not exact command string) so a fresh
-    // install sweeps stale entries left by older builds or a different
-    // Electron userData path (dev vs. prod). Without this, repeated installs
-    // accumulate duplicate hook entries pointing at defunct scripts.
+    // Why: match by script filename (not exact command) so installs sweep stale entries from older builds or a different userData path.
     const isManagedCommand = createManagedCommandMatcher(getManagedScriptFileName())
 
-    // Why: sweep managed entries out of events we no longer subscribe to
-    // (e.g. a future rename where we drop an event name). Without this,
-    // users who already had that event registered would keep firing stale
-    // hooks after the app upgrade.
+    // Why: sweep managed entries from events we no longer subscribe to, else upgraded users keep firing stale hooks.
     for (const [eventName, definitions] of Object.entries(nextHooks)) {
       if (managedEvents.has(eventName)) {
         continue
@@ -226,24 +192,16 @@ export class CursorHookService {
 
     for (const eventName of CURSOR_EVENTS) {
       const current = Array.isArray(nextHooks[eventName]) ? nextHooks[eventName] : []
-      // Sweep both the Claude-shaped (hooks[].command) and Cursor-shaped
-      // (definition.command) variants so repeated installs converge on a
-      // single managed entry.
+      // Sweep both Claude-shaped (hooks[].command) and Cursor-shaped (definition.command) variants so installs converge on one entry.
       const cleaned = removeManagedCommands(current, isManagedCommand).filter(
         (definition) => !isManagedCommand(definition.command as string | undefined)
       )
-      // Why: Cursor's documented schema puts `command` directly on the
-      // definition (not under `hooks`). Emit that shape so cursor-agent
-      // actually invokes the script.
+      // Why: Cursor's schema puts `command` directly on the definition (not under `hooks`); emit that shape.
       const definition: HookDefinition = buildManagedCommandDefinition(command)
       nextHooks[eventName] = [...cleaned, definition]
     }
 
-    // Why: cursor-agent's config schema requires a top-level `version: 1`
-    // (see https://cursor.com/docs/hooks). Preserve an existing value if the
-    // user has already pinned one, otherwise stamp the default so a fresh
-    // install produces a valid file. HooksConfig has an index signature on
-    // extra keys, so assign via a Record-typed object to satisfy the type.
+    // Why: cursor-agent's schema requires top-level `version: 1` (https://cursor.com/docs/hooks); keep any user-pinned value.
     const nextConfig: Record<string, unknown> = { ...config, hooks: nextHooks }
     if (nextConfig.version === undefined) {
       nextConfig.version = 1
@@ -253,12 +211,7 @@ export class CursorHookService {
     return this.getStatus()
   }
 
-  // Why: install Orca's managed Cursor hooks on the remote box. Mirrors
-  // ClaudeHookService.installRemote — POSIX-only, uses the same SFTP-backed
-  // primitives, and emits Cursor's documented schema (top-level `command`
-  // on each definition + top-level `version: 1`) so cursor-agent on the
-  // remote actually invokes the script. See docs/design/agent-status-over-ssh.md
-  // §8.
+  // Installs managed Cursor hooks on an SSH remote (POSIX-only). See docs/design/agent-status-over-ssh.md §8.
   async installRemote(sftp: SFTPWrapper, remoteHome: string): Promise<AgentHookInstallStatus> {
     const remoteConfigPath = `${remoteHome.replace(/\/$/, '')}/.cursor/hooks.json`
     const remoteScriptPath = `${remoteHome.replace(/\/$/, '')}/.orca/agent-hooks/cursor-hook.sh`
@@ -280,8 +233,7 @@ export class CursorHookService {
 
       for (const eventName of CURSOR_EVENTS) {
         const current = Array.isArray(nextHooks[eventName]) ? nextHooks[eventName] : []
-        // Why: same dual-shape sweep as the local install — repeated
-        // installs converge on a single managed entry.
+        // Why: dual-shape sweep so repeated installs converge on a single managed entry.
         const cleaned = removeManagedCommands(current, isManagedCommand).filter(
           (definition) => !isManagedCommand(definition.command as string | undefined)
         )
@@ -294,11 +246,8 @@ export class CursorHookService {
         nextConfig.version = 1
       }
 
-      // Why: script-then-config order so a partial-failure mid-install at
-      // worst leaves a working script no settings.json points at — see
-      // ClaudeHookService.installRemote.
-      // Why: SSH remotes use POSIX `.sh` hook paths even when Orca itself is
-      // running on Windows; never derive remote script syntax from local OS.
+      // Why: script-then-config order so a partial mid-install leaves a working script nothing points at.
+      // Why: SSH remotes always use POSIX `.sh` hook paths even when Orca runs on Windows; never derive from local OS.
       await writeManagedScriptRemote(sftp, remoteScriptPath, getManagedScript('posix'))
       await writeHooksJsonRemote(sftp, remoteConfigPath, nextConfig)
 
diff --git a/src/main/devin/hook-service.ts b/src/main/devin/hook-service.ts
index 8b4cc439058..82b00a71c3c 100644
--- a/src/main/devin/hook-service.ts
+++ b/src/main/devin/hook-service.ts
@@ -39,12 +39,7 @@ function getManagedScript(target: 'local' | 'posix' = 'local'): string {
     return [
       '@echo off',
       'setlocal',
-      // Why: the endpoint file holds the *live* port/token for this Orca
-      // install. A PTY that survived an Orca restart has stale PORT/TOKEN
-      // baked into its env from the old instance — loading `endpoint.cmd`
-      // (`set KEY=VALUE` lines) via `call` refreshes them so the hook
-      // reaches the current server. Falls through to PTY env if the file
-      // is missing (first run / pre-endpoint-file / running outside Orca).
+      // Why: endpoint file holds the live port/token; a PTY that outlives an Orca restart carries stale env, so `call` it to refresh (else PTY env).
       'if defined ORCA_AGENT_HOOK_ENDPOINT if exist "%ORCA_AGENT_HOOK_ENDPOINT%" call "%ORCA_AGENT_HOOK_ENDPOINT%" 2>nul',
       ...buildWindowsHookEnvironmentGuardLines(),
       buildWindowsAgentHookPostCommand('devin'),
@@ -57,33 +52,16 @@ function getManagedScript(target: 'local' | 'posix' = 'local'): string {
   return [
     '#!/bin/sh',
     ...buildPosixHookPayloadCapture(),
-    // Why: the endpoint file holds the *live* port/token for this Orca
-    // install. PTYs that survive an Orca restart have stale PORT/TOKEN
-    // baked into their env from the old instance — sourcing the file here
-    // lets us reach the new server. Falls back to PTY env if the file is
-    // missing (first-run / pre-endpoint-file scripts / running outside Orca).
-    // Why: suppress stderr on the `.` builtin. A TOCTOU race (endpoint unlinked
-    // between the `[ -r ]` test and the source) or a malformed line (e.g. CRLF
-    // bled in from a cross-platform userData copy) would otherwise print a
-    // parse error that agent transcripts could surface. Stale coords → dead
-    // port → silent-fail is the documented fail-open path anyway — the env-var
-    // guards below handle the empty PORT/TOKEN case — so swallowing the noise
-    // here is strictly better than leaking shell errors into the hook output.
-    // `|| :` defends against an eventual `set -e` in an outer script context
-    // (not present today) aborting the hook on a parse error.
+    // Why: endpoint file holds the live port/token; PTYs that outlive an Orca restart carry stale env, so source it to reach the new server (else PTY env).
+    // Why: silence the `.` builtin (2>/dev/null + `|| :`) so a TOCTOU race or CRLF-mangled line can't leak shell parse errors into agent transcripts (fail-open).
     'if [ -n "$ORCA_AGENT_HOOK_ENDPOINT" ] && [ -r "$ORCA_AGENT_HOOK_ENDPOINT" ]; then',
     '  . "$ORCA_AGENT_HOOK_ENDPOINT" 2>/dev/null || :',
     'fi',
     'if [ -z "$ORCA_AGENT_HOOK_PORT" ] || [ -z "$ORCA_AGENT_HOOK_TOKEN" ] || [ -z "$ORCA_PANE_KEY" ]; then',
     '  exit 0',
     'fi',
-    // Why: worktreeId embeds a filesystem path, so hand-building JSON in POSIX
-    // shell is not safe once a path contains quotes or newlines. Post the raw
-    // hook payload plus metadata as form fields and let the receiver parse it.
-    // Timeout caps best-effort hook posts if the local listener stalls.
-    // Why: pipe payload to curl's stdin (`payload@-`) instead of an inline
-    // `payload=$VALUE` arg, so tens-of-KB tool output stays off the curl
-    // command line (EDR command-line false positives). Wire body is identical.
+    // Why: worktreeId embeds a filesystem path, so hand-building JSON in shell is unsafe (quotes/newlines); post as form fields instead.
+    // Why: pipe payload to curl's stdin (payload@-) not an inline arg, so large tool output stays off the command line (EDR false positives).
     'printf \'%s\' "$payload" | curl -sS -X POST "http://127.0.0.1:${ORCA_AGENT_HOOK_PORT}/hook/devin" \\',
     '  --connect-timeout 0.5 --max-time 1.5 \\',
     '  -H "Content-Type: application/x-www-form-urlencoded" \\',
@@ -115,10 +93,7 @@ export class DevinHookService {
       }
     }
 
-    // Why: Report `partial` when only some managed events are registered so the
-    // sidebar surfaces a degraded install rather than a false-positive
-    // `installed`. Each DEVIN_EVENTS entry must contain the managed command for
-    // the integration to function end-to-end.
+    // Why: report `partial` when only some managed events are registered, so the sidebar shows a degraded install instead of a false `installed`.
     const command = getDevinManagedCommand(scriptPath)
     const missing: string[] = []
     let presentCount = 0
@@ -178,28 +153,15 @@ export class DevinHookService {
     return this.getStatus()
   }
 
-  // Why: install Orca's Devin hook settings on the remote box rather than the
-  // local machine. Caller passes the user's SFTP handle plus the resolved
-  // remote `$HOME`; POSIX-only by design (Windows-remote deferred).
+  // Why: install the Devin hook on the remote box (SFTP handle + resolved remote $HOME); POSIX-only by design.
   async installRemote(sftp: SFTPWrapper, remoteHome: string): Promise<AgentHookInstallStatus> {
-    // Why: remote-Windows is out of scope for v1 — we ship POSIX-shaped paths
-    // and a `.sh` managed script body. The remote platform is gated by the
-    // relay's capability RPC at a higher layer; we cannot detect it from
-    // `process.platform` here (that's the local box).
+    // Why: remote-Windows is out of scope for v1; process.platform here is the local box, not the remote, so assume POSIX.
     const remoteConfigPath = getDevinRemoteConfigPath(remoteHome)
     const remoteScriptFileName = getDevinPosixManagedScriptFileName()
     const remoteScriptPath = `${remoteHome.replace(/\/$/, '')}/.orca/agent-hooks/${remoteScriptFileName}`
-    // Why: SFTP reads/writes fail far more often than local fs (network drops,
-    // EACCES on remote dirs, disk full, channel closed). Wrap the entire
-    // install flow in try/catch so a transient I/O failure surfaces as a
-    // structured `state: 'error'` result for the UI, not an unstructured
-    // rejection the caller has to remember to handle. A `null` config
-    // specifically means "file present but unparseable" — keep that branch
-    // distinct so the user sees an actionable message.
+    // Why: SFTP I/O fails far more often than local fs; wrap the flow so failures surface as a structured error, not an unhandled rejection.
     try {
-      // Why: Devin config.json is JSONC (comments); stock
-      // JSON.parse rejects them. Read the raw text via SFTP and parse with
-      // jsonc-parser, mirroring the local readDevinHooksConfig path.
+      // Why: Devin config.json is JSONC (comments), so JSON.parse rejects it; parse via jsonc-parser.
       const body = await readTextFileRemote(sftp, remoteConfigPath)
       const config =
         body === null ? {} : parseDevinHooksConfigText(body, 'remote Devin config.json')
@@ -213,19 +175,12 @@ export class DevinHookService {
         }
       }
 
-      // Why: the POSIX wrapper is identical regardless of where the script
-      // lands; only the path differs. Reuse the same wrapper helper.
+      // Why: the POSIX wrapper body is path-independent, so reuse the same helper.
       const command = getDevinRemoteManagedCommand(remoteScriptPath)
       const nextConfig = applyDevinManagedHooks(config, command, remoteScriptFileName)
 
-      // Why: write the script first, then the settings — settings.json
-      // referencing a missing script body would fire `command not found` on
-      // every tool call until the user re-runs install. Doing it in this
-      // order means a partial-failure mid-install at worst leaves the user
-      // with a working script no settings.json points at (a no-op), instead
-      // of broken settings.json.
-      // Why: SSH remotes use POSIX `.sh` hook paths even when Orca itself is
-      // running on Windows; never derive remote script syntax from local OS.
+      // Why: write script before settings so a mid-install failure never leaves settings.json referencing a missing script.
+      // Why: SSH remotes use POSIX `.sh` hooks even when Orca runs on Windows; never derive remote script syntax from local OS.
       await writeManagedScriptRemote(sftp, remoteScriptPath, getManagedScript('posix'))
       await writeHooksJsonRemote(sftp, remoteConfigPath, nextConfig)
 
diff --git a/src/main/gemini/hook-service.ts b/src/main/gemini/hook-service.ts
index e078476edce..1615ea336f9 100644
--- a/src/main/gemini/hook-service.ts
+++ b/src/main/gemini/hook-service.ts
@@ -27,15 +27,8 @@ import {
   buildWindowsHookStdinDrainEpilogue
 } from '../agent-hooks/hook-stdin-contract'
 
-// Why: Gemini CLI fires `BeforeAgent` when a turn starts and `AfterAgent` when
-// it completes. `AfterTool` marks the resumption of model work after a tool
-// call, which maps back to `working`. Gemini has no permission-prompt hook
-// (approvals flow through inline UI), so Orca cannot surface a waiting state
-// for Gemini — that is an upstream limitation, not an Orca bug.
-//
-// Gemini's native pre-tool event is BeforeTool, not Claude/Codex's PreToolUse.
-// Keep installing the pre-tool status hook, but sweep stale PreToolUse entries
-// below so current Gemini CLI no longer warns about an invalid event bucket.
+// Why: Gemini has no permission-prompt hook (approvals are inline UI), so Orca can't show a waiting state — upstream limitation.
+// Why: Gemini's pre-tool event is BeforeTool, not Claude/Codex's PreToolUse; sweep stale PreToolUse entries below.
 const GEMINI_EVENTS = ['BeforeAgent', 'AfterAgent', 'AfterTool', 'BeforeTool'] as const
 
 function getConfigPath(): string {
@@ -61,14 +54,9 @@ function getManagedScript(target: 'local' | 'posix' = 'local'): string {
     return [
       '@echo off',
       'setlocal',
-      // Why: Gemini expects valid JSON on stdout even when the hook has nothing
-      // to return. Emit `{}` first so the agent never stalls parsing our
-      // output, even if the env-var guards below cause an early exit.
+      // Why: emit `{}` first so Gemini never stalls parsing stdout, even if the guards below exit early.
       'echo {}',
-      // Why: see claude/hook-service.ts for rationale. The endpoint file holds
-      // the live port/token for this Orca install; sourcing it here lets a
-      // surviving PTY reach the current server even though its env points at
-      // the prior Orca's coordinates.
+      // Why: source the endpoint file so a surviving PTY reaches the current server. See claude/hook-service.ts.
       'if defined ORCA_AGENT_HOOK_ENDPOINT if exist "%ORCA_AGENT_HOOK_ENDPOINT%" call "%ORCA_AGENT_HOOK_ENDPOINT%" 2>nul',
       ...buildWindowsHookEnvironmentGuardLines(),
       buildWindowsAgentHookPostCommand('gemini'),
@@ -80,27 +68,18 @@ function getManagedScript(target: 'local' | 'posix' = 'local'): string {
 
   return [
     '#!/bin/sh',
-    // Why: Gemini expects valid JSON on stdout even when the hook has nothing
-    // to return. Emit `{}` first so the agent never stalls parsing our output,
-    // even if the env-var guards below cause an early exit.
+    // Why: emit `{}` first so Gemini never stalls parsing stdout, even if the guards below exit early.
     'printf "{}\\n"',
     ...buildPosixHookPayloadCapture(),
-    // Why: see claude/hook-service.ts for rationale. Sourcing refreshes
-    // PORT/TOKEN/ENV/VERSION from the current Orca so a surviving PTY keeps
-    // reporting after a restart.
+    // Why: source refreshes endpoint coords so a PTY surviving an Orca restart keeps reporting. See claude/hook-service.ts.
     'if [ -n "$ORCA_AGENT_HOOK_ENDPOINT" ] && [ -r "$ORCA_AGENT_HOOK_ENDPOINT" ]; then',
     '  . "$ORCA_AGENT_HOOK_ENDPOINT" 2>/dev/null || :',
     'fi',
     'if [ -z "$ORCA_AGENT_HOOK_PORT" ] || [ -z "$ORCA_AGENT_HOOK_TOKEN" ] || [ -z "$ORCA_PANE_KEY" ]; then',
     '  exit 0',
     'fi',
-    // Why: worktreeId embeds a filesystem path, so hand-building JSON in POSIX
-    // shell is not safe once a path contains quotes or newlines. Post the raw
-    // hook payload plus metadata as form fields and let the receiver parse it.
-    // Timeout caps best-effort hook posts if the local listener stalls.
-    // Why: pipe payload to curl's stdin (`payload@-`) instead of an inline
-    // `payload=$VALUE` arg, so tens-of-KB tool output stays off the curl
-    // command line (EDR command-line false positives). Wire body is identical.
+    // Why: worktreeId embeds a path, so post form fields, not hand-built JSON that breaks on quotes/newlines.
+    // Why: pipe payload via curl stdin (`payload@-`) so large tool output stays off the command line (EDR false positives).
     'printf \'%s\' "$payload" | curl -sS -X POST "http://127.0.0.1:${ORCA_AGENT_HOOK_PORT}/hook/gemini" \\',
     '  --connect-timeout 0.5 --max-time 1.5 \\',
     '  -H "Content-Type: application/x-www-form-urlencoded" \\',
@@ -179,18 +158,12 @@ export class GeminiHookService {
     const command = getManagedCommand(scriptPath)
     const nextHooks = { ...config.hooks }
 
-    // Why: match by script filename (not exact command string) so a fresh
-    // install sweeps stale entries left by older builds or a different
-    // Electron userData path (dev vs. prod). Without this, repeated installs
-    // accumulate duplicate hook entries pointing at defunct scripts.
+    // Why: match by filename not exact command, so installs sweep stale entries instead of duplicating them.
     const isManagedCommand = createManagedCommandMatcher(getManagedScriptFileName())
 
     const managedEvents = new Set<string>(GEMINI_EVENTS)
 
-    // Why: when Orca stops subscribing to an event, install() must sweep the
-    // old managed entry out of any leftover event bucket. Otherwise a stale
-    // hook such as PreToolUse survives forever in ~/.gemini/settings.json and
-    // continues firing even though the current build no longer wants it.
+    // Why: sweep managed entries from dropped event buckets so stale hooks (e.g. PreToolUse) don't keep firing.
     for (const [eventName, definitions] of Object.entries(nextHooks)) {
       if (managedEvents.has(eventName)) {
         continue
@@ -222,11 +195,7 @@ export class GeminiHookService {
     return this.getStatus()
   }
 
-  // Why: install Orca's managed Gemini hooks on the remote box. Mirrors
-  // ClaudeHookService.installRemote — POSIX-only, uses the same SFTP-backed
-  // primitives, and lays down the same script body the local install
-  // generates so a remote-side Gemini CLI behaves identically. See
-  // docs/design/agent-status-over-ssh.md §8.
+  // POSIX-only remote install mirroring ClaudeHookService.installRemote. See docs/design/agent-status-over-ssh.md §8.
   async installRemote(sftp: SFTPWrapper, remoteHome: string): Promise<AgentHookInstallStatus> {
     const remoteConfigPath = `${remoteHome.replace(/\/$/, '')}/.gemini/settings.json`
     const remoteScriptPath = `${remoteHome.replace(/\/$/, '')}/.orca/agent-hooks/gemini-hook.sh`
@@ -247,8 +216,7 @@ export class GeminiHookService {
       const isManagedCommand = createManagedCommandMatcher('gemini-hook.sh')
       const managedEvents = new Set<string>(GEMINI_EVENTS)
 
-      // Why: remote installs must sweep legacy managed event buckets too.
-      // Otherwise stale PreToolUse entries keep warning in SSH Gemini sessions.
+      // Why: sweep legacy managed event buckets so stale PreToolUse stops warning in SSH Gemini sessions.
       for (const [eventName, definitions] of Object.entries(nextHooks)) {
         if (managedEvents.has(eventName)) {
           continue
@@ -275,10 +243,8 @@ export class GeminiHookService {
       }
       config.hooks = nextHooks
 
-      // Why: write the script first so an interrupted install never leaves
-      // settings.json pointing at a missing script. See ClaudeHookService.
-      // Why: SSH remotes use POSIX `.sh` hook paths even when Orca itself is
-      // running on Windows; never derive remote script syntax from local OS.
+      // Why: write the script before settings.json so an interrupted install never points at a missing script.
+      // Why: SSH remotes always use POSIX `.sh` paths even when Orca runs on Windows.
       await writeManagedScriptRemote(sftp, remoteScriptPath, getManagedScript('posix'))
       await writeHooksJsonRemote(sftp, remoteConfigPath, config)
 
@@ -314,14 +280,10 @@ export class GeminiHookService {
     }
 
     const nextHooks = { ...config.hooks }
-    // Why: same broad matcher as install(), so remove() also cleans up stale
-    // entries from older builds even if the current scriptPath has moved.
+    // Why: match by filename so remove() sweeps stale entries even after the script path moved.
     const isManagedCommand = createManagedCommandMatcher(getManagedScriptFileName())
     for (const [eventName, definitions] of Object.entries(nextHooks)) {
-      // Why: a malformed settings.json entry (non-array value for an event
-      // name) would make removeManagedCommands throw via definitions.flatMap.
-      // Skip — remove() must fail open so a broken user config never blocks
-      // uninstall.
+      // Why: fail open on malformed (non-array) entries so a broken user config never blocks uninstall.
       if (!Array.isArray(definitions)) {
         continue
       }
diff --git a/src/main/git/repo.test.ts b/src/main/git/repo.test.ts
index d4abbd2501e..90199d1c69b 100644
--- a/src/main/git/repo.test.ts
+++ b/src/main/git/repo.test.ts
@@ -15,9 +15,7 @@ import {
   searchBaseRefs
 } from './repo'
 
-// Why: these tests exercise real git state (not mocked gitExecFileAsync)
-// because the change under test is in the `for-each-ref` glob argument
-// shape — the exact kind of bug a mock-based test would miss.
+// Why: use real git state (not mocked) because the bug is in the for-each-ref glob shape a mock would miss.
 
 function git(cwd: string, args: string[]): string {
   return execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] })
@@ -25,21 +23,14 @@ function git(cwd: string, args: string[]): string {
 
 function initRepo(dir: string): void {
   git(dir, ['init', '--quiet'])
-  // Why: explicit symbolic-ref rather than `git init --initial-branch=main`
-  // (which requires git >= 2.28). Setting HEAD before the first commit
-  // makes the initial branch `main` regardless of host git version or
-  // `init.defaultBranch` config.
+  // Why: `--initial-branch=main` needs git >= 2.28; symbolic-ref before the first commit forces `main` on any git version.
   git(dir, ['symbolic-ref', 'HEAD', 'refs/heads/main'])
   git(dir, ['config', 'user.email', 'test@test.com'])
   git(dir, ['config', 'user.name', 'Test'])
   git(dir, ['commit', '--allow-empty', '-m', 'initial', '--quiet'])
 }
 
-/**
- * Create a remote-tracking ref in `mainDir` at the given short-name
- * (e.g. `origin/main`) by creating a packed ref under refs/remotes.
- * Uses `update-ref` so we don't need to actually configure a live remote.
- */
+/** Create a remote-tracking ref via `update-ref`, avoiding a live remote. */
 function createRemoteRef(mainDir: string, shortName: string, sha: string): void {
   git(mainDir, ['update-ref', `refs/remotes/${shortName}`, sha])
 }
@@ -137,7 +128,6 @@ describe('searchBaseRefs (widened glob)', () => {
     const sha = getHeadSha(tmpDir)
     createRemoteRef(tmpDir, 'origin/main', sha)
     createRemoteRef(tmpDir, 'upstream/main', sha)
-    // symbolic-ref creates the HEAD pseudo-ref
     git(tmpDir, ['symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/main'])
     git(tmpDir, ['symbolic-ref', 'refs/remotes/upstream/HEAD', 'refs/remotes/upstream/main'])
 
@@ -164,9 +154,7 @@ describe('searchBaseRefs (widened glob)', () => {
     expect(results).toContain('local-only')
   })
 
-  // Why: a single-word query must match a term in ANY segment of a slashed
-  // branch name (`user/feature`), not just the leaf. fnmatch `*` does not
-  // cross `/`, so the glob must use `**` to span ref segments.
+  // Why: fnmatch `*` doesn't cross `/`, so a single-word query needs `**` to match any segment of a slashed name.
   it('finds a local slashed branch when the query lands in a deep segment', async () => {
     git(tmpDir, ['branch', 'feature/login'])
 
@@ -311,10 +299,7 @@ describe('searchBaseRefs (widened glob)', () => {
     await expect(searchBaseRefs(tmpDir, '', Number.NaN)).resolves.toEqual([])
   })
 
-  // Why: the picker displays results as `<remote>/<branch>` and labels
-  // `origin/main` as "Current", so users naturally retype the displayed
-  // format. Before segment-wise globbing this returned [] because the
-  // slash in the query made every fnmatch pattern unable to match.
+  // Why: users retype the displayed `<remote>/<branch>` format, so a slashed query must still match.
   it('finds the ref when the query is in display format `<remote>/<branch>`', async () => {
     const sha = getHeadSha(tmpDir)
     createRemoteRef(tmpDir, 'upstream/main', sha)
@@ -334,8 +319,7 @@ describe('searchBaseRefs (widened glob)', () => {
 
     expect(results).toContain('upstream/feature-x')
     expect(results).toContain('upstream/feature-y')
-    // Why: `upstream/feat` pins the remote segment to *upstream*, so
-    // origin/feature-x must not leak in.
+    // Why: `upstream/feat` pins the remote segment to *upstream*, so origin/feature-x must not leak in.
     expect(results).not.toContain('origin/feature-x')
   })
 
@@ -343,10 +327,7 @@ describe('searchBaseRefs (widened glob)', () => {
     const sha = getHeadSha(tmpDir)
     createRemoteRef(tmpDir, 'upstream/main', sha)
 
-    // Why: `main/upstream` means "remote matching *main*, branch matching
-    // *upstream*". upstream/main has remote=upstream (no `main`) and
-    // branch=main (no `upstream`), so it must NOT match — confirms each
-    // token is pinned to its own segment, not treated as a free substring.
+    // Why: each token is pinned to its own segment (remote vs branch), so `main/upstream` must not match `upstream/main`.
     const results = await searchBaseRefs(tmpDir, 'main/upstream')
 
     expect(results).not.toContain('upstream/main')
@@ -357,10 +338,7 @@ describe('searchBaseRefs (widened glob)', () => {
     createRemoteRef(tmpDir, 'upstream/main', sha)
     git(tmpDir, ['symbolic-ref', 'refs/remotes/upstream/HEAD', 'refs/remotes/upstream/main'])
 
-    // Why: typing `upstream/HEAD` must not surface the pseudo-ref even
-    // though it's a valid display-format query — the HEAD filter runs
-    // after the glob match, so coverage of the filter must survive
-    // changes to the glob shape.
+    // Why: the HEAD filter runs after the glob match, so display-format queries must still drop the pseudo-ref.
     const results = await searchBaseRefs(tmpDir, 'upstream/HEAD')
 
     expect(results).not.toContain('upstream/HEAD')
@@ -370,10 +348,7 @@ describe('searchBaseRefs (widened glob)', () => {
     const sha = getHeadSha(tmpDir)
     createRemoteRef(tmpDir, 'upstream/main', sha)
 
-    // Why: empty tokens from trailing/leading/doubled slashes would
-    // degrade to `**` segments with fnmatch, matching nothing useful
-    // and silently breaking the feature. Filtering empty tokens keeps
-    // the query behavior identical to the intended non-empty tokens.
+    // Why: empty tokens from stray slashes would degrade to `**` and match nothing, so they're filtered out.
     expect(await searchBaseRefs(tmpDir, 'upstream/')).toContain('upstream/main')
     expect(await searchBaseRefs(tmpDir, '/upstream')).toContain('upstream/main')
     expect(await searchBaseRefs(tmpDir, 'upstream//main')).toContain('upstream/main')
@@ -515,15 +490,13 @@ describe('getDefaultBaseRef (regression — unchanged behavior)', () => {
   })
 
   it('does NOT fall through to upstream/main when origin/* is absent', () => {
-    // Why: this is the explicit design decision — the default probe order
-    // is origin-only. upstream-aware defaulting is deferred work.
+    // Why: default probe order is origin-only by design; upstream-aware defaulting is deferred.
     const sha = getHeadSha(tmpDir)
     createRemoteRef(tmpDir, 'upstream/main', sha)
 
     const result = getDefaultBaseRef(tmpDir)
 
-    // With no origin/* but a local main branch (initRepo creates one),
-    // we expect the local `main` — NOT `upstream/main`.
+    // initRepo creates a local `main`, so with no origin/* we expect it — not `upstream/main`.
     expect(result).toBe('main')
     expect(result).not.toBe('upstream/main')
   })
diff --git a/src/main/git/repo.ts b/src/main/git/repo.ts
index fa1c23ebf0d..df5b2865132 100644
--- a/src/main/git/repo.ts
+++ b/src/main/git/repo.ts
@@ -33,14 +33,9 @@ function gitExecOptions(
 }
 
 /**
- * Ordered probe list used to resolve a repo's default base ref when no
- * explicit origin/HEAD symbolic-ref is set. `returnAs` is the short-name
- * format the UI expects (matches how `git for-each-ref --format=%(refname:short)`
- * would render the ref).
- *
- * Why: shared between the local path (getDefaultBaseRefAsync) and the SSH
- * relay path in src/main/ipc/repos.ts so both resolve identical defaults
- * for equivalent repo states.
+ * Ordered probe list for a repo's default base ref when no origin/HEAD symbolic-ref is set.
+ * `returnAs` is the short-name format the UI expects (as `for-each-ref --format=%(refname:short)` renders it).
+ * Shared local/SSH so both resolve identical defaults.
  */
 export const DEFAULT_BASE_REF_PROBES: readonly { ref: string; returnAs: string }[] = [
   { ref: 'refs/remotes/origin/main', returnAs: 'origin/main' },
@@ -50,12 +45,8 @@ export const DEFAULT_BASE_REF_PROBES: readonly { ref: string; returnAs: string }
 ]
 
 /**
- * Walk DEFAULT_BASE_REF_PROBES in order, returning the first ref whose
- * existence is confirmed by `hasRef`. Returns null if none exist.
- *
- * Why: abstracts the "how do we test a ref exists" detail so the local
- * path (hasGitRefAsync) and the SSH path (provider.exec rev-parse) can
- * share a single authoritative probe ordering.
+ * Walk DEFAULT_BASE_REF_PROBES in order, returning the first ref `hasRef` confirms, or null.
+ * Abstracts the existence test so local and SSH paths share one authoritative probe ordering.
  */
 async function resolveDefaultBaseRefFromProbes(
   hasRef: (ref: string) => Promise<boolean>
@@ -68,9 +59,7 @@ async function resolveDefaultBaseRefFromProbes(
   return null
 }
 
-/**
- * Check if a path is a valid git repository (regular or bare).
- */
+/** Check if a path is a valid git repository (regular or bare). */
 export function isGitRepo(path: string): boolean {
   try {
     if (!existsSync(path) || !statSync(path).isDirectory()) {
@@ -80,8 +69,7 @@ export function isGitRepo(path: string): boolean {
     return false
   }
 
-  // Authoritative positive signal: ask git directly. Covers regular work
-  // trees, linked worktrees (gitfile), submodules, and bare repos.
+  // Ask git directly first — authoritative for work trees, linked worktrees, submodules, and bare repos.
   const gitProbeResult = probeGitRepo(path)
   if (gitProbeResult === 'repo') {
     return true
@@ -90,20 +78,11 @@ export function isGitRepo(path: string): boolean {
     return false
   }
 
-  // Why: `git rev-parse` can fail to produce a clean answer for reasons
-  // unrelated to repo-ness — a transient spawn failure or git-shim hiccup in
-  // the packaged app, resource pressure in the Electron main process, or a
-  // repo whose config errors out. Treating every such failure as "not a repo"
-  // silently downgrades a real repository to a plain folder (worktrees, SCM,
-  // PRs all disappear) and is the regression behind the spurious "Open as
-  // Folder" prompt. Fall back to a validated `.git` marker so a directory that
-  // genuinely carries Git metadata is still recognized; a directory with only
-  // a garbage `.git` file has no valid marker and is correctly rejected.
+  // Why: rev-parse can fail for reasons unrelated to repo-ness (spawn hiccup, config error); fall back to a
+  // validated `.git` marker instead of downgrading a real repo to a plain folder (the spurious "Open as Folder" bug).
   const markerScan = scanGitMarkerSync(path)
   if (markerScan.status === 'valid' && !warnedMarkerFallbackThisSession) {
-    // Why: warn only once per session. The folder scanner calls isGitRepo for
-    // many paths; if git is genuinely unavailable, warning per path would flood
-    // the main-process logs without adding signal beyond the first occurrence.
+    // Why: warn once per session; the folder scanner calls isGitRepo for many paths and would otherwise flood logs.
     warnedMarkerFallbackThisSession = true
     console.warn('[isGitRepo] git rev-parse could not confirm repo; accepted via .git marker', {
       path
@@ -179,23 +158,16 @@ export function getGitRepoRoot(path: string): string {
 export function normalizeGitRepoRootForInputPath(inputPath: string, rootPath: string): string {
   const inputWsl = parseWslUncPath(inputPath)
   if (inputWsl && rootPath.startsWith('/')) {
-    // Why: WSL git reports Linux-native roots; Orca must persist the UNC path so
-    // later local git calls keep routing through the WSL-aware runner.
+    // Why: WSL git reports Linux-native roots; persist the UNC path so later git calls keep routing through the WSL runner.
     return toWindowsWslPath(rootPath, inputWsl.distro)
   }
   return normalizeRuntimePathSeparators(rootPath)
 }
 
 /**
- * Filesystem-only check for genuine Git metadata, used as a fallback when git
- * cannot give a clean answer. Strict enough to reject a directory whose `.git`
- * is a garbage file (preserving the validation added in 18ed7b27d):
- * - `.git` directory: accepted only if it has real common or linked-worktree
- *   gitdir shape, so empty/incomplete `.git/` folders are rejected.
- * - `.git` file: accepted only if its `gitdir:` target resolves to valid Git
- *   metadata, covering linked worktrees and submodules.
- * - bare repo root: accepted when HEAD + objects/ + refs/ are present and the
- *   config does not mark it as a regular worktree admin dir.
+ * Filesystem-only fallback check for genuine Git metadata when git can't answer cleanly. Strict enough to
+ * reject a garbage `.git` file (validation from 18ed7b27d): accepts a `.git` dir/file with real gitdir shape
+ * or a bare-repo root (HEAD + objects/ + refs/, not a worktree admin dir).
  */
 function scanGitMarkerSync(path: string): GitMarkerScanResult {
   const realPath = resolveRealPathSync(path)
@@ -207,8 +179,7 @@ function scanGitMarkerSync(path: string): GitMarkerScanResult {
       realPathScan.status === 'valid' &&
       pathsReferToSameEntry(lexicalScan.rootPath, realPathScan.rootPath)
     ) {
-      // Why: preserve lexical spellings such as /var vs /private/var, but let a
-      // symlink from one repo into another bind to the real target repo like git.
+      // Why: preserve lexical spellings (/var vs /private/var), but let a cross-repo symlink bind to the real target like git.
       return lexicalScan
     }
     return realPathScan
@@ -439,18 +410,14 @@ function isGitBooleanFalse(value: string): boolean {
   return ['', 'false', 'no', 'off', '0'].includes(value.toLowerCase())
 }
 
-/**
- * Get a human-readable name for the repo from its path.
- */
+/** Get a human-readable name for the repo from its path. */
 export function getRepoName(path: string): string {
   const name = basename(path)
   // Strip .git suffix from bare repos
   return name.endsWith('.git') ? name.slice(0, -4) : name
 }
 
-/**
- * Get the remote origin URL, or null if not set.
- */
+/** Get the remote origin URL, or null if not set. */
 export function getRemoteUrl(path: string): string | null {
   try {
     return getRemoteUrlByName(path, 'origin')
@@ -486,8 +453,7 @@ function getVerifiedOriginHeadBaseRef(path: string): string | null {
       cwd: path
     }).trim()
 
-    // Why: origin/HEAD may survive a default-branch rename while pointing at a
-    // deleted ref; verify before trusting it over the probe list.
+    // Why: origin/HEAD may survive a default-branch rename pointing at a deleted ref; verify before trusting it.
     return ref && hasGitRef(path, ref) ? gitRefToDefaultBaseRef(ref) : null
   } catch {
     return null
@@ -495,14 +461,8 @@ function getVerifiedOriginHeadBaseRef(path: string): string | null {
 }
 
 /**
- * Resolve the default base ref for new worktrees.
- * Prefer the remote primary branch over a potentially stale local branch.
- *
- * Why: returns `null` when no candidate ref is resolvable. Previously this
- * fell through to a hardcoded `'origin/main'` even when that ref did not
- * exist, which silently handed `git worktree add` a bad ref and produced
- * an opaque git error. Callers now fail loudly with a useful message, or
- * degrade gracefully for non-creation uses (e.g. hosted URL building).
+ * Resolve the default base ref for new worktrees, preferring the remote primary over a stale local branch.
+ * Returns null when nothing resolves (rather than a hardcoded `origin/main`) so callers fail loudly or degrade.
  */
 export function getDefaultBaseRef(path: string): string | null {
   const originHeadBaseRef = getVerifiedOriginHeadBaseRef(path)
@@ -510,8 +470,7 @@ export function getDefaultBaseRef(path: string): string | null {
     return originHeadBaseRef
   }
 
-  // Why: walk the shared DEFAULT_BASE_REF_PROBES list so the sync path and the
-  // async/SSH paths cannot drift on which refs are tried or in what order.
+  // Why: walk the shared DEFAULT_BASE_REF_PROBES so sync and async/SSH paths can't drift on ref order.
   for (const { ref, returnAs } of DEFAULT_BASE_REF_PROBES) {
     if (hasGitRef(path, ref)) {
       return returnAs
@@ -528,14 +487,8 @@ export async function getBaseRefDefault(
 }
 
 /**
- * Return { ahead, behind } for localRef vs remoteRef, or null on git failure.
- *
- * Why: `rev-list --left-right --count A...B` emits `<ahead>\t<behind>` —
- * ahead = commits on A not reachable from B; behind = commits on B not
- * reachable from A. This is the merge-base-symmetric delta used by the
- * stale-base dispatch guard (§3.1). Returning null on any failure (bad
- * ref, corrupt repo, non-numeric output) lets callers degrade gracefully
- * instead of failing dispatch on a probe error.
+ * Return { ahead, behind } (merge-base-symmetric delta) for localRef vs remoteRef, or null on failure.
+ * ahead = commits on localRef not in remoteRef; behind = the reverse. Used by the stale-base dispatch guard (§3.1).
  */
 export function getRemoteDrift(
   repoPath: string,
@@ -559,12 +512,8 @@ export function getRemoteDrift(
 }
 
 /**
- * Up to `limit` commit subjects present on remoteRef but not localRef, in
- * recency order. Returns [] on git failure.
- *
- * Why: powers the preamble drift section (§3.2) so a worker dispatched
- * against an acknowledged-stale base can see at a glance whether the
- * drift touches their task area.
+ * Up to `limit` commit subjects on remoteRef but not localRef, recency order; [] on git failure.
+ * Powers the preamble drift section (§3.2) so a worker sees whether stale-base drift touches its area.
  */
 export function getRecentDriftSubjects(
   repoPath: string,
@@ -584,29 +533,18 @@ export function getRecentDriftSubjects(
   }
 }
 
-/**
- * Parse `git remote` stdout into a count of configured remotes.
- *
- * Why: shared between the local path and the SSH relay path so the
- * count semantics cannot drift.
- */
+/** Parse `git remote` stdout into a remote count. Shared local/SSH so count semantics can't drift. */
 export function parseRemoteCount(stdout: string): number {
   return stdout.split('\n').filter((line) => line.trim().length > 0).length
 }
 
-/**
- * Count the repo's configured remotes by shelling out `git remote`.
- * Returns 0 on error — callers use 0 as "unknown / do not render the
- * multi-remote hint", preserving today's no-hint behavior on failure.
- */
+/** Count configured remotes via `git remote`; returns 0 on error (callers read 0 as "unknown / no hint"). */
 export async function getRemoteCount(path: string): Promise<number> {
   try {
     const { stdout } = await gitExecFileAsync(['remote'], { cwd: path })
     return parseRemoteCount(stdout)
   } catch (err) {
-    // Why: surface the failure for diagnostics; callers treat 0 as "unknown /
-    // do not render the multi-remote hint", but silently swallowing the error
-    // makes a missing hint impossible to debug.
+    // Why: log so a missing multi-remote hint is debuggable; callers still treat 0 as "unknown".
     console.warn('[getRemoteCount] git remote failed', { path, err })
     return 0
   }
@@ -638,17 +576,10 @@ async function resolveVerifiedOriginHeadBaseRefViaExec(exec: GitExec): Promise<s
 }
 
 /**
- * Resolve the default base ref given a git exec callback. Prefers
- * origin/HEAD's symbolic-ref target; falls back to DEFAULT_BASE_REF_PROBES.
+ * Resolve the default base ref via a git exec callback: prefer origin/HEAD's symbolic-ref target,
+ * else fall back to DEFAULT_BASE_REF_PROBES. Shared local/SSH so both transports agree.
  *
- * Why: shared between the local path (via gitExecFileAsync) and the SSH
- * relay path (via provider.exec) so both paths return identical results
- * for equivalent repo states. Accepting an exec callback avoids coupling
- * this helper to either transport. Callers that want transport-level
- * diagnostics should log inside their own exec callback before rethrowing —
- * this helper swallows symbolic-ref's catch because a non-zero exit is the
- * expected signal for "origin/HEAD is unset" and not distinguishable here
- * from a genuine transport failure.
+ * Why swallow symbolic-ref's error: a non-zero exit is the expected "origin/HEAD unset" signal, not a failure.
  */
 export async function resolveDefaultBaseRefViaExec(exec: GitExec): Promise<string | null> {
   const originHeadBaseRef = await resolveVerifiedOriginHeadBaseRefViaExec(exec)
@@ -678,30 +609,10 @@ async function getDefaultBaseRefAsync(
 }
 
 /**
- * Build the argv for `git for-each-ref` used by ref search, given an
- * already-normalized query string.
+ * Build the argv for `git for-each-ref` used by ref search, given an already-normalized query.
  *
- * Why: glob `refs/remotes/*\/*` (not `refs/remotes/origin/*`) so fork
- * workflows can discover branches from any configured remote (e.g.
- * `upstream/main`). The picker would otherwise structurally deny the
- * correct answer for fork contributors — see docs/upstream-base-ref-design.md.
- *
- * Why paired leaf/ancestor globs for a single-segment query: `git for-each-ref`
- * uses fnmatch-style globs where `*` does NOT cross `/`. Slash-named branch
- * refs need an ancestor-segment glob for `user` in `user/feature`, a leaf glob
- * for `feature`, and the same remote-side shape so typing a remote name like
- * `upstream` keeps working.
- *
- * Why the multi-segment branch: the picker displays results as
- * `upstream/main`, so users naturally retype that format. With a single
- * glob, `upstream/main` becomes `refs/remotes/*upstream/main*\/*` — five
- * path segments, zero matches. Splitting on `/` and emitting one
- * `*<token>*` per ref segment maps directly to git's ref structure
- * (`refs/remotes/<remote>/<branch>`, `refs/heads/<branch>`) and makes
- * display-format queries actually find the ref on screen.
- *
- * Why shared: the local path and the SSH relay path must send the exact
- * same argv so results cannot diverge between transports.
+ * Why: glob every remote (`refs/remotes/*\/*`), not just origin, so fork workflows can find branches like
+ * `upstream/main` — see docs/upstream-base-ref-design.md. Shared with the SSH relay path so argv can't diverge.
  */
 const REF_SEARCH_CANDIDATE_MULTIPLIER = 4
 const REF_SEARCH_LEGACY_HEADROOM = 100
@@ -737,30 +648,18 @@ export function buildSearchBaseRefsArgv(
     '--sort=-committerdate',
     ...(excludeRemoteHead
       ? [
-          // Why: exclude remote HEAD pseudo-refs before --count so the bounded
-          // candidate window is spent on refs the picker can actually display.
+          // Why: exclude remote HEAD pseudo-refs before --count so the candidate window holds displayable refs.
           '--exclude=refs/remotes/**/HEAD'
         ]
       : []),
-    // Why: empty Branch-tab searches use broad globs; cap git output before
-    // execFile/SSH buffers capture every ref in very large repositories.
+    // Why: cap git output so broad globs don't overflow execFile/SSH buffers in very large repos.
     `--count=${candidateCount}`
   ]
-  // Why: split on `/` so display-format queries (`upstream/main`) route
-  // each token to one git ref segment. Filter empty tokens so trailing
-  // (`upstream/`), leading (`/main`), or doubled (`upstream//main`)
-  // slashes don't produce empty `**` segments that degrade to useless
-  // patterns. A single remaining token means the user hasn't committed
-  // to a remote-plus-branch query yet — route through the widened
-  // single-segment globs below instead of pinning to one segment.
+  // Why: split on `/` so display-format queries route each token to one ref segment; filter empties from stray slashes.
   const tokens = getRefSearchTokens(normalizedQuery)
   if (tokens.length <= 1) {
     const q = tokens[0] ?? ''
-    // Why `**`, not `*`: git for-each-ref globs are fnmatch-style where a
-    // single `*` does NOT cross `/`. Slash-named branches (`user/feature`)
-    // are the norm, so match both leaf and ancestor branch-name segments.
-    // The remote ancestor glob also preserves remote-name queries like
-    // `upstream` while `**/` keeps flat names like `main` working.
+    // Why `**` not `*`: fnmatch `*` can't cross `/`, so match slash-named branches at both leaf and ancestor segments.
     return [
       ...base,
       `refs/heads/**/*${q}*`,
@@ -769,11 +668,7 @@ export function buildSearchBaseRefsArgv(
       `refs/remotes/**/*${q}*/**`
     ]
   }
-  // Why: multi-token queries like `upstream/main` map one `*token*` per
-  // ref segment, so each token is matched within a single git ref
-  // segment (fnmatch `*` cannot cross `/`). The picker displays results
-  // as `<remote>/<branch>`, so users naturally retype that format; this
-  // branch is what makes re-typing a visible result actually find it.
+  // Why: one `*token*` per ref segment because fnmatch `*` can't cross `/`; lets a retyped `<remote>/<branch>` result match.
   const segmented = tokens.map((token) => `*${token}*`).join('/')
   const substringQuery = tokens.join('/')
   const remoteBranchRootPatterns =
@@ -785,9 +680,7 @@ export function buildSearchBaseRefsArgv(
       : [`refs/remotes/*/${substringQuery}*`, `refs/remotes/*/${substringQuery}*/**`]
   const segmentedPatterns = [`refs/remotes/${segmented}`, `refs/heads/${segmented}`]
   const branchRootPatterns = [
-    // Why: branch names often contain slashes (`plan/docs`). Segment-wise
-    // display-format globs only align with `<remote>/<branch>`; these root
-    // patterns also match the local branch name beneath any configured remote.
+    // Why: branch names often contain slashes (plan/docs); these root patterns also match a local branch beneath any remote.
     `refs/heads/${substringQuery}*`,
     `refs/heads/${substringQuery}*/**`,
     ...remoteBranchRootPatterns
@@ -865,9 +758,7 @@ export async function getDefaultRemote(
   options: LocalGitExecOptions = {}
 ): Promise<string> {
   const defaultRef = await getDefaultBaseRefAsync(path, options)
-  // Why: getDefaultBaseRefAsync returns null when no default branch can be
-  // detected (e.g. a brand-new repo with no commits on origin). Guard so we
-  // don't crash on .includes(); fall through to the remote-list heuristics.
+  // Why: getDefaultBaseRefAsync returns null when no default branch exists; guard so .includes() can't crash.
   const defaultBranch = defaultRef
     ? defaultRef.includes('/')
       ? defaultRef.split('/').slice(1).join('/')
@@ -930,14 +821,11 @@ export async function searchBaseRefDetails(
   const normalizedQuery = normalizeRefSearchQuery(query)
 
   try {
-    // Why: argv (including the two-remote-glob rationale) lives in
-    // buildSearchBaseRefsArgv so the SSH sibling cannot drift.
+    // Why: argv lives in buildSearchBaseRefsArgv so the SSH sibling cannot drift.
     const remotes = await listRemoteNames(path)
     const tokens = getRefSearchTokens(normalizedQuery)
     if (tokens.length > 1) {
-      // Why: ambiguous slash queries need both display-format matches
-      // (`upstream/feat`) and local branch-name matches (`plan/docs`).
-      // Parse and merge buckets before the final limit so neither side starves.
+      // Why: slash queries need both display-format and local-branch matches; merge before the limit so neither starves.
       const results = await Promise.all([
         runSearchBaseRefsGit(path, normalizedQuery, limit, {
           remoteNames: remotes,
@@ -959,10 +847,7 @@ export async function searchBaseRefDetails(
     })
     return parseAndFilterSearchRefDetails(result.stdout, limit, remotes)
   } catch (err) {
-    // Why: surface the failure for diagnostics; callers treat `[]` as "no
-    // matches", but silently swallowing the error makes a missing result
-    // set impossible to debug. Mirrors the SSH sibling in
-    // src/main/ipc/repos.ts.
+    // Why: log so a missing result set is debuggable; callers still treat [] as "no matches".
     console.warn('[searchBaseRefs] for-each-ref failed', { path, err })
     return []
   }
@@ -981,15 +866,8 @@ async function listRemoteNames(path: string, options: LocalGitExecOptions = {}):
 }
 
 /**
- * Parse `git for-each-ref --format=%(refname)%00%(refname:short)` stdout
- * into a deduped list of short refs, filtering out `<remote>/HEAD`
- * pseudo-refs, honoring a limit.
- *
- * Why: shared between the local `searchBaseRefs` and the SSH branch in
- * `src/main/ipc/repos.ts` so both return identical, correctly-filtered
- * results. The same bug class (wrong filter ordering, HEAD leaking into
- * results, duplicate short refs) that motivated this helper originally
- * lived in a single location; two copies double the regression surface.
+ * Parse `git for-each-ref --format=%(refname)%00%(refname:short)` stdout into a deduped list of short
+ * refs, dropping `<remote>/HEAD` pseudo-refs. Shared with the SSH branch in ipc/repos.ts so filtering can't drift.
  */
 export function parseAndFilterSearchRefs(stdout: string, limit: number): string[] {
   return parseAndFilterSearchRefDetails(stdout, limit).map((entry) => entry.refName)
@@ -1010,22 +888,13 @@ export function parseAndFilterSearchRefDetails(
       .map((line) => {
         const nul = line.indexOf('\0')
         if (nul < 0) {
-          // Why: defensive fallback for an unlikely %(refname) format change.
-          // Drop the entry — emitting a full refname as a "short" ref would
-          // hand callers a ref they can't use (and would bypass the HEAD
-          // filter below, since we could no longer tell a `<remote>/HEAD`
-          // pseudo-ref from a local branch named `foo/HEAD`).
+          // Why: no NUL means an unexpected %(refname) format; drop it rather than hand callers an unusable "short" ref.
           return null
         }
         return { full: line.slice(0, nul), short: line.slice(nul + 1) }
       })
       .filter((entry): entry is { full: string; short: string } => entry !== null)
-      // Why: drop `refs/remotes/<remote>/HEAD` pseudo-refs. Uses `.+` (not
-      // `[^/]+`) because git allows slashes in remote names, so nested
-      // remotes like `refs/remotes/foo/bar/HEAD` also match. A local branch
-      // named `foo/HEAD` (rare but valid per git check-ref-format) is
-      // preserved because its `full` is `refs/heads/foo/HEAD`, which does
-      // not match this pattern.
+      // Why: drop `<remote>/HEAD` pseudo-refs; `.+` (not `[^/]+`) since git allows slashes in remote names.
       .filter(({ full }) => !/^refs\/remotes\/.+\/HEAD$/.test(full))
       .filter(({ short }) => {
         if (seen.has(short)) {
@@ -1038,9 +907,7 @@ export function parseAndFilterSearchRefDetails(
         refName: short,
         localBranchName: resolveLocalBranchName(full, short, sortedRemotes)
       }))
-      // Why: `Math.max(0, limit)` — treat pathological `limit <= 0` as
-      // "zero results" rather than "at least 1". More honest than silently
-      // returning a single ref when the caller explicitly asked for none.
+      // Why: Math.max(0, limit) so pathological limit <= 0 yields zero results, not one.
       .slice(0, Math.max(0, limit))
   )
 }
@@ -1099,9 +966,7 @@ export async function getBranchConflictKind(
         return false
       }
       const shortRef = trimmed.replace(/^refs\/remotes\//, '')
-      // Why: git allows slashes in remote names. Use the configured remote
-      // list so foo/bar/feature resolves as branch "feature" for remote
-      // "foo/bar", matching searchBaseRefDetails.
+      // Why: git allows slashes in remote names; use the configured list so foo/bar/feature resolves to branch "feature".
       return resolveLocalBranchName(trimmed, shortRef, remoteNames) === branchName
     })
 
@@ -1121,10 +986,7 @@ function isAllowedRemoteBaseRef(refName: string, allowedBaseRef: string | undefi
   return refName === normalizedAllowedRef
 }
 
-/**
- * Build a hosted URL (e.g. GitHub, GitLab, Bitbucket) for a specific file
- * and line in the repo. Returns null when the remote isn't a recognized host.
- */
+/** Build a hosted URL (GitHub/GitLab/Bitbucket) for a file+line; null when the remote isn't a recognized host. */
 export function getRemoteFileUrl(
   repoPath: string,
   relativePath: string,
@@ -1144,10 +1006,7 @@ export function getRemoteFileUrl(
   return buildHostedRemoteFileUrl(remoteUrl, relativePath, defaultBranch, line)
 }
 
-/**
- * Build a hosted URL (e.g. GitHub, GitLab, Bitbucket) for a commit. Returns
- * null when the origin remote isn't a recognized host.
- */
+/** Build a hosted URL (GitHub/GitLab/Bitbucket) for a commit; null when origin isn't a recognized host. */
 export function getRemoteCommitUrl(repoPath: string, sha: string): string | null {
   const remoteUrl = getRemoteUrl(repoPath)
   if (!remoteUrl) {
diff --git a/src/main/git/runner.ts b/src/main/git/runner.ts
index 598ed2a9781..fac9f57ecac 100644
--- a/src/main/git/runner.ts
+++ b/src/main/git/runner.ts
@@ -1,13 +1,10 @@
-/* eslint-disable max-lines -- Why: command routing, WSL translation, and
-git/gh/glab wrappers must stay co-located so platform behavior remains
-consistent across every repo-scoped subprocess call. */
+/* eslint-disable max-lines -- command routing, WSL translation, and git/gh/glab wrappers stay co-located for consistent platform behavior. */
 /**
  * Centralized git/gh/command runner with transparent WSL support.
  *
- * Why: When a repo lives on a WSL filesystem (UNC path like \\wsl.localhost\Ubuntu\...),
- * native Windows binaries (git.exe, gh.exe, rg.exe) are either absent or extremely slow.
- * This module detects WSL paths and routes command execution through `wsl.exe -d <distro>`
- * with translated Linux paths, so every call site gets WSL support for free.
+ * Why: when a repo lives on a WSL filesystem, native Windows binaries (git.exe,
+ * gh.exe, rg.exe) are absent or slow, so this routes execution through
+ * `wsl.exe -d <distro>` with translated Linux paths.
  */
 import {
   execFile,
@@ -42,16 +39,13 @@ import {
 } from '../../shared/wsl-login-shell-command'
 import { UNTRANSLATED_GIT_OUTPUT_ENV } from '../../shared/git-output-locale'
 import { endSubprocessStdin } from '../../shared/subprocess-stdin-write'
-// Re-exported for existing importers; lightweight consumers should import these
-// from './exec-error' directly so they do not depend on this heavy module.
+// Re-exported for existing importers; lightweight consumers should import from './exec-error' to avoid this heavy module.
 import { extractExecError, parseRetryAfterMs } from './exec-error'
 export { extractExecError, parseRetryAfterMs }
 
 // ─── Core resolution ────────────────────────────────────────────────
 
-// `LANGUAGE=en LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8` — env-assignment prefix for
-// WSL-routed git, where spawn env cannot cross the wsl.exe boundary. Values are
-// shell-safe unquoted (alnum, dot, dash, underscore only).
+// Env-assignment prefix for WSL-routed git, where spawn env can't cross the wsl.exe boundary; values are shell-safe unquoted.
 const GIT_OUTPUT_LOCALE_SHELL_PREFIX = Object.entries(UNTRANSLATED_GIT_OUTPUT_ENV)
   .map(([key, value]) => `${key}=${value}`)
   .join(' ')
@@ -65,14 +59,10 @@ type ResolvedCommand = {
 }
 
 /**
- * Translate any Windows-style paths in command arguments to Linux paths
- * when the command will execute inside WSL.
+ * Translate Windows-style path arguments to Linux paths for commands run in WSL.
  *
- * Why: callers like worktree-create pass Windows paths (e.g. the workspace
- * directory) as git arguments. WSL git doesn't understand Windows paths,
- * so we must translate them. WSL UNC paths (\\wsl.localhost\...) are
- * converted to their native Linux form; regular Windows drive paths
- * (C:\Users\...) are converted to /mnt/c/Users/...
+ * Why: callers pass Windows paths as git arguments, which WSL git can't read.
+ * UNC paths (\\wsl.localhost\…) become native Linux; drive paths (C:\…) → /mnt/c/…
  */
 function translateArgsForWsl(args: string[]): string[] {
   return args.map(translateArgForWsl)
@@ -155,8 +145,7 @@ function resolveHostGitHubCli(command: 'gh', args: string[]): ResolvedCommand {
   return {
     binary: command,
     args,
-    // Why: host gh cannot use a WSL UNC cwd reliably. We only fall back
-    // for commands with explicit repo/API context, so no repo cwd is required.
+    // Why: host gh can't use a WSL UNC cwd; we only fall back for commands with explicit repo/API context, so none is needed.
     cwd: undefined,
     wsl: null
   }
@@ -183,13 +172,10 @@ function isHostCommandMissing(err: unknown, command: 'gh' | 'glab'): boolean {
 }
 
 /**
- * Given a command, its arguments, and a working directory, resolve whether
- * the invocation should be routed through wsl.exe.
+ * Resolve whether a command invocation should be routed through wsl.exe.
  *
- * Why `bash -c "cd ... && ..."` instead of `--cd`: wsl.exe's --cd flag
- * does not work reliably when invoked via Node's execFile/spawn (it fails
- * with ERROR_PATH_NOT_FOUND in some configurations). Using bash -c with
- * an explicit cd is universally supported.
+ * Why `bash -c "cd … && …"` instead of `--cd`: wsl.exe's --cd fails with
+ * ERROR_PATH_NOT_FOUND under Node's execFile/spawn in some configs.
  */
 function resolveCommand(
   command: string,
@@ -202,16 +188,8 @@ function resolveCommand(
     return { binary: command, args, cwd, wsl: null }
   }
 
-  // Why: global gh callers (rate_limit, listAccessibleProjects) have no
-  // meaningful cwd to derive a WSL distro from. On WSL-only Windows setups,
-  // gh.exe isn't on the host PATH and the spawn fails with ENOENT. Allow
-  // callers to pass a distro hint so we can route through wsl.exe regardless.
-  // TODO(wsl-default-distro): the codebase currently has no persistent
-  // "default WSL distro" setting — distros are derived from individual repo
-  // paths. Until such a setting exists, global gh callers without an explicit
-  // override silently fall back to host gh.exe, which on WSL-only Windows
-  // installs will ENOENT. The wslDistroOverride parameter is the hook for
-  // wiring a future setting in without re-plumbing the runner.
+  // Why: global gh callers (rate_limit, listAccessibleProjects) have no cwd to derive a distro from; a distro hint still routes through wsl.exe.
+  // TODO(wsl-default-distro): no default-distro setting yet, so override-less global gh callers fall back to host gh.exe (ENOENT on WSL-only installs).
   const cwdWsl = cwd ? parseWslPath(cwd) : null
   const wsl: WslPathInfo | null =
     cwdWsl ?? (wslDistroOverride ? { distro: wslDistroOverride, linuxPath: '' } : null)
@@ -220,20 +198,12 @@ function resolveCommand(
   }
 
   const translatedArgs = translateArgsForWsl(args)
-  // Why: env set on wsl.exe stays on the Windows side (WSLENV forwards only
-  // named vars), so the untranslated-output locale must ride the command
-  // string for git stderr parsers to work inside the distro (issue #7808).
+  // Why: env on wsl.exe stays Windows-side (WSLENV forwards only named vars), so the locale must ride the command string (issue #7808).
   const localePrefix = command === 'git' ? `${GIT_OUTPUT_LOCALE_SHELL_PREFIX} ` : ''
   const escapedCommand = quotePosixShell(command)
-  // Why: shell-escape each argument to prevent word splitting / glob expansion
-  // inside the bash -c string. Single quotes are safe for all chars except
-  // single quotes themselves, which we escape as '\'' (end quote, escaped
-  // literal, reopen quote).
+  // Why: shell-escape each arg to prevent word splitting / glob expansion inside the bash -c string.
   const escapedArgs = translatedArgs.map(quotePosixShell)
-  // Why: when cwd is supplied as a WSL UNC path, prepend `cd <linuxPath> &&`
-  // so the command runs in the expected directory. When the caller only
-  // supplied a distro override (no cwd), skip the cd entirely — the gh CLI
-  // doesn't need a particular cwd for global calls like `api rate_limit`.
+  // Why: prepend `cd <linuxPath> &&` for a UNC cwd; skip it when only a distro override was given (global gh needs no cwd).
   const linuxCwd = cwdWsl?.linuxPath ?? (cwd && wslDistroOverride ? translateArgForWsl(cwd) : null)
   const shellCmd = linuxCwd
     ? `cd ${quotePosixShell(linuxCwd)} && ${localePrefix}${escapedCommand} ${escapedArgs.join(' ')}`
@@ -258,9 +228,7 @@ function resolveCommand(
   return {
     binary: 'wsl.exe',
     args: ['-d', wsl.distro, '--', 'bash', '-c', shellCmd],
-    // Why: cwd is set to undefined because wsl.exe handles directory switching
-    // via the cd inside bash -c. Setting a UNC cwd on the Node process would
-    // be redundant and can cause issues with some Node internals.
+    // Why: the `cd` inside bash -c handles the directory; a UNC cwd on the Node process is redundant and can break Node internals.
     cwd: undefined,
     wsl
   }
@@ -268,12 +236,7 @@ function resolveCommand(
 
 // ─── Git-specific runners ───────────────────────────────────────────
 
-// Why: Node's execFile only honors maxBuffer when it is a number — passing
-// `undefined` (which happens whenever a caller omits the option) disables the
-// cap entirely, so a command that prints more than V8's ~512MB max string
-// length crashes the main process uncatchably inside execFile's exit handler
-// (Array.join over the buffered chunks). Apply this floor so no git call can
-// ever buffer without a bound. Matches the relay's MAX_GIT_BUFFER.
+// Why: execFile disables its cap when maxBuffer is undefined; unbounded output over V8's string max crashes main uncatchably — keep in sync with relay MAX_GIT_BUFFER.
 export const DEFAULT_GIT_MAX_BUFFER = 10 * 1024 * 1024
 
 type GitExecOptions = {
@@ -334,8 +297,7 @@ function killSpawnedCommandTree(child: ChildProcess): Promise<void> {
   return new Promise((resolve) => {
     let killer: ChildProcess
     try {
-      // Why: Windows shims and wsl.exe can own descendants; wait for /t tree
-      // cleanup before settling so a timed-out command cannot outlive its probe.
+      // Why: Windows shims/wsl.exe own descendants; wait for /t tree cleanup so a timed-out command can't outlive its probe.
       killer = spawn('taskkill', ['/pid', String(pid), '/t', '/f'], {
         stdio: 'ignore',
         windowsHide: true
@@ -457,8 +419,7 @@ function execFileCapture(
 
     try {
       const spawnStartedAt = performance.now()
-      // Why: the abort listener below owns tree-aware cleanup. Node's
-      // signal handler could kill wsl.exe before taskkill sees its children.
+      // Why: our abort listener owns tree cleanup; Node's signal handler could kill wsl.exe before taskkill sees its children.
       child = execFile(
         command,
         args,
@@ -495,8 +456,7 @@ function execFileCapture(
       endSubprocessStdin(child.stdin, options.stdin)
     }
 
-    // Why: Node's native timeout can wait forever for signal-ignoring CLIs;
-    // enforce our own deadline and settle after bounded process-tree cleanup.
+    // Why: Node's timeout waits forever on signal-ignoring CLIs; enforce our own deadline with bounded tree cleanup.
     if (options.timeout && options.timeout > 0) {
       timer = setTimeout(() => {
         if (settled || terminating) {
@@ -623,19 +583,14 @@ export function gitOptionalLocksDisabledEnv(
 }
 
 /**
- * Append git config entries through the GIT_CONFIG_COUNT / GIT_CONFIG_KEY_n /
- * GIT_CONFIG_VALUE_n env protocol (git >= 2.31), composing with any count
- * already present in `env` so we never clobber config a caller injected the
- * same way.
+ * Append git config via the GIT_CONFIG_COUNT/KEY_n/VALUE_n env protocol (git >= 2.31),
+ * composing with any count already in `env` so we never clobber a caller's config.
  */
 export { appendGitConfigEnv }
 
 /**
- * Pin Orca-spawned git to untranslated English output so stderr/progress
- * parsers keep working under any user locale (issue #7808; see
- * UNTRANSLATED_GIT_OUTPUT_ENV for the full rationale). Terminal git is
- * untouched. Injected by every git runner in this module; WSL-routed spawns
- * get the same values via GIT_OUTPUT_LOCALE_SHELL_PREFIX instead.
+ * Pin Orca-spawned git to untranslated English output so stderr/progress parsers
+ * work under any user locale (issue #7808). Terminal git is untouched.
  */
 export function untranslatedGitOutputEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   return { ...env, ...UNTRANSLATED_GIT_OUTPUT_ENV }
@@ -649,11 +604,9 @@ export function promptGuardGitEnv(
 }
 
 /**
- * Credential-prompt guard for a general-purpose shell environment (terminal
- * PTYs, hook scripts): everything promptGuardGitEnv does EXCEPT the issue-7808
- * locale pins. Those exist so Orca can parse stderr of git it spawns itself;
- * forcing LC_ALL/LANG/LANGUAGE onto a user's shell would change the locale of
- * every child process, not just git's.
+ * Credential-prompt guard for a general-purpose shell (PTYs, hook scripts):
+ * like promptGuardGitEnv but without the issue-7808 locale pins, which would
+ * change the locale of every child process, not just git's.
  */
 export function promptGuardShellEnv(
   env: NodeJS.ProcessEnv = process.env,
@@ -663,21 +616,15 @@ export function promptGuardShellEnv(
 }
 
 /**
- * Force git to be non-interactive so it fails fast instead of blocking forever
- * on a prompt. Without this, a git read-path call (status, worktree list, …)
- * that hits an auth/credential prompt or an SSH host-key confirmation hangs on
- * stdin with no terminal to answer it; on the headless `serve` runtime those
- * stuck calls pile up and the runtime stops answering all clients (issue #5308).
+ * Force git non-interactive so it fails fast instead of hanging on a prompt with
+ * no terminal to answer it; on headless `serve` those stuck calls wedge every
+ * client (issue #5308).
  *
- * - GIT_TERMINAL_PROMPT=0: git refuses to prompt for credentials and errors out.
- * - GIT_ASKPASS / SSH_ASKPASS: emptied when unset so no GUI/askpass helper can
- *   pop a prompt and block. A caller-provided askpass is preserved on purpose —
- *   custom askpass setups commonly *serve* credentials non-interactively, and
- *   blanking them would break those fetches.
- * - GIT_SSH_COMMAND BatchMode=yes: SSH fails instead of waiting on an
- *   interactive password/host-key prompt. BatchMode does NOT change host trust
- *   (an unknown host still errors, it just won't hang). Only added when the
- *   caller hasn't set its own GIT_SSH_COMMAND.
+ * - GIT_TERMINAL_PROMPT=0: git errors instead of prompting for credentials.
+ * - GIT_ASKPASS / SSH_ASKPASS: emptied when unset so no GUI helper blocks; a
+ *   caller-provided askpass is preserved (custom setups serve creds non-interactively).
+ * - GIT_SSH_COMMAND BatchMode=yes: SSH errors instead of prompting (doesn't change
+ *   host trust); only added when the caller hasn't set its own.
  */
 export function nonInteractiveGitEnv(
   env: NodeJS.ProcessEnv = process.env,
@@ -687,9 +634,7 @@ export function nonInteractiveGitEnv(
   if (!next.GIT_SSH_COMMAND) {
     next.GIT_SSH_COMMAND = 'ssh -o BatchMode=yes'
     if (platform === 'win32') {
-      // Why: forward across the WSL boundary only when we set the value —
-      // plain `ssh` resolves inside the distro, whereas a caller's
-      // Windows-specific GIT_SSH_COMMAND must not leak into Linux git.
+      // Why: forward GIT_SSH_COMMAND to WSL only when we set it — a caller's Windows-specific value must not leak into Linux git.
       addWslEnvKeys(next, ['GIT_SSH_COMMAND'])
     }
   }
@@ -852,8 +797,7 @@ async function buildNetworkSshPolicyEnv(options: GitExecOptions): Promise<{
 
   const batchModeCommand = buildOpenSshBatchModeCommand(configuredCommand)
   if (!batchModeCommand) {
-    // Why: custom wrappers are executable user policy; rewriting their argv is
-    // riskier than relying on prompt guards plus the caller's target timeout.
+    // Why: custom SSH wrappers are user policy; rewriting their argv is riskier than relying on prompt guards + timeout.
     return { env: promptEnv, mode: 'configured-wrapper-passthrough' }
   }
 
@@ -872,10 +816,7 @@ export async function gitExecFileAsync(
   args: string[],
   options: GitExecOptions
 ): Promise<{ stdout: string; stderr: string }> {
-  // Why wrap here: the resolved binary path / WSL detection is internal
-  // detail; the span attributes track the user-visible `git <subcommand>
-  // <args…>` form so dashboards group cleanly by intent rather than by
-  // platform-conditional binary path.
+  // Why: span the user-visible `git <subcommand>` form, not the resolved binary, so dashboards group by intent.
   return withGitSpan(
     { args, ...(options.cwd !== undefined ? { cwd: options.cwd } : {}) },
     async () => {
@@ -893,8 +834,7 @@ export async function gitExecFileAsync(
           maxBuffer: options.maxBuffer,
           timeout: options.timeout,
           stdin: options.stdin,
-          // Why: never let a git read-path call block on an interactive prompt
-          // (issue #5308) — fail fast instead of hanging the runtime.
+          // Why: never let a git read-path call block on an interactive prompt (issue #5308) — fail fast.
           env: policy.env,
           signal: options.signal
         })
@@ -973,8 +913,7 @@ export async function gitExecFileAsyncBuffer(
   return { stdout }
 }
 
-/** Result of a streamed git command. `stoppedEarly` is true when the caller's
- * onStdout hook asked to stop and the child was killed before exiting. */
+/** Result of a streamed git command; `stoppedEarly` is true when onStdout asked to stop before the child exited. */
 export type GitStreamResult = { stoppedEarly: boolean }
 
 type GitStreamOptions = {
@@ -985,10 +924,8 @@ type GitStreamOptions = {
   /** Byte backstop; defaults to DEFAULT_GIT_MAX_BUFFER. */
   maxBuffer?: number
   /**
-   * Called for each decoded stdout chunk as it arrives. Return true to stop:
-   * the child is killed and the promise resolves with stoppedEarly=true. This
-   * lets a streaming parser bail out (e.g. once an entry limit is reached)
-   * without ever buffering the full output.
+   * Called for each decoded stdout chunk. Return true to stop: the child is
+   * killed and the promise resolves with stoppedEarly=true.
    */
   onStdout: (chunk: string) => boolean | void
 }
@@ -996,11 +933,9 @@ type GitStreamOptions = {
 /**
  * Stream a git command's stdout incrementally instead of buffering it whole.
  *
- * Why: status on a repo with an enormous un-ignored folder can emit more output
- * than fits in a single string, crashing the process when buffered. Streaming
- * lets the parser count entries as they arrive and stop git the moment a limit
- * is crossed, so memory stays bounded. Built on gitSpawn so WSL routing is
- * preserved. stderr is bounded; a non-zero exit rejects (unless we stopped it).
+ * Why: output larger than V8's max string (e.g. status on a repo with a huge
+ * un-ignored folder) crashes the process when buffered; streaming keeps memory
+ * bounded and lets the parser stop git early. Built on gitSpawn for WSL routing.
  */
 export async function gitStreamStdout(
   args: string[],
@@ -1026,9 +961,7 @@ export async function gitStreamStdout(
       let stdoutBytes = 0
       let stderr = ''
       let stderrBytes = 0
-      // Why: decode statefully so a multibyte UTF-8 character split across two
-      // chunks (common with non-ASCII filenames) isn't corrupted into
-      // replacement characters and mis-parsed.
+      // Why: decode statefully so a multibyte UTF-8 char split across chunks isn't corrupted into replacement chars.
       const stdoutDecoder = new StringDecoder('utf8')
       const stderrDecoder = new StringDecoder('utf8')
 
@@ -1066,9 +999,7 @@ export async function gitStreamStdout(
         if (decoded.length === 0) {
           return
         }
-        // Why: the parser callback is caller-supplied; a throw here would escape
-        // the stream event handler and crash the main process (the exact failure
-        // mode this streaming path exists to prevent). Convert it to a rejection.
+        // Why: a throw from the caller's parser would escape this event handler and crash main; convert to a rejection.
         let shouldStop: boolean | void
         try {
           shouldStop = options.onStdout(decoded)
@@ -1078,8 +1009,7 @@ export async function gitStreamStdout(
           return
         }
         if (shouldStop === true) {
-          // Why: parser hit its limit. Kill git and resolve cleanly — the
-          // partial output we already parsed is the intended result.
+          // Parser hit its limit: kill git and resolve cleanly with the partial output.
           stoppedEarly = true
           void killSpawnedCommandTree(child)
           finish(null)
@@ -1121,11 +1051,7 @@ export async function gitStreamStdout(
   })
 }
 
-// Why: sync git calls run on the Electron main thread. Local git is normally
-// fast, but a repo on a dead network drive / cloud-placeholder path can hang
-// git on filesystem timeouts for minutes with no timeout set — the leading
-// explanation for issue #7225's 127s "Not Responding" freeze. Callers needing
-// longer operations should use the async runners instead.
+// Why: sync git blocks the main thread; a dead network drive can hang git for minutes without a timeout (issue #7225's 127s freeze).
 const GIT_EXEC_SYNC_TIMEOUT_MS = 15_000
 
 /**
@@ -1154,8 +1080,7 @@ export function gitExecFileSync(
       timeout: options.timeout ?? GIT_EXEC_SYNC_TIMEOUT_MS
     }) as string
   } finally {
-    // Sync exec holds the main thread for its whole duration, so the entire
-    // call is main-thread block time — the cost issue #7576 flags.
+    // Sync exec blocks the main thread for its whole duration — the cost issue #7576 flags.
     recordSubprocessSpawn(resolved.binary, resolved.args, performance.now() - spawnStartedAt)
   }
 }
@@ -1184,23 +1109,9 @@ export function gitSpawn(
 
 // ─── gh CLI runners ─────────────────────────────────────────────────
 
-// Why: non-repo-scoped gh calls (listAccessibleProjects, rate_limit, etc.)
-// have no meaningful cwd. Allow it to be omitted so the one WSL-aware wrapper
-// serves both repo-scoped and global callers and we stop having two spawn
-// sites (the other one — a plain execFileAsync in project-view.ts — bypasses
-// retry/backoff and any future quota tracker).
-// Why: `wslDistro` is an explicit hint for global (cwd-less) gh callers on
-// WSL-only Windows installs where gh.exe isn't on the host PATH. When set,
-// resolveCommand routes the spawn through `wsl.exe -d <distro> -- gh ...`
-// even without a UNC cwd to parse a distro from. Repo-scoped callers should
-// keep using cwd — the distro derives from the path automatically there.
-// Why: `idempotent` gates the transient-error retry. When undefined we
-// auto-detect from argv (writes are detected by `-X POST/PATCH/PUT/DELETE`
-// or a `query=mutation …` arg); callers can also pass an explicit override.
-// A 5xx/socket reset after the request reaches GitHub but before the
-// response returns is the canonical case where the server-side write
-// succeeded; retrying would create a duplicate comment/issue/label addition.
-// See bug-scan finding 1.
+// `cwd?` omitted for non-repo-scoped gh calls (rate_limit, listAccessibleProjects) so one WSL-aware wrapper serves both.
+// `wslDistro?` routes global cwd-less gh through `wsl.exe -d <distro>` on WSL-only Windows where gh.exe isn't on host PATH.
+// `idempotent?` gates transient-error retry (auto-detected from argv); retrying a write that already reached GitHub would duplicate it.
 type GhExecOptions = Omit<GitExecOptions, 'cwd'> & {
   cwd?: string
   wslDistro?: string
@@ -1208,8 +1119,7 @@ type GhExecOptions = Omit<GitExecOptions, 'cwd'> & {
 }
 
 const NON_IDEMPOTENT_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE'])
-// `gh <noun> <verb>` write subcommands. Reads (view/list/status/checks)
-// are absent on purpose so the default of "retry" stays for them.
+// `gh <noun> <verb>` write subcommands; reads are absent on purpose so they keep retrying.
 const NON_IDEMPOTENT_GH_VERBS = new Set([
   'create',
   'edit',
@@ -1251,9 +1161,7 @@ function argsLookIdempotent(args: string[]): boolean {
         return false
       }
     }
-    // `gh api` auto-switches GET→POST when -f/-F/--field/--raw-field body
-    // fields are supplied without an explicit -X. Track those to classify
-    // such calls as non-idempotent.
+    // `gh api` auto-POSTs when -f/-F/--field body fields are given without -X; track them.
     if (a === '-f' || a === '-F' || a === '--field' || a === '--raw-field') {
       hasApiBodyField = true
     } else if (
@@ -1264,8 +1172,7 @@ function argsLookIdempotent(args: string[]): boolean {
     ) {
       hasApiBodyField = true
     }
-    // `gh api graphql -f query=mutation(...){ ... }` — detect mutation queries
-    // so writes via the GraphQL endpoint also fail fast on transient errors.
+    // Detect GraphQL `query=mutation(…)` so endpoint writes also fail fast on transient errors.
     if (a.startsWith('query=')) {
       hasGraphQlQuery = true
       const trimmed = a.slice('query='.length).trimStart().toLowerCase()
@@ -1274,10 +1181,7 @@ function argsLookIdempotent(args: string[]): boolean {
       }
     }
   }
-  // `gh api ... -f foo=bar` with no explicit method: gh switches to POST.
-  // Treat as non-idempotent so a transient 5xx after the server applied
-  // the write doesn't retry and duplicate it. GraphQL reads are the exception:
-  // gh sends them as POST body fields, but a query operation is idempotent.
+  // `gh api -f foo=bar` with no -X auto-POSTs → non-idempotent; GraphQL query bodies are the exception (still reads).
   if (
     args[0] === 'api' &&
     hasApiBodyField &&
@@ -1286,10 +1190,7 @@ function argsLookIdempotent(args: string[]): boolean {
   ) {
     return false
   }
-  // `gh issue close`, `gh pr edit`, `gh pr merge`, etc. The first arg is the
-  // noun (issue/pr/repo/label/...) and the second is the verb. Defaulting
-  // `gh api` calls without an explicit -X to GET-equivalent (idempotent) is
-  // intentional: callers that POST through `gh api` set `-X POST`.
+  // `gh <noun> <verb>` writes (args[1]); `gh api` without -X defaults to idempotent GET, so it's excluded here.
   if (args.length >= 2 && args[0] !== 'api') {
     if (NON_IDEMPOTENT_GH_VERBS.has(args[1])) {
       return false
@@ -1301,12 +1202,9 @@ function argsLookIdempotent(args: string[]): boolean {
 /**
  * Classify whether a gh execFile rejection is worth retrying.
  *
- * Why: gh surfaces HTTP status in stderr as "HTTP 504", "HTTP 502", etc.
- * Network resets and DNS hiccups also show up as stderr substrings. We retry
- * those and 429 (rate-limited) — but only 429s without an explicit
- * Retry-After (the caller is better off propagating so the UI can show the
- * actual wait time). The primary-rate-limit 403 branch is NOT retried: those
- * require the user to back off for minutes, which is not transient.
+ * Why: gh surfaces HTTP status as stderr substrings ("HTTP 504", econnreset, …).
+ * Retry 5xx/network resets and 429 only without Retry-After (propagate those so
+ * the UI can show the wait); primary-rate-limit 403 is never transient.
  */
 export function isTransientGhError(stderr: string): boolean {
   const s = stderr.toLowerCase()
@@ -1328,18 +1226,10 @@ export function isTransientGhError(stderr: string): boolean {
   return false
 }
 
-// Why: total of 3 attempts (original + 2 retries) with 250ms → 1s backoff.
-// These are standard "transient 5xx" values. Longer waits push past user
-// patience for an interactive action; shorter waits would hammer the same
-// unhealthy upstream that just failed. The array length defines retry count;
-// total attempts = length + 1.
+// Why: 3 attempts total (250ms → 1s backoff); array length defines retry count (total attempts = length + 1).
 const GH_RETRY_DELAYS_MS = [250, 1000] as const
 
-// Why: the upstream Retry-After header is server-suggested but unbounded —
-// GitHub has been observed to send tens-of-seconds values on rare incidents,
-// and a malicious or misconfigured proxy could send anything. Cap the wait
-// at 30s so a single transient gh call can never block the IPC main thread
-// for longer than the user's patience budget for an interactive action.
+// Why: Retry-After is unbounded and untrusted; cap at 30s so a gh call can't block the IPC thread indefinitely.
 const GH_RETRY_AFTER_MAX_MS = 30_000
 const DEFAULT_GH_EXEC_TIMEOUT_MS = 30_000
 
@@ -1367,17 +1257,14 @@ function nonInteractiveGhEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.Proce
  * Async gh CLI execution. Drop-in replacement for
  * `execFileAsync('gh', args, { cwd, encoding, ... })`.
  *
- * Retries transient 5xx / 429 (without Retry-After) / network-reset failures
- * with exponential backoff. Non-transient errors (auth, 404, rate-limit 403,
- * validation, 429-with-Retry-After) fail fast on the first attempt.
+ * Retries transient 5xx / 429-without-Retry-After / network-reset failures with
+ * exponential backoff; other errors fail fast.
  */
 export async function ghExecFileAsync(
   args: string[],
   options: GhExecOptions = {}
 ): Promise<{ stdout: string; stderr: string }> {
-  // Why: while a bucket's primary rate limit is exhausted, every spawn would
-  // return the same 403 — fail fast without paying the subprocess cost. The
-  // rate_limit probe itself is exempt so the breaker can learn the reset time.
+  // Why: while a bucket is rate-limited every spawn returns 403 — fail fast; the probe is exempt so the breaker can learn the reset.
   const rateLimitBucket = classifyGhRateLimitBucket(args)
   if (!isGhRateLimitProbe(args)) {
     const blockedUntilMs = getGhRateLimitBlockedUntilMs(rateLimitBucket)
@@ -1395,8 +1282,7 @@ export async function ghExecFileAsync(
         cwd: resolved.cwd,
         encoding: (options.encoding ?? 'utf-8') as BufferEncoding,
         maxBuffer: options.maxBuffer,
-        // Why: GitHub detail IPC powers PR cards, Tasks, and URL worktree
-        // creation; one stuck gh child must fail visibly, not wedge every lane.
+        // Why: bound gh so one stuck child fails visibly instead of wedging the IPC lane.
         timeout: options.timeout ?? defaultGhExecTimeoutMs(options.env),
         env: nonInteractiveGhEnv(options.env)
       })
@@ -1417,8 +1303,7 @@ export async function ghExecFileAsync(
       ) {
         const wslResolved = resolveDefaultWslCli('gh', args)
         if (wslResolved) {
-          // Why: WSL-only Windows installs have no gh.exe on the host PATH, but
-          // global calls like rate_limit/auth do not carry a repo cwd to route by.
+          // Why: WSL-only Windows installs have no host gh.exe, and global calls (rate_limit/auth) carry no cwd to route by.
           resolved = wslResolved
           attemptedDefaultWslFallback = true
           attempt = -1
@@ -1432,22 +1317,10 @@ export async function ghExecFileAsync(
         continue
       }
       const isLastAttempt = attempt >= GH_RETRY_DELAYS_MS.length
-      // Why: only retry idempotent calls. A 5xx/socket reset can arrive
-      // after the server already applied a POST/PATCH/PUT/DELETE; retrying
-      // would duplicate the write (e.g. double-post a comment, double-add
-      // a label). When the caller doesn't say, we auto-detect from argv —
-      // explicit `-X <method>` and GraphQL `query=mutation …` are treated
-      // as non-idempotent. See bug-scan finding 1.
+      // Why: only retry idempotent calls; a transient error can arrive after a write already applied, so retrying would duplicate it.
       const idempotent = options.idempotent ?? argsLookIdempotent(args)
       if (idempotent && !isLastAttempt && isTransientGhError(stderr)) {
-        // Why: when the upstream surfaced a Retry-After (e.g. on a transient
-        // 5xx that GitHub explicitly recommends backing off for), honor it
-        // instead of using our default backoff — sleeping less than the
-        // server suggests just earns another failure and burns our retry
-        // budget. Cap at GH_RETRY_AFTER_MAX_MS so a pathologically large
-        // hint can't block IPC for minutes; if the real wait is longer, the
-        // attempt will fail again and the error will propagate to the UI
-        // where the user can see it.
+        // Why: honor the server's Retry-After over our backoff (a shorter sleep just re-fails); cap so a huge hint can't stall IPC.
         const retryAfterMs = parseRetryAfterMs(stderr)
         const delayMs =
           retryAfterMs !== null
@@ -1464,13 +1337,7 @@ export async function ghExecFileAsync(
 }
 
 // ─── glab CLI runner ────────────────────────────────────────────────
-// Why: parallel to gh CLI runner above. GitLab support is added by
-// cloning gh's surface rather than abstracting both behind a generic
-// runner — keeping them as parallel implementations matches the
-// project's clone-and-adapt approach for new providers and avoids
-// touching the working gh path. Reuses the shared retry/transient
-// helpers since HTTP-status- and TCP-error-based classification is
-// provider-agnostic.
+// Why: cloned from the gh runner rather than abstracted behind a generic runner, to avoid touching the working gh path.
 
 type GlabExecOptions = Omit<GitExecOptions, 'cwd'> & {
   cwd?: string
@@ -1479,21 +1346,9 @@ type GlabExecOptions = Omit<GitExecOptions, 'cwd'> & {
   allowDefaultWslFallback?: boolean
 }
 
+/** Async glab CLI execution; drop-in for execFileAsync('glab', …). Retry policy mirrors ghExecFileAsync. */
 /**
- * Async glab CLI execution. Drop-in replacement for
- * `execFileAsync('glab', args, { cwd, encoding, ... })`.
- *
- * Retry policy mirrors ghExecFileAsync.
- */
-/**
- * glab's `--hostname` flag rejects a host that carries a port
- * ("error parsing --hostname: invalid hostname"). A self-hosted GitLab on a
- * non-default port (e.g. `gitlab.example.com:8443`) must instead be selected
- * via the `GITLAB_HOST` env var, which accepts `host:port`. Translate any
- * `--hostname host:port` pair into `GITLAB_HOST` so every call site (`api`,
- * `auth status`, …) works against ported self-hosted instances. Port-less
- * `--hostname` values are left untouched.
- *
+ * glab's `--hostname` rejects host:port, so a ported self-hosted GitLab must use the GITLAB_HOST env var instead — translate it.
  * @internal exported for tests.
  */
 export function redirectPortedHostnameToEnv(
@@ -1555,9 +1410,7 @@ export async function glabExecFileAsync(
         }
       }
       const isLastAttempt = attempt >= GH_RETRY_DELAYS_MS.length
-      // Why: mirror gh's write-safety gate. A transient error after GitLab
-      // applies a POST/PATCH/PUT/DELETE must not create duplicate comments,
-      // issues, or merge actions through an automatic retry.
+      // Why: mirror gh's write-safety gate — don't auto-retry a non-idempotent write that GitLab may already have applied.
       const idempotent = options.idempotent ?? argsLookIdempotent(args)
       if (idempotent && !isLastAttempt && isTransientGhError(stderr)) {
         const retryAfterMs = parseRetryAfterMs(stderr)
@@ -1602,10 +1455,7 @@ export function wslAwareSpawn(
 
 /**
  * Translate absolute Linux paths in git output back to Windows UNC paths.
- *
- * Why: when git runs inside WSL, paths in output (e.g. `git worktree list`)
- * are Linux-native (/home/user/repo). The rest of Orca needs Windows UNC
- * paths (\\wsl.localhost\Ubuntu\home\user\repo) to read files via Node fs.
+ * Why: git-in-WSL emits Linux-native paths, but Orca reads files via Node fs, which needs Windows UNC.
  */
 export function translateWslOutputPaths(
   output: string,
@@ -1618,15 +1468,11 @@ export function translateWslOutputPaths(
     return output
   }
 
-  // Replace absolute Linux paths that start with / and look like filesystem
-  // paths in structured git output (e.g. "worktree /home/user/repo/feature")
+  // Rewrite absolute Linux paths in structured git output (e.g. "worktree /home/user/repo/feature") to Windows UNC.
   return output.replace(/(?<=worktree )(\/.+)$/gm, (_match, linuxPath: string) =>
     toWindowsWslPath(linuxPath, distro)
   )
 }
 
-/**
- * Get the WSL info for a path, if applicable. Convenience re-export so
- * consumers don't need to import from wsl.ts directly.
- */
+/** Convenience re-export of wsl.ts path helpers so consumers don't import it directly. */
 export { parseWslPath, toLinuxPath, toWindowsWslPath, isWslPath } from '../wsl'
diff --git a/src/main/git/status.ts b/src/main/git/status.ts
index ae818b52567..d325003fd2b 100644
--- a/src/main/git/status.ts
+++ b/src/main/git/status.ts
@@ -75,12 +75,7 @@ type SubmodulePathsCacheEntry = { paths: string[]; expiresAt: number }
 const submodulePathsCache = new Map<string, SubmodulePathsCacheEntry>()
 let submodulePathsCacheGeneration = 0
 
-// Why: the effective-upstream resolution chain (symbolic-ref + rev-parse ×2-3
-// + config snapshot) costs 4-5 subprocess spawns and only changes when branch
-// or git config changes. Ahead/behind is a pure function of the two rev-list
-// endpoints, so a recently-resolved name can be revalidated with one rev-list
-// spawn per poll tick; a failed rev-list (deleted ref) falls back to a full
-// re-resolve. Issue #7576: this path dominated idle main-process spawn churn.
+// Why: cache the upstream name to skip its 4-5-spawn resolution chain each poll; revalidate via one rev-list (issue #7576).
 const RESOLVED_UPSTREAM_NAME_CACHE_TTL_MS = 60_000
 
 type ResolvedUpstreamNameCacheEntry = {
@@ -97,9 +92,7 @@ const gitDiffReadDedupe = new InFlightPromiseDedupe<GitDiffResult>()
 const effectiveUpstreamStatusWriteGeneration = new Map<string, number>()
 const statusReadsInFlight = new Map<string, Promise<GitStatusResult>>()
 
-// Why: a mutation invalidates both in-flight diff reads and in-flight status
-// coalescing; clearing only the diff dedupe would let a post-mutation
-// getStatus() join a pre-mutation read and return stale entries.
+// Why: clear both diff and status in-flight caches; clearing only diff would let getStatus() join a pre-mutation read.
 export function invalidateGitReadCaches(): void {
   gitDiffReadDedupe.clear()
   statusReadsInFlight.clear()
@@ -113,8 +106,7 @@ export async function runWithGitReadCacheInvalidation<T>(run: () => Promise<T>):
   try {
     return await run()
   } finally {
-    // Why: a read that started during the mutation can be stale too, so the
-    // post-mutation boundary retires both pre-existing and overlapping reads.
+    // Why: a read that started mid-mutation can be stale too, so invalidate again after.
     invalidateGitReadCaches()
   }
 }
@@ -125,8 +117,7 @@ export function clearSubmodulePathsCacheForTests(): void {
 
 function clearSubmodulePathsCache(): void {
   submodulePathsCache.clear()
-  // Why: a pre-mutation .gitmodules read must not repopulate the cache after
-  // the mutation invalidated it.
+  // Why: bump the generation so a pre-mutation read can't repopulate the invalidated cache.
   submodulePathsCacheGeneration += 1
 }
 
@@ -139,8 +130,7 @@ function gitRuntimeOptionsKey(options: GitRuntimeOptions): readonly unknown[] {
 }
 
 function getSubmodulePathsCacheKey(worktreePath: string, options: GitRuntimeOptions): string {
-  // Why: the same path string can refer to different filesystem views across
-  // WSL distros, so the `.gitmodules` cache must follow runtime routing.
+  // Why: the same path can map to different WSL-distro filesystems, so key the cache by runtime routing.
   return [worktreePath, ...gitRuntimeOptionsKey(options)].join('\0')
 }
 
@@ -182,8 +172,7 @@ function rememberSubmodulePaths(cacheKey: string, paths: string[], now: number):
   trimSubmodulePathsCache()
 }
 
-// Why: status tests reuse this reset hook, so every cross-call memoization layer
-// must reset together even though the historical name mentions upstream only.
+// Why: tests reuse this hook, so every memoization layer resets together despite the upstream-only name.
 export function clearEffectiveUpstreamStatusCacheForTests(): void {
   effectiveUpstreamStatusCache.clear()
   effectiveUpstreamStatusInFlight.clear()
@@ -222,8 +211,7 @@ export async function getStatus(
   if (options.signal) {
     return runGetStatus(worktreePath, options)
   }
-  // Why: dedupe only concurrent identical reads; after settle, callers must
-  // execute a fresh status read rather than observing a cached result.
+  // Why: dedupe only concurrent identical reads; after settle, callers must run a fresh read.
   const cacheKey = getStatusReadKey(worktreePath, options)
   const inFlightStatus = statusReadsInFlight.get(cacheKey)
   if (inFlightStatus) {
@@ -265,21 +253,15 @@ async function runGetStatus(
   const lineStatsWriteToken = beginGitStatusLineStatsCacheWrite(lineStatsCacheKey)
   let effectiveUpstreamStatus: GitUpstreamStatus | undefined
   let statusSucceeded = false
-  // Why: a negative/fractional/NaN limit would trigger spurious early-stop or
-  // inconsistent truncation; fall back to the default unless it's a valid
-  // non-negative integer (0 explicitly disables the cap).
+  // Why: a bad limit (negative/fractional/NaN) breaks early-stop; require a valid non-negative int (0 disables the cap).
   const limit =
     typeof options.limit === 'number' && Number.isInteger(options.limit) && options.limit >= 0
       ? options.limit
       : DEFAULT_GIT_STATUS_LIMIT
 
-  // Why: detectConflictOperation (4 existsSync + readFile) and git status are
-  // independent. Running them concurrently saves one round-trip of I/O latency.
+  // Why: detectConflictOperation and git status are independent, so run them concurrently to save I/O latency.
   const conflictPromise = detectConflictOperation(worktreePath)
-  // Why: -c core.quotePath=false keeps non-ASCII filenames (Japanese, emoji,
-  // etc.) as raw UTF-8 instead of git's default C-style octal escapes wrapped
-  // in double quotes. Without it, the parsed entry.path is unreadable in the
-  // sidebar and downstream `git show :"docs/\346..."` lookups silently miss.
+  // Why: core.quotePath=false keeps non-ASCII paths as raw UTF-8, not octal escapes, so entry.path is readable and lookups match.
   const statusArgs = [
     '-c',
     'core.quotePath=false',
@@ -292,9 +274,7 @@ async function runGetStatus(
     statusArgs.push('--ignored=matching')
   }
 
-  // Why: stream + parse incrementally and stop git the moment the entry count
-  // crosses `limit`, so a repo with an enormous un-ignored folder never buffers
-  // a status listing big enough to crash the process. See StatusPorcelainParser.
+  // Why: stream + parse and stop at `limit` so a huge un-ignored folder can't buffer enough to crash the process.
   const parser = new StatusPorcelainParser()
   let didHitLimit = false
   const conflictOperation = await conflictPromise
@@ -303,8 +283,7 @@ async function runGetStatus(
     const { stoppedEarly } = await gitStreamStdout(statusArgs, {
       cwd: worktreePath,
       wslDistro: options.wslDistro,
-      // Why: status polling is read-like; avoid refreshing the index and racing
-      // terminal Git commands on `.git/worktrees/*/index.lock`.
+      // Why: status polling is read-like; disable optional locks to avoid racing terminal Git on index.lock.
       env: gitOptionalLocksDisabledEnv(),
       signal: options.signal,
       onStdout: (chunk) => parser.update(chunk, limit)
@@ -315,22 +294,18 @@ async function runGetStatus(
     didHitLimit = stoppedEarly
     statusSucceeded = true
   } catch (error) {
-    // Why: an aborted scan must reject, not resolve — swallowing here would let
-    // a cancelled request be mistaken for a completed (empty) status result.
+    // Why: an aborted scan must reject, not resolve as an empty result.
     if (options.signal?.aborted) {
       throw error
     }
     // Not a git repo or git not available
   }
 
-  // Why: the parser stops one entry past the limit (it checks after pushing), so
-  // trim back to exactly `limit` for a stable "first N shown" contract.
+  // Why: the parser overshoots by one (checks after pushing), so trim to exactly `limit`.
   const entries = didHitLimit ? parser.entries.slice(0, limit) : parser.entries
   const { head, branch, upstreamName, upstreamAheadBehind } = parser.branch
 
-  // Why: unmerged (`u`) records need async per-file git lookups, so the parser
-  // collected their raw lines; resolve them now. Conflicts are rare and never
-  // the source of huge output, so this stays off the streamed hot path.
+  // Why: unmerged (`u`) records need async per-file lookups; resolve them off the hot path (conflicts are rare).
   if (!didHitLimit) {
     for (const line of parser.unmergedLines) {
       const unmergedEntry = await parseUnmergedEntry(worktreePath, line)
@@ -350,11 +325,7 @@ async function runGetStatus(
         options
       )
       try {
-        // Why: the probe promise and its name/negative caches are shared by
-        // concurrent status reads, so one caller's abort must not reject the
-        // shared probe or evict warm cache state for the others. The probe is
-        // small and its cached result stays useful, so run it unbound from
-        // this request's signal.
+        // Why: the shared probe/caches serve concurrent reads, so run it unbound from this signal — one abort mustn't reject it for others.
         const { signal: _requestSignal, ...sharedProbeOptions } = options
         effectiveUpstreamStatus = await readOrProbeEffectiveUpstreamStatus(
           cacheKey,
@@ -364,18 +335,12 @@ async function runGetStatus(
           options.bypassEffectiveUpstreamNegativeCache === true
         )
       } catch {
-        // Why: git status polling should not fail just because the richer
-        // upstream probe hit a transient ref/read error; the explicit
-        // upstream-status path will surface those failures when invoked.
+        // Why: don't fail status polling on a transient upstream-probe error; the explicit upstream path surfaces those.
       }
     }
   }
 
-  // Why: attach per-area line counts for the sidebar. Diffs run after status
-  // (we need the entry list first) and only for areas that have entries, so a
-  // clean tree costs zero extra git calls. Skipped when the limit was hit —
-  // running numstat over a huge change set would reintroduce the cost the limit
-  // exists to avoid, matching how a "huge" repo disables extra git features.
+  // Why: line counts run only for areas with entries (clean tree = 0 calls); skip past the limit to avoid numstat over a huge set.
   if (!didHitLimit) {
     await reuseOrRecomputeGitStatusLineStats({
       cacheKey: lineStatsCacheKey,
@@ -390,8 +355,7 @@ async function runGetStatus(
     clearGitStatusLineStatsCacheKey(lineStatsCacheKey, lineStatsWriteToken)
   }
 
-  // Why: abort after the stream (e.g. during unmerged/upstream/line-stats work)
-  // must still reject — never resolve a cancelled scan as a completed result.
+  // Why: an abort after the stream (unmerged/upstream/line-stats work) must still reject, not resolve.
   if (options.signal?.aborted) {
     const error = new Error('The operation was aborted.')
     error.name = 'AbortError'
@@ -423,15 +387,13 @@ async function runGetStatus(
 }
 
 function getStatusLineStatsCacheKey(worktreePath: string, options: GitRuntimeOptions = {}): string {
-  // Why: identical path strings can address different Linux filesystems in
-  // different WSL distros, so derived stats must follow Git's execution host.
+  // Why: identical paths can map to different WSL-distro filesystems, so key stats by Git's execution host.
   return `${options.wslDistro ?? 'native'}\0${worktreePath}`
 }
 
 /**
  * Resolve a submodule's own worktree path from a parent worktree + relative
- * submodule path, rejecting anything that escapes the parent. Shared by the
- * on-demand submodule status query and the submodule-aware diff router.
+ * submodule path, rejecting anything that escapes the parent.
  */
 export function resolveSubmoduleWorktreePath(worktreePath: string, submodulePath: string): string {
   if (!submodulePath || submodulePath.includes('\0') || path.isAbsolute(submodulePath)) {
@@ -446,11 +408,8 @@ export function resolveSubmoduleWorktreePath(worktreePath: string, submodulePath
 }
 
 /**
- * Run a plain status inside a submodule's own worktree. Used by the lazy
- * "expand submodule" flow — the parent status only reports a single gitlink
- * row, so the inner per-file changes are fetched on demand here. Entry paths
- * are relative to the submodule root; the renderer prefixes them with the
- * submodule path.
+ * Run a plain status inside a submodule's own worktree (lazy "expand submodule"
+ * flow). Entry paths are relative to the submodule root; the renderer prefixes them.
  */
 export async function getSubmoduleStatus(
   worktreePath: string,
@@ -459,9 +418,7 @@ export async function getSubmoduleStatus(
 ): Promise<GitStatusResult> {
   const submoduleWorktreePath = resolveSubmoduleWorktreePath(worktreePath, submodulePath)
   const workingResult = await getStatus(submoduleWorktreePath, options)
-  // Why: a moved gitlink (clean worktree) has no uncommitted status rows; its
-  // real changes live between the parent-recorded commit and the checked-out
-  // commit. Surface those as inner rows so the expansion isn't empty.
+  // Why: a moved gitlink (clean worktree) has no status rows; surface the parent-commit→checkout range as inner rows.
   const fromOid = options.staged
     ? await readGitlinkOidFromTree(worktreePath, 'HEAD', submodulePath, options)
     : (await readGitlinkOidFromIndex(worktreePath, submodulePath, options)) ||
@@ -494,9 +451,8 @@ export async function getSubmoduleStatus(
 }
 
 /**
- * List files changed between two submodule commits as status rows. Used when a
- * gitlink pointer moved so the expanded submodule shows the committed file
- * changes (each row diffs the file across the two commits).
+ * List files changed between two submodule commits as status rows — used when a
+ * gitlink pointer moved so the expanded submodule shows committed changes.
  */
 async function computeSubmoduleRangeEntries(
   submoduleWorktreePath: string,
@@ -567,15 +523,11 @@ async function runNumstat(
     )
     return parseNumstat(stdout)
   } catch (error) {
-    // Why: an aborted pass must reject so a cancelled scan is never treated as
-    // a completed one; only a genuine (non-abort) numstat failure degrades to
-    // uncounted rows below.
+    // Why: an aborted pass must reject; only a genuine numstat failure degrades to uncounted rows.
     if (options.signal?.aborted) {
       throw error
     }
-    // Why: a numstat failure (e.g. transient lock) should leave rows without
-    // counts rather than break the whole status refresh. Null (vs an empty
-    // map) tells the caller the pass is incomplete and must not be cached.
+    // Why: a numstat failure leaves rows uncounted; null (not empty map) flags the pass incomplete and uncacheable.
     return null
   }
 }
@@ -708,8 +660,7 @@ function rememberEffectiveUpstreamStatus(
   probedSameNameOriginRef: boolean,
   writeGeneration: number
 ): void {
-  // Why: hasConfiguredPushTarget gates a write action. Re-probe it each poll
-  // rather than keeping a stale positive target after branch config changes.
+  // Why: hasConfiguredPushTarget gates a write action; re-probe each poll rather than cache a stale positive.
   if (status.hasUpstream || status.hasConfiguredPushTarget) {
     effectiveUpstreamStatusCache.delete(cacheKey)
     effectiveUpstreamStatusWriteGeneration.set(cacheKey, writeGeneration + 1)
@@ -722,8 +673,7 @@ function rememberEffectiveUpstreamStatus(
   if (!probedSameNameOriginRef) {
     return
   }
-  // Why: a stable no-upstream branch should not spawn failed git probes every
-  // source-control poll, but remote refs can appear after push/fetch.
+  // Why: cache the negative so a stable no-upstream branch doesn't re-probe every poll (TTL lets push/fetch refs appear).
   effectiveUpstreamStatusCache.set(cacheKey, {
     status,
     expiresAt: now + EFFECTIVE_UPSTREAM_NEGATIVE_CACHE_TTL_MS
@@ -758,8 +708,7 @@ async function readOrProbeEffectiveUpstreamStatus(
     }
   }
 
-  // Why: source-control mount and root git refresh can overlap during startup.
-  // Coalesce the richer upstream probe so a stable missing ref fails once.
+  // Why: overlapping refreshes at startup — coalesce the upstream probe so a stable missing ref fails once.
   const writeGeneration = effectiveUpstreamStatusWriteGeneration.get(cacheKey) ?? 0
   const probe = probeOrRevalidateEffectiveUpstreamStatus(
     cacheKey,
@@ -809,8 +758,7 @@ async function probeOrRevalidateEffectiveUpstreamStatus(
       )
       return { status, probedSameNameOriginRef: false }
     } catch (error) {
-      // Why: an aborted probe says nothing about the ref; evicting the warm
-      // name cache here would force a pointless full re-resolve next scan.
+      // Why: an aborted probe says nothing about the ref; don't evict the warm name cache.
       if (options.signal?.aborted) {
         throw error
       }
@@ -889,12 +837,7 @@ async function parseUnmergedEntry(
   worktreePath: string,
   line: string
 ): Promise<GitStatusEntry | null> {
-  // Why: porcelain v2 unmerged entries are fully space-separated (like type-1
-  // ordinary entries), NOT tab-separated. The format is:
-  //   u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
-  // The path starts at field index 10 and may contain spaces, so we join the
-  // remaining fields. The earlier tab-based parsing silently dropped all
-  // unmerged entries because the tab was never present.
+  // Why: porcelain v2 `u` records are space-separated (not tab); path is field 10+ and may contain spaces, so join the tail.
   const parts = line.split(' ')
   const xy = parts[1]
   const modeStage1 = parts[3]
@@ -905,9 +848,7 @@ async function parseUnmergedEntry(
     return null
   }
 
-  // Why: submodule conflicts (mode 160000) are out of scope for v1.
-  // Presenting them with normal file-conflict UX would be misleading because
-  // submodule resolution requires different Git commands and user mental model.
+  // Why: submodule conflicts (mode 160000) are out of scope for v1 — they need different resolution UX.
   if ([modeStage1, modeStage2, modeStage3].some((mode) => mode === '160000')) {
     return null
   }
@@ -917,9 +858,7 @@ async function parseUnmergedEntry(
     return null
   }
 
-  // Why: porcelain v2 `u` records do not provide rename-origin metadata (unlike
-  // `2` records), so oldPath is intentionally omitted. v1 should not promise
-  // rename ancestry in conflict rows without a separate Git query.
+  // Why: porcelain v2 `u` records lack rename-origin metadata, so oldPath is intentionally omitted.
   return {
     path: filePath,
     area: 'unstaged',
@@ -950,16 +889,8 @@ function parseConflictKind(xy: string): GitConflictKind | null {
   }
 }
 
-// Why: the `status` field on conflict entries is a *rendering compatibility*
-// choice for existing icon/color plumbing, not a semantic claim about the file.
-// The conflict badge and subtype carry the real meaning. We use 'modified' when
-// a working-tree file exists and 'deleted' when it does not, so that downstream
-// consumers (file explorer decorations, tab badges) get a reasonable fallback
-// without needing conflict-aware upgrades in v1.
-//
-// For `deleted_by_us` / `deleted_by_them` and the `added_by_*` variants, Git's
-// behavior depends on the merge strategy, so we check the filesystem rather
-// than hardcoding an assumption.
+// Why: `status` here is a rendering-compat choice for icon/color plumbing, not semantic; the conflict badge carries the real meaning.
+// Why: for deleted_by_*/added_by_* variants Git's result depends on merge strategy, so check the filesystem.
 async function getConflictCompatibilityStatus(
   worktreePath: string,
   filePath: string,
@@ -976,25 +907,13 @@ async function getConflictCompatibilityStatus(
   try {
     return existsSync(path.join(worktreePath, filePath)) ? 'modified' : 'deleted'
   } catch {
-    // Why: if the filesystem check throws (permissions error, unmounted path,
-    // etc.), 'modified' is the safer fallback. It avoids suppressing the row
-    // from the sidebar and avoids a misleading 'deleted' when we simply could
-    // not check. The conflict badge still carries the real semantics.
+    // Why: on an fs check failure, 'modified' is safer — it keeps the row visible rather than falsely showing 'deleted'.
     return 'modified'
   }
 }
 
-// Why: there is an inherent race between the `git status` call and these
-// fs.existsSync checks — the HEAD file may not yet exist or may already be
-// cleaned up by the time we check. In that case we fall back to 'unknown' for
-// one poll cycle, which is acceptable. The renderer uses this to label the
-// merge summary ("Merge conflicts" vs "Rebase conflicts" vs generic "Conflicts").
-//
-// Why rebase detection relies on rebase-merge/ or rebase-apply/ directories
-// instead of REBASE_HEAD: those directories persist for the entire rebase, so
-// they cover both conflicting and non-conflicting steps. REBASE_HEAD, by
-// contrast, only exists on some steps and can also be left behind after a
-// completed rebase, which would make the UI show a stale "Rebasing" badge.
+// Why: the git-status → existsSync race can miss a transient HEAD; fall back to 'unknown' for one poll cycle.
+// Why: detect rebase from rebase-merge/ or rebase-apply/ dirs (persist all steps), not REBASE_HEAD (partial, lingers → stale badge).
 export async function detectConflictOperation(worktreePath: string): Promise<GitConflictOperation> {
   const gitDir = await resolveGitDir(worktreePath)
   const mergeHead = path.join(gitDir, 'MERGE_HEAD')
@@ -1061,9 +980,8 @@ export async function resolveGitDir(worktreePath: string): Promise<string> {
 }
 
 /**
- * List configured submodule paths (relative, forward-slash) for a worktree,
- * cached briefly. Read from `.gitmodules` so a single diff click doesn't pay
- * for an index-wide `ls-files` scan. Used to route gitlink/inner diffs.
+ * List configured submodule paths (relative, forward-slash) for a worktree, cached
+ * briefly. Read from `.gitmodules` to avoid an index-wide `ls-files` scan.
  */
 export async function listSubmodulePaths(
   worktreePath: string,
@@ -1075,8 +993,7 @@ export async function listSubmodulePaths(
   if (cached) {
     return cached
   }
-  // Why: prune on misses so removed worktrees do not accumulate while hot
-  // cache hits stay O(1).
+  // Why: prune on misses so removed worktrees don't accumulate; hot hits stay O(1).
   pruneExpiredSubmodulePathsCache(now)
   const cacheGeneration = submodulePathsCacheGeneration
   let paths: string[] = []
@@ -1174,9 +1091,8 @@ async function readWorkingSubmoduleHead(
 }
 
 /**
- * Synthesize a gitlink pointer diff. Git represents submodule commit changes as
- * a one-line `Subproject commit <oid>` swap, so feeding the old/new oids through
- * the normal text differ matches git's own rendering.
+ * Synthesize a gitlink pointer diff: Git represents submodule commit changes as a
+ * one-line `Subproject commit <oid>` swap, so the old/new oids feed the text differ.
  */
 async function buildSubmodulePointerDiff(
   worktreePath: string,
@@ -1184,8 +1100,7 @@ async function buildSubmodulePointerDiff(
   staged: boolean,
   compareAgainstHead: boolean,
   options: GitRuntimeOptions,
-  // Why: default to the validated resolver so every caller (not just loadDiff)
-  // is protected from a .gitmodules path escaping the parent worktree.
+  // Why: default to the validated resolver so every caller is guarded against path escape.
   submoduleWorktreePath = resolveSubmoduleWorktreePath(worktreePath, submodulePath)
 ): Promise<GitDiffResult> {
   let leftOid = ''
@@ -1212,9 +1127,8 @@ async function buildSubmodulePointerDiff(
 }
 
 /**
- * Diff a file inside a submodule across two of its commits. Used when the parent
- * gitlink moved but the submodule worktree is clean — the change is committed,
- * so compare the recorded commit's blob against the checked-out commit's blob.
+ * Diff a file inside a submodule across two of its commits — used when the parent
+ * gitlink moved but the submodule worktree is clean (change is committed).
  */
 async function buildSubmoduleInnerCommitRangeDiff(
   submoduleWorktreePath: string,
@@ -1256,8 +1170,7 @@ export async function getDiff(
   compareAgainstHead = false,
   options: GitRuntimeOptions = {}
 ): Promise<GitDiffResult> {
-  // Why: register the in-flight dedupe synchronously (before any await) so
-  // concurrent identical reads coalesce; submodule routing happens inside.
+  // Why: register the dedupe synchronously (before any await) so concurrent identical reads coalesce.
   return gitDiffReadDedupe.run(
     stableInFlightKey([
       'diff',
@@ -1278,17 +1191,12 @@ async function loadDiff(
   compareAgainstHead: boolean,
   options: GitRuntimeOptions
 ): Promise<GitDiffResult> {
-  // Why: gitlink paths can't be read as blobs (`git show HEAD:<sub>` is a "bad
-  // object") and a submodule working dir reads as empty, so route submodule
-  // diffs explicitly: the gitlink root → pointer diff, inner files → recurse
-  // into the submodule's own worktree.
+  // Why: gitlink paths can't be read as blobs, so route submodule diffs explicitly (root → pointer, inner → recurse).
   const submodulePaths = await listSubmodulePaths(worktreePath, options)
   if (submodulePaths.length > 0) {
     const matchedSubmodule = findContainingSubmodule(submodulePaths, filePath)
     if (matchedSubmodule) {
-      // Why: matchedSubmodule originates from .gitmodules, so validate it against
-      // the worktree boundary before any inner read — a crafted submodule path
-      // must not let the diff escape the selected repo.
+      // Why: validate the .gitmodules-derived path against the worktree boundary so a crafted one can't escape the repo.
       const submoduleWorktreePath = resolveSubmoduleWorktreePath(worktreePath, matchedSubmodule)
       const normalizedFilePath = filePath.replace(/\\/g, '/').replace(/\/+$/, '')
       if (normalizedFilePath === matchedSubmodule) {
@@ -1309,9 +1217,7 @@ async function loadDiff(
       const toOid = staged
         ? await readGitlinkOidFromIndex(worktreePath, matchedSubmodule, options)
         : await readWorkingSubmoduleHead(submoduleWorktreePath, options)
-      // Why: when the gitlink moved but the submodule worktree is clean, the
-      // file's change lives in committed history — diff the two commits. Only
-      // fall back to the working-tree blob read when the commit didn't move.
+      // Why: a moved gitlink with a clean submodule worktree means the change is committed — diff the two commits.
       if (fromOid && toOid && fromOid !== toOid) {
         return buildSubmoduleInnerCommitRangeDiff(
           submoduleWorktreePath,
@@ -1362,8 +1268,7 @@ async function loadDiff(
     modifiedIsBinary,
     filePath
   )
-  // Why: mark a proven deletion so previewers can fall back to the original bytes
-  // without mistaking a read failure's empty modified side for a deletion.
+  // Why: mark a proven deletion so previewers don't mistake a read failure's empty side for one.
   if (result.kind === 'binary' && modifiedDeleted) {
     return { ...result, modifiedDeleted: true }
   }
@@ -1387,8 +1292,7 @@ export async function getBranchCompare(
 
   const compareRef = await resolveCompareRef(worktreePath, options)
   summary.compareRef = compareRef
-  // Why: short remote display refs like "origin/main" can collide with a local
-  // branch of the same name. Compare against the proven remote-tracking ref.
+  // Why: short refs like "origin/main" can collide with a local branch; use the proven remote-tracking ref.
   const resolvedBaseRef = await resolveWorktreeAddBaseRef(baseRef, (qualifiedRef) =>
     hasWorktreeBaseCommitRef(worktreePath, qualifiedRef, options)
   )
@@ -1402,16 +1306,13 @@ export async function getBranchCompare(
     try {
       baseOid = await resolveRefOid(worktreePath, resolvedBaseRef, options)
       summary.baseOid = baseOid
-      // Why: new remote worktrees can be on an unborn branch until the first
-      // commit. There are no committed branch changes yet; surfacing this as a
-      // compare error makes the source-control panel look broken.
+      // Why: an unborn branch (new remote worktree) has no changes yet; a compare error would look broken.
       summary.changedFiles = 0
       summary.commitsAhead = 0
       summary.status = 'ready'
       return { summary, entries: [] }
     } catch {
-      // Preserve the existing unborn-head message when even the base is not
-      // resolvable; callers cannot compare or present a useful empty state.
+      // Preserve the unborn-head message when even the base is unresolvable.
     }
     summary.status = 'unborn-head'
     summary.errorMessage =
@@ -1637,14 +1538,12 @@ async function loadBranchChanges(
   headOid: string,
   options: GitRuntimeOptions = {}
 ): Promise<GitBranchChangeEntry[]> {
-  // Why: see core.quotePath=false rationale in getStatus — same reason here so
-  // branch-diff entries render with their real UTF-8 paths.
+  // Why: core.quotePath=false keeps real UTF-8 paths — see getStatus rationale.
   const gitOptions = {
     ...gitOptionsForWorktree(worktreePath, options),
     maxBuffer: MAX_GIT_SHOW_BYTES
   }
-  // Why: both diffs walk the same range and are independent, so start them
-  // together instead of serializing two potentially large git operations.
+  // Why: both diffs are independent, so run them concurrently instead of serializing.
   const [{ stdout }, { stdout: numstat }] = await Promise.all([
     gitExecFileAsync(
       ['-c', 'core.quotePath=false', 'diff', '--name-status', '-M', '-C', mergeBase, headOid],
@@ -1658,8 +1557,7 @@ async function loadBranchChanges(
   const statsByPath = parseNumstat(numstat)
 
   const entries: GitBranchChangeEntry[] = []
-  // [Fix]: Split by /\r?\n/ instead of '\n' to handle Git CRLF output on Windows,
-  // preventing trailing \r characters in extracted file paths.
+  // Why: split on /\r?\n/ so Git's CRLF output on Windows leaves no trailing \r in paths.
   for (const line of stdout.split(/\r?\n/)) {
     if (!line) {
       continue
@@ -1678,8 +1576,7 @@ async function loadCommitChanges(
   commitOid: string,
   options: GitRuntimeOptions = {}
 ): Promise<GitBranchChangeEntry[]> {
-  // Why: root commits have no parent tree; diff-tree --root asks git to
-  // compare against the repository's empty tree without hardcoding hash format.
+  // Why: root commits have no parent tree; diff-tree --root uses git's empty tree, avoiding a hardcoded hash-format-specific oid.
   const args = parentOid
     ? ['-c', 'core.quotePath=false', 'diff', '--name-status', '-M', '-C', parentOid, commitOid]
     : [
@@ -1713,8 +1610,7 @@ async function loadCommitChanges(
     ...gitOptionsForWorktree(worktreePath, options),
     maxBuffer: MAX_GIT_SHOW_BYTES
   }
-  // Why: commit diff rows need metadata and line counts, but those git queries
-  // do not depend on each other.
+  // Why: the two git queries are independent, so run them in parallel.
   const [{ stdout }, { stdout: numstat }] = await Promise.all([
     gitExecFileAsync(args, gitOptions),
     gitExecFileAsync(numstatArgs, gitOptions)
@@ -1872,9 +1768,7 @@ async function readWorkingTreeFile(filePath: string): Promise<GitBlobReadResult>
   try {
     fileStat = await stat(filePath)
   } catch (error) {
-    // Why: ENOENT means the working-tree file is genuinely gone (a deletion);
-    // any other stat error is a read failure, which must not be reported as an
-    // absence since callers fall back to the original bytes only for deletions.
+    // Why: only ENOENT is a real deletion; other stat errors are read failures, not absence.
     return {
       content: '',
       isBinary: false,
@@ -1885,8 +1779,7 @@ async function readWorkingTreeFile(filePath: string): Promise<GitBlobReadResult>
     return { content: '', isBinary: false, exists: false }
   }
   if (fileStat.size > MAX_GIT_SHOW_BYTES) {
-    // Why: git blob reads are capped through maxBuffer; mirror that bound for
-    // unstaged working-tree content before readFile can pull in huge assets.
+    // Why: mirror git's maxBuffer cap for working-tree reads so readFile can't pull in huge assets.
     return { content: '', isBinary: true, exists: true }
   }
   try {
@@ -1932,15 +1825,12 @@ function buildDiffResult(
       modifiedContent,
       originalIsBinary,
       modifiedIsBinary,
-      // Why: binary diff previews were originally image-only, so the renderer
-      // still checks `isImage` before showing a preview component. Preserve
-      // that legacy flag for PDFs until the wider contract is renamed.
+      // Why: renderer still checks legacy `isImage` before previewing, so set it for PDFs too until the contract is renamed.
       ...(mimeType ? { isImage: true, mimeType } : {})
     } as GitDiffResult
   }
 
-  // Why: if the diff exceeds safe render limits, avoid sending large text
-  // payloads and return metadata so the renderer can show fallback UI.
+  // Why: over the render limit, return metadata instead of huge text so the renderer can show fallback UI.
   const largeDiffRenderLimit = getLargeDiffRenderLimit({ originalContent, modifiedContent })
   if (largeDiffRenderLimit.limited) {
     return {
@@ -2049,9 +1939,7 @@ export async function getStagedCommitContext(
     if (!isMaxBufferOverflowError(error)) {
       throw error
     }
-    // Why: a very large staged diff overflows maxBuffer (ENOBUFS). The patch is
-    // optional context that gets truncated to STAGED_DIFF_BYTE_BUDGET anyway, so
-    // degrade to the file-name summary instead of failing commit-message generation.
+    // Why: staged patch is optional context (truncated later anyway); degrade to file-name summary rather than fail.
     console.warn(
       '[git] Staged patch too large to read; using file summary only:',
       describeMaxBufferOverflowError(error)
@@ -2075,9 +1963,7 @@ export async function commitChanges(
     await gitExecFileAsync(['commit', '-m', message], gitOptionsForWorktree(worktreePath, options))
     return { success: true }
   } catch (error) {
-    // Why: surface whichever channel carries the useful message. Pre-commit/GPG
-    // hook failures write to stderr; "nothing to commit, working tree clean"
-    // writes to stdout. Try stderr first, fall back to stdout, then error.message.
+    // Why: useful message may be on stderr (hook/GPG failures) or stdout ("nothing to commit"), so try both then message.
     const readStringField = (field: string): string | null => {
       if (typeof error === 'object' && error && field in error) {
         const v = (error as Record<string, unknown>)[field]
@@ -2149,8 +2035,7 @@ function normalizeGitPathForCompare(filePath: string): string {
 }
 
 function literalPathspec(filePath: string, options: GitRuntimeOptions): string {
-  // Why: Windows validation produces backslashes, but Git running inside WSL
-  // needs POSIX paths. Host paths stay untouched so POSIX filenames remain literal.
+  // Why: Git inside WSL needs POSIX paths, but host paths must stay literal, so convert backslashes only for WSL.
   const runtimePath = options.wslDistro ? filePath.replace(/\\/g, '/') : filePath
   return `:(literal)${runtimePath}`
 }
@@ -2177,8 +2062,7 @@ async function listTrackedPathSpecs(
         ...gitOptionsForWorktree(worktreePath, options)
       }
     )
-    // Why: a tracked directory can contain enough paths for push(...split)
-    // to exceed the JavaScript argument limit before discard decisions run.
+    // Why: a tracked directory can hold enough paths to exceed the JS argument limit.
     for (const trackedPath of stdout.split('\0')) {
       if (trackedPath) {
         trackedPaths.push(trackedPath)
diff --git a/src/main/git/worktree.ts b/src/main/git/worktree.ts
index 84ce3963192..92fb4437d77 100644
--- a/src/main/git/worktree.ts
+++ b/src/main/git/worktree.ts
@@ -84,10 +84,7 @@ const SPARSE_CHECKOUT_DETECTION_CONCURRENCY = 8
 
 const PRUNABLE_EXISTENCE_PROBE_CONCURRENCY = 8
 
-// Why: bound `git worktree add` so a OneDrive cloud-placeholder base path can't
-// stall its checkout writes for minutes (STA-1292) — a stuck create then fails
-// fast instead of spinning forever. Generous enough not to kill a legit large
-// checkout (mirrors the SYNC runner's cloud-placeholder floor, #7225).
+// Why: bound `git worktree add` so a OneDrive cloud-placeholder stall fails fast (STA-1292); generous enough for a legit large checkout (#7225).
 export const WORKTREE_ADD_TIMEOUT_MS = 180_000
 export const WORKTREE_REMOVAL_PREFLIGHT_TIMEOUT_MS = 30_000
 
@@ -155,9 +152,7 @@ function parseRemoteTrackingLocalBaseRef(
     return undefined
   }
 
-  // Why: Only refs proven to be remote-tracking refs get refresh status.
-  // Local branches can contain slashes (e.g. release/2026) and must not
-  // produce a fake "Local 2026 was not refreshed" warning.
+  // Why: only proven remote-tracking refs get refresh status; slash-containing local branches (release/2026) must not fake a "not refreshed" warning.
   const shortRemoteRef = remoteTrackingRef.slice(remoteRefPrefix.length)
   const slashIndex = shortRemoteRef.indexOf('/')
   if (slashIndex <= 0) {
@@ -196,9 +191,7 @@ async function evaluateLocalBaseRefRefreshability(
   let localOid = ''
   let remoteOid = ''
   try {
-    // Why: advisory and mutating paths must agree on "safe to fast-forward".
-    // `rev-list A...B` proves the local branch exists, has no local-only
-    // commits, and tells the toast whether it is actually behind.
+    // Why: advisory and mutating paths must agree on "safe to fast-forward"; `rev-list A...B` proves no local-only commits and how far behind.
     const { stdout } = await gitExecFileAsync(
       ['rev-list', '--left-right', '--count', `${parsed.fullRef}...${remoteTrackingRef}`],
       gitExecOptions(repoPath, options)
@@ -208,8 +201,7 @@ async function evaluateLocalBaseRefRefreshability(
       return { refreshable: false, result: { ...resultBase, status: 'skipped_not_fast_forward' } }
     }
     if (!shouldInspectOwner(parsedDrift.behind)) {
-      // Why: a current local ref cannot produce an update suggestion, so the
-      // advisory path need not resolve OIDs or inspect its owner worktree.
+      // Why: a current local ref yields no update suggestion, so the advisory path skips OID resolution and owner inspection.
       return undefined
     }
     const { stdout: localOidOutput } = await gitExecFileAsync(
@@ -238,8 +230,7 @@ async function evaluateLocalBaseRefRefreshability(
   }
 
   try {
-    // Why: if the local base branch is checked out anywhere, turning on the
-    // setting would only update it when that owner worktree is clean.
+    // Why: if the local base branch is checked out, only update it when that owner worktree is clean.
     const { stdout: worktreeListOutput } = await gitExecFileAsync(
       ['worktree', 'list', '--porcelain'],
       gitExecOptions(repoPath, options)
@@ -276,9 +267,7 @@ async function evaluateLocalBaseRefRefreshability(
       }
     }
 
-    // Why: localBranch isn't checked out anywhere, so there is no working tree
-    // to desync — a bare ref fast-forward (update-ref) is safe. Omitting
-    // ownerWorktreePath signals the mutating path to take that branch.
+    // Why: localBranch isn't checked out anywhere, so a bare-ref fast-forward is safe; omitting ownerWorktreePath signals the mutating path to take it.
     return {
       refreshable: true,
       ...resultBase,
@@ -332,8 +321,7 @@ async function persistWorktreeCreationBase(
   } catch (error) {
     console.warn(`addWorktree: failed to set ${configKey} for ${worktreePath}`, error)
     try {
-      // Why: reused branch names may carry stale base metadata; if replacement
-      // fails, remove the old value so consumers do not trust outdated lineage.
+      // Why: reused branch names may carry stale base metadata; if replacement fails, unset it so consumers don't trust stale lineage.
       await gitExecFileAsync(['config', '--local', '--unset-all', configKey], {
         ...gitExecOptions(worktreePath, options)
       })
@@ -356,8 +344,7 @@ async function unsetWorktreeCreationBase(
       ...gitExecOptions(worktreePath, options)
     })
   } catch {
-    // Best-effort cleanup; missing keys and locked config both leave the
-    // original sparse setup error as the actionable failure.
+    // Best-effort cleanup; leave the original sparse-setup error as the actionable failure.
   }
 }
 
@@ -383,8 +370,7 @@ function resolveRevParsePath(repoPath: string, value: string): string {
   if (posix.isAbsolute(value) || win32.isAbsolute(value)) {
     return value
   }
-  // Old git ignores `--path-format=absolute`, so a relative toplevel/git-dir
-  // must be resolved against the scanned repo path.
+  // Old git ignores `--path-format=absolute`, so resolve a relative toplevel/git-dir against the scanned repo path.
   return looksLikeWindowsPath(repoPath)
     ? win32.resolve(repoPath, value)
     : posix.resolve(repoPath, value)
@@ -393,11 +379,8 @@ function resolveRevParsePath(repoPath: string, value: string): string {
 type RepoLocation = { topLevel: string; commonDir: string }
 
 function parseRepoLocation(repoPath: string, output: string): RepoLocation | undefined {
-  // Old git (pre `--path-format`) echoes the unrecognized flag to stdout and
-  // exits 0 rather than erroring, so drop any echoed `-`-prefixed lines and
-  // read the two trailing path lines (toplevel, then git-common-dir). Strip only
-  // the trailing CR, not surrounding spaces — git paths may legitimately start
-  // or end with a space.
+  // Old git echoes the unrecognized `--path-format` flag and exits 0, so drop `-`-prefixed lines and
+  // read the last two path lines (toplevel, git-common-dir); strip only trailing CR — paths may have edge spaces.
   const lines = output
     .split('\n')
     .map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line))
@@ -430,8 +413,7 @@ async function readRepoLocation(
           gitExecOptions(repoPath, options)
         )
         if (hasUnsupportedRevParsePathFormatEcho(stdout)) {
-          // Why: some old Git versions echo the unknown option and exit zero;
-          // remember that compatibility signal even though parsing can recover.
+          // Why: some old Git echoes the unknown option and exits zero; remember that compat signal even though parsing recovers.
           capabilities.rememberUnsupported('rev-parse-path-format')
         }
         return parseRepoLocation(resolveBasePath, stdout)
@@ -457,11 +439,8 @@ async function normalizeMainWorktreePath(
 ): Promise<GitWorktreeInfo[]> {
   const mainIndex = worktrees.findIndex((worktree) => worktree.isMainWorktree)
   const mainWorktree = worktrees[mainIndex]
-  // Compare in the Git-output space: under WSL the porcelain/rev-parse paths are
-  // Linux while repoPath is a UNC path, so without translating, a UNC repoPath
-  // never matches the early-return and fires a needless rev-parse on every poll.
-  // Use the platform-independent UNC parser so the comparison holds regardless
-  // of host OS; the runner still receives the original repoPath for WSL routing.
+  // Why: under WSL, porcelain/rev-parse paths are Linux but repoPath is UNC; compare in Git-output
+  // space so the early-return matches and we skip a needless rev-parse per poll (runner still gets repoPath).
   const wslRepo = parseWslUncPath(repoPath)
   const comparablePath = wslRepo ? wslRepo.linuxPath : repoPath
   if (!mainWorktree || areWorktreePathsEqual(mainWorktree.path, comparablePath)) {
@@ -473,10 +452,8 @@ async function normalizeMainWorktreePath(
     return worktrees
   }
 
-  // Why: only a separate-git-dir/submodule main worktree reports the Git
-  // directory as the main entry — i.e. the main entry equals git-common-dir.
-  // A linked worktree's main entry is a real working root, so gating on this
-  // equality avoids overwriting it with the linked worktree's own toplevel.
+  // Why: only a separate-git-dir/submodule main worktree reports git-common-dir as its path; gate on
+  // that equality so we don't overwrite a linked worktree's real working root with its own toplevel.
   if (!areWorktreePathsEqual(mainWorktree.path, location.commonDir)) {
     return worktrees
   }
@@ -527,8 +504,7 @@ export function parseWorktreeList(
         const rawReason = line.slice('locked'.length).trim()
         lockReason = options.nulDelimited ? rawReason : decodeGitCQuotedPath(rawReason)
       } else if (line === 'prunable' || line.startsWith('prunable ')) {
-        // Why: Git ≥ 2.36 flags registrations whose directory is gone; ignoring
-        // it surfaces the stale worktree as a live workspace (issue #8389).
+        // Why: Git ≥2.36 flags registrations whose directory is gone; ignoring it shows the stale worktree as live (#8389).
         prunable = true
         const rawReason = line.slice('prunable'.length).trim()
         prunableReason = options.nulDelimited ? rawReason : decodeGitCQuotedPath(rawReason)
@@ -610,8 +586,7 @@ async function readWorktreeList(
       )
     },
     async () => {
-      // Why: `-z` is required to preserve worktree paths containing newlines,
-      // but Git <2.36 rejects it. Keep the line parser as the fallback.
+      // Why: `-z` preserves worktree paths with newlines but Git <2.36 rejects it; fall back to the line parser.
       const { stdout } = await gitExecFileAsync(['worktree', 'list', '--porcelain'], {
         cwd: repoPath,
         ...options
@@ -621,11 +596,8 @@ async function readWorktreeList(
         parseWorktreeList(stdout),
         options
       )
-      // Why: this `-z`-unsupported fallback (Git <2.36) also serves Git <2.31,
-      // which emits no `prunable` annotation; probe each linked worktree path
-      // for existence instead of treating stale registrations as live. On Git
-      // 2.31–2.35 `parseWorktreeList` already set `prunable`, so the probe is a
-      // harmless backstop that skips those entries (issue #8389).
+      // Why: Git <2.31 emits no `prunable`, so probe each linked path for existence instead of trusting
+      // stale registrations; a harmless backstop on 2.31–2.35 where parseWorktreeList already set it (#8389).
       return annotatePrunableByExistence(normalized, repoPath, options)
     },
     isUnsupportedWorktreeListZError
@@ -645,11 +617,8 @@ async function annotatePrunableByExistence(
       const index = nextIndex
       nextIndex += 1
       const worktree = worktrees[index]
-      // Git only marks linked worktrees prunable, and never locked ones (a
-      // lock shields the registration even when the directory is missing). The
-      // `locked` annotation is only parsed on Git >=2.31, so on older Git a
-      // locked+missing worktree cannot be shielded here. A missing main
-      // worktree is handled by the repo-level ENOENT paths.
+      // Git only prunes linked worktrees, never locked ones (a lock shields a missing dir; `locked`
+      // parses only on Git >=2.31). A missing main worktree is handled by the repo-level ENOENT paths.
       if (
         !worktree ||
         worktree.isMainWorktree ||
@@ -709,17 +678,10 @@ export async function listWorktreeGraph(
   }
 }
 
-// Why: a cold start lists every repo's worktrees from several independent
-// paths (renderer worktrees fetch, lineage resolution, boot pty-registry
-// hydration), and each `git worktree list` is a full process spawn —
-// expensive on Windows (issue #7225). Sharing the in-flight promise collapses
-// concurrent duplicate scans; nothing is served after a scan settles.
+// Why: cold start triggers many concurrent `git worktree list` spawns per repo (expensive on Windows, #7225); share the in-flight promise to collapse duplicates.
 const inFlightWorktreeScans = new Map<string, Promise<GitWorktreeInfo[]>>()
 
-// Why: a caller listing AFTER a mutation completed must observe it, so it may
-// not join a scan that started before the mutation. Bumping the generation on
-// mutation completion retires older in-flight scans from sharing (they still
-// settle for their original callers).
+// Why: a listing after a mutation must not join a scan that predates it; bumping the generation on mutation retires older in-flight scans from sharing.
 const worktreeScanGenerations = new Map<string, number>()
 
 function hasInFlightWorktreeScanForRepo(repoPath: string): boolean {
@@ -733,8 +695,7 @@ function hasInFlightWorktreeScanForRepo(repoPath: string): boolean {
 }
 
 function bumpWorktreeScanGeneration(repoPath: string): void {
-  // Why: generations only prevent joining a pre-mutation scan. Without an
-  // active scan, retaining the repo path just leaks completed mutation keys.
+  // Why: generations only prevent joining a pre-mutation scan; with no active scan, keeping the repo path just leaks completed mutation keys.
   if (!hasInFlightWorktreeScanForRepo(repoPath)) {
     return
   }
@@ -742,8 +703,7 @@ function bumpWorktreeScanGeneration(repoPath: string): void {
 }
 
 function pruneWorktreeScanGeneration(repoPath: string): void {
-  // Why: ordinary scan settlement should stay O(1); only repos invalidated
-  // during an active scan need the cross-generation in-flight check.
+  // Why: keep ordinary scan settlement O(1); only repos invalidated during an active scan need the cross-generation check.
   if (!worktreeScanGenerations.has(repoPath)) {
     return
   }
@@ -813,9 +773,7 @@ async function listWorktreesUnshared(
     if (isNotGitRepositoryError(err)) {
       return []
     }
-    // Why: a silent catch turns git compatibility or repo-state failures into
-    // opaque downstream errors like "Worktree created but not found in listing".
-    // Surface the cause so future regressions show up immediately.
+    // Why: don't swallow git-compat/repo-state failures — else they resurface as opaque "created but not found in listing" errors.
     console.warn(`[git/worktree] listWorktrees failed for ${repoPath}:`, err)
     return []
   }
@@ -853,8 +811,7 @@ async function annotateSparseCheckoutStatus(
     }
   }
 
-  // Why: worktree refreshes run on git-status polling paths. Many worktrees can
-  // otherwise fan out `.git`/sparse-checkout filesystem probes all at once.
+  // Why: cap concurrency so status-poll refreshes don't fan out many sparse-checkout filesystem probes at once.
   const workerCount = Math.min(SPARSE_CHECKOUT_DETECTION_CONCURRENCY, worktrees.length)
   await Promise.all(Array.from({ length: workerCount }, () => detectNext()))
   return annotated
@@ -913,17 +870,14 @@ async function refreshLocalBaseRefForWorktreeCreate(
       return { ...resultBase, status: 'updated', ownerWorktreePath: currentOwner.path }
     }
 
-    // Why: no owner worktree — fast-forward the bare ref. The expected-old-OID
-    // form makes this a no-op-safe compare-and-swap if the ref moved since the
-    // evaluation snapshot.
+    // Why: no owner worktree — fast-forward the bare ref; the expected-old-OID form is a no-op-safe CAS if the ref moved since evaluation.
     await gitExecFileAsync(
       ['update-ref', evaluation.fullRef, evaluation.remoteOid, evaluation.localOid],
       gitExecOptions(repoPath, options)
     )
     return { ...resultBase, status: 'updated' }
   } catch {
-    // update-ref/reset can fail on locked refs, filesystem errors, or unusual
-    // worktree states. Worktree creation should still proceed.
+    // update-ref/reset can fail on locked refs or odd worktree states; worktree creation should still proceed.
     return { ...resultBase, status: 'skipped_error' }
   }
 }
@@ -934,10 +888,9 @@ async function refreshLocalBaseRefForWorktreeCreate(
  * @param worktreePath - Absolute path where the worktree will be created
  * @param branch - Branch name for the new worktree
  * @param baseBranch - Optional base branch to create from (defaults to HEAD)
- * @remarks Side effect: passes `--no-track`, writes `branch.<branch>.base`
- * for new-branch worktrees with a base ref, and may write
- * `push.autoSetupRemote=true` to the repo's shared config. Config writes are
- * best-effort and warn-only. See body comments below for the full rationale.
+ * @remarks Side effects (best-effort, warn-only): passes `--no-track`, writes
+ * `branch.<branch>.base` for new-branch worktrees with a base ref, and may
+ * write `push.autoSetupRemote=true` to the repo's shared config.
  */
 export async function addWorktree(
   repoPath: string,
@@ -985,20 +938,13 @@ async function performAddWorktree(
     // Why: -b would create a new branch instead of checking out the selected one.
     args.push(worktreePath, branch)
   } else {
-    // Why: --no-track keeps the new branch from inheriting the base ref's
-    // upstream, so `git status` doesn't report "behind by N" against the base
-    // pre-publish and tools/agents don't misread an unpublished branch as
-    // out-of-sync. First push sets the upstream — see push.autoSetupRemote
-    // below for the terminal ergonomics.
+    // Why: --no-track avoids inheriting the base's upstream so `git status` won't misreport "behind by N" pre-publish; first push sets it (see push.autoSetupRemote below).
     args.push('--no-track', '-b', branch, worktreePath)
     if (baseBranch) {
       effectiveBase = await resolveWorktreeAddBaseRef(baseBranch, (qualifiedRef) =>
         hasWorktreeBaseCommitRef(repoPath, qualifiedRef, options)
       )
-      // Why: resolving the creation base first distinguishes real
-      // remote-tracking refs from slash-containing local branch names.
-      // The mutation stays behind the explicit setting so the default
-      // remains conservative.
+      // Why: resolve the creation base first to distinguish remote-tracking refs from slash-containing local branches (mutation gated behind the explicit setting).
       if (refreshLocalBaseRef) {
         localBaseRefRefresh = await refreshLocalBaseRefForWorktreeCreate(
           repoPath,
@@ -1021,8 +967,7 @@ async function performAddWorktree(
   }
   await gitExecFileAsync(args, {
     ...gitExecOptions(repoPath, options),
-    // Why: bound the checkout so a OneDrive cloud-placeholder stall (STA-1292)
-    // fails fast rather than hanging worktree creation indefinitely.
+    // Why: bound the checkout so a OneDrive cloud-placeholder stall (STA-1292) fails fast instead of hanging.
     timeout: WORKTREE_ADD_TIMEOUT_MS
   })
 
@@ -1034,38 +979,13 @@ async function performAddWorktree(
     await persistWorktreeCreationBase(worktreePath, branch, effectiveBase, options)
   }
 
-  // SSH parity: src/relay/git-handler-worktree-ops.ts addWorktreeOp mirrors this exact
-  // probe-and-write state machine. If you change the logic here, update
-  // the relay handler in lockstep so local and SSH paths stay aligned.
-  //
-  // Why: with --no-track there is no upstream until first push. Setting
-  // push.autoSetupRemote=true makes a plain `git push` from the terminal
-  // create origin/<branch> and set it as upstream automatically — matching
-  // user expectations from modern git without requiring `-u`. Note that
-  // `--local` on a linked worktree writes to the shared common-dir config,
-  // so this affects the whole repo, not just this worktree. That is
-  // intentional and acceptable: the value is benign and idempotent, and
-  // every Orca-created worktree wants the same default. True per-worktree
-  // scope would require enabling extensions.worktreeConfig=true repo-wide,
-  // which is a larger change we deliberately avoid.
-  //
-  // Notes on the design:
-  // - push.autoSetupRemote is honored by git >= 2.37; older clients ignore
-  //   the value, so `git push` falls back to the pre-2.37 "no upstream"
-  //   error and the user runs `git push -u` once.
-  // - Failures here are warn-only: config writes are best-effort and a
-  //   missing write degrades to the same fallback as old git.
-  // - The write is skipped when any value is already set (local, global,
-  //   or system) so a deliberate user `false` is preserved.
-  // - Not rolled back on creation failure: addSparseWorktree's catch path
-  //   removes the worktree but does not unset this config. That is consistent
-  //   with the "benign and idempotent" rationale above — every Orca-created
-  //   worktree wants this default, and a future creation will silently re-set
-  //   it via the existing-value check anyway.
+  // SSH parity: relay's addWorktreeOp (src/relay/git-handler-worktree-ops.ts) mirrors this — change both in lockstep.
+  // Why: --no-track leaves no upstream until first push; push.autoSetupRemote=true lets a plain
+  // `git push` create+set origin/<branch> (git >=2.37; older clients ignore it). `--local` on a
+  // linked worktree writes the shared common-dir config (whole repo) — intentional and idempotent,
+  // so it's warn-only and not rolled back on failure.
   try {
-    // Why: `--get` (not `--local --get`) so a value set at any scope
-    // (local/global/system) counts as "user already chose" and we don't
-    // overwrite it.
+    // Why: `--get` (not `--local --get`) so a value at any scope counts as "user already chose" and isn't overwritten.
     let alreadySet = false
     try {
       await gitExecFileAsync(['config', '--get', 'push.autoSetupRemote'], {
@@ -1073,10 +993,7 @@ async function performAddWorktree(
       })
       alreadySet = true
     } catch (readError) {
-      // Why: `git config --get` exits 1 only when the key is unset at every
-      // scope. Any other exit code means a real read failure (corrupt config,
-      // locked file, parse error) — surface that via the outer catch instead
-      // of silently overwriting whatever value the user actually has.
+      // Why: `git config --get` exits 1 only when unset at every scope; any other code is a real read failure — rethrow rather than overwrite the user's value.
       const code = (readError as { code?: unknown })?.code
       if (code !== 1) {
         throw readError
@@ -1138,15 +1055,13 @@ export async function addSparseWorktree(
       try {
         await removeWorktree(repoPath, worktreePath, true, {
           deleteBranch: !options.checkoutExistingBranch,
-          // Why: rolling back a failed creation — the just-created branch has no
-          // user commits, so force-delete it rather than preserving an orphan.
+          // Why: failed-creation rollback — the fresh branch has no user commits, so force-delete rather than orphan it.
           forceBranchDelete: !options.checkoutExistingBranch,
           ...(options.wslDistro ? { wslDistro: options.wslDistro } : {})
         })
       } catch {
         wrapped.cleanupFailed = true
-        // Why: the user needs to know that manual cleanup may be required —
-        // otherwise a half-created worktree silently lingers on disk.
+        // Why: surface that manual cleanup may be needed, else a half-created worktree lingers silently on disk.
         wrapped.message = `${wrapped.message} (cleanup also failed — the partially created worktree at "${worktreePath}" may need manual removal)`
       }
     }
@@ -1155,13 +1070,10 @@ export async function addSparseWorktree(
 }
 
 /**
- * Move a worktree's directory to a new path with `git worktree move`, which
- * relocates the working tree and rewrites git's gitdir pointers so the linkage
- * stays intact — a raw `fs.rename` would corrupt the `.git` file and the
- * `.git/worktrees/<name>/gitdir` back-pointer. Local worktrees only: the
- * first-work folder rename skips SSH/remote, so there is no relay parity handler
- * for this op. The caller owns migrating Orca's path-derived worktree identity
- * after a successful move, and pre-checks that the destination is free.
+ * Move a worktree with `git worktree move` (not `fs.rename`, which corrupts the
+ * `.git` file and the `.git/worktrees/<name>/gitdir` back-pointer). Local-only,
+ * so there is no relay parity handler. Caller owns migrating Orca's
+ * path-derived worktree identity and pre-checks that the destination is free.
  */
 export async function moveWorktree(
   repoPath: string,
@@ -1184,10 +1096,7 @@ export async function removeWorktree(
   repoPath: string,
   worktreePath: string,
   force = false,
-  // Why: forceBranchDelete is for cleaning up a worktree this code just created
-  // (e.g. rollback of a failed creation) where the fresh branch has no user work
-  // and must be removed outright. User-initiated deletes leave it false so unmerged
-  // commits are preserved.
+  // forceBranchDelete: for failed-creation rollback (fresh branch, no user work); user deletes leave it false so unmerged commits survive.
   options: RemoveWorktreeOptions = {}
 ): Promise<RemoveWorktreeResult> {
   try {
@@ -1213,8 +1122,7 @@ async function performRemoveWorktree(
   const branchName = normalizeLocalBranchRef(removedWorktree?.branch ?? '')
   const branchHead = removedWorktree?.head ?? ''
 
-  // Why: callers outside the IPC/runtime preflight must not bypass Git's lock
-  // contract or depend on localized stderr to discover it after side effects.
+  // Why: callers outside the IPC/runtime preflight must not bypass Git's lock contract or rely on localized stderr after side effects.
   assertWorktreeUnlockedForRemoval(removedWorktree)
 
   const args = ['worktree', 'remove']
@@ -1228,9 +1136,7 @@ async function performRemoveWorktree(
     if (force || !isSubmoduleWorktreeRemovalRefusal(error)) {
       throw error
     }
-    // Why: Git refuses non-force removal of any worktree with an initialised
-    // submodule even when everything is clean. Re-prove cleanliness (parent
-    // status reports dirty submodule content as ` M <sub>`), then --force.
+    // Why: Git refuses non-force removal of a worktree with an initialised submodule even when clean; re-prove cleanliness, then --force.
     await assertWorktreeCleanForRemoval(worktreePath, false, options)
     await gitExecFileAsync(
       ['worktree', 'remove', '--force', worktreePath],
@@ -1246,13 +1152,8 @@ async function performRemoveWorktree(
   }
 
   try {
-    // Why: `git worktree remove` only detaches the filesystem entry. Orca also
-    // drops the now-unused local branch here so delete-worktree does not leave
-    // behind orphaned feature branches unless another worktree still points at it.
-    // Use `-d` (not `-D`): Git refuses to delete a branch with commits not merged
-    // into its upstream or HEAD, so unpublished work is preserved instead of
-    // force-deleted. forceBranchDelete opts into `-D` for failed-creation rollback,
-    // where the fresh branch has no user work to protect.
+    // Why: also drop the now-orphaned branch so delete-worktree leaves none; `-d` (not `-D`) preserves
+    // unmerged work, and forceBranchDelete opts into `-D` for failed-creation rollback.
     const branchDeleteResult = await deleteLocalBranchAfterWorktreeRemoval(
       repoPath,
       branchName,
@@ -1277,16 +1178,14 @@ async function performRemoveWorktree(
           return {}
         }
       } catch (alreadyMergedDeleteError) {
-        // Why: the worktree is already gone; a raced branch cleanup should
-        // degrade to the preserved-branch recovery path instead of failing delete.
+        // Why: worktree is already gone; a raced branch cleanup should degrade to preserved-branch recovery, not fail delete.
         console.warn(
           `[git] Failed to delete already-merged local branch "${branchName}" after removing worktree`,
           alreadyMergedDeleteError
         )
       }
     }
-    // Expected when the branch still has unmerged/unpublished commits: keep it.
-    // Deleting a worktree must never silently discard commits.
+    // Keep an unmerged/unpublished branch: deleting a worktree must never silently discard commits.
     console.warn(
       `[git] Preserved local branch "${branchName}" after removing worktree (not fully merged)`,
       error
@@ -1315,8 +1214,7 @@ async function deleteLocalBranchAfterWorktreeRemoval(
   }
 
   try {
-    // Why: `branch -d` is the cheap live-checkout guard. Only pay for
-    // `worktree prune` when a stale admin record may be the thing blocking it.
+    // Why: only pay for `worktree prune` when a stale admin record may be blocking `branch -d`.
     await gitExecFileAsync(['worktree', 'prune'], gitExecOptions(repoPath, options))
   } catch (error) {
     console.warn(`[git] Failed to prune worktrees before deleting branch "${branchName}"`, error)
@@ -1350,9 +1248,7 @@ async function deleteAlreadyMergedBranchAfterSafeDeleteFailure(
     })
   const targetRefs = await getBranchCleanupTargetRefs(runGit, branchName)
   await refreshBranchCleanupTargetRefs(runGit, targetRefs)
-  // Why: squash merges rewrite commit IDs, so `branch -d` can reject a branch
-  // whose changes are already on the base ref. Delete only when Git can prove
-  // the branch contributes no tree changes to that base.
+  // Why: squash merges rewrite commit IDs, so `branch -d` rejects already-merged branches; delete only when Git proves no unmerged tree changes.
   if (
     !(await branchHasNoUnmergedChangesOnAnyTarget(
       runGit,
@@ -1389,8 +1285,7 @@ export async function forceDeleteLocalBranch(
   if (await isLocalBranchCheckedOut(repoPath, branchName, runGit)) {
     throw new Error(`Local branch "${branchName}" is checked out in another worktree.`)
   }
-  // Why: stale toast actions must not delete a branch that moved after Git
-  // preserved it. `update-ref` deletes only if the ref still has expectedHead.
+  // Why: stale toast actions must not delete a branch that moved; `update-ref -d` deletes only if the ref still == expectedHead.
   try {
     await runGit(['update-ref', '-d', `refs/heads/${branchName}`, expectedHead], repoPath)
   } catch {
@@ -1412,8 +1307,7 @@ export async function forceDeleteLocalBranch(
   try {
     await runGit(['config', '--remove-section', `branch.${branchName}`], repoPath)
   } catch {
-    // Best-effort parity with `git branch -D`; stale config is harmless and
-    // should not make the already-deleted ref look like a failed delete.
+    // Best-effort parity with `git branch -D`; stale config is harmless.
   }
 }
 
@@ -1493,22 +1387,8 @@ function translateWorktreePath(
 }
 
 async function detectSparseCheckout(worktreePath: string): Promise<boolean> {
-  // Why: `listWorktrees` runs on every 3-second git-status poll and on every
-  // worktree refresh, so this probe fires N times per poll for N worktrees.
-  // The previous `git sparse-checkout list` subprocess made that N*poll extra
-  // git processes, which regressed app responsiveness on machines with many
-  // worktrees (see PR #1131 revert in #1290). A single fs.stat on the
-  // per-worktree sparse-checkout config file is ~two orders of magnitude
-  // cheaper and has the same truthiness semantics: Git writes this file when
-  // sparse checkout is enabled for the worktree and does not write it
-  // otherwise.
-  //
-  // Why per-worktree gitdir and not `<worktreePath>/.git/info/sparse-checkout`:
-  // linked worktrees have a `.git` file that points at
-  // `<repo>/.git/worktrees/<name>`, and that is where Git stores the
-  // worktree-local sparse-checkout config. `core.sparseCheckout` itself is
-  // shared across all worktrees, so the presence of the config file is the
-  // correct per-worktree signal.
+  // Why: fs.stat the per-worktree gitdir's sparse-checkout config instead of a per-poll `git sparse-checkout list` subprocess that regressed responsiveness (PR #1290);
+  // the file's presence is the per-worktree signal because core.sparseCheckout is shared across all worktrees.
   try {
     const gitDir = await resolveGitDir(worktreePath)
     const stats = await stat(join(gitDir, 'info', 'sparse-checkout'))
diff --git a/src/main/github/client.ts b/src/main/github/client.ts
index d9d41f4f653..53bf26614ff 100644
--- a/src/main/github/client.ts
+++ b/src/main/github/client.ts
@@ -1,5 +1,4 @@
-/* eslint-disable max-lines -- Why: co-locating all GitHub client functions keeps the
-concurrency acquire/release pattern and error handling consistent across operations. */
+/* eslint-disable max-lines -- Why: co-locating all GitHub client functions keeps acquire/release and error handling consistent. */
 import type {
   ClassifiedError,
   GitPushTarget,
@@ -66,8 +65,7 @@ import {
   type LocalGitExecOptions,
   type OwnerRepo
 } from './gh-utils'
-// Import the pure error-parsing helpers from the lightweight module, not
-// `./gh-utils`, so tests that mock gh-utils still resolve the real functions.
+// Why: import from the lightweight module (not ./gh-utils) so tests mocking gh-utils still get the real functions.
 import { extractExecError, parseRetryAfterMs } from '../git/exec-error'
 import {
   isCommitPartOfMergedPR,
@@ -120,8 +118,7 @@ type HostedReviewLocalGitOptions = ReturnType<typeof getHostedReviewLocalGitOpti
 
 const ORCA_REPO = 'stablyai/orca'
 const PR_CHECK_LOG_TAIL_JOB_LIMIT = 5
-// Why: each entry holds up to 16KB of log text; bound the cache so a long
-// session reviewing many failing checks can't grow it without limit.
+// Why: each entry holds up to 16KB of log text; bound the cache so a long session can't grow it unbounded.
 const PR_CHECK_LOG_TAIL_CACHE_MAX_ENTRIES = 128
 const prCheckLogTailCache = new Map<string, string | null>()
 
@@ -197,9 +194,7 @@ function prRefreshUpstreamError(
     message: safePRRefreshErrorMessage(errorType),
     fetchedAt: Date.now()
   }
-  // Why: a rate limit that carries a Retry-After is a real cooldown — surface it
-  // as the retry schedule so the renderer disables manual Retry until the reset
-  // and shows a truthful auto-retry time, instead of retrying into another 429.
+  // Why: a Retry-After is a real cooldown — surface it as the retry schedule so the renderer doesn't retry into another 429.
   if (errorType === 'rate_limited') {
     const retryAfterMs = parseRetryAfterMs(extractExecError(err).stderr)
     if (retryAfterMs !== null && retryAfterMs > 0) {
@@ -268,9 +263,8 @@ function sanitizeRemoteName(owner: string, repo: string): string {
 }
 
 /**
- * A fork push target plus the PR's `maintainer_can_modify` flag. The flag rides
- * alongside the target (rather than inside {@link GitPushTarget}) so it never
- * leaks into the persisted, validated push-target shape.
+ * A fork push target plus the PR's `maintainer_can_modify` flag, kept outside
+ * {@link GitPushTarget} so it never leaks into the persisted push-target shape.
  */
 export type PullRequestPushTarget = {
   pushTarget: GitPushTarget
@@ -309,9 +303,7 @@ export async function getPullRequestPushTarget(
         prStdout = stdout
         break
       } catch (error) {
-        // Why: in fork workflows `origin` is often the contributor fork while
-        // the PR number belongs to `upstream`; probe all known PR repos before
-        // deciding this PR number is unavailable.
+        // Why: origin is often the contributor fork while the PR belongs to upstream; probe all PR repos before giving up.
         if (isNotFoundGhError(error)) {
           continue
         }
@@ -421,22 +413,17 @@ export async function getAuthenticatedViewer(): Promise<GitHubViewer | null> {
   }
 }
 
-// Why: main-process maps omit repoId because the IPC handler never receives
-// a repo identifier beyond path. Exported because runtime consumers receive
-// listWorkItems results before the renderer stamps repoId.
+// Why: omit repoId — the main process only has the path; the renderer stamps repoId after IPC.
 export type MainWorkItem = Omit<GitHubWorkItem, 'repoId'>
 
-// Why: issue numbers follow creation order within a repository. Pinning this
-// sort keeps gh's rich PR rows aligned with numbered Search API issue pages.
+// Why: issue numbers follow creation order, so this sort aligns gh's PR rows with numbered Search API issue pages.
 const WORK_ITEM_NUMBER_SORT_QUALIFIER = 'sort:created-desc'
 
 const WORK_ITEM_PR_LIST_JSON_FIELDS =
   'number,title,state,url,labels,updatedAt,author,isDraft,headRefName,baseRefName,headRefOid,headRepositoryOwner,reviewRequests'
 
-// Why: these fields are intentionally excluded from `gh pr list` because
-// statusCheckRollup/review decision/PR-specific merge metadata fan out into
-// expensive GraphQL work across every row. Requested reviewers are kept in the
-// list payload because the Tasks table renders that column on first paint.
+// Why: kept out of `gh pr list` — statusCheckRollup/reviewDecision/merge metadata fan out into expensive per-row GraphQL.
+// Requested reviewers stay in the list payload because Tasks renders that column on first paint.
 const WORK_ITEM_PR_DETAIL_JSON_FIELDS =
   'number,title,state,url,labels,updatedAt,author,isDraft,headRefName,baseRefName,headRefOid,headRepositoryOwner,additions,deletions,changedFiles,reviewDecision,reviewRequests,latestReviews,assignees,statusCheckRollup,mergeable,mergeStateStatus,autoMergeRequest,maintainerCanModify'
 
@@ -464,12 +451,8 @@ function mapIssueWorkItem(item: Record<string, unknown>): MainWorkItem {
 }
 
 /**
- * Derive both the author login and its API avatar_url in one place so GHE
- * avatars render (the login-only `github.com/{login}.png` URL 404s on GHE).
- *
- * REST exposes `user.avatar_url`; gh/GraphQL expose `author.avatarUrl`. `gh pr
- * view` omits the avatar entirely, so authorAvatarUrl is left undefined and the
- * UI falls back to the login URL then a placeholder. See #8784.
+ * Derive author login + avatar_url together so GHE avatars render — the login-only
+ * `{login}.png` URL 404s on GHE. REST uses `user.avatar_url`, gh/GraphQL `author.avatarUrl` (#8784).
  */
 function authorFieldsFromUnknown(
   item: Record<string, unknown>
@@ -505,8 +488,7 @@ function extractHeadOwnerLogin(item: Record<string, unknown>): string | null {
         }
       }
     }
-    // Why: when a fork is deleted or made inaccessible, GitHub can return
-    // `head.repo = null` but still include `head.user`/`head.label`.
+    // Why: a deleted/inaccessible fork returns head.repo = null but still has head.user/head.label.
     const user = head.user
     if (typeof user === 'object' && user !== null) {
       const login = (user as { login?: unknown }).login
@@ -682,14 +664,9 @@ function mapPullRequestWorkItem(
   item: Record<string, unknown>,
   baseOwnerRepo: OwnerRepo | null = null
 ): MainWorkItem {
-  // Why: fork PRs are disabled in the Start-from picker. We compare the PR head's
-  // owner to the selected repo's owner; when the base repo is unknown we default
-  // to false so non-picker call sites see the same shape as before.
+  // Why: fork PRs are disabled in the Start-from picker; compare head owner to the selected repo's owner.
   const headOwnerLogin = extractHeadOwnerLogin(item)
-  // Why: only emit isCrossRepository when we actually know the head owner. If
-  // the gh response lacks `headRepositoryOwner` (older callers, tests without
-  // that fixture, or gh not returning it), leave the field undefined instead
-  // of falsely claiming "not a fork".
+  // Why: leave isCrossRepository undefined when the head owner is unknown, rather than falsely claiming "not a fork".
   const isCrossRepository =
     headOwnerLogin !== null && baseOwnerRepo !== null
       ? headOwnerLogin !== baseOwnerRepo.owner
@@ -787,8 +764,7 @@ async function hydrateWorkItemRepositoryMergeMetadata(
   if (!ownerRepo || !hasPullRequest) {
     return items
   }
-  // Why: merge method settings are repository-level, so one cached metadata
-  // probe can keep Tasks rows accurate without per-PR GraphQL fan-out.
+  // Why: merge settings are repo-level, so one cached probe keeps Tasks rows accurate without per-PR GraphQL fan-out.
   const mergeMetadata = await detectRepositoryMergeMetadata(ownerRepo, undefined, ghOptions)
   if (!mergeMetadata.mergeMethodSettings && mergeMetadata.autoMergeAllowed === null) {
     return items
@@ -835,9 +811,7 @@ async function fetchIssueWorkItem(
   return mapIssueWorkItem(JSON.parse(stdout) as Record<string, unknown>)
 }
 
-// REST /pulls/{n} has requested_reviewers but not latestReviews. When the JSON
-// `gh pr view` path fails, still pull review fields from gh so mobile/desktop
-// reviewer lists (CodeRabbit COMMENTED, etc.) are not silently empty.
+// Why: REST /pulls/{n} lacks latestReviews, so pull review fields from gh so reviewer lists aren't silently empty.
 const WORK_ITEM_PR_REVIEW_JSON_FIELDS = 'reviewRequests,latestReviews'
 
 async function fetchPullRequestReviewFields(
@@ -896,9 +870,7 @@ async function fetchPullRequestWorkItem(
       )
       const item = JSON.parse(stdout) as Record<string, unknown>
       const mapped = mapPullRequestWorkItem(item, ownerRepo)
-      // Why: merge-metadata GraphQL is best-effort. A failure here must not fall
-      // through to the REST path below — that path drops latestReviews and blanks
-      // the mobile/desktop reviewer list for bots that only left a review.
+      // Why: merge-metadata GraphQL is best-effort — don't fall through to REST, which drops latestReviews and blanks bot-only reviewer lists.
       const baseRefName = typeof item.baseRefName === 'string' ? item.baseRefName : undefined
       try {
         const mergeMetadata = await detectRepositoryMergeMetadata(ownerRepo, baseRefName, ghOptions)
@@ -1010,8 +982,7 @@ function buildWorkItemListRequest(args: {
     }
   }
 
-  // Why: search/issues omits the PR fields used by the Tasks management
-  // columns. Fetch through gh's rich PR list and slice its stable created sort.
+  // Why: search/issues omits the PR fields the Tasks columns need; use gh's rich PR list on a stable created sort.
   searchParts.push(WORK_ITEM_NUMBER_SORT_QUALIFIER)
   const out = [
     'pr',
@@ -1030,11 +1001,7 @@ function buildWorkItemListRequest(args: {
   return { args: out, offset: (page - 1) * limit }
 }
 
-// Why: internal shape shared by listRecentWorkItems / listQueriedWorkItems so
-// listWorkItems can lift per-side errors into the IPC envelope. The issue-side
-// error is the specific new class of silent wrongness introduced by #1076 —
-// PR-side errors existed before and are explicitly out of scope for this
-// feature per the parent design doc §6.
+// Why: shared shape so listWorkItems can lift the issue-side error (#1076 silent wrongness) into the IPC envelope; PR errors out of scope (§6).
 type PartialWorkItemsResult = {
   items: MainWorkItem[]
   issuesError?: ClassifiedError
@@ -1048,8 +1015,7 @@ function assertSshRepoHasResolvedGitHubSource(args: {
   if (!args.connectionId || args.issueOwnerRepo || args.prOwnerRepo) {
     return
   }
-  // Why: SSH repo paths are remote-only, so gh cannot use cwd to infer repo
-  // context. Without a resolved owner/repo, running gh would query local state.
+  // Why: SSH repo paths are remote-only, so without a resolved owner/repo gh would query local state.
   throw new Error(GITHUB_WORK_ITEMS_SSH_REMOTE_REQUIRED_MESSAGE)
 }
 
@@ -1066,8 +1032,7 @@ async function resolvePrWorkItemSource(
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<ResolvedPrWorkItemSource> {
   const [originCandidate, upstreamCandidate] = await Promise.all([
-    // Why: this caller combines both remotes itself, so it needs origin
-    // specifically (getOwnerRepo is upstream-first since #7331).
+    // Why: this caller combines both remotes itself, so it needs origin specifically (getOwnerRepo is upstream-first since #7331).
     getOwnerRepoForRemote(repoPath, 'origin', connectionId, localGitOptions),
     getOwnerRepoForRemote(repoPath, 'upstream', connectionId, localGitOptions)
   ])
@@ -1077,10 +1042,8 @@ async function resolvePrWorkItemSource(
 }
 
 /**
- * gh exec for calls that rely on gh's own cwd→repo resolution (no explicit
- * owner/repo). Serves a remembered deterministic resolution failure without
- * spawning, so a remote-less repo costs one gh spawn per config change/TTL
- * instead of two per Tasks refresh.
+ * gh exec relying on gh's own cwd→repo resolution. Serves a remembered resolution failure
+ * without spawning, so a remote-less repo costs one gh spawn per config change/TTL, not two per refresh.
  */
 async function ghCwdResolvedExec(
   context: GitHubRepoContext,
@@ -1135,9 +1098,7 @@ async function listRecentWorkItems(
     issueRequest.args.splice(1, 2)
   }
   if (issueOwnerRepo || prOwnerRepo || requiresExplicitRepo) {
-    // Why: allSettled so a 403 on upstream issues doesn't zero out the origin
-    // PR half — the UI renders partial results plus a banner for the failing
-    // side, matching the parent design doc's partial-failure rule (§2).
+    // Why: allSettled so a 403 on the issue side doesn't zero the PR half — partial results + banner (parent doc §2).
     const [issuesSettled, prsSettled] = await Promise.allSettled([
       issueOwnerRepo
         ? ghExecFileAsync(issueRequest.args, ghOptions)
@@ -1155,9 +1116,7 @@ async function listRecentWorkItems(
     let issuesError: ClassifiedError | undefined
     if (issuesSettled.status === 'fulfilled') {
       issues = (JSON.parse(issuesSettled.value.stdout) as Record<string, unknown>[])
-        // Why: the GitHub search/issues endpoint may still return PRs with a
-        // pull_request marker even when queried with is:issue. Filter them out
-        // here to keep the issue and PR buckets clean.
+        // Why: search/issues can still return PRs (pull_request marker) even with is:issue; filter them out.
         .filter((item) => !('pull_request' in item))
         .map(mapIssueWorkItem)
     } else {
@@ -1175,15 +1134,8 @@ async function listRecentWorkItems(
         .map((item) => mapPullRequestWorkItem(item, prOwnerRepo))
       prs = await hydrateWorkItemRepositoryMergeMetadata(prs, prOwnerRepo, ghOptions)
     } else {
-      // Why: PR-side failures must preserve the pre-diff behavior of
-      // Promise.all by re-throwing so the rejection propagates up through
-      // listWorkItems to the renderer's cross-repo aggregator (which counts
-      // the repo as failed). This feature is scoped to the issue-side silent
-      // wrongness from #1076; PR errors must not be silently swallowed here.
-      // Why: if the issue side ALSO failed, the classified issuesError would
-      // otherwise be silently dropped when we throw the PR reason. Log it so
-      // debugging both-sides-failed scenarios (e.g. 403 on both endpoints)
-      // isn't blind to the issue-side classification.
+      // Why: re-throw PR errors so the cross-repo aggregator counts the repo failed; this feature only fixes issue-side swallowing (#1076).
+      // Why: log issuesError first so a both-sides-failed case isn't blind to the classification we're about to drop.
       if (issuesError) {
         console.warn(
           'listRecentWorkItems: both issue and PR sides failed; issuesError was classified:',
@@ -1200,13 +1152,7 @@ async function listRecentWorkItems(
     }
   }
 
-  // Why: the fallback path (non-GitHub remote — neither issueOwnerRepo nor
-  // prOwnerRepo resolved) intentionally stays on Promise.all rather than the
-  // Promise.allSettled + per-side classification used above. There are no
-  // `sources` to surface on this branch and nothing for the partial-failure
-  // banner to render, so a single-side failure here means the whole call is
-  // effectively unusable for the feature — reject-all matches reality. If
-  // non-GitHub remotes ever grow source metadata, revisit this symmetry.
+  // Why: non-GitHub remotes have no sources for a partial-failure banner, so keep Promise.all (reject-all) instead of allSettled.
   const [issuesResult, prsResult] = await Promise.all([
     ghCwdResolvedExec(repoContext, issueRequest.args, ghOptions),
     ghCwdResolvedExec(repoContext, prRequest.args, ghOptions)
@@ -1249,9 +1195,7 @@ async function listQueriedWorkItems(
   let nonAvailabilityFailureCount = 0
   let availabilityError: unknown
 
-  // Why: run the issue and PR fetches in parallel but surface the
-  // issue-side error separately so the IPC envelope can carry it up. PR-side
-  // failures retain the prior swallow-and-log behavior per parent doc §6.
+  // Why: surface the issue-side error separately for the IPC envelope; PR-side keeps prior swallow-and-log (parent doc §6).
   const issueFetch = (async (): Promise<PartialWorkItemsResult> => {
     if (!issueScope) {
       return { items: [] }
@@ -1327,9 +1271,7 @@ async function listQueriedWorkItems(
 
   const [issueResult, prItems] = await Promise.all([issueFetch, prFetch])
   if (availabilityError && successfulRequestCount === 0 && nonAvailabilityFailureCount === 0) {
-    // Why: combined queries normally preserve either successful half. When
-    // every attempted half hit the same availability class, propagate one of
-    // those existing failures so Tasks can distinguish an outage from no data.
+    // Why: when every half hit the same availability failure, propagate it so Tasks can distinguish an outage from no data.
     throw availabilityError
   }
   return {
@@ -1369,10 +1311,7 @@ export async function listWorkItems(
   const prOwnerRepo = prResolved.source
   await acquire()
   try {
-    // Why: errors propagate to IPC so the renderer's cross-repo aggregator can
-    // count this repo as failed and surface the partial-failure banner. A
-    // catch-all here would make an auth/network failure indistinguishable from
-    // an empty result and silently under-report per-repo failures.
+    // Why: let errors propagate to IPC — a catch-all would make failure indistinguishable from empty and under-report per-repo failures.
     const partial = !trimmedQuery
       ? await listRecentWorkItems(
           repoPath,
@@ -1425,8 +1364,7 @@ function buildSearchQueryString(
   if (query.state === 'open') {
     parts.push('is:open')
   } else if (query.state === 'closed') {
-    // Why: GitHub search treats merged PRs as closed. Exclude merged so the
-    // "Closed" filter actually means closed-without-merge.
+    // Why: GitHub search treats merged PRs as closed; exclude merged so "Closed" means closed-without-merge.
     parts.push('is:closed')
     if (query.scope !== 'issue') {
       parts.push('-is:merged')
@@ -1482,16 +1420,13 @@ async function countWorkItemsForQuery(
     ],
     ghOptions
   )
-  // Why: over-counts gh cache hits, which is the safe direction — the search
-  // bucket is only 30/min and the next probe corrects the estimate.
+  // Why: over-counting cache hits is the safe direction — the next probe corrects the estimate.
   noteRateLimitSpend('search')
   return Number.parseInt(stdout.trim(), 10) || 0
 }
 
 function sameOwnerRepo(left: OwnerRepo | null, right: OwnerRepo | null): boolean {
-  // Why: GitHub treats owner and repo names as case-insensitive, so remotes
-  // with different casing (StablyAI/Orca vs stablyai/orca) point at the same
-  // repo and should not split into two search queries.
+  // Why: GitHub owner/repo names are case-insensitive, so differently-cased remotes are the same repo (don't split into two searches).
   return (
     left?.owner.toLowerCase() === right?.owner.toLowerCase() &&
     left?.repo.toLowerCase() === right?.repo.toLowerCase()
@@ -1512,9 +1447,7 @@ function defaultOpenWorkItemQuery(): ParsedTaskQuery {
   }
 }
 
-// Why: uses GitHub's search API to get total_count without fetching items.
-// This powers the pagination bar so the user sees total pages upfront.
-// Cached for 120s to avoid burning the search rate limit (30 req/min).
+// Why: cached 120s to avoid burning the 30/min search rate limit that backs the pagination total.
 export async function countWorkItems(
   repoPath: string,
   query?: string,
@@ -1540,10 +1473,7 @@ export async function countWorkItems(
   const parsedQuery = trimmedQuery ? parseTaskQuery(trimmedQuery) : null
   const effectiveQuery = parsedQuery ?? defaultOpenWorkItemQuery()
 
-  // Why: counts are decorative (pagination totals). The search bucket is only
-  // 30/min, so a multi-repo Tasks page must stop counting when the budget is
-  // gone instead of converting the remaining repos into 403 spawns. getRateLimit
-  // is 30s-cached and single-flight, so priming here is one spawn per window.
+  // Why: counts are decorative, so stop when the 30/min search budget is gone rather than spawn into 403s (getRateLimit is 30s-cached).
   await getRateLimit()
   if (rateLimitGuard('search').blocked) {
     return 0
@@ -1562,9 +1492,7 @@ export async function countWorkItems(
     }
 
     const counts: Promise<number>[] = []
-    // Why: `draft`, `reviewRequested`, and `reviewedBy` are PR-only predicates.
-    // When present, the issue half would always return 0 and wastes a search
-    // API call — skip the issue half entirely in that case.
+    // Why: draft/reviewRequested/reviewedBy are PR-only, so the issue half would always return 0 — skip it to save a search call.
     const hasPrOnlyFilter =
       effectiveQuery.draft ||
       effectiveQuery.reviewRequested !== null ||
@@ -1596,9 +1524,7 @@ export async function countWorkItems(
         )
       )
     }
-    // Why: allSettled so a single failing search (e.g. transient network, rate
-    // limit on one side) doesn't silently zero out the total; sum only the
-    // fulfilled halves instead.
+    // Why: allSettled so one failing search side doesn't zero the total; sum only fulfilled halves.
     const results = await Promise.allSettled(counts)
     let total = 0
     for (const r of results) {
@@ -1622,9 +1548,7 @@ export async function getRepoSlug(
   connectionId?: string | null,
   options: HostedReviewExecutionOptions = {}
 ): Promise<{ owner: string; repo: string } | null> {
-  // Why: the slug is the checkout's own identity (renderer display, icon
-  // autodetect), so it must stay origin-based — getOwnerRepo became
-  // upstream-first for PR reads in #7331.
+  // Why: the slug is the checkout's own identity, so it must stay origin-based (getOwnerRepo is upstream-first since #7331).
   return getOwnerRepoForRemote(
     repoPath,
     'origin',
@@ -1634,11 +1558,8 @@ export async function getRepoSlug(
 }
 
 /**
- * Resolve a fork's upstream/parent owner/repo, or null when the repo is not a
- * fork. Why: a fork's `origin` points at the personal copy, so repo identity
- * (notably the avatar) should prefer the upstream. Fast-paths the `upstream`
- * remote (offline); otherwise asks the GitHub API for the fork parent. The API
- * call targets the explicit origin slug, so it works for SSH repos too.
+ * Resolve a fork's upstream/parent owner/repo, or null when not a fork.
+ * Why: a fork's `origin` is the personal copy, so repo identity (avatar) should prefer upstream.
  * Best-effort: any failure (offline, unauthed, non-GitHub) resolves to null.
  */
 export async function getRepoUpstream(
@@ -1648,8 +1569,7 @@ export async function getRepoUpstream(
 ): Promise<OwnerRepo | null> {
   const localGitArgs = hostedReviewLocalGitOptionArgs(options)
   const localGitOptions = localGitArgs[0] ?? {}
-  // Why: must be origin specifically — the fork-parent fast-path below compares
-  // it against the upstream remote (getOwnerRepo is upstream-first since #7331).
+  // Why: must be origin — the fast-path compares it against upstream (getOwnerRepo is upstream-first since #7331).
   const origin = await getOwnerRepoForRemote(repoPath, 'origin', connectionId, ...localGitArgs)
   if (!origin) {
     return null
@@ -1667,8 +1587,7 @@ export async function getRepoUpstream(
   try {
     const { stdout } = await ghExecFileAsync(
       ['repo', 'view', `${origin.owner}/${origin.repo}`, '--json', 'isFork,parent'],
-      // Why: best-effort fork lookup runs at add-time; cap latency so a stalled
-      // gh process can't hold up repo creation.
+      // Why: cap latency so a stalled gh process can't hold up repo creation.
       {
         ...ghRepoExecOptions(githubRepoContext(repoPath, connectionId, localGitOptions)),
         timeout: 10_000
@@ -1753,8 +1672,7 @@ function parseCreatePRPayload(stdout: string): { number: number; url: string } |
   } catch {
     // Fall through to URL parsing for older gh versions without --json support.
   }
-  // Why: gh prints the PR URL (not JSON) here; match any host, not just
-  // github.com, so a GitHub Enterprise Server URL still parses directly (#8312).
+  // Why: match any host (not just github.com) so a GHES PR URL still parses (#8312).
   const urlMatch = trimmed.match(/https?:\/\/[^\s/]+\/[^\s/]+\/[^\s/]+\/pull\/(\d+)/)
   if (!urlMatch) {
     return null
@@ -1762,11 +1680,7 @@ function parseCreatePRPayload(stdout: string): { number: number; url: string } |
   return { number: Number(urlMatch[1]), url: urlMatch[0] }
 }
 
-// Why: `gh --repo OWNER/REPO` resolves the shorthand against gh's default host
-// (usually github.com), not the repo's remote — so a GHES repo would target a
-// same-named github.com repo, or fail. Qualify with the host for GHES so gh hits
-// the Enterprise server; this is the only host signal for SSH repos, which run
-// gh with no cwd context (#8312). github.com keeps the bare shorthand.
+// Why: bare OWNER/REPO resolves against gh's default host, so qualify with host for GHES; the only host signal for cwd-less SSH repos (#8312).
 function ghRepoArg(slug: { owner: string; repo: string; host?: string }): string {
   return slug.host && slug.host.toLowerCase() !== 'github.com'
     ? `${slug.host}/${slug.owner}/${slug.repo}`
@@ -1860,11 +1774,8 @@ export async function createGitHubPullRequest(
     }
   }
 
-  // Why: github.com-only slug parsing returns null for GHES, so fall back to the
-  // enterprise resolver (gh-authenticated custom host) before giving up (#8312).
-  // Creation targets origin: the head branch is unqualified, so `gh pr create`
-  // must run against the repo the branch was pushed to, not the fork parent
-  // (getOwnerRepo became upstream-first for PR reads in #7331).
+  // Why: github.com-only slug parsing returns null for GHES; fall back to the enterprise resolver (#8312).
+  // Why: use origin, not the fork parent — the unqualified head branch was pushed there (getOwnerRepo upstream-first since #7331).
   const ownerRepo =
     (await getOwnerRepoForRemote(
       repoPath,
@@ -2029,11 +1940,7 @@ export async function getWorkItem(
         return issue
       }
     } catch (err) {
-      // Why: a transient failure (5xx, rate limit, network flake) on issue #N would
-      // silently fall through to PR #N — potentially a completely unrelated item.
-      // Only fall through when the issue genuinely doesn't exist (404); re-throw everything
-      // else so the outer catch returns null and the caller sees a real failure instead of
-      // a wrong item. classifyGhError centralizes the 404/"not found" pattern-matching.
+      // Why: only fall through to PR #N on a genuine 404; re-throw transient errors so a flake can't surface an unrelated PR.
       const stderr = err instanceof Error ? err.message : String(err)
       if (classifyGhError(stderr).type !== 'not_found') {
         throw err
@@ -2130,8 +2037,7 @@ const GITHUB_AUTO_MERGE_METHODS: Record<GitHubPRMergeMethod, 'MERGE' | 'SQUASH'
 
 export type GitHubPRBranchLookupOptions = HostedReviewExecutionOptions & {
   acceptMergedFallbackPR?: boolean
-  // Why: compare merged implicit PRs against the inspected worktree HEAD, not
-  // the main repo HEAD, without adding a worktree-scoped git call.
+  // Why: compare merged implicit PRs against the worktree HEAD, not main repo HEAD, without a worktree-scoped git call.
   currentHeadOid?: string | null
 }
 
@@ -2172,9 +2078,7 @@ function mapRestPullRequest(pr: RestPullRequest): PullRequestLookupData {
 }
 
 function isMergedImplicitPR(data: PullRequestLookupData, linkedPRNumber?: number | null): boolean {
-  // Why: merged PRs are historical branch matches unless the worktree has an
-  // explicit PR link. Showing them as implicit review context leaves nothing
-  // meaningful to unlink after the branch has been rebased or merged.
+  // Why: a merged PR without an explicit link is just a historical branch match, not implicit review context.
   return typeof linkedPRNumber !== 'number' && mapPRState(data.state, data.isDraft) === 'merged'
 }
 
@@ -2205,8 +2109,7 @@ function shouldHideMergedImplicitPR(
   if (!data || !isMergedImplicitPR(data, linkedPRNumber)) {
     return false
   }
-  // Why: keep hiding historical merged branch matches, but preserve the merged
-  // PR for the exact commit currently checked out in the sidebar.
+  // Why: keep hiding historical merged branch matches, but preserve the merged PR for the exact commit currently checked out.
   return !currentHeadOid || data.headRefOid !== currentHeadOid
 }
 
@@ -2228,8 +2131,7 @@ function cacheRepositoryMergeMetadata(
 ): void {
   const now = Date.now()
   pruneRepositoryMergeMetadataCache(now)
-  // Why: merge metadata is keyed by user-controlled branch names. Keep the
-  // per-session cache bounded even if many short-lived branches are inspected.
+  // Why: merge metadata is keyed by user-controlled branch names; keep the cache bounded across many short-lived branches.
   repositoryMergeMetadataCache.delete(cacheKey)
   repositoryMergeMetadataCache.set(cacheKey, {
     value,
@@ -2321,8 +2223,7 @@ async function detectRepositoryMergeMetadata(
     cacheRepositoryMergeMetadata(cacheKey, value, MERGE_QUEUE_CACHE_TTL_MS)
     return value
   } catch {
-    // Why: failed merge-queue probes should stay conservative without
-    // retrying GraphQL on every status poll while GitHub/network is unhappy.
+    // Why: cache a conservative result for failed merge-queue probes so we don't retry GraphQL on every poll while GitHub/network is unhappy.
     const value: GitHubRepositoryMergeMetadata = {
       mergeQueueRequired: null,
       autoMergeAllowed: null
@@ -2445,8 +2346,7 @@ function beginTrackedUpstreamSnapshotProbe(cacheKey: string): symbol {
 }
 
 function finishTrackedUpstreamSnapshotProbe(cacheKey: string, generation: symbol): void {
-  // Why: generations only guard an active probe; retaining completed repo keys
-  // leaks worktree/runtime identities after the short-lived snapshot TTL expires.
+  // Why: generations only guard an active probe; retaining completed keys leaks worktree/runtime identities past the snapshot TTL.
   if (trackedUpstreamSnapshotGenerations.get(cacheKey) === generation) {
     trackedUpstreamSnapshotGenerations.delete(cacheKey)
   }
@@ -2458,8 +2358,7 @@ function pruneTrackedUpstreamSnapshotCache(now: number): void {
       trackedUpstreamSnapshotCache.delete(cacheKey)
     }
   }
-  // Why: workspace/runtime churn can create unbounded unique keys within one
-  // TTL window, so expiry sweeping alone is not a memory bound.
+  // Why: workspace/runtime churn can create unbounded unique keys within one TTL window, so expiry sweeping alone isn't a memory bound.
   while (trackedUpstreamSnapshotCache.size > TRACKED_UPSTREAM_SNAPSHOT_CACHE_MAX_ENTRIES) {
     const oldestKey = trackedUpstreamSnapshotCache.keys().next().value
     if (oldestKey === undefined) {
@@ -2549,8 +2448,7 @@ async function getTrackedUpstreamBranch(
     if (result.upstreamsByBranchName.has(branchName)) {
       return result.upstreamsByBranchName.get(branchName) ?? null
     }
-    // Why: a concurrent snapshot may finish before this branch exists in git.
-    // Re-probe instead of returning a one-shot synthetic null.
+    // Why: a concurrent snapshot may finish before this branch exists in git; re-probe instead of returning a synthetic null.
     const retryInFlight = trackedUpstreamSnapshotInFlight.get(cacheKey)
     if (retryInFlight) {
       const retryResult = await retryInFlight
@@ -2558,9 +2456,7 @@ async function getTrackedUpstreamBranch(
     }
   }
 
-  // Why: PR polling can ask about hundreds of local worktree branches at once.
-  // Read the branch upstream snapshot in one git process per repo/runtime
-  // instead of spawning one failing `branch@{upstream}` probe per branch.
+  // Why: PR polling asks about hundreds of branches at once; read all upstreams in one git process per repo/runtime, not one probe per branch.
   const probeGeneration = beginTrackedUpstreamSnapshotProbe(cacheKey)
   const probe = probeTrackedUpstreamSnapshot(repoPath, connectionId, localGitOptions)
   trackedUpstreamSnapshotInFlight.set(cacheKey, probe)
@@ -2615,8 +2511,7 @@ async function probeTrackedUpstreamSnapshot(
   const gitConfigSignature =
     startingGitConfigSignature === endingGitConfigSignature ? endingGitConfigSignature : undefined
   return {
-    // Why: transient git failures must not cache an empty snapshot that forces
-    // every branch lookup to delete and re-probe on the next refresh tick.
+    // Why: don't cache an empty snapshot after a transient git failure, or every branch lookup re-probes on the next refresh tick.
     cacheable: !configSignatureChanged && !probeFailed,
     probeFailed,
     ...(gitConfigSignature ? { gitConfigSignature } : {}),
@@ -2627,8 +2522,7 @@ async function probeTrackedUpstreamSnapshot(
 function getCacheableTrackedUpstreamSnapshot(
   upstreamsByBranchName: Map<string, TrackedUpstreamBranch | null>
 ): Map<string, TrackedUpstreamBranch | null> {
-  // Why: SSH/WSL cannot cheaply inspect remote .git/config here. The short TTL
-  // still bounds stale positives, while repeated PR refreshes share one scan.
+  // Why: SSH/WSL can't cheaply inspect remote .git/config here; the short TTL bounds stale positives while refreshes share one scan.
   return upstreamsByBranchName
 }
 
@@ -2744,8 +2638,7 @@ async function lookupPRByBranchName(args: {
               args.ghOptions
             )
           : await getFallbackPRListForBranch(candidate, args.branchName, args.ghOptions)
-        // Why: REST/list branch lookup identifies the PR cheaply; exact
-        // `gh pr view` carries review, merge queue, and auto-merge state.
+        // Why: REST/list branch lookup identifies the PR cheaply; exact `gh pr view` carries review, merge-queue, and auto-merge state.
         const data = await hydrateBranchLookupWithExactPR(candidate, branchData, args.ghOptions)
         if (data) {
           return { data, dataRepo: candidate }
@@ -2777,8 +2670,7 @@ async function lookupPRByBranchName(args: {
         }
       }
     }
-    // Why: branch-list failures are ambiguous for fork discovery, but exact
-    // fallback-number recovery should still get a chance before surfacing error.
+    // Why: branch-list failures are ambiguous for fork discovery; give exact fallback-number recovery a chance before surfacing the error.
     return hasPendingError
       ? { data: null, dataRepo: null, pendingError }
       : { data: null, dataRepo: null }
@@ -2837,8 +2729,7 @@ async function getPRByNumber(
       ghOptions
     )
   } catch (err) {
-    // Why: deleted or manually edited linked PR metadata should fall back to
-    // branch discovery; quota/auth/network failures get one cheaper REST exact lookup.
+    // Why: deleted/edited linked PR metadata falls back to branch discovery; quota/auth/network failures get one cheaper REST exact lookup.
     if (isNotFoundGhError(err)) {
       return null
     }
@@ -2892,8 +2783,7 @@ async function lookupPRByNumber(args: {
     }
   } catch (err) {
     if (isNoPullRequestError(err)) {
-      // Why: stale cached fallback numbers should not turn every poll into an
-      // error when the PR was deleted or belonged to a different repo.
+      // Why: stale cached fallback numbers shouldn't error every poll when the PR was deleted or belongs to another repo.
       return { data: null, dataRepo: null }
     }
     throw err
@@ -2941,10 +2831,7 @@ export async function getPRForBranch(
   return outcome.kind === 'found' ? outcome.pr : null
 }
 
-// Why: the exact-linked fallback (`gh pr view` with no resolved repo candidates)
-// returns dataRepo=null, which would leave the merged-PR membership probe unable
-// to run. Derive the PR's own repo from its web URL so a diverged merged linked
-// PR can still be confirmed and cleared. Host-agnostic to cover GitHub Enterprise.
+// Why: exact-linked fallback returns dataRepo=null; derive the PR's repo from its web URL (host-agnostic for GHE) so the merged-PR membership probe can run.
 function ownerRepoFromPullRequestUrl(url: string): OwnerRepo | null {
   const match = url.match(/^https?:\/\/[^/\s]+\/([^/\s]+)\/([^/\s]+)\/pull\/\d+/)
   return match ? { owner: match[1], repo: match[2] } : null
@@ -2958,10 +2845,8 @@ export async function getPRForBranchOutcome(
   fallbackPRNumber?: number | null,
   options: GitHubPRBranchLookupOptions = {}
 ): Promise<PRRefreshOutcome> {
-  // Strip refs/heads/ prefix if present
   const branchName = branch.replace(/^refs\/heads\//, '')
-  // Why: detached HEAD cannot use branch lookup, but an exact linked/fallback
-  // PR number remains safe to query and keeps review state visible.
+  // Why: detached HEAD can't use branch lookup, but an exact linked/fallback PR number is still safe to query and keeps review state visible.
   if (!branchName && typeof linkedPRNumber !== 'number' && typeof fallbackPRNumber !== 'number') {
     return { kind: 'no-pr', fetchedAt: Date.now() }
   }
@@ -3028,8 +2913,7 @@ export async function getPRForBranchOutcome(
         explicitCurrentHeadOid
       )
       if (membership === 'not-contained') {
-        // explicitCurrentHeadOid is non-null here (guarded above); record the
-        // exact head so consumers only clear the worktree that actually diverged.
+        // explicitCurrentHeadOid is non-null here (guarded above); record the exact diverged head so consumers clear only that worktree.
         headDivergedFromMergedPRAtOid = explicitCurrentHeadOid
       }
     }
@@ -3040,9 +2924,7 @@ export async function getPRForBranchOutcome(
       if (!candidate || !isMergedImplicitPR(candidate, linkedPRNumber)) {
         return false
       }
-      // Why: prefer the caller-supplied worktree HEAD; only shell out (against
-      // the main repo path) when no explicit oid is available, matching legacy
-      // behavior. This keeps merged-at-head PRs visible for secondary worktrees.
+      // Why: prefer the caller's worktree HEAD; only shell out (main repo path) when no explicit oid, keeping merged-at-head PRs visible for secondary worktrees.
       currentHeadOidForMergedImplicit ??=
         explicitCurrentHeadOid !== null
           ? explicitCurrentHeadOid
@@ -3050,10 +2932,7 @@ export async function getPRForBranchOutcome(
       if (!shouldHideMergedImplicitPR(candidate, linkedPRNumber, currentHeadOidForMergedImplicit)) {
         return false
       }
-      // Why: a worktree can sit behind its own PR's final head (update-branch
-      // merges, web-committed suggestions). A head that is one of the PR's own
-      // commits is the same line of work, not a reused branch name — keep the
-      // merged PR visible instead of offering "create a pull request".
+      // Why: a head that is one of the PR's own commits (update-branch/web commits) is the same work, not a reused branch name — keep the merged PR visible.
       return (
         (await mergedPRContainsHead(candidate, candidateRepo, currentHeadOidForMergedImplicit)) !==
         'contained'
@@ -3069,8 +2948,7 @@ export async function getPRForBranchOutcome(
       data = exactLookup.data
       dataRepo = exactLookup.dataRepo
     } else if (branchName) {
-      // During a rebase the worktree is in detached HEAD and branch is empty.
-      // An empty --head filter causes gh to return an arbitrary PR.
+      // During a rebase (detached HEAD) branch is empty; an empty --head filter makes gh return an arbitrary PR.
       const branchLookup = await lookupPRByBranchName({
         candidates,
         headRepo,
@@ -3084,8 +2962,7 @@ export async function getPRForBranchOutcome(
         hasPendingBranchLookupError = true
       }
       if (!data) {
-        // Why: the tracked upstream can identify the real PR head by branch
-        // name or by fork owner even when branch names match locally.
+        // Why: the tracked upstream identifies the real PR head by branch name or fork owner even when local branch names match.
         const upstreamBranch = await getTrackedUpstreamBranch(
           repoPath,
           branchName,
@@ -3154,16 +3031,11 @@ export async function getPRForBranchOutcome(
       explicitCurrentHeadOid !== null &&
       shouldHideMergedImplicitPR(data, linkedPRNumber, explicitCurrentHeadOid) &&
       (await mergedPRContainsHead(data, dataRepo, explicitCurrentHeadOid)) !== 'contained'
-    // Why no lazy-HEAD re-check on preservation: fallback numbers come from
-    // callers that already gated them on head equality or confirmed
-    // containment; re-hiding against the main-repo HEAD would blank
-    // deleted-head merged PRs that are deliberately kept visible.
+    // Why no lazy-HEAD re-check: fallback numbers were already gated on head equality/containment; re-hiding would blank kept deleted-head merged PRs.
     const shouldPreserveMergedFallback =
       !explicitHeadHidesMergedImplicitPR &&
       (fallbackConfirmedMergedBranch || options.acceptMergedFallbackPR === true)
-    // Why: a currently visible PR can be merged outside Orca; when the caller
-    // marks the fallback as visible review state, keep its lifecycle fresh even
-    // if GitHub no longer reports it by branch (for example deleted heads).
+    // Why: a visible PR can be merged outside Orca; keep a caller-marked fallback fresh even when GitHub no longer reports it by branch (e.g. deleted heads).
     if ((await hideMergedImplicitPR(data, dataRepo)) && !shouldPreserveMergedFallback) {
       return { kind: 'no-pr', fetchedAt: Date.now() }
     }
@@ -3440,8 +3312,7 @@ function mapGraphQLPendingApprovalCheckSuite(
     name: getPendingApprovalCheckSuiteName(suite, headSha, index),
     status: 'completed',
     conclusion: 'action_required',
-    // Why: suite-only approval blockers have no check run; use the suite page
-    // as the actionable destination when GraphQL exposes one.
+    // Why: suite-only approval blockers have no check run; link the suite page when GraphQL exposes one.
     url:
       nullableString(suite.url) ??
       (headSha ? getPendingApprovalCheckSuiteUrl(ownerRepo, headSha, suite.databaseId) : null)
@@ -3472,8 +3343,7 @@ function mapGraphQLPRChecksResponse(
       .map((context) => nullableNumber(context.checkSuite?.databaseId))
       .filter((id): id is number => id !== null)
   )
-  // Why: mixed-CI repos expose Jenkins/Prow/Tide as legacy status contexts
-  // inside the same rollup as check runs. Keep check-run metadata on collisions.
+  // Why: mixed-CI repos expose Jenkins/Prow/Tide as legacy status contexts in the same rollup; keep check-run metadata on name collisions.
   const legacyStatuses = contexts
     .filter(isGraphQLStatusContext)
     .map(mapGraphQLStatusContext)
@@ -3544,8 +3414,7 @@ async function getPRChecksViaRestFallback(
         .map(mapRestCommitStatus)
         .filter((check): check is PRCheckDetail => check !== null && !checkRunNames.has(check.name))
     } catch (err) {
-      // Why: the REST fallback is already degraded; keep richer check-run rows
-      // if the legacy-status enrichment fails.
+      // Why: REST fallback is already degraded; keep the richer check-run rows if legacy-status enrichment fails.
       console.warn('getPRChecks REST status fallback failed:', err)
     }
 
@@ -3612,8 +3481,7 @@ export async function getPRChecks(
       }
       const { stdout } = await ghExecFileAsync(fallbackArgs, ghOptions).catch((err: unknown) => {
         const { stderr } = extractExecError(err)
-        // Why: `gh pr checks` exits non-zero when a PR genuinely has no check
-        // runs yet. Treat that as an empty optional section, not a load failure.
+        // Why: `gh pr checks` exits non-zero when a PR has no check runs yet; treat that as empty, not a load failure.
         if (stderr.toLowerCase().includes('no checks reported')) {
           return { stdout: '[]', stderr }
         }
@@ -3644,8 +3512,7 @@ export async function getPRChecks(
     if (canUseGraphQLRollup) {
       await acquire()
       try {
-        // Why: --cache 60s saves rate-limit budget during polling, but when the
-        // user explicitly clicks refresh we must skip it so gh fetches fresh data.
+        // Why: --cache 60s saves rate-limit budget during polling; explicit refresh skips it for fresh data.
         const cacheArgs = options?.noCache ? [] : ['--cache', '60s']
         const { stdout } = await ghExecFileAsync(
           [
@@ -3672,8 +3539,7 @@ export async function getPRChecks(
           return checks
         }
       } catch (err) {
-        // Why: if GitHub's richer rollup query is unavailable, the older gh
-        // command still returns the combined check/status list for display.
+        // Why: fall back to older `gh pr checks` when GitHub's richer rollup query is unavailable.
         console.warn('getPRChecks via GraphQL rollup failed, falling back to gh pr checks:', err)
       } finally {
         release()
@@ -3821,8 +3687,7 @@ async function attachFailedJobLogTails(
     })
     .slice(0, PR_CHECK_LOG_TAIL_JOB_LIMIT)
 
-  // Why: failed workflows can have many jobs; cap log fetches so details remain
-  // a lazy, bounded follow-up request instead of a burst of hosted log downloads.
+  // Why: cap log fetches so failed-job details stay a bounded follow-up, not a burst of hosted log downloads.
   for (const job of failedJobs) {
     const cacheKey = getCheckJobLogTailCacheKey(job)
     if (!cacheKey) {
@@ -4042,9 +3907,7 @@ export async function rerunPRChecks(
   }
 }
 
-// Why: review thread resolution status and thread IDs are only available via
-// GraphQL. The REST pulls/{n}/comments endpoint does not expose them, so we
-// use GraphQL for review threads and REST for issue-level comments.
+// Why: review thread resolution status + thread IDs are GraphQL-only (REST pulls/{n}/comments omits them).
 const REVIEW_THREADS_QUERY = `
 query($owner: String!, $repo: String!, $pr: Int!) {
   repository(owner: $owner, name: $repo) {
@@ -4114,15 +3977,11 @@ export async function getPRComments(
   await acquire()
   try {
     if (ownerRepo) {
-      // Why: --cache 60s saves rate-limit budget during normal loads, but when the
-      // user explicitly clicks refresh we must skip it so gh fetches fresh data.
+      // Why: --cache 60s saves rate-limit budget on normal loads; explicit refresh skips it for fresh data.
       const cacheArgs = options?.noCache ? [] : ['--cache', '60s']
       const base = `repos/${ownerRepo.owner}/${ownerRepo.repo}`
 
-      // Why: use allSettled so a single failing endpoint (e.g. GraphQL
-      // permissions, transient network error) doesn't blank out all comments.
-      // Each source is parsed independently; failed sources contribute zero
-      // comments instead of aborting the entire fetch.
+      // Why: allSettled so one failing endpoint doesn't blank out all comments; failed sources contribute zero.
       const reviewThreadsGuard = rateLimitGuard('graphql')
       let reviewThreadsFetch: Promise<{ stdout: string; stderr: string } | null>
       if (reviewThreadsGuard.blocked) {
@@ -4151,10 +4010,7 @@ export async function getPRComments(
           ghOptions
         ),
         reviewThreadsFetch,
-        // Why: review summaries (approve, request changes, general comments) live
-        // under pulls/{n}/reviews, not under issue comments or review threads.
-        // Without this, a reviewer who submits "LGTM" without inline threads
-        // would have their comment silently dropped from the panel.
+        // Why: review summaries (approve/request-changes/general) live under pulls/{n}/reviews, not issue comments or threads.
         ghExecFileAsync(
           ['api', ...cacheArgs, `${base}/pulls/${prNumber}/reviews?per_page=100`],
           ghOptions
@@ -4260,9 +4116,7 @@ export async function getPRComments(
               threadId: thread.id,
               isResolved: thread.isResolved,
               isOutdated: thread.line == null,
-              // Why: GitHub nulls out line/startLine when the commented code is
-              // outdated (e.g. after a force-push). Fall back to originalLine which
-              // always preserves the line numbers from when the comment was created.
+              // Why: GitHub nulls line/startLine when the commented code is outdated (e.g. force-push); originalLine preserves the original numbers.
               line: thread.line ?? thread.originalLine ?? undefined,
               startLine: thread.startLine ?? thread.originalStartLine ?? undefined
             })
@@ -4274,8 +4128,7 @@ export async function getPRComments(
         }
       }
 
-      // Parse review summaries (REST) — only include reviews with a body,
-      // since empty-body reviews (e.g. approvals with no comment) add noise.
+      // Review summaries (REST); skip empty-body reviews (e.g. approvals with no comment) as noise.
       type RESTReview = {
         id: number
         user: { login: string; avatar_url: string; type?: string } | null
@@ -4581,9 +4434,7 @@ export async function mergePR(
       return { ok: false, error: mergeBlocker }
     }
 
-    // Don't use --delete-branch: it tries to delete the local branch which
-    // fails when the user's worktree is checked out on it. Branch cleanup
-    // is handled by worktree deletion (local) and GitHub's auto-delete setting (remote).
+    // Don't use --delete-branch: it deletes the local branch, which fails while the worktree is checked out on it.
     const args = ['pr', 'merge', String(prNumber), `--${method}`]
     if (ownerRepo) {
       args.push('--repo', `${ownerRepo.owner}/${ownerRepo.repo}`)
@@ -4636,9 +4487,7 @@ export async function setPRAutoMerge(
   }
 }
 
-// Why: GitHub rejects enabling auto-merge on a PR that can already merge with
-// "Pull request is in clean status". Surface the actionable next step (merge
-// directly) instead of the raw GraphQL error.
+// Why: GitHub rejects auto-merge on an already-mergeable PR ("clean status"); surface an actionable message instead of the raw error.
 function classifySetAutoMergeError(message: string): string {
   if (/in clean status/i.test(message)) {
     return 'This pull request can already be merged. Use Merge instead of auto-merge.'
@@ -4734,8 +4583,7 @@ async function enablePRAutoMerge(
   if (pr.headRefOid) {
     args.push('-f', `expectedHeadOid=${pr.headRefOid}`)
   }
-  // Why: `gh pr merge --auto` can perform an immediate merge; this mutation
-  // only creates GitHub's auto-merge request and lets branch requirements gate it.
+  // Why: `gh pr merge --auto` can merge immediately; this mutation only creates the auto-merge request, letting branch requirements gate it.
   await ghExecFileAsync(args, {
     ...ghOptions,
     env: { ...process.env, GH_PROMPT_DISABLED: '1' }
@@ -4769,8 +4617,7 @@ async function getPRMergeBlocker(
     if (pr.mergeQueueRequired === true) {
       return 'This pull request must be merged through GitHub merge queue. Use Merge when ready instead.'
     }
-    // Why: conflict summaries shell out to local git; SSH repo paths are remote-only
-    // until that helper is routed through the SSH git provider.
+    // Why: conflict summaries shell out to local git; skip for SSH repos until that helper routes through the SSH provider.
     if (
       connectionId ||
       pr.mergeable !== 'CONFLICTING' ||
@@ -4790,8 +4637,7 @@ async function getPRMergeBlocker(
     )
     return formatMergeConflictBlocker(pr.baseRefName, summary)
   } catch {
-    // Why: conflict preflight should improve stale UI diagnostics, not make
-    // merge impossible when the lookup endpoint has a transient failure.
+    // Why: conflict preflight should improve stale UI diagnostics, not block merge on a transient lookup failure.
     return null
   }
 }
@@ -4827,8 +4673,7 @@ export async function updatePRState(
   await acquire()
   try {
     const cmd = updates.state === 'closed' ? 'close' : 'reopen'
-    // Why: GitHub can reject REST pull state PATCHes for reopen paths with a
-    // generic 422; gh's PR commands use GitHub's supported reopen flow.
+    // Why: gh's PR commands use GitHub's supported reopen flow; REST state PATCH can 422 on reopen.
     await ghExecFileAsync(
       ['pr', cmd, String(prNumber), '--repo', `${ownerRepo.owner}/${ownerRepo.repo}`],
       {
diff --git a/src/main/github/pr-refresh-coordinator.ts b/src/main/github/pr-refresh-coordinator.ts
index 700cc32ecd2..592bea4870b 100644
--- a/src/main/github/pr-refresh-coordinator.ts
+++ b/src/main/github/pr-refresh-coordinator.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: the coordinator keeps queueing, pacing, and
-renderer broadcast rules together so freshness and rate-limit invariants are
-reviewable in one place. */
+/* eslint-disable max-lines -- Why: queueing, pacing, and broadcast rules stay together so freshness and rate-limit invariants are reviewable in one place. */
 import { webContents } from 'electron'
 import type {
   GitHubPRRefreshAlias,
@@ -83,16 +81,13 @@ const queue = new Map<string, QueueEntry>()
 const backgroundStarts: number[] = []
 const activeStartsByScope = new Map<string, number[]>()
 const errorBackoff = new Map<string, { failures: number; retryAt: number }>()
-// Per-key manual-retry cooldown from a real secondary rate limit (Retry-After).
-// refreshPRNow refuses a manual retry until this time so a stale renderer cannot
-// bypass the gate the client advertised via `retryDisabledUntil`.
+// Per-key manual-retry cooldown (secondary rate-limit Retry-After); refreshPRNow refuses manual retry until this time so a stale renderer can't bypass it.
 const manualRetryGates = new Map<string, number>()
 let lastBackgroundStartAt = 0
 
 /**
  * Track (or clear) the manual-retry cooldown for a key from a broadcast outcome.
- * Only a rate-limit outcome carrying `retryDisabledUntil` sets a gate; any other
- * settled outcome clears it.
+ * Only a rate-limit outcome carrying `retryDisabledUntil` sets a gate; any other settled outcome clears it.
  */
 function noteManualRetryGate(key: string, outcome: PRRefreshOutcome): void {
   if (outcome.kind === 'upstream-error' && outcome.retryDisabledUntil !== undefined) {
@@ -169,8 +164,7 @@ export function clearVisiblePRRefreshWindow(windowId: number): void {
   const hadVisibleRefreshes = visibleByWindow.delete(windowId)
   clearActiveBurstWindow(windowId)
   if (hadVisibleRefreshes) {
-    // Why: visible follow-ups are owned by the renderer that reported them.
-    // If that WebContents is destroyed, no later visibility report may arrive.
+    // Why: visible follow-ups are owned by the reporting renderer; if its WebContents is destroyed, no later visibility report arrives.
     removeInvisibleVisibleRefreshes()
   }
 }
@@ -178,12 +172,7 @@ export function clearVisiblePRRefreshWindow(windowId: number): void {
 /**
  * Drop a removed worktree's aliases from every queue entry.
  *
- * Why: many local branches/worktrees that resolve to the same PR coalesce into
- * one queue entry whose `aliases` map keeps one entry per worktree. Aliases are
- * only pruned when a candidate is re-enqueued as invalid — never when a worktree
- * is simply removed. Over a long session with churning worktrees these maps grow
- * unbounded, contributing to the renderer/process memory creep behind the OOM
- * reports. Called from worktree removal so stale aliases are released promptly.
+ * Why: aliases are otherwise only pruned when a candidate is re-enqueued as invalid, so churning worktrees grow these maps unbounded (OOM creep).
  */
 export function pruneWorktreePRRefreshAliases(worktreeId: string): void {
   for (const [key, entry] of queue) {
@@ -203,8 +192,7 @@ export function pruneWorktreePRRefreshAliases(worktreeId: string): void {
       resetKeyRetryState(key)
       continue
     }
-    // Keep the entry alive but ensure its representative candidate is not a
-    // dangling reference to the removed worktree.
+    // Keep the entry alive but replace its representative so it isn't a dangling reference to the removed worktree.
     if (entry.candidate.worktreeId === worktreeId) {
       const replacementAlias = entry.aliases.values().next().value
       if (replacementAlias) {
@@ -213,9 +201,7 @@ export function pruneWorktreePRRefreshAliases(worktreeId: string): void {
           cacheKey: replacementAlias.cacheKey,
           branch: replacementAlias.branch,
           worktreeId: replacementAlias.worktreeId,
-          // Why: the probe now represents the replacement worktree, so it must
-          // use that worktree's head — otherwise divergence is stamped for the
-          // removed worktree's head and the survivor's link is never cleared.
+          // Why: the probe now represents the replacement worktree, so use its head — else the removed worktree's link never clears.
           currentHeadOid: replacementAlias.currentHeadOid ?? null
         }
       }
@@ -382,8 +368,7 @@ function setVisibleFollowUp(entry: QueueEntry): void {
     existing.aliases.set(alias.cacheKey, alias)
   }
 
-  // Why: a user activation can arrive while a background refresh is awaiting gh.
-  // The background follow-up must not overwrite that pending active/manual work.
+  // Why: a user activation can arrive while a background refresh awaits gh; the follow-up must not overwrite that pending active/manual work.
   if (
     bypassesFreshnessDelay(existing.reason) ||
     existing.priority > entry.priority ||
@@ -418,9 +403,7 @@ function removeQueuedAliasForInvalidCandidate(key: string, alias: GitHubPRRefres
       cacheKey: replacementAlias.cacheKey,
       branch: replacementAlias.branch,
       worktreeId: replacementAlias.worktreeId,
-      // Why: the probe now represents the replacement worktree, so it must use
-      // that worktree's head — otherwise divergence is stamped for the pruned
-      // candidate's head and the survivor's link is never cleared.
+      // Why: the probe now represents the replacement worktree, so use its head — else the survivor's link never clears.
       currentHeadOid: replacementAlias.currentHeadOid ?? null,
       isArchived: false,
       isBare: false
@@ -430,8 +413,7 @@ function removeQueuedAliasForInvalidCandidate(key: string, alias: GitHubPRRefres
 
 /**
  * Advances the visible-key error backoff and returns the earliest retry time.
- * The renderer surfaces this as `nextAutoRetryAt`; only visible keys auto-retry,
- * so callers must gate on `isVisibleKey` before computing a schedule.
+ * Why: only visible keys auto-retry, so callers must gate on `isVisibleKey` first.
  */
 function nextVisibleErrorRetryAt(key: string): number {
   const failures = (errorBackoff.get(key)?.failures ?? 0) + 1
@@ -442,23 +424,14 @@ function nextVisibleErrorRetryAt(key: string): number {
 }
 
 /**
- * Stamps the auto-retry time onto an error outcome before broadcast so every
- * alias receives identical timing.
- *
- * Why: this only sets `nextAutoRetryAt` (the "Orca will retry at {time}" hint).
- * It must NOT set `retryDisabledUntil` — that field disables *manual* Retry and
- * is reserved for a real rate-limit gate (the paused/breaker path in
- * `refreshPRNow`, which maps `pausedUntil` into it). Deriving it from ordinary
- * exponential backoff would disable a manual Retry that `refreshPRNow` would in
- * fact accept.
+ * Stamps the auto-retry time onto an error outcome before broadcast.
+ * Why: sets only `nextAutoRetryAt`, never `retryDisabledUntil` — that disables *manual* Retry and is reserved for a real rate-limit gate.
  */
 function withErrorSchedule(outcome: PRRefreshOutcome, retryAt: number): PRRefreshOutcome {
   if (outcome.kind !== 'upstream-error') {
     return outcome
   }
-  // Why: preserve a real Retry-After cooldown the client already stamped on the
-  // outcome (`retryDisabledUntil`); auto-retry no earlier than both the backoff
-  // and that cooldown so we do not retry into an active secondary rate limit.
+  // Why: honor a real Retry-After cooldown the client stamped (`retryDisabledUntil`) so we don't auto-retry into an active secondary rate limit.
   const cooldownUntil = outcome.retryDisabledUntil
   return {
     ...outcome,
@@ -476,14 +449,12 @@ function scheduleVisibleFollowUp(
   options?: { pendingMergeabilityDelayMs?: number; plannedRetryAt?: number }
 ): void {
   if (!isVisibleKey(key)) {
-    // Why: manual/active refreshes can remove the queued visible retry after
-    // its owner window is gone, leaving the retry backoff without an owner.
+    // Why: manual/active refreshes can remove the queued visible retry after its owner window is gone, orphaning the backoff.
     resetKeyRetryState(key)
     return
   }
   if (outcome.kind === 'upstream-error') {
-    // Why: reuse the retry time already computed for the broadcast schedule so
-    // the same failure is not counted twice against the backoff.
+    // Why: reuse the retry time already computed for the broadcast so the same failure isn't counted twice against the backoff.
     const retryAt = options?.plannedRetryAt ?? nextVisibleErrorRetryAt(key)
     setVisibleFollowUp({
       key,
@@ -495,8 +466,7 @@ function scheduleVisibleFollowUp(
       queuedAt: nextQueueOrder(),
       windowId
     })
-    // Why: this is a delayed retry, not active work; showing it as a spinner
-    // makes visible worktrees look stuck until the backoff expires.
+    // Why: this is a delayed retry, not active work; a spinner would make visible worktrees look stuck until backoff expires.
     scheduleDrain(retryAt - Date.now())
     return
   }
@@ -511,9 +481,7 @@ function scheduleVisibleFollowUp(
     pendingMergeabilityDueAt === null
       ? regularDueAt
       : Math.min(regularDueAt, pendingMergeabilityDueAt)
-  // Why: coalesced linked-PR refreshes may represent several local branches.
-  // Preserve every alias for the next visible follow-up so all cache entries
-  // keep receiving periodic updates.
+  // Why: a coalesced linked-PR refresh may represent several branches; preserve every alias so all cache entries keep getting updates.
   setVisibleFollowUp({
     key,
     candidate: followUpCandidate,
@@ -522,8 +490,7 @@ function scheduleVisibleFollowUp(
     priority,
     dueAt,
     queuedAt: nextQueueOrder(),
-    // Why: this manual one-shot fixes GitHub's transient UNKNOWN state; visible
-    // spacing would otherwise delay it past the intended prompt retry window.
+    // Why: this manual one-shot fixes GitHub's transient UNKNOWN state; visible spacing would delay it past the prompt retry window.
     bypassBackgroundBudget: pendingMergeabilityDueAt !== null,
     windowId
   })
@@ -543,8 +510,7 @@ function refreshIntervalForCandidate(candidate: GitHubPRRefreshCandidate): numbe
     candidate.cachedMergeable === 'UNKNOWN' &&
     !hasResolvedMergeStateStatus(candidate.cachedMergeStateStatus)
   ) {
-    // Why: GitHub can return transient UNKNOWN mergeability while it computes
-    // the PR test merge; visible merge buttons need a prompt follow-up.
+    // Why: GitHub returns transient UNKNOWN mergeability while computing the test merge; visible merge buttons need a prompt follow-up.
     return MERGEABILITY_PENDING_REFRESH_MS
   }
   if (candidate.cachedChecksStatus === 'success') {
@@ -573,9 +539,7 @@ function isMergeabilityPendingOutcome(outcome: PRRefreshOutcome): boolean {
 }
 
 function backgroundRefreshBuckets(): ('core' | 'graphql')[] {
-  // Why: branch refreshes prefer REST but can still fall back to `gh pr list`
-  // when local head-owner metadata is unavailable. Guard both buckets until the
-  // client exposes an exact per-lookup cost plan.
+  // Why: branch refreshes prefer REST but can fall back to `gh pr list`, so guard both buckets until the client exposes a per-lookup cost plan.
   return ['core', 'graphql']
 }
 
@@ -648,8 +612,7 @@ function activeOrder(a: QueueEntry, b: QueueEntry): number {
   if (activeBurstScope(a) !== activeBurstScope(b)) {
     return 0
   }
-  // Why: activation churn should refresh the worktree the user lands on before
-  // stale transient selections from the same window/runtime scope.
+  // Why: refresh the worktree the user lands on before stale transient selections in the same window/runtime scope.
   return b.queuedAt - a.queuedAt
 }
 
@@ -765,10 +728,7 @@ async function drainQueue(): Promise<void> {
       )
 
       if (isBackground(next.reason)) {
-        // Why: the probe only warms rateLimitGuard's cached snapshot, so a
-        // failed probe must fail open — GHES with rate limiting disabled 404s
-        // every probe (#7553). A genuinely broken gh surfaces per-key as typed
-        // fetch outcomes instead (visible keys additionally back off).
+        // Why: the probe only warms rateLimitGuard's cache, so it must fail open — GHES with rate limiting disabled 404s every probe (#7553).
         await getRateLimit()
         const buckets = backgroundRefreshBuckets()
         const blockedGuard = buckets
@@ -791,8 +751,7 @@ async function drainQueue(): Promise<void> {
           noteBackgroundStart()
         }
         if (next.reason === 'active') {
-          // Why: activation is high priority, but tab/worktree churn can enqueue
-          // many distinct active refreshes that each probe local Git.
+          // Why: tab/worktree churn can enqueue many distinct active refreshes that each probe local Git.
           noteActiveStart(next)
         }
         for (const bucket of buckets) {
@@ -808,8 +767,7 @@ async function drainQueue(): Promise<void> {
         next.candidate.linkedPRNumber == null ? (next.candidate.fallbackPRNumber ?? null) : null,
         ...hostedReviewOptionArgs(next.candidate)
       )
-      // Why: compute the retry schedule before broadcasting so the outcome and
-      // its follow-up retry share one timing; only visible keys auto-retry.
+      // Why: compute the retry schedule before broadcasting so the outcome and its follow-up share one timing; only visible keys auto-retry.
       let plannedRetryAt: number | undefined
       let broadcastOutcome = outcome
       if (outcome.kind === 'upstream-error' && isVisibleKey(next.key)) {
@@ -882,11 +840,7 @@ export function enqueuePRRefresh(
       existing.candidate = candidate
       existing.windowId = windowId ?? existing.windowId
     } else if (existing.candidate.worktreeId === candidate.worktreeId) {
-      // Why: a non-promoting coalesce (e.g. visible→visible) keeps the existing
-      // representative, but the representative drives the probe head. If its own
-      // worktree moved head/branch, refresh those probe inputs so divergence is
-      // stamped for the current head — otherwise the head-scoped clear never
-      // matches and a merged linked PR lingers after a branch switch.
+      // Why: the representative drives the probe head; refresh probe inputs when its worktree moved head/branch, else a merged linked PR lingers after a switch.
       existing.candidate = {
         ...existing.candidate,
         cacheKey: candidate.cacheKey,
@@ -908,8 +862,7 @@ export function enqueuePRRefresh(
       windowId
     })
   }
-  // Why: visible/SWR refreshes are background maintenance and may sit behind
-  // the budget queue. Only user/action-driven queueing should surface in UI.
+  // Why: visible/SWR are background maintenance behind the budget queue; only user/action-driven queueing should surface in UI.
   if (shouldBroadcastQueued(reason, dueAt)) {
     broadcast({ aliases: [alias], reason, status: 'queued' })
   }
@@ -968,11 +921,7 @@ export async function refreshPRNow(candidate: GitHubPRRefreshCandidate): Promise
     return outcome
   }
 
-  // Why: enforce the same rate-limit gate main advertises via `retryDisabledUntil`
-  // so a stale renderer cannot bypass it. A blocked primary bucket means gh would
-  // 403 anyway; a recorded secondary Retry-After cooldown means gh would 429
-  // again. Refuse without spending quota until the later of the two and report
-  // the pause honestly.
+  // Why: enforce the rate-limit gate so a stale renderer can't bypass it; refuse without spending quota until the later of the two cooldowns.
   const manualBlockedGuard = backgroundRefreshBuckets()
     .map((bucket) => rateLimitGuard(bucket))
     .find((guard) => guard.blocked)
@@ -983,11 +932,7 @@ export async function refreshPRNow(candidate: GitHubPRRefreshCandidate): Promise
   )
   if (gateUntil > Date.now()) {
     const retryAt = gateUntil
-    // Why: the paused broadcast maps `pausedUntil` into the renderer's
-    // `nextAutoRetryAt` ("Orca will retry at {time}"), so that auto-retry must be
-    // real. Requeue this candidate at the reset time and wake the drain then —
-    // mirroring the background paused path — instead of advertising an automatic
-    // retry that was never scheduled (finding 12).
+    // Why: paused maps `pausedUntil` into the renderer's auto-retry, so requeue at reset (finding 12) — don't advertise an unscheduled retry.
     queue.set(key, {
       key,
       candidate,
@@ -1041,8 +986,7 @@ export async function refreshPRNow(candidate: GitHubPRRefreshCandidate): Promise
   )
   scheduleVisibleFollowUp(key, candidate, outcome, 40, aliases, undefined, {
     plannedRetryAt,
-    // Why: GitHub often reports UNKNOWN immediately after `gh pr reopen`;
-    // do one prompt visible retry so conflicts replace the transient label.
+    // Why: GitHub reports UNKNOWN right after `gh pr reopen`; one prompt visible retry replaces the transient label.
     pendingMergeabilityDelayMs: MANUAL_MERGEABILITY_PENDING_REFRESH_MS
   })
   return broadcastOutcome
diff --git a/src/main/github/project-view.ts b/src/main/github/project-view.ts
index 3a040d37520..8e2be18044e 100644
--- a/src/main/github/project-view.ts
+++ b/src/main/github/project-view.ts
@@ -1,9 +1,4 @@
-/* eslint-disable max-lines -- Why: ProjectV2 GraphQL has its own normalization
-layer, retry policy (parent-field dance), paste-to-add parser, and discovery
-pagination. Co-locating the read path keeps the retry/classify/normalize
-contract reviewable as one surface. Lower-level plumbing (slug validation,
-error classifier, runGraphql/runRest) lives in ./project-view/internals; the
-slug-addressed write path lives in ./project-view/mutations. */
+/* eslint-disable max-lines -- Why: co-locate the ProjectV2 read path (normalize/retry/paste-parser/discovery) as one reviewable surface; plumbing lives in ./project-view/internals and mutations. */
 import {
   acquire,
   release,
@@ -52,8 +47,7 @@ import {
   isGitHubProjectRefInputTooLarge
 } from '../../shared/github-project-ref-input'
 
-// Re-export the public API so existing call sites (`./project-view`) keep
-// working unchanged. The split is internal-only.
+// Re-export the public API so existing `./project-view` call sites keep working; the split is internal-only.
 export {
   isValidOwnerSlug,
   isValidRepoSlug,
@@ -77,14 +71,7 @@ export {
 
 // ─── Constants ─────────────────────────────────────────────────────────
 
-// Why: these defaults were deliberately shrunk from 50/50/100 to cut quota
-// spend in the most expensive gh call reachable from TaskPage. Discovery
-// walks viewer projects, then up to `DISCOVERY_MAX_ORGS` orgs × a nested
-// `projectsV2(first:N)` query. The org loop dominates the cost and is the
-// path that produced the user-visible HTTP 504 when one org was slow. Users
-// with projects outside this window can still paste a URL to reach them —
-// no functional loss. Prior values: MAX_ORGS=50, ORG_PAGE_SIZE=30,
-// PROJECTS_PER_OWNER=100, nested projectsV2 first=50.
+// Why: defaults deliberately shrunk to cut quota spend in discovery — the org loop dominates and produced the HTTP 504; overflow owners can paste a URL.
 const ITEM_PAGE_SIZE = 100
 const MAX_ITEMS = 500
 const VIEWS_PAGE_SIZE = 20
@@ -98,9 +85,7 @@ export const PROJECT_VIEW_OWNER_CACHE_MAX_ENTRIES = 512
 
 // ─── Module-scope caches (reset on HMR — intentional) ──────────────────
 
-// Why: pasted and discovered GitHub owners are user-controlled across a long
-// main-process session; keep capability probes bounded to avoid unbounded
-// retention while preserving the hot-owner fast path.
+// Why: owners are user-controlled over a long session; bound cache entries to avoid unbounded retention while keeping the hot-owner fast path.
 function rememberProjectViewCacheEntry<K, V>(
   cache: Map<K, V>,
   key: K,
@@ -129,20 +114,12 @@ function getProjectViewCacheEntry<K, V>(cache: Map<K, V>, key: K): V | undefined
   return value
 }
 
-// Why: HMR reloading should re-probe capability. Both caches live as plain
-// module locals so a dev-time code swap naturally re-runs capability probes
-// instead of carrying a stale "unsupported" flag into fresh code.
+// Why: plain module locals so HMR code swaps re-run capability probes instead of carrying a stale "unsupported" flag.
 const ownerTypeCache = new Map<string, GitHubProjectOwnerType | null>()
-// Why: keyed by `${owner}\0${ownerType}` rather than a process-global flag so
-// a single owner's capability gap (e.g. token without scope on org A) doesn't
-// poison every subsequent fetch for unrelated owners that DO support
-// Issue.parent. See bug-scan finding 2.
+// Why: keyed per owner (not a process-global flag) so one owner's capability gap doesn't poison others that DO support Issue.parent (bug-scan finding 2).
 const parentFieldRetriedByOwner = new Map<string, true>()
 const parentFieldWarningLoggedByOwner = new Map<string, true>()
-// Why: concurrent fetchAllItems calls for the same owner all observe the
-// same "not-yet-retried" state, each issuing a duplicate first-page probe
-// and racing to set the flag. Use an in-flight promise per owner so only
-// one caller drives the probe; siblings await the same result.
+// Why: in-flight promise per owner so concurrent fetchAllItems callers share one probe instead of each racing a duplicate first-page probe.
 const parentFieldProbeInFlight = new Map<string, Promise<void>>()
 
 function ownerScopeKey(owner: string, ownerType: GitHubProjectOwnerType): string {
@@ -392,8 +369,7 @@ export function normalizeFieldValue(
     }
     case undefined:
     default:
-      // Unknown __typename → forward-compat: drop silently, do not throw,
-      // do not classify as drift (see design §Error Handling).
+      // Unknown __typename → forward-compat: drop silently, don't classify as drift (see design §Error Handling).
       return null
   }
 }
@@ -713,13 +689,7 @@ async function fetchViewFieldsContinuation(
 ): Promise<
   { ok: true; fields: RawProjectV2Field[] } | { ok: false; error: GitHubProjectViewError }
 > {
-  // Why: address the view directly via `node(id:)` instead of re-fetching the
-  // whole project + walking views every page. Previous shape paid an
-  // unnecessary `${VIEWS_PAGE_SIZE}` views fan-out per field-continuation
-  // page; the new shape is one round-trip per field page, which is the
-  // minimum possible cost. Field-paged views are rare (>50 fields), so this
-  // only matters for the few projects that hit it — but when they do, the
-  // savings compound across pagination loops.
+  // Why: address the view directly via node(id:) instead of re-walking all views each page — one round-trip per field page.
   const query = `
     query($after:String!, $viewId:ID!) {
       node(id:$viewId) {
@@ -844,9 +814,7 @@ type RawItemsPage = {
   nodes?: (RawItem | null)[]
 }
 
-// Why: runGraphql returns the classified error but not the raw GraphQL
-// errors; for the parent-field retry decision we need those. This variant
-// returns the raw envelope so callers can re-inspect.
+// Why: unlike runGraphql, return the raw GraphQL error envelope so the parent-field retry decision can re-inspect it.
 async function fetchItemsPageWithRaw(args: {
   owner: string
   ownerType: GitHubProjectOwnerType
@@ -925,9 +893,7 @@ async function fetchItemsPageWithRaw(args: {
     try {
       parsed = JSON.parse(stdout)
     } catch {
-      // Why: when gh exits non-zero with no parseable JSON on stdout (network,
-      // auth, rate-limit, missing scope), classify against stderr so callers
-      // see the real cause instead of a synthesized drift/not-found.
+      // Why: gh exited non-zero with unparseable stdout; classify against stderr so callers see the real cause, not a synthesized drift/not-found.
       if (execFailed) {
         return {
           ok: false,
@@ -943,9 +909,7 @@ async function fetchItemsPageWithRaw(args: {
         stderr
       }
     }
-    // Why: gh exec rejected but stdout still had a parseable error envelope —
-    // fall through to the parsed.errors branch below. If parsed has neither
-    // data nor errors, surface the stderr classification rather than not_found.
+    // Why: gh rejected but stdout parsed; fall through to parsed.errors below, else surface the stderr classification rather than not_found.
     if (execFailed && (!parsed.errors || parsed.errors.length === 0) && !parsed.data) {
       return {
         ok: false,
@@ -987,26 +951,16 @@ async function fetchAllItems(args: {
   | { ok: true; rows: GitHubProjectRow[]; totalCount: number; parentFieldDropped: boolean }
   | { ok: false; error: GitHubProjectViewError; totalCount?: number }
 > {
-  // Why: caches keyed by (owner, ownerType) so a single owner's lack of
-  // Issue.parent capability (e.g. token without scope on org A) doesn't
-  // poison fetches for unrelated owners. See bug-scan finding 2.
+  // Why: keyed by (owner, ownerType) so one owner's missing Issue.parent capability doesn't poison unrelated owners.
   const scopeKey = ownerScopeKey(args.owner, args.ownerType)
-  // Why: if another caller for the SAME owner is currently probing whether
-  // Issue.parent is supported, await its decision so we don't fire a
-  // duplicate with-parent probe. We must re-read the retried flag AFTER
-  // awaiting because the probe may have flipped it.
+  // Why: await any in-flight same-owner probe so we don't duplicate it, then re-read the retried flag (the probe may have flipped it).
   const inFlight = parentFieldProbeInFlight.get(scopeKey)
   if (inFlight) {
     await inFlight.catch(() => {})
   }
   let includeParent = !hasParentFieldRetried(scopeKey)
   let parentFieldDropped = !includeParent
-  // First page — single-flight the with-parent attempt PER OWNER so
-  // concurrent callers for the same owner observe one probe result instead
-  // of each issuing their own. We must assign the in-flight promise
-  // synchronously (no await between the get() check and the set()) so
-  // concurrent callers race on the same promise rather than each creating
-  // a duplicate probe.
+  // Single-flight the with-parent probe per owner; assign the in-flight promise synchronously (no await between get() and set()) so callers share one probe.
   let first: Awaited<ReturnType<typeof fetchItemsPageWithRaw>>
   let probePromise: Promise<Awaited<ReturnType<typeof fetchItemsPageWithRaw>>> | null = null
   if (includeParent && !parentFieldProbeInFlight.has(scopeKey)) {
@@ -1026,12 +980,7 @@ async function fetchAllItems(args: {
           after: null,
           includeParent: true
         })
-        // Why: flip parentFieldRetriedByOwner BEFORE resolveProbe()/clearing
-        // parentFieldProbeInFlight so siblings that awoke on `inFlight.catch()`
-        // observe the updated flag. Doing this in the outer block (after
-        // `await probePromise`) leaves a gap where siblings see
-        // parentFieldProbeInFlight=null and parentFieldRetriedByOwner without
-        // the scopeKey, then issue duplicate with-parent probes.
+        // Why: set the retried flag BEFORE resolving/clearing the probe so siblings awoken on inFlight.catch() see it and don't fire duplicate with-parent probes.
         if (!result.ok && errorsIndicateParentField(result.rawErrors, result.stderr)) {
           markParentFieldRetried(scopeKey)
         }
@@ -1054,9 +1003,7 @@ async function fetchAllItems(args: {
     })
   }
   if (!first.ok && includeParent && errorsIndicateParentField(first.rawErrors, first.stderr)) {
-    // Retry the whole table without parent. Mark this owner as retried so
-    // subsequent fetches against the same owner skip the probe — but other
-    // owners are unaffected.
+    // Retry the whole table without parent; mark this owner retried so later fetches skip the probe (other owners unaffected).
     markParentFieldRetried(scopeKey)
     includeParent = false
     parentFieldDropped = true
@@ -1255,16 +1202,7 @@ export async function getProjectViewTable(
         matchStrength = m
       }
     }
-    // Why: stop as soon as we have ANY match — including 'default' (first
-    // table view). Continuing to walk views pages for a default selector
-    // costs one extra GraphQL call per page with no upside: the default
-    // contract is "first table view we see", and view layouts don't change
-    // ordering between pages such that a later view would outrank the
-    // first table layout. Previously we kept walking on default match
-    // because the precedence comment hinted at re-ranking, but no real
-    // selector promotes a 'default' to a stronger match within the same
-    // selector input — those ranks only matter when the caller supplied
-    // a selector. Bail early on any non-null selectedRaw.
+    // Why: stop on ANY match (incl. 'default' = first table view); walking further pages costs a GraphQL call per page with no re-ranking upside.
     if (selectedRaw) {
       break
     }
@@ -1300,15 +1238,11 @@ export async function getProjectViewTable(
   }
   const selectedView = finalized.view
 
-  // Why: an explicit empty-string override means "no filter"; treat undefined
-  // as "use the view's filter as-is". The override is ephemeral — never
-  // persisted to GitHub — so users can clear the search without mutating the
-  // view's stored filter.
+  // Why: empty-string override means "no filter"; undefined means "use the view's stored filter". The override is ephemeral, never persisted.
   const effectiveQuery =
     typeof args.queryOverride === 'string' ? args.queryOverride : selectedView.filter
 
-  // Unsupported layout: return without paginating items; attempt a cheap
-  // count-only query best-effort.
+  // Unsupported layout: skip item pagination; best-effort count-only query.
   if (selectedView.layout !== 'TABLE_LAYOUT') {
     const count = await fetchItemsCountOnly({
       owner: args.owner,
@@ -1389,10 +1323,7 @@ type RawViewerDiscovery = {
 export async function listAccessibleProjects(): Promise<ListAccessibleProjectsResult> {
   const viewerProjects: GitHubProjectSummary[] = []
   const orgProjects: GitHubProjectSummary[] = []
-  // Why: per-org failures are collected so the picker can render a "some orgs
-  // didn't load" banner with the affected logins, instead of aborting the
-  // whole discovery on the first 504. Users with flaky org fetches still get
-  // viewer + other orgs in the list.
+  // Why: collect per-org failures so the picker shows a "some orgs didn't load" banner instead of aborting discovery on the first 504.
   const partialFailures: { owner: string; message: string }[] = []
   let viewerLogin: string | null = null
 
@@ -1423,10 +1354,7 @@ export async function listAccessibleProjects(): Promise<ListAccessibleProjectsRe
     }
     const res = await runGraphql<RawViewerDiscovery>(query, vars)
     if (!res.ok) {
-      // Why: a viewer-level failure is structural — if we can't list the
-      // user's own projects, we have nothing to build on. Propagate as a
-      // hard error instead of returning partial. Org-level errors below
-      // are non-fatal because the viewer slice is still useful on its own.
+      // Why: viewer-level failure is structural (no projects to build on), so propagate hard; org-level errors below are non-fatal.
       return { ok: false, error: res.error }
     }
     if (!res.data.viewer) {
@@ -1463,13 +1391,7 @@ export async function listAccessibleProjects(): Promise<ListAccessibleProjectsRe
   }
 
   // 2) Organizations the viewer belongs to, each with its projectsV2.
-  // Why: we intentionally drop the per-org continuation loop that previously
-  // ran `organization(login).projectsV2(first:50, after:$after)` when the
-  // first nested page had more. That inner loop was the dominant cost
-  // multiplier and the most common 504 source — a single slow org would
-  // serially block the picker for tens of seconds. Users with more than
-  // DISCOVERY_PROJECTS_PER_ORG projects in a given org can still paste a
-  // URL to reach them; the picker is discovery, not an exhaustive index.
+  // Why: no per-org projectsV2 continuation loop — it was the dominant 504 cost; users past the cap can paste a URL instead.
   let orgCursor: string | null = null
   let orgMore = true
   let orgsSeen = 0
@@ -1498,11 +1420,7 @@ export async function listAccessibleProjects(): Promise<ListAccessibleProjectsRe
     }
     const res = await runGraphql<RawViewerDiscovery>(query, vars)
     if (!res.ok) {
-      // Why: the org-listing query itself failed (not a nested projectsV2).
-      // Record it as a partial failure against a synthetic `*` owner so the
-      // UI banner explains why additional orgs aren't listed, but keep any
-      // viewer projects we already collected. This is the critical 504 path
-      // the user reported in the ProjectPicker.
+      // Why: org-listing failed; record a synthetic '*' partial failure so the banner explains it, but keep collected viewer projects (the reported 504 path).
       partialFailures.push({ owner: '*', message: res.error.message })
       break
     }
@@ -1516,9 +1434,7 @@ export async function listAccessibleProjects(): Promise<ListAccessibleProjectsRe
       }
       orgsSeen++
       const login = org.login
-      // Cache owner → ownerType for downstream paste/resolve even when the
-      // nested projects query was empty or partially failed — paste-to-add
-      // uses this to disambiguate /orgs/ vs /users/ URLs.
+      // Cache owner → ownerType even when the projects query failed; paste-to-add uses it to disambiguate /orgs/ vs /users/ URLs.
       rememberOwnerType(login, 'organization')
       const nodes = org.projectsV2?.nodes ?? []
       let ownerCount = 0
@@ -1746,9 +1662,7 @@ export async function resolveProjectRef(
     ownerType,
     number: parsed.number,
     title: p.title ?? '',
-    // Why: forward the parsed view number from /views/{n} URLs so the
-    // renderer can skip the view-pick step. parsed.kind === 'bare' has no
-    // viewNumber (owner/number shorthand carries no view).
+    // Why: forward the view number from /views/{n} URLs so the renderer can skip the view-pick step (bare owner/number shorthand carries none).
     ...(parsed.kind !== 'bare' && parsed.viewNumber !== undefined
       ? { viewNumber: parsed.viewNumber }
       : {})
diff --git a/src/main/github/rate-limit.ts b/src/main/github/rate-limit.ts
index f4a1ba56248..1b77198db68 100644
--- a/src/main/github/rate-limit.ts
+++ b/src/main/github/rate-limit.ts
@@ -1,17 +1,8 @@
 /**
  * GitHub API rate-limit probe.
  *
- * Why: `listWorkItems` fan-out × selected repos plus `countWorkItems` in
- * parallel, plus `listAccessibleProjects` org-walk, can chew through the
- * core (5000/hr) or search (30/min) buckets quickly. Surfacing the remaining
- * budget in the TaskPage header lets users self-regulate before they hit the
- * wall — without actually throttling (which would hurt responsiveness in
- * the common not-near-the-limit case). The probe itself is exempt from
- * rate-limit accounting per GitHub docs.
- *
- * The result is intentionally minimal: we expose just the counts the UI
- * needs (remaining + limit for the three buckets we actually stress). If a
- * future feature needs reset-time countdowns we can add resetAt here.
+ * Why: heavy fan-out (listWorkItems × repos, org-walks) can drain the core/search buckets; surfacing remaining budget lets users self-regulate rather than throttle.
+ * The probe itself is exempt from rate-limit accounting per GitHub docs.
  */
 import type {
   GetRateLimitResult,
@@ -28,17 +19,10 @@ import {
   type GhRateLimitBucket
 } from '../git/gh-rate-limit-breaker'
 
-// Why: GitHub explicitly states `GET /rate_limit` does NOT count against
-// any bucket, so the only reason to cache is to avoid spawning a `gh`
-// subprocess on every render. 30s is a pragmatic balance — short enough
-// that the number in the header feels live, long enough to absorb the
-// 1-per-second "is it safe now?" polling pattern UIs tend to fall into.
+// Why: GET /rate_limit is exempt from limits, so caching only avoids a gh subprocess per render; 30s stays live while absorbing 1/s polling.
 const RATE_LIMIT_CACHE_TTL_MS = 30_000
 let cached: GitHubRateLimitSnapshot | null = null
-// Why: failed probes are cached for the same TTL as successes. Refreshes fail
-// open past a failed probe, so on a host that can never report a budget (GHES
-// with rate limiting disabled 404s every probe) an uncached failure would cost
-// a gh subprocess per queued refresh.
+// Why: cache failures too — a host that 404s every probe (GHES with rate limiting off) would otherwise spawn a gh subprocess per refresh.
 let probeFailure: { at: number; error: string } | null = null
 
 type GhRateLimitPayload = {
@@ -58,9 +42,7 @@ function parseBucket(
       }
     | undefined
 ): GitHubRateLimitBucket {
-  // Why: if a bucket is absent from the response (old gh, partial response),
-  // return 0/0/now so the UI shows a clear "unknown" state (0/0 is
-  // unambiguous) rather than a misleading "plenty left" fallback.
+  // Why: absent bucket → 0/0/now so the UI reads "unknown" rather than a misleading "plenty left".
   return {
     limit: typeof raw?.limit === 'number' ? raw.limit : 0,
     remaining: typeof raw?.remaining === 'number' ? raw.remaining : 0,
@@ -74,14 +56,7 @@ export function _resetRateLimitCache(): void {
   probeFailure = null
 }
 
-// Why: hard-stop thresholds for the circuit breaker. We refuse to issue a new
-// gh request when the cached snapshot says the relevant bucket is below this
-// floor. Numbers chosen as "enough budget for one user-initiated flow":
-// - core/graphql at 50: a typical work-item details fetch + a few mutations
-// - search at 2: a search-driven view paginates in chunks of 1; 2 leaves the
-//   user one safety click without tipping into the 30/min hard limit
-// Below the floor, callers get a synthesized rate_limited error and never
-// spawn a gh subprocess.
+// Circuit-breaker floors: enough budget for one user flow; search paginates by 1, so 2 leaves a safety click under the 30/min cap.
 const MIN_REMAINING_CORE = 50
 const MIN_REMAINING_GRAPHQL = 50
 const MIN_REMAINING_SEARCH = 2
@@ -89,14 +64,8 @@ const MIN_REMAINING_SEARCH = 2
 export type RateLimitBucketKind = 'core' | 'graphql' | 'search'
 
 /**
- * Return a "soft" stop reason if we should refuse to issue a new gh request
- * for the given bucket. Returns null when there's no cached snapshot (we
- * haven't probed yet — fail open) or when the bucket has enough budget left.
- *
- * Why: this is the proactive guard the pill alone cannot provide. The pill is
- * informational; this function actually blocks the spawn. We deliberately keep
- * it advisory (returns a reason, doesn't throw) so callers can format the
- * envelope/error in their own shape.
+ * Return a "soft" stop reason if we should refuse a new gh request for the bucket; `{ blocked: false }` when there's budget or no snapshot yet (fail open).
+ * Why: advisory (returns a reason, doesn't throw) so callers format the error envelope in their own shape.
  */
 export function rateLimitGuard(bucket: RateLimitBucketKind):
   | { blocked: false }
@@ -106,9 +75,7 @@ export function rateLimitGuard(bucket: RateLimitBucketKind):
       limit: number
       resetAt: number
     } {
-  // Why: the runner-level breaker learns about exhaustion from actual 403s,
-  // which can happen long before (or without) a snapshot probe — e.g. quota
-  // burned by another tool on the same account.
+  // Why: the breaker learns exhaustion from real 403s, which can precede a probe (e.g. quota burned by another tool on the account).
   const breakerBlockedUntilMs = getGhRateLimitBlockedUntilMs(bucket)
   if (breakerBlockedUntilMs !== null) {
     return {
@@ -128,14 +95,11 @@ export function rateLimitGuard(bucket: RateLimitBucketKind):
       : bucket === 'graphql'
         ? MIN_REMAINING_GRAPHQL
         : MIN_REMAINING_SEARCH
-  // Why: a snapshot from before the bucket's reset time describes a window
-  // that has already ended — fail open rather than blocking on stale data.
+  // Why: a snapshot from before reset describes an ended window — fail open rather than block on stale data.
   if (b.resetAt * 1000 <= Date.now()) {
     return { blocked: false }
   }
-  // Why: only block when we have a positive limit (limit:0 means "unknown" per
-  // parseBucket fallback — don't block on missing data, that would brick the
-  // app on a single bad rate_limit response).
+  // Why: limit:0 means "unknown" (parseBucket fallback) — don't block on missing data or a single bad response bricks the app.
   if (b.limit > 0 && b.remaining < floor) {
     return { blocked: true, remaining: b.remaining, limit: b.limit, resetAt: b.resetAt }
   }
@@ -143,12 +107,8 @@ export function rateLimitGuard(bucket: RateLimitBucketKind):
 }
 
 /**
- * Decrement the cached `remaining` counter for a bucket after a successful
- * spawn. Why: the canonical numbers come from the next probe, but between
- * probes the cached snapshot would over-report budget if we didn't account
- * for the work we just did. The decrement keeps the circuit breaker honest
- * during a burst (e.g. paginating items) instead of waiting 30s for the cache
- * to expire.
+ * Decrement the cached `remaining` for a bucket after a successful spawn.
+ * Why: between probes the snapshot would over-report budget, so this keeps the breaker honest during a burst instead of waiting for the TTL.
  */
 export function noteRateLimitSpend(bucket: RateLimitBucketKind, cost = 1): void {
   if (!cached) {
@@ -160,11 +120,7 @@ export function noteRateLimitSpend(bucket: RateLimitBucketKind, cost = 1): void
   }
 }
 
-// Why: when the runner's breaker trips it only knows "blocked", not for how
-// long. `gh api rate_limit` is exempt from limits, so one forced probe turns
-// the fallback block into the bucket's real reset time (or clears a block
-// that a stale fallback would otherwise keep alive). Single-flight: a 90-repo
-// 403 burst must refine once, not 90 times.
+// Why: the breaker only knows "blocked", not the reset time; one exempt probe refines it to the real reset or clears a stale block (single-flight so a 403 burst probes once).
 let resetRefinementInFlight: Promise<void> | null = null
 
 function refineBreakerFromSnapshot(): void {
@@ -193,9 +149,7 @@ function refineBreakerFromSnapshot(): void {
 
 registerGhRateLimitResetProbe(() => refineBreakerFromSnapshot())
 
-// Why: a 90-repo fan-out that primes the guard concurrently must resolve to
-// one `gh api rate_limit` spawn, not one per repo — the TTL cache alone can't
-// dedupe calls that all start before the first probe lands.
+// Why: single-flight so a concurrent fan-out resolves to one probe — the TTL cache can't dedupe calls that start before the first lands.
 let probeInFlight: Promise<GetRateLimitResult> | null = null
 
 export async function getRateLimit(options?: { force?: boolean }): Promise<GetRateLimitResult> {
diff --git a/src/main/github/work-item-details.ts b/src/main/github/work-item-details.ts
index 406856c6b3e..87cdbe52eaa 100644
--- a/src/main/github/work-item-details.ts
+++ b/src/main/github/work-item-details.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: the PR/Issue details service groups the
-   body/comments/files/checks fetch paths alongside the file-contents resolver
-   so the drawer's rate-limit and caching strategy lives in one place. */
+/* eslint-disable max-lines -- Why: groups the PR/Issue fetch paths and file-contents resolver so caching/rate-limit strategy lives in one place. */
 import type {
   GitHubAssignableUser,
   GitHubPRFile,
@@ -28,17 +26,12 @@ import { noteRateLimitSpend, rateLimitGuard } from './rate-limit'
 import { getPRReviewCommentLineNumbersFromPatch } from './pr-review-comment-lines'
 import { isMaxBufferOverflowError } from '../git/max-buffer-overflow'
 
-// Why: a PR "changed file" listing returned by the REST endpoint is paginated
-// at 100 per page; we cap at a reasonable total so a massive PR cannot starve
-// the gh semaphore while we fetch file listings.
+// Why: cap total PR files so a massive PR can't starve the gh semaphore while paging (100/page).
 const MAX_PR_FILES = 300
-// Why: issue timelines can be extremely noisy from automation and cross-links.
-// Bound drawer detail work so one huge issue cannot monopolize gh/API time.
+// Why: bound noisy issue timelines so one huge issue can't monopolize gh/API time.
 const MAX_ISSUE_TIMELINE_ITEMS = 300
 const GITHUB_REST_PAGE_SIZE = 100
-// Why: hosted PR files must exceed the renderer's large-diff threshold before
-// we give up on the raw fetch; otherwise the UI sees an empty diff instead of
-// the safety fallback.
+// Why: raw-fetch buffer must exceed the renderer's large-diff threshold, else the UI shows an empty diff instead of the fallback.
 const GITHUB_RAW_CONTENT_MAX_BUFFER_BYTES = 8 * 1024 * 1024
 
 function localGitOptionArgs(options: LocalGitExecOptions = {}): [] | [LocalGitExecOptions] {
@@ -75,12 +68,7 @@ const WORK_ITEM_PARTICIPANTS_QUERY = `query($owner: String!, $repo: String!, $nu
   }
 }`
 
-// Why: a single GraphQL round-trip replaces three serial gh subprocesses on
-// the issue path (REST issue + REST comments + GraphQL participants). The
-// previous fan-out could spawn ~3 `gh` processes per drawer-open; this drops
-// it to one. We still fall back to the legacy REST+GraphQL path if the
-// collapsed query throws or returns missing data — see the strict-fallback
-// branch in getWorkItemDetails.
+// Why: one GraphQL round-trip replaces the 3 serial gh subprocesses (REST issue + comments + participants); falls back to the legacy path on failure.
 const ISSUE_DETAILS_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
   repository(owner: $owner, name: $repo) {
     issue(number: $number) {
@@ -300,8 +288,7 @@ async function getIssueTimelineItems(
         ],
         ghOptions
       )
-      // Why: --jq emits compact NDJSON while explicit pages let us stop once
-      // supported activity reaches the drawer cap.
+      // Why: --jq emits NDJSON and explicit paging lets us stop once we hit the drawer cap.
       const pageEvents = parseRestTimelineEventLines(stdout)
       for (const event of pageEvents) {
         const item = mapRestTimelineEvent(event)
@@ -324,10 +311,9 @@ async function getIssueTimelineItems(
 }
 
 /**
- * Fetch an issue's body, comments, assignees, participants, and timeline in a
- * single GraphQL round-trip. Returns null on any partial error so the caller
- * falls back to the strict REST path. Assignee/participant avatars are resolved
- * here so GitHub Enterprise users don't render blank.
+ * Fetch an issue's body, comments, assignees, participants, and timeline in one GraphQL round-trip.
+ * Returns null on any partial error so the caller falls back to the strict REST path.
+ * Avatars are resolved here so GHE users don't render blank.
  */
 async function getIssueDetailsViaGraphQL(
   repoPath: string,
@@ -338,9 +324,7 @@ async function getIssueDetailsViaGraphQL(
   body: string
   comments: PRComment[]
   assignees: string[]
-  // Avatar-bearing assignees, kept separate from the `assignees` login list so
-  // callers that only need logins are unaffected; used to enrich assignee
-  // avatars that `gh` leaves blank (notably GitHub Enterprise users).
+  // Avatar-bearing assignees, kept separate from the login-only `assignees`; enriches avatars `gh` leaves blank (GHE).
   assigneeUsers: GitHubAssignableUser[]
   participants: GitHubAssignableUser[]
   timelineItems: GitHubIssueTimelineItem[]
@@ -376,9 +360,7 @@ async function getIssueDetailsViaGraphQL(
     )
     const parsed = JSON.parse(stdout) as GraphQLIssueDetailsResponse
     if (parsed.errors && parsed.errors.length > 0) {
-      // Why: any partial GraphQL error (permissions, unknown field on a fork)
-      // forces the strict REST fallback so the drawer never paints a half-built
-      // shell. The fallback path's behavior is the historical contract.
+      // Why: any partial GraphQL error forces the strict REST fallback so the drawer never paints a half-built shell.
       return null
     }
     const issue = parsed.data?.repository?.issue
@@ -436,8 +418,7 @@ function mergeGitHubUsers(users: GitHubAssignableUser[]): GitHubAssignableUser[]
     const key = user.login.toLowerCase()
     const existing = byLogin.get(key)
     if (existing) {
-      // Why: avoid mutating caller-provided objects — return a new merged record
-      // so upstream references to `user`/`existing` stay unchanged.
+      // Why: return a new merged record instead of mutating caller-provided objects.
       byLogin.set(key, {
         login: existing.login,
         name: existing.name ?? user.name ?? null,
@@ -486,14 +467,10 @@ function mapFileStatus(raw: string): GitHubPRFile['status'] {
   }
 }
 
-// Why: GitHub's REST file listing does not explicitly flag binary files, but it
-// omits the `patch` field for them. When a file has changes but no patch, we
-// treat it as binary so the drawer's diff tab can show a placeholder instead of
-// attempting to fetch contents that would render as noise in a text diff viewer.
+// Why: REST doesn't flag binaries but omits `patch` for them; treat "changes but no patch" as binary so the diff tab shows a placeholder.
 function isBinaryHint(file: RESTPRFile): boolean {
   if (file.status === 'removed' || file.status === 'added') {
-    // A newly added or removed file with zero patch text but non-zero changes
-    // is almost always binary (images, lockfiles over the size cap, etc.).
+    // Added/removed file with changes but no patch is almost always binary (images, oversized lockfiles).
     return file.patch === undefined && file.changes > 0
   }
   return file.patch === undefined && file.changes > 0
@@ -543,9 +520,7 @@ async function getPRHeadBaseSha(
   }
 }
 
-// Why: null signals a failed/blocked fetch (rate limit, auth, unresolved
-// remote) so the Files tab can show a retryable error instead of the
-// misleading "No files changed." empty state; [] means a genuinely empty PR.
+// Why: null = failed/blocked fetch (Files tab shows retry, not "No files changed."); [] = genuinely empty PR.
 async function getPRFiles(
   repoPath: string,
   prNumber: number,
@@ -822,9 +797,7 @@ async function getWorkItemParticipants(
   connectionId?: string | null,
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<GitHubAssignableUser[]> {
-  // Why: work items in a fork live on the upstream remote, so participants must
-  // be resolved via the same upstream-first resolvers the body/comment fetches
-  // use (getIssueOwnerRepo for issues, getOwnerRepo for PRs; see #7331).
+  // Why: fork work items live upstream, so resolve owner/repo with the same upstream-first resolvers as body/comments (#7331).
   const ownerRepo =
     item.type === 'issue'
       ? await getIssueOwnerRepo(repoPath, connectionId, ...localGitOptionArgs(localGitOptions))
@@ -895,8 +868,7 @@ async function getGitHubUsersByLogin(
     return []
   }
   if (rateLimitGuard('graphql').blocked) {
-    // Why: surface the skip. Callers degrade silently to login-based avatar URLs
-    // (blank on GHE), so without this log "why are avatars missing" is untraceable.
+    // Why: log the skip — callers degrade silently to blank GHE avatars, so it's otherwise untraceable.
     console.warn(
       `getGitHubUsersByLogin skipped: GraphQL rate-limit budget exhausted (${uniqueLogins.length} logins unresolved)`
     )
@@ -945,15 +917,9 @@ async function getGitHubUsersByLogin(
 }
 
 /**
- * Stamp GraphQL-resolved avatars onto a work item's author, reviewers, review
- * requests, latest reviews, and assignees.
+ * Stamp GraphQL-resolved avatars onto a work item's author, reviewers, review requests, latest reviews, and assignees.
  *
- * The work item's users come from `gh pr view`, which omits avatar_url. On
- * GitHub Enterprise the login-based `github.com/{login}.png` URL 404s, so those
- * avatars render blank while comment avatars (fetched via GraphQL) work.
- * `knownUsers` (participants + the mention-author batch, which already includes
- * the item's reviewers/assignees) carries the resolved avatars, so we apply
- * them without any extra round-trip. See #8784.
+ * Why: `gh pr view` omits avatar_url, so login-based avatars 404 on GHE; knownUsers carries the GraphQL-resolved ones. See #8784.
  */
 function enrichItemDisplayAvatars(
   item: Omit<GitHubWorkItem, 'repoId'>,
@@ -968,16 +934,11 @@ function enrichItemDisplayAvatars(
   if (avatarByLogin.size === 0) {
     return item
   }
-  // Why: prefer the GraphQL-resolved avatar over whatever `gh` returned. `gh pr
-  // view` often yields an empty avatar or the default `u/0` placeholder for
-  // enterprise users; the resolved avatar is the authoritative one for that
-  // login. Fall back to the original only when the lookup found nothing.
+  // Why: prefer the GraphQL-resolved avatar — `gh pr view` returns empty/`u/0` placeholders for enterprise users; fall back to the original only when the lookup is empty.
   const avatarFor = (login: string): string | undefined => avatarByLogin.get(login.toLowerCase())
   const resolvedAvatar = (login: string, existing?: string | null): string | undefined =>
     avatarFor(login) || existing || undefined
-  // Callers coalesce a missing result to the field's "no avatar" sentinel (''
-  // for GitHubAssignableUser, null for GitHubPRReviewSummary); GitHubUserAvatar
-  // treats both as falsy and falls back to the login URL then initials.
+  // Callers coalesce a missing result to each field's "no avatar" sentinel ('' or null); GitHubUserAvatar falls back to login URL then initials.
   const authorAvatarUrl = (item.author ? avatarFor(item.author) : undefined) || item.authorAvatarUrl
   return {
     ...item,
@@ -1020,17 +981,8 @@ async function getMentionParticipants(
   connectionId?: string | null,
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<GitHubAssignableUser[]> {
-  // Why: resolve mention authors AND the item's reviewers/assignees in ONE
-  // aliased GraphQL round-trip. Folding the display users in here means the
-  // caller can reuse this result to stamp avatars (see enrichItemDisplayAvatars)
-  // without a second, separately rate-limited lookup — which is what made GHE
-  // reviewer/assignee avatars resolve intermittently. See #8784.
-  // Why: order the always-visible display users (author, reviewers, assignees)
-  // before comment authors so the 40-login cap in getGitHubUsersByLogin never
-  // drops a reviewer/assignee avatar on a PR with many commenters. On a PR with
-  // 40+ distinct participants the trailing comment authors are dropped from this
-  // batch and lose only their @mention-suggestion avatar; rendered comment
-  // avatars are unaffected (they carry their own avatarUrl from the comment).
+  // Why: resolve mention authors + display users (reviewers/assignees) in one aliased trip so avatars reuse it without a second rate-limited lookup (#8784).
+  // Why: order display users before comment authors so the 40-login cap in getGitHubUsersByLogin can't drop a reviewer/assignee avatar.
   const visibleLogins = [
     item.author ?? '',
     ...(item.reviewRequests ?? []).map((user) => user.login),
@@ -1065,8 +1017,7 @@ async function getPRChecksForDetails(
       ...localGitOptionArgs(localGitOptions)
     )
   } catch (err) {
-    // Why: checks are auxiliary PR metadata; a gh CLI edge case must not block
-    // the user from opening the PR review drawer and reading the files/comments.
+    // Why: checks are auxiliary — a gh failure must not block opening the PR drawer.
     console.warn('getWorkItemDetails PR checks failed:', err)
     return []
   }
@@ -1079,9 +1030,7 @@ export async function getWorkItemDetails(
   connectionId?: string | null,
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<GitHubWorkItemDetails | null> {
-  // Why: getWorkItem already handles acquire/release. We call it first (outside
-  // our semaphore) so the known-cheap lookup doesn't compete with the richer
-  // detail fetches that follow.
+  // Why: getWorkItem self-manages acquire/release; call it outside our semaphore so the cheap lookup doesn't block detail fetches.
   const item: Omit<GitHubWorkItem, 'repoId'> | null = await getWorkItem(
     repoPath,
     number,
@@ -1096,13 +1045,7 @@ export async function getWorkItemDetails(
   await acquire()
   try {
     if (item.type === 'issue') {
-      // Why: try the collapsed single-GraphQL path first — body, assignees,
-      // participants, and comments all return in one round-trip. On any
-      // failure (permissions, partial errors, non-GitHub remote), strictly
-      // fall back to the legacy REST+GraphQL fan-out so historical behavior
-      // is preserved. The GraphQL `participants` connection includes every
-      // commenter, so we skip the extra `getMentionParticipants` aliased
-      // user-hydration trip when the collapsed path succeeds.
+      // Why: one GraphQL round-trip returns everything (its participants include commenters, so getMentionParticipants is skipped); fall back to REST+GraphQL on any failure.
       const collapsed = await getIssueDetailsViaGraphQL(
         repoPath,
         item.number,
@@ -1111,9 +1054,7 @@ export async function getWorkItemDetails(
       )
       if (collapsed) {
         return {
-          // Include assigneeUsers: a non-participating assignee is absent from
-          // the participants connection, so without them item.assignees keeps a
-          // blank/placeholder avatar (common for GitHub Enterprise users).
+          // Include assigneeUsers: non-participating assignees are absent from participants and keep a blank avatar (GHE).
           item: enrichItemDisplayAvatars(item, [
             ...collapsed.participants,
             ...collapsed.assigneeUsers
@@ -1125,8 +1066,7 @@ export async function getWorkItemDetails(
           timelineItems: collapsed.timelineItems
         }
       }
-      // Why: fall back to body/comments and GraphQL participants in parallel;
-      // the mention-participant merge is a cheap local operation afterward.
+      // Fallback: fetch body/comments and participants in parallel.
       const [{ body, comments, assignees, timelineItems }, participants] = await Promise.all([
         getIssueBodyAndComments(repoPath, item.number, connectionId, localGitOptions),
         getWorkItemParticipants(repoPath, item, connectionId, localGitOptions)
@@ -1165,9 +1105,7 @@ export async function getWorkItemDetails(
       getWorkItemParticipants(repoPath, item, connectionId, localGitOptions)
     ])
 
-    // Why: run the mention-author GraphQL lookup in parallel with the final
-    // checks fetch instead of serially — both depend only on data from the
-    // Promise.all above, so there's no ordering requirement between them.
+    // Why: mention-author lookup and checks are independent, so run them in parallel.
     const [mentionParticipants, checks] = await Promise.all([
       getMentionParticipants(repoPath, item, comments, participants, connectionId, localGitOptions),
       getPRChecksForDetails(repoPath, item.number, shas?.headSha, connectionId, localGitOptions)
@@ -1181,8 +1119,7 @@ export async function getWorkItemDetails(
       baseSha: shas?.baseSha,
       pullRequestId: viewedStates?.pullRequestId,
       checks,
-      // Why: distinguish a failed file fetch (null) from an empty PR so the
-      // Files tab surfaces a retry instead of "No files changed."
+      // Why: null (failed fetch) vs empty PR — Files tab shows retry, not "No files changed."
       files: files === null ? undefined : mergePRFileViewedStates(files, viewedStates),
       filesUnavailable: files === null,
       participants: mentionParticipants
@@ -1192,10 +1129,7 @@ export async function getWorkItemDetails(
   }
 }
 
-// Why: base64-decoded contents at specific commits are needed to feed Orca's
-// Monaco-based DiffViewer (which expects original/modified text, not unified
-// diff patches). Fetching via gh api --cache keeps rate-limit usage bounded
-// during rapid file-expand clicks in the drawer.
+// Why: Monaco DiffViewer needs original/modified text (not patches); --cache bounds rate-limit spend on rapid file-expands.
 async function fetchContentAtRef(args: {
   repoPath: string
   connectionId?: string | null
@@ -1222,9 +1156,7 @@ async function fetchContentAtRef(args: {
         maxBuffer: GITHUB_RAW_CONTENT_MAX_BUFFER_BYTES
       }
     )
-    // Raw content response: Electron's execFile returns string in utf-8. If the
-    // file is binary, the string will contain replacement characters — we treat
-    // anything with a NUL byte in the first 2KB as binary and skip rendering.
+    // Heuristic: a NUL byte in the first 2KB means binary (execFile decodes as lossy utf-8).
     const sample = stdout.slice(0, 2048)
     if (sample.includes('\u0000')) {
       return { content: '', isBinary: true }
@@ -1265,9 +1197,7 @@ export async function getPRFileContents(args: {
 
   await acquire()
   try {
-    // Why: for added files there's no original content at the base ref; for
-    // removed files there's no modified content at the head ref. Skipping the
-    // redundant fetches keeps latency down and avoids spurious 404 warnings.
+    // Why: added files have no base-ref original, removed files no head-ref modified; skip those to avoid spurious 404s.
     const needsOriginal = args.status !== 'added'
     const needsModified = args.status !== 'removed'
     const originalRef = args.baseSha
diff --git a/src/main/gitlab/client.ts b/src/main/gitlab/client.ts
index eef57b3aaba..a179ea4be86 100644
--- a/src/main/gitlab/client.ts
+++ b/src/main/gitlab/client.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: parallel to src/main/github/client.ts —
-co-locating GitLab MR/issue/work-item operations keeps the concurrency
-acquire/release pattern obvious across operations. */
+/* eslint-disable max-lines -- co-locates GitLab MR/issue/work-item operations sharing one acquire/release pattern. */
 import type {
   ClassifiedError,
   GitLabAssignableUser,
@@ -48,8 +46,7 @@ import {
   type HostedReviewExecutionOptions
 } from '../source-control/hosted-review-git-options'
 
-// Why: glab REST API addresses projects by URL-encoded path. Centralized
-// so call sites don't forget the slash escapes for nested groups.
+// Why: glab REST addresses projects by URL-encoded path; escapes slashes for nested groups.
 function encodedProject(projectPath: string): string {
   return encodeURIComponent(projectPath)
 }
@@ -67,9 +64,8 @@ function hostedReviewLocalGitOptionArgs(
 }
 
 /**
- * Get the authenticated GitLab viewer. Mirrors getAuthenticatedViewer
- * from the GitHub client — returns null when glab is unavailable, the
- * user is unauthenticated, or the lookup fails.
+ * Get the authenticated GitLab viewer.
+ * Returns null when glab is unavailable, unauthenticated, or the lookup fails.
  */
 export async function getAuthenticatedViewer(): Promise<GitLabViewer | null> {
   await acquire()
@@ -202,8 +198,7 @@ function rememberGitLabRateLimitSnapshot(
   snapshot: GitLabRateLimitSnapshot
 ): void {
   pruneGitLabRateLimitCache()
-  // Why: self-managed GitLab hostnames come from repo config; keep this
-  // process cache bounded even across many transient hosts.
+  // Why: self-managed hostnames come from repo config; keep this cache bounded across many transient hosts.
   gitLabRateLimitCache.delete(cacheKey)
   gitLabRateLimitCache.set(cacheKey, snapshot)
   pruneGitLabRateLimitCache()
@@ -223,9 +218,7 @@ export async function getRateLimit(options?: {
 
   await acquire()
   try {
-    // Why: GitLab.com and self-managed GitLab instances expose REST budget
-    // headers inconsistently. Query a cheap authenticated endpoint and report
-    // the headers when present; a null bucket means this host omitted them.
+    // Why: GitLab exposes REST budget headers inconsistently; a null bucket means this host omitted them.
     const args = host ? ['--hostname', host, 'user'] : ['user']
     const { headers } = await glabApiWithHeaders(args)
     const snapshot = parseGitLabRateLimitSnapshot(headers, host)
@@ -239,10 +232,7 @@ export async function getRateLimit(options?: {
   }
 }
 
-/**
- * Resolve a project's full GitLab project ref (host + path). Mirrors
- * github/getRepoSlug. Returns null for non-GitLab remotes.
- */
+/** Resolve a project's full GitLab project ref (host + path); null for non-GitLab remotes. */
 export async function getProjectSlug(
   repoPath: string,
   connectionId?: string | null,
@@ -254,9 +244,8 @@ export async function getProjectSlug(
 }
 
 /**
- * Fetch a single merge request with the pipeline status rolled up.
- * Returns null when the MR doesn't exist or glab fails — callers
- * decide whether to surface "not found" UI.
+ * Fetch a single merge request with pipeline status rolled up.
+ * Returns null when the MR doesn't exist or glab fails.
  */
 export async function getMergeRequest(
   repoPath: string,
@@ -285,9 +274,7 @@ export async function getMergeRequest(
       head_pipeline?: { status?: string } | null
       pipeline?: { status?: string } | null
     }
-    // Why: GitLab's MR detail surfaces the head pipeline directly.
-    // Older instances expose `pipeline` instead of `head_pipeline` — try
-    // both. If neither is set the rollup falls back to neutral.
+    // Why: older GitLab instances expose `pipeline` instead of `head_pipeline`; try both.
     const pipelineStatus = derivePipelineStatus(data.head_pipeline ?? data.pipeline ?? null)
     return mapMRInfo(data, pipelineStatus)
   } catch {
@@ -298,11 +285,8 @@ export async function getMergeRequest(
 }
 
 /**
- * Find the merge request whose source branch matches the given branch
- * name. Mirrors github/getPRForBranch — returns the most recently
- * updated MR for the branch, or null when none exists. The branch is the
- * local checkout's current ref (Orca strips refs/heads/ prefix upstream
- * so we don't need to here).
+ * Find the merge request whose source branch matches the given name.
+ * Returns the most recently updated MR for the branch, or null when none exists.
  */
 export async function getMergeRequestForBranch(
   repoPath: string,
@@ -310,9 +294,7 @@ export async function getMergeRequestForBranch(
   linkedMRIid?: number | null,
   connectionId?: string | null,
   options: HostedReviewExecutionOptions = {},
-  // Why: the existing-review lookup behind Create must distinguish a real glab
-  // transport/auth failure from an accepted "no MR". When true, a failed lookup
-  // throws instead of collapsing to null so callers never report false not_found.
+  // Why: when true, a failed lookup throws instead of returning null, so callers never report a false not_found.
   throwOnFailure = false
 ): Promise<MRInfo | null> {
   const branchName = branch.replace(/^refs\/heads\//, '')
@@ -343,8 +325,7 @@ export async function getMergeRequestForBranch(
       })[]
       if (Array.isArray(data) && data.length > 0) {
         const raw = data[0]
-        // Why: older GitLab list payloads expose `pipeline` instead of
-        // `head_pipeline`, matching the detail endpoint compatibility path.
+        // Why: older GitLab list payloads expose `pipeline` instead of `head_pipeline`.
         const pipelineStatus = derivePipelineStatus(raw.head_pipeline ?? raw.pipeline ?? null)
         return mapMRInfo(raw, pipelineStatus)
       }
@@ -352,9 +333,7 @@ export async function getMergeRequestForBranch(
     if (typeof linkedMRIid !== 'number') {
       return null
     }
-    // Why: create-from-MR worktrees may use a fresh local branch name rather
-    // than the MR source branch. Fall back to the durable linked iid so the
-    // core review status still follows the workspace.
+    // Why: create-from-MR worktrees may rename the branch; fall back to the durable linked iid.
     const { stdout } = await glabExecFileAsync(
       [
         'api',
@@ -380,9 +359,7 @@ export async function getMergeRequestForBranch(
 }
 
 /**
- * Existing-review lookup that surfaces glab transport/auth failures instead of
- * collapsing them to null, so a failed lookup becomes
- * `reviewLookupOutcome: 'unavailable'` rather than a false "No merge request found".
+ * Like getMergeRequestForBranch but throws glab failures instead of returning null, so callers report 'unavailable' not a false "not found".
  */
 export function getMergeRequestForBranchOrThrow(
   repoPath: string,
@@ -407,10 +384,7 @@ function mrListStateFlags(state: MRListState): string[] {
   }
 }
 
-/**
- * List merge requests for a project. Uses glab CLI pagination because
- * it handles self-hosted auth and project selection consistently.
- */
+/** List merge requests for a project via glab CLI, which handles self-hosted auth and project selection. */
 export async function listMergeRequests(
   repoPath: string,
   state: MRListState = 'opened',
@@ -422,10 +396,7 @@ export async function listMergeRequests(
   localGitOptions: LocalGitExecOptions = {}
 ): Promise<ListMergeRequestsResult> {
   const knownHosts = await getGlabKnownHosts(connectionId, localGitOptions)
-  // Why: MRs sit on `origin` in the fork model (the user's fork is where
-  // they push branches and submit MRs). Mirror github's `getOwnerRepo`
-  // call site by going through the upstream/origin preference resolver
-  // so cross-fork workflows reuse the same plumbing.
+  // Why: MRs live on the user's fork (origin); route through the preference resolver so fork workflows share plumbing.
   const { source: projectRef } = await resolveIssueSource(
     repoPath,
     preference,
@@ -435,8 +406,7 @@ export async function listMergeRequests(
   )
   if (!projectRef) {
     if (connectionId) {
-      // Why: SSH-backed repos have no local cwd for glab to infer from.
-      // Running cwd-less could resolve an unrelated local project instead.
+      // Why: SSH-backed repos have no local cwd; a cwd-less glab could resolve an unrelated project.
       return {
         items: [],
         page,
@@ -449,14 +419,9 @@ export async function listMergeRequests(
         }
       }
     }
-    // Why: fallback — let glab infer project from cwd, same as listIssues.
-    // Used when the repo's remote host is not in getGlabKnownHosts(connectionId)
-    // (e.g. a fresh self-hosted instance), but glab itself can still
-    // resolve it from the local git config.
+    // Why: fallback — let glab infer the project from cwd when the host isn't in getGlabKnownHosts.
     const stateFlag = mrListStateFlags(state)
-    // Why: the cwd-inferred fallback must honor the same search the API path
-    // does, otherwise typing a query against a self-hosted / unresolved-projectRef
-    // repo silently returns the unfiltered list (the original #6263 symptom).
+    // Why: apply the same search as the API path, else queries are silently ignored on cwd-inferred repos (#6263).
     const searchFlag = query?.trim() ? ['--search', query.trim()] : []
     await acquire()
     try {
@@ -484,8 +449,7 @@ export async function listMergeRequests(
         items: data.map((d) => mapMRToWorkItem(d, 'unknown')),
         page,
         perPage,
-        // Why: the CLI doesn't return x-total headers, so totals are
-        // approximate. For the Tasks UI this is acceptable.
+        // Why: the CLI omits x-total headers, so totals are approximate.
         totalCount: data.length,
         totalPages: data.length < perPage ? page : page + 1
       }
@@ -503,8 +467,7 @@ export async function listMergeRequests(
       release()
     }
   }
-  // Why: 'all' is exposed as the picker filter but GitLab's API expects
-  // no state param to mean "any state". Drop the param when 'all'.
+  // Why: GitLab's API uses an absent state param to mean "any"; drop it for 'all'.
   const stateParam = state === 'all' ? '' : `&state=${state}`
   const searchParam = query?.trim() ? `&search=${encodeURIComponent(query.trim())}` : ''
   const path =
@@ -524,8 +487,7 @@ export async function listMergeRequests(
       page,
       perPage,
       totalCount: parseHeaderInt(headers['x-total'], 0),
-      // Why: when 'all' state is requested or the per_page is large,
-      // GitLab may not include x-total-pages; fall back to ceil(total/perPage).
+      // Why: GitLab may omit x-total-pages for 'all' or large per_page; fall back to ceil(total/perPage).
       totalPages:
         parseHeaderInt(headers['x-total-pages'], 0) ||
         Math.max(1, Math.ceil(parseHeaderInt(headers['x-total'], 0) / perPage))
@@ -554,10 +516,8 @@ function parseHeaderInt(value: string | undefined, fallback: number): number {
 }
 
 /**
- * Fetch a work item (MR or issue) given an explicit project ref +
- * iid + type. Mirrors github/getWorkItemByOwnerRepo — used by the
- * paste-URL flow in the picker where the URL determines the project
- * directly rather than going through the local repo's remotes.
+ * Fetch a work item (MR or issue) by explicit project ref + iid + type.
+ * Used by the paste-URL flow, where the URL determines the project directly.
  */
 export async function getWorkItemByProjectRef(
   repoPath: string,
@@ -573,8 +533,7 @@ export async function getWorkItemByProjectRef(
     const { stdout } = await glabExecFileAsync(
       [
         'api',
-        // Why: pasted GitLab URLs carry an explicit host; preserve it even for
-        // local/runtime-local repos so cwd remotes cannot redirect the lookup.
+        // Why: preserve the pasted URL's explicit host so cwd remotes can't redirect the lookup.
         ...(projectRef.host ? ['--hostname', projectRef.host] : []),
         `projects/${encodedProject(projectRef.path)}/${resource}/${iid}`
       ],
@@ -593,9 +552,7 @@ export async function getWorkItemByProjectRef(
 }
 
 function mrStateToIssueState(state: MRListState): IssueListState | null {
-  // Why: GitLab issues don't have a 'merged' state. When the user is
-  // filtering MRs to merged, return null so listWorkItems can skip the
-  // issues fetch entirely instead of mis-mapping to opened/closed.
+  // Why: issues have no 'merged' state; return null so the issues fetch is skipped, not mis-mapped.
   switch (state) {
     case 'opened':
       return 'opened'
@@ -640,16 +597,8 @@ export async function listWorkItems(
       }
     }
   }
-  // Why: fan out the two read calls so the response time is the slower
-  // of the two, not their sum. Errors classify per-side; an MR-side
-  // failure with a successful issues fetch still surfaces issues with
-  // an error envelope.
-  //
-  // Why we don't go through `listIssues` here: that function returns
-  // IssueInfo, which deliberately strips the raw glab fields (notably
-  // `updated_at`). The combined sort needs updatedAt, so we read the
-  // raw issues API directly and run mapIssueToWorkItem against the
-  // raw payload instead.
+  // Why: fan out both reads so latency is the slower of the two, not the sum.
+  // Why read the raw issues API (not listIssues): IssueInfo strips updated_at, which the combined sort needs.
   const [mrs, issues] = await Promise.all([
     listMergeRequests(
       repoPath,
@@ -680,20 +629,13 @@ export async function listWorkItems(
   const merged = [...mrs.items, ...issues.items].sort((a, b) =>
     (b.updatedAt ?? '').localeCompare(a.updatedAt ?? '')
   )
-  // Why: combine error envelopes — the renderer's banner cares about
-  // any failed fetch, not which one. MR-side error wins because it's
-  // strictly more informative than an issues-side error in most
-  // permission scenarios (issues can be disabled per project).
+  // Why: MR-side error wins — issues can be disabled per project, making its error less informative.
   const error: ClassifiedError | undefined = mrs.error ?? issues.error
   return {
     items: merged,
     page,
     perPage,
-    // Why: approximate totals — an exact combined-pagination total would
-    // require a server-side ordering primitive across two distinct
-    // resources, which the GitLab API doesn't offer. MR total is the
-    // right direction; the UI's "Page X of Y" reads as a hint, not a
-    // strict count.
+    // Why: approximate totals — GitLab can't paginate across MRs+issues as one set, so MR totals stand in.
     totalCount: mrs.totalCount,
     totalPages: mrs.totalPages,
     ...(error ? { error } : {})
@@ -739,14 +681,7 @@ export async function fetchIssuesAsWorkItems(
 
 /**
  * List the authenticated user's GitLab todos (gitlab.com/dashboard/todos).
- * Cross-project — `glab api todos` is user-scoped so the cwd doesn't
- * affect the result; callers may pass any registered repo path so the
- * IPC handler's path-validation guard has something to check.
- *
- * Why: GitLab's todos surface is the closest GitLab-native analogue of
- * GitHub's notifications/inbox. Surfacing it in Orca lets users start
- * work directly from a mention/assignment without going to gitlab.com
- * first.
+ * User-scoped, so cwd is irrelevant; repoPath only satisfies the IPC handler's path-validation guard.
  */
 export async function listTodos(
   repoPath: string,
@@ -764,9 +699,7 @@ export async function listTodos(
   }
   await acquire()
   try {
-    // Why: per_page=50 keeps this user-scoped cross-project view cheap. The UI
-    // shows the highest-priority todos first, so avoid walking every pending
-    // todo page from large GitLab accounts.
+    // Why: per_page=50 keeps this cross-project view cheap; the UI only shows top-priority todos.
     const { stdout } = await glabExecFileAsync(
       [
         'api',
@@ -805,9 +738,7 @@ export async function listTodos(
       state: t.state === 'done' ? 'done' : 'pending'
     }))
   } catch {
-    // Why: silent empty-list on auth/network failures matches the rest
-    // of the read-side surface (`listLabels`, `listAssignableUsers`).
-    // The caller's banner / loading-state UI signals connectivity issues.
+    // Why: silent empty-list on auth/network failure matches the read-side surface; caller UI signals connectivity.
     return []
   } finally {
     release()
@@ -815,9 +746,6 @@ export async function listTodos(
 }
 
 // ── MR mutations ──────────────────────────────────────────────────
-// Why: mirror the GitHub-side actions (mergePR, updatePRTitle, close
-// via gh issue close, etc.) for the GitLab dialog footer. All take a
-// repoPath + iid and resolve the project ref via the existing helper.
 
 async function withProjectRef<T>(
   repoPath: string,
@@ -875,9 +803,7 @@ export async function closeMR(
         return { ok: true }
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err)
-        // Why: glab returns a non-zero exit when the MR is already
-        // closed — treat that as success since the desired state is
-        // reached.
+        // Why: glab exits non-zero when the MR is already closed — treat as success.
         if (msg.toLowerCase().includes('already')) {
           return { ok: true }
         }
@@ -951,9 +877,7 @@ export async function mergeMR(
     async (projectRef, repoFlag) => {
       await acquire()
       try {
-        // Why: glab mr merge accepts --squash and --rebase flags;
-        // omitting both does a regular merge commit. Map our union
-        // to the right glab flag.
+        // Why: omitting both --squash and --rebase yields a regular merge commit.
         const methodFlag =
           method === 'squash' ? ['--squash'] : method === 'rebase' ? ['--rebase'] : []
         await glabExecFileAsync(
@@ -1148,8 +1072,7 @@ export async function resolveMRDiscussion(
       }
       await acquire()
       try {
-        // Why: GitLab resolves/reopens the whole discussion thread, not a single
-        // note; this mirrors GitHub's thread-level resolve mutation.
+        // Why: GitLab resolves/reopens the whole discussion thread, not a single note.
         await glabExecFileAsync(
           [
             'api',
@@ -1429,7 +1352,5 @@ export {
   updateIssue
 } from './issues'
 
-// Why: surface the upstream-aware project-ref helper so non-issue call
-// sites that need the resolved project (e.g. the paste-URL UI) don't
-// have to import from gl-utils directly.
+// Re-exported so paste-URL call sites don't import getProjectRefForRemote from gl-utils directly.
 export { getProjectRefForRemote }
diff --git a/src/main/opencode/hook-service.test.ts b/src/main/opencode/hook-service.test.ts
index 2ad00cf5baa..f3956519ee7 100644
--- a/src/main/opencode/hook-service.test.ts
+++ b/src/main/opencode/hook-service.test.ts
@@ -46,10 +46,7 @@ describe('OpenCode hook plugin source', () => {
   })
 
   it('resolves hook coords from the endpoint file before falling back to process.env', () => {
-    // Why: a long-running OpenCode session was fork()ed with the prior Orca's
-    // PORT/TOKEN frozen into process.env. The plugin must prefer the on-disk
-    // endpoint file (rewritten on every Orca start()) over env, otherwise it
-    // keeps posting to a dead port after an Orca restart.
+    // Why: a forked session freezes the prior Orca's PORT/TOKEN in env; prefer the on-disk endpoint file or it posts to a dead port after restart.
     const source = _internals.getOpenCodePluginSource()
 
     expect(source).toContain('function readEndpointFile()')
@@ -71,12 +68,7 @@ describe('OpenCode hook plugin source', () => {
   })
 
   it('caches the parsed endpoint file on mtime+size+inode to skip re-reads per post', () => {
-    // Why: message.part.updated fires many times per second during a streaming
-    // assistant reply. Each post() calls resolveHookCoords() which reads the
-    // endpoint file — without the cache we'd readFileSync + parse on every
-    // streamed Part. The cache key combines mtime + size + inode so renameSync
-    // (writeEndpointFile's atomic swap) invalidates the cache via the ino
-    // change even when mtime resolution is coarse and size happens to match.
+    // Why: cache the parse to avoid a read per streamed Part; inode in the key lets renameSync invalidate it even when mtime/size collide.
     const source = _internals.getOpenCodePluginSource()
 
     expect(source).toContain('let cachedEndpointKey = "";')
@@ -91,14 +83,7 @@ describe('OpenCode hook plugin source', () => {
   })
 
   it('forwards question.asked as AskUserQuestion so the pane flips to waiting', () => {
-    // Why: OpenCode exposes two separate plugin events for human-in-the-loop
-    // moments — `permission.asked` (blocks on tool approval) and
-    // `question.asked` (the agent called an ask-the-user tool). The plugin
-    // must forward both so the server-side normalizer can map each to
-    // `waiting` and render the red indicator. Dropping `question.asked`
-    // leaves the pane stuck in `working` while the agent is actually idle,
-    // waiting on a human reply — exactly the bug other OpenCode integrations
-    // also handle.
+    // Why: forward question.asked too (not just permission.asked), else the pane stays "working" while the agent idles on a human reply.
     const source = _internals.getOpenCodePluginSource()
 
     expect(source).toContain('if (event.type === "question.asked")')
@@ -118,10 +103,7 @@ describe('OpenCode hook plugin source', () => {
   })
 
   it('guards endpoint-file parse warnings with a process-lifetime latch', () => {
-    // Why: ENOENT is the normal pre-install case and must stay silent, but a
-    // malformed/unreadable file (EACCES, EIO, parse error) would otherwise
-    // spam stderr once per hook post. The latch keeps the warning to once per
-    // OpenCode process — mirrors server.ts's warnedVersions/warnedEnvs intent.
+    // Why: ENOENT is normal pre-install (stay silent), but a bad file would spam stderr per post; latch warns once per process.
     const source = _internals.getOpenCodePluginSource()
 
     expect(source).toContain('let warnedBadEndpoint = false;')
@@ -132,11 +114,7 @@ describe('OpenCode hook plugin source', () => {
 
 describe('OpenCode id safety guard', () => {
   it('accepts the daemon-path sessionId shape (worktreeId@@uuid with ::/...)', () => {
-    // Why: after the daemon-parity refactor (#1148) pty.ts mints sessionIds
-    // like `<worktreeId>@@<uuid>` where worktreeId contains "::" and a
-    // filesystem path. The previous strict regex rejected every real id and
-    // silently dropped OPENCODE_CONFIG_DIR. Lock in that such ids are now
-    // accepted so the plugin dir is actually written.
+    // Why: after #1148 pty.ts mints sessionIds like <worktreeId>@@<uuid> with "::" and a path; the old strict regex rejected every real id.
     const daemonSessionId =
       '50c010a2-bc8e-4eb1-8847-5812133ad6df::/Users/thebr/ghostx/workspaces/noqa/autoheal@@a1b2c3d4'
     expect(isUsableId(daemonSessionId)).toBe(true)
@@ -152,8 +130,7 @@ describe('OpenCode id safety guard', () => {
   })
 
   it('rejects non-string runtime values even though the type says string', () => {
-    // Why: the typeof guard is defense-in-depth for any-typed callers;
-    // without a test, a future refactor could delete the guard silently.
+    // Why: the typeof guard is defense-in-depth for any-typed callers; a test keeps a refactor from silently deleting it.
     expect(isUsableId(undefined as unknown as string)).toBe(false)
     expect(isUsableId(null as unknown as string)).toBe(false)
     expect(isUsableId(42 as unknown as string)).toBe(false)
@@ -176,11 +153,7 @@ describe('OpenCode id safety guard', () => {
 })
 
 describe('OpenCodeHookService buildPtyEnv / clearPty round-trip', () => {
-  // Why: the primitives above only prove the helpers work in isolation. This
-  // suite exercises the public surface against a real filesystem so a future
-  // regression — e.g. re-tightening the id guard or desyncing the path used by
-  // writeLegacyPluginConfig vs clearPty — fails loudly. Before #1148 the service
-  // silently returned {} for daemon-shaped ids; these tests lock that in.
+  // Why: exercise the public surface against a real filesystem so regressions fail loudly (before #1148 daemon-shaped ids silently returned {}).
   const daemonSessionId =
     '50c010a2-bc8e-4eb1-8847-5812133ad6df::/Users/thebr/ghostx/workspaces/noqa/autoheal@@a1b2c3d4'
   const plainUuidId = 'c0ffee00-0000-4000-8000-000000000000'
@@ -244,9 +217,7 @@ describe('OpenCodeHookService buildPtyEnv / clearPty round-trip', () => {
   })
 
   it('buildPtyEnv preserves a user-set OPENCODE_CONFIG_DIR when the id is unusable', () => {
-    // Why: defense-in-depth — if the bounds guard rejects the id, we still
-    // must not blow away the user's own OPENCODE_CONFIG_DIR. The status
-    // plugin is forfeited, but the user's plugins/auth/keymap keep loading.
+    // Why: even when the id is rejected, don't blow away the user's own OPENCODE_CONFIG_DIR.
     const service = new OpenCodeHookService()
     const userDir = mkdtempSync(join(tmpdir(), 'orca-opencode-userdir-'))
     try {
@@ -271,11 +242,7 @@ describe('OpenCodeHookService buildPtyEnv / clearPty round-trip', () => {
 })
 
 describe('OpenCodeHookService overlay mode (user OPENCODE_CONFIG_DIR set)', () => {
-  // Why: locks in docs/opencode-config-dir-collision.md — when the user has
-  // their own OPENCODE_CONFIG_DIR (e.g. a company-wide opencode config repo),
-  // Orca must mirror it into a source-scoped overlay rather than `delete` its
-  // own injection or overwrite the user's value. The user's auth/models/keymap
-  // and Orca's status plugin both load via a single OPENCODE_CONFIG_DIR.
+  // Why: with a user-set OPENCODE_CONFIG_DIR, mirror it into an overlay rather than overwrite it (docs/opencode-config-dir-collision.md).
   const ptyId = 'overlay-pty-1'
   let userDataDir: string
   let userConfigDir: string
@@ -350,18 +317,14 @@ describe('OpenCodeHookService overlay mode (user OPENCODE_CONFIG_DIR set)', () =
   it.skipIf(process.platform === 'win32')(
     'mirrors top-level entries via symlinks so plugins/ is a real directory',
     () => {
-      // Why: only the plugins/ subtree needs entry-by-entry mirroring so Orca
-      // can drop a sibling file alongside the user's plugins. Other top-level
-      // entries (auth.json, opencode.json) are mirrored as a single symlink so
-      // user edits propagate live on POSIX.
+      // Why: only plugins/ needs per-entry mirroring (Orca drops a sibling); other entries are single symlinks so user edits propagate live.
       const service = new OpenCodeHookService()
       const env = service.buildPtyEnv(ptyId, userConfigDir)
 
       const overlay = env.OPENCODE_CONFIG_DIR!
       expect(lstatSync(join(overlay, 'opencode.json')).isSymbolicLink()).toBe(true)
       expect(lstatSync(join(overlay, 'auth.json')).isSymbolicLink()).toBe(true)
-      // plugins/ must be a real directory in the overlay so Orca can write
-      // its sibling status plugin into it.
+      // plugins/ must be a real dir in the overlay so Orca can drop its sibling plugin.
       expect(lstatSync(join(overlay, 'plugins')).isDirectory()).toBe(true)
       expect(lstatSync(join(overlay, 'plugins')).isSymbolicLink()).toBe(false)
       // user-plugin.js inside plugins/ is mirrored entry-by-entry.
@@ -370,11 +333,7 @@ describe('OpenCodeHookService overlay mode (user OPENCODE_CONFIG_DIR set)', () =
   )
 
   it("does not overwrite a user plugin file with the same filename as Orca's plugin", () => {
-    // Why: the failure mode this guards against — a user-owned plugin file
-    // happens to be named orca-opencode-status.js. Without the per-entry
-    // skip in mirrorUserConfig, the file would be linked into the overlay
-    // and Orca's writeFileSync would write through the symlink, destroying
-    // the user's content on their real filesystem.
+    // Why: a user plugin named orca-opencode-status.js must not be symlinked into the overlay, or writeFileSync would clobber it.
     const userOrcaSentinel = 'USER OWNED ORCA-NAMED PLUGIN — DO NOT CLOBBER'
     writeFileSync(join(userConfigDir, 'plugins', 'orca-opencode-status.js'), userOrcaSentinel)
 
@@ -399,15 +358,12 @@ describe('OpenCodeHookService overlay mode (user OPENCODE_CONFIG_DIR set)', () =
   it.skipIf(process.platform === 'win32')(
     'does not write through a symlinked plugins/ directory into the user filesystem',
     () => {
-      // Why: if plugins/ is a symlink (common dotfiles pattern), writing Orca's
-      // status plugin through it would land in the user's real filesystem —
-      // exactly the failure mode docs/opencode-config-dir-collision.md rejects.
+      // Why: writing Orca's plugin through a symlinked plugins/ would leak into the user's fs (docs/opencode-config-dir-collision.md).
       const realPluginsDir = mkdtempSync(join(tmpdir(), 'orca-real-plugins-'))
       try {
         writeFileSync(join(realPluginsDir, 'real-plugin.js'), 'REAL USER PLUGIN')
 
-        // Replace the userConfigDir/plugins dir created by beforeEach with a
-        // symlink pointing at the external "real" plugins dir.
+        // Swap plugins/ for a symlink to the external "real" dir (dotfiles pattern).
         rmSync(join(userConfigDir, 'plugins'), { recursive: true, force: true })
         symlinkSync(realPluginsDir, join(userConfigDir, 'plugins'), 'dir')
 
@@ -416,15 +372,13 @@ describe('OpenCodeHookService overlay mode (user OPENCODE_CONFIG_DIR set)', () =
 
         // The user's real filesystem must NOT receive Orca's status plugin.
         expect(existsSync(join(realPluginsDir, 'orca-opencode-status.js'))).toBe(false)
-        // Overlay's plugins/ must be a real directory, not a symlink that
-        // would write through to the user's filesystem.
+        // Overlay's plugins/ must be a real dir, else writes leak into the user's filesystem.
         expect(lstatSync(join(env.OPENCODE_CONFIG_DIR!, 'plugins')).isSymbolicLink()).toBe(false)
         // Orca's status plugin lands in the overlay only.
         expect(
           existsSync(join(env.OPENCODE_CONFIG_DIR!, 'plugins', 'orca-opencode-status.js'))
         ).toBe(true)
-        // The user's sentinel plugin is reachable through the overlay (mirrored
-        // entry-by-entry after resolving the symlink target).
+        // User's real plugin is reachable via the overlay (plugins mirrored entry-by-entry after resolving the symlink target).
         expect(
           readFileSync(join(env.OPENCODE_CONFIG_DIR!, 'plugins', 'real-plugin.js'), 'utf8')
         ).toBe('REAL USER PLUGIN')
@@ -435,10 +389,7 @@ describe('OpenCodeHookService overlay mode (user OPENCODE_CONFIG_DIR set)', () =
   )
 
   it("preserves the user's OPENCODE_CONFIG_DIR when the path does not exist", () => {
-    // Why: typoed user path — overriding it with an Orca-owned dir would let
-    // Orca's status plugin "succeed" while silently hiding the user's typo.
-    // The design rejects that: leave the user's value alone and let OpenCode
-    // surface the typo on its own.
+    // Why: leave a nonexistent user path alone so OpenCode surfaces the typo instead of Orca silently hiding it.
     const service = new OpenCodeHookService()
     const missingPath = join(tmpdir(), `orca-opencode-nope-${Date.now()}`)
     expect(existsSync(missingPath)).toBe(false)
@@ -456,11 +407,7 @@ describe('OpenCodeHookService overlay mode (user OPENCODE_CONFIG_DIR set)', () =
   })
 
   it("preserves the user's OPENCODE_CONFIG_DIR when the mirror step fails", async () => {
-    // Why: mock the shared mirrorEntry helper to throw on the first symlink
-    // (e.g. Windows without developer mode → EPERM). The hook service must
-    // catch and fall back to { OPENCODE_CONFIG_DIR: existingConfigDir } —
-    // the user's plugins/auth/models keep loading; only Orca's status plugin
-    // is forfeited.
+    // Why: if mirroring fails (e.g. Windows EPERM), fall back to the user's OPENCODE_CONFIG_DIR so their config still loads.
     const overlayMirror = await import('../pty/overlay-mirror')
     const mirrorSpy = vi.spyOn(overlayMirror, 'mirrorEntry').mockImplementation(() => {
       throw new Error('simulated EPERM on symlink')
@@ -469,8 +416,7 @@ describe('OpenCodeHookService overlay mode (user OPENCODE_CONFIG_DIR set)', () =
       const service = new OpenCodeHookService()
       const env = service.buildPtyEnv(ptyId, userConfigDir)
       expect(env).toEqual({ OPENCODE_CONFIG_DIR: userConfigDir })
-      // Overlay cleanup is deliberately not on the fallback path; it may hold
-      // OpenCode-created runtime files on Windows.
+      // Overlay cleanup is deliberately off the fallback path; it may hold OpenCode runtime files on Windows.
       const overlayDir = join(
         userDataDir,
         'opencode-config-overlays',
@@ -486,8 +432,7 @@ describe('OpenCodeHookService overlay mode (user OPENCODE_CONFIG_DIR set)', () =
   it.skipIf(process.platform === 'win32')(
     'clearPty leaves the source overlay off the teardown hot path',
     () => {
-      // Why: OpenCode may populate OPENCODE_CONFIG_DIR with runtime files.
-      // PTY teardown must not recursively delete that tree on Electron main.
+      // Why: OpenCode may fill the overlay with runtime files; PTY teardown must not recursively delete it on Electron main.
       const service = new OpenCodeHookService()
       service.buildPtyEnv(ptyId, userConfigDir)
 
@@ -509,10 +454,7 @@ describe('OpenCodeHookService overlay mode (user OPENCODE_CONFIG_DIR set)', () =
   )
 
   it('rebuilding the overlay for the same ptyId does not corrupt the user dir', () => {
-    // Mirrors the daemon cold-restore code path that calls buildPtyEnv with
-    // the same sessionId across restarts. Each rebuild must refresh the prior
-    // overlay safely (no symlink-walk into user data) and keep both user files
-    // and Orca's plugin reachable.
+    // Mirrors daemon cold-restore: rebuilding for the same sessionId must refresh the overlay without symlink-walking into user data.
     const service = new OpenCodeHookService()
     service.buildPtyEnv(ptyId, userConfigDir)
     service.buildPtyEnv(ptyId, userConfigDir)
diff --git a/src/main/opencode/hook-service.ts b/src/main/opencode/hook-service.ts
index 4195e4a0732..c2baa488dc9 100644
--- a/src/main/opencode/hook-service.ts
+++ b/src/main/opencode/hook-service.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: this file contains a multi-line inline
-   JS plugin source emitted into OpenCode's plugins directory as a single
-   file; splitting the plugin source across TS modules would obscure the
-   runtime artifact and scatter tightly coupled string-template logic. */
+/* eslint-disable max-lines -- Why: holds an inline JS plugin source emitted as one file; splitting across TS modules would scatter tightly coupled string-template logic. */
 import { app } from 'electron'
 import { join } from 'node:path'
 import {
@@ -28,33 +25,13 @@ type OpenCodeOverlayManifest = {
   pluginEntries: string[]
 }
 
-// Why: the id passed in by pty.ts's daemon path is a sessionId shaped like
-// "<worktreeId>@@<uuid>" where worktreeId itself contains "::" and a
-// filesystem path (slashes, colons). Earlier the id was a simple numeric
-// counter, so rejecting anything with "/" or ":" was a safe guard against
-// path traversal. After the daemon-parity refactor (#1148) the sessionId
-// shape changed, and the old regex silently rejected every legitimate id,
-// leaving OPENCODE_CONFIG_DIR unset and the plugin never loading.
-//
-// Keep an input-bounds guard (non-empty, bounded length) for defense in
-// depth, and derive the on-disk directory name via hash so any caller's id —
-// including ones containing path separators — produces a short, stable,
-// filesystem-safe name. Hashing also eliminates path-traversal risk at the
-// source: the directory name is always 32 hex chars, never a prefix/suffix
-// of the caller's input.
-// Why: 1024 is a generous sanity cap — daemon-shaped ids embed a worktree
-// filesystem path plus "@@<uuid>", and this bound prevents pathological inputs
-// from burning CPU in the SHA-256 step. Since the id is hashed anyway, 1024
-// is decoupled from PATH_MAX.
+// Why: bounds-check only — the id is a daemon sessionId with path separators, hashed downstream to a filesystem-safe name (an old regex rejecting "/"/":" broke every such id, #1148); 1024 just caps pathological hash input.
 function isUsableId(id: string): boolean {
   return typeof id === 'string' && id.length > 0 && id.length <= 1024
 }
 
 function toSafeDirName(id: string): string {
-  // Why: SHA-256 truncated to 32 hex chars (128 bits) is ample for a
-  // per-session directory name — collisions require ~2^64 concurrent sessions
-  // to become likely, far beyond any real workload. Hex keeps the name
-  // portable across all filesystems (no base64 padding, no `/`).
+  // Why: 32 hex chars (128 bits) makes collisions negligible and stays filesystem-portable (no base64 padding or `/`).
   return createHash('sha256').update(id).digest('hex').slice(0, 32)
 }
 
@@ -63,13 +40,7 @@ export function getOpenCodePluginSource(): string {
 }
 
 export function getOpenCodeFamilyPluginSource(hookPathname: string): string {
-  // Why: the plugin runs inside the OpenCode Node process and POSTs to the
-  // unified agent-hooks server shared with Claude/Codex/Gemini. It reads the
-  // same ORCA_PANE_KEY / ORCA_TAB_ID / ORCA_WORKTREE_ID / ORCA_AGENT_HOOK_*
-  // env vars that Orca injects into every PTY, so OpenCode panes flow into
-  // agentStatusByPaneKey via the same IPC path as every other agent. Event
-  // mapping is done plugin-side (SessionBusy / SessionIdle / PermissionRequest)
-  // so the server-side normalizer can keep its one-event-per-case switch shape.
+  // Why: plugin runs in OpenCode's Node process and POSTs Orca's ORCA_* PTY env to the shared agent-hooks server; events are mapped plugin-side to fit the server's per-case switch.
   return [
     '// Why: process-lifetime guard so a recurring parse error on a malformed',
     "// endpoint file does not spam OpenCode's stderr once per hook post.",
@@ -404,35 +375,20 @@ export function getOpenCodeFamilyPluginSource(hookPathname: string): string {
   ].join('\n')
 }
 
-// Why: OpenCode hooks used to run their own loopback HTTP server + IPC
-// channel (pty:opencode-status). That pathway produced a synthetic terminal
-// title but never entered agentStatusByPaneKey, so the unified dashboard
-// never saw OpenCode sessions. The service now only installs the plugin
-// file into OPENCODE_CONFIG_DIR — the plugin POSTs directly to the shared
-// agent-hooks server (/hook/opencode), so OpenCode rides the same status
-// pipeline as Claude/Codex/Gemini.
+// Why: installs the plugin into OPENCODE_CONFIG_DIR so it POSTs to the shared agent-hooks server, unifying OpenCode status with Claude/Codex/Gemini (the old loopback-IPC path never reached agentStatusByPaneKey).
 export class OpenCodeHookService {
   clearPty(_ptyId: string): void {
-    // Why: OpenCode can materialize thousands of plugin runtime files under
-    // OPENCODE_CONFIG_DIR. This teardown runs on Electron's main process hot
-    // path, so recursive deletion here can freeze the whole app on Windows
-    // while Node, antivirus, or indexing still holds file handles.
-    //
-    // Current builds use app/source-scoped config dirs, not PTY-scoped dirs,
-    // so there is no live PTY-owned OpenCode filesystem state to remove.
+    // Why: no-op — config dirs are app/source-scoped now, and recursive delete on the main-process hot path could freeze on Windows.
   }
 
   buildPtyEnv(ptyId: string, existingConfigDir?: string | undefined): Record<string, string> {
     if (!isUsableId(ptyId)) {
-      // Why: defense-in-depth. If the id fails the bounds guard, a user-set
-      // OPENCODE_CONFIG_DIR should still be preserved so OpenCode loads the
-      // user's own config — only the Orca status plugin is forfeited.
+      // Why: on a bad id, still preserve a user-set OPENCODE_CONFIG_DIR; only the Orca status plugin is forfeited.
       return existingConfigDir ? { OPENCODE_CONFIG_DIR: existingConfigDir } : {}
     }
 
     if (!existingConfigDir) {
-      // Why: OpenCode may install plugin dependencies under this root. Sharing
-      // it prevents per-terminal node_modules churn and teardown freezes.
+      // Why: share one config root so OpenCode's plugin deps don't churn node_modules per terminal.
       const configDir = this.writeSharedPluginConfig()
       if (!configDir) {
         return {}
@@ -440,10 +396,7 @@ export class OpenCodeHookService {
       return { OPENCODE_CONFIG_DIR: configDir }
     }
 
-    // Why: do NOT `mkdir -p` the user's typoed path — overriding it with an
-    // Orca-owned dir is the exact config-replacement failure mode documented in
-    // docs/opencode-config-dir-collision.md. Let OpenCode surface the typo on
-    // its own; we only forfeit our status plugin for this pane.
+    // Why: don't mkdir the user's (possibly typoed) path — that's the config-replacement failure mode in docs/opencode-config-dir-collision.md; let OpenCode surface it.
     if (!existsSync(existingConfigDir)) {
       return { OPENCODE_CONFIG_DIR: existingConfigDir }
     }
@@ -455,11 +408,7 @@ export class OpenCodeHookService {
       this.mirrorUserConfig(existingConfigDir, overlayDir)
       this.writePluginIntoOverlay(overlayDir)
     } catch {
-      // Why: overlay creation is best-effort. Symlink-creation can fail on
-      // Windows without developer mode (EPERM), userData can be read-only on
-      // locked-down corporate machines, etc. In every case, preserve the
-      // user's OPENCODE_CONFIG_DIR — a missing status plugin is a vastly
-      // smaller harm than silently dropping the user's auth/models/keymap.
+      // Why: best-effort — symlink creation needs Windows developer mode (else EPERM) and userData may be read-only; preserve the user's config over dropping their auth/models/keymap.
       return { OPENCODE_CONFIG_DIR: existingConfigDir }
     }
 
@@ -513,17 +462,10 @@ export class OpenCodeHookService {
     }
   }
 
-  // Why: walks the user's OPENCODE_CONFIG_DIR top-level entries. The
-  // `plugins/` subdirectory gets created as a real directory in the overlay
-  // so Orca can drop a sibling file alongside the user's plugins; everything
-  // else (opencode.json, auth.json, themes/, etc.) is mirrored as a single
-  // top-level entry via symlink/junction so user edits propagate live on
-  // POSIX (and on Windows-with-developer-mode) without copying files.
+  // Why: mirror user config entries as symlinks so edits propagate live; only plugins/ becomes a real overlay dir so Orca can drop a sibling plugin file.
   private mirrorUserConfig(sourceDir: string, overlayDir: string): void {
     const previousManifest = this.readOverlayManifest(overlayDir)
-    // Why: source-scoped overlays persist across terminals. Only remove paths
-    // Orca previously mirrored, so deleted/replaced user config cannot stay
-    // stale while OpenCode-owned runtime dirs such as node_modules survive.
+    // Why: overlays persist across terminals; remove only Orca-mirrored paths so stale user config clears but OpenCode runtime dirs (node_modules) survive.
     this.clearManifestEntries(overlayDir, previousManifest)
 
     const nextManifest: OpenCodeOverlayManifest = { topLevelEntries: [], pluginEntries: [] }
@@ -532,43 +474,25 @@ export class OpenCodeHookService {
       const sourcePath = join(sourceDir, entry.name)
 
       if (entry.name === 'plugins') {
-        // Why: check isSymbolicLink BEFORE isDirectory — a Windows junction
-        // can report both as true on a Dirent, and we must take the symlink
-        // branch so the per-entry mirroring (not a single mirrorEntry call
-        // that would create a symlink at <overlay>/plugins) handles it.
+        // Why: check isSymbolicLink before isDirectory — a Windows junction reports both, and the symlink branch must win.
         const isSymlink = entry.isSymbolicLink()
         let isLinkPointingToDir = false
         if (isSymlink) {
           try {
             isLinkPointingToDir = statSync(sourcePath).isDirectory()
           } catch {
-            // Why: broken symlink (target missing) or permission error — fall
-            // through to the default mirrorEntry path so the dangling link is
-            // mirrored verbatim rather than write-through-resolved.
+            // Why: broken/inaccessible symlink — mirror the dangling link verbatim instead of resolving through it.
             isLinkPointingToDir = false
           }
         }
 
         if ((!isSymlink && entry.isDirectory()) || isLinkPointingToDir) {
-          // Why: when the user's plugins/ is a symlink-to-dir, resolve to the
-          // real target so readdir returns the actual entries and child paths
-          // join against the resolved root. mirrorEntry then creates symlinks
-          // pointing into the resolved real plugins (not back through the
-          // user's link), and <overlay>/plugins itself stays a real dir so
-          // writePluginIntoOverlay can never write through to the user's FS.
+          // Why: resolve a symlinked plugins/ to its real target so <overlay>/plugins stays a real dir and writePluginIntoOverlay can't write through the user's link.
           const resolvedSource = isLinkPointingToDir ? realpathSync(sourcePath) : sourcePath
           const overlayPluginsDir = join(overlayDir, 'plugins')
           mkdirSync(overlayPluginsDir, { recursive: true })
           for (const pluginEntry of readdirSync(resolvedSource, { withFileTypes: true })) {
-            // Why: skip a user file with the same filename as Orca's plugin —
-            // mirroring it here would either resolve a same-named target via
-            // symlink (writePluginIntoOverlay then clobbers the user's file
-            // through the link) or collide on Windows with the directory entry
-            // about to be created by writePluginIntoOverlay. Either way the
-            // user's plugin would be lost. Skipping yields the desired
-            // semantics: Orca's status plugin runs and the user's same-named
-            // plugin is shadowed for this PTY only — their source file on disk
-            // is untouched.
+            // Why: skip a user plugin sharing Orca's filename; mirroring it would let writePluginIntoOverlay clobber the user's file.
             if (pluginEntry.name === ORCA_OPENCODE_PLUGIN_FILE) {
               continue
             }
@@ -589,13 +513,7 @@ export class OpenCodeHookService {
     this.writeOverlayManifest(overlayDir, nextManifest)
   }
 
-  // Why: write Orca's status plugin into the overlay's plugins/ dir. The
-  // pre-write unlink is the load-bearing part — POSIX writeFileSync over a
-  // symlink writes through to the link target, so without it a user-owned
-  // plugin with this filename would be clobbered through a mirrored link.
-  // Skipping the same-named user file in mirrorUserConfig already prevents
-  // the link from being created, but the unlink keeps this function safe
-  // even if a stale overlay slips through with the link still in place.
+  // Why: pre-write unlink guards against POSIX writeFileSync writing through a mirrored symlink and clobbering a same-named user plugin.
   private writePluginIntoOverlay(overlayDir: string): void {
     const pluginsDir = join(overlayDir, 'plugins')
     mkdirSync(pluginsDir, { recursive: true })
@@ -603,8 +521,7 @@ export class OpenCodeHookService {
     try {
       unlinkSync(pluginPath)
     } catch {
-      // No-op: file may not exist on a fresh overlay. Any persistent failure
-      // (e.g. permissions) will surface on the writeFileSync below.
+      // File may not exist on a fresh overlay; a real failure surfaces on writeFileSync below.
     }
     writeFileSync(pluginPath, getOpenCodePluginSource())
   }
@@ -616,9 +533,7 @@ export class OpenCodeHookService {
       mkdirSync(pluginsDir, { recursive: true })
       writeFileSync(join(pluginsDir, ORCA_OPENCODE_PLUGIN_FILE), getOpenCodePluginSource())
     } catch {
-      // Why: on Windows, userData directories can be locked by antivirus or
-      // indexers (EPERM/EBUSY). Plugin config is non-critical — the PTY should
-      // still spawn without the OpenCode status plugin.
+      // Why: userData can be locked on Windows (EPERM/EBUSY); plugin is non-critical, so spawn without it.
       return null
     }
     return configDir
diff --git a/src/main/ports/advertised-url-watcher.ts b/src/main/ports/advertised-url-watcher.ts
index b5a9876b55d..befc11ab94f 100644
--- a/src/main/ports/advertised-url-watcher.ts
+++ b/src/main/ports/advertised-url-watcher.ts
@@ -1,42 +1,26 @@
-/* eslint-disable no-control-regex, max-lines -- Why: ANSI/OSC stripping must match raw
- * control sequences in PTY output, same as src/main/runtime/orca-runtime.ts;
- * URL parsing, host classification, cache lifecycle, and cross-worktree lookup
- * are tightly coupled and kept in one file to keep the rules in lockstep. */
-// Watches PTY output for HTTP(S) URLs that dev servers (Vite, Next, etc.)
-// print on startup. Maintains a per-{worktreeId, port} cache so the workspace
-// ports panel can show the tool-advertised origin instead of the kernel bind
-// (e.g. `https://local.getmontecarlo.com:3001/` rather than `127.0.0.1:3001`).
-//
-// Why a separate stateful buffer per PTY: ANSI escape sequences and URLs can
-// both straddle PTY write boundaries, so we cannot strip ANSI and scan one
-// chunk at a time. We accumulate raw bytes, finalize only at newline-anchored
-// boundaries, then run a stateless strip-and-scan on the finalized prefix.
+/* eslint-disable no-control-regex, max-lines -- control-sequence regexes need raw matching; URL parsing, host classification, cache lifecycle, and cross-worktree lookup stay in one file to keep the rules in lockstep. */
+// Watches PTY output for HTTP(S) URLs dev servers print on startup, caching the
+// advertised origin per {worktreeId, port} for the ports panel (vs the kernel bind).
+// Why a separate stateful buffer per PTY: ANSI sequences and URLs can straddle PTY
+// write boundaries, so we accumulate raw bytes and strip-and-scan only at newlines.
 
 const PER_PTY_BUFFER_LIMIT = 4096
 const PENDING_PRE_BIND_LIMIT = 16 * 1024
-/** Cap on distinct never-bound PTY IDs. Spawn-failure paths can leave a
- *  pending entry that never gets bindPty'd — without an upper bound, a
- *  long-running app would slowly leak one entry per failure. */
+/** Cap on distinct never-bound PTY IDs; spawn-failure paths never bindPty, so without a bound they'd leak one entry each. */
 const MAX_PENDING_ENTRIES = 32
 const MAX_CACHE_ENTRIES = 256
 const URL_CANDIDATE_LIMIT = 2048
 
-// ANSI/OSC strippers mirror the runtime normalizer, with URL-specific cursor
-// move handling below to avoid fusing text that a real terminal would skip.
+// ANSI/OSC strippers mirror the runtime normalizer in src/main/runtime/orca-runtime.ts, plus URL-specific cursor-move handling to avoid fusing skipped text.
 const OSC_PATTERN = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g
-// Why: cursor moves in differential redraws can skip cells that are already on
-// screen. Replacing them with a URL-invalid guard skips the damaged candidate.
+// Why: cursor moves in differential redraws skip on-screen cells; a URL-invalid guard drops the damaged candidate.
 const CURSOR_MOVE_PATTERN = /\x1b\[[0-?]*[ -/]*[CDGHf]/g
 const CURSOR_MOVE_URL_GUARD = '['
 const CSI_PATTERN = /\x1b\[[0-?]*[ -/]*[@-~]/g
 const SINGLE_ESC_PATTERN = /\x1b[@-_]/g
 const CONTROL_PATTERN = /[\x00-\x08\x0b-\x1f\x7f]/g
 
-// Why: this is a permissive candidate matcher. Real validation happens via
-// `new URL()` below. Stopping at characters that cannot appear in a URL
-// (whitespace, quotes, angle brackets, backtick) avoids absorbing terminal
-// punctuation. Trailing punctuation like `.,;)` is trimmed before parsing
-// because URLs are commonly followed by sentence punctuation in human text.
+// Permissive matcher (real validation is `new URL()` below); stops at non-URL chars so terminal punctuation isn't absorbed.
 const URL_CANDIDATE_PATTERN = /\bhttps?:\/\/[^\s<>"'`]+/gi
 
 export type HostKind = 'custom' | 'loopback' | 'private-ip' | 'public-ip'
@@ -49,11 +33,8 @@ export type AdvertisedUrl = {
   port: number
   ptyId: string
   lastSeenAt: number
-  /** PID of the listening process that this advertised URL was validated
-   *  against on a previous scan. Set by lookup APIs when a current PID is
-   *  supplied; a later mismatch evicts the entry. Captured on first scan
-   *  rather than at capture time because the PTY shell PID is not the
-   *  listener PID. */
+  /** Listener PID this URL was validated against on a prior scan; a later mismatch evicts the entry.
+   *  Captured on first scan (not at capture time) because the PTY shell PID isn't the listener PID. */
   validatedListenerPid?: number
 }
 
@@ -82,9 +63,7 @@ function worktreeIdFromCacheKey(key: CacheKey, port: number): string {
 class PtyBuffer {
   private raw = ''
 
-  /** Append a chunk and return the cleaned, finalized text (everything up to
-   *  and including the last newline). Whatever follows the last newline stays
-   *  buffered so that a URL or ANSI sequence split across chunks survives. */
+  /** Append a chunk; return cleaned text up to the last newline. The tail stays buffered so a URL or ANSI sequence split across chunks survives. */
   ingest(chunk: string): string {
     const chunkHasLineBreak = chunk.includes('\n') || chunk.includes('\r')
     this.raw += chunk
@@ -105,8 +84,7 @@ class PtyBuffer {
 }
 
 function lastLineBreak(text: string): number {
-  // Both \n and \r are accepted; \r\n is handled by stripping \r in
-  // stripTerminalControls — but we still want either one as a finalize point.
+  // Accept either \n or \r as a finalize point (\r\n is normalized later in stripTerminalControls).
   for (let i = text.length - 1; i >= 0; i--) {
     const ch = text.charCodeAt(i)
     if (ch === 0x0a || ch === 0x0d) {
@@ -162,8 +140,7 @@ function parseUrl(candidate: string): URL | null {
 }
 
 export function classifyHost(hostname: string): HostKind {
-  // Why: Node's URL.hostname returns IPv6 literals with brackets ("[::1]"),
-  // while the public API for this function should accept either form.
+  // Why: strip IPv6 brackets so this public API accepts both "[::1]" (Node's form) and bare literals.
   const lower = hostname.toLowerCase().replace(/^\[|\]$/g, '')
   if (lower === 'localhost' || lower === '127.0.0.1' || lower === '::1') {
     return 'loopback'
@@ -230,10 +207,7 @@ function isPrivateIpv6(value: string): boolean {
 }
 
 function hostKindScore(kind: HostKind): number {
-  // Codex's preference: custom DNS > loopback > private IP > public IP.
-  // A custom-configured host (e.g. `local.getmontecarlo.com`) is almost always
-  // the one the user wants opened, and loopback beats LAN for cert/cookie
-  // reasons on a single-machine setup.
+  // Prefer custom DNS > loopback > private IP > public IP: loopback beats LAN for cert/cookie reasons on one machine.
   switch (kind) {
     case 'custom':
       return 3
@@ -310,8 +284,7 @@ export class AdvertisedUrlWatcher {
       if (entry.ptyId !== ptyId) {
         continue
       }
-      // Why: SSH forward enrichment has no listener PID to validate against,
-      // so PTY teardown is the only reliable expiry signal for that cache row.
+      // Why: SSH forward enrichment has no listener PID, so PTY teardown is the only reliable expiry signal.
       this.cache.delete(key)
       this.validationBaselines.delete(key)
       this.startupAbsentAllowances.delete(key)
@@ -324,8 +297,7 @@ export class AdvertisedUrlWatcher {
   }
 
   forgetWorktree(worktreeId: string): void {
-    // Why: worktree IDs are reused for the same repo/path, so removed
-    // worktrees must not leave scan baselines for a future workspace.
+    // Why: worktree IDs are reused, so a removed worktree must not leave scan baselines for a future one.
     for (const [ptyId, boundWorktreeId] of this.ptyToWorktree) {
       if (boundWorktreeId !== worktreeId) {
         continue
@@ -357,14 +329,10 @@ export class AdvertisedUrlWatcher {
     }
     const worktreeId = this.ptyToWorktree.get(ptyId)
     if (!worktreeId) {
-      // Why: data can arrive on daemon-backed PTYs before the spawn handler
-      // resolves and we learn the worktreeId (see comment at
-      // src/main/ipc/pty.ts:1318-1323). Buffer until bindPty replays.
+      // Why: daemon PTY data can arrive before the spawn handler resolves the worktreeId (src/main/ipc/pty.ts:1318-1323); buffer until bindPty replays.
       const prior = this.pending.get(ptyId) ?? ''
       const merged = (prior + chunk).slice(-PENDING_PRE_BIND_LIMIT)
-      // Why: drop+reinsert touches insertion order so this acts as an LRU
-      // (Map iterates in insertion order). Combined with the eviction below,
-      // we keep at most MAX_PENDING_ENTRIES distinct unbound PTYs.
+      // Why: drop+reinsert refreshes Map insertion order (LRU) so the eviction below drops the oldest unbound PTY.
       this.pending.delete(ptyId)
       this.pending.set(ptyId, merged)
       while (this.pending.size > MAX_PENDING_ENTRIES) {
@@ -398,18 +366,12 @@ export class AdvertisedUrlWatcher {
       return
     }
     const hostname = url.hostname
-    // Why: dev servers sometimes print their bind address verbatim
-    // (`http://0.0.0.0:3000/`). Those wildcard hosts cannot be opened in a
-    // browser — the OS scanner already normalizes wildcards to `localhost`
-    // for the connect host, so refuse the advertised value rather than let
-    // it overwrite that sensible default.
+    // Why: wildcard bind hosts (0.0.0.0, ::) can't be opened in a browser; keep the scanner's localhost default instead.
     if (isUnspecifiedHost(hostname)) {
       return
     }
     const hostKind = classifyHost(hostname)
-    // Why: store origin only — no path, query, fragment, or userinfo. A
-    // terminal line containing an OAuth callback or token must not get
-    // surfaced in the port panel.
+    // Why: store origin only (no path/query/fragment/userinfo) so an OAuth callback or token can't leak to the panel.
     const origin = `${protocol}://${formatHostForOrigin(url)}${
       isDefaultPort(protocol, port) ? '' : `:${port}`
     }`
@@ -430,17 +392,14 @@ export class AdvertisedUrlWatcher {
       if (baseline) {
         this.validationBaselines.set(key, baseline)
         if (baseline.kind === 'absent') {
-          // Why: the advertised URL can arrive between the process printing its
-          // banner and the scanner seeing the listener; allow one settling scan.
+          // Why: the URL can arrive between the banner print and the scanner seeing the listener; allow one settling scan.
           this.startupAbsentAllowances.add(key)
         } else {
           this.startupAbsentAllowances.delete(key)
         }
       } else {
         this.validationBaselines.delete(key)
-        // Why: PTY output can arrive before the scanner has produced any
-        // snapshot for the worktree; give that startup race the same one-scan
-        // absent allowance as a known-absent baseline.
+        // Why: PTY output can arrive before any scan snapshot exists; grant the same one-scan absent allowance.
         this.startupAbsentAllowances.add(key)
       }
       const changedEvents = this.enforceCacheLimit()
@@ -496,9 +455,7 @@ export class AdvertisedUrlWatcher {
       if (entry.validatedListenerPid === undefined) {
         entry.validatedListenerPid = currentListenerPid
       } else if (entry.validatedListenerPid !== currentListenerPid) {
-        // Why: the process that printed this URL is gone and a different
-        // process is now listening on the port. Drop the cached URL — the
-        // new listener may be unrelated to the captured banner.
+        // Why: a different process now listens on this port, so the captured banner may be unrelated — drop it.
         this.cache.delete(key)
         this.validationBaselines.delete(key)
         this.startupAbsentAllowances.delete(key)
@@ -519,9 +476,8 @@ export class AdvertisedUrlWatcher {
     }
   }
 
-  /** Reconcile the URL cache with a scanner snapshot for a worktree scope.
-   *  Unvalidated URLs are tied to the listener state observed around capture,
-   *  so a later absent port or changed PID cannot be lazily blessed. */
+  /** Reconcile the URL cache with a scanner snapshot. Unvalidated URLs stay tied to the
+   *  listener state seen at capture, so a later absent port or changed PID can't lazily bless them. */
   reconcileScan(
     worktreeIds: readonly string[],
     observations: readonly AdvertisedUrlListenerObservation[]
@@ -582,8 +538,7 @@ export class AdvertisedUrlWatcher {
     }
     if (baseline?.kind === 'absent' && current.kind === 'present') {
       this.startupAbsentAllowances.delete(key)
-      // Why: dev servers can print their URL before the OS listener scan sees
-      // the port. Let that first present scan validate the startup banner.
+      // Why: dev servers print their URL before the listener scan sees the port; let this first present scan validate it.
       return false
     }
     return (
@@ -593,17 +548,10 @@ export class AdvertisedUrlWatcher {
     )
   }
 
-  /** Find the best advertised URL for `port` across multiple worktrees. SSH
-   *  connections host several worktrees but the remote-side port scanner
-   *  returns ports for the whole connection, so we need to scan all the
-   *  worktrees attached to that connection. Returns the highest-scoring
-   *  entry by hostKind (custom DNS > loopback > private IP > public IP),
-   *  with HTTPS and recency as tie-breakers — same rule as `shouldReplace`
-   *  uses on insert.
-   *
-   *  When `currentListenerPid` is supplied each candidate entry is run
-   *  through PID filtering first. Already-pinned mismatches are evicted,
-   *  then only the returned winner is pinned to the current listener. */
+  /** Find the best advertised URL for `port` across worktrees, scored via `shouldReplace`.
+   *  Scans all worktrees on the connection because an SSH port scanner reports ports for the
+   *  whole connection, not per-worktree. With `currentListenerPid`, mismatched pinned entries
+   *  are evicted and only the winner is pinned. */
   lookupBest(
     worktreeIds: readonly string[],
     port: number,
@@ -663,15 +611,11 @@ function isDefaultPort(protocol: 'http' | 'https', port: number): boolean {
   return (protocol === 'http' && port === 80) || (protocol === 'https' && port === 443)
 }
 
-/** Process-wide singleton. The runtime feeds it from `onPtyData`; the scanner
- *  enrichment reads it. Tests should instantiate their own
- *  `AdvertisedUrlWatcher` rather than relying on this. */
+/** Process-wide singleton fed by the runtime and read by scanner enrichment. Tests should instantiate their own instead. */
 export const advertisedUrlWatcher = new AdvertisedUrlWatcher()
 
 function formatHostForOrigin(url: URL): string {
-  // Why: Node returns IPv6 hostnames pre-bracketed ("[::1]"). Some other JS
-  // runtimes strip the brackets. Accept both: re-bracket if a bare IPv6
-  // literal slips through.
+  // Why: some JS runtimes strip the IPv6 brackets Node adds; re-bracket a bare IPv6 literal.
   const h = url.hostname
   if (h.startsWith('[') && h.endsWith(']')) {
     return h
@@ -691,8 +635,7 @@ function observedListenersByPort(
     if (!observed.has(observation.port)) {
       observed.set(observation.port, observation.pid)
     } else if (existing !== observation.pid) {
-      // Multiple host-specific listeners on one port make PID attribution
-      // ambiguous for our port-keyed URL cache; preserve presence only.
+      // Multiple host-specific listeners on one port make PID attribution ambiguous; keep presence only.
       observed.set(observation.port, undefined)
     }
   }
diff --git a/src/main/source-control/hosted-review-creation.ts b/src/main/source-control/hosted-review-creation.ts
index a0271d0ea3d..9d95f6ddf02 100644
--- a/src/main/source-control/hosted-review-creation.ts
+++ b/src/main/source-control/hosted-review-creation.ts
@@ -1,5 +1,4 @@
-/* eslint-disable max-lines -- Why: provider detection, eligibility, and creation
-   preflight share one boundary so renderer and main-process gating cannot drift. */
+/* eslint-disable max-lines -- Why: detection, eligibility, and creation preflight share one boundary so gating can't drift. */
 import type {
   CreateHostedReviewInput,
   CreateHostedReviewResult,
@@ -43,9 +42,7 @@ import {
 
 type HostedReviewCreationEligibilityInput = HostedReviewCreationEligibilityArgs & {
   connectionId?: string | null
-  // Why: only the create-time preflight enforces base-on-remote as a hard block;
-  // the renderer's eligibility probe passes the base as a candidate and relies on
-  // Change 1 to correct a local-only parent, so it must never set this.
+  // Why: only the create-time preflight sets this; the renderer's probe leaves it unset to auto-correct a local-only parent.
   enforceBaseOnRemote?: boolean
 } & HostedReviewExecutionOptions
 
@@ -65,11 +62,7 @@ async function isGitHubAuthenticated(
   connectionId?: string | null,
   options: HostedReviewExecutionOptions = {}
 ): Promise<boolean> {
-  // Why: a GHES remote is only routed to the GitHub provider once detection has
-  // confirmed gh is authenticated to its enterprise host, so a non-null slug
-  // already means authenticated — skip a redundant, rate-limited gh probe.
-  // Reaching the github.com check below therefore means the remote is github.com
-  // (its own custom host would have resolved above) (#8312).
+  // Why: a non-null enterprise slug already means gh is authenticated there, so skip a redundant probe (#8312).
   if (await getEnterpriseGitHubRepoSlug(repoPath, connectionId, options)) {
     return true
   }
@@ -142,14 +135,7 @@ async function getDefaultBaseRef(
  * Whether the candidate base resolves to a remote-tracking branch on the
  * executing host.
  *
- * Why: a stacked worktree's `worktree.baseRef` is typically a bare parent
- * branch name with no remote qualifier, so the probe must match the branch
- * under *any* configured remote rather than assume `origin` — otherwise fork
- * workflows (`upstream/main`) would be missed. Runs through
- * `runGitForHostedReview` so it evaluates on the same host that will run the
- * provider create (native/WSL/SSH/relay). This reads the local remote-tracking
- * snapshot, not the live remote; see the design doc's Open Questions for the
- * ls-remote/staleness tradeoff left as a follow-up.
+ * Why: matches under *any* remote (not just origin) and reads the local tracking snapshot, not the live remote.
  */
 async function baseRefExistsOnRemote(
   candidate: string,
@@ -165,18 +151,13 @@ async function baseRefExistsOnRemote(
     runGitForHostedReview(repoPath, argv, connectionId, options)
 
   const patterns = [`refs/remotes/*/${base}`]
-  // Non-origin remote-qualified candidate (e.g. `fork/main`): the wildcard glob
-  // above only matches a branch literally named that because `*` does not cross `/`.
-  // Include the exact tracking ref directly.
+  // `*` does not cross `/`, so a remote-qualified candidate (e.g. `fork/main`) needs its exact tracking ref too.
   if (base.includes('/')) {
     patterns.push(`refs/remotes/${base}`)
   }
 
   try {
-    // for-each-ref exits 0 whether or not the pattern matches, so a clean empty
-    // result is an authoritative "absent" while a thrown error is a transport
-    // failure. Never conflate the two: on an unreachable host, preserve the
-    // candidate rather than silently demoting a legitimately-pushed parent base.
+    // for-each-ref exits 0 on no match: empty means absent, a thrown error means transport failure (preserve the candidate).
     const { stdout } = await run(['for-each-ref', '--count=1', '--format=%(refname)', ...patterns])
     return stdout.trim().length > 0
   } catch {
@@ -210,15 +191,13 @@ async function hasUncommittedChanges(
         'Remote connection dropped. Click Reconnect on the SSH target before retrying.'
       )
     }
-    // Why: the relay intentionally restricts generic git.exec. Use the
-    // structured status RPC for SSH dirty checks instead of raw `git status`.
+    // Why: the relay restricts generic git.exec, so use the structured status RPC for SSH dirty checks.
     return (await provider.getStatus(repoPath)).entries.length > 0
   }
   const { stdout } = await gitExecFileAsync(['status', '--porcelain'], {
     cwd: repoPath,
     ...getHostedReviewLocalGitOptions(options),
-    // Why: create-PR validation should not take Git's optional index lock while
-    // the user may be running fetch/pull/rebase from a terminal.
+    // Why: don't take Git's optional index lock while the user may be running fetch/pull/rebase in a terminal.
     env: gitOptionalLocksDisabledEnv()
   })
   return stdout.trim().length > 0
@@ -237,8 +216,7 @@ async function getHostedReviewUpstreamStatus(
     throw new Error('Remote connection dropped. Click Reconnect on the SSH target before retrying.')
   }
   try {
-    // Why: SSH exposes upstream divergence through a dedicated relay RPC;
-    // generic git.exec intentionally does not allow rev-list/status plumbing.
+    // Why: the relay blocks generic git.exec, so use its dedicated upstream RPC for SSH divergence.
     return await provider.getUpstreamStatus(repoPath)
   } catch (error) {
     if (isNoUpstreamError(error)) {
@@ -431,16 +409,11 @@ async function validateCurrentBranchCanCreateReview(
       ahead: upstreamStatus.ahead,
       behind: upstreamStatus.behind,
       connectionId,
-      // Why: this is the last gate before the provider create, which targets the
-      // submitted base verbatim — enforce that the base exists on the remote here.
+      // Why: last gate before the create, which targets the submitted base verbatim — enforce it exists on the remote.
       enforceBaseOnRemote: true,
       ...options
     })
-    // Why: never call the provider create API when the existing-review lookup
-    // could not prove the branch has no review. An `unavailable` outcome means a
-    // real MR/PR might exist that a failed lookup could not see; refuse
-    // inconclusively (design invariant 8 / submission boundary) so we never
-    // create a duplicate. The composed title/body are preserved by the caller.
+    // Why: an unavailable lookup might hide a real PR — refuse rather than risk a duplicate (design invariant 8).
     if (eligibility.reviewLookupOutcome === 'unavailable') {
       return {
         ok: false,
@@ -448,8 +421,7 @@ async function validateCurrentBranchCanCreateReview(
         error: `Create ${copy.shortLabel} failed: Orca could not confirm whether this branch already has a ${copy.reviewLabel}. Retry once the ${copy.providerName} lookup succeeds.`
       }
     }
-    // Why: renderer eligibility can be stale by submit time; the main process
-    // is the last chance to avoid creating a PR from an out-of-date remote head.
+    // Why: renderer eligibility can be stale by submit time; main process is the last gate before an out-of-date create.
     return blockedEligibilityToCreateResult(eligibility, submittedBase)
   } catch (error) {
     console.warn('Hosted review creation preflight failed:', error)
@@ -470,11 +442,7 @@ export async function getHostedReviewCreationEligibility(
     connectionId: args.connectionId,
     ...hostedReviewExecutionContext(args)
   })
-  // Why: an incoming base is only a *candidate* for the default merge target. A
-  // stacked worktree's parent base resolves on the remote only when it was
-  // actually pushed; a local-only parent must fall back to the repo default so
-  // the PR targets a ref the remote can resolve. Never regress to "no base" —
-  // keep the candidate if the repo default itself is unavailable.
+  // Why: the base is only a candidate; fall back to repo default so a local-only parent targets a remote-resolvable ref.
   const candidateBase = args.base?.trim() || null
   const candidateBaseOnRemote =
     candidateBase != null &&
@@ -488,9 +456,7 @@ export async function getHostedReviewCreationEligibility(
   }
   const baseBranch = defaultBaseRef ? normalizeHostedReviewBaseRef(defaultBaseRef) : null
   let review: Awaited<ReturnType<typeof getHostedReviewForBranch>> = null
-  // Why: a swallowed lookup failure must not masquerade as authoritative
-  // no-review evidence. Track it so the renderer can distinguish an accepted
-  // no-PR result (`not_found`) from a local-blocker fallback (`unavailable`).
+  // Why: track lookup failure so a swallowed error isn't mistaken for authoritative no-review evidence.
   let lookupFailed = false
   try {
     review = await getHostedReviewForBranch({
@@ -506,12 +472,7 @@ export async function getHostedReviewCreationEligibility(
       ...hostedReviewExecutionContext(args)
     })
   } catch (error) {
-    // Why: a failed existing-review lookup can never authorize Create — it might
-    // be hiding a real PR. Record `unavailable` and fall through so any local
-    // blocker (dirty/no-upstream/behind) still supplies primary guidance, but the
-    // clean-branch happy path below is forced to `canCreate: false`. Never rethrow
-    // here: a thrown lookup must not collapse into a false `not_found` and must
-    // stay a structured, honest empty state for the renderer.
+    // Why: a failed lookup might hide a real PR, so record unavailable and fall through rather than rethrow.
     lookupFailed = true
     console.warn('Hosted review lookup failed; treating existing-review as unavailable:', error)
   }
@@ -580,12 +541,7 @@ export async function getHostedReviewCreationEligibility(
   if ((args.ahead ?? 0) > 0) {
     return { ...baseResult, canCreate: false, blockedReason: 'needs_push', nextAction: 'push' }
   }
-  // Why: at create-time, `gh pr create` (and the other providers) target the
-  // submitted base verbatim — Change 1 only corrects the *default*, not a stale
-  // renderer's submitted value. Block a local-only submitted base here so it
-  // fails with actionable copy instead of the provider's opaque error. Only the
-  // create-time preflight enforces this; the renderer's eligibility probe leaves
-  // enforceBaseOnRemote unset so a local-only parent is silently auto-corrected.
+  // Why: providers target the submitted base verbatim; block a local-only base here with actionable copy.
   if (args.enforceBaseOnRemote && candidateBase && !candidateBaseOnRemote) {
     return {
       ...baseResult,
@@ -594,9 +550,7 @@ export async function getHostedReviewCreationEligibility(
       nextAction: null
     }
   }
-  // Why: a lookup that failed leaves review existence unproven, so the clean,
-  // in-sync happy path must not claim `canCreate` — that would open Create
-  // against a branch that may already have a review. Stays `unavailable`.
+  // Why: a failed lookup leaves review existence unproven, so the happy path must not claim canCreate.
   return {
     ...baseResult,
     canCreate: lookupFailed ? false : Boolean(baseBranch),
diff --git a/src/main/speech/model-manager.ts b/src/main/speech/model-manager.ts
index c8f918f1526..2b8bca8bbca 100644
--- a/src/main/speech/model-manager.ts
+++ b/src/main/speech/model-manager.ts
@@ -46,24 +46,13 @@ type DownloadTotals = { totalBytes: number }
 type ContentRange = { start: number; end: number; totalBytes?: number }
 
 const DOWNLOAD_IDLE_TIMEOUT_MS = 120_000
-// Why: flaky networks and scanning proxies commonly kill long CDN transfers
-// near the end (reported as "stuck at 90%, then fails"); resuming with a Range
-// request lets those connections finish instead of failing the same way on
-// every full restart.
+// Why: flaky networks/proxies often kill long CDN transfers near the end; Range-resume lets them finish.
 const DOWNLOAD_RETRY_DELAYS_MS = [1_000, 2_000, 4_000]
-// Why: abandon a download only after this many CONSECUTIVE attempts make no
-// forward progress. A resume that keeps advancing (even across many mid-stream
-// drops) is never given up on — that is the whole point of resumable downloads
-// for large models over flaky networks, and a fixed all-time failure budget
-// would wrongly kill a steadily-progressing large download.
+// Why: count only CONSECUTIVE no-progress attempts, so a download still advancing across drops is never abandoned.
 const MAX_NO_PROGRESS_ATTEMPTS = DOWNLOAD_RETRY_DELAYS_MS.length + 1
-// Why: an absolute backstop so a server handing back pathologically tiny (or
-// zero-net) segments cannot loop forever; sized to cover the largest (~1GB)
-// model even if a proxy caps each range response near ~256KB, far below any
-// real CDN chunk.
+// Why: absolute backstop against a tiny-segment server; 4096 covers the ~1GB model even at a proxy's ~256KB min range.
 const MAX_TOTAL_DOWNLOAD_REQUESTS = 4_096
-// Why: a longer server window should be surfaced for a later manual retry,
-// rather than leaving the settings download looking stuck for minutes.
+// Why: cap honored Retry-After; a longer server window is surfaced for manual retry, not a multi-minute stall.
 const MAX_RETRY_AFTER_MS = 120_000
 const RETRYABLE_NET_ERROR =
   /net::ERR_(CONTENT_LENGTH_MISMATCH|INCOMPLETE_CHUNKED_ENCODING|CONNECTION_(RESET|CLOSED|ABORTED|REFUSED|TIMED_OUT)|EMPTY_RESPONSE|NETWORK_CHANGED|TIMED_OUT|INTERNET_DISCONNECTED|ADDRESS_UNREACHABLE|NAME_NOT_RESOLVED|SOCKET_NOT_CONNECTED|HTTP2_PROTOCOL_ERROR|QUIC_PROTOCOL_ERROR)\b/
@@ -172,8 +161,7 @@ export class ModelManager {
     const prepared = this.prepareModelsDir(requestedModelsDir)
     this.modelsDir = prepared.modelsDir
     this.migrationSourceDir = prepared.migrationSourceDir
-    // Why: migrating a non-ASCII cache copies large model files; run it off the
-    // main thread and gate model-state reads on it so the UI stays responsive.
+    // Why: migration copies large model files, so run it async and gate state reads on it to keep the UI responsive.
     this.migrationReady = migrateSpeechModelCacheIfNeeded(
       prepared.migrationSourceDir,
       prepared.modelsDir
@@ -181,8 +169,7 @@ export class ModelManager {
   }
 
   setProgressCallback(cb: ProgressCallback): () => void {
-    // Why: concurrent settings windows can observe the same download; a
-    // returned unsubscribe prevents one window from replacing another.
+    // Why: return an unsubscribe so concurrent settings windows don't replace each other's callback.
     this.progressCallbacks.add(cb)
     return () => {
       this.progressCallbacks.delete(cb)
@@ -274,10 +261,7 @@ export class ModelManager {
   }
 
   async downloadModel(modelId: string): Promise<void> {
-    // Why: no migration await here — migration only copies dirs already present
-    // in the old cache (surfaced as ready via getModelState before download is
-    // offered), so it never races a download, and awaiting would defer the
-    // synchronous request setup that cancelDownload relies on.
+    // Why: no migration await — it never races a download, and awaiting would defer setup cancelDownload relies on.
     if (this.activeDownloads.has(modelId)) {
       return
     }
@@ -302,8 +286,7 @@ export class ModelManager {
     this.updateState(modelId, 'downloading', 0)
 
     const archivePath = join(this.modelsDir, `${modelId}.tar.bz2`)
-    // Why: resume appends to the partial archive from this download run only;
-    // a leftover file from a crashed run would corrupt the resumed archive.
+    // Why: resume appends, so a leftover archive from a crashed run would corrupt the download.
     try {
       if (existsSync(archivePath)) {
         rmSync(archivePath)
@@ -317,8 +300,7 @@ export class ModelManager {
     const handle: DownloadHandle = {
       abort: () => {
         aborted = true
-        // Why: a stalled HTTPS request may never deliver another data chunk;
-        // cancellation must tear down the request immediately.
+        // Why: a stalled HTTPS request may never deliver another chunk, so tear it down immediately.
         abortController.abort()
       }
     }
@@ -355,9 +337,7 @@ export class ModelManager {
       }
 
       if (!this.validateModelFiles(manifest, modelDir)) {
-        // Why: some archives nest files inside a subdirectory matching the
-        // archive name. If the expected files aren't at the top-level model
-        // dir, scan one level down and move them up.
+        // Why: some archives nest files in a subdir; scan one level down and move them up.
         await this.flattenNestedDir(modelDir, manifest)
       }
 
@@ -378,8 +358,7 @@ export class ModelManager {
       }
       this.cleanup(modelId, archivePath)
       if (!aborted) {
-        // Why: the settings UI awaits this promise to show download failures;
-        // cancellation stays quiet, but real failures must reach the caller.
+        // Why: the settings UI awaits this to surface failures; stay quiet on cancellation, rethrow real errors.
         throw err
       }
     } finally {
@@ -416,9 +395,7 @@ export class ModelManager {
     if (existsSync(modelDir)) {
       await rm(modelDir, { recursive: true, force: true })
     }
-    // Why: also delete the pre-migration copy (awaited above, so the copy has
-    // finished) — otherwise the next launch re-migrates it and resurrects the
-    // model the user just deleted.
+    // Why: also delete the pre-migration copy, or the next launch re-migrates it and resurrects the model.
     if (this.migrationSourceDir) {
       const sourceModelDir = this.getSafeModelDir(modelId, this.migrationSourceDir)
       if (existsSync(sourceModelDir)) {
@@ -436,8 +413,7 @@ export class ModelManager {
   ): void {
     const state: SpeechModelState = { id: modelId, status, progress, error }
     this.modelStates.set(modelId, state)
-    // Why: notify the renderer on every state change (not just download
-    // progress) so the UI updates for extracting/ready/error transitions.
+    // Why: notify on every state change (not just progress) so extracting/ready/error transitions reach the UI.
     const progressValue = progress ?? (status === 'extracting' ? 0.95 : -1)
     for (const callback of this.progressCallbacks) {
       callback(modelId, progressValue)
@@ -466,13 +442,11 @@ export class ModelManager {
     for (;;) {
       requestCount += 1
       const offset = this.getPartialArchiveBytes(archivePath)
-      // Why: the transport can fail after the final byte reached disk; the
-      // caller's SHA-256 check is the authoritative completion test.
+      // Why: transport can fail after the last byte hits disk; the SHA-256 check is the real completion test.
       if (offset === totals.totalBytes) {
         return
       }
-      // Why: absolute backstop against a server that never lets the download
-      // finish; the stall and abort paths handle the common cases first.
+      // Why: absolute backstop against a server that never lets the download finish.
       if (requestCount > MAX_TOTAL_DOWNLOAD_REQUESTS) {
         throw describeInterruptedDownload(
           new Error('too many download requests'),
@@ -482,8 +456,7 @@ export class ModelManager {
         )
       }
       try {
-        // Why: each attempt restarts from the canonical URL rather than the
-        // last redirect target, because CDN redirect URLs are signed and expire.
+        // Why: restart from the canonical URL, not the last redirect, because signed CDN redirect URLs expire.
         await this.downloadFile(
           url,
           archivePath,
@@ -508,10 +481,7 @@ export class ModelManager {
           `Model download response ended at ${receivedBytes} of ${totals.totalBytes} bytes`
         )
         if (receivedBytes > offset) {
-          // Why: some proxies return a valid but bounded range segment; request
-          // the next segment immediately instead of failing checksum or waiting.
-          // Forward progress resets the stall counter; the total-request ceiling
-          // at the loop top bounds a pathological tiny-segment server.
+          // Why: some proxies cap each range segment; request the next immediately and reset the stall counter.
           noProgressStreak = 0
           continue
         }
@@ -530,8 +500,7 @@ export class ModelManager {
         if (!isRetryableDownloadError(err)) {
           throw err
         }
-        // Why: give up only on a genuine stall (repeated no forward progress);
-        // a download that keeps advancing across drops is allowed to continue.
+        // Why: give up only on a genuine stall; a download still advancing across drops keeps going.
         if (noProgressStreak >= MAX_NO_PROGRESS_ATTEMPTS) {
           throw describeInterruptedDownload(err, receivedBytes, totals.totalBytes, requestCount)
         }
@@ -697,8 +666,7 @@ export class ModelManager {
           (parsedLength <= 0 || parsedLength === contentRange.end - contentRange.start + 1)
 
         if (resumeOffset > 0 && response.statusCode === 206 && !resumed) {
-          // Why: appending an unverified range can silently corrupt the archive;
-          // discard it so the canonical URL is retried from byte zero.
+          // Why: appending an unverified range can silently corrupt the archive; discard and retry from byte zero.
           try {
             rmSync(dest)
           } catch {
@@ -716,8 +684,7 @@ export class ModelManager {
 
         if (response.statusCode !== 200 && !resumed) {
           if (response.statusCode === 416) {
-            // Why: the server rejected our resume offset; drop the partial so
-            // the retry loop can restart this download from scratch.
+            // Why: 416 means the server rejected our resume offset; drop the partial to restart from scratch.
             try {
               rmSync(dest)
             } catch {
@@ -729,17 +696,14 @@ export class ModelManager {
           statusError.httpStatusCode = response.statusCode
           statusError.retryAfterMs = parseRetryAfterMs(response.headers['retry-after'])
           rejectOnce(statusError)
-          // Why: retrying must not leave a prior error body draining without
-          // cancellation or idle-timeout ownership.
+          // Why: abort so a retry doesn't leave the error-response body draining unowned.
           activeRequest?.abort()
           return
         }
 
-        // Why: a 200 despite our Range request means the server restarted the
-        // transfer from byte zero, so the partial file must be overwritten.
+        // Why: a 200 to our Range request means the server restarted from byte zero, so overwrite the partial.
         const progressBase = resumed ? resumeOffset : 0
-        // Why: Content-Length on a 206 describes only this segment; when
-        // Content-Range uses '*', retain the known complete archive size.
+        // Why: Content-Length on a 206 is only this segment; on Content-Range '*' keep the known full size.
         const totalSize = resumed
           ? (contentRange?.totalBytes ?? totals?.totalBytes ?? expectedSize)
           : parsedLength > 0
@@ -789,8 +753,7 @@ export class ModelManager {
         request.setHeader('Range', `bytes=${resumeOffset}-`)
       }
 
-      // Why: Electron's net stack honors app proxy settings, unlike Node's
-      // https client, but it does not expose request.setTimeout().
+      // Why: Electron net honors app proxy settings (unlike Node https) but exposes no setTimeout, so time out manually.
       resetIdleTimeout()
       request.on('error', onRequestError)
       request.on('response', onResponse)
@@ -838,8 +801,7 @@ export class ModelManager {
       const onEnd = (): void => {
         const actualSha256 = hash.digest('hex')
         if (actualSha256 !== expectedSha256.toLowerCase()) {
-          // Why: these archives feed native model parsers; filename checks do
-          // not protect against compromised or redirected release assets.
+          // Why: archives feed native parsers, so verify contents against compromised/redirected release assets.
           settleReject(new Error('Downloaded model archive failed integrity verification'))
           return
         }
@@ -862,10 +824,7 @@ export class ModelManager {
     mkdirSync(modelDir, { recursive: true })
 
     return new Promise((resolve, reject) => {
-      // Why: spawn instead of exec because exec buffers all stdout/stderr
-      // (1MB default maxBuffer). bzip2 decompression is slow (~1-5 min for
-      // 170MB archives) and exec can silently kill the process if stderr
-      // exceeds the buffer. spawn streams output without buffering.
+      // Why: spawn (not exec) so slow bzip2 stderr can't overflow exec's 1MB maxBuffer and silently kill the process.
       const tarExecutable = resolveTarExecutable()
       const child = spawn(
         tarExecutable,
@@ -929,8 +888,7 @@ export class ModelManager {
       }, 600_000)
       abortPoll = setInterval(() => {
         if (isAborted()) {
-          // Why: if the extraction child wedges and never emits close/error,
-          // the abort poller must still clear itself when we reject.
+          // Why: a wedged child may never emit close/error, so abort must kill it here.
           fail(new Error('Aborted'), true)
         }
       }, 250)
diff --git a/src/main/ssh/ssh-connection.ts b/src/main/ssh/ssh-connection.ts
index d38b0ab359c..eb2f79cf13a 100644
--- a/src/main/ssh/ssh-connection.ts
+++ b/src/main/ssh/ssh-connection.ts
@@ -51,15 +51,10 @@ type SshRemoteFileOptions = {
   hostPlatform?: RemoteHostPlatform
 }
 
-// Upper bound on waiting, after an abort, for the in-flight open callback or
-// for an aborted late-opened channel to finish closing before rejecting
-// anyway. Normal opens and closes complete in one network round-trip.
+// Upper bound on waiting for an aborted channel's open/close to settle before rejecting anyway.
 const ABORTED_CHANNEL_CLOSE_GRACE_MS = 5_000
 
-// Why: on session-limited servers (MaxSessions), a channel open can be refused
-// transiently — e.g. our next CHANNEL_OPEN reaching sshd a few microseconds
-// before it finishes processing the previous channel's close. A refused open
-// never started the command, so retrying is always safe.
+// Why: MaxSessions servers can transiently refuse a channel open; a refused open never ran the command, so retry is safe.
 const SESSION_LIMIT_OPEN_RETRIES = 4
 const SESSION_LIMIT_OPEN_RETRY_DELAY_MS = 150
 
@@ -131,12 +126,7 @@ export class SshConnection {
     this.callbacks = callbacks
   }
 
-  // Why: exposes whether a passphrase/password is already cached in-memory for
-  // this connection. Used by ssh:needsPassphrasePrompt so callers can decide
-  // whether a manual-reconnect will prompt or go through silently. Without this,
-  // lastRequiredPassphrase stays true across the session even after the user
-  // has entered the credential once, causing redundant "enter passphrase"
-  // prompts on disconnect→reconnect cycles within a single app session.
+  // Why: lets ssh:needsPassphrasePrompt skip redundant passphrase prompts on reconnect when the credential is already cached in-memory.
   hasCachedCredential(): boolean {
     return this.cachedPassphrase != null || this.cachedPassword != null
   }
@@ -247,10 +237,7 @@ export class SshConnection {
         unconfirmedOpenError = Object.assign(error, { sshChannelCloseConfirmed: false })
         return unconfirmedOpenError
       }
-      // Why: rejecting the instant the signal aborts lets the caller proceed
-      // while the in-flight channel open completes in the background and holds
-      // a server-side session slot (MaxSessions). Mark the abort and settle
-      // from the open callback, after the late resource has been closed.
+      // Why: an in-flight open holds a MaxSessions slot; reject the caller now, then settle from the open callback once the late channel closes.
       let abortRequested = false
       let abortDeadlineTimer: NodeJS.Timeout | undefined
       const cleanup = (): void => {
@@ -260,8 +247,7 @@ export class SshConnection {
       }
       const onAbort = (): void => {
         abortRequested = true
-        // Why: a hung socket may never invoke the open callback — bound the
-        // aborted caller's wait instead of pinning it for CONNECT_TIMEOUT_MS.
+        // Why: a hung socket may never invoke the open callback; bound the aborted caller's wait instead of pinning it for CONNECT_TIMEOUT_MS.
         abortDeadlineTimer = setTimeout(() => {
           settled = true
           cleanup()
@@ -288,8 +274,7 @@ export class SshConnection {
         if (onClose) {
           emitter.once?.('close', onClose)
         }
-        // Why: ssh2 can withhold CHANNEL_CLOSE while discarded exec streams
-        // remain unread, and teardown errors have no other owner.
+        // Why: ssh2 withholds CHANNEL_CLOSE while discarded exec streams remain unread, and teardown errors have no other owner.
         emitter.resume?.()
         emitter.stderr?.resume?.()
         try {
@@ -320,14 +305,12 @@ export class SshConnection {
           }
           done()
         }
-        // Why: bounded — a remote that never confirms the close must not hang
-        // the aborted operation forever.
+        // Why: bounded so a remote that never confirms the close can't hang the aborted operation forever.
         const closeGraceTimer = setTimeout(done, ABORTED_CHANNEL_CLOSE_GRACE_MS)
         if (typeof emitter.once === 'function') {
           emitter.once('close', confirmAndDone)
         }
-        // Why: ssh2 withholds the 'close' event until the channel's streams
-        // are drained; nobody else will ever read this discarded channel.
+        // Why: ssh2 withholds 'close' until the channel's streams are drained; nobody else will read this discarded channel.
         discardLateValue(value)
         if (typeof emitter.once !== 'function') {
           done()
@@ -335,9 +318,7 @@ export class SshConnection {
       }
       const finish = (error: Error | undefined, value?: T): void => {
         if (settled) {
-          // Why: ssh2 can invoke the open callback after our timeout has
-          // rejected. Close that late resource so the remote channel is not
-          // left open with no owner.
+          // Why: ssh2 can invoke the open callback after our timeout rejected; close that late channel so it isn't left open with no owner.
           if (!error && value !== undefined) {
             discardLateValue(value, () => {
               if (unconfirmedOpenError) {
@@ -372,8 +353,7 @@ export class SshConnection {
       signal?.addEventListener('abort', onAbort, { once: true })
 
       try {
-        // Why: higher-level channel timers start only after ssh2 invokes its
-        // open callback. A stale SSH socket can otherwise keep exec/sftp stuck.
+        // Why: higher-level channel timers start only after ssh2's open callback; a stale SSH socket can otherwise keep exec/sftp stuck.
         register(finish)
       } catch (error) {
         finish(error instanceof Error ? error : new Error(String(error)))
@@ -386,8 +366,7 @@ export class SshConnection {
     remoteDir: string,
     options?: SshRemoteFileOptions & { signal?: AbortSignal }
   ): Promise<void> {
-    // Why: relay deployment timeout and connection teardown are independent;
-    // either owner must stop a transfer that can otherwise outlive its lock.
+    // Why: relay-deploy timeout and connection teardown are independent owners; either must stop a transfer that could outlive its lock.
     const linkedSignal = createLinkedSshFileTransferSignal(
       [this.systemOperationAbortController.signal, options?.signal].filter(
         (signal): signal is AbortSignal => signal !== undefined
@@ -463,8 +442,7 @@ export class SshConnection {
         close: () => sftp.end()
       }
     }
-    // Why: disconnect replaces the connection controller; an existing import
-    // session must stay bound to the signal and SSH config it opened with.
+    // Why: disconnect replaces the connection controller, so an existing import session must stay bound to the signal and SSH config it opened with.
     const signal = this.systemOperationAbortController.signal
     const buildArgsOptions = this.getSystemSshBuildArgsOptions()
     return {
@@ -590,8 +568,7 @@ export class SshConnection {
       } catch (err) {
         lastError = err instanceof Error ? err : new Error(String(err))
 
-        // Why: a concurrent disconnect() already set 'disconnected'; a cancelled
-        // attempt's late error must not overwrite it with auth-failed/error.
+        // Why: a concurrent disconnect() already set 'disconnected'; a cancelled attempt's late error must not overwrite it with auth-failed/error.
         if (this.disposed) {
           throw lastError
         }
@@ -630,10 +607,7 @@ export class SshConnection {
       await this.doSystemSshProbeWithControlMasterRetry(connectGeneration, resolved)
       return
     }
-    // Why: ssh2 has no gssapi-with-mic support, so hosts that explicitly
-    // request GSSAPIAuthentication try Kerberos SSO via the system OpenSSH
-    // binary first. Restrict the probe to GSSAPI so missing tickets fall through
-    // to Orca's existing key and credential-prompt path.
+    // Why: ssh2 lacks gssapi-with-mic; GSSAPIAuthentication hosts try Kerberos SSO via system OpenSSH first, then fall through to key/credential auth.
     if (this.target.gssapiAuthentication === true) {
       try {
         await this.doSystemSshProbeWithControlMasterRetry(connectGeneration, resolved, true)
@@ -644,9 +618,7 @@ export class SshConnection {
         }
       }
     }
-    // Why: a synchronous spawn throw (no system ssh binary) bypasses the probe's
-    // own catch, so the ssh2 fall-through must clear all system-transport state
-    // itself — otherwise exec/sftp keep routing through the failed transport.
+    // Why: a synchronous spawn throw bypasses the probe's catch, so clear system-transport state here or exec/sftp keep routing through the failed transport.
     this.systemSshResolvedConfig = null
     this.systemSshControlMasterDisabledForSession = false
     this.systemSshGssapiOnlyForSession = false
@@ -654,8 +626,7 @@ export class SshConnection {
 
     const config = buildConnectConfig(this.target, resolved)
 
-    // Why: ssh2 doesn't support ProxyCommand/ProxyJump natively. Spawn the
-    // resolved proxy and pipe its stdin/stdout as config.sock.
+    // Why: ssh2 doesn't support ProxyCommand/ProxyJump natively; spawn the resolved proxy and pipe its stdin/stdout as config.sock.
     const effectiveProxy = resolveEffectiveProxy(this.target, resolved)
     if (effectiveProxy) {
       const proxy = spawnProxyCommand(effectiveProxy, config.host!, config.port!, config.username!)
@@ -683,8 +654,7 @@ export class SshConnection {
         this.proxyProcess?.kill()
         this.proxyProcess = null
         try {
-          // Why: on macOS, per-app network policy can block Orca's direct
-          // TCP socket while the system OpenSSH binary is still allowed.
+          // Why: on macOS, per-app network policy can block Orca's direct TCP socket while the system OpenSSH binary is still allowed.
           await this.doSystemSshProbeWithControlMasterRetry(connectGeneration, resolved)
           return
         } catch {
@@ -700,16 +670,13 @@ export class SshConnection {
       let passphrasePromptHandled = false
       let credentialRetryConfig = config
 
-      // Why: ssh2 parses encrypted privateKey values before it tries agent
-      // auth. When an agent is available, give it the first attempt and only
-      // fall back to direct key parsing after agent auth fails.
+      // Why: ssh2 parses encrypted privateKey before agent auth; when an agent exists, let it try first and fall back to direct key parsing only if it fails.
       if (isAgentFallbackError(authError) && config.agent && !config.privateKey) {
         const keyConfig = buildConnectConfig(this.target, resolved, {
           includeAgent: false,
           includePrivateKey: true
         })
-        // Why: if the agent path failed, password/passphrase retries should not
-        // go back through the same agent-only config.
+        // Why: if the agent path failed, password/passphrase retries must not reuse the same agent-only config.
         credentialRetryConfig = keyConfig
         if (this.cachedPassphrase) {
           keyConfig.passphrase = this.cachedPassphrase
@@ -729,10 +696,7 @@ export class SshConnection {
               throw keyErr
             }
             authError = keyErr
-            // Why: when the effective config enables GSSAPI, let the reactive
-            // system-ssh probe (below) try a Kerberos ticket before prompting
-            // for the key passphrase; the general passphrase prompt still runs
-            // if that probe fails, since passphrasePromptHandled stays false.
+            // Why: with GSSAPI enabled, let the reactive system-ssh probe try a Kerberos ticket before prompting for the passphrase; the prompt still runs if it fails.
             if (
               isPassphraseError(authError) &&
               !this.cachedPassphrase &&
@@ -757,8 +721,7 @@ export class SshConnection {
         }
       }
 
-      // Why: a Kerberos ticket may authenticate where keys did not; try the
-      // system ssh binary before falling back to interactive prompts.
+      // Why: a Kerberos ticket may authenticate where keys did not; try the system ssh binary before falling back to interactive prompts.
       if (isGssapiSystemSshFallbackCandidate(authError, this.target, resolved)) {
         this.proxyProcess?.kill()
         this.proxyProcess = null
@@ -771,9 +734,7 @@ export class SshConnection {
           this.systemSshGssapiOnlyForSession = false
           this.useSystemSshTransport = false
         }
-        // Why: if a disconnect/reconnect superseded this attempt mid-probe, throw
-        // the cancellation error — not the stale ssh2 authError — so connect()
-        // does not post auth-failed after the target was deliberately disconnected.
+        // Why: if a disconnect/reconnect superseded this attempt mid-probe, throw the cancellation error (not the stale authError) so connect() doesn't post auth-failed.
         if (this.disposed || !this.isCurrentConnectAttempt(connectGeneration)) {
           throw this.createCancelledConnectAttemptError()
         }
@@ -785,8 +746,7 @@ export class SshConnection {
         throw authError
       }
 
-      // Why: prompt for passphrase on encrypted-key error, then retry with
-      // a fresh proxy socket (ssh2 may have destroyed the original).
+      // Why: prompt for passphrase on encrypted-key error, then retry with a fresh proxy socket (ssh2 may have destroyed the original).
       if (isPassphraseError(authError) && !this.cachedPassphrase && !passphrasePromptHandled) {
         const detail = this.target.identityFile || resolved?.identityFile?.[0] || '(unknown)'
         const val = await this.callbacks.onCredentialRequest(this.target.id, 'passphrase', detail)
@@ -798,8 +758,7 @@ export class SshConnection {
           return
         }
       }
-      // Why: an agent socket failure can still be recovered by password auth,
-      // but the retry must use the no-agent config selected above.
+      // Why: an agent socket failure can still be recovered by password auth, but the retry must use the no-agent config selected above.
       if (isAgentFallbackError(authError) && !this.cachedPassword) {
         const val = await this.callbacks.onCredentialRequest(
           this.target.id,
@@ -828,9 +787,7 @@ export class SshConnection {
       clearTimeout(this.reconnectTimer)
       this.reconnectTimer = null
     }
-    // Why: OS sleep/wake can leave ssh2 thinking a dead TCP socket is still
-    // connected. Tear down the local transport and run the normal reconnect
-    // path so the relay session can reattach remote PTYs after wake.
+    // Why: OS sleep/wake can leave ssh2 thinking a dead TCP socket is still connected; tear down and reconnect so the relay can reattach remote PTYs.
     this.closeTransportsForReconnect()
     this.state.reconnectAttempt = 0
     this.setState('reconnecting')
@@ -843,8 +800,7 @@ export class SshConnection {
     this.proxyProcess?.kill()
     this.proxyProcess = null
 
-    // Why: this probe runs before remote platform detection. A raw echo works
-    // under POSIX shells, cmd.exe, and PowerShell; `/bin/sh` wrapping does not.
+    // Why: this probe runs before remote platform detection; a raw echo works under POSIX shells, cmd.exe, and PowerShell, but `/bin/sh` wrapping does not.
     const channel = this.spawnTrackedSystemSshCommand('echo ORCA-SYSTEM-SSH-OK', {
       wrapCommand: false
     })
@@ -1006,8 +962,7 @@ export class SshConnection {
         reject(this.createCancelledConnectAttemptError())
       }
       const onReady = (): void => {
-        // Why: direct system SSH startup has the same late-ready race as ssh2;
-        // disconnect/reconnect must own the generation before state can flip.
+        // Why: direct system SSH has the same late-ready race as ssh2; disconnect/reconnect must own the generation before state flips.
         if (!this.isCurrentConnectAttempt(connectGeneration)) {
           settle(cancelStartup)
           return
@@ -1101,8 +1056,7 @@ export class SshConnection {
     return options
   }
 
-  // Why: ssh2 may destroy the proxy socket on auth failure, so credential
-  // retries need a fresh proxy process and Duplex stream.
+  // Why: ssh2 may destroy the proxy socket on auth failure, so credential retries need a fresh proxy process and Duplex stream.
   private respawnProxy(
     config: ConnectConfig,
     proxy: ReturnType<typeof resolveEffectiveProxy> | null | undefined
@@ -1126,8 +1080,7 @@ export class SshConnection {
         client.off('error', onStartupError)
       }
       const swallowLateStartupError = (): void => {
-        // Why: ssh2 can emit another socket error while a failed or cancelled
-        // pre-handshake client is being destroyed, after startup has settled.
+        // Why: ssh2 can emit another socket error while destroying a settled pre-handshake client.
       }
       const guardStartupDestroy = (): void => {
         client.on('error', swallowLateStartupError)
@@ -1137,9 +1090,7 @@ export class SshConnection {
         if (settled) {
           return
         }
-        // Why: connect() completion races with explicit disconnect(). Once a
-        // newer connect attempt or disconnect bumps the generation/disposed
-        // state, this late ready event must not resurrect the torn-down client.
+        // Why: connect() completion races with disconnect(); a late ready must not resurrect a torn-down client after generation/disposed changes.
         if (this.disposed || connectGeneration !== this.connectGeneration) {
           settled = true
           guardStartupDestroy()
@@ -1154,15 +1105,7 @@ export class SshConnection {
         this.proxyProcess = null
         this.setupDisconnectHandler(client)
         cleanupStartupListeners()
-        // Why: ssh2 leaves Nagle's algorithm on by default. For single-byte
-        // keystrokes through a remote PTY this stacks with the kernel's
-        // delayed-ACK timer and adds up to ~40 ms per keystroke. OpenSSH's
-        // `ssh` sets TCP_NODELAY whenever a PTY is allocated; we mirror that
-        // because every channel we open over this connection (PTY data,
-        // JSON-RPC requests, port-scan probes) is latency-sensitive. No-op
-        // for proxy-command / proxy-jump connections where _sock is a custom
-        // Duplex; that case relies on the proxy program's own TCP behavior,
-        // same as native ssh.
+        // Why: ssh2 leaves Nagle on; enable TCP_NODELAY so keystrokes don't stack with delayed-ACK (~40ms each). No-op for proxy sockets.
         const sock = (client as unknown as { _sock?: { setNoDelay?: unknown } })._sock
         if (sock instanceof net.Socket) {
           console.warn(`[ssh] TCP_NODELAY enabled for ${this.target.label}`)
@@ -1191,8 +1134,7 @@ export class SshConnection {
     })
   }
 
-  // Why: guard on identity so a late event from the old client doesn't
-  // null out a successful reconnect.
+  // Why: guard on identity so a late event from the old client can't null out a successful reconnect.
   private setupDisconnectHandler(client: SshClient): void {
     const onDrop = () => {
       if (this.disposed || this.client !== client) {
@@ -1234,8 +1176,7 @@ export class SshConnection {
 
   private async runReconnectAttempt(attempt: number): Promise<void> {
     try {
-      // Why: reset reconnectAttempt before attemptConnect so setState('connected')
-      // broadcasts reconnectAttempt=0, which ssh.ts uses to trigger relay re-establishment.
+      // Why: reset before connecting so the 'connected' broadcast carries reconnectAttempt=0, which ssh.ts uses to trigger relay re-establishment.
       this.state.reconnectAttempt = 0
       await this.attemptConnect()
     } catch (err) {
@@ -1316,9 +1257,7 @@ export class SshConnection {
       this.systemSsh = proc
       this.useSystemSshTransport = true
       this.setState('connected')
-      // Why: register reconnection handler only after the initial handshake
-      // succeeds. The onExit registered above guards with `settled` so it
-      // won't fire a duplicate for exits during the handshake phase.
+      // Why: register the reconnect handler only after handshake succeeds (the onExit above guards with `settled`).
       proc.onExit(() => {
         if (!this.disposed && this.systemSsh === proc) {
           this.systemSsh = null
diff --git a/src/main/ssh/ssh-relay-deploy.ts b/src/main/ssh/ssh-relay-deploy.ts
index 56779b87f0f..2d1a1a446fc 100644
--- a/src/main/ssh/ssh-relay-deploy.ts
+++ b/src/main/ssh/ssh-relay-deploy.ts
@@ -1,8 +1,5 @@
 import { join } from 'node:path'
-/* eslint-disable max-lines -- Why: the relay-deploy module owns one cohesive
-   contract — version detection, install-locked deploy, native-deps probe,
-   relay launch, and GC — and splitting risks drift between the install
-   sequence and the GC's live-socket invariant. */
+/* eslint-disable max-lines -- Why: one cohesive contract (version detect, install-locked deploy, native-deps probe, launch, GC); splitting risks install/GC drift. */
 import { existsSync } from 'node:fs'
 import { app } from 'electron'
 import type { SshConnection } from './ssh-connection'
@@ -101,15 +98,7 @@ function execHostCommand(
 }
 
 /**
- * Deploy the relay to the remote host and launch it.
- *
- * Steps:
- * 1. Detect remote OS/arch via `uname -sm`
- * 2. Check if correct relay version is already deployed
- * 3. If not, SCP the relay package
- * 4. Launch relay via exec channel
- * 5. Wait for ORCA-RELAY sentinel on stdout
- * 6. Return the transport (relay's stdin/stdout) for multiplexer use
+ * Deploy the relay to the remote host and launch it, returning the transport (relay's stdin/stdout) for multiplexer use.
  */
 export async function deployAndLaunchRelay(
   conn: SshConnection,
@@ -118,8 +107,7 @@ export async function deployAndLaunchRelay(
   relayInstanceId?: string
 ): Promise<RelayDeployResult> {
   let timeoutHandle: ReturnType<typeof setTimeout>
-  // Why: Promise.race does not cancel its loser. Stop a contended install-lock
-  // waiter so it cannot acquire and mutate the relay after this call times out.
+  // Why: Promise.race doesn't cancel its loser; abort so a contended install-lock waiter can't mutate the relay after this call times out.
   const deployAbortController = new AbortController()
   const timeoutPromise = new Promise<never>((_resolve, reject) => {
     timeoutHandle = setTimeout(() => {
@@ -145,12 +133,9 @@ export async function deployAndLaunchRelay(
 }
 
 /**
- * Resolve the remote home, derive the versioned relay directory, and check
- * whether the relay is already installed there.
+ * Resolve the remote home, derive the versioned relay dir, and check whether the relay is installed there.
  *
- * Why: extracted so the deploy can run this chain concurrently with node-path
- * resolution (the two are independent). Home and install-check stay sequential
- * here because the install-check needs the resolved directory.
+ * Why: extracted to run concurrently with node-path resolution; home and install-check stay sequential because the check needs the resolved dir.
  */
 async function resolveRemoteInstallState(
   conn: SshConnection,
@@ -158,17 +143,14 @@ async function resolveRemoteInstallState(
   fullVersion: string,
   options?: { rethrowSessionLimitErrors?: boolean; signal?: AbortSignal }
 ): Promise<{ remoteHome: string; remoteRelayDir: string; alreadyInstalled: boolean }> {
-  // Why: SFTP does not expand `~`, so we must resolve the remote home
-  // explicitly with the host's native shell and normalize it before use.
+  // Why: SFTP doesn't expand `~`, so resolve the remote home explicitly via the host's native shell and normalize it.
   const remoteHome = normalizeRemoteHome(
     await execHostCommand(conn, hostPlatform, readRemoteHomeCommand(hostPlatform), {
       signal: options?.signal
     }),
     hostPlatform
   )
-  // Why: we only interpolate $HOME into single-quoted shell strings later, so
-  // this validation only needs to reject obviously unsafe control characters.
-  // Allow spaces and non-ASCII so valid home directories are not rejected.
+  // Why: $HOME is only used inside single-quoted shell strings, so validation only rejects control chars — spaces and non-ASCII stay valid.
   if (!validateRemoteHome(remoteHome, hostPlatform)) {
     throw new Error(`Remote home is not a valid path: ${remoteHome.slice(0, 100)}`)
   }
@@ -264,8 +246,7 @@ function isAbortError(err: unknown): boolean {
 }
 
 /**
- * Detect the remote platform, resolve install state and node path, install the
- * relay if it is not already present, then launch it and return the transport.
+ * Detect platform, resolve install state + node path, install if absent, launch, and return the transport.
  * Inner implementation wrapped by `deployAndLaunchRelay` with an overall timeout.
  */
 async function deployAndLaunchRelayInner(
@@ -289,8 +270,7 @@ async function deployAndLaunchRelayInner(
       if (!(err instanceof RelayDirectoryGcConflictError)) {
         throw err
       }
-      // Why: GC atomically moves the old install aside. Wait for its stable
-      // sibling claim to clear, then recompute install state from scratch.
+      // Why: GC atomically moves the old install aside; wait for its sibling claim to clear, then recompute install state.
       await waitForRelayGcClaimRelease(conn, err.remoteRelayDir, err.hostPlatform, deploySignal)
     }
   }
@@ -321,19 +301,11 @@ async function deployAndLaunchRelayAttempt(
         `This may be a packaging issue — try reinstalling Orca.`
     )
   }
-  // Why: read the content-hashed full version from the local build's .version
-  // file. Used as both the remote dir name and the wire-handshake version.
-  // Throws on missing/empty rather than silently falling back — see
-  // docs/ssh-relay-versioned-install-dirs.md "Data Flow: Upstream Error".
+  // Why: content-hashed version doubles as remote dir name and wire-handshake version; throws on missing rather than falling back (see docs/ssh-relay-versioned-install-dirs.md).
   const fullVersion = readLocalFullVersion(localRelayDir)
 
   onProgress?.('Checking existing relay...')
-  // Why: the remote-home -> install-check chain and node resolution are
-  // independent (both only need hostPlatform, not each other's results), yet
-  // each is a separate SSH exec round trip. Run them concurrently so the deploy
-  // pays one round trip instead of two for this phase. Most failures stay
-  // fail-fast; remotes that reject overlapping session channels retry the old
-  // sequential order so restrictive SSH servers keep working.
+  // Why: install-check and node resolution are independent; run concurrently to save a round trip, with sequential fallback for restrictive SSH servers.
   const { remoteHome, remoteRelayDir, alreadyInstalled, nodePath } =
     await resolveRelayBootstrapState(conn, hostPlatform, fullVersion, deploySignal)
   console.log(`[ssh-relay] Remote dir: ${remoteRelayDir}`)
@@ -354,14 +326,11 @@ async function deployAndLaunchRelayAttempt(
     launchGcClaimToken = launchFence.gcClaimToken
     deploySignal?.throwIfAborted()
   } else {
-    // Why: serialize concurrent first-installs of the same version against
-    // each other via a host-native exclusive lock. The losing caller polls and either
-    // re-checks `alreadyInstalled` (now true) or steals a stale lock.
+    // Why: serialize concurrent first-installs via a host-native exclusive lock; the loser polls to re-check installed or steal a stale lock.
     await acquireInstallLock(conn, remoteRelayDir, hostPlatform, { signal: deploySignal })
     ownsInstallLock = true
     try {
-      // Re-probe after acquiring the lock — a sibling installer may have
-      // finished while we were waiting.
+      // Re-probe after acquiring the lock — a sibling installer may have finished while we waited.
       if (
         !(await isRelayAlreadyInstalled(conn, remoteRelayDir, hostPlatform, {
           signal: deploySignal
@@ -384,18 +353,15 @@ async function deployAndLaunchRelayAttempt(
         )
         console.log('[ssh-relay] Native deps installed')
 
-        // Why: mark complete but retain the lock until launch makes daemon
-        // liveness observable to cross-version GC.
+        // Why: mark complete but retain the lock until launch makes daemon liveness observable to cross-version GC.
         await finalizeInstall(conn, remoteRelayDir, hostPlatform, {
           signal: deploySignal,
           releaseLock: false
         })
       }
     } catch (err) {
-      // Why: leave a partial install dir in place (no `.install-complete`)
-      // so the next deploy detects the partial and re-runs upload + install.
-      // Keep the lock if remote command termination was not confirmed; stale
-      // recovery is safer than overlapping a still-running npm process.
+      // Why: leave a partial install dir (no .install-complete) so the next deploy re-runs upload + install.
+      // Why: keep the lock if remote termination was unconfirmed — stale recovery beats overlapping a still-running npm.
       if (!isUnconfirmedSshCommandTermination(err)) {
         await abandonInstall(conn, remoteRelayDir, hostPlatform)
         ownsInstallLock = false
@@ -421,23 +387,18 @@ async function deployAndLaunchRelayAttempt(
     )
     launchLivenessObserved = true
   } finally {
-    // Why: older clients understand only the install lock. If launch never
-    // becomes live, retain it for stale recovery so their GC cannot race a
-    // concurrent caller that was waiting behind this owner.
+    // Why: older clients understand only the install lock; if launch never goes live, keep it so their GC can't race a caller waiting behind this owner.
     if (ownsInstallLock && launchLivenessObserved) {
       await abandonInstall(conn, remoteRelayDir, hostPlatform)
     }
-    // The detached start may outlive a timed-out SSH command. Preserve either
-    // fence on failed launch until stale recovery can prove the handoff ended.
+    // The detached start may outlive a timed-out SSH command; keep the fence on failed launch until stale recovery proves the handoff ended.
     if (launchGcClaimToken && launchLivenessObserved) {
       await releaseRelayGcClaimWithRetry(conn, remoteRelayDir, launchGcClaimToken, hostPlatform)
     }
   }
   console.log('[ssh-relay] Relay started successfully')
 
-  // Why: best-effort cleanup of unreferenced sibling version dirs. Errors
-  // are logged inside gcOldRelayVersions and never propagate, so a GC failure
-  // can never block the user from connecting.
+  // Why: best-effort GC of unreferenced sibling version dirs; errors are swallowed so a GC failure never blocks connecting.
   void gcOldRelayVersions(conn, remoteHome, remoteRelayDir, hostPlatform, {
     windowsNodePath: launched.nodePath,
     windowsSockNames: [relaySocketNameForInstanceId(relayInstanceId)]
@@ -470,14 +431,12 @@ async function uploadRelay(
     )
   }
 
-  // Create remote directory
   await execHostCommand(conn, hostPlatform, makeRemoteDirectoryCommand(hostPlatform, remoteDir), {
     signal
   })
 
   await uploadDirectoryForConnection(conn, localRelayDir, remoteDir, hostPlatform, signal)
 
-  // Make the node binary executable
   if (!isWindowsRemoteHost(hostPlatform)) {
     await execHostCommand(
       conn,
@@ -487,9 +446,7 @@ async function uploadRelay(
     )
   }
 
-  // Why: write `.version` via SFTP rather than shell to avoid quoting issues
-  // with content-hashed version strings. The remote daemon reads this same
-  // file on startup so the wire-handshake validates against it.
+  // Why: write .version via SFTP not shell to avoid quoting content-hashed versions; the daemon reads it to validate the wire handshake.
   await writeRemoteFile(
     conn,
     hostPlatform,
@@ -535,8 +492,7 @@ async function writeRemoteFile(
   try {
     await new Promise<void>((resolve, reject) => {
       const ws = sftp.createWriteStream(remotePath)
-      // .once: a session 'error' arriving after we've already resolved/rejected
-      // would otherwise become an unhandled error and crash main.
+      // .once: a late session 'error' after resolve/reject would otherwise be unhandled and crash main.
       sftp.once('error', reject)
       ws.once('close', resolve)
       ws.once('error', reject)
@@ -556,15 +512,13 @@ type RelayNativeDepName = keyof typeof RELAY_NATIVE_DEPS
 const RELAY_NATIVE_DEP_NAMES = Object.keys(RELAY_NATIVE_DEPS) as RelayNativeDepName[]
 const NATIVE_DEPS_MISSING_PREFIX = 'ORCA-NATIVE-DEPS-MISSING:'
 
-// Why: npm 12 blocks dependency lifecycle scripts unless each exact package
-// version is approved, even when ignore-scripts is explicitly disabled.
+// Why: npm 12 blocks dependency lifecycle scripts unless each exact package version is approved, even with ignore-scripts disabled.
 const RELAY_NATIVE_DEP_SCRIPT_ALLOWLIST = Object.fromEntries(
   Object.entries(RELAY_NATIVE_DEPS).map(([name, version]) => [`${name}@${version}`, true])
 )
 
 function nativeDepsProbeJs(successToken: string): string {
-  // Why: node-pty's Windows wrapper defers loading conpty.node until first
-  // spawn, so require("node-pty") alone cannot prove the binding is healthy.
+  // Why: node-pty's Windows wrapper defers conpty.node until first spawn, so require("node-pty") alone can't prove the binding is healthy.
   const loadNodePty =
     'require("node-pty"); require("node-pty/lib/utils").loadNativeModule(process.platform==="win32"&&Number(require("os").release().split(".")[2])>=18309?"conpty":"pty")'
   return `(()=>{const missing=[];try{${loadNodePty}}catch{missing.push("node-pty")}try{require("@parcel/watcher")}catch{missing.push("@parcel/watcher")}if(missing.length){console.log("${NATIVE_DEPS_MISSING_PREFIX}"+missing.join(","));process.exitCode=1}else{console.log(${JSON.stringify(successToken)})}})()`
@@ -644,8 +598,7 @@ async function repairInstalledNativeDeps(
       throw err
     }
     if (!stillInstalled) {
-      // Why: GC may finish its rename before our lock attempt recreates the
-      // original path. Never trust probes made before this locked recheck.
+      // Why: GC may finish its rename before our lock recreates the path; never trust probes made before this locked recheck.
       await abandonInstall(conn, remoteDir, hostPlatform)
       throw new RelayDirectoryGcConflictError(remoteDir, hostPlatform)
     }
@@ -655,16 +608,11 @@ async function repairInstalledNativeDeps(
       ? await acquireRelayLaunchGcFence(conn, remoteDir, hostPlatform, signal)
       : undefined
   if (initialProbe.available) {
-    // Why: even a healthy reconnect must stay fenced until launch liveness is
-    // observable; otherwise cross-version GC can rename after this probe.
+    // Why: even a healthy reconnect stays fenced until launch liveness is observable, or cross-version GC can rename after this probe.
     return { ownsInstallLock: lockResult === 'acquired', gcClaimToken }
   }
 
-  // Why: an already-installed relay can launch in degraded mode (fs/git/preflight
-  // still work; native-backed ops fail), so native-deps repair is best-effort:
-  // lock contention and repair failures must not abort the connection. Pre-repair
-  // this path used require.resolve (which passed for a present-but-unloadable
-  // binding), so a fatal repair here would be a straight regression.
+  // Why: an already-installed relay can launch degraded, so native-deps repair is best-effort — lock contention and failures must not abort the connection.
   console.warn(`[ssh-relay] Repairing missing native deps at ${remoteDir}`)
   if (lockResult === 'busy' || lockResult === 'error') {
     console.warn(
@@ -673,8 +621,7 @@ async function repairInstalledNativeDeps(
     return { ownsInstallLock: false, gcClaimToken }
   }
   try {
-    // Why: older complete relay dirs were created before @parcel/watcher was
-    // installed. Re-probe under the lock so only one reconnect mutates the dir.
+    // Why: older complete relay dirs predate @parcel/watcher; re-probe under the lock so only one reconnect mutates the dir.
     const probe = await probeRequiredNativeDeps(conn, remoteDir, hostPlatform, nodePath, signal)
     if (!probe.available) {
       await installNativeDeps(
@@ -691,9 +638,8 @@ async function repairInstalledNativeDeps(
     return { ownsInstallLock: true }
   } catch (err) {
     const terminationUnconfirmed = isUnconfirmedSshCommandTermination(err)
-    // Why: keep a confirmed-failure lock through degraded launch so GC cannot
-    // move the relay before liveness is visible. Unconfirmed remote mutation
-    // keeps its stale-recoverable lock beyond this connection.
+    // Why: hold a confirmed-failure lock through degraded launch so GC can't move the relay before liveness is visible.
+    // Why: unconfirmed remote mutation keeps its stale-recoverable lock beyond this connection.
     console.warn(
       `[ssh-relay] Native deps repair failed at ${remoteDir}; launching degraded: ${
         err instanceof Error ? err.message : String(err)
@@ -723,8 +669,7 @@ async function acquireRelayLaunchGcFence(
     if (!stillInstalled) {
       throw new RelayDirectoryGcConflictError(remoteDir, hostPlatform)
     }
-    // Why: a caller that cannot own the install lock still needs its own
-    // durable fence; never borrow another connection's lock through launch.
+    // Why: a caller without the install lock still needs its own durable fence; never borrow another connection's lock through launch.
     return token
   } catch (err) {
     await releaseRelayGcClaimWithRetry(conn, remoteDir, token, hostPlatform)
@@ -732,14 +677,8 @@ async function acquireRelayLaunchGcFence(
   }
 }
 
-// Why: node-pty and @parcel/watcher are native addons that can't be bundled by
-// esbuild. They must be installed on the remote host against its Node.js version
-// and OS so dynamic imports/require calls resolve from the relay dir.
-//
-// TODO(#1693): VS Code ships per-platform tarballs with node-pty pre-built
-// from CI and skips `npm install` on the remote entirely. That approach
-// eliminates the whole class of bugs around npm/compiler/network failures
-// on the remote. Worth doing once we're past the immediate fix.
+// Why: node-pty and @parcel/watcher are native addons esbuild can't bundle; install them on the remote against its Node/OS.
+// TODO(#1693): ship per-platform tarballs with node-pty prebuilt from CI to skip remote npm install.
 async function installNativeDeps(
   conn: SshConnection,
   remoteDir: string,
@@ -749,14 +688,9 @@ async function installNativeDeps(
   signal?: AbortSignal,
   resetDeps: RelayNativeDepName[] = []
 ): Promise<void> {
-  // Why: commandWithNodePath puts node's bin directory in PATH for npm's child processes.
-  // npm install runs node-pty's prebuild script (`node scripts/prebuild.js`)
-  // which spawns `node` as a child — if node isn't in PATH, that child
-  // fails with exit 127 even though we invoked npm via its full path.
-  // npm init -y rejects '+' in derived package names (content-hashed dir
-  // names like relay-0.1.0+abc123). Bypass it with a fixed minimal
-  // package.json. type:commonjs pins module resolution against Node default
-  // flips or a remote ~/.npmrc setting type=module.
+  // Why: node-pty's prebuild spawns `node` as a child, so node must be in PATH (commandWithNodePath) or it fails exit 127.
+  // Why: npm init -y rejects '+' in content-hashed dir names, so write a fixed minimal package.json instead.
+  // Why: type:commonjs pins module resolution against Node default flips or a remote ~/.npmrc type=module.
   const pkgJson = `${JSON.stringify({
     name: 'orca-relay',
     version: '1.0.0',
@@ -777,8 +711,7 @@ async function installNativeDeps(
     const installArgs = Object.entries(RELAY_NATIVE_DEPS)
       .map(([dep, version]) => shellEscape(`${dep}@${version}`))
       .join(' ')
-    // Why: npm reports a present package as up to date even when one packaged
-    // native file was deleted. Reset only dependencies the probe found broken.
+    // Why: npm reports a present package as up to date even if a native file was deleted; reset only deps the probe found broken.
     const resetCommand = resetNativeDepsCommand(hostPlatform, resetDeps)
     const resetPrefix = resetCommand ? `${resetCommand}; ` : ''
     const command = isWindowsRemoteHost(hostPlatform)
@@ -807,17 +740,12 @@ async function installNativeDeps(
       throw err
     }
     signal?.throwIfAborted()
-    // Don't write .install-complete on hard fail; reconnect retries on a
-    // partial install. Greppable token so user bug reports paste something
-    // searchable.
+    // Don't write .install-complete on hard fail so reconnect retries the partial install; greppable token aids bug reports.
     const msg = (err as Error).message
     console.warn(
       `[ssh-relay][NATIVE-DEPS-INSTALL-FAIL] npm install native deps failed at ${remoteDir} (${platform}): ${msg}`
     )
-    // Why: on Linux node-pty has no prebuild and must compile, so a missing
-    // C/C++ toolchain is the dominant first-connect failure (#1693). Probe the
-    // remote and replace node-gyp's opaque `not found: make` with an actionable
-    // install hint instead of leaking the raw npm output to the user.
+    // Why: on Linux node-pty compiles, so a missing C/C++ toolchain is the dominant first-connect failure (#1693); probe to give an actionable install hint.
     if (platform.startsWith('linux') && shouldProbeBuildToolchainAfterNativeDepsFailure(msg)) {
       const toolchain = await probeBuildToolchain(conn, hostPlatform, signal)
       if (toolchain?.toolchainMissing) {
@@ -831,8 +759,7 @@ async function installNativeDeps(
 
   let probe = await probeInstalledNativeDeps(conn, remoteDir, hostPlatform, nodePath, signal)
   if (!probe.available) {
-    // Why: npm treats an already-present package as up to date, so enabling
-    // lifecycle scripts on install cannot repair a binding skipped earlier.
+    // Why: npm treats an already-present package as up to date, so re-enabling lifecycle scripts on install can't repair a skipped binding.
     console.warn(`[ssh-relay] Rebuilding unloadable native deps at ${remoteDir}`)
     let rebuilt = false
     try {
@@ -854,8 +781,7 @@ async function installNativeDeps(
     }
   }
 
-  // MISSING is non-fatal by design: the relay still serves fs/git/preflight;
-  // only native-backed operations fail on hosts that cannot build the addons.
+  // MISSING is non-fatal by design: the relay still serves fs/git/preflight; only native-backed ops fail on hosts that can't build the addons.
   if (!probe.available) {
     console.warn(
       `[ssh-relay][NPTY-MISSING] native deps installed but require() failed at ${remoteDir} (${platform}). stdout=${probe.output.trim().slice(-200)} stderr=${probe.stderr.trim().slice(-500)}`
@@ -937,8 +863,7 @@ async function makeNodePtySpawnHelperExecutable(
   if (isWindowsRemoteHost(hostPlatform)) {
     return
   }
-  // SFTP doesn't preserve execute bits; node-pty's spawn-helper prebuild
-  // must be +x for posix_spawnp.
+  // SFTP doesn't preserve execute bits; node-pty's spawn-helper must be +x for posix_spawnp.
   await execHostCommand(
     conn,
     hostPlatform,
@@ -959,8 +884,7 @@ async function probeInstalledNativeDeps(
   output: string
   stderr: string
 }> {
-  // require() catches unloadable installs (wrong arch, missing prebuild, or a
-  // skipped lifecycle script) that require.resolve() and test -d both miss.
+  // require() catches unloadable installs (wrong arch, missing prebuild, skipped lifecycle script) that require.resolve() and test -d miss.
   const PROBE_OK = 'ORCA-NPTY-PROBE-OK'
   const stderrFile = joinRemotePath(hostPlatform, remoteDir, '.npty-probe.stderr')
   const escapedStderr = shellEscape(stderrFile)
@@ -1016,8 +940,7 @@ export function getLocalRelayCandidates(platform: RelayPlatform): string[] {
     candidates.push(join(process.env.ORCA_RELAY_PATH, platform))
   }
 
-  // Why: electron-builder copies extraResources next to the app bundle, while
-  // app.getAppPath() points at app.asar in packaged builds.
+  // Why: electron-builder copies extraResources next to the app bundle, but app.getAppPath() points at app.asar in packaged builds.
   if (process.resourcesPath) {
     candidates.push(join(process.resourcesPath, 'relay', platform))
     candidates.push(join(process.resourcesPath, 'app.asar.unpacked', 'out', 'relay', platform))
@@ -1041,13 +964,7 @@ async function launchRelay(
   relayInstanceId?: string,
   signal?: AbortSignal
 ): Promise<{ transport: MultiplexerTransport; nodePath: string; sockPath: string }> {
-  // Why: Phase 1 of the plan requires Node.js on the remote. We use the
-  // system `node` rather than bundling a node binary, keeping the relay
-  // package small (~100KB JS vs ~60MB with embedded node).
-  // Non-login SSH shells may not have node in PATH, so we source the
-  // user's profile to pick up nvm/fnm/brew PATH entries.
-  // Why: graceTimeSeconds originates from user-editable SshTarget config.
-  // Clamping to integer prevents shell injection if the type ever loosened.
+  // Why: graceTimeSeconds comes from user-editable SshTarget config; floor+clamp to an integer prevents shell injection if the type ever loosened.
   const requestedGraceTime = Math.floor(graceTimeSeconds ?? DEFAULT_SSH_RELAY_GRACE_PERIOD_SECONDS)
   const graceTime =
     requestedGraceTime === 0
@@ -1058,9 +975,7 @@ async function launchRelay(
         )
   const escapedDir = shellEscape(remoteDir)
   const escapedNode = shellEscape(nodePath)
-  // Why: remoteRelayDir is shared by every Orca target for the same remote
-  // account. Hashing the target ID into the socket name prevents one target
-  // from attaching to another target's live relay.
+  // Why: remoteRelayDir is shared across Orca targets for one account; hashing the target ID into the socket name stops cross-target attach.
   const sockName = relaySocketNameForInstanceId(relayInstanceId)
   const sockFile = relayEndpointForHost(hostPlatform, remoteDir, sockName)
   const endpointDir = relayHookEndpointDirForHost(hostPlatform, remoteDir, sockFile)
@@ -1094,10 +1009,7 @@ async function launchRelay(
     )
   }
 
-  // Why: after an app restart a relay may still be running in its grace
-  // period with live PTY sessions.  We check for its Unix socket and
-  // launch in --connect mode to bridge the new SSH channel to the
-  // existing relay process — preserving PTY state and scrollback.
+  // Why: after a restart the relay may still be alive in its grace period; --connect to its socket preserves PTY state and scrollback.
   try {
     const probeOutput = await execCommand(
       conn,
@@ -1121,8 +1033,7 @@ async function launchRelay(
           '[ssh-relay] Socket reconnect failed, launching fresh relay:',
           err instanceof Error ? err.message : String(err)
         )
-        // Why: stale socket from a crashed relay — remove it so the
-        // fresh launch can bind a new socket at the same path.
+        // Why: stale socket from a crashed relay — remove it so the fresh launch can bind at the same path.
         await execCommand(conn, `rm -f ${shellEscape(sockFile)}`, { signal }).catch(
           (cleanupErr) => {
             if (isUnconfirmedSshCommandTermination(cleanupErr)) {
@@ -1141,41 +1052,21 @@ async function launchRelay(
     // Probe failed — fall through to fresh launch
   }
 
-  // Why: the relay must outlive the SSH connection so PTY sessions survive
-  // app restarts.  nohup prevents SIGHUP death, </dev/null detaches stdin,
-  // and & backgrounds the process so it's not a direct child of the exec
-  // channel.  When sshd tears down the session the relay continues as an
-  // orphan adopted by init, listening on its Unix socket for a --connect
-  // bridge from the next app launch.
-  // Why: execCommand waits for the channel to close, but SSH channels stay
-  // open while backgrounded children exist (even with fd redirection).
-  // Fire-and-forget via conn.exec: we don't need the output — the socket
-  // poll below detects readiness.
+  // Why: relay must outlive the SSH connection so PTY sessions survive app restarts — nohup + </dev/null + & detach it from the exec channel.
+  // Why: execCommand would block on channel close that backgrounded children never allow; fire-and-forget via conn.exec, the socket poll detects readiness.
   const logFile = `${remoteDir}/relay.log`
-  // Why: pass --log-file so the relay rotates relay.log in-process (size cap +
-  // one archived generation). The shell redirect stays so pre-JS boot/crash
-  // output is still captured; once JS starts, the in-process rotator owns all
-  // subsequent logging (it wraps process.stderr/stdout), so the current log
-  // stays at relay.log for the `tail relay.log` diagnostics workflow.
+  // Why: --log-file lets the relay rotate relay.log in-process; the shell redirect stays to capture pre-JS boot/crash output.
   const launchCmd = `cd ${escapedDir} && nohup ${escapedNode} relay.js --detached --grace-time ${graceTime} --sock-path ${shellEscape(sockFile)} --log-file ${shellEscape(logFile)} > ${shellEscape(logFile)} 2>&1 </dev/null &`
   const launchChannel = await conn.exec(launchCmd, { signal })
   launchChannel.on('data', () => {})
   launchChannel.on('error', () => {})
   launchChannel.stderr.on('data', () => {})
   launchChannel.stderr.on('error', () => {})
-  // Why: the shell exits quickly (nohup ... &), but the SSH channel stays
-  // open until all child fds close. Explicitly closing it after the poll
-  // loop prevents channel accumulation across relay restarts, which would
-  // eventually hit the server's MaxSessions limit.
+  // Why: the SSH channel stays open until all child fds close; close it after the poll or channels accumulate and hit the server's MaxSessions limit.
   launchChannel.on('close', () => {})
 
-  // Why: the backgrounded relay needs time to bind its Unix socket.  We
-  // poll rather than sleep a fixed duration because remote host speed
-  // varies widely (CI vs. Raspberry Pi).
-  // Why: checking `test -S` only verifies the inode exists, not that the
-  // relay is listening. After a stale socket removal + fresh launch, the
-  // old inode can linger briefly. We probe with a connect-and-close to
-  // confirm the socket is actually accepting connections.
+  // Why: poll rather than fixed sleep — remote host speed varies widely (CI vs. Raspberry Pi).
+  // Why: test -S only proves the inode exists, not that the relay is listening; a connect-and-close confirms it accepts connections.
   const POLL_INTERVAL_MS = 200
   const POLL_TIMEOUT_MS = 10_000
   const pollStart = Date.now()
@@ -1183,10 +1074,7 @@ async function launchRelay(
   try {
     while (Date.now() - pollStart < POLL_TIMEOUT_MS) {
       try {
-        // Why: node is guaranteed to exist on the remote (we just deployed
-        // the relay with it). Using it to probe the socket is more portable
-        // than python3/socat/perl which may not be installed. The socket
-        // path is passed as argv[1] to avoid shell quoting issues with -e.
+        // Why: probe via node (guaranteed present) not python3/socat/perl; pass the socket path as argv[1] to dodge -e quoting issues.
         const result = await execCommand(
           conn,
           `${escapedNode} -e 'var s=require("net").connect(process.argv[1]);s.on("connect",function(){s.destroy();process.stdout.write("READY")});s.on("error",function(){process.stdout.write("WAITING")})' ${shellEscape(sockFile)} 2>/dev/null || (test -S ${shellEscape(sockFile)} && echo READY || echo WAITING)`,
@@ -1216,10 +1104,7 @@ async function launchRelay(
     throw new Error(`Relay failed to start within ${POLL_TIMEOUT_MS / 1000}s. Log:\n${logOutput}`)
   }
 
-  // Why: the backgrounded relay's stdout goes to a log file, not the exec
-  // channel.  We connect via --connect which bridges this new channel's
-  // stdin/stdout to the relay's Unix socket — same path used for reconnect
-  // after app restart.
+  // Why: backgrounded relay's stdout goes to a log file, not the exec channel; --connect bridges this channel to its Unix socket.
   const channel = await conn.exec(
     `cd ${escapedDir} && ${escapedNode} relay.js --connect --sock-path ${shellEscape(sockFile)}`,
     { signal }
@@ -1302,8 +1187,7 @@ async function rememberWindowsActiveRelayEndpoint(
     { signal }
   ).catch((err) => {
     signal?.throwIfAborted()
-    // Why: fallback pipe names are deterministic, so losing this marker does
-    // not force the next deploy to orphan an undiscoverable relay.
+    // Why: fallback pipe names are deterministic, so losing this marker won't orphan an undiscoverable relay.
     console.warn(
       `[ssh-relay] Failed to persist Windows active relay pipe at ${markerPath}: ${err instanceof Error ? err.message : String(err)}`
     )
@@ -1353,11 +1237,8 @@ async function launchWindowsRelay(
         err instanceof Error ? err.message : String(err)
       )
       if (opts.reconnectFallback) {
-        // Why: an existing Windows named pipe cannot be unlinked like a Unix
-        // socket; use a deterministic fallback pipe so marker write failures
-        // remain recoverable on the next deploy.
-        // Keep activePipeMarkerPath keyed by the original target sock name;
-        // the marker records the active pipe for that target, fallback or not.
+        // Why: a Windows named pipe can't be unlinked like a Unix socket; a deterministic fallback pipe keeps the next deploy recoverable.
+        // Why: spread keeps activePipeMarkerPath at the original target sock name — the marker records that target's active pipe, fallback or not.
         launchOpts = { ...opts, ...opts.reconnectFallback }
       }
     }
@@ -1489,8 +1370,7 @@ function windowsRelayLaunchCommand(
   errFile: string
 ): string {
   const relayScript = joinRemotePath(hostPlatform, remoteDir, 'relay.js')
-  // Why: Windows sshd kills the exec channel's process tree when the channel
-  // closes. WMI re-parents the detached relay so the named pipe stays alive.
+  // Why: Windows sshd kills the exec channel's process tree on close; WMI re-parents the detached relay to survive.
   const quoted = (value: string): string => `"${value.replace(/"/g, '\\"')}"`
   const relayCommandLine = [
     quoted(nodePath),
@@ -1502,8 +1382,7 @@ function windowsRelayLaunchCommand(
     quoted(sockPath),
     '--endpoint-dir',
     quoted(endpointDir),
-    // Why: in-process rotation owns relay.log (the tail-diagnostics target);
-    // the shell redirects remain for pre-JS boot/crash output.
+    // Why: --log-file owns rotation; shell redirects still capture pre-JS boot/crash output.
     '--log-file',
     quoted(logFile),
     `1>${quoted(logFile)}`,
diff --git a/src/main/ssh/ssh-relay-native-deps-install.test.ts b/src/main/ssh/ssh-relay-native-deps-install.test.ts
index f38a2b1065b..fdc7ff3e73e 100644
--- a/src/main/ssh/ssh-relay-native-deps-install.test.ts
+++ b/src/main/ssh/ssh-relay-native-deps-install.test.ts
@@ -1,8 +1,4 @@
-// Why: regression coverage for the install-probe contract. The original
-// "node-pty is not available" bug shipped because every layer that should
-// have caught it (chained shell, swallowing catch, resolve-only probe) was
-// silent. Tests below pin the parts that, individually, would have caught
-// it.
+// Why: regression coverage for the install-probe contract — the "node-pty is not available" bug shipped because every guard layer was silent.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -84,8 +80,7 @@ import type { SshConnection } from './ssh-connection'
 type SftpWriteCapture = {
   paths: string[]
   contents: Record<string, string>
-  // Number of execCommand calls observed at the moment ws.end() ran for each
-  // captured path. Used to pin "package.json was written before npm install".
+  // execCommand call count observed when ws.end() ran, per path — pins "package.json written before npm install".
   execCallCountAtWrite: Record<string, number>
 }
 
@@ -115,8 +110,7 @@ function makeMockConnection(capture: SftpWriteCapture): SshConnection {
           }
         })
       }
-      // Why: production code uses ws.once('close', ...). The 'once' wrapper
-      // delegates to the same handler-table as 'on' for the test mock.
+      // Why: production uses ws.once('close'); the mock delegates 'once' to the same handler table as 'on'.
       return Object.assign(stub, { once: stub.on })
     }),
     end: vi.fn()
@@ -141,17 +135,8 @@ function decodePowerShellCommand(command: string): string | null {
   return match ? Buffer.from(match[1], 'base64').toString('utf16le') : null
 }
 
-// Exec call order under our mocks (deploy happy path):
-//   1: uname              2: $HOME            3: mkdir remoteDir (uploadRelay)
-//   4: chmod +x node      5: npm install      6: chmod prebuilds
-//   7: probe (cd && node -e require)
-//   [8: cat stderr — only when probe stdout is MISSING (graceful path)]
-//   8 or 9: rm probe-stderr (best-effort cleanup; runs whenever probe resolved)
-//   [next: npm rebuild → chmod → second probe when the first probe is MISSING]
-//   next: socket DEAD     next: socket READY
-//
-// When the probe rejects (SSH channel close or cd-failure when the install
-// dir vanished), the catch path skips both stderr-capture and the rm.
+// Happy-path exec order: uname, $HOME, mkdir, chmod node, npm install, chmod prebuilds, probe, [cat stderr + rm if MISSING], [rebuild → chmod → re-probe if MISSING], DEAD, READY.
+// When the probe rejects (SSH channel close or vanished install dir), the catch skips both stderr-capture and the rm.
 function makeExecResponses(opts: {
   npmInstall: 'ok' | { reject: string }
   // 'ok'      : probe resolves with the sentinel; rm runs once
@@ -159,19 +144,14 @@ function makeExecResponses(opts: {
   // 'dir-gone': probe rejects (cd-failure), exec rejects directly
   // { reject }: probe rejects with custom error (e.g. SSH channel)
   probe: 'ok' | 'missing' | 'dir-gone' | { reject: string }
-  // Override probe stdout for shell-noise pressure tests. If set, replaces
-  // the load-test stdout entirely (useful for testing pollution prefixes).
+  // Override probe stdout entirely for shell-noise/pollution-prefix pressure tests.
   probeStdoutOverride?: string
-  // Result after the automatic rebuild. Defaults to missing so legacy tests
-  // continue to exercise the final degraded-mode warning.
+  // Result after the automatic rebuild; defaults to missing so legacy tests still exercise the degraded-mode warning.
   repairProbe?: 'ok' | 'missing'
-  // Raw stdout for the build-toolchain probe that runs in installNativeDeps'
-  // catch when `npm install` rejects on Linux. Defaults to a fully-present
-  // toolchain so the original npm error propagates unchanged.
+  // Raw stdout for the toolchain probe in installNativeDeps' catch; defaults to a full toolchain so the original npm error propagates unchanged.
   toolchainProbe?: string
 }): ExecResponse[] {
-  // npm install failure aborts the deploy after the catch probes the remote's
-  // build toolchain — no chmod/probe/launch slots are reached.
+  // npm install failure aborts after the catch probes the toolchain; no chmod/probe/launch slots are reached.
   if (opts.npmInstall !== 'ok') {
     return [
       '__ORCA_REMOTE_PLATFORM__ Linux x86_64',
@@ -234,10 +214,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
 
   beforeEach(() => {
     vi.clearAllMocks()
-    // Tests that throw mid-deploy leave unconsumed `mockResolvedValueOnce`
-    // entries queued. Without resetting, the next test's first await consumes
-    // a leaked response. clearAllMocks doesn't drop the queue (it only clears
-    // .mock.calls), so we explicitly mockReset.
+    // mockReset because clearAllMocks keeps queued mockResolvedValueOnce entries, so a leaked response would bleed into the next test.
     vi.mocked(execCommand).mockReset()
     vi.mocked(uploadDirectory).mockResolvedValue(undefined)
     sftpCapture.paths.length = 0
@@ -247,9 +224,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
     for (const k of Object.keys(sftpCapture.execCallCountAtWrite)) {
       delete sftpCapture.execCallCountAtWrite[k]
     }
-    // Re-prime: factory mockReturnValue / mockResolvedValue survive
-    // clearAllMocks, so this is just defense-in-depth in case a test does its
-    // own resetAllMocks.
+    // Re-prime as defense-in-depth: factory mocks survive clearAllMocks but a test's own resetAllMocks would drop them.
     vi.mocked(parseUnameToRelayPlatform).mockReturnValue('linux-x64')
     vi.mocked(isRelayAlreadyInstalled).mockResolvedValue(false)
     warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
@@ -285,8 +260,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
     expect(parsed.name).toBe('orca-relay')
     expect(parsed.version).toBe('1.0.0')
     expect(parsed.private).toBe(true)
-    // Why: pin commonjs so a future Node default flip doesn't silently
-    // break `require('node-pty')`.
+    // Why: pin commonjs so a future Node default flip can't break require('node-pty').
     expect(parsed.type).toBe('commonjs')
     expect(parsed.dependencies).toEqual({ '@parcel/watcher': '2.5.6', 'node-pty': '1.1.0' })
     expect(parsed.allowScripts).toEqual({
@@ -300,10 +274,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
     )
     expect(npmInstallIdx).toBeGreaterThanOrEqual(0)
     expect(execCalls[npmInstallIdx]).toContain('--ignore-scripts=false')
-    // Pin actual ordering: number of execCommand calls observed at the moment
-    // ws.end() ran for package.json must be < the index of `npm install`.
-    // Catches a future refactor that fires SFTP-write and npm install via
-    // Promise.all (where the final-state assertions above would still pass).
+    // Pin write-before-install ordering to catch a Promise.all refactor where the final-state assertions above still pass.
     const writeObservedAt = sftpCapture.execCallCountAtWrite[pkgPath as string]
     expect(writeObservedAt).toBeLessThanOrEqual(npmInstallIdx)
   })
@@ -319,8 +290,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
 
     await expect(deployAndLaunchRelay(conn)).rejects.toThrow(/npm ERR/)
 
-    // The crucial regression: `.install-complete` must NOT have been written.
-    // Previously the catch swallowed the throw and finalizeInstall ran anyway.
+    // Regression: previously the catch swallowed the throw and finalizeInstall ran anyway.
     expect(vi.mocked(finalizeInstall)).not.toHaveBeenCalled()
 
     const warnMessages = warnSpy.mock.calls.map((args) => String(args[0] ?? ''))
@@ -333,8 +303,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
       makeExecResponses({
         npmInstall: { reject: 'gyp ERR! stack Error: not found: make' },
         probe: 'ok',
-        // No HAVE lines → make/g++ absent; apk present → tailored hint must
-        // come from the remote probe rather than a hardcoded apt fallback.
+        // No HAVE lines + apk present: the tailored hint must come from the remote probe, not a hardcoded apt fallback.
         toolchainProbe: 'PKG apk'
       })
     )
@@ -362,14 +331,12 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
       makeExecResponses({
         npmInstall: { reject: 'npm ERR! network ETIMEDOUT' },
         probe: 'ok',
-        // Even if the host also lacks build tools, a network error should stay
-        // a network error instead of being relabeled as an install-tools fix.
+        // A network error must stay a network error even if the host also lacks build tools.
         toolchainProbe: 'PKG apt-get'
       })
     )
 
-    // The npm output is something else (network, registry), so surface the
-    // real error rather than a misleading "install build tools".
+    // Non-toolchain npm error (network/registry): surface the real error, not a misleading "install build tools".
     const error = await deployAndLaunchRelay(conn).catch((e: Error) => e)
     expect((error as Error).message).toContain('npm ERR! network ETIMEDOUT')
     expect((error as Error).message).not.toContain('build tools')
@@ -405,11 +372,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
 
     await deployAndLaunchRelay(conn)
 
-    // Probe failure is non-fatal by design (see docs/ssh-relay-versioned-
-    // install-dirs.md): relay still serves fs/git/preflight, only pty.spawn
-    // fails at runtime. Throwing here would loop reconnects forever on
-    // hosts where node-pty truly cannot build (Alpine without compiler,
-    // glibc too old).
+    // Probe failure is non-fatal by design (docs/ssh-relay-versioned-install-dirs.md): throwing would loop reconnects forever where node-pty can't build.
     const warnMessages = warnSpy.mock.calls.map((args) => String(args[0] ?? ''))
     expect(warnMessages.some((m) => m.includes('[ssh-relay][NPTY-MISSING]'))).toBe(true)
 
@@ -439,9 +402,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
   })
 
   it('propagates an SSH-channel failure from the post-rebuild re-probe', async () => {
-    // Why: the rebuild itself degrades gracefully, but the verification probe
-    // after it must still surface transport death — conflating a dead channel
-    // with "native deps missing" would finalize a half-repaired install.
+    // Why: rebuild degrades gracefully, but the post-rebuild probe must surface transport death, else a dead channel finalizes a half-repaired install.
     const conn = makeMockConnection(sftpCapture)
     feed([
       '__ORCA_REMOTE_PLATFORM__ Linux x86_64', // uname
@@ -517,23 +478,18 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
 
     await expect(deployAndLaunchRelay(conn)).rejects.toThrow(/SSH channel/)
 
-    // Pin that the rejection actually came from the PROBE call (not some
-    // earlier/later exec). Drift in slot ordering would otherwise let this
-    // test pass while exercising a different failure path.
+    // Pin the rejection to the PROBE call so slot-ordering drift can't pass this test via a different failure path.
     const execCalls = vi.mocked(execCommand).mock.calls.map(([, c]) => c)
     const probeCallIdx = execCalls.findIndex((c) => c.includes('require("node-pty")'))
     const npmInstallIdx = execCalls.findIndex(
       (c) => c.includes('npm install') && c.includes('node-pty') && c.includes('@parcel/watcher')
     )
     expect(probeCallIdx, 'probe must have been invoked').toBeGreaterThanOrEqual(0)
-    // Probe must come strictly AFTER `npm install` — otherwise we'd be
-    // probing into an empty install dir and this whole failure mode
-    // wouldn't represent the real-world race.
+    // Probe must come strictly after npm install, else it probes an empty dir and doesn't represent the real-world race.
     expect(probeCallIdx).toBeGreaterThan(npmInstallIdx)
 
     const warnMessages = warnSpy.mock.calls.map((args) => String(args[0] ?? ''))
-    // Channel failure must NOT be conflated with "node-pty missing" or with
-    // "npm install failed".
+    // Channel failure must not be conflated with "node-pty missing" or "npm install failed".
     expect(warnMessages.some((m) => m.includes('[ssh-relay][NPTY-MISSING]'))).toBe(false)
     expect(warnMessages.some((m) => m.includes('[ssh-relay][NATIVE-DEPS-INSTALL-FAIL]'))).toBe(
       false
@@ -548,17 +504,10 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
     const conn = makeMockConnection(sftpCapture)
     feed(makeExecResponses({ npmInstall: 'ok', probe: 'dir-gone' }))
 
-    // The probe shape `cd ${dir} && (node -e ... || echo MISSING)` short-
-    // circuits on cd-failure (`&&`), so the whole exec rejects rather than
-    // resolving with the MISSING sentinel. Conflating "dir vanished" with
-    // "node-pty missing" would mark the version installed and strand the
-    // user in degraded mode forever.
+    // Why: cd-failure short-circuits the probe's && so it rejects instead of resolving MISSING; conflating "dir gone" with "node-pty missing" strands the user in degraded mode.
     await expect(deployAndLaunchRelay(conn)).rejects.toThrow(/cd:/)
 
-    // Pin that the rejection came from the probe slot specifically, not
-    // some earlier exec — otherwise a future refactor could move probe
-    // before npm install and this test would still pass for the wrong
-    // reason.
+    // Pin the rejection to the probe slot so a refactor moving probe before npm install can't pass this test for the wrong reason.
     const execCalls = vi.mocked(execCommand).mock.calls.map(([, c]) => c)
     const probeIdx = execCalls.findIndex((c) => c.includes('require("node-pty")'))
     const npmInstallIdx = execCalls.findIndex(
@@ -584,16 +533,11 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
       .mock.calls.map(([, c]) => c)
       .filter((c) => c.includes(`require("node-pty")`))
 
-    // Why: the probe shape must invoke the deployed node binary against
-    // require('node-pty'). A weaker probe (test -d) could pass even when
-    // the native binding load is broken.
+    // Why: probe must require('node-pty') via the node binary; a weaker test -d passes even when the native binding load is broken.
     expect(probeCmds.length).toBeGreaterThan(0)
     expect(probeCmds[0]).toMatch(/node['"]?\s+-e/)
 
-    // Pin the full installNativeDeps exec sequence: npm install → chmod
-    // prebuilds → probe. A refactor that moves chmod-prebuilds after the
-    // probe would silently break spawn-helper bits; one that probes before
-    // npm install would test an empty dir.
+    // Pin order npm install → chmod prebuilds → probe: chmod-after-probe breaks spawn-helper bits; probe-before-install tests an empty dir.
     const all = vi.mocked(execCommand).mock.calls.map(([, c]) => c)
     const npmIdx = all.findIndex(
       (c) => c.includes('npm install') && c.includes('node-pty') && c.includes('@parcel/watcher')
@@ -613,10 +557,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
 
   it('matches the sentinel even with bashrc/MOTD noise prefixed to probe stdout', async () => {
     const conn = makeMockConnection(sftpCapture)
-    // Some remotes have customized .bashrc that prints to stdout on every
-    // non-interactive shell exec (corporate MOTD, NVM/conda init banners).
-    // Production uses .includes(PROBE_OK) with stderr redirected to a file,
-    // so noise on stdout BEFORE the sentinel must still resolve to OK.
+    // Why: noisy .bashrc/MOTD can prefix probe stdout; production uses .includes(PROBE_OK) so pre-sentinel noise still resolves OK.
     feed(
       makeExecResponses({
         npmInstall: 'ok',
@@ -644,8 +585,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
 
     await deployAndLaunchRelay(conn)
 
-    // Absence of PROBE_OK is what triggers the warn, regardless of what
-    // appears around it. finalize still runs (degraded-mode by design).
+    // Absence of PROBE_OK triggers the warn regardless of surrounding noise; finalize still runs by design.
     const warnMessages = warnSpy.mock.calls.map((args) => String(args[0] ?? ''))
     expect(warnMessages.some((m) => m.includes('[ssh-relay][NPTY-MISSING]'))).toBe(true)
     expect(vi.mocked(finalizeInstall)).toHaveBeenCalledTimes(1)
@@ -708,8 +648,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
   })
 
   it('includes the platform tuple in NPTY-MISSING and native install failure logs', async () => {
-    // Platform tuple lets bug reports be triaged for prebuild availability
-    // without asking the user to dig out their arch.
+    // Platform tuple lets bug reports be triaged for prebuild availability without asking the user for their arch.
     const conn = makeMockConnection(sftpCapture)
     feed(makeExecResponses({ npmInstall: 'ok', probe: 'missing' }))
     await deployAndLaunchRelay(conn)
@@ -783,10 +722,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
   })
 
   it('launches an already-installed relay in degraded mode when repair throws', async () => {
-    // Why: a repair failure on a completed dir (e.g. offline/proxy-locked npm)
-    // must not block the connection — the relay still serves fs/git/preflight.
-    // Pre-fix this rethrew and aborted the whole deploy. The next reconnect
-    // retries, so a transient failure self-heals.
+    // Why: a repair failure on a completed dir must not block the connection — relay still serves fs/git/preflight; next reconnect retries.
     vi.mocked(isRelayAlreadyInstalled).mockResolvedValue(true)
     const conn = makeMockConnection(sftpCapture)
     feed([
@@ -849,8 +785,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
           installSignal?.addEventListener(
             'abort',
             () => {
-              // Mirrors execCommand's bounded close grace when ssh2 never
-              // confirms that the remote npm process stopped.
+              // Mirrors execCommand's bounded close grace when ssh2 never confirms npm stopped.
               setTimeout(
                 () =>
                   reject(
@@ -960,8 +895,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
   })
 
   it.each(['busy', 'error'] as const)('launches degraded when lock is %s', async (lockResult) => {
-    // Why: lock contention/wedge must not block a completed relay from launching
-    // in degraded mode — repair is best-effort and we hold no lock to release.
+    // Why: lock contention/wedge must not block a completed relay from launching in degraded mode.
     vi.mocked(isRelayAlreadyInstalled).mockResolvedValue(true)
     vi.mocked(tryAcquireRelayRepairLock).mockResolvedValueOnce(lockResult)
     const conn = makeMockConnection(sftpCapture)
diff --git a/src/main/ssh/ssh-relay-session.ts b/src/main/ssh/ssh-relay-session.ts
index b9c41c84c1d..0428a4d3086 100644
--- a/src/main/ssh/ssh-relay-session.ts
+++ b/src/main/ssh/ssh-relay-session.ts
@@ -1,12 +1,5 @@
 /* oxlint-disable max-lines */
-// Why: consolidates all relay lifecycle state (multiplexer, providers, abort
-// controller, initialization flag) into a single class per SSH target.
-// Previously this state was scattered across 5 module-level Maps/Sets in
-// ssh.ts and ssh-relay-helpers.ts, with 3 separate code paths for initial
-// connect, network-blip reconnect, and cleanup — each partially duplicating
-// provider registration/teardown logic. This class is the single authority
-// for relay session state, eliminating the class of bugs where one path
-// forgets a step that another path handles.
+// Why: single authority for all relay lifecycle state per SSH target (previously scattered across module Maps/Sets with duplicated paths).
 
 import type { BrowserWindow } from 'electron'
 import { deployAndLaunchRelay } from './ssh-relay-deploy'
@@ -132,8 +125,7 @@ async function resolveRemoteGrokHome(
 ): Promise<string> {
   const fallback = defaultRemoteGrokHome(remoteHome)
   try {
-    // Why: remote PTYs start login shells, so probe the same profile-derived
-    // environment instead of the relay service or local Electron environment.
+    // Why: remote PTYs start login shells, so probe that profile-derived env, not the relay service or local Electron env.
     const shellOutput = await execCommand(connection, "printenv SHELL || printf '/bin/sh\\n'", {
       timeoutMs: REMOTE_GROK_HOME_PROBE_TIMEOUT_MS
     })
@@ -141,8 +133,7 @@ async function resolveRemoteGrokHome(
     if (!shell?.startsWith('/') || hasControlCharacter(shell)) {
       return fallback
     }
-    // Why: this runs inside the user's actual login shell, which may be fish or
-    // tcsh. External commands avoid shell-specific variable/conditional syntax.
+    // Why: runs in the user's login shell (maybe fish/tcsh), so use external commands to avoid shell-specific syntax.
     const probe = `printenv GROK_HOME | head -c ${REMOTE_GROK_HOME_MAX_LENGTH + 1}`
     const output = await execCommand(connection, loginShellCommand(shell, probe), {
       wrapCommand: false,
@@ -204,20 +195,11 @@ export class SshRelaySession {
   private mux: SshChannelMultiplexer | null = null
   private abortController: AbortController | null = null
   private muxDisposeCleanup: (() => void) | null = null
-  // Why: store the notification-handler disposer so teardownProviders can
-  // release it on reconnect/shutdown. Symmetric with muxDisposeCleanup; while
-  // the old mux's handler array is GC'd along with the mux today, holding the
-  // disposer is cheap insurance against future code that retains the old mux.
+  // Why: hold the notification-handler disposer so teardownProviders can release it on reconnect/shutdown (symmetric with muxDisposeCleanup).
   private muxNotificationCleanup: (() => void) | null = null
-  // Why: when the relay exec channel closes but the SSH connection stays
-  // up, the onStateChange reconnect path never fires. This callback lets
-  // ssh.ts wire up relay-level reconnect from outside the session.
+  // Why: onStateChange never fires when the relay channel closes but SSH stays up; this callback lets ssh.ts drive relay-level reconnect.
   private _onRelayLost: ((targetId: string) => void) | null = null
-  // Why: a wire-handshake mismatch is terminal — the daemon and client are at
-  // different versions, no amount of backoff retry will reconcile them. This
-  // separate callback lets ssh.ts surface the failure to the user and skip
-  // the relay-lost backoff loop entirely. Distinct from _onRelayLost because
-  // _onRelayLost expects a recoverable transport drop.
+  // Why: version mismatch is terminal, so it needs a separate callback from _onRelayLost (which expects a recoverable transport drop).
   private _onTerminalRelayError:
     | ((targetId: string, err: RelayVersionMismatchError) => void)
     | null = null
@@ -271,11 +253,7 @@ export class SshRelaySession {
     return this._state
   }
 
-  // Why: TypeScript narrows _state after control-flow checks and then
-  // rejects comparisons like `this._state === 'disposed'` inside async
-  // methods where it "knows" the state was e.g. 'deploying'. But dispose()
-  // can mutate _state from another call stack between await points. This
-  // helper defeats narrowing so the disposed checks compile correctly.
+  // Why: dispose() can mutate _state across await points, so defeat TS's control-flow narrowing that would otherwise reject the 'disposed' check.
   private isDisposed(): boolean {
     return (this._state as RelaySessionState) === 'disposed'
   }
@@ -320,9 +298,7 @@ export class SshRelaySession {
     mux.notify(SSH_RELAY_CONFIGURE_GRACE_TIME_METHOD, { graceTimeSeconds: 0 })
   }
 
-  // Why: single entry point for relay setup — used by both initial connect
-  // and app-restart reconnect. Having one path eliminates the risk of
-  // forgetting a registration step.
+  // Why: single entry point for relay setup (initial connect + app-restart reconnect) so no path forgets a registration step.
   async establish(conn: SshConnection, graceTimeSeconds?: number): Promise<void> {
     if (this._state !== 'idle') {
       throw new Error(`Cannot establish relay session in state: ${this._state}`)
@@ -347,10 +323,7 @@ export class SshRelaySession {
             }
           : null
 
-      // Why: dispose() can fire during the await above (e.g. user clicks
-      // disconnect while relay is deploying). If so, the session is already
-      // cleaned up — creating a mux and registering providers would leak
-      // resources with no owner to dispose them.
+      // Why: dispose() can fire during the await above; if it did, creating a mux/providers now would leak with no owner to dispose them.
       if (this.isDisposed()) {
         const orphanMux = new SshChannelMultiplexer(transport)
         orphanMux.dispose()
@@ -361,12 +334,7 @@ export class SshRelaySession {
       this.mux = mux
       const ownsAttempt = (): boolean => this.mux === mux && !this.isDisposed()
 
-      // Why: verify the relay is actually responsive before registering
-      // providers. In --connect mode the bridge may have already closed
-      // (e.g. the grace-period relay exited because it had no PTYs), and
-      // registerRelayRoots would silently swallow all mux errors, leaving
-      // the session in 'ready' state with a dead mux. A round-trip request
-      // here fails fast so doConnect() can report the real error.
+      // Why: round-trip the relay before registering providers so a closed --connect bridge fails fast instead of leaving a 'ready' session on a dead mux.
       await mux.request('session.resolveHome', { path: '~' })
 
       const registered = await this.registerProviders(mux, ownsAttempt)
@@ -377,11 +345,7 @@ export class SshRelaySession {
         throw new Error('Session disposed during establish')
       }
 
-      // Why: the mux's transport can close during registerProviders (e.g.
-      // the --connect bridge exits). registerRelayRoots swallows mux errors
-      // (notifications no-op when disposed, git.listWorktrees requests are
-      // try/caught), so establish would otherwise reach 'ready' with a dead
-      // mux. Checking isDisposed catches this silent failure.
+      // Why: registerProviders swallows mux errors, so an isDisposed check catches a transport that closed mid-registration before we reach 'ready'.
       if (mux.isDisposed()) {
         throw new Error('Relay connection lost during provider registration')
       }
@@ -391,8 +355,7 @@ export class SshRelaySession {
         throw new Error('Session disposed during establish')
       }
 
-      // Why: explicit disconnect keeps PTY ownership so a later manual connect
-      // must reattach those remote PTYs through the fresh relay connection.
+      // Why: explicit disconnect keeps PTY ownership, so a later manual connect must reattach those remote PTYs.
       await this.reattachKnownPtys(ownsAttempt)
 
       if (!ownsAttempt()) {
@@ -405,22 +368,12 @@ export class SshRelaySession {
       this.startPortScanning()
       this._onReady?.(this.targetId)
     } catch (err) {
-      // Why: if deployAndLaunchRelay succeeded but registerProviders threw
-      // partway through, the mux is live and some providers may be partially
-      // registered. teardownProviders cleans up everything so a subsequent
-      // establish() call starts from a clean slate.
+      // Why: registerProviders can throw with a live mux and partial registration — tear everything down so a retry starts clean.
       if (!this.isDisposed()) {
         this.teardownProviders('connection_lost')
         this._state = 'idle'
       }
-      // Why: a wire-handshake mismatch on the FIRST connect is also terminal
-      // — the deployed relay binary on disk does not match a still-running
-      // daemon (typically because a legacy daemon from before the
-      // versioned-dir change is still alive). Notify the terminal-error
-      // callback so ssh.ts surfaces an actionable message and the caller's
-      // catch path doesn't conflate this with a transient deploy failure.
-      // We still rethrow so doConnect's existing failure path runs (clean up
-      // the SSH connection); ssh.ts's handler is idempotent.
+      // Why: a version mismatch on first connect is terminal (deployed binary vs. a still-running legacy daemon); notify the callback but still rethrow.
       if (isRelayVersionMismatchError(err)) {
         console.warn(
           `[ssh-relay-session] Terminal relay version mismatch on initial connect for ${this.targetId}: ${err.message}`
@@ -431,14 +384,9 @@ export class SshRelaySession {
     }
   }
 
-  // Why: network-blip reconnect path. Tears down the old provider stack,
-  // deploys a fresh relay, and re-attaches any PTYs that survived the
-  // relay's grace window. Guarded by an AbortController so overlapping
-  // reconnect attempts (fast connection flaps) cancel the stale one.
+  // Why: network-blip reconnect; AbortController-guarded so overlapping attempts from fast flaps cancel the stale one.
   async reconnect(conn: SshConnection, graceTimeSeconds?: number): Promise<void> {
-    // Why: only allow reconnect from 'ready' or 'reconnecting'. Calling
-    // reconnect from 'deploying' would tear down a mux that establish() is
-    // concurrently using. 'idle' means no session was established yet.
+    // Why: reconnect only from 'ready'/'reconnecting' — from 'deploying' it would tear down a mux establish() is still using; 'idle' has no session yet.
     if (this._state !== 'ready' && this._state !== 'reconnecting') {
       return
     }
@@ -451,8 +399,7 @@ export class SshRelaySession {
     this._state = 'reconnecting'
     this.currentConnection = conn
 
-    // Why: stop scanning before teardownProviders so the polling timer doesn't
-    // fire against a disposed multiplexer.
+    // Why: stop scanning before teardownProviders so the poll timer can't fire against a disposed multiplexer.
     this.stopPortScanning()
     await this.portForwardManager.removeAllForwards(this.targetId)
     this.broadcastEmptyLists()
@@ -476,9 +423,7 @@ export class SshRelaySession {
           : null
 
       if (abortController.signal.aborted || this.isDisposed()) {
-        // Why: the relay is already running on the remote. Creating a temporary
-        // multiplexer and immediately disposing it sends a clean shutdown to the
-        // relay process so it doesn't linger until its grace timer expires.
+        // Why: relay is already running remotely — a throwaway mux we immediately dispose sends a clean shutdown so it doesn't linger until grace expires.
         const orphanMux = new SshChannelMultiplexer(transport)
         orphanMux.dispose()
         return
@@ -492,9 +437,7 @@ export class SshRelaySession {
         !abortController.signal.aborted &&
         !this.isDisposed()
 
-      // Why: same health check as establish() — verify the relay is
-      // responsive before registering providers so a dead --connect bridge
-      // fails fast instead of silently producing a dead mux.
+      // Why: same health check as establish() — round-trip the relay before registering providers so a dead --connect bridge fails fast.
       await mux.request('session.resolveHome', { path: '~' })
       if (!ownsAttempt()) {
         if (!mux.isDisposed()) {
@@ -515,10 +458,7 @@ export class SshRelaySession {
         throw new Error('Relay connection lost during provider registration')
       }
 
-      // Why: dispose() can fire during registerProviders or the attach loop
-      // below. If it did, providers and mux were already cleaned up by
-      // dispose() — but this.mux was reassigned above, so the new mux
-      // would leak. Clean it up and bail.
+      // Why: dispose() during registration/attach already cleaned up, but this.mux was reassigned above — clean up the new mux so it doesn't leak.
       if (!ownsAttempt()) {
         if (this.mux === mux) {
           this.teardownProviders('shutdown')
@@ -540,16 +480,11 @@ export class SshRelaySession {
       this.startPortScanning()
       this._onReady?.(this.targetId)
     } catch (err) {
-      // Why: clean up the mux if it was created but registration failed
-      // partway through. Without this, the mux's keepalive/timeout timers
-      // continue running on a half-initialized session.
+      // Why: tear down a partially-registered mux so its keepalive/timeout timers don't keep running on a half-initialized session.
       if (this.abortController === abortController && !this.isDisposed()) {
         this.teardownProviders('connection_lost')
       }
-      // Why: a version-mismatch is terminal. Fire the typed callback so
-      // ssh.ts can surface a "please reconnect manually" notice and skip the
-      // relay-lost backoff loop entirely. We do NOT keep state at
-      // 'reconnecting' — there's no transient drop to recover from.
+      // Why: version-mismatch is terminal — fire the typed callback and drop out of 'reconnecting' since backoff retry can't reconcile it.
       if (isRelayVersionMismatchError(err)) {
         console.warn(
           `[ssh-relay-session] Terminal relay version mismatch for ${this.targetId}: ${err.message}`
@@ -560,17 +495,12 @@ export class SshRelaySession {
         this._onTerminalRelayError?.(this.targetId, err)
         return
       }
-      // Why: stay in 'reconnecting' rather than reverting to 'ready', because
-      // the provider stack is already torn down. The SSH connection manager
-      // will fire another onStateChange when it reconnects again.
+      // Why: stay in 'reconnecting' (not 'ready') since the provider stack is torn down; the SSH manager will fire another onStateChange to retry.
       console.warn(
         `[ssh-relay-session] Failed to re-establish relay for ${this.targetId}: ${err instanceof Error ? err.message : String(err)}`
       )
       if (this.abortController === abortController && !this.isDisposed()) {
-        // Why: non-not-found PTY attach failures are usually transient mux or
-        // relay transport failures. Treat them like relay loss so ssh.ts's
-        // bounded backoff retries instead of stranding the session forever in
-        // reconnecting.
+        // Why: treat non-not-found attach failures as relay loss so ssh.ts's bounded backoff retries instead of stranding the session in 'reconnecting'.
         this._onRelayLost?.(this.targetId)
       }
     } finally {
@@ -586,8 +516,7 @@ export class SshRelaySession {
     }
     this.abortController?.abort()
     this.stopPortScanning()
-    // Why: fire-and-forget — nothing rebinds after dispose, so we don't
-    // need to wait for the OS to release ports.
+    // Why: fire-and-forget — nothing rebinds after dispose, so no need to await port release.
     void this.portForwardManager.removeAllForwards(this.targetId)
     this.broadcastEmptyLists()
     this.teardownProviders('shutdown')
@@ -603,9 +532,7 @@ export class SshRelaySession {
     this.abortController?.abort()
     this.stopPortScanning()
     this.broadcastEmptyLists()
-    // Why: app/window disconnect is non-destructive for remote PTYs. The relay
-    // owns the grace timer, so Orca must unregister local providers without
-    // clearing PTY ownership needed for reattach.
+    // Why: window disconnect is non-destructive — unregister local providers but keep PTY ownership so reattach works (relay owns the grace timer).
     this.teardownProviders('connection_lost')
     this.store.markSshRemotePtyLeases(this.targetId, 'detached')
     this.currentConnection = null
@@ -614,11 +541,7 @@ export class SshRelaySession {
 
   // ── Private ───────────────────────────────────────────────────────
 
-  // Why: when the relay exec channel closes (e.g. --connect bridge exits,
-  // relay process crashes) but the SSH connection stays up, there is no
-  // automatic recovery — onStateChange only fires on SSH-level reconnects.
-  // This watcher detects relay-level channel loss and fires onRelayLost
-  // so ssh.ts can trigger session.reconnect() with the still-live SSH conn.
+  // Why: onStateChange only fires on SSH-level reconnects, so watch for relay-channel loss while SSH stays up and fire onRelayLost.
   private watchMuxForRelayLoss(mux: SshChannelMultiplexer): void {
     this.muxDisposeCleanup?.()
     this.muxDisposeCleanup = mux.onDispose((reason) => {
@@ -631,8 +554,7 @@ export class SshRelaySession {
     })
   }
 
-  // Why: shared by establish() and reconnect() — the exact same provider
-  // registration sequence, eliminating the duplication that caused bugs.
+  // Why: shared by establish() and reconnect() so both use the exact same registration sequence.
   private async registerProviders(
     mux: SshChannelMultiplexer,
     shouldContinue?: () => boolean
@@ -655,10 +577,7 @@ export class SshRelaySession {
     try {
       await this.installRemoteOrcaCliLauncher()
     } catch (error) {
-      // Why: the remote `orca` CLI launcher is a convenience bridge. On session-
-      // limited remotes (MaxSessions=1) the relay bridge holds the only slot,
-      // so this raw-connection install can fail — that must not fail the
-      // whole connection, matching the managed-hook install above.
+      // Why: on MaxSessions=1 remotes the relay holds the only slot, so this raw-connection install can fail — don't fail the whole connection.
       console.warn(
         `[ssh-relay-session] remote orca CLI launcher install failed for ${this.targetId}: ${
           error instanceof Error ? error.message : String(error)
@@ -679,8 +598,7 @@ export class SshRelaySession {
       connection.usesSystemSshTransport?.() === true
         ? undefined
         : (options?: { signal?: AbortSignal }) => this.requireReadyConnection().sftp(options)
-    // Why: getHostPlatform() falls back to this.hostPlatform when the full
-    // remote CLI bridge env is incomplete, so path rules still match the host.
+    // Why: getHostPlatform() falls back to this.hostPlatform when bridge env is incomplete, so path rules still match the host.
     const hostPlatform = this.getHostPlatform() ?? undefined
     const fsProvider = new SshFilesystemProvider(
       this.targetId,
@@ -728,11 +646,7 @@ export class SshRelaySession {
     })
   }
 
-  // Why: the relay can inject ORCA_AGENT_HOOK_* env into SSH PTYs, but
-  // hook-script agents (Claude/Codex/Gemini/etc.) still need their config
-  // files on the remote host to call Orca's managed script. Install those
-  // configs before registering the PTY provider so newly spawned agent panes
-  // report status from their first prompt.
+  // Why: hook-script agents need remote config files (relay env alone isn't enough); install before the PTY provider so first prompts report status.
   private async installManagedHooksOnRemote(mux: SshChannelMultiplexer): Promise<void> {
     if (!isRemoteAgentHooksEnabled() || !this.areAgentStatusHooksEnabled()) {
       return
@@ -741,8 +655,7 @@ export class SshRelaySession {
       this.remoteCliBridgeEnv?.hostPlatform &&
       isWindowsRemoteHost(this.remoteCliBridgeEnv.hostPlatform)
     ) {
-      // Why: managed hook installers currently emit POSIX hook scripts and paths.
-      // Windows remotes still get relay-injected env plus plugin overlays.
+      // Why: managed hook installers emit POSIX-only scripts/paths; Windows remotes rely on relay-injected env + plugin overlays instead.
       return
     }
 
@@ -848,17 +761,7 @@ export class SshRelaySession {
     })
   }
 
-  // Why: ship the OpenCode plugin / Pi extension source bodies to the relay
-  // so it can materialize overlay dirs and inject OPENCODE_CONFIG_DIR
-  // / PI_CODING_AGENT_DIR into spawn env. The strings change as we add agent
-  // events (recent additions: cursor, pi); pinning them to the relay binary
-  // would force a relay redeploy on every Orca update. See
-  // docs/design/agent-status-over-ssh.md §4 + §8 (commit #7).
-  //
-  // Best-effort: a -32601 from an older relay (no handler installed) is
-  // swallowed; the user just doesn't get OpenCode/Pi status reporting until
-  // they upgrade. Hook-script-based agents use a separate explicit remote
-  // installer flow because that mutates user-owned agent config files.
+  // Why: ship plugin/extension source from Orca so agent-event changes don't force a relay redeploy (agent-status-over-ssh.md §4/§8). Best-effort.
   private async installPluginsOnRelay(mux: SshChannelMultiplexer): Promise<void> {
     if (!isRemoteAgentHooksEnabled() || !this.areAgentStatusHooksEnabled()) {
       return
@@ -870,11 +773,7 @@ export class SshRelaySession {
         ompExtensionSource: getPiAgentStatusExtensionSource('omp')
       })
     } catch (err) {
-      // Why: -32601 = older relay without the handler (treat as soft skip).
-      // CONNECTION_LOST / DISPOSED come from the multiplexer when it tears
-      // down mid-flight (routine on session shutdown / reconnect race) — not
-      // a real failure to surface; suppress to avoid log spam on every clean
-      // disconnect.
+      // Why: -32601 = older relay without the handler; CONNECTION_LOST/DISPOSED = routine mid-flight teardown — swallow both.
       const code = (err as { code?: unknown })?.code
       if (code === -32601 || code === 'CONNECTION_LOST' || code === 'DISPOSED') {
         return
@@ -901,25 +800,12 @@ export class SshRelaySession {
     })
   }
 
-  // Why: route the relay's `agent.hook` JSON-RPC notification into Orca's
-  // shared `agentHookServer` via `ingestRemote`. The wire envelope carries
-  // `connectionId: null` (the relay does not know Orca's local handle); we
-  // stamp the real value here from `this.targetId` so the renderer can drop
-  // in-flight events for connections that have torn down. After wiring is
-  // in place we kick off a request-driven replay so any cached payload from
-  // before the channel was up survives the reconnect — see §5 Path 3.
-  //
-  // The Orca-side mux's `notificationHandlers` is a flat array — each
-  // handler must filter by method name itself.
+  // Why: relay sends connectionId:null, so stamp this.targetId here so the renderer can drop events from torn-down connections.
   private wireUpAgentHookEvents(mux: SshChannelMultiplexer): void {
     if (!isRemoteAgentHooksEnabled()) {
       return
     }
-    // Why: capture the disposer so teardownProviders can release the
-    // notification handler symmetrically with muxDisposeCleanup. Even though
-    // the disposed mux's handler array is GC'd along with it today, retaining
-    // the disposer makes "registerProviders called twice on the same mux"
-    // safe by future-proofing against duplicate handler registration.
+    // Why: capture the disposer so teardownProviders can release this handler and re-wiring can't double-register it.
     this.muxNotificationCleanup?.()
     this.muxNotificationCleanup = mux.onNotification((method, params) => {
       if (method !== AGENT_HOOK_NOTIFICATION_METHOD) {
@@ -946,11 +832,7 @@ export class SshRelaySession {
       if (typeof envelope.paneKey !== 'string') {
         return
       }
-      // Why: forward env/version verbatim so Orca's warn-once cross-build /
-      // dev-vs-prod diagnostics fire on remote events the same as on local
-      // ones — see docs/design/agent-status-over-ssh.md §3 ("Replay /
-      // version mismatch") and the relay's wire envelope at
-      // src/shared/agent-hook-relay.ts.
+      // Why: forward env/version verbatim so cross-build warn-once diagnostics fire on remote events too (agent-status-over-ssh.md §3).
       agentHookServer.ingestRemote(
         {
           paneKey: envelope.paneKey,
@@ -979,12 +861,7 @@ export class SshRelaySession {
       )
     })
 
-    // Why: ask the relay to replay every cached paneKey it remembers. Issued
-    // *after* the handler is wired so the request-driven replay shape
-    // strictly trails our subscription on the dispatcher's single write
-    // callback. Best-effort: a relay that does not know the method
-    // (e.g. older relay binary) returns -32601; CONNECTION_LOST / DISPOSED
-    // arise from mux teardown mid-flight on routine reconnect/shutdown.
+    // Why: request replay of cached paneKeys only after the handler is wired, so replayed events can't arrive before we subscribe. Best-effort.
     void mux.request(AGENT_HOOK_REQUEST_REPLAY_METHOD).catch((err) => {
       const code = (err as { code?: unknown })?.code
       if (code === -32601 || code === 'CONNECTION_LOST' || code === 'DISPOSED') {
@@ -993,9 +870,7 @@ export class SshRelaySession {
       if (mux.isDisposed()) {
         return
       }
-      // Why: a normal disconnect/teardown rejects the in-flight request with
-      // "Multiplexer disposed"; suppress the warn for that path so reconnect
-      // cycles aren't noisy.
+      // Why: suppress the warn when a normal teardown rejects the in-flight request, so reconnect cycles aren't noisy.
       if (mux.isDisposed()) {
         return
       }
@@ -1020,8 +895,7 @@ export class SshRelaySession {
     if (reason === 'shutdown') {
       clearPtyOwnershipForConnection(this.targetId)
     } else {
-      // Why: handlers are detached above, so no late event can recreate a
-      // stamped status between this clear and reconnect replay.
+      // Why: handlers detached above, so no late event can re-stamp status between this clear and reconnect replay.
       agentHookServer.clearStatusEntriesForConnection(this.targetId)
     }
 
@@ -1039,10 +913,7 @@ export class SshRelaySession {
     unregisterSshGitProvider(this.targetId)
   }
 
-  // Why: kept for back-compat with old relay binaries during the upgrade
-  // window — those still gate FS ops on registered roots. New relays no-op
-  // these notifications. Tracked for removal once the relay-version floor
-  // moves past the cutover (see docs/relay-fs-allowlist-removal.md).
+  // Why: back-compat for old relays that gate FS ops on registered roots; removable post-cutover (docs/relay-fs-allowlist-removal.md).
   private async registerRelayRoots(mux: SshChannelMultiplexer): Promise<void> {
     const remoteRepos = this.store.getRepos().filter((r) => r.connectionId === this.targetId)
 
@@ -1069,9 +940,7 @@ export class SshRelaySession {
     )
   }
 
-  // Why: extracted so establish() and reconnect() share exactly the same
-  // event wiring. Previously forgetting to wire onReplay on one path
-  // caused silent terminal blanking after reconnect.
+  // Why: shared by establish()/reconnect() so both paths reset renderer lists the same way.
   private broadcastEmptyLists(): void {
     const win = this.getMainWindow()
     if (!win || win.isDestroyed()) {
@@ -1091,17 +960,13 @@ export class SshRelaySession {
     if (!this.mux || this.isDisposed()) {
       return
     }
-    // Why: each scan walks /proc/*/fd on the remote host, so the scanner skips
-    // ticks entirely while no window can show the results (hidden to tray or
-    // minimized overnight) and rescans immediately when the window returns.
+    // Why: each scan walks /proc/*/fd remotely, so skip ticks while the window is hidden and rescan when it returns.
     const scanner = new PortScanner({
       isWindowVisible: () => isMainWindowVisible(this.getMainWindow()),
       onWindowBecameVisible: onMainWindowBecameVisible
     })
     this.portScanner = scanner
-    // Why: capture the scanner instance so that a late ports.detect callback
-    // from a previous relay session (before reconnect replaced it) is silently
-    // discarded instead of publishing stale results into the new session.
+    // Why: guard against a late ports.detect callback from a pre-reconnect scanner publishing stale results into the new session.
     scanner.startScanning(this.targetId, this.mux, (targetId, ports, platform) => {
       if (this.portScanner !== scanner) {
         return
@@ -1131,11 +996,7 @@ export class SshRelaySession {
       if (!win || win.isDestroyed()) {
         return
       }
-      // Why: hidden-delivery gate parity with ipc/pty.ts — runtime ingestion
-      // above already consumed the chunk; gated renderer delivery is dropped
-      // and one out-of-band pty:modelRestoreNeeded signal latches
-      // model-restore-needed for reveal. Never an in-band pty:data sentinel:
-      // OSC-9999-only chunks legitimately strip to empty in the renderer.
+      // Why: hidden-delivery gate parity with ipc/pty.ts — latch model-restore out-of-band, never an in-band pty:data sentinel (OSC-9999-only chunks strip to empty).
       const store = this.store as { getSettings?: Store['getSettings'] }
       if (shouldDropHiddenRendererPtyData(payload.id, store.getSettings?.())) {
         const drop = recordHiddenRendererPtyDataDrop(payload.id, rawLength)
@@ -1210,9 +1071,7 @@ export class SshRelaySession {
       .getSshRemotePtyLeases(this.targetId)
       .filter((lease) => lease.state !== 'terminated' && lease.state !== 'expired')
     const leasedPtyIds = activeLeases.map((lease) => lease.ptyId)
-    // Why: carry each lease's pane identity into the attach so the relay can
-    // reject cross-generation id collisions even between split panes in one tab.
-    // Older leases may lack leafId, so tabId remains the compatibility fallback.
+    // Why: pass pane identity so the relay can reject cross-generation id collisions; tabId falls back for pre-leafId leases.
     const expectedIdentityByPtyId = new Map(
       activeLeases
         .map((lease): [string, ExpectedPtyIdentity] | null => {
@@ -1221,8 +1080,7 @@ export class SshRelaySession {
         })
         .filter((entry): entry is [string, ExpectedPtyIdentity] => entry !== null)
     )
-    // Why: after app restart, ptyOwnership is empty but durable SSH leases
-    // still describe remote PTYs that survived in the relay grace window.
+    // Why: after app restart ptyOwnership is empty, but durable SSH leases still describe grace-window survivors.
     const ptyIds = Array.from(
       new Set([
         ...getPtyIdsForConnection(this.targetId).map((ptyId) =>
@@ -1274,9 +1132,7 @@ export class SshRelaySession {
         deletePtyOwnership(appPtyId)
         this.forwardedReattachReplayByPty.delete(appPtyId)
         this.store.markSshRemotePtyLease(this.targetId, ptyId, 'expired')
-        // Why: if the new relay cannot reattach this id, the remote backing
-        // process is gone. Tell the renderer so it clears stale pane bindings
-        // instead of keeping a cursor-only terminal.
+        // Why: reattach failure means the remote process is gone; tell the renderer to clear the stale pane.
         const win = this.getMainWindow()
         if (win && !win.isDestroyed()) {
           win.webContents.send('pty:exit', { id: appPtyId, code: -1 })
diff --git a/src/main/ssh/ssh-relay-versioned-install.ts b/src/main/ssh/ssh-relay-versioned-install.ts
index b211fec4dd0..def8840ca57 100644
--- a/src/main/ssh/ssh-relay-versioned-install.ts
+++ b/src/main/ssh/ssh-relay-versioned-install.ts
@@ -1,12 +1,6 @@
-// Versioned-install plumbing for the remote relay.
-//
-// Why this exists: the relay used to install into a single shared directory
-// (~/.orca-remote/relay-v0.1.0) which the deploy step would overwrite in place
-// on every cross-version push. A daemon already loaded into memory then served
-// new clients off rewritten on-disk code, producing protocol drift and a
-// reconnect loop. We now install each (RELAY_VERSION + content-hash) bundle
-// into its own directory and never mutate it after the install finishes,
-// matching VS Code's `~/.vscode-server/bin/<commit>/` layout.
+// Versioned-install plumbing for the remote relay: each (RELAY_VERSION + content-hash)
+// bundle installs into its own immutable dir (like VS Code's ~/.vscode-server/bin/<commit>/)
+// so an in-memory daemon never serves new clients off overwritten on-disk code.
 //
 // See: docs/ssh-relay-versioned-install-dirs.md
 
@@ -44,17 +38,10 @@ import { windowsRelayPipePathsForSocketName } from './ssh-relay-endpoints'
 import { isUnconfirmedSshCommandTermination } from './ssh-relay-exec-command'
 import { isSshSessionLimitError } from './ssh-session-limit-error'
 
-// Why: the GC pass and the version-dir parser must agree on what counts as a
-// relay install dir. Single source of truth for both. The pattern matches the
-// new layout `relay-${RELAY_VERSION}+${hash}` and the legacy `relay-v${VERSION}`
-// so the GC eventually drains the old layout once its daemons idle out.
+// Single source of truth for GC and the version-dir parser; matches both the new and legacy relay-dir layouts.
 const RELAY_VERSION_DIR_REGEX = /^relay-(v?\d+\.\d+\.\d+(\+[0-9a-f]+)?)$/
 
-// Why: legacy dirs from before `.install-complete` was introduced (i.e. the
-// `relay-v0.1.0` shape with no content-hash suffix). They are missing the
-// install-complete sentinel by definition and need a separate liveness-only
-// GC check so they actually drain after the legacy daemon dies, instead of
-// living on remote disks forever.
+// Legacy dirs predate `.install-complete`; they need a liveness-only GC check so they eventually drain.
 const LEGACY_RELAY_DIR_REGEX = /^relay-v\d+\.\d+\.\d+$/
 
 const INSTALL_COMPLETE_NAME = '.install-complete'
@@ -78,11 +65,9 @@ function execHostCommand(
 }
 
 /**
- * Read the local relay's content-hashed version (e.g. "0.1.0+0a5fe134d020")
- * from `${localRelayDir}/.version`. Throws on missing/empty so the caller
- * never silently falls back to a path where a daemon from a different code
- * generation may already be running — that fallback is the failure mode the
- * versioned-install design exists to prevent.
+ * Read the local relay's content-hashed version (e.g. "0.1.0+0a5fe134d020") from
+ * `${localRelayDir}/.version`. Throws on missing/empty so the caller can't
+ * silently fall back to a path where a stale-generation daemon may be running.
  */
 export function readLocalFullVersion(localRelayDir: string): string {
   const versionFile = join(localRelayDir, '.version')
@@ -119,11 +104,9 @@ export function computeRemoteRelayDir(
 }
 
 /**
- * Probe whether a fully-installed relay already exists at remoteRelayDir.
- *
- * "Fully installed" means: the directory contains relay.js, its isolated
- * relay-watcher.js child, and the .install-complete sentinel written at the
- * end of a successful install. Missing artifacts force a complete re-deploy.
+ * Probe whether a fully-installed relay exists at remoteRelayDir — meaning
+ * relay.js, its relay-watcher.js child, and the .install-complete sentinel are
+ * all present. Missing artifacts force a complete re-deploy.
  */
 export async function isRelayAlreadyInstalled(
   conn: SshConnection,
@@ -149,9 +132,9 @@ export async function isRelayAlreadyInstalled(
 }
 
 /**
- * Mark the install as complete, then normally release the lock. Deploy keeps
- * the lock through first launch so cross-version GC cannot move the directory
- * between finalization and daemon liveness becoming observable.
+ * Mark the install complete, then normally release the lock. Deploy keeps the
+ * lock through first launch so cross-version GC can't move the dir before daemon
+ * liveness is observable.
  */
 export async function finalizeInstall(
   conn: SshConnection,
@@ -173,9 +156,8 @@ export async function finalizeInstall(
 }
 
 /**
- * Release the install lock without writing the completion sentinel. Called
- * from the failure path so the dir remains a recoverable partial that the
- * next deploy detects (alreadyInstalled=false) and re-runs upload+install.
+ * Release the install lock without writing the completion sentinel, leaving the
+ * dir as a recoverable partial the next deploy re-installs.
  */
 export async function abandonInstall(
   conn: SshConnection,
@@ -187,17 +169,9 @@ export async function abandonInstall(
 }
 
 /**
- * Garbage-collect old version directories. Removes a sibling dir under
- * `${remoteHome}/${RELAY_REMOTE_DIR}/` only if ALL of:
- *
- *   - it matches the relay-version-dir regex (allowlist)
- *   - it is NOT the current version dir
- *   - it has no live `relay-*.sock` (pgrep + connectability probe)
- *   - it contains `.install-complete` (a fully-installed dir, not a partial)
- *   - it does NOT contain `.install-lock` (no in-progress install)
- *
- * Best-effort: any error is logged and swallowed; GC must never block the
- * user from connecting.
+ * Garbage-collect old version directories: remove an idle, fully-installed,
+ * unlocked sibling version dir (never the current one). Best-effort — errors
+ * are swallowed so GC never blocks the user from connecting.
  */
 export async function gcOldRelayVersions(
   conn: SshConnection,
@@ -242,8 +216,7 @@ export async function gcOldRelayVersions(
         kept.push(name)
         continue
       }
-      // Why: the claim is a sibling, so it survives moving/deleting the
-      // candidate and lets installers back out before mutating the old path.
+      // Why: the claim is a sibling, so it survives moving/deleting the candidate and lets installers back out first.
       const gcClaimToken = await tryAcquireRelayGcClaim(conn, dir, host)
       if (!gcClaimToken) {
         kept.push(name)
@@ -252,8 +225,7 @@ export async function gcOldRelayVersions(
       let preserveGcClaim = false
       let gcClaimReleaseNeeded = true
       try {
-        // Recheck under the stable claim. New installers probe the claim both
-        // before and after creating their in-tree lock, closing both orders.
+        // Recheck under the stable claim; installers probe it before and after creating their lock, closing both orders.
         if (!(await isCandidateSafeToRemove(conn, dir, name, host, options))) {
           kept.push(name)
           continue
@@ -268,8 +240,7 @@ export async function gcOldRelayVersions(
           kept.push(name)
           continue
         }
-        // Once renamed, a fresh install at the original path is isolated from
-        // deletion of the tombstone, so the sibling claim can be released.
+        // Once renamed, a fresh install at the original path is isolated from the tombstone's deletion, so release the claim.
         const release = await releaseRelayGcClaimWithRetry(conn, dir, gcClaimToken, host)
         gcClaimReleaseNeeded = release === 'unknown'
         await execHostCommand(conn, host, removeRemoteTreeCommand(host, tombstone))
@@ -326,22 +297,14 @@ async function isCandidateSafeToRemove(
   const locked = lockState === 'LOCKED'
 
   if (locked) {
-    // Why: a locked dir is normally unsafe to remove — but a STALE lock
-    // (remote age older than INSTALL_LOCK_STALE_MS) means the previous installer
-    // crashed and is never coming back. If the dir also has the
-    // .install-complete sentinel (touch succeeded but the rm-lock at the
-    // end of finalizeInstall failed), removing the dir is safe — no
-    // installer is racing us, and the daemon (if any) keeps running off
-    // its already-loaded code regardless of disk state.
+    // Why: stale lock = crashed installer; finalize can leave a dir .install-complete yet locked (lock-rm failed), so it's reclaimable.
     if (!(await isRelayInstallLockStale(conn, lockDir, host))) {
       return false
     }
     process.stderr.write?.(`[ssh-relay] GC: lock at ${lockDir} is stale; treating as recoverable\n`)
   }
 
-  // Legacy dirs (relay-v0.1.0) predate .install-complete. Skip the sentinel
-  // check for them and rely solely on the live-socket probe — that's the
-  // only signal we have that a legacy daemon is still serving clients.
+  // Legacy dirs predate .install-complete; skip the sentinel and rely on the live-socket probe alone.
   if (!isLegacy) {
     const completePath = joinRemotePath(host, dir, INSTALL_COMPLETE_NAME)
     const completeProbe = await execHostCommand(
@@ -372,10 +335,7 @@ async function hasLiveRelaySocket(
   }
 ): Promise<boolean> {
   try {
-    // Why: `ls -1 dir/relay-*.sock 2>/dev/null` lists socket files. For each,
-    // we test -S to confirm it's a socket inode. We do NOT attempt to open
-    // the socket here — `test -S` is sufficient for the GC decision and a
-    // connect-and-close probe would race with a daemon that's about to idle.
+    // Why: `test -S` only — a connect-and-close probe would race with a daemon about to idle.
     const windowsOptions =
       isWindowsRemoteHost(host) && options?.windowsNodePath
         ? {

From 0f7250879ae3791512e3d00095aba91f797c0dec Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Mon, 20 Jul 2026 03:18:32 -0700
Subject: [PATCH 50/54] refactor(comments): slim verbose comments in renderer
 state (store/hooks/lib) (#9545)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Collapse multi-line explanatory comment blocks into single-line "why" statements
per AGENTS.md ("Document the Why, Briefly"): drop restatements of the code and
mechanism narration; keep the non-obvious reason, external refs, and directives.

Comments-only — verified no code changed via a Babel/esbuild comment-strip
token-equality gate against origin/main; typecheck and oxlint clean.

Area: renderer — store, hooks, lib, runtime. 36 files changed, 1673 insertions(+), 5677 deletions(-).

Co-authored-by: Orca <help@stably.ai>
---
 src/renderer/src/App.tsx                      | 562 ++++------------
 .../src/hooks/useAutoAckViewedAgent.ts        | 101 +--
 src/renderer/src/hooks/useComposerState.ts    | 427 +++---------
 .../src/hooks/useEditorExternalWatch.ts       | 220 ++-----
 src/renderer/src/hooks/useIpcEvents.ts        | 491 ++++----------
 src/renderer/src/lib/agent-status.test.ts     |  81 +--
 src/renderer/src/lib/agent-status.ts          |  59 +-
 .../src/lib/launch-agent-in-new-tab.ts        |  94 +--
 .../pane-terminal-output-scheduler.ts         | 176 ++---
 .../terminal-arabic-shaping-joiner.ts         |  92 +--
 src/renderer/src/lib/telemetry.ts             |  65 +-
 src/renderer/src/lib/use-tab-agent.ts         | 122 +---
 src/renderer/src/lib/workspace-session.ts     |  88 +--
 src/renderer/src/lib/worktree-activation.ts   | 132 +---
 src/renderer/src/lib/worktree-status.ts       |  69 +-
 .../src/runtime/sync-runtime-graph.ts         |  93 +--
 .../src/runtime/web-runtime-session.ts        |  75 +--
 .../src/runtime/web-session-tabs-sync.ts      | 164 ++---
 src/renderer/src/store/slices/agent-status.ts | 476 +++-----------
 src/renderer/src/store/slices/browser.ts      | 124 +---
 src/renderer/src/store/slices/diffComments.ts | 110 +---
 src/renderer/src/store/slices/editor.ts       | 484 +++-----------
 src/renderer/src/store/slices/github.ts       | 497 ++++----------
 src/renderer/src/store/slices/repos.ts        | 190 ++----
 .../src/store/slices/store-cascades.test.ts   |  69 +-
 .../slices/store-session-cascades.test.ts     | 112 +---
 src/renderer/src/store/slices/tabs.test.ts    | 125 +---
 src/renderer/src/store/slices/tabs.ts         | 180 ++---
 .../store/slices/terminals-hydration.test.ts  |  57 +-
 src/renderer/src/store/slices/terminals.ts    | 615 ++++--------------
 src/renderer/src/store/slices/ui.ts           | 280 ++------
 .../src/store/slices/worktree-nav-history.ts  |  65 +-
 .../src/store/slices/worktrees.test.ts        |  84 +--
 src/renderer/src/store/slices/worktrees.ts    | 543 ++++------------
 src/renderer/src/web/web-preload-api.ts       | 141 ++--
 src/renderer/src/web/web-runtime-client.ts    |  87 +--
 36 files changed, 1673 insertions(+), 5677 deletions(-)

diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 977b32d30f6..faf1b7bb9ba 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -195,18 +195,13 @@ import {
   subscribeBackgroundTerminalWorktreeMountRequests
 } from './components/terminal/background-terminal-worktree-mount'
 
-// Why: agents alive during a hard kill (crash, forced update install) need a
-// reasonably fresh resume record on disk; one minute bounds the lost window
-// without measurable per-tick cost (the capture skips unchanged records).
+// Why: bound the resume-record loss window on a hard kill to ~1 min; capture skips unchanged records so per-tick cost is negligible.
 const SLEEPING_AGENT_RESUME_CAPTURE_INTERVAL_MS = 60_000
 
 const isMac = navigator.userAgent.includes('Mac')
 const isWindows = !isMac && navigator.userAgent.includes('Windows')
 const shortcutPlatform: NodeJS.Platform = isMac ? 'darwin' : isWindows ? 'win32' : 'linux'
-// Why: Windows and Linux both run with the native title bar removed (Windows
-// via titleBarStyle: 'hidden', Linux via frame: false), so the renderer draws
-// its own logo/menu anchor and min/max/close controls on both. Paired web
-// clients run in a browser tab, so they must not render desktop window chrome.
+// Why: Windows and Linux remove the native title bar so the renderer draws its own chrome; paired web clients run in a browser tab and must not.
 const hasCustomTitleBar = shouldRenderDesktopWindowChrome({
   platform: shortcutPlatform,
   isWebClient: isPairedWebClientWindow()
@@ -229,9 +224,7 @@ function getKeybindingContext(target: EventTarget | null): KeybindingContext {
     : 'app'
 }
 
-// Abstraction over a real KeyboardEvent and a synthetic double-tap gesture so a
-// single dispatch path serves both. KeybindingInput-compatible (key/code +
-// modifier flags) so it flows straight into keybindingMatchesAction.
+// Abstraction over a real KeyboardEvent and a synthetic double-tap gesture so one dispatch path serves both; KeybindingInput-compatible.
 type ShortcutDispatchInput = {
   key?: string
   code?: string
@@ -245,16 +238,11 @@ type ShortcutDispatchInput = {
   preventDefault: () => void
 }
 
-// Why: Windows ('hidden' titleBarStyle) and Linux (frame: false) both remove
-// the native OS title bar, so we render our own minimize/maximize/close
-// buttons. These SVG icons match the Fluent/Win11 style: thin 10×10 paths on a
-// 40×30 hit area.
+// Why: Windows and Linux both remove the native title bar, so we render our own min/max/close buttons (Fluent/Win11-style SVGs).
 function WindowControls(): React.JSX.Element {
   const [maximized, setMaximized] = useState(false)
   useEffect(() => {
-    // Why: window:maximize-changed only fires on transitions, so a window
-    // restored to a maximized state at startup would render the wrong icon
-    // until the user first clicks the button. Seed from main on mount.
+    // Why: maximize-changed only fires on transitions; seed from main on mount so a startup-maximized window shows the right icon.
     let cancelled = false
     void window.api.ui.isMaximized().then((value) => {
       if (!cancelled) {
@@ -302,10 +290,7 @@ function WindowControls(): React.JSX.Element {
       <button
         className="window-controls-btn window-controls-close"
         aria-label={translate('auto.App.e960d18540', 'Close')}
-        // Why: IPC to main so the BrowserWindow 'close' event fires, which
-        // sends 'window:close-requested' back to the renderer and keeps the
-        // terminal-running confirmation guard active. window.close() is
-        // unreliable in sandboxed renderers.
+        // Why: route close through main so the 'close' event fires the terminal-running confirmation guard; window.close() is unreliable in sandboxed renderers.
         onClick={() => window.api.ui.requestClose()}
       >
         <svg width="10" height="10" viewBox="0 0 10 10" aria-hidden>
@@ -374,12 +359,9 @@ const FloatingTerminalPanel = lazy(() =>
     default: module.FloatingTerminalPanel
   }))
 )
-// Why: lazy-loaded so the WebP asset + overlay module aren't fetched unless
-// the user opts into the experimental flag.
+// Why: lazy so the WebP asset + overlay module aren't fetched unless the experimental flag is on.
 const PetOverlay = lazy(() => import('./components/pet/PetOverlay'))
-// Why: lazy so onboarding's step modules + assets aren't fetched for users
-// past first-launch. The gate `shouldShowOnboarding` lives in its own tiny
-// module so no eager import path pulls OnboardingFlow into the main chunk.
+// Why: lazy so onboarding's step modules + assets aren't fetched for users past first-launch.
 const OnboardingFlow = lazy(() => import('./components/onboarding/OnboardingFlow'))
 
 function applyRemoteWorkspacePatchStatus(
@@ -433,10 +415,7 @@ function App(): React.JSX.Element {
     recordFeatureInteractionForTour: boolean
   } | null>(null)
 
-  // Why: Zustand actions are referentially stable, but each individual
-  // useAppStore(s => s.someAction) still registers a subscription that React
-  // must check on every store mutation. Consolidating action refs into one
-  // useShallow subscription means one equality check instead of many.
+  // Why: consolidate action refs into one useShallow subscription so React runs one equality check per store mutation instead of one per action.
   const actions = useAppStore(
     useShallow((s) => ({
       toggleSidebar: s.toggleSidebar,
@@ -496,16 +475,13 @@ function App(): React.JSX.Element {
     effectiveActiveTabExpanded
   } = useAppStore(useShallow(selectActiveTerminalChromeState))
   const activePendingCreationId = useAppStore((s) => s.activePendingCreationId)
-  // Why: the creation surface owns the tab strip from the first pending frame.
-  // Gating it on the delayed loader flag made the tab bar swap in mid-create.
+  // Why: the creation surface owns the tab strip from the first pending frame; gating on the delayed loader flag swapped the tab bar mid-create.
   const activePendingCreationExists = useAppStore(
     (s) =>
       s.activePendingCreationId !== null &&
       s.pendingWorktreeCreations[s.activePendingCreationId] !== undefined
   )
-  // Why: App swaps the sidebar between workspace and landing layouts when the
-  // active workspace is slept/deleted. Keep virtualized scroll memory above
-  // that remount so the left workspace list doesn't restart at scrollTop 0.
+  // Why: keep virtualized scroll memory above the sidebar's workspace/landing remount so the left list doesn't restart at scrollTop 0.
   const worktreeSidebarScrollOffsetRef = useRef(0)
   const worktreeSidebarScrollAnchorRef = useRef<VirtualizedScrollAnchor>(null)
   const floatingVisibleTabCount = useAppStore(selectFloatingVisibleTabCount)
@@ -534,16 +510,12 @@ function App(): React.JSX.Element {
   if (activeWorktreeId !== null || backgroundTerminalMountRequested) {
     hasMountedTerminalWorkbenchRef.current = true
   }
-  // Why: skip the terminal bundle on the no-workspace landing path, but once a
-  // workspace has mounted, keep Terminal-owned hidden panes alive through sleep
-  // and shutdown transitions where activeWorktreeId can briefly become null.
+  // Why: skip the terminal bundle on the landing path, but once mounted keep hidden panes alive through sleep/shutdown when activeWorktreeId briefly goes null.
   const shouldMountTerminalWorkbench =
     activeWorktreeId !== null ||
     backgroundTerminalMountRequested ||
     hasMountedTerminalWorkbenchRef.current
-  // Why: visible worktree creation owns its faux tab strip from start to finish;
-  // the previous workspace must stay mounted for retention without rendering
-  // real chrome.
+  // Why: visible worktree creation owns its faux tab strip start to finish; keep the previous workspace mounted for retention without real chrome.
   const creationLayoutActive = shouldShowWorktreeCreationSurface({
     activeView,
     activePendingCreationId,
@@ -553,13 +525,10 @@ function App(): React.JSX.Element {
     activeView === 'terminal' && activeWorktreeId !== null && !creationLayoutActive
   const terminalWorkbenchVisible =
     activeView === 'terminal' && activeWorktreeId !== null && !creationLayoutActive
-  // Why: a closed empty floating workspace is not startup-critical. Once it owns
-  // tabs, keep it mounted while closed so hidden terminal/browser/editor panes
-  // retain their local state.
+  // Why: once the floating workspace owns tabs, keep it mounted while closed so hidden terminal/browser/editor panes retain local state.
   const shouldMountFloatingTerminalPanel =
     floatingTerminalEnabled && (floatingTerminalOpen || floatingVisibleTabCount > 0)
-  // Why: the floating workspace is a transient overlay; hotkey minimize should
-  // return keyboard focus to the surface the user was working in before it.
+  // Why: floating workspace is a transient overlay; hotkey minimize returns focus to the surface the user came from.
   const floatingTerminalReturnFocusRef = useRef<HTMLElement | null>(null)
   const floatingTerminalReturnFocusFrameRef = useRef<number | null>(null)
 
@@ -617,8 +586,7 @@ function App(): React.JSX.Element {
     (nextOpen: SetStateAction<boolean>): void => {
       const resolvedOpen =
         typeof nextOpen === 'function' ? nextOpen(floatingTerminalOpen) : nextOpen
-      // Why: recordFeatureInteraction updates Zustand subscribers; doing it
-      // inside React's state updater logs a render-phase update warning.
+      // Why: recordFeatureInteraction updates Zustand subscribers; running it inside the state updater logs a render-phase update warning.
       if (resolvedOpen && !floatingTerminalOpen) {
         const state = useAppStore.getState()
         floatingWorkspaceTourInteractionSnapshotRef.current =
@@ -709,8 +677,7 @@ function App(): React.JSX.Element {
   const onboardingSettingsDetourActive =
     onboardingSettingsDetour && activeView === 'settings' && shouldRenderOnboarding
   if (onboardingSettingsDetour && !onboardingSettingsDetourActive) {
-    // Why: the settings detour is valid only while Settings is onscreen; clear
-    // it during render so onboarding can resume without a follow-up Effect pass.
+    // Why: the detour is valid only while Settings is onscreen; clear it during render so onboarding resumes without an extra Effect pass.
     setOnboardingSettingsDetour(false)
   }
 
@@ -724,8 +691,7 @@ function App(): React.JSX.Element {
       return
     }
     if (shouldMountAddRepoDialog && !unmountAddRepoDialogTimerRef.current) {
-      // Why: AddRepoDialog's close effect aborts in-flight clone/nested work.
-      // Keep one closed render, then remove hidden SSH/remote subscriptions.
+      // Why: AddRepoDialog's close effect aborts in-flight clone work; keep one closed render before unmounting hidden SSH/remote subscriptions.
       unmountAddRepoDialogTimerRef.current = setTimeout(() => {
         setShouldMountAddRepoDialog(false)
         unmountAddRepoDialogTimerRef.current = null
@@ -742,28 +708,10 @@ function App(): React.JSX.Element {
   // Subscribe to IPC push events
   useIpcEvents()
   useAutomationDispatchEvents()
-  // Why: retention must run at App level so the inline per-card agents list
-  // always sees retained entries. If retention ran inside the sidebar-card
-  // subtree, "done" agents would vanish any time the user collapsed a card's
-  // inline agents section. The retention hooks are hosted inside
-  // <RetainedAgentsSyncGate /> (a leaf component that renders null) rather
-  // than being called inline here so its high-churn store subscriptions
-  // (agentStatusByPaneKey ticks at PTY event frequency)
-  // do not re-render the App tree on every agent status update.
-  // Why: git conflict-operation state also drives the worktree cards. Polling
-  // cannot live under RightSidebar because App unmounts that subtree when the
-  // sidebar is closed, which leaves stale "Rebasing"/"Merging" badges behind
-  // until some unrelated view remount happens to refresh them.
-  // Why: visible-window polling runs immediately on mount. Wait until the
-  // workspace session has hydrated so git status work cannot compete with the
-  // first window becoming usable.
+  // Why: retention runs at App level (in <RetainedAgentsSyncGate />, a null leaf) so "done" agents survive card collapse and its high-churn subscriptions don't re-render App.
+  // Why: git polling lives at App level (RightSidebar unmounts when closed, stranding stale Rebasing/Merging badges); gate on workspaceSessionReady so it doesn't compete with first paint.
   useGitStatusPolling({ enabled: workspaceSessionReady })
-  // Why: the editor must hear external filesystem changes regardless of
-  // which right-sidebar panel is visible (Explorer unmounts when the user
-  // switches to Source Control or Checks). Wiring this at App level mirrors
-  // VSCode's workbench-scoped `TextFileEditorModelManager`, which reloads
-  // clean models from a single always-on file-change subscription instead
-  // of tying reloads to the Explorer UI lifecycle.
+  // Why: wire file-change watching at App level so the editor keeps hearing FS changes when Explorer unmounts (right-sidebar switches to Source Control/Checks).
   useEditorExternalWatch()
   useGlobalFileDrop()
   useAutoAckViewedAgent()
@@ -773,9 +721,7 @@ function App(): React.JSX.Element {
   }, [])
 
   useEffect(() => {
-    // Why: `onboarding === null` is the startup loading state. Suppress
-    // contextual tours until the persisted onboarding state is known so a
-    // first-run user cannot have a tour marked seen before onboarding appears.
+    // Why: suppress tours until onboarding state is known (null = loading) so a first-run user can't mark a tour seen before onboarding appears.
     const suppressTours = !onboardingLoaded || shouldShowOnboarding(onboarding)
     actions.setContextualToursOnboardingVisible(suppressTours)
   }, [actions, onboarding, onboardingLoaded])
@@ -784,8 +730,7 @@ function App(): React.JSX.Element {
     if (!persistedUIReady || !onboardingLoaded || contextualToursAutoEligible !== null) {
       return
     }
-    // Why: this rollout is for users who are still in first-run onboarding.
-    // Existing profiles are locally classified once and never auto-toured.
+    // Why: rollout targets first-run onboarding users; existing profiles are classified once and never auto-toured.
     actions.setContextualToursAutoEligible(shouldShowOnboarding(onboarding))
   }, [actions, contextualToursAutoEligible, onboarding, onboardingLoaded, persistedUIReady])
 
@@ -828,8 +773,7 @@ function App(): React.JSX.Element {
     })
 
     if (featureTipsDecision.kind === 'suppress-for-onboarding') {
-      // Why: first-download users should finish onboarding without a second
-      // education modal appearing later in the same first-run session.
+      // Why: first-run users should finish onboarding without a second education modal in the same session.
       featureTipsSuppressedByOnboardingThisSessionRef.current = true
       return
     }
@@ -844,8 +788,7 @@ function App(): React.JSX.Element {
     } else if (featureTipsDecision.tipId === 'cmd-j-palette') {
       trackCmdJPaletteFeatureTipShown('app_open')
     }
-    // Why: once a tip is visible, app quit/crash should not make it reappear
-    // on the next launch just because the user never clicked a dismiss button.
+    // Why: mark seen on show so a quit/crash before dismiss doesn't reappear it next launch.
     actions.markFeatureTipsSeen([featureTipsDecision.tipId])
     actions.openModal('feature-tips', { source: 'app_open', tipId: featureTipsDecision.tipId })
   }, [
@@ -863,13 +806,7 @@ function App(): React.JSX.Element {
     setOnboardingSettingsDetour(true)
   }, [])
 
-  // Why: sidebar open/close flips width instantaneously. useLayoutEffect
-  // runs synchronously after React commits the DOM but before paint, so
-  // dispatching SYNC_FIT_PANES_EVENT here lets the terminal reflow in the
-  // same frame as the width change — no "wrongly-sized terminal" transient
-  // and no delayed snap. The later ResizeObserver rAF and 150ms debounced
-  // fit both become no-ops because proposeDimensions() will match the
-  // already-fitted cols/rows.
+  // Why: useLayoutEffect fires before paint, so dispatching SYNC_FIT_PANES_EVENT reflows the terminal in the same frame as the width change — no wrongly-sized transient.
   useLayoutEffect(() => {
     window.dispatchEvent(new CustomEvent(SYNC_FIT_PANES_EVENT))
   }, [sidebarOpen, rightSidebarOpen])
@@ -877,56 +814,28 @@ function App(): React.JSX.Element {
   // Fetch initial data + hydrate GitHub cache from disk
   useEffect(() => {
     let cancelled = false
-    // Why: AbortController must be declared outside the async block so the
-    // cleanup function can abort it. Under StrictMode the effect runs twice;
-    // without this, the first (unmounted) pass would keep spawning PTYs.
+    // Why: declared outside the async block so cleanup can abort it — under StrictMode the first (unmounted) pass would otherwise keep spawning PTYs.
     const abortController = new AbortController()
 
-    // Why (issue #1158): hydrate persisted UI immediately after ui.get()
-    // succeeds, before any later session step can throw. The UI writer is
-    // gated only on persistedUIReady, so falling back to defaults after a
-    // successful ui.get() would serialize those defaults back to disk.
+    // Why (issue #1158): hydrate persisted UI right after ui.get() succeeds; the UI writer is gated only on persistedUIReady, so later default fallback would serialize defaults to disk.
     let uiHydrated = false
-    // Why (issue #1158): track whether the success-path call to
-    // reconnectPersistedTerminals started so the catch path doesn't run it a
-    // second time. Reconnect mutates store state via per-tab set() blocks
-    // inside its loops (populating tabsByWorktree / ptyIdsByTabId); re-entering
-    // it on partially-mutated state would double-set ptyIds and drain pending*
-    // maps twice. If the success-path call started and threw mid-loop, those
-    // per-tab set() blocks may have populated tabsByWorktree / ptyIdsByTabId
-    // for some tabs but did NOT reach the tail set() that flips
-    // workspaceSessionReady — so we still need to force the flag true so the
-    // UI mounts.
+    // Why (issue #1158): track whether success-path reconnect started so the catch doesn't re-run it — re-entering on partially-mutated state would double-set ptyIds and drain pending* twice.
     let reconnectStarted = false
     void (async () => {
       const startupStartedAt = performance.now()
       logRendererStartupDiagnostic('startup-chain-start')
       try {
-        // Why: profile state only feeds the switcher and the add-project
-        // advisory — nothing in the hydration chain reads it synchronously,
-        // so it must not add a serial IPC round-trip before fetchSettings.
+        // Why: nothing in the hydration chain reads profile state synchronously, so don't let it add a serial IPC round-trip before fetchSettings.
         void actions.fetchOrcaProfiles()
-        // Why: repo/worktree hydration routes through settings.activeRuntimeEnvironmentId.
-        // Load settings first so a persisted remote runtime does not boot against
-        // the local filesystem and then hydrate stale local workspace state.
+        // Why: repo/worktree hydration routes through settings.activeRuntimeEnvironmentId; load settings first so a persisted remote runtime doesn't hydrate stale local state.
         await timeRendererStartupStep('fetch-settings', () => actions.fetchSettings())
-        // Why here: hidden-at-launch PTYs (background terminal reconnects,
-        // agent sessions) can query OSC 10/11 before any terminal pane mounts
-        // and main's responder is silent-until-first-push. Publish composed
-        // view attributes as soon as settings exist, before any spawn below.
+        // Why: hidden-at-launch PTYs can query OSC 10/11 before any pane mounts; publish view attributes as soon as settings exist so main's silent-until-push responder has data.
         publishTerminalViewAttributesAtAppStart(
           useAppStore.getState().settings,
           getSystemPrefersDark()
         )
-        // Why: keybindings + onboarding are main-side reads with no dependency
-        // on the catalog/session steps below, so start them now and await them
-        // at their original positions — the round-trips overlap the local
-        // catalog scans instead of queuing after them. Browser session profiles
-        // are deliberately NOT started early: on a remote runtime they route
-        // through a runtime RPC that may not be connected this early, and a
-        // failed fetch clears the profile list. The floating .catch marks the
-        // rejection handled if an earlier awaited step throws first; each await
-        // still rethrows its own failure.
+        // Why: start keybindings + onboarding now so their IPC overlaps the local catalog scans; await them at their original spots. The .catch marks rejections handled if an earlier await throws first.
+        // Why: browser session profiles are NOT started early — on a remote runtime the RPC may be unconnected and a failed fetch clears the list.
         const keybindingsPromise = timeRendererStartupStep('fetch-keybindings', () =>
           actions.fetchKeybindings()
         )
@@ -935,10 +844,7 @@ function App(): React.JSX.Element {
           window.api.onboarding.get()
         )
         onboardingPromise.catch(() => {})
-        // Why: hydrate persisted UI immediately after ui.get() so first paint
-        // reflects saved view settings before the catalog scans below. ui.get()
-        // is awaited (not overlapped) because the hydrate must land before the
-        // local-first catalog/session steps run.
+        // Why: await ui.get() (not overlap) so persisted view settings hydrate before the local catalog/session steps and first paint reflects them.
         const persistedUI = await timeRendererStartupStep('ui-get', () => window.api.ui.get())
         uiHydrated = timeRendererStartupSyncStep('hydrate-persisted-ui', () =>
           hydratePersistedUIAfterStartupRead({
@@ -951,9 +857,7 @@ function App(): React.JSX.Element {
           'list-runtime-session-hosts',
           listRuntimeSessionHostIdsForStartup
         )
-        // Why: first paint needs local data and persisted view settings, but
-        // saved remote runtimes can spend the full connect timeout. Load only
-        // the local catalog here; remotes refresh after hydration below.
+        // Why: saved remote runtimes can spend the full connect timeout; load only the local catalog for first paint and refresh remotes after hydration.
         await timeRendererStartupStep('fetch-repos-local', () =>
           actions.fetchReposForAllHosts({ remoteHosts: 'skip' })
         )
@@ -966,10 +870,7 @@ function App(): React.JSX.Element {
         await timeRendererStartupStep('fetch-worktrees', () =>
           actions.fetchAllWorktrees({ hydrationPurge: 'defer' })
         )
-        // Why: runtime-owned worktree slices live in per-host partitions.
-        // Remote catalogs now load after first paint, so include saved runtime
-        // host ids from local settings to restore their persisted session slices
-        // without waiting on network reachability. Unreadable partitions skip.
+        // Why: include saved runtime host ids so per-host worktree session slices restore from local settings without waiting on network reachability; unreadable partitions skip.
         const sessionRead = await timeRendererStartupStep('session-get', () =>
           fetchWorkspaceSessionWithRuntimeHostOwners(
             window.api.session,
@@ -991,13 +892,7 @@ function App(): React.JSX.Element {
             actions.hydrateEditorSession(sessionRead.session, sessionHydrationOptions)
             actions.hydrateBrowserSession(sessionRead.session, sessionHydrationOptions)
           })
-          // Why: prune lastVisitedAtByWorktreeId entries whose worktrees
-          // no longer exist. Must run AFTER hydration — before this point,
-          // async repo loads may not have populated worktreesByRepo yet and
-          // pruning would delete timestamps for worktrees that are about to
-          // appear. Seed the restored active worktree's timestamp if missing
-          // so users upgrading from a pre-feature build don't see the active
-          // worktree sink in the empty-query list.
+          // Why: prune visit timestamps AFTER hydration (earlier, worktreesByRepo may be empty and prune would drop entries for worktrees about to appear); seed the active worktree if missing.
           // See docs/cmd-j-empty-query-ordering.md.
           timeRendererStartupSyncStep('visit-timestamp-prune', () => {
             actions.pruneLastVisitedTimestamps()
@@ -1012,15 +907,8 @@ function App(): React.JSX.Element {
             setOnboardingLoaded(true)
           }
 
-          // Why: SSH connections must be re-established BEFORE terminal
-          // reconnect so that reconnectPersistedTerminals can route SSH-backed
-          // tabs through pty.attach on the relay. Passphrase-protected targets
-          // are deferred to tab focus to avoid stacking credential dialogs at
-          // startup before the user has context.
-          // Why: runtime-owned (ephemeral-VM) targets must never be dialed from
-          // the renderer — ssh.connect would dispose the runtime layer's live
-          // relay session. Main's windowless-promotion path can persist such
-          // ids into this list, so filter at the consumption boundary too.
+          // Why: re-establish SSH before terminal reconnect so SSH-backed tabs route through pty.attach; passphrase targets defer to tab focus to avoid stacked credential dialogs.
+          // Why: never dial runtime-owned (ephemeral-VM) targets from the renderer — ssh.connect would dispose the runtime layer's live relay session; filter them out here too.
           const connectionIds = (sessionRead.session.activeConnectionIdsAtShutdown ?? []).filter(
             (targetId) => !isRuntimeOwnedSshTargetId(targetId)
           )
@@ -1043,12 +931,7 @@ function App(): React.JSX.Element {
                 actions.setDeferredSshReconnectTargets(deferredTargets.map((t) => t.targetId))
               }
 
-              // Why: track which eager targets timed out so we can treat them
-              // as deferred — the underlying ssh.connect() keeps running in the
-              // main process, but reconnectPersistedTerminals won't see them as
-              // connected. Adding them to the deferred list ensures PTYs get
-              // reattached when the user focuses the tab (by which time the
-              // slow connect will likely have succeeded).
+              // Why: treat timed-out eager targets as deferred so their PTYs reattach on tab focus (ssh.connect keeps running in main and likely finishes by then).
               const timedOutTargets: string[] = []
               await timeRendererStartupStep(
                 'ssh-reconnect',
@@ -1081,9 +964,7 @@ function App(): React.JSX.Element {
                 ])
               }
 
-              // Why: connect's returned state is published above, but older or
-              // wrapped providers may return no state. Poll main once as a
-              // compatibility fallback before terminal restoration.
+              // Why: older/wrapped providers may return no state from connect; poll main once as a compatibility fallback before terminal restoration.
               for (const { targetId } of eagerTargets) {
                 if (timedOutTargets.includes(targetId)) {
                   continue
@@ -1107,9 +988,7 @@ function App(): React.JSX.Element {
             logRendererStartupDiagnostic('ssh-reconnect-skipped', { connectionIds: 0 })
           }
 
-          // Why: main overlaps daemon/hook startup with renderer hydration for
-          // first paint, but restored terminals still need those services ready
-          // before they mount and spawn/reconnect PTYs.
+          // Why: main overlaps daemon/hook startup with hydration, but restored terminals need those services ready before they spawn/reconnect PTYs.
           await timeRendererStartupStep('first-window-services-await', () =>
             window.api.app.awaitFirstWindowStartupServices()
           )
@@ -1118,13 +997,7 @@ function App(): React.JSX.Element {
             actions.reconnectPersistedTerminals(abortController.signal)
           )
           syncZoomCSSVar()
-          // Why (issue #1158): unlock the debounced session writer only after
-          // hydration AND all dependent startup steps (SSH reconnect, terminal
-          // reconnect) completed without throwing. If this flag flipped earlier
-          // and a later step threw, the catch path's reconnectPersistedTerminals
-          // would flip workspaceSessionReady=true with the gate already open,
-          // and the writer would serialize a partially-mutated store back to
-          // disk — the exact data-loss mode this PR fixes.
+          // Why (issue #1158): unlock the session writer only after hydration and all dependent steps succeeded, so a mid-startup throw can't serialize partially-mutated state to disk.
           actions.setHydrationSucceeded(true)
           logRendererStartupDiagnostic('startup-hydration-done', {
             durationMs: Math.round(performance.now() - startupStartedAt)
@@ -1148,13 +1021,7 @@ function App(): React.JSX.Element {
           })()
         }
       } catch (error) {
-        // Why (issue #1158): previously this catch called hydrateWorkspaceSession
-        // with empty defaults, which overwrote the in-memory tab map. The
-        // debounced session writer then serialized that empty state back to
-        // orca-data.json, silently erasing the user's saved tabs. The fix is
-        // to leave in-memory state untouched and keep hydrationSucceeded
-        // false so the writer stays gated. We still ensure persistedUIReady and
-        // workspaceSessionReady flip so the UI can mount without a session.
+        // Why (issue #1158): leave in-memory state untouched and keep hydrationSucceeded false (default-hydrating here once erased saved tabs); still flip the ready flags so the UI mounts.
         const stepLabel = error instanceof Error && error.message ? error.message : String(error)
         console.error(
           '[startup] Workspace session hydration failed; leaving disk state untouched:',
@@ -1162,21 +1029,12 @@ function App(): React.JSX.Element {
           error
         )
         if (!cancelled) {
-          // Why (issue #1158): only hydrate UI with defaults if ui.get() never
-          // produced persisted data. If the real UI hydrate already ran and a
-          // later session step threw, defaults would flow through the debounced
-          // UI writer and clobber ui.json (sidebar width, sort, filters, etc.).
+          // Why (issue #1158): only apply default UI if ui.get() never hydrated; otherwise defaults would clobber ui.json via the debounced writer.
           const fallbackUI = getStartupErrorFallbackUI(uiHydrated)
           if (fallbackUI) {
             actions.hydratePersistedUI(fallbackUI, 'startup')
           }
-          // Why (issue #1158): surface a sticky, dismissible toast so the
-          // user knows they're in degraded "no-save" mode. Without this, every
-          // new tab/file/browse becomes silently ephemeral — `hydrationSucceeded`
-          // stays false for the rest of the process and the session writer is
-          // a no-op. The "Restart now" action calls app.relaunch (defined in
-          // src/main/ipc/app.ts) so the user can recover with one click instead
-          // of having to find a quit/relaunch path themselves.
+          // Why (issue #1158): sticky toast so the user knows they're in degraded "no-save" mode (hydrationSucceeded stays false); "Restart now" calls app.relaunch to recover.
           toast.error(translate('auto.App.12e77cf12b', 'Session restore failed'), {
             description: translate(
               'auto.App.0a9e810705',
@@ -1191,11 +1049,7 @@ function App(): React.JSX.Element {
               }
             }
           })
-          // Why: reconnectPersistedTerminals flips workspaceSessionReady so the
-          // UI mounts; auto-tab-creation becomes unblocked. hydrationSucceeded
-          // is intentionally NOT set — the session writer must stay a no-op
-          // until the user gets a clean restart, so we don't overwrite the
-          // on-disk file we failed to load.
+          // Why: reconnect flips workspaceSessionReady so the UI mounts, but hydrationSucceeded stays false so the session writer can't overwrite the file we failed to load.
           if (!reconnectStarted) {
             try {
               await window.api.app.awaitFirstWindowStartupServices()
@@ -1205,25 +1059,9 @@ function App(): React.JSX.Element {
                 '[startup] reconnectPersistedTerminals failed in error path:',
                 reconnectErr
               )
-              // Why (issue #1158): re-check !cancelled before mutating store
-              // state. The await above may have run while the effect was being
-              // torn down (StrictMode pass 1 cleanup) — in that case the
-              // second pass owns hydration and we must not stomp its work
-              // from a cancelled run.
+              // Why (issue #1158): the await may have run during StrictMode teardown; re-check !cancelled so a cancelled pass 1 doesn't stomp pass 2's hydration.
               if (!cancelled) {
-                // Why (issue #1158): this is already the recovery path from a
-                // failed hydration. If the recovery itself throws, the async IIFE
-                // rejects as an unhandled promise and workspaceSessionReady never
-                // flips — leaving the user staring at a blank window. Forcing the
-                // flag true lets the app shell mount with an empty session, which
-                // is strictly better than a non-functional UI.
-                //
-                // Also clear pendingReconnect* maps because reconnectPersistedTerminals
-                // normally drains them as part of its post-conditions
-                // (see terminals.ts post-loop cleanup). Bypassing that drain by
-                // flipping only the flag would leave stale reconnect data in
-                // memory — any later reader of pending* maps could trigger
-                // phantom reconnect attempts on PTYs that no longer exist.
+                // Why (issue #1158): recovery threw too; force the flag so the shell still mounts, and clear pending* maps (normally drained by reconnect) to avoid phantom reconnects on dead PTYs.
                 useAppStore.setState({
                   workspaceSessionReady: true,
                   pendingReconnectWorktreeIds: [],
@@ -1233,15 +1071,7 @@ function App(): React.JSX.Element {
               }
             }
           } else {
-            // Why (issue #1158): the success-path call to
-            // reconnectPersistedTerminals already started; its per-tab set()
-            // blocks may have populated tabsByWorktree / ptyIdsByTabId for
-            // some tabs but did NOT reach the tail set() that flips
-            // workspaceSessionReady (that runs after the loop completes).
-            // Don't re-run reconnect over partially-mutated state — doing so
-            // would double-set ptyIds and drain pending* maps twice. Force
-            // the flag true so the UI mounts. The same pending* clear applies
-            // here for the same reason as above.
+            // Why (issue #1158): reconnect already started; re-running over its partially-mutated state would double-set ptyIds and drain pending* twice — force the flag, clear pending*.
             useAppStore.setState({
               workspaceSessionReady: true,
               pendingReconnectWorktreeIds: [],
@@ -1270,16 +1100,9 @@ function App(): React.JSX.Element {
   useEffect(() => {
     let previousKey = getRuntimeMobileSessionSyncKey(useAppStore.getState())
     return useAppStore.subscribe((state, previousState) => {
-      // Why: this subscriber fires on every store mutation (PTY/agent-status
-      // ticks). Read the cached prefers-dark snapshot — kept fresh by the shared
-      // listener that useSystemPrefersDark() below already mounts — instead of
-      // allocating a throwaway MediaQueryList via matchMedia on every tick,
-      // before the skip-gate even runs.
+      // Why: this fires on every store mutation; read the cached prefers-dark snapshot instead of allocating a throwaway MediaQueryList via matchMedia each tick.
       const systemPrefersDark = getSystemPrefersDarkSnapshot()
-      // Why: skip the key build entirely when every input field is unchanged
-      // by reference. Mirrors every field used by
-      // getRuntimeMobileSessionSyncKey so this gate covers every "could the
-      // key have changed?" case.
+      // Why: skip the key build when every input is reference-unchanged; the gate mirrors every field getRuntimeMobileSessionSyncKey uses.
       if (
         canSkipRuntimeMobileSessionSyncKeyBuild(
           state,
@@ -1313,18 +1136,14 @@ function App(): React.JSX.Element {
     }
   }, [workspaceSessionReady])
 
-  // Why: session persistence never drives JSX — it only writes to disk.
-  // Using a Zustand subscribe() outside React removes ~15 subscriptions from
-  // App's render cycle, eliminating re-renders on every tab/file/browser change.
+  // Why: session persistence only writes to disk; a Zustand subscribe() outside React drops ~15 render-cycle subscriptions and their re-renders on every tab/file/browser change.
   useEffect(() => {
     return createSessionWriteSubscriber({
       store: useAppStore,
       shouldSchedulePersist: () => !isRemoteWorkspaceSnapshotApplyInProgress(),
       persist: ({ patch }) => {
         const state = useAppStore.getState()
-        // Why: route each runtime host's worktree-scoped slice to its own
-        // partition; the returned promise is the local write so the
-        // remote-workspace upload chain below keeps its ordering.
+        // Why: route each host's worktree-scoped slice to its own partition; return the local write so the remote-workspace upload chain below keeps its ordering.
         const localWrite = patchWorkspaceSessionByHost(window.api.session, patch, state)
         void localWrite
         const hydratedTargetIds = Array.from(state.remoteWorkspaceHydratedTargetIds).filter(
@@ -1408,12 +1227,7 @@ function App(): React.JSX.Element {
     }
   }, [])
 
-  // Why: beforeunload never fires on a hard kill (crash, forced update
-  // install, TerminateProcess), so agents alive at that moment would leave no
-  // resume record. This periodic capture stores only agent session ids — not
-  // scrollback, see the no-periodic-scrollback note below — and the store
-  // action skips unchanged records, so idle ticks write nothing; real changes
-  // flow through the debounced session-write subscriber.
+  // Why: beforeunload never fires on a hard kill (crash, forced update, TerminateProcess), so periodically capture agent session ids (not scrollback) so live agents keep a resume record.
   useEffect(() => {
     const timer = window.setInterval(() => {
       if (!shouldPersistWorkspaceSession(useAppStore.getState())) {
@@ -1424,27 +1238,12 @@ function App(): React.JSX.Element {
     return () => window.clearInterval(timer)
   }, [])
 
-  // Own the single window-close-request subscription at the always-mounted App
-  // root. Why: the rich confirmation flow lives in Terminal, which is not
-  // mounted on the no-workspace landing page (and is lazy-loaded elsewhere), so
-  // subscribing there left File → Exit / Ctrl+Q with no listener and the window
-  // never closed (#5144). dispatchWindowCloseRequest delegates to Terminal's
-  // handler when present, else confirms the close directly.
+  // Why: subscribe at the always-mounted App root — Terminal owns the confirm flow but isn't mounted on the landing page, so subscribing there left File→Exit / Ctrl+Q with no listener (#5144).
   useEffect(() => {
     return window.api.ui.onWindowCloseRequested(dispatchWindowCloseRequest)
   }, [])
 
-  // Why there is no periodic scrollback save: PR #461 added a 3-minute
-  // setInterval that re-serialized every mounted TerminalPane's scrollback
-  // so a crash wouldn't lose in-session output. With many panes of
-  // accumulated output, each tick blocked the renderer main thread for
-  // several seconds (serialize is synchronous and does a binary search on
-  // >512KB buffers), causing visible input lag across the whole app.
-  // The durable replacement is the out-of-process terminal daemon
-  // (PR #729), which preserves buffers across renderer crashes with no
-  // main-thread work. Non-daemon users lose in-session scrollback on an
-  // unexpected exit — an acceptable tradeoff vs. periodic UI stalls, and
-  // in line with how most terminal apps behave.
+  // Why no periodic scrollback save: the old 3-min re-serialize (#461) stalled the main thread for seconds; the out-of-process daemon (#729) is the durable replacement, non-daemon users lose in-session scrollback on unexpected exit.
 
   useEffect(() => {
     if (!persistedUIReady) {
@@ -1529,8 +1328,7 @@ function App(): React.JSX.Element {
       applyDocumentTheme('system')
       const handler = (): void => {
         applyDocumentTheme('system')
-        // Why: system theme changes do not mutate the store, so mobile
-        // terminal colors need an explicit graph republish.
+        // System theme changes don't mutate the store, so mobile terminal colors need an explicit graph republish.
         scheduleRuntimeGraphSync()
       }
       mq.addEventListener('change', handler)
@@ -1561,28 +1359,23 @@ function App(): React.JSX.Element {
 
   const hasTabBar = tabCount >= 2
   const showTitlebarExpandButton = workspaceChromeActive && !hasTabBar && effectiveActiveTabExpanded
-  // Why: Activity and Space are full-page navigation surfaces — same
-  // treatment as Settings — so the worktree sidebar is removed for those views.
+  // Activity/Space are full-page navigation surfaces (like Settings), so the worktree sidebar is hidden there.
   const showSidebar =
     activeView !== 'settings' &&
     activeView !== 'activity' &&
     activeView !== 'space' &&
     activeView !== 'skills'
-  // Why: Tasks/Landing keep the full titlebar only when the sidebar is
-  // collapsed; with it open, mirror workspace view so titlebar-left sits flush
-  // above nav. Creation layout suppresses the full-width titlebar.
+  // Tasks/Landing show the full titlebar only when the sidebar is collapsed; open, they mirror workspace view (creation suppresses it).
   const stackedSidebarOpen =
     !workspaceChromeActive && !creationLayoutActive && showSidebar && sidebarOpen
-  // Why: visible creation keeps only the top-left window chrome; workspace tabs
-  // and right-sidebar chrome remain gated by workspaceChromeActive.
+  // Visible creation keeps only the top-left window chrome; tabs and right-sidebar chrome stay gated by workspaceChromeActive.
   const leftTitlebarChromeLayout = resolveLeftTitlebarChromeLayout({
     workspaceChromeActive,
     stackedSidebarOpen,
     creationLayoutActive,
     sidebarOpen
   })
-  // Why: suppress right sidebar controls on full-page navigation surfaces
-  // since those surfaces intentionally own the full content area.
+  // Full-page navigation surfaces own the whole content area, so suppress right-sidebar controls.
   const showRightSidebarControls = !creationLayoutActive && canShowRightSidebarForView(activeView)
   const showProfileSwitcherInSidebarFooter = showSidebar && sidebarOpen
   const showProfileSwitcherInTopRight = !showProfileSwitcherInSidebarFooter
@@ -1611,8 +1404,7 @@ function App(): React.JSX.Element {
     workspaceChromeActive,
     creationLayoutActive
   })
-  // Why: window key listeners are global and long-lived; keep one registration
-  // while letting the handler read current shortcut state on each key event.
+  // Window key listeners are global and long-lived: one registration, but the handler reads current shortcut state each key event.
   globalShortcutStateRef.current = {
     activeView,
     activeWorktreeId,
@@ -1645,15 +1437,11 @@ function App(): React.JSX.Element {
         creationLayoutActive
       } = globalShortcutStateRef.current
 
-      // Why: child-component handlers (e.g. terminal search Cmd+G / Cmd+Shift+G)
-      // register on the same window capture phase and fire first. If they already
-      // called preventDefault, this handler must not also act on the event —
-      // otherwise both actions execute (e.g. search navigation AND sidebar open).
+      // Child handlers (e.g. terminal search) share this window capture phase and fire first; bail if they already preventDefault'd so both don't act.
       if (input.defaultPrevented) {
         return
       }
-      // Why: the Settings recorder intentionally captures existing app
-      // shortcuts, so global handlers must not fire while its button has focus.
+      // The Settings shortcut recorder captures existing shortcuts, so global handlers must not fire while its button has focus.
       if (
         input.target instanceof Element &&
         input.target.closest('[data-shortcut-recorder-active]') !== null
@@ -1662,10 +1450,7 @@ function App(): React.JSX.Element {
       }
       const context = getKeybindingContext(input.target)
 
-      // Note: some app-level shortcuts are also intercepted via
-      // before-input-event in createMainWindow.ts so they still work when a
-      // browser guest has focus. The renderer keeps matching handlers for
-      // local-focus cases and to preserve the same guards in one place.
+      // Note: some shortcuts are also intercepted in createMainWindow.ts before-input-event (for browser-guest focus); the renderer keeps handlers for local focus.
 
       const matchShortcut = (actionId: KeybindingActionId): boolean =>
         keybindingMatchesAction(actionId, input, shortcutPlatform, keybindings, {
@@ -1690,9 +1475,7 @@ function App(): React.JSX.Element {
       }
 
       if (matchShortcut('sidebar.search.toggle') && canRevealRightSidebar) {
-        // Why: when focus is inside the file explorer and a folder is selected,
-        // Cmd/Ctrl+Shift+F means "Find in Folder" — seed the include pattern
-        // with that folder instead of treating the chord as a text-search seed.
+        // With a folder selected in the explorer, Cmd/Ctrl+Shift+F means "Find in Folder" — seed the include pattern with it, not a text search.
         const selectedFolderRelativePath =
           document.activeElement instanceof Element
             ? selectedExplorerFolderRelativePath(document.activeElement)
@@ -1715,8 +1498,7 @@ function App(): React.JSX.Element {
         }
       }
 
-      // Why: an empty floating workspace has no tab to close; Cmd/Ctrl+W
-      // should hide that transient overlay before underlying app surfaces act.
+      // An empty floating workspace has no tab to close, so Cmd/Ctrl+W hides the overlay before other surfaces act.
       if (
         keybindingMatchesAction('tab.close', input, shortcutPlatform, keybindings, {
           context: 'app'
@@ -1731,11 +1513,7 @@ function App(): React.JSX.Element {
         return
       }
 
-      // Why: when the floating workspace is closed, its own keydown handler is
-      // unmounted and cannot claim Cmd+Opt+Shift+A. Honor the maximize chord
-      // here by opening the panel with a one-shot intent so it mounts straight
-      // into the maximized state. While the panel is open, this is a no-op: the
-      // panel's handler owns the maximize/restore toggle.
+      // Floating panel closed → its keydown handler is gone, so honor the maximize chord here by opening it pre-maximized (no-op while it's open).
       if (
         !floatingTerminalOpen &&
         matchShortcut('floatingWorkspace.maximize') &&
@@ -1747,29 +1525,19 @@ function App(): React.JSX.Element {
         return
       }
 
-      // Why: keep this guard. TipTap's Cmd+B bold binding depends on the
-      // window-level handler *not* toggling the sidebar when focus lives in an
-      // editable surface. The main-process before-input-event already carves out
-      // Cmd+B for the markdown editor (see createMainWindow.ts +
-      // docs/markdown-cmd-b-bold-design.md), but this renderer-side fallback
-      // still covers the blur→press IPC race and any non-carved editable surface.
+      // Skip editable surfaces so TipTap's Cmd+B bold works; this renderer-side fallback covers the blur→press IPC race (docs/markdown-cmd-b-bold-design.md).
       if (isEditableTarget(input.target)) {
         return
       }
 
-      // Why: xterm's helper textarea is intentionally not a generic editable
-      // target, but floating-terminal SSH/tmux control chords must still reach
-      // the terminal instead of app-level chrome shortcuts.
+      // Let floating-terminal SSH/tmux control chords reach the terminal (xterm's helper textarea isn't a generic editable target).
       if (isFloatingWorkspaceTerminalInputTarget(input.target)) {
         return
       }
 
-      // Cmd/Ctrl+Alt+Arrow — worktree history back/forward. This stays before
-      // right-sidebar shortcuts because it is navigation, not sidebar reveal.
+      // Cmd/Ctrl+Alt+Arrow worktree history — kept before right-sidebar shortcuts because it's navigation, not sidebar reveal.
       if (matchShortcut('worktree.history.back') || matchShortcut('worktree.history.forward')) {
-        // Why: Back/Forward traverse mixed worktree + page visits, so the
-        // shortcut is active wherever the titlebar button cluster is (terminal
-        // or stack-backed pages). Still suppressed in Settings.
+        // Back/Forward is live wherever the titlebar cluster shows (worktree + page visits), but suppressed in Settings.
         if (creationLayoutActive || !shouldShowWorktreeHistoryControls(activeView)) {
           return
         }
@@ -1783,11 +1551,7 @@ function App(): React.JSX.Element {
         return
       }
 
-      // Why: only short-circuit chords the floating panel's own keydown
-      // handler claims (Cmd/Ctrl+T, Cmd/Ctrl+W, Cmd/Ctrl+Shift+B/M). Other
-      // app-level mod shortcuts (B, L, Shift+E/F/G) have no panel-level
-      // counterpart, so suppressing them here would silently no-op when
-      // focus lives inside the floating panel.
+      // Only short-circuit chords the floating panel itself claims; suppressing others here would silently no-op them when focus is in the panel.
       const floatingWorkspaceFocused = isFloatingWorkspacePanelFocused()
       if (floatingWorkspaceFocused) {
         if (
@@ -1808,9 +1572,7 @@ function App(): React.JSX.Element {
         return
       }
 
-      // Toggle the "show sleeping workspaces" sidebar filter without opening the
-      // filters menu (issue #5209). When revealing them, open the left sidebar
-      // so the now-visible sleeping worktrees are actually reachable.
+      // Toggle the sleeping-workspaces filter without the filters menu (issue #5209); open the sidebar when revealing so they're reachable.
       if (matchShortcut('sidebar.sleepingWorkspaces.toggle')) {
         input.preventDefault()
         notifyTerminalCapture('sidebar.sleepingWorkspaces.toggle')
@@ -1823,10 +1585,7 @@ function App(): React.JSX.Element {
         return
       }
 
-      // Why: rename the active terminal tab. Cmd+R is free in the app/terminal
-      // focus zone because the browser pane owns its own Cmd+R reload and that
-      // focus never reaches this renderer-window handler. Only terminal tabs
-      // have an inline title editor, so other active tab types fall through.
+      // Cmd+R renames the active terminal tab — free here because the browser pane owns its own reload; non-terminal tabs fall through (no inline title editor).
       if (workspaceChromeActive && !floatingWorkspaceFocused && matchShortcut('tab.rename')) {
         const store = useAppStore.getState()
         if (store.activeTabType === 'terminal' && store.activeTabId) {
@@ -1837,9 +1596,7 @@ function App(): React.JSX.Element {
         }
       }
 
-      // Why: open the active worktree's inline title editor. Open/reveal it
-      // first so the card is mounted and visible even when sidebar filters or
-      // collapse state would otherwise hide it.
+      // Open/reveal the worktree card first so its inline title editor is mounted even when filters or collapse state would hide it.
       if (
         workspaceChromeActive &&
         !floatingWorkspaceFocused &&
@@ -1863,14 +1620,9 @@ function App(): React.JSX.Element {
         return
       }
 
-      // Why: Cmd/Ctrl+N is handled via the main-process before-input-event
-      // allowlist (see window-shortcut-policy.ts / useIpcEvents.ts) so it works
-      // globally — including when focus lives inside the markdown rich editor
-      // (contentEditable) or a browser guest webContents, both of which bypass
-      // this renderer-side window keydown listener.
+      // Cmd/Ctrl+N is handled in the main-process before-input-event allowlist (window-shortcut-policy.ts), not here, so it fires even inside editors/browser guests.
 
-      // Why: full-page navigation surfaces should not reveal the right sidebar;
-      // they are designed as distraction-free content areas.
+      // Full-page navigation surfaces own the whole content area, so don't reveal the right sidebar.
       if (matchShortcut('view.tasks') && activeView !== 'settings') {
         const store = useAppStore.getState()
         if (store.repos.some((repo) => isGitRepoKind(repo))) {
@@ -1909,11 +1661,7 @@ function App(): React.JSX.Element {
         return
       }
 
-      // Cmd/Ctrl+Shift+G — toggle right sidebar / source control tab.
-      // Skip when terminal search is open — Cmd+Shift+G means "find previous"
-      // in that context (handled by keyboard-handlers.ts). Both listeners share
-      // the window capture phase and registration order can vary with React
-      // effect re-runs, so a DOM check is the reliable coordination mechanism.
+      // Cmd/Ctrl+Shift+G — source control tab; skip when terminal search is open (there it means "find previous"). DOM check because capture-phase order varies.
       if (matchShortcut('sidebar.sourceControl.toggle')) {
         if (document.querySelector('[data-terminal-search-root]')) {
           return
@@ -1933,9 +1681,7 @@ function App(): React.JSX.Element {
         return
       }
 
-      // Cmd+Shift+I — toggle right sidebar / ports tab (macOS only).
-      // Why: Ctrl+Shift+I is the built-in DevTools accelerator on Windows/Linux;
-      // intercepting it would break an essential developer tool.
+      // Cmd+Shift+I — ports tab (macOS only); Ctrl+Shift+I is the DevTools accelerator on Windows/Linux.
       if (matchShortcut('sidebar.ports.toggle')) {
         input.preventDefault()
         notifyTerminalCapture('sidebar.ports.toggle')
@@ -2038,23 +1784,14 @@ function App(): React.JSX.Element {
 
   const resolvedMountedLazyModalIds = resolveMountedLazyModalIds(activeModal, mountedLazyModalIds)
   if (resolvedMountedLazyModalIds !== mountedLazyModalIds) {
-    // Why: lazy-load these modals only after first use, then keep them mounted
-    // so repeat opens preserve their local state and avoid re-fetch flashes.
+    // Why: lazy-load modals on first use, then keep them mounted so repeat opens preserve state and avoid re-fetch flashes.
     setMountedLazyModalIds(new Set(resolvedMountedLazyModalIds))
   }
 
-  // Why: extracted so both the full-width titlebar (settings/landing) and
-  // the sidebar-width left header (workspace view) can share the same
-  // controls without duplicating the agent badge popover.
+  // Why: extracted so the full-width titlebar and the sidebar-width left header share these controls without duplicating the agent badge popover.
   const titlebarLeftControls = (
-    // Why: measure the ENTIRE row (traffic-light pad + sidebar toggle + agent
-    // badge + back/forward group) so the sidebar-collapse spacer in
-    // TabGroupPanel reserves enough width to clear the full floating
-    // `titlebar-left`. Measuring only the inner control cluster left the
-    // back/forward arrows hanging over the first tab when the sidebar was
-    // collapsed (Cmd+B), producing a half-occluded, non-scrollable tab strip.
-    // Why: collapsed workspace mode floats inside a w-0 sidebar wrapper; w-max
-    // prevents Windows Chromium from shrinking the app name down to one glyph.
+    // Why: measure the ENTIRE row so TabGroupPanel's collapse spacer reserves enough width; measuring only the inner cluster left back/forward over the first tab.
+    // Why: collapsed mode floats in a w-0 wrapper; w-max stops Windows Chromium from shrinking the app name to one glyph.
     <div
       ref={titlebarLeftControlsRef}
       className={`flex h-full shrink-0 items-center${
@@ -2065,10 +1802,7 @@ function App(): React.JSX.Element {
         {isMac && !isFullScreen ? (
           <div className="titlebar-traffic-light-pad" />
         ) : hasCustomTitleBar ? (
-          /* Why: on Windows/Linux the native title bar is removed, so we render
-             the Orca logo as a non-interactive identity anchor and a ··· button
-             that pops up the application menu (the same menu revealed by Alt
-             on the default autoHideMenuBar). */
+          /* Why: Windows/Linux remove the native title bar, so render the logo plus a ··· button that pops the application menu (as Alt does). */
           <>
             <img src={logo} alt="" aria-hidden className="titlebar-logo" />
             <Tooltip>
@@ -2135,12 +1869,9 @@ function App(): React.JSX.Element {
           </Tooltip>
         )}
       </div>
-      {/* Why: Back/Forward traverse mixed worktree + page history, so the
-          cluster is shown wherever the history shortcut is live. Hidden in
-          Settings and non-stack page views. */}
+      {/* Why: Back/Forward span worktree + page history, so show the cluster wherever the shortcut is live (hidden in Settings/non-stack views). */}
       {shouldShowWorktreeHistoryControls(activeView) && (
-        // Why: when the workspace sidebar is collapsed, this header shrink-wraps
-        // and ml-auto has no spare width; keep a fixed gutter before Back.
+        // With the sidebar collapsed the header shrink-wraps and ml-auto has no spare width, so keep a fixed gutter before Back.
         <div className="ml-auto mr-3 flex items-center pl-2">
           <Tooltip>
             <TooltipTrigger asChild>
@@ -2228,12 +1959,9 @@ function App(): React.JSX.Element {
         </Tooltip>
       )}
       {showProfileSwitcherInTopRight ? <OrcaProfileSwitcher /> : null}
-      {/* Why: when the right sidebar is open, its own header renders
-      an identical close button — hide this copy so only one is
-      visible at a time. */}
+      {/* Why: the open right sidebar's header renders its own close button, so hide this duplicate. */}
       {!rightSidebarOpen && rightSidebarToggle}
-      {/* Why: reserve space so content is not obscured by the
-      fixed-position window-controls overlay on Windows/Linux. */}
+      {/* Why: reserve space so the Windows/Linux window-controls overlay doesn't obscure content. */}
       {hasCustomTitleBar && <div className="window-controls-titlebar-spacer" />}
     </>
   )
@@ -2264,13 +1992,9 @@ function App(): React.JSX.Element {
       style={
         {
           '--collapsed-sidebar-header-width': `${collapsedSidebarHeaderWidth}px`,
-          // Why: consumed by anything that needs to avoid the fixed-position
-          // window-controls overlay on Windows/Linux (floating sidebar toggle,
-          // right sidebar header, etc.) without hardcoding 138px in multiple
-          // places.
+          // Shared so surfaces can avoid the Windows/Linux window-controls overlay without hardcoding 138px everywhere.
           '--window-controls-width': hasCustomTitleBar ? '138px' : '0px',
-          // Why: consumed by the side-position activity bar to push icons below
-          // the fixed-position window-controls overlay on Windows/Linux.
+          // Side-position activity bar uses this to push icons below the Windows/Linux window-controls overlay.
           '--window-controls-height': hasCustomTitleBar ? '36px' : '0px'
         } as React.CSSProperties
       }
@@ -2279,12 +2003,10 @@ function App(): React.JSX.Element {
         <ConfirmationDialogProvider>
           <LinkRoutingPreferenceDialogProvider>
             <WorkspacePortScanner enabled={workspaceSessionReady} />
-            {/* Why: leaf-mounted retention sync keeps agent-status retention
-            subscriptions from re-rendering the App tree. */}
+            {/* Why: leaf-mounted retention sync keeps agent-status subscriptions out of the App render tree. */}
             <RetainedAgentsSyncGate />
             <AgentHibernationGate />
-            {/* Why: workspace activation is a hot path; including activeWorktreeId
-            in reset keys remounts whole surfaces during wake. */}
+            {/* Why: workspace activation is a hot path; activeWorktreeId in reset keys would remount whole surfaces during wake. */}
             <RecoverableRenderErrorBoundary
               boundaryId="app.workspace-shell"
               surface="workspace-shell"
@@ -2296,16 +2018,9 @@ function App(): React.JSX.Element {
               )}
             >
               <div className="flex flex-row flex-1 min-h-0 overflow-hidden">
-                {/* Why: the non-workspace titlebar lives inside this left+center
-              wrapper so it does not span over the right-sidebar column —
-              when the right sidebar is open, its own header anchors at the
-              top alongside the titlebar instead of being pushed below it. */}
+                {/* Why: keep the non-workspace titlebar inside this left+center wrapper so it doesn't span over the right-sidebar column. */}
                 <div className="flex flex-col flex-1 min-w-0 min-h-0">
-                  {/* Why: in workspace view (split groups always enabled), the
-                full-width titlebar is removed so tab groups + terminal extend
-                to the top of the window. Left titlebar controls move to a
-                header above the sidebar. Settings, landing, and the tasks
-                page keep the titlebar. */}
+                  {/* Why: workspace view drops the full-width titlebar so tab groups extend to the top; settings/landing/tasks keep it. */}
                   {!leftTitlebarChromeLayout.shouldMount ? (
                     <div className="titlebar">
                       <div className="flex items-center shrink-0 mr-2">{titlebarLeftControls}</div>
@@ -2315,52 +2030,28 @@ function App(): React.JSX.Element {
                   <div className="flex flex-row flex-1 min-h-0 overflow-hidden">
                     {showSidebar ? (
                       leftTitlebarChromeLayout.shouldMount ? (
-                        /* Why: left column wraps the sidebar with a titlebar-height
-                     header above it. The header holds the same controls
-                     (traffic lights, sidebar toggle, "Orca" title, agent badge)
-                     that the full-width titlebar held while the center and right
-                     columns keep their own top strips at the same 36px height.
-                     When the sidebar is collapsed, take this header out of flex
-                     layout so the terminal/editor reclaim the left edge instead of
-                     leaving behind a content-width blank strip. */
+                        /* Why: when the sidebar is collapsed, take this titlebar-height header out of flex layout so the terminal/editor reclaim the left edge. */
                         <div
                           className={`flex min-h-0 flex-col shrink-0${sidebarOpen ? '' : ' relative w-0 overflow-visible'}`}
                         >
                           <div
-                            // Why: when the sidebar is collapsed, titlebar-left floats
-                            // absolutely on top of the center column's own `border-l`
-                            // (see TabGroupSplitLayout), occluding that seam. Add a
-                            // `border-r` in the floating state so the vertical line
-                            // between the traffic-light/nav cluster and the tab strip
-                            // stays visible in both states. w-max keeps the floating
-                            // header sized to its own controls instead of the w-0
-                            // sidebar wrapper.
+                            // Why: floating titlebar-left occludes the center column's border-l seam; border-r restores that line, w-max sizes it to its own controls.
                             className={`titlebar-left${
                               leftTitlebarChromeLayout.isFloating
                                 ? ' titlebar-left-floating absolute top-0 left-0 z-10 w-max border-r border-border'
                                 : ''
                             }`}
                             style={{
-                              // Why: custom sidebar appearances are scoped to the sidebar
-                              // root, so mirror those variables onto the open header that
-                              // visually belongs to the same left-column panel.
+                              // Why: custom sidebar appearances are scoped to the sidebar root; mirror those vars onto the header in the same left-column panel.
                               ...(sidebarOpen ? leftSidebarStyle : undefined),
-                              // Why: the Sidebar resize hook updates the sidebar DOM width
-                              // directly during drag and only persists to Zustand on
-                              // mouseup. In workspace view, size this header from the
-                              // wrapper's live width so it tracks those in-flight resizes
-                              // instead of leaving a stale-width gap until the drag ends.
+                              // Why: size from the wrapper's live width so the header tracks in-flight drag resizes (persisted to Zustand only on mouseup).
                               width: sidebarOpen ? '100%' : undefined
                             }}
                           >
                             {titlebarLeftControls}
                           </div>
                           <div className="flex min-h-0 flex-1">
-                            {/* Why: the workspace-view wrapper adds a fixed 36px header
-                          above the sidebar. Without a flex-1/min-h-0 slot here,
-                          the sidebar falls back to its content height, so the
-                          worktree list loses its scroll viewport and the fixed
-                          bottom toolbar (including Add Project) gets pushed offscreen. */}
+                            {/* Why: flex-1/min-h-0 slot needed under the fixed 36px header, else the sidebar collapses to content height and loses its scroll viewport. */}
                             <RecoverableRenderErrorBoundary
                               boundaryId="sidebar.worktrees"
                               surface="sidebar"
@@ -2407,24 +2098,13 @@ function App(): React.JSX.Element {
                         <div className="titlebar">{titlebarMainStrip}</div>
                       ) : null}
                       <div className="relative flex flex-1 min-w-0 min-h-0 overflow-hidden">
-                        {/* Why: right sidebar toggle floats at the top-right of the center
-                    column so it's always accessible whether the right sidebar is
-                    open or closed. Match the RightSidebar header's 36px height and
-                    top-0 anchor so the icon's vertical center is identical between
-                    open and closed states — otherwise toggling makes the icon jump
-                    a few pixels, which reads as layout jitter. */}
+                        {/* Why: match the RightSidebar header's 36px/top-0 so the toggle's vertical center is identical open vs closed — else the icon jitters. */}
                         {workspaceChromeActive && !rightSidebarOpen && (
                           <div
                             className="absolute top-0 z-10 flex items-center h-[36px]"
                             style={
                               {
-                                // Why: right: var(--window-controls-width) is the single
-                                // mechanism that keeps the toggle clear of the
-                                // fixed-position window-controls overlay on custom desktop
-                                // chrome (138px) and sits at the right edge otherwise (0px).
-                                // No internal spacer needed — adding one would push the button
-                                // a further 138px to the left and cover the pane-actions
-                                // Ellipsis button with an un-clickable div.
+                                // Why: --window-controls-width keeps the toggle clear of the fixed window-controls overlay (138px on custom chrome, 0px otherwise); no internal spacer — one would cover the pane-actions Ellipsis button with an unclickable div.
                                 right: 'var(--window-controls-width)',
                                 WebkitAppRegion: 'no-drag'
                               } as React.CSSProperties
@@ -2508,10 +2188,7 @@ function App(): React.JSX.Element {
                     </div>
                   </div>
                 </div>
-                {/* Why: keep the right-sidebar shell mounted for layout stability.
-              Its heavy panels disconnect while closed so workspace wake stays
-              responsive. Unmount on the tasks view since that surface is
-              intentionally distraction-free. */}
+                {/* Why: keep the shell mounted for layout stability (heavy panels disconnect while closed); unmount on the distraction-free tasks view. */}
                 {showRightSidebarControls ? (
                   <RecoverableRenderErrorBoundary
                     boundaryId="right-sidebar"
@@ -2574,8 +2251,7 @@ function App(): React.JSX.Element {
                 </RecoverableRenderErrorBoundary>
               </Suspense>
             ) : null}
-            {/* Why: workspace creation is a core action; keeping it in the
-            entry bundle avoids stale/corrupt lazy chunks stranding users at Create. */}
+            {/* Why: keep in the entry bundle so a stale/corrupt lazy chunk can't strand users at Create. */}
             {activeModal === 'new-workspace-composer' ? (
               <RecoverableRenderErrorBoundary
                 boundaryId="modal.new-workspace-composer"
@@ -2597,8 +2273,7 @@ function App(): React.JSX.Element {
                   <AddRepoDialog />
                 </RecoverableRenderErrorBoundary>
               ) : null}
-              {/* Why: Settings can start Add Project without mounting Sidebar,
-              so Add Project handoff dialogs must share the root host. */}
+              {/* Why: Settings can start Add Project without Sidebar, so its handoff dialogs must share the root host. */}
               {activeModal === 'confirm-non-git-folder' ? (
                 <RecoverableRenderErrorBoundary
                   boundaryId="modal.confirm-non-git-folder"
@@ -2630,8 +2305,7 @@ function App(): React.JSX.Element {
                 </RecoverableRenderErrorBoundary>
               ) : null}
             </Suspense>
-            {/* Why: root overlays can render Radix <Tooltip>s; keep them inside
-            the shared provider so lazy surfaces mount safely from any entry point. */}
+            {/* Why: root overlays can render Radix <Tooltip>s; keep inside the shared provider so lazy surfaces mount from any entry point. */}
             <Suspense fallback={null}>
               {resolvedMountedLazyModalIds.has('workspace-cleanup') ? (
                 <RecoverableRenderErrorBoundary
@@ -2706,9 +2380,7 @@ function App(): React.JSX.Element {
                 <ContextualTourOverlay />
               </Suspense>
             ) : null}
-            {/* Why: mount PetOverlay only after persisted UI hydration, with
-          both independent pet toggles allowing it; otherwise a hidden pet
-          flashes while the store still has default visibility. */}
+            {/* Why: mount only after UI hydration, else a hidden pet flashes while the store still holds default visibility. */}
             {renderPetOverlay ? (
               <Suspense fallback={null}>
                 <RecoverableRenderErrorBoundary
@@ -2750,13 +2422,7 @@ function App(): React.JSX.Element {
               <StarNagToastHost />
             </RecoverableRenderErrorBoundary>
             <StarNagAgentValueMomentObserver />
-            {/* Why: the existing-user opt-in banner mounts at App root so it
-          renders once per renderer session, not per view. It gates
-          internally on the cohort markers populated by the migration,
-          so it only shows for users who installed before the telemetry
-          release and have not yet resolved consent. New users get no
-          first-launch surface — see telemetry-plan.md §First-launch
-          experience. */}
+            {/* Why: mount at App root to render once per session; internal cohort gate limits it to pre-telemetry users — see telemetry-plan.md §First-launch experience. */}
             <RecoverableRenderErrorBoundary
               boundaryId="overlay.telemetry-first-launch"
               surface="overlay"
@@ -2859,8 +2525,7 @@ function App(): React.JSX.Element {
             >
               <RecentTabSwitcher />
             </RecoverableRenderErrorBoundary>
-            {/* Why: the dialog hosts a live terminal pane, which requires the
-                link-routing preference context; mounting outside crashes it. */}
+            {/* Why: hosts a live terminal pane needing the link-routing preference context; mounting outside crashes it. */}
             <RecoverableRenderErrorBoundary
               boundaryId="overlay.skill-freshness-update-dialog"
               surface="overlay"
@@ -2874,10 +2539,7 @@ function App(): React.JSX.Element {
       <Toaster closeButton toastOptions={{ className: 'font-sans text-sm' }} />
       <SkillFreshnessNudge />
       <PinnedTabCloseDialog />
-      {/* Why: rendered last so it sits after all -webkit-app-region:drag elements
-          in DOM order. Electron's hit-test for drag regions is DOM-order-based and
-          ignores z-index — placing WindowControls earlier caused the drag region to
-          win, making the buttons unclickable. */}
+      {/* Why: Electron's drag-region hit-test is DOM-order-based (ignores z-index); render last so WindowControls stay clickable. */}
       {hasCustomTitleBar && <WindowControls />}
     </div>
   )
diff --git a/src/renderer/src/hooks/useAutoAckViewedAgent.ts b/src/renderer/src/hooks/useAutoAckViewedAgent.ts
index 2e3ed36e9f4..1e6052342ba 100644
--- a/src/renderer/src/hooks/useAutoAckViewedAgent.ts
+++ b/src/renderer/src/hooks/useAutoAckViewedAgent.ts
@@ -14,14 +14,10 @@ function resolveActiveLeafId(
 }
 
 /**
- * Pure helper used by the hook below — exported so the regression test for
- * the codex-row-stays-bold race (docs/codex-agent-row-bold-stuck.md) can
- * exercise the decision against a real test store without needing a DOM.
+ * Returns paneKeys to ack for the active tab/leaf; exported for the
+ * codex-row-bold regression test (docs/codex-agent-row-bold-stuck.md).
  *
- * Returns the list of paneKeys that should be acked given the active tab and
- * exact active leaf. Split tabs can host multiple agent panes, so equality on
- * `${tabId}:${leafId}` is required; tab-prefix matching would mark siblings
- * read without ever displaying them.
+ * Why: split tabs host multiple agent panes, so match exact `${tabId}:${leafId}` — a tab-prefix match would ack undisplayed siblings.
  */
 export function computeAutoAckTargets(
   state: {
@@ -40,9 +36,7 @@ export function computeAutoAckTargets(
   const liveEntry = state.agentStatusByPaneKey[targetKey]
   if (liveEntry) {
     const ackAt = state.acknowledgedAgentsByPaneKey[targetKey] ?? 0
-    // Why: use stateStartedAt (not updatedAt) so tool/prompt pings within the
-    // same state don't re-trigger ack work — keeping the comparison aligned
-    // with WorktreeCardAgents' is-unvisited rule.
+    // Why: compare stateStartedAt (not updatedAt) so same-state pings don't re-trigger ack, matching WorktreeCardAgents' is-unvisited rule.
     if (ackAt < liveEntry.stateStartedAt) {
       targets.push(targetKey)
     }
@@ -93,8 +87,7 @@ export function shouldClearViewedAgentWorktreeUnread(
     return true
   }
 
-  // Why: worktree unread is coarse. Do not clear it for the visible pane if a
-  // hidden tab/pane in the same worktree still owns unread agent attention.
+  // Why: worktree unread is coarse — don't clear for the visible pane if a hidden tab/pane in the same worktree still owns unread attention.
   for (const paneKey of Object.keys(state.unreadAgentCompletionPanes)) {
     if (args.paneKeysToClear.has(paneKey)) {
       continue
@@ -143,8 +136,7 @@ export function acknowledgeViewedAgentAttention(
     state.acknowledgeAgents(args.paneKeys)
   }
   if (args.activeWorktreeId) {
-    // Why: focus-return auto-ack means the selected agent is now visible;
-    // clear the Dock-driving worktree unread state without requiring a click.
+    // Why: the selected agent is now visible, so clear the Dock-driving worktree unread without a click.
     state.clearWorktreeUnread(args.activeWorktreeId)
   }
   state.clearTerminalTabUnread(args.activeTabId)
@@ -153,57 +145,12 @@ export function acknowledgeViewedAgentAttention(
   }
 }
 
-// Why: an agent row counts as "already seen" when the user is actually looking
-// at the tab it lives on. Without this effect, ack only fires via an explicit
-// click in the dashboard — which misses the common case where the user is
-// already on the terminal tab when the agent finishes or blocks. That leaves
-// the dashboard bolded and Dock badge raised for an event the user literally
-// just watched happen.
-//
-// The effect subscribes directly to the store (not via React selectors) so it
-// sees every state change with no re-render amplification up the component
-// tree. A reference-equality guard inside the callback bails out immediately
-// when none of the seven slices we care about (activeView, activeTabId,
-// agentStatusByPaneKey, retainedAgentsByPaneKey, acknowledgedAgentsByPaneKey,
-// terminalLayoutsByTabId, unreadAgentCompletionPanes)
-// have changed — so the Object.entries walk only runs for updates
-// that could legitimately affect the ack decision.
-//
-// It acks whenever:
-//   - activeView is 'terminal' (the user isn't on Settings/Tasks), AND
-//   - activeTabId identifies a live tab, AND
-//   - at least one agentStatusByPaneKey entry OR retainedAgentsByPaneKey
-//     entry matches the active tab+leaf AND its ackAt < stateStartedAt, OR
-//     the active pane has unread agent-completion attention.
-//
-// Why both maps: the inline-agents list renders the union of live + retained
-// rows (see useWorktreeAgentRows), so the ack scan must too. Without the
-// retained walk, a `done` row whose live entry was torn down by the
-// title-revert path (see pty-connection.ts:onAgentExited) migrates to the
-// retained map carrying a fresh `done.stateStartedAt` and never gets
-// auto-acked — leaving the inline row bold forever even while the user
-// stares at the terminal. Codex hits this race reliably because its TUI
-// reverts to a shell title within milliseconds of `Stop`.
-//
-// The ack ALSO requires the OS window to be visible and focused
-// (document.visibilityState === 'visible' && document.hasFocus()) —
-// otherwise a transition that arrives while the user is away would silently
-// clear the bold-until-viewed signal for an event they never saw. A
-// visibilitychange / focus listener re-runs the scan when the user returns
-// so any transitions that failed the gate while away get acked the moment
-// focus actually comes back.
-//
-// We ack ALL matching panes in one call (a tab can host split panes, each
-// with its own paneKey), then clear the active unread surfaces. Returning focus
-// to a visible agent counts as viewing it, without requiring a click/keystroke.
+// Auto-ack an agent row as "seen" when the user is already on its tab, so the dashboard/Dock don't stay bold for an event they watched happen.
+// Scans live + retained maps: Codex's title-revert (pty-connection.ts:onAgentExited) migrates `done` rows to retained mid-race — see docs/codex-agent-row-bold-stuck.md.
 export function useAutoAckViewedAgent(): void {
   useEffect(() => {
-    // Why: the root zustand store is created with plain `create()` (no
-    // subscribeWithSelector middleware), so subscribe has no selector form.
-    // Track the slice references we actually depend on and early-return on
-    // unrelated updates — terminal output, tab state, settings, etc. would
-    // otherwise invoke the scan on every store change. Initialize to
-    // `undefined` so the first call always runs at least once.
+    // Why: the store uses plain create() (no subscribeWithSelector), so manually track the slices we depend on to skip unrelated updates.
+    // Init to undefined so the first maybeAck() (on mount) always passes the ref guard and scans.
     let lastActiveView: unknown = undefined
     let lastActiveTabId: unknown = undefined
     let lastAgentStatus: unknown = undefined
@@ -229,12 +176,7 @@ export function useAutoAckViewedAgent(): void {
       if (s.activeView !== 'terminal') {
         return
       }
-      // Why: the auto-ack represents "the user saw this row" — but tab-active is
-      // only a proxy. If the OS window is hidden, minimized, or another app has
-      // focus, the user is demonstrably not looking at the inline agents list
-      // even with the terminal tab set. Without this gate, an agent finishing
-      // while the user is away silently clears the bold-until-viewed signal and
-      // the user returns to a card with no indication anything transitioned.
+      // Why: tab-active only proxies "seen"; gate on window visible+focused so away-time transitions don't silently clear the bold signal.
       if (typeof document !== 'undefined') {
         if (document.visibilityState !== 'visible') {
           return
@@ -248,13 +190,7 @@ export function useAutoAckViewedAgent(): void {
         return
       }
       const activeLeafId = resolveActiveLeafId(s, activeTabId)
-      // Why: advance the refs ONLY after all gates have passed — if the
-      // visibility gate (window hidden/unfocused or no activeTabId) caused an
-      // early return, leave the refs stale so the next call (e.g. triggered by
-      // the focus listener on return) sees a diff and actually runs the scan.
-      // Updating refs before the gates would consume the diff silently and
-      // leave the user returning to cards whose bold-until-viewed rows stay
-      // bold until some unrelated store change happens to bump the refs.
+      // Why: advance refs only after gates pass, else the diff is consumed and a gated-out transition never re-acks when focus returns.
       lastActiveView = s.activeView
       lastActiveTabId = s.activeTabId
       lastAgentStatus = s.agentStatusByPaneKey
@@ -283,18 +219,11 @@ export function useAutoAckViewedAgent(): void {
         })
       }
     }
-    // Why: run once on mount to catch the case where the app restores to a
-    // session whose current state already has agents on the visible tab.
+    // Why: run once on mount to catch a restored session that already has agents on the visible tab.
     maybeAck()
-    // Why: store.subscribe fires on every state change. The reference-
-    // equality guard above bails out immediately for the common case
-    // (terminal output, timers, etc.) so the Object.entries walk only runs
-    // when one of the five slices we read has actually changed.
+    // Subscribe to all store changes; the ref-equality guard above skips unrelated updates.
     const unsubscribe = useAppStore.subscribe(maybeAck)
-    // Why: focus/visibility don't flow through the zustand store, so a
-    // late-arriving transition that failed the gate above never re-evaluates
-    // when focus returns. Subscribe to the two DOM events so the ack scan
-    // reruns the moment the user is actually back on the window.
+    // Why: focus/visibility don't flow through zustand, so re-run the scan on these DOM events when focus returns.
     const onVisibility = (): void => maybeAck()
     const onFocus = (): void => maybeAck()
     document.addEventListener('visibilitychange', onVisibility)
diff --git a/src/renderer/src/hooks/useComposerState.ts b/src/renderer/src/hooks/useComposerState.ts
index 1c2e633a67c..accc351ca50 100644
--- a/src/renderer/src/hooks/useComposerState.ts
+++ b/src/renderer/src/hooks/useComposerState.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: this hook co-locates every piece of state
-the NewWorkspaceComposerCard reads or mutates, so both the full-page composer
-and the global quick-composer modal can consume a single unified source of
-truth without duplicating effects, derivation, or the create side-effect. */
+/* eslint-disable max-lines -- Why: co-locates all NewWorkspaceComposerCard state so the full-page composer and quick-composer modal share one source of truth. */
 /* oxlint-disable react-doctor/no-adjust-state-on-prop-change -- Why: composer state synchronizes selected repo metadata, setup policy, issue-command hooks, and provider link lookups from async runtime IPC. */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { toast } from 'sonner'
@@ -217,30 +214,18 @@ export type UseComposerStateOptions = {
   initialLinkedWorkItem?: LinkedWorkItemSummary | null
   initialTaskSourceContext?: TaskSourceContext | null
   initialWorkspaceStatus?: WorkspaceStatus
-  /** Seed the Start-from selection when the composer opens. Used by the
-   *  Create-from → Quick fallback path so a PR pick that needs a setup
-   *  decision still lands with the resolved PR head as the base branch. */
+  /** Seeds the Start-from selection on open; the Create-from → Quick fallback uses it so a PR pick lands with the resolved PR head as base. */
   initialBaseBranch?: string
-  /** Why: the full-page composer persists drafts so users can navigate away
-   *  without losing work; the quick-composer modal is transient and must not
-   *  clobber or leak that long-running draft. */
+  /** The full-page composer persists drafts across navigation; the transient quick-composer modal must not clobber that draft. */
   persistDraft: boolean
-  /** Invoked after a successful createWorktree. The caller usually closes its
-   *  surface here (palette modal, full page, etc.). */
+  /** Invoked after a successful createWorktree; the caller usually closes its surface (palette modal, full page, etc.). */
   onCreated?: () => void
-  /** Optional external repoId override — used by TaskPage's work-item list
-   *  which drives repo selection from the page header, not the card. */
+  /** External repoId override — used by TaskPage's work-item list, which drives repo selection from the page header, not the card. */
   repoIdOverride?: string
   onRepoIdOverrideChange?: (value: string) => void
-  /** Telemetry surface that opened this composer. Threaded into
-   *  `createWorktree` so `workspace_created.source` reflects the actual
-   *  entry point (Cmd+J palette → `command_palette`, sidebar buttons →
-   *  `sidebar`, keyboard shortcut → `shortcut`). Omitted callers default
-   *  to `unknown` at the IPC boundary. */
+  /** Telemetry surface that opened this composer; threaded into createWorktree so workspace_created.source reflects the entry point. Defaults to unknown. */
   telemetrySource?: WorkspaceCreateTelemetrySource
-  /** Quick-create launches a blank/draft agent session and does not run
-   *  issueCommand automation, so it can skip the issue-command probe that the
-   *  full composer needs for linked-item prompt previews. */
+  /** Quick-create skips the issueCommand probe (no automation), which the full composer needs for linked-item prompt previews. */
   enableIssueAutomation?: boolean
   createGateMode?: 'full' | 'quick'
 }
@@ -283,24 +268,19 @@ export type ComposerCardProps = {
   ) => void
   smartNameSelection: SmartWorkspaceNameSelection | null
   onClearSmartNameSelection: () => void
-  /** True when the selected source is an existing LOCAL branch that can be
-   *  reused (checked out) instead of branched off — gates the reuse checkbox. */
+  /** True when the selected source is an existing LOCAL branch that can be reused (checked out) — gates the reuse checkbox. */
   canReuseSelectedBranch: boolean
-  /** Whether the selected existing local branch will be reused (checked out)
-   *  rather than used as the base for a new branch. */
+  /** Whether the selected existing local branch is reused (checked out) rather than branched from. */
   reuseSelectedBranch: boolean
   onReuseSelectedBranchChange: (next: boolean) => void
-  /** Whether the "create multiple" toggle is shown — worktree (git) targets
-   *  only; folder-workspace targets create-and-close as before. */
+  /** Whether the "create multiple" toggle shows — worktree (git) targets only; folder workspaces create-and-close. */
   showCreateMultiple: boolean
-  /** When on, the modal stays open after each create and resets identity fields
-   *  so the user can create several worktrees in a row. */
+  /** When on, the modal stays open after each create and resets identity fields to allow creating several in a row. */
   createMultiple: boolean
   onCreateMultipleChange: (next: boolean) => void
   agentPrompt: string
   onAgentPromptChange: (value: string) => void
-  /** Rendered issueCommand template to preview inside the empty prompt
-   *  textarea when the user has linked a work item but not typed anything. */
+  /** Rendered issueCommand template previewed in the empty prompt when a work item is linked but nothing typed. */
   linkedOnlyTemplatePreview: string | null
   attachmentPaths: string[]
   getAttachmentLabel: (pathValue: string) => string
@@ -331,8 +311,7 @@ export type ComposerCardProps = {
   onNoteChange: (value: string) => void
   baseBranch: string | undefined
   onBaseBranchChange: (next: string | undefined) => void
-  /** Called when a PR is selected in the Start-from picker. Updates both
-   *  baseBranch and linkedWorkItem/linkedPR in one pass. */
+  /** Called when a PR is selected in the Start-from picker; updates baseBranch and linkedWorkItem/linkedPR in one pass. */
   onBaseBranchPrSelect: (
     baseBranch: string,
     item: GitHubWorkItem,
@@ -340,8 +319,7 @@ export type ComposerCardProps = {
     branchNameOverride?: string,
     compareBaseRef?: string
   ) => void
-  /** PR number selected via the Start-from picker (when applicable). Used so the
-   *  field can render "PR #N" copy. */
+  /** PR number selected via the Start-from picker, so the field can render "PR #N" copy. */
   baseBranchLinkedPrNumber: number | null
   /** Absolute path of the selected repo, used by Start-from picker for SWR. */
   selectedRepoPath: string | null
@@ -353,11 +331,9 @@ export type ComposerCardProps = {
   selectedRepoConnectInProgress: boolean
   onConnectSelectedRepo: () => Promise<void>
   branchesEnabled?: boolean
-  /** Transient inline hint shown next to the Start-from trigger after a repo
-   *  switch resets a prior selection (e.g. "was PR #8778"). Null when none. */
+  /** Inline hint next to the Start-from trigger after a repo switch resets a prior selection (e.g. "was PR #8778"). Null when none. */
   startFromResetHint: string | null
-  /** Warning shown when a selected fork PR has "Allow edits from maintainers"
-   *  off, so a push to the fork may be rejected. Null when none. */
+  /** Warning when a selected fork PR has "Allow edits from maintainers" off, so a push may be rejected. Null when none. */
   forkPushWarning: string | null
   setupConfig: SetupConfig | null
   setupControlsEnabled?: boolean
@@ -370,8 +346,7 @@ export type ComposerCardProps = {
   resolvedSetupDecision: 'run' | 'skip' | null
   createError: WorkspaceCreateErrorDisplay | null
   canUseSparseCheckout: boolean
-  /** Saved presets for the currently-selected repo. Empty array when no
-   *  presets exist or when the repo is remote. */
+  /** Saved sparse presets for the selected repo; empty when none exist or the repo is remote. */
   sparsePresets: SparsePreset[]
   /** ID of the selected sparse preset. Null means sparse checkout is off. */
   sparseSelectedPresetId: string | null
@@ -381,8 +356,7 @@ export type ComposerCardProps = {
 
 export type UseComposerStateResult = {
   cardProps: ComposerCardProps
-  /** Ref the consumer should attach to the composer wrapper so the global
-   *  Enter-to-submit handler can scope its behavior to the visible composer. */
+  /** Attach to the composer wrapper so the global Enter-to-submit handler scopes to the visible composer. */
   composerRef: React.RefObject<HTMLDivElement | null>
   onComposerNodeChange: (node: HTMLDivElement | null) => void
   promptTextareaRef: React.RefObject<HTMLTextAreaElement | null>
@@ -391,8 +365,7 @@ export type UseComposerStateResult = {
   submitQuick: (agent: TuiAgent | null) => Promise<void>
   /** Invoked by the Enter handler to re-check whether submission should fire. */
   createDisabled: boolean
-  /** Selects the repo a nested Add Project flow just added, clearing any
-   *  folder-group target so the composer lands on the new project. */
+  /** Selects the repo a nested Add Project flow just added, clearing any folder-group target so the composer lands on it. */
   selectAddedProjectRepo: (repoId: string) => void
 }
 
@@ -473,8 +446,7 @@ export function resolveSmartGitHubCreateNames({
   nameIsAutoManaged: boolean
 }): { workspaceName: string; displayName: string | undefined } {
   if (resolutionKind === 'pr-start-point' && !nameIsAutoManaged && fallbackWorkspaceName) {
-    // Why: submit-time PR start-point resolution augments an already-linked PR;
-    // it must not reclaim a workspace name the user edited after selection.
+    // Why: submit-time PR start-point augments an already-linked PR; don't reclaim a name the user edited after selecting.
     return { workspaceName: fallbackWorkspaceName, displayName: undefined }
   }
   return { workspaceName: smartWorkspaceName, displayName: smartDisplayName }
@@ -530,20 +502,13 @@ export function getInitialAutoManagedWorkspaceName({
   initialName: string
   initialLinkedWorkItem?: LinkedWorkItemSummary | null
 }): string {
-  // Why: command-palette prefilled names are user input unless they exactly
-  // match the linked item seed Orca generated for a source selection.
+  // Why: a prefilled name counts as user input unless it exactly matches the linked-item seed Orca generated.
   const candidateName = draftName ?? initialName
   const seedName = getLinkedWorkItemSeedName(draftLinkedWorkItem ?? initialLinkedWorkItem)
   return candidateName && seedName && candidateName === seedName ? candidateName : ''
 }
 
-// Why: both the full-page TaskPage composer and the Cmd+J modal can be
-// mounted simultaneously. Without instance scoping, a single native file
-// drop fires every subscriber and duplicates attachments/prompt edits across
-// the background draft and the visible modal. Route drops to the
-// most-recently-mounted composer only — the modal stacks on top, so the
-// modal wins when both are present, and the page takes over once the modal
-// closes.
+// Why: page composer and Cmd+J modal can coexist, so route a native file drop to only the most-recently-mounted one, else it duplicates across both.
 const composerDropStack: symbol[] = []
 const EMPTY_SPARSE_PRESETS: SparsePreset[] = []
 
@@ -567,10 +532,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     initialProjectGroupId
   } = options
 
-  // Why: each `useAppStore(s => s.someAction)` registers its own equality
-  // check that React has to re-run on every store mutation. Consolidating
-  // all stable actions into a single useShallow subscription turns 11 checks
-  // per store update into one.
+  // Why: fold stable actions into one useShallow subscription so a store mutation runs one equality check instead of 11.
   const actions = useAppStore(
     useShallow((s) => ({
       setNewWorkspaceDraft: s.setNewWorkspaceDraft,
@@ -621,8 +583,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   const runtimeStatusByEnvironmentId = useAppStore((s) => s.runtimeStatusByEnvironmentId)
   const workspaceHostScope = useAppStore((s) => s.workspaceHostScope)
   const eligibleRepos = useMemo(() => getComposerEligibleRepos(repos), [repos])
-  // Why: a runtime-owned SSH repo (the active repo right after creating a per-workspace-env) is not
-  // eligible, so seed from its local same-project sibling instead of falling back to another project.
+  // Why: a runtime-owned SSH repo (active right after creating a per-workspace-env) is ineligible; seed from its local same-project sibling, not another project.
   const seedActiveRepoId = useMemo(
     () => resolveComposerActiveRepoId(repos, eligibleRepos, activeRepoId),
     [repos, eligibleRepos, activeRepoId]
@@ -634,9 +595,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   const draftProjectHostSetupId = persistDraft
     ? (newWorkspaceDraft?.projectHostSetupId ?? null)
     : null
-  // Why: Tasks can start work from Linear/Jira source contexts that are not
-  // repo-backed. Seed the run target from the logical project/source host so
-  // the modal does not silently fall back to the ambient active repo.
+  // Why: Tasks can start from non-repo Linear/Jira contexts; seed from the logical project/source host so the modal doesn't fall back to the active repo.
   const initialRunSeed = resolveInitialWorkspaceRunSeed({
     draftProjectId,
     draftHostId,
@@ -786,8 +745,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         )
     return getAgentLaunchPlatformForRepo(selectedRepo, projectRuntime)
   }, [activeRepoId, projects, repos, selectedRepo, settings, worktreesByRepo])
-  // Why: SSH remotes deploy the CLI shim as plain `orca`, so the Linux-only
-  // `orca-ide` rename must not be applied to remote launch commands.
+  // Why: SSH remotes deploy the CLI shim as plain `orca`, so the Linux-only `orca-ide` rename must not apply to remote launch commands.
   const selectedRepoIsRemote = selectedRepo ? repoIsRemote(selectedRepo) : false
   const selectedRepoStartupShell = resolveLocalWindowsAgentStartupShell({
     platform: selectedRepoAgentLaunchPlatform,
@@ -848,22 +806,16 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     if (!settings) {
       return settings
     }
-    // Why: composer probes and attachment uploads inspect the selected repo,
-    // even though workspace creation defaults still follow host scope.
+    // Why: probes and attachment uploads inspect the selected repo, even though creation defaults still follow host scope.
     return getSettingsForRepoRuntimeOwner(
       { repos: selectedRepo ? [selectedRepo] : [], settings },
       selectedRepo?.id ?? null
     )
   }, [selectedRepo, settings])
-  // Why: key the recipe load on the repo's stable identity, not the whole repo
-  // object. `updateRepo` (e.g. saving the setup-startup policy from this very
-  // composer, or a GitHub upstream backfill) replaces the selected repo object
-  // by reference; depending on the object would re-run this effect and silently
-  // reset the user's manually-chosen recipe via setSelectedEphemeralVmRecipeId(null).
+  // Why: key on repo id, not the repo object — updateRepo replaces it by reference and would re-run this effect, wiping the user's chosen recipe.
   const selectedRecipeRepoId = selectedRepo?.id ?? null
   const selectedRecipeRepoConnectionId = selectedRepo?.connectionId ?? null
-  // Why: the experimental toggle must hide the composer target and avoid probing
-  // repo recipes, since recipe discovery can surface setup errors for a hidden feature.
+  // Why: gate recipe probing on the experimental toggle, since discovery can surface setup errors for a hidden feature.
   const ephemeralVmsEnabled = settings?.experimentalEphemeralVms === true
   useEffect(() => {
     let cancelled = false
@@ -1065,10 +1017,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     }
     return initialLinkedWorkItem?.type === 'pr' ? initialLinkedWorkItem.number : null
   })
-  // Why: GitLab parallels of linkedIssue/linkedPR. Kept as separate state
-  // (rather than reusing the GitHub slots with a provider discriminator) so
-  // the existing GitHub auto-name / linked-badge / persistence code paths
-  // stay untouched.
+  // Why: GitLab parallels of linkedIssue/linkedPR, kept as separate state so existing GitHub auto-name/badge/persistence paths stay untouched.
   const [linkedGitLabIssue, setLinkedGitLabIssue] = useState<number | null>(() => {
     if (persistDraft && newWorkspaceDraft?.linkedGitLabIssue !== undefined) {
       return newWorkspaceDraft.linkedGitLabIssue
@@ -1096,33 +1045,22 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     Boolean(initialLinearBranchName)
   )
   const [smartNameMode, setSmartNameMode] = useState<SmartNameMode>('smart')
-  // Why (#5181): when the user picks an existing LOCAL branch, let them reuse it
-  // (check it out) instead of creating a new branch from it. `reuseEligibleBranch`
-  // is the local branch name eligible for reuse (null = not a reusable local
-  // branch, e.g. a remote-only ref or non-branch source); `reuseSelectedBranch`
-  // is the explicit checkbox value driving whether reuse actually happens.
+  // Why (#5181): reuseEligibleBranch = local branch name eligible for checkout-reuse (null if none); reuseSelectedBranch = the checkbox that enacts it.
   const [reuseEligibleBranch, setReuseEligibleBranch] = useState<string | null>(null)
   const [reuseSelectedBranch, setReuseSelectedBranch] = useState(false)
   const [pushTarget, setPushTarget] = useState<GitPushTarget | undefined>(undefined)
-  // Why: when a repo switch wipes a prior Start-from selection, surface the
-  // reset inline (e.g. "was PR #8778") so the change is recoverable visually
-  // instead of slipping past the user. Cleared on any subsequent selection.
+  // Why: when a repo switch wipes a prior Start-from selection, surface the reset inline (e.g. "was PR #8778") so it doesn't slip past the user.
   const [startFromResetHint, setStartFromResetHint] = useState<string | null>(null)
-  // Why: a fork PR with "Allow edits from maintainers" off can't be pushed to;
-  // warn (but don't block) so the maintainer isn't surprised by a rejected push.
+  // Why: a fork PR with "Allow edits from maintainers" off can't be pushed to; warn (don't block) so a rejected push isn't a surprise.
   const [forkPushWarning, setForkPushWarning] = useState<string | null>(null)
   const disabledTuiAgentKey = (settings?.disabledTuiAgents ?? []).join('\u0000')
   const disabledTuiAgents = useMemo<TuiAgent[]>(
     () => settings?.disabledTuiAgents ?? [],
-    // Why: settings IPC round-trips clone arrays; agent availability only
-    // changes when the disabled-agent content changes.
+    // Why: settings IPC clones arrays, so key on the disabled-agent content, not the array ref.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [disabledTuiAgentKey]
   )
-  // Why: the long-form composer's agent selection is a required TuiAgent (not
-  // null/blank), so 'blank' preferences from global settings must collapse to
-  // the Claude default here — the blank-terminal affordance only lives in the
-  // quick-create flow.
+  // Why: the long-form composer requires a real TuiAgent, so a global 'blank' pref collapses to Claude (blank only exists in quick-create).
   const enabledCatalogAgents = useMemo(
     () =>
       filterEnabledTuiAgents(
@@ -1140,10 +1078,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   const [tuiAgent, setTuiAgent] = useState<TuiAgent>(
     persistDraft ? (newWorkspaceDraft?.agent ?? fallbackDefaultAgent) : fallbackDefaultAgent
   )
-  // Why: when the selected repo has a connectionId or runtime environment, read
-  // the per-host agent list instead of the local one. This ensures the Create
-  // Workspace dialog shows agents installed on the SSH host or paired runtime,
-  // not the local machine.
+  // Why: for a repo on an SSH host or runtime env, read the per-host agent list so the dialog shows the host's installed agents, not local.
   const connectionId = selectedRepoConnectionId
   const isRemote = typeof connectionId === 'string'
   const runtimeEnvironmentId = selectedRepoSettings?.activeRuntimeEnvironmentId?.trim() || null
@@ -1185,10 +1120,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   } | null>(null)
   const [creating, setCreating] = useState(false)
   const [createError, setCreateError] = useState<WorkspaceCreateErrorDisplay | null>(null)
-  // Why: when checked, a successful worktree create keeps the modal open and
-  // resets identity fields so the user can queue another worktree without
-  // reopening. Defaults off; the modal unmounts on close, so reopening always
-  // starts unchecked.
+  // Why: when checked, a successful create keeps the modal open and resets identity fields so the user can queue another worktree.
   const [createMultiple, setCreateMultiple] = useState(false)
   const [advancedOpen, setAdvancedOpen] = useState(
     persistDraft ? Boolean((newWorkspaceDraft?.note ?? '').trim()) : false
@@ -1216,16 +1148,12 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   const nameRef = useRef<string>(name)
   nameRef.current = name
   const branchAutoNameRef = useRef<string>('')
-  // Why: tracks the note value we auto-prefilled from a Start-from PR pick, so
-  // a subsequent PR change can replace it without clobbering user-typed text.
+  // Why: the note we auto-prefilled from a Start-from PR pick, so a later PR change can replace it without clobbering user-typed text.
   const lastAutoNoteRef = useRef<string>('')
-  // Why: read the latest note inside handleBaseBranchPrSelect without adding
-  // `note` to its deps (which would rebuild the callback on every keystroke).
+  // Why: let handleBaseBranchPrSelect read the latest note without adding it to deps (would rebuild the callback on every keystroke).
   const noteRef = useRef<string>(note)
   noteRef.current = note
-  // Why: PR selections in the Create From field resolve their checkout ref
-  // asynchronously. Submit must still know that the linked PR is a checkout
-  // source if Create is clicked before that resolver settles.
+  // Why: PR checkout refs resolve async, so submit can still see the linked PR as a checkout source if Create fires before the resolver settles.
   const smartGitHubPrStartPointSelectionRef = useRef<SmartGitHubPrStartPointSelection | null>(null)
   useEffect(() => {
     const clearAutoManagedName = (): void => {
@@ -1248,11 +1176,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   const promptTextareaRef = useRef<HTMLTextAreaElement | null>(null)
   const promptCaretFrameRef = useRef<number | null>(null)
   const nameInputRef = useRef<HTMLInputElement | null>(null)
-  // Why: the native-file-drop effect below subscribes once on mount and must
-  // read the latest agentPrompt when computing the caret-scoped insertion.
-  // Mirror the value into a ref so the listener sees fresh state without
-  // re-subscribing (which would reorder the composerDropStack and break
-  // multi-instance routing).
+  // Why: mirror agentPrompt into a ref so the once-mounted file-drop listener reads it fresh without re-subscribing, which would reorder composerDropStack.
   const agentPromptRef = useRef(agentPrompt)
   agentPromptRef.current = agentPrompt
   const connectionIdRef = useRef(connectionId)
@@ -1260,11 +1184,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   const selectedRepoConnectionIdRef = useRef(selectedRepoConnectionId)
   selectedRepoConnectionIdRef.current = selectedRepoConnectionId
 
-  // Why: resolves the selected repo's owner/repo slug so a PR URL pasted
-  // into the workspace name field can be matched against the current repo.
-  // Pasting a PR URL from a different repo would otherwise recover only the
-  // PR number, mislinking the worktree to an unrelated PR with the same
-  // number in the selected repo.
+  // Why: the selected repo's slug, used to confirm a pasted PR URL belongs to this repo before linking (else a same-numbered foreign PR mislinks).
   const [selectedRepoSlug, setSelectedRepoSlug] = useState<{ owner: string; repo: string } | null>(
     null
   )
@@ -1371,8 +1291,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
 
   const handleComposerNodeChange = useCallback(
     (node: HTMLDivElement | null): void => {
-      // Why: the queued caret restoration targets composer descendants and
-      // must be canceled as soon as the composer root leaves the DOM.
+      // Why: cancel the queued caret restoration once the composer root (its target's ancestor) leaves the DOM.
       if (!node) {
         cancelPromptCaretFrame()
       }
@@ -1446,10 +1365,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     () => normalizeSparseDirectoryLines(sparseDirectories),
     [sparseDirectories]
   )
-  // Why: a preset attribution should only ride along if what's about to be
-  // created actually equals the saved preset. If the user picked a preset and
-  // then edited the textarea, we want the worktree to be a "Custom" sparse
-  // checkout — not falsely tagged as the original preset.
+  // Why: only attribute the preset if the directories still match it; an edited selection is "Custom", not falsely tagged as the original preset.
   const effectivePresetId = useMemo(() => {
     if (!sparseSelectedPresetId) {
       return null
@@ -1487,21 +1403,14 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     () => (linkedIssue.trim() ? parseGitHubIssueOrPRNumber(linkedIssue) : null),
     [linkedIssue]
   )
-  // Why: when the user pastes a PR URL straight into the workspace name field
-  // (without picking from the source picker), `linkedPR` stays null and the
-  // worktree card has no PR strip. Recover the PR number from the name on
-  // submit so create-from-PR worktrees always link back to their PR.
+  // Why: a PR URL pasted into the name field (not picked) leaves linkedPR null; recover the number so the worktree still links back to its PR.
   const effectiveLinkedPR = useMemo<number | null>(() => {
     if (linkedPR !== null) {
       return linkedPR
     }
     const fromName = parseGitHubIssueOrPRLink(name)
     if (fromName && fromName.type === 'pr') {
-      // Why: only adopt a number when the URL's owner/repo matches the
-      // selected repo. Pasting `github.com/other/repo/pull/1234` must not
-      // mislink the worktree to an unrelated PR #1234 in the current repo.
-      // If the slug hasn't resolved yet, suppress recovery rather than
-      // risking a cross-repo mislink.
+      // Why: adopt the number only when the URL slug matches the selected repo (and the slug has resolved), else a foreign PR URL mislinks to a same-numbered PR here.
       if (
         selectedRepoSlug &&
         fromName.slug.owner.toLowerCase() === selectedRepoSlug.owner.toLowerCase() &&
@@ -1518,9 +1427,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   )
   const setupPolicy: SetupRunPolicy = selectedRepo?.hookSettings?.setupRunPolicy ?? 'run-by-default'
   const linkedWorkItemProvider = linkedWorkItem ? getLinkedWorkItemProvider(linkedWorkItem) : null
-  // Why: the "no prompt + linked item" path below rehydrates the issueCommand
-  // template into the main startup prompt. Linear starts never use that
-  // product-authored workflow text, so they should not wait for it either.
+  // Why: the no-prompt+linked-item path rehydrates the issueCommand template into the prompt, but Linear starts never use it, so they must not wait.
   const willApplyIssueCommandAsPrompt =
     enableIssueAutomation &&
     !agentPrompt.trim() &&
@@ -1541,11 +1448,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   const isSetupCheckPending = Boolean(repoId) && checkedHooksRepoId !== repoId
   const shouldWaitForSetupCheck = Boolean(selectedRepo) && selectedRepoIsGit && isSetupCheckPending
 
-  // Why: when the user leaves the workspace name blank and provides no other
-  // seed source (prompt, linked issue/PR), pick a globally-unique marine
-  // creature name so the workspace gets a distinct, readable identifier
-  // instead of colliding on a literal "workspace" default — or on the same
-  // creature already used in another repo.
+  // Why: blank name with no other seed → globally-unique creature name so workspaces don't collide across repos or on a literal default.
   const fallbackCreatureName = useMemo(
     () => getSuggestedCreatureName(worktreesByRepo),
     [worktreesByRepo]
@@ -1561,8 +1464,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       }),
     [agentPrompt, fallbackCreatureName, linkedPR, name, parsedLinkedIssueNumber]
   )
-  // Why: Linear starts may include only the neutral issue reference; repo
-  // issue-command templates are product-authored workflow direction.
+  // Why: exclude Linear — its starts may carry only a neutral issue ref, whereas repo issue-command templates are product-authored workflow direction.
   const shouldApplyLinkedOnlyTemplate =
     enableIssueAutomation &&
     !agentPrompt.trim() &&
@@ -1700,8 +1602,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     setRepoId(folderSourceRepos[0]?.id ?? '')
   }, [folderSourceRepos, repoId, selectedProjectGroup, setRepoId])
 
-  // Why: the compact sparse dropdown is always visible under Advanced, so
-  // presets must load before sparse mode is enabled.
+  // Why: the sparse dropdown is always visible under Advanced, so presets must load before sparse mode is enabled.
   useEffect(() => {
     if (!repoId || !selectedRepoIsGit || selectedRepo?.connectionId) {
       return
@@ -1718,9 +1619,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     sparsePresetsByRepo
   ])
 
-  // Why: detect agents for the selected repo. For local repos this runs once
-  // on mount (deduped by the store). For remote/runtime repos it re-runs when
-  // the selected repo changes so the agent list matches the correct host.
+  // Why: re-detect agents when the selected repo changes so the list matches the correct host (local runs once, deduped by the store).
   useEffect(() => {
     if (isRemote && selectedRepoSshStatus !== 'connected') {
       return
@@ -1749,9 +1648,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     return () => {
       cancelled = true
     }
-    // Why: re-run when connectionId/runtimeEnvironmentId changes (user picks a
-    // different repo) so detection targets the correct host. Draft/settings deps
-    // are intentionally excluded — detection is a best-effort PATH snapshot.
+    // Why: deps narrowed to host identity (connectionId/runtimeEnvironmentId); detection is a best-effort PATH snapshot, so draft/settings are excluded.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [connectionId, runtimeEnvironmentId, isRemote, selectedRepoSshStatus, disabledTuiAgents])
 
@@ -1867,9 +1764,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     }
   }, [folderTargetConnectionId])
 
-  // Why: warm the Start-from picker's PR cache on composer mount and whenever
-  // the selected repo changes so opening the picker paints instantly from
-  // cache.
+  // Why: warm the Start-from picker's PR cache so opening it paints instantly from cache.
   const canPrefetchSelectedRepoWorkItems = canUseRepoBackedComposerSources({
     connectionId: selectedRepoConnectionId,
     status: selectedRepoSshStatus
@@ -1939,22 +1834,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       .listWorkItems({ repoPath: selectedRepo.path, repoId: selectedRepo.id, limit: 100 })
       .then((envelope) => {
         if (!cancelled) {
-          // Why: IPC payload omits repoId — stamp it here from the repo we
-          // queried so downstream consumers typed against GitHubWorkItem work.
-          // Cast through unknown: spreading a discriminated union loses the
-          // discriminant, so the union-preserving shape must be asserted.
-          // Why: the link popover intentionally does NOT surface
-          // `envelope.errors?.issues`. Per-surface error copy lives in the
-          // Tasks view (TaskPage) and the smart workspace-name field — a
-          // partial-failure banner inside the small
-          // @-mention popover would crowd the input and the user would
-          // already see the same error on the originating Tasks page. If a
-          // future UX decision flips this, add an error row to the popover's
-          // render output.
-          // Why: surface partial issues-side failures via devtools even though the
-          // popover intentionally omits a UI banner (see rationale above). A user
-          // hitting a 403 on a private upstream would otherwise see an empty popover
-          // and no diagnostic trail.
+          // Why: IPC omits repoId — stamp it from the queried repo below; cast through unknown since spreading the discriminated union loses the discriminant.
+          // Why: the @-mention popover deliberately shows no error banner (it would crowd the input and the user sees it on the Tasks page); log to devtools instead.
           if (envelope.errors?.issues) {
             console.warn(
               '[composer/link] issues-side partial failure in @-mention popover:',
@@ -1999,10 +1880,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
 
     let cancelled = false
     setLinkDirectLoading(true)
-    // Why: Superset lets users paste a full GitHub URL or type a raw issue/PR
-    // number and still get a concrete selectable result. Full URLs carry
-    // issue-vs-PR intent, so preserve the URL route instead of probing by
-    // number only.
+    // Why: a full URL carries issue-vs-PR intent, so preserve the URL route instead of probing by number only.
     const lookupRepoId = selectedRepo.id
     const lookup =
       normalizedLinkQuery.directLink !== undefined
@@ -2079,9 +1957,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       const suggestedName =
         getLinkedWorkItemWorkspaceName(normalizedItem)?.seedName ??
         getLinkedWorkItemSuggestedName(normalizedItem)
-      // Why: a pasted URL/#123 in the field is the lookup query that found
-      // this item, not a deliberate name — replace it with the title-derived
-      // name or it silently becomes a slugified-URL workspace name.
+      // Why: a pasted URL/#123 is the lookup query, not a chosen name — replace with the title-derived name or it becomes a slugified-URL workspace name.
       if (
         suggestedName &&
         shouldApplyWorkspaceSourceAutoName({
@@ -2243,9 +2119,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
             ...smartGitHubMetadata,
             kind: 'metadata-only'
           }
-      // Why: Create can be clicked before the debounced smart field commits
-      // its selected source. Commit the resolved item here so failures leave
-      // the form showing the title instead of the raw URL.
+      // Why: Create can fire before the debounced smart field commits; commit the resolved item here so the form shows the title, not the raw URL.
       setLinkedIssue(
         resolution.linkedIssueNumber !== null ? String(resolution.linkedIssueNumber) : ''
       )
@@ -2285,8 +2159,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       settings
     ])
 
-  // Why: GitHub/GitLab review routing prefers one provider identity. Clear
-  // the opposite provider slots so stale hidden fields cannot win later.
+  // Why: review routing prefers one provider identity — clear the opposite provider slots so stale hidden fields can't win later.
   const applyLinkedGitLabWorkItem = useCallback(
     (item: GitLabWorkItem): void => {
       smartGitHubPrStartPointSelectionRef.current = null
@@ -2306,9 +2179,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         title: item.title,
         url: item.url
       })
-      // Why: GitLabWorkItem.branchName lines up with GitHubWorkItem.branchName
-      // structurally; cast to the suggested-name helper's input shape so we
-      // reuse the existing naming heuristic without forking it.
+      // Why: GitLabWorkItem.branchName lines up structurally with GitHubWorkItem's; cast to reuse the naming heuristic without forking it.
       const suggestedName = getLinkedWorkItemSuggestedName({
         type: item.type === 'mr' ? 'pr' : 'issue',
         number: item.number,
@@ -2371,8 +2242,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       lastAutoNameRef.current = ''
     }
     if (removedLinearItem) {
-      // Why: a Linear branch override belongs to its linked issue; unlinking
-      // must not leave provider metadata driving a later worktree create.
+      // Why: a Linear branch override belongs to its issue; unlinking must not leave it driving a later worktree create.
       setBranchNameOverride(undefined)
       setBranchNameOverridePreservesNameEdits(false)
       branchAutoNameRef.current = ''
@@ -2381,10 +2251,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
 
   const handleNameValueChange = useCallback(
     (nextName: string): void => {
-      // Why: linked GitHub items should keep refreshing the suggested workspace
-      // name only while the current value is still auto-managed. As soon as the
-      // user edits the field by hand, later issue/PR selections must stop
-      // clobbering it until they clear the field again.
+      // Why: linked items keep refreshing the suggested name only while it's auto-managed; a manual edit stops later picks from clobbering it until cleared.
       if (!nextName.trim()) {
         lastAutoNameRef.current = ''
       } else if (name !== lastAutoNameRef.current) {
@@ -2441,13 +2308,9 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       if (folderPaths.length === 0) {
         return
       }
-      // Why: de-dup within a single drop — the OS occasionally delivers the
-      // same folder twice when a user drags from a selection that includes both
-      // the item and its parent, and we don't want to insert it multiple times.
+      // Why: de-dup within one drop — the OS can deliver the same folder twice when the selection includes an item and its parent.
       const uniqueFolderPaths = Array.from(new Set(folderPaths))
-      // Why: wrap paths containing shell metacharacters in double quotes (and
-      // escape embedded quotes) so inserted folder refs stay a single token if
-      // pasted into a terminal. Simple paths stay unadorned to match OS drops.
+      // Why: quote paths with shell metacharacters so an inserted folder ref stays one token if pasted into a terminal; simple paths stay unadorned.
       const formatPath = (p: string): string => {
         if (/[\s"'$`\\()[\]{}*?!;&|<>#~]/.test(p)) {
           return `"${p.replace(/(["\\$`])/g, '\\$1')}"`
@@ -2456,16 +2319,13 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       }
       const insertion = uniqueFolderPaths.map(formatPath).join(' ')
       const textarea = promptTextareaRef.current
-      // Why: compute selection, insertion, and caret target OUTSIDE the
-      // setAgentPrompt updater so the updater stays pure. React Strict Mode
-      // double-invokes updaters in dev, and batching can delay execution.
+      // Why: compute selection/insertion/caret outside the setAgentPrompt updater so it stays pure — Strict Mode double-invokes updaters in dev.
       const current = agentPromptRef.current
       const selStart = textarea?.selectionStart ?? current.length
       const selEnd = textarea?.selectionEnd ?? current.length
       const before = current.slice(0, selStart)
       const after = current.slice(selEnd)
-      // Why: pad with single spaces when the caret sits directly against other
-      // text so the folder path doesn't merge into an adjacent word.
+      // Why: pad with spaces when the caret abuts text so the folder path doesn't merge into an adjacent word.
       const needsLeadingSpace = before.length > 0 && !/\s$/.test(before)
       const needsTrailingSpace = after.length > 0 && !/^\s/.test(after)
       const padded = `${needsLeadingSpace ? ' ' : ''}${insertion}${needsTrailingSpace ? ' ' : ''}`
@@ -2481,9 +2341,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
           textarea.setSelectionRange(caret, caret)
         })
       }
-      // Why: pass a plain value (not an updater) since `before`/`after` were
-      // already resolved from `agentPromptRef.current`; this keeps the state
-      // write side-effect-free under Strict-Mode double-render.
+      // Why: pass a plain value (not an updater) since before/after were already resolved, keeping the write pure under Strict-Mode double-render.
       setAgentPrompt(before + padded + after)
     },
     [cancelPromptCaretFrame]
@@ -2591,12 +2449,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   const applyLocalComposerDropRef = useRef(applyLocalComposerDrop)
   applyLocalComposerDropRef.current = applyLocalComposerDrop
 
-  // Why: native OS file drops onto the composer are captured by the preload
-  // bridge (see `data-native-file-drop-target="composer"` markers) and relayed
-  // as a gesture-scoped IPC event. Files become attachments (matching the
-  // manual picker behavior); folders are pasted inline at the textarea caret
-  // so the user can reference them as working directories in their prompt
-  // without attaching a path we can't embed as file content.
+  // Why: native OS file drops relay via the preload bridge; files become attachments, folders paste inline at the caret since a path can't be embedded as file content.
   const instanceIdRef = useRef<symbol>(Symbol('composer'))
   useEffect(() => {
     const instanceId = instanceIdRef.current
@@ -2605,10 +2458,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       if (data.target !== 'composer') {
         return
       }
-      // Why: only the top-of-stack composer (most recently mounted) owns the
-      // drop. Earlier subscribers stay bound to keep their own cleanup tidy
-      // but short-circuit so the event doesn't double-apply when page+modal
-      // are both alive.
+      // Why: only the top-of-stack composer owns the drop; earlier subscribers short-circuit so page+modal don't double-apply it.
       if (!isCurrentComposerDropOwner(composerDropStack, instanceId)) {
         return
       }
@@ -2652,16 +2502,13 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         setRepoId(value)
         return
       }
-      // Why: capture a short descriptor of the prior Start-from selection so
-      // the field can render an inline reset (e.g. "was PR #8778") after the
-      // repo changes and the selection is wiped.
+      // Why: capture a descriptor of the prior Start-from selection so the field can show an inline reset (e.g. "was PR #8778") after it's wiped.
       let hint: string | null = null
       if (!options.preserveStartFrom) {
         if (linkedWorkItem?.type === 'pr' && baseBranch) {
           hint = `was PR #${linkedWorkItem.number}`
         } else if (linkedWorkItem?.type === 'mr' && baseBranch) {
-          // Why: GitLab MR convention is `!N`, not `#N` — match the
-          // upstream UI so the reset hint is recognizable.
+          // Why: GitLab MR convention is `!N`, not `#N` — match the upstream UI so the hint is recognizable.
           hint = `was MR !${linkedWorkItem.number}`
         } else if (baseBranch) {
           hint = `was ${baseBranch}`
@@ -2678,32 +2525,25 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         setLinkedPR(null)
         setLinkedGitLabIssue(null)
         setLinkedGitLabMR(null)
-        // Why: repo changes invalidate repo-scoped sources (GitHub/GitLab/branch),
-        // but a selected Linear issue is workspace-scoped source context and
-        // must survive choosing the implementation project.
+        // Why: a repo change invalidates repo-scoped sources, but a Linear issue is workspace-scoped and must survive choosing the implementation project.
         if (!preserveLinearLinkedWorkItem) {
           setLinkedWorkItem(null)
         }
       }
       setSparseEnabled(false)
       setSparseDirectories('')
-      // Why: presets are repo-scoped, so a stale selection from the prior
-      // repo would be meaningless after a repo switch.
+      // Why: presets are repo-scoped, so a prior-repo selection is meaningless after a switch.
       setSparseSelectedPresetId(null)
-      // Why: the Start-from picker is repo-scoped, so any prior branch/PR
-      // selection is meaningless in the new repo. Resetting to undefined
-      // makes the field fall back to the new repo's effective base ref.
+      // Why: Start-from is repo-scoped; reset to undefined so the field falls back to the new repo's effective base ref.
       if (!options.preserveStartFrom) {
         setBaseBranch(undefined)
         setCompareBaseRef(undefined)
         setPushTarget(undefined)
-        // Why: Linear sources are workspace-scoped, so their canonical branch
-        // survives choosing a different implementation repo with the issue.
+        // Why: Linear sources are workspace-scoped, so their canonical branch survives choosing a different implementation repo.
         setBranchNameOverride(preservedLinearBranchName)
         setBranchNameOverridePreservesNameEdits(Boolean(preservedLinearBranchName))
         branchAutoNameRef.current = preservedLinearBranchName ?? ''
-        // Why (#5181): reuse state is branch-scoped, so a repo switch must clear
-        // it even when a workspace-scoped Linear override is restored.
+        // Why (#5181): reuse state is branch-scoped, so a repo switch clears it even when a workspace-scoped Linear override is restored.
         setReuseEligibleBranch(null)
         setReuseSelectedBranch(false)
         setForkPushWarning(null)
@@ -2736,8 +2576,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       if (!option || option.kind !== 'ready') {
         return
       }
-      // Why: switching the run host for the same logical project must not
-      // erase the task/PR source the user is starting from.
+      // Why: switching run host for the same project must not erase the task/PR source the user is starting from.
       handleRepoChange(option.repoId, { preserveStartFrom: true })
     },
     [handleRepoChange, projectHostSetupOptions]
@@ -2790,12 +2629,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       setSelectedProjectGroupId(null)
       const preferredHostId =
         selectedWorkspaceTarget.status === 'ready' ? selectedWorkspaceTarget.target.hostId : null
-      // Why: prefer the host the user is currently on, but treat it as a
-      // preference (focusedHostScope) rather than a hard hostId match. Pinning
-      // hostId made selecting a project that is only set up on a different host
-      // a silent no-op — the resolver returned '' (project-not-set-up-on-host)
-      // and the early return below swallowed the click. Falling back to any
-      // host the project is ready on lets cross-host selection work.
+      // Why: pass the current host as a preference (focusedHostScope), not a hard hostId — pinning made selecting a project set up only on another host a silent no-op.
       const nextRepoId = resolveWorkspaceCreationRepoId({
         eligibleRepos,
         projects,
@@ -2824,9 +2658,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   )
   const selectAddedProjectRepo = useCallback(
     (nextRepoId: string): void => {
-      // Why: the nested Add Project flow hands back a repo id. Selecting it
-      // must also clear a folder-group target, whose onRepoChange handler
-      // only accepts repos inside the selected group.
+      // Why: clear the folder-group target when selecting the Add-Project repo, since the group's onRepoChange only accepts repos inside the group.
       initialProjectGroupAppliedRef.current = true
       setSelectedProjectGroupId(null)
       setProjectError(null)
@@ -2864,9 +2696,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     setCompareBaseRef(undefined)
     setPushTarget(undefined)
     setBranchNameOverride(undefined)
-    // Why (#5181): the Start-from picker means "create a new branch from this
-    // base", so it never offers branch reuse — clear any reuse state left over
-    // from a prior smart-field branch pick.
+    // Why (#5181): Start-from means "new branch from this base", so it never reuses — clear reuse state from a prior smart-field branch pick.
     setBranchNameOverridePreservesNameEdits(false)
     setReuseEligibleBranch(null)
     setReuseSelectedBranch(false)
@@ -2890,14 +2720,9 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       setBranchNameOverridePreservesNameEdits(Boolean(nextBranchNameOverride))
       branchAutoNameRef.current = ''
       setStartFromResetHint(null)
-      // Why: per spec, a PR selection in the Start-from picker is also a
-      // linkedWorkItem assignment. Reuse applyLinkedWorkItem so auto-name and
-      // linkedPR state stay in a single code path.
+      // Why: a Start-from PR pick is also a linkedWorkItem assignment; reuse applyLinkedWorkItem so auto-name and linkedPR stay one code path.
       applyLinkedWorkItem(item, { preserveBranchNameOverride: Boolean(nextBranchNameOverride) })
-      // Why: starting a worktree from a PR is a strong hint for what the
-      // worktree's comment should surface (`orca worktree current`, sidebar).
-      // Prefill the note if it's empty or still equal to a prior auto-fill, so
-      // we don't overwrite anything the user has typed.
+      // Why: prefill the note from the PR (only when empty or still an auto-fill) so the sidebar surfaces it without clobbering user text.
       const identity = resolveGitHubWorkItemIdentity(item)
       if (identity.type === 'pr') {
         const suggestedNote = `PR #${identity.number} — ${item.title}`
@@ -2911,9 +2736,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     [applyLinkedWorkItem]
   )
 
-  // Why: GitLab parallel of handleBaseBranchPrSelect. Same shape, same
-  // semantics — except the note prefill uses GitLab's `!N` MR convention
-  // so a glance at the worktree sidebar makes the provider obvious.
+  // Why: GitLab parallel of handleBaseBranchPrSelect; note prefill uses GitLab's `!N` MR convention so the sidebar makes the provider obvious.
   const handleBaseBranchMrSelect = useCallback(
     (
       nextBaseBranch: string,
@@ -2974,9 +2797,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       setForkPushWarning(null)
       branchAutoNameRef.current = ''
       smartGitHubPrStartPointSelectionRef.current = null
-      // Why: provider items can come from a different source host than the
-      // selected run host. Resolve git refs against the run repo; keep item
-      // metadata/source context separate for provider identity.
+      // Why: provider items can come from a different source host than the run host — resolve refs against the run repo, keep item metadata for provider identity.
       const runRepo = selectedRepo ?? eligibleRepos.find((repo) => repo.id === item.repoId)
       applyLinkedWorkItem(normalizedItem)
       if (identity.type !== 'pr' || !runRepo) {
@@ -3020,8 +2841,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
             result.branchNameOverride,
             result.compareBaseRef
           )
-          // Why: a fork PR push lands on the contributor's fork; if they didn't
-          // allow maintainer edits, GitHub will reject it. Warn up front.
+          // Why: a fork PR push lands on the contributor's fork; without maintainer-edits allowed GitHub rejects it, so warn up front.
           setForkPushWarning(getForkPushWarning(result))
         })
         .catch((error: unknown) => {
@@ -3049,11 +2869,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     ]
   )
 
-  // Why: GitLab parallel of handleSmartGitHubItemSelect. For a picked
-  // MR, resolves the base branch via worktrees:resolveMrBase (which uses
-  // refs/merge-requests/<iid>/head for fork MRs the same way the gh side
-  // uses refs/pull/<N>/head). Issue selections short-circuit since
-  // there's no branch-resolution step to run.
+  // Why: GitLab parallel of handleSmartGitHubItemSelect — resolves MR base via worktrees:resolveMrBase (refs/merge-requests/<iid>/head); issues short-circuit.
   const handleSmartGitLabItemSelect = useCallback(
     (item: GitLabWorkItem): void => {
       if (isProjectGroupTarget) {
@@ -3082,8 +2898,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       setBranchNameOverridePreservesNameEdits(false)
       setForkPushWarning(null)
       branchAutoNameRef.current = ''
-      // Why: MR metadata can be sourced from one host/account while the
-      // workspace is created on another host for the same logical project.
+      // Why: MR metadata can be sourced from one host/account while the workspace is created on another for the same logical project.
       const runRepo = selectedRepo ?? eligibleRepos.find((repo) => repo.id === item.repoId)
       if (item.type !== 'mr' || !runRepo) {
         setCompareBaseRef(undefined)
@@ -3126,9 +2941,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       void resolveMrBase
         .then((result) => {
           if ('error' in result) {
-            // Why: without surfacing the failure the worktree silently falls
-            // back to the repo default branch (origin/master), so clear stale
-            // base state and tell the user — mirrors the GitHub PR path.
+            // Why: an unsurfaced failure silently falls back to the repo default branch, so clear stale base state and toast — mirrors the GitHub PR path.
             setBaseBranch(undefined)
             setCompareBaseRef(undefined)
             setPushTarget(undefined)
@@ -3179,15 +2992,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       setPushTarget(undefined)
       setStartFromResetHint(null)
       setForkPushWarning(null)
-      // Why (#5181): reuse an existing local branch (check it out) instead of
-      // branching off it. Default reuse ON when the worktree name was
-      // auto-derived from the branch, and preserve name edits so reuse survives
-      // renaming the worktree folder. Reuse is impossible when the branch is
-      // already checked out in another worktree (git allows it in only one), so
-      // gate eligibility on that and don't pin the override to a busy branch.
-      // Note: worktreesByRepo only covers visible worktrees; a branch busy only
-      // in a hidden external worktree falls through to the backend conflict
-      // check, which rejects it with a clear "already exists locally" error.
+      // Why (#5181): reuse (check out) an existing branch instead of branching off it; git allows a branch in only one worktree, so gate eligibility on that.
+      // Note: worktreesByRepo covers only visible worktrees; a branch busy in a hidden external worktree falls through to the backend "already exists locally" check.
       const { reuseEligibleBranch: nextReuseEligibleBranch, defaultReuse } = selection
       setReuseEligibleBranch(nextReuseEligibleBranch)
       setReuseSelectedBranch(defaultReuse)
@@ -3211,10 +3017,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         return
       }
       setReuseSelectedBranch(next)
-      // Why (#5181): reuse pins the exact existing branch as the override and
-      // preserves it across worktree-name edits, so the folder can be named
-      // independently while the branch is checked out. Opting out drops the
-      // override so a fresh branch is created from the selected ref as base.
+      // Why (#5181): reuse pins the existing branch as override (preserved across name edits); opting out drops it so a fresh branch is created from the ref.
       setBranchNameOverridePreservesNameEdits(next)
       setBranchNameOverride(next ? reuseEligibleBranch : undefined)
       if (next) {
@@ -3254,8 +3057,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       const linkedLinearIssue = buildLinearIssueLinkedWorkItem(issue)
       setLinkedWorkItem(linkedLinearIssue)
       const suggestedName = getLinearIssueWorkspaceName(issue)
-      // Why: same lookup-text rule as applyLinkedWorkItem, plus the typed
-      // Linear identifier ("STA-123") that matched this issue.
+      // Why: same lookup-text rule as applyLinkedWorkItem, plus the typed Linear identifier ("STA-123") that matched this issue.
       if (
         shouldApplyWorkspaceSourceAutoName({
           currentName: name,
@@ -3271,9 +3073,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       setBranchNameOverridePreservesNameEdits(Boolean(linearBranchName))
       setForkPushWarning(null)
       branchAutoNameRef.current = linearBranchName ?? ''
-      // Why: match the GitHub issue/PR flow by drafting linked context for
-      // review instead of auto-submitting. Auto-filling the note here would
-      // turn a source selection into user-authored instructions.
+      // Why: don't prefill the note for a Linear pick — that would turn a source selection into user-authored instructions (matches the GitHub flow).
     },
     [isProjectGroupTarget, name]
   )
@@ -3618,8 +3418,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
             ? submitTitleName?.displayName
             : undefined
           : smartGitHubCreateNames.displayName
-      // Why: the first-work hook only renames blank, auto-generated git workspaces
-      // that actually launch an agent. Persist that known-pending state for the card.
+      // Why: the first-work hook only renames blank, auto-generated git workspaces that launch an agent; persist that pending state for the card.
       const pendingFirstAgentMessageRename =
         selectedRepoIsGit &&
         settings?.autoRenameBranchFromWork === true &&
@@ -3644,9 +3443,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       const shouldSeedInitialAgentStatus =
         tuiAgent === 'command-code' && submitStartupPrompt.trim().length > 0
 
-      // Why: backend startup is safe only when the launch command is
-      // self-contained. Agents that need post-ready paste/follow-up stay on
-      // the renderer path so prompt delivery is not skipped.
+      // Why: backend startup is safe only for self-contained launch commands; agents needing post-ready paste stay on the renderer path.
       const composerTelemetry: AgentStartedTelemetry = {
         agent_kind: tuiAgentToAgentKind(tuiAgent),
         launch_source: telemetrySource === 'onboarding' ? 'onboarding' : 'new_workspace_composer',
@@ -3708,8 +3505,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       const worktree = result.worktree
 
       const trimmedNote = note.trim()
-      // Why: linked source metadata is already included in createWorktree.
-      // Re-saving it here can trigger slow post-create PR push-target lookups.
+      // Why: linked source metadata is already in createWorktree; re-saving it can trigger slow post-create PR push-target lookups.
       await applyWorktreeMeta(worktree.id, trimmedNote ? { comment: trimmedNote } : {})
 
       const issueCommand =
@@ -3723,8 +3519,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
           : undefined
       const backendSpawnedStartup = result.startupTerminal?.spawned === true
       if (startupPlan && !backendSpawnedStartup && !startupPlan.launchToken) {
-        // Why: delayed delivery must target the exact pane spawned from this
-        // queued startup, so both halves share one renderer-session token.
+        // Why: delayed delivery must target the exact pane from this queued startup, so both halves share one renderer-session token.
         startupPlan.launchToken = createBrowserUuid()
       }
       const activation = activateAndRevealWorktree(worktree.id, {
@@ -3844,13 +3639,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   ])
 
   const resetForNextCreate = useCallback(() => {
-    // Why: with "create multiple" on, clear identity fields after each create so
-    // the next worktree starts clean. Context (repo, base branch, agent, project
-    // group) is intentionally retained for fast sequential creation. The
-    // PR-pick-derived refs (compare base, push target, branch override) are
-    // identity, not durable context, so they reset too — leaving them while the
-    // linked item is cleared would carry a half-set Start-from state (e.g. a
-    // silent fork push target) into the next worktree.
+    // Why: clears identity fields incl PR-pick-derived refs (else a half-set Start-from state — e.g. a silent fork push target — leaks into the next create); retains context (repo, base, agent, group) for fast sequential creates.
     setName('')
     lastAutoNameRef.current = ''
     setAgentPrompt('')
@@ -3869,8 +3658,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     setStartFromResetHint(null)
     setForkPushWarning(null)
     setCreateError(null)
-    // Refocus the name field on the next frame (after the reset re-render) so the
-    // user can immediately type the next worktree name.
+    // Refocus after the reset re-render (next frame) so the user can type the next worktree name immediately.
     requestAnimationFrame(() => nameInputRef.current?.focus())
   }, [])
 
@@ -4039,8 +3827,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
               ? submitTitleName?.displayName
               : undefined
             : smartGitHubCreateNames.displayName
-        // Why: quick create uses the same blank-name creature branch flow; the card
-        // needs an explicit marker rather than guessing from the generated title.
+        // Why: quick create shares the blank-name flow; the card needs an explicit marker, not a guess from the title.
         const pendingFirstAgentMessageRename =
           selectedRepoIsGit &&
           settings?.autoRenameBranchFromWork === true &&
@@ -4049,9 +3836,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
           !effectiveBranchNameOverride &&
           !createDisplayName
         const trimmedNote = note.trim()
-        // Why: backend startup is safe only when the launch command is
-        // self-contained. Agents that need post-ready paste/follow-up stay on
-        // the renderer path so prompt delivery is not skipped.
+        // Why: agents needing post-ready paste/follow-up stay on the renderer path so prompt delivery isn't skipped.
         const promptLinkedWorkItem = agent === null ? null : submitLinkedWorkItem
         const { prompt: quickPrompt, draftPrompt: quickDraftPrompt } =
           resolveQuickCreateLinkedWorkItemPrompt(promptLinkedWorkItem, trimmedNote)
@@ -4227,16 +4012,13 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
           ...(createMultiple ? { suppressTerminalFocusOnCompletion: true } : {})
         }
 
-        // Why: git fetch + `git worktree add` can take 10–15s; holding the modal
-        // hostage to that made it feel frozen, so hand off to a background flow and
-        // close the modal immediately.
+        // Why: git fetch + `git worktree add` can take 10–15s; run in the background so the modal isn't frozen.
         if (persistDraft) {
           clearNewWorkspaceDraft()
         }
         runBackgroundWorktreeCreation(request)
         if (createMultiple) {
-          // Why: keep the modal open and reset identity so the user can queue
-          // another worktree right away; the creation above runs in the background.
+          // Why: creation runs in the background, so reset identity to queue another worktree right away.
           resetForNextCreate()
         } else {
           onCreated?.()
@@ -4365,8 +4147,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       smartNameSelection?.kind === 'branch',
     reuseSelectedBranch,
     onReuseSelectedBranchChange: handleReuseSelectedBranchChange,
-    // Why: the "create multiple" toggle only applies to worktree (git) targets;
-    // folder-workspace targets keep the create-and-close behavior.
+    // Why: "create multiple" applies only to worktree (git) targets; folder-workspace keeps create-and-close.
     showCreateMultiple: !isProjectGroupTarget,
     createMultiple,
     onCreateMultipleChange: setCreateMultiple,
diff --git a/src/renderer/src/hooks/useEditorExternalWatch.ts b/src/renderer/src/hooks/useEditorExternalWatch.ts
index 9fd18202b98..facb821e77b 100644
--- a/src/renderer/src/hooks/useEditorExternalWatch.ts
+++ b/src/renderer/src/hooks/useEditorExternalWatch.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: the editor external-watch hook co-locates
-   target diffing, fs:changed dispatch, tombstone coalescing, and rename
-   correlation so the end-to-end event-to-store mutation contract stays
-   readable in one file. */
+/* eslint-disable max-lines -- co-locates target diffing, fs:changed dispatch, tombstone coalescing, and rename correlation so the event-to-store contract stays in one file. */
 import { useEffect, useRef } from 'react'
 import { useAppStore, type AppState } from '@/store'
 import { basename, joinPath } from '@/lib/path'
@@ -31,14 +28,7 @@ import {
 import { isGitRepoKind } from '../../../shared/repo-kind'
 import { markFileChangedOnDisk } from '@/components/editor/editor-changed-on-disk-mark'
 
-// Why: atomic-write patterns (Claude Code's Edit tool, editors like vim,
-// VSCode) land as a short burst of `update` events — or `delete + create` on
-// renamers — within a few milliseconds for the same path. Dispatching an
-// `ORCA_EDITOR_EXTERNAL_FILE_CHANGE_EVENT` per raw event fan-outs into N full
-// `setContent` + document-repair rebuilds per mounted EditorPanel,
-// which under split-pane + large markdown is enough to wedge the renderer
-// and black out the window (issue #826). Coalescing per (worktreeId + path)
-// on a short debounce collapses that burst into one reload notification.
+// Why: atomic writes burst same-path events; one reload dispatch each fans out into N EditorPanel rebuilds that can wedge the renderer (issue #826), so debounce per (worktreeId+path).
 const EXTERNAL_RELOAD_DEBOUNCE_MS = 75
 const pendingExternalReloadTimers = new Map<string, ReturnType<typeof setTimeout>>()
 
@@ -115,9 +105,7 @@ let cachedSshConnectionStates: AppState['sshConnectionStates'] | null = null
 let cachedWatchedTargetsSnapshot: WatchedTargetsSnapshot = { targets: [], targetsKey: '' }
 
 export function getWatchedTargetKey(target: WatchedTarget): string {
-  // Why: SSH worktrees can exist in the store before their remote filesystem
-  // provider is ready. Include connectionId so a local/unknown placeholder
-  // watch is replaced by the real SSH watch when the repo metadata hydrates.
+  // Why: include connectionId so a local placeholder watch is replaced by the real SSH watch once an SSH worktree's provider metadata hydrates.
   return `${target.worktreeId}::${target.worktreePath}::${target.connectionId ?? 'local'}::${target.runtimeEnvironmentId ?? 'client'}`
 }
 
@@ -145,18 +133,14 @@ export function getEditorExternalWatchTargets(
   }
 
   const targetOwnersByWorktreeId = new Map<string, Set<string | null>>()
-  // Why: watcher ownership is scoped by both worktree and runtime owner.
-  // The same path can be open locally and in a runtime-backed workspace at
-  // once; reads/saves already route per tab owner, so live reloads must too.
+  // Why: watcher ownership is scoped by worktree + runtime owner — the same path can be open locally and in a runtime workspace, and reads/saves already route per owner.
   for (const f of state.openFiles) {
     let owners = targetOwnersByWorktreeId.get(f.worktreeId)
     if (!owners) {
       owners = new Set()
       targetOwnersByWorktreeId.set(f.worktreeId, owners)
     }
-    // Why: persisted/restored local tabs may have runtimeEnvironmentId
-    // undefined. New openFile calls resolve active-runtime inheritance before
-    // storing the tab, so an ownerless stored tab must stay local here.
+    // Why: persisted/restored tabs may have runtimeEnvironmentId undefined; new openFile calls resolve inheritance before storing, so an ownerless tab stays local.
     owners.add(openFileRuntimeOwner(f))
   }
   const activeWorktreeId = state.activeWorktreeId
@@ -179,16 +163,13 @@ export function getEditorExternalWatchTargets(
     ((state.rightSidebarTab === 'explorer' && state.rightSidebarExplorerView === 'files') ||
       (state.rightSidebarTab === 'source-control' && sourceControlCanConsumeWatch))
   if (activeWorktreeNeedsSidebarWatch) {
-    // Why: this app-level watcher owns subscriptions for Explorer and Source
-    // Control so downstream consumers do not fight over watch/unwatch IPC.
+    // Why: this app-level watcher owns Explorer/Source-Control subscriptions so downstream consumers don't fight over watch/unwatch IPC.
     let owners = targetOwnersByWorktreeId.get(activeWorktreeId)
     if (!owners) {
       owners = new Set()
       targetOwnersByWorktreeId.set(activeWorktreeId, owners)
     }
-    // Why: sidebar consumers are mounted for the selected worktree. Their
-    // watcher must follow that worktree's host owner, not the host currently
-    // focused in the UI.
+    // Why: sidebar watcher must follow the selected worktree's host owner, not the host currently focused in the UI.
     owners.add(getRuntimeEnvironmentIdForWorktree(state, activeWorktreeId))
   }
 
@@ -236,16 +217,7 @@ export function getEditorExternalWatchTargets(
   return cachedWatchedTargetsSnapshot
 }
 
-// Why: macOS atomic writes (Claude Code Edit, vim :w, VSCode save) deliver a
-// delete event immediately followed by a create event for the same path. When
-// those two land in separate fs:changed payloads a few ms apart, the tab
-// flickers struck-through for one render before the follow-up create clears
-// it. Debouncing just the 'deleted' signal — keyed by absolute path — lets a
-// same-path create in the next payload cancel the tombstone before it ever
-// paints. Key by owner as well as path so local/runtime tabs for the same
-// worktree file cannot cancel each other's tombstones. A naked delete still
-// resolves to 'deleted' after the window. The in-payload rename correlation
-// is unchanged.
+// Why: macOS atomic writes split delete→create across payloads; debounce the 'deleted' signal so a same-path create cancels the tombstone before it paints. Key by owner+path so a local and runtime tab for the same file can't cancel each other's tombstones.
 const EXTERNAL_MUTATION_DEBOUNCE_MS = 75
 
 type PendingDeleteTimer = {
@@ -258,14 +230,7 @@ type PendingDeleteTimer = {
  * has an editor tab open, and notifies the editor to reload clean tabs when
  * their on-disk contents change.
  *
- * Why: the File Explorer panel's watcher hook is unmounted whenever the user
- * switches the right sidebar to Source Control / Checks / Search. Relying on
- * that panel to dispatch editor-reload notifications means terminal edits go
- * unnoticed while any non-Explorer sidebar tab is active. Lifting the
- * editor-reload subscription to an always-mounted hook mirrors VSCode's
- * `TextFileEditorModelManager`, which subscribes to `fileService
- * .onDidFilesChange` once at the workbench level and reloads non-dirty models
- * regardless of which UI panel is visible.
+ * Why: the File Explorer watcher unmounts when the sidebar leaves Explorer, so lifting this to an always-mounted hook keeps terminal edits noticed everywhere.
  */
 export function useEditorExternalWatch(): void {
   const { targets, targetsKey } = useAppStore(getEditorExternalWatchTargets)
@@ -278,10 +243,7 @@ export function useEditorExternalWatch(): void {
     ((payload: FsChangedPayload, runtimeEnvironmentId?: string | null) => void) | null
   >(null)
 
-  // Why: diff previous vs next targets so unchanged worktrees keep their
-  // existing subscription. Tearing down every subscription on each targetsKey
-  // change (e.g. opening/closing a tab in an already-watched worktree) causes
-  // a watcher churn that can drop events emitted during the gap.
+  // Why: diff prev vs next targets so unchanged worktrees keep their subscription; tearing down all on every targetsKey change churns watchers and drops events in the gap.
   useEffect(() => {
     const nextTargets = latestTargetsRef.current
     const prev = targetsRef.current
@@ -346,22 +308,15 @@ export function useEditorExternalWatch(): void {
           connectionId: target.connectionId
         })
         .catch((err) => {
-          // Why: remote SSH providers can disappear while tabs still reference
-          // the worktree. Watching should degrade to a diagnostic, not an
-          // uncaught renderer promise that looks like the terminal froze.
+          // Why: remote SSH providers can disappear while tabs still reference the worktree; degrade to a diagnostic, not an uncaught renderer promise.
           warnExternalWatchFailure(target, err)
         })
     }
     targetsRef.current = nextTargets
-    // Why: this effect is intentionally differential — it does not unwatch on
-    // cleanup. Final unmount unwatching lives in the separate [] effect below
-    // so that re-running on targetsKey changes doesn't tear down everything.
+    // Why: intentionally differential — no unwatch on cleanup; final unmount unwatching lives in the [] effect below so targetsKey changes don't tear down everything.
   }, [targetsKey])
 
-  // Why: the fs:changed subscription and the final unmount unwatch are
-  // independent of which worktrees are currently watched. Keeping them in a
-  // single always-mounted effect avoids re-subscribing on every targetsKey
-  // change (which would otherwise miss events fired during re-subscription).
+  // Why: keep the fs:changed subscription in an always-mounted [] effect so it doesn't re-subscribe on every targetsKey change and miss events fired during the gap.
   useEffect(() => {
     const remoteWatchUnsubs = remoteWatchUnsubsRef.current
     const { handleFsChanged, dispose } = createExternalWatchEventHandler(
@@ -380,9 +335,7 @@ export function useEditorExternalWatch(): void {
       unsubscribe()
       dispose()
       fsChangedHandlerRef.current = null
-      // Why: final unmount must tear down every outstanding subscription.
-      // The differential watch effect above intentionally never unwatches on
-      // cleanup, so this is the only place that clears them.
+      // Why: the differential watch effect never unwatches on cleanup, so final unmount is the only place that tears down every subscription.
       for (const target of targetsRef.current) {
         const key = getWatchedTargetKey(target)
         const remoteUnsubscribe = remoteWatchUnsubs.get(key)
@@ -397,21 +350,15 @@ export function useEditorExternalWatch(): void {
       }
       remoteWatchUnsubs.clear()
       targetsRef.current = []
-      // Why: deliberately do NOT clear pendingExternalReloadTimers here.
-      // The map is module-scoped, so in React StrictMode (dev) the first
-      // mount's cleanup would otherwise drop timers scheduled by the second
-      // mount. A late `notifyEditorExternalFileChange` dispatch after unmount
-      // is also harmless — it's a window event with no EditorPanel listeners
-      // attached once the editor tree is torn down.
+      // Why: don't clear the module-scoped pendingExternalReloadTimers — StrictMode's first-mount cleanup would drop the second mount's timers; a late dispatch is harmless.
     }
   }, [])
 }
 
 /**
- * Builds the fs:changed handler used by `useEditorExternalWatch`. Exported
- * so tests can drive the full event pipeline — including the debounced
- * tombstone coalescer — without mounting the hook. See
- * `EXTERNAL_MUTATION_DEBOUNCE_MS` for the macOS atomic-write rationale.
+ * Builds the fs:changed handler used by `useEditorExternalWatch`. Exported so
+ * tests can drive the full event pipeline (including the tombstone coalescer)
+ * without mounting the hook.
  */
 export function createExternalWatchEventHandler(
   findTarget: (
@@ -422,10 +369,7 @@ export function createExternalWatchEventHandler(
   handleFsChanged: (payload: FsChangedPayload, runtimeEnvironmentId?: string | null) => void
   dispose: () => void
 } {
-  // Why: coalesce 'deleted' tombstones across back-to-back payloads so a
-  // same-path create arriving in the next payload (macOS atomic write)
-  // cancels the tombstone before the tab flashes. Keyed by normalized
-  // absolute path, scoped per-target. See EXTERNAL_MUTATION_DEBOUNCE_MS.
+  // Why: coalesce 'deleted' tombstones so a same-path create cancels them before the tab flashes (macOS atomic write). See EXTERNAL_MUTATION_DEBOUNCE_MS.
   const pendingDeletes = new Map<string, PendingDeleteTimer>()
   const pendingKey = (
     worktreeId: string,
@@ -441,8 +385,7 @@ export function createExternalWatchEventHandler(
     if (!target) {
       return
     }
-    // Why: this app-level hook owns worktree watcher subscriptions. Other
-    // consumers listen here so they do not fight over watch/unwatch ownership.
+    // Why: this app-level hook owns watcher subscriptions; other consumers listen here so they don't fight over watch/unwatch ownership.
     if (typeof window !== 'undefined' && typeof window.dispatchEvent === 'function') {
       window.dispatchEvent(
         new CustomEvent<WorktreeFileChangeEventDetail>(ORCA_WORKTREE_FILE_CHANGE_EVENT, {
@@ -451,9 +394,7 @@ export function createExternalWatchEventHandler(
       )
     }
 
-    // Why: collect create/update paths first so we can cancel any pending
-    // same-path delete before scheduling a new one. This is what absorbs
-    // the macOS atomic-write delete→create split across two payloads.
+    // Why: collect create/update paths first to cancel any pending same-path delete — this absorbs the macOS atomic-write delete→create split across two payloads.
     const createOrUpdatePaths = new Set<string>()
     for (const evt of payload.events) {
       if (evt.isDirectory === true) {
@@ -472,14 +413,8 @@ export function createExternalWatchEventHandler(
       }
     }
 
-    // Why: when an external process removes (or `git mv`s) a file that's
-    // open in the editor, keep the tab alive and mark it as deleted/renamed
-    // so the user can see the mutation and still access their in-memory
-    // content. A paired create-event in the same batch signals a rename;
-    // a lone delete is a hard delete. Resurrection (same path comes back
-    // on disk) clears the mark further down.
-    // Why: snapshot openFiles once so the delete/rename helpers below share a
-    // consistent view and we don't pay N store reads per payload.
+    // Why: mark editor tabs deleted/renamed instead of closing them so the user keeps in-memory content; a paired create means rename, a lone delete is hard.
+    // Why: snapshot openFiles once so the delete/rename helpers share a consistent view without N store reads per payload.
     const openFilesAtStart = useAppStore.getState().openFiles
     const deletedOpenEditorIds = collectDeletedOpenEditorIds(
       payload,
@@ -487,26 +422,19 @@ export function createExternalWatchEventHandler(
       target.runtimeEnvironmentId,
       openFilesAtStart
     )
-    // Why: correlate creates to deletes by basename OR parent directory to
-    // avoid mislabelling unrelated create+delete pairs in a batched payload
-    // as "renamed". When we can't correlate, default to 'deleted' — that's
-    // the least misleading fallback (it preserves in-memory content and
-    // doesn't claim a rename target that doesn't exist).
+    // Why: correlate creates to deletes by basename to avoid mislabelling unrelated create+delete pairs as "renamed"; default to 'deleted' when we can't correlate.
     const hasPairedCreate =
       deletedOpenEditorIds.length > 0 &&
       hasRenameCorrelatedCreate(payload, target.worktreeId, deletedOpenEditorIds, openFilesAtStart)
     if (deletedOpenEditorIds.length > 0) {
       if (hasPairedCreate) {
-        // Why: single-payload delete+create is already correct — the rename
-        // label is visible in one render tick, so no debounce is needed.
+        // Why: single-payload delete+create is already correct in one render tick, so no debounce needed.
         const setExternalMutation = useAppStore.getState().setExternalMutation
         for (const fileId of deletedOpenEditorIds) {
           setExternalMutation(fileId, 'renamed')
         }
       } else {
-        // Why: defer the 'deleted' tombstone so a follow-up same-path create
-        // in the next payload can cancel it. Build a fileId → path map so we
-        // can key the timer by the deleted file's absolute path.
+        // Why: defer the 'deleted' tombstone so a follow-up same-path create in the next payload can cancel it (macOS atomic write).
         const deletePathByFileId = buildDeletePathByFileId(
           payload,
           target.worktreeId,
@@ -527,12 +455,7 @@ export function createExternalWatchEventHandler(
           }
           const timer = setTimeout(() => {
             pendingDeletes.delete(key)
-            // Why: the debounce widens the window between scheduling the
-            // tombstone and applying it; the tab may have been closed or
-            // switched out of edit mode in between. Re-check both before
-            // writing so we don't resurrect state for a dropped fileId or
-            // tombstone a non-edit tab (mirrors the scheduling-time filter
-            // in `collectDeletedOpenEditorIds`).
+            // Why: the debounce window lets the tab close or leave edit mode, so re-check before writing to avoid tombstoning a dropped or non-edit tab.
             const state = useAppStore.getState()
             const stillEditing = state.openFiles.some((f) => f.id === fileId && f.mode === 'edit')
             if (stillEditing) {
@@ -544,13 +467,7 @@ export function createExternalWatchEventHandler(
       }
     }
 
-    // Why: if a previously-deleted file reappears at the same path (e.g.
-    // the user ran `git checkout`), clear the tombstone so the tab returns
-    // to its normal state and any non-dirty content gets reloaded below.
-    // `createOrUpdatePaths` was collected above. Scoped to deleted/renamed:
-    // a 'changed' mark means the file was rewritten while the tab was dirty,
-    // so a further update event must not clear it — it resolves via reload,
-    // save, or the reload path below.
+    // Why: a reappearing file (e.g. `git checkout`) clears its deleted/renamed tombstone — but not a 'changed' mark, which resolves via reload/save instead.
     if (createOrUpdatePaths.size > 0) {
       const state = useAppStore.getState()
       for (const file of state.openFiles) {
@@ -569,17 +486,11 @@ export function createExternalWatchEventHandler(
     const changedFiles = new Set<string>()
     for (const evt of payload.events) {
       if (evt.kind === 'overflow') {
-        // Why: overflow payloads omit per-path create/update info, so any
-        // stale tombstone must be cleared conservatively before we decide
-        // which clean tabs to reload. Otherwise a file that reappeared on
-        // disk during the overrun stays struck through until some later
-        // path-specific event happens to clear it.
+        // Why: overflow omits per-path info, so conservatively clear stale tombstones or a file that reappeared during the overrun stays struck through.
         for (const notification of getOverflowExternalReloadTargets(target)) {
           scheduleDebouncedExternalReload(notification)
         }
-        // Why: `break` (not `return`) — the remaining code early-returns
-        // when changedFiles is empty, so breaking out is semantically
-        // equivalent and more robust to future code added after the loop.
+        // Why: `break` not `return` — changedFiles is empty so the rest early-returns anyway, and this is more robust to code added after the loop.
         break
       }
 
@@ -588,10 +499,7 @@ export function createExternalWatchEventHandler(
       }
 
       if (evt.kind === 'delete') {
-        // Why: delete events are already handled above by marking the tab
-        // as tombstoned. Feeding them into the reload pipeline would fire
-        // `readFile` against the ENOENT path and replace the in-memory
-        // content with "Error loading file..." — losing the user's view.
+        // Why: deletes are tombstoned above; feeding them into reload would read the ENOENT path and replace in-memory content with an error, losing the user's view.
         continue
       }
 
@@ -609,15 +517,9 @@ export function createExternalWatchEventHandler(
       return
     }
 
-    // Why: skip notifying for any tab with unsaved edits so external writes
-    // don't silently destroy the user's work. Mirrors the dirty guard in
-    // `useFileExplorerHandlers`. Read `openFiles` once per payload to avoid
-    // N store reads for large batched events.
+    // Why: read openFiles once per payload to avoid N store reads on large batches; consumers skip dirty tabs so external writes don't destroy unsaved work.
     const openFilesSnapshot = useAppStore.getState().openFiles
-    // Why: a combined "Changes" tab matches no single path but renders every
-    // changed file's working-tree diff. This is per-worktree, not per-path, so
-    // compute it once instead of rescanning openFiles for each changed file in
-    // a large batched payload (e.g. a branch switch touching hundreds of files).
+    // Why: the combined "Changes" tab is per-worktree not per-path, so compute it once instead of rescanning openFiles per changed file in a large batched payload.
     const hasCombinedDiffConsumer = openFilesSnapshot.some(
       (f) =>
         f.worktreeId === target.worktreeId &&
@@ -633,10 +535,7 @@ export function createExternalWatchEventHandler(
       }
       const matching = getOpenFilesForExternalFileChange(openFilesSnapshot, notification)
       if (matching.length === 0) {
-        // Why: notify the combined-diff tab so its section reloads. Its own
-        // dirty/section guards make a blanket reload safe, and there is no
-        // in-memory editor content to clobber, so self-write suppression is
-        // unnecessary here.
+        // Why: combined-diff tab has no in-memory content to clobber and guards its own reload, so notify it directly without self-write suppression.
         if (hasCombinedDiffConsumer) {
           scheduleDebouncedExternalReload(notification)
         }
@@ -644,15 +543,11 @@ export function createExternalWatchEventHandler(
       }
       const dirtyMatches = matching.filter((f) => f.isDirty)
       if (dirtyMatches.length > 0) {
-        // Why: an external write landing on a dirty tab must not vanish
-        // silently (issue #7265) — the user was left with a stale tab and a
-        // save that clobbered the newer disk content. Mark the tab so the
-        // editor shows a changed-on-disk banner with an explicit reload path.
+        // Why: an external write on a dirty tab must not vanish silently (issue #7265) — mark it so the editor shows a changed-on-disk banner with a reload path.
         scheduleChangedOnDiskMark(
           target,
           notification,
-          // Why: canAutoSaveOpenFile is exactly the set of tabs that can hold
-          // unsaved edits (edit + unstaged diff) — the tabs the banner serves.
+          // Why: canAutoSaveOpenFile is exactly the tabs that can hold unsaved edits (edit + unstaged diff) — the tabs the banner serves.
           dirtyMatches.filter((dirtyFile) => canAutoSaveOpenFile(dirtyFile)).map((f) => f.id)
         )
         if (dirtyMatches.length === matching.length) {
@@ -661,8 +556,7 @@ export function createExternalWatchEventHandler(
           }
           continue
         }
-        // Clean sibling tabs (e.g. an unstaged diff of the same path) still
-        // reload below; every notification consumer skips dirty files.
+        // Clean sibling tabs (e.g. an unstaged diff of the same path) still reload below; consumers skip dirty files.
       }
       const absolutePath = joinPath(notification.worktreePath, notification.relativePath)
       const recentSelfWrite = getRecentSelfWrite(absolutePath, target.runtimeEnvironmentId)
@@ -675,8 +569,7 @@ export function createExternalWatchEventHandler(
   }
 
   const dispose = (): void => {
-    // Why: clear in-flight debounced tombstone timers so they don't fire
-    // after disposal and touch a no-longer-relevant store.
+    // Why: clear in-flight tombstone timers so they don't fire after disposal and touch a stale store.
     for (const pending of pendingDeletes.values()) {
       clearTimeout(pending.timer)
     }
@@ -688,10 +581,7 @@ export function createExternalWatchEventHandler(
 
 const inFlightEchoVerificationReads = new Map<string, ReturnType<typeof readRuntimeFileContent>>()
 
-// Why: one save echo can arrive as a burst of watcher payloads (SSH poll +
-// event streams), and each verification is a full-file read — on remote
-// transports a network round-trip. Concurrent payloads for the same file
-// share the in-flight read instead of stacking duplicates.
+// Why: one save echo can arrive as a burst of payloads; share the in-flight full-file read so concurrent payloads for the same file don't stack duplicate reads.
 function readFileForEchoVerification(args: {
   runtimeEnvironmentId: string | null | undefined
   filePath: string
@@ -726,8 +616,7 @@ function markTabsChangedOnDisk(fileIds: string[], connectionId: string | undefin
   const state = useAppStore.getState()
   for (const fileId of fileIds) {
     const file = state.openFiles.find((f) => f.id === fileId)
-    // Why: echo verification resolves async — a save or reload may already
-    // have resolved the conflict; the helper only marks still-dirty tabs.
+    // Why: echo verification resolves async — the tab may have been closed since, so only mark files still open.
     if (file) {
       markFileChangedOnDisk(state, file, { connectionId, origin: 'live' })
     }
@@ -744,9 +633,7 @@ function scheduleChangedOnDiskMark(
   }
   const absolutePath = joinPath(notification.worktreePath, notification.relativePath)
   const recentSelfWrite = getRecentSelfWrite(absolutePath, target.runtimeEnvironmentId)
-  // Why: the fs event may be the echo of Orca's own save racing keystrokes
-  // typed during the write. Marking on the echo would show a false "changed
-  // on disk" banner, so verify disk really differs from our last write.
+  // Why: the fs event may be the echo of Orca's own save — verify disk really differs from our last write before showing a "changed on disk" banner.
   if (!recentSelfWrite || recentSelfWrite.content === null) {
     markTabsChangedOnDisk(fileIds, target.connectionId)
     return
@@ -764,8 +651,7 @@ function scheduleChangedOnDiskMark(
       }
     })
     .catch(() => {
-      // Why: unreadable disk state can't disprove an external change — keep
-      // the conflict visible rather than risk a silent overwrite.
+      // Why: unreadable disk state can't disprove an external change — keep the conflict visible rather than risk a silent overwrite.
       markTabsChangedOnDisk(fileIds, target.connectionId)
     })
 }
@@ -782,9 +668,7 @@ function scheduleSelfWriteAwareExternalReload(
   }
 
   const runtimeEnvironmentId = file.runtimeEnvironmentId ?? target.runtimeEnvironmentId
-  // Why: a recent self-write stamp only proves the path changed recently; an
-  // agent can write a newer version inside the same TTL. Compare disk content
-  // with the saved text so we suppress only the echo of Orca's own write.
+  // Why: a self-write stamp only proves recent change; compare disk content so we suppress only Orca's own echo, not a newer agent write in the same TTL.
   void readFileForEchoVerification({
     runtimeEnvironmentId,
     filePath: file.filePath,
@@ -811,8 +695,7 @@ function scheduleSelfWriteAwareExternalReload(
 
 function hasCleanExternalReloadTarget(notification: ExternalWatchNotification): boolean {
   const matching = getOpenFilesForExternalFileChange(useAppStore.getState().openFiles, notification)
-  // Why: one clean target is enough — every notification consumer skips dirty
-  // files per-file, so a dirty sibling tab no longer vetoes the reload.
+  // Why: one clean target is enough — consumers skip dirty files per-file, so a dirty sibling doesn't veto the reload.
   return matching.some((file) => !file.isDirty)
 }
 
@@ -834,11 +717,7 @@ export function getOverflowExternalReloadTargets(
       continue
     }
     if (file.externalMutation) {
-      // Why: overflow gives no per-path resurrection signal, so fall back to
-      // "assume it may exist again" and clear the tombstone before reloading.
-      // If the file is still gone, EditorPanel will preserve the current in-
-      // memory view by showing the read failure instead of leaving a permanent
-      // stale "deleted" badge with no path to recovery.
+      // Why: overflow gives no per-path resurrection signal, so clear the tombstone and let a still-missing file surface as a read failure.
       state.setExternalMutation(file.id, null)
     }
     notifications.push({
@@ -921,14 +800,7 @@ function collectDeletedOpenEditorIds(
  * Returns true if the batched payload contains at least one file-create event
  * whose basename matches a deleted open editor file.
  *
- * Why: a batched fs payload may include unrelated create+delete events. A
- * blanket `events.some(kind === 'create')` would mislabel those as renames.
- * Basename correlation catches the common `git mv` / `mv` case where the
- * filename survives the move. We intentionally do NOT correlate by parent
- * directory because editor save-as-temp patterns (`rm foo.md && touch
- * foo.md.new`) routinely put unrelated creates in the same dir as a delete,
- * which would produce false rename labels. When correlation fails the caller
- * falls back to 'deleted', which is the least misleading default.
+ * Why: correlate by basename only, not parent dir — save-as-temp patterns (`rm foo.md && touch foo.md.new`) put unrelated creates in the same dir and would mislabel deletes as renames.
  */
 function hasRenameCorrelatedCreate(
   payload: FsChangedPayload,
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index 3b83dc4603d..eeadaed9dea 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -241,14 +241,9 @@ const ZOOM_STEP = 0.5
 const PENDING_AGENT_STATUS_RETRY_MS = 100
 const PENDING_AGENT_STATUS_TTL_MS = 15_000
 const MAX_PENDING_AGENT_STATUS_EVENTS = 100
-// Why: mobile driver hydration is async; cap transient replay so a stuck IPC
-// snapshot cannot retain an unbounded startup buffer.
+// Why: mobile driver hydration is async; cap replay so a stuck IPC snapshot can't retain an unbounded startup buffer.
 const MAX_PENDING_MOBILE_STATE_EVENTS = 300
-// Why: a folder rename emits a burst of `worktrees:changed` events while the
-// worktree list lags the on-disk move, so the deletion diff can transiently see
-// the old OR new id as "removed" and tear down the live worktree's PTYs. Protect
-// both ids of a recent rename from that diff for a short grace window — genuine
-// out-of-band deletions still purge once it lapses. Keyed worktreeId -> expiry ms.
+// Why: a rename's event burst lags the on-disk move; shield both ids from the deletion diff for a grace window.
 const WORKTREE_RENAME_PURGE_GRACE_MS = 20_000
 const recentlyRenamedWorktreeIdExpiry = new Map<string, number>()
 let remoteWorkspaceSnapshotApplyDepth = 0
@@ -291,8 +286,7 @@ function focusTerminalInitiatedTab(tabId: string, leafId?: string | null): void
 function activateTerminalInitiatedWorktree(store: AppState, worktreeId: string): void {
   store.setActiveView('terminal')
   store.setActiveWorktree(worktreeId)
-  // Why: CLI/runtime terminal focus is user-visible worktree navigation, so it
-  // must feed both Cmd+J recency and the titlebar back/forward stack.
+  // Why: CLI/runtime terminal focus is user-visible navigation, so feed both Cmd+J recency and the back/forward stack.
   store.markWorktreeVisited(worktreeId)
   if (!store.isNavigatingHistory) {
     store.recordWorktreeVisit(worktreeId)
@@ -571,9 +565,7 @@ async function applyRemoteWorkspaceSnapshot(
     })
     await useAppStore.getState().reconnectPersistedTerminals()
   } finally {
-    // Why: remote terminal reattach can update pty ids and titles just after
-    // hydration. Those local side effects came from the remote snapshot and
-    // must not echo back as a fresh workspace revision.
+    // Why: reattach updates pty ids/titles after hydration; they came from the snapshot, don't echo back as a new revision.
     remoteWorkspaceSnapshotWriteSuppressUntil =
       Date.now() + REMOTE_WORKSPACE_SNAPSHOT_WRITE_SUPPRESS_MS
     remoteWorkspaceSnapshotApplyDepth -= 1
@@ -614,9 +606,7 @@ async function syncRemoteWorkspaceAfterConnect(targetId: string): Promise<void>
 
   useAppStore.getState().markRemoteWorkspaceHydrated(targetId)
   if (hasLocalTabs) {
-    // Why: first connect must read the relay before publishing local tabs.
-    // Otherwise a reconnecting device can overwrite a newer cross-device
-    // workspace snapshot with stale local renderer state.
+    // Why: read the relay before publishing local tabs, or a reconnect can overwrite a newer snapshot with stale local state.
     const session = buildWorkspaceSessionPayload(useAppStore.getState())
     const results = await window.api.remoteWorkspace.setForConnectedTargets({
       session,
@@ -697,8 +687,7 @@ export function buildNewWorkspaceShortcutModalData(
   return {
     telemetrySource: 'shortcut',
     prefilledName: getLinearIssueWorkspaceName(linearIssue),
-    // Why: Cmd+N from a Linear issue should behave like the issue's Start
-    // workspace action; otherwise the agent launches without source context.
+    // Why: Cmd+N from a Linear issue mirrors its Start-workspace action, else the agent launches without source context.
     linkedWorkItem: buildLinearIssueLinkedWorkItem(linearIssue)
   }
 }
@@ -771,8 +760,7 @@ export function buildRuntimeClientEventEnvironmentKey(environmentIds: string[]):
   return [...new Set(environmentIds)].sort().join('\u0000')
 }
 
-/** Ids in `next` not in `previous` — runtime environments that just became
- *  connected. Exported to unit-test the on-connect discovery trigger. */
+/** Ids in `next` not in `previous` — environments that just became connected (exported to unit-test on-connect discovery). */
 export function getNewlyConnectedRuntimeEnvironmentIds(
   previous: readonly string[],
   next: readonly string[]
@@ -781,8 +769,7 @@ export function getNewlyConnectedRuntimeEnvironmentIds(
   return [...new Set(next)].filter((environmentId) => !known.has(environmentId))
 }
 
-/** Ids in `previous` not in `next` — runtime environments whose transport was
- *  just observed down. Their mirrored SSH buckets get downgraded to unknown. */
+/** Ids in `previous` not in `next` — environments whose transport was just observed down. */
 export function getNewlyDisconnectedRuntimeEnvironmentIds(
   previous: readonly string[],
   next: readonly string[]
@@ -809,8 +796,7 @@ async function refreshRuntimeProjectWorktrees(repos: readonly { id: string }[]):
   const failures: { repoId: string; error: unknown }[] = []
   const workerCount = Math.min(RUNTIME_PROJECT_REFRESH_CONCURRENCY, repos.length)
 
-  // Why: one coalesced remote repo event can still represent many repos; keep the
-  // expensive worktree probes bounded so idle refresh never floods the renderer.
+  // Why: one coalesced repo event can represent many repos; bound the probes so idle refresh never floods the renderer.
   await Promise.all(
     Array.from({ length: workerCount }, async () => {
       while (nextIndex < repos.length) {
@@ -853,10 +839,7 @@ export function useIpcEvents(): void {
     const transientClearWatermarkByConnectionId = new Map<string, number>()
     let agentStatusEffectDisposed = false
     let pendingAgentStatusRetryTimer: ReturnType<typeof setTimeout> | null = null
-    // Why: applyAgentStatus -> store.setAgentStatus notifies the store
-    // subscriber synchronously, which re-enters flushPendingAgentStatuses while
-    // the queue is still mid-drain. Guard against that re-entrancy so the same
-    // event is not reprocessed forever (crash 9fc89529: stack overflow).
+    // Why: setAgentStatus notifies synchronously and re-enters this flush mid-drain; guard re-entrancy (crash 9fc89529).
     let isFlushingAgentStatuses = false
 
     unsubs.push(attachMobileMarkdownBridge())
@@ -865,36 +848,24 @@ export function useIpcEvents(): void {
       repoId: string,
       renamed?: { oldWorktreeId: string; newWorktreeId: string }
     ): Promise<void> => {
-      // Why: a folder rename changes the worktree's path-derived id. Re-key every
-      // worktree-scoped map to the new id BEFORE the deletion diff below so the
-      // rename is not mistaken for a deletion that would tear down the live
-      // worktree. Capture active-ness before migrating (which moves the pointer).
+      // Why: capture active-ness before migration moves the pointer; re-key maps before the diff so a rename isn't a deletion.
       const renamedWasActive =
         renamed != null && useAppStore.getState().activeWorktreeId === renamed.oldWorktreeId
       if (renamed) {
-        // Shield both ids from the deletion diff across the rename's event burst
-        // (any event, any order) — the worktree list lags the on-disk move.
+        // Shield both ids from the deletion diff across the rename's event burst — the worktree list lags the on-disk move.
         const expiry = Date.now() + WORKTREE_RENAME_PURGE_GRACE_MS
         recentlyRenamedWorktreeIdExpiry.set(renamed.oldWorktreeId, expiry)
         recentlyRenamedWorktreeIdExpiry.set(renamed.newWorktreeId, expiry)
         useAppStore.getState().migrateWorktreeIdentity(renamed.oldWorktreeId, renamed.newWorktreeId)
       }
-      // Why: diff before vs. after fetchWorktrees to detect server-side
-      // deletions (CLI `orca worktree rm`, other window, out-of-band RPC)
-      // and purge worktree-scoped state for removed ids. Without this,
-      // `ptyIdsByTabId` would retain entries for tabs whose worktree is
-      // gone, and SessionsStatusSegment's `boundPtyIds` set would keep
-      // misclassifying the zombie as bound (design §2c, §4.4).
+      // Why: diff before/after fetch to catch out-of-band deletions and purge worktree state, else zombie ptyId entries leak (design §2c, §4.4).
       const state = useAppStore.getState()
       const before =
         getAuthoritativeDetectedWorktreeIds(state, repoId) ??
         getVisibleWorktreeIdsForRepo(state, repoId)
       await state.fetchWorktrees(repoId)
       await useAppStore.getState().fetchWorktreeLineage()
-      // Why: changing the worktree's id unmounts the active pane without
-      // re-rendering it under the new id. Now that the list has refreshed,
-      // re-activate the renamed worktree so its tab model reconciles and the
-      // pane reconnects — otherwise the tab vanishes until manual re-selection.
+      // Why: an id change unmounts the active pane; re-activate so the tab reconciles, else it vanishes until re-select.
       if (renamedWasActive && renamed) {
         useAppStore.getState().setActiveWorktree(renamed.newWorktreeId)
       }
@@ -909,8 +880,7 @@ export function useIpcEvents(): void {
         if (after.has(id)) {
           continue
         }
-        // A recently renamed worktree's old/new id is not a deletion — its
-        // state moved (or is moving) to the new id; the list just lags.
+        // A recently renamed worktree's old/new id isn't a deletion — its state moved to the new id; the list just lags.
         const graceExpiry = recentlyRenamedWorktreeIdExpiry.get(id)
         if (graceExpiry != null && graceExpiry > now) {
           continue
@@ -945,29 +915,20 @@ export function useIpcEvents(): void {
       options: { allowRuntimeEnvironment: boolean }
     ): Promise<void> => {
       if (!options.allowRuntimeEnvironment && isRuntimeEnvironmentActive()) {
-        // Why: local CLI-created worktree events carry local repo/worktree
-        // ids. Runtime server activation arrives through the remote event
-        // stream and is allowed through this helper separately.
+        // Why: local CLI worktree events carry local ids; runtime activation comes via the remote stream, allowed separately.
         return
       }
       const existedBeforeFetch = Boolean(useAppStore.getState().getKnownWorktreeById(worktreeId))
-      // Why: fetch worktrees first so the activation helper can resolve
-      // the CLI-created worktree via findWorktreeById — it arrived from
-      // the main process and is not yet in the renderer state.
+      // Why: fetch first so activation can resolve the CLI-created worktree; it arrived from main, not yet in renderer state.
       await useAppStore.getState().fetchWorktrees(repoId)
       const existsAfterFetch = Boolean(useAppStore.getState().getKnownWorktreeById(worktreeId))
-      // Why: route through activateAndRevealWorktree so CLI-created
-      // worktrees share the canonical activation path with UI-created
-      // ones. This records the visit in the back/forward history stack
-      // (recordWorktreeVisit), without which the nav buttons would
-      // ignore the CLI-driven workspace switch.
+      // Why: use the canonical activation path so the CLI switch records a back/forward visit, or the nav buttons ignore it.
       activateAndRevealWorktree(worktreeId, {
         ...(setup ? { setup } : {}),
         ...(startup ? { startup } : {}),
         ...(defaultTabs ? { defaultTabs } : {}),
         ...(!existedBeforeFetch && existsAfterFetch ? { sidebarRevealBehavior: 'auto' } : {}),
-        // Why: this activation already came from the host runtime event stream.
-        // Echoing it back as worktree.activate can create a selection loop.
+        // Why: this activation came from the host runtime stream; echoing it back can create a selection loop.
         notifyHostRuntime: false
       })
     }
@@ -985,10 +946,7 @@ export function useIpcEvents(): void {
     const runtimeProjectRefreshScheduler = createRuntimeProjectRefreshScheduler({
       refresh: async (environmentId) => {
         if (!isPairedWebClientWindow()) {
-          // Why: mirrored SSH-backed workspaces read the owning environment's
-          // SSH bucket; refresh it whenever the environment (re)connects so a
-          // pre-drop snapshot can't keep a reconnect overlay stale. The web
-          // client mirrors host SSH state through the global store instead.
+          // Why: refresh the env's SSH bucket on (re)connect so a pre-drop snapshot can't keep a reconnect overlay stale.
           void hydrateRuntimeEnvironmentSshState(environmentId, { force: true }).catch(() => {})
         }
         const repos = await useAppStore.getState().fetchRuntimeEnvironmentRepos(environmentId)
@@ -1000,8 +958,7 @@ export function useIpcEvents(): void {
       }
     })
 
-    // Assigned later in this effect, next to the ssh.onStateChanged wiring;
-    // events can't fire before that because subscriptions attach asynchronously.
+    // Assigned later (by the ssh.onStateChanged wiring); safe because subscriptions attach asynchronously.
     let handleSshStateChangedEvent: ((data: { targetId: string; state: unknown }) => void) | null =
       null
 
@@ -1011,10 +968,7 @@ export function useIpcEvents(): void {
         return
       }
       if (event.type === 'sshStateChanged') {
-        // Why: a paired web client mirrors host SSH state in the global store —
-        // its whole ssh.* API routes to that one host (STA-1468). A desktop
-        // client owns a local SSH surface those maps must keep describing, so a
-        // remote host's state goes into that environment's own bucket instead.
+        // Why: a paired web client mirrors host SSH state globally (STA-1468); desktop routes it to the env's own bucket.
         if (isPairedWebClientWindow()) {
           handleSshStateChangedEvent?.({ targetId: event.targetId, state: event.state })
         } else {
@@ -1048,18 +1002,12 @@ export function useIpcEvents(): void {
       getDesiredEnvironmentIds: getRuntimeClientEventEnvironmentIds,
       subscribe: (environmentId, onEvent, onError) =>
         subscribeRuntimeClientEvents(environmentId, onEvent, onError, () => {
-          // Why: worktreesChanged/reposChanged during the transport gap are
-          // lost, not queued. A quick drop can replay without ever flipping the
-          // env unreachable, so the reachability-transition refetch never runs
-          // and a server-created worktree stays invisible until relaunch
-          // (#7970). The scheduler debounces, so this stays cheap.
+          // Why: events during a transport gap are lost; a quick reconnect won't flip unreachable, so refetch (#7970).
           runtimeProjectRefreshScheduler.request(environmentId)
           if (isPairedWebClientWindow()) {
             return
           }
-          // Why: sshStateChanged events during the transport gap are lost, so
-          // the pre-drop bucket may hold a stale "connected". Downgrade to
-          // unknown, then refetch the authoritative state.
+          // Why: sshStateChanged events during the transport gap are lost, so downgrade the possibly-stale bucket, then refetch.
           useAppStore.getState().markEnvironmentSshStateStale(environmentId)
           void hydrateRuntimeEnvironmentSshState(environmentId, { force: true }).catch(() => {})
         }),
@@ -1067,11 +1015,7 @@ export function useIpcEvents(): void {
     })
 
     runtimeClientEventsSync.sync()
-    // Why: PR #2 removed desktop's eager session-sync discovery and there is no
-    // on-connect repo fetch, so remote projects only appeared after the user
-    // opened the Add-Project dropdown. Seed discovery for runtimes already
-    // connected at mount, and for each newly-connected one below. The scheduler
-    // debounces/throttles, so this stays cheap even with chatty status updates.
+    // Why: no on-connect repo fetch (PR #2); seed discovery for connected runtimes or remote projects hide until Add-Project.
     let runtimeClientEventEnvironmentIds = getRuntimeClientEventEnvironmentIds()
     for (const environmentId of runtimeClientEventEnvironmentIds) {
       runtimeProjectRefreshScheduler.request(environmentId)
@@ -1124,9 +1068,7 @@ export function useIpcEvents(): void {
       window.api.repos.onChanged(() => {
         const state = useAppStore.getState()
         if (isRuntimeEnvironmentActive()) {
-          // Why: the all-host sidebar includes local repos even when a runtime
-          // is focused, so local store changes must refresh the local slice
-          // without dropping the runtime-owned slices already shown.
+          // Why: the all-host sidebar shows local repos even under a runtime; refresh the local slice, keep runtime slices.
           void (async () => {
             await state.fetchReposForAllHosts()
             await state.fetchProjectGroupsForAllHosts()
@@ -1147,12 +1089,10 @@ export function useIpcEvents(): void {
           renamed?: { oldWorktreeId: string; newWorktreeId: string }
         }) => {
           if (isRuntimeEnvironmentActive()) {
-            // Why: local worktree events carry local repo ids. Fetching the
-            // active runtime with those ids can purge or overwrite server state.
+            // Why: local worktree events carry local repo ids; fetching the runtime with them can purge or overwrite server state.
             return
           }
-          // A folder rename changes the worktree id; handleWorktreesChanged
-          // re-keys state and shields it from the deletion diff (see there).
+          // A folder rename changes the worktree id; handleWorktreesChanged re-keys state and shields it from the deletion diff.
           worktreeChangeRefreshQueue.enqueue(data)
         }
       )
@@ -1192,9 +1132,7 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: drive each background creation's status panel by routing the main
-    // process's two-phase progress to its pending entry via the correlation id.
-    // Guarded with `?.` so a stale preload bundle doesn't crash the listener set.
+    // Why: route main's two-phase creation progress to each pending entry by correlation id (?. guards stale preload).
     unsubs.push(
       window.api.worktrees.onCreateProgress?.((data) => {
         if (!data.creationId) {
@@ -1218,9 +1156,7 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: a tray/menu-bar "Settings…" click can fire before this listener
-    // attaches on a fresh window; consume any intent queued for us. Guarded
-    // with `?.` so a stale preload bundle doesn't crash the listener set.
+    // Why: a tray "Settings…" click can fire before this attaches; consume any queued intent (?. guards stale preload).
     void window.api.ui
       .consumePendingOpenSettings?.()
       .then((open) => {
@@ -1242,11 +1178,7 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: the View > Appearance menu toggles settings directly in main (so
-    // checkbox state reflects the persisted value without a round-trip) and
-    // broadcasts the change. Merge it into the store so the sidebar and
-    // titlebar re-render immediately instead of waiting for the next
-    // fetchSettings() call.
+    // Why: View > Appearance toggles settings in main and broadcasts; merge into the store for an immediate re-render.
     unsubs.push(
       window.api.settings.onChanged((updates) => {
         const store = useAppStore.getState()
@@ -1266,9 +1198,7 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: UI view-state (group/sort/filters, collapsed groups, etc.) is shared
-    // with mobile via the ui.set RPC. When mobile changes it, main broadcasts so
-    // the desktop re-hydrates and the sidebar reflects it live — bi-directional.
+    // Why: UI view-state is shared with mobile via ui.set; re-hydrate so mobile changes reflect live in the desktop sidebar.
     unsubs.push(
       window.api.ui.onStateChanged((ui) => {
         useAppStore.getState().hydratePersistedUI(ui, 'sync')
@@ -1411,10 +1341,7 @@ export function useIpcEvents(): void {
     unsubs.push(
       window.api.ui.onWorktreeHistoryNavigate((direction) => {
         const store = useAppStore.getState()
-        // Why: mirror the button-visibility rule — worktree history navigation
-        // is only meaningful in the terminal (worktree) view. Settings/Tasks
-        // transitions aren't worktree activations and the buttons are hidden,
-        // so the shortcut no-ops there too.
+        // Why: mirror button visibility — worktree history nav is only meaningful in the terminal view, so no-op elsewhere.
         if (store.activeView !== 'terminal') {
           return
         }
@@ -1518,9 +1445,7 @@ export function useIpcEvents(): void {
                     return candidate.ptyId == null && candidatePtyIds.length === 0
                   })
                 : undefined
-            // Why: runtime fallback can reveal a PTY for a renderer-created
-            // pending tab; that id collision is adoption only until another
-            // PTY is already associated with the hinted tab.
+            // Why: runtime fallback reveals a PTY for a renderer-created pending tab; adopt only when the hinted tab has no PTY yet.
             const reusedTab = existingTab ?? splitTargetTab ?? hintedPendingTab
             const tab =
               reusedTab ??
@@ -1531,8 +1456,7 @@ export function useIpcEvents(): void {
                     ...(launchAgent
                       ? {
                           launchAgent,
-                          // Why: a paired client resolved explicit mode before
-                          // PTY materialization; only omitted mode uses host defaults.
+                          // Why: a paired client resolved explicit mode before PTY materialization; only omitted mode uses host defaults.
                           ...(viewMode
                             ? { viewMode }
                             : initialAgentTabViewModeProps(store.settings, {
@@ -1545,9 +1469,7 @@ export function useIpcEvents(): void {
                         }
                       : {}),
                     ...(cwd ? { startupCwd: cwd } : {}),
-                    // Why: tabId hint comes from CLI-spawned PTYs whose env
-                    // already has the pane key baked in. Adopting the tab under
-                    // the same id keeps hook-event attribution working.
+                    // Why: CLI-spawned PTYs bake the pane key into env; adopt the same tab id so hook-event attribution keeps working.
                     ...(tabId !== undefined ? { id: tabId } : {})
                   })
                 : store.createTab(
@@ -1564,10 +1486,7 @@ export function useIpcEvents(): void {
                           ...(cwd ? { startupCwd: cwd } : {})
                         }
                   ))
-            // Why: when an existing tab already owns this ptyId, we reuse it instead of
-            // minting a new one — but the PTY env already carries a paneKey from main.
-            // If the existing tab id doesn't match the hint, hook attribution degrades
-            // for that PTY's lifetime. Warn so this is visible during development.
+            // Why: a reused tab whose id differs from the hint breaks the PTY's baked-in paneKey attribution; warn during dev.
             if (tabId !== undefined && tab.id !== tabId) {
               console.warn(
                 `[onCreateTerminal] tabId hint ${tabId} ignored for ptyId ${ptyId}; existing tab ${tab.id} adopted instead (hook attribution will degrade for this terminal)`
@@ -1581,10 +1500,7 @@ export function useIpcEvents(): void {
               store.revealWorktreeInSidebar(worktreeId)
               focusTerminalInitiatedTab(tab.id, leafId)
             }
-            // Why: only stamp the runtime-supplied title on freshly created tabs.
-            // Existing tabs may have a user customTitle (set via UI rename) that
-            // the runtime's stored title would otherwise silently overwrite on
-            // every focus.
+            // Why: only stamp the runtime title on fresh tabs; reused tabs may have a user customTitle it would overwrite on focus.
             if (title && !reusedTab) {
               store.setTabCustomTitle(tab.id, title, { recordInteraction: false })
             }
@@ -1603,9 +1519,7 @@ export function useIpcEvents(): void {
                 store.clearAgentLaunchConfig(launchPaneKey)
               }
               if (splitFromLeafId) {
-                // Why: runtime-spawned split PTYs already carry the parent tab's
-                // paneKey. Reusing the existing tab preserves native split-pane
-                // behavior instead of letting createTab mint a collision tab.
+                // Why: runtime split PTYs already carry the parent tab's paneKey, so reuse the tab instead of minting a collision tab.
                 store.updateTabPtyId(tab.id, ptyId)
                 const existingLayout = store.terminalLayoutsByTabId?.[tab.id]
                 const sourcePtyId = existingLayout?.ptyIdsByLeafId?.[splitFromLeafId]
@@ -1636,9 +1550,7 @@ export function useIpcEvents(): void {
                   })
                 )
               } else {
-                // Why: CLI/runtime-spawned PTYs emit hook events before a hidden
-                // tab mounts TerminalPane, so the adopted UUID leaf must exist
-                // in layout state for paneKey validation to accept them.
+                // Why: CLI/runtime PTYs emit hook events before the tab mounts, so the leaf must exist in layout for paneKey validation.
                 const existingLayout = reusedTab
                   ? activateExistingLeafInLayout(
                       store.terminalLayoutsByTabId?.[tab.id],
@@ -1684,15 +1596,13 @@ export function useIpcEvents(): void {
       )
     )
 
-    // Why: background-mounting a mobile-subscribed tab attaches a PTY that this
-    // renderer never mounted, without navigating the desktop (STA-1840).
+    // Why: background-mount a mobile-subscribed tab's PTY without navigating the desktop (STA-1840).
     unsubs.push(
       window.api.ui.onRequestTerminalTabMount(({ worktreeId, tabId, ptyId }) => {
         if (!worktreeId) {
           return
         }
-        // Why: synthetic pty handles need persisted-tab resolution, but a miss
-        // must not mount every saved terminal in a large hidden worktree.
+        // Why: synthetic pty handles need persisted-tab resolution; a miss must not mount every saved tab in a hidden worktree.
         const mount = planMobileTerminalTabMount(
           useAppStore.getState(),
           {
@@ -1710,14 +1620,11 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: CLI-driven terminal creation sends a request and waits for the
-    // tabId reply so it can resolve a handle the caller can use immediately.
-    // This mirrors the browser's onRequestTabCreate/replyTabCreate pattern.
+    // Why: CLI-driven terminal creation waits for the tabId reply so it can hand the caller a usable handle immediately.
     unsubs.push(
       window.api.ui.onRequestTerminalCreate((data) => {
         try {
-          // Why: runtime-session requests are host-owned tabs materialized by this
-          // renderer, not ordinary local creates that bypass remote runtime mode.
+          // Why: runtime-session requests are host-owned tabs materialized by this renderer, not ordinary local creates.
           if (isRuntimeEnvironmentActive() && data.source !== 'runtime-session') {
             window.api.ui.replyTerminalCreate({
               requestId: data.requestId,
@@ -1743,8 +1650,7 @@ export function useIpcEvents(): void {
           if (shouldActivate) {
             activateTerminalInitiatedWorktree(store, worktreeId)
           }
-          // Why: the paired launch client already resolved the initial mode, so
-          // its explicit choice must win over this host renderer's local default.
+          // Why: the paired launch client already resolved the mode, so its choice wins over the host renderer's local default.
           const tabOptions = data.launchAgent
             ? {
                 ...(shouldActivate ? {} : { activate: false, recordInteraction: false }),
@@ -1770,8 +1676,7 @@ export function useIpcEvents(): void {
                 }
           const tab = store.createTab(worktreeId, data.targetGroupId, undefined, tabOptions)
           if (!shouldActivate) {
-            // Why: renderer-backed Codex startup must mount its new TerminalPane
-            // without switching UI or connecting every saved tab in the worktree.
+            // Why: renderer-backed Codex startup must mount its new TerminalPane without switching UI or connecting every saved tab.
             requestBackgroundTerminalWorktreeMount({ worktreeId, tabIds: [tab.id] })
           }
           if (data.afterTabId) {
@@ -1897,8 +1802,7 @@ export function useIpcEvents(): void {
         const browserTarget = resolveBrowserSessionTabTarget(store, worktreeId, tabId)
         if (!tab) {
           if (browserTarget) {
-            // Why: older/mobile fallback snapshots can identify browser tabs
-            // by workspace id when no unified tab wrapper exists.
+            // Why: older/mobile fallback snapshots identify browser tabs by workspace id when no unified tab wrapper exists.
             store.setActiveWorktree(worktreeId)
             store.markWorktreeVisited(worktreeId)
             store.setActiveView('terminal')
@@ -1914,9 +1818,7 @@ export function useIpcEvents(): void {
         store.focusGroup(worktreeId, tab.groupId)
         store.activateTab(tab.id)
         if (browserTarget) {
-          // Why: mobile session tabs reuse this IPC for renderer-owned
-          // unified tabs. Browser tabs need their own active-page state,
-          // not the editor file activation path.
+          // Why: browser tabs need their own active-page state, not the editor file activation path.
           store.setActiveBrowserTab(browserTarget.workspaceId)
           store.setActiveTabType('browser')
         } else {
@@ -1974,9 +1876,7 @@ export function useIpcEvents(): void {
           store.setActiveWorktree(worktreeId)
           store.markWorktreeVisited(worktreeId)
           store.setActiveView('terminal')
-          // Why: mobile only sends a desktop-backed path. The renderer owns
-          // editor tab creation so grouped tab order and markdown bridges update
-          // through the same store path as desktop File Explorer.
+          // Why: renderer owns tab creation so grouped order and markdown bridges share the desktop File Explorer's store path.
           store.openFile({
             filePath,
             relativePath,
@@ -1999,9 +1899,7 @@ export function useIpcEvents(): void {
           store.setActiveWorktree(worktreeId)
           store.markWorktreeVisited(worktreeId)
           store.setActiveView('terminal')
-          // Why: mobile renders diff tabs from diff metadata. The desktop
-          // markdown Changes-mode shortcut is editor-local and would publish
-          // plain markdown content back to mobile.
+          // Why: mobile renders diffs from metadata; the editor-local Changes shortcut would send plain markdown back to mobile.
           store.openDiff(worktreeId, filePath, relativePath, language, staged, {
             runtimeEnvironmentId
           })
@@ -2014,9 +1912,7 @@ export function useIpcEvents(): void {
     unsubs.push(
       window.api.ui.onCloseTerminal(({ tabId, paneRuntimeId }) => {
         if (paneRuntimeId != null) {
-          // Why: when targeting a specific pane in a split layout, dispatch to the
-          // lifecycle hook so PaneManager.closePane() handles sibling promotion.
-          // The lifecycle hook falls through to closeTab() if this is the last pane.
+          // Why: route pane closes via the lifecycle hook for sibling promotion (falls through to closeTab on the last pane).
           const detail: CloseTerminalPaneDetail = { tabId, paneRuntimeId }
           window.dispatchEvent(new CustomEvent(CLOSE_TERMINAL_PANE_EVENT, { detail }))
         } else {
@@ -2025,8 +1921,7 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: during an in-place renderer reload, an older preload can briefly
-    // remain installed. Keep the new request listener additive at that seam.
+    // Why: during an in-place renderer reload an older preload can linger; keep this listener additive at that seam.
     if (window.api.ui.onTerminalTabCloseRequest) {
       unsubs.push(
         window.api.ui.onTerminalTabCloseRequest(({ requestId, tabId }) => {
@@ -2067,8 +1962,7 @@ export function useIpcEvents(): void {
 
     unsubs.push(
       window.api.ui.onResumeSleepingAgents(({ worktreeId }) => {
-        // Why: a phone opened this worktree; wake its slept agents on the host
-        // renderer navigation-free (no desktop worktree/tab/view change).
+        // Why: a phone opened this worktree; wake its slept agents without changing the desktop's worktree/tab/view.
         backgroundSleepingAgentWakeDispatcher.request(worktreeId)
       })
     )
@@ -2123,10 +2017,7 @@ export function useIpcEvents(): void {
       unsubs.push(unsubscribeCertificateFailure)
     }
 
-    // Why: agent-browser drives navigation via CDP, bypassing Electron's webview
-    // event system. The renderer's did-navigate listener never fires for those
-    // navigations, so the Zustand store (address bar, tab title) stays stale.
-    // This IPC pushes the live URL/title from main after goto/click/back/reload.
+    // Why: agent-browser navigates via CDP so did-navigate never fires; this IPC pushes live URL/title to the stale store.
     unsubs.push(
       window.api.browser.onNavigationUpdate(({ browserPageId, url, title }) => {
         if (isRuntimeEnvironmentActive()) {
@@ -2138,9 +2029,7 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: browser webviews only start their guest process when the container
-    // has display != none. Main sends this before browser automation commands
-    // so persisted hidden tabs mount without changing the user's active pane.
+    // Why: webviews start their guest only when shown; sent pre-automation so hidden tabs mount without moving the active pane.
     unsubs.push(
       window.api.browser.onActivateView(({ worktreeId, browserPageId }) => {
         if (isRuntimeEnvironmentActive()) {
@@ -2150,26 +2039,15 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: `orca tab switch --focus` lands here after the bridge's state-only
-    // `tabSwitch`. We deliberately DO NOT call `setActiveWorktree` — multiple
-    // agents drive browsers in parallel worktrees, so a global focus call from
-    // one agent's tab switch would steal the user's view from whichever
-    // worktree they're actually reading. Instead `focusBrowserTabInWorktree`
-    // updates the targeted worktree's per-worktree state in place; globals
-    // (activeBrowserTabId, activeTabType) only flip when the user is already
-    // on the targeted worktree. Cross-worktree --focus calls are silent
-    // pre-staging for whenever the user next visits that worktree.
+    // Why: `orca tab switch --focus` must NOT call setActiveWorktree — a global focus from one agent's parallel-worktree switch would steal the user's view.
+    // focusBrowserTabInWorktree updates per-worktree state in place; globals flip only when the user is already on the targeted worktree.
     unsubs.push(
       window.api.browser.onPaneFocus(({ worktreeId, browserPageId }) => {
         if (isRuntimeEnvironmentActive()) {
           return
         }
         const store = useAppStore.getState()
-        // Why: main sends `worktreeId: null` if the tab closed between the
-        // bridge resolving tabSwitch and getWorktreeIdForTab running. Falling
-        // back to activeWorktreeId means a stale page id in another worktree
-        // is silently ignored by focusBrowserTabInWorktree (page not found
-        // in its tabsForWorktree.find), which is the intended no-op.
+        // Why: worktreeId is null if the tab closed mid-switch; the activeWorktreeId fallback makes the focus call a safe no-op for a stale page id.
         const targetWt = worktreeId ?? store.activeWorktreeId
         if (!targetWt) {
           return
@@ -2190,14 +2068,12 @@ export function useIpcEvents(): void {
         if (getRuntimeEnvironmentIdForWorktree(store, sourcePage.worktreeId)) {
           return
         }
-        // Why: only the renderer owns Orca's tab model. Creating the tab with
-        // the default activation behavior brings the clicked link forward.
+        // Why: only the renderer owns Orca's tab model, so main delegates link-open here.
         store.createBrowserTab(sourcePage.worktreeId, url, { title: url })
       })
     )
 
-    // Shortcut forwarding for embedded browser guests whose webContents
-    // capture keyboard focus and bypass the renderer's window-level keydown.
+    // Why: embedded browser guests capture keyboard focus and bypass window-level keydown, so shortcuts are forwarded via IPC.
     unsubs.push(
       window.api.ui.onNewBrowserTab(() => {
         const store = useAppStore.getState()
@@ -2217,9 +2093,7 @@ export function useIpcEvents(): void {
               return
             }
             void (async () => {
-              // Why: paired web browser tabs are host-owned and arrive through
-              // session.tabs. On RPC failure we leave local state unchanged so
-              // the next host snapshot remains authoritative.
+              // Why: paired web tabs are host-owned; on RPC failure leave local state so the next host snapshot stays authoritative.
               await createWebRuntimeSessionBrowserTab({
                 worktreeId,
                 environmentId,
@@ -2264,8 +2138,7 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: emulator IPC is additive. Older paired clients and partial test
-    // preload mocks should not crash the whole event hook when it is absent.
+    // Why: emulator IPC is additive; guard so older clients or partial preload mocks don't crash the hook when it's absent.
     const unsubscribeNewSimulatorTab = window.api.ui.onNewSimulatorTab?.(() => {
       if (isRuntimeEnvironmentActive()) {
         return
@@ -2287,8 +2160,7 @@ export function useIpcEvents(): void {
           return
         }
         if (isManualSimulatorLaunchPending(worktreeId)) {
-          // Why: manual launches pre-attach first so the ready pane can be
-          // created in the right split instead of as a hidden tab in this group.
+          // Why: manual launches pre-attach so the ready pane opens in the right split, not as a hidden tab in this group.
           rememberPrelaunchedSimulatorSession(worktreeId, info)
           return
         }
@@ -2317,15 +2189,12 @@ export function useIpcEvents(): void {
       unsubs.push(unsubscribeEmulatorPaneFocus)
     }
 
-    // Why: CLI-driven tab creation sends a request with a specific worktreeId and
-    // url. The renderer creates the tab and replies with the page ID so the
-    // main process can wait for registerGuest before returning to the CLI.
+    // Why: reply with the page ID so main can await registerGuest before returning to the CLI.
     unsubs.push(
       window.api.ui.onRequestTabCreate((data) => {
         try {
           if (isRuntimeEnvironmentActive()) {
-            // Why: browser automation targets client-local Electron webviews.
-            // Runtime agents cannot see or control those surfaces.
+            // Why: browser automation targets client-local Electron webviews that runtime agents can't see or control.
             window.api.ui.replyTabCreate({
               requestId: data.requestId,
               error: translate(
@@ -2344,9 +2213,7 @@ export function useIpcEvents(): void {
             })
             return
           }
-          // Why: CLI-created tabs should land in the same group as the active
-          // browser tab, not the terminal's group (which is typically the
-          // UI-active group when an agent is running commands).
+          // Why: CLI-created tabs should land in the active browser tab's group, not the terminal's UI-active group.
           const activeBrowserTabId = store.activeBrowserTabIdByWorktree[worktreeId]
           const activeBrowserUnifiedTab = activeBrowserTabId
             ? (store.unifiedTabsByWorktree[worktreeId] ?? []).find(
@@ -2354,10 +2221,8 @@ export function useIpcEvents(): void {
               )
             : undefined
 
-          // Why: a user-initiated open (data.activate, e.g. mobile tapping an HTML
-          // path) foregrounds the tab so it lands in the active group's order and
-          // publishes to mobile in the right place. Agent/automation opens stay in
-          // the background (activate:false) in the active browser group.
+          // Why: a user-initiated open (data.activate, e.g. mobile tapping an HTML path) foregrounds the tab so it lands in active-group order and publishes to mobile.
+          // Agent/automation opens stay in the background (activate:false) in the active browser group.
           const workspace = store.createBrowserTab(worktreeId, data.url, {
             title: data.url,
             targetGroupId: data.activate ? undefined : activeBrowserUnifiedTab?.groupId,
@@ -2365,9 +2230,7 @@ export function useIpcEvents(): void {
             sessionPartition: data.sessionPartition,
             activate: data.activate === true
           })
-          // Why: registerGuest fires with the page ID (not workspace ID) as
-          // browserPageId. Return the page ID so waitForTabRegistration can
-          // correlate correctly.
+          // Why: registerGuest fires with the page ID, not the workspace ID; return it so waitForTabRegistration can correlate.
           const pages = useAppStore.getState().browserPagesByWorkspace[workspace.id] ?? []
           const browserPageId = pages[0]?.id ?? workspace.id
           acquireBrowserAutomationBootstrapLease(worktreeId, browserPageId)
@@ -2415,8 +2278,7 @@ export function useIpcEvents(): void {
             })
             return
           }
-          // Why: a workspace can host multiple browser pages; profile switch must
-          // tear down every sibling webview, not just the one referenced by the IPC.
+          // Why: a workspace may host several browser pages; profile switch must tear down all sibling webviews, not just the IPC's.
           const workspacePages = store.browserPagesByWorkspace[owningWorkspace.id] ?? []
           if (workspacePages.length > 0) {
             for (const page of workspacePages) {
@@ -2491,11 +2353,8 @@ export function useIpcEvents(): void {
             })
             return
           }
-          // Why: the bridge stores tabs keyed by browserPageId (which is the page
-          // ID from registerGuest), but closeBrowserTab expects a workspace ID. If
-          // tabToClose is a page ID, close only that page unless it is the
-          // last page in its workspace. The CLI's `tab close --page` contract
-          // targets one browser page, not the entire workspace tab.
+          // Why: the bridge keys tabs by browserPageId, but closeBrowserTab expects a workspace id.
+          // Per the CLI's `tab close --page` contract, close only that page unless it is the last in its workspace.
           const isWorkspaceId = Object.values(store.browserTabsByWorktree)
             .flat()
             .some((ws) => ws.id === tabToClose)
@@ -2575,9 +2434,7 @@ export function useIpcEvents(): void {
           }
           const newTab = store.createTab(worktreeId)
           store.setActiveTabType('terminal')
-          // Why: replicate the full reconciliation from Terminal.tsx handleNewTab
-          // so the new tab appends at the visual end instead of jumping to index 0
-          // when tabBarOrderByWorktree is unset (e.g. restored worktrees).
+          // Why: mirror Terminal.tsx handleNewTab so a new tab appends at the end, not index 0, when tabBarOrder is unset.
           const freshStore = useAppStore.getState()
           const currentTerminals = freshStore.tabsByWorktree[worktreeId] ?? []
           const currentEditors = freshStore.openFiles.filter((f) => f.worktreeId === worktreeId)
@@ -2685,8 +2542,7 @@ export function useIpcEvents(): void {
         useAppStore.getState().setRateLimitsFromPush(state as RateLimitState)
       })
     )
-    // Why: the startup get is a fallback; a live push may already include
-    // system-default account snapshots that an older get result lacks.
+    // Why: the startup get is a fallback; a live push may already include account snapshots the get result lacks.
     window.api.rateLimits.get().then((state) => {
       initialRateLimitsSnapshotPending = false
       if (receivedRateLimitsPushBeforeInitialSnapshot) {
@@ -2704,16 +2560,12 @@ export function useIpcEvents(): void {
       unsubs.push(unsubscribeWorkspaceSpaceProgress)
     }
 
-    // Track SSH connection state changes so the renderer can show
-    // disconnected indicators on remote worktrees.
-    // Why: hydrate initial state for all known targets so worktree cards
-    // reflect the correct connected/disconnected state on app launch.
+    // Why: hydrate initial SSH state for all targets so worktree cards show correct connect state on launch.
     void (async () => {
       try {
         const targets = await window.api.ssh.listTargets()
         useAppStore.getState().setSshTargetsMetadata(targets)
-        // Why: ghost-host UI (removed target still referenced by a workspace)
-        // shows a friendly name from the removal tombstones instead of the raw id.
+        // Why: ghost-host UI (removed target still referenced by a workspace) shows a tombstone name instead of the raw id.
         try {
           const removedLabels = await window.api.ssh.listRemovedTargetLabels()
           useAppStore.getState().setRemovedSshTargetLabels(removedLabels)
@@ -2724,18 +2576,13 @@ export function useIpcEvents(): void {
           const state = await window.api.ssh.getState({ targetId: target.id })
           if (state) {
             useAppStore.getState().setSshConnectionState(target.id, state as SshConnectionState)
-            // Why: if the renderer reattaches while an SSH session is alive
-            // (e.g. window re-creation or reload), forwarded and detected ports
-            // are only populated via push events. Fetch current snapshots so the
-            // Ports panel doesn't show empty for an active session.
+            // Why: ports arrive only via push events; on reattach to a live session fetch snapshots or the Ports panel shows empty.
             if ((state as SshConnectionState).status === 'connected') {
               const [forwards, detected] = await Promise.all([
                 window.api.ssh.listPortForwards({ targetId: target.id }),
                 window.api.ssh.listDetectedPorts({ targetId: target.id })
               ])
-              // Why: if the session disconnected while we were awaiting the
-              // snapshot, the disconnect handler already cleared port state.
-              // Applying stale data here would resurrect a dead session's ports.
+              // Why: if the session disconnected while awaiting the snapshot, applying it would resurrect a dead session's ports.
               const currentState = useAppStore.getState().sshConnectionStates.get(target.id)
               if (currentState?.status === 'connected') {
                 useAppStore.getState().setPortForwards(target.id, forwards)
@@ -2785,21 +2632,14 @@ export function useIpcEvents(): void {
       const remoteRepos = store.repos.filter((r) => r.connectionId === targetId)
 
       if (['disconnected', 'auth-failed', 'reconnection-failed', 'error'].includes(state.status)) {
-        // Why: the remote agent list is tied to a live SSH connection. On
-        // disconnect the relay is gone, so clear the cached list and dedup
-        // promise. When the user reconnects and opens the quick-launch menu,
-        // ensureRemoteDetectedAgents will re-detect against the new relay.
+        // Why: remote agent list is tied to a live relay; clear on disconnect so reconnect re-detects against the new relay.
         store.clearRemoteDetectedAgents(targetId)
 
-        // Why: defensive — clear port forward and detected port state in case
-        // the broadcast from removeAllForwards races with the state change.
+        // Why: defensive — clear port state in case the removeAllForwards broadcast races this state change.
         store.clearPortForwards(targetId)
         store.setDetectedPorts(targetId, [])
 
-        // Why: an explicit disconnect or terminal failure tears down the SSH
-        // PTY provider without emitting per-PTY exit events. Clear the stale
-        // PTY ids in renderer state so a later reconnect remounts TerminalPane
-        // instead of keeping a dead remote PTY attached to the tab.
+        // Why: SSH teardown fires no per-PTY exit events; clear stale PTY ids so reconnect remounts rather than reattach a dead PTY.
         const remoteWorktreeIds = new Set(
           Object.values(store.worktreesByRepo)
             .flat()
@@ -2819,11 +2659,8 @@ export function useIpcEvents(): void {
       if (state.status === 'connected') {
         void Promise.all(remoteRepos.map((r) => store.fetchWorktrees(r.id))).then(async () => {
           await useAppStore.getState().fetchWorktreeLineage()
-          // Why: terminal panes that failed to spawn (no PTY provider on cold
-          // start) or whose deferred reattach never ran sit inert. Bumping
-          // generation forces TerminalPane to remount and retry; the remount
-          // routes through the deferred-connect gate, which reattaches the
-          // stranded session or spawns fresh now that the provider exists.
+          // Why: panes that never spawned (no PTY provider at cold start) or whose deferred reattach never ran sit inert.
+          // Bumping generation remounts TerminalPane so the deferred-connect gate reattaches or spawns fresh now that the provider exists.
           const freshStore = useAppStore.getState()
           const remoteRepoIds = new Set(remoteRepos.map((r) => r.id))
           const worktreeIds = Object.values(freshStore.worktreesByRepo)
@@ -2869,13 +2706,10 @@ export function useIpcEvents(): void {
       const stateEventId = ++sshTargetStateEventId
       latestSshTargetStateEventByTargetId.set(data.targetId, stateEventId)
       if (!store.sshTargetLabels.has(data.targetId)) {
-        // Why: targets added after boot aren't in the labels map, while
-        // removed targets can still race a final disconnect event. Confirm
-        // with main before mutating renderer state for an unknown target id.
+        // Why: unknown target id could be a post-boot add or a removed target racing disconnect; confirm with main first.
         window.api.ssh
           .listTargets()
-          // Why: this refresh is now a deletion guard, not just a label fetch.
-          // Retry once so a transient IPC failure does not drop a real added-target event.
+          // Why: refresh doubles as a deletion guard; retry once so a transient IPC failure doesn't drop a real added-target event.
           .catch(() => window.api.ssh.listTargets())
           .then((targets) => {
             if (latestSshTargetStateEventByTargetId.get(data.targetId) !== stateEventId) {
@@ -2884,8 +2718,7 @@ export function useIpcEvents(): void {
             latestSshTargetStateEventByTargetId.delete(data.targetId)
             const latestStore = useAppStore.getState()
             if (!targets.some((target) => target.id === data.targetId)) {
-              // Why: disconnect/state events can race after target removal.
-              // Treat absence from main's target list as deletion, not a new target.
+              // Why: state events can race after target removal; absence from main's target list means deletion, not a new target.
               latestStore.clearRemovedSshTargetState(data.targetId)
               return
             }
@@ -2931,8 +2764,7 @@ export function useIpcEvents(): void {
       unsubs.push(
         window.api.remoteWorkspace.onChanged((event) => {
           void (async () => {
-            // Why: relay notifications can race the initial client-id IPC.
-            // Self-originated writes must never bounce back into restore.
+            // Why: relay notifications can race the client-id IPC; self-originated writes must never bounce back into restore.
             const clientId = await getRemoteWorkspaceClientId()
             if (event.sourceClientId && clientId && event.sourceClientId === clientId) {
               return
@@ -2968,9 +2800,7 @@ export function useIpcEvents(): void {
           setEditorFontZoomLevel(next)
           void window.api.ui.set({ editorFontZoomLevel: next })
 
-          // Why: use the same base font size the editor surfaces use (terminalFontSize)
-          // and computeEditorFontSize to account for clamping, so the overlay percent
-          // matches the actual rendered size.
+          // Why: mirror the editor's base font (terminalFontSize) + clamping so the overlay percent matches the rendered size.
           const baseFontSize = settings?.terminalFontSize ?? 13
           const actual = computeEditorFontSize(baseFontSize, next)
           const percent = Math.round((actual / baseFontSize) * 100)
@@ -2990,12 +2820,8 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: agent status arrives from native hook receivers in the main process.
-    // Re-parse it here so the renderer enforces the same normalization rules
-    // (state enum, field truncation) regardless of whether the source was a
-    // hook callback or an OSC fallback path. Startup pushes are ignored until
-    // workspace session hydration finishes; the snapshot pull below replays the
-    // main-process cache after tab identity is available.
+    // Why: re-parse main-process agent status here so the renderer applies the same normalization regardless of hook vs OSC source.
+    // Startup pushes are ignored until workspace session hydration finishes; the snapshot pull below replays main's cache once tab identity exists.
     function schedulePendingAgentStatusFlush(): void {
       if (pendingAgentStatusRetryTimer !== null || pendingAgentStatusEvents.length === 0) {
         return
@@ -3015,10 +2841,7 @@ export function useIpcEvents(): void {
     }
 
     function flushPendingAgentStatuses(): void {
-      // Why: a re-entrant call (store subscriber firing during a setAgentStatus
-      // inside the loop below) must not reprocess the still-queued events — the
-      // outer flush already owns them. Bailing here breaks the infinite
-      // recursion without dropping work; the outer loop finishes the drain.
+      // Why: guard re-entrancy — a subscriber firing mid-loop must not reprocess queued events the outer flush already owns.
       if (isFlushingAgentStatuses) {
         return
       }
@@ -3069,13 +2892,11 @@ export function useIpcEvents(): void {
         agentType: data.agentType,
         toolName: data.toolName,
         toolInput: data.toolInput,
-        // Why: the live AskUserQuestion prompt rides this IPC field; omitting it
-        // here silently dropped the native question card on web/mobile clients.
+        // Why: the live AskUserQuestion prompt rides this field; omitting it drops the native question card on web/mobile.
         interactivePrompt: data.interactivePrompt,
         lastAssistantMessage: data.lastAssistantMessage,
         interrupted: data.interrupted,
-        // Why: same trap as interactivePrompt — this rebuild is a field
-        // whitelist, so the subagent child rows vanish if omitted here.
+        // Why: same trap as interactivePrompt — this rebuild is a field whitelist, so subagent child rows vanish if omitted.
         subagents: data.subagents
       })
       if (!payload) {
@@ -3090,10 +2911,8 @@ export function useIpcEvents(): void {
         owningWorktreeId
       } = resolvePaneKey(store, paneKey)
       if (!exists && data.worktreeId && hasRuntimeBackedWorktreeAttribution(data)) {
-        // Why: orchestration worker hooks can carry main-side worktree
-        // attribution before this renderer has a terminal tab for the pane.
-        // Require runtime identity too; durable snapshots with only worktreeId
-        // can be stale cached rows from closed/remounted panes.
+        // Why: orchestration worker hooks may carry worktree attribution before this renderer has a tab for the pane.
+        // Require runtime identity too — worktreeId-only snapshots can be stale rows from closed/remounted panes.
         const fallbackOwnership = resolveWorktreeConnection(store, data.worktreeId)
         if (fallbackOwnership.worktreeExists) {
           owningWorktreeId = data.worktreeId
@@ -3103,18 +2922,12 @@ export function useIpcEvents(): void {
         }
       }
       if (!exists) {
-        // Why: empty paneKeys are dropped in main before IPC fanout. Reaching
-        // this branch means a non-empty paneKey escaped without a matching
-        // renderer tab, so track the adoption/routing failure separately.
-        // Skipped during snapshot replay because main's durable cache may
-        // include entries whose tabs were closed before this session — that
-        // reconciliation miss is not a regression signal.
+        // Why: a non-empty paneKey with no matching tab is a routing failure to track.
+        // Skip during replay — main's durable cache legitimately holds closed-tab entries.
         if (options?.replay !== true) {
           if (options?.retry !== true) {
             track('agent_hook_unattributed', { reason: 'unknown_tab_id' })
-            // Why: live hook IPC can beat the renderer's tab/layout hydration.
-            // Main already cached the event; retry locally so a transient
-            // pane-key miss does not drop Droid/Codex completion state.
+            // Why: live hook IPC can beat tab/layout hydration; retry so a transient pane-key miss doesn't drop completion state.
             enqueuePendingAgentStatus(data)
           }
           return 'pending'
@@ -3128,25 +2941,9 @@ export function useIpcEvents(): void {
           }
         }
       }
-      // Why: drop in-flight events from a connection that no longer owns
-      // this pane. After an SSH disconnect (or tab destroy/recreate during
-      // reconnect), notifications may still arrive stamped with the
-      // connectionId of the dead connection. The renderer compares the
-      // stamped connectionId against the live repo's connectionId for the
-      // pane's worktree — see docs/design/agent-status-over-ssh.md §5.
-      // The IPC contract declares connectionId as required (string | null),
-      // so the undefined branch only fires under dev hot-reload skew where
-      // the renderer bundle is newer than the preload bundle.
-      // Why: startup snapshot replay can beat repo/worktree hydration for SSH
-      // panes. If the pane is already present and the event's worktreeId
-      // matches that tab's worktree, accept the status until repo ownership
-      // becomes available; once ownership is resolved, keep the strict
-      // connectionId check below.
-      // Why: the WSL hook relay stamps a transport-provenance connectionId
-      // (`wsl:<distro>`), but the pane is a LOCAL pane on a local repo —
-      // ownership-wise it is null. Without this normalization the strict
-      // check below drops every WSL-relayed status for a local repo (while
-      // still rejecting WSL-stamped events against SSH-owned repos).
+      // Why: drop in-flight events stamped with a dead connection's id after SSH disconnect/reconnect — see docs/design/agent-status-over-ssh.md §5.
+      // Why: startup snapshot replay can beat SSH repo hydration; accept when worktreeId matches the tab until repo ownership resolves.
+      // Why: WSL relay stamps a `wsl:<distro>` connectionId but the pane is a local repo (ownership null); normalize so the strict check below doesn't drop it.
       const ownershipConnectionId = isWslHookRelayConnectionId(data.connectionId)
         ? null
         : data.connectionId
@@ -3154,8 +2951,7 @@ export function useIpcEvents(): void {
         typeof data.connectionId === 'string'
           ? transientClearWatermarkByConnectionId.get(data.connectionId)
           : undefined
-      // Why: delayed snapshots and queued relay events must not resurrect a
-      // status cleared by a newer disconnect from the same connection.
+      // Why: delayed snapshots/queued relay events must not resurrect a status cleared by a newer disconnect on this connection.
       if (transientClearWatermark !== undefined && data.receivedAt <= transientClearWatermark) {
         return 'dropped'
       }
@@ -3174,8 +2970,7 @@ export function useIpcEvents(): void {
       }
       const existingStatus = store.agentStatusByPaneKey[paneKey]
       if (existingStatus && data.receivedAt < existingStatus.updatedAt) {
-        // Why: the store rejects out-of-order status rows; keep metadata-only
-        // session identity on the same accepted event boundary.
+        // Why: the store rejects out-of-order status rows; keep metadata-only session identity on the same event boundary.
         return 'dropped'
       }
       if (data.providerSessionOnly) {
@@ -3190,8 +2985,7 @@ export function useIpcEvents(): void {
           {
             tabId: ownerTabId,
             worktreeId: data.worktreeId ?? owningWorktreeId,
-            // Why: persist the WSL-normalized ownership id, not the raw relay
-            // provenance; a `wsl:*` connectionId would misroute later resumes.
+            // Why: persist the WSL-normalized ownership id, not raw relay provenance; a `wsl:*` connectionId would misroute later resumes.
             ...(ownershipConnectionId !== undefined ? { connectionId: ownershipConnectionId } : {})
           },
           data.launchToken ? { launchToken: data.launchToken } : undefined
@@ -3223,8 +3017,7 @@ export function useIpcEvents(): void {
           incomingState: statusPayload.state
         })
       ) {
-        // Why: renderer may receive an old/stale main-process child completion.
-        // Keep the defensive store guard and completion notification path in sync.
+        // Why: guards against a stale main-process child completion resurrecting terminal status.
         return 'dropped'
       }
       if (
@@ -3237,8 +3030,7 @@ export function useIpcEvents(): void {
           existingProviderSession: existingStatus?.providerSession
         })
       ) {
-        // Why: Codex yolo permission hooks are not user-actionable, and must
-        // not drive status, synthetic titles, unread badges, or notifications.
+        // Why: Codex yolo permission hooks are not user-actionable; they must not drive status, titles, badges, or notifications.
         return 'dropped'
       }
       const terminalTitle = resolveAgentStatusTerminalTitle(statusPayload, title)
@@ -3266,9 +3058,7 @@ export function useIpcEvents(): void {
       )
       applyResolvedAgentTerminalTitleToTab(store, paneKey, title, terminalTitle)
       if (options?.replay !== true && statusWorktreeId) {
-        // Why: local Codex/Claude hooks arrive through this main-process IPC
-        // path, not the PTY OSC fallback, so task-complete notifications must
-        // observe accepted hook state here as well.
+        // Why: local Codex/Claude hooks arrive via this main-process IPC path, not the PTY OSC fallback, so task-complete notifications must observe accepted hook state here too.
         const notificationPayload =
           typeof data.stateStartedAt === 'number'
             ? { ...resolvedPayload, stateStartedAt: data.stateStartedAt }
@@ -3332,13 +3122,7 @@ export function useIpcEvents(): void {
           })
         })
         .catch((err) => {
-          // Why: keep snapshotRequestedForReadyWindow latched on failure. The
-          // store subscriber below fires on every update (including high-rate
-          // PTY ticks), so resetting the flag here would turn a persistent IPC
-          // failure into an unbounded retry storm. One warning per ready
-          // window is sufficient; the flag still clears when
-          // workspaceSessionReady toggles off, so a fresh workspace re-ready
-          // cycle will retry.
+          // Why: stay latched on failure; the store subscriber fires on every update, so resetting here would turn a persistent IPC failure into a retry storm (flag clears on workspaceSessionReady toggle).
           console.warn('[agent-status] failed to load startup snapshot:', err)
         })
     }
@@ -3412,10 +3196,7 @@ export function useIpcEvents(): void {
       unsubs.push(unsubscribeMigrationUnsupportedClear)
     }
 
-    // Why: the main hook server is the durable source of truth. Pull a
-    // snapshot only after workspace tabs are ready, so early startup pushes
-    // can be safely ignored instead of buffered against partially hydrated
-    // renderer state.
+    // Why: main hook server is the durable source of truth; pull the snapshot only after tabs are ready so early startup pushes can be ignored, not buffered.
     requestAgentStatusSnapshotIfReady()
     unsubs.push(
       useAppStore.subscribe((state, previousState) => {
@@ -3488,10 +3269,7 @@ export function useIpcEvents(): void {
     )
 
     unsubs.push(
-      // Why: presence-lock driver state mirror. Updates the renderer's
-      // mobile-driver-state map so TerminalPane / pty-connection guards
-      // know which PTYs are currently driven by mobile. See
-      // docs/mobile-presence-lock.md.
+      // Why: mirror presence-lock driver state so TerminalPane / pty-connection guards know which PTYs are mobile-driven. See docs/mobile-presence-lock.md.
       window.api.runtime.onTerminalDriverChanged((event) => {
         if (isRuntimeEnvironmentActive()) {
           return
@@ -3517,9 +3295,7 @@ export function useIpcEvents(): void {
       })
     )
 
-    // Why: hydrate mobile-owned terminal state on renderer reload. Subscribe
-    // first and buffer live events during the snapshot round trip; otherwise an
-    // older snapshot could overwrite a newer live lock and hide the overlay.
+    // Why: subscribe before the snapshot round trip and buffer live events; otherwise an older snapshot could overwrite a newer live lock and hide the overlay.
     if (!isRuntimeEnvironmentActive()) {
       void Promise.all([
         window.api.runtime.getTerminalFitOverrides(),
@@ -3547,8 +3323,7 @@ export function useIpcEvents(): void {
     }
 
     return () => {
-      // Why: React remount can leave an older snapshot promise in flight. It
-      // must not write through after the replacement effect processes a clear.
+      // Why: React remount can leave an older snapshot promise in flight; it must not write through after the replacement effect processes a clear.
       agentStatusEffectDisposed = true
       snapshotRequestId += 1
       if (pendingAgentStatusRetryTimer !== null) {
@@ -3595,22 +3370,14 @@ function applyResolvedAgentTerminalTitleToTab(
   if (layout?.root && layout.activeLeafId && layout.activeLeafId !== parsed.leafId) {
     return
   }
-  // Why: hook completion can arrive while the pane transport is unmounted.
-  // Keep the active terminal tab label in sync with the resolved state title.
+  // Why: hook completion can arrive while the pane transport is unmounted; keep the tab label synced to the resolved state title.
   store.updateTabTitle(parsed.tabId, nextTitle)
 }
 
-/** Resolve a paneKey (tabId:leafId) to both a liveness check and the current
- *  title, the pane's worktree, and the connectionId of the repo that owns it.
- *  Walks tabsByWorktree to locate the tab, then resolves the owning worktree
- *  and repo via cached selector maps. Used for agent type inference when the
- *  CLI payload omits agentType, plus to drop status updates targeted at panes
- *  whose tabs have already been torn down or whose owning connection is no
- *  longer live (see docs/design/agent-status-over-ssh.md §5).
- *  Why combined: callers need all routing pieces per hook event, and hook
- *  events can fire many times per second during a tool-use run. Bundling
- *  liveness + title + connectionId into one helper keeps the per-event work
- *  in one place and avoids re-deriving the owning repo at the call site. */
+/** Resolve a paneKey (tabId:leafId) to liveness, current title, owning worktree,
+ *  and the owning repo's connectionId. Used for agent-type inference and to drop
+ *  status updates for torn-down tabs or dead connections
+ *  (see docs/design/agent-status-over-ssh.md §5). */
 function resolvePaneKey(
   store: ReturnType<typeof useAppStore.getState>,
   paneKey: string
@@ -3658,10 +3425,7 @@ function resolvePaneKey(
       break
     }
   }
-  // Why: ownership lookup is `tab → worktree → repo → repo.connectionId`.
-  // Keep "resolved to a local repo" distinct from "not hydrated yet" so the
-  // caller can preserve strict filtering after hydration while accepting SSH
-  // snapshots that arrive during the startup ownership gap.
+  // Why: keep "resolved to a local repo" distinct from "not hydrated yet" so callers filter strictly post-hydration but still accept SSH snapshots during the startup ownership gap.
   let repoConnectionId: string | null = null
   let repoConnectionResolved = false
   if (owningWorktreeId !== undefined) {
@@ -3682,9 +3446,7 @@ function resolvePaneKey(
       owningWorktreeId
     }
   }
-  // Why: inactive worktree switches can leave the tab's layout at the empty
-  // snapshot while the tab and PTY are still live. Treat that like missing
-  // layout metadata; a non-empty layout that lacks the leaf still means closed.
+  // Why: an empty layout snapshot from a worktree switch (tab/PTY still live) counts as missing metadata; a non-empty layout lacking the leaf still means closed.
   const leafExists = layout?.root ? collectLeafIdsInOrder(layout.root).includes(leafId) : true
   if (!leafExists) {
     return {
@@ -3696,20 +3458,14 @@ function resolvePaneKey(
       owningWorktreeId
     }
   }
-  // Why: inactive worktrees can have a durable tab and live PTY while their
-  // terminal layout is temporarily unmounted. Hook state must still land there.
+  // Why: inactive worktrees can have a durable tab and live PTY while the layout is unmounted; hook state must still land there.
   const rawPaneTitle = layout?.titlesByLeafId?.[leafId]
-  // Why: treat an empty-string paneTitle as "no title" so the tab-level
-  // fallback still fires. `paneTitle ?? tabTitle` alone would short-circuit on
-  // '' and also erase any previously-cached terminalTitle in the store
-  // (`terminalTitle ?? existing?.terminalTitle` resolves to '').
+  // Why: treat empty-string paneTitle as "no title" so the tab-level fallback fires; nullish-coalescing on '' would short-circuit and erase cached terminalTitle.
   const paneTitle = rawPaneTitle && rawPaneTitle.length > 0 ? rawPaneTitle : undefined
   return {
     exists,
     title: paneTitle ?? tabTitle,
-    // Why: some agents (OpenClaude in practice) keep the low-level terminal
-    // title generic while the unified tab label carries the launched agent
-    // identity. Use only the non-custom label as evidence for hook attribution.
+    // Why: some agents (OpenClaude) keep the terminal title generic while the tab label carries the agent identity; use only the non-custom label for attribution.
     identityTitle: paneTitle ?? unifiedTabLabel ?? tabTitle,
     repoConnectionId,
     repoConnectionResolved,
@@ -3748,7 +3504,6 @@ function resolveHookPayloadAgentType(
   ) {
     return payload
   }
-  // Why: OpenClaude emits Claude-compatible hooks, so title identity is the
-  // renderer's last chance to keep OpenClaude out of Claude-only status paths.
+  // Why: OpenClaude emits Claude-compatible hooks; the title is the last renderer signal to keep it out of Claude-only status paths.
   return { ...payload, agentType: 'openclaude' }
 }
diff --git a/src/renderer/src/lib/agent-status.test.ts b/src/renderer/src/lib/agent-status.test.ts
index 327f080dc1a..14ac79c4ac8 100644
--- a/src/renderer/src/lib/agent-status.test.ts
+++ b/src/renderer/src/lib/agent-status.test.ts
@@ -189,14 +189,9 @@ describe('detectAgentStatusFromTitle', () => {
   })
 
   // --- Cursor (cursor-agent) synthesized titles ---
-  // Why: cursor-agent's native OSC title stays literally "Cursor Agent" for
-  // the entire turn, so Orca synthesizes decorated titles from hook events
-  // to drive the existing spinner/unread pipeline. These tests pin the
-  // contract the main-process hook listener relies on.
+  // Why: cursor-agent's native title stays "Cursor Agent" all turn, so Orca synthesizes decorated titles for the spinner/unread pipeline.
   it('treats the bare "Cursor Agent" native title as a no-op (not idle)', () => {
-    // Why: if the native title classified as idle, cursor's own per-turn
-    // re-emissions would trigger working→idle transitions between our
-    // synthesized working frames, stomping the spinner off mid-turn.
+    // Why: if the native title classified as idle, cursor's per-turn re-emissions would stomp the spinner off mid-turn.
     expect(detectAgentStatusFromTitle('Cursor Agent')).toBeNull()
     expect(detectAgentStatusFromTitle('cursor agent')).toBeNull()
     expect(detectAgentStatusFromTitle('  Cursor Agent  ')).toBeNull()
@@ -246,10 +241,7 @@ describe('detectAgentStatusFromTitle', () => {
     expect(detectAgentStatusFromTitle('Codex Working')).toBe('working')
   })
 
-  // Why: `containsAgentName` token-matches legacy agent names, so a cwd-path
-  // fragment like "~/codex-scratch" (hyphen-adjacent) or "opencode-blinker"
-  // (the worktree name that mislabeled Codex tabs as OpenCode) no longer mints
-  // an 'idle' agent signal. A bare "~/codex" path still has no strong keyword.
+  // Why: `containsAgentName` token-matches, so cwd-path fragments like "~/codex-scratch" no longer mint an 'idle' agent signal.
   it('does not treat cwd-path agent-name fragments as agent activity', () => {
     expect(detectAgentStatusFromTitle('~/codex-scratch')).toBeNull()
     expect(detectAgentStatusFromTitle('~/codex already built')).toBeNull()
@@ -257,10 +249,7 @@ describe('detectAgentStatusFromTitle', () => {
     expect(detectAgentStatusFromTitle('claude-scratch')).toBeNull()
   })
 
-  // Why: short agent names are unsafe under substring detection. Telemetry now
-  // records explicit launch facts rather than widening OSC-title inference, so
-  // this detector must not grow aliases that turn ordinary shell titles like
-  // "timestamp ready" into agent activity.
+  // Why: short agent names are unsafe under substring detection; don't add aliases that turn "timestamp ready" into agent activity.
   it('does not treat ordinary words containing "amp" as agent titles', () => {
     expect(detectAgentStatusFromTitle('timestamp ready')).toBeNull()
     expect(detectAgentStatusFromTitle('clamp working')).toBeNull()
@@ -280,15 +269,7 @@ describe('detectAgentStatusFromTitle', () => {
   })
 })
 
-// Why: regression guard for the STRONG_WORKING_KEYWORDS_RE path-separator
-// false positive. Before the lookarounds were widened to `[\w./\\-]`, a title
-// like `~/codex/working` matched STRONG_WORKING_KEYWORDS_RE (because `/` is
-// not in `[\w\-]`) and the function classified a plain path as 'working',
-// driving spinners and agent counts off a shell cwd. The idle-side fallback
-// at the bottom of `detectAgentStatusFromTitle` still returns 'idle' for
-// agent-name-containing titles — that's the known `containsAgentName`
-// substring gap documented in the test above — so the behavior this block
-// pins is specifically "no path fragment is ever classified as 'working'."
+// Why: regression guard — a path fragment like `~/codex/working` must never classify as 'working' (path separators aren't word boundaries).
 describe('detectAgentStatusFromTitle path-separator rejection', () => {
   test('rejects working keywords adjacent to POSIX path separators', () => {
     expect(detectAgentStatusFromTitle('~/codex/working')).not.toBe('working')
@@ -314,9 +295,7 @@ describe('detectAgentStatusFromTitle path-separator rejection', () => {
     expect(detectAgentStatusFromTitle('Aider thinking')).toBe('working')
   })
 
-  // Why: path separators only need to be blocked on the LEFT of the keyword
-  // (where path fragments sit). Blocking them on the right would regress
-  // legitimate sentence-style titles where a keyword is followed by `.`/`!`/`?`.
+  // Why: block path separators only on the LEFT of the keyword; blocking the right would regress titles ending in `.`/`!`/`?`.
   test('still accepts keywords followed by trailing punctuation', () => {
     expect(detectAgentStatusFromTitle('Codex done.')).toBe('idle')
     expect(detectAgentStatusFromTitle('Aider idle!')).toBe('idle')
@@ -355,12 +334,7 @@ describe('clearWorkingIndicators', () => {
     expect(clearWorkingIndicators('Terminal 1')).toBe('Terminal 1')
   })
 
-  // Why: clearWorkingIndicators must use the same hyphen/word-char-aware
-  // boundary as STRONG_WORKING_KEYWORDS_RE (agent-detection.ts). A prior
-  // implementation used plain `\b${keyword}\b` which — since `-` is a
-  // non-word char — would strip "working" out of "codex is-working-cap"
-  // even though detectAgentStatusFromTitle correctly refuses to classify
-  // that title as 'working'. The clearer and detector must stay symmetric.
+  // Why: clearWorkingIndicators must use the same hyphen-aware boundary as STRONG_WORKING_KEYWORDS_RE so clearer and detector stay symmetric.
   it('does not strip working keywords inside hyphenated compounds', () => {
     expect(clearWorkingIndicators('codex is-working-cap')).toBe('codex is-working-cap')
     expect(clearWorkingIndicators('claude reworking diff')).toBe('claude reworking diff')
@@ -391,8 +365,7 @@ describe('normalizeTerminalTitle', () => {
   })
 
   it('collapses Grok rotating working titles to one stable label', () => {
-    // Grok interpolates a rotating status/tool phrase between the spinner and its
-    // name, so each frame is a distinct title; they must all fold to one label.
+    // Grok interpolates a rotating phrase between spinner and name, so each frame differs; all must fold to one label.
     expect(normalizeTerminalTitle('⠋ - Waiting for response… - grok')).toBe('⠋ Grok')
     expect(normalizeTerminalTitle('⠴ - Thinking - grok')).toBe('⠋ Grok')
     expect(normalizeTerminalTitle('⠙ - Responding - grok')).toBe('⠋ Grok')
@@ -410,8 +383,7 @@ describe('normalizeTerminalTitle', () => {
     expect(normalizeTerminalTitle('Fix the auth bug - grok')).toBe('Fix the auth bug - grok')
     // Names "grok" mid-title but ends with another agent → not a Grok frame.
     expect(normalizeTerminalTitle('⠋ debugging grok - claude')).toBe('⠋ debugging grok - claude')
-    // Claude/Codex task text ending in "grok" must not collapse — only the
-    // Grok frame shape "spinner - phrase - grok" is the rotating-frame signal.
+    // Only the Grok frame shape "spinner - phrase - grok" is the rotating-frame signal; task text ending in "grok" must not collapse.
     expect(normalizeTerminalTitle('⠋ wire up grok')).toBe('⠋ wire up grok')
     expect(normalizeTerminalTitle('⠋ Codex is thinking about grok')).toBe(
       '⠋ Codex is thinking about grok'
@@ -511,10 +483,7 @@ describe('getAgentLabel', () => {
     expect(getAgentLabel('android emulator ready')).toBeNull()
   })
 
-  // Why: cwd/worktree titles embed agent-name fragments. Substring matching
-  // mislabeled a Codex tab whose title fell back to the "opencode-blinker"
-  // worktree name as OpenCode. Token matching must reject these fragments for
-  // every legacy agent name.
+  // Why: substring matching mislabeled cwd/worktree name fragments (e.g. "opencode-blinker") as agents; token-match to reject them.
   it('does not label cwd/worktree path fragments as an agent', () => {
     expect(getAgentLabel('opencode-blinker')).toBeNull()
     expect(getAgentLabel('claude-scratch')).toBeNull()
@@ -534,9 +503,7 @@ describe('getAgentLabel', () => {
     expect(getAgentLabel('Devin working')).toBe('Devin')
   })
 
-  // Why: `cursor` is ordinary editor vocabulary in another agent's task title, so a
-  // bare token is not Cursor identity — a Claude tab working on cursor code was being
-  // mislabeled Cursor on the worktree card. Match Cursor's closed title set only.
+  // Why: "cursor" is ordinary editor vocabulary, so a bare token isn't Cursor identity; match Cursor's closed title set only.
   it('labels Cursor by identity, not a bare "cursor" token in another agent title', () => {
     expect(getAgentLabel('Cursor Agent')).toBe('Cursor')
     expect(getAgentLabel('⠋ Cursor Agent')).toBe('Cursor')
@@ -555,8 +522,7 @@ describe('isClaudeAgent', () => {
     expect(isClaudeAgent('OpenClaude ready')).toBe(false)
   })
 
-  // Why: a braille Claude title merely mentioning a text cursor is still Claude, so its
-  // prompt-cache paths must fire; only Cursor's own identity titles are excluded.
+  // Why: a Claude title merely mentioning a text cursor is still Claude; only Cursor's own identity titles are excluded.
   it('counts cursor-mentioning Claude braille titles as Claude, excludes real Cursor', () => {
     expect(isClaudeAgent('⠋ preserve cursor visibility across replays')).toBe(true)
     expect(isClaudeAgent('⠋ Cursor Agent')).toBe(false)
@@ -585,8 +551,7 @@ describe('isClaudeAgent', () => {
 
 describe('createAgentStatusTracker', () => {
   // --- Claude Code: real captured OSC title sequence (v2.1.86) ---
-  // CRITICAL: Claude Code changes the title to the TASK DESCRIPTION,
-  // not "Claude Code". The ✳ prefix is the only reliable idle indicator.
+  // Claude Code sets the title to the TASK DESCRIPTION, not "Claude Code"; ✳ prefix is the only reliable idle indicator.
   it('fires on Claude Code working → idle (real captured titles)', () => {
     const onBecameIdle = vi.fn()
     const tracker = createAgentStatusTracker(onBecameIdle)
@@ -655,9 +620,7 @@ describe('createAgentStatusTracker', () => {
     expect(onBecameIdle).toHaveBeenCalledTimes(1)
   })
 
-  // Why: end-to-end tracker coverage for cursor — synthesized working frames
-  // interleaved with cursor's own "Cursor Agent" re-emissions must not fire
-  // onBecameIdle until the "Cursor ready" done frame arrives.
+  // Why: cursor's native "Cursor Agent" re-emissions between synthesized working frames must not fire onBecameIdle before the done frame.
   it('fires on Cursor working → idle across native "Cursor Agent" re-emissions', () => {
     const onBecameIdle = vi.fn()
     const tracker = createAgentStatusTracker(onBecameIdle)
@@ -739,10 +702,7 @@ describe('createAgentStatusTracker', () => {
     expect(onBecameIdle).not.toHaveBeenCalled()
   })
 
-  // Why: reset() clears the tracker's working latch so stale working→idle
-  // transitions cannot fire after the owning transport is torn down. Without
-  // this guarantee, a reattach or late title delivery could surface a
-  // phantom idle notification for work the user already dismissed.
+  // Why: reset() clears the working latch so a late/reattach idle title can't fire a phantom notification after teardown.
   it('reset() clears working state so a subsequent idle does not fire onBecameIdle', () => {
     const onBecameIdle = vi.fn()
     const tracker = createAgentStatusTracker(onBecameIdle)
@@ -758,8 +718,7 @@ describe('createAgentStatusTracker', () => {
     const onBecameIdle = vi.fn()
     const tracker = createAgentStatusTracker(onBecameIdle)
 
-    // Simulate raw PTY data chunks containing OSC title sequences
-    // Uses real title patterns: task description, NOT "Claude Code"
+    // Real title patterns: task description, NOT "Claude Code"
     const oscTitle = (title: string): string => `\x1b]0;${title}\x07`
 
     const chunks = [
@@ -804,9 +763,7 @@ describe('createAgentStatusTracker', () => {
 
 describe('isExplicitAgentStatusFresh', () => {
   it('treats the boundary (now - updatedAt == staleAfterMs) as fresh', () => {
-    // Why: the function uses `<=`, so equality at the boundary must remain
-    // fresh. Protecting this invariant keeps entries from flipping to stale
-    // one tick earlier than the configured TTL implies.
+    // Why: uses `<=`, so equality at the boundary stays fresh (not stale one tick before the TTL).
     const staleAfterMs = 60_000
     const now = 1_000_000
     const entry = { updatedAt: now - staleAfterMs }
@@ -930,9 +887,7 @@ describe('agentTypeToIconAgent', () => {
   })
 
   it('returns null for arbitrary non-iconable strings', () => {
-    // Why: guards against hook payloads reporting agentTypes that AgentIcon
-    // cannot render (e.g. "totally-fake-agent"); returning null lets the
-    // caller fall back to a neutral glyph instead of a broken icon.
+    // Why: unknown agentTypes must return null so the caller falls back to a neutral glyph, not a broken icon.
     expect(agentTypeToIconAgent('totally-fake-agent')).toBeNull()
   })
 })
diff --git a/src/renderer/src/lib/agent-status.ts b/src/renderer/src/lib/agent-status.ts
index aaf3fc4795c..af19128f886 100644
--- a/src/renderer/src/lib/agent-status.ts
+++ b/src/renderer/src/lib/agent-status.ts
@@ -5,9 +5,7 @@ import type { WorktreeStatus } from './worktree-status'
 import { tuiAgentToAgentKind } from '../../../shared/agent-kind'
 import type { AgentKind } from '../../../shared/telemetry-events'
 
-// Re-export from shared module so existing renderer imports continue to work.
-// Why: the main process now needs the same agent detection logic for stat
-// tracking. Moving to shared avoids duplicating the detection code.
+// Re-export from shared so existing renderer imports work; main process now shares the detection logic.
 export {
   type AgentStatus,
   detectAgentStatusFromTitle,
@@ -25,13 +23,7 @@ import { classifyTitleActivity, resolveTitleActivityLabel } from './pane-agent-e
 type AgentQueryArgs = {
   tabsByWorktree: Record<string, TerminalTab[]>
   runtimePaneTitlesByTabId: Record<string, Record<number, string>>
-  // Why: title-scraped agent activity (pane titles, tab.title) survives sleep
-  // because runtimePaneTitlesByTabId is intentionally preserved under
-  // keepIdentifiers for wake recovery. Without the live-PTY map, slept tabs
-  // whose preserved titles still match a working pattern would surface as
-  // working agents through the title-bar count, dock badge, and per-worktree
-  // aggregates. Threading ptyIdsByTabId lets every title-scrape branch gate
-  // on actual liveness (`tabHasLivePty`).
+  // Why: gates title-scraped activity on liveness — preserved-under-sleep titles would otherwise surface slept tabs as working.
   ptyIdsByTabId: Record<string, string[]>
   worktreesByRepo: Record<string, Worktree[]>
 }
@@ -57,20 +49,14 @@ export function getWorkingAgentsPerWorktree({
   const result: Record<string, WorktreeAgents> = {}
 
   for (const [worktreeId, tabs] of Object.entries(tabsByWorktree)) {
-    // Why: tabsByWorktree can retain orphaned entries for worktrees that no
-    // longer exist in git (e.g. deleted worktrees whose tab cleanup didn't
-    // complete, or worktrees removed outside Orca). worktreesByRepo is the
-    // source of truth — only include worktrees that still exist.
+    // Why: tabsByWorktree can retain orphaned entries for deleted worktrees; worktreesByRepo is the source of truth.
     if (!validIds.has(worktreeId)) {
       continue
     }
     const agents: WorkingAgentEntry[] = []
 
     for (const tab of tabs) {
-      // Why: title-scraped activity must be gated on actual PTY liveness.
-      // runtimePaneTitlesByTabId is preserved under sleep (keepIdentifiers),
-      // so a slept tab whose pane titles still match a working pattern would
-      // surface as a working agent without this gate.
+      // Why: pane titles are preserved under sleep (keepIdentifiers), so gate on live PTY or slept tabs surface as working agents.
       if (!tabHasLivePty(ptyIdsByTabId, tab.id)) {
         continue
       }
@@ -105,23 +91,10 @@ export function getWorkingAgentsPerWorktree({
   return result
 }
 
-// Re-exported from shared so mobile shows the same agent labels (one source of
-// truth). Kept re-exported here so existing `@/lib/agent-status` importers work.
+// Re-export: shared so mobile shows the same agent labels; kept here for existing importers.
 export { formatAgentTypeLabel } from '../../../shared/agent-type-label'
 
-// Why: AgentIcon expects a TuiAgent, but AgentType is a broader union
-// (WellKnownAgentType | (string & {})) that includes 'unknown' and arbitrary
-// strings reported by hook payloads. Return null for the unknown case so
-// AgentIcon renders a neutral "?" glyph — using 'claude' as a fallback
-// caused Codex panes to briefly show the Claude icon before the hook fired.
-// Why: we also guard against arbitrary strings (e.g. a hook reporting
-// agentType: "weirdo") by checking membership in an explicit record. A
-// blind `as TuiAgent` cast would pass values through that AgentIcon can't
-// render, producing a broken icon or falling back to an unrelated glyph.
-// Why: modeled as `Record<TuiAgent, true>` rather than a Set so the TypeScript
-// compiler fails to build when a TuiAgent member is added to shared/types.ts
-// without being added here — a Set<TuiAgent> is structurally permissive and
-// would silently accept a subset of the union.
+// Why: Record<TuiAgent, true> (not a Set) forces a build error if a TuiAgent member is added without being listed here.
 const ICONABLE_AGENT_TYPES: Record<TuiAgent, true> = {
   claude: true,
   'claude-agent-teams': true,
@@ -159,6 +132,7 @@ const ICONABLE_AGENT_TYPES: Record<TuiAgent, true> = {
   ante: true
 }
 
+// Why: return null (not a 'claude' fallback) for unknown so Codex panes don't flash the Claude icon before the hook fires.
 export function agentTypeToIconAgent(agentType: AgentType | null | undefined): TuiAgent | null {
   if (!agentType || agentType === 'unknown') {
     return null
@@ -168,16 +142,13 @@ export function agentTypeToIconAgent(agentType: AgentType | null | undefined): T
     : null
 }
 
-// Why: telemetry's `agent_kind` enum derives from the TuiAgent mapping. Share
-// one resolver so the notes-send dropdown and the sidebar send path stamp
-// identical agent_kind values on `agent_prompt_sent`.
+// Why: shared resolver so all send paths stamp identical agent_kind on agent_prompt_sent telemetry.
 export function agentKindForAgentType(agentType: AgentType | null | undefined): AgentKind {
   const tuiAgent = agentTypeToIconAgent(agentType)
   return tuiAgent ? tuiAgentToAgentKind(tuiAgent) : 'other'
 }
 
-// Why: the freshness gate moved into the pane-agent-evidence resolvers; the
-// re-export keeps this module's many existing importers unchanged.
+// Re-export: freshness gate moved into pane-agent-evidence; keeps existing importers unchanged.
 export { isExplicitAgentStatusFresh } from './pane-agent-evidence'
 
 /**
@@ -239,21 +210,13 @@ function countWorkingAgentsForTab(
   runtimePaneTitlesByTabId: Record<string, Record<number, string>>,
   ptyIdsByTabId: Record<string, string[]>
 ): number {
-  // Why: liveness precondition shared with getWorkingAgentsPerWorktree.
-  // runtimePaneTitlesByTabId is preserved under sleep (keepIdentifiers) and
-  // tab.ptyId is the wake-hint sessionId, not a liveness signal. Without
-  // this gate, slept tabs whose preserved titles still match a working
-  // pattern would inflate the title-bar agent count and dock badge.
+  // Why: pane titles are preserved under sleep (keepIdentifiers), so gate on live PTY or slept tabs inflate the agent count.
   if (!tabHasLivePty(ptyIdsByTabId, tab.id)) {
     return 0
   }
   let count = 0
   const paneTitles = runtimePaneTitlesByTabId[tab.id]
-  // Why: split-pane tabs can host multiple concurrent agents, but the
-  // legacy tab title only reflects the last pane title update that won the
-  // tab label. Prefer pane-level titles whenever TerminalPane is mounted,
-  // and fall back to the tab title only for tabs we have not mounted yet
-  // (for example restored-but-unvisited worktrees).
+  // Why: split-pane tabs host multiple agents; the tab title only shows the last pane update, so prefer pane titles when mounted.
   if (paneTitles && Object.keys(paneTitles).length > 0) {
     for (const title of Object.values(paneTitles)) {
       if (classifyTitleActivity(title) === 'working') {
diff --git a/src/renderer/src/lib/launch-agent-in-new-tab.ts b/src/renderer/src/lib/launch-agent-in-new-tab.ts
index 6dca4ecf4aa..4eaa9d1108a 100644
--- a/src/renderer/src/lib/launch-agent-in-new-tab.ts
+++ b/src/renderer/src/lib/launch-agent-in-new-tab.ts
@@ -34,24 +34,19 @@ import { seedNativeChatAppliedSessionOptions } from '@/components/native-chat/na
 export type LaunchAgentInNewTabArgs = {
   agent: TuiAgent
   worktreeId: string
-  /** The tab group the user clicked from. Keeps split-group launches in the
-   *  pane the user initiated from instead of falling through to the active group. */
+  /** Tab group the user launched from; keeps split-group launches in that pane instead of the active group. */
   groupId?: string
-  /** Optional initial prompt. Delivery depends on `promptDelivery` and the
-   *  agent's prompt mode. */
+  /** Optional initial prompt; delivery depends on `promptDelivery` and the agent's prompt mode. */
   prompt?: string
   /** Optional CLI arguments appended to the selected agent command. */
   agentArgs?: string | null
-  /** Force generated prompt text out of the shell launch command. `draft`
-   *  leaves it editable; `submit-after-ready` sends it once the TUI is ready. */
+  /** How to deliver the prompt: `draft` leaves it editable, `submit-after-ready` sends it once the TUI is ready. */
   promptDelivery?: 'auto-submit' | 'draft' | 'submit-after-ready'
-  /** Telemetry surface that initiated this launch. Defaults to the tab-bar
-   *  quick-launch entry point so existing callers stay unchanged. */
+  /** Telemetry surface that initiated this launch. Defaults to the tab-bar quick-launch entry point. */
   launchSource?: LaunchSource
   /** User-authored Quick Command label for local tabs created from the tab bar. */
   quickCommandLabel?: string | null
-  /** Shell platform that will execute the startup command. Defaults to the
-   * renderer OS; SSH and WSL worktrees run a Linux shell even from Windows. */
+  /** Shell platform for the startup command; defaults to renderer OS. SSH/WSL worktrees run Linux even from Windows. */
   launchPlatform?: NodeJS.Platform
   /** Called after the prompt is actually delivered to the agent input path. */
   onPromptDelivered?: () => void
@@ -68,23 +63,11 @@ export type LaunchAgentInNewTabResult = {
  * Create a new terminal tab and queue the agent's launch command, optionally
  * with an initial prompt.
  *
- * Why: this is the single entry point for "launch agent X in a new tab" from
- * the tab-bar quick-launch menu and the Source Control "send notes to agent"
- * action. It mirrors the `+` button's path (`createNewTerminalTab`) — createTab,
- * flip `activeTabType` to terminal, and persist the appended tab-bar order —
- * then queues the agent startup through the same `pendingStartupByTabId`
- * channel the new-workspace ("cmd+N") flow uses. TerminalPane consumes the
- * queued command on first mount and the local PTY provider writes it once the
- * shell is ready (see `pty-connection.ts`: startup-command path).
+ * Submission mode follows `promptInjectionMode`: argv/flag agents fold the
+ * prompt into the launch command; followup-path agents launch empty and get a
+ * post-ready draft paste. Callers can override via `promptDelivery`.
  *
- * Default submission mode follows `promptInjectionMode`: argv/flag agents
- * include the prompt directly in the launch command, while followup-path
- * agents launch empty and receive a post-ready draft paste. Generated contexts
- * can override this with draft or submit-after-ready delivery.
- *
- * Returns `null` when no startup plan can be built — for example, a whitespace-
- * only prompt on the trim-empty branch of `buildAgentStartupPlan`. Callers
- * surface that as a launch failure (see `QuickLaunchButton.runLaunch`).
+ * Returns `null` when no startup plan can be built (e.g. a whitespace-only prompt).
  */
 export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentInNewTabResult {
   const {
@@ -110,8 +93,7 @@ export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentI
           repo.connectionId ? undefined : getLocalProjectExecutionRuntimeContext(store, worktreeId)
         )
       : CLIENT_PLATFORM)
-  // Why: SSH remotes deploy the CLI shim as plain `orca`, so the Linux-only
-  // `orca-ide` rename must not be applied for remote launches.
+  // Why: SSH remotes deploy the shim as plain `orca`, so skip the Linux-only `orca-ide` rename for remote launches.
   const isRemote = repo ? repoIsRemote(repo) : false
   const queuedShell = resolveLocalWindowsAgentStartupShell({
     platform: resolvedLaunchPlatform,
@@ -140,12 +122,7 @@ export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentI
   const trimmedPrompt = prompt?.trim() ?? ''
   const hasPrompt = trimmedPrompt.length > 0
   const isFollowupPath = TUI_AGENT_CONFIG[agent].promptInjectionMode === 'stdin-after-start'
-  // Why: argv/flag agents fold the prompt into the launch command and
-  // auto-submit — keeping behavior consistent with the composer/tab-bar `+`
-  // mental model, where the prompt is "the first turn the user sent".
-  // Followup-path and generated-context launches can deliver a prompt via
-  // post-launch bracketed paste; callers decide whether that paste remains a
-  // draft or submits after readiness.
+  // argv/flag agents fold the prompt into the launch command; followup/generated launches deliver it via post-launch paste.
   let startupPlan: AgentStartupPlan | null = null
   let pasteDraftAfterLaunch: string | null = null
   let submitPastedPrompt = false
@@ -153,8 +130,7 @@ export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentI
   let promptDeliveryResult: Promise<{ delivered: boolean; failureNotified: boolean }> | undefined
 
   if (hasPrompt && promptDelivery === 'submit-after-ready') {
-    // Why: generated multi-line prompts are too large to echo through a shell
-    // argv/prefill command. Launch cleanly, then paste+submit inside the TUI.
+    // Why: multi-line generated prompts are too large for a shell argv, so launch clean then paste+submit in the TUI.
     startupPlan = buildAgentStartupPlan({
       ...startupPlanBase,
       prompt: '',
@@ -210,8 +186,7 @@ export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentI
     return null
   }
 
-  // Why: host-owned paired tabs must receive the same initial-view decision as
-  // local tabs; the remote host cannot infer this client's draft/default choice.
+  // Why: the remote host can't infer this client's draft/default view choice, so decide it here for paired tabs too.
   const viewModePromptDelivery =
     hasPrompt && isFollowupPath && promptDelivery === 'auto-submit' ? 'draft' : promptDelivery
   const initialViewModeProps = initialAgentTabViewModeProps(store.settings, {
@@ -231,23 +206,15 @@ export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentI
       groupId,
       hasPrompt,
       startupPlan,
-      // Why: omission means terminal locally, but would let a paired host apply
-      // its own default; send the client's resolved terminal choice explicitly.
+      // Why: send the client's resolved terminal choice explicitly, else a paired host applies its own default.
       viewMode: initialViewModeProps.viewMode ?? 'terminal',
       onPromptDelivered
     })
     return { tabId: null, startupPlan, pasteDraftAfterLaunch: false }
   }
 
-  // Why: queue the startup command BEFORE TerminalPane mounts — it captures
-  // `pendingStartupByTabId[tabId]` in useState on first render. If the queue
-  // lands after mount the agent binary never starts; the user sees a bare shell.
-  // Since both calls happen synchronously in the same React batch, the queue
-  // is in place by the time the pane commits.
-  // Why: the followup path pastes the prompt as an unsubmitted draft (submit
-  // stays false), so gate the initial chat view like a `draft` launch —
-  // otherwise a default `auto-submit` followup would open native chat with no
-  // submitted turn to render.
+  // Why: queue startup BEFORE TerminalPane mounts — it snapshots pendingStartupByTabId in useState on first render.
+  // Why: followup path pastes an unsubmitted draft, so gate the initial chat view like a draft launch, not auto-submit.
   const tab = store.createTab(worktreeId, groupId, undefined, {
     launchAgent: agent,
     quickCommandLabel,
@@ -271,17 +238,10 @@ export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentI
       request_kind: 'new'
     }
   })
-  // Why: schedule the bracketed-paste-after-ready follow-up immediately after
-  // the startup command is queued. Fire-and-forget so callers keep their
-  // synchronous `{ tabId, startupPlan }` signature. The helper short-circuits
-  // for agents with a `draftPromptFlag`, so calling it on the followup path
-  // is safe even when the draft was already injected via the native flag.
+  // Why: fire-and-forget the paste-after-ready delivery so callers keep the synchronous { tabId, startupPlan } signature.
+  // Why: safe to call unconditionally — the helper short-circuits (no paste) for native-prefill agents already holding the draft.
   if (pasteDraftAfterLaunch !== null) {
-    // Why: surface silent paste failures — without onTimeout, a stalled agent
-    // readiness wait drops the user's notes with no feedback. Suppress when
-    // the user closed the tab or switched worktrees so the toast/telemetry
-    // don't fire for user-initiated cancellation (mirrors the 5s launch
-    // watchdog in QuickLaunchButton).
+    // Why: onTimeout surfaces silent paste failures — a stalled readiness wait would otherwise drop notes silently.
     let failureNotified = false
     const deliveryPromise = deliverLaunchPromptToAgentTab({
       tabId: tab.id,
@@ -294,15 +254,11 @@ export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentI
         const tabsForWorktree = state.tabsByWorktree[worktreeId] ?? []
         const currentTab = tabsForWorktree.find((t) => t.id === tab.id)
         if (currentTab?.ptyId === null) {
-          // Why: PTY never spawned — a genuine launch failure. Stay silent so
-          // the single notice comes from the caller (source-control dialog
-          // toast, or QuickLaunch's watchdog); leaving failureNotified false lets it fire.
+          // Why: PTY never spawned = genuine launch failure; stay silent so the caller emits the sole notice.
           return
         }
         if (!currentTab || state.activeWorktreeId !== worktreeId) {
-          // Why: user-initiated cancellation (closed the tab or switched
-          // worktrees) — mark notified so the deferred source-control caller
-          // suppresses its generic "couldn't start" toast too, not just this nudge.
+          // Why: user cancelled (closed tab / switched worktrees); mark notified so the deferred caller suppresses its toast too.
           failureNotified = true
           return
         }
@@ -341,14 +297,10 @@ export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentI
     onPromptDelivered?.()
   }
 
-  // Why: match the `+` button's `createNewTerminalTab` sequence — without
-  // `setActiveTabType('terminal')`, a worktree currently showing an editor
-  // file keeps rendering the editor and the new terminal tab stays invisible.
+  // Why: without setActiveTabType('terminal') a worktree showing an editor keeps rendering it and the new tab stays hidden.
   store.setActiveTabType('terminal')
 
-  // Why: persist the tab-bar order with the new terminal appended. Without
-  // this, `reconcileTabOrder` falls back to terminals-first when the stored
-  // order is unset, which can jump the new tab to index 0 instead of the end.
+  // Why: persist tab-bar order so reconcileTabOrder doesn't fall back to terminals-first and jump the new tab to index 0.
   const fresh = useAppStore.getState()
   const termIds = (fresh.tabsByWorktree[worktreeId] ?? []).map((t) => t.id)
   const editorIds = fresh.openFiles.filter((f) => f.worktreeId === worktreeId).map((f) => f.id)
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
index c57175bb463..4272d4c0913 100644
--- a/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
@@ -1,6 +1,4 @@
-/* oxlint-disable max-lines -- Why: output ordering, foreground settle, queue
-state, and e2e diagnostics share one state machine; splitting it would make the
-backlog/resume guarantees harder to audit. */
+/* oxlint-disable max-lines -- Why: output ordering, foreground settle, queue state, and e2e diagnostics form one state machine; splitting it would make backlog/resume guarantees harder to audit. */
 import { e2eConfig } from '@/lib/e2e-config'
 import {
   discardForegroundRenderSettle,
@@ -37,11 +35,7 @@ type WriteTerminalOutputOptions = {
   foreground: boolean
   beforeWrite?: TerminalOutputBeforeWrite
   onParsed?: TerminalOutputParsedCallback
-  /** Parse-deferred delivery ACK (terminal-pty-ack-gate). The scheduler MUST
-   *  invoke it exactly when the chunk's bytes are parsed by xterm OR discarded
-   *  by any drop path. A missed credit permanently shrinks
-   *  main's in-flight window for this PTY (the callback is fire-once, so
-   *  double invocation is safe; omission is not). */
+  /** Parse-deferred delivery ACK (terminal-pty-ack-gate). MUST be invoked when the chunk is parsed OR discarded by any drop path; fire-once, so double invocation is safe but omission permanently shrinks main's in-flight window. */
   ackCredit?: () => void
   onBackgroundBacklogDropped?: () => void
   latencySensitive?: boolean
@@ -98,20 +92,12 @@ const BACKGROUND_DRAIN_INTERVAL_MS = 16
 const HIGH_PRIORITY_DRAIN_INTERVAL_MS = 4
 const BACKGROUND_CHUNK_CHARS = 16 * 1024
 const MAX_WRITES_PER_DRAIN = 2
-// Why 8: with the parse-clock pacer, high-priority ticks fire only after
-// xterm confirms the previous batch parsed, and Chromium clamps chained
-// timers to ~4ms — so per-tick volume (8 x 16KB = 128KB ≈ 1.3ms of parse)
-// sets the sustained ceiling (~30MB/s) while staying far inside
-// DRAIN_TIME_BUDGET_MS. At 2 the ceiling was 8MB/s against a ~100MB/s
-// parser (see pane-terminal-output-scheduler-throughput.bench.test.ts).
+// Why 8: per-tick volume (8 x 16KB = 128KB ≈ 1.3ms parse) sets the sustained ceiling (~30MB/s) within DRAIN_TIME_BUDGET_MS; at 2 it was only 8MB/s against a ~100MB/s parser (see throughput bench).
 const HIGH_PRIORITY_MAX_WRITES_PER_DRAIN = 8
 const DRAIN_TIME_BUDGET_MS = 8
 const LARGE_BACKLOG_CHARS = 512 * 1024
 const SYNC_FOREGROUND_FLUSH_CHARS = 256 * 1024
-// Why mutable: the cap scales with the user's scrollback setting (see
-// terminalOutputBacklogCapChars); the terminal lifecycle configures it when
-// settings are applied. The chunk-count cap stays fixed — it bounds queue
-// bookkeeping, not retained content.
+// Why mutable: the cap scales with the user's scrollback setting (terminalOutputBacklogCapChars), configured when settings apply; the chunk-count cap stays fixed.
 let maxQueueChars = TERMINAL_OUTPUT_BACKLOG_MIN_CAP_CHARS
 const MAX_BACKGROUND_QUEUE_CHUNKS = 4096
 
@@ -121,21 +107,16 @@ export function configureTerminalOutputBacklogCap(scrollbackRows: unknown): void
 const PARSE_SETTLE_TIMEOUT_MS = 250
 const FOREGROUND_COALESCE_DELAY_MS = 1000
 const FOREGROUND_HOLD_SAFETY_DELAY_MS = 250
-// Why: key repeat can tick every 30-50ms; one frame catches split restores
-// without batching multiple typed-character redraws behind the fallback.
+// Why: key repeat can tick every 30-50ms; one frame catches split restores without batching multiple typed-character redraws behind the fallback.
 const LATENCY_SENSITIVE_FOREGROUND_COALESCE_DELAY_MS = 16
 const LATENCY_SENSITIVE_FOREGROUND_HOLD_SAFETY_DELAY_MS = 32
 const CURSOR_SHOW_SEQUENCE = '\x1b[?25h'
 const CURSOR_HIDE_SEQUENCE = '\x1b[?25l'
 const SYNCHRONIZED_OUTPUT_END_SEQUENCE = '\x1b[?2026l'
-// Why: CAN aborts a partial escape sequence before resetting style and showing
-// the lossy-backlog warning. Cap-agnostic wording: the byte limit scales with
-// the scrollback setting.
+// Why: leading CAN aborts any partial escape sequence before the style reset so the backlog warning renders cleanly.
 const BACKGROUND_BACKLOG_WARNING =
   '\x18\x1b[0m\r\n[Orca skipped hidden terminal output because the backlog grew too large.]\r\n'
-// Why a separate foreground message: a visible pane hitting the cap means the
-// drain could not keep up with a flood (starved renderer) — the output was
-// skipped, not merely produced while hidden.
+// Why a separate foreground message: a visible pane hitting the cap means the drain couldn't keep up with a flood (starved renderer), not merely output produced while hidden.
 const FOREGROUND_BACKLOG_WARNING =
   '\x18\x1b[0m\r\n[Orca skipped a burst of terminal output because the backlog grew too large.]\r\n'
 const ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY = (): boolean => true
@@ -147,21 +128,14 @@ const backlogRecoveryByTerminal = new WeakMap<
 >()
 let drainTimer: ReturnType<typeof setTimeout> | null = null
 let drainTimerDelayMs: number | null = null
-// Why a MessageChannel for zero-delay drains: Chromium clamps nested
-// setTimeout(0) to ~4ms, which stacks a dead gap onto every parse-clocked
-// drain tick under flood (measured: standing queue ~18ms vs VS Code ~7ms).
-// A posted message is still a macrotask — input events and paint are
-// serviced between posts — so the cooperative yield survives without the
-// clamp. Cancellation is by generation: posts carry the generation they
-// were armed with and no-op when it has moved on.
+// Why a MessageChannel for zero-delay drains: Chromium clamps nested setTimeout(0) to ~4ms; a posted macrotask isn't clamped yet still yields to input/paint. Cancellation is by generation.
 let drainImmediatePending = false
 let drainImmediateGeneration = 0
 let useMessageChannelDrain = typeof MessageChannel !== 'undefined' && !isVitestEnv()
 let drainChannel: MessageChannel | null = null
 
 function isVitestEnv(): boolean {
-  // Why: vitest fake timers cannot advance MessageChannel macrotasks; the
-  // timer path keeps the existing suites' virtual clock authoritative.
+  // Why: vitest fake timers can't advance MessageChannel macrotasks; the timer path keeps the suites' virtual clock authoritative.
   return typeof process !== 'undefined' && process.env?.VITEST === 'true'
 }
 
@@ -190,9 +164,7 @@ export function setUseMessageChannelDrainForTesting(value: boolean | null): void
 }
 const debugEnabled = e2eConfig.exposeStore
 
-// Why the cap is lossy: a hidden/backgrounded Chromium document can throttle
-// timers while PTYs keep writing. Preserving unlimited hidden scrollback would
-// let renderer memory grow until the app stalls or crashes.
+// Why the cap is lossy: a backgrounded Chromium document throttles timers while PTYs keep writing, so unbounded hidden scrollback would grow renderer memory until the app crashes.
 
 type TerminalOutputSchedulerDebugSnapshot = {
   backgroundEnqueueCount: number
@@ -290,8 +262,7 @@ function exposeDebugApi(): void {
   if (!debugEnabled || typeof window === 'undefined') {
     return
   }
-  // Why: the e2e repro needs to prove background output used the shared drain,
-  // but production must not accumulate diagnostic counters indefinitely.
+  // Why: the e2e repro must prove background output used the shared drain, but production must not accumulate diagnostic counters indefinitely.
   const target = window as unknown as {
     __terminalOutputSchedulerDebug?: TerminalOutputSchedulerDebugApi
   }
@@ -458,9 +429,7 @@ function removeTransientCursorShowSequences(data: string): string {
         if (synchronizedEndIndex === -1) {
           break
         }
-        // Why: keep the cursor hidden while xterm parses the synchronized
-        // repaint, then restore it after the frame ends so Windows never paints
-        // the cursor in the transient draw position.
+        // Why: keep the cursor hidden through the synchronized repaint, restoring it after the frame ends so Windows never paints it in the transient draw position.
         result += data.slice(offset, showIndex)
         result += data.slice(
           showIndex + CURSOR_SHOW_SEQUENCE.length,
@@ -471,8 +440,7 @@ function removeTransientCursorShowSequences(data: string): string {
         showIndex = data.indexOf(CURSOR_SHOW_SEQUENCE, offset)
         continue
       }
-      // Why: Codex can show the cursor before its final synchronized-frame
-      // placement. Place first so xterm cannot rasterize the stale cell.
+      // Why: Codex can show the cursor before its final synchronized-frame placement. Place first so xterm cannot rasterize the stale cell.
       result += data.slice(offset, showIndex)
       result += data.slice(showIndex + CURSOR_SHOW_SEQUENCE.length, nextPositionEnd)
       result += CURSOR_SHOW_SEQUENCE
@@ -596,8 +564,7 @@ function takeQueuedChunk(entry: QueueEntry, limit: number): QueuedWrite | null {
     foreground ??= chunk.foreground
     forceForegroundRefresh ||= chunk.forceForegroundRefresh
     followupForegroundRefresh ||= chunk.followupForegroundRefresh
-    // Why: one drained write can combine chunks from different renderer
-    // states or producers; preserve every forced policy and preparation hook.
+    // Why: one drained write can combine chunks from different renderer states or producers; preserve every forced policy and prep hook.
     if (chunk.forceForegroundRefresh) {
       if (shouldRefreshForegroundSynchronously === null) {
         shouldRefreshForegroundSynchronously = chunk.shouldRefreshForegroundSynchronously
@@ -728,10 +695,7 @@ function enqueueChunk(
   recordQueueDebugPressure()
 }
 
-// Fires the delivery ACK credits of every not-yet-consumed queued chunk.
-// Every discard path MUST call this before clearing/replacing the queue —
-// a dropped chunk still counts as consumed for main's in-flight window, or
-// the window shrinks permanently and the PTY wedges behind lost credit.
+// Why: every discard path MUST fire these before clearing/replacing the queue — a dropped chunk still counts as consumed, or main's in-flight window shrinks permanently and the PTY wedges.
 function fireQueuedAckCredits(entry: QueueEntry): void {
   for (let index = entry.chunkIndex; index < entry.chunks.length; index += 1) {
     entry.chunks[index].ackCredit?.()
@@ -761,8 +725,7 @@ function replaceBacklogWithWarning(
 ): void {
   const shouldNotify = !entry.backgroundBacklogDropped
   if (shouldNotify) {
-    // Why: field visibility for cap tuning — how often drops happen and at
-    // what size decides whether the cap is too small (issue #2836 / #7017).
+    // Why: field visibility for cap tuning — drop frequency and size decide whether the cap is too small (issue #2836 / #7017).
     recordRendererCrashBreadcrumb('terminal_output_backlog_dropped', {
       foreground: warning === FOREGROUND_BACKLOG_WARNING,
       droppedChars: entry.queuedChars,
@@ -829,18 +792,14 @@ function hasDrainableBacklog(): boolean {
   return false
 }
 
-// Why no per-write scroll enforcement: xterm's BufferService.isUserScrolling
-// natively owns live follow/pin semantics. App-side intent enforcement is
-// limited to structural operations xterm cannot identify, such as replay.
+// Why no per-write scroll enforcement: xterm's BufferService.isUserScrolling owns live follow/pin; app-side enforcement is limited to structural ops xterm can't identify, like replay.
 function writeBackgroundTerminalChunk(
   terminal: TerminalOutputTarget,
   data: string,
   onParsed?: TerminalOutputParsedCallback,
   onWriteFailure?: () => void
 ): boolean {
-  // Why guarded: these callbacks run inside xterm's WriteBuffer loop, where an
-  // escaping throw permanently wedges the terminal (see
-  // xterm-write-callback-guard.ts).
+  // Why guarded: these callbacks run inside xterm's WriteBuffer loop, where an escaping throw permanently wedges the terminal (see xterm-write-callback-guard.ts).
   const runOnParsed = onParsed
     ? (): void => runGuardedWriteCompletionStep('background-on-parsed', onParsed)
     : undefined
@@ -867,8 +826,7 @@ function takeNextDrainableEntry(): QueueEntry | null {
     if (!isEntryDrainable(entry)) {
       continue
     }
-    // Why: active/foreground output should be chosen first, not just widen the
-    // drain budget while older background terminals keep their insertion order.
+    // Why: active/foreground output should be chosen first, not left in insertion order behind older background terminals.
     if (entry.highPriority) {
       queuedByTerminal.delete(entry.terminal)
       return entry
@@ -891,12 +849,7 @@ function takeNextDrainableEntry(): QueueEntry | null {
   return null
 }
 
-// Why: the parse-completion pacer re-arms a zero-delay drain as soon as xterm
-// reports the previous high-priority batch parsed. Without it, cadence is a
-// fixed 4/16ms nap per <=32KB batch — a ~2-8 MB/s drip against xterm's
-// ~100 MB/s parse rate (measured: scheduler-throughput bench + baseline-jul02).
-// Only high-priority (visible-pane) backlogs are pacer-clocked; background
-// panes keep the fixed cadence that protects the focused terminal.
+// Why: re-arm a zero-delay drain once xterm confirms the previous high-priority batch parsed; the fixed 4/16ms cadence otherwise drips far below xterm's ~100 MB/s parse. Only visible panes are pacer-clocked; background keeps the fixed cadence to protect the focused terminal.
 function makeParseClockPacer(): () => void {
   return () => {
     try {
@@ -904,8 +857,7 @@ function makeParseClockPacer(): () => void {
         scheduleDrain(0)
       }
     } catch {
-      // Why: runs inside xterm's write-callback chain; a throw here would
-      // wedge the terminal (see xterm-write-callback-guard.ts).
+      // Why: runs inside xterm's write-callback chain; a throw here would wedge the terminal (see xterm-write-callback-guard.ts).
     }
   }
 }
@@ -916,9 +868,7 @@ function composeParsedCallback(
   ackCreditsParsed: (() => void) | undefined,
   pacer: (() => void) | undefined
 ): TerminalOutputParsedCallback {
-  // Why always non-undefined: the write-completion callback doubles as the
-  // pipeline-health settle signal. A write with no callback could never settle
-  // the stall watch, forcing a probe round-trip for every healthy idle pane.
+  // Why always non-undefined: the callback doubles as the pipeline-health settle signal — with none, the stall watch could never settle, forcing a probe round-trip per healthy idle pane.
   return () => {
     try {
       onParsed?.()
@@ -939,8 +889,7 @@ function composeWriteFailureCallback(
       // A rejected write still consumed the main-owned delivery window.
       ackCreditsParsed?.()
     } finally {
-      // Why: a synchronous rejection proves undeliverability, but it proves
-      // nothing about parse progress. Recover without extending replay guards.
+      // Why: a synchronous rejection proves undeliverability but nothing about parse progress; recover without extending replay guards.
       failTerminalWriteStallWatch(terminal)
     }
   }
@@ -959,13 +908,7 @@ function writeQueuedChunk(entry: QueueEntry): 'foreground' | 'background' | null
   }
   const pacer = entry.highPriority ? makeParseClockPacer() : undefined
   const ackCreditsParsed = registerTerminalOutputAckCredits(entry.terminal, queuedWrite.ackCredits)
-  // Why armed BEFORE the write: a wedged WriteBuffer (escaping callback throw,
-  // issue #2836) or a disposed xterm (write() silently drops its completion —
-  // verified against 6.1.0-beta.287) never runs the parsed callback below. The
-  // stall watch probe-certifies dead-vs-slow and hands the pane to recovery;
-  // the entry cleanup credits queued deliveries so main's in-flight window
-  // never leaks. Arming first keeps a synchronously-completing write able to
-  // settle its own watch.
+  // Why armed BEFORE the write: a wedged WriteBuffer (issue #2836) or disposed xterm (6.1.0-beta.287) never runs the parsed callback, so the watch must be live first to catch it.
   armTerminalWriteStallWatch(entry.terminal, {
     onCertifiedDead: () => discardTerminalOutput(entry.terminal)
   })
@@ -997,8 +940,7 @@ function writeQueuedChunk(entry: QueueEntry): 'foreground' | 'background' | null
           composeWriteFailureCallback(entry.terminal, ackCreditsParsed)
         )
     if (!writeAccepted) {
-      // The failure callback credited the submitted chunk; credit and abandon
-      // the detached tail so the drain cannot retry a certified-dead xterm.
+      // Why: the failure callback credited the submitted chunk; credit and abandon the detached tail so the drain can't retry a certified-dead xterm.
       fireQueuedAckCredits(entry)
       entry.chunks.length = 0
       entry.chunkIndex = 0
@@ -1009,8 +951,7 @@ function writeQueuedChunk(entry: QueueEntry): 'foreground' | 'background' | null
       return null
     }
   } catch {
-    // Why: beforeWrite or write setup can fail before xterm owns the bytes.
-    // Cancel the armed watch without claiming parser failure.
+    // Why: beforeWrite or write setup can fail before xterm owns the bytes; cancel the armed watch without claiming parser failure.
     cancelTerminalWriteStallWatch(entry.terminal)
     ackCreditsParsed?.()
     fireQueuedAckCredits(entry)
@@ -1065,8 +1006,7 @@ function drainQueuedOutput(): void {
       clearForegroundCoalesce(entry)
       clearForegroundHoldSafety(entry)
     }
-    // Why: xterm parsing and DOM work share the renderer thread with input.
-    // Keep backlog draining cooperative so WSL/agent output cannot pin the UI.
+    // Why: xterm parsing and DOM work share the renderer thread with input; keep draining cooperative so WSL/agent output can't pin the UI.
     if (writes > 0 && getDrainNow() - startedAt >= DRAIN_TIME_BUDGET_MS) {
       break
     }
@@ -1077,11 +1017,7 @@ function drainQueuedOutput(): void {
   }
   recordQueueDebugPressure()
   if (queuedByTerminal.size > 0 && hasDrainableBacklog()) {
-    // Why 0 on the channel path: the 4ms high-priority interval existed to
-    // yield between ticks, but a posted message already yields — Chromium
-    // services input and paint between macrotasks. The explicit sleep only
-    // deepened the standing queue (~4ms per 128KB tick). Timer path keeps
-    // the interval so fake-timer tests retain stepwise drain semantics.
+    // Why 0 on the channel path: a posted message already yields (input/paint serviced between macrotasks), so the 4ms interval only deepened the queue; timer path keeps it for fake-timer tests.
     scheduleDrain(
       hasHighPriorityBacklog()
         ? useMessageChannelDrain
@@ -1098,15 +1034,13 @@ export function writeTerminalOutput(
   options: WriteTerminalOutputOptions
 ): void {
   exposeDebugApi()
-  // Why: recovery may be budget-delayed while PTY output keeps flowing. Main
-  // owns the authoritative buffer; credit delivery without waking dead xterm.
+  // Why: recovery may be budget-delayed while PTY output keeps flowing; main owns the authoritative buffer, so credit delivery without waking dead xterm.
   if (isTerminalWritePipelineCertifiedDead(terminal)) {
     options.ackCredit?.()
     return
   }
   if (!data) {
-    // Why: an empty write still consumed its delivery — credit or main's
-    // in-flight window leaks.
+    // Why: an empty write still consumed its delivery — credit or main's in-flight window leaks.
     options.ackCredit?.()
     return
   }
@@ -1132,20 +1066,16 @@ export function writeTerminalOutput(
         debugState.foregroundWriteCount++
         debugState.deferredForegroundEnqueueCount++
       }
-      // Why: a visible pane's queue was previously uncapped — a flood the
-      // drain can't keep up with ballooned renderer memory without bound.
+      // Why: a visible pane's queue was previously uncapped — a flood the drain couldn't keep up with ballooned renderer memory without bound.
       if (queueCapExceeded(queued)) {
         replaceBacklogWithWarning(queued, FOREGROUND_BACKLOG_WARNING)
         scheduleDrain(0)
         return
       }
       if (options.holdForeground) {
-        // Why: synchronized-output start/body chunks contain transient cursor
-        // moves. Holding them prevents Chromium from rasterizing those states.
+        // Why: synchronized-output start/body chunks contain transient cursor moves; holding them prevents Chromium from rasterizing those states.
         if (options.latencySensitive === true) {
-          // Why: Codex composer redraws can split the end marker from the
-          // input-triggered frame; keep cursor protection without adding a
-          // human-visible fallback delay to typed characters.
+          // Why: Codex composer redraws can split the end marker from the input-triggered frame; keep cursor protection without a human-visible fallback delay on typed chars.
           queued.foregroundHoldSafetyDelayMs = Math.min(
             queued.foregroundHoldSafetyDelayMs,
             LATENCY_SENSITIVE_FOREGROUND_HOLD_SAFETY_DELAY_MS
@@ -1163,8 +1093,7 @@ export function writeTerminalOutput(
         clearForegroundHoldSafety(queued)
         const shouldShortenCoalesceForLatencySensitiveForeground = options.latencySensitive === true
         if (shouldShortenCoalesceForLatencySensitiveForeground) {
-          // Why: user input echo must not inherit the normal synchronized-frame
-          // restore fallback; wait briefly for the restore, then paint.
+          // Why: user input echo must not inherit the normal synchronized-frame restore fallback; wait briefly for the restore, then paint.
           queued.foregroundCoalesceDelayMs = Math.min(
             queued.foregroundCoalesceDelayMs,
             LATENCY_SENSITIVE_FOREGROUND_COALESCE_DELAY_MS
@@ -1178,9 +1107,7 @@ export function writeTerminalOutput(
           scheduleDrain(0)
           return
         }
-        // Why: TUI synchronized-output end markers can be split from the
-        // immediate cursor-restoring bytes by the PTY transport. Wait only
-        // until the restore arrives; the timer is a bounded fallback.
+        // Why: the PTY transport can split TUI synchronized-output end markers from the cursor-restoring bytes; wait for the restore, with the timer as bounded fallback.
         scheduleForegroundCoalesceRelease(queued, {
           rescheduleEarlier: shouldShortenCoalesceForLatencySensitiveForeground
         })
@@ -1211,9 +1138,7 @@ export function writeTerminalOutput(
       if (queueCapExceeded(entry)) {
         replaceBacklogWithWarning(entry, FOREGROUND_BACKLOG_WARNING)
       }
-      // Why: returning from a hidden window can have megabytes queued. Keep
-      // byte order, but drain it asynchronously so the first foreground frame
-      // is not pinned behind the entire backlog.
+      // Why: returning from a hidden window can have megabytes queued — keep byte order but drain async so the first foreground frame isn't pinned behind the whole backlog.
       scheduleDrain(0)
       return
     }
@@ -1243,9 +1168,7 @@ export function writeTerminalOutput(
       if (queueCapExceeded(queued)) {
         replaceBacklogWithWarning(queued, FOREGROUND_BACKLOG_WARNING)
       }
-      // Why: visible command floods are throughput work, not keystroke echo.
-      // Queue them behind a zero-delay drain so one IPC callback cannot pin
-      // the renderer in xterm.write while input and paint are waiting.
+      // Why: visible command floods are throughput work, not keystroke echo — queue behind a zero-delay drain so one IPC callback can't pin the renderer while input/paint wait.
       scheduleDrain(0)
       return
     }
@@ -1275,8 +1198,7 @@ export function writeTerminalOutput(
         }
       )
     } catch (error) {
-      // beforeWrite can throw before xterm owns the callback; consume the
-      // delivery here. xterm write throws are caught by the foreground writer.
+      // Why: beforeWrite can throw before xterm owns the callback, so consume the delivery here (xterm write throws are caught by the foreground writer).
       ackCreditsParsed?.()
       cancelTerminalWriteStallWatch(terminal)
       throw error
@@ -1303,9 +1225,7 @@ export function writeTerminalOutput(
   if (debugEnabled) {
     debugState.backgroundEnqueueCount++
   }
-  // Why: non-focused panes can produce output continuously. Letting every
-  // pane call xterm.write immediately schedules one xterm WriteBuffer timer
-  // per pane, which starves the focused terminal on the shared renderer thread.
+  // Why: letting every non-focused pane call xterm.write immediately spawns a WriteBuffer timer per pane, starving the focused terminal on the shared renderer thread.
   scheduleDrain(
     entry.highPriority || entry.queuedChars > LARGE_BACKLOG_CHARS ? 0 : BACKGROUND_FLUSH_DELAY_MS
   )
@@ -1388,8 +1308,7 @@ export function flushTerminalOutput(
         return
       }
     } catch {
-      // Why: pre-write hooks/setup failed before xterm owned these bytes.
-      // Cancel the watch; consumed + abandoned chunks still credit delivery.
+      // Why: pre-write hooks/setup failed before xterm owned these bytes; cancel the watch, but consumed + abandoned chunks still credit delivery.
       cancelTerminalWriteStallWatch(terminal)
       ackCreditsParsed?.()
       fireQueuedAckCredits(entry)
@@ -1443,8 +1362,7 @@ export function registerTerminalBacklogRecovery(
 export function waitForTerminalOutputParsed(terminal: TerminalOutputTarget): Promise<void> {
   flushTerminalOutput(terminal)
   if (isTerminalWritePipelineCertifiedDead(terminal)) {
-    // A dead pipeline cannot settle; recovery owns it and serializers must not
-    // enqueue probe writes while a bounded remount retry is pending.
+    // Why: a dead pipeline cannot settle; recovery owns it and serializers must not enqueue probe writes during a pending remount retry.
     return Promise.resolve()
   }
 
@@ -1462,8 +1380,7 @@ export function waitForTerminalOutputParsed(terminal: TerminalOutputTarget): Pro
       resolve()
     }
     const finishParsed = (): void => {
-      // Why: serializer/startup probes share xterm's FIFO with replay guards;
-      // their completion is real parser progress even though they carry no bytes.
+      // Why: serializer/startup probes share xterm's FIFO with replay guards; their completion is real parser progress despite carrying no bytes.
       recordTerminalParseProgress(terminal)
       finish()
     }
@@ -1471,8 +1388,7 @@ export function waitForTerminalOutputParsed(terminal: TerminalOutputTarget): Pro
     try {
       terminal.write('', finishParsed)
     } catch {
-      // Why: a synchronous rejection means this concrete xterm cannot accept
-      // even an empty FIFO probe; recovery must replace it before reuse.
+      // Why: a synchronous rejection means this xterm can't accept even an empty FIFO probe; recovery must replace it before reuse.
       failTerminalWriteStallWatch(terminal)
       finish()
     }
@@ -1483,15 +1399,13 @@ export function discardTerminalOutput(terminal: TerminalOutputTarget): void {
   exposeDebugApi()
   const entry = queuedByTerminal.get(terminal)
   if (entry) {
-    // Why: discarded queued chunks still consumed their deliveries — credit
-    // them or main's in-flight window leaks (see fireQueuedAckCredits).
+    // Why: discarded chunks still consumed their deliveries — credit them or main's in-flight window leaks (fireQueuedAckCredits).
     fireQueuedAckCredits(entry)
   }
   discardInFlightTerminalOutputAckCredits(terminal)
   queuedByTerminal.delete(terminal)
   discardForegroundRenderSettle(terminal)
-  // Why: cleanup must cancel the watch without masquerading as parse progress;
-  // replay guards use real completions to distinguish slow from wedged.
+  // Why: cancel the watch without masquerading as parse progress; replay guards use real completions to tell slow from wedged.
   cancelTerminalWriteStallWatch(terminal)
   recordQueueDebugPressure()
 }
diff --git a/src/renderer/src/lib/pane-manager/terminal-arabic-shaping-joiner.ts b/src/renderer/src/lib/pane-manager/terminal-arabic-shaping-joiner.ts
index 802f708b8e4..e5bb91c81fa 100644
--- a/src/renderer/src/lib/pane-manager/terminal-arabic-shaping-joiner.ts
+++ b/src/renderer/src/lib/pane-manager/terminal-arabic-shaping-joiner.ts
@@ -14,24 +14,14 @@ const lazyArabicShapingJoinerByTerminal = new WeakMap<
   LazyArabicShapingJoinerState
 >()
 
-// Why: xterm draws every cell's glyph in isolation, so Arabic output shows
-// disconnected letterforms in logical (reversed) order — upstream has no
-// BiDi/shaping support (xtermjs/xterm.js#701, Orca #5262). Joining each RTL
-// run into one cell range makes both renderers (WebGL atlas, DOM row factory)
-// draw the run as a single string, letting the browser apply contextual
-// shaping and BiDi ordering inside the run's grid-aligned cell box. The
-// terminal buffer and PTY stream are untouched, and xterm itself un-joins any
-// range that holds the cursor or a partially selected span, so cursor
-// visibility and selection stay cell-accurate.
+// Why: xterm lacks BiDi/shaping (xterm.js#701, Orca #5262); joining each RTL run into one cell lets the browser shape and reorder it.
 
-// Every strong-RTL script block sits at or above U+0590, so plain ASCII/Latin
-// segments bail out with a single charCodeAt sweep and no per-char decode.
+// Every strong-RTL block sits at/above U+0590, so ASCII/Latin bails out with a single charCodeAt sweep.
 const RTL_SCAN_FLOOR = 0x0590
 
 export function isStrongRtlCodePoint(codePoint: number): boolean {
   return (
-    // Hebrew, Arabic, Syriac, Arabic Sup, Thaana, NKo, Samaritan, Mandaic,
-    // Syriac Sup, Arabic Extended-B/A — one contiguous strong-RTL span.
+    // One contiguous strong-RTL span (Hebrew through Arabic Extended-A).
     (codePoint >= 0x0590 && codePoint <= 0x08ff) ||
     // Hebrew + Arabic presentation forms (legacy shaped codepoints).
     (codePoint >= 0xfb1d && codePoint <= 0xfdff) ||
@@ -64,10 +54,7 @@ function containsStrongRtlText(text: string): boolean {
   return false
 }
 
-// Neutral characters may sit inside an RTL run (so a multi-word phrase joins
-// as one unit and keeps right-to-left word order) but never start or end one:
-// ASCII space/digits/punctuation and NBSP. ASCII letters are strong LTR and
-// always break a run so paths like `test.txt` never get pulled into one.
+// Neutrals may sit inside a run but never open/close it; ASCII letters break runs so paths like test.txt aren't pulled in.
 function isRunNeutralCharCode(charCode: number): boolean {
   if (charCode < 0x20) {
     return false
@@ -80,16 +67,7 @@ function isRunNeutralCharCode(charCode: number): boolean {
   return charCode === 0xa0
 }
 
-// ZWNJ/ZWJ shape within a word (mandatory in Persian/Kurdish orthography) and
-// RLM/ALM assert RTL context — breaking the run on them would split one word
-// into two joined chunks laid out in swapped visual order. Transparent: never
-// opens, closes, extends, or counts toward a run. LRM (U+200E) is strong LTR
-// and intentionally still breaks the run.
-// The zero-width Cf controls inside the RTL blocks (Arabic number signs
-// U+0600–0605, end of ayah U+06DD, Syriac abbreviation mark U+070F, disputed
-// end of ayah U+08E2) and BOM/ZWNBSP U+FEFF are width-0 in xterm, so like
-// combining marks they must never open or count a run (an empty joined cell
-// range blanks the following glyph in WebGL) — and they have no shape to join.
+// Run-transparent format controls: breaking on them would split a word, or open an empty joined range that blanks a glyph.
 function isRtlRunTransparentCodePoint(codePoint: number): boolean {
   return (
     codePoint === 0x200c ||
@@ -104,35 +82,22 @@ function isRtlRunTransparentCodePoint(codePoint: number): boolean {
   )
 }
 
-// Why: a combining mark renders inside its base's cell, so a run opened at a
-// mark starts mid-cell — xterm rounds that to an empty joined cell range and
-// the WebGL renderer then draws an empty glyph over the next character. Marks
-// may extend and count only after a spacing RTL letter opened the run.
+// Why: opening a run at a combining mark (renders in its base cell) makes an empty joined range that blanks a glyph in WebGL.
 const COMBINING_MARK = /\p{Mn}/u
 function canOpenRtlRun(codePoint: number): boolean {
   return !COMBINING_MARK.test(String.fromCodePoint(codePoint))
 }
 
 /**
- * Character-joiner handler for xterm's registerCharacterJoiner API. Receives
- * one attribute-homogeneous segment of a row and returns [start, end) string
- * ranges that should render as single joined units.
+ * Character-joiner handler for xterm's registerCharacterJoiner API: returns the
+ * [start, end) ranges of a row segment that should render as joined units. A run
+ * spans the first to last strong-RTL code point, tunneling neutrals; runs of
+ * fewer than two RTL code points are skipped (isolated forms already render).
  *
- * A run spans from the first strong-RTL code point to the last one of a
- * cluster, tunneling through neutral characters between RTL words. Runs with
- * fewer than two RTL code points are skipped: an isolated Arabic letter
- * already renders in its correct (isolated) form cell-by-cell.
- *
- * Known upstream limitation (affects every joiner, ligatures too): a
- * standalone width-0 cell (e.g. RLM at line start) makes xterm's
- * CharacterJoinerService skip the cell without advancing its string index,
- * shifting the run's cell range by one — fix belongs upstream in xterm.js.
- *
- * Known upstream limitation #2: the WebGL renderer un-joins a range for the
- * cursor or a partial selection but not for decorations, so a search-match
- * highlight inside a joined run renders all-or-nothing — the whole run when
- * the match covers the run's first cell, otherwise not at all. Same class as
- * ligatures today, extended here to phrase-length runs.
+ * Known xterm limitations: a standalone width-0 cell (e.g. RLM at line start)
+ * shifts the run's cell range by one; and the WebGL renderer un-joins for
+ * cursor/selection but not decorations, so a search-match highlight inside a run
+ * renders all-or-nothing.
  */
 export function findRtlJoinRanges(text: string): [number, number][] {
   const length = text.length
@@ -142,9 +107,7 @@ export function findRtlJoinRanges(text: string): [number, number][] {
       break
     }
   }
-  // Why: xterm merges other joiners' results into the returned array in
-  // place, so this must be a fresh array on every call — never a shared
-  // constant. The non-RTL fast path above keeps the allocation the only cost.
+  // Why: xterm merges other joiners' results into this array in place, so it must be freshly allocated each call.
   const ranges: [number, number][] = []
   if (i === length) {
     return ranges
@@ -189,8 +152,7 @@ export function findRtlJoinRanges(text: string): [number, number][] {
         runRtlCount++
       }
     } else if (runStart !== -1) {
-      // Non-RTL above the floor (box drawing, CJK, emoji, …) breaks the run
-      // so TUI borders and East Asian text keep per-cell rendering.
+      // Non-RTL above the floor (box drawing, CJK, emoji) breaks the run so TUI borders and CJK keep per-cell rendering.
       closeRun()
     }
     i += codeUnitLength - 1
@@ -199,20 +161,12 @@ export function findRtlJoinRanges(text: string): [number, number][] {
   return ranges
 }
 
-/** Register the RTL shaping joiner on a terminal. Returns a cleanup that
- *  deregisters the joiner — `Terminal.dispose()` does not remove registered
- *  character joiners, so disposePane() must call this to avoid leaking the
- *  registration (xtermjs/xterm.js#3289). */
+/** Register the RTL shaping joiner; returns a cleanup deregistering it — Terminal.dispose() leaks joiners (xtermjs/xterm.js#3289). */
 export function registerArabicShapingJoiner(
   terminal: ArabicShapingTerminal,
   isShapingActive: () => boolean
 ): () => void {
-  // Why: the DOM renderer sizes a joined span with one letter-spacing value
-  // that the browser applies after every character, so a joined run whose
-  // shaped width differs from its cell budget blows out the whole row's grid
-  // alignment. Join only while the WebGL renderer is live (checked per render
-  // call, so context-loss/GPU-setting fallbacks revert to per-cell rendering
-  // on their own refresh); DOM-rendered panes keep xterm's unshaped default.
+  // Why: DOM renderer letter-spacing breaks grid alignment for joined runs, so join only while WebGL is the live renderer.
   const joinerId = terminal.registerCharacterJoiner((text) =>
     isShapingActive() ? findRtlJoinRanges(text) : []
   )
@@ -221,9 +175,7 @@ export function registerArabicShapingJoiner(
   }
 }
 
-/** Configure RTL shaping without registering an xterm character joiner until
- *  output actually contains RTL text. Any registered joiner makes xterm scan
- *  every visible cell on every repaint, even when its handler returns no ranges. */
+/** Configure lazy RTL shaping; defer joiner registration since any joiner makes xterm rescan every cell each repaint. */
 export function configureLazyArabicShapingJoiner(
   terminal: ArabicShapingTerminal,
   isShapingActive: () => boolean
@@ -267,8 +219,7 @@ export function ensureArabicShapingJoinerForText(
     return
   }
 
-  // Why: PTY/replay chunks can split supplementary-plane RTL code points
-  // between their surrogate halves; retain only that one boundary code unit.
+  // Why: PTY/replay chunks can split a supplementary-plane RTL code point across surrogate halves; keep the boundary unit.
   const scanText = state.trailingHighSurrogate + text
   const finalCharacter = scanText.at(-1) ?? ''
   const finalCodeUnit = finalCharacter.charCodeAt(0)
@@ -283,7 +234,6 @@ export function ensureArabicShapingJoinerForText(
   try {
     state.cleanup = registerArabicShapingJoiner(terminal, state.isShapingActive)
   } catch {
-    // Why: shaping is optional; a registration race with pane disposal must
-    // never drop the PTY/replay bytes that triggered it or retry every chunk.
+    // Why: shaping is optional; swallow a registration race with pane disposal rather than drop bytes.
   }
 }
diff --git a/src/renderer/src/lib/telemetry.ts b/src/renderer/src/lib/telemetry.ts
index 2bf00b879d7..18f2103292e 100644
--- a/src/renderer/src/lib/telemetry.ts
+++ b/src/renderer/src/lib/telemetry.ts
@@ -1,37 +1,16 @@
-// Typed renderer-side wrapper around the preload bridge.
-//
-// Renderer call sites import `track` from this module rather than reaching
-// for `window.api.telemetryTrack` directly, because this wrapper is what
-// gives them the `EventMap`-based type safety. The preload bridge is
-// deliberately typed as a loose `(name: string, props: Record<string,
-// unknown>) => Promise<void>` so it can cross the IPC boundary without
-// pretending the renderer's types are load-bearing — the main-side
-// validator is the single enforcement point.
-//
-// The renderer does NOT bundle `posthog-node` or any PostHog SDK. There is
-// one PostHog client in the process tree and it lives in main. That
-// invariant is what keeps the vendor out of the renderer's attack surface.
+// Typed renderer-side wrapper around the preload bridge: gives call sites EventMap type safety, while main stays the single validator.
+// Security invariant: the renderer bundles no PostHog SDK — the sole client lives in main, off the renderer's attack surface.
 
 import type { EventName, EventProps } from '../../../shared/telemetry-events'
 import type { TelemetryConsentState } from '../../../shared/telemetry-consent-types'
 
-// Re-exported so renderer call sites can import the mapper from this lib
-// alongside `track`. The implementation lives in `src/shared/agent-kind.ts`
-// because main-process telemetry emission needs the same mapping when it
-// receives a `TuiAgent`-derived agent kind through the spawn IPC.
+// Re-exported so renderer call sites can import the mapper alongside `track` (impl is shared because main needs the same mapping).
 export { tuiAgentToAgentKind } from '../../../shared/agent-kind'
 
-// Why: single source-of-truth for the privacy doc URL linked from the two
-// telemetry surfaces (FirstLaunchBanner, PrivacyPane). Keeping it here — in
-// the shared telemetry lib — prevents the surfaces from drifting if the doc
-// ever moves.
+// Single source-of-truth for the privacy doc URL so FirstLaunchBanner and PrivacyPane can't drift.
 export const PRIVACY_URL = 'https://www.onorca.dev/docs/telemetry'
 
-// Why: the IPC boundary is untyped at runtime, so a malformed payload from
-// main would otherwise let the Privacy pane render on garbage. Validate the
-// `effective` discriminant (and `reason` when disabled) before trusting it;
-// fall through to `pending_banner` otherwise, matching the bridge-missing
-// fail-closed behavior below.
+// Why: the IPC boundary is untyped at runtime, so validate before the Privacy pane trusts a payload from main.
 function isTelemetryConsentState(x: unknown): x is TelemetryConsentState {
   if (!x || typeof x !== 'object') {
     return false
@@ -48,13 +27,7 @@ function isTelemetryConsentState(x: unknown): x is TelemetryConsentState {
 }
 
 export function track<N extends EventName>(name: N, props: EventProps<N>): void {
-  // Why: telemetry must never throw into the renderer. A missing bridge
-  // (tests, early init, sandboxed iframe) would turn `window.api.telemetryTrack`
-  // into a synchronous TypeError that defeats the documented fire-and-forget
-  // contract. Log (do not rethrow) on both the sync throw and any promise
-  // rejection so IPC failures leave a diagnostic breadcrumb while preserving
-  // the fire-and-forget contract — silent swallowing would let disk state
-  // drift out of sync with UI state with zero signal to anyone debugging.
+  // Why: telemetry is fire-and-forget and must never throw into the renderer; log (don't rethrow/silently swallow) so IPC failures leave a breadcrumb.
   try {
     void window.api?.telemetryTrack?.(name, props as Record<string, unknown>)?.catch((err) => {
       console.warn('[telemetry] IPC track failed', err)
@@ -64,10 +37,7 @@ export function track<N extends EventName>(name: N, props: EventProps<N>): void
   }
 }
 
-// Returns a Promise so callers that need to order a subsequent settings
-// write after the opt-in event can `await` it. Most call sites ignore the
-// return value; the fire-and-forget contract is preserved by resolving
-// (not rejecting) on any bridge error.
+// Returns a Promise (resolves, never rejects) so callers can await ordering a settings write after the opt-in event.
 export function setOptIn(optedIn: boolean): Promise<void> {
   try {
     return (
@@ -81,10 +51,7 @@ export function setOptIn(optedIn: boolean): Promise<void> {
   }
 }
 
-// Read the effective consent state for Privacy-pane rendering. Fails
-// closed to `pending_banner` if the bridge is missing (tests, sandbox),
-// which the UI treats like a non-actionable/disabled toggle — safer than
-// pretending the toggle is live when we cannot confirm consent.
+// Fails closed to `pending_banner` when the bridge is missing, so the UI never shows a live toggle we can't confirm.
 export async function getConsentState(): Promise<TelemetryConsentState> {
   try {
     const result = await window.api?.telemetryGetConsentState?.()
@@ -95,20 +62,8 @@ export async function getConsentState(): Promise<TelemetryConsentState> {
   }
 }
 
-// Banner ✕ — silent persisted opt-IN (acknowledge without eventing).
-// Separate channel from `setOptIn(true)` because the event contract for
-// the ✕ path is "persist optedIn=true, fire nothing." Routing this through
-// `setOptIn(true)` would derive `via='first_launch_banner'` and emit
-// `telemetry_opted_in`, which the ✕-as-silent-acknowledge semantics
-// forbid — the user did not explicitly opt in, they declined to intervene.
-// The only renderer surface that calls this bridge is the FirstLaunchBanner
-// ✕ button; the banner's "Turn off" and every other opt-{in,out} path
-// uses `setOptIn(…)` so the corresponding event still fires.
-//
-// Returns a Promise so callers that need to order a subsequent settings
-// fetch after main has persisted the acknowledge can `await` it. Most
-// call sites ignore the return value; the fire-and-forget contract is
-// preserved by resolving (not rejecting) on any bridge error.
+// Banner ✕ = silent persisted opt-in: unlike setOptIn(true) it must NOT emit telemetry_opted_in (user declined to intervene, didn't opt in).
+// Returns a Promise (resolves, never rejects) so callers can await ordering a settings fetch after the acknowledge persists.
 export function acknowledgeBanner(): Promise<void> {
   try {
     return (
diff --git a/src/renderer/src/lib/use-tab-agent.ts b/src/renderer/src/lib/use-tab-agent.ts
index b75273befbe..c3eb287afd2 100644
--- a/src/renderer/src/lib/use-tab-agent.ts
+++ b/src/renderer/src/lib/use-tab-agent.ts
@@ -15,8 +15,7 @@ import { resolveCompatibleAgentTypeForOwner } from '../../../shared/agent-title-
 import { resolvePaneAgentOwner } from '../../../shared/pane-agent-owner'
 import type { TerminalTab, TuiAgent } from '../../../shared/types'
 
-// A shell name, or the tab's neutral default title — where Orca's
-// inferred-interrupt reset parks it. Blank titles are no evidence either way.
+// A shell name or the tab's neutral default title (where inferred-interrupt reset parks it); blank titles are no evidence.
 function titleShowsNoAgent(title: string, defaultTitle?: string): boolean {
   const trimmed = title.trim()
   return trimmed.length > 0 && (isShellProcess(trimmed) || trimmed === defaultTitle?.trim())
@@ -36,11 +35,9 @@ function resolveSignalAgentForLaunchOwner(
 }
 
 /**
- * Probe-free evidence that a launched agent exited: the title shows no agent,
- * no live hook row remains in the tab, and either the hook completed or
- * previously observed activity vanished. The vanished-activity disjunct is
- * local-only: remote rows also drop on transport blips that say nothing about
- * the process.
+ * Probe-free evidence a launched agent exited: title shows no agent, no live
+ * hook remains, and either the hook completed or observed activity vanished.
+ * Vanished-activity is local-only — remote rows also drop on transport blips.
  */
 export function resolveLaunchedAgentExitEvidence(args: {
   title: string
@@ -56,10 +53,7 @@ export function resolveLaunchedAgentExitEvidence(args: {
   if (args.hookAgent || args.siblingHookAgent || args.processAgent) {
     return false
   }
-  // Why: OSC 133;D proved the foreground returned to the shell — process-grade
-  // exit evidence that doesn't depend on the agent leaving a clean title.
-  // Local-only by construction (remote panes have no shell-foreground producer);
-  // the gate keeps the invariant even for out-of-pipeline callers.
+  // Why: OSC 133;D (foreground back at shell) is title-independent exit evidence; local-only — remote panes have no shell-foreground producer.
   if (!args.isRemote && args.processShellForeground && args.hasObservedAgentSignal) {
     return true
   }
@@ -84,15 +78,7 @@ export function resolveTabAgentFromSignals(args: {
   launchAgent?: TuiAgent
 }): TuiAgent | null {
   const launchAgent = args.launchAgent ?? null
-  // The focused pane's durable agent owner: launch intent first, then this
-  // pane's own host-stamped hook identity (live or completed), then its
-  // hibernated session record. It anchors every identity decision for THIS pane
-  // — it re-owns ambiguous Pi-compatible wrapper titles (OMP emits Pi's frames)
-  // and keeps a mirrored or restored pane, which dropped its host-owned
-  // launchAgent, resolving through the durable record instead of the title.
-  // Why: strictly focused-pane-scoped — a sibling split-pane's identity says
-  // nothing about which Pi-variant this pane runs, so it must not re-own the
-  // focused title (it would mislabel a genuine Pi pane as its sibling's OMP).
+  // Durable focused-pane owner (launch intent → hook → session); focused-pane-scoped so a sibling can't re-own the focused title (would mislabel a Pi pane as OMP).
   const owner = resolvePaneAgentOwner({
     launchAgent,
     hookAgent: args.hookAgent,
@@ -100,18 +86,10 @@ export function resolveTabAgentFromSignals(args: {
     sleepingSessionAgent: args.sleepingSessionAgent
   }) as TuiAgent | null
 
-  // A pane's identity comes from its hook record regardless of activity state —
-  // being idle between turns must not erase which agent is here. We keep the
-  // live/idle split only because it governs how a title may override identity: a
-  // LIVE hook is ground truth (a title never overrides it), while an IDLE record
-  // is durable but a cross-group title can reclaim a pane reused for a different
-  // agent. Sibling identities normalize against launchAgent only (the tab's
-  // shared launch intent), never the focused pane's own hook identity.
+  // The live/idle split governs title override: a LIVE hook is never title-overridden; an IDLE record can be reclaimed by a cross-group title. Siblings normalize vs launchAgent only.
   const liveFocusedIdentity = resolveSignalAgentForLaunchOwner(args.hookAgent, owner)
   const liveSiblingIdentity = resolveSignalAgentForLaunchOwner(args.siblingHookAgent, launchAgent)
-  // Why: OSC 133;D proved this local pane's foreground is back at the shell, so
-  // the finished agent's idle identity is stale and must stop painting the tab.
-  // Remote titles lag their runtime, so keep the idle identity there.
+  // Why: OSC 133;D proves this local pane returned to shell, so the idle identity is stale; remote titles lag runtime, so keep it there.
   const processProvesShell = !args.isRemote && args.processShellForeground === true
   const hasCompletedHook = (args.focusedCompletedHookAgent ?? null) !== null
   const noAgentTitle = titleShowsNoAgent(args.title, args.defaultTitle)
@@ -120,29 +98,19 @@ export function resolveTabAgentFromSignals(args: {
   const idleFocusedIdentity = idleIdentitySuppressed
     ? null
     : resolveSignalAgentForLaunchOwner(args.focusedCompletedHookAgent, owner)
-  // Why: `idleIdentitySuppressed` is the FOCUSED pane's own exit evidence, so it
-  // must not clear a sibling split-pane's idle identity — a focused pane back at
-  // its shell says nothing about whether the sibling's agent has exited.
+  // Why: idleIdentitySuppressed is the FOCUSED pane's exit evidence, so it must not clear a sibling's idle identity.
   const idleSiblingIdentity = resolveSignalAgentForLaunchOwner(
     args.siblingCompletedHookAgent,
     launchAgent
   )
 
-  // The title carries identity in only two roles: (a) a reuse override — it
-  // names a DIFFERENT-group agent than the pane's known identity, proving the
-  // pane was reused for a new agent — or (b) a legacy standalone identity when
-  // the pane has no hook at all. Within the same title-identity group it says
-  // nothing (OMP wraps Pi and emits identical frames), so the durable record
-  // wins; re-owning explicitTitleAgent through `owner` enforces that.
+  // Title carries identity only as a reuse override (names a DIFFERENT-group agent) or a legacy standalone id when no hook — same-group titles say nothing (OMP wraps Pi), so the record wins.
   const explicitTitleAgent = resolveSignalAgentForLaunchOwner(
     resolveExplicitTerminalTitleAgentType(args.title),
     owner
   )
   const priorIdentity = idleFocusedIdentity ?? launchAgent
-  // Why: a completed hook is itself proof the pane has shown activity, so it
-  // arms the reuse override without waiting for `hasObservedAgentSignal` — which
-  // starts false for one mount commit and would otherwise flash the exited
-  // agent's idle identity before the new (hookless) agent's title reclaims.
+  // Why: a completed hook already proves activity, so it arms the reuse override without waiting for hasObservedAgentSignal (false for one mount commit).
   const titleReclaimsReusedPane =
     priorIdentity !== null &&
     explicitTitleAgent !== null &&
@@ -168,19 +136,10 @@ export function resolveTabAgentFromSignals(args: {
     processShellForeground: args.processShellForeground
   })
   const activeLaunchAgent = launchedAgentExited ? null : launchAgent
-  // Why: the foreground process, like the hook and title signals, must be
-  // re-owned within its title-identity group. OMP wraps Pi as `shell → omp → pi`,
-  // so the foreground reader oscillates between reporting `omp` and `pi` across
-  // command boundaries; taken raw it outranks launchAgent and flips an OMP-owned
-  // tab's icon between the two glyphs. Re-owning collapses the same-group read
-  // onto the durable owner while a genuine cross-group process still stands.
+  // Why: re-own the foreground process within its title-identity group so OMP's nested pi (shell → omp → pi) can't flip an OMP-owned tab's icon.
   const processAgent = resolveSignalAgentForLaunchOwner(args.processAgent, owner)
   const sleepingSessionAgent = args.sleepingSessionAgent ?? null
-  // Identity-first precedence. The live focused hook is ground truth while the
-  // agent works; process identity covers agents with neither hook nor title; the
-  // title then acts only in its reuse-override / legacy roles; and the pane's
-  // durable idle identity — the record for an agent that ran here and went idle —
-  // ranks above the hibernated session, the launch bootstrap, and sibling panes.
+  // Identity-first precedence (see JSDoc): live hook > process > title > idle > sleeping > launch > sibling.
   return (
     liveFocusedIdentity ??
     processAgent ??
@@ -195,29 +154,16 @@ export function resolveTabAgentFromSignals(args: {
 
 /**
  * Resolve which coding-harness agent a terminal tab is running, for its tab-bar
- * icon. Identity flows through the same already-computed state as the sidebar
- * agent rows — no foreground probing. It is a pane's IDENTITY, kept separate
- * from its activity state: a hook record identifies the pane whether the agent
- * is working or idle. Identity-first precedence:
+ * icon. A pane's IDENTITY (separate from activity state), from the same
+ * already-computed state as the sidebar rows — no foreground probing.
+ * Identity-first precedence:
  *
- * 1. Live focused hook — provider identity from native integrations while the
- *    agent is actively working; ground truth, never overridden by a title.
- * 2. Process identity — the recognized foreground process, read at OSC 133
- *    command boundaries (local panes only); covers agents that emit neither
- *    hooks nor titles, and its shell-foreground mark is title-independent exit
- *    evidence. Re-owned within its title-identity group, so OMP's nested `pi`
- *    child (the `shell → omp → pi` tree) cannot flip the icon back to Pi.
- * 3. Title — only as a reuse override (it names a DIFFERENT-group agent than the
- *    pane's known identity, proving reuse) or as a legacy standalone identity
- *    when the pane has no hook. Within the same title-identity group it carries
- *    no identity (OMP wraps Pi with identical frames), so the record wins.
- * 4. Idle focused identity — the pane's own hook record after the agent went
- *    idle between turns; the durable answer to "which agent is this" once the
- *    live hook, process, and any reuse-title are absent. Suppressed on a local
- *    pane once OSC 133;D proves the agent exited.
+ * 1. Live focused hook — ground truth while the agent works; never title-overridden.
+ * 2. Process identity — recognized foreground process (local only); re-owned within its title-identity group so OMP's nested `pi` (shell → omp → pi) can't flip the icon.
+ * 3. Title — only a reuse override (names a DIFFERENT-group agent) or a legacy standalone identity when the pane has no hook.
+ * 4. Idle focused identity — the pane's own hook record after it went idle; suppressed locally once OSC 133;D proves exit.
  * 5. Sleeping session identity — a hibernated pane's captured session record.
- * 6. launchAgent — what Orca launched here; the bootstrap before any hook, hook
- *    record, or process signal exists, cleared once exit evidence shows it left.
+ * 6. launchAgent — bootstrap before any hook/process signal; cleared once exit evidence shows it left.
  * 7. Sibling-pane identity (live, then idle) — split-tab fallback.
  */
 export function useTabAgent(tab: TerminalTab): TuiAgent | null {
@@ -255,15 +201,12 @@ export function useTabAgent(tab: TerminalTab): TuiAgent | null {
       ? Boolean(s.paneForegroundAgentByPaneKey[focusedPaneKey]?.shellForeground)
       : false
   )
-  // Why: a hibernated pane's persisted session record is pane-scoped evidence of
-  // which agent actually ran here — the freshest identity once the PTY, hook,
-  // and process signals are all gone, and proof a stale launchAgent was reused.
+  // Why: a hibernated pane's session record is the freshest identity once PTY, hook, and process signals are all gone.
   const sleepingSessionAgent = useAppStore((s) =>
     focusedPaneKey ? (s.sleepingAgentSessionsByPaneKey[focusedPaneKey]?.agent ?? null) : null
   )
 
-  // The focused pane's PTY (single-pane tabs have exactly one leaf). Only used
-  // to reset per-process-generation signals when the pane is respawned.
+  // Focused pane's PTY; only used to reset per-process-generation signals on respawn.
   const ptyId = useAppStore((s) => {
     const layout = s.terminalLayoutsByTabId[tab.id]
     const activeLeafId = layout?.activeLeafId
@@ -274,9 +217,7 @@ export function useTabAgent(tab: TerminalTab): TuiAgent | null {
     const ptyIds = s.ptyIdsByTabId[tab.id] ?? []
     return ptyIds.length === 1 ? ptyIds[0]! : null
   })
-  // Why: with no layout to prove which pane a completed row belongs to, only a
-  // single-pane tab may treat it as focused-pane exit evidence — a sibling's
-  // done row must not clear another pane's launch identity.
+  // Why: with no layout to place a completed row, only a single-pane tab may treat it as focused-pane exit evidence.
   const completedHookScopeKnown = useAppStore((s) => {
     const layout = s.terminalLayoutsByTabId[tab.id]
     if (layout?.activeLeafId && isTerminalLeafId(layout.activeLeafId)) {
@@ -301,9 +242,7 @@ export function useTabAgent(tab: TerminalTab): TuiAgent | null {
   const completedHookEvidence = hasCompletedHook && completedHookScopeKnown
 
   useEffect(() => {
-    // Why: reset and re-seed in one effect so a pane respawn both invalidates
-    // the previous generation's signal and immediately re-observes a still-live
-    // hook row instead of leaving the signal stuck false.
+    // Why: reset+re-seed in one effect so a respawn drops the stale-generation signal yet re-observes a still-live hook, not left stuck false.
     const generation = `${ptyId ?? ''}|${String(isRemoteLike)}`
     if (signalGenerationRef.current !== generation) {
       signalGenerationRef.current = generation
@@ -311,14 +250,11 @@ export function useTabAgent(tab: TerminalTab): TuiAgent | null {
       setHasObservedAgentSignal(false)
     }
     const explicitTitleAgent = resolveExplicitTerminalTitleAgentType(tab.title)
-    // Why: for launched panes, only a title naming the launched agent counts as
-    // its activity — other-agent or sibling evidence must not arm exit clearing
-    // for an agent that never produced evidence of its own.
+    // Why: only a title naming the launched agent arms its exit clearing — sibling/other-agent evidence must not.
     const fallbackAgentSignal = tab.launchAgent
       ? explicitTitleAgent === tab.launchAgent
       : Boolean(explicitTitleAgent || siblingHookAgent)
-    // Why: a recognized foreground process is focused-pane ground truth, so it
-    // arms exit clearing even for agents with no hook or title integration.
+    // Why: a recognized foreground process arms exit clearing even for agents with no hook or title integration.
     if (focusedHookAgent || completedHookEvidence || processAgent || fallbackAgentSignal) {
       hasObservedAgentSignalRef.current = true
       setHasObservedAgentSignal(true)
@@ -338,9 +274,7 @@ export function useTabAgent(tab: TerminalTab): TuiAgent | null {
     if (!tab.launchAgent) {
       return
     }
-    // Why: AND the state with the ref — the ref is generation-safe within this
-    // commit (the observe effect above already reset it), while the state can
-    // lag one render behind a pane focus/respawn switch.
+    // Why: AND ref with state — the ref is generation-safe this commit while state can lag one render behind a respawn.
     const launchedAgentExited = resolveLaunchedAgentExitEvidence({
       title: tab.title,
       defaultTitle: tab.defaultTitle,
diff --git a/src/renderer/src/lib/workspace-session.ts b/src/renderer/src/lib/workspace-session.ts
index 23cc4da80e0..461a161af0f 100644
--- a/src/renderer/src/lib/workspace-session.ts
+++ b/src/renderer/src/lib/workspace-session.ts
@@ -16,17 +16,7 @@ import { buildActiveConnectionIdsAtShutdown } from './workspace-session-reconnec
 
 export { buildActiveConnectionIdsAtShutdown }
 
-/** Why (issue #1158): the debounced + shutdown session writers share this
- *  gate so a hydration failure cannot overwrite orca-data.json with the
- *  empty in-memory state the error path leaves behind.
- *
- *  - workspaceSessionReady gates the UI mount; it flips true even in the
- *    error path so users aren't locked out of a crashed session.
- *  - hydrationSucceeded only flips true after a clean load; it stays false
- *    forever if hydration ever threw, which is what keeps the writer a
- *    no-op for the rest of that process lifetime.
- *
- *  Both must be true to persist. */
+/** Why (issue #1158): require both flags so a hydration failure can't overwrite orca-data.json with empty error-path state. */
 export function shouldPersistWorkspaceSession(
   state: Pick<AppState, 'workspaceSessionReady' | 'hydrationSucceeded'>
 ): boolean {
@@ -66,12 +56,7 @@ export type WorkspaceSessionSnapshot = Pick<
   sleepingAgentSessionsByPaneKey?: AppState['sleepingAgentSessionsByPaneKey']
 }
 
-// Why: the App-level Zustand subscriber that debounces session writes uses
-// this list as a shallow-equality gate so it only resets the timer when a
-// field that actually feeds buildWorkspaceSessionPayload changes. Keeping
-// the list co-located with WorkspaceSessionSnapshot means a future field
-// added to the snapshot type fails the _exhaustive check below at compile
-// time, preventing the gate from silently going stale.
+// Why: shallow-equality gate for the debounced session writer; _exhaustive below keeps it in sync with the snapshot type.
 export const SESSION_RELEVANT_FIELDS = [
   'activeRepoId',
   'activeWorkspaceKey',
@@ -130,9 +115,7 @@ export function buildEditorSessionData(
   const editFileIdsByWorktree: Record<string, Set<string>> = {}
   for (const f of editFiles) {
     const arr = byWorktree[f.worktreeId] ?? (byWorktree[f.worktreeId] = [])
-    // Why: read-only tabs never persist a dirty draft even if isDirty is
-    // somehow set — restoring a draft would reintroduce writable/hot-exit state
-    // for an agent-owned transcript.
+    // Why: never persist a dirty draft for a read-only tab — restoring one would reintroduce writable/hot-exit state for an agent transcript.
     const dirtyDraftContent = f.isDirty && f.readOnly !== true ? editorDrafts[f.id] : undefined
     arr.push({
       filePath: f.filePath,
@@ -141,14 +124,11 @@ export function buildEditorSessionData(
       language: f.language,
       isPreview: f.isPreview || undefined,
       runtimeEnvironmentId: f.runtimeEnvironmentId,
-      // Why: persist read-only only when true so pre-existing writable sessions
-      // stay writable on restore (absence is the writable default).
+      // Why: persist readOnly only when true; absence is the writable default on restore.
       ...(f.readOnly === true ? { readOnly: true } : {}),
       ...(f.readOnly === true && f.liveTail === true ? { liveTail: true } : {}),
       ...(dirtyDraftContent !== undefined ? { dirtyDraftContent } : {}),
-      // Why: the edit baseline travels with the dirty draft so a restore can
-      // re-derive a changed-on-disk conflict before autosave may overwrite an
-      // agent write that landed while the app was closed.
+      // Why: baseline travels with the draft so restore can detect a changed-on-disk conflict before autosave clobbers an offline agent write.
       ...(dirtyDraftContent !== undefined && f.lastKnownDiskSignature
         ? { lastKnownDiskSignature: f.lastKnownDiskSignature }
         : {})
@@ -178,10 +158,7 @@ export function buildEditorSessionData(
       activeTabTypeEntries.push([worktreeId, tabType])
       continue
     }
-    // Why: restart only restores edit-mode files. Persisting "editor" with a
-    // transient diff/conflict file ID creates a session payload that cannot be
-    // satisfied on startup and leaves the UI with no real editor tab to select.
-    // Only keep the editor marker when it points at a restored file.
+    // Why: only keep the "editor" marker when it points at a restored file, else startup has no real editor tab to select.
     if (persistedActiveFileIdByWorktree[worktreeId]) {
       activeTabTypeEntries.push([worktreeId, tabType])
     }
@@ -191,8 +168,7 @@ export function buildEditorSessionData(
     WorkspaceVisibleTabType
   >
   const allEditFileIds = new Set(Object.values(editFileIdsByWorktree).flatMap((ids) => [...ids]))
-  // Why: preserve the actual value so per-file hide overrides survive restart;
-  // the map only ever carries `false` entries (visible is the default).
+  // Why: preserve the value so per-file hide overrides survive restart (map only carries `false`; visible is the default).
   const persistedMarkdownFrontmatterVisible = Object.fromEntries(
     Object.entries(markdownFrontmatterVisible ?? {}).filter(([fileId]) =>
       allEditFileIds.has(fileId)
@@ -216,9 +192,7 @@ export function buildBrowserSessionData(
   'browserTabsByWorktree' | 'browserPagesByWorkspace' | 'activeBrowserTabIdByWorktree'
 > {
   return {
-    // Why: browser tabs persist only lightweight chrome state. Live guest
-    // webContents are recreated on restore, so loading is reset to false and
-    // transient errors are preserved only as last-known tab metadata.
+    // Why: guest webContents are recreated on restore, so persist only lightweight chrome state (loading reset to false).
     browserTabsByWorktree: buildPersistedBrowserTabsByWorktree(browserTabsByWorktree),
     browserPagesByWorkspace: buildPersistedBrowserPagesByWorkspace(browserPagesByWorkspace),
     activeBrowserTabIdByWorktree
@@ -250,15 +224,7 @@ export function buildPersistedBrowserPagesByWorkspace(
 export function buildSanitizedTabsByWorktree(
   tabsByWorktree: WorkspaceSessionSnapshot['tabsByWorktree']
 ): WorkspaceSessionState['tabsByWorktree'] {
-  // Why: pendingActivationSpawn is documented on TerminalTab as a transient
-  // renderer-only handoff between setActiveWorktree and the next updateTabPtyId
-  // — it must never be persisted. The main-process session:set handler writes
-  // the payload to disk without re-parsing it against the Zod schema, so if
-  // the flag were ever set and not consumed before a save (e.g. app quits
-  // mid-handoff), it would round-trip to disk and the next session would
-  // start with a stale suppression flag that drops the first legitimate PTY
-  // spawn from the sidebar's recency sort. Strip it here to enforce the
-  // type-level invariant at the persistence boundary.
+  // Why: strip transient pendingActivationSpawn — session:set persists without Zod re-parse, so a stale flag would drop the first PTY spawn on restart.
   return Object.fromEntries(
     Object.entries(tabsByWorktree).map(([worktreeId, tabs]) => [
       worktreeId,
@@ -276,17 +242,11 @@ export function buildTerminalSessionData(
 ): Pick<WorkspaceSessionState, 'activeWorktreeIdsOnShutdown' | 'remoteSessionIdsByTabId'> {
   const tabsByWorktree = snapshot.tabsByWorktree
 
-  // Why: ptyIdsByTabId is the live-PTY map. tab.ptyId is only a wake hint that
-  // sleep intentionally preserves, so using it as liveness would revive slept
-  // worktrees as active after restart.
+  // Why: use ptyIdsByTabId (live PTYs), not tab.ptyId, which sleep preserves as a wake hint and would revive slept worktrees as active.
   const ptyIdsByTabId = snapshot.ptyIdsByTabId
   const hasLivePty = (tabId: string): boolean => (ptyIdsByTabId[tabId]?.length ?? 0) > 0
 
-  // Why: lastKnownRelayPtyIdByTabId preserves remote session IDs across relay
-  // disconnect/reconnect cycles, where clearTabPtyId(null) clears tab.ptyId
-  // but keeps the relay PTY alive. Sleep is different: it preserves tab.ptyId
-  // as a wake hint after clearing ptyIdsByTabId, so that shape must not count
-  // as active on restart.
+  // Why: relay reconnect keeps lastKnown but clears tab.ptyId; the !tab.ptyId guard excludes slept tabs (which keep ptyId as a wake hint).
   const lastKnown = snapshot.lastKnownRelayPtyIdByTabId
   const hasReconnectableSession = (tab: { id: string; ptyId: string | null }): boolean =>
     hasLivePty(tab.id) || (!tab.ptyId && Boolean(lastKnown[tab.id]))
@@ -302,13 +262,8 @@ export function buildTerminalSessionData(
   )
   const repoById = new Map(snapshot.repos.map((repo) => [repo.id, repo]))
 
-  // Why: the renderer already has tab.ptyId for every terminal tab and knows
-  // which worktrees are SSH-backed via repo.connectionId. Deriving the map
-  // here avoids a sync IPC round-trip during beforeunload, which is fragile
-  // (can be dropped by Chromium under shutdown time pressure).
-  // Why: this builder runs from the session-write debounce and beforeunload.
-  // Pre-index repo/worktree identity once so large workspaces don't rescan all
-  // repos/worktrees for every terminal tab while the renderer is trying to quit.
+  // Why: derive here to avoid a fragile sync IPC round-trip during beforeunload (Chromium can drop it under shutdown pressure).
+  // Why: pre-indexed above so large workspaces don't rescan every repo/worktree per terminal tab while the renderer is quitting.
   const remoteSessionIdsByTabId: Record<string, string> = {}
   for (const [worktreeId, tabs] of Object.entries(tabsByWorktree)) {
     const worktree = worktreeById.get(worktreeId)
@@ -346,9 +301,7 @@ export function buildWorkspaceSessionPayload(
     activeTabId: snapshot.activeTabId,
     tabsByWorktree: buildSanitizedTabsByWorktree(snapshot.tabsByWorktree),
     terminalLayoutsByTabId: snapshot.terminalLayoutsByTabId,
-    // Why: session:set fully replaces the persisted object, so every write path
-    // must carry forward which worktrees still had live PTYs. Dropping this
-    // field silently disables eager terminal reconnect on the next restart.
+    // Why: session:set fully replaces the persisted object, so dropping this silently disables eager terminal reconnect on restart.
     activeWorktreeIdsOnShutdown: terminalSessionData.activeWorktreeIdsOnShutdown,
     activeTabIdByWorktree: snapshot.activeTabIdByWorktree,
     ...buildEditorSessionData(
@@ -363,23 +316,16 @@ export function buildWorkspaceSessionPayload(
       snapshot.browserPagesByWorkspace,
       snapshot.activeBrowserTabIdByWorktree
     ),
-    // Why: browser history is user-lifetime state. Enforce the storage cap at
-    // the payload boundary so stale renderer state cannot make every session
-    // write stringify an oversized legacy history array.
+    // Why: enforce the history storage cap here so stale renderer state can't make every write stringify an oversized legacy array.
     browserUrlHistory: normalizeBrowserHistoryEntries(snapshot.browserUrlHistory),
-    // Why: split creation and tab creation are separate renderer updates.
-    // Persist only layouts backed by real tabs so a reload cannot restore a
-    // blank split pane from that transient midpoint.
+    // Why: persist only layouts backed by real tabs so a reload can't restore a blank split pane from the split-before-tab midpoint.
     ...buildPersistedUnifiedTabSessionData(snapshot),
     activeConnectionIdsAtShutdown: buildActiveConnectionIdsAtShutdown(
       snapshot,
       terminalSessionData.remoteSessionIdsByTabId ?? null
     ),
     remoteSessionIdsByTabId: terminalSessionData.remoteSessionIdsByTabId,
-    // Why: per-worktree focus-recency for Cmd+J's empty-query ordering.
-    // Omit when empty so sessions written by builds that never stamped
-    // anything don't bloat the payload. See
-    // docs/cmd-j-empty-query-ordering.md.
+    // Why: omit when empty so builds that never stamped focus-recency don't bloat the payload. See docs/cmd-j-empty-query-ordering.md.
     lastVisitedAtByWorktreeId: buildLastVisitedAtByWorktreeId(snapshot),
     defaultTerminalTabsAppliedByWorktreeId:
       snapshot.defaultTerminalTabsAppliedByWorktreeId &&
diff --git a/src/renderer/src/lib/worktree-activation.ts b/src/renderer/src/lib/worktree-activation.ts
index 5c5ad3bde39..f1779144513 100644
--- a/src/renderer/src/lib/worktree-activation.ts
+++ b/src/renderer/src/lib/worktree-activation.ts
@@ -69,9 +69,8 @@ import { seedNativeChatAppliedSessionOptions } from '@/components/native-chat/na
 import { resolveNativeChatSessionOptionDefaults } from '../../../shared/native-chat-session-option-defaults'
 import type { SessionOptionValue } from '../../../shared/native-chat-session-options'
 
-/** Telemetry payload threaded from the launch site to `pty:spawn`. Main
- *  fires `agent_started` only after the spawn succeeds — see
- *  telemetry-plan.md§Agent launch semantics. */
+/** Telemetry threaded from the launch site to `pty:spawn`; main fires `agent_started`
+ *  only after the spawn succeeds. See telemetry-plan.md§Agent launch semantics. */
 export type AgentStartedTelemetry = EventProps<'agent_started'>
 
 /** Startup command threaded onto a worktree's first terminal at activation. */
@@ -89,11 +88,7 @@ export type WorktreeStartupPayload = {
   telemetry?: AgentStartedTelemetry
 }
 
-// Why: issue commands can originate from two sources with different shapes —
-// (1) a repo-level runner script generated by main (WorktreeSetupLaunch), or
-// (2) a user-typed command template substituted in the TaskPage flow.
-// We accept either so callers don't need to synthesize a runner script file
-// just to queue a direct command string.
+// Why: accept either a main-generated runner script or a plain TaskPage command string, so callers needn't synthesize a runner file.
 export type IssueCommandLaunch =
   | WorktreeSetupLaunch
   | { command: string; env?: Record<string, string> }
@@ -150,22 +145,13 @@ type WorktreeActivationStore = Partial<WorktreeRuntimeOwnerState> & {
 }
 
 /**
- * Shared activation sequence used by the worktree palette, AddRepoDialog,
- * and AddWorktreeDialog. Covers: cross-repo `activeRepoId` switch,
- * `activeView` back to terminal, `setActiveWorktree`, initial terminal
- * creation, sidebar filter clearing, and sidebar reveal.
- *
- * The caller only passes `worktreeId`; the helper derives `repoId`
- * internally via `findWorktreeById`. Returns early without side effects
- * if the worktree is not found (e.g. deleted between palette open and select).
+ * Shared activation sequence used by the worktree palette and add-repo/worktree dialogs.
+ * The caller passes only `worktreeId`; the helper derives `repoId` and returns early
+ * without side effects if the worktree is not found (deleted between palette open and select).
  */
 export type ActivateAndRevealResult = {
-  /** Id of the primary terminal tab seeded with `opts.startup`, when one was
-   *  created during this activation call. Callers that want to target the
-   *  exact pane the startup command ran in (e.g. to await agent readiness
-   *  and paste follow-up text) should use this rather than peeking at
-   *  `activeTabIdByWorktree`, which may point at another tab if setup or
-   *  issue-command scripts opened their own. */
+  /** Id of the primary terminal tab seeded with `opts.startup`, or null. Prefer this over
+   *  `activeTabIdByWorktree`, which may point at another tab if setup/issue scripts opened their own. */
   primaryTabId: string | null
 }
 
@@ -313,8 +299,7 @@ export function activateAndRevealWorktree(
   const hasActivationWork = Boolean(
     opts?.startup || opts?.setup || opts?.defaultTabs || opts?.issueCommand
   )
-  // Why: a plain reselect of the already-visible workspace should still reveal
-  // the sidebar row, but it must not restamp focus recency and wake persistence.
+  // Why: a plain reselect should still reveal the sidebar row but must not restamp focus recency or wake persistence.
   const isPlainAlreadyActiveTerminal =
     !hasActivationWork &&
     state.activeRepoId === wt.repoId &&
@@ -331,15 +316,12 @@ export function activateAndRevealWorktree(
     state.setActiveView('terminal')
   }
 
-  // 3. Core activation: sets activeWorktreeId, restores per-worktree state,
-  // clears unread, bumps dead PTY generations, triggers GitHub refresh
+  // 3. Core activation: setActiveWorktree also restores per-worktree state, clears unread, bumps dead PTY generations, refreshes GitHub
   state.setActiveWorktree(worktreeId)
   const postActivationState = useAppStore.getState()
   const ownerRuntimeEnvironmentId = getRuntimeEnvironmentIdForWorktree(postActivationState, wt.id)
   if (opts?.notifyHostRuntime !== false && isWebRuntimeSessionActive(ownerRuntimeEnvironmentId)) {
-    // Why: paired web clients own only local selection state. The desktop host
-    // should publish session surfaces for the phone without treating that as a
-    // desktop navigation command.
+    // Why: paired web clients own only local selection, so the desktop host publishes session surfaces without treating it as a nav command.
     void activateWebRuntimeSessionWorktree({
       worktreeId,
       environmentId: ownerRuntimeEnvironmentId,
@@ -347,28 +329,17 @@ export function activateAndRevealWorktree(
     })
   }
 
-  // Why: record focus recency for Cmd+J's empty-query ordering BEFORE any
-  // later async step (initial terminal / reveal) could throw — the user
-  // already perceives the switch as successful the instant activeWorktreeId
-  // flips, so the recency stamp must land with the same guarantee. Separate
-  // from recordWorktreeVisit (nav-history) and from worktree.lastActivityAt
-  // (background signal) on purpose — see docs/cmd-j-empty-query-ordering.md.
+  // Why: focus recency for Cmd+J ordering, distinct from recordWorktreeVisit/lastActivityAt; stamp before any later async step could throw. See docs/cmd-j-empty-query-ordering.md.
   if (!isPlainAlreadyActiveTerminal) {
     state.markWorktreeVisited(worktreeId)
   }
 
-  // Why: activateAndRevealWorktree always ends in 'terminal' view (step 2),
-  // and Settings/Tasks transitions do not pass through this function, so no
-  // view-guard is needed here. The guard skips re-recording when the caller
-  // is goBackWorktree/goForwardWorktree, which mutate the history index
-  // directly instead of treating the target as a new visit.
+  // Why: skip re-recording for goBack/goForward history navigation — it moves the index instead of visiting anew (isNavigatingHistory).
   if (!isPlainAlreadyActiveTerminal && !state.isNavigatingHistory) {
     state.recordWorktreeVisit(worktreeId)
   }
 
-  // Why: sleeping an agent destroys the local PTY but preserves the provider
-  // session id. Waking the workspace should restore those CLI sessions without
-  // making the user click a separate sidebar row.
+  // Why: sleeping destroys the local PTY but preserves the provider session id, so waking should restore those CLI sessions automatically.
   resumeSleepingAgentSessionsForWorktree(worktreeId)
 
   // 4. Ensure a focusable surface exists for externally-created worktrees
@@ -384,10 +355,7 @@ export function activateAndRevealWorktree(
     useAppStore.getState().queueTabInitialCwd(primaryTabId, opts.initialCwd)
   }
 
-  // 5. Clear sidebar filters that would hide the target worktree
-  // Why: revealWorktreeInSidebar relies on the worktree card being rendered
-  // in the sidebar. If sidebar filters exclude the target, the card is never
-  // rendered and the reveal silently no-ops.
+  // 5. Clear sidebar filters hiding the target — reveal needs the card rendered, else it silently no-ops.
   if (state.filterRepoIds.length > 0 && !state.filterRepoIds.includes(wt.repoId)) {
     state.setFilterRepoIds([])
   }
@@ -433,8 +401,7 @@ export function ensureWebRuntimeWorktreeTerminalAfterWake(worktreeId: string): v
 
   const hasMirroredHostTabs = tabs.some((tab) => isWebTerminalSurfaceTabId(tab.id))
   if (hasMirroredHostTabs) {
-    // Why: the host session still owns these tabs — wait for the mirror to
-    // repopulate PTY handles instead of creating a duplicate terminal.
+    // Why: the host session still owns these tabs — wait for the mirror to repopulate PTY handles instead of duplicating a terminal.
     return
   }
 
@@ -451,8 +418,7 @@ export function ensureWebRuntimeWorktreeTerminalAfterWake(worktreeId: string): v
     return
   }
 
-  // Why: sleep keeps local tab rows but terminal.stop clears host PTYs, so
-  // activation alone can leave a woke workspace with tab chrome but no surface.
+  // Why: sleep keeps tab rows but terminal.stop clears host PTYs, so a woke workspace can have tab chrome but no surface.
   void createWebRuntimeSessionTerminal({
     worktreeId,
     environmentId: runtimeEnvironmentId,
@@ -473,9 +439,7 @@ export function ensureWorktreeHasInitialTerminal(
   opts?: { activateCreatedTabs?: boolean }
 ): string | null {
   const { renderableTabCount } = store.reconcileWorktreeTabModel(worktreeId)
-  // Why: activation can now restore editor- or browser-only worktrees from the
-  // reconciled tab-group model. Creating a terminal just because the legacy
-  // terminal slice is empty would reopen worktrees with an unexpected extra tab.
+  // Why: creating a terminal just because the legacy terminal slice is empty gives editor/browser-only worktrees an unexpected extra tab.
   const ownerState =
     store.settings !== undefined || store.repos !== undefined || store.worktreesByRepo !== undefined
       ? store
@@ -501,9 +465,7 @@ export function ensureWorktreeHasInitialTerminal(
     wrappedSetupCommandStr = sequenced.setupCommand
   }
 
-  // Why: remote web clients mirror the runtime server's session tabs. A local
-  // activation fallback can spawn a second host terminal before the mirror lands,
-  // but returned setup fallbacks still need to run on an already mirrored tab.
+  // Why: web clients mirror the server's session tabs, so avoid spawning a duplicate host terminal before the mirror lands.
   if (isWebRuntimeSessionActive(getRuntimeEnvironmentIdForWorktree(ownerState, worktreeId))) {
     const existingTerminalTabId = store.tabsByWorktree[worktreeId]?.[0]?.id
     if (existingTerminalTabId && (setup || issueCommand)) {
@@ -519,9 +481,7 @@ export function ensureWorktreeHasInitialTerminal(
       return existingTerminalTabId
     }
     if (setup || issueCommand) {
-      // Why: runtime-owned worktrees mirror their session tabs asynchronously,
-      // so right after create there is usually no tab yet. Hold the commands
-      // for the first mirrored tab instead of silently dropping them.
+      // Why: runtime-owned worktrees mirror session tabs async, so hold commands for the first mirrored tab instead of dropping them.
       queueHookCommandsForFirstWorktreeTab({
         worktreeId,
         deliver: (state, firstTerminalTabId) =>
@@ -542,8 +502,7 @@ export function ensureWorktreeHasInitialTerminal(
   if (!shouldAutoCreateInitialTerminal(renderableTabCount)) {
     const existingTerminalTabId = store.tabsByWorktree[worktreeId]?.[0]?.id
     if (existingTerminalTabId && (setup || issueCommand)) {
-      // Why: main may have already adopted the startup tab but failed to spawn
-      // setup; renderer activation must still launch the returned fallback setup.
+      // Why: main may have adopted the startup tab but failed to spawn setup; renderer must still launch the returned fallback setup.
       queueSetupAndIssueCommands(
         store,
         worktreeId,
@@ -572,15 +531,8 @@ export function ensureWorktreeHasInitialTerminal(
     return templatedTabId
   }
 
-  // Why: this tab only exists because the user clicked/activated a worktree
-  // that had no focusable surface yet. Tag it so the resulting PTY spawn
-  // does not count as activity and reshuffle the Recent sort. Explicit
-  // "New Tab" actions (handleNewTab in Terminal.tsx) do not set the flag.
-  //
-  // Why: the initial terminal can be seeded with a coding agent (new-workspace
-  // flow, or reopening an empty worktree created with an agent). Stamp that on
-  // the tab before hooks arrive so native chat and provider chrome can resolve
-  // the agent immediately; sequenced setup keeps the same launch metadata.
+  // Why: tag this activation-created tab so its PTY spawn doesn't count as activity and reshuffle the Recent sort.
+  // Why: stamp the seeded agent before hooks arrive so native chat and provider chrome can resolve it immediately.
   const launchAgent =
     sequencedStartup?.launchAgent ??
     (sequencedStartup?.telemetry
@@ -606,10 +558,7 @@ export function ensureWorktreeHasInitialTerminal(
     store.setActiveTab(terminalTab.id)
   }
 
-  // Why: the new-workspace flow can seed the first terminal with a selected
-  // coding agent and user prompt. Queue that startup command on the initial
-  // pane so the main terminal begins in the requested agent session instead of
-  // opening to an idle shell and forcing the user to repeat the same prompt.
+  // Why: queue the seeded startup on the initial pane so the terminal begins in the requested agent session instead of an idle shell.
   if (sequencedStartup) {
     if (launchAgent) {
       seedNativeChatAppliedSessionOptions(
@@ -730,11 +679,7 @@ function queueSetupAndIssueCommands(
   wrappedSetupCommandStr: string | undefined,
   opts: { activateCreatedTabs?: boolean } | undefined
 ): void {
-  // Why: the setup script launch location is user-configurable. The default
-  // 'new-tab' creates a separate background tab titled "Setup" without
-  // stealing focus from the main terminal, so setup output never crowds the
-  // primary pane; 'split-vertical' and 'split-horizontal' keep the setup
-  // output adjacent to the main terminal via a split.
+  // Why: setup launch location is user-configurable — 'new-tab' keeps setup output off the primary pane; splits keep it adjacent.
   if (setup) {
     const mode = useAppStore.getState().settings?.setupScriptLaunchMode ?? 'new-tab'
     const setupCommand = {
@@ -747,15 +692,11 @@ function queueSetupAndIssueCommands(
         recordInteraction: false,
         ...(opts?.activateCreatedTabs === false ? { activate: false } : {})
       })
-      // Why: createTab auto-activates the new tab. Revert activation so the
-      // user's focus stays on the primary terminal — per the design, the
-      // Setup tab runs unattended in the background.
+      // Why: createTab auto-activates the new tab; revert so focus stays on the primary terminal while Setup runs in the background.
       if (opts?.activateCreatedTabs !== false) {
         store.setActiveTab(terminalTabId)
       }
-      // Why: customTitle wins over the auto-generated "Terminal N" label
-      // everywhere the tab is rendered (tab bar, switcher, session snapshots),
-      // so labeling via customTitle is the single authoritative source.
+      // Why: customTitle overrides the auto "Terminal N" label everywhere the tab renders, so it's the authoritative label source.
       store.setTabCustomTitle(setupTab.id, 'Setup', { recordInteraction: false })
       store.queueTabStartupCommand(setupTab.id, setupCommand)
     } else {
@@ -766,15 +707,9 @@ function queueSetupAndIssueCommands(
     }
   }
 
-  // Why: when the user links a GitHub issue and opts into that repo's
-  // per-user issue automation, spawn a separate split pane to run the
-  // agent command. Queued independently from setup so both can start in
-  // parallel; repo bootstrap and personal issue workflows are separate
-  // concerns, so Orca should not invent a dependency between them.
+  // Why: issue automation runs in its own split, queued independently from setup so both can start in parallel (separate concerns).
   if (issueCommand) {
-    // Why: WorktreeSetupLaunch carries a runner-script file (from main) and we
-    // shell out to bash; the TaskPage variant is already an expanded command
-    // string, so pass it through directly.
+    // Why: WorktreeSetupLaunch carries a runner-script file to shell out to; the TaskPage variant is already an expanded command string.
     const queuedIssueCommand =
       'runnerScriptPath' in issueCommand
         ? {
@@ -786,10 +721,7 @@ function queueSetupAndIssueCommands(
   }
 }
 
-// Why: break the import cycle — the nav-history slice must activate workspace
-// entries from goBack/goForward, but it lives under @/store, which activation
-// already imports from. Registering here keeps folder workspace replay on the
-// same path as direct folder activation.
+// Why: break the import cycle — nav-history slice (under @/store) can't import activation directly, so register the activator here.
 setWorktreeNavActivator((workspaceId) => {
   const workspaceScope = parseWorkspaceKey(workspaceId)
   if (workspaceScope?.type === 'folder') {
@@ -798,9 +730,7 @@ setWorktreeNavActivator((workspaceId) => {
   return activateAndRevealWorktree(workspaceId)
 })
 
-// Why: page entries in nav history replay through setActiveView(...)
-// (not open*Page) so back/forward does not mutate previousViewBefore* or
-// append duplicate history. See navigateToIndex for the replay branch.
+// Why: page entries replay via setActiveView (not open*Page) so back/forward doesn't mutate previousViewBefore* or duplicate history (see navigateToIndex).
 setWorktreeNavViewActivator((entry) => {
   if (entry === 'automations') {
     useAppStore.getState().setActiveView(entry)
diff --git a/src/renderer/src/lib/worktree-status.ts b/src/renderer/src/lib/worktree-status.ts
index 90136246169..902e3cb2257 100644
--- a/src/renderer/src/lib/worktree-status.ts
+++ b/src/renderer/src/lib/worktree-status.ts
@@ -33,22 +33,10 @@ export function getWorktreeStatus(
   runtimePaneTitlesByTabId: Record<string, Record<number, string>> = {},
   options: WorktreeStatusHeuristicOptions = {}
 ): WorktreeStatus {
-  // Why: liveness gates every promotion. tab.ptyId is the wake-hint sessionId
-  // preserved across sleep (so wake can reattach to the same daemon history
-  // dir / relay session) — it is *not* a liveness signal. ptyIdsByTabId is the
-  // source of truth: sleep clears it to []; pty.spawn writes it; pty.kill
-  // clears it. Reading the live-pty map keeps the dot honest after sleep,
-  // crash, or any path where the wake-hint outlives the actual PTY.
+  // Why: tab.ptyId is a wake-hint that survives sleep, not a liveness signal; gate on ptyIdsByTabId, which sleep/kill clear when the PTY dies.
   const liveTabs = tabs.filter((tab) => tabHasLivePty(ptyIdsByTabId, tab.id))
 
-  // Why: a split-pane tab can host multiple concurrent agents, but `tab.title`
-  // only reflects the most-recently-focused pane (see onActivePaneChange in
-  // use-terminal-pane-lifecycle.ts). Reading just `tab.title` causes the
-  // sidebar spinner to follow the focused pane instead of the aggregate tab
-  // state — e.g. clicking an idle Claude pane while Codex is still working in
-  // another pane would collapse the spinner to solid green. Consult per-pane
-  // titles first (same pattern as countWorkingAgentsForTab) and only fall back
-  // to `tab.title` for tabs that have no mounted panes yet.
+  // Why: tab.title tracks only the most-recently-focused pane (onActivePaneChange in use-terminal-pane-lifecycle.ts); consult per-pane titles so the spinner reflects aggregate tab state.
   const hasStatus = (status: 'permission' | 'working'): boolean =>
     liveTabs.some((tab) => tabHasStatus(tab, runtimePaneTitlesByTabId, status, options))
 
@@ -59,8 +47,7 @@ export function getWorktreeStatus(
     return 'working'
   }
   if (liveTabs.length > 0 || browserTabs.length > 0) {
-    // Why: browser-only worktrees are still active from the user's point of
-    // view even when they have no PTY-backed terminal.
+    // Why: browser-only worktrees (no PTY) are still active from the user's point of view.
     return 'active'
   }
   return 'inactive'
@@ -80,9 +67,7 @@ function tabHasStatus(
     const paneTitleEntries = Object.entries(paneTitles)
     for (const [runtimePaneId, title] of paneTitleEntries) {
       const leafId = resolveRuntimePaneTitleLeafIdFromRoot(tabLayoutRoot, runtimePaneId)
-      // Why: runtime titles can arrive before layout hydration in SSH/replay
-      // paths. With exactly one title and one authoritative agent row, the tab
-      // is unambiguous enough to prefer that row over a stale spinner.
+      // Why: runtime titles can precede layout hydration (SSH/replay); with one title and one agent row, prefer that row over a stale spinner.
       const hasSingleUnmappedAgentStatusPane =
         leafId === null && agentStatusPaneIds?.size === 1 && paneTitleEntries.length === 1
       if (
@@ -98,21 +83,14 @@ function tabHasStatus(
     }
     return false
   }
-  // Why: a tab-level title does not identify which split pane it came from.
-  // Once any visible agent row owns a pane in that tab, prefer the row state
-  // to avoid resurrecting stale "working" titles for a completed pane.
+  // Why: a tab title can't identify its pane; once an agent row owns one, prefer the row over a completed pane's stale "working" title.
   if (agentStatusPaneIds && agentStatusPaneIds.size > 0) {
     return false
   }
   return classifyTitleActivity(tab.title) === status && titleStatusIsAgentAttributable(tab.title)
 }
 
-// Why: the title heuristic is only a fallback — hook-managed agents promote the
-// worktree via hasLiveWorking/hasPermission in resolveWorktreeStatus, not here.
-// A bare braille-spinner title (e.g. an exited agent's never-cleared "⠐ task"
-// frame) classifies as working yet produces no sidebar agent row, spinning the
-// worktree forever with "0 agents". Require the same agent attribution the row
-// builder uses, so a title only spins the dot when it would also show a row.
+// Why: require agent attribution so a bare never-cleared spinner title can't spin the dot "0 agents" forever with no matching sidebar row.
 function titleStatusIsAgentAttributable(title: string): boolean {
   return resolveAgentTypeFromTerminalTitle(title) !== null
 }
@@ -123,27 +101,12 @@ export function getWorktreeStatusLabel(status: WorktreeStatus): string {
 
 /**
  * Apply the WorktreeCard priority overlay (permission > working > done >
- * heuristic) on top of the title-heuristic base. Live PTY liveness still gates
- * title-derived working/permission, but explicit agent rows are allowed to
- * promote the dot: if the sidebar shows a running/completed/blocking inline
- * agent row, the worktree status must agree with that visible row. Sleep
- * cleanup owns removing stale retained rows; once they are gone, no promotion
- * occurs.
+ * heuristic) on top of the title-heuristic base. Explicit agent rows may
+ * promote the dot; sleep cleanup owns removing stale retained rows.
  *
- * Argument semantics (sourced by the WorktreeCard caller from the store):
- * - `tabs`, `browserTabs`: the worktree's terminal and browser tabs.
- * - `ptyIdsByTabId`: live-PTY map narrowed to this worktree (the liveness
- *   gate; see tabHasLivePty).
- * - `runtimePaneTitlesByTabId`: per-tab pane title map narrowed to this
- *   worktree (used by the title-heuristic for split-pane spinners).
- * - `hasPermission`: any fresh hook entry in {blocked, waiting} for a tab in
- *   this worktree.
- * - `hasLiveWorking`: any fresh hook entry in {working} for a tab in this
- *   worktree.
- * - `hasLiveDone`: any fresh hook entry in {done} for a tab in this worktree.
- * - `hasRetainedDone`: any retained-agent snapshot scoped to this worktreeId.
- * - `agentStatusPaneIdsByTabId`: stable leaf ids and legacy runtime pane ids
- *   whose visible agent rows should override title-derived heuristics.
+ * Map args are narrowed to this worktree. `hasPermission`/`hasLiveWorking`/
+ * `hasLiveDone` are fresh hook entries ({blocked,waiting} / {working} / {done});
+ * `hasRetainedDone` is a retained-agent snapshot scoped to this worktreeId.
  */
 export function resolveWorktreeStatus(args: {
   tabs: readonly Pick<TerminalTab, 'id' | 'title'>[]
@@ -172,17 +135,11 @@ export function resolveWorktreeStatus(args: {
   if (args.hasPermission) {
     return 'permission'
   }
-  // Why: heuristic 'permission' must outrank heuristic 'working' (a tab can
-  // be "working" while another pane in the same tab is blocked on permission;
-  // the user-actionable signal wins). Both this branch and the args.hasPermission
-  // branch above return 'permission' — they're separated only because
-  // args.hasPermission must also outrank heuristic 'working' below.
+  // Why: heuristic 'permission' outranks heuristic 'working' — the user-actionable signal wins when panes in one tab disagree.
   if (heuristic === 'permission') {
     return 'permission'
   }
-  // Why: restored-but-unfocused cards may have the startup hook snapshot before
-  // their terminal pane mounts and repopulates runtimePaneTitlesByTabId.
-  // Trust the fresh explicit working row so those cards stay yellow on restart.
+  // Why: restored cards get the hook snapshot before panes mount; trust the explicit working row so they stay yellow on restart.
   if (args.hasLiveWorking || heuristic === 'working') {
     return 'working'
   }
diff --git a/src/renderer/src/runtime/sync-runtime-graph.ts b/src/renderer/src/runtime/sync-runtime-graph.ts
index fb32a847941..4a4e12fddc5 100644
--- a/src/renderer/src/runtime/sync-runtime-graph.ts
+++ b/src/renderer/src/runtime/sync-runtime-graph.ts
@@ -70,11 +70,7 @@ type TabsProjectionCache = {
 }
 
 const registeredTabs = new Map<string, RegisteredTerminalTab>()
-// Why: track when each tab was registered so we can suppress the "no live
-// transport" warning during the initial PTY connection window. The warning
-// is noise when it fires on mount (PTY spawn/attach is async and hasn't
-// finished yet), but valuable if the transport is still missing after the
-// grace period — that indicates a real stuck state.
+// Why: registration time suppresses the "no live transport" warning during the async PTY-connect window; after the grace period it's a real stuck state.
 const tabRegisteredAt = new Map<string, number>()
 const NO_TRANSPORT_GRACE_MS = 10_000
 const EMPTY_ACTIVE_BROWSER_TAB_ID_BY_WORKTREE: AppState['activeBrowserTabIdByWorktree'] = {}
@@ -112,8 +108,7 @@ export function registerRuntimeTerminalTab(tab: RegisteredTerminalTab): () => vo
   tabRegisteredAt.set(tab.tabId, Date.now())
   scheduleRuntimeGraphSync()
   return () => {
-    // Why: React can mount a replacement surface before the prior effect
-    // cleans up. Stale cleanup must not erase the successor's live registry.
+    // Why: React can mount a replacement surface before the prior effect cleans up; stale cleanup must not erase the successor's registry.
     if (registeredTabs.get(tab.tabId) !== tab) {
       return
     }
@@ -169,9 +164,7 @@ export function scheduleRuntimeGraphSync(): void {
     return
   }
   syncScheduled = true
-  // Why: terminal title/status updates often arrive as separate IPC tasks.
-  // A frame-sized timer collapses that churn into one graph publish without
-  // tying runtime state publication to paint frames or visible-window status.
+  // Why: a frame-sized timer collapses separate title/status IPC tasks into one graph publish without tying publication to paint frames.
   syncTimer = setTimeout(() => {
     syncTimer = null
     syncScheduled = false
@@ -191,22 +184,14 @@ async function runRuntimeGraphSync(): Promise<void> {
     syncInFlight = false
     if (syncPendingAfterFlight) {
       syncPendingAfterFlight = false
-      // Why: syncWindowGraph crosses IPC and can be slower than title/layout
-      // churn. Collapse all updates that arrived during one in-flight sync
-      // into a single trailing graph instead of stacking concurrent IPC calls.
+      // Why: coalesce updates that arrived during one in-flight sync into a single trailing graph instead of stacking concurrent IPC calls.
       scheduleRuntimeGraphSync()
     }
   }
 }
 
 export type RuntimeMobileSessionSyncKey = {
-  // Why: large maps the renderer never reshapes are compared by reference.
-  // Reallocating `terminalLayoutsByTabId` / `runtimePaneTitlesByTabId` is the
-  // signal that some pane layout or pane title actually changed; nothing else
-  // in the store rewrites those references. Comparing references avoids
-  // stringifying potentially thousands of accumulated tab entries on every
-  // `setActivePane` / `updateTabTitle` mutation. See
-  // docs/agent-working-pane-typing-lag.md.
+  // Why: compared by reference; reallocation signals a real layout/title change, avoiding stringifying thousands of tabs. See docs/agent-working-pane-typing-lag.md.
   terminalLayoutsByTabId: AppState['terminalLayoutsByTabId']
   runtimePaneTitlesByTabId: AppState['runtimePaneTitlesByTabId']
   groupsByWorktree: AppState['groupsByWorktree']
@@ -225,10 +210,7 @@ export type RuntimeMobileSessionSyncKey = {
   generatedTabTitlesEnabled: boolean
   systemPrefersDark: boolean | null
   terminalThemeProjection: string
-  // Why: these projections still need value-level inspection because the
-  // underlying references churn even when the mobile-relevant shape is
-  // unchanged (`tabsByWorktree` reallocates on every OSC title frame).
-  // Pre-serialize them once.
+  // Why: underlying refs churn even when the mobile shape is unchanged (tabsByWorktree reallocates per OSC title frame); pre-serialize.
   tabsProjection: string
   openFilesProjection: string
   browserProjection: string
@@ -315,9 +297,7 @@ export function getRuntimeMobileSessionSyncKey(
     activeTabId: state.activeTabId,
     activeBrowserTabIdByWorktree:
       state.activeBrowserTabIdByWorktree ?? EMPTY_ACTIVE_BROWSER_TAB_ID_BY_WORKTREE,
-    // Why: paired web/mobile snapshots include full agentStatus details. The
-    // epoch covers sort/retention/freshness transitions; the projection covers
-    // prompt/tool details without publishing every timestamp-only heartbeat.
+    // Why: epoch covers sort/retention/freshness changes; projection covers prompt/tool details, skipping timestamp-only heartbeats.
     agentStatusEpoch: state.agentStatusEpoch ?? 0,
     agentStatusProjection:
       canReusePrevious && agentStatusByPaneKey === previousAgentStatusByPaneKey
@@ -331,9 +311,7 @@ export function getRuntimeMobileSessionSyncKey(
       previousKey.systemPrefersDark === terminalThemeSystemPrefersDark
         ? previousKey.terminalThemeProjection
         : JSON.stringify(resolveMobileTerminalTheme(state, systemPrefersDark) ?? null),
-    // Why: background agent title ticks can change runtimePaneTitlesByTabId
-    // many times per second while the user types elsewhere. Reuse unchanged
-    // projections so those ticks do not rescan all tabs, files, and drafts.
+    // Why: background title ticks churn many times/sec; reuse unchanged projections so they don't rescan all tabs, files, and drafts.
     tabsProjection:
       canReusePrevious && state.tabsByWorktree === previousState.tabsByWorktree
         ? previousKey.tabsProjection
@@ -356,8 +334,7 @@ export function getRuntimeMobileSessionSyncKey(
 }
 
 function getBrowserTabsByWorktree(state: AppState): AppState['browserTabsByWorktree'] {
-  // Why: some runtime-sync callers and tests construct partial pre-browser
-  // renderer states; treat missing browser slices as no browser tabs.
+  // Why: some callers/tests build partial pre-browser states; treat missing browser slices as no tabs.
   return state.browserTabsByWorktree ?? EMPTY_BROWSER_TABS_BY_WORKTREE
 }
 
@@ -496,8 +473,7 @@ function buildRuntimeMobileAgentStatusProjection(
         })),
         toolName: entry.toolName ?? null,
         toolInput: entry.toolInput ?? null,
-        // Why: include so a newly-captured AskUserQuestion prompt re-fires the
-        // mobile session republish even when no other field changed.
+        // Why: include so a newly-captured AskUserQuestion prompt re-fires the mobile republish even when no other field changed.
         interactivePrompt: entry.interactivePrompt ?? null,
         lastAssistantMessage: entry.lastAssistantMessage ?? null,
         interrupted: entry.interrupted ?? null
@@ -539,15 +515,10 @@ async function syncRuntimeGraph(): Promise<void> {
   if (!syncEnabled || !getStoreState) {
     return
   }
-  // Why: the runtime graph helper cannot import the Zustand store directly
-  // because the terminal slice also imports this module to schedule syncs.
-  // Injecting the getter from App keeps the runtime graph path out of the
-  // store construction cycle and avoids test-time partial initialization.
+  // Why: can't import the store directly (terminal slice imports this module); inject the getter to break the construction cycle.
   const state = getStoreState()
   const systemPrefersDark = getSystemPrefersDark()
-  // Why: sync can run after high-churn terminal/title mutations. Build lookup
-  // maps once per sync instead of flattening every worktree's tabs for each
-  // registered terminal.
+  // Why: build lookup maps once per sync instead of re-flattening every worktree's tabs for each registered terminal.
   const terminalTabById = new Map(
     Object.values(state.tabsByWorktree)
       .flat()
@@ -615,13 +586,7 @@ async function syncRuntimeGraph(): Promise<void> {
     }
   }
 
-  // Why: background automation tabs spawn their agent PTY eagerly and are created
-  // inactive, so they never mount a TerminalPane and never enter `registeredTabs`.
-  // Without this pass their leaf+ptyId is never published, so the runtime treats
-  // the live agent PTY as orphaned (surfaced as a synthetic `pty:<id>` terminal)
-  // and `orca terminal list` / session-reuse can't see the real tab. Publish them
-  // from the persisted layout, gated on a live eager buffer so we only adopt a
-  // still-running unmounted PTY (never a stale saved ptyId).
+  // Why: inactive automation tabs never mount a TerminalPane; publish their leaf+ptyId from persisted layout (gated on a live buffer) or the live PTY looks orphaned.
   for (const [worktreeId, tabs] of Object.entries(state.tabsByWorktree)) {
     for (const tab of tabs) {
       if (registeredTabs.has(tab.id) || isWebOnlyMirroredTerminalTab(state, tab)) {
@@ -685,9 +650,7 @@ export function buildMobileSessionTabSnapshots(
   state: AppState,
   systemPrefersDark = getSystemPrefersDark()
 ): RuntimeMobileSessionTabsSnapshot[] {
-  // Why: mobile publication can run on high-frequency background agent title
-  // ticks. Cache open-file indexes and draft hashes by immutable store-slice
-  // reference so title-only syncs do not rescan or rehash editor state.
+  // Why: high-frequency title ticks fire mobile sync; cache indexes/hashes by store-slice ref to skip rescanning editor state.
   const openFileIndexes = getOpenFileIndexes(state.openFiles)
   const editorDraftVersionByFileId = getEditorDraftVersionByFileId(state.editorDrafts)
   const worktreeIds = new Set<string>([
@@ -788,8 +751,7 @@ export function buildMobileSessionTabSnapshots(
       }
     }
 
-    // Why: split-group projection can miss plain editor files during hydration.
-    // Publish the missing file so paired mobile/web clients still mirror it.
+    // Why: split-group projection can miss plain editor files during hydration; publish them so mobile/web still mirror.
     const fallbackEditorTabs: FallbackEditorTabTarget[] = []
     if (openFilesForWorktree) {
       const unifiedEditorTabs = getEditorUnifiedTabsForWorktree(state, worktreeId)
@@ -876,8 +838,7 @@ export function buildMobileSessionTabSnapshots(
 }
 
 function isEditorSurfaceTab(tab: Pick<Tab, 'contentType'>): boolean {
-  // Why: mobile file snapshots can faithfully mirror ordinary edit/diff files;
-  // conflict review and check-details tabs require metadata this contract lacks.
+  // Why: mobile can mirror ordinary edit/diff files; conflict-review and check-details tabs need metadata this contract lacks.
   return tab.contentType === 'editor' || tab.contentType === 'diff'
 }
 
@@ -1009,10 +970,7 @@ function isWebOnlyMirroredTerminalTab(
   const ptyIds = [tab.ptyId, ...layoutPtyIds].filter(
     (ptyId): ptyId is string => typeof ptyId === 'string' && ptyId.length > 0
   )
-  // Why: web mirror ids are a web-renderer implementation detail. If such an
-  // id has only remote/no PTYs, it is a mirror and must not be published back
-  // as host state. Legacy leaked host tabs with local PTYs still publish so
-  // existing sessions keep desktop/web parity.
+  // Why: only-remote/no-PTY tabs are web mirrors, not host state; legacy local-PTY tabs still publish for desktop/web parity.
   return ptyIds.every(isRemoteRuntimePtyId)
 }
 
@@ -1151,8 +1109,7 @@ function buildMobileSessionGroupProjection(
     }
     const tabOrder = visibleOrder.map((item) => item.tabId ?? item.id)
     const tabOrderSet = new Set(tabOrder)
-    // Why: persisted split groups can contain very large tab orders; append
-    // iteratively so mobile sync does not hit V8's argument-list limit.
+    // Why: persisted split groups can have very large tab orders; append iteratively to avoid V8's argument-list limit.
     for (const item of visibleOrder) {
       order.push(item)
     }
@@ -1259,9 +1216,7 @@ function getRuntimeLeafIdsForTerminal(tabId: string, state: AppState): string[]
     return persistedLeafIds
   }
 
-  // Why: a newly-created terminal tab can be in the store before TerminalPane
-  // mounts. Without a live or persisted UUID leaf, there is no stable mobile
-  // surface to publish yet; fabricating pane:1 would become stale after mount.
+  // Why: a new tab can predate TerminalPane mount; fabricating pane:1 with no live/persisted leaf would go stale after mount.
   return []
 }
 
@@ -1301,9 +1256,7 @@ function buildMobileTerminalSurfaceTabs(
     typeof HTMLElement !== 'undefined' && firstChild instanceof HTMLElement ? firstChild : null
   )
   const parentLayout = normalizeTerminalLayoutSnapshot({
-    // Why: the live DOM tree (when mounted) is authoritative; otherwise the
-    // saved tree. Both carry the real direction — only synthesize as a last
-    // resort, never re-guess. Shared with the client-ingest path.
+    // Why: live DOM tree is authoritative when mounted, else the saved tree; synthesize only as a last resort, never re-guess.
     root: resolveTerminalLayoutRoot({
       authoritativeRoot: liveLayoutRoot,
       existingRoot: sanitizedSavedLayout?.root,
@@ -1466,8 +1419,7 @@ function isMobileUnsupportedCombinedDiffSource(
 }
 
 function isMobilePublishableOpenFile(file: AppState['openFiles'][number]): boolean {
-  // Why: combined diff tabs use display labels as relative paths and require
-  // the desktop combined renderer; mobile would otherwise try files.read.
+  // Why: combined diff tabs use display labels as paths and need the desktop renderer; mobile would mis-call files.read.
   return !isMobileUnsupportedCombinedDiffSource(file.diffSource)
 }
 
@@ -1492,8 +1444,7 @@ function buildMobileBrowserTab(
     loading: activePage?.loading ?? workspace.loading,
     canGoBack: activePage?.canGoBack ?? workspace.canGoBack,
     canGoForward: activePage?.canGoForward ?? workspace.canGoForward,
-    // Why: null means the active page successfully cleared its failure. Falling
-    // back through ?? would resurrect a stale workspace-level error.
+    // Why: null means the active page cleared its failure; ?? would resurrect a stale workspace-level error.
     loadError: activePage ? activePage.loadError : workspace.loadError,
     certificateFailure: activePage
       ? (state.browserCertificateFailuresByPageId?.[activePage.id] ?? null)
diff --git a/src/renderer/src/runtime/web-runtime-session.ts b/src/renderer/src/runtime/web-runtime-session.ts
index 8cfc23eb19c..de8b9603e6b 100644
--- a/src/renderer/src/runtime/web-runtime-session.ts
+++ b/src/renderer/src/runtime/web-runtime-session.ts
@@ -35,8 +35,7 @@ export {
 export function isWebRuntimeSessionActive(
   activeRuntimeEnvironmentId: string | null | undefined
 ): boolean {
-  // Why: headless serve sessions are owned by the remote runtime, regardless
-  // of whether the attaching client is web or desktop Electron.
+  // Why: headless serve sessions are owned by the remote runtime, whether the client is web or desktop Electron.
   return Boolean(activeRuntimeEnvironmentId?.trim())
 }
 
@@ -95,8 +94,7 @@ export async function createWebRuntimeSessionTerminal(args: {
       response as RuntimeRpcResponse<RuntimeMobileSessionCreateTerminalResult>
     )
     if (args.activate !== false) {
-      // Why: record focus intent so the reconcile follows the snapshot's active
-      // tab to THIS new terminal, instead of sticky-keeping the prior tab.
+      // Why: record focus intent so the reconcile follows to this new terminal instead of sticky-keeping the prior tab.
       recordWebSessionFocusIntent(args.worktreeId, createdTerminal.tab.id)
     }
     await refreshWebRuntimeSessionTabsSnapshot(environmentId, args.worktreeId)
@@ -139,24 +137,17 @@ export async function createWebRuntimeSessionBrowserTab(args: {
         worktree: toRuntimeWorktreeSelector(args.worktreeId),
         url: args.url,
         profileId: args.profileId ?? undefined,
-        // Why: this is the user clicking "New Browser Tab", so focus it. On a
-        // headless host this marks the tab active in the session snapshot so the
-        // reconcile keeps focus on it instead of snapping back to a terminal.
+        // Why: user clicked "New Browser Tab", so mark it active in the snapshot, else the reconcile snaps back to a terminal.
         activate: true,
-        // Why: place the new browser in the split group whose "+" was clicked,
-        // so the host snapshot is authoritative for its group (no left-snap).
+        // Why: place the new browser in the clicked split group so the host snapshot is authoritative for it (no left-snap).
         ...(args.targetGroupId ? { targetGroupId: args.targetGroupId } : {}),
-        // Why: paired web clients need the local tab immediately. The remote
-        // pane will stream once the host webview registers; waiting here makes
-        // the workspace appear to close while the host finishes mounting.
+        // Why: web clients need the local tab now; waiting for host webview registration makes the workspace appear to close.
         waitForRegistration: false
       },
       timeoutMs: 15_000
     })
     const created = unwrapRuntimeRpcResult(response as RuntimeRpcResponse<BrowserTabCreateResult>)
-    // Why: record focus intent (browser session tab id === browserPageId on a
-    // headless host) so the reconcile follows the snapshot's active tab to this
-    // new browser tab rather than sticky-keeping the prior one.
+    // Why: record focus intent (tab id === browserPageId on a headless host) so the reconcile follows to the new browser tab.
     recordWebSessionFocusIntent(args.worktreeId, created.browserPageId)
     stageWebRuntimeBrowserTab({
       environmentId,
@@ -212,9 +203,7 @@ function stageWebRuntimeBrowserTab(args: {
   }
 
   const url = args.url?.trim() || 'about:blank'
-  // Why: paired web browser tabs are host-owned, but the session snapshot can
-  // arrive after React has already rendered a fallback workspace. Stage the
-  // remote handle immediately so the current worktree stays selected.
+  // Why: the snapshot can arrive after React renders a fallback; stage the handle now so the worktree stays selected.
   const browserTab = useAppStore.getState().createBrowserTab(args.worktreeId, url, {
     title: url === 'about:blank' ? 'New Browser Tab' : url,
     focusAddressBar: true,
@@ -270,14 +259,12 @@ async function refreshWebRuntimeSessionTabsSnapshot(
     const { applyFreshWebSessionTabsSnapshot, applyWebSessionTabsStorePatch } =
       await import('./web-session-tabs-sync')
     applyWebSessionTabsStorePatch((state) => {
-      // Why: eager refreshes can resolve after the user has selected another
-      // worktree; session parity should update tabs without stealing focus.
+      // Why: eager refreshes can resolve after the user switched worktrees; update tabs without stealing focus.
       const patch = applyFreshWebSessionTabsSnapshot(state, snapshot, environmentId)
       return patch === state ? state : patch
     })
   } catch (error) {
-    // Why: browser creation already succeeded on the host. If the eager parity
-    // refresh fails, the long-lived session.tabs subscription can still catch up.
+    // Why: host creation already succeeded; the long-lived session.tabs subscription catches up if this eager refresh fails.
     console.warn(
       '[web-runtime-session] failed to refresh browser tab snapshot:',
       error instanceof Error ? error.message : String(error)
@@ -350,10 +337,7 @@ export async function moveWebRuntimeSessionTab(
   }
 
   if (args.kind === 'reorder') {
-    // Why: record the intended LOCAL order synchronously, before the async host
-    // resolution below, so an in-flight pre-move snapshot carrying the old order
-    // can't snap the tab back. The reconcile applies this until the host echoes
-    // the new order. (tabOrder here is already local unified tab ids.)
+    // Why: record local order synchronously before async host resolution, so a pre-move snapshot can't snap the tab back.
     recordWebSessionReorderIntent(args.worktreeId, args.targetGroupId, args.tabOrder, Date.now())
   }
 
@@ -401,9 +385,7 @@ export async function moveWebRuntimeSessionTab(
         ? {
             ...base,
             kind: 'reorder' as const,
-            // Why: paired web groups can contain local-only tabs alongside
-            // host-mirrored tabs. The host reorder API only accepts host tab
-            // ids, so local ids must be omitted from the mirrored order.
+            // Why: the host reorder API only accepts host tab ids, so local-only tabs must be omitted from the mirrored order.
             tabOrder: reorderedHostTabOrder
           }
         : args.kind === 'split'
@@ -415,8 +397,7 @@ export async function moveWebRuntimeSessionTab(
           : {
               ...base,
               kind: 'move-to-group' as const,
-              // Why: web groups can contain local-only tabs. Host insertion
-              // indexes must be counted in the filtered host-backed order.
+              // Why: web groups can contain local-only tabs, so host insertion indexes count only the filtered host-backed order.
               index: targetHostIndex
             }
     const response = await window.api.runtimeEnvironments.call({
@@ -453,12 +434,7 @@ async function callWebRuntimeSessionTabMethod(
   }
 
   if (method === 'session.tabs.close') {
-    // Why: the caller prunes the local mirror synchronously, but the precise
-    // host id resolution below sits behind an async import. A host snapshot
-    // published in that gap would re-materialize the just-closed tab before any
-    // intent exists to suppress it (the immediate "flash back"). Record a
-    // best-effort intent synchronously now — the resolved-id record below then
-    // covers any id the static decode couldn't recover.
+    // Why: sync best-effort intent before the async id resolution, so a snapshot in that gap can't flash the closed tab back.
     recordWebSessionCloseIntent(args.worktreeId, toHostSessionTabId(args.tabId), Date.now())
   }
 
@@ -472,9 +448,7 @@ async function callWebRuntimeSessionTabMethod(
         tabId: args.tabId
       }) ?? toHostSessionTabId(args.tabId)
     if (method === 'session.tabs.close') {
-      // Why: the local mirror is pruned before this resolves, so suppress this
-      // host tab in the reconcile until the host snapshot confirms removal —
-      // otherwise an in-flight pre-close snapshot makes the tab flash back.
+      // Why: suppress until the host confirms removal, else an in-flight pre-close snapshot flashes the tab back.
       recordWebSessionCloseIntent(args.worktreeId, hostTabId, Date.now())
     }
     const response = await window.api.runtimeEnvironments.call({
@@ -514,9 +488,7 @@ export function splitWebRuntimeTerminal(
     return false
   }
 
-  // Why: split requests from the paired web client must run on the host pane.
-  // A local split would mint a web-only pane and the host would mirror it back
-  // as a separate tab instead of preserving the terminal split layout.
+  // Why: split must run on the host pane; a local split mints a web-only pane the host mirrors back as a tab, not a split.
   const pendingMirrorSuppressionId = reservePendingWebRuntimeSplitMirrorTelemetry(ptyId, direction)
   const releasePendingMirrorSuppression = schedulePendingWebRuntimeSplitMirrorTelemetryRelease(
     ptyId,
@@ -632,9 +604,7 @@ export function closeWebRuntimeTerminal(ptyId: string | null | undefined): boole
     return false
   }
 
-  // Why: host-session mirror panes are detached locally in the browser, but
-  // the host owns the real pane graph. Close the host terminal first so later
-  // session snapshots cannot resurrect the locally removed pane.
+  // Why: host owns the real pane graph; close the host terminal first so later snapshots can't resurrect the removed pane.
   void window.api.runtimeEnvironments
     .call({
       selector: environmentId,
@@ -656,10 +626,7 @@ export function closeWebRuntimeTerminal(ptyId: string | null | undefined): boole
   return true
 }
 
-// Why: pane geometry inside a tab (split ratios, expanded pane, pane titles) is
-// host-authoritative for remote-server tabs, so a local-only divider drag /
-// expand / pane-rename reverts on the next snapshot. Push the structure to the
-// host so it persists. tabId is the local web tab id; we resolve the host id.
+// Why: pane geometry is host-authoritative for remote tabs; local-only changes revert on next snapshot, so push to host.
 export async function updateWebRuntimePaneLayout(args: {
   worktreeId: string
   tabId: string
@@ -699,9 +666,7 @@ export async function updateWebRuntimePaneLayout(args: {
   }
 }
 
-// Why: tab color/pin are host-authoritative for remote-server tabs; mirror the
-// change to the host so it persists and survives the next snapshot. Pass only
-// the fields that changed (undefined = leave as-is on the host).
+// Why: tab color/pin are host-authoritative; mirror the change so it persists (undefined field = leave as-is on host).
 export function setWebRuntimeTabProps(args: {
   worktreeId: string
   tabId: string
@@ -748,9 +713,7 @@ export function setWebRuntimeTabProps(args: {
   return true
 }
 
-// Why: clearing scrollback locally (pane.terminal.clear()) is undone by the next
-// host snapshot/re-subscribe, which replays the host buffer. Clear the host
-// buffer too so the clear actually sticks on a remote-server pane.
+// Why: local pane.terminal.clear() is undone by the next host snapshot replay; clear the host buffer so it sticks.
 export function clearWebRuntimeTerminalBuffer(ptyId: string | null | undefined): boolean {
   if (!ptyId) {
     return false
diff --git a/src/renderer/src/runtime/web-session-tabs-sync.ts b/src/renderer/src/runtime/web-session-tabs-sync.ts
index 3833eea19c1..3dddb45fc0b 100644
--- a/src/renderer/src/runtime/web-session-tabs-sync.ts
+++ b/src/renderer/src/runtime/web-session-tabs-sync.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: web session-tab sync reconciles terminal,
- * unified-tab, group, and PTY maps atomically so host-published surfaces don't
- * leave the web client in a split-brain tab state. */
+/* eslint-disable max-lines -- web session-tab sync reconciles terminal, unified-tab, group, and PTY maps atomically to avoid split-brain tab state */
 import { useEffect } from 'react'
 import type { AppState } from '../store'
 import { useAppStore } from '../store'
@@ -178,11 +176,7 @@ export function getLastKnownHostTerminalTabCount(
   )
 }
 
-// Why: a post-reconnect subscription replay re-emits the current snapshot with
-// an unchanged epoch/version; dropping the freshness entry lets the monotonic
-// gate accept that replay as authoritative instead of freezing the mirror
-// (#7718). Normal-operation ordering protection is untouched — this only runs
-// for responses the connection tagged as reconnect replays.
+// Why: a post-reconnect replay re-emits the snapshot with unchanged epoch/version; dropping the freshness entry lets the monotonic gate accept it instead of freezing the mirror (#7718).
 export function acceptReplayedWebSessionTabsSnapshot(
   environmentId: string,
   worktreeId: string
@@ -196,31 +190,18 @@ export function shouldApplyWebSessionTabsSnapshot(
 ): boolean {
   const key = sessionTabsFreshnessKey(environmentId, snapshot.worktree)
   if ((snapshot as { removed?: unknown }).removed === true) {
-    // Why: removed worktrees can stop publishing snapshots, so their
-    // freshness/mapping entries need explicit cleanup instead of waiting for
-    // a later replacement snapshot that may never arrive.
+    // Why: removed worktrees can stop publishing, so clean up their tracking now instead of waiting for a replacement snapshot that may never arrive.
     clearWebSessionTabsTrackingForWorktree(environmentId, snapshot.worktree)
     queueAcceptedWebSessionTerminalSnapshot(snapshot, environmentId)
     return true
   }
   if (snapshot.worktree === FLOATING_TERMINAL_WORKTREE_ID) {
-    // Why: the floating workspace is a local synthetic terminal. A focused
-    // remote runtime can publish an empty same-id snapshot while the user has a
-    // local ssh/tmux tab open; treating that as authoritative deletes the local
-    // floating tabs.
+    // Why: the floating workspace is a local synthetic terminal; a remote empty same-id snapshot would delete the user's local floating tabs.
     return false
   }
   rememberHostTerminalTabCount(environmentId, snapshot)
   const current = latestSessionTabsSnapshotByWorktree.get(key)
-  // Why: snapshotVersion is monotonic only WITHIN one host generation; it resets
-  // when the host restarts, and each restart produces a different publicationEpoch.
-  // So only treat a frame as stale when it shares the current epoch and isn't
-  // newer — a different epoch is a new generation (or a restart) and must apply,
-  // even if its version is lower. (A cross-stream out-of-order frame with a
-  // different epoch may briefly apply, but the next snapshot's higher version
-  // self-heals it; rejecting on version alone would instead permanently drop a
-  // post-restart snapshot, since the client's tracking survives transparent
-  // transport reconnects.)
+  // Why: snapshotVersion is monotonic only within one publicationEpoch (resets on host restart); reject as stale only within the same epoch, since a different epoch is a new generation and must apply.
   if (
     current &&
     current.publicationEpoch === snapshot.publicationEpoch &&
@@ -232,8 +213,7 @@ export function shouldApplyWebSessionTabsSnapshot(
     publicationEpoch: snapshot.publicationEpoch,
     snapshotVersion: snapshot.snapshotVersion
   })
-  // Why: a mounted mirror that exhausted bounded polling needs fresh host
-  // evidence without subscribing to every application-store write.
+  // Why: a mounted mirror that exhausted bounded polling needs fresh host evidence without subscribing to every store write.
   queueAcceptedWebSessionTerminalSnapshot(snapshot, environmentId)
   return true
 }
@@ -437,8 +417,7 @@ function chooseRemoteTerminalLayout(
       ])
     : undefined
   const activeLeafId =
-    // Why: host title/status snapshots may still mark an agent pane active
-    // after this client selected a different split pane.
+    // Why: host title/status snapshots may still mark an agent pane active after this client selected a different split pane.
     (existingLayout?.activeLeafId && knownLeafIds.has(existingLayout.activeLeafId)
       ? existingLayout.activeLeafId
       : null) ??
@@ -453,9 +432,7 @@ function chooseRemoteTerminalLayout(
       ? parentLayout.expandedLeafId
       : null
   return {
-    // Why: the host's parentLayout is authoritative (carries the real split
-    // direction); only if it doesn't cover the current leaves do we keep the
-    // prior client tree, then degenerate — never re-guess a direction.
+    // Why: host parentLayout is authoritative for split direction; else keep the prior client tree, then degenerate — never re-guess a direction.
     root: resolveTerminalLayoutRoot({
       authoritativeRoot: parentLayout?.root,
       existingRoot: existingLayout?.root,
@@ -468,9 +445,7 @@ function chooseRemoteTerminalLayout(
     activeLeafId,
     expandedLeafId,
     ptyIdsByLeafId,
-    // Why: surface.title is the tab/PTY label ("Terminal 2", agent title,
-    // etc.). Restoring it as a pane title makes the web client render a fake
-    // title bar above xterm. Only host layout titles are real user pane titles.
+    // Why: surface.title is the tab/PTY label, not a pane title; restoring it as one renders a fake title bar. Only host layout titles are real pane titles.
     ...(parentLayout?.titlesByLeafId ? { titlesByLeafId: parentLayout.titlesByLeafId } : {})
   }
 }
@@ -487,14 +462,11 @@ function shouldReplaceTerminalTab(
     !isMirroredTerminalSurfaceId(tab.id) &&
     nextMirroredLaunchAgents.has(tab.launchAgent)
   ) {
-    // Why: paired web agent quick-launch used to create local-only tabs before
-    // the host snapshot landed. Retire only the matching agent's stale row.
+    // Why: agent quick-launch created a local-only tab before the host snapshot landed; retire only the matching agent's stale row.
     return true
   }
   if (isMirroredTerminalSurfaceId(tab.id)) {
-    // Why: host session snapshots are authoritative for host-mirrored tabs.
-    // Replace old mirrors even when the next surface is still waiting on a
-    // stream handle, otherwise paired web keeps stale handles or drops parity.
+    // Why: host snapshots are authoritative for mirrored tabs; replace old mirrors even when the next surface still awaits a stream handle, else parity drifts.
     return true
   }
   if (tab.pendingActivationSpawn && tab.ptyId === null && nextRemotePtyIds.size > 0) {
@@ -503,9 +475,7 @@ function shouldReplaceTerminalTab(
   if (!isRuntimeTerminalTabForEnvironment(tab, environmentId)) {
     return false
   }
-  // Why: web-created remote tabs use local UUIDs until the host publishes the
-  // corresponding session surface. Only retire them once their PTY is present
-  // in the host snapshot, while always pruning prior mirrored surface IDs.
+  // Why: web-created remote tabs use local UUIDs until the host publishes their surface; only retire them once their PTY appears in the snapshot.
   return (
     tab.ptyId !== null &&
     (nextRemotePtyIds.has(tab.ptyId) ||
@@ -513,10 +483,7 @@ function shouldReplaceTerminalTab(
   )
 }
 
-/**
- * Constructs mirrored terminal tabs from the mobile session status payload,
- * normalising Pi-compatible agent titles under launch ownership.
- */
+/** Constructs mirrored terminal tabs from the mobile session status payload, normalising Pi-compatible agent titles under launch ownership. */
 function buildMirroredTerminalTabs(
   snapshot: RuntimeMobileSessionTabsResult,
   environmentId: string,
@@ -571,23 +538,16 @@ function buildMirroredTerminalTabs(
       activeSurface.quickCommandLabel?.trim() ||
       surfaces.find((surface) => surface.quickCommandLabel?.trim())?.quickCommandLabel?.trim() ||
       existing?.quickCommandLabel?.trim()
-    // Why: startup cwd is host-owned launch metadata; once the host omits it,
-    // mirrored clients must not resurrect stale subdirectory intent.
+    // Why: startupCwd is host-owned launch metadata; once the host omits it, don't resurrect stale subdirectory intent.
     const startupCwd =
       activeSurface.startupCwd || surfaces.find((surface) => surface.startupCwd)?.startupCwd
-    // Why: tab color/pin echo back through host snapshots, so prefer the client's
-    // own record (kept authoritative in tabsByWorktree by the pin/color setters)
-    // and fall back to the host value only when this client has no prior tab —
-    // e.g. first reconcile or a change made on another client. Mirrors how
-    // customTitle always prefers the client value to avoid echo-window reverts.
+    // Why: color/pin echo back through host snapshots, so prefer the client's own record and fall back to host only without a prior tab (avoids echo-window reverts).
     const hostColorSurface = surfaces.find((surface) => surface.color != null)
     const color = existing ? (existing.color ?? null) : (hostColorSurface?.color ?? null)
     const isPinned = existing
       ? existing.isPinned === true
       : surfaces.some((surface) => surface.isPinned)
-    // Why: viewMode echoes back through host snapshots like color/pin, so prefer
-    // the client's own record during the optimistic echo window and adopt the host
-    // value only when this client has no prior tab (first reconcile / other client).
+    // Why: viewMode echoes back through host snapshots, so prefer the client's record during the echo window and adopt the host value only without a prior tab.
     const hostViewModeSurface = surfaces.find((surface) => surface.viewMode)
     const viewMode = existing ? existing.viewMode : hostViewModeSurface?.viewMode
     return {
@@ -605,8 +565,7 @@ function buildMirroredTerminalTabs(
         ...(viewMode ? { viewMode } : {}),
         sortOrder: sortOffset + index,
         createdAt: existing?.createdAt ?? now + index,
-        // Why: launchAgent is host-owned lifecycle metadata. If the host stops
-        // publishing it, mirrored clients must not resurrect stale startup intent.
+        // Why: launchAgent is host-owned lifecycle metadata; once the host omits it, don't resurrect stale startup intent.
         ...(launchAgent ? { launchAgent } : {})
       },
       hostTabId: parentTabId,
@@ -623,10 +582,7 @@ function toMirroredPaneKey(surface: TerminalSurface): string | null {
   return makePaneKey(toWebTerminalSurfaceTabId(surface.parentTabId), surface.leafId)
 }
 
-/**
- * Normalises and mirrors agent status updates from the host payload,
- * preserving authoritative ownership metadata.
- */
+/** Normalises and mirrors agent status updates from the host payload, preserving ownership metadata. */
 function remapHostAgentStatus(surface: TerminalSurface): AgentStatusEntry | null {
   if (!surface.agentStatus) {
     return null
@@ -650,10 +606,7 @@ function isMirroredAgentPaneKeyForTabs(paneKey: string, tabIds: ReadonlySet<stri
   return parsed !== null && tabIds.has(parsed.tabId)
 }
 
-/**
- * Generates a state patch for mirrored agent statuses, merging host
- * status entries with client overrides defensively.
- */
+/** Generates a state patch for mirrored agent statuses, merging host entries with client overrides. */
 function buildMirroredAgentStatusPatch(
   state: WebSessionTabsSyncState,
   currentTerminalTabs: readonly TerminalTab[],
@@ -681,9 +634,7 @@ function buildMirroredAgentStatusPatch(
       continue
     }
     const existing = state.agentStatusByPaneKey[entry.paneKey]
-    // Why: active web streams can report a fresher OSC 9999 status for the same
-    // mirrored pane before the next host snapshot arrives. Do not rewind that
-    // row with an older host publication.
+    // Why: an active web stream can report a fresher OSC 9999 status before the next host snapshot, so don't rewind it with an older host publication.
     const nextEntry =
       existing && existing.updatedAt > entry.updatedAt
         ? normalizeCompatibleAgentStatusEntryForOwner(existing, entry.agentType)
@@ -748,10 +699,7 @@ function buildMirroredAgentStatusPatch(
 function buildTerminalUnifiedTab(
   tab: TerminalTab,
   groupId: string,
-  // Why: viewMode (terminal vs native chat) is host-tracked, but the client's
-  // optimistic toggle must win during the echo window. Callers pass the reconciled
-  // value (host value falling back to the captured client value) so toggling to
-  // chat doesn't revert when the next session-graph sync rebuilds tabs.
+  // Why: viewMode is host-tracked but the client's optimistic toggle must win during the echo window; callers pass the reconciled value.
   viewMode?: Tab['viewMode']
 ): Tab {
   return {
@@ -871,8 +819,7 @@ function buildMirroredEditorTabs(
       runtimeEnvironmentId: environmentId,
       mode: tab.type === 'markdown' ? tab.mode : 'edit',
       markdownPreviewSourceFileId: sourceFileId,
-      // Why: marks this tab as host-owned so a later snapshot that omits it can
-      // cull it. Locally opened web tabs lack this flag and survive syncs.
+      // Why: marks this tab host-owned so a later snapshot that omits it can cull it; locally opened tabs lack this flag and survive.
       mirroredFromRuntimeSession: true
     }
     return {
@@ -1006,8 +953,7 @@ function chooseTargetGroupId(
         group.id === state.activeGroupIdByWorktree[snapshot.worktree] && inRenderedLayout(group.id)
     ) ??
     groups.find((group) => inRenderedLayout(group.id))
-  // Why: host snapshots can reference desktop-only group ids. The web layout's
-  // rendered group is the only safe CSS anchor target for mirrored panes.
+  // Why: host snapshots can reference desktop-only group ids; the rendered group is the only safe CSS anchor for mirrored panes.
   const firstRenderedLayoutGroupId = layoutGroupIds.values().next().value as string | undefined
   return (
     preferred?.id ??
@@ -1233,8 +1179,7 @@ function buildMirroredHostGroups({
       ...(existing?.tabOrder.filter((tabId) => !localHostOrder.includes(tabId)) ?? []),
       ...localHostOrder
     ]
-    // Why: a pending client reorder for this group wins over a stale pre-move
-    // host order until the host echoes the move (or membership changes).
+    // Why: a pending client reorder wins over a stale pre-move host order until the host echoes the move (or membership changes).
     const tabOrder = resolveWebSessionReorderedOrder(worktreeId, hostGroup.id, hostTabOrder, now)
     if (tabOrder.length === 0) {
       continue
@@ -1680,15 +1625,8 @@ export function applyWebSessionTabsSnapshot(
   if (worktreeId === FLOATING_TERMINAL_WORKTREE_ID) {
     return state
   }
-  // Why: a remote close prunes the local mirror immediately, but an in-flight
-  // pre-close snapshot can still list the tab and flash it back. Drop any tab
-  // the client is closing until the host confirms removal; reconcile the intents
-  // against the full snapshot first so confirmed (absent) closes clear.
-  // Why: must match the id the close path records as the intent. The close RPC
-  // resolves to the host session tab id (terminal parentTabId; otherwise tab.id)
-  // — keying browser on browserPageId instead never matched, so browser closes
-  // were never suppressed and reconcile cleared the intent on the still-present
-  // snapshot. The host also addresses tabs by session id, not page id.
+  // Why: an in-flight pre-close snapshot can flash a closing tab back, so drop tabs the client is closing until the host confirms removal.
+  // Why: key close intents by host session tab id (terminal parentTabId else tab.id), not browserPageId, or browser closes never get suppressed.
   const snapshotHostTabId = (tab: RuntimeMobileSessionTabsResult['tabs'][number]): string =>
     tab.type === 'terminal' ? tab.parentTabId : tab.id
   reconcileWebSessionCloseIntents(
@@ -1705,11 +1643,7 @@ export function applyWebSessionTabsSnapshot(
         )
       }
     : rawSnapshot
-  // Why: only follow the snapshot's active tab over the user's current focus when
-  // the client itself initiated this activation (a create/activate it recorded).
-  // An unsolicited server-active (e.g. an agent "thinking" echo) must not steal
-  // focus — that's the #5435 contract. Intent matches by the host active tab id
-  // (terminal session id, or browserPageId for browser tabs); consume it once.
+  // Why: follow the snapshot's active tab over the user's focus only when this client initiated the activation; unsolicited server-active must not steal focus (#5435).
   const focusIntentHostTabId = peekWebSessionFocusIntent(worktreeId)
   const honorSnapshotActiveFocus =
     focusIntentHostTabId !== null &&
@@ -1830,9 +1764,7 @@ export function applyWebSessionTabsSnapshot(
           file.worktreeId === worktreeId &&
           file.runtimeEnvironmentId === environmentId &&
           (file.mode === 'edit' || file.mode === 'markdown-preview') &&
-          // Why: only cull tabs that came from the host mirror. Files the web
-          // user opened locally have no host counterpart, so a snapshot that
-          // omits them is not a signal to close them.
+          // Why: only cull host-mirrored tabs; locally opened files have no host counterpart, so their omission isn't a close signal.
           file.mirroredFromRuntimeSession === true &&
           !mirroredEditorFileIds.has(file.id)
       )
@@ -1882,8 +1814,6 @@ export function applyWebSessionTabsSnapshot(
     buildTerminalUnifiedTab(
       entry.tab,
       hostGroupIdByTabId.get(entry.hostTabId) ?? targetGroupId,
-      // Prefer the reconciled mirrored value (already client-wins during the echo
-      // window); fall back to the captured client value when the entry omits it.
       entry.tab.viewMode ?? existingViewModeByTabId.get(entry.tab.id)
     )
   )
@@ -1935,8 +1865,7 @@ export function applyWebSessionTabsSnapshot(
     (nextTerminalTabs ?? []).some((tab) => tab.id === state.activeTabIdByWorktree[worktreeId])
       ? state.activeTabIdByWorktree[worktreeId]
       : null
-  // Why: when the client initiated this activation (honorSnapshotActiveFocus),
-  // the snapshot's active terminal wins over the sticky current focus.
+  // Why: on a client-initiated activation (honorSnapshotActiveFocus), the snapshot's active terminal wins over sticky current focus.
   const intentTerminalId =
     honorSnapshotActiveFocus && snapshot.activeTabType === 'terminal'
       ? activeMirroredTerminalId
@@ -1983,8 +1912,7 @@ export function applyWebSessionTabsSnapshot(
     worktreeId,
     nextUnifiedTabs
   })
-  // Why: a client-initiated activation also drives the visible unified tab,
-  // overriding the sticky current-visible tab.
+  // Why: a client-initiated activation also drives the visible unified tab, overriding the sticky current-visible tab.
   const intentUnifiedTabId = honorSnapshotActiveFocus
     ? snapshot.activeTabType === 'browser'
       ? activeMirroredBrowserTabId
@@ -2103,9 +2031,7 @@ export function applyWebSessionTabsSnapshot(
         next.push(tabId)
       }
     }
-    // Why: remote snapshots can arrive after the client staged local browser
-    // tabs. Preserve the user's visible mixed order and only append new host
-    // tabs; otherwise terminal-browser-terminal can collapse to browser-terminal-terminal.
+    // Why: snapshots can arrive after the client staged local browser tabs, so preserve visible order and only append new host tabs.
     for (const tabId of current) {
       push(tabId)
     }
@@ -2260,8 +2186,7 @@ export function applyWebSessionTabsSnapshot(
     sameGroups
   )
   const nextActiveGroupId =
-    // Why: remote status/title snapshots carry the host's last active tab; a
-    // client that already switched panes must keep its local group focus.
+    // Why: status/title snapshots carry the host's last active tab; a client that already switched panes keeps its local group focus.
     nextGroups?.find((group) => group.activeTabId === nextActiveUnifiedTabId)?.id ??
     nextGroups?.find((group) => group.id === snapshot.activeGroupId)?.id ??
     nextGroups?.[0]?.id ??
@@ -2363,10 +2288,7 @@ export function applyWebSessionTabsSnapshot(
           : nextActiveEditorFileId
             ? ('editor' as const)
             : ('terminal' as const)
-  // Why: an empty/closed host snapshot has no active host tab, but the web
-  // client must not keep pointing global shortcuts at a removed browser/editor.
-  // A client-initiated activation (honorSnapshotActiveFocus) makes the snapshot's
-  // type win, so a create can switch the visible pane (e.g. terminal -> browser).
+  // Why: don't keep pointing shortcuts at a removed browser/editor; a client-initiated activation lets the snapshot's type switch the visible pane.
   const nextVisibleTabType = honorSnapshotActiveFocus
     ? (snapshotVisibleTabType ?? currentVisibleTabTypeStillValid ?? fallbackVisibleTabType)
     : (currentVisibleTabTypeStillValid ?? snapshotVisibleTabType ?? fallbackVisibleTabType)
@@ -2520,8 +2442,7 @@ export function applyWebSessionTabsStorePatch(
       patch !== state && Object.prototype.hasOwnProperty.call(patch, 'agentStatusByPaneKey')
     return patch
   })
-  // Why: paired-web snapshots bypass setAgentStatus, so they must explicitly
-  // arm the same stale-boundary timer as local hook events.
+  // Why: paired-web snapshots bypass setAgentStatus, so arm the stale-boundary timer explicitly like local hook events do.
   if (mirroredAgentStatusChanged) {
     useAppStore.getState().scheduleAgentStatusFreshness()
   }
@@ -2541,20 +2462,15 @@ export function useWebSessionTabsSync(): void {
     const environmentIds = runtimeSessionMirrorEnvironmentKey
       ? runtimeSessionMirrorEnvironmentKey.split('\u0000').filter((id) => id.trim())
       : []
-    // Why: startup hydration writes browser-local session state; applying the
-    // host snapshot before that point gets clobbered and leaves the sidebar stale.
-    // Selectedness is not liveness: desktop and web clients both mirror the
-    // runtime's session bindings so background worktrees do not look asleep.
+    // Why: mirror all paired runtimes' sessions, not just the selected worktree, so background worktrees don't look asleep (selectedness isn't liveness).
+    // Why: applying the host snapshot before startup hydration writes browser-local session state clobbers it and leaves the sidebar stale.
     if (!workspaceSessionReady || environmentIds.length === 0) {
       return
     }
 
     let disposed = false
     const unsubscribes: (() => void)[] = []
-    // Why: the streaming RPC emits an initial snapshots event, but startup can
-    // render a paired web session before that event is applied. A one-shot
-    // fetch makes initial parity deterministic; the stream remains the live
-    // update path afterward.
+    // Why: the stream's initial snapshot can land after first render, so a one-shot fetch makes initial parity deterministic.
     for (const environmentId of environmentIds) {
       if (
         !shouldSyncAllRuntimeSessionTabs({
@@ -2667,8 +2583,7 @@ export function useWebSessionTabsSync(): void {
       for (const unsubscribe of unsubscribes) {
         unsubscribe()
       }
-      // Why: environment ids can churn as paired runtimes reconnect or switch;
-      // stale freshness/mapping entries should not live for the renderer lifetime.
+      // Why: environment ids churn as paired runtimes reconnect; don't leak stale tracking for the renderer lifetime.
       for (const environmentId of environmentIds) {
         clearWebSessionTabsTrackingForEnvironment(environmentId)
       }
@@ -2758,8 +2673,7 @@ export function useWebSessionTabsSync(): void {
               beginWebRuntimeWakeTerminalRespawn(activeWorktreeId)
             ) {
               requestedRespawnAfterWake = true
-              // Why: wake recovery must recreate the terminal without changing
-              // selected worktree to avoid re-triggering activation churn.
+              // Why: recreate the terminal without changing selected worktree to avoid re-triggering activation churn.
               void createWebRuntimeSessionTerminal({
                 worktreeId: activeWorktreeId,
                 environmentId,
diff --git a/src/renderer/src/store/slices/agent-status.ts b/src/renderer/src/store/slices/agent-status.ts
index f30164e8790..42d8fa7a2bf 100644
--- a/src/renderer/src/store/slices/agent-status.ts
+++ b/src/renderer/src/store/slices/agent-status.ts
@@ -42,17 +42,13 @@ import {
 } from './agent-pane-authority'
 import { createFreshnessScheduler } from './agent-status-freshness-scheduler'
 
-/** Snapshot of a finished (or vanished) agent status entry, kept around so
- *  the dashboard + sidebar hover can continue showing the completion until the
- *  user acknowledges it by clicking the worktree. The `worktreeId` is stamped
- *  at retention time so we know where the row belongs even after the tab/pty
- *  it came from has gone away. */
+/** Snapshot of a finished/vanished agent status entry, kept so the dashboard and sidebar hover
+ *  keep showing the completion until the user clicks the worktree. `worktreeId` is stamped at
+ *  retention time so the row's home is known even after its tab/pty is gone. */
 export type RetainedAgentEntry = {
   entry: AgentStatusEntry
   worktreeId: string
-  /** Snapshot of the tab the agent lived in at retention time. We keep the
-   *  full record (not just an id) because the tab may be gone from
-   *  `tabsByWorktree` by the time the retained row is rendered. */
+  /** Snapshot of the tab at retention time; kept full (not just an id) because the tab may be gone from `tabsByWorktree` by render time. */
   tab: TerminalTab
   agentType: AgentType
   startedAt: number
@@ -106,14 +102,11 @@ type AgentLaunchConfigRegistryEntry = {
 }
 
 export type AgentStatusSlice = {
-  /** Explicit agent status entries keyed by `${tabId}:${leafId}` composite.
-   *  Real-time only — lives in renderer memory, not persisted to disk. */
+  /** Explicit agent status entries keyed by `${tabId}:${leafId}`; real-time only, not persisted. */
   agentStatusByPaneKey: Record<string, AgentStatusEntry>
-  /** Main-synced dispatch metadata for live terminal panes that may only have
-   *  title-derived status in the renderer. */
+  /** Main-synced dispatch metadata for live panes that may only have title-derived status in the renderer. */
   runtimeAgentOrchestrationByPaneKey: Record<string, AgentStatusOrchestrationContext>
-  /** PTYs that still report legacy numeric pane keys but have registry-backed
-   *  UUID pane proof. Stored separately from normal hook-reported status. */
+  /** PTYs still reporting legacy numeric pane keys but with registry-backed UUID proof; stored separately from normal hook-reported status. */
   migrationUnsupportedByPtyId: Record<string, MigrationUnsupportedPtyEntry>
   /** Monotonic tick that advances when agent-status freshness boundaries pass. */
   agentStatusEpoch: number
@@ -123,27 +116,19 @@ export type AgentStatusSlice = {
   /** Arm the shared freshness timer after an external mirror writes live rows. */
   scheduleAgentStatusFreshness: () => void
 
-  /** Retained "done" entries — snapshots of agents that have disappeared from
-   *  `agentStatusByPaneKey`. Keyed by paneKey so re-appearance of the same pane
-   *  overwrites the snapshot. Shared between the dashboard and the sidebar
-   *  agent-status hover so the two surfaces display identical rows. */
+  /** Retained "done" snapshots of agents gone from `agentStatusByPaneKey`, keyed by paneKey so pane re-appearance overwrites; shared by dashboard and sidebar hover. */
   retainedAgentsByPaneKey: Record<string, RetainedAgentEntry>
 
-  /** Durable agent sessions captured when a workspace sleeps. These are not
-   *  live status rows; they power the one-click CLI resume action on wake. */
+  /** Durable agent sessions captured on sleep (not live rows); power the one-click CLI resume on wake. */
   sleepingAgentSessionsByPaneKey: Record<string, SleepingAgentSessionRecord>
 
-  /** Ephemeral launch snapshots keyed by concrete pane. Hook payloads do not
-   *  carry Orca launch settings, so the renderer supplies them from startup. */
+  /** Ephemeral launch snapshots keyed by pane; hook payloads lack Orca launch settings, so the renderer supplies them from startup. */
   agentLaunchConfigByPaneKey: Record<string, AgentLaunchConfigRegistryEntry>
 
-  /** Pane keys explicitly torn down (pane close, tab close, PTY exit, manual
-   *  dismissal) and therefore forbidden from being re-retained on their next
-   *  disappearance. Consumed by the retention sync as a one-shot suppressor. */
+  /** Pane keys explicitly torn down, forbidden from re-retention on next disappearance; a one-shot suppressor consumed by the retention sync. */
   retentionSuppressedPaneKeys: Record<string, true>
 
-  /** Terminal tabs explicitly closed in this renderer session. Used only to
-   *  drop late in-flight IPC statuses and stale main-cache replays. */
+  /** Terminal tabs explicitly closed this session; used to drop late in-flight IPC statuses and stale main-cache replays. */
   recentlyClosedAgentStatusTabIds: Record<string, true>
 
   /** Exact pane authorities retired while sibling panes in the tab stay live. */
@@ -211,56 +196,41 @@ export type AgentStatusSlice = {
   /** Remove a single entry (e.g., when a pane's terminal exits). */
   removeAgentStatus: (paneKey: string) => void
 
-  /** Remove all entries whose paneKey starts with the given prefix.
-   *  Used when a tab is closed — same prefix-sweep as cacheTimerByKey cleanup. */
+  /** Remove all entries whose paneKey starts with the given prefix (tab close prefix-sweep). */
   removeAgentStatusByTabPrefix: (tabIdPrefix: string) => void
 
   /** Remove stale live rows while preserving pane launch and resume identity. */
   clearTransientAgentStatuses: (connectionId: string, clearedAt: number) => void
 
-  /** Remove a single entry AND suppress re-retention on its next disappearance.
-   *  Used for USER-INITIATED teardown — the dashboard/hover X button, and
-   *  pane close — where the user is telling us "I'm done with this row". */
+  /** Remove a single entry AND suppress re-retention on its next disappearance (user-initiated teardown: X button, pane close). */
   dropAgentStatus: (paneKey: string) => void
 
-  /** Remove all entries under a tab AND suppress re-retention for each.
-   *  Used on tab close — the user is tearing down the whole tab, so any
-   *  remaining agent rows (live or retained) must not reappear. */
+  /** Remove all entries under a tab AND suppress re-retention for each (tab close — no rows may reappear). */
   dropAgentStatusByTabPrefix: (
     tabIdPrefix: string,
     opts?: DropAgentStatusByTabPrefixOptions
   ) => void
 
-  /** Remove one automatically hibernated completed-agent pane while preserving
-   *  sibling live/retained rows in the same worktree. */
+  /** Remove one auto-hibernated completed-agent pane while preserving sibling live/retained rows in the same worktree. */
   dropHibernatedAgentStatusPane: (
     worktreeId: string,
     paneKey: string,
     opts?: DropHibernatedAgentPaneOptions
   ) => void
 
-  /** Remove all entries for a worktree AND suppress re-retention for live rows.
-   *  Used on worktree sleep/remove — the whole worktree surface is folding, so
-   *  retained rows must drop even if their original tab is no longer present.
-   *
-   *  Live entries are swept by tab prefix and by main-stamped worktree
-   *  attribution so worker rows that arrive before their tab exists do not
-   *  survive sleep/remove. */
+  /** Remove all entries for a worktree AND suppress re-retention for live rows (worktree sleep/remove).
+   *  Sweeps live rows by tab prefix and by main-stamped worktree attribution so worker rows that arrive before their tab don't survive. */
   dropAgentStatusByWorktree: (worktreeId: string, opts?: DropAgentStatusByWorktreeOptions) => void
 
   captureSleepingAgentSessionsByWorktree: (worktreeId: string, paneKeys?: string[]) => void
-  /** Capture resumable agent sessions across every worktree for crash recovery
-   *  or a confirmed quit. The mode keeps live and quit precedence explicit. */
+  /** Capture resumable agent sessions across every worktree for crash recovery or quit; mode sets live/quit precedence. */
   captureAllSleepingAgentSessions: (mode: AllAgentSessionCaptureMode) => void
   clearSleepingAgentSession: (paneKey: string) => void
   clearSleepingAgentSessionsByPaneKey: (paneKeys: readonly string[]) => void
   clearSleepingAgentSessionsByWorktree: (worktreeId: string) => void
   pruneSleepingAgentSessions: (validWorktreeIds: Set<string>) => void
 
-  /** Retain agent snapshots (called by the top-level retention sync effect).
-   *  Accepts an array so multiple agents disappearing in the same frame
-   *  produce a single set(...) — avoids intermediate states visible
-   *  mid-loop to consumers. */
+  /** Retain agent snapshots. Accepts an array so simultaneous disappearances produce a single set() with no mid-loop intermediate states. */
   retainAgents: (entries: RetainedAgentEntry[]) => void
 
   /** Dismiss a retained entry by its paneKey. */
@@ -272,20 +242,11 @@ export type AgentStatusSlice = {
   /** Prune retained entries whose worktreeId is not in the given set. */
   pruneRetainedAgents: (validWorktreeIds: Set<string>) => void
 
-  /** Clear one-shot teardown suppressors after the retention sync observes
-   *  that disappearance and decides not to retain the row. */
+  /** Clear one-shot teardown suppressors after the retention sync declines to retain the row. */
   clearRetentionSuppressedPaneKeys: (paneKeys: string[]) => void
 }
 
-// Why: retainedAgentsByPaneKey snapshots a completed agent (a full
-// AgentStatusEntry — up to ~24KB of prompt/message text — plus a TerminalTab)
-// per ephemeral paneKey. paneKeys never recur, and the map is pruned only on
-// worktree removal or manual dismissal, so a long-lived worktree in a busy
-// multi-agent session grows it without bound — the dominant driver of the
-// renderer JS-heap OOM. Cap by insertion order (== retention order), evicting
-// the oldest completions first so the newest — the ones a user is most likely
-// to still care about — always survive. Evicted rows just stop showing in the
-// recently-completed overlay.
+// Why: retained entries are heavy (~24KB) and grow unbounded on busy worktrees (dominant renderer OOM); cap, evicting oldest completions first.
 const MAX_RETAINED_AGENTS = 500
 
 function capRetainedAgents(
@@ -603,8 +564,8 @@ export function collectSleepingAgentSessionRecordsForWorktree(
   const isManualWorktreeSleep = collectOptions.captureMode === 'manual-worktree-sleep'
   const isCompletedAgentHibernation = collectOptions.captureMode === 'completed-agent-hibernation'
   const isWorktreeOwnedCapture = isManualWorktreeSleep || isCompletedAgentHibernation
-  // Why: hibernated completions are intentional worktree-owned records; wake
-  // treats originless completed records as ambiguous legacy captures.
+  // Why: hibernated completions are intentional worktree-owned records; wake treats
+  // originless completed records as ambiguous legacy captures.
   const origin: SleepingAgentSessionRecord['origin'] | undefined = isWorktreeOwnedCapture
     ? 'worktree-sleep'
     : undefined
@@ -623,8 +584,8 @@ export function collectSleepingAgentSessionRecordsForWorktree(
       ) {
         continue
       }
-      // Why: Pi identity is resumable with no turn row and while idle after
-      // done; manual sleep must promote both instead of deleting the checkpoint.
+      // Why: Pi identity is resumable with no turn row and while idle after done, so manual
+      // sleep must promote both instead of deleting the checkpoint.
       records[existing.paneKey] = {
         ...existing,
         state: 'working',
@@ -721,9 +682,8 @@ export function collectHibernatedCompletionEvidenceForWorktree(
   return retained
 }
 
-// Why: the periodic resume-record capture re-runs on an interval; comparing
-// everything except capturedAt lets an unchanged agent skip the store write
-// entirely, so idle ticks never dirty the session persistence pipeline.
+// Why: comparing all fields except capturedAt lets an unchanged agent skip the store write,
+// so periodic idle re-captures never dirty session persistence.
 function sleepingRecordsEquivalentIgnoringCaptureTime(
   existing: SleepingAgentSessionRecord | undefined,
   next: SleepingAgentSessionRecord
@@ -872,8 +832,7 @@ function registryEntryMatchesStatus(args: {
     identity.launchToken !== undefined &&
     (args.launchToken === undefined || identity.launchToken !== args.launchToken)
   ) {
-    // Why: missing or mismatched launch tokens are stale launch proof even if a
-    // provider session id was reused by a later manual/mixed Codex run.
+    // Why: a missing/mismatched launch token is stale proof even if a later manual/mixed Codex run reused the provider session id.
     return false
   }
   if (identity.providerSession !== undefined) {
@@ -933,16 +892,13 @@ function getLaunchConfigForEntry(
     : undefined
 }
 
-// Why: the renderer twin of the main-process closedAgentStatusTabIds set that
-// #7561 FIFO-capped. It suppresses late hook/status events for a just-closed tab,
-// so it must outlive the tab briefly — but tabId is ephemeral and it was only
-// ever added to, growing one entry per tab-close for the renderer's whole life.
+// Why: renderer twin of main's #7561 FIFO-capped closedAgentStatusTabIds — suppresses late
+// events for a just-closed tab, but was add-only and grew unbounded, hence this cap.
 export const RECENTLY_CLOSED_AGENT_STATUS_TAB_IDS_MAX = 1024
 export const RECENTLY_RETIRED_AGENT_STATUS_PANE_KEYS_MAX = 1024
 
-// delete-then-set for LRU recency, then evict the oldest keys past the cap (Record
-// key order is insertion order for non-integer string keys). A status event for a
-// tab closed >MAX tabs ago cannot still arrive, so eviction is safe.
+// delete-then-set for LRU recency, then evict oldest keys past the cap (Record iterates
+// insertion order); safe because a status for a tab closed >MAX tabs ago cannot still arrive.
 function boundRecentlyClosedAgentStatusTabIds(
   existing: Record<string, true>,
   tabId: string
@@ -1099,19 +1055,13 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
   set,
   get
 ) => {
-  // Why: the freshness scheduler is intentionally process-lifetime-scoped —
-  // no dispose path — because it matches the store's own lifetime model
-  // (the zustand store is a module-level singleton that lives until process
-  // exit). Adding a teardown hook would require a store-dispose lifecycle
-  // that does not exist anywhere else in the codebase.
+  // Why: scheduler is process-lifetime-scoped (no dispose) because the store is a
+  // module-level singleton with no teardown lifecycle anywhere in the codebase.
   const freshness = createFreshnessScheduler({
     getEntries: () => Object.values(get().agentStatusByPaneKey),
     bumpEpochs: () => {
-      // Why: freshness is time-based, not event-based. Advancing these epochs
-      // at the exact stale boundary forces all freshness-aware selectors to
-      // recompute — and re-sorts WorktreeList — even when no new PTY output
-      // arrives. sortEpoch must bump in lockstep with agentStatusEpoch because
-      // a stale transition can legitimately change worktree ordering.
+      // Why: freshness is time-based — bump both epochs at the stale boundary to force selector
+      // recompute and re-sort even with no new output, since staleness can change worktree ordering.
       set((s) => ({
         agentStatusEpoch: s.agentStatusEpoch + 1,
         sortEpoch: s.sortEpoch + 1
@@ -1327,8 +1277,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
               }
               const nextEntry = { ...liveEntry, orchestration: merged }
               nextLive[paneKey] = nextEntry
-              // Why: only replace titles when labels match the live dispatch
-              // taskId; sticky completed context must not rename a later turn.
+              // Why: only replace titles when labels match the live dispatch taskId; sticky completed context must not rename a later turn.
               if (
                 (merged.displayName?.trim() || merged.taskTitle?.trim()) &&
                 orchestrationLabelsMatchLiveDispatch({
@@ -1524,8 +1473,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           agent,
           providerSession,
           prompt: '',
-          // Why: this is durable process/session identity, not visible turn
-          // state; a non-done value keeps cold restore eligible.
+          // Why: durable process/session identity, not visible turn state; a non-done value keeps cold restore eligible.
           state: 'working',
           capturedAt: updatedAt,
           updatedAt,
@@ -1554,9 +1502,8 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         if (nextRetained !== s.retainedAgentsByPaneKey) {
           delete nextRetained[paneKey]
         }
-        // Why: on identity mismatch the sleeping record drops its launch config,
-        // so a stale registry entry must be cleared too or a later return to the
-        // old provider identity could reuse stale args/env. Mirror setAgentStatus.
+        // Why: on identity mismatch the sleeping record drops its launch config, so clear the stale
+        // registry entry too, else a later return to the old identity reuses stale args/env.
         let nextLaunchConfigs = s.agentLaunchConfigByPaneKey
         if (registryMatches && registryEntry) {
           nextLaunchConfigs = {
@@ -1600,8 +1547,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
       const updatedAt = timing?.updatedAt ?? Date.now()
       if (
         paneKey in get().recentlyRetiredAgentStatusPaneKeys ||
-        // Why: a closed terminal tab is no longer a valid destination for hook
-        // replays or late status events, even if main still receives them.
+        // Why: a closed tab is no longer a valid destination for hook replays or late status events.
         isRecentlyClosedAgentStatusTab(
           get().recentlyClosedAgentStatusTabIds,
           getTabIdFromPaneKey(paneKey)
@@ -1614,24 +1560,17 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
       const generatedTitleEntry: { current: AgentStatusEntry | null } = { current: null }
       set((s) => {
         const existing = s.agentStatusByPaneKey[paneKey]
-        // Why: snapshots and live pushes share receivedAt from the same main-side
-        // lastStatusByPaneKey.set, so equal timestamps carry identical data. Strict <
-        // preserves live-after-live updates that land in the same millisecond.
+        // Why: snapshots and live pushes share one timestamp source, so equal timestamps carry
+        // identical data; strict < preserves same-millisecond live-after-live updates.
         if (existing && updatedAt < existing.updatedAt) {
           return s
         }
-        // Why: terminalTitle is identity-like — it labels the pane itself, not
-        // the current turn's activity. Preserve the prior value when a ping
-        // omits it so the pane label does not flicker out between hook events.
-        // Unlike the tool/prompt/assistant fields below (which legitimately
-        // clear on a fresh turn), a missing title means "no update", not "the
-        // pane has no title any more".
+        // Why: terminalTitle labels the pane itself, not the turn, so a missing title means "no update" —
+        // preserve the prior value to avoid flicker (unlike tool/prompt fields, which clear on a fresh turn).
         const effectiveTitle = terminalTitle ?? existing?.terminalTitle
 
-        // Why: build up a rolling log of state transitions so the dashboard can
-        // render activity blocks showing what the agent has been doing. Only push
-        // when the state actually changes to avoid duplicate entries from prompt-
-        // only updates within the same state.
+        // Rolling log of state transitions for the dashboard's activity blocks; push only on
+        // real state changes to avoid dupes from prompt-only pings within the same state.
         let history: AgentStateHistoryEntry[] = existing?.stateHistory ?? []
         if (existing && existing.state !== payload.state) {
           history = [
@@ -1639,13 +1578,9 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
             {
               state: existing.state,
               prompt: existing.prompt,
-              // Why: use stateStartedAt (not updatedAt) so the history row
-              // reflects when the state was first reported, not the most
-              // recent within-state ping (tool/prompt updates refresh
-              // updatedAt but not stateStartedAt).
+              // Why: use stateStartedAt (not updatedAt) so the row reflects when the state was first reported, not the latest within-state ping.
               startedAt: existing.stateStartedAt,
-              // Why: preserve the interrupt flag on the historical `done` entry
-              // so activity-block views can render past cancellations as such.
+              // Why: preserve the interrupt flag on the historical `done` entry so activity-block views can render past cancellations.
               interrupted: existing.interrupted
             }
           ]
@@ -1665,8 +1600,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           incoming: payload.agentType,
           now: updatedAt
         })
-        // Why: Command Code has no UserPromptSubmit; a fresh transcript prompt while
-        // still `working` is the smart-sort turn boundary.
+        // Why: Command Code has no UserPromptSubmit; a fresh transcript prompt while still `working` is the smart-sort turn boundary.
         const commandCodeNewTurn =
           existing !== undefined &&
           isCommandCodeNewTurnWhileWorking({
@@ -1681,11 +1615,8 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         const promptInteractionKey =
           payload.promptInteractionKey ??
           (payload.prompt === existing?.prompt ? existing?.promptInteractionKey : undefined)
-        // Why: prefer main's authoritative stateStartedAt when provided — main's
-        // attachStatusTiming preserves it across same-state pings (server.ts) and
-        // persists it across restart. Fall back to existing.stateStartedAt only when
-        // main did not send timing (legacy callers / OSC fallback path), and to
-        // updatedAt for a brand-new pane.
+        // Why: prefer main's authoritative stateStartedAt (attachStatusTiming persists it across
+        // same-state pings and restart); fall back to existing only when main sent no timing, updatedAt for a new pane.
         const stateStartedAt =
           timing?.stateStartedAt ??
           (commandCodeNewTurn
@@ -1704,11 +1635,8 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           return s
         }
 
-        // Why: tool/assistant fields come pre-merged from the main-process
-        // cache (see `resolveToolState` in server.ts), so the payload always
-        // carries the authoritative current snapshot — including clears on a
-        // fresh turn. Writing through directly (no existing fallback) is what
-        // lets a `UserPromptSubmit` reset clear stale tool lines in the UI.
+        // Why: tool/assistant fields arrive pre-merged and authoritative from main (resolveToolState
+        // in server.ts), so write them through directly — no fallback — so UserPromptSubmit clears stale tool lines.
         const runtimeOrchestration = s.runtimeAgentOrchestrationByPaneKey[paneKey]
         const runtimeMergedOrchestration = runtimeOrchestration
           ? mergeCurrentOrchestrationContext(existing?.orchestration, runtimeOrchestration)
@@ -1775,9 +1703,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           )
             ? existingSleepingRecord.launchConfig
             : undefined
-        // Why: pane keys can be reused after a manually-started agent replaces
-        // an Orca-launched one. Once the provider session changes, the old
-        // pane-key launch registry must not bleed options into the new session.
+        // Why: on a reused pane key, once the provider session changes the old launch registry must not bleed options into the new session.
         const launchConfigSource =
           (payload.state !== 'done' && !providerSessionChanged && metadata?.launchToken
             ? metadata?.launchConfig
@@ -1807,27 +1733,20 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           stateHistory: history,
           toolName: payload.toolName,
           toolInput: payload.toolInput,
-          // Why: full untruncated AskUserQuestion JSON; carried so mobile/web
-          // clients can render the live prompt card. parseAgentStatusPayload
-          // already clears it when the agent moves to a different tool/state.
+          // Why: full untruncated AskUserQuestion JSON so mobile/web can render the live prompt
+          // card; parseAgentStatusPayload clears it on tool/state change.
           interactivePrompt: payload.interactivePrompt,
           lastAssistantMessage: payload.lastAssistantMessage,
-          // Why: reused panes may start non-orchestrated work after runtime
-          // metadata expires. Only final done rows keep the previous lineage
-          // fallback so completed children stay grouped.
+          // Why: reused panes can start non-orchestrated work; only final done rows keep the
+          // previous lineage fallback so completed children stay grouped.
           orchestration,
-          // Why: reuse the previous array reference when the roster is
-          // unchanged so subscribers comparing by identity skip re-renders on
-          // high-frequency same-roster pings.
+          // Why: reuse the prior array ref when the roster is unchanged so identity-comparing subscribers skip re-renders.
           subagents: agentSubagentsEqual(existing?.subagents, payload.subagents)
             ? existing?.subagents
             : payload.subagents,
           ...(providerSession ? { providerSession } : {}),
           ...(promptInteractionKey ? { promptInteractionKey } : {}),
-          // Why: interrupted lives on `done` only. parseAgentStatusPayload
-          // already clamps it to `undefined` for non-done states, so writing
-          // the field through directly preserves truth for done and resets
-          // it when a new turn starts (working → Stop reprices it).
+          // Why: `interrupted` is done-only; parseAgentStatusPayload already clamps it for non-done states, so write it through directly.
           interrupted: payload.interrupted
         }
         generatedTitleEntry.current = entry
@@ -1838,37 +1757,16 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         ) {
           completionRefreshWorktreeId = entry.worktreeId ?? findAgentPaneWorktreeId(s, paneKey)
         }
-        // Why: broad freshness-aware subscribers only need a global tick when
-        // an entry appears, changes state, crosses stale->fresh, or receives
-        // a same-state `done` update that may carry the final assistant
-        // message for retained rows. Same-state working prompt/tool pings
-        // still update agentStatusByPaneKey for the owning row, but they must
-        // not fan out through dashboard/sidebar aggregate work across every
-        // card. Sort-relevant inputs are:
-        //   1. `state` transitions — smart-sort class is a function of state.
-        //   2. Freshness transitions (stale → fresh) — `resolveAttention` in
-        //      smart-attention.ts filters entries through
-        //      `isExplicitAgentStatusFresh(entry, now, AGENT_STATUS_STALE_AFTER_MS)`
-        //      (30-min TTL). A stale entry that refreshes with the SAME state
-        //      goes from "not contributing" (Class 4) to driving a higher
-        //      class — order must update. Snapshot hydration can pass an older
-        //      updatedAt; in that case the entry is still stored with its true
-        //      age, and selectors will immediately decay it if it is already
-        //      stale.
+        // Why: emit a global tick only when an entry appears, changes state, crosses stale→fresh,
+        // or is a same-state `done` update — same-state working pings must not fan out to aggregates.
         const wasFresh =
           !!existing && isExplicitAgentStatusFresh(existing, updatedAt, AGENT_STATUS_STALE_AFTER_MS)
-        // Why attribution is aggregate state: a late main-process stamp can
-        // change which workspace remains visible without changing agent state.
+        // Why: a late main-process attribution stamp can change which workspace stays visible without changing agent state.
         const attributionChanged =
           existing?.worktreeId !== entry.worktreeId || existing?.tabId !== entry.tabId
-        // Why: main is authoritative on stateStartedAt and only advances it on a
-        // real turn boundary (state transition or a Command Code new turn). If the
-        // renderer-local `commandCodeNewTurn` misses it — e.g. a transcript-read
-        // failure left `existing.promptInteractionKey` undefined so the key-change
-        // is invisible here — main's reset still arrives via `timing.stateStartedAt`.
-        // Treat a same-state stateStartedAt advance as sort-relevant so smart sort
-        // never goes stale. Non-Command-Code agents never advance stateStartedAt
-        // while the state is unchanged, so this stays effectively CC-scoped.
+        // Why: main can advance stateStartedAt on a same-state turn boundary the renderer
+        // missed; treat that as sort-relevant so smart sort never goes stale.
+        // Non-Command-Code agents never advance stateStartedAt at a fixed state, so this stays CC-scoped.
         const sameStateStateStartedAtChanged =
           !!existing &&
           existing.state === payload.state &&
@@ -1897,22 +1795,15 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
             entry.interrupted !== existing.interrupted)
         const retentionRelevantChange =
           sortRelevantChange || attributionChanged || doneRetentionFieldsChanged
-        // Why: a new status event means the agent is live again — lift any
-        // one-shot retention suppressor so the row can be retained normally
-        // on its next disappearance. setAgentStatus fires on every PTY status
-        // update (high frequency), so only clone retentionSuppressedPaneKeys
-        // when there is actually a suppressor to remove — otherwise every
-        // status ping would churn that map reference and force spurious
-        // re-renders in any subscriber selecting on it.
+        // Why: a fresh status means the agent is live again — lift its one-shot retention suppressor.
+        // Clone the map only when a suppressor exists, else every high-frequency ping churns the ref.
         const hasSuppressor = paneKey in s.retentionSuppressedPaneKeys
         let nextRetentionSuppressedPaneKeys = s.retentionSuppressedPaneKeys
         if (hasSuppressor) {
           nextRetentionSuppressedPaneKeys = { ...s.retentionSuppressedPaneKeys }
           delete nextRetentionSuppressedPaneKeys[paneKey]
         }
-        // Why: pane keys are reused by the same terminal pane across turns.
-        // Once a fresh live hook row arrives, any retained snapshot for that
-        // pane is stale and must not render beside the live row in the sidebar.
+        // Why: pane keys are reused across turns, so a fresh live row makes any retained snapshot stale — drop it so it doesn't render beside the live row.
         const hasRetainedSnapshot = paneKey in s.retainedAgentsByPaneKey
         const nextRetainedAgents = hasRetainedSnapshot
           ? { ...s.retainedAgentsByPaneKey }
@@ -1931,8 +1822,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         const liveRecoveryRecord = liveRecoveryWorktreeId
           ? sleepingRecordFromEntry({
               state: s,
-              // Why: a completed Pi turn leaves the TUI session alive. Keep
-              // resume identity active without representing done as pending work.
+              // Why: a completed Pi turn leaves the TUI session alive — keep resume identity active without representing done as pending work.
               entry: retainsPiRecoveryIdentity
                 ? { ...entry, state: 'working', prompt: '', lastAssistantMessage: undefined }
                 : entry,
@@ -1965,8 +1855,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
             }
           }
         }
-        // Why: launch tokens can remain in a shell after an Orca-started TUI exits;
-        // once the original session is done they must no longer authorize config reuse.
+        // Why: launch tokens can outlive an Orca-started TUI in the shell; once the session is done they must no longer authorize config reuse.
         if (
           (providerSessionChanged || entry.state === 'done') &&
           paneKey in s.agentLaunchConfigByPaneKey
@@ -2005,10 +1894,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
       }
       const entryForGeneratedTitle = generatedTitleEntry.current
       if (entryForGeneratedTitle) {
-        // Why: sticky orchestration (~30m) can outlive the dispatch turn.
-        // - Matching labels: replace so displayName upgrades the task preview.
-        // - Mismatched sticky taskId on a new dispatch preamble: replace so the
-        //   prior task's title does not stick across re-dispatch on the same pane.
+        // Why: sticky orchestration (~30m) can outlive the dispatch turn, so replace the title on matching labels or a re-dispatch's mismatched taskId.
         const hasMatchingOrchestrationLabels = Boolean(
           (entryForGeneratedTitle.orchestration?.displayName?.trim() ||
             entryForGeneratedTitle.orchestration?.taskTitle?.trim()) &&
@@ -2027,8 +1913,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         )
         const shouldReplaceGeneratedTitle =
           hasMatchingOrchestrationLabels || isNewDispatchAgainstStickyOrchestration
-        // Why: setAgentStatus is high-frequency. Only parse dispatch preambles when
-        // a title write is still possible (feature on + replace or first-write).
+        // Why: setAgentStatus is high-frequency, so only parse dispatch preambles when a title write is actually possible.
         const mayWriteGeneratedTitle =
           get().settings?.tabAutoGenerateTitle === true &&
           (shouldReplaceGeneratedTitle ||
@@ -2049,13 +1934,11 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           get().setGeneratedTabTitleFromAgentPrompt(paneKey, generatedTitlePrompt)
         }
       }
-      // Why: schedule after set completes so the timer reads the updated map.
-      // queueMicrotask avoids re-entry into the zustand store during set.
+      // Why: schedule via queueMicrotask after set so the timer reads the updated map without re-entering the store during set.
       queueMicrotask(() => freshness.schedule())
       if (completionRefreshWorktreeId) {
         const worktreeId = completionRefreshWorktreeId
-        // Why: agents can create a PR via `gh pr create`, bypassing Orca's
-        // create-PR flow and leaving a fresh "no PR" cache entry in place.
+        // Why: agents can create a PR via `gh pr create`, bypassing Orca's flow and leaving a stale "no PR" cache entry in place.
         queueMicrotask(() => get().refreshGitHubForWorktreeIfStale(worktreeId))
       }
     },
@@ -2117,19 +2000,13 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           s.migrationUnsupportedByPtyId,
           (entry) => entry.paneKey === paneKey
         )
-        // Why: acknowledgedAgentsByPaneKey is written per user-ack but owned
-        // lifecycle-wise by the pane — drop the ack entry in lockstep with the
-        // live-map entry so closed panes don't leave stale ack timestamps that
-        // could silently suppress "unvisited" signals on future paneKey
-        // collisions.
+        // Why: drop the ack entry with the pane so a future paneKey collision can't inherit a stale ack that suppresses "unvisited" signals.
         let nextAck = s.acknowledgedAgentsByPaneKey
         if (paneKey in nextAck) {
           nextAck = { ...nextAck }
           delete nextAck[paneKey]
         }
-        // Why: bump sortEpoch in lockstep with agentStatusEpoch — removing an
-        // agent can legitimately change worktree sort order, same rationale
-        // as setAgentStatus.
+        // Why: bump sortEpoch with agentStatusEpoch — removing an agent can change worktree sort order (same as setAgentStatus).
         return {
           agentStatusByPaneKey: next,
           agentLaunchConfigByPaneKey: nextLaunchConfigs,
@@ -2179,10 +2056,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
             delete nextAck[k]
           }
         }
-        // Why: bump sortEpoch in lockstep with agentStatusEpoch — removing
-        // agents can legitimately change worktree sort order, same rationale
-        // as setAgentStatus. The pre-check guards against spurious bumps when
-        // no keys matched the prefix.
+        // Why: bump sortEpoch with agentStatusEpoch — removing agents can change worktree sort order (same as setAgentStatus).
         return {
           agentStatusByPaneKey: next,
           agentLaunchConfigByPaneKey: nextLaunchConfigs,
@@ -2205,8 +2079,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
       set((s) => {
         let next: Record<string, AgentStatusEntry> | null = null
         for (const [paneKey, existing] of Object.entries(s.agentStatusByPaneKey)) {
-          // Why: undefined is an unstamped legacy/renderer-owned row. Its host
-          // cannot be proven, so normal pane teardown remains its safe cleanup.
+          // Why: undefined connectionId is an unstamped legacy/renderer-owned row whose host can't be proven, so leave it to normal pane teardown.
           if (existing.connectionId !== connectionId || existing.updatedAt > clearedAt) {
             continue
           }
@@ -2239,10 +2112,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
     },
 
     dropAgentStatus: (paneKey) => {
-      // Why: single sync read — zustand set is synchronous, so the value we
-      // observe inside the set callback is the same one we would re-read via
-      // get() immediately after. Capture it once from inside the callback
-      // rather than double-reading the store before and during set.
+      // Why: zustand set is synchronous, so capture liveExisted once inside the callback instead of double-reading the store.
       let liveExisted = false
       set((s) => {
         const hasLive = paneKey in s.agentStatusByPaneKey
@@ -2252,9 +2122,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           s.migrationUnsupportedByPtyId,
           (entry) => entry.paneKey === paneKey
         )
-        // See removeAgentStatus for rationale on ack cleanup. Apply this
-        // regardless of live/retained presence — the ack entry is owned by
-        // the pane lifecycle independently of live/retained state.
+        // See removeAgentStatus for ack-cleanup rationale; the ack entry is owned by the pane lifecycle regardless of live/retained state.
         let nextAck = s.acknowledgedAgentsByPaneKey
         if (paneKey in nextAck) {
           nextAck = { ...nextAck }
@@ -2267,13 +2135,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         if (hasLaunchConfig) {
           delete nextLaunchConfigs[paneKey]
         }
-        // Why: bail when there is genuinely nothing to do. The old guard
-        // `!hasLive && !hasRetained && alreadySuppressed` leaked a phantom
-        // suppressor write in the `!hasLive && !hasRetained && !alreadySuppressed`
-        // case. With the hasLive-gated suppressor below, a no-op drop on a
-        // paneKey with no live and no retained entry truly has nothing to
-        // change, so short-circuit here — but still flush a pending ack
-        // cleanup or launch-config cleanup if one is present.
+        // Why: short-circuit when there's nothing to change, but still flush a pending ack or launch-config cleanup if one is present.
         if (!hasLive && !hasRetained && !migrationUnsupported.changed) {
           if (hasLaunchConfig) {
             return {
@@ -2300,34 +2162,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           delete nextRetained[paneKey]
         }
 
-        // Why: explicit teardown means "the user is done with this row", so
-        // the next retention sync must not resurrect it from the previous frame.
-        //
-        // Why same-frame race is acceptable: if dropAgentStatus fires in the
-        // same React frame as setAgentStatus, before useRetainedAgentsSync's
-        // prevAgentsRef has captured the live entry, the planted suppressor
-        // may never be consumed by a live→gone transition and would persist.
-        // In practice suppressors are bounded by user-dismissed paneKeys (a
-        // small set), so the leak is pragmatically inert — accepting it is
-        // cheaper than threading frame-level ordering guarantees through the
-        // retention sync.
-        //
-        // Why gate on hasLive: the suppressor is a one-shot flag consumed by
-        // `collectRetainedAgentsOnDisappear` (useRetainedAgents.ts), which
-        // iterates the PREVIOUS render's LIVE agents to decide what to
-        // retain. If we dismiss a retained-only row (no live entry at drop
-        // time), no live→gone transition will ever fire for this paneKey, so
-        // the suppressor would never be consumed and would leak indefinitely
-        // — only clearing if the same paneKey later became live again via
-        // setAgentStatus. A retained-only dismissal just needs the retained
-        // entry removed; there is no live-agent resurrection risk to guard
-        // against. Only spread retentionSuppressedPaneKeys when hasLive.
-        //
-        // Why the `!(paneKey in s.retentionSuppressedPaneKeys)` check: if a
-        // suppressor is already present, re-spreading produces a new object
-        // reference with identical contents and spuriously re-renders any
-        // subscriber selecting on retentionSuppressedPaneKeys. Mirror the
-        // guard used in setAgentStatus.
+        // Why: explicit teardown must not let retention sync resurrect this row — plant a one-shot suppressor, but only when hasLive (a retained-only key has no live→gone transition to consume it, so it leaks) and not already present (re-spreading spuriously re-renders subscribers).
         const needsSuppressorWrite = hasLive && !(paneKey in s.retentionSuppressedPaneKeys)
 
         return {
@@ -2348,28 +2183,16 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
             : {}),
           agentStatusEpoch:
             hasLive || migrationUnsupported.changed ? s.agentStatusEpoch + 1 : s.agentStatusEpoch,
-          // Why: mirrors removeAgentStatus — dropping a live working/blocked
-          // agent changes its contribution to the worktree sort score, so the
-          // sidebar smart-sort must recompute. Without this bump, a user-
-          // initiated dismissal from the inline agents list would leave the
-          // sidebar ordering stale until some unrelated event repaired it.
+          // Why: mirrors removeAgentStatus — dropping a live agent changes its worktree sort score, so bump sortEpoch to recompute the sidebar smart-sort.
           sortEpoch: hasLive || migrationUnsupported.changed ? s.sortEpoch + 1 : s.sortEpoch
         }
       })
-      // Why: freshness.schedule only matters when the live map changed —
-      // retained-only and no-op drops don't touch it. Gate on the live
-      // presence observed inside set() so a noop drop on a paneKey with no
-      // live and no retained entry (or a retained-only dismissal) skips the
-      // microtask.
+      // Why: freshness.schedule only matters when the live map changed, so gate on the live presence observed inside set() — no-op/retained-only drops skip it.
       if (liveExisted) {
         queueMicrotask(() => freshness.schedule())
       }
-      // Why: propagate the dismissal to the main-process hook cache so the
-      // on-disk last-status file evicts this paneKey on the next debounced
-      // write. Without this, the main process would re-hydrate the dismissed
-      // entry on the next launch and the row would re-appear. Fire-and-forget.
-      // Why: the typeof window guard keeps the slice usable from the
-      // node test environment, where window is undefined.
+      // Why: propagate the dismissal to the main-process hook cache so the on-disk cache doesn't re-hydrate this row on next launch. Fire-and-forget.
+      // Why: the typeof window guard keeps the slice usable from the node test env, where window is undefined.
       if (typeof window !== 'undefined') {
         window.api?.agentStatus?.drop?.(paneKey)
       }
@@ -2400,9 +2223,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           s.migrationUnsupportedByPtyId,
           (entry) => entry.paneKey?.startsWith(prefix) ?? false
         )
-        // See removeAgentStatus for rationale on ack cleanup. Apply this
-        // regardless of live/retained presence — ack entries are owned by
-        // the pane lifecycle independently of live/retained state.
+        // See removeAgentStatus for ack-cleanup rationale; ack entries are owned by the pane lifecycle regardless of live/retained state.
         let nextAck = s.acknowledgedAgentsByPaneKey
         const ackKeys = Object.keys(nextAck).filter(
           (k) => k.startsWith(prefix) || completedOrphanKeySet.has(k)
@@ -2461,24 +2282,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           delete nextRetained[key]
         }
 
-        // Why: plant suppressors only for paneKeys that had a live entry,
-        // mirroring the hasLive gate in dropAgentStatus — suppressors are
-        // one-shot flags consumed by collectRetainedAgentsOnDisappear on a
-        // live→gone transition, so a suppressor on a retained-only paneKey
-        // would leak because no such transition will ever fire. Also skip
-        // keys that are already suppressed so we don't spuriously reallocate
-        // the suppressor map for subscribers that select on its identity.
-        //
-        // Same-frame race: if a hook ping promotes working→done in the same
-        // render frame as teardown, the next retention-sync run sees the entry
-        // as `done` in prevAgents and surfaces it in retained — even though
-        // the user just tore it down. Planting suppressors is the cheap guard
-        // for the common ordering; the rare inverse ordering has the same
-        // bounded suppressor-leak tradeoff described in dropAgentStatus.
-        //
-        // Skip completed-orphan keys: their tab is already gone, so retention
-        // sync never snapshots them and no live→gone transition ever fires to
-        // consume the suppressor — planting one would leak permanently.
+        // Why: a suppressor is only consumed on a live→gone transition, so plant one only for live paneKeys and skip already-suppressed and completed-orphan keys — otherwise it leaks (mirrors dropAgentStatus).
         const suppressorAdds = liveKeys.filter(
           (k) => !completedOrphanKeySet.has(k) && !(k in s.retentionSuppressedPaneKeys)
         )
@@ -2501,9 +2305,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           ...(nextAck !== s.acknowledgedAgentsByPaneKey
             ? { acknowledgedAgentsByPaneKey: nextAck }
             : {}),
-          // Why: mirrors removeAgentStatusByTabPrefix — only bump the live-map
-          // epoch / sortEpoch when the live map actually changed. Retained-only
-          // sweeps do not participate in smart-sort or freshness calculations.
+          // Why: mirrors removeAgentStatusByTabPrefix — only bump epochs when the live map changed; retained-only sweeps don't affect sort/freshness.
           agentStatusEpoch:
             hadLive || migrationUnsupported.changed ? s.agentStatusEpoch + 1 : s.agentStatusEpoch,
           sortEpoch: hadLive || migrationUnsupported.changed ? s.sortEpoch + 1 : s.sortEpoch
@@ -2680,10 +2482,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           }
         }
         const retainedEvidenceKeys = new Set(retainedEvidence.keys())
-        // See removeAgentStatus for rationale on ack cleanup. Current tabs are
-        // swept by prefix; attributed live rows and orphan retained rows are
-        // swept by their retained/lifecycle key. Auto-hibernated completion
-        // evidence keeps its read state so a slept card does not turn bold again.
+        // See removeAgentStatus for ack-cleanup rationale; auto-hibernated completion evidence keeps its read state so a slept card doesn't turn bold again.
         let nextAck = s.acknowledgedAgentsByPaneKey
         const ackKeys = Object.keys(nextAck).filter(
           (k) =>
@@ -2698,10 +2497,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
             delete nextAck[key]
           }
         }
-        // Mirror dropAgentStatusByTabPrefix: when nothing live or retained
-        // changed, narrow the return to just the ack delta (or s) so we don't
-        // emit a new top-level state object that re-renders full-state
-        // subscribers for nothing.
+        // Mirror dropAgentStatusByTabPrefix: when nothing live/retained changed, return just the ack delta (or s) to avoid full-state re-renders.
         if (
           liveKeys.length === 0 &&
           launchConfigKeys.length === 0 &&
@@ -2744,10 +2540,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           }
         }
 
-        // Why: normal worktree teardown folds the surface, so live rows need
-        // suppressors. Auto-hibernated `done` rows become retained evidence
-        // immediately, so suppressing those same pane keys would erase them on
-        // the next retention sync.
+        // Why: suppress live rows on teardown, but skip auto-hibernated `done` rows — they become retained evidence a suppressor would erase next sync.
         const suppressorAdds = liveKeys.filter(
           (k) => !retainedEvidenceKeys.has(k) && !(k in s.retentionSuppressedPaneKeys)
         )
@@ -2804,8 +2597,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
     },
 
     captureAllSleepingAgentSessions: (mode) => {
-      // Why: both periodic crash checkpoints and quit flushes persist live
-      // provider ids, but only a confirmed quit may claim quit precedence.
+      // Why: periodic checkpoints and quit flushes both persist provider ids, but only a confirmed quit may claim quit precedence.
       set((s) => {
         const capturedAt = Date.now()
         const origin = mode === 'quit' ? ('quit' as const) : ('live' as const)
@@ -2842,8 +2634,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
             origin
           })
           const existing = next[entry.paneKey]
-          // Why: a timer racing confirmed window close must not downgrade its
-          // shutdown snapshot; a new live hook event supersedes it elsewhere.
+          // Why: a periodic timer must not downgrade a confirmed-quit shutdown snapshot; a live hook event supersedes it elsewhere.
           if (
             mode === 'periodic' &&
             existing?.origin === 'quit' &&
@@ -2923,20 +2714,12 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
     },
 
     retainAgents: (entries) => {
-      // Why: retained entries are a pure read-overlay — consumers read
-      // retainedAgentsByPaneKey directly each render, so no sort/status epoch
-      // bump is needed. Retention does not participate in sort ordering.
-      // Batching into a single set(...) keeps multi-agent disappearance atomic.
+      // Why: retained entries are a pure read-overlay (no epoch bump needed); batch into one set so multi-agent disappearance is atomic.
       if (entries.length === 0) {
         return
       }
       set((s) => {
-        // Why: skip the allocation + set(...) entirely when every input entry
-        // is already present by reference. Consumers of retainedAgentsByPaneKey
-        // select on its identity (the inline agents list), so a spurious map
-        // reallocation forces re-renders even when nothing changed. Mirrors
-        // the identity-preservation pattern used by pruneRetainedAgents and
-        // clearRetentionSuppressedPaneKeys.
+        // Why: skip reallocation when every entry is already present by reference — consumers select on map identity, so a spurious realloc forces re-renders.
         let changed = false
         for (const retained of entries) {
           if (s.retainedAgentsByPaneKey[retained.entry.paneKey] !== retained) {
@@ -2957,51 +2740,24 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
             mergedOrchestration !== retained.entry.orchestration
               ? { ...retained.entry, orchestration: mergedOrchestration }
               : retained.entry
-          // Why: INVARIANT — the map key equals retained.entry.paneKey. This
-          // lets callers look up a retained row by the same paneKey they use
-          // for agentStatusByPaneKey and keeps dismissal (dismissRetainedAgent)
-          // keyed on a single identifier. collectRetainedAgentsOnDisappear
-          // relies on this invariant too: it checks
-          // `retainedAgentsByPaneKey[paneKey]` to decide whether a vanished
-          // agent is already retained.
+          // INVARIANT: map key equals retained.entry.paneKey, so callers look up retained rows by the same paneKey as agentStatusByPaneKey.
           next[retained.entry.paneKey] =
             entry === retained.entry ? retained : { ...retained, entry }
         }
-        // Why: bound the map so a long multi-agent session cannot leak the
-        // renderer heap. retainAgents is the only path that grows it, so
-        // capping here is sufficient; evicts oldest-retained first.
+        // Why: cap the map so a long multi-agent session can't leak the renderer heap (retainAgents is the only growth path); evicts oldest-retained first.
         return { retainedAgentsByPaneKey: capRetainedAgents(next) }
       })
     },
 
     dismissRetainedAgent: (paneKey) => {
-      // Why: no agentStatusEpoch / sortEpoch bump here (mirrors retainAgents).
-      // Retained rows are a pure read-overlay on top of agentStatusByPaneKey —
-      // they do not contribute to smart-sort class resolution (see
-      // resolveAttention in smart-attention.ts, which reads
-      // agentStatusByPaneKey only) and dashboard
-      // selectors re-render on retainedAgentsByPaneKey identity changes
-      // directly. Bumping epochs would force sidebar re-sorts and selector
-      // recomputations for a change that cannot affect either result.
+      // Why: no epoch bump (mirrors retainAgents) — retained rows are a pure read-overlay that don't affect smart-sort; selectors re-render on map identity.
       set((s) => {
         if (!(paneKey in s.retainedAgentsByPaneKey)) {
           return s
         }
         const next = { ...s.retainedAgentsByPaneKey }
         delete next[paneKey]
-        // Why: mirror dropAgentStatus's hasLive-gated suppressor. If the same
-        // paneKey has BOTH a retained entry AND a concurrent live entry, simply
-        // removing the retained row leaves the live entry free to vanish
-        // cleanly on its next disappearance — and because
-        // collectRetainedAgentsOnDisappear (useRetainedAgents.ts) only skips
-        // paneKeys that are currently in retainedAgentsByPaneKey, the
-        // just-dismissed row would be resurrected by a new retention snapshot.
-        // Plant a one-shot suppressor so the next live→gone transition for
-        // this paneKey is ignored by the retention sync.
-        //
-        // Gate on `paneKey in agentStatusByPaneKey`: with no live entry there
-        // is no live→gone transition to guard against, and a stray suppressor
-        // would leak indefinitely (same rationale as dropAgentStatus).
+        // Why: mirror dropAgentStatus — plant a one-shot suppressor only when a live entry coexists, so the retention sync doesn't resurrect this dismissed row (gate on hasLive, else it leaks).
         const hasLive = paneKey in s.agentStatusByPaneKey
         if (!hasLive || paneKey in s.retentionSuppressedPaneKeys) {
           return { retainedAgentsByPaneKey: next }
@@ -3017,27 +2773,12 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
     },
 
     dismissRetainedAgentsByWorktree: (worktreeId) => {
-      // Why: collect inside set so we capture the exact paneKeys removed
-      // (worktree filter is applied here). After the synchronous set()
-      // returns, fan out a window.api.agentStatus.drop per removed key so
-      // the main-process hook cache (and on-disk last-status file) eviction
-      // matches the renderer's removal. Without this, the on-disk cache
-      // would resurrect the dismissed rows on the next launch.
+      // Why: collect removed paneKeys inside set, then fan out window.api drop so the on-disk cache doesn't resurrect the dismissed rows on next launch.
       const dismissedPaneKeys: string[] = []
       set((s) => {
         let changed = false
         const next: Record<string, RetainedAgentEntry> = {}
-        // Why: mirror dismissRetainedAgent's hasLive-gated suppressor logic.
-        // When a dismissed paneKey ALSO has a concurrent live entry in
-        // agentStatusByPaneKey, removing the retained row alone lets the next
-        // live→gone transition for that paneKey re-retain the row via the
-        // retention sync (collectRetainedAgentsOnDisappear only skips paneKeys
-        // currently present in retainedAgentsByPaneKey). Without planting a
-        // suppressor here, "Dismiss all" for a worktree would silently
-        // resurrect the just-dismissed rows as soon as the live agents
-        // disappeared. Only plant suppressors for the hasLive subset — a stray
-        // suppressor on a retained-only paneKey would leak indefinitely
-        // because no live→gone transition would ever consume it.
+        // Why: mirror dismissRetainedAgent — plant a suppressor only for dismissed paneKeys that also have a live entry, else the next live→gone transition re-retains the row (a retained-only suppressor leaks).
         const toSuppress: string[] = []
         for (const [key, ra] of Object.entries(s.retainedAgentsByPaneKey)) {
           if (ra.worktreeId === worktreeId) {
@@ -3073,12 +2814,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
     },
 
     pruneRetainedAgents: (validWorktreeIds) => {
-      // Why: deliberately does NOT sweep retentionSuppressedPaneKeys for
-      // pruned worktrees. PaneKeys are minted fresh when a worktree is
-      // re-created (worktrees keep unique tab IDs), so stale suppressors
-      // keyed on pruned paneKeys can never be matched by a future live entry
-      // — they are inert and harmless. Sweeping them would add churn for no
-      // observable benefit.
+      // Why: intentionally leaves retentionSuppressedPaneKeys — paneKeys are minted fresh on worktree re-create, so stale suppressors can never match a future live entry.
       set((s) => {
         let changed = false
         const next: Record<string, RetainedAgentEntry> = {}
diff --git a/src/renderer/src/store/slices/browser.ts b/src/renderer/src/store/slices/browser.ts
index ea4d2e0ebb3..fcc58a5fd83 100644
--- a/src/renderer/src/store/slices/browser.ts
+++ b/src/renderer/src/store/slices/browser.ts
@@ -61,15 +61,9 @@ type CreateBrowserTabOptions = {
   title?: string
   sessionProfileId?: string | null
   sessionPartition?: string | null
-  // Why: callers like "Open Preview to the Side" need to place the new browser
-  // tab in a specific (sibling or newly-split) group rather than the ambient
-  // active group. Defaults to the worktree's current active group.
+  // Place the new tab in a specific group (e.g. "Open Preview to the Side"); defaults to the worktree's active group.
   targetGroupId?: string
-  // Why: the explicit "New Tab" action (keyboard shortcut, + button) should
-  // land the user in the address bar even when their configured home page is a
-  // real URL, so they can type a destination immediately. Link-opened tabs
-  // (context menu, window.open, http link routing) leave this unset so focus
-  // stays on the webview. When omitted, we fall back to the blank-URL check.
+  // Explicit "New Tab" focuses the address bar even with a real home URL; link-opened tabs leave it unset.
   focusAddressBar?: boolean
   browserRuntimeEnvironmentId?: string | null
 }
@@ -103,8 +97,7 @@ function sanitizeBrowserPageAnnotation(annotation: BrowserPageAnnotation): Brows
         : annotation.comment,
     payload: {
       ...annotation.payload,
-      // Why: annotations live in persisted renderer state; screenshots are
-      // transient copy payloads and can retain megabytes per note.
+      // Why: annotations persist to disk; null the transient screenshot to avoid retaining megabytes per note.
       screenshot: null
     }
   }
@@ -145,14 +138,7 @@ export type BrowserSlice = {
   closeBrowserPage: (pageId: string) => void
   reopenClosedBrowserPage: (workspaceId: string) => BrowserPage | null
   setActiveBrowserPage: (workspaceId: string, pageId: string) => void
-  // Why: scoped sibling of setActiveBrowserTab+setActiveBrowserPage that
-  // never yanks the user across worktrees. Multiple agents can drive
-  // browsers in parallel worktrees; a global focus call from agent X would
-  // steal the screen from the user reading agent Y. Updates per-worktree
-  // active tab/page unconditionally; updates the GLOBAL active tab and (if
-  // surfacePane) global activeTabType only when worktreeId === active
-  // worktree. Cross-worktree calls pre-stage the targeted worktree's view
-  // for whenever the user next switches to it.
+  // Focus that never yanks the user across worktrees: per-worktree slots always update, globals only when targeting the active worktree.
   focusBrowserTabInWorktree: (
     worktreeId: string,
     browserPageId: string,
@@ -231,10 +217,7 @@ function normalizeUrl(url: string): string {
   if (trimmed.length === 0) {
     return 'about:blank'
   }
-  // Why: setBrowserPageUrl is the single sink for URL updates from did-navigate,
-  // CDP navigation-update IPC, and direct address-bar submits. Redact at this
-  // boundary so the Kagi bearer token cannot reach BrowserPage.url, which is
-  // persisted to disk via the workspace session writer.
+  // Why: redact at this single URL sink so the Kagi bearer token can't reach BrowserPage.url, which is persisted to disk.
   return redactKagiSessionToken(trimmed)
 }
 
@@ -246,10 +229,7 @@ function normalizeBrowserTitle(title: string | null | undefined, url: string): s
     title === ORCA_BROWSER_BLANK_URL ||
     !title
   ) {
-    // Why: blank pages render through Orca's inert data: URL guest. Persisting
-    // that internal bootstrap URL as the page/workspace title leaks an
-    // implementation detail into the tab strip and makes every blank page look
-    // broken. Keep the user-facing label stable as "New Tab" instead.
+    // Why: don't surface the internal blank-guest URL as a title (leaks an impl detail, looks broken); show "New Tab" instead.
     return 'New Tab'
   }
   return title
@@ -324,9 +304,7 @@ function buildBrowserPage(
     worktreeId,
     url: normalizedUrl,
     title: normalizeBrowserTitle(title, normalizedUrl),
-    // Why: blank pages mount an inert guest first. Treating them as loading
-    // would make an empty workspace flash the global loading affordance even
-    // though no real navigation happened yet.
+    // Why: blank pages mount an inert guest (no real navigation); marking them loading would flash the loading affordance.
     loading: normalizedUrl !== 'about:blank' && normalizedUrl !== ORCA_BROWSER_BLANK_URL,
     faviconUrl: null,
     canGoBack: false,
@@ -514,9 +492,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       options?.title,
       options?.browserRuntimeEnvironmentId
     )
-    // Why: when no explicit profile is passed, inherit the user's chosen default
-    // profile. This lets users set a preferred profile in Settings that all new
-    // browser tabs use automatically.
+    // Why: with no explicit profile, inherit the user's default so a Settings preference applies to new tabs.
     const sessionProfileId =
       options?.sessionProfileId !== undefined
         ? options.sessionProfileId
@@ -639,10 +615,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
           return
         }
       } catch (error) {
-        // Why: a remote-owned workspace must NOT silently fall back to a local
-        // desktop browser tab — that creates confusing split ownership. Headless
-        // remotes that support browser panes advertise browser.headless.v1 and
-        // succeed above; if creation fails, surface it instead of going local.
+        // Why: browser.headless.v1 remotes succeed above, so a failure here is real; surface it instead of a confusing local-tab fallback (split ownership).
         console.warn(
           '[browser] remote browser tab creation failed:',
           error instanceof Error ? error.message : String(error)
@@ -798,10 +771,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
 
   shutdownWorktreeBrowsers: async (worktreeId) => {
     const workspaces = get().browserTabsByWorktree[worktreeId] ?? []
-    // Why: snapshot pre-loop so the post-loop set() can reproduce the original
-    // `hadBrowserTabs` semantics. Reading `s.browserTabsByWorktree[worktreeId]`
-    // inside set() would always be empty here because each closeBrowserTab call
-    // above has already removed the workspace from that array.
+    // Why: snapshot before the loop — closeBrowserTab empties the array, so set() below couldn't recompute hadBrowserTabs.
     const hadBrowserTabs = workspaces.length > 0
     for (const workspace of workspaces) {
       destroyWorkspaceWebviews(get().browserPagesByWorkspace, workspace.id)
@@ -812,10 +782,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       delete nextBrowserTabsByWorktree[worktreeId]
       const nextActiveBrowserTabIdByWorktree = { ...s.activeBrowserTabIdByWorktree }
       delete nextActiveBrowserTabIdByWorktree[worktreeId]
-      // Why: mirror shutdownWorktreeTerminals' `hadBrowserTabs && isActive`
-      // guard. Only reset the globally-visible active browser surface when the
-      // worktree being shut down is the one the user is looking at AND it
-      // actually had browser tabs to tear down.
+      // Why: reset the global browser surface only when the shut-down worktree is the active one AND had tabs.
       const shouldResetGlobalBrowser = s.activeWorktreeId === worktreeId && hadBrowserTabs
       return {
         browserTabsByWorktree: nextBrowserTabsByWorktree,
@@ -828,8 +795,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   reopenClosedBrowserTab: (worktreeId) => {
-    // Why: read and pop atomically inside set() to prevent a TOCTOU race
-    // where two rapid Cmd+Shift+T presses both restore the same entry.
+    // Why: read and pop atomically inside set() so two rapid Cmd+Shift+T presses can't both restore the same entry (TOCTOU).
     let entryToRestore: ClosedBrowserWorkspaceSnapshot | undefined
 
     set((s) => {
@@ -865,8 +831,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       return get().browserTabsByWorktree[worktreeId]?.find((tab) => tab.id === restored.id) ?? null
     }
 
-    // Why: create the tab with the first page, then append the rest in
-    // original order so multi-page workspaces preserve their page sequence.
+    // Why: append remaining pages in original order so multi-page workspaces preserve their page sequence.
     const [firstPage, ...restPages] = pages
     const restored = get().createBrowserTab(worktreeId, firstPage.url, {
       title: firstPage.title,
@@ -884,8 +849,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       })
     }
 
-    // Why: duplicate URLs are valid browser pages; restoring by URL can select
-    // the wrong copy. The restore path preserves page order, so map by index.
+    // Why: duplicate URLs are valid, so matching by URL can pick the wrong copy; restore preserves order, so map by index.
     const activePageId = snap.activePageId
     if (activePageId) {
       const restoredPages = get().browserPagesByWorkspace[restored.id] ?? []
@@ -919,10 +883,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       }
     })
 
-    // Why: notify the CDP bridge which guest webContents is now active so
-    // subsequent agent commands (snapshot, click, etc.) target the correct tab.
-    // registerGuest uses page IDs (not workspace IDs), so we resolve the active
-    // page within the workspace to find the correct browserPageId.
+    // Why: notify the CDP bridge of the active guest; it keys on page IDs not workspace IDs, so resolve the workspace's active page.
     const workspace = findWorkspace(get().browserTabsByWorktree, tabId)
     if (
       workspace?.activePageId &&
@@ -1111,8 +1072,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   reopenClosedBrowserPage: (workspaceId) => {
-    // Why: read and pop atomically inside set() to prevent a TOCTOU race
-    // where two rapid Cmd+Shift+T presses both restore the same page.
+    // Why: read and pop atomically inside set() so two rapid Cmd+Shift+T presses can't both restore the same page (TOCTOU).
     let pageToRestore: BrowserPage | undefined
 
     set((s) => {
@@ -1167,8 +1127,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       }
     })
 
-    // Why: switching the active page within a workspace changes which guest
-    // webContents the CDP bridge should target for agent commands.
+    // Why: switching the active page changes which guest webContents the CDP bridge targets for agent commands.
     if (
       !isRuntimeEnvironmentActive(get()) &&
       typeof window !== 'undefined' &&
@@ -1190,37 +1149,24 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   focusBrowserTabInWorktree: (worktreeId, browserPageId, options) => {
-    // Why: bridge identifies the target by browserPageId (CDP page id stored
-    // on BrowserPage.id), but the renderer's tab strip activates a workspace
-    // (BrowserWorkspace.id, a local UUID). They diverge whenever a workspace
-    // owns more than one page. Walk pageIds in the targeted worktree's tab
-    // list to find the owning workspace.
+    // Why: bridge targets a browserPageId but tabs activate a workspace; find the owning workspace (they differ for multi-page tabs).
     const tabsForWorktree = get().browserTabsByWorktree[worktreeId] ?? []
     const workspace = tabsForWorktree.find((tab) => (tab.pageIds ?? []).includes(browserPageId))
     if (!workspace) {
-      // Best-effort: state for this worktree may not be hydrated yet, or the
-      // page closed between the bridge switching and this IPC arriving.
+      // Best-effort: worktree state may not be hydrated yet, or the page closed between bridge switch and this IPC arriving.
       return
     }
-    // Default to true: the only caller (`tab switch --focus` IPC listener)
-    // wants the pane surfaced when targeting the active worktree. `false` is
-    // an opt-out for hypothetical pure-pre-staging callers.
+    // Default true: the only caller (tab switch --focus) wants the pane surfaced; false is an opt-out for pre-staging callers.
     const surfacePane = options?.surfacePane ?? true
     const pages = get().browserPagesByWorkspace[workspace.id] ?? []
     const nextWorkspace = mirrorWorkspaceFromActivePage(
       { ...workspace, activePageId: browserPageId },
       pages
     )
-    // TODO: per-worktree writes below duplicate setActiveBrowserTab /
-    // setActiveBrowserPage. We can't reuse those because they touch globals
-    // unconditionally (the very behavior --focus is avoiding). If they ever
-    // grow side-effects (analytics, persistence) those will silently diverge
-    // here. Consider extracting a private per-worktree-only helper that
-    // both call paths share.
+    // TODO: duplicates setActiveBrowserTab/Page; can't reuse (they touch globals unconditionally). Extract a per-worktree-only helper.
     set((s) => {
       const isActiveWorktree = s.activeWorktreeId === worktreeId
-      // Per-worktree slots: always update (safe pre-staging; only visible
-      // when user navigates to this worktree).
+      // Per-worktree slots: always update — safe pre-staging, only visible when user navigates here.
       const nextTabsByWorktree = {
         ...s.browserTabsByWorktree,
         [worktreeId]: tabsForWorktree.map((tab) => (tab.id === workspace.id ? nextWorkspace : tab))
@@ -1232,8 +1178,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       const nextActiveTabTypeByWorktree = surfacePane
         ? { ...s.activeTabTypeByWorktree, [worktreeId]: 'browser' as const }
         : s.activeTabTypeByWorktree
-      // Globals: only mutate when the targeted worktree is currently active.
-      // This is the line that keeps cross-worktree --focus calls silent.
+      // Globals: mutate only when the targeted worktree is active — keeps cross-worktree --focus silent.
       return {
         browserTabsByWorktree: nextTabsByWorktree,
         activeBrowserTabIdByWorktree: nextActiveTabIdByWorktree,
@@ -1243,9 +1188,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       }
     })
 
-    // Why: notify the CDP bridge which guest webContents is now active so
-    // subsequent agent commands target the correct page. Mirrors the
-    // notifyActiveTabChanged calls in setActiveBrowserTab/setActiveBrowserPage.
+    // Why: notify the CDP bridge which guest webContents is active so agent commands target the correct page.
     if (
       !isRuntimeEnvironmentActive(get()) &&
       typeof window !== 'undefined' &&
@@ -1254,9 +1197,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       window.api.browser.notifyActiveTabChanged({ browserPageId }).catch(() => {})
     }
 
-    // Why: keep the unified-tab strip's active entry in sync within the
-    // targeted worktree. activateTab only mutates per-worktree slices, so
-    // it's safe to call cross-worktree without yanking the user.
+    // Why: sync the unified-tab strip's active entry; activateTab only mutates per-worktree slices, so it's cross-worktree-safe.
     const item = (get().unifiedTabsByWorktree[worktreeId] ?? []).find(
       (entry) => entry.contentType === 'browser' && entry.entityId === workspace.id
     )
@@ -1431,8 +1372,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       if (!workspace) {
         return s
       }
-      // Why: annotations point at DOM coordinates from one loaded document.
-      // A real URL change invalidates those markers and copied context.
+      // Why: annotations point at DOM coords of the loaded document; a real URL change invalidates those markers.
       const shouldClearAnnotations = normalizeUrl(page.url) !== nextUrl
       const nextPages = (s.browserPagesByWorkspace[workspace.id] ?? []).map((entry) =>
         entry.id === pageId
@@ -1497,10 +1437,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
     return removedHandle
   },
 
-  // viewportPresetId is a per-page setting on BrowserPage and is intentionally not
-  // mirrored onto BrowserWorkspace: the outer tab strip doesn't surface the preset,
-  // so there's no UI consumer at the workspace layer. Keeping it page-local avoids
-  // cross-layer plumbing; do NOT add mirrorWorkspaceFromActivePage here.
+  // viewportPresetId is intentionally page-local (no workspace-layer UI consumer); do NOT add mirrorWorkspaceFromActivePage here.
   setBrowserPageViewportPreset: (pageId, viewportPresetId) =>
     set((s) => {
       const page = findPage(s.browserPagesByWorkspace, pageId)
@@ -1576,12 +1513,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
     }
     addAdditionalValidWorkspaceKeys(validWorktreeIdsForCleanup, options)
 
-    // Why: mirror closeBrowserTab's contract — reducers are pure, imperative
-    // side effects bracket them. Compute dropped workspaces first, destroy
-    // their webviews, then run the state reducer unchanged. hydrate is called
-    // once at boot (App.tsx) when the webview registry is empty, so this loop
-    // is a no-op today; it's defense-in-depth for any future caller that
-    // re-hydrates after webviews are live.
+    // Why: destroy dropped workspaces' webviews before the pure reducer; no-op today (boot registry empty), defends future re-hydration callers.
     const droppedWorkspaceIds: string[] = []
     for (const [worktreeId, tabs] of Object.entries(persistedTabsByWorktree)) {
       if (!validWorktreeIdsForCleanup.has(worktreeId)) {
diff --git a/src/renderer/src/store/slices/diffComments.ts b/src/renderer/src/store/slices/diffComments.ts
index 5e0f4b82cec..ce11b5b4eb6 100644
--- a/src/renderer/src/store/slices/diffComments.ts
+++ b/src/renderer/src/store/slices/diffComments.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: this slice keeps optimistic note
-mutation, rollback, persistence ordering, and sent-state transitions together
-so every write follows the same queue and rollback invariants. */
+/* eslint-disable max-lines -- Why: keeps note mutation, rollback, persistence ordering, and sent-state transitions under shared queue/rollback invariants. */
 import type { StateCreator } from 'zustand'
 import type { AppState } from '../types'
 import type { DiffComment, Worktree } from '../../../../shared/types'
@@ -87,12 +85,7 @@ function deliverySnapshotMatches(
   )
 }
 
-// Why: return a stable reference when no comments exist so selectors don't
-// produce a fresh `[]` on every store update. A new array identity would
-// trigger re-renders in any consumer using referential equality.
-// Frozen + typed `readonly` so an accidental `list.push(...)` on the returned
-// value is both a runtime TypeError and a TypeScript compile error, preventing
-// the sentinel from being corrupted globally.
+// Why: one shared frozen sentinel so selectors don't return a fresh [] (avoids re-renders); freezing stops a stray push corrupting the shared instance for every consumer.
 const EMPTY_COMMENTS: readonly DiffComment[] = Object.freeze([])
 
 async function persist(
@@ -123,25 +116,11 @@ function settingsForWorktreeOwner(state: AppState, worktreeId: string): AppState
     : ({ activeRuntimeEnvironmentId: runtimeEnvironmentId } as AppState['settings'])
 }
 
-// Why: IPC writes from `persist` are not ordered with respect to each other.
-// If two mutations (e.g. rapid add then delete, or two adds) are in flight
-// concurrently, their `updateMeta` resolutions can arrive out of call order,
-// letting an older snapshot overwrite a newer one on disk. We serialize per
-// worktree so only one write runs at a time. We also defer reading the
-// snapshot until the queued work actually starts — at dequeue time we pull
-// the LATEST `diffComments` from the store — which collapses a burst of N
-// mutations into at most 2 in-flight writes per worktree (1 running + 1
-// queued) and guarantees the last disk write reflects the newest state.
+// Why: IPC writes aren't ordered, so serialize per worktree to stop an older snapshot from overwriting a newer one on disk.
 const persistQueueByWorktree: Map<string, Promise<void>> = new Map()
 
-// Why: chain each new write onto the prior promise for this worktree so
-// writes land in call order. We use `.then(..., ..)` with both handlers so a
-// failing previous write doesn't break the chain — we still proceed with the
-// next write. The queued work reads the latest list from the store via
-// `get()` at dequeue time (not via a captured parameter) so it writes the
-// most recent snapshot rather than a stale one from when it was enqueued.
-// The returned promise resolves/rejects when THIS specific write commits so
-// callers can preserve their optimistic-update + rollback flow.
+// Why: chain each write onto the prior promise so writes land in call order; both then handlers keep the chain alive past a failure.
+// Why: queued work reads the latest list at dequeue time, and the returned promise settles for THIS write so callers can roll back.
 function enqueuePersist(worktreeId: string, get: () => AppState): Promise<void> {
   const prior = persistQueueByWorktree.get(worktreeId) ?? Promise.resolve()
   const run = async (): Promise<void> => {
@@ -153,14 +132,8 @@ function enqueuePersist(worktreeId: string, get: () => AppState): Promise<void>
   }
   const next = prior.then(run, run)
   persistQueueByWorktree.set(worktreeId, next)
-  // Why: once this write settles, clear the queue entry only if no later
-  // write has been chained on top. Otherwise the map should keep pointing at
-  // the latest tail so subsequent enqueues chain onto the real in-flight
-  // tail, not a stale resolved promise. Use `then(cleanup, cleanup)` (not
-  // `finally`) so a rejection on `next` is fully consumed by this branch —
-  // otherwise the `.finally()` chain propagates the rejection as an
-  // unhandledRejection even though the caller `await`s `next` in its own
-  // try/catch.
+  // Why: clear the queue entry only if still the tail, so later enqueues chain onto the real in-flight promise.
+  // Why: then(cleanup, cleanup) not finally, so a rejection is consumed here rather than re-thrown as unhandledRejection.
   const cleanup = (): void => {
     if (persistQueueByWorktree.get(worktreeId) === next) {
       persistQueueByWorktree.delete(worktreeId)
@@ -170,9 +143,7 @@ function enqueuePersist(worktreeId: string, get: () => AppState): Promise<void>
   return next
 }
 
-// Why: derive the next comment list from the latest store snapshot inside
-// the `set` updater so two concurrent writes (rapid add+delete, or a
-// delete-while-add-in-flight) can't clobber each other via a stale closure.
+// Why: derive the next list inside the `set` updater so concurrent writes can't clobber each other via a stale closure.
 function mutateComments(
   set: Parameters<StateCreator<AppState, [], [], DiffCommentsSlice>>[0],
   worktreeId: string,
@@ -207,16 +178,7 @@ function mutateComments(
   return { previous, next }
 }
 
-// Why: if the IPC write fails, the optimistic renderer state drifts from
-// disk. Roll back so what the user sees always matches what will survive a
-// reload.
-//
-// Identity guard: we only revert when the current diffComments array is
-// strictly identical (===) to the `next` array this mutation produced. If
-// another mutation has already landed (e.g. Add B succeeded while Add A was
-// still in flight), it will have replaced the array with a different
-// identity. In that case we must leave the newer state alone — rolling back
-// to our stale `previous` would erase B along with the failed A.
+// Why: on IPC-write failure, roll back optimistic state so the renderer matches disk (identity-guarded below).
 function rollback(
   set: Parameters<StateCreator<AppState, [], [], DiffCommentsSlice>>[0],
   worktreeId: string,
@@ -230,16 +192,11 @@ function rollback(
       return {}
     }
     const target = repoList.find((w) => w.id === worktreeId)
-    // Why: if the worktree was removed between the optimistic mutation and
-    // this rollback, there is nothing to restore. Bail out before remapping
-    // `repoList` so we don't allocate a new outer-array identity and trigger
-    // spurious subscriber notifications.
+    // Why: worktree gone since the mutation; bail before remapping so we don't allocate a new array identity and fire spurious notifications.
     if (!target) {
       return {}
     }
-    // Why: only roll back if no other mutation landed since this one. If a
-    // later write already replaced the comments array with a different
-    // identity, our stale `previous` would erase that newer state.
+    // Why: only roll back if no later mutation replaced the array, else our stale `previous` would erase newer state.
     if (target.diffComments !== expectedCurrent) {
       return {}
     }
@@ -255,19 +212,13 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
   get
 ) => ({
   getDiffComments: (worktreeId) => {
-    // Why: accept null/undefined so callers with an optional active worktree
-    // can pass it through without allocating a fresh `[]` fallback each
-    // render, which would defeat the `EMPTY_COMMENTS` sentinel's referential
-    // stability and trigger spurious re-renders in useAppStore selectors.
+    // Why: return the stable sentinel for a missing worktree so optional-worktree callers don't allocate a fresh [] and trigger re-renders.
     if (!worktreeId) {
       return EMPTY_COMMENTS as DiffComment[]
     }
     const worktree = findWorktreeById(get().worktreesByRepo, worktreeId)
     if (!worktree?.diffComments) {
-      // Why: cast the frozen sentinel to the mutable `DiffComment[]` return
-      // type. The array is frozen at runtime so accidental mutation throws;
-      // the cast only hides the `readonly` marker from consumers that never
-      // mutate the list in practice.
+      // Why: cast the frozen sentinel to the mutable return type; runtime freeze makes accidental mutation throw.
       return EMPTY_COMMENTS as DiffComment[]
     }
     return worktree.diffComments
@@ -284,38 +235,26 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
       return null
     }
     try {
-      // Why: enqueue through the per-worktree queue so concurrent mutations
-      // cannot land on disk out of call order. The queued write reads the
-      // latest store snapshot at dequeue time, so it will reflect any newer
-      // mutation that landed after this one was enqueued.
+      // Why: serialize through the per-worktree queue so concurrent writes can't land on disk out of call order.
       await enqueuePersist(input.worktreeId, get)
       get().recordFeatureInteraction?.('review-notes')
       return comment
     } catch (err) {
       console.error('Failed to persist diff comments:', err)
-      // Why: rollback's identity guard will no-op if a later mutation has
-      // already replaced the in-memory list, so losing a successful newer
-      // write is not possible here even though we queued in order.
+      // Why: rollback's identity guard no-ops if a later mutation already replaced the list, so a newer write can't be lost.
       rollback(set, input.worktreeId, result.previous, result.next)
       return null
     }
   },
 
   updateDiffComment: async (worktreeId, commentId, body) => {
-    // Why: trim trailing whitespace but reject an entirely-empty edit so we
-    // don't end up with a saved note that renders as a blank card. Callers
-    // should treat `false` as "edit not committed" and keep the editor open
-    // so the user can either type more or cancel explicitly.
+    // Why: reject an empty edit so we never save a note that renders as a blank card; false means "not committed", keep the editor open.
     const trimmed = body.trim()
     if (!trimmed) {
       return false
     }
 
-    // Why: look up the current state OUTSIDE mutateComments so we can
-    // distinguish "comment missing" (return false — likely an edit-while-
-    // deleted race; the card should keep its draft and not silently close)
-    // from "body unchanged" (return true — benign no-op; the card can close
-    // the editor without surfacing an error).
+    // Why: distinguish "comment missing" (false; keep draft, likely edit-while-deleted) from "body unchanged" (true; close editor) before mutating.
     const repoId = getRepoIdFromWorktreeId(worktreeId)
     const repoList = get().worktreesByRepo[repoId]
     const target = repoList?.find((w) => w.id === worktreeId)
@@ -337,15 +276,12 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
         return null
       }
       const next = current.slice()
-      // Why: editing a previously-sent note makes the agent's copy stale, so
-      // the note should become eligible for the next Send notes action.
+      // Why: editing a sent note makes the agent's copy stale, so reset sentAt to re-queue it for the next Send.
       next[idx] = { ...current[idx], body: trimmed, sentAt: undefined }
       return next
     })
     if (!result) {
-      // Why: between the pre-check and the set updater, the comment vanished
-      // or another mutation already wrote the same body. Treat as success so
-      // the caller closes its editor.
+      // Why: comment vanished or the same body was already written between pre-check and set; treat as success so the editor closes.
       return true
     }
     try {
@@ -366,9 +302,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
     const result = mutateComments(set, worktreeId, (existing) => {
       const next = existing.filter((comment) => {
         const snapshot = snapshotsById.get(comment.id)
-        // Why: delivery is async. If the user edits a note before the prompt
-        // is accepted by the agent, the old snapshot was sent but the current
-        // note is a fresh pending note and must stay visible.
+        // Why: delivery is async; a note edited after its snapshot was sent is a fresh pending note that must stay visible.
         return !snapshot || !deliverySnapshotMatches(comment, snapshot)
       })
       return next.length === existing.length ? null : next
@@ -426,9 +360,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
       return
     }
     try {
-      // Why: enqueue through the per-worktree queue so concurrent mutations
-      // cannot land on disk out of call order. See enqueuePersist for the
-      // ordering invariant.
+      // Why: serialize through the per-worktree queue so concurrent writes can't land out of call order.
       await enqueuePersist(worktreeId, get)
     } catch (err) {
       console.error('Failed to persist diff comments:', err)
diff --git a/src/renderer/src/store/slices/editor.ts b/src/renderer/src/store/slices/editor.ts
index 5856c14039c..79f99f81fc1 100644
--- a/src/renderer/src/store/slices/editor.ts
+++ b/src/renderer/src/store/slices/editor.ts
@@ -153,8 +153,7 @@ function branchCompareMatchesStatusHead(
   statusHead: string
 ): boolean {
   const summaryHead = getKnownGitHead(summary.headOid)
-  // Why: git status reports '(initial)' for unborn branches, while branch
-  // compare represents that same state as a null headOid.
+  // Why: git status reports '(initial)' for unborn branches; branch compare represents that same state as a null headOid.
   return summaryHead === statusHead || (statusHead === '(initial)' && summary.headOid === null)
 }
 
@@ -197,22 +196,9 @@ export type CombinedDiffSkippedConflict = {
   conflictKind: GitConflictKind
 }
 
-// Why: OpenFile is a single type (not a discriminated union on `mode`) because
-// the tab plumbing (reorder, close, activate) treats all tabs uniformly. However,
-// consumers that access `filePath` must be aware that conflict-review tabs use
-// the worktree root as filePath, not a real file. Any code that assumes filePath
-// points to an actual file should check `mode` first.
-//
-// `skippedConflicts` is stored directly on the tab state so the exclusion notice
-// in combined-diff views is stable for the tab's lifetime. It must NOT be
-// reconstructed from live status on every render — the live set can change
-// between polls, which would make the notice flicker or become inaccurate.
-//
-// `branchEntriesSnapshot` exists for the same reason on combined branch diffs:
-// the active worktree is the only one guaranteed to keep a live branch-compare
-// entry list warm. When the user switches worktrees and comes back, the tab must
-// still know which files it was showing even if the live compare data for that
-// inactive worktree has not been refreshed yet.
+// OpenFile is one type (not a `mode` union); consumers reading `filePath` must check `mode` first — conflict-review tabs use the worktree root, not a real file.
+// `skippedConflicts` lives on the tab so the combined-diff exclusion notice stays stable; live status changing between polls would make it flicker.
+// `branchEntriesSnapshot` keeps a combined-branch tab's file list known after switching away from an inactive worktree whose compare data is stale.
 export type OpenFile = {
   id: string // use filePath as unique key
   filePath: string // absolute path
@@ -220,17 +206,11 @@ export type OpenFile = {
   worktreeId: string
   language: string
   isDirty: boolean
-  // Why: remote untitled cleanup must target the environment that created the
-  // file, even if the user switches to Local or another runtime before closing.
+  // Why: remote untitled cleanup must target the creating environment even if the user later switches runtime.
   runtimeEnvironmentId?: string | null
-  /** Why: markdown preview tabs are separate editor tabs that mirror a source
-   *  markdown file's live draft. Storing the source file ID lets the preview
-   *  follow unsaved edits from the normal editor without becoming editable
-   *  itself or conflating the preview tab's identity with the source tab. */
+  /** Why: preview tabs mirror a source file's live draft; storing its ID lets the preview follow unsaved edits without becoming editable. */
   markdownPreviewSourceFileId?: string
-  /** Optional hash fragment to reveal when a preview tab is opened from a
-   *  markdown link such as `./guide.md#setup`. Kept on tab state so repeated
-   *  "open preview" actions can retarget an already-open preview tab. */
+  /** Hash fragment to reveal when a preview tab opens from a link (`./guide.md#setup`); kept on tab state so repeat opens can retarget it. */
   markdownPreviewAnchor?: string
   diffSource?: DiffSource
   branchCompare?: BranchCompareSnapshot
@@ -240,59 +220,32 @@ export type OpenFile = {
   combinedAreaFilter?: string // filter combined diff to a specific area (e.g. 'staged', 'unstaged', 'untracked')
   branchEntriesSnapshot?: GitBranchChangeEntry[]
   commitEntriesSnapshot?: GitBranchChangeEntry[]
-  /** Why: snapshot uncommitted entries at tab-open time so a subsequent commit
-   *  does not yank entries out from under the combined diff, which would rebuild
-   *  all sections and lose loaded content + scroll position. */
+  /** Why: snapshot uncommitted entries at tab-open so a later commit can't yank them out from under the combined diff (rebuild + lost scroll). */
   uncommittedEntriesSnapshot?: GitStatusEntry[]
   conflict?: OpenConflictMetadata
   skippedConflicts?: CombinedDiffSkippedConflict[]
   conflictReview?: ConflictReviewState
   isPreview?: boolean // preview tabs are replaced when another file is single-clicked
   isUntitled?: boolean // true for files created via "New Markdown" that haven't been renamed yet
-  // Why: templated New Markdown files contain real user-visible content at
-  // creation time, unlike blank placeholder files that can be discarded.
+  // Why: templated New Markdown files have real content at creation, unlike blank placeholders that can be discarded.
   deleteUntouchedOnClose?: boolean
-  // Why: when an external process (e.g. `git mv`, `rm`) removes the file on
-  // disk while it's open, we keep the tab around so the user can still see
-  // (and potentially save) their in-memory content. The tab surfaces this as
-  // a strikethrough label plus a "deleted"/"renamed" suffix. Cleared if the
-  // file reappears on disk at its original path. 'changed' means the file was
-  // rewritten on disk while this tab held unsaved edits (issue #7265): the
-  // buffer is preserved and the editor shows a changed-on-disk banner instead
-  // of tab strikethrough.
+  // Why: external delete/rename of an open file keeps the tab (strikethrough label); 'changed' = rewritten on disk under unsaved edits → changed-on-disk banner (#7265).
   externalMutation?: 'deleted' | 'renamed' | 'changed'
-  /** Why: signature of the disk content this tab's edits are based on (last
-   * load or save). Persisted with dirty drafts so a restore can re-derive a
-   * changed-on-disk conflict from ground truth — an agent write that landed
-   * while the app was closed must not be clobbered by a resumed autosave. */
+  /** Signature of the disk content this tab's edits are based on; persisted so a restore detects a changed-on-disk conflict before autosave clobbers an agent write. */
   lastKnownDiskSignature?: string
-  /** Why: set at hydration for restored dirty tabs; suspends autosave until
-   * the restored-tab conflict scan has compared disk against the baseline.
-   * Without this hard gate the scan's async read merely races the autosave
-   * timer, and a slow (SSH/runtime) read loses the race. Not persisted. */
+  /** Why: gates autosave for restored dirty tabs until the conflict scan compares disk vs baseline, else a slow SSH read loses the race. Not persisted. */
   pendingDiskBaselineVerification?: boolean
-  /** Why: diff bodies are cached in EditorPanel. Re-selecting an existing diff
-   * tab from the tree bumps this so the panel refetches instead of reusing a
-   * stale snapshot. */
+  /** Why: diff bodies are cached in EditorPanel; bump this on re-select so the panel refetches instead of reusing a stale snapshot. */
   diffContentReloadNonce?: number
-  /** Why: terminal/agent links can be the user's manual recovery path when a
-   * remote watcher misses an external write. Bumping this refetches clean tabs. */
+  /** Why: bumping refetches clean tabs — the user's manual recovery when a remote watcher misses an external write. */
   fileContentReloadNonce?: number
-  /** Why: CI check full-details tabs are virtual editor tabs backed by fetched
-   *  PR check-run metadata instead of a file on disk. */
+  /** Why: CI check-details tabs are virtual editor tabs backed by fetched PR check-run metadata, not a file on disk. */
   checkRunDetails?: OpenCheckRunDetailsState
-  /** Why: on the web client an editor tab can either be mirrored from the host
-   *  runtime's session snapshot or opened locally by the web user. Only mirrored
-   *  tabs may be culled when they vanish from a later host snapshot; locally
-   *  opened tabs have no host counterpart and must survive snapshot syncs. */
+  /** Why: web-client tab mirrored from the host snapshot; only mirrored tabs may be culled when they vanish, locally-opened tabs must survive. */
   mirroredFromRuntimeSession?: boolean
-  /** Why: orthogonal to `mode` — a `mode: 'edit'` tab that must never accept
-   *  edits, dirty state, autosave, format, or rename. Used by AI Vault View Log
-   *  so an agent-owned transcript cannot be mutated through editor write paths.
-   *  Persisted only when true; absence is the writable default. */
+  /** Why: orthogonal to `mode` — an edit-mode tab that must never accept edits/autosave/rename (AI Vault View Log). Persisted only when true. */
   readOnly?: boolean
-  /** Why: live tail is explicit and only meaningful for a read-only local log;
-   *  ordinary editor tabs and read-only snapshots keep their existing behavior. */
+  /** Why: explicit live tail, only meaningful for a read-only local log. */
   liveTail?: boolean
   mode: 'edit' | 'diff' | 'conflict-review' | 'markdown-preview' | 'check-details'
 }
@@ -301,16 +254,11 @@ export type ActivityBarPosition = 'top' | 'side'
 
 export type MarkdownViewMode = 'source' | 'rich' | 'preview'
 
-// Why: orthogonal to MarkdownViewMode. 'changes' flips the editor tab to a
-// diff-against-HEAD rendering (working tree incl. unsaved draft vs HEAD) in
-// place of the normal editor, without creating a separate tab. The per-tab
-// Tab.contentType stays 'editor' for the whole lifetime; this slice drives
-// what EditorPanel *renders* for that tab. See reviews/changes-view-mode-plan.md.
+// Why: orthogonal to MarkdownViewMode; 'changes' renders diff-vs-HEAD in place of the editor without a separate tab. See reviews/changes-view-mode-plan.md.
 export type EditorViewMode = 'edit' | 'changes'
 
 /** Enough state to restore a tab via `openFile` after `closeFile` (id is always filePath). */
-// Why: omit mirroredFromRuntimeSession so a user-reopened tab is never treated
-// as host-owned; otherwise the web session sync could cull it on the next snapshot.
+// Why: omit mirroredFromRuntimeSession so a user-reopened tab isn't treated as host-owned and culled by the next web session sync.
 export type ClosedEditorTabSnapshot = Omit<
   OpenFile,
   'id' | 'isDirty' | 'mirroredFromRuntimeSession'
@@ -338,10 +286,7 @@ function resolveDiffRuntimeEnvironmentId(
   if (explicitRuntimeEnvironmentId !== undefined) {
     return explicitRuntimeEnvironmentId
   }
-  // Why: route diffs by the worktree's EXPLICIT owner (#6957); owner-less/local
-  // resolves to null so the read is forced LOCAL. undefined would instead
-  // inherit the focused runtime in settingsForRuntimeOwner and read the diff
-  // from the wrong host — the exact bug in #8484.
+  // Why: route diffs by explicit worktree owner; null forces LOCAL, undefined would inherit the focused runtime → wrong host (#6957, #8484).
   return getExplicitRuntimeEnvironmentIdForWorktree(state, worktreeId) ?? null
 }
 
@@ -390,8 +335,7 @@ function scheduleEditorLineReveal(
   column?: number,
   fileId?: string
 ): void {
-  // Why: openFile can replace a preview and remount Monaco asynchronously; the
-  // reveal must land after that remount or the old editor can clear it.
+  // Why: openFile may remount Monaco async; the reveal must land after remount or the old editor clears it.
   cancelPendingEditorLineRevealFrames()
   get().setPendingEditorReveal(null)
   requestTrackedEditorLineRevealFrame(() => {
@@ -408,10 +352,7 @@ function scheduleEditorLineReveal(
 }
 
 export type EditorSlice = {
-  // Why: #300 originally kept EditorPanel mounted while hidden so unsaved
-  // drafts and autosave timers could survive tab switches. Drafts live in the
-  // store instead so the visible editor UI can unmount without losing edits or
-  // widening the app-shutdown surface.
+  // Why: drafts live in the store (not a hidden mounted EditorPanel, #300) so the editor UI can unmount without losing edits.
   editorDrafts: Record<string, string>
   setEditorDraft: (fileId: string, content: string) => void
   clearEditorDraft: (fileId: string) => void
@@ -421,20 +362,15 @@ export type EditorSlice = {
   markdownViewMode: Record<string, MarkdownViewMode>
   setMarkdownViewMode: (fileId: string, mode: MarkdownViewMode) => void
 
-  // Editor view mode per file (fileId -> mode). Orthogonal to markdownViewMode:
-  // a markdown file can be in Raw+Changes, Rendered+Changes, etc. Absent entry
-  // means 'edit'.
+  // Editor view mode per file (fileId -> mode). Orthogonal to markdownViewMode; absent entry means 'edit'.
   editorViewMode: Record<string, EditorViewMode>
   setEditorViewMode: (fileId: string, mode: EditorViewMode) => void
 
-  // Per-file opt-in to render front matter in the markdown preview (#4468).
-  // Default is hidden; absent entry means hidden. Storing only the explicit
-  // true values keeps the record minimal and the default implicit.
+  // Per-file opt-in to render markdown-preview front matter (#4468); absent = default.
   markdownFrontmatterVisible: Record<string, boolean>
   setMarkdownFrontmatterVisible: (fileId: string, visible: boolean) => void
 
-  // Per-file opt-in to keep the markdown table of contents open. Default is
-  // hidden; absent entry means hidden.
+  // Per-file opt-in to keep the markdown TOC open; absent = hidden (default).
   markdownTableOfContentsVisible: Record<string, boolean>
   setMarkdownTableOfContentsVisible: (fileId: string, visible: boolean) => void
 
@@ -495,10 +431,7 @@ export type EditorSlice = {
     }
   ) => void
   openNewMarkdownInActiveWorkspace: (groupId: string) => Promise<void>
-  // Why: dispatcher for markdown link activation. Lives on the slice because it
-  // sequences openFile, setMarkdownViewMode, and setPendingEditorReveal around
-  // an async Monaco remount — all reading/writing state in this slice. See
-  // docs/markdown-internal-link-opening-design.md.
+  // Why: sequences openFile/setMarkdownViewMode/reveal around an async Monaco remount. See docs/markdown-internal-link-opening-design.md.
   activateMarkdownLink: (
     rawHref: string | undefined,
     ctx: {
@@ -616,33 +549,21 @@ export type EditorSlice = {
   // Git status cache
   gitStatusByWorktree: Record<string, GitStatusEntry[]>
   gitStatusHeadByWorktree: Record<string, string>
-  // Why: when status was truncated at the entry limit (a repo with an enormous
-  // un-ignored folder), the SCM view shows a "too many changes" state and
-  // polling pauses. `{ limit }` when huge, absent otherwise.
+  // Why: set when status hit the entry limit; SCM shows "too many changes" and pauses polling. `{ limit }` when huge, else absent.
   gitStatusHugeByWorktree: Record<string, { limit: number }>
   gitIgnoredPathsByWorktree: Record<string, string[]>
   gitConflictOperationByWorktree: Record<string, GitConflictOperation>
   trackedConflictPathsByWorktree: Record<string, Record<string, GitConflictKind>>
   trackConflictPath: (worktreeId: string, path: string, conflictKind: GitConflictKind) => void
   setGitStatus: (worktreeId: string, status: GitStatusResult) => void
-  // Why: lightweight updater for conflict operation only, used to clear stale
-  // "Rebasing"/"Merging" badges on non-active worktrees without a full git status poll.
+  // Why: clears stale Rebasing/Merging badges on non-active worktrees without a full git status poll.
   setConflictOperation: (worktreeId: string, operation: GitConflictOperation) => void
   remoteStatusesByWorktree: Record<string, GitUpstreamStatus>
   setUpstreamStatus: (worktreeId: string, status: GitUpstreamStatus) => void
-  // Why: refcount-backed busy flag. A bare boolean races across worktrees —
-  // push on A finishing while pull on B is still in flight would flip the
-  // flag off and prematurely re-enable B's button. beginRemoteOperation /
-  // endRemoteOperation must be paired (begin at the start of the async
-  // operation, end in finally) so the derived boolean only flips to false
-  // once every in-flight remote op has finished.
+  // Why: refcount-backed busy flag; a bare boolean races across worktrees (A finishing re-enables B mid-flight). begin/end must be paired.
   isRemoteOperationActive: boolean
   remoteOperationDepth: number
-  // Why: surfaces *which* remote op the user actually triggered so the
-  // primary button can mirror it (label + spinner) rather than leaving a
-  // stale label from before the dropdown click. Cleared when depth hits 0.
-  // Last-write-wins on concurrent ops, which is fine — the UI disables
-  // every entry while busy, so concurrent ops can't be initiated through it.
+  // Why: which remote op the user triggered, so the primary button mirrors its label+spinner; cleared at depth 0.
   inFlightRemoteOpKind: RemoteOpKind | null
   beginRemoteOperation: (kind?: RemoteOpKind) => void
   endRemoteOperation: () => void
@@ -771,8 +692,7 @@ function openWorkspaceEditorItem(
       contentType
     )
     if (existing) {
-      // Why: sidebar preview reopens should focus the tab without making it
-      // permanent; explicit tab activation still promotes previews by default.
+      // Why: sidebar preview reopens focus the tab without promoting it; explicit activation still promotes previews by default.
       state.activateTab?.(existing.id, { preservePreview: isPreview })
       return existing.id
     }
@@ -809,9 +729,7 @@ function getReplaceablePreviewFileId(
     if (!previewTab) {
       return null
     }
-    // Why: split groups may hold separate tabs for the same editor entity. A
-    // group-scoped preview replacement must not mutate the shared OpenFile out
-    // from under another group's tab.
+    // Why: split groups can share one OpenFile; a group-scoped preview replacement must not mutate it out from under another group's tab.
     const isSharedEntity = tabsForWorktree.some(
       (tab) =>
         tab.id !== previewTab.id &&
@@ -968,9 +886,7 @@ function resolveEditorOpenTargetGroupId(
     return activeGroup.id
   }
 
-  // Why: file explorer opens should reuse an existing editor pane when the
-  // focused pane is an agent terminal, instead of turning that terminal pane
-  // into an editor tab.
+  // Why: reuse an existing editor pane rather than turning a focused agent-terminal pane into an editor tab.
   const visibleEditorGroup = groups.find((group) => {
     if (group.id === activeGroup.id) {
       return false
@@ -999,9 +915,7 @@ function buildEditorActiveResult(
   activeTabTypeByWorktree: Record<string, WorkspaceVisibleTabType>
 } {
   return {
-    // Why: floating markdown tabs use the editor surface without becoming the
-    // main worktree's active editor. Updating only the per-worktree maps keeps
-    // the workspace behind the floating panel from switching surfaces.
+    // Why: floating markdown tabs must not become the worktree's active editor, so update only the per-worktree maps.
     ...(worktreeId === FLOATING_TERMINAL_WORKTREE_ID
       ? {}
       : { activeFileId: fileId, activeTabType: 'editor' as const }),
@@ -1090,8 +1004,7 @@ function matchesEditorMode(
 }
 
 function getReusableOpenFileModes(mode: OpenFile['mode']): readonly OpenFile['mode'][] {
-  // Why: the same path can be open as both a diff and an editable file; matching
-  // by path alone collapses those distinct visible tabs onto one OpenFile.
+  // Why: one path can be open as both a diff and an editable tab; matching by path alone would collapse them onto one OpenFile.
   return [mode]
 }
 
@@ -1111,8 +1024,7 @@ function resolveEditorFileIdForOwner(
   if (existing) {
     return existing.id
   }
-  // Why: preview-only markdown tabs also reserve their source id. Treat those
-  // source ids like open editor ids so same-path owners do not collapse.
+  // Why: preview-only markdown tabs reserve their source id too; treat it like an open editor id so same-path owners don't collapse.
   return state.openFiles.some((file) =>
     isEditorFileIdOccupiedByOtherOwner(file, filePath, worktreeId, runtimeEnvironmentId)
   )
@@ -1319,8 +1231,7 @@ function deleteUntouchedUntitledFile(state: AppState, file: OpenFile): void {
   const repoId = worktree?.repoId ?? getRepoIdFromWorktreeId(file.worktreeId)
   const repo = state.repos.find((candidate) => candidate.id === repoId)
   const owningRuntimeEnvironmentId = file.runtimeEnvironmentId?.trim()
-  // Why: untitled placeholders may live on a remote runtime or SSH target.
-  // Route through the runtime-aware client instead of assuming client-local FS.
+  // Why: untitled placeholders may live on a remote runtime/SSH target; route through the runtime-aware client, not local FS.
   const context = {
     settings: settingsForRuntimeOwner(state.settings, file.runtimeEnvironmentId),
     worktreeId: file.worktreeId,
@@ -1347,9 +1258,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
   editorDrafts: {},
   setEditorDraft: (fileId, content) =>
     set((s) => {
-      // Why: read-only tabs (e.g. AI Vault View Log) must never accumulate an
-      // editor draft — a draft is the seed of dirty state, autosave, and a
-      // hot-exit restore that could write over an agent-owned transcript.
+      // Why: read-only tabs must never accrue a draft — it seeds dirty/autosave/hot-exit restore that could overwrite an agent transcript.
       const file = s.openFiles.find((f) => f.id === fileId)
       if (file?.readOnly === true) {
         return s
@@ -1392,9 +1301,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
   editorViewMode: {},
   setEditorViewMode: (fileId, mode) =>
     set((s) => {
-      // Why: default is 'edit'. Writing 'edit' explicitly when no entry exists
-      // would grow the record unnecessarily; delete instead so the shape stays
-      // minimal and hydration round-trips cleanly.
+      // Why: default is 'edit' — delete rather than store it so the record stays minimal and hydration round-trips cleanly.
       if (mode === 'edit') {
         if (!(fileId in s.editorViewMode)) {
           return s
@@ -1406,15 +1313,11 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       return { editorViewMode: { ...s.editorViewMode, [fileId]: mode } }
     }),
 
-  // Markdown preview front-matter visibility (#4468). Default is hidden; the
-  // preview only renders the front-matter card when the user opts in per file.
+  // Markdown preview front-matter visibility (#4468).
   markdownFrontmatterVisible: {},
   setMarkdownFrontmatterVisible: (fileId, visible) =>
     set((s) => {
-      // Why: default is visible. Writing `true` explicitly when no entry exists
-      // would grow the record unnecessarily; delete instead so the map only
-      // carries hide overrides and hydration round-trips cleanly — same
-      // trade-off as setEditorViewMode above.
+      // Why: don't persist the default value; delete instead so the map carries only overrides and hydration round-trips cleanly.
       if (visible) {
         if (!(fileId in s.markdownFrontmatterVisible)) {
           return s
@@ -1662,9 +1565,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       editorItemFileId = id
       const isPreview = options?.preview ?? false
       const recordReplacedPreview = options?.recordReplacedPreview ?? false
-      // Why: resolve the target group up-front so preview replacement can be
-      // scoped to that group. Opening as preview in group B must not evict a
-      // preview tab belonging to group A (split tab groups).
+      // Why: resolve the target group up-front so preview replacement is scoped to it (group B open must not evict group A's preview).
       const targetGroupId =
         resolveEditorOpenTargetGroupId(s, worktreeId, options?.targetGroupId) ?? undefined
       editorItemTargetGroupId = targetGroupId
@@ -1698,10 +1599,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         if (!needsExistingUpdate) {
           return activeResult
         }
-        // Why: `readOnly` is intentionally NOT in this override map. It is
-        // sticky: an existing tab keeps its own authority (`...f`). View Log
-        // never flips a writable tab to read-only, and an ordinary open never
-        // silently upgrades a read-only View Log tab to writable.
+        // Why: `readOnly` is intentionally NOT in this override map — it's sticky, so `...f` preserves the tab's own read-only state.
         return {
           openFiles: s.openFiles.map((f) =>
             f.id === id
@@ -1731,21 +1629,14 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         }
       }
 
-      // If opening as preview, replace the existing preview tab.
-      // Why: preview replacement is scoped to `worktreeId + targetGroupId` so
-      // link clicks in group B do not silently evict previews from group A.
-      // Falls back to worktree-wide when group plumbing is unavailable (e.g.
-      // in tests that don't populate unifiedTabsByWorktree), matching the
-      // prior behavior.
+      // Why: scope preview replacement to worktreeId + targetGroupId so link clicks in group B don't evict group A's previews.
       let newFiles = s.openFiles
       if (isPreview) {
         const replaceablePreviewId = getReplaceablePreviewFileId(s, worktreeId, targetGroupId)
         const existingPreviewIdx = s.openFiles.findIndex((f) => f.id === replaceablePreviewId)
         if (existingPreviewIdx !== -1) {
           const replacedPreview = s.openFiles[existingPreviewIdx]
-          // Why: reuse the shared eviction helper (as the four other preview-
-          // replacement paths do) so per-file cursor/draft/visibility cleanup stays
-          // defined in one place instead of a hand-rolled copy that drifts.
+          // Why: reuse the shared eviction helper so per-file cursor/draft/visibility cleanup stays in one place.
           const {
             editorDrafts: nextEditorDrafts,
             editorCursorLine: nextEditorCursorLine,
@@ -1770,11 +1661,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
                 }
               }
             : {}
-          // Why: link-activation replaces previews by default, so users walking
-          // A → B → C can't reach A via Cmd/Ctrl+Shift+T unless we push the
-          // evicted preview onto the recently-closed stack. Gated with
-          // recordReplacedPreview so file-explorer single-click (which
-          // semantically *wants* silent eviction) is unaffected.
+          // Why: push the evicted preview onto the recently-closed stack so Cmd/Ctrl+Shift+T can reopen it; gated to keep file-explorer clicks silent.
           let nextRecentlyClosed = s.recentlyClosedEditorTabsByWorktree
           let nextRecentlyClosedKinds = s.recentlyClosedTabKindsByWorktree
           if (recordReplacedPreview && replacedPreview.id !== id) {
@@ -1814,10 +1701,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         }
       }
 
-      // Why: append the new file to the persisted tab bar order so it appears
-      // at the end of the tab bar. Without this, reconcileOrder in TabBar
-      // falls back to type-grouped ordering (terminals first) when the stored
-      // order doesn't contain the new file.
+      // Why: append to the persisted tab bar order, else TabBar's reconcileOrder falls back to type-grouped ordering (terminals first).
       const tabBarUpdate: Record<string, unknown> = {}
       if (s.tabBarOrderByWorktree) {
         const currentOrder = s.tabBarOrderByWorktree[worktreeId] ?? []
@@ -2014,28 +1898,15 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     }
   },
 
-  // Why: closing a tab does NOT clear Resolved locally state. If the file is
-  // still present in Changes or Staged Changes, the continuity badge should
-  // remain visible until the file leaves the sidebar, the session resets, or
-  // the file becomes live-unresolved again. trackedConflictPaths is tied to
-  // sidebar presence, not tab lifecycle.
+  // Why: closing a tab does NOT clear Resolved-locally state — trackedConflictPaths is tied to sidebar presence, not tab lifecycle.
   closeFile: (fileId) => {
-    // Why: capture untitled + dirty state before the set() call mutates the
-    // store, so we can decide after the tab is removed whether the on-disk
-    // file should be cleaned up (untitled files closed without edits are
-    // throwaway and should not litter the worktree).
+    // Why: capture untitled+dirty state before set() mutates the store, so cleanup of throwaway untitled files can decide after removal.
     const preClose = get().openFiles.find((f) => f.id === fileId)
-    // Why: also check editorDrafts as a safety net — isDirty is set via a
-    // debounced callback from the editor, so there's a narrow window where
-    // content exists but isDirty hasn't flushed yet. A draft means the user
-    // typed something, so the file should be kept.
+    // Why: also check editorDrafts — isDirty is set by a debounced callback, so a draft can exist before isDirty flushes; a draft means the user typed something.
     const hasDraft = !!get().editorDrafts[fileId]
     const shouldDeleteFromDisk = shouldDeleteUntouchedUntitledFile(preClose, hasDraft)
 
-    // Why: closeFile is the single chokepoint every editor close funnels through
-    // (tab strips, bulk close, save/discard, floating panel). Mirrored tabs are
-    // host-owned, so the host must close its copy too or its next snapshot
-    // re-mirrors the file and the tab reopens. No-op for the host's own files.
+    // Why: mirrored tabs are host-owned, so the host must close its copy or its next snapshot re-mirrors the file and the tab reopens.
     notifyHostOfMirroredEditorClose(get(), preClose?.worktreeId, fileId)
 
     set((s) => {
@@ -2064,9 +1935,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         visibilityKeysToRemove.length > 0
           ? removeMarkdownVisibilityKeys(s.markdownTableOfContentsVisible, visibilityKeysToRemove)
           : s.markdownTableOfContentsVisible
-      // Why: editorCursorLine entries are keyed by fileId and accumulate on
-      // every cursor move. Without cleanup they grow without bound across a
-      // long session as files are opened and closed.
+      // Why: editorCursorLine is keyed by fileId and grows unbounded across a long session without cleanup on close.
       const newEditorCursorLine = { ...s.editorCursorLine }
       delete newEditorCursorLine[fileId]
       let newActiveId = s.activeFileId
@@ -2097,9 +1966,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         }
       }
 
-      // Why: editor tabs share a mixed tab strip with browser tabs. Closing the
-      // last editor in a worktree should reveal an available browser tab before
-      // falling all the way back to a terminal surface.
+      // Why: editors share a mixed tab strip with browser tabs; closing the last editor should reveal a browser tab before falling back to a terminal.
       const activeWorktreeId = s.activeWorktreeId
       const remainingForWorktree = activeWorktreeId
         ? newFiles.filter((f) => f.worktreeId === activeWorktreeId)
@@ -2133,8 +2000,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         browserTabsForWorktree.length === 0 &&
         terminalTabsForWorktree.length === 0
 
-      // Why: keep tabBarOrderByWorktree in sync so stale editor IDs don't
-      // linger and cause position shifts the next time the order is reconciled.
+      // Why: prune the closed id from tabBarOrderByWorktree so stale ids don't shift positions on the next reconcile.
       const worktreeId = closedFile?.worktreeId ?? activeWorktreeId
       const nextTabBarOrderByWorktree =
         worktreeId && s.tabBarOrderByWorktree
@@ -2149,10 +2015,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       let nextRecentlyClosed = s.recentlyClosedEditorTabsByWorktree
       let nextRecentlyClosedKinds = s.recentlyClosedTabKindsByWorktree
       const wtRecent = closedFile?.worktreeId
-      // Why: untitled files that were never edited will be deleted from disk
-      // after close. Adding them to the reopen stack would let Cmd+Shift+T
-      // try to reopen a path that no longer exists. Preview tabs are also
-      // excluded — they are ephemeral views, not user-opened files.
+      // Why: exclude untitled unedited files (deleted from disk after close, so Cmd+Shift+T can't reopen a gone path) and ephemeral preview tabs from the reopen stack.
       if (
         closedFile &&
         wtRecent &&
@@ -2185,10 +2048,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         editorDrafts: newEditorDrafts,
         editorCursorLine: newEditorCursorLine,
         activeFileId: newActiveId,
-        // Why: if closing the last editor also leaves the worktree without any
-        // browser or terminal surface, keep parity with the terminal/browser
-        // close handlers and return to the Orca landing state instead of
-        // leaving an active worktree selected with nothing renderable.
+        // Why: if the last editor closes with no browser/terminal surface left, return to the landing state like the terminal/browser close handlers do.
         activeWorktreeId: shouldDeactivateWorktree ? null : s.activeWorktreeId,
         activeBrowserTabId: shouldDeactivateWorktree
           ? null
@@ -2209,21 +2069,12 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       }
     })
 
-    // Why: untitled files that were never edited are empty placeholders — they
-    // exist on disk only because createUntitledMarkdownFile() eagerly writes
-    // them so the editor has a real path to bind to. If the user closes the
-    // tab without typing anything, the file is just clutter. Fire-and-forget
-    // delete; failure (e.g. already removed externally) is harmless.
+    // Why: untitled unedited files exist on disk only because createUntitledMarkdownFile() eagerly writes a bindable path; delete the clutter (fire-and-forget).
     if (shouldDeleteFromDisk && preClose && typeof window !== 'undefined') {
       deleteUntouchedUntitledFile(get(), preClose)
     }
 
-    // Why: the unified tab model drives visual tab-bar order and next-active
-    // selection (MRU-based, falling back to the visual neighbor). Without
-    // this, closing an editor/diff tab picks the next active file from the
-    // openFiles array instead of running the unified close path, producing
-    // inconsistent behavior vs terminal/browser tab closes which already go
-    // through closeUnifiedTab.
+    // Why: route editor/diff closes through the unified close path (MRU + visual-neighbor fallback) so they match terminal/browser tab-close behavior.
     for (const tabs of Object.values(get().unifiedTabsByWorktree ?? {})) {
       const unifiedTab = tabs.find(
         (entry) =>
@@ -2260,8 +2111,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     const state = get()
     const activeWorktreeId = state.activeWorktreeId
 
-    // Why: same rationale as closeFile — untitled files that were never edited
-    // are empty placeholders that should not survive a "close all" operation.
+    // Why: like closeFile — untitled unedited files are empty placeholders that shouldn't survive close-all.
     const untitledToDelete = state.openFiles.filter(
       (f) =>
         shouldDeleteUntouchedUntitledFile(f, !!state.editorDrafts[f.id]) &&
@@ -2270,8 +2120,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     const closingFiles = state.openFiles.filter(
       (file) => !activeWorktreeId || file.worktreeId === activeWorktreeId
     )
-    // Why: close-all bypasses closeFile's per-tab path, so mirrored host-owned
-    // editors must be notified here or the next host snapshot reopens them.
+    // Why: close-all bypasses closeFile, so notify mirrored host-owned editors here or the next host snapshot reopens them.
     for (const file of closingFiles) {
       notifyHostOfMirroredEditorClose(state, file.worktreeId, file.id)
     }
@@ -2338,8 +2187,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       const shouldDeactivateWorktree =
         browserTabsForWorktree.length === 0 && terminalTabsForWorktree.length === 0
 
-      // Why: mirrored editor tabs use host tab ids in tab order, while local
-      // editor entries may still use file ids. Remove both close-all shapes.
+      // Why: mirrored tabs use host tab ids in tab order while local entries use file ids; remove both shapes.
       const closedFileIds = new Set(
         s.openFiles.filter((f) => f.worktreeId === activeWorktreeId).map((f) => f.id)
       )
@@ -2357,9 +2205,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       let nextRecentClosed = s.recentlyClosedEditorTabsByWorktree[activeWorktreeId] ?? []
       let capturedCloseCount = 0
       for (const f of [...closingFiles].toReversed()) {
-        // Why: untitled non-dirty files are deleted from disk after close —
-        // skip them so the reopen stack doesn't reference vanished paths.
-        // Preview tabs are ephemeral views that shouldn't pollute the stack.
+        // Why: skip untitled non-dirty files (deleted from disk after close) and ephemeral preview tabs so the reopen stack has no vanished/junk paths.
         if (
           shouldDeleteUntouchedUntitledFile(f, !!s.editorDrafts[f.id]) ||
           f.mode === 'markdown-preview'
@@ -2379,9 +2225,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         editorDrafts: newEditorDrafts,
         editorCursorLine: newEditorCursorLine,
         activeFileId: null,
-        // Why: closing every editor in the active worktree can leave no
-        // renderable surface at all. Clear the active worktree in that case so
-        // the renderer shows the landing page instead of a blank workspace.
+        // Why: closing every editor can leave no renderable surface; clear the active worktree so the renderer shows the landing page, not a blank workspace.
         activeWorktreeId: shouldDeactivateWorktree ? null : s.activeWorktreeId,
         activeBrowserTabId: shouldDeactivateWorktree
           ? null
@@ -2398,10 +2242,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         activeFileIdByWorktree: newActiveFileIdByWorktree,
         activeTabTypeByWorktree: newActiveTabTypeByWorktree,
         tabBarOrderByWorktree: nextTabBarOrderByWorktree,
-        // Why: search-result navigation queues a one-shot reveal for the next
-        // editor mount. If the worktree closes all editor tabs before that
-        // reveal is consumed, keeping it around would make a later reopen jump
-        // to an old match unexpectedly.
+        // Why: clear the one-shot search reveal; keeping it after closing all editors would make a later reopen jump to an old match.
         pendingEditorReveal: null,
         recentlyClosedEditorTabsByWorktree: {
           ...s.recentlyClosedEditorTabsByWorktree,
@@ -2476,17 +2317,12 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
 
   markFileDirty: (fileId, dirty) =>
     set((s) => {
-      // Why: typing fires this on every keystroke. Rebuilding openFiles
-      // unconditionally thrashes every subscriber (EditorPanel → EditorContent
-      // → MonacoEditor re-renders) and produced visible typing lag. Bail out
-      // when the dirty bit is already the target value and the preview-promote
-      // side effect is a no-op.
+      // Why: this fires on every keystroke; rebuilding openFiles unconditionally thrashes subscribers and caused typing lag, so bail when nothing changes.
       const file = s.openFiles.find((f) => f.id === fileId)
       if (!file) {
         return s
       }
-      // Why: read-only tabs can never become dirty; a mutation path that reached
-      // here (stray change/save callback) must hard no-op the integrity invariant.
+      // Why: read-only tabs can never become dirty; hard no-op any stray change/save callback that reached here.
       if (file.readOnly === true) {
         return s
       }
@@ -2865,9 +2701,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       const skippedConflicts = relevantEntries
         .filter((entry) => entry.conflictStatus === 'unresolved' && entry.conflictKind)
         .map((entry) => ({ path: entry.path, conflictKind: entry.conflictKind! }))
-      // Why: snapshot the entry list at open time so a subsequent commit does
-      // not yank entries from under the combined diff view, which would rebuild
-      // all sections and lose loaded content + scroll position.
+      // Why: snapshot entries at open time so a later commit can't yank them and force a rebuild that loses loaded content + scroll position.
       const uncommittedEntriesSnapshot = relevantEntries
       const id = areaFilter
         ? `${worktreeId}::all-diffs::uncommitted::${areaFilter}`
@@ -3126,9 +2960,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       }
     })
 
-    // Why: the conflict file needs a normal editor backing tab for save/close
-    // flows, but selecting it from Conflict Review must keep the review tab
-    // visible. Create the backing tab beside the review tab, then restore focus.
+    // Why: the conflict file needs a normal editor backing tab for save/close, but selecting from Conflict Review must keep the review tab visible; restore focus after.
     void openWorkspaceEditorItem(
       get(),
       absolutePath,
@@ -3143,11 +2975,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     }
   },
 
-  // Why: Review conflicts is launched from Source Control into the editor area,
-  // not from Checks. Merge-conflict review is source-control work, not CI/PR
-  // status. The tab renders from a stored snapshot (entries + timestamp), not
-  // from live status on every paint, so the list is stable even if the live
-  // unresolved set changes between polls.
+  // Why: renders from a stored snapshot (entries + timestamp), not live status, so the list stays stable across polls while reviewing.
   openConflictReview: (worktreeId, worktreePath, entries, source) => {
     const id = `${worktreeId}::conflict-review`
     set((s) => {
@@ -3203,8 +3031,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     void openWorkspaceEditorItem(get(), id, worktreeId, 'Conflict Review', 'conflict-review')
   },
 
-  // Why: the checks sidebar only has room for inline summaries; full logs and
-  // annotations belong in the center editor pane like diff tabs.
+  // Why: the checks sidebar only fits inline summaries; full logs and annotations belong in the center editor pane.
   openCheckRunDetails: (worktreeId, contextKey, check, state) => {
     const id = buildCheckRunDetailsTabId(worktreeId, check)
     const label = getCheckRunDetailsTabLabel(check)
@@ -3259,8 +3086,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     void openWorkspaceEditorItem(get(), id, worktreeId, label, 'check-details')
   },
 
-  // Why: sidebar detail fetches can finish after a full-details tab is already
-  // open; this updates the tab snapshot without stealing focus from the user.
+  // Why: sidebar detail fetches can finish after the full-details tab is open; update the snapshot without stealing focus.
   patchOpenCheckRunDetails: (worktreeId, contextKey, check, state) => {
     const id = buildCheckRunDetailsTabId(worktreeId, check)
     const nextCheckRunDetails: OpenCheckRunDetailsState = {
@@ -3498,21 +3324,14 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         }
       }
     }),
-  // Why: session-local conflict tracking (trackedConflictPaths, Resolved locally
-  // state) lives entirely in the renderer and never crosses the IPC boundary.
-  // The main process returns only what `git status` reports. The renderer is
-  // responsible for setting conflictStatusSource ('git' for live u-records,
-  // 'session' for Resolved locally) and for all Resolved locally lifecycle.
+  // Why: session-local conflict tracking (Resolved-locally) lives only in the renderer; main returns raw git status, so the renderer owns conflictStatusSource.
   setGitStatus: (worktreeId, status) =>
     set((s) => {
       const hadStatusEntry = Object.prototype.hasOwnProperty.call(s.gitStatusByWorktree, worktreeId)
       const prevEntries = s.gitStatusByWorktree[worktreeId] ?? []
       const prevOperation = s.gitConflictOperationByWorktree[worktreeId] ?? 'unknown'
       const currentTracked = { ...s.trackedConflictPathsByWorktree[worktreeId] }
-      // Why: conflictStatusSource is NOT set by the main process. The renderer
-      // stamps 'git' here for live u-records, and 'session' below when applying
-      // Resolved locally state. This keeps the main process free of session
-      // awareness while letting the renderer distinguish the two sources.
+      // Why: main process doesn't set conflictStatusSource; stamp 'git' here for live u-records ('session' is stamped below for Resolved-locally).
       const normalizedEntries = status.entries.map((entry) =>
         entry.conflictStatus === 'unresolved'
           ? { ...entry, conflictStatusSource: 'git' as const }
@@ -3523,13 +3342,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       )
       const unresolvedByPath = new Map(unresolvedEntries.map((entry) => [entry.path, entry]))
 
-      // Why: when the operation is aborted (git merge --abort, etc.), all u-records
-      // disappear and the HEAD file is cleaned up simultaneously. We detect this as
-      // the operation transitioning to 'unknown' with zero unresolved entries. In
-      // this case we clear the entire trackedConflictPaths set rather than
-      // transitioning each path to Resolved locally — abort is NOT resolution, and
-      // showing "Resolved locally" on every previously-conflicted file after an
-      // abort would be misleading.
+      // Why: operation → 'unknown' with zero unresolved means an abort (git merge --abort), not resolution; clear tracked paths instead of marking each "Resolved locally".
       if (
         status.conflictOperation === 'unknown' &&
         prevOperation !== 'unknown' &&
@@ -3587,8 +3400,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       const statusHeadUnchanged = prevStatusHead === nextStatusHead
 
       const prevBranchSummary = s.gitBranchCompareSummaryByWorktree[worktreeId]
-      // Why: a compare request can finish after git status has observed a new
-      // HEAD; reject that stale snapshot before it can render a false clean state.
+      // Why: a compare request can finish after git status observed a new HEAD; reject the stale snapshot before it renders a false clean state.
       const shouldInvalidateBranchCompare =
         !statusHeadUnchanged &&
         nextStatusHead !== undefined &&
@@ -3663,9 +3475,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       if (prev === operation) {
         return s
       }
-      // Why: when the operation clears (transitions to 'unknown') on a non-active
-      // worktree, we also need to clear tracked conflict paths — same as the
-      // full setGitStatus handler does for the active worktree.
+      // Why: when the operation clears on a non-active worktree, also clear tracked conflict paths — same as setGitStatus does for the active one.
       const nextTracked =
         operation === 'unknown' && prev !== 'unknown'
           ? {}
@@ -3706,10 +3516,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     set((s) => ({
       remoteOperationDepth: s.remoteOperationDepth + 1,
       isRemoteOperationActive: true,
-      // Why: last-write-wins. The UI disables every action entry while busy,
-      // so a second remote op can't be started from inside Orca. If a
-      // background caller (future) triggers one, surfacing the most recent
-      // kind matches "what the user is currently watching".
+      // Why: last-write-wins on the kind; the UI blocks a second user-initiated op, so the most recent kind matches what the user is watching.
       inFlightRemoteOpKind: kind ?? s.inFlightRemoteOpKind
     })),
   endRemoteOperation: () =>
@@ -3718,9 +3525,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       return {
         remoteOperationDepth: next,
         isRemoteOperationActive: next > 0,
-        // Why: only clear the in-flight kind when no remote op remains. Until
-        // depth reaches 0 some other op is still running and its label/
-        // spinner should keep displaying.
+        // Why: keep the in-flight kind (its label/spinner) until depth reaches 0 and no remote op remains.
         inFlightRemoteOpKind: next > 0 ? s.inFlightRemoteOpKind : null
       }
     }),
@@ -3741,15 +3546,9 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       }
       return status
     } catch (error) {
-      // Why: on error we leave the prior status in place rather than writing a
-      // synthetic {hasUpstream:false} — that would flash 'Publish Branch' on a
-      // tracked branch after any transient IPC hiccup and a user click would
-      // re-publish, clobbering the upstream relationship. If the branch is
-      // genuinely newly unpublished, the polling effect will eventually correct
-      // the status on success.
+      // Why: keep prior status on error — a synthetic {hasUpstream:false} would flash 'Publish Branch' on a tracked branch and a click could re-publish, clobbering the upstream.
       if (pushTarget) {
-        // Why: an old automatic poll cache entry must not suppress the next
-        // retry after a post-push/fetch refresh fails transiently.
+        // Why: don't let an old automatic-poll cache entry suppress the next retry after a transient refresh failure.
         invalidateAutomaticPushTargetUpstreamStatusCache({
           settings: runtimeSettings,
           worktreeId,
@@ -3770,15 +3569,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     pushTarget,
     options = {}
   ) => {
-    // Why: don't *await* a post-op git status / upstream refresh here.
-    // Chaining awaited refreshes inside the mutation extends the gap before
-    // compound flows (runCompoundCommitAction → runRemoteAction) reach the
-    // next step. But we still need a near-immediate upstream refresh so
-    // the primary button label rotates from "Push" to "Commit" as soon as
-    // ahead=0 — the polling layer is on a 3s interval, which is long
-    // enough to read as a stuck label. Solution: fire the upstream refresh
-    // as fire-and-forget so it doesn't block the mutation but updates the
-    // store as soon as the IPC resolves.
+    // Why: fire-and-forget the upstream refresh (don't await) so compound flows aren't delayed, but the "Push"→"Commit" label still rotates faster than the 3s poll.
     get().beginRemoteOperation(
       publish ? 'publish' : options.forceWithLease === true ? 'force_push' : 'push'
     )
@@ -3803,9 +3594,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       get().endRemoteOperation()
       if (shouldRefreshAfterRejectedPush) {
         const context = { settings: runtimeSettings, worktreeId, worktreePath, connectionId }
-        // Why: the rejected push proved the publish branch moved. Fetch first
-        // so legacy base-tracking worktrees can discover origin/<branch>, then
-        // refresh ahead/behind so Pull/Sync become actionable immediately.
+        // Why: the rejected push proved the branch moved; fetch first so legacy base-tracking worktrees discover origin/<branch>, then refresh ahead/behind.
         void fetchRuntimeGit(context, pushTarget)
           .catch(() => undefined)
           .then(() =>
@@ -3868,14 +3657,9 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     }
   },
   syncBranch: async (worktreeId, worktreePath, connectionId, pushTarget, options) => {
-    // Why: same shape as pushBranch / pullBranch — fire-and-forget the
-    // post-op upstream refresh after the busy flag clears so the primary
-    // button label rotates immediately when the IPC resolves.
+    // Why: like pushBranch — fire-and-forget the post-op upstream refresh so the primary button label rotates immediately.
     get().beginRemoteOperation('sync')
-    // Why: the inner push stage toasts with { isSync: true } so its failure
-    // surfaces a "Sync failed..." message instead of "Push failed..." — the
-    // user invoked Sync; the underlying push is implementation detail. The
-    // outer catch must then skip toasting to avoid a double-toast.
+    // Why: the inner push stage toasts as Sync and marks the error so the outer catch skips toasting, avoiding a double-toast.
     let pushStageToastShown = false
     let pushed = false
     const runtimeSettings = options?.runtimeTargetSettings ?? get().settings
@@ -3899,19 +3683,14 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         }
       } else {
         await pullRuntimeGit(context, pushTarget)
-        // Why: push only if the pull left local commits that aren't on the
-        // remote. After a merge pull the ahead count can be >0 (local commits +
-        // the new merge commit) or 0 (pure fast-forward), and we avoid a
-        // no-op push round-trip in the fast-forward case.
+        // Why: push only if the pull left local commits ahead of the remote; skip the no-op push after a pure fast-forward.
         const upstreamStatus = await getRuntimeGitUpstreamStatus(context, pushTarget)
         if (upstreamStatus.ahead > 0) {
           try {
             await pushRuntimeGit(context, { pushTarget })
             pushed = true
           } catch (error) {
-            // Why: format under the user-facing operation (sync) rather than
-            // the inner step (push) — the user clicked Sync and shouldn't see
-            // a "Push failed" toast for a step they didn't directly invoke.
+            // Why: frame as Sync, not the inner push — the user clicked Sync and didn't directly invoke this push.
             toast.error(
               resolveRemoteOperationErrorMessage(error, {
                 isSync: true,
@@ -3925,10 +3704,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       }
     } catch (error) {
       if (!pushStageToastShown) {
-        // Why: same isSync framing for fetch/pull/upstream-status failures so
-        // every sync failure path consistently reads as "Sync failed..." (or
-        // a more specific actionable message like "Pull blocked..." when the
-        // shared classifiers match first).
+        // Why: frame fetch/pull/upstream failures as "Sync failed..." since the user invoked Sync, not the inner step.
         toast.error(resolveRemoteOperationErrorMessage(error, { isSync: true }))
       }
       throw error
@@ -3968,10 +3744,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     }
   },
   fetchBranch: async (worktreeId, worktreePath, connectionId, pushTarget, options) => {
-    // Why: same shape as pushBranch / pullBranch — fire-and-forget the
-    // upstream refresh after the busy flag clears. Fetch updates the
-    // remote refs only, so the visible signal we want is the new
-    // ahead/behind counts on the upstream-status payload.
+    // Why: like pushBranch — fire-and-forget the upstream refresh after the busy flag clears so new ahead/behind counts surface.
     get().beginRemoteOperation('fetch')
     const runtimeSettings = options?.runtimeTargetSettings ?? get().settings
     try {
@@ -4019,9 +3792,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       }
       const statusHead = getKnownGitHead(s.gitStatusHeadByWorktree[worktreeId])
       const requestStatusHead = s.gitBranchCompareRequestStatusHeadByWorktree[worktreeId]
-      // Why: polling refreshes can leave the prior UI visible while a compare
-      // request is in flight; never let a pre-status-change result overwrite
-      // a newer status snapshot.
+      // Why: never let a compare result computed before a status change overwrite a newer status snapshot.
       if (
         result.summary.status !== 'loading' &&
         statusHead !== undefined &&
@@ -4059,9 +3830,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
           : { ...s.gitBranchCompareSummaryByWorktree, [worktreeId]: result.summary }
       }
     }),
-  // Why: when the compare base resolves to "no base" (e.g. the prefer-upstream
-  // setting is on and the branch has no upstream), drop any stale summary so the
-  // committed-changes section and "vs" row disappear instead of lingering.
+  // Why: when the compare base resolves to "no base", drop any stale summary so the committed-changes section and "vs" row disappear instead of lingering.
   clearGitBranchCompare: (worktreeId) =>
     set((s) => {
       if (
@@ -4260,14 +4029,11 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       const { line, column } = target
       if (target.relativePath === undefined) {
         if (isLocalPathOpenBlocked(sourceSettings, { connectionId: sourceConnectionId })) {
-          // Why: a file:// link outside the worktree is a client-local escape
-          // hatch. Remote runtime/SSH editors must not treat server paths as client paths.
+          // Why: a file:// link outside the worktree is client-local; remote runtime/SSH editors must not treat server paths as client paths.
           showLocalPathOpenBlockedToast()
           return
         }
-        // Why: terminal file links already authorize clicked external paths
-        // before opening them in Orca. Markdown file:// links need the same
-        // user-gesture authorization so /tmp screenshots can use ImageViewer.
+        // Why: markdown file:// links need the same user-gesture authorization terminal links get, so external paths (e.g. /tmp screenshots) can open in Orca.
         await window.api.fs.authorizeExternalPath({ targetPath: target.absolutePath })
       } else {
         let stats: { isDirectory: boolean }
@@ -4353,17 +4119,13 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
 
     if (line !== undefined) {
       const fileId = getOpenedEditFileIdAfterOpen(get(), absolutePath, ctx.worktreeId)
-      // Why: pendingEditorReveal is consumed by MonacoEditor on mount. If the
-      // file stays in rich mode, the reveal is silently dropped; use the final
-      // owner-qualified id after openFile has resolved the tab identity.
+      // Why: MonacoEditor drops the reveal if the file stays in rich mode; switch to source using the resolved owner-qualified id.
       get().setMarkdownViewMode(fileId, 'source')
       scheduleEditorLineReveal(get, absolutePath, line, column, fileId)
     }
   },
 
-  // Why: only edit-mode files are restored — diffs and conflict views depend on
-  // transient git state that may have changed between sessions. Restoring them
-  // would show stale data or fail to load entirely.
+  // Why: only edit-mode files are restored — diffs/conflict views depend on transient git state that may be stale between sessions.
   hydrateEditorSession: (session, options) => {
     set((s) => {
       const openFilesByWorktree = session.openFilesByWorktree ?? {}
@@ -4371,9 +4133,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       const persistedActiveTabTypeByWorktree = session.activeTabTypeByWorktree ?? {}
       const persistedMarkdownFrontmatterVisible = session.markdownFrontmatterVisible ?? {}
 
-      // Why: worktrees may have been deleted between sessions. Filter out
-      // files for worktrees that no longer exist, mirroring the validation
-      // that hydrateWorkspaceSession performs for terminal tabs.
+      // Why: worktrees may have been deleted between sessions; drop files for worktrees that no longer exist.
       const validWorktreeIds = new Set(
         Object.values(s.worktreesByRepo)
           .flat()
@@ -4400,9 +4160,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
             pf,
             worktreeId
           )
-          // Why: floating/runtime-owned files need IDs that survive peers
-          // disappearing between restarts; collision-based IDs drift when the
-          // same path is no longer open in another owner.
+          // Why: floating/runtime-owned files need IDs that survive peers disappearing between restarts; collision-based IDs drift when the path is no longer open elsewhere.
           const ownedId = buildOwnedEditorFileId(pf.filePath, worktreeId, pf.runtimeEnvironmentId)
           const id =
             shouldHydrateWithOwnedEditorFileId(worktreeId, pf.runtimeEnvironmentId) ||
@@ -4410,9 +4168,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
               ? ownedId
               : pf.filePath
           usedOpenFileIds.add(id)
-          // Why: legacy sessions used the collision-derived id for each
-          // persisted entry. Mapping every filePath would collapse same-path
-          // local/runtime tabs onto whichever owner hydrates last.
+          // Why: map from the collision-derived legacy id; keying by filePath would collapse same-path local/runtime tabs onto the last owner to hydrate.
           addEditorFileIdMigration(editorFileIdMigrationsByWorktree, worktreeId, legacyId, id)
           legacyHydratedOpenFiles.push({
             id: legacyId,
@@ -4420,9 +4176,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
             worktreeId,
             runtimeEnvironmentId: pf.runtimeEnvironmentId
           })
-          // Why: read-only tabs (AI Vault View Log) must restore clean. Ignore
-          // any persisted dirty draft / baseline so a restored agent log can
-          // never come back writable or as a hot-exit draft to be saved.
+          // Why: read-only tabs (AI Vault View Log) must restore clean — ignore any persisted dirty draft/baseline so they can't come back writable.
           const isReadOnly = pf.readOnly === true
           if (!isReadOnly && pf.dirtyDraftContent !== undefined) {
             editorDrafts[id] = pf.dirtyDraftContent
@@ -4432,9 +4186,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
             filePath: pf.filePath,
             relativePath: pf.relativePath,
             worktreeId,
-            // Why: sessions can contain language ids from older Orca builds.
-            // Re-detect on hydrate so newly-supported extensions like .ipynb
-            // stop reopening as raw JSON/plain text after the upgrade.
+            // Why: re-detect language on hydrate — older sessions stored ids from before extensions like .ipynb were supported.
             language: detectLanguage(pf.relativePath || pf.filePath),
             isDirty: !isReadOnly && pf.dirtyDraftContent !== undefined,
             isPreview: pf.isPreview,
@@ -4442,10 +4194,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
             ...(isReadOnly ? { readOnly: true } : {}),
             ...(isReadOnly && pf.liveTail === true ? { liveTail: true } : {}),
             lastKnownDiskSignature: isReadOnly ? undefined : pf.lastKnownDiskSignature,
-            // Why: hard-suspends autosave until the restored-tab conflict scan
-            // verifies disk against the baseline — an async race would let a
-            // slow remote read lose to the autosave timer and clobber an
-            // offline agent write.
+            // Why: suspend autosave until the conflict scan verifies disk vs baseline, else a slow remote read clobbers an offline write.
             pendingDiskBaselineVerification:
               !isReadOnly &&
               pf.dirtyDraftContent !== undefined &&
@@ -4457,9 +4206,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         }
       }
 
-      // Why: use the store's activeWorktreeId (set by hydrateWorkspaceSession)
-      // rather than the raw session value. hydrateWorkspaceSession may have
-      // nulled out an invalid worktree ID, and we must respect that decision.
+      // Why: use the store's activeWorktreeId — hydrateWorkspaceSession may have nulled an invalid ID, and we must respect that.
       const activeWorktreeId = s.activeWorktreeId
       const fallbackActiveFileId = activeWorktreeId
         ? (openFiles.find((f) => f.worktreeId === activeWorktreeId)?.id ?? null)
@@ -4471,16 +4218,11 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
             persistedActiveFileIdByWorktree[activeWorktreeId]
           )
         : null
-      // Why: verify the persisted active file still exists in the restored set.
-      // The file may have been removed due to worktree validation or the
-      // persisted data may reference a stale path.
+      // Why: the persisted active file may be gone (worktree validation or stale path), so verify it exists in the restored set.
       const activeFileExists = persistedActiveFileId
         ? openFiles.some((f) => f.id === persistedActiveFileId && f.worktreeId === activeWorktreeId)
         : false
-      // Why: if the previously active editor surface pointed at a transient
-      // diff/conflict tab, restart still restores any normal edit tabs for the
-      // worktree. Promote the first restored edit file so the UI comes back on
-      // a concrete file tab instead of an unselected editor surface.
+      // Why: the previous active surface may have been a transient diff/conflict tab (not restored), so promote the first restored edit file.
       const nextActiveFileId = activeFileExists ? persistedActiveFileId : fallbackActiveFileId
       const activeTabType: WorkspaceVisibleTabType =
         activeWorktreeId && persistedActiveTabTypeByWorktree[activeWorktreeId]
@@ -4513,23 +4255,16 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
           if (tabType !== 'editor') {
             return true
           }
-          // Why: a persisted "editor" surface only makes sense if that
-          // worktree still restored a concrete active editor file. Otherwise we
-          // preserve a stale last-active marker that conflicts with browser or
-          // terminal restore logic for the same worktree.
+          // Why: an "editor" marker is valid only if the worktree restored a concrete active file; otherwise it's a stale marker.
           return Boolean(filteredActiveFileIdByWorktree[wId])
         })
       )
 
-      // Why: restart only restores edit-mode files. If the previous active
-      // surface for the current worktree was a transient diff/conflict view,
-      // we must clear the stale "editor" marker here so startup falls back to
-      // browser or terminal instead of showing an empty editor surface.
+      // Why: transient diff/conflict surfaces aren't restored, so clear a stale "editor" marker and fall back to terminal.
       const nextActiveTabType =
         nextActiveFileId || activeTabType !== 'editor' ? activeTabType : 'terminal'
       const openFileIds = new Set(openFiles.map((file) => file.id))
-      // Why: visible is the default, so only restore per-file hide overrides
-      // (`false`); legacy `true` entries collapse back to the default.
+      // Why: visible is the default, so restore only per-file hide overrides (`false`); legacy `true` entries collapse to the default.
       const hiddenFrontmatterEntries = new Map<string, boolean>()
       for (const [persistedFileId, visible] of Object.entries(
         persistedMarkdownFrontmatterVisible
@@ -4630,10 +4365,7 @@ function toOpenConflictMetadata(entry: GitStatusEntry): OpenConflictMetadata | u
       }
 }
 
-// Why: equality checks comparing only path/status/area are insufficient. A row
-// can change from unresolved to resolved_locally (or vice versa) without its
-// base GitFileStatus changing. Without checking conflictKind, conflictStatus,
-// and conflictStatusSource here, the affected row would remain visually stale.
+// Why: conflict state can change (unresolved↔resolved_locally) without the base status changing, so also compare conflict fields.
 function areGitStatusEntriesEqual(prev: GitStatusEntry[], next: GitStatusEntry[]): boolean {
   return (
     prev.length === next.length &&
diff --git a/src/renderer/src/store/slices/github.ts b/src/renderer/src/store/slices/github.ts
index 7a6527e46f0..6d1af5ad691 100644
--- a/src/renderer/src/store/slices/github.ts
+++ b/src/renderer/src/store/slices/github.ts
@@ -1,5 +1,4 @@
-/* eslint-disable max-lines -- Why: the GitHub slice co-locates all cache + fetch logic for
-PR, issue, checks, and comments data so the dedup and invalidation patterns stay consistent. */
+/* eslint-disable max-lines -- Why: the GitHub slice co-locates cache + fetch logic for PR/issue/checks/comments so dedup and invalidation patterns stay consistent. */
 import type { StateCreator } from 'zustand'
 import { toast } from 'sonner'
 import type { AppState } from '../types'
@@ -71,9 +70,7 @@ import {
 } from '../../../../shared/task-source-context'
 
 // ─── ProjectV2 cache types ────────────────────────────────────────────
-// Why: declared separately from CacheEntry<T> (not a generified E parameter)
-// because project-view has a single GraphQL source — no issue/PR-source
-// fallback — and the error union is distinct. Shared structural shape only.
+// Why: separate from CacheEntry<T> — project-view has a single GraphQL source (no issue/PR fallback) and a distinct error union.
 export type ProjectViewCacheEntry<T> = {
   data: T | null
   fetchedAt: number
@@ -93,31 +90,17 @@ export type GitHubPatchWorkItemOptions = {
   sourceContext?: TaskSourceContext | null
 }
 
-/** Optimistic, IPC-free patch shape for `projectViewCache` rows.
- *  Why: the dialog already issues mutations via slug-addressed IPCs and only
- *  needs to keep the Project table view in sync optimistically. Replacing
- *  `addLabels`/`removeLabels` deltas with full `labels`/`assignees` arrays
- *  matches what the dialog's local state already tracks (`localLabels`,
- *  `localAssignees`) and avoids redundant set-merge logic at the call site. */
+/** Optimistic, IPC-free patch shape for `projectViewCache` rows; uses full `labels`/`assignees` arrays (not add/remove deltas) to match the dialog's local state and avoid set-merge at the call site. */
 export type ProjectRowContentPatch = {
   title?: string
   body?: string
-  /** Why: accept the renderer's lowercase work-item state vocabulary
-   *  ('open' | 'closed' | 'merged' | 'draft') and translate to GitHub's
-   *  UPPERCASE row.content.state when applying. The reducer only writes
-   *  what callers send; merged/draft are passed through for completeness
-   *  even though the dialog edits only flip open↔closed today. */
+  /** Lowercase renderer state vocab, translated to GitHub's UPPERCASE `row.content.state` on apply; merged/draft pass through though the dialog only flips open↔closed today. */
   state?: 'open' | 'closed' | 'merged' | 'draft'
   labels?: string[]
   assignees?: string[]
 }
 
-// Why: queryOverride participates in the cache key so an overridden search
-// does not clobber the default-view cache entry, and vice versa. `undefined`
-// means "use the view's stored filter" — the unfiltered cache entry. An
-// empty string is a *distinct* override meaning "no filter", which produces
-// different rows when the view's stored filter is non-empty, so it gets its
-// own cache key.
+// Why: queryOverride is part of the cache key; `undefined` = the view's stored filter, `''` = a distinct "no filter" override that gets its own entry.
 function queryOverrideKeyPart(queryOverride: string | undefined): string {
   if (queryOverride === undefined) {
     return ''
@@ -158,8 +141,7 @@ function getPRRefreshRuntimeRepoTarget(
   if (!ownerRuntimeEnvironmentId) {
     return null
   }
-  // Why: PR refreshes must follow the repo owner host, not the Active Server
-  // dropdown. A runtime-owned worktree can be visible while Local desktop is focused.
+  // Why: PR refreshes must follow the repo owner host, not the Active Server dropdown (a runtime-owned worktree can show while Local is focused).
   return getRuntimeRepoTarget(
     state,
     candidate.repoPath,
@@ -170,8 +152,7 @@ function getPRRefreshRuntimeRepoTarget(
 }
 
 function shouldEnqueueLocalPRRefresh(candidate: GitHubPRRefreshCandidate): boolean {
-  // Why: the local PR coordinator owns local git and SSH bridge refreshes, but
-  // runtime-owned repos and disconnected SSH repos must not hit the IPC crash path.
+  // Why: the local coordinator owns local git + SSH-bridge refreshes; runtime-owned and disconnected-SSH repos must not hit the IPC crash path.
   if (getPRRefreshOwnerRuntimeEnvironmentId(candidate) !== null) {
     return false
   }
@@ -190,8 +171,7 @@ function enqueueLocalGitHubPRRefresh(
   if (!enqueue) {
     return
   }
-  // Why: main can reject stale/unknown local paths; renderer refresh triggers
-  // are best-effort and must not become unhandled rejection crash breadcrumbs.
+  // Why: renderer refresh triggers are best-effort — main may reject stale paths, and this must not become an unhandled-rejection crash.
   void enqueue(args)
     .then((queued) =>
       queued === false || queued?.kind === 'fallback' ? onNotQueued?.() : undefined
@@ -231,8 +211,7 @@ function settingsForGitHubRepoOwner(
       ? { ...settings, activeRuntimeEnvironmentId: parsed.environmentId }
       : ({ activeRuntimeEnvironmentId: parsed.environmentId } as AppState['settings'])
   }
-  // Why: local and SSH-owned GitHub lookups are served by the desktop client;
-  // host focus must not redirect them to the currently selected runtime.
+  // Why: local and SSH-owned GitHub lookups run on the desktop client; host focus must not redirect them to the selected runtime.
   return settings
     ? { ...settings, activeRuntimeEnvironmentId: null }
     : ({ activeRuntimeEnvironmentId: null } as AppState['settings'])
@@ -425,9 +404,7 @@ function countGitHubWorkItemsForRepo(
 }
 
 function isGitHubUnavailableWorkItemsError(error: unknown): boolean {
-  // Why: remote-runtime transport failures can also say "timed out" or
-  // "unavailable". Only runtime_error came from the GitHub method itself;
-  // other RPC codes must not be attributed to GitHub.
+  // Why: only `runtime_error` came from the GitHub method; other RPC transport failures ("timed out"/"unavailable") must not be blamed on GitHub.
   if (error instanceof RuntimeRpcCallError && error.code !== 'runtime_error') {
     return false
   }
@@ -447,9 +424,7 @@ export function projectViewCacheKey(
 }
 
 function projectViewRequestKey(args: GetProjectViewTableArgs, sourceScope: string): string {
-  // Why: callers without `viewId` can't compute the resolved cache key up
-  // front. Use the input-arg signature for inflight dedup; the resolved
-  // cache key is only known after the main-process IPC returns.
+  // Why: without `viewId` the resolved cache key isn't known until the IPC returns, so dedup on the input-arg signature instead.
   const selector = args.viewId
     ? `id:${args.viewId}`
     : args.viewNumber !== undefined
@@ -476,20 +451,13 @@ function settingsForProjectViewCacheKey(
   return { ...settings, activeRuntimeEnvironmentId: null }
 }
 
-// Why: module-scope inflight map — must mirror `inflightWorkItemsRequests`
-// (dedup + force-refresh semantics). Reuses the work-item concurrency gate:
-// the gate exists to bound `gh` subprocess pressure at the renderer boundary,
-// and project-view fetches pressure the same subprocess budget. Two separate
-// gates would let concurrent Project + work-item fetches blow past the cap.
+// Why: reuses the work-item concurrency gate since project-view and work-item fetches share the same gh subprocess budget; separate gates would blow the cap.
 const inflightProjectViewRequests = new Map<
   string,
   { promise: Promise<GetProjectViewTableResult>; force: boolean }
 >()
 
-// Why: derive an optimistic GitHubProjectFieldValue from a mutation value so
-// the patched row re-renders immediately. Single-select and iteration lookups
-// consult the field config on the cached table; the result is best-effort and
-// is overwritten by the authoritative payload on next refresh.
+// Why: optimistic field value so the patched row re-renders immediately; best-effort, overwritten by the authoritative payload on next refresh.
 function optimisticFieldValueFromMutation(
   table: GitHubProjectTable,
   fieldId: string,
@@ -587,10 +555,7 @@ function rollbackRowIfPresent(
   rowId: string,
   previousRow: GitHubProjectRow
 ): void {
-  // Why: the cache entry may have moved (rapid project switch) or the row may
-  // no longer exist by the time the mutation response returns. Skip rollback
-  // in that case — resurrecting stale data into a newly selected project would
-  // show the wrong row.
+  // Why: skip rollback when the entry moved (rapid project switch) or the row is gone, else stale data would surface in the newly selected project.
   const entry = get().projectViewCache[cacheKey]
   if (!entry?.data) {
     return
@@ -618,47 +583,24 @@ function parseSlugAndNumber(
 export type WorkItemsCacheSources = {
   issues: GitHubOwnerRepo | null
   prs: GitHubOwnerRepo | null
-  /** Raw origin remote (if any). Required-nullable so selector code can
-   *  distinguish the raw candidate from the effective PR source. */
+  /** Raw origin remote (if any); required-nullable so the selector can distinguish it from the effective PR source. */
   originCandidate: GitHubOwnerRepo | null
-  /** Raw upstream remote (if any) — present so the selector can render
-   *  independently of the currently-effective preference. Required-nullable
-   *  (matches siblings `issues`/`prs`) so consumers only branch on `null`
-   *  vs value, not a three-state (undefined | null | value). */
+  /** Raw upstream remote (if any); required-nullable (like `issues`/`prs`) so consumers branch on null-vs-value, not a three-state. */
   upstreamCandidate: GitHubOwnerRepo | null
 }
 
-// Why: the indicator and retry banner both need the resolved owner/repo for
-// the failing side. Stamping the slug onto the error keeps the banner copy
-// correct even when the error outlives the cache entry's `sources` field
-// (e.g. on partial-success merges where `data` is retained from a later read).
+// Why: stamp the slug on the error so banner copy stays correct even when the error outlives the entry's `sources` field.
 export type WorkItemsCacheError = ClassifiedError & { source: GitHubOwnerRepo }
 
 export type CacheEntry<T> = {
   data: T | null
   fetchedAt: number
   headSha?: string
-  /**
-   * Resolved issue/PR owner/repo slugs for this entry. Set only on entries
-   * populated by `fetchWorkItems` — PR and issue single-item caches don't
-   * carry sources since the indicator surfaces derive from list reads.
-   */
+  /** Resolved issue/PR owner/repo slugs; set only on `fetchWorkItems` entries (single-item PR/issue caches don't carry sources). */
   sources?: WorkItemsCacheSources
-  /**
-   * Per-side classified error. Present when one (or both) of the underlying
-   * gh list calls failed. Partial-success reads keep `data` from the
-   * successful side and record the failing side here so the banner + list
-   * render together.
-   */
+  /** Per-side classified error; on partial success `data` keeps the good side and the failing side is recorded here so banner + list render together. */
   error?: WorkItemsCacheError
-  /**
-   * True when the resolver fell back to origin because the user's preferred
-   * `'upstream'` remote is no longer configured for this repo. Consumers
-   * surface a one-time toast per session/repo; TaskPage tracks the
-   * already-toasted set so repeated refreshes don't re-toast.
-   * Typed as `?: true` (not `?: boolean`) to encode the invariant "present
-   * iff fell-back" — an explicit `false` write would be a bug.
-   */
+  /** True when the resolver fell back to origin because the preferred `'upstream'` remote is gone; typed `?: true` (never `false`) to encode "present iff fell-back". */
   issueSourceFellBack?: true
 }
 
@@ -701,13 +643,9 @@ function bypassesGitHubPRRefreshFreshness(reason: GitHubPRRefreshReason): boolea
 const CACHE_TTL = 300_000 // 5 minutes (stale data shown instantly, then refreshed)
 const CHECKS_CACHE_TTL = 60_000 // 1 minute — checks change more frequently
 const EMPTY_CHECKS_CACHE_TTL = 10_000
-// Why: the NewWorkspace page's work-item list is a browse surface, not a
-// source of truth, so 60s staleness is fine — stale data renders instantly
-// while a background refresh keeps it current.
+// Why: the work-item list is a browse surface, not a source of truth, so 60s staleness is fine (SWR keeps it current).
 const WORK_ITEMS_CACHE_TTL = 60_000
-// Why: match repos.ts so error toasts surfaced from this slice share the same
-// long-lived duration — the user needs time to read + act on persist failures
-// rather than having the toast vanish behind default short-lived timings.
+// Why: long-lived (matches repos.ts) so the user has time to read + act on persist failures before the toast vanishes.
 const ERROR_TOAST_DURATION = 60_000
 
 const inflightPRRequests = new Map<
@@ -750,10 +688,7 @@ export function _clearGitHubPRRefreshStartedEntriesForTest(): void {
   prRefreshStartedHostedReviewEntries.clear()
 }
 
-// Why: cap in-flight cross-repo fan-out and hover-prefetches at the renderer
-// boundary — the main-side gate is behind the IPC queue, so it can't see a
-// stampede until the calls are already mid-flight. 8 balances responsiveness
-// against gh rate-limit pressure.
+// Why: cap fan-out at the renderer boundary (main-side gate is behind IPC, can't stop a stampede in time); 8 balances responsiveness vs gh rate limits.
 const WORK_ITEM_FETCH_CONCURRENCY = 8
 let workItemFetchInFlight = 0
 const workItemFetchWaiters: (() => void)[] = []
@@ -764,15 +699,13 @@ async function acquireWorkItemSlot(): Promise<void> {
     return
   }
   await new Promise<void>((resolve) => workItemFetchWaiters.push(resolve))
-  // Why: resolver has already claimed the slot on our behalf, so we don't
-  // re-increment here. Pairing convention: acquireWorkItemSlot + releaseWorkItemSlot.
+  // Why: the resolver already claimed the slot on our behalf, so don't re-increment here.
 }
 
 function releaseWorkItemSlot(): void {
   const next = workItemFetchWaiters.shift()
   if (next) {
-    // Hand the slot off directly — net count unchanged — so we can't race a
-    // third caller into the cap between decrement and resolve.
+    // Hand the slot off directly (net count unchanged) so a third caller can't race into the cap between decrement and resolve.
     next()
     return
   }
@@ -994,9 +927,7 @@ function hasUsableCommentPayload(result: GitHubCommentResult): result is {
   )
 }
 
-// Why: 500 entries is generous enough that active developers will never hit it
-// during normal use, but prevents the cache from growing without bound across
-// many repos and branches over a long-running session.
+// Why: bound cache growth across many repos/branches over a long session; 500 is above realistic use.
 const MAX_CACHE_ENTRIES = 500
 type GitHubPRFallbackSource = NonNullable<GitHubPRRefreshAlias['fallbackPRSource']>
 
@@ -1061,8 +992,7 @@ function findUniqueWorktreeById(
   lookupIndex = buildWorktreeLookupIndex(state)
 ): Worktree | null {
   const match = lookupIndex.byId.get(worktreeId)?.unique ?? null
-  // Why: metadata persistence is keyed only by worktree id. If two hosts own
-  // that id, the index marks it non-unique and destructive clears fail closed.
+  // Why: metadata persistence is keyed only by worktree id; an id owned by two hosts is non-unique so destructive clears fail closed.
   if (!match || executionHostId === undefined) {
     return match
   }
@@ -1105,9 +1035,7 @@ function shouldClearDivergedLinkedMergedPR(args: {
     requestHeadOid !== null &&
     pr?.number === linkedPRNumber &&
     pr.state === 'merged' &&
-    // Head-scoped: only clear the worktree whose exact head diverged, so a
-    // PR-number-coalesced refresh broadcast cannot clear a sibling worktree that
-    // is still on the PR's line of work.
+    // Head-scoped: clear only the worktree whose head diverged, so a PR-number-coalesced broadcast can't clear a sibling still on the PR's line of work.
     pr.headDivergedFromMergedPRAtOid === requestHeadOid &&
     pr.headSha !== requestHeadOid &&
     pr.confirmedContainedHeadOid !== requestHeadOid
@@ -1132,11 +1060,7 @@ function shouldApplyDivergedLinkedPRClear(args: {
   )
 }
 
-// Why: a linked PR is a branch-scoped hint. When a lookup returns the linked
-// open or draft PR while the worktree sits on a different branch — and neither
-// the push target nor the worktree HEAD still points at the PR head — the link is stale
-// (a branch switch whose identity-path clear was missed) and would otherwise
-// pin Checks to the previous branch's PR on every refresh.
+// Why: a linked PR is branch-scoped; it's stale once the worktree switched branches with neither push target nor HEAD at the PR head, else Checks stays pinned to the old branch's PR.
 export function shouldClearBranchMismatchedLinkedOpenPR(args: {
   pr: PRInfo | null
   linkedPRNumber: number | null
@@ -1150,16 +1074,14 @@ export function shouldClearBranchMismatchedLinkedOpenPR(args: {
   return (
     linkedPRNumber != null &&
     pr?.number === linkedPRNumber &&
-    // Draft reviews are open PRs too; their distinct renderer state must not
-    // leave the same stale durable link permanently wedged after a branch switch.
+    // Draft reviews are open PRs too; don't let their distinct renderer state leave a stale durable link wedged after a branch switch.
     (pr.state === 'open' || pr.state === 'draft') &&
     requestHeadOid !== null &&
     headRefName !== '' &&
     currentBranch !== '' &&
     headRefName !== currentBranch &&
     (pushTargetBranch === null || pushTargetBranch !== headRefName) &&
-    // A worktree parked on the PR's own head commit is the same line of work
-    // (e.g. a PR checkout under a renamed local branch); keep the link.
+    // A worktree parked on the PR's head commit is the same line of work (e.g. renamed local branch); keep the link.
     !(pr.headSha != null && pr.headSha === requestHeadOid)
   )
 }
@@ -1175,8 +1097,7 @@ function shouldApplyBranchMismatchedLinkedPRClear(args: {
     Boolean(worktree) &&
     requestHeadOid !== null &&
     worktree?.linkedPR === linkedPRNumber &&
-    // Branch-scoped: only clear while the worktree is still on the branch the
-    // mismatch was computed against; a newer switch gets its own validation.
+    // Branch-scoped: clear only while still on the branch the mismatch was computed against; a newer switch re-validates.
     worktree.branch.replace(/^refs\/heads\//, '') === branch.replace(/^refs\/heads\//, '') &&
     worktree.head === requestHeadOid &&
     worktree.isBare !== true &&
@@ -1217,9 +1138,7 @@ function buildPRRefreshCandidate(
     true
   )
   const cachedFallbackPRNumber = cachedPR?.number ?? null
-  // Why: a merged PR stays a valid fallback when the worktree sits on its head or
-  // on a commit confirmed to be part of the PR; anything else means the branch
-  // moved on and the number must not resurrect the old merged PR.
+  // Why: a merged PR is a valid fallback only while the worktree sits on its head or a confirmed-contained commit — else the branch moved on.
   const cachedMergedPRMovedPastHead =
     worktree.linkedPR == null &&
     cachedPR?.state === 'merged' &&
@@ -1246,8 +1165,7 @@ function buildPRRefreshCandidate(
     cacheKey,
     worktreeId: worktree.id,
     currentHeadOid: worktree.head ?? null,
-    // Why: persisted linked PR metadata is exact, while PR cache numbers are
-    // only fallback hints after branch lookup misses.
+    // Why: persisted linked PR metadata is exact; PR cache numbers are only fallback hints after branch-lookup misses.
     linkedPRNumber: worktree.linkedPR ?? null,
     fallbackPRNumber,
     fallbackPRSource,
@@ -1294,8 +1212,7 @@ function githubHostedReviewFallbackPRNumber(
 function shouldClearHostedReviewForNoGitHubPR(
   entry: AppState['hostedReviewCache'][string] | undefined
 ): boolean {
-  // Why: a GitHub-only miss should not create or refresh provider-neutral
-  // branch misses that suppress discovery for GitLab/other hosted reviews.
+  // Why: a GitHub-only miss must not suppress GitLab/other hosted-review discovery via provider-neutral branch misses.
   if (!entry) {
     return false
   }
@@ -1390,8 +1307,7 @@ function syncHostedReviewCacheFromGitHubPRResult(args: {
   if (args.pr && hostedReviewEntry?.data && hostedReviewEntry.data.provider !== 'github') {
     return { cache: args.cache, accepted: false }
   }
-  // Why: a hosted-review row may only protect itself from an authoritative
-  // miss when the paired PR cache is preserving a terminal, head-current PR.
+  // Why: a hosted-review row survives an authoritative miss only when the paired PR cache preserves a terminal, head-current PR.
   if (
     !args.pr &&
     args.linkedPRNumber == null &&
@@ -1429,8 +1345,7 @@ function shouldWritePRCacheForHostedReviewSync(args: {
   linkedPRNumber?: number | null
   fallbackPRNumber?: number | null
 }): boolean {
-  // Why: PR-status grouping reads prCache while cards read hostedReviewCache.
-  // If a GitHub PR result was rejected for the card, don't let grouping drift.
+  // Why: grouping reads prCache while cards read hostedReviewCache; keep them from drifting when a result is rejected for the card.
   if (args.hostedReviewSyncAccepted) {
     return true
   }
@@ -1465,13 +1380,10 @@ function shouldPreserveExistingPRForFallbackMiss(args: {
   ) {
     return false
   }
-  // Why: the common found/non-merged paths do not depend on worktree state.
-  // Gate the global lookup so batched refresh aliases do not multiply full scans.
+  // Why: gate the global worktree scan so batched refresh aliases don't multiply full scans (common paths don't need it).
   const worktree = args.worktreeId ? findWorktreeById(args.state, args.worktreeId) : null
   const worktreeHead = worktree?.head
-  // Why: merged branch PRs are only safe to keep when cached PR metadata still
-  // matches the commit this stored worktree is actually on — exactly, or via a
-  // head confirmed to be part of the merged PR.
+  // Why: keep a merged PR only when its cached head matches the worktree head — exactly or a confirmed-contained commit.
   const preservesMergedPRForCurrentHead =
     typeof worktreeHead === 'string' &&
     worktreeHead.length > 0 &&
@@ -1690,10 +1602,7 @@ function applyGitHubPRResultToCaches(args: {
   }
 }
 
-/**
- * Evict the oldest entries from a cache record when it exceeds the max size.
- * Returns a pruned copy, or the original reference if no eviction was needed.
- */
+/** Evicts the oldest entries when over max size; returns a pruned copy, or the original reference if nothing was evicted. */
 function evictStaleEntries<T extends { fetchedAt: number }>(
   cache: Record<string, T>,
   maxEntries = MAX_CACHE_ENTRIES
@@ -1721,11 +1630,7 @@ function withBoundedCacheEntry<T extends { fetchedAt: number }>(
   return evictStaleEntries({ ...cache, [key]: entry })
 }
 
-// Why: the prRefresh* maps are keyed by PR cache key (repo/branch/execution-host)
-// — an ephemeral, unbounded key space over a long session. They have no
-// `fetchedAt` to sort by, so bound them by insertion order (oldest-touched keys
-// evicted first; the writers move each touched key to the end). An evicted
-// long-idle branch simply restarts from a clean state, which is acceptable.
+// Why: prRefresh* maps have no `fetchedAt` to sort by, so bound them by insertion order (oldest-touched evicted first; an evicted long-idle branch restarts clean).
 function capRecordByInsertionOrder<T>(
   record: Record<string, T>,
   maxEntries = MAX_CACHE_ENTRIES
@@ -1748,12 +1653,7 @@ function capPrRefreshSequences(
   return capRecordByInsertionOrder(sequences, maxEntries)
 }
 
-// Why: prRefreshStates backs visible status pills (refreshing/queued/paused/error)
-// so — unlike the invisible sequence guard — eviction must never drop an in-progress
-// indicator. Bound it well above any realistic tracked-branch count, and when over
-// cap evict *settled* statuses (error/skipped) first; only fall back to evicting an
-// active (in-flight/queued/paused) entry as a last-resort hard memory bound that
-// realistic usage never reaches. Evicted entries self-heal on the next refresh event.
+// Why: backs visible status pills, so evict *settled* (error/skipped) before active entries and never drop an in-progress indicator; evicted entries self-heal on next refresh.
 const MAX_PR_REFRESH_STATE_ENTRIES = 2000
 const SETTLED_PR_REFRESH_STATUSES = new Set<PRRefreshState['status']>(['error', 'skipped'])
 const ACTIVE_PR_REFRESH_STATUSES = new Set<PRRefreshState['status']>([
@@ -1767,9 +1667,7 @@ function isPRRefreshStateExpired(state: PRRefreshState, now: number): boolean {
   return expiryAt !== null && now > expiryAt
 }
 
-/**
- * Captures the exact refresh snapshot a later timeout or request is allowed to clear.
- */
+/** Captures the exact refresh snapshot a later timeout or request is allowed to clear. */
 export function buildGitHubPRRefreshStateClearToken(
   state: PRRefreshState | undefined,
   sequences: Record<string, number>,
@@ -1785,9 +1683,7 @@ export function buildGitHubPRRefreshStateClearToken(
   }
 }
 
-/**
- * Returns the wall-clock expiry for transient refresh states; settled states persist.
- */
+/** Returns the wall-clock expiry for transient refresh states; settled states persist. */
 export function getGitHubPRRefreshStateExpiryAt(state: PRRefreshState | undefined): number | null {
   if (!state) {
     return null
@@ -1807,9 +1703,7 @@ function isExpiredActivePRRefreshState(state: PRRefreshState, now: number): bool
   return ACTIVE_PR_REFRESH_STATUSES.has(state.status) && isPRRefreshStateExpired(state, now)
 }
 
-/**
- * Reads refresh state for UI selectors while hiding stale active entries from view.
- */
+/** Reads refresh state for UI selectors while hiding stale active entries from view. */
 export function getEffectiveGitHubPRRefreshState(
   states: Record<string, PRRefreshState>,
   cacheKey: string,
@@ -1907,10 +1801,7 @@ export type GitHubSlice = {
   prRefreshSequences: Record<string, number>
   prRefreshStates: Record<string, PRRefreshState>
   prVisibleRefreshGeneration: number
-  // Why: keyed by repoId + limit + query so remote repos with the same path on
-  // different SSH targets do not share issue/PR results.
-  // from cache instantly on mount (and on hover-prefetch from sidebar buttons)
-  // while a background refresh keeps the list fresh.
+  // Why: keyed by repoId + limit + query so same-path repos on different SSH targets don't share results.
   workItemsCache: Record<string, CacheEntry<GitHubWorkItem[]>>
   fetchPRForBranch: (
     repoPath: string,
@@ -1994,11 +1885,7 @@ export type GitHubSlice = {
     token: PRRefreshStateClearToken,
     now?: number
   ) => void
-  /**
-   * Why: returns cached work items immediately (null if none) and fires a
-   * background refresh when stale. Callers can render the cached list while
-   * the SWR revalidate hydrates the latest.
-   */
+  /** SWR: returns cached work items immediately (null if none) and fires a background refresh when stale. */
   getCachedWorkItems: (
     repoId: string,
     limit: number,
@@ -2006,14 +1893,7 @@ export type GitHubSlice = {
     repoPath?: string,
     sourceContext?: TaskSourceContext | null
   ) => GitHubWorkItem[] | null
-  /**
-   * Why: the Tasks view header reads sources from the cache to render the
-   * "Issues from owner/repo" indicator, and the Tasks empty/partial banner
-   * reads `error` here to show the retry affordance. Returning a thin view of
-   * the cache entry (never the items) keeps this a cheap selector the
-   * component can subscribe to without dragging the whole work-item array
-   * through the equality check.
-   */
+  /** Returns a thin view (sources + error, never items) so it stays a cheap selector without dragging the whole work-item array through the equality check. */
   getWorkItemsSourcesAndError: (
     repoId: string,
     limit: number,
@@ -2021,19 +1901,8 @@ export type GitHubSlice = {
     repoPath?: string
   ) => { sources: WorkItemsCacheSources | null; error: WorkItemsCacheError | null }
   /**
-   * Why: the dialog renders the "Issue from owner/repo" chip for a single work
-   * item but may be opened before the Tasks view has populated the primary
-   * `(repoPath, PER_REPO_FETCH_LIMIT, '')` cache entry — e.g. when the user
-   * searches for an issue by query. Falls back to scanning `workItemsCache`
-   * for any entry keyed by `${repoPath}::` that carries resolved sources,
-   * returning that entry's `sources` directly. Sources are repo-level
-   * (query-independent), so any sibling entry is safe to reuse.
-   *
-   * Returning a single stable reference means the dialog can subscribe to just
-   * this selector instead of the whole `workItemsCache`, so unrelated cache
-   * writes don't force a re-render. Cache entries are fully replaced (not
-   * mutated) on every write, so reference equality is preserved between
-   * unchanged entries.
+   * Falls back to any `${repoPath}::` cache entry with resolved sources when the primary entry isn't populated yet — sources are repo-level (query-independent), so any sibling is safe to reuse.
+   * Returns a single stable reference so the dialog can subscribe to just this selector; entries are replaced (not mutated) on write, preserving reference equality between unchanged entries.
    */
   getWorkItemsAnySourcesForRepo: (
     repoId: string,
@@ -2048,17 +1917,8 @@ export type GitHubSlice = {
     options?: FetchOptions
   ) => Promise<GitHubWorkItem[]>
   /**
-   * Why: fan out a single work-item query across multiple repos. Partial
-   * failures don't reject — a repo that both fails to fetch *and* has no
-   * cached fallback contributes nothing and increments `failedCount`, which
-   * the caller surfaces as a "N of M projects failed to load" banner. A repo
-   * served from stale cache on rejection is NOT counted as failed — matching
-   * the single-repo behavior of quietly serving stale data.
-   *
-   * `githubUnavailable` is true when every selected GitHub source refresh failed
-   * because GitHub was unreachable/unavailable (5xx outage, network, or rate
-   * limit), even when stale cache data remains available. The caller uses it to
-   * attribute the stale/empty list instead of showing a normal-looking result.
+   * Fan out one work-item query across repos; partial failures don't reject — a repo with no cached fallback increments `failedCount`, but one served stale cache on rejection isn't counted.
+   * `githubUnavailable`: every selected GitHub source refresh failed because GitHub was unreachable (5xx/network/rate-limit), even if stale cache remains — lets the caller attribute the stale/empty list.
    */
   fetchWorkItemsAcrossRepos: (
     repos: {
@@ -2096,10 +1956,7 @@ export type GitHubSlice = {
     query: string,
     perRepoLimit: number
   ) => Promise<{ totalCount: number; totalPages: number }>
-  /**
-   * Fire-and-forget prefetch used by UI entry points (hover/focus of the
-   * "new workspace" buttons) to warm the cache before the page mounts.
-   */
+  /** Fire-and-forget prefetch to warm the cache before the page mounts (hover/focus of the "new workspace" buttons). */
   prefetchWorkItems: (
     repoId: string,
     repoPath: string,
@@ -2113,25 +1970,9 @@ export type GitHubSlice = {
     repoId?: string | null,
     options?: GitHubPatchWorkItemOptions
   ) => void
-  /**
-   * Monotonic counter bumped whenever a repo's issue-source preference is
-   * flipped. Subscribers (TaskPage's fetch effect) include this in their
-   * dependency array to force a re-fetch after preference changes — the
-   * work-items cache eviction alone isn't enough because the effect keys on
-   * `selectedRepos`/`appliedTaskSearch`/`taskRefreshNonce` and wouldn't
-   * otherwise notice the cache went empty.
-   */
+  /** Monotonic counter bumped on issue-source preference flips; subscribers include it in their deps to force a re-fetch, since cache eviction alone won't trip effects keyed on selectedRepos/search/nonce. */
   workItemsInvalidationNonce: number
-  /**
-   * Persist a per-repo issue-source preference, update the local Repo record
-   * for reactive UI, and invalidate all cached work-items entries that key
-   * off this repo's identity so the Tasks list re-fetches against the new source.
-   *
-   * Why invalidate all `${repoId}::*` keys and not only the primary entry:
-   * preferences flip the issue source for every list query (query-less +
-   * user-entered queries alike). Surgical eviction of the primary key alone
-   * would leave stale results in alternate-query cache lines.
-   */
+  /** Persist the preference, update the local Repo record, and invalidate all `${repoId}::*` cache keys — not just the primary — so alternate-query lines don't serve stale results after the source flips. */
   setIssueSourcePreference: (
     repoId: string,
     repoPath: string,
@@ -2165,22 +2006,11 @@ export type GitHubSlice = {
     rowId: string,
     issueType: { id: string; name: string; color: string | null; description: string | null } | null
   ) => Promise<GitHubProjectMutationResult>
-  /** Optimistic, IPC-free patcher for a single `projectViewCache` row's
-   *  `content`. Used by GitHubItemDialog when `projectOrigin` is set so the
-   *  Project table re-renders immediately after dialog edits — `patchWorkItem`
-   *  alone only walks `workItemsCache` and would leave the Project view stale
-   *  until the next refresh. The actual write is dispatched separately via
-   *  the slug-addressed update IPCs. */
+  /** Optimistic, IPC-free patcher for a single `projectViewCache` row's `content`; `patchWorkItem` only walks `workItemsCache` and would leave the Project view stale until the next refresh. */
   patchProjectRowContent: (cacheKey: string, rowId: string, patch: ProjectRowContentPatch) => void
 }
 
-/**
- * Normalizes the `github.prForBranch` runtime RPC result into a
- * {@link PRRefreshOutcome}. Current hosts return the full outcome (with a
- * `kind`), so a runtime `upstream-error` is preserved instead of collapsing to a
- * false accepted "no PR". A legacy host that still returns `PRInfo | null` is
- * mapped to `found` / `no-pr` to preserve backward behavior on that host only.
- */
+/** Normalizes `github.prForBranch` into a {@link PRRefreshOutcome}: preserves a runtime `upstream-error` instead of collapsing to a false "no PR"; a legacy host returning `PRInfo | null` maps to `found`/`no-pr`. */
 function normalizeRuntimePRForBranchOutcome(
   result: PRRefreshOutcome | PRInfo | null
 ): PRRefreshOutcome {
@@ -2243,8 +2073,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const sourceScope = projectViewSourceScope(get().settings)
     const requestKey = projectViewRequestKey(args, sourceScope)
 
-    // Fast path: when the caller supplies `viewId`, we already know the
-    // resolved cache key and can serve a fresh entry directly.
+    // Fast path: a caller-supplied `viewId` gives the resolved cache key up front, so serve a fresh entry directly.
     const maybeKnownKey = args.viewId
       ? projectViewCacheKey(
           args.ownerType,
@@ -2264,9 +2093,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
     const existing = inflightProjectViewRequests.get(requestKey)
     if (existing) {
-      // Why: mirror fetchWorkItems force-refresh semantics — a forcing caller
-      // must not silently dedupe to a non-forcing in-flight request; wait for
-      // that to settle (result discarded) and then issue a fresh forced call.
+      // Why: a forcing caller must not dedupe to a non-forcing in-flight request; wait for it to settle, then issue a fresh forced call (mirrors fetchWorkItems).
       if (options?.force && !existing.force) {
         await existing.promise.catch(() => {})
       } else {
@@ -2303,9 +2130,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
             })
           }))
         } else if (maybeKnownKey) {
-          // Only stamp the error onto the cache when we have a resolved key
-          // (i.e. caller supplied viewId). Otherwise we have nowhere to write
-          // it — the renderer classifies the error directly from the envelope.
+          // Why: only stamp the error when we have a resolved key; without one there's nowhere to write it and the renderer classifies from the envelope.
           set((s) => ({
             projectViewCache: withBoundedCacheEntry(s.projectViewCache, maybeKnownKey, {
               data: s.projectViewCache[maybeKnownKey]?.data ?? null,
@@ -2316,9 +2141,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
         }
         return envelope
       } catch (err) {
-        // Why: IPC boundary must not throw across the promise — wrap any
-        // unexpected error in the classified envelope so the renderer has
-        // a single shape to render.
+        // Why: the IPC boundary must not throw across the promise — wrap unexpected errors in the classified envelope for a single renderer shape.
         console.error('Failed to fetch GitHub project view:', err)
         return {
           ok: false,
@@ -2530,13 +2353,9 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const optimisticRow: GitHubProjectRow = { ...previousRow, content: nextContent }
     applyRowPatch(set, cacheKey, rowId, optimisticRow)
 
-    // Why: PRs and issues both accept label/assignee edits through the issue
-    // endpoint — GitHub PRs are issues for labels/assignees. Title/body for
-    // PRs goes through updatePullRequestBySlug; for issues through
-    // updateIssueBySlug. We dispatch both as needed.
+    // Why: labels/assignees go through the issue endpoint for both (GitHub PRs are issues for those); title/body split PR→updatePullRequestBySlug vs issue→updateIssueBySlug.
     let envelope: GitHubProjectMutationResult = { ok: true }
-    // Why: Project rows may be slug-only and have no registered Orca repo.
-    // Fall back to the view source encoded in the cache key, not focused host.
+    // Why: slug-only Project rows have no registered Orca repo, so fall back to the view source in the cache key, not the focused host.
     const target = getActiveRuntimeTarget(
       settingsForProjectRowOwner(
         get(),
@@ -2663,8 +2482,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       content: { ...previousRow.content, issueType }
     }
     applyRowPatch(set, cacheKey, rowId, optimistic)
-    // Why: slug-only Project rows still belong to the source host that loaded
-    // the view; focused host may have changed after the table was fetched.
+    // Why: slug-only Project rows belong to the host that loaded the view, which may differ from the now-focused host.
     const target = getActiveRuntimeTarget(
       settingsForProjectRowOwner(
         get(),
@@ -2713,11 +2531,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       nextContent.body = patch.body
     }
     if (patch.state !== undefined) {
-      // Why: ProjectV2 row.state mirrors GitHub's UPPERCASE state enum
-      // ('OPEN' | 'CLOSED' | 'MERGED'). The dialog tracks lowercase
-      // ('open' | 'closed') matching `GitHubWorkItem['state']`. Translate
-      // here so the optimistic patch matches the canonical row shape and
-      // the next authoritative fetch overwrites cleanly.
+      // Why: ProjectV2 row.state is GitHub's UPPERCASE enum ('OPEN'|'CLOSED'|'MERGED') but the dialog tracks lowercase; upper-case so the patch matches the canonical row shape.
       nextContent.state = patch.state.toUpperCase()
     }
     if (patch.labels !== undefined) {
@@ -2806,9 +2620,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const inflightKey = workItemsInflightRequestKey(key, requestContext.target)
     const existing = inflightWorkItemsRequests.get(inflightKey)
     if (existing) {
-      // Why: a user-initiated refresh (force=true) must not silently dedupe to
-      // a less-fresh fetch already in flight. noCache=true is stricter than a
-      // cacheable forced landing probe because it must bypass gh api's cache too.
+      // Why: a forcing/noCache caller must not dedupe to a weaker in-flight fetch (noCache is stricter — it must bypass gh api's cache too).
       if ((options?.force && !existing.force) || (options?.noCache && !existing.noCache)) {
         await existing.promise.catch(() => {})
       } else {
@@ -2824,19 +2636,11 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           query: query || undefined,
           ...(options?.noCache ? { noCache: true } : {})
         })
-        // Why: stamp repoId at the renderer fetch boundary so every downstream
-        // consumer (cross-repo merge, row rendering, drawer) can rely on the
-        // field being present. Main doesn't know Orca's Repo.id.
+        // Why: stamp repoId at the fetch boundary so downstream consumers can rely on it — main doesn't know Orca's Repo.id.
         const items: GitHubWorkItem[] = envelope.items.map((item) => ({ ...item, repoId }))
-        // Why: only surface the issues-side error in the cache entry. The
-        // parent design doc §2 scopes feature 1 to the new class of silent
-        // wrongness introduced by the issue-source split in #1076; PR-side
-        // failures existed before and are out of scope for this banner.
+        // Why: only surface issues-side errors here; PR-side failures predate the issue-source split (#1076) and are out of scope for this banner (design doc §2).
         const issuesError = envelope.errors?.issues
-        // Why: if the main process resolved `errors.issues` but not `sources.issues`,
-        // the renderer has no slug to render in the banner copy, so the error is
-        // dropped from the cache entry. Log it so this rare case is at least visible
-        // in devtools rather than disappearing silently.
+        // Why: errors.issues without sources.issues has no slug for the banner, so it's dropped from the cache; log it so this rare case is visible in devtools.
         if (issuesError && !envelope.sources.issues) {
           console.warn(
             '[workItems] dropping issues-side error with no resolved source:',
@@ -2853,14 +2657,11 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           currentRepo,
           options?.sourceContext
         )
-        // Why: host focus changes are allowed, but repo ownership changes mean
-        // this response belongs to an older execution host bucket.
+        // Why: repo ownership changed, so this response belongs to an older execution-host bucket (host focus changes alone are fine).
         if ((currentHostId ?? null) !== (ownerHostId ?? null)) {
           return items
         }
-        // Why: clearing in-flight entries lets the next fetch start, but the
-        // old promise can still settle. Do not let pre-flip source data
-        // repopulate the cache after the invalidation nonce changes.
+        // Why: the old promise can still settle after the in-flight clear; don't let pre-flip source data repopulate the cache once the invalidation nonce changed.
         if (get().workItemsInvalidationNonce !== requestInvalidationNonce) {
           return items
         }
@@ -2875,8 +2676,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
         }))
         return items
       } catch (err) {
-        // Why: surface the error to the caller; keep stale cache entry so the
-        // UI can continue to render something useful while the user retries.
+        // Why: rethrow but keep the stale cache entry so the UI still renders while the user retries.
         if (!isGitHubWorkItemsSshRemoteRequiredError(err)) {
           console.error('Failed to fetch GitHub work items:', err)
         }
@@ -2912,12 +2712,8 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
             sourceContext: r.sourceContext ?? options?.sourceContext
           })
         } catch (err) {
-          // Why: fall back to any cache entry (stale or not) before declaring
-          // this repo failed. Matches single-repo behavior of silently serving
-          // stale data on error. A repo is only counted as failed when it has
-          // nothing at all to contribute.
-          // Why: must use perRepoLimit (not displayLimit) so the cache key
-          // matches what fetchWorkItems wrote.
+          // Why: fall back to any cache entry (stale or not) before declaring this repo failed; only count as failed when it has nothing to contribute.
+          // Why: use perRepoLimit (not displayLimit) so the cache key matches what fetchWorkItems wrote.
           if (isGitHubWorkItemsSshRemoteRequiredError(err)) {
             skippedSourceCount += 1
             return [] as GitHubWorkItem[]
@@ -2947,10 +2743,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       })
     )
     const merged = sortWorkItemsByNumber(perProjectResults.flat()).slice(0, displayLimit)
-    // Why: one repo can fail with a 5xx while another succeeds (or fails for a
-    // permission reason). Only claim a global availability failure when every
-    // eligible source failed for a GitHub reachability reason; intentionally
-    // skipped SSH repos are not GitHub sources for this calculation.
+    // Why: only claim global unavailability when every eligible source failed for a reachability reason; skipped SSH repos aren't GitHub sources here.
     const githubUnavailable =
       requestFailureCount > 0 &&
       requestFailureCount === repos.length - skippedSourceCount &&
@@ -2986,13 +2779,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
             query: query || undefined,
             page
           })
-          // Why: page-N partial failures don't participate in the cache's per-repo
-          // error banner (which is keyed on the initial-fetch cache entry). Log the
-          // classified issues-side error so pagination failures are at least
-          // observable in logs rather than silently truncating the merged list. A
-          // richer surface would require threading per-page errors back to the
-          // caller and wiring a transient pagination banner — deferred per parent
-          // design doc §6 scope.
+          // Why: page-N failures aren't in the per-repo banner (keyed on the initial fetch); log them so pagination failures are observable instead of silently truncating (richer surface deferred, design doc §6).
           if (envelope.errors?.issues) {
             console.warn(
               `[workItems] next page ${r.repoId} issues-side partial failure:`,
@@ -3023,9 +2810,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const normalizedLimit = Math.max(1, Math.floor(perRepoLimit))
     const counts = await Promise.all(
       repos.map(async (r) => {
-        // Why: same stampede cap as the item-fetch paths — without a slot,
-        // a 90-repo selection dispatches 90 concurrent count IPCs before the
-        // main-side rate-limit guard can see the first 403.
+        // Why: same stampede cap as item-fetch — without a slot a 90-repo selection fires 90 concurrent count IPCs before the main-side rate-limit guard sees the first 403.
         await acquireWorkItemSlot()
         try {
           const requestState = get()
@@ -3052,8 +2837,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     )
     return {
       totalCount: counts.reduce((sum, count) => sum + count, 0),
-      // Why: each repo advances independently by the same numbered page. A sum
-      // divided by page width undercounts when one repo owns most results.
+      // Why: repos advance independently by page, so take the max across repos — a sum/page-width undercounts when one repo owns most results.
       totalPages: counts.reduce(
         (maxPages, count) => Math.max(maxPages, Math.ceil(count / normalizedLimit)),
         0
@@ -3085,7 +2869,6 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       options?.sourceContext
     )
     const inflightKey = workItemsInflightRequestKey(key, requestContext.target)
-    // Skip when the cache is fresh or a request is already in flight.
     if (isFresh(cached, WORK_ITEMS_CACHE_TTL) || inflightWorkItemsRequests.has(inflightKey)) {
       return
     }
@@ -3133,10 +2916,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       repo?.executionHostId,
       repo !== undefined
     )
-    // Why: if a prior caller without a linkedPR cached `null` for this branch,
-    // the worktree-card lookup (which has a linked PR fallback) would otherwise
-    // return null forever. Refetch when the cached miss could now resolve via
-    // the linkedPR path.
+    // Why: a prior linkedPR-less caller may have cached null for this branch; refetch so the cached miss can now resolve via the linkedPR path.
     const linkedPRNumber = options?.linkedPRNumber ?? null
     const explicitFallbackPRNumber = options?.fallbackPRNumber ?? null
     const hostedReviewFallbackPRNumber = githubHostedReviewFallbackPRNumber(
@@ -3159,10 +2939,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const linkedRefetch =
       cached?.data === null && (linkedPRNumber !== null || fallbackPRNumber !== null)
     if (!options?.force && !linkedRefetch && isFresh(cached)) {
-      // Why: a fresh cache hit still carries the head-scoped divergence signal.
-      // If a prior clear was declined because the head moved mid-request and the
-      // worktree is now back on that diverged head, clear the durable link the
-      // cache would otherwise keep serving until it expires.
+      // Why: even a fresh cache hit carries the head-scoped divergence signal; if a prior clear was declined for a mid-request head move and we're back on that head, clear the durable link.
       if (
         options?.worktreeId &&
         linkedPRNumber != null &&
@@ -3280,11 +3057,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
         const pr: PRInfo | null =
           outcome.kind === 'found' ? outcome.pr : outcome.kind === 'no-pr' ? null : null
         if (outcome.kind === 'upstream-error') {
-          // Why: the runtime RPC path does not flow through the coordinator
-          // broadcast that populates prRefreshStates on native execution, so a
-          // runtime/SSH gh failure would otherwise show generic "checking" copy.
-          // Record the classified error + schedule here so the Checks panel shows
-          // the same classified failure copy as native (design criterion 2).
+          // Why: the runtime RPC path skips the coordinator broadcast that fills prRefreshStates on native, so record the classified error here for Checks parity with native (design criterion 2).
           if (runtimeRepo && prRequestGenerations.get(cacheKey) === generation) {
             set((s) => {
               const nextStates = { ...s.prRefreshStates }
@@ -3307,8 +3080,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           let skippedStaleLinkedPRLookup = false
           let didUpdatePRCache = false
           set((s) => {
-            // Why: unlinking a PR while an exact linked-PR lookup is in flight
-            // must prevent that older result from restoring the manual link UI.
+            // Why: unlinking a PR mid exact-linked-PR-lookup must stop the older result from restoring the manual link UI.
             if (isStaleExactLinkedPRLookup(s, options?.worktreeId, linkedPRNumber)) {
               skippedStaleLinkedPRLookup = true
               return {}
@@ -3354,8 +3126,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
             linkedPRNumber != null &&
             shouldClearDivergedLinkedMergedPR({ pr, linkedPRNumber, requestHeadOid })
           ) {
-            // Why: only clear the durable link that produced this exact probe;
-            // branch/head drift means the stale result no longer owns the worktree.
+            // Why: only clear the durable link that produced this exact probe; drift means the stale result no longer owns the worktree.
             void get().updateWorktreeMeta(
               options.worktreeId,
               { linkedPR: null },
@@ -3391,8 +3162,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
               options.worktreeId,
               { linkedPR: null },
               {
-                // Why: the branch-scoped PR refetch below updates both GitHub
-                // caches; the generic metadata refresh would duplicate provider work.
+                // Why: the branch-scoped PR refetch below updates both caches; the generic metadata refresh would duplicate provider work.
                 suppressHostedReviewRefresh: true,
                 shouldApply: () =>
                   shouldApplyBranchMismatchedLinkedPRClear({
@@ -3408,8 +3178,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
                   })
               }
             )
-            // Re-resolve by branch right away so visible Checks recover on this
-            // refresh instead of keeping the stale linked PR cached.
+            // Re-resolve by branch now so Checks recover this refresh instead of serving the stale linked PR.
             void get().fetchPRForBranch(repoPath, branch, {
               force: true,
               repoId,
@@ -4010,8 +3779,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       repo !== undefined
     )
 
-    // Optimistic update: toggle isResolved on all comments in this thread immediately
-    // so the UI feels instant. Reverts if the API call fails.
+    // Optimistic toggle of isResolved for this thread; reverts if the API call fails.
     const prev = get().commentsCache[cacheKey]?.data
     if (prev) {
       set((s) => ({
@@ -4135,9 +3903,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
   },
 
   applyGitHubPRRefreshEvent: (event) => {
-    // Why: the sidebar/left-list refresh for local repos flows through the main
-    // PR coordinator (not fetchPRForBranch), so it must run the same guarded
-    // clear when main stamps a merged linked PR whose head has diverged.
+    // Why: local-repo sidebar refresh routes through the main PR coordinator, so run the same guarded diverged-merged-PR clear.
     const divergedLinkedPRClears: {
       worktreeId: string
       linkedPRNumber: number
@@ -4173,8 +3939,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           }
           continue
         }
-        // Why: delete-then-set moves this key to the end of insertion order so
-        // capPrRefreshSequences evicts genuinely idle keys, not active ones.
+        // Why: delete-then-set re-orders this key last so capPrRefreshSequences evicts idle, not active, keys.
         delete nextSequences[alias.cacheKey]
         nextSequences[alias.cacheKey] = event.sequence
         changed = true
@@ -4271,14 +4036,12 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
                 })()
               : null
           const linkedPRNumber = alias.linkedPRNumber ?? null
-          // Why: one coordinator outcome can fan out to many linked aliases.
-          // Build one lazy index instead of rescanning all worktrees per alias.
+          // Why: one outcome fans out to many aliases; build one lazy index instead of rescanning worktrees per alias.
           const worktreeLookupIndex =
             alias.worktreeId && linkedPRNumber != null
               ? (linkedWorktreeLookupIndex ??= buildWorktreeLookupIndex(s))
               : undefined
-          // Why: queued local refreshes may finish after the user unlinks an
-          // exact PR; those older results must not restore the manual-link UI.
+          // Why: a queued refresh finishing after the user unlinks an exact PR must not restore the manual-link UI.
           if (
             isStaleExactLinkedPRLookup(s, alias.worktreeId, linkedPRNumber, worktreeLookupIndex)
           ) {
@@ -4295,8 +4058,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
                     worktreeLookupIndex
                   )
                 : null
-            // Why: only an event that won the sequence gate above owns metadata
-            // side effects; rejected late outcomes must not unlink a newer PR.
+            // Why: only the sequence-gate winner owns metadata side effects; late outcomes must not unlink a newer PR.
             if (
               worktree &&
               linkedPRNumber != null &&
@@ -4379,13 +4141,10 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
               s.hostedReviewCache[hostedReviewCacheKey]
             )
           } else {
-            // Why: rate-limit pauses/skips can follow an in-flight broadcast
-            // without an outcome; the cached request-start snapshot is no
-            // longer live and would otherwise accumulate per refresh sequence.
+            // Why: pause/skip can follow an in-flight broadcast with no outcome; drop the stale request-start snapshot.
             deletePRRefreshStartedEntry(event.sequence, alias.cacheKey)
           }
-          // Why: delete-then-set moves this key to the end of insertion order so
-          // capRecordByInsertionOrder evicts genuinely idle keys, not active ones.
+          // Why: delete-then-set re-orders this key last so capRecordByInsertionOrder evicts idle, not active, keys.
           delete nextStates[alias.cacheKey]
           const isPaused = event.status === 'paused'
           nextStates[alias.cacheKey] = {
@@ -4394,9 +4153,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
             updatedAt: Date.now(),
             pausedUntil: event.pausedUntil,
             skippedReason: event.skippedReason,
-            // Why: a paused refresh is a rate-limit gate. Map its pausedUntil into
-            // the unified schedule so the panel shows the auto-retry time and
-            // disables manual Retry until the limit resets.
+            // Why: paused = rate-limit gate; map pausedUntil into the schedule to show auto-retry and disable manual Retry.
             nextAutoRetryAt: isPaused ? event.pausedUntil : undefined,
             retryDisabledUntil: isPaused ? event.pausedUntil : undefined
           }
@@ -4406,8 +4163,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       return changed
         ? {
             prRefreshSequences: capPrRefreshSequences(nextSequences),
-            // Why: bound prRefreshStates too (same unbounded PR-cache-key space),
-            // but with status-aware eviction so visible in-progress pills survive.
+            // Why: bound prRefreshStates with status-aware eviction so visible in-progress pills survive.
             prRefreshStates: capPrRefreshStates(nextStates),
             prCache: nextPRCache,
             hostedReviewCache: nextHostedReviewCache
@@ -4452,9 +4208,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
   },
 
   refreshAllGitHub: () => {
-    // Invalidate comments cache so it refreshes on next access.
-    // Also evict old entries from retained caches to prevent unbounded growth
-    // across many repos and branches over a long-running session.
+    // Clear comments cache; evict stale entries to bound long-session growth across repos/branches.
     set((s) => ({
       commentsCache: {},
       prCache: evictStaleEntries(s.prCache),
@@ -4465,9 +4219,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       prRefreshStates: pruneExpiredPRRefreshStates(s.prRefreshStates)
     }))
 
-    // Why: prRequestGenerations tracks only live inflight fetches and is
-    // cleared when the active request settles. Do not prune it here; deleting
-    // a live generation would make the corresponding response look stale.
+    // Why: don't prune prRequestGenerations here — deleting a live generation makes its response look stale.
 
     // Only re-fetch PR/issue entries that are already stale — skip fresh ones
     const state = get()
@@ -4643,8 +4395,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           ? getTaskSourceCacheScope(options.sourceContext)
           : null
       for (const key of Object.keys(nextCache)) {
-        // Why: task edits from one host/account must not optimistically patch
-        // another host's visually identical GitHub issue or PR cache entry.
+        // Why: don't patch another host/account's visually identical issue/PR cache entry.
         if (sourceScope && key !== sourceScope && !key.startsWith(`${sourceScope}::`)) {
           continue
         }
@@ -4652,8 +4403,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
         if (!entry?.data) {
           continue
         }
-        // Why: GitHub issue/PR ids are only unique within a repo. Cross-repo
-        // task views can contain the same `pr:42` id from multiple repos.
+        // Why: issue/PR ids are only unique within a repo; cross-repo views can share `pr:42`.
         const idx = entry.data.findIndex(
           (item) => item.id === itemId && (!repoId || item.repoId === repoId)
         )
@@ -4670,10 +4420,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
   },
 
   setIssueSourcePreference: async (repoId, repoPath, preference) => {
-    // Why: optimistically patch the local Repo first so the segmented control
-    // reflects the new selection on the same frame. On IPC failure we resync
-    // from disk via `fetchRepos()` below so the UI doesn't lie about what's
-    // persisted.
+    // Why: optimistically patch the local Repo so the segmented control updates this frame; resync via fetchRepos on IPC failure.
     set((s) => ({
       repos: s.repos.map((r) =>
         r.id === repoId
@@ -4685,49 +4432,29 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       )
     }))
     try {
-      // Why: persist via the generic `repos:update` channel rather than a
-      // dedicated gh-namespaced handler. Single write path → single
-      // `repos:changed` broadcast → other windows re-fetch. The store layer
-      // normalizes `'auto'` to `undefined` so the persisted record drops
-      // the key entirely (see main/persistence.ts#updateRepo).
+      // Why: use the generic `repos:update` channel so a single write → single `repos:changed` broadcast re-fetches other windows.
+      // Why: map 'auto' to undefined so persistence drops the key entirely (see main/persistence.ts#updateRepo).
       const updates = { issueSourcePreference: preference === 'auto' ? undefined : preference }
-      // Why: persist to the repo's owner host (same routing as updateRepo) so the
-      // write lands where the repo lives, not on the focused runtime.
+      // Why: route to the repo's owner host (like updateRepo) so the write lands where the repo lives, not the focused runtime.
       const target = getActiveRuntimeTarget(getSettingsForRepoRuntimeOwner(get(), repoId))
       await (target.kind === 'local'
         ? window.api.repos.update({ repoId, updates })
         : callRuntimeRpc(target, 'repo.update', { repo: repoId, updates }, { timeoutMs: 15_000 }))
     } catch (err) {
       console.error('Failed to persist issue-source preference:', err)
-      // Why: surface the persist failure so the user understands why the
-      // pill visually reverts (optimistic patch above → resync via
-      // fetchRepos below). Without this toast, the UI silently snaps back
-      // and the user has no clue the write failed.
+      // Why: without this toast the pill silently snaps back (optimistic patch + resync) and the user wouldn't know the write failed.
       toast.error(
         translate('auto.store.slices.github.d49ef4b944', 'Failed to save issue-source preference'),
         {
           duration: ERROR_TOAST_DURATION
         }
       )
-      // Why: the optimistic patch above may now disagree with disk. Resync
-      // rather than leave a lie on screen. We only refetch repos — the cache
-      // eviction below is still safe to run; worst case we trigger a
-      // harmless re-fetch of work items against the pre-flip preference.
+      // Why: the optimistic patch may now disagree with disk; resync rather than leave a lie on screen.
       void get().fetchRepos()
     }
-    // Why: wipe in-flight dedupe entries for this repo BEFORE bumping the
-    // invalidation nonce. The bump triggers a re-run of TaskPage's fetch
-    // effect; if the inflight map still held a pre-flip entry, the new
-    // dispatch could collapse onto it and skip the source swap. Clearing
-    // first makes the "new fetch gets a fresh request" invariant impossible
-    // to trip on later refactors that change zustand or React flush timing.
+    // Why: clear inflight dedupe BEFORE bumping the nonce so the re-triggered fetch can't collapse onto a pre-flip in-flight entry.
     clearInflightWorkItemsForRepo(repoId, repoPath)
-    // Why: evict every cache entry keyed on this repo AFTER the IPC
-    // resolves. If we evicted before awaiting, an overlapping fetch triggered
-    // by a different subscriber would hit main with the pre-flip persisted
-    // preference and repopulate the cache with stale-source data. Work-items
-    // cache keys are repo-scoped, but we also drop legacy path-scoped entries
-    // that may have been restored from older persisted cache data.
+    // Why: evict AFTER the await so an overlapping fetch can't repopulate with pre-flip data; also drops legacy path-scoped keys.
     set((s) => {
       const prefix = `${repoId}::`
       const legacyPrefix = `${repoPath}::`
@@ -4737,11 +4464,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           next[key] = entry
         }
       }
-      // Why: bump the invalidation nonce so the Tasks list's fetch effect
-      // — which keys on `[selectedRepos, appliedTaskSearch, taskRefreshNonce,
-      // taskSource, workItemsInvalidationNonce]` — re-runs and re-populates
-      // the just-evicted entries. Evicting alone wouldn't trigger the effect
-      // because it doesn't depend on the cache.
+      // Why: the Tasks fetch effect keys on the nonce, not the cache, so bump it to re-run and re-populate the evicted entries.
       return { workItemsCache: next, workItemsInvalidationNonce: s.workItemsInvalidationNonce + 1 }
     })
   },
@@ -4778,9 +4501,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     })
   },
 
-  // Why: activation is the user's strongest freshness signal. A PR can merge
-  // seconds after the last sidebar poll; enqueue through the coordinator so
-  // clicks revalidate PR state without bypassing coalescing/rate-limit guards.
+  // Why: activation is the strongest freshness signal; route through the coordinator to keep coalescing/rate-limit guards.
   refreshGitHubForWorktreeIfStale: (worktreeId) => {
     const state = get()
     let worktree: Worktree | undefined
diff --git a/src/renderer/src/store/slices/repos.ts b/src/renderer/src/store/slices/repos.ts
index 2bb99fa3484..9719e1056af 100644
--- a/src/renderer/src/store/slices/repos.ts
+++ b/src/renderer/src/store/slices/repos.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: repo slice owns local/runtime routing,
-add/remove/reorder side effects, and cross-slice teardown. Splitting it during
-the client-server refactor would obscure the invariants this file is currently
-auditing and preserving. */
+/* eslint-disable max-lines -- Why: repo slice owns local/runtime routing, add/remove/reorder side effects, and cross-slice teardown; splitting mid-refactor would obscure its invariants. */
 import type { StateCreator } from 'zustand'
 import { toast } from 'sonner'
 import type { AppState } from '../types'
@@ -289,8 +286,7 @@ async function warnIfProjectKnownInAnotherProfile(
   activeOrcaProfileId: string | null
 ): Promise<void> {
   const findProjectProfiles = window.api.orcaProfiles?.findProjectProfiles
-  // Why: without a loaded active profile ID the scan cannot exclude the
-  // current profile and would false-positive on the project just added.
+  // Why: without an active profile ID the scan can't exclude the current profile and would false-positive on the just-added project.
   if (!findProjectProfiles || !activeOrcaProfileId) {
     return
   }
@@ -342,9 +338,7 @@ function scheduleSafeAutoForkSync(get: () => AppState, repos: readonly Repo[]):
     )
       .then(() => undefined)
       .catch((error) => {
-        // Why: safe-auto is opportunistic. Auth/protection/divergence failures
-        // should not create startup noise; the settings row exposes Sync Now
-        // for explicit, toast-backed diagnosis.
+        // Why: safe-auto is opportunistic; auth/protection/divergence failures shouldn't add startup noise (Sync Now handles explicit diagnosis).
         console.info('Safe fork auto-sync skipped', error)
       })
       .finally(() => {
@@ -431,8 +425,7 @@ async function fetchProjectHostSetupCompatibility(
       setups: setupResponse.setups.map((setup) => setupWithFetchedOwner(setup, target))
     }
   } catch {
-    // Why: newer clients must still hydrate against older runtimes/preloads
-    // that only know `repo.list`; derive the transitional model locally.
+    // Why: newer clients must hydrate against older runtimes that only know repo.list; derive the transitional model locally.
     return projectHostSetupProjectionFromRepos(repos)
   }
 }
@@ -484,8 +477,7 @@ function mergeProjectCompatibilityProject(base: Project, overlay: Project): Proj
   const project: Project = {
     ...base,
     ...overlay,
-    // Why: all-host startup fetches hosts separately; one host's project record
-    // must not erase repo ownership learned from another host with the same id.
+    // Why: all-host startup fetches hosts separately; one host's record must not erase repo ownership learned from another host with the same id.
     sourceRepoIds: [...new Set([...base.sourceRepoIds, ...overlay.sourceRepoIds])],
     createdAt: Math.min(base.createdAt, overlay.createdAt),
     updatedAt: Math.max(base.updatedAt, overlay.updatedAt)
@@ -527,8 +519,7 @@ function mergeUpdatedProjectCompatibilityProject(
       'localWindowsRuntimePreference' in updated
         ? updated.localWindowsRuntimePreference
         : updates.localWindowsRuntimePreference
-    // Why: project.update returns one host's project record, but preference
-    // clears must still override the cross-host metadata preservation merge.
+    // Why: project.update returns one host's record, but preference clears must override the cross-host metadata-preservation merge.
     if (localWindowsRuntimePreference === undefined) {
       delete project.localWindowsRuntimePreference
     } else {
@@ -598,8 +589,7 @@ function mergePreviousProjectMetadata(
 ): Project {
   const project = mergeProjectCompatibilityProject(previous, current)
   if (hostId === LOCAL_EXECUTION_HOST_ID) {
-    // Why: `localWindowsRuntimePreference` belongs to the local host; a local
-    // refresh that omits it is authoritative and should clear stale renderer state.
+    // Why: localWindowsRuntimePreference belongs to the local host; a local refresh that omits it is authoritative and clears stale renderer state.
     if ('localWindowsRuntimePreference' in current) {
       if (current.localWindowsRuntimePreference === undefined) {
         delete project.localWindowsRuntimePreference
@@ -610,14 +600,12 @@ function mergePreviousProjectMetadata(
       delete project.localWindowsRuntimePreference
     }
   } else if (previous.localWindowsRuntimePreference !== undefined) {
-    // Why: remote runtimes can have their own local Windows preference; they must
-    // not overwrite the client-local project runtime setting.
+    // Why: a remote runtime's local Windows preference must not overwrite the client-local project runtime setting.
     project.localWindowsRuntimePreference = previous.localWindowsRuntimePreference
   }
   return {
     ...project,
-    // Why: fetched project metadata can lag behind repo.list; repo ownership
-    // must track the freshly reconciled repos so removed host repos do not linger.
+    // Why: fetched project metadata can lag repo.list; track ownership to the reconciled repos so removed-host repos don't linger.
     sourceRepoIds: getMergedSourceRepoIdsForHostRefresh(previous, current, reposById, hostId)
   }
 }
@@ -713,8 +701,7 @@ function mergeFetchedProjectCompatibilityForHost({
       return setup.hostId === hostId
     }
     const owner = parseExecutionHostId(setup.hostId)
-    // Why: desktop persistence owns local and direct-SSH setups; runtime setups
-    // remain authoritative on their remote Orca server.
+    // Why: desktop persistence owns local and direct-SSH setups; runtime setups stay authoritative on their remote Orca server.
     return setup.hostId === LOCAL_EXECUTION_HOST_ID || owner?.kind === 'ssh'
   }
   const fetchedSetupsForHost = fetched.projectHostSetups.filter(setupBelongsToFetchedCatalog)
@@ -734,8 +721,7 @@ function mergeFetchedProjectCompatibilityForHost({
   const fetchedProjects = fetched.projects
     .filter((project) => {
       const previousProject = previousProjectById.get(project.id)
-      // Why: repo-derived compatibility projects include every known host.
-      // A one-host refresh should only reconcile that host or prune its stale ownership.
+      // Why: repo-derived compatibility projects include every host; a one-host refresh should only reconcile or prune that host's ownership.
       return (
         projectHasHost(project, fetched.projectHostSetups) ||
         (previousProject ? projectHasHost(previousProject, previous.projectHostSetups) : false)
@@ -836,8 +822,7 @@ function applyInheritedProjectGroups(previous: readonly Repo[], fetched: readonl
     if (inheritedProjectGroupId === undefined) {
       return repo
     }
-    // Why: project groups are a local organization affordance. Runtime copies
-    // of the same canonical project should appear in the user's existing group.
+    // Why: project groups are a local affordance; runtime copies of the same canonical project should appear in the user's existing group.
     return { ...repo, projectGroupId: inheritedProjectGroupId }
   })
 }
@@ -1042,9 +1027,7 @@ function clearRestoredFolderWorkspaceSessionOwners(
     }
     const workspace = state.folderWorkspaces.find((entry) => entry.id === scope.folderWorkspaceId)
     if (workspace && !state.projectGroups.some((group) => group.id === workspace.projectGroupId)) {
-      // Why: folder workspace ownership is resolved through its project group.
-      // If that catalog is still missing, keep the restored host owner so a
-      // session write before the next retry does not move runtime tabs local.
+      // Why: ownership resolves via the project group; if that catalog is still missing, keep the restored host owner so a session write doesn't move runtime tabs local.
       next[key] = hostId
     }
   }
@@ -1495,12 +1478,10 @@ export type RepoSlice = {
     groupId: string | null,
     order?: number
   ) => Promise<boolean>
-  // options.hostId disambiguates which host's row to remove when the same repo
-  // id exists on multiple hosts; without it the focused host is assumed.
+  // options.hostId disambiguates which host's row to remove when the id exists on multiple hosts; else the focused host is assumed.
   removeProject: (projectId: string, options?: { hostId?: ExecutionHostId }) => Promise<void>
   updateProject: (projectId: string, updates: ProjectUpdate) => Promise<boolean>
-  // options.hostId targets a specific host's repo row + RPC target when the same
-  // repo id exists on multiple hosts; without it the focused host is assumed.
+  // options.hostId targets a specific host's row + RPC target when the id exists on multiple hosts; else the focused host is assumed.
   updateRepo: (
     projectId: string,
     updates: RepoUpdate,
@@ -1547,8 +1528,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     }),
 
   fetchRepos: async () => {
-    // Why: overlapping repos:changed fetches can resolve out of order; an earlier
-    // one must not overwrite a newer result and resurrect deleted projects (#7020).
+    // Why: overlapping repos:changed fetches can resolve out of order; a stale one must not overwrite a newer result and resurrect deleted projects (#7020).
     let generation = 0
     set((s) => {
       generation = s.reposFetchGeneration + 1
@@ -1563,17 +1543,11 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       }
       let finalizedHostRepos: Repo[] = []
       set((s) => {
-        // Why: an in-flight fetch for a just-removed runtime env would otherwise
-        // re-add purged repos/rows and stick — nothing re-triggers the purge. Skip
-        // only when the catalog's env was actually removed (tombstoned), not merely
-        // absent from the not-yet-hydrated saved list (#8881).
+        // Why: an in-flight fetch for a just-removed env would re-add purged repos and stick; skip only when the env was tombstoned, not merely unhydrated (#8881).
         if (isRemovedRuntimeHostId(catalog.hostId, s.removedRuntimeEnvironmentIds)) {
           return s
         }
-        // Why: after re-adoption re-points a repo onto a re-added SSH target, the
-        // per-host merge leaves the stale row on the old (removed) target id — a
-        // ghost a terminal pane can bind to and fail with "SSH target not found".
-        // Drop rows on unknown SSH targets that a live-host sibling supersedes.
+        // Why: re-adoption leaves a stale row on the old SSH target id (a ghost that fails "SSH target not found"); drop rows a live-host sibling supersedes.
         const result = mergeFetchedRepoCatalog(catalog, s.repos)
         const reconciliation = reconcileSupersededSshRepos(result.repos, s)
         const prunedRepos = applyManualRepoOrder(reconciliation.repos, s.manualRepoOrder)
@@ -1624,8 +1598,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       const catalog = await fetchRepoCatalogForTarget(target)
       let finalizedHostRepos: Repo[] = []
       set((s) => {
-        // Why: skip a merge for a runtime env removed while this Connect-flow fetch
-        // was in flight, so purged repos/rows are not re-added (#8881).
+        // Why: skip merging a runtime env removed while this Connect-flow fetch was in flight, so purged repos aren't re-added (#8881).
         if (isRemovedRuntimeHostId(catalog.hostId, s.removedRuntimeEnvironmentIds)) {
           return s
         }
@@ -1680,24 +1653,15 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       generation = s.reposFetchGeneration + 1
       return { reposFetchGeneration: generation }
     })
-    // Why: a cold start that restores a remote workspace re-activates that
-    // remote runtime environment, and fetching only the active host hides every
-    // other host's repos (notably all local repos), which reads as "my projects
-    // vanished". Load local + every configured runtime environment so the
-    // sidebar "All hosts" scope shows them together regardless of which
-    // environment is active. Each host fails soft: an unreachable/disconnected
-    // host is skipped without blocking the others.
+    // Why: fetching only the active host hides every other host's repos ("my projects vanished"); load local + all runtime envs, each failing soft.
     const applyCatalog = (catalog: FetchedRepoCatalog): void => {
-      // Why: repos:changed can start another all-host refresh while this one is
-      // in flight. Never let the older catalog resurrect a migrated SSH owner.
+      // Why: a concurrent all-host refresh must not let the older catalog resurrect a migrated SSH owner.
       if (get().reposFetchGeneration !== generation) {
         return
       }
       let hostRepos: Repo[] = []
       set((s) => {
-        // Why: an all-host refresh can still be merging a host removed mid-load;
-        // skip a catalog whose env was tombstoned by a removal, not one merely
-        // absent from the not-yet-hydrated saved list (#8881).
+        // Why: skip a catalog whose env was tombstoned mid-load (removed), not one merely absent from the not-yet-hydrated saved list (#8881).
         if (isRemovedRuntimeHostId(catalog.hostId, s.removedRuntimeEnvironmentIds)) {
           return s
         }
@@ -1733,9 +1697,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
           setupScriptPromptDismissedRepoIds: s.setupScriptPromptDismissedRepoIds
         }
       })
-      // Why: preserve the safe-auto fork sync that fetchRepos /
-      // fetchRuntimeEnvironmentRepos schedule after merging each host, so
-      // cold-start (which now routes through here) keeps updating safe-auto forks.
+      // Why: keep the safe-auto fork sync (as fetchRepos does) so cold-start, which now routes here, still updates safe-auto forks.
       scheduleSafeAutoForkSync(get, hostRepos)
     }
     const validateRepoScopedUi = (): void => {
@@ -1769,8 +1731,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     }
 
     const environments = await listRuntimeEnvironmentsForAllHostLoad()
-    // Why: unreachable remotes can spend the full connect timeout; merge each
-    // resolved host through the state updater so parallel loads do not clobber.
+    // Why: unreachable remotes can spend the full connect timeout; merge each resolved host via the state updater so parallel loads don't clobber.
     await Promise.all(
       environments.map(async (environment) => {
         try {
@@ -1786,9 +1747,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
         }
       })
     )
-    // Why: first-paint startup intentionally loads only local repos before
-    // remotes answer. Validate repo-scoped UI only once every configured host has
-    // answered; otherwise an offline runtime would erase its saved filters.
+    // Why: validate repo-scoped UI only after every host answers; first-paint loads only local repos, so an offline runtime would erase its saved filters.
     if (!failed && get().reposFetchGeneration === generation) {
       validateRepoScopedUi()
     }
@@ -1808,8 +1767,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
   },
 
   fetchProjectGroupsForAllHosts: async (options) => {
-    // Why: startup renders an all-host sidebar; replacing groups with only the
-    // active host would leave repos from other hosts visible but ungrouped.
+    // Why: startup renders an all-host sidebar; replacing groups with only the active host leaves other hosts' repos visible but ungrouped.
     const applyCatalog = (catalog: FetchedProjectGroupCatalog): void => {
       set((s) => ({
         projectGroups: mergeFetchedProjectGroupCatalog(catalog, s.projectGroups).projectGroups,
@@ -1858,8 +1816,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
   },
 
   fetchFolderWorkspacesForAllHosts: async (options) => {
-    // Why: folder workspaces are owned through their project groups, so startup
-    // must fetch groups first and then merge each host's folder slice.
+    // Why: folder workspaces are owned through their project groups; fetch groups first, then merge each host's folder slice.
     const applyCatalog = (catalog: FetchedFolderWorkspaceCatalog): void => {
       set((s) => ({
         folderWorkspaces: mergeFetchedFolderWorkspaceCatalog(
@@ -1993,8 +1950,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
           target,
           'projectGroup.scanNested',
           { path },
-          // Why: older runtime servers cannot stream or cancel scans, so the
-          // renderer must retain a bounded failure path for large folders.
+          // Why: older runtime servers can't stream or cancel scans; keep a bounded failure path for large folders.
           { timeoutMs: 20_000 }
         )
       )
@@ -2173,8 +2129,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
   updateProjectGroup: async (groupId, updates) => {
     try {
-      // Why: project groups are focused-host-scoped by design — fetch/create/update/
-      // delete all route by the focused host, and the list is replaced (not merged).
+      // Why: project groups are focused-host-scoped by design; all CRUD routes by the focused host and the list is replaced, not merged.
       const target = getActiveRuntimeTarget(get().settings)
       const updated =
         target.kind === 'local'
@@ -2401,10 +2356,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
             return null
           }
         }
-        // Why: folder mode is a capability downgrade, not a silent fallback.
-        // Show an in-app confirmation dialog so users understand that worktrees,
-        // SCM, PRs, and checks will be unavailable for this root. The dialog's
-        // OK handler calls addNonGitFolder to complete the flow.
+        // Why: folder mode is a capability downgrade (no worktrees/SCM/PRs/checks), so confirm via dialog rather than silently falling back.
         const { openModal } = get()
         openModal('confirm-non-git-folder', {
           folderPath: path,
@@ -2447,8 +2399,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
             description: repo.displayName
           }
         )
-        // Why: the design requires the cross-profile advisory for SSH-added
-        // projects too — the presence lookup already keys on connection/host.
+        // Why: the cross-profile advisory applies to SSH-added projects too; the presence lookup already keys on connection/host.
         await warnIfProjectKnownInAnotherProfile(repo, get().activeOrcaProfileId)
       }
       return repo
@@ -2706,8 +2657,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
   addRepo: async () => {
     const target = getActiveRuntimeTarget(get().settings)
     if (target.kind !== 'local') {
-      // Why: OS folder pickers return client-local paths. Remote environments
-      // need an explicit host path, which the Add Project dialog handles.
+      // Why: OS folder pickers return client-local paths; remote environments need an explicit host path (Add Project dialog).
       toast.error(
         translate(
           'auto.store.slices.repos.e649269645',
@@ -2731,20 +2681,13 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
         return null
       }
       await markOnboardingProjectAdded('addedFolder')
-      // Why: without focusing the new folder, the UI looks unchanged after
-      // the dialog closes and users think nothing happened. Fetch the
-      // synthetic folder worktree and route through the standard activation
-      // sequence so the sidebar reveals and opens the folder the same way
-      // clicking a worktree card does. Lazy-imported to avoid a circular
-      // module load (worktree-activation imports the store root).
+      // Why: focus the new folder so the add is visible; lazy-import worktree-activation to avoid a circular module load (it imports the store root).
       await get().fetchWorktrees(repo.id)
       const folderWorktree = get().worktreesByRepo[repo.id]?.[0]
       if (folderWorktree) {
         const { activateAndRevealWorktree } = await import('../../lib/worktree-activation')
         const onboarding = await window.api.onboarding.get().catch(() => null)
-        // Why: a new user can dismiss the wizard, then immediately add their
-        // first folder from Landing. That path skips onboarding's completeRepo
-        // hook, so carry the selected default agent into the first terminal here.
+        // Why: adding the first folder from Landing skips onboarding's completeRepo hook; carry the default agent into the first terminal here.
         const startup = buildDismissedOnboardingFolderAgentStartup(
           get().settings,
           onboarding,
@@ -2769,9 +2712,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
   removeProject: async (projectId, options) => {
     try {
-      // Why: pass an explicit hostId (e.g. when removing an SSH host's root repo)
-      // so a duplicate id across hosts resolves to the intended row instead of
-      // falling back to the focused host.
+      // Why: pass an explicit hostId so a duplicate id across hosts resolves to the intended row, not the focused-host fallback.
       const ownerRepo = findRepoForHost(get().repos, projectId, {
         settings: get().settings,
         hostId: options?.hostId
@@ -2780,26 +2721,16 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
         return
       }
       const ownerHostId = getRepoExecutionHostId(ownerRepo)
-      // Why: an SSH-mode per-workspace-env's workspace is the repo's main worktree, so deleting it
-      // routes here (project removal) rather than through removeWorktree. Tear down the backing
-      // ephemeral runtime (Docker/VM + hidden SSH target) first so it doesn't leak when the project
-      // is removed. Matches on the repo's runtime-owned connectionId and its known worktree ids.
+      // Why: an SSH per-workspace-env's workspace is the repo's main worktree, so removal routes here; tear down its ephemeral runtime first so it doesn't leak.
       if (isRuntimeOwnedSshTargetId(ownerRepo.connectionId)) {
         await cleanupEphemeralVmRuntimesForDeleted({
           workspaceIds: getKnownRepoWorktreeIds(get(), projectId, ownerHostId),
           runtimeOwnedSshTargetIds: [ownerRepo.connectionId as string]
         })
       }
-      // Why: derive the runtime target from the owner's own settings, passing the
-      // explicit options.hostId so a duplicate repo id across hosts resolves to the
-      // intended row. settingsForRepoOwner clears the focused runtime for SSH/local
-      // owners (routing local) and pins runtime owners to their environment, so an
-      // SSH host removal never routes repo.rm to the focused runtime.
+      // Why: derive the target from the owner's settings (via options.hostId) so an SSH host removal never routes repo.rm to the focused runtime.
       const target = getActiveRuntimeTarget(settingsForRepoOwner(get(), projectId, options?.hostId))
-      // Why: the same repo id can exist on multiple hosts (local + an SSH target,
-      // or a re-added SSH target). Main's repos:remove is repo-id-only and would
-      // delete every host's row. Scope the local-side removal to the owning host
-      // so a cross-host duplicate id keeps its other rows.
+      // Why: repos:remove is id-only and would delete every host's row; scope local removal to the owning host so cross-host duplicates keep other rows.
       const idExistsOnOtherHost = get().repos.some(
         (repo) => repo.id === projectId && getRepoExecutionHostId(repo) !== ownerHostId
       )
@@ -2844,11 +2775,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
         }
       }
 
-      // Why: route project removal through the canonical per-worktree purge so all
-      // ~30 worktree-scoped maps are evicted. removeProject previously hand-deleted
-      // only a handful (tabs/layouts/ptys), leaking the rest (unified tabs, groups,
-      // git status, browser, everActivated, …) per worktree of every removed repo.
-      // Runs before the repo-scoped set() below so the purge still sees tabsByWorktree.
+      // Why: use the canonical per-worktree purge to evict all worktree-scoped maps (hand-deletion leaked most); runs before the set() below so it still sees tabsByWorktree.
       get().purgeWorktreeTerminalState(worktreeIds)
 
       set((s) => {
@@ -2885,10 +2812,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
           delete nextPtyIdsByTabId[tabId]
           delete nextRuntimePaneTitlesByTabId[tabId]
         }
-        // Why: editor state is worktree-scoped. Removing a repo must also
-        // remove open editor files and per-worktree active-file tracking for
-        // all worktrees that belonged to the repo, otherwise orphaned entries
-        // would persist in the session save and pollute state.
+        // Why: editor state is worktree-scoped; clear the repo's open files + active-file tracking so orphans don't linger in the session save.
         const worktreeIdSet = new Set(worktreeIds)
         const nextOpenFiles = s.openFiles.filter((f) => !worktreeIdSet.has(f.worktreeId))
         const nextActiveFileIdByWorktree = { ...s.activeFileIdByWorktree }
@@ -2901,11 +2825,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
           ? s.openFiles.some((f) => f.id === s.activeFileId && worktreeIdSet.has(f.worktreeId))
           : false
         const nextRepos = s.repos.filter((r) => !repoMatchesHostIdentity(r, projectId, ownerHostId))
-        // Why: when no sibling host still owns this repo id, drop every persisted
-        // timestamp for the repo's worktrees — including unhydrated SSH/remote ones
-        // absent from worktreeIdSet, which pruneLastVisitedTimestamps would otherwise
-        // defer forever as "not yet hydrated" after the repo is gone. When a duplicate
-        // id remains on another host, stay host-scoped via worktreeIdSet.
+        // Why: when no sibling host owns this id, drop every worktree timestamp (unhydrated SSH ones would otherwise never prune); else stay host-scoped.
         const repoIdFullyRemoved = !nextRepos.some((r) => r.id === projectId)
         let nextLastVisitedAtByWorktreeId = s.lastVisitedAtByWorktreeId
         for (const id of Object.keys(s.lastVisitedAtByWorktreeId)) {
@@ -2923,8 +2843,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
         const removedRepoIds = s.repos.filter((r) => !survivingRepoIds.has(r.id)).map((r) => r.id)
         return {
           repos: nextRepos,
-          // Why: drop the removed repos' sparse-preset maps so they don't outlive
-          // the repo for the renderer's whole session.
+          // Why: drop removed repos' sparse-preset maps so they don't outlive the repo for the whole session.
           ...omitSparsePresetsForRepos(s, removedRepoIds),
           ...mergeProjectCompatibilityForHostRepoChange({
             previous: { projects: s.projects, projectHostSetups: s.projectHostSetups },
@@ -2948,10 +2867,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
           lastVisitedAtByWorktreeId: nextLastVisitedAtByWorktreeId,
           folderWorkspacePathStatuses: {},
           sortEpoch: s.sortEpoch + 1,
-          // Why: removing the last repo while in settings leaves activeView as
-          // 'settings', which renders an empty settings pane instead of Landing.
-          // Also clear activeWorktreeId so App renders Landing (it checks
-          // !activeWorktreeId). Without this, the terminal surface shows instead.
+          // Why: removing the last repo must reset activeView + clear activeWorktreeId so App renders Landing, not an empty settings/terminal pane.
           ...(nextRepos.length === 0
             ? {
                 activeView: 'terminal' as const,
@@ -3006,8 +2922,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
   updateRepo: async (projectId, updates, options) => {
     const updateRepoChains = getRepoUpdateChains(get)
-    // Why: pass options.hostId so a duplicate repo id across hosts resolves to the
-    // intended row instead of findRepoForHost's settings-focused fallback.
+    // Why: pass options.hostId so a duplicate repo id across hosts resolves to the intended row, not the settings-focused fallback.
     const ownerRepo = findRepoForHost(get().repos, projectId, {
       settings: get().settings,
       hostId: options?.hostId
@@ -3015,9 +2930,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     if (!ownerRepo) {
       return false
     }
-    // Why: an explicit hostId is authoritative — treat it as an explicit host so
-    // routing goes to that host's target (local IPC or its runtime RPC) rather
-    // than the currently-focused runtime, which is the same-id/self-pair case.
+    // Why: an explicit hostId is authoritative; route to that host's target rather than the currently-focused runtime.
     const ownerHasExplicitHost = Boolean(
       options?.hostId || ownerRepo.executionHostId?.trim() || ownerRepo.connectionId?.trim()
     )
@@ -3097,8 +3010,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       }
     }
     const previous = updateRepoChains.get(updateChainKey)
-    // Why: repo settings are persisted as full nested values. Preserve call
-    // order per repo so a slower IPC/RPC response cannot overwrite newer state.
+    // Why: settings persist as full nested values, so preserve per-repo call order — a slower response mustn't overwrite newer state.
     const next = previous
       ? previous.catch(() => undefined).then(applyRepoUpdate)
       : applyRepoUpdate()
@@ -3115,8 +3027,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
   setActiveRepo: (projectId) => set({ activeRepoId: projectId }),
 
   reorderRepos: async (orderedIds) => {
-    // Optimistically apply the new order so the sidebar updates instantly;
-    // resync only if main rejects (stale permutation due to a racing add/remove).
+    // Optimistically apply the new order for instant sidebar update; resync only if main rejects (racing add/remove).
     const previous = get().repos
     const remainingById = new Map<string, { repos: Repo[]; nextIndex: number }>()
     for (const repo of previous) {
@@ -3149,9 +3060,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       folderWorkspacePathStatuses: {}
     })
     try {
-      // Why: each host persists only its own repos and rejects non-permutations,
-      // so split the cross-host order into per-host permutations and dispatch one
-      // reorder per owner host.
+      // Why: each host persists only its own repos and rejects non-permutations; dispatch one per-host permutation per owner.
       const groups = splitRepoReorderByHost(orderedIds, next, get().settings)
       const [results] = await Promise.all([
         Promise.all(
@@ -3174,8 +3083,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
                 )
           })
         ),
-        // Why: servers can only persist their local permutations. The desktop
-        // profile owns the cross-host relationships needed after a cold load.
+        // Why: servers only persist local permutations; the desktop profile owns cross-host order after a cold load.
         window.api.ui.set({ manualRepoOrder })
       ])
       if (results.some((result) => result.status === 'rejected')) {
diff --git a/src/renderer/src/store/slices/store-cascades.test.ts b/src/renderer/src/store/slices/store-cascades.test.ts
index 5e6e10f13fc..209ff44fc5c 100644
--- a/src/renderer/src/store/slices/store-cascades.test.ts
+++ b/src/renderer/src/store/slices/store-cascades.test.ts
@@ -805,8 +805,7 @@ describe('setActiveWorktree', () => {
     const worktree = store.getState().worktreesByRepo.repo1[0]
     expect(worktree.sortOrder).toBe(123)
     expect(worktree.lastActivityAt).toBe(lastActivityAt)
-    // Why: selecting a worktree should not manufacture smart-sort activity.
-    // Persisted ordering signals come from real background work or edits, not focus.
+    // Why: selecting a worktree must not manufacture smart-sort activity; ordering comes from real work, not focus.
     expect(mockApi.worktrees.updateMeta).not.toHaveBeenCalled()
   })
 
@@ -1708,9 +1707,7 @@ describe('setActiveWorktree', () => {
     store.getState().createTab(wt)
     unsubscribe()
 
-    // Why: task-page launches queue startup/setup commands before React mounts.
-    // A terminal-only intermediate state can mount the legacy host and race
-    // the split-group host, duplicating setup panes and PTYs.
+    // Why: a terminal-only intermediate state mounts the legacy host and races the split-group host, duplicating setup panes and PTYs.
     expect(snapshots).toEqual([{ terminalCount: 1, unifiedCount: 1, groupCount: 1 }])
   })
 
@@ -2423,10 +2420,7 @@ describe('setActiveWorktree', () => {
     })
   })
 
-  // Why: unread flags are ephemeral UI state — they must not linger past the
-  // lifetime of the tab/pane they point at. A stale flag on a closed tab
-  // would render a bell the user can never dismiss because the tab (and
-  // therefore every focus path that clears it) is gone.
+  // Why: a stale unread flag on a closed tab renders a bell the user can never dismiss, since the tab is gone.
   it('drops unreadTerminalTabs for a closed tab', () => {
     const store = createTestStore()
     const wt = 'repo1::/path/wt1'
@@ -2440,9 +2434,7 @@ describe('setActiveWorktree', () => {
     const closing = store.getState().createTab(wt)
     const surviving = store.getState().createTab(wt)
 
-    // Seed flags directly — the self-guarded mark actions intentionally
-    // refuse the currently-active tab, but this test's subject is closeTab's
-    // cleanup behavior, not the guards.
+    // Seed directly: mark actions refuse the active tab, but this test targets closeTab's cleanup, not the guards.
     store.setState({
       unreadTerminalTabs: {
         [closing.id]: true as const,
@@ -2458,10 +2450,7 @@ describe('setActiveWorktree', () => {
     expect(s.unreadTerminalTabs[surviving.id]).toBe(true)
   })
 
-  // Why: shutdownWorktreeTerminals tears down every PTY in the worktree. The
-  // focus events that would normally clear unread (bell-in-focused-pane,
-  // activate-tab) never arrive for dead PTYs, so the flags have to be
-  // dropped by the shutdown path itself.
+  // Why: focus events that normally clear unread never arrive for dead PTYs, so the shutdown path must drop the flags itself.
   it('drops unread flags for every tab in a shutdown worktree', async () => {
     const store = createTestStore()
     const wt = 'repo1::/path/wt1'
@@ -2490,11 +2479,7 @@ describe('setActiveWorktree', () => {
     expect(s.unreadTerminalTabs[tabB.id]).toBeUndefined()
   })
 
-  // Why: ownership regression (design §1.3). shutdownWorktreeTerminals used to
-  // delete browserTabsByWorktree[worktreeId] and reset
-  // activeBrowserTabId/activeTabType as a side effect — now those mutations
-  // belong exclusively to shutdownWorktreeBrowsers. If a refactor reintroduces
-  // the side effect, both thunks will write the same keys and race.
+  // Why: browser-state mutations belong to shutdownWorktreeBrowsers only (design §1.3); reintroducing them here races both thunks.
   it('leaves browser state untouched when shutting down terminals', async () => {
     const store = createTestStore()
     const wt = 'repo1::/path/wt1'
@@ -2925,14 +2910,7 @@ describe('setActiveWorktree', () => {
   })
 })
 
-// Why: sleep (`shutdownWorktreeTerminals(wt, { keepIdentifiers: true })`)
-// kills the PTYs but preserves wake hints (tab.ptyId, ptyIdsByLeafId, the
-// runtime pane titles) so wake can reattach to the same daemon-history dir
-// or relay session. Before the sleep-statuses fix, the live agent-status
-// rows were also preserved — so a Claude that was mid-turn at sleep time
-// kept its row in the inline agents list as "working" until the 30-min
-// stale TTL decayed it. Sleep now drops live entries and retained `done`
-// snapshots for the whole worktree, so the card folds to a single grey signal.
+// Why: sleep must drop live + retained agent-status rows, else a mid-turn agent stays "working" until the 30-min stale TTL.
 describe('shutdownWorktreeTerminals (sleep) — agent status hygiene', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -3047,11 +3025,7 @@ describe('shutdownWorktreeTerminals (sleep) — agent status hygiene', () => {
   })
 
   it('aborts pane hibernation without side effects when no resume record can be captured', async () => {
-    // The prod ghost pane was killed with NO sleeping record captured, so
-    // nothing could ever wake it. Planner eligibility can go stale between
-    // ticks, so the shutdown must throw before any suppression or kill when the
-    // capture comes back empty (a done agent with no resumable provider
-    // session), leaving the pane fully intact for a later retry.
+    // No capturable resume record means the pane could never wake, so shutdown throws before any suppression or kill.
     const store = createTestStore()
     const wt = 'repo1::/path/wt1'
     const targetLeaf = '11111111-1111-4111-8111-111111111111'
@@ -3110,10 +3084,7 @@ describe('shutdownWorktreeTerminals (sleep) — agent status hygiene', () => {
   })
 
   it('rolls back the sleeping record and suppression when the hibernation kill fails', async () => {
-    // The sleeping record must be visible to the pane's exit handler BEFORE the
-    // kill (pty:exit can beat the kill promise back to the renderer), so it is
-    // written alongside the suppression — and both must roll back if the kill
-    // fails, or a live pane would carry a stale wake record.
+    // Record written before the kill (pty:exit can beat it back); both it and the suppression must roll back if the kill fails.
     const store = createTestStore()
     const wt = 'repo1::/path/wt1'
     const targetLeaf = '11111111-1111-4111-8111-111111111111'
@@ -3164,11 +3135,7 @@ describe('shutdownWorktreeTerminals (sleep) — agent status hygiene', () => {
   })
 
   it('persists the sleeping record and suppression before issuing the hibernation kill', async () => {
-    // pty:exit can beat the kill promise back to the renderer, and the pane's
-    // exit handler arms the hibernation wake only if the sleeping record is
-    // already in the store. A record written after the kill resolves passes
-    // every end-state assertion while still losing that race, so this test
-    // observes the store at the moment the kill is issued.
+    // pty:exit can beat the kill promise back; the record must be in the store before the kill or the wake never arms.
     const store = createTestStore()
     const wt = 'repo1::/path/wt1'
     const targetLeaf = '11111111-1111-4111-8111-111111111111'
@@ -3222,8 +3189,7 @@ describe('shutdownWorktreeTerminals (sleep) — agent status hygiene', () => {
       providerSession: { key: 'session_id', id: 'sess-ordering-1' }
     })
     expect(suppressionAtKillTime).toBe(true)
-    // The record must survive the successful kill so the reveal-time wake can
-    // consume it.
+    // The record must survive the successful kill so the reveal-time wake can consume it.
     const state = store.getState()
     expect(state.sleepingAgentSessionsByPaneKey[targetPaneKey]).toBeDefined()
   })
@@ -4838,8 +4804,7 @@ describe('shutdownWorktreeTerminals (sleep) — agent status hygiene', () => {
       ptyIdsByTabId: { 'tab-1': ['pty-1'] }
     })
 
-    // Plant one current-tab row and one orphan row. Retained rows render by
-    // worktreeId, so sleep must sweep both instead of only tab prefixes.
+    // Retained rows render by worktreeId, so sleep must sweep the orphan row too, not just tab prefixes.
     store.getState().retainAgents([
       {
         entry: {
@@ -4959,8 +4924,7 @@ describe('shutdownWorktreeTerminals (sleep) — agent status hygiene', () => {
 
     await store.getState().shutdownWorktreeTerminals(wt, { keepIdentifiers: true })
 
-    // Why: sleep folds retained rows too, so the next retention sync must not
-    // recreate a `done` row from the previous render after the user slept it.
+    // Why: sleep folds retained rows too, so the next retention sync must not recreate a slept `done` row.
     expect(store.getState().retentionSuppressedPaneKeys['tab-1:0']).toBe(true)
   })
 
@@ -4983,8 +4947,7 @@ describe('shutdownWorktreeTerminals (sleep) — agent status hygiene', () => {
 
     await store.getState().shutdownWorktreeTerminals(wt, { keepIdentifiers: true })
 
-    // Why: an existing suppressor was planted by a prior dismissal flow; sleep
-    // must not erase it (would resurface a row the user already dismissed).
+    // Why: a suppressor planted by a prior dismissal must survive sleep, else the dismissed row resurfaces.
     expect(store.getState().retentionSuppressedPaneKeys['tab-1:0']).toBe(true)
   })
 
@@ -5038,9 +5001,7 @@ describe('shutdownWorktreeTerminals (sleep) — agent status hygiene', () => {
   })
 })
 
-// Why: CLI-spawned background terminals stamp ORCA_PANE_KEY into the PTY env
-// at spawn time. The renderer must adopt the tab under the same id so hook
-// events route to the correct slot.
+// Why: CLI-spawned terminals stamp ORCA_PANE_KEY at spawn; renderer must adopt the tab under that id so hook events route correctly.
 describe('createTab tabId hint', () => {
   it('uses the supplied id when no collision exists', () => {
     const store = createTestStore()
diff --git a/src/renderer/src/store/slices/store-session-cascades.test.ts b/src/renderer/src/store/slices/store-session-cascades.test.ts
index 2a9a3de8e94..c84f5814572 100644
--- a/src/renderer/src/store/slices/store-session-cascades.test.ts
+++ b/src/renderer/src/store/slices/store-session-cascades.test.ts
@@ -214,8 +214,7 @@ describe('removeProject cascade', () => {
     expect(mockApi.pty.kill).toHaveBeenCalledWith('pty1')
     expect(mockApi.pty.kill).toHaveBeenCalledWith('pty2')
 
-    // The tabs are gone before async exit events can close them, so retaining
-    // their one-shot guards would leak ephemeral PTY ids for the renderer session.
+    // Tabs are gone before async exit events fire, so retaining one-shot guards would leak ephemeral PTY ids.
     expect(s.suppressedPtyExitIds['pty1']).toBeUndefined()
     expect(s.suppressedPtyExitIds['pty2']).toBeUndefined()
     expect(s.pendingCodexPaneRestartIds['pty1']).toBeUndefined()
@@ -224,8 +223,7 @@ describe('removeProject cascade', () => {
     store.getState().clearTabPtyId('tab1', 'pty1')
     store.getState().clearTabPtyId('tab2', 'pty2')
 
-    // Why: exit IPC can arrive after repo purge but before the mounted pane
-    // unmounts. A late exit must not recreate an index for a tab with no owner.
+    // Why: exit IPC can arrive after repo purge but before the pane unmounts; a late exit must not recreate an index for an ownerless tab.
     expect(store.getState().ptyIdsByTabId['tab1']).toBeUndefined()
     expect(store.getState().ptyIdsByTabId['tab2']).toBeUndefined()
   })
@@ -318,9 +316,7 @@ describe('hydrateWorkspaceSession', () => {
     expect(s.terminalLayoutsByTabId['tab-valid']).toBeDefined()
     expect(s.terminalLayoutsByTabId['tab-invalid']).toBeUndefined()
 
-    // Why: with two-phase hydration, workspaceSessionReady stays false after
-    // hydrateWorkspaceSession. It flips to true in reconnectPersistedTerminals()
-    // after all eager PTY spawns complete.
+    // Why: two-phase hydration keeps workspaceSessionReady false until reconnectPersistedTerminals() flips it after eager spawns.
     expect(s.workspaceSessionReady).toBe(false)
   })
 
@@ -373,8 +369,7 @@ describe('hydrateWorkspaceSession', () => {
   })
 
   it('preserves tabs for a known repo whose worktrees have not loaded yet', () => {
-    // Why (#1158): empty per-repo worktrees can mean a degraded local fetch or
-    // SSH reconnect race, not that every persisted tab for the repo is stale.
+    // Why (#1158): empty per-repo worktrees can mean a degraded fetch or reconnect race, not that persisted tabs are stale.
     const store = createTestStore()
     const stalledWt = 'repo1::/path/wt1'
 
@@ -440,8 +435,7 @@ describe('hydrateWorkspaceSession', () => {
   })
 
   it('drops tabs when an authoritative scan reports no matching worktrees', () => {
-    // Why: once git has answered authoritatively, an empty repo list means
-    // deleted local worktrees, not a startup race.
+    // Why: once git answers authoritatively, an empty repo list means deleted local worktrees, not a startup race.
     const store = createTestStore()
     const staleWt = 'repo1::/path/deleted'
 
@@ -475,9 +469,7 @@ describe('hydrateWorkspaceSession', () => {
   })
 
   it('drops tabs for an unknown repo', () => {
-    // Why: the carve-out only forgives missing worktrees for repos that still
-    // exist in the repos list. If the user removed the whole repo, its tabs
-    // are genuinely stale and must be dropped.
+    // Why: the carve-out only forgives missing worktrees for repos still in the repos list; a removed repo's tabs are genuinely stale.
     const store = createTestStore()
     const orphanWt = 'repoGone::/path/wt1'
 
@@ -537,13 +529,10 @@ describe('hydrateWorkspaceSession', () => {
     expect(s.activeTabId).toBe('tab1')
     expect(s.activeRepoId).toBe('repo1')
 
-    // Why: restored tabs receive pendingActivationSpawn so the pane mount's
-    // reattach (or fresh spawn if the daemon session died) does not count as
-    // activity and bounce the worktree to the top of Recent.
+    // Why: pendingActivationSpawn keeps the mount's reattach/respawn from counting as activity and bouncing the worktree up Recent.
     expect(s.tabsByWorktree[validWt][0].pendingActivationSpawn).toBe(true)
 
-    // The restored-active worktree is marked ever-activated so a later click
-    // doesn't retag (which would suppress a real codex-restart / new-pane bump).
+    // Marked ever-activated so a later click doesn't retag and suppress a real codex-restart/new-pane bump.
     expect(s.everActivatedWorktreeIds.has(validWt)).toBe(true)
   })
 })
@@ -773,8 +762,7 @@ describe('hydrateBrowserSession', () => {
         repo1: [makeWorktree({ id: wt, repoId: 'repo1', path: '/path/wt1' })]
       },
       activeWorktreeId: wt,
-      // Simulate hydrateEditorSession returning {} (no editor files) —
-      // activeTabTypeByWorktree stays at the initial empty object
+      // Simulate hydrateEditorSession returning {} (no editor files) — activeTabTypeByWorktree stays empty.
       activeTabTypeByWorktree: {}
     })
 
@@ -792,8 +780,7 @@ describe('hydrateBrowserSession', () => {
     })
 
     const s = store.getState()
-    // hydrateBrowserSession must merge 'browser' entries into activeTabTypeByWorktree
-    // so setActiveWorktree doesn't default to 'terminal' and cause a blank screen
+    // hydrateBrowserSession must merge 'browser' into activeTabTypeByWorktree, else setActiveWorktree defaults to 'terminal' → blank screen.
     expect(s.activeTabTypeByWorktree[wt]).toBe('browser')
     expect(s.activeTabType).toBe('browser')
     expect(s.activeBrowserTabId).toBe('browser-1')
@@ -1156,20 +1143,13 @@ describe('terminal slice behaviors', () => {
     expect(mockApi.worktrees.updateMeta).not.toHaveBeenCalled()
   })
 
-  // Why: clicking a worktree in the sidebar triggers a generation bump on
-  // dead-PTY tabs which remounts TerminalPane and fresh-spawns a PTY. That
-  // fresh spawn calls updateTabPtyId → bumpWorktreeActivity. Without the
-  // pendingActivationSpawn tag, the just-clicked worktree would be stamped
-  // with Date.now() and float to the top of Recent on every click. isReattach
-  // is not set on fresh spawns, so this bug slips past PR 310e9daf.
+  // Why: a click's fresh spawn on dead-PTY tabs would bump activity and float the worktree up Recent; pendingActivationSpawn prevents it (PR 310e9daf).
   it('does not bump lastActivityAt when a click-driven fresh spawn follows setActiveWorktree', () => {
     const store = createTestStore()
     const worktreeId = 'repo1::/path/wt1'
     const originalLastActivityAt = 1000
 
-    // Why: a tab with a null ptyId triggers the allDead branch in
-    // setActiveWorktree, which bumps generation and sets
-    // pendingActivationSpawn so the subsequent fresh spawn is suppressed.
+    // Why: a null-ptyId tab hits setActiveWorktree's allDead branch, which tags pendingActivationSpawn to suppress the fresh spawn.
     store.setState({
       repos: [
         { id: 'repo1', path: '/repo1', displayName: 'Repo 1', badgeColor: '#000', addedAt: 0 }
@@ -1224,8 +1204,7 @@ describe('terminal slice behaviors', () => {
         updates: expect.objectContaining({ lastActivityAt: expect.any(Number) })
       })
     )
-    // The flag is consumed so a later legitimate respawn (codex restart etc.)
-    // is not silently suppressed as well.
+    // The flag is consumed so a later legit respawn (codex restart etc.) isn't silently suppressed too.
     expect(store.getState().tabsByWorktree[worktreeId][0].pendingActivationSpawn).toBeUndefined()
   })
 
@@ -1280,13 +1259,7 @@ describe('terminal slice behaviors', () => {
     expect(tab.pendingActivationSpawn).toBe(true)
   })
 
-  // Why: the FIRST activation of a worktree tags every tab — even if tab.ptyId
-  // already looks live, because reconnectPersistedTerminals can re-populate
-  // tab.ptyId with a restored daemon session ID before the pane mounts, making
-  // the upcoming updateTabPtyId look like new activity when it is really just
-  // the click-driven reattach. Subsequent activations of the SAME worktree
-  // must NOT re-tag — otherwise a later split-pane spawn or codex restart
-  // would be silently suppressed.
+  // Why: first activation tags every tab (even live-looking ptyIds, since reconnect may repopulate before mount); re-activation must not re-tag or it drops later spawns.
   it('tags on first activation but not on re-activation', () => {
     const store = createTestStore()
     const worktreeId = 'repo1::/path/wt1'
@@ -1332,20 +1305,13 @@ describe('terminal slice behaviors', () => {
     store.getState().updateTabPtyId('tab-1', 'pty-live')
     expect(store.getState().tabsByWorktree[worktreeId][0].pendingActivationSpawn).toBeUndefined()
 
-    // Switch away, then re-activate. The re-activation must NOT tag again,
-    // or a later legitimate spawn (codex restart, new pane) would be dropped.
+    // Switch away, then re-activate: re-activation must NOT tag again, or a later legit spawn (codex restart, new pane) is dropped.
     store.getState().setActiveWorktree(null)
     store.getState().setActiveWorktree(worktreeId)
     expect(store.getState().tabsByWorktree[worktreeId][0].pendingActivationSpawn).toBeUndefined()
   })
 
-  // Why: re-activating a worktree whose PTYs died while the user was away (e.g.
-  // relay disconnect, sleep) hits the allDead generation bump, which remounts
-  // TerminalPane and fresh-spawns a PTY. That respawn is a side-effect of the
-  // click, not real activity. First-activation tagging doesn't cover it
-  // (everActivatedWorktreeIds already has the worktree), so without tagging the
-  // allDead bump the worktree would stamp lastActivityAt and jump to the top of
-  // Recent on every re-click — the reported "click bounces it to the top" bug.
+  // Why: re-activating dead-PTY worktrees triggers the allDead respawn (a click side-effect, not activity) that first-activation tagging misses, so tag it too.
   it('does not bump lastActivityAt when a re-activation respawns dead PTYs', () => {
     const store = createTestStore()
     const worktreeId = 'repo1::/path/wt1'
@@ -1365,9 +1331,7 @@ describe('terminal slice behaviors', () => {
           })
         ]
       },
-      // Tab retains a wake-hint ptyId but has no live PTY, and the worktree was
-      // already activated this session — so this is a re-activation, not a
-      // first activation.
+      // Wake-hint ptyId but no live PTY, and worktree already activated this session — a re-activation, not a first activation.
       tabsByWorktree: {
         [worktreeId]: [makeTab({ id: 'tab-1', worktreeId, ptyId: 'wake-hint-session' })]
       },
@@ -1396,15 +1360,12 @@ describe('terminal slice behaviors', () => {
     })
 
     store.getState().setActiveWorktree(worktreeId)
-    // The allDead generation bump must tag the tab so the click-driven respawn
-    // is suppressed, even though this is not the first activation.
+    // The allDead generation bump must tag the tab so the click-driven respawn is suppressed, even on a non-first activation.
     expect(store.getState().tabsByWorktree[worktreeId][0].pendingActivationSpawn).toBe(true)
 
     const sortEpochBeforeSpawn = store.getState().sortEpoch
 
-    // Simulate the stale wake-hint reattach failing before TerminalPane falls
-    // back to a fresh spawn. The clear suppresses its own activity bump without
-    // consuming the spawn suppression.
+    // Stale wake-hint reattach fails before a fresh spawn; the clear suppresses its own bump without consuming the spawn suppression.
     store.getState().clearTabPtyId('tab-1', 'wake-hint-session')
     expect(store.getState().tabsByWorktree[worktreeId][0].pendingActivationSpawn).toBe(true)
 
@@ -1499,11 +1460,7 @@ describe('terminal slice behaviors', () => {
     expect(store.getState().tabsByWorktree[worktreeId][0].pendingActivationSpawn).toBeUndefined()
   })
 
-  // Why: first-visit worktrees (no tabs yet) trigger Terminal.tsx's activation
-  // fallback which calls createTab(). That auto-created tab passes
-  // pendingActivationSpawn: true so its PTY spawn is suppressed — otherwise
-  // clicking a never-visited worktree in the sidebar would stamp lastActivityAt
-  // and reshuffle Recent/Smart (the user-reported bounce ~5s after click).
+  // Why: first-visit worktrees auto-create a pendingActivationSpawn tab so the spawn doesn't stamp lastActivityAt and bounce Recent.
   it('does not bump lastActivityAt when createTab auto-creates for a first-visit worktree', () => {
     const store = createTestStore()
     const worktreeId = 'repo1::/path/wt1'
@@ -1523,8 +1480,7 @@ describe('terminal slice behaviors', () => {
           })
         ]
       },
-      // No tabs yet — this is a fresh worktree the user is visiting for the
-      // first time in this session.
+      // No tabs yet — a fresh worktree visited for the first time this session.
       tabsByWorktree: {},
       ptyIdsByTabId: {},
       activeWorktreeId: worktreeId
@@ -1551,8 +1507,7 @@ describe('terminal slice behaviors', () => {
     expect(store.getState().tabsByWorktree[worktreeId][0].pendingActivationSpawn).toBeUndefined()
   })
 
-  // Why: real background events (agent output, OSC titles) must still bump
-  // activity. Only the specific activation-driven spawn is suppressed.
+  // Why: real background events (agent output, OSC titles) must still bump activity; only activation-driven spawns are suppressed.
   it('bumps lastActivityAt for a fresh spawn with no activation tag', () => {
     const store = createTestStore()
     const worktreeId = 'repo1::/path/wt1'
@@ -1600,11 +1555,7 @@ vi.mock('@/components/terminal-pane/pty-transport', () => ({
 describe('reconnectPersistedTerminals', () => {
   let ptyIdCounter: number
 
-  // Why: reconnect-by-daemon-session-ID is an opt-in path (the experimental
-  // daemon toggle). These tests exercise that path, so each store created here
-  // must have the toggle set to true before hydrateWorkspaceSession runs —
-  // otherwise hydration clears pendingReconnectPtyIdByTabId and tab.ptyId
-  // never gets rehydrated.
+  // Why: the daemon toggle must be on before hydration, else hydration clears reconnect state and tab.ptyId never rehydrates.
   function createDaemonEnabledStore(): ReturnType<typeof createTestStore> {
     return createTestStore()
   }
@@ -1658,9 +1609,7 @@ describe('reconnectPersistedTerminals', () => {
 
     const s = store.getState()
     expect(s.workspaceSessionReady).toBe(true)
-    // Why: Option 2 defers actual pty.spawn to connectPanePty. The store
-    // records daemon session IDs as tab-level ptyIds so connectPanePty
-    // can pass them as sessionId to the daemon's createOrAttach.
+    // Why: spawn is deferred to connectPanePty; the store records daemon session IDs as tab-level ptyIds for it to reattach.
     expect(s.tabsByWorktree[wt1][0].ptyId).toBe('old-pty-1')
     expect(s.tabsByWorktree[wt2][0].ptyId).toBeNull()
     expect(s.ptyIdsByTabId.tab1).toEqual(['old-pty-1'])
@@ -1760,8 +1709,7 @@ describe('reconnectPersistedTerminals', () => {
       }
     })
 
-    // No activeWorktreeIdsOnShutdown — simulates session from older build
-    // The tab still has a ptyId from the raw session data
+    // No activeWorktreeIdsOnShutdown — simulates a session from an older build.
     store.getState().hydrateWorkspaceSession({
       activeRepoId: 'repo1',
       activeWorktreeId: wt1,
@@ -1956,12 +1904,9 @@ describe('reconnectPersistedTerminals', () => {
     const s = store.getState()
     // Why: deferred reattach doesn't call spawn — connectPanePty handles it
     expect((mockApi.pty as Record<string, unknown>).spawn).not.toHaveBeenCalled()
-    // Why: reconnect restores the tab-level ptyId so getWorktreeStatus()
-    // sees the tab as active (green dot) even before the terminal mounts.
-    // connectPanePty reads ptyIdsByLeafId for per-leaf daemon sessions.
+    // Why: reconnect restores the tab-level ptyId so getWorktreeStatus() shows active (green dot) before the terminal mounts.
     expect(s.tabsByWorktree[wt1][0].ptyId).toBe('daemon-session-B')
-    // ptyIdsByLeafId preserved from hydration for connectPanePty to consume,
-    // but legacy pane:* leaves are reminted to durable UUID leaves at hydration.
+    // ptyIdsByLeafId preserved for connectPanePty; legacy pane:* leaves reminted to durable UUID leaves at hydration.
     const layout = s.terminalLayoutsByTabId['tab1']
     const bindings = layout.ptyIdsByLeafId ?? {}
     expect(Object.keys(bindings)).toHaveLength(2)
@@ -2049,8 +1994,7 @@ describe('hydrateEditorSession', () => {
       worktreesByRepo: {
         repo1: [makeWorktree({ id: wt, repoId: 'repo1', path: '/path/wt1' })]
       },
-      // Why: hydrateEditorSession reads activeWorktreeId from the store
-      // (set by hydrateWorkspaceSession), not from the raw session.
+      // Why: hydrateEditorSession reads activeWorktreeId from the store (set by hydrateWorkspaceSession), not the raw session.
       activeWorktreeId: wt
     })
 
diff --git a/src/renderer/src/store/slices/tabs.test.ts b/src/renderer/src/store/slices/tabs.test.ts
index ea5e42dd1df..4c286ea7289 100644
--- a/src/renderer/src/store/slices/tabs.test.ts
+++ b/src/renderer/src/store/slices/tabs.test.ts
@@ -429,9 +429,7 @@ describe('TabsSlice', () => {
       const t2 = store.getState().createUnifiedTab(WT, 'terminal')
       const t3 = store.getState().createUnifiedTab(WT, 'terminal')
 
-      // Visit order: ...→t3 (last created)→t1→t3. Closing t3 should jump
-      // back to t1 (previous), not t2 (the visual right-neighbor after t3's
-      // removal fallback or left-neighbor).
+      // Visit order ...→t3→t1→t3; closing t3 should jump to t1 (MRU previous), not the visual neighbor t2.
       store.getState().activateTab(t1.id)
       store.getState().activateTab(t3.id)
       store.getState().closeUnifiedTab(t3.id)
@@ -447,8 +445,7 @@ describe('TabsSlice', () => {
     })
 
     it('falls back to neighbor selection when the MRU stack has no prior tab', () => {
-      // Build state manually so no prior activations have been recorded. This
-      // mirrors a freshly-hydrated session with only an active tab known.
+      // Build state manually (no prior activations) — mirrors a freshly-hydrated session with only an active tab known.
       const groupId = 'mru-fallback-group'
       store.setState({
         unifiedTabsByWorktree: {
@@ -526,13 +523,10 @@ describe('TabsSlice', () => {
       })
       // Second group's MRU tail should be t3.
 
-      // Switch focus to the source group so subsequent activations in the
-      // source group don't pollute the second group's MRU.
+      // Focus the source group so its activations don't pollute the second group's MRU.
       store.getState().activateTab(t1.id)
 
-      // Re-focus second group by activating t2, then close t2 — we expect the
-      // previous tab within the same group (t3), not a neighbor from the
-      // source group.
+      // Re-focus the second group via t2, then close it: expect the same-group previous tab (t3), not a source-group neighbor.
       store.getState().activateTab(t3.id)
       store.getState().activateTab(t2.id)
       store.getState().closeUnifiedTab(t2.id)
@@ -586,24 +580,17 @@ describe('TabsSlice', () => {
       expect(store.getState().unifiedTabsByWorktree[WT][0].isPreview).toBe(false)
     })
 
-    // Why: regression guard for "click the tab with a bell and it doesn't go
-    // away". The tab-strip bell reads from unreadTerminalTabs, keyed by the
-    // terminal tab's entityId. activateTab receives a *unified* tabId, so the
-    // clear step must resolve entityId from the unified tab or the flag sticks.
+    // Why (regression): activateTab gets a *unified* tabId but the bell is keyed by entityId, so it must resolve entityId or the bell won't clear on click.
     it('clears unreadTerminalTabs for a terminal tab when its unified tab activates', () => {
       const t1 = store.getState().createUnifiedTab(WT, 'terminal')
       const t2 = store.getState().createUnifiedTab(WT, 'terminal')
       // t2 is active after creation; move focus to t1 so we can mark t2 unread.
       store.getState().activateTab(t1.id)
 
-      // Mark WT as the active worktree. activateTab's unread-clear is guarded
-      // on activeWorktreeId so the signal isn't swallowed when activating a
-      // tab in a hidden worktree. Real-world callers only hit activateTab
-      // for visible tabs, so this mirrors production conditions.
+      // Mark WT active: activateTab's unread-clear is guarded on activeWorktreeId so hidden-worktree activations don't swallow the signal.
       store.setState({ activeWorktreeId: WT })
 
-      // t1.entityId and t2.entityId are the terminal tabIds that
-      // markTerminalTabUnread / TabBar read from.
+      // entityId is the terminal tabId that markTerminalTabUnread / TabBar read from.
       const t2TerminalId = t2.entityId
       store.setState({
         unreadTerminalTabs: {
@@ -619,22 +606,14 @@ describe('TabsSlice', () => {
     })
   })
 
-  // ─── markTerminalTabUnread ───────────────────────────────────────
-  //
-  // Ghostty "show until interact" model: BEL always marks the tab unread,
-  // including the currently-focused tab and the active tab of every visible
-  // split group. The indicator is cleared by user interaction (keystroke,
-  // click, focus-gain) via clearTerminalTabUnread — NOT by the mark path
-  // trying to guess whether the user already "sees" the tab.
+  // Ghostty "show until interact": BEL always marks unread (even focused/visible tabs); only user interaction via clearTerminalTabUnread dismisses it.
   describe('markTerminalTabUnread', () => {
     it('marks the tab even when it is active in a visible split group of the active worktree', () => {
-      // Group A: the current worktree's root group, created implicitly by
-      // createUnifiedTab. Populate it with a terminal tab (tabA).
+      // Group A: the worktree's root group (implicit from createUnifiedTab), populated with tabA.
       const tabA = store.getState().createUnifiedTab(WT, 'terminal')
       const groupAId = store.getState().groupsByWorktree[WT][0].id
 
-      // Group B: split to the right of Group A, then populate with its own
-      // terminal tab and focus Group B so tabA is visible-but-not-focused.
+      // Group B: split right of A, populate + focus it so tabA is visible-but-not-focused.
       const groupBId = store.getState().createEmptySplitGroup(WT, groupAId, 'right')
       if (!groupBId) {
         throw new Error('createEmptySplitGroup returned null')
@@ -643,8 +622,7 @@ describe('TabsSlice', () => {
       store.getState().focusGroup(WT, groupBId)
       store.setState({ activeWorktreeId: WT })
 
-      // Seed the backing legacy terminal tab so markTerminalTabUnread's
-      // owner-missing guard doesn't short-circuit.
+      // Seed the backing legacy terminal tab so the owner-missing guard doesn't short-circuit.
       store.setState({
         tabsByWorktree: {
           [WT]: [
@@ -662,9 +640,7 @@ describe('TabsSlice', () => {
         }
       })
 
-      // Fire a bell on Group A's terminal tab. Under ghostty semantics the
-      // indicator must appear even though that tab is visible — only
-      // clearTerminalTabUnread (called from onData / pointerdown) dismisses it.
+      // Fire a bell on Group A's visible tab: under ghostty semantics the indicator still appears — only clearTerminalTabUnread dismisses it.
       store.getState().markTerminalTabUnread(tabA.entityId)
 
       expect(store.getState().unreadTerminalTabs[tabA.entityId]).toBe(true)
@@ -677,8 +653,7 @@ describe('TabsSlice', () => {
       const groupAId = store.getState().groupsByWorktree[WT][0].id
       store.getState().activateTab(tabA1.id)
 
-      // Group B split to the right with its own tab (so there are two visible
-      // groups, matching the split-group condition). Focus Group B.
+      // Split Group B to the right with its own tab (two visible groups, matching the split-group condition); focus it.
       const groupBId = store.getState().createEmptySplitGroup(WT, groupAId, 'right')
       if (!groupBId) {
         throw new Error('createEmptySplitGroup returned null')
@@ -686,10 +661,7 @@ describe('TabsSlice', () => {
       store.getState().createUnifiedTab(WT, 'terminal', { targetGroupId: groupBId })
       store.getState().focusGroup(WT, groupBId)
       store.setState({ activeWorktreeId: WT })
-      // Why: markTerminalTabUnread guards against writing unread for a tab
-      // that no longer exists in tabsByWorktree. In production, every
-      // terminal unified tab has a backing legacy terminal tab (createTab
-      // calls createUnifiedTab with matching ids); seed that invariant here.
+      // Why: markTerminalTabUnread skips tabs missing from tabsByWorktree, so seed the backing legacy tab that every terminal unified tab has in production.
       store.setState({
         tabsByWorktree: {
           [WT]: [
@@ -713,19 +685,11 @@ describe('TabsSlice', () => {
       expect(store.getState().unreadTerminalTabs[tabA2.entityId]).toBe(true)
     })
 
-    // Why: under the show-until-interact model, BEL fires unconditionally
-    // even when the user is looking at a non-terminal surface or the tab
-    // is globally active. This test pins that behavior for the "editor is
-    // on screen, terminal is offscreen" case — clearly a legitimate unread.
+    // Why: under show-until-interact, BEL fires unconditionally even on a non-terminal/offscreen surface — a legitimate unread.
     it('still marks the tab when the active surface is not terminal', () => {
       const tab = store.getState().createUnifiedTab(WT, 'terminal')
-      // Point global active* at this tab (matches post-activate state) but
-      // mark a *different* worktree as active so the visible-groups check
-      // does not apply. The only remaining guard is activeTabType, which
-      // we set to 'editor' — the user is NOT looking at this terminal.
-      // Why: seed tabsByWorktree to match the production invariant that
-      // every terminal unified tab has a backing legacy terminal tab —
-      // markTerminalTabUnread now guards against a missing owner tab.
+      // Point active* at this tab but mark a different worktree active (skips the visible-groups check); only activeTabType='editor' remains as a guard.
+      // Why: seed tabsByWorktree — markTerminalTabUnread guards against a missing owner tab.
       store.setState({
         activeWorktreeId: 'other-wt::/path/x',
         activeTabId: tab.entityId,
@@ -753,9 +717,7 @@ describe('TabsSlice', () => {
 
     it('is a no-op when the tab is already flagged', () => {
       const tab = store.getState().createUnifiedTab(WT, 'terminal')
-      // Why: seed tabsByWorktree so markTerminalTabUnread's owner-missing guard
-      // (terminals.ts:641-643) doesn't short-circuit — we need to exercise the
-      // "already flagged" branch further down (terminals.ts:673-676).
+      // Why: seed tabsByWorktree so the owner-missing guard doesn't short-circuit before we reach the "already flagged" branch.
       store.setState({
         unreadTerminalTabs: { [tab.entityId]: true as const },
         activeTabId: 'something-else',
@@ -784,10 +746,7 @@ describe('TabsSlice', () => {
       expect(store.getState().unreadTerminalTabs).toBe(before)
     })
 
-    // Why: markTerminalTabUnread is agent-agnostic — the working→idle
-    // transition in onAgentBecameIdle fires once per Claude task and MUST
-    // raise the dot; blocking it at the store layer would swallow the
-    // completion signal.
+    // Why: markTerminalTabUnread is agent-agnostic — blocking the working→idle dot here would swallow the agent's completion signal.
     it('marks unread for an agent tab when it is not focused', () => {
       const agentTabId = 'agent-tab-1'
       store.setState({
@@ -816,11 +775,7 @@ describe('TabsSlice', () => {
     })
   })
 
-  // ─── clearTerminalTabUnread ──────────────────────────────────────────
-  //
-  // Called on actual user interaction with a terminal pane (keystroke via
-  // xterm onData, or pointerdown on the container). Pins the dismissal half
-  // of the show-until-interact contract.
+  // Called on real user interaction (xterm onData keystroke or pointerdown) — the dismissal half of show-until-interact.
   describe('clearTerminalTabUnread', () => {
     it('removes the tab from unreadTerminalTabs', () => {
       const tabId = 'bell-tab-1'
@@ -844,12 +799,7 @@ describe('TabsSlice', () => {
     })
   })
 
-  // ─── focusGroup clears unread on focused group's terminal tab ─────────
-  //
-  // Regression guard: users clicking a group that already had its tab
-  // "active" (so activateTab doesn't run) must still dismiss the indicator
-  // on that group's active terminal tab. Without this, the bell lingers
-  // until the tab is clicked a second time.
+  // Regression guard: clicking a group whose tab is already active (no activateTab) must still dismiss the bell, else it lingers until a second click.
   describe('focusGroup', () => {
     it('does not broadcast active-surface writes when the focused group is already current', () => {
       const editorFileId = '/tmp/feature/src/main.ts'
@@ -893,9 +843,7 @@ describe('TabsSlice', () => {
       expect(store.getState().activeTabTypeByWorktree).toBe(before.activeTabTypeByWorktree)
     })
 
-    // Why: focusGroup is fired on every pointerdown within a split group's
-    // chrome (onPointerDown + onFocusCapture in TabGroupPanel). Clearing the
-    // tab-level bell here is fine — the user is now looking at this group.
+    // Why: focusGroup fires on every pointerdown in the group chrome, so clearing the tab-level bell here is safe — the user is now viewing it.
     it("clears the tab-level bell on the focused group's active tab", () => {
       const tabA = store.getState().createUnifiedTab(WT, 'terminal')
       const groupAId = store.getState().groupsByWorktree[WT][0].id
@@ -907,16 +855,13 @@ describe('TabsSlice', () => {
       // Focus Group B first so the active group is not A.
       store.getState().focusGroup(WT, groupBId)
 
-      // Seed tab-level unread on Group A's terminal tab. Also mark WT as the
-      // active worktree — focusGroup's unread-clear is guarded on
-      // activeWorktreeId to avoid swallowing bells in hidden worktrees.
+      // Mark WT active: focusGroup's unread-clear is guarded on activeWorktreeId to avoid swallowing bells in hidden worktrees.
       store.setState({
         unreadTerminalTabs: { [tabA.entityId]: true as const },
         activeWorktreeId: WT
       })
 
-      // Clicking Group A's chrome re-focuses the group without necessarily
-      // calling activateTab (its active tab hasn't changed).
+      // Clicking Group A's chrome re-focuses it without calling activateTab (active tab unchanged).
       store.getState().focusGroup(WT, groupAId)
 
       // Tab-level bell cleared — the user is now viewing this tab.
@@ -940,9 +885,7 @@ describe('TabsSlice', () => {
         activeWorktreeId: WT
       })
 
-      // Why: both groups' active tabs are simultaneously visible in a split
-      // layout, so neither should keep a stale unread bell once the user is
-      // looking at the workspace.
+      // Why: both groups' active tabs are visible in a split, so neither keeps a stale unread bell once focused.
       store.getState().focusGroup(WT, groupAId)
 
       expect(store.getState().unreadTerminalTabs[tabA.entityId]).toBeUndefined()
@@ -1366,9 +1309,7 @@ describe('TabsSlice', () => {
     })
 
     it('syncs isPinned to the TerminalTab in tabsByWorktree (reconcile echo guard)', () => {
-      // Why: reconcile derives a remote tab's pin from tabsByWorktree[*].isPinned;
-      // if pin/unpin only touched unifiedTabsByWorktree, an unrelated host
-      // snapshot would recompute isPinned:false and un-pin during the echo window.
+      // Why: reconcile derives pin from tabsByWorktree[*].isPinned; without syncing, a host snapshot re-computes isPinned:false and un-pins during the echo window.
       const tab = store.getState().createUnifiedTab(WT, 'terminal')
       store.setState((state) => ({
         tabsByWorktree: {
@@ -2126,11 +2067,7 @@ describe('TabsSlice', () => {
     })
 
     it('promotes legacy terminals to the worktree remembered tab, not always the first one', () => {
-      // Why (regression): selecting a non-first terminal, switching to another
-      // worktree, then returning must land on the remembered tab. Reconcile
-      // used to seed a freshly-ensured group with restoredLegacyTabs[0], so the
-      // remembered selection in activeTabIdByWorktree was silently dropped and
-      // the worktree always reopened on Terminal 1.
+      // Why (regression): reconcile seeded the group with restoredLegacyTabs[0], dropping the remembered selection so it always reopened Terminal 1.
       const firstTerminalId = 'runtime-terminal-1'
       const secondTerminalId = 'runtime-terminal-2'
 
@@ -2179,13 +2116,7 @@ describe('TabsSlice', () => {
     })
 
     it('keeps a sole terminal renderable after its PTY exits so a failed direnv does not strand the worktree', () => {
-      // Why (regression): a PR worktree's only terminal can die on startup (a
-      // failing .envrc/direnv). pty-connection keeps that dead pane mounted
-      // instead of bouncing to Landing; this asserts the supporting invariant —
-      // once a terminal is promoted to a unified tab, clearing its PTY does NOT
-      // make it an orphan, so reconcile still reports it renderable (count 1).
-      // If this regressed to 0, the worktree would auto-respawn or get torn
-      // down (setActiveWorktree(null)), reintroducing the Landing bounce.
+      // Why (regression): a promoted terminal whose PTY dies must stay renderable, not orphan and bounce to Landing.
       const tab = store
         .getState()
         .createTab(WT, undefined, undefined, { pendingActivationSpawn: true })
diff --git a/src/renderer/src/store/slices/tabs.ts b/src/renderer/src/store/slices/tabs.ts
index 79513b1254b..e6dc3b798d3 100644
--- a/src/renderer/src/store/slices/tabs.ts
+++ b/src/renderer/src/store/slices/tabs.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: split-tab group state has to update layout,
- * per-group focus, and tab membership atomically. Keeping those transitions in
- * one slice avoids split-brain behavior between the unified tab model and the
- * legacy terminal/editor/browser content slices. */
+/* eslint-disable max-lines -- Why: split-tab group state updates layout, focus, and tab membership atomically in one slice to avoid split-brain. */
 import type { StateCreator } from 'zustand'
 import type { AppState } from '../types'
 import type {
@@ -44,8 +41,7 @@ export type TabSplitDirection = 'left' | 'right' | 'up' | 'down'
 
 export type TabsSlice = {
   unifiedTabsByWorktree: Record<string, Tab[]>
-  // Why: signals the matching tab's inline title editor to open. A global
-  // keyboard shortcut (tab.rename) sets this; the tab clears it on consume.
+  // Why: id of the tab whose inline title editor should open; shortcut (tab.rename) sets it, the tab clears it on consume.
   renamingTabId: string | null
   groupsByWorktree: Record<string, TabGroup[]>
   activeGroupIdByWorktree: Record<string, string>
@@ -118,8 +114,7 @@ export type TabsSlice = {
   setTabLabel: (tabId: string, label: string) => void
   /** Set a tab's view mode (terminal vs native chat). Patches only that tab. */
   setTabViewMode: (tabId: string, mode: 'terminal' | 'chat') => void
-  /** Flip a tab between the terminal and native chat renderings. The live
-   *  TerminalPane stays mounted — this only changes which surface is shown. */
+  /** Flip a tab between terminal and native-chat renderings; the live TerminalPane stays mounted. */
   toggleTabViewMode: (tabId: string) => void
   setTabCustomLabel: (
     tabId: string,
@@ -182,9 +177,7 @@ export type TabsSlice = {
   ) => void
 }
 
-// Why: keep the TerminalTab (tabsByWorktree) pin in sync with the unified-tab
-// pin so reconcile's `existing.isPinned` fallback stays authoritative locally.
-// Returns an empty patch when the tab isn't a persisted TerminalTab.
+// Why: keep the TerminalTab pin in sync with the unified pin so reconcile's existing.isPinned fallback stays authoritative locally.
 function patchTerminalTabPinned(
   tabsByWorktree: Record<string, TerminalTab[]>,
   worktreeId: string,
@@ -203,14 +196,11 @@ function patchTerminalTabPinned(
   }
 }
 
-// Why: pin is host-authoritative for remote-server tabs, so mirror it to the
-// host (like setTabColor) or it's lost on reconnect/restart/other clients.
+// Why: pin is host-authoritative for remote-server tabs, so mirror it (like setTabColor) or it's lost on reconnect/other clients.
 // Dynamic import keeps this store slice off the runtime layer.
 function mirrorTabPinnedToHost(state: AppState, tabId: string, isPinned: boolean): void {
   const found = findTabAndWorktree(state.unifiedTabsByWorktree, tabId)
-  // Why: only terminal tab pins are persisted host-side today (browser/editor
-  // tracked in #5729), so skip the RPC for other types instead of a no-op round
-  // trip.
+  // Why: only terminal tab pins are persisted host-side today (browser/editor in #5729); skip the RPC for other types.
   if (
     !found ||
     found.tab.contentType !== 'terminal' ||
@@ -224,18 +214,15 @@ function mirrorTabPinnedToHost(state: AppState, tabId: string, isPinned: boolean
   )
 }
 
-// Why: viewMode is host-tracked like color/pin, so mirror the local toggle/set to
-// the host or it's lost on reconnect/restart and never reaches paired clients.
-// Only the user/RPC-set action path mirrors — never the reconcile that applies a
-// host value — so the echoed snapshot can't re-trigger an outbound RPC (no loop).
+// Why: viewMode is host-tracked like color/pin, so mirror local sets or they're lost on reconnect and to paired clients.
+// Only the action path mirrors (never reconcile applying a host value), so the echoed snapshot can't re-trigger an outbound RPC.
 function mirrorTabViewModeToHost(
   state: AppState,
   tabId: string,
   viewMode: 'terminal' | 'chat'
 ): void {
   const found = findTabAndWorktree(state.unifiedTabsByWorktree, tabId)
-  // Why: only terminal tab viewMode is persisted host-side; skip the RPC for other
-  // types instead of a no-op round trip.
+  // Why: only terminal tab viewMode is persisted host-side; skip the RPC for other types instead of a no-op round trip.
   if (
     !found ||
     found.tab.contentType !== 'terminal' ||
@@ -487,9 +474,7 @@ function deriveActiveSurfaceForWorktree(
   } else if (hasGroupOwnedSurface) {
     activeFileId = fileStillOpen ? restoredFileId : null
     activeBrowserTabId = browserTabStillOpen ? restoredBrowserTabId : (browserTabs[0]?.id ?? null)
-    // Why: when the user focuses an empty split, global shortcuts should
-    // target that group's default terminal area instead of the previously
-    // active browser/editor in another group.
+    // Why: focusing an empty split should target its default terminal area, not the previously active browser/editor in another group.
     activeTabType = 'terminal'
   } else if (browserTabStillOpen) {
     activeFileId = fileStillOpen ? restoredFileId : null
@@ -669,8 +654,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       const shouldActivate = init?.activate ?? true
       const nextActiveTabId = shouldActivate ? created.id : (group.activeTabId ?? created.id)
       const sanitizedRecent = sanitizeRecentTabIds(group.recentTabIds, nextOrder)
-      // Why: automation-created browser tabs need to exist and paint without
-      // stealing the visible group selection from the user's current tab.
+      // Why: automation-created browser tabs must paint without stealing the visible group selection from the user's current tab.
       const nextRecent = shouldActivate
         ? pushRecentTabId(sanitizedRecent, created.id)
         : sanitizedRecent
@@ -827,13 +811,8 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
         return {}
       }
       const { tab, worktreeId } = found
-      // Why: activating a terminal tab dismisses the tab-level bell — the user
-      // has now moved their eyes to this tab.
-      //
-      // Why (activeWorktree guard below): only dismiss the tab-level bell when
-      // the tab is in the active worktree — otherwise the tab is not visible
-      // yet and the signal would be lost before the user saw it. Mirrors the
-      // guard in focusGroup.
+      // Why: activating a terminal tab dismisses its tab-level bell — the user has moved their eyes here.
+      // Why (activeWorktree guard below): only when the tab is in the active worktree, else the unseen signal is lost (mirrors focusGroup).
       const terminalEntityId = tab.contentType === 'terminal' ? tab.entityId : null
       const nextUnreadTerminalTabs =
         state.activeWorktreeId === worktreeId &&
@@ -861,10 +840,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
               ? {
                   ...group,
                   activeTabId: tabId,
-                  // Why: MRU tracks every activation within the group so
-                  // closeUnifiedTab can jump back to the previous tab instead
-                  // of the visual neighbor. Sanitize first to prune ids from
-                  // removed tabs that may have lingered in persisted state.
+                  // Why: track every activation in the group's MRU so closeUnifiedTab returns to the previous tab; sanitize to prune removed ids.
                   recentTabIds: pushRecentTabId(
                     sanitizeRecentTabIds(group.recentTabIds, group.tabOrder),
                     tabId
@@ -877,9 +853,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
           ...state.activeGroupIdByWorktree,
           [worktreeId]: tab.groupId
         },
-        // Why: skip writing unreadTerminalTabs when the reference is unchanged —
-        // avoids a no-op top-level state allocation that would force re-evaluation
-        // of full-state selectors. Mirrors focusGroup / reconcileWorktreeTabModel.
+        // Why: skip writing unreadTerminalTabs when the reference is unchanged, avoiding a no-op alloc that re-runs full-state selectors.
         ...(nextUnreadTerminalTabs !== state.unreadTerminalTabs
           ? { unreadTerminalTabs: nextUnreadTerminalTabs }
           : {})
@@ -902,8 +876,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
     if (tab.contentType === 'terminal' && !opts?.terminalRetirementHandled) {
       const dedupedGroupOrder = dedupeTabOrder(group.tabOrder)
       const wasLastTab = dedupeTabOrder(dedupedGroupOrder.filter((id) => id !== tabId)).length === 0
-      // Why: unified-only hydrated tabs still own provider sessions even when
-      // their legacy terminal row is missing, so every terminal close retires by entity id.
+      // Why: unified-only hydrated tabs still own provider sessions without a legacy row, so retire every terminal close by entity id.
       get().closeTab(tab.entityId, { recordInteraction: opts?.recordInteraction })
       return { closedTabId: tabId, wasLastTab, worktreeId }
     }
@@ -911,10 +884,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
     const dedupedGroupOrder = dedupeTabOrder(group.tabOrder)
     const remainingOrder = dedupeTabOrder(dedupedGroupOrder.filter((id) => id !== tabId))
     const wasLastTab = remainingOrder.length === 0
-    // Why: when closing the active tab, walk the group's MRU stack back to the
-    // previously-active tab instead of the visual neighbor. `pickNextActiveTab`
-    // falls back to pickNeighbor when the MRU is empty (hydrated sessions,
-    // never-visited siblings) so behavior degrades gracefully.
+    // Why: on closing the active tab, walk the MRU stack to the previously-active tab; pickNextActiveTab falls back to the neighbor.
     const nextActiveTabId =
       group.activeTabId === tabId
         ? wasLastTab
@@ -931,10 +901,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       const nextTabs = (current.unifiedTabsByWorktree[worktreeId] ?? []).filter(
         (item) => item.id !== tabId
       )
-      // Why: closeUnifiedTab can be invoked without going through terminals.closeTab
-      // (e.g., close-to-right / close-others gestures via closeOtherTabs and
-      // closeTabsToRight). The unread-flag map is keyed by terminal entityId and
-      // would otherwise leak a stale dot for a tab that no longer renders.
+      // Why: close-to-right/others bypass terminals.closeTab, so clear the entityId-keyed unread flag here or a stale dot leaks.
       let nextUnreadTerminalTabs = current.unreadTerminalTabs
       if (terminalEntityId && current.unreadTerminalTabs[terminalEntityId]) {
         nextUnreadTerminalTabs = { ...current.unreadTerminalTabs }
@@ -978,18 +945,11 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
         },
         layoutByWorktree: nextLayoutByWorktree,
         activeGroupIdByWorktree: nextActiveGroupIdByWorktree,
-        // Why: skip writing unreadTerminalTabs when the reference is unchanged —
-        // avoids a no-op top-level state allocation that would force re-evaluation
-        // of full-state selectors. Mirrors focusGroup / reconcileWorktreeTabModel.
+        // Why: skip writing unreadTerminalTabs when the reference is unchanged, avoiding a no-op alloc that re-runs full-state selectors.
         ...(nextUnreadTerminalTabs !== current.unreadTerminalTabs
           ? { unreadTerminalTabs: nextUnreadTerminalTabs }
           : {}),
-        // Why: the split-group model can legally derive "terminal with no
-        // active tab" after the final unified tab closes. That leaves the
-        // worktree selected but render-empty, so the workspace shows a blank
-        // pane instead of Orca's landing screen. When that happens, write the
-        // landing-state fallback directly instead of recomputing active-surface
-        // fields from a worktree that is no longer active.
+        // Why: closing the last tab can leave the worktree selected but render-empty, so write the landing-state fallback directly.
         ...(shouldDeactivateWorktree
           ? {
               activeWorktreeId: null,
@@ -1052,9 +1012,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
         if (!group) {
           continue
         }
-        // Why: drag-and-drop should preserve a single canonical position for
-        // each tab. Sanitizing here restores the invariant at the store
-        // boundary so later group operations do not branch on duplicate ids.
+        // Why: dedupe at the store boundary so each tab keeps one canonical position and later group ops don't branch on duplicate ids.
         const nextTabOrder = dedupeTabOrder(tabIds)
         reordered = true
         const orderMap = new Map(nextTabOrder.map((id, index) => [id, index]))
@@ -1099,13 +1057,10 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       if (!found) {
         return {}
       }
-      // Why: default is 'terminal' for legacy/missing, so the first toggle flips
-      // to 'chat'. patchTab mutates only this tab, leaving split siblings intact.
+      // Why: viewMode defaults to 'terminal' for legacy/missing, so the first toggle flips to 'chat'.
       const fromMode: 'terminal' | 'chat' = found.tab.viewMode === 'chat' ? 'chat' : 'terminal'
       const nextMode = fromMode === 'chat' ? 'terminal' : 'chat'
-      // Why: `launchAgent` lives on the legacy terminal tab keyed by the unified
-      // tab's entityId — resolve it here so the toggle telemetry can attribute
-      // adoption by agent without threading it through every caller.
+      // Why: launchAgent lives on the legacy terminal tab (keyed by entityId); resolve it here so toggle telemetry can attribute by agent.
       const agent =
         (state.tabsByWorktree[found.worktreeId] ?? []).find(
           (terminal) => terminal.id === found.tab.entityId
@@ -1169,9 +1124,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
           ...state.unifiedTabsByWorktree,
           [worktreeId]: applyTabOrderSortValues(tabs, tabOrder)
         },
-        // Why: reconcile derives a tab's pin from the TerminalTab (tabsByWorktree),
-        // so mirror the pin there too — otherwise an unrelated host snapshot
-        // recomputes isPinned:false and visually un-pins during the echo window.
+        // Why: reconcile derives pin from the TerminalTab, so mirror it there too or a host snapshot recomputes isPinned:false and un-pins during the echo window.
         ...patchTerminalTabPinned(state.tabsByWorktree, worktreeId, tabId, true),
         groupsByWorktree: {
           ...state.groupsByWorktree,
@@ -1278,9 +1231,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
 
     const groupId = createBrowserUuid()
     set((state) => ({
-      // Why: a freshly selected worktree can legitimately have zero tabs, but
-      // split-group affordances still need a canonical root group so new tabs
-      // and splits land in a deterministic place like VS Code's editor area.
+      // Why: a zero-tab worktree still needs a canonical root group so new tabs and splits land in a deterministic place.
       groupsByWorktree: {
         ...state.groupsByWorktree,
         [worktreeId]: [{ id: groupId, worktreeId, activeTabId: null, tabOrder: [] }]
@@ -1306,15 +1257,8 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
             ...state.activeGroupIdByWorktree,
             [worktreeId]: groupId
           }
-      // Why: focusing a split group surfaces whichever terminal tab is already
-      // active in that group, so the tab-level bell is no longer needed.
-      //
-      // Why (activeWorktree guard below): only clear unreadTerminalTabs when
-      // focusing a group within the *active* worktree. If the caller is
-      // focusing a group in a background worktree, that tab is not visible
-      // yet — dismissing its bell here would silently swallow the signal
-      // before the user ever sees the tab. All current callers only fire for
-      // the active worktree, but this guard prevents future misuse.
+      // Why: focusing a group surfaces its active terminal tab, so dismiss the tab-level bell.
+      // Why (activeWorktree guard below): only when the group is in the active worktree, else the unseen tab's bell is swallowed.
       if (state.activeWorktreeId !== worktreeId) {
         if (groupAlreadyFocused) {
           return state
@@ -1365,11 +1309,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       }
       return {
         ...(groupAlreadyFocused ? {} : { activeGroupIdByWorktree: nextActiveGroupIdByWorktree }),
-        // Why: only write unreadTerminalTabs back into state when it actually
-        // changed. The IIFE above returns state.unreadTerminalTabs by reference
-        // on no-op; preserving that reference via conditional spread keeps
-        // downstream selectors/subscribers from firing spuriously. This matches
-        // the pattern used by activateTab and closeUnifiedTab.
+        // Why: only write unreadTerminalTabs when it changed — preserving the reference keeps selectors/subscribers from firing spuriously.
         ...(nextUnreadTerminalTabs !== state.unreadTerminalTabs
           ? { unreadTerminalTabs: nextUnreadTerminalTabs }
           : {}),
@@ -1396,8 +1336,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
         groupId,
         remainingGroups[0]?.id ?? null
       )
-      // Why: drop the dead group's recent-quick-command entry so the in-memory
-      // map can't grow unbounded as users open/close groups.
+      // Why: drop the dead group's recent-quick-command entry so the map can't grow unbounded as groups open/close.
       const { [groupId]: _droppedRecent, ...remainingRecent } = current.recentQuickCommandIdByGroup
       return {
         groupsByWorktree: { ...current.groupsByWorktree, [worktreeId]: remainingGroups },
@@ -1476,9 +1415,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
 
       const dedupedSourceGroupOrder = dedupeTabOrder(sourceGroup.tabOrder)
       const sourceOrder = dedupeTabOrder(dedupedSourceGroupOrder.filter((id) => id !== tabId))
-      // Why: defensive filter so target order can't grow a duplicate if the
-      // tab id somehow already exists there (stale state, prior bug). See
-      // dropUnifiedTab for the same guard.
+      // Why: defensive dedupe so target order can't grow a duplicate id (stale state); see dropUnifiedTab for the same guard.
       const targetOrder = dedupeTabOrder(targetGroup.tabOrder.filter((id) => id !== tabId))
       const targetIndex = Math.max(
         0,
@@ -1499,9 +1436,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
             ...group,
             activeTabId:
               group.activeTabId === tabId
-                ? // Why: when the moved tab was active in the source, keep
-                  // MRU-aware selection so the user lands on their previously
-                  // focused tab rather than a visual neighbor.
+                ? // Why: keep MRU-aware selection so the user lands on their previously-focused tab, not a visual neighbor.
                   pickNextActiveTab(dedupedSourceGroupOrder, sourceGroup.recentTabIds, tabId)
                 : group.activeTabId,
             tabOrder: sourceOrder,
@@ -1603,9 +1538,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
           layout
         })
       ) {
-        // Why: dragging the final tab in a group onto that same group's edge,
-        // or onto the adjacent sibling's matching edge, creates a transient
-        // column only to collapse the emptied source immediately.
+        // Why: dropping a group's last tab on its own/sibling matching edge only makes a transient column that immediately collapses.
         return {}
       }
 
@@ -1651,11 +1584,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       const sourceOrder = dedupeTabOrder(dedupedSourceGroupOrder.filter((id) => id !== tabId))
       const destinationGroup =
         nextGroups.find((group) => group.id === resolvedTargetGroupId) ?? targetGroup
-      // Why: the target group's stored order can already contain this tab id
-      // from a prior racey write or a same-group split where the source and
-      // destination transiently share it. Splicing without filtering first
-      // would leave the same id in the order twice, which React surfaces as
-      // a duplicate-key warning in TabBar and can mis-reconcile xterm panes.
+      // Why: target order may already hold this tab id (racey write / same-group split); dedupe first or React hits a duplicate key.
       const targetOrder = dedupeTabOrder(destinationGroup.tabOrder.filter((id) => id !== tabId))
       const targetIndex = Math.max(
         0,
@@ -1673,9 +1602,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
             ...group,
             activeTabId:
               group.activeTabId === tabId
-                ? // Why: same MRU-aware fallback as moveUnifiedTabToGroup so
-                  // the pane left behind by a drag keeps the user on their
-                  // previously-active tab.
+                ? // Why: same MRU-aware fallback as moveUnifiedTabToGroup — the drag keeps the user on their previously-active tab.
                   pickNextActiveTab(dedupedSourceGroupOrder, sourceGroup.recentTabIds, tabId)
                 : group.activeTabId,
             tabOrder: sourceOrder,
@@ -1809,9 +1736,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       return {
         layoutByWorktree: {
           ...state.layoutByWorktree,
-          // Why: split sizing is part of the tab-group model, not transient UI
-          // state. Persisting ratios here keeps restores and multi-step group
-          // operations in sync with what the user actually resized.
+          // Why: split ratios belong to the tab-group model (not transient UI), so persist them for restores and multi-step group ops.
           [worktreeId]: updateSplitRatio(
             currentLayout,
             nodePath.length > 0 ? nodePath.split('.') : [],
@@ -1834,15 +1759,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       if (unifiedTerminalEntityIds.has(tab.id)) {
         return false
       }
-      // Why: this is a one-shot migration filter for tabs not yet promoted
-      // to unifiedTabs — keeping the wake-hint `tab.ptyId` clause is
-      // intentional. tab.ptyId is the preserved sessionId (so wake can
-      // reattach to the same daemon-history dir / relay session); a slept
-      // tab will have `livePtyIds` empty *and* `tab.ptyId` populated, and
-      // we want it included in the migration sweep so reconcile picks it
-      // up. Reconcile fires again post-reattach, so the eventual live PTY
-      // also routes through this branch. Do *not* repurpose this as an
-      // "is this tab alive?" check — those reads must use ptyIdsByTabId.
+      // Why: migration filter — tab.ptyId (preserved sessionId) keeps slept tabs in the sweep for wake reattach; NOT a liveness check (use ptyIdsByTabId).
       const livePtyIds = state.ptyIdsByTabId[tab.id] ?? []
       return livePtyIds.length > 0 || tab.ptyId != null
     })
@@ -1880,10 +1797,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
             }))
     const reconciledUnifiedTabs =
       restoredLegacyTabs.length > 0 ? [...unifiedTabs, ...restoredLegacyTabs] : unifiedTabs
-    // Why: when a freshly-ensured group has no active tab yet, seed it from the
-    // worktree's remembered selection before the first restored tab. Otherwise
-    // returning to a worktree whose terminals only exist in the runtime slice
-    // always reopens on Terminal 1 and drops the tab the user left on.
+    // Why: seed a freshly-ensured group's active tab from the remembered selection, else the worktree always reopens on Terminal 1.
     const rememberedLegacyActiveTabId = state.activeTabIdByWorktree[worktreeId]
     const restoredLegacyTabIds = new Set(restoredLegacyTabs.map((tab) => tab.id))
     const legacyFallbackActiveTabId =
@@ -1894,10 +1808,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       restoredLegacyTabs.length > 0 && reconciliationGroup
         ? updateGroup(ensuredGroupState!.groupsByWorktree[worktreeId] ?? [], {
             ...reconciliationGroup,
-            // Why: legacy terminal tabs can still exist in the runtime slice
-            // after split groups became the source of truth. Restoring them
-            // into the active/root group keeps existing live PTYs reachable
-            // instead of making activation spawn a duplicate "Terminal 2".
+            // Why: restore runtime-slice legacy tabs into the active/root group so live PTYs stay reachable instead of spawning a duplicate.
             activeTabId: reconciliationGroup.activeTabId ?? legacyFallbackActiveTabId,
             tabOrder: dedupeTabOrder([
               ...reconciliationGroup.tabOrder,
@@ -1940,9 +1851,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       const tabOrderUnchanged =
         tabOrder.length === group.tabOrder.length &&
         tabOrder.every((tabId, index) => tabId === group.tabOrder[index])
-      // Why: reconciliation can drop backing tabs (stale persisted ids, dead
-      // PTYs, closed editor files). Keep the MRU stack in sync so the next
-      // close doesn't try to activate a tab the renderer no longer owns.
+      // Why: keep the MRU stack in sync with dropped tabs so the next close doesn't activate one the renderer no longer owns.
       const recentTabIds = sanitizeRecentTabIds(group.recentTabIds, tabOrder)
       const recentUnchanged =
         recentTabIds.length === (group.recentTabIds ?? []).length &&
@@ -1993,11 +1902,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       layoutChanged ||
       orphanTerminalIds.size > 0
     ) {
-      // Why: when reconcile drops a unified terminal tab (stale persisted id,
-      // dead PTY, closed editor), its entry in unreadTerminalTabs (keyed by the
-      // terminal tab's entityId) would otherwise linger forever and bleed into
-      // downstream persistence/selectors. Mirrors the cleanup in closeUnifiedTab
-      // which removes the unread flag when a terminal tab is torn down.
+      // Why: drop unreadTerminalTabs entries (keyed by entityId) for terminal tabs reconcile removed, or the stale flag lingers forever.
       const droppedTerminalEntityIds: string[] = []
       for (const tab of unifiedTabs) {
         if (tab.contentType !== 'terminal') {
@@ -2036,10 +1941,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
             ? {
                 layoutByWorktree: {
                   ...current.layoutByWorktree,
-                  // Why: a restored live runtime terminal needs a concrete leaf
-                  // in the split-group model before activation runs again.
-                  // Without this, the worktree still looks render-empty and the
-                  // activation fallback spawns a duplicate "Terminal 2".
+                  // Why: restored runtime terminal needs a concrete leaf before activation, else the fallback spawns a duplicate "Terminal 2".
                   [worktreeId]: nextLayout!
                 }
               }
diff --git a/src/renderer/src/store/slices/terminals-hydration.test.ts b/src/renderer/src/store/slices/terminals-hydration.test.ts
index 62f4c35a3d1..aae9aede851 100644
--- a/src/renderer/src/store/slices/terminals-hydration.test.ts
+++ b/src/renderer/src/store/slices/terminals-hydration.test.ts
@@ -139,9 +139,7 @@ describe('hydrateWorkspaceSession', () => {
 
     store.getState().hydrateWorkspaceSession(session)
 
-    // Why: ptyIdsByLeafId contains daemon session IDs that survive restart.
-    // reconnectPersistedTerminals uses them to reattach each split-pane
-    // leaf to its specific daemon session.
+    // Why: ptyIdsByLeafId holds daemon session IDs that survive restart, letting each split-pane leaf reattach to its own session.
     expect(store.getState().terminalLayoutsByTabId['tab-1']).toEqual({
       ...makeLayout(),
       ptyIdsByLeafId: { 'pane:1': 'daemon-session-1' },
@@ -218,9 +216,7 @@ describe('hydrateWorkspaceSession', () => {
       }
     })
 
-    // Why: `id` keeps the `::workspace:<uuid>` identity suffix, but `path` and
-    // `displayName` must resolve to the real folder so Git and other filesystem
-    // callers never spawn against a nonexistent cwd.
+    // Why: id keeps the ::workspace:<uuid> suffix, but path/displayName must resolve to the real folder so callers don't spawn against a missing cwd.
     expect(store.getState().worktreesByRepo['folder-repo']).toEqual([
       expect.objectContaining({ id: worktreeId, path: '/home/user', displayName: 'user' })
     ])
@@ -367,8 +363,7 @@ describe('hydrateWorkspaceSession', () => {
 
     store.getState().hydrateWorkspaceSession(session)
 
-    // Why: restart can preserve scrollback for an exited pane while live siblings
-    // reattach. Keyboard focus must land on a PTY-backed pane, not the dead leaf.
+    // Why: restart can preserve scrollback for an exited pane, so focus must land on a live PTY-backed pane, not the dead leaf.
     expect(store.getState().terminalLayoutsByTabId['tab-1']?.activeLeafId).toBe(liveLeftLeafId)
   })
 
@@ -441,8 +436,7 @@ describe('hydrateWorkspaceSession', () => {
     await store.getState().reconnectPersistedTerminals()
     unsubscribe()
 
-    // Why: startup restores every daemon wake hint, but subscribers should see
-    // one ready-state transition instead of one update per restored tab.
+    // Why: startup restores every daemon wake hint, but subscribers should see one ready-state transition, not one update per restored tab.
     expect(updateCount).toBe(1)
     expect(store.getState().workspaceSessionReady).toBe(true)
     expect(store.getState().ptyIdsByTabId).toMatchObject({
@@ -458,11 +452,7 @@ describe('hydrateWorkspaceSession', () => {
   })
 
   it('stashes deferred SSH session ids for worktrees not yet in worktreesByRepo', async () => {
-    // Why: at cold start SSH worktrees are absent from worktreesByRepo (relay
-    // discovery needs the connection). The deferred stash must fall back to
-    // the repo id embedded in the composite worktree id — otherwise restored
-    // SSH panes fresh-spawn into a missing PTY provider and strand an
-    // "SSH connection is not active" toast.
+    // Why: at cold start SSH worktrees aren't in worktreesByRepo, so the stash must fall back to the repo id embedded in the composite worktree id — else restored panes strand an "SSH connection is not active" toast.
     const store = createTestStore()
     const worktreeId = 'repo1::/home/user/remote-project'
     const sshSessionId = 'ssh:ssh-target-1@@pty-7'
@@ -547,11 +537,7 @@ describe('hydrateWorkspaceSession', () => {
   })
 
   it('seeds worktree nav history with the restored active worktree', () => {
-    // Why: without seeding, the first sidebar click after startup becomes the
-    // only history entry, so Back stays disabled until the user clicks a
-    // second worktree. Seeding here ensures the restored worktree is already
-    // at index 0 so the very first user-driven switch has a prior entry to
-    // go Back to.
+    // Why: seeding the restored worktree at index 0 gives the first user switch a prior entry, so Back isn't disabled until a second click.
     const store = createTestStore()
     const worktreeId = 'repo1::/wt-1'
     seedStore(store, {
@@ -607,10 +593,7 @@ describe('hydrateWorkspaceSession', () => {
     const store = createTestStore()
     seedStore(store, { worktreesByRepo: {} })
 
-    // Why: pre-seed non-default stale values so the assertions below can only
-    // pass if hydration actively overwrites the fields. Without this, the
-    // slice's default `[]` / `-1` would satisfy the expectations even if
-    // hydrateWorkspaceSession never touched nav history in this branch.
+    // Why: pre-seed stale values so the assertions can only pass if hydration actively overwrites nav history in this branch.
     store.setState({ worktreeNavHistory: ['stale-a', 'stale-b'], worktreeNavHistoryIndex: 1 })
 
     const session: WorkspaceSessionState = {
@@ -628,17 +611,11 @@ describe('hydrateWorkspaceSession', () => {
   })
 
   it('drops invalid restored worktree from nav history seed', () => {
-    // Why: hydrateWorkspaceSession validates activeWorktreeId against the
-    // current worktreesByRepo and sets it to null when stale. The history
-    // seed must follow that validation, not the raw session field — otherwise
-    // a deleted worktree would sit at history[0] and fail activation on Back.
+    // Why: the history seed must follow the validated activeWorktreeId (nulled when stale), or a deleted worktree sits at history[0] and fails Back.
     const store = createTestStore()
     seedStore(store, { worktreesByRepo: { repo1: [] } })
 
-    // Why: pre-seed non-default stale values so the assertions below can only
-    // pass if hydration actively overwrites the fields. Without this, the
-    // slice's default `[]` / `-1` would satisfy the expectations even if
-    // hydrateWorkspaceSession never cleared nav history for an invalid worktree.
+    // Why: pre-seed stale values so the assertions can only pass if hydration actively clears nav history for the invalid worktree.
     store.setState({ worktreeNavHistory: ['stale-a', 'stale-b'], worktreeNavHistoryIndex: 1 })
 
     const session: WorkspaceSessionState = {
@@ -657,11 +634,7 @@ describe('hydrateWorkspaceSession', () => {
   })
 
   it('records a subsequent visit on top of the hydration seed so Back is enabled after the first click', () => {
-    // Why: pins down the PR's user-visible contract — after hydration seeds
-    // the restored worktree at index 0, the very first sidebar click appends
-    // a new entry at index 1, which is what makes Back enabled immediately.
-    // Without the seed, the first click would produce a single-entry history
-    // and Back would stay disabled until a second click.
+    // Why: the hydration seed at index 0 lets the first sidebar click enable Back immediately (without it, Back needs a second click).
     const store = createTestStore()
     const wt1 = 'repo1::/wt-1'
     const wt2 = 'repo1::/wt-2'
@@ -693,10 +666,7 @@ describe('hydrateWorkspaceSession', () => {
 
 describe('hydrationSucceeded flag (issue #1158)', () => {
   it('defaults to false so the session writer is gated off at startup', () => {
-    // Why: App.tsx only flips hydrationSucceeded=true after a clean load from
-    // orca-data.json. If a startup error prevents that call, the flag stays
-    // false and the debounced writer never fires — protecting the user's good
-    // on-disk state from being overwritten with an empty in-memory snapshot.
+    // Why: default false so a startup error keeps the debounced writer gated off, protecting good on-disk state from an empty snapshot.
     const store = createTestStore()
     expect(store.getState().hydrationSucceeded).toBe(false)
   })
@@ -710,10 +680,7 @@ describe('hydrationSucceeded flag (issue #1158)', () => {
   })
 
   it('hydrateWorkspaceSession does not flip hydrationSucceeded on its own', () => {
-    // Why: the hydration call can populate state partially and still throw
-    // downstream (e.g. reconnect fails). Leaving the flip to App.tsx — after
-    // hydrateWorkspaceSession has returned without throwing — keeps the gate
-    // honest in those mid-flight failures.
+    // Why: hydration can populate state then throw downstream, so App.tsx flips the flag only after a clean return.
     const store = createTestStore()
     const wt = 'repo1::/wt'
     seedStore(store, {
diff --git a/src/renderer/src/store/slices/terminals.ts b/src/renderer/src/store/slices/terminals.ts
index d6f8b196324..6b92fcdbed6 100644
--- a/src/renderer/src/store/slices/terminals.ts
+++ b/src/renderer/src/store/slices/terminals.ts
@@ -65,9 +65,7 @@ import {
   restorePtyDataHandlersAfterFailedShutdown,
   unregisterPtyDataHandlers
 } from '@/components/terminal-pane/pty-transport'
-// Why: import the store-free registry, not terminal-parked-tab-watchers —
-// that module imports @/store, and a slice importing it would re-enter store
-// creation before this slice finishes evaluating.
+// Why: use the store-free registry (not terminal-parked-tab-watchers, which imports @/store) to avoid re-entering store creation during this slice's eval.
 import {
   disposeParkedTerminalWatchersForPtyIds,
   retireParkedTerminalTab
@@ -182,19 +180,14 @@ function buildRuntimeSessionPlaceholders({
     }
     const worktreeId =
       workspaceScope?.type === 'worktree' ? workspaceScope.worktreeId : workspaceSessionKey
-    // Why: folder-workspace instance IDs carry a synthetic `::workspace:<uuid>`
-    // suffix. The placeholder's `id` keeps it for identity, but `path`/display
-    // must be the real folder path so Git and other filesystem callers do not
-    // spawn against a nonexistent cwd — matching the authoritative worktree.
+    // Why: strip the synthetic `::workspace:<uuid>` suffix so path is the real folder — Git callers must not spawn against a nonexistent cwd.
     const parsed = splitWorktreeIdForFilesystem(worktreeId)
     if (!parsed) {
       continue
     }
     const existingRepo = nextRepos.some((repo) => repo.id === parsed.repoId)
     if (!existingRepo) {
-      // Why: remote catalogs load after hydration, but host-split session
-      // writes need owner metadata. If any repo with this id already exists,
-      // avoid duplicate ids; the worktree placeholder below carries hostId.
+      // Why: remote catalogs load after hydration but host-split session writes need owner metadata; skip if the repo id already exists to avoid duplicates.
       nextRepos = [
         ...nextRepos,
         {
@@ -454,28 +447,18 @@ export type AutomaticAgentResumeClaim = {
 export type TerminalSlice = {
   tabsByWorktree: Record<string, TerminalTab[]>
   activeTabId: string | null
-  /** Per-worktree last-active terminal tab — restored on worktree switch so
-   *  the user returns to the same tab they left, not always tabs[0]. */
+  /** Per-worktree last-active tab, restored on worktree switch so the user returns to where they left, not tabs[0]. */
   activeTabIdByWorktree: Record<string, string | null>
   ptyIdsByTabId: Record<string, string[]>
-  /** Live pane titles keyed by tabId then paneId. Unlike the legacy tab title,
-   *  this preserves split-pane agent status per pane while TerminalPane is mounted. */
+  /** Live pane titles by tabId then paneId; preserves per-pane agent status (unlike the legacy tab title) while TerminalPane is mounted. */
   runtimePaneTitlesByTabId: Record<string, Record<number, string>>
-  /** Why: per-tab activity indicators. A tab gets flagged unread when terminal
-   *  output requests attention (BEL) or an agent-complete notification is
-   *  dispatched for one of its panes. The flag clears when the user activates
-   *  or interacts with the tab. This is ephemeral UI state only — not
-   *  persisted across restarts. */
+  /** Per-tab unread flags (BEL or agent-complete); ephemeral UI state, not persisted. Cleared when the user activates/interacts with the tab. */
   unreadTerminalTabs: Record<string, true>
-  /** Pane-keyed attention marker for split-pane precision. This is narrower
-   *  than unreadTerminalTabs and clears when the user interacts with the exact
-   *  pane that raised attention. */
+  /** Pane-keyed attention marker (narrower than unreadTerminalTabs); clears when the user interacts with the exact pane that raised it. */
   unreadTerminalPanes: Record<string, true>
-  /** Agent-completion source marker for focus-return auto-ack. Kept separate
-   *  from unreadTerminalPanes so generic terminal bells still show until interact. */
+  /** Agent-completion marker for focus-return auto-ack; separate from unreadTerminalPanes so generic bells still show until interact. */
   unreadAgentCompletionPanes: Record<string, true>
-  // Remote guard keys must use renderer-visible, environment-scoped PTY ids;
-  // raw runtime handles are only valid at the RPC boundary.
+  // Remote guard keys must use renderer-visible, environment-scoped PTY ids; raw runtime handles are only valid at the RPC boundary.
   suppressedPtyExitIds: Record<string, true>
   pendingCodexPaneRestartIds: Record<string, true>
   codexRestartNoticeByPtyId: Record<
@@ -485,13 +468,10 @@ export type TerminalSlice = {
   expandedPaneByTabId: Record<string, boolean>
   canExpandPaneByTabId: Record<string, boolean>
   terminalLayoutsByTabId: Record<string, TerminalLayoutSnapshot>
-  /** Most recently run quick-command id per tab group. In-memory only; resets
-   *  on app restart so a stale id from a deleted command can't surface as the
-   *  split-button label across sessions. */
+  /** Most recent quick-command id per group; in-memory only so a deleted command's stale id can't surface as the split-button label. */
   recentQuickCommandIdByGroup: Record<string, string>
   setRecentQuickCommandForGroup: (groupId: string, quickCommandId: string) => void
-  /** Runtime-only claim for automatic sleeping-session recovery tabs. It
-   *  bridges the gap after startup payload consumption and before hooks go live. */
+  /** Runtime-only claim for auto sleeping-session recovery tabs; bridges the gap between startup payload consumption and hooks going live. */
   automaticAgentResumeClaimsByTabId: Record<string, AutomaticAgentResumeClaim>
   claimAutomaticAgentResume: (tabId: string, claim: AutomaticAgentResumeClaim) => void
   /** Launch-time native-chat prompt echo, keyed by terminal tab. In-memory only. */
@@ -503,8 +483,7 @@ export type TerminalSlice = {
     string,
     {
       command: string
-      /** Renderer-delivered startup input for callers that need xterm paste
-       *  semantics before the submit Enter. */
+      /** Renderer-delivered startup input for callers needing xterm paste semantics before the submit Enter. */
       delivery?: 'terminal-paste'
       startupCommandDelivery?: StartupCommandDelivery
       env?: Record<string, string>
@@ -517,53 +496,33 @@ export type TerminalSlice = {
       initialAgentStatus?: { agent: TuiAgent; prompt: string }
       /** Show the restored-session banner when this startup command mounts. */
       showSessionRestoredBanner?: boolean
-      /** Telemetry metadata for the `agent_started` event. Threaded all the
-       *  way to the `pty:spawn` IPC handler in main so the event fires only
-       *  after spawn confirms — never on click-intent. */
+      /** Telemetry for the `agent_started` event; threaded to the pty:spawn handler so it fires only after spawn confirms, not on click-intent. */
       telemetry?: AgentStartedTelemetry
     }
   >
   pendingInitialCwdByTabId: Record<string, string>
-  /** Queued setup-split requests — when present, TerminalPane creates the
-   *  initial pane clean, then splits (vertical or horizontal per user setting)
-   *  and runs the command in the new pane so the main terminal stays
-   *  immediately interactive. */
+  /** Queued setup-split requests; TerminalPane splits and runs the command in a new pane so the main terminal stays immediately interactive. */
   pendingSetupSplitByTabId: Record<
     string,
     { command: string; env?: Record<string, string>; direction: SetupSplitDirection }
   >
-  /** Queued issue-command-split requests — similar to setup splits but triggered
-   *  when an issue is linked during worktree creation and the repo's issue
-   *  automation command is enabled. */
+  /** Queued issue-command-split requests, triggered when an issue is linked at worktree creation and the repo's issue automation is enabled. */
   pendingIssueCommandSplitByTabId: Record<string, { command: string; env?: Record<string, string> }>
   tabBarOrderByWorktree: Record<string, string[]>
   workspaceSessionReady: boolean
   restoredRuntimeHostIdByWorkspaceSessionKey: Record<string, ExecutionHostId>
   defaultTerminalTabsAppliedByWorktreeId: Record<string, true>
   markDefaultTerminalTabsApplied: (worktreeId: string) => void
-  /** True only after hydrateWorkspaceSession ran from a real load of
-   *  orca-data.json. Guards the debounced session writer so that a crash
-   *  during early startup (fetchRepos / fetchAllWorktrees / session.get /
-   *  hydrateWorkspaceSession itself) cannot cause an empty in-memory state
-   *  to be serialized back over the user's good data on disk.
-   *  Kept separate from workspaceSessionReady, which still flips true in
-   *  the error path so the UI can mount without a rich session. */
+  /** True only after hydrateWorkspaceSession loaded real orca-data.json; guards the session writer so an early-startup crash can't overwrite good data on disk. */
   hydrationSucceeded: boolean
   setHydrationSucceeded: (value: boolean) => void
   pendingReconnectWorktreeIds: string[]
   pendingReconnectTabByWorktree: Record<string, string[]>
-  /** Maps tabId → previous ptyId from the last session. When the PTY backend is
-   *  a daemon, the old ptyId doubles as the daemon sessionId — passing it to
-   *  spawn triggers createOrAttach which returns the surviving terminal snapshot. */
+  /** tabId → previous session's ptyId; for daemon backends it doubles as the sessionId, so spawn createOrAttach returns the surviving terminal. */
   pendingReconnectPtyIdByTabId: Record<string, string>
-  // Why: relay session IDs (e.g. pty-0) are stored in tab.ptyId, but
-  // clearTabPtyId nulls it on disconnect.  This map preserves the last
-  // known ID so the session save can capture it even when the relay mux
-  // is temporarily down — without it, remoteSessionIdsByTabId would be
-  // empty and the relay PTY could not be reattached after restart.
+  // Why: clearTabPtyId nulls tab.ptyId on disconnect; keep the last relay ID here so session save can still capture it for reattach after restart.
   lastKnownRelayPtyIdByTabId: Record<string, string>
-  /** ANSI snapshots returned by daemon reattach, keyed by the new ptyId.
-   *  TerminalPane writes these to xterm.js to restore visual state. */
+  /** ANSI snapshots from daemon reattach, keyed by new ptyId; TerminalPane writes them to xterm.js to restore visual state. */
   pendingSnapshotByPtyId: Record<
     string,
     { snapshot: string; cols?: number; rows?: number; isAlternateScreen?: boolean }
@@ -571,9 +530,7 @@ export type TerminalSlice = {
   consumePendingSnapshot: (
     ptyId: string
   ) => { snapshot: string; cols?: number; rows?: number; isAlternateScreen?: boolean } | null
-  /** Cold restore data from disk history after a daemon crash, keyed by
-   *  the new ptyId. Contains read-only scrollback to display above the
-   *  fresh shell prompt. */
+  /** Cold-restore data (read-only scrollback shown above the fresh prompt) from disk history after a daemon crash, keyed by the new ptyId. */
   pendingColdRestoreByPtyId: Record<string, { scrollback: string; cwd: string }>
   consumePendingColdRestore: (ptyId: string) => { scrollback: string; cwd: string } | null
   createTab: (
@@ -585,20 +542,12 @@ export type TerminalSlice = {
       initialPtyId?: string
       activate?: boolean
       recordInteraction?: boolean
-      /** Pre-allocated tab id (e.g. minted by main for CLI/runtime-spawned
-       *  terminals whose PTY env already carries a pane key). Falls back to
-       *  minting a fresh id when omitted or when the supplied id collides
-       *  with an existing tab anywhere in the store (tabIds form the global
-       *  paneKey namespace, so collisions are checked across all worktrees). */
+      /** Pre-allocated tab id (main mints it for CLI/runtime PTYs with a baked pane key); minted fresh on omit or cross-worktree collision. */
       id?: string
-      /** Coding-harness agent being launched in this tab, recorded so the tab
-       *  bar can show the provider icon before the agent's first hook event. */
+      /** Coding-harness agent launched here, recorded so the tab bar shows the provider icon before the agent's first hook event. */
       launchAgent?: TuiAgent
       quickCommandLabel?: string | null
-      /** Initial native-chat view mode for the unified tab. When the
-       *  `openAgentTabsInChatByDefault` setting is on, agent launches pass
-       *  `'chat'` so the tab opens in the native chat view; omitted otherwise
-       *  so the tab keeps the implicit `'terminal'` default. */
+      /** Initial native-chat view mode; agent launches pass 'chat' when openAgentTabsInChatByDefault is on, else omitted for the 'terminal' default. */
       viewMode?: Tab['viewMode']
       startupCwd?: string
     }
@@ -628,18 +577,11 @@ export type TerminalSlice = {
   clearTabLaunchAgent: (tabId: string) => void
   setRuntimePaneTitle: (tabId: string, paneId: number, title: string) => void
   clearRuntimePaneTitle: (tabId: string, paneId: number) => void
-  /** Mark a tab as having unread activity (agent working→idle transition).
-   *  Skipped when the tab is currently visible to the user — either as
-   *  the global active terminal tab, or as the active tab of any split
-   *  group within the active worktree. A visible tab is already "seen",
-   *  so a flag would never clear naturally. */
+  /** Mark a tab unread (agent working→idle); skipped when the tab is visible, since a "seen" flag would never clear. */
   markTerminalTabUnread: (tabId: string) => void
   markTerminalPaneUnread: (paneKey: string) => void
   markAgentCompletionPaneUnread: (paneKey: string) => void
-  /** Clear a tab's unread indicator. Called on user interaction with the
-   *  pane (keystroke, click) — matches ghostty's "show until interact"
-   *  model where the bell stays visible until the user engages with the
-   *  surface that raised it. */
+  /** Clear a tab's unread indicator on user interaction (ghostty "show until interact" model). */
   clearTerminalTabUnread: (tabId: string) => void
   clearTerminalPaneUnread: (paneKey: string) => void
   setTabCustomTitle: (
@@ -734,25 +676,17 @@ export type TerminalSlice = {
   consumeTabIssueCommandSplit: (
     tabId: string
   ) => { command: string; env?: Record<string, string> } | null
-  /** Per-pane timestamp (ms) when the prompt-cache countdown started (agent became idle).
-   *  Keys are `${tabId}:${leafId}` composites so split-pane tabs can track each pane
-   *  independently. null means no active timer for that pane. */
+  /** `${tabId}:${leafId}` → ms when the prompt-cache countdown started (agent idle); null means no active timer for that pane. */
   cacheTimerByKey: Record<string, number | null>
   setCacheTimerStartedAt: (key: string, ts: number | null) => void
-  /** Wall-clock user input markers keyed by paneKey. Hibernation uses these to
-   *  avoid sleeping a completed agent pane that the user has turned into a shell. */
+  /** paneKey → wall-clock user input time; hibernation uses it to avoid sleeping a completed agent pane the user turned into a shell. */
   lastTerminalInputAtByPaneKey: Record<string, number>
   recordTerminalInput: (paneKey: string, timestamp?: number) => void
-  /** Scan all tabs and seed cache timers for any idle Claude sessions that don't
-   *  already have a timer. Called when the feature is enabled mid-session. */
+  /** Seed cache timers for idle Claude sessions missing one; called when the feature is enabled mid-session. */
   seedCacheTimersForIdleTabs: () => void
-  /** SSH target IDs that require a passphrase — deferred to on-demand
-   *  reconnect when the user focuses an affected terminal tab. */
+  /** SSH target IDs needing a passphrase; reconnect is deferred until the user focuses an affected terminal tab. */
   deferredSshReconnectTargets: string[]
-  /** Maps tabId → remote PTY session ID for tabs whose SSH target was
-   *  deferred (passphrase-protected). Persisted across the startup clear
-   *  of pendingReconnectPtyIdByTabId because the deferred reconnect runs
-   *  later, on tab focus. */
+  /** tabId → remote PTY session ID for deferred (passphrase) SSH tabs; survives the startup clear because reconnect runs later, on focus. */
   deferredSshSessionIdsByTabId: Record<string, string>
   setDeferredSshReconnectTargets: (targetIds: string[]) => void
   removeDeferredSshReconnectTarget: (targetId: string) => void
@@ -889,10 +823,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
   setCacheTimerStartedAt: (key, ts) => {
     set((s) => {
       const next = { ...s.cacheTimerByKey, [key]: ts }
-      // Why: when a real pane transition writes a key like `${tabId}:${leafId}`,
-      // clean up any `${tabId}:seed` sentinel left by seedCacheTimersForIdleTabs.
-      // This prevents phantom timers when the seeded key doesn't match the real
-      // pane ID (e.g., idle Claude in pane 2 of a split tab).
+      // Why: a real pane write clears any ':seed' sentinel from seedCacheTimersForIdleTabs, avoiding phantom timers when the seed key doesn't match the real pane.
       const colonIdx = key.indexOf(':')
       if (colonIdx !== -1) {
         const tabId = key.slice(0, colonIdx)
@@ -906,10 +837,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
   },
 
   seedCacheTimersForIdleTabs: () => {
-    // Why: when the user enables the cache timer feature mid-session, any Claude
-    // tabs that are already idle won't have a timer because the working→idle
-    // transition already happened. Scan all tabs and seed timers for idle Claude
-    // sessions that don't already have one.
+    // Why: tabs already idle when the feature is enabled mid-session missed their working→idle transition, so seed timers for them.
     const s = get()
     const now = Date.now()
     const updates: Record<string, number> = {}
@@ -922,10 +850,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         if (status === null || status === 'working') {
           continue
         }
-        // Why: the store doesn't know which pane holds the idle Claude session,
-        // so we use a sentinel suffix. The `setCacheTimerStartedAt` action
-        // automatically cleans up `:seed` entries when any real pane transition
-        // writes to the same tab, preventing phantom timers.
+        // Why: the store doesn't know which pane holds the idle session, so use a ':seed' sentinel; setCacheTimerStartedAt clears it on any real pane write.
         const key = `${tab.id}:seed`
         if (s.cacheTimerByKey[key] == null) {
           updates[key] = now
@@ -962,18 +887,8 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       const existing = (s.tabsByWorktree[worktreeId] ?? []).filter(
         (entry) => !orphanTerminalIds.has(entry.id)
       )
-      // Why: caller-supplied id (e.g. main pre-allocates the tabId for CLI
-      // background terminals so the paneKey env baked into the PTY matches
-      // the renderer's tab id). Fall back to minting if the id collides — a
-      // collision would alias two distinct PTYs to one tab id and silently
-      // corrupt agent-status routing. Hook attribution degrades for that
-      // single terminal because paneKey is already baked into PTY env, but
-      // the rest of the tab works normally. See docs/cli-terminal-hook-pane-key.md.
-      // Why: only honor a hint that's a non-empty trimmed string. The IPC
-      // boundary at useIpcEvents.ts spreads `id` whenever `tabId !== undefined`,
-      // so a stray `''` or whitespace-only value from a future producer would
-      // otherwise be persisted as a real tab id and break paneKey routing
-      // (`${tabId}:${leafId}` would inherit the bad tab segment).
+      // Why: honor a caller-supplied tab id but mint on collision — aliasing two PTYs to one id corrupts agent-status routing. See docs/cli-terminal-hook-pane-key.md.
+      // Why: only honor a non-empty trimmed hint; useIpcEvents spreads `id` whenever tabId !== undefined, so a stray '' would break paneKey routing.
       const trimmedHint = typeof options?.id === 'string' ? options.id.trim() : ''
       const hintedId =
         trimmedHint.length > 0 && isValidHostTerminalTabId(trimmedHint) ? trimmedHint : undefined
@@ -997,28 +912,22 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       const createdShellOverride = resolveCreatedTabShellOverride(
         shellOverride,
         s.settings?.terminalWindowsShell,
-        // Why: SSH PTYs ignore local Windows shell selection; persisting a
-        // local shell icon would mislabel a remote terminal.
+        // Why: SSH PTYs ignore local Windows shell selection; a local shell icon would mislabel a remote terminal.
         isRemoteWorktree,
         remoteConnectionId
           ? ((s.sshConnectionStates.get(remoteConnectionId)
               ?.remotePlatform as NodeJS.Platform | null) ?? null)
           : null,
-        // Why: WSL UNC worktrees are repo-scoped WSL environments. New default
-        // terminals should enter that distro even when the global Windows shell
-        // preference is PowerShell or cmd.exe.
+        // Why: new terminals enter the worktree's repo-scoped WSL distro even when the global Windows shell is PowerShell/cmd.exe.
         isWslWorktree,
         isRemoteWorktree ? undefined : getLocalProjectExecutionRuntimeContext(s, worktreeId)
       )
       tab = {
         id,
-        // Why: CLI-created background sessions already own a PTY; revealing
-        // one later should attach the pane instead of spawning a duplicate.
+        // Why: CLI-created background sessions already own a PTY, so reveal attaches instead of spawning a duplicate.
         ptyId: options?.initialPtyId ?? null,
         worktreeId,
-        // Why: users expect terminal labels to reflect the currently open set,
-        // not a monotonic creation counter. Reusing the lowest free ordinal
-        // keeps a lone fresh terminal at "Terminal 1" after older tabs close.
+        // Why: reuse the lowest free ordinal so a fresh terminal stays "Terminal 1" after older tabs close, not a monotonic counter.
         title: defaultTitle,
         defaultTitle,
         ...(quickCommandLabel ? { quickCommandLabel } : {}),
@@ -1029,13 +938,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         ...(createdShellOverride !== undefined ? { shellOverride: createdShellOverride } : {}),
         ...(startupCwd && startupCwd.length > 0 ? { startupCwd } : {}),
         ...(options?.launchAgent ? { launchAgent: options.launchAgent } : {}),
-        // Why: when Terminal.tsx's activation fallback auto-creates a tab for a
-        // first-visit worktree, the resulting PTY spawn is caused by the user
-        // clicking the worktree, not by work happening in it. Tagging the tab
-        // lets updateTabPtyId suppress the activity bump and sortEpoch bump.
-        // Without this, clicking a never-visited worktree would stamp
-        // lastActivityAt and reorder Recent/Smart on click — same bug class as
-        // the generation-bump → remount path, different code path.
+        // Why: mark click-caused (not work-caused) spawns so updateTabPtyId skips the activity/sortEpoch bump that would reorder Recent/Smart on click.
         ...(options?.pendingActivationSpawn ? { pendingActivationSpawn: true } : {})
       }
       const validTargetGroupId =
@@ -1065,8 +968,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         orphanTerminalIds.size === 0
           ? groupsForWorktree
           : groupsForWorktree.map((entry) => {
-              // Why: orphan cleanup must repair every group before adding the
-              // new tab, or inactive/background creation can revive stale focus.
+              // Why: repair every group before adding the new tab, or inactive/background creation can revive stale focus.
               const tabOrder = dedupeTabOrder(entry.tabOrder).filter(
                 (tabId) => !orphanTerminalIds.has(tabId)
               )
@@ -1104,8 +1006,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         color: tab.color,
         sortOrder: cleanedGroupOrder.length,
         createdAt: tab.createdAt,
-        // Why: agent launches open in chat when the opt-in default is on;
-        // omitted for all other tabs so they keep the implicit 'terminal' mode.
+        // Why: omit for non-agent tabs so they keep the implicit 'terminal' view mode.
         ...(options?.viewMode ? { viewMode: options.viewMode } : {})
       }
       const nextGroupOrder = dedupeTabOrder([...cleanedGroupOrder, unifiedTab.id])
@@ -1126,9 +1027,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           ...orphanCleanupPatch.tabsByWorktree,
           [worktreeId]: [...existing, tab]
         },
-        // Why: task-page launch queues startup/setup work before React mounts
-        // the terminal. Publishing the unified tab atomically with the runtime
-        // tab prevents a transient legacy mount from racing the split host.
+        // Why: publish the unified tab atomically with the runtime tab so a transient legacy mount can't race the split host.
         unifiedTabsByWorktree: {
           ...s.unifiedTabsByWorktree,
           [worktreeId]: existingTerminalTab
@@ -1211,8 +1110,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         base.push(id)
       }
     }
-    // Why: Cmd+J uses the same creation path as the titlebar button, so a new
-    // terminal should append after mixed editor/browser tabs rather than jump first.
+    // Why: Cmd+J shares the titlebar-button creation path, so append the new terminal after mixed editor/browser tabs, not first.
     get().setTabBarOrder(worktreeId, [...base.filter((id) => id !== terminal.id), terminal.id])
     focusTerminalTabSurface(terminal.id)
   },
@@ -1226,8 +1124,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         : buildTerminalTabRetirementPlan(get(), tabId)
     let closingWorktreeId: string | null = null
 
-    // Why: a parked tab has no mounted TerminalPane cleanup. Retirement must
-    // synchronously revoke its observer/candidate state before provider exit races.
+    // Why: a parked tab has no mounted TerminalPane cleanup, so revoke its observer/candidate state before provider exit races.
     retireParkedTerminalTab(tabId)
     if (retiresSession) {
       const fallbackRuntimeEnvironmentId = retirementPlan.worktreeId
@@ -1255,8 +1152,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           count: retirementPlan.unroutablePtyIds.length
         })
       }
-      // Why: close remains synchronous and idempotent; provider failures must
-      // not reject into the UI or prevent renderer ownership from being revoked.
+      // Why: keep close synchronous and idempotent — provider failures must not reject into the UI or block ownership revocation.
       void Promise.allSettled(retirementTasks).then((results) => {
         const localOrSshFailures = results
           .slice(0, localOrSshTaskCount)
@@ -1283,8 +1179,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         const closing = before.find((t) => t.id === tabId)
         if (closing) {
           closingWorktreeId = wId
-          // Why: capture the first-matched tab's snapshot for the Cmd+Shift+T
-          // reopen stack (see capturedSnapshot below).
+          // Why: capture the first-matched tab's snapshot for the Cmd+Shift+T reopen stack (see capturedSnapshot below).
           if (!closedTab) {
             closedTab = closing
             closedWorktreeId = wId
@@ -1295,8 +1190,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           next[wId] = after
         }
       }
-      // Why: only explicit user closes feed the Cmd+Shift+T reopen stack.
-      // Cleanup and PTY-exit closes must not pollute user undo history.
+      // Why: only explicit user closes feed the Cmd+Shift+T reopen stack; cleanup/PTY-exit closes must not pollute undo history.
       const capturedSnapshot =
         closeReason === 'user' &&
         opts?.captureRecentlyClosed !== false &&
@@ -1325,10 +1219,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       delete nextPendingReconnectPtyIdByTabId[tabId]
       const nextRuntimePaneTitlesByTabId = { ...s.runtimePaneTitlesByTabId }
       delete nextRuntimePaneTitlesByTabId[tabId]
-      // Why: preserve the unreadTerminalTabs reference when the closing tab had
-      // no unread flag — avoids a no-op top-level state allocation that would
-      // force re-evaluation of full-state selectors on unrelated closeTab calls.
-      // Mirrors the sibling pattern in tabs.ts (focusGroup, reconcileWorktreeTabModel).
+      // Why: keep the same reference when the closing tab had no unread flag, so unrelated closes don't force full-state selector re-eval.
       let nextUnreadTerminalTabs = s.unreadTerminalTabs
       if (s.unreadTerminalTabs[tabId]) {
         nextUnreadTerminalTabs = { ...s.unreadTerminalTabs }
@@ -1374,16 +1265,13 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       const nextPendingIssueCommandSplitByTabId = { ...s.pendingIssueCommandSplitByTabId }
       delete nextPendingIssueCommandSplitByTabId[tabId]
       const nextCacheTimer = { ...s.cacheTimerByKey }
-      // Why: cache timer keys are `${tabId}:${leafId}` composites. Remove all
-      // entries for the closing tab, regardless of how many panes it had.
+      // Why: cache timer keys are `${tabId}:${leafId}` composites; remove all entries for the closing tab.
       for (const key of Object.keys(nextCacheTimer)) {
         if (key.startsWith(`${tabId}:`)) {
           delete nextCacheTimer[key]
         }
       }
-      // Why: keep activeTabIdByWorktree in sync when a tab is closed in a
-      // background worktree. Without this, the remembered tab becomes stale
-      // and restoring it on worktree switch falls back to tabs[0].
+      // Why: keep activeTabIdByWorktree in sync when closing a background-worktree tab, else the stale remembered tab falls back to tabs[0] on switch.
       const nextActiveTabIdByWorktree = { ...s.activeTabIdByWorktree }
       for (const [wId, tabs] of Object.entries(next)) {
         if (nextActiveTabIdByWorktree[wId] === tabId) {
@@ -1391,8 +1279,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         }
       }
 
-      // Why: keep tabBarOrderByWorktree in sync so stale terminal IDs don't
-      // linger and cause position shifts on subsequent tab operations.
+      // Why: keep tabBarOrderByWorktree in sync so stale terminal IDs don't linger and shift positions on later tab operations.
       const nextTabBarOrderByWorktree: Record<string, string[]> = {
         ...s.tabBarOrderByWorktree
       }
@@ -1403,9 +1290,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         }
       }
 
-      // Why: if the tab had a ptyId with unconsumed snapshot or cold restore
-      // data (e.g., tab closed before TerminalPane mounted), clean it up to
-      // prevent unbounded store growth across restarts.
+      // Why: clean up unconsumed snapshot/cold-restore data (e.g. tab closed before TerminalPane mounted) to prevent unbounded store growth across restarts.
       let nextSnapshots = s.pendingSnapshotByPtyId
       let nextColdRestores = s.pendingColdRestoreByPtyId
       const closingPtyIds = new Set([
@@ -1437,9 +1322,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         ...(nextSleepingAgentSessionsByPaneKey !== s.sleepingAgentSessionsByPaneKey
           ? { sleepingAgentSessionsByPaneKey: nextSleepingAgentSessionsByPaneKey }
           : {}),
-        // Why: skip writing unreadTerminalTabs when the reference is unchanged —
-        // avoids a no-op top-level state allocation that would force re-evaluation
-        // of full-state selectors. Mirrors the sibling pattern in tabs.ts.
+        // Why: skip writing unreadTerminalTabs when unchanged to avoid a no-op state allocation that re-evaluates full-state selectors. Mirrors tabs.ts.
         ...(nextUnreadTerminalTabs !== s.unreadTerminalTabs
           ? { unreadTerminalTabs: nextUnreadTerminalTabs }
           : {}),
@@ -1479,28 +1362,17 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           : {})
       }
     })
-    // Why: sweep live AND retained agent-status entries for this tab — closing
-    // the tab is the user telling us "I'm done with this session", so any
-    // completion snapshots it left behind (in the inline agents list) must go
-    // too. Use dropAgentStatusByTabPrefix (not removeAgentStatusByTabPrefix)
-    // so retention suppressors are planted: a live→gone transition inside the
-    // same frame as the tab close cannot re-snapshot a row we just dropped.
-    // Why: Pi can leave a completed row attributed to the worktree but keyed
-    // under an already-missing tab id; pass the worktree to sweep only that
-    // completed orphan while preserving active pre-render child rows.
+    // Why: closing a tab sweeps live and retained agent-status for it; use dropAgentStatusByTabPrefix so retention suppressors block a same-frame live→gone re-snapshot.
+    // Why: Pi can leave a completed row keyed under an already-missing tab id; pass the worktree to sweep that orphan while preserving active pre-render child rows.
     get().dropAgentStatusByTabPrefix(
       tabId,
       closingWorktreeId ? { worktreeId: closingWorktreeId } : undefined
     )
-    // Why: retired pane keys never recur, so stranded foreground entries would
-    // accumulate for the renderer's whole lifetime.
+    // Why: retired pane keys never recur, so stranded foreground entries would accumulate for the renderer's whole lifetime.
     get().clearPaneForegroundAgentByTabPrefix(tabId)
-    // Why: closing a tab permanently retires every pane under it (a reopen mints
-    // a fresh leafId at epoch 0), so drop the panes' hibernation output epochs to
-    // keep that module-level map from growing for the renderer's whole lifetime.
+    // Why: closing a tab permanently retires its panes (reopen mints a fresh leafId), so drop hibernation output epochs to keep the module map from growing forever.
     forgetAgentHibernationTabOutput(tabId)
-    // Why: same rationale for the tab's foreground last-seen timestamp and any
-    // consumed agent-startup delivery guards — retired tab ids never recur.
+    // Why: same rationale — retired tab ids never recur, so drop the foreground last-seen and consumed agent-startup delivery guards.
     forgetForegroundTerminalTabs([tabId])
     forgetAgentStartupDeliveriesForTabs([tabId])
     for (const tabs of Object.values(get().unifiedTabsByWorktree)) {
@@ -1564,15 +1436,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
 
   setActiveTab: (tabId) => {
     set((s) => {
-      // Why: focusing a terminal tab clears the tab-level bell — the user has
-      // moved to this tab.
-      //
-      // Why (activeWorktree guard below): only clear when the tab belongs to
-      // the active worktree. If setActiveTab is invoked with a tab from a
-      // background worktree (e.g., during worktree activation, or the
-      // "jump to agent" path), the tab is not yet visible and clearing would
-      // silently swallow the signal. Mirrors the guard in activateTab and
-      // focusGroup.
+      // Why: focusing a terminal tab clears its bell, but only for the active worktree — clearing a not-yet-visible background tab (worktree activation / jump-to-agent) would swallow the signal.
       let tabOwnerWorktreeId: string | null = null
       for (const [wId, tabs] of Object.entries(s.tabsByWorktree)) {
         if (tabs.some((t) => t.id === tabId)) {
@@ -1588,15 +1452,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
               return copy
             })()
           : s.unreadTerminalTabs
-      // Why: only write the global activeTabId when the tab belongs to the
-      // currently active worktree. markTerminalTabUnread treats activeTabId
-      // as "the tab the user is looking at" and suppresses BELs on it; if we
-      // pinned activeTabId to a background-worktree tab (e.g. the
-      // jump-to-agent path calls setActiveTab before switching worktrees),
-      // a subsequent BEL on that tab would be silently swallowed. The
-      // per-worktree map still gets updated so the background worktree
-      // remembers its last-active tab for later restoration. Mirrors the
-      // pattern already used above for nextUnreadTerminalTabs.
+      // Why: only pin global activeTabId to active-worktree tabs — markTerminalTabUnread treats it as "the visible tab" and would swallow BELs on a background tab (e.g. jump-to-agent).
       const isActiveWorktreeTab = tabOwnerWorktreeId === s.activeWorktreeId
       return {
         activeTabId: isActiveWorktreeTab ? tabId : s.activeTabId,
@@ -1625,11 +1481,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
 
   updateTabTitle: (tabId, title) => {
     set((s) => {
-      // Why: locate the owning worktree and mutate only that entry in
-      // tabsByWorktree. Rebuilding every worktree's tab array (even when
-      // unchanged) would break shallow-equality checks in unrelated
-      // selectors and trigger spurious re-renders across background
-      // worktrees on every OSC title frame.
+      // Why: mutate only the owning worktree's tab array — rebuilding all of them would break shallow-equality selectors and spuriously re-render background worktrees on every OSC title frame.
       const ownerWorktreeId = getTerminalTabOwnerWorktreeId(s.tabsByWorktree, tabId)
       if (!ownerWorktreeId) {
         return s
@@ -1676,8 +1528,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         tab.id === tabId
           ? {
               ...tab,
-              // Why: PTYs can briefly emit an empty title while an agent exits.
-              // Keep the stable fallback label instead of rendering a blank tab.
+              // Why: PTYs can briefly emit an empty title as an agent exits; keep the stable fallback instead of a blank tab.
               title: nextTitle,
               defaultTitle:
                 tab.defaultTitle ??
@@ -1688,13 +1539,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       )
       scheduleRuntimeGraphSync()
       const nextTabsByWorktree = { ...s.tabsByWorktree, [ownerWorktreeId]: ownerTabs }
-      // Agent status is derived from terminal titles and affects sort scoring,
-      // so a title change is a meaningful event that should allow re-sort —
-      // but only for background worktrees. Title changes in the active
-      // worktree are side-effects of PTY reconnection during worktree
-      // activation (generation bump → TerminalPane remount → new shell →
-      // title update). Bumping sortEpoch here would reorder the sidebar
-      // on click — the exact bug PR #209 intended to fix.
+      // Why: title changes affect agent-status sort scoring, so re-sort — but only background worktrees; active-worktree changes are click-driven PTY-remount side-effects (bug PR #209).
       const isActive = ownerWorktreeId === s.activeWorktreeId
       const nextState: Partial<AppState> = isActive
         ? { tabsByWorktree: nextTabsByWorktree }
@@ -1710,8 +1555,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
   },
 
   setGeneratedTabTitleFromAgentPrompt: (paneKey, prompt, options) => {
-    // Why: setAgentStatus is high-frequency; skip derive/set unless the feature
-    // is on and this tab still needs a (re)generated title.
+    // Why: setAgentStatus is high-frequency; skip derive/set unless the feature is on and this tab still needs a (re)generated title.
     if (get().settings?.tabAutoGenerateTitle !== true) {
       return
     }
@@ -1817,21 +1661,10 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       if (prevTitle && isDecorativeAgentTitleFrameChange(prevTitle, title)) {
         return s
       }
-      // Why: smart sort's title-heuristic fallback (Edge case 9) reads
-      // runtimePaneTitlesByTabId. A hookless agent transitioning from
-      // 'working' → 'permission' via a title change must trigger a re-sort,
-      // otherwise the worktree stays in its old class until some unrelated
-      // event fires. Bumping only on classification change keeps incidental
-      // title noise (spinner frame, prompt suffix) from churning the sidebar.
+      // Why: smart sort's title-heuristic fallback (Edge case 9) reads this map; a hookless 'working' → 'permission' title change must re-sort, but only on classification change.
       const classificationChanged =
         classifyTitleActivity(prevTitle ?? '') !== classifyTitleActivity(title)
-      // Why: locate the owning worktree so we can suppress the sortEpoch
-      // bump when the changing pane lives in the active worktree. Title
-      // changes there are side-effects of the user's click (PTY remount on
-      // worktree activation emits a fresh shell prompt, then the agent
-      // re-emits its working title) — bumping would re-rank the sidebar on
-      // click, the exact bug PR #209 fixed for updateTabTitle. If no owner
-      // is found the pane is orphaned; skip the bump as unsafe.
+      // Why: suppress the sortEpoch bump when the pane lives in the active worktree — its title change is a click side-effect (PTY remount), the bug PR #209 fixed; skip if orphaned.
       const ownerWorktreeId = classificationChanged
         ? getTerminalTabOwnerWorktreeId(s.tabsByWorktree, tabId)
         : null
@@ -1864,14 +1697,9 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         delete next[tabId]
       }
 
-      // Why: clearing a 'working'/'permission'-classified title back to none
-      // changes the title-heuristic verdict for that pane, so the smart sort
-      // needs a re-sort. See setRuntimePaneTitle for the rationale.
+      // Why: clearing a classified title changes the smart-sort title-heuristic verdict, so it needs a re-sort. See setRuntimePaneTitle.
       const hadClassification = classifyTitleActivity(prevTitle ?? '') !== null
-      // Why: same active-worktree gate as setRuntimePaneTitle — clears that
-      // fire as a side-effect of a click-driven PTY teardown in the active
-      // worktree must not re-rank the sidebar. Skip bumping when no owner is
-      // found (orphaned pane) for the same safety reason.
+      // Why: same active-worktree gate as setRuntimePaneTitle — click-driven teardown clears must not re-rank the sidebar; skip when owner is missing (orphaned).
       const ownerWorktreeId = hadClassification
         ? getTerminalTabOwnerWorktreeId(s.tabsByWorktree, tabId)
         : null
@@ -1892,12 +1720,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
     if (!ownerTab) {
       return
     }
-    // Why: terminal attention must stay visible until interaction ("show
-    // until interact"). A signal on the focused tab still sets the indicator;
-    // real user interaction with the pane dismisses it. Keystroke/pointerdown
-    // routes through clearTerminalTabUnread (see pty-connection.ts and
-    // TerminalPane.tsx); tab/group activation clears unreadTerminalTabs
-    // directly in activateTab/focusGroup as a pre-existing side-effect.
+    // Why: terminal attention persists until real interaction ("show until interact"); keystroke/pointerdown clears via clearTerminalTabUnread, tab/group activation clears directly.
     set((s) => {
       if (s.unreadTerminalTabs[tabId]) {
         return s
@@ -1986,8 +1809,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       .find((entry) => entry.contentType === 'terminal' && entry.entityId === tabId)
     if (item) {
       get().setUnifiedTabColor(item.id, color)
-      // Why: tab color is host-authoritative for remote-server tabs; mirror it
-      // so it persists instead of reverting on the next snapshot.
+      // Why: tab color is host-authoritative for remote-server tabs; mirror it so it persists instead of reverting on the next snapshot.
       const state = get()
       const owningWorktreeId = Object.keys(state.unifiedTabsByWorktree).find((wId) =>
         (state.unifiedTabsByWorktree[wId] ?? []).some((entry) => entry.id === item.id)
@@ -2001,8 +1823,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
   },
 
   updateTabPtyId: (tabId, ptyId, replacedPtyId) => {
-    // Why: async spawn owners must perform provider teardown themselves, but
-    // this final guard prevents any late caller from recreating retired tab maps.
+    // Why: final guard preventing a late caller from recreating retired tab maps (async spawn owners still do their own provider teardown).
     if (!isTerminalTabPresent(get(), tabId)) {
       return
     }
@@ -2037,15 +1858,10 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         if (getPendingActivationSpawnCount(tab.pendingActivationSpawn) > 0) {
           wasActivationSpawn = true
         }
-        // Why: consume one pendingActivationSpawn unit here. Split layouts can
-        // remount several panes for one click, and each pane's activation-time
-        // PTY callback must be suppressed without hiding later real activity.
+        // Why: consume one pendingActivationSpawn unit — a split remounts several panes per click, each activation callback suppressed without hiding later real activity.
         const { pendingActivationSpawn: _unused, ...rest } = tab
         void _unused
-        // Why: tab.ptyId is the single-pane fallback used by legacy attach
-        // paths. In split panes, later pane spawns must not steal that
-        // primary binding from the original pane or remount/close flows can
-        // reattach the tab to the wrong PTY and appear to "reset" panes.
+        // Why: tab.ptyId is the single-pane fallback for legacy attach; later split-pane spawns must not steal it or remount/close reattaches the tab to the wrong PTY.
         const currentTabPtyId = tab.ptyId === replacementPtyId ? ptyId : tab.ptyId
         const nextTabPtyId = currentTabPtyId ?? nextPtyIds[0] ?? null
         const nextPendingActivationSpawn = consumePendingActivationSpawn(tab.pendingActivationSpawn)
@@ -2062,12 +1878,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         }
         break
       }
-      // Why: when a brand-new tab in the active worktree receives its first
-      // PTY, the live-tab signal (+12) flips on. Normally we bump sortEpoch
-      // here so the sort reflects the new signal immediately. Suppress the
-      // bump on activation-driven spawns because they are side-effects of the
-      // user clicking on a worktree, not real activity — otherwise clicking a
-      // dormant worktree would always trigger a re-sort.
+      // Why: a new active-worktree tab's first PTY flips the live-tab signal (+12), so bump sortEpoch — but suppress on activation spawns (click side-effect, not activity).
       const isFirstPty = existingPtyIds.length === 0
       const isActiveWorktree = worktreeId != null && s.activeWorktreeId === worktreeId
       const shouldBumpSortEpoch = isFirstPty && isActiveWorktree && !wasActivationSpawn
@@ -2082,8 +1893,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         delete nextSuppressedPtyExitIds[replacementPtyId]
       }
       if (shouldRetainSuppressedExit) {
-        // Why: explicit handle rotation preserves the same terminal lifecycle;
-        // an intentional exit racing the rotation must stay suppressed once.
+        // Why: handle rotation keeps the same terminal lifecycle; an intentional exit racing the rotation must stay suppressed once.
         nextSuppressedPtyExitIds[ptyId] = true
       }
       const hasReplacementPendingRestart = replacementPtyId
@@ -2141,11 +1951,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       }
     })
 
-    // Why: activation-driven spawns are caused by the user clicking a
-    // worktree, not by work happening in it. Skip both the lastActivityAt
-    // stamp and the sortEpoch bump so the sidebar does not reorder on click.
-    // Other spawn reasons (new tab, codex restart, reconnect) still flow
-    // through bumpWorktreeActivity as a normal activity signal.
+    // Why: activation spawns come from clicking a worktree, not work in it — skip the lastActivityAt stamp and sortEpoch bump; other spawn reasons still bump.
     if (worktreeId && !wasActivationSpawn && !isRemoteRuntimeMirror) {
       get().bumpWorktreeActivity(worktreeId)
     }
@@ -2173,10 +1979,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           isRemoteRuntimeMirror =
             existingPtyIds.length > 0 && existingPtyIds.every((id) => isRemoteRuntimePtyId(id))
         }
-        // Why: consume pendingActivationSpawn for real activation-time clears,
-        // but keep it when clearing a stale wake-hint id that was not live in
-        // ptyIdsByTabId. That path immediately falls back to a fresh spawn,
-        // and the spawn still needs the click-driven suppression.
+        // Why: consume pendingActivationSpawn on real activation clears, but keep it when clearing a stale wake-hint id — its fallback spawn still needs the suppression.
         const { pendingActivationSpawn: _unused, ...rest } = tab
         void _unused
         const nextTabPtyId = remainingPtyIds.at(-1) ?? null
@@ -2202,8 +2005,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       if (worktreeId) {
         nextPtyIdsByTabId[tabId] = remainingPtyIds
       } else {
-        // Why: repo purge can remove the owning tab before its asynchronous
-        // exit arrives. Do not resurrect an orphan PTY index for a retired tab.
+        // Why: repo purge can retire the owning tab before its async exit arrives; don't resurrect an orphan PTY index.
         delete nextPtyIdsByTabId[tabId]
       }
       const nextPendingCodexPaneRestartIds = { ...s.pendingCodexPaneRestartIds }
@@ -2217,11 +2019,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           delete nextCodexRestartNoticeByPtyId[currentPtyId]
         }
       }
-      // Why: when a specific ptyId is passed, the PTY actually exited (not
-      // just disconnected). Remove its lastKnown entry so session-save does
-      // not attempt to reattach a dead relay PTY on next restart. When no
-      // ptyId is passed (bulk clear on connection_lost), preserve lastKnown
-      // because the relay still has the PTY alive during its grace period.
+      // Why: a passed ptyId means the PTY actually exited — drop its lastKnown so restart won't reattach a dead relay; bulk clear (connection_lost) keeps it during relay grace.
       const nextLastKnownRelay = { ...s.lastKnownRelayPtyIdByTabId }
       if (ptyId && nextLastKnownRelay[tabId] === ptyId) {
         delete nextLastKnownRelay[tabId]
@@ -2236,9 +2034,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       }
     })
 
-    // Bump meaningful activity when a PTY exits, but skip if this exit
-    // was triggered by an intentional shutdown (suppressed exits) OR by a
-    // click-driven pane unmount (pendingActivationSpawn).
+    // Bump activity on PTY exit, but skip intentional shutdowns (suppressed exits) and click-driven pane unmounts (pendingActivationSpawn).
     if (
       worktreeId &&
       !wasActivationSpawn &&
@@ -2258,8 +2054,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
     const rendererShutdownPtyIds = [opts.ptyId]
     const state = get()
     const runtimeEnvironmentId = resolveTerminalStopRuntimeEnvironmentId(state, worktreeId)
-    // Why: pane transports emit renderer PTY ids, never raw exact-stop handles.
-    // Guard only the identity that can actually deliver an exit callback.
+    // Why: pane transports emit renderer PTY ids, not raw exact-stop handles; guard only the identity that can deliver an exit callback.
     const exitGuardPtyIds = [opts.ptyId]
     const tab = (state.tabsByWorktree[worktreeId] ?? []).find(
       (candidate) => candidate.id === opts.tabId
@@ -2292,9 +2087,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       paneKeys
     )
     if (!sleepingAgentSessionRecords[opts.paneKey]) {
-      // Why: killing the PTY without a persisted resume record strands the
-      // pane — nothing can ever wake it. Planner eligibility can go stale
-      // between ticks; abort this round instead of hibernating unrecoverably.
+      // Why: killing the PTY with no persisted resume record strands the pane unwakeable; abort instead of hibernating unrecoverably.
       throw new Error('agent_hibernation_capture_missing')
     }
 
@@ -2307,10 +2100,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       }
     }
 
-    // Why: the pane's exit handler consults sleepingAgentSessionsByPaneKey to
-    // tell a hibernation kill from other suppressed exits. pty:exit can reach
-    // the renderer before the kill promise resolves, so the record must be in
-    // the store BEFORE the kill is issued — and rolled back if the kill fails.
+    // Why: pty:exit can reach the renderer before the kill promise resolves, so the sleeping record must be in the store before the kill (and rolled back on failure).
     const sleepingRecordKeys = Object.keys(sleepingAgentSessionRecords)
     const replacedSleepingRecords: Record<string, (typeof sleepingAgentSessionRecords)[string]> = {}
     for (const key of sleepingRecordKeys) {
@@ -2395,8 +2185,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       }
       unregisterPtyDataHandlers(rendererShutdownPtyIds)
     } else if (!opts.ptyId.startsWith('remote:')) {
-      // Why: pty.kill can flush final data before exit; unregister first so
-      // pane hibernation cannot fire phantom notifications from stale handlers.
+      // Why: pty.kill can flush final data before exit; unregister first so stale handlers can't fire phantom notifications during hibernation.
       const handlerSnapshots = unregisterPtyDataHandlers(rendererShutdownPtyIds)
       try {
         await window.api.pty.kill(opts.ptyId, { keepHistory: true })
@@ -2493,8 +2282,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
     const rendererShutdownPtyIds = sortedUniquePtyIds(ptyIds)
     const expectedRuntimePtyIds = sortedUniquePtyIds(opts?.expectedRuntimePtyIds)
     const runtimeEnvironmentId = resolveTerminalStopRuntimeEnvironmentId(get(), worktreeId)
-    // Why: expectedRuntimePtyIds are raw RPC handles. Only renderer-bound ids
-    // can emit pane exit callbacks, so they are the complete guard identity set.
+    // Why: only renderer-bound ids emit pane exit callbacks, so they are the complete guard set (expectedRuntimePtyIds are raw RPC handles).
     const exitGuardPtyIds = rendererShutdownPtyIds
     const sleepingAgentSessionRecords = keepIdentifiers
       ? collectSleepingAgentSessionRecordsForWorktree(get(), worktreeId, {
@@ -2510,33 +2298,15 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         ? collectHibernatedCompletionEvidenceForWorktree(get(), worktreeId, opts?.sleepingPaneKeys)
         : []
 
-    // Why: the main process flushes any remaining batched PTY data before
-    // sending the exit event (pty.ts onExit handler). Without this, that
-    // final data burst flows through the still-registered ptyDataHandlers
-    // where bell detection and agent-status tracking can fire system
-    // notifications for a worktree that is already being torn down —
-    // the "phantom alerts" users see after shutting down worktrees.
-    // Removing the data handlers first ensures the final flush is a no-op.
+    // Why: main process flushes batched PTY data before exit; unregister handlers first so bell/agent-status can't fire "phantom alerts" for a tearing-down worktree.
     if (expectedRuntimePtyIds.length === 0) {
       unregisterPtyDataHandlers(rendererShutdownPtyIds)
-      // Why: parked-tab byte watchers observe the same flush through dispatcher
-      // sidecars, which the call above does not touch — dispose them now or a
-      // just-slept/deleted worktree still gets unread marks and delayed
-      // bell/completion OS notifications from its teardown bytes.
+      // Why: parked-tab byte watchers observe the same flush via dispatcher sidecars (untouched above); dispose now or teardown bytes fire stray unread/notifications.
       disposeParkedTerminalWatchersForPtyIds(rendererShutdownPtyIds)
     }
 
-    // Why (ordering invariant — DESIGN_DOC §3.3.c): on sleep, capture every
-    // pane's serializer buffer into terminalLayoutsByTabId[tab].buffersByLeafId
-    // BEFORE issuing pty.kill (panes unmount on PTY exit and their
-    // serializeAddons go with them) AND BEFORE the set() block below (the
-    // capture writes through to the store via its own setTabLayout call; any
-    // subsequent set must use a functional updater spreading
-    // s.terminalLayoutsByTabId, not a captured snapshot). For SSH this is
-    // load-bearing — the relay drops the remote PTY on kill so there's no
-    // on-disk history dir to cold-restore from. Local daemon scrollback is
-    // intentionally skipped because the session payload prunes it and daemon
-    // history/checkpoints are authoritative.
+    // Why (ordering invariant, DESIGN_DOC §3.3.c): capture serializer buffers before pty.kill (panes unmount on exit); SSH-critical since the relay drops remote history on kill.
+    // Why: capture() writes through the store via setTabLayout, so the set() below must spread s.terminalLayoutsByTabId in a functional updater, not a captured snapshot, or it clobbers the capture.
     if (keepIdentifiers) {
       for (const tab of tabs) {
         const capture = shutdownBufferCaptures.get(tab.id)
@@ -2639,11 +2409,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         ...s.suppressedPtyExitIds,
         ...Object.fromEntries(exitGuardPtyIds.map((ptyId) => [ptyId, true] as const))
       }
-      // Why: pendingCodexPaneRestartIds is keyed by ptyId — under sleep we
-      // preserve it so a mid-restart marker survives wake against the same
-      // identifier. codexRestartNoticeByPtyId is also keyed by the now-stale
-      // ptyId; on wake the post-spawn ptyId may differ, so the notice can't
-      // be carried forward and is cleared in both cases.
+      // Why: keep pendingCodexPaneRestartIds (same ptyId survives sleep→wake), but clear codexRestartNoticeByPtyId since wake's post-spawn ptyId may differ.
       const nextPendingCodexPaneRestartIds = keepIdentifiers
         ? s.pendingCodexPaneRestartIds
         : { ...s.pendingCodexPaneRestartIds }
@@ -2654,30 +2420,13 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         }
         delete nextCodexRestartNoticeByPtyId[ptyId]
       }
-      // Why: setup-split and issue-command-split are transient one-shots that
-      // drive new-tab UX. They are not sleep-recovery state; clear in both
-      // cases.
+      // Why: setup-split and issue-command-split are transient new-tab one-shots, not sleep-recovery state; clear in both cases.
       const nextPendingSetupSplitByTabId = { ...s.pendingSetupSplitByTabId }
       const nextPendingIssueCommandSplitByTabId = { ...s.pendingIssueCommandSplitByTabId }
-      // Why: under remove-worktree (default), layout snapshots carry
-      // `ptyIdsByLeafId` referencing now-dead PTY IDs; if we leave them, the
-      // next remount takes the reattach branch in connectPanePty and produces
-      // a visible but non-interactive "zombie" pane. Under sleep
-      // (keepIdentifiers), we preserve `ptyIdsByLeafId` precisely so wake can
-      // pass them as args.sessionId to pty.spawn and reattach to the daemon
-      // history dir (or, on SSH, restore scrollback from buffersByLeafId
-      // captured above).
+      // Why: remove-worktree must clear ptyIdsByLeafId (dead IDs → zombie reattach pane on remount); sleep preserves it so wake can reattach via pty.spawn.
       const nextTerminalLayoutsByTabId = { ...s.terminalLayoutsByTabId }
-      // Why: unread dots survive across worktree switches by design, but a
-      // full shutdown tears down the PTYs behind them. Even under sleep, the
-      // PTYs are killed, so unread state pointing at dead ptyIds is stale —
-      // clear in both cases. (Carrying the dot across sleep would also be
-      // surprising and inconsistent with how it behaves on tab close.)
-      // Why: preserve the unreadTerminalTabs reference when none of the
-      // shutting-down tabs had an unread flag — avoids a no-op top-level
-      // state allocation that would force re-evaluation of full-state
-      // selectors on unrelated shutdown calls. Mirrors the sibling pattern
-      // in tabs.ts.
+      // Why: unread dots survive worktree switches, but shutdown/sleep both kill the PTYs behind them, so dead-ptyId unread state is stale — clear in both.
+      // Why: preserve the unreadTerminalTabs reference when no shutting-down tab was unread, avoiding a no-op state allocation that re-evaluates selectors.
       let nextUnreadTerminalTabs = s.unreadTerminalTabs
       let nextUnreadTerminalPanes = s.unreadTerminalPanes
       let nextUnreadAgentCompletionPanes = s.unreadAgentCompletionPanes
@@ -2729,11 +2478,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         }
       }
 
-      // Why: under remove-worktree, intentional shutdown kills the relay PTY
-      // and persisting a dead session ID would cause next-restart reattach to
-      // fail. Under sleep, wake re-spawns over the relay against this exact
-      // session ID — preserving it is what lets the wake-side wiring stay
-      // consistent.
+      // Why: remove-worktree kills the relay PTY, so a persisted session ID would fail reattach; sleep preserves it for wake's re-spawn over the relay.
       const nextLastKnownRelay = keepIdentifiers
         ? s.lastKnownRelayPtyIdByTabId
         : { ...s.lastKnownRelayPtyIdByTabId }
@@ -2754,9 +2499,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         pendingSetupSplitByTabId: nextPendingSetupSplitByTabId,
         pendingIssueCommandSplitByTabId: nextPendingIssueCommandSplitByTabId,
         terminalLayoutsByTabId: nextTerminalLayoutsByTabId,
-        // Why: skip writing unreadTerminalTabs when the reference is unchanged —
-        // avoids a no-op top-level state allocation that would force re-evaluation
-        // of full-state selectors. Mirrors the sibling pattern in tabs.ts.
+        // Why: skip writing unreadTerminalTabs when unchanged to avoid a no-op state allocation that re-evaluates full-state selectors. Mirrors tabs.ts.
         ...(nextUnreadTerminalTabs !== s.unreadTerminalTabs
           ? { unreadTerminalTabs: nextUnreadTerminalTabs }
           : {}),
@@ -2793,8 +2536,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       get().clearSleepingAgentSessionsByWorktree(worktreeId)
     }
 
-    // Why: only automatic completed-agent sleep keeps passive completion
-    // evidence; manual sleep/remove still fold the entire worktree surface.
+    // Why: only automatic completed-agent sleep keeps passive completion evidence; manual sleep/remove fold the whole worktree surface.
     get().dropAgentStatusByWorktree(worktreeId, {
       shutdownReason,
       sleepingPaneKeys: opts?.sleepingPaneKeys,
@@ -2879,11 +2621,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         const existing = next[notice.ptyId]
         const previousAccountLabel = existing?.previousAccountLabel ?? notice.previousAccountLabel
 
-        // Why: a live Codex pane stays on the account it originally launched
-        // with until that pane actually restarts. Repeated account switches
-        // must preserve that original pane account; otherwise A -> B -> A
-        // keeps showing a stale restart notice even though the pane never left
-        // account A and no longer needs a restart.
+        // Why: a live Codex pane keeps its original launch account until it actually restarts, so A -> B -> A must not leave a stale restart notice.
         if (previousAccountLabel === notice.nextAccountLabel) {
           delete next[notice.ptyId]
           delete nextPendingCodexPaneRestartIds[notice.ptyId]
@@ -2979,8 +2717,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         nextLastKnownRelayPtyIdByTabId[targetTabId] = detachedPtyId
       }
 
-      // Why: pane-to-tab detach moves a live PTY without spawning or exiting,
-      // so transfer its safe pane-owned identity without activity bumps.
+      // Why: pane-to-tab detach moves a live PTY without spawning or exiting, so transfer identity without activity bumps.
       const sourceTabsByWorktree = withTerminalTabPtyId(
         s.tabsByWorktree,
         sourceTabId,
@@ -2996,8 +2733,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         ...(nextTabsByWorktree !== s.tabsByWorktree ? { tabsByWorktree: nextTabsByWorktree } : {})
       }
     })
-    // Why: detach keeps the process and its immutable physical pane key alive;
-    // move resume/status authority to the new surface before the source can close.
+    // Why: detach keeps the process and its pane key alive, so move resume/status authority to the new surface before the source closes.
     get().transferAgentPaneAuthority({
       fromPaneKey: sourcePaneKey,
       toPaneKey: targetPaneKey,
@@ -3006,8 +2742,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
   },
 
   queueTabStartupCommand: (tabId, startup) => {
-    // Why: launchToken is only meaningful for tracked launch-config reuse;
-    // plain startup commands must not mint or carry a synthetic token.
+    // Why: launchToken is only meaningful for tracked launch-config reuse; plain startup commands must not mint a synthetic token.
     const launchToken = startup.launchConfig
       ? (startup.launchToken ?? createBrowserUuid())
       : undefined
@@ -3156,9 +2891,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           .filter(([, detected]) => detected.authoritative)
           .map(([repoId]) => repoId)
       )
-      // Why: the Floating Workspace is intentionally not a repo worktree, but
-      // its tabs still use the normal terminal session pipeline so daemon PTYs
-      // can survive app restart just like workspace terminals.
+      // Why: the Floating Workspace isn't a repo worktree, but its tabs use the normal session pipeline so daemon PTYs survive app restart.
       validWorktreeIds.add(FLOATING_TERMINAL_WORKTREE_ID)
       for (const workspace of s.folderWorkspaces) {
         validWorktreeIds.add(folderWorkspaceKey(workspace.id))
@@ -3171,8 +2904,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         }
         if (!validWorktreeIds.has(worktreeId)) {
           const repoId = getRepoIdFromWorktreeId(worktreeId)
-          // Why (#1158): an empty/missing list can mean degraded hydration; a
-          // non-empty repo list is authoritative for deleted-worktree cleanup.
+          // Why (#1158): an empty/missing list can mean degraded hydration; a non-empty repo list is authoritative for deleted-worktree cleanup.
           if (
             knownRepoIds.has(repoId) &&
             !repoIdsWithLoadedWorktrees.has(repoId) &&
@@ -3182,18 +2914,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           }
         }
       }
-      // Why pendingActivationSpawn on hydrated tabs: when a worktree restored
-      // from the previous session is mounted for the first time this session
-      // (either because it's the restored activeWorktreeId, or because the
-      // user clicks it), TerminalPane's connectPanePty fires — either
-      // reattaching to the daemon/relay session or spawning fresh. Both call
-      // updateTabPtyId, which would otherwise bump lastActivityAt and make
-      // the worktree bounce to the top of Recent ~5 seconds later when an
-      // unrelated event triggers a re-sort. Tagging at hydration covers the
-      // restored-active worktree (which never goes through setActiveWorktree
-      // again) and any other restored worktrees the user clicks later. The
-      // tag is consumed on the first updateTabPtyId/clearTabPtyId per tab,
-      // so subsequent legitimate events (codex restart, new pane) still bump.
+      // Why pendingActivationSpawn: a restored worktree's first mount calls updateTabPtyId, which would bump lastActivityAt and bounce it to the top of Recent; the tag (consumed on the first pty update) suppresses that so only real activity bumps.
       const tabsByWorktree: Record<string, TerminalTab[]> = Object.fromEntries(
         Object.entries(session.tabsByWorktree)
           .filter(([worktreeId]) => validWorktreeIds.has(worktreeId))
@@ -3207,8 +2928,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
               worktreeId,
               [...tabs]
                 .filter((tab) => {
-                  // Why: old web-client mirrors could persist host surface ids
-                  // with "::"; makePaneKey reserves ":" as its separator.
+                  // Why: old web-client mirrors could persist host surface ids with "::"; makePaneKey reserves ":" as its separator.
                   return isValidTerminalTabId(tab.id)
                 })
                 .sort((a, b) => a.sortOrder - b.sortOrder || a.createdAt - b.createdAt)
@@ -3249,9 +2969,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         if (session.activeWorktreeId && validWorktreeIds.has(session.activeWorktreeId)) {
           return session.activeWorktreeId
         }
-        // Why: a workspace with no terminal tabs is still a valid workspace.
-        // Falling back from the active repo prevents the blank landing screen
-        // when session tabs were pruned or never created.
+        // Why: a workspace with no tabs is still valid; fall back from the active repo to avoid a blank landing screen when tabs were pruned or never created.
         return fallbackActiveWorktreeId
       })()
       const activeWorkspaceKey: WorkspaceKey | null =
@@ -3270,13 +2988,8 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           ? session.activeRepoId
           : null
 
-      // Why: workspaceSessionReady stays false here. It is set to true in
-      // reconnectPersistedTerminals() after all eager PTY spawns complete.
-      // This prevents TerminalPane from mounting and spawning duplicate PTYs
-      // before the reconnect phase has set ptyId on each tab.
-      // Why: match the pre-idle-runtime-optimization startup contract.
-      // activeWorktreeIdsOnShutdown is authoritative when present; persisted
-      // tab/layout PTY IDs are wake hints, not a broader active-workspace list.
+      // Why: workspaceSessionReady stays false here; reconnectPersistedTerminals sets it true after eager spawns so TerminalPane can't mount and spawn duplicate PTYs first.
+      // Why: activeWorktreeIdsOnShutdown is authoritative when present; persisted tab/layout PTY IDs are only wake hints, not a full active-workspace list.
       const shutdownIds =
         session.activeWorktreeIdsOnShutdown ??
         Object.entries(session.tabsByWorktree)
@@ -3284,13 +2997,8 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           .map(([wId]) => wId)
       const pendingReconnectWorktreeIds = shutdownIds.filter((id) => validWorktreeIds.has(id))
 
-      // Why: capture which specific tabs had live PTYs per worktree from the
-      // raw session data BEFORE clearTransientTerminalState nulled the ptyIds.
-      // This ensures reconnectPersistedTerminals binds PTYs to the correct
-      // tabs, not just tabs[0], which matters for multi-tab worktrees.
-      // Also include tabs whose relay session IDs were preserved in
-      // remoteSessionIdsByTabId — those tabs were disconnected before shutdown
-      // (ptyId was null) but the relay still has their PTY alive.
+      // Why: record which tabs had live PTYs from raw session data before clearTransientTerminalState nulls ptyIds, so reconnect binds the right tabs in multi-tab worktrees (not just tabs[0]).
+      // Also include tabs whose relay session id survived in remoteSessionIdsByTabId (ptyId was null but the relay PTY is alive).
       const remoteSessionIds = session.remoteSessionIdsByTabId ?? {}
       const pendingReconnectTabByWorktree: Record<string, string[]> = {}
       for (const worktreeId of pendingReconnectWorktreeIds) {
@@ -3303,9 +3011,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         }
       }
 
-      // Why: preserve the previous session's ptyId for each tab so that
-      // reconnectPersistedTerminals can pass it as sessionId to the daemon's
-      // createOrAttach RPC, triggering reattach instead of a fresh spawn.
+      // Why: preserve each tab's prior ptyId so reconnect passes it as sessionId to the daemon's createOrAttach, triggering reattach instead of a fresh spawn.
       const pendingReconnectPtyIdByTabId: Record<string, string> = {}
       for (const worktreeId of pendingReconnectWorktreeIds) {
         const worktree = Object.values(runtimeSessionPlaceholders.worktreesByRepo)
@@ -3325,19 +3031,14 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         }
       }
 
-      // Why: remote PTY reattach uses the relay's pty.attach RPC, not the
-      // local terminal daemon. The loop above correctly skips SSH repos
-      // (connectionId check), so there is no overlap.
+      // Why: remote PTY reattach uses the relay's pty.attach RPC, not the local daemon; the loop above skips SSH repos, so no overlap.
       for (const [tabId, sessionId] of Object.entries(remoteSessionIds)) {
         if (validTabIds.has(tabId)) {
           pendingReconnectPtyIdByTabId[tabId] = sessionId
         }
       }
 
-      // Why: restore per-worktree active terminal tab from session.
-      // If the session has the map, validate that each tab ID still exists.
-      // Otherwise, derive it: the active worktree gets activeTabId, others
-      // default to their first tab.
+      // Restore per-worktree active tab; validate ids when the map exists, else derive for legacy sessions.
       let activeTabIdByWorktree: Record<string, string | null> = {}
       if (session.activeTabIdByWorktree) {
         for (const [wId, tabId] of Object.entries(session.activeTabIdByWorktree)) {
@@ -3357,14 +3058,8 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         }
       }
 
-      // Why: SSH worktrees are not persisted in worktreesByRepo (they're
-      // discovered at runtime via the relay). On restart, worktreesByRepo for
-      // SSH repos is empty, so the sidebar can't render them. Synthesize
-      // placeholder entries from the session's tabsByWorktree so the sidebar
-      // shows them immediately. The placeholders will be replaced with full
-      // data once SSH reconnects and fetchWorktrees runs.
-      // Why: only SSH needs placeholders; local metadata should come from the
-      // next successful fetch so the sidebar does not render synthetic entries.
+      // Why: SSH worktrees aren't persisted in worktreesByRepo (discovered via relay); synthesize placeholders from session tabs so the sidebar shows them until SSH reconnect + fetchWorktrees replace them.
+      // Why: only SSH gets placeholders; local metadata comes from the next successful fetch.
       const sshRepoIds = new Set(
         runtimeSessionPlaceholders.repos.filter((r) => r.connectionId).map((r) => r.id)
       )
@@ -3378,8 +3073,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         if (existing) {
           continue
         }
-        // Why: strip the synthetic `::workspace:<uuid>` folder-workspace suffix
-        // so the placeholder path is a real cwd; `id` above keeps it for identity.
+        // Why: strip the synthetic `::workspace:<uuid>` folder suffix so the placeholder path is a real cwd; `id` above keeps it for identity.
         const path = splitWorktreeIdForFilesystem(worktreeId)?.worktreePath ?? ''
         // Why: SSH worktree paths may use backslash separators on Windows remotes.
         const displayName = path.split(/[/\\]/).pop() || path
@@ -3407,11 +3101,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         worktreesByRepo[repoId] = [...(worktreesByRepo[repoId] ?? []), placeholder]
       }
 
-      // Why: the restored-active worktree is set as activeWorktreeId here
-      // without ever going through setActiveWorktree, so its first-activation
-      // tagging needs to happen at hydration. Record it in
-      // everActivatedWorktreeIds so a later re-click doesn't re-tag (which
-      // would suppress real activity).
+      // Why: the restored-active worktree bypasses setActiveWorktree, so record it in everActivatedWorktreeIds here to keep a later re-click from re-tagging (which would suppress real activity).
       const nextEverActivated = new Set(s.everActivatedWorktreeIds)
       if (activeWorktreeId) {
         nextEverActivated.add(activeWorktreeId)
@@ -3428,10 +3118,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         repos: runtimeSessionPlaceholders.repos,
         tabsByWorktree,
         worktreesByRepo,
-        // Why: restore the per-worktree focus-recency map. Pruning of stale
-        // entries happens later (App.tsx calls pruneLastVisitedTimestamps
-        // after hydration) — not here — because SSH worktrees may still be
-        // appearing in worktreesByRepo at this moment.
+        // Why: restore the focus-recency map; pruning is deferred to App.tsx (post-hydration) because SSH worktrees may still be appearing in worktreesByRepo.
         lastVisitedAtByWorktreeId: session.lastVisitedAtByWorktreeId ?? {},
         defaultTerminalTabsAppliedByWorktreeId:
           session.defaultTerminalTabsAppliedByWorktreeId ?? {},
@@ -3441,13 +3128,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         pendingReconnectTabByWorktree,
         pendingReconnectPtyIdByTabId,
         everActivatedWorktreeIds: nextEverActivated,
-        // Why: seed worktree nav history with the hydrated active worktree so
-        // the first user-driven activation (e.g. a sidebar click to a different
-        // worktree) has a prior entry to go Back to. Without this the restored
-        // startup worktree is never recorded — recordWorktreeVisit only runs
-        // inside activateAndRevealWorktree, which hydration bypasses — so Back
-        // stays disabled until a second click produces the first-ever history
-        // pair.
+        // Why: seed nav history with the hydrated active worktree so the first activation has a Back target; hydration bypasses recordWorktreeVisit, so otherwise Back stays disabled until a second click.
         worktreeNavHistory: activeWorktreeId ? [activeWorktreeId] : [],
         worktreeNavHistoryIndex: activeWorktreeId ? 0 : -1,
         ptyIdsByTabId: Object.fromEntries(
@@ -3455,16 +3136,12 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
             .flat()
             .map((tab) => [tab.id, []] as const)
         ),
-        // Why: with the daemon backend, ptyIds are daemon session IDs that
-        // survive app restart. Preserve ptyIdsByLeafId so that
-        // reconnectPersistedTerminals can reattach each split-pane leaf
-        // to its specific daemon session (not just the tab-level ptyId).
+        // Why: daemon ptyIds survive app restart; preserve ptyIdsByLeafId so reconnect can reattach each split-pane leaf to its own session, not just the tab-level ptyId.
         terminalLayoutsByTabId: Object.fromEntries(
           Object.entries(session.terminalLayoutsByTabId)
             .filter(([tabId]) => validTabIds.has(tabId))
             .map(([tabId, layout]) => {
-              // Why: old sessions can contain renderer-local pane:1-style leaf
-              // ids. Normalize during hydration before runtime/mobile surfaces read them.
+              // Why: old sessions can contain renderer-local pane:1-style leaf ids; normalize before runtime/mobile surfaces read them.
               const normalized = normalizeTerminalLayoutSnapshot(layout).snapshot
               const tab = Object.values(tabsByWorktree)
                 .flat()
@@ -3505,16 +3182,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       return
     }
 
-    // Why: instead of eagerly spawning PTYs at default 80×24 (which fills
-    // eager buffers with content at wrong dimensions that gets garbled on
-    // flush), we defer the actual daemon createOrAttach call to connectPanePty
-    // where fitAddon provides real dims.
-    //
-    // This loop just records the daemon session IDs each leaf/tab needs so
-    // connectPanePty can pass them as sessionId to pty.spawn at mount time.
-    // The layout's ptyIdsByLeafId (preserved from shutdown) already has per-leaf
-    // mappings. For single-pane tabs without leaf mappings, store the tab-level
-    // ptyId as a sentinel so connectPanePty knows to reattach.
+    // Why: defer daemon createOrAttach to connectPanePty (real fitAddon dims) instead of eager-spawning at 80×24 and garbling on flush; this loop only records the session IDs to reattach.
     let reconnectedTabsByWorktree: Record<string, TerminalTab[]> | null = null
     let reconnectedPtyIdsByTabId: Record<string, string[]> | null = null
     for (const worktreeId of ids) {
@@ -3523,12 +3191,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         .flat()
         .find((entry) => entry.id === worktreeId)
       const repo = worktree ? get().repos.find((entry) => entry.id === worktree.repoId) : null
-      // Why: SSH-backed tabs were previously always skipped because the SSH
-      // connection wasn't re-established on startup. Now that we auto-reconnect
-      // SSH targets before this loop runs, we allow deferred reattach when the
-      // SSH connection is active. Without the active-connection check, we'd try
-      // to reattach to a relay that isn't connected yet (the deferred/passphrase
-      // targets), which would fail.
+      // Why: only allow deferred reattach when the SSH connection is active; reattaching to a not-yet-connected relay (deferred/passphrase targets) would fail.
       const sshState = repo?.connectionId ? get().sshConnectionStates.get(repo.connectionId) : null
       const sshConnected = repo?.connectionId != null && sshState?.status === 'connected'
       const supportsDeferredReattach = !repo?.connectionId || sshConnected
@@ -3553,16 +3216,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         const tabLevelPtyId = pendingReconnectPtyIdByTabId[tabId]
         const hasLeafMappings = Object.keys(leafPtyMap).length > 0
 
-        // Why: populate the wake-hint and the live-pty map so the worktree
-        // dot lights up green even before the terminal pane mounts —
-        // including deferred SSH worktrees whose connection isn't established
-        // yet. tab.ptyId carries the wake-hint sessionId (consumed by
-        // pty-connection.ts on remount); ptyIdsByTabId is the source of
-        // truth getWorktreeStatus reads for liveness. Without the live-pty
-        // population, the sidebar "show active only" filter hides SSH
-        // worktrees and the user must manually search for them. The actual
-        // PTY reattach is handled later by pty-connection.ts when the
-        // terminal pane mounts; this block only sets the visual state.
+        // Why: set the wake-hint (tab.ptyId) and live-pty map (ptyIdsByTabId) so the worktree dot goes green before the pane mounts; actual reattach happens later in pty-connection.ts.
         console.debug(
           `[reconnect-terminals] tab=${tabId} tabLevelPtyId=${tabLevelPtyId} supportsDeferredReattach=${supportsDeferredReattach} hasLeafMappings=${hasLeafMappings}`
         )
@@ -3573,38 +3227,27 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
             continue
           }
 
-          // Why: populate ptyIdsByTabId so the sessions status segment
-          // can map daemon session IDs back to tabs (for bound/orphan
-          // detection and click-to-navigate). Without this, all sessions
-          // appear as orphans until the terminal pane mounts.
+          // Why: populate ptyIdsByTabId so the sessions status segment maps daemon IDs to tabs; otherwise all sessions look like orphans until the pane mounts.
           const allPtyIds = hasLeafMappings
             ? (Object.values(leafPtyMap).filter(Boolean) as string[])
             : [tabLevelPtyId]
           reconnectedTabsByWorktree[worktreeId] = nextTabs.map((t) =>
             t.id === tabId ? { ...t, ptyId: tabLevelPtyId } : t
           )
-          // Why: hide-sleeping uses ptyIdsByTabId as the liveness source.
-          // Restored daemon sessions are still running even before their
-          // pane remounts, so background workspaces must advertise them.
+          // Why: hide-sleeping reads ptyIdsByTabId for liveness; restored daemon sessions run before their pane remounts, so advertise them.
           reconnectedPtyIdsByTabId ??= { ...ptyIdsByTabId }
           reconnectedPtyIdsByTabId[tabId] = allPtyIds
         }
       }
     }
 
-    // Why: deferred SSH targets (passphrase-protected) haven't connected
-    // yet, so their tabs' ptyIds were never restored above. Stash the
-    // session IDs in a separate map that survives this cleanup so the
-    // deferred reconnect code in pty-connection.ts can find them.
+    // Why: deferred SSH targets haven't connected yet, so their ptyIds weren't restored above; stash session IDs in a map that survives cleanup for pty-connection.ts's deferred reconnect.
     const deferredSshSessionIdsByTabId: Record<string, string> = {}
     for (const worktreeId of ids) {
       const worktree = Object.values(get().worktreesByRepo)
         .flat()
         .find((entry) => entry.id === worktreeId)
-      // Why: SSH worktrees aren't in worktreesByRepo at cold start (relay
-      // discovery needs the connection). Fall back to the repo id embedded in
-      // the composite worktree id so their sessions still reach the deferred
-      // map — otherwise panes fresh-spawn into a missing PTY provider.
+      // Why: SSH worktrees aren't in worktreesByRepo at cold start; fall back to the repo id in the composite worktree id so sessions still reach the deferred map.
       const repoId = worktree?.repoId ?? getRepoIdFromWorktreeId(worktreeId)
       const repo = repoId ? get().repos.find((entry) => entry.id === repoId) : null
       if (!repo?.connectionId) {
diff --git a/src/renderer/src/store/slices/ui.ts b/src/renderer/src/store/slices/ui.ts
index 713c204669d..fc0d5eba962 100644
--- a/src/renderer/src/store/slices/ui.ts
+++ b/src/renderer/src/store/slices/ui.ts
@@ -237,9 +237,7 @@ function clampPetSize(size: number): number {
   return Math.max(PET_SIZE_MIN, Math.min(PET_SIZE_MAX, Math.round(size)))
 }
 
-// Why: mirrors the preset→query mapping used by TaskPage's preset buttons.
-// Keeping a local copy here avoids a store ↔ lib circular import while letting
-// openTaskPage warm exactly the cache key the page will read on mount.
+// Why: local copy of TaskPage's preset→query mapping avoids a store ↔ lib circular import while warming the exact cache key.
 function presetToQuery(presetId: TaskViewPresetId | null): string {
   switch (presetId) {
     case 'all':
@@ -258,10 +256,7 @@ function presetToQuery(presetId: TaskViewPresetId | null): string {
   }
 }
 
-// Why: persisted UI state pre-dated the consolidation of `memory` + `sessions`
-// into a single `resource-usage` entry. Rewrite legacy ids in place and
-// de-duplicate. We leave unknown ids alone so a downgrade→upgrade cycle
-// doesn't strip a newer build's ids out of the user's settings.
+// Why: migrate legacy memory+sessions ids → resource-usage; keep unknown ids so downgrade→upgrade can't strip a newer build's ids.
 function migrateStatusBarItems(items: readonly string[] | undefined): StatusBarItem[] {
   const source = items ?? DEFAULT_STATUS_BAR_ITEMS
   const out: string[] = []
@@ -291,17 +286,10 @@ function normalizeHydratedVisibleWorkspaceHostIds(ui: PersistedUIState): Visible
 
 const MIN_SIDEBAR_WIDTH = 220
 const MAX_LEFT_SIDEBAR_WIDTH = 500
-// Why: the right sidebar drag-resize is window-relative (see right-sidebar
-// component), so persisted widths can legitimately be well above the old 500px
-// cap on wide displays. Use a large hard ceiling purely as a safety net for
-// corrupted/manually-edited values rather than as a product limit.
+// Why: right-sidebar resize is window-relative, so widths can far exceed 500px on wide displays; this ceiling is only a corruption safety net.
 const MAX_RIGHT_SIDEBAR_WIDTH = 4000
 const LINEAR_TASK_PREFETCH_LIMIT = 36
-// Why: bound disk growth for acknowledgedAgentsByPaneKey across hard quits —
-// in-session cleanup (agent-status.ts) prunes on pane lifecycle, but crash/
-// forced-kill paths leave entries pinned. Mirrors HYDRATE_MAX_AGE_MS in
-// src/main/agent-hooks/server.ts for parallel reasoning with the sibling
-// hook-status entries these acks pair with.
+// Why: bound disk growth across hard quits (crash paths leave acks pinned); mirrors HYDRATE_MAX_AGE_MS in agent-hooks/server.ts.
 const HYDRATE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
 const VALID_TASK_PRESETS = new Set<TaskViewPresetId>([
   'all',
@@ -439,10 +427,7 @@ function sanitizePersistedSidebarWidth(width: unknown, fallback: number, maxWidt
   return Math.min(maxWidth, Math.max(MIN_SIDEBAR_WIDTH, width))
 }
 
-// Why: persisted JSON can be tampered with or carry legacy/corrupt shapes.
-// Reject arrays (typeof [] === 'object'), prototype-pollution keys, and
-// non-positive-finite values; drop entries past the TTL so hard-quit leaks
-// don't accumulate forever.
+// Why: persisted JSON may be tampered/corrupt — reject arrays, prototype-pollution keys, and non-finite values; drop past-TTL entries.
 function sanitizeAcknowledgedAgentsByPaneKey(value: unknown): Record<string, number> {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     return {}
@@ -513,9 +498,7 @@ function sanitizeHydratedActiveView(
   if (!isTopLevelView(value)) {
     return 'terminal'
   }
-  // Why: activity is hidden when its setting is off, so restoring it lands on a
-  // hidden page (same guard as closeSettingsPage). mobile/automations stay
-  // functional when hidden, so only activity is gated here.
+  // Why: activity is hidden when its setting is off, so gate only it (mobile/automations stay functional when hidden).
   if (value === 'activity' && !experimentalActivityEnabled) {
     return 'terminal'
   }
@@ -605,13 +588,7 @@ export type UISlice = {
   openAgentSendPopoverTargetMode: (args: OpenAgentSendPopoverTargetModeArgs) => void
   closeAgentSendPopoverTargetMode: (id?: string, instanceId?: string) => void
   sendPromptToSidebarAgentTarget: (paneKey: string) => Promise<boolean>
-  /** Per-agent "I've looked at this" timestamps, keyed by paneKey. Set when
-   *  the user clicks an agent row or its parent workspace card from the
-   *  dashboard. A row is considered unvisited when no ack exists OR the
-   *  agent's current stateStartedAt is newer than the last ack (i.e. the
-   *  agent has transitioned state since the user last saw it). Persisted
-   *  via PersistedUIState because agent rows themselves now survive restart —
-   *  without this, rows you'd already visited come back bold on relaunch. */
+  /** Per-agent "I've looked at this" timestamps (paneKey → ts). A row is unvisited when no ack exists or stateStartedAt is newer than the last ack. Persisted so visited rows don't return bold on relaunch. */
   acknowledgedAgentsByPaneKey: Record<string, number>
   acknowledgeAgents: (paneKeys: string[]) => void
   unacknowledgeAgents: (paneKeys: string[]) => void
@@ -693,8 +670,7 @@ export type UISlice = {
   setGithubTaskDrawerWorkItem: (item: GitHubWorkItem | null) => void
   newWorkspaceDraft: {
     repoId: string | null
-    // Why: project-first workspace creation resolves through these when present,
-    // while old drafts can keep using only repoId during the additive migration.
+    // Why: project-first creation uses these when present; old drafts keep using only repoId during the additive migration.
     projectId?: string | null
     projectGroupId?: string | null
     hostId?: ExecutionHostId | null
@@ -711,21 +687,17 @@ export type UISlice = {
       linearIdentifier?: string
       linearBranchName?: string
     } | null
-    /** Why: starting from a task must preserve where provider data came from
-     *  separately from the host selected to run the workspace. */
+    /** Preserve where provider data came from, separately from the host chosen to run the workspace. */
     taskSourceContext?: TaskSourceContext | null
     agent: TuiAgent
     linkedIssue: string
     linkedPR: number | null
-    /** GitLab parallels — number for an issue, iid for an MR. Optional so
-     *  drafts saved before GitLab support keep loading without migration. */
+    /** GitLab parallels — number for an issue, iid for an MR. Optional so pre-GitLab drafts still load without migration. */
     linkedGitLabIssue?: number | null
     linkedGitLabMR?: number | null
-    // Why: repo-scoped start ref selected via the "Start from" picker.
-    // Absent means "use the repo's effective base ref".
+    // Why: repo-scoped start ref from the "Start from" picker; absent means "use the repo's effective base ref".
     baseBranch?: string
-    // Why: review-created worktrees can start from a head ref/SHA while Source
-    // Control must compare against the provider target branch.
+    // Why: review worktrees start from a head ref/SHA while Source Control compares against the provider target branch.
     compareBaseRef?: string
   } | null
   openTaskPage: (
@@ -765,19 +737,10 @@ export type UISlice = {
   } | null
   openSettingsTarget: (target: NonNullable<UISlice['settingsNavigationTarget']>) => void
   clearSettingsTarget: () => void
-  /**
-   * Which host the Projects Settings pane shows for each project, keyed by
-   * projectId. Set by the pane's "Available Hosts" switcher. Ephemeral on
-   * purpose — never persisted, so a reload reopens on the project's effective
-   * host rather than a possibly-dangling selection.
-   */
+  /** Which host the Projects Settings pane shows per project (keyed by projectId). Ephemeral on purpose — never persisted, so reload reopens on the effective host. */
   settingsProjectHostSelection: Record<string, ExecutionHostId>
   setSettingsProjectHostSelection: (projectId: string, hostId: ExecutionHostId) => void
-  /**
-   * One-shot Appearance accordion to expand for nested Settings deep links
-   * (e.g. Usage percentages lives under Window & Sidebar). Cleared when
-   * Appearance consumes it.
-   */
+  /** One-shot Appearance accordion to expand for nested Settings deep links (e.g. Usage percentages under Window & Sidebar). Cleared when Appearance consumes it. */
   appearanceAccordionDeepLink: 'interface' | 'terminal' | 'window' | null
   setAppearanceAccordionDeepLink: (
     section: NonNullable<UISlice['appearanceAccordionDeepLink']>
@@ -928,23 +891,17 @@ export type UISlice = {
   ) => void
   setWorkspacePortScanForKey: (key: string, result: WorkspacePortScanResult | null) => void
   setWorkspacePortScanRefreshing: (refreshing: boolean) => void
-  /** Whether the experimental pet overlay is currently visible. Persisted
-   *  so "Hide pet" from the status-bar menu survives reload. Independent
-   *  of the experimentalPet settings flag — the feature flag gates
-   *  whether the overlay can ever render; this controls whether it does now. */
+  /** Whether the pet overlay is currently visible. Persisted so "Hide pet" survives reload. Independent of the experimentalPet flag (which gates whether it can render at all). */
   petVisible: boolean
   setPetVisible: (v: boolean) => void
-  /** Which pet is active — either a bundled id or a custom UUID.
-   *  Persisted alongside petVisible via the PersistedUIState pipeline. */
+  /** Which pet is active — a bundled id or a custom UUID. Persisted via PersistedUIState. */
   petId: string
   setPetId: (id: string) => void
   /** User-uploaded pet images. Metadata only — bytes live in main's userData. */
   customPets: CustomPet[]
   addCustomPet: (model: CustomPet) => void
   removeCustomPet: (id: string) => void
-  /** Pet overlay size in CSS pixels (square). User-adjustable from the
-   *  status-bar menu so a too-big imported sprite isn't a stuck-on-screen
-   *  problem. */
+  /** Pet overlay size in CSS pixels (square). User-adjustable so an oversized imported sprite isn't stuck on screen. */
   petSize: number
   setPetSize: (size: number) => void
   pendingRevealWorktree: PendingSidebarWorktreeReveal | null
@@ -966,10 +923,7 @@ export type UISlice = {
   ) => void
   clearPendingRevealWorktreeId: () => void
   clearPendingRevealSidebarRow: () => void
-  // Why: lets the SourceControl sidebar request that the diff editor scroll
-  // to a specific note. Cleared by the diff decorator after it reveals the
-  // line, so the same id can be requested again later without the surface
-  // seeing a stale value.
+  // Why: cleared by the diff decorator after it reveals the line, so the same id can be requested again without a stale value.
   scrollToDiffCommentId: string | null
   setScrollToDiffCommentId: (id: string | null) => void
   persistedUIReady: boolean
@@ -980,19 +934,14 @@ export type UISlice = {
   hydratePersistedUI: (ui: PersistedUIState, source?: 'startup' | 'sync') => void
   updateStatus: UpdateStatus
   setUpdateStatus: (status: UpdateStatus) => void
-  // Why: cached changelog from the last 'available' status so the card still has
-  // rich content (title/media/description) during downloading, error, and downloaded
-  // states. Cleared on idle/checking/not-available to prevent stale leakage.
+  // Why: cache last-'available' changelog so the card keeps rich content while downloading; cleared on idle/checking to avoid staleness.
   updateChangelog: ChangelogData | null
-  // Why: UpdateCard is lazy-loaded, so it may miss the transient
-  // checking/userInitiated status. Keep manual-check intent in the store until
-  // the resulting available/error/not-available state can consume it.
+  // Why: UpdateCard is lazy-loaded and may miss the transient checking status; hold manual-check intent until a terminal state consumes it.
   updateUserInitiatedCycle: boolean
   dismissedUpdateVersion: string | null
   dismissUpdate: (versionOverride?: string) => void
   clearDismissedUpdateVersion: () => void
-  // Why: ephemeral and renderer-only — never persisted and never crosses IPC.
-  // Resets every session and on every phase transition (see setUpdateStatus).
+  // Why: ephemeral, renderer-only — never persisted; resets each session and on every phase transition (see setUpdateStatus).
   updateCardCollapsed: boolean
   setUpdateCardCollapsed: (collapsed: boolean) => void
   updateReassuranceSeen: boolean
@@ -1068,9 +1017,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
 
     const target = resolveRunningAgentSendTarget(get(), mode.worktreeId, paneKey)
     if (!target || target.status !== 'eligible' || !target.ptyId) {
-      // Why: live revalidation can lose eligibility after the user opened the
-      // menu. Treat that like an ineligible row click: keep the picker open and
-      // let the row title explain the current reason without adding toast noise.
+      // Why: eligibility can drop after the menu opened; keep the picker open (row title explains) rather than adding toast noise.
       return false
     }
 
@@ -1162,13 +1109,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         return s
       }
       const now = Date.now()
-      // Why: only allocate a new map (and emit a store update) if at least
-      // one ack is actually moving forward. Comparing `prev < now` instead
-      // of `prev !== now` matters because stored values are historical
-      // timestamps and `Date.now()` advances every millisecond — a strict-
-      // inequality guard would fire on every call and rewrite the map on
-      // every dashboard click or auto-ack tick, forcing every subscriber
-      // (all agent rows, the SidebarHeader count, etc.) to re-render.
+      // Why: only reallocate if an ack advances; compare prev<now not !== — Date.now() ticks every ms and !== would rewrite the map every call.
       let next: Record<string, number> | null = null
       for (const key of paneKeys) {
         const prev = s.acknowledgedAgentsByPaneKey[key] ?? 0
@@ -1259,12 +1200,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
     if (data.openJiraIssue) {
       get().recordFeatureInteraction?.('jira-tasks')
     }
-    // Why: record a Tasks visit in the shared back/forward history so the
-    // titlebar Back/Forward buttons can return to Tasks. All task-source
-    // variants (github/linear presets) collapse to a single 'tasks' entry;
-    // the slice's adjacent-entry dedupe drops re-opens. No isNavigatingHistory
-    // guard needed — back-to-Tasks routes through setActiveView('tasks') and
-    // never re-enters openTaskPage.
+    // Why: record a Tasks visit in shared back/forward history; all task-source variants collapse to one deduped 'tasks' entry.
     const detailEntry = data.openGitHubWorkItem
       ? ({
           kind: 'task-detail',
@@ -1311,11 +1247,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         state.activeView === 'tasks' ? state.previousViewBeforeTasks : state.activeView,
       taskPageData: data
     }))
-    // Why: prefetch the GitHub work-item list in parallel with React's first
-    // render of the TaskPage — by the time the page's own effect runs, the SWR
-    // cache is either already populated or the request is in-flight and will
-    // be deduped. This removes ~300–800ms of perceived latency on initial
-    // page load.
+    // Why: prefetch the work-item list during first render so the page's effect hits a warm/in-flight SWR cache (~300–800ms win).
     const state = get()
     const preferredVisibleTaskProviders = normalizeVisibleTaskProviders(
       state.settings?.visibleTaskProviders
@@ -1353,11 +1285,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
 
       const resume = state.taskResumeState
       const defaultPreset = state.settings?.defaultTaskViewPreset ?? 'all'
-      // Why: must match the exact query TaskPage's resume effect mounts with,
-      // otherwise the warm cache key (e.g. 'is:issue is:open') misses the
-      // page's actual fetch key and the prefetch is wasted. When the user has
-      // an explicit custom search (preset === null), preserve it so both sides
-      // agree.
+      // Why: must match the query TaskPage's resume effect mounts with, else the warm cache key misses and prefetch is wasted.
       const query =
         resume?.githubItemsPreset === null
           ? (resume.githubItemsQuery ?? '').trim()
@@ -1383,8 +1311,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
           { sourceContext }
         )
       } else {
-        // Why: TaskPage no longer exposes Linear preset filters; keep warm
-        // prefetch aligned with the default unsearched issue list.
+        // Why: TaskPage no longer exposes Linear preset filters; keep prefetch aligned with the default unsearched issue list.
         state.prefetchLinearIssues(
           {
             kind: 'list',
@@ -1405,15 +1332,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
   setGithubTaskDrawerWorkItem: (item) => set({ githubTaskDrawerWorkItem: item }),
   closeTaskPage: () =>
     set((state) => {
-      // Why: Esc-close from Tasks must rewind the history index if we're
-      // currently parked on a 'tasks' entry. Without this, A → Tasks → Esc
-      // leaves the index at the 'tasks' entry, making Back a visual no-op
-      // (activator re-activates A) and Forward re-opens Tasks. If there is no
-      // earlier live entry (e.g. history is just ['tasks']), leave the index
-      // at 0 — setting it to -1 would lose the only forward target, while the
-      // resulting Back visual no-op self-heals as soon as a real visit records
-      // a new entry. closeTaskPage never runs from the history-nav path, so no
-      // isNavigatingHistory guard is needed.
+      // Why: if parked on a 'tasks' entry, rewind the history index so Back/Forward aren't no-ops; keep 0 if it's the only entry.
       const currentEntry = state.worktreeNavHistory[state.worktreeNavHistoryIndex]
       let nextHistoryIndex = state.worktreeNavHistoryIndex
       if (
@@ -1511,15 +1430,11 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
   setNewWorkspaceDraft: (draft) => set({ newWorkspaceDraft: draft }),
   clearNewWorkspaceDraft: () => set({ newWorkspaceDraft: null }),
   openSettingsPage: () => {
-    // Why: settings search is a transient page filter; opening Settings
-    // should never inherit hidden sections from the previous visit.
+    // Why: settings search is a transient filter; opening Settings shouldn't inherit hidden sections from last visit.
     get().setSettingsSearchQuery('')
     set((state) => ({
       activeView: 'settings',
-      // Why: Settings is a temporary detour from either terminal or the
-      // full-page tasks view. Preserve the originating view so the Settings
-      // back action restores an in-progress workspace draft instead of always
-      // dumping the user into terminal.
+      // Why: preserve the originating view so Settings back returns there (e.g. in-progress draft), not always terminal.
       previousViewBeforeSettings:
         state.activeView === 'settings' ? state.previousViewBeforeSettings : state.activeView
     }))
@@ -1537,8 +1452,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
   openSettingsTarget: (target) => set({ settingsNavigationTarget: target }),
   clearSettingsTarget: () => set({ settingsNavigationTarget: null }),
   settingsProjectHostSelection: {},
-  // Why: renderer-only, never persisted — no window.api.ui.set here and this
-  // field is intentionally absent from the debounced UI writer in App.tsx.
+  // Why: renderer-only, never persisted — no window.api.ui.set, and absent from the debounced UI writer in App.tsx.
   setSettingsProjectHostSelection: (projectId, hostId) =>
     set((s) =>
       s.settingsProjectHostSelection[projectId] === hostId
@@ -1623,8 +1537,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         persistPromise = persist.catch(console.error)
       }
       if (tourProgression === 'reveal-sidebar-and-advance') {
-        // Why: the split can be triggered by keyboard/menu paths while the
-        // sidebar is closed, but the next tour target lives in the sidebar.
+        // Why: split can fire from keyboard/menu with the sidebar closed, but the next tour target lives in the sidebar.
         return {
           featureInteractions: next,
           sidebarOpen: true,
@@ -1978,8 +1891,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
       window.api.ui.set({ projectOrderManualDefaultNoticeDismissed: true }).catch(console.error)
       return { projectOrderManualDefaultNoticeDismissed: true }
     }),
-  // Why: defaults true so pre-hydration / brand-new sessions never flash the
-  // change notice before persistence resolves eligibility.
+  // Why: default true so pre-hydration / new sessions never flash the change notice before persistence resolves.
   usagePercentageDisplayChangeNoticeDismissed: true,
   dismissUsagePercentageDisplayChangeNotice: () =>
     set((s) => {
@@ -2000,9 +1912,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
     }),
 
   groupBy: 'repo',
-  // Why: group keys are mode-specific (e.g. repo id vs PR status), so
-  // collapsed state from one mode is meaningless in another. Clearing
-  // also prevents unbounded accumulation of stale keys across mode switches.
+  // Why: group keys are mode-specific, so clear collapsed state on mode switch — stale keys are meaningless and accumulate.
   setGroupBy: (g) => {
     window.api.ui.set({ groupBy: g, collapsedGroups: [] }).catch(console.error)
     set({ groupBy: g, collapsedGroups: new Set<string>() })
@@ -2011,8 +1921,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
   sortBy: 'recent',
   setSortBy: (s) => set({ sortBy: s }),
 
-  // Why: like setSortBy, this is a bare set — it persists only via the
-  // debounced window.api.ui.set writer in App.tsx, not on its own.
+  // Why: bare set — persists only via the debounced window.api.ui.set writer in App.tsx, not on its own.
   projectOrderBy: 'manual',
   setProjectOrderBy: (p) => set({ projectOrderBy: p }),
 
@@ -2023,8 +1932,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
   setShowSleepingWorkspaces: (v) => set({ showSleepingWorkspaces: v }),
 
   workspaceHostScope: 'all',
-  // Why (multi-host design): host scope is presentation/filtering only — it must
-  // never trigger resource teardown (terminals, browser pages, etc.).
+  // Why: host scope is presentation/filtering only — must never trigger resource teardown (terminals, browser pages).
   setWorkspaceHostScope: (scope) => {
     const normalized = normalizeExecutionHostScope(scope)
     const visibleWorkspaceHostIds = normalized === 'all' ? null : [normalized]
@@ -2036,8 +1944,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
   visibleWorkspaceHostIds: null,
   setVisibleWorkspaceHostIds: (ids) => {
     const normalized = normalizeVisibleExecutionHostIds(ids)
-    // Why: workspaceHostScope remains the compatibility/default-host signal
-    // for creation flows while visibility can now be multi-select.
+    // Why: workspaceHostScope stays the compat/default-host signal for creation flows; visibility can now be multi-select.
     let workspaceHostScope: WorkspaceHostScope = get().workspaceHostScope
     if (normalized === null) {
       workspaceHostScope = 'all'
@@ -2190,8 +2097,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
   usagePercentageDisplay: DEFAULT_USAGE_PERCENTAGE_DISPLAY,
   setUsagePercentageDisplay: (display) => {
     const normalized = normalizeUsagePercentageDisplay(display)
-    // Why: changing the control is the discovery path; permanently dismiss the
-    // one-time change notice so it does not reappear after the user adapted.
+    // Why: changing the control is the discovery path, so permanently dismiss the one-time change notice.
     window.api.ui
       .set({
         usagePercentageDisplay: normalized,
@@ -2237,8 +2143,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
       }
       return { workspacePortScan: scan }
     }),
-  // Why: host-set changes must remove stale per-host scans in one store update so a
-  // large disconnected host set cannot fan out map notifications to every subscriber.
+  // Why: drop stale per-host scans in one store update so a large host set can't fan out notifications to every subscriber.
   replaceWorkspacePortScans: (scansByKey, projection) =>
     set((state) => {
       if (
@@ -2274,9 +2179,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
     }),
   setWorkspacePortScanRefreshing: (refreshing) => set({ workspacePortScanRefreshing: refreshing }),
 
-  // Why: default true so a user who enables experimentalPet sees the
-  // pet immediately. Hide pet from the status-bar menu flips this
-  // to false; the value is persisted via the standard PersistedUIState pipeline.
+  // Why: default true so enabling experimentalPet shows the pet immediately (persisted; "Hide pet" flips it false).
   petVisible: true,
   setPetVisible: (v) => {
     window.api.ui.set({ petVisible: v }).catch(console.error)
@@ -2310,11 +2213,9 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         return s
       }
       const next = s.customPets.filter((m) => m.id !== id)
-      // Why: if the user removes the currently-active custom pet, fall
-      // back to the bundled default so the overlay doesn't render nothing.
+      // Why: removing the active custom pet falls back to bundled default so the overlay isn't empty.
       const fallback = s.petId === id ? DEFAULT_PET_ID : s.petId
-      // Why: send a single combined IPC update so customPets and
-      // petId persist atomically when both change.
+      // Why: single combined IPC update so customPets and petId persist atomically.
       const ipcPayload: { customPets: CustomPet[]; petId?: string } = {
         customPets: next
       }
@@ -2322,13 +2223,9 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         ipcPayload.petId = fallback
       }
       window.api.ui.set(ipcPayload).catch(console.error)
-      // Why: revoke the cached blob: URL so the underlying Blob is released;
-      // otherwise it stays in memory for the rest of the session.
+      // Why: revoke the cached blob: URL so the Blob is released, not leaked for the session.
       revokeCustomPetBlobUrl(id)
-      // Why: best-effort — the bytes are owned by main. If the disk delete
-      // fails, the orphaned image stays in userData; each import uses a fresh
-      // UUID so the file won't be hit again, and the renderer's metadata
-      // index no longer references it.
+      // Why: best-effort delete — bytes owned by main; fresh-UUID imports mean an orphaned file is never re-referenced.
       window.api.pet.delete(id, target.fileName, target.kind).catch(console.error)
       const partial: Partial<UISlice> = { customPets: next }
       if (fallback !== s.petId) {
@@ -2372,23 +2269,14 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
       const orderedRepos = applyManualRepoOrder(s.repos, manualRepoOrder)
       const validRepoIds = new Set(s.repos.map((repo) => repo.id))
       const persistedFilterRepoIds = sanitizePersistedRepoIds(ui.filterRepoIds)
-      // Why: persisted UI from pre-rename builds used sidekick* keys. Read
-      // those only as fallbacks so new pet* writes win immediately after upgrade.
+      // Why: pre-rename builds used sidekick* keys; read as fallback only so new pet* writes win after upgrade.
       const customPets = Array.isArray(ui.customPets)
         ? ui.customPets
         : Array.isArray(ui.customSidekicks)
           ? ui.customSidekicks
           : []
       const petId = ui.petId ?? ui.sidekickId
-      // Migration history:
-      // v1: sort was called 'smart' internally
-      // v2: renamed 'smart' → 'recent' (same weighted-score behavior)
-      // v3: 'smart' reintroduced as the weighted-score sort, 'recent' becomes
-      //     a last-activity sort (worktree.lastActivityAt descending). The
-      //     one-shot migration from old 'recent' to 'smart' happens in the
-      //     main process (persistence.ts load()) using the _sortBySmartMigrated
-      //     flag — not here — so that users who intentionally select the new
-      //     'recent' sort keep it across restarts.
+      // Migration: one-shot old-'recent'→'smart' runs in main (_sortBySmartMigrated), not here, so a deliberate 'recent' choice survives restart.
       const sortBy = ui.sortBy
       const migratedStatusBarItems = migrateStatusBarItems(ui.statusBarItems)
       const statusBarItemsWithPorts =
@@ -2435,10 +2323,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         ui.rightSidebarExplorerView
       )
       const hydrated = {
-        // Why: persisted UI data comes from disk and may be stale, corrupted,
-        // or manually edited. Clamp widths during hydration so invalid values
-        // cannot push the renderer into broken layouts before the user drags a
-        // sidebar again.
+        // Why: persisted widths may be stale/corrupt/hand-edited; clamp during hydration so invalid values can't break layout.
         sidebarWidth: sanitizePersistedSidebarWidth(
           ui.sidebarWidth,
           s.sidebarWidth,
@@ -2459,28 +2344,22 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         rightSidebarExplorerView: rightSidebarRoute.rightSidebarExplorerView,
         groupBy: (ui.groupBy as UISlice['groupBy'] | 'parent') === 'parent' ? 'repo' : ui.groupBy,
         sortBy,
-        // Why: main-process getUI() already normalized this to a valid value
-        // (defaulting to 'manual'); read it through without migrating sortBy.
+        // Why: main-process getUI() already normalized this (defaulting to 'manual'); read it through without migrating.
         projectOrderBy: ui.projectOrderBy,
-        // Why: Active-only was retired. Force the old persisted flag off so an
-        // old profile cannot invisibly keep narrowing the workspace list.
+        // Why: Active-only was retired; force the old flag off so an old profile can't invisibly narrow the workspace list.
         showActiveOnly: false,
-        // Why: `hideSleepingWorkspaces` is the canonical negative-form filter.
-        // Older positive-form keys are intentionally ignored so old profiles
-        // start from the new default: sleeping workspaces visible.
+        // Why: ignore older positive-form keys so old profiles start from the new default (sleeping workspaces visible).
         showSleepingWorkspaces: !(ui.hideSleepingWorkspaces ?? DEFAULT_HIDE_SLEEPING_WORKSPACES),
         workspaceHostScope: normalizeExecutionHostScope(ui.workspaceHostScope),
         visibleWorkspaceHostIds: normalizeHydratedVisibleWorkspaceHostIds(ui),
         workspaceHostOrder: normalizeExecutionHostOrder(ui.workspaceHostOrder),
         manualRepoOrder,
-        // Why: UI state can arrive after a catalog or from another client; apply
-        // the desktop-owned overlay immediately instead of waiting for a refetch.
+        // Why: apply the desktop-owned overlay immediately since UI state can arrive after a catalog or from another client.
         repos: orderedRepos,
         hideDefaultBranchWorkspace: ui.hideDefaultBranchWorkspace ?? false,
         hideAutomationGeneratedWorkspaces: ui.hideAutomationGeneratedWorkspaces === true,
         showDotfilesByWorktree: sanitizeShowDotfilesByWorktree(ui.showDotfilesByWorktree),
-        // Why: startup hydrates UI before repo catalogs now. With no catalog
-        // loaded yet, defer repo-filter validation to the all-host repo refresh.
+        // Why: startup hydrates UI before repo catalogs, so defer repo-filter validation to the all-host refresh.
         filterRepoIds:
           validRepoIds.size === 0
             ? persistedFilterRepoIds
@@ -2498,15 +2377,11 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         statusBarItems: statusBarItemsWithGrok,
         statusBarVisible: ui.statusBarVisible ?? true,
         usagePercentageDisplay: normalizeUsagePercentageDisplay(ui.usagePercentageDisplay),
-        // Why: absent → true so existing users see the pet the first time
-        // they enable the experimental flag. Only an explicit Hide pet
-        // dismissal persists a `false` value.
+        // Why: default true so existing users see the pet on first enabling the flag; only an explicit Hide persists false.
         petVisible: ui.petVisible ?? ui.sidekickVisible ?? true,
         petSize: clampPetSize(ui.petSize ?? ui.sidekickSize ?? PET_SIZE_DEFAULT),
         customPets,
-        // Why: accept the persisted id if it matches a bundled pet or a
-        // known custom one; otherwise fall back so the overlay never renders
-        // nothing (e.g. custom pet was removed by another session).
+        // Why: fall back to default when the persisted id is unknown (e.g. custom pet removed elsewhere) so the overlay renders.
         petId: ((): string => {
           const id = petId
           if (typeof id !== 'string') {
@@ -2551,38 +2426,26 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         mobileEmulatorAgentSetupDismissed: ui.mobileEmulatorAgentSetupDismissed === true,
         projectOrderManualDefaultNoticeDismissed:
           ui.projectOrderManualDefaultNoticeDismissed === true,
-        // Why: load() resolves this for existing vs new profiles; treat only
-        // explicit true as dismissed so a false from migration still surfaces.
+        // Why: treat only explicit true as dismissed so a false from migration still surfaces.
         usagePercentageDisplayChangeNoticeDismissed:
           ui.usagePercentageDisplayChangeNoticeDismissed === true,
-        // Why: default false when undefined so existing users still see the CTA;
-        // only an explicit dismissal persists true.
+        // Why: default false so existing users still see the CTA; only explicit dismissal persists true.
         usageEmptyStateDismissed: ui.usageEmptyStateDismissed === true,
-        // Why: restore visited-row acks alongside the persisted hook entries
-        // they pair with. Stale acks for paneKeys whose tab/PTY no longer
-        // exists are inert (no row references them); a paneKey reuse stamps a
-        // fresh stateStartedAt that beats the old ack via the ackAt <
-        // stateStartedAt comparison in WorktreeCardAgents. Sanitizer drops
-        // entries past HYDRATE_MAX_AGE_MS so hard-quit/crash paths that miss
-        // the in-session cleanup in agent-status.ts can't accumulate forever.
+        // Why: stale acks are inert (paneKey reuse beats them via stateStartedAt); sanitizer bounds growth past HYDRATE_MAX_AGE_MS.
         acknowledgedAgentsByPaneKey: sanitizeAcknowledgedAgentsByPaneKey(
           ui.acknowledgedAgentsByPaneKey
         ),
         workspaceCleanupDismissals: sanitizeWorkspaceCleanupDismissals(
           ui.workspaceCleanup?.dismissals
         ),
-        // Why: restore the view only from the startup hydration. The same action also
-        // runs on every cross-window ui:stateChanged broadcast (source 'sync', the
-        // default); re-applying activeView there would yank the user's current
-        // per-window view (navigation state, not a synced preference).
+        // Why: restore only on startup; on 'sync' broadcasts it would clobber the window's current per-window view.
         activeView:
           source === 'startup'
             ? sanitizeHydratedActiveView(ui.activeView, s.settings?.experimentalActivity === true)
             : s.activeView,
         persistedUIReady: true
       }
-      // Why: main rebroadcasts UI written by any client. Identical hydration must
-      // not create fresh references that App's debounced writer echoes to main.
+      // Why: return the same ref on identical hydration so App's debounced writer doesn't echo it back to main.
       return hydratedUIPartialMatchesState(s, hydrated) ? s : hydrated
     }),
 
@@ -2603,25 +2466,19 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
       update.updateUserInitiatedCycle = false
     }
     if (status.state === 'available') {
-      // Why: cache changelog from each 'available' payload so the card retains
-      // rich content across downloading/error/downloaded transitions. Always
-      // overwrite (even with null) to prevent a previous rich changelog from
-      // leaking into a later simple-mode update for a different version.
+      // Why: always overwrite (even with null) so a prior version's changelog can't leak into a later simple-mode update.
       update.updateChangelog = status.changelog ?? null
     } else if (
       status.state === 'idle' ||
       status.state === 'checking' ||
       status.state === 'not-available'
     ) {
-      // Why: reset on cycle-boundary states so stale rich content from a
-      // previous update cycle cannot resurface.
+      // Why: reset on cycle-boundary states so stale rich content from a previous cycle can't resurface.
       update.updateChangelog = null
     }
-    // For 'downloading', 'downloaded', 'error': leave updateChangelog untouched
-    // so the card can keep showing rich content from the original 'available'.
+    // 'downloading'/'downloaded'/'error': leave updateChangelog untouched to keep the original 'available' content.
     if (status.state !== prevState) {
-      // Why: re-surface the card on every phase transition so a prior collapse
-      // of `downloading` doesn't bury the `downloaded`/`error` that follows.
+      // Why: re-surface the card on each phase transition so a collapsed `downloading` doesn't bury `downloaded`/`error`.
       update.updateCardCollapsed = false
     }
     set(update)
@@ -2634,19 +2491,14 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
   },
   dismissUpdate: (versionOverride?: string) =>
     set((s) => {
-      // Why: the 'error' variant has no version field, so the card passes
-      // the cached version explicitly via versionOverride.
+      // Why: the 'error' variant has no version field, so the card passes it via versionOverride.
       const dismissedUpdateVersion =
         versionOverride ?? ('version' in s.updateStatus ? (s.updateStatus.version ?? null) : null)
       const activeNudgeId =
         'activeNudgeId' in s.updateStatus ? (s.updateStatus.activeNudgeId ?? null) : null
-      // Why: dismissing an update is user intent, not transient view state. Persist
-      // the dismissed version so relaunching the app does not immediately re-show
-      // the same reminder card until a newer release appears.
+      // Why: persist dismissal so relaunch doesn't immediately re-show the same card until a newer release.
       void window.api.ui.set({ dismissedUpdateVersion }).catch(console.error)
-      // Why: only dismiss the main-process nudge campaign when the visible card
-      // actually came from a nudge-driven update cycle. Ordinary update dismissals
-      // must not consume the active campaign state.
+      // Why: only consume the nudge campaign for cards from a nudge cycle, not ordinary dismissals.
       if (activeNudgeId) {
         void window.api.updater.dismissNudge().catch(console.error)
       }
diff --git a/src/renderer/src/store/slices/worktree-nav-history.ts b/src/renderer/src/store/slices/worktree-nav-history.ts
index 35fa9825e4d..5a72d3d0530 100644
--- a/src/renderer/src/store/slices/worktree-nav-history.ts
+++ b/src/renderer/src/store/slices/worktree-nav-history.ts
@@ -9,17 +9,10 @@ import {
 } from '../../../../shared/task-source-context'
 import { parseWorkspaceKey } from '../../../../shared/workspace-scope'
 
-// Why: cap the per-session history so a long-lived workspace with many
-// worktree jumps cannot grow the array unbounded. 50 is generous enough
-// that the cap is never visible in normal use but small enough that the
-// linear skip-deleted scan in goBack/goForward stays trivially cheap.
+// Why: bound per-session history growth; 50 keeps goBack/goForward's linear scans cheap yet is never hit in normal use.
 const MAX_HISTORY = 50
 
-// Why: entries are worktree IDs OR page sentinels for full-page visits.
-// The slice, selector, and action names retain the
-// "worktree"/"WorktreeHistory" prefix for call-site stability — renaming
-// across ~20 sites would churn for no behavior win. View entries are
-// always live (never skipped by findPrev/NextLiveWorktreeHistoryIndex).
+// Why: entries may be page sentinels, not just worktree IDs; names keep the "worktree" prefix for call-site stability.
 export type WorktreeNavHistorySimpleViewEntry = 'tasks' | 'automations'
 export type WorktreeNavHistoryTaskDetailEntry =
   | {
@@ -55,13 +48,9 @@ export type WorktreeNavHistoryEntry = string | WorktreeNavHistoryViewEntry
 export type WorktreeNavHistorySlice = {
   // Linear history, oldest -> newest.
   worktreeNavHistory: WorktreeNavHistoryEntry[]
-  // Index into worktreeNavHistory; points at the currently-active entry.
-  // -1 means empty (no worktree ever activated this session).
+  // Index into worktreeNavHistory pointing at the active entry; -1 means empty.
   worktreeNavHistoryIndex: number
-  // Why: set while goBack/goForward are calling activateAndRevealWorktree so
-  // the activation path's recordWorktreeVisit step can skip re-recording a
-  // history-driven navigation. Kept in-store (rather than as a module-level
-  // mutable) so tests can drive the slice in isolation.
+  // Why: true during goBack/goForward so recordWorktreeVisit skips re-recording a history-driven navigation.
   isNavigatingHistory: boolean
 
   recordWorktreeVisit: (worktreeId: string) => void
@@ -73,10 +62,7 @@ export type WorktreeNavHistorySlice = {
 type ActivateFn = (worktreeId: string) => unknown
 type ViewActivateFn = (entry: WorktreeNavHistoryViewEntry) => void
 
-// Why: the slice must call activateAndRevealWorktree from goBack/goForward, but
-// importing it directly would create a cycle (activation imports the store).
-// Install the reference at module init via setWorktreeNavActivator and keep
-// the slice itself unaware of the activation module.
+// Why: injected via setWorktreeNavActivator to avoid an import cycle (activation imports the store).
 let activator: ActivateFn | null = null
 let viewActivator: ViewActivateFn | null = null
 
@@ -84,15 +70,12 @@ export function setWorktreeNavActivator(fn: ActivateFn | null): void {
   activator = fn
 }
 
-// Why: installed by App-level init so the slice can dispatch page entries
-// to setActiveView(...) without importing the UI slice directly (the UI
-// slice already transitively depends on this module via the store creator).
+// Why: injected to avoid an import cycle — the UI slice already depends on this module.
 export function setWorktreeNavViewActivator(fn: ViewActivateFn | null): void {
   viewActivator = fn
 }
 
-// Why: view entries short-circuit as live unconditionally — findWorktreeById
-// takes a worktree id and would always return undefined for page sentinels.
+// Why: view entries count as live unconditionally — findWorktreeById can't resolve page sentinels.
 function isViewEntry(entry: WorktreeNavHistoryEntry): entry is WorktreeNavHistoryViewEntry {
   return entry === 'tasks' || entry === 'automations' || typeof entry === 'object'
 }
@@ -150,22 +133,18 @@ function appendHistoryEntry(
   s: { worktreeNavHistory: WorktreeNavHistoryEntry[]; worktreeNavHistoryIndex: number },
   entry: WorktreeNavHistoryEntry
 ): { worktreeNavHistory: WorktreeNavHistoryEntry[]; worktreeNavHistoryIndex: number } {
-  // Why: re-visiting the same entry must not pollute history. The de-dup
-  // applies only to the current entry so that A -> B -> A remains a valid
-  // stack (user left B, returned to A). Same rule covers page re-opens:
-  // Tasks data changes and repeated Automations opens collapse to one entry.
+  // Why: de-dup only against the current entry so A -> B -> A stays a valid stack.
   const current = s.worktreeNavHistory[s.worktreeNavHistoryIndex]
   if (current !== undefined && getHistoryEntryKey(current) === getHistoryEntryKey(entry)) {
     return s
   }
 
-  // Truncate any forward entries, then append and advance the index.
+  // Truncate forward entries so appending starts a new branch.
   const truncated = s.worktreeNavHistory.slice(0, s.worktreeNavHistoryIndex + 1)
   truncated.push(entry)
   let nextIndex = s.worktreeNavHistoryIndex + 1
 
-  // Why: cap eviction drops the oldest entries. The index must shift left
-  // by the same count so it still points at the just-appended current entry.
+  // Why: shift index left by the eviction count so it still points at the just-appended entry.
   if (truncated.length > MAX_HISTORY) {
     const evict = truncated.length - MAX_HISTORY
     truncated.splice(0, evict)
@@ -265,44 +244,30 @@ function navigateToIndex(
   }
   const targetEntry = state.worktreeNavHistory[targetIndex]
 
-  // Why: capture-and-restore (not force false) so re-entrant navigation
-  // (e.g. a store subscriber synchronously triggers another goBack) does
-  // not race on the boolean — the outer call's `finally` restores its own
-  // prior value rather than clobbering state set by an inner call.
+  // Why: capture-and-restore (not force false) so re-entrant navigation doesn't clobber the flag.
   const prevNavigating = get().isNavigatingHistory
   set({ isNavigatingHistory: true } as Partial<AppState>)
   try {
     if (isViewEntry(targetEntry)) {
       if (!viewActivator) {
-        // Why: a silent no-op would mean the back/forward chord lands on a
-        // page history entry and appears broken. See setWorktreeNavActivator
-        // rationale above.
+        // Why: warn (not a silent no-op) so a page-entry chord isn't a broken-looking no-op.
         console.warn(
           `go${direction === 'back' ? 'Back' : 'Forward'}Worktree: view activator not registered`
         )
         return
       }
-      // Why: dispatch via setActiveView (installed as viewActivator) rather
-      // than open*Page so we don't mutate previousViewBefore* or fire
-      // page-open side effects during replay. activateAndRevealWorktree on the
-      // other branch already switches activeView back to 'terminal'.
+      // Why: use setActiveView (not open*Page) so replay doesn't mutate previousViewBefore* or fire page-open side effects.
       viewActivator(targetEntry)
       set({ worktreeNavHistoryIndex: targetIndex } as Partial<AppState>)
     } else {
       if (!activator) {
-        // Why: a silent no-op here would mean the back/forward chord simply
-        // does nothing with no diagnostic. The activator is registered at
-        // module init by worktree-activation.ts, so a missing activator means
-        // either test setup forgot to install one or the production import
-        // graph regressed.
+        // Why: warn (not a silent no-op) so a missing activator is diagnosable.
         console.warn(
           `go${direction === 'back' ? 'Back' : 'Forward'}Worktree called before worktree activator was registered`
         )
         return
       }
-      // Why: activateAndRevealWorktree returns `ActivateAndRevealResult | false`;
-      // `false` is the only observable failure signal. Advance the index only on
-      // success so the slice stays consistent with what the user actually sees.
+      // Why: `false` is the activator's only failure signal — advance the index only on success.
       const result = activator(targetEntry)
       if (result !== false) {
         set({ worktreeNavHistoryIndex: targetIndex } as Partial<AppState>)
diff --git a/src/renderer/src/store/slices/worktrees.test.ts b/src/renderer/src/store/slices/worktrees.test.ts
index bb120d973db..2bc6fa59b7d 100644
--- a/src/renderer/src/store/slices/worktrees.test.ts
+++ b/src/renderer/src/store/slices/worktrees.test.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines --
- * Why: this slice test keeps the worktree store scenarios in one file so the
- * shared mock store setup stays consistent across closely related behaviors.
- */
+/* eslint-disable max-lines -- keeps all worktree-slice test scenarios in one file for a consistent shared mock store setup. */
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { create } from 'zustand'
 import type { AppState } from '../types'
@@ -127,8 +124,7 @@ function createTestStore() {
   return create<AppState>()(
     (...a) =>
       ({
-        // Why: this test isolates the worktree slice, so it only provides the
-        // state surface that `createWorktreeSlice` reads and writes.
+        // Why: this test isolates the worktree slice, so it provides only the state surface createWorktreeSlice touches.
         ...createWorktreeSlice(...a),
         trustedOrcaHooks: {},
         repos: [],
@@ -419,8 +415,7 @@ describe('fetchWorktrees', () => {
       linkedPR: 101,
       pushTarget: { remoteName: 'origin', branchName: 'feature-one' }
     })
-    // Persisted metadata still carries the stale link when the listing refresh
-    // is the first path to observe the terminal branch switch.
+    // Persisted metadata still carries the stale link when the listing refresh first observes the terminal branch switch.
     const refreshed = makeWorktree({
       id: 'repo1::/path/wt1',
       repoId: 'repo1',
@@ -1256,8 +1251,7 @@ describe('fetchWorktrees', () => {
 
     expect(mockApi.worktrees.listDetected).toHaveBeenCalledWith({ repoId: 'repo-ssh' })
     expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
-    // Why: SSH worktrees are fetched via local IPC but belong to the SSH host;
-    // they must carry the repo's ssh host id, not the local default.
+    // Why: SSH worktrees are fetched via local IPC but belong to the SSH host, so they carry the repo's ssh host id.
     expect(store.getState().worktreesByRepo['repo-ssh']).toEqual([
       { ...sshWorktree, hostId: 'ssh:ssh-1' }
     ])
@@ -1265,8 +1259,7 @@ describe('fetchWorktrees', () => {
 
   it('stamps remote runtime worktrees with the owning repo runtime host', async () => {
     const store = createTestStore()
-    // Why: a remote runtime returns its worktrees from its own perspective, so
-    // their hostId arrives as the default "local" even though they live remotely.
+    // Why: a remote runtime returns worktrees from its own perspective, so their hostId arrives as the default "local".
     const remote = makeWorktree({
       id: 'repo-remote::/remote/wt1',
       repoId: 'repo-remote',
@@ -1816,8 +1809,7 @@ describe('worktree lineage state', () => {
       repoId: 'repo-remote',
       path: '/remote/child'
     })
-    // Why: the remote returns the updated worktree from its own perspective, so
-    // it arrives with the default local host even though the repo is remote.
+    // Why: the remote returns the updated worktree from its own perspective, so it arrives with the default local host.
     const updatedChild = { ...child, hostId: 'local' as const, lineage }
     store.setState({
       repos: [
@@ -2965,8 +2957,7 @@ describe('createWorktree base status merge', () => {
       id: 'repo-remote::/remote/feature',
       repoId: 'repo-remote',
       path: '/remote/feature',
-      // Why: the remote creates the worktree and reports it from its own
-      // perspective, so it comes back with the default local host.
+      // Why: the remote reports the worktree from its own perspective, so it comes back with the default local host.
       hostId: 'local'
     })
     store.setState({
@@ -3139,8 +3130,7 @@ describe('createWorktree base status merge', () => {
 
     await store.getState().createWorktree('repo1', 'feature', 'origin/main')
 
-    // The button workflow (Keep main up to date / Settings link) lives in the
-    // toast component's own test; here we just assert the sticky nudge is raised.
+    // Button workflow is tested in the toast component; here we just assert the sticky nudge is raised.
     expect(toast.info).toHaveBeenCalledWith(
       'Local main is behind origin/main',
       expect.objectContaining({
@@ -3194,8 +3184,7 @@ describe('createWorktree base status merge', () => {
     const options = vi.mocked(toast.info).mock.calls.at(-1)?.[1] as unknown as {
       onDismiss: () => void
     }
-    // The Turn On success path dismisses the toast, which fires onDismiss; that
-    // must not be recorded as a decline now that the feature is enabled.
+    // Turn On dismisses the toast (firing onDismiss); that must not be recorded as a decline.
     options.onDismiss()
     await Promise.resolve()
 
@@ -3436,8 +3425,7 @@ describe('removeWorktree state cleanup', () => {
         [removed.id]: [makeTerminalTab({ id: 'removed-tab', worktreeId: removed.id })],
         [surviving.id]: [makeTerminalTab({ id: 'surviving-tab', worktreeId: surviving.id })]
       },
-      // Split panes write these even when false; only closeTab deleted them
-      // before, so removeWorktree used to strand them for the whole session.
+      // Split panes write these even when false; removeWorktree used to strand them (only closeTab deleted them).
       expandedPaneByTabId: { 'removed-tab': true, 'surviving-tab': false },
       canExpandPaneByTabId: { 'removed-tab': false, 'surviving-tab': true }
     } as unknown as Partial<AppState>)
@@ -3721,8 +3709,7 @@ describe('removeWorktree state cleanup', () => {
       globalWithDocument.document = originalDocument
     }
 
-    // The anchor must be captured while the row still exists so the post-delete
-    // restore pins the pre-removal position instead of the already-shifted list.
+    // The anchor must be captured while the row still exists so restore pins the pre-removal position.
     expect(worktreePresentWhenRecorded).toBe(true)
     expect(store.getState().worktreesByRepo.repo1).toEqual([])
   })
@@ -3930,12 +3917,7 @@ describe('removeWorktree state cleanup', () => {
   })
 
   it('clears recentlyClosedBrowserTabsByWorktree for the removed worktree', async () => {
-    // Why: closeBrowserTab (which shutdownWorktreeBrowsers delegates to) pushes
-    // each closed workspace into recentlyClosedBrowserTabsByWorktree for the
-    // Cmd+Shift+T undo path. When the owning worktree is deleted those
-    // snapshots reference entities that can never be restored — removeWorktree
-    // must clear the worktree key symmetrically with browserTabsByWorktree
-    // (design §1.1).
+    // Why: undo snapshots for a deleted worktree can never be restored, so removeWorktree clears the key (design §1.1).
     const store = createTestStore()
     const wt = makeWorktree({ id: 'repo1::/path/wt1', repoId: 'repo1', path: '/path/wt1' })
 
@@ -5562,10 +5544,7 @@ describe('worktree remote runtime mutations', () => {
   })
 })
 
-// Why: ghostty "show until interact" model — BEL must raise the sidebar dot
-// even on the active worktree, and only clearWorktreeUnread (called from the
-// terminal pane on keystroke / pointerdown) dismisses it. Pins both halves
-// of that contract.
+// Why: ghostty "show until interact" — BEL raises the dot even on the active worktree; only clearWorktreeUnread clears it.
 describe('worktree unread (show-until-interact)', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -5679,12 +5658,7 @@ describe('worktree unread (show-until-interact)', () => {
   })
 })
 
-// Why: design §4.4 — the hydration-time purge must be gated behind a
-// per-repo success check (F1 regression) so a transient git error on one
-// repo cannot silently wipe every persisted tabsByWorktree entry for that
-// repo. An empty-but-successful fetch from a newly-cloned sibling repo is
-// also unsafe to treat as authoritative on its own. Pins both halves of
-// that contract plus the happy-path purge.
+// Why: design §4.4 — hydration purge gated on per-repo success (F1 regression) so a git error can't wipe tabsByWorktree.
 describe('fetchAllWorktrees hydration-time purge (design §4.4)', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -5711,8 +5685,7 @@ describe('fetchAllWorktrees hydration-time purge (design §4.4)', () => {
     const wtA = makeWorktree({ id: 'repoA::/a/wt1', repoId: 'repoA', path: '/a/wt1' })
     const wtB = makeWorktree({ id: 'repoB::/b/wt1', repoId: 'repoB', path: '/b/wt1' })
 
-    // Stub: repoA succeeds; repoB throws. Stale tabsByWorktree entry for
-    // repoA::/a/stale must NOT be purged while any repo fetch is degraded.
+    // repoA succeeds, repoB throws; a stale tabsByWorktree entry must NOT be purged while any repo fetch is degraded.
     mockApi.worktrees.list.mockImplementation(async ({ repoId }: { repoId: string }) => {
       if (repoId === 'repoA') {
         return [wtA]
@@ -5756,9 +5729,7 @@ describe('fetchAllWorktrees hydration-time purge (design §4.4)', () => {
   it('defers the purge when every repo succeeds but none returns worktrees (empty-sibling safety)', async () => {
     const store = createTestStore()
 
-    // Both repos succeed but legitimately return empty (newly-cloned). The
-    // union of valid ids would be empty — declaring that authoritative
-    // would wipe every persisted tabsByWorktree entry. Must defer instead.
+    // Empty valid-id union (both repos newly-cloned, empty) isn't authoritative — defer instead of wiping tabsByWorktree.
     mockApi.worktrees.list.mockResolvedValue([])
 
     store.setState({
@@ -5906,10 +5877,7 @@ describe('fetchAllWorktrees hydration-time purge (design §4.4)', () => {
     })
   })
 
-  // Why: multi-host regression — once hydration has fired, a mid-session
-  // fetchAllWorktrees (e.g. triggered by switching focus) must NEVER purge
-  // terminal state, even if a host transiently reports zero worktrees. The
-  // hydration-time purge is the only purge path here; it is gated to boot.
+  // Why: multi-host regression — after hydration a mid-session fetch must never purge, even if a host reports zero worktrees.
   it('does not purge another host tab state when hasHydratedWorktreePurge is already true and a host reports zero worktrees', async () => {
     const store = createTestStore()
     const wtA = makeWorktree({ id: 'repoA::/a/wt1', repoId: 'repoA', path: '/a/wt1' })
@@ -6141,10 +6109,7 @@ describe('fetchAllWorktrees hydration-time purge (design §4.4)', () => {
   })
 
   it('does not coalesce a foreground re-probe onto a background reuse:true scan for a remote repo', async () => {
-    // Why: the reuse flag is part of the coalescing key for remote targets, so a
-    // foreground fetchWorktrees (reuse:false) must run its own compat-preflighted
-    // scan instead of sharing a background reuse:true scan that may have reused a
-    // stale failure — the foreground caller must always re-probe.
+    // Why: reuse is part of the coalescing key, so a foreground reuse:false scan must re-probe, not reuse a stale background failure.
     const store = createTestStore()
     const remote = makeWorktree({ id: 'repo1::/remote/wt', repoId: 'repo1', path: '/remote/wt' })
     store.setState({
@@ -6307,12 +6272,7 @@ describe('fetchAllWorktrees hydration-time purge (design §4.4)', () => {
   })
 })
 
-// Why: design §4.4 — purgeWorktreeTerminalState wipes every worktree-scoped
-// map symmetrically so a single removed-worktree event cannot leave
-// per-worktree entries stranded. The full cascade is already covered by
-// removeWorktree tests above; this block exercises the action directly to
-// confirm cross-map coverage (worktree key, tab id, file id, and top-level
-// actives).
+// Why: design §4.4 — purgeWorktreeTerminalState wipes every worktree-scoped map symmetrically so no entry is stranded.
 describe('purgeWorktreeTerminalState direct (design §4.4)', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -6818,8 +6778,7 @@ describe('setWorktreesPinnedAndReveal', () => {
     // Only the focused row is revealed, not the first-changed one.
     expect(reveal).toHaveBeenCalledTimes(1)
     expect(reveal).toHaveBeenCalledWith(focused.id, { behavior: 'smooth', highlight: true })
-    // Every targeted row is pinned, not just the revealed one, and the
-    // already-pinned row is left untouched.
+    // Every targeted row is pinned, not just the revealed one; the already-pinned row is untouched.
     expect(store.getState().worktreesByRepo.repo1[0].isPinned).toBe(true)
     expect(store.getState().worktreesByRepo.repo1[1].isPinned).toBe(true)
     expect(store.getState().worktreesByRepo.repo1[2].isPinned).toBe(true)
@@ -6957,8 +6916,7 @@ describe('migrateWorktreeIdentity', () => {
     expect(s.defaultTerminalTabsAppliedByWorktreeId[NEW]).toBe(true)
     // The two maps absent from the purge list are still re-keyed.
     expect(s.recentlyClosedEditorTabsByWorktree[NEW]).toEqual([{ id: 'f1', worktreeId: NEW }])
-    // Terminal reopen snapshots re-key AND remap startupCwd under the old
-    // worktree path; paths outside the renamed folder stay as-is.
+    // Terminal reopen snapshots re-key and remap startupCwd under the old path; outside paths stay as-is.
     expect(s.recentlyClosedTerminalTabsByWorktree[OLD]).toBeUndefined()
     expect(s.recentlyClosedTerminalTabsByWorktree[NEW]).toEqual([
       { startupCwd: '/ws/worktree-creation-spinner/packages/app' },
diff --git a/src/renderer/src/store/slices/worktrees.ts b/src/renderer/src/store/slices/worktrees.ts
index 298a18c965c..31b3542e1ae 100644
--- a/src/renderer/src/store/slices/worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees.ts
@@ -95,17 +95,14 @@ import {
 } from '../../../../shared/worktree-removal'
 export type { WorktreeSlice, WorktreeDeleteState } from './worktree-helpers'
 
-// Why: old runtime servers only have `worktree.list`; preserve the large-list
-// UI hydration parity this slice used before `worktree.detectedList` existed.
+// Why: old runtime servers only have `worktree.list`; preserve the large-list UI hydration parity used before `worktree.detectedList` existed.
 const REMOTE_WORKTREE_LIST_PARITY_LIMIT = 10_000
 const WORKTREE_REMOVAL_AMBIGUOUS_ERROR =
   'Workspace identity is ambiguous across hosts. Refresh projects and try again.'
 const ACTIVE_WORKTREE_TERMINAL_PREP_DELAY_MS = 300
 const ACTIVE_WORKTREE_TERMINAL_PREP_INPUT_QUIET_MS = 450
 const ACTIVE_WORKTREE_TERMINAL_PREP_IDLE_TIMEOUT_MS = 180
-// Why: each repo's `git worktree list` is an independent main-process child, so
-// a higher ceiling cuts startup scan batches (#7225) while staying bounded so
-// one UI moment can't launch every git probe at once.
+// Why: each repo's `git worktree list` is an independent main-process child; a higher ceiling cuts startup scan batches (#7225) while staying bounded against launching every git probe at once.
 export const WORKTREE_REFRESH_CONCURRENCY = 8
 const pendingActivationTerminalPrepCancels = new Map<string, () => void>()
 const detachedHeadAutoDerivedDisplayNames = new Map<string, string>()
@@ -125,8 +122,7 @@ async function mapReposForWorktreeRefresh<TRepo extends { id: string }, TResult>
   let nextIndex = 0
   const workerCount = Math.min(WORKTREE_REFRESH_CONCURRENCY, repos.length)
 
-  // Why: worktree refresh can be triggered during activation/startup. Keeping
-  // repo scans bounded avoids one UI moment launching every git probe at once.
+  // Why: refresh can fire during activation/startup; bound repo scans so one UI moment can't launch every git probe at once.
   await Promise.all(
     Array.from({ length: workerCount }, async () => {
       while (nextIndex < repos.length) {
@@ -335,11 +331,8 @@ function toVisibleWorktree(worktree: DetectedWorktreeListResult['worktrees'][num
   return base
 }
 
-// Why: runtime worktree payloads arrive from the owning host's own perspective,
-// so their hostId defaults to "local" even for remote checkouts. Re-stamp them
-// with the repo's execution host so per-worktree host resolution doesn't route
-// remote terminals to the local machine. Local-owned repos are left untouched,
-// so an explicit local worktree still overrides a runtime repo owner.
+// Why: runtime worktree payloads report hostId "local" (owning host's own perspective) even for remote checkouts; re-stamp with the repo's execution host so remote terminals don't route locally.
+// Local-owned repos stay untouched, so an explicit local worktree still overrides a runtime repo owner.
 function withRepoHostOwnership<
   T extends { hostId?: ExecutionHostId; projectId?: string; projectHostSetupId?: string }
 >(worktree: T, hostId: ExecutionHostId, setup?: ProjectHostSetup): T {
@@ -377,8 +370,7 @@ function repoHasExecutionHost(
   ownerWasMissingAtStart: boolean
 ): boolean {
   const repoOwners = state.repos.filter((repo) => repo.id === repoId)
-  // Why: worktrees can load before the repo catalog during startup; only reject
-  // a missing owner when this request previously observed an owned repo.
+  // Why: worktrees can load before the repo catalog at startup; only reject a missing owner when this request previously observed an owned repo.
   return (
     (repoOwners.length === 0 && ownerWasMissingAtStart) ||
     repoOwners.some((repo) => getRepoExecutionHostId(repo) === hostId)
@@ -459,8 +451,7 @@ function worktreeHostMatchOptions(
   hostId: ExecutionHostId
 ): WorktreeHostMatchOptions {
   return {
-    // Why: pre-host persisted runtime/SSH worktrees were stored without hostId.
-    // Treat them as the sole repo owner's rows, but keep ambiguous duplicates local.
+    // Why: pre-host persisted runtime/SSH worktrees lack hostId; treat them as the sole repo owner's rows but keep ambiguous duplicates local.
     unhostedWorktreesMatchHost: unhostedWorktreesMatchRefreshHost(state, repoId, hostId)
   }
 }
@@ -482,8 +473,7 @@ function mergeWorktreesForHost<T extends { hostId?: ExecutionHostId }>(
   hostId: ExecutionHostId,
   options?: WorktreeHostMatchOptions
 ): T[] {
-  // Why: host-scoped refreshes should replace that host in place so alternating
-  // local/runtime refreshes do not churn sibling row order or sortEpoch.
+  // Why: host-scoped refreshes replace that host in place so alternating local/runtime refreshes don't churn sibling row order or sortEpoch.
   const existing = current ?? []
   const next: T[] = []
   let inserted = false
@@ -541,8 +531,7 @@ function getKnownWorktreeIdsForPurge(
     }
   }
   if (!state.hasHydratedWorktreePurge && matchOptions.unhostedWorktreesMatchHost === true) {
-    // Why (#1158): hydration can preserve tab keys before worktree metadata exists;
-    // the first authoritative scan still needs to reap deleted session-only keys.
+    // Why (#1158): hydration can preserve tab keys before worktree metadata exists; the first authoritative scan must still reap deleted session-only keys.
     for (const id of getHydratedSessionWorktreeIdsForRepo(state, repoId)) {
       knownIds.add(id)
     }
@@ -584,10 +573,7 @@ function isRuntimeMethodNotFoundError(error: unknown): boolean {
   return error instanceof RuntimeRpcCallError && error.code === 'method_not_found'
 }
 
-// Why: a mobile-scope web pairing is denied worktree/repo RPCs, which would
-// otherwise be swallowed into empty workspaces on every repo. Surface one
-// deduped, actionable toast (stable id) instead of spamming per-repo, steering
-// the user to re-pair via the full-access browser link.
+// Why: a mobile-scope web pairing is denied worktree/repo RPCs (else silently empty workspaces); surface one deduped toast (stable id) instead of spamming per-repo.
 const RUNTIME_SCOPE_FORBIDDEN_TOAST_ID = 'runtime-scope-forbidden'
 
 function notifyRuntimeScopeForbiddenIfNeeded(error: unknown): boolean {
@@ -836,8 +822,7 @@ function settingsForKnownRepoOwner(
   if (parsed?.kind !== 'ssh') {
     return settings
   }
-  // Why: SSH repos are owned by the desktop client/SSH provider, not the
-  // currently focused runtime server.
+  // Why: SSH repos are owned by the desktop client/SSH provider, not the focused runtime server.
   return settings
     ? { ...settings, activeRuntimeEnvironmentId: null }
     : ({ activeRuntimeEnvironmentId: null } as AppState['settings'])
@@ -939,10 +924,7 @@ function detectedWorktreeRefreshKey(
     targetKey,
     options.requireAuthoritative === true ? 'authoritative' : 'best-effort'
   ]
-  // Why: only remote targets run a compat preflight, so a foreground (reuse:false)
-  // refresh must not coalesce onto a background reuse:true scan that reused a
-  // stale failure — it must re-probe. Local targets have no preflight; keep them
-  // coalesced so a foreground/background collision stays one git scan.
+  // Why: only remote targets run a compat preflight, so a foreground (reuse:false) refresh must re-probe not coalesce onto a stale-failure background scan; local targets have no preflight and stay coalesced.
   if (target.kind === 'environment') {
     parts.push(options.reuseRecentCompatibilityFailure === true ? 'reuse-failure' : 'reprobe')
   }
@@ -963,8 +945,7 @@ async function listDetectedWorktreesForRepoCoalesced(
   if (existing) {
     return existing
   }
-  // Why: startup/event fan-out can ask for the same repo/host refresh many
-  // times at once; share only the scan promise so state merge semantics stay local.
+  // Why: startup/event fan-out can request the same repo/host refresh many times at once; share only the scan promise so state-merge semantics stay local.
   const refresh = listDetectedWorktreesForRepo(settings, repoId, {
     reuseRecentCompatibilityFailure: options.reuseRecentCompatibilityFailure
   })
@@ -1153,8 +1134,7 @@ async function refreshRemoteWorktreeLineageBestEffort(
       )
     }))
   } catch (err) {
-    // Why: lineage is supplemental to the worktree list. A remote timeout here
-    // must not discard a successful worktree refresh.
+    // Why: lineage is supplemental, so a remote timeout here must not discard a successful worktree refresh.
     console.error('Failed to fetch worktree lineage:', err)
   }
 }
@@ -1276,9 +1256,7 @@ async function persistWorktreeMeta(
   )
 }
 
-// Why: an SSH-mode per-workspace-env registers a project whose host is the runtime-owned SSH
-// target. Once that runtime is destroyed the project points at a host that no longer exists, so it
-// must be removed — otherwise it lingers as a dead, never-connectable project in the composer.
+// Why: an SSH per-workspace-env project's host is the runtime-owned SSH target; once that runtime is destroyed, remove the project or it lingers as a dead, never-connectable one.
 async function purgeOrphanedRuntimeSshProjects(
   get: () => AppState,
   destroyedSshTargetIds: string[]
@@ -1304,8 +1282,7 @@ async function purgeOrphanedRuntimeSshProjects(
       console.error('Failed to purge orphaned per-workspace-env project:', error)
     }
   }
-  // A repo whose only host was the destroyed runtime can outlive its setup (the setup may be pruned
-  // by a projection refresh first). Remove it directly so no dead, never-connectable project lingers.
+  // A repo whose only host was the destroyed runtime can outlive its setup (pruned first by a projection refresh); remove it directly so no dead project lingers.
   const orphanedRepoIds = get()
     .repos.filter(
       (repo) => destroyedTargetIds.has(repo.connectionId ?? '') && !purgedRepoIds.has(repo.id)
@@ -1698,8 +1675,7 @@ function clearOlderHostedReviewLinksForReplacement(
     if (key === replacementKey || existingWorktree[key] == null) {
       continue
     }
-    // Why: one branch can only push to one hosted-review head; keeping older
-    // provider links lets stale metadata win the target lookup after replacement.
+    // Why: one branch pushes to one hosted-review head; stale provider links would win the target lookup after replacement.
     normalized = normalized === updates ? { ...updates } : normalized
     normalized[key] = null
   }
@@ -1732,15 +1708,12 @@ function encodePushTargetClearForRuntimeRpc(
   if (!hasExplicitPushTargetClear(updates)) {
     return updates
   }
-  // Why: remote runtime RPC is JSON-shaped and drops undefined fields, so use
-  // null as the wire-only signal for clearing persisted pushTarget metadata.
+  // Why: remote runtime RPC is JSON-shaped and drops undefined, so null is the wire signal for clearing persisted pushTarget metadata.
   return { ...updates, pushTarget: null }
 }
 
-// Every worktree-id-keyed store map the rename path re-keys on a folder move, so a
-// new `*ByWorktree` map is not silently missed when a worktree id changes. Maps keyed
-// by tab id or file id are deliberately NOT here — tabs and files keep their ids across
-// a worktree rename.
+// Every worktree-id-keyed store map the rename path re-keys, so a new `*ByWorktree` map isn't silently missed.
+// Tab-id/file-id-keyed maps are deliberately excluded: tabs and files keep their ids across a rename.
 const WORKTREE_ID_KEYED_MAP_KEYS = [
   'worktreeLineageById',
   'tabsByWorktree',
@@ -1779,14 +1752,9 @@ const WORKTREE_ID_KEYED_MAP_KEYS = [
 ] as const satisfies readonly (keyof AppState)[]
 
 /**
- * Re-key every worktree-id-keyed map (plus the Set, openFiles[].worktreeId, and
- * the active/renaming pointers) from `oldWorktreeId` to `newWorktreeId` after a
- * folder rename changed the worktree's path-derived id. Tab-id/file-id-keyed maps
- * and the activeFile/activeTab/activeBrowserTab pointers are untouched because
- * tabs and files keep their ids. No-op when nothing references the old id.
- *
- * Main-process counterpart: `Store.migrateWorktreeIdentity` in persistence.ts
- * re-keys the persisted worktree state for the same id change.
+ * Re-key every worktree-id-keyed map from `oldWorktreeId` to `newWorktreeId` after a folder
+ * rename. Tab-id/file-id-keyed maps and active/renaming pointers stay put since tabs/files keep their ids.
+ * Main-process counterpart: `Store.migrateWorktreeIdentity` in persistence.ts.
  */
 function buildWorktreeRenameState(
   s: AppState,
@@ -1834,16 +1802,11 @@ function buildWorktreeRenameState(
   for (const key of WORKTREE_ID_KEYED_MAP_KEYS) {
     renameKey(key, renameValueByKey[key] as ((value: unknown) => unknown) | undefined)
   }
-  // Re-key these on rename so a renamed worktree keeps its editor-undo + push/pull
-  // state. (Both removal paths — buildWorktreePurgeState and the single
-  // removeWorktree reducer — now also purge them on removal.)
+  // Re-key on rename so a renamed worktree keeps its editor-undo + push/pull state.
   renameKey('recentlyClosedEditorTabsByWorktree', (files: { worktreeId: string }[]) =>
     files.map(withNewWorktreeId)
   )
-  // Why: terminal reopen snapshots carry absolute startupCwd paths under the
-  // old worktree folder; remap them or Cmd+Shift+T respawns into a directory
-  // that no longer exists after the rename. Paths outside the renamed folder
-  // are untouched by the move and stay valid as-is.
+  // Why: terminal reopen snapshots hold absolute startupCwd paths under the old folder; remap or Cmd+Shift+T respawns into a directory that no longer exists after the rename.
   const oldWorktreePath = splitWorktreeIdForFilesystem(oldWorktreeId)?.worktreePath
   const newWorktreePath = splitWorktreeIdForFilesystem(newWorktreeId)?.worktreePath
   renameKey('recentlyClosedTerminalTabsByWorktree', (snapshots: ClosedTerminalTabSnapshot[]) =>
@@ -1931,14 +1894,12 @@ function buildWorktreeRenameState(
 function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<AppState> {
   const worktreeIdSet = new Set(worktreeIds)
   pruneHostedReviewLinkMutationGenerations(worktreeIdSet)
-  // Why: every authoritative and explicit purge converges here, including
-  // fetchAllWorktrees; centralizing prevents a deleted path inheriting UI state.
+  // Why: every authoritative and explicit purge converges here, so a deleted path can't inherit stale UI state.
   forgetHugeRepoWarningDismissalsForWorktrees(worktreeIdSet)
 
   // Collect every tab id (and removed file id) we are about to orphan.
   const doomedTabIds = new Set<string>()
-  // Why: some terminal/agent maps are keyed by ptyId, not tabId. Collect every
-  // durable wake hint too, because slept panes have already left the live index.
+  // Why: some terminal/agent maps are keyed by ptyId, not tabId; collect durable wake hints too since slept panes have left the live index.
   const doomedPtyIds = new Set<string>()
   const addDoomedPtyId = (ptyId: string | null | undefined): void => {
     if (!ptyId) {
@@ -1962,29 +1923,21 @@ function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<Ap
   for (const id of worktreeIdSet) {
     for (const tab of s.tabsByWorktree[id] ?? []) {
       doomedTabIds.add(tab.id)
-      // Null-tolerant like the omit* helpers below: some callers pass partial
-      // state that omits this slice; the production store always inits it to {}.
+      // Null-tolerant like the omit* helpers below: some callers pass partial state omitting this slice (production store always inits to {}).
       addDoomedTabPtyIds(tab.id, tab.ptyId)
-      // Why: a removed worktree's panes are gone for good, so drop their
-      // hibernation output epochs from that module-level map (mirrors the
-      // hosted-review prune above). A future pane mints a fresh leafId at epoch 0.
+      // Why: a removed worktree's panes are gone, so drop their hibernation output epochs from the module-level map (a future pane mints a fresh leafId at epoch 0).
       forgetAgentHibernationTabOutput(tab.id)
     }
     for (const workspace of s.browserTabsByWorktree[id] ?? []) {
       doomedBrowserWorkspaceIds.add(workspace.id)
     }
-    // Why: drop this worktree's auto-derived detached-HEAD display name so the
-    // module-level map doesn't retain removed worktrees for the whole session.
+    // Why: drop the auto-derived detached-HEAD display name so the module-level map doesn't retain removed worktrees for the session.
     detachedHeadAutoDerivedDisplayNames.delete(id)
   }
-  // Why: same rationale for the doomed tabs' foreground last-seen timestamps and
-  // consumed agent-startup delivery guards — retired tab ids never recur.
+  // Why: same rationale for doomed tabs' foreground last-seen timestamps and agent-startup delivery guards — retired tab ids never recur.
   forgetForegroundTerminalTabs(doomedTabIds)
   forgetAgentStartupDeliveriesForTabs(doomedTabIds)
-  // Why: the per-page browser maps are keyed by page id, not worktree/workspace id.
-  // Collect every page owned by a doomed workspace so this bulk purge can evict
-  // them. (The single removeWorktree path clears these via closeBrowserTab, but the
-  // authoritative-scan reconcile that also reaches this reducer does not.)
+  // Why: per-page browser maps are keyed by page id, so collect every page of a doomed workspace to evict here (the authoritative-scan reconcile skips closeBrowserTab's cleanup).
   for (const workspaceId of doomedBrowserWorkspaceIds) {
     for (const page of s.browserPagesByWorkspace[workspaceId] ?? []) {
       doomedPageIds.add(page.id)
@@ -2066,11 +2019,9 @@ function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<Ap
     }
     return changed ? out : obj
   }
-  // Pane-scoped maps are keyed by `${tabId}:${leafId}` (stable-pane-id); tabId
-  // never contains ":", so the segment before the first ":" is the owning tab.
+  // Pane-scoped maps are keyed `${tabId}:${leafId}`; tabId never contains ":", so the prefix before the first ":" is the owning tab.
   const omitByPaneKeyTabPrefix = <T>(obj: Record<string, T>): Record<string, T> => {
-    // Null-tolerant like omitByTabId: some worktree-isolation callers omit these
-    // slices entirely, and the production store always initializes them to {}.
+    // Null-tolerant like omitByTabId: some worktree-isolation callers omit these slices (production store always inits to {}).
     if (!obj) {
       return obj
     }
@@ -2156,18 +2107,10 @@ function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<Ap
     runtimePaneTitlesByTabId: omitByTabId(s.runtimePaneTitlesByTabId),
     automaticAgentResumeClaimsByTabId: omitByTabId(s.automaticAgentResumeClaimsByTabId),
     nativeChatLaunchPromptByTabId: omitByTabId(s.nativeChatLaunchPromptByTabId),
-    // Why: bulk/hydration purge must drop the per-tab pane-expand flags too;
-    // this path never runs terminal teardown, so nothing else evicts them.
+    // Why: bulk/hydration purge runs no terminal teardown, so it must drop the per-tab pane-expand flags itself.
     expandedPaneByTabId: omitByTabId(s.expandedPaneByTabId),
     canExpandPaneByTabId: omitByTabId(s.canExpandPaneByTabId),
-    // Why: these per-tab / per-pty terminal+agent maps are evicted on the single
-    // removeWorktree path (via closeTab / shutdownWorktreeTerminals) but this bulk
-    // reconcile / remove-project / hydration-stale path runs no terminal teardown,
-    // so without these lines each one strands an entry per tab/pane of every
-    // externally-removed worktree for the renderer's whole session. lastKnownRelay
-    // and the two ptyId maps retain an entry for a live pane's entire lifetime
-    // (highest value); the pending* one-shots are consumed at pane mount so usually
-    // already empty at removal, but strand when a tab's pane never mounted.
+    // Why: these per-tab/per-pty terminal+agent maps evict on the single removeWorktree teardown path; the bulk reconcile / remove-project / hydration-stale paths run no teardown, so without these each strands an entry per tab/pane of externally-removed worktrees.
     lastKnownRelayPtyIdByTabId: omitByTabId(s.lastKnownRelayPtyIdByTabId),
     pendingInitialCwdByTabId: omitByTabId(s.pendingInitialCwdByTabId),
     pendingIssueCommandSplitByTabId: omitByTabId(s.pendingIssueCommandSplitByTabId),
@@ -2177,16 +2120,8 @@ function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<Ap
     migrationUnsupportedByPtyId: omitByPtyId(s.migrationUnsupportedByPtyId),
     suppressedPtyExitIds: omitByPtyId(s.suppressedPtyExitIds),
     pendingCodexPaneRestartIds: omitByPtyId(s.pendingCodexPaneRestartIds),
-    // Why: these tab/pane-scoped agent-status, unread, and input maps are only
-    // cleared on the single removeWorktree path (via shutdownWorktreeTerminals /
-    // dropAgentStatusByWorktree / clearPaneForegroundAgentByWorktree, which read
-    // tabsByWorktree while it is still populated). The bulk reconcile / remove-
-    // project / hydration-stale paths that reach this reducer never run terminal
-    // teardown, so without this they orphan an entry per agent pane of every
-    // externally-removed worktree for the session (plus a phantom unread dock
-    // badge). retainedAgentsByPaneKey and runtimeAgentOrchestrationByPaneKey are
-    // intentionally omitted here — both self-heal (pruneRetainedAgents on a
-    // worktreesByRepo change; the runtime map is replaced wholesale each sync).
+    // Why: these agent-status/unread/input maps clear only on the single removeWorktree teardown path; the bulk reconcile / remove-project / hydration-stale paths run no teardown, so without this they orphan an entry per agent pane (plus a phantom unread badge).
+    // retainedAgentsByPaneKey and runtimeAgentOrchestrationByPaneKey are omitted here — both self-heal (pruneRetainedAgents on worktreesByRepo change; runtime map replaced wholesale each sync).
     agentStatusByPaneKey: nextAgentStatusByPaneKey,
     ...(nextAgentStatusByPaneKey !== s.agentStatusByPaneKey
       ? { agentStatusEpoch: s.agentStatusEpoch + 1 }
@@ -2210,10 +2145,7 @@ function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<Ap
     browserPagesByWorkspace: omitByBrowserWorkspaceId(s.browserPagesByWorkspace),
     recentlyClosedBrowserTabsByWorktree: omitByWorktree(s.recentlyClosedBrowserTabsByWorktree),
     activeBrowserTabIdByWorktree: omitByWorktree(s.activeBrowserTabIdByWorktree),
-    // Why: these browser maps are keyed by page/workspace id and were only cleaned
-    // on the single-worktree removal path (closeBrowserTab); this bulk reconcile path
-    // missed them, orphaning an annotation/handle/focus/closed-page entry per page of
-    // every externally-removed worktree for the session.
+    // Why: keyed by page/workspace id, only cleaned by closeBrowserTab on the single-removal path; the bulk reconcile missed them, orphaning an entry per page of externally-removed worktrees.
     browserAnnotationsByPageId: omitByPageId(s.browserAnnotationsByPageId),
     remoteBrowserPageHandlesByPageId: omitByPageId(s.remoteBrowserPageHandlesByPageId),
     pendingAddressBarFocusByPageId: omitByPageId(s.pendingAddressBarFocusByPageId),
@@ -2239,8 +2171,7 @@ function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<Ap
     activeGroupIdByWorktree: omitByWorktree(s.activeGroupIdByWorktree),
     // Git status caches
     gitStatusByWorktree: omitByWorktree(s.gitStatusByWorktree),
-    // Why: keyed by worktreeId; re-keyed on rename but missed by both removal
-    // paths, leaking an upstream-status entry per removed worktree.
+    // Why: keyed by worktreeId; re-keyed on rename but missed by both removal paths (upstream-status entry).
     remoteStatusesByWorktree: omitByWorktree(s.remoteStatusesByWorktree),
     gitStatusHeadByWorktree: omitByWorktree(s.gitStatusHeadByWorktree),
     gitIgnoredPathsByWorktree: omitByWorktree(s.gitIgnoredPathsByWorktree),
@@ -2252,8 +2183,7 @@ function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<Ap
     gitBranchCompareRequestStatusHeadByWorktree: omitByWorktree(
       s.gitBranchCompareRequestStatusHeadByWorktree
     ),
-    // Why: keyed by worktreeId; without this it leaks a huge-status marker per
-    // removed worktree for the rest of the session.
+    // Why: keyed by worktreeId; without this it leaks a huge-status marker per removed worktree.
     gitStatusHugeByWorktree: omitByWorktree(s.gitStatusHugeByWorktree),
     showDotfilesByWorktree: omitByWorktree(s.showDotfilesByWorktree),
     expandedDirs: omitByWorktree(s.expandedDirs),
@@ -2261,12 +2191,10 @@ function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<Ap
     editorDrafts: omitByFileId(s.editorDrafts),
     markdownViewMode: omitByFileId(s.markdownViewMode),
     markdownFrontmatterVisible: omitByFileId(s.markdownFrontmatterVisible),
-    // Why: keyed by fileId; the bulk reconcile path previously kept these,
-    // leaking a cursor-line / view-mode entry per file of every removed worktree.
+    // Why: keyed by fileId; the bulk reconcile path previously kept these, leaking a cursor-line / view-mode entry per removed file.
     editorCursorLine: omitByFileId(s.editorCursorLine),
     editorViewMode: omitByFileId(s.editorViewMode),
-    // Why: keyed by worktreeId; re-keyed on rename but missed by both removal
-    // paths, leaking the per-worktree editor-undo (Cmd/Ctrl+Shift+T) snapshots.
+    // Why: keyed by worktreeId; re-keyed on rename but missed by both removal paths (editor-undo / Cmd+Shift+T snapshots).
     recentlyClosedEditorTabsByWorktree: omitByWorktree(s.recentlyClosedEditorTabsByWorktree),
     recentlyClosedTerminalTabsByWorktree: omitByWorktree(s.recentlyClosedTerminalTabsByWorktree),
     recentlyClosedTabKindsByWorktree: omitByWorktree(s.recentlyClosedTabKindsByWorktree),
@@ -2274,8 +2202,7 @@ function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<Ap
     openFiles: nextOpenFiles,
     everActivatedWorktreeIds: nextEverActivatedWorktreeIds,
     lastVisitedAtByWorktreeId: omitByWorktree(s.lastVisitedAtByWorktreeId),
-    // Why: keyed by worktreeId; the write-once default-terminal idempotency guard
-    // was re-keyed on rename but missed by both removal paths.
+    // Why: keyed by worktreeId; re-keyed on rename but missed by both removal paths (write-once default-terminal guard).
     defaultTerminalTabsAppliedByWorktreeId: omitByWorktree(
       s.defaultTerminalTabsAppliedByWorktreeId
     ),
@@ -2329,8 +2256,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         if (!repoHasExecutionHost(s, repoId, hostId, ownerWasMissingAtStart)) {
           return s
         }
-        // Why: detected-only refreshes can overlap host-scoped visible refreshes;
-        // keep detected state stamped/merged so SSH/runtime rows are not clobbered.
+        // Why: detected-only refreshes can overlap host-scoped visible refreshes; merge detected state so SSH/runtime rows aren't clobbered.
         const mergedDetected = mergeDetectedWorktreesForHost(
           s.detectedWorktreesByRepo[repoId],
           result,
@@ -2436,13 +2362,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         return detected.authoritative
       }
 
-      // Why: `git worktree list` can fail transiently (e.g. concurrent git
-      // operations holding a lock, disk I/O hiccup). The backend catches these
-      // errors and returns []. Replacing a known-good worktree list with []
-      // causes tabsByWorktree entries to become orphaned — the agent activity
-      // badge then shows raw worktree IDs instead of display names, and click-
-      // to-navigate silently fails because findWorktreeById returns undefined.
-      // Keep the stale-but-correct data until the next successful refresh.
+      // Why: a transient `git worktree list` failure returns []; replacing a known-good list with [] orphans tabsByWorktree state, so keep stale-but-correct data until the next successful refresh.
       if (!detected.authoritative && worktrees.length === 0 && currentForHost.length > 0) {
         set((s) => {
           if (!repoHasExecutionHost(s, repoId, hostId, ownerWasMissingAtStart)) {
@@ -2468,9 +2388,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         if (!repoHasExecutionHost(s, repoId, hostId, ownerWasMissingAtStart)) {
           return s
         }
-        // Why: hidden worktrees are not in worktreesByRepo. Purge decisions
-        // must diff against the previous authoritative detected list so hiding
-        // does not delete state, and deleting a hidden worktree still does.
+        // Why: hidden worktrees aren't in worktreesByRepo; diff purges against the prior authoritative detected list so hiding keeps state but deleting a hidden worktree still purges.
         const matchOptions = worktreeHostMatchOptions(s, repoId, hostId)
         const removedIds = getRemovedWorktreeIdsAfterAuthoritativeScan(s, repoId, detected, hostId)
         const mergedWorktrees = mergeWorktreesForHost(
@@ -2488,9 +2406,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         )
 
         return {
-          // Why: active worktrees can change branches entirely from a terminal.
-          // We refresh that live git identity into renderer state, but only bump
-          // sortEpoch when git actually reports a different worktree payload.
+          // Why: a terminal can switch an active worktree's branch; refresh that live git identity but only bump sortEpoch when the payload actually changed.
           worktreesByRepo: { ...s.worktreesByRepo, [repoId]: mergedWorktrees },
           detectedWorktreesByRepo: { ...s.detectedWorktreesByRepo, [repoId]: mergedDetected },
           sortEpoch: s.sortEpoch + 1,
@@ -2511,9 +2427,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
   fetchAllWorktrees: async (options) => {
     const { repos } = get()
 
-    // Why: once the one-shot hydration-time purge has fired, subsequent
-    // calls just need to refresh each repo's cached list. No need to
-    // double-probe the IPC for the per-repo success signal.
+    // Why: after the one-shot hydration purge, later calls only refresh cached lists — no IPC double-probe for the per-repo success signal.
     if (get().hasHydratedWorktreePurge) {
       await mapReposForWorktreeRefresh(repos, async (r) => {
         try {
@@ -2591,17 +2505,8 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       return
     }
 
-    // Why: users upgrading from a pre-fix build may have persisted
-    // tabsByWorktree entries for worktrees that were deleted in the previous
-    // session. Without the hydration-time purge below those entries would
-    // keep zombie PTYs misclassified as "bound" in SessionsStatusSegment
-    // (design §2c), which means the user would still need a second restart
-    // post-upgrade to reclaim memory.
-    //
-    // Safety gate: fetchWorktrees swallows IPC errors and short-circuits on
-    // empty-replace when cached data exists. Neither signal bubbles up to the
-    // caller, so we probe the IPC directly to get the per-repo success signal,
-    // then apply that same payload to state instead of listing each repo again.
+    // Why: a pre-fix upgrade can persist tabsByWorktree entries for worktrees deleted last session; without this hydration purge they leave zombie PTYs misclassified as "bound" (design §2c) until a second restart.
+    // Safety gate: fetchWorktrees swallows IPC errors and short-circuits on empty-replace, so probe the IPC directly for the per-repo success signal instead of re-listing.
     const results = await mapReposForWorktreeRefresh(
       repos,
       async (
@@ -2706,18 +2611,13 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       get().workspaceSessionReady === false ||
       get().hydrationSucceeded === false
     ) {
-      // Why: startup first refreshes only local repos so the app can paint
-      // before remote runtime timeouts. Keep the one-shot purge available for
-      // the later all-host refresh, after a clean session hydrate and when
-      // remote worktree ids are known too.
+      // Why: startup refreshes local repos first; defer the one-shot purge to the later all-host refresh, once remote worktree ids are known.
       return
     }
     const validIds = new Set<string>()
-    // Why: floating is persisted renderer state, but not a repo worktree that
-    // authoritative runtime scans can return.
+    // Why: floating is persisted renderer state, not a repo worktree an authoritative scan returns.
     validIds.add(FLOATING_TERMINAL_WORKTREE_ID)
-    // Why: folder workspaces persist terminal tabs under `folder:<id>` keys,
-    // but authoritative repo scans can never return those synthetic ids.
+    // Why: folder workspaces persist tabs under `folder:<id>` keys that authoritative repo scans never return.
     for (const workspace of get().folderWorkspaces ?? []) {
       validIds.add(folderWorkspaceKey(workspace.id))
     }
@@ -2747,8 +2647,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
 
   fetchWorktreeLineage: async () => {
     try {
-      // Why: lineage is a focused-host refresh — fetch from the focused host and
-      // host-merge so other hosts' previously fetched lineage is preserved.
+      // Why: lineage is a focused-host refresh; host-merge so other hosts' fetched lineage is preserved.
       await refreshWorktreeLineageForSettings(get().settings, set, {
         reuseRecentCompatibilityFailure: true
       })
@@ -2845,8 +2744,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             }
           }
         }
-        // Why: terminal branch switches only patch branch/head here; auto-derived
-        // titles need the same branch derivation that full worktree listing uses.
+        // Why: terminal branch switches only patch branch/head here; re-derive auto titles like full listing does.
         const currentBranchName = branchName(worktree.branch)
         const wasAutoDerived = worktree.displayName === currentBranchName
         const wasDetachedAutoDerived =
@@ -2867,8 +2765,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           head: nextHead,
           branch: nextBranch,
           displayName: nextDisplayName,
-          // Why: linked reviews are branch-scoped hints. If a terminal switches
-          // branches, keeping the old exact link makes Checks refresh the old PR.
+          // Why: linked reviews are branch-scoped; keeping the old link on a branch switch would refresh the old PR.
           ...(shouldClearHostedReviewContext ? CLEARED_HOSTED_REVIEW_LINK_UPDATES : {})
         }
       })
@@ -2905,8 +2802,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             return
           }
           if (!hostedReviewLinksAreCleared(current as Worktree)) {
-            // Why: a worktree refetch can rehydrate stale linked-review metadata
-            // before this async clear starts; clear it again instead of bailing out.
+            // Why: a refetch can rehydrate stale linked-review metadata before this async clear starts; clear it again.
             applyHostedReviewLinkClear(set, currentWorktreeId)
             current = get().getKnownWorktreeById(currentWorktreeId)
             if (!current || current.branch !== clearedBranch) {
@@ -2922,8 +2818,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           if (migratedWorktreeId === currentWorktreeId) {
             break
           }
-          // Why: worktree creation can migrate ids while this IPC is in flight;
-          // persist the branch-scoped clear under the new durable id as well.
+          // Why: worktree creation can migrate ids mid-IPC; persist the clear under the new durable id too.
           currentWorktreeId = migratedWorktreeId
         }
         const latest = get().getKnownWorktreeById(currentWorktreeId)
@@ -2943,8 +2838,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           )
           return
         }
-        // Why: a worktree refetch can briefly rehydrate old metadata before
-        // the branch-switch clear reaches disk; do not write that stale link back.
+        // Why: a refetch can rehydrate old metadata before the branch-switch clear reaches disk; don't write the stale link back.
         applyHostedReviewLinkClear(set, currentWorktreeId)
       })
       .catch((err) => {
@@ -2993,8 +2887,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         { timeoutMs: 30_000 }
       )
     } catch {
-      // Why: prefetch is only a latency hedge. The create path awaits the same
-      // backend refresh and owns user-visible error reporting.
+      // Why: prefetch is only a latency hedge; the create path awaits the same refresh and owns error reporting.
     }
   },
 
@@ -3030,14 +2923,12 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     try {
       for (let attempt = 0; attempt < CLIENT_WORKTREE_CREATE_MAX_ATTEMPTS; attempt += 1) {
         const candidateName = getClientWorktreeCreateCandidate(name, attempt)
-        // Why: older runtimes may still reject exact PR branch overrides on
-        // collision, so the renderer retries both branch and worktree names.
+        // Why: older runtimes reject exact PR branch overrides on collision, so retry both branch and worktree names.
         const candidateBranchNameOverride = branchNameOverride
           ? getClientWorktreeCreateCandidate(branchNameOverride, attempt)
           : undefined
         try {
-          // Why: Manual sort is user-authored order. Stamp new workspaces
-          // deliberately at the top instead of relying on sortOrder fallback.
+          // Why: manual sort is user-authored order; stamp new workspaces at the top rather than relying on sortOrder fallback.
           const manualOrder = get().sortBy === 'manual' ? Date.now() : undefined
           const activeScope = parseWorkspaceKey(get().activeWorkspaceKey ?? '')
           const parentWorkspace =
@@ -3138,11 +3029,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
                   },
                   { timeoutMs: 10 * 60_000 }
                 )
-          // Why: a file watcher (worktrees.onChanged) can fire between the
-          // backend creating the worktree and this callback running, causing
-          // fetchWorktrees to add the worktree first. Appending unconditionally
-          // then produces a duplicate entry in worktreesByRepo, which gives
-          // React duplicate keys and can corrupt terminal DOM containers.
+          // Why: worktrees.onChanged can add this worktree before this callback runs; appending blindly would duplicate it (React key clash).
           set((s) => {
             const hostId = repoHostId(s, repoId)
             const createdWorktree = withRepoHostOwnership(
@@ -3221,9 +3108,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       if (!entry) {
         return {}
       }
-      // Why: the main process re-emits the same phase across mutually-exclusive
-      // fetch paths; skip the write when nothing changes so the strip and panel
-      // don't re-render on a no-op progress event.
+      // Why: the main process re-emits the same phase; skip no-op writes so the strip and panel don't re-render.
       const hasChange = (Object.keys(patch) as (keyof typeof patch)[]).some(
         (key) => patch[key] !== entry[key]
       )
@@ -3253,8 +3138,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         window.api?.ephemeralVm?.cancelProvision
       ) {
         void window.api.ephemeralVm.cancelProvision({ provisionId: creationId }).catch(() => {
-          // Best effort: dismissing the pending surface should not be blocked by
-          // an already-finished or unreachable provisioning process.
+          // Best effort: dismissing the pending surface shouldn't block on a finished or unreachable provisioning process.
         })
       }
       if (
@@ -3266,16 +3150,13 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         void window.api.ephemeralVm
           .cleanup({ runtimeId: entry.request.ephemeralVmRuntimeId })
           .catch(() => {
-            // Best effort: cancellation should not block on provider cleanup,
-            // and the Settings runtime list still exposes retry/manual cleanup.
+            // Best effort: cancellation shouldn't block on provider cleanup; Settings still exposes retry/manual cleanup.
           })
       }
       const { [creationId]: _removed, ...rest } = s.pendingWorktreeCreations
       return {
         pendingWorktreeCreations: rest,
-        // Why: only clear the active surface if it pointed here, so dismissing a
-        // background creation the user already navigated away from doesn't yank
-        // them off whatever they're now looking at.
+        // Why: only clear the active surface if it pointed here, so dismissing a background creation doesn't yank the user away.
         ...(s.activePendingCreationId === creationId ? { activePendingCreationId: null } : {})
       }
     })
@@ -3311,8 +3192,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     }))
 
     try {
-      // Why: forget-local touches no remote, so there is no archive hook to run
-      // and no need to prompt for hook trust.
+      // Why: forget-local touches no remote, so there's no archive hook to run or trust prompt needed.
       const skipArchive = forgetLocalOnly
         ? true
         : (await ensureHooksConfirmed(
@@ -3335,9 +3215,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       ) {
         throw new Error(WORKTREE_REMOVAL_AMBIGUOUS_ERROR)
       }
-      // Why: forget-local always clears Orca's own records via the local IPC
-      // handler regardless of the workspace's execution host — the whole point
-      // is that the remote (SSH relay / runtime) is gone or unreachable.
+      // Why: forget-local clears Orca's records via local IPC regardless of host — the remote is gone or unreachable.
       const target = getActiveRuntimeTarget(
         hostId
           ? settingsForExecutionHostOwner(get().settings, hostId)
@@ -3358,8 +3236,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
               { timeoutMs: 60_000 }
             ))
 
-      // Why: invalidate stale probes as soon as deletion is authoritative, so
-      // an old toast cannot mutate a same-path replacement during UI teardown.
+      // Why: invalidate stale probes once deletion is authoritative, so an old toast can't mutate a same-path replacement.
       forgetHugeRepoWarningDismissalsForWorktrees([worktreeId])
 
       const worktreeDisplayName = worktreeBeforeRemoval?.displayName?.trim()
@@ -3370,54 +3247,33 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             displayName: worktreeDisplayName
           })
         } catch (error) {
-          // Why: preserving automation history labels is best-effort; a stale
-          // preload/test harness must not block worktree removal cleanup.
+          // Why: snapshotting automation labels is best-effort; a stale preload/test harness must not block removal.
           console.warn('Failed to snapshot automation workspace name:', error)
         }
       }
 
-      // Why: backend delete paths now preflight and kill PTYs only after the
-      // worktree is cleanly removable. Renderer state follows the successful
-      // backend result so blocked dirty deletes keep their terminals intact.
-      //
-      // Why browsers first: `shutdownWorktreeTerminals` used to own the
-      // `browserTabsByWorktree[worktreeId]` delete as a side effect, which would
-      // race `shutdownWorktreeBrowsers`' read of the same map. After the §1.3
-      // split, terminals no longer touches browser state, but we still call
-      // browsers first so destroyPersistentWebview sees the workspaces in place
-      // and the Chromium guests are unregistered before any other teardown work
-      // can intercept them.
+      // Why: renderer state follows the successful backend result, so blocked dirty deletes keep their terminals intact.
+      // Why browsers first: unregister Chromium guests before other teardown can intercept them (avoids a browser-state race).
       await get().shutdownWorktreeBrowsers(worktreeId)
       await get().shutdownWorktreeTerminals(worktreeId)
-      // Why: dispose the runtime-owned SSH relay AFTER tearing down this workspace's terminals,
-      // so a still-mounted SSH terminal pane can't connect to an already-gone relay and surface a
-      // spurious "SSH connection is not active" toast during delete.
+      // Why: dispose the SSH relay AFTER terminal teardown so a still-mounted pane can't hit a gone relay and toast "SSH not active".
       const destroyedRuntimeSshTargetIds = await cleanupEphemeralVmRuntimesForDeleted({
         workspaceIds: [worktreeId]
       })
-      // Remove the now-orphaned project that pointed at the destroyed runtime-owned SSH target so it
-      // can't surface as a dead, never-connectable project in the composer.
+      // Remove the orphaned project for the destroyed SSH target so it can't surface as a dead project in the composer.
       await purgeOrphanedRuntimeSshProjects(get, destroyedRuntimeSshTargetIds)
       const tabs = get().tabsByWorktree[worktreeId] ?? []
       const tabIds = new Set(tabs.map((t) => t.id))
 
-      // Why: this path deletes tabsByWorktree wholesale (not via closeTab), so
-      // purge the module-level maps keyed by this worktree/its tabs here too —
-      // matching buildWorktreePurgeState so retired ids don't accumulate.
+      // Why: this path deletes tabsByWorktree wholesale (not via closeTab), so purge the module-level tab maps here too.
       detachedHeadAutoDerivedDisplayNames.delete(worktreeId)
       forgetForegroundTerminalTabs(tabIds)
       forgetAgentStartupDeliveriesForTabs(tabIds)
 
-      // Why: deletion is async (backend + terminal/browser teardown awaited
-      // above), so snapshot the sidebar's current top-row anchor in the same
-      // tick we remove the row. Recording at click time goes stale across the
-      // await, and this covers every delete entry point (modal, card, SSH,
-      // batch) rather than only the context menu.
+      // Why: snapshot the sidebar top-row anchor in the same tick we remove the row; recording at click time goes stale across the await.
       requestVirtualizedScrollAnchorRecord('[data-worktree-sidebar]')
 
-      // Why: explicit deletion provenance is available here before child
-      // unmount cleanup; identity migration and recoverable remounts are not
-      // destructive and must keep their buffered live PTY state.
+      // Why: dispose parked terminal watchers only on explicit deletion; identity migration/remounts must keep buffered PTY state.
       disposeRemovedWorktreeParkedTerminalWatchers(worktreeId, terminalPtyIdsBeforeRemoval)
       set((s) => {
         const next = { ...s.worktreesByRepo }
@@ -3433,9 +3289,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           ...s.automaticAgentResumeClaimsByTabId
         }
         const nextNativeChatLaunchPromptByTabId = { ...s.nativeChatLaunchPromptByTabId }
-        // Why: closeTab deletes these two per-tab maps but removeWorktree missed
-        // them, so a split pane's expand flags outlived its deleted worktree for
-        // the renderer's whole session. Purge them here to match closeTab.
+        // Why: closeTab deletes these per-tab maps but removeWorktree missed them, leaking a split pane's expand flags.
         const nextExpandedPaneByTabId = { ...s.expandedPaneByTabId }
         const nextCanExpandPaneByTabId = { ...s.canExpandPaneByTabId }
         for (const tabId of tabIds) {
@@ -3461,13 +3315,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         delete nextActiveFileIdByWorktree[worktreeId]
         const nextActiveBrowserTabIdByWorktree = { ...s.activeBrowserTabIdByWorktree }
         delete nextActiveBrowserTabIdByWorktree[worktreeId]
-        // Why: closeBrowserTab — which shutdownWorktreeBrowsers delegates to —
-        // pushes a snapshot into recentlyClosedBrowserTabsByWorktree for the
-        // Cmd+Shift+T undo path. That is correct for UI close, but wrong when
-        // the owning worktree itself is being deleted: the snapshots reference
-        // workspaces and pages that can never be restored. Purge the worktree
-        // key symmetrically with browserTabsByWorktree. Per-workspace page
-        // snapshots are already cleared upstream by closeBrowserTab.
+        // Why: closeBrowserTab records a Cmd+Shift+T undo snapshot, but a deleted worktree's tabs can't be restored; purge it.
         const nextRecentlyClosedBrowserTabsByWorktree = {
           ...s.recentlyClosedBrowserTabsByWorktree
         }
@@ -3477,16 +3325,11 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         const nextActiveTabIdByWorktree = { ...s.activeTabIdByWorktree }
         delete nextActiveTabIdByWorktree[worktreeId]
         const nextTabBarOrderByWorktree = { ...s.tabBarOrderByWorktree }
-        // Why: the mixed terminal/editor/browser tab strip persists visual order
-        // per worktree. If a deleted worktree keeps its entry, stale tab IDs stay
-        // retained indefinitely even though reconcileTabOrder filters them later.
+        // Why: the tab strip persists visual order per worktree; drop the entry so stale tab IDs aren't retained.
         delete nextTabBarOrderByWorktree[worktreeId]
         const nextPendingReconnectTabByWorktree = { ...s.pendingReconnectTabByWorktree }
         delete nextPendingReconnectTabByWorktree[worktreeId]
-        // Why: split-tab layout/group state is owned by the worktree. Leaving it
-        // behind retains full tab chrome for terminals/editors/browser tabs that
-        // no longer exist and makes a deleted worktree look restorable in session
-        // state even though its backing entities were already removed.
+        // Why: split-tab layout/group state is worktree-owned; leaving it makes a deleted worktree look restorable.
         const nextUnifiedTabsByWorktree = { ...s.unifiedTabsByWorktree }
         delete nextUnifiedTabsByWorktree[worktreeId]
         const nextGroupsByWorktree = { ...s.groupsByWorktree }
@@ -3495,10 +3338,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         delete nextLayoutByWorktree[worktreeId]
         const nextActiveGroupIdByWorktree = { ...s.activeGroupIdByWorktree }
         delete nextActiveGroupIdByWorktree[worktreeId]
-        // Why: git status / compare caches are keyed by worktree and stop being
-        // refreshed once the worktree is deleted. Remove them here so deleted
-        // worktrees cannot retain stale conflict badges, branch diffs, or compare
-        // request keys indefinitely in a long-lived renderer session.
+        // Why: git status/compare caches stop refreshing once the worktree is deleted; remove them so no stale badges/diffs linger.
         const nextGitStatusByWorktree = { ...s.gitStatusByWorktree }
         delete nextGitStatusByWorktree[worktreeId]
         const nextGitStatusHeadByWorktree = { ...s.gitStatusHeadByWorktree }
@@ -3521,8 +3361,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           ...s.gitBranchCompareRequestStatusHeadByWorktree
         }
         delete nextGitBranchCompareRequestStatusHeadByWorktree[worktreeId]
-        // Why: clean up per-file editor state for files belonging to the removed
-        // worktree so stale drafts and view modes never accumulate in memory.
+        // Why: clean up per-file editor state for the removed worktree so stale drafts/view modes don't accumulate.
         const removedFileIds = new Set<string>()
         for (const file of s.openFiles) {
           if (file.worktreeId !== worktreeId) {
@@ -3542,8 +3381,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           removedFileIds.size > 0
             ? { ...s.markdownFrontmatterVisible }
             : s.markdownFrontmatterVisible
-        // Why: editorCursorLine is keyed by fileId and must be cleared with the
-        // other per-file editor state so it does not leak per removed file.
+        // Why: editorCursorLine is keyed by fileId; clear it with the other per-file state so it doesn't leak.
         const nextEditorCursorLine =
           removedFileIds.size > 0 ? { ...s.editorCursorLine } : s.editorCursorLine
         if (removedFileIds.size > 0) {
@@ -3559,8 +3397,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         delete nextExpandedDirs[worktreeId]
         const nextShowDotfilesByWorktree = { ...s.showDotfilesByWorktree }
         delete nextShowDotfilesByWorktree[worktreeId]
-        // Why: keyed by worktreeId; clear the huge-status marker so it does not
-        // linger after the worktree is gone.
+        // Why: clear the huge-status marker so it doesn't linger after the worktree is gone.
         const nextGitStatusHugeByWorktree = { ...s.gitStatusHugeByWorktree }
         delete nextGitStatusHugeByWorktree[worktreeId]
         const nextRightSidebarExplorerViewByWorktree = {
@@ -3608,14 +3445,11 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           })(),
           fileSearchStateByWorktree: (() => {
             const nextSearch = { ...s.fileSearchStateByWorktree }
-            // Why: file search UI state is worktree-scoped. Removing the worktree
-            // must also remove its cached query/results so another worktree never
-            // inherits stale matches from a path that no longer exists.
+            // Why: file search state is worktree-scoped; clear it so another worktree can't inherit stale matches.
             delete nextSearch[worktreeId]
             return nextSearch
           })(),
-          // Why: these worktree-keyed maps are re-keyed on rename but were missed
-          // by both removal paths, leaking one entry per removed worktree.
+          // Why: these worktree-keyed maps are re-keyed on rename but were missed by removal, leaking one entry each.
           remoteStatusesByWorktree: (() => {
             const next = { ...s.remoteStatusesByWorktree }
             delete next[worktreeId]
@@ -3631,8 +3465,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             delete next[worktreeId]
             return next
           })(),
-          // Why: a deleted worktree's tabs can never be reopened, so purge the
-          // cross-type kind list symmetrically with the snapshot stacks above.
+          // Why: a deleted worktree's tabs can never be reopened; purge the kind list with the snapshot stacks above.
           recentlyClosedTabKindsByWorktree: (() => {
             const next = { ...s.recentlyClosedTabKindsByWorktree }
             delete next[worktreeId]
@@ -3686,21 +3519,16 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         }
       })
       get().removeWorkspaceSpaceWorktrees?.([worktreeId])
-      // Why: PR/commit-message generation records are keyed by worktree and were
-      // never evicted on removal — they leaked one record (title/body text) per
-      // worktree for the session. Prune to the surviving worktree set, reusing
-      // the generation slices' tested prune actions.
+      // Why: PR/commit-message generation records are keyed by worktree; prune to the surviving set so they don't leak.
       const liveWorktreeKeys = new Set(
         get()
           .allWorktrees()
           .map((w) => w.id)
       )
-      // Optional-chained like removeWorkspaceSpaceWorktrees above: minimal store
-      // assemblies (some unit tests) omit the generation slices.
+      // Optional-chained: minimal store assemblies (some unit tests) omit the generation slices.
       get().prunePullRequestGenerationRecords?.(liveWorktreeKeys)
       get().pruneCommitMessageGenerationRecords?.(liveWorktreeKeys)
-      // Why: Source Control may be unmounted during deletion, so its local
-      // prune effect cannot be the only stale-draft cleanup path.
+      // Why: Source Control may be unmounted during deletion, so it can't be the only stale-draft cleanup path.
       clearSessionCommitDraftForWorktree(worktreeId)
       const preservedBranch = removalResult?.preservedBranch
       if (preservedBranch && options?.suppressPreservedBranchToast !== true) {
@@ -3711,8 +3539,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       pruneHostedReviewLinkMutationGenerations([worktreeId])
       return preservedBranch ? { ok: true as const, preservedBranch } : { ok: true as const }
     } catch (err) {
-      // Why: git refusing a non-force delete for dirty/untracked files is a
-      // handled user decision point surfaced by the delete toast, not an app error.
+      // Why: git refusing a non-force delete for dirty/untracked files is a handled user decision, not an app error.
       console.warn('Failed to remove worktree:', err)
       const error = err instanceof Error ? err.message : String(err)
       const forceDeleteReason = classifyWorktreeForceDeleteReason(error, force)
@@ -3841,9 +3668,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     const normalizedUpdates = existingWorktree
       ? clearOlderHostedReviewLinksForReplacement(updates, existingWorktree)
       : updates
-    // Why: manual PR linking only supplies the PR number. Resolve the PR head
-    // branch here so Push targets the review branch; re-saving the same PR can
-    // also heal older metadata that lost pushTarget.
+    // Why: manual PR linking supplies only the number; resolve the head branch so Push targets the review branch.
     const linkedPrForPushTarget = isPositiveHostedReviewNumber(normalizedUpdates.linkedPR)
       ? normalizedUpdates.linkedPR
       : null
@@ -3864,8 +3689,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     const nextHostedReviewPushTargetLookup = existingWorktree
       ? getHostedReviewPushTargetLookup({ ...existingWorktree, ...normalizedUpdates })
       : null
-    // Why: a pushTarget derived from one linked review must not keep steering
-    // pushes after that review is unlinked or replaced by another provider/id.
+    // Why: a pushTarget derived from a linked review must not keep steering pushes after it's unlinked or replaced.
     const shouldClearStaleHostedReviewPushTarget =
       Boolean(existingWorktree?.pushTarget) &&
       normalizedUpdates.pushTarget === undefined &&
@@ -3891,11 +3715,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       : undefined
     const reviewBranch = worktreeForUpdate?.branch.replace(/^refs\/heads\//, '')
 
-    // Why: editing a comment is meaningful interaction with the worktree.
-    // Without refreshing lastActivityAt, the time-decay score has decayed
-    // since the previous sort, so a re-sort causes the worktree to drop in
-    // ranking even though the user just touched it. Bumping the timestamp
-    // keeps the recency signal fresh so the worktree holds its position.
+    // Why: bump lastActivityAt on comment edits so the time-decay sort doesn't drop a just-touched worktree.
     const targetEnriched = resolvedPushTarget
       ? { ...normalizedUpdates, pushTarget: resolvedPushTarget }
       : shouldClearStaleHostedReviewPushTarget
@@ -4013,9 +3833,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         reviewBranch &&
         typeof get().fetchHostedReviewForBranch === 'function'
       ) {
-        // Why: the old cache entry may have been populated by the previous
-        // provider link. Refetch against the post-update links so stale lookups
-        // cannot keep showing the removed review.
+        // Why: refetch against post-update links so a cache entry from the previous provider link can't keep showing the removed review.
         void get().fetchHostedReviewForBranch(reviewRepo.path, reviewBranch, {
           repoId: reviewRepo.id,
           linkedGitHubPR: getHostedReviewLinkForMetaRefresh(
@@ -4079,8 +3897,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       if (currentLookup?.key !== lookup.key) {
         return
       }
-      // Why: old linked-review worktrees can lose metadata while their branch
-      // tracks a helper ref; restoring the review head target keeps push/status aligned.
+      // Why: restore the review head push target so push/status stay aligned after metadata loss.
       await get().updateWorktreeMeta(worktreeId, { pushTarget: resolvedPushTarget })
     } finally {
       hostedReviewPushTargetLookupsInFlight.delete(lookup.key)
@@ -4137,15 +3954,12 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
   },
 
   setWorktreesPinnedAndReveal: (worktreeIds, isPinned) => {
-    // Only follow a toggled row with the viewport when it's the focused
-    // worktree; pinning/unpinning an unfocused card shouldn't yank the user's
-    // scroll to a row they aren't looking at.
+    // Only follow a toggled row with the viewport when it's the focused worktree, not an unfocused card.
     const activeSidebarWorktreeId = getActiveSidebarWorkspaceId(
       get().activeWorkspaceKey,
       get().activeWorktreeId
     )
-    // Skip worktrees already in the target state so a no-op toggle doesn't
-    // scroll the viewport away from where the user is.
+    // Skip worktrees already in the target state so a no-op toggle doesn't scroll the viewport away.
     const updates = new Map<string, Partial<WorktreeMeta>>()
     let didChange = false
     let revealWorktreeId: string | null = null
@@ -4168,9 +3982,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     if (!didChange) {
       return
     }
-    // updateWorktreesMeta applies its store update synchronously (only the
-    // persistence is async), so the reveal below resolves against a render
-    // where the shortcut row already exists.
+    // updateWorktreesMeta applies the store update synchronously, so the reveal below sees the row already rendered.
     void get().updateWorktreesMeta(updates)
     if (revealWorktreeId !== null) {
       get().revealWorktreeInSidebar(revealWorktreeId, { behavior: 'smooth', highlight: true })
@@ -4178,11 +3990,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
   },
 
   markWorktreeUnread: (worktreeId) => {
-    // Why: terminal attention should remain visible until the user engages
-    // with the worktree. Interaction with a pane inside the worktree dismisses
-    // the dot via clearWorktreeUnread. Worktree activation via setActiveWorktree
-    // also clears isUnread as a side-effect; that path predates this PR and is
-    // unaffected here.
+    // Why: attention dot stays until the user engages the worktree; cleared by pane interaction or activation.
     let shouldPersist = false
     const now = Date.now()
     set((s) => {
@@ -4258,9 +4066,8 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         fallbackPRSource: alreadyLinked ? null : 'explicit'
       }).then((pr) => {
         if (!alreadyLinked && pr?.number === link.number) {
-          // Why: terminal output can include arbitrary PR URLs from docs,
-          // agents, or logs. Persist only after branch lookup confirms it and
-          // the user has not picked a different PR while lookup was in flight.
+          // Why: terminal output can carry arbitrary PR URLs (docs/agents/logs).
+          // Persist only after branch lookup confirms it and the user hasn't picked another PR mid-flight.
           void get().updateWorktreeMeta(
             worktreeId,
             { linkedPR: link.number },
@@ -4281,8 +4088,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
 
     const fetchHostedReviewForBranch = get().fetchHostedReviewForBranch
     if (typeof fetchHostedReviewForBranch === 'function') {
-      // Why: full app stores always have fetchPRForBranch, which syncs the
-      // GitHub hosted-review cache. Keep this only as a slice-test fallback.
+      // Why: full app stores have fetchPRForBranch (syncs the hosted-review cache); this is only a slice-test fallback.
       void refreshHostedReviewCard(fetchHostedReviewForBranch, {
         repoPath: repo.path,
         repoId: repo.id,
@@ -4299,10 +4105,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     set((s) => {
       const worktree = findKnownWorktreeById(s, worktreeId)
       if (!worktree || !worktree.isUnread) {
-        // Why: return `s` (not `{}`) to preserve the exact object reference
-        // on no-op. This matches the sibling `clearTerminalTabUnread` in
-        // terminals.ts and avoids downstream selector churn on the hot path
-        // (called on every keystroke and pointerdown).
+        // Why: return `s` (not {}) to keep the object reference on this hot-path no-op (every keystroke), avoiding selector churn.
         return s
       }
       shouldPersist = true
@@ -4349,15 +4152,8 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         return {}
       }
       shouldPersist = true
-      // Skip sortEpoch bump for the active worktree. Terminal events
-      // (PTY spawn, PTY exit) in the active worktree are side-effects of
-      // the user clicking the card or interacting with the terminal —
-      // re-sorting the sidebar in response would cause the exact reorder-
-      // on-click bug PR #209 intended to fix (e.g. dead-PTY reconnection
-      // after generation bump triggers updateTabPtyId → here).
-      // The lastActivityAt timestamp is still persisted so that the NEXT
-      // meaningful sortEpoch bump (from a background worktree event) will
-      // include this worktree's updated smart-sort score.
+      // Why: skip sortEpoch bump for the active worktree — its PTY events are click side-effects (reorder-on-click bug, PR #209).
+      // lastActivityAt is still persisted so the next background-driven sortEpoch bump includes this worktree's score.
       const isActive = s.activeWorktreeId === worktreeId
       const nextWorktrees = applyWorktreeUpdates(s.worktreesByRepo, worktreeId, {
         lastActivityAt: now
@@ -4398,11 +4194,8 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
   },
 
   markWorktreeVisited: (worktreeId, visitedAt) => {
-    // Why: Cmd+J's empty-query ordering needs a focus-recency signal that is
-    // distinct from worktree.lastActivityAt (which is driven by background
-    // PTY/activity events). Monotonic: CLI- and IPC-driven activations can
-    // race, so older timestamps must not regress the stored value. See
-    // docs/cmd-j-empty-query-ordering.md.
+    // Why: Cmd+J empty-query ordering needs a focus-recency signal distinct from lastActivityAt (background PTY/activity).
+    // Monotonic: CLI/IPC activations can race, so older timestamps must not regress. See docs/cmd-j-empty-query-ordering.md.
     set((s) => {
       const now = visitedAt ?? Date.now()
       const prev = s.lastVisitedAtByWorktreeId[worktreeId] ?? 0
@@ -4420,17 +4213,8 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
 
   pruneLastVisitedTimestamps: () => {
     set((s) => {
-      // Why: scope pruning per-repo. SSH-backed repos cannot enumerate
-      // worktrees until their connection is established, so at hydration
-      // time worktreesByRepo[sshRepoId] is empty/undefined. If we pruned
-      // globally based on the union of all repos' worktrees, we would wipe
-      // every persisted focus-recency entry for SSH worktrees — precisely
-      // the set this feature exists to preserve. Instead, only drop entries
-      // whose repo has a populated worktree list: a missing repoId means
-      // "not yet hydrated" (defer), a repoId with an empty list after a
-      // successful listing means the worktree really is gone (drop).
-      // The ssh:state-changed 'connected' handler re-fetches worktrees and
-      // a follow-up prune runs from the same site if needed.
+      // Why: prune per-repo, not globally — SSH repos aren't hydrated at startup, so a global prune would wipe SSH focus-recency.
+      // Only drop for repos with a populated/authoritative list; a missing repoId means not-yet-hydrated (defer).
       const validIdsByRepo = new Map<string, Set<string>>()
       for (const [repoId, list] of Object.entries(s.worktreesByRepo)) {
         if (s.detectedWorktreesByRepo[repoId]) {
@@ -4499,14 +4283,9 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         const nextTabs = tabs.slice()
         nextTabs[index] = {
           ...tab,
-          // Why: TerminalPane keys on `${tab.id}-${generation}` — the bump is
-          // the remount. Same mechanism as the dead-transport activation bump
-          // above; here it is health-driven for a pane whose renderer died
-          // while its PTY stayed alive (wedged/disposed xterm, unbound
-          // transport), so the remounted pane reattaches instead of spawning.
+          // Why: bump generation to remount a pane whose renderer died while its PTY stayed alive, so it reattaches, not spawns.
           generation: (tab.generation ?? 0) + 1,
-          // Why: recovery is not a user interaction — suppress the resulting
-          // PTY updates from reshuffling Recent, like activation remounts do.
+          // Why: recovery isn't a user interaction — suppress its PTY updates from reshuffling Recent, like activation remounts.
           pendingActivationSpawn: getActivationSpawnSuppression(s.terminalLayoutsByTabId[tab.id])
         }
         remounted = true
@@ -4541,8 +4320,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         return {
           activeWorktreeId: null,
           activeWorkspaceKey: null,
-          // Why: activating any real worktree (or clearing it) must dismiss the
-          // background-creation panel so the user isn't stranded on it.
+          // Why: clearing/activating a worktree must dismiss the background-creation panel so the user isn't stranded on it.
           activePendingCreationId: null
         }
       }
@@ -4550,9 +4328,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       const worktree = findKnownWorktreeById(s, worktreeId)
       shouldClearUnread = Boolean(worktree?.isUnread)
 
-      // Restore per-worktree editor state
-      // Why: Search now lives under Explorer, so the files/search sub-route
-      // must switch with the worktree instead of leaking the previous one.
+      // Why: Search lives under Explorer, so the files/search sub-route must switch with the worktree, not leak the prior one.
       const restoredRightSidebarExplorerView =
         s.rightSidebarExplorerViewByWorktree?.[worktreeId] ?? 'files'
       const restoredFileId = s.activeFileIdByWorktree[worktreeId] ?? null
@@ -4583,11 +4359,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       const hasGroupOwnedSurface =
         (s.groupsByWorktree[worktreeId]?.length ?? 0) > 0 || Boolean(s.layoutByWorktree[worktreeId])
 
-      // Why: worktree activation must restore from the reconciled tab-group
-      // model first. Split groups are now the ownership model for visible
-      // content; if we prefer the legacy activeTabType/browser/file fallbacks
-      // when the two models disagree, the renderer can reopen a surface that
-      // has no backing unified tab and show a blank worktree.
+      // Why: restore from the reconciled tab-group model first; preferring legacy fallbacks can show a blank worktree.
       let activeFileId: string | null
       let activeBrowserTabId: string | null
       let activeTabType: WorkspaceVisibleTabType
@@ -4648,8 +4420,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         activeTabType = fallbackFile ? 'editor' : fallbackBrowserTab ? 'browser' : 'terminal'
       }
 
-      // Why: restore the last-active terminal tab for this worktree so the
-      // user returns to the same tab they left, not always the first one.
+      // Why: restore the last-active terminal tab so the user returns to where they left, not tab 0.
       const restoredTabId = s.activeTabIdByWorktree[worktreeId] ?? null
       const worktreeTabs = s.tabsByWorktree[worktreeId] ?? []
       const tabStillExists = restoredTabId
@@ -4662,34 +4433,13 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             ? restoredTabId
             : (worktreeTabs[0]?.id ?? null)
 
-      // Why: focusing a worktree is not meaningful background activity for the
-      // smart sort. Writing lastActivityAt here makes the next unrelated
-      // sortEpoch bump reshuffle cards based on what the user merely looked at,
-      // which is the "jump after focus" bug reported in Slack. Keep selection
-      // side-effects limited to unread clearing; true activity signals such as
-      // PTY lifecycle and explicit edits still flow through bumpWorktreeActivity.
+      // Why: focus isn't smart-sort activity — writing lastActivityAt here caused the "jump after focus" bug; only clear unread.
       const metaUpdates: Partial<WorktreeMeta> = shouldClearUnread ? { isUnread: false } : {}
 
-      // Why: dead-PTY terminal prep must complete before the workspace shell
-      // renders that tab. The shell render is deferred below, so terminal prep
-      // can wait for input quiet instead of blocking the activation click.
-      //
-      // Why pendingActivationSpawn + first-activation check: the first time a
-      // worktree is activated in this session, its TerminalPane mounts and
-      // each tab's PTY either reattaches (restored session) or fresh-spawns
-      // (never visited). Both paths call updateTabPtyId; neither is real
-      // activity — they are side-effects of the click. Tag every tab on the
-      // FIRST activation so the resulting updateTabPtyId suppresses both the
-      // activity bump and the sortEpoch bump.
-      //
-      // We can't use tab.ptyId==null as the guard (what the old `allDead`
-      // check did): reconnectPersistedTerminals re-populates tab.ptyId with
-      // restored daemon session IDs *before* the pane mounts, so tabs look
-      // live to allDead even though the next updateTabPtyId is a reattach.
-      // Tracking first-activation per worktree is the reliable signal.
-      //
-      // Generation is still only bumped when tabs have no live PTY — a live
-      // tab remount would kill the user's running shell.
+      // Why: prep is deferred (shell render deferred below) so it waits for input quiet instead of blocking the click.
+      // Why first-activation guard, not tab.ptyId==null: reconnectPersistedTerminals repopulates ptyId before mount.
+      // Tag every tab on FIRST activation so reattach/fresh-spawn updateTabPtyId suppresses activity + sortEpoch bumps.
+      // Generation is only bumped when no tab has a live PTY — a live remount would kill the user's shell.
       const tabs = s.tabsByWorktree[worktreeId ?? ''] ?? []
       const allDead =
         worktreeId != null &&
@@ -4697,14 +4447,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         tabs.every((tab) => !tabHasLivePty(s.ptyIdsByTabId, tab.id))
       const isFirstActivation = worktreeId != null && !s.everActivatedWorktreeIds.has(worktreeId)
       const shouldTagTabs = worktreeId != null && tabs.length > 0 && isFirstActivation
-      // Why: when every PTY for the worktree's tabs is dead, the existing
-      // (hidden) TerminalPane wraps a dead transport. Once activeWorktreeId
-      // commits, that pane becomes visible and accepts keystrokes that the
-      // dead transport silently drops. Bump generation in the SAME set() so
-      // React/Zustand commit activation and the remount key in one render —
-      // no visible-but-dead-transport window. First-activation tagging
-      // (shouldTagTabs without allDead) does not remount panes and stays on
-      // the deferred path below.
+      // Why: bump generation in the same set() as activation so a dead-transport pane can't go visible-but-dead before remount.
       shouldPrepareTerminalTabs = Boolean(
         worktreeId && tabs.length > 0 && shouldTagTabs && !allDead
       )
@@ -4740,9 +4483,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           : { ...s.activeTabTypeByWorktree, [worktreeId]: activeTabType }
       const hasStateChange =
         s.activeWorktreeId !== worktreeId ||
-        // Why: a pending-creation panel can be showing while activeWorktreeId is
-        // still the prior worktree. Re-selecting that same worktree must clear
-        // the panel, so a non-null activePendingCreationId counts as a change.
+        // Why: a pending-creation panel can show over the prior worktree; a non-null activePendingCreationId counts as a change.
         s.activePendingCreationId !== null ||
         s.activeFileId !== activeFileId ||
         s.activeBrowserTabId !== activeBrowserTabId ||
@@ -4754,9 +4495,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         nextWorktrees !== s.worktreesByRepo ||
         nextDetectedWorktrees !== s.detectedWorktreesByRepo
       if (!hasStateChange) {
-        // Why: repeated activation of the already-active worktree can come from
-        // clicks, IPC, and automation restore paths. Preserve the root Zustand
-        // reference so session persistence/runtime sync do not fan out on a no-op.
+        // Why: preserve the root Zustand reference on a no-op re-activation so session persistence/runtime sync don't fan out.
         return s
       }
 
@@ -4800,8 +4539,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
               [worktreeId]: tabs.map((tab) => ({
                 ...tab,
                 ...(allDead ? { generation: (tab.generation ?? 0) + 1 } : {}),
-                // Why: slept terminal remount/spawn is click-driven wake work.
-                // Tag the resulting PTY updates so they do not reshuffle Recent.
+                // Why: slept terminal remount/spawn is click-driven wake work; tag its PTY updates so they don't reshuffle Recent.
                 pendingActivationSpawn: getActivationSpawnSuppression(
                   s.terminalLayoutsByTabId[tab.id]
                 )
@@ -4829,8 +4567,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       }
     }
 
-    // Why: activation is explicit enough to revalidate PR state immediately;
-    // the GitHub coordinator still coalesces requests and applies rate guards.
+    // Why: activation is explicit enough to revalidate PR state now; the coordinator still coalesces and rate-guards.
     if (worktreeId) {
       get().refreshGitHubForWorktreeIfStale(worktreeId)
     }
@@ -5002,9 +4739,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       }
       const reposChanged = survivingRepos.length !== s.repos.length
 
-      // Why: broader than filterSetupsForPrunedRepoRows — a repoId-less setup on
-      // the removed host can still flip projectIdsRequiringSetupGroups and split a
-      // surviving project group, so drop every setup owned by the removed host.
+      // Why: a repoId-less setup on the removed host can still split a surviving project group, so drop every setup it owns.
       const survivingSetups: AppState['projectHostSetups'] = []
       for (const setup of s.projectHostSetups) {
         if (isRemovedRuntimeHostId(setup.hostId, removed)) {
@@ -5026,8 +4761,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             result.worktrees
           ])
         )
-      // Why: repo/setup catalogs can lag session hydration; hosted worktree rows
-      // are ownership evidence during that loading gap too.
+      // Why: repo/setup catalogs can lag session hydration, so hosted worktree rows are ownership evidence during that gap.
       const recordWorktreeOwners = (
         rowsByRepo: Record<string, readonly { hostId?: ExecutionHostId }[]>
       ): void => {
@@ -5070,8 +4804,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         delete survivingRestoredSessionOwners[workspaceKey]
       }
 
-      // Why: legacy rows predate host stamps; every available owner record must
-      // agree that no other host survives before an unhosted row can be retired.
+      // Why: legacy rows predate host stamps; every owner record must agree no host survives before an unhosted row is retired.
       const repoIdsWithoutSurvivingOwners = new Set(repoIdsWithRemovedOwners)
       for (const repoId of repoIdsWithSurvivingOwners) {
         repoIdsWithoutSurvivingOwners.delete(repoId)
@@ -5096,8 +4829,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         ...detectedDrop.removedWorktreeIds,
         ...sessionWorktreeIdsOwnedByRemovedHosts
       ])
-      // Why: terminal tabs hydrate before worktree metadata; session-only ids for
-      // repos whose owners are all gone still need the full worktree-state purge.
+      // Why: terminal tabs hydrate before worktree metadata, so session-only ids for owner-less repos still need purging.
       if (repoIdsWithoutSurvivingOwners.size > 0) {
         for (const worktreeId of Object.keys(s.tabsByWorktree)) {
           const scope = parseWorkspaceKey(worktreeId)
@@ -5110,8 +4842,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           }
         }
       }
-      // Why: bare-id state follows an exact survivor unless the restored session
-      // partition proves that state belonged to the removed host.
+      // Why: bare-id state follows an exact survivor unless the restored-session partition proves it belonged to the removed host.
       for (const rows of Object.values(worktreeDrop.rowsByRepo)) {
         for (const row of rows) {
           if (!sessionWorktreeIdsOwnedByRemovedHosts.has(row.id)) {
@@ -5162,8 +4893,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           ? { restoredRuntimeHostIdByWorkspaceSessionKey: survivingRestoredSessionOwners }
           : {}),
         ...(rowsChanged ? { sortEpoch: s.sortEpoch + 1 } : {}),
-        // Why: mirror validateRepoScopedUi's repo-scoped UI subset so a filtered or
-        // active sidebar can't be left referencing a purged repo id.
+        // Why: mirror validateRepoScopedUi so a filtered/active sidebar can't reference a purged repo id.
         ...(reposChanged
           ? {
               activeRepoId:
@@ -5179,8 +4909,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     if (oldWorktreeId === newWorktreeId) {
       return
     }
-    // Why: invalidate pre-rename toast actions before publishing the new path,
-    // while carrying the dismissal forward for the same logical worktree.
+    // Why: invalidate pre-rename toast actions before publishing the new path, carrying the dismissal forward.
     migrateHugeRepoWarningDismissal(oldWorktreeId, newWorktreeId)
     set((s) => buildWorktreeRenameState(s, oldWorktreeId, newWorktreeId))
     migrateHostedReviewLinkMutationGeneration(oldWorktreeId, newWorktreeId)
diff --git a/src/renderer/src/web/web-preload-api.ts b/src/renderer/src/web/web-preload-api.ts
index b899324a48f..153839e27bf 100644
--- a/src/renderer/src/web/web-preload-api.ts
+++ b/src/renderer/src/web/web-preload-api.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: the web preload adapter is the browser-side
-   replacement for Electron preload, so the compatibility surface is necessarily
-   centralized at this boundary. */
+/* eslint-disable max-lines -- Why: browser-side Electron-preload replacement; compatibility surface centralizes here. */
 import type {
   PreloadApi,
   PreflightStatus,
@@ -137,8 +135,7 @@ const SESSION_STORAGE_KEY = 'orca.web.workspaceSession.v1'
 const ONBOARDING_STORAGE_KEY = 'orca.web.onboarding.v1'
 const GITHUB_CACHE_STORAGE_KEY = 'orca.web.githubCache.v1'
 const KEYBINDINGS_STORAGE_KEY = 'orca.web.keybindings.v1'
-// Why: browser-paired clients need desktop parity for large dev sessions; the
-// runtime's no-limit default remains capped for lower-level RPC callers.
+// Why: paired clients need parity for large dev sessions; the runtime default stays capped for lower-level RPC callers.
 const WEB_RUNTIME_WORKTREE_LIST_LIMIT = 10_000
 const MAX_CLIPBOARD_IMAGE_BASE64_CHARS = CLIPBOARD_IMAGE_MAX_BASE64_CHARS
 export const MAX_CLIPBOARD_IMAGE_SOURCE_BYTES = CLIPBOARD_IMAGE_MAX_SOURCE_BYTES
@@ -511,8 +508,7 @@ function createWebPreloadApi(): Partial<PreloadApi> {
       getFloatingMarkdownDirectory: () => Promise.resolve(''),
       pickFloatingMarkdownDocument: () => Promise.resolve(null),
       pickFloatingWorkspaceDirectory: () => Promise.resolve(null),
-      // Browser fallback has no app-owned userData directory; rejecting keeps
-      // the sentinel from claiming that sensitive evidence was persisted.
+      // Browser fallback has no app-owned userData dir; reject so the sentinel can't claim sensitive evidence was persisted.
       writeTerminalRenderDesyncEvidence: () =>
         Promise.reject(
           new Error('Terminal render evidence is unavailable in the browser fallback.')
@@ -596,8 +592,7 @@ function createWebPreloadApi(): Partial<PreloadApi> {
     },
     settings: {
       get: async () => getRuntimeBackedStoredSettings(),
-      // Why: localStorage-backed settings are synchronous in the web client,
-      // so the pre-hydration kill-switch read works the same as desktop.
+      // Why: localStorage-backed settings are synchronous, so the pre-hydration kill-switch read works the same as desktop.
       getSync: () => getStoredSettings(),
       set: async (updates) => {
         if (updates.activeRuntimeEnvironmentId === null) {
@@ -652,9 +647,7 @@ function createWebPreloadApi(): Partial<PreloadApi> {
       deleteBundle: () => Promise.reject(new Error('Sent diagnostics are unavailable on web.'))
     },
     session: {
-      // hostId mirrors the desktop bridge: omitted/'local' targets the existing
-      // storage key; non-local hosts persist under a host-suffixed key so their
-      // sessions stay isolated from the local one.
+      // Mirrors desktop bridge: non-local hosts persist under a host-suffixed key so their sessions stay isolated from local.
       get: (hostId) => Promise.resolve(getStoredWorkspaceSession(hostId)),
       set: async (session, hostId) => {
         writeJson(sessionStorageKeyForHost(hostId), sanitizeWebRuntimeWorkspaceSession(session))
@@ -1096,10 +1089,7 @@ function createWebKeybindingsApi(): WebKeybindingsApi {
   }
 }
 
-// Why: the desktop reads native-chat transcripts over IPC; the web client has
-// no IPC, so route readSession/subscribe through the runtime RPC (the same
-// methods the mobile app uses). Without this, window.api.nativeChat was
-// undefined on web and the chat view showed no messages.
+// Why: web has no IPC for native-chat transcripts, so route readSession/subscribe through runtime RPC (as mobile does).
 function createNativeChatApi(): NativeChatApi {
   return {
     readSession: async (agent, sessionId, limit, transcriptPath) =>
@@ -1112,10 +1102,7 @@ function createNativeChatApi(): NativeChatApi {
         })
       ),
     subscribe: (args, onFrame) => {
-      // No paired runtime yet: nothing to subscribe to, and
-      // requireActiveEnvironment() would throw. Return a no-op teardown so the
-      // chat view mounts cleanly until a runtime is paired (only the not-paired
-      // case is swallowed — real subscribe errors still surface via .catch).
+      // No paired runtime yet: return a no-op teardown so the chat view mounts cleanly; only the not-paired case is swallowed.
       const environment = requireActiveEnvironmentOrNull()
       if (!environment) {
         onFrame({
@@ -1207,10 +1194,7 @@ function createNativeChatApi(): NativeChatApi {
                   )
                 }
               } else if (!receivedInitial) {
-                // Why: an ok response whose payload shape we don't recognize would
-                // otherwise never flip receivedInitial, stranding the view on
-                // 'loading'. Settle it with an empty snapshot (carrying any error
-                // the runtime sent) so the UI resolves.
+                // Why: an unrecognized ok payload never flips receivedInitial, stranding the view on 'loading'; settle it empty instead.
                 receivedInitial = true
                 onFrame({
                   type: 'snapshot',
@@ -1222,10 +1206,7 @@ function createNativeChatApi(): NativeChatApi {
             }
           },
           {
-            // Why: send nativeChat.unsubscribe on teardown so the server reaps
-            // the transcript fs-watcher on view-toggle, not just on socket close
-            // (the watcher-leak fix). Echo the pane-specific token so two panes
-            // watching one session cannot tear down each other's watcher.
+            // Why: unsubscribe reaps the fs-watcher on view-toggle (leak fix); echo the pane token so two panes don't tear down each other's watcher.
             buildUnsubscribe: () =>
               buildNativeChatUnsubscribe(args.agent, args.sessionId, args.subscriptionId)
           }
@@ -1327,8 +1308,7 @@ function createAiVaultApi(): NonNullable<Partial<PreloadApi>['aiVault']> {
       if (requestedScope !== 'all' && requestedScope !== executionHostId) {
         return Promise.resolve(webAiVaultUnavailableResult(requestedScope))
       }
-      // Why: the browser client has no local filesystem; every history scan
-      // runs on the paired server and must be stamped as that runtime host.
+      // Why: no local filesystem in the browser, so every history scan runs on and is stamped as the paired runtime host.
       return callRuntimeResult<AiVaultListResult>('aiVault.listSessions', {
         limit: args?.limit,
         force: args?.force,
@@ -1336,9 +1316,7 @@ function createAiVaultApi(): NonNullable<Partial<PreloadApi>['aiVault']> {
         executionHostId
       })
     },
-    // Why: the runtime RPC surface only exposes aiVault.listSessions; subagent
-    // transcript listing has no server-side method yet, so the browser client
-    // reports an empty (not erroring) result.
+    // Why: no server-side RPC for subagent transcript listing yet, so report an empty (not erroring) result.
     listSubagentSessions: () => Promise.resolve({ sessions: [], issues: [] }),
     onWindowFocused: () => noopUnsubscribe
   }
@@ -1373,15 +1351,12 @@ function createReposApi(): NonNullable<Partial<PreloadApi>['repos']> {
       await callRuntimeResult('repo.rm', { repo: repoId })
       invalidateRuntimeWorktreeCaches()
     },
-    // Why: host-scoped forget targets a disconnected/removed SSH host owned by
-    // the desktop app. A paired web client talks to a single Orca runtime and
-    // has no ghost-host state to reconcile.
+    // Why: host-scoped forget targets a desktop-owned SSH host; a paired web client has one runtime and no ghost-host state.
     removeForHost: () => {
       throw new Error('Forgetting a host is unavailable in paired web clients.')
     },
     reorder: async ({ orderedIds }) => callRuntimeResult('repo.reorder', { orderedIds }),
-    // Why: this path persists desktop-owned local or SSH rows. Paired web
-    // clients own only their single runtime, which uses repo.reorder directly.
+    // Why: this persists desktop-owned local/SSH rows; paired web clients own one runtime and use repo.reorder directly.
     reorderForHost: async () => {
       throw new Error('Host-scoped project reordering is unavailable in paired web clients.')
     },
@@ -1397,13 +1372,11 @@ function createReposApi(): NonNullable<Partial<PreloadApi>['repos']> {
       ).repo
     },
     cloneRemote: async () => {
-      // Why: SSH relay cloning is owned by the desktop main process; paired web
-      // clients must not pretend they can run that local IPC path directly.
+      // Why: SSH relay cloning is owned by the desktop main process; paired web clients can't run that local IPC path.
       throw new Error('SSH clone is unavailable in paired web clients.')
     },
     createRemote: async () => {
-      // Why: SSH relay project creation is owned by the desktop main process;
-      // paired web clients cannot create folders through local SSH IPC.
+      // Why: SSH relay project creation is owned by the desktop main process; paired web clients can't use local SSH IPC.
       throw new Error('Creating projects on SSH hosts is unavailable in paired web clients.')
     },
     cloneAbort: () => Promise.resolve(),
@@ -1515,8 +1488,7 @@ function createWorktreesApi(): NonNullable<Partial<PreloadApi>['worktrees']> {
         automationProvenanceRequest: args.automationProvenanceRequest
       })
     },
-    // Why: the runtime create path emits no two-phase progress, so the web
-    // client's creation panel simply falls back to an indeterminate spinner.
+    // Why: the runtime create path emits no two-phase progress, so the panel falls back to an indeterminate spinner.
     onCreateProgress: () => noopUnsubscribe,
     prefetchCreateBase: async ({ repoId, baseBranch }) => {
       await callRuntimeResult('worktree.prefetchCreateBase', {
@@ -1548,8 +1520,7 @@ function createWorktreesApi(): NonNullable<Partial<PreloadApi>['worktrees']> {
         runHooks: skipArchive !== true
       })
     },
-    // Why: forget-locally clears a workspace pinned to a disconnected/removed
-    // SSH host on the desktop app; a paired web client has no such ghost state.
+    // Why: forget-locally clears a desktop workspace pinned to a dead SSH host; a paired web client has no such ghost state.
     forgetLocal: () => {
       throw new Error('Forgetting a workspace is unavailable in paired web clients.')
     },
@@ -1591,8 +1562,7 @@ function createWorktreesApi(): NonNullable<Partial<PreloadApi>['worktrees']> {
     persistSortOrder: async ({ orderedIds }) => {
       await callRuntimeResult('worktree.persistSortOrder', { orderedIds })
     },
-    // Why: the capture lives in desktop main memory and is not exposed over
-    // pairing; the dialog falls back to the persisted excerpt on web clients.
+    // Why: the capture lives in desktop main memory, unexposed over pairing; the dialog falls back to the persisted excerpt.
     getBranchRenameFailureOutput: async () => null,
     onChanged: () => noopUnsubscribe,
     onGitStatusMetadataChanged: () => noopUnsubscribe,
@@ -1736,8 +1706,7 @@ function createFileApi(): NonNullable<Partial<PreloadApi>['fs']> {
       return result.files.map((entry) => entry.relativePath)
     },
     cancelListFiles: async () => {
-      // Why: the paired-web path lists files over runtime RPC with its own
-      // request timeout; there is no host-side scan to abort from here.
+      // Why: paired-web lists files over runtime RPC with its own timeout; there's no host-side scan to abort here.
     },
     search: async (args) => {
       const file = await resolveRuntimeFilePath(args.rootPath)
@@ -1761,8 +1730,7 @@ function createFileApi(): NonNullable<Partial<PreloadApi>['fs']> {
   }
 }
 
-// Why: track the in-flight abortable status request per token so cancelStatus
-// can abort the matching subscription and close its remote request context.
+// Why: track the in-flight abortable status request per token so cancelStatus can abort it and close its remote context.
 const webGitStatusAbortControllers = new Map<string, AbortController>()
 
 async function callAbortableRuntimeStatus<TResult>(
@@ -1809,9 +1777,7 @@ function createGitApi(): NonNullable<Partial<PreloadApi>['git']> {
         bypassEffectiveUpstreamNegativeCache,
         reuseLineStats
       }
-      // Why: without a token there's nothing to cancel, so stay on the pooled
-      // call transport. With one, route through the subscription bridge so
-      // cancelStatus can close the request context and abort the remote scan.
+      // Why: no token = nothing to cancel (pooled); a token routes via the subscription bridge so cancelStatus can abort.
       if (!requestToken) {
         return callRuntimeResult('git.status', params)
       }
@@ -1835,8 +1801,7 @@ function createGitApi(): NonNullable<Partial<PreloadApi>['git']> {
         paths
       })
     },
-    // Why: the "add huge folder to .gitignore" flow is a local-desktop helper;
-    // in the web runtime there's no offer, so return no candidates / no-op.
+    // Why: the "add huge folder to .gitignore" flow is desktop-only; the web runtime makes no offer, so return no candidates.
     findHugeFoldersToIgnore: async () => [],
     appendGitignore: async () => false,
     history: async ({ worktreePath, limit, baseRef }) => {
@@ -2496,14 +2461,12 @@ function createWebUiApi(): NonNullable<Partial<PreloadApi>['ui']> {
     },
     isMaximized: () => Promise.resolve(false),
     onOpenSettings: () => noopUnsubscribe,
-    // Why: the web client has no native tray/menu bar, so there is never a
-    // queued open-settings intent to consume.
+    // Why: the web client has no native tray/menu bar, so there's never a queued open-settings intent to consume.
     consumePendingOpenSettings: () => Promise.resolve(false),
     onOpenSetupGuide: () => noopUnsubscribe,
     onOpenFeatureTour: () => noopUnsubscribe,
     onOpenCrashReport: () => noopUnsubscribe,
-    // No desktop main process to push state changes; the web client re-reads
-    // via ui.get on interaction instead.
+    // No desktop main process to push state changes; the web client re-reads via ui.get on interaction.
     onStateChanged: () => noopUnsubscribe,
     onToggleLeftSidebar: () => noopUnsubscribe,
     onToggleRightSidebar: () => noopUnsubscribe,
@@ -2563,12 +2526,10 @@ function createWebUiApi(): NonNullable<Partial<PreloadApi>['ui']> {
     onTerminalTabCloseRequest: () => noopUnsubscribe,
     respondTerminalTabClose: () => {},
     onSleepWorktree: () => noopUnsubscribe,
-    // Why: paired web is a full renderer that wakes on activation; mobile wake is
-    // desktop-host-scoped, so the web client never receives this signal.
+    // Why: paired web is a full renderer that wakes on activation; mobile wake is desktop-host-scoped and never reaches web.
     onResumeSleepingAgents: () => noopUnsubscribe,
     onTerminalZoom: () => noopUnsubscribe,
-    // Why: a paired web client has no OS sleep signal; occlusion-driven
-    // visibilitychange already covers its wake recovery.
+    // Why: a paired web client has no OS sleep signal; occlusion-driven visibilitychange already covers wake recovery.
     onSystemResumed: () => noopUnsubscribe,
     onFileDrop: () => noopUnsubscribe,
     syncTrafficLights: () => {},
@@ -2775,8 +2736,7 @@ function createSkillsApi(): NonNullable<Partial<PreloadApi>['skills']> {
   return {
     discover: (target) =>
       callRuntimeResult<SkillDiscoveryResult>('skills.discover', target, 15_000),
-    // Why: browser clients have no local skill homes, and remote-host
-    // freshness stays disabled until its update rail has equivalent coverage.
+    // Why: browser clients have no local skill homes; remote-host freshness stays off until its update rail covers it.
     freshnessInventory: (): Promise<SkillFreshnessInventory> =>
       Promise.resolve({
         schemaVersion: 1,
@@ -2820,8 +2780,7 @@ function createRateLimitsApi(): NonNullable<Partial<PreloadApi>['rateLimits']> {
     get: () => Promise.resolve(empty),
     refresh: () => Promise.resolve(empty),
     refreshCodexForTarget: () => Promise.resolve(empty),
-    // Why: web clients do not own local Codex auth, so reset-credit
-    // redemption remains desktop-only and reports the safe no-credit outcome.
+    // Why: web clients don't own local Codex auth; report the safe no-credit outcome since redemption is desktop-only.
     consumeCodexResetCredit: () => Promise.resolve({ outcome: 'noCredit', state: empty }),
     refreshClaudeForTarget: () => Promise.resolve(empty),
     setPollingInterval: () => Promise.resolve(),
@@ -2929,8 +2888,7 @@ function createPtyApi(): NonNullable<Partial<PreloadApi>['pty']> {
     ackData: () => {},
     onDeliveryResyncRequest: () => noopUnsubscribe,
     respondDeliveryResync: () => {},
-    // Why healthy stub: web terminals ride the remote-runtime transport, not
-    // main's delivery gate — a zero-in-flight reply keeps the watchdog idle.
+    // Why: web terminals bypass main's delivery gate; a zero-in-flight reply keeps the watchdog idle.
     reportRendererDeliveryState: () =>
       Promise.resolve({ inFlightTotalChars: 0, inFlightPtyCount: 0, msSinceLastAck: null }),
     getPtyDataListenerCount: () => 0,
@@ -2939,8 +2897,7 @@ function createPtyApi(): NonNullable<Partial<PreloadApi>['pty']> {
     setRendererPtyVisible: () => {},
     setHiddenRendererPty: () => {},
     setPtyDeliveryInterest: () => {},
-    // Why no-op: remote-runtime PTYs are never hidden-gate markable, so the
-    // web client has no main-side responder to feed.
+    // Why: remote-runtime PTYs are never hidden-gate markable, so there's no main-side responder to feed.
     publishTerminalViewAttributes: () => {},
     hasChildProcesses: () => Promise.resolve(false),
     getForegroundProcess: () => Promise.resolve(null),
@@ -2953,8 +2910,7 @@ function createPtyApi(): NonNullable<Partial<PreloadApi>['pty']> {
       ids.map((id) => ({ id, authoritative: false })),
     hasPty: () => Promise.resolve(null),
     getMainBufferSnapshot: () => Promise.resolve(null),
-    // Why: remote-runtime PTYs never transit local main, so the web client has
-    // no side-effect facts source; renderer byte parsing stays authoritative.
+    // Why: remote-runtime PTYs skip local main (no side-effect source); renderer byte parsing stays authoritative.
     onSideEffect: () => noopUnsubscribe,
     getSideEffectSnapshot: () => Promise.resolve(null),
     getRendererDeliveryDebugSnapshot: () =>
@@ -3008,9 +2964,7 @@ function createPtyApi(): NonNullable<Partial<PreloadApi>['pty']> {
 
 function createSshApi(): NonNullable<Partial<PreloadApi>['ssh']> {
   return {
-    // Why: SSH connections are owned by the paired host. Read/connect route to
-    // its runtime RPC so remote worktrees can show real connection state and
-    // reconnect (STA-1468); target management stays desktop-only.
+    // Why: SSH is owned by the paired host; route read/connect to runtime RPC for state/reconnect (STA-1468). Target mgmt is desktop-only.
     listTargets: async () => {
       if (!requireActiveEnvironmentOrNull()) {
         return []
@@ -3168,8 +3122,7 @@ async function saveClipboardImageAsTempFileInRuntime(
       CLIPBOARD_IMAGE_SAVE_TIMEOUT_MS
     )
   } catch (error) {
-    // Why: once chunked paste has created server-side state, failed append or
-    // commit must not wait for TTL cleanup before releasing the bounded slot.
+    // Why: after chunked paste holds server-side state, release the bounded slot on failure rather than wait for TTL cleanup.
     await callRuntimeResult(
       'clipboard.abortImageUpload',
       { uploadId },
@@ -3211,8 +3164,7 @@ function resolveEnvironment(selector: string): StoredWebRuntimeEnvironment {
     return environment
   }
   if (selector.startsWith('web-') && environment.id.startsWith('web-')) {
-    // Why: persisted terminal ids can outlive a web-client re-pair, which creates
-    // a fresh web-* environment id even when it points at the same active server.
+    // Why: persisted terminal ids can outlive a re-pair, which mints a fresh web-* id for the same active server.
     return environment
   }
   throw new Error(`Unknown Orca runtime environment: ${selector}`)
@@ -3370,8 +3322,7 @@ async function updateRuntimePRBotAuthorOverride(args: {
 }): Promise<GlobalSettings> {
   const local = getStoredSettings()
   if (requireActiveEnvironmentOrNull()) {
-    // Why: a paired client must not report a successful mark that the
-    // authoritative runtime failed to persist and will later overwrite.
+    // Why: don't report a successful mark the authoritative runtime failed to persist and will later overwrite.
     const result = await callRuntimeResult<{ settings: Partial<GlobalSettings> }>(
       'settings.updatePRBotAuthorOverride',
       args,
@@ -3406,14 +3357,12 @@ function getStoredOnboarding(): OnboardingState {
     return closed
   }
   const closed = closeWebOnboarding(getDefaultOnboardingState())
-  // Why: pairing already means the user has an Orca server. Desktop first-run
-  // onboarding would incorrectly probe browser-local tools and block the client.
+  // Why: paired clients already have an Orca server; skip desktop first-run onboarding that would probe browser-local tools.
   writeJson(ONBOARDING_STORAGE_KEY, closed)
   return closed
 }
 
-/** Resolve the localStorage key for a session partition. Non-'local' hosts get
- *  a host-suffixed key so their sessions never clobber the local one. */
+/** Resolve the localStorage key for a session partition; non-'local' hosts get a host-suffixed key so they never clobber the local one. */
 function sessionStorageKeyForHost(hostId?: string | null): string {
   const resolved = normalizeExecutionHostId(hostId) ?? LOCAL_EXECUTION_HOST_ID
   return resolved === LOCAL_EXECUTION_HOST_ID
@@ -3435,8 +3384,7 @@ function getStoredWorkspaceSession(hostId?: string | null): WorkspaceSessionStat
     return localSession
   }
   const ui = readLocalWebUIState()
-  // Why: paired web clients mirror host session-tabs after startup. Replaying
-  // browser-local terminal handles first creates stale remote PTYs and errors.
+  // Why: replaying browser-local terminal handles first creates stale remote PTYs; mirror host session-tabs instead.
   return sanitizeWebRuntimeWorkspaceSession({
     ...getDefaultWorkspaceSession(),
     activeRepoId: ui.lastActiveRepoId,
@@ -3464,8 +3412,7 @@ function readLocalWebUIState(): PersistedUIState {
   const storedSettings = getStoredSettings()
   const base = {
     ...defaults,
-    // Why: when runtime ui.get is unavailable, web fallback must mirror the
-    // main-process missing-property seed from the legacy card layout mode.
+    // Why: mirror the main-process missing-property seed from legacy card layout mode when runtime ui.get is unavailable.
     worktreeCardProperties: getWorktreeCardModeProperties(
       storedSettings.compactWorktreeCards ? 'Compact' : 'Default'
     )
@@ -3475,8 +3422,7 @@ function readLocalWebUIState(): PersistedUIState {
   }
   return mergeWebUIState(base, {
     ...stored,
-    // Why: web fallback lacks main-process normalization, so migrate the
-    // retired setting only when the local UI preference is still absent.
+    // Why: web fallback lacks main-process normalization; migrate the retired setting only when local UI preference is absent.
     rightSidebarOpen: storedSettings.rightSidebarOpenByDefault
   })
 }
@@ -3657,8 +3603,7 @@ function isMissingPathError(error: unknown): boolean {
 }
 
 async function resolveRuntimeWorktreeByPath(worktreePath: string): Promise<Worktree> {
-  // Why: hidden-but-open worktrees must still resolve for git/file operations.
-  // `worktree.list` is sidebar-visible only, so path resolution uses detected rows.
+  // Why: hidden-but-open worktrees must still resolve, but `worktree.list` is sidebar-visible only — resolve via detected rows.
   const worktrees = await listAllRuntimeDetectedWorktrees()
   const match = worktrees
     .map((worktree) => ({
@@ -3716,9 +3661,7 @@ function mapRepoPathArg(args: unknown): unknown {
   const repoId = typeof record.repoId === 'string' && record.repoId.trim() ? record.repoId : null
   return {
     ...record,
-    // Why: runtime repo selectors accept loose path/name forms, but duplicate
-    // checked-out repos can make those ambiguous. The renderer already passes
-    // Orca's repo id on task calls, so prefer the explicit selector.
+    // Why: duplicate checked-out repos make path/name selectors ambiguous; prefer the explicit repo id the renderer passes.
     repo: repoId ? `id:${repoId}` : record.repoPath
   }
 }
diff --git a/src/renderer/src/web/web-runtime-client.ts b/src/renderer/src/web/web-runtime-client.ts
index 0162dc24ff9..4f44fe2a811 100644
--- a/src/renderer/src/web/web-runtime-client.ts
+++ b/src/renderer/src/web/web-runtime-client.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: this browser runtime client owns the E2EE
-   WebSocket state machine, JSON-RPC request routing, streaming callbacks, and
-   binary frame forwarding as one transport boundary. */
+/* eslint-disable max-lines -- Why: one transport boundary — E2EE WebSocket state machine, JSON-RPC routing, streaming, binary frame forwarding. */
 import type { RuntimeRpcResponse, RuntimeRpcSuccess } from '../../../shared/runtime-rpc-envelope'
 import { isKeepaliveFrame } from '../../../shared/runtime-rpc-envelope'
 import type { WebPairingOffer } from './web-pairing'
@@ -54,11 +52,7 @@ export type WebRuntimeSubscriptionHandle = {
 
 export type SubscribeOptions = {
   timeoutMs?: number
-  // Why: streaming subscriptions whose server-side cleanup is keyed by a
-  // client-supplied token (native chat keys its fs-watcher by agent:sessionId)
-  // must send an explicit unsubscribe RPC on teardown so the watcher is reaped
-  // on view-toggle, not just on socket close. Returns the RPC frame to emit, or
-  // null when the method needs no explicit teardown.
+  // Why: token-keyed server cleanup needs an explicit unsubscribe to be reaped on view-toggle, not just socket close.
   buildUnsubscribe?: (params: unknown) => { method: string; params: unknown } | null
 }
 
@@ -67,15 +61,7 @@ const CONNECT_TIMEOUT_MS = 12_000
 const HANDSHAKE_TIMEOUT_MS = 10_000
 const RECONNECT_DELAYS_MS = [500, 1000, 2000, 4000, 8000, 15_000]
 const SHARED_CONNECTION_SUBSCRIPTION_METHODS = new Set(['files.watch'])
-// Why: the browser WebSocket API hides protocol pings/pongs, so a half-open
-// connection (mobile NAT idle timeout, server crash, wifi→cellular handoff)
-// leaves readyState===OPEN with no onclose/onerror — the UI silently freezes on
-// stale data and never reconnects. Poll connection liveness while the tab is
-// visible: after HEARTBEAT_IDLE_MS of silence send a cheap status.get probe
-// (any inbound frame proves liveness), and only if that probe stays unanswered
-// for HEARTBEAT_PROBE_GRACE_MS close the socket to drive the reconnect path.
-// Closing is gated on an unanswered PROBE, never on raw accumulated silence, so
-// a backgrounded/frozen tab can never be mistaken for a dead socket on resume.
+// Why: browser WebSockets hide pings/pongs, so a half-open socket stays OPEN with no onclose/onerror — poll liveness in-app.
 const HEARTBEAT_INTERVAL_MS = 10_000
 const HEARTBEAT_IDLE_MS = 25_000
 const HEARTBEAT_PROBE_GRACE_MS = 20_000
@@ -92,13 +78,9 @@ export class WebRuntimeClient {
   private reconnectTimer: number | null = null
   private heartbeatTimer: number | null = null
   private lastInboundFrameAt = 0
-  // Why: timestamp of an outstanding liveness probe (null = none in flight).
-  // The dead-close fires only when a SENT probe goes unanswered, never on raw
-  // silence, so a hidden/frozen tab resuming after a long gap re-probes first.
+  // Timestamp of an outstanding liveness probe (null = none); dead-close fires only on an unanswered sent probe.
   private heartbeatProbeSentAt: number | null = null
-  // Why: detect a suspended tick loop (backgrounded/frozen tab). If a tick lands
-  // far later than scheduled, treat the gap as "no evidence", reset the clocks,
-  // and re-probe instead of closing.
+  // Why: tracks last tick time to detect a suspended loop (frozen tab) so a long gap re-probes instead of closing.
   private lastHeartbeatTickAt = 0
   private readonly pending = new Map<string, PendingRequest>()
   private readonly subscriptions = new Map<string, RuntimeSubscription>()
@@ -141,9 +123,7 @@ export class WebRuntimeClient {
     options?: SubscribeOptions
   ): Promise<WebRuntimeSubscriptionHandle> {
     if (SHARED_CONNECTION_SUBSCRIPTION_METHODS.has(method)) {
-      // Why: file watches are text-only and already have an explicit
-      // files.unwatch RPC, so sharing the main socket avoids exhausting the
-      // server's WebSocket connection cap in large browser sessions.
+      // Why: sharing the main socket for file watches avoids exhausting the server's WebSocket connection cap.
       return this.subscribeSharedFileWatch(params, callbacks, options)
     }
     const client = new WebRuntimeClient(this.pairing)
@@ -172,9 +152,7 @@ export class WebRuntimeClient {
       )
       return {
         unsubscribe: () => {
-          // Why: emit the explicit teardown RPC (e.g. nativeChat.unsubscribe)
-          // on the child socket BEFORE closing it, so the server reaps the
-          // fs-watcher on view-toggle instead of leaking it until socket close.
+          // Why: emit the teardown RPC before closing the child socket so the server reaps the fs-watcher on view-toggle.
           handle.unsubscribe()
           closeChild()
         },
@@ -245,8 +223,7 @@ export class WebRuntimeClient {
         dropLocalSubscription()
         return
       }
-      // Why: retain the shared-socket callback and retry ownership until the
-      // server acknowledges physical teardown; a new watch joins this barrier.
+      // Why: retain the callback and retry until the server acks physical teardown; a new watch joins this barrier.
       const retries = this.fileWatchTeardownRetries.get(teardownKey) ?? new Set()
       retries.add(retryRemoteUnwatch)
       this.fileWatchTeardownRetries.set(teardownKey, retries)
@@ -264,8 +241,7 @@ export class WebRuntimeClient {
             return
           }
         }
-        // Why: the server publishes cancellation ownership before native setup;
-        // callers should still become ready only after the watcher is live.
+        // Why: server publishes cancellation ownership before native setup; callers become ready only once the watcher is live.
         if (isFileWatchStartingResponse(response)) {
           return
         }
@@ -273,9 +249,7 @@ export class WebRuntimeClient {
           callbacks.onResponse(response)
           if (pendingReplayResync && nextSubscriptionId && response.ok) {
             pendingReplayResync = false
-            // Why: a replayed watch reports changes only from its own native
-            // setup; the reconnect gap produced no events, so consumers must
-            // conservatively re-scan once the replacement is ready.
+            // Why: a replayed watch only reports events after its own setup, so consumers must re-scan the reconnect gap.
             callbacks.onResponse(createFileWatchReplayOverflowResponse(response, params))
           }
         } else if (response.ok === false) {
@@ -303,8 +277,7 @@ export class WebRuntimeClient {
         if (retries?.size === 0) {
           this.fileWatchTeardownRetries.delete(teardownKey)
         }
-        // Why: socket close physically releases the old server subscription;
-        // a locally stopped watch must not be replayed on the replacement.
+        // Why: socket close physically releases the server subscription — a stopped watch must not replay on the replacement.
         dropLocalSubscription()
       },
       onTransportReplayed: () => {
@@ -328,12 +301,10 @@ export class WebRuntimeClient {
         if (remoteSubscriptionId) {
           unwatchAndDropLocalSubscription()
         } else if (transportInterrupted) {
-          // Why: socket close already released the old server subscription;
-          // remove its replay record instead of reviving a locally stopped watch.
+          // Why: socket close already released the server subscription — drop its replay record, don't revive a stopped watch.
           dropLocalSubscription()
         }
-        // Why: an older server may not publish its id until ready. Retain the
-        // callback so a late response can still physically unwatch the root.
+        // Why: an older server may not publish its id until ready — retain the callback so a late response can still unwatch.
       },
       sendBinary: (bytes) => handle?.sendBinary(bytes)
     }
@@ -356,8 +327,7 @@ export class WebRuntimeClient {
     return {
       unsubscribe: () => {
         this.subscriptions.delete(subscription.id)
-        // Tell the server to reap its keyed cleanup (e.g. native-chat fs-watcher)
-        // before the socket goes away. Best-effort: a closed socket already reaps.
+        // Tell the server to reap its keyed cleanup before the socket closes; best-effort (a closed socket already reaps).
         const teardown = options?.buildUnsubscribe?.(params)
         if (teardown) {
           this.sendEncrypted({
@@ -445,14 +415,11 @@ export class WebRuntimeClient {
     }
 
     ws.onmessage = (event) => {
-      // Why: stale socket callbacks can arrive after reconnect swaps this.ws;
-      // they must not drive auth or subscription state on the replacement.
+      // Why: stale callbacks from a pre-reconnect socket must not drive state on the replacement this.ws.
       if (this.ws !== ws) {
         return
       }
-      // Why: any inbound frame (RPC reply, subscription push, keepalive, probe
-      // echo) proves the socket is alive — reset the liveness watchdog and clear
-      // any outstanding probe.
+      // Why: any inbound frame proves the socket is alive — reset the liveness watchdog and clear any outstanding probe.
       this.lastInboundFrameAt = this.now()
       this.heartbeatProbeSentAt = null
       void this.handleSocketMessage(event.data, ws)
@@ -787,8 +754,7 @@ export class WebRuntimeClient {
     }
   }
 
-  // Why: overridable seams so a test can drive deterministic time + visibility
-  // without faking globals across the whole crypto/transport fixture.
+  // Why: overridable seams so tests can drive deterministic time + visibility without faking globals.
   protected now(): number {
     return Date.now()
   }
@@ -816,17 +782,14 @@ export class WebRuntimeClient {
 
   private runHeartbeatTick(): void {
     const now = this.now()
-    // Why: if this tick lands far later than scheduled, the loop was suspended
-    // (backgrounded/frozen tab) — that gap is NOT evidence the socket died, so
-    // re-baseline the liveness clocks and drop any stale probe before judging.
+    // Why: a much-later-than-scheduled tick means the loop was suspended (frozen tab), not a dead socket — re-baseline.
     const sinceLastTick = now - this.lastHeartbeatTickAt
     this.lastHeartbeatTickAt = now
     if (sinceLastTick >= HEARTBEAT_INTERVAL_MS * 2) {
       this.lastInboundFrameAt = now
       this.heartbeatProbeSentAt = null
     }
-    // Why: a backgrounded tab shows no live data and the user can't see
-    // staleness, so don't spend battery probing; the next visible tick re-checks.
+    // Why: don't probe while hidden — no visible staleness to detect and it wastes battery; next visible tick re-checks.
     if (!this.isDocumentVisible()) {
       return
     }
@@ -834,9 +797,7 @@ export class WebRuntimeClient {
     if (!ws || ws.readyState !== WebSocket.OPEN || this.state !== 'connected') {
       return
     }
-    // Why: close ONLY when a probe we actually sent has gone unanswered past the
-    // grace window — never on raw accumulated silence. This guarantees at least
-    // one real round-trip attempt before declaring the socket half-open.
+    // Why: close only when a probe we actually sent goes unanswered past grace — never on raw accumulated silence.
     if (
       this.heartbeatProbeSentAt !== null &&
       now - this.heartbeatProbeSentAt >= HEARTBEAT_PROBE_GRACE_MS
@@ -846,10 +807,7 @@ export class WebRuntimeClient {
       return
     }
     if (this.heartbeatProbeSentAt === null && now - this.lastInboundFrameAt >= HEARTBEAT_IDLE_MS) {
-      // Why: a fire-and-forget liveness probe. The reply (or any other frame)
-      // resets lastInboundFrameAt and clears heartbeatProbeSentAt; the id is
-      // intentionally unmatched in handleSocketMessage so it adds no pending
-      // request or timeout. If sending fails the socket isn't OPEN — skip.
+      // Why: fire-and-forget liveness probe; its id is intentionally unmatched so it registers no pending request/timeout.
       if (
         this.sendEncrypted({
           id: `web-heartbeat-${this.nextId()}`,
@@ -903,8 +861,7 @@ function createFileWatchReplayOverflowResponse(
     result: {
       type: 'changed',
       worktree: typeof worktree === 'string' ? worktree : '',
-      // Why: overflow consumers re-scan the whole root and never read the
-      // path; the client does not know the server-side root path here.
+      // Why: overflow consumers re-scan the whole root and ignore the path (client lacks the server-side root here).
       events: [{ kind: 'overflow', absolutePath: '' }]
     },
     _meta: readyResponse._meta

From c6f0ac4040cae54bdb6ec12e4a57b063ae1ff453 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Mon, 20 Jul 2026 03:18:35 -0700
Subject: [PATCH 51/54] refactor(comments): slim verbose comments in mobile
 (#9547)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Collapse multi-line explanatory comment blocks into single-line "why" statements
per AGENTS.md ("Document the Why, Briefly"): drop restatements of the code and
mechanism narration; keep the non-obvious reason, external refs, and directives.

Comments-only — verified no code changed via a Babel/esbuild comment-strip
token-equality gate against origin/main; typecheck and oxlint clean.

Area: mobile. 11 files changed, 339 insertions(+), 1137 deletions(-).

Co-authored-by: Orca <help@stably.ai>
---
 mobile/app/h/[hostId]/index.tsx               | 155 ++----
 .../app/h/[hostId]/session/[worktreeId].tsx   | 514 +++++-------------
 mobile/app/index.tsx                          | 110 +---
 .../src/notifications/mobile-notifications.ts |  73 +--
 .../use-mobile-pr-sidebar-controller.ts       |  80 +--
 .../MobileSourceControlPanel.tsx              |  67 +--
 .../src/terminal/terminal-viewport-refit.ts   |  75 +--
 mobile/src/terminal/terminal-webview-html.ts  |  16 +-
 mobile/src/transport/client-context.tsx       | 117 +---
 mobile/src/transport/host-store.ts            |  77 +--
 mobile/src/transport/rpc-client.ts            | 192 ++-----
 11 files changed, 339 insertions(+), 1137 deletions(-)

diff --git a/mobile/app/h/[hostId]/index.tsx b/mobile/app/h/[hostId]/index.tsx
index 442066ca962..126744a984e 100644
--- a/mobile/app/h/[hostId]/index.tsx
+++ b/mobile/app/h/[hostId]/index.tsx
@@ -108,14 +108,9 @@ function isErrorVerdict(v: ConnectionVerdict): boolean {
 const REPO_METADATA_REFRESH_MS = 60_000
 
 type HostScreenProps = {
-  // Why: when true, this worktree list is rendered as the persistent tablet
-  // sidebar by the host layout rather than as its own routed screen. That
-  // swaps the back button for a hide-sidebar control, drives data fetching
-  // from a plain mount effect (the sidebar is never the "focused" route), and
-  // opens sessions into the detail pane instead of pushing a new full screen.
+  // When true, rendered as the persistent tablet sidebar by the host layout, not as its own routed screen.
   embedded?: boolean
-  // Route params aren't in scope when rendered from the layout, so the caller
-  // passes hostId/action explicitly; falls back to the local route params.
+  // Route params aren't in scope when rendered from the layout, so the caller passes these explicitly.
   hostId?: string
   action?: string
   onHideSidebar?: () => void
@@ -133,16 +128,12 @@ export function HostScreen({
   const router = useRouter()
   const pathname = usePathname()
   const insets = useSafeAreaInsets()
-  // Why: cap and center the worktree list on wide/tablet canvases; on phones
-  // isWideLayout is false so the list stays edge-to-edge as before. When
-  // embedded as the sidebar the list already lives in a narrow pane, so the
-  // cap is skipped (see the SectionList contentContainerStyle below).
+  // Why: cap and center the list on wide/tablet canvases; on phones isWideLayout is false so it stays edge-to-edge.
   const { isWideLayout, contentMaxWidth } = useResponsiveLayout()
   const [initialCache] = useState(() =>
     hostId ? (getCachedWorktrees(hostId) as Worktree[] | null) : null
   )
-  // Why: shared client per host owned by RpcClientProvider. See
-  // docs/mobile-shared-client-per-host.md.
+  // Shared client per host owned by RpcClientProvider. See docs/mobile-shared-client-per-host.md.
   const { client, state: connState } = useHostClient(hostId)
   const reconnectAttempts = useReconnectAttempt(hostId)
   const lastConnectedAt = useLastConnectedAt(hostId)
@@ -156,9 +147,7 @@ export function HostScreen({
   const forceReconnectHost = useForceReconnect()
   const [worktrees, setWorktrees] = useState<Worktree[]>(initialCache ?? [])
   const [worktreesLoaded, setWorktreesLoaded] = useState(initialCache != null)
-  // Why: opening a worktree activates it on the host, but the active-row
-  // highlight otherwise waits for the next worktree.ps poll to reflect it.
-  // Track the locally-opened worktree so the highlight moves instantly.
+  // Why: track the locally-opened worktree so the active-row highlight moves instantly instead of waiting for the next poll.
   const [optimisticActiveWorktreeId, setOptimisticActiveWorktreeId] = useState<string | null>(null)
   // One tick drives every visible agent row's relative timestamp.
   const now = useNow(30_000)
@@ -180,9 +169,7 @@ export function HostScreen({
   const [workspaceStatuses, setWorkspaceStatuses] = useState<readonly WorkspaceStatusDefinition[]>(
     DEFAULT_MOBILE_WORKSPACE_STATUSES
   )
-  // displayName → repo id, populated from repo.list. The filter model keys on
-  // repo ids (desktop's PersistedUIState), but the section headers/rows key on
-  // displayName, so we bridge the two here.
+  // displayName → repo id: filters key on repo id, but section headers/rows key on displayName, so bridge the two.
   const [repoIdsByName, setRepoIdsByName] = useState<Map<string, string>>(new Map())
   const [showSortPicker, setShowSortPicker] = useState(false)
   const [showGroupPicker, setShowGroupPicker] = useState(false)
@@ -201,9 +188,7 @@ export function HostScreen({
   }, [router])
   const [pinnedIds, setPinnedIds] = useState<Set<string>>(new Set())
   const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(new Set())
-  // Why: snapshot of the synced view settings so the focus-effect ui.get merge
-  // and the optimistic ui.set writes read the latest values without forcing the
-  // callbacks to re-create on every state change.
+  // Why: ref so the ui.get merge and ui.set writes read the latest values without re-creating callbacks on every state change.
   const viewStateRef = useRef<MobileViewState>({
     groupMode: 'repo',
     sortMode: 'recent',
@@ -226,8 +211,7 @@ export function HostScreen({
     }
   }, [groupMode, sortMode, filters, collapsedGroups, workspaceStatuses])
 
-  // Apply a MobileViewState (e.g. from a desktop ui.get) onto the individual
-  // states and the snapshot ref in one shot.
+  // Apply a MobileViewState onto the individual states and the snapshot ref in one shot.
   const applyViewState = useCallback((next: MobileViewState) => {
     viewStateRef.current = next
     setGroupMode(next.groupMode)
@@ -241,8 +225,7 @@ export function HostScreen({
     })
   }, [])
 
-  // Optimistically apply a partial change locally, then push the full mapped
-  // settings to the desktop's shared store via ui.set so both apps stay in sync.
+  // Apply the change locally, then push full settings to the desktop's shared store (ui.set) so both apps stay in sync.
   const persistViewSettings = useCallback(
     (patch: Partial<MobileViewState>) => {
       const next: MobileViewState = { ...viewStateRef.current, ...patch }
@@ -275,8 +258,7 @@ export function HostScreen({
   }, [])
 
   const resolvedRouteActionState = resolveHostRouteActionState(routeActionState, action)
-  // Why: `action=newWorktree` is a route-derived open edge. Resolve it before
-  // commit, but don't reopen after the user closes while the same URL remains.
+  // Why: resolve `action=newWorktree` before commit, but don't reopen after the user closes while the URL persists.
   if (resolvedRouteActionState !== routeActionState) {
     setRouteActionState(resolvedRouteActionState)
   }
@@ -285,8 +267,7 @@ export function HostScreen({
     setRouteActionState((current) => setHostRouteNewWorktreeVisible(current, visible))
   }, [])
 
-  // Load persisted pins from the local cache. View settings are no longer
-  // stored locally — they sync from the desktop's shared store via ui.get.
+  // Load persisted pins from local cache; view settings are no longer local (they sync via ui.get).
   useEffect(() => {
     if (!hostId) {
       return
@@ -304,9 +285,7 @@ export function HostScreen({
     }
   }, [hostId])
 
-  // Read the desktop's shared view settings (PersistedUIState) and merge them
-  // onto local state. Runs on connect and on screen focus so changes made on
-  // desktop appear on the phone.
+  // Merge the desktop's shared view settings (PersistedUIState) onto local state so desktop changes appear here.
   const syncViewSettingsFromDesktop = useCallback(async () => {
     if (!client || connState !== 'connected') {
       return
@@ -328,9 +307,7 @@ export function HostScreen({
     }
   }, [client, connState, hostId, applyViewState])
 
-  // Why: keep clientRef in sync so existing imperative call sites work
-  // unchanged. Also re-seed the cached worktree list on hostId change
-  // since the useState initializer only runs on first mount.
+  // Why: mirror client into a ref so imperative call sites read it without re-subscribing.
   useEffect(() => {
     clientRef.current = client
   }, [client])
@@ -342,9 +319,7 @@ export function HostScreen({
     setRepoColorsByName(new Map())
     setRepoIconsByName(new Map())
     repoMetadataFetchedAtRef.current = 0
-    // Why: re-seed from the current host's cache on every hostId change.
-    // The useState initializer only runs on first mount, so if Expo Router
-    // reuses this screen with a different hostId, we must reset here.
+    // Why: useState initializer runs only on first mount, so re-seed the cache when Expo Router reuses this screen for a new hostId.
     const freshCache = hostId ? (getCachedWorktrees(hostId) as Worktree[] | null) : null
     if (freshCache) {
       setWorktrees(freshCache)
@@ -432,8 +407,7 @@ export function HostScreen({
       if (!options.allowDuringModal && newWorktreeModalVisibleRef.current) {
         return
       }
-      // The embedded sidebar polls for the whole split-view session; keep slow
-      // remote hosts from stacking overlapping expensive list requests.
+      // Why: prevent slow remote hosts from stacking overlapping worktree.ps requests during polling.
       if (fetchWorktreesInFlightRef.current) {
         return
       }
@@ -442,8 +416,7 @@ export function HostScreen({
       const requestHostId = hostId
 
       try {
-        // Why: worktree.ps defaults to 200 and silently truncates; match the
-        // desktop's high cap so large hosts don't drop workspaces on mobile.
+        // Why: worktree.ps silently truncates at 200; use a high cap so large hosts don't drop workspaces.
         const response = await requestClient.sendRequest('worktree.ps', { limit: 10000 })
         if (clientRef.current !== requestClient || hostId !== requestHostId) {
           return
@@ -453,9 +426,7 @@ export function HostScreen({
         }
         if (response.ok) {
           const result = (response as RpcSuccess).result as { worktrees: Worktree[] }
-          // Why: large hosts can return identical worktree.ps snapshots every
-          // poll. Preserving the existing array keeps SectionList/sort rebuilds
-          // off the JS tap path unless something actually changed.
+          // Why: reuse the existing array on identical snapshots to keep SectionList/sort rebuilds off the tap path.
           setWorktrees((current) =>
             areWorktreeListsEqual(current, result.worktrees) ? current : result.worktrees
           )
@@ -463,25 +434,18 @@ export function HostScreen({
             areWorktreeListsEqual(current, result.worktrees) ? current : result.worktrees
           )
           setWorktreesLoaded(true)
-          // Why (#8498): the host detail screen seeds its list from the
-          // home-written cache, so a partial home fetch could poison it until a
-          // focus poll corrected it. Write the confirmed snapshot back through
-          // the same cache so a reconnect refetch (or a remount) can't serve a
-          // stale worktree list.
+          // Why (#8498): overwrite the home-written cache with the confirmed snapshot so a reconnect/remount can't serve a stale list.
           if (hostId) {
             setCachedWorktrees(hostId, result.worktrees)
           }
-          // Drop the optimistic active override once the host confirms it (the
-          // activate RPC has landed and worktree.ps now reports it active), so we
-          // stop overriding and respect any later desktop-driven change.
+          // Drop the optimistic active override once the host reports it active, so later desktop changes win.
           setOptimisticActiveWorktreeId((pending) =>
             pending && result.worktrees.some((w) => w.worktreeId === pending && w.isActive)
               ? null
               : pending
           )
 
-          // Clear optimistic sleep overrides once the server confirms the
-          // worktree is actually inactive (liveTerminalCount dropped to 0).
+          // Clear optimistic sleep overrides once the server confirms inactive (liveTerminalCount === 0).
           setSleptIds((prev) => {
             if (prev.size === 0) {
               return prev
@@ -496,8 +460,7 @@ export function HostScreen({
             return still.size === prev.size ? prev : still
           })
 
-          // Sync local pin state from server so desktop-initiated pins/unpins
-          // are reflected without relying on stale AsyncStorage.
+          // Sync pin state from server so desktop-initiated pins reflect without relying on stale AsyncStorage.
           const serverPinned = new Set(
             result.worktrees.filter((w) => w.isPinned).map((w) => w.worktreeId)
           )
@@ -520,17 +483,10 @@ export function HostScreen({
     [client, connState, hostId]
   )
 
-  // Why: read desktop's protocol version from status.get on every connect
-  // and re-evaluate compatibility. If the desktop declares this mobile
-  // build too old (or vice versa via the local minimum), the host detail
-  // screen swaps to a hard-block screen instead of the worktree list.
-  // Today's compat constants are wide-open so this never blocks; the wire
-  // format is in place to flip a switch in a future release.
+  // Why: re-evaluate protocol compat on connect; today's constants are wide-open so this never blocks yet.
   useEffect(() => {
     if (connState !== 'connected' || !client) {
-      // Why: drop the prior host's capabilities while disconnected/switching so
-      // a capability-gated action (e.g. Agent Session History) can't linger for
-      // a host that doesn't support it.
+      // Why: drop capabilities while disconnected/switching so a capability-gated action can't linger for a new host.
       setHostCapabilities([])
       return
     }
@@ -556,8 +512,7 @@ export function HostScreen({
         })
         setCompatVerdict(verdict)
         if (verdict.kind === 'blocked') {
-          // Why: deterministic breadcrumb so support can confirm a block
-          // actually fired (vs a render bug). No PII — just version ints.
+          // Why: support breadcrumb to confirm a block fired vs a render bug; no PII, just version ints.
           console.warn('[protocol-compat] blocked', {
             reason: verdict.reason,
             desktopVersion: verdict.desktopVersion,
@@ -566,8 +521,7 @@ export function HostScreen({
           })
         }
       } catch {
-        // Why: rare path — sendRequest can throw on transport tear-down.
-        // Treat as transient; verdict stays at previous value.
+        // Why: sendRequest can throw on transport tear-down; treat as transient, keep the prior verdict.
       }
     })()
     return () => {
@@ -577,29 +531,22 @@ export function HostScreen({
 
   useFocusEffect(
     useCallback(() => {
-      // Why: opening the host is a strong user signal — reset a backed-off or
-      // trickling reconnect loop (and probe a possibly half-open socket)
-      // immediately instead of waiting out its timer. Deps stay empty so this
-      // fires per focus transition, not per connection-state change; nudging
-      // on every reconnecting↔connecting flip would defeat the backoff.
+      // Why: focus nudges reconnect and probes a possibly half-open socket; empty deps fire per focus, not per state flip (which defeats backoff).
       clientRef.current?.notifyForeground()
     }, [])
   )
 
   useFocusEffect(
     useCallback(() => {
-      // The embedded sidebar drives its own polling below; focus never fires
-      // for it since it isn't a routed screen.
+      // The embedded sidebar isn't a routed screen (focus never fires); it polls via the mount effect below.
       if (embedded || connState !== 'connected') {
         return
       }
       void fetchWorktrees()
       void fetchRepoMetadata()
-      // Pull desktop's shared view settings on focus so desktop-side changes
-      // show up here without a manual refresh.
+      // Pull desktop's shared view settings on focus so desktop changes show up without a manual refresh.
       void syncViewSettingsFromDesktop()
-      // Why: React Navigation keeps previous stack screens mounted; only
-      // poll the host list while this route is visible.
+      // Why: React Navigation keeps prior screens mounted; only poll while this route is visible.
       const interval = setInterval(() => {
         void fetchWorktrees()
         void fetchRepoMetadata()
@@ -608,9 +555,7 @@ export function HostScreen({
     }, [embedded, connState, fetchWorktrees, fetchRepoMetadata, syncViewSettingsFromDesktop])
   )
 
-  // Why: as the persistent tablet sidebar this list is never the focused
-  // route, so useFocusEffect won't fetch/poll. Mirror that behavior from a
-  // plain mount effect while connected instead.
+  // Why: the embedded sidebar is never the focused route, so useFocusEffect never polls; mirror it from a mount effect.
   useEffect(() => {
     if (!embedded || connState !== 'connected') {
       return
@@ -625,10 +570,7 @@ export function HostScreen({
     return () => clearInterval(interval)
   }, [embedded, connState, fetchWorktrees, fetchRepoMetadata, syncViewSettingsFromDesktop])
 
-  // Why (#8498): reconnect refetch + manual pull-to-refresh, extracted to
-  // useWorktreeResync so this screen stays under its max-lines budget. The
-  // steady-state focus/embedded polls don't cover the transition INTO
-  // 'connected' after a background/sleep, which is when the cache is stalest.
+  // Why (#8498): steady-state polls miss the transition INTO 'connected' after background/sleep, when the cache is stalest.
   const { refreshing, onRefresh } = useWorktreeResync({
     client,
     connState,
@@ -720,8 +662,7 @@ export function HostScreen({
       await removeHostAndCloseClient(hostId, closeHostClient)
       leaveHost()
     } catch {
-      // Why: metadata commit can fail while the host is still paired; keep the
-      // screen mounted and re-open confirm (ConfirmModal closes on confirm).
+      // Why: removal can fail while still paired; re-open confirm (ConfirmModal closes on confirm).
       setConfirmRemoveHost(true)
       Alert.alert('Could not remove host', 'Please try again.')
     }
@@ -748,11 +689,9 @@ export function HostScreen({
 
   const openWorktreeSession = useCallback(
     (item: Worktree) => {
-      // Highlight the row immediately; the next worktree.ps poll confirms it.
       setOptimisticActiveWorktreeId(item.worktreeId)
       if (client && connState === 'connected') {
-        // Why: opening a mobile session should hydrate host-owned tabs without
-        // pulling other paired clients, especially desktop, into this worktree.
+        // Why: notifyClients:false hydrates host tabs without pulling desktop into this worktree.
         void client
           .sendRequest('worktree.activate', {
             worktree: `id:${item.worktreeId}`,
@@ -831,8 +770,7 @@ export function HostScreen({
       const slept = sleptIds.has(w.worktreeId)
         ? { liveTerminalCount: 0, hasAttachedPty: false, status: 'inactive' as const }
         : null
-      // Force the just-opened worktree active (and the rest inactive) until the
-      // next poll confirms it, so the highlight doesn't lag the navigation.
+      // Force the just-opened worktree active until the next poll confirms it, so the highlight doesn't lag.
       const active =
         optimisticActiveWorktreeId !== null
           ? { isActive: w.worktreeId === optimisticActiveWorktreeId }
@@ -912,12 +850,7 @@ export function HostScreen({
                 </View>
                 {connState !== 'connected' &&
                   (() => {
-                    // Why: status label removed in favor of just the dot +
-                    // Reconnect button — the home screen already surfaces the
-                    // verdict text per host, and the dot color already
-                    // signals severity here. Auth-failed routes through its
-                    // dedicated banner so we still want to suppress the
-                    // Reconnect button for that case.
+                    // Why: auth-failed has its own banner, so suppress the Reconnect button for that verdict.
                     const verdict = headerVerdict
                     const isError = isErrorVerdict(verdict)
                     const showReconnectButton = isError && hostId && verdict.kind !== 'auth-failed'
@@ -1166,8 +1099,7 @@ export function HostScreen({
             onChangeText={setSearch}
             placeholder="Search worktrees…"
             autoFocus
-            // Why: new key each open remounts focus effect if the field stays mounted
-            // across rapid toggles; pairs with delayed focus so the keyboard appears.
+            // Why: new key per open remounts the focus effect across rapid toggles so the keyboard reappears.
             focusKey={showSearch}
             accessibilityLabel="Search worktrees"
           />
@@ -1206,13 +1138,10 @@ export function HostScreen({
           keyboardShouldPersistTaps="handled"
           keyboardDismissMode="on-drag"
           onScrollToIndexFailed={onScrollToIndexFailed}
-          // Why: edge-to-edge — the list scrolls under the system nav bar
-          // while reserving insets.bottom keeps the last worktree row reachable
-          // above the Samsung 3-button nav / iOS home indicator.
+          // Why: edge-to-edge under the system nav bar; insets.bottom keeps the last row above it.
           contentContainerStyle={[
             styles.list,
-            // Phone shows a floating "+" button bottom-right; reserve room so the
-            // last row stays tappable above it. Embedded sidebars keep the toolbar +.
+            // Reserve room so the last row stays tappable above the phone's floating "+" (embedded uses the toolbar +).
             { paddingBottom: (embedded ? spacing.lg : FAB_SIZE + spacing.xl) + insets.bottom },
             isWideLayout &&
               !embedded && { maxWidth: contentMaxWidth, width: '100%', alignSelf: 'center' }
@@ -1252,8 +1181,7 @@ export function HostScreen({
             )
           }}
           ItemSeparatorComponent={ListSeparator}
-          // Why (#8498): manual pull-to-refresh forces a fresh worktree
-          // snapshot after a reconnect or whenever the cache looks stale.
+          // Why (#8498): manual pull-to-refresh forces a fresh snapshot after a stale-cache reconnect.
           refreshControl={
             <RefreshControl
               refreshing={refreshing}
@@ -1478,10 +1406,7 @@ export function HostScreen({
   )
 }
 
-// Default route export. On wide tablet/foldable canvases the worktree list is
-// rendered as a persistent sidebar by the host layout, so the route itself
-// becomes the empty detail pane until a workspace is opened. On phones it is
-// the full-screen worktree list as before.
+// On wide layouts the sidebar hosts the list, so this route is just the empty detail pane.
 export default function HostWorktreeRoute() {
   const { isWideLayout } = useResponsiveLayout()
   if (isWideLayout) {
diff --git a/mobile/app/h/[hostId]/session/[worktreeId].tsx b/mobile/app/h/[hostId]/session/[worktreeId].tsx
index 08f1f16ae8a..bd361b93c63 100644
--- a/mobile/app/h/[hostId]/session/[worktreeId].tsx
+++ b/mobile/app/h/[hostId]/session/[worktreeId].tsx
@@ -284,8 +284,7 @@ function MarkdownReader({
   onDiscard: () => void
   keyboardLift: number
 }) {
-  // The editor lives in a WebView; native Keyboard events under-report its
-  // covered area, so prefer the inset measured inside the WebView when larger.
+  // Native Keyboard events under-report the WebView editor's covered area, so prefer the larger WebView-measured inset.
   const [webviewKeyboardInset, setWebviewKeyboardInset] = useState(0)
   const effectiveKeyboardLift = Math.max(keyboardLift, webviewKeyboardInset)
   if (!doc || doc.status === 'loading') {
@@ -333,8 +332,7 @@ function MarkdownReader({
           pointerEvents="box-none"
           style={[
             styles.markdownFloatingBar,
-            // Why: the editor focus lives inside a WebView, so keep native
-            // Save/Discard controls lifted instead of resizing that surface.
+            // Why: editor focus lives in a WebView, so lift native Save/Discard controls instead of resizing it.
             {
               bottom: resolveMarkdownFloatingActionsBottom({
                 keyboardLift: effectiveKeyboardLift,
@@ -423,8 +421,7 @@ function DiffLineRow({
   const commentLine = line.newLineNumber
   const isCommenting = commentLine !== undefined && activeCommentLine === commentLine
   const canComment = commentLine !== undefined
-  // Why: review notes are anchored to the modified side, so the single mobile
-  // gutter should show the same line number the note will reference.
+  // Why: review notes anchor to the modified side, so show that line number in the single mobile gutter.
   const gutterLineNumber = line.newLineNumber ?? line.oldLineNumber ?? ''
   return (
     <View style={styles.diffLineBlock}>
@@ -647,8 +644,7 @@ function FileReader({
       return undefined
     }
 
-    // Why: highlighting can create many nested Text nodes; defer it one tick so
-    // large files show immediately as plain text before colors are applied.
+    // Why: defer highlighting one tick so large files show as plain text immediately before colors are applied.
     const timer = setTimeout(() => {
       // file + html share the syntax-segment source view (html's "Source" toggle).
       if (doc.kind === 'file' || doc.kind === 'html') {
@@ -822,8 +818,7 @@ export default function SessionScreen() {
   const isFolderWorkspaceRoute = worktreeId.startsWith('folder:') // Synthetic ids have no repo scope.
   const router = useRouter()
   const insets = useSafeAreaInsets()
-  // Why: shared client per host owned by RpcClientProvider. See
-  // docs/mobile-shared-client-per-host.md.
+  // Why: shared client per host owned by RpcClientProvider (docs/mobile-shared-client-per-host.md).
   const { client, state: connState } = useHostClient(hostId)
   const reconnectAttempts = useReconnectAttempt(hostId)
   const lastConnectedAt = useLastConnectedAt(hostId)
@@ -834,8 +829,7 @@ export default function SessionScreen() {
     routeName: routeWorktreeName,
     worktreeId
   })
-  // Master-detail host state (U5/KTD2): on wide layouts a tapped panel docks beside the
-  // session content; on narrow it stays null and the icons push full-screen routes.
+  // Master-detail state: wide layouts dock a tapped panel beside the session; narrow keeps it null and pushes full-screen routes.
   const { isWideLayout } = useResponsiveLayout()
   const [activePanel, setActivePanel] = useState<ActivePanel>(null)
   const [sessionContentRowWidth, setSessionContentRowWidth] = useState(0)
@@ -844,17 +838,13 @@ export default function SessionScreen() {
     availableWidth: sessionContentRowWidth,
     dockWidth: HOST_DOCK_MIN_WIDTH
   })
-  // Why: docking needs enough measured row width. If rotation/split-screen makes
-  // the session row too narrow while a panel is docked, clear activePanel so the
-  // icon state and live mounted panel do not survive into overlay/push mode.
+  // Why: if rotation/split-screen makes the docked row too narrow, clear activePanel so it doesn't survive into overlay/push mode.
   useEffect(() => {
     if (!canDockPanel && activePanel !== null) {
       setActivePanel(null)
     }
   }, [canDockPanel, activePanel])
-  // Session-level GitHub remote probe gates the PR dock icon so non-GitHub
-  // providers do not open the hosted-review surface. Branch/head/status for the
-  // hub are loaded inside MobileSourceControlPanel — skip the unused identity RPCs.
+  // GitHub remote probe gates the PR dock icon so non-GitHub providers can't open the hosted-review surface; skip the unused identity RPCs.
   const { isGithubRepo: prIsGithubRepo, repoLoaded: prRepoContextLoaded } =
     useMobilePrBranchContext({
       client,
@@ -872,23 +862,15 @@ export default function SessionScreen() {
   const terminalsRef = useRef<Terminal[]>([])
   const [sessionTabs, setSessionTabs] = useState<MobileSessionTab[]>([])
   const sessionTabsRef = useRef<MobileSessionTab[]>([])
-  // Why: subscription, 2s polling, and post-mutation refetch race to apply tab
-  // snapshots. Track the last applied (publicationEpoch, snapshotVersion) so a
-  // late-arriving older snapshot from the same publisher can't overwrite (and
-  // resurrect closed tabs in) a newer one. See session-tab-snapshot-gate.
+  // Why: track the last applied (epoch, version) so a late older snapshot can't overwrite a newer one and resurrect closed tabs (session-tab-snapshot-gate).
   const appliedSnapshotMarkerRef = useRef<AppliedSnapshotMarker>({ epoch: null, version: -1 })
-  // Why: after an optimistic local close, suppress the tab until the publisher
-  // confirms its absence, so an in-flight snapshot generated before the close
-  // propagated (and thus newer by version) can't flash the tab back. Maps tab id
-  // to an expiry timestamp so a failed host-side close can't hide a tab forever.
+  // Why: after an optimistic close, suppress the tab (with expiry) until the publisher confirms, so an in-flight snapshot can't flash it back.
   const closedTabTombstonesRef = useRef<Map<string, number>>(new Map())
   const [terminalsLoaded, setTerminalsLoaded] = useState(false)
   const [input, setInput] = useState('')
-  // Why: baseline terminal zoom, reloaded on focus so a Settings → Terminal change
-  // applies in place (the terminal panes stay mounted).
+  // Why: baseline terminal zoom reloaded on focus so a Settings → Terminal change applies in place (panes stay mounted).
   const [terminalTextScale, setTerminalTextScale] = useState(1)
-  // Why: local opt-in for keyboard autocomplete/autocorrect on the terminal
-  // command bar; reloaded on focus so a Settings → Terminal toggle takes effect on return.
+  // Why: terminal command-bar autocomplete opt-in, reloaded on focus so a Settings → Terminal toggle takes effect on return.
   const [autocompleteEnabled, setAutocompleteEnabled] = useState(false)
   const [terminalLinkOpenMode, setTerminalLinkOpenMode] =
     useState<MobileTerminalLinkOpenMode>('orca-browser')
@@ -904,8 +886,7 @@ export default function SessionScreen() {
   const [activeHandle, setActiveHandle] = useState<string | null>(null)
   const [activeSessionTabId, setActiveSessionTabId] = useState<string | null>(null)
   const activeSessionTabIdRef = useRef<string | null>(null)
-  // Auto-scroll the tab strip so the active tab (synced from desktop on
-  // worktree entry) is revealed without a manual scroll.
+  // Auto-scroll the tab strip so the desktop-synced active tab is revealed without a manual scroll.
   const tabStripRef = useRef<ScrollView>(null)
   const tabStripOffsetRef = useRef(0)
   const tabStripViewportWidthRef = useRef(0)
@@ -920,9 +901,7 @@ export default function SessionScreen() {
   const [pendingDiffNotesDelivery, setPendingDiffNotesDelivery] =
     useState<DiffNotesDelivery | null>(null)
   const [creating, setCreating] = useState(false)
-  // Why: React state isn't a synchronous lock — a fast double-tap can fire two
-  // creates before `creating` re-renders. This ref blocks the second one in the
-  // same tick (server idempotency only dedupes identical clientMutationIds).
+  // Why: React state isn't a synchronous lock; this ref blocks a double-tap's second create in the same tick before `creating` re-renders.
   const creatingTerminalRef = useRef(false)
   const [creatingBrowser, setCreatingBrowser] = useState(false)
   const [creatingMarkdown, setCreatingMarkdown] = useState(false)
@@ -966,14 +945,9 @@ export default function SessionScreen() {
     () => getVisibleTerminalAccessoryKeys(visibleBuiltInIds),
     [visibleBuiltInIds]
   )
-  // Why: in Expo SDK 55 edge-to-edge mode the OS does NOT resize the window when
-  // the IME opens — the keyboard draws on top of the app. We track the keyboard
-  // height ourselves and translate the input/accessory area above the IME without
-  // changing the terminal frame height, so keyboard open/close does not resize
-  // the desktop PTY.
+  // Why: Expo SDK 55 edge-to-edge doesn't resize the window on IME open, so track keyboard height ourselves and lift the input without resizing the desktop PTY.
   const [keyboardHeight, setKeyboardHeight] = useState(0)
-  // Why: server-authoritative display mode per terminal. The runtime is the
-  // single source of truth — this state is populated from subscribe responses.
+  // Why: server-authoritative display mode per terminal, populated from subscribe responses.
   const [terminalModes, setTerminalModes] = useState<Map<string, MobileDisplayMode>>(new Map())
   const [terminalKeyboardMetrics, setTerminalKeyboardMetrics] = useState<
     Map<string, TerminalKeyboardAvoidanceMetrics>
@@ -981,15 +955,13 @@ export default function SessionScreen() {
   const [selectModeActive, setSelectModeActive] = useState(false)
   const [canPaste, setCanPaste] = useState(false)
   const [showDictationSetup, setShowDictationSetup] = useState(false)
-  // 'hold' makes the mic press-and-hold; 'toggle' makes it tap-to-start/stop.
-  // Mirrors Settings ▸ Voice ▸ Dictation Mode so the button matches the setting.
+  // 'hold' = press-and-hold mic, 'toggle' = tap-to-start/stop; mirrors Settings ▸ Voice ▸ Dictation Mode.
   const [dictationMode, setDictationMode] = useState<'toggle' | 'hold'>('toggle')
   const [toastMessage, setToastMessage] = useState<string | null>(null)
   const toastOpacityRef = useRef(new Animated.Value(0))
   const toastHideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const toastSeqRef = useRef(0)
-  // Why: WebView pushes terminal modes (bracketed-paste, alt-screen) on every
-  // change so paste reads a synchronous snapshot — no round-trip required.
+  // Why: WebView pushes terminal modes on every change so paste reads a synchronous snapshot — no round-trip.
   const ptyModesRef = useRef<Map<string, TerminalModes>>(new Map())
   const terminalGestureInputBucketsRef = useRef<Map<string, TerminalGestureInputBucket>>(new Map())
   const terminalGestureInputQueuesRef = useRef<Map<string, TerminalGestureInputQueue>>(new Map())
@@ -997,13 +969,11 @@ export default function SessionScreen() {
   const terminalCwdRef = useRef<Map<string, string>>(new Map())
   const initialModesSeenRef = useRef<Set<string>>(new Set())
   const deviceTokenRef = useRef<string | null>(null)
-  // Why: state (not a ref) — the connection verdict needs a re-render once
-  // the endpoint loads so the Tailscale hint can appear.
+  // Why: state (not a ref) so the connection verdict re-renders when the endpoint loads and the Tailscale hint can appear.
   const [hostEndpoint, setHostEndpoint] = useState<string | null>(null)
   const clientRef = useRef<RpcClient | null>(null)
   const connStateRef = useRef<ConnectionState>(connState)
-  // Why: measured once from TerminalWebView on mount, then passed with every
-  // subscribe call so the server can auto-fit the PTY to phone dimensions.
+  // Why: measured once on mount, then passed with every subscribe so the server can auto-fit the PTY to phone dims.
   const viewportRef = useRef<{ cols: number; rows: number } | null>(null)
   const viewportMeasuredRef = useRef(false)
   const terminalRefs = useRef<Map<string, TerminalWebViewHandle>>(new Map())
@@ -1023,53 +993,31 @@ export default function SessionScreen() {
   const subscribingHandlesRef = useRef<Set<string>>(new Set())
   const initializedHandlesRef = useRef<Set<string>>(new Set())
   const terminalDiagnosticsRef = useRef(new MobileTerminalDiagnostics())
-  // Why: WebViews load xterm.js from CDN asynchronously. Hidden WebViews
-  // (opacity:0) may have delayed JS execution on iOS. We must not subscribe
-  // until the WebView has fired web-ready, otherwise init() messages queue
-  // and may not render reliably.
+  // Why: don't subscribe until the WebView fires web-ready — iOS may defer JS in hidden WebViews and init() messages would queue unrendered.
   const webReadyHandlesRef = useRef<Set<string>>(new Set())
   const activeHandleRef = useRef<string | null>(null)
   const activeSessionTabTypeRef = useRef<MobileSessionTabType | null>(null)
   const pendingActiveSessionTabIdRef = useRef<string | null>(null)
   const pendingActiveTerminalHandleRef = useRef<string | null>(null)
-  // Why: a browser tab opened from a terminal-tapped HTML must be focused as an
-  // Orca session tab (bridge auto-activate only flags the live webContents, not
-  // the app-level active tab). We remember the page id and, once its session tab
-  // syncs, activate it through the normal switchSessionTab path (which also makes
-  // switching back to the terminal work). A ref breaks the callback dep cycle.
+  // Why: remember the page id to activate its session tab once it syncs (bridge auto-activate flags only webContents, not the app-level active tab).
   const pendingBrowserFocusPageIdRef = useRef<string | null>(null)
   const switchSessionTabRef = useRef<((tab: MobileSessionTab) => void) | null>(null)
   const pendingTerminalActivationAttemptRef = useRef<string | null>(null)
-  // Why: handleTerminalOpenUrl is memoized on terminalLinkOpenMode, but
-  // handleCreateBrowser is a per-render closure that captures the live `client`.
-  // A terminal URL tap must run the CURRENT closure (the memoized one can hold a
-  // render where client was still null/connecting, silently no-opping the
-  // in-app-browser open). Route through a ref kept current every render.
+  // Why: route the terminal URL tap through a ref so it runs the current handleCreateBrowser closure (the memoized one may hold a null-client render).
   const handleCreateBrowserRef = useRef<((rawUrl?: string) => Promise<boolean>) | null>(null)
 
   const initialEmptySessionAutoCreateRef = useRef<string | null>(null)
   const markdownSaveSeqRef = useRef<Map<string, number>>(new Map())
   const markdownSaveInFlightRef = useRef<Set<string>>(new Set())
   const subscribeSeqRef = useRef<Map<string, number>>(new Map())
-  // Why: post-RPC refresh timers capture this screen and must not survive
-  // route reuse or unmount.
+  // Why: post-RPC refresh timers capture this screen and must not survive route reuse or unmount.
   const delayedActionTimersRef = useRef<Set<ReturnType<typeof setTimeout>>>(new Set())
-  // Why: server-side layout state machine emits a monotonic seq on every
-  // applyLayout. Track the highest seq we've observed per handle and drop
-  // any scrollback/resized event with a strictly older seq — these are
-  // late-arriving events from a superseded layout (e.g. phone-fit dims
-  // landing after the user toggled to desktop). Drops below `>20`-window
-  // gap reset (treat as a fresh subscription, e.g. server restart).
+  // Why: highest applyLayout seq seen per handle; drop older scrollback/resized as stale, but a >20 gap resets (fresh subscription/server restart).
   const layoutSeqRef = useRef<Map<string, number>>(new Map())
   const sendingRef = useRef(false)
-  // Why: tracks the pixel height of the terminal frame so measureFitDimensions
-  // can use the exact container height instead of relying on window.innerHeight,
-  // which can overstate the visible area due to layout timing.
+  // Why: exact terminal-frame height for measureFitDimensions; window.innerHeight can overstate the visible area.
   const terminalFrameHeightRef = useRef<number>(0)
-  // Why: the terminal frame's width changes when EITHER sidebar is resized (the
-  // left worktree sidebar shrinks the detail pane; the right dock takes a slice of
-  // the row) without any window-dim change. Tracking the measured width lets the
-  // refit hook re-fit the PTY on those resizes — see terminal-viewport-refit.ts.
+  // Why: sidebar resizes change the terminal frame width without a window-dim change; track it so the refit hook re-fits (see terminal-viewport-refit.ts).
   const [terminalFrameWidth, setTerminalFrameWidth] = useState(0)
   const activeSessionTab = sessionTabs.find((tab) => tab.id === activeSessionTabId) ?? null
   const {
@@ -1098,9 +1046,7 @@ export default function SessionScreen() {
     activeSessionTab?.type !== 'browser'
   const liveInputEnabled = activeHandle ? liveInputTerminalHandles.has(activeHandle) : false
   const [browserScreencastSupported, setBrowserScreencastSupported] = useState<boolean | null>(null)
-  // Why: hosts without aiVault.v1 reject aiVault.listSessions, so the header
-  // entry stays hidden there (mirrors the gated host-list action) instead of
-  // opening a dead-end "update this host" panel.
+  // Why: hosts without aiVault.v1 reject listSessions, so hide the header entry instead of a dead-end "update this host" panel.
   const [agentSessionHistorySupported, setAgentSessionHistorySupported] = useState<boolean | null>(
     null
   )
@@ -1109,8 +1055,7 @@ export default function SessionScreen() {
   // the capability probe resolves after the callbacks are created.
   const browserScreencastSupportedRef = useRef(browserScreencastSupported)
   browserScreencastSupportedRef.current = browserScreencastSupported
-  // Why: terminal gesture/input callbacks are intentionally stable and
-  // imperative; keep their refs current before commit instead of one effect later.
+  // Why: terminal gesture/input callbacks are stable/imperative, so keep their refs current before commit, not in a later effect.
   clientRef.current = client
   connStateRef.current = connState
   activeSessionTabTypeRef.current = activeSessionTab?.type ?? null
@@ -1121,8 +1066,7 @@ export default function SessionScreen() {
     createWarningState,
     initialCreateWarning
   )
-  // Why: Expo can reuse this screen for a new route. Reconcile before paint
-  // so a dismissed old creation warning never flashes for the next session.
+  // Why: Expo can reuse this screen for a new route; reconcile before paint so a dismissed old warning doesn't flash.
   if (reconciledCreateWarningState !== createWarningState) {
     setCreateWarningState(reconciledCreateWarningState)
   }
@@ -1214,8 +1158,7 @@ export default function SessionScreen() {
     client,
     enabled: canSend,
     onTranscript: (text) => {
-      // Why: dictation belongs to the visible composer. Native chat consumes it
-      // locally; terminal mode retains the live-input routing and flush contract.
+      // Why: dictation belongs to the visible composer — native chat consumes it locally, terminal mode keeps live-input routing.
       if (showNativeChatRef.current) {
         nativeChatController.setChatComposerText((current) =>
           appendBufferedDictation(current, text)
@@ -1223,9 +1166,7 @@ export default function SessionScreen() {
         showToast('Dictation inserted')
         return
       }
-      // Live mode inserts the transcript straight into its originating PTY as
-      // text (no Return — the user sends it themselves), matching live keystroke
-      // semantics; buffered mode keeps appending to the command field.
+      // Live mode inserts the transcript into its PTY as text (no Return); buffered mode appends to the command field.
       const routeContext = dictationRouteContextRef.current
       dictationRouteContextRef.current = null
       const route = routeDictationTranscript(
@@ -1254,8 +1195,7 @@ export default function SessionScreen() {
     },
     onError: (err) => {
       dictationRouteContextRef.current = null
-      // Dictation isn't set up on the desktop yet → open the setup sheet so the
-      // user can download a model + enable it from here, instead of a dead-end toast.
+      // Dictation not set up on desktop → open the setup sheet instead of a dead-end toast.
       if (isDictationSetupRequiredError(err.message)) {
         setShowDictationSetup(true)
         return
@@ -1325,8 +1265,7 @@ export default function SessionScreen() {
     }
   }, [client])
 
-  // Re-read on focus so a Dictation Mode change made in Settings ▸ Voice is
-  // reflected when the user returns to the session.
+  // Re-read on focus so a Settings ▸ Voice dictation-mode change is reflected on return.
   useFocusEffect(
     useCallback(() => {
       void refreshDictationMode()
@@ -1348,9 +1287,7 @@ export default function SessionScreen() {
       subscribingHandlesRef.current.delete(handle)
       terminalDiagnosticsRef.current.terminalUnsubscribed(handle)
       subscribeSeqRef.current.set(handle, (subscribeSeqRef.current.get(handle) ?? 0) + 1)
-      // Why: a fresh subscription will land on a new server-side state machine
-      // run (or the same one with a higher seq); reset the high-water mark so
-      // the first scrollback isn't accidentally dropped as stale.
+      // Why: reset the high-water mark so a fresh subscription's first scrollback isn't dropped as stale.
       layoutSeqRef.current.delete(handle)
       clearNativeChatInputLease(handle)
     },
@@ -1376,9 +1313,7 @@ export default function SessionScreen() {
     }
   }, [clearNativeChatInputLease])
 
-  // Why: measures the phone viewport once from the first available TerminalWebView.
-  // The viewport dims are passed with every subscribe call so the server can
-  // auto-fit the PTY without a separate RPC round-trip.
+  // Why: measure the phone viewport once from the first TerminalWebView; dims ride every subscribe so the server auto-fits without a separate RPC.
   const measureViewportOnce = useCallback(
     async (handle: string) => {
       if (viewportMeasuredRef.current) {
@@ -1418,8 +1353,7 @@ export default function SessionScreen() {
         activeHandleRef.current,
         handle
       )
-      // Why: a native-chat-covered terminal subscribes as the input-floor lease
-      // without a mounted xterm webview, so only gate on the webview when NOT covered.
+      // Why: a native-chat-covered terminal has no mounted webview, so only gate on the webview when not covered.
       if (!covered) {
         if (!getTerminalRef(handle)) {
           logSkippedGate('no-webview-ref')
@@ -1436,10 +1370,7 @@ export default function SessionScreen() {
       subscribeSeqRef.current.set(handle, seq)
       diagnostics.streamArmed(handle, seq, viewportRef.current)
 
-      // Why: server handles auto-fit on subscribe — no terminal.focus call needed.
-      // The viewport is embedded in the subscribe params so the server resizes
-      // the PTY before serializing scrollback. This eliminates the focus→safeFit
-      // race and the measure→resize→resubscribe pipeline.
+      // Why: viewport is embedded in the subscribe params so the server auto-fits before serializing scrollback (no focus→safeFit race).
       const unsub = subscribeMobileTerminalSafely(
         client,
         {
@@ -1462,8 +1393,7 @@ export default function SessionScreen() {
             markNativeChatInputLeaseReady(handle)
             return
           }
-          // Why: retain the subscription as the mobile input-floor lease, but
-          // do not mutate covered xterm state; return-to-terminal resubscribes.
+          // Why: keep the subscription as the input-floor lease but don't mutate covered xterm state; return-to-terminal resubscribes.
           if (
             nativeChatTerminalStream.isTerminalCoveredByNativeChat(
               showNativeChatRef.current,
@@ -1473,15 +1403,7 @@ export default function SessionScreen() {
           ) {
             return
           }
-          // Why: stale-event filter. Server-side state machine bumps a
-          // monotonic seq on every applyLayout. Drop `resized` events
-          // whose seq is strictly older than what we've already observed
-          // for this handle — they're late-arriving from a superseded
-          // layout. `scrollback` is the response to a fresh subscribe,
-          // so it always resets the high-water mark regardless of seq
-          // (post-WS-reconnect or post-resubscribe the server may emit
-          // scrollback at a seq lower than what we'd seen pre-reconnect;
-          // dropping it would leave the user with a blank terminal).
+          // Why: drop `resized` events older than the seen seq (superseded layout); scrollback always resets the mark, else reconnect blanks the terminal.
           const eventSeq = typeof data.seq === 'number' ? data.seq : null
           if (eventSeq != null && data.type === 'resized') {
             const last = layoutSeqRef.current.get(handle)
@@ -1517,11 +1439,7 @@ export default function SessionScreen() {
                 : ''
             const oscLinks = isTerminalOscLinkRanges(data.oscLinks) ? data.oscLinks : undefined
             const ref = getTerminalRef(handle)
-            // Why: previously we set `initializedHandlesRef` even when the
-            // WebView wasn't mounted yet (ref=null). The init message went
-            // nowhere, but the flag stayed true, so any subsequent scrollback
-            // for THIS handle was silently dropped → blank terminal. Only
-            // mark initialized if init() actually reached the WebView.
+            // Why: only mark initialized once init() reaches the WebView, else later scrollback is dropped and the terminal stays blank.
             if (!ref) {
               console.log('[fit][session] scrollback DROPPED — no terminal ref', {
                 handle: handle.slice(-8),
@@ -1537,21 +1455,9 @@ export default function SessionScreen() {
                 new Map(prev).set(handle, data.displayMode as MobileDisplayMode)
               )
             }
-            // Why: belt-and-suspenders cold-start fit. The applyFitScale
-            // queued by init() runs after writes drain, but on cold start
-            // xterm's scrollWidth can still be transient when it commits.
-            // Re-fire after a short delay so it runs against a settled DOM.
-            // Mirrors the 'resized' handler below.
+            // Why: cold-start refit — init()'s fit can run against a transient scrollWidth, so re-fire against a settled DOM.
             scheduleDelayedAction(() => getTerminalRef(handle)?.resetZoom(), 200)
-            // Why: viewport measurement needs xterm to be initialized (cell
-            // dimensions come from the renderer). On the first subscribe the
-            // WebView hasn't loaded yet, so viewportRef is null and the server
-            // can't auto-fit. After the first init we can measure, then
-            // resubscribe so the server gets the viewport and phone-fits.
-            // If viewport was measured by a parallel path BUT the scrollback
-            // we just received came back at desktop dims, our subscribe
-            // beat the measure; the server still has a null viewport for
-            // this subscriber record — resubscribe so it gets stored.
+            // Why: first subscribe has no viewport (xterm not loaded yet), so measure after init and resubscribe so the server can phone-fit.
             const needsResubscribe =
               !viewportMeasuredRef.current ||
               (viewportRef.current != null &&
@@ -1559,14 +1465,7 @@ export default function SessionScreen() {
                   scrollbackRows !== viewportRef.current.rows))
             if (needsResubscribe) {
               void (async () => {
-                // Why: wait for the WebView's init() rAF chain to fully
-                // run (term.open → renderService population → first
-                // paint) before measuring. Without this, the measure
-                // postMessage races ahead of init's async work and
-                // returns null (term not ready / cells size 0), the
-                // resubscribe never fires, and the server never gets
-                // phone dims. See log dump 2026-05-06 confirming the
-                // race + measure-result null pattern.
+                // Why: wait for init()'s rAF chain before measuring, else the measure races ahead and returns null (log dump 2026-05-06).
                 await getTerminalRef(handle)?.awaitReady()
                 if (subscribeSeqRef.current.get(handle) !== seq) {
                   return
@@ -1574,25 +1473,14 @@ export default function SessionScreen() {
                 const dims = await getTerminalRef(handle)?.measureFitDimensions(
                   terminalFrameHeightRef.current || undefined
                 )
-                // Why: re-check seq after the awaits — awaitReady (up to
-                // 3s) and measureFitDimensions can take hundreds of ms,
-                // during which a newer subscribe cycle may have armed
-                // its own subscription. Tearing it down here would reset
-                // the freshly-armed initialized flag and re-subscribe a
-                // stale generation.
+                // Why: re-check seq — the awaits may have let a newer subscribe cycle arm; tearing it down would resubscribe a stale generation.
                 if (subscribeSeqRef.current.get(handle) !== seq) {
                   return
                 }
                 if (!getTerminalRef(handle)) {
                   return
                 }
-                // Why: we just got `scrollback` with cols=80 (server's
-                // default fallback for null viewport). That means the
-                // server-side subscriber record was registered before we
-                // could send viewport. Even if `viewportMeasuredRef`
-                // raced ahead via a parallel `measureViewportOnce`, the
-                // server still has a null viewport for THIS subscriber
-                // record — we MUST resubscribe so the server stores it.
+                // Why: scrollback came back at cols=80 (server's null-viewport fallback), so this subscriber record has no viewport — resubscribe so the server stores it.
                 if (dims) {
                   diagnostics.streamResubscribing(handle, seq, dims)
                   viewportRef.current = dims
@@ -1607,11 +1495,7 @@ export default function SessionScreen() {
             updateTerminalCwdFromStreamEvent(handle, data, terminalCwdRef.current)
           } else if (data.type === 'data') {
             updateTerminalCwdFromStreamEvent(handle, data, terminalCwdRef.current)
-            // Why: log when data arrives but the WebView ref is missing
-            // — this is the most likely cause of "blank but input works":
-            // server stream is alive, sends flow, but writes are dropped
-            // because the WebView ref disappeared (unmount mid-flight) or
-            // the scrollback never landed (so xterm has no buffer).
+            // Why: missing ref is the likely cause of "blank but input works" — writes dropped after mid-flight unmount or scrollback never landed.
             const dataRef = getTerminalRef(handle)
             if (!dataRef) {
               console.log('[fit][session] data DROPPED — no terminal ref', {
@@ -1630,12 +1514,7 @@ export default function SessionScreen() {
             dataRef.write(data.chunk as string)
           } else if (data.type === 'resized') {
             updateTerminalCwdFromStreamEvent(handle, data, terminalCwdRef.current)
-            // Why: inline resize event — the server changed the PTY dimensions
-            // (mode toggle, desktop restore, or a width reflow). When the server
-            // includes a fresh full-buffer snapshot (width reflow), reinitialize
-            // xterm at the new dims so the hard-wrapped scrollback rewraps;
-            // preserve the reader's scroll position across the replay. Otherwise
-            // resize xterm geometry and let the TUI's own redraw repaint.
+            // Server resize: reinit xterm on a full-buffer snapshot (width reflow rewraps scrollback), else just resize geometry.
             const cols = (data.cols as number) || 80
             const rows = (data.rows as number) || 24
             const serialized = typeof data.serialized === 'string' ? data.serialized : null
@@ -1679,9 +1558,7 @@ export default function SessionScreen() {
     unsubscribe: unsubscribeTerminal
   })
 
-  // Why: toggles between phone and desktop mode via server RPC. The server
-  // handles the actual resize and emits a 'resized' event on the existing
-  // subscription stream — no client-side state tracking needed.
+  // Why: server does the resize and emits 'resized' on the existing subscription — no client-side state tracking needed.
   const toggleInFlightRef = useRef<Set<string>>(new Set())
   const toggleDisplayMode = useCallback(
     async (handle: string) => {
@@ -1692,8 +1569,7 @@ export default function SessionScreen() {
         return
       }
       const current = terminalModes.get(handle) ?? 'auto'
-      // Why: 'phone' on the wire is an observation ("currently phone-fitted"),
-      // not a setting. The toggle only ever requests 'auto' or 'desktop'.
+      // Why: 'phone' is an observed state, not a setting; the toggle only requests 'auto' or 'desktop'.
       const next: 'auto' | 'desktop' =
         current === 'auto' || current === 'phone' ? 'desktop' : 'auto'
       toggleInFlightRef.current.add(handle)
@@ -1701,14 +1577,11 @@ export default function SessionScreen() {
         await client.sendRequest('terminal.setDisplayMode', {
           terminal: handle,
           mode: next,
-          // Why: presence-lock take-floor signal — requesting 'auto' is the
-          // explicit "I want to drive at phone dims" gesture.
+          // Why: presence-lock take-floor — requesting 'auto' is the explicit "drive at phone dims" gesture.
           ...(deviceTokenRef.current
             ? { client: { id: deviceTokenRef.current, type: 'mobile' as const } }
             : {}),
-          // Why: late-bind viewport for terminals whose subscribe record
-          // was registered before measurement landed. Without this the
-          // server's stored viewport is null and auto toggles no-op.
+          // Why: late-bind viewport for terminals subscribed before measurement, or auto toggles no-op on a null stored viewport.
           ...(viewportRef.current && next === 'auto' ? { viewport: viewportRef.current } : {})
         })
       } catch {
@@ -1744,19 +1617,14 @@ export default function SessionScreen() {
           if (result.terminals.length === 0 && !allowEmptyLoaded) {
             return
           }
-          // Why: protect against transient empty responses from the server
-          // during rapid tab switching or RPC timing. If we previously had
-          // terminals and the server now says 0, require a second consecutive
-          // empty to confirm. This prevents the UI from flashing empty during
-          // rapid interactions while still allowing genuine cleanup.
+          // Why: require two consecutive empties before trusting 0, so transient empty responses don't flash the UI empty.
           if (result.terminals.length === 0 && lastKnownTerminalCountRef.current > 0) {
             lastKnownTerminalCountRef.current = 0
             return
           }
 
           const liveHandles = new Set(result.terminals.map((terminal) => terminal.handle))
-          // Why: terminal.list is the lifetime signal; session-tab snapshots can lag
-          // mobile-created tabs and must not erase a user's buffered-mode opt-out.
+          // Why: terminal.list is the lifetime signal; lagging tab snapshots must not erase a user's buffered-mode opt-out.
           pruneTerminalHandlesFromLiveInput(liveHandles)
           defaultTerminalHandlesToLiveInput([...liveHandles])
           for (const handle of Array.from(terminalUnsubsRef.current.keys())) {
@@ -1776,11 +1644,7 @@ export default function SessionScreen() {
             }
           }
           lastKnownTerminalCountRef.current = result.terminals.length
-          // Why: defense-in-depth dedupe. If the server ever returns a list
-          // with the same handle twice (race during rename/split, or stale
-          // process tracking), React would throw 'two children with same
-          // key' on render. Keep the first occurrence — list order matters
-          // for the tab strip, and createParams puts new tabs at the end.
+          // Why: dedupe duplicate handles (rename/split race) to avoid a React duplicate-key throw; keep first for tab-strip order.
           const seen = new Set<string>()
           const deduped = result.terminals.filter((t) => {
             if (seen.has(t.handle)) {
@@ -1800,8 +1664,7 @@ export default function SessionScreen() {
           )
           terminalsRef.current = mergedTerminals
 
-          // Session tabs are the UI authority. terminal.list only refreshes
-          // per-handle metadata for existing ready terminal surfaces.
+          // Session tabs are the UI authority; terminal.list only refreshes per-handle metadata for existing terminal surfaces.
         }
       } catch {
         // Failed to list terminals
@@ -1823,8 +1686,7 @@ export default function SessionScreen() {
   const applySessionTabs = useCallback(
     (result: SessionTabsResult) => {
       const diagnostics = terminalDiagnosticsRef.current
-      // Reject out-of-order snapshots, then suppress just-closed tabs until the
-      // publisher confirms their absence. See session-tab-snapshot-gate.
+      // Reject stale snapshots; suppress just-closed tabs until the publisher confirms absence — see session-tab-snapshot-gate.
       if (!acceptSessionSnapshot(result, appliedSnapshotMarkerRef.current)) {
         return
       }
@@ -1846,8 +1708,7 @@ export default function SessionScreen() {
             tab.type === 'markdown' && tab.id === tabId
         )
         if (draftTab) {
-          // Why: save-only mobile edits live only on the phone until Save. If the
-          // desktop tab disappears, keep every local draft reachable for copy/discard.
+          // Why: mobile edits live on the phone until Save; if the desktop tab vanishes, keep drafts reachable for copy/discard.
           orphanedDraftTabs.push({ ...draftTab, isActive: tabId === activeSessionTabIdRef.current })
         }
       }
@@ -1855,8 +1716,7 @@ export default function SessionScreen() {
         nextTabs = [...orphanedDraftTabs, ...nextTabs]
       }
       sessionTabsRef.current = nextTabs
-      // Why: subscribe snapshots often repeat identical tab payloads. Avoid a
-      // render loop where the subscription effect tears down and replays itself.
+      // Why: subscribe snapshots often repeat identical payloads; skip re-set to avoid a subscription teardown/replay loop.
       setSessionTabs((prev) => (mobileSessionTabsEqual(prev, nextTabs) ? prev : nextTabs))
       const terminalTabs = getTerminalRecordsFromSessionTabs(nextTabs)
       const terminalTabHandles = terminalTabs.map((terminal) => terminal.handle)
@@ -1890,8 +1750,7 @@ export default function SessionScreen() {
         } else {
           const pendingTab = nextTabs.find((tab) => tab.id === pendingActiveSessionTabId)
           if (pendingTab) {
-            // Why: desktop tab snapshots can lag a mobile tap while activate RPC
-            // is in flight. Keep the locally selected tab to avoid snapping back.
+            // Why: desktop tab snapshots can lag a mobile tap mid-activate-RPC; keep the local selection to avoid snapping back.
             active = pendingTab
             selectionSource = 'pending-tab'
           } else {
@@ -1917,9 +1776,7 @@ export default function SessionScreen() {
             selectionSource = 'pending-handle-local-ack'
           }
         } else if (pendingTerminalTab) {
-          // Why: desktop active flags can lag a mobile terminal tap. Key by
-          // terminal handle too, because fallback PTY tabs may not yet have a
-          // stable session tab id during new-worktree startup.
+          // Why: desktop active flags lag a mobile tap; key by handle too, as fallback PTY tabs lack a stable tab id at startup.
           active = pendingTerminalTab
           selectionSource = 'pending-handle-tab'
         } else if (pendingTerminalExists) {
@@ -2006,10 +1863,7 @@ export default function SessionScreen() {
         if (!shouldReadMarkdownFromDiskAfterReadTabFailure(response as RpcFailure)) {
           throw new Error((response as RpcFailure).error.message)
         }
-        // Why: a headless host (no desktop renderer) can't serve the live editor
-        // document and fails markdown.readTab with renderer_unavailable. Fall back
-        // to the on-disk file so markdown still renders read-only, matching how
-        // other file types load via files.read.
+        // Why: a headless host fails markdown.readTab (renderer_unavailable); fall back to the on-disk file for read-only render.
         const fallback = await client.sendRequest('files.read', {
           worktree: `id:${worktreeId}`,
           relativePath: tab.relativePath
@@ -2270,8 +2124,7 @@ export default function SessionScreen() {
       router.back()
       return
     }
-    // Why: Android back can arrive when this session is the root route; using
-    // replace avoids React Navigation's dev-only unhandled GO_BACK warning.
+    // Why: Android back can fire at the root route; replace avoids React Navigation's dev-only GO_BACK warning.
     router.replace(`/h/${hostId}`)
   }, [hostId, router])
 
@@ -2418,8 +2271,7 @@ export default function SessionScreen() {
       const result = (response as RpcSuccess).result as SessionTabsResult
       terminalDiagnosticsRef.current.tabsFetchSucceeded(result)
       applySessionTabs(result)
-      // Focus a just-opened browser tab once it appears in the snapshot, via the
-      // normal activate path so it sticks and the user can still switch away.
+      // Focus a just-opened browser tab when it appears, via the normal activate path so it sticks yet stays switchable.
       const pendingPageId = pendingBrowserFocusPageIdRef.current
       if (pendingPageId) {
         const browserTab = result.tabs.find(
@@ -2500,10 +2352,7 @@ export default function SessionScreen() {
     }
   }, [client, connState])
 
-  // Why: deviceToken is read from host record so feature code can pass
-  // `client.id` on subscribe/send for driver-state-machine identity.
-  // The shared client itself stays alive across screens; we just need
-  // the token alongside the client.
+  // Why: read deviceToken from host record so code can pass client.id on subscribe/send for driver-state-machine identity.
   useEffect(() => {
     if (!hostId) {
       return
@@ -2578,9 +2427,7 @@ export default function SessionScreen() {
       for (const terminalRef of terminalRefs.current.values()) {
         terminalRef.prepareForForegroundRecovery()
       }
-      // Why: iOS can resume a live WKWebView with a blank xterm backing store
-      // without firing web-ready/reconnect; invalidate the native readiness
-      // latch before replay so init waits for the document's pong.
+      // Why: iOS can resume a WKWebView with a blank xterm store and no web-ready; invalidate the latch so init waits for the pong.
       const outcome = recoverActiveTerminalAfterForeground({
         activeHandleRef,
         terminalRefs,
@@ -2597,10 +2444,7 @@ export default function SessionScreen() {
     }
   }, [scheduleDelayedAction, subscribeToTerminal, unsubscribeTerminal])
 
-  // Why: resume usually lands mid-reconnect (the socket dies after ~60-80s of
-  // background), so the recovery above defers. Re-run it once the connection
-  // is back; otherwise a blanked WKWebView whose socket was merely probed (no
-  // stream replay) stays stale until a manual tab switch.
+  // Why: resume lands mid-reconnect (socket dies in bg); re-run recovery once connected or a blanked WKWebView stays stale.
   useEffect(() => {
     if (connState !== 'connected' || !pendingForegroundRecoveryRef.current) {
       return
@@ -2620,9 +2464,7 @@ export default function SessionScreen() {
     })
   }, [connState, scheduleDelayedAction, subscribeToTerminal, unsubscribeTerminal])
 
-  // Why: viewport refits for layout changes outside the subscribe path
-  // (tab strip toggling, fold/unfold, rotation) live in a dedicated hook —
-  // see terminal-viewport-refit.ts for the full rationale.
+  // Why: non-subscribe layout refits (tab strip, fold, rotation) live in a dedicated hook — see terminal-viewport-refit.ts.
   const { notifyTerminalFrameHeight, notifyKeyboardVisibility } = useTerminalViewportRefit({
     activeHandleRef,
     terminalRefs,
@@ -2680,8 +2522,7 @@ export default function SessionScreen() {
     }
   }, [])
 
-  // Reveal the active tab whenever it changes (e.g. desktop's open tab synced on
-  // worktree entry). Defer one frame so freshly mounted tab layouts are recorded.
+  // Reveal the active tab on change; defer one frame so freshly mounted tab layouts are recorded.
   useEffect(() => {
     const id = requestAnimationFrame(() => scrollActiveTabIntoView(activeSessionTabId, true))
     return () => cancelAnimationFrame(id)
@@ -2711,9 +2552,7 @@ export default function SessionScreen() {
   }, [router])
 
   useEffect(() => {
-    // Why: Expo can reuse this screen across worktrees. Reset pending
-    // keyboard listeners, snapshot floors, and tombstones so prior route state
-    // cannot open stale UI or reject the next worktree's first snapshot.
+    // Why: Expo reuses this screen across worktrees; reset route state so it can't open stale UI or reject the next snapshot.
     sessionTabActionSheetRequestSeqRef.current += 1
     sessionTabActionSheetKeyboardHideSubRef.current?.remove()
     sessionTabActionSheetKeyboardHideSubRef.current = null
@@ -2762,18 +2601,11 @@ export default function SessionScreen() {
     if (connState !== 'connected') {
       return
     }
-    // Why: the RPC client auto-resends terminal.subscribe on reconnect.
-    // Keep the current xterm visible while the binary snapshot hydrates,
-    // instead of clearing to a blank "Loading terminals" surface.
+    // Why: keep the current xterm visible while the reconnect snapshot hydrates, not a blank "Loading terminals" surface.
     if (initializedHandlesRef.current.size === 0) {
       setTerminalsLoaded(false)
     }
-    // Why: on reconnect the RPC client auto-resends terminal.subscribe and
-    // the server sends a fresh scrollback frame. The subscribe handler drops
-    // scrollback when initializedHandlesRef already contains the handle, so
-    // we'd keep stale pre-disconnect content (and lose any output emitted
-    // during the disconnect). Clear the flag so the fresh snapshot calls
-    // ref.init(...) and replaces the buffer.
+    // Why: clear the initialized flag so the reconnect scrollback replaces stale content instead of being dropped.
     initializedHandlesRef.current.clear()
     let disposed = false
     const timers: ReturnType<typeof setTimeout>[] = []
@@ -2790,8 +2622,7 @@ export default function SessionScreen() {
         }
       }
       if (client && created !== '1') {
-        // Why: mobile needs host-owned tabs hydrated for this route, but should
-        // not pull other paired clients, especially desktop, into this worktree.
+        // Why: hydrate host-owned tabs without pulling other paired clients (esp. desktop) into this worktree.
         void client
           .sendRequest('worktree.activate', {
             worktree: `id:${worktreeId}`,
@@ -2882,8 +2713,7 @@ export default function SessionScreen() {
       }
       void fetchSessionTabs()
       void fetchTerminals()
-      // Why: the live tab subscription stays mounted for stream ownership,
-      // but the fallback list poll should stop while this route is hidden.
+      // Why: live subscription keeps stream ownership, but the fallback list poll should stop while this route is hidden.
       const interval = setInterval(() => {
         void fetchSessionTabs()
         void fetchTerminals()
@@ -2892,8 +2722,7 @@ export default function SessionScreen() {
     }, [connState, fetchSessionTabs, fetchTerminals])
   )
 
-  // Why: pick up the Settings → Terminal text size when returning here — the
-  // terminal panes stay mounted, so they update in place.
+  // Why: pick up Settings → Terminal text size on return; panes stay mounted and update in place.
   useFocusEffect(
     useCallback(() => {
       let active = true
@@ -2938,10 +2767,7 @@ export default function SessionScreen() {
     }, [])
   )
 
-  // Why: unsubscribe the old terminal so the server restores its desktop dims
-  // (clearing the phone-fit banner), then subscribe the new terminal with the
-  // measured viewport so the server phone-fits it. Also call terminal.focus
-  // so the desktop renderer follows the mobile user's active terminal.
+  // Why: unsubscribe restores old dims (clears phone-fit banner); resubscribe phone-fits the new one; terminal.focus makes desktop follow.
   const switchTab = useCallback(
     (handle: string) => {
       triggerSelection()
@@ -2971,8 +2797,7 @@ export default function SessionScreen() {
       if (client) {
         void focusMobileTerminal(client, handle).catch(() => {})
         if (matchingTab) {
-          // Why: persist selection for headless hosts; the snapshot gate keeps
-          // this phone-local acknowledgement from impersonating desktop focus.
+          // Why: persist selection for headless hosts; snapshot gate stops this phone-local ack from impersonating desktop focus.
           void activateMobileSessionTab(client, {
             worktree: `id:${worktreeId}`,
             tabId: matchingTab.id,
@@ -3052,20 +2877,15 @@ export default function SessionScreen() {
       if (cached?.status === 'ready' && cached.isDirty) {
         return
       }
-      // Why: desktop clean saves do not carry a reliable content version in the
-      // lightweight tab list. Re-read on revisit unless the phone has a draft.
+      // Why: tab list lacks a reliable version for desktop clean saves; re-read on revisit unless the phone has a draft.
       void readMarkdownTab(tab)
     },
     [client, markdownDocs, readFileTab, readMarkdownTab, switchTab, unsubscribeTerminal, worktreeId]
   )
-  // Keep the ref pointing at the latest switchSessionTab so fetchSessionTabs can
-  // activate a freshly-synced browser tab without a callback dependency cycle.
+  // Ref to latest switchSessionTab so fetchSessionTabs can activate a synced browser tab without a dependency cycle.
   switchSessionTabRef.current = switchSessionTab
 
-  // Why: just store the ref. Subscription is deferred to handleTerminalWebReady
-  // which fires after the WebView has loaded xterm.js and is ready to process
-  // init messages. This prevents the blank terminal race where init() was
-  // queued before the WebView loaded.
+  // Why: only store the ref; subscribe on web-ready to avoid the blank-terminal race (init queued before xterm.js loaded).
   const setTerminalWebViewRef = useCallback((handle: string, ref: TerminalWebViewHandle | null) => {
     terminalDiagnosticsRef.current.webViewRef(handle, ref != null)
     if (ref) {
@@ -3093,12 +2913,7 @@ export default function SessionScreen() {
         handle === activeHandleRef.current
       )
       if (wasAlreadyReady && initializedHandlesRef.current.has(handle)) {
-        // Why: the native WebView reloaded (Metro hot reload or Android
-        // process churn). The old xterm buffer is gone, so force a fresh
-        // scrollback snapshot. Only resubscribe if this is a reload — on
-        // first load the subscription is already running and pendingMessages
-        // will flush the queued init after this callback returns.
-        // (unsubscribeTerminal also clears layoutSeqRef for this handle.)
+        // Why: WebView reloaded (hot reload / Android churn); old xterm buffer is gone, so resubscribe for a fresh scrollback.
         unsubscribeTerminal(handle)
         initializedHandlesRef.current.delete(handle)
         if (handle === activeHandleRef.current) {
@@ -3106,17 +2921,8 @@ export default function SessionScreen() {
         }
         return
       }
-      // Why: on first web-ready, the initial subscribeToTerminal call from
-      // fetchTerminals may have been skipped (reason=no-ref, WebView wasn't
-      // mounted yet). Now that the WebView is ready, subscribe if this is the
-      // active terminal and no subscription is running. Await measure before
-      // subscribe so the very first subscribe carries the viewport — without
-      // this, subscribe(viewport=null) lands on the server first and the
-      // post-scrollback measure path's resubscribe sees alreadyMeasured=true
-      // (because measureViewportOnce won the race) and silently skips.
-      // Why: a just-created tab can briefly lose activeHandleRef to a lagging
-      // session-tab snapshot; honor the pending marker so its one web-ready
-      // subscribe still fires (see handleCreateTerminal).
+      // Why: first subscribe may skip (no WebView ref); await measure so it carries the viewport, else it races measureViewportOnce and skips.
+      // Why: a just-created tab can lose activeHandleRef to a lagging snapshot; honor the pending marker so its web-ready subscribe still fires.
       const isIntendedActive = () =>
         handle === activeHandleRef.current || handle === pendingActiveTerminalHandleRef.current
       if (isIntendedActive() && !terminalUnsubsRef.current.has(handle)) {
@@ -3165,9 +2971,7 @@ export default function SessionScreen() {
         terminal: activeHandle,
         text,
         enter: true,
-        // Why: presence-lock take-floor signal. Identifies this phone as
-        // the active mobile actor so the runtime can resolve multi-mobile
-        // contention (most-recent-actor's viewport wins).
+        // Why: presence-lock take-floor; marks this phone active so multi-mobile contention resolves to the last actor.
         ...(deviceTokenRef.current
           ? { client: { id: deviceTokenRef.current, type: 'mobile' as const } }
           : {})
@@ -3286,8 +3090,7 @@ export default function SessionScreen() {
 
   const openSessionTabActionSheetAfterKeyboardDismiss = useCallback(
     (tab: MobileSessionTab) => {
-      // Why: live input can have a queued refocus; action sheets should open after
-      // the terminal keyboard is gone, not race it under the drawer.
+      // Why: live input may queue a refocus; open the action sheet after the keyboard is gone, not racing it under the drawer.
       sessionTabActionSheetRequestSeqRef.current += 1
       const requestSeq = sessionTabActionSheetRequestSeqRef.current
       clearSessionTabActionSheetKeyboardListener()
@@ -3345,9 +3148,7 @@ export default function SessionScreen() {
     [focusLiveInput]
   )
 
-  // Tap on a file path in terminal output → resolve it on the host and open it
-  // as a file tab (mirrors desktop Cmd/Ctrl-click). Silent on a miss; the
-  // WebView only emits this when the tap landed on a detected path.
+  // Tap a terminal file path → resolve on host, open as file tab (mirrors desktop Cmd/Ctrl-click); silent on a miss.
   const handleFileTapActivationSeqRef = useRef(0)
   const handleFileTap = useCallback(
     (handle: string, pathText: string, line: number | null, column: number | null) => {
@@ -3387,9 +3188,7 @@ export default function SessionScreen() {
   )
 
   const handleOpenedFileDiffActivationSeqRef = useRef(0)
-  // Active tab captured at tap time (before the openDiff RPC). Capturing it when
-  // the diff finishes opening would misread a tab the user switched to mid-RPC
-  // as the tap-time tab, letting the retry steal focus back to the diff.
+  // Capture active tab at tap time; reading it after openDiff would misread a mid-RPC switch and let the retry steal focus.
   const fileOpenStartActiveTabIdRef = useRef<string | null>(null)
   const handleFileOpenStart = useCallback(() => {
     fileOpenStartActiveTabIdRef.current = activeSessionTabIdRef.current
@@ -3401,8 +3200,7 @@ export default function SessionScreen() {
 
       let activated = false
       const activateOpenedTab = async (): Promise<void> => {
-        // Route matching through the shared helper so the deterministic repro
-        // test exercises the same logic production runs.
+        // Route matching through the shared helper so the repro test exercises the same logic production runs.
         const settled = await activateOpenedSourceControlDiffTab<MobileSessionTab>({
           relativePath,
           activeTabIdAtTap,
@@ -3469,8 +3267,7 @@ export default function SessionScreen() {
         current.tokens + elapsedSeconds * TERMINAL_GESTURE_INPUT_REFILL_PER_SECOND
       )
 
-      // Why: tokens represent terminal control sequences, not WebView messages;
-      // one legitimate gesture message may batch up to 32 wheel/key reports.
+      // Why: tokens count terminal control sequences, not WebView messages; one gesture may batch up to 32 wheel/key reports.
       if (tokens < sequenceCount) {
         terminalGestureInputBucketsRef.current.set(handle, { tokens, lastRefillMs: now })
         return false
@@ -3556,12 +3353,7 @@ export default function SessionScreen() {
         if (!terminalGestureInputInFlightRef.current.has(handle)) {
           void flushTerminalGestureInput(handle)
         } else {
-          // Why: an RPC is in-flight and the new batch would overflow the
-          // pending-sequences cap. Appending preserves the already-queued
-          // bytes (which would otherwise be dropped) — the in-flight flush's
-          // finally block will pick up the merged queue. The cap is a soft
-          // guideline; brief overflow during in-flight is preferable to
-          // silently dropping user input.
+          // Why: cap is a soft guideline — append instead of dropping queued bytes; the in-flight flush picks up the merged queue.
           current.bytes += bytes
           current.sequenceCount += sequenceCount
           current.lastUpdatedMs = now
@@ -3597,8 +3389,7 @@ export default function SessionScreen() {
         return
       }
       const modes = ptyModesRef.current.get(handle)
-      // Why: WebView gesture bytes can become PTY input here, so mouse-aware
-      // reports stay behind validation and SSH-safe rate limiting.
+      // Why: WebView gesture bytes can become PTY input, so gate mouse reports behind validation and SSH-safe rate limiting.
       if (!modes?.altScreen && !isGestureMouseTrackingMode(modes?.mouseTrackingMode)) {
         return
       }
@@ -3641,18 +3432,10 @@ export default function SessionScreen() {
     }
   }
 
-  // Why: press-and-hold key repeat for keys flagged repeatable (arrows,
-  // backspace, forward-delete). Matches iOS keyboard cadence: instant first
-  // fire, then ~400ms before the second, then ~45ms between subsequent
-  // repeats. Non-repeatable keys (Tab, Esc, Ctrl-*) intentionally fire once
-  // because holding them is destructive or meaningless.
+  // Why: hold-to-repeat matches iOS cadence (400ms then 45ms); non-repeatable keys fire once (holding is destructive).
   const repeatTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const repeatIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
-  // Why: hold the latest handleAccessoryKey in a ref so the repeat interval
-  // always invokes the current callback. Otherwise a held key keeps firing
-  // through the callback captured when the interval started, which can route
-  // bytes to a stale terminal/RPC client after a tab switch or reconnect
-  // mid-hold.
+  // Why: ref keeps repeat firing the current callback; else a mid-hold tab switch/reconnect routes bytes to a stale terminal.
   const handleAccessoryKeyRef = useRef(handleAccessoryKey)
   handleAccessoryKeyRef.current = handleAccessoryKey
   const stopAccessoryRepeat = useCallback(() => {
@@ -3681,9 +3464,7 @@ export default function SessionScreen() {
       if (node !== null) {
         return
       }
-      // Why: terminal subscriptions and route-level timers must clear only on
-      // real route detach; client churn during mount can otherwise wipe xterm
-      // state mid-subscribe.
+      // Why: clear only on real route detach; client churn during mount would wipe xterm state mid-subscribe.
       toastSeqRef.current += 1
       clearTerminalCache()
       clearToastHideTimer()
@@ -3726,10 +3507,7 @@ export default function SessionScreen() {
       try {
         await Clipboard.setStringAsync(text)
         triggerSuccess()
-        // Why: Android 13+ shows its own system "Copied to clipboard" toast on
-        // every clipboard write, so our toast would be redundant; iOS shows
-        // nothing on copy (it only banners on paste), so the in-app toast is
-        // the only success signal there.
+        // Why: Android 13+ shows its own system copy toast; iOS shows none, so only iOS needs our in-app toast.
         if (Platform.OS === 'ios') {
           showToast('Copied')
         }
@@ -3970,10 +3748,7 @@ export default function SessionScreen() {
     setCreating(true)
     setCreateError('')
 
-    // Why: idempotency key so a transport-level retry (reconnect replay) of this
-    // create resolves to the same terminal instead of spawning a duplicate. Kept
-    // compact (no worktree id) to stay under the schema's length cap; the ref
-    // guard above blocks concurrent taps synchronously.
+    // Why: idempotency key so a transport retry (reconnect replay) resolves to the same terminal, not a duplicate; kept compact (no worktree id) for the schema length cap.
     const clientMutationId = `mobile-create:${Date.now().toString(36)}-${Math.random()
       .toString(36)
       .slice(2, 10)}`
@@ -3993,9 +3768,7 @@ export default function SessionScreen() {
       if (response.ok) {
         const result = (response as RpcSuccess).result as TerminalCreateResult
         const created = result.tab
-        // Why: unsubscribe the old active terminal so the server restores its
-        // desktop dims. Without this, the old terminal's mobile subscription
-        // stays alive and its restore timer is never set.
+        // Why: unsubscribe the old terminal so the server restores its desktop dims; otherwise its restore timer is never set.
         const prev = activeHandleRef.current
         if (prev) {
           unsubscribeTerminal(prev)
@@ -4013,10 +3786,7 @@ export default function SessionScreen() {
         if (typeof created.terminal === 'string') {
           const createdHandle = created.terminal
           defaultTerminalHandlesToLiveInput([createdHandle])
-          // Why: session-tab snapshots can lag the create RPC. Without the
-          // handle marker, applySessionTabs snaps activeHandleRef back to the
-          // previous terminal, and the new pane's web-ready subscribe (gated
-          // on the active handle) is skipped — blank tab until a manual switch.
+          // Why: snapshots lag the create RPC; without this marker applySessionTabs reverts the active handle, blanking the new pane.
           pendingActiveTerminalHandleRef.current = createdHandle
           activeHandleRef.current = createdHandle
           setActiveHandle(createdHandle)
@@ -4079,8 +3849,7 @@ export default function SessionScreen() {
             showToast(options.successToast)
           }
         } else {
-          // Why: a prior pending handle must not outlive a create that returned
-          // no terminal; web-ready subscribe gates on this ref as active.
+          // Why: a prior pending handle must not outlive a create that returned no terminal; web-ready subscribe gates on this ref.
           pendingActiveTerminalHandleRef.current = null
           activeHandleRef.current = null
           setActiveHandle(null)
@@ -4184,8 +3953,7 @@ export default function SessionScreen() {
     if (!client || creatingBrowser) {
       return false
     }
-    // Why: read via ref so a tap that fires before the capability probe resolves
-    // (or from a stale callback) still sees the live support value.
+    // Why: read via ref so a tap before the capability probe resolves (or a stale callback) still sees the live value.
     if (browserScreencastSupportedRef.current !== true) {
       showToast('Desktop update required for mobile browser streaming', 1600)
       return false
@@ -4214,9 +3982,7 @@ export default function SessionScreen() {
       if (!response.ok) {
         throw new Error((response as RpcFailure).error.message)
       }
-      // Focus the new browser tab once it syncs (fetchSessionTabs activates it
-      // via the normal path). Refresh a few times since the desktop registers
-      // the tab asynchronously.
+      // Focus the new browser tab once it syncs; refresh a few times since the desktop registers the tab asynchronously.
       const created = (response as RpcSuccess).result as { browserPageId?: string }
       if (created.browserPageId) {
         pendingBrowserFocusPageIdRef.current = created.browserPageId
@@ -4234,8 +4000,7 @@ export default function SessionScreen() {
       setCreatingBrowser(false)
     }
   }
-  // Keep the ref pointing at the latest handleCreateBrowser so a terminal URL
-  // tap (handleTerminalOpenUrl) always runs the current closure.
+  // Keep the ref at the latest handleCreateBrowser so a terminal URL tap always runs the current closure.
   handleCreateBrowserRef.current = handleCreateBrowser
 
   async function handleBrowserNavigationCommand(
@@ -4345,9 +4110,7 @@ export default function SessionScreen() {
           clearTerminalLiveInputDefault(terminalHandle)
         }
         setSessionTabs((prev) => prev.filter((candidate) => candidate.id !== tab.id))
-        // Why: tombstone the closed tab and rely on the subscription/poll
-        // snapshot (gated by snapshotVersion) instead of a blind 300ms refetch
-        // that re-applied whatever the host had — often the not-yet-closed list.
+        // Why: tombstone the closed tab and rely on the snapshot, not a blind refetch that often re-added the not-yet-closed tab.
         closedTabTombstonesRef.current.set(tab.id, Date.now() + 10_000)
         if (activeSessionTabId === tab.id) {
           activeSessionTabTypeRef.current = null
@@ -4389,8 +4152,7 @@ export default function SessionScreen() {
     if (pendingTerminalActivationAttemptRef.current === activationKey) {
       return
     }
-    // Why: a hydrated headless/server-owned tab can already be active but still
-    // pending; activation is the RPC that materializes or focuses its PTY handle.
+    // Why: a server-owned tab can be active but still pending; activation is the RPC that materializes its PTY handle.
     pendingTerminalActivationAttemptRef.current = activationKey
     void activateMobileSessionTab(client, {
       worktree: `id:${worktreeId}`,
@@ -4439,16 +4201,13 @@ export default function SessionScreen() {
     ) {
       return
     }
-    // Why: a sleeping/new workspace can hydrate with zero session tabs. Create
-    // the first terminal once on initial load instead of leaving mobile blank.
+    // Why: a sleeping/new workspace can hydrate with zero tabs; create the first terminal once so mobile isn't blank.
     initialEmptySessionAutoCreateRef.current = worktreeId
     setCreateError('')
     void handleCreateTerminal()
   }, [client, creating, creatingBrowser, creatingMarkdown, showEmptyState, worktreeId])
 
-  // Why: the reconnect loop slows to a 90s trickle at its give-up cap;
-  // surface tap-to-retry once the verdict escalates so recovery doesn't
-  // wait out the trickle timer (issue #5049).
+  // Why: reconnect trickles to 90s at its give-up cap; surface tap-to-retry so recovery needn't wait it out (issue #5049).
   const connectionVerdict = classifyConnection({
     state: connState,
     reconnectAttempts,
@@ -4469,9 +4228,7 @@ export default function SessionScreen() {
         ? `${verdictDisplayLabel(connectionVerdict)} — tap to retry`
         : MOBILE_SESSION_STATUS_LABELS[connState]
 
-  // Why: keep safe-area padding in layout at all times, then visually translate
-  // the controls over the terminal when the keyboard appears. iOS keyboard
-  // height includes the home-indicator inset; Android IME height does not.
+  // Why: iOS keyboard height includes the home-indicator inset; Android IME height does not.
   const keyboardLift =
     keyboardHeight > 0
       ? Platform.OS === 'ios'
@@ -4493,8 +4250,7 @@ export default function SessionScreen() {
     const cursorBottom = (metrics.cursorY + 1) * rowHeight
     const dockTop = terminalFrameHeightRef.current - keyboardLift
     const margin = rowHeight
-    // Why: only move the terminal when the active cursor would sit under the
-    // raised input dock. Short shell output near the top should stay put.
+    // Why: only move the terminal when the cursor would sit under the raised input dock; short top output stays put.
     return Math.min(keyboardLift, Math.max(0, cursorBottom + margin - dockTop))
   })()
   const toastAnimatedStyle = {
@@ -4592,8 +4348,7 @@ export default function SessionScreen() {
                 ]
               : []
 
-  // Routes a header panel-icon tap through the pure dock-vs-push decision (U1):
-  // measured dock-capable rows toggle/swap, constrained rows push full-screen.
+  // Panel-icon taps route through the dock-vs-push decision (U1): dock-capable rows dock, constrained rows push.
   const handleSessionContentRowLayout = useCallback((event: LayoutChangeEvent) => {
     const width = Math.round(event.nativeEvent.layout.width)
     setSessionContentRowWidth((prev) => (prev === width ? prev : width))
@@ -4612,8 +4367,7 @@ export default function SessionScreen() {
         hostId,
         worktreeId,
         name: worktreeName || '',
-        // SC + PR both land on the source-control hub; post-diff-open dismissal
-        // keys off origin: 'session' (U2). Files keeps its own route without origin.
+        // SC + PR both land on the source-control hub with origin:'session' for post-diff-open dismissal (U2); Files opts out.
         ...(action.panel === 'sourceControl' || action.panel === 'pr' ? { origin: 'session' } : {}),
         // The PR panel routes into the hub's Pull Request segment via descriptor params.
         ...descriptor.params
@@ -4695,10 +4449,7 @@ export default function SessionScreen() {
 
           {visibleTabs.length > 0 && (
             <View style={styles.tabBar}>
-              {/* Why: tab taps must register on the first press while the live
-                  keyboard is open instead of being eaten by keyboard dismissal
-                  (#5106); leaving a non-live tab still closes the keyboard
-                  because the live input unmounts. */}
+              {/* Why: tab taps must register on first press with the keyboard open instead of being eaten by dismissal (#5106). */}
               <ScrollView
                 ref={tabStripRef}
                 horizontal
@@ -4765,8 +4516,7 @@ export default function SessionScreen() {
                   </Pressable>
                 ))}
               </ScrollView>
-              {/* Why: pinned outside the scroll strip so the new-agent button
-                  stays reachable no matter how far the tabs scroll. */}
+              {/* Why: pinned outside the scroll strip so the new-agent button stays reachable however far the tabs scroll. */}
               <Pressable
                 style={({ pressed }) => [
                   styles.newTerminalButton,
@@ -4797,10 +4547,7 @@ export default function SessionScreen() {
           )}
         </SafeAreaView>
 
-        {/* Content-row host (KTD2): the header/tab chrome stays a full-width sibling
-            above; on wide the post-chrome content shares this row with the docked panel.
-            There is no single terminal node, so the entire conditional block is the
-            flex-1 left child. On narrow the dock never renders and layout is unchanged. */}
+        {/* Content-row host (KTD2): on wide, content shares this row with the docked panel as the flex-1 left child. */}
         <View style={styles.sessionContentRow} onLayout={handleSessionContentRowLayout}>
           <View style={styles.sessionContentMain}>
             {createWarning ? (
@@ -4898,8 +4645,7 @@ export default function SessionScreen() {
               </View>
             ) : activeBrowserTab ? (
               <View style={styles.browserFrame}>
-                {/* Why: the pane owns imperative frame refs; browser tabs should
-            never render a stale frame while the old stream effect cleans up. */}
+                {/* Why: pane owns imperative frame refs; don't render a stale frame while the old stream effect cleans up. */}
                 <MobileBrowserPane
                   key={activeBrowserTab.browserPageId ?? activeBrowserTab.id}
                   client={client}
@@ -4928,8 +4674,7 @@ export default function SessionScreen() {
                 style={styles.terminalFrame}
                 onLayout={(e) => {
                   terminalFrameHeightRef.current = e.nativeEvent.layout.height
-                  // Why: notify height imperatively so dock settling re-fits the
-                  // PTY without rerendering SessionScreen for layout callbacks.
+                  // Why: notify height imperatively so dock settling re-fits the PTY without rerendering SessionScreen.
                   const nextWidth = Math.round(e.nativeEvent.layout.width)
                   const nextHeight = Math.round(e.nativeEvent.layout.height)
                   setTerminalFrameWidth((prev) => (prev === nextWidth ? prev : nextWidth))
@@ -4945,8 +4690,7 @@ export default function SessionScreen() {
                     terminalTheme={terminal.terminalTheme}
                     textScale={terminalTextScale}
                     onTextScaleChange={(scale) => {
-                      // Why: pinch-to-zoom in the WebView reports a new preset; persist
-                      // it so the size sticks across panes and app launches.
+                      // Why: pinch-to-zoom reports a new preset; persist it so the size sticks across panes and launches.
                       setTerminalTextScale(scale)
                       void saveTerminalTextScale(scale)
                     }}
@@ -4985,9 +4729,7 @@ export default function SessionScreen() {
               </View>
             )}
 
-            {/* Why: translate instead of resizing so keyboard open/close does not
-            trigger a server-side PTY viewport change. The dock hides in native
-            chat because that view supplies its own composer. */}
+            {/* Why: translate instead of resize so keyboard toggles don't trigger a server-side PTY viewport change. */}
             {!activeMarkdownTab && !activeFileTab && !activeBrowserTab && !showNativeChat && (
               <View
                 style={[
@@ -4997,10 +4739,7 @@ export default function SessionScreen() {
               >
                 {/* Accessory keys */}
                 <View style={styles.accessoryBar}>
-                  {/* Why: a fixed, always-visible escape hatch from the open
-                  keyboard. Kept outside the horizontal ScrollView so it does
-                  not scroll away, and out of the terminal-byte shortcut path so
-                  it cannot be hidden by user shortcut customization (#5106). */}
+                  {/* Why: fixed keyboard escape hatch; outside ScrollView + shortcut path so it can't scroll away or be hidden (#5106). */}
                   {keyboardLift > 0 && (
                     <Pressable
                       style={({ pressed }) => [
@@ -5024,9 +4763,7 @@ export default function SessionScreen() {
                       </View>
                     </Pressable>
                   )}
-                  {/* Why: with default tap handling the first tap on any accessory
-                  key dismisses the open keyboard and is swallowed, so live
-                  input lost its keyboard on every Esc/Tab press (#5106). */}
+                  {/* Why: default tap handling makes the first accessory-key tap dismiss the keyboard and get swallowed (#5106). */}
                   <ScrollView
                     style={styles.accessoryScroll}
                     horizontal
@@ -5241,8 +4978,7 @@ export default function SessionScreen() {
                       autoCorrect={false}
                       spellCheck={false}
                       smartInsertDelete={false}
-                      // Why: iOS textContentType wins over autoComplete and can
-                      // narrow the keyboard surface; keep IME switching available.
+                      // Why: iOS textContentType overrides autoComplete and can narrow the keyboard; keep IME switching available.
                       autoComplete="off"
                       keyboardType={getTerminalLiveInputKeyboardType(Platform.OS)}
                       returnKeyType="default"
@@ -5255,8 +4991,7 @@ export default function SessionScreen() {
                   <View style={styles.inputBar}>
                     <TextInput
                       ref={commandInputRef}
-                      // Why: Android caches the IME inputType at mount, so toggling
-                      // autocomplete must remount there; iOS can update without a focus-costly remount.
+                      // Why: Android caches IME inputType at mount, so toggling autocomplete must remount there; iOS updates in place.
                       key={
                         Platform.OS === 'android'
                           ? autocompleteEnabled
@@ -5266,9 +5001,7 @@ export default function SessionScreen() {
                       }
                       style={styles.textInput}
                       value={input}
-                      // Why: iOS kills an active dictation/IME session when JS
-                      // writes a value that differs from the native field text;
-                      // store the raw field text and normalize at send time.
+                      // Why: iOS kills active dictation/IME if JS writes a value differing from native text; store raw, normalize at send.
                       onChangeText={setInput}
                       placeholder="Type a command…"
                       placeholderTextColor={colors.textMuted}
@@ -5276,8 +5009,7 @@ export default function SessionScreen() {
                       autoCorrect={autocompleteEnabled}
                       spellCheck={autocompleteEnabled}
                       smartInsertDelete={false}
-                      // Why: terminal commands are not autofill content, but the
-                      // keyboard must stay default so non-Latin IMEs remain selectable.
+                      // Why: not autofill content, but keyboard must stay default so non-Latin IMEs remain selectable.
                       autoComplete="off"
                       keyboardType={getTerminalCommandKeyboardType(
                         Platform.OS,
diff --git a/mobile/app/index.tsx b/mobile/app/index.tsx
index b33aac12610..265e3413c42 100644
--- a/mobile/app/index.tsx
+++ b/mobile/app/index.tsx
@@ -123,10 +123,7 @@ function formatDuration(ms: number): string {
   return `${totalMinutes}m`
 }
 
-// Why: derive a stable per-instance identity for RpcClient so the wireUp
-// effect's dep key changes when forceReconnect swaps the underlying client
-// for a host (without this, listeners stay attached to the closed client
-// and notifications/accounts subs never re-attach).
+// Why: stable per-instance RpcClient identity so wireUp's dep key changes when forceReconnect swaps the client, re-attaching listeners.
 const clientIdentities = new WeakMap<RpcClient, number>()
 let nextClientIdentity = 1
 function clientKey(client: RpcClient): number {
@@ -164,11 +161,7 @@ function fetchWorktreeInfo(
   ) => void,
   disposed: () => boolean
 ) {
-  // Why: only seed an empty zeroed entry when this host has no prior info
-  // at all (e.g., first ever load before any cache hydration). On a
-  // transient failure for a host that already has cached data, leave the
-  // cached entry alone so the Resume card and host-meta line don't
-  // momentarily flip to "0 worktrees" / disappear during reconnects.
+  // Why: only seed a zeroed entry when the host has no prior info; keep cached data on transient failure so counts don't flip to 0 during reconnects.
   const markLoadedIfMissing = () => {
     setInfo((prev) => {
       if (prev[hostId]) {
@@ -187,8 +180,7 @@ function fetchWorktreeInfo(
   }
 
   client
-    // Why: worktree.ps defaults to 200 and silently truncates; request the full
-    // set so the host worktree count and active count are accurate.
+    // Why: worktree.ps defaults to 200 and silently truncates; request all so counts are accurate.
     .sendRequest('worktree.ps', { limit: 10000 })
     .then((response) => {
       if (disposed()) {
@@ -286,8 +278,7 @@ function fetchTaskProviders(
     })
 }
 
-// Why: repo names get a stable color derived from hashing, matching the
-// host detail page's colored dots for visual consistency.
+// Why: hash repo name to a stable color, matching the host detail page's dots.
 const REPO_COLORS = ['#8b5cf6', '#3b82f6', '#22c55e', '#f59e0b', '#ef4444', '#ec4899', '#06b6d4']
 function repoColor(name: string): string {
   let hash = 0
@@ -300,8 +291,7 @@ function repoColor(name: string): string {
 export default function HomeScreen() {
   const router = useRouter()
   const insets = useSafeAreaInsets()
-  // Why: cap and center content on wide/tablet canvases so cards don't stretch
-  // edge-to-edge on iPad; on phones isWideLayout is false and layout is unchanged.
+  // Why: cap/center content on wide/tablet canvases so cards don't stretch edge-to-edge on iPad.
   const { isWideLayout, contentMaxWidth } = useResponsiveLayout()
   const [hosts, setHosts] = useState<HostProfile[]>([])
   const [actionTarget, setActionTarget] = useState<HostProfile | null>(null)
@@ -318,9 +308,7 @@ export default function HomeScreen() {
   )
   const notificationOptInCheckedRef = useRef(false)
 
-  // Why: read shared clients from the per-host store. Replaces the prior
-  // pattern of opening N independent WebSockets here. See
-  // docs/mobile-shared-client-per-host.md.
+  // Why: shared clients from the per-host store, not N independent WebSockets. See docs/mobile-shared-client-per-host.md.
   const hostIds = useMemo(() => hosts.map((h) => h.id), [hosts])
   const allClients = useAllHostClients(hostIds)
   const hostPaths = useMemo(
@@ -330,27 +318,20 @@ export default function HomeScreen() {
   const closeHostClient = useCloseHost()
   const forceReconnectHost = useForceReconnect()
   const primeHosts = usePrimeHosts()
-  // Why: feed the loaded HostProfiles into the provider's prime cache as
-  // soon as we have them. This avoids a second Keychain pass inside
-  // openEntry on cold start (which serialised behind the first one and
-  // showed up as multi-second connect latency).
+  // Why: prime the cache with loaded HostProfiles to avoid a second serialized Keychain pass (multi-second connect latency) on cold start.
   useEffect(() => {
     if (hosts.length > 0) {
       primeHosts(hosts)
     }
   }, [hosts, primeHosts])
   const allClientsRef = useRef<Array<{ hostId: string; client: RpcClient }>>([])
-  // Why: the focus callback stays stable to avoid refetching on every
-  // client-store render, but it still needs the latest host clients.
+  // Why: keep the focus callback stable (no refetch per render) while still exposing the latest host clients.
   allClientsRef.current = allClients.map((entry) => ({
     hostId: entry.hostId,
     client: entry.client
   }))
 
-  // Why: hydrate the home page from a persisted snapshot on cold-start so
-  // Resume + Account-usage cards paint immediately with last-known data
-  // instead of flashing empty for ~1s while the WebSocket reconnects.
-  // Stream/list responses overwrite this seed in place when they arrive.
+  // Why: hydrate from a persisted snapshot on cold-start so Resume + Account cards paint immediately instead of flashing empty.
   const hydratedRef = useRef(false)
   useEffect(() => {
     if (hydratedRef.current) {
@@ -367,8 +348,7 @@ export default function HomeScreen() {
       for (const [hostId, info] of Object.entries(snap.worktreeInfo)) {
         const wt = info.lastActiveWorktree
         if (wt) {
-          // Why: also seed the in-memory worktree cache so resumeWorktree's
-          // lastVisited fast-path can find the cached worktree object.
+          // Why: seed the in-memory cache so resumeWorktree's lastVisited fast-path finds the worktree object.
           setCachedWorktrees(hostId, [wt])
         }
       }
@@ -378,9 +358,7 @@ export default function HomeScreen() {
     }
   }, [])
 
-  // Why: persist the merged snapshot whenever either piece updates so the
-  // next cold-start has fresh seed data. The cache module debounces writes
-  // internally so a flurry of streamed updates doesn't hammer disk.
+  // Why: persist the merged snapshot on each update so the next cold-start has fresh seed data (cache debounces writes).
   useEffect(() => {
     if (Object.keys(worktreeInfo).length === 0 && Object.keys(accountsByHost).length === 0) {
       return
@@ -436,8 +414,7 @@ export default function HomeScreen() {
     [hosts]
   )
 
-  // Why: mirror per-host connection state into hostStates so existing
-  // render code (status dots, connecting indicators) keeps working.
+  // Why: mirror per-host connection state into hostStates so existing render code (status dots) keeps working.
   useEffect(() => {
     setHostAttempts((prev) => {
       const next: Record<string, number> = { ...prev }
@@ -473,11 +450,7 @@ export default function HomeScreen() {
           changed = true
         }
       }
-      // Why: when a paired host disappears from allClients (because the
-      // user tapped Disconnect, or the host record was invalid) the card
-      // must reflect that. We only force-update hosts whose state was
-      // already tracked — otherwise the initial-acquire frame (entry not
-      // yet materialised) would briefly flip every host to 'disconnected'.
+      // Why: reflect hosts that dropped from allClients, but only if already tracked — else the initial-acquire frame flips all to 'disconnected'.
       for (const host of hosts) {
         if (liveIds.has(host.id)) {
           continue
@@ -506,11 +479,7 @@ export default function HomeScreen() {
     })
   }, [allClients, hosts])
 
-  // Why: per-host streaming subscriptions (notifications + accounts) and
-  // one-shot stats fetches when each host transitions to 'connected'.
-  // Runs once per (hostId, client) pair and tears down when that pair
-  // changes. The provider keeps the underlying socket open across
-  // resubscription cycles so this is cheap.
+  // Per-host notif/accounts subs + one-shot stats on 'connected'; re-runs per (hostId, client) pair, socket stays open so it's cheap.
   useEffect(() => {
     const cleanups: Array<() => void> = []
     for (const entry of allClients) {
@@ -563,12 +532,7 @@ export default function HomeScreen() {
         c()
       }
     }
-    // Why: depend on the host-id set AND each entry's client identity, so
-    // resubscriptions don't fire on every render that produces a new
-    // array reference, but DO fire when forceReconnect swaps the
-    // underlying client for a host (otherwise wireUp would keep firing
-    // on a closed client and never re-attach to the fresh one, leaving
-    // notifications/accounts subs broken until the user navigates).
+    // Why: key on host-id set + each client's identity so resubs fire when forceReconnect swaps a host's client, not on every render.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     allClients
@@ -577,22 +541,10 @@ export default function HomeScreen() {
       .join(',')
   ])
 
-  // Why: prefer the worktree the user last opened on this device so the
-  // "Resume" card reflects their mobile session history, not just the
-  // desktop's most-recently-outputting worktree.
-  // Why: rendering used to be gated on hostStates === 'connected', which
-  // caused the Resume card to vanish for ~1s on every cold-start /
-  // resume-from-background while the WebSocket reconnected, even though we
-  // had perfectly good cached worktree data. Now the card stays visible as
-  // long as we have a cached lastActiveWorktree for any known host; the
-  // tap target is still the same and a fresher snapshot from the live RPC
-  // overwrites the card's contents in place when it lands.
+  // Why: prefer the worktree last opened on this device so Resume reflects mobile session history.
+  // Why: don't gate on 'connected' so the card doesn't flash empty for ~1s on cold-start; cached data holds until fresh RPC lands.
   const resumeWorktree = useMemo(() => {
-    // Why: only surface Resume for hosts that are currently connected.
-    // Showing a stale cached worktree for a disconnected host is
-    // misleading — the user would tap into a session route that can't
-    // load anything until the host reconnects. Once the host reconnects,
-    // the card reappears with fresh data.
+    // Why: only surface Resume for connected hosts; a stale worktree taps into a route that can't load.
     if (lastVisited && hostStates[lastVisited.hostId] === 'connected') {
       const cached = getCachedWorktrees(lastVisited.hostId) as WorktreeSummary[] | null
       const match = cached?.find((w) => w.worktreeId === lastVisited.worktreeId)
@@ -612,9 +564,7 @@ export default function HomeScreen() {
     return null
   }, [sortedHosts, hostStates, worktreeInfo, lastVisited])
 
-  // Why: only show the Account usage section for hosts that are currently
-  // connected. Showing stale cached usage for a disconnected host implies
-  // live data; better to hide until the host reconnects and we can refresh.
+  // Why: only show Account usage for connected hosts; stale cached usage would imply live data.
   const accountsHosts = useMemo(() => {
     const items: Array<{ host: HostProfile; snapshot: AccountsSnapshot }> = []
     for (const host of sortedHosts) {
@@ -625,9 +575,7 @@ export default function HomeScreen() {
       if (!snap) {
         continue
       }
-      // Why: also show hosts whose only usage is the system-default login
-      // (no Orca-managed accounts but live rate-limit data for the active
-      // target), otherwise system-default users see no usage section at all.
+      // Why: also show hosts whose only usage is the system-default login, else those users see no usage section.
       if (hasRenderableUsage(snap, 'claude') || hasRenderableUsage(snap, 'codex')) {
         items.push({ host, snapshot: snap })
       }
@@ -716,8 +664,7 @@ export default function HomeScreen() {
       setConfirmRemove(null)
       setHosts(await loadHosts())
     } catch {
-      // Why: ConfirmModal closes on confirm; re-open for retry and surface the
-      // failure instead of silently leaving the host listed.
+      // Why: ConfirmModal closes on confirm; re-open for retry so the failure isn't silent.
       setConfirmRemove(hostToRemove)
       Alert.alert('Could not remove host', 'Please try again.')
     }
@@ -782,9 +729,7 @@ export default function HomeScreen() {
         <FlatList
           data={sortedHosts}
           keyExtractor={(h) => h.id}
-          // Why: edge-to-edge — let the list scroll under the system nav bar
-          // but reserve insets.bottom so the last row stays reachable above
-          // the Samsung 3-button nav / iOS home indicator.
+          // Why: reserve insets.bottom so the last row stays reachable above the system nav bar / home indicator.
           contentContainerStyle={[
             styles.list,
             { paddingBottom: spacing.xl + insets.bottom },
@@ -961,10 +906,7 @@ export default function HomeScreen() {
                               ? snapshot.claude.accounts
                               : snapshot.codex.accounts
                           const limits = getActiveProviderRateLimits(snapshot, provider)
-                          // Why: with no managed accounts, still render a
-                          // "System default" row when the active target has
-                          // live usage data; the row label already falls back
-                          // to "System default" below.
+                          // Why: with no managed accounts, still render the row when the active target has live usage data.
                           if (accounts.length === 0 && !hasActiveProviderUsage(limits)) {
                             return null
                           }
@@ -1027,11 +969,7 @@ export default function HomeScreen() {
             state === 'connecting' ||
             state === 'handshaking' ||
             state === 'reconnecting'
-          // Why: "Reconnect" implies "you were connected, try again". If
-          // the client has never reached 'connected' this session (cold
-          // start, unreachable host, or after Disconnect) the action is
-          // functionally a fresh Connect — using the right verb makes
-          // the affordance match what tapping it actually does.
+          // Why: label "Connect" (not "Reconnect") when never connected this session, so the verb matches the action.
           const hasEverConnected = (hostLastConnected[host.id] ?? null) != null
           const items: ActionSheetAction[] = []
           items.push({
diff --git a/mobile/src/notifications/mobile-notifications.ts b/mobile/src/notifications/mobile-notifications.ts
index d3866393116..7e1444d9b0c 100644
--- a/mobile/src/notifications/mobile-notifications.ts
+++ b/mobile/src/notifications/mobile-notifications.ts
@@ -17,9 +17,7 @@ type NotificationEvent = {
   body: string
   worktreeId?: string
   notificationId?: string
-  // Mirrors the desktop-assigned MobileNotificationEvent.notificationSeq used
-  // for reconnect catch-up (#8129). Optional because older runtimes / non-
-  // replay events may omit it.
+  // Desktop-assigned seq for reconnect catch-up (#8129); optional since older runtimes may omit it.
   notificationSeq?: number
 }
 
@@ -42,12 +40,7 @@ type ScheduledNotificationState = {
 
 const scheduledNotificationsByHostAndNotificationId = new Map<string, ScheduledNotificationState>()
 
-// Why: notificationId embeds a per-completion timestamp (buildAgentNotificationId),
-// so every agent-task-complete inserts a new, never-reused key. Entries are only
-// removed when the desktop sends a matching dismiss — which a remote mobile user
-// (not at the desktop) frequently never gets — so the map grew for the app's whole
-// life. Bound it; a settled entry only retains a small identifier used for later
-// programmatic dismissal, unnecessary for long-past completions.
+// Why: keys never repeat and are only freed on desktop dismiss (which remote users often miss), so bound the map to stop unbounded growth.
 const MAX_SCHEDULED_NOTIFICATIONS = 256
 let maxScheduledNotifications = MAX_SCHEDULED_NOTIFICATIONS
 
@@ -55,8 +48,7 @@ function getStoredNotificationKey(hostId: string, notificationId: string): strin
   return `${encodeURIComponent(hostId)}:${encodeURIComponent(notificationId)}`
 }
 
-// Evict the oldest SETTLED entries (never one mid-schedule) until within the cap.
-// Map iteration is insertion order, so the first match is the oldest.
+// Evict oldest settled entries (never mid-schedule); Map iteration is insertion order so the first match is oldest.
 function boundScheduledNotifications(): void {
   while (scheduledNotificationsByHostAndNotificationId.size > maxScheduledNotifications) {
     let evicted = false
@@ -91,16 +83,13 @@ export async function getNotificationPermissionState(): Promise<NotificationPerm
     granted: status === 'granted',
     status,
     canAskAgain,
-    // Why: Android before API 33 has no runtime notification permission, so
-    // Expo's default "granted" state is capability evidence, not user consent.
+    // Why: Android <33 has no runtime notification permission, so "granted" is capability, not user consent.
     authorizationReflectsUserChoice:
       status === 'granted' && (Platform.OS !== 'android' || Number(Platform.Version) >= 33)
   }
 }
 
-// Why: permissions must be requested before scheduling any local notification.
-// Read the OS state every time because users can change it in Settings while
-// Orca remains alive in the background.
+// Why: re-read OS state every call — users can change it in Settings while Orca is backgrounded.
 export async function ensureNotificationPermissions(): Promise<boolean> {
   const existing = await getNotificationPermissionState()
   if (existing.granted) {
@@ -225,8 +214,7 @@ async function dismissLocalNotification(
     return
   }
   if (state.pending) {
-    // Why: desktop can send dismiss while iOS/Android is still scheduling the
-    // matching local notification. Remember it so no stale banner survives.
+    // Why: dismiss can arrive while the OS is still scheduling; defer it so no stale banner survives.
     state.dismissAfterSchedule = true
     return
   }
@@ -237,29 +225,15 @@ async function dismissLocalNotification(
   await Notifications.dismissNotificationAsync(state.identifier).catch(() => {})
 }
 
-// Why: each host connection gets its own notification subscription. When the
-// connection drops, the unsubscribe function cleans up the streaming RPC.
-// On reconnect the same subscribe stream is re-established by the RPC client;
-// we use its `ready` event to trigger catch-up (#8129): fetch notifications
-// dispatched while the socket was reaped, watermarked by the last seq we
-// already delivered so the desktop never re-sends an already-pushed one.
-// Returns an unsubscribe function.
+// Per-connection subscription; a reconnect `ready` triggers watermarked catch-up (#8129) so already-pushed events aren't re-sent.
 export function subscribeToDesktopNotifications(client: RpcClient, hostId: string): () => void {
   configureNotificationChannel()
 
   let subscriptionId: string | null = null
   let disposed = false
-  // Highest seq delivered on the live stream or replay for this connection.
-  // Persisted per-host so a cold app start still resumes from the right cut.
+  // Highest seq delivered (live or replay) this connection; persisted per-host so cold start resumes from the right cut.
   let lastDeliveredSeq = 0
-  // Why: per-connection dedup guard applied ONLY to the replay path
-  // (fetchMissed), never the live stream. The desktop already guarantees the
-  // replay cannot contain an event with seq <= lastDeliveredSeq (both live and
-  // replay advance the same watermark), so live + replay never overlap there.
-  // This set is defense-in-depth: if the desktop's bounded buffer evicted an
-  // old entry and a reconnect re-fetches across a boundary, an id delivered in
-  // the same connection isn't pushed twice. Bounded (RECENTLY_SEEN_CAP) so a
-  // long-lived session can't grow without limit.
+  // Why: defense-in-depth dedup for replayed events if the desktop's bounded buffer evicted across a reconnect boundary.
   const seenReplay = createSeenNotificationGuard()
 
   function deliverLive(
@@ -270,10 +244,7 @@ export function subscribeToDesktopNotifications(client: RpcClient, hostId: strin
       lastDeliveredSeq = event.notificationSeq
       void saveLastSeenSeq(hostId, lastDeliveredSeq)
     }
-    // Why (#8129 dedup): mark the event seen on EVERY delivery path (live AND
-    // replay) so a replay that re-includes an id already pushed live in this
-    // connection is dropped instead of double-pushed. fetchMissed also
-    // pre-checks seenReplay, but without this the live path never populated it.
+    // Why (#8129): mark seen on the live path too, so a later replay of an already-pushed id dedups instead of double-pushing.
     const key = seenKeyForEvent(event)
     if (key) {
       seenReplay.add(key)
@@ -284,12 +255,7 @@ export function subscribeToDesktopNotifications(client: RpcClient, hostId: strin
     return dismissLocalNotification(event as DismissNotificationEvent, hostId)
   }
 
-  // Why: on a reconnect `ready` the desktop has already dispatched whatever we
-  // missed; ask for it from our persisted watermark. Because the desktop cuts
-  // by seq > lastSeenSeq this is idempotent — we only ever get events we have
-  // not delivered before. The seenReplay guard is a second layer so a replay
-  // that somehow re-includes an id already delivered this connection is
-  // dropped instead of double-pushed.
+  // Why: desktop cuts by seq > lastSeenSeq, so re-fetching from the watermark is idempotent (seenReplay guards residual overlap).
   async function fetchMissed(): Promise<void> {
     if (disposed) {
       return
@@ -321,10 +287,7 @@ export function subscribeToDesktopNotifications(client: RpcClient, hostId: strin
     }
   }
 
-  // Why: lazily seed the watermark from durable storage on first use so we
-  // don't block subscribe() on an AsyncStorage read. The first `ready` (cold
-  // open) does NOT need catch-up — the live stream starts fresh; only
-  // subsequent reconnect `ready` events fetch missed notifications.
+  // Why: seed the watermark lazily so subscribe() doesn't block on an AsyncStorage read.
   let watermarkLoaded = false
   void loadLastSeenSeq(hostId).then((seq) => {
     lastDeliveredSeq = Math.max(lastDeliveredSeq, seq)
@@ -352,10 +315,7 @@ export function subscribeToDesktopNotifications(client: RpcClient, hostId: strin
         unsubscribeStream()
         return
       }
-      // Why: first ready is the cold-open live stream — no catch-up needed.
-      // Every later ready is a reconnect; fetch what we missed from the
-      // watermark. Guard on watermarkLoaded so a fast reconnect doesn't
-      // fetch from a stale 0 watermark (which would re-push everything).
+      // Why: only reconnects fetch missed; watermarkLoaded guards against fetching from a stale 0 (which re-pushes everything).
       if (reconnectReadyCount > 1 && watermarkLoaded) {
         void fetchMissed()
       }
@@ -379,12 +339,7 @@ export function subscribeToDesktopNotifications(client: RpcClient, hostId: strin
 
   return () => {
     disposed = true
-    // Why: the client may already be closed when this cleanup runs (component
-    // unmount races with disconnect). sendRequest rejects immediately on a
-    // closed client — swallow it since server-side cleanup happens via
-    // connection-close anyway.
-    // Always drop the local stream first; readiness can race unmount and we
-    // must not retain the callback while waiting for a subscription id.
+    // Why: drop the local stream first — readiness can race unmount; don't hold the callback while a subscription id is pending.
     unsubscribeStream()
     if (subscriptionId) {
       unsubscribeServer(subscriptionId)
diff --git a/mobile/src/session/use-mobile-pr-sidebar-controller.ts b/mobile/src/session/use-mobile-pr-sidebar-controller.ts
index 752b2ecb3b8..6c97b9e0b04 100644
--- a/mobile/src/session/use-mobile-pr-sidebar-controller.ts
+++ b/mobile/src/session/use-mobile-pr-sidebar-controller.ts
@@ -24,21 +24,17 @@ type PrSidebarControllerInput = {
   client: RpcClient | null
   connState: ConnectionState
   worktreeId: string
-  // Head branch + SHA come from git.status (`branch`/`head`) via the review screen,
-  // not the branchCompare base ref nor worktree metadata (which carries no branch).
+  // branch/headSha come from git.status (not the branchCompare base ref nor worktree metadata, which carries no branch).
   branch: string | null
   headSha: string | null
 }
 
-// Load options for the shared PR controller. The Source Control hub chip only needs
-// phase 1 (PR + checks); phase 2 (comments/body) is heavy and should wait until the
-// Pull Request segment is actually open.
+// Load options: the hub chip needs only phase 1 (PR + checks); phase 2 (comments/body) is heavy and waits until the PR segment opens.
 export type PrSidebarLoadOptions = {
   includeDetails?: boolean
 }
 
-// Identity is worktree + branch only. Head SHA advances on every commit and must not
-// wipe a ready chip/sidebar to "loading" — soft-refresh uses the new head instead.
+// Identity is worktree + branch only: headSha advances every commit and must not wipe a ready chip to "loading" (soft-refresh handles it).
 export function buildMobilePrSidebarIdentity(args: {
   worktreeId: string
   branch: string | null
@@ -48,33 +44,23 @@ export function buildMobilePrSidebarIdentity(args: {
 
 export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
   const { client, connState, worktreeId, branch, headSha } = input
-  // The dedicated PR icon is available whenever the repo has a GitHub remote —
-  // independent of whether the branch has an open PR (a no-PR branch shows an
-  // empty state rather than hiding the icon).
+  // PR icon shows for any GitHub remote, regardless of an open PR — a no-PR branch shows an empty state rather than hiding the icon.
   const [isGithubRepo, setIsGithubRepo] = useState(false)
-  // False until the probe resolves for this worktree. Consumers gate "unavailable
-  // for this provider" copy on it — isGithubRepo=false is meaningless mid-probe.
+  // False until the probe resolves — isGithubRepo=false is meaningless mid-probe, so consumers gate "unavailable" copy on this.
   const [repoProbeLoaded, setRepoProbeLoaded] = useState(false)
   const [state, setState] = useState<PrSidebarState>({ kind: 'hidden' })
   const [showPRSidebar, setShowPRSidebar] = useState(false)
   const loadSeqRef = useRef(0)
-  // Phase-2-only fetches use a separate sequence so they cannot cancel a concurrent
-  // phase-1 soft refresh (and vice versa) when chip bootstrap left details null.
+  // Separate seq for phase-2 fetches so they can't cancel a concurrent phase-1 soft refresh (and vice versa).
   const detailsSeqRef = useRef(0)
-  // The (seq, prNumber) of the phase-2 fetch currently in flight. The hub's
-  // fill-in effect fires as soon as phase 1 renders ready with null details —
-  // exactly when load()'s own phase 2 just started. Without this claim, every
-  // cold PR-segment open fetched the heavy details payload twice.
+  // (seq, prNumber) of the in-flight phase-2 fetch; without this claim every cold PR-segment open fetched the heavy details twice.
   const detailsInFlightRef = useRef<{ seq: number; prNumber: number } | null>(null)
   const stateIdentityRef = useRef<string | null>(null)
   const stateRef = useRef(state)
   stateRef.current = state
   const headShaRef = useRef(headSha)
 
-  // Repo eligibility (a GitHub remote) is independent of the branch, so the probe
-  // must not require one: a detached HEAD / mid-rebase worktree (branch === null)
-  // would otherwise never set repoProbeLoaded, stranding the PR segment on a
-  // forever spinner instead of the "Current branch unavailable" state.
+  // Probe is branch-independent (repo eligibility is): requiring a branch would strand a detached-HEAD worktree on a forever spinner.
   const probeReady = client !== null && connState === 'connected'
   const identity = buildMobilePrSidebarIdentity({ worktreeId, branch })
 
@@ -91,9 +77,7 @@ export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
     }
   }, [client])
 
-  // Probe whether this is a GitHub repo to decide icon availability (GitHub-only).
-  // Worktree change must reset eligibility; a brief disconnect must not — otherwise
-  // the hub shows "unavailable for this provider" and hides the chip mid-session.
+  // Probe GitHub-repo eligibility for the icon; a worktree change resets it, a brief disconnect must not (else the chip hides mid-session).
   useEffect(() => {
     setIsGithubRepo(false)
     setRepoProbeLoaded(false)
@@ -112,8 +96,7 @@ export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
         }
       })
       .catch(() => {
-        // Why: sendGithubPrRead already normalizes throws, but a cancelled
-        // unmount + any unexpected rejection must not surface as LogBox.
+        // Why: sendGithubPrRead normalizes throws, but a stray rejection on unmount must not surface as LogBox.
         if (!cancelled) {
           setIsGithubRepo(false)
           setRepoProbeLoaded(true)
@@ -133,8 +116,7 @@ export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
       return
     }
     if (stateIdentityRef.current !== null && stateIdentityRef.current !== identity) {
-      // Why: ready/loading data is scoped to branch. A branch switch must not let
-      // the open panel keep rendering the previous PR as "fresh."
+      // Why: data is scoped to branch; a branch switch must not keep rendering the previous PR as "fresh."
       loadSeqRef.current += 1
       detailsSeqRef.current += 1
       stateIdentityRef.current = null
@@ -152,16 +134,10 @@ export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
       }
       const seq = loadSeqRef.current + 1
       loadSeqRef.current = seq
-      // In-flight phase-2 work is NOT invalidated here: this load only takes phase-2
-      // ownership when its own phase 2 actually starts (the bump below), so a load
-      // superseded at the phase-1 guard can never orphan a detailsSeq and silently
-      // discard the only details fetch. A stale ensure applying mid-phase-1 is safe —
-      // its identity/number/kind guards only let matching details through.
+      // Don't invalidate in-flight phase 2 here: it's only claimed when this load's own phase 2 starts, so a superseded phase-1 load can't orphan the details fetch.
       const previousIdentity = stateIdentityRef.current
       stateIdentityRef.current = loadIdentity
-      // Soft refresh: same branch already showing ready/none stays visible while
-      // checks re-fetch (head advanced after commit). Hard loading only on first load
-      // or after a real identity wipe.
+      // Soft refresh: same-branch ready/none stays visible while checks re-fetch; hard "loading" only on first load or identity wipe.
       const keepVisible =
         previousIdentity === loadIdentity &&
         (stateRef.current.kind === 'ready' ||
@@ -170,8 +146,7 @@ export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
       if (!keepVisible) {
         setState({ kind: 'loading' })
       }
-      // Phase 1: PR + checks (fast) — the worktree linkedPR read is parallelized with
-      // forBranch inside loadPrSidebarData so a closed/merged linked PR still resolves.
+      // Phase 1: PR + checks (fast); linkedPR read runs in parallel with forBranch so a closed/merged linked PR still resolves.
       const next = await loadPrSidebarData(deps, { worktreeId, branch, headSha })
       if (
         !shouldApplyResult(seq, loadSeqRef.current) ||
@@ -181,9 +156,7 @@ export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
       }
       stateIdentityRef.current = loadIdentity
 
-      // Keep prior comments/body visible across phase 1 when the same PR is still open.
-      // loadPrSidebarData always returns details:null; without this, soft refresh and
-      // PR-tab refresh blank the comment tree until phase 2 finishes.
+      // Preserve prior details across phase 1 (loadPrSidebarData returns details:null) so soft/PR-tab refresh doesn't blank the comment tree.
       const priorDetails =
         next.kind === 'ready' &&
         stateRef.current.kind === 'ready' &&
@@ -213,10 +186,7 @@ export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
       if (detailsInFlightRef.current?.seq === detailsSeq) {
         detailsInFlightRef.current = null
       }
-      // Phase-2 ownership is encoded by detailsSeq + identity + PR number alone —
-      // deliberately NOT by loadSeq: a chip-only soft refresh bumps loadSeq without
-      // bumping detailsSeq, and must not discard the in-flight details it preserved
-      // (ensure dedupes against this claim, so nothing would re-fetch them).
+      // Ownership keyed on detailsSeq (not loadSeq): a chip-only soft refresh bumps loadSeq without detailsSeq and must not discard these details.
       if (
         detailsSeq !== detailsSeqRef.current ||
         stateIdentityRef.current !== loadIdentity ||
@@ -236,11 +206,7 @@ export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
     [buildDeps, branch, headSha, identity, worktreeId]
   )
 
-  // Phase-2 only — used when the hub opens the PR segment after a chip-only load.
-  // Uses detailsSeqRef (not loadSeqRef) so it cannot cancel a concurrent soft phase-1.
-  // Retries synthetic placeholders too: a failed phase-2 installs non-null empty
-  // details so Description/Comments leave the spinner, and without this ensure
-  // would never re-fetch on tab re-open.
+  // Phase-2-only fill-in; uses detailsSeqRef so it can't cancel a concurrent phase-1, and re-fetches non-null placeholders too.
   const ensurePrSidebarDetails = useCallback(async () => {
     const current = stateRef.current
     if (current.kind !== 'ready' || !prSidebarDetailsNeedFetch(current.data.details)) {
@@ -252,8 +218,7 @@ export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
       return
     }
     const prNumber = current.data.pr.number
-    // A live phase-2 fetch for this PR is already in flight (its claim still owns
-    // the latest details seq) — do not start a duplicate.
+    // Skip if a live phase-2 fetch for this PR already owns the latest details seq (dedupe).
     const inFlight = detailsInFlightRef.current
     if (inFlight && inFlight.prNumber === prNumber && inFlight.seq === detailsSeqRef.current) {
       return
@@ -284,18 +249,13 @@ export function useMobilePrSidebarController(input: PrSidebarControllerInput) {
     })
   }, [buildDeps, identity, worktreeId])
 
-  // Soft-refresh checks when HEAD advances on the same branch (post-commit).
-  // Also restarts an in-flight phase-1 load so a mid-flight head advance is not
-  // applied with a stale SHA (headShaRef would otherwise advance with no reload).
+  // Soft-refresh on same-branch HEAD advance; restart in-flight load so the advance isn't applied with a stale SHA.
   useEffect(() => {
     if (headShaRef.current === headSha) {
       return
     }
     headShaRef.current = headSha
-    // Identity was just wiped (branch/worktree switch): stateRef still holds the
-    // pre-wipe state in this effect flush, which would start a load flavored for
-    // the OLD surface (e.g. heavy details on the Changes tab). Let the owning
-    // surface's hidden-state effects drive the first load for the new identity.
+    // Identity just wiped: stateRef still holds stale pre-wipe state, so let the surface's hidden-state effects drive the new load.
     if (stateIdentityRef.current === null) {
       return
     }
diff --git a/mobile/src/source-control/MobileSourceControlPanel.tsx b/mobile/src/source-control/MobileSourceControlPanel.tsx
index 25656aae2bd..9c3ebb27062 100644
--- a/mobile/src/source-control/MobileSourceControlPanel.tsx
+++ b/mobile/src/source-control/MobileSourceControlPanel.tsx
@@ -46,16 +46,13 @@ export function MobileSourceControlPanel({
   onOpenedFileDiff
 }: MobileSourceControlPanelProps) {
   const [activeTab, setActiveTab] = useState<SourceControlHubTab>(initialTab)
-  // Track first visit so Changes/History keep scroll state across segment switches
-  // without paying the mount cost until the user actually opens them. PR unmounts
-  // when inactive (WebViews / comment tree) but its controller state stays for the chip.
+  // Track first visit so Changes/History stay mounted (keep scroll) after first open; PR still unmounts when inactive.
   const [visitedTabs, setVisitedTabs] = useState<ReadonlySet<SourceControlHubTab>>(
     () => new Set<SourceControlHubTab>([initialTab])
   )
   const [historyRefreshNonce, setHistoryRefreshNonce] = useState(0)
 
-  // Deep-link / push with a different `tab` param should adopt the new segment
-  // (expo-router can reuse the screen instance when only query params change).
+  // expo-router reuses the screen instance when only query params change, so adopt the new tab.
   useEffect(() => {
     setActiveTab(initialTab)
     setVisitedTabs((prev) => {
@@ -119,13 +116,7 @@ export function MobileSourceControlPanel({
   const ioBusy = busyAction !== null || openingPath !== null || openingBranchPath !== null
   const ready = screenState.kind === 'ready'
 
-  // One PR controller feeds both the branch-card chip and the Pull Request
-  // segment, so the chip's rollup can never disagree with the checks list it
-  // links to. Branch + head come from the already-loaded git.status — no second
-  // status read. The chip loads independently, so it never blocks the file list.
-  // Keep last-known identity across a transient status unload (disconnect /
-  // failed refresh) so the controller does not wipe ready → hidden → cold start.
-  // Head SHA matches the review path: status.head ?? branchCompare headOid.
+  // Keep last-known branch/head across a transient status unload so the PR controller isn't wiped ready → hidden → cold start.
   const lastPrBranchRef = useRef<string | null>(null)
   const lastPrHeadRef = useRef<string | null>(null)
   useEffect(() => {
@@ -134,8 +125,7 @@ export function MobileSourceControlPanel({
   }, [worktreeId])
   const statusBranch = status?.branch ?? null
   const statusHead = status?.head ?? branchCompareResult?.summary.headOid ?? null
-  // Write last-known identity in an effect, not the render body: a discarded
-  // concurrent render must not leave the fallback holding a never-committed value.
+  // Write last-known identity in an effect, not render: a discarded concurrent render must not leave the fallback stale.
   useEffect(() => {
     if (statusBranch) {
       lastPrBranchRef.current = statusBranch
@@ -163,8 +153,7 @@ export function MobileSourceControlPanel({
   const ensurePrDetailsRef = useRef(ensurePrDetails)
   ensurePrDetailsRef.current = ensurePrDetails
 
-  // Chip bootstrap: phase-1 only (PR + checks). Full comment payload waits until
-  // the Pull Request segment is open — opening SC to stage must not pull details.
+  // Chip bootstrap: phase-1 only (PR + checks); full payload waits for the PR segment so opening SC to stage doesn't pull details.
   useEffect(() => {
     if (activeTab === 'pr') {
       return
@@ -174,22 +163,14 @@ export function MobileSourceControlPanel({
     }
   }, [activeTab, prBranch, isHostedRepo, prSidebarKind])
 
-  // Number of the ready PR whose phase-2 details are still missing (null when
-  // none). Keyed by PR number — not a boolean — so a same-branch PR swap during a
-  // chip-only soft refresh re-arms phase 2 for the new PR instead of leaving its
-  // comments on a forever-spinner (a stale ensure bails on the number mismatch).
-  // Placeholder details (failed phase 2) also count as missing so reopening the
-  // PR tab retries instead of leaving empty Description/Comments forever.
+  // Keyed by PR number, not a boolean, so a same-branch PR swap re-arms phase 2 for the new PR.
   const prDetailsMissingFor =
     prController.prSidebarState.kind === 'ready' &&
     prSidebarDetailsNeedFetch(prController.prSidebarState.data.details)
       ? prController.prSidebarState.data.pr.number
       : null
 
-  // PR segment: full load or phase-2 fill-in. Body only mounts while active.
-  // Guarded (and keyed) on prBranch so a branch that arrives while the segment is
-  // already open — e.g. mounted on a detached HEAD, then checkout — still loads;
-  // kind stays 'hidden' through that transition, so kind alone can't re-fire this.
+  // PR segment full load / phase-2 fill-in; key on prBranch so a branch arriving while open still loads (kind stays 'hidden').
   useEffect(() => {
     if (activeTab !== 'pr' || !isHostedRepo || !prBranch) {
       return
@@ -204,9 +185,7 @@ export function MobileSourceControlPanel({
   }, [activeTab, isHostedRepo, prBranch, prSidebarKind, prDetailsMissingFor])
 
   const prChip = useMemo(() => {
-    // No branch (detached HEAD / mid-rebase) never runs a PR load, so the shared
-    // state stays 'hidden' — which the chip would render as a forever spinner.
-    // Hide the chip instead; the Pull Request segment shows "branch unavailable".
+    // No branch (detached HEAD / mid-rebase) never loads a PR, so state stays 'hidden'; hide the chip or it spins forever.
     if (!isHostedRepo || !prBranch) {
       return null
     }
@@ -217,9 +196,7 @@ export function MobileSourceControlPanel({
     return buildMobilePrChipSummary(prController.prSidebarState, commentCount)
   }, [isHostedRepo, prBranch, prController.prSidebarState])
 
-  // Design: refresh the active segment's body work, plus git.status for the shared
-  // branch card (counts/sync stay honest even while on History). Preserve ready
-  // status on a failed refresh so PR chip identity is not wiped to hidden.
+  // Refresh the active segment plus git.status (branch card stays honest on History); preserve ready on failure so the PR chip isn't wiped.
   const onRefresh = useCallback(() => {
     void loadStatus({ preserveReadyOnFailure: true })
     if (activeTab === 'history') {
@@ -237,11 +214,9 @@ export function MobileSourceControlPanel({
     void refetchPr({ includeDetails: false })
   }, [activeTab, isHostedRepo, loadStatus, refetchPr])
 
-  // Embedded mode docks beside the terminal: close the dock instead of popping
-  // a route, and skip the full-screen safe-area chrome (the dock column owns it).
+  // Embedded mode docks beside the terminal: close the dock instead of popping a route; skip safe-area chrome (the dock column owns it).
   const onBack = embedded ? (onRequestClose ?? (() => router.back())) : () => router.back()
-  // Chromeless PR body has no panel header — surface open-on-web on the hub chrome
-  // while the Pull Request segment is active (same affordance as the old /pr route).
+  // Chromeless PR body has no header, so surface open-on-web on the hub chrome while the PR segment is active.
   const prWebUrl =
     activeTab === 'pr' &&
     prController.prSidebarState.kind === 'ready' &&
@@ -277,10 +252,7 @@ export function MobileSourceControlPanel({
           <Pressable
             style={styles.retryButton}
             onPress={() => {
-              // Why: retrying the request is useless while the transport's
-              // reconnect loop is parked at its give-up cap — revive the
-              // connection instead (issue #5049). loadStatus re-runs via
-              // its connState effect once the new client connects.
+              // Why: a parked reconnect loop makes retry useless — revive the connection instead (issue #5049); loadStatus re-runs on reconnect.
               if (connState !== 'connected' && hostId) {
                 void forceReconnect(hostId)
                 return
@@ -294,13 +266,10 @@ export function MobileSourceControlPanel({
       </View>
     ) : null
 
-  // History only needs the RPC client — do not block it behind git.status.
-  // Changes/PR need status (branch, file list, head SHA), so they stay gated.
+  // History only needs the RPC client, so it isn't gated on git.status; Changes/PR need status (branch, files, head).
   const showChanges = ready && (activeTab === 'changes' || visitedTabs.has('changes'))
   const showHistory = activeTab === 'history' || visitedTabs.has('history')
-  // Why: only mount the PR body while its segment is active. Keep-mounting retained
-  // Mermaid WebViews and re-rendered the comment tree on every commit keystroke.
-  // Controller + chip state still live for instant re-open without a full cold start.
+  // Only mount PR body while active: keep-mounting retained Mermaid WebViews and re-rendered the comment tree per keystroke.
   const showPrBody = ready && activeTab === 'pr'
   const conflictOperation = status?.conflictOperation ?? null
   // Git status always reports a conflictOperation enum; 'unknown' means none.
@@ -319,10 +288,7 @@ export function MobileSourceControlPanel({
 
       <MobileSourceControlSegments active={activeTab} onSelect={selectTab} />
 
-      {/* Branch card + PR chip are the Changes/Commits glance layer. On the PR
-          tab they duplicate the ready PR body (#, state, checks rollup, branch
-          trajectory), so hide the whole card there and let the PR panel own it —
-          unless a merge/rebase conflict is active, which only this card can abort. */}
+      {/* On the PR tab the branch card duplicates the ready PR body, so hide it there — unless a conflict is active, which only this card can abort. */}
       {ready && (activeTab !== 'pr' || hasActiveConflict) ? (
         <MobileSourceControlBranchCard
           branchLabel={branchLabel}
@@ -357,8 +323,7 @@ export function MobileSourceControlPanel({
             headSha={prHeadSha}
             gitStatus={status}
             isGithubRepo={isHostedRepo}
-            // Gate on the probe too: isGithubRepo=false mid-probe must render as
-            // loading, not flash "unavailable for this provider" (old /pr parity).
+            // Gate on the probe too: isGithubRepo=false mid-probe must render loading, not flash "unavailable".
             branchContextLoaded={ready && prController.prSidebarRepoProbeLoaded}
             controller={prController}
           />
diff --git a/mobile/src/terminal/terminal-viewport-refit.ts b/mobile/src/terminal/terminal-viewport-refit.ts
index e54c7c47737..6194fabc675 100644
--- a/mobile/src/terminal/terminal-viewport-refit.ts
+++ b/mobile/src/terminal/terminal-viewport-refit.ts
@@ -28,14 +28,9 @@ type TerminalViewportRefitOptions = {
   initializedHandlesRef: RefObject<Set<string>>
   connState: ConnectionState
   tabStripVisible: boolean
-  // Why: terminal text size (font scale) — changing it changes the cell size, so
-  // the PTY must be re-fitted to a new column count and reflowed.
+  // Why: text size (font scale); changing it changes cell size, so the PTY must be re-fitted to a new column count.
   textScale: number
-  // Why: the terminal's measured frame width changes when a side panel docks/undocks
-  // or EITHER sidebar is drag-resized (the left worktree sidebar shrinks the detail
-  // pane; the right dock takes a slice of the row) — all without any window-dim or
-  // tab-strip change. Carries that measured width so those resizes re-fit the PTY;
-  // the 150ms debounce coalesces the stream of drag widths into one settle-time refit.
+  // Why: measured frame width; panel dock/undock or sidebar resize changes it with no window/tab change, so it re-fits the PTY.
   terminalFrameWidth: number
   unsubscribeTerminal: (handle: string) => void
   subscribeToTerminal: (handle: string) => void
@@ -46,12 +41,7 @@ type TerminalViewportRefitNotifications = {
   notifyKeyboardVisibility: (visible: boolean) => void
 }
 
-// Why: re-measure the phone viewport when layout-affecting state changes
-// outside the subscribe path — the tab strip toggling visibility, and the
-// window itself resizing (fold/unfold on foldables, orientation rotation,
-// split-screen). Without the resize trigger, a PTY fitted on the folded
-// cover screen stays at cover-screen cols after unfolding and the terminal
-// renders in only part of the display (#4579's "cut in half" symptom).
+// Why: re-measure on layout changes outside the subscribe path (tab strip, fold/rotate/resize), or a PTY renders "cut in half" (#4579).
 export function useTerminalViewportRefit(
   options: TerminalViewportRefitOptions
 ): TerminalViewportRefitNotifications {
@@ -82,9 +72,7 @@ export function useTerminalViewportRefit(
     keyboardVisible: false,
     pending: false
   })
-  // Why: marks the currently-armed timer as a height refit so its callback can
-  // re-check the keyboard at fire time. Non-height refits (width/rotation and
-  // the forced reconnect/foreground re-asserts) stay unguarded so they always run.
+  // Why: marks the armed timer as a height refit so its callback re-checks the keyboard; other refits always run unguarded.
   const heightOriginatedRefitRef = useRef(false)
   const scheduleViewportRefit = useCallback(
     (options?: { heightOriginated?: boolean }) => {
@@ -94,9 +82,7 @@ export function useTerminalViewportRefit(
       heightOriginatedRefitRef.current = options?.heightOriginated ?? false
       refitTimerRef.current = setTimeout(() => {
         refitTimerRef.current = null
-        // Why: a height refit deferred at keyboard-close can fire after the keyboard
-        // reopened within the 150ms debounce; re-check and re-defer so we never
-        // reflow the PTY mid-keystroke. Scoped via the height-originated flag.
+        // Why: a height refit can fire after the keyboard reopened within the debounce; re-check so we never reflow the PTY mid-keystroke.
         if (heightOriginatedRefitRef.current) {
           heightOriginatedRefitRef.current = false
           const decision = reduceTerminalFrameHeightRefit(frameHeightRefitStateRef.current, {
@@ -143,11 +129,7 @@ export function useTerminalViewportRefit(
           }
           viewportRef.current = dims
           viewportMeasuredRef.current = true
-          // Why: prefer the in-place viewport update RPC over the legacy
-          // unsubscribe → subscribe cycle. This keeps the server-side
-          // mobile subscriber record alive (no driver=idle blip on the
-          // desktop banner; no false phone-fit baseline capture on the
-          // re-subscribe). See docs/mobile-presence-lock.md.
+          // Why: prefer in-place updateViewport over resubscribe to keep the mobile subscriber record alive. See docs/mobile-presence-lock.md.
           const rpc = clientRef.current
           const deviceToken = deviceTokenRef.current
           if (rpc && deviceToken && updateViewportCapabilityRef.current !== 'unsupported') {
@@ -165,11 +147,7 @@ export function useTerminalViewportRefit(
               if (isTerminalUpdateViewportUpdated(response)) {
                 rpc.updateTerminalSubscriptionViewport(handle, dims)
                 if (isTerminalUpdateViewportApplied(response)) {
-                  // Why: updateViewport reflows the server PTY and re-streams only
-                  // the visible screen, so the WebView's local xterm scrollback
-                  // stays wrapped at the old width. Reflow it locally only when
-                  // the server actually applied phone-fit; desktop mode records
-                  // the viewport but leaves the PTY at desktop dims.
+                  // Why: updateViewport re-streams only the visible screen, so local scrollback stays wrapped at the old width — reflow it locally.
                   ref.reflow(dims.cols, dims.rows)
                 }
                 return
@@ -205,14 +183,7 @@ export function useTerminalViewportRefit(
     scheduleViewportRefit()
   }, [scheduleViewportRefit])
 
-  // Why: the tab strip is hidden when only one terminal exists and shown
-  // once a second is created. Crossing the 1↔2 boundary changes the
-  // visible terminal area by ~40px, so the cached viewport dims in
-  // viewportRef become stale. Mark the viewport as un-measured so the
-  // next subscribe path's self-correcting loop (init → measure →
-  // resubscribe-with-fresh-viewport) re-runs against the new layout.
-  // Also schedule an explicit refit to cover the case where no new
-  // subscribe is happening.
+  // Why: the tab strip toggles at the 1↔2 terminal boundary (~40px area change), so the cached viewport goes stale.
   const prevTabStripVisibleRef = useRef(tabStripVisible)
   useEffect(() => {
     if (prevTabStripVisibleRef.current === tabStripVisible) {
@@ -223,10 +194,7 @@ export function useTerminalViewportRefit(
     scheduleViewportRefit()
   }, [tabStripVisible, viewportMeasuredRef, scheduleViewportRefit])
 
-  // Why: fold/unfold and rotation change the window dimensions without any
-  // subscribe or tab-strip transition. The PTY must be re-fitted to the new
-  // viewport or the terminal keeps the old grid (fit scale is capped at 1,
-  // so a grown window leaves the surface pinned to a fraction of the screen).
+  // Why: fold/unfold and rotation change window dims with no subscribe/tab change; refit or the grid stays stale (fit capped at 1).
   const { width: windowWidth, height: windowHeight } = useWindowDimensions()
   const prevWindowDimsRef = useRef({ width: windowWidth, height: windowHeight })
   useEffect(() => {
@@ -235,8 +203,7 @@ export function useTerminalViewportRefit(
       return
     }
     prevWindowDimsRef.current = { width: windowWidth, height: windowHeight }
-    // Why: adjustResize can change only window height while the IME is open;
-    // the frame-height notifier schedules one correction after it closes.
+    // Why: adjustResize can change only window height while the IME is open; the frame-height notifier corrects once it closes.
     if (prev.width === windowWidth && frameHeightRefitStateRef.current.keyboardVisible) {
       return
     }
@@ -244,10 +211,7 @@ export function useTerminalViewportRefit(
     scheduleViewportRefit()
   }, [windowWidth, windowHeight, viewportMeasuredRef, scheduleViewportRefit])
 
-  // Why: the text size changed, so the WebView is re-rendering at a new font/cell
-  // size. Re-measure and resize the PTY so the server reflows to the new column
-  // count. The refit's own 150ms debounce gives the WebView a frame to apply the
-  // new fontSize before we measure the resulting cell metrics.
+  // Why: on text-size change the refit's 150ms debounce lets the WebView apply the new fontSize before we re-measure cell metrics.
   const prevTextScaleRef = useRef(textScale)
   useEffect(() => {
     if (prevTextScaleRef.current === textScale) {
@@ -258,10 +222,7 @@ export function useTerminalViewportRefit(
     scheduleViewportRefit()
   }, [textScale, viewportMeasuredRef, scheduleViewportRefit])
 
-  // Why: the terminal's measured frame width changes when a panel docks/undocks or
-  // either sidebar is drag-resized — none of which touch the window dims or tab
-  // strip — so the cached viewport goes stale and the PTY keeps the pre-resize
-  // width. Mark un-measured and refit when the measured width changes.
+  // Why: panel dock/undock or sidebar resize changes frame width with no window/tab change, so the cached viewport goes stale.
   const prevFrameWidthRef = useRef(terminalFrameWidth)
   useEffect(() => {
     if (prevFrameWidthRef.current === terminalFrameWidth) {
@@ -284,8 +245,7 @@ export function useTerminalViewportRefit(
     },
     [viewportMeasuredRef, scheduleViewportRefit]
   )
-  // Why: notify imperatively so layout churn does not rerender the full session;
-  // a height change during typing is coalesced into one refit after keyboard close.
+  // Why: notify imperatively so layout churn doesn't rerender the full session.
   const notifyTerminalFrameHeight = useCallback(
     (height: number) => notifyFrameHeightRefitEvent({ type: 'frame-height', height }),
     [notifyFrameHeightRefitEvent]
@@ -310,8 +270,7 @@ export function useTerminalViewportRefit(
       if (!shouldRefit) {
         return
       }
-      // Why: the cached grid can match while the host PTY changed in background;
-      // reasserting equal dimensions is the convergence signal after iOS resume.
+      // Why: cached grid can match while the host PTY changed in background; reassert equal dims to converge after iOS resume.
       viewportMeasuredRef.current = false
       scheduleForcedViewportRefit()
     })
@@ -325,11 +284,9 @@ export function useTerminalViewportRefit(
     if (previous === 'connected' || connState !== 'connected') {
       return
     }
-    // Why: an in-place desktop upgrade may add updateViewport; reconnect is the
-    // narrow boundary where an old-host method_not_found cache becomes stale.
+    // Why: an in-place desktop upgrade may add updateViewport; reconnect is where the cached method_not_found goes stale.
     updateViewportCapabilityRef.current = 'unknown'
-    // Why: reconnect can restore a PTY whose host-side size changed while the
-    // socket was down, so equal cached dimensions still need reassertion.
+    // Why: reconnect can restore a PTY resized while the socket was down, so equal cached dims still need reassertion.
     viewportMeasuredRef.current = false
     scheduleForcedViewportRefit()
   }, [connState, viewportMeasuredRef, scheduleForcedViewportRefit])
diff --git a/mobile/src/terminal/terminal-webview-html.ts b/mobile/src/terminal/terminal-webview-html.ts
index e9d188b74ef..a4d9c350c47 100644
--- a/mobile/src/terminal/terminal-webview-html.ts
+++ b/mobile/src/terminal/terminal-webview-html.ts
@@ -1,5 +1,4 @@
-// xterm.js WebView document + default Tokyonight theme. Extracted from
-// TerminalWebView.tsx to keep that file within the max-lines budget.
+// xterm.js WebView document + default Tokyonight theme; extracted from TerminalWebView.tsx for the max-lines budget.
 import type { RuntimeMobileTerminalTheme } from '../../../src/shared/runtime-types'
 import { colors } from '../theme/mobile-theme'
 import { TERMINAL_TEXT_SCALES } from '../storage/preferences'
@@ -38,15 +37,7 @@ const DEFAULT_TERMINAL_THEME: RuntimeMobileTerminalTheme['theme'] = {
   brightWhite: '#c0caf5'
 }
 
-// Why: TUI apps (Claude Code / Ink) emit escape codes with absolute cursor
-// positioning designed for the desktop's terminal dimensions (~150+ cols).
-// We initialize xterm at the desktop's exact cols/rows so those escape codes
-// render correctly, then use a measured CSS transform: scale() to fit the
-// canvas into the phone viewport. The scale is computed after xterm opens
-// by measuring the rendered surface width, not hardcoded, so it adapts to
-// any terminal column count (80, 150, 200+). All touch gestures (scroll,
-// pinch-to-zoom, pan) are handled by custom JS rather than native WebView
-// behavior, so they work correctly with the CSS scale transform.
+// Why: TUI escape codes assume the desktop's cols/rows, so init xterm at those dims and fit the phone via a measured CSS scale() instead of resizing.
 export const XTERM_HTML = `<!DOCTYPE html>
 <html>
 <head>
@@ -1892,6 +1883,5 @@ ${TERMINAL_WEBGL_RECOVERY_JS}
 </body>
 </html>`
 
-// Why: WebView treats source identity as page identity on some platforms; keep
-// parent/session re-renders from reloading xterm and forcing fresh snapshots.
+// Why: some WebViews treat source identity as page identity; keep this stable so re-renders don't reload xterm.
 export const XTERM_WEBVIEW_SOURCE = { html: XTERM_HTML }
diff --git a/mobile/src/transport/client-context.tsx b/mobile/src/transport/client-context.tsx
index d9e07be4033..80ec7f11c1f 100644
--- a/mobile/src/transport/client-context.tsx
+++ b/mobile/src/transport/client-context.tsx
@@ -1,14 +1,5 @@
-// Why: collapses the per-screen WebSocket connection model into a single
-// shared RpcClient per host. Implements the design in
-// docs/mobile-shared-client-per-host.md.
-//
-// Lifecycle rules:
-// - First request for a host opens its client lazily.
-// - Refcount tracks active subscribers; when it drops to zero we schedule
-//   a 30-second idle close timer. If a new subscriber arrives within that
-//   window we cancel and reuse the same client.
-// - removeHost() forces an immediate close so re-pairing gets a fresh
-//   transport.
+// Single shared RpcClient per host, collapsing the old per-screen WebSocket connections.
+// Design: docs/mobile-shared-client-per-host.md.
 import {
   createContext,
   useCallback,
@@ -42,40 +33,28 @@ export type RpcClientContextValue = {
   closeHost: (hostId: string) => void
   getState: (hostId: string) => ConnectionState
   getReconnectAttempt: (hostId: string) => number
-  // Why: timestamp (ms epoch) of the last successful 'connected' state
-  // transition for this host, or null if never connected this session.
-  // Used by the UI to escalate "Reconnecting…" into a "host appears
-  // unreachable, re-pair?" prompt.
+  // Why: ms-epoch of the last 'connected' (null if never this session); UI escalates "Reconnecting…" into a re-pair prompt.
   getLastConnectedAt: (hostId: string) => number | null
   getActivePath: (hostId: string) => MobileConnectionPath
   subscribeHostState: (hostId: string, listener: (state: ConnectionState) => void) => () => void
   getAllClients: () => Array<{ hostId: string; client: RpcClient }>
   subscribeAllHosts: (listener: () => void) => () => void
-  // Why: lets the home screen feed already-loaded HostProfiles in so we
-  // don't pay loadHosts() latency twice (once in the focus-effect, again
-  // inside openEntry).
+  // Why: lets the home screen feed already-loaded HostProfiles so we don't pay loadHosts() latency twice.
   primeHosts: (hosts: HostProfile[]) => void
 }
 
 const Ctx = createContext<RpcClientContextValue | null>(null)
 
 export function RpcClientProvider({ children }: { children: ReactNode }) {
-  // Why: entries live in a ref so updates don't force re-renders of the
-  // entire tree on every connection state change. State propagation goes
-  // through per-host listener Sets instead.
+  // Why: entries in a ref so state changes don't re-render the whole tree; propagation goes through per-host listener Sets.
   const storeRef = useRef<Map<string, StoreEntry>>(new Map())
   const stateListenersRef = useRef<Map<string, Set<(state: ConnectionState) => void>>>(new Map())
   const allHostsListenersRef = useRef<Set<() => void>>(new Set())
 
-  // Pending opens (avoid two acquire() callers in the same render racing the
-  // host lookup). Keyed by hostId, value is a sentinel resolved when the
-  // entry materialises.
+  // Pending opens keyed by hostId so two acquire() callers in the same render don't race the host lookup.
   const pendingOpensRef = useRef(new HostClientOpenRegistry())
 
-  // Why: a fast-path cache of already-loaded HostProfiles. Screens that
-  // have run loadHosts() can call primeHosts() to populate this and skip
-  // the second loadHosts() inside openEntry. Without this we'd serialize
-  // two Keychain passes on cold start.
+  // Why: cache of already-loaded HostProfiles so openEntry can skip a second loadHosts()/Keychain pass on cold start.
   const primedHostsRef = useRef<Map<string, HostProfile>>(new Map())
 
   function notifyHostState(hostId: string, state: ConnectionState) {
@@ -118,28 +97,20 @@ export function RpcClientProvider({ children }: { children: ReactNode }) {
     const pendingOpen = pendingOpensRef.current.register(hostId, promise)
 
     try {
-      // Why: prefer the primed cache (populated by primeHosts when the
-      // screen already ran loadHosts) so we don't serialize a second
-      // Keychain pass behind the first one on cold start.
+      // Why: prefer the primed cache so we don't serialize a second Keychain pass on cold start.
       let host = primedHostsRef.current.get(hostId)
       if (!host) {
         try {
           const hosts = await loadHosts()
           host = hosts.find((h) => h.id === hostId)
         } catch {
-          // Why: a Keychain failure on cold start (rare but observed —
-          // happens when iOS Keychain is mid-unlock or Android Keystore
-          // races the JS bridge). Surface it as 'disconnected' so the
-          // home card flips off the perma-spinner and the user can hit
-          // Reconnect from the action sheet to retry.
+          // Why: cold-start Keychain failure (iOS mid-unlock / Android Keystore race); surface 'disconnected' so the user can Reconnect.
           notifyHostState(hostId, 'disconnected')
           notifyAllHosts()
           return null
         }
         if (!host) {
-          // Why: returning silently leaves mounted screens on a permanent
-          // spinner (STA-1511) — surface 'disconnected' so they can render
-          // their waiting/retry affordance instead.
+          // Why: silent return leaves screens on a permanent spinner (STA-1511); surface 'disconnected' so they show a retry affordance.
           notifyHostState(hostId, 'disconnected')
           notifyAllHosts()
           return null
@@ -160,9 +131,7 @@ export function RpcClientProvider({ children }: { children: ReactNode }) {
       try {
         client = openHostLogicalClient(host, (entry) => connectionLogStore.append(hostId, entry))
       } catch {
-        // Why: connect() can throw synchronously if the public key is
-        // malformed or the endpoint URL is invalid. Notify so the UI
-        // doesn't sit on a stale 'connecting' label forever.
+        // Why: openHostLogicalClient can throw synchronously (bad public key / invalid URL); notify so the UI leaves 'connecting'.
         notifyHostState(hostId, 'disconnected')
         notifyAllHosts()
         return null
@@ -191,12 +160,7 @@ export function RpcClientProvider({ children }: { children: ReactNode }) {
     }
   }, [])
 
-  // Why: `acquire` is the synchronous get-or-open. If the entry already
-  // exists, return its client immediately and bump the refcount. If not,
-  // kick off an async open (the consumer will subscribe via
-  // `subscribeHostState` and re-read once 'connecting' fires). Optionally
-  // accepts the HostProfile so the caller can avoid an extra loadHosts()
-  // pass inside openEntry.
+  // Synchronous get-or-open: returns an existing client immediately, else kicks off an async open and returns null this tick.
   const acquire = useCallback(
     (hostId: string, host?: HostProfile): RpcClient | null => {
       if (host) {
@@ -207,9 +171,7 @@ export function RpcClientProvider({ children }: { children: ReactNode }) {
         existing.refCount += 1
         return existing.client
       }
-      // Trigger async open. The acquire-side will return null this tick and
-      // try again once the state listener fires; consumers are expected to
-      // call acquire() inside an effect that re-runs on state changes.
+      // Trigger async open; returns null this tick — consumers re-call acquire() from an effect that re-runs on state changes.
       void openEntry(hostId).then((entry) => {
         if (!entry) {
           return
@@ -227,14 +189,7 @@ export function RpcClientProvider({ children }: { children: ReactNode }) {
     }
   }, [])
 
-  // Why: refcount dropping to 0 no longer triggers an idle-close. The
-  // app deliberately keeps live WebSockets open while the app itself is
-  // foregrounded — closing on transient navigation gaps was producing
-  // false 'disconnected' flashes when the user navigated home → host →
-  // back to home faster than React could re-acquire on the home side.
-  // Connections still close on: explicit user Disconnect, host removal,
-  // app backgrounding (OS-level socket suspension), and provider
-  // unmount (app shutdown).
+  // Why: no idle-close on refcount→0 — transient nav gaps flashed false 'disconnected', so keep sockets alive while foregrounded.
   const release = useCallback((hostId: string) => {
     const entry = storeRef.current.get(hostId)
     if (!entry) {
@@ -246,10 +201,7 @@ export function RpcClientProvider({ children }: { children: ReactNode }) {
   const forceReconnect = useCallback(
     async (hostId: string) => {
       const entry = storeRef.current.get(hostId)
-      // Why: preserve refcount across the swap. If the user reaches
-      // forceReconnect via the Disconnect → Reconnect path, the entry
-      // was already closed and refCount=0; fall back to active listener
-      // count as a proxy for "screens still watching this host."
+      // Why: preserve refcount across the swap; via Disconnect→Reconnect the entry is already gone, so fall back to listener count.
       const listenerCount = stateListenersRef.current.get(hostId)?.size ?? 0
       const savedRefCount = entry?.refCount ?? Math.max(1, listenerCount)
       if (entry) {
@@ -318,16 +270,7 @@ export function RpcClientProvider({ children }: { children: ReactNode }) {
     }
   }, [])
 
-  // Close all clients on provider unmount (app shutdown).
-  // Why: deps must be empty so this cleanup ONLY runs on real unmount.
-  // Hot-reload re-evaluates this module, which makes closeEntry a new
-  // function identity. With [closeEntry] as deps, every Fast Refresh
-  // would tear down all open WebSockets, leaving screens holding closed
-  // clients and the user staring at a 'Reconnecting…' card. Reading
-  // storeRef.current and the locally-scoped closeEntry inside the
-  // cleanup is safe — the ref is stable across renders, and the
-  // function captured here will be the one defined in the same
-  // closure as this effect.
+  // Close all clients on provider unmount. Empty deps: [closeEntry] would let Fast Refresh tear down all live sockets.
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(() => {
     const store = storeRef.current
@@ -339,9 +282,7 @@ export function RpcClientProvider({ children }: { children: ReactNode }) {
     }
   }, [])
 
-  // Why: nudge every live client when the OS signals the link may be back
-  // (foreground, network restored/switched) so sessions recover without an
-  // app restart (issue #5049).
+  // Why: nudge live clients when the OS signals the link may be back so sessions recover without a restart (issue #5049).
   useEffect(() => {
     return subscribeConnectionRevivalTriggers(() => {
       for (const entry of storeRef.current.values()) {
@@ -392,9 +333,7 @@ export function useRpcClientContext(): RpcClientContextValue {
   return ctx
 }
 
-// Why: the primary hook for screens. Acquires the shared client for a
-// hostId on mount and releases on unmount. Re-renders when the host's
-// connection state changes.
+// Primary hook for screens: acquires the shared client on mount, releases on unmount, re-renders on state change.
 export function useHostClient(hostId: string | undefined): {
   client: RpcClient | null
   state: ConnectionState
@@ -419,17 +358,13 @@ export function useHostClient(hostId: string | undefined): {
         return
       }
       setState(next)
-      // Why: the client materialises after an async open, and forceReconnect
-      // swaps in a fresh client object. Re-read on every state change so a
-      // mounted screen never keeps driving a stale (closed) client.
+      // Why: async open and forceReconnect swap the client object; re-read each state change so screens never drive a stale one.
       const found = ctx.getAllClients().find((entry) => entry.hostId === hostId)
       if (found && found.client !== clientRef.current) {
         clientRef.current = found.client
         force((n) => n + 1)
       } else if (!found && clientRef.current) {
-        // Why: closeHost deletes the entry without a replacement; holding the
-        // closed client would let screens keep issuing requests that can never
-        // resolve (STA-1511). Null it so they render disconnected states.
+        // Why: closeHost deletes the entry with no replacement; null it so screens don't drive a dead client (STA-1511).
         clientRef.current = null
         force((n) => n + 1)
       }
@@ -450,9 +385,7 @@ export function useHostClient(hostId: string | undefined): {
   return { client: clientRef.current, state }
 }
 
-// Why: home screen renders all paired hosts at once. Acquires each on
-// mount, releases on unmount. The provider's refcounting ensures we
-// don't double-open if a host-detail screen is also open.
+// Why: refcounting prevents a double-open when a host-detail screen shares one of these hosts.
 export function useAllHostClients(hostIds: string[]): Array<{
   hostId: string
   client: RpcClient
@@ -510,9 +443,7 @@ export function useAllHostClients(hostIds: string[]): Array<{
   }, [key, tick])
 }
 
-// Why: removeHost() in host-store.ts must close the live client, but
-// host-store has no React-side handle. Expose a hook that lets callers
-// close a host after removal.
+// Why: host-store's removeHost() must close the live client but has no React-side handle; this hook bridges to it.
 export function useCloseHost(): (hostId: string) => void {
   const ctx = useRpcClientContext()
   return ctx.closeHost
@@ -524,9 +455,7 @@ export function useForceReconnect(): (hostId: string) => Promise<void> {
   return ctx.forceReconnect
 }
 
-// Why: lets the home screen feed already-loaded HostProfiles in so the
-// provider can skip its own loadHosts() pass when it eventually opens
-// each host — collapses two serial Keychain reads on cold-start into one.
+// Why: primes already-loaded HostProfiles so the provider can skip a second loadHosts()/Keychain pass on cold start.
 export function usePrimeHosts(): (hosts: HostProfile[]) => void {
   const ctx = useRpcClientContext()
   return ctx.primeHosts
diff --git a/mobile/src/transport/host-store.ts b/mobile/src/transport/host-store.ts
index a404379e557..61ed6742d12 100644
--- a/mobile/src/transport/host-store.ts
+++ b/mobile/src/transport/host-store.ts
@@ -23,16 +23,12 @@ import { deleteMobileRelayDirectUpgradeJournal } from './mobile-relay-direct-upg
 import { scheduleOrphanedMobileRelayCleanup } from './mobile-relay-orphan-cleanup'
 
 const STORAGE_KEY = 'orca:hosts'
-// Why: SecureStore keys must match [A-Za-z0-9._-]; colons are rejected.
-// Use dots as the separator so the key shape stays readable while
-// satisfying the validator.
+// Why: SecureStore keys must match [A-Za-z0-9._-] (colons rejected), so use dots as the separator.
 const TOKEN_KEY_PREFIX = 'orca.host-token.'
 const WEB_TOKEN_KEY_PREFIX = 'orca:web-host-token:'
 
-// Why: WHEN_UNLOCKED_THIS_DEVICE_ONLY keeps the pairing token off
-// iCloud Keychain and out of iCloud/iTunes backup restores onto a
-// different physical device. Reads/writes are silent (no biometric
-// prompt) since we don't request access control flags.
+// Why: WHEN_UNLOCKED_THIS_DEVICE_ONLY keeps the pairing token off iCloud Keychain and out of backup restores onto another device.
+// Reads/writes stay silent (no biometric prompt) because we don't request access control flags.
 const KEYCHAIN_OPTIONS: SecureStore.SecureStoreOptions = {
   keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY
 }
@@ -46,8 +42,7 @@ function webTokenKey(hostId: string): string {
 }
 
 async function readDeviceToken(hostId: string): Promise<string | null> {
-  // Why: Expo SecureStore has no working web backend; keep this fallback
-  // web-only so native builds still keep pairing tokens in the keychain.
+  // Why: Expo SecureStore has no working web backend; fall back to AsyncStorage only on web so native still uses the keychain.
   if (Platform.OS === 'web') {
     return AsyncStorage.getItem(webTokenKey(hostId))
   }
@@ -76,18 +71,10 @@ async function deleteHostCredentials(hostId: string): Promise<void> {
   await deleteMobileRelayDirectUpgradeJournal(hostId)
 }
 
-// Why: SecureStore reads on Android Keystore can take 50-200ms each, and
-// loadHosts() is called from every screen mount + every useFocusEffect.
-// Stack with N hosts and you get N*200ms blocking every navigation, which
-// triggers connection-churn cycles in the home-screen useEffect. Cache
-// per-hostId in memory; invalidate only on save/remove. The cache lives
-// for the JS-runtime lifetime, which matches AsyncStorage semantics
-// (cleared on app uninstall, persisted across foreground/background).
+// Why: Keychain reads are slow (50-200ms) and loadHosts() runs on every screen mount; cache per-hostId in memory, invalidate on save/remove.
 const tokenCache = new Map<string, string>()
 let inflightLoad: Promise<HostProfile[]> | null = null
-// Why: rename / lastConnected / remove / save all RMW the same hosts JSON.
-// Without a queue, concurrent writers re-read a stale snapshot and the last
-// setItem wins — resurrecting a removed host or dropping a rename.
+// Why: serialize RMW of the shared hosts JSON; without a queue concurrent writers drop writes (resurrect a removed host, drop a rename).
 let hostListMutation: Promise<void> = Promise.resolve()
 
 function parseStoredHosts(raw: string | null): StoredHostProfile[] | null {
@@ -100,9 +87,7 @@ function parseStoredHosts(raw: string | null): StoredHostProfile[] | null {
       return null
     }
     return parsed.flatMap((item) => {
-      // Why: pre-v0.0.3 records carry the deviceToken in AsyncStorage.
-      // Drop them silently — the three pre-launch users will re-pair on
-      // first run rather than carry a migration shim through the auth path.
+      // Why: pre-v0.0.3 records stored deviceToken in AsyncStorage; drop them (users re-pair) rather than carry a migration shim.
       if (item && typeof item === 'object' && 'deviceToken' in item) {
         return []
       }
@@ -115,11 +100,9 @@ function parseStoredHosts(raw: string | null): StoredHostProfile[] | null {
 }
 
 export async function loadHosts(): Promise<HostProfile[]> {
-  // Why: writers hold the mutation chain across their full RMW; wait so a
-  // load right after rename/remove does not race a half-written list.
+  // Why: writers hold the mutation chain across their full RMW; wait so a load doesn't race a half-written list.
   await hostListMutation
-  // Why: deduplicate concurrent loadHosts() calls so multiple screens
-  // mounting simultaneously share one Keychain read pass.
+  // Why: deduplicate concurrent loadHosts() calls so simultaneously mounting screens share one Keychain read pass.
   if (inflightLoad) {
     return inflightLoad
   }
@@ -152,16 +135,11 @@ async function doLoadHosts(): Promise<HostProfile[]> {
       try {
         fetched = await readDeviceToken(stored.id)
       } catch {
-        // Why: a transient Keychain failure for one entry (e.g.
-        // errSecInteractionNotAllowed while the device is briefly locked,
-        // or a single corrupt record) must not blank the entire host list.
-        // Skip just this host — it'll reappear on the next load.
+        // Why: a transient Keychain failure for one entry (e.g. errSecInteractionNotAllowed while locked) must not blank the whole host list; skip it.
         continue
       }
       if (!fetched) {
-        // Why: orphaned metadata with no matching keychain entry — most
-        // likely a stale record from a development install. Skip it
-        // rather than surface a half-broken host.
+        // Why: orphaned metadata with no matching keychain entry; skip rather than surface a half-broken host.
         continue
       }
       token = fetched
@@ -187,8 +165,7 @@ export async function resolvePairingHostIdentity(
   publicKeyB64: string,
   newHostId: string
 ): Promise<{ id: string; name: string }> {
-  // Why: one durable read both preserves an existing identity and names a new host,
-  // avoiding duplicate cards and a second serial storage read before connecting.
+  // Why: one durable read both preserves an existing identity and names a new host, avoiding duplicate cards.
   await hostListMutation
   const hosts = await readStoredHostsForMutation()
   const match = hosts.find((host) => host.publicKeyB64 === publicKeyB64)
@@ -201,8 +178,7 @@ async function readStoredHostsForMutation(): Promise<StoredHostProfile[]> {
   try {
     const parsed = parseStoredHosts(await AsyncStorage.getItem(STORAGE_KEY))
     if (!parsed) {
-      // Why: refuse to RMW over unreadable payload — treating it as [] would
-      // wipe the durable host list on the next rename/remove/save.
+      // Why: refuse to RMW over unreadable payload — treating it as [] would wipe the durable host list on the next write.
       throw new Error('host list storage unreadable')
     }
     return parsed
@@ -260,8 +236,7 @@ async function persistHost(host: HostProfile, requireExisting: boolean): Promise
     }
     if (index >= 0) {
       updatedExistingHost = true
-      // Why: affected installs may already contain duplicate rows; an authoritative
-      // save is the safe point to collapse them to the preserved host id.
+      // Why: an authoritative save is the safe point to collapse pre-existing duplicate rows to the preserved host id.
       return hosts
         .filter(({ id }) => !duplicateHostIds.has(id))
         .map((candidate) => (candidate.id === stored.id ? stored : candidate))
@@ -272,11 +247,7 @@ async function persistHost(host: HostProfile, requireExisting: boolean): Promise
     }
     return [...hosts.filter(({ id }) => !duplicateHostIds.has(id)), stored]
   })
-  // Why: write metadata BEFORE the keychain token so a crash between the two
-  // leaves orphaned metadata (which loadHosts skips and removeHost can clean
-  // up) rather than an orphaned keychain token with no metadata pointer —
-  // the latter would persist forever since removeHost only deletes by hostId
-  // from current metadata.
+  // Why: write metadata before the keychain token so a crash leaves recoverable orphaned metadata, not an orphaned token that persists forever.
   await writeDeviceToken(stored.id, validated.deviceToken)
   tokenCache.set(stored.id, validated.deviceToken)
   if (validated.endpoints) {
@@ -293,8 +264,7 @@ async function persistHost(host: HostProfile, requireExisting: boolean): Promise
     overlayRemovalIds.push(stored.id)
   }
   if (overlayRemovalIds.length > 0) {
-    // Why: reusing an id for direct-only re-pairing must not retain routing
-    // metadata from the host's previous transport state.
+    // Why: reusing an id for direct-only re-pairing must not retain routing metadata from the previous transport state.
     await removeMobileRelayHostOverlays(overlayRemovalIds)
   }
   for (const duplicateHostId of duplicateHostIds) {
@@ -313,11 +283,9 @@ export async function removeHost(hostId: string): Promise<void> {
   try {
     await removeMobileRelayHostOverlay(hostId)
   } catch {
-    // The missing legacy base is authoritative, so a retained overlay cannot
-    // resurrect this host and can be cleaned on a later explicit retry.
+    // Base removal is authoritative; a retained overlay can't resurrect the host and is cleaned on a later retry.
   }
-  // Why: await only the durable cleanup intent (AsyncStorage). Native keychain
-  // delete can reject or stall and must not freeze removeHost / the UI.
+  // Why: keychain delete can stall/reject; await only the durable cleanup intent so removeHost can't freeze the UI.
   try {
     await scheduleHostCredentialCleanup(hostId, deleteHostCredentials)
   } catch {
@@ -333,10 +301,7 @@ export async function retryPendingHostCredentialCleanup(): Promise<{
   return retryPendingHostCredentialCleanups(deleteHostCredentials)
 }
 
-// Why: Edit host can change name and endpoint together; a single
-// mutateStoredHosts pass keeps both fields committed atomically so a
-// mid-save failure can never persist one change without the other, and a
-// host removed mid-edit throws consistently instead of silently no-oping.
+// Why: single mutation pass commits name + endpoint atomically so a mid-save failure can't persist one without the other.
 export async function updateHostNameAndEndpoint(
   hostId: string,
   updates: { name?: string; endpoint?: string }
@@ -368,9 +333,7 @@ export async function updateLastConnected(hostId: string): Promise<void> {
       return next
     })
   } catch {
-    // Why: last-connected is a best-effort timestamp and callers fire it with
-    // `void`. Swallow unreadable-storage failures so they don't surface as an
-    // unhandled promise rejection.
+    // Why: best-effort timestamp fired with void; swallow so unreadable storage doesn't reject.
   }
 }
 
diff --git a/mobile/src/transport/rpc-client.ts b/mobile/src/transport/rpc-client.ts
index 5420ba679a6..578e1a1ba0b 100644
--- a/mobile/src/transport/rpc-client.ts
+++ b/mobile/src/transport/rpc-client.ts
@@ -79,74 +79,36 @@ export type RpcClient = {
     viewport: { cols: number; rows: number }
   ) => void
   getState: () => ConnectionState
-  // Why: UI escalates "Reconnecting…" to "Can't connect" once attempts cross
-  // a threshold. 0 means never failed; counter is reset on successful open.
+  // 0 means never failed (reset on successful open); the UI escalates "Reconnecting…" to "Can't connect" past a threshold.
   getReconnectAttempt: () => number
-  // Why: timestamp (ms epoch) of the last time we reached 'connected'.
-  // null = never connected since the client was created. Used by the UI
-  // to distinguish "host moved/never reachable" from "transient blip".
+  // Last 'connected' timestamp (ms epoch); null = never connected. Lets the UI tell "never reachable" from "transient blip".
   getLastConnectedAt: () => number | null
   onStateChange: (listener: (state: ConnectionState) => void) => () => void
-  // Why: app-resume hook. Android/iOS can kill the TCP path or park the
-  // reconnect loop while the app is backgrounded; callers invoke this on
-  // AppState 'active' so the session recovers without an app restart.
+  // Why: app-resume hook — iOS/Android can kill the TCP path while backgrounded; call on AppState 'active' to recover.
   notifyForeground: () => void
   close: () => void
 }
 
-// Why: tiered backoff. The first four entries (500ms→4s) keep
-// auto-recovery snappy for the common case — a brief Wi-Fi blip,
-// laptop wake, or AP-isolation cycle. Beyond that we slow down
-// (8s→60s) so a phone whose desktop is genuinely unreachable doesn't
-// burn a TCP SYN every 4s indefinitely while still healing on its
-// own when the network recovers. With 12 total attempts, the last
-// four reuse the 60s cap (Math.min(idx, length-1)), so total elapsed
-// time across all 12 attempts is ≈ 6 minutes before the give-up cap
-// fires (0.5+1+2+4+8+15+30+60+60+60+60+60 ≈ 360s).
+// Why: tiered backoff — fast early entries recover blips; the slow tail avoids burning a SYN every 4s on an unreachable desktop.
 const RECONNECT_DELAYS = [500, 1000, 2000, 4000, 8000, 15_000, 30_000, 60_000]
-// Why: cap fast auto-retry once we're clearly unreachable for a long time.
-// With the tiered backoff above this is ≈ 6 minutes of continuous
-// failure before the UI surfaces the re-pair banner. The longer
-// runway tolerates flaky AP-isolation routers and laptop sleep cycles
-// that briefly drop the LAN path. MUST stay aligned with
-// connection-health.ts UNREACHABLE_ATTEMPTS so the "unreachable"
-// verdict matches the moment the loop slows to the trickle cadence.
+// Why: ≈6 min of failure before the re-pair banner; MUST stay aligned with connection-health.ts UNREACHABLE_ATTEMPTS.
 const GIVE_UP_AFTER_ATTEMPTS = 12
-// Why: past the cap the loop must never park permanently. A wedged
-// Tailscale/VPN tunnel produces no AppState or network-type transition
-// (still Wi-Fi, still "online"), so no revival nudge ever fires — users
-// had to toggle Tailscale off/on just to force one. A slow trickle dial
-// self-heals once the tunnel recovers while staying cheap: one TCP
-// attempt per 90s, foreground-only (iOS/Android suspend JS timers in
-// the background).
+// Why: never park past the cap — a wedged VPN fires no AppState/network nudge to revive it, so trickle-dial every 90s to self-heal.
 const TRICKLE_RECONNECT_DELAY_MS = 90_000
-// Why: a single `unauthorized`/`e2ee_error` is not proof the pairing is dead.
-// Issue #5200: a tablet showed "Auth failed" and forced a needless re-pair
-// while the desktop still listed it as paired with a valid token — a transient
-// rejection (mid-session resume race, a stale frame after background) latched
-// the terminal auth-failed state permanently. Retry the full handshake this
-// many times with a clean reconnect before declaring auth dead. A genuinely
-// revoked token is rejected on every attempt and converges to auth-failed in
-// seconds; a one-off glitch self-heals without the user re-pairing.
+// Why: one unauthorized isn't proof the pairing is dead (issue #5200) — retry the handshake this many times before latching auth-failed.
 const AUTH_RETRY_BUDGET = 3
 const REQUEST_TIMEOUT_MS = 30_000
 const CONNECT_TIMEOUT_MS = 12_000
 const HANDSHAKE_TIMEOUT_MS = 5_000
-// Why: RN's WebSocket implementation may not expose static readyState
-// constants, but the protocol value for CONNECTING is stable across runtimes.
+// Why: RN may not expose WebSocket.readyState constants, but the CONNECTING protocol value (0) is stable across runtimes.
 const WEBSOCKET_CONNECTING_STATE = 0
 
-// Why: RN auto-pongs WebSocket pings natively, so JS needs an app-level
-// liveness probe to detect half-open sockets. Any inbound app traffic after
-// a probe starts proves the link is alive; otherwise an unanswered probe
-// force-closes the socket so the reconnect path can recover.
+// Why: RN auto-pongs pings natively, so JS needs an app-level probe to detect half-open sockets.
 const ACTIVITY_PROBE_INTERVAL_MS = 20_000
 
 export type ConnectOptions = {
   onStateChange?: (state: ConnectionState) => void
-  // Fires for every observable lifecycle event so the UI can render a
-  // detailed connection log. Useful when 'Connecting…' hangs forever
-  // (e.g. broken Tailscale route) and you need to see *where* it's stuck.
+  // Fires for every lifecycle event so the UI can show where 'Connecting…' is stuck (e.g. broken Tailscale route).
   onLog?: ConnectionLogSink
 }
 
@@ -185,14 +147,10 @@ export function connect(
   let handshakeTimer: ReturnType<typeof setTimeout> | null = null
   let activityProbeTimer: ReturnType<typeof setInterval> | null = null
   let intentionallyClosed = false
-  // Why: consecutive auth rejections since the last successful connect. We
-  // tolerate up to AUTH_RETRY_BUDGET (issue #5200) before latching auth-failed
-  // so a transient rejection doesn't force a needless re-pair. Reset to 0 on
-  // every 'connected'.
+  // Consecutive auth rejections; tolerate up to AUTH_RETRY_BUDGET (issue #5200) before latching to avoid a needless re-pair.
   let authRejectionCount = 0
   let lastConnectedAt: number | null = null
-  // Why: cheap diagnostics for RN/OkHttp process-state poisoning: do retry
-  // attempts differ, is anything inbound, and are closes instant or slow?
+  // Why: cheap diagnostics for RN/OkHttp process-state poisoning (retry cadence, inbound traffic, close timing).
   let lastInboundAt: number | null = null
   let inboundSequence = 0
   let lastWsClosedAt: number | null = null
@@ -200,7 +158,6 @@ export function connect(
   let currentWsOpenedAt: number | null = null
 
   // Why: fresh ephemeral keypair per connection provides forward secrecy.
-  // The shared key is derived from our ephemeral secret + server's static public key.
   let sharedKey: Uint8Array | null = null
   const serverPublicKey = publicKeyFromBase64(serverPublicKeyB64)
 
@@ -218,9 +175,7 @@ export function connect(
     stateListeners.add(onStateChange)
   }
 
-  // Diagnostic: tracks how long we've been in the current state. Useful
-  // for spotting "stuck in connecting" or "stuck in reconnecting" cases
-  // in the logs.
+  // Diagnostic: dwell time in the current state, for spotting "stuck in connecting/reconnecting".
   let stateEnteredAt = Date.now()
 
   function rejectConnectWaiters(reason: string) {
@@ -250,8 +205,7 @@ export function connect(
     })
     if (next === 'connected') {
       lastConnectedAt = Date.now()
-      // Why: a clean handshake proves the token is valid — clear the auth
-      // retry budget so a future isolated rejection gets the full budget again.
+      // Why: a clean handshake proves the token is valid — reset the auth retry budget.
       authRejectionCount = 0
       for (const waiter of connectWaiters.splice(0)) {
         if (waiter.timeout) {
@@ -269,8 +223,7 @@ export function connect(
     }
   }
 
-  // Why: don't dump device tokens / full URLs into log scrolls; truncate to
-  // the host:port so reconnect lifecycles are still readable.
+  // Why: keep device tokens / full URLs out of log scrolls — truncate to host:port.
   function redactedEndpoint(ep: string): string {
     try {
       const m = ep.match(/^wss?:\/\/([^/]+)/i)
@@ -288,17 +241,13 @@ export function connect(
       return Promise.reject(new Error('Client closed'))
     }
     if (state === 'reconnecting' && reconnectAttempt >= GIVE_UP_AFTER_ATTEMPTS) {
-      // Why: past the retry cap the loop only trickles every 90s — callers
-      // must fail fast rather than hang on a host that's been unreachable
-      // for minutes. A trickle dial that succeeds flips state to 'connected'
-      // and later requests go through normally.
+      // Why: past the cap the loop only trickles every 90s — fail fast instead of hanging on a long-unreachable host.
       return Promise.reject(new Error('Connection retry limit reached'))
     }
     return new Promise((resolve, reject) => {
       const waiter: ConnectWaiter = { resolve, reject, timeout: null }
       if (timeoutMs !== undefined) {
-        // Why: explicit per-request timeouts must include offline/reconnect
-        // waiting, not only the RPC after the socket becomes connected.
+        // Why: per-request timeouts must cover offline/reconnect waiting, not just the RPC after connect.
         waiter.timeout = setTimeout(
           () => {
             const index = connectWaiters.indexOf(waiter)
@@ -328,11 +277,7 @@ export function connect(
     console.log('[net] openConnection', {
       attempt: reconnectAttempt,
       endpoint: redactedEndpoint(endpoint),
-      // Why: process-poisoning diagnostic. If wsCount is high (e.g. >50)
-      // and every recent open fails with 1006, suspect RN/OkHttp internal
-      // pool corruption that only force-quit clears. Compare msSinceLast*
-      // values to the failure cadence: instant repeated fails with no
-      // inbound traffic between them = process-state stuck.
+      // Why: diagnostic for RN/OkHttp pool corruption — high wsCount + repeated 1006 closes means process-state stuck.
       wsCount: wsConstructionCounter,
       msSinceLastConnected: lastConnectedAt != null ? now - lastConnectedAt : null,
       msSinceLastClose: lastWsClosedAt != null ? now - lastWsClosedAt : null,
@@ -354,8 +299,7 @@ export function connect(
       if (ws === openingWs) {
         return false
       }
-      // Why: React Native can deliver callbacks from a timed-out socket after
-      // reconnect has swapped in a replacement; stale events must not mutate it.
+      // Why: RN can deliver callbacks from a timed-out socket after reconnect swapped in a replacement — ignore them.
       console.log('[net] stale ws event ignored', {
         eventName,
         state,
@@ -364,9 +308,7 @@ export function connect(
       return true
     }
 
-    // Why: React Native can leave TCP/WebSocket opens pending indefinitely on
-    // flaky network handoffs. Force the existing onclose reconnect path if
-    // onopen never arrives, instead of leaving the UI stuck at "Connecting...".
+    // Why: RN can leave opens pending forever on flaky handoffs — force reconnect if onopen never arrives.
     connectTimer = setTimeout(() => {
       connectTimer = null
       if (ws === openingWs && openingWs.readyState === WEBSOCKET_CONNECTING_STATE) {
@@ -396,9 +338,7 @@ export function connect(
       setState('handshaking')
       emitLog('success', 'WebSocket open', 'Starting E2EE handshake')
 
-      // Why: generate a fresh ephemeral keypair for each connection.
-      // This provides forward secrecy — compromising one session's key
-      // doesn't compromise past or future sessions.
+      // Why: fresh ephemeral keypair per connection provides forward secrecy.
       const ephemeral = generateKeyPair()
       const hello = JSON.stringify({
         type: 'e2ee_hello',
@@ -437,8 +377,7 @@ export function connect(
       lastInboundAt = Date.now()
       const raw = typeof rawData === 'string' ? rawData : null
 
-      // Why: during handshaking, e2ee_ready is plaintext because it precedes
-      // encrypted auth; e2ee_authenticated/e2ee_error are encrypted.
+      // Why: e2ee_ready is plaintext (precedes encrypted auth); e2ee_authenticated/e2ee_error are encrypted.
       if (state === 'handshaking') {
         if (raw === null) {
           return
@@ -481,9 +420,7 @@ export function connect(
                 removeStreamListener(id)
                 continue
               }
-              // Why: setState('connected') notifies UI listeners synchronously;
-              // a listener may subscribe and send immediately before this
-              // reconnect replay loop resumes.
+              // Why: a UI listener notified synchronously by setState('connected') may already have sent this stream — skip it.
               if (stream.sent) {
                 continue
               }
@@ -515,8 +452,7 @@ export function connect(
         return
       }
 
-      // Why: guard against decrypt with an invalid key — sharedKey can be null
-      // after destroy() or if a message arrives during a reconnect race.
+      // Why: sharedKey can be null after destroy() or a reconnect race — don't decrypt with an invalid key.
       if (!sharedKey || sharedKey.length !== 32) {
         return
       }
@@ -553,10 +489,7 @@ export function connect(
       }
       recordValidatedInboundTraffic()
 
-      // Why: a mid-session unauthorized may be a transient glitch, not a dead
-      // pairing (issue #5200). handleAuthRejection retries the handshake a few
-      // times before latching auth-failed, while still bounding churn via the
-      // budget so a genuinely revoked token doesn't reconnect forever.
+      // Why: a mid-session unauthorized may be transient (issue #5200) — handleAuthRejection retries before latching auth-failed.
       if (!response.ok && response.error.code === 'unauthorized') {
         handleAuthRejection('Unauthorized — pairing may be revoked')
         return
@@ -646,18 +579,12 @@ export function connect(
     ws.onclose = (event) => {
       const e = event as { code?: number; reason?: string; wasClean?: boolean } | undefined
       const closeAt = Date.now()
-      // Why: time-since-construct distinguishes failure modes. Instant
-      // close (<300ms) = TCP RST / port closed / route unreachable / RN
-      // synchronous reject. Mid (300ms–3s) = DNS/connect attempt + reset.
-      // Slow (>3s) = TCP SYN timeout / packet loss / NAT wedge. If an
-      // entire reconnect burst is all instant, the problem is local
-      // process state or routing, not packet loss.
+      // Why: time-since-construct classifies the failure — instant close = RST/unreachable, slow = SYN timeout/packet loss.
       const constructToCloseMs = currentWsOpenedAt != null ? closeAt - currentWsOpenedAt : null
       const aliveMs =
         currentWsOpenedAt != null && state === 'connected' ? closeAt - currentWsOpenedAt : null
       const inboundIdleMs = lastInboundAt != null ? closeAt - lastInboundAt : null
-      // Why: statically imported (not closure-built) — an earlier hot-reload
-      // bug came from a stale closure capturing a half-loaded module.
+      // Why: statically imported — a hot-reload bug came from a stale closure capturing a half-loaded module.
       const closeEvent = describeSocketEvent(event)
       console.log('[net] ws.onclose', {
         code: e?.code,
@@ -682,9 +609,7 @@ export function connect(
       if (ignoreStaleSocketEvent('error')) {
         return
       }
-      // Why: RN surfaces network errors here (DNS failure, TCP RST, etc).
-      // onclose fires right after, but logging the error message gives us
-      // the original cause that the close code alone can hide.
+      // Why: RN surfaces the original network error here — onclose follows but its close code alone hides the cause.
       const e = event as { message?: string } | undefined
       const errEvent = describeSocketEvent(event)
       console.log('[net] ws.onerror', {
@@ -734,11 +659,7 @@ export function connect(
     scheduleReconnect()
   }
 
-  // Why: a token rejection (handshake e2ee_error/unauthorized or a mid-session
-  // unauthorized RPC) may be transient — issue #5200. Retry the full handshake
-  // up to AUTH_RETRY_BUDGET times before declaring auth dead, so a one-off
-  // glitch self-heals instead of forcing the user to re-pair. A genuinely
-  // revoked token fails every retry and latches auth-failed within seconds.
+  // Why: an auth rejection may be transient (issue #5200) — retry up to AUTH_RETRY_BUDGET times before latching auth-failed.
   function handleAuthRejection(reason: string): void {
     activeBrowserScreencastRequestId = null
     pendingBrowserScreencastRequestId = null
@@ -754,9 +675,7 @@ export function connect(
         'Authentication rejected',
         `Retrying (${authRejectionCount}/${AUTH_RETRY_BUDGET})`
       )
-      // Why: close the current socket but DON'T set intentionallyClosed —
-      // we want handleSocketClosed to route into the reconnect path so the
-      // token gets a fresh handshake. rejectAllPending unblocks in-flight RPCs.
+      // Why: close without setting intentionallyClosed so handleSocketClosed routes to reconnect and retries the handshake.
       const closing = ws
       ws = null
       sharedKey = null
@@ -782,19 +701,11 @@ export function connect(
   }
 
   function scheduleReconnect() {
-    // Why: spinning fast reconnects forever drains battery and floods logs
-    // when the host is genuinely unreachable (wrong IP, port closed,
-    // host moved). Past GIVE_UP_AFTER_ATTEMPTS the UI surfaces a
-    // "Can't reach desktop, re-pair?" banner and the loop drops to the
-    // 90s trickle cadence instead of parking — a permanently parked loop
-    // could only be revived by an AppState/network transition, which a
-    // wedged VPN tunnel never produces.
+    // Why: past the cap, trickle (never park) — a parked loop only revives on a network transition a wedged VPN never produces.
     const pastGiveUpCap = reconnectAttempt >= GIVE_UP_AFTER_ATTEMPTS
     let delay: number
     if (pastGiveUpCap) {
-      // Why: the counter holds at the cap — connection-health thresholds and
-      // the "Can't reach desktop" verdict key off attempts >= 12, and a
-      // successful open resets it to 0 anyway.
+      // Why: hold the counter at the cap — connection-health's "Can't reach desktop" verdict keys off attempts >= 12.
       delay = TRICKLE_RECONNECT_DELAY_MS
       rejectConnectWaiters('Connection retry limit reached')
     } else {
@@ -824,10 +735,7 @@ export function connect(
     }
   }
 
-  // Why: app-level liveness probe — see ACTIVITY_PROBE_INTERVAL_MS comment
-  // at the top of the file. Fires while the channel is in 'connected'
-  // state, sends a tiny status.get, and force-closes the WS if the probe
-  // fails (which the existing onclose path then turns into a reconnect).
+  // Why: app-level liveness probe (see ACTIVITY_PROBE_INTERVAL_MS) — force-closes the WS on failure so onclose reconnects.
   function runActivityProbe() {
     if (state !== 'connected' || !ws) {
       return
@@ -966,8 +874,7 @@ export function connect(
       removeStreamListener(id)
       return
     }
-    // Why: sent streams may still reply with `ready`; keep a tombstone so we
-    // can immediately unsubscribe. Queued streams never reached desktop.
+    // Why: a sent stream may still reply `ready`; keep the tombstone to unsubscribe it (queued streams never reached the desktop).
     if (!stream.sent) {
       removeStreamListener(id)
     }
@@ -1013,11 +920,7 @@ export function connect(
       hasKey: !!sharedKey,
       state
     })
-    // Why: if the state machine still thinks we're connected but the
-    // underlying WebSocket has flipped to CLOSING/CLOSED without onclose
-    // having fired (RN's WebSocket sometimes drops the event, or the
-    // server half-closed the stream), force a reconnect. Without this
-    // every send silently fails forever and the user sees a frozen UI.
+    // Why: RN can drop onclose, leaving state 'connected' over a dead socket; force reconnect or every send silently fails forever.
     if (state === 'connected' && ws && ws.readyState !== WebSocket.OPEN) {
       console.log('[net] sendEncrypted detected ws desync — forcing reconnect', {
         readyState: ws.readyState
@@ -1125,9 +1028,7 @@ export function connect(
         if (pendingBrowserScreencastRequestId && pendingBrowserScreencastRequestId !== id) {
           disposeBrowserScreencastStream(pendingBrowserScreencastRequestId)
         }
-        // Why: browser screencast frames are connection-scoped and carry no
-        // stream id. Wait for the replacement stream's ready response before
-        // routing frames, so in-flight old-page pixels are dropped.
+        // Why: screencast frames carry no stream id, so route only after the new stream's ready to drop stale old-page pixels.
         pendingBrowserScreencastRequestId = id
         activeBrowserScreencastRequestId = null
       }
@@ -1140,9 +1041,7 @@ export function connect(
           removeStreamListener(id)
         }
       } else {
-        // Stream is registered but the actual outbound subscribe will be
-        // sent (or re-sent) when the channel reaches 'connected'. Useful
-        // when terminals don't load — confirms the request is queued.
+        // Registered now; the outbound subscribe is (re-)sent once the channel reaches 'connected'.
         console.log('[net] subscribe queued — waiting for connected', { method, state })
       }
 
@@ -1157,12 +1056,7 @@ export function connect(
           return
         }
         if (stream?.method === 'terminal.subscribe') {
-          // Why: the runtime registers cleanup under the composite key
-          // `${terminal}:${clientId}` so two phones subscribing to the same
-          // terminal handle don't evict each other. Echo that composite key
-          // back on unsubscribe; also include `client.id` so the server can
-          // reconstruct it if a stale build emits a bare-handle id. See
-          // docs/mobile-presence-lock.md.
+          // Why: server keys cleanup by composite `${terminal}:${clientId}` so two phones don't evict each other. See docs/mobile-presence-lock.md.
           const unsubscribeParams = buildTerminalUnsubscribeParams(stream.params)
           if (unsubscribeParams) {
             sendEncrypted({
@@ -1211,20 +1105,14 @@ export function connect(
         return
       }
       if (state === 'connected') {
-        // Why: the OS can kill the TCP path while the app is backgrounded
-        // without delivering onclose, leaving a half-open socket that
-        // blackholes input. Probe now so death is detected in ≤8s instead
-        // of waiting out the 20s interval (issue #5049).
+        // Why: OS can kill the TCP path while backgrounded without onclose; probe now to detect the half-open socket in ≤8s (issue #5049).
         console.log('[net] foreground — probing live connection')
         startActivityProbe()
         runActivityProbe()
         return
       }
       if (state === 'reconnecting') {
-        // Why: while backgrounded the retry loop may be sitting on a 60s
-        // backoff or 90s trickle timer. Returning to the foreground is a
-        // strong user signal — restart with a fresh attempt budget
-        // immediately instead of waiting out the timer.
+        // Why: foreground is a strong user signal — restart immediately instead of waiting out a 60s/90s backoff timer.
         console.log('[net] foreground — restarting reconnect loop', {
           attempt: reconnectAttempt,
           hadTimer: !!reconnectTimer

From 0989128287b266bcb1d2927ed19758d50e47b4f6 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Mon, 20 Jul 2026 03:34:44 -0700
Subject: [PATCH 52/54] refactor(comments): slim verbose comments in
 shared/cli/relay/preload (#9544)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Collapse multi-line explanatory comment blocks into single-line "why" statements
per AGENTS.md ("Document the Why, Briefly"): drop restatements of the code and
mechanism narration; keep the non-obvious reason, external refs, and directives.

Comments-only — verified no code changed via a Babel/esbuild comment-strip
token-equality gate against origin/main; typecheck and oxlint clean.

Area: shared, cli, relay, preload. 26 files changed, 1039 insertions(+), 3300 deletions(-).

Co-authored-by: Orca <help@stably.ai>
---
 src/cli/handlers/orchestration.ts          | 101 +---
 src/preload/api-types.ts                   | 162 ++---
 src/preload/index.ts                       | 227 ++-----
 src/relay/agent-hook-server.ts             | 107 +---
 src/relay/dispatcher.ts                    |  82 +--
 src/relay/git-handler-status-ops.ts        |  47 +-
 src/relay/git-handler.test.ts              |  90 +--
 src/relay/git-handler.ts                   | 139 ++---
 src/relay/pty-handler.ts                   | 252 ++------
 src/relay/relay-handshake.ts               |  54 +-
 src/relay/relay.ts                         | 238 ++------
 src/shared/agent-hook-listener.ts          | 461 ++++----------
 src/shared/agent-status-types.test.ts      |  65 +-
 src/shared/agent-status-types.ts           | 142 ++---
 src/shared/constants.ts                    | 100 +--
 src/shared/git-remote-error.ts             |  77 +--
 src/shared/gitlab-types.ts                 | 120 +---
 src/shared/keybindings.ts                  | 154 ++---
 src/shared/quick-open-filter.ts            | 136 ++---
 src/shared/secure-file.ts                  |  72 +--
 src/shared/telemetry-events.ts             | 346 ++---------
 src/shared/terminal-output-side-effects.ts | 138 ++---
 src/shared/terminal-title-status.ts        |  95 +--
 src/shared/text-search.ts                  | 115 +---
 src/shared/tui-agent-config.ts             | 146 +----
 src/shared/types.ts                        | 669 ++++++---------------
 26 files changed, 1037 insertions(+), 3298 deletions(-)

diff --git a/src/cli/handlers/orchestration.ts b/src/cli/handlers/orchestration.ts
index fc285c56440..cdafcd66743 100644
--- a/src/cli/handlers/orchestration.ts
+++ b/src/cli/handlers/orchestration.ts
@@ -10,19 +10,13 @@ import { RuntimeClientError } from '../runtime-client'
 import { getTerminalHandle } from '../selectors'
 import { abbreviateOrchestrationTasks } from '../../shared/orchestration-task-summary'
 
-// Why: 15 s is well under Claude Code's empirical ~2 min Bash-tool silence
-// budget and generates only ~40 lines per 10 min wait — enough to assure the
-// parent process the subprocess is alive without flooding logs. See design
-// doc §3.4.
+// Why: 15 s is well under Claude Code's ~2 min Bash-tool silence budget while keeping log volume low. See design doc §3.4.
 const DEFAULT_KEEPALIVE_INTERVAL_MS = 15_000
 function getLifecycleGroupRecipientError(type: 'worker_done' | 'heartbeat'): string {
   return `${type} messages must be sent to a concrete coordinator terminal handle, not a group address.`
 }
 
-// Why: test-only escape hatch so subprocess tests can verify the feature in
-// under 10 s rather than needing a full 15 s silence window. Production users
-// should never set this — there is no surface documentation. A bogus value
-// falls back to the default rather than disabling the keepalive.
+// Why: test-only escape hatch so subprocess tests avoid the full 15 s window; bogus values fall back to the default.
 function resolveKeepaliveIntervalMs(): number {
   const raw = process.env.ORCA_KEEPALIVE_INTERVAL_MS ?? process.env.ORCA_HEARTBEAT_INTERVAL_MS
   if (!raw) {
@@ -40,16 +34,12 @@ function startCheckKeepalive(deadlineMs: number | undefined): () => void {
   const interval = setInterval(() => {
     const payload = {
       _keepalive: true,
-      // Why: retain the old marker for scripts filtering merged stderr while
-      // callers migrate to the unambiguous _keepalive field.
+      // Why: retain the old marker for scripts still filtering it while callers migrate to _keepalive.
       _heartbeat: true,
       elapsedMs: Date.now() - startedAt,
       deadlineMs: deadlineMs ?? null
     }
-    // Why: `process.stderr.write` is line-flushed per-call in Node, whereas a
-    // fully-buffered writer would hold all keepalive lines until exit and
-    // silently defeat the whole point of the ping. Subprocess test asserts
-    // this by reading stderr incrementally. See §3.4.
+    // Why: process.stderr.write is line-flushed per-call in Node; a buffered writer would hold keepalives until exit. See §3.4.
     process.stderr.write(`${JSON.stringify(payload)}\n`)
   }, resolveKeepaliveIntervalMs())
   if (typeof interval.unref === 'function') {
@@ -58,8 +48,7 @@ function startCheckKeepalive(deadlineMs: number | undefined): () => void {
   return () => clearInterval(interval)
 }
 
-// Why: mirrors TaskStatus (orchestration/types.ts) so the CLI can surface a
-// clear enum-aware error before the generic RPC Zod "Missing --status" message.
+// Why: mirrors TaskStatus (orchestration/types.ts) so the CLI surfaces an enum-aware error before the generic RPC message.
 const TASK_STATUS_VALUES = [
   'pending',
   'ready',
@@ -114,8 +103,7 @@ function getOptionalStructuredMessagePayload(
       'Use either --payload or structured payload flags, not both.'
     )
   }
-  // Why: raw JSON arguments are fragile in Windows PowerShell; these flags let
-  // workers send parseable orchestration payloads without shell-specific quoting.
+  // Why: raw JSON args are fragile in Windows PowerShell; these flags avoid shell-specific quoting.
   const payload: Record<string, string | string[]> = {}
   if (taskId) {
     payload.taskId = taskId
@@ -152,9 +140,7 @@ async function resolveOrchestrationTerminalHandle(
   const envHandle = process.env.ORCA_TERMINAL_HANDLE
   if (envHandle && envHandle.length > 0) {
     if (flagName === 'from' && options.validateEnvHandle) {
-      // Why: long-lived shells can retain an ORCA_TERMINAL_HANDLE after the
-      // runtime remints the pane handle; do not bake that stale id into
-      // coordinator preambles.
+      // Why: long-lived shells can retain a stale ORCA_TERMINAL_HANDLE after remint; don't bake it into coordinator preambles.
       const live = await isLiveTerminalHandle(envHandle, client)
       if (!live) {
         const reminted = await resolveOrchestrationPaneTerminalHandle(client)
@@ -184,8 +170,7 @@ async function resolveTaskCreatorTerminalHandle(
     live = await isLiveTerminalHandle(envHandle, client)
   } catch (err) {
     if (isOptionalTaskCreatorHandleError(err)) {
-      // Why: creator handles are best-effort lineage metadata; graph
-      // unavailability should not block task creation itself.
+      // Why: creator handles are best-effort lineage metadata; graph unavailability must not block task creation.
       return undefined
     }
     throw err
@@ -242,8 +227,7 @@ async function resolveOrchestrationPaneTerminalHandle(
     return undefined
   }
   try {
-    // Why: pane key reminting preserves the caller identity; focus-based
-    // active-terminal fallback can point at a different pane.
+    // Why: pane-key reminting preserves caller identity; focus-based active-terminal fallback can point at a different pane.
     const response = await client.call<{ terminal: { handle: string } }>('terminal.resolvePane', {
       paneKey
     })
@@ -362,17 +346,11 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
       !getOptionalStringFlag(flags, 'from') &&
       !process.env.ORCA_TERMINAL_HANDLE
     ) {
-      // Why: focus is not lifecycle authority; injected dispatches carry an
-      // explicit worker handle so an identity-less subprocess must fail closed.
+      // Why: focus isn't lifecycle authority — an identity-less subprocess must fail closed rather than guess the worker.
       throwNoActiveSenderTerminal()
     }
 
-    // Why: lifecycle senders keep ORCA_TERMINAL_HANDLE verbatim — no liveness
-    // probe (terminal.show throws runtime_unavailable in the exact mid-restart
-    // window worker_done must survive) and no pane remint (pre-payload-
-    // authority runtimes require from === the equally stale assignee_handle,
-    // and coordinator replies route to the sender row while the worker's own
-    // `check` reads its env-handle inbox).
+    // Why: lifecycle senders keep ORCA_TERMINAL_HANDLE verbatim — no liveness probe (worker_done must survive the mid-restart window) and no remint (older runtimes require from === the stale assignee_handle).
     const from = await resolveOrchestrationTerminalHandle(flags, cwd, client, 'from')
     const result = await client.call<OrchestrationSendResult>('orchestration.send', {
       from,
@@ -383,14 +361,12 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
       priority: getOptionalStringFlag(flags, 'priority'),
       threadId: getOptionalStringFlag(flags, 'thread-id'),
       payload: getOptionalStructuredMessagePayload(flags),
-      // Why: the pane key is the remint-stable sender identity the runtime
-      // verifies lifecycle ownership against; older runtimes strip it.
+      // Why: pane key is the remint-stable sender identity the runtime verifies lifecycle ownership against; older runtimes strip it.
       senderPaneKey: process.env.ORCA_PANE_KEY || undefined,
       devMode: isDevCliInvocation()
     })
     if ('message' in result.result && result.result.lifecycle?.action === 'rejected') {
-      // Why: a persisted diagnostic is not a successful lifecycle signal;
-      // the non-zero status prevents workers from treating it as completion.
+      // Why: a rejected lifecycle signal isn't completion; non-zero exit stops workers from treating it as such.
       process.exitCode = 1
     }
     printResult(result, json, (r) => {
@@ -407,9 +383,7 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
   'orchestration check': async ({ flags, client, cwd, json }) => {
     const wait = flags.has('wait')
     const peek = flags.has('peek')
-    // Why: enforce mode exclusivity client-side too — an older runtime strips
-    // the unknown `peek` param and would otherwise execute --unread --peek as
-    // a destructive mark-read.
+    // Why: enforce mode exclusivity client-side — older runtimes strip unknown peek and run --unread --peek as destructive mark-read.
     if ([flags.has('unread'), peek, flags.has('all')].filter(Boolean).length > 1) {
       throw new RuntimeClientError(
         'invalid_argument',
@@ -419,13 +393,7 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
     const timeoutMs = getOptionalPositiveIntegerValueFlag(flags, 'timeout-ms')
     const terminal = await resolveOrchestrationTerminalHandle(flags, cwd, client, 'terminal')
 
-    // Why: Claude Code's Bash tool auto-backgrounds subprocesses that produce
-    // no output for ~2 min (shorter on the non-interactive path). Emit a
-    // keepalive line to stderr every KEEPALIVE_INTERVAL_MS while the wait is
-    // active so the parent process can see the subprocess is still alive.
-    // Stderr rather than stdout so stdout stays a single final JSON payload,
-    // and JSON-shaped rather than `# …` so `2>&1 | jq` pipelines still work
-    // (jq refuses `#`-prefixed lines). See design doc §3.4.
+    // Why: Claude Code auto-backgrounds subprocesses silent ~2 min; emit JSON keepalives to stderr (stdout stays one payload). See §3.4.
     const stopKeepalive = wait ? startCheckKeepalive(timeoutMs) : null
     type CheckResult = {
       messages: MessageSummary[]
@@ -436,10 +404,7 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
     try {
       result = await client.call<CheckResult>('orchestration.check', {
         terminal,
-        // Why: --peek also sends unread:false so runtimes that predate the
-        // peek param (which their non-strict schema strips) degrade to the
-        // non-consuming all-messages mode instead of the destructive
-        // mark-read default; the read filter below restores peek semantics.
+        // Why: peek also sends unread:false so pre-peek runtimes degrade to non-consuming all mode instead of destructive mark-read.
         unread: flags.has('unread') ? true : peek ? false : undefined,
         peek: peek ? true : undefined,
         all: flags.has('all') ? true : undefined,
@@ -455,19 +420,14 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
       const rawRowCount = result.result.messages.length
       const unreadOnly = result.result.messages.filter((m) => m.read !== 1)
       const removedReadRows = unreadOnly.length !== rawRowCount
-      // Why: read rows in a peek response are the pre-peek-runtime signature
-      // (its schema stripped `peek` and it ran the all mode). Such a runtime
-      // returned instead of blocking, so honoring --wait is impossible —
-      // failing beats silently returning empty before the deadline.
+      // Why: read rows mean a pre-peek runtime ran the all mode and returned instead of blocking; can't honor --wait, so fail loudly.
       if (wait && removedReadRows && unreadOnly.length === 0) {
         throw new RuntimeClientError(
           'peek_wait_unsupported',
           'The connected runtime does not support --peek with --wait; upgrade the runtime or use --wait without --peek.'
         )
       }
-      // Why: pre-peek runtimes cap the all mode at the newest 100 rows, so a
-      // full page means older unread messages may have been cut off. Warn on
-      // stderr so stdout stays a single JSON payload.
+      // Why: pre-peek runtimes cap the all mode at 100 rows; a full page may hide older unread — warn on stderr.
       if (removedReadRows && rawRowCount >= 100) {
         console.error(
           'Warning: this runtime returned only its newest 100 messages for --peek; older unread messages may be missing. Upgrade the runtime for exact peek results.'
@@ -477,8 +437,7 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
         ...result,
         result: {
           ...result.result,
-          // Why: a pre-peek runtime builds `formatted` from all rows; drop it
-          // when the read filter removed any so output matches the peek set.
+          // Why: a pre-peek runtime builds `formatted` from all rows; drop it so output matches the filtered peek set.
           ...(removedReadRows ? { formatted: undefined } : {}),
           messages: unreadOnly,
           count: unreadOnly.length
@@ -521,8 +480,7 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
       if (r.count === 0) {
         return 'No messages.'
       }
-      // Why: default output omits body/payload for at-a-glance sweeps; --full
-      // prints them verbatim so callers can audit without parsing --json.
+      // Why: default output omits body/payload for at-a-glance sweeps; --full prints them for auditing.
       return r.messages
         .map((m) => {
           const head = `${m.id} ${m.from_handle} -> ${m.to_handle ?? '?'}: "${m.subject}"`
@@ -577,9 +535,7 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
       ready: flags.has('ready') ? true : undefined,
       brief: brief ? true : undefined
     })
-    // Why: current runtimes abbreviate server-side (rows carry
-    // spec_truncated) so full specs never cross the wire; older runtimes
-    // strip the brief param and need the client-side fallback.
+    // Why: only older runtimes (no spec_truncated) skip server-side abbreviation and need this client-side fallback.
     const needsClientAbbreviation =
       brief && result.result.tasks.some((task) => task.spec_truncated === undefined)
     const output = needsClientAbbreviation
@@ -671,18 +627,10 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
         timeoutMs: parsedTimeoutMs,
         from
       },
-      // Why: the runtime's `waitForMessage` can block up to `timeoutMs`, but
-      // the RPC transport has its own 60s default timeout that would fire
-      // first. Extend the per-call timeout by a small grace window so the
-      // RPC doesn't abort before the runtime's internal timeout resolves.
+      // Why: extend past timeoutMs so the RPC transport's 60s default doesn't abort before the runtime's own timeout resolves.
       { timeoutMs: timeoutMs + 5_000 }
     )
-    // Why: deliberate bypass of `printResult`. `--json` on `ask` emits a
-    // single-line bare JSON object (no RPC envelope, no multi-line pretty-
-    // print) so workers can pipe `orca orchestration ask … --json | jq -r
-    // .answer` without reaching into a `result` envelope. This diverges from
-    // every other orchestration verb; called out in the commit message and
-    // guarded by a unit test in orchestration.test.ts.
+    // Why: bypass printResult so --json emits a bare JSON object (no envelope) pipeable via `jq -r .answer`, unlike other verbs.
     if (json) {
       console.log(JSON.stringify(result.result))
     } else if (result.result.answer !== null) {
@@ -698,8 +646,7 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
 
   'orchestration dispatch-show': async ({ flags, client, cwd, json }) => {
     const showPreamble = flags.has('preamble') ? true : undefined
-    // Why: resolve --from when previewing so the preamble embeds a real
-    // coordinator handle, matching what an actual dispatch would produce.
+    // Why: resolve --from so the previewed preamble embeds a real coordinator handle like an actual dispatch.
     const from = showPreamble
       ? await resolveCoordinatorTerminalHandle(flags, cwd, client)
       : undefined
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 2e0d86ab3b2..b4bb2be8b3b 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -615,8 +615,7 @@ export type DetectedBrowserInfo = {
 export type PreflightStatus = {
   git: { installed: boolean }
   gh: { installed: boolean; authenticated: boolean }
-  /** Optional — older preload payloads predating GitLab support don't
-   *  include it. Consumers gate on `glab?.installed` / `authenticated`. */
+  /** Optional — older preload payloads predating GitLab support omit it; consumers gate on `glab?.installed`. */
   glab?: { installed: boolean; authenticated: boolean }
   bitbucket?: { configured: boolean; authenticated: boolean; account: string | null }
   azureDevOps?: {
@@ -639,14 +638,10 @@ export type RefreshAgentsResult = {
   agents: string[]
   addedPathSegments: string[]
   shellHydrationOk: boolean
-  /** Why: drives the agent_picks `on_path:false` triage in dashboard 1562016
-   *  (insight A). `'shell_hydrate'` = detection saw the user's full shell PATH;
-   *  `'sync_seed_only'` = hydration failed and detection ran against the
-   *  seed list from `patchPackagedProcessPath`. */
+  /** Drives agent_picks `on_path:false` triage (dashboard 1562016). `'shell_hydrate'` = detection saw the user's
+   *  full shell PATH; `'sync_seed_only'` = hydration failed and detection ran against the `patchPackagedProcessPath` seed list. */
   pathSource: PathSource
-  /** Why: classified hydration outcome. `'none'` on success; one of the failure
-   *  modes when `shellHydrationOk` is false. Typed off the shared alias so
-   *  schema/main/preload/renderer stay in lockstep. */
+  /** Classified hydration outcome: `'none'` on success, else a failure mode when `shellHydrationOk` is false. */
   pathFailureReason: ShellHydrationFailureReason
 }
 
@@ -670,12 +665,7 @@ export type PreflightApi = {
   }>
 }
 
-// Why: renderer-facing mirror of the daemon's `SessionInfo` + protocolVersion
-// annotation (src/main/daemon/types.ts `DaemonSessionInfo`). Kept here instead
-// of imported from main because the preload boundary must not depend on
-// main-only protocol types — those are subprocess-facing. Keep the two shapes
-// in sync when adding fields on either side; the Manage Sessions panel reads
-// these directly.
+// Mirror of daemon's `DaemonSessionInfo` (src/main/daemon/types.ts); not imported — preload can't depend on main-only protocol types.
 export type PtyManagementSession = {
   sessionId: string
   state: 'created' | 'spawning' | 'running' | 'exiting' | 'exited'
@@ -690,8 +680,7 @@ export type PtyManagementSession = {
 }
 
 export type PtyManagementApi = {
-  // `degraded` is true when the daemon is alive but cannot spawn fresh PTYs, so
-  // new terminals run on the local provider without daemon persistence.
+  // `degraded`: daemon is alive but can't spawn fresh PTYs, so new terminals run locally without daemon persistence.
   listSessions: () => Promise<{ sessions: PtyManagementSession[]; degraded: boolean }>
   killAll: () => Promise<{
     killedCount: number
@@ -715,11 +704,7 @@ export type StatsApi = {
   getSummary: () => Promise<StatsSummary>
 }
 
-// Diagnostics — error-tracking-lane payload shapes that cross the IPC
-// boundary. Mirror the runtime types in
-// `src/main/observability/{index,bundle}.ts`. Kept here, not imported,
-// because the preload api-types file is the source of truth for the
-// renderer's view of the IPC surface.
+// Diagnostics IPC payloads; mirror the runtime types in `src/main/observability/{index,bundle}.ts`.
 export type DiagnosticsStatusPayload = {
   readonly localFileEnabled: boolean
   readonly bundleEnabled: boolean
@@ -843,8 +828,7 @@ export type AiVaultApi = {
   onWindowFocused: (callback: () => void) => () => void
 }
 
-// notFound marks a miss caused by the transcript not existing on disk yet
-// (retry-worthy), as opposed to a real read/parse error (#8401).
+// notFound marks a not-yet-on-disk miss (retry-worthy) vs a real read/parse error (#8401).
 export type NativeChatReadSessionResult =
   | {
       messages: NativeChatMessage[]
@@ -894,10 +878,8 @@ export type NativeChatSubscribeArgs = {
 }
 
 export type NativeChatApi = {
-  /** Read the on-disk transcript for an agent + session id, windowed to the most
-   *  recent `limit` turns (defaults to the desktop window). The renderer raises
-   *  `limit` to page in older history as it scrolls to the top. `transcriptPath`
-   *  is the hook-reported authoritative file path, preferred over the id glob. */
+  /** Read the on-disk transcript for an agent + session id, windowed to the most recent `limit`
+   *  turns. `transcriptPath` is the hook-reported authoritative path, preferred over the id glob. */
   readSession: (
     agent: AgentType,
     sessionId: string,
@@ -918,9 +900,7 @@ export type AppApi = {
   /** Returns a URL base for feature-wall assets. In dev this is Vite /@fs;
    *  in packaged builds this is file:// resources. Renderer appends filenames. */
   getFeatureWallAssetBaseUrl: () => Promise<string>
-  /** Relaunches the app via Electron's app.relaunch() + app.exit(0). Used
-   *  by settings panes that need a full restart to apply changes (e.g. the
-   *  terminal-window blur setting in TerminalWindowSection). */
+  /** Relaunches the app (app.relaunch() + app.exit(0)) for settings that need a full restart to apply. */
   relaunch: () => Promise<void>
   /** Restarts Orca through the normal quit pipeline so daemon-backed terminal
    *  sessions survive and can reattach after the new process starts. */
@@ -939,12 +919,9 @@ export type AppApi = {
   awaitFirstWindowStartupServices: () => Promise<void>
   /** Emits a startup benchmark marker when ORCA_STARTUP_DIAGNOSTICS is enabled. */
   startupDiagnostic: (event: string, details?: Record<string, unknown>) => Promise<void>
-  /** Returns the macOS active input mode, or layout ID when no IME mode is
-   *  selected (e.g. `com.apple.keylayout.PolishPro`). Used by the
-   *  keyboard-layout probe to distinguish CJK IMEs and layouts whose base
-   *  layer matches US QWERTY but whose Option layer composes characters
-   *  (issue #1205).
-   *  Returns null on non-Darwin platforms or when the defaults read fails. */
+  /** macOS active input mode, or layout ID when no IME is selected (e.g. `com.apple.keylayout.PolishPro`).
+   *  Distinguishes CJK IMEs and Option-layer-composing layouts that look like US QWERTY (issue #1205).
+   *  Returns null on non-Darwin or when the defaults read fails. */
   getKeyboardInputSourceId: () => Promise<string | null>
   /** Updates the macOS Dock unread badge. No-op on Windows/Linux. */
   setUnreadDockBadgeCount: (count: number) => Promise<void>
@@ -1019,8 +996,7 @@ export type PreloadApi = {
       kind?: 'git' | 'folder'
     }) => Promise<{ repo: Repo } | { error: string }>
     remove: (args: { repoId: string }) => Promise<void>
-    // Forget a project on one execution host only, leaving the same repo id on
-    // other hosts (local or a re-added SSH target) intact.
+    // Forget a project on one execution host only, leaving the same repo id on other hosts intact.
     removeForHost: (args: { repoId: string; hostId: string }) => Promise<void>
     reorder: (args: { orderedIds: string[] }) => Promise<{ status: 'applied' | 'rejected' }>
     reorderForHost: (args: {
@@ -1202,10 +1178,8 @@ export type PreloadApi = {
     listDetected: (args: { repoId: string }) => Promise<DetectedWorktreeListResult>
     listAll: () => Promise<Worktree[]>
     create: (args: CreateWorktreeArgs) => Promise<CreateWorktreeResult>
-    /** Two-phase progress for a background `create`, correlated by
-     *  `creationId`. Renderer routes each event to its pending creation's
-     *  status surface; the remote/runtime create path emits nothing, so the
-     *  surface falls back to an indeterminate spinner. */
+    /** Two-phase progress for a background `create`, correlated by `creationId`. The remote/runtime
+     *  create path emits nothing, so the surface falls back to an indeterminate spinner. */
     onCreateProgress: (
       callback: (data: { creationId?: string; phase: 'fetching' | 'creating' }) => void
     ) => () => void
@@ -1236,8 +1210,7 @@ export type PreloadApi = {
       force?: boolean
       skipArchive?: boolean
     }) => Promise<RemoveWorktreeResult>
-    // Forget a workspace from Orca only — no remote Git/filesystem work. Used
-    // for workspaces pinned to a removed/disconnected SSH host.
+    // Forget a workspace from Orca only (no remote Git/FS work) — for workspaces pinned to a removed/disconnected SSH host.
     forgetLocal: (args: {
       worktreeId: string
       hostId?: ExecutionHostId
@@ -1310,24 +1283,15 @@ export type PreloadApi = {
       worktreeId?: string
       sessionId?: string
       // Why: lets a single tab open in a different shell than the user's default.
-      // Preserved from the deleted index.d.ts PtyApi duplicate during the
-      // single-source-of-truth collapse (see docs/preload-typecheck-hole.md §1).
       shellOverride?: string
       projectRuntime?: ProjectExecutionRuntimeResolution
       terminalColorQueryReplies?: { foreground?: string; background?: string }
-      // Why: hidden-at-spawn declaration — main marks the PTY hidden before
-      // its first byte so the delivery gate + model responder own spawn-time
-      // queries (terminal-query-authority.md §races).
+      // Why: mark the PTY hidden before its first byte so the delivery gate owns spawn-time queries (terminal-query-authority.md §races).
       initiallyHidden?: boolean
-      // Why: closes the SIGKILL race documented in INVESTIGATION.md — main
-      // sync-flushes the (worktreeId, tabId, leafId → ptyId) binding before
-      // pty:spawn returns. Only the renderer's daemon-host path threads these.
+      // Why: main sync-flushes the (worktreeId,tabId,leafId→ptyId) binding before pty:spawn returns to close a SIGKILL race (INVESTIGATION.md).
       tabId?: string
       leafId?: string
-      // Why: telemetry-plan.md§Agent launch semantics — main emits
-      // `agent_started` only after the PTY/session is created successfully,
-      // so the renderer threads the launch metadata through this field and
-      // the IPC handler fires the event from the spawn-success branch.
+      // Why: main fires `agent_started` only on spawn success, so launch metadata rides this field (telemetry-plan.md §Agent launch semantics).
       telemetry?: { agent_kind: AgentKind; launch_source: LaunchSource; request_kind: RequestKind }
     }) => Promise<{
       id: string
@@ -1701,11 +1665,7 @@ export type PreloadApi = {
       args: GitHubRepoSelectorArgs & {
         number: number
         body: string
-        /** Why: GitHub stores PR conversation comments under `/issues/N/comments`
-         *  too, so the IPC and `gh` call paths are identical. The renderer cache
-         *  key is keyed by the drawer's `type`, so callers pass it through to
-         *  scope the cross-window invalidation broadcast correctly and avoid
-         *  evicting an unrelated PR/issue that happens to share the number. */
+        /** Why: scopes the cross-window cache invalidation so a PR and issue sharing the same number don't evict each other. */
         type?: 'issue' | 'pr'
         prRepo?: GitHubOwnerRepo | null
       }
@@ -1737,11 +1697,7 @@ export type PreloadApi = {
       repoId?: string
       sourceContext?: TaskSourceContext | null
     }) => Promise<GitHubAssignableUser[]>
-    /**
-     * Subscribe to local-mutation broadcasts. Used by the work-item-drawer
-     * cache to invalidate entries across windows after a successful mutation.
-     * Returns an unsubscribe function.
-     */
+    /** Subscribe to local-mutation broadcasts so the work-item-drawer cache can invalidate across windows. Returns an unsubscribe. */
     onWorkItemMutated: (
       callback: (payload: {
         repoPath: string
@@ -1758,13 +1714,7 @@ export type PreloadApi = {
      * `force: true` to bust after a known-expensive op.
      */
     rateLimit: (args?: { force?: boolean }) => Promise<GetRateLimitResult>
-    /**
-     * Probe `gh auth status` and the Electron process env to explain
-     * why ProjectV2 calls are failing with scope_missing. Surfaces the
-     * common gotcha where `GITHUB_TOKEN` is exported in the user's
-     * shell and silently shadows the keyring credential — in that case
-     * `gh auth refresh` is a no-op and the UI must say so.
-     */
+    /** Explains scope_missing ProjectV2 failures — notably a shell `GITHUB_TOKEN` shadowing the keyring credential, where `gh auth refresh` is a no-op. */
     diagnoseAuth: () => Promise<GhAuthDiagnostic>
     // ── ProjectV2 (GitHub Projects) ─────────────────────────────────
     listAccessibleProjects: () => Promise<ListAccessibleProjectsResult>
@@ -1806,9 +1756,7 @@ export type PreloadApi = {
     create: (args: CreateHostedReviewArgs) => Promise<CreateHostedReviewResult>
   }
   // ── GitLab — parallel to gh, MR/issue surface only in v1 ────────
-  // Shapes mirror gh.* one-to-one where the data matches; diverge
-  // where GitLab's API differs (MR state values, project path with
-  // host, paginated envelope from `glab api -i`).
+  // Shapes mirror gh.* except where GitLab's API differs (MR states, host-qualified project path, `glab api -i` paging).
   gl: {
     viewer: () => Promise<GitLabViewer | null>
     diagnoseAuth: () => Promise<GitLabAuthDiagnostic>
@@ -2131,19 +2079,14 @@ export type PreloadApi = {
     showAgentValueMoment: () => Promise<void>
     onboardingCompleted: () => Promise<void>
   }
-  /** Fire-and-forget track. Loose typing at the IPC boundary on purpose —
-   *  the main-side validator is the single enforcement point. Renderer call
-   *  sites should import `track<N>()` from `src/renderer/src/lib/telemetry.ts`
-   *  for the `EventMap`-based type safety, not reach for this directly. */
+  /** Fire-and-forget track. Loose IPC typing on purpose — the main-side validator enforces;
+   *  renderer sites should import `track<N>()` from lib/telemetry.ts, not reach here. */
   telemetryTrack: (name: string, props: Record<string, unknown>) => Promise<void>
   /** Flip the persisted opt-in preference. Subject to a per-session
    *  consent-mutation rate limit on the main side (≤5/session). */
   telemetrySetOptIn: (optedIn: boolean) => Promise<void>
-  /** Diagnostic file controls. Surface for telemetry-error-tracking.md
-   *  §User controls. The renderer triggers flows; main does the filesystem /
-   *  network work and returns serializable metadata. Main retains collected
-   *  upload payloads so the renderer can confirm without reading or
-   *  substituting arbitrary bytes. */
+  /** Diagnostic file controls (telemetry-error-tracking.md §User controls). Main does the FS/network
+   *  work and retains upload payloads so the renderer can't read or substitute arbitrary bytes. */
   diagnostics: {
     getStatus: () => Promise<DiagnosticsStatusPayload>
     collectBundle: (lookbackMinutes?: number) => Promise<DiagnosticsBundlePayload>
@@ -2152,33 +2095,21 @@ export type PreloadApi = {
     uploadBundle: (bundleSubmissionId: string) => Promise<DiagnosticsUploadPayload>
     deleteBundle: (ticketId: string) => Promise<void>
   }
-  /** Read-only view of effective consent state, including the reason if
-   *  disabled (env var / user opt-out / CI / pending banner). Used by the
-   *  Privacy pane to render the correct "blocked by X" helper text — env
-   *  vars are main-side state the renderer cannot read directly. */
+  /** Read-only effective consent state (+ reason if disabled) — env vars are main-side state the renderer can't read directly. */
   telemetryGetConsentState: () => Promise<TelemetryConsentState>
-  /** Banner ✕ — persist `optedIn = true` silently, emit nothing. Deliberately
-   *  a separate channel from `telemetrySetOptIn` because main's `via`
-   *  derivation on that channel would tag this path as `first_launch_banner`
-   *  and fire `telemetry_opted_in`, which the ✕-as-silent-acknowledge
-   *  semantics forbid (the user did not explicitly opt in, they declined to
-   *  intervene). Subject to the same per-session consent-mutation rate
-   *  limit as `telemetrySetOptIn`. */
+  /** Banner ✕ — persist `optedIn = true` silently. Separate channel from `telemetrySetOptIn`,
+   *  whose `via` derivation would wrongly fire `telemetry_opted_in`. Same per-session rate limit. */
   telemetryAcknowledgeBanner: () => Promise<void>
   settings: {
     get: () => Promise<GlobalSettings>
-    /** Synchronous persisted-settings read for startup decisions that cannot
-     *  wait for async hydration (terminal side-effect authority). Blocking
-     *  IPC — call sparingly. */
+    /** Synchronous persisted-settings read for startup decisions that can't wait for async hydration. Blocking IPC — call sparingly. */
     getSync: () => GlobalSettings | null
     set: (args: Partial<GlobalSettings>) => Promise<GlobalSettings>
     updatePRBotAuthorOverride: (args: { author: string; isBot: boolean }) => Promise<GlobalSettings>
     listFonts: () => Promise<string[]>
     previewGhosttyImport: () => Promise<GhosttyImportPreview>
     previewWarpThemeImport: (source: WarpThemeImportSource) => Promise<WarpThemeImportPreview>
-    /** Subscribe to out-of-band settings updates (e.g. the View > Appearance
-     *  menu toggles) so the renderer can stay in sync with main's persisted
-     *  state without round-tripping through settings:get. */
+    /** Subscribe to out-of-band settings updates (e.g. View > Appearance toggles) to stay in sync with main. */
     onChanged: (callback: (updates: Partial<GlobalSettings>) => void) => () => void
   }
   localhostWorktreeLabels: {
@@ -2266,9 +2197,7 @@ export type PreloadApi = {
   }
   onboarding: {
     get: () => Promise<OnboardingState>
-    // Why: main-process `updateOnboarding` merges checklist field-by-field, so
-    // callers can pass a partial checklist (e.g. just `{ addedRepo: true }`)
-    // without re-supplying every flag.
+    // Why: main merges the checklist field-by-field, so a partial checklist is fine.
     update: (
       updates: Partial<Omit<OnboardingState, 'checklist'>> & {
         checklist?: Partial<OnboardingState['checklist']>
@@ -2418,8 +2347,7 @@ export type PreloadApi = {
     }) => Promise<void>
   }
   session: {
-    // hostId is optional and defaults to the 'local' partition on the main
-    // side, so existing callers that omit it behave exactly as before.
+    // hostId defaults to the 'local' partition on main, so omitting it stays backward-compatible.
     get: (hostId?: ExecutionHostId) => Promise<WorkspaceSessionState>
     set: (args: WorkspaceSessionState, hostId?: ExecutionHostId) => Promise<void>
     patch: (args: WorkspaceSessionPatch, hostId?: ExecutionHostId) => Promise<void>
@@ -3124,8 +3052,7 @@ export type PreloadApi = {
   }
   ssh: {
     listTargets: () => Promise<SshTarget[]>
-    // Removed-target id → last known label, for showing a friendly host name on
-    // workspaces still pinned to a target that no longer exists.
+    // Removed-target id → last known label, for a friendly host name on workspaces still pinned to a removed target.
     listRemovedTargetLabels: () => Promise<Record<string, string>>
     addTarget: (args: { target: Omit<SshTarget, 'id'> }) => Promise<SshTargetAddResult>
     updateTarget: (args: {
@@ -3224,19 +3151,15 @@ export type PreloadApi = {
     /** Return the current main-process hook cache after renderer hydration. */
     getSnapshot: () => Promise<AgentStatusIpcPayload[]>
     inferInterrupt: (request: AgentInterruptInferenceRequest) => Promise<boolean>
-    /** Guarded clear for an answered AskUserQuestion wait — the CLI emits no
-     *  hook at answer time, so the renderer reports the submit keystroke. */
+    /** Guarded clear for an answered AskUserQuestion wait — the CLI emits no hook at answer time, so the renderer reports the submit keystroke. */
     inferQuestionAnswered: (request: AgentQuestionAnsweredInferenceRequest) => Promise<boolean>
-    /** Listen for PTYs that still use a legacy numeric pane key but have
-     *  registry-backed UUID pane proof. */
+    /** Listen for PTYs on a legacy numeric pane key that have registry-backed UUID pane proof. */
     onMigrationUnsupported: (callback: (entry: MigrationUnsupportedPtyEntry) => void) => () => void
     onMigrationUnsupportedClear: (callback: (data: { ptyId: string }) => void) => () => void
     getMigrationUnsupportedSnapshot: () => Promise<MigrationUnsupportedPtyEntry[]>
-    /** Drop a paneKey from the main-process hook cache and the on-disk
-     *  last-status file. Fire-and-forget. */
+    /** Drop a paneKey from the main-process hook cache and on-disk last-status file. Fire-and-forget. */
     drop: (paneKey: string) => void
-    /** Drop every cached hook status under one terminal tab prefix.
-     *  Fire-and-forget. */
+    /** Drop every cached hook status under one terminal tab prefix. Fire-and-forget. */
     dropByTabPrefix: (tabId: string) => void
     /** Permanently retire one pane's hook authority while siblings stay live. */
     retirePaneAuthority: (paneKey: string) => void
@@ -3263,8 +3186,7 @@ export type PreloadApi = {
           pairingUrl: string
           endpoint: string
           deviceId: string
-          /** Mode the QR actually encodes; 'local-only' when an automatic
-           *  request degraded because Relay could not be attached. */
+          /** Mode the QR actually encodes; 'local-only' when Relay could not be attached. */
           connectionMode: MobilePairingConnectionMode
         }
     >
diff --git a/src/preload/index.ts b/src/preload/index.ts
index da24ff26aa7..eed959cd2cb 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: the preload bridge is the audited contract between
-renderer and Electron. Keeping the IPC surface co-located in one file makes security
-review and type drift checks easier than scattering these bindings across modules. */
+/* eslint-disable max-lines -- Why: preload is the audited renderer/Electron IPC contract; co-locating the surface eases security and type-drift review. */
 import { contextBridge, ipcRenderer, webFrame, webUtils } from 'electron'
 import { electronAPI } from '@electron-toolkit/preload'
 import { preloadE2EConfig } from './e2e-config'
@@ -269,8 +267,7 @@ const onNativeFileDrop = (_event: Electron.IpcRendererEvent, data: NativeFileDro
 function subscribeNativeFileDrop(callback: NativeFileDropCallback): () => void {
   nativeFileDropCallbacks.push(callback)
   if (!nativeFileDropListenerRegistered) {
-    // Why: terminal panes subscribe per visible split group, so the IPC layer
-    // must keep one real listener and fan out locally to avoid listener warnings.
+    // Why: keep one real IPC listener and fan out locally — panes subscribe per split group, which would otherwise trip listener warnings.
     ipcRenderer.on('terminal:file-drop', onNativeFileDrop)
     nativeFileDropListenerRegistered = true
   }
@@ -286,21 +283,14 @@ function subscribeNativeFileDrop(callback: NativeFileDropCallback): () => void {
   }
 }
 
-// Why: one shared HTMLAudioElement per sound file, restarted from t=0 on each
-// play, with an in-flight guard that drops new plays while the sound is still
-// ringing. This mirrors VS Code's AccessibilitySignalService and GNOME's
-// libcanberra: a burst of triggers self-dedupes by the sound's own duration
-// (no magic time constant), while distinct sounds are still allowed to overlap.
-// We also cache the decoded blob URL by path so we don't re-read 10MB from
-// disk and re-transfer it over IPC on every notification.
+// Why: cache one shared Audio + blob URL per sound path so we don't re-read 10MB from disk and re-transfer over IPC on every notification.
 let cachedNotificationSound: {
   path: string
   blobUrl: string
   audio: HTMLAudioElement
 } | null = null
 let isNotificationSoundPlaying = false
-// Why: audio.play() can reject before ended/error fires; keep a cleanup hook
-// so failed or replaced plays do not accumulate listeners on the cached Audio.
+// Why: audio.play() can reject before ended/error fires — cleanup hook prevents leaked listeners on the cached Audio.
 let cleanupNotificationSoundPlayback: (() => void) | null = null
 
 function clearNotificationSoundPlaybackState(): void {
@@ -320,14 +310,11 @@ function disposeCachedNotificationSound(): void {
 }
 
 /**
- * Walk the composed event path to classify which UI surface the native OS drop
- * landed on, and — for file-explorer drops — extract the nearest destination
- * directory from `data-native-file-drop-dir`.
+ * Classify which UI surface the native OS drop landed on, and for file-explorer drops
+ * extract the destination directory from `data-native-file-drop-dir`.
  *
- * Why: the preload layer consumes native OS `drop` events before React can read
- * filesystem paths. If preload does not capture the destination directory at
- * drop time, the renderer can no longer tell whether the user meant "root" or
- * "inside this folder".
+ * Why: preload consumes the native `drop` before React can read paths, so it must capture
+ * the destination dir now — otherwise the renderer can't tell "root" from "inside this folder".
  */
 function resolveNativeFileDrop(event: DragEvent): NativeDropResolution | null {
   const pathEntries: NativeFileDropPathEntry[] = []
@@ -344,16 +331,11 @@ function resolveNativeFileDrop(event: DragEvent): NativeDropResolution | null {
   return resolveNativeFileDropPath(pathEntries)
 }
 
-// ---------------------------------------------------------------------------
-// File drag-and-drop: handled here in the preload because webUtils (which
-// resolves File objects to filesystem paths) is only available in Electron's
-// preload/main worlds, not the renderer's isolated main world.
-// ---------------------------------------------------------------------------
+// File drag-and-drop lives in preload because webUtils (File→path) is only available in the preload/main world, not the renderer's isolated world.
 document.addEventListener(
   'dragover',
   (e) => {
-    // Let in-app drags (e.g. file explorer drag-to-move) through to React handlers
-    // so they can set their own dropEffect. Only override for native OS file drops.
+    // Let in-app drags through to React handlers (their own dropEffect); only override for native OS file drops.
     if (e.dataTransfer && !hasNativeFileDragTypes(e.dataTransfer.types)) {
       return
     }
@@ -381,8 +363,7 @@ document.addEventListener(
     }
     const resolution = resolveNativeFileDrop(e)
 
-    // Why: resolving native File objects to paths is synchronous in preload.
-    // Reject oversized gestures by count before touching every File object.
+    // Why: reject oversized gestures by count before resolving every File object (path resolution is synchronous here).
     if (files.length > NATIVE_FILE_DROP_MAX_PATHS) {
       ipcRenderer.send(
         'terminal:file-dropped-from-preload',
@@ -409,9 +390,7 @@ document.addEventListener(
       return
     }
 
-    // Why: when the explorer marker was present but no destination directory
-    // could be resolved, the gesture is rejected entirely — no fallback to
-    // editor, per the fail-closed requirement in design §7.1.
+    // Why: explorer marker present but no destination dir resolved → reject entirely, no editor fallback (fail-closed, design §7.1).
     if (resolution?.target === 'rejected') {
       return
     }
@@ -420,9 +399,7 @@ document.addEventListener(
     if (!payload) {
       return
     }
-    // Why: preload must emit exactly one native-drop event per drop gesture.
-    // The shared planner also rejects large path payloads without including
-    // path contents in the failure event.
+    // Why: emit exactly one native-drop event per gesture (the shared planner rejects oversized payloads without leaking path contents).
     ipcRenderer.send('terminal:file-dropped-from-preload', payload)
   },
   true
@@ -466,10 +443,7 @@ const api = {
       startupDiagnosticsEnabled
         ? ipcRenderer.invoke('app:startupDiagnostic', event, details)
         : Promise.resolve(),
-    // Why: on macOS this returns the active input mode, or the layout ID when
-    // no IME mode is selected, so renderer keyboard workarounds can distinguish
-    // CJK IMEs and compose layouts from plain US QWERTY (see issue #1205).
-    // Returns null on non-Darwin or when the defaults read fails.
+    // Why: macOS input mode (or layout ID) so keyboard workarounds can tell CJK/compose layouts from US QWERTY (issue #1205); null on non-Darwin or read failure.
     getKeyboardInputSourceId: (): Promise<string | null> =>
       ipcRenderer.invoke('app:getKeyboardInputSourceId'),
     setUnreadDockBadgeCount: (count: number): Promise<void> =>
@@ -823,21 +797,12 @@ const api = {
       shellOverride?: string
       projectRuntime?: ProjectExecutionRuntimeResolution
       terminalColorQueryReplies?: { foreground?: string; background?: string }
-      // Why: hidden-at-spawn declaration — main marks the PTY hidden before
-      // its first byte so the delivery gate + model responder own spawn-time
-      // queries (terminal-query-authority.md §races).
+      // Why: marks the PTY hidden before its first byte so the delivery gate + model responder own spawn-time queries (terminal-query-authority.md §races).
       initiallyHidden?: boolean
-      // Why: closes the SIGKILL race documented in INVESTIGATION.md by
-      // letting main patch + sync-flush the (worktreeId, tabId, leafId →
-      // ptyId) binding before pty:spawn returns. Only the renderer's
-      // user-typing-Ctrl+T daemon-host path threads these.
+      // Why: closes the SIGKILL race (INVESTIGATION.md) — main sync-flushes the (worktreeId, tabId, leafId → ptyId) binding before pty:spawn returns.
       tabId?: string
       leafId?: string
-      // Why: telemetry-plan.md§Agent launch semantics — main fires
-      // `agent_started` only after the spawn succeeds. The renderer is the
-      // source of truth for the launch metadata; main is the source of
-      // truth for whether the launch happened. Loose typing here on
-      // purpose: validation lives at the main-side schema validator.
+      // Why: loose typing on purpose — renderer owns launch metadata, main owns whether the launch happened and validates (telemetry-plan.md §Agent launch semantics).
       telemetry?: { agent_kind: AgentKind; launch_source: LaunchSource; request_kind: RequestKind }
     }): Promise<{
       id: string
@@ -866,11 +831,7 @@ const api = {
       ipcRenderer.send('pty:claimViewport', { id, cols, rows })
     },
 
-    /** Why: measurement-only sibling of resize. Fires when a desktop pane
-     * container measures real geometry (e.g. previously hidden tab becomes
-     * visible) so the runtime's restore-target baseline can stay fresh
-     * even while a mobile-fit override blocks pty:resize. Never resizes
-     * the PTY. See docs/mobile-fit-hold.md. */
+    /** Why: measurement-only sibling of resize — keeps the runtime's restore-target baseline fresh while a mobile-fit override blocks pty:resize. Never resizes the PTY. See docs/mobile-fit-hold.md. */
     reportGeometry: (id: string, cols: number, rows: number): void => {
       ipcRenderer.send('pty:reportGeometry', { id, cols, rows })
     },
@@ -879,9 +840,7 @@ const api = {
       ipcRenderer.send('pty:signal', { id, signal })
     },
 
-    /** Why: Cmd/Ctrl+K clears the renderer xterm, but the PTY host (ConPTY,
-     * daemon emulator, SSH host buffer) keeps its own screen state and would
-     * repaint the next prompt at the stale cursor row. */
+    /** Why: Cmd/Ctrl+K clears the renderer xterm, but the PTY host keeps its own screen state and would repaint the next prompt at the stale cursor row. */
     clearBuffer: (id: string): void => {
       ipcRenderer.send('pty:clearBuffer', { id })
     },
@@ -889,8 +848,7 @@ const api = {
     ackColdRestore: (id: string): void => {
       ipcRenderer.send('pty:ackColdRestore', { id })
     },
-    /** charCount is the legacy per-chunk delta; processedChars is the
-     *  cumulative per-pty total (self-healing under lost ACK messages). */
+    /** charCount is the legacy per-chunk delta; processedChars is the cumulative per-pty total (self-heals under lost ACKs). */
     ackData: (id: string, charCount: number, processedChars?: number): void => {
       ipcRenderer.send('pty:ackData', {
         id,
@@ -898,8 +856,7 @@ const api = {
         ...(typeof processedChars === 'number' ? { processedChars } : {})
       })
     },
-    /** Main asks for the renderer's cumulative processed totals when terminal
-     *  delivery looks stuck on lost ACKs. */
+    /** Main requests the renderer's cumulative processed totals when delivery looks stuck on lost ACKs. */
     onDeliveryResyncRequest: (callback: (payload: { requestId: number }) => void): (() => void) => {
       const listener = (_event: Electron.IpcRendererEvent, payload: { requestId: number }) =>
         callback(payload)
@@ -912,15 +869,12 @@ const api = {
     }): void => {
       ipcRenderer.send('pty:deliveryResyncResponse', payload)
     },
-    /** Renderer-initiated delivery health/heal lane. Rides invoke because the
-     *  field wedge (v1.4.121-rc.0 snapshot) kills main→renderer push events
-     *  while invoke stays alive — push-initiated recovery can't reach it. */
+    /** Renderer-initiated delivery health/heal lane — rides invoke because the field wedge (v1.4.121-rc.0) kills main→renderer push while invoke stays alive. */
     reportRendererDeliveryState: (
       report: PtyRendererDeliveryStateReport
     ): Promise<PtyRendererDeliveryHealthReply> =>
       ipcRenderer.invoke('pty:reportRendererDeliveryState', report),
-    /** Sync count of live pty:data listeners on this preload's emitter — the
-     *  watchdog's "listener detached" vs "channel dead" discriminator. */
+    /** Live pty:data listener count — the watchdog's "listener detached" vs "channel dead" discriminator. */
     getPtyDataListenerCount: (): number => ipcRenderer.listenerCount('pty:data'),
     rendererDispatcherReady: (): void => {
       ipcRenderer.send('pty:rendererDispatcherReady')
@@ -931,21 +885,15 @@ const api = {
     setRendererPtyVisible: (id: string, visible: boolean): void => {
       ipcRenderer.send('pty:setRendererPtyVisible', { id, visible })
     },
-    /** Hidden-delivery gate (Phase 4): hidden=true lets main DROP renderer
-     *  byte delivery after model ingestion; reveal restores from the model
-     *  snapshot. Fire-and-forget like setActiveRendererPty. */
+    /** Hidden-delivery gate: hidden=true lets main DROP renderer byte delivery after model ingestion; reveal restores from the model snapshot. Fire-and-forget. */
     setHiddenRendererPty: (id: string, hidden: boolean): void => {
       ipcRenderer.send('pty:setHiddenRendererPty', { id, hidden })
     },
-    /** Delivery-interest signal: any renderer party that needs raw bytes
-     *  (dispatcher sidecars, eager pre-mount buffers) suppresses the
-     *  hidden-delivery gate for that PTY while registered. */
+    /** Delivery-interest signal: a renderer party needing raw bytes suppresses the hidden-delivery gate for that PTY while registered. */
     setPtyDeliveryInterest: (id: string, interested: boolean): void => {
       ipcRenderer.send('pty:setPtyDeliveryInterest', { id, interested })
     },
-    /** View-attribute bridge (Phase 5 slice 2): app-global composed terminal
-     *  appearance push that lets main's model responder answer OSC 4/10/11/12
-     *  and DSR ?996n for hidden-gated PTYs with renderer-true values. */
+    /** Push composed terminal appearance so main's model responder can answer OSC 4/10/11/12 and DSR ?996n for hidden-gated PTYs with renderer-true values. */
     publishTerminalViewAttributes: (attributes: TerminalViewAttributes): void => {
       ipcRenderer.send('pty:terminalViewAttributes', attributes)
     },
@@ -1008,8 +956,7 @@ const api = {
     resetRendererDeliveryDebug: (): Promise<void> =>
       ipcRenderer.invoke('pty:resetRendererDeliveryDebug'),
 
-    /** Check if a PTY's shell has child processes (e.g. a running command).
-     *  Returns false for an idle shell prompt. */
+    /** True if the PTY's shell has child processes (a running command); false at an idle prompt. */
     hasChildProcesses: (id: string): Promise<boolean> =>
       ipcRenderer.invoke('pty:hasChildProcesses', { id }),
 
@@ -1019,13 +966,10 @@ const api = {
     confirmForegroundProcess: (id: string): Promise<string | null> =>
       ipcRenderer.invoke('pty:confirmForegroundProcess', { id }),
 
-    /** Resolve the live cwd of a PTY via `/proc` (Linux) or `lsof` (macOS).
-     *  Returns `''` when the id is unknown or the platform cannot resolve one. */
+    /** Resolve a PTY's live cwd via `/proc` (Linux) or `lsof` (macOS); `''` when unknown or unresolvable. */
     getCwd: (id: string): Promise<string> => ipcRenderer.invoke('pty:getCwd', { id }),
 
-    /** The PTY's last APPLIED size (its real winsize), or null if unknown.
-     *  Lets the renderer detect drift after a resize was dropped main-side and
-     *  re-assert, instead of trusting the size it last fired blind. */
+    /** The PTY's last APPLIED size (real winsize), or null if unknown — lets the renderer detect drift after a dropped resize and re-assert. */
     getSize: (id: string): Promise<{ cols: number; rows: number } | null> =>
       ipcRenderer.invoke('pty:getSize', { id }),
 
@@ -1063,10 +1007,8 @@ const api = {
       return () => ipcRenderer.removeListener('pty:replay', listener)
     },
 
-    /** Out-of-band signal that main dropped renderer-bound bytes for a PTY
-     *  (hidden-delivery gate / pending cap) — the pane must restore from the
-     *  model snapshot. Deliberately NOT on pty:data: an in-band marker is
-     *  ambiguous with chunks fully stripped by OSC-9999 cleaning. */
+    /** Out-of-band signal that main dropped renderer-bound bytes (hidden-gate / pending cap); pane restores from the model snapshot.
+     *  NOT on pty:data — an in-band marker is ambiguous with chunks fully stripped by OSC-9999 cleaning. */
     onModelRestoreNeeded: (callback: (event: PtyModelRestoreNeededEvent) => void): (() => void) => {
       const listener = (_event: Electron.IpcRendererEvent, event: PtyModelRestoreNeededEvent) =>
         callback(event)
@@ -1074,9 +1016,8 @@ const api = {
       return () => ipcRenderer.removeListener('pty:modelRestoreNeeded', listener)
     },
 
-    /** Batched derived side-effect facts (title/bell/agent transitions) for
-     *  PTYs whose bytes transit local main. Per-PTY in-order; deliberately not
-     *  synchronized with pty:data (terminal-side-effect-authority.md). */
+    /** Batched side-effect facts (title/bell/agent transitions) for local-main PTYs.
+     *  Per-PTY in-order; deliberately NOT synced with pty:data (terminal-side-effect-authority.md). */
     onSideEffect: (callback: (batch: TerminalSideEffectBatch) => void): (() => void) => {
       const listener = (_event: Electron.IpcRendererEvent, batch: TerminalSideEffectBatch) =>
         callback(batch)
@@ -1084,8 +1025,7 @@ const api = {
       return () => ipcRenderer.removeListener('pty:sideEffect', listener)
     },
 
-    /** Title-only replay snapshot applied on (re)attach — attention facts
-     *  (bells/completions) never replay. */
+    /** Title-only replay snapshot on (re)attach — attention facts (bells/completions) never replay. */
     getSideEffectSnapshot: (id: string): Promise<TerminalSideEffectBatch | null> =>
       ipcRenderer.invoke('pty:sideEffectSnapshot', { id }),
 
@@ -1135,11 +1075,8 @@ const api = {
       ipcRenderer.send('pty:serializeBuffer:response', { requestId, snapshot })
     },
 
-    // Why: pre-signal handshake — renderer declares it will own the serializer
-    // for `paneKey` BEFORE issuing pty:spawn so the cooperation gate in main
-    // can suppress the daemon-snapshot seed. Returns a generation token that
-    // the renderer must echo on settle/clear so paneKey-reuse during teardown
-    // cannot defeat the pre-signal. See docs/mobile-prefer-renderer-scrollback.md.
+    // Why: renderer declares serializer ownership for `paneKey` BEFORE pty:spawn so main suppresses the daemon-snapshot seed.
+    // The returned gen token must be echoed on settle/clear so paneKey reuse during teardown can't defeat the pre-signal. See docs/mobile-prefer-renderer-scrollback.md.
     declarePendingPaneSerializer: (paneKey: string): Promise<number> =>
       ipcRenderer.invoke('pty:declarePendingPaneSerializer', { paneKey }),
 
@@ -1485,9 +1422,7 @@ const api = {
       sourceContext?: TaskSourceContext | null
     }): Promise<GitHubAssignableUser[]> => ipcRenderer.invoke('gh:listAssignableUsers', args),
 
-    // Why: the app renderer owns the work-item-details cache. Main targets this
-    // bridge for non-origin mutations; origin callers already updated their
-    // cache optimistically — see src/main/ipc/github.ts.
+    // Why: renderer owns the work-item cache; main fires this for non-origin mutations only (origin callers updated optimistically). See src/main/ipc/github.ts.
     onWorkItemMutated: (
       callback: (payload: {
         repoPath: string
@@ -1508,9 +1443,7 @@ const api = {
     starOrca: (source: AppStarSource): Promise<boolean> =>
       ipcRenderer.invoke('gh:starOrca', source),
 
-    // Why: rate_limit is exempt from rate-limit accounting, but we still pass
-    // `force` through so callers can bust the 30s in-process cache after a
-    // known-expensive op (e.g. after ProjectPicker discovery).
+    // Why: rate_limit is exempt from rate-limit accounting; `force` still busts the 30s in-process cache after an expensive op.
     rateLimit: (args?: { force?: boolean }): Promise<GetRateLimitResult> =>
       ipcRenderer.invoke('gh:rateLimit', args),
 
@@ -1575,9 +1508,7 @@ const api = {
     create: (args: unknown): Promise<unknown> => ipcRenderer.invoke('hostedReview:create', args)
   },
 
-  // Why: GitLab bindings live in `./gitlab` so adding or changing a
-  // `gl.*` channel doesn't surface as a merge conflict on every
-  // upstream sync of this central preload file.
+  // Why: GitLab bindings live in `./gitlab` so `gl.*` changes don't conflict on every upstream sync of this central file.
   gl: glApi,
 
   linear: {
@@ -1842,11 +1773,7 @@ const api = {
     onboardingCompleted: (): Promise<void> => ipcRenderer.invoke('star-nag:onboardingCompleted')
   },
 
-  // Why: telemetry uses a loose untyped surface at the preload boundary on
-  // purpose — the main-side validator (src/main/telemetry/validator.ts) is
-  // the single enforcement point, not the preload types. The renderer gets
-  // typed `track<N>()` / `setOptIn()` wrappers via
-  // src/renderer/src/lib/telemetry.ts, which is what call sites import.
+  // Why: deliberately loose — main's validator (src/main/telemetry/validator.ts) is the single enforcement point; call sites use the typed wrappers in src/renderer/src/lib/telemetry.ts.
   telemetryTrack: (name: string, props: Record<string, unknown>): Promise<void> =>
     ipcRenderer.invoke('telemetry:track', name, props),
   telemetrySetOptIn: (optedIn: boolean): Promise<void> =>
@@ -1856,10 +1783,7 @@ const api = {
   telemetryGetConsentState: (): Promise<TelemetryConsentState> =>
     ipcRenderer.invoke('telemetry:getConsentState'),
 
-  // Why: diagnostics is the renderer-facing surface for the error-tracking
-  // lane (telemetry-error-tracking.md §User controls). Handlers type-narrow
-  // their inputs in main (renderer is untrusted by design); the bridges here
-  // are deliberately loose for the same reason the telemetry bridges are.
+  // Why: bridges are deliberately loose — main type-narrows this untrusted renderer input (see telemetry-error-tracking.md).
   diagnostics: {
     getStatus: (): Promise<unknown> => ipcRenderer.invoke('diagnostics:getStatus'),
     collectBundle: (lookbackMinutes?: number): Promise<unknown> =>
@@ -1877,8 +1801,7 @@ const api = {
   settings: {
     get: (): Promise<unknown> => ipcRenderer.invoke('settings:get'),
 
-    // Why: blocking read for the few startup decisions (terminal side-effect
-    // authority) that cannot wait for async hydration. Call sparingly.
+    // Why: blocking read for the few startup decisions (terminal side-effect authority) that can't wait for async hydration. Call sparingly.
     getSync: (): unknown => ipcRenderer.sendSync('settings:get-sync'),
 
     set: (args: Record<string, unknown>): Promise<unknown> =>
@@ -2066,8 +1989,7 @@ const api = {
       volume?: number
     }): Promise<NotificationSoundResult> => {
       try {
-        // Why: drop replays while the sound is still ringing. The "test"
-        // button bypasses with force so the user always hears a confirmation.
+        // Why: drop replays while still ringing; the test button passes force to always confirm.
         if (!options?.force && isNotificationSoundPlaying) {
           return { played: false, reason: 'deduped' }
         }
@@ -2101,9 +2023,7 @@ const api = {
         }
 
         const audio = entry.audio
-        // Why: restart-from-zero on every play so a burst of triggers replays
-        // the sound from the start instead of stacking overlapping copies.
-        // Matches GNOME canberra and VS Code AccessibilitySignalService.
+        // Why: restart from zero on each play so bursts replay instead of stacking copies (GNOME canberra / VS Code signal service).
         audio.currentTime = 0
         if (typeof options?.volume === 'number' && Number.isFinite(options.volume)) {
           audio.volume = Math.min(1, Math.max(0, options.volume / 100))
@@ -2702,8 +2622,7 @@ const api = {
   } satisfies PreloadApi['cache'],
 
   session: {
-    // hostId is optional and defaults to 'local' on the main side, so existing
-    // call sites that omit it keep targeting the local session partition.
+    // hostId is optional; main defaults it to 'local' so existing omitting call sites keep the local session partition.
     get: (hostId) => ipcRenderer.invoke('session:get', hostId),
     set: (args, hostId) => ipcRenderer.invoke('session:set', args, hostId),
     patch: (args, hostId) => ipcRenderer.invoke('session:patch', args, hostId),
@@ -3759,10 +3678,7 @@ const api = {
     setZoomLevel: (level: number): void => webFrame.setZoomLevel(level),
     syncTrafficLights: (zoomFactor: number): void =>
       ipcRenderer.send('ui:sync-traffic-lights', zoomFactor),
-    // Why: one-way send (not invoke) so the main-process before-input-event
-    // handler can read the mirrored flag synchronously without a round-trip.
-    // The carve-out in createMainWindow.ts uses this to skip Cmd+B interception
-    // while the markdown editor owns focus, letting TipTap apply bold instead.
+    // Why: one-way send so main's before-input-event can synchronously skip Cmd+B while the markdown editor is focused (TipTap bold).
     setMarkdownEditorFocused: (focused: boolean): void => {
       ipcRenderer.send('ui:setMarkdownEditorFocused', focused)
     },
@@ -3791,9 +3707,7 @@ const api = {
       ipcRenderer.on('window:fullscreen-changed', listener)
       return () => ipcRenderer.removeListener('window:fullscreen-changed', listener)
     },
-    /** Fired when the OS resumes from sleep (main relays powerMonitor). A
-     *  focus-preserving display wake fires no renderer focus/visibility
-     *  events, so terminal wake recovery listens to this explicit signal. */
+    /** Fired when the OS resumes from sleep — a focus-preserving wake fires no renderer focus/visibility events. */
     onSystemResumed: (callback: () => void): (() => void) => {
       const listener = () => callback()
       ipcRenderer.on('system:resumed', listener)
@@ -3807,36 +3721,26 @@ const api = {
     maximize: (): void => {
       ipcRenderer.send('window:maximize')
     },
-    /** Desktop custom titlebar only: read the current maximize state on mount, since
-     *  window:maximize-changed only fires on transitions and a window that
-     *  starts maximized would otherwise show the wrong icon. */
+    /** Desktop custom titlebar only: read initial maximize state on mount — maximize-changed only fires on transitions. */
     isMaximized: (): Promise<boolean> => ipcRenderer.invoke('window:isMaximized'),
-    /** Desktop custom titlebar only: subscribe to maximize state changes so the renderer-drawn
-     *  maximize button can show the correct restore/maximize icon. */
+    /** Desktop custom titlebar only: subscribe to maximize-state changes so the maximize button shows the right icon. */
     onMaximizeChanged: (callback: (isMaximized: boolean) => void): (() => void) => {
       const listener = (_event: Electron.IpcRendererEvent, isMaximized: boolean) =>
         callback(isMaximized)
       ipcRenderer.on('window:maximize-changed', listener)
       return () => ipcRenderer.removeListener('window:maximize-changed', listener)
     },
-    /** Desktop custom titlebar only: request a close from the renderer-drawn close button.
-     *  Routes through main so the BrowserWindow 'close' event fires and the
-     *  terminal-running confirmation guard in the renderer stays active.
-     *  window.close() is unreliable in sandboxed renderers. */
+    /** Desktop custom titlebar only: request close via main so the BrowserWindow 'close' event
+     *  (and its terminal-running guard) still fires — window.close() is unreliable in sandboxed renderers. */
     requestClose: (): void => {
       ipcRenderer.send('window:request-close')
     },
-    /** Desktop custom titlebar only: pop up the application menu at the cursor position.
-     *  Replicates the Alt-key reveal that autoHideMenuBar normally provides,
-     *  triggered by the ··· button in the renderer-drawn title bar. */
+    /** Desktop custom titlebar only: pop up the app menu at the cursor — Alt-reveal replacement for the ··· button. */
     popupMenu: (): void => {
       ipcRenderer.send('menu:popup')
     },
-    /** Fired by the main process when the user tries to close the window
-     *  (X button, Cmd+Q, etc.). Renderer should show a confirmation dialog
-     *  if terminals are still running, then call confirmWindowClose().
-     *  When isQuitting is true, the close was initiated by app.quit() (Cmd+Q)
-     *  and the renderer should skip the running-process dialog. */
+    /** Fired by main when the user tries to close the window; renderer confirms running
+     *  terminals then calls confirmWindowClose(). isQuitting (Cmd+Q / app.quit) skips that dialog. */
     onWindowCloseRequested: (callback: (data: { isQuitting: boolean }) => void): (() => void) => {
       const listener = (_event: Electron.IpcRendererEvent, data: { isQuitting: boolean }) =>
         callback(data ?? { isQuitting: false })
@@ -3936,9 +3840,7 @@ const api = {
       transcriptPath?: string
     ): Promise<NativeChatReadSessionResult> =>
       ipcRenderer.invoke('nativeChat:readSession', { agent, sessionId, limit, transcriptPath }),
-    /** Start live tailing for a transcript. `onAppended` fires with only the
-     *  newly-appended messages. Returns an unsubscribe fn that closes the
-     *  main-process watcher (subscriptionId routes appends to this caller). */
+    /** Start live tailing; onAppended fires with only newly-appended messages. Returns an unsubscribe fn that closes the watcher. */
     subscribe: (
       args: {
         subscriptionId: string
@@ -4385,9 +4287,7 @@ const api = {
       ipcRenderer.on('agentStatus:clear', listener)
       return () => ipcRenderer.removeListener('agentStatus:clear', listener)
     },
-    /** Pull the current cached hook statuses after renderer workspace-session
-     *  hydration. This avoids losing startup replays before the renderer
-     *  knows which tabs exist. */
+    /** Pull cached hook statuses after renderer hydration, so startup replays aren't lost before tabs exist. */
     getSnapshot: (): Promise<AgentStatusIpcPayload[]> =>
       ipcRenderer.invoke('agentStatus:getSnapshot'),
     inferInterrupt: (request: AgentInterruptInferenceRequest): Promise<boolean> =>
@@ -4410,15 +4310,11 @@ const api = {
     },
     getMigrationUnsupportedSnapshot: (): Promise<MigrationUnsupportedPtyEntry[]> =>
       ipcRenderer.invoke('agentStatus:getMigrationUnsupportedSnapshot'),
-    /** Drop the cached hook status for a paneKey on both sides — main-process
-     *  cache (lastStatusByPaneKey) and on-disk last-status file. Fired from
-     *  the renderer when the user dismisses a retained row so a relaunch
-     *  cannot resurrect it. Fire-and-forget; no response. */
+    /** Drop the cached hook status for a paneKey on both sides (memory + on-disk) so a relaunch can't resurrect a dismissed row. */
     drop: (paneKey: string): void => {
       ipcRenderer.send('agentStatus:drop', paneKey)
     },
-    /** Drop all cached hook statuses under one terminal tab prefix. Fired on
-     *  explicit tab close even when the renderer has no matching local row. */
+    /** Drop all cached hook statuses under one terminal tab prefix; fired on explicit tab close even without a local row. */
     dropByTabPrefix: (tabId: string): void => {
       ipcRenderer.send('agentStatus:dropByTabPrefix', tabId)
     },
@@ -4455,8 +4351,7 @@ const api = {
       sessionId: string
     ): Promise<void> => ipcRenderer.invoke('speech:startDictation', modelId, hotwords, sessionId),
     feedAudio: (samples: Float32Array, sampleRate: number, sessionId = 'desktop'): Promise<void> =>
-      // Why: Float32Array data gets zeroed out when crossing the contextBridge
-      // + IPC boundary. Wrapping in a Buffer preserves the raw bytes reliably.
+      // Why: Float32Array is zeroed crossing the contextBridge/IPC boundary; wrap in a Buffer to preserve bytes.
       ipcRenderer.invoke(
         'speech:feedAudio',
         Buffer.from(samples.buffer, samples.byteOffset, samples.byteLength),
@@ -4509,9 +4404,7 @@ const api = {
   }
 }
 
-// Use `contextBridge` APIs to expose Electron APIs to
-// renderer only if context isolation is enabled, otherwise
-// just add to the DOM global.
+// Expose Electron APIs via contextBridge when context-isolated, otherwise attach to the DOM global.
 if (process.contextIsolated) {
   try {
     contextBridge.exposeInMainWorld('electron', electronAPI)
diff --git a/src/relay/agent-hook-server.ts b/src/relay/agent-hook-server.ts
index 8768b57dc1e..40775b5bd6a 100644
--- a/src/relay/agent-hook-server.ts
+++ b/src/relay/agent-hook-server.ts
@@ -1,16 +1,8 @@
-/* eslint-disable max-lines -- Why: relay hook parsing, replay cache, endpoint
-   writing, and assistant-message retry state are one lifecycle unit; splitting
-   them would obscure cleanup ordering across remote PTY reconnects. */
-// Why: relay-side adapter for the shared agent-hook listener pipeline. Hosts
-// a loopback HTTP server (same shape as Orca's main-process server: bind
-// 127.0.0.1:0, bearer-token auth, /hook/<source> routing) and forwards every
-// parsed payload via a callback so `relay.ts` can re-emit it as an
-// `agent.hook` JSON-RPC notification across the existing SSH channel.
-//
-// Per-instance state (warn-once Sets, last-status cache, last-prompt /
-// last-tool caches) lives on `HookListenerState`. The cache is bounded to one
-// entry per paneKey — see docs/design/agent-status-over-ssh.md §5 (Path 3,
-// request-driven replay) for the rationale.
+/* eslint-disable max-lines -- Why: parsing, replay cache, endpoint writing, and retry state are one lifecycle unit; splitting obscures cleanup ordering across reconnects. */
+// Relay-side adapter for the shared agent-hook listener: hosts a loopback HTTP server and
+// forwards each parsed payload via a callback so `relay.ts` re-emits it as an `agent.hook`
+// JSON-RPC notification over the SSH channel. Replay cache is bounded one-entry-per-paneKey —
+// see docs/design/agent-status-over-ssh.md §5 (Path 3, request-driven replay) for the rationale.
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
 import { randomUUID } from 'node:crypto'
 import { basename, dirname, join } from 'node:path'
@@ -40,25 +32,16 @@ import {
 
 export type RelayHookForward = (envelope: AgentHookRelayEnvelope) => void
 
-// Why: relay's userData equivalent. Lives under $HOME so each user on a
-// shared dev box gets their own dir, owned 0o700. Mirrors RELAY_REMOTE_DIR
-// from `ssh-relay-deploy.ts` but stays local to this module — the hook
-// server is the only consumer.
+// Why: relay's userData equivalent under $HOME so each user on a shared dev box gets their own 0o700 dir.
 const RELAY_HOOKS_DIR_NAME = '.orca-relay'
 const RELAY_HOOKS_SUBDIR = 'agent-hooks'
 const ASSISTANT_MESSAGE_RETRY_ATTEMPTS = 5
 const ASSISTANT_MESSAGE_RETRY_MS = 50
 
-// Why: cap env/version metadata at 64 chars so a misbehaving agent CLI
-// cannot grow lastEnvelopeMetaByPaneKey unboundedly per pane via the cache
-// + replay path. Canonical values are short ('production'/'development',
-// '1'/'999'); anything longer is treated as absent.
+// Why: cap env/version at 64 chars so a misbehaving agent CLI can't grow the meta cache unboundedly; canonical values are short.
 const MAX_HOOK_META_LEN = 64
 
-// Why: the WSL relay has no per-pane teardown signal (PTYs live on the
-// Windows host, so nothing calls clearPaneState), and the replay cache would
-// otherwise grow for the relay's lifetime. Recency-cap it; backstop for the
-// SSH relay too.
+// Why: WSL relay has no per-pane teardown (PTYs live on the Windows host), so the replay cache would grow forever without a recency cap.
 const MAX_CACHED_PANES = 256
 
 function defaultEndpointDir(): string {
@@ -88,20 +71,13 @@ export function endpointDirForRelaySocket(sockPath: string): string {
 export type RelayHookServerOptions = {
   /** Where to put endpoint.env / endpoint.cmd. Defaults to `$HOME/.orca-relay/agent-hooks`. */
   endpointDir?: string
-  /** Env tag forwarded into hook payloads. Defaults to "remote", a relay
-   *  location marker that main excludes from dev-vs-prod mismatch warnings. */
+  /** Env tag forwarded into hook payloads. Defaults to "remote", which main excludes from dev-vs-prod mismatch warnings. */
   env?: string
-  /** Fixed auth token. The WSL relay passes the host-issued token that
-   *  already crossed into guest env via WSLENV, so unmodified hook clients
-   *  authenticate without any re-coordination. Defaults to a fresh UUID. */
+  /** Fixed auth token. WSL relay passes the host-issued token (already in guest env via WSLENV) so unmodified hook clients authenticate. Defaults to a fresh UUID. */
   token?: string
-  /** Preferred bind port. The WSL relay passes the Windows listener's port —
-   *  free inside the guest under NAT, so env-sourced client coords stay
-   *  truthful. Occupied (e.g. mirrored networking) → fall back to :0 and rely
-   *  on the endpoint file for re-coordination. Defaults to :0. */
+  /** Preferred bind port. WSL relay passes the Windows listener's port so env-sourced client coords stay truthful; falls back to :0 if occupied. Defaults to :0. */
   preferredPort?: number
-  /** Called once per parsed payload. The relay wires this to
-   *  `dispatcher.notify('agent.hook', envelope)`. */
+  /** Called once per parsed payload; the relay wires this to `dispatcher.notify('agent.hook', envelope)`. */
   forward: RelayHookForward
 }
 
@@ -118,13 +94,8 @@ export class RelayAgentHookServer {
   private endpointFilePath: string
   private endpointFileWritten = false
   private state: HookListenerState = createHookListenerState()
-  // Why: the shared `HookListenerState.lastStatusByPaneKey` cache only stores
-  // `AgentHookEventPayload` (no wire-envelope fields). Replay must still emit
-  // the original `source`/`env`/`version` so Orca's warn-once diagnostics fire
-  // identically to the live POST path. Keep this as a per-instance sidecar map
-  // so the shared listener type stays unchanged. Invariant: every key present
-  // in `state.lastStatusByPaneKey` must also be present here — populated and
-  // cleared in lockstep on the live POST path, clearPaneState, and stop().
+  // Why: shared status cache drops wire-envelope fields; this sidecar holds source/env/version so replay matches the live POST path.
+  // Invariant: keys mirror state.lastStatusByPaneKey, populated/cleared in lockstep.
   private lastEnvelopeMetaByPaneKey: Map<
     string,
     { source: AgentHookSource; env?: string; version?: string }
@@ -154,10 +125,7 @@ export class RelayAgentHookServer {
     try {
       await this.listenOn(this.preferredPort)
     } catch (err) {
-      // Why: the preferred port is best-effort (WSL relay: the Windows
-      // listener's port — occupied under mirrored networking, or by an
-      // unrelated guest process). Fall back to an ephemeral port; clients
-      // re-coordinate through the endpoint file.
+      // Why: preferred port is best-effort; on EADDRINUSE fall back to ephemeral and let clients re-coordinate via the endpoint file.
       if (this.preferredPort > 0 && (err as NodeJS.ErrnoException)?.code === 'EADDRINUSE') {
         this.portFallbackApplied = true
         await this.listenOn(0)
@@ -170,8 +138,7 @@ export class RelayAgentHookServer {
     }
   }
 
-  /** True when the preferred port was occupied and the server fell back to
-   *  an ephemeral bind — diagnostics for the host-side relay manager. */
+  /** True when the preferred port was occupied and the server fell back to an ephemeral bind. */
   get usedPortFallback(): boolean {
     return this.portFallbackApplied
   }
@@ -181,10 +148,7 @@ export class RelayAgentHookServer {
     return new Promise<void>((resolve, reject) => {
       const onStartupError = (err: Error): void => {
         this.server?.off('listening', onListening)
-        // Why: null the server reference on bind failure so a subsequent
-        // start() can retry. Without this, a failed bind (e.g. EMFILE) leaves
-        // this.server populated and the early-return at the top of start()
-        // wedges the relay into a permanently broken state until stop() runs.
+        // Why: null the server ref on bind failure so a later start() can retry (else the early-return at top of start() wedges it).
         this.server = null
         reject(err)
       }
@@ -200,8 +164,7 @@ export class RelayAgentHookServer {
         resolve()
       }
       this.server!.once('error', onStartupError)
-      // Why: loopback only — the agent CLI inside the same remote box reaches
-      // us via curl 127.0.0.1:PORT; nobody outside the box can.
+      // Why: loopback only — reachable by the in-box agent CLI (127.0.0.1), not from outside the box.
       this.server!.listen(port, '127.0.0.1', onListening)
     })
   }
@@ -234,20 +197,13 @@ export class RelayAgentHookServer {
     this.lastEnvelopeMetaByPaneKey.clear()
   }
 
-  /** Request-driven replay: walks the per-paneKey last-payload cache and
-   *  forwards each entry as a fresh notification. Called after Orca has
-   *  re-wired its `agent.hook` handler on the new mux post-`--connect`.
-   *  The relay-driver issues the replay forwards BEFORE returning from the
-   *  request handler so the response strictly trails all replayed
-   *  notifications on the dispatcher's single write callback. */
+  /** Request-driven replay: re-forwards each cached paneKey payload as a fresh notification. Forwards are
+   *  issued before the request handler returns, so the response trails all replayed notifications. */
   replayCachedPayloadsForPanes(): number {
     let count = 0
     for (const [paneKey, event] of this.state.lastStatusByPaneKey.entries()) {
       const meta = this.lastEnvelopeMetaByPaneKey.get(paneKey)
-      // Why: invariant — every paneKey in the shared status cache is populated
-      // in lockstep with `lastEnvelopeMetaByPaneKey`. If meta is missing,
-      // something has drifted; skip rather than fall back to a guessed source
-      // that would mis-tag the event downstream.
+      // Why: invariant — status-cache keys always have meta; if it drifted, skip rather than guess a source that mis-tags downstream.
       if (!meta) {
         continue
       }
@@ -257,17 +213,14 @@ export class RelayAgentHookServer {
     return count
   }
 
-  /** Drop a paneKey's cached entries on PTY exit so a terminated pane never
-   *  resurfaces as a ghost event on a later reconnect. Symmetric with the
-   *  local server's clearPaneState on PTY teardown. */
+  /** Drop a paneKey's cached entries on PTY exit so a terminated pane can't resurface as a ghost event on reconnect. */
   clearPaneState(paneKey: string): void {
     this.clearAssistantMessageRetry(paneKey)
     clearPaneCacheState(this.state, paneKey)
     this.lastEnvelopeMetaByPaneKey.delete(paneKey)
   }
 
-  /** Env vars to inject into every relay-spawned PTY so the hook script /
-   *  in-process plugin POSTs to this loopback server. */
+  /** Env vars to inject into relay-spawned PTYs so the hook script/plugin POSTs back to this loopback server. */
   buildPtyEnv(): Record<string, string> {
     if (this.port <= 0 || !this.token) {
       return {}
@@ -316,8 +269,7 @@ export class RelayAgentHookServer {
       }
       const event = normalizeHookPayload(this.state, source, body, this.env)
       if (event) {
-        // TODO: once normalizeHookPayload returns validated env/version, drop
-        // bodyEnv/bodyVersion and source those from the listener result instead.
+        // TODO: once normalizeHookPayload returns validated env/version, drop bodyEnv/bodyVersion and source them from the listener result.
         const env = this.bodyEnv(body)
         const version = this.bodyVersion(body)
         this.applyEvent(event, source, env, version)
@@ -326,10 +278,7 @@ export class RelayAgentHookServer {
       res.writeHead(204)
       res.end()
     } catch (err) {
-      // Why: agent hooks must fail open — return success on parse / size /
-      // timeout errors so a buggy agent script never blocks the agent run.
-      // Log the swallowed error to stderr so future programmer bugs are not
-      // invisible (the 204 response would otherwise mask them entirely).
+      // Why: hooks fail open (204 on any error) so a buggy agent never blocks the run; still log so the 204 doesn't mask bugs.
       process.stderr.write(
         `[relay-hook-server] hook request failed: ${err instanceof Error ? err.message : String(err)}\n`
       )
@@ -377,8 +326,7 @@ export class RelayAgentHookServer {
     if (event.payload.state !== 'done' || event.payload.lastAssistantMessage) {
       this.clearAssistantMessageRetry(event.paneKey)
     }
-    // Why: delete-then-set keeps Map insertion order equal to last-update
-    // recency, so the cache cap below always evicts the longest-idle pane.
+    // Why: delete-then-set makes Map insertion order = recency, so the cap below evicts the longest-idle pane.
     this.state.lastStatusByPaneKey.delete(event.paneKey)
     this.state.lastStatusByPaneKey.set(event.paneKey, event)
     this.lastEnvelopeMetaByPaneKey.delete(event.paneKey)
@@ -422,8 +370,7 @@ export class RelayAgentHookServer {
     if (!discoveryReady) {
       const discovery = preparePendingGrokResultDiscovery(source, body)
       if (discovery) {
-        // Why: remote slug-group discovery can outlive the bounded transcript-
-        // flush timers, so completion itself drives the first retry.
+        // Why: slug-group discovery can outlive the bounded flush timers, so its completion drives the first retry.
         void discovery
           .then(() => {
             if (this.server) {
diff --git a/src/relay/dispatcher.ts b/src/relay/dispatcher.ts
index a036d5449bb..1f1445da2f1 100644
--- a/src/relay/dispatcher.ts
+++ b/src/relay/dispatcher.ts
@@ -1,5 +1,4 @@
-/* eslint-disable max-lines -- Why: the relay protocol dispatcher keeps client
-   routing, request cancellation, and framing state together. */
+/* eslint-disable max-lines -- dispatcher keeps client routing, cancellation, and framing state together */
 import {
   FrameDecoder,
   MessageType,
@@ -27,14 +26,11 @@ export type MethodHandler = (
 
 export type NotificationHandler = (params: Record<string, unknown>, context: RequestContext) => void
 
-/** Sink write. Returning literal `false` signals saturation (Node stream
- * semantics); `void`/`true` mean the frame was accepted. */
+/** Sink write: `false` signals saturation (Node stream semantics); `void`/`true` mean accepted. */
 export type RelayClientWrite = (data: Buffer) => boolean | void
 
 export type RelayClientSinkOptions = {
-  /** One-shot: invoke `cb` once when the sink can accept more data again
-   * (stream 'drain'), or when the sink is permanently dead (error/close) so
-   * bulk senders waiting on it never hang. */
+  /** One-shot: invoke `cb` when the sink can accept more data (drain) or is permanently dead, so waiters never hang. */
   waitWriteDrain?: (cb: () => void) => void
 }
 
@@ -43,11 +39,9 @@ type RelayClient = {
   decoder: FrameDecoder
   write: RelayClientWrite
   waitWriteDrain?: (cb: () => void) => void
-  /** Pending resolvers for bulk sends stalled on sink saturation. Flushed on
-   * drain, write failure, detach, setWrite, and dispose so no pump hangs. */
+  /** Resolvers for bulk sends stalled on sink saturation; flushed so no pump hangs. */
   drainWaiters: Set<() => void>
-  /** Serializes bulk-lane sends per client so at most one bulk frame is
-   * admitted past the sink's high-water mark at a time. */
+  /** Serializes bulk-lane sends so only one bulk frame is admitted past the sink high-water mark at a time. */
   bulkChain: Promise<void>
   nextOutgoingSeq: number
   highestReceivedSeq: number
@@ -82,31 +76,19 @@ export class RelayDispatcher {
     this.startKeepalive()
   }
 
-  // Why: when a client reconnects via Unix socket, the relay must redirect
-  // all outgoing frames (pty.data, keepalives, responses) to the new socket
-  // instead of the original stdout. Swapping the write callback avoids
-  // tearing down and reconstructing the entire dispatcher + handler tree.
-  //
-  // Why: sequence counters and decoder state must also reset because the new
-  // client's SshChannelMultiplexer starts at seq=1. Without resetting, the
-  // relay's highestReceivedSeq stays at the old client's last value, so it
-  // never acks the new client's frames until the new client's seq catches
-  // up - causing the client's unacked-timeout checker to accumulate stale
-  // timestamps that could eventually fire a false connection-dead signal.
+  // Why: redirect outgoing frames to the reconnected socket without rebuilding the dispatcher + handler tree.
+  // Why: the new client's multiplexer restarts at seq=1, so reset seq/decoder state or acks stall and fire a false connection-dead signal.
   setWrite(write: RelayClientWrite, sinkOptions?: RelayClientSinkOptions): void {
     this.requestAborts.abortClient(this.primaryClient.id)
     this.primaryClient.write = write
     this.primaryClient.waitWriteDrain = sinkOptions?.waitWriteDrain
     this.primaryClient.closed = false
-    // Why: the saturated sink the waiters were parked on no longer exists;
-    // wake stalled bulk senders so they re-evaluate against the new sink.
+    // Why: the old sink is gone; wake stalled bulk senders to re-evaluate against the new one.
     this.flushDrainWaiters(this.primaryClient)
     this.resetClient(this.primaryClient)
   }
 
-  // Why: in-flight mutating requests must become stale when the active client
-  // disconnects even if no replacement has connected yet. Otherwise a late
-  // pty.spawn/fs.watch completion can create remote state nobody can own.
+  // Why: mark in-flight requests stale on disconnect so a late pty.spawn/fs.watch can't create unowned remote state.
   invalidateClient(): void {
     this.requestAborts.abortClient(this.primaryClient.id)
     this.primaryClient.generation++
@@ -115,9 +97,7 @@ export class RelayDispatcher {
     this.notifyClientDetached(this.primaryClient.id)
   }
 
-  // Why: synced remote workspaces can have more than one Orca client attached
-  // to the same relay. Frame sequence numbers and JSON-RPC request ids are per
-  // SSH channel, so each socket client needs independent protocol state.
+  // Why: seq numbers and request ids are per SSH channel, so each attached client needs independent protocol state.
   attachClient(write: RelayClientWrite, sinkOptions?: RelayClientSinkOptions): number {
     const client = this.createClient(write, sinkOptions)
     this.clients.set(client.id, client)
@@ -205,16 +185,10 @@ export class RelayDispatcher {
   }
 
   /**
-   * Bulk-lane notification. Sends are serialized per client and the returned
-   * promise resolves only after the sink accepted the frame without reporting
-   * saturation (or the client went away). Bulk producers (file streams) await
-   * this between frames so interactive frames (pty.data echo) never queue
-   * behind an unbounded backlog on the shared SSH channel.
-   *
-   * With `clientId`, the frame goes only to that client — stream chunks have
-   * exactly one consumer, and broadcasting them would let one slow secondary
-   * client stall everyone. A missing/closed target resolves immediately; the
-   * caller's staleness check owns aborting the stream.
+   * Bulk-lane notification: sends are serialized per client and the promise
+   * resolves only after the sink accepted the frame (backpressure), so bulk
+   * producers await between frames and never starve interactive frames.
+   * With `clientId`, targets only that client — broadcasting would let one slow secondary stall everyone.
    */
   notifyBulk(
     method: string,
@@ -238,8 +212,7 @@ export class RelayDispatcher {
       if (client.closed) {
         continue
       }
-      // Why: the frame is encoded inside the chain step, not at call time —
-      // sequence numbers must be assigned in actual write order.
+      // Why: encode inside the chain step, not at call time, so sequence numbers match actual write order.
       const step = client.bulkChain.then(() => {
         if (this.disposed || client.closed) {
           return
@@ -304,9 +277,7 @@ export class RelayDispatcher {
     const candidates = Array.from(this.clients.values()).filter(
       (client) => !client.closed && client.id !== options?.excludeClientId
     )
-    // Why: detached relays keep the synthetic primary client object around even
-    // though the owning Orca is attached through a Unix-socket client. Prefer a
-    // real attached client so remote `orca` shims do not forward to dead stdout.
+    // Why: prefer a real socket client over the synthetic primary so requests don't forward to a dead stdout.
     const target = candidates.find((client) => client !== this.primaryClient) ?? candidates[0]
     if (!target) {
       return Promise.reject(new Error('No owning Orca client is connected to the relay'))
@@ -356,8 +327,7 @@ export class RelayDispatcher {
       pending.reject(new Error('Relay dispatcher disposed'))
       this.pendingRelayRequests.delete(id)
     }
-    // Why: dispose means this relay instance cannot send responses anymore;
-    // abort in-flight request work so stale SSH-side scans/watchers release.
+    // Why: can't send responses after dispose; abort in-flight work so SSH-side scans/watchers release.
     this.requestAborts.abortAll()
     for (const client of this.clients.values()) {
       this.flushDrainWaiters(client)
@@ -450,9 +420,7 @@ export class RelayDispatcher {
       return
     }
 
-    // Why: capture this client's generation before the async handler runs.
-    // If that client disconnects while the handler is in flight, the response
-    // belongs to a dead request-id space and mutating work may need cleanup.
+    // Why: snapshot generation before the await to detect if the client disconnected mid-flight.
     const gen = client.generation
     const { key: abortKey, controller: abortController } = this.requestAborts.create(
       client.id,
@@ -539,9 +507,7 @@ export class RelayDispatcher {
         this.writeFrame(client, frame)
       }
     }, KEEPALIVE_SEND_MS)
-    // Why: without unref, the keepalive interval keeps the event loop alive
-    // even when the relay should be winding down (e.g. after stdin ends and
-    // all PTYs have exited). unref lets the process exit naturally.
+    // Why: unref so the keepalive interval doesn't pin the event loop and block process exit.
     this.keepaliveTimer.unref()
   }
 
@@ -553,15 +519,7 @@ export class RelayDispatcher {
       client.generation++
       this.requestAborts.abortClient(client.id)
       this.flushDrainWaiters(client)
-      // Why: a write throw means this frame (possibly pty.data or pty.exit) was
-      // lost with no resend — the framing carries seq/ack but no retransmit
-      // buffer. Detach so the owning Orca's reconnect + PTY-reattach path runs
-      // promptly (regenerating dropped pty.data from the replay buffer and pane
-      // death via reattach-not-found), instead of silently dropping frames until
-      // the ~20s keepalive timeout notices. The primary client stays in the map
-      // (its object is reused across setWrite reconnects) but detach listeners
-      // must still fire, exactly as invalidateClient() does for stdin/stdout
-      // death — this makes the socket-write-throw path consistent with those.
+      // Why: frames have no retransmit buffer; detach now so reconnect/PTY-reattach runs instead of waiting the ~20s keepalive timeout.
       if (client !== this.primaryClient) {
         this.clients.delete(client.id)
       }
diff --git a/src/relay/git-handler-status-ops.ts b/src/relay/git-handler-status-ops.ts
index 81d0a4eb83b..37501318154 100644
--- a/src/relay/git-handler-status-ops.ts
+++ b/src/relay/git-handler-status-ops.ts
@@ -1,8 +1,6 @@
 /**
  * Status and conflict-detection operations extracted from git-handler.ts.
- *
- * Why: oxlint max-lines (300) requires splitting large files.
- * These functions are pure data operations on git state — no class coupling.
+ * Why: split to satisfy oxlint max-lines (300); pure data ops on git state, no class coupling.
  */
 import * as path from 'node:path'
 import { existsSync } from 'node:fs'
@@ -79,8 +77,7 @@ export async function getStatusOp(
   const lineStatsCacheKey = `relay\0${worktreePath}`
   const lineStatsWriteToken = beginGitStatusLineStatsCacheWrite(lineStatsCacheKey)
   const includeIgnored = params.includeIgnored === true
-  // Why: reject non-finite/negative limits so the cap guard stays reliable
-  // (NaN would silently disable capping; negatives would over-truncate).
+  // Why: reject NaN/negative limits — NaN would silently disable capping, negatives would over-truncate.
   const rawLimit = params.limit
   const limit =
     typeof rawLimit === 'number' && Number.isFinite(rawLimit) && rawLimit >= 0
@@ -96,10 +93,7 @@ export async function getStatusOp(
   let statusLength = 0
 
   try {
-    // Why: -c core.quotePath=false keeps non-ASCII filenames as raw UTF-8 in
-    // git's stdout instead of C-style octal escapes; without it the parsed
-    // entry.path renders as gibberish in the source-control sidebar and
-    // downstream blob lookups miss.
+    // Why: core.quotePath=false keeps non-ASCII filenames as raw UTF-8 instead of octal escapes that render as gibberish.
     const statusArgs = [
       '-c',
       'core.quotePath=false',
@@ -112,8 +106,7 @@ export async function getStatusOp(
       statusArgs.push('--ignored=matching')
     }
     const { stdout } = await git(statusArgs, worktreePath, {
-      // Why: status polling is read-like; avoid refreshing the index and racing
-      // terminal Git commands on `.git/worktrees/*/index.lock`.
+      // Why: status polling is read-like; avoid racing terminal Git on .git/worktrees/*/index.lock.
       disableOptionalLocks: true,
       signal: options.signal
     })
@@ -123,10 +116,7 @@ export async function getStatusOp(
     upstreamStatus = parsed.upstreamStatus
     ignoredPaths = parsed.ignoredPaths
     statusLength = parsed.entries.length
-    // Why: cap the entry count to match the local path. A repo with an enormous
-    // un-ignored folder would otherwise push tens of thousands of rows through
-    // every poll; truncating keeps the SCM view (and its "too many changes"
-    // state) consistent across local and SSH repos.
+    // Why: cap entry count so an enormous un-ignored folder can't push tens of thousands of rows through every poll.
     if (limit !== 0 && parsed.entries.length > limit) {
       didHitLimit = true
       for (let i = 0; i < limit; i++) {
@@ -143,9 +133,7 @@ export async function getStatusOp(
         const branchName = getShortBranchName(branch)
         if (branchName) {
           try {
-            // Why: this probe coalesces across concurrent status reads, so one
-            // request's abort must not reject the shared in-flight promise for
-            // the others; the probe is small and its cached result stays useful.
+            // Why: this probe coalesces across concurrent status reads, so one request's abort must not reject the shared in-flight promise.
             upstreamStatus = await readOrProbeNoEffectiveUpstreamStatus(
               { worktreePath, branchName, upstreamName: upstreamStatus?.upstreamName },
               (args) => git(args, worktreePath),
@@ -154,8 +142,7 @@ export async function getStatusOp(
               }
             )
           } catch {
-            // Why: status polling should keep returning working-tree entries even
-            // if the richer upstream probe hits a transient SSH/git ref error.
+            // Why: keep returning working-tree entries even if the upstream probe hits a transient SSH/git ref error.
           }
         }
       }
@@ -168,19 +155,14 @@ export async function getStatusOp(
       }
     }
   } catch (error) {
-    // Why: an aborted scan must reject, not resolve — swallowing here would let
-    // a cancelled request be mistaken for a completed (empty) status result.
+    // Why: an aborted scan must reject, not resolve as a completed (empty) status result.
     if (options.signal?.aborted) {
       throw error
     }
     // not a git repo or git not available
   }
 
-  // Why: attach per-area line counts for the sidebar. Diffs run after status
-  // (we need the entry list first) and only for areas that have entries, so a
-  // clean tree costs zero extra git calls. Skipped when the limit was hit —
-  // running numstat over a huge change set would reintroduce the cost the limit
-  // exists to avoid.
+  // Why: skip line-stats when the limit was hit — numstat over a huge change set would reintroduce the cost the limit avoids.
   if (!didHitLimit) {
     await reuseOrRecomputeGitStatusLineStats({
       cacheKey: lineStatsCacheKey,
@@ -195,8 +177,7 @@ export async function getStatusOp(
     clearGitStatusLineStatsCacheKey(lineStatsCacheKey, lineStatsWriteToken)
   }
 
-  // Why: abort after the porcelain read (e.g. during unmerged/upstream/line-stats
-  // work) must still reject — never resolve a cancelled scan as completed.
+  // Why: a late abort (during unmerged/upstream/line-stats work) must still reject, not resolve as completed.
   if (options.signal?.aborted) {
     const error = new Error('The operation was aborted.')
     error.name = 'AbortError'
@@ -228,15 +209,11 @@ async function runNumstat(
     )
     return parseNumstat(stdout)
   } catch (error) {
-    // Why: an aborted pass must reject so a cancelled scan is never treated as
-    // a completed one; only a genuine (non-abort) numstat failure degrades to
-    // uncounted rows below.
+    // Why: an aborted pass must reject so a cancelled scan is never treated as completed.
     if (signal?.aborted) {
       throw error
     }
-    // Why: a numstat failure should leave rows without counts rather than break
-    // the whole status refresh. Null (vs an empty map) tells the caller the
-    // pass is incomplete and must not be cached.
+    // Why: null (vs an empty map) tells the caller the pass is incomplete and must not be cached.
     return null
   }
 }
diff --git a/src/relay/git-handler.test.ts b/src/relay/git-handler.test.ts
index ca787ac1e1b..68e1982d4e2 100644
--- a/src/relay/git-handler.test.ts
+++ b/src/relay/git-handler.test.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: this file covers ~14 distinct relay git
-   handlers plus the addWorktree state machine (--no-track + push.autoSetupRemote
-   probe/write across four flow branches). Splitting per-handler would scatter
-   related coverage without a meaningful boundary. */
+/* eslint-disable max-lines -- Why: one file covers ~14 relay git handlers + the addWorktree state machine; splitting would scatter related coverage. */
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import { GitHandler } from './git-handler'
 import { RelayContext } from './context'
@@ -501,10 +498,7 @@ describe('GitHandler', () => {
       expect(staged!.removed).toBe(1)
     })
 
-    // Why: regression for issue #1503 — git's default core.quotePath=true
-    // emits non-ASCII paths as octal-escaped, double-quoted strings (e.g.
-    // "docs/\346\227\245\346\234\254\350\252\236/sample.md"), which made the
-    // sidebar show gibberish and broke downstream blob reads.
+    // Why: regression for #1503 — default core.quotePath=true octal-escapes non-ASCII paths (breaks sidebar + blob reads).
     it('preserves UTF-8 paths in status output', async () => {
       gitInit(tmpDir)
       const utf8Dir = path.join(tmpDir, 'docs', '日本語')
@@ -521,10 +515,7 @@ describe('GitHandler', () => {
       expect(entry!.path).toBe('docs/日本語/sample.md')
     })
 
-    // Why: regression for issue #1503 on the porcelain v2 type-1 entry parser
-    // branch (tracked + modified). The existing UTF-8 test exercises only the
-    // untracked '?' branch; this one exercises the path-reconstruction code in
-    // parseStatusOutput that joins parts.slice(8).
+    // Why: regression for #1503 on the porcelain v2 type-1 (tracked+modified) parser branch, which the untracked '?' test misses.
     it('preserves UTF-8 paths for tracked-modified entries', async () => {
       gitInit(tmpDir)
       const utf8Dir = path.join(tmpDir, 'docs', '日本語')
@@ -682,8 +673,7 @@ describe('GitHandler', () => {
       )
     })
 
-    // Why: `git submodule add` against a local path is blocked since git 2.38
-    // unless protocol.file.allow=always is set explicitly.
+    // Why: `git submodule add` against a local path is blocked since git 2.38 unless protocol.file.allow=always is set.
     function addSubmodule(parent: string, name: string): string {
       const src = mkdtempSync(path.join(tmpdir(), 'relay-subsrc-'))
       extraDirs.push(src)
@@ -772,9 +762,7 @@ describe('GitHandler', () => {
       expect(result.modifiedContent).toBe(`Subproject commit ${newOid}\n`)
     })
 
-    // Why: a moved gitlink with a clean submodule worktree has no uncommitted
-    // rows, so status/diff must surface the committed file changes between the
-    // recorded and checked-out commits.
+    // Why: a moved gitlink with a clean submodule has no uncommitted rows, so status/diff must surface the committed commit-range changes.
     it('lists commit-range files and diffs them when the pointer moved', async () => {
       gitInit(tmpDir)
       writeFileSync(path.join(tmpDir, 'root.txt'), 'root')
@@ -1038,16 +1026,13 @@ describe('GitHandler', () => {
       }
     })
 
-    // Why: regression for issue #1503 on the branch-diff path. Without
-    // -c core.quotePath=false the diff --name-status output is octal-escaped,
-    // which broke the "Committed on branch" file list.
+    // Why: regression for #1503 on the branch-diff path; without -c core.quotePath=false diff paths are octal-escaped.
     it('preserves UTF-8 paths in branch-compare entries', async () => {
       gitInit(tmpDir)
       writeFileSync(path.join(tmpDir, 'base.txt'), 'base')
       gitCommit(tmpDir, 'initial')
 
-      // Capture the default branch name before switching, so the test works
-      // regardless of whether git's init.defaultBranch is master or main.
+      // Capture the default branch name so the test works regardless of init.defaultBranch (master vs main).
       const baseRef = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
         cwd: tmpDir,
         encoding: 'utf-8'
@@ -1495,10 +1480,7 @@ describe('GitHandler', () => {
       await expect(retry).rejects.toThrow('commitOid must be a full git object id')
     })
 
-    // Why: regression for issue #1503 on git.branchDiff. The branchCompare test
-    // covers loadBranchChanges in git-handler.ts, but branchDiffEntries in
-    // git-handler-ops.ts is a separate code path that also passes
-    // -c core.quotePath=false and must round-trip UTF-8.
+    // Why: regression for #1503 on git.branchDiff — branchDiffEntries is a separate quotePath=false path that must round-trip UTF-8.
     it('preserves UTF-8 paths in branch-diff entries', async () => {
       gitInit(tmpDir)
       writeFileSync(path.join(tmpDir, 'base.txt'), 'base')
@@ -1521,11 +1503,7 @@ describe('GitHandler', () => {
         filePath: 'docs/日本語/sample.md'
       })) as Record<string, unknown>[]
 
-      // Without includePatch, branchDiffEntries returns one stub entry per
-      // changed file. Asserting length===1 confirms the filter matched the
-      // raw UTF-8 path emitted by `git diff --name-status` — if quotePath
-      // were left at default, the entry's path would be the octal-quoted
-      // form and the filter at git-handler-ops.ts:230-237 would not match.
+      // length===1 confirms the path filter matched the raw UTF-8 path; octal-quoted (default quotePath) wouldn't match.
       expect(result).toHaveLength(1)
     })
   })
@@ -1546,10 +1524,7 @@ describe('GitHandler', () => {
     })
 
     it('reports ahead/behind counts against a real upstream remote', async () => {
-      // Why: the upstream branch exists but isn't configured — exercise the
-      // full path through `git rev-parse HEAD@{u}` + `rev-list --left-right`
-      // so a future refactor can't silently break the happy-path roundtrip
-      // the no-upstream test doesn't cover.
+      // Why: exercise the configured-upstream happy path (rev-parse HEAD@{u} + rev-list --left-right) the no-upstream test misses.
       const bareDir = mkdtempSync(path.join(tmpdir(), 'relay-git-bare-'))
       try {
         execFileSync('git', ['init', '--bare'], { cwd: bareDir, stdio: 'pipe' })
@@ -1575,9 +1550,7 @@ describe('GitHandler', () => {
           stdio: 'pipe'
         })
 
-        // Add two local commits (ahead=2), then reset behind the remote tip
-        // and add one different commit so we end up ahead=1, behind=0 vs.
-        // upstream; then reset to first commit to produce behind=1 ahead=0.
+        // Juggle local commits/resets to produce specific ahead/behind counts vs. upstream.
         writeFileSync(path.join(tmpDir, 'ahead1.txt'), 'a1')
         gitCommit(tmpDir, 'ahead1')
         writeFileSync(path.join(tmpDir, 'ahead2.txt'), 'a2')
@@ -1652,8 +1625,7 @@ describe('GitHandler', () => {
           dispatcher.callRequest('git.fetch', { worktreePath: tmpDir })
         ).resolves.not.toThrow()
 
-        // FETCH_HEAD is created by any successful fetch, confirming the
-        // remote was actually contacted (not just silently no-op'd).
+        // FETCH_HEAD exists only after a successful fetch, confirming the remote was actually contacted.
         await expect(fs.access(path.join(tmpDir, '.git', 'FETCH_HEAD'))).resolves.toBeUndefined()
       } finally {
         await fs.rm(bareDir, { recursive: true, force: true })
@@ -1892,10 +1864,7 @@ describe('GitHandler', () => {
     })
 
     it('rethrows upstreamStatus failures that are not "no upstream configured"', async () => {
-      // Why: the handler's catch is narrowed to only swallow the expected
-      // "no upstream" signal. A non-repo path should surface its error rather
-      // than silently returning hasUpstream=false, which would mask auth or
-      // corruption failures in production.
+      // Why: the catch only swallows "no upstream"; other errors must surface so auth/corruption failures aren't masked.
       const nonRepoDir = path.join(tmpDir, 'not-a-repo')
       await fs.mkdir(nonRepoDir, { recursive: true })
 
@@ -1972,9 +1941,7 @@ describe('GitHandler', () => {
     it.skipIf(process.platform === 'win32')(
       'leaves an ordinary repo reached via a symlinked path unchanged',
       async () => {
-        // A symlink alias defeats the path-string gate (git reports the
-        // realpath toplevel); the git-common-dir gate must still skip the
-        // rewrite for an ordinary repo so the reported path is untouched.
+        // A symlink alias defeats the path-string gate; the git-common-dir gate must still skip rewrite for an ordinary repo.
         const repoPath = path.join(tmpDir, 'plain-repo')
         mkdirSync(repoPath)
         gitInit(repoPath)
@@ -1998,10 +1965,7 @@ describe('GitHandler', () => {
     it.skipIf(process.platform === 'win32')(
       'leaves the main entry unchanged when scanned via a linked worktree',
       async () => {
-        // A linked worktree has a `.git` pointer file like a separate-git-dir
-        // checkout, but its porcelain main entry is the real main working root.
-        // The git-common-dir gate must skip the rewrite so the main entry is
-        // not overwritten with the linked worktree's own toplevel.
+        // The git-common-dir gate must skip rewrite so a linked worktree's main entry isn't overwritten with its own toplevel.
         const repoPath = path.join(tmpDir, 'main-repo')
         mkdirSync(repoPath)
         gitInit(repoPath)
@@ -2413,10 +2377,7 @@ describe('GitHandler', () => {
   })
 
   describe('addWorktree', () => {
-    // Why: relay handler tests for addWorktree use a mock-injection approach
-    // to deterministically control git exit codes (in particular `--get` exit
-    // 1 vs other non-zero codes) without relying on the test host's global
-    // git config. Mirrors the pattern in src/main/git/worktree.test.ts.
+    // Why: mock git to control exit codes (e.g. --get exit 1 vs other) deterministically, independent of host git config.
     function setupMockedHandler(roots: string[]) {
       const ctx = new RelayContext()
       for (const r of roots) {
@@ -2498,10 +2459,7 @@ describe('GitHandler', () => {
     })
 
     it('qualifies bare branch name as refs/heads/ when a same-named tag exists', async () => {
-      // Why: repos that fetch with --tags can end up with a local tag named
-      // 'main', making `git worktree add ... main` fail with "fatal: Ambiguous
-      // object name". Qualifying as refs/heads/main tells git exactly which
-      // object to use.
+      // Why: a local tag named 'main' makes bare-name `worktree add ... main` ambiguous; refs/heads/ disambiguates.
       const { localDispatcher, gitMock } = setupMockedHandler(['/relay/repo', '/relay/wt'])
       gitMock.mockResolvedValueOnce({ stdout: 'abc123\n', stderr: '' }) // rev-parse refs/heads/main^{commit}
       gitMock.mockResolvedValueOnce({ stdout: '', stderr: '' }) // worktree add
@@ -2617,10 +2575,7 @@ describe('GitHandler', () => {
     })
 
     it('treats --get success with empty stdout as "already set" (key present but blank)', async () => {
-      // Why: `git config --get key` exits 0 if the key has any value at any
-      // scope, including an explicitly empty string. We must not fall through
-      // to `--local set true` and overwrite that. Mirrors the local addWorktree
-      // parity case in src/main/git/worktree.test.ts.
+      // Why: --get exits 0 for any value including empty string, so an empty value must not fall through to set-true.
       const { localDispatcher, gitMock } = setupMockedHandler(['/relay/repo', '/relay/wt'])
       gitMock.mockRejectedValueOnce(new Error('not a branch')) // rev-parse refs/heads/main^{commit}
       gitMock.mockResolvedValueOnce({ stdout: '', stderr: '' }) // worktree add
@@ -2643,10 +2598,7 @@ describe('GitHandler', () => {
     })
 
     it('does not write --local when --get fails with non-unset code (corrupt config)', async () => {
-      // Why: exit 1 from `git config --get` means "key unset" — anything else
-      // is a real read failure (parse error, locked file). We must NOT fall
-      // through to `--local set true`, which would silently overwrite
-      // whatever value the user actually has.
+      // Why: only --get exit 1 means "unset"; any other code is a real read failure, so don't fall through to set-true.
       const { localDispatcher, gitMock } = setupMockedHandler(['/relay/repo', '/relay/wt'])
       gitMock.mockRejectedValueOnce(new Error('not a branch')) // rev-parse refs/heads/main^{commit}
       gitMock.mockResolvedValueOnce({ stdout: '', stderr: '' }) // worktree add
@@ -2704,9 +2656,7 @@ describe('GitHandler', () => {
     })
 
     it('does not write config when worktree add itself fails', async () => {
-      // Why: a refactor that moves the config block earlier could try to
-      // probe config against a worktree directory that was never created. Pin
-      // the ordering invariant: config calls happen only after worktree add succeeds.
+      // Why: config probes must run only after worktree add succeeds (never against an uncreated dir).
       const { localDispatcher, gitMock } = setupMockedHandler(['/relay/repo', '/relay/wt'])
       gitMock.mockRejectedValueOnce(new Error('not a branch')) // rev-parse refs/heads/main^{commit}
       gitMock.mockRejectedValueOnce(new Error('worktree add failed'))
diff --git a/src/relay/git-handler.ts b/src/relay/git-handler.ts
index 66b5eb2198c..b6275945226 100644
--- a/src/relay/git-handler.ts
+++ b/src/relay/git-handler.ts
@@ -1,5 +1,4 @@
-/* eslint-disable max-lines -- Why: this relay handler centralizes the git RPC
-protocol surface so local and SSH git behavior stay in one dispatch table. */
+/* eslint-disable max-lines -- Why: centralizes the git RPC protocol surface so local and SSH git behavior stay in one dispatch table. */
 import { execFile, spawn, type ExecFileOptions } from 'node:child_process'
 import { promisify } from 'node:util'
 import * as path from 'node:path'
@@ -101,9 +100,7 @@ function resolveRelayPath(repoPath: string, value: string): string {
   if (path.posix.isAbsolute(value) || path.win32.isAbsolute(value)) {
     return value
   }
-  // Old git ignores `--path-format=absolute`, so a relative toplevel/git-dir
-  // must be resolved against the scanned repo path. Mirror worktree.ts's
-  // resolveRevParsePath: pick the win32/posix resolver from the repoPath shape.
+  // Old git ignores `--path-format=absolute`; resolve relative toplevel/git-dir against repoPath, picking the win32/posix resolver by its shape.
   return isWindowsAbsolutePath(repoPath)
     ? path.win32.resolve(repoPath, value)
     : path.posix.resolve(repoPath, value)
@@ -112,11 +109,8 @@ function resolveRelayPath(repoPath: string, value: string): string {
 type RelayRepoLocation = { topLevel: string; commonDir: string }
 
 function parseRelayRepoLocation(repoPath: string, output: string): RelayRepoLocation | undefined {
-  // Old git (pre `--path-format`) echoes the unrecognized flag to stdout and
-  // exits 0 rather than erroring, so drop any echoed `-`-prefixed lines and
-  // read the two trailing path lines (toplevel, then git-common-dir). Strip only
-  // the trailing CR, not surrounding spaces — git paths may legitimately start
-  // or end with a space.
+  // Old git (pre `--path-format`) echoes the unknown flag and exits 0; drop `-`-prefixed lines, take the last two paths.
+  // Strip only the trailing CR, not surrounding spaces — git paths may legitimately start or end with a space.
   const lines = output
     .split('\n')
     .map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line))
@@ -170,17 +164,13 @@ export class GitHandler {
   private dispatcher: RelayDispatcher
   private readonly gitDiffReadDedupe = new InFlightPromiseDedupe<unknown>()
   private readonly gitCapabilities = new GitCapabilityCache()
-  // Why: large diff/exec responses are chunked onto the bulk lane so they do
-  // not head-of-line-block interactive pty.data echo on the shared SSH channel.
+  // Why: large diff/exec responses go on the bulk lane so they don't head-of-line-block interactive pty.data echo on the shared SSH channel.
   private readonly responseStreams = new GitResponseStreamRegistry()
 
-  // Why: configured submodule paths change rarely; an instance-level TTL cache
-  // avoids re-reading `.gitmodules` on every diff click over SSH, and being
-  // per-instance it stays bound to the connection lifecycle (no cross-test leak).
+  // Why: instance-level TTL cache avoids re-reading `.gitmodules` per diff click over SSH; per-instance so it can't leak across tests.
   private submodulePathsCache: SubmodulePathsCache = createSubmodulePathsCache()
 
-  // Why: RelayContext is accepted for protocol back-compat (see
-  // docs/relay-fs-allowlist-removal.md) but no longer consulted on git ops.
+  // Why: RelayContext accepted for protocol back-compat (docs/relay-fs-allowlist-removal.md) but no longer consulted on git ops.
   constructor(
     dispatcher: RelayDispatcher,
     _context: RelayContext,
@@ -188,8 +178,7 @@ export class GitHandler {
   ) {
     this.dispatcher = dispatcher
     this.registerHandlers()
-    // Why: a detached client's git.responseAck frames will never arrive; wake
-    // any pump parked on the ack window so it re-checks staleness and exits.
+    // Why: a detached client's git.responseAck frames never arrive; wake any pump parked on the ack window so it re-checks staleness and exits.
     this.dispatcher.onClientDetached?.(() => this.responseStreams.wakeAll())
   }
 
@@ -266,11 +255,7 @@ export class GitHandler {
     }
   }
 
-  // Why: when the client opted into response streaming and the serialized result
-  // exceeds the threshold, chunk it onto the bulk lane and return a small
-  // sentinel as the RPC result. Old clients omit the flag (single-frame, as
-  // today); old relays never call this, so a new client falls back to the plain
-  // result they return.
+  // Why: opt-in streaming — old clients/relays omit the flag and fall back to the plain result.
   private maybeStreamResponse(
     result: unknown,
     params: Record<string, unknown>,
@@ -293,8 +278,7 @@ export class GitHandler {
   }
 
   private async runWithGitReadCacheClear<T>(run: () => Promise<T>): Promise<T> {
-    // Why: git mutations can stale existing and concurrently-started diff and
-    // .gitmodules reads. Clear before and after so later reads cannot join them.
+    // Why: git mutations can stale in-flight diff/.gitmodules reads; clear before and after so later reads cannot join them.
     this.clearGitMutationReadCaches()
     try {
       return await run()
@@ -349,10 +333,7 @@ export class GitHandler {
     return getStatusOp(this.git.bind(this), params, { signal: context.signal })
   }
 
-  // Why: the parent status only lists a single gitlink row per submodule. The
-  // renderer fetches inner per-file changes on demand by running a plain status
-  // inside the submodule's own worktree. Reject paths escaping the worktree to
-  // match the diff handler's traversal guard.
+  // Why: parent status lists one gitlink row per submodule; fetch inner per-file changes by running status inside the submodule's own worktree.
   private async getSubmoduleStatus(params: Record<string, unknown>) {
     const worktreePath = params.worktreePath as string
     const submodulePath = params.submodulePath as string
@@ -363,9 +344,7 @@ export class GitHandler {
       ...params,
       worktreePath: resolved
     })
-    // Why: a moved gitlink (clean worktree) has no uncommitted rows; surface the
-    // files changed between the recorded and checked-out commits so the expanded
-    // submodule isn't empty. Mirrors getSubmoduleStatus in the local handler.
+    // Why: a moved gitlink (clean worktree) has no uncommitted rows; surface files changed between recorded and checked-out commits so it isn't empty.
     const { fromOid, toOid } = await resolveSubmoduleCommitRange(
       this.git.bind(this),
       worktreePath,
@@ -410,8 +389,7 @@ export class GitHandler {
   private async getDiff(params: Record<string, unknown>, context?: RequestContext) {
     const worktreePath = params.worktreePath as string
     const filePath = params.filePath as string
-    // Why: filePath is relative to worktreePath and used in readWorkingFile via
-    // path.join. Without validation, ../../etc/passwd traverses outside the worktree.
+    // Why: filePath is relative and joined for readWorkingFile; validate or `../../etc/passwd` traverses outside the worktree.
     const resolved = path.resolve(worktreePath, filePath)
     const rel = path.relative(path.resolve(worktreePath), resolved)
     if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
@@ -419,14 +397,11 @@ export class GitHandler {
     }
     const staged = params.staged as boolean
     const compareAgainstHead = params.compareAgainstHead as boolean | undefined
-    // Why: register the in-flight dedupe synchronously (before any await) so
-    // concurrent identical reads coalesce; submodule routing happens inside.
+    // Why: register the in-flight dedupe synchronously (before any await) so concurrent identical reads coalesce; submodule routing happens inside.
     const result = await this.gitDiffReadDedupe.run(
       stableInFlightKey(['diff', worktreePath, filePath, staged, compareAgainstHead]),
       async () => {
-        // Why: gitlink paths can't be read as blobs and submodule working dirs
-        // read as empty, so route the gitlink root → pointer diff and inner
-        // files → recurse into the submodule's own worktree (mirrors local).
+        // Why: gitlinks can't be read as blobs, so route the gitlink root to a pointer diff and inner files into the submodule's own worktree.
         const submodulePaths = await listSubmodulePathsCached(
           this.git.bind(this),
           worktreePath,
@@ -456,9 +431,7 @@ export class GitHandler {
               matchedSubmodule,
               staged
             )
-            // Why: a moved gitlink (clean worktree) keeps inner changes in
-            // committed history, so diff the two commits; otherwise read the
-            // working-tree blob.
+            // Why: a moved gitlink (clean worktree) keeps inner changes in committed history, so diff the two commits; otherwise read the working-tree blob.
             if (fromOid && toOid && fromOid !== toOid) {
               return buildSubmoduleInnerCommitRangeDiff(
                 this.gitBuffer.bind(this),
@@ -582,10 +555,7 @@ export class GitHandler {
     this.clearGitMutationReadCaches()
     const worktreePath = params.worktreePath as string
     const branch = params.branch as string
-    // Defense-in-depth: reject option-like branch tokens (the RPC schema also
-    // validates, but this relay entrypoint is reachable independently). The
-    // `startsWith('-')` guard is what prevents flag injection; the trailing `--`
-    // marks that no pathspecs follow so the token is treated as a branch ref.
+    // Defense-in-depth: reject `-`-prefixed branch tokens to block flag injection (this relay entrypoint is reachable independently of the RPC schema).
     if (typeof branch !== 'string' || branch.length === 0 || branch.startsWith('-')) {
       throw new Error('invalid_branch_name')
     }
@@ -637,8 +607,7 @@ export class GitHandler {
   private assertInWorktree(worktreePath: string, filePath: string): string {
     const resolved = path.resolve(worktreePath, filePath)
     const rel = path.relative(path.resolve(worktreePath), resolved)
-    // Why: empty rel or '.' means the path IS the worktree root — rm -rf would
-    // delete the entire worktree. Reject along with parent-escaping paths.
+    // Why: empty rel or '.' means the path IS the worktree root; reject (with parent-escaping paths) so a discard can't wipe the whole worktree.
     if (
       !rel ||
       rel === '.' ||
@@ -704,8 +673,7 @@ export class GitHandler {
           ['ls-files', '-z', '--', ...chunk.map((p) => this.literalPathspec(p))],
           worktreePath
         )
-        // Why: selecting a tracked directory can make `ls-files -z` return
-        // enough descendants for push(...split) to exceed the argument limit.
+        // Why: a selected tracked directory can make `ls-files -z` return enough descendants for push(...split) to exceed the argument limit.
         for (const trackedPathSpec of stdout.split('\0')) {
           if (trackedPathSpec) {
             trackedPathSpecs.push(trackedPathSpec)
@@ -770,15 +738,13 @@ export class GitHandler {
   private async branchCompare(params: Record<string, unknown>) {
     const worktreePath = params.worktreePath as string
     const baseRef = params.baseRef as string
-    // Why: a baseRef starting with '-' would be interpreted as a flag to
-    // git rev-parse, potentially leaking environment variables or config.
+    // Why: a baseRef starting with '-' would be read as a git rev-parse flag, potentially leaking environment variables or config.
     if (baseRef.startsWith('-')) {
       throw new Error('Base ref must not start with "-"')
     }
     const gitBound = this.git.bind(this)
     return branchCompareOp(gitBound, worktreePath, baseRef, async (mergeBase, headOid) => {
-      // Why: -c core.quotePath=false keeps non-ASCII filenames as raw UTF-8;
-      // without it parseBranchDiff would yield C-style octal-escaped paths.
+      // Why: -c core.quotePath=false keeps non-ASCII filenames as raw UTF-8; without it parseBranchDiff would get C-style octal-escaped paths.
       const { stdout } = await gitBound(
         ['-c', 'core.quotePath=false', 'diff', '--name-status', '-M', '-C', mergeBase, headOid],
         worktreePath
@@ -816,14 +782,11 @@ export class GitHandler {
         (upstreamName) => this.getBehindCommitsArePatchEquivalent(worktreePath, upstreamName)
       )
     } catch (error) {
-      // Why: we only swallow the 'no upstream configured' error — that's an
-      // expected state, not a failure. Other errors (auth, corruption, network)
-      // should surface to the user so they can act on them.
+      // Why: swallow only 'no upstream configured' (an expected state); other errors (auth, corruption, network) must surface to the user.
       if (isNoUpstreamError(error)) {
         return { hasUpstream: false, ahead: 0, behind: 0 }
       }
-      // Why: match fetch/push/pull normalization so execFile preamble and local
-      // paths don't leak to the renderer.
+      // Why: match fetch/push/pull normalization so execFile preamble and local paths don't leak to the renderer.
       throw new Error(normalizeGitErrorMessage(error, 'upstream'))
     }
   }
@@ -839,8 +802,7 @@ export class GitHandler {
       )
       return upstreamOnlyCommitsArePatchEquivalent(stdout)
     } catch {
-      // Why: this only identifies stale post-rebase upstreams. If the probe
-      // fails over SSH, keep the conservative pull-first sync path.
+      // Why: this only identifies stale post-rebase upstreams; if the probe fails over SSH, keep the conservative pull-first sync path.
       return false
     }
   }
@@ -859,9 +821,7 @@ export class GitHandler {
         }
         await this.git(['fetch', '--prune'], worktreePath)
       } catch (error) {
-        // Why: mirror the local gitFetch normalization so SSH users see the same
-        // actionable messages instead of raw git stderr (which varies across
-        // versions/locales and may embed credentials).
+        // Why: normalize like local gitFetch so SSH users get actionable messages, not raw stderr (may embed credentials).
         throw new Error(normalizeGitErrorMessage(error, 'fetch'))
       }
     } finally {
@@ -944,9 +904,7 @@ export class GitHandler {
           worktreePath
         )
       } catch (error) {
-        // Why: create-worktree needs a write-capable fetch, but generic git.exec
-        // intentionally rejects fetch. This narrow RPC keeps the relay allowlist
-        // tight while preserving the same safe error normalization as git.fetch.
+        // Why: create-worktree needs a write-capable fetch that generic git.exec rejects; narrow RPC keeps the allowlist tight.
         throw new Error(normalizeGitErrorMessage(error, 'fetch'))
       }
     } finally {
@@ -980,8 +938,7 @@ export class GitHandler {
         if (!remotes.includes(remote)) {
           throw new Error(`Remote "${remote}" is not configured.`)
         }
-        // Why: GitLab MR heads are not refs/heads/*, so the remote-tracking
-        // fetch RPC cannot represent fork MRs. Keep this write path MR-only.
+        // Why: GitLab MR heads aren't refs/heads/*, so the remote-tracking fetch RPC can't represent fork MRs; keep this write path MR-only.
         await this.git(
           ['fetch', '--no-tags', remote, `refs/merge-requests/${mergeRequestIid}/head`],
           worktreePath
@@ -997,8 +954,7 @@ export class GitHandler {
   private async push(params: Record<string, unknown>) {
     this.clearGitMutationReadCaches()
     const worktreePath = params.worktreePath as string
-    // Why: mirror src/main/git/remote.ts. Push to a configured upstream when
-    // present so SSH worktrees with non-origin targets do not get repointed.
+    // Why: mirror src/main/git/remote.ts — push to a configured upstream when present so SSH worktrees with non-origin targets aren't repointed.
     void params.publish
     try {
       try {
@@ -1015,8 +971,7 @@ export class GitHandler {
         ]
         await this.git(args, worktreePath)
       } catch (error) {
-        // Why: mirror the local gitPush normalization so SSH users see the same
-        // "non-fast-forward / pull first" guidance instead of raw git stderr.
+        // Why: mirror local gitPush normalization so SSH users get "non-fast-forward / pull first" guidance instead of raw git stderr.
         throw new Error(normalizeGitErrorMessage(error, 'push'))
       }
     } finally {
@@ -1040,8 +995,7 @@ export class GitHandler {
       }
       const upstream = await resolveEffectiveGitUpstream((args) => this.git(args, worktreePath))
       if (upstream && !upstream.isConfiguredUpstream) {
-        // Why: legacy Orca branches may still track origin/main while pushes
-        // target origin/<branch>. Pull the same effective branch the UI reports.
+        // Why: legacy Orca branches may track origin/main while pushes target origin/<branch>; pull the same effective branch the UI reports.
         await this.git(
           ['pull', ...effectiveArgs, upstream.remoteName, upstream.branchName],
           worktreePath
@@ -1055,8 +1009,7 @@ export class GitHandler {
       try {
         await runPullWithDivergenceFallback(pullArgs, runPull)
       } catch (error) {
-        // Why: mirror the local gitPull normalization so SSH users see the same
-        // actionable messages instead of raw git stderr.
+        // Why: mirror local gitPull normalization so SSH users get actionable messages instead of raw git stderr.
         throw new Error(normalizeGitErrorMessage(error, 'pull'))
       }
     } finally {
@@ -1065,8 +1018,7 @@ export class GitHandler {
   }
 
   private async pull(params: Record<string, unknown>) {
-    // Why: plain `git pull` honors the user's configured merge/rebase/ff policy.
-    // If no policy exists, Git's policy error is normalized with setup guidance.
+    // Why: plain `git pull` honors the user's merge/rebase/ff policy; with none, Git's policy error is normalized with setup guidance.
     await this.pullWithArgs(params, [])
   }
 
@@ -1252,8 +1204,7 @@ export class GitHandler {
         throw new Error('Branch name must not start with "-".')
       }
       try {
-        // Why: generic git.exec intentionally blocks destructive branch flags.
-        // This narrow RPC permits only the already-checked current-branch rename.
+        // Why: generic git.exec blocks destructive branch flags; this narrow RPC permits only the already-checked current-branch rename.
         await this.git(['check-ref-format', '--branch', newBranch], worktreePath)
         await this.git(['branch', '-m', newBranch], worktreePath)
       } catch (error) {
@@ -1273,9 +1224,7 @@ export class GitHandler {
     ) {
       throw new Error('Invalid preserved branch force-delete request.')
     }
-    // Why: an empty repoPath would resolve `cwd` to the relay's own process
-    // directory, running the destructive update-ref against the wrong repo. NUL
-    // bytes cannot reach git safely either; reject both at the boundary.
+    // Why: empty repoPath would target the relay's own cwd with a destructive update-ref, and NUL bytes can't reach git safely — reject both.
     if (!repoPath || repoPath.includes('\0') || expectedHead.includes('\0')) {
       throw new Error('Invalid preserved branch force-delete request.')
     }
@@ -1304,8 +1253,7 @@ export class GitHandler {
             repoPath
           )
           if (hasUnsupportedRevParsePathFormatEcho(stdout)) {
-            // Why: some old Git versions echo the unknown option and exit zero;
-            // remember that signal even though the trailing paths remain usable.
+            // Why: old Git echoes the unknown option and exits zero; remember the signal though the paths still parse.
             this.gitCapabilities.rememberUnsupported('rev-parse-path-format')
           }
           return parseRelayRepoLocation(repoPath, stdout)
@@ -1331,8 +1279,7 @@ export class GitHandler {
     const mainIndex = worktrees.findIndex((worktree) => worktree.isMainWorktree === true)
     const mainWorktree = worktrees[mainIndex]
     const mainPath = typeof mainWorktree?.path === 'string' ? mainWorktree.path : ''
-    // Expand `~` so the early-return matches git's absolute porcelain path for
-    // legacy SSH repos stored with a tilde, sparing them a rev-parse per poll.
+    // Expand `~` so legacy tilde SSH repo paths match git's absolute path, sparing a rev-parse per poll.
     const resolvedRepoPath = expandTilde(repoPath)
     if (!mainPath || areRelayWorktreePathsEqual(mainPath, resolvedRepoPath)) {
       return worktrees
@@ -1343,10 +1290,7 @@ export class GitHandler {
       return worktrees
     }
 
-    // Why: only a separate-git-dir/submodule main worktree reports the Git
-    // directory as the main entry — i.e. the main entry equals git-common-dir.
-    // A linked worktree's main entry is a real working root, so gating on this
-    // equality avoids overwriting it with the linked worktree's own toplevel.
+    // Why: only separate-git-dir/submodule repos have main entry == git-common-dir; gate on it so we don't clobber a linked worktree's real root.
     if (!areRelayWorktreePathsEqual(mainPath, location.commonDir)) {
       return worktrees
     }
@@ -1371,8 +1315,7 @@ export class GitHandler {
           )
         },
         async () => {
-          // Why: `-z` keeps newline-containing SSH worktree paths intact, but
-          // Git <2.36 requires the line-block parser.
+          // Why: Git <2.36 lacks worktree-list `-z`, so fall back to the newline-block parser (loses newline-in-path safety).
           try {
             const { stdout } = await this.git(['worktree', 'list', '--porcelain'], repoPath, {
               signal: context?.signal
@@ -1381,11 +1324,7 @@ export class GitHandler {
               repoPath,
               parseWorktreeList(stdout)
             )
-            // Why: this `-z`-unsupported fallback (Git <2.36) also serves Git
-            // <2.31, which emits no `prunable` annotation; probe each linked
-            // worktree path instead of treating stale registrations as live.
-            // On Git 2.31–2.35 the annotation is already parsed, so the probe
-            // is a harmless backstop (issue #8389).
+            // Why: Git <2.31 emits no `prunable` annotation, so probe each linked worktree's existence instead of trusting stale registrations (issue #8389).
             return annotatePrunableWorktreesByExistence(normalized)
           } catch {
             return []
diff --git a/src/relay/pty-handler.ts b/src/relay/pty-handler.ts
index d06695342d0..28df63b7960 100644
--- a/src/relay/pty-handler.ts
+++ b/src/relay/pty-handler.ts
@@ -60,20 +60,14 @@ type ManagedPty = {
   buffered: string
   /** Timer for SIGKILL fallback after a graceful SIGTERM shutdown. */
   killTimer?: ReturnType<typeof setTimeout>
-  /** True once disposeManagedPty has run. Prevents double-dispose (onExit + an
-   *  explicit shutdown can both fire for the same PTY) and converts post-dispose
-   *  entry-point calls into a clean "not found" error instead of a silent no-op
-   *  (POSIX proc.kill is neutralized inside disposeManagedPty). */
+  /** True once disposeManagedPty has run; blocks double-dispose and makes post-dispose calls fail "not found" not silently. */
   disposed?: boolean
   /** True once external cleanup observers have been notified. */
   exitListenerNotified?: boolean
-  /** Renderer-supplied paneKey from spawn env (ORCA_PANE_KEY). Captured so
-   *  external observers (the relay-hook-server cache) can evict per-pane
-   *  state when this PTY exits. Symmetric with Orca's local pty.ts. */
+  /** Renderer-supplied paneKey (ORCA_PANE_KEY); captured so exit observers can evict per-pane cache state. */
   paneKey?: string
   tabId?: string
-  /** Attach-only identity metadata supplied over RPC. Kept separate from
-   *  paneKey/tabId because those fields also control shell env/revive hooks. */
+  /** Attach-only identity metadata (RPC). Separate from paneKey/tabId, which also drive shell env/revive hooks. */
   attachIdentity?: PtyIdentity
   worktreeId?: string
   terminalHandle?: string
@@ -103,10 +97,7 @@ type ManagedStartupCommand = {
   timer: ReturnType<typeof setTimeout> | null
 }
 
-// Why: node-pty's Windows agent throws "Signals not supported on windows." for
-// any signal argument. ConPTY/winpty has no signal semantics — a bare kill()
-// force-terminates the child — so drop the signal on Windows and forward it
-// (SIGTERM graceful vs SIGKILL force) on POSIX.
+// Why: node-pty's Windows agent throws on any signal arg (ConPTY has no signal semantics); drop it there, forward on POSIX.
 function killPtyProcess(pty: IPty, signal: string): void {
   if (process.platform === 'win32') {
     pty.kill()
@@ -131,26 +122,17 @@ function disposeManagedPty(managed: ManagedPty): void {
     return
   }
   managed.disposed = true
-  // Why: clear any pending 5s SIGKILL fallback timer. If graceful-shutdown
-  // armed a killTimer and the child then exited cleanly (firing onExit →
-  // disposeManagedPty), the timer would otherwise fire later and attempt
-  // pty.kill('SIGKILL') on an already-disposed instance. The ptys.has(id)
-  // guard inside the timer short-circuits today, but symmetry is clearer.
+  // Why: clear the SIGKILL fallback timer so it can't fire pty.kill on an already-disposed instance.
   if (managed.killTimer) {
     clearTimeout(managed.killTimer)
     managed.killTimer = undefined
   }
-  // Why: UnixTerminal.destroy() registers `_socket.once('close', () => this.kill('SIGHUP'))`.
-  // The close event fires asynchronously; by then the child may have exited and
-  // its pid been recycled. On the Linux remote hosts the relay typically runs on,
-  // pid recycling is fast — SIGHUP to a stranger is a real hazard. Neutralize
-  // managed.pty.kill before destroy() runs. Windows exempt: WindowsTerminal.destroy
-  // IS a kill() call via _deferNoArgs — neutralizing it leaks the ConPTY agent.
+  // Why: neutralize pty.kill before destroy() so UnixTerminal's async 'close' SIGHUP can't hit a recycled pid.
+  // Windows exempt: its destroy() IS a kill() (via _deferNoArgs), so neutralizing leaks the ConPTY agent.
   if (process.platform !== 'win32') {
     ;(managed.pty as unknown as { kill: (sig?: string) => void }).kill = () => {}
   } else if (managed.gracefulKillSent || managed.forceKillSent) {
-    // Why: WindowsTerminal.destroy() calls kill() internally; any prior bare
-    // kill already closed ConPTY, so destroy would double-close the handle.
+    // Why: WindowsTerminal.destroy() calls kill(); a prior bare kill already closed ConPTY, so skip to avoid double-close.
     return
   }
   try {
@@ -251,11 +233,9 @@ export type PtyExitListener = (event: { id: string; paneKey?: string }) => void
 type PtyIdentity = { paneKey?: string; tabId?: string }
 
 /**
- * True when a reattach's expected pane identity contradicts the target PTY's
- * own. Used to reject cross-relay-generation id collisions: a reset relay mints
- * `pty-N` from 1 again, so an old lease's `pty-N` can name a different pane's
- * fresh PTY. Only compares fields present on *both* sides — absent identity on
- * either side is permissive so legacy PTYs and identity-less callers still attach.
+ * True when a reattach's expected pane identity contradicts the target PTY's own.
+ * Rejects cross-relay-generation id collisions (a reset relay reuses `pty-N`).
+ * Only compares fields present on both sides; absent identity stays permissive.
  */
 export function attachIdentityMismatches(expected: PtyIdentity, managed: PtyIdentity): boolean {
   return Boolean(
@@ -263,14 +243,8 @@ export function attachIdentityMismatches(expected: PtyIdentity, managed: PtyIden
     (expected.tabId && managed.tabId && expected.tabId !== managed.tabId)
   )
 }
-/** Returns env to merge into the PTY's spawn env. Receives spawn context so
- *  augmenters that need a per-PTY identity (e.g. OPENCODE_CONFIG_DIR overlay
- *  paths derived from the renderer's paneKey) can compute it without pulling
- *  the renderer's env in twice. `command` is the renderer-chosen agent launch
- *  command (`pi`, `omp`, …) — supplied by ssh-pty-provider.ts so the Pi
- *  overlay can resolve the per-agent source dir without disk-presence
- *  guessing. NEVER undefined for client-driven spawns that target a
- *  Pi-compatible agent; may be undefined for CLI-launched bare shells. */
+/** Returns env to merge into the PTY's spawn env. Receives spawn context so augmenters can derive per-PTY identity from paneKey.
+ *  `command` is the renderer-chosen agent launch command (`pi`, `omp`, …); undefined for CLI-launched bare shells. */
 export type PtyEnvAugmenter = (ctx: {
   id: string
   paneKey?: string
@@ -302,18 +276,9 @@ export class PtyHandler {
   private ptyModule: typeof NodePty | null = null
   private ptyModuleLoadPromise: Promise<typeof NodePty | null> | null = null
   private reloadPtyModuleFromDisk = false
-  // Why: external observers need to drop per-pane state when a PTY exits.
-  // Today the relay composes multiple consumers (hook-server cache eviction
-  // and plugin-overlay dir cleanup) into a single callback at the call site
-  // (see relay.ts setExitListener). A single optional slot is intentional —
-  // callers compose externally rather than us maintaining a listener list.
-  // A throw inside the listener is swallowed so it can never block
-  // disposeManagedPty / map cleanup.
+  // Why: single optional slot is intentional — callers compose externally; a throw is swallowed so it can't block cleanup.
   private exitListener: PtyExitListener | null = null
-  // Why: env augmenters injected at relay boot (currently the relay-hook
-  // server's ORCA_AGENT_HOOK_* coords). Run on every spawn so every PTY
-  // sees the live hook coordinates without the dispatcher needing to know
-  // about agent hooks.
+  // Why: env augmenters run on every spawn so each PTY sees live hook coords without the dispatcher knowing about agent hooks.
   private envAugmenters: PtyEnvAugmenter[] = []
 
   constructor(dispatcher: RelayDispatcher, graceTimeMs = DEFAULT_GRACE_TIME_MS) {
@@ -346,8 +311,7 @@ export class PtyHandler {
         this.reloadPtyModuleFromDisk = true
       }
     }
-    // Why: the relay is launched from its install dir today, but module
-    // resolution must remain tied to the deployed bundle rather than cwd.
+    // Why: tie module resolution to the deployed bundle dir, not cwd.
     const moduleEntry = join(__dirname, 'node_modules', 'node-pty', 'lib', 'index.js')
     if (!existsSync(moduleEntry)) {
       return null
@@ -398,17 +362,13 @@ export class PtyHandler {
     return this.graceTimeMs
   }
 
-  /** Subscribe to PTY-exit events. Used by the relay-hook server to evict
-   *  per-paneKey cached payloads when the backing PTY ends. */
+  /** Subscribe to PTY-exit events (relay-hook server uses this to evict per-paneKey caches). */
   setExitListener(listener: PtyExitListener | null): void {
     this.exitListener = listener
   }
 
-  /** Register an env augmenter whose return value is merged into every spawn
-   *  env *after* `process.env` and the renderer-supplied env. Used by the
-   *  relay-hook server to inject ORCA_AGENT_HOOK_PORT/TOKEN/ENV/VERSION/
-   *  ENDPOINT — values the agent CLI inside the PTY needs to find the local
-   *  hook receiver. See docs/design/agent-status-over-ssh.md §3. */
+  /** Register an env augmenter merged into every spawn env *after* process.env and renderer env.
+   *  Used by the relay-hook server to inject ORCA_AGENT_HOOK_* coords. See docs/design/agent-status-over-ssh.md §3. */
   addEnvAugmenter(augmenter: PtyEnvAugmenter): () => void {
     this.envAugmenters.push(augmenter)
     return () => {
@@ -419,13 +379,7 @@ export class PtyHandler {
     }
   }
 
-  /** Build the augmented spawn env. Augmenter values override `process.env`
-   *  and any renderer-supplied env (the augmenter contract — see
-   *  addEnvAugmenter doc-comment). Used by both spawn() and revive() so the
-   *  relationship between process.env, renderer env, and augmenters cannot
-   *  drift between the two paths — revived shells after a relay restart must
-   *  see the fresh ORCA_AGENT_HOOK_* coords just like freshly-spawned ones,
-   *  otherwise agent-status over SSH silently breaks on every revive. */
+  /** Build augmented spawn env; augmenter values win over process.env/renderer env. Shared by spawn()/revive() so precedence can't drift. */
   private buildSpawnEnv(
     rendererEnv: Record<string, string> | undefined,
     ctx: { id: string; paneKey?: string; shell: string; command?: string },
@@ -454,8 +408,7 @@ export class PtyHandler {
       }
     }
     const result = mergeGitConfigEnvProtocol(baseEnv, augmented) as Record<string, string>
-    // Why: match local/daemon precedence so relay defaults and augmenters
-    // cannot resurrect attribution or identity values explicitly removed.
+    // Why: match local/daemon precedence so defaults/augmenters can't resurrect explicitly-removed values.
     for (const key of envToDelete) {
       delete result[key]
     }
@@ -466,8 +419,7 @@ export class PtyHandler {
     ) {
       result.TERM = rendererEnv.TERM
     }
-    // Why: node-pty treats missing/empty TERM as its own platform-specific
-    // default. Normalize here so POSIX and Windows relay children agree.
+    // Why: node-pty defaults missing/empty TERM per-platform; normalize so POSIX and Windows children agree.
     if (!result.TERM) {
       result.TERM = 'xterm-256color'
     }
@@ -522,10 +474,7 @@ export class PtyHandler {
       }
     }
     const submit = process.platform === 'win32' ? '\r' : '\n'
-    // Why: a multiline startup prompt is pasted literally via bracketed paste
-    // only when the Orca shell-ready wrapper is active (waitForShellReady) —
-    // that is the bash/zsh overlay that arms bracketed-paste mode. Other remote
-    // shells keep the raw submit path so the ESC[200~ markers are not echoed.
+    // Why: only the shell-ready wrapper arms bracketed-paste; other shells use raw submit so ESC[200~ markers aren't echoed.
     const payload = buildStartupCommandSubmission(startup.command, {
       submit,
       bracketedPasteSafe: startup.waitForShellReady
@@ -570,19 +519,11 @@ export class PtyHandler {
       if (managed.disposed) {
         return
       }
-      // Why: neutralize managed.pty.kill synchronously BEFORE anything else
-      // in this callback. node-pty's UnixTerminal has
-      // `_socket.once('close', () => this.kill('SIGHUP'))` wired at destroy
-      // time, and the master socket can emit 'close' concurrently with this
-      // onExit on natural exit. If 'close' wins, SIGHUP targets the reaped
-      // pid — recycled to an unrelated process on Linux (the typical relay
-      // host). Synchronous neutralization closes that window. Windows is
-      // exempt (WindowsTerminal.destroy uses kill() to close ConPTY).
+      // Why: neutralize pty.kill synchronously so node-pty's 'close' SIGHUP can't hit a recycled pid on POSIX.
       if (process.platform !== 'win32') {
         ;(managed.pty as unknown as { kill: (sig?: string) => void }).kill = () => {}
       }
-      // Why: If the PTY exits normally (or via SIGTERM), we must clear the
-      // SIGKILL fallback timer to avoid firing SIGKILL later.
+      // Why: clear the SIGKILL fallback timer on clean exit so it doesn't fire later.
       if (managed.killTimer) {
         clearTimeout(managed.killTimer)
         managed.killTimer = undefined
@@ -594,9 +535,7 @@ export class PtyHandler {
       this.notifyExitListener(managed)
       this.ptys.delete(managed.id)
       this.clearPtyFlowState(managed.id)
-      // Why: release the ptmx fd on the natural-exit path. Without this the
-      // node-pty wrapper's _socket stays alive until GC and the master fd
-      // leaks (see docs/fix-pty-fd-leak.md).
+      // Why: release the ptmx fd on natural exit, else the master fd leaks until GC (docs/fix-pty-fd-leak.md).
       disposeManagedPty(managed)
     })
   }
@@ -617,8 +556,7 @@ export class PtyHandler {
       return
     }
     managed.exitListenerNotified = true
-    // Why: external observers own relay-hook cache eviction and plugin-overlay
-    // cleanup. Physical exits and whole-relay disposal both need it exactly once.
+    // Why: notify exactly once — both physical exit and whole-relay disposal reach here.
     if (this.exitListener) {
       try {
         this.exitListener({ id: managed.id, paneKey: managed.paneKey })
@@ -701,8 +639,7 @@ export class PtyHandler {
   ): void {
     const existing = this.pendingOutputByPty.get(id)
     if (meta.transformed === true) {
-      // Why: transformed spans have no raw-to-clean slice mapping, so neither
-      // side of their boundary may be folded into the relay's output batch.
+      // Why: transformed spans lack a raw-to-clean slice mapping, so they can't be folded into the output batch.
       if (existing) {
         this.flushPtyOutput(id)
       }
@@ -720,8 +657,7 @@ export class PtyHandler {
     if (this.shouldSendInteractiveOutputNow(id, pending.data)) {
       this.pendingOutputByPty.delete(id)
       this.clearOutputFlushTimerIfIdle()
-      // Why: remote agent TUIs redraw around each keystroke. Background relay
-      // batching should reduce SSH chatter, not add visible input echo delay.
+      // Why: send interactive echo immediately — batching must not add visible input delay for TUIs.
       this.dispatcher.notify('pty.data', { id, ...pending })
       return
     }
@@ -772,8 +708,7 @@ export class PtyHandler {
       writes++
     }
     if (this.pendingOutputByPty.size > 0 && writes > 0) {
-      // Why: relay-side output can arrive as a large single PTY chunk. Yield
-      // between slices so client input and control frames can interleave.
+      // Why: yield between slices of a large chunk so client input and control frames can interleave.
       this.scheduleOutputFlush(PTY_OUTPUT_DRAIN_CONTINUE_MS)
     }
   }
@@ -826,8 +761,7 @@ export class PtyHandler {
         throw new Error('Maximum number of PTY sessions reached (50)')
       }
     } catch (error) {
-      // Why: worktree identity and cwd can belong to different roots. A later
-      // rejection must release every earlier admission before propagating.
+      // Why: a later rejection must release every earlier admission before propagating.
       finishPtyCreationOperations(finishRemovalOperations)
       throw error
     }
@@ -905,16 +839,9 @@ export class PtyHandler {
       id = `pty-${this.nextId++}`
     } while (this.ptys.has(id) || this.pendingReviveIds.has(id))
 
-    // Why: server-side augmenter values (ORCA_AGENT_HOOK_* and plugin overlay
-    // dirs) override renderer-supplied env so live remote paths and hook coords
-    // win over local userData paths. The context lets overlay augmenters derive
-    // per-PTY OpenCode/Pi directories from the stable paneKey when present.
-    // `command` is usually forwarded by ssh-pty-provider.ts only as a hint
-    // for overlay resolution; runtime-owned PTYs opt into relay delivery
-    // because no renderer TerminalPane exists to type the command.
+    // Why: augmenter values override renderer env so remote paths and hook coords win over local userData.
     const paneKey = typeof env?.ORCA_PANE_KEY === 'string' ? env.ORCA_PANE_KEY : undefined
-    // Why: kept so a restarted runtime can re-adopt this live PTY under its
-    // originally-exported handle (reported via listProcesses, survives revive).
+    // Why: kept so a restarted runtime can re-adopt this PTY under its original handle (survives revive).
     const terminalHandle =
       typeof env?.ORCA_TERMINAL_HANDLE === 'string' ? env.ORCA_TERMINAL_HANDLE : undefined
     const command = typeof params.command === 'string' ? params.command : undefined
@@ -924,9 +851,7 @@ export class PtyHandler {
     const shouldProviderDeliverCommand = commandDelivery === 'provider' && command !== undefined
     const spawnEnv = this.buildSpawnEnv(env, { id, paneKey, shell, command }, envToDelete)
     const launchCommandHint = resolveSetupAgentSequenceLaunchCommand(spawnEnv, command)
-    // Why: SSH PTYs bypass main's host-env builder. Apply the policy only
-    // after the relay merges its authoritative process environment so indexed
-    // Git config and remote Windows/WSL behavior remain intact.
+    // Why: SSH PTYs bypass main's host-env builder, so apply the guard after the relay merges its authoritative env.
     const gitCredentialPromptGuarded = applyTerminalGitCredentialPromptGuard(spawnEnv, {
       launchCommand: launchCommandHint,
       isUnattended: isTuiAgent(params.launchAgent),
@@ -939,34 +864,26 @@ export class PtyHandler {
         startupCommandDelivery:
           params.startupCommandDelivery === 'shell-ready' ? 'shell-ready' : undefined
       })
-    // Why: renderer- and provider-delivered startup commands both use this
-    // marker; the side responsible for delivery also strips it from output.
+    // Why: both renderer- and provider-delivered startup commands use this marker; the delivering side strips it from output.
     const shellLaunch = getRelayShellLaunchConfig(shell, spawnEnv, process.platform, {
       terminalWindowsWslDistro,
       emitReadyMarker: shouldEmitShellReadyMarker
     })
 
-    // Why: SSH exec channels give the relay a minimal environment without
-    // .zprofile/.bash_profile sourced. Spawning a login shell ensures PATH
-    // includes Homebrew, nvm, and user-installed CLIs (claude, codex, gh).
-    // When overlays are injected, the launch wrapper keeps those paths after
-    // user startup files re-export their defaults.
+    // Why: SSH exec channels give a minimal env; a login shell sources startup files so PATH includes Homebrew/nvm/user CLIs.
     let term: IPty
     try {
       term = pty.spawn(shell, shellLaunch.args, {
-        // Why: node-pty overwrites env.TERM with `name`; keep caller-selected
-        // terminal identities instead of losing them at the final spawn boundary.
+        // Why: node-pty overwrites env.TERM with `name`; pass caller-selected TERM so it isn't lost.
         name: spawnEnv.TERM ?? 'xterm-256color',
         cols,
         rows,
         cwd,
-        // Why: relay shells inherit process.env; never let an ambient Orca marker
-        // enable shell-ready behavior unless this spawn explicitly requested it.
+        // Why: relay shells inherit process.env; don't let an ambient Orca marker enable shell-ready unless requested.
         env: { ...spawnEnv, ORCA_SHELL_READY_MARKER: '0', ...shellLaunch.env }
       })
     } catch (error) {
-      // Why: Windows node-pty loads conpty.node only on first spawn, after the
-      // wrapper import succeeded. Keep that late failure on the degraded path.
+      // Why: Windows loads conpty.node only on first spawn, so handle that late binding failure here.
       if (isMissingNodePtyNativeBinding(error)) {
         this.invalidatePtyModuleAfterBindingFailure()
         throw new Error('node-pty is not available on this remote host')
@@ -974,10 +891,7 @@ export class PtyHandler {
       throw error
     }
 
-    // Why: capture the renderer-supplied paneKey on the managed entry so the
-    // exit listener can evict per-pane caches without the relay needing a
-    // separate ptyId→paneKey map. ORCA_PANE_KEY is shaped `${tabId}:${paneId}`
-    // and is bounded by the renderer; the relay treats it as opaque.
+    // Why: capture paneKey so the exit listener can evict per-pane caches without a separate ptyId→paneKey map.
     const tabId = typeof env?.ORCA_TAB_ID === 'string' ? env.ORCA_TAB_ID : undefined
     const attachIdentity = {
       paneKey: typeof params.paneKey === 'string' ? params.paneKey : paneKey,
@@ -1021,9 +935,7 @@ export class PtyHandler {
     }
     this.wireAndStore(managed)
     if (context?.isStale()) {
-      // Why: if the client reconnected while pty.spawn was in flight, the
-      // response is discarded and no renderer can own this PTY. Shut it down
-      // immediately so it does not linger as an unreachable remote shell.
+      // Why: a client reconnect mid-spawn discards the response, so no renderer can own this PTY — shut it down.
       this.releaseStartupCommand(managed)
       this.requestGracefulKill(managed, 'terminate stale')
     } else if (managed.startupCommand) {
@@ -1040,22 +952,12 @@ export class PtyHandler {
   private async attach(params: Record<string, unknown>): Promise<{ replay?: string }> {
     const id = params.id as string
     const managed = this.ptys.get(id)
-    // Why: treat a disposed managed entry the same as "not found" — after
-    // disposeManagedPty has run, managed.pty is torn down and any write/kill
-    // would hit a neutralized no-op on POSIX. The explicit check converts a
-    // silent failure into the existing error callers already handle.
+    // Why: after dispose, pty.kill is a POSIX no-op; treat disposed as not-found so failures aren't silent.
     if (!managed || managed.disposed) {
       throw new Error(`PTY "${id}" not found`)
     }
 
-    // Why: a reattach can arrive for a relay PTY whose backing shell already
-    // died without node-pty delivering onExit (e.g. the child was reaped out of
-    // band while the SSH channel was down). The map entry lingers, so attach
-    // would otherwise "succeed" with an empty replay and strand the reattached
-    // pane on a black, unresponsive shell. Prove liveness here; if the pid is
-    // provably gone, reap the stale entry and report not-found so the caller
-    // drops the dead lease and spawns fresh — the same recovery path an expired
-    // grace window already takes.
+    // Why: a shell can die without node-pty firing onExit (reaped out-of-band); prove liveness so attach doesn't strand a dead, lingering lease.
     if (managed.pty.pid && !isProcessAlive(managed.pty.pid)) {
       managed.physicalExit?.markExited()
       this.releaseRelayIngress(managed)
@@ -1067,14 +969,7 @@ export class PtyHandler {
       throw new Error(`PTY "${id}" not found`)
     }
 
-    // Why: PTY ids are a per-relay-process counter (pty-1, pty-2, …). When the
-    // relay changes generation — an app update deploys a new content-hashed
-    // relay dir, or a grace-expired relay restarts — the counter resets, so an
-    // old lease's `pty-N` can name a freshly spawned `pty-N` that belongs to a
-    // *different* pane. Attaching by id alone then wires a tab to the wrong
-    // shell. Reject when the caller's expected identity disagrees with this
-    // PTY's own so the client falls back to a fresh spawn. Absent identity on
-    // either side stays permissive for backward compatibility.
+    // Why: a relay generation reset can reuse pty-N for a different pane; reject on identity disagreement (absent identity permissive).
     const mismatch = attachIdentityMismatches(
       {
         paneKey: typeof params.expectedPaneKey === 'string' ? params.expectedPaneKey : undefined,
@@ -1088,19 +983,10 @@ export class PtyHandler {
 
     managed.startupIngress?.snapshotBarrier()
 
-    // Replay buffered output. During pty.spawn({ sessionId }) the renderer has
-    // not registered replay handlers yet, so return the bytes to the caller
-    // instead of notifying them too early.
-    // Why: the buffer is NOT cleared after replay. It always holds the last
-    // 100 KB of raw output (capped in onData). The client clears xterm before
-    // writing the replay, so returning the full buffer on every attach does
-    // not cause duplication. Keeping the buffer intact means a second app
-    // restart still replays the full terminal history instead of only output
-    // generated since the previous attach.
+    // Why: renderer hasn't registered replay handlers yet during spawn, so return to the caller instead of notifying too early.
+    // Why: buffer intentionally NOT cleared after replay (client clears xterm first) so later restarts still replay full history.
     if (managed.buffered) {
-      // Why: relay batching may still hold bytes that are already included in
-      // the full replay buffer. Drop that pending notification before attach
-      // so reconnect/suppressed replay cannot render the same bytes twice.
+      // Why: drop pending batched bytes already in the replay buffer so attach doesn't render them twice.
       this.pendingOutputByPty.delete(id)
       this.clearOutputFlushTimerIfIdle()
       if (params.suppressReplayNotification) {
@@ -1147,9 +1033,7 @@ export class PtyHandler {
       this.releaseStartupCommand(managed)
       this.flushPtyOutput(id)
       this.requestForceKill(managed)
-      // Why: remote Git deletion must not race native handles still owned by
-      // an uninterruptible child. Timeout rejects but deliberately keeps the
-      // map entry so a later onExit or retry retains the physical owner.
+      // Why: remote Git deletion must not race the child's native handles; on timeout keep the map entry so onExit/retry still owns it.
       await this.waitForPhysicalExit(managed, IMMEDIATE_PTY_EXIT_TIMEOUT_MS)
     } else {
       this.releaseStartupCommand(managed)
@@ -1164,9 +1048,7 @@ export class PtyHandler {
       throw new Error(`Signal not allowed: ${signal}`)
     }
     const managed = this.ptys.get(id)
-    // Why: POSIX disposeManagedPty neutralizes managed.pty.kill. Without the
-    // disposed check, a post-dispose sendSignal would silently succeed (no
-    // error, no action). Convert to the existing "not found" error.
+    // Why: dispose neutralizes pty.kill on POSIX; treat disposed as not-found so signals don't silently no-op.
     if (!managed || managed.disposed) {
       throw new Error(`PTY "${id}" not found`)
     }
@@ -1193,8 +1075,7 @@ export class PtyHandler {
     }
     managed.gracefulKillSent = true
     if (process.platform === 'win32') {
-      // Why: bare node-pty kill is already force-final on ConPTY, so no later
-      // fallback, immediate cleanup, or destroy may close the handle again.
+      // Why: ConPTY's bare kill is already force-final; block any later close of the handle.
       managed.forceKillSent = true
     }
     try {
@@ -1207,8 +1088,7 @@ export class PtyHandler {
     if (process.platform === 'win32') {
       return
     }
-    // Why: POSIX children may ignore SIGTERM; only onExit releases ownership
-    // after the bounded SIGKILL fallback.
+    // Why: POSIX children may ignore SIGTERM; arm a bounded SIGKILL fallback.
     this.armForceKillFallback(managed, fallbackAction, 5000, PTY_FORCE_KILL_MAX_ATTEMPTS)
   }
 
@@ -1230,8 +1110,7 @@ export class PtyHandler {
         process.stderr.write(
           `[pty-handler] failed to ${fallbackAction} PTY ${managed.id}: ${error instanceof Error ? error.message : String(error)}\n`
         )
-        // Why: a transient native SIGKILL failure must not strand an
-        // unreachable remote shell after the only cleanup owner returned.
+        // Why: a transient SIGKILL failure must not strand an unreachable remote shell.
         if (attemptsRemaining > 1 && this.ptys.get(still.id) === still && !still.disposed) {
           this.armForceKillFallback(
             still,
@@ -1379,10 +1258,7 @@ export class PtyHandler {
     if (!ptyMod) {
       return
     }
-    // Why: revive must apply the same hook env as spawn(). The hook-server
-    // coords come from augmenters, while pane identity comes from the
-    // serialized PTY entry because managed hook scripts exit without
-    // ORCA_PANE_KEY.
+    // Why: pane identity comes from the serialized entry (not env) since hook scripts exit without ORCA_PANE_KEY.
     const revivedEnv: Record<string, string> = {}
     if (entry.paneKey) {
       revivedEnv.ORCA_PANE_KEY = entry.paneKey
@@ -1403,8 +1279,7 @@ export class PtyHandler {
     if (explicitTerm !== undefined) {
       revivedEnv.TERM = explicitTerm
     }
-    // Why: serialized state can come from an older or untrusted client, so
-    // revive reapplies the same bounds as a fresh spawn before retaining it.
+    // Why: serialized state may come from an older/untrusted client; reapply fresh-spawn bounds.
     const envToDelete = sanitizeEnvToDelete(entry.envToDelete)
     const shell = resolveDefaultShell()
     const spawnEnv = this.buildSpawnEnv(
@@ -1412,8 +1287,7 @@ export class PtyHandler {
       { id: entry.id, paneKey: entry.paneKey, shell },
       envToDelete
     )
-    // Why: revive lacks the original launch command, so preserve the guard
-    // decision made at fresh spawn. Legacy state remains an ordinary shell.
+    // Why: revive lacks the original launch command, so reuse the fresh-spawn guard decision (legacy defaults to unguarded).
     const gitCredentialPromptGuarded = entry.gitCredentialPromptGuarded === true
     if (gitCredentialPromptGuarded) {
       Object.assign(spawnEnv, gitCredentialPromptGuardEnv(spawnEnv, process.platform))
@@ -1453,9 +1327,7 @@ export class PtyHandler {
     if (timeoutMs === 0) {
       return
     }
-    // Why: callers may shorten the first empty-detached startup window, but
-    // connected relays still use the configured grace so live PTYs can survive
-    // app restarts and reconnects.
+    // Why: connected relays keep the configured grace so live PTYs survive restarts/reconnects.
     this.graceTimer = setTimeout(() => {
       onExpire()
     }, timeoutMs)
@@ -1469,8 +1341,7 @@ export class PtyHandler {
   }
 
   dispose(options: { waitForPhysicalExit?: boolean } = {}): Promise<void> {
-    // Why: fence creation synchronously before the first await so a spawn or
-    // revive cannot appear after the disposal snapshot and escape process exit.
+    // Why: fence synchronously before the first await so a spawn/revive can't slip past disposal and escape exit.
     this.creationFenced = true
     if (this.disposePromise) {
       return this.disposePromise
@@ -1478,8 +1349,7 @@ export class PtyHandler {
     const disposePromise = this.disposePtys(options.waitForPhysicalExit !== false)
     this.disposePromise = disposePromise
     void disposePromise.catch(() => {
-      // Why: a rejected native kill retains ownership so a later shutdown
-      // signal can retry instead of joining a permanently rejected promise.
+      // Why: clear on rejected kill so a later shutdown can retry instead of joining a rejected promise.
       if (this.disposePromise === disposePromise) {
         this.disposePromise = null
       }
@@ -1524,15 +1394,13 @@ export class PtyHandler {
     }
     this.clearStartupCommandTimer(managed)
     this.releaseRelayIngress(managed)
-    // Why: relay exit must retain the native owner until SIGKILL is accepted
-    // (with one bounded retry) or onExit proves the process is already gone.
+    // Why: retain the native owner until SIGKILL is accepted (one bounded retry) or onExit proves it gone.
     await this.requestForceKillForRelayShutdown(managed)
     if (waitForPhysicalExit && this.ptys.get(managed.id) === managed && !managed.disposed) {
       try {
         await this.waitForPhysicalExit(managed, IMMEDIATE_PTY_EXIT_TIMEOUT_MS)
       } catch {
-        // An accepted SIGKILL is the bounded final boundary when a child is
-        // uninterruptible and cannot report exit before relay shutdown.
+        // An accepted SIGKILL is the final boundary when an uninterruptible child can't report exit.
       }
     }
     if (this.ptys.get(managed.id) === managed && !managed.disposed) {
diff --git a/src/relay/relay-handshake.ts b/src/relay/relay-handshake.ts
index fb64c57ec16..e021c392561 100644
--- a/src/relay/relay-handshake.ts
+++ b/src/relay/relay-handshake.ts
@@ -1,10 +1,4 @@
 // Wire-level handshake helpers for the Orca relay.
-//
-// Why this lives in its own module: oxlint enforces a 300-line limit (with
-// blanks/comments stripped) on .ts files, and relay.ts already runs near that
-// limit. Splitting the version-handshake plumbing into a sibling module keeps
-// relay.ts focused on the daemon-lifecycle wiring and makes the handshake
-// independently unit-testable.
 
 import { dirname, join } from 'node:path'
 import { existsSync, readFileSync, realpathSync } from 'node:fs'
@@ -19,21 +13,10 @@ import {
 } from './protocol'
 import { relayLogLine } from './relay-diagnostic-log'
 
-// Why: a unique exit code reserved for the wire-level version-mismatch terminal
-// condition. The client (waitForSentinel + ssh.ts) maps this exit code to a
-// non-retryable RelayVersionMismatchError so _onRelayLost skips the backoff
-// loop. Any other non-zero exit is treated as a transient transport error.
+// Why: client maps this exit code to a non-retryable error so it skips reconnect backoff; other non-zero exits are treated as transient.
 export const EXIT_CODE_VERSION_MISMATCH = 42
 
-// Why: the deploy step writes a content-hashed version marker (e.g.
-// "0.1.0+0a5fe134d020") into ${remoteDir}/.version next to relay.js. Read it
-// from the directory the running script lives in (NOT process.cwd()) so test
-// spawns from arbitrary working dirs still report a coherent version. We
-// resolve symlinks via realpathSync so a daemon launched indirectly (e.g.
-// `node /tmp/symlink-to-relay.js`) still finds .version next to the real
-// script. Falls back to bare RELAY_VERSION only if the file truly cannot be
-// read; the wire handshake then refuses a fresh content-hashed client and
-// the user gets a clean typed error rather than a silent stale-daemon loop.
+// Why: read .version next to the resolved script path (realpathSync, not cwd) so arbitrary-cwd or symlink-launched spawns still report a coherent version.
 export function readLaunchVersion(): string {
   try {
     const entry = process.argv[1]
@@ -65,21 +48,12 @@ export function readLaunchVersion(): string {
 // ── Daemon side ─────────────────────────────────────────────────────
 
 export type DaemonHandshakeCallbacks = {
-  // Why: leftover is any bytes the FrameDecoder buffered AFTER the handshake
-  // frame (e.g. the bridge wrote handshake + a JSON-RPC frame in the same
-  // TCP send). The caller MUST feed leftover into the dispatcher before
-  // attaching the new 'data' listener, otherwise those bytes are silently
-  // lost.
+  // leftover: bytes buffered after the handshake frame; caller must feed the dispatcher before attaching the data listener or they're lost.
   onAccepted: (sock: Socket, leftover: Buffer) => void
   launchVersion: string
 }
 
-// Why: pre-dispatcher version handshake. The daemon reads exactly one
-// Handshake-typed frame off this freshly-accepted socket BEFORE the JSON-RPC
-// dispatcher pipe is attached. Mismatch means the connecting bridge was
-// launched against a different relay.js version than the daemon was; we close
-// the socket so the bridge exits 42 and the client surfaces a typed error
-// instead of looping over the dispatcher.
+// Why: read one handshake frame before attaching the dispatcher; version mismatch closes the socket so the bridge exits 42.
 export function setupDaemonHandshake(sock: Socket, cb: DaemonHandshakeCallbacks): void {
   let handshakeResolved = false
   const decoder: FrameDecoder = new FrameDecoder(
@@ -168,22 +142,11 @@ function handleDaemonHandshakeFrame(
 // ── --connect side ──────────────────────────────────────────────────
 
 export type ConnectHandshakeCallbacks = {
-  // Why: leftover is any bytes the FrameDecoder buffered AFTER the
-  // handshake-ok frame. The caller MUST forward leftover to process.stdout
-  // (the SSH stdout pipe) before attaching the raw bridge, otherwise daemon
-  // bytes coalesced into the same TCP send as handshake-ok are silently
-  // dropped.
+  // leftover: bytes buffered after handshake-ok; caller must forward to stdout before attaching the bridge or they're dropped.
   onAccepted: (leftover: Buffer) => void
 }
 
-// Why: the wire-level version handshake from the bridge side. Before we attach
-// the bidirectional pipe (and before we write RELAY_SENTINEL to stdout to
-// unblock the client), we send a Handshake-typed frame carrying our version
-// and wait for the daemon's Handshake response. This is defense-in-depth on
-// top of the versioned-install-dir layout: a corrupt/missing .version, hash
-// collision, or legacy-fallback path would otherwise let a v2 bridge drive a
-// v1 daemon. VS Code's remoteExtensionHostAgentServer.ts:340 does the same
-// check.
+// Why: bridge-side version handshake; defense-in-depth so a bad .version can't let a v2 bridge drive a v1 daemon (cf. VS Code remoteExtensionHostAgentServer.ts:340).
 export function runConnectHandshake(
   sock: Socket,
   myVersion: string,
@@ -222,10 +185,7 @@ export function runConnectHandshake(
         return
       }
       if (msg.type === 'orca-relay-handshake-mismatch') {
-        // Why: explicit stderr flush + exit so the diagnostic line is
-        // delivered to the client BEFORE the process exits. Without this,
-        // process.stderr writes can be buffered/async on pipe transports
-        // and parseHandshakeMismatchStderr loses the version detail.
+        // Why: exit inside the write callback; stderr is async on pipe transports, so exiting early drops the version detail.
         process.stderr.write(
           `[relay-connect] Handshake mismatch: expected=${msg.expected}, daemon=${msg.got}; exiting ${EXIT_CODE_VERSION_MISMATCH}\n`,
           () => {
diff --git a/src/relay/relay.ts b/src/relay/relay.ts
index debef3b85e8..2e3c77bb4b3 100644
--- a/src/relay/relay.ts
+++ b/src/relay/relay.ts
@@ -1,23 +1,12 @@
 #!/usr/bin/env node
-/* oxlint-disable max-lines -- Why: the relay entry point centralizes process
-   lifecycle (stdio, --connect bridge, grace timer, signal handlers, socket
-   server) and handler registration in one file so the boot sequence stays in
-   topological order. Splitting by line count would scatter ordered side-
-   effects across modules and obscure the lifecycle. */
+/* oxlint-disable max-lines -- Why: the entry point keeps process lifecycle and handler registration in one file so the boot sequence stays in topological order. */
 
-/* eslint-disable max-lines -- Why: the relay entrypoint owns process startup,
-   daemon reconnect, and handler registration. Splitting the orchestration
-   would hide the startup order, which is the important invariant here. */
+/* eslint-disable max-lines -- Why: splitting the entrypoint's startup/reconnect/registration would hide the startup order, the key invariant here. */
 
-// Orca Relay — lightweight daemon deployed to remote hosts.
+// Orca Relay — lightweight daemon deployed to remote hosts over SCP and launched via an SSH exec channel.
 // Communicates over stdin/stdout using the framed JSON-RPC protocol.
-// The Electron app (client) deploys this script via SCP and launches
-// it via an SSH exec channel.
-//
-// On client disconnect the relay enters a grace period, keeping PTYs
-// alive and listening on a Unix domain socket. A subsequent app launch
-// can reconnect by running relay.js --connect, which bridges the new
-// SSH channel's stdin/stdout to the existing relay's socket.
+// On client disconnect it enters a grace period, keeping PTYs alive on a Unix domain socket; a later launch
+// reconnects via `relay.js --connect`, bridging the new SSH channel's stdio to the existing relay's socket.
 
 import { createServer, createConnection, type Socket, type Server } from 'node:net'
 import { homedir } from 'node:os'
@@ -127,9 +116,7 @@ function parseArgs(argv: string[]): {
   for (let i = 2; i < argv.length; i++) {
     if (argv[i] === '--grace-time' && argv[i + 1]) {
       const parsed = Number.parseInt(argv[i + 1], 10)
-      // Why: the CLI flag is in seconds for ergonomics, but internally we track
-      // ms. 0 is allowed for opt-in synced workspaces that intentionally keep a
-      // relay alive until explicitly terminated.
+      // Why: flag is seconds (internally ms); 0 keeps the relay alive until explicitly terminated for synced workspaces.
       if (!Number.isNaN(parsed) && parsed >= 0) {
         graceTimeMs = parsed * 1000
       }
@@ -158,11 +145,7 @@ function parseArgs(argv: string[]): {
 }
 
 // ── Connect mode ─────────────────────────────────────────────────────
-// Why: after an app restart, a new SSH exec channel is established but
-// the original relay (with live PTYs) is still running in its grace
-// period.  --connect bridges the new channel's stdin/stdout to the
-// existing relay's Unix socket so the client talks to the SAME process
-// that owns the PTY sessions.
+// Why: --connect bridges a new SSH channel's stdin/stdout to the existing relay's socket so the client keeps talking to the process that owns the live PTYs.
 
 function runConnectMode(sockPath: string): void {
   const myVersion = readLaunchVersion()
@@ -178,18 +161,9 @@ function runConnectMode(sockPath: string): void {
     clearTimeout(connectTimeout)
     runConnectHandshake(sock, myVersion, {
       onAccepted: (leftover: Buffer) => {
-        // Why: RELAY_SENTINEL must be written AFTER the handshake passes; if it
-        // were written earlier, waitForSentinel on the client would resolve
-        // and start sending JSON-RPC over a socket the daemon was about to
-        // close on mismatch — surfacing as a generic channel drop and
-        // re-entering the backoff loop. Sequencing it post-handshake makes
-        // mismatch a clean exit-42 path with no false-positive sentinel.
+        // Why: write RELAY_SENTINEL only after the handshake passes, so a version mismatch is a clean exit-42 instead of a false sentinel + channel drop.
         process.stdout.write(RELAY_SENTINEL)
-        // Why: bytes that arrived in the same TCP send as the handshake-ok
-        // frame were buffered inside the handshake's FrameDecoder. Forward
-        // them to stdout BEFORE attaching sock.pipe(process.stdout), so the
-        // multiplexer downstream sees them in order and no daemon frames
-        // are silently dropped at the transition.
+        // Why: forward handshake-buffered leftover bytes before sock.pipe(process.stdout) so the downstream mux sees them in order.
         if (leftover.length > 0) {
           process.stdout.write(leftover)
         }
@@ -199,13 +173,7 @@ function runConnectMode(sockPath: string): void {
     })
   })
 
-  // Why: when the SSH channel closes, stdout becomes a broken pipe.
-  // Node.js silently swallows EPIPE on process.stdout, so the bridge
-  // stays alive as a zombie — connected to the relay socket but unable
-  // to forward data. The relay keeps writing to this dead bridge,
-  // silently dropping pty.data frames until the next --connect replaces
-  // the socket. Exiting immediately on stdout error lets the relay
-  // detect the disconnect (socket close) and enter grace mode promptly.
+  // Why: Node swallows EPIPE on stdout, so the bridge would zombie and drop frames; exit on stdout error so the relay enters grace promptly.
   process.stdout.on('error', () => {
     sock.destroy()
     process.exit(1)
@@ -338,9 +306,7 @@ async function main(): Promise<void> {
     return
   }
 
-  // Why: only the long-lived detached daemon accumulates relay.log; --connect
-  // bridges and --orca-cli are short-lived and already returned above. Route all
-  // relay logging through a size-capped rotator so relay.log can't grow forever.
+  // Why: only the long-lived detached daemon accumulates relay.log; route it through a size-capped rotator so it can't grow forever.
   if (detached && logFile) {
     installRelayLogRotation(logFile)
   }
@@ -367,10 +333,7 @@ async function main(): Promise<void> {
     ownedSocketIdentity = null
   }
 
-  // Why: After an uncaught exception Node's internal state may be corrupted
-  // (e.g. half-written buffers, broken invariants). Logging and continuing
-  // would risk silent data corruption or zombie PTYs. We log for diagnostics
-  // and then exit so the client can detect the disconnect and reconnect cleanly.
+  // Why: after an uncaught exception Node's state may be corrupted; log and exit rather than risk data corruption or zombie PTYs.
   process.on('uncaughtException', (err) => {
     relayLogLine(`[relay] Uncaught exception: ${err.message}\n${err.stack}`)
     cleanupOwnedSocket()
@@ -381,16 +344,9 @@ async function main(): Promise<void> {
     relayLogLine(`[relay] Unhandled rejection: ${reason}`)
   })
 
-  // Why: stdoutAlive tracks whether process.stdout is still writable.
-  // After stdin ends (SSH channel dropped), the stdout pipe goes dead.
-  // Without this guard, keepalive frames and pty.data notifications would
-  // write to a dead pipe, silently failing or throwing EPIPE.  When a
-  // socket client reconnects, setWrite swaps the callback to the socket.
+  // Why: guards writes after the stdin/SSH channel drops so keepalive/pty.data frames don't hit a dead pipe (EPIPE).
   let stdoutAlive = true
-  // Why: one-shot waiters parked by the dispatcher's bulk lane when stdout
-  // reports saturation (write() === false). Flushed on 'drain' and on every
-  // stdout-death path so a stalled file-stream pump never outlives the pipe
-  // it was waiting on.
+  // Why: one-shot waiters parked when stdout saturates (write() === false); flushed on 'drain' and every stdout-death path.
   const stdoutDrainWaiters = new Set<() => void>()
   const flushStdoutDrainWaiters = (): void => {
     for (const cb of Array.from(stdoutDrainWaiters)) {
@@ -405,9 +361,7 @@ async function main(): Promise<void> {
         return
       }
       try {
-        // Why: surface Node's backpressure signal to the dispatcher so bulk
-        // frames (fs.streamChunk) wait for drain instead of queueing megabytes
-        // ahead of interactive pty.data frames on the SSH channel.
+        // Why: surface Node's backpressure so bulk frames (fs.streamChunk) wait for drain instead of queueing ahead of interactive pty.data.
         return process.stdout.write(data)
       } catch {
         stdoutAlive = false
@@ -428,13 +382,7 @@ async function main(): Promise<void> {
 
   const context = new RelayContext()
 
-  // Why: session.registerRoot is now a protocol-level no-op (the relay no
-  // longer enforces a workspace allowlist; see docs/relay-fs-allowlist-removal.md).
-  // Both notification and request handlers are retained so a new main
-  // connecting to a new relay during the upgrade window — and an old main
-  // connecting to a new relay — both keep working without "Method not found"
-  // errors. Tracked for removal once the relay-version floor moves past the
-  // cutover.
+  // Why: registerRoot is a no-op now (allowlist removed, docs/relay-fs-allowlist-removal.md); both handlers kept for version-skew compat until the version floor moves.
   dispatcher.onNotification('session.registerRoot', (params) => {
     const rootPath = params.rootPath as string
     if (rootPath) {
@@ -450,10 +398,7 @@ async function main(): Promise<void> {
     return { ok: true }
   })
 
-  // Why: the client stores repo paths as-is from user input, but `~` is a
-  // shell expansion — Node's fs APIs don't understand it. This handler lets
-  // the client resolve tilde paths to absolute paths on the remote host
-  // before persisting them, so all downstream fs operations work correctly.
+  // Why: `~` is a shell expansion Node's fs APIs don't understand; resolve it to an absolute path on the remote host before persisting.
   dispatcher.onRequest('session.resolveHome', async (params) => {
     const inputPath = params.path as string
     if (inputPath === '~' || inputPath === '~/') {
@@ -496,8 +441,7 @@ async function main(): Promise<void> {
   function configureRelayGraceTime(params: Record<string, unknown>): { graceTimeMs: number } {
     const seconds = Number(params.graceTimeSeconds)
     if (Number.isFinite(seconds) && seconds >= 0) {
-      // Why: the host sends 0 before system sleep so live remote PTYs survive
-      // longer than the ordinary disconnect grace window.
+      // Why: the host sends 0 before system sleep so live remote PTYs survive longer than the ordinary grace window.
       ptyHandler.setGraceTimeMs(Math.floor(seconds) * 1000)
     }
     return { graceTimeMs: ptyHandler.configuredGraceTimeMs }
@@ -511,35 +455,19 @@ async function main(): Promise<void> {
   )
 
   // ── Agent-hook server ─────────────────────────────────────────────
-  // Why: hosts a loopback HTTP receiver inside the relay process so agent
-  // CLIs running in remote PTYs can post hook events without leaving the
-  // host. Each parsed payload is forwarded to Orca via an `agent.hook`
-  // JSON-RPC notification on the existing SSH channel — see
-  // docs/design/agent-status-over-ssh.md §2-§5.
+  // Why: loopback HTTP receiver so remote-PTY agent CLIs post hook events locally, forwarded to Orca as agent.hook notifications. See docs/design/agent-status-over-ssh.md §2-§5.
   const hookServer = new RelayAgentHookServer({
-    // Why: a remote account can host multiple target-specific relay daemons.
-    // Scope endpoint.env/cmd by the daemon socket path so their hook tokens
-    // cannot overwrite each other.
+    // Why: scope endpoint.env/cmd by socket path so multiple relay daemons on one account can't overwrite each other's hook tokens.
     endpointDir: endpointDir ?? endpointDirForRelaySocket(sockPath),
     forward: (envelope) => {
-      // Why: dispatcher.notify is fire-and-forget — when the SSH channel is
-      // mid-reconnect the write callback no-ops and the notification is
-      // silently dropped. The per-paneKey cache inside `hookServer` lets us
-      // replay the last status for each live pane after Orca re-wires its
-      // handler post-`--connect`.
+      // Why: notify is fire-and-forget and drops during reconnect; the per-paneKey cache lets us replay last status after --connect.
       dispatcher.notify(
         AGENT_HOOK_NOTIFICATION_METHOD,
         envelope as unknown as Record<string, unknown>
       )
     }
   })
-  // Why: await the hook-server bind before announcing readiness so the very
-  // first PTY spawn (which can land within milliseconds of the sentinel)
-  // already sees populated ORCA_AGENT_HOOK_* env. The bind is a local-loopback
-  // listen — measured in ms — so the latency cost is trivial and removes a
-  // class of "first agent invocation has no status" races. Bind failure is
-  // treated as soft: log and continue, the augmenter returns {} and agent
-  // status simply does not flow.
+  // Why: await the bind before announcing readiness so the first PTY spawn already sees ORCA_AGENT_HOOK_* env; bind failure is soft (log and continue).
   try {
     await hookServer.start({ publishEndpoint: false })
   } catch (err) {
@@ -548,22 +476,14 @@ async function main(): Promise<void> {
     )
   }
 
-  // Why: every relay-spawned PTY needs the live ORCA_AGENT_HOOK_* coords. The
-  // augmenter is read on every spawn so a hook-server bind that succeeded
-  // late (or after a stop/start) lands in the next PTY's env without a
-  // restart.
+  // Why: read the augmenter on every spawn so a late (or restarted) hook-server bind still lands in the next PTY's ORCA_AGENT_HOOK_* env.
   ptyHandler.addEnvAugmenter(() => hookServer.buildPtyEnv())
 
-  // Why: plugin install paths must be resolved on the relay host. OpenCode
-  // still needs a relay-local config overlay, while Pi/OMP receive guarded
-  // status extensions in their real remote agent dirs.
+  // Why: plugin paths resolve on the relay host — OpenCode gets a relay-local overlay; Pi/OMP get extensions in their real remote dirs.
   const pluginOverlay = new PluginOverlayManager()
   ptyHandler.addEnvAugmenter((ctx) => {
     const env: Record<string, string> = {}
-    // Why: prefer paneKey for overlay identity so a renderer-side remount
-    // that reuses the paneKey lands in the same overlay dir. Falls back to
-    // the relay-internal pty-id when paneKey is absent (e.g. CLI-launched
-    // PTYs that don't go through the renderer).
+    // Why: prefer paneKey for overlay identity so a renderer remount reusing it lands in the same dir; fall back to pty-id when absent.
     const overlayId = ctx.paneKey ?? ctx.id
     if (pluginOverlay.hasOpenCodeSource()) {
       const sourceDir = resolveOpenCodeSourceConfigDir(ctx.env, ctx.shell)
@@ -577,9 +497,7 @@ async function main(): Promise<void> {
       }
     }
     if (pluginOverlay.hasPiSource()) {
-      // Why: source-dir defaulting is keyed on which Pi-compatible agent is
-      // being launched (Pi vs OMP). Install Orca's guarded extension into that
-      // real remote agent dir without redirecting PI_CODING_AGENT_DIR.
+      // Why: install Orca's guarded extension into the launched agent's (Pi vs OMP) real remote dir without redirecting PI_CODING_AGENT_DIR.
       const launchCommandHint = resolveSetupAgentSequenceLaunchCommand(ctx.env, ctx.command)
       const kind = detectPiAgentKindFromCommand(launchCommandHint)
       const hasLaunchCommand =
@@ -593,8 +511,7 @@ async function main(): Promise<void> {
         }
       }
       if (shouldPrepareOmpShadow) {
-        // Why: in a bare shell, prepare OMP's status extension so a typed
-        // `omp` gets integration, but do not make OMP the shell's home.
+        // Why: prepare OMP's status extension for a bare shell so a typed `omp` gets integration, without making OMP the shell's home.
         const sourceDir =
           kind === 'omp'
             ? resolvePiSourceAgentDir(ctx.env, ctx.shell, 'omp')
@@ -609,10 +526,7 @@ async function main(): Promise<void> {
     return env
   })
 
-  // Why: evict the per-pane last-status cache AND any plugin overlay dirs
-  // when the backing PTY exits so terminated panes do not (a) resurface as
-  // ghost events after a later reconnect (§5 Path 3) or (b) leak overlay
-  // dirs on a long-lived relay.
+  // Why: evict pane status cache + overlay dirs on PTY exit so panes don't ghost after reconnect (§5 Path 3) or leak dirs.
   ptyHandler.setExitListener(({ paneKey, id }) => {
     if (paneKey) {
       hookServer.clearPaneState(paneKey)
@@ -620,27 +534,14 @@ async function main(): Promise<void> {
     pluginOverlay.clearOverlay(paneKey ?? id)
   })
 
-  // Why: request-driven replay. Orca issues this *after* it re-wires the
-  // `agent.hook` filter on the new mux post-`--connect`. We forward each
-  // cached entry as a fresh notification BEFORE returning so the response
-  // strictly trails all replays on the dispatcher's single write callback —
-  // closing the race the push-on-`setWrite` shape would have lost. See
-  // docs/design/agent-status-over-ssh.md §5 Path 3.
+  // Why: forward cached entries as notifications before returning so the response trails all replays, closing a reconnect race. See docs/design/agent-status-over-ssh.md §5 Path 3.
   dispatcher.onRequest(AGENT_HOOK_REQUEST_REPLAY_METHOD, async () => {
     const replayed = hookServer.replayCachedPayloadsForPanes()
     return { replayed }
   })
 
-  // Why: Orca ships the OpenCode plugin / Pi extension source bodies over
-  // the wire at session-ready (the renderer's bundled hook-service strings
-  // change as new agent events are added — pinning them to the relay binary
-  // would force a relay redeploy on every Orca update). Cache them so each
-  // subsequent PTY spawn can materialize the remote OpenCode overlay and
-  // install Pi/OMP managed extensions. See docs/design/agent-status-over-ssh.md §4.
-  // Why: bound the per-source size so a buggy/hostile Orca can't OOM the
-  // relay by pushing a giant string. The HTTP path has HOOK_REQUEST_MAX_BYTES
-  // = 1 MB; the JSON-RPC path needs an equivalent ceiling. Real plugin sources
-  // are <50 KB today; 256 KB leaves generous headroom.
+  // Why: plugin sources ship over the wire so an Orca update doesn't force a relay redeploy; cache them per spawn. See docs/design/agent-status-over-ssh.md §4.
+  // Why: bound per-source size so a buggy/hostile Orca can't OOM the relay by pushing a giant string.
   dispatcher.onRequest(AGENT_HOOK_INSTALL_PLUGINS_METHOD, async (params) => {
     const opencode = params.opencodePluginSource
     const pi = params.piExtensionSource
@@ -663,10 +564,7 @@ async function main(): Promise<void> {
   })
 
   // ── Socket server for reconnection ──────────────────────────────────
-  // Why: the relay's original stdin/stdout is tied to the SSH exec channel.
-  // When the app restarts that channel is gone.  A Unix domain socket lets
-  // a new --connect bridge pipe data to the same dispatcher that owns the
-  // live PTYs — no serialization or process handoff needed.
+  // Why: the SSH channel dies on app restart; a Unix socket lets a new --connect bridge reach the dispatcher that owns live PTYs.
 
   const socketClients = new Map<Socket, number>()
   let socketServer: Server | null = null
@@ -710,9 +608,7 @@ async function main(): Promise<void> {
   }
 
   function attachAcceptedSocket(sock: Socket, leftover: Buffer): void {
-    // Why: stdin's data listener is still registered from the initial connection.
-    // Pause/remove it once the first socket client is accepted so stale bytes
-    // from the original SSH channel cannot interleave with socket frames.
+    // Why: remove the initial stdin data listener once a socket client is accepted, so stale SSH-channel bytes can't interleave.
     process.stdin.pause()
     process.stdin.removeAllListeners('data')
 
@@ -723,8 +619,7 @@ async function main(): Promise<void> {
     )
     cancelGrace('socket client accepted')
 
-    // Why: same backpressure surface as the stdout sink — bulk frames wait
-    // for the socket to drain so they cannot bury interactive PTY frames.
+    // Why: same backpressure surface as stdout — bulk frames wait for socket drain so they can't bury interactive PTY frames.
     const sockDrainWaiters = new Set<() => void>()
     const flushSockDrainWaiters = (): void => {
       for (const cb of Array.from(sockDrainWaiters)) {
@@ -754,10 +649,7 @@ async function main(): Promise<void> {
     )
     socketClients.set(sock, clientId)
 
-    // Why: bytes that arrived in the same TCP send as the handshake frame
-    // were buffered inside the handshake's FrameDecoder. Feed them into the
-    // dispatcher BEFORE wiring sock.on('data'), so frame ordering is
-    // preserved and no client data is silently dropped at the transition.
+    // Why: feed handshake-buffered leftover bytes before wiring sock.on('data') so frame ordering is preserved.
     if (leftover.length > 0) {
       dispatcher.feedClient(clientId, leftover)
     }
@@ -773,9 +665,7 @@ async function main(): Promise<void> {
       // Why: pre-dispatcher version handshake — see relay-handshake.ts.
       setupDaemonHandshake(sock, { launchVersion, onAccepted: attachAcceptedSocket })
 
-      // Why: when --connect's SSH channel dies, stdin.pipe(sock) calls
-      // sock.end(), sending FIN to the relay. Destroying on 'end' ensures
-      // the 'close' handler fires promptly so the daemon can enter grace.
+      // Why: destroy on 'end' (FIN from --connect's dying channel) so the 'close' handler fires promptly and the daemon enters grace.
       sock.on('end', () => {
         if (!sock.destroyed) {
           sock.destroy()
@@ -783,8 +673,7 @@ async function main(): Promise<void> {
       })
 
       sock.on('error', () => {
-        // Why: Node emits 'error' then 'close'. The close handler owns
-        // activeSocket cleanup and grace startup.
+        // Why: Node emits 'error' then 'close'; the close handler owns cleanup and grace startup.
       })
 
       sock.on('close', () => {
@@ -800,10 +689,7 @@ async function main(): Promise<void> {
       })
     })
 
-    // Why: setting umask to 0o177 BEFORE listen ensures the socket is
-    // created with 0o600 permissions atomically. The previous approach
-    // (chmod after listen) had a TOCTOU window where another local user
-    // could connect to the socket before chmod ran.
+    // Why: umask 0o177 before listen makes the socket 0o600 atomically, closing the chmod-after-listen TOCTOU window.
     const shouldSetSocketUmask = !isWindowsNamedPipePath(sockPath)
     const prevUmask = shouldSetSocketUmask ? process.umask(0o177) : 0
     let umaskRestored = false
@@ -871,12 +757,7 @@ async function main(): Promise<void> {
         }
       }
 
-      // Why: a previous relay killed by SIGKILL/OOM/host-crash leaves the
-      // socket file on disk with no listener. EADDRINUSE on bind in that
-      // case is not "duplicate active" — it is a stale inode. Probe with a
-      // short connect; if it refuses, the socket is dead and we may unlink
-      // and retry once. If it connects, a live relay owns it and we keep
-      // the existing "duplicate detected" rejection.
+      // Why: EADDRINUSE may be a stale socket from a crashed relay, not a live one; probe-connect to tell them apart before unlinking.
       function onInitialError(err: NodeJS.ErrnoException): void {
         if (err.code !== 'EADDRINUSE' || staleRetryAttempted) {
           failInitial(err)
@@ -938,9 +819,7 @@ async function main(): Promise<void> {
 
   try {
     socketServer = await startSocketServer()
-    // Why: endpoint.env is shared by PTYs under this relay socket path. Publish
-    // it only after socket ownership is proven so a refused duplicate daemon
-    // cannot poison the active relay's hook coordinates.
+    // Why: publish endpoint.env only after socket ownership is proven, so a refused duplicate daemon can't poison hook coordinates.
     hookServer.publishEndpointFile()
   } catch {
     process.exit(1)
@@ -948,10 +827,7 @@ async function main(): Promise<void> {
 
   // ── stdin/stdout transport (initial connection) ─────────────────────
 
-  // Why: when the SSH channel closes, writing to stdout can emit an
-  // 'error' event (EPIPE/ERR_STREAM_DESTROYED). Without a handler,
-  // Node treats it as an uncaught exception and the process exits
-  // before the grace period starts.
+  // Why: without this handler an EPIPE/ERR_STREAM_DESTROYED on stdout becomes an uncaught exception, exiting before grace starts.
   process.stdout.on('error', () => {
     stdoutAlive = false
     flushStdoutDrainWaiters()
@@ -961,8 +837,7 @@ async function main(): Promise<void> {
   function startGrace(reason: string): void {
     const startupEmptyDetached =
       detached && !hasAcceptedSocketClient && ptyHandler.activePtyCount === 0
-    // Why: "until reset" preserves real PTYs, but a detached relay that never
-    // accepted a client has no terminal state and should not linger forever.
+    // Why: a detached relay that never accepted a client has no PTY state and shouldn't linger forever.
     const timeoutMs = startupEmptyDetached
       ? graceTimeMs === 0
         ? EMPTY_DETACHED_STARTUP_GRACE_MS
@@ -980,12 +855,7 @@ async function main(): Promise<void> {
   }
 
   if (detached) {
-    // Why: in detached mode the relay is backgrounded (nohup ... &) so
-    // stdin is /dev/null and stdout goes to a log file.  Listening on
-    // stdin would trigger an immediate EOF → grace → shutdown before any
-    // --connect client arrives.  Instead we mark stdout dead (no direct
-    // pipe), start the grace timer (socket connect will cancel it), and
-    // rely entirely on the Unix socket for client communication.
+    // Why: detached stdin is /dev/null, so listening would EOF → grace → shutdown before --connect arrives; use the socket instead.
     stdoutAlive = false
     startGrace('detached startup')
   } else {
@@ -995,10 +865,7 @@ async function main(): Promise<void> {
     })
 
     process.stdin.on('end', () => {
-      // Why: stdout is piped to the SSH channel — once stdin closes the
-      // channel is gone and stdout writes would hit a dead pipe.  Mark it
-      // dead so the primary client write callback becomes a no-op while
-      // socket clients, if any, keep their own live transports.
+      // Why: stdin close means the SSH channel is gone; mark stdout dead so its write callback no-ops instead of hitting a dead pipe.
       stdoutAlive = false
       flushStdoutDrainWaiters()
       dispatcher.invalidateClient()
@@ -1035,9 +902,7 @@ async function main(): Promise<void> {
         fsHandler.dispose()
         gitHandler.dispose()
         hookServer.stop()
-        // Why: Node's Unix server.close() can unlink the listen path. If the path
-        // was externally removed and rebound by a newer relay, closing this older
-        // server would strand the newer daemon behind a missing socket.
+        // Why: server.close() unlinks the listen path; skip if a newer relay rebound it, else we strand that newer daemon.
         if (socketServer && ownsCurrentSocketPath()) {
           socketServer.close()
         }
@@ -1045,8 +910,7 @@ async function main(): Promise<void> {
         process.exit(0)
       })
       .catch((error) => {
-        // Why: keep owning a PTY whose native kill was rejected; exiting here
-        // would turn a transient signal failure into an orphan remote shell.
+        // Why: keep owning a PTY whose native kill was rejected so a transient signal failure doesn't orphan a remote shell.
         shutdownInFlight = false
         relayLogLine(
           `[relay] Shutdown deferred: ${error instanceof Error ? error.message : String(error)}`
@@ -1056,12 +920,7 @@ async function main(): Promise<void> {
 
   process.on('SIGTERM', shutdown)
   process.on('SIGINT', shutdown)
-  // Why: when the SSH session drops, the OS sends SIGHUP to the relay's
-  // process group. Node's default SIGHUP behavior is to exit immediately,
-  // which kills all PTYs before the grace period can start. Ignoring
-  // SIGHUP lets the relay survive the SSH disconnect and enter its grace
-  // window — a reconnecting client can then bridge to the live relay via
-  // --connect and reattach to the still-running PTY sessions.
+  // Why: default SIGHUP exits immediately, killing PTYs before grace; ignore it so the relay survives SSH disconnect.
   process.on('SIGHUP', () => {
     relayLogLine('[relay] Received SIGHUP (SSH session dropped), ignoring')
   })
@@ -1069,8 +928,7 @@ async function main(): Promise<void> {
     relayLogLine(`[relay] Process exiting with code ${code}`)
   })
 
-  // Signal readiness to the client — the client watches for this exact
-  // string before sending framed data.
+  // Why: the client waits for this exact sentinel string before sending framed data.
   process.stdout.write(RELAY_SENTINEL)
 }
 
diff --git a/src/shared/agent-hook-listener.ts b/src/shared/agent-hook-listener.ts
index f983d409e79..0f27caafa62 100644
--- a/src/shared/agent-hook-listener.ts
+++ b/src/shared/agent-hook-listener.ts
@@ -1,15 +1,6 @@
-/* eslint-disable max-lines -- Why: this module is the canonical, transport-
-   agnostic agent-hook listener. The HTTP request parser, payload normalizer,
-   per-CLI extractors, and on-disk endpoint-file writer all share invariants
-   (size caps, warn-once Sets, shell-safe value rules) that must not drift
-   between Orca's main process and the relay. Splitting by line count would
-   force the same invariants to be re-derived in two places. */
+/* eslint-disable max-lines -- Why: canonical transport-agnostic listener; parser, normalizer, per-CLI extractors, and endpoint writer share invariants that must not drift between Orca's main process and the relay. */
 
-// Why: extracted from `src/main/agent-hooks/server.ts` so the relay can host
-// the same listener pipeline on the remote without dragging Electron in. The
-// module uses only Node builtins (http/fs/crypto/net/path/url/os) — none of
-// which pull `electron` — so it is safe to import from `src/relay/`. See
-// docs/design/agent-status-over-ssh.md §3 ("relay normalizes; Orca routes").
+// Why: extracted from src/main/agent-hooks/server.ts so the relay can host the pipeline without Electron (Node builtins only). See docs/design/agent-status-over-ssh.md §3.
 import type { IncomingMessage } from 'node:http'
 import { createHash, randomUUID } from 'node:crypto'
 import { homedir } from 'node:os'
@@ -67,19 +58,13 @@ import {
 /** Maximum request body size accepted by the listener (1 MB). */
 export const HOOK_REQUEST_MAX_BYTES = 1_000_000
 
-/** Bound the warn-once Sets so a buggy/malicious local client that varies its
- *  `version` / `env` fields per request cannot grow them without bound for the
- *  process lifetime. */
+/** Bound the warn-once Sets so a client varying `version`/`env` per request can't grow them unbounded. */
 const MAX_WARNED_KEYS = 32
 
 /** Slowloris cap: drop requests that have not finished sending after 5 s. */
 export const HOOK_REQUEST_SLOWLORIS_MS = 5_000
 
-/** Why: OpenCode plugin builds installed before the throttle/cap fix re-post
- *  the full accumulated reply text on every streamed part update (O(n²) bytes
- *  per turn). Capping at ingest bounds the per-event cost of the status
- *  compare, IPC fanout, renderer store update, and disk persist regardless of
- *  which plugin version is running inside the OpenCode process. */
+/** Why: old OpenCode plugin builds re-post the full accumulated reply on every streamed part (O(n²) bytes/turn); cap at ingest to bound per-event cost. */
 export const OPENCODE_HOOK_TEXT_MAX_CHARS = 8_000
 
 function capOpenCodeHookText(text: string): string {
@@ -88,15 +73,10 @@ function capOpenCodeHookText(text: string): string {
     : text
 }
 
-/** Bound paneKey size — `${tabId}:${leafUuid}` is well under 200 chars in
- *  practice; cap defends per-pane caches against pathological input.
- *  Exported so non-HTTP ingest paths (e.g. Orca's `ingestRemote`) can apply
- *  the same cap as defense-in-depth. */
+/** Bound paneKey size (real keys are well under 200); caps per-pane caches against pathological input. Exported so non-HTTP ingest (`ingestRemote`) applies the same cap as defense-in-depth. */
 export const MAX_PANE_KEY_LEN = 200
 
-/** Per-listener-instance state that holds caches needing per-PTY teardown
- *  (last prompt, last tool snapshot, last status replay). Both Orca's main
- *  process and the relay get their own instance — they never share. */
+/** Per-listener-instance caches needing per-PTY teardown; Orca's main process and the relay each get their own, never shared. */
 export type HookListenerState = {
   warnedVersions: Set<string>
   warnedEnvs: Set<string>
@@ -105,29 +85,18 @@ export type HookListenerState = {
   lastStatusByPaneKey: Map<string, AgentHookEventPayload>
   antigravityCompletedTranscriptByPaneKey: Map<string, string>
   ampCompletedCacheKeys: Set<string>
-  /** Live subagents/teammates per Claude pane. Survives turn boundaries —
-   *  background children outlive the lead turn that spawned them. */
+  /** Live subagents/teammates per Claude pane; survives turn boundaries since background children outlive the lead turn. */
   claudeSubagentRosterByPaneKey: Map<string, ClaudeSubagentRoster>
-  /** Last state derived from the LEAD session's own events (subagent-origin
-   *  events carry `agent_id` and are excluded). Needed so a SubagentStop can
-   *  re-emit the pane status without inventing a lead state. `interrupted`
-   *  persists here because a gated 'working' emit clamps the flag away, and
-   *  the eventual done (when the last child drains) must still carry it. */
+  /** Last state from the LEAD session's own events (subagent events carry agent_id, excluded), so a SubagentStop can re-emit pane status; `interrupted` persists so the eventual done still carries it. */
   claudeLeadStateByPaneKey: Map<string, ClaudeLeadTurnState>
 }
 
 export type ClaudeLeadTurnState = {
   state: AgentStatusState
   interrupted?: true
-  /** Set when the waiting state was induced by a subagent's PermissionRequest
-   *  or AskUserQuestion (those payloads carry `agent_id`). Only that agent's
-   *  next tool activity may clear the wait — other children's churn must not
-   *  dismiss a pending human-input card. */
+  /** Subagent that induced the wait; only its next tool activity may clear it, so other children's churn can't dismiss a pending human-input card. */
   waitingAgentId?: string
-  /** The lead state a child-induced wait displaced. Restored when the wait
-   *  clears — the lead may have already finished its turn, and inventing
-   *  'working' would leave the pane spinning after the roster drains (the
-   *  done-gate only ever downgrades done → working, never back). */
+  /** Lead state a child-induced wait displaced, restored when the wait clears; can't invent 'working' since the done-gate only downgrades done→working, never back. */
   stateBeforeWait?: Pick<ClaudeLeadTurnState, 'state' | 'interrupted'>
 }
 
@@ -235,12 +204,7 @@ export function clearAllListenerCaches(state: HookListenerState): void {
   state.claudeLeadStateByPaneKey.clear()
 }
 
-/** Emit warn-once diagnostics for cross-build (`version`) and dev-vs-prod
- *  (`env`) mismatches. Shared between the local HTTP path
- *  (`normalizeHookPayload`) and the relay-forwarded path
- *  (`AgentHookServer.ingestRemote`) so a remote-sourced event triggers the
- *  same diagnostic noise as a local one. The relay's "remote" marker is a
- *  location tag, not a build env, so it must not look like stale local hooks. */
+/** Warn-once on cross-build (`version`) and dev-vs-prod (`env`) mismatches; the relay's "remote" env marker is a location tag, not a build env, so it must not warn as a stale local hook. */
 export function warnOnHookEnvOrVersionMismatch(
   state: HookListenerState,
   fields: { version?: string; env?: string; expectedEnv: string }
@@ -276,16 +240,11 @@ export type AgentHookEventPayload = {
   launchToken?: string
   tabId?: string
   worktreeId?: string
-  /** Identifies the SSH connection the event arrived on, or null for local.
-   *  Stamped only on the remote-ingest path (Orca's `ingestRemote`); the
-   *  HTTP path always sets null because it cannot know which mux a request
-   *  came from. See docs/design/agent-status-over-ssh.md §5. */
+  /** SSH connection the event arrived on, or null for local (only ingestRemote stamps it; the HTTP path can't know the mux). See docs/design/agent-status-over-ssh.md §5. */
   connectionId: string | null
-  /** True when this hook event carried prompt text directly, instead of using
-   *  the listener's cached prompt from an earlier event in the same pane. */
+  /** True when the event carried prompt text directly, not the listener's cached prompt from an earlier event in the pane. */
   hasExplicitPrompt?: boolean
-  /** Stable per-turn key when a source exposes enough local hook context to
-   *  distinguish duplicate hook delivery from a same-text prompt rerun. */
+  /** Stable per-turn key to distinguish duplicate hook delivery from a same-text prompt rerun (when the source exposes enough context). */
   promptInteractionKey?: string
   /** Raw agent hook event name, used by main-process transition guards. */
   hookEventName?: string
@@ -297,8 +256,7 @@ export type AgentHookEventPayload = {
   toolAgentType?: string
   /** Provider-owned conversation/session id needed to resume a sleeping agent. */
   providerSession?: AgentProviderSessionMetadata
-  /** Session identity update with no turn-state transition. The receiver uses
-   *  this to refresh durable resume metadata without showing a fake status row. */
+  /** Session identity update with no turn-state transition; refreshes durable resume metadata without a fake status row. */
   providerSessionOnly?: boolean
   /** True when this event is a relay cache replay rather than a live hook. */
   isReplay?: boolean
@@ -326,8 +284,7 @@ export function readRequestBody(req: IncomingMessage): Promise<unknown> {
       req.off('end', onEnd)
       req.off('error', onError)
       req.off('close', onClose)
-      // Why: detached parser closures release body chunks; keep a neutral
-      // error sink so a late IncomingMessage error cannot become unhandled.
+      // Why: keep a neutral error sink so a late IncomingMessage error after cleanup can't become unhandled.
       req.on('error', ignoreSettledRequestError)
     }
     const settleResolve = (value: unknown): void => {
@@ -347,8 +304,7 @@ export function readRequestBody(req: IncomingMessage): Promise<unknown> {
       reject(error)
     }
     const onData = (chunk: Buffer): void => {
-      // Why: check size in bytes (not UTF-16 code units) and stop accumulating
-      // after rejection so a malicious client cannot push memory past the cap.
+      // Why: bound by bytes (not UTF-16 units) and stop accumulating after rejection so a client can't push memory past the cap.
       if (byteLength + chunk.length > HOOK_REQUEST_MAX_BYTES) {
         settleReject(new Error('payload too large'))
         req.destroy()
@@ -359,8 +315,7 @@ export function readRequestBody(req: IncomingMessage): Promise<unknown> {
     }
     const onEnd = (): void => {
       try {
-        // Why: decode once via Buffer.concat so multi-byte UTF-8 characters
-        // that straddle a chunk boundary are reassembled correctly.
+        // Why: Buffer.concat before decode so multi-byte UTF-8 straddling a chunk boundary reassembles correctly.
         const body = chunks.length > 0 ? Buffer.concat(chunks).toString('utf8') : ''
         const contentType = req.headers['content-type'] ?? ''
         if (typeof contentType === 'string' && contentType.includes('application/json')) {
@@ -374,8 +329,7 @@ export function readRequestBody(req: IncomingMessage): Promise<unknown> {
           settleResolve(parseFormEncodedBody(body))
           return
         }
-        // Why: existing managed scripts POST JSON; updated POSIX scripts POST
-        // form-encoded. Default to JSON for unknown content types.
+        // Why: managed scripts POST JSON, updated POSIX scripts form-encoded; default to JSON for unknown content types.
         settleResolve(body ? JSON.parse(body) : {})
       } catch (error) {
         settleReject(error)
@@ -384,9 +338,7 @@ export function readRequestBody(req: IncomingMessage): Promise<unknown> {
     const onError = (err: Error): void => {
       settleReject(err)
     }
-    // Why: req.destroy() (called by the slowloris timer) emits 'close' but
-    // not 'end'/'error'. Without this handler the promise would never settle
-    // and the chunk buffers would be retained for the process lifetime.
+    // Why: req.destroy() (slowloris timer) emits 'close' but not 'end'/'error'; without this the promise never settles and buffers leak.
     const onClose = (): void => {
       settleReject(new Error('aborted'))
     }
@@ -415,9 +367,7 @@ type ExtractedPromptText = {
     | null
 }
 
-// Joins the `text` of an Anthropic-style content-block array ([{ type: 'text',
-// text }, ...]); plain string items are included too. Returns '' when nothing
-// textual is present so callers can fall through to the next prompt source.
+// Joins text of an Anthropic-style content-block array; returns '' when nothing textual so callers fall through to the next prompt source.
 function contentBlockArrayText(value: unknown[]): string {
   const parts: string[] = []
   for (const item of value) {
@@ -448,14 +398,10 @@ function extractPromptText(hookPayload: Record<string, unknown>): ExtractedPromp
   for (const key of candidateKeys) {
     const value = hookPayload[key]
     if (typeof value === 'string' && value.trim().length > 0) {
-      // Why: trim so prompts match what readStringField produces elsewhere —
-      // surrounding whitespace would otherwise leak into UI and caches.
+      // Why: trim so prompts match readStringField output — whitespace would otherwise leak into UI and caches.
       return { text: value.trim(), source: key as Exclude<ExtractedPromptText['source'], null> }
     }
-    // Why: Kimi Code sends UserPromptSubmit `prompt` as a content-block array
-    // ([{ type: 'text', text }]) rather than a string. Extract its text for the
-    // genuine prompt keys. `message` stays string-only: it is the ambiguous
-    // status/permission field that hasExplicitUserPrompt intentionally distrusts.
+    // Why: Kimi sends `prompt` as a content-block array, not a string; extract it for real prompt keys but skip `message` (ambiguous status field).
     if (key !== 'message' && Array.isArray(value)) {
       const text = contentBlockArrayText(value)
       if (text.length > 0) {
@@ -463,9 +409,7 @@ function extractPromptText(hookPayload: Record<string, unknown>): ExtractedPromp
       }
     }
   }
-  // Why: OpenCode's plugin sends MessagePart events with { role, text }. When
-  // role === 'user', the text *is* the prompt — surface it even though
-  // OpenCode has no UserPromptSubmit-equivalent.
+  // Why: OpenCode sends MessagePart { role, text } with no UserPromptSubmit; when role === 'user' the text is the prompt.
   if (hookPayload.role === 'user' && typeof hookPayload.text === 'string') {
     const trimmed = capOpenCodeHookText(hookPayload.text.trim())
     if (trimmed.length > 0) {
@@ -483,8 +427,7 @@ function stripGrokUserQueryWrapper(promptText: string): string {
   const closer = '</user_query>'
   const wrappedText = promptText.slice(opener.length)
   const text = wrappedText.endsWith(closer) ? wrappedText.slice(0, -closer.length) : wrappedText
-  // Why: Grok emits the submitted prompt wrapped in its internal
-  // `<user_query>` envelope; the status cache should hold the user text.
+  // Why: Grok wraps the submitted prompt in a `<user_query>` envelope; the status cache should hold the plain user text.
   return text.trim()
 }
 
@@ -494,11 +437,7 @@ function resolvePrompt(
   promptText: string,
   options?: { resetOnNewTurn?: boolean }
 ): string {
-  // Why: harness-injected turns (task notifications, system reminders) fire
-  // UserPromptSubmit but are not the user's ask — keep the cached real prompt
-  // instead of surfacing raw machinery tags in status labels. Match only known
-  // harness tags: a real prompt pasting a custom `<my-element>` must reset the
-  // turn, not be mistaken for machinery and leave the pane on a stale prompt.
+  // Why: harness-injected turns fire UserPromptSubmit but aren't the user's ask — keep cached prompt; match only known tags so real <tags> still reset the turn.
   if (isKnownHarnessInjectedUserTurnText(promptText)) {
     return state.lastPromptByPaneKey.get(paneKey) ?? ''
   }
@@ -515,10 +454,7 @@ function resolvePrompt(
 export type ToolSnapshot = {
   toolName?: string
   toolInput?: string
-  /** Full JSON of an AskUserQuestion tool input, set only on the event that
-   *  carries it. Deliberately NOT inherited across events in resolveToolState
-   *  so it clears the moment the agent moves to a different tool / state and a
-   *  stale prompt can't linger on the emitted payload. */
+  /** Full JSON of an AskUserQuestion tool input; set only on its own event and NOT inherited (resolveToolState) so no stale prompt lingers. */
   interactivePrompt?: string
   hasToolUpdate?: boolean
   hasToolInputField?: boolean
@@ -536,8 +472,7 @@ function resolveToolState(
     state.lastToolByPaneKey.delete(paneKey)
   }
   const previous = state.lastToolByPaneKey.get(paneKey) ?? {}
-  // Why: `undefined` can mean "no update" or "explicit input was not
-  // previewable"; extractor metadata decides whether stale input is inherited.
+  // Why: undefined means either "no update" or "input not previewable"; extractor metadata decides whether to inherit stale input.
   const clearsUnpreviewableInput =
     update.hasToolInputField === true && update.toolInput === undefined
   const clearsUnidentifiedTool =
@@ -555,9 +490,7 @@ function resolveToolState(
   const merged: ToolSnapshot = {
     toolName,
     toolInput,
-    // Why: do NOT inherit `previous.interactivePrompt`. The prompt is only
-    // valid for the single AskUserQuestion event that produced it; carrying it
-    // forward would leave a stale live card on the next tool/state change.
+    // Why: don't inherit previous.interactivePrompt — valid only for its one AskUserQuestion event; carrying it forward leaves a stale live card.
     interactivePrompt: update.interactivePrompt,
     lastAssistantMessage: update.clearLastAssistantMessage
       ? undefined
@@ -595,9 +528,7 @@ const TOOL_INPUT_KEYS_BY_TOOL: Record<string, readonly string[]> = {
   exec_command: ['cmd', 'command'],
   shell_command: ['cmd', 'command'],
   run_terminal_cmd: ['command'],
-  // Why: Grok maps Bash/Edit/Write to snake_case first-party tool names
-  // (run_terminal_command, search_replace, …). Without these keys the status
-  // row shows a blank toolInput for the bulk of Grok tool turns.
+  // Why: Grok maps Bash/Edit/Write to snake_case tool names; without these keys the status row shows blank toolInput for most Grok turns.
   run_terminal_command: ['command'],
   search_replace: ['file_path', 'path', 'filePath'],
   write_to_file: ['TargetFile', 'path', 'file_path'],
@@ -737,10 +668,7 @@ function toolUpdate(
   }
 }
 
-/** Clear the active-tool metadata (name/input/prompt) so a just-failed tool
- *  stops looking in-flight. Why: the compact sidebar prioritizes current-tool
- *  metadata over the failure message, so a completed failed tool must no
- *  longer look active or the error text stays hidden behind the tool name. */
+/** Clear active-tool metadata so a failed tool stops looking in-flight (else the compact sidebar hides the error behind the tool name). */
 function clearActiveToolFieldsUpdate(): ToolSnapshot {
   return toolUpdate(
     { toolName: undefined, toolInput: undefined, interactivePrompt: undefined },
@@ -748,19 +676,13 @@ function clearActiveToolFieldsUpdate(): ToolSnapshot {
   )
 }
 
-/** Capture the full AskUserQuestion tool input as a JSON string when the tool
- *  is an AskUserQuestion variant; otherwise undefined so resolveToolState
- *  clears any prior prompt. Kept agent-generic: callers pass whatever raw
- *  tool-input object their hook payload exposed. */
-/** Drop the hook envelope keys a plugin merges into its event properties so
- *  the serialized interactive prompt holds only the question structure. */
+/** Drop the hook envelope keys a plugin merges into event properties so the serialized prompt holds only the question structure. */
 function stripHookEnvelopeKeys(record: Record<string, unknown>): Record<string, unknown> {
   const { hook_event_name: _h, hookEventName: _he, ...rest } = record
   return rest
 }
 
-/** Short, single-line description of a tool call for an approval card (the
- *  command for Bash, the path for file tools, else a clipped JSON preview). */
+/** One-line description of a tool call for an approval card (Bash command, file path, else clipped JSON). */
 function summarizeApprovalInput(toolInput: unknown): string {
   if (toolInput && typeof toolInput === 'object') {
     const obj = toolInput as Record<string, unknown>
@@ -777,19 +699,13 @@ function summarizeApprovalInput(toolInput: unknown): string {
   }
 }
 
-/** Capture a pending interactive prompt as a normalized JSON envelope:
- *  - AskUserQuestion → the raw `{ questions: [...] }` structure (kind inferred
- *    by the client from the `questions` key, kept stable for back-compat).
- *  - any other tool on a PermissionRequest → `{ approval: { tool, summary } }`
- *    so the client can render an Allow/Deny card.
- *  Returns undefined otherwise so resolveToolState clears any prior prompt. */
+/** Normalized JSON envelope for a pending prompt: AskUserQuestion → `{ questions }` (shape kept stable for back-compat); other tool on PermissionRequest → `{ approval }`; else undefined. */
 function deriveInteractivePrompt(
   toolName: string | undefined,
   toolInput: unknown,
   eventName?: unknown
 ): string | undefined {
-  // Why: providers vary event casing; any post-tool event means the question is
-  // no longer pending and must not recreate its answered live card.
+  // Why: providers vary casing; any post-tool event means the question is no longer pending — don't recreate its answered card.
   const normalizedEventName = normalizeHookEventName(eventName)
   const isPostToolEvent =
     normalizedEventName === 'post_tool_use' || normalizedEventName === 'post_tool_use_failure'
@@ -802,8 +718,7 @@ function deriveInteractivePrompt(
     try {
       return JSON.stringify(toolInput)
     } catch {
-      // Why: defend against circular/unserializable input from a buggy agent —
-      // a missing live card is better than throwing in the hook hot path.
+      // Why: circular/unserializable input from a buggy agent — a missing live card beats throwing in the hook hot path.
       return undefined
     }
   }
@@ -1184,8 +1099,7 @@ function readGrokSessionMetadata(
     ['cwd', 'workspaceRoot', 'workspace_root'],
     GROK_SESSION_CWD_MAX_LENGTH
   )
-  // Why: hook scripts report the effective per-PTY/remote home; old scripts
-  // fall back to the listener runtime's Grok home for compatibility.
+  // Why: hook scripts report the effective per-PTY/remote Grok home; old scripts fall back to the runtime's for compatibility.
   const sessionsDir = grokHome
     ? join(grokHome, 'sessions')
     : resolveGrokSessionsDir(process.env, homedir())
@@ -1212,9 +1126,7 @@ function getGrokChatHistoryPath(
   if (cached) {
     return cached
   }
-  // Why: hasPendingAgentResultText only needs a plausible on-disk target when
-  // the file may not exist yet (SessionEnd can race the last write). Prefer a
-  // short-cwd candidate when available; async discovery caches slug groups.
+  // Why: SessionEnd can race the last write; return a plausible on-disk candidate (short-cwd preferred) even if the file doesn't exist yet.
   if (!metadata.cwd) {
     return undefined
   }
@@ -1249,8 +1161,7 @@ export function hasPendingAgentResultText(source: AgentHookSource, body: unknown
     return false
   }
   if (source === 'copilot') {
-    // Why: Copilot Stop consumes generic `message` as its final assistant text;
-    // Grok and Antigravity use that field for status text instead.
+    // Why: Copilot Stop uses generic `message` as final assistant text; Grok/Antigravity use that field for status instead.
     if (hasNonEmptyString(record.message)) {
       return false
     }
@@ -1317,8 +1228,7 @@ export function preparePendingGrokResultDiscovery(
   if (!metadata) {
     return null
   }
-  // Why: the server can await this signal without moving filesystem discovery
-  // back into the synchronous hook normalization path.
+  // Why: lets the server await discovery without moving filesystem I/O back into synchronous hook normalization.
   return findGrokChatHistoryBySessionId(metadata.sessionsDir, metadata.sessionId).then(
     () => undefined
   )
@@ -1591,8 +1501,7 @@ function extractAmpToolFields(
       deriveToolInputPreview(toolName, hookPayload.input) ??
       deriveToolInputPreview(toolName, hookPayload.tool_input) ??
       deriveToolInputPreview(toolName, hookPayload.arguments) ??
-      // Why: Amp plugin tools can have arbitrary names, so fall back to the
-      // obvious argument fields instead of rendering an empty tool preview.
+      // Why: Amp plugin tools can have arbitrary names; fall back to obvious arg fields instead of an empty tool preview.
       deriveFallbackToolInputPreview(hookPayload.input) ??
       deriveFallbackToolInputPreview(hookPayload.tool_input) ??
       deriveFallbackToolInputPreview(hookPayload.arguments)
@@ -1625,10 +1534,7 @@ function extractOpenCodeToolFields(
     }
   }
   if (eventName === 'AskUserQuestion') {
-    // Why: OpenCode posts the question.asked event's `event.properties` as the
-    // hook payload (the plugin merges `hook_event_name` into it). The structured
-    // input is that object — minus the hook envelope key — or its `tool_input`
-    // when wrapped. Capture the full JSON so clients render the live card.
+    // Why: OpenCode's payload is question.asked's event.properties (hook_event_name merged in); strip envelope or use tool_input, capture JSON for the card.
     const toolInputSource = hasOwnField(hookPayload, 'tool_input')
       ? hookPayload.tool_input
       : stripHookEnvelopeKeys(hookPayload)
@@ -1909,8 +1815,7 @@ function extractPiToolFields(
     const toolName = readString(hookPayload, 'tool_name')
     const rawToolInput = hookPayload.tool_input
     const toolInput = deriveToolInputPreview(toolName, rawToolInput)
-    // Why: OMP shares this extractor. interactivePrompt derivation should
-    // only apply to Pi so OMP ask_user_question metadata stays unchanged.
+    // Why: OMP shares this extractor; only derive interactivePrompt for Pi so OMP ask_user_question metadata stays unchanged.
     const interactivePrompt =
       agentKind === 'pi' && (eventName === 'tool_call' || eventName === 'tool_execution_start')
         ? deriveInteractivePrompt(toolName, rawToolInput, eventName)
@@ -1934,8 +1839,7 @@ function isDroidPermissionNotification(message: string | undefined): boolean {
     return false
   }
   const lower = message.toLowerCase()
-  // Why: 'confirm' is excluded — it false-positives on benign messages like
-  // "Confirmed configuration loaded" / "task confirmed" that aren't permission prompts.
+  // Why: 'confirm' is excluded — it false-positives on benign messages like "task confirmed" that aren't permission prompts.
   return lower.includes('permission') || lower.includes('approve') || lower.includes('approval')
 }
 
@@ -2097,9 +2001,7 @@ function extractGrokToolFields(
         hookPayload.arguments
       const toolInput =
         deriveToolInputPreview(toolName, rawInput) ?? deriveFallbackToolInputPreview(rawInput)
-      // Why: Grok's ask_user_question is auto-allowed and arrives as PreToolUse
-      // (not PermissionRequest). Capture the full question payload so the live
-      // card path can render options instead of only a waiting Notification.
+      // Why: Grok's ask_user_question is auto-allowed via PreToolUse, not PermissionRequest; capture full payload for the live card.
       const interactivePrompt = deriveInteractivePrompt(toolName, rawInput, eventName)
       Object.assign(
         update,
@@ -2171,8 +2073,7 @@ function extractHermesToolFields(
       deriveToolInputPreview(toolName, hookPayload.tool_input) ??
       deriveToolInputPreview(toolName, hookPayload.args) ??
       deriveToolInputPreview(toolName, hookPayload.input) ??
-      // Why: Hermes exposes many first-party/plugin tool names. When a new
-      // name appears, still show the obvious argument instead of a blank row.
+      // Why: Hermes has many tool names; fall back to obvious arg fields so a new name still shows a value, not a blank row.
       deriveFallbackToolInputPreview(hookPayload.tool_input) ??
       deriveFallbackToolInputPreview(hookPayload.args) ??
       deriveFallbackToolInputPreview(hookPayload.input) ??
@@ -2245,8 +2146,7 @@ function isGrokRoutinePermissionPromptNotification(
   message: string | undefined,
   level: string | undefined
 ): boolean {
-  // Why: Grok emits this info notification before each tool even under
-  // bypassPermissions; PreToolUse already captures progress without paging users.
+  // Why: Grok emits this before each tool even under bypassPermissions; PreToolUse already covers progress.
   return (
     isGrokEvent(notificationType, 'permission_prompt') &&
     message?.trim().toLowerCase() === 'tool permission requested' &&
@@ -2268,12 +2168,10 @@ function isGrokIdleNotification(message: string | undefined): boolean {
 }
 
 function isNewTurnEvent(source: AgentHookSource, eventName: unknown): boolean {
-  // Why: exhaustive switch so adding a source to AgentHookSource fails
-  // typecheck here instead of silently falling through to `false`.
+  // Why: exhaustive switch so a new AgentHookSource fails typecheck here instead of falling through to false.
   switch (source) {
     case 'claude':
-    // Why: Kimi Code emits Claude-compatible hook events, so UserPromptSubmit
-    // is its new-turn boundary too.
+    // Why: Kimi Code emits Claude-compatible hook events, so UserPromptSubmit is its new-turn boundary too.
     case 'kimi':
       return eventName === 'UserPromptSubmit'
     case 'codex':
@@ -2305,9 +2203,7 @@ function isNewTurnEvent(source: AgentHookSource, eventName: unknown): boolean {
     case 'hermes':
       return eventName === 'pre_llm_call' || eventName === 'on_session_start'
     case 'devin':
-      // Why: SessionStart is handled by an early return in normalizeDevinEvent
-      // (clears turn cache, returns null) so it never reaches this branch.
-      // UserPromptSubmit is the real new-turn boundary for Devin.
+      // Why: SessionStart is handled by an early return in normalizeDevinEvent, so UserPromptSubmit is Devin's real new-turn boundary here.
       return eventName === 'UserPromptSubmit'
   }
 }
@@ -2325,9 +2221,7 @@ function hasExplicitUserPrompt(
     (extractedPrompt.source !== 'message' || hasTranscriptPromptEvidence) &&
     resolvedPromptText.trim().length > 0
   ) {
-    // Why: Command Code exposes the submitted prompt through its transcript
-    // rather than direct hook fields. Treat the transcript-backed prompt as
-    // explicit so hook telemetry covers real Command Code turns.
+    // Why: Command Code exposes the submitted prompt via its transcript, not direct hook fields; treat the transcript-backed prompt as explicit so telemetry covers real turns.
     return true
   }
   if (
@@ -2343,16 +2237,11 @@ function hasExplicitUserPrompt(
   if (extractedPrompt.text.length === 0) {
     return false
   }
-  // Why: harness-injected machinery turns are not proof of a user submit —
-  // they must not count for prompt-sent telemetry or permission stickiness.
-  // Match only known harness tags: a real prompt starting with a custom
-  // `<my-element>` is an explicit user turn and must survive interrupt recovery
-  // (a false "not explicit" leaves the agent visibly done after Ctrl+C).
+  // Why: harness-injected turns aren't a user submit (no prompt-sent telemetry or permission stickiness); match only KNOWN tags so a real `<my-element>` prompt still counts and survives interrupt recovery.
   if (isKnownHarnessInjectedUserTurnText(extractedPrompt.text)) {
     return false
   }
-  // Why: bare `message` fields often contain permission or status copy. They
-  // may update visible status prompts, but they are not proof of user submit.
+  // Why: bare `message` fields often carry permission/status copy — may update visible status prompts but aren't proof of a user submit.
   if (extractedPrompt.source === 'message') {
     return false
   }
@@ -2372,8 +2261,7 @@ function extractToolFields(
   hookPayload: Record<string, unknown>,
   options?: { grokHome?: string }
 ): ToolSnapshot {
-  // Why: exhaustive switch so adding a source to AgentHookSource fails
-  // typecheck here instead of silently routing through OpenCode's extractor.
+  // Why: exhaustive switch so a new AgentHookSource fails typecheck here instead of silently routing through OpenCode's extractor.
   switch (source) {
     case 'claude':
     // Why: Kimi Code uses Claude's tool_name/tool_input payload fields verbatim.
@@ -2422,11 +2310,7 @@ function getOrCreateClaudeSubagentRoster(
   return roster
 }
 
-/** SubagentStart/SubagentStop/TeammateIdle don't map to a pane state by
- *  themselves; they update the roster and re-emit the lead's last known state
- *  with the fresh child list so the sidebar reflects spawn/finish immediately
- *  (a background child can outlive the lead turn by minutes with no other
- *  hook traffic). */
+/** SubagentStart/Stop/TeammateIdle update the roster and re-emit the lead's last known state with the fresh child list, so the sidebar reflects spawn/finish even when a background child outlives the lead turn with no other hook traffic. */
 function normalizeClaudeSubagentLifecycleEvent(
   state: HookListenerState,
   eventName: 'SubagentStart' | 'SubagentStop' | 'TeammateIdle',
@@ -2439,9 +2323,7 @@ function normalizeClaudeSubagentLifecycleEvent(
     if (!teammateName) {
       return null
     }
-    // Why: idle means not working, and only working children keep a row. This
-    // is the fallback finish signal for a named agent whose SubagentStop was
-    // lost — its background_tasks entry never stops reading "running".
+    // Why: only working children keep a row; TeammateIdle is the fallback finish signal when a named agent's SubagentStop was lost (its background_tasks never stops reading "running").
     removeClaudeTeammateByName(roster, teammateName)
     clearClaudePendingWaitForAgent(state, paneKey, (waitingAgentId) =>
       claudeTeammateIdMatchesName(waitingAgentId, teammateName)
@@ -2459,31 +2341,21 @@ function normalizeClaudeSubagentLifecycleEvent(
         Date.now()
       )
     } else {
-      // Why: a finished child (one-shot, workflow lane, or named teammate)
-      // leaves the sidebar at once. SubagentStop is the reliable finish
-      // signal even for teammate-shaped ids — their background_tasks entries
-      // stay "running" forever — and a resumed teammate re-earns its row.
+      // Why: SubagentStop is the reliable finish signal even for teammate-shaped ids (their background_tasks stay "running" forever); a resumed teammate re-earns its row.
       finishClaudeSubagent(roster, agentId)
-      // Why: a blocked child that dies (killed, errored) without another tool
-      // event would otherwise pin its permission/question wait on the pane
-      // forever — nothing else references that agent again.
+      // Why: a blocked child that dies without another tool event would pin its permission/question wait on the pane forever — nothing else references that agent again.
       clearClaudePendingWaitForAgent(state, paneKey, (waitingAgentId) => waitingAgentId === agentId)
     }
   }
   return buildClaudeChildDrivenStatusPayload(state, eventName, paneKey, hookPayload)
 }
 
-/** Sync the Claude lead-turn record when the SERVER infers an interrupt
- *  outside the hook stream (Ctrl+C with a missed Stop hook). Without this, a
- *  later child lifecycle event would re-emit the stale pre-interrupt lead
- *  state and resurrect a cancelled pane. */
+/** Sync the Claude lead-turn record when the SERVER infers an interrupt outside the hook stream (Ctrl+C with a missed Stop); else a later child lifecycle event resurrects the cancelled pane. */
 export function markClaudeLeadTurnInterrupted(state: HookListenerState, paneKey: string): void {
   state.claudeLeadStateByPaneKey.set(paneKey, { state: 'done', interrupted: true })
 }
 
-/** Rebuild a pane's working roster from a persisted status snapshot. Live
- *  activity confirms a seed after restart; a complete task inventory may reap
- *  an unconfirmed seed whose finish hook arrived while Orca was offline. */
+/** Rebuild a pane's working roster from a persisted snapshot; live activity confirms a seed, a complete task inventory may reap an unconfirmed one whose finish hook arrived while Orca was offline. */
 export function seedClaudeSubagentRosterFromSnapshots(
   state: HookListenerState,
   paneKey: string,
@@ -2494,9 +2366,7 @@ export function seedClaudeSubagentRosterFromSnapshots(
   }
   const roster = getOrCreateClaudeSubagentRoster(state, paneKey)
   for (const snapshot of snapshots) {
-    // Why: the roster only tracks working children now. A persisted idle
-    // snapshot (from a build that kept idle rows) is a finished child — drop
-    // it so restart doesn't resurrect the stale pile this fix removes.
+    // Why: the roster tracks only working children now; a persisted idle snapshot (from a build that kept idle rows) is finished — drop it so restart doesn't resurrect the stale pile.
     if (snapshot.state !== 'working') {
       continue
     }
@@ -2504,19 +2374,13 @@ export function seedClaudeSubagentRosterFromSnapshots(
       startedAt: snapshot.startedAt,
       agentType: snapshot.agentType,
       description: snapshot.description,
-      // Why: the seed can be a phantom (child finished while Orca was down,
-      // its SubagentStop lost). Let a PRESENT background_tasks list that
-      // omits the id remove it instead of gating the pane 'working' forever.
+      // Why: the seed can be a phantom (child finished while Orca was down, SubagentStop lost); let a PRESENT background_tasks list omitting the id remove it, not gate the pane 'working' forever.
       backgroundTasksAuthoritative: true
     })
   }
 }
 
-/** Drop a child-owned waiting state when that child stops/idles, restoring
- *  the lead state the wait displaced. Without a stash (the wait was the
- *  pane's first observed lead event) fall back to 'working' and let the next
- *  lead event resolve it — a transient spinner beats a permanently stuck
- *  card. */
+/** Drop a child-owned waiting state when the child stops/idles, restoring the displaced lead state; without a stash, fall back to 'working' (a transient spinner beats a permanently stuck card). */
 function clearClaudePendingWaitForAgent(
   state: HookListenerState,
   paneKey: string,
@@ -2529,13 +2393,7 @@ function clearClaudePendingWaitForAgent(
   state.claudeLeadStateByPaneKey.set(paneKey, lead.stateBeforeWait ?? { state: 'working' })
 }
 
-/** Clear an AskUserQuestion wait after the user's answer was typed into the
- *  terminal. Answering emits no hook event, so the caller infers it from the
- *  submit keystroke. Restores the stashed pre-wait lead state (child-induced
- *  question) or falls back to 'working' (lead question), and drops the cached
- *  question card so later child-driven refreshes cannot re-emit the stale
- *  wait. Returns the pane state to emit, gated up to 'working' while children
- *  still run. */
+/** Clear an AskUserQuestion wait after the answer is typed (answering emits no hook event; the caller infers it from the submit keystroke). Restores the stashed pre-wait lead state or 'working', drops the cached card, and returns the pane state to emit (gated up to 'working' while children run). */
 export function clearClaudeAnsweredQuestionWait(
   state: HookListenerState,
   paneKey: string
@@ -2559,19 +2417,14 @@ export function clearClaudeAnsweredQuestionWait(
     : restored
 }
 
-/** Emit a pane status refresh driven by child activity (lifecycle events and
- *  child-origin tool events): the lead's cached state is re-emitted — gated up
- *  to 'working' while a child works — without touching the lead's tool/prompt
- *  caches, so a live AskUserQuestion card or permission wait survives child
- *  churn. */
+/** Re-emit the lead's cached state on child activity — gated up to 'working' while a child works — without touching the lead's tool/prompt caches, so a live card or permission wait survives child churn. */
 function buildClaudeChildDrivenStatusPayload(
   state: HookListenerState,
   eventName: unknown,
   paneKey: string,
   hookPayload: Record<string, unknown>
 ): ParsedAgentStatusPayload | null {
-  // Why: default 'working' — a spawn is proof of activity even before the
-  // lead's first state-bearing event (e.g. Orca restarted mid-session).
+  // Why: default 'working' — a spawn proves activity even before the lead's first state-bearing event (e.g. Orca restarted mid-session).
   const lead = state.claudeLeadStateByPaneKey.get(paneKey)
   const leadState = lead?.state ?? 'working'
   const roster = state.claudeSubagentRosterByPaneKey.get(paneKey)
@@ -2598,12 +2451,8 @@ function normalizeClaudeEvent(
     return normalizeClaudeSubagentLifecycleEvent(state, eventName, paneKey, hookPayload)
   }
 
-  // Why: Claude's AskUserQuestion tool is auto-allowed, so it emits PreToolUse
-  // (not PermissionRequest) while blocked on a human answer — Claude posts a
-  // Notification instead of PermissionRequest, and Orca does not register the
-  // Notification hook. Treat that PreToolUse as waiting so the sidebar shows the
-  // amber attention state instead of a working spinner that decays to grey while
-  // the question sits unanswered. Mirrors normalizeKimiEvent's handling.
+  // Why: Claude's auto-allowed AskUserQuestion emits PreToolUse (not PermissionRequest; its Notification hook isn't registered) while blocked on a human answer.
+  // Treat that PreToolUse as waiting so the sidebar shows amber attention, not a spinner that decays to grey. Mirrors normalizeKimiEvent.
   const isAskUserQuestion =
     eventName === 'PreToolUse' && isAskUserQuestionTool(readString(hookPayload, 'tool_name'))
   const stateName =
@@ -2623,15 +2472,8 @@ function normalizeClaudeEvent(
   }
 
   const eventAgentId = readString(hookPayload, 'agent_id')
-  // Why: hook events originating inside a subagent/teammate carry `agent_id`;
-  // the lead session's own events don't. Subagent tool activity keeps that
-  // child's row live but must not be mistaken for the lead's turn state, and
-  // must not overwrite the lead's tool/prompt caches (a live AskUserQuestion
-  // card would vanish when a background child ran its next tool). Two
-  // exceptions take the full path below: waiting-inducing events (a child's
-  // PermissionRequest/AskUserQuestion needs the human's attention on this
-  // pane), and the blocked child's own next tool event (approval granted —
-  // the wait must clear exactly as it does for the lead).
+  // Why: subagent/teammate events carry `agent_id` (lead's don't); child tool activity keeps its row live but must not become the lead's state or overwrite its tool/prompt caches (a live card would vanish).
+  // Two exceptions take the full path below: waiting-inducing events (a child needs human attention on this pane) and the blocked child's own next tool event (approval granted — clear the wait as for the lead).
   const isWaitingInducing = stateName === 'waiting'
   const subagentOriginId =
     !isWaitingInducing &&
@@ -2653,11 +2495,8 @@ function normalizeClaudeEvent(
     if (lead?.state !== 'waiting' || lead.waitingAgentId !== subagentOriginId) {
       return buildClaudeChildDrivenStatusPayload(state, eventName, paneKey, hookPayload)
     }
-    // Why: approval granted — update the tool snapshot exactly as the lead's
-    // own next tool event would (dropping the pending card), but restore the
-    // lead state the wait displaced instead of adopting this child event as
-    // the lead's 'working': the lead may already be done, and the done-gate
-    // never upgrades working back to done once the roster drains.
+    // Why: approval granted — update the tool snapshot (drop the pending card) as the lead's own next tool event would.
+    // Restore the stashed lead state, not this child's 'working': the lead may already be done, and the done-gate never upgrades working back to done once the roster drains.
     const restored = lead.stateBeforeWait ?? { state: 'working' as const }
     state.claudeLeadStateByPaneKey.set(paneKey, restored)
     const roster = state.claudeSubagentRosterByPaneKey.get(paneKey)
@@ -2671,10 +2510,7 @@ function normalizeClaudeEvent(
     })
   }
 
-  // Why: lead events never carry agent_id, so a known child's id on a
-  // turn-boundary event (a CLI that stops converting child Stops to
-  // SubagentStop) must not retire or resurrect the pane as if the lead
-  // spoke — re-emit it as child activity instead.
+  // Why: lead events never carry agent_id, so a known child's id on a turn-boundary event must not retire/resurrect the pane as if the lead spoke — re-emit as child activity.
   if (
     eventAgentId &&
     !isWaitingInducing &&
@@ -2684,11 +2520,8 @@ function normalizeClaudeEvent(
   }
 
   if (eventName === 'Stop' || eventName === 'StopFailure') {
-    // Why: background_tasks is only trusted where unambiguous (empty list,
-    // id-exact matches, unmatched running one-shot subagents) — see
-    // foldClaudeBackgroundTasksIntoRoster. The lifecycle events own teammate
-    // state; teammates report "running" here even while idle. Older Claude
-    // builds without the field keep the incrementally tracked roster.
+    // Why: background_tasks is trusted only where unambiguous (see foldClaudeBackgroundTasksIntoRoster) — teammates report "running" here even while idle.
+    // Older Claude builds without the field keep the incrementally tracked roster.
     const backgroundTasks = readClaudeBackgroundAgentTasks(hookPayload)
     if (backgroundTasks.present) {
       foldClaudeBackgroundTasksIntoRoster(
@@ -2701,10 +2534,7 @@ function normalizeClaudeEvent(
   }
   const interrupted =
     eventName === 'Stop' && hookPayload['is_interrupt'] === true ? true : undefined
-  // Why: a child-induced wait displaces the lead's own state; stash it so
-  // clearing the wait restores reality (the lead may already be done). A
-  // second child wait carries the ORIGINAL stash forward, not the
-  // intermediate waiting state.
+  // Why: a child-induced wait displaces the lead state; stash it so clearing restores reality (lead may be done). A 2nd child wait carries the ORIGINAL stash, not the intermediate waiting state.
   const previousLead = state.claudeLeadStateByPaneKey.get(paneKey)
   const stateBeforeWait =
     isWaitingInducing && eventAgentId && previousLead
@@ -2722,10 +2552,7 @@ function normalizeClaudeEvent(
     ...(stateBeforeWait ? { stateBeforeWait } : {})
   })
 
-  // Why: the lead ending its turn is not "done" while spawned subagents or
-  // teammates are still running — that reads as a finished ✅ in the sidebar
-  // while a background review loop is mid-flight. Claude wakes the lead when
-  // a child finishes, so a later Stop with an empty roster resolves to done.
+  // Why: a lead Stop isn't "done" while subagents/teammates run (would show a finished row mid-flight); Claude re-wakes the lead, so a later empty-roster Stop resolves to done.
   const roster = state.claudeSubagentRosterByPaneKey.get(paneKey)
   const effectiveState =
     stateName === 'done' && claudeRosterHasWorkingSubagent(roster) ? 'working' : stateName
@@ -2745,24 +2572,18 @@ function buildClaudeStatusPayload(
   hookPayload: Record<string, unknown>,
   options: { stateName: AgentStatusState; updateToolSnapshot: boolean; interrupted?: boolean }
 ): ParsedAgentStatusPayload | null {
-  // Why: child-driven refreshes are roster bookkeeping, not lead tool
-  // activity. Read the cached tool snapshot without merging so they can't
-  // clear a live AskUserQuestion card or clobber the in-flight tool preview.
+  // Why: child-driven refreshes are roster bookkeeping, not lead tool activity; read the cached snapshot without merging so they can't clear a live AskUserQuestion card or clobber the tool preview.
   const snapshot = options.updateToolSnapshot
     ? resolveToolState(state, paneKey, extractToolFields('claude', eventName, hookPayload), {
         resetOnNewTurn: isNewTurnEvent('claude', eventName)
       })
     : (state.lastToolByPaneKey.get(paneKey) ?? {})
 
-  // Why: normalizeAgentStatusPayload validates the object directly — the
-  // JSON stringify/parse round trip the other normalizers use is pure
-  // overhead on this hot per-hook-event path. The normalizer clamps
-  // `interrupted` to done-state payloads, so a gated 'working' emit drops it
-  // while claudeLeadStateByPaneKey preserves it for the eventual done.
+  // Why: validate directly — the JSON stringify/parse round trip other normalizers use is pure overhead on this hot per-hook path.
+  // The normalizer clamps `interrupted` to done payloads, so a gated 'working' emit drops it; claudeLeadStateByPaneKey preserves it for the eventual done.
   return normalizeAgentStatusPayload({
     state: options.stateName,
-    // Why: only lead-origin events (updateToolSnapshot) may reset the prompt
-    // cache; a child-driven refresh must not blank the lead's prompt label.
+    // Why: only lead-origin events may reset the prompt cache; a child-driven refresh must not blank the lead's prompt label.
     prompt: resolvePrompt(state, paneKey, promptText, {
       resetOnNewTurn: options.updateToolSnapshot && isNewTurnEvent('claude', eventName)
     }),
@@ -2776,9 +2597,7 @@ function buildClaudeStatusPayload(
   })
 }
 
-// Why: Devin uses Claude-compatible hook payload shapes but has its own
-// documented lifecycle event set. Keep attribution as Devin while normalizing
-// those event names into Orca's shared status states.
+// Why: Devin uses Claude-compatible payloads but its own lifecycle event set; normalize those event names while keeping Devin attribution.
 function normalizeDevinEvent(
   state: HookListenerState,
   eventName: unknown,
@@ -2787,10 +2606,7 @@ function normalizeDevinEvent(
   hookPayload: Record<string, unknown>
 ): ParsedAgentStatusPayload | null {
   if (eventName === 'SessionStart') {
-    // Why: Devin emits SessionStart when the TUI opens/resumes while still idle.
-    // Only UserPromptSubmit or tool activity should create a visible working row —
-    // mapping SessionStart to 'working' made the sidebar show "Devin - Running"
-    // with a spinner before the user typed anything.
+    // Why: Devin emits SessionStart on idle TUI open/resume; mapping it to 'working' showed a spinner before the user typed, so only UserPromptSubmit/tool activity may create a row.
     clearPaneTurnCacheState(state, paneKey)
     return null
   }
@@ -2837,17 +2653,12 @@ function normalizeDevinEvent(
   )
 }
 
-// Why: Kimi's AskUserQuestion tool is auto-allowed, so it emits PreToolUse
-// instead of PermissionRequest while blocked on a human answer. Treat it as a
-// waiting state so the UI shows the attention icon instead of the working spinner.
+// Why: Kimi's auto-allowed AskUserQuestion emits PreToolUse (not PermissionRequest) while awaiting an answer; treat as waiting so the UI shows the attention icon, not a spinner.
 function isKimiUserInputTool(toolName: string | undefined): boolean {
   return toolName?.replaceAll(/[^a-z0-9]/gi, '').toLowerCase() === 'askuserquestion'
 }
 
-// Why: Kimi Code emits Claude-compatible hook payloads and reuses Claude's
-// lifecycle event names (UserPromptSubmit/PreToolUse/Stop/...). Normalize them
-// into Orca's shared status states while attributing the status to Kimi so the
-// sidebar shows the Kimi icon and label instead of falling back to Claude.
+// Why: Kimi Code emits Claude-compatible payloads/event names; normalize but attribute to Kimi so the sidebar shows Kimi's icon/label, not Claude's.
 function normalizeKimiEvent(
   state: HookListenerState,
   eventName: unknown,
@@ -2908,8 +2719,7 @@ function normalizeGeminiEvent(
   paneKey: string,
   hookPayload: Record<string, unknown>
 ): ParsedAgentStatusPayload | null {
-  // Why: Gemini CLI's native pre-tool event is BeforeTool. PreToolUse/PostToolUse
-  // remain accepted for legacy Antigravity-compatible payloads on this endpoint.
+  // Why: Gemini CLI's native pre-tool event is BeforeTool; PreToolUse/PostToolUse still accepted for legacy Antigravity-compatible payloads.
   const stateName =
     eventName === 'BeforeAgent' ||
     eventName === 'BeforeTool' ||
@@ -2970,8 +2780,7 @@ function normalizeAntigravityEvent(
     eventName !== 'Stop' &&
     state.antigravityCompletedTranscriptByPaneKey.get(paneKey) === transcriptPath
   ) {
-    // Why: agy can emit a bookkeeping PostToolUse after Stop; ignore it so a
-    // finished row does not turn back into a yellow spinner.
+    // Why: agy can emit a bookkeeping PostToolUse after Stop; ignore it so a finished row doesn't turn back into a yellow spinner.
     return null
   }
 
@@ -2996,8 +2805,7 @@ function normalizeAntigravityEvent(
   }
 
   const resetsTurn = isNewTurnEvent('antigravity', eventName)
-  // Why: Antigravity transcripts can grow during long tool-heavy turns. Once
-  // the prompt is cached for this pane, avoid rescanning the file per hook.
+  // Why: once the prompt is cached for this pane, avoid rescanning the (potentially large) Antigravity transcript per hook.
   const cachedPrompt = resetsTurn ? undefined : state.lastPromptByPaneKey.get(paneKey)
   const effectivePrompt =
     promptText || cachedPrompt || readLastUserPromptFromTranscript(transcriptPath) || ''
@@ -3021,9 +2829,7 @@ function normalizeAntigravityEvent(
       lastAssistantMessage: snapshot.lastAssistantMessage
     })
   )
-  // Why: Antigravity can emit Stop with fullyIdle=false between tool steps.
-  // Only a fully idle Stop is terminal; otherwise the sidebar would bounce
-  // done -> working during tool-heavy turns and ignore later tool updates.
+  // Why: Antigravity can emit Stop with fullyIdle=false between tool steps; only a fully idle Stop is terminal, else the sidebar bounces done -> working and ignores later tool updates.
   if (eventName === 'Stop' && !stopStillBusy && transcriptPath) {
     state.antigravityCompletedTranscriptByPaneKey.set(paneKey, transcriptPath)
   }
@@ -3062,8 +2868,7 @@ function normalizeAmpEvent(
     (eventName === 'tool.call' || eventName === 'tool.result') &&
     state.ampCompletedCacheKeys.has(ampCacheKey)
   ) {
-    // Why: Amp status posts are fire-and-forget so tool requests cannot block
-    // the agent. Drop stale tool events that arrive after the thread ended.
+    // Why: Amp status posts are fire-and-forget, so drop stale tool events that arrive after the thread ended.
     return null
   }
 
@@ -3092,8 +2897,7 @@ function normalizeAmpEvent(
   const normalized = parseAgentStatusPayload(
     JSON.stringify({
       state: stateName,
-      // Why: Amp tool/result events may use `message` for tool output; only
-      // lifecycle events may treat it as the turn prompt.
+      // Why: Amp tool/result events may use `message` for tool output; only lifecycle events may treat it as the turn prompt.
       prompt: resolvePrompt(state, ampCacheKey, ampPromptText, {
         resetOnNewTurn: isNewTurnEvent('amp', eventName)
       }),
@@ -3120,8 +2924,7 @@ function getAmpCacheKey(paneKey: string, hookPayload: Record<string, unknown>):
     ['threadId', 'threadID', 'thread_id'],
     AMP_THREAD_ID_MAX_LENGTH
   )
-  // Why: Amp plugin processes can emit events for multiple threads in one
-  // pane. Cache by thread internally while keeping the visible paneKey stable.
+  // Why: Amp emits events for multiple threads per pane; cache by thread internally while keeping the visible paneKey stable.
   return threadId ? `${paneKey}\0amp:${threadId}` : paneKey
 }
 
@@ -3157,9 +2960,7 @@ function pruneAmpThreadCacheKeys(
     return
   }
 
-  // Why: Amp can multiplex many thread IDs through one pane. Keep the current
-  // thread plus the most recent cache entries instead of retaining every
-  // completed thread until pane teardown.
+  // Why: Amp multiplexes many thread IDs through one pane; keep the current thread plus the most recent entries instead of retaining every completed thread until teardown.
   for (const key of scopedKeys) {
     if (overflow <= 0) {
       break
@@ -3294,8 +3095,7 @@ function normalizeCursorEvent(
   paneKey: string,
   hookPayload: Record<string, unknown>
 ): ParsedAgentStatusPayload | null {
-  // Why: Cursor can emit the final response text after `stop`; that should
-  // enrich the completed row, not resurrect the agent as working.
+  // Why: Cursor can emit final response text after `stop`; enrich the completed row, don't resurrect the agent as working.
   const previousStatus = state.lastStatusByPaneKey.get(paneKey)?.payload
   const stateName =
     eventName === 'beforeSubmitPrompt' ||
@@ -3303,9 +3103,7 @@ function normalizeCursorEvent(
     eventName === 'preToolUse' ||
     eventName === 'postToolUse' ||
     eventName === 'postToolUseFailure' ||
-    // Why: these fire for every shell/MCP invocation as pre-execution gates,
-    // not only when the user is blocked on approval. Treat them like PreToolUse
-    // so a tool-heavy turn does not spam waiting-state notifications.
+    // Why: these fire on every shell/MCP invocation (pre-execution gates, not just approval); treat as working to avoid waiting-notification spam.
     eventName === 'beforeShellExecution' ||
     eventName === 'beforeMCPExecution'
       ? 'working'
@@ -3351,9 +3149,7 @@ function normalizeCursorEvent(
   )
 }
 
-// Why: PermissionRequest fires before Copilot's allow/ask/deny checks, so a
-// generic PermissionRequest stays working. `ask_user` itself is a user-input
-// boundary, and notification prompts are the async user-visible blocked signal.
+// Why: Copilot PermissionRequest fires before allow/ask/deny (stays working); ask_user and notification prompts are the real blocked signals.
 function normalizeCopilotEvent(
   state: HookListenerState,
   eventName: unknown,
@@ -3424,15 +3220,12 @@ function normalizePiCompatibleEvent(
   hookPayload: Record<string, unknown>
 ): ParsedAgentStatusPayload | null {
   if (agentType === 'pi' && eventName === 'session_start') {
-    // Why: Pi emits session_start when the TUI opens or resumes; discard stale
-    // turn details without creating a visible working row before user activity.
+    // Why: Pi's session_start fires on TUI open/resume; discard stale turn details, no working row before user activity.
     clearPaneTurnCacheState(state, paneKey)
     return null
   }
 
-  // Why: gate on the event's own tool_name (matching the Claude/Grok normalizers),
-  // not a merged snapshot, so a partial follow-up event can't inherit a stale
-  // ask_user_question name from the tool cache and spuriously re-enter blocked.
+  // Why: gate on the event's own tool_name (not a merged snapshot) so a stale cached ask_user_question can't re-enter blocked.
   const isPiAskUserQuestion =
     agentType === 'pi' &&
     isAskUserQuestionTool(readString(hookPayload, 'tool_name')) &&
@@ -3485,8 +3278,7 @@ function normalizeDroidEvent(
   hookPayload: Record<string, unknown>
 ): ParsedAgentStatusPayload | null {
   if (eventName === 'SessionStart') {
-    // Why: Droid emits SessionStart when the TUI opens/resumes while still idle.
-    // Only UserPromptSubmit or tool activity should create a visible working row.
+    // Why: Droid's SessionStart fires while idle (TUI open/resume); wait for real activity before a working row.
     clearPaneTurnCacheState(state, paneKey)
     return null
   }
@@ -3498,8 +3290,7 @@ function normalizeDroidEvent(
     eventName === 'PreToolUse' &&
     (isDroidAskUserTool(droidToolName) || isDroidHighRiskToolUse(hookPayload))
   ) {
-    // Why: Droid surfaces both AskUser and high-risk approval prompts as
-    // PreToolUse events; the observed approval path emits no Notification hook.
+    // Why: Droid surfaces AskUser and high-risk approvals as PreToolUse; the approval path emits no Notification hook.
     stateName = 'waiting'
   } else if (
     eventName === 'UserPromptSubmit' ||
@@ -3514,8 +3305,7 @@ function normalizeDroidEvent(
   } else if (eventName === 'Notification' && isDroidPermissionNotification(notificationMessage)) {
     stateName = 'waiting'
   } else if (eventName === 'Notification' && isDroidIdleNotification(notificationMessage)) {
-    // Why: Factory does not emit Stop when the user interrupts Droid, but it
-    // does emit an idle notification when Droid is ready for input again.
+    // Why: Droid emits no Stop on user-interrupt, only an idle notification when ready again.
     stateName = 'done'
   }
   if (!stateName) {
@@ -3529,9 +3319,7 @@ function normalizeDroidEvent(
     { resetOnNewTurn: isNewTurnEvent('droid', eventName) }
   )
 
-  // Why: Droid's Notification.message contains status text (e.g. "Droid is
-  // waiting for your input"), not the user's prompt. Pass '' so resolvePrompt
-  // falls back to the cached UserPromptSubmit value instead of overwriting it.
+  // Why: Droid Notification.message is status text, not the prompt; '' keeps resolvePrompt's cached UserPromptSubmit value.
   const effectivePrompt = eventName === 'Notification' ? '' : promptText
 
   return parseAgentStatusPayload(
@@ -3597,9 +3385,7 @@ function normalizeGrokEvent(
   grokHome?: string
 ): ParsedAgentStatusPayload | null {
   if (isGrokEvent(eventName, 'session_start')) {
-    // Why: Grok emits SessionStart when the TUI opens/resumes. It should reset
-    // stale per-turn details without creating a visible "working" row before a
-    // user prompt or tool event exists.
+    // Why: SessionStart resets stale per-turn state but must not create a working row before any prompt/tool event.
     clearPaneTurnCacheState(state, paneKey)
     return null
   }
@@ -3611,9 +3397,7 @@ function normalizeGrokEvent(
     readString(hookPayload, 'toolName') ??
     readString(hookPayload, 'tool_name') ??
     readString(hookPayload, 'name')
-  // Why: Grok's ask_user_question is auto-allowed, so it emits PreToolUse while
-  // blocked on a human answer (same shape as Kimi). Map that to waiting so the
-  // sidebar attention state matches Claude PermissionRequest UX.
+  // Why: Grok's ask_user_question is auto-allowed, so it fires PreToolUse while blocked on a human answer; map to waiting.
   const isUserInputPreTool =
     isGrokEvent(eventName, 'pre_tool_use') && isAskUserQuestionTool(preToolName)
 
@@ -3658,8 +3442,7 @@ function normalizeGrokEvent(
     { resetOnNewTurn: isNewTurnEvent('grok', eventName) }
   )
 
-  // Why: Grok Notification.message is status UI text, not necessarily the
-  // user's prompt. Preserve the cached UserPromptSubmit prompt for the row.
+  // Why: Grok Notification.message is status UI text, not the prompt; '' preserves the cached UserPromptSubmit.
   const effectivePrompt = isGrokEvent(eventName, 'notification')
     ? ''
     : stripGrokUserQueryWrapper(promptText)
@@ -3794,8 +3577,7 @@ export function normalizeHookPayload(
   const promptText = extractedPrompt.text
   let resolvedPromptText = promptText
   let hasTranscriptPromptEvidence = false
-  // Why: exhaustive switch so adding a source to AgentHookSource fails
-  // typecheck here instead of silently routing through OpenCode's normalizer.
+  // Why: exhaustive switch so a new AgentHookSource fails typecheck here instead of silently misrouting.
   let payload: ParsedAgentStatusPayload | null
   switch (source) {
     case 'claude':
@@ -3911,16 +3693,11 @@ export function normalizeHookPayload(
       break
   }
 
-  // Why: connectionId stays null at the listener layer. The local server keeps
-  // it null; the relay forwards null on the wire and Orca's `ingestRemote`
-  // stamps the real value from `mux` identity on receive. See
-  // docs/design/agent-status-over-ssh.md §5.
+  // Why: connectionId is null here; ingestRemote stamps it from mux identity on receive. See docs/design/agent-status-over-ssh.md §5.
   const providerSession = extractAgentProviderSession(source, hookPayloadRecord)
   const providerSessionOnly =
     source === 'pi' && eventName === 'session_start' && providerSession !== null
-  // Why: session_start establishes resume identity while Pi is idle. Carry a
-  // valid placeholder through the status-shaped transport; receivers discard
-  // it when providerSessionOnly is set, so no working/done row is fabricated.
+  // Why: Pi session_start carries resume identity while idle; providerSessionOnly makes receivers discard the placeholder row.
   const transportPayload =
     payload ??
     (providerSessionOnly
@@ -3986,16 +3763,12 @@ export function resolveHookSource(pathname: string): AgentHookSource | null {
 // ─── Endpoint-file writing ──────────────────────────────────────────
 
 export function getEndpointFileName(): string {
-  // Why: per-platform extension lets hook scripts source the file natively
-  // (`. "$file"` POSIX, `call "%file%"` Windows). The OpenCode plugin's regex
-  // accepts both shapes already.
+  // Why: per-platform extension lets hook scripts source the file natively (POSIX `. "$file"` / Windows `call "%file%"`); the OpenCode plugin regex accepts both shapes.
   return process.platform === 'win32' ? 'endpoint.cmd' : 'endpoint.env'
 }
 
 export function isShellSafeEndpointValue(value: string): boolean {
-  // Why: every value in the endpoint file is sourced as shell. The `+`
-  // quantifier rejects empty strings as defense-in-depth — a sourced empty
-  // `KEY=` would clear the env var in the sourcing shell.
+  // Why: values are shell-sourced; the + rejects empty strings so a sourced `KEY=` can't clear the env var.
   return /^[A-Za-z0-9._:/-]+$/.test(value)
 }
 
@@ -4007,9 +3780,8 @@ export type EndpointFileFields = {
 }
 
 /** Atomically write the endpoint file at `endpointDir/<getEndpointFileName()>`.
- *  Returns true on success, false on any error (caller may fall back to PTY
- *  env). Mirrors `AgentHookServer.writeEndpointFile` and is shared verbatim by
- *  the relay's adapter. */
+ *  Returns true on success, false on error (caller may fall back to PTY env).
+ *  Kept in sync with `AgentHookServer.writeEndpointFile`. */
 export function writeEndpointFile(
   endpointDir: string,
   finalPath: string,
@@ -4035,20 +3807,17 @@ export function writeEndpointFile(
   const lines = [...valuesToWrite.map(([key, value]) => `${prefix}${key}=${value}`), '']
   let tmpWritten = false
   try {
-    // Why: 0o700 — match the file's owner-only policy so the directory does
-    // not leak the existence of this Orca/relay install to other local users.
+    // Why: 0o700 owner-only so the dir doesn't leak this install's existence to other local users.
     mkdirSync(endpointDir, { recursive: true, mode: 0o700 })
     if (process.platform !== 'win32') {
-      // Why: mkdirSync's mode only applies on creation — a pre-existing
-      // directory keeps its original perms. POSIX-only chmod fix.
+      // Why: mkdirSync mode only applies on creation; chmod fixes perms on a pre-existing dir (POSIX-only).
       try {
         chmodSync(endpointDir, 0o700)
       } catch {
         // best-effort
       }
     }
-    // Why: sweep stale `.endpoint-*.tmp` orphans older than 5 min so a crash
-    // between writeFileSync and renameSync cannot grow the dir unboundedly.
+    // Why: sweep stale .endpoint-*.tmp orphans (crash between write and rename) so the dir can't grow unbounded.
     try {
       const entries = readdirSync(endpointDir)
       const cutoff = Date.now() - 5 * 60 * 1000
diff --git a/src/shared/agent-status-types.test.ts b/src/shared/agent-status-types.test.ts
index 2fd33036b61..d555d9ae913 100644
--- a/src/shared/agent-status-types.test.ts
+++ b/src/shared/agent-status-types.test.ts
@@ -87,10 +87,7 @@ describe('parseAgentStatusPayload', () => {
     expect(result!.prompt).toHaveLength(AGENT_STATUS_MAX_FIELD_LENGTH)
   })
 
-  // Why: real dispatch preambles bury the task body after multi-KB CLI text. A
-  // naive head-truncation would keep only lifecycle boilerplate in the 200-char
-  // prompt field and drop the fallback label the UI needs before orchestration
-  // metadata arrives.
+  // Why: dispatch preambles bury the task body after multi-KB CLI text; naive head-truncation would keep only boilerplate.
   it('compacts Orca dispatch preambles so the task body survives 200-char truncation', () => {
     const longCliNoise = Array.from(
       { length: 50 },
@@ -123,8 +120,7 @@ Fix dispatch fallback preview for normalized status prompts`
   it('ignores task-marker text inside base-drift commit subjects', () => {
     const result = normalizeAgentStatusPayload({
       state: 'working',
-      // Why: use CRLF to cover Windows hook payloads while proving repository
-      // commit text cannot impersonate Orca's standalone task separator.
+      // Why: CRLF covers Windows hook payloads; commit text must not impersonate the task separator.
       prompt: [
         'You are working inside Orca, a multi-agent IDE. You are a dispatched worker.',
         'Your task ID is: task_drift_marker',
@@ -185,9 +181,7 @@ Fix dispatch fallback preview for normalized status prompts`
   })
 
   it('collapses newlines in agentType (single-line field)', () => {
-    // Why: pins the regression the parser comment on agent-status-types.ts calls
-    // out — a payload with agentType: "claude\nrogue" must not leak the newline
-    // into UI rendering or equality checks.
+    // Why: agentType is single-line; a newline must not leak into UI rendering or equality checks.
     const result = parseAgentStatusPayload('{"state":"working","agentType":"claude\\nrogue"}')
     expect(result!.agentType).toBe('claude rogue')
   })
@@ -216,8 +210,7 @@ Fix dispatch fallback preview for normalized status prompts`
       questions: [{ question: 'Pick one', options: ['a', 'b'] }]
     })
     const result = parseAgentStatusPayload(JSON.stringify({ state: 'waiting', interactivePrompt }))
-    // Why: the value is raw JSON the client parses back — content (including
-    // any embedded newlines) must survive untouched, unlike toolInput.
+    // Why: interactivePrompt is raw JSON the client parses back, so content must survive untouched (unlike toolInput).
     expect(result!.interactivePrompt).toBe(interactivePrompt)
   })
 
@@ -322,9 +315,7 @@ Fix dispatch fallback preview for normalized status prompts`
   })
 
   it('preserves paragraph breaks in lastAssistantMessage', () => {
-    // Why: the assistant message is rendered with `whitespace-pre-wrap` in the
-    // dashboard row so the user sees the same paragraph structure the agent
-    // produced. Collapsing newlines would destroy that structure.
+    // Why: assistant message renders with whitespace-pre-wrap, so paragraph breaks must survive.
     const result = parseAgentStatusPayload(
       '{"state":"done","lastAssistantMessage":"Summary line.\\n\\nDetails paragraph."}'
     )
@@ -359,13 +350,7 @@ Fix dispatch fallback preview for normalized status prompts`
   })
 
   it('folds Unicode line/paragraph separators into \\n and caps blank-line runs in lastAssistantMessage', () => {
-    // Why: U+2028 and U+2029 render as real line breaks under
-    // `whitespace-pre-wrap`. Without folding them to `\n`, a payload with
-    // many separators would bypass the `\n{3,}` → `\n\n` safeguard and let
-    // an agent emit arbitrarily many paragraph breaks. Pin that the
-    // multiline normalizer treats these code points the same way the
-    // single-line normalizer does (strip/convert), so the blank-line cap
-    // applies.
+    // Why: U+2028/U+2029 render as line breaks under whitespace-pre-wrap; fold to \n so the blank-line cap applies.
     const resultLineSep = parseAgentStatusPayload(
       '{"state":"done","lastAssistantMessage":"a\u2028\u2028\u2028\u2028b"}'
     )
@@ -404,8 +389,7 @@ Fix dispatch fallback preview for normalized status prompts`
   })
 
   it('requires strict boolean true for interrupted (rejects truthy non-boolean)', () => {
-    // Why: the parser uses `=== true` to guard against agents that surface a
-    // string or numeric truthy sentinel; only an explicit boolean counts.
+    // Why: parser uses `=== true`, so truthy string/number sentinels don't count.
     expect(
       parseAgentStatusPayload('{"state":"done","interrupted":"true"}')!.interrupted
     ).toBeUndefined()
@@ -416,42 +400,27 @@ Fix dispatch fallback preview for normalized status prompts`
   })
 
   it('never leaves a lone high surrogate when truncating mid surrogate-pair', () => {
-    // Why: prepend a single-code-unit character so truncation at the (even)
-    // AGENT_STATUS_MAX_FIELD_LENGTH cap lands ON a high surrogate rather than
-    // between complete pairs. Without this prefix the test would pass even if
-    // the surrogate guard were removed, because the last code unit would
-    // always be a low surrogate.
+    // Why: prepend one code unit so truncation lands ON a high surrogate, else the test passes without the guard.
     const prompt = `x${'😀'.repeat(AGENT_STATUS_MAX_FIELD_LENGTH)}`
     const result = parseAgentStatusPayload(JSON.stringify({ state: 'working', prompt }))
     expect(result!.prompt.length).toBeLessThanOrEqual(AGENT_STATUS_MAX_FIELD_LENGTH)
-    // Why: pins the guard as load-bearing — a future change that over-trims
-    // (e.g., drops more than one trailing code unit by accident) would leave
-    // the non-malformed assertions happy but silently shrink the output.
-    // The surrogate-pair guard may drop at most ONE trailing high surrogate,
-    // so the result must still reach `max - 1`.
+    // Why: guard drops at most ONE trailing high surrogate, so output must still reach max - 1.
     expect(result!.prompt.length).toBeGreaterThanOrEqual(AGENT_STATUS_MAX_FIELD_LENGTH - 1)
     const len = result!.prompt.length
     const last = result!.prompt.charCodeAt(len - 1)
     const secondLast = len >= 2 ? result!.prompt.charCodeAt(len - 2) : 0
     const isLoneHighSurrogate = last >= 0xd800 && last <= 0xdbff
     expect(isLoneHighSurrogate).toBe(false)
-    // Why: if the last char is a low surrogate, its preceding char must be a
-    // high surrogate — otherwise we'd have a dangling low surrogate, which is
-    // also malformed UTF-16. Pin both directions so the guard is actually load-bearing.
+    // Why: a trailing low surrogate must follow a high surrogate, else it's also malformed UTF-16.
     if (last >= 0xdc00 && last <= 0xdfff) {
       expect(secondLast >= 0xd800 && secondLast <= 0xdbff).toBe(true)
     }
   })
 
   it('never leaves a lone high surrogate in lastAssistantMessage truncation', () => {
-    // Why: the multiline normalizer has the same surrogate-pair guard as the
-    // single-line path; cover both so a refactor can't drop the protection
-    // on one side. Emoji count chosen to land truncation inside a pair.
+    // Why: cover the multiline surrogate-pair guard too, so a refactor can't drop it on one side.
     const surrogatePairs = Math.floor(AGENT_STATUS_ASSISTANT_MESSAGE_MAX_LENGTH / 2) + 1
-    // Why: prepend a single-code-unit character so truncation at the (even)
-    // cap lands ON a high surrogate rather than between complete pairs. Without
-    // this prefix the test would pass even if the surrogate guard were removed,
-    // because the last code unit would always be a low surrogate.
+    // Why: prepend one code unit so truncation lands ON a high surrogate, else the test passes without the guard.
     const message = `x${'😀'.repeat(surrogatePairs)}`
     const result = parseAgentStatusPayload(
       JSON.stringify({ state: 'done', lastAssistantMessage: message })
@@ -459,11 +428,7 @@ Fix dispatch fallback preview for normalized status prompts`
     expect(result!.lastAssistantMessage!.length).toBeLessThanOrEqual(
       AGENT_STATUS_ASSISTANT_MESSAGE_MAX_LENGTH
     )
-    // Why: pins the guard as load-bearing — a future change that over-trims
-    // (e.g., drops more than one trailing code unit by accident) would leave
-    // the non-malformed assertions happy but silently shrink the output.
-    // The surrogate-pair guard may drop at most ONE trailing high surrogate,
-    // so the result must still reach `max - 1`.
+    // Why: guard drops at most ONE trailing high surrogate, so output must still reach max - 1.
     expect(result!.lastAssistantMessage!.length).toBeGreaterThanOrEqual(
       AGENT_STATUS_ASSISTANT_MESSAGE_MAX_LENGTH - 1
     )
@@ -472,9 +437,7 @@ Fix dispatch fallback preview for normalized status prompts`
     const secondLast = len >= 2 ? result!.lastAssistantMessage!.charCodeAt(len - 2) : 0
     const isLoneHighSurrogate = last >= 0xd800 && last <= 0xdbff
     expect(isLoneHighSurrogate).toBe(false)
-    // Why: if the last char is a low surrogate, its preceding char must be a
-    // high surrogate — otherwise we'd have a dangling low surrogate, which is
-    // also malformed UTF-16. Pin both directions so the guard is actually load-bearing.
+    // Why: a trailing low surrogate must follow a high surrogate, else it's also malformed UTF-16.
     if (last >= 0xdc00 && last <= 0xdfff) {
       expect(secondLast >= 0xd800 && secondLast <= 0xdbff).toBe(true)
     }
diff --git a/src/shared/agent-status-types.ts b/src/shared/agent-status-types.ts
index 5eaec131742..28e8385c2b3 100644
--- a/src/shared/agent-status-types.ts
+++ b/src/shared/agent-status-types.ts
@@ -1,9 +1,6 @@
 // ─── Explicit agent status (reported via native agent hooks → IPC) ──────────
-// These types define the normalized status that Orca receives from Claude,
-// Codex, and other explicit integrations. Agent state normally comes from
-// hooks; a narrow interrupt fallback may synthesize a final done state when an
-// agent misses its own cancellation hook. We still do not infer status from
-// terminal titles anywhere in the data flow.
+// Why: status comes from hooks (Claude, Codex, etc.) — never inferred from terminal titles;
+// a narrow interrupt fallback synthesizes a final `done` when an agent misses its cancellation hook.
 
 import type { AgentProviderSessionMetadata } from './agent-session-resume'
 import {
@@ -17,10 +14,8 @@ export { AGENT_STATUS_MAX_FIELD_LENGTH } from './agent-status-field-normalizatio
 
 export const AGENT_STATUS_STATES = ['working', 'blocked', 'waiting', 'done'] as const
 export type AgentStatusState = (typeof AGENT_STATUS_STATES)[number]
-// Why: agent types are not restricted to a fixed set — new agents appear
-// regularly and users may run custom agents. Any non-empty string is accepted;
-// well-known names are kept as a convenience union for internal code that
-// wants to pattern-match on common agents.
+// Why: agent types aren't a fixed set (custom agents exist); any non-empty string is
+// accepted — these well-known names are just a convenience union for pattern-matching.
 export type WellKnownAgentType =
   | 'claude'
   | 'openclaude'
@@ -45,24 +40,15 @@ export type WellKnownAgentType =
 export type AgentType = WellKnownAgentType | (string & {})
 
 /** A snapshot of a previous agent state, used to render activity blocks.
- *  Why: intentionally narrower than AgentStatusEntry — omits toolName,
- *  toolInput, and lastAssistantMessage. History rows record what STATE the
- *  agent was in and what PROMPT was being handled; tool context is
- *  per-event/per-turn and doesn't meaningfully apply to a historical state
- *  snapshot. Carrying tool/assistant payloads on every transition would also
- *  bloat memory on long sessions (capped at AGENT_STATE_HISTORY_MAX entries
- *  per agent). The current state's tool/assistant fields live on
- *  AgentStatusEntry only, and activity-block rendering intentionally shows
- *  state + prompt + duration summaries rather than tool traces. */
+ *  Why: intentionally narrower than AgentStatusEntry — tool/assistant context is
+ *  per-turn, not meaningful on a historical snapshot, and would bloat memory. */
 export type AgentStateHistoryEntry = {
   state: AgentStatusState
   prompt: string
   /** When this state was first reported. */
   startedAt: number
-  /** True when this `done` was a cancellation. May come from an agent hook
-   *  (for example Claude Code `is_interrupt`) or Orca's guarded interrupt
-   *  fallback. Always falsy for non-`done` states, so retention logic can
-   *  preserve this signal. */
+  /** True when this `done` was a cancellation (agent hook like Claude `is_interrupt`,
+   *  or Orca's guarded fallback). Always falsy for non-`done` states so retention logic can preserve it. */
   interrupted?: boolean
 }
 
@@ -82,10 +68,8 @@ export type AgentStatusOrchestrationContext = {
 
 export type AgentSubagentState = 'working' | 'idle'
 
-/** A live in-process subagent/teammate spawned by the pane's agent session
- *  (reported by Claude's SubagentStart/SubagentStop hooks and the
- *  `background_tasks` field on Stop). Rendered as an indented child row under
- *  the owning pane's sidebar row — these children have no PTY of their own. */
+/** A live in-process subagent/teammate of the pane's session (Claude Subagent hooks +
+ *  the `background_tasks` field on Stop). Rendered as an indented child row with no PTY of its own. */
 export type AgentSubagentSnapshot = {
   /** Provider-assigned id (Claude hook `agent_id`). */
   id: string
@@ -98,17 +82,13 @@ export type AgentSubagentSnapshot = {
 
 export type AgentStatusEntry = {
   state: AgentStatusState
-  /** The user's most recent prompt, when the hook payload carried one.
-   *  Cached across the turn — subsequent tool-use events in the same turn do
-   *  not include the prompt, so the renderer receives the last known value
-   *  until a new prompt arrives or the pane resets. Empty when unknown. */
+  /** The user's most recent prompt. Cached across the turn — later tool-use events
+   *  omit it, so the last value persists until a new prompt or pane reset. Empty when unknown. */
   prompt: string
   /** Timestamp (ms) of the last status update. */
   updatedAt: number
   /** Timestamp (ms) when the current `state` was first reported.
-   *  Why: separate from updatedAt so stateHistory[].startedAt reflects when
-   *  the state was first reported, not the most recent within-state update
-   *  (tool/prompt pings reset updatedAt but not stateStartedAt). */
+   *  Why: separate from updatedAt so tool/prompt pings (which reset updatedAt) don't move it. */
   stateStartedAt: number
   agentType?: AgentType
   /** Composite key: `${tabId}:${leafId}` where leafId is a stable UUID layout leaf. */
@@ -116,41 +96,30 @@ export type AgentStatusEntry = {
   /** Runtime terminal handle for matching retained parent rows when the parent
    *  pane key cannot be re-derived after terminal teardown. */
   terminalHandle?: string
-  /** Worktree attribution stamped by main when a hook can be resolved there.
-   *  Why: orchestration workers can report status before their terminal tab is
-   *  present in a renderer; retaining this lets worktree-level UI still show
-   *  the live child agent instead of dropping it as unattributed. */
+  /** Worktree attribution stamped by main when a hook resolves there.
+   *  Why: orchestration workers can report before their tab exists in a renderer, so retaining this keeps them attributed instead of dropped. */
   worktreeId?: string
   /** Accepted transport authority for this live row; null means local. */
   connectionId?: string | null
   /** Tab attribution from the hook IPC payload, when available. */
   tabId?: string
   terminalTitle?: string
-  /** Rolling log of previous states. Each entry records a state the agent was in
-   *  before transitioning to the current one. Capped at AGENT_STATE_HISTORY_MAX. */
+  /** Rolling log of previous states, capped at AGENT_STATE_HISTORY_MAX. */
   stateHistory: AgentStateHistoryEntry[]
   /** Name of the tool the agent is currently using (e.g. "Edit", "Bash"). */
   toolName?: string
   /** Short preview of the tool input (e.g. file path, command). */
   toolInput?: string
-  /** JSON string of the AskUserQuestion tool input (`{ questions: [...] }`),
-   *  captured live when the agent calls AskUserQuestion. Unlike toolInput this
-   *  is NOT truncated to a short preview — clients render the full structured
-   *  prompt as a live card. Cleared (undefined) once the agent moves on to a
-   *  different tool or state so a stale prompt doesn't linger. */
+  /** JSON of the AskUserQuestion tool input, captured live; unlike toolInput it's not
+   *  truncated (clients render the full card). Cleared once the agent moves on so a stale prompt can't linger. */
   interactivePrompt?: string
   /** Most recent assistant message preview, when the hook carried one. */
   lastAssistantMessage?: string
-  /** True when the current `done` state was reached via an interrupt rather
-   *  than a normal turn completion. May be reported by the agent itself or
-   *  inferred by Orca's guarded interrupt fallback.
-   *  Orthogonal to `state`: the agent still finished the turn, but the user
-   *  cancelled it. Undefined while the agent is working or when no interrupt
-   *  signal was available. */
+  /** True when this `done` was reached via interrupt, not normal completion
+   *  (agent-reported or Orca's guarded fallback). Undefined otherwise. */
   interrupted?: boolean
-  /** Orchestration dispatch context for agent panes spawned by another agent.
-   *  Why: parent/child agent hierarchy is pane-level state, not worktree
-   *  lineage; workers often run in the same worktree as their coordinator. */
+  /** Orchestration dispatch context for panes spawned by another agent.
+   *  Why: parent/child hierarchy is pane-level state, not worktree lineage — workers often share the coordinator's worktree. */
   orchestration?: AgentStatusOrchestrationContext
   /** Live in-process subagents/teammates of this pane's session. Absent when
    *  none are tracked; the sidebar derives indented child rows from it. */
@@ -175,9 +144,7 @@ export type MigrationUnsupportedPtyEntry = {
 }
 
 // ─── Agent status payload shape (what hook receivers send via IPC) ──────────
-// Hook integrations only need to provide normalized state fields. The
-// remaining AgentStatusEntry fields (updatedAt, paneKey, etc.) are populated
-// by the renderer when it receives the IPC event.
+// Hook integrations provide only normalized state fields; the renderer fills the rest (updatedAt, paneKey, …) on IPC receipt.
 
 export type AgentStatusPayload = {
   state: AgentStatusState
@@ -195,19 +162,15 @@ export type AgentStatusPayload = {
 }
 
 /**
- * The result of `parseAgentStatusPayload`: prompt is always normalized to a
- * string (empty string when the raw payload omits it), so consumers do not
- * need nullish-coalescing on the field. Tool/assistant fields stay optional so
- * absence ("no new info") is distinguishable from an explicit empty string.
+ * Result of `parseAgentStatusPayload`: prompt is always a string (empty when omitted) so
+ * consumers needn't nullish-coalesce; tool/assistant fields stay optional to distinguish
+ * absence ("no new info") from an explicit empty string.
  */
 export type ParsedAgentStatusPayload = Omit<AgentStatusPayload, 'prompt'> & { prompt: string }
 
 /**
- * Wire shape for agent-status IPC. Both the push channel `agentStatus:set` and the
- * pull channel `agentStatus:getSnapshot` produce this shape so renderer call sites
- * can apply entries through a single `setAgentStatus` path. Flattens the parsed
- * payload onto pane identity + timing because the renderer's slice expects them
- * destructured.
+ * Wire shape for agent-status IPC. Both `agentStatus:set` and `agentStatus:getSnapshot`
+ * produce this shape so renderer call sites share a single `setAgentStatus` path.
  */
 export type AgentStatusIpcPayload = ParsedAgentStatusPayload & {
   paneKey: string
@@ -216,9 +179,7 @@ export type AgentStatusIpcPayload = ParsedAgentStatusPayload & {
   tabId?: string
   worktreeId?: string
   /** Identifies the SSH connection the event arrived on, or null for local.
-   *  Stamped only on the remote-ingest path (Orca's `ingestRemote`); the
-   *  HTTP path always sets null because it cannot know which mux a request
-   *  came from. See docs/design/agent-status-over-ssh.md §5. */
+   *  Only the remote-ingest path (`ingestRemote`) can stamp it; the HTTP path always sets null. See docs/design/agent-status-over-ssh.md §5. */
   connectionId: string | null
   /** Timestamp (ms) when the hook server received this latest status event. */
   receivedAt: number
@@ -246,25 +207,14 @@ export const AGENT_STATUS_TOOL_NAME_MAX_LENGTH = 60
 /** Maximum character length for the toolInput preview. */
 export const AGENT_STATUS_TOOL_INPUT_MAX_LENGTH = 160
 /** Maximum character length for the lastAssistantMessage preview.
- *  Why: assistant messages are the user-facing "what did the agent say" body,
- *  expanded inline in the dashboard row. 8 KB comfortably fits a multi-
- *  paragraph summary while still providing a hard upper bound — the hook
- *  HTTP endpoint already caps bodies at 1 MB, but per-field truncation is a
- *  second line of defense against a buggy/malicious agent spamming huge
- *  strings into the cache (which lives per pane with bounded history). */
+ *  Why: 8 KB fits a multi-paragraph summary while bounding per-pane cache against a buggy/malicious agent spamming huge strings. */
 export const AGENT_STATUS_ASSISTANT_MESSAGE_MAX_LENGTH = 8000
 /** Maximum character length for the interactivePrompt field.
- *  Why: this holds the full JSON of an AskUserQuestion tool input
- *  (`{ questions: [...] }`), which clients render as a structured live card —
- *  truncating to a 160-char preview like toolInput would corrupt the JSON and
- *  drop options. Capped generously so multi-question prompts survive intact
- *  while still bounding per-pane cache growth from a buggy/malicious agent. */
+ *  Why: holds full AskUserQuestion JSON — truncating to a preview like toolInput would corrupt it and drop options; capped to still bound cache growth. */
 export const AGENT_STATUS_INTERACTIVE_PROMPT_MAX_LENGTH = 16000
 /**
- * Freshness threshold for explicit agent status. Retained past this point so
- * WorktreeCard's sidebar dot can decay "working" back to "active" when the
- * hook stream goes silent. Smart-sort + WorktreeCard still read this; the
- * dashboard + hover only display hook-reported data as-is.
+ * Freshness threshold for explicit agent status: retained past this so WorktreeCard's
+ * sidebar dot can decay "working" back to "active" when the hook stream goes silent.
  */
 export const AGENT_STATUS_STALE_AFTER_MS = 30 * 60 * 1000
 
@@ -276,9 +226,7 @@ export function isFreshNonDoneAgentStatus(
   return Boolean(entry && entry.state !== 'done' && now - entry.updatedAt <= staleAfterMs)
 }
 
-// Why: typed as ReadonlySet<string> so .has() accepts any string without
-// requiring `state as AgentStatusState` at the check site. The narrowing
-// cast stays on the return line, where it's actually proven safe.
+// Why: ReadonlySet<string> so .has() accepts any string without a cast here; the narrowing cast stays on the return line where it's proven safe.
 const VALID_STATES: ReadonlySet<string> = new Set<string>(AGENT_STATUS_STATES)
 /** Maximum character length for the agentType label. Truncated on parse. */
 export const AGENT_TYPE_MAX_LENGTH = 40
@@ -369,9 +317,7 @@ function normalizeAgentStatusObject(parsed: unknown): ParsedAgentStatusPayload |
     return null
   }
   const obj = parsed as Record<string, unknown>
-  // Why: explicit typeof guard ensures non-string values (e.g. numbers)
-  // are rejected rather than relying on Set.has returning false for
-  // mismatched types.
+  // Why: explicit typeof guard rejects non-string values instead of leaning on Set.has to return false for mismatched types.
   if (typeof obj.state !== 'string') {
     return null
   }
@@ -382,12 +328,7 @@ function normalizeAgentStatusObject(parsed: unknown): ParsedAgentStatusPayload |
   return {
     state: state as AgentStatusState,
     prompt: normalizePromptField(obj.prompt),
-    // Why: route through normalizeOptionalField so agentType gets the same
-    // trim / collapse-newlines / truncate / empty→undefined treatment as the
-    // other single-line string fields (toolName, toolInput, prompt). Inline
-    // trim+slice left embedded newlines intact, which broke single-line UI
-    // rendering and equality checks when a payload contained e.g.
-    // `agentType: "claude\nrogue"`.
+    // Why: normalize like the other single-line fields so embedded newlines (e.g. `agentType: "claude\nrogue"`) can't break single-line UI and equality checks.
     agentType: normalizeOptionalField(obj.agentType, AGENT_TYPE_MAX_LENGTH),
     toolName: normalizeOptionalField(obj.toolName, AGENT_STATUS_TOOL_NAME_MAX_LENGTH),
     toolInput: normalizeOptionalField(obj.toolInput, AGENT_STATUS_TOOL_INPUT_MAX_LENGTH),
@@ -399,19 +340,16 @@ function normalizeAgentStatusObject(parsed: unknown): ParsedAgentStatusPayload |
       obj.lastAssistantMessage,
       AGENT_STATUS_ASSISTANT_MESSAGE_MAX_LENGTH
     ),
-    // Why: only meaningful on `done`. Coerce to undefined on other states so
-    // the field doesn't leak stale truth through state transitions.
+    // Why: only meaningful on `done`; coerce to undefined elsewhere so it can't leak stale truth across transitions.
     interrupted: obj.interrupted === true && state === 'done' ? true : undefined,
     subagents: normalizeSubagentsField(obj.subagents)
   }
 }
 
 /**
- * Normalize an already-structured agent status object (e.g. arriving via IPC
- * where the payload has already been deserialized by Electron). Skips the
- * JSON.stringify → JSON.parse round-trip that `parseAgentStatusPayload`
- * requires, which matters because hook events can fire many times per second
- * during a tool-use run.
+ * Normalize an already-structured agent status object (e.g. from IPC, already
+ * deserialized by Electron). Skips the JSON round-trip parseAgentStatusPayload
+ * needs — hook events can fire many times per second during a tool-use run.
  */
 export function normalizeAgentStatusPayload(payload: unknown): ParsedAgentStatusPayload | null {
   return normalizeAgentStatusObject(payload)
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index d65182c20c4..19074727e06 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -54,20 +54,15 @@ export function normalizeAgentActivityDisplayMode(value: unknown): AgentActivity
   return value === 'full' || value === 'compact' ? value : DEFAULT_AGENT_ACTIVITY_DISPLAY_MODE
 }
 
-// Why: the onboarding wizard's last step index. Centralized so backfill,
-// clamps, and UI step references all agree on the same upper bound.
+// Why: onboarding wizard's last step index, centralized so backfill, clamps, and UI agree on the bound.
 export const ONBOARDING_FINAL_STEP = 5
 export const ONBOARDING_FLOW_VERSION = 4
 
 export const ORCA_BROWSER_PARTITION = 'persist:orca-browser'
-// Why: blank browser tabs must start from an inert guest URL that does not
-// navigate the privileged main window to about:blank. Renderer and main both
-// need the exact same value so the attach policy can allow only this one safe
-// data URL while still rejecting arbitrary renderer-provided data URLs.
+// Why: inert blank-tab URL shared by main/renderer so the attach policy can allow just this one data URL and reject others.
 export const ORCA_BROWSER_BLANK_URL = 'data:text/html,'
 
-// Why: Electron's invoke error path preserves message text, not arbitrary
-// custom Error fields. Keep this stable token shared across main/renderer.
+// Why: Electron's invoke error path preserves only message text, so signal reconnect via this stable token.
 export const SSH_TERMINATE_RECONNECT_REQUIRED = 'SSH_TERMINATE_RECONNECT_REQUIRED'
 
 export const BROWSER_FAMILY_LABELS: Record<string, string> = {
@@ -83,9 +78,7 @@ export const BROWSER_FAMILY_LABELS: Record<string, string> = {
   manual: 'File'
 }
 
-// Pick a default terminal font that is likely to exist on the current OS.
-// buildFontFamily() adds the full cross-platform fallback chain, so this only
-// affects what users see in Settings as the initial value.
+// Why: only the initial value shown in Settings; buildFontFamily() adds the real cross-platform fallback chain.
 function defaultTerminalFontFamily(): string {
   const platform = typeof process !== 'undefined' ? process.platform : ''
   if (platform === 'win32') {
@@ -105,31 +98,20 @@ export const getDefaultTerminalRightClickToPaste = (
   platform = typeof process !== 'undefined' ? process.platform : ''
 ): boolean => platform === 'win32'
 
-/**
- * Why: ProseMirror builds an in-memory tree for the entire document, so large
- * markdown files cause noticeable typing lag in the rich editor. Files above
- * this threshold fall back to source mode (Monaco) which handles large files
- * efficiently via virtualized line rendering.
- */
+/** Why: ProseMirror's full-document tree lags on large files; above this, fall back to source mode (Monaco). */
 export const RICH_MARKDOWN_MAX_SIZE_BYTES = 300 * 1024
 
 export const DEFAULT_EDITOR_AUTO_SAVE_DELAY_MS = 1000
 export const MIN_EDITOR_AUTO_SAVE_DELAY_MS = 250
 export const MAX_EDITOR_AUTO_SAVE_DELAY_MS = 10_000
 
-// Why: initial threshold of agents spawned (since last update) before we show
-// the star-on-GitHub notification. Doubles each time the user dismisses
-// without starring — e.g. 35 → 70 → 140 → 280. Past dismissals are encoded
-// in starNagNextThreshold, so this constant is only the first-time seed.
+// Why: first-time seed only — doubles on each dismissal without starring; later thresholds live in starNagNextThreshold.
 export const STAR_NAG_INITIAL_THRESHOLD = 35
 
-/** Synthetic worktree id used by the memory collector to bucket PTYs that
- *  are not associated with any worktree. Shared across main and renderer so
- *  the collector and the status-bar popover agree on the sentinel. */
+/** Synthetic worktree id for PTYs not tied to any worktree; shared so main and renderer agree on the sentinel. */
 export const ORPHAN_WORKTREE_ID = '__orphan__'
 
-// Why: the floating workspace is a local synthetic workspace, so persistence
-// pruning must classify it without consulting the repo catalog.
+// Why: synthetic local workspace; persistence pruning must classify it without the repo catalog.
 export const FLOATING_TERMINAL_WORKTREE_ID = 'global-floating-terminal'
 
 export const REPO_COLORS = [
@@ -224,13 +206,9 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     terminalFastScrollSensitivity: 5,
     terminalTuiScrollSensitivity: 1,
     terminalTuiScrollSensitivityDefaultedToOne: true,
-    // Why: "auto" should use WebGL when supported while keeping DOM fallback
-    // for renderer failures and Linux software/unknown GPU renderers.
+    // Why: "auto" uses WebGL when supported, falling back to DOM on renderer failure or software/unknown GPU.
     terminalGpuAcceleration: 'auto',
-    // Why 'auto': when the user has picked a known ligature font we want the
-    // feature enabled by default, but we never force it if they pick a font
-    // that lacks ligatures or if they've explicitly opted out. The resolver
-    // is in shared/terminal-ligatures.ts.
+    // Why 'auto': enable ligatures only for known ligature fonts, never forced. Resolver in shared/terminal-ligatures.ts.
     terminalLigatures: 'auto',
     terminalCursorStyle: 'block',
     terminalCursorStyleDefaultedToBlock: true,
@@ -245,8 +223,7 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     terminalActivePaneOpacity: 1,
     terminalPaneOpacityTransitionMs: 140,
     terminalDividerThicknessPx: 3,
-    // Why: Windows follows its native terminal paste convention, while macOS
-    // and Linux keep right-click available for the context menu by default.
+    // Why: Windows paste-on-right-click matches native convention; macOS/Linux keep right-click for the context menu.
     terminalRightClickToPaste: getDefaultTerminalRightClickToPaste(),
     terminalRightClickToPasteDefaultedForPlatform: true,
     terminalWindowsShell: 'powershell.exe',
@@ -254,26 +231,18 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     localAccountRuntime: 'host',
     localAccountWslDistro: null,
     localWindowsRuntimeDefault: { kind: 'windows-host' },
-    // Why: Windows users expect "PowerShell" to mean modern PowerShell when it
-    // is installed, with a safe fallback to the inbox Windows PowerShell.
+    // Why: prefer modern PowerShell when installed, falling back to inbox Windows PowerShell.
     terminalWindowsPowerShellImplementation: 'auto',
     terminalMouseHideWhileTyping: false,
     terminalQuickCommands: getDefaultTerminalQuickCommands(),
-    // Default false: opt-in only (matches Ghostty's default). Existing users
-    // on upgrade inherit this default via persistence.ts's
-    // { ...defaults.settings, ...parsed.settings } merge, so enabling
-    // focus-follows-mouse never happens unexpectedly.
+    // Why: opt-in only, matching Ghostty's default (upgrades never enable it unexpectedly).
     terminalFocusFollowsMouse: false,
     windowBackgroundBlur: false,
     minimizeToTrayOnClose: false,
-    // Why: default-on everywhere so the value round-trips across platforms;
-    // only the darwin consumers act on it.
+    // Why: default-on everywhere so it round-trips across platforms; only darwin acts on it.
     showMenuBarIcon: true,
     terminalClipboardOnSelect: false,
-    // Why: OSC 52 is a classic data-exfiltration vector (any process piping
-    // untrusted output into the terminal can rewrite the clipboard). Keep the
-    // conservative default off; users who need Grok/tmux/nvim remote copy can
-    // enable the toggle. OSC 52 *query* remains disabled separately.
+    // Why: OSC 52 is a clipboard data-exfiltration vector; default off (query stays disabled separately).
     terminalAllowOsc52Clipboard: false,
     claudeAgentTeamsMode: 'off',
     setupScriptLaunchMode: 'new-tab',
@@ -299,8 +268,7 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     showMobileButton: true,
     showPinnedWorktreesInGroups: false,
     ctrlTabOrderMode: 'mru',
-    // Why: switching worktrees and opening command surfaces from a focused
-    // terminal is a core Orca workflow; users who prefer TUI ownership opt in.
+    // Why: Orca-first keeps core shortcuts working from a focused terminal; TUI-ownership users opt in.
     terminalShortcutPolicy: 'orca-first',
     floatingTerminalEnabled: true,
     floatingTerminalDefaultedForAllUsers: true,
@@ -351,12 +319,7 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     tabAutoGenerateTitle: false,
     confirmClosePinnedTab: true,
     keepComputerAwakeWhileAgentsRun: false,
-    // Why: 'auto' runs a layout-aware probe at boot (see
-    // src/renderer/src/lib/keyboard-layout/*) that picks 'true' for US and
-    // US-International and 'false' for every other layout. This mirrors
-    // Ghostty's detectOptionAsAlt() and ensures users on Turkish, German,
-    // French, etc. can type Option+Q/L/E characters like @, €, [, ] out of
-    // the box (issue #903) while US users keep Option-as-Alt readline chords.
+    // Why: 'auto' probes keyboard layout so non-US users can type Option chars like @/€/[ out of the box (issue #903). See src/renderer/src/lib/keyboard-layout/*.
     terminalMacOptionAsAlt: 'auto',
     terminalMacOptionAsAltMigrated: false,
     terminalJISYenToBackslash: false,
@@ -364,15 +327,11 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     mobileEmulatorEnabled: true,
     mobileEmulatorDefaultDeviceUdid: null,
     androidSdkPath: null,
-    // Why: indefinite hold by default — the desktop "Restore" banner is the
-    // explicit return-to-desktop-size action, no wall-clock guess.
-    // See docs/mobile-fit-hold.md.
+    // Why: indefinite hold — the "Restore" banner is the explicit return action, no wall-clock guess. See docs/mobile-fit-hold.md.
     mobileAutoRestoreFitMs: null,
-    // Why: Anywhere (Relay + local) is the default remote path. Explicit
-    // `local-only` is only written after the user picks same-network only.
+    // Why: Anywhere (Relay + local) is the default; local-only is written only on explicit same-network choice.
     mobilePairingConnectionMode: 'automatic',
-    // Why: off by default — opt-in cosmetic joke feature. Leaving the default
-    // false keeps the overlay unmounted for users who never enable it.
+    // Why: off keeps the cosmetic overlay unmounted for users who never opt in.
     experimentalPet: false,
     experimentalActivity: false,
     experimentalActivityDefaultedOffForAllUsers: true,
@@ -382,23 +341,16 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     experimentalNewWorktreeCardStyle: false,
     experimentalEphemeralVms: false,
     compactWorktreeCards: false,
-    // Why: local desktop remains the default server until the user explicitly
-    // selects a saved runtime environment.
+    // Why: local desktop stays the default until the user picks a saved runtime environment.
     activeRuntimeEnvironmentId: null,
-    // Why: hydrate an empty default so the renderer's optional-chained reads
-    // (`settings?.githubProjects?.activeProject`) land on a stable shape
-    // instead of `undefined`. Upgraded profiles inherit this via the
-    // `{ ...defaults, ...parsed }` merge in persistence.ts.
+    // Why: hydrate a stable empty shape so renderer optional-chained reads never hit undefined.
     githubProjects: {
       pinned: [],
       recent: [],
       lastViewByProject: {},
       activeProject: null
     },
-    // Why: default-on uses the user's default agent when it supports
-    // non-interactive commit-message generation. Keep agent/model maps empty
-    // so first use follows the default agent's configured default model instead
-    // of freezing a stale choice into new profiles.
+    // Why: keep agent/model maps empty so first use follows the default agent's model, not a frozen stale choice.
     commitMessageAi: {
       enabled: true,
       agentId: null,
@@ -524,11 +476,9 @@ export function getDefaultUIState(): PersistedUIState {
     trayMinimizeNoticeShown: false,
     mobileEmulatorTabIntroDismissed: false,
     mobileEmulatorAgentSetupDismissed: false,
-    // Why: brand-new profiles never saw recent project ordering; only upgraded
-    // profiles get the one-time sidebar notice on first launch.
+    // Why: only upgraded profiles saw the old ordering, so only they get the one-time notice.
     projectOrderManualDefaultNoticeDismissed: true,
-    // Why: brand-new profiles never saw percent-remaining as the default; only
-    // upgraded profiles get the one-time usage-display change notice.
+    // Why: only upgraded profiles saw the old default, so only they get the one-time change notice.
     usagePercentageDisplayChangeNoticeDismissed: true,
     workspaceCleanup: { dismissals: {} },
     featureTipsSeenIds: [],
diff --git a/src/shared/git-remote-error.ts b/src/shared/git-remote-error.ts
index d2171f8a6a2..26475281b84 100644
--- a/src/shared/git-remote-error.ts
+++ b/src/shared/git-remote-error.ts
@@ -1,14 +1,6 @@
 import { isPushHookFailure } from './source-control-push-failure'
 
-// Why: git's stderr often embeds the full remote URL, which can include a
-// credential. Redact carefully: classic `user:password@` forms always carry
-// a credential on any scheme (HTTPS, ssh://, git://, git+ssh://), but a
-// lone `user@` is a credential ONLY for HTTP(S) (e.g. token-only PATs like
-// `https://ghp_xxx@host`). For `ssh://git@host/...` the `git` login is
-// required by the SSH remote — stripping it would produce a broken URL in
-// the surfaced error and hide which remote actually failed. The two
-// scheme-scoped patterns below keep SSH user-info intact while still
-// scrubbing passwords on any scheme and HTTPS token-only forms.
+// Why: strip `user:password@` on any scheme, but a lone `user@` only on HTTP(S) — SSH's git@host user-info is required, so stripping breaks the URL.
 const USERPASS_URL_PATTERN = /([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi
 const HTTPS_TOKEN_URL_PATTERN = /(https?:\/\/)[^\s/@:]+@/gi
 const SUBMODULE_PUSH_FAILURE_PATTERN = /Unable to push submodule ['"](.+?)['"]/i
@@ -20,14 +12,10 @@ const NORMALIZED_SUBMODULE_PUSH_FAILURE_PATTERN =
   /(?:^|:\s)((?:Submodule '[^'\n]+'|A submodule) (?:has remote changes\. Pull inside the submodule, then try again\.|could not be pushed\. Resolve the submodule push error, then try again\.))(?:$|\s)/i
 const DIVERGENT_PULL_RECONCILIATION_PATTERN =
   /Need to specify how to reconcile divergent branches|divergent branches and need to specify how to reconcile them/i
-// Why: any of these already pin a reconciliation strategy, so the merge
-// fallback must not override an explicit caller/user choice (e.g. --ff-only).
+// Why: these args already pin a reconcile strategy; the merge fallback must not override an explicit choice like --ff-only.
 const RECONCILIATION_PULL_ARG_PATTERN =
   /^(--rebase|--no-rebase|--ff-only|--ff|--no-ff|--merge|-r)(=|$)/
-// Why: merge is Git's historical pre-2.27 default. Falling back to it lets
-// divergent pulls reconcile on fresh hosts that never configured pull.rebase
-// or pull.ff, instead of failing outright. `--no-rebase` predates the 2.25
-// baseline, so it is safe across all supported Git binaries.
+// Why: --no-rebase (historical merge default) predates the 2.25 baseline, so this fallback is safe on every supported Git.
 export const MERGE_RECONCILIATION_PULL_ARGS = ['--no-rebase']
 
 export function stripCredentialsFromMessage(message: string): string {
@@ -45,8 +33,7 @@ export function formatSubmodulePushFailureDetail(message: string): string | null
     return null
   }
 
-  // Why: recursive push can hide the actionable nested rejection behind a
-  // top-level "failed to push all needed submodules" fatal line.
+  // Why: recursive push hides the actionable nested rejection behind a top-level "failed to push all needed submodules" line.
   const submoduleName = trimmed.match(SUBMODULE_PUSH_FAILURE_PATTERN)?.[1]?.trim()
   const subject = submoduleName ? `Submodule '${submoduleName}'` : 'A submodule'
   if (SUBMODULE_REMOTE_CHANGED_PATTERN.test(trimmed)) {
@@ -56,10 +43,7 @@ export function formatSubmodulePushFailureDetail(message: string): string | null
 }
 
 function extractTailLine(message: string): string {
-  // Why: execFile rejections prefix the message with "Command failed: git ..."
-  // followed by the full stderr. The meaningful diagnostic is typically the
-  // last non-empty line; surfacing the full blob risks leaking local paths or
-  // environment details to the UI.
+  // Why: last non-empty stderr line is the diagnostic; the full blob risks leaking local paths/env to the UI.
   for (const rawLine of iterateLinesFromEnd(message)) {
     const line = rawLine.trim()
     if (line.length > 0) {
@@ -90,9 +74,7 @@ function* iterateLinesFromEnd(value: string): Generator<string> {
   yield value.slice(0, lineEnd)
 }
 
-// Why: a fresh host may lack any pull.rebase/pull.ff policy, so Git 2.27+
-// refuses to reconcile divergent branches. Detect that specific failure so the
-// caller can retry with an explicit merge instead of surfacing a config error.
+// Why: Git 2.27+ refuses divergent pulls when no pull.rebase/pull.ff policy is set; detected so callers can retry as merge.
 export function isDivergentPullReconciliationError(error: unknown): boolean {
   if (!(error instanceof Error)) {
     return false
@@ -100,19 +82,13 @@ export function isDivergentPullReconciliationError(error: unknown): boolean {
   return DIVERGENT_PULL_RECONCILIATION_PATTERN.test(stripCredentialsFromMessage(error.message))
 }
 
-// Whether the pull already specifies how to reconcile (rebase/merge/ff-only),
-// in which case the caller's choice must win over the merge fallback.
+// Why: if the pull already specifies a reconcile strategy, the caller's choice must win over the merge fallback.
 export function pullArgsSpecifyReconciliation(pullArgs: string[]): boolean {
   return pullArgs.some((arg) => RECONCILIATION_PULL_ARG_PATTERN.test(arg))
 }
 
-// Why: on hosts with no pull.rebase/pull.ff policy, Git 2.27+ refuses to
-// reconcile divergent branches. Retry as a merge (Git's historical default) so
-// pulls succeed out of the box; callers that already forced a strategy — or
-// users who configured rebase — never reach this fallback.
-// Not routed through GitCapabilityCache: this is per-repo config/branch state,
-// not a stable host capability, and only fires on an actual divergence error,
-// so there is nothing host-scoped to cache.
+// Why: on hosts with no pull.rebase/pull.ff policy, Git 2.27+ refuses divergent pulls; retry as merge (Git's historical default).
+// Not GitCapabilityCache-routed: this is per-repo config/branch state, not a stable host capability.
 export async function runPullWithDivergenceFallback(
   pullArgs: string[],
   runPull: (effectiveArgs: string[]) => Promise<void>
@@ -135,10 +111,7 @@ export function normalizeGitErrorMessage(error: unknown, operation?: GitRemoteOp
     return 'Git remote operation failed.'
   }
 
-  // Why: scrub credentials up-front so every downstream branch — including
-  // any future refactor that returns a substring of `raw` — operates on
-  // already-redacted text. The fast-path branches below return fixed
-  // literals today, but this hardens against accidental leakage later.
+  // Why: scrub credentials up-front so every downstream branch operates on already-redacted text.
   const raw = stripCredentialsFromMessage(error.message)
 
   const submodulePushFailureDetail = formatSubmodulePushFailureDetail(raw)
@@ -146,12 +119,7 @@ export function normalizeGitErrorMessage(error: unknown, operation?: GitRemoteOp
     return submodulePushFailureDetail
   }
 
-  // Why: `non-fast-forward` / `fetch first` can appear on fetch (after a
-  // remote force-push updating a tracking ref) and on pull (with
-  // `pull.ff=only`), so the "pull or sync first" guidance only makes sense
-  // when the user was actually pushing. For other operations, fall through
-  // to the generic tail-line path. `operation === undefined` keeps the
-  // legacy push-shaped message for any caller that hasn't been updated yet.
+  // Why: `non-fast-forward`/`fetch first` also occur on fetch/pull, so gate this push-specific guidance to push.
   if (
     (operation === 'push' || operation === undefined) &&
     (raw.includes('non-fast-forward') || raw.includes('fetch first'))
@@ -160,8 +128,7 @@ export function normalizeGitErrorMessage(error: unknown, operation?: GitRemoteOp
   }
 
   if (operation === 'push' && isPushHookFailure(raw)) {
-    // Why: local pre-push hooks put the actionable lint/hook output before
-    // git's generic "failed to push some refs" tail line.
+    // Why: pre-push hook output is the actionable part, printed before git's generic "failed to push some refs" tail line.
     return raw.trim()
   }
 
@@ -196,27 +163,11 @@ export function normalizeGitErrorMessage(error: unknown, operation?: GitRemoteOp
     return 'Pull would overwrite untracked files. Move, remove, or add them before pulling.'
   }
 
-  // Fallthrough: extract only the tail stderr line. `raw` was already
-  // credential-scrubbed at the top of the function, so no further scrub needed.
+  // Fallthrough: raw was already credential-scrubbed at top, so just extract the tail stderr line.
   return extractTailLine(raw)
 }
 
-// Why: we only swallow clearly-no-upstream signals — an expected state, not a
-// failure. Other errors ('not a git repository', 'corrupt', auth failures,
-// sparse-checkout errors, etc.) must fall through to the caller so users can
-// act on them. We explicitly avoid matching `HEAD@{u}` alone because execFile
-// wraps errors with "Command failed: git rev-parse --abbrev-ref HEAD@{u}…",
-// which would cause every non-repo/corrupt failure to spuriously look like
-// no-upstream. We also do NOT match 'no such branch' — that phrase is too
-// broad and can mask real errors on corrupt refs or sparse-checkout failures.
-// Additionally gate the phrase match on a `fatal:` prefix: git always
-// prefixes these diagnostics with `fatal:`, so requiring it prevents
-// `HEAD does not point` / `Needed a single revision` from matching unrelated
-// output (e.g. hook stdout, progress lines) and silently hiding real
-// corrupt-repo / unborn-HEAD / ambiguous-ref failures behind a spurious
-// "0 ahead / 0 behind, no upstream" UI state. The one ambiguous-ref
-// exception is HEAD@{u}: git emits it when branch config points at a
-// tracking ref that is missing locally, which is the same expected UX state.
+// Why: require a `fatal:` prefix so wrapped command text or hook/progress output can't spuriously match and mask real failures.
 const NO_UPSTREAM_PHRASE_PATTERN =
   /no upstream configured|no tracking information|HEAD does not point|Needed a single revision|ambiguous argument 'HEAD@\{u\}'/i
 const FATAL_PREFIX_PATTERN = /(^|\n)fatal:/i
diff --git a/src/shared/gitlab-types.ts b/src/shared/gitlab-types.ts
index 6b348247e34..5d007d7f923 100644
--- a/src/shared/gitlab-types.ts
+++ b/src/shared/gitlab-types.ts
@@ -1,37 +1,18 @@
-/* GitLab-specific shared types. Split out of `src/shared/types.ts` so
-   adding or changing a GitLab type doesn't surface as a merge conflict
-   on every upstream sync of the much larger central types file.
-   Imports the small base types (CheckStatus, ClassifiedError,
-   PRConflictSummary) it depends on; re-exported from `./types` for
-   import-stability — existing call sites (`from '../shared/types'`)
-   continue to work without changes. */
+/* GitLab-specific shared types, split from `./types` to avoid merge conflicts on upstream syncs; re-exported from `./types` for import stability. */
 import type { CheckStatus, ClassifiedError, PRConflictSummary } from './types'
 
-// Why: GitLab's analogue of `GitHubOwnerRepo`. Two structural differences
-// from GitHub make the flat owner/repo shape inadequate: (a) projects can
-// live under arbitrarily nested groups (`group/subgroup/project`), and
-// (b) self-hosted instances live on hostnames other than gitlab.com so the
-// host has to travel with the path for URL construction and glab host
-// targeting. Aliased as `ProjectRef` in `src/main/gitlab/gl-utils.ts`.
+// Why: flat owner/repo is inadequate — projects nest (`group/subgroup/project`) and self-hosted hosts must travel with the path for URL/glab targeting.
 export type GitLabProjectRef = { host: string; path: string }
 
 // ── GitLab MR / issue / work-item shapes ────────────────────────────
-// Why: parallel to the GitHub PR/Issue/WorkItem types above. Native
-// GitLab state strings are preserved (`opened` vs gh `open`) so we don't
-// have to remember whether a value has been mapped — every GitLab-side
-// type uses the API's own vocabulary.
+// Why: preserve native GitLab state strings (`opened`, not gh `open`) so values are never ambiguously mapped.
 
 export type MRState = 'opened' | 'closed' | 'merged' | 'locked' | 'draft'
 export type GitLabIssueState = 'opened' | 'closed'
-// Why: glab does not surface a structured "mergeable" field equivalent to
-// GitHub's GraphQL `mergeable`; we project the available signals
-// (`detailed_merge_status`, `has_conflicts`) onto the same three-value
-// shape used by GitHub's PRMergeableState so the UI can stay simple.
+// Why: glab has no structured `mergeable`; we project `detailed_merge_status`/`has_conflicts` onto GitHub's three-value shape.
 export type MRMergeableState = 'MERGEABLE' | 'CONFLICTING' | 'UNKNOWN'
 
-// Why: GitLab pipeline jobs and GitHub check-runs map onto the same
-// three-state lifecycle. Keep the field names identical to PRCheckDetail
-// so the rendering layer can share a row component.
+// Why: field names mirror PRCheckDetail so the rendering layer can share a row component.
 export type MRCheckDetail = {
   name: string
   status: 'queued' | 'in_progress' | 'completed'
@@ -55,8 +36,7 @@ export type MRInfo = {
   pipelineStatus: CheckStatus
   updatedAt: string
   mergeable: MRMergeableState
-  /** Full markdown description as authored on the MR. Optional because
-   *  list endpoints omit it; populated on single-MR fetch (`getMR`). */
+  /** Full markdown description. Optional — list endpoints omit it; populated on single-MR fetch (`getMR`). */
   description?: string
   /** Author username (GitLab `username`). Optional for the same reason. */
   author?: string | null
@@ -68,9 +48,7 @@ export type MRInfo = {
   conflictSummary?: PRConflictSummary
 }
 
-// Why: GitLab "emoji awards" are a richer set than GitHub's eight
-// reactions; rather than enumerate all of them, carry the raw award name
-// and let the renderer decide what to surface.
+// Why: GitLab emoji awards are open-ended, so we carry the raw award name and let the renderer decide.
 export type GitLabReaction = {
   name: string
   count: number
@@ -86,15 +64,13 @@ export type MRComment = {
   reactions?: GitLabReaction[]
   /** File path for inline review comments (absent for top-level discussion notes). */
   path?: string
-  /** GitLab discussion ID — present only for inline review comments. Used to
-   *  resolve/unresolve the discussion via `glab api`. */
+  /** GitLab discussion ID (inline review comments only). Used to resolve/unresolve via `glab api`. */
   threadId?: string
   /** Whether the discussion has been resolved. Only meaningful when threadId is set. */
   isResolved?: boolean
   line?: number
   startLine?: number
-  /** True when GitLab identifies the author as a bot (user `state === 'bot'`
-   *  or matching system user heuristics). Mirrors GitHub PRComment.isBot. */
+  /** True when GitLab marks the author as a bot. Mirrors GitHub PRComment.isBot. */
   isBot?: boolean
 }
 
@@ -113,11 +89,9 @@ export type GitLabIssueInfo = {
   state: GitLabIssueState
   url: string
   labels: string[]
-  /** ISO 8601 timestamp from the list endpoint. Optional because single-
-   *  issue fetches may not include it. */
+  /** ISO 8601 timestamp. Optional — single-issue fetches may omit it. */
   updatedAt?: string
-  /** Full markdown description as authored on the issue. Optional because
-   *  list endpoints omit it; populated on single-issue fetch (`getIssue`). */
+  /** Full markdown description. Optional — list endpoints omit it; populated on single-issue fetch (`getIssue`). */
   description?: string
   /** Author username — populated on single-issue fetch. */
   author?: string | null
@@ -192,16 +166,11 @@ export type GitLabWorkItem = {
   author: string | null
   branchName?: string
   baseRefName?: string
-  /** True when an MR's source branch lives in a fork project. The
-   *  Start-from picker mirrors GitHub's behavior and disables fork MRs in
-   *  v1 because resolving a fork head from the source branch alone is not
-   *  safe. */
+  /** True when an MR's source branch lives in a fork. Fork MRs are disabled in v1 — resolving a fork head from the source branch alone isn't safe. */
   isCrossRepository?: boolean
-  /** Stamped by the renderer fetcher / optimistic stubs so cross-project
-   *  views can attribute rows. Mirrors GitHubWorkItem.repoId. */
+  /** Stamped by the renderer so cross-project views can attribute rows. Mirrors GitHubWorkItem.repoId. */
   repoId: string
-  /** Exact GitLab project that produced this row. Mutations/details must use it
-   *  instead of re-resolving the repo preference later. */
+  /** Exact GitLab project that produced this row — mutations/details use it instead of re-resolving the repo preference. */
   projectRef?: GitLabProjectRef
 }
 
@@ -226,82 +195,56 @@ export type GitLabMRInlineCommentInput = {
   headSha: string
 }
 
-// Why: parallel of GitHubProjectSettings, scoped to plain GitLab
-// projects since v1 doesn't ship Projects-v2-style boards. Recent is
-// auto-tracked from the picker's paste-URL flow so users coming back to
-// projects they've recently visited don't have to re-paste the URL.
-// Pinned is reserved for a future UI affordance — defining the field
-// now keeps settings migrations simple later.
+// Why: mirrors GitHubProjectSettings. `pinned` is reserved for a future UI affordance — defined now to keep settings migrations simple.
 export type GitLabProjectSettings = {
   pinned: { host: string; path: string }[]
   recent: { host: string; path: string; lastOpenedAt: string }[]
 }
 
-// Why: GitLab Todos (gitlab.com/dashboard/todos) are cross-project
-// notifications — assigned items, mentions, build failures, review
-// requests, etc. The action_name field is open-ended in the API; we
-// keep it as a string so new GitLab versions don't break the type.
-// target_type narrows to the four shapes Orca renders meaningfully —
-// other values (DesignManagement::Design, AlertManagement::Alert)
-// fall back to a generic "open URL" treatment in the UI.
+// Why: only the four Todo target types Orca renders meaningfully; others (e.g. DesignManagement::Design) fall back to a generic "open URL".
 export type GitLabTodoTargetType = 'MergeRequest' | 'Issue' | 'Commit' | 'Note'
 
 export type GitLabTodo = {
   id: number
-  /** Free-form GitLab action name: 'assigned', 'mentioned', 'build_failed',
-   *  'marked', 'approval_required', 'review_requested', 'unmergeable', etc. */
+  /** Free-form GitLab action name, e.g. 'assigned', 'mentioned', 'build_failed', 'review_requested'. */
   actionName: string
   targetType: GitLabTodoTargetType | string
-  /** iid when target is an MR or Issue; '' for Commit/Note targets where the
-   *  identifier is a SHA or note ID instead. */
+  /** iid for MR/Issue targets; absent for Commit/Note targets where the identifier is a SHA or note ID. */
   targetIid: number | null
   targetTitle: string
   targetUrl: string
-  /** Project path (`group/subgroup/project`) for the target. Empty for
-   *  rare targets that aren't project-scoped. */
+  /** Project path (`group/subgroup/project`). Empty for targets that aren't project-scoped. */
   projectPath: string
-  /** Author of the action that produced the todo. Empty when the todo was
-   *  generated by the system (e.g. build_failed). */
+  /** Empty when the todo was system-generated (e.g. build_failed). */
   authorUsername: string
   authorAvatarUrl: string
   /** ISO timestamp from GitLab. */
   updatedAt: string
-  /** GitLab supports todos in 'pending' or 'done' state. v1 only fetches
-   *  pending; the field is on the type for future filter support. */
+  /** v1 only fetches 'pending'; 'done' is on the type for future filter support. */
   state: 'pending' | 'done'
 }
 
-// Why: per-job pipeline status — surfaces in the GitLab dialog Pipeline
-// tab so users can see which job failed and where without leaving Orca.
-// Mirrors PRCheckDetail's "single row per check" shape so the rendering
-// component is reusable.
+// Why: per-job pipeline status for the dialog's Pipeline tab. Mirrors PRCheckDetail so the rendering component is reusable.
 export type GitLabPipelineJob = {
   id: number
   pipelineId?: number
   name: string
   /** GitLab stage name, e.g. 'build' / 'test' / 'deploy'. */
   stage: string
-  /** Raw GitLab job status — 'success' / 'failed' / 'running' / 'pending'
-   *  / 'canceled' / 'skipped' / 'manual' / 'created' / 'preparing'. The
-   *  renderer maps to a colored pill via the existing status helpers. */
+  /** Raw GitLab job status — 'success' / 'failed' / 'running' / 'pending' / 'canceled' / 'skipped' / 'manual' / 'created' / 'preparing'. */
   status: string
   webUrl: string
   /** Duration in seconds. null when the job hasn't finished. */
   duration: number | null
 }
 
-// Why: aggregated detail payload for GitLabItemDialog. Parallel to
-// GitHubWorkItemDetails. Flattens discussion notes into a single comments
-// list — inline review-comment positioning is v1.5 work; this surface is
-// "read description + conversation + pipeline + act on it".
+// Why: aggregated detail for GitLabItemDialog; flattens discussions into one comments list (inline positioning is v1.5 work).
 export type GitLabWorkItemDetails = {
-  /** repoId is stamped by the renderer from the dialog's caller (TaskPage,
-   *  picker) — main-process doesn't know Orca's Repo.id. */
+  /** repoId is stamped by the renderer's caller — the main process doesn't know Orca's Repo.id. */
   item: Omit<GitLabWorkItem, 'repoId'>
   body: string
   comments: MRComment[]
-  /** MR head/base SHAs — populated for MRs only. Reserved for a future
-   *  Files tab; the dialog reads `body` for now. */
+  /** MR head/base SHAs — MRs only. Reserved for a future Files tab. */
   headSha?: string
   baseSha?: string
   startSha?: string
@@ -319,8 +262,7 @@ export type GitLabWorkItemDetails = {
 export type GitLabIssueUpdate = {
   state?: 'opened' | 'closed'
   title?: string
-  /** Why: `glab issue update` handles title/labels/assignees, while body edits
-   *  use the REST issue endpoint so mobile can save the markdown description. */
+  /** Body edits use the REST issue endpoint (not `glab issue update`) so mobile can save the markdown description. */
   body?: string
   addLabels?: string[]
   removeLabels?: string[]
@@ -335,14 +277,10 @@ export type GitLabMRUpdate = {
   removeLabels?: string[]
 }
 
-// Why: GitLab-native MR list filter — Open / Merged / Closed / All —
-// replaces GitHub's search-DSL on the GitLab tab per the agreed scope.
-// 'all' maps to no state filter (any state).
+// Why: GitLab-native MR list filter replacing GitHub's search-DSL; 'all' maps to no state filter.
 export type MRListState = 'opened' | 'merged' | 'closed' | 'all'
 
-// Why: paginated list result for both MRs and combined work-items.
-// totalCount / totalPages come from X-Total / X-Total-Pages response
-// headers via `glab api -i`, so the renderer can show "Page X of Y".
+// Why: totalCount / totalPages come from X-Total / X-Total-Pages headers via `glab api -i`.
 export type GitLabPagedResult<T> = {
   items: T[]
   page: number
diff --git a/src/shared/keybindings.ts b/src/shared/keybindings.ts
index 8dfba7e15b3..6b2860ced48 100644
--- a/src/shared/keybindings.ts
+++ b/src/shared/keybindings.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: the central shortcut registry, parser,
- * formatter, and conflict detector must stay in one shared module so main,
- * renderer, browser guests, and Settings cannot drift apart. */
+/* eslint-disable max-lines -- Why: keep the shortcut registry, parser, formatter, and conflict detector in one shared module so main/renderer/browser/Settings can't drift. */
 import type { TuiAgent } from './types'
 import { ALL_TUI_AGENTS, TUI_AGENT_DISPLAY_NAMES } from './tui-agent-display-names'
 
@@ -266,9 +264,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     scope: 'global',
     conflictGroup: 'workspace-shell',
     searchKeywords: ['shortcut', 'global', 'worktree', 'rename', 'workspace', 'title'],
-    // Why: macOS only. On Windows/Linux Ctrl+Alt+R has no safe default, and the
-    // chord families there (Ctrl+R reverse-search, Ctrl+Shift+R reload) are
-    // taken, so users bind it explicitly in Settings.
+    // Why: macOS only — Windows/Linux Ctrl+Alt+R has no safe default (Ctrl+R reverse-search, Ctrl+Shift+R reload are taken).
     defaultBindings: {
       darwin: ['Mod+Alt+R'],
       linux: [],
@@ -290,8 +286,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
       'remove',
       'trash'
     ],
-    // Why: ship the command now without claiming a default chord; user
-    // overrides still win automatically when a future default is assigned.
+    // Why: ship now without a default chord; user overrides still win when a future default is assigned.
     defaultBindings: platformBindings([]),
     allowInTerminal: true
   },
@@ -301,8 +296,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     group: 'Global',
     scope: 'global',
     searchKeywords: ['shortcut', 'global', 'workspace', 'board', 'kanban', 'worktree'],
-    // Why: make the command configurable without taking a global chord from
-    // terminal/browser/editor users by default.
+    // Why: configurable but unbound by default, to not take a global chord from terminal/browser/editor users.
     defaultBindings: platformBindings([]),
     allowInTerminal: true
   },
@@ -323,9 +317,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
       '1-9',
       'index'
     ],
-    // Why: one remappable row for the whole 1-9 range. The stored chord is a
-    // representative — its digit normalizes to 1, but the modifier set is what
-    // matters and any of 1-9 fires it. mac Cmd+1-9, Windows/Linux Ctrl+1-9 → Mod+1.
+    // Why: one remappable row covers the whole 1-9 range (stored chord is a representative; any of 1-9 fires it).
     defaultBindings: platformBindings(['Mod+1'])
   },
   {
@@ -420,8 +412,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
       'show',
       'hide'
     ],
-    // Why: ship unbound — issue #5209 asks to "assign a shortcut", so we avoid
-    // claiming a cross-platform chord and let users bind it in Settings.
+    // Why: ship unbound (issue #5209 asks users to assign it), avoiding a claimed cross-platform chord.
     defaultBindings: platformBindings([])
   },
   {
@@ -430,8 +421,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     group: 'Global',
     scope: 'global',
     searchKeywords: ['shortcut', 'sidebar', 'worktree', 'focus'],
-    // Why: keep zoom.reset on the browser-standard Mod+0; this chord was
-    // unreachable while it shared that default (#8584).
+    // Why: keep zoom.reset on the browser-standard Mod+0; this chord was unreachable while it shared that default (#8584).
     defaultBindings: platformBindings(['Mod+Shift+0'])
   },
   {
@@ -458,10 +448,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
       'maximize',
       'expand'
     ],
-    // Why: pairs with the floatingTerminal.toggle chord (Cmd+Opt+A) so
-    // maximize/restore lives on the same key anchor and stays one-handed,
-    // instead of the two-hand reach to Cmd+Opt+ArrowUp. macOS-only default;
-    // Linux/Windows stay unbound for users to assign.
+    // Why: pairs with floatingTerminal.toggle (Cmd+Opt+A) so maximize stays one-handed; macOS-only, Linux/Windows unbound.
     defaultBindings: {
       darwin: ['Mod+Alt+Shift+A'],
       linux: [],
@@ -484,9 +471,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
       'minimize',
       'hide'
     ],
-    // Why: intentionally unbound on every platform. floatingTerminal.toggle
-    // already owns the default show/hide chord; this action exists only so
-    // users can bind an explicit "hide the focused panel" shortcut in Settings.
+    // Why: unbound everywhere since floatingTerminal.toggle owns show/hide; this exists only for an explicit user-bound "hide panel" shortcut.
     defaultBindings: {
       darwin: [],
       linux: [],
@@ -550,9 +535,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     group: 'Tabs',
     scope: 'tabs',
     searchKeywords: ['shortcut', 'tab', 'agent', 'new', 'default', 'launch'],
-    // Why: macOS only. On Windows Ctrl+Alt is AltGr on many layouts, and on
-    // Linux Ctrl+Alt+T is the desktop-level "open terminal" shortcut, so
-    // there is no safe default chord there; users bind it in Settings.
+    // Why: macOS only — Windows Ctrl+Alt is AltGr and Linux Ctrl+Alt+T is the desktop "open terminal", so no safe default there.
     defaultBindings: {
       darwin: ['Mod+Alt+T'],
       linux: [],
@@ -573,8 +556,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     group: 'Tabs',
     scope: 'tabs',
     searchKeywords: ['shortcut', 'tab', 'simulator', 'emulator', 'mobile', 'ios', 'new'],
-    // Why: keep explorer on Mod+Shift+E (VS Code muscle memory). Emulator is
-    // macOS-only and less common, so it yields to a free chord (#8533).
+    // Why: keep explorer on Mod+Shift+E (VS Code muscle memory); emulator is macOS-only and less common, so it yields to a free chord (#8533).
     defaultBindings: {
       darwin: ['Mod+Alt+Shift+E'],
       linux: [],
@@ -620,9 +602,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     scope: 'tabs',
     conflictGroup: 'workspace-shell',
     searchKeywords: ['shortcut', 'tab', 'rename', 'title', 'label'],
-    // Why: macOS only. Cmd+R is free in the app/terminal focus zone (the
-    // browser pane owns its own Cmd+R reload). On Windows/Linux Ctrl+R is the
-    // shell reverse-search, so it is left unbound for explicit user binding.
+    // Why: macOS only — Cmd+R is free in app/terminal focus; on Windows/Linux Ctrl+R is shell reverse-search, so left unbound.
     defaultBindings: {
       darwin: ['Mod+R'],
       linux: [],
@@ -643,9 +623,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     group: 'Tab Navigation',
     scope: 'tabs',
     searchKeywords: ['shortcut', 'tab', 'next', 'switch', 'cycle'],
-    // Why: Mod+Shift+Bracket is the widespread "switch tab" chord, so it now
-    // drives the broad all-types cycle for new users; same-type moves to
-    // Mod+Alt. Pre-release installs keep the old mapping via the seed migration.
+    // Why: the widespread "switch tab" chord (Mod+Shift+Bracket) now drives all-types cycling; same-type moved to Mod+Alt for new installs.
     defaultBindings: platformBindings(['Mod+Alt+BracketRight'])
   },
   {
@@ -704,14 +682,9 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     title: 'Select Tab 1–9',
     group: 'Tab Navigation',
     scope: 'tabs',
-    // Why: deliberately no shared conflictGroup with workspace.selectByIndex.
-    // They live in different scopes, so swapping their modifiers (the headline
-    // use case) is never blocked as a false conflict; runtime stays deterministic
-    // because resolveWindowShortcutAction checks the workspace range first.
+    // Why: no shared conflictGroup with workspace.selectByIndex so swapping their modifiers isn't a false conflict; safe because resolveWindowShortcutAction checks the workspace range first.
     searchKeywords: ['shortcut', 'tab', 'select', 'switch', 'number', 'digit', '1-9', 'index'],
-    // Why: representative chord for the 1-9 range (see workspace.selectByIndex).
-    // mac Ctrl+1-9 (Cmd+1-9 is the workspace jump); Windows/Linux Alt+1-9
-    // (Ctrl+1-9 is the workspace jump), so each platform gets a free chord.
+    // Why: representative chord for the 1-9 range (see workspace.selectByIndex); each platform avoids the workspace-jump chord (Mod+1-9).
     defaultBindings: {
       darwin: ['Ctrl+1'],
       linux: ['Alt+1'],
@@ -723,8 +696,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     title: 'Toggle Quick Commands menu',
     group: 'Quick Commands',
     scope: 'tabs',
-    // Why: this tab-scoped action is also routed through the main window
-    // shortcut allowlist, so Settings must warn when it shadows global chords.
+    // Why: this tab-scoped action is also routed through the main-window allowlist, so Settings must warn when it shadows global chords.
     conflictGroup: 'global',
     searchKeywords: ['shortcut', 'quick', 'command', 'menu', 'tab', 'group', 'toggle'],
     defaultBindings: platformBindings([])
@@ -807,8 +779,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     group: 'Editors',
     scope: 'editor',
     searchKeywords: ['shortcut', 'editor', 'replace', 'find', 'search'],
-    // Why: match the source editor's native replace shortcut — Cmd+Alt+F on
-    // macOS, Ctrl+H on Linux/Windows.
+    // Why: match the source editor's native replace shortcut per platform.
     defaultBindings: {
       darwin: ['Mod+Alt+F'],
       linux: ['Mod+H'],
@@ -839,8 +810,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     searchKeywords: ['shortcut', 'editor', 'copy', 'context'],
     defaultBindings: platformBindings(['Mod+Alt+C'])
   },
-  // Why: F7 / Shift+F7 gives VS Code / JetBrains diff-change navigation. Function
-  // keys are safe as bare / Shift bindings, so both opt into allowBareKeybindings.
+  // Why: F7 / Shift+F7 mirror VS Code / JetBrains diff-change nav; function keys are safe bare/Shift, so both opt into allowBareKeybindings.
   {
     id: 'editor.previousChange',
     title: 'Go to Previous Change',
@@ -865,8 +835,7 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
     group: 'Editors',
     scope: 'editor',
     searchKeywords: ['shortcut', 'editor', 'markdown', 'note', 'comment', 'annotation', 'review'],
-    // Why: Ctrl+Alt+letter is AltGr text input on Windows/Linux; an editor-scope
-    // default must not reserve characters such as Polish `ń`.
+    // Why: Ctrl+Alt+letter is AltGr text input on Windows/Linux, so an editor default must not reserve chars like Polish `ń`.
     defaultBindings: platformBindings(['Mod+Shift+A'])
   },
   {
@@ -1068,18 +1037,13 @@ export const KEYBINDING_DEFINITIONS: readonly KeybindingDefinition[] = [
       linux: [],
       win32: []
     },
-    // Why: macOS permits Shift+Space as an input-source shortcut, while normal
-    // Orca actions reject Shift-only bindings to avoid stealing typed text.
+    // Why: macOS uses Shift+Space as an input-source shortcut; Orca otherwise rejects Shift-only bindings to avoid stealing typed text.
     allowShiftOnlyKeybindings: true
   },
   ...buildAgentTabKeybindingDefinitions()
 ]
 
-/**
- * The tab-switch bindings as they shipped before the convention swap. A one-time
- * migration pins these for pre-release installs so upgrading users keep the
- * shortcuts they learned; fresh installs get the new registry defaults above.
- */
+/** Pre-swap tab-switch bindings; a one-time migration pins these for pre-release installs so upgrading users keep the shortcuts they learned. */
 export const LEGACY_TAB_SWITCH_BINDINGS: Readonly<Partial<Record<KeybindingActionId, string[]>>> = {
   'tab.nextSameType': ['Mod+Shift+BracketRight'],
   'tab.previousSameType': ['Mod+Shift+BracketLeft'],
@@ -1091,9 +1055,7 @@ export function agentTabActionId(agent: TuiAgent): AgentTabActionId {
   return `tab.newAgent.${agent}`
 }
 
-// Why: one bindable action per agent so users can put each enabled agent on
-// its own chord. All ship unassigned — `tab.newAgent` covers the default
-// agent — and Settings → Shortcuts hides rows for disabled agents.
+// Why: one bindable action per agent; all ship unassigned since tab.newAgent covers the default, and Settings hides disabled agents.
 function buildAgentTabKeybindingDefinitions(): KeybindingDefinition[] {
   return ALL_TUI_AGENTS.map((agent) => ({
     id: agentTabActionId(agent),
@@ -1121,9 +1083,7 @@ const DEFINITION_IDS = new Set<KeybindingActionId>(
   KEYBINDING_DEFINITIONS.map((definition) => definition.id)
 )
 
-// Why: "Select Tab 1-9" / "Select Workspace 1-9" are single remappable rows
-// whose chord is a representative — the digit is canonicalized to 1, but the
-// binding fires for any of 1-9. These ids opt into that range behavior.
+// Why: these ids are single remappable rows whose chord is a representative — the digit canonicalizes to 1 but the binding fires for any 1-9.
 export const DIGIT_INDEX_ACTION_IDS: readonly KeybindingActionId[] = [
   'tab.selectByIndex',
   'workspace.selectByIndex'
@@ -1294,9 +1254,7 @@ function emptyParsedKeybinding(): ParsedKeybinding {
   return { mod: false, meta: false, control: false, alt: false, shift: false, key: '' }
 }
 
-// Why: a double-tap is a bare modifier with no key, so it cannot reuse the
-// normal "one key required" parse path; validation of conflicting/extra
-// modifiers is deferred to normalizeKeybindingWithOptions for shared errors.
+// Why: a double-tap is a bare modifier with no key, so it can't use the normal parse path; modifier validation is deferred to normalize.
 function parseDoubleTapKeybinding(rawParts: string[]): ParsedKeybinding | null {
   const modifiers: ModifierToken[] = []
   let sawDoubleTap = false
@@ -1321,8 +1279,7 @@ function parseDoubleTapKeybinding(rawParts: string[]): ParsedKeybinding | null {
   for (const modifier of modifiers) {
     applyModifierToken(parsed, modifier)
   }
-  // Mod combined with a platform-specific modifier: keep both flags so normalize
-  // emits the shared "Mod or platform-specific, not both" error.
+  // Keep both flags when Mod is combined with a platform modifier, so normalize emits the shared "Mod or platform-specific, not both" error.
   if (parsed.mod && (parsed.meta || parsed.control)) {
     parsed.doubleTapModifier = 'Mod'
     return parsed
@@ -1395,9 +1352,7 @@ function isSafeBareKey(parsed: ParsedKeybinding): boolean {
   if (parsed.mod || parsed.meta || parsed.control || parsed.alt) {
     return false
   }
-  // Function keys produce no text, so they're safe standalone or with Shift
-  // (e.g. F7 / Shift+F7 for diff-change navigation). Shift is only permitted
-  // alongside a function key — Shift+letter stays unsafe.
+  // Function keys produce no text, so they're safe bare or with Shift (Shift+letter stays unsafe).
   if (parsed.shift) {
     return isFunctionKeyToken(parsed.key)
   }
@@ -1516,11 +1471,7 @@ function normalizeOptionsForAction(actionId: KeybindingActionId): NormalizeKeybi
   }
 }
 
-// Why: a digit-index row stores one representative chord. Rewrite the key to 1
-// so display and conflict detection stay stable across the 1-9 range, and
-// reject anything that is not a number key 1-9. Extra modifiers (e.g. Shift) are
-// intentionally allowed — only the key must be a digit; parseKeybinding has
-// already enforced that at least one modifier is present.
+// Why: rewrite a digit-index chord's key to 1 so display and conflict detection stay stable across the 1-9 range; reject any non 1-9 key.
 function canonicalizeDigitIndexBinding(binding: string): KeybindingValidationResult {
   const parsed = parseKeybinding(binding)
   if (!parsed || parsed.doubleTapModifier || !DIGIT_INDEX_KEY_PATTERN.test(parsed.key)) {
@@ -1631,15 +1582,12 @@ function logicalKeyTokenFromInput(input: KeybindingInput): string | null {
 }
 
 function canUsePhysicalCodeFallback(input: KeybindingInput): boolean {
-  // Why: layout-aware shortcuts must trust real logical keys; physical code is
-  // only a fallback when the platform cannot report the produced key.
+  // Why: layout-aware shortcuts trust real logical keys; physical code is only a fallback when the platform can't report the produced key.
   return PHYSICAL_CODE_FALLBACK_KEYS.has(input.key ?? '')
 }
 
 function isLatinShortcutKey(key: string): boolean {
-  // Why: A-Z / 0-9 are the only single chars a Latin shortcut token names; any
-  // other produced character (Cyrillic с, Greek π, ...) cannot be a deliberate
-  // remap of a Latin chord, so it is safe to fall back to the physical code.
+  // Why: A-Z / 0-9 are the only chars a Latin shortcut names; a non-Latin char (Cyrillic с, Greek π) is never a Latin remap, so physical-code fallback is safe.
   if (key.length !== 1) {
     return false
   }
@@ -1651,12 +1599,7 @@ function shouldUseNonLatinShortcutPhysicalFallback(
   input: KeybindingInput,
   platform: NodeJS.Platform
 ): boolean {
-  // Why: non-Latin layouts (Cyrillic, Greek, ...) report a non-Latin logical key
-  // for physical letter keys (issue #6274), so Ctrl/Meta shortcuts never match.
-  // Fall back to the physical code, but only when no logical shortcut token
-  // exists, a real primary modifier (Ctrl or Meta) is held, and this is not an
-  // AltGr (Ctrl+Alt) text-composition event. macOS is excluded — it already has
-  // dedicated Option-composed fallbacks and Cmd shortcuts are layout-stable.
+  // Why: non-Latin layouts report non-Latin logical keys for physical letters (#6274), breaking Ctrl/Meta shortcuts; fall back to the physical code.
   if (getKeybindingPlatform(platform) === 'darwin') {
     return false
   }
@@ -1702,8 +1645,7 @@ function shouldUseMacOptionComposedCaptureFallback(
   input: KeybindingInput,
   platform: NodeJS.Platform
 ): boolean {
-  // Why: macOS Option+key reports composed characters (Option+C -> ç), so
-  // capturing Alt shortcuts needs the same physical-code fallback as matching.
+  // Why: macOS Option+key reports composed characters (Option+C -> ç), so capturing Alt shortcuts needs the physical-code fallback.
   if (
     getKeybindingPlatform(platform) !== 'darwin' ||
     !hasModifier(input, 'alt') ||
@@ -1740,8 +1682,7 @@ function keyTokenFromInput(input: KeybindingInput, platform: NodeJS.Platform): s
   return physicalCodeKeyTokenFromInput(input)
 }
 
-// Why: the platform primary modifier canonicalizes to Mod, mirroring normal
-// capture where Cmd on macOS / Ctrl elsewhere both become Mod.
+// Why: the platform primary modifier canonicalizes to Mod (Cmd on macOS / Ctrl elsewhere), mirroring normal capture.
 function canonicalDoubleTapToken(
   modifier: PhysicalModifierToken,
   platform: NodeJS.Platform
@@ -1839,9 +1780,7 @@ export function getEffectiveKeybindingsForAction(
   }
   const override = overrides?.[actionId]
   if (Array.isArray(override)) {
-    // Why: digit-index overrides resolve to their canonical <mods>+1 representative
-    // (deduped) so effective bindings stay consistent for display and conflict
-    // detection even if a hand-edited file stored a different digit.
+    // Why: canonicalize digit-index overrides to <mods>+1 so display/conflict stay consistent even if a hand-edited file stored a different digit.
     if (isDigitIndexActionId(actionId)) {
       const canonical: string[] = []
       for (const binding of override) {
@@ -1888,8 +1827,7 @@ export function keybindingIsActiveInContext(
   if (options.context !== 'terminal') {
     return true
   }
-  // Why: Orca-first preserves existing app shortcut behavior inside terminals.
-  // Terminal-first is the explicit escape hatch for shells and TUIs.
+  // Why: Orca-first keeps app shortcuts inside terminals; terminal-first is the escape hatch for shells and TUIs.
   if (normalizeTerminalShortcutPolicy(options.terminalShortcutPolicy) === 'orca-first') {
     return true
   }
@@ -1928,8 +1866,7 @@ function shouldUseMacOptionLetterPhysicalFallback(
   input: KeybindingInput,
   platform: NodeJS.Platform
 ): boolean {
-  // Why: macOS Option+letter can report composed characters (Option+A -> å),
-  // leaving no logical Latin key for app shortcuts that intentionally use Alt.
+  // Why: macOS Option+letter reports composed characters (Option+A -> å), leaving no logical Latin key for Alt shortcuts.
   return (
     getKeybindingPlatform(platform) === 'darwin' &&
     parsed.alt &&
@@ -1943,8 +1880,7 @@ function shouldUseMacOptionPunctuationPhysicalFallback(
   input: KeybindingInput,
   platform: NodeJS.Platform
 ): boolean {
-  // Why: macOS Option+punctuation can report composed quote/dead-key values,
-  // leaving no logical bracket token for app shortcuts that intentionally use Alt.
+  // Why: macOS Option+punctuation reports composed dead-key values, leaving no logical bracket token for Alt shortcuts.
   return (
     getKeybindingPlatform(platform) === 'darwin' &&
     parsed.alt &&
@@ -2001,8 +1937,7 @@ function shouldUseSemanticPunctuation(
   input: KeybindingInput,
   platform: NodeJS.Platform
 ): boolean {
-  // Why: Windows/Linux often expose AltGr as Ctrl+Alt. Do not turn ordinary
-  // international text input into Mod+Alt app shortcuts.
+  // Why: Windows/Linux expose AltGr as Ctrl+Alt; don't turn international text input into Mod+Alt app shortcuts.
   if (
     getKeybindingPlatform(platform) !== 'darwin' &&
     parsed.mod &&
@@ -2038,8 +1973,7 @@ function keyMatches(
   }
 
   if (isPunctuationKeyToken(parsedKey)) {
-    // Why: shortcut labels name logical punctuation, but international
-    // layouts can report the same character from different physical codes.
+    // Why: shortcut labels name logical punctuation, but international layouts can report it from different physical codes.
     const semanticKey = semanticPunctuationKey(input)
     if (semanticKey !== null) {
       if (!shouldUseSemanticPunctuation(parsed, input, platform)) {
@@ -2090,8 +2024,7 @@ export function keybindingMatchesInput(
   if (!parsed) {
     return false
   }
-  // A double-tap binding matches only a synthetic double-tap input, resolved per
-  // platform; a normal binding never matches a synthetic input, and vice-versa.
+  // A double-tap binding matches only a synthetic double-tap input (and vice-versa), resolved per platform.
   if (parsed.doubleTapModifier) {
     return (
       input.doubleTapModifier !== undefined &&
@@ -2176,11 +2109,7 @@ function digitFromInput(input: KeybindingInput, platform: NodeJS.Platform): stri
   return null
 }
 
-// Why: digit-index rows bind a representative chord but fire for 1-9. Reuse the
-// representative's modifier set with the pressed digit, then match it through the
-// normal input matcher so Mod/Cmd resolution and layout fallbacks stay shared.
-// Honors keybindingIsActiveInContext, so terminal-first focus disables the range
-// just like the scope-based gating for every other shortcut.
+// Why: a digit-index row's representative chord fires for any 1-9 — reuse its modifiers with the pressed digit via the normal matcher.
 export function matchKeybindingDigitIndex(
   actionId: KeybindingActionId,
   input: KeybindingInput,
@@ -2323,8 +2252,7 @@ export function findKeybindingConflicts(
     for (const binding of getEffectiveKeybindingsForAction(definition.id, platform, overrides)) {
       const groups = new Set([definition.conflictGroup ?? definition.scope])
       if (definition.conflictGroup) {
-        // Why: native menu accelerators can still consume global chords, so custom
-        // renderer bindings must be checked against both the menu bucket and scope.
+        // Why: native menu accelerators can consume global chords, so check custom bindings against both the menu bucket and scope.
         groups.add(definition.scope)
       }
       for (const group of groups) {
diff --git a/src/shared/quick-open-filter.ts b/src/shared/quick-open-filter.ts
index 899d13aeaa3..a0ac929bea1 100644
--- a/src/shared/quick-open-filter.ts
+++ b/src/shared/quick-open-filter.ts
@@ -1,29 +1,17 @@
 /**
- * Shared, pure Quick Open (Cmd/Ctrl+P) file-listing filter policy used by both
- * the local main process and the SSH relay. No IO, no Electron, no WSL, no
- * auth — callers own process execution and transport-specific path translation.
+ * Shared, pure Quick Open (Cmd/Ctrl+P) file-listing filter policy used by both the local main
+ * process and the SSH relay. No IO, Electron, WSL, or auth — callers own process execution and
+ * transport-specific path translation.
  *
- * Why this module exists (design doc: docs/design/share-quick-open-file-listing.md):
- * Before extraction, the local and relay listFiles implementations had diverged
- * on blocklist, ignored-file handling, nested-worktree exclusions, timeout
- * strategy, and buffering. A home-dir worktree over SSH would descend into $HOME dotfile
- * caches, hit a 10s timeout, and silently resolve with a partial result —
- * Quick Open showed "No matching files" even though the scan was incomplete.
- * Centralizing the policy prevents future drift.
+ * Centralized to stop local/relay listFiles from drifting on blocklist, ignores, exclusions,
+ * timeouts, and buffering. See docs/design/share-quick-open-file-listing.md.
  */
 import { posix, win32 } from 'node:path'
 
 // ─── Hidden-dir blocklist ────────────────────────────────────────────
 
-// Why: with rg --hidden we surface dotfiles users commonly edit (.env,
-// .github/*, .eslintrc). A blocklist (not an allowlist) keeps novel dotfiles
-// discoverable by default; the entries here are tool-generated caches / state
-// that are never hand-edited. Do NOT add broad user-authored dotdirs like
-// .config, .ssh, .gnupg, .github, .devcontainer — users open files in them.
-//
-// .npm, .npm-global, .local/share, .gvfs added for the home-root failure
-// (design doc): these are generated package cache, install state, desktop
-// runtime state — not normal project source.
+// Blocklist (not allowlist) keeps novel dotfiles discoverable; entries here are tool-generated
+// caches/state, never hand-edited. Do NOT add user-authored dotdirs (.config, .ssh, .github) — users open files there.
 export const HIDDEN_DIR_BLOCKLIST: ReadonlySet<string> = new Set([
   '.git',
   '.next',
@@ -37,19 +25,16 @@ export const HIDDEN_DIR_BLOCKLIST: ReadonlySet<string> = new Set([
   '.terraform',
   '.docker',
   '.husky',
-  // Home-dir cache/install/runtime state that caused the original bug when
-  // a worktree rooted at $HOME let rg descend for 10s before timing out.
+  // Home-dir cache/install/runtime state; caused the original $HOME-root 10s-timeout bug.
   '.npm',
   '.npm-global',
   '.gvfs'
 ])
 
-// `.local` itself can contain user-authored files; only the generated desktop
-// runtime subtree is part of the home-root failure blocklist.
+// `.local` may hold user files; block only the generated `.local/share` runtime subtree.
 const HIDDEN_PATH_BLOCKLIST: readonly string[] = ['.local/share']
 
-// Kept separate from HIDDEN_DIR_BLOCKLIST because node_modules is not a
-// dotfile dir, but it must still be pruned from every traversal.
+// Separate from HIDDEN_DIR_BLOCKLIST: node_modules isn't a dotdir but must still be pruned.
 const NON_DOTTED_PRUNE = 'node_modules'
 
 function containsBlockedRelPath(path: string, blockedPath: string): boolean {
@@ -62,14 +47,9 @@ function containsBlockedRelPath(path: string, blockedPath: string): boolean {
 }
 
 /**
- * Returns true if `relPath` (a `/`-separated, root-relative path) does not
- * traverse through any blocklisted directory segment. Used as a correctness
- * backstop after the rg/git traversal-pruning globs — if a blocklisted dir
- * slips through (e.g., via a glob edge case), this filter still drops it.
- *
- * Why: walks the string segment-by-segment without allocating a split array,
- * since this is called once per listed file and large repos produce ~100k
- * files.
+ * Returns true if `path` (`/`-separated, root-relative) traverses no blocklisted segment.
+ * Correctness backstop after the rg/git pruning globs, in case a blocked dir slips through.
+ * Walks segment-by-segment (no split allocation) since it runs once per file on ~100k-file repos.
  */
 export function shouldIncludeQuickOpenPath(path: string): boolean {
   for (const blockedPath of HIDDEN_PATH_BLOCKLIST) {
@@ -95,10 +75,7 @@ export function shouldIncludeQuickOpenPath(path: string): boolean {
 
 // ─── Path flavor detection ───────────────────────────────────────────
 
-// Why: buildExcludePathPrefixes must run correctly even when the main process
-// OS differs from the remote relay OS (macOS app talking to a Linux relay, or
-// Windows app talking to a Linux relay). path.relative from the local OS is
-// wrong for remote roots — pick win32 vs posix based on the root's shape.
+// Why: local-OS path.relative is wrong for remote roots (app OS vs relay OS); pick win32 vs posix by root shape.
 function pathFlavor(rootPath: string): typeof posix | typeof win32 {
   // Drive letter like C:\ or C:/
   if (/^[a-zA-Z]:[\\/]/.test(rootPath)) {
@@ -114,16 +91,9 @@ function pathFlavor(rootPath: string): typeof posix | typeof win32 {
 // ─── Exclude-path normalization ──────────────────────────────────────
 
 /**
- * Normalize `excludePaths` (absolute paths sent by the renderer for nested
- * worktrees) into `/`-separated, root-relative prefixes. Returns empty array
- * on any malformed input — the request must not fail if the renderer sends a
- * stale or typo'd exclude path.
- *
- * Design doc notes:
- * - Missing, non-array, non-string, empty, outside-root, and root-equal
- *   values are silently ignored.
- * - Always returns `/`-separated strings because rg globs and the shared
- *   Quick Open policy compare `/`-separated paths.
+ * Normalize `excludePaths` (renderer-sent absolute paths for nested worktrees) into `/`-separated,
+ * root-relative prefixes. Malformed/outside-root/root-equal values are silently dropped so a stale
+ * or typo'd exclude path can't fail the request.
  */
 export function buildExcludePathPrefixes(rootPath: string, excludePaths?: unknown): string[] {
   if (!Array.isArray(excludePaths)) {
@@ -147,8 +117,7 @@ export function buildExcludePathPrefixes(rootPath: string, excludePaths?: unknow
     }
     rel = rawFwd.startsWith(normalizedRoot)
       ? rawFwd.slice(normalizedRoot.length)
-      : // Fall back to path-flavor relative so we do not accidentally use the
-        // local OS's semantics on remote paths.
+      : // Fall back to path-flavor relative so remote paths don't get local-OS semantics.
         flavor.relative(trimmedRoot, raw).replace(/\\/g, '/')
     if (!rel || isParentRelativePath(rel) || rel.startsWith('/')) {
       continue
@@ -164,12 +133,8 @@ export function buildExcludePathPrefixes(rootPath: string, excludePaths?: unknow
 }
 
 /**
- * Segment-boundary exclude check. `relPath` is `/`-separated, root-relative.
- * Returns true iff `relPath === prefix` or `relPath` starts with `prefix + '/'`.
- *
- * Why: a raw `startsWith` would match `packages/app2` against an exclusion
- * for `packages/app`. This guard is required wherever exclude prefixes are
- * used as a post-filter (git and readdir paths).
+ * Segment-boundary exclude check (`relPath` is `/`-separated, root-relative).
+ * Why segment boundary: a raw `startsWith` would match `packages/app2` against exclusion `packages/app`.
  */
 export function shouldExcludeQuickOpenRelPath(
   relPath: string,
@@ -188,9 +153,7 @@ export function shouldExcludeQuickOpenRelPath(
 
 // ─── Glob escaping ───────────────────────────────────────────────────
 
-// rg/git glob metacharacters. Escape them when a user-supplied or directory
-// name is embedded into a glob, so a directory literally named `feature[1]`
-// does not silently exclude `feature1`.
+// rg/git glob metacharacters; escape embedded dir names so a dir named `feature[1]` doesn't exclude `feature1`.
 const GLOB_META = new Set<string>(['*', '?', '[', ']', '{', '}', '\\'])
 
 function escapeGlob(segment: string): string {
@@ -215,11 +178,9 @@ function isParentRelativePath(relPath: string): boolean {
 // ─── rg traversal-pruning globs ──────────────────────────────────────
 
 /**
- * Build the hidden-dir traversal-pruning glob args for rg (includes
- * `node_modules`). Uses the directory-match form `!**\/name` instead of the
- * contents form `!**\/name/**` because rg still descends into a directory
- * matched only by the contents form to enumerate entries — the directory
- * form is what actually prunes traversal of huge caches under $HOME.
+ * Build the hidden-dir traversal-pruning glob args for rg (includes `node_modules`).
+ * Uses directory-match form `!**\/name` not contents form `!**\/name/**`: rg still descends into a
+ * dir matched only by the contents form, so only the directory form actually prunes traversal.
  */
 export function buildHiddenDirExcludeGlobs(): string[] {
   const names = [NON_DOTTED_PRUNE, ...HIDDEN_DIR_BLOCKLIST]
@@ -236,9 +197,7 @@ export function buildHiddenDirExcludeGlobs(): string[] {
 // ─── rg arg builder ──────────────────────────────────────────────────
 
 export type RgArgsOptions = {
-  /** What to pass to rg as the positional search target — pass the absolute
-   *  root path when you plan to strip that prefix from output, or `.` when
-   *  you prefer cwd-relative output (both require cwd: rootPath). */
+  /** rg positional search target: absolute root (strip prefix from output) or `.` (cwd-relative); both need cwd: rootPath. */
   searchRoot: string
   /** Root-relative, `/`-separated prefixes (from buildExcludePathPrefixes). */
   excludePathPrefixes: readonly string[]
@@ -254,23 +213,16 @@ export type RgArgs = {
 }
 
 /**
- * Build the two rg arg arrays for Quick Open. The caller is responsible for
- * spawning rg with `cwd: rootPath`; root-relative globs like `!packages/app`
- * are evaluated against rg's working directory, so omitting `cwd` silently
- * breaks nested-worktree exclusions.
- *
- * The builder deliberately does not emit `--follow`: rg --files does not
- * follow symlinks by default, and enabling it on a home-dir root risks
- * escaping the authorized root (symlinks into /mnt, /tmp, other users' homes)
- * and hitting traversal loops.
+ * Build the two rg arg arrays for Quick Open. Caller must spawn with `cwd: rootPath` — root-relative
+ * globs are evaluated against rg's cwd, so omitting it silently breaks nested-worktree exclusions.
+ * Deliberately omits `--follow` so symlinks can't escape the authorized root or cause traversal loops.
  */
 export function buildRgArgsForQuickOpen(opts: RgArgsOptions): RgArgs {
   const sepArgs = opts.forceSlashSeparator ? ['--path-separator', '/'] : []
   const hiddenDirGlobs = buildHiddenDirExcludeGlobs()
   const excludeGlobs: string[] = []
   for (const prefix of opts.excludePathPrefixes) {
-    // Use directory-match form so rg prunes traversal of the nested worktree
-    // entirely, not just drops already-listed files from it.
+    // Directory-match form so rg prunes the nested worktree's traversal, not just its listed files.
     excludeGlobs.push('--glob', `!${escapeGlobPath(prefix)}`)
     excludeGlobs.push('--glob', `!${escapeGlobPath(prefix)}/**`)
   }
@@ -284,8 +236,7 @@ export function buildRgArgsForQuickOpen(opts: RgArgsOptions): RgArgs {
     opts.searchRoot
   ]
 
-  // Ignored pass: --no-ignore-vcs broadens traversal to gitignored and
-  // parent/global ignored files; blocklist globs remain the guardrail.
+  // Ignored pass: --no-ignore-vcs broadens to gitignored/parent/global ignored files; blocklist globs still guard.
   const ignoredPass = [
     '--files',
     '--hidden',
@@ -304,15 +255,13 @@ export function buildRgArgsForQuickOpen(opts: RgArgsOptions): RgArgs {
 export type RgOutputMode =
   /** rg was invoked with an absolute search target; output paths are absolute. */
   | { kind: 'absolute'; rootPath: string }
-  /** rg was invoked with cwd: rootPath and searchRoot '.'; output is cwd-relative
-   *  and typically prefixed with `./`. */
+  /** rg invoked with cwd: rootPath and searchRoot '.'; output is cwd-relative, usually `./`-prefixed. */
   | { kind: 'cwd-relative' }
 
 /**
  * Convert one rg --files stdout line into a root-relative, `/`-separated path.
- * Returns `null` for lines that escape the root (symlink resolution edge cases)
- * or cannot be normalized. The main-process caller is responsible for any WSL
- * translation before calling this — keeping WSL out of the shared module.
+ * Returns `null` for lines that escape the root (symlink edge cases) or can't be normalized.
+ * Callers do any WSL translation first, keeping WSL out of the shared module.
  */
 export function normalizeQuickOpenRgLine(rawLine: string, outputMode: RgOutputMode): string | null {
   let line = rawLine
@@ -337,9 +286,7 @@ export function normalizeQuickOpenRgLine(rawLine: string, outputMode: RgOutputMo
     return rel
   }
   // Absolute mode: strip the root prefix.
-  // Why: replace only backslashes here. Collapsing repeated slashes breaks
-  // Windows UNC roots (`\\server\share` -> `//server/share`) by turning them
-  // into single-slash POSIX-looking paths that no rg output can match.
+  // Why: only replace backslashes; collapsing repeated slashes would break Windows UNC roots (`\\server\share`).
   const normalizedRoot = `${outputMode.rootPath.replace(/\\/g, '/').replace(/\/+$/, '')}/`
   if (normalized.startsWith(normalizedRoot)) {
     const rel = normalized.substring(normalizedRoot.length)
@@ -359,13 +306,8 @@ export type GitLsFilesArgs = {
 }
 
 /**
- * Build the two `git ls-files` arg arrays for Quick Open. Exclude prefixes
- * are encoded as `:(exclude,glob)` pathspecs; a positive `.` pathspec is
- * prepended so exclude-only pathspecs do not depend on git's edge-case
- * defaults.
- *
- * The ignored pass asks git for ignored untracked files. Non-git roots keep
- * their existing non-git fallback limits in the callers.
+ * Build the two `git ls-files` arg arrays for Quick Open. A positive `.` pathspec is prepended
+ * so the exclude-only `:(exclude,glob)` pathspecs don't depend on git's edge-case defaults.
  */
 export function buildGitLsFilesArgsForQuickOpen(
   excludePathPrefixes: readonly string[] = []
@@ -376,12 +318,10 @@ export function buildGitLsFilesArgsForQuickOpen(
     excludeSpecs.push(`:(exclude,glob)${escapeGlobPath(prefix)}/**`)
   }
   const trailingPathspecs = excludeSpecs.length > 0 ? ['--', '.', ...excludeSpecs] : []
-  // Why: collapse untracked trees before Git traverses them; callers expand
-  // only allowed directory placeholders with the shared bounded walker.
+  // Why: collapse untracked trees so callers expand only allowed dir placeholders via the bounded walker.
   const directoryCollapseArgs = ['--directory', '--no-empty-directory']
 
-  // Why: NUL preserves real Git paths; stage mode identifies gitlinks without
-  // lstat probes for ordinary tracked files.
+  // Why: -z NUL preserves real Git paths; -s stage mode identifies gitlinks without lstat probes.
   const primary = [
     '-z',
     '-s',
diff --git a/src/shared/secure-file.ts b/src/shared/secure-file.ts
index 1ed451b5633..90bfd5d6df9 100644
--- a/src/shared/secure-file.ts
+++ b/src/shared/secure-file.ts
@@ -24,36 +24,20 @@ type HardenedPathCacheEntry = {
   birthtimeMs: number
 }
 
-// Why: hardening shells out to PowerShell on Windows (~1-1.5s each). Re-hardening a path
-// whose ACLs we already applied in this process is wasted work that stalls the main thread,
-// so cache idempotent calls. The post-rename target write is NOT routed through this — it
-// always re-hardens (new inode) and then refreshes the cache entry.
+// Why: PowerShell hardening (~1-1.5s) stalls the main thread, so cache idempotent re-hardens per process.
 const hardenedPathsThisProcess = new Map<string, HardenedPathCacheEntry>()
 
-// Why: a directory's required ACL does not change because its mtime changed (child writes
-// update the directory's mtime constantly). Keying the directory cache on mtime/ctime causes
-// a cache miss — and a blocking PowerShell spawn — on every read-path call. We instead cache
-// directory hardening by PATH for the entire process lifetime: once a directory's ACL has
-// been applied in this process we trust it stays correct. Files keep the metadata-keyed cache
-// so that post-rename inode changes are detected correctly. See #4901 regression report.
-//
-// Known limitation: because this is a process-lifetime path cache, a directory that is deleted
-// and recreated during the same process will NOT be re-hardened. The secure dirs we own
-// (.orca runtime/auth/device stores) are not deleted at runtime, so this is acceptable; the
-// next process restart re-hardens. Do not rely on this cache if a path's lifecycle changes.
+// Why: child writes constantly bump a dir's mtime, so cache dirs by path (not metadata) to avoid a PowerShell spawn every read (#4901).
+// Limitation: a dir deleted+recreated in-process won't re-harden; fine since we never delete our secure dirs at runtime.
 const hardenedDirectoryPathsThisProcess = new Set<string>()
 
 function hardenSecureDirectoryOnce(dirPath: string): void {
-  // Why: directory hardening is async + path-cached. The directory ACL is broad-but-bounded
-  // (current user + SYSTEM + Administrators) and re-applying it is what stormed the main
-  // thread (#4901), so we never block on it. A pending dir ACL on first run is acceptable
-  // because the credential FILES inside it are hardened synchronously on the write path.
+  // Why: dir hardening stays async — re-applying it stormed the main thread (#4901); files inside are hardened synchronously anyway.
   if (hardenedDirectoryPathsThisProcess.has(dirPath)) {
     return
   }
   applySecurePathRestriction(dirPath, true, process.platform, false)
-  // Optimistic: cache even though the async ACL may still be in flight. The dir restriction
-  // is best-effort and re-running it does not improve security, so we accept no-retry here.
+  // Cache even though the async ACL may still be in flight — dir restriction is best-effort, no retry.
   hardenedDirectoryPathsThisProcess.add(dirPath)
 }
 
@@ -71,10 +55,7 @@ function hardenSecurePathOnce(targetPath: string, isDirectory: boolean): boolean
   if (currentEntry && cachedEntry && hardenedPathCacheEntriesMatch(currentEntry, cachedEntry)) {
     return true
   }
-  // Why: the read path re-hardens an existing file at most once per process (metadata-cached
-  // above), so async file hardening here does not storm. The async restriction only re-asserts
-  // an ACL on a file that already exists; new credential files are hardened synchronously on
-  // the write path (see writeSecureFile), so there is no async window on creation.
+  // Why: async re-harden is safe here — read path hardens each file at most once/process; new files harden synchronously on the write path.
   if (applySecurePathRestriction(targetPath, isDirectory, process.platform, false)) {
     rememberHardenedPath(targetPath, isDirectory)
     return true
@@ -91,8 +72,7 @@ export function writeSecureFile(targetPath: string, contents: string): void {
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true, mode: 0o700 })
   }
-  // Windows directory hardening stays async + path-cached: it is what stormed the main thread
-  // (#4901). POSIX keeps the metadata cache so chmod/ctime changes are corrected.
+  // Windows dir hardening stays async + path-cached (it stormed the main thread, #4901); POSIX keeps the metadata cache to catch chmod/ctime drift.
   hardenSecurePathOnce(dir, true)
 
   const tmpFile = `${targetPath}.${process.pid}.${Date.now()}.${randomBytes(4).toString('hex')}.tmp`
@@ -101,17 +81,10 @@ export function writeSecureFile(targetPath: string, contents: string): void {
       encoding: 'utf-8',
       mode: 0o600
     })
-    // Why: on Windows writeFileSync({mode:0o600}) is a no-op, so the file is created carrying
-    // the parent directory's inherited (broader) ACL. We must restrict the credential file's
-    // ACL SYNCHRONOUSLY before the atomic rename publishes it — otherwise writeSecureFile
-    // would return with the credential readable under inherited ACLs for the ~1-1.5s PowerShell
-    // cold-start window. The write path is infrequent, so the synchronous cost is acceptable;
-    // it is the READ path that stormed (#4901), and that stays async + cached.
+    // Why: writeFileSync mode is a no-op on Windows, so restrict the credential's ACL synchronously before the rename publishes it under inherited ACLs.
     applySecurePathRestriction(tmpFile, false, process.platform, true)
     renameSync(tmpFile, targetPath)
-    // Why: these files carry runtime auth/device credentials; the published
-    // path must remain current-user only after the atomic rename. Apply synchronously and only
-    // cache on confirmed success so a failed ACL apply is retried on the next read/write.
+    // Why: these hold auth credentials, so the published path must stay current-user only; cache only on confirmed success so failures retry.
     if (applySecurePathRestriction(targetPath, false, process.platform, true)) {
       rememberHardenedPath(targetPath, false)
     }
@@ -157,15 +130,10 @@ function applySecurePathRestriction(
 ): boolean {
   if (platform === 'win32') {
     if (sync) {
-      // Why: the write path must apply the credential FILE's ACL before returning, otherwise
-      // the file is briefly readable under inherited (broader) ACLs (writeFileSync mode is a
-      // no-op on Windows). Run PowerShell synchronously and report real success so callers only
-      // cache the path as hardened when the ACL actually applied. The write path is infrequent.
+      // Why: apply the ACL synchronously so the credential file isn't briefly readable under inherited ACLs (writeFileSync mode is a no-op on Windows).
       return restrictWindowsPathSync(targetPath, isDirectory)
     }
-    // Why: the directory and read-path re-harden are async (fire-and-forget) to avoid blocking
-    // the main thread (#4901). We optimistically return true because the restriction is
-    // best-effort; the cache entry is written immediately so we do not re-spawn on the next call.
+    // Why: dir/read-path re-harden runs async to avoid blocking the main thread (#4901); return true optimistically since it's best-effort.
     bestEffortRestrictWindowsPath(targetPath, isDirectory)
     return true
   }
@@ -251,11 +219,7 @@ function bestEffortRestrictWindowsPath(targetPath: string, isDirectory: boolean)
   if (!currentUserSid) {
     return
   }
-  // Why: execFile (async) is used instead of execFileSync to avoid blocking the Electron main
-  // thread. PowerShell cold-start is ~1–1.5 s; spawning it synchronously on every read-path
-  // call saturated the main thread in v1.4.52+ where the env-store is read ~2×/s by the
-  // remote-runtime tab-sync loop (#4901 regression). The restriction is best-effort
-  // (see function name), so it is safe to apply it in the background.
+  // Why: async to avoid blocking the main thread — sync PowerShell cold-start (~1-1.5s) on the frequent read path stormed it (#4901).
   execFile(
     getWindowsSystemToolPath('WindowsPowerShell\\v1.0\\powershell.exe'),
     buildWindowsRestrictAclArgs(targetPath, currentUserSid, isDirectory),
@@ -264,9 +228,7 @@ function bestEffortRestrictWindowsPath(targetPath: string, isDirectory: boolean)
       timeout: 5000
     },
     () => {
-      // Why: errors are intentionally ignored — credential-file hardening should not
-      // prevent Orca from starting on Windows machines where PowerShell ACL APIs are
-      // unavailable or locked down.
+      // Why: ignore errors — hardening is best-effort; PowerShell ACL APIs may be unavailable or locked down.
     }
   )
 }
@@ -276,10 +238,7 @@ function restrictWindowsPathSync(targetPath: string, isDirectory: boolean): bool
   if (!currentUserSid) {
     return false
   }
-  // Why: synchronous variant for the credential-FILE write path only. The file must not be
-  // published (renamed into place / returned to the caller) until its ACL has actually been
-  // restricted, so we block here and report real success. This is the rare path; the frequent
-  // read path stays async (bestEffortRestrictWindowsPath) to avoid the #4901 main-thread storm.
+  // Why: file must not be published until its ACL is actually restricted, so block and report real success (read path stays async, #4901).
   try {
     execFileSync(
       getWindowsSystemToolPath('WindowsPowerShell\\v1.0\\powershell.exe'),
@@ -292,8 +251,7 @@ function restrictWindowsPathSync(targetPath: string, isDirectory: boolean): bool
     )
     return true
   } catch {
-    // Why: best-effort — a failed ACL apply (locked-down PowerShell, etc.) must not crash the
-    // write. Returning false leaves the path uncached so a later read/write retries it.
+    // Why: best-effort — a failed ACL apply must not crash the write; false leaves the path uncached to retry later.
     return false
   }
 }
diff --git a/src/shared/telemetry-events.ts b/src/shared/telemetry-events.ts
index f7f43c076d9..cb0d3f32236 100644
--- a/src/shared/telemetry-events.ts
+++ b/src/shared/telemetry-events.ts
@@ -1,17 +1,7 @@
 /* eslint-disable max-lines -- Why: this is the single source of truth for every telemetry event schema, enum, and the cohort-injection set predicates. Splitting it would scatter the .strict() / Zod-first doctrine across files and break the EventMap derivation that makes adding an event a one-line change. */
 // Single source of truth for telemetry event names, schemas, and enums.
-//
-// Zod-first: every event schema is declared once and the compile-time
-// `EventMap` is `z.infer`-derived from the same record the runtime validator
-// consumes. There is no parallel `EVENT_SPEC` / hand-rolled union to drift
-// out of sync with. Adding an event means adding a schema to `eventSchemas`;
-// `EventMap` picks it up automatically and call sites that reference an
-// unknown event name fail `tsc`.
-//
-// `.strict()` on every object schema is the runtime counterpart to "no extra
-// keys." Free-form string fields carry an explicit `.max(N)` cap at the
-// schema — the cap and the schema are the same thing; the validator does not
-// re-check string length.
+// Zod-first: `EventMap` is `z.infer`-derived from the same `eventSchemas` record the runtime validator consumes — no parallel union to drift.
+// `.strict()` on every object schema is the runtime "no extra keys"; free-form strings carry an explicit `.max(N)` cap.
 
 import { z } from 'zod'
 import { FEATURE_WALL_MAX_DWELL_MS } from './feature-wall-telemetry'
@@ -62,12 +52,7 @@ import type {
 
 // ── Shared property enums ───────────────────────────────────────────────
 
-// Mirrors the shipped `TuiAgent` launch surface, with one deliberate shift:
-// `claude` in settings/launch state ↔ `claude-code` here (product, not CLI
-// string) so dashboards read cleanly.
-//
-// `other` remains as a telemetry escape hatch, but project-owned TuiAgents
-// should map to concrete values; see `tuiAgentToAgentKind`.
+// Mirrors `TuiAgent` launch surface; `claude`↔`claude-code` (product, not CLI string). `other` is the escape hatch; see `tuiAgentToAgentKind`.
 export const AGENT_KIND_VALUES = [
   'claude-code',
   'claude-agent-teams',
@@ -108,31 +93,15 @@ export const AGENT_KIND_VALUES = [
 export const agentKindSchema = z.enum(AGENT_KIND_VALUES)
 export type AgentKind = z.infer<typeof agentKindSchema>
 
-// Trimmed to a small set of values Orca's PTY-typed-command launch architecture
-// can emit:
-//   - `binary_not_found` — `provider.spawn` ENOENT (the *shell* binary is
-//     missing). The agent CLI being missing is invisible: Orca spawns a
-//     healthy shell and types the command, and bash/zsh's "command not found"
-//     surfaces only as terminal output.
-//   - `paste_readiness_timeout` — bracketed-paste readiness wait timed out.
-//     The agent process spawned but its TUI input box didn't reach a ready
-//     state before the watchdog deadline, so the queued draft was dropped.
-//   - `unknown` — every other thrown error (env-build failures,
-//     unclassifiable shell-spawn errors).
-// Provider-side errors (`auth_expired`, `rate_limited`, `network_timeout`,
-// `provider_*`) happen inside the agent CLI subprocess and are not observable
-// to Orca — see telemetry-plan.md §Decision: Defer per-incident error fields.
-// Adding a new value is additive-safe; do it when the call site lands, not in
-// anticipation.
+// Small set: only failures Orca's PTY-typed-command launch can observe (`binary_not_found` = shell ENOENT, `paste_readiness_timeout`, `unknown`).
+// Provider-side errors (auth/rate-limit/network) happen inside the agent CLI subprocess and are invisible to Orca. See telemetry-plan.md §Defer per-incident error fields.
 export const errorClassSchema = z.enum(['binary_not_found', 'paste_readiness_timeout', 'unknown'])
 export type ErrorClass = z.infer<typeof errorClassSchema>
 
 export const repoMethodSchema = z.enum(['folder_picker', 'clone_url', 'drag_drop'])
 export type RepoMethod = z.infer<typeof repoMethodSchema>
 
-// Historical setup-step affordances users could pick after `repo_added` fired.
-// Current Add Project flows skip that choice screen and auto-open the default
-// checkout, but the schema stays for pre-rollout rows and compatibility.
+// Historical setup-step choices (current flows skip that screen); kept for pre-rollout rows and compatibility.
 export const addRepoSetupStepActionSchema = z.enum([
   'open_primary',
   'create_worktree',
@@ -183,11 +152,7 @@ export const addRepoDefaultCheckoutHandoffReasonSchema = z.enum([
 export const setupScriptImportProviderSchema = z.enum(SETUP_SCRIPT_IMPORT_PROVIDERS)
 export type SetupScriptImportProviderTelemetry = z.infer<typeof setupScriptImportProviderSchema>
 
-// Deliberately a separate enum from `errorClassSchema` (PTY-spawn taxonomy):
-// different domain — this one buckets git/filesystem failures thrown by
-// `createLocalWorktree` / `createRemoteWorktree`. Merging the two would lock
-// both domains to the union forever, which the schema-evolution comment
-// below warns against.
+// Separate enum from `errorClassSchema` — different domain (git/filesystem worktree-create failures); merging would couple the two forever.
 export const workspaceCreateErrorClassSchema = z.enum([
   'git_failed',
   'path_collision',
@@ -256,36 +221,15 @@ export type FeatureWallTourDepthStepTelemetry = z.infer<typeof featureWallTourDe
 export const featureWallExitActionSchema = z.enum(FEATURE_WALL_EXIT_ACTIONS)
 export type FeatureWallExitActionTelemetry = z.infer<typeof featureWallExitActionSchema>
 
-// `env_var` is deliberately absent — env-var and CI paths override consent at
-// runtime only (see consent.ts); they never mutate `optedIn` and therefore
-// never fire a `telemetry_opted_in/out` event. If a future path explicitly
-// persists an env-var-driven opt-out, add `env_var` back here together with
-// the call site.
-//
-// `first_launch_notice` (new-user disclosure toast) is deliberately absent —
-// the new-user cohort has no first-launch surface (see telemetry-plan.md
-// §First-launch experience). Opt-outs from new users come through
-// `via: 'settings'`.
+// `env_var` absent — env-var/CI paths override consent at runtime only, never firing an opt-in/out event.
+// `first_launch_notice` absent — the new-user cohort has no first-launch surface; those opt-outs come via `'settings'`.
 export const optInViaSchema = z.enum(['first_launch_banner', 'settings'])
 export type OptInVia = z.infer<typeof optInViaSchema>
 
-// Whitelist of settings whose `setting_key` may be emitted on
-// `settings_changed`. If a setting isn't in this list, we do not emit.
-//
-// Keys are camelCase to match the actual field names in `GlobalSettings`.
-// `orca_channel` is intentionally absent — it is a build-time common
-// property baked in from `ORCA_BUILD_IDENTITY`, not a user-togglable setting.
-//
-// Intentionally does NOT include the telemetry opt-in toggle — that is
-// covered by the dedicated `telemetry_opted_in` / `telemetry_opted_out`
-// events, which carry `via` context that a plain `settings_changed` could
-// not. Listing it here would double-fire.
-//
-// Kept as an `as const` tuple so the Zod enum below and any call-site usage
-// share one array — typo-drift is impossible.
+// Whitelist of settings emittable on `settings_changed`. `orca_channel` (build-time, not user-togglable) is absent.
+// The telemetry opt-in toggle is also absent — it fires dedicated `telemetry_opted_in/out` events; listing it would double-fire.
 type BooleanGlobalSettingsKey = {
-  // Why: new persisted toggles may be optional for legacy-settings compatibility
-  // while still being boolean settings once defaults are applied.
+  // Why: new toggles may be optional for legacy-settings compat but are still boolean once defaulted.
   [Key in keyof GlobalSettings]-?: NonNullable<GlobalSettings[Key]> extends boolean ? Key : never
 }[keyof GlobalSettings]
 export const SETTINGS_CHANGED_WHITELIST = [
@@ -305,18 +249,8 @@ export const settingsChangedKeySchema = z.enum(SETTINGS_CHANGED_WHITELIST)
 export type SettingsChangedKey = z.infer<typeof settingsChangedKeySchema>
 
 // ── Per-event schemas ───────────────────────────────────────────────────
-//
-// `.strict()` on every object is what enforces "no extra keys" at runtime —
-// the validator does not need a separate extra-key check because zod rejects
-// unknown keys at parse time. This is the runtime counterpart to the
-// compile-time "unions of string literals, no raw `string`" rule.
 
-// Cohort signal — see docs/onboarding-funnel-cohort-addendum.md. One integer
-// shared across the events listed in `COHORT_EXTENDED` below: the count of
-// repos the user has at emit time, read from `store.getRepos().length`.
-// `.int().nonnegative()` constrains malformed values to the floor;
-// `.optional()` lets the classifier's fail-soft fallback (returning
-// `undefined`) validate cleanly so a read error never crashes a track call.
+// Cohort signal (repo count at emit time); `.optional()` lets a fail-soft `undefined` validate. See docs/onboarding-funnel-cohort-addendum.md.
 const nthRepoAddedSchema = z.number().int().nonnegative().optional()
 
 const appOpenedSchema = z.object({ nth_repo_added: nthRepoAddedSchema }).strict()
@@ -343,12 +277,7 @@ const featureInteractionUsageBucketReachedSchema = z
   })
 
 const repoAddedSchema = z
-  // Why: `is_git_repo` is the real git-vs-folder signal, sourced from git
-  // detection at the add point. It moved here from `onboarding_completed`
-  // once project selection left onboarding (1.4.46). `.optional()` so
-  // SSH/remote or any path that genuinely can't determine git-ness validates
-  // cleanly instead of crashing the track call — same fail-soft intent as
-  // `nthRepoAddedSchema`. Never default-guess `false`; omit instead.
+  // Why: `.optional()` so paths that can't detect git-ness validate cleanly; never default-guess `false` — omit instead.
   .object({
     method: repoMethodSchema,
     is_git_repo: z.boolean().optional(),
@@ -422,11 +351,7 @@ const agentPromptSentSchema = z
   })
   .strict()
 
-// Enum-only by design for both fields. `error_message` and `error_stack` are
-// deliberately absent — `.strict()` rejects either key if a call site ever
-// tries to attach one, which fails the validator and drops the event. Raw
-// error strings carry arbitrary user/workspace/path content; keeping them off
-// the wire is the only way to guarantee we never transmit them by accident.
+// Enum-only by design: `.strict()` blocks `error_message`/`error_stack`, keeping raw user/path content off the wire.
 const agentErrorSchema = z
   .object({
     error_class: errorClassSchema,
@@ -435,11 +360,7 @@ const agentErrorSchema = z
   })
   .strict()
 
-// Why: emitted when the terminal daemon cannot start and terminals fall back to
-// the (non-persistent) local provider. Enum-only `error_class` — the raw daemon
-// stderr tail stays in local logs and never reaches the wire (paths/usernames).
-// A spike in this event is the fleet-wide signal for a daemon outage like
-// v1.4.129-rc.1, which was otherwise invisible until users filed bug reports.
+// Why: daemon start-failure signal (fleet-wide outage like v1.4.129-rc.1); enum-only so raw stderr never reaches the wire.
 const daemonStartFailedSchema = z.object({ error_class: errorClassSchema }).strict()
 
 const settingsChangedSchema = z
@@ -449,9 +370,7 @@ const settingsChangedSchema = z
   })
   .strict()
 
-// Native chat view (per-tab terminal⇄chat toggle) adoption signals.
-// `agent_kind` reuses the shared closed enum so dashboards can slice adoption
-// by agent. The view-mode enum mirrors `Tab.viewMode` in shared/types.ts.
+// Native chat (terminal⇄chat toggle) adoption; view-mode enum mirrors `Tab.viewMode` in shared/types.ts.
 const nativeChatViewModeSchema = z.enum(['terminal', 'chat'])
 const nativeChatToggledSchema = z
   .object({
@@ -460,8 +379,7 @@ const nativeChatToggledSchema = z
     agent_kind: agentKindSchema
   })
   .strict()
-// `runtime` records whether the agent PTY runs locally or over an SSH/remote
-// runtime; `'unknown'` when the owning runtime cannot be resolved at send time.
+// `runtime`: local vs SSH/remote agent PTY; `'unknown'` when unresolved at send time.
 const nativeChatRuntimeSchema = z.enum(['local', 'remote', 'unknown'])
 export type NativeChatRuntime = z.infer<typeof nativeChatRuntimeSchema>
 const nativeChatMessageSentSchema = z
@@ -609,10 +527,7 @@ const addRepoDefaultCheckoutHandoffSchema = z
   })
   .strict()
 
-// Why: same enum-only discipline as `agent_error` — `.strict()` rejects raw
-// error strings if a future call site tries to attach `error_message` /
-// `error_stack`. The classifier in worktrees.ts reads `error.message` to
-// bucket into the enum, but those strings never cross the wire.
+// Why: enum-only like `agent_error` — `.strict()` blocks raw error strings from ever crossing the wire.
 const workspaceCreateFailedSchema = z
   .object({
     source: workspaceSourceSchema,
@@ -625,8 +540,7 @@ const setupScriptPromptModeSchema = z.enum(['import_available', 'configure_neede
 const setupScriptCountBucketSchema = z.enum(['0', '1', '2-3', '4+'])
 const setupScriptPromptContextSchema = {
   mode: setupScriptPromptModeSchema,
-  // Why: cohort injection probes top-level ZodObject shapes; superRefine
-  // keeps that path while still rejecting impossible mode/provider pairs.
+  // Why: superRefine (not transform) keeps the top-level ZodObject shape that cohort injection probes.
   provider: setupScriptImportProviderSchema.optional(),
   file_count_bucket: setupScriptCountBucketSchema,
   unsupported_field_count_bucket: setupScriptCountBucketSchema,
@@ -658,8 +572,7 @@ function validateSetupScriptPromptProvider(
     })
   }
 }
-// Why: setup-candidate telemetry is for a retention cohort, not debugging a
-// user's repo, so it carries only closed enums and count buckets.
+// Why: retention-cohort telemetry, not repo debugging — closed enums and count buckets only.
 const setupScriptPromptShownSchema = z
   .object(setupScriptPromptContextSchema)
   .strict()
@@ -721,21 +634,11 @@ const setupScriptPromptActionSchema = z
   .strict()
   .superRefine(validateSetupScriptPromptAction)
 
-// Managed-hook installer per-agent label. Distinct from `AGENT_KIND_VALUES`:
-// hook installation only targets the agents in `AGENT_HOOK_TARGETS` and the
-// labels here match the `*HookService.install()` call sites in
-// `src/main/index.ts`. `claude` (not `claude-code`) is intentional — the
-// failure is about Claude Code's `~/.claude/settings.json`, not the broader
-// product taxonomy. Sourced from `AGENT_HOOK_TARGETS` so the wire enum and
-// the IPC `AgentHookTarget` type cannot drift as new hook-install agents
-// are added.
+// Managed-hook installer label from `AGENT_HOOK_TARGETS`, distinct from `AGENT_KIND_VALUES`; `claude` (not `claude-code`) is intentional.
 export const hookInstallAgentSchema = z.enum(AGENT_HOOK_TARGETS)
 export type HookInstallAgent = z.infer<typeof hookInstallAgentSchema>
 
-// Why: install failures are config-file-shape errors (malformed JSON, missing
-// keys, ACL denials on `~/.claude` etc.) — not user content. The 200-char
-// cap is the truncation contract; callers must truncate before calling
-// `track`, and the validator will drop overlength strings via `.max(200)`.
+// Why: config-shape errors (not user content); callers must truncate before `track` — `.max(200)` drops overlength strings.
 const agentHookInstallFailedSchema = z
   .object({
     agent: hookInstallAgentSchema,
@@ -743,27 +646,14 @@ const agentHookInstallFailedSchema = z
   })
   .strict()
 
-// Why: regression signal for paneKey attribution. A hook event whose paneKey
-// does not correspond to any tab in `tabsByWorktree` indicates the renderer
-// could not route the event to a pane. Pre-fix this fired routinely for
-// CLI-spawned terminals (empty paneKey); post-fix it should be near-zero in
-// normal use. The lone `reason` field reflects what the producer can observe
-// at emission time: an empty paneKey on the wire (pre-fix CLI shape) vs. any
-// non-empty paneKey that fails to resolve to a known tab in `tabsByWorktree`
-// (stale tab id, malformed value, or wrong-worktree id all bucket here).
-// See docs/cli-terminal-hook-pane-key.md.
+// Why: regression signal for paneKey attribution — a hook event that can't route to a pane. See docs/cli-terminal-hook-pane-key.md.
 const agentHookUnattributedSchema = z
   .object({ reason: z.enum(['empty_pane_key', 'unknown_tab_id']) })
   .strict()
 
 // ── Onboarding ──────────────────────────────────────────────────────────
-//
-// Closed enums only — no raw paths, repo names, clone URLs, or error
-// strings. The funnel exists to measure activation, not to debug specific
-// user repos.
-// Why: active onboarding now has fewer steps, but these event names already
-// carried seven-step payloads. Keep validation backward-compatible for old rows
-// unless a future versioned event replaces the historical schema.
+// Closed enums only — no raw paths/repo names/URLs/error strings (measures activation, not repo debugging).
+// Why: event names still carry legacy seven-step payloads; keep validation backward-compatible for old rows.
 const ONBOARDING_TELEMETRY_LEGACY_MAX_STEP = 7
 const onboardingStepSchema = z.number().int().min(1).max(ONBOARDING_TELEMETRY_LEGACY_MAX_STEP)
 const onboardingPathSchema = z.enum(['open_folder', 'clone_url', 'add_project_modal'])
@@ -807,10 +697,7 @@ const onboardingWindowsTerminalShellSchema = z.enum([
 ])
 const onboardingWindowsTerminalRightClickSchema = z.enum(['paste', 'menu'])
 const onboardingWindowsTerminalExitActionSchema = z.enum(['continue', 'skip_to_project_setup'])
-// `dismissed` from `OnboardingChecklistState` is intentionally excluded —
-// it is a UI panel-visibility flag, not an activation event, so it never
-// fires `activation_checklist_item_completed`. Keep this list in sync with
-// the activation keys of `OnboardingChecklistState` in shared/types.ts.
+// `dismissed` is intentionally excluded — it's a UI panel-visibility flag, not an activation event.
 const onboardingChecklistItemSchema = z.enum([
   'addedRepo',
   'addedFolder',
@@ -852,17 +739,13 @@ const onboardingFeatureSetupSelectedCountRefinement = {
 function hasMatchingOnboardingFeatureSetupSelectedCount(
   props: OnboardingFeatureSetupSelectionTelemetry
 ): boolean {
-  // Why: Linear ticket setup is a recommended add-on and must not affect
-  // onboarding progress metrics.
+  // Why: Linear ticket setup is a recommended add-on and excluded from progress metrics.
   const selectedCount =
     (props.browser_use ? 1 : 0) + (props.computer_use ? 1 : 0) + (props.orchestration ? 1 : 0)
   return props.selected_count === selectedCount
 }
 
-// Why: compile-time guard that the enum above stays in lockstep with the
-// activation keys of OnboardingChecklistState (everything except the UI-only
-// `dismissed` flag). Adding/removing a checklist key without updating this
-// schema breaks the build here rather than silently dropping telemetry.
+// Compile-time guard: enum must match OnboardingChecklistState activation keys (minus UI-only `dismissed`); drift breaks the build.
 type _OnboardingChecklistItemSync =
   z.infer<typeof onboardingChecklistItemSchema> extends Exclude<
     keyof OnboardingChecklistState,
@@ -877,14 +760,7 @@ type _OnboardingChecklistItemSync =
 const _onboardingChecklistItemSyncCheck: _OnboardingChecklistItemSync = true
 void _onboardingChecklistItemSyncCheck
 
-// Cohort discriminator threaded onto every onboarding-wizard event by the
-// IPC `telemetry:track` handler (mirrors `nth_repo_added`). `.optional()` is
-// load-bearing: the classifier returns `undefined` when settings can't be
-// read, and `.strict()` would otherwise reject the event entirely.
-//
-// Adding a new onboarding event: include `cohort: cohortSchema` on its
-// schema. The injection set in `telemetry:track` is derived from
-// `'cohort' in schema.shape`, so there is no parallel hand-maintained list.
+// Cohort discriminator for onboarding events; `.optional()` is load-bearing so `.strict()` accepts the `undefined` fallback.
 const cohortSchema = z.enum(['fresh_install', 'upgrade_backfill']).optional()
 
 const nestedRepoTelemetrySurfaceSchema = z.enum(NESTED_REPO_TELEMETRY_SURFACES)
@@ -930,8 +806,7 @@ function validateNestedRepoCountBuckets(
 }
 
 const nestedRepoTelemetryBaseSchema = {
-  // Why: high-cardinality by design, but random and non-persistent. It lets
-  // dashboards count scan -> action -> result attempts without path-derived IDs.
+  // Why: high-cardinality but random and non-persistent — correlates scan→action→result without path-derived IDs.
   attempt_id: nestedRepoAttemptIdSchema,
   surface: nestedRepoTelemetrySurfaceSchema,
   runtime_kind: nestedRepoTelemetryRuntimeKindSchema,
@@ -984,10 +859,7 @@ const addRepoNestedImportResultSchema = z
   .strict()
   .superRefine(validateNestedRepoCountBuckets)
 
-// `'button' | 'keyboard'` records whether the user advanced via a footer
-// button click, Cmd/Ctrl+Enter, or an equivalent keyboard exit like Escape.
-// The uniform shape lets keyboard skip/dismiss paths arrive without a
-// schema migration.
+// Uniform button/keyboard shape lets keyboard skip/dismiss paths arrive without a schema migration.
 const advancedViaSchema = z.enum(['button', 'keyboard']).optional()
 
 const onboardingStartedSchema = z
@@ -1121,21 +993,11 @@ const activationChecklistItemCompletedSchema = z
   })
   .strict()
 
-// Why: see docs/agent-on-path-detection.md. Disambiguates `on_path: false`
-// rows on dashboard 1562016 — distinguishes shell-hydration failure (where
-// `on_path` is misleading because Orca's view of PATH is incomplete) from
-// genuinely-not-on-PATH (where the field is reporting accurately). Closed
-// enum kept in lockstep with `ShellHydrationFailureReason` via a compile-time
-// guard below.
+// Why: disambiguates `on_path:false` rows on dashboard 1562016 (shell-hydration failure vs genuinely-not-on-PATH). See docs/agent-on-path-detection.md.
 const pathSourceSchema = z.enum(['shell_hydrate', 'sync_seed_only'])
 const pathFailureReasonSchema = z.enum(['none', 'no_shell', 'timeout', 'spawn_error', 'empty_path'])
 
-// Compile-time guard: schema enum must match `ShellHydrationFailureReason`.
-// Adding a new failure mode in `hydrate-shell-path.ts` without updating both
-// the shared alias and this schema breaks the build here. Without the guard,
-// a new enum value would ship `failureReason` strings the strict validator
-// rejects, dropping the entire `onboarding_agent_picked` event at parse time
-// and losing the `agent_kind`/`on_path` data on that pick.
+// Compile-time guard: schema enum must match `ShellHydrationFailureReason`; drift breaks the build, not runtime parsing.
 type _PathFailureReasonSync =
   z.infer<typeof pathFailureReasonSchema> extends ShellHydrationFailureReason
     ? ShellHydrationFailureReason extends z.infer<typeof pathFailureReasonSchema>
@@ -1154,42 +1016,27 @@ type _PathSourceSync =
 const _pathSourceSyncCheck: _PathSourceSync = true
 void _pathSourceSyncCheck
 
-// Fired at click time from `setSelectedAgentInteractive` so we capture
-// mind-changes within the step rather than just the final pick. `agent_kind`
-// uses `tuiAgentToAgentKind` so the wire enum stays closed even when stale
-// persisted settings present a string outside `TuiAgent` (the fallback is
-// `'other'`).
+// Fired at click time (captures mind-changes); `agent_kind` uses `tuiAgentToAgentKind` to keep the wire enum closed.
 const onboardingAgentPickedSchema = z
   .object({
     agent_kind: agentKindSchema,
     on_path: z.boolean(),
     detected_count: z.number().int().nonnegative(),
-    // `'pending'` when the merged isDetectingAgents/isRefreshingAgents flag
-    // is truthy at click time — distinguishes "picked the only detected
-    // agent" from "picked before detection finished."
+    // `'pending'` when detection is still running at click time (picked-before-detection vs picked-the-only-agent).
     detection_state: z.enum(['complete', 'pending']),
-    // `true` when the selected agent lived under the `<details>` disclosure
-    // ("Show N more"). Signals whether users go looking for less-popular
-    // agents — input for catalog ordering decisions.
+    // `true` when the agent lived under the "Show N more" disclosure — signals demand for less-popular agents.
     from_collapsed_section: z.boolean(),
-    // Why: instrumentation for the `on_path:false` triage. `.optional()` is
-    // load-bearing — events emitted before this deploy validate cleanly under
-    // `.strict()`. See docs/agent-on-path-detection.md.
+    // Why: `.optional()` is load-bearing so pre-deploy events validate under `.strict()`. See docs/agent-on-path-detection.md.
     path_source: pathSourceSchema.optional(),
     path_failure_reason: pathFailureReasonSchema.optional(),
     cohort: cohortSchema
   })
   .strict()
 
-// Mirrors the renderer's DiscoveryState taxonomy in ThemeStep.tsx. `failed`
-// is intentionally NOT a discovery state — it is the outcome of an Import
-// attempt, reported by `onboarding_ghostty_import_failed`.
+// Mirrors ThemeStep.tsx DiscoveryState; `failed` is intentionally absent (it's an import outcome, see onboarding_ghostty_import_failed).
 const ghosttyDiscoveryStateSchema = z.enum(['found', 'absent', 'imported'])
 
-// Compile-time guard: every member of ghosttyDiscoveryStateSchema must be a
-// discovery `status` the renderer can actually emit. Adding a new
-// DiscoveryState member in ThemeStep.tsx without updating the schema (or
-// vice versa) breaks the build here rather than silently dropping telemetry.
+// Compile-time guard: schema enum must stay in sync with the renderer's DiscoveryState; drift breaks the build, not runtime.
 type _GhosttyDiscoveryStateSync =
   z.infer<typeof ghosttyDiscoveryStateSchema> extends DiscoveryStatusEmitted
     ? DiscoveryStatusEmitted extends z.infer<typeof ghosttyDiscoveryStateSchema>
@@ -1202,23 +1049,14 @@ void _ghosttyDiscoveryStateSyncCheck
 const onboardingGhosttyDiscoveredSchema = z
   .object({
     state: ghosttyDiscoveryStateSchema,
-    // Bucketed, not raw, count: exact group counts are an environment
-    // fingerprint (heavy customizers are uniquely identifiable). Buckets
-    // cover the nine possible group labels in `humanFields()` without
-    // re-emitting the count itself.
+    // Bucketed not raw: exact group counts fingerprint heavy customizers.
     field_group_count_bucket: z.enum(['0', '1-3', '4-7', '8+']),
     cohort: cohortSchema
   })
   .strict()
 const onboardingGhosttyImportClickedSchema = z.object({ cohort: cohortSchema }).strict()
 
-// Why: smart-sort telemetry. The class distribution event tells us whether
-// real users have meaningful Class 1/2/3 populations (signal that the
-// redesign is doing work) or whether everyone collapses to Class 4 (signal
-// that hook coverage is too low). The Class 1 promotion event distinguishes
-// hook-driven attention from the title-heuristic fallback so we can tell
-// whether Edge case 9 is carrying weight. The smart→recent switch event is
-// our regression signal: users abandoning Smart for Recent.
+// Smart-sort telemetry: measures whether the redesign concentrates users in Class 1-3, and flags Smart→Recent abandonment as a regression.
 const smartSortClassDistributionSchema = z
   .object({
     class_1: z.number().int().nonnegative(),
@@ -1233,18 +1071,11 @@ const smartSortClass1PromotionSchema = z
     cause: z.enum(['blocked', 'waiting', 'title-heuristic'])
   })
   .strict()
-// Why a placeholder field instead of `z.object({})`: an empty zod object
-// infers as TS `{}` (which in TS means "anything non-null/undefined"). That
-// upsets the `keyof EventMap[N]` probes used by COHORT_EXTENDED_SET and
-// ONBOARDING_COHORT_SET, breaking their compile-time roster sync checks.
-// Carrying a single optional `_v` discriminator dodges the issue and
-// preserves room to add future fields without renaming the event.
+// Why `_v` not `z.object({})`: empty zod object infers as TS `{}` ("anything"), breaking the `keyof EventMap[N]` roster probes.
 const smartToRecentSwitchSchema = z.object({ _v: z.literal(1).optional() }).strict()
 const onboardingGhosttyImportFailedSchema = z
   .object({
-    // `'no_config'` is reserved for a future explicit "preview returned
-    // found:false" branch. Today's call sites emit `'empty_diff'` (the
-    // import resolved to no changes) or `'unknown'` (caught throw).
+    // `'no_config'` is reserved for future use; call sites currently emit `'empty_diff'` or `'unknown'`.
     reason: z.enum(['no_config', 'empty_diff', 'unknown']),
     cohort: cohortSchema
   })
@@ -1266,8 +1097,7 @@ const onboardingFeatureSetupRunSchema = z
     warning_count: z.number().int().nonnegative(),
     cohort: cohortSchema
   })
-  // Why: selected_count is derived analytics data; validate the relationship
-  // at the untrusted IPC boundary instead of trusting renderer callers.
+  // Why: validate derived selected_count at the untrusted IPC boundary rather than trust renderer callers.
   .refine(
     hasMatchingOnboardingFeatureSetupSelectedCount,
     onboardingFeatureSetupSelectedCountRefinement
@@ -1386,9 +1216,7 @@ const terminalPaneSplitSchema = z
   })
   .strict()
 
-// Why: measures the changed-on-disk conflict flow (issue #7265) — how often
-// conflicts surface per transport (false-banner detection on ssh/runtime
-// echoes) and which resolution users pick. Deliberately path-free.
+// Why: measures the changed-on-disk conflict flow (issue #7265) per transport; deliberately path-free.
 const editorExternalChangeConflictShownSchema = z
   .object({
     surface: z.enum(['edit', 'unstaged-diff']),
@@ -1406,18 +1234,7 @@ const editorExternalChangeConflictActionSchema = z
   .strict()
 
 // ── Event registry: the one record the validator consumes ───────────────
-//
-// The validator does `eventSchemas[name].safeParse(props)`. `EventMap` is
-// `z.infer`-derived from this record, so there is exactly one source of
-// truth for both compile-time types and runtime validation.
-//
-// Schema-evolution / versioning doctrine:
-// Breaking changes (renaming a field, changing an enum's meaning, removing a
-// required key) require a new event name (e.g. `agent_started_v2`), not an
-// in-place edit. Additive-optional fields (`z.field().optional()`) are safe
-// to add in place. This keeps PostHog funnels clean — an in-place breaking
-// change silently blends pre- and post-change rows under one event name,
-// which cannot be unmixed after the fact.
+// Versioning: breaking changes (rename/re-mean/remove a key) need a new event name; in-place edits blend pre/post rows unmixably. Additive-optional fields are safe.
 export const eventSchemas = {
   app_opened: appOpenedSchema,
   app_starred_orca: appStarredOrcaSchema,
@@ -1510,20 +1327,14 @@ export type EventMap = { [N in keyof typeof eventSchemas]: z.infer<(typeof event
 export type EventName = keyof EventMap
 export type EventProps<N extends EventName> = EventMap[N]
 
-// Why: events whose schemas declare a given property name. Extracted so the
-// cast (Object.entries → [EventName, ZodTypeAny]) stays in one place; if the
-// schema-registry shape ever changes, only one site needs to update.
-// Safely skips non-`ZodObject` schemas (e.g. a future `z.discriminatedUnion`
-// or `z.union`) — those have no `.shape`, and probing `key in undefined`
-// would throw at module load and take the telemetry module down on import.
+// Why: non-`ZodObject` schemas have no `.shape`; return null so `key in undefined` can't throw at module load.
 function eventSchemaShape(schema: z.ZodTypeAny): z.ZodRawShape | null {
   if (schema instanceof z.ZodObject) {
     return schema.shape
   }
 
   const shapeBearingSchema = schema as { shape?: unknown }
-  // Why: refined object schemas may still expose `.shape` even if a Zod
-  // version stops preserving `instanceof ZodObject` through refinement.
+  // Why: refined object schemas may expose `.shape` even when refinement breaks `instanceof ZodObject`.
   if (shapeBearingSchema.shape && typeof shapeBearingSchema.shape === 'object') {
     return shapeBearingSchema.shape as z.ZodRawShape
   }
@@ -1541,23 +1352,11 @@ function eventsWithShapeKey(key: string): ReadonlySet<EventName> {
   )
 }
 
-// Events whose schemas declare `nth_repo_added`. Derived from `eventSchemas`
-// at module load by probing each schema's `.shape` — there is no parallel
-// hand-maintained list to drift out of sync. The IPC `telemetry:track`
-// handler injects the cohort property only when the incoming event name is
-// in this set: the schemas are `.strict()`, so injecting `nth_repo_added`
-// on an event whose schema does not declare it would fail validation and
-// silently drop the entire event.
-//
-// Schema-additions checklist for adding a new cohort-extended event:
-//   add `nth_repo_added: nthRepoAddedSchema` to the event's schema above.
-//   That is the *only* step — this set updates automatically.
+// Cohort injection is gated on this derived set because `.strict()` schemas drop events that don't declare `nth_repo_added`.
 const COHORT_EXTENDED_SET = eventsWithShapeKey('nth_repo_added')
 export const COHORT_EXTENDED: readonly EventName[] = Array.from(COHORT_EXTENDED_SET)
 
-// Compile-time roster of events that must declare `nth_repo_added`. Same
-// rationale as `_OnboardingCohortRosterSync` below — guards the runtime
-// injection set against silent schema drift.
+// Compile-time roster guarding the runtime injection set against silent schema drift.
 type _CohortExtendedRoster =
   | 'app_opened'
   | 'app_starred_orca'
@@ -1582,9 +1381,7 @@ type _CohortExtendedRoster =
   | 'orca_cli_feature_tip_setup_result'
   | 'cmd_j_palette_feature_tip_shown'
   | 'cmd_j_palette_feature_tip_acknowledged'
-// Why: `z.object({}).strict()` infers a string index signature, which would
-// make every key appear present. Ignore index-signature-only keys here so
-// strict empty event payloads do not get pulled into keyed telemetry rosters.
+// Why: strict empty payloads infer a string index signature; ignore index-only keys so they aren't pulled into keyed rosters.
 type _KnownPayloadKeys<T> = string extends keyof T ? never : keyof T
 type _DerivedCohortExtendedEvents = {
   [N in EventName]: 'nth_repo_added' extends _KnownPayloadKeys<EventMap[N]> ? N : never
@@ -1601,26 +1398,12 @@ export function isCohortExtendedEvent(name: EventName): boolean {
   return COHORT_EXTENDED_SET.has(name)
 }
 
-// Onboarding events — derived the same way as `COHORT_EXTENDED_SET`: probe
-// each schema's `.shape` for the `cohort` key. The IPC `telemetry:track`
-// handler injects the onboarding cohort property only when the incoming
-// event name is in this set; schemas are `.strict()`, so injecting `cohort`
-// on an event whose schema does not declare it would fail validation and
-// silently drop the entire event.
-//
-// Adding a new onboarding event: include `cohort: cohortSchema` on its
-// schema. This set updates automatically.
+// Events whose schema declares `cohort`: the IPC handler injects cohort only for these — a `.strict()` schema without it would reject the event.
 const ONBOARDING_COHORT_SET = eventsWithShapeKey('cohort')
 // `NonNullable` strips `undefined` introduced by `cohortSchema`'s `.optional()`.
 export type OnboardingCohort = NonNullable<z.infer<typeof cohortSchema>>
 
-// Compile-time roster of events that must declare `cohort`. If a schema
-// refactor drops the field from one of these, this fails tsc rather than
-// silently dropping the event from the runtime injection set above (which
-// the `.optional()` schema would tolerate without any test failure).
-//
-// Adding a new onboarding event: add its name here AND declare
-// `cohort: cohortSchema` on its schema. Both are required.
+// Compile-time roster: dropping `cohort` from any of these fails tsc, rather than silently at runtime (`.optional()` would tolerate that).
 type _OnboardingCohortRoster =
   | 'onboarding_started'
   | 'onboarding_step_viewed'
@@ -1656,30 +1439,15 @@ export function isOnboardingEvent(name: EventName): boolean {
   return ONBOARDING_COHORT_SET.has(name)
 }
 
-// Common props attached by the client — declared here so the validator knows
-// which keys to allow on every outgoing event.
-//
-// No `env: 'prod' | 'dev'` property. Every transmitted event is by
-// construction from an official CI build, so a wire discriminator would be
-// redundant. Contributor / `pnpm dev` builds do not transmit at all; they
-// console-mirror.
-//
-// Every string field carries the 64-char cap directly — this is what the
-// validator's "string-length cap" rule is made of; there is no separate
-// post-parse length check to keep in sync with the schema.
+// No `env` discriminator: every transmitted event is from an official CI build (dev/contributor builds only console-mirror).
+// The per-field `.max(64)` is the validator's string-length cap — there is no separate post-parse length check.
 export const commonPropsSchema = z
   .object({
     app_version: z.string().max(64),
     platform: z.string().max(64),
     arch: z.string().max(64),
     os_release: z.string().max(64),
-    // `install_id` is used as PostHog's `distinctId` and `session_id` is the
-    // per-process correlation key — an empty string on either would collapse
-    // unrelated events into a single synthetic "user" / "session" and
-    // silently corrupt analytics. `.min(1)` rejects that actual observed
-    // failure mode without pinning the shape to UUIDs (both ids come from
-    // `randomUUID()` today, but forward-compatibility with a future id
-    // scheme is cheap to preserve).
+    // `.min(1)`: an empty install_id/session_id would collapse unrelated events into one synthetic user/session, corrupting analytics.
     install_id: z.string().min(1).max(64),
     session_id: z.string().min(1).max(64),
     orca_channel: z.enum(['stable', 'rc'])
diff --git a/src/shared/terminal-output-side-effects.ts b/src/shared/terminal-output-side-effects.ts
index 4f00c9f1753..2b4b3ea81c5 100644
--- a/src/shared/terminal-output-side-effects.ts
+++ b/src/shared/terminal-output-side-effects.ts
@@ -1,12 +1,7 @@
 /**
- * Shared per-PTY terminal title side-effect tracking — the parser core behind
- * both the renderer transport (`createPtyOutputProcessor`) and main's
- * per-PTY tracker in `OrcaRuntimeService.onPtyData`.
- *
- * Why shared: main is the side-effect parser for every PTY whose bytes transit
- * local main. Title
- * semantics (all-titles ordering, cursor-agent literal drop, normalization,
- * stale-working-title clearing) must not drift between the two paths.
+ * Shared per-PTY terminal title side-effect tracking — the parser core behind both the renderer
+ * transport (`createPtyOutputProcessor`) and main's per-PTY tracker (`OrcaRuntimeService.onPtyData`).
+ * Title semantics must not drift between the two paths.
  */
 
 import {
@@ -28,56 +23,41 @@ import { createOsc133CommandFinishedScanner } from './terminal-osc133-command-fi
 /** Ms of title-less output after a working title before it is cleared. */
 export const STALE_WORKING_TITLE_TIMEOUT_MS = 3000
 
-// Braille spinner frame glyphs (U+2800–U+28FF) — the decorative animation
-// class agents rotate through while working. Mirrors the range
-// clearWorkingIndicators strips in agent-detection.ts.
+// Braille spinner glyphs (U+2800–U+28FF); mirrors the range clearWorkingIndicators strips in agent-detection.ts.
 // eslint-disable-next-line no-control-regex -- intentional unicode range
 const BRAILLE_SPINNER_RE = /[\u2800-\u28FF]/g
 
 /**
- * Strip decorative braille spinner frame glyphs for change comparisons.
- * Two working titles that differ only by the animation frame (e.g.
- * "⠋ Cursor Agent" vs "⠙ Cursor Agent") compare equal after stripping —
- * the gate consumers use to avoid fan-out churn on spinner ticks.
+ * Strip decorative braille spinner frame glyphs so titles differing only by the animation frame
+ * compare equal — the gate consumers use to avoid fan-out churn on spinner ticks.
  */
 export function stripBrailleSpinnerGlyphs(title: string): string {
   return title.replace(BRAILLE_SPINNER_RE, '').trim()
 }
 
-/** Provenance for title/idle facts. `staleWorkingTitleClear` marks facts
- *  synthesized by the 3s stale-working-title timer rather than observed
- *  bytes — consumers must not treat them as genuine task completions. */
+/** Provenance for title/idle facts; `staleWorkingTitleClear` marks facts synthesized by the 3s stale timer — not genuine task completions. */
 export type TerminalTitleFactMeta = {
   staleWorkingTitleClear?: boolean
 }
 
 export type TerminalTitleTrackerCallbacks = {
-  /**
-   * Fired once per observed OSC title, in byte order — including the
-   * synthesized cleared title when the stale-working timer fires.
-   */
+  /** Fired once per observed OSC title, in byte order — including the synthesized cleared title when the stale-working timer fires. */
   onTitle?: (normalizedTitle: string, rawTitle: string, meta?: TerminalTitleFactMeta) => void
   onAgentBecameIdle?: (title: string, meta?: TerminalTitleFactMeta) => void
   onAgentBecameWorking?: () => void
   onAgentExited?: () => void
-  /**
-   * Fired once per chunk containing a real BEL (OSC-aware, escape state kept
-   * across chunks), after the chunk's title facts — the renderer drain order.
-   */
+  /** Fired once per chunk containing a real BEL (OSC-aware, cross-chunk escape state), after the chunk's titles (renderer drain order). */
   onBell?: () => void
   /**
-   * Fired per complete OSC 133;D (chunk-boundary-safe) with the sequence's
-   * best-effort exit code — mirrors the renderer terminal-command-lifecycle
-   * semantics so the fact path drops stale agent rows exactly like byte mode.
+   * Fired per complete OSC 133;D (chunk-boundary-safe) with the sequence's best-effort exit code;
+   * mirrors renderer command-lifecycle semantics so the fact path drops stale agent rows like byte mode.
    */
   onCommandFinished?: (bestEffortExitCode: number | null) => void
-  /** Fired once per newly observed GitHub PR URL (chunk-boundary-safe,
-   *  deduplicated per tracker like the renderer detector). */
+  /** Fired once per newly observed GitHub PR URL (chunk-boundary-safe, deduplicated per tracker). */
   onPrLink?: (link: TerminalGitHubPRLink) => void
   /**
-   * Fired per chunk containing a DECSET 2031 subscribe (chunk-boundary-safe).
-   * Lets hidden-delivery-gated renderer views answer the color-scheme query
-   * without byte access; the reply itself stays with the view.
+   * Fired per chunk containing a DECSET 2031 subscribe (chunk-boundary-safe): lets
+   * hidden-delivery-gated renderer views answer the color-scheme query without byte access.
    */
   onMode2031Subscribe?: () => void
 }
@@ -86,27 +66,21 @@ export type TerminalTitleTracker = {
   /** Feed one raw PTY chunk; titles are applied synchronously in byte order. */
   handleChunk: (data: string, options?: { titleScanData?: string }) => void
   /**
-   * Apply a main-fabricated OSC title/BEL frame (agent hook spinner frames).
-   * Parsed statelessly — never through the chunk bell detector — so a
-   * synthetic tick landing between two real chunks that split an OSC cannot
-   * corrupt the cross-chunk escape state into phantom or swallowed bells.
+   * Apply a main-fabricated OSC title/BEL frame (agent hook spinner frames). Parsed statelessly,
+   * never through the chunk bell detector, so a synthetic tick can't corrupt cross-chunk escape state.
    */
   applySyntheticTitleFrame: (frame: string) => void
   /**
-   * Seed the last-known title for a tracker created mid-session (app relaunch
-   * with persisted/snapshot titles). No-ops once any title has been observed
-   * or seeded — live state always wins. Fires no callbacks.
+   * Seed the last-known title for a mid-session tracker (app relaunch with persisted titles).
+   * No-ops once any title has been observed or seeded (live state wins); fires no callbacks.
    */
   seedInitialTitle: (rawTitle: string) => void
   /** Last title surfaced through onTitle, after normalization. */
   getLastNormalizedTitle: () => string | null
   /**
-   * While suppressed, handleChunk skips the four transient-fact scanners
-   * (bell/133/pr-link/2031) — a thinning transport holds scan authority for
-   * this PTY and relays their facts itself; feeding the (possibly gapped)
-   * delivered bytes here would mint phantom or duplicate facts. Title
-   * processing is unaffected. Un-suppressing resets the scanners' cross-chunk
-   * carry: their last-fed byte predates the gap.
+   * While suppressed, handleChunk skips the transient-fact scanners (bell/133/pr-link/2031)
+   * because a thinning transport owns scan authority and the delivered bytes may be gapped.
+   * Titles are unaffected; un-suppressing resets the scanners' cross-chunk carry.
    */
   setTransientFactScanningSuppressed: (suppressed: boolean) => void
   /** Cancel the stale-title timer and clear accumulated tracker state. */
@@ -128,25 +102,19 @@ export function createTerminalTitleTracker(
     onMode2031Subscribe
   } = callbacks
   const bellDetector = onBell ? createBellDetector() : null
-  // Why: created only when a consumer exists (like the bell detector) so
-  // headless serve never pays the per-chunk 133/URL scans.
+  // Why: created only when a consumer exists so headless serve never pays the per-chunk 133/URL scans.
   const commandFinishedScanner = onCommandFinished
     ? createOsc133CommandFinishedScanner(onCommandFinished)
     : null
   let prLinkDetector = onPrLink ? createTerminalGitHubPRLinkDetector() : null
   let transientFactScanningSuppressed = false
-  // Why: a DECSET 2031 subscribe can be split across PTY chunks; carry a
-  // bounded tail between chunks so split sequences still match.
+  // Why: a DECSET 2031 subscribe can split across chunks; carry a bounded tail so split sequences still match.
   let mode2031ScanTail = ''
-  // Why: seed both the emitted-title memory (stale-title probe) and the agent
-  // tracker so a mid-session tracker behaves as if it had observed the pane's
-  // last live title — parity with the renderer processor's seeding.
+  // Why: seed both so a mid-session tracker behaves as if it had observed the pane's last live title (renderer parity).
   let lastEmittedTitle: string | null =
     options.initialTitle !== undefined ? normalizeTerminalTitle(options.initialTitle) : null
   let staleTitleTimer: ReturnType<typeof setTimeout> | null = null
-  // Why: set while the stale timer's cleared title flows through the agent
-  // tracker so the resulting idle callback carries timer provenance — the
-  // renderer must not turn a stale clear into a task-complete notification.
+  // Why: flags the stale-timer clear so its idle callback carries timer provenance, not a genuine task-complete.
   let applyingStaleWorkingTitleClear = false
   const agentTracker =
     onAgentBecameIdle || onAgentBecameWorking || onAgentExited
@@ -171,9 +139,7 @@ export function createTerminalTitleTracker(
   }
 
   function applyObservedTitle(rawTitle: string): void {
-    // Why: cursor-agent re-emits its bare native title many times per turn
-    // while still working; letting it through would stomp Orca's synthesized
-    // "⠋ Cursor Agent" spinner state back to agentless within a second.
+    // Why: cursor-agent re-emits its bare native title mid-turn; passing it through would stomp Orca's synthesized spinner state.
     if (isCursorNativeAgentTitle(rawTitle)) {
       return
     }
@@ -184,22 +150,14 @@ export function createTerminalTitleTracker(
 
   function handleChunk(data: string, options: { titleScanData?: string } = {}): void {
     const titleScanData = options.titleScanData ?? data
-    // Why: this is main's per-chunk hot path — scan for the OSC introducer
-    // once and share the result with the bell detector's fast-path gate.
+    // Why: hot path — scan for the OSC introducer once and share it with the bell detector's fast-path gate.
     const containsOscIntroducer = data.includes('\x1b]')
-    // Why: the bell detector must consume EVERY chunk so OSC sequences that
-    // span chunk boundaries keep their escape state, even when the chunk has
-    // no title. The fact itself is surfaced after the chunk's titles, the
-    // renderer drain's order (payloads → titles → bell). While suppressed it
-    // must consume NONE: the delivered bytes may be gapped.
+    // Why: consume every chunk so cross-chunk OSC escape state survives; but none while suppressed, since delivered bytes may be gapped.
     const containsBell =
       bellDetector && !transientFactScanningSuppressed
         ? bellDetector.chunkContainsBell(data, { containsOscIntroducer })
         : false
-    // Why: feed EVERY OSC title in the chunk in byte order, never just the
-    // last one. node-pty plus the main-process batch window commonly coalesce
-    // multiple title updates into a single payload; a last-title reader drops
-    // intra-chunk working→idle transitions (issue #1083).
+    // Why: feed every OSC title in byte order; a last-title reader drops intra-chunk working→idle transitions in coalesced payloads (issue #1083).
     const titles = titleScanData.includes('\x1b]') ? extractAllOscTitles(titleScanData) : []
     if (titles.length > 0) {
       clearStaleTitleTimer()
@@ -207,10 +165,7 @@ export function createTerminalTitleTracker(
         applyObservedTitle(title)
       }
     } else if (
-      // Why: agents that exit without resetting their title leave a stale
-      // working spinner behind. Any title-less output while the last title
-      // classifies as working restarts a 3s timer that rewrites the title to
-      // its cleared form — the renderer transport's stale-title semantics.
+      // Why: an agent exiting without resetting its title leaves a stale spinner; title-less output while working arms the 3s clear timer.
       data.length > 0 &&
       lastEmittedTitle !== null &&
       detectAgentStatusFromTitle(lastEmittedTitle) === 'working'
@@ -221,10 +176,7 @@ export function createTerminalTitleTracker(
         if (lastEmittedTitle && detectAgentStatusFromTitle(lastEmittedTitle) === 'working') {
           const cleared = clearWorkingIndicators(lastEmittedTitle)
           lastEmittedTitle = cleared
-          // Why: tag timer-synthesized facts. Main's timer is unthrottled
-          // (unlike the renderer timers that previously damped this path in
-          // hidden windows), so a merely-paused agent must be distinguishable
-          // from a genuine working→idle completion downstream.
+          // Why: tag timer-synthesized facts so downstream distinguishes a merely-paused agent from a genuine working→idle completion.
           applyingStaleWorkingTitleClear = true
           try {
             onTitle?.(cleared, cleared, { staleWorkingTitleClear: true })
@@ -235,10 +187,7 @@ export function createTerminalTitleTracker(
         }
       }, STALE_WORKING_TITLE_TIMEOUT_MS)
     }
-    // Per-chunk fact order: titles → command-finished → pr-link →
-    // 2031-subscribe → bell. The bell stays last (the renderer drain's
-    // order); the byte scanners keep their own cross-chunk carry so split
-    // sequences/URLs still resolve.
+    // Fact order (matches renderer drain): titles → command-finished → pr-link → 2031-subscribe → bell; bell last.
     if (!transientFactScanningSuppressed) {
       commandFinishedScanner?.scan(data)
       if (prLinkDetector) {
@@ -260,11 +209,7 @@ export function createTerminalTitleTracker(
   }
 
   function applySyntheticTitleFrame(frame: string): void {
-    // Why: synthetic frames have an exact main-fabricated shape, so they are
-    // parsed statelessly here. Feeding them through handleChunk would run the
-    // stateful bell detector: a tick landing while a REAL OSC is split across
-    // two chunks would consume the pending escape state, minting a phantom
-    // bell from the continuation chunk or swallowing a real one.
+    // Why: parse statelessly — the stateful chunk bell detector could mint or swallow bells around a real cross-chunk OSC split.
     const titles = extractAllOscTitles(frame)
     if (titles.length > 0) {
       clearStaleTitleTimer()
@@ -272,23 +217,18 @@ export function createTerminalTitleTracker(
         applyObservedTitle(title)
       }
     }
-    // The deliberate permission BEL rides outside the OSC title sequence. A
-    // FRESH detector instance keeps the OSC-terminator-vs-bell semantics
-    // while guaranteeing zero interaction with the chunk detector's state.
-    // Synthetic frames never reach the 133/PR-link scanners: fabricated bytes
-    // contain neither and must not perturb their cross-chunk carry state.
+    // The permission BEL rides outside the OSC title; a FRESH detector avoids touching the chunk detector's cross-chunk escape state.
     if (onBell && createBellDetector().chunkContainsBell(frame)) {
       onBell()
     }
+    // Why: deliberately skip the 133/PR-link/2031 scanners — fabricated bytes contain none and must not perturb their cross-chunk carry.
   }
 
   return {
     handleChunk,
     applySyntheticTitleFrame,
     seedInitialTitle(rawTitle: string): void {
-      // Why: the cursor-agent literal drop applies to seeds too — restoring
-      // the bare native title would stomp synthesized spinner state exactly
-      // like emitting it live would.
+      // Why: the cursor-agent literal drop applies to seeds too — a bare native title would stomp synthesized spinner state.
       if (lastEmittedTitle !== null || !rawTitle || isCursorNativeAgentTitle(rawTitle)) {
         return
       }
@@ -302,11 +242,7 @@ export function createTerminalTitleTracker(
       }
       transientFactScanningSuppressed = suppressed
       if (!suppressed) {
-        // Cross-chunk carry predates the suppressed (gapped) span — a stale
-        // half-open OSC would swallow real bells; a stale 133/2031 tail or
-        // URL fragment would mint phantom facts. The PR-link dedup memory is
-        // lost with the recreate; a re-printed link may re-fire (consumers
-        // treat pr-link as a latest-association update).
+        // Cross-chunk carry predates the gapped span; reset it so stale state can't swallow real bells or mint phantom facts.
         bellDetector?.reset()
         commandFinishedScanner?.reset()
         mode2031ScanTail = ''
diff --git a/src/shared/terminal-title-status.ts b/src/shared/terminal-title-status.ts
index 5d8cd0a45f2..e0fe8312468 100644
--- a/src/shared/terminal-title-status.ts
+++ b/src/shared/terminal-title-status.ts
@@ -18,62 +18,25 @@ import {
 
 export type AgentStatus = 'working' | 'permission' | 'idle'
 
-// Why: idle keywords used inside `detectAgentStatusFromTitle` to map titles
-// like "Codex done", "OpenCode ready", "Aider idle" to AgentStatus 'idle'.
-// `as const` so consumers receive literal-union types.
+// Idle-status keywords; `as const` gives consumers literal-union types.
 const STRONG_IDLE_KEYWORDS = ['ready', 'idle', 'done'] as const
 
-// Why: working keywords used inside `detectAgentStatusFromTitle` to map
-// titles like "Codex working", "Aider thinking", "OpenCode running" to
-// AgentStatus 'working'. Shared with `clearWorkingIndicators` so both stay
-// in lock-step when stripping working indicators from stale titles.
+// Working-status keywords, shared with `clearWorkingIndicators` so detection and stripping stay in lock-step.
 const STRONG_WORKING_KEYWORDS = ['working', 'thinking', 'running'] as const
 
-// Why: match STRONG_IDLE_KEYWORDS only when not adjacent to characters that
-// would make the "keyword" part of a larger token. Plain `\b` alone is
-// insufficient because `-` is a non-word character in JS regex, so `\bready\b`
-// still matches inside "is-ready-cap" (a `\b` boundary falls between `-` and
-// `r`).
-//
-// Lookarounds are intentionally ASYMMETRIC:
-//   - LEFT: reject `[\w./\\-]` so path fragments like `~/codex/ready`,
-//     Windows `C:\codex\ready`, and `codex.ready` cannot mint a strong idle
-//     signal by having the agent name sit earlier in the same path and the
-//     keyword land right after a path separator. Orca is a cross-platform
-//     Electron app, so Windows path separators must be handled too.
-//   - RIGHT: reject only `[\w\-]` so legitimate sentence-style titles like
-//     "Codex done." / "Aider idle." / "OpenCode ready!" still match — path
-//     separators after the keyword are not a false-positive vector in
-//     practice and blocking them would regress trailing-punctuation titles.
-//
-// Also rejects hyphenated compounds ("is-ready-cap", "re-done") and plain
-// substring false positives ("already"/"redone"/"idleness").
+// Why: `\b` fails since "-" is a non-word char (`\bready\b` matches "is-ready-cap"); lookarounds are asymmetric — reject path chars left, allow trailing punctuation ("Codex done.") right.
 export const STRONG_IDLE_KEYWORDS_RE = new RegExp(
   `(?<![\\w./\\\\-])(${STRONG_IDLE_KEYWORDS.join('|')})(?![\\w\\-])`,
   'i'
 )
 
-// Why: mirrors STRONG_IDLE_KEYWORDS_RE — plain substring matching on the
-// working keywords caused the symmetric class of false positives, e.g.
-// "reworking" ⊃ "working", "overthinking" ⊃ "thinking", "rerunning" ⊃
-// "running", hyphenated compounds like "is-thinking-cap", AND cwd-path
-// fragments like "~/codex/working" or "C:\codex\working". Uses the same
-// asymmetric lookarounds as STRONG_IDLE_KEYWORDS_RE (path separators blocked
-// on the left only so "Codex working." still matches). A false 'working'
-// classification is worse than the idle one because it drives active-agent
-// UI (spinners, counts), so word-char- and left-path-separator-aware
-// matching is required here too.
+// Why: mirrors STRONG_IDLE_KEYWORDS_RE; boundary match avoids "reworking" ⊃ "working"; a false 'working' is worse (drives active-agent UI).
 export const STRONG_WORKING_KEYWORDS_RE = new RegExp(
   `(?<![\\w./\\\\-])(${STRONG_WORKING_KEYWORDS.join('|')})(?![\\w\\-])`,
   'i'
 )
 
-// Why: global-flag companion of STRONG_WORKING_KEYWORDS_RE used by
-// clearWorkingIndicators to strip ALL occurrences in a single pass. Keeps
-// clearing and detection in lock-step — both use identical [\w\-] lookarounds,
-// so `clearWorkingIndicators` no longer strips keywords out of hyphenated
-// compounds like "is-working-cap" that `detectAgentStatusFromTitle` would
-// correctly refuse to classify as working.
+// Why: global-flag companion for clearWorkingIndicators; shares lookarounds so clearing and detection stay in lock-step.
 export const STRONG_WORKING_KEYWORDS_RE_GLOBAL = new RegExp(STRONG_WORKING_KEYWORDS_RE.source, 'gi')
 
 function containsAny(title: string, words: readonly string[]): boolean {
@@ -83,8 +46,7 @@ function containsAny(title: string, words: readonly string[]): boolean {
 
 /**
  * Tracks agent status transitions from terminal title changes.
- * Fires `onBecameIdle` when an agent transitions from working to idle/permission,
- * like haunt's attention flag — the key trigger for unread notifications.
+ * Fires `onBecameIdle` on working→idle/permission — the trigger for unread notifications.
  */
 export function createAgentStatusTracker(
   onBecameIdle: (title: string) => void,
@@ -92,8 +54,7 @@ export function createAgentStatusTracker(
   onAgentExited?: () => void
 ): {
   handleTitle: (title: string) => void
-  /** Clear accumulated status so a stale working→idle transition cannot fire
-   *  after the owning transport is torn down. */
+  /** Clear status so a stale working→idle transition can't fire after teardown. */
   reset: () => void
 } {
   let lastStatus: AgentStatus | null = null
@@ -107,12 +68,7 @@ export function createAgentStatusTracker(
       if (lastStatus !== 'working' && newStatus === 'working') {
         onBecameWorking?.()
       }
-      // Why: when the title reverts to a plain shell prompt (e.g., "bash", "zsh"),
-      // detectAgentStatusFromTitle returns null. If we were idle or in a permission
-      // prompt, this means the user exited the agent — clear session-tied state
-      // (like the prompt-cache countdown). We intentionally do NOT fire this when
-      // lastStatus is 'working', because active agents can briefly flash shell
-      // titles during internal operations without actually exiting.
+      // Why: null title = reverted to a plain shell prompt (agent exited); skip when 'working' since active agents briefly flash shell titles.
       if (lastStatus !== null && lastStatus !== 'working' && newStatus === null) {
         lastStatus = null
         onAgentExited?.()
@@ -127,12 +83,7 @@ export function createAgentStatusTracker(
   }
 }
 
-// Why: cursor-agent's native OSC title is the literal string "Cursor Agent"
-// across the entire turn — it carries zero working/idle information. Orca
-// synthesizes its own titles ("⠋ Cursor Agent" for working, "Cursor -
-// action required" for permission) from cursor's hook events; the bare
-// native title must be a no-op so cursor's per-turn re-emissions cannot
-// stomp the synthesized state back to idle.
+// Why: cursor's native title is constant and carries no working/idle info; keep it a no-op so per-turn re-emissions can't stomp Orca-synthesized state.
 const CURSOR_NATIVE_TITLE_LOWER = 'cursor agent'
 
 export function detectAgentStatusFromTitle(title: string): AgentStatus | null {
@@ -142,10 +93,7 @@ export function detectAgentStatusFromTitle(title: string): AgentStatus | null {
   if (isClaudeManagementTitle(title)) {
     return null
   }
-  // Why: "Cursor Agent" exactly (case-insensitive, no prefix/suffix) is cursor's
-  // native title. Anything with additional tokens ("⠋ Cursor Agent", "Cursor -
-  // action required") is either an Orca-synthesized working/permission title
-  // or a tighter match worth classifying.
+  // Why: exact "Cursor Agent" is cursor's info-free native title; titles with extra tokens are Orca-synthesized and worth classifying.
   if (title.trim().toLowerCase() === CURSOR_NATIVE_TITLE_LOWER) {
     return null
   }
@@ -161,15 +109,13 @@ export function detectAgentStatusFromTitle(title: string): AgentStatus | null {
     return 'idle'
   }
 
-  // Why: resolve synthetic Pi/OMP permission/idle labels before the broader
-  // Pi and braille-spinner checks below.
+  // Why: resolve synthetic Pi/OMP labels before the broader Pi/braille checks below.
   const piCompatibleSyntheticAgentStatus = getPiCompatibleSyntheticAgentStatus(title)
   if (piCompatibleSyntheticAgentStatus) {
     return piCompatibleSyntheticAgentStatus
   }
 
-  // Claude Code uses ✳ prefix for idle — must check before braille/agent-name
-  // because the title text is the task description, not "Claude Code".
+  // Claude Code uses ✳ idle prefix; check before braille/agent-name since the title is the task description, not "Claude Code".
   if (title.startsWith(`${CLAUDE_IDLE} `) || title === CLAUDE_IDLE) {
     return 'idle'
   }
@@ -190,20 +136,11 @@ export function detectAgentStatusFromTitle(title: string): AgentStatus | null {
     if (containsAny(title, ['action required', 'permission', 'waiting'])) {
       return 'permission'
     }
-    // Why: hyphen/word-char-aware boundary match (not plain substring, and
-    // stricter than `\b` — which treats `-` as a boundary) so titles like
-    // "~/codex already built" do not classify as idle via the substring
-    // "already" ⊃ "ready". See STRONG_IDLE_KEYWORDS_RE comment.
+    // Why: boundary match (not substring) so "already" ⊃ "ready" isn't classified idle. See STRONG_IDLE_KEYWORDS_RE.
     if (STRONG_IDLE_KEYWORDS_RE.test(title)) {
       return 'idle'
     }
-    // Why: hyphen/word-char-aware boundary match (not plain substring, and
-    // stricter than `\b`) so titles like "~/codex reworking diff" or
-    // "is-thinking-cap" do not classify as working via the substrings
-    // "reworking" ⊃ "working" or the `-`-adjacent "thinking" in
-    // "is-thinking-cap". Mirrors STRONG_IDLE_KEYWORDS_RE for symmetry; a
-    // false 'working' is worse than a false 'idle' because it drives
-    // active-agent UI (spinners, counts).
+    // Why: false 'working' is worse than false 'idle' (drives active-agent UI); boundary match avoids "reworking" ⊃ "working".
     if (STRONG_WORKING_KEYWORDS_RE.test(title)) {
       return 'working'
     }
@@ -216,9 +153,7 @@ export function detectAgentStatusFromTitle(title: string): AgentStatus | null {
       return 'idle'
     }
 
-    // Why: Factory Droid can publish native titles like "Factory Droid needs
-    // input" while an Execute tool is still sleeping. Droid's hook events are
-    // authoritative; don't turn a name-only native title into a completion.
+    // Why: Droid's hook events are authoritative; don't treat a name-only native title as a completion.
     if (hasDroidAgentName && !hasLegacyAgentName) {
       return null
     }
diff --git a/src/shared/text-search.ts b/src/shared/text-search.ts
index d16382202a6..0543360d229 100644
--- a/src/shared/text-search.ts
+++ b/src/shared/text-search.ts
@@ -1,23 +1,14 @@
-/* oxlint-disable max-lines -- Why: this is the single source of truth for
- * rg arg construction, rg --json parsing, git-grep submatch parsing, and
- * relative-path normalization, shared by both the local main process and
- * the SSH relay. The prior divergence between those two implementations
- * caused the maxBuffer footgun the design doc calls out; re-splitting the
- * file would re-introduce that failure mode. */
+/* oxlint-disable max-lines -- Why: single source of truth for rg/git-grep arg
+ * construction and --json/submatch parsing shared by main process and SSH relay;
+ * re-splitting would re-introduce the maxBuffer divergence the design doc calls out. */
 /**
  * Shared, pure text-search helpers used by both the local main process and the
- * SSH relay. No Electron, no child_process, no fs — the caller owns process
+ * SSH relay. No Electron, child_process, or fs — the caller owns process
  * execution and transport-specific path translation (WSL).
  *
- * Why this module exists (design doc: docs/design/share-text-search.md):
- * Before extraction, the local (`src/main/ipc/filesystem.ts`,
- * `filesystem-search-git.ts`) and relay (`src/relay/fs-handler-utils.ts`,
- * `fs-handler-git-fallback.ts`) search implementations had diverged on
- * rg arg construction, rg --json parsing, the git-grep submatch regex,
- * relative-path normalization, and — most consequentially — the relay's
- * `execFile` + `maxBuffer: 50MB` footgun that silently dropped matches on
- * large repos. Centralizing the policy prevents future drift. Both call
- * sites must use this module; see filesystem.ts and relay/fs-handler.ts.
+ * Centralizes rg/git-grep arg construction and parsing so the local and relay paths
+ * can't re-diverge (notably the relay's old execFile maxBuffer that dropped matches).
+ * Design doc: docs/design/share-text-search.md.
  */
 import { posix, win32 } from 'node:path'
 import { normalizeSearchResult } from './search-match-count'
@@ -38,9 +29,7 @@ function acceptMatch(fileResult: SearchFileResult): void {
   fileResult.matchCount = (fileResult.matchCount ?? 0) + 1
 }
 
-// Why: collapse mixed separators and strip leading slashes so results are
-// stable across Windows/Linux and never start with `/` (which would break
-// `join(rootPath, relPath)` in callers).
+// Why: normalize separators and strip leading `/` so results are cross-platform stable and don't break callers' `join(rootPath, relPath)`.
 export function normalizeRelativePath(path: string): string {
   return path.replace(/[\\/]+/g, '/').replace(/^\/+/, '')
 }
@@ -66,17 +55,10 @@ export const MAX_MATCHES_PER_FILE = 100
 export const DEFAULT_SEARCH_MAX_RESULTS = 2000
 export const SEARCH_TIMEOUT_MS = 15_000
 
-// Why: search should stay cheaper than opening a file in the editor. The
-// editor read path has a larger cap and relies on Monaco large-file handling.
+// Why: keep search cheaper than opening a file; the editor read path has a larger cap (Monaco large-file handling).
 const SEARCH_MAX_FILE_SIZE = 5 * 1024 * 1024
 
-// Why: `lineContent` is carried per-match to the renderer. Minified bundles
-// and generated files can have single lines in the megabytes; at 2000-match
-// caps that serializes into frames that blow past the 16MB SSH relay
-// `MAX_MESSAGE_SIZE`, producing "Message too large" errors on fs:search for
-// large folders (and bloats local IPC unnecessarily). Clamping to a window
-// around each match keeps the payload bounded while preserving enough
-// context for the sidebar to render the highlight.
+// Why: mega-byte lines (minified/generated files) × 2000-match caps blow past the 16MB SSH relay MAX_MESSAGE_SIZE; clamp each match's context.
 export const MAX_LINE_CONTENT_LENGTH = 500
 const TRUNCATION_MARKER = '…'
 
@@ -94,8 +76,7 @@ function clampLineContext(
   if (text.length <= MAX_LINE_CONTENT_LENGTH) {
     return { lineContent: text, column: matchStart + 1, matchLength }
   }
-  // Clamp the match itself first so a pathological multi-MB regex hit
-  // cannot defeat the windowing below.
+  // Clamp the match first so a pathological multi-MB regex hit can't defeat the windowing below.
   const clampedMatchLength = Math.min(matchLength, MAX_LINE_CONTENT_LENGTH)
   const remaining = MAX_LINE_CONTENT_LENGTH - clampedMatchLength
   const leftBudget = Math.floor(remaining / 2)
@@ -121,8 +102,7 @@ function clampLineContext(
   }
 }
 
-// Why: rg and git-grep share this append-and-cap step; keeping it in one
-// place preserves the synchronous truncation ordering required by callers.
+// Why: shared by rg and git-grep to preserve the synchronous truncation ordering callers require.
 function pushMatch(
   fileResult: SearchFileResult,
   acc: SearchAccumulator,
@@ -130,8 +110,7 @@ function pushMatch(
   lineNumber: number,
   maxResults: number
 ): 'continue' | 'stop' {
-  // Why: direct assignment avoids conditional-spread allocations on the
-  // per-match hot path while preserving optional display fields.
+  // Why: direct assignment avoids conditional-spread allocations on the per-match hot path.
   const match: SearchMatch = {
     line: lineNumber,
     column: clamped.column,
@@ -196,14 +175,10 @@ export function splitSearchGlobPatterns(patterns: string): string[] {
 }
 
 /**
- * Build the rg argv used by both callers. The returned array is the COMPLETE
- * argv (flags + `--` + query + target); the caller spawns rg with it as-is.
+ * Build the complete rg argv (flags + `--` + query + target) for both callers to spawn as-is.
  *
- * Both callers pass `rootPath` unchanged as `target` — do NOT translate the
- * target to a WSL-native path on the local side. On Windows/WSL, only the
- * rg *invocation* is routed through `wslAwareSpawn`; the target string keeps
- * its original shape, and rg's output paths are translated back to Windows
- * paths via the `transformAbsPath` callback in `ingestRgJsonLine`.
+ * Constraint: pass `rootPath` unchanged as `target` — do NOT WSL-translate it; only the rg
+ * invocation is routed through `wslAwareSpawn`, and output paths are translated back in `ingestRgJsonLine`.
  */
 export function buildRgArgs(query: string, target: string, opts: SearchOptionsLike): string[] {
   const args: string[] = [
@@ -240,17 +215,12 @@ export function buildRgArgs(query: string, target: string, opts: SearchOptionsLi
 }
 
 /**
- * Ingest a single line of rg `--json` stdout. Mutates `acc`. Returns 'stop'
- * when `maxResults` is reached so the caller can kill the child; 'continue'
- * otherwise. `transformAbsPath` lets the local caller apply WSL translation
- * (parseWslPath + toWindowsWslPath); the relay passes no transform.
+ * Ingest a single line of rg `--json` stdout, mutating `acc`. Returns 'stop' when
+ * `maxResults` is reached (so the caller can kill the child), else 'continue'.
+ * `transformAbsPath` lets the local caller apply WSL translation; the relay passes none.
  *
- * Truncation ordering invariant (see design doc): this function sets
- * `acc.truncated = true` SYNCHRONOUSLY in the same tick it returns 'stop',
- * before any child-kill. Callers must NOT flip `truncated` in their own
- * code and must NOT resolve the promise before the 'stop'-return tick has
- * completed. Breaking that ordering re-introduces the silent-truncation
- * bug the relay had with execFile's maxBuffer overflow.
+ * Invariant: sets `acc.truncated = true` synchronously in the same tick it returns
+ * 'stop'; callers must not flip `truncated` or resolve before that tick (see design doc).
  */
 export function ingestRgJsonLine(
   line: string,
@@ -293,8 +263,7 @@ export function ingestRgJsonLine(
   const lineNumber = data.line_number ?? 0
   let submatches = data.submatches ?? []
   if (submatches.length === 0) {
-    // Why: some rg regex matches report the line but no submatch ranges.
-    // Surface a navigable line-level result instead of a file row with count 0.
+    // Why: some rg matches report a line but no submatch ranges; surface a navigable line-level result instead of a count-0 row.
     submatches = [{ start: 0, end: lineContent.length > 0 ? 1 : 0 }]
   }
 
@@ -317,10 +286,7 @@ export function ingestRgJsonLine(
 /**
  * Convert a user-facing glob pattern into a git pathspec.
  *
- * Why: rg globs like `*.ts` match at any directory depth, but a bare git
- * pathspec `*.ts` only matches in the repo root. Wrapping with `:(glob)` and
- * prepending `**\/` for patterns without a path separator replicates rg's
- * recursive-by-default behaviour.
+ * Why: bare git pathspecs only match the repo root, so wrap with `:(glob)` and prepend `**\/` to replicate rg's recursive-by-default globbing.
  */
 export function toGitGlobPathspec(glob: string, exclude?: boolean): string {
   const needsRecursive = !glob.includes('/')
@@ -329,12 +295,7 @@ export function toGitGlobPathspec(glob: string, exclude?: boolean): string {
 }
 
 export function buildGitGrepArgs(query: string, opts: SearchOptionsLike): string[] {
-  // Why: --untracked searches untracked (but not ignored) files in addition
-  // to tracked ones, matching rg's default behaviour of respecting gitignore.
-  // -I skips binary files; --null uses \0 as filename delimiter so filenames
-  // with colons parse unambiguously. --no-recurse-submodules is needed because
-  // users may have submodule.recurse=true in their git config, which conflicts
-  // with --untracked and would cause git grep to fail.
+  // Why: --no-recurse-submodules avoids failing when submodule.recurse=true conflicts with --untracked; --null disambiguates colon-containing filenames.
   const gitArgs: string[] = [
     '-c',
     'submodule.recurse=false',
@@ -373,8 +334,7 @@ export function buildGitGrepArgs(query: string, opts: SearchOptionsLike): string
       hasPathspecs = true
     }
   }
-  // Why: when no include patterns are given, git grep needs a pathspec to
-  // search the working tree. '.' means "everything under cwd".
+  // Why: git grep needs a pathspec to search the working tree; '.' means everything under cwd.
   if (!hasPathspecs) {
     gitArgs.push('.')
   }
@@ -382,15 +342,11 @@ export function buildGitGrepArgs(query: string, opts: SearchOptionsLike): string
 }
 
 /**
- * Build the JS regex used to locate all submatch column positions within a
- * matched line. git grep only reports the first hit per line; we need this
- * to populate SearchMatch[] for every occurrence.
+ * Build the JS regex to locate all submatch column positions in a matched line
+ * (git grep reports only the first hit per line).
  *
- * Returns `null` when `useRegex` is true and the query is valid ERE for git
- * grep but not a valid JS `RegExp` (common mismatches: POSIX classes like
- * `[[:alpha:]]`, back-reference numbering differences, `\<` / `\>` word
- * anchors). Callers fall back to a whole-line highlight so git-reported
- * hits still appear in results instead of silently failing the request.
+ * @returns `null` when the query is valid git-grep ERE but not a valid JS RegExp
+ * (POSIX classes, back-ref numbering, `\<`/`\>` anchors); callers then fall back to a whole-line highlight.
  */
 export function buildSubmatchRegex(
   query: string,
@@ -421,9 +377,7 @@ export function ingestGitGrepLine(
     return 'continue'
   }
 
-  // Why: with --null -n, modern git emits filename\0linenum\0content.
-  // Keep the older colon parser too so relay hosts with different git output
-  // remain searchable.
+  // Why: modern git with --null -n emits filename\0linenum\0content; keep the colon parser too for hosts with older git output.
   const nullIdx = line.indexOf('\0')
   if (nullIdx === -1) {
     return 'continue'
@@ -459,10 +413,7 @@ export function ingestGitGrepLine(
     return fileResult
   }
 
-  // Why: git grep already confirmed the line matched — if we can't build a
-  // JS-side regex to find exact submatch positions (e.g. user typed a POSIX
-  // class that git accepts but JS RegExp rejects), fall back to a single
-  // whole-line highlight so the result still shows up in the UI.
+  // Why: no JS-side submatch regex (git accepts patterns JS RegExp rejects); fall back to whole-line highlight so the hit still shows.
   if (submatchRegex === null) {
     const clamped = clampLineContext(lineContent, 0, lineContent.length)
     const fileResult = getFileResult()
@@ -484,9 +435,7 @@ export function ingestGitGrepLine(
       submatchRegex.lastIndex++
     }
   }
-  // Why: git grep reported this line as a match, but JS regex semantics can
-  // still find no exact occurrence. Keep the result navigable instead of
-  // silently dropping a git-confirmed hit.
+  // Why: git grep confirmed the line but JS regex found no occurrence; keep it navigable, don't drop a git-confirmed hit.
   if (!acceptedLineMatch) {
     const clamped = clampLineContext(lineContent, 0, lineContent.length)
     const fileResult = getFileResult()
diff --git a/src/shared/tui-agent-config.ts b/src/shared/tui-agent-config.ts
index 6e5f5d8295a..4405d106162 100644
--- a/src/shared/tui-agent-config.ts
+++ b/src/shared/tui-agent-config.ts
@@ -31,41 +31,15 @@ export type TuiAgentConfig = {
   promptInjectionMode: AgentPromptInjectionMode
   /** Option terminator required before positional prompts that may look like CLI syntax. */
   argvPromptSeparator?: '--'
-  /** Why: flag that launches the TUI with the given text already in the
-   * input box but NOT submitted, so the user still gets a reviewable draft.
-   * Only set when the CLI documents native support — e.g. Claude's
-   * `--prefill <text>`. The draft-launch flow prefers this over the
-   * post-launch bracketed-paste path because it eliminates the empirical
-   * agent-readiness wait entirely: the TUI mounts with the input pre-filled.
-   * Agents without native support fall through to the paste-after-ready
-   * code path in agent-paste-draft.ts. */
+  /** Native CLI flag that seeds the input without submitting (e.g. Claude's `--prefill <text>`); preferred over the paste-after-ready path. */
   draftPromptFlag?: string
-  /** Why: agents that don't expose a `--prefill <text>`-style CLI flag but
-   * CAN read an env var on startup to seed their input box without
-   * submitting. Today only pi uses this (via Orca's overlay-installed
-   * `orca-prefill` extension reading `ORCA_PI_PREFILL`). Equivalent in
-   * effect to `draftPromptFlag`: avoids the bracketed-paste-after-ready
-   * race when the agent's startup output is long (pi prints banner,
-   * skills, and extensions for several seconds, which keeps the
-   * readiness quiet-timer resetting). When set, the draft-launch plan
-   * passes the text via this env var instead of pasting after ready. */
+  /** Startup env var that seeds the input without submitting, for agents with no `--prefill`-style flag (e.g. pi); avoids the paste-after-ready race. */
   draftPromptEnvVar?: string
-  /** Why: agents that gate first-launch behind a "Do you trust this
-   * folder?" menu (Cursor-Agent, GitHub Copilot CLI, Codex) consume the
-   * bracketed paste as menu input. Pre-write the same trust artifact the
-   * agent writes after the user accepts so the menu never fires. The actual
-   * file/path written lives in src/main/agent-trust-presets.ts; this flag
-   * just routes the workspace path through the matching preset before the
-   * agent spawns. */
+  /** Pre-write a trust artifact so the agent's first-launch "trust this folder?" menu doesn't consume the bracketed paste (see agent-trust-presets.ts). */
   preflightTrust?: 'cursor' | 'copilot' | 'codex'
-  /** Why: most TUIs need both bracketed-paste enablement and a quiet render
-   * window before pasted bytes reliably land in the composer. Codex can use
-   * a stronger signal from its own renderer: chat_composer.rs writes the
-   * `›` prompt only when the composer row exists, so Orca can paste as soon
-   * as that prompt appears after bracketed paste is enabled. */
+  /** Renderer-specific signal that the composer is ready for paste, stronger than the default quiet-render window. */
   draftPasteReadySignal?: DraftPasteReadySignal
-  /** Windows Shift+Enter override. Omitted agents keep the legacy Esc+CR path
-   * because the renderer cannot infer every local or remote TUI's decoder. */
+  /** Windows Shift+Enter encoding override; omitted agents keep the legacy Esc+CR path. */
   windowsShiftEnterEncoding?: 'csi-u'
 }
 
@@ -75,22 +49,16 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     launchCmd: 'claude',
     expectedProcess: 'claude',
     promptInjectionMode: 'argv',
-    // Why: `claude --prefill <text>` lands the TUI with `<text>` in the
-    // input box, nothing submitted. Strictly better than the paste-after-
-    // ready fallback because it eliminates the readiness race entirely.
-    // See PR https://github.com/stablyai/orca/pull/926 for context.
+    // Why: `claude --prefill <text>` seeds the input without submitting, avoiding the paste-after-ready race (PR https://github.com/stablyai/orca/pull/926).
     draftPromptFlag: '--prefill'
   },
   'claude-agent-teams': {
-    // Why: this is an Orca-provided launch mode, not a separate upstream
-    // binary. Detection follows the Orca CLI and requires Claude below.
+    // Why: an Orca-provided launch mode, not a separate binary; detection follows the Orca CLI.
     detectCmd: 'orca',
     detectCmdAliases: ['orca-dev', 'orca-ide'],
-    // Why: the Orca shim alone exists on fresh installs. Require Claude too so
-    // onboarding does not report Agent Teams when no agent CLI is installed.
+    // Why: require Claude too so fresh installs (Orca shim always present) don't report Agent Teams without an agent CLI.
     detectRequiredCommands: ['claude'],
-    // Why: native Windows and WSL use Claude's in-process Agent Teams fallback,
-    // not the Orca native-pane/tmux-shim wrapper exposed by this agent entry.
+    // Why: Windows/WSL use Claude's in-process Agent Teams fallback, not this Orca native-pane/tmux-shim wrapper.
     detectUnsupportedRuntimes: ['win32', 'wsl'],
     launchCmd: 'orca claude-teams',
     launchCmdByPlatform: {
@@ -125,9 +93,7 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     detectCmd: 'ante',
     launchCmd: 'ante',
     expectedProcess: 'ante',
-    // Why: `ante --prompt` is Ante's documented headless mode (runs the task
-    // once and exits), so Orca launches the bare interactive TUI and injects
-    // the composed prompt after startup to keep the hosted session alive.
+    // Why: `ante --prompt` is headless (runs once and exits), so launch the bare TUI and inject after startup.
     promptInjectionMode: 'stdin-after-start'
   },
   opencode: {
@@ -135,8 +101,7 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     launchCmd: 'opencode',
     expectedProcess: 'opencode',
     promptInjectionMode: 'flag-prompt',
-    // Why: opencode enables bracketed paste before its composer mounts; wait
-    // for post-\x1b[?2004h show-cursor (\x1b[?25h) so paste hits mounted input.
+    // Why: opencode enables bracketed paste before its composer mounts; wait for the post-\x1b[?2004h show-cursor so paste lands.
     draftPasteReadySignal: 'render-cursor-after-bracketed-paste'
   },
   'mimo-code': {
@@ -144,9 +109,7 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     launchCmd: 'mimo',
     expectedProcess: 'mimo',
     promptInjectionMode: 'flag-prompt',
-    // Why: mimo-code shares opencode's flag-prompt paste route, so it gets the
-    // same cursor-gated signal by parity (its startup stream is not separately
-    // validated); the quiet-window fallback bounds the risk if it differs.
+    // Why: mirrors opencode's cursor-gated signal by parity; mimo's startup stream isn't separately validated.
     draftPasteReadySignal: 'render-cursor-after-bracketed-paste'
   },
   pi: {
@@ -154,13 +117,7 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     launchCmd: 'pi',
     expectedProcess: 'pi',
     promptInjectionMode: 'argv',
-    // Why: pi has no `--prefill` flag, and bracketed-paste-after-ready
-    // races against its multi-second startup output (banner + skills +
-    // extensions list) so the paste frequently never lands. Orca's
-    // overlay installs an `orca-prefill` pi extension (see
-    // src/main/pi/titlebar-extension-service.ts) that reads this env var
-    // on session_start and calls `pi.ui.setEditorText(text)`. Same
-    // user-visible behavior as `claude --prefill <text>`.
+    // Why: pi has no `--prefill` and paste-after-ready races its long startup; the orca-prefill extension seeds this env var instead.
     draftPromptEnvVar: 'ORCA_PI_PREFILL'
   },
   omp: {
@@ -207,14 +164,9 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     promptInjectionMode: 'stdin-after-start'
   },
   kiro: {
-    // Why: the official Kiro installer (https://cli.kiro.dev/install) places a
-    // binary named `kiro-cli` on PATH — there is no `kiro` binary. Keep the
-    // TuiAgent id as 'kiro' for stored preferences, but detect/launch/identify
-    // the real binary name so the agent is recognized as active.
+    // Why: the Kiro installer (https://cli.kiro.dev/install) ships `kiro-cli`, not `kiro`; keep id 'kiro' for stored prefs.
     detectCmd: 'kiro-cli',
-    // Why: trust flags are accepted by Kiro's chat subcommand, not the
-    // top-level kiro-cli command. Keep TUI startup explicit so default args
-    // like --trust-all-tools are appended where the installed CLI accepts them.
+    // Why: trust flags like --trust-all-tools attach to Kiro's `chat` subcommand, not top-level kiro-cli.
     launchCmd: 'kiro-cli chat --tui',
     expectedProcess: 'kiro-cli',
     promptInjectionMode: 'stdin-after-start'
@@ -226,9 +178,7 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     promptInjectionMode: 'stdin-after-start'
   },
   aug: {
-    // Why: the published @augmentcode/auggie npm package installs a binary
-    // named `auggie` (not `aug`). Keep the TuiAgent id as 'aug' for stored
-    // preferences, but detect/launch/identify the real binary name.
+    // Why: @augmentcode/auggie installs a binary named `auggie`, not `aug`; keep id 'aug' for stored prefs.
     detectCmd: 'auggie',
     launchCmd: 'auggie',
     expectedProcess: 'auggie',
@@ -247,23 +197,15 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     promptInjectionMode: 'stdin-after-start'
   },
   'command-code': {
-    // Why: `npm i -g command-code` installs two binaries — `command-code` and
-    // the shorter alias `cmd`. Use the full `command-code` name so detection
-    // does not collide with Windows' built-in `cmd.exe` shell, which
-    // agent-process-recognition normalizes to `cmd` after stripping the .exe.
+    // Why: use the full name (not its `cmd` alias) so detection doesn't collide with Windows' built-in cmd.exe.
     detectCmd: 'command-code',
-    // Why: Command Code's documented positional prompt starts the turn, while
-    // paste-after-start can leave the prompt sitting in the composer. `--trust`
-    // mirrors the preflight trust behavior Orca applies to other first-run
-    // TUIs so launch prompts do not consume the task text.
+    // Why: `--trust` skips the first-run trust prompt so it doesn't consume the task text.
     launchCmd: 'command-code --trust',
     expectedProcess: 'command-code',
     promptInjectionMode: 'argv'
   },
   continue: {
-    // Why: Continue's CLI binary is `cn`; `continue` is a shell builtin in
-    // bash/zsh, so using it here can resolve to the shell keyword instead of
-    // the coding agent.
+    // Why: Continue's CLI binary is `cn`; `continue` is a bash/zsh builtin and would resolve to the shell keyword.
     detectCmd: 'cn',
     launchCmd: 'cn',
     expectedProcess: 'cn',
@@ -274,11 +216,7 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     launchCmd: 'cursor-agent',
     expectedProcess: 'cursor-agent',
     promptInjectionMode: 'argv',
-    // Why: cursor-agent's first-launch trust menu ([a]/[w]/[q]) used to
-    // swallow our bracketed paste. Pre-writing the same `.workspace-trusted`
-    // marker the CLI itself writes after the user accepts (see
-    // agent-trust-presets.ts) makes the menu skip entirely, so the draft
-    // URL paste lands in the input as intended.
+    // Why: first-launch trust menu swallows the bracketed paste; pre-write the .workspace-trusted marker so it skips (agent-trust-presets.ts).
     preflightTrust: 'cursor'
   },
   droid: {
@@ -286,8 +224,7 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     launchCmd: 'droid',
     expectedProcess: 'droid',
     promptInjectionMode: 'argv',
-    // Why: Droid decodes CSI-u on Windows and treats Orca's legacy Esc+CR
-    // fallback as plain Enter, which submits instead of inserting a newline.
+    // Why: Droid decodes CSI-u on Windows; the legacy Esc+CR fallback reads as Enter and submits instead of newline.
     windowsShiftEnterEncoding: 'csi-u'
   },
   kimi: {
@@ -297,9 +234,7 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     promptInjectionMode: 'stdin-after-start'
   },
   'mistral-vibe': {
-    // Why: Mistral's installer and PyPI package expose `vibe` even though the
-    // package/project name is mistral-vibe. Keep the old name as an alias for
-    // manually wrapped installs.
+    // Why: installer exposes binary `vibe` though the package is mistral-vibe; keep old name as alias for wrapped installs.
     detectCmd: 'vibe',
     detectCmdAliases: ['mistral-vibe'],
     launchCmd: 'vibe',
@@ -307,8 +242,7 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     promptInjectionMode: 'stdin-after-start'
   },
   'qwen-code': {
-    // Why: the upstream package is QwenLM/qwen-code, but its installed CLI
-    // executable on PATH is `qwen`, so detect/launch/recognition must use that.
+    // Why: package is qwen-code but its installed CLI binary on PATH is `qwen`.
     detectCmd: 'qwen',
     launchCmd: 'qwen',
     expectedProcess: 'qwen',
@@ -322,12 +256,10 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
   },
   hermes: {
     detectCmd: 'hermes',
-    // Why: bare `hermes` opens the classic REPL in recent Hermes releases;
-    // `--tui` starts the full-screen agent UI Orca is designed to host.
+    // Why: bare `hermes` opens the classic REPL; `--tui` starts the full-screen agent UI Orca hosts.
     launchCmd: 'hermes --tui',
     expectedProcess: 'hermes',
-    // Why: Hermes owns prompt delivery through its startup-query contract,
-    // which submits only after the TUI composer and session are ready.
+    // Why: Hermes delivers the prompt via its startup-query contract, submitting only after the composer is ready.
     promptInjectionMode: 'hermes-query'
   },
   openclaw: {
@@ -340,39 +272,25 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     detectCmd: 'copilot',
     launchCmd: 'copilot',
     expectedProcess: 'copilot',
-    // Why: `copilot --prompt <text>` runs non-interactively and exits on
-    // completion, which would kill the TUI session Orca is hosting.
-    // `-i/--interactive <prompt>` starts an interactive session with the
-    // initial prompt pre-executed — the behavior Orca needs.
+    // Why: `--prompt` exits on completion (kills the hosted session); `-i/--interactive` keeps it interactive.
     promptInjectionMode: 'flag-interactive',
-    // Why: Copilot's first-launch trust menu used to swallow our bracketed
-    // paste. Pre-appending the workspace path to `trustedFolders` in
-    // ~/.copilot/config.json (the same array Copilot's own
-    // `addTrustedFolder` writes after the user accepts) makes the menu skip
-    // entirely. See agent-trust-presets.ts for the file layout.
+    // Why: first-launch trust menu swallows the bracketed paste; pre-write trust so it skips (see agent-trust-presets.ts).
     preflightTrust: 'copilot'
   },
   grok: {
     detectCmd: 'grok',
     launchCmd: 'grok',
     expectedProcess: 'grok',
-    // Why: Grok CLI accepts an initial prompt as a positional argv
-    // (`grok "fix the bug"`). Prefer argv over stdin-after-start so multi-line
-    // / special-character prompts are not typed as raw PTY keystrokes, and so
-    // clipboard-derived launch text is not mangled by line-edit shortcuts.
+    // Why: argv (grok takes a positional prompt) so multi-line/special-char text isn't mangled as raw PTY keystrokes.
     promptInjectionMode: 'argv',
-    // Why: prompts such as `help` or `--version` otherwise select Grok CLI
-    // syntax instead of starting an interactive turn with that literal text.
+    // Why: separator so prompts like `help`/`--version` aren't parsed as Grok CLI syntax.
     argvPromptSeparator: '--'
   },
   devin: {
     detectCmd: 'devin',
     launchCmd: 'devin',
     expectedProcess: 'devin',
-    // Why: `devin -- <prompt>` auto-submits immediately (docs.devin.ai/cli).
-    // `stdin-after-start` starts the REPL with no argv prompt; Orca then sends
-    // `followupPrompt` to the PTY as plain input + Enter after startup (not
-    // bracketed paste). Use `draftPrompt` / agent-paste-draft for review-before-send.
+    // Why: `devin -- <prompt>` auto-submits immediately (docs.devin.ai/cli), so start the REPL with no argv prompt.
     promptInjectionMode: 'stdin-after-start'
   }
 }
@@ -390,9 +308,7 @@ export function getTuiAgentLaunchCommand(
   platform: NodeJS.Platform,
   opts?: { isRemote?: boolean }
 ): string {
-  // Why: the SSH relay shim is always named `orca` on Unix, so the local-only
-  // `orca-ide` rename (avoids shadowing the GNOME Orca screen reader) must not
-  // leak to Linux remotes — the remote has no such desktop binary on PATH.
+  // Why: local-only orca-ide rename (avoids GNOME Orca clash) must not leak to Linux remotes, whose relay shim is always `orca`.
   if (opts?.isRemote && platform === 'linux') {
     return config.launchCmd
   }
diff --git a/src/shared/types.ts b/src/shared/types.ts
index b28bf97d451..fbb1288de3d 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -2641,93 +2641,55 @@ export type GlobalSettings = {
   terminalCursorOpacity?: number
   terminalQuickCommands?: TerminalQuickCommand[]
   windowBackgroundBlur?: boolean
-  /** Why: Windows-only. When on, the close (X) button hides the window to the
-   *  system tray instead of quitting Orca; off keeps the default quit-on-close.
-   *  The tray icon itself is always present on Windows regardless of this flag. */
+  /** Windows-only: close (X) hides to tray instead of quitting; the tray icon is always present regardless. */
   minimizeToTrayOnClose?: boolean
-  /** Why: macOS keeps Orca running after its last window closes, so this
-   *  controls the additive menu-bar entry without changing Dock behavior. */
+  /** macOS: toggles the additive menu-bar entry (Orca survives last-window close); doesn't change Dock behavior. */
   showMenuBarIcon?: boolean
-  /** Why: Windows terminals conventionally use right-click as a paste gesture,
-   *  while macOS/Linux default to their existing context menu behavior. */
+  /** Windows convention: right-click pastes; macOS/Linux keep the context menu. */
   terminalRightClickToPaste: boolean
-  /** One-shot guard that distinguishes the old global true default from a
-   *  choice made after the setting became available on every platform. */
+  /** One-shot guard distinguishing the old global true default from a per-platform choice. */
   terminalRightClickToPasteDefaultedForPlatform?: boolean
-  /** Why: COMSPEC always points to cmd.exe on stock Windows, so without an
-   *  explicit setting the terminal would always open CMD instead of the
-   *  user's preferred shell. Defaults to 'powershell.exe' which is the
-   *  modern choice for an IDE context. Only consulted on Windows. */
+  /** Windows-only: COMSPEC always points to cmd.exe, so this explicit shell (default 'powershell.exe') overrides it. */
   terminalWindowsShell: string
-  /** Why: when WSL is the Windows default shell, users with multiple distros
-   *  need Orca to launch terminals and scan agents in the same chosen distro
-   *  instead of whatever WSL currently marks as its global default. */
+  /** Pins the WSL distro for terminals/agent scans instead of WSL's current global default. */
   terminalWindowsWslDistro?: string | null
-  /** Why: account/auth location is independent from the user's preferred
-   *  terminal shell. A user may default new terminals to WSL while still
-   *  inspecting or adding Windows-scoped provider accounts. */
+  /** Account/auth location independent from the terminal shell (e.g. WSL terminals but Windows-scoped accounts). */
   localAccountRuntime: 'host' | 'wsl'
   localAccountWslDistro?: string | null
-  /** Why: installed-agent detection is also a local environment choice. Keep
-   *  it independent so users can inspect Windows and WSL PATH state without
-   *  changing the default terminal shell. */
+  /** Independent from the terminal shell so users can inspect Windows vs WSL agent PATH state without changing it. */
   localAgentRuntime?: 'host' | 'wsl'
   localAgentWslDistro?: string | null
   /** Why: global is only the default policy; project-level runtime preference wins. */
   localWindowsRuntimeDefault: GlobalWindowsRuntimeDefault
-  /** Why: "PowerShell" is the product-facing shell family. Auto resolves to
-   *  PowerShell 7+ when present and falls back to inbox Windows PowerShell. */
+  /** 'auto' resolves to PowerShell 7+ when present, else falls back to inbox Windows PowerShell. */
   terminalWindowsPowerShellImplementation: 'auto' | 'powershell.exe' | 'pwsh.exe'
   terminalFocusFollowsMouse: boolean
-  /** Why: mirrors X11 / gnome-terminal "copy on select" UX — making a terminal
-   *  selection copies it to the system clipboard automatically, so users can
-   *  paste with Cmd/Ctrl+V without an intervening Cmd/Ctrl+Shift+C. Defaults
-   *  to false so existing users keep the explicit-copy behavior. */
+  /** X11/gnome-terminal "copy on select": selecting text auto-copies to the clipboard; default off. */
   terminalClipboardOnSelect: boolean
-  /** Why: lets TUIs like Grok, tmux, nvim, and fzf copy to the system clipboard
-   *  via the OSC 52 escape sequence — essential for SSH-hosted workflows where
-   *  the terminal is the only bridge to the local clipboard. Defaults to
-   *  false because OSC 52 is a classic data-exfiltration vector (any
-   *  process piping untrusted output into the terminal — `cat attacker.log`
-   *  — can silently rewrite the user's clipboard). Opt-in preserves the
-   *  conservative default while making the capability one toggle away. */
+  /** Enables OSC 52 clipboard writes for TUIs (SSH clipboard bridge); default off since OSC 52 is a clipboard-exfiltration vector. */
   terminalAllowOsc52Clipboard: boolean
-  /** Experimental Claude Code Agent Teams integration. Native panes use a
-   *  tmux-compatible shim so teammate output stays on Orca's normal PTY path. */
+  /** Experimental Claude Agent Teams; native panes use a tmux-compatible shim so teammate output stays on the normal PTY path. */
   claudeAgentTeamsMode?: ClaudeAgentTeamsMode
-  /** Where the repo setup script runs on workspace create. Defaults to a
-   *  background "Setup" tab so the user's main terminal stays immediately
-   *  usable without the setup output crowding the initial pane. */
+  /** Where the repo setup script runs on workspace create; defaults to a background "Setup" tab to keep the main terminal usable. */
   setupScriptLaunchMode: SetupScriptLaunchMode
   terminalScrollbackRows: number
-  /** Optional app-level proxy for Electron networking and locally spawned PTYs.
-   *  Empty preserves system proxy settings plus inherited proxy env behavior. */
+  /** Optional app-level proxy for Electron networking and local PTYs; empty preserves system/inherited proxy env. */
   httpProxyUrl?: string
   /** Optional semicolon/comma/newline-separated bypass rules for httpProxyUrl. */
   httpProxyBypassRules?: string
-  /** Why: corporate TLS-intercepting proxies can break Electron HTTP/2 downloads;
-   *  this opt-in compatibility mode applies Chromium's process-wide HTTP/1.1 switch. */
+  /** Why: corporate TLS-intercepting proxies can break HTTP/2 downloads; opt-in Chromium process-wide HTTP/1.1 switch. */
   electronHttp1CompatibilityMode?: boolean
-  /** Why: opening arbitrary links inside Orca uses an isolated guest browser surface.
-   *  The setting stays opt-in so existing workflows continue to use the system browser
-   *  until the user explicitly wants worktree-scoped in-app browsing. */
+  /** Opt-in in-app browsing (isolated guest surface); default keeps links opening in the system browser. */
   openLinksInApp: boolean
-  /** Why: worktree-scoped localhost hostnames make same-app tabs distinguishable
-   *  in external browsers. Opt-in (default off): serving the app under a different
-   *  host can break dev apps that bind cookies/sessions to localhost. */
+  /** Worktree-scoped localhost hostnames to distinguish tabs; opt-in since a non-localhost host can break apps binding cookies/sessions to localhost. */
   localhostWorktreeLabelsEnabled?: boolean
-  /** Why: terminal link routing asks once at first use instead of silently
-   *  changing where links open for new users. */
+  /** Tracks the one-time first-use prompt for terminal link routing (avoid silently changing where links open). */
   openLinksInAppPreferencePrompted: boolean
-  /** Opt-in: open newly launched coding-agent tabs directly in the native chat
-   *  view instead of the raw terminal. Off by default so existing workflows are
-   *  unchanged. Optional for legacy-settings compatibility; defaults applied. */
+  /** Opt-in: open new coding-agent tabs in native chat instead of the raw terminal; optional for legacy settings. */
   openAgentTabsInChatByDefault?: boolean
-  /** Experimental: native chat surface for Claude/Codex terminal sessions.
-   *  Off by default while the desktop UX is still being exercised. */
+  /** Experimental native chat surface for Claude/Codex sessions; off by default. */
   experimentalNativeChat?: boolean
-  /** Last explicit native-chat model and model-scoped option selections. Live
-   * panes still require an applied/dispatched record before showing a value. */
+  /** Last explicit native-chat model + option selections; live panes need an applied/dispatched record before showing a value. */
   nativeChatSessionOptions?: PersistedNativeChatSessionOptions
   /** Extra launcher rows for the worktree "Open in" submenu. VS Code is always shown first. */
   openInApplications?: OpenInApplication[]
@@ -2738,177 +2700,109 @@ export type GlobalSettings = {
   sourceControlViewMode: SourceControlViewMode
   /** Preferred Source Control group order. Per-user, not per-workspace. */
   sourceControlGroupOrder: SourceControlGroupOrder
-  /** When enabled, the Source Control compare base defaults to the current
-   *  branch's upstream (prioritizing local changes) instead of the repo
-   *  default branch. Only affects the compare/diff view, not the PR/rebase
-   *  merge target. Per-user, not per-workspace. */
+  /** Compare base defaults to the branch upstream instead of the repo default; affects only the compare/diff view, not the PR/rebase target. Per-user. */
   sourceControlCompareAgainstUpstream: boolean
   /** Whether to show the Orca app name in the titlebar. */
   showTitlebarAppName: boolean
-  /** Why: some users do not use the Tasks feature and prefer to keep the
-   *  left sidebar free of its button entirely. Hiding the button here also
-   *  removes it from keyboard navigation. */
+  /** Hides the Tasks sidebar button (also removes it from keyboard navigation). */
   showTasksButton: boolean
-  /** Why: Automations can be restored from Settings or the View menu, so this
-   *  only controls whether the top-level sidebar shortcut is shown. */
+  /** Only toggles the sidebar shortcut; Automations stay reachable from Settings/View menu. */
   showAutomationsButton?: boolean
-  /** Why: Orca Mobile remains reachable from Settings; this only controls
-   *  whether the top-level sidebar shortcut is shown. */
+  /** Only toggles the sidebar shortcut; Orca Mobile stays reachable from Settings. */
   showMobileButton?: boolean
-  /** Why: pinned workspaces default to one sidebar location; users can opt
-   *  back into seeing them in their natural groups too. */
+  /** Pinned workspaces show in one sidebar location by default; opt in to also show them in their natural groups. */
   showPinnedWorktreesInGroups?: boolean
-  /** Controls how Ctrl+Tab chooses the next visible tab. Optional for
-   *  profiles saved before this setting existed; readers default to MRU. */
+  /** How Ctrl+Tab picks the next visible tab; optional (older profiles), readers default to MRU. */
   ctrlTabOrderMode?: CtrlTabOrderMode
-  /** Why: Orca-first preserves fast workspace/app control from agent TUIs.
-   *  Terminal-first is opt-in for users who want shell/TUI bindings to win. */
+  /** Orca-first keeps app shortcuts from TUIs; terminal-first is opt-in to let shell/TUI bindings win. */
   terminalShortcutPolicy?: TerminalShortcutPolicy
-  /** Why: Floating Workspace is the default global surface so users can
-   *  reach terminal, browser, and markdown tabs outside repo/worktree context. */
+  /** Floating Workspace: global surface for terminal/browser/markdown tabs outside repo/worktree context. */
   floatingTerminalEnabled: boolean
-  /** One-shot migration flag for the default-on rollout. Before this field
-   *  landed, the floating workspace defaulted off and many profiles persisted
-   *  that inherited false. Once migrated, an explicit off choice sticks. */
+  /** One-shot migration flag for the floating-workspace default-on rollout; after migration an explicit off sticks. */
   floatingTerminalDefaultedForAllUsers?: boolean
-  /** Where new Floating Workspace terminal tabs start. Empty or '~' means
-   *  the user's home directory; markdown notes use Orca's app-owned
-   *  floating workspace under Electron userData. */
+  /** Start dir for new floating-workspace terminal tabs; empty or '~' = home dir. */
   floatingTerminalCwd: string
-  /** Picker-approved Floating Workspace directories that may be reauthorized
-   *  across restarts. Renderer-provided text alone must not populate this. */
+  /** Picker-approved floating-workspace dirs reauthorized across restarts; renderer text alone must not populate this. */
   floatingTerminalTrustedCwds?: string[]
   /** One-shot migration marker for legacy floating workspace cwd trust grants. */
   floatingTerminalCwdMigratedToAppWorkspace?: boolean
-  /** Where the Floating Workspace toggle is shown. Defaults to the floating
-   *  button for discoverability. */
+  /** Where the Floating Workspace toggle is shown; defaults to the floating button for discoverability. */
   floatingTerminalTriggerLocation: FloatingTerminalTriggerLocation
-  /** Legacy pre-file-backed keyboard shortcut overrides. New writes go to
-   *  ~/.orca/keybindings.json; main migrates this once when present. */
+  /** Legacy keyboard-shortcut overrides; new writes go to ~/.orca/keybindings.json, migrated once when present. */
   keybindings?: KeybindingOverrides
   diffDefaultView: 'inline' | 'side-by-side'
   diffWordWrap: boolean
   combinedDiffFileTreeVisibleByDefault: boolean
-  /** Comment author logins the user manually marked as bots (stored lowercased).
-   *  Why: some review bots use regular user accounts that defeat both provider
-   *  metadata and login heuristics, so the Humans/Bots comment filter needs a
-   *  user-supplied escape hatch. */
+  /** Bot-marked comment-author logins (stored lowercased); escape hatch for review bots on regular accounts that defeat provider metadata/heuristics. */
   prBotAuthorOverrides: string[]
   notifications: NotificationSettings
-  /** When true, a countdown timer is shown after a Claude agent becomes idle,
-   *  indicating time remaining before the prompt cache expires. Disabled by default. */
+  /** Countdown after a Claude agent goes idle showing time left before the prompt cache expires. */
   promptCacheTimerEnabled: boolean
-  /** Prompt-cache TTL in milliseconds. Only two values are supported:
-   *  300 000 (5 min, the standard Anthropic API / Bedrock TTL) and
-   *  3 600 000 (1 hr, for extended-TTL plans). */
+  /** Prompt-cache TTL (ms); only 300000 (5 min standard) or 3600000 (1 hr, extended-TTL plans). */
   promptCacheTtlMs: number
-  /** Why: Codex rate-limit account routing is a durable app preference owned by
-   *  the main process, not transient UI state. Persisting the selected managed
-   *  auth here lets Orca prepare shared ~/.codex before the renderer hydrates,
-   *  while keeping this scope explicitly separate from Codex usage analytics
-   *  and external terminal sessions. */
+  /** Why: durable main-owned pref so Orca can prepare shared ~/.codex before the renderer hydrates. */
   codexManagedAccounts: CodexManagedAccount[]
   activeCodexManagedAccountId: string | null
   activeCodexManagedAccountIdsByRuntime?: CodexManagedAccountRuntimeSelection
-  /** Why: Claude Code keeps conversations under one shared config root. Orca
-   *  persists only per-account auth material here so switching accounts does
-   *  not fork prior chat/session context the way CLAUDE_CONFIG_DIR swapping would. */
+  /** Why: persist only per-account auth (not a CLAUDE_CONFIG_DIR swap) so switching accounts doesn't fork Claude's shared chat/session context. */
   claudeManagedAccounts: ClaudeManagedAccount[]
   activeClaudeManagedAccountId: string | null
   activeClaudeManagedAccountIdsByRuntime?: ClaudeManagedAccountRuntimeSelection
-  /** When true, each worktree gets its own shell history file so ArrowUp
-   *  does not surface commands from other worktrees. Defaults to true.
-   *  Disable to revert to shared global shell history. */
+  /** Per-worktree shell history file so ArrowUp doesn't surface other worktrees' commands. Defaults to true. */
   terminalScopeHistoryByWorktree: boolean
-  /** Kill switch for hidden terminal view parking — unmounting long-hidden
-   *  terminal panes while a pane-less watcher keeps PTY side effects alive.
-   *  Defaults to true; `false` disables parking entirely. */
+  /** Kill switch for hidden terminal view parking: unmount long-hidden panes while a pane-less watcher keeps PTY side effects alive. */
   terminalHiddenViewParking?: boolean
-  /** Kill switch for main-process terminal side-effect authority: when true
-   *  (default), local-daemon/SSH PTY title/bell/agent facts are consumed from
-   *  the `pty:sideEffect` channel and renderer byte parsers stay unregistered
-   *  for those PTYs; `false` restores renderer byte parsing. */
+  /** Kill switch for main-process PTY side-effect authority; on (default) = title/bell/agent facts via pty:sideEffect channel, not renderer byte parsing. */
   terminalMainSideEffectAuthority?: boolean
-  /** Kill switch for main's hidden-delivery gate (Phase 4): when true
-   *  (default) AND terminalMainSideEffectAuthority is on, main drops PTY byte
-   *  delivery to hidden renderer views after model ingestion; reveal restores
-   *  from the model snapshot. `false` restores hidden byte delivery. */
+  /** Kill switch for main's hidden-delivery gate (Phase 4): drops PTY bytes to hidden views after model ingestion; requires terminalMainSideEffectAuthority. */
   terminalHiddenDeliveryGate?: boolean
-  /** Kill switch for the main model query responder (Phase 5): when true
-   *  (default) AND both Phase-4 gate switches are on, main answers terminal
-   *  queries (DA1/CPR/DECRPM, …) embedded in hidden-dropped chunks from the
-   *  runtime emulator. `false` silences the responder without changing drops. */
+  /** Kill switch for main's model query responder (Phase 5); active only when both Phase-4 gates are also on. */
   terminalModelQueryAuthority?: boolean
   /** Which agent to pre-select in the new-workspace composer.
    *  - null: auto (first detected agent)
    *  - 'blank': blank terminal (no agent launched)
    *  - TuiAgent: a specific agent id */
   defaultTuiAgent: TuiAgent | 'blank' | null
-  /** Agents hidden from future picker and automatic launch choices. Detection
-   *  remains a raw PATH capability snapshot. */
+  /** Agents hidden from picker/auto-launch; detection stays a raw PATH snapshot. */
   disabledTuiAgents: TuiAgent[]
-  /** One-shot guard so the experimental Claude Agent Teams launch mode starts
-   *  hidden for existing profiles without overriding later user opt-ins. */
+  /** One-shot guard: start Claude Agent Teams hidden for existing profiles without overriding later opt-ins. */
   claudeAgentTeamsDefaultDisabledMigrated?: boolean
-  /** Why: worktree deletion is destructive (git worktree remove + rm -rf of the
-   *  working directory), so Orca shows a confirmation dialog by default. Users
-   *  who delete frequently can opt into skipping the dialog via a "Don't ask
-   *  again" checkbox inside it or from the General settings pane. We keep this
-   *  defaulted to false so first-time behavior stays safe. */
+  /** Why: worktree deletion is destructive (rm -rf of the working dir), so confirm by default. */
   skipDeleteWorktreeConfirm: boolean
-  /** Why: closing a terminal with child processes kills foreground work. Keep
-   *  this separate from other destructive confirmations so power users can speed
-   *  up terminal cleanup without weakening workspace or automation safeguards. */
+  /** Why: closing a terminal with child processes kills foreground work; keep this skip separate from other confirmations. */
   skipCloseTerminalWithRunningProcessConfirm: boolean
-  /** Why: deleting an automation also deletes its run history. Keep this
-   *  separate from worktree deletion so skipping one destructive confirmation
-   *  does not silently skip the other. */
+  /** Why: deleting an automation also deletes its run history; keep this skip separate from worktree deletion. */
   skipDeleteAutomationConfirm: boolean
-  /** Why: Codex rate-limit resets consume a scarce reset credit and immediately
-   *  affect the signed-in account, so keep the skip preference explicit and
-   *  separate from local destructive-action confirmations. */
+  /** Why: a Codex rate-limit reset spends a scarce credit on the live account; keep this skip separate from local confirmations. */
   skipCodexRateLimitResetConfirm: boolean
   /** Default preset in the new-workspace GitHub task view. */
   defaultTaskViewPreset: TaskViewPresetId
-  /** Why: persists the user's last-used task source so the Tasks page
-   *  reopens to the same provider instead of always defaulting to GitHub. */
+  /** Persisted last-used task source so Tasks reopens to the same provider instead of defaulting to GitHub. */
   defaultTaskSource: TaskProvider
-  /** Why: users may only work from one hosted task system. Persisting this
-   *  list hides unused providers from Tasks chrome and sidebar shortcuts while
-   *  leaving the chosen default source stable when it is still visible. */
+  /** Persisted visible task providers; hides unused providers from Tasks chrome and sidebar shortcuts. */
   visibleTaskProviders: TaskProvider[]
-  /** Why: one-shot migration guard so Jira becomes visible for existing
-   *  profiles once, without re-adding it after a later deliberate opt-out. */
+  /** Why: one-shot guard to make Jira visible for existing profiles once, without re-adding after a later opt-out. */
   visibleTaskProvidersDefaultedForJira: boolean
-  /** Why: persists the user's repo selection in the cross-repo tasks view.
-   *  `null` means sticky-all — every eligible repo is selected, including
-   *  repos added in future sessions, so the "All repos" label stays
-   *  truthful. An explicit array freezes the curated subset; ids no longer
-   *  eligible are silently dropped on load. An empty array after that drop
-   *  is treated as `null`. */
+  /** Persisted repo selection (cross-repo tasks view). null = sticky-all (includes future-added repos);
+   *  string[] = frozen curated subset (ineligible ids dropped on load; empty after drop is treated as null). */
   defaultRepoSelection: string[] | null
-  /** Why: persists the user's Linear team selection in the tasks view.
-   *  Same nullable-array pattern as `defaultRepoSelection`: `null` = sticky-all,
-   *  `string[]` = frozen subset of team IDs. */
+  /** Persisted Linear team selection (tasks view). Same nullable-array pattern as
+   *  defaultRepoSelection: null = sticky-all, string[] = frozen subset of team IDs. */
   defaultLinearTeamSelection: string[] | null
   /** Session cookie for OpenCode Go rate-limit fetching. Stored encrypted. */
   opencodeSessionCookie: string
-  /** Optional workspace ID override for OpenCode Go. When set, skips the
-   *  workspaces lookup and fetches usage directly for this workspace. */
+  /** Optional OpenCode Go workspace ID override; when set, skips the workspaces lookup and fetches usage directly. */
   opencodeWorkspaceId: string
   /** Optional MiniMax group id. When empty, the usage fetcher extracts minimax_group_id_v2 from the cookie. */
   minimaxGroupId: string
   /** Comma-separated MiniMax model names to show in the status bar usage window. */
   minimaxUsageModels: string
-  /** Whether to extract OAuth credentials from the local Gemini CLI installation
-   *  for rate-limit fetching. Disabled by default for explicit opt-in. */
+  /** Extract OAuth credentials from the local Gemini CLI for rate-limit fetching. Off by default (explicit opt-in). */
   geminiCliOAuthEnabled: boolean
   /** Per-agent CLI command overrides. A missing key means use the catalog default binary name. */
   agentCmdOverrides: Partial<Record<TuiAgent, string>>
-  /** Why: Orca bridges Codex session history from the user's real Codex home into
-   *  its managed home so /resume finds it, but defaults to ~/.codex. Users who run
-   *  Codex with a custom CODEX_HOME can point history discovery at that folder here.
-   *  History-only: this does not change which account/config/hooks Orca uses. */
+  /** Custom CODEX_HOME for Codex session-history discovery (defaults to ~/.codex).
+   *  History-only: does not change which account/config/hooks Orca uses. */
   codexSessionSourceHome?: {
     /** Absolute host path; empty/undefined falls back to ~/.codex. */
     host?: string
@@ -2921,82 +2815,50 @@ export type GlobalSettings = {
   agentDefaultEnv?: Partial<Record<TuiAgent, Record<string, string>>>
   /** One-shot guard for adding yolo-mode default args to untouched agent launch profiles. */
   agentYoloDefaultsMigrated?: boolean
-  /** Why: disabling must persist so startup does not reinstall global agent
-   *  hook entries right after the user removes them from Settings or CLI. */
+  /** Why: disabling must persist so startup doesn't reinstall global agent hook entries the user just removed. */
   agentStatusHooksEnabled: boolean
-  /** Dismissed freshness tuples grant no write authority; they only keep the
-   *  same exact official placement/revision from nudging more than once. */
+  /** Dismissed freshness tuples: no write authority, just suppress re-nudging the same official placement/revision. */
   dismissedSkillFreshnessNudges?: string[]
-  /** Why: generated tab titles are semantic but subjective, so they stay opt-in
-   *  and manual renames remain the stronger user intent. */
+  /** Why: generated tab titles are subjective, so they stay opt-in and manual renames win. */
   tabAutoGenerateTitle: boolean
-  /** Why: pinned tabs can still be closed via the keyboard/native-menu close
-   *  path, so this gates that close behind a confirmation prompt to prevent
-   *  accidental loss. Defaults on. */
+  /** Why: pinned tabs can still be closed via keyboard/native-menu; this gates that behind a confirmation. Defaults on. */
   confirmClosePinnedTab: boolean
   /** When true, Orca requests local awake assertions while hook-reported agents are working. */
   keepComputerAwakeWhileAgentsRun: boolean
-  /** Why: macOS terminals must choose between letting Option compose layout
-   *  characters (@ on German, € on French) or treating Option as Meta/Esc for
-   *  readline shortcuts. Mirrors Ghostty's macos-option-as-alt setting — and
-   *  like Ghostty, defaults to 'auto', which fingerprints the active keyboard
-   *  layout via navigator.keyboard.getLayoutMap() at runtime and picks
-   *  'true' for US / US-International and 'false' for everything else.
-   *  'auto'  = layout-aware (default). See docs/terminal-option-key-layout-aware-default.md.
-   *  'false' = compose (for non-US keyboards);
-   *  'true'  = full Meta on both Option keys;
-   *  'left' / 'right' = only that Option key acts as Meta, the other composes. */
+  /** macOS Option key: compose layout chars (@ German, € French) vs act as Meta/Esc for readline.
+   *  'auto' (default) = layout-aware via navigator.keyboard.getLayoutMap() (US → Meta, else compose);
+   *  'false' = compose; 'true' = Meta on both Option keys; 'left'/'right' = only that key is Meta.
+   *  See docs/terminal-option-key-layout-aware-default.md. */
   terminalMacOptionAsAlt: 'auto' | 'true' | 'false' | 'left' | 'right'
-  /** One-shot migration guard for the 'auto' rollout. Before this field landed,
-   *  the field defaulted to 'true' for everyone, meaning a persisted 'true'
-   *  could either be an explicit user choice or just the old default. On first
-   *  launch after upgrade, if this flag is false and the persisted value is
-   *  'true', we reset to 'auto' so non-US users stop getting their keyboard
-   *  broken by the stale global default. US users land on 'true' anyway via
-   *  detection, so no visible behavior change. Then we flip this flag to true
-   *  and never migrate again. */
+  /** One-shot migration guard for the 'auto' rollout. Old default 'true' was ambiguous (explicit vs default);
+   *  on first upgrade launch, reset a persisted 'true' to 'auto' so non-US keyboards aren't broken by the stale default. */
   terminalMacOptionAsAltMigrated: boolean
-  /** Controls whether macOS terminal input translates the physical JIS Yen (¥)
-   *  key to a backslash, matching the common terminal expectation for that key. */
+  /** Whether macOS terminal input maps the physical JIS Yen (¥) key to backslash, per common terminal expectation. */
   terminalJISYenToBackslash: boolean
   experimentalMobile: boolean
-  /** Why: the iOS Simulator feature is default-on for capable macOS hosts, but
-   *  users need a durable off switch that hides UI affordances and blocks CLI attach. */
+  /** Why: iOS Simulator is default-on for capable macOS hosts; this is the durable off switch (hides UI, blocks CLI attach). */
   mobileEmulatorEnabled?: boolean
   /** Preferred iOS Simulator UDID for UI auto-attach and agent CLI attach. */
   mobileEmulatorDefaultDeviceUdid?: string | null
-  /** Explicit Android SDK root, used when auto-discovery (ANDROID_HOME / the
-   *  default install path) does not find it. `null` (default) auto-discovers. */
+  /** Explicit Android SDK root for when auto-discovery (ANDROID_HOME / default path) fails; null (default) auto-discovers. */
   androidSdkPath?: string | null
-  /** Auto-restore window for a phone-fit PTY after the last mobile
-   *  subscriber leaves. `null` (default) holds the PTY at phone size
-   *  indefinitely; the desktop "Restore" banner remains the explicit
-   *  return-to-desktop-size action. A finite millisecond value schedules
-   *  an automatic restore that long after the last unsubscribe. Clamped
-   *  on read into [5_000ms, 60min] to defend against bad config.
-   *  See docs/mobile-fit-hold.md. */
+  /** Auto-restore window (ms) for a phone-fit PTY after the last mobile subscriber leaves.
+   *  `null` (default) holds phone size indefinitely; a finite value schedules restore.
+   *  Clamped on read to [5_000ms, 60min]. See docs/mobile-fit-hold.md. */
   mobileAutoRestoreFitMs: number | null
-  /** Preferred mobile pairing path for new QR codes: Anywhere (Orca Relay +
-   *  local) or same-network only. Missing/undefined defaults to Anywhere.
-   *  An explicit `local-only` means the user already chose that path. */
+  /** Preferred mobile pairing path for new QR codes. Missing/'automatic' = Anywhere (Relay + local);
+   *  explicit 'local-only' = same-network only. */
   mobilePairingConnectionMode?: 'automatic' | 'local-only'
-  /** Experimental: floating animated pet (claude.webp) in the bottom-right
-   *  corner. Opt-in because it's a cosmetic joke feature; users who leave it
-   *  off never mount the overlay. Toggling takes effect immediately in the
-   *  current session (no relaunch) because it is purely renderer-side. */
+  /** Experimental: floating animated pet in the bottom-right corner. Opt-in cosmetic;
+   *  off never mounts the overlay, and toggling takes effect instantly (renderer-side). */
   experimentalPet: boolean
-  /** Legacy persisted key from before the sidekick -> pet rename. Read only
-   *  during migration; new writes use experimentalPet. */
+  /** Legacy persisted key from before the sidekick -> pet rename; read only during migration, new writes use experimentalPet. */
   experimentalSidekick?: boolean
-  /** Experimental: left-sidebar Agents view with a threaded feed for agent
-   *  completions, blocking states, unread state, and worktree creation events. */
+  /** Experimental: left-sidebar Agents view — threaded feed of agent completions, blocking/unread state, worktree creation. */
   experimentalActivity: boolean
-  /** One-shot migration guard for defaulting the Agents view off for all
-   *  users. Once set, later explicit opt-ins persist normally. */
+  /** One-shot migration guard for defaulting the Agents view off; later explicit opt-ins persist normally. */
   experimentalActivityDefaultedOffForAllUsers?: boolean
-  /** Experimental: persistent terminal pane attention ring for terminal bell
-   *  and agent-completion events. Opt-in while the signal/noise balance is
-   *  being tested. */
+  /** Experimental: persistent terminal-pane attention ring for bell + agent-completion events. Opt-in while tuning signal/noise. */
   experimentalTerminalAttention: boolean
   /** Experimental: automatically sleep completed, resumable background agent terminals. */
   experimentalAgentHibernation?: boolean
@@ -3006,68 +2868,35 @@ export type GlobalSettings = {
   experimentalNewWorktreeCardStyle?: boolean
   /** Experimental: per-workspace on-demand environment recipes and setup surface. */
   experimentalEphemeralVms?: boolean
-  /** Compact worktree cards by hiding a redundant metadata row when the title
-   *  and branch already say the same thing. */
+  /** Compact worktree cards: hide the metadata row when title and branch say the same thing. */
   compactWorktreeCards: boolean
-  /** Legacy persisted key from the Experimental rollout. New writes use
-   *  compactWorktreeCards. */
+  /** Legacy persisted key from the Experimental rollout; new writes use compactWorktreeCards. */
   experimentalCompactWorktreeCards?: boolean
-  /** Active non-local runtime environment for client-routed RPC. `null`
-   *  preserves the current local desktop behavior. */
+  /** Active non-local runtime environment for client-routed RPC; null keeps local desktop behavior. */
   activeRuntimeEnvironmentId?: string | null
-  /** GitHub Project mode state — pinned/recent/active project, last selected
-   *  view per project. Optional because profiles created before this feature
-   *  landed won't have the key; `getDefaultSettings()` hydrates the empty
-   *  default via the persistence merge. */
+  /** GitHub Project mode state (pinned/recent/active project, last view per project).
+   *  Optional for pre-feature profiles; the persistence merge hydrates the default. */
   githubProjects?: GitHubProjectSettings
-  /** AI-generated commit messages: agent + model + per-model thinking +
-   *  user-customizable prompt suffix. Optional so existing profiles do not
-   *  require a migration step before this feature lands. */
+  /** AI commit-message config (agent, model, per-model thinking, prompt suffix). Optional to avoid migrating existing profiles. */
   commitMessageAi?: CommitMessageAiSettings
   /** Source-control AI generation settings for commit messages and hosted-review drafts. */
   sourceControlAi?: SourceControlAiSettings
-  /** GitLab project preferences — pinned + recent project paths.
-   *  Optional for backward compatibility with profiles saved before
-   *  GitLab support; the persistence merge fills the empty default. */
+  /** GitLab project preferences (pinned + recent paths). Optional for pre-GitLab profiles; persistence merge fills the default. */
   gitlabProjects?: GitLabProjectSettings
-  /** Anonymous product-telemetry state. Optional because the one-shot
-   *  migration in `Store.load()` is what populates it on first boot of the
-   *  telemetry release; before migration runs, the field is absent. After
-   *  migration every user has `installId` set and `optedIn` is `true` (new
-   *  users) or `null` (existing users awaiting the first-launch banner).
-   *
-   *  Why this block carries only consent + identity state, not volatile
-   *  counters: DAU and crash attribution are both out of v1 scope
-   *  (daily_active_user is derived server-side from app_opened; crashes are
-   *  handled by a separate crash-reporting lane, not product telemetry). So
-   *  there is no lastActiveDate, no lastSessionId, and no heartbeat
-   *  timestamp here — adding any of those would amplify the debounced
-   *  settings write on a fast cadence and couple user preferences to
-   *  volatile telemetry counters. Keep this surface to values that only
-   *  change on explicit consent transitions. */
+  /** Anonymous product-telemetry state; optional until the one-shot Store.load() migration populates it.
+   *  Holds only consent + identity, not volatile counters — those would amplify the debounced settings write. */
   telemetry?: {
-    /** New users: initialized to `true` at install.
-     *  Existing users: `null` until they resolve the first-launch banner. */
+    /** New users: true at install. Existing users: null until they resolve the first-launch banner. */
     optedIn: boolean | null
     /** Anonymous UUID v4. Generated on first run. Stable across launches; not surfaced in the UI. */
     installId: string
-    /** Cohort marker set once during migration. True for users with a
-     *  pre-existing profile (gates the existing-user opt-in banner);
-     *  false for fresh installs (no first-launch surface). */
+    /** Cohort marker: true for pre-existing profiles (gates the opt-in banner), false for fresh installs. */
     existedBeforeTelemetryRelease: boolean
   }
-  /** One-shot cohort marker for the tab-switch keybinding convention swap.
-   *  Absent before the migration runs. Set once on first boot after the swap:
-   *  `'pending'` for pre-existing installs (a seed then pins the old chords in
-   *  keybindings.json before flipping this to `'done'`), or `'done'` for fresh
-   *  installs, which adopt the new registry defaults with no seed. */
+  /** One-shot cohort marker for the tab-switch keybinding swap. 'pending' =
+   *  pre-existing install (seed pins old chords, then flips to 'done'); 'done' = fresh install. */
   tabSwitchKeybindingSeed?: 'pending' | 'done'
-  /** Local voice/dictation configuration (Phase 1 voice feature). Optional
-   *  because profiles created before voice landed won't have the key;
-   *  `getDefaultSettings()` hydrates `getDefaultVoiceSettings()` via the
-   *  `{ ...defaults, ...parsed }` merge in persistence.ts. Treat as
-   *  effectively present at runtime — the renderer should still fall back to
-   *  defaults when reading optional sub-fields. */
+  /** Local voice/dictation config. Optional for pre-voice profiles; getDefaultSettings() hydrates defaults via the persistence merge. */
   voice?: VoiceSettings
 }
 
@@ -3101,9 +2930,7 @@ export type CommitMessageAiSettings = {
   selectedThinkingByModel: Record<string, string>
   /** Optional user-provided suffix appended to the base prompt (style overrides, etc.). */
   customPrompt: string
-  /** Command template used when `agentId === 'custom'`. Tokenized POSIX-style;
-   *  `{prompt}` is substituted with the diff prompt (argv delivery). When the
-   *  template has no `{prompt}`, the prompt is piped via stdin. */
+  /** Command template for agentId === 'custom'; {prompt} substitutes the diff prompt via argv, else the prompt is piped via stdin. */
   customAgentCommand: string
 }
 
@@ -3116,12 +2943,7 @@ export type GhosttyImportPreview = {
   error?: string
 }
 
-// Subset of the renderer's onboarding-step Ghostty `DiscoveryState['status']`
-// values that ever ship a telemetry event. The UI-only states (`'idle'`,
-// `'detecting'`) never fire `onboarding_ghostty_discovered`. Lives in
-// `shared/` because the schema in `telemetry-events.ts` (node-tsconfig) and
-// `ThemeStep.tsx` (web-tsconfig) both need it for the compile-time
-// schema-vs-renderer enum sync guard.
+// Subset of onboarding Ghostty DiscoveryState statuses that emit telemetry; UI-only 'idle'/'detecting' don't.
 export type DiscoveryStatusEmitted = 'found' | 'absent' | 'imported'
 
 export type NotificationEventSource = 'agent-task-complete' | 'terminal-bell' | 'test'
@@ -3150,9 +2972,7 @@ export type NotificationDispatchRequest = {
 
 export type NotificationDispatchResult = {
   delivered: boolean
-  /** Present when delivered is false. Tells the caller why delivery was skipped.
-   *  'blocked-by-system' means the OS-level permission readout says macOS
-   *  would silently swallow the notification (denied or prompt unanswered). */
+  /** Why delivery was skipped (set when delivered is false); 'blocked-by-system' = macOS would silently swallow it. */
   reason?:
     | 'disabled'
     | 'source-disabled'
@@ -3209,20 +3029,16 @@ export type OnboardingChecklistState = {
   addedFolder: boolean
   openedFile: boolean
   ranAgentOnFile: boolean
-  // Why: UI state flag (panel visibility), not an activation event. The
-  // telemetry checklist enum in telemetry-events.ts intentionally omits this.
+  // Why: UI state flag (panel visibility), not an activation event; telemetry checklist enum omits it.
   dismissed: boolean
 }
 
 export type OnboardingState = {
-  // Why: numeric step meanings can change when pages are removed; persisted
-  // state needs a version marker so migration does not re-run on new progress.
+  // Why: step meanings change when pages are removed; version marker prevents migration re-running on new progress.
   flowVersion: number
   closedAt: number | null
   outcome: OnboardingOutcome | null
-  // Sentinel `-1` = not started; `1..5` = highest wizard step the user
-  // finished. Kept as `number` (not a literal union) because callers clamp
-  // via `Math.max`/`Math.min` against arbitrary numerics.
+  // Sentinel -1 = not started; 1..5 = highest finished wizard step. number (not union) because callers clamp via Math.max/min.
   lastCompletedStep: number
   checklist: OnboardingChecklistState
 }
@@ -3233,15 +3049,11 @@ export type NotificationPermissionStatusResult = {
   requested: boolean
 }
 
-/** Outcome of a macOS notification permission check. Preferred source is the
- *  bundled native helper reading UNUserNotificationCenter authorization
- *  (authoritative); when unavailable, a silent delivery probe supplies weaker
- *  scheduling-based evidence. 'awaiting-decision' means the macOS permission
- *  dialog has not been answered yet. */
+/** macOS notification permission outcome: authoritative native UNUserNotificationCenter readout, else a weaker
+ *  delivery-probe fallback; 'awaiting-decision' = permission dialog unanswered. */
 export type NotificationDeliveryProbeResult = {
   state: 'delivered' | 'blocked' | 'awaiting-decision' | 'unsupported'
-  /** True when the state comes from the native authorization readout. Silent
-   *  to poll; probe-based fallbacks flash a banner when delivery works. */
+  /** True when the state comes from the native authorization readout (vs. the delivery-probe fallback). */
   authoritative: boolean
 }
 
@@ -3250,21 +3062,16 @@ export type WorktreeCardProperty =
   | 'unread'
   // Legacy persisted preference. CI status is now represented by linked PR metadata.
   | 'ci'
-  // Internal migration-only property for legacy detailed cards that showed
-  // branch identity as a visible row.
+  // Migration-only: legacy detailed cards showed branch identity as a visible row.
   | 'branch'
-  // Task metadata shown on workspace cards. Kept as provider-specific
-  // persisted values so older profiles and provider-specific fetch paths work.
+  // Task metadata on workspace cards; provider-specific persisted values kept for older profiles.
   | 'issue'
   | 'linear-issue'
   | 'pr'
   | 'automation'
   | 'comment'
   | 'ports'
-  // Why: inline list of agent activity rendered directly inside each
-  // workspace card when the experimental agent-activity feature is on. On by
-  // default (see DEFAULT_WORKTREE_CARD_PROPERTIES in shared/constants.ts) —
-  // live agent activity is the primary reason users opt into the feature.
+  // Inline agent-activity list rendered in each workspace card; on by default (see DEFAULT_WORKTREE_CARD_PROPERTIES in shared/constants.ts).
   | 'inline-agents'
 
 export type WorktreeCardMode = 'Default' | 'Compact'
@@ -3338,10 +3145,7 @@ export type TopLevelView =
 export type PersistedUIState = {
   lastActiveRepoId: string | null
   lastActiveWorktreeId: string | null
-  /** Active top-level view at save time, restored on reload/relaunch so the app
-   *  reopens where the user left off instead of snapping back to the terminal.
-   *  Sanitized on hydration (unknown value or a now-gated view falls back to
-   *  'terminal'). */
+  /** Active top-level view at save time, restored on relaunch; sanitized to 'terminal' if unknown or now-gated. */
   activeView: TopLevelView
   sidebarWidth: number
   rightSidebarOpen: boolean
@@ -3351,36 +3155,25 @@ export type PersistedUIState = {
   markdownTocPanelWidth?: number
   groupBy: 'none' | 'workspace-status' | 'repo' | 'pr-status'
   sortBy: 'name' | 'smart' | 'recent' | 'repo' | 'manual'
-  /** Project header ordering in `groupBy: 'repo'`, independent of workspace
-   *  `sortBy`. 'manual' (default) uses the persisted repo order and enables
-   *  header drag; 'recent' orders by each project's most recent visible
-   *  workspace activity. */
+  /** Project header ordering in `groupBy: 'repo'`, independent of `sortBy`: 'manual' uses persisted order + header drag, 'recent' by latest visible activity. */
   projectOrderBy: ProjectOrderBy
   /** Deprecated; the Active only filter is retired and ignored on hydration. */
   showActiveOnly: boolean
   /** Hide sleeping/inactive workspaces from workspace navigation. Off by default. */
   hideSleepingWorkspaces?: boolean
-  /** Which execution hosts the workspace sidebar shows. `all` keeps the mixed
-   *  command-center view; specific host IDs focus the sidebar without tearing
-   *  down sessions owned by other hosts. */
+  /** Which execution hosts the sidebar shows; `all` = mixed view, specific IDs focus without tearing down other hosts' sessions. */
   workspaceHostScope?: WorkspaceHostScope
-  /** Which execution hosts the workspace sidebar shows. `null` means sticky
-   *  all-hosts so newly-added hosts appear automatically. */
+  /** Which execution hosts the sidebar shows; `null` = sticky all-hosts so new hosts appear automatically. */
   visibleWorkspaceHostIds?: VisibleWorkspaceHostIds
-  /** User-defined sidebar order for host sections. Missing/new hosts append in
-   *  the discovered host order. */
+  /** User-defined sidebar order for host sections; missing/new hosts append in discovered order. */
   workspaceHostOrder?: WorkspaceHostOrder
-  /** Desktop-owned all-host repo order. Host-qualified identities preserve a
-   *  manual cross-host interleaving while each host owns its local permutation. */
+  /** Desktop-owned all-host repo order; host-qualified identities keep a manual cross-host interleaving while each host owns its local permutation. */
   manualRepoOrder?: ManualRepoOrderEntry[]
   /** Deprecated legacy positive-form setting. Ignored on hydration. */
   showSleepingWorkspaces?: boolean
   /** Deprecated legacy name used by a short-lived build. Ignored on hydration. */
   showInactiveWorkspaces?: boolean
-  /** Hide the repo's original checked-out branch from workspace navigation
-   *  (sidebar and Cmd+J jump palette). Folder-mode repos are unaffected —
-   *  the predicate in visible-worktrees.ts excludes worktrees with an empty
-   *  branch. */
+  /** Hide the repo's checked-out branch from workspace nav (sidebar, Cmd+J); folder-mode repos are unaffected (empty-branch worktrees excluded). */
   hideDefaultBranchWorkspace: boolean
   /** Hide workspaces created by automation new-per-run dispatches. */
   hideAutomationGeneratedWorkspaces?: boolean
@@ -3391,26 +3184,20 @@ export type PersistedUIState = {
   uiZoomLevel: number
   editorFontZoomLevel: number
   worktreeCardProperties: WorktreeCardProperty[]
-  /** One-shot migration flag for deriving card properties from the two
-   *  user-facing worktree card modes. */
+  /** One-shot migration flag for deriving card properties from the two worktree card modes. */
   _worktreeCardModeDefaulted?: boolean
   agentActivityDisplayMode?: AgentActivityDisplayMode
   workspaceStatuses?: WorkspaceStatusDefinition[]
   workspaceBoardOpacity?: number
   workspaceBoardColumnWidth?: number
   syncTaskStatusFromWorkspaceBoard?: boolean
-  /** One-shot migration flag for a short-lived build that persisted the
-   *  default workspace statuses in reverse workflow order. Once stamped,
-   *  user-authored status ordering is never inferred from IDs/labels again. */
+  /** One-shot migration flag for a short-lived build that persisted default statuses in reverse order; once stamped, ordering is never re-inferred from IDs/labels. */
   _workspaceStatusesDefaultOrderMigrated?: boolean
-  /** One-shot repair flag for the exact default payload that a short-lived
-   *  build persisted in reverse workflow order. */
+  /** One-shot repair flag for the exact default payload a short-lived build persisted in reverse workflow order. */
   _workspaceStatusesReorderedDefaultRepaired?: boolean
-  /** One-shot migration flag for default status workflow labels/visuals.
-   *  Exact legacy default payloads migrate; customized statuses are preserved. */
+  /** One-shot migration flag for default status workflow labels/visuals; only exact legacy defaults migrate, customized statuses preserved. */
   _workspaceStatusesDefaultWorkflowMigrated?: boolean
-  /** One-shot migration flag for the old default blue/violet/emerald status
-   *  visuals. Once stamped, valid user-authored colors/icons are preserved. */
+  /** One-shot migration flag for the old default status visuals; once stamped, user-authored colors/icons are preserved. */
   _workspaceStatusesDefaultVisualsMigrated?: boolean
   /** One-shot migration flag for adding the default-on Ports status item. */
   _portsStatusBarDefaultAdded?: boolean
@@ -3430,157 +3217,88 @@ export type PersistedUIState = {
   lastUpdateCheckAt: number | null
   pendingUpdateNudgeId?: string | null
   dismissedUpdateNudgeId?: string | null
-  /** Whether Orca has already attempted to trigger the macOS notification
-   *  permission dialog via a startup notification. Prevents re-firing on
-   *  every launch. */
+  /** Whether Orca already tried triggering the macOS notification permission dialog; prevents re-firing every launch. */
   notificationPermissionRequested?: boolean
-  /** Once the user has seen the "your sessions won't be interrupted"
-   *  reassurance card, we never show it again. */
+  /** Once the "your sessions won't be interrupted" reassurance card is seen, never show it again. */
   updateReassuranceSeen?: boolean
-  /** Per-paneKey "user has visited this row" timestamps, used by the inline
-   *  agents list to mute rows the user has already seen. Persisted because
-   *  agent rows themselves now survive restart; without persisting acks too,
-   *  rows you'd already clicked come back bold on relaunch. Stale entries
-   *  keyed on dead panes are inert: a future paneKey reuse stamps a fresh
-   *  stateStartedAt that beats the old ack via the existing comparison in
-   *  WorktreeCardAgents. Renderer-owned, written through ui:set. */
+  /** Per-paneKey "row visited" timestamps that mute seen inline-agent rows; persisted because rows survive restart, else acked rows return bold. Renderer-owned via ui:set. */
   acknowledgedAgentsByPaneKey?: Record<string, number>
-  /** User-hidden sidebar entry for the setup guide. The Help menu remains
-   *  available so this is a reversible declutter preference, not completion. */
+  /** User-hidden setup-guide sidebar entry; a reversible declutter pref (Help menu stays available), not completion. */
   setupGuideSidebarDismissed?: boolean
-  /** One-shot migration marker for the browser setup-guide milestone. Existing
-   *  profiles missing this marker are evaluated once in the renderer because
-   *  full checklist completion depends on runtime probes. */
+  /** One-shot marker for the browser setup-guide milestone; profiles missing it are evaluated once in the renderer (completion needs runtime probes). */
   setupGuideBrowserMilestoneMigrated?: boolean
-  /** Existing users who completed or dismissed the pre-browser checklist stay
-   *  complete after the browser milestone is added. */
+  /** Existing users who completed/dismissed the pre-browser checklist stay complete after the browser milestone is added. */
   setupGuideBrowserMilestoneLegacyComplete?: boolean
-  /** User-dismissed browser import hint in the browser toolbar. Import remains
-   *  available from Settings > Browser and the toolbar overflow menu. */
+  /** User-dismissed browser import toolbar hint; import stays available from Settings > Browser and the overflow menu. */
   browserImportHintHidden?: boolean
-  /** Why: Windows-only. Set once after the window first hides to the system
-   *  tray, so the "Orca is still running" notification shows only on first use. */
+  /** Why: Windows-only. Set once on first hide to tray so the "Orca is still running" notice shows only once. */
   trayMinimizeNoticeShown?: boolean
-  /** User dismissed the first-run Mobile Emulator intro (Keep, Hide, or close).
-   *  Reversible only by re-enabling the feature in Settings. */
+  /** User dismissed the first-run Mobile Emulator intro; reversible only by re-enabling the feature in Settings. */
   mobileEmulatorTabIntroDismissed?: boolean
   /** User deferred the in-pane Mobile Emulator CLI + skill setup guide. */
   mobileEmulatorAgentSetupDismissed?: boolean
-  /** One-shot rollout notice for manual project ordering becoming the default.
-   *  Absent or true means the sidebar callout stays hidden. */
+  /** One-shot rollout notice for manual project ordering default; absent or true keeps the sidebar callout hidden. */
   projectOrderManualDefaultNoticeDismissed?: boolean
-  /** One-shot notice that status-bar usage meters now show percent used (not
-   *  remaining). Absent is resolved on load: brand-new profiles default to
-   *  dismissed; upgraded profiles see the notice once. */
+  /** One-shot notice that usage meters show percent used, not remaining; absent resolves on load (new profiles dismissed, upgraded see it once). */
   usagePercentageDisplayChangeNoticeDismissed?: boolean
-  /** User-hidden empty-state usage CTA in the status bar. Permanently hides the
-   *  "Connect AI accounts to see usage" prompt even if all providers are later
-   *  disconnected — a dismissed teaching nudge stays dismissed. */
+  /** User-hidden empty-state usage CTA; permanently hides the "Connect AI accounts" prompt even if providers are later disconnected. */
   usageEmptyStateDismissed?: boolean
-  /** URL to navigate to when a new browser tab is opened. Null means blank tab.
-   *  Phase 3 will expand this to a full BrowserSessionProfile per workspace. */
+  /** URL for new browser tabs; null = blank tab. */
   browserDefaultUrl?: string | null
   browserDefaultSearchEngine?: 'google' | 'duckduckgo' | 'bing' | 'kagi' | null
   /** Electron browser zoom level applied when a new local browser tab is created. */
   browserDefaultZoomLevel?: number
   /** Optional Kagi private-session link used only when Kagi is the search engine. */
   browserKagiSessionLink?: string | null
-  /** Saved window bounds so the app restores to the user's last position/size
-   *  instead of maximizing on every launch. */
+  /** Saved window bounds so the app restores last position/size instead of maximizing each launch. */
   windowBounds?: { x: number; y: number; width: number; height: number } | null
   /** Whether the window was maximized when it was last closed. */
   windowMaximized?: boolean
-  /** One-shot migration flag: 'recent' used to mean the weighted smart sort
-   *  (v1→v2 rename). When this flag is absent and sortBy is 'recent', the
-   *  main-process load() migrates it to 'smart' and sets this flag so the
-   *  migration never re-fires — allowing users to intentionally select the
-   *  new 'recent' (last-activity) sort without it being clobbered on restart. */
+  /** One-shot flag: 'recent' once meant the smart sort (v1→v2 rename), migrated to 'smart' once so the new last-activity 'recent' isn't re-clobbered. */
   _sortBySmartMigrated?: boolean
-  /** LEGACY one-shot flag from the experimental-toggle era of the inline
-   *  agents feature. It was stamped unconditionally on every successful
-   *  load() in prior builds (regardless of whether the experiment was on),
-   *  so it cannot be used to detect "already migrated under the new
-   *  default-on rules" — every prior-RC user already has it set to true on
-   *  disk. Kept persisted for forward-compat with rollback to a pre-default-on
-   *  build that still reads it; the actual migration gate is now
-   *  `_inlineAgentsDefaultedForAllUsers` below. */
+  /** LEGACY inline-agents flag, stamped unconditionally every load so it can't gate migration; kept only for rollback forward-compat (real gate: _inlineAgentsDefaultedForAllUsers). */
   _inlineAgentsDefaultedForExperiment?: boolean
-  /** One-shot migration flag for the default-on rollout of the inline
-   *  agents feature. Set once on first load after upgrade once the
-   *  'inline-agents' card property has been ensured in
-   *  `worktreeCardProperties`. Distinct from
-   *  `_inlineAgentsDefaultedForExperiment` because that legacy flag was
-   *  stamped on every prior load and so is permanently dirty for the
-   *  prior-RC opt-out cohort the widened migration is meant to reach. */
+  /** One-shot flag for the inline-agents default-on rollout; distinct from _inlineAgentsDefaultedForExperiment, which was stamped every load and is permanently dirty. */
   _inlineAgentsDefaultedForAllUsers?: boolean
-  /** One-shot migration flag for card properties that were split out after
-   *  the original metadata toggles shipped. Set once so later deliberate
-   *  unchecks of Linear issue and Ports stick across restarts. */
+  /** One-shot migration flag for split-out card properties, set once so later deliberate unchecks of Linear issue/Ports stick across restarts. */
   _expandedWorktreeCardPropertiesDefaulted?: boolean
-  /** Snapshot of totalAgentsSpawned captured the first time we see the current
-   *  app version. Why: the nag threshold counts agents spawned *since the
-   *  user's last update* so a fresh install or new release does not trigger
-   *  the notification immediately. Reset whenever starNagAppVersion changes. */
+  /** totalAgentsSpawned snapshot at first sighting of the current app version, so the nag counts agents since last update (not from zero). */
   starNagBaselineAgents?: number | null
-  /** The app version that set the current baseline. When the live app version
-   *  differs from this value, the baseline is re-captured on next agent
-   *  spawn — effectively restarting the nag countdown after each update. */
+  /** App version that set the current baseline; a version change re-captures the baseline on next spawn, restarting the nag countdown. */
   starNagAppVersion?: string | null
-  /** Next threshold (agents spawned since baseline) at which the star-nag
-   *  notification should fire. Starts at 35 and doubles each time the user
-   *  dismisses the notification without starring. */
+  /** Next agents-since-baseline threshold that fires the star-nag; starts at 35, doubles per dismissal without starring. */
   starNagNextThreshold?: number
-  /** Once the user has starred Orca (from any entry point) we permanently
-   *  suppress the nag — no further thresholds, no notifications. */
+  /** Once the user has starred Orca (any entry point), permanently suppress the nag. */
   starNagCompleted?: boolean
-  /** Timestamp until which nonterminal dismissals suppress threshold prompts.
-   *  Force-show bypasses this for dev/testing. */
+  /** Timestamp until which nonterminal dismissals suppress threshold prompts (force-show bypasses for dev/testing). */
   starNagDeferredUntil?: number | null
-  /** App version that already consumed the first successful-agent value-moment ask.
-   *  Main-owned so remote/web clients cannot spoof the once-per-version cap. */
+  /** App version that consumed the first value-moment ask; main-owned so remote/web clients can't spoof the once-per-version cap. */
   starNagAgentValueMomentAppVersion?: string | null
   trustedOrcaHooks?: PersistedTrustedOrcaHooks
   setupScriptPromptDismissedRepoIds?: string[]
-  /** Whether the experimental pet overlay is currently visible. Separate
-   *  from the experimentalPet settings flag so "Hide pet" from the
-   *  status-bar menu is a reversible dismiss (re-show without re-enabling the
-   *  feature). Absent = treated as true so existing users see the pet
-   *  the first time they enable the experimental flag. */
+  /** Pet overlay visibility, separate from the experimentalPet settings flag so "Hide pet" is a reversible dismiss; absent = true. */
   petVisible?: boolean
-  /** Active pet id: one of the bundled ids or a custom UUID from
-   *  customPets. Unknown ids fall back to the default at read time so
-   *  removing a custom pet the user had selected doesn't leave the
-   *  overlay rendering nothing. */
+  /** Active pet id (bundled id or custom UUID); unknown ids fall back to the default on read so a removed custom pet doesn't blank the overlay. */
   petId?: string
-  /** User-uploaded pet images. Bytes live under the legacy
-   *  userData/sidekicks/custom/ folder; this field is the metadata index so
-   *  custom pets ride the existing PersistedUIState save pipeline. */
+  /** Metadata index for user-uploaded pet images; bytes live under legacy userData/sidekicks/custom/. */
   customPets?: CustomPet[]
-  /** On-screen size of the pet overlay in CSS pixels (square box).
-   *  Clamped to [PET_SIZE_MIN, PET_SIZE_MAX] when read. */
+  /** Pet overlay size in CSS pixels (square); clamped to [PET_SIZE_MIN, PET_SIZE_MAX] on read. */
   petSize?: number
-  /** Legacy persisted keys from before the sidekick -> pet rename. Read only
-   *  during migration; new writes use the pet* names above. */
+  /** Legacy keys from before the sidekick -> pet rename; read only during migration, new writes use pet* above. */
   sidekickVisible?: boolean
   sidekickId?: string
   customSidekicks?: CustomPet[]
   sidekickSize?: number
-  /** Page-position state for Tasks. Source/repo/team/project selections keep
-   *  using their existing settings paths; this only restores transient tabs
-   *  and applied searches. */
+  /** Page-position state for Tasks: only transient tabs/searches (source/repo/team/project selections use their own settings paths). */
   taskResumeState?: TaskResumeState
   workspaceCleanup?: WorkspaceCleanupUIState
-  /** Feature tips already surfaced to the user. Startup only opens the tips
-   *  modal when this list is missing one of the current tip ids. */
+  /** Feature tips already surfaced; startup opens the tips modal only when a current tip id is missing here. */
   featureTipsSeenIds?: FeatureTipId[]
-  /** Local product-state facts: feature ids the user has actually used.
-   *  Used by education surfaces to avoid teaching already-discovered features. */
+  /** Feature ids the user has actually used; education surfaces skip teaching already-discovered features. */
   featureInteractions?: FeatureInteractionState
-  /** Contextual tours already surfaced to the user. Unknown ids are ignored
-   *  during hydration so downgrade/upgrade cycles remain forward-compatible. */
+  /** Contextual tours already surfaced; unknown ids ignored on hydration for downgrade/upgrade forward-compat. */
   contextualToursSeenIds?: ContextualTourId[]
-  /** Whether this profile may receive automatic contextual tours from this
-   *  rollout. Missing means the renderer has not classified the profile yet. */
+  /** Whether this profile may receive automatic contextual tours; missing = renderer hasn't classified the profile yet. */
   contextualToursAutoEligible?: boolean
 }
 
@@ -3588,26 +3306,16 @@ export const PET_SIZE_MIN = 60
 export const PET_SIZE_MAX = 360
 export const PET_SIZE_DEFAULT = 180
 
-/** Metadata for a user-uploaded pet image. `id` is the stable identifier;
- *  the on-disk filename (preserving the original extension) lives in `fileName`.
- *  The renderer never learns the absolute path — it asks main for the bytes
- *  via pet:read using (id, fileName). */
+/** User-uploaded pet image metadata; renderer fetches bytes from main via pet:read (id, fileName), never learning the on-disk path. */
 export type CustomPet = {
   id: string
   label: string
   fileName: string
-  /** MIME type needed so the renderer builds a Blob with the correct
-   *  Content-Type — especially image/svg+xml, which browsers won't render
-   *  from a misdeclared blob URL. */
+  /** MIME type for the renderer's Blob Content-Type — esp. image/svg+xml, which browsers won't render from a misdeclared blob URL. */
   mimeType: string
-  /** Storage layout. `image` = legacy flat file at `custom/<id>.<ext>`.
-   *  `bundle` = `.codex-pet` import expanded into `custom/<id>/`. Absent =
-   *  legacy `image` for backwards compatibility with persisted state. */
+  /** Storage layout: `image` = legacy flat file `custom/<id>.<ext>`; `bundle` = `.codex-pet` expanded into `custom/<id>/`; absent = legacy `image`. */
   kind?: 'image' | 'bundle'
-  /** Sprite-sheet metadata captured at import time. Present iff this entry
-   *  came from a `.codex-pet` bundle and the manifest declared frame layout.
-   *  `columns`/`rows`/`sheetWidth`/`sheetHeight` are derived in main from
-   *  the decoded sheet so the renderer doesn't need to probe the image. */
+  /** Sprite-sheet metadata; present iff from a `.codex-pet` bundle with a manifest frame layout. Dims derived in main so the renderer needn't probe the image. */
   sprite?: {
     frameWidth: number
     frameHeight: number
@@ -3619,14 +3327,11 @@ export type CustomPet = {
     defaultAnimation?: string
     animations?: Record<string, SpriteAnimation>
   }
-  /** Manifest-declared fps captured even when the manifest omits `frame` and
-   *  the renderer falls back to auto-detected frames. Lets DetectedSpriteFrame
-   *  honor the bundle's intended playback speed instead of a hardcoded 8 fps. */
+  /** Manifest-declared fps kept even when frames are auto-detected, so playback honors the bundle's speed instead of a hardcoded 8 fps. */
   spriteFps?: number
 }
 
-/** One animation strip within a sprite sheet: `row` is the y-index (0-based)
- *  and `frames` is the number of consecutive cells played left-to-right. */
+/** One animation strip in a sprite sheet: `row` = 0-based y-index, `frames` = consecutive cells played left-to-right. */
 export type SpriteAnimation = {
   row: number
   frames: number
@@ -3653,8 +3358,7 @@ export type PersistedTrustedOrcaHooks = Record<string, PersistedTrustedOrcaHookR
 
 export type LegacyPaneKeyAliasEntry = {
   ptyId: string
-  /** Physical pane key retained by the live process. Field name is persisted
-   *  for compatibility; UUID keys are used after pane-to-tab detach. */
+  /** Physical pane key retained by the live process; name is persisted for compatibility (UUID keys after detach). */
   legacyPaneKey: string
   /** Current logical owner pane key. May belong to another tab after detach. */
   stablePaneKey: string
@@ -3669,8 +3373,7 @@ export type PersistedState = {
   projectHostSetups: ProjectHostSetup[]
   projectGroups: ProjectGroup[]
   folderWorkspaces: FolderWorkspace[]
-  /** Sparse-checkout presets keyed by repoId. Empty record on first launch;
-   *  presets are managed from the new-workspace composer and repo settings. */
+  /** Sparse-checkout presets keyed by repoId. */
   sparsePresetsByRepo: Record<string, SparsePreset[]>
   worktreeMeta: Record<string, WorktreeMeta>
   worktreeLineageById: Record<string, WorktreeLineage>
@@ -3681,26 +3384,17 @@ export type PersistedState = {
     pr: Record<string, { data: PRInfo | null; fetchedAt: number }>
     issue: Record<string, { data: IssueInfo | null; fetchedAt: number }>
   }
-  /** Legacy single-blob session. Retained as the canonical 'local' execution
-   *  host partition so an app downgrade still reads its workspace. Non-local
-   *  hosts live in workspaceSessionsByHostId, keyed by ExecutionHostId. */
+  /** Legacy single-blob session, kept as the canonical 'local' host partition so an app downgrade still reads its workspace. */
   workspaceSession: WorkspaceSessionState
-  /** Per-execution-host session partitions for non-'local' hosts (ssh:/runtime:).
-   *  Mixed-host writes stay isolated here; 'local' stays in workspaceSession so
-   *  pre-partition builds keep working. Optional/absent on legacy files. */
+  /** Per-execution-host session partitions for non-'local' hosts (ssh:/runtime:); 'local' stays in workspaceSession so pre-partition builds keep working. */
   workspaceSessionsByHostId?: Partial<Record<ExecutionHostId, WorkspaceSessionState>>
   sshTargets: SshTarget[]
-  /** SSH config aliases the user explicitly deleted. Suppresses re-import of the
-   *  matching ~/.ssh/config host on the next sync so a deleted host does not
-   *  reappear. Cleared for an alias when the user re-adds it or re-adopts config. */
+  /** SSH config aliases the user deleted; suppresses re-import from ~/.ssh/config so a deleted host doesn't reappear. */
   deletedSshConfigAliases: string[]
-  /** Identity records for removed SSH targets. Lets a re-added host re-adopt
-   *  workspaces that were orphaned on the old target id. Pruned by age/count. */
+  /** Identity records for removed SSH targets so a re-added host can re-adopt workspaces orphaned on the old target id. */
   removedSshTargetTombstones?: RemovedSshTargetTombstone[]
   sshRemotePtyLeases: SshRemotePtyLease[]
-  /** Daemon session ids of live local Claude launches. Seeds the Claude
-   *  live-PTY gate on startup so an early OAuth refresh cannot rotate the
-   *  single-use refresh token out from under a still-running daemon CLI. */
+  /** Live local Claude daemon session ids; seeds the live-PTY gate so early OAuth refresh can't rotate the single-use refresh token out from under a running daemon. */
   claudeLivePtySessionIds?: string[]
   migrationUnsupportedPtyEntries: MigrationUnsupportedPtyEntry[]
   legacyPaneKeyAliasEntries: LegacyPaneKeyAliasEntry[]
@@ -3739,8 +3433,7 @@ export type FsChangedPayload = {
 }
 
 // ─── Git Status ─────────────────────────────────────────────
-// Re-exported from git-status-types.ts so mobile can share the runtime git
-// wire contract without importing this desktop-oriented aggregate type module.
+// Re-exported from git-status-types.ts so mobile shares the wire contract without this desktop aggregate.
 
 export type GitBranchChangeEntry = {
   path: string
@@ -3799,12 +3492,7 @@ export type GitDiffBinaryResult = {
   isImage?: boolean
   /** MIME type for binary preview rendering, e.g. "image/png" or "application/pdf" */
   mimeType?: string
-  /**
-   * True only when the modified side is a proven deletion (working-tree file gone
-   * or absent from the index) — distinct from an empty modified side caused by a
-   * read failure or size cap. Lets previewers fall back to the original bytes for
-   * a deletion without showing a stale image on a failed read.
-   */
+  /** True only for a proven deletion — distinct from an empty modified side caused by a read failure or size cap. */
   modifiedDeleted?: boolean
 } & (
   | { originalIsBinary: true; modifiedIsBinary: boolean }
@@ -3853,15 +3541,11 @@ export type StatsSummary = {
   totalAgentsSpawned: number
   totalPRsCreated: number
   totalAgentTimeMs: number
-  // For display formatting — sourced from aggregates, not the event log,
-  // so it survives event trimming.
+  // Sourced from aggregates, not the event log, so it survives event trimming.
   firstEventAt: number | null // timestamp of first-ever event, for "tracking since..."
 }
 
 // ─── Memory dashboard ──────────────────────────────────────────────
-// Resource-metrics snapshot shared across main, preload, and renderer so
-// the IPC payload is the same shape everywhere. Memory is in bytes; CPU
-// is a percentage (can exceed 100 on multi-core).
 
 /** cpu is percent of a single core — can exceed 100 on multi-core. memory is in bytes. */
 export type UsageValues = {
@@ -3874,9 +3558,7 @@ export type AppMemory = UsageValues & {
   main: UsageValues
   renderer: UsageValues
   other: UsageValues
-  /** Oldest-first memory samples (bytes) for the whole Orca app, one per
-   *  successful collection. Used to render the sparkline in the dashboard.
-   *  Empty before the first snapshot is recorded. */
+  /** Oldest-first memory samples (bytes) for the whole Orca app; empty before the first snapshot. */
   history: number[]
 }
 
@@ -3893,8 +3575,7 @@ export type WorktreeMemory = UsageValues & {
   repoId: string
   repoName: string
   sessions: SessionMemory[]
-  /** Oldest-first memory samples (bytes) for this worktree's tracked
-   *  subtrees, one per successful collection. */
+  /** Oldest-first memory samples (bytes) for this worktree's tracked subtrees. */
   history: number[]
 }
 

From 633cad3551e5d64a6ad80687496f6980137b1b6d Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Mon, 20 Jul 2026 04:01:58 -0700
Subject: [PATCH 53/54] refactor(comments): slim verbose comments in renderer
 components (#9546)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* refactor(comments): slim verbose comments in renderer components

Collapse multi-line explanatory comment blocks into single-line "why" statements
per AGENTS.md ("Document the Why, Briefly"): drop restatements of the code and
mechanism narration; keep the non-obvious reason, external refs, and directives.

Comments-only — verified no code changed via a Babel/esbuild comment-strip
token-equality gate against origin/main; typecheck and oxlint clean.

Area: renderer — components. 64 files changed, 2610 insertions(+), 8794 deletions(-).

Co-authored-by: Orca <help@stably.ai>

* fix(comments): restore comment markers pinned by source-boundary guard tests

Four *-boundary.test.ts guards assert on exact comment strings in the source
(e.g. '// Why: issue #4756 keeps project-view actions on the direct'). Slimming
reworded them, breaking the guards. Restored the pinned prefixes while keeping
the comments to one line. Guard suite (16 files/110 tests) green locally.

Co-authored-by: Orca <help@stably.ai>

---------

Co-authored-by: Orca <help@stably.ai>
---
 .../src/components/FirstLaunchBanner.tsx      |  91 +--
 .../src/components/GitHubItemDialog.tsx       | 304 ++------
 .../components/NewWorkspaceComposerCard.tsx   | 107 +--
 .../src/components/PullRequestPage.tsx        | 264 ++-----
 src/renderer/src/components/TaskPage.tsx      | 606 ++++-----------
 src/renderer/src/components/Terminal.tsx      | 426 +++--------
 src/renderer/src/components/UpdateCard.tsx    | 116 +--
 .../src/components/WorktreeJumpPalette.tsx    | 160 +---
 .../activity/ActivityPrototypePage.tsx        | 140 +---
 .../components/browser-pane/BrowserPane.tsx   | 371 +++-------
 .../browser-pane/BrowserPaneOverlayLayer.tsx  |  73 +-
 .../dashboard/DashboardAgentRow.tsx           | 143 +---
 .../diff-comments/DiffCommentPopover.tsx      |  85 +--
 .../diff-comments/useDiffCommentDecorator.tsx | 220 +-----
 .../components/editor/CombinedDiffViewer.tsx  | 114 +--
 .../src/components/editor/DiffViewer.tsx      |  81 +-
 .../src/components/editor/EditorContent.tsx   |  88 +--
 .../src/components/editor/MarkdownPreview.tsx | 149 +---
 .../src/components/editor/MonacoEditor.tsx    | 128 +---
 .../editor/editor-autosave-controller.ts      |  65 +-
 .../editor-restored-tab-conflict-scan.ts      |  56 +-
 .../editor/rich-markdown-source-reconcile.ts  |  65 +-
 .../github-project/ProjectViewWrapper.tsx     | 110 +--
 .../use-native-chat-live-session.ts           | 136 +---
 .../new-workspace/SmartWorkspaceNameField.tsx | 114 +--
 .../onboarding/use-onboarding-flow.ts         | 140 +---
 .../components/right-sidebar/ChecksPanel.tsx  | 255 ++-----
 .../right-sidebar/SourceControl.tsx           | 679 ++++-------------
 .../source-control-dropdown-items.ts          |  57 +-
 .../right-sidebar/useFileExplorerWatch.ts     |  80 +-
 .../src/components/settings/Settings.tsx      | 136 +---
 .../settings/TerminalSettingsPreview.tsx      |  86 +--
 .../components/sidebar/RemoteFileBrowser.tsx  | 106 +--
 .../src/components/sidebar/WorktreeCard.tsx   | 153 ++--
 .../components/sidebar/WorktreeCardAgents.tsx | 121 +--
 .../src/components/sidebar/WorktreeList.tsx   | 388 +++-------
 .../sidebar/delete-worktree-flow.ts           |  91 +--
 .../src/components/sidebar/smart-attention.ts | 138 +---
 .../status-bar/ResourceUsageStatusSegment.tsx | 145 +---
 .../src/components/status-bar/StatusBar.tsx   | 168 +----
 .../src/components/tab-bar/SortableTab.tsx    | 111 +--
 .../src/components/tab-bar/TabBar.tsx         |  83 +--
 .../components/tab-group/TabGroupPanel.tsx    |  87 +--
 .../tab-group/useTabGroupWorkspaceModel.ts    |  74 +-
 .../components/terminal-pane/TerminalPane.tsx | 491 +++---------
 .../agent-completion-coordinator.ts           | 146 +---
 .../hidden-reveal-reconciliation.fuzz.test.ts | 173 +----
 .../terminal-pane/layout-serialization.ts     | 127 +---
 .../parked-terminal-byte-watcher.ts           | 133 +---
 .../terminal-pane/pty-connection.test.ts      | 697 +++++-------------
 .../terminal-pane/pty-connection.ts           | 621 ++++------------
 .../pty-dispatcher-pi-routing.test.ts         |  65 +-
 .../terminal-pane/pty-dispatcher.ts           | 105 +--
 .../terminal-pane/pty-size-reconcile.test.ts  | 105 +--
 .../terminal-pane/pty-size-reconcile.ts       | 133 +---
 .../terminal-pane/pty-transport.test.ts       | 102 +--
 .../components/terminal-pane/pty-transport.ts | 200 ++---
 .../remote-runtime-pty-transport.ts           | 106 +--
 .../components/terminal-pane/replay-guard.ts  | 109 +--
 .../terminal-pane/terminal-appearance.test.ts |  69 +-
 .../terminal-pane/terminal-appearance.ts      | 120 +--
 .../terminal-parked-tab-watchers.ts           | 116 +--
 .../terminal-pane/terminal-shortcut-policy.ts | 115 +--
 .../use-terminal-pane-lifecycle.ts            | 361 +++------
 64 files changed, 2610 insertions(+), 8794 deletions(-)

diff --git a/src/renderer/src/components/FirstLaunchBanner.tsx b/src/renderer/src/components/FirstLaunchBanner.tsx
index 2237770e2f2..e6a5c39c616 100644
--- a/src/renderer/src/components/FirstLaunchBanner.tsx
+++ b/src/renderer/src/components/FirstLaunchBanner.tsx
@@ -1,37 +1,6 @@
-// Existing-user first-launch notice. Shown to users whose cohort marker is
-// `existedBeforeTelemetryRelease === true` and whose `optedIn` is still
-// `null`, i.e. users who installed Orca before the telemetry release and
-// have not yet resolved the notice.
-//
-// Why existing users see a notice at all (and new users do not): pre-
-// telemetry users installed Orca under a "no telemetry" social contract,
-// so default-on for them would be a silent policy flip. New users are
-// covered by the install-time disclosure and receive no first-launch UI —
-// see telemetry-plan.md §First-launch experience.
-//
-// Three actions, two semantics:
-//   - "Got it" and the ✕ in the corner → silent acknowledge. Both persist
-//     `optedIn: true`, fire no opt-in event, route through
-//     `window.api.telemetryAcknowledgeBanner()` to a dedicated main-side
-//     channel so no `via` derivation can tag this path. Two surfaces for
-//     the same action because the ✕ alone is easy to miss; "Got it" is
-//     the discoverable primary, ✕ is the keyboard/notification-style
-//     escape. Either way the user sees the notice, chooses not to
-//     intervene, and is opted in silently.
-//   - "Turn off" → explicit opt-out. Routes through
-//     `window.api.telemetrySetOptIn(false)`; main derives
-//     `via = 'first_launch_banner'` from the pre-mutation state
-//     (existedBeforeTelemetryRelease=true, optedIn=null, incoming=false)
-//     and fires `telemetry_opted_out { via: 'first_launch_banner' }`
-//     BEFORE disabling the SDK — the one signal that tells us the
-//     opt-out flow is working must not be silenced by the opt-out it
-//     announces.
-//   - "Privacy policy" link → opens the privacy doc URL, no state change,
-//     no dismiss.
-//
-// No auto-dismiss, no delayed re-ask: once resolved (Got it / ✕ / Turn
-// off), the notice never returns, because the cohort condition
-// (`optedIn === null`) clears in all three resolving paths.
+// First-launch telemetry notice shown only to pre-telemetry users (existedBeforeTelemetryRelease && optedIn === null),
+// who installed under a "no telemetry" contract; new users are covered by install-time disclosure.
+// Got it / ✕ silently opt in; "Turn off" explicitly opts out. See telemetry-plan.md §First-launch experience.
 
 import { useState } from 'react'
 import { X } from 'lucide-react'
@@ -50,14 +19,7 @@ export function FirstLaunchBanner({
   onResolve,
   fetchSettings
 }: FirstLaunchBannerProps): React.JSX.Element {
-  // Double-click guard. Without this, a fast second click on "Turn off"
-  // would re-enter telemetrySetOptIn(false); on the second call, main's
-  // deriveOptInVia sees currentOptedIn=false (just persisted by click 1)
-  // and falls through to the 'settings' branch, producing one opt-out
-  // intent tagged as two different `via` values. The acknowledge paths
-  // are guarded symmetrically — a second Got-it/✕ click would be a
-  // wasted IPC round-trip, but the guard also blocks a Turn-off click
-  // arriving mid-flight after an acknowledge (or vice versa).
+  // Double-click guard: a second Turn-off click would re-derive `via` as 'settings', mis-tagging one opt-out as two.
   const [inFlight, setInFlight] = useState(false)
   const mountedRef = useMountedRef()
 
@@ -66,14 +28,7 @@ export function FirstLaunchBanner({
       return
     }
     setInFlight(true)
-    // Main's `telemetry:acknowledgeBanner` handler persists `optedIn: true`
-    // without an opt-in event and intentionally does NOT broadcast
-    // `settings:changed` (see src/main/ipc/telemetry.ts). Without an
-    // explicit `fetchSettings()` refresh, the renderer store would retain
-    // `optedIn: null` and PrivacyPane would keep rendering its pending-
-    // banner helper text until the next full relaunch. Mirror
-    // PrivacyPane's handleToggle pattern which refetches for the same
-    // reason before surfacing UI changes.
+    // acknowledgeBanner doesn't broadcast settings:changed, so refetch or the store keeps optedIn: null.
     try {
       await acknowledgeBanner()
       await fetchSettings()
@@ -81,10 +36,7 @@ export function FirstLaunchBanner({
         onResolve()
       }
     } finally {
-      // Why: if `fetchSettings` rejects (IPC error during shutdown,
-      // settings file lock, etc.), `onResolve` never runs and the banner
-      // stays mounted. Without resetting `inFlight`, every button stays
-      // permanently disabled for the rest of the session.
+      // Reset inFlight so a fetchSettings rejection doesn't leave every button permanently disabled.
       if (mountedRef.current) {
         setInFlight(false)
       }
@@ -96,11 +48,7 @@ export function FirstLaunchBanner({
       return
     }
     setInFlight(true)
-    // Opt-out fires `telemetry_opted_out { via: 'first_launch_banner' }`
-    // BEFORE the SDK disable — main enforces that ordering inside
-    // `setOptIn` (client.ts). The renderer just needs to route through
-    // `telemetrySetOptIn(false)` so the IPC handler derives the correct
-    // `via` and fires the event.
+    // Route through telemetrySetOptIn(false) so main derives `via` and fires telemetry_opted_out before disabling the SDK.
     try {
       await telemetrySetOptIn(false)
       await fetchSettings()
@@ -115,24 +63,15 @@ export function FirstLaunchBanner({
   }
 
   return (
-    // Fixed-top strip so the notice overlays whatever is beneath without
-    // shifting the rest of the layout. `top-2` hugs the top edge of the
-    // window; on macOS the titlebar is drawn over the same region but the
-    // banner stays below the traffic lights via centering + narrow width.
-    // The notice is non-modal and intentionally does not occlude the main
-    // content — clicks pass through to below-notice regions outside this
-    // box.
-    //
-    // `relative` is load-bearing: the absolutely-positioned ✕ anchors to
-    // this container.
+    // Fixed non-modal overlay; centered + narrow so it clears the macOS traffic lights.
+    // `relative` is load-bearing: the absolutely-positioned ✕ anchors to this container.
     <div
       className="fixed left-1/2 top-2 z-40 flex w-[min(44.625rem,calc(100vw-2rem))] -translate-x-1/2 items-start gap-4 rounded-lg border border-border bg-card/95 py-3 pl-4 pr-3 shadow-lg backdrop-blur"
       role="region"
       aria-label={translate('auto.components.FirstLaunchBanner.fcbee32f08', 'Telemetry notice')}
       aria-live="polite"
     >
-      {/* Text column — title + body stack on the left, takes remaining
-          width so the action column never pushes copy into a wrap. */}
+      {/* Text column — flex-1 so the action column never wraps the copy. */}
       <div className="flex-1 space-y-0.5 pr-1 text-sm">
         <p className="font-medium leading-snug">
           {translate(
@@ -155,12 +94,7 @@ export function FirstLaunchBanner({
           .
         </p>
       </div>
-      {/* Action column — vertically centered against the text block.
-          "Got it" is the affirmative primary so it reads as the easy
-          path; "Turn off" is the secondary outline so the destructive
-          (from telemetry's perspective) action requires an explicit
-          choice. ✕ stays in the corner as a familiar escape and to
-          satisfy keyboard/notification-style dismiss expectations. */}
+      {/* Action column — "Got it" primary reads as the easy path; "Turn off" outline marks the explicit opt-out. */}
       <div className="flex shrink-0 items-center gap-2 self-center pr-6">
         <Button
           variant="outline"
@@ -175,8 +109,7 @@ export function FirstLaunchBanner({
           {translate('auto.components.FirstLaunchBanner.94cc673726', 'Got it')}
         </Button>
       </div>
-      {/* aria-label says "Dismiss" — the action persists silent opt-in,
-          not just hides the UI. */}
+      {/* aria-label says "Dismiss" but this persists silent opt-in, not just hides the UI. */}
       <button
         type="button"
         aria-label={translate('auto.components.FirstLaunchBanner.b9e1b966c7', 'Dismiss notice')}
diff --git a/src/renderer/src/components/GitHubItemDialog.tsx b/src/renderer/src/components/GitHubItemDialog.tsx
index 5d98a84f0f1..30c4a491bd4 100644
--- a/src/renderer/src/components/GitHubItemDialog.tsx
+++ b/src/renderer/src/components/GitHubItemDialog.tsx
@@ -227,12 +227,7 @@ import {
   type TaskPageGitHubCloseAction
 } from '@/components/task-page-github-status-actions'
 
-// Why: the GH item dialog can be opened from any work-item list surface and
-// doesn't have the full owner/repo context the list's cache entry carries.
-// Parsing the canonical `https://github.com/{owner}/{repo}/...` URL is the
-// simplest reliable source — the URL is already present on every work item
-// and survives the main-process → IPC boundary. Non-GitHub hosts return null,
-// which matches the indicator's suppression rule.
+// Why: the dialog lacks owner/repo context, so recover it from the canonical URL present on every item; non-GitHub hosts return null (matches the indicator's suppression rule).
 function parseOwnerRepoFromItemUrl(url: string): GitHubOwnerRepo | null {
   try {
     const parsed = new URL(url)
@@ -259,8 +254,7 @@ function getGitHubRepositoryLabelsUrl(itemUrl: string): string | null {
     if (segments.length < 2) {
       return null
     }
-    // Why: label management is repository-scoped; preserving the origin keeps
-    // GitHub Enterprise URLs working while navigating away from the issue path.
+    // Why: preserve the origin so GitHub Enterprise URLs keep working while re-pathing to the repo-scoped labels page.
     parsed.pathname = `/${segments[0]}/${segments[1]}/labels`
     parsed.search = ''
     parsed.hash = ''
@@ -299,13 +293,7 @@ function normalizeItemDialogTab(
   return tab ?? 'conversation'
 }
 
-/** Why: Project-origin rows don't always belong to the active local repo.
- *  When set, GHEditSection routes label/assignee/state mutations through
- *  slug-addressed IPCs against `owner`/`repo` instead of through `repoPath`,
- *  preventing edits from silently landing on the workspace's repo when the
- *  Project view is showing rows from a different repo. See
- *  docs/design/github-project-view-tasks.md §Dialog editing from Project rows.
- */
+/** Why: a Project row may not belong to the active repo; when set, mutations route through slug-addressed IPCs against `owner`/`repo` so edits don't land on the workspace's repo. See docs/design/github-project-view-tasks.md §Dialog editing from Project rows. */
 export type GitHubItemDialogProjectOrigin = {
   owner: string
   repo: string
@@ -330,11 +318,7 @@ type GitHubItemDialogProps = {
     reviewRequests: GitHubAssignableUser[]
   ) => void
   onClose: () => void
-  /** Optional Project-origin context. When set, edits in the dialog are
-   *  routed via slug-addressed mutation IPCs against the row's actual repo
-   *  instead of the active workspace's `repoPath`. Both can be set
-   *  simultaneously (Project mode where the row also lives in the active
-   *  workspace) — slug routing wins for writes. */
+  /** Optional Project-origin context; when set, edits route via slug-addressed IPCs against the row's repo (slug routing wins for writes). */
   projectOrigin?: GitHubItemDialogProjectOrigin
 }
 
@@ -387,8 +371,7 @@ function getStateTone(item: GitHubWorkItem): string {
     return 'border-emerald-500/30 bg-emerald-500/10 text-emerald-600 dark:text-emerald-300'
   }
   if (item.state === 'closed') {
-    // Why: closed issues can mean completed/resolved; keep them neutral instead
-    // of using destructive red, which is reserved for PR closed-without-merge.
+    // Why: keep closed issues neutral (may be completed/resolved); red is reserved for PR closed-without-merge.
     return 'border-ring/50 bg-primary/10 text-foreground'
   }
   return 'border-emerald-500/30 bg-emerald-500/10 text-emerald-600 dark:text-emerald-300'
@@ -502,8 +485,7 @@ function PRAssigneesPanel({
   )
   const { isPending, run } = useImmediateMutation()
 
-  // Why: PR assignees can change through background refetches; sync them
-  // before paint so the right rail never shows a stale reviewer/assignee split.
+  // Why: a background refetch can change PR assignees; sync before paint so the right rail never shows a stale reviewer/assignee split.
   if (
     assigneesSource.itemId !== item.id ||
     assigneesSource.repoId !== item.repoId ||
@@ -768,8 +750,7 @@ function PRReviewersPanel({
     }
   }, [cancelReviewerInputFocusFrame])
 
-  // Why: reviewer edits are optimistic, but item switches/refetches must clear
-  // stale local requests before paint; a passive Effect leaves one stale render.
+  // Why: clear stale optimistic reviewer requests on item switch/refetch before paint; a passive Effect would leave one stale render.
   if (
     reviewRequestsSource.itemId !== item.id ||
     reviewRequestsSource.repoId !== item.repoId ||
@@ -1386,13 +1367,7 @@ function isPRFileViewed(file: GitHubPRFile): boolean {
   return file.viewerViewedState === 'VIEWED'
 }
 
-// Why: SWR cache for the work-item details fetch. Reopening the same drawer
-// pays full IPC + `gh` process startup latency without this; with it, cached
-// data paints immediately while a background refetch keeps the view honest.
-// Cache is keyed by repoPath + issueSourcePreference + type + number so
-// upstream/origin source toggles and issue#N vs pr#N never collide. Bounded
-// to ~50 entries to cap memory; entries older than FRESH_MS trigger a
-// background refetch on open. See docs/gh-work-item-drawer-cache.md.
+// Why: SWR cache for work-item details so reopening paints instantly instead of paying IPC + `gh` startup; keyed to avoid source/type collisions, LRU-bounded, FRESH_MS refetch on open. See docs/gh-work-item-drawer-cache.md.
 const WORK_ITEM_DETAILS_CACHE_MAX = 50
 const WORK_ITEM_DETAILS_FRESH_MS = 30_000
 const WORK_ITEM_DETAILS_UNAVAILABLE_MESSAGE = 'Unable to load details for this GitHub item.'
@@ -1404,10 +1379,7 @@ type WorkItemDetailsCacheEntry = {
 }
 const workItemDetailsCache = new Map<string, WorkItemDetailsCacheEntry>()
 
-// Why: drawers subscribe via useSyncExternalStore so reopening a cached item
-// paints synchronously on first render. Stability of the snapshot relies on
-// every cache write replacing the entry object identity (delete+set), which
-// touchWorkItemDetailsCache already does.
+// Why: drawers subscribe via useSyncExternalStore so a cached item paints synchronously; snapshot stability relies on every write replacing entry identity (delete+set).
 const workItemDetailsCacheListeners = new Set<() => void>()
 function subscribeWorkItemDetailsCache(listener: () => void): () => void {
   workItemDetailsCacheListeners.add(listener)
@@ -1429,8 +1401,7 @@ function getWorkItemDetailsCacheKey(args: {
   type: 'issue' | 'pr'
   number: number
 }): string {
-  // Why: include all axes that change which (repo, item) the IPC resolves to.
-  // `\0` separator avoids ambiguity between fields that may contain `:` or `/`.
+  // Why: key on every axis that changes which (repo, item) the IPC resolves to; `\0` separator avoids ambiguity with fields containing `:` or `/`.
   const keyParts = args.sourceCacheScope
     ? [args.repoId, args.sourceCacheScope, args.issueSourcePreference ?? 'auto', args.type]
     : [args.repoId, args.issueSourcePreference ?? 'auto', args.type]
@@ -1438,8 +1409,7 @@ function getWorkItemDetailsCacheKey(args: {
 }
 
 function touchWorkItemDetailsCache(key: string, entry: WorkItemDetailsCacheEntry): void {
-  // Why: re-insert to move to MRU position; Map preserves insertion order so
-  // the oldest key is always first when evicting.
+  // Why: re-insert to move to MRU position; Map insertion order keeps the oldest key first for eviction.
   workItemDetailsCache.delete(key)
   workItemDetailsCache.set(key, entry)
   while (workItemDetailsCache.size > WORK_ITEM_DETAILS_CACHE_MAX) {
@@ -1452,12 +1422,9 @@ function touchWorkItemDetailsCache(key: string, entry: WorkItemDetailsCacheEntry
   notifyWorkItemDetailsCache()
 }
 
-// Why: exposed so mutation handlers (in this file and elsewhere) can drop a
-// stale entry after a successful local mutation. Cross-window invalidation
-// arrives via the `gh:workItemMutated` event listener installed below.
+// Why: exposed so mutation handlers can drop a stale entry after a local mutation; cross-window invalidation arrives via the gh:workItemMutated listener below.
 export function invalidateWorkItemDetailsCacheForKey(key: string): void {
-  // Why: bump generation so an in-flight fetch launched before this exact-key
-  // invalidation will not write its stale result back into the cache.
+  // Why: bump generation so a fetch launched before this invalidation won't write its stale result back.
   workItemDetailsCacheGeneration += 1
   const existed = workItemDetailsCache.delete(key)
   if (existed) {
@@ -1465,16 +1432,10 @@ export function invalidateWorkItemDetailsCacheForKey(key: string): void {
   }
 }
 
-// Why: monotonically increases on every invalidation so an in-flight refetch
-// that started before a mutation can detect that its result is stale and
-// must not be written back. Without this, a mutation that lands while a
-// refetch is in flight would have its invalidation silently undone when the
-// stale promise resolves and re-populates the entry.
+// Why: bumped on every invalidation so an in-flight refetch started before a mutation can detect its result is stale and skip writing it back.
 let workItemDetailsCacheGeneration = 0
 
-// Why: when we don't have the exact cache key (e.g. an event from another
-// window only carries repoPath + number + type), drop every entry that
-// matches the (repoPath, type, number) tuple regardless of source preference.
+// Why: without the exact key (e.g. a cross-window event carries only repoPath+number+type), drop every entry matching that tuple regardless of source preference.
 function invalidateWorkItemDetailsCacheByMatch(args: {
   repoPath: string
   repoId?: string
@@ -1570,11 +1531,7 @@ function patchCachedWorkItemBody(cacheKey: string, body: string): void {
   })
 }
 
-// Why: install once at module load — every dialog instance shares the cache,
-// so a single subscription is enough. Main targets the registered app renderer
-// for non-origin mutations, and this listener invalidates the matching entry.
-// We track the unsubscribe so
-// Vite HMR doesn't accumulate listeners across module reloads in dev.
+// Why: install once — all dialogs share the cache; track unsubscribe so Vite HMR doesn't accumulate listeners across dev reloads.
 let workItemMutatedUnsub: (() => void) | undefined
 let workItemDetailsCacheEventUnsub: (() => void) | undefined
 if (typeof window !== 'undefined' && window.api?.gh?.onWorkItemMutated) {
@@ -1597,11 +1554,9 @@ if (typeof import.meta !== 'undefined' && import.meta.hot) {
   })
 }
 
-// Why: bounded LRU — opening many PRs with many files during a session
-// would otherwise grow this module-level map without bound until reload.
+// Why: bounded LRU so opening many PRs with many files doesn't grow this module-level map unboundedly until reload.
 const PR_FILE_CONTENT_CACHE_MAX = 64
-// Why: raw-content overflow is only a sentinel; force the reported size past
-// the render budget so downstream checks reliably choose fallback mode.
+// Why: overflow is a sentinel; force reported size past the render budget so downstream checks reliably pick fallback mode.
 const GITHUB_PR_RAW_CONTENT_OVERFLOW_CHARACTER_COUNT = MAX_RENDERED_DIFF_COMBINED_CHARACTERS + 1
 const PR_FILE_CONTENT_CACHE_MAX_BYTES = MAX_RENDERED_DIFF_COMBINED_CHARACTERS * 4
 type PRFileContentCacheEntry = {
@@ -1667,8 +1622,7 @@ function touchPRFileContentCache(
 
   const existing = prFileContentCache.get(key)
   prFileContentCacheBytes -= existing?.byteCount ?? 0
-  // Why: re-insert to move to the most-recently-used position; Map preserves
-  // insertion order so the oldest key is always first when evicting.
+  // Why: re-insert to move to MRU position; Map insertion order keeps the oldest key first for eviction.
   prFileContentCache.delete(key)
   const byteCount = retainedByteCount
   prFileContentCache.set(key, { value, byteCount })
@@ -2214,8 +2168,7 @@ function PRFilesCombinedDiffViewer({
   const inlineReviewComments = useMemo<DecoratedDiffComment[]>(
     () =>
       comments.flatMap((comment): DecoratedDiffComment[] => {
-        // Why: stale threads keep originalLine for the sidebar, but rendering
-        // that number inline can attach the comment to unrelated current code.
+        // Why: outdated threads' line number can attach the comment to unrelated current code, so skip them inline.
         if (comment.isOutdated || !comment.path || typeof comment.line !== 'number') {
           return []
         }
@@ -2761,8 +2714,7 @@ function CommentCodeContext({
     comment.id
   )
   if (resolvedContextExpansionState !== contextExpansionState) {
-    // Why: comment rows can be reused when a PR refreshes; reset before paint
-    // so expanded context from the previous comment is never shown on the next.
+    // Why: comment rows can be reused on PR refresh; reset before paint so the previous comment's expanded context isn't shown on the next.
     setContextExpansionState(resolvedContextExpansionState)
   }
   const contextBefore = resolvedContextExpansionState.contextBefore
@@ -3135,15 +3087,13 @@ function ConversationTab({
   const resolvedReplyingTo = resolveCommentReplyTarget(replyingTo, replyTargetComments)
 
   if (resolvedReplyingTo !== replyingTo) {
-    // Why: comment filters/refetches can hide the active reply target; clear it
-    // before paint so a stale composer does not flash for the wrong comment set.
+    // Why: filters/refetches can hide the active reply target; clear before paint so a stale composer doesn't flash for the wrong comment set.
     setReplyingTo(resolvedReplyingTo)
   }
 
   const resolvedBodyDraft = resolveGitHubBodyDraft(bodyDraft, body, bodyEditing)
   if (shouldSyncGitHubBodyDraft(bodyDraft, body, bodyEditing)) {
-    // Why: background detail refreshes can change the body while the editor is
-    // closed; reconcile before paint so reopening never sees a stale draft.
+    // Why: a background refresh can change the body while the editor is closed; reconcile before paint so reopening never sees a stale draft.
     setBodyDraft(resolvedBodyDraft)
   }
 
@@ -3619,9 +3569,7 @@ function ConversationTab({
     <div
       className={cn(
         'grid min-w-0 gap-5 px-4 py-4',
-        // Why: the drawer expands nearly full-width on narrow app windows, so
-        // keep PR controls beside the conversation instead of hiding them below
-        // long review threads.
+        // Why: keep PR controls beside the conversation, not buried below long review threads on narrow windows.
         item.type === 'pr' && 'grid-cols-[minmax(0,1fr)_300px]'
       )}
     >
@@ -4367,8 +4315,7 @@ function getChecksSummaryLabel(checks: PRCheckDetail[]): string {
   if (counts.failing > 0) {
     return `${counts.failing} ${counts.failing === 1 ? 'check' : 'checks'} failing`
   }
-  // Why: action_required (e.g. a workflow awaiting approval) blocks merge but is
-  // not a failure; call it out distinctly so users know a manual step is needed.
+  // Why: action_required blocks merge but isn't a failure; surface it distinctly so users know a manual step is needed.
   if (counts.needsAction > 0) {
     return `${counts.needsAction} ${counts.needsAction === 1 ? 'check needs' : 'checks need'} action`
   }
@@ -4429,8 +4376,7 @@ function ChecksTab({
   const mountedRef = useMountedRef()
   const resolvedChecksState = resolveGitHubChecksTabState(checksState, checks)
   if (resolvedChecksState !== checksState) {
-    // Why: parent check refreshes replace the source list; clear local refresh
-    // and inline detail state before stale rows/details can paint.
+    // Why: a parent check refresh replaces the source list; reset local state before stale rows/details can paint.
     setChecksState(resolvedChecksState)
   }
   const { localChecks, expandedCheckKey, detailsByCheckKey } = resolvedChecksState
@@ -5238,16 +5184,11 @@ function ChecksTab({
   )
 }
 
-// Why: when the dialog opens for a Project row whose repo differs from the
-// active workspace, mutations must target the row's actual repo via
-// slug-addressed IPCs. Otherwise edits silently apply to the workspace's
-// repo. The edit IPCs return a structured `{ ok, error }` shape; we adapt
-// to a thrown rejection so the existing `useImmediateMutation` flow
-// (which expects throws on failure) continues to work unchanged.
+// Why: for a Project row whose repo differs from the active workspace, mutations must target the row's actual repo via slug-addressed IPCs, else edits silently apply to the workspace's repo.
+// Why: these edit IPCs return `{ ok, error }`; callers throw on `!ok` so useImmediateMutation (which expects throws on failure) works unchanged.
 function getGitHubMutationSettings(repoId: string | null | undefined) {
   const state = useAppStore.getState()
-  // Why: project-origin mutations are slug-addressed, but when we know the
-  // backing repo id they must still execute on that repo's owner host.
+  // Why: even slug-addressed project-origin mutations must run on the backing repo's owner host when its id is known.
   return getSettingsForRepoRuntimeOwner(state, repoId ?? null)
 }
 
@@ -5553,17 +5494,13 @@ function GHEditSection({
   localLabels: string[]
   onStateChange: (state: GitHubWorkItem['state']) => void
   onLabelsChange: (labels: string[]) => void
-  /** Why: called after a successful issue mutation so the parent dialog can
-   *  invalidate its work-item-details cache entry. Without this, reopening the
-   *  drawer in the FRESH_MS window would paint pre-mutation data. */
+  /** Why: lets the parent invalidate its details cache after a mutation, else a reopen within FRESH_MS paints pre-mutation data. */
   onMutated: () => void
   assignees: string[]
   onUse: (item: GitHubWorkItem) => void
   onOpenOrUse?: (item: GitHubWorkItem) => void
   attachedWorkspaceLabel?: string | null
-  /** Two surfaces only: compact pill strip for the non-issue drawer/header
-   *  (`horizontal`), and labeled property columns above the issue page body
-   *  (`top-columns`). */
+  /** `horizontal`: compact pill strip for the non-issue drawer/header; `top-columns`: labeled columns above the issue page body. */
   layout?: 'horizontal' | 'top-columns'
 }): React.JSX.Element | null {
   const [labelPopoverOpen, setLabelPopoverOpen] = useState(false)
@@ -5612,11 +5549,7 @@ function GHEditSection({
     [repoOwnerSettings, sourceContext]
   )
   const { isPending, run } = useImmediateMutation()
-  // Why: when the dialog opens from a Project view, mutations route through
-  // *BySlug IPCs and we must keep `projectViewCache` in sync alongside
-  // `workItemsCache` — `patchWorkItem` only walks the latter, so without this
-  // helper the Project table would render stale data until manual refresh.
-  // See docs/design/github-project-view-tasks.md §Dialog editing from Project rows.
+  // Why: from a Project view, keep projectViewCache in sync too — patchWorkItem only walks workItemsCache, so the table would render stale without this. See docs/design/github-project-view-tasks.md §Dialog editing from Project rows.
   const patchProjectRowIfNeeded = useCallback(
     (patch: Parameters<typeof patchProjectRowContent>[2]) => {
       if (!projectOrigin) {
@@ -5627,9 +5560,7 @@ function GHEditSection({
     [projectOrigin, patchProjectRowContent]
   )
 
-  // Why: when projectOrigin is set we MUST read labels/assignees from the
-  // row's repo, not from the workspace path — otherwise the popovers list
-  // values from a different repo than the writes target.
+  // Why: with projectOrigin set, read labels/assignees from the row's repo, not the workspace path, or popovers list a different repo than writes target.
   const slugOwner = projectOrigin?.owner ?? null
   const slugRepo = projectOrigin?.repo ?? null
   const repoLabelsByPath = useRepoLabels(
@@ -5684,9 +5615,7 @@ function GHEditSection({
     onUse(item)
   }, [item, onOpenOrUse, onUse])
 
-  // Why: sync local assignees when item changes or when the detail fetch
-  // resolves with real data — but skip if the user already made an
-  // optimistic edit so we don't clobber in-flight changes.
+  // Why: sync local assignees on item change / detail resolve, but skip if the user made an optimistic edit so we don't clobber in-flight changes.
   useEffect(() => {
     if (editedAssigneesItemKeyRef.current === assigneesItemKey) {
       return
@@ -5870,8 +5799,7 @@ function GHEditSection({
         ? prevAssignees.filter((l) => l !== login)
         : [...prevAssignees, login]
 
-      // Why: the optimistic guard is scoped to this repo item so switching
-      // items does not suppress the next item's assignee sync.
+      // Why: scope the optimistic guard to this repo item so switching items doesn't suppress the next item's assignee sync.
       editedAssigneesItemKeyRef.current = assigneesItemKey
       if (isAssigned) {
         run('assignees', {
@@ -6146,8 +6074,7 @@ function GHEditSection({
   )
 
   if (layout === 'top-columns') {
-    // Why: issue page body should match the header width — property fields sit
-    // as top columns so the description is not squeezed by a right rail.
+    // Why: lay property fields as top columns so the description isn't squeezed by a right rail.
     return (
       <aside className="grid grid-cols-2 gap-x-6 gap-y-5 text-[13px] sm:grid-cols-4">
         {/* State */}
@@ -6333,8 +6260,7 @@ function GHEditSection({
         </section>
 
         <section className="min-w-0">
-          {/* Why: primary open/start CTA lives only in the issue header — property
-              columns are metadata (status, assignees, labels, attached workspace). */}
+          {/* Why: property columns are metadata only; the primary open/start CTA lives solely in the issue header. */}
           <div className="mb-2 text-[11px] font-semibold uppercase tracking-[0.05em] text-muted-foreground">
             {translate('auto.components.GitHubItemDialog.2e4d806c92', 'Workspace')}
           </div>
@@ -6600,8 +6526,7 @@ function GHCommentComposer({
       }
       if (result.ok) {
         setBody('')
-        // Why: use the comment returned by GitHub so the optimistic row shows
-        // the real login/avatar immediately instead of waiting for a reopen.
+        // Why: use GitHub's returned comment so the optimistic row shows the real login/avatar immediately.
         onCommentAdded(result.comment)
       } else {
         toast.error(
@@ -6661,21 +6586,7 @@ function GHCommentComposer({
   )
 }
 
-// Why: the dialog doesn't carry the resolved PR-source slug the Tasks view's
-// list cache carries, so we reach into workItemsCache to recover it. We scope
-// the lookup to the dialog's own `repoPath` via the public
-// `getWorkItemsAnySourcesForRepo` selector keyed by (repoPath, limit) —
-// scanning the whole cache risks picking a sibling repo's PR-source when two
-// selected repos share the same issue-source (e.g. two forks of the same
-// upstream), producing an incorrect "Issues from" chip or incorrectly
-// suppressing it. The selector keys primarily on the first-page entry
-// (PER_REPO_FETCH_LIMIT, empty query) because sources are repo-level and
-// don't vary by search query. If that slot is empty — e.g. the Tasks view is
-// filtering by a typed query and only populated the query-keyed entry — the
-// selector falls back to scanning cache entries prefixed by this same
-// `repoPath::` and reuses sources from the first match. Falling back to hiding
-// the indicator when we still can't find a match matches the parent design
-// doc §1 rule: hide when either side is unknown rather than guessing.
+// Why: recover the PR-source slug the dialog lacks from workItemsCache, scoped to this repoPath so a sibling repo sharing the issue-source (e.g. two forks) can't mislabel the chip; hide when unknown rather than guess (design doc §1).
 function WorkItemIssueSourceIndicator({
   url,
   repoId,
@@ -6685,17 +6596,7 @@ function WorkItemIssueSourceIndicator({
   repoId: string | null
   repoPath?: string | null
 }): React.JSX.Element | null {
-  // Why: subscribe to a single store-side selector that returns the resolved
-  // sources for this repo — either the primary `(repoPath, PER_REPO_FETCH_LIMIT, '')`
-  // entry or the first sibling cache entry that has sources (the Tasks view may
-  // write cache entries keyed by a user-typed search query, so the primary slot
-  // can be empty even when sources are known). Sources are repo-level
-  // (query-independent), so any sibling entry is safe. When the primary slot
-  // is populated its reference is stable across unrelated cache writes; when
-  // the fallback path is used a sibling cache rewrite may produce a new
-  // `sources` object and trigger a harmless extra render. That's cheap — the
-  // indicator is small and the cache rewrite rate is bounded by user-initiated
-  // refresh/search actions.
+  // Why: resolve repo sources via the primary cache entry, or any sibling entry if the Tasks view only populated a query-keyed slot (sources are repo-level, so any is safe).
   const sources = useAppStore((s) =>
     s.getWorkItemsAnySourcesForRepo(repoId ?? '', PER_REPO_FETCH_LIMIT, repoPath ?? undefined)
   )
@@ -6704,9 +6605,7 @@ function WorkItemIssueSourceIndicator({
     if (!fromUrl) {
       return null
     }
-    // Prefer the cache's resolved issue-source when it matches the URL-derived
-    // slug — the cache entry is authoritative (canonicalized by the main
-    // process) while the URL parse is a best-effort fallback.
+    // Prefer the cache's resolved issue-source (canonicalized by main) over the best-effort URL parse when they match.
     const cachedIssues = sources?.issues
     if (cachedIssues && sameGitHubOwnerRepo(cachedIssues, fromUrl)) {
       return cachedIssues
@@ -6744,8 +6643,7 @@ export default function GitHubItemDialog({
   const [linkCopyState, setLinkCopyState] = useState(() => createGitHubLinkCopyState(workItemId))
   const resolvedLinkCopyState = resolveGitHubLinkCopyState(linkCopyState, workItemId)
   if (resolvedLinkCopyState !== linkCopyState) {
-    // Why: switching GitHub items should not paint a stale copied indicator
-    // from the previous item while waiting for a passive Effect pass.
+    // Why: switching items must not paint a stale "copied" indicator from the previous item.
     setLinkCopyState(resolvedLinkCopyState)
   }
   const linkCopied = resolvedLinkCopyState.copied
@@ -6789,11 +6687,7 @@ export default function GitHubItemDialog({
     [effectiveRepoId, onUse]
   )
 
-  // Why: the cache key has to include the issue source preference so a user
-  // toggling between origin/upstream for the same issue number doesn't read
-  // back the wrong repo's details. We pull it from the repos slice rather
-  // than threading it as a prop because every existing call site already has
-  // the repo registered in the store.
+  // Why: the cache key must include issue source preference so toggling origin/upstream for the same issue number doesn't read the wrong repo's details.
   const issueSourcePreference = useAppStore((s) => {
     if (!repoPath && !effectiveRepoId) {
       return undefined
@@ -6824,20 +6718,12 @@ export default function GitHubItemDialog({
     issueSourcePreference
   ])
 
-  // Why: track comments added optimistically before the detail fetch resolves
-  // so they can be merged into the fetch result instead of being overwritten.
+  // Why: hold comments added before the detail fetch resolves so they merge into the result instead of being overwritten.
   const optimisticCommentsRef = useRef<PRComment[]>([])
-  // Why: track the last item we fetched so we can distinguish "reopen same
-  // item" from "switch to a different item". Reopening the same item must
-  // preserve optimistic comments because gh's 60s response cache will return
-  // stale data that doesn't include the just-posted comment.
+  // Why: distinguish "reopen same item" from "switch item" — reopen must keep optimistic comments since gh's 60s cache omits the just-posted one.
   const prevItemIdRef = useRef<string | null>(null)
 
-  // Why: when this dialog opens immediately after another Radix overlay
-  // (e.g. the New Issue dialog) closed, Radix may leave `pointer-events: none`
-  // on <body>. That silently kills clicks on the header's Close/open-in-GitHub
-  // buttons. Poll a few frames to clear it whenever Radix re-applies it during
-  // its own mount sequence.
+  // Why: a just-closed Radix overlay can leave `pointer-events: none` on <body>, killing header button clicks; poll a few frames to clear it.
   useEffect(() => {
     if (!workItem) {
       return
@@ -6866,10 +6752,7 @@ export default function GitHubItemDialog({
     }
   }, [workItem])
 
-  // Why: subscribe to the module-level cache so reopening a cached item
-  // paints synchronously on first render. getSnapshot returns the entry
-  // object directly — touchWorkItemDetailsCache writes always replace entry
-  // identity (delete+set), so Map.get is referentially stable between writes.
+  // Why: subscribe to the module-level cache so reopening a cached item paints synchronously on first render.
   const cachedEntry = useSyncExternalStore(
     subscribeWorkItemDetailsCache,
     useCallback(
@@ -6878,24 +6761,15 @@ export default function GitHubItemDialog({
     )
   )
 
-  // Why: bumped by appendOptimisticComment on cold open (no cached details
-  // yet) so the details memo re-runs and surfaces the optimistic comment via
-  // the loading-shell fallback. Without this, the comment would sit in the
-  // ref alone and not render until the in-flight fetch lands. The cache
-  // notify path handles the warm case.
+  // Why: bumped on cold open (no cached details yet) so the details memo re-runs and surfaces the optimistic comment before the fetch lands.
   const [optimisticTick, setOptimisticTick] = useState(0)
 
-  // Why: merge optimistic comments into the cached details. Keyed off
-  // cachedEntry identity (stable) rather than the optimistic ref array (a
-  // fresh array each render) to avoid unnecessary recomputation. Cache
-  // notifications after optimistic writes will re-render this anyway.
+  // Why: key off cachedEntry identity (stable), not the optimistic ref array (fresh each render), to avoid needless recompute.
   const details = useMemo<GitHubWorkItemDetails | null>(() => {
     const cachedDetails = cachedEntry?.details ?? null
     const opt = optimisticCommentsRef.current
     if (!cachedDetails) {
-      // Why: details may still be loading on a cold open — surface optimistic
-      // comments via a minimal shell so a comment posted before the fetch
-      // resolves isn't held invisibly in ref-land.
+      // Why: on cold open, details may still be loading — surface optimistic comments via a minimal shell so a pre-fetch comment isn't invisible.
       if (opt.length > 0 && workItem) {
         return { item: workItem, body: '', comments: [...opt] }
       }
@@ -6913,18 +6787,13 @@ export default function GitHubItemDialog({
       ...cachedDetails,
       comments: [...cachedDetails.comments, ...missing]
     }
-    // Why: optimisticTick is the rerender signal for cold-open writes — the
-    // memo reads optimisticCommentsRef.current (a ref, no subscription), so
-    // bumping the tick is what forces this memo to re-run. The lint flags it
-    // as "unnecessary" because it's not referenced in the body, but removing
-    // it would silently break the cold-open optimistic-shell path.
+    // Why: optimisticTick forces this ref-reading memo to re-run on cold-open writes; lint can't see the dependency.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [cachedEntry, workItem, optimisticTick])
 
   const resolvedWorkItemState = details?.item.state ?? workItemState
 
-  // Why: the list row that opens the dialog can be stale; the detail payload
-  // carries the authoritative issue/PR state and should refresh local edit UI.
+  // Why: the opening list row can be stale; the detail payload has authoritative state, so refresh the local edit UI from it.
   useEffect(() => {
     if (resolvedWorkItemState) {
       setLocalState(resolvedWorkItemState)
@@ -6938,10 +6807,7 @@ export default function GitHubItemDialog({
   const error = cachedEntry?.error && !cachedEntry?.details ? cachedEntry.error : null
   const detailsLoaded = Boolean(cachedEntry?.details)
 
-  // Why: if a cross-window mutation invalidates the open drawer's entry
-  // (cachedEntry becomes undefined while workItem is still set), the main
-  // fetch effect won't re-run because its deps haven't changed. Bump a local
-  // tick so the fetch effect fires a refetch in that case.
+  // Why: if a cross-window mutation invalidates the open drawer's entry (cachedEntry undefined, fetch deps unchanged), bump a tick to force the refetch.
   const [refetchTick, setRefetchTick] = useState(0)
   useEffect(() => {
     if (workItem && detailsCacheKey && !cachedEntry) {
@@ -6953,11 +6819,7 @@ export default function GitHubItemDialog({
     if (!workItem || !effectiveRepoId || !detailsCacheKey || !canUseDetailsRepoContext) {
       return
     }
-    // Why: only clear optimistic comments when switching to a genuinely
-    // different item. When reopening the same item (close → reopen), the
-    // gh API's 60s response cache will return stale data that omits the
-    // just-posted comment — preserving the optimistic ref lets the merge
-    // logic above re-attach it to the stale response.
+    // Why: clear optimistic comments only on item switch — on reopen, gh's 60s cache omits the just-posted comment, so keep the ref to re-merge.
     if (workItem.id !== prevItemIdRef.current) {
       optimisticCommentsRef.current = []
     }
@@ -6972,9 +6834,7 @@ export default function GitHubItemDialog({
       return
     }
 
-    // Why: dedupe concurrent opens for the same key — concurrent dialogs or
-    // a rapid close→reopen must share one in-flight promise instead of
-    // racing two `gh` subprocesses against each other.
+    // Why: dedupe concurrent opens for the same key — share one in-flight promise instead of racing two `gh` subprocesses.
     const inflight: Promise<GitHubWorkItemDetails | null> =
       cached?.pending ??
       lookupGitHubWorkItemDetailsForSource({
@@ -6985,9 +6845,7 @@ export default function GitHubItemDialog({
         type: workItem.type
       })
 
-    // Why: snapshot the invalidation generation at fetch start; if the
-    // generation advances before we resolve, a mutation invalidated the
-    // entry mid-flight and we must not write a stale result back.
+    // Why: snapshot the invalidation generation; if it advances before resolve, a mid-flight mutation invalidated the entry — don't write back.
     const launchedAtGeneration = workItemDetailsCacheGeneration
 
     if (!cached?.pending) {
@@ -7004,8 +6862,7 @@ export default function GitHubItemDialog({
         const invalidatedMidFlight = workItemDetailsCacheGeneration !== launchedAtGeneration
         const prev = workItemDetailsCache.get(detailsCacheKey)
         if (invalidatedMidFlight && prev?.pending !== inflight) {
-          // Why: entry was deliberately dropped; do not recreate it. If the
-          // entry still exists (later open repopulated it) leave it alone too.
+          // Why: entry was deliberately dropped (or later repopulated) — don't recreate or touch it.
           return
         }
         // Why: null means unavailable/not found, not loaded empty content.
@@ -7036,9 +6893,7 @@ export default function GitHubItemDialog({
         if (invalidatedMidFlight && prev?.pending !== inflight) {
           return
         }
-        // Why: stale-on-error — keep cached data if we have it, drop the
-        // pending promise so the next open can retry. Only surface the
-        // blocking error when nothing is cached.
+        // Why: stale-on-error — keep cached data, drop the pending promise so next open retries; show the error only when nothing is cached.
         touchWorkItemDetailsCache(detailsCacheKey, {
           details: prev?.details ?? null,
           fetchedAt: prev?.fetchedAt ?? 0,
@@ -7071,8 +6926,7 @@ export default function GitHubItemDialog({
     if (!workItem || details?.item.reviewRequests === undefined) {
       return
     }
-    // Why: PR details can carry fresher reviewer metadata than the list row;
-    // push it back so the Tasks review chip doesn't keep a stale snapshot.
+    // Why: PR details can carry fresher reviewer metadata than the list row; push it back so the Tasks review chip isn't stale.
     onReviewRequestsChange?.(
       { id: workItem.id, repoId: workItem.repoId },
       details.item.reviewRequests
@@ -7086,8 +6940,7 @@ export default function GitHubItemDialog({
   const filesUnavailable = details?.filesUnavailable ?? false
   const checks = details?.checks ?? []
   const [pendingViewedPaths, setPendingViewedPaths] = useState<Set<string>>(() => new Set())
-  // Why: clipboard IPC can resolve after the dialog unmounts; skip copied-state
-  // feedback instead of starting its reset timer on a stale surface.
+  // Why: clipboard IPC can resolve after unmount; skip copied-state feedback rather than start a reset timer on a stale surface.
   const linkCopyMountedRef = useRef(false)
   const linkCopiedResetTimerRef = useRef<number | null>(null)
   const clearLinkCopiedResetTimer = useCallback((): void => {
@@ -7101,8 +6954,7 @@ export default function GitHubItemDialog({
     (node: HTMLButtonElement | null) => {
       linkCopyMountedRef.current = node !== null
       if (node === null) {
-        // Why: the copied-state timer belongs to the copy control surface;
-        // clear it when that surface detaches without a passive cleanup Effect.
+        // Why: the copied-state timer belongs to this control; clear it on detach without a passive cleanup Effect.
         clearLinkCopiedResetTimer()
       }
     },
@@ -7114,8 +6966,7 @@ export default function GitHubItemDialog({
       return
     }
     try {
-      // Why: Electron's clipboard IPC is reliable even when browser clipboard
-      // APIs lose focus/activation inside nested overlay surfaces.
+      // Why: Electron clipboard IPC works even when browser clipboard APIs lose focus/activation in nested overlays.
       await window.api.ui.writeClipboardText(workItem.url)
       if (!linkCopyMountedRef.current) {
         return
@@ -7138,15 +6989,9 @@ export default function GitHubItemDialog({
   const appendOptimisticComment = useCallback(
     (comment: PRComment) => {
       useAppStore.getState().recordFeatureInteraction('github-tasks')
-      // Why: skip refreshDetails() — gh api --cache 60s returns stale data
-      // that overwrites the optimistic comment. The next dialog open (after
-      // cache expiry) will pick up the server-confirmed version.
+      // Why: skip refreshDetails() — gh's 60s cache would overwrite the optimistic comment; next open picks up the server version.
       optimisticCommentsRef.current.push(comment)
-      // Why: write through the module-level cache so subscribers (this
-      // drawer plus any concurrent ones on the same item) re-render with the
-      // optimistic comment. Mark fetchedAt as stale (0) so the next open
-      // still triggers a background refresh to pick up server-side fields
-      // like reaction groups or thread bindings.
+      // Why: write through the module cache so concurrent drawers re-render; mark fetchedAt stale (0) so next open refetches server fields.
       if (detailsCacheKey) {
         const prev = workItemDetailsCache.get(detailsCacheKey)
         if (prev?.details) {
@@ -7164,10 +7009,7 @@ export default function GitHubItemDialog({
           }
         }
       }
-      // Why: when the cache has no details yet (still loading), no cache
-      // write/notify fires above. Bump local state so the details memo
-      // re-runs and surfaces the optimistic comment via the loading-shell
-      // fallback instead of holding it invisibly in the ref.
+      // Why: no cache write fires while details are still loading; bump local state so the memo re-runs and shows the optimistic comment.
       setOptimisticTick((n) => n + 1)
     },
     [detailsCacheKey]
@@ -7177,8 +7019,7 @@ export default function GitHubItemDialog({
     if (!workItem) {
       return
     }
-    // Why: local repos can invalidate every source-preference variant; runtime-only
-    // entries need their exact source-scoped key because there is no local path.
+    // Why: local repos invalidate all source-pref variants; runtime-only entries need their exact source-scoped key (no local path).
     if (repoPath) {
       invalidateWorkItemDetailsCacheByMatch({
         repoPath,
@@ -7350,8 +7191,7 @@ export default function GitHubItemDialog({
                 <span className="ml-2 font-light text-muted-foreground">#{workItem.number}</span>
               </h1>
               <div className="flex shrink-0 items-center gap-2">
-                {/* Why: Orca's signature affordance — keep this primary so it
-                    stands out against GitHub's familiar surface. */}
+                {/* Why: Orca's signature affordance — keep primary so it stands out against GitHub's familiar surface. */}
                 {issueAttachedWorkspace ? (
                   <DropdownMenu modal={false}>
                     <ButtonGroup>
@@ -7609,9 +7449,7 @@ export default function GitHubItemDialog({
           <div className="px-4 py-6 text-[12px] text-destructive">{error}</div>
         ) : isIssuePage ? (
           <div className="h-full min-h-0 overflow-y-auto scrollbar-sleek bg-background">
-            {/* Why: match the header's full content width — property columns sit
-                above the body so the description is not squeezed by a right rail.
-                Outer px-2 + ConversationTab px-4 totals the header's px-6. */}
+            {/* Why: full content width so the description isn't squeezed by a right rail; px-2 + ConversationTab px-4 = header px-6. */}
             <div className="w-full px-2 py-6">
               {(canUseDetailsRepoContext || projectOrigin) && (
                 <div className="mb-5 border-b border-border/60 px-4 pb-5">
@@ -7782,8 +7620,7 @@ export default function GitHubItemDialog({
                         <LoaderCircle className="size-5 animate-spin text-muted-foreground" />
                       </div>
                     ) : filesUnavailable && files.length === 0 ? (
-                      // Why: the file fetch failed (rate limit, auth, unresolved
-                      // remote); offer a retry instead of implying the PR is empty.
+                      // Why: file fetch failed (rate limit, auth, unresolved remote); offer a retry instead of implying the PR is empty.
                       <div className="flex flex-col items-center gap-3 px-4 py-10 text-center">
                         <div className="text-[12px] text-muted-foreground">
                           {translate(
@@ -7830,8 +7667,7 @@ export default function GitHubItemDialog({
   ) : null
 
   return (
-    // Why: GitHub item details render inline (not a Radix dialog), so e2e needs a
-    // stable hook to scope assertions to this detail surface.
+    // Why: rendered inline (not a Radix dialog), so e2e needs a stable hook to scope assertions to this detail surface.
     <div
       data-testid="github-item-detail"
       className="flex h-full min-h-0 flex-col overflow-hidden rounded-md border border-border/50 bg-background shadow-sm"
diff --git a/src/renderer/src/components/NewWorkspaceComposerCard.tsx b/src/renderer/src/components/NewWorkspaceComposerCard.tsx
index 238360230f2..c952431a5ba 100644
--- a/src/renderer/src/components/NewWorkspaceComposerCard.tsx
+++ b/src/renderer/src/components/NewWorkspaceComposerCard.tsx
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: this component intentionally keeps the full
-composer card markup together so the inline and modal variants share one UI
-surface without splitting the controlled form into hard-to-follow fragments. */
+/* eslint-disable max-lines -- Why: keep the full composer card markup together so the inline and modal variants share one UI surface. */
 import React from 'react'
 import { createPortal } from 'react-dom'
 import { useTranslation } from 'react-i18next'
@@ -155,8 +153,7 @@ type NewWorkspaceComposerCardProps = {
   sparseSelectedPresetId: string | null
   onSparseSelectPreset: (preset: SparsePreset | null) => void
   sparseControlsEnabled?: boolean
-  /** When set, "Add project" opens a host-provided flow (e.g. a nested dialog
-   *  over the composer modal) instead of swapping the store's active modal. */
+  /** When set, "Add project" opens a host-provided flow instead of swapping the store's active modal. */
   onAddProjectOverride?: () => void
 }
 
@@ -273,8 +270,7 @@ function HostPathTooltip({ path }: { path: string }): React.JSX.Element {
         return
       }
       const rect = trigger.getBoundingClientRect()
-      // Why: anchor directly under the hovered path line (left-aligned to it), and cap the width to
-      // the space remaining to the viewport edge so a long path wraps instead of flying off-screen.
+      // Why: anchor under the hovered path, capping width to the viewport edge so a long path wraps instead of flying off-screen.
       const left = Math.max(HOST_PATH_TOOLTIP_VIEWPORT_GAP_PX, rect.left)
       setPosition({
         left,
@@ -430,8 +426,7 @@ function WorkspaceRunTargetCombobox({
             {recipes.length > 0 ? (
               <Popover open={vmRecipesOpen} onOpenChange={setVmRecipesOpen}>
                 <PopoverTrigger asChild>
-                  {/* Why: a real CommandItem (not a raw button) so cmdk registers it — fixes the row
-                      only rendering under the first host, the uneven height, and the double-highlight. */}
+                  {/* Why: a real CommandItem (not a raw button) so cmdk registers it — fixes missing rows, uneven height, and double-highlight. */}
                   <CommandItem
                     value="per-workspace-env"
                     onSelect={() => setVmRecipesOpen(true)}
@@ -446,8 +441,7 @@ function WorkspaceRunTargetCombobox({
                     <Cloud className="size-3.5 shrink-0 text-muted-foreground" />
                     <div className="min-w-0 flex-1">
                       <div className="truncate text-sm">{ephemeralVmLabel}</div>
-                      {/* Why: a second line so this row matches the two-line height of the host
-                          options above, and to hint what choosing it opens. */}
+                      {/* Why: a second line so this row matches the two-line host options above and hints what it opens. */}
                       <div className="mt-0.5 truncate text-[11px] text-muted-foreground">
                         {translate(
                           'auto.components.NewWorkspaceComposerCard.perWorkspaceEnvHint',
@@ -563,9 +557,7 @@ function useComposerFileDragOver(): {
   }, [])
 
   const onDragEnter = React.useCallback((event: React.DragEvent<HTMLDivElement>): void => {
-    // Why: "Files" is the DataTransfer type the OS adds for native file drags;
-    // internal in-app drags must not trigger the
-    // attachment-drop highlight so they still route to their own handlers.
+    // Why: "Files" is the DataTransfer type the OS adds for native drags; skip internal drags so they route to their own handlers.
     if (!event.dataTransfer.types.includes('Files')) {
       return
     }
@@ -581,10 +573,7 @@ function useComposerFileDragOver(): {
       if (!event.dataTransfer.types.includes('Files')) {
         return
       }
-      // Why: mirror the onDragEnter guard so internal in-app drags (which may
-      // carry both "Files" and the workspace path MIME type) don't decrement
-      // the counter when enter skipped incrementing it — otherwise the counter
-      // goes negative and the native-drag highlight state desyncs.
+      // Why: mirror the onDragEnter guard so internal drags don't decrement a counter enter skipped incrementing (else it goes negative).
       if (event.dataTransfer.types.includes(WORKSPACE_FILE_PATH_MIME)) {
         return
       }
@@ -596,10 +585,7 @@ function useComposerFileDragOver(): {
     [reset]
   )
 
-  // Why: the preload bridge calls stopPropagation on native `drop` events so
-  // React's onDrop never fires on the composer card. Listen at the document
-  // level (also capture-phase) to reset the drag highlight whenever any drop
-  // or dragend occurs anywhere in the window.
+  // Why: preload stops native drop events before React's onDrop, so reset the drag highlight via a document capture listener.
   React.useEffect(() => {
     const handler = (): void => {
       reset()
@@ -701,8 +687,7 @@ export default function NewWorkspaceComposerCard({
   sparseControlsEnabled = true,
   onAddProjectOverride
 }: NewWorkspaceComposerCardProps): React.JSX.Element {
-  // Why: this form uses the lightweight translate() helper directly; subscribe
-  // so an already-open create dialog repaints when the UI language changes.
+  // Why: subscribe (form uses translate() directly) so an open create dialog repaints when the UI language changes.
   useTranslation()
   const { isFileDragOver, dragHandlers } = useComposerFileDragOver()
   const openModal = useAppStore((s) => s.openModal)
@@ -753,8 +738,7 @@ export default function NewWorkspaceComposerCard({
         ? 'Run commands now'
         : 'Run setup now'
   const setupSkipButtonLabel = setupConfig?.kind === 'setup' ? 'Skip for now' : 'Skip commands'
-  // Why: defaultTabs launch commands can be long-running too, but they are not
-  // the setup command this setting gates agent startup on.
+  // Why: defaultTabs launch commands can run long too, but aren't the setup command this setting gates agent startup on.
   const showSetupAgentStartupPolicy =
     setupControlsEnabled && setupConfig !== null && setupConfig.kind !== 'default-tabs'
 
@@ -788,9 +772,7 @@ export default function NewWorkspaceComposerCard({
   )
 
   const focusNameInput = React.useCallback(() => {
-    // Why: after the repo picker commits a choice, moving focus to the name
-    // field keeps the keyboard flow progressing through the form instead of
-    // trapping the user in the repo popover interaction.
+    // Why: move focus to the name field after the repo pick so keyboard flow continues instead of trapping in the repo popover.
     cancelNameInputFocusFrame()
     nameInputFocusFrameRef.current = requestAnimationFrame(() => {
       nameInputFocusFrameRef.current = null
@@ -812,8 +794,7 @@ export default function NewWorkspaceComposerCard({
   }, [detectedAgentIds, disabledTuiAgents])
 
   const handleAddRepo = React.useCallback((): void => {
-    // Why: inside the composer modal, swapping activeModal would abruptly
-    // unmount the composer; the override layers Add Project on top instead.
+    // Why: swapping activeModal would unmount the composer, so the override layers Add Project on top instead.
     if (onAddProjectOverride) {
       onAddProjectOverride()
       return
@@ -835,8 +816,7 @@ export default function NewWorkspaceComposerCard({
     event.preventDefault()
     event.stopPropagation()
     const textarea = event.currentTarget
-    // Why: large note pastes need one controlled owner so React receives a
-    // single final input event after chunked DOM insertion.
+    // Why: large note pastes need one controlled owner so React gets a single final input event after chunked DOM insertion.
     void pasteTextIntoTextControl(textarea, text, {
       source: 'clipboard',
       canContinue: (target) => target.ownerDocument.activeElement === target
@@ -877,11 +857,7 @@ export default function NewWorkspaceComposerCard({
     <div
       ref={setComposerNode}
       data-workspace-composer-root="true"
-      // Why: preload classifies native OS file drops by the nearest
-      // `data-native-file-drop-target` marker in the composedPath. Tagging
-      // the composer root makes drops anywhere on the card route to the
-      // composer attachment handler instead of falling back to the default
-      // editor-open behavior.
+      // Why: preload routes native file drops by the nearest data-native-file-drop-target marker, so tag the root to catch card-wide drops.
       data-native-file-drop-target="composer"
       onDragEnter={dragHandlers.onDragEnter}
       onDragLeave={dragHandlers.onDragLeave}
@@ -931,10 +907,7 @@ export default function NewWorkspaceComposerCard({
               projectPlaceholder ??
               translate('auto.components.NewWorkspaceComposerCard.dccd26d4e4', 'Choose project')
             }
-            // Why: programmatic .focus() does not reliably trigger
-            // :focus-visible in Chromium. Mirror the Input component's
-            // standard ring (border-ring + ring-ring/50, 3px) onto :focus so
-            // keyboard navigation paints the familiar field ring.
+            // Why: programmatic .focus() doesn't reliably trigger :focus-visible in Chromium, so mirror the Input ring onto :focus.
             triggerClassName="h-9 w-full border-input text-sm focus:border-ring focus:ring-[3px] focus:ring-ring/50"
             invalid={Boolean(projectError)}
             describedBy={projectDescriptionId}
@@ -1052,9 +1025,7 @@ export default function NewWorkspaceComposerCard({
             crossRepoSwitchTarget={smartNameRepoSwitchTarget}
             onActiveSourceModeChange={onSmartNameModeChange}
             onPlainEnter={() => {
-              // Why: Enter on the workspace name advances focus to the next
-              // field (Agent combobox) rather than submitting, letting the user
-              // progress through the form with just the keyboard.
+              // Why: Enter advances focus to the Agent combobox rather than submitting, keeping keyboard flow through the form.
               const root = composerRef?.current
               const agentTrigger = root?.querySelector<HTMLElement>(
                 '[data-agent-combobox-root="true"][role="combobox"]'
@@ -1068,13 +1039,7 @@ export default function NewWorkspaceComposerCard({
               <span>{forkPushWarning}</span>
             </p>
           ) : null}
-          {/* Why (#5181): sits right under the branch selection (not the Name
-              field, which can differ from the branch) so reusing the picked
-              branch is an explicit, discoverable choice. Stays mounted and
-              collapses via a grid-rows transition (matching the Advanced
-              drawer) so the dialog grows/shrinks smoothly as the option
-              appears. Only offered when reuse is possible — an existing local
-              branch not already checked out in another worktree. */}
+          {/* Why (#5181): sits under the branch selection (not Name, which can differ) so reusing the picked branch is an explicit choice. */}
           <div
             className={cn(
               'grid overflow-hidden transition-[grid-template-rows] duration-200 ease-out',
@@ -1104,9 +1069,7 @@ export default function NewWorkspaceComposerCard({
                     type="checkbox"
                     checked={reuseSelectedBranch}
                     onChange={(event) => onReuseSelectedBranchChange(event.target.checked)}
-                    // Why: while collapsed the row is aria-hidden, so disable the
-                    // input too — keeps a hidden control out of the tab order and
-                    // fully inert (no focusable control inside an aria-hidden tree).
+                    // Why: row is aria-hidden while collapsed, so disable the input too (no focusable control inside an aria-hidden tree).
                     disabled={!canReuseSelectedBranch}
                     className="sr-only"
                   />
@@ -1140,9 +1103,7 @@ export default function NewWorkspaceComposerCard({
                   variant="ghost"
                   size="icon-xs"
                   onClick={onOpenAgentSettings}
-                  // Why: keep Tab flow Name → Agent combobox. This settings
-                  // shortcut is a detour; making it tabbable forces a keystroke
-                  // on every workspace creation.
+                  // Why: keep Tab flow Name → Agent; tabIndex=-1 so this settings detour doesn't add a keystroke to every creation.
                   tabIndex={-1}
                   className="size-5 shrink-0 rounded-sm text-muted-foreground hover:text-foreground"
                   aria-label={translate(
@@ -1173,9 +1134,7 @@ export default function NewWorkspaceComposerCard({
           />
         </div>
 
-        {/* Why: Advanced is a disclosure header, so keep it visually grouped
-            with the content or footer below it while preserving normal spacing
-            from the Agent field above. */}
+        {/* Why: keep the Advanced disclosure header grouped with the content below while preserving spacing from the Agent field above. */}
         <div className="!mb-2">
           <Button
             type="button"
@@ -1200,10 +1159,7 @@ export default function NewWorkspaceComposerCard({
           aria-hidden={!advancedOpen}
         >
           <div className="min-h-0">
-            {/* Why: px-1 insets the content 4px on each side so the Note
-                textarea's 3px outset focus ring has horizontal breathing room
-                inside the overflow-hidden drawer above. Without it the ring
-                gets clipped on the right edge when the field is focused. */}
+            {/* Why: px-1 gives the Note textarea's 3px outset focus ring breathing room so the overflow-hidden drawer doesn't clip it. */}
             <div
               className={cn(
                 'space-y-4 px-1 pt-1 pb-3 transition-[opacity,transform] duration-150 ease-out',
@@ -1213,12 +1169,7 @@ export default function NewWorkspaceComposerCard({
               )}
             >
               {smartNameSelection ? (
-                // Why: when a source (PR/issue/Linear/Jira/branch) is picked the
-                // smart field shows a pill instead of an editable name, so
-                // surface the auto-derived workspace name here under Advanced
-                // where it can be reviewed/overridden. When the user typed an
-                // explicit name there's no source pill — the smart input is
-                // already the name field, so we don't duplicate it here.
+                // Why: with a source pill the smart field isn't editable, so surface the derived name here; a typed name already is the name field.
                 <div className="space-y-1">
                   <label className="text-xs font-medium text-muted-foreground">
                     {translate('auto.components.NewWorkspaceComposerCard.2688050e4b', 'Name')}
@@ -1236,11 +1187,7 @@ export default function NewWorkspaceComposerCard({
                 </div>
               ) : null}
 
-              {/* Why: only offer a manual branch name when creating from a
-                  typed name or a base branch. When a tracked work item (PR/
-                  issue/MR/Linear) is the source, the branch is derived from
-                  that item — a linked GitHub PR even re-resolves it at submit —
-                  so an override typed here would be silently ignored. */}
+              {/* Why: for a tracked work item (PR/issue/MR/Linear) the branch is derived from the item, so a manual override here would be silently ignored. */}
               {selectedRepoIsGit &&
               branchesEnabled &&
               (!smartNameSelection || smartNameSelection.kind === 'branch') ? (
@@ -1277,9 +1224,7 @@ export default function NewWorkspaceComposerCard({
                   onChange={(event) => onNoteChange(event.target.value)}
                   onPaste={handleNotePaste}
                   onInput={(event) => {
-                    // Why: start at one-line height, grow to fit content so a short
-                    // note keeps the dialog compact while longer notes get room to
-                    // breathe without a scroll bar until the max-h clamps growth.
+                    // Why: reset then size to content so short notes stay compact and long ones grow without a scrollbar until max-h clamps.
                     const ta = event.currentTarget
                     ta.style.height = 'auto'
                     ta.style.height = `${ta.scrollHeight}px`
@@ -1317,9 +1262,7 @@ export default function NewWorkspaceComposerCard({
                     </span>
                   </div>
 
-                  {/* Why: `orca.yaml` is the committed source of truth for shared setup,
-                      so the preview reconstructs the real YAML shape instead of showing a raw
-                      shell blob that hides where the command came from. */}
+                  {/* Why: `orca.yaml` is the committed source of truth, so the preview reconstructs the real YAML shape rather than a raw shell blob. */}
                   <SetupCommandPreview
                     setupConfig={setupConfig}
                     headerAction={
diff --git a/src/renderer/src/components/PullRequestPage.tsx b/src/renderer/src/components/PullRequestPage.tsx
index 8cd3f872974..11cd506a7e6 100644
--- a/src/renderer/src/components/PullRequestPage.tsx
+++ b/src/renderer/src/components/PullRequestPage.tsx
@@ -223,12 +223,7 @@ import {
 import { translate } from '@/i18n/i18n'
 import { getSettingsForRepoRuntimeOwner } from '@/lib/repo-runtime-owner'
 
-// Why: the GH item dialog can be opened from any work-item list surface and
-// doesn't have the full owner/repo context the list's cache entry carries.
-// Parsing the canonical `https://github.com/{owner}/{repo}/...` URL is the
-// simplest reliable source — the URL is already present on every work item
-// and survives the main-process → IPC boundary. Non-GitHub hosts return null,
-// which matches the indicator's suppression rule.
+// Why: the item URL is the only owner/repo source present on every work item across the IPC boundary; non-GitHub hosts return null (matching the indicator's suppression).
 function parseOwnerRepoFromItemUrl(url: string): GitHubOwnerRepo | null {
   try {
     const parsed = new URL(url)
@@ -286,13 +281,7 @@ function normalizeItemDialogTab(
   return tab ?? 'conversation'
 }
 
-/** Why: Project-origin rows don't always belong to the active local repo.
- *  When set, GHEditSection routes label/assignee/state mutations through
- *  slug-addressed IPCs against `owner`/`repo` instead of through `repoPath`,
- *  preventing edits from silently landing on the workspace's repo when the
- *  Project view is showing rows from a different repo. See
- *  docs/design/github-project-view-tasks.md §Dialog editing from Project rows.
- */
+/** When set, GHEditSection routes label/assignee/state edits through slug-addressed IPCs (owner/repo) instead of `repoPath`, so Project rows from another repo aren't edited on the workspace repo. See docs/design/github-project-view-tasks.md. */
 export type PullRequestPageProjectOrigin = {
   owner: string
   repo: string
@@ -317,11 +306,7 @@ type PullRequestPageProps = {
     reviewRequests: GitHubAssignableUser[]
   ) => void
   onClose: () => void
-  /** Optional Project-origin context. When set, edits in the dialog are
-   *  routed via slug-addressed mutation IPCs against the row's actual repo
-   *  instead of the active workspace's `repoPath`. Both can be set
-   *  simultaneously (Project mode where the row also lives in the active
-   *  workspace) — slug routing wins for writes. */
+  /** Optional Project-origin context; when set, slug-addressed IPCs route writes to the row's repo instead of `repoPath` (both may be set — slug wins for writes). */
   projectOrigin?: PullRequestPageProjectOrigin
 }
 
@@ -549,8 +534,7 @@ function PRAssigneesPanel({
   )
   const { isPending, run } = useImmediateMutation()
 
-  // Why: PR assignees can change through background refetches; sync them
-  // before paint so the right rail never shows a stale reviewer/assignee split.
+  // Why: sync assignees before paint (background refetches change them) so the right rail never shows a stale split.
   if (
     assigneesSource.itemId !== item.id ||
     assigneesSource.repoId !== item.repoId ||
@@ -812,8 +796,7 @@ function PRReviewersPanel({
     }
   }, [cancelReviewerInputFocusFrame])
 
-  // Why: reviewer edits are optimistic, but item switches/refetches must clear
-  // stale local requests before paint; a passive Effect leaves one stale render.
+  // Why: clear stale optimistic review requests before paint on item switch/refetch (a passive Effect leaves one stale render).
   if (
     reviewRequestsSource.itemId !== item.id ||
     reviewRequestsSource.repoId !== item.repoId ||
@@ -1428,13 +1411,7 @@ function isPRFileViewed(file: GitHubPRFile): boolean {
   return file.viewerViewedState === 'VIEWED'
 }
 
-// Why: SWR cache for the work-item details fetch. Reopening the same drawer
-// pays full IPC + `gh` process startup latency without this; with it, cached
-// data paints immediately while a background refetch keeps the view honest.
-// Cache is keyed by repoPath + issueSourcePreference + type + number so
-// upstream/origin source toggles and issue#N vs pr#N never collide. Bounded
-// to ~50 entries to cap memory; entries older than FRESH_MS trigger a
-// background refetch on open. See docs/gh-work-item-drawer-cache.md.
+// SWR cache: reopening a drawer paints cached data instantly while a background refetch reconciles. See docs/gh-work-item-drawer-cache.md.
 const WORK_ITEM_DETAILS_CACHE_MAX = 50
 const WORK_ITEM_DETAILS_FRESH_MS = 30_000
 const WORK_ITEM_DETAILS_UNAVAILABLE_MESSAGE = 'Unable to load details for this GitHub item.'
@@ -1446,10 +1423,7 @@ type WorkItemDetailsCacheEntry = {
 }
 const workItemDetailsCache = new Map<string, WorkItemDetailsCacheEntry>()
 
-// Why: drawers subscribe via useSyncExternalStore so reopening a cached item
-// paints synchronously on first render. Stability of the snapshot relies on
-// every cache write replacing the entry object identity (delete+set), which
-// touchWorkItemDetailsCache already does.
+// Why: useSyncExternalStore snapshot stability relies on every cache write replacing the entry object identity (delete+set).
 const workItemDetailsCacheListeners = new Set<() => void>()
 function subscribeWorkItemDetailsCache(listener: () => void): () => void {
   workItemDetailsCacheListeners.add(listener)
@@ -1471,8 +1445,7 @@ function getWorkItemDetailsCacheKey(args: {
   type: 'issue' | 'pr'
   number: number
 }): string {
-  // Why: include all axes that change which (repo, item) the IPC resolves to.
-  // `\0` separator avoids ambiguity between fields that may contain `:` or `/`.
+  // Why: `\0` separator avoids collisions between key fields that may contain `:` or `/`.
   const keyParts = args.sourceCacheScope
     ? [args.repoId, args.sourceCacheScope, args.issueSourcePreference ?? 'auto', args.type]
     : [args.repoId, args.issueSourcePreference ?? 'auto', args.type]
@@ -1480,8 +1453,7 @@ function getWorkItemDetailsCacheKey(args: {
 }
 
 function touchWorkItemDetailsCache(key: string, entry: WorkItemDetailsCacheEntry): void {
-  // Why: re-insert to move to MRU position; Map preserves insertion order so
-  // the oldest key is always first when evicting.
+  // Why: re-insert moves the key to MRU; Map insertion order keeps the oldest key first when evicting.
   workItemDetailsCache.delete(key)
   workItemDetailsCache.set(key, entry)
   while (workItemDetailsCache.size > WORK_ITEM_DETAILS_CACHE_MAX) {
@@ -1494,12 +1466,9 @@ function touchWorkItemDetailsCache(key: string, entry: WorkItemDetailsCacheEntry
   notifyWorkItemDetailsCache()
 }
 
-// Why: exposed so mutation handlers (in this file and elsewhere) can drop a
-// stale entry after a successful local mutation. Cross-window invalidation
-// arrives via the `gh:workItemMutated` event listener installed below.
+// Exposed so mutation handlers can drop a stale entry after a local mutation (cross-window invalidation arrives via the `gh:workItemMutated` listener below).
 export function invalidateWorkItemDetailsCacheForKey(key: string): void {
-  // Why: bump generation so an in-flight fetch launched before this exact-key
-  // invalidation will not write its stale result back into the cache.
+  // Why: bump generation so an in-flight fetch launched before this invalidation won't write its stale result back.
   workItemDetailsCacheGeneration += 1
   const existed = workItemDetailsCache.delete(key)
   if (existed) {
@@ -1507,16 +1476,10 @@ export function invalidateWorkItemDetailsCacheForKey(key: string): void {
   }
 }
 
-// Why: monotonically increases on every invalidation so an in-flight refetch
-// that started before a mutation can detect that its result is stale and
-// must not be written back. Without this, a mutation that lands while a
-// refetch is in flight would have its invalidation silently undone when the
-// stale promise resolves and re-populates the entry.
+// Why: monotonic counter so an in-flight refetch that started before a mutation detects its result is stale and skips the write-back.
 let workItemDetailsCacheGeneration = 0
 
-// Why: when we don't have the exact cache key (e.g. an event from another
-// window only carries repoPath + number + type), drop every entry that
-// matches the (repoPath, type, number) tuple regardless of source preference.
+// Why: without the exact key (cross-window events carry only repoPath+number+type), drop every entry matching that tuple regardless of source preference.
 function invalidateWorkItemDetailsCacheByMatch(args: {
   repoPath: string
   repoId?: string
@@ -1612,11 +1575,7 @@ function patchCachedWorkItemBody(cacheKey: string, body: string): void {
   })
 }
 
-// Why: install once at module load — every dialog instance shares the cache,
-// so a single subscription is enough. Main targets the registered app renderer
-// for non-origin mutations, and this listener invalidates the matching entry.
-// We track the unsubscribe so
-// Vite HMR doesn't accumulate listeners across module reloads in dev.
+// Install once at module load (all dialogs share the cache); track the unsubscribe so Vite HMR doesn't accumulate listeners across reloads.
 let workItemMutatedUnsub: (() => void) | undefined
 let workItemDetailsCacheEventUnsub: (() => void) | undefined
 if (typeof window !== 'undefined' && window.api?.gh?.onWorkItemMutated) {
@@ -1639,11 +1598,9 @@ if (typeof import.meta !== 'undefined' && import.meta.hot) {
   })
 }
 
-// Why: bounded LRU — opening many PRs with many files during a session
-// would otherwise grow this module-level map without bound until reload.
+// Why: bounded LRU so a session of opening many PR files can't grow this module map without bound.
 const PR_FILE_CONTENT_CACHE_MAX = 64
-// Why: raw-content overflow is only a sentinel; force the reported size past
-// the render budget so downstream checks reliably choose fallback mode.
+// Why: overflow sentinel — force reported size past the render budget so downstream reliably picks fallback mode.
 const GITHUB_PR_RAW_CONTENT_OVERFLOW_CHARACTER_COUNT = MAX_RENDERED_DIFF_COMBINED_CHARACTERS + 1
 const PR_FILE_CONTENT_CACHE_MAX_BYTES = MAX_RENDERED_DIFF_COMBINED_CHARACTERS * 4
 type PRFileContentCacheEntry = {
@@ -1709,8 +1666,7 @@ function touchPRFileContentCache(
 
   const existing = prFileContentCache.get(key)
   prFileContentCacheBytes -= existing?.byteCount ?? 0
-  // Why: re-insert to move to the most-recently-used position; Map preserves
-  // insertion order so the oldest key is always first when evicting.
+  // Why: re-insert moves the key to MRU; Map insertion order makes the oldest key first when evicting.
   prFileContentCache.delete(key)
   const byteCount = retainedByteCount
   prFileContentCache.set(key, { value, byteCount })
@@ -2270,8 +2226,7 @@ function PRFilesCombinedDiffViewer({
   const inlineReviewComments = useMemo<DecoratedDiffComment[]>(
     () =>
       comments.flatMap((comment): DecoratedDiffComment[] => {
-        // Why: stale threads keep originalLine for the sidebar, but rendering
-        // that number inline can attach the comment to unrelated current code.
+        // Why: outdated threads keep originalLine for the sidebar, but rendering it inline can attach the comment to unrelated current code.
         if (comment.isOutdated || !comment.path || typeof comment.line !== 'number') {
           return []
         }
@@ -2329,8 +2284,7 @@ function PRFilesCombinedDiffViewer({
   sectionsRef.current = sections
 
   useEffect(() => {
-    // Why: even cached restores represent a new PR/file generation; stale async
-    // diff loads from the previous view must not patch the restored sections.
+    // Why: bump generation so stale async diff loads from the previous view can't patch the restored sections.
     generationRef.current += 1
     const cached = prFilesDiffViewStateCache.get(viewStateKey)
     if (cached && cached.entrySignature === entrySignature) {
@@ -2929,8 +2883,7 @@ function CommentCodeContext({
     comment.id
   )
   if (resolvedContextExpansionState !== contextExpansionState) {
-    // Why: comment rows can be reused when a PR refreshes; reset before paint
-    // so expanded context from the previous comment is never shown on the next.
+    // Why: rows are reused across PR refreshes; reset before paint so the previous comment's expanded context isn't shown on the next.
     setContextExpansionState(resolvedContextExpansionState)
   }
   const contextBefore = resolvedContextExpansionState.contextBefore
@@ -3269,15 +3222,13 @@ function ConversationTab({
   }, [])
 
   if (resolvedReplyingTo !== replyingTo) {
-    // Why: comment filters/refetches can hide the active reply target; clear it
-    // before paint so a stale composer does not flash for the wrong comment set.
+    // Why: clear before paint when filters/refetches hide the reply target, so a stale composer doesn't flash for the wrong comment set.
     setReplyingTo(resolvedReplyingTo)
   }
 
   const resolvedBodyDraft = resolveGitHubBodyDraft(bodyDraft, body, bodyEditing)
   if (shouldSyncGitHubBodyDraft(bodyDraft, body, bodyEditing)) {
-    // Why: background detail refreshes can change the body while the editor is
-    // closed; reconcile before paint so reopening never sees a stale draft.
+    // Why: reconcile before paint so a background body refresh while the editor is closed doesn't show a stale draft on reopen.
     setBodyDraft(resolvedBodyDraft)
   }
 
@@ -3620,9 +3571,7 @@ function ConversationTab({
     <div
       className={cn(
         'grid min-w-0 gap-5 px-4 py-4',
-        // Why: the drawer expands nearly full-width on narrow app windows, so
-        // keep PR controls beside the conversation instead of hiding them below
-        // long review threads.
+        // Why: on narrow windows the drawer is near full-width, so keep PR controls beside the conversation, not below long threads.
         item.type === 'pr' && 'grid-cols-[minmax(0,1fr)_300px]'
       )}
     >
@@ -4373,8 +4322,7 @@ function getChecksSummaryLabel(checks: PRCheckDetail[]): string {
   if (counts.failing > 0) {
     return `${counts.failing} ${counts.failing === 1 ? 'check' : 'checks'} failing`
   }
-  // Why: action_required (e.g. a workflow awaiting approval) blocks merge but is
-  // not a failure; call it out distinctly so users know a manual step is needed.
+  // Why: action_required (e.g. workflow awaiting approval) blocks merge but isn't a failure, so surface it distinctly.
   if (counts.needsAction > 0) {
     return `${counts.needsAction} ${counts.needsAction === 1 ? 'check needs' : 'checks need'} action`
   }
@@ -4443,8 +4391,7 @@ function ChecksTab({
   const mountedRef = useMountedRef()
   const resolvedChecksState = resolveGitHubChecksTabState(checksState, checks)
   if (resolvedChecksState !== checksState) {
-    // Why: parent check refreshes replace the source list; clear local refresh
-    // and inline detail state before stale rows/details can paint.
+    // Why: reconcile before paint when a parent check refresh replaces the source list, so stale rows/details never show.
     setChecksState(resolvedChecksState)
   }
   const { localChecks, expandedCheckKey, detailsByCheckKey } = resolvedChecksState
@@ -5518,16 +5465,10 @@ function MentionTextarea({
   )
 }
 
-// Why: when the dialog opens for a Project row whose repo differs from the
-// active workspace, mutations must target the row's actual repo via
-// slug-addressed IPCs. Otherwise edits silently apply to the workspace's
-// repo. The edit IPCs return a structured `{ ok, error }` shape; we adapt
-// to a thrown rejection so the existing `useImmediateMutation` flow
-// (which expects throws on failure) continues to work unchanged.
+// Why: Project-row mutations must target the row's repo via slug-addressed IPCs, else edits silently apply to the active workspace's repo.
 function getGitHubMutationSettings(repoId: string | null | undefined) {
   const state = useAppStore.getState()
-  // Why: project-origin mutations are slug-addressed, but when we know the
-  // backing repo id they must still execute on that repo's owner host.
+  // Why: slug-addressed project-origin mutations must still run on the backing repo's owner host when we know its id.
   return getSettingsForRepoRuntimeOwner(state, repoId ?? null)
 }
 
@@ -5797,9 +5738,7 @@ function GHEditSection({
   localLabels: string[]
   onStateChange: (state: GitHubWorkItem['state']) => void
   onLabelsChange: (labels: string[]) => void
-  /** Why: called after a successful issue mutation so the parent dialog can
-   *  invalidate its work-item-details cache entry. Without this, reopening the
-   *  drawer in the FRESH_MS window would paint pre-mutation data. */
+  /** Called after a successful issue mutation so the parent can invalidate its details cache; otherwise a reopen within FRESH_MS paints pre-mutation data. */
   onMutated: () => void
   assignees: string[]
   onUse: (item: GitHubWorkItem) => void
@@ -5825,11 +5764,7 @@ function GHEditSection({
     [repoOwnerSettings, sourceContext]
   )
   const { isPending, run } = useImmediateMutation()
-  // Why: when the dialog opens from a Project view, mutations route through
-  // *BySlug IPCs and we must keep `projectViewCache` in sync alongside
-  // `workItemsCache` — `patchWorkItem` only walks the latter, so without this
-  // helper the Project table would render stale data until manual refresh.
-  // See docs/design/github-project-view-tasks.md §Dialog editing from Project rows.
+  // Why: patchWorkItem only updates workItemsCache; Project-view rows also need projectViewCache patched or the table stays stale. See docs/design/github-project-view-tasks.md.
   const patchProjectRowIfNeeded = useCallback(
     (patch: Parameters<typeof patchProjectRowContent>[2]) => {
       if (!projectOrigin) {
@@ -5840,9 +5775,7 @@ function GHEditSection({
     [projectOrigin, patchProjectRowContent]
   )
 
-  // Why: when projectOrigin is set we MUST read labels/assignees from the
-  // row's repo, not from the workspace path — otherwise the popovers list
-  // values from a different repo than the writes target.
+  // Why: with projectOrigin set, read labels/assignees from the row's repo (not workspace path) so popovers match where writes target.
   const slugOwner = projectOrigin?.owner ?? null
   const slugRepo = projectOrigin?.repo ?? null
   const repoLabelsByPath = useRepoLabels(
@@ -5860,9 +5793,7 @@ function GHEditSection({
   const repoAssigneesBySlug = useRepoAssigneesBySlug(slugOwner, slugRepo, assignees, sourceSettings)
   const repoAssignees = projectOrigin ? repoAssigneesBySlug : repoAssigneesByPath
 
-  // Why: sync local assignees when item changes or when the detail fetch
-  // resolves with real data — but skip if the user already made an
-  // optimistic edit so we don't clobber in-flight changes.
+  // Why: sync local assignees on item change / detail resolve, but skip if the user made an optimistic edit so we don't clobber in-flight changes.
   useEffect(() => {
     if (editedAssigneesItemKeyRef.current === assigneesItemKey) {
       return
@@ -6004,8 +5935,7 @@ function GHEditSection({
         ? prevAssignees.filter((l) => l !== login)
         : [...prevAssignees, login]
 
-      // Why: the optimistic guard is scoped to this repo item so switching
-      // items does not suppress the next item's assignee sync.
+      // Why: scope the optimistic guard to this repo item so switching items doesn't suppress the next item's assignee sync.
       editedAssigneesItemKeyRef.current = assigneesItemKey
       if (isAssigned) {
         run('assignees', {
@@ -6331,8 +6261,7 @@ function GHCommentComposer({
       if (result.ok) {
         setBody('')
         requestAnimationFrame(autoGrow)
-        // Why: use the comment returned by GitHub so the optimistic row shows
-        // the real login/avatar immediately instead of waiting for a reopen.
+        // Why: use GitHub's returned comment so the optimistic row shows the real login/avatar without a reopen.
         onCommentAdded(result.comment)
       } else {
         toast.error(
@@ -6417,8 +6346,7 @@ function GHCommentComposer({
   )
 }
 
-// Why: the issue-source indicator is issue-only and lives on GitHubItemDialog;
-// PullRequestPage doesn't render it.
+// Note: the issue-source indicator is issue-only and lives on GitHubItemDialog, not here.
 
 export default function PullRequestPage({
   workItem,
@@ -6440,8 +6368,7 @@ export default function PullRequestPage({
   const [linkCopyState, setLinkCopyState] = useState(() => createGitHubLinkCopyState(workItemId))
   const resolvedLinkCopyState = resolveGitHubLinkCopyState(linkCopyState, workItemId)
   if (resolvedLinkCopyState !== linkCopyState) {
-    // Why: switching GitHub items should not paint a stale copied indicator
-    // from the previous item while waiting for a passive Effect pass.
+    // Why: reconcile before paint so switching items doesn't flash the previous item's copied indicator.
     setLinkCopyState(resolvedLinkCopyState)
   }
   const linkCopied = resolvedLinkCopyState.copied
@@ -6461,11 +6388,7 @@ export default function PullRequestPage({
     ? getGithubPrWorkspaceAttachmentLabel(attachedWorkspace)
     : null
 
-  // Why: the cache key has to include the issue source preference so a user
-  // toggling between origin/upstream for the same issue number doesn't read
-  // back the wrong repo's details. We pull it from the repos slice rather
-  // than threading it as a prop because every existing call site already has
-  // the repo registered in the store.
+  // Why: key must include issue source preference so origin/upstream toggles for the same issue number don't read back the wrong repo's details.
   const issueSourcePreference = useAppStore((s) => {
     if (!repoPath && !effectiveRepoId) {
       return undefined
@@ -6496,8 +6419,7 @@ export default function PullRequestPage({
     issueSourcePreference
   ])
 
-  // Why: reset lifted edit state when the dialog switches items or when the
-  // same item receives an optimistic cache patch from the surrounding table.
+  // Why: reset lifted edit state on item switch or when the same item gets an optimistic cache patch from the table.
   useEffect(() => {
     if (workItemState && workItemLabels) {
       setLocalState(workItemState)
@@ -6548,20 +6470,12 @@ export default function PullRequestPage({
     }
   }, [effectiveRepoId, handleUseWorkItem, workItem])
 
-  // Why: track comments added optimistically before the detail fetch resolves
-  // so they can be merged into the fetch result instead of being overwritten.
+  // Why: hold optimistically-added comments so they merge into the fetch result instead of being overwritten.
   const optimisticCommentsRef = useRef<PRComment[]>([])
-  // Why: track the last item we fetched so we can distinguish "reopen same
-  // item" from "switch to a different item". Reopening the same item must
-  // preserve optimistic comments because gh's 60s response cache will return
-  // stale data that doesn't include the just-posted comment.
+  // Why: track last fetched item to distinguish reopen from switch — reopen must preserve optimistic comments since gh's 60s cache omits the just-posted one.
   const prevItemIdRef = useRef<string | null>(null)
 
-  // Why: when this dialog opens immediately after another Radix overlay
-  // (e.g. the New Issue dialog) closed, Radix may leave `pointer-events: none`
-  // on <body>. That silently kills clicks on the header's Close/open-in-GitHub
-  // buttons. Poll a few frames to clear it whenever Radix re-applies it during
-  // its own mount sequence.
+  // Why: Radix can leave `pointer-events: none` on <body> when opening right after another overlay closes, killing header clicks; poll a few frames to clear it.
   useEffect(() => {
     if (!workItem) {
       return
@@ -6590,10 +6504,7 @@ export default function PullRequestPage({
     }
   }, [workItem])
 
-  // Why: subscribe to the module-level cache so reopening a cached item
-  // paints synchronously on first render. getSnapshot returns the entry
-  // object directly — touchWorkItemDetailsCache writes always replace entry
-  // identity (delete+set), so Map.get is referentially stable between writes.
+  // Why: subscribe to the module cache so reopening a cached item paints synchronously; writes replace entry identity (delete+set), so Map.get is a stable snapshot.
   const cachedEntry = useSyncExternalStore(
     subscribeWorkItemDetailsCache,
     useCallback(
@@ -6602,24 +6513,15 @@ export default function PullRequestPage({
     )
   )
 
-  // Why: bumped by appendOptimisticComment on cold open (no cached details
-  // yet) so the details memo re-runs and surfaces the optimistic comment via
-  // the loading-shell fallback. Without this, the comment would sit in the
-  // ref alone and not render until the in-flight fetch lands. The cache
-  // notify path handles the warm case.
+  // Why: bumped on cold open (no cached details) so the details memo re-runs and surfaces the optimistic comment via the loading shell; cache-notify handles the warm case.
   const [optimisticTick, setOptimisticTick] = useState(0)
 
-  // Why: merge optimistic comments into the cached details. Keyed off
-  // cachedEntry identity (stable) rather than the optimistic ref array (a
-  // fresh array each render) to avoid unnecessary recomputation. Cache
-  // notifications after optimistic writes will re-render this anyway.
+  // Why: merge optimistic comments into cached details; keyed off stable cachedEntry identity (not the per-render ref array) to avoid needless recompute.
   const details = useMemo<GitHubWorkItemDetails | null>(() => {
     const cachedDetails = cachedEntry?.details ?? null
     const opt = optimisticCommentsRef.current
     if (!cachedDetails) {
-      // Why: details may still be loading on a cold open — surface optimistic
-      // comments via a minimal shell so a comment posted before the fetch
-      // resolves isn't held invisibly in ref-land.
+      // Why: on a cold open details may still be loading; surface optimistic comments via a minimal shell so a just-posted comment isn't held invisibly in the ref.
       if (opt.length > 0 && workItem) {
         return { item: workItem, body: '', comments: [...opt] }
       }
@@ -6637,11 +6539,7 @@ export default function PullRequestPage({
       ...cachedDetails,
       comments: [...cachedDetails.comments, ...missing]
     }
-    // Why: optimisticTick is the rerender signal for cold-open writes — the
-    // memo reads optimisticCommentsRef.current (a ref, no subscription), so
-    // bumping the tick is what forces this memo to re-run. The lint flags it
-    // as "unnecessary" because it's not referenced in the body, but removing
-    // it would silently break the cold-open optimistic-shell path.
+    // Why: optimisticTick isn't read in the body but is the rerender signal for cold-open writes (memo reads a ref); removing it breaks the optimistic shell.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [cachedEntry, workItem, optimisticTick])
 
@@ -6649,10 +6547,7 @@ export default function PullRequestPage({
   const error = cachedEntry?.error && !cachedEntry?.details ? cachedEntry.error : null
   const detailsLoaded = Boolean(cachedEntry?.details)
 
-  // Why: if a cross-window mutation invalidates the open drawer's entry
-  // (cachedEntry becomes undefined while workItem is still set), the main
-  // fetch effect won't re-run because its deps haven't changed. Bump a local
-  // tick so the fetch effect fires a refetch in that case.
+  // Why: if a cross-window mutation invalidates the open drawer's entry (cachedEntry undefined, fetch deps unchanged), bump a tick so it refetches.
   const [refetchTick, setRefetchTick] = useState(0)
   useEffect(() => {
     if (workItem && detailsCacheKey && !cachedEntry) {
@@ -6664,11 +6559,7 @@ export default function PullRequestPage({
     if (!workItem || !effectiveRepoId || !detailsCacheKey || !canUseDetailsRepoContext) {
       return
     }
-    // Why: only clear optimistic comments when switching to a genuinely
-    // different item. When reopening the same item (close → reopen), the
-    // gh API's 60s response cache will return stale data that omits the
-    // just-posted comment — preserving the optimistic ref lets the merge
-    // logic above re-attach it to the stale response.
+    // Why: only clear optimistic comments on a genuine item switch; on reopen gh's 60s cache omits the just-posted comment, so preserve the ref for re-merge.
     if (workItem.id !== prevItemIdRef.current) {
       optimisticCommentsRef.current = []
     }
@@ -6682,9 +6573,7 @@ export default function PullRequestPage({
       return
     }
 
-    // Why: dedupe concurrent opens for the same key — concurrent dialogs or
-    // a rapid close→reopen must share one in-flight promise instead of
-    // racing two `gh` subprocesses against each other.
+    // Why: dedupe concurrent opens on the same key so a rapid close→reopen shares one in-flight promise instead of racing two `gh` subprocesses.
     const inflight: Promise<GitHubWorkItemDetails | null> =
       cached?.pending ??
       lookupGitHubWorkItemDetailsForSource({
@@ -6695,9 +6584,7 @@ export default function PullRequestPage({
         type: workItem.type
       })
 
-    // Why: snapshot the invalidation generation at fetch start; if the
-    // generation advances before we resolve, a mutation invalidated the
-    // entry mid-flight and we must not write a stale result back.
+    // Why: snapshot the generation so a mid-flight invalidation (generation advance) blocks writing a stale result back.
     const launchedAtGeneration = workItemDetailsCacheGeneration
 
     if (!cached?.pending) {
@@ -6714,8 +6601,7 @@ export default function PullRequestPage({
         const invalidatedMidFlight = workItemDetailsCacheGeneration !== launchedAtGeneration
         const prev = workItemDetailsCache.get(detailsCacheKey)
         if (invalidatedMidFlight && prev?.pending !== inflight) {
-          // Why: entry was deliberately dropped; do not recreate it. If the
-          // entry still exists (later open repopulated it) leave it alone too.
+          // Why: entry was deliberately dropped (or later repopulated) — don't recreate or clobber it.
           return
         }
         // Why: null means unavailable/not found, not loaded empty content.
@@ -6746,9 +6632,7 @@ export default function PullRequestPage({
         if (invalidatedMidFlight && prev?.pending !== inflight) {
           return
         }
-        // Why: stale-on-error — keep cached data if we have it, drop the
-        // pending promise so the next open can retry. Only surface the
-        // blocking error when nothing is cached.
+        // Why: stale-on-error — keep cached data, drop the pending promise so next open retries; surface the error only when nothing is cached.
         touchWorkItemDetailsCache(detailsCacheKey, {
           details: prev?.details ?? null,
           fetchedAt: prev?.fetchedAt ?? 0,
@@ -6765,8 +6649,7 @@ export default function PullRequestPage({
     refetchTick
   ])
 
-  // Why: the state pill's icon must track the resolved state so a merged PR
-  // reads as merged (purple GitMerge) rather than wearing the open-PR glyph.
+  // Why: icon must track resolved state so a merged PR reads as merged, not as the open-PR glyph.
   const Icon =
     workItem?.type === 'pr'
       ? localState === 'merged'
@@ -6791,8 +6674,7 @@ export default function PullRequestPage({
     if (!workItem || details?.item.reviewRequests === undefined) {
       return
     }
-    // Why: PR details can carry fresher reviewer metadata than the list row;
-    // push it back so the Tasks review chip doesn't keep a stale snapshot.
+    // Why: PR details can carry fresher reviewer metadata than the list row; push it back so the Tasks review chip isn't stale.
     onReviewRequestsChange?.(
       { id: workItem.id, repoId: workItem.repoId },
       details.item.reviewRequests
@@ -6805,8 +6687,7 @@ export default function PullRequestPage({
   const filesUnavailable = details?.filesUnavailable ?? false
   const checks = details?.checks ?? []
   const [pendingViewedPaths, setPendingViewedPaths] = useState<Set<string>>(() => new Set())
-  // Why: clipboard IPC can resolve after the page unmounts; skip copied-state
-  // feedback instead of starting its reset timer on a stale surface.
+  // Why: clipboard IPC can resolve after unmount; skip copied-state feedback rather than start a reset timer on a stale surface.
   const linkCopyMountedRef = useRef(false)
   const linkCopiedResetTimerRef = useRef<number | null>(null)
   const clearLinkCopiedResetTimer = useCallback((): void => {
@@ -6820,8 +6701,7 @@ export default function PullRequestPage({
     (node: HTMLButtonElement | null) => {
       linkCopyMountedRef.current = node !== null
       if (node === null) {
-        // Why: the copied-state timer belongs to the copy control surface;
-        // clear it when that surface detaches without a passive cleanup Effect.
+        // Why: clear the copied-state timer on ref detach instead of via a passive cleanup Effect.
         clearLinkCopiedResetTimer()
       }
     },
@@ -6833,8 +6713,7 @@ export default function PullRequestPage({
       return
     }
     try {
-      // Why: Electron's clipboard IPC is reliable even when browser clipboard
-      // APIs lose focus/activation inside nested overlay surfaces.
+      // Why: Electron clipboard IPC works even when browser clipboard APIs lose focus/activation in nested overlays.
       await window.api.ui.writeClipboardText(workItem.url)
       if (!linkCopyMountedRef.current) {
         return
@@ -6856,15 +6735,9 @@ export default function PullRequestPage({
 
   const appendOptimisticComment = useCallback(
     (comment: PRComment) => {
-      // Why: skip refreshDetails() — gh api --cache 60s returns stale data
-      // that overwrites the optimistic comment. The next dialog open (after
-      // cache expiry) will pick up the server-confirmed version.
+      // Why: skip refreshDetails() — gh api --cache 60s returns stale data that would overwrite the optimistic comment.
       optimisticCommentsRef.current.push(comment)
-      // Why: write through the module-level cache so subscribers (this
-      // drawer plus any concurrent ones on the same item) re-render with the
-      // optimistic comment. Mark fetchedAt as stale (0) so the next open
-      // still triggers a background refresh to pick up server-side fields
-      // like reaction groups or thread bindings.
+      // Why: write through the shared cache so subscribers re-render; fetchedAt=0 forces a background refresh next open for server-side fields.
       if (detailsCacheKey) {
         const prev = workItemDetailsCache.get(detailsCacheKey)
         if (prev?.details) {
@@ -6882,10 +6755,7 @@ export default function PullRequestPage({
           }
         }
       }
-      // Why: when the cache has no details yet (still loading), no cache
-      // write/notify fires above. Bump local state so the details memo
-      // re-runs and surfaces the optimistic comment via the loading-shell
-      // fallback instead of holding it invisibly in the ref.
+      // Why: cache empty (still loading) so no write/notify above; bump local state so the memo re-runs and surfaces the optimistic comment.
       setOptimisticTick((n) => n + 1)
     },
     [detailsCacheKey]
@@ -6895,8 +6765,7 @@ export default function PullRequestPage({
     if (!workItem) {
       return
     }
-    // Why: local repos can invalidate every source-preference variant; runtime-only
-    // entries need their exact source-scoped key because there is no local path.
+    // Why: local repos invalidate all source-preference variants; runtime-only entries need their exact source-scoped key (no local path).
     if (repoPath) {
       invalidateWorkItemDetailsCacheByMatch({
         repoPath,
@@ -7073,8 +6942,7 @@ export default function PullRequestPage({
             </span>
           </h1>
           <div className="flex shrink-0 items-center gap-2">
-            {/* Why: Orca's signature affordance — keep this primary so it stands out
-                against GitHub's familiar surface. */}
+            {/* Why: Orca's signature affordance — keep primary so it stands out against GitHub's familiar surface. */}
             <DropdownMenu modal={false}>
               <ButtonGroup>
                 <Button
@@ -7149,8 +7017,7 @@ export default function PullRequestPage({
                 translate('auto.components.PullRequestPage.77d9388fb0', 'unknown')}
             </span>
           </span>
-          {/* Why: the scannable base ← head idiom reads faster than a prose
-              sentence and matches how reviewers think about merge direction. */}
+          {/* Why: base ← head scans faster than prose and matches how reviewers think about merge direction. */}
           <span className="flex flex-wrap items-center gap-1.5">
             {baseBranch ? (
               <span className="rounded-md border border-border bg-muted/40 px-1.5 py-0.5 font-mono text-[12px] text-foreground">
@@ -7216,9 +7083,7 @@ export default function PullRequestPage({
             onValueChange={(value) => setTab(value as ItemDialogTab)}
             className="flex h-full min-h-0 flex-col gap-0"
           >
-            {/* Why: page-level tabs sit on a flat strip; the line variant
-                already paints an underline under the active tab via its own
-                ::after, so don't add a second border that boxes the trigger. */}
+            {/* Why: the line variant already underlines the active tab via ::after; a second border would box the trigger. */}
             <TabsList
               variant="line"
               className="mx-0 justify-start gap-2 border-b border-border/60 bg-transparent px-6"
@@ -7314,8 +7179,7 @@ export default function PullRequestPage({
                     <LoaderCircle className="size-5 animate-spin text-muted-foreground" />
                   </div>
                 ) : filesUnavailable && files.length === 0 ? (
-                  // Why: the file fetch failed (rate limit, auth, unresolved
-                  // remote); offer a retry instead of implying the PR is empty.
+                  // Why: fetch failed (rate limit/auth/unresolved remote); offer retry instead of implying the PR is empty.
                   <div className="flex flex-col items-center gap-3 px-4 py-10 text-center">
                     <div className="text-[12px] text-muted-foreground">
                       {translate(
diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index 727c0a44970..9d08575e625 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: the tasks page keeps the repo selector,
-task source controls, and GitHub task list co-located so the wiring between the
-selected repo, the task filters, and the work-item list stays readable in one
-place while this surface is still evolving. */
+/* eslint-disable max-lines -- Why: repo selector, task-source controls, and task list stay co-located so their wiring reads in one place. */
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { useShallow } from 'zustand/react/shallow'
@@ -512,10 +509,7 @@ function getTaskPageRepoCacheInput(repo: Repo): {
   }
 }
 
-// Why: the sticky header's bg must be opaque (GITHUB_TASK_ROW_SURFACE_CLASS, not
-// bg-muted/50) or vertically-scrolled rows bleed through it. These left-sticky
-// cells additionally need a ::before gap-cover so horizontally-scrolled header
-// columns don't show through the row's px-3 padding strip.
+// Why: sticky header bg must be opaque or scrolled rows bleed through; the ::before gap-cover keeps horizontally-scrolled columns off the px-3 padding strip.
 const GITHUB_TASK_STICKY_ID_HEADER_CLASS = cn(
   'sticky left-3 z-30 before:absolute before:-left-3 before:top-0 before:bottom-0 before:w-3 before:bg-inherit',
   GITHUB_TASK_ROW_SURFACE_CLASS
@@ -550,8 +544,7 @@ function isPRFocusedTaskView(preset: TaskViewPresetId | null, query: string): bo
 }
 
 function normalizeGitHubTaskPreset(preset: TaskViewPresetId | null | undefined): TaskViewPresetId {
-  // Why: the split Issues/PRs tabs no longer have a mixed "All" view, so
-  // legacy saved defaults should land on the first tab instead of mixing rows.
+  // Why: the split Issues/PRs tabs dropped the mixed "All" view, so legacy saved defaults land on the first tab instead of mixing rows.
   return !preset || preset === 'all' ? 'issues' : preset
 }
 
@@ -576,9 +569,7 @@ function scopeGitHubTaskSearch(query: string, kind: GitHubTaskKind): string {
   return `${inferredKind === 'prs' ? 'is:pr' : 'is:issue'} ${trimmed}`
 }
 
-// Why: Intl.RelativeTimeFormat allocation is non-trivial, and previously we
-// built a new formatter per work-item row render. Hoisting to module scope
-// means all rows share one instance — zero per-row allocation cost.
+// Why: Intl.RelativeTimeFormat allocation is non-trivial; hoist to module scope so all rows share one instance instead of allocating per render.
 const relativeTimeFormatter = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' })
 
 function formatRelativeTime(input: string): string {
@@ -1149,8 +1140,7 @@ function GHStatusCell({
 
   const resolvedStatusStateDraft = resolveTaskPageGitHubStatusStateDraft(statusStateDraft, item)
   if (resolvedStatusStateDraft !== statusStateDraft) {
-    // Why: item rows can refresh from the GitHub cache while this cell is still
-    // mounted; reconcile before paint instead of showing one stale status frame.
+    // Why: item rows can refresh from the cache while this cell is mounted; reconcile before paint to avoid one stale status frame.
     setStatusStateDraft(resolvedStatusStateDraft)
   }
   const localState = resolvedStatusStateDraft.localState
@@ -1181,8 +1171,7 @@ function GHStatusCell({
       updateLocalState(newState)
       patchWorkItem(item.id, { state: newState }, item.repoId, { sourceContext })
       const target = getActiveRuntimeTarget(sourceSettings)
-      // Why: issue rows can be sourced by owner/repo URL instead of the local
-      // repo context; slug-aware writes preserve close reasons and duplicates.
+      // Why: issue rows can be sourced by owner/repo URL, not local repo context; slug-aware writes preserve close reasons and duplicates.
       const updatePromise = parsedOwnerRepo
         ? target.kind === 'environment'
           ? callRuntimeRpc<{ ok?: boolean; error?: { message?: string } | string }>(
@@ -1521,9 +1510,7 @@ function ReviewChipAvatar({
   reviewer: GitHubPRPrimaryReviewer | null
 }): React.JSX.Element {
   if (reviewer?.login) {
-    // Why: `gh pr list --json reviewRequests` can return only logins. Prefer the
-    // API avatar_url so GHE renders; GitHubUserAvatar falls back to the login URL
-    // and then an initials placeholder when no avatar loads. See #8784.
+    // Why: gh pr list --json reviewRequests can return only logins; prefer API avatar_url so GHE renders (falls back to login URL, then initials). See #8784.
     return (
       <GitHubUserAvatar
         login={reviewer.login}
@@ -2154,8 +2141,7 @@ function PRReviewCell({
     [cancelReviewerInputFocusFrame]
   )
 
-  // Why: reviewer edits are optimistic, but item switches/refetches must clear
-  // stale local requests before paint; a passive Effect leaves one stale render.
+  // Why: reviewer edits are optimistic, but item switches/refetches must clear stale local requests before paint (a passive Effect leaves one stale frame).
   if (
     reviewRequestsSource.itemId !== item.id ||
     reviewRequestsSource.repoId !== item.repoId ||
@@ -2417,8 +2403,7 @@ function PRReviewCell({
   }
 
   const requestReviewer = async (reviewer: GitHubAssignableUser): Promise<void> => {
-    // Close the popover immediately so the UI feels responsive; the GitHub
-    // request/remove runs in the background and toasts on completion.
+    // Close the popover immediately for responsiveness; the GitHub request/remove runs in the background and toasts on completion.
     setOpen(false)
     setReviewerInput('')
     await (selectedReviewerLogins.has(reviewer.login.toLowerCase())
@@ -2929,9 +2914,7 @@ function PRMergeCell({
   )
 }
 
-// Why: builds the page number array with ellipsis gaps, matching GitHub's
-// pagination pattern: always show first page, last page, and a window of
-// pages around the current page with "..." gaps between distant ranges.
+// Builds the page-number array with ellipsis gaps: first, last, and a window around the current page.
 function getPageNumbers(current: number, total: number): (number | 'ellipsis')[] {
   if (total <= 9) {
     return Array.from({ length: total }, (_, i) => i)
@@ -3035,20 +3018,14 @@ function PaginationBar({
   )
 }
 
-// Why: type-guard predicate used to filter `perRepoSourceState` down to rows
-// whose issue-source and PR-source slugs differ. Hoisted to module scope so
-// the predicate isn't re-allocated on every TaskPage render.
+// Why: hoisted to module scope so the type-guard predicate isn't re-allocated on every TaskPage render.
 const hasDivergentSources = (
   s: TaskPageRepoSourceState
 ): s is TaskPageRepoSourceState & {
   sources: { issues: GitHubOwnerRepo; prs: GitHubOwnerRepo }
 } => !!s.sources?.issues && !!s.sources.prs && !sameGitHubOwnerRepo(s.sources.issues, s.sources.prs)
 
-// Why: the selector keeps rendering even after the user picks 'upstream' (which
-// makes effective `sources.prs` point at upstream). Raw-candidate divergence is the
-// right render gate — a repo that has an `upstream` remote pointing somewhere
-// different from origin is always a candidate for the toggle, regardless of
-// the current effective preference.
+// Why: gate on raw origin/upstream candidate divergence, not effective sources, so the toggle keeps rendering after the user picks 'upstream'.
 const hasUpstreamCandidateDivergence = (
   s: TaskPageRepoSourceState
 ): s is TaskPageRepoSourceState & {
@@ -3081,10 +3058,7 @@ export default function TaskPage(): React.JSX.Element {
   const fetchPRChecks = useAppStore((s) => s.fetchPRChecks)
   const getCachedWorkItems = useAppStore((s) => s.getCachedWorkItems)
   const setIssueSourcePreference = useAppStore((s) => s.setIssueSourcePreference)
-  // Why: bumped by `setIssueSourcePreference` after cache eviction so the
-  // fetch effect below re-runs and repopulates work-items against the new
-  // source. Eviction alone isn't enough because the effect's deps don't
-  // include `workItemsCache`.
+  // Why: bumped after cache eviction to re-run the fetch effect — eviction alone won't, since its deps don't include workItemsCache.
   const workItemsInvalidationNonce = useAppStore((s) => s.workItemsInvalidationNonce)
   const linearStatus = useAppStore((s) => s.linearStatus)
   const linearStatusChecked = useAppStore((s) => s.linearStatusChecked)
@@ -3135,11 +3109,7 @@ export default function TaskPage(): React.JSX.Element {
   const submitShortcutLabel = getScreenSubmitShortcutLabel()
   const eligibleRepos = useMemo(() => repos.filter((repo) => isGitRepoKind(repo)), [repos])
 
-  // Why: initial selection resolution honors (1) an explicit preselection from
-  // the caller, (2) the persisted defaultRepoSelection (null = sticky-all,
-  // array = curated subset, empty after filter = fall back to all), (3) fall
-  // back to "all eligible". An explicit preselection wins so "open tasks for
-  // this specific repo" entry points still land on a single-repo view.
+  // Why: initial selection precedence — explicit preselection > persisted defaultRepoSelection > all eligible; preselection wins so "open tasks for this repo" lands single-repo.
   const resolvedInitialSelection = useMemo<ReadonlySet<string>>(() => {
     const preferred = pageData.preselectedRepoId
     if (preferred && eligibleRepos.some((repo) => repo.id === preferred)) {
@@ -3151,9 +3121,7 @@ export default function TaskPage(): React.JSX.Element {
       if (filtered.length > 0) {
         return normalizeTaskRepoSelection(eligibleRepos, new Set(filtered))
       }
-      // Why: empty after filtering (e.g. all persisted repos were removed)
-      // falls through to the automatic default so the page never renders with
-      // an empty selection — see the multi-combobox invariant.
+      // Why: empty after filtering (all persisted repos removed) falls through to the automatic default so the page never renders an empty selection.
     }
     return getDefaultTaskRepoSelection(eligibleRepos)
   }, [eligibleRepos, pageData.preselectedRepoId, settings?.defaultRepoSelection])
@@ -3168,10 +3136,7 @@ export default function TaskPage(): React.JSX.Element {
     [taskPickerGroups]
   )
 
-  // Why: prune selection when a previously-selected repo is removed, and
-  // preserve sticky-all (when the selection equaled every logical project
-  // pre-change, keep it equal to every logical project post-change). Recreating
-  // the Set every time eligibleRepos changes would churn the fetch effect.
+  // Why: prune removed repos and preserve sticky-all (selection == all projects stays == all), without recreating the Set each time and churning the fetch effect.
   const prevTaskPickerCountRef = useRef(taskPickerRepos.length)
   useEffect(() => {
     const prevCount = prevTaskPickerCountRef.current
@@ -3205,9 +3170,7 @@ export default function TaskPage(): React.JSX.Element {
     [eligibleRepos, repoSelection]
   )
 
-  // Why: many affordances (new-issue dialog default, item dialog repo path lookup,
-  // optimistic stub) need *a* repo. First selected is used as the default;
-  // cross-repo dialogs still let the user override per-action.
+  // Why: many affordances need *a* repo; use the first selected as default, while cross-repo dialogs still let the user override per-action.
   const primaryRepo = selectedRepos[0] ?? null
   const linearWorkspaces = linearStatus.workspaces ?? []
   const selectedLinearWorkspaceId =
@@ -3268,8 +3231,7 @@ export default function TaskPage(): React.JSX.Element {
       const visibleWithoutProvider = preferredVisibleTaskProviders.filter(
         (visibleProvider) => visibleProvider !== provider
       )
-      // Why: an empty provider list normalizes back to "all providers"; keep
-      // one other source visible so opting out actually hides this provider.
+      // Why: an empty provider list normalizes to "all providers", so keep one other source visible or hiding this one has no effect.
       const nextVisibleTaskProviders: TaskProvider[] =
         visibleWithoutProvider.length > 0 ? visibleWithoutProvider : ['github']
       const nextDefaultTaskSource = resolveVisibleTaskProvider(
@@ -3291,11 +3253,7 @@ export default function TaskPage(): React.JSX.Element {
     [defaultTaskSource, preferredVisibleTaskProviders, updateSettings]
   )
 
-  // Why: seed the preset + query from the user's saved default synchronously
-  // so the first fetch effect issues exactly one request keyed to the final
-  // query. Previously a separate effect "re-seeded" these after mount, which
-  // caused a throwaway empty-query fetch followed by a second fetch for the
-  // real default — doubling the time-to-first-paint of the list.
+  // Why: seed preset + query synchronously so the first fetch issues one request; a prior post-mount re-seed caused a throwaway empty-query fetch, doubling time-to-first-paint.
   const defaultTaskViewPreset = normalizeGitHubTaskPreset(settings?.defaultTaskViewPreset ?? 'all')
   const initialTaskQuery = getTaskPresetQuery(defaultTaskViewPreset)
 
@@ -3391,8 +3349,7 @@ export default function TaskPage(): React.JSX.Element {
       if (parsed?.kind !== 'runtime') {
         continue
       }
-      // Why: task sources can span multiple runtime hosts; each runtime owns
-      // its own gh/glab installation and auth state.
+      // Why: task sources can span multiple runtime hosts; each runtime owns its own gh/glab install and auth state.
       void callRuntimeRpc<PreflightStatus>(
         { kind: 'environment', environmentId: parsed.environmentId },
         'preflight.check',
@@ -3680,9 +3637,7 @@ export default function TaskPage(): React.JSX.Element {
   const jiraSearchPersistReadyRef = useRef(false)
   const [taskResumeApplied, setTaskResumeApplied] = useState(false)
 
-  // Why: pageData.taskSource changes when the user clicks a specific source
-  // icon in the sidebar while the task page is already open. useState only
-  // initializes once, so sync from the store when the value changes.
+  // Why: useState only inits once, so sync taskSource from the store when a sidebar source-icon click changes pageData.taskSource.
   useEffect(() => {
     const pageTaskSourceChanged = lastPageTaskSourceRef.current !== pageData.taskSource
     lastPageTaskSourceRef.current = pageData.taskSource
@@ -3700,9 +3655,7 @@ export default function TaskPage(): React.JSX.Element {
     if (taskSourceManuallyChangedRef.current) {
       return
     }
-    // Why: GitLab/Linear availability hydrates after mount. If the saved
-    // default was unavailable during the first render, restore it once the
-    // relevant check proves the provider can be shown.
+    // Why: GitLab/Linear availability hydrates after mount; restore the saved default once its provider check proves it can be shown.
     if (visibleTaskProviders.includes(preferredTaskSource) && taskSource !== preferredTaskSource) {
       setTaskSource(preferredTaskSource)
     }
@@ -3714,30 +3667,21 @@ export default function TaskPage(): React.JSX.Element {
     }
   }, [settings?.defaultTaskSource, taskSource, visibleTaskProviders])
 
-  // Why: Project mode is a sub-tab within the GitHub source. Visible whenever
-  // the user is on the GitHub task source — actual entry into Project mode is
-  // gated on a non-null `activeProject` once they pick one.
+  // Why: Project mode is a GitHub sub-tab — visible on the GitHub source, but actual entry is gated on a non-null activeProject.
   const projectModeVisible = taskSource === 'github'
   const [githubMode, setGithubMode] = useState<'items' | 'project'>('items')
 
   // ── GitLab task-source state ──────────────────────────────────────
-  // Why: parallel to Linear's slim per-source state. Skips workItemsCache
-  // and cross-repo aggregation in v1 — the GitLab list fetches directly
-  // from `window.api.gl.listMRs` / `listIssues` for the primary repo.
+  // Why: parallel to Linear's slim per-source state — skips workItemsCache and cross-repo aggregation; fetches directly via window.api.gl for the primary repo.
   const [gitlabFilter, setGitlabFilter] = useState<GitLabTaskFilter | GitLabIssueFilter>('opened')
   const [gitlabItems, setGitlabItems] = useState<GitLabWorkItem[]>([])
   const [gitlabLoading, setGitlabLoading] = useState(false)
   const [gitlabError, setGitlabError] = useState<string | null>(null)
   const [gitlabRefreshNonce, setGitlabRefreshNonce] = useState(0)
-  // Why: opens GitLabItemDialog when a row is clicked. Separate state from
-  // gitlabItems so the dialog target survives a list refresh that might
-  // remove the item from the visible filter (e.g. closing an MR while
-  // it's open in the dialog).
+  // Why: separate from gitlabItems so the dialog target survives a list refresh that removes the item from the visible filter (e.g. closing an MR).
   const [gitlabDialogItem, setGitlabDialogItem] = useState<GitLabWorkItem | null>(null)
 
-  // Why: GitLab tab has two sub-views — the project's MR/issue list,
-  // and the user's cross-project Todos (gitlab.com/dashboard/todos).
-  // 'project' is default; 'todos' fetches a separate stream.
+  // Why: GitLab tab has two sub-views — the project MR/issue list and the user's cross-project Todos (a separate stream).
   const [gitlabView, setGitlabView] = useState<'issues' | 'mrs' | 'todos'>('mrs')
   const [gitlabTodos, setGitlabTodos] = useState<GitLabTodo[]>([])
   const [gitlabTodosLoading, setGitlabTodosLoading] = useState(false)
@@ -3758,8 +3702,7 @@ export default function TaskPage(): React.JSX.Element {
         ? isGitLabMRFilter(gitlabFilter)
         : true
   const activeGitlabFilter = gitlabFilterIsValid ? gitlabFilter : 'opened'
-  // Why: Issues and MRs expose different filter sets; repair before commit so
-  // fetch Effects never issue `glab` with a stale filter from the other view.
+  // Why: Issues and MRs expose different filter sets; repair before commit so fetch effects never run glab with a stale filter from the other view.
   if (!gitlabFilterIsValid) {
     setGitlabFilter('opened')
   }
@@ -3784,40 +3727,26 @@ export default function TaskPage(): React.JSX.Element {
   const [tasksRefreshing, setTasksRefreshing] = useState(false)
   const [tasksFiltering, setTasksFiltering] = useState(false)
   const [tasksError, setTasksError] = useState<string | null>(null)
-  // Why: per-repo failure count surfaced through the "N of M" banner. IPC-level
-  // rejections populate tasksError instead — the two are mutually exclusive so
-  // a successful-with-partial-failure read and a hard-reject don't double-show.
+  // Why: per-repo failure count for the "N of M" banner; IPC rejections use tasksError instead so partial-failure and hard-reject don't double-show.
   const [failedCount, setFailedCount] = useState(0)
-  // Why: when every selected refresh fails because GitHub is unreachable
-  // (outage / network / rate limit), attribute it to GitHub instead of making
-  // an empty or stale cached list look current.
+  // Why: when every refresh fails (GitHub outage/network/rate limit), attribute it to GitHub instead of showing an empty or stale list as current.
   const [githubUnavailable, setGithubUnavailable] = useState(false)
   const [taskRefreshNonce, setTaskRefreshNonce] = useState(0)
-  // Why: the fetch effect uses this to detect when a nonce bump is from the
-  // user clicking the refresh button (force=true) vs. re-running for any
-  // other reason — e.g. a repo change while the nonce happens to be > 0.
+  // Why: lets the fetch effect tell a user refresh-click nonce bump (force=true) from a re-run for another reason (e.g. repo change with nonce > 0).
   const lastFetchedNonceRef = useRef(-1)
-  // Why: analogous to `lastFetchedNonceRef` for the invalidation nonce. A
-  // preference flip should force the dispatch past fetch-dedupe (same repos +
-  // same query, cache just evicted — without `force: true` the fan-out could
-  // collapse onto a stale in-flight request that resolved against the
-  // pre-flip source).
+  // Why: invalidation-nonce analog of lastFetchedNonceRef; a preference flip must force past fetch-dedupe or the fan-out collapses onto a stale in-flight request from the pre-flip source.
   const lastFetchedInvalidationNonceRef = useRef(0)
   const paginationGenerationRef = useRef(0)
-  // Why: entering Tasks with fresh cache should still verify remote status
-  // once, but the result is reconciled into existing rows to avoid a full
-  // table shuffle when only status/key fields changed.
+  // Why: entering Tasks with fresh cache still verifies remote status once, reconciled into existing rows to avoid a full table shuffle.
   const landingGitHubRefreshKeysRef = useRef<ReadonlySet<string>>(new Set())
-  // Why: divide the display budget between repos so one provider page maps to
-  // one UI page without truncating rows that later provider pages cannot return.
+  // Why: split the display budget across repos so one provider page maps to one UI page without truncating rows later pages can't return.
   const githubPerRepoPageLimit = getTaskPagePerRepoLimit(
     selectedRepos.length,
     PER_REPO_FETCH_LIMIT,
     CROSS_REPO_DISPLAY_LIMIT
   )
   const githubPageSize = githubPerRepoPageLimit * Math.max(1, selectedRepos.length)
-  // Why: null entries are pages not fetched yet. Numbered provider pages let a
-  // high-page click load that page directly without rate-limiting intermediate reads.
+  // Why: null entries are pages not fetched yet; numbered provider pages let a high-page click load directly without reading intermediate pages.
   const [pages, setPages] = useState<(GitHubWorkItem[] | null)[]>(() => {
     const trimmed = initialTaskQuery.trim()
     const merged: GitHubWorkItem[] = []
@@ -3852,10 +3781,7 @@ export default function TaskPage(): React.JSX.Element {
     setLoadingTargetPage(null)
   }, [selectedRepos, appliedTaskSearch, workItemsInvalidationNonce])
 
-  // Why: clicking a GitHub row (or completing the create-issue flow) opens
-  // this dialog for a read/review surface. The dialog's "Use" button routes
-  // through the same direct-launch flow as the row-level "Use" CTA so
-  // behavior is consistent regardless of entry point.
+  // Why: the dialog's "Use" button routes through the same direct-launch flow as the row-level "Use" CTA so behavior is consistent regardless of entry point.
   const githubTaskDrawerWorkItem = useAppStore((s) => s.githubTaskDrawerWorkItem)
   const setGithubTaskDrawerWorkItem = useAppStore((s) => s.setGithubTaskDrawerWorkItem)
   const [dialogInitialTab, setDialogInitialTab] = useState<ItemDialogTab>('conversation')
@@ -3878,12 +3804,7 @@ export default function TaskPage(): React.JSX.Element {
     )
   )
 
-  // Why: derive the dialog's work item from the store cache so it reflects
-  // optimistic patches (e.g. table-cell status toggle). Falls back to the
-  // snapshot stored at click time for newly-created stubs not yet in the cache.
-  // Disambiguates by repoId so issues with the same number fetched from
-  // multiple repos (e.g. fork + non-fork, both routed through the same
-  // upstream) resolve to the clicked row's repo, not the first one scanned.
+  // Why: derive the dialog item from the cache for optimistic patches, falling back to the click-time snapshot for new stubs; key by repoId so same-number issues across repos resolve to the clicked row.
   const cachedDialogWorkItem = useAppStore((s) =>
     findTaskPageDialogWorkItem(s.workItemsCache, dialogWorkItemKey)
   )
@@ -4024,15 +3945,8 @@ export default function TaskPage(): React.JSX.Element {
     [patchTaskPageWorkItemRows]
   )
 
-  // Why: feature 1 — render the "Issues from {owner}/{repo}" indicator per
-  // selected repo whose issue-source and PR-source slugs differ, and surface
-  // a per-repo retryable banner when the issue-side fetch failed. Both derive
-  // from the same `workItemsCache` entry the list already consumes, so no
-  // extra IPC round-trip is needed. The `TaskPageRepoSourceState` shape lives
-  // with the cache selectors so the render and guard code share one contract.
-  // Why: subscribe only to the cache entries this page can render. The selector
-  // returns entry references so Zustand shallow equality filters unrelated
-  // cache writes before they re-render the full tasks page.
+  // Why: the per-repo issue-source indicator and retry banner both derive from the same workItemsCache entry, so no extra IPC.
+  // Why: subscribe only to entries this page renders; the selector returns entry refs so shallow equality filters unrelated cache writes.
   const perRepoSourceState = useMemo<TaskPageRepoSourceState[]>(
     () => buildTaskPageRepoSourceState(selectedRepos, selectedWorkItemsCacheEntries),
     [selectedRepos, selectedWorkItemsCacheEntries]
@@ -4042,18 +3956,13 @@ export default function TaskPage(): React.JSX.Element {
     if (taskSource !== 'github' || githubMode !== 'items') {
       return
     }
-    // Why: inline/dialog edits patch `workItemsCache`; the paged table renders
-    // from a local snapshot so it needs the patched row objects copied across.
+    // Why: inline/dialog edits patch workItemsCache; the paged table renders from a local snapshot, so copy patched rows across.
     setPages((current) =>
       reconcileTaskPagePagesWithWorkItemsCache(current, selectedWorkItemsCacheEntries)
     )
   }, [githubMode, selectedWorkItemsCacheEntries, taskSource])
 
-  // Why: surface a one-time toast per session per repo when the user's
-  // preferred `'upstream'` is no longer configured and we fell back to
-  // origin. Gated on a ref-backed set so repeated list refreshes don't
-  // re-toast. We deliberately do NOT auto-reset the preference — the user
-  // may re-add `upstream` later and expect it to pick up again.
+  // Why: one-time toast per repo when the 'upstream' preference fell back to origin (ref-gated); deliberately don't auto-reset the preference so re-adding upstream later still applies.
   const fellBackToastedRef = useRef<Set<string>>(new Set())
   useEffect(() => {
     if (taskSource !== 'github') {
@@ -4081,14 +3990,7 @@ export default function TaskPage(): React.JSX.Element {
     }
   }, [selectedRepos, selectedWorkItemsCacheEntries, taskSource])
 
-  // Why: on a partial-failure retry the cache still holds successful-side
-  // data, so `tasksLoading` (which is gated on `anyUncached`) never flips
-  // true and the Retry button would otherwise give no feedback. Track
-  // retry-in-flight per selected source so that clicking Retry
-  // on one banner only flips that source's button into its "Retrying…"
-  // state — other still-failing banners stay in their "Retry" state rather
-  // than misleadingly flipping in lockstep. The fetch effect clears the set
-  // when the nonce-driven refresh settles.
+  // Why: partial-failure retry leaves the cache populated so tasksLoading never flips, giving no feedback; track retry-in-flight per source so only the clicked banner shows "Retrying…".
   const [retryingSourceKeys, setRetryingSourceKeys] = useState<ReadonlySet<string>>(() => new Set())
 
   const handleRetryIssuesFetch = useCallback(
@@ -4097,12 +3999,7 @@ export default function TaskPage(): React.JSX.Element {
       if (!source) {
         return
       }
-      // Why: bumping the shared refresh nonce reuses the Tasks list's
-      // single fetch path — nonce changes are treated as force=true so
-      // retry doesn't silently dedupe onto a still-failing in-flight request.
-      // The nonce bump refreshes ALL selected repos, but the Retrying…
-      // state is scoped to the clicked source so other banners stay in their
-      // "Retry" state rather than misleadingly flipping to "Retrying…".
+      // Why: nonce bump reuses the fetch path as force=true so retry doesn't dedupe onto a still-failing in-flight request (refreshes all repos; Retrying… stays scoped to the clicked source).
       setRetryingSourceKeys((prev) => {
         const next = new Set(prev)
         next.add(source.sourceKey)
@@ -4123,20 +4020,11 @@ export default function TaskPage(): React.JSX.Element {
   const [newIssueAssignees, setNewIssueAssignees] = useState<GitHubAssignableUser[]>([])
   const [newIssueSubmitting, setNewIssueSubmitting] = useState(false)
   const [newIssueRepoId, setNewIssueRepoId] = useState<string | null>(null)
-  // Why: session-only draft slice backs recovery of an in-progress issue after
-  // an accidental dismissal (outside click/Escape/Cancel) and across a Tasks
-  // view unmount. Component `useState` stays the inputs' immediate source; the
-  // store is the durable-across-remount backing. See task-page-new-issue-draft.
-  // The draft value is read imperatively at open time (getState) rather than
-  // subscribed: it's only consumed in the `+` open handler, and the write-through
-  // rewrites it on every keystroke — subscribing would re-render all of TaskPage
-  // per keystroke while the modal is open. Actions are stable refs (no churn).
+  // Why: session-only draft recovers an in-progress issue across dismissal/remount; read imperatively (not subscribed) so per-keystroke writes don't re-render all of TaskPage.
   const setNewIssueDraft = useAppStore((s) => s.setNewIssueDraft)
   const clearNewIssueDraft = useAppStore((s) => s.clearNewIssueDraft)
 
-  // Why: resolve the target repo from the user's choice, falling back to the
-  // first selected repo if the chosen id drops out of the selection while the
-  // dialog is open — keeps submit always landing on a valid repo.
+  // Why: fall back to the first selected repo if the chosen id drops from the selection mid-dialog, so submit always has a valid target.
   const newIssueTargetRepo = useMemo(
     () => selectedRepos.find((r) => r.id === newIssueRepoId) ?? selectedRepos[0] ?? null,
     [selectedRepos, newIssueRepoId]
@@ -4177,13 +4065,7 @@ export default function TaskPage(): React.JSX.Element {
     { runtimeEnvironmentId: newIssueOpen ? (newIssueRuntimeTarget?.environmentId ?? null) : null }
   )
 
-  // Why: repo-scoped labels/assignees can't cross repos. A reactive clear keyed
-  // on the derived target id can't tell a restore apart from a user switch, so
-  // it would wipe just-restored fields and corrupt the recovery draft via the
-  // write-through below. Decompose by cause instead: this guard only handles the
-  // "chosen repo vanished from the selection" case (removed/deselected). A
-  // genuine user switch clears imperatively in the repo Select's handler; a
-  // restore always seeds an in-selection repoId, so neither path fires here.
+  // Why: only handles the "chosen repo vanished" case; a reactive clear keyed on target id can't tell a restore from a user switch and would wipe the recovery draft.
   useEffect(() => {
     const reset = resolveVanishedNewIssueRepoReset(
       newIssueRepoId,
@@ -4197,10 +4079,7 @@ export default function TaskPage(): React.JSX.Element {
     setNewIssueRepoId(reset.repoId)
   }, [newIssueRepoId, selectedRepos])
 
-  // Why: mirror the live fields into the session draft while the modal is open
-  // so an accidental dismissal doesn't lose input. Content-gate the write so an
-  // untouched open never pins a meaningless draft (repoId alone is not content),
-  // and clear any stale draft once the form is emptied back out.
+  // Why: content-gated mirror of live fields into the session draft while the modal is open, so dismissal doesn't lose input.
   useEffect(() => {
     if (!newIssueOpen) {
       return
@@ -4239,9 +4118,7 @@ export default function TaskPage(): React.JSX.Element {
     useState<LinearIssue | null>(null)
   const [selectedLinearIssueCanFloat, setSelectedLinearIssueCanFloat] = useState(false)
 
-  // Why: the Linear list keeps its own fetched array, while cell edits patch
-  // the shared caches. Subscribing to just the Linear caches lets the list and
-  // inline detail reflect optimistic mutations without a second durable cache.
+  // Why: subscribe to just the Linear caches so list and inline detail reflect optimistic cell edits without a second cache.
   const linearCacheSnapshot = useAppStore(
     useShallow((s) => ({
       issueCache: s.linearIssueCache,
@@ -4717,8 +4594,7 @@ export default function TaskPage(): React.JSX.Element {
     setJiraSearchInput(jiraQuery)
     setAppliedJiraSearch(jiraQuery)
 
-    // Why: settings and persisted UI hydrate asynchronously. Apply the restored
-    // Tasks context exactly once so later source/filter clicks remain local.
+    // Why: settings/UI hydrate async; apply the restored Tasks context exactly once so later source/filter clicks stay local.
     taskResumeAppliedRef.current = true
     setTaskResumeApplied(true)
   }, [
@@ -4825,9 +4701,7 @@ export default function TaskPage(): React.JSX.Element {
     taskSource
   ])
 
-  // Why: fetch the full team list from the Linear API so the selector shows
-  // all teams the user belongs to, not just teams with issues in the current
-  // fetch window. Fetched once when the Linear tab is active and connected.
+  // Why: fetch the full Linear team list so the selector shows all teams, not just those with issues in the fetch window.
   const [availableTeams, setAvailableTeams] = useState<LinearTeam[]>([])
   const [linearTeamRefreshNonce, setLinearTeamRefreshNonce] = useState(0)
 
@@ -4843,9 +4717,7 @@ export default function TaskPage(): React.JSX.Element {
     const cachedTeams = getCachedLinearTeams(selectedLinearWorkspaceId, {
       sourceContext: linearTaskSourceContext
     })
-    // Why: workspace switches must not leave the prior workspace's teams
-    // available for new-issue creation while the replacement fetch is pending,
-    // but a workspace-scoped cache can keep the selector usable immediately.
+    // Why: on a workspace switch, drop the prior workspace's teams during the pending fetch but seed from the workspace-scoped cache.
     setAvailableTeams(cachedTeams ?? [])
     void listLinearTeams(selectedLinearWorkspaceId, { sourceContext: linearTaskSourceContext })
       .then((teams) => {
@@ -4916,10 +4788,7 @@ export default function TaskPage(): React.JSX.Element {
     jiraTaskSourceContext
   ])
 
-  // Why: stable key for `selectedRepos` so the GitLab fetch effect below
-  // doesn't re-run on every parent re-render just because the array
-  // reference changed. The memoized string keys off id + path +
-  // connectionId — the only fields the effect actually reads.
+  // Why: stable string key for selectedRepos so the GitLab effect doesn't re-run on every parent render from a new array ref.
   const selectedReposKey = useMemo(
     () =>
       selectedRepos
@@ -4928,10 +4797,7 @@ export default function TaskPage(): React.JSX.Element {
     [selectedRepos]
   )
 
-  // Why: GitLab task-source data fetch. Issues and MRs are fetched
-  // separately (mirrors GitHub's separate Issues / PRs endpoints) so
-  // errors are isolated per tab and the backend doesn't need a combined
-  // merge+sort that can hide failures.
+  // Why: fetch GitLab Issues and MRs separately so errors stay isolated per tab (mirrors GitHub's split endpoints).
   useEffect(() => {
     if (taskSource !== 'gitlab') {
       return
@@ -4949,8 +4815,7 @@ export default function TaskPage(): React.JSX.Element {
     ) {
       return
     }
-    // Why: folder-mode repos have no remotes to derive a GitLab project from;
-    // SSH-backed Git repos go through the same provider-aware IPC path.
+    // Why: folder-mode repos lack remotes to derive a GitLab project from; SSH-backed repos use the same provider-aware IPC path.
     const eligibleRepos = selectedRepos
     if (eligibleRepos.length === 0) {
       setGitlabItems([])
@@ -4980,9 +4845,7 @@ export default function TaskPage(): React.JSX.Element {
                   items: GitLabWorkItem[]
                   error?: { type?: string; message: string }
                 }
-                // Why: not_found just means "this repo isn't a GitLab project"
-                // (e.g. a GitHub-only repo in a mixed selection). Drop it
-                // silently so the GitLab list doesn't show false errors.
+                // Why: not_found just means the repo isn't a GitLab project (mixed selection); drop it so the list shows no false errors.
                 const error = typed.error?.type === 'not_found' ? undefined : typed.error
                 return { repoId: repo.id, items: typed.items, error }
               })
@@ -5027,9 +4890,7 @@ export default function TaskPage(): React.JSX.Element {
         }
         merged.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''))
         setGitlabItems(merged)
-        // Why: only surface an error banner when EVERY eligible repo failed.
-        // Mixed selections often include non-GitLab repos, and a partial
-        // banner would hide the working rows.
+        // Why: only banner when every eligible repo failed; a partial one would hide working rows in a mixed (non-GitLab) selection.
         if (errs.length > 0 && merged.length === 0) {
           setGitlabError(errs[0])
         }
@@ -5045,9 +4906,7 @@ export default function TaskPage(): React.JSX.Element {
     // eslint-disable-next-line react-hooks/exhaustive-deps -- selectedReposKey encodes the only selectedRepos fields read above; keying off the array ref would re-run on every parent render.
   }, [taskSource, gitlabView, activeGitlabFilter, gitlabRefreshNonce, selectedReposKey])
 
-  // Why: Todos fetch lives in its own effect — different trigger
-  // condition from the project view (no chip filter dependence) and a
-  // different data path (`gl.todos` is user-scoped, not repo-scoped).
+  // Why: Todos fetch has its own effect — different trigger (no chip filter) and data path (gl.todos is user-scoped, not repo-scoped).
   useEffect(() => {
     if (taskSource !== 'gitlab' || gitlabView !== 'todos') {
       return
@@ -5208,8 +5067,7 @@ export default function TaskPage(): React.JSX.Element {
     return teams.sort((a, b) => a.name.localeCompare(b.name))
   }, [displayedLinearIssues])
 
-  // Why: the full Linear team fetch is async and can temporarily be empty.
-  // Keep the selector usable from issue metadata until the complete list lands.
+  // Why: the full team fetch is async and briefly empty; keep the selector usable from issue metadata until the list lands.
   const linearTeamOptions = useMemo(() => {
     if (availableTeams.length === 0) {
       return linearIssueTeams
@@ -5226,8 +5084,7 @@ export default function TaskPage(): React.JSX.Element {
     })
   }, [availableTeams, linearIssueTeams])
 
-  // Why: team IDs belong to one Linear workspace. Switching workspaces while a
-  // saved subset exists must not leave the task list filtered by stale team IDs.
+  // Why: team IDs belong to one workspace, so a workspace switch must not leave the list filtered by stale team IDs.
   useEffect(() => {
     if (linearTeamOptions.length === 0) {
       return
@@ -5247,8 +5104,7 @@ export default function TaskPage(): React.JSX.Element {
   )
 
   const applyLinearAttributeFilter = useCallback((next: LinearIssueAttributeFilter) => {
-    // Why: batch filter + limit/page reset in one transition so the fetch
-    // effect never issues an old expanded-limit request for the new filter.
+    // Why: batch filter + limit/page reset so the fetch effect never issues an old expanded-limit request for the new filter.
     setLinearAttributeFilter(next)
     setLinearIssueLimit(LINEAR_ITEM_LIMIT)
     setLinearIssuePage(0)
@@ -5272,8 +5128,7 @@ export default function TaskPage(): React.JSX.Element {
     if (previousId === null || previousId === nextId) {
       return
     }
-    // Why: status/assignee/labels are team-scoped; clearing them is a filter change
-    // and must reset limit/page via applyLinearAttributeFilter (R6), not a bare set.
+    // Why: team-scoped facets; clearing them is a filter change, so reset limit/page via applyLinearAttributeFilter (R6), not a bare set.
     const next = teamDerivedFacetsForPrimaryTeamChange(linearAttributeFilter)
     if (
       linearIssueAttributeFilterSignature(linearAttributeFilter) ===
@@ -5292,8 +5147,7 @@ export default function TaskPage(): React.JSX.Element {
     if (activeLinearIssueContextLabel) {
       return displayedLinearIssues
     }
-    // Why: team options can be derived after issue rows render. Treat an
-    // empty selection as "all" until reconciliation has a concrete team set.
+    // Why: team options can arrive after issue rows render; treat an empty selection as "all" until reconciliation sets teams.
     if (displayedLinearIssues.length > 0 && linearTeamSelection.size === 0) {
       return displayedLinearIssues
     }
@@ -5374,9 +5228,7 @@ export default function TaskPage(): React.JSX.Element {
         return
       }
 
-      // Why: unlike GitHub's cursor pages, Linear reads are cached as an
-      // expanded prefix. Jumping to a new page first expands the prefix, then
-      // commits the page when the fetch returns enough rows.
+      // Why: Linear reads are cached as an expanded prefix; a page jump expands it and commits once enough rows arrive.
       setActiveLinearIssueLoadingTargetPage(page)
       ensureActiveLinearIssueLimit((page + 1) * LINEAR_ITEM_LIMIT)
     },
@@ -5410,9 +5262,7 @@ export default function TaskPage(): React.JSX.Element {
       return
     }
 
-    // Why: Linear can return more backend rows without immediately filling the
-    // next visible page after local team filtering. Keep expanding the prefix
-    // until the requested page exists or Linear reports exhaustion.
+    // Why: local filtering can leave the next page short, so keep expanding the prefix until the page exists or Linear is exhausted.
     ensureActiveLinearIssueLimit(activeLinearIssueLimit + LINEAR_ITEM_LIMIT)
   }, [
     activeLinearIssueCanRequestMore,
@@ -5461,8 +5311,7 @@ export default function TaskPage(): React.JSX.Element {
       next.delete(groupedProperty)
     }
 
-    // Why: a Team column repeats the same value when one team is selected.
-    // Keep it hidden until the user explicitly opts back into that property.
+    // Why: a Team column repeats the same value when one team is selected; keep it hidden until the user opts back in.
     if (linearTeamSelection.size <= 1 && !linearTeamPropertyTouched) {
       next.delete('team')
     } else if (linearTeamSelection.size > 1 && !linearTeamPropertyTouched) {
@@ -5795,8 +5644,7 @@ export default function TaskPage(): React.JSX.Element {
         }
       })
     return () => {
-      // Why: project lists are workspace-scoped; stale responses must not
-      // populate the composer after a team/workspace switch.
+      // Why: project lists are workspace-scoped; stale responses must not populate the composer after a team/workspace switch.
       cancelled = true
     }
   }, [
@@ -5809,8 +5657,7 @@ export default function TaskPage(): React.JSX.Element {
   ])
 
   useEffect(() => {
-    // Why: the selected team can change indirectly when the available Linear
-    // teams/workspace list refreshes, even if the explicit picker value did not.
+    // Why: the selected team can change indirectly when the Linear teams/workspace list refreshes, even if the picker value didn't.
     setNewLinearIssueStateId(null)
     setNewLinearIssueAssigneeId(null)
     setNewLinearIssuePriority(0)
@@ -6132,8 +5979,7 @@ export default function TaskPage(): React.JSX.Element {
         }
       })
     return () => {
-      // Why: create fields are scoped to project + issue type; ignore late
-      // responses after the user switches either selector.
+      // Why: create fields are scoped to project + issue type; ignore late responses after switching either selector.
       cancelled = true
     }
   }, [
@@ -6145,9 +5991,7 @@ export default function TaskPage(): React.JSX.Element {
     jiraTaskSourceContext
   ])
 
-  // Why: defense-in-depth safety net applied to the current page's items.
-  // The active tab scopes requests to issues or PRs, and this keeps stale
-  // cache rows from leaking across the split tabs.
+  // Why: defense-in-depth — keep stale cache rows from leaking across the issue/PR split tabs.
   const applyTypeFilter = useCallback(
     (items: GitHubWorkItem[]) => {
       return items.filter((item) => {
@@ -6250,8 +6094,7 @@ export default function TaskPage(): React.JSX.Element {
       lastLoadedPageIndex = index
     }
   }
-  // Why: when counts fail, a full loaded page is enough evidence to expose one
-  // more page without pretending unfetched sparse entries are empty results.
+  // Why: when counts fail, a full loaded page is enough evidence to expose one more page without faking empty results.
   const lastLoadedPageFull =
     (pages[lastLoadedPageIndex]?.length ?? 0) >= Math.max(1, githubPageSize)
   const fallbackTotalPages = lastLoadedPageFull
@@ -6262,8 +6105,7 @@ export default function TaskPage(): React.JSX.Element {
       ? Math.max(pages.length, countedTotalPages)
       : fallbackTotalPages
 
-  // Why: numbered provider pages support random access. Load only the clicked
-  // page so a high-page jump does not exhaust GitHub's Search API rate bucket.
+  // Why: load only the clicked page so a high-page jump doesn't exhaust GitHub's Search API rate bucket.
   const handleLoadNextPage = useCallback(
     async (targetPage?: number) => {
       if (paginationLoading || selectedRepos.length === 0) {
@@ -6346,12 +6188,7 @@ export default function TaskPage(): React.JSX.Element {
       githubSearchPersistReadyRef.current = true
       return
     }
-    // Why: persist the debounced applied query regardless of the active
-    // preset. The preset-click handler writes the canonical query for that
-    // preset, so persisting again here is at worst idempotent. When the
-    // user types into the search box `handleTaskSearchChange` clears the
-    // preset, but persisting unconditionally also covers paths that change
-    // appliedTaskSearch without going through that handler.
+    // Why: persist the applied query unconditionally to cover paths that change appliedTaskSearch outside the preset handler.
     setTaskResumeState({
       githubItemsPreset: activeTaskPreset,
       githubItemsQuery: appliedTaskSearch.trim()
@@ -6362,11 +6199,7 @@ export default function TaskPage(): React.JSX.Element {
     if (!taskResumeApplied) {
       return
     }
-    // Why: both early-return branches must clear `retryingSourceKeys` — if the
-    // user clicks Retry and then switches `taskSource` away from 'github' (or
-    // somehow ends up with zero repos selected) before the fetch dispatches,
-    // neither the `.then` nor the `.catch` below will fire, and the Retry
-    // button would stay stuck in its disabled/Retrying state indefinitely.
+    // Why: both early-return branches must clear retryingSourceKeys — if they fire, neither .then nor .catch runs and Retry stays stuck.
     if (taskSource !== 'github' || githubMode !== 'items') {
       setRetryingSourceKeys(new Set())
       setTasksRefreshing(false)
@@ -6380,16 +6213,11 @@ export default function TaskPage(): React.JSX.Element {
       return
     } // unreachable — multi-combobox forbids empty
 
-    // Why: `repo:owner/name` qualifiers are silently dropped before fan-out
-    // because in cross-repo mode they would pin every per-repo fetch to a
-    // single repo and zero out the rest. See stripRepoQualifiers.
+    // Why: strip repo:owner/name qualifiers before fan-out — cross-repo they'd pin every fetch to one repo. See stripRepoQualifiers.
     const q = stripRepoQualifiers(appliedTaskSearch.trim())
     let cancelled = false
 
-    // Why: paint cached rows synchronously before awaiting the fan-out so
-    // selection changes don't leave the previous selection's rows on screen
-    // for a frame. Any repo without a cache entry simply contributes nothing
-    // to this pre-paint; the fetch will fill it in.
+    // Why: paint cached rows synchronously before the fan-out so a selection change doesn't leave the prior rows on screen for a frame.
     const preMerged: GitHubWorkItem[] = []
     let anyUncached = false
     let anyRepoCached = false
@@ -6408,9 +6236,7 @@ export default function TaskPage(): React.JSX.Element {
         preMerged.push(...cached)
       }
     }
-    // Why: always replace — if preMerged is empty (e.g. query just changed and
-    // no repo has a cache entry for it), we clear the previous query's rows
-    // rather than leaving them on screen under the spinner.
+    // Why: always replace — an empty preMerged clears the previous query's rows instead of leaving them under the spinner.
     const page0 =
       preMerged.length > 0 ? sortWorkItemsByNumber(preMerged).slice(0, githubPageSize) : []
     setPages([page0])
@@ -6424,10 +6250,7 @@ export default function TaskPage(): React.JSX.Element {
     // Preserve the existing nonce-gated force behavior.
     const forceRefresh = taskRefreshNonce !== lastFetchedNonceRef.current
     lastFetchedNonceRef.current = taskRefreshNonce
-    // Why: a preference flip bumps `workItemsInvalidationNonce`. Treat that
-    // bump as a forced refresh so the fan-out bypasses the in-flight dedupe
-    // map — otherwise an overlapping request started before the flip could
-    // resolve the new fetch and repopulate the cache with pre-flip data.
+    // Why: treat a preference-flip nonce bump as a forced refresh so it bypasses the dedupe map and can't reuse pre-flip data.
     const preferenceInvalidated =
       workItemsInvalidationNonce !== lastFetchedInvalidationNonceRef.current
     lastFetchedInvalidationNonceRef.current = workItemsInvalidationNonce
@@ -6447,27 +6270,16 @@ export default function TaskPage(): React.JSX.Element {
         landingRefreshKey
       ])
     }
-    // Why: manual refresh keeps cached rows visible, so the normal
-    // `tasksLoading` flag may stay false. Track the forced fetch separately
-    // so the toolbar still shows a refresh-in-progress affordance.
+    // Why: manual refresh keeps cached rows (tasksLoading stays false), so track forced fetch separately for the toolbar spinner.
     setTasksRefreshing(forcedFetch)
 
-    // Why: snapshot the retrying source keys at effect-dispatch so overlapping
-    // retries don't clear each other's pending state. An earlier cancelled
-    // effect settling after a newer retry starts would otherwise wipe the
-    // newer retry's source from the set. Clearing only the keys captured
-    // when this effect dispatched preserves later additions.
+    // Why: snapshot retrying keys at dispatch so an earlier settling effect doesn't wipe a newer retry's pending source.
     const dispatchedRetrySourceKeys = retryingSourceKeys
     void fetchWorkItemsAcrossRepos(repoArgs, githubPerRepoPageLimit, githubPageSize, q, {
       ...deriveTaskPageGitHubWorkItemsFetchOptions(forcedFetch, shouldProbeOnLanding)
     })
       .then(({ items, failedCount: failed, githubUnavailable: unavailable }) => {
-        // Why: clear only the sources this effect was responsible for
-        // retrying (the snapshot captured at dispatch time). Overlapping
-        // retries — a second click while a prior fetch is still in flight
-        // — must not clear the newer source from the set, so we can't just
-        // reset the whole set here. The early-return branches above reset
-        // the whole set because those branches won't dispatch a fetch.
+        // Why: clear only the dispatch-time snapshot keys so an overlapping retry's newer source isn't wiped.
         setRetryingSourceKeys((prev) => {
           if (dispatchedRetrySourceKeys.size === 0) {
             return prev
@@ -6499,14 +6311,8 @@ export default function TaskPage(): React.JSX.Element {
         setTasksFiltering(false)
       })
       .catch((err) => {
-        // Why: fetchWorkItemsAcrossRepos swallows per-repo failures, so a
-        // reject here means an IPC-level or programmer error — surface it.
-        // Clear only the sources this effect was responsible for retrying
-        // (the snapshot captured at dispatch time). Overlapping retries —
-        // a second click while a prior fetch is still in flight — must
-        // not clear the newer source from the set, so we can't just reset
-        // the whole set here. The early-return branches above reset the
-        // whole set because those branches won't dispatch a fetch.
+        // Why: fetchWorkItemsAcrossRepos swallows per-repo failures, so a reject here is IPC/programmer error — surface it.
+        // Why: clear only the dispatch-time snapshot keys so an overlapping retry's newer source isn't wiped.
         setRetryingSourceKeys((prev) => {
           if (dispatchedRetrySourceKeys.size === 0) {
             return prev
@@ -6528,9 +6334,7 @@ export default function TaskPage(): React.JSX.Element {
         setTasksFiltering(false)
       })
 
-    // Why: fire-and-forget count query in parallel with the items fetch.
-    // The search API is cached 120s server-side so this doesn't add
-    // meaningful latency or rate-limit pressure.
+    // Why: fire-and-forget count query alongside the items fetch; the search API is cached 120s server-side so it adds little cost.
     void countWorkItemsAcrossRepos(
       selectedRepos.map((r) => ({
         repoId: r.id,
@@ -6549,10 +6353,7 @@ export default function TaskPage(): React.JSX.Element {
     return () => {
       cancelled = true
     }
-    // Why: getCachedWorkItems and fetchWorkItemsAcrossRepos are stable zustand
-    // selectors; depending on them would re-run the effect on unrelated store
-    // updates. `workItemsInvalidationNonce` is explicitly included so a
-    // preference flip (which only evicts cache) re-dispatches this effect.
+    // Why: store selectors are stable (omit from deps); workItemsInvalidationNonce included so a preference flip re-dispatches.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     selectedRepos,
@@ -6567,9 +6368,7 @@ export default function TaskPage(): React.JSX.Element {
   const applyPRFilterChange = useCallback(
     (change: PRFilterChange): void => {
       let next = scopeGitHubTaskSearch(taskSearchInput, activeGithubTaskKind)
-      // Why: each filter dropdown contributes an independent qualifier patch.
-      // `withQualifier` round-trips through parseTaskQuery so prior filters and
-      // free-text are preserved.
+      // Why: withQualifier round-trips through parseTaskQuery so each dropdown's patch preserves prior filters and free-text.
       if ('author' in change) {
         next = withQualifier(next, 'author', change.author ?? null)
       }
@@ -6589,9 +6388,7 @@ export default function TaskPage(): React.JSX.Element {
         next = withQualifier(next, 'draft', change.draft ? 'true' : 'false')
       }
       if ('reviewer' in change) {
-        // Why: the two reviewer qualifiers (review-requested vs reviewed-by) are
-        // mutually exclusive in the PR-list UX — clear the other axis whenever
-        // one is set so the chip's visible state matches the actual query.
+        // Why: the two reviewer qualifiers are mutually exclusive — clear the other whenever one is set so the chip matches the query.
         const reviewer = change.reviewer ?? null
         if (reviewer === null) {
           next = withQualifier(next, 'reviewRequested', null)
@@ -6608,9 +6405,7 @@ export default function TaskPage(): React.JSX.Element {
       setAppliedTaskSearch(next)
       setActiveTaskPreset(null)
       setTaskResumeState({ githubItemsPreset: null, githubItemsQuery: next })
-      // Why: filter changes replace the meaning of every row. Showing stale
-      // rows while the filtered query resolves reads like the filter did
-      // nothing, so render the same skeleton used for an uncached initial load.
+      // Why: a filter change replaces every row's meaning; show the load skeleton so stale rows don't read as if the filter did nothing.
       setTasksFiltering(true)
       setTaskRefreshNonce((current) => current + 1)
     },
@@ -6633,8 +6428,7 @@ export default function TaskPage(): React.JSX.Element {
       const scoped = scopeGitHubTaskSearch(next, activeGithubTaskKind)
       setTaskSearchInput(next)
       setActiveTaskPreset(null)
-      // Why: the visible rows are keyed by appliedTaskSearch, not the draft
-      // input. Hide stale rows as soon as the draft would change the query.
+      // Why: visible rows are keyed by appliedTaskSearch, not the draft input; hide stale rows once the draft changes the query.
       setTasksFiltering(scoped !== appliedTaskSearch)
     },
     [activeGithubTaskKind, appliedTaskSearch]
@@ -6642,9 +6436,7 @@ export default function TaskPage(): React.JSX.Element {
 
   const handleSetDefaultTaskPreset = useCallback(
     (presetId: TaskViewPresetId): void => {
-      // Why: the default task view is a durable preference, so right-clicking a
-      // preset updates the persisted settings instead of only changing the
-      // current page state.
+      // Why: the default task view is a durable preference, so persist it instead of only changing page state.
       void updateSettings({ defaultTaskViewPreset: presetId }).catch(() => {
         toast.error(
           translate('auto.components.TaskPage.fe380f306c', 'Failed to save default task view.')
@@ -6870,8 +6662,7 @@ export default function TaskPage(): React.JSX.Element {
               labels: newIssueLabels,
               assignees: newIssueAssignees.map((assignee) => assignee.login)
             },
-            // Why: oversized-body recovery can require two 30-second writes
-            // after GitHub rejects the initial create request.
+            // Why: oversized-body recovery can need two 30s writes after GitHub rejects the initial create.
             { timeoutMs: 65_000 }
           )
         : await window.api.gh.createIssue({
@@ -6913,8 +6704,7 @@ export default function TaskPage(): React.JSX.Element {
       }
       setNewIssueOpen(false)
       if (result.bodySaveWarning) {
-        // Why: retain the unsaved body for recovery, but clear the title so
-        // reopening the composer cannot repeat the create with one click.
+        // Why: keep the unsaved body for recovery but clear the title so reopening can't one-click repeat the create.
         setNewIssueTitle('')
         setNewIssueDraft({ title: '' })
       } else {
@@ -6922,16 +6712,13 @@ export default function TaskPage(): React.JSX.Element {
         setNewIssueBody('')
         setNewIssueLabels([])
         setNewIssueAssignees([])
-        // Why: only a complete success discards the recovery draft; a partial
-        // body save keeps the original text available without another create.
+        // Why: only a complete success discards the recovery draft; a partial body save keeps the text for recovery.
         clearNewIssueDraft()
       }
       // Why: bump the nonce so the list refetches and shows the new issue.
       setTaskRefreshNonce((current) => current + 1)
 
-      // Why: auto-open the new issue in the dialog so the user sees
-      // exactly what was filed. Use an optimistic stub first so the dialog
-      // has immediate content, then refine with the full `workItem` fetch.
+      // Why: auto-open the new issue with an optimistic stub for immediate content, then refine with the full workItem fetch.
       const stub: GitHubWorkItem = {
         id: `issue:${String(result.number)}`,
         repoId: newIssueTargetRepo.id,
@@ -6971,10 +6758,7 @@ export default function TaskPage(): React.JSX.Element {
       void fullIssuePromise
         .then((full) => {
           if (full) {
-            // Why: `full` is `Omit<GitHubWorkItem, 'repoId'>` (IPC shape).
-            // Cast through unknown: spreading a discriminated union loses the
-            // discriminant, so `{ ...full, repoId }` doesn't typecheck as
-            // GitHubWorkItem. The runtime shape is correct by construction.
+            // Why: cast through unknown — spreading the discriminated union loses the discriminant, so { ...full, repoId } won't typecheck.
             const withRepoId = { ...full, repoId: stubRepoId } as unknown as GitHubWorkItem
             setDialogWorkItem(withRepoId)
           }
@@ -7155,8 +6939,7 @@ export default function TaskPage(): React.JSX.Element {
       setLinearRefreshNonce((n) => n + 1)
       useAppStore.getState().recordFeatureInteraction('linear-tasks')
 
-      // Why: auto-select the new issue in the inline workspace so the user
-      // sees exactly what was filed, mirroring the GitHub create-issue flow.
+      // Why: auto-select the new issue so the user sees exactly what was filed (mirrors the GitHub create-issue flow).
       void linearGetIssue(
         linearTaskSourceContext ?? settings,
         result.id,
@@ -7255,8 +7038,7 @@ export default function TaskPage(): React.JSX.Element {
             return
           }
           if (full) {
-            // Why: the list cache may still be fresh after create; insert the
-            // new row locally before selecting it so the inspector stays open.
+            // Why: list cache may still be fresh after create; insert the new row locally before selecting so the inspector stays open.
             setJiraIssues((prev) => [full, ...prev.filter((issue) => issue.key !== full.key)])
             setSelectedJiraIssue(full)
           }
@@ -7308,9 +7090,7 @@ export default function TaskPage(): React.JSX.Element {
         return
       }
 
-      // Why: Esc should first dismiss the focused control so users can back
-      // out of text entry without accidentally closing the whole page.
-      // Once focus is already outside an input, Esc closes the tasks page.
+      // Why: Esc first blurs a focused input so it doesn't accidentally close the whole page; only closes once focus is outside an input.
       if (
         target instanceof HTMLInputElement ||
         target instanceof HTMLTextAreaElement ||
@@ -7363,8 +7143,7 @@ export default function TaskPage(): React.JSX.Element {
     refreshPreflightStatus
   ])
 
-  // Why: debounce the Linear search input so we don't fire a request on every
-  // keystroke — matches the 300ms cadence used for GitHub search.
+  // Why: debounce the Linear search input so we don't fire a request per keystroke (300ms, matching GitHub search).
   useEffect(() => {
     if (!taskResumeApplied) {
       return
@@ -7399,8 +7178,7 @@ export default function TaskPage(): React.JSX.Element {
     taskSource
   ])
 
-  // Why: fetch Linear issues when the tab is active and connected. Empty search
-  // uses the plain `all` list with optional server-side attribute filters.
+  // Why: fetch Linear issues when the tab is active and connected; empty search uses the `all` list with server-side filters.
   useEffect(() => {
     if (!taskResumeApplied) {
       return
@@ -7480,8 +7258,7 @@ export default function TaskPage(): React.JSX.Element {
       ])
     }
 
-    // Why: cached rows should remain visible on navigation. Only an explicit
-    // refresh or a true cache miss needs the blocking loading state.
+    // Why: keep cached rows visible on navigation; only explicit refresh or a true cache miss shows the blocking loading state.
     setLinearLoading(forceRefresh || cachedResult === null)
 
     const request =
@@ -7542,8 +7319,7 @@ export default function TaskPage(): React.JSX.Element {
     return () => {
       cancelled = true
     }
-    // Why: searchLinearIssues and listLinearIssues are stable zustand selectors;
-    // depending on them would re-run the effect on unrelated store updates.
+    // Why: searchLinearIssues/listLinearIssues are stable selectors; adding them would re-run the effect on unrelated store updates.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     taskSource,
@@ -7729,8 +7505,7 @@ export default function TaskPage(): React.JSX.Element {
     const force = linearRefreshNonce > 0
     setLinearCustomViewsLoading(force || !allCached)
     setLinearCustomViewsError(null)
-    // Why: the Views tab already has a Model column, so listing both view
-    // models avoids a second, redundant Issues/Projects switch.
+    // Why: the Views tab already has a Model column, so list both models rather than add a redundant Issues/Projects switch.
     void Promise.all(
       LINEAR_CUSTOM_VIEW_MODELS.map((model) =>
         listLinearCustomViews(model, LINEAR_ITEM_LIMIT, undefined, {
@@ -7843,10 +7618,7 @@ export default function TaskPage(): React.JSX.Element {
       return
     }
 
-    // Why: the corrected Linear surface is list-first. Keep an open inspector
-    // only while its issue remains in the current filter instead of auto-opening
-    // the first row and turning the list back into navigation chrome. Related
-    // sub-issue navigation is allowed to stay open because it is user-directed.
+    // Why: list-first — keep an open inspector only while its issue stays in the filter, not auto-open row 1; user-directed sub-issue nav stays.
     if (
       selectedLinearIssueId &&
       !selectedLinearIssueCanFloat &&
@@ -7992,10 +7764,7 @@ export default function TaskPage(): React.JSX.Element {
     taskSource
   ])
 
-  // Why: for Linear issues the "Use" flow opens the composer with the issue
-  // info adapted to the LinkedWorkItemSummary shape. Linear identifiers are
-  // strings (e.g. "ENG-123") so we use 0 as a placeholder number since the
-  // provider-generic work item shape still expects numeric issue metadata.
+  // Why: Linear ids are strings (e.g. "ENG-123") but the provider-generic shape needs a numeric number, so the adapter uses 0 as placeholder.
   const openComposerForLinearItem = useCallback(
     (issue: LinearIssue): void => {
       const linkedWorkItem = buildLinearIssueLinkedWorkItem(issue)
@@ -8011,10 +7780,7 @@ export default function TaskPage(): React.JSX.Element {
 
   const handleUseLinearItem = useCallback(
     (issue: LinearIssue): void => {
-      // Why: same rationale as handleUseWorkItem — open the New Workspace
-      // dialog pre-filled rather than yolo-creating the worktree, so the
-      // user can confirm name / agent / setup before the worktree lands in
-      // the sidebar. Telemetry attribution flows via openComposerForLinearItem.
+      // Why: like handleUseWorkItem — open the pre-filled dialog instead of creating the worktree directly, so the user confirms name/agent/setup.
       useAppStore.getState().recordFeatureInteraction('linear-tasks')
       openComposerForLinearItem(issue)
     },
@@ -8129,12 +7895,7 @@ export default function TaskPage(): React.JSX.Element {
   return (
     <div className="relative flex h-full min-h-0 flex-1 overflow-hidden bg-background text-foreground">
       <div className="relative flex min-h-0 min-w-0 flex-1 flex-col">
-        {/* Why: pt-1.5 vertically centers this row's 32px icon cluster (X +
-            source toggles) with the sidebar's "Tasks" nav row. Sidebar Tasks
-            center sits 22px below the titlebar (pt-2 + py-1.5 + half size-4
-            icon). Matching that here needs 6px top padding above the 32px
-            cluster (6 + 16 = 22). The previous pt-3 placed the cluster 6px
-            too low, breaking the visual band across the top chrome. */}
+        {/* Why: pt-1.5 (6px) aligns this 32px icon cluster's center with the sidebar Tasks row, 22px below the titlebar. */}
         <div className="mx-auto flex min-h-0 min-w-0 w-full flex-1 flex-col px-5 pt-1.5 pb-4 md:px-8 md:pt-1.5 md:pb-5">
           <div
             className={cn('flex-none flex flex-col gap-2', taskPageListChromeHidden && 'hidden')}
@@ -8146,10 +7907,7 @@ export default function TaskPage(): React.JSX.Element {
                     className="flex min-w-0 flex-wrap items-center gap-2"
                     data-contextual-tour-target="tasks-source-filters"
                   >
-                    {/* Why: Close is anchored left in the same row as the
-                        source icons so the top chrome is one compact band.
-                        Left-aligned keeps it clear of the app sidebar on the
-                        right edge. */}
+                    {/* Why: Close is anchored left with the source icons for one compact band, clear of the app sidebar on the right. */}
                     <Tooltip>
                       <TooltipTrigger asChild>
                         <Button
@@ -8371,8 +8129,7 @@ export default function TaskPage(): React.JSX.Element {
                         })}
                       </div>
                     ) : null}
-                    {/* Why: Project rows are now repo-scoped too, so the
-                        selection must stay visible in both GitHub modes. */}
+                    {/* Why: Project rows are repo-scoped, so the selection must stay visible in both GitHub modes. */}
                     <div className="min-w-0 max-w-[220px] shrink-0">
                       <TaskProjectSourceCombobox
                         groups={taskPickerGroups}
@@ -8545,11 +8302,7 @@ export default function TaskPage(): React.JSX.Element {
                               variant="outline"
                               size="icon"
                               onClick={() => {
-                                // Why: restore a content-non-empty draft instead
-                                // of resetting, so an accidental dismissal is
-                                // recoverable. The empty-default branch stays live
-                                // so a stale draft never hijacks a fresh open after
-                                // the user changed their primary/selected repo.
+                                // Why: restore a non-empty draft (accidental dismissal recoverable); empty default guards a stale draft after a repo change.
                                 const seed = resolveNewIssueOpenSeed({
                                   draft: useAppStore.getState().newIssueDraft,
                                   selectedRepoIds: selectedRepos.map((r) => r.id)
@@ -8619,13 +8372,7 @@ export default function TaskPage(): React.JSX.Element {
                     </div>
 
                     {(() => {
-                      // Why: unify feature 1 (indicator) and feature 2 (selector)
-                      // into a single chip per repo. Rendering both separately
-                      // produced visually redundant output — two local-repo
-                      // badge labels, duplicate slugs. The selector's active pill
-                      // + tooltip already announce the source, so the "Issues
-                      // from {slug}" chip is only shown when the selector does
-                      // not render (no upstream remote — nothing to toggle).
+                      // Why: show the source-slug chip only when the selector can't render (no upstream to toggle); otherwise it duplicates the selector.
                       const rows = perRepoSourceState.filter(
                         (s) => hasUpstreamCandidateDivergence(s) || hasDivergentSources(s)
                       )
@@ -8638,10 +8385,7 @@ export default function TaskPage(): React.JSX.Element {
                             const repo = selectedRepos.find((r) => r.id === s.repoId)
                             const showRepoBadgeLabel = selectedRepos.length > 1 && repo
                             const selectorRenderable = hasUpstreamCandidateDivergence(s)
-                            // Why: the static indicator has its own wrapping
-                            // chip styles, so we render it standalone and don't
-                            // nest it inside our own chip — nesting would
-                            // double-border it.
+                            // Why: render the indicator standalone — it has its own chip styles, so nesting it in our chip would double-border it.
                             if (!selectorRenderable && hasDivergentSources(s)) {
                               return (
                                 <IssueSourceIndicator
@@ -8659,12 +8403,7 @@ export default function TaskPage(): React.JSX.Element {
                             if (!selectorRenderable || !repo) {
                               return null
                             }
-                            // Why: must be a <div> (not <span>) because the child
-                            // <IssueSourceSelector> renders a <div role="group">, and
-                            // a block-level <div> nested inside an inline <span> is
-                            // invalid HTML — React emits a hydration warning and
-                            // browsers may auto-close the span. `issueSourceChipClass`
-                            // uses `inline-flex`, so the visual rendering is identical.
+                            // Why: <div> not <span> — the child selector renders a block <div> (div-in-span is invalid HTML); inline-flex class looks identical.
                             return (
                               <div key={s.repoId} className={issueSourceChipClass}>
                                 {showRepoBadgeLabel ? (
@@ -9267,9 +9006,7 @@ export default function TaskPage(): React.JSX.Element {
                 style={{ scrollbarGutter: 'stable' }}
               >
                 <div
-                  // Why: z-40 must beat the data rows' sticky left cells (z-20);
-                  // this container is a stacking context, so its z sets the whole
-                  // header's level — at z-10 the rows' sticky cells painted over it.
+                  // Why: z-40 must beat the rows' sticky left cells (z-20); this stacking context's z sets the whole header's level.
                   className={cn(
                     'sticky top-0 z-40 grid gap-2 border-b border-border/50 px-3 py-2 text-[10px] font-medium uppercase tracking-[0.16em] text-muted-foreground',
                     GITHUB_TASK_ROW_SURFACE_CLASS,
@@ -9305,9 +9042,7 @@ export default function TaskPage(): React.JSX.Element {
                 ) : null}
 
                 {!tasksError && githubUnavailable ? (
-                  // Why: attribute a GitHub availability failure explicitly so
-                  // an empty list doesn't read as an Orca bug. Takes priority
-                  // over the generic count banner below.
+                  // Why: name the GitHub outage explicitly so an empty list isn't misread as an Orca bug; takes priority over the count banner.
                   <div
                     role="alert"
                     className="border-b border-border/50 bg-destructive/10 px-4 py-3 text-sm text-destructive"
@@ -9320,8 +9055,7 @@ export default function TaskPage(): React.JSX.Element {
                 ) : null}
 
                 {!tasksError && !githubUnavailable && failedCount > 0 ? (
-                  // Why: per-repo partial-failure signal — distinct from a hard
-                  // IPC reject (tasksError). The two are mutually exclusive.
+                  // Why: per-repo partial-failure signal, distinct from a hard IPC reject (tasksError); the two are mutually exclusive.
                   <div className="border-b border-border/50 bg-amber-500/10 px-4 py-3 text-sm text-amber-700 dark:text-amber-200">
                     {failedCount} {translate('auto.components.TaskPage.7762f4b03a', 'of')}{' '}
                     {selectedRepos.length}{' '}
@@ -9333,20 +9067,12 @@ export default function TaskPage(): React.JSX.Element {
                   .filter((s) => s.error)
                   .map((s) => {
                     const err = s.error!
-                    // Why: parent design doc §2 — when the issue fetch fails
-                    // (e.g. a 403 on a private upstream) we render a retryable
-                    // banner with slug-qualified copy instead of a silent
-                    // empty list. The [Retry] action re-invokes the fetch
-                    // with force=true via the shared refresh nonce so any
-                    // still-failing in-flight request is invalidated first.
+                    // Why: Retry re-fetches force=true via the shared refresh nonce, invalidating any still-failing in-flight request first.
                     return (
                       <div
                         key={`source-err-${s.repoId}`}
                         role="alert"
-                        // Why: aria-atomic ensures screen readers re-announce the full banner
-                        // when retry produces a new error on the same repo. Without it, React's
-                        // reconciliation (stable key per repo) may diff-only the changed text
-                        // node and some assistive tech will miss the update.
+                        // Why: aria-atomic re-announces the whole banner on a new same-repo error SRs would otherwise miss (stable key → text-only diff).
                         aria-atomic="true"
                         className="flex items-center justify-between gap-3 border-b border-border/50 bg-destructive/10 px-4 py-3 text-sm text-destructive"
                       >
@@ -9380,10 +9106,7 @@ export default function TaskPage(): React.JSX.Element {
                   })}
 
                 {showGitHubTaskSkeletons ? (
-                  // Why: render enough shimmer rows to fill a typical viewport
-                  // so the table doesn't visibly grow when results land. A
-                  // 3-row stub jumps to ~30 real rows; matching the steady-
-                  // state height keeps layout stable across the load.
+                  // Why: fill a typical viewport with shimmer rows so the table doesn't jump in height when results land.
                   <div className="divide-y divide-border/50">
                     {Array.from({ length: 12 }).map((_, i) => (
                       <div key={i} className={cn('grid gap-2 px-3 py-2', githubTaskGridClass)}>
@@ -9427,12 +9150,7 @@ export default function TaskPage(): React.JSX.Element {
                   </div>
                 ) : null}
 
-                {/* Why: suppress the generic empty state when any error banner is
-                    visible (IPC reject via tasksError, GitHub-unavailable outage,
-                    cross-repo partial failure via failedCount, or per-repo
-                    issue-side error). Showing "No matching GitHub work" next to
-                    "Couldn't load issues from X/Y" is contradictory and misleads
-                    the user into thinking they typed the wrong query. */}
+                {/* Why: hide the empty state while any error banner shows, so "No matching work" doesn't contradict "Couldn't load issues". */}
                 {!showGitHubTaskSkeletons &&
                 filteredWorkItems.length === 0 &&
                 !tasksError &&
@@ -9486,18 +9204,9 @@ export default function TaskPage(): React.JSX.Element {
                         </span>
                       )
                       return (
-                        // Why: the row is a clickable container rather than a
-                        // <button> because it holds nested interactive elements
-                        // (Use button, ellipsis DropdownMenuTrigger, Radix
-                        // TooltipTrigger). A <button> ancestor of another
-                        // <button> is invalid HTML and triggers React hydration
-                        // errors that break rendering of the whole page.
+                        // Why: clickable div not a <button> — it nests buttons, and button-in-button is invalid HTML that breaks hydration.
                         <div
-                          // Why: combine repoId with item.id because two selected repos
-                          // that route issues through the same upstream (e.g. fork +
-                          // non-fork both resolving to stablyai/orca) surface the same
-                          // item.id under different repoIds. React treats a bare id as
-                          // a collision and warns + silently drops rows otherwise.
+                          // Why: key on repoId+item.id — repos sharing an upstream reuse item.id, so a bare key collides and React silently drops rows.
                           key={`${item.repoId}:${item.id}`}
                           role="button"
                           tabIndex={0}
@@ -9509,9 +9218,7 @@ export default function TaskPage(): React.JSX.Element {
                             }
                           }}
                           className={cn(
-                            // Why: hover uses the same opaque muted-70% mix as the sticky
-                            // ID/Title cells (GITHUB_TASK_ROW_HOVER_SURFACE_CLASS) so the
-                            // left columns don't show a different shade than the rest of the row.
+                            // Why: hover uses the same opaque muted-70% mix as the sticky ID/Title cells so the left columns match the rest of the row.
                             'group/github-task-row grid cursor-pointer gap-2 px-3 py-2 text-left transition-colors hover:[background:color-mix(in_srgb,var(--muted)_70%,var(--background))] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50',
                             githubTaskGridClass
                           )}
@@ -9543,8 +9250,7 @@ export default function TaskPage(): React.JSX.Element {
                                 />
                               ) : null}
                               {selectedRepos.length > 1 && itemRepo ? (
-                                // Why: disambiguate rows when multiple repos are in
-                                // the merged list — a single-repo view doesn't need it.
+                                // Why: disambiguate rows in the merged multi-repo list; a single-repo view doesn't need it.
                                 <RepoBadgeLabel
                                   name={itemRepo.displayName}
                                   color={itemRepo.badgeColor}
@@ -9732,8 +9438,7 @@ export default function TaskPage(): React.JSX.Element {
                             ) : (
                               <Button
                                 type="button"
-                                // Why: Open resumes an existing workspace — solid primary so it
-                                // reads as the stronger action vs outline Start (new workspace).
+                                // Why: Open resumes an existing workspace — solid primary reads stronger than outline Start (new workspace).
                                 variant={attachedWorkspace ? 'default' : 'outline'}
                                 size="xs"
                                 data-contextual-tour-target="tasks-start-workspace"
@@ -9810,9 +9515,7 @@ export default function TaskPage(): React.JSX.Element {
                 </div>
               </div>
 
-              {/* Why: pagination sits outside the scroll container so it
-                  remains pinned at the bottom of the panel rather than
-                  hiding below the last row inside the scrolling region. */}
+              {/* Why: pagination sits outside the scroll container so it stays pinned at the panel bottom instead of scrolling away. */}
               {filteredWorkItems.length > 0 && !showGitHubTaskSkeletons && totalPages > 1 ? (
                 <div className="flex-none border-t border-border/50 bg-muted/50">
                   <PaginationBar
@@ -9903,9 +9606,7 @@ export default function TaskPage(): React.JSX.Element {
                       }
                     >
                       <span className="text-xs text-muted-foreground">
-                        {/* Why: GitLab action_name uses snake_case (assigned,
-                            review_requested, build_failed). Replace _ with
-                            space so the row reads like a sentence. */}
+                        {/* Why: GitLab action_name is snake_case (review_requested); swap _ for space so the row reads like a sentence. */}
                         {todo.actionName.replace(/_/g, ' ')}
                       </span>
                       <span className="min-w-0 truncate text-sm">{todo.targetTitle}</span>
@@ -9942,10 +9643,7 @@ export default function TaskPage(): React.JSX.Element {
                   </div>
                 ) : null}
                 {gitlabLoading && gitlabItems.length === 0 ? (
-                  // Why: matches the GitHub / Linear shimmer pattern so the card
-                  // never flashes empty during the initial fetch. Row count is
-                  // tuned to fill the viewport so the table doesn't visibly
-                  // grow when real rows land.
+                  // Why: shimmer rows fill the viewport so the card never flashes empty and the table doesn't jump when real rows land.
                   <div className="divide-y divide-border/50">
                     {Array.from({ length: 12 }).map((_, i) => (
                       <div
@@ -9975,11 +9673,7 @@ export default function TaskPage(): React.JSX.Element {
                 ) : null}
                 <div className="divide-y divide-border/50">
                   {displayedGitLabItems.map((item) => (
-                    // Why: row uses a <div role="button"> rather than a
-                    // <button> because it nests an inner button for
-                    // open-in-browser. Native <button> nesting is invalid
-                    // HTML and React warns; the role + tabIndex + keyDown
-                    // handler preserve a11y semantics.
+                    // Why: div role="button" not a <button> — it nests an open-in-browser button, and button-in-button is invalid HTML.
                     <div
                       role="button"
                       tabIndex={0}
@@ -9998,9 +9692,7 @@ export default function TaskPage(): React.JSX.Element {
                       className="grid w-full cursor-pointer gap-3 px-3 py-2 text-left grid-cols-[80px_minmax(0,3fr)_120px_110px_50px] hover:bg-muted/50"
                     >
                       <span className="font-mono text-xs text-muted-foreground">
-                        {/* Why: GitLab's user-facing convention is `!N` for MRs
-                            and `#N` for issues — matches gitlab.com's UI so users
-                            scanning the list can map rows back to web links. */}
+                        {/* Why: GitLab uses !N for MRs and #N for issues — match gitlab.com so rows map to web links. */}
                         {item.type === 'mr' ? '!' : '#'}
                         {item.number}
                       </span>
@@ -11181,18 +10873,7 @@ export default function TaskPage(): React.JSX.Element {
               {translate('auto.components.TaskPage.d3d0998b7d', 'New GitHub issue')}
             </DialogTitle>
             {(() => {
-              // Why: parent design doc §1 surface 2 — the composer is the
-              // non-negotiable surface because User D's regression (filing a
-              // personal TODO against upstream/fork after #1076 changed
-              // routing) is specifically about this dialog. The description
-              // line doubles as the source indicator: inlining the resolved
-              // `{owner}/{repo}` slug (e.g. "stablyai/orca") means the
-              // destination is impossible to miss before the user submits,
-              // without needing a secondary chip that duplicates the info.
-              // Falls back to the local displayName when the slug isn't
-              // resolved yet (pre-IPC cache hit, or non-GitHub remote). The
-              // multi-repo case uses the same computation — the Select below
-              // drives `newIssueTargetRepo`, so the active target is known.
+              // Why: inline the resolved {owner}/{repo} slug as the source indicator; fall back to displayName when unresolved.
               const entry = newIssueTargetRepo
                 ? perRepoSourceState.find((s) => s.repoId === newIssueTargetRepo.id)
                 : undefined
@@ -11208,20 +10889,8 @@ export default function TaskPage(): React.JSX.Element {
               )
             })()}
             {(() => {
-              // Why: mirror the Tasks-view selector in the composer so User D
-              // (fork contributor filing a personal TODO against their own
-              // fork) can flip the target *at the moment of filing* — the
-              // only moment that matters for this regression. Reuses the
-              // same cache entry the description line reads so no extra
-              // IPC round-trip is needed.
-              //
-              // Why sibling of DialogDescription (not nested inside it):
-              // DialogDescription renders a <p>, and `IssueSourceSelector`
-              // renders a <div role="group"> with <button>s inside. Nesting
-              // a div inside a <p> is invalid HTML — React emits a hydration
-              // warning and some a11y tools flag it. Rendering the selector
-              // as a sibling keeps both surfaces in the same header band
-              // without the nesting violation.
+              // Why: mirror the Tasks-view target selector so a fork contributor can flip target at filing time (fork-routing regression #1076).
+              // Sibling (not nested) because DialogDescription renders a <p> and the selector a <div> — nesting is invalid HTML.
               if (!newIssueTargetRepo) {
                 return null
               }
@@ -11241,10 +10910,7 @@ export default function TaskPage(): React.JSX.Element {
                     origin={entry.sources.originCandidate}
                     upstream={entry.sources.upstreamCandidate}
                     disabled={newIssueSubmitting}
-                    // Why: the composer only files issues, so the "Issues from
-                    // <slug>" tooltip restates what the surrounding form already
-                    // implies. Keep it on the Tasks header (that page also lists
-                    // PRs, which the selector doesn't affect).
+                    // Why: composer only files issues, so the source tooltip is redundant here (kept on the Tasks header, which also lists PRs).
                     suppressTooltip
                     onChange={(next) => {
                       void setIssueSourcePreference(
@@ -11267,9 +10933,7 @@ export default function TaskPage(): React.JSX.Element {
                 <Select
                   value={newIssueRepoId ?? undefined}
                   onValueChange={(v) => {
-                    // Why: repo-scoped labels/assignees can't cross a genuine
-                    // user repo switch, so clear them imperatively here (co-located
-                    // with the cause). Restore never routes through this handler.
+                    // Why: repo-scoped labels/assignees can't survive a real repo switch, so clear them here (restore never routes through this handler).
                     setNewIssueRepoId(v)
                     const reset = resolveUserRepoSwitchReset()
                     setNewIssueLabels(reset.labels)
@@ -12661,9 +12325,7 @@ export default function TaskPage(): React.JSX.Element {
 
       <GitLabItemDialog
         item={gitlabDialogItem}
-        // Why: dialog's repoPath has to come from the clicked item's
-        // own repo, not primaryRepo — items may originate in any of
-        // the selected repos now that the GitLab fetch is multi-repo.
+        // Why: repoPath comes from the clicked item's own repo, not primaryRepo — the GitLab fetch is now multi-repo.
         repoPath={gitlabDialogRepo?.path ?? null}
         repoId={gitlabDialogItem?.repoId ?? null}
         sourceContext={gitlabDialogSourceContext}
diff --git a/src/renderer/src/components/Terminal.tsx b/src/renderer/src/components/Terminal.tsx
index 5c2b0830aff..f093cdcf95b 100644
--- a/src/renderer/src/components/Terminal.tsx
+++ b/src/renderer/src/components/Terminal.tsx
@@ -139,11 +139,7 @@ import { browserWorkspaceHasRemoteOwner } from '@/runtime/remote-browser-tab-own
 
 const EditorPanel = lazy(() => import('./editor/EditorPanel'))
 
-// Why: after a close-dialog handler advances the queue and renders the next
-// dialog, gate new handler runs for this long so a stray carry-over click
-// from the prior dialog can't silently act on the new one. Short enough to
-// feel responsive on a deliberate follow-up click; long enough to absorb the
-// trailing edge of a physical double-click (~150 ms on most hardware).
+// Why: gate handler runs after a dialog advances so a stray carry-over click can't act on the next dialog; ~200ms absorbs a physical double-click while staying responsive.
 const CLOSE_DIALOG_DEBOUNCE_MS = 200
 const EDITOR_TAB_CONTENT_TYPES = new Set<TabContentType>([
   'editor',
@@ -326,12 +322,7 @@ function Terminal(): React.JSX.Element | null {
   const tabBarOrder = renderedActiveWorktreeId
     ? tabBarOrderByWorktree[renderedActiveWorktreeId]
     : undefined
-  // Why (anchored to selected thread, not active tab): the activity page
-  // publishes the full {target, worktreeId, tabId} descriptor sourced from
-  // its selectedThread. Deriving worktreeId/tabId from activeWorktreeId/
-  // activeTabId here used to flash the wrong terminal — selectThread updates
-  // the store in multiple steps and intermediate renders briefly pointed the
-  // portal at the new worktree's stale last-active tab.
+  // Why: use the activity page's selectedThread descriptor, not activeWorktreeId/activeTabId — selectThread updates the store in steps, so deriving here flashed the wrong terminal.
   const activityTerminalPortals: ActivityTerminalPortalTarget[] = useActivityTerminalPortals(
     activeView === 'activity'
   )
@@ -347,8 +338,7 @@ function Terminal(): React.JSX.Element | null {
   }, [activeTabId, activeTabType, activeView, activityTerminalPortals])
 
   useEffect(() => {
-    // Why: hibernation must treat terminals portaled into foreground surfaces
-    // as visible even when they are not the singular active terminal tab.
+    // Why: hibernation must treat terminals portaled into foreground surfaces as visible even when not the active tab.
     setForegroundTerminalTabIds(foregroundTerminalTabIds)
     return () => setForegroundTerminalTabIds([])
   }, [foregroundTerminalTabIds])
@@ -359,17 +349,14 @@ function Terminal(): React.JSX.Element | null {
   )
   useTerminalProviderSnapshotCapability(workspaceSessionReady && hydrationSucceeded)
 
-  // Why: the TabBar is rendered into the titlebar via a portal so tabs share
-  // the same row as the "Orca" title. The target element is created by App.tsx.
+  // Why: TabBar portals into the titlebar (target created by App.tsx) so tabs share the "Orca" title row.
   const titlebarTabsTarget = document.getElementById('titlebar-tabs')
 
   useEffect(() => {
     if (!activeWorktreeId) {
       return
     }
-    // Why: split-group ownership is now the real path. Ensure the active
-    // worktree always has a root group so terminal-first fallback can attach
-    // fresh tabs to a concrete owner even before any explicit split exists.
+    // Why: ensure a root group exists so terminal-first fallback can attach fresh tabs to a concrete owner before any explicit split.
     ensureWorktreeRootGroup(activeWorktreeId)
   }, [activeWorktreeId, ensureWorktreeRootGroup])
 
@@ -414,21 +401,10 @@ function Terminal(): React.JSX.Element | null {
   const saveDialogFile = saveDialogFileId ? openFiles.find((f) => f.id === saveDialogFileId) : null
   const pendingEditorCloseQueueRef = useRef<string[]>([])
 
-  // Why: while a save-and-close is awaiting the file to disappear from
-  // openFiles, concurrent queueEditorCloseRequests calls (e.g. user clicks X
-  // on another dirty tab, or a split-group dispatch fires
-  // ORCA_EDITOR_REQUEST_FILE_CLOSE_EVENT) must not re-open the dialog over
-  // the in-flight save. Track the in-flight file here so
-  // getNextQueuedEditorClose can skip it as an un-advanceable head.
+  // Why: track the file whose save-and-close is in flight so getNextQueuedEditorClose skips it and concurrent close requests can't re-open the dialog over it.
   const inFlightSaveFileIdRef = useRef<string | null>(null)
 
-  // Why: after a Save/Discard/Cancel handler dismisses its dialog and advances
-  // the queue, a rapid second physical click can land on the freshly-rendered
-  // next dialog's button before the user has read the filename — silently
-  // discarding or saving work they didn't consciously choose to act on. Gate
-  // the three handlers on this ref and release after CLOSE_DIALOG_DEBOUNCE_MS
-  // so the stray click from the previous dialog is absorbed while a genuine
-  // new click on the next dialog still works.
+  // Why: gate the Save/Discard/Cancel handlers so a stray carry-over click doesn't act on the next dialog before the user reads it; released after CLOSE_DIALOG_DEBOUNCE_MS.
   const isClosingRef = useRef(false)
   const closeDialogDebounceTimersRef = useRef<Set<number>>(new Set())
   const releaseCloseDialogGuardAfterDebounce = useCallback(() => {
@@ -439,14 +415,10 @@ function Terminal(): React.JSX.Element | null {
     closeDialogDebounceTimersRef.current.add(timer)
   }, [])
 
-  // Window close confirmation dialog — shown for local terminals with running
-  // child processes. SSH terminals detach/persist through the relay lifecycle.
+  // Window close confirmation, shown for local terminals with running children (SSH terminals detach/persist via the relay).
   const [windowCloseDialogOpen, setWindowCloseDialogOpen] = useState(false)
 
-  // Why: when the main process requests a close while editor tabs are dirty, we
-  // must not call confirmWindowClose() until the user saves or discards. The
-  // global beforeunload guard still calls preventDefault() while any file is
-  // dirty, so an immediate confirm would leave the window open with no UI.
+  // Why: defer confirmWindowClose() while tabs are dirty — the beforeunload guard preventDefault()s, so an immediate confirm leaves the window open with no UI.
   const windowCloseAfterDirtyRef = useRef<{ isQuitting: boolean } | null>(null)
 
   const confirmNativeWindowClose = useCallback(() => {
@@ -509,9 +481,7 @@ function Terminal(): React.JSX.Element | null {
           resolve(true)
         }
       })
-      // Why: zustand only fires subscribers on subsequent state changes. If
-      // the file closed between the initial guard and subscribe, the
-      // transition was missed — re-check synchronously after subscribe.
+      // Why: zustand only fires subscribers on later changes, so re-check in case the file closed between the guard and subscribe.
       if (!useAppStore.getState().openFiles.some((f) => f.id === fileId)) {
         window.clearTimeout(timeoutId)
         unsub?.()
@@ -521,14 +491,10 @@ function Terminal(): React.JSX.Element | null {
   }, [])
 
   const getNextQueuedEditorClose = useCallback((): string | null => {
-    // Why: bulk close actions can enqueue files that become clean or disappear
-    // before they reach the front. Drain those entries eagerly so the dialog
-    // only blocks on tabs that still require an explicit close decision.
+    // Why: bulk closes enqueue files that may go clean or vanish before reaching the front; drain them so the dialog only blocks on tabs still needing a decision.
     while (pendingEditorCloseQueueRef.current.length > 0) {
       const fileId = pendingEditorCloseQueueRef.current[0]
-      // Why: if a save is still in-flight for this fileId, do not re-open the
-      // dialog on top of it. waitForFileClosed will re-advance the queue once
-      // the file finishes closing (or the save times out).
+      // Why: skip a fileId with an in-flight save; waitForFileClosed re-advances the queue once it closes or times out.
       if (inFlightSaveFileIdRef.current === fileId) {
         return null
       }
@@ -550,9 +516,7 @@ function Terminal(): React.JSX.Element | null {
   const advanceEditorCloseQueue = useCallback(() => {
     const nextFileId = getNextQueuedEditorClose()
     if (nextFileId) {
-      // Why: the queue can cross worktree boundaries during window-close
-      // flows. Switch to the target file's worktree before opening the
-      // dialog so the UI behind the dialog matches the filename in it.
+      // Why: the queue can cross worktrees during window-close; switch to the file's worktree so the UI behind the dialog matches its filename.
       const state = useAppStore.getState()
       const file = state.openFiles.find((f) => f.id === nextFileId)
       if (file && file.worktreeId !== state.activeWorktreeId) {
@@ -627,10 +591,7 @@ function Terminal(): React.JSX.Element | null {
       return
     }
 
-    // Why: save-and-close must flush the latest draft even when the visible
-    // editor panel has already unmounted. The headless autosave controller
-    // owns that write path now, so the dialog signals it through a custom
-    // event instead of poking at editor component refs.
+    // Why: signal the headless autosave controller via event (not editor refs) so save-and-close flushes even when the editor panel has unmounted.
     setSaveDialogFileId(null)
     window.dispatchEvent(new CustomEvent(ORCA_EDITOR_SAVE_AND_CLOSE_EVENT, { detail: { fileId } }))
     inFlightSaveFileIdRef.current = fileId
@@ -638,18 +599,13 @@ function Terminal(): React.JSX.Element | null {
     try {
       closed = await waitForFileClosed(fileId, 10_000)
     } finally {
-      // Why: clear the in-flight ref regardless of success/timeout so the
-      // queue head is no longer treated as un-advanceable by
-      // getNextQueuedEditorClose before we re-advance the queue below.
+      // Why: clear the in-flight ref on success or timeout so getNextQueuedEditorClose no longer treats the queue head as un-advanceable.
       if (inFlightSaveFileIdRef.current === fileId) {
         inFlightSaveFileIdRef.current = null
       }
     }
     if (!closed) {
-      // Why: the save may have resolved in the tiny gap after the timeout
-      // fired. Re-check synchronously so we don't re-open a stale dialog
-      // for a file that is already gone — drain the queue entry and
-      // advance instead. Toast only for the genuine timeout case.
+      // Why: the save may have resolved just after the timeout fired; re-check so we drain/advance instead of re-opening a stale dialog, toasting only real timeouts.
       if (!useAppStore.getState().openFiles.some((f) => f.id === fileId)) {
         pendingEditorCloseQueueRef.current = pendingEditorCloseQueueRef.current.filter(
           (id) => id !== fileId
@@ -665,9 +621,7 @@ function Terminal(): React.JSX.Element | null {
         )
       )
       setSaveDialogFileId(fileId)
-      // Why: a genuine timeout leaves the user back on the same dialog, so
-      // release the guard immediately — a new click here is a deliberate
-      // retry, not a stray carry-over from a prior dialog.
+      // Why: on a genuine timeout the user stays on the same dialog, so release the guard now — a new click is a deliberate retry.
       isClosingRef.current = false
       return
     }
@@ -693,21 +647,14 @@ function Terminal(): React.JSX.Element | null {
     isClosingRef.current = true
     const fileId = saveDialogFileId
 
-    // Why: dismiss the dialog synchronously before awaiting quiesce. A rapid
-    // double-click on "Don't Save" would otherwise fire the handler twice
-    // with the same captured fileId, causing two concurrent queue advances
-    // after the quiesce settles. Mirrors handleSaveDialogSave's early clear.
+    // Why: dismiss synchronously before awaiting quiesce so a double-click can't fire twice with the same fileId and double-advance the queue.
     setSaveDialogFileId(null)
 
-    // Why: autosave runs on a background timer. Wait for any pending/in-flight
-    // write to settle before honoring "Don't Save", otherwise the file can be
-    // written after the user explicitly chose to discard their edits.
+    // Why: wait for background autosave to settle before "Don't Save", else a write can land after the user chose to discard.
     try {
       await requestEditorSaveQuiesce({ fileId })
     } catch (error) {
-      // Why: quiesce failure must not trap the user in a close dialog loop, but
-      // silently swallowing it also hides broken autosave state. Warn so a
-      // stuck controller is visible in devtools instead of disappearing.
+      // Why: don't trap the user in the close-dialog loop on quiesce failure, but still warn so a stuck controller stays visible.
       console.warn('Autosave quiesce failed before discard', error)
     }
     markFileDirty(fileId, false)
@@ -760,9 +707,7 @@ function Terminal(): React.JSX.Element | null {
     const rememberedTabId = renderedActiveWorktreeId
       ? (activeTabIdByWorktree[renderedActiveWorktreeId] ?? null)
       : null
-    // Why: prefer the worktree's remembered active tab over the first tab so a
-    // repair firing on a transient worktree-switch render restores the tab the
-    // user left on instead of permanently resetting the selection to Terminal 1.
+    // Why: prefer the remembered active tab so a repair on a transient switch render doesn't reset selection to Terminal 1.
     const repairedTabId = resolveRepairedActiveTerminalTabId({
       activeTabType,
       activeTabId,
@@ -772,14 +717,9 @@ function Terminal(): React.JSX.Element | null {
     if (!repairedTabId) {
       return
     }
-    // Why: mutating Zustand during render trips React's "Cannot update a
-    // component while rendering a different component" warning. Keep the repair
-    // terminal-only so inactive CLI-created tabs cannot steal editor/browser focus.
+    // Why: run in an effect (Zustand mutation during render trips React's cross-component update warning); keep terminal-only so inactive CLI-created tabs can't steal editor/browser focus.
     setActiveTab(repairedTabId)
-    // Why: `tabs` is intentionally the dependency here because the repair must
-    // react to tab-order/content changes, not just scalar IDs. The list comes
-    // from Zustand selectors and is small in practice, so this explicit repair
-    // effect is preferred over duplicating reconciliation state.
+    // Why: `tabs` is the dependency so the repair reacts to tab-order/content changes, not just scalar IDs.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     activeTabId,
@@ -790,25 +730,18 @@ function Terminal(): React.JSX.Element | null {
     renderedActiveWorktreeId
   ])
 
-  // Track which worktrees have been activated during this app session.
-  // Only mount TerminalPanes for visited worktrees to prevent mass PTY
-  // spawning when restoring a session with many saved worktree tabs.
+  // Why: only mount TerminalPanes for visited worktrees, else restoring many saved tabs mass-spawns PTYs.
   const measurableBackgroundWorktreeTimersRef = useRef(new Map<string, number>())
   const [backgroundMountRevision, setBackgroundMountRevision] = useState(0)
   const [terminalParkingRevision, setTerminalParkingRevision] = useState(0)
   const [parkedTerminalWorktreeIds, setParkedTerminalWorktreeIds] = useState<ReadonlySet<string>>(
     () => new Set()
   )
-  // Why: background-mounted worktrees restricted to specific tabs (targeted
-  // wake/resume) must not instantiate a TerminalPane per saved tab. A worktree
-  // absent from this map mounts all of its tabs.
+  // Tab restriction for targeted background mounts (wake/resume); a worktree absent from this map mounts all its tabs.
   const backgroundMountTabIdsByWorktreeRef = useRef(new Map<string, ReadonlySet<string>>())
-  // Why: targeted background mounts share the allowed-tab map above, but only
-  // cold activation deferral should immediately create watcher coverage for
-  // every unmounted tab.
+  // Why: only cold-activation deferral (not targeted mounts, which share the map above) creates watcher coverage for every unmounted tab.
   const activationDeferredMountTabIdsByWorktreeRef = useRef(new Map<string, ReadonlySet<string>>())
-  // Why: the cold-activation deferral decision must run once per activation
-  // transition, not on every re-render of an already-active worktree.
+  // Why: run the cold-activation deferral decision once per activation transition, not on every re-render.
   const lastActivationWorktreeIdRef = useRef<string | null>(null)
   useEffect(() => {
     const timers = measurableBackgroundWorktreeTimersRef.current
@@ -821,8 +754,7 @@ function Terminal(): React.JSX.Element | null {
         worktreeId,
         detail.tabIds
       )
-      // Why: a targeted wake can reveal a tab that was deferred by an earlier
-      // user activation. Remove it from watcher ownership before its pane mounts.
+      // Why: a targeted wake can reveal an earlier activation-deferred tab; drop it from watcher ownership before its pane mounts.
       const worktreeTabIds = (useAppStore.getState().tabsByWorktree[worktreeId] ?? []).map(
         (tab) => tab.id
       )
@@ -856,8 +788,7 @@ function Terminal(): React.JSX.Element | null {
       BACKGROUND_MOUNT_TERMINAL_WORKTREE_EVENT,
       onBackgroundMountTerminalWorktree as EventListener
     )
-    // Requests made while the lazy Terminal bundle/effect was absent stay in
-    // the registry and are replayed only after the listener owns the surface.
+    // Replay mounts requested while the lazy Terminal bundle/effect was absent, now that the listener owns the surface.
     for (const pending of takeAllPendingBackgroundTerminalWorktreeMounts()) {
       applyBackgroundMount(pending)
     }
@@ -870,8 +801,7 @@ function Terminal(): React.JSX.Element | null {
         window.clearTimeout(timer)
       }
       timers.clear()
-      // Why: close-dialog debounce timers are Terminal-owned and only need
-      // unmount cleanup; keep them with the existing Terminal lifetime cleanup.
+      // Close-dialog debounce timers are Terminal-owned, so clear them with the Terminal lifetime cleanup.
       for (const timer of closeDialogDebounceTimers) {
         window.clearTimeout(timer)
       }
@@ -889,9 +819,7 @@ function Terminal(): React.JSX.Element | null {
     }
   }, [])
 
-  // Why: worktree-level cold-park policy — hiddenSince bookkeeping, parked-set
-  // selection, and one recheck timer per still-pending deadline so React
-  // re-renders exactly when the hysteresis elapses instead of polling.
+  // Worktree cold-park policy: hiddenSince bookkeeping, parked-set selection, and one recheck timer per deadline so React re-renders when hysteresis elapses instead of polling.
   useEffect(() => {
     const parkingTimers = terminalWorktreeParkingTimersRef.current
     for (const timer of parkingTimers.values()) {
@@ -943,10 +871,7 @@ function Terminal(): React.JSX.Element | null {
       nowMs,
       ...overrides
     })
-    // Why: a worktree with any tab the byte watchers cannot cover (no
-    // capture, no layout snapshot, legacy leaf ids) must never park — it
-    // would go silent for bells/titles/completions, the failure that sank
-    // the first parking attempt.
+    // Why: a worktree with any watcher-uncoverable tab must never park, or it goes silent for bells/titles/completions (sank the first parking attempt).
     for (const worktreeId of Array.from(nextParkedTerminalWorktreeIds)) {
       const tabs = tabsByWorktree[worktreeId] ?? []
       if (!tabs.every((tab) => canWatcherCoverParkedTerminalTab(worktreeId, tab))) {
@@ -994,18 +919,9 @@ function Terminal(): React.JSX.Element | null {
     terminalParkingRevision,
     workspaceSurfaces
   ])
-  // Why: gated on workspaceSessionReady to prevent TerminalPane from mounting
-  // before reconnectPersistedTerminals() has finished eagerly spawning PTYs.
-  // Without this gate, Phase 1 (hydrateWorkspaceSession) sets activeWorktreeId
-  // with ptyId: null, and TerminalPane would call connectPanePty → pty:spawn,
-  // creating a duplicate PTY for the same tab.
+  // Why: gate on workspaceSessionReady so TerminalPane doesn't mount and spawn a duplicate PTY before reconnectPersistedTerminals() finishes.
   if (renderedActiveWorktreeId && workspaceSessionReady) {
-    // A real activation supersedes any targeted background mount, but a cold
-    // activation must not mount every saved tab in one pass: each TerminalPane
-    // mount replays scrollback through xterm, attaches a WebGL renderer, and
-    // issues a sync-IPC snapshot read, so a whole-worktree stampede freezes
-    // the renderer for the entire activation. Hidden tabs defer like
-    // cold-parked tabs from birth and mount on first reveal.
+    // Why: mounting every saved tab at once (scrollback replay + WebGL + sync-IPC snapshot per pane) freezes the renderer, so hidden tabs defer and mount on first reveal.
     const worktreeTabs = tabsByWorktree[renderedActiveWorktreeId] ?? []
     const coldActivationDeferralEnabled =
       terminalParkingEnabled && terminalTitleSnapshotAuthorityEnabled
@@ -1013,17 +929,12 @@ function Terminal(): React.JSX.Element | null {
     if (activeTabId) {
       immediateTabIds.add(activeTabId)
     }
-    // Why: on a fresh switch the global activeTabId can still point at the
-    // previous worktree for one pass; the remembered per-worktree tab is the
-    // one about to become visible.
+    // Why: on a fresh switch the global activeTabId lags to the previous worktree for one pass; the remembered per-worktree tab is the one about to show.
     const rememberedActiveTabId = activeTabIdByWorktree[renderedActiveWorktreeId]
     if (rememberedActiveTabId) {
       immediateTabIds.add(rememberedActiveTabId)
     }
-    // Why groups: split mode shows one tab per group at once, so every
-    // group's active tab is user-visible and must not defer. group.activeTabId
-    // is a unified-tab id — map it to the terminal tab's entity id, keeping
-    // the raw id too in case older persisted groups stored entity ids.
+    // Why groups: split mode shows each group's active tab at once, so none may defer; map the unified-tab id to its entity id (keep the raw id for legacy groups that stored entity ids).
     const unifiedTabById = new Map(
       (useAppStore.getState().unifiedTabsByWorktree[renderedActiveWorktreeId] ?? []).map(
         (unifiedTab) => [unifiedTab.id, unifiedTab]
@@ -1044,10 +955,7 @@ function Terminal(): React.JSX.Element | null {
         immediateTabIds.add(portal.tabId)
       }
     }
-    // Why: a queued startup needs a mounted pane to run its command.
-    // pendingActivationSpawn is deliberately NOT immediate: session hydration
-    // blanket-marks every persisted tab with it, and a deferred tab's reveal
-    // consumes it exactly like an activation mount would — just later.
+    // Why: a queued startup needs a mounted pane to run; pendingActivationSpawn is excluded because hydration marks every persisted tab and a deferred reveal consumes it later.
     for (const tab of worktreeTabs) {
       if (pendingStartupByTabId[tab.id] !== undefined) {
         immediateTabIds.add(tab.id)
@@ -1065,15 +973,11 @@ function Terminal(): React.JSX.Element | null {
         worktreeId: renderedActiveWorktreeId,
         allTabIds: worktreeTabs.map((tab) => tab.id),
         isTabLive: hasRegisteredRuntimeTerminalTab,
-        // Why the coverage gate: an unmounted tab's bells/titles/completions
-        // are owned by parked byte watchers; a tab they cannot cover must
-        // mount immediately, mirroring the cold-park eligibility rule.
+        // Why the coverage gate: parked byte watchers own an unmounted tab's bells/titles/completions, so a tab they can't cover must mount immediately.
         isTabDeferrable: (tabId) => {
           const tab = tabById.get(tabId)
           return (
-            // Why: byte-mode watchers cannot reconstruct output emitted before
-            // registration. Remote or unresolved ownership also mounts eagerly
-            // because only a confirmed local daemon can provide snapshots.
+            // Why: byte-mode watchers can't reconstruct pre-registration output; remote/unresolved ownership mounts eagerly since only a local daemon has snapshots.
             coldActivationDeferralEnabled &&
             activationHostSupportsDeferral &&
             tab !== undefined &&
@@ -1087,14 +991,11 @@ function Terminal(): React.JSX.Element | null {
         immediateTabIds
       })
     } else if (!coldActivationDeferralEnabled || !activationHostSupportsDeferral) {
-      // Why: kill-switch or host-ownership changes while active must restore
-      // eager mounting immediately, not strand an old local-only restriction.
+      // Why: kill-switch or host-ownership change while active must restore eager mounting, not strand an old restriction.
       backgroundMountTabIdsByWorktreeRef.current.delete(renderedActiveWorktreeId)
       activationDeferredMountTabIdsByWorktreeRef.current.delete(renderedActiveWorktreeId)
     } else {
-      // Why: tabs added after activation never passed the original coverage
-      // gate. Uncoverable/no-PTY tabs must mount now so they can spawn or keep
-      // their non-snapshot-backed live transport.
+      // Why: tabs added after activation never passed the coverage gate — uncoverable/no-PTY ones must mount now to spawn or keep their live transport.
       for (const tab of worktreeTabs) {
         if (
           !canWatcherCoverParkedTerminalTab(
@@ -1116,8 +1017,7 @@ function Terminal(): React.JSX.Element | null {
     }
     mountedWorktreeIdsRef.current.add(renderedActiveWorktreeId)
   } else {
-    // Why: the next ready activation must re-run the deferral decision even
-    // if it re-activates the same worktree the session started on.
+    // Why: reset so the next ready activation re-runs the deferral decision even for the same worktree.
     lastActivationWorktreeIdRef.current = null
   }
   pruneClosedBackgroundMountTabs(
@@ -1142,11 +1042,7 @@ function Terminal(): React.JSX.Element | null {
     groupsByWorktree,
     activeGroupIdByWorktree
   )
-  // Why: parked byte-watcher reconciliation for the legacy (non-split)
-  // terminal host, which renders TerminalPanes directly. In split mode each
-  // TerminalPaneOverlayLayer owns its worktree's watchers, so here we only
-  // dispose worktrees that render no overlay layer (no layout / unmounted)
-  // and prune watchers for deleted worktrees.
+  // Why: legacy (non-split) host owns watcher reconciliation; split mode's overlay layers own theirs, so only dispose worktrees with no overlay layer.
   useEffect(() => {
     pruneParkedTerminalWatchers(new Set(workspaceSurfaces.map((workspace) => workspace.id)))
     for (const workspace of workspaceSurfaces) {
@@ -1177,9 +1073,7 @@ function Terminal(): React.JSX.Element | null {
             }
           }
         }
-        // Why: activation-deferred tabs are unmounted like parked ones; the
-        // same byte watchers own their side effects until first reveal.
-        // Targeted restrictions keep their existing delayed parking policy.
+        // Why: activation-deferred tabs are unmounted like parked ones — the same byte watchers own their side effects until first reveal.
         deferredTabIds =
           activationDeferredMountTabIdsByWorktreeRef.current.get(workspace.id) ?? null
         for (const tab of tabs) {
@@ -1200,15 +1094,12 @@ function Terminal(): React.JSX.Element | null {
         worktreeId: workspace.id,
         tabs,
         parkedTabIds,
-        // Why: activation-deferred tabs never mounted a pane to restore their
-        // title, unlike ordinary parked tabs whose live pane populated it.
+        // Why: activation-deferred tabs never mounted a pane to restore their title, unlike ordinary parked tabs.
         ...(deferredTabIds ? { restoreTitleOnStartTabIds: deferredTabIds } : {})
       })
     }
   }, [
-    // Why activeTabId: revealing a deferred tab mutates the mount restriction
-    // during the same render; the watcher sync must re-run in that flush so
-    // the revealed tab's watcher disposes before its pane attaches.
+    // Why activeTabId: revealing a deferred tab mutates the mount restriction in the same render; sync must re-run so its watcher disposes before the pane attaches.
     activeTabId,
     activeView,
     activityTerminalPortals,
@@ -1226,10 +1117,7 @@ function Terminal(): React.JSX.Element | null {
     workspaceSessionReady,
     workspaceSurfaces
   ])
-  // Why: symmetric with useTerminalTabColdParking's unmount cleanup — when
-  // the terminal host unmounts, no reconciliation effect will run again, so
-  // dispose every remaining parked watcher here (overlay-layer children have
-  // already disposed theirs by the time this parent cleanup runs).
+  // Why: on host unmount no reconciliation effect runs again, so dispose every remaining parked watcher here.
   useEffect(() => () => disposeAllParkedTerminalWatchers(), [])
   // Auto-create first tab when worktree activates
   useEffect(() => {
@@ -1239,24 +1127,17 @@ function Terminal(): React.JSX.Element | null {
     if (!activeWorktreeId) {
       return
     }
-    // Why: in the paired web client, host session-tabs are authoritative.
-    // Creating a local fallback races the host's initial terminal and duplicates tabs.
+    // Why: host session-tabs are authoritative in the paired web client; a local fallback races the host's initial terminal and duplicates tabs.
     if (isWebRuntimeSessionActive(getActiveWorktreeRuntimeEnvironmentId(activeWorktreeId))) {
       return
     }
 
-    // Why: this fallback exists to give a newly activated/restored worktree a
-    // focusable surface when the reconciled tab model has nothing renderable.
-    // Re-running it on ordinary tab-count changes would recreate a terminal
-    // immediately after the user intentionally closed the last visible one.
+    // Why: give a newly activated worktree a focusable surface when nothing renders, without recreating one after the user closes the last visible tab.
     const { renderableTabCount } = reconcileWorktreeTabModel(activeWorktreeId)
     if (!shouldAutoCreateInitialTerminal(renderableTabCount)) {
       return
     }
-    // Why: this tab only exists because the user clicked a never-visited
-    // worktree. Tag it so the PTY spawn it triggers does not count as
-    // activity and reshuffle the sidebar. Explicit "New Tab" actions
-    // (handleNewTab below) still bump normally.
+    // Why: tag this never-visited-worktree tab so its PTY spawn doesn't count as activity and reshuffle the sidebar (explicit New Tab still bumps).
     createTab(activeWorktreeId, undefined, undefined, { pendingActivationSpawn: true })
   }, [workspaceSessionReady, activeWorktreeId, createTab, reconcileWorktreeTabModel])
 
@@ -1269,9 +1150,7 @@ function Terminal(): React.JSX.Element | null {
       return
     }
     startupResumeWorktreeIdsRef.current.add(activeWorktreeId)
-    // Why: startup hydration restores the active worktree without calling
-    // activateAndRevealWorktree, so orphaned live/quit records need a terminal
-    // surface pass after pane-level cold restore had first chance.
+    // Why: startup hydration restores the worktree without activateAndRevealWorktree, so orphaned live/quit records need a terminal-surface pass after cold restore.
     resumeSleepingAgentSessionsForWorktree(activeWorktreeId)
   }, [activeWorktreeId, hydrationSucceeded, workspaceSessionReady])
 
@@ -1300,10 +1179,7 @@ function Terminal(): React.JSX.Element | null {
       }
       const newTab = createTab(activeWorktreeId, undefined, shellOverride)
       setActiveTabType('terminal')
-      // Why: persist the tab bar order with the new terminal at the end of the
-      // current visual order. Without this, reconcileOrder falls back to
-      // terminals-first when tabBarOrderByWorktree is unset, causing a new
-      // terminal to jump to index 0 instead of appending after editor tabs.
+      // Why: persist tab-bar order with the new terminal appended; else reconcileOrder falls back to terminals-first and jumps it to index 0 before editor tabs.
       const state = useAppStore.getState()
       const currentTerminals = state.tabsByWorktree[activeWorktreeId] ?? []
       const currentEditors = state.openFiles.filter((f) => f.worktreeId === activeWorktreeId)
@@ -1325,8 +1201,7 @@ function Terminal(): React.JSX.Element | null {
       const order = base.filter((id) => id !== newTab.id)
       order.push(newTab.id)
       setTabBarOrder(activeWorktreeId, order)
-      // Why: shell-specific creation still uses the legacy path; keep the
-      // keyboard shortcut focused until the lifted action accepts shell overrides.
+      // Why: shell-specific creation still uses the legacy path; keep focus here until the lifted action accepts shell overrides.
       focusTerminalTabSurface(newTab.id)
     },
     [
@@ -1529,9 +1404,7 @@ function Terminal(): React.JSX.Element | null {
       if (consumeSuppressedPtyExit(ptyId)) {
         return
       }
-      // Why: a parked multi-leaf tab has no PaneManager to promote split
-      // siblings, so closing the tab here would kill them; the reveal
-      // remount handles dead PTYs per leaf instead.
+      // Why: a parked multi-leaf tab has no PaneManager to promote split siblings, so closing here would kill them; reveal-remount handles dead PTYs per leaf.
       if (shouldDeferParkedPtyExitTabClose(tabId, ptyId)) {
         return
       }
@@ -1566,8 +1439,7 @@ function Terminal(): React.JSX.Element | null {
               browserWorkspaceHasRemoteOwner(state, unifiedTab.entityId, runtimeEnvironmentId)))
         ) {
           if (unifiedTab.contentType === 'terminal') {
-            // Why: paired-host bulk close must revoke renderer resume and hook
-            // authority as well as removing the host-owned session tab.
+            // Why: paired-host bulk close must revoke renderer resume and hook authority, not just remove the host session tab.
             closeTerminalTab(unifiedTab.entityId)
           } else {
             void closeWebRuntimeSessionTab({
@@ -1631,8 +1503,7 @@ function Terminal(): React.JSX.Element | null {
               browserWorkspaceHasRemoteOwner(state, unifiedTab.entityId, runtimeEnvironmentId)))
         ) {
           if (unifiedTab.contentType === 'terminal') {
-            // Why: route every terminal close through the destructive local
-            // lifecycle boundary before the paired host RPC.
+            // Why: route terminal close through the destructive local lifecycle boundary before the paired-host RPC.
             closeTerminalTab(unifiedTab.entityId)
           } else {
             void closeWebRuntimeSessionTab({
@@ -1769,10 +1640,7 @@ function Terminal(): React.JSX.Element | null {
           keybindings
         })
       }
-      // Why: Cmd/Ctrl+T always opens a new terminal, regardless of which
-      // surface is active. Browser-tab creation has its own shortcut
-      // (Cmd/Ctrl+Shift+B) so users have a predictable way to spawn a
-      // terminal from anywhere in the central pane.
+      // Why: Cmd/Ctrl+T always opens a terminal regardless of active surface; browser tabs have their own chord (Cmd/Ctrl+Shift+B).
       if (!e.repeat && matchShortcut('tab.newTerminal')) {
         e.preventDefault()
         notifyTerminalCapture('tab.newTerminal')
@@ -1784,11 +1652,8 @@ function Terminal(): React.JSX.Element | null {
         return
       }
 
-      // Cmd/Ctrl+Alt+T (macOS default) — launch the default agent in a new
-      // tab; per-agent chords (Settings → Shortcuts → Agents) launch their
-      // specific agent. Unlike Cmd+T this never targets the floating panel:
-      // agent sessions belong to a worktree, so the launch always lands in
-      // the active workspace's tab bar.
+      // Cmd/Ctrl+Alt+T — launch the default agent in a new tab (per-agent chords launch specific agents).
+      // Why: unlike Cmd+T this never targets the floating panel — agent sessions belong to a worktree.
       if (!e.repeat) {
         const state = useAppStore.getState()
         let agentActionId: KeybindingActionId | null = null
@@ -1811,9 +1676,7 @@ function Terminal(): React.JSX.Element | null {
           )) {
             if (matchShortcut(bound.actionId)) {
               agentActionId = bound.actionId
-              // Why: a per-agent chord is an explicit request for that agent,
-              // so launch it even when detection hasn't (or can't have)
-              // confirmed the binary; a missing CLI fails visibly in the tab.
+              // Why: a per-agent chord is explicit, so launch even if detection didn't confirm the binary — a missing CLI fails visibly in the tab.
               agentToLaunch = bound.agent
               break
             }
@@ -1836,9 +1699,7 @@ function Terminal(): React.JSX.Element | null {
         }
       }
 
-      // Cmd/Ctrl+Shift+T — reopen the most recently closed tab of any kind
-      // (terminal, browser, or editor), Chrome/Ghostty-style. Repeated presses
-      // walk back through the close history.
+      // Cmd/Ctrl+Shift+T — reopen the most recently closed tab (terminal/browser/editor), Chrome-style; repeats walk back through history.
       if (!e.repeat && matchShortcut('tab.reopenClosed')) {
         e.preventDefault()
         notifyTerminalCapture('tab.reopenClosed')
@@ -1868,10 +1729,7 @@ function Terminal(): React.JSX.Element | null {
         return
       }
 
-      // Save active editor file (fallback for when focus is
-      // outside the editor content area, e.g. on the tab bar or sidebar).
-      // When the editor itself has focus, editor-local handlers own the save
-      // shortcut, so we skip this when the target is editable.
+      // Save active editor file — fallback for when focus is outside the editor (tab bar/sidebar); editor-local handlers own save when the editor is focused.
       if (!e.repeat && matchShortcut('editor.save')) {
         const target = e.target as HTMLElement | null
         const inEditor =
@@ -1913,11 +1771,8 @@ function Terminal(): React.JSX.Element | null {
         return
       }
 
-      // Cmd/Ctrl+W - close active editor tab, browser tab, or terminal pane.
-      // Terminal pane/tab close is handled by the pane-level keyboard handler
-      // in keyboard-handlers.ts so it can close individual split panes and
-      // show a confirmation dialog. We still preventDefault here so Electron
-      // doesn't close the window as its default Cmd+W action.
+      // Cmd/Ctrl+W — close active editor/browser tab or terminal pane. Terminal close lives in keyboard-handlers.ts (split panes + confirm dialog).
+      // Why: still preventDefault here so Electron doesn't run its default Cmd+W window-close.
       if (!e.repeat && matchShortcut('tab.close')) {
         const state = useAppStore.getState()
         if (state.activeTabType === 'terminal' && context === 'terminal') {
@@ -1933,9 +1788,8 @@ function Terminal(): React.JSX.Element | null {
         return
       }
 
-      // Cmd/Ctrl+Alt+W - close every editor file tab in the active worktree.
-      // Why: reuse the context-menu close-all path so pinned and dirty-file
-      // rules stay identical; terminal focus still honors shortcut policy.
+      // Cmd/Ctrl+Alt+W — close every editor file tab in the active worktree.
+      // Why: reuse the context-menu close-all path so pinned/dirty-file rules stay identical.
       if (!e.repeat && matchShortcut('tab.closeAll')) {
         e.preventDefault()
         notifyTerminalCapture('tab.closeAll')
@@ -1960,13 +1814,7 @@ function Terminal(): React.JSX.Element | null {
         return
       }
 
-      // Fresh installs use Cmd/Ctrl+Shift+[ / ] across all tab types and
-      // Cmd/Ctrl+Alt+[ / ] within the active type; upgrading users keep the
-      // inverse mapping, and both actions remain rebindable.
-      // Why: use e.code instead of e.key because on macOS, Shift+[ reports '{'
-      // as the key value (the shifted character), not '['. Option+[ also
-      // composes to dead-key / punctuation on many layouts, so matching on
-      // event.key would miss the chord entirely on non-US layouts.
+      // Why: match on e.code, not e.key — macOS Shift+[ reports '{' and Option+[ composes dead-keys, so e.key misses the chord on many layouts.
       const switchSameTypeDirection = matchShortcut('tab.nextSameType')
         ? 1
         : matchShortcut('tab.previousSameType')
@@ -1978,11 +1826,7 @@ function Terminal(): React.JSX.Element | null {
           ? -1
           : null
       if (!e.repeat && (switchSameTypeDirection !== null || switchAllTypesDirection !== null)) {
-        // Why: delegate to the shared handler used by the IPC shortcut path
-        // so both code paths share one implementation. Always consume the
-        // chord — even when the switch is a no-op (e.g. single tab), we own
-        // this key combo and shouldn't let it reach xterm or the browser
-        // guest's default handling.
+        // Why: share the IPC-path handler and always consume the chord (even single-tab no-op) so it never reaches xterm or the browser guest.
         e.preventDefault()
         e.stopPropagation()
         e.stopImmediatePropagation()
@@ -2008,30 +1852,15 @@ function Terminal(): React.JSX.Element | null {
         }
       }
 
-      // Ctrl+PageDown/PageUp - switch terminal tabs only
-      // Why: this chord intentionally uses Ctrl on every platform; on macOS,
-      // Cmd+PageUp/PageDown is an OS desktop-switch shortcut we should not steal.
-      // Why: also reject Shift so Ctrl+Shift+PageUp/PageDown stays available
-      // for focused terminal / editor consumers and matches the unshifted
-      // predicate in browser-guest-ui.ts and the chord advertised in
-      // ShortcutsPane.
+      // Ctrl+PageDown/PageUp — switch terminal tabs only. Ctrl on every platform since macOS Cmd+PageUp/Down is an OS desktop-switch shortcut.
+      // Why: reject Shift too so Ctrl+Shift+PageUp/Down stays free for focused terminal/editor consumers.
       const terminalTabDirection = matchShortcut('tab.nextTerminal')
         ? 1
         : matchShortcut('tab.previousTerminal')
           ? -1
           : null
       if (!e.repeat && terminalTabDirection !== null) {
-        // Why: always consume the chord before xterm's textarea listener
-        // sees it, regardless of whether we actually switched tabs. xterm
-        // translates plain Ctrl+PageUp/PageDown into \e[5~ / \e[6~ escape
-        // sequences and writes them to the shell; that stray output then
-        // also flips the tab's unread/bell indicator. In the single-terminal
-        // case handleSwitchTerminalTab is a no-op, but we still need to
-        // swallow the event — otherwise pressing the chord on the only
-        // terminal leaves "5~" in the shell and lights up a phantom
-        // notification on the tab that already has focus. preventDefault
-        // alone does not stop xterm's own keydown listener, so we also
-        // stop propagation.
+        // Why: fully consume the chord (preventDefault alone won't stop xterm's listener); else xterm writes \e[5~/\e[6~ escapes to the shell even in the single-terminal no-op case.
         e.preventDefault()
         e.stopPropagation()
         e.stopImmediatePropagation()
@@ -2064,8 +1893,7 @@ function Terminal(): React.JSX.Element | null {
   // Warn on window close if there are unsaved editor files
   useEffect(() => {
     const handler = (e: BeforeUnloadEvent): void => {
-      // Why: update/manual restarts pre-save dirty tabs and then intentionally
-      // close the app. Do not let stale dirty flags veto the relaunch path.
+      // Why: intentional restarts pre-save dirty tabs, so don't let stale dirty flags veto the relaunch.
       if (isIntentionalAppRestartInProgress()) {
         return
       }
@@ -2078,13 +1906,8 @@ function Terminal(): React.JSX.Element | null {
     return () => window.removeEventListener('beforeunload', handler)
   }, [])
 
-  // Handle main-process window close requests. Terminal sessions are detached
-  // by the daemon/SSH lifecycle; only dirty editor files should block close
-  // here. Explicit destructive terminal actions keep their own confirms.
-  // Why: register into the coordinator rather than subscribing to IPC directly.
-  // The single IPC subscription lives at the always-mounted App root, so quits
-  // on the no-workspace landing page (where Terminal is not mounted) are still
-  // handled instead of deadlocking the window (#5144).
+  // Handle main-process window close requests: only dirty editor files block close (terminal sessions detach via daemon/SSH).
+  // Why: register into the coordinator, not IPC directly, so quits on the Terminal-less landing page are still handled (#5144).
   useEffect(() => {
     setWindowCloseRequestHandler(({ isQuitting }) => {
       if (isIntentionalAppRestartInProgress()) {
@@ -2092,9 +1915,7 @@ function Terminal(): React.JSX.Element | null {
         return
       }
 
-      // Why: if a previous close request is already being handled (user is
-      // working through dirty-file dialogs), ignore duplicate quit signals
-      // to avoid overwriting the in-flight ref and losing the close sequence.
+      // Why: ignore duplicate quit signals while a close is in flight, else the in-flight ref is overwritten and the close sequence is lost.
       if (windowCloseAfterDirtyRef.current) {
         return
       }
@@ -2113,10 +1934,7 @@ function Terminal(): React.JSX.Element | null {
     return () => setWindowCloseRequestHandler(null)
   }, [proceedToNativeWindowClose, queueEditorCloseRequests])
 
-  // Why: browser page state can disappear through store-only paths (CLI tab
-  // close, worktree deletion). The store cannot call destroyPersistentWebview
-  // because that function owns renderer DOM nodes, so this subscriber tears down
-  // webviews whose backing page records were removed.
+  // Why: browser pages can vanish via store-only paths; the store can't destroy webviews (owns DOM nodes), so this subscriber tears down orphaned ones.
   const prevBrowserWebviewIdsRef = useRef<Set<string>>(
     collectBrowserWebviewIds(
       useAppStore.getState().browserTabsByWorktree,
@@ -2148,12 +1966,7 @@ function Terminal(): React.JSX.Element | null {
     })
   }, [])
 
-  // Why: defensive guard against state inconsistency. If activeTabType is
-  // 'browser' but no browser tab can be rendered (e.g. activeBrowserTabId is
-  // null or doesn't match any tab), fall back to terminal view instead of
-  // rendering a blank screen. This runs as an effect (not during render)
-  // because calling Zustand mutations during render interferes with React's
-  // render cycle and causes blank screens when creating new tabs.
+  // Why: fall back to terminal when activeTabType 'browser' has no renderable tab; run as effect, not render (Zustand mutations mid-render blank the screen).
   useEffect(() => {
     const activeWorktreeBrowserTabs = renderedActiveWorktreeId
       ? (useAppStore.getState().browserTabsByWorktree[renderedActiveWorktreeId] ?? [])
@@ -2187,9 +2000,7 @@ function Terminal(): React.JSX.Element | null {
     >
       <EditorAutosaveController />
 
-      {/* Why: once split groups are enabled, each group owns its own tab strip
-          inline. The old titlebar portal stays only as a fallback
-          before the root-group layout has been established. */}
+      {/* Why: with split groups each group owns its inline tab strip; this titlebar portal is only a fallback before the root-group layout exists. */}
       {renderedActiveWorktreeId &&
         !effectiveActiveLayout &&
         titlebarTabsTarget &&
@@ -2246,18 +2057,13 @@ function Terminal(): React.JSX.Element | null {
           titlebarTabsTarget
         )}
 
-      {/* Why: the full-width titlebar is no longer rendered in workspace view
-          — tab groups + terminal extend to the top of the window instead.
-          The old summary label (workspace / active surface) is removed. */}
+      {/* Why: no full-width titlebar in workspace view — tab groups + terminal extend to the window top. */}
 
       {anyMountedWorktreeHasLayout ? (
         <div
           className={`relative flex flex-1 min-w-0 min-h-0 overflow-hidden${effectiveActiveLayout ? '' : ' hidden'}`}
         >
-          {/* Why: each mounted worktree surface is absolutely positioned so we
-              can preserve hidden trees without reflowing the active one. Keep
-              a relative anchor here so those panes size to the workspace body
-              rather than some outer ancestor when split groups are enabled. */}
+          {/* Why: absolutely position each mounted surface so hidden trees don't reflow the active one; the relative anchor sizes panes to the workspace body. */}
           {workspaceSurfaces
             .filter((workspace) => mountedWorktreeIdsRef.current.has(workspace.id))
             .map((workspace) => {
@@ -2265,8 +2071,7 @@ function Terminal(): React.JSX.Element | null {
               if (!layout) {
                 return null
               }
-              // Why: use strict equality with 'terminal' instead of !== 'settings'
-              // so the terminal/browser surface hides on the tasks page too.
+              // Why: strict '=== terminal' (not !== settings) so the terminal/browser surface hides on the tasks page too.
               const isVisible =
                 activeView === 'terminal' && workspace.id === renderedActiveWorktreeId
               const shouldMeasureHiddenWorktree =
@@ -2300,32 +2105,11 @@ function Terminal(): React.JSX.Element | null {
 
       {!effectiveActiveLayout && !anyMountedWorktreeHasLayout && (
         <>
-          {/* Why: split-group layouts render their own terminal/browser/editor
-              surfaces through TabGroupPanel plus stable overlay layers.
-              Keeping the legacy workspace-level panes mounted underneath
-              as hidden DOM creates duplicate
-              TerminalPane/BrowserPane instances for the same tab, which lets
-              two React trees race over one PTY or webview. Render only one
-              surface model at a time.
-
-              Also gate on !anyMountedWorktreeHasLayout: when the active
-              worktree goes null (e.g. during shutdown-from-focused, which
-              calls setActiveWorktree(null) before shutdownWorktreeTerminals)
-              effectiveActiveLayout becomes undefined but other mounted
-              worktrees still have layouts. Without this guard, the legacy
-              branch mounts fresh TerminalPanes for every worktree in
-              mountedWorktreeIdsRef, each running connectPanePty →
-              startFreshSpawn → new PTY. That respawn is exactly what flips
-              getWorktreeStatus back to 'active' and re-lights the sidebar
-              dot green moments after the user clicked Shutdown. */}
+          {/* Why: render only one surface model — legacy panes mounted alongside split-group panes race two React trees over one PTY/webview; gate on !anyMountedWorktreeHasLayout too so shutdown-from-focused doesn't respawn PTYs and re-light the sidebar dot. */}
           {/* Terminal panes container - hidden when editor tab active */}
           <div
             className={`relative flex-1 min-h-0 overflow-hidden ${
-              // Why: only hide the terminal container when another tab type has
-              // content to display. Hiding unconditionally for non-terminal types
-              // causes a blank screen when activeTabType is stale (e.g. 'editor'
-              // with no files after session restore). The terminal stays visible
-              // as a fallback until another surface is ready.
+              // Why: only hide the terminal when another tab type has content; else a stale activeTabType (e.g. 'editor' with no files after restore) blanks the screen.
               (activeTabType === 'editor' && worktreeFiles.length > 0) ||
               (activeTabType === 'browser' && worktreeBrowserTabs.length > 0) ||
               activeTabType === 'simulator'
@@ -2336,8 +2120,7 @@ function Terminal(): React.JSX.Element | null {
             {workspaceSurfaces
               .filter((workspace) => mountedWorktreeIdsRef.current.has(workspace.id))
               .map((workspace) => {
-                // Why: use strict equality with 'terminal' instead of !== 'settings'
-                // so the terminal/browser surface hides on the tasks page too.
+                // Why: strict '=== terminal' (not !== settings) so the terminal/browser surface hides on the tasks page too.
                 const isVisible =
                   activeView === 'terminal' && workspace.id === renderedActiveWorktreeId
                 const shouldMeasureHiddenWorktree =
@@ -2374,8 +2157,7 @@ function Terminal(): React.JSX.Element | null {
                         const isActivityPortalTab = activityTerminalPortal !== null
                         const isActiveTerminalTab =
                           isVisible && tab.id === activeTabId && activeTabType === 'terminal'
-                        // Why: parking unmounts the view while preserving the PTY;
-                        // an Activity portal remains mounted as a visible consumer.
+                        // Why: parking unmounts the view but keeps the PTY; an Activity portal stays mounted as a visible consumer.
                         if (shouldColdParkTerminalPanes && !isActivityPortalTab) {
                           return null
                         }
@@ -2388,18 +2170,11 @@ function Terminal(): React.JSX.Element | null {
                             isActive={
                               isActiveTerminalTab || activityTerminalPortal?.active === true
                             }
-                            // Why: the activity page hosts this existing pane via
-                            // portal while the workspace surface remains hidden.
-                            // Keeping `isVisible` true for the portaled tab lets
-                            // xterm fit and stream foreground output in-place.
+                            // Why: keep isVisible true for the portaled tab so xterm fits/streams while the workspace surface stays hidden.
                             isVisible={isActiveTerminalTab || isActivityPortalTab}
-                            // Why: inactive tabs in the visible legacy surface
-                            // are tab-hidden, not worktree-hidden, so they need
-                            // the same light resume path as split-group overlays.
+                            // Why: inactive tabs here are tab-hidden (not worktree-hidden), so they need the same light resume path as split-group overlays.
                             isWorktreeActive={isVisible || isActivityPortalTab}
-                            // Why: when portaled to Activity for a specific agent
-                            // pane, isolate that leaf so split siblings stay
-                            // hidden. Workspace renders pass null → no override.
+                            // Why: isolate the portaled Activity leaf so split siblings stay hidden; workspace renders pass null.
                             isolatedPaneKey={activityTerminalPortal?.paneKey ?? null}
                             onPtyExit={(ptyId) => handlePtyExit(tab.id, ptyId)}
                             onCloseTab={() => handleCloseTab(tab.id)}
@@ -2419,9 +2194,7 @@ function Terminal(): React.JSX.Element | null {
               })}
           </div>
 
-          {/* Browser panes container — only the active pane mounts so inactive
-              webviews park into the bounded registry instead of keeping hidden
-              Electron guest renderers alive indefinitely. */}
+          {/* Browser panes: only the active pane mounts so inactive webviews park rather than keep hidden guest renderers alive. */}
           <div
             className={`relative flex-1 min-h-0 overflow-hidden ${
               activeTabType !== 'browser' ? 'hidden' : ''
@@ -2429,8 +2202,7 @@ function Terminal(): React.JSX.Element | null {
           >
             {workspaceSurfaces.map((workspace) => {
               const browserTabs = browserTabsByWorktree[workspace.id] ?? []
-              // Why: use strict equality with 'terminal' instead of !== 'settings'
-              // so browser panes also hide on the tasks page.
+              // Why: strict '=== terminal' (not !== settings) so browser panes hide on the tasks page too.
               const isVisibleWorktree =
                 activeView === 'terminal' && workspace.id === renderedActiveWorktreeId
               if (browserTabs.length === 0) {
@@ -2567,19 +2339,8 @@ function Terminal(): React.JSX.Element | null {
   )
 }
 
-// Why: each TabGroupPanel tags its body element with an `anchor-name`, and
-// worktree-level overlay layers render every terminal/browser tab once —
-// keyed by pane id only — then pin each pane to the owning group's anchor via
-// CSS `position-anchor`. Moving a tab between groups now only changes which
-// anchor-name the overlay references, so terminals do not remount and
-// webviews do not reparent/reload.
-//
-// Why `React.memo`: Terminal.tsx has many store subscriptions and re-renders
-// on unrelated updates (terminal keystrokes, editor edits, focus changes).
-// Without memoization, every Terminal re-render would cascade into
-// BrowserPaneOverlayLayer and its BrowserPane subtrees. Memoizing here means
-// the surface only re-renders when its own props (worktreeId / layout /
-// focusedGroupId / isVisible) actually change.
+// Why: overlay pins each once-rendered pane (keyed by pane id) to its group's CSS anchor, so cross-group moves avoid terminal remount / webview reload.
+// React.memo: Terminal.tsx re-renders on unrelated store updates; memoize so this surface only re-renders on its own prop changes.
 const WorktreeSplitSurface = React.memo(function WorktreeSplitSurface({
   worktreeId,
   worktreePath,
@@ -2624,8 +2385,7 @@ const WorktreeSplitSurface = React.memo(function WorktreeSplitSurface({
             ? 'absolute inset-0 flex opacity-0 pointer-events-none'
             : 'absolute inset-0 hidden'
       }
-      // Why: automation and mobile control need paintable webviews, but hidden
-      // worktree controls cannot remain reachable by Tab or assistive tech.
+      // Why: paintable-but-hidden webviews must be inert so they stay unreachable by Tab / assistive tech.
       inert={!isVisible}
       aria-hidden={!isVisible}
     >
diff --git a/src/renderer/src/components/UpdateCard.tsx b/src/renderer/src/components/UpdateCard.tsx
index c080b518f64..0612c91fd39 100644
--- a/src/renderer/src/components/UpdateCard.tsx
+++ b/src/renderer/src/components/UpdateCard.tsx
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: the update card owns the full updater lifecycle in one
-   renderer surface. Keeping the state machine and its presentation variants together avoids
-   scattering tightly coupled update behavior across multiple files. */
+/* eslint-disable max-lines -- Why: keeps the updater state machine and its presentation variants in one file. */
 import { useCallback, useEffect, useId, useRef, useState } from 'react'
 import { usePrefersReducedMotion } from '@/hooks/usePrefersReducedMotion'
 import { useAppStore } from '../store'
@@ -28,10 +26,7 @@ import { translate } from '@/i18n/i18n'
 // ── Helpers ──────────────────────────────────────────────────────────
 
 function releaseUrlForVersion(version: string | null): string {
-  // Why: when no version is cached (typically a failed check), point at the
-  // plain releases listing rather than /releases/latest — /latest also breaks
-  // when GitHub's release API is degraded, and the listing is the most
-  // reliable manual fallback.
+  // Why: fall back to the plain releases listing (not /releases/latest) — /latest also breaks when GitHub's API is degraded.
   return version
     ? `https://github.com/stablyai/orca/releases/tag/v${version}`
     : 'https://github.com/stablyai/orca/releases'
@@ -135,26 +130,15 @@ export function UpdateCard() {
   const [installError, setInstallError] = useState<string | null>(null)
   const [compatibilityRelaunching, setCompatibilityRelaunching] = useState(false)
   const [compatibilitySetupError, setCompatibilitySetupError] = useState<string | null>(null)
-  // Why: the version-based dismiss gate at the bottom of the visibility
-  // section intentionally keeps error cards visible so a download failure
-  // still surfaces even if the user previously dismissed the "available"
-  // card for the same version.  But this means the error card's own X
-  // button cannot hide the card via dismissUpdate alone.  A separate
-  // local flag tracks whether the user has explicitly closed the error
-  // card in this render cycle.
+  // Why: the dismiss gate keeps error cards visible, so a separate local flag tracks the error card's own X close.
   const [errorDismissed, setErrorDismissed] = useState(false)
-  // Why: "not-available" is transient feedback ("You're up to date") that
-  // should auto-dismiss. A local flag avoids polluting the store with
-  // timer state that no other component cares about.
+  // Why: local flag (not store) for the transient "up to date" auto-dismiss — no other component needs it.
   const [autoDismissed, setAutoDismissed] = useState(false)
-  // Why: tracks whether the card is exiting so we can play the fade-out
-  // animation before unmounting.
+  // Tracks card exit so the fade-out animation plays before unmount.
   const [exiting, setExiting] = useState(false)
   const changelog: ChangelogData | null = storeChangelog
 
-  // Why: the 'error' variant of UpdateStatus does not carry a `version` field,
-  // but the card needs the version for the "Download Manually" fallback URL
-  // and for dismiss persistence. Cache it from states that do carry it.
+  // Why: the 'error' variant carries no version, but the card needs it for the fallback URL and dismiss; cache from states that have it.
   const versionRef = useRef<string | null>(null)
   if ('version' in status && status.version) {
     versionRef.current = status.version
@@ -163,17 +147,11 @@ export function UpdateCard() {
     status.state === 'idle' ||
     status.state === 'not-available'
   ) {
-    // Why: a new check cycle has started or completed without an available update.
-    // Clear the cached version so a later check failure cannot dismiss or link to
-    // an unrelated older release that happened to be cached locally.
+    // Why: clear the cached version so a later check failure can't link/dismiss against an unrelated older release.
     versionRef.current = null
   }
 
-  // Why: reset component-local state when a new update cycle begins. Without
-  // this, stale flags from a previous version leak forward — e.g., a failed
-  // image load for version A would suppress the hero for version B, or a
-  // hasStartedDownload flag from version A would cause a Settings-initiated
-  // download for version B to auto-restart.
+  // Why: reset component-local state on a new version so stale flags (media load, hasStartedDownload) don't leak forward.
   const prevVersionRef = useRef<string | null>(null)
   if (status.state === 'available' && status.version !== prevVersionRef.current) {
     prevVersionRef.current = status.version
@@ -183,8 +161,7 @@ export function UpdateCard() {
     setInstallError(null)
   }
 
-  // Why: reset autoDismissed when a new status arrives so the card is
-  // visible again for the next user-initiated check cycle.
+  // Why: reset per-cycle flags when a new status arrives so the card shows again next check cycle.
   const prevStateRef = useRef(status.state)
   if (status.state !== prevStateRef.current) {
     prevStateRef.current = status.state
@@ -202,8 +179,7 @@ export function UpdateCard() {
   const shouldAutoDismissLatest =
     status.state === 'not-available' && 'userInitiated' in status && Boolean(status.userInitiated)
 
-  // Why: auto-dismiss "You're on the latest version" after 3 seconds.
-  // The timer resets if the status changes before it fires.
+  // Auto-dismiss "You're on the latest version" after 3s; timer resets if status changes first.
   useEffect(() => {
     if (!shouldAutoDismissLatest) {
       return
@@ -212,11 +188,8 @@ export function UpdateCard() {
     return () => clearTimeout(timer)
   }, [shouldAutoDismissLatest])
 
-  // Why: quitAndInstall is a side effect that must not run during render —
-  // React StrictMode double-invokes render functions, which would call
-  // quitAndInstall twice. useEffect with a state guard is the safe path.
-  // Gated on hasStartedDownload so a Settings-initiated download doesn't
-  // auto-restart the app — the user expects to click "Restart" in Settings.
+  // Why: quitAndInstall must run in an effect, not render — StrictMode's double render would fire it twice.
+  // Gated on hasStartedDownload so Settings-initiated downloads don't auto-restart (user expects "Restart" there).
   useEffect(() => {
     if (status.state === 'downloaded' && hasStartedDownload.current) {
       void window.api.updater.quitAndInstall().catch((error) => {
@@ -244,8 +217,7 @@ export function UpdateCard() {
       if (node !== null) {
         return
       }
-      // Why: exit timers are owned by the visible update-card surface, so
-      // stale callbacks should be cancelled as soon as that surface unmounts.
+      // Why: cancel exit timers when the card surface unmounts so stale callbacks don't fire.
       clearAnimationTimers()
     },
     [clearAnimationTimers]
@@ -274,26 +246,17 @@ export function UpdateCard() {
     return null
   }
 
-  // Error: show card for user-initiated check failures or for failures tied to
-  // a concrete cached update version (card-initiated and Settings-initiated
-  // download/install flows). Background check failures stay silent.
+  // Error: show for user-initiated failures or failures tied to a cached version; background failures stay silent.
   if (status.state === 'error' && !shouldShowDetailedErrorCard && !isUserInitiated) {
     return null
   }
 
-  // Why: the version-based dismiss gate below intentionally keeps error cards
-  // visible, but when the user explicitly clicks X on the error card itself
-  // the card must disappear. This gate handles that case.
+  // Why: the dismiss gate below keeps error cards visible, so an explicit X on the error card needs this gate to hide it.
   if (status.state === 'error' && errorDismissed) {
     return null
   }
 
-  // Dismiss gate: if the user previously dismissed this version, hide the card
-  // for passive reminder states. Keep active in-progress/error states visible so
-  // explicit install actions can still surface progress and failures.
-  // Why: bypass the gate when the current cycle was user-initiated — the user
-  // explicitly asked to check, so they expect to see the result even if they
-  // dismissed the same version earlier.
+  // Dismiss gate: hide previously-dismissed versions for passive states, keep in-progress/error visible, and bypass for user-initiated checks.
   if (versionRef.current && dismissedVersion === versionRef.current && !updateUserInitiatedCycle) {
     if (status.state !== 'downloading' && status.state !== 'error') {
       return null
@@ -313,19 +276,16 @@ export function UpdateCard() {
 
   const handleUpdate = () => {
     hasStartedDownload.current = true
-    // Why: clicking "Update" implies the user is not worried about interruption,
-    // so dismiss the reassurance tip permanently.
+    // Why: clicking Update implies the user isn't worried about interruption, so retire the reassurance tip.
     if (!reassuranceSeen) {
       markReassuranceSeen()
     }
     void window.api.updater.download()
   }
 
-  // Why: the 'error' variant has no version field, so dismiss needs an
-  // optional explicit version override for error/install-failure states.
+  // Why: the 'error' variant has no version field, so dismiss needs an explicit version override.
   const handleClose = () => {
-    // Why: dismissUpdate clears the store-level manual-check bypass so the
-    // dismiss gate re-engages immediately after closing a requested result.
+    // Why: dismissUpdate clears the store manual-check bypass so the dismiss gate re-engages after closing.
     if (status.state === 'error') {
       setErrorDismissed(true)
       if (cachedVersion) {
@@ -356,11 +316,7 @@ export function UpdateCard() {
       })
   }
 
-  // Why: classify each failure so the card leads with one plain sentence and
-  // the right action, and keeps the raw error behind "Show details" instead of
-  // dumping a PowerShell/stack trace as the headline. Order matters: the
-  // security-stop (wrong publisher) must win over the AV/EDR "check couldn't
-  // run" case so a real integrity failure is never softened into "try again".
+  // Why: order matters — the wrong-publisher security-stop must beat the "check couldn't run" case so integrity failures aren't softened to "try again".
   const isHttp2UpdateError = status.state === 'error' && isHttp2ProtocolError(status.message)
   const isSignatureMismatchError =
     status.state === 'error' && isWindowsSignatureMismatchFailure(status.message)
@@ -388,8 +344,7 @@ export function UpdateCard() {
           }
         : isSignatureMismatchError
           ? {
-              // Security stop: the installer is readable but signed by the wrong
-              // publisher. No retry — only a path to the verified download.
+              // Security stop: installer signed by the wrong publisher — no retry, only a verified-download path.
               variant: 'security',
               title: translate('auto.components.UpdateCard.5b309b19f3', "Update Wasn't Installed"),
               summary: translate(
@@ -397,8 +352,7 @@ export function UpdateCard() {
                 "The installer's publisher doesn't match Orca, so we stopped the update. Don't install this download; check official releases for a corrected version."
               ),
               detail: status.message,
-              // Why: linking the rejected version directly would invite users
-              // to bypass the publisher check by running the same installer.
+              // Why: linking the rejected version would let users bypass the publisher check by re-running it.
               releaseUrl: releaseUrlForVersion(null),
               manualLabel: translate(
                 'auto.components.UpdateCard.c9ff9b9ec2',
@@ -423,17 +377,14 @@ export function UpdateCard() {
                 }
               }
             : {
-                // Why: title is scoped to the operation that failed so check-time
-                // failures (commonly GitHub-side) don't read as a bug in Orca.
+                // Why: title is scoped to the failed operation so check-time (GitHub-side) failures don't read as an Orca bug.
                 title: cachedVersion ? 'Update Error' : 'Update Check Failed',
                 summary: cachedVersion
                   ? 'Could not complete the update.'
                   : 'Could not check for updates.',
                 detail: status.message,
                 releaseUrl: releaseUrlForVersion(cachedVersion),
-                // Why: check-time failures are often transient (offline, GitHub
-                // hiccup), so offer a Re-check next to "Download Manually" instead
-                // of forcing the user into the manual fallback.
+                // Why: check-time failures are often transient, so offer a Re-check instead of forcing manual download.
                 primaryAction: cachedVersion
                   ? {
                       label: translate('auto.components.UpdateCard.48565a32bc', 'Retry Download'),
@@ -474,9 +425,7 @@ export function UpdateCard() {
     }, 150)
   }
 
-  // Why: long-running phases (downloading, downloaded, error) minimize to the
-  // status bar instead of persistently dismissing. A dismiss during an active
-  // download would orphan the in-flight download with no surfaced recovery.
+  // Why: dismissing an active download would orphan it, so long-running phases minimize to the status bar.
   const handleCollapseWithAnimation = () => {
     if (prefersReducedMotion) {
       setCollapsed(true)
@@ -649,9 +598,7 @@ export function UpdateCard() {
     )
   })()
 
-  // Why: show a one-time reassurance tip above the card so first-time users
-  // know updating won't kill their running terminals. Once seen, persisted
-  // to disk so it never reappears.
+  // One-time reassurance tip that updating won't kill running terminals; persisted once seen.
   const showReassurance =
     !reassuranceSeen && (status.state === 'available' || status.state === 'downloading')
 
@@ -724,9 +671,7 @@ function RichCardContent({
   const showMedia =
     release.mediaUrl &&
     !mediaFailed &&
-    // Why: when prefers-reduced-motion is active, hide animated GIFs entirely
-    // rather than showing a frozen frame (GIFs cannot be reliably paused
-    // cross-browser). Static images are shown normally since they produce no motion.
+    // Why: GIFs can't be reliably paused cross-browser, so hide them entirely under reduced-motion.
     !(prefersReducedMotion && isAnimatedGif(release.mediaUrl))
 
   return (
@@ -983,8 +928,7 @@ function ErrorCardContent({
   }
   onClose: () => void
 }) {
-  // Why: the raw error is kept for support but starts collapsed so the card
-  // leads with the plain-language summary, not a PowerShell/stack dump.
+  // Why: raw error starts collapsed so the card leads with the plain summary, not a stack dump.
   const [showDetails, setShowDetails] = useState(false)
   const detailId = useId()
   const isCompatibility = variant === 'http1Compatibility'
@@ -1023,9 +967,7 @@ function ErrorCardContent({
         </div>
       ) : null}
 
-      {/* Why: a caret disclosure sits directly above the raw error it reveals,
-          so the card leads with the plain summary and expands the last-error
-          block in place — the action buttons stay pinned below it. */}
+      {/* Caret disclosure that reveals the raw error while the plain summary stays the lead. */}
       {detail ? (
         <div className="flex flex-col gap-2">
           <Button
diff --git a/src/renderer/src/components/WorktreeJumpPalette.tsx b/src/renderer/src/components/WorktreeJumpPalette.tsx
index e1bb431c76e..ae38e76bb3e 100644
--- a/src/renderer/src/components/WorktreeJumpPalette.tsx
+++ b/src/renderer/src/components/WorktreeJumpPalette.tsx
@@ -181,8 +181,7 @@ type CreateWorktreePaletteItem = {
   type: 'create-worktree'
 }
 
-// Why: Cmd+J is a fast intent surface, not a dump of every setup button.
-// Keep future quick actions curated; route one-time setup flows through Settings.
+// Why: keep quick actions curated — Cmd+J is a fast intent surface, not a dump of every setup button.
 type PaletteItem =
   | WorktreePaletteItem
   | ProjectTargetPaletteItem
@@ -196,8 +195,7 @@ type PaletteListEntry = PaletteItem | CreateWorktreePaletteItem | SectionHeader
 
 const CREATE_WORKSPACE_QUICK_ACTION_ITEM_ID = `quick-action:${CREATE_WORKSPACE_QUICK_ACTION_ID}`
 
-// Why: comfortably outlast the CommandDialog close animation (~150–200ms) so the
-// gated status maps stay live until the fading rows are gone from the DOM.
+// Why: outlast the CommandDialog close animation (~150–200ms) so gated status maps stay live until fading rows are gone.
 const PALETTE_STATUS_INPUTS_LINGER_MS = 300
 
 function getComposerPrefetchRepoId(
@@ -216,8 +214,7 @@ function appendPaletteListEntries(
   target: PaletteListEntry[],
   source: readonly PaletteItem[]
 ): void {
-  // Why: query mode can expose generated-size workspace/tab result lists.
-  // Avoid the function argument limit from `push(...source)`.
+  // Why: source can be large enough to hit the argument limit of push(...source).
   for (const entry of source) {
     target.push(entry)
   }
@@ -326,8 +323,7 @@ function getSettingsTargetFromSectionId(sectionId: string): {
 }
 
 export default function WorktreeJumpPalette(): React.JSX.Element | null {
-  // Why: subscribe this palette to language changes; translated memo contents
-  // recompute on the rerender without using i18n.language as a fake dependency.
+  // Why: subscribe to language changes so translated memos recompute without a fake i18n.language dependency.
   useTranslation()
   const visible = useAppStore((s) => s.activeModal === 'worktree-palette')
   const closeModal = useAppStore((s) => s.closeModal)
@@ -344,11 +340,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   const projectHostSetups = useAppStore((s) => s.projectHostSetups)
   const detectedWorktreesByRepo = useAppStore((s) => s.detectedWorktreesByRepo)
   const pendingWorktreeCreations = useAppStore((s) => s.pendingWorktreeCreations)
-  // Why: keep the (very hot) status maps subscribed through the dialog's close
-  // animation. `visible` flips false synchronously on close, but the CommandDialog
-  // content stays mounted while it fades/zooms out — dropping the maps to empty
-  // there would flash the switcher rows empty/reordered mid-animation. Linger a
-  // beat past close, then let the gate drop the subscription.
+  // Why: keep status maps subscribed through the close animation — dropping them while CommandDialog fades out would flash rows empty mid-animation.
   const [statusInputsLingering, setStatusInputsLingering] = useState(false)
   useEffect(() => {
     if (visible) {
@@ -361,18 +353,8 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     )
     return () => window.clearTimeout(timer)
   }, [visible])
-  // Why: these five status maps drive per-worktree live/working dots and the
-  // switcher sort, but only matter while the palette is active. Two of them
-  // (agentStatusByPaneKey, runtimePaneTitlesByTabId) get a new identity on every
-  // agent-status / pane-title write app-wide, so subscribing to them while the
-  // always-mounted palette is closed re-rendered it on unrelated terminals. Gate
-  // the subscription on active-or-still-closing: a shared frozen constant while
-  // inactive keeps useShallow referentially equal across the churn, and the live
-  // maps flow through the instant the palette opens.
-  // - runtimePaneTitlesByTabId: split-pane tabs with a working agent in a
-  //   non-focused pane still surface as 'working' (matches the sidebar spinner).
-  // - ptyIdsByTabId: the live-pty source of truth — slept tabs keep a wake-hint
-  //   sessionId in tab.ptyId, so without it the palette dot would lie green.
+  // Why: these hot status maps get a new identity on every app-wide write, so gate the subscription on active-or-closing to stop the always-mounted palette re-rendering on unrelated terminals.
+  // Why: ptyIdsByTabId must be included — slept tabs keep a wake-hint sessionId in tab.ptyId, so without it the palette dot would lie green.
   const {
     agentStatusByPaneKey,
     runtimePaneTitlesByTabId,
@@ -431,10 +413,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   )
   const previousBrowserPageIdRef = useRef<string | null>(null)
   const previousBrowserFocusTargetRef = useRef<'webview' | 'address-bar'>('webview')
-  // Why: the exact element focused before Cmd+J opened (e.g. the terminal
-  // textarea the user was typing in) so Escape restores it precisely instead
-  // of the first matching surface in the DOM, which may be a background
-  // worktree's mounted-but-hidden terminal.
+  // Why: the exact element focused before Cmd+J opened, so Escape restores it precisely (not a background worktree's hidden terminal).
   const previousFocusElementRef = useRef<HTMLElement | null>(null)
   const activeGroupSnapshotRef = useRef<CmdJActiveGroupSnapshot | null>(null)
   const wasVisibleRef = useRef(false)
@@ -451,8 +430,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     [repos]
   )
   const hostLabelOverrides = useMemo(() => getHostDisplayLabelOverrides(settings), [settings])
-  // Why: host badges only appear when more than one execution host exists; reuse
-  // the same registry the sidebar host-scope strip builds so labels stay in sync.
+  // Why: reuse the sidebar host-scope registry so host badge labels stay in sync.
   const hostOptions = useMemo(
     () =>
       buildSidebarHostOptions({
@@ -479,8 +457,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   const hasQuery = deferredQuery.trim().length > 0
   const isLoading = repos.length > 0 && Object.keys(worktreesByRepo).length === 0
 
-  // Why: keep running-agent workspaces visible under "Hide sleeping" even when
-  // their live PTY is momentarily absent, matching the sidebar filter. #7197
+  // Why: keep running-agent workspaces visible under "Hide sleeping" even when the live PTY is momentarily absent, matching sidebar. #7197
   const liveAgentActivity = useMemo(() => {
     void agentStatusEpoch
     const statusByWorktreeId = getLiveAgentStatusByWorktreeId(
@@ -492,9 +469,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   }, [agentStatusByPaneKey, agentStatusEpoch, tabsByWorktree])
   const worktreeIdsWithLiveAgent = liveAgentActivity.worktreeIds
 
-  // Why: the empty-query palette mirrors sidebar filters so opening Search
-  // starts from the same quiet list. Typed search switches to the global
-  // non-archived scope below.
+  // Why: empty-query mirrors sidebar filters so Search opens on the same quiet list; typed search widens to global non-archived scope.
   const emptyQueryVisibleWorktrees = useMemo(
     () =>
       allWorktrees.filter((worktree) => {
@@ -533,13 +508,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     ]
   )
 
-  // Why: empty-query rows use focus-recency (lastVisitedAtByWorktreeId) with
-  // lastActivityAt fallback so SSH / quiet worktrees don't get pushed below
-  // the fold by noisy local worktrees. Current worktree is excluded from the
-  // empty-query rows per product model (Cmd+J is a switch surface, not a
-  // "show me everything" surface), but kept in visibleWorktreesForState so
-  // empty-state/loading logic remains unaffected.
-  // See docs/cmd-j-empty-query-ordering.md.
+  // Why: empty-query rows order by focus-recency (quiet/SSH worktrees stay visible) and exclude the current worktree, kept only in visibleWorktreesForState. See docs/cmd-j-empty-query-ordering.md.
   const { visibleWorktreesForState, switchableWorktreesForRows } = useMemo(
     () =>
       orderEmptyQueryWorktrees({
@@ -560,8 +529,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     [allWorktrees, hasQuery, switchableWorktreesForRows]
   )
 
-  // Why: typed queries still route through sortWorktreesSmart — switcher
-  // ranking only diverges from smart-sort on the empty-query branch.
+  // Why: typed queries route through sortWorktreesSmart — ranking only diverges on the empty-query branch.
   const sortedWorktrees = useMemo(
     () =>
       hasQuery
@@ -590,12 +558,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   )
 
   const browserSortedWorktrees = useMemo(() => {
-    // Why: browser-tab search is explicitly cross-worktree, so it must keep
-    // indexing live browser pages even when their owning worktree is archived
-    // or hidden by the default-branch-workspace setting. A user who opened a
-    // tab on the default-branch worktree before toggling hide-on should still
-    // be able to Cmd+J back to it — the setting hides the *workspace row*,
-    // not the browser tabs that live inside it.
+    // Why: browser-tab search is cross-worktree, so keep indexing browser pages even when the owning worktree is archived/hidden.
     return sortWorktreesSmart(
       allWorktrees,
       tabsByWorktree,
@@ -617,9 +580,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     terminalLayoutsByTabId
   ])
 
-  // Why: browser rows need worktree lookups for repo badge colors, and browser
-  // search intentionally includes archived worktrees. This map must cover all
-  // worktrees, not just the non-archived sortedWorktrees used for the Worktrees scope.
+  // Why: browser search includes archived worktrees, so this map must cover all worktrees, not just non-archived.
   const worktreeMap = useMemo(() => {
     const map = new Map<string, Worktree>()
     for (const worktree of browserSortedWorktrees) {
@@ -837,8 +798,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     (BrowserPaletteItem | SimulatorPaletteItem | WorkspaceTabPaletteItem)[]
   >(
     () =>
-      // Why: these result builders emit comparable ascending scores, so one sort
-      // keeps cross-source ranking consistent within the OPEN TABS section.
+      // Why: result builders emit comparable ascending scores, so one sort keeps cross-source ranking consistent.
       [...browserItems, ...simulatorItems, ...workspaceTabItems].sort((a, b) => {
         if (a.result.score !== b.result.score) {
           return a.result.score - b.result.score
@@ -853,8 +813,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     [settingsSections]
   )
   const actionResults = useMemo(() => buildCmdJActionResults(getCmdJQuickActions()), [])
-  // Why: Cmd+J should only offer project jumps the sidebar can actually reveal;
-  // archived-only repos are intentionally left out of this navigation surface.
+  // Why: only offer project jumps the sidebar can reveal — archived-only repos are excluded from navigation.
   const renderableProjectRepoIds = useMemo(() => {
     const ids = new Set<string>()
     for (const worktree of allWorktrees) {
@@ -937,8 +896,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     if (activeView !== 'terminal' || !activeWorktreeId) {
       return
     }
-    // Why: the delete confirmation is also a modal; let the palette close
-    // before mounting it so Radix focus teardown cannot fight the new dialog.
+    // Why: let the palette close before mounting the delete-confirm modal so Radix focus teardown can't fight it.
     queueMicrotask(() => runWorktreeDelete(activeWorktreeId))
   }, [])
 
@@ -987,22 +945,12 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     [actionResults, deferredQuery, quickActionContext, settingsResults]
   )
 
-  // Why: on empty query we cap the worktree section (not open tabs) so the
-  // OPEN TABS header + ≥1 tab row stays visible above the fold — users
-  // with 30+ worktrees would otherwise never see open tabs. The cap is
-  // paired with a "Type to see all N worktrees" hint row so the full list is
-  // one keystroke away. Typing lifts both caps. Cap size is tied to the
-  // palette's max-h-[min(460px,62vh)] viewport math: ~60px/row, ~32px/header,
-  // leaves room for OPEN TABS header + one tab row at default window size.
-  // Revisit if row heights or max-h change.
+  // Why: on empty query, cap the worktree section so the OPEN TABS header + ≥1 row stays above the fold; typing lifts the cap.
   const EMPTY_QUERY_WORKTREE_CAP = 5
   const EMPTY_QUERY_OPEN_TAB_CAP = 5
 
   const paletteSections = useMemo(() => {
-    // Why: the worktree cap only earns its keep when there are open tabs to
-    // protect above-the-fold. With zero open tabs, capping would force
-    // the user to type for no reason — uncap so the recent list fills the
-    // viewport naturally.
+    // Why: the worktree cap only matters when open tabs need above-the-fold protection; uncap with zero open tabs.
     const worktreeCap = !hasQuery && openTabItems.length > 0 ? EMPTY_QUERY_WORKTREE_CAP : Infinity
     const visibleWorktreeItems = hasQuery ? worktreeItems : worktreeItems.slice(0, worktreeCap)
     const visibleProjectTargetItems = hasQuery ? projectTargetItems : []
@@ -1057,10 +1005,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       visibleOpenTabItems.length
     ].filter((count) => count > 0).length
 
-    // Header rule: on empty query each section is categorically distinct
-    // (worktrees vs. open tabs), so a lone header is a useful signpost. On query,
-    // suppress headers unless both sections are populated — otherwise a lone
-    // header above one list is noise.
+    // Header rule: empty query shows lone headers as signposts; on query, suppress unless both sections are populated (else noise).
     const showWorktreeHeader = hasQuery
       ? visibleWorkspaceItemCount > 0 && populatedSectionCount > 1
       : visibleWorktreeItems.length > 0
@@ -1111,8 +1056,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       appendPaletteListEntries(entries, visibleProjectTargetItems)
     }
     if (showCreateAction) {
-      // Why: project/group jump targets are navigation results; keep them
-      // directly after worktree matches before the creation fallback.
+      // Why: project/group jump targets are navigation results — keep them after worktree matches, before the creation fallback.
       entries.push({ id: CREATE_WORKTREE_ITEM_ID, type: 'create-worktree' })
     }
     if (visibleMiddleItems.length > 0) {
@@ -1143,10 +1087,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     [listEntries]
   )
 
-  // Why: empty-state / "has any worktrees?" uses the full visible list
-  // (including current) so the palette never claims to be empty just
-  // because the only visible worktree is the currently active one.
-  // See docs/cmd-j-empty-query-ordering.md.
+  // Why: "has any worktrees?" counts the full visible list (incl. current) so the palette never falsely claims empty. See docs/cmd-j-empty-query-ordering.md.
   const hasAnyWorktrees = visibleWorktreesForState.length > 0
   const hasAnySearchableWorktrees = hasQuery ? searchScopeWorktrees.length > 0 : hasAnyWorktrees
   const hasAnyOpenTabs =
@@ -1171,18 +1112,14 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
               (workspace) => workspace.id === activeBrowserTabId
             )?.activePageId ?? null)
           : null
-      // Why: capture which browser surface had focus *before* Radix Dialog
-      // steals it. By onOpenAutoFocus time, document.activeElement has already
-      // moved to the dialog content, so address-bar detection must happen here.
+      // Why: capture browser focus before Radix Dialog steals it — by onOpenAutoFocus, activeElement is already the dialog.
       previousBrowserFocusTargetRef.current =
         activeTabType === 'browser' &&
         document.activeElement instanceof HTMLElement &&
         document.activeElement.closest('[data-orca-browser-address-bar="true"]')
           ? 'address-bar'
           : 'webview'
-      // Why: same timing constraint — capture the pre-dialog focus target now
-      // so Escape can return focus to the exact input the user left (excluding
-      // document.body, which isn't a meaningful restore target).
+      // Why: same timing constraint — capture pre-dialog focus now so Escape can restore the exact input (not document.body).
       previousFocusElementRef.current =
         document.activeElement instanceof HTMLElement && document.activeElement !== document.body
           ? document.activeElement
@@ -1195,8 +1132,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
 
     if (!visible && wasVisibleRef.current) {
       if (preserveCreateLookupOnCloseRef.current) {
-        // Why: create intentionally closes the palette before GH resolves;
-        // reopening still invalidates the pending lookup above.
+        // Why: create closes the palette before GH resolves; reopening still invalidates the pending lookup above.
         preserveCreateLookupOnCloseRef.current = false
       } else {
         createLookupGuard.invalidate()
@@ -1229,8 +1165,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     if (!visible || !isCreateWorkspaceHighlighted) {
       return
     }
-    // Why: Cmd+J opens the composer after selection; warming the same default
-    // repo here buys time while the user is still on the highlighted row.
+    // Why: prewarm the composer's default repo while the row is highlighted, before Cmd+J opens it.
     prefetchCreateWorkspaceBaseForComposer()
   }, [commandSelectedItemId, prefetchCreateWorkspaceBaseForComposer, visible])
 
@@ -1290,8 +1225,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
         return
       }
       if (previousActiveTabTypeRef.current === 'browser' && previousBrowserPageIdRef.current) {
-        // Why: dismissing Cmd+J from a browser surface should return focus to
-        // that page, not fall through to the generic terminal/editor fallback.
+        // Why: dismissing from a browser surface returns focus to that page, not the generic terminal/editor fallback.
         requestBrowserFocus({
           pageId: previousBrowserPageIdRef.current,
           target: previousBrowserFocusTargetRef.current
@@ -1299,9 +1233,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
         return
       }
       if (previousWorktreeIdRef.current) {
-        // Why: dismissing Cmd+J should return to whatever the user was doing —
-        // restore the exact previously-focused surface (e.g. the terminal they
-        // were typing in) rather than an arbitrary first match.
+        // Why: restore the exact previously-focused surface on dismiss, not an arbitrary first match.
         focusFallbackSurface(previousFocusElementRef.current)
       }
     },
@@ -1340,9 +1272,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
         )
         return
       }
-      // Why: capture the workspace and page info before activateAndRevealWorktree
-      // mutates store state. Store cascades during worktree activation can remap
-      // browser workspace state, making a second findBrowserSelection unreliable.
+      // Why: capture page info before activateAndRevealWorktree mutates store state — a later findBrowserSelection would be unreliable.
       const { worktree, workspace, page } = selection
       const activated = activateAndRevealWorktree(worktree.id)
       if (!activated) {
@@ -1467,8 +1397,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   const handleSelectProjectTarget = useCallback(
     (result: CmdJProjectSearchResult) => {
       skipRestoreFocusRef.current = true
-      // Why: selecting a project or repo group is a sidebar navigation action;
-      // it should reveal the grouping row without activating an arbitrary workspace.
+      // Why: selecting a project/repo group is sidebar navigation — reveal the row without activating an arbitrary workspace.
       revealSidebarRow(result.rowKey, { behavior: 'smooth', highlight: true })
       recordFeatureInteraction('cmd-j')
       closeModal()
@@ -1534,8 +1463,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       )
       closeModal()
       recordFeatureInteraction('cmd-j-create-workspace')
-      // Why: defer opening so Radix fully unmounts the palette's dialog before
-      // the composer modal mounts, avoiding focus churn between the two.
+      // Why: defer so Radix fully unmounts the palette dialog before the composer mounts, avoiding focus churn.
       queueMicrotask(() =>
         openModal('new-workspace-composer', { ...data, telemetrySource: 'command_palette' })
       )
@@ -1546,8 +1474,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       const { number } = ghLink
       const state = useAppStore.getState()
 
-      // Why: the existing-worktree check only needs the issue/PR number, which
-      // is repo-agnostic on the worktree meta side.
+      // Why: the existing-worktree check only needs the issue/PR number (repo-agnostic in worktree meta).
       const matches = allWorktrees.filter(
         (w) => !w.isArchived && (w.linkedIssue === number || w.linkedPR === number)
       )
@@ -1559,12 +1486,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
         return
       }
 
-      // Why: hand the raw URL to the composer's name field so it runs the same
-      // cross-project detection as Cmd+N — surfacing the "Switch project?"
-      // dialog when the URL targets a different project. Pre-resolving here
-      // against an arbitrary repo silently linked cross-project items to the
-      // wrong project and skipped that prompt. Seed the active repo so the
-      // field compares the URL against the project the user is currently in.
+      // Why: hand the raw URL to the composer so it runs Cmd+N cross-project detection; pre-resolving here silently linked to the wrong project.
       const eligibleRepos = state.repos.filter((r) => isGitRepoKind(r))
       const repoForLookup =
         (state.activeRepoId && eligibleRepos.find((r) => r.id === state.activeRepoId)) ||
@@ -1671,8 +1593,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   }, [])
 
   const handleOpenAutoFocus = useCallback((_event: Event) => {
-    // No-op: address-bar detection is handled in the visible effect before
-    // Radix steals focus. This callback exists only to satisfy the prop API.
+    // No-op: focus handled in the visible effect before Radix; exists only to satisfy the prop API.
   }, [])
 
   const resultCount = selectableItems.length
@@ -1695,10 +1616,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
         )
       }
     }
-    // Why: empty-query rows exclude the current worktree, so a single-worktree
-    // setup has hasAnyWorktrees=true but zero switchable rows. Without this
-    // branch the palette would claim "No active worktrees" while one is open
-    // — misleading. See docs/cmd-j-empty-query-ordering.md.
+    // Why: empty-query rows exclude the current worktree, so a single-worktree setup has zero switchable rows. See docs/cmd-j-empty-query-ordering.md.
     if (!hasQuery && hasAnyWorktrees && !hasAnyOpenTabs) {
       return {
         title: translate(
@@ -1786,8 +1704,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
               }
 
               if (entry.type === 'hint') {
-                // Why: plain div (not CommandItem) so cmdk can't land selection
-                // on it and arrow keys skip over it naturally via selectableItems.
+                // Why: plain div (not CommandItem) so cmdk can't select it; arrow keys skip it via selectableItems.
                 return (
                   <div
                     key={entry.id}
@@ -1836,8 +1753,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
                 )
                 const statusLabel = getWorktreeStatusLabel(status)
                 const isCurrentWorktree = activeWorktreeId === worktree.id
-                // Runtime-owned (per-workspace-env) SSH targets are hidden and their relay health is
-                // owned by the runtime layer (broadcasts suppressed) — don't show a false disconnected.
+                // Why: runtime-owned SSH targets have relay health owned by the runtime layer — don't show a false disconnected.
                 const sshConnectionId =
                   repo?.connectionId && !isRuntimeOwnedSshTargetId(repo.connectionId)
                     ? repo.connectionId
diff --git a/src/renderer/src/components/activity/ActivityPrototypePage.tsx b/src/renderer/src/components/activity/ActivityPrototypePage.tsx
index ccb57a05e80..aa7f06c4747 100644
--- a/src/renderer/src/components/activity/ActivityPrototypePage.tsx
+++ b/src/renderer/src/components/activity/ActivityPrototypePage.tsx
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: this prototype keeps the real-data adapter
-and current visual skeleton together until the next refinement pass decides
-which pieces become production modules. */
+/* eslint-disable max-lines -- Why: prototype keeps the real-data adapter and visual skeleton together until a refinement pass splits them into modules. */
 import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import { useShallow } from 'zustand/react/shallow'
 import {
@@ -104,9 +102,7 @@ type ActivityLiveAgentSnapshot = {
   agentType: AgentType
 }
 
-// Why (per-pane thread): the activity feed is keyed on the agent pane (a
-// terminal tab + stable leaf id) rather than on the workspace, so the left list
-// shows one entry per agent. paneKey is the durable identity (`${tabId}:${leafId}`).
+// Why: keyed per agent pane (tab + leaf id), not per workspace, so the list shows one row per agent; paneKey is `${tabId}:${leafId}`.
 type AgentPaneThread = {
   paneKey: string
   paneTitle: string
@@ -352,9 +348,7 @@ function useActivityTerminalPortalStatus(
         if (readyFrame !== null) {
           return
         }
-        // Why: the PTY id can appear before xterm has painted replayed output.
-        // Waiting one frame keeps Activity's cover in place for the blank canvas
-        // frame without moving terminal lifecycle work into global layout effects.
+        // Why: PTY id can appear before xterm paints replayed output; wait one frame so Activity's cover hides the blank frame.
         readyFrame = requestAnimationFrame(() => {
           readyFrame = null
           if (!disposed && getSelectedActivityTerminalPortalStatus(target, paneKey).ready) {
@@ -443,10 +437,7 @@ function agentMeta(event: ActivityEvent): string {
   return event.state === 'waiting' ? `${agent} waiting` : `${agent} blocked`
 }
 
-// Why (label hierarchy): Activity rows need a stable task identity across
-// follow-up turns. The live hook prompt tracks the current turn ("yes",
-// "ok proceed") and must not replace the task title when scanning many agents
-// across worktrees.
+// Why: rows need a stable task identity across follow-up turns; the live turn prompt ("yes", "ok proceed") must not replace the task title.
 function paneTitleForEntry(
   entry: AgentStatusEntry,
   tab: TerminalTab,
@@ -576,9 +567,7 @@ function appendActivityEventsForEntry(args: {
   acknowledgedAt: number
   migrationUnsupportedPtyId?: string
 }): void {
-  // Why: Activity is an append-only history surface. When a user continues in
-  // the same terminal pane, the live entry moves done→working; stateHistory is
-  // the only place the previous done/blocking event still exists.
+  // Why: Activity is append-only; when a pane continues (done→working), stateHistory is the only record of the previous done/blocking event.
   for (const history of args.entry.stateHistory) {
     if (!isActivityEventState(history.state)) {
       continue
@@ -636,9 +625,7 @@ export function buildActivityEvents(args: {
       continue
     }
     const ackAt = args.acknowledgedAgentsByPaneKey[paneKey] ?? 0
-    // Why: live status is separate from historical events. A fresh working turn
-    // should update/create the pane thread without being counted as an unread
-    // done/blocked/waiting event.
+    // Why: live status is separate from history; a fresh working turn updates the thread without counting as an unread done/blocked/waiting event.
     const liveState = freshActivityLiveAgentState(entry, args.now)
     if (liveState) {
       liveAgentByPaneKey[paneKey] = {
@@ -731,10 +718,7 @@ export function buildActivityEvents(args: {
   const perPaneCount = new Map<string, number>()
   const includedEventIds = new Set<string>()
   const capped: ActivityEvent[] = []
-  // Why: reserve each pane's most-recent event before applying the global 80
-  // cap so a pane never disappears from the left list when many panes are
-  // active. The validator's scenario (>16 panes × ≥5 events) could push a
-  // pane's events past the 80-event window, hiding the pane entirely.
+  // Why: reserve each pane's newest event before the global 80-event cap so the validator's >16 panes × ≥5 events can't push a pane out of the window and hide it.
   for (const event of sorted) {
     const paneKey = event.entry.paneKey
     if (perPaneCount.has(paneKey)) {
@@ -833,9 +817,7 @@ export function buildAgentPaneThreads(args: {
       })
       continue
     }
-    // Why: live metadata is the current thread identity. Historical events stay
-    // in the event list, but the row title/time/target must follow the active
-    // turn so a running agent never shows the previous prompt as primary.
+    // Why: row title/time/target must follow the active turn (not historical events) so a running agent never shows the previous prompt as primary.
     existing.paneTitle = paneTitleForEntry(liveAgent.entry, liveAgent.tab, generatedTitlesEnabled)
     existing.worktree = liveAgent.worktree
     existing.repo = liveAgent.repo
@@ -895,8 +877,7 @@ export function ActivityThreadOptionsMenu({
     <DropdownMenu>
       <Tooltip>
         <TooltipTrigger asChild>
-          {/* Why: keep Tooltip and Dropdown from composing refs onto the same
-              button; the crash report's stack loops through Radix setRef. */}
+          {/* Why: keep Tooltip and Dropdown from composing refs onto the same button (Radix setRef crash loop). */}
           <span className="inline-flex shrink-0">
             <DropdownMenuTrigger asChild>
               <Button
@@ -1124,8 +1105,7 @@ export function shouldIgnoreActivityFilterFocusShortcutTarget(
   if (!target) {
     return false
   }
-  // Why: the workspace terminal stays mounted while Activity is open; only the
-  // Activity-portaled terminal should keep Cmd/Ctrl+F for terminal search.
+  // Why: workspace terminal stays mounted while Activity is open; only the Activity-portaled terminal keeps Cmd/Ctrl+F for terminal search.
   return terminalPortalTargets.some((portalTarget) => portalTarget?.contains(target) ?? false)
 }
 
@@ -1162,8 +1142,7 @@ export function handleActivityFilterFocusShortcut({
     return false
   }
   event.preventDefault()
-  // Why: hidden workspace xterms can retain focus behind Activity; capture-phase
-  // handling must stop the chord before xterm forwards it to a local/SSH PTY.
+  // Why: hidden workspace xterms can retain focus behind Activity; stop the chord before xterm forwards it to a local/SSH PTY.
   event.stopPropagation()
   event.stopImmediatePropagation()
   input.focus()
@@ -1258,8 +1237,7 @@ function ThreadRow({
       role="button"
       tabIndex={0}
       onKeyDown={(event) => {
-        // Why: response markdown can contain links; keyboard activation on a
-        // nested link should follow the link instead of selecting the row.
+        // Why: markdown responses can contain links; keyboard activation on a nested link follows the link instead of selecting the row.
         if (isEventFromNestedInteractiveElement(event.target, event.currentTarget)) {
           return
         }
@@ -1269,19 +1247,8 @@ function ThreadRow({
         }
       }}
       className={cn(
-        // Why (selected/hover/unread cues match WorktreeCard):
-        // - selected → solid black/white tint + faint shadow, no hover
-        //   override (the active class wins so hover doesn't fight it).
-        // - non-selected → only then does hover apply (bg-accent/40), so a
-        //   selected row stays visually fixed when the cursor moves over it.
-        // - unread → weight + left-edge primary bar carry the cue; no row
-        //   tint, mirroring WorktreeCard's "weight alone" pattern. Three
-        //   stacked tints (selected + unread + hover) made selected and
-        //   unread look identical when hovered.
-        // Why (asymmetric padding): the title uses leading-snug, which adds
-        // ~3px of internal space above the cap-height that isn't present
-        // below the secondary badge row. Symmetric py made the top read
-        // heavier; the smaller top pad visually evens the row.
+        // Why (WorktreeCard cues): selected = tint+shadow, beats hover; unread = weight + left bar only; stacking all three confused selected vs unread on hover.
+        // Why (asymmetric padding): title leading-snug adds ~3px above cap-height; smaller top pad evens the row.
         'group relative flex w-full cursor-pointer flex-col gap-1 border-b border-border px-3 pt-2.5 pb-3 text-left transition-colors',
         selected
           ? 'bg-black/[0.08] shadow-[0_1px_2px_rgba(0,0,0,0.04)] dark:bg-white/[0.10] dark:shadow-[0_1px_2px_rgba(0,0,0,0.03)]'
@@ -1436,11 +1403,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     useState<ActivityTerminalPortalSlotId>('primary')
   const [primaryPortalTargetEl, setPrimaryPortalTargetEl] = useState<HTMLElement | null>(null)
   const [secondaryPortalTargetEl, setSecondaryPortalTargetEl] = useState<HTMLElement | null>(null)
-  // Why (default width): the thread cards are the primary surface in the
-  // Activity view; the terminal is supplementary. A narrow list squeezed the
-  // prompts to truncated single-liners and made the per-card actions feel
-  // cramped. 480px gives prompts room to breathe at line-clamp-3 and leaves
-  // the action buttons clearly readable.
+  // Why (default width): thread cards are the primary surface; 480px lets prompts fill line-clamp-3 and keeps the per-card actions readable.
   const [threadListWidth, setThreadListWidth] = useState(480)
   const {
     containerRef: threadListRef,
@@ -1469,9 +1432,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
       generatedTitlesEnabled: s.settings?.tabAutoGenerateTitle === true
     }))
   )
-  // Why: agentStatusEpoch is included in the dependency array (but not in the
-  // computation itself) so the memo recomputes when freshness boundaries expire,
-  // even if no new PTY data arrives.
+  // Why: agentStatusEpoch is a dep (not used in the body) so the memo recomputes when freshness boundaries expire even without new PTY data.
   const agentStatusEpoch = useAppStore((s) => s.agentStatusEpoch)
 
   const { events: allEvents, liveAgentByPaneKey } = useMemo(
@@ -1484,10 +1445,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
         worktreeMap: storeData.worktreeMap,
         repoMap: storeData.repoMap,
         acknowledgedAgentsByPaneKey: storeData.acknowledgedAgentsByPaneKey,
-        // Why: Date.now() is read inside the memo (not as a dep) so stale-decay
-        // recalculates whenever agentStatusEpoch ticks. The epoch bumps when the
-        // freshness boundary crosses, driving re-evaluation without coupling to
-        // wall-clock time directly.
+        // Why: Date.now() is read in the memo body (not a dep) so stale-decay recomputes when agentStatusEpoch ticks, not on wall-clock time.
         now: Date.now()
       }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -1507,17 +1465,14 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     selectedPaneKey === null || allThreads.some((thread) => thread.paneKey === selectedPaneKey)
   const effectiveSelectedPaneKey = selectedPaneKeyIsLive ? selectedPaneKey : null
   if (!selectedPaneKeyIsLive) {
-    // Why: Activity rows disappear when agent retention or tab state changes;
-    // clear stale selection before detail/portal rendering can target it.
+    // Why: rows disappear when agent retention or tab state changes; clear stale selection before detail/portal rendering targets it.
     setSelectedPaneKey(null)
   }
 
   const visibleThreads = useMemo(() => {
     const normalizedQuery = isActivitySearchQueryTooLarge(query) ? null : query.trim().toLowerCase()
     return allThreads.filter((thread) => {
-      // Why: keep the just-selected thread visible even after auto-mark-read
-      // flips it to read, otherwise clicking a row in unread-only mode makes it
-      // vanish from the left list while staying selected on the right.
+      // Why: keep the just-selected thread visible after auto-mark-read flips it to read, else unread-only mode makes the clicked row vanish from the list.
       if (
         readFilter === 'unread' &&
         !thread.unread &&
@@ -1540,8 +1495,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     ? (allThreads.find((thread) => thread.paneKey === effectiveSelectedPaneKey) ?? null)
     : null
   const selectedTabId = selectedThread?.tab.id ?? null
-  // Why: repo-less terminal buckets can still produce Activity rows, but the
-  // workspace Terminal tree only portals real worktrees.
+  // Why: repo-less terminal buckets can produce Activity rows, but the workspace Terminal tree only portals real worktrees.
   const selectedHasLiveTab =
     selectedThread && selectedTabId && storeData.worktreeMap.has(selectedThread.worktree.id)
       ? (storeData.tabsByWorktree[selectedThread.worktree.id] ?? []).some(
@@ -1612,18 +1566,8 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     setSecondaryPortalTargetEl(target)
   }, [])
 
-  // Why (no flash on selection): publish the portal descriptor with the
-  // selected thread's worktreeId+tabId directly, instead of letting Terminal
-  // derive it from activeWorktreeId/activeTabId. selectThread updates the
-  // store in multiple steps (setActiveRepo → setActiveWorktree →
-  // setActiveTabType → setActiveTab) and React commits in between can
-  // briefly reflect the new worktree's stale "last active tab" — that's the
-  // wrong-terminal flash. Anchoring the portal to the selected thread
-  // sidesteps the race entirely.
-  // Why useMemo: keep a stable descriptor identity across unrelated re-renders
-  // so subscribers (Terminal → WorktreeSplitSurface) keep their React.memo
-  // bail-outs. The inactive descriptor is a same-size staging slot: the old
-  // terminal stays visible while the next terminal mounts underneath it.
+  // Why (no flash): anchor the portal to the selected thread's ids; selectThread's multi-step store update can briefly reflect a stale "last active tab" (wrong-terminal flash).
+  // Why useMemo: stable descriptor identity so subscribers keep React.memo bail-outs; inactive descriptor stages the next terminal at the same size.
   const portalDescriptors = useMemo(() => {
     const descriptors: ActivityTerminalPortalTarget[] = []
     if (visibleThread && activePortalTargetEl) {
@@ -1666,8 +1610,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
       return
     }
     if (stagedThread && (stagedPortalReady || stagedPortalUnavailable)) {
-      // Why: a stale selected pane should replace the old terminal with the
-      // unavailable state, not leave the previous pane visible under the new row.
+      // Why: a stale selected pane must swap to the unavailable state, not leave the previous pane visible under the new row.
       setActivePortalSlotId(inactivePortalSlotId)
       setDisplayedPaneKey(stagedThread.paneKey)
       return
@@ -1686,14 +1629,8 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     visibleThread
   ])
 
-  // Why useLayoutEffect (not useEffect): publish must happen before paint so
-  // Terminal's portal subscriber rerenders in the same commit. With useEffect
-  // the publish runs after paint, so the user briefly sees Terminal's stale
-  // portal target on screen — the "wrong terminal flash" symptom.
-  // Why no cleanup-to-null on every change: clearing on dependency change
-  // forces the portal through a null state on every thread switch (cleanup →
-  // effect within one commit) which can flash the workspace pane behind the
-  // activity slot. We only null on unmount, via a separate effect below.
+  // Why useLayoutEffect (not useEffect): publish before paint so Terminal's portal subscriber rerenders in the same commit, else the stale target flashes on screen.
+  // Why no cleanup-to-null on each change: it forces the portal through null on every switch, flashing the workspace pane; null only on unmount (effect below).
   // oxlint-disable-next-line react-doctor/no-derived-state-effect -- Why: this publishes portal descriptors to Terminal's external portal store before paint.
   useLayoutEffect(() => {
     setActivityTerminalPortals(portalDescriptors)
@@ -1701,8 +1638,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
 
   const setActivityPageRef = useCallback((node: HTMLDivElement | null): void => {
     if (!node) {
-      // Why: portal cleanup must only happen when the page unmounts; clearing on
-      // descriptor changes flashes the workspace pane behind the activity slot.
+      // Why: portal cleanup must happen only on page unmount; clearing on descriptor changes flashes the workspace pane behind the activity slot.
       setActivityTerminalPortals([])
     }
   }, [])
@@ -1735,9 +1671,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     if (!worktree) {
       return
     }
-    // Why: retained-agent threads can outlive their tab. With no live tab, the
-    // right pane shows the empty-state placeholder; reorienting the workspace
-    // and dispatching focus to a dead tab id would just confuse the user.
+    // Why: retained-agent threads can outlive their tab; without a live tab, reorienting the workspace and focusing a dead tab id would just confuse the user.
     const liveTabs = state.tabsByWorktree[worktree.id] ?? []
     const hasLiveTab = liveTabs.some((t) => t.id === thread.tab.id)
     if (!hasLiveTab) {
@@ -1808,11 +1742,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     storeData.acknowledgeAgents(unreadKeys)
   }
 
-  // Why (page padding): drop top + horizontal padding so the page extends to
-  // the window's left and right edges (matching how sidebars abut the chrome
-  // elsewhere). The titlebar (ActivityTitlebarControls) already provides the
-  // breathing-room band above; the right pane's title row supplies its own
-  // top padding (pt-2) so the heading isn't pinned to the titlebar.
+  // Why (page padding): no top/horizontal padding so the page reaches the window edges; the titlebar and the right pane's title row (pt-2) supply the top spacing.
   return (
     <div ref={setActivityPageRef} className="flex h-full min-h-0 flex-col bg-background pb-3">
       <main className="flex min-h-0 flex-1 overflow-hidden">
@@ -1905,11 +1835,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
                   )}
                 </TooltipContent>
               </Tooltip>
-              {/* Why (overflow menu): "Mark all read" is a low-frequency,
-                  destructive-feeling action — parking it behind a `…` keeps
-                  the toolbar focused on the high-frequency Filter + unread
-                  toggle while still giving the action a stable home next to
-                  the list it acts on (rather than the titlebar). */}
+              {/* Why (overflow menu): "Mark all read" is low-frequency and destructive-feeling; behind `…` keeps the toolbar on the frequent Filter + unread toggle. */}
               <ActivityThreadOptionsMenu
                 compactMode={compactMode}
                 hasUnreadThreads={hasUnreadThreads}
@@ -1980,9 +1906,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
         <section className="min-w-0 flex-1 overflow-hidden">
           {selectedThread ? (
             <div className="flex h-full min-h-0 flex-col">
-              {/* Why (no header action button): per-card hover actions on the
-                  thread list (Mark unread, Open) are the primary controls now,
-                  so the header keeps just the thread identity. */}
+              {/* Why (no header action button): per-card hover actions (Mark unread, Open) are the primary controls now, so the header keeps just the thread identity. */}
               <div className="flex shrink-0 items-start gap-4 border-b border-border px-4 pt-2 pb-3">
                 <div className="min-w-0">
                   <div className="flex min-w-0 items-start gap-2">
@@ -2007,9 +1931,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
                   </div>
                 </div>
               </div>
-              {/* Why: Terminal stays mounted in the hidden workspace tree while
-                  Activity is open. This target lets that existing TerminalPane
-                  move here instead of creating a second PTY/xterm owner. */}
+              {/* Why: Terminal stays mounted in the hidden workspace tree; this target moves that existing TerminalPane here instead of spawning a second PTY/xterm owner. */}
               {(() => {
                 // Why: retained threads can outlive their tab; portal needs a live TerminalPane to render into.
                 if (!selectedHasLiveTab) {
diff --git a/src/renderer/src/components/browser-pane/BrowserPane.tsx b/src/renderer/src/components/browser-pane/BrowserPane.tsx
index 2d555f5c77d..55e3a67a7c3 100644
--- a/src/renderer/src/components/browser-pane/BrowserPane.tsx
+++ b/src/renderer/src/components/browser-pane/BrowserPane.tsx
@@ -237,8 +237,7 @@ const BROWSER_ANNOTATION_INTENT_OPTIONS = [
   }
 ] as const
 
-// Why: priority remains in the persisted annotation shape for backwards
-// compatibility, but the annotation UI no longer exposes urgency choices.
+// Why: priority stays in the persisted annotation shape for backwards compat, though the UI no longer exposes urgency choices.
 const DEFAULT_BROWSER_ANNOTATION_PRIORITY: BrowserAnnotationPriority = 'important'
 const BROWSER_PAGE_ZOOM_FEEDBACK_MS = 1400
 
@@ -330,8 +329,7 @@ function createBrowserAnnotationId(): string {
 function createBrowserAnnotationPayload(payload: BrowserGrabPayload): BrowserAnnotationPayload {
   return {
     ...payload,
-    // Why: annotations are persisted renderer state; screenshot data is a
-    // transient copy action payload and can be megabytes per selection.
+    // Why: annotations are persisted; screenshot data is a transient copy payload that can be megabytes per selection.
     screenshot: null
   }
 }
@@ -709,10 +707,7 @@ function getOpenableExternalUrl(
     try {
       currentUrl = webview.getURL() || fallbackUrl
     } catch {
-      // Why: restored browser tabs render before the guest emits dom-ready.
-      // Electron throws if toolbar code queries navigation state too early, and
-      // that renderer exception blanks the whole IDE on launch. Fall back to the
-      // persisted tab URL until the guest is fully attached.
+      // Why: querying nav state before dom-ready throws and blanks the whole IDE on launch; fall back to the persisted URL.
       currentUrl = fallbackUrl
     }
   }
@@ -725,9 +720,7 @@ function getCurrentBrowserUrl(webview: Electron.WebviewTag | null, fallbackUrl:
     try {
       currentUrl = webview.getURL() || fallbackUrl
     } catch {
-      // Why: toolbar actions still need a stable URL during early guest attach
-      // and restore. Fall back to the persisted tab URL instead of throwing
-      // and dropping browser actions on freshly restored tabs.
+      // Why: toolbar actions need a stable URL during early guest attach/restore; fall back to the persisted URL instead of throwing.
       currentUrl = fallbackUrl
     }
   }
@@ -750,12 +743,7 @@ function retryBrowserTabLoad(
     return
   }
 
-  // Why: once Chromium lands on chrome-error://chromewebdata/, reload() can
-  // simply refresh the internal error page instead of retrying the original
-  // destination. Force navigation back to the attempted URL so Retry and the
-  // toolbar reload button actually re-attempt the failed page. Keep the last
-  // failure visible until a real success arrives so retry does not briefly
-  // drop the user back to a blank black guest surface.
+  // Why: after chrome-error://, reload() only refreshes the error page — force navigation back to the attempted URL; keep the failure visible until success.
   onUpdatePageState(browserTab.id, {
     loading: true,
     title: retryUrl
@@ -788,9 +776,7 @@ export default function BrowserPane({
   const browserPageIds = useMemo(() => browserPages.map((page) => page.id), [browserPages])
   const automationVisiblePageIds = useBrowserAutomationVisiblePageIds(browserPageIds)
   const mobileDrivenPageIds = useBrowserMobileDrivenPageIds(browserPageIds)
-  // Why: inactive Electron webviews must stay mounted in their original DOM
-  // parent. Parking them by unmounting/reparenting loses form text and SPA
-  // state on normal tab switches.
+  // Why: inactive webviews must stay mounted in their original DOM parent; unmounting/reparenting loses form text and SPA state.
   const renderedBrowserPages = browserPages.filter(
     (page) => !getBrowserPageRuntimeEnvironmentId(page, activeRuntimeEnvironmentId)
   )
@@ -949,10 +935,7 @@ function RemoteBrowserPagePane({
   const closeBrowserTab = useAppStore((s) => s.closeBrowserTab)
   const keybindings = useAppStore((state) => state.keybindings)
 
-  // Why: a remote runtime that predates browser.certificate-trust.v1 cannot
-  // honor a proceed request, so the "Proceed Anyway (Unsafe)" affordance stays
-  // hidden until the connected runtime positively advertises support (design
-  // doc: older runtimes never show an enabled proceed action).
+  // Why: runtimes predating browser.certificate-trust.v1 can't honor a proceed request, so hide "Proceed Anyway" until support is advertised.
   const [remoteCertificateTrustSupported, setRemoteCertificateTrustSupported] = useState(false)
   const remoteCertificateEnvironmentId = remotePageHandle?.environmentId ?? null
   const certificateChallengeId = certificateFailure?.challengeId ?? null
@@ -1045,8 +1028,7 @@ function RemoteBrowserPagePane({
       clearStreamFrame()
       setRemoteError(null)
       setBusy(false)
-      // Why: a runtime-side tab close is the remote equivalent of closing the
-      // visible browser tab; don't leave a dead pane behind with a not-found RPC.
+      // Why: a runtime-side tab close mirrors closing the visible tab; don't leave a dead pane behind.
       const workspacePageCount = state.browserPagesByWorkspace[browserTab.workspaceId]?.length ?? 0
       if (workspacePageCount <= 1) {
         closeBrowserTab(browserTab.workspaceId)
@@ -1128,8 +1110,7 @@ function RemoteBrowserPagePane({
         { timeoutMs: 15_000, suppressFeatureInteraction: true }
       )
       try {
-        // Why: the streamed bitmap can include the host compositor surface,
-        // while CDP input wants the guest page's CSS viewport coordinates.
+        // Why: the streamed bitmap can include the host compositor surface, but CDP input wants the guest page's CSS viewport coords.
         const viewport = await callRuntimeRpc(
           target,
           'browser.eval',
@@ -1209,10 +1190,7 @@ function RemoteBrowserPagePane({
   )
 
   useEffect(() => {
-    // Why: StrictMode (and any real remount) runs mount→cleanup→mount. The
-    // cleanup sets mountedRef false; without re-arming it on mount, every
-    // subsequent operation token reads as stale (isCurrentRemoteOperationToken
-    // gates on mountedRef) and the pane wedges on "Opening remote browser".
+    // Why: StrictMode's mount→cleanup→mount leaves mountedRef false; re-arm or operation tokens read stale and the pane wedges.
     mountedRef.current = true
     return () => {
       mountedRef.current = false
@@ -1243,11 +1221,7 @@ function RemoteBrowserPagePane({
   }, [clearPendingRemoteWheel])
 
   useEffect(() => {
-    // Why: only reset the visible frame/wheel when the pane's identity changes.
-    // The stream/operation generations are owned solely by the streaming effect
-    // below — bumping them here too races that effect (e.g. under StrictMode's
-    // mount→cleanup→mount), leaving its captured token permanently one behind so
-    // the pane wedges on "Opening remote browser" while frames are available.
+    // Why: only reset frame/wheel on identity change; bumping the stream/operation generations here races the streaming effect and wedges the pane.
     remoteStreamViewportSizeRef.current = null
     clearPendingRemoteWheel()
     clearStreamFrame()
@@ -1352,8 +1326,7 @@ function RemoteBrowserPagePane({
       if (!removedHandle) {
         return
       }
-      // Why: remote browser tabs outlive React components on the daemon. Close
-      // only when the local page is gone or its owning runtime environment is.
+      // Why: remote tabs outlive React components on the daemon; close only when the local page or its runtime environment is gone.
       void callRuntimeRpc(
         { kind: 'environment', environmentId: removedHandle.environmentId },
         'browser.tabClose',
@@ -1643,9 +1616,7 @@ function RemoteBrowserPagePane({
       streamSubscriptionRef.current = null
       activeStreamTokenRef.current = null
       remoteStreamViewportSizeRef.current = null
-      // Why: browser navigation can close and recreate the screencast stream.
-      // Keep the last frame visible during restart so remote browser panes do
-      // not flash back to the generic loading placeholder on every navigation.
+      // Why: navigation recreates the screencast stream; keep the last frame during restart so panes don't flash the loading placeholder.
       if (!restart) {
         clearStreamFrame()
       }
@@ -1787,9 +1758,7 @@ function RemoteBrowserPagePane({
         return
       }
 
-      // Why: the runtime stream validates frames against the viewport it was
-      // started with. After a pane resize, restart media so new-size frames are
-      // accepted instead of leaving the renderer on the last old-size bitmap.
+      // Why: the runtime stream validates frames against its start viewport, so restart media after resize or new-size frames get rejected.
       streamGenerationRef.current += 1
       activeStreamTokenRef.current = null
       streamSubscriptionRef.current = null
@@ -2001,8 +1970,7 @@ function RemoteBrowserPagePane({
         setRemoteError(message)
         onUpdatePageState(browserTab.id, {
           loading: false,
-          // Why: validatedUrl crosses process/persistence boundaries, so redact a
-          // Kagi session token the same way the main-process failure path does.
+          // Why: validatedUrl is persisted, so redact the Kagi session token like the main-process failure path does.
           loadError: {
             code: 0,
             description: message,
@@ -2037,8 +2005,7 @@ function RemoteBrowserPagePane({
   )
 
   // Browser history shortcuts for SSH/runtime browsers.
-  // Why: remote browser panes have no local webview ref, so history shortcuts
-  // must route through the runtime RPC methods rather than desktop WebContents.
+  // Why: remote panes have no local webview ref, so route history through runtime RPC instead of WebContents.
   useEffect(() => {
     if (!isActive) {
       return
@@ -2413,8 +2380,7 @@ function RemoteBrowserPagePane({
     if (!image || !frameUrl) {
       return
     }
-    // Why: React delegates wheel listeners passively in Chromium, so native
-    // non-passive binding is required to prevent page scroll and console noise.
+    // Why: React binds wheel listeners passively in Chromium, so bind natively non-passive to preventDefault scroll.
     image.addEventListener('wheel', handleRemoteScreenshotWheel, { passive: false })
     return () => image.removeEventListener('wheel', handleRemoteScreenshotWheel)
   }, [frameUrl, handleRemoteScreenshotWheel])
@@ -2427,9 +2393,7 @@ function RemoteBrowserPagePane({
     remoteFailureUrl !== 'about:blank' &&
     remoteFailureUrl !== ORCA_BROWSER_BLANK_URL
 
-  // Why: markup works on remote panes by snapshotting the already-displayed
-  // screencast <img> — no in-page injection needed, so it is enabled here even
-  // though element-grab annotations are not.
+  // Why: markup snapshots the displayed screencast <img> (no injection), so it works on remote panes even though element-grab doesn't.
   const markup = useMarkupMode({
     getCaptureContext: useCallback((): MarkupCaptureContext | null => {
       const element = imageRef.current
@@ -2847,9 +2811,7 @@ function BrowserPagePane({
   inputLockedRef.current = inputLocked
   const navigateBrowserHistoryRef = useRef<(direction: 'back' | 'forward') => void>(() => {})
   navigateBrowserHistoryRef.current = (direction: 'back' | 'forward'): void => {
-    // Why: Logitech Options+ side-button remaps on macOS arrive as these
-    // keyboard shortcuts. This local pane owns the webview ref, so route the
-    // remap through the same navigation path as the toolbar buttons.
+    // Why: Logitech Options+ side-button remaps arrive as these chords on macOS; route through the same nav path as the toolbar.
     if (direction === 'back') {
       webviewRef.current?.goBack()
     } else {
@@ -2872,18 +2834,11 @@ function BrowserPagePane({
   const initialBrowserUrlRef = useRef(browserTab.url)
   const browserTabUrlRef = useRef(browserTab.url)
   const activeLoadFailureRef = useRef<BrowserLoadError | null>(browserTab.loadError)
-  // Why: CDP viewport emulation does not survive all renderer process swaps
-  // (cross-origin navigations, crashes). We reapply on every dom-ready from
-  // this ref so the persisted preset survives reloads without re-running the
-  // webview lifecycle effect whenever the preset changes.
+  // Why: CDP viewport emulation doesn't survive renderer process swaps, so reapply the preset from this ref on every dom-ready.
   const viewportPresetIdRef = useRef(browserTab.viewportPresetId ?? null)
   viewportPresetIdRef.current = browserTab.viewportPresetId ?? null
   const trackNextLoadingEventRef = useRef(false)
-  // Why: tracks the most recent URL the webview has navigated to or been
-  // observed at, from any source (navigation events, address bar, initial
-  // load). The URL sync effect checks this ref to avoid force-navigating
-  // the webview to an intermediate redirect URL — which would restart the
-  // redirect chain and cause an infinite loop.
+  // Most-recent observed webview URL; URL sync checks it to avoid force-navigating to an intermediate redirect (which would loop the redirect chain).
   const lastKnownWebviewUrlRef = useRef<string | null>(null)
   const onUpdatePageStateRef = useRef(onUpdatePageState)
   const onSetUrlRef = useRef(onSetUrl)
@@ -3026,10 +2981,7 @@ function BrowserPagePane({
 
   const keepAddressBarFocusRef = useRef(false)
 
-  // Inline toast that appears near the grabbed element instead of the global
-  // bottom-right toaster, so feedback feels spatially connected to the action.
-  // Why: positioned below (or above, if near viewport bottom) so it doesn't
-  // occlude the element the user just selected.
+  // Inline toast near the grabbed element (below, or above near the viewport bottom) so it doesn't occlude the selection.
   const [grabToast, setGrabToast] = useState<{
     message: string
     type: 'success' | 'error'
@@ -3056,10 +3008,7 @@ function BrowserPagePane({
   const dismissGrabToast = useCallback(() => {
     clearTimeout(grabToastTimerRef.current)
     setGrabToast(null)
-    // Why: only rearm if the grab state is still 'confirming', meaning the
-    // auto-copy toast is dismissing naturally. If the user already triggered
-    // a shortcut (C/S) that called rearm, the state will be 'armed' and we
-    // skip to avoid a double-rearm race.
+    // Why: only rearm while 'confirming'; if a C/S shortcut already rearmed (state 'armed'), skip to avoid a double-rearm race.
     if (
       grabRef.current.state === 'confirming' &&
       !(grabIntentRef.current === 'annotate' && pendingAnnotationPayloadRef.current)
@@ -3098,9 +3047,7 @@ function BrowserPagePane({
     [dismissGrabToast]
   )
 
-  // Why: the same in-guest picker powers two flows. Cmd/Ctrl+C preserves the
-  // original one-click copy behavior, while the toolbar annotation action turns
-  // the selected element into a pending feedback note.
+  // Why: the same in-guest picker powers two flows — Cmd/Ctrl+C copies, the toolbar action creates a pending annotation.
   useEffect(() => {
     if (grab.state !== 'confirming' || !grab.payload) {
       return
@@ -3164,10 +3111,7 @@ function BrowserPagePane({
   }, [browserTab.id, browserTab.url])
 
   useEffect(() => {
-    // Why: if the user is actively typing in the address bar (focused), do not
-    // clobber their in-progress query when an async URL update lands (e.g., the
-    // configured default URL resolving after a new tab opens). Syncing will
-    // resume on the next legitimate URL change after the input loses focus.
+    // Why: don't clobber an in-progress address-bar query when an async URL update lands; syncing resumes once the input blurs.
     if (document.activeElement === addressBarInputRef.current) {
       return
     }
@@ -3218,13 +3162,7 @@ function BrowserPagePane({
       if (event.browserPageId !== browserTab.id) {
         return
       }
-      // Why: convert the OS screen cursor position to the renderer's CSS
-      // viewport coordinates. This is the only approach immune to coordinate
-      // space mismatches between the guest process and the renderer (caused
-      // by UI zoom, DPI scaling, or Electron version differences).
-      // window.screenX/Y gives the window origin in the same screen
-      // coordinate system that screen.getCursorScreenPoint() uses. Dividing
-      // by the zoom factor converts screen points to CSS pixels.
+      // Why: convert OS screen cursor coords to renderer CSS pixels — immune to guest/renderer coordinate-space mismatches from zoom/DPI.
       const zoomFactor = Math.pow(1.2, window.api.ui.getZoomLevel())
       const x = Math.round((event.screenX - window.screenX) / zoomFactor)
       const y = Math.round((event.screenY - window.screenY) / zoomFactor)
@@ -3271,12 +3209,7 @@ function BrowserPagePane({
     return () => window.removeEventListener('keydown', handleKeyDown, true)
   }, [contextMenu])
 
-  // Why: position: fixed can be offset by ancestor CSS properties (backdrop-filter,
-  // transform, will-change) that create new containing blocks. Even with a Portal to
-  // document.body, global CSS or Electron chrome can shift the element. Measuring the
-  // actual rendered position and correcting before paint is immune to all of these.
-  // Additionally, flip the menu when it would overflow the viewport edge so right-clicking
-  // near the screen border keeps the entire menu visible.
+  // Why: ancestor CSS (transform/backdrop-filter) can shift position:fixed even via a body Portal, so measure/correct before paint; also flip on viewport overflow.
   useLayoutEffect(() => {
     const el = contextMenuRef.current
     if (!el || !contextMenu) {
@@ -3286,8 +3219,7 @@ function BrowserPagePane({
     el.style.top = `${contextMenu.y}px`
     const rect = el.getBoundingClientRect()
 
-    // Why: CSS containing blocks can shift "fixed" elements. Capture the offset
-    // between where we asked CSS to place the element and where it actually rendered.
+    // Why: CSS containing blocks can shift "fixed" elements; capture the offset between requested and actual position.
     const offsetX = contextMenu.x - rect.left
     const offsetY = contextMenu.y - rect.top
 
@@ -3414,12 +3346,7 @@ function BrowserPagePane({
       return
     }
     keepAddressBarFocusRef.current = true
-    // Why: terminal activation restores xterm focus on a later animation frame
-    // when the surface changes. A single address-bar focus attempt can lose
-    // that race, leaving the new browser tab on <body>. Retry briefly across a
-    // few frames so a freshly opened blank tab still lands in the location bar,
-    // but keep the request one-shot so revisiting the tab later does not steal
-    // focus back from the user.
+    // Why: terminal activation re-grabs focus a frame later; retry a few frames to win the race, but stay one-shot so revisiting the tab doesn't steal focus.
     let cancelled = false
     let frameId = 0
     let attempts = 0
@@ -3473,9 +3400,7 @@ function BrowserPagePane({
         frameId = window.requestAnimationFrame(runFocus)
       }
     }
-    // Why: jump-palette browser focus can be queued before the target page
-    // pane mounts. Persisting the request outside React lets the active page
-    // claim it once mounted instead of depending on a transient event race.
+    // Why: focus can be queued before the pane mounts; persisting outside React lets it be claimed on mount instead of racing an event.
     frameId = window.requestAnimationFrame(runFocus)
     return () => {
       cancelled = true
@@ -3497,8 +3422,7 @@ function BrowserPagePane({
         return
       }
       if (focusTarget === 'address-bar') {
-        // Why: palette-triggered address-bar focus has to survive the same
-        // follow-up browser load events as the existing blank-tab path.
+        // Why: palette-triggered address-bar focus must survive the same follow-up load events as the blank-tab path.
         keepAddressBarFocusRef.current = true
         focusAddressBarNow()
         return
@@ -3506,19 +3430,14 @@ function BrowserPagePane({
       keepAddressBarFocusRef.current = false
       focusWebviewNow()
     }
-    // Why: queued focus lets a page claim a request after mount, but palette
-    // re-selecting an already-active page never remounts. Listening for the
-    // matching event lets the active pane consume the durable request
-    // immediately without regressing the mount/activation path above.
+    // Why: an already-active page never remounts, so listen for the event to consume the durable focus request immediately.
     window.addEventListener(ORCA_BROWSER_FOCUS_REQUEST_EVENT, handleBrowserFocusRequest)
     return () =>
       window.removeEventListener(ORCA_BROWSER_FOCUS_REQUEST_EVENT, handleBrowserFocusRequest)
   }, [browserTab.id, focusAddressBarNow, focusWebviewNow, isActive])
 
   // Cmd/Ctrl+F — find in page (renderer path: focus on browser chrome)
-  // Why: unlike grab-mode shortcuts (bare C/S) which skip editable targets,
-  // Cmd+F is a modified chord that should always open find — even from the
-  // address bar. This matches Chrome/Safari behavior.
+  // Why: unlike bare C/S grab shortcuts, Cmd+F should always open find even from the address bar (matches Chrome/Safari).
   useEffect(() => {
     if (!isActive) {
       return
@@ -3537,9 +3456,7 @@ function BrowserPagePane({
   }, [isActive, keybindings])
 
   // Cmd/Ctrl+F — find in page (IPC path: focus inside webview guest)
-  // Why: a focused webview guest is a separate Chromium process so the renderer
-  // keydown handler above never fires. Main intercepts the chord and sends it
-  // back here so find works whether focus is on the toolbar or the page.
+  // Why: a focused guest is a separate Chromium process, so main forwards the chord back here.
   useEffect(() => {
     if (!isActive) {
       return
@@ -3550,9 +3467,7 @@ function BrowserPagePane({
   }, [isActive])
 
   // Browser history shortcuts (renderer path: focus on browser chrome)
-  // Why: macOS cannot deliver Logitech side-button navigation to Electron, but
-  // Logi Options+ can remap those buttons to standard browser history chords.
-  // Handle the chords here when focus is on the toolbar or address bar.
+  // Why: macOS can't deliver Logitech side-buttons to Electron; Logi Options+ remaps them to history chords, handled here when chrome is focused.
   useEffect(() => {
     if (!isActive) {
       return
@@ -3576,9 +3491,7 @@ function BrowserPagePane({
   }, [isActive, keybindings])
 
   // Browser history shortcuts (IPC path: focus inside webview guest)
-  // Why: a focused webview is a separate WebContents. Main forwards the same
-  // remapped history chords back here so page focus and toolbar focus behave
-  // identically.
+  // Why: a focused webview is a separate WebContents, so main forwards the chords back here.
   useEffect(() => {
     if (!isActive) {
       return
@@ -3596,10 +3509,7 @@ function BrowserPagePane({
   }, [isActive])
 
   // Cmd/Ctrl+R — reload (renderer path: focus on browser chrome, not in guest)
-  // Why: when focus is inside the renderer chrome (address bar, toolbar buttons)
-  // rather than the webview guest, the guest shortcut forwarding in main never
-  // fires. Handle the chord directly here so reload works regardless of where
-  // focus sits within the browser pane.
+  // Why: guest shortcut forwarding never fires when focus is on browser chrome, so handle the chord directly here.
   useEffect(() => {
     if (!isActive) {
       return
@@ -3632,9 +3542,7 @@ function BrowserPagePane({
   }, [isActive, keybindings])
 
   // Cmd/Ctrl+R — reload (IPC path: focus inside webview guest)
-  // Why: a focused webview guest is a separate Chromium process so the renderer
-  // keydown handler above never fires. Main intercepts the chord and sends it
-  // back here so reload works whether focus is on the toolbar or the page.
+  // Why: a focused guest is a separate Chromium process, so main forwards the chord back here.
   useEffect(() => {
     if (!isActive) {
       return
@@ -3694,18 +3602,12 @@ function BrowserPagePane({
             webview.getTitle(),
             webview.getURL() || browserTabUrlRef.current
           ),
-          // Why: webview attach can transiently report isLoading() even
-          // when no user-visible navigation happened. If we sync that into the
-          // tab model on every activation, switching tabs flashes the blue
-          // loading dot and makes hidden tabs look like they are reloading.
-          // Only explicit navigation/load events should drive Orca's loading UI.
+          // Why: attach can transiently report isLoading() with no real navigation; syncing it would flash the loading dot on tab switches.
           canGoBack: webview.canGoBack(),
           canGoForward: webview.canGoForward()
         })
       } catch {
-        // Why: Electron only exposes these getters after the guest fully
-        // attaches. Ignoring the transient failure avoids crashing Orca while
-        // the webview guest becomes ready.
+        // Why: these getters only exist after the guest fully attaches; ignore the transient failure during attach.
       }
     },
     [browserTab.id]
@@ -3713,8 +3615,7 @@ function BrowserPagePane({
 
   const syncBrowserAnnotationViewportBridge = useCallback((): void => {
     const pendingAnnotationPayload = pendingAnnotationPayloadRef.current
-    // Why: existing annotation badges are rendered in the guest process for
-    // compositor-smooth scroll; only the pending dialog needs viewport messages.
+    // Why: existing badges render in-guest for smooth scroll; only the pending dialog needs viewport messages.
     const markers = browserAnnotationsRef.current.map((annotation, index) => ({
       id: annotation.id,
       index,
@@ -3732,16 +3633,11 @@ function BrowserPagePane({
         token: annotationViewportBridgeTokenRef.current
       })
       .catch(() => {
-        // The viewport bridge is visual-only; stale markers are less bad than
-        // breaking the browser pane on a navigated or destroyed guest.
+        // The viewport bridge is visual-only; stale markers beat breaking the pane on a destroyed guest.
       })
   }, [browserTab.id])
 
-  // Why: this effect manages the full lifecycle of the webview DOM element —
-  // creation, event wiring, and teardown. browserTab.url is
-  // intentionally excluded — it changes on every navigation, and including it
-  // would destroy and recreate the webview on every page load. URL-dependent
-  // logic inside the effect reads from browserTabUrlRef instead.
+  // Why: browserTab.url excluded from deps (changes every navigation → would destroy/recreate the webview); URL logic reads browserTabUrlRef.
   // eslint-disable-next-line react-hooks/exhaustive-deps -- see comment above
   useEffect(() => {
     let container = ensureBrowserPageViewport(browserTab.id, workspaceId)?.container ?? null
@@ -3766,25 +3662,16 @@ function BrowserPagePane({
     let needsInitialDefaultZoom = ensuredWebview.created
 
     if (!ensuredWebview.created) {
-      // pointerEvents is already applied inside ensureBrowserPageWebview for the
-      // reused-webview path, so it isn't repeated here.
+      // pointerEvents already applied inside ensureBrowserPageWebview for the reused-webview path.
       syncNavigationState(webview)
-      // Why: seed the ref with the store URL so the URL sync effect does not
-      // force-navigate an already-mounted webview that is on the right page.
-      // getURL() can throw briefly during attach, so use the store URL from the
-      // last navigation event.
+      // Why: seed from the store URL (getURL() can throw during attach) so URL sync won't force-navigate an already-correct webview.
       lastKnownWebviewUrlRef.current =
         normalizeBrowserNavigationUrl(browserTabUrlRef.current) ?? null
     }
 
     webviewRef.current = webview
 
-    // Why: the viewport shell is created display:none and the lifecycle cleanup
-    // parks it; the separate visibility layout effect (deps isActive/isPaintable)
-    // does NOT re-run when the viewport first appears (slotViewportReady flip) or
-    // on remount, so the shell must be un-parked here — before the initial
-    // `webview.src` is assigned — or the guest navigates while hidden and stays
-    // blank/about:blank.
+    // Why: un-park the shell before webview.src is assigned or the guest navigates while hidden and stays blank (the visibility layout effect doesn't re-run on first appear).
     applyBrowserPageViewportLayout(browserTab.id, { paintable: isPaintable, active: isActive })
 
     const onContainerDragOver = (event: globalThis.DragEvent): void => {
@@ -3823,8 +3710,7 @@ function BrowserPagePane({
           }
           return registered
         })
-        // Why: normalize IPC rejection to false so the dom-ready fallback can
-        // retry attach-policy races without an unhandled promise rejection.
+        // Why: normalize IPC rejection to false so the dom-ready fallback can retry attach-policy races.
         .catch(() => false)
         .finally(() => {
           if (registrationInFlight?.promise === promise) {
@@ -3836,9 +3722,7 @@ function BrowserPagePane({
     }
 
     const handleDidAttach = (): void => {
-      // Why: certificate failures can happen before dom-ready. Register at
-      // attach so main can map the initial failure to this page; dom-ready below
-      // remains an idempotent fallback for attach-policy races.
+      // Why: register at attach since cert failures can precede dom-ready; the dom-ready path stays an idempotent fallback.
       void registerGuest().finally(() => syncBrowserAnnotationViewportBridge())
     }
 
@@ -3862,17 +3746,10 @@ function BrowserPagePane({
         }
         needsInitialDefaultZoom = false
       }
-      // Why: CDP Emulation.setDeviceMetricsOverride and related overrides are
-      // scoped to the guest's debugger session and do not survive all
-      // cross-origin navigations (renderer swaps). Reapplying on dom-ready is
-      // idempotent, so users who picked a viewport preset keep it after
-      // reloads, SPA navigations, and persisted-session restoration.
+      // Why: CDP viewport overrides are scoped to the debugger session and don't survive cross-origin nav, so reapply (idempotently) on dom-ready.
       const presetId = viewportPresetIdRef.current
       const preset = getBrowserViewportPreset(presetId)
-      // Why: always reapply on dom-ready (including null) because
-      // Emulation.setDeviceMetricsOverride can persist across same-origin navigations
-      // within the same renderer. Sending null ensures CDP matches the store state
-      // instead of showing a stale emulated viewport after the user picks "Default".
+      // Why: reapply even null so CDP matches store state; setDeviceMetricsOverride persists across same-origin nav and would leave a stale viewport.
       void window.api.browser.setViewportOverride({
         browserPageId: browserTab.id,
         override: preset ? browserViewportPresetToOverride(preset) : null
@@ -3880,8 +3757,7 @@ function BrowserPagePane({
     }
 
     const handleDidStartLoading = (): void => {
-      // Why: reloads replace the document without changing URL, invalidating
-      // captured element rects and DOM context just like navigation does.
+      // Why: a reload replaces the document without changing the URL, invalidating captured element rects like a navigation does.
       clearBrowserPageAnnotationsRef.current(browserTab.id)
       setPendingAnnotationPayload(null)
       setBrowserOverlayViewport({ scrollX: 0, scrollY: 0, version: 0 })
@@ -3926,10 +3802,7 @@ function BrowserPagePane({
           normalizeBrowserNavigationUrl(browserModelUrl) ?? browserModelUrl
         if (normalizedAttemptedUrl === normalizedCurrentUrl) {
           trackNextLoadingEventRef.current = false
-          // Why: some webview failures still emit did-stop-loading on the
-          // original destination URL. If we clear loadError here, the failed
-          // navigation falls back to a blank Chromium surface even though Orca
-          // already knows this exact load failed.
+          // Why: some failures still emit did-stop-loading on the original URL; keep loadError so the known-failed load isn't cleared to a blank surface.
           onUpdatePageStateRef.current(browserTab.id, {
             loading: false,
             title: getBrowserDisplayTitle(webview.getTitle(), browserModelUrl),
@@ -3946,8 +3819,7 @@ function BrowserPagePane({
       lastKnownWebviewUrlRef.current =
         normalizeBrowserNavigationUrl(browserModelUrl) ?? browserModelUrl
       rememberLiveBrowserUrl(browserTab.id, browserModelUrl)
-      // Why: don't overwrite in-progress typing. See comment on the
-      // browserTab.url sync effect above.
+      // Why: don't overwrite in-progress typing (see the browserTab.url sync effect above).
       if (document.activeElement !== addressBarInputRef.current) {
         setAddressBarValue(toDisplayUrl(browserModelUrl))
       }
@@ -4025,9 +3897,7 @@ function BrowserPagePane({
         return
       }
       if (event.errorCode === -3) {
-        // Why: Chromium reports redirect/cancel races as ERR_ABORTED (-3) even
-        // when the replacement navigation succeeds. Ignore that noise so Orca
-        // does not show a false load failure for a working page.
+        // Why: Chromium reports redirect/cancel races as ERR_ABORTED (-3) even when the replacement navigation succeeds; ignore to avoid a false failure.
         return
       }
       trackNextLoadingEventRef.current = false
@@ -4070,10 +3940,7 @@ function BrowserPagePane({
     webview.addEventListener('focus', dismissAddressBarSuggestions)
     webview.addEventListener('did-start-loading', handleDidStartLoading)
     webview.addEventListener('did-stop-loading', handleDidStopLoading)
-    // Why: separate handler registered only on 'did-navigate' (full page loads),
-    // NOT on 'did-navigate-in-page'. The shared handleDidNavigate is registered
-    // on both events, so adding find-close logic there would also close on SPA
-    // hash changes and pushState calls, which fire constantly on single-page apps.
+    // Why: close find only on full 'did-navigate', not the shared handler, which also fires on SPA in-page hash/pushState changes.
     const handleFindCloseOnNavigate = (): void => {
       setFindOpen(false)
     }
@@ -4087,10 +3954,7 @@ function BrowserPagePane({
     webview.addEventListener('console-message', handleAnnotationViewportMessage)
 
     if (needsInitialNavigation) {
-      // Why: connection-refused localhost tabs can fail before Electron wires up
-      // event delivery if src is assigned too early. Attach listeners first so
-      // Orca never misses the initial did-fail-load signal for a new tab.
-      // Only non-blank initial tabs should light up Orca's loading indicator.
+      // Why: set src only after listeners attach so a fast localhost failure isn't missed; only non-blank tabs show the loading indicator.
       const initialUrl =
         normalizeBrowserNavigationUrl(initialBrowserUrlRef.current) ?? ORCA_BROWSER_BLANK_URL
       trackNextLoadingEventRef.current = initialUrl !== ORCA_BROWSER_BLANK_URL
@@ -4118,18 +3982,12 @@ function BrowserPagePane({
         webviewRef.current = null
       }
 
-      // Why: park the viewport when chrome unmounts (worktree switch) so the
-      // guest stays alive. Destruction is reserved for explicit close paths.
+      // Why: park the viewport on chrome unmount (worktree switch) to keep the guest alive; destroy only on explicit close.
       moveFocusToRendererBeforeWebviewDetach(webview)
       parkBrowserPageViewport(browserTab.id)
     }
-    // Why: this effect mounts and wires up webview event listeners once per tab
-    // identity. browserTab.url is intentionally excluded: re-running on URL
-    // changes would detach/reattach the webview, cancelling in-progress
-    // navigations. Callbacks use refs so they always see current values.
-    // webviewPartition IS included: switching profiles changes the partition,
-    // which requires destroying and recreating the webview since Electron does
-    // not allow changing a webview's partition after creation.
+    // Why: wire listeners once per tab identity. browserTab.url is excluded (re-running would detach/reattach and cancel navigations; callbacks use refs).
+    // webviewPartition IS included: Electron can't change a webview's partition after creation, so a profile switch must recreate it.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     browserTab.id,
@@ -4163,9 +4021,7 @@ function BrowserPagePane({
     return () => {
       resizeObserver?.disconnect()
     }
-    // Why: slotViewportReady gates viewport creation. Re-run once the viewport
-    // exists so visibility AND the chrome-inset measurement land on a real shell
-    // (the first render no-ops because ensureBrowserPageViewport returned null).
+    // Why: re-run once slotViewportReady flips so visibility and chrome-inset land on a real viewport (first render no-ops).
   }, [browserTab.id, isActive, isPaintable, slotViewportReady])
 
   useEffect(() => {
@@ -4187,12 +4043,7 @@ function BrowserPagePane({
     if (!normalizedUrl) {
       return
     }
-    // Why: navigation events (did-navigate, did-stop-loading) update both the
-    // store URL and this ref to the same value. If they match, the store URL
-    // change came from a navigation event — not a user action — so there is
-    // nothing to navigate to. Skipping here prevents the sync effect from
-    // force-navigating the webview back to an intermediate redirect URL, which
-    // would restart the redirect chain and cause an infinite loop.
+    // Why: navigation events set both the store URL and this ref; a match means the change came from navigation, so skip to avoid a redirect infinite loop.
     if (lastKnownWebviewUrlRef.current === normalizedUrl) {
       return
     }
@@ -4200,9 +4051,7 @@ function BrowserPagePane({
     try {
       liveUrl = webview.getURL() || null
     } catch {
-      // Why: newly attached guests can briefly reject getURL() before the
-      // underlying guest is fully ready. Skip entirely so we do not
-      // misinterpret a transient error as a URL mismatch and force-navigate.
+      // Why: a newly attached guest can reject getURL(); skip so a transient error isn't misread as a mismatch and force-navigated.
       return
     }
     const normalizedLiveUrl = liveUrl ? (normalizeBrowserNavigationUrl(liveUrl) ?? liveUrl) : null
@@ -4212,9 +4061,7 @@ function BrowserPagePane({
       webview.src !== normalizedUrl &&
       declaredSrc !== normalizedUrl
     ) {
-      // Why: browserTab.url changes are Orca-driven navigations (address bar,
-      // terminal link open, retry target update). Gate the next did-start-loading
-      // event so only real navigations, not tab activation churn, show loading UI.
+      // Why: browserTab.url changes are Orca-driven navigations; gate did-start-loading so only real navigations show loading UI.
       trackNextLoadingEventRef.current = normalizedUrl !== ORCA_BROWSER_BLANK_URL
       lastKnownWebviewUrlRef.current = normalizedUrl
       webview.src = normalizedUrl
@@ -4256,17 +4103,11 @@ function BrowserPagePane({
           }
         })
       } catch {
-        // Why: the guest can still be mid-attach while the loading spinner is
-        // visible. Polling is only a fallback for missed failure events, so
-        // transient getURL() errors should be ignored until the next tick.
+        // Why: ignore transient getURL() errors from a mid-attach guest; this poll is only a fallback.
       }
     }
 
-    // Why: some Electron builds paint Chromium's internal chrome-error page
-    // without delivering a timely did-fail-load event to the renderer webview.
-    // Polling only while the active tab is "loading" gives Orca a last-resort
-    // path to swap the black guest surface without waking every retained
-    // inactive browser pane on a 250ms loop.
+    // Why: some Electron builds paint chrome-error pages without a did-fail-load event; poll only while the active tab loads as a fallback.
     detectChromiumErrorPage()
     const intervalId = window.setInterval(detectChromiumErrorPage, 250)
     return () => window.clearInterval(intervalId)
@@ -4292,29 +4133,19 @@ function BrowserPagePane({
     [grab, grabIntent, recordFeatureInteraction]
   )
 
-  // CmdOrCtrl+C toggles grab mode
-  // Why: Cmd+C is deliberately repurposed inside the browser pane so that the
-  // most natural "copy" gesture enters grab mode, letting the user visually
-  // pick and copy an element.  Normal text copy inside the webview guest is
-  // handled by the guest page itself (Chromium's built-in Cmd+C) and never
-  // reaches the host renderer keydown listener.
+  // Why: Cmd+C is repurposed as the grab-mode gesture; native text copy in the guest is handled by Chromium and never reaches here.
   useEffect(() => {
-    // Why: without the isActive gate, every mounted BrowserPagePane registers
-    // a global keydown listener, so Cmd+C would toggle grab mode on all panes
-    // simultaneously — not just the active one.
+    // Why: gate on isActive so only the active pane's global keydown listener toggles grab mode.
     if (!isActive) {
       return
     }
     const shortcutPlatform = getShortcutPlatform()
     const handleKeyDown = (e: KeyboardEvent): void => {
-      // Why: let native Cmd+C work in text inputs (address bar, search fields,
-      // contentEditable regions). Only intercept when focus is on a non-input
-      // element so grab-mode toggle doesn't swallow copy in form controls.
+      // Why: don't intercept in editable targets so native Cmd+C still copies in inputs/contentEditable.
       if (isEditableKeyboardTarget(e.target)) {
         return
       }
-      // Why: while the markup overlay is open, don't let the grab shortcut start
-      // the in-guest picker behind it — matching the disabled grab toolbar buttons.
+      // Why: don't start the in-guest picker behind an open markup overlay (matches the disabled toolbar buttons).
       if (
         !markup.isActive &&
         keybindingMatchesAction('browser.grabElement', e, shortcutPlatform, keybindings)
@@ -4336,9 +4167,7 @@ function BrowserPagePane({
       if (!keybindingMatchesAction('browser.focusAddressBar', e, shortcutPlatform, keybindings)) {
         return
       }
-      // Why: Cmd/Ctrl+L is a browser-local focus command. Capture it before
-      // the surrounding workspace or any embedded editor surface can treat the
-      // same chord as something else.
+      // Why: capture Cmd/Ctrl+L before the workspace or an embedded editor can claim the same chord.
       e.preventDefault()
       e.stopPropagation()
       focusAddressBarNow()
@@ -4347,10 +4176,7 @@ function BrowserPagePane({
     return () => window.removeEventListener('keydown', handleKeyDown, true)
   }, [focusAddressBarNow, isActive, keybindings])
 
-  // Why: a focused webview guest receives Cmd/Ctrl+C inside Chromium, not the
-  // host renderer window. Main forwards the chord back only when the page
-  // would not use it for native copy, so grab mode still toggles from web
-  // content without stealing real copy from inputs or selections.
+  // Why: a focused guest gets Cmd/Ctrl+C inside Chromium; main forwards it back only when the page wouldn't use it for native copy.
   useEffect(() => {
     return window.api.browser.onGrabModeToggle((tabId) => {
       if (tabId === browserTab.id) {
@@ -4359,12 +4185,7 @@ function BrowserPagePane({
     })
   }, [browserTab.id, startGrabIntent])
 
-  // Why: single-key shortcuts (C / S) let the user copy the hovered element
-  // without clicking. During 'armed'/'awaiting' state, the shortcut calls the
-  // extractHoverPayload IPC to read the currently hovered element directly.
-  // During 'confirming' state, it uses the already-captured payload instead.
-  // The shortcuts only fire when grab mode is active, so they don't interfere
-  // with normal typing elsewhere.
+  // C / S copy the hovered element without clicking: extract via IPC while armed/awaiting, else use the captured payload.
   const grabPayloadRef = useRef(grab.payload)
   grabPayloadRef.current = grab.payload
   const handleGrabActionShortcut = useCallback(
@@ -4391,8 +4212,7 @@ function BrowserPagePane({
       }
 
       if (grab.state === 'confirming') {
-        // Why: left-click auto-copies, so only S (screenshot) is useful.
-        // But right-click (contextMenu) skips auto-copy, so C must still work.
+        // Why: right-click (contextMenu) skips the left-click auto-copy, so C must still work here.
         if (grab.contextMenu && key === 'c') {
           const currentPayload = grabPayloadRef.current
           if (currentPayload) {
@@ -4475,9 +4295,7 @@ function BrowserPagePane({
     })
   }, [browserTab.id, grab.state, handleGrabActionShortcut])
 
-  // Why: Radix DropdownMenu fires onOpenChange(false) before onSelect, so
-  // the rearm in onOpenChange would clear the payload before the handler runs.
-  // This ref lets onOpenChange skip the rearm when a menu action was taken.
+  // Why: Radix fires onOpenChange(false) before onSelect, so this flag lets onOpenChange skip the rearm that would clear the payload first.
   const grabMenuActionTakenRef = useRef(false)
 
   // Handlers for the right-click context dropdown menu
@@ -4759,8 +4577,7 @@ function BrowserPagePane({
             'auto.components.browser.pane.BrowserPane.87eb75f7d2',
             'Enter a valid http(s) or localhost URL.'
           ),
-          // Why: the user may have pasted a Kagi URL with a token; redact
-          // before persisting it into BrowserPage.loadError.
+          // Why: redact a possible Kagi session token before persisting into loadError.
           validatedUrl: redactKagiSessionToken(addressBarValue.trim()) || 'about:blank'
         }
       })
@@ -4769,9 +4586,7 @@ function BrowserPagePane({
     navigateToUrl(nextUrl)
   }
 
-  // Why: the store initially holds 'about:blank', but once the webview loads
-  // with the safe data: URL, handleDidStopLoading writes the resolved URL back.
-  // Match both so the "New Browser Tab" overlay stays visible for blank tabs.
+  // Why: a blank tab reads as 'about:blank' or the resolved data: URL, so match both to keep the "New Browser Tab" overlay visible.
   const isBlankTab = browserTab.url === 'about:blank' || browserTab.url === ORCA_BROWSER_BLANK_URL
   const externalUrl = getOpenableExternalUrl(webviewRef.current, browserTab.url)
   const currentBrowserUrl = getCurrentBrowserUrl(webviewRef.current, browserTab.url)
@@ -4796,8 +4611,7 @@ function BrowserPagePane({
     if (!webview) {
       return
     }
-    // Why: desktop reclaim uses a React overlay, but Electron webviews can
-    // keep receiving native input unless their own hit testing is disabled.
+    // Why: Electron webviews keep receiving native input under a React overlay unless their own hit testing is disabled.
     webview.style.pointerEvents = inputLocked ? 'none' : 'auto'
   }, [inputLocked])
 
@@ -4806,10 +4620,7 @@ function BrowserPagePane({
     if (!webview) {
       return
     }
-    // Why: Electron webviews render in their own compositor layer, so a React
-    // overlay can sit "under" a failed guest and still look like a black page.
-    // Fully removing the guest from layout is more reliable than visibility
-    // toggles here; some Electron builds keep painting a hidden guest layer.
+    // Why: some Electron builds keep painting a hidden guest layer, so drop it from layout (display:none) instead of just hiding it.
     webview.style.display = showFailureOverlay ? 'none' : 'flex'
   }, [showFailureOverlay])
 
@@ -4831,8 +4642,7 @@ function BrowserPagePane({
       event.preventDefault()
       event.stopPropagation()
 
-      // Why: browser drops open one URL; multi-path drags must not silently
-      // degrade into opening whichever selected file happened to lead.
+      // Why: a browser opens one URL, so reject multi-path drags rather than silently opening the lead file.
       const dragPaths = readWorkspaceFileDragPaths(event.dataTransfer, { maxPaths: 1 })
       if (dragPaths.status === 'rejected') {
         setResourceNotice(getWorkspaceFileDragRejectionMessage(dragPaths.reason))
@@ -4924,14 +4734,11 @@ function BrowserPagePane({
             ? 'pointer-events-none z-0 opacity-0'
             : 'pointer-events-none hidden'
       )}
-      // Why: automation-visible and mobile-driven webviews must stay paintable,
-      // but hidden toolbar and guest content cannot stay keyboard-focusable.
+      // Why: hidden panes stay paintable (automation/mobile) but must not stay keyboard-focusable.
       inert={!isActive}
       aria-hidden={!isActive}
     >
-      {/* IPC-driven context menu — rendered in a Portal so position: fixed is
-          relative to the viewport, not affected by ancestor backdrop-filter or
-          transform properties that create new containing blocks. */}
+      {/* IPC-driven context menu in a Portal so position:fixed escapes ancestor transform/backdrop-filter containing blocks. */}
       {contextMenu
         ? createPortal(
             <>
@@ -5180,10 +4987,7 @@ function BrowserPagePane({
 
           <Tooltip>
             <TooltipTrigger asChild>
-              {/* Why: wrap the disabled button in a span so pointer events still
-                reach the tooltip trigger — Radix (and the DOM) drop hover
-                events on disabled <button>, which is why the previous native
-                `title` attribute fired inconsistently. */}
+              {/* Why: disabled <button> drops hover events, so wrap in a span so the tooltip trigger still fires. */}
               <span className="inline-flex">
                 <Button
                   size="icon"
@@ -5784,14 +5588,12 @@ function BrowserPagePane({
                   </div>
                 </div>
               ) : null}
-              {/* Right-click context dropdown: positioned at the element's center,
-            shown when grab.contextMenu is true (user right-clicked). */}
+              {/* Right-click context dropdown, positioned at the grabbed element's center. */}
               <DropdownMenu
                 open={grab.state === 'confirming' && grab.contextMenu && grabIntent === 'copy'}
                 onOpenChange={(open) => {
                   if (!open && grab.state === 'confirming') {
-                    // Why: skip rearm if a menu action (Copy/Screenshot) already
-                    // handled the rearm — see grabMenuActionTakenRef.
+                    // Why: skip rearm if a menu action already handled it — see grabMenuActionTakenRef.
                     if (grabMenuActionTakenRef.current) {
                       grabMenuActionTakenRef.current = false
                       return
@@ -5853,10 +5655,7 @@ function BrowserPagePane({
                 </DropdownMenuContent>
               </DropdownMenu>
 
-              {/* Inline toast bubble (left-click auto-copy feedback). Positioned
-            below (or above if near viewport bottom) so it doesn't occlude
-            the element. The "···" button opens the same action dropdown as
-            right-click for users who prefer clicking. */}
+              {/* Inline toast bubble; flips above the element when near the viewport bottom so it doesn't occlude it. */}
               {grabToast ? (
                 <div
                   className="absolute z-30 flex items-center animate-in fade-in zoom-in-95 duration-150"
diff --git a/src/renderer/src/components/browser-pane/BrowserPaneOverlayLayer.tsx b/src/renderer/src/components/browser-pane/BrowserPaneOverlayLayer.tsx
index 19f3a7e2999..00008a0500f 100644
--- a/src/renderer/src/components/browser-pane/BrowserPaneOverlayLayer.tsx
+++ b/src/renderer/src/components/browser-pane/BrowserPaneOverlayLayer.tsx
@@ -8,12 +8,7 @@ import { tabGroupBodyAnchorName } from '../tab-group/tab-group-body-anchor'
 import { useBrowserAutomationVisibilityForAny } from './browser-automation-visibility'
 import { useBrowserMobileDriverForAny } from '@/lib/pane-manager/browser-mobile-driver-state'
 
-// Why: Electron `<webview>` destroys its guest contents whenever its DOM
-// parent changes. Rendering paintable BrowserPanes at the worktree level
-// (keyed only by browserTab.id) means moving an active tab between groups
-// never reparents the webview — it only updates the overlay's CSS
-// `position-anchor` so the pane tracks the new owning group's body via
-// native CSS anchor positioning.
+// Why: Electron <webview> destroys its guest on DOM reparent, so BrowserPanes render at worktree level and moving a tab between groups only swaps the overlay's CSS position-anchor.
 
 type BrowserOverlayAssignment = {
   groupId: string
@@ -26,27 +21,15 @@ const EMPTY_GROUPS: readonly TabGroup[] = []
 
 type BrowserOverlaySlotProps = {
   browserTab: BrowserTabState
-  // Why: `undefined` means this browser tab has no owning group (an "orphan" —
-  // present in `browserTabs` but not referenced by any group's unified-tab
-  // list). See the fallback branch below for why these slots remain hidden.
+  // Why: undefined = orphan tab (in browserTabs but not referenced by any group's unified-tab list); the fallback branch keeps these hidden.
   groupId: string | undefined
   isActive: boolean
-  // Why: the legacy architecture rendered BrowserPane inside TabGroupPanel, so
-  // React events from the pane bubbled through TabGroupPanel's
-  // `onPointerDown={focusGroup}` / `onFocusCapture={focusGroup}`. Now that
-  // BrowserPane lives in a worktree-level overlay that is a SIBLING of
-  // TabGroupSplitLayout, those events no longer reach TabGroupPanel — so in
-  // split view, clicking the browser chrome would leave
-  // `activeGroupIdByWorktree` stale. The overlay slot re-implements that
-  // focus sync directly, targeting the owning group.
+  // Why: overlay is a sibling of the group layout, so pane focus doesn't bubble to TabGroupPanel; re-sync it here or split-view clicks leave activeGroupIdByWorktree stale.
   onFocusOwningGroup: ((groupId: string) => void) | undefined
   isWorktreeActive: boolean
 }
 
-// Why: each overlay slot is memoized so its BrowserPane subtree only re-renders
-// when its own assignment, active state, or worktree visibility changes.
-// Without this, unrelated worktree mutations (terminal keystrokes, editor
-// updates, etc.) would cascade into every BrowserPane.
+// Why: memoize each slot so unrelated worktree mutations don't cascade a re-render into every BrowserPane subtree.
 const BrowserOverlaySlot = memo(function BrowserOverlaySlot({
   browserTab,
   groupId,
@@ -54,8 +37,7 @@ const BrowserOverlaySlot = memo(function BrowserOverlaySlot({
   onFocusOwningGroup,
   isWorktreeActive
 }: BrowserOverlaySlotProps): React.JSX.Element {
-  // Why: persistent page viewports (webview guests) live under this root so they
-  // survive BrowserPane chrome unmounts on worktree switch without reparenting.
+  // Why: persistent page viewports (webview guests) live under this root so they survive BrowserPane chrome unmounts without reparenting.
   const setSlotViewportRef = useCallback(
     (node: HTMLDivElement | null): void => {
       registerBrowserOverlaySlotViewport(browserTab.id, node)
@@ -70,19 +52,10 @@ const BrowserOverlaySlot = memo(function BrowserOverlaySlot({
   const automationVisible = useBrowserAutomationVisibilityForAny(browserPageIds)
   const mobileDriven = useBrowserMobileDriverForAny(browserPageIds)
   const isPaintable = isActive || automationVisible || mobileDriven
-  // Why: hidden worktrees keep lightweight overlay slots mounted, but their
-  // Electron webviews must park unless a remote controller needs the guest.
+  // Why: hidden worktrees keep lightweight overlay slots, but park their webviews unless a remote controller needs the guest.
   const shouldMountPane = isWorktreeActive || automationVisible || mobileDriven
-  // Why: each overlay pins itself to the owning TabGroupPanel's body via CSS
-  // anchor positioning. `anchor()` resolves top/left relative to the viewport,
-  // and the overlay's own `position: absolute` inside a positioned ancestor
-  // (the worktree surface div) converts those to the surface's coordinate
-  // space. `anchor-size()` fills the slot exactly. When the tab moves between
-  // groups, only `positionAnchor` changes and the browser relayouts on its
-  // own — no measurement or state updates.
-  //
-  // The orphan branch (no anchorName) stays display:none until the tab is
-  // reassigned (e.g. mid-move) or explicitly destroyed via `closeBrowserTab`.
+  // Why: CSS anchor positioning pins the overlay to its owning group's body — a tab move only swaps positionAnchor, no measurement/state.
+  // Orphan branch (no anchorName) stays display:none until the tab is reassigned or destroyed.
   const style: React.CSSProperties = useMemo(
     () =>
       anchorName
@@ -123,19 +96,13 @@ const BrowserOverlaySlot = memo(function BrowserOverlaySlot({
       onFocusCapture={handleFocus}
     >
       <div ref={setSlotViewportRef} className="absolute inset-0 flex min-h-0 flex-col" />
-      {/* Why: moving an Electron webview between DOM parents destroys the guest
-          document in some Electron builds. Visible worktree browsers stay in
-          stable overlay slots; hidden worktrees park the heavy pane subtree. */}
+      {/* Why: hidden worktrees park the heavy pane subtree; visible ones keep stable slots so reparenting can't destroy the webview guest. */}
       {shouldMountPane ? <BrowserPane browserTab={browserTab} isActive={isActive} /> : null}
     </div>
   )
 })
 
-// Why: memoize so parent re-renders (e.g. `WorktreeSplitSurface` re-rendering
-// because `focusedGroupId` changed — a prop this component doesn't consume)
-// don't rerun the overlay's zustand selector or the assignments mapping.
-// The child `BrowserOverlaySlot` is already memoized, but skipping this layer
-// entirely when its own props are unchanged keeps the fast path fastest.
+// Why: memoize so parent re-renders on props this layer doesn't consume (e.g. focusedGroupId) don't rerun its selector or assignments mapping.
 const BrowserPaneOverlayLayer = memo(function BrowserPaneOverlayLayer({
   worktreeId,
   isWorktreeActive
@@ -152,20 +119,13 @@ const BrowserPaneOverlayLayer = memo(function BrowserPaneOverlayLayer({
   )
   const focusGroup = useAppStore((state) => state.focusGroup)
 
-  // Why: stable callback identity so BrowserOverlaySlot's memo isn't broken by
-  // a fresh function reference every render. The group id is passed in at call
-  // time so the same callback serves every slot regardless of which group owns
-  // that tab.
+  // Why: stable identity so BrowserOverlaySlot's memo holds; groupId is passed at call time so one callback serves every slot.
   const focusOwningGroup = useCallback(
     (groupId: string) => focusGroup(worktreeId, groupId),
     [focusGroup, worktreeId]
   )
 
-  // Why: derive the lookup OUTSIDE the zustand selector so shallow equality
-  // holds across unrelated store mutations. If we built the object inside the
-  // selector, every store change would create a new reference and useShallow
-  // would never find equality — the overlay would re-render on every
-  // keystroke in an unrelated terminal.
+  // Why: build this lookup outside the zustand selector — a fresh object inside it would break useShallow equality and re-render on every unrelated mutation.
   const groupActiveTabById = useMemo(() => {
     const lookup: Record<string, string | null | undefined> = {}
     for (const group of groups) {
@@ -174,14 +134,7 @@ const BrowserPaneOverlayLayer = memo(function BrowserPaneOverlayLayer({
     return lookup
   }, [groups])
 
-  // Map each browser tab to the group that owns it (if any) and whether it's
-  // the currently active tab in that group. Tabs that exist in `browserTabs`
-  // but are not referenced by any group's unified-tab list are "orphans". In
-  // normal flows this is a transient mid-move state, not a steady state:
-  // closing a tab calls `closeBrowserTab` which removes it from `browserTabs`
-  // (and `destroyPersistentWebview` tears down the guest), and "Close Group"
-  // closes each browser tab before collapsing the group shell — no
-  // follow-to-sibling migration happens.
+  // Map each browser tab to its owning group; tabs not in any group's unified-tab list are transient mid-move "orphans", not a steady state.
   const assignments = useMemo(() => {
     const entries = new Map<string, BrowserOverlayAssignment>()
     for (const tab of unifiedTabs) {
diff --git a/src/renderer/src/components/dashboard/DashboardAgentRow.tsx b/src/renderer/src/components/dashboard/DashboardAgentRow.tsx
index 1a84a985ba5..05c11660793 100644
--- a/src/renderer/src/components/dashboard/DashboardAgentRow.tsx
+++ b/src/renderer/src/components/dashboard/DashboardAgentRow.tsx
@@ -12,9 +12,7 @@ import type { AgentStatusState } from '../../../../shared/agent-status-types'
 import type { DashboardAgentRow as DashboardAgentRowData } from './useDashboardData'
 import { getAgentRowPrimaryText } from '@/lib/agent-row-primary-text'
 
-// Why: the dashboard tracks its own rollup states (incl. 'idle'); narrow to the
-// shared dot states for rendering, falling back to 'idle' for any unknown
-// value so an unexpected state never crashes a row.
+// Why: narrow the dashboard's rollup states to shared dot states, defaulting unknowns to 'idle' so a row never crashes.
 function asDotState(state: AgentStatusState | 'idle'): AgentDotState {
   switch (state) {
     case 'working':
@@ -44,15 +42,9 @@ function formatTimeAgo(ts: number, now: number): string {
   return `${days}d ago`
 }
 
-// Why: surface the moment the agent most recently transitioned *into* done.
-// When the current live state is done, use `stateStartedAt` (not `updatedAt`)
-// — `updatedAt` is refreshed on within-state pings (tool/prompt) and would
-// drift away from the true transition moment. For past dones, stateHistory
-// entries already store the per-transition `startedAt` so we read it directly.
+// Why: use stateStartedAt (not updatedAt, which drifts on within-state pings) for the true done-transition time.
 function lastEnteredDoneAt(agent: DashboardAgentRowData): number | null {
-  // Why: idle subagent child rows are alive-but-idle (teammates persist
-  // between turns) — reading their synthetic entry as "done Xm ago" would
-  // mislabel a live teammate as finished.
+  // Why: idle subagents are alive-but-idle (persist between turns); don't label them as done.
   if (agent.rowSource === 'subagent' && agent.state === 'idle') {
     return null
   }
@@ -78,44 +70,15 @@ function stateDotTooltipLabel(agent: DashboardAgentRowData, dotState: AgentDotSt
 type Props = {
   agent: DashboardAgentRowData
   onDismiss: (paneKey: string) => void
-  /** Navigate directly to the tab this agent lives in. paneKey is passed
-   *  through so the caller can acknowledge (mark-visited) the specific row
-   *  that was clicked, without having to re-derive it from the tab id. */
+  /** Navigate to this agent's tab; paneKey lets the caller mark-visit the exact clicked row. */
   onActivate: (tabId: string, paneKey: string) => void
-  /**
-   * Why: the relative-time labels ("Xm ago") need a periodic re-render to stay
-   * honest. We accept `now` from a parent container so a single 30s tick owned
-   * by the container drives every visible row, rather than each row running
-   * its own setInterval. See useNow.ts for the shared hook — WorktreeCardAgents
-   * owns the tick for the inline-in-card list.
-   */
+  /** Why: injected from a parent so one shared tick re-renders every row's "Xm ago" (see useNow.ts), not a per-row interval. */
   now: number
-  /**
-   * Why: bold weight for the prompt rides on the enclosing workspace card's
-   * unvisited signal, not on the per-agent state. Passed in from
-   * WorktreeCardAgents so the workspace name and its agent rows share
-   * the same "you haven't looked at this yet" rule — visiting the worktree
-   * clears the signal, and the next render mutes both in lockstep.
-   *
-   * Optional so other callers can opt out and default to muted when their
-   * surface carries the unread signal elsewhere.
-   */
+  /** Why: bold prompt rides on the card's unvisited signal (shared with the workspace name), not per-agent state. */
   isUnvisited?: boolean
-  /**
-   * Why: the inline-in-card variant sits in a tighter layout next to the
-   * agent identity icon, so 'md' reads as a second ~12px glyph that users
-   * can confuse with the agent icon. 'sm' keeps them visually distinct.
-   * The full dashboard has more breathing room and prefers 'md' for leading-
-   * slot presence, so default stays 'md'.
-   */
+  /** Why: inline variant passes 'sm' so the dot isn't mistaken for the adjacent ~12px agent icon. */
   stateDotSize?: 'sm' | 'md'
-  /**
-   * Why: the inline-in-card variant lives next to a worktree card that the
-   * user clicks to jump directly to the agent — a separate expand chevron
-   * and a second identity glyph (Claude/Gemini/…) are redundant noise in
-   * that tighter layout. The full dashboard keeps both, so these flags
-   * default to showing them.
-   */
+  /** Why: inline-in-card variant drops the redundant chevron and identity glyph in its tighter layout. */
   hideIdentityIcon?: boolean
   hideExpand?: boolean
   /** Reuse the row's hover tint to show the focused terminal pane's agent. */
@@ -128,8 +91,7 @@ type Props = {
   reserveDisclosureGutter?: boolean
   // Why: chevron indentation replaces fixed-offset lineage connector art.
   hideLineageConnectors?: boolean
-  // Why: send-popover target mode temporarily turns sidebar rows into the
-  // picker surface, so row clicks must send/no-op instead of navigating.
+  // Why: send-popover target mode makes row clicks send/no-op instead of navigating.
   sendTargetStatus?: 'eligible' | 'disabled' | 'sending'
   sendTargetDisabledReason?: string
   onSendTargetClick?: (paneKey: string) => void
@@ -162,15 +124,11 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
   const handleToggleExpanded = useCallback(() => {
     setExpanded((prev) => !prev)
   }, [])
-  // Why: agent rows navigate directly to the agent's own tab, while the
-  // surrounding worktree card navigates to whatever tab the worktree last had
-  // focused. Stop propagation so the card click handler does not run second
-  // and override our tab activation.
+  // Why: stop propagation so the surrounding card's click handler can't override our tab activation.
   const handleActivate = useCallback(
     (e: React.MouseEvent) => {
       e.stopPropagation()
-      // Why: subagent child rows have no pane of their own; they focus the
-      // parent pane whose session spawned them.
+      // Why: subagent rows have no pane of their own, so focus the spawning parent's pane.
       onActivate(agent.tab.id, agent.activationPaneKey ?? agent.paneKey)
     },
     [onActivate, agent.tab.id, agent.activationPaneKey, agent.paneKey]
@@ -198,18 +156,9 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
   const startedAt = agent.startedAt > 0 ? agent.startedAt : null
   const doneAt = lastEnteredDoneAt(agent)
   const prompt = getAgentRowPrimaryText(agent.entry)
-  // Why: `agent.entry.prompt` is normalized to '' when the prompt is unknown
-  // (fresh agent, missing telemetry). Rendering the row with an empty primary
-  // slot would collapse the text column and leave the row with no human-
-  // readable label — just a state dot and icon. Fall back to the state label
-  // ("Working", "Done", "Waiting", …) so every row is identifiable at a
-  // glance.
+  // Why: prompt is '' when unknown, so fall back to the state label to keep the row labeled.
   const displayLabel = prompt || agentStateLabel(asDotState(agent.state))
-  // Why: the tool row describes what the agent is *currently* doing; once it
-  // leaves working, that line goes stale and misleads (a done row showing
-  // "Bash: pnpm test" reads as if the command is still running). Gate tool
-  // fields on `state === 'working'`. The assistant message is the opposite
-  // — it's the reply, most useful on `done`, so we always show it.
+  // Why: gate tool fields on 'working' — a stale tool line on a done row reads as still-running.
   const isWorking = agent.state === 'working'
   const toolName = isWorking ? (agent.entry.toolName?.trim() ?? '') : ''
   const toolInput = isWorking ? (agent.entry.toolInput?.trim() ?? '') : ''
@@ -225,17 +174,11 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
           lineageChildCount === 1 ? 'agent' : 'agents'
         }`
       : formatAgentTypeLabel(agent.agentType)
-  // Why: interrupted is a terminal outcome the user needs to scan in the
-  // leading state column; the secondary-line text below provides the
-  // explanation without competing with the prompt or timestamp.
+  // Why: interrupted is a terminal outcome, so surface it in the leading state dot.
   const dotState: AgentDotState = isInterrupted ? 'interrupted' : asDotState(agent.state)
   const dotTooltipLabel = stateDotTooltipLabel(agent, dotState)
 
-  // Why: always show the chevron to keep the row's right edge stable — a
-  // conditional control would appear/disappear as agent content grows and
-  // shrinks mid-turn, which reads as UI flicker. Expanding a row whose
-  // content already fits is a no-op; the cost of an occasionally inert
-  // toggle is much lower than layout jitter on every live row.
+  // Why: always show the chevron so the row's right edge doesn't flicker as content grows/shrinks.
 
   const startedTimeAgo = startedAt !== null ? formatTimeAgo(startedAt, now) : null
   const doneTimeAgo = doneAt !== null ? formatTimeAgo(doneAt, now) : null
@@ -251,24 +194,15 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
   const titleParts = sendTargetDisabledReason ? [sendTargetDisabledReason, ...tsParts] : tsParts
 
   return (
-    // Why: NOT role="button" / tabIndex={0}. The row contains real <button>
-    // children (dismiss X, expand chevron) and tooltip triggers that forward
-    // button semantics to their children — nesting them inside an outer
-    // role=button violates ARIA's "no interactive content inside interactive
-    // content" rule and breaks keyboard/AT navigation. Keyboard users reach
-    // the agent via the child buttons and the tab switcher; the outer <div>
-    // stays a plain clickable surface for pointer activation.
+    // Why: no role="button" — nested interactive children (buttons, tooltip triggers) would violate ARIA nesting rules.
     <div
       onClickCapture={handleSendTargetClickCapture}
       onClick={handleActivate}
       className={cn(
-        // Why: this row owns the timestamp/X hover boundary; anonymous
-        // ancestor groups from workspace cards must not reveal every row's X.
+        // Why: named group scopes the X-reveal to this row, not every row in the card.
         'group/agent-row relative flex flex-col -ml-2 py-1',
         isLineageChild ? 'pl-5 pr-2' : 'px-2',
-        // Why: inline agent rows sit inside a hoverable workspace card, so
-        // their hover wash must stay softer than the parent card highlight.
-        // The focused-pane state reuses the same class via data attribute.
+        // Why: hover wash stays softer than the enclosing card's highlight.
         'cursor-pointer rounded-sm worktree-agent-row-hover',
         hasChildDisclosure && 'worktree-agent-lineage-parent-row',
         isLineageChild && 'worktree-agent-lineage-child-row',
@@ -315,13 +249,7 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
           onToggleChildAgents={onToggleChildAgents}
           reserveDisclosureGutter={reserveDisclosureGutter}
         />
-        {/* Why: state indicator lives in the leading gutter so the user's
-            eye can sweep one column and know which rows are working,
-            waiting, or done at a glance — the list-view convention (Linear,
-            GitHub issues, JetBrains TODO). Replaces the earlier left accent
-            bar + right-side dot combo, which double-encoded state. Size md
-            gives the glyph enough presence for the leading slot without
-            overpowering the prompt text. */}
+        {/* Why: state dot sits in the leading gutter so the eye can scan one column for row state. */}
         <Tooltip>
           <TooltipTrigger asChild>
             <span
@@ -335,37 +263,13 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
             {dotTooltipLabel}
           </TooltipContent>
         </Tooltip>
-        {/* Why: identity (Claude/Codex/Gemini/…) sits inline with the prompt
-            so the reader gets "state → who → what they said" left-to-right
-            on the top row. The sub-rows (tool step, assistant response) are
-            about the same agent and do not need the icon repeated next to
-            them — keeping the icon only on the prompt row lets the sub-rows
-            indent under the prompt text cleanly. Subagent child rows carry
-            the child's NAME in agentType (not an iconable agent — it would
-            render the unknown "?" glyph), and nesting under the parent
-            already conveys identity. */}
+        {/* Why: subagent rows skip the icon — agentType holds a child name, not an iconable agent, so it would render the unknown "?" glyph. */}
         {!hideIdentityIcon && agent.rowSource !== 'subagent' && (
           <span className="inline-flex shrink-0" title={identityTitle}>
             <AgentIcon agent={agentTypeToIconAgent(agent.agentType)} size={14} />
           </span>
         )}
-        {/* Why: animate between a 1-line clipped height and the content's
-            natural height using Chromium's `interpolate-size: allow-keywords`
-            — this is the only way to transition a `height` property to/from
-            `auto` without measuring sizes in JS. Falls back to an instant
-            swap in engines that don't support it. The inner span keeps
-            overflow-hidden so the truncate→wrap class flip stays clipped
-            during the interpolation.
-
-            Weight tracks the workspace's unvisited signal (isUnvisited):
-            bold + full foreground for agents inside a workspace the user
-            hasn't looked at yet, normal + muted once they've visited. This
-            keeps the prompt row's weight in lockstep with the workspace
-            name above it — one attention axis, not two.
-
-            Rendered unconditionally with a state-label fallback so rows
-            without a prompt (fresh/unknown) still have a human-readable
-            primary label instead of an empty text column. */}
+        {/* Why: interpolate-size:allow-keywords is the only way to animate height to/from auto without measuring in JS; falls back to an instant swap where unsupported. */}
         <span
           className={cn(
             'block min-w-0 flex-1 overflow-hidden text-[11px] leading-snug',
@@ -379,10 +283,7 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
         >
           {displayLabel}
         </span>
-        {/* Why: "+N" badge mirrors the leading chevron — without it the
-            parent row reads identical to a leaf row when collapsed, and the
-            child count is invisible. Hidden when expanded because the
-            children are visible directly below. */}
+        {/* Why: "+N" badge shows the hidden child count when collapsed; redundant once children are expanded below. */}
         {hasChildDisclosure && !childAgentsExpanded && (
           <span
             className="shrink-0 text-[10px] font-normal leading-none text-muted-foreground/70 tabular-nums"
diff --git a/src/renderer/src/components/diff-comments/DiffCommentPopover.tsx b/src/renderer/src/components/diff-comments/DiffCommentPopover.tsx
index b85f75f965f..235c572216f 100644
--- a/src/renderer/src/components/diff-comments/DiffCommentPopover.tsx
+++ b/src/renderer/src/components/diff-comments/DiffCommentPopover.tsx
@@ -11,21 +11,14 @@ import { translate } from '@/i18n/i18n'
 import { installOpenDraftAddReviewNoteGuard } from '../editor/editor-shortcuts'
 import { resolveDiffCommentPopoverTop } from './diff-comment-popover-position'
 
-// Why: rendered as a DOM sibling overlay inside the editor container rather
-// than as a Monaco content widget because it owns a React textarea with
-// auto-resize behaviour. Positioning mirrors what useDiffCommentDecorator does
-// for the "+" button so scroll updates from the parent keep the popover
-// aligned with its anchor line.
+// Why: a DOM sibling overlay rather than a Monaco content widget, so it can own a React auto-resizing textarea.
 
 type Props = {
   lineNumber: number
   startLine?: number
   top: number
   left?: number
-  // Height of the anchor line, used to flip the popover above it when it would
-  // overflow the bottom of the viewport. Defaults to 0 for callers that don't
-  // anchor to a Monaco line (e.g. markdown annotations): the popover still
-  // clamps inside the viewport, it just doesn't offset by the line's height.
+  // Anchor line height, used to flip the popover above the line near the viewport bottom; 0 for non-Monaco callers.
   lineHeight?: number
   title?: string
   placeholder?: string
@@ -53,46 +46,22 @@ export function DiffCommentPopover({
   onSubmit
 }: Props): React.JSX.Element {
   const [body, setBody] = useState('')
-  // Why: mirror the draft into a ref so the document mousedown listener (empty
-  // dep array, see below) can read the freshest body without re-registering on
-  // every keystroke. Used to keep the popover open on outside-click when the
-  // user has typed something, so an accidental click never discards a draft.
+  // Why: mirror the draft into a ref so the mousedown listener reads it fresh without re-registering each keystroke.
   const bodyRef = useRef(body)
   bodyRef.current = body
-  // Why: `submitting` prevents duplicate note rows when the user
-  // double-clicks the Add note button or hits Enter twice before the
-  // IPC round-trip resolves. Iteration 1 made submission async and keeps the
-  // popover open on failure (to preserve the draft); that widened the window
-  // between the first click and `setPopover(null)` during which a second
-  // trigger would call `addDiffComment` again and produce a second row with a
-  // fresh id/createdAt. Tracked in React state (not a ref) so the button can
-  // reflect the in-flight status to the user.
+  // Why: block duplicate note rows from double-click/Enter during the async submit; state (not a ref) so the button shows in-flight.
   const [submitting, setSubmitting] = useState(false)
   const mountedRef = useMountedRef()
   const popoverRef = useRef<HTMLDivElement | null>(null)
-  // Why: stash onCancel in a ref so the document mousedown listener below can
-  // read the freshest callback without listing `onCancel` in its dependency
-  // array. Parents (DiffSectionItem, DiffViewer) pass a new arrow function on
-  // every render and the popover re-renders frequently (scroll tracking updates
-  // `top`, font zoom, etc.), which would otherwise tear down and re-attach the
-  // document listener on every parent render. Mirrors the pattern in
-  // useDiffCommentDecorator.tsx.
+  // Why: keep onCancel in a ref so the mousedown listener reads it fresh without re-attaching when parents pass a new callback each render.
   const onCancelRef = useRef(onCancel)
   onCancelRef.current = onCancel
-  // Why: stable id per-instance so multiple popovers (should they ever coexist)
-  // don't collide on aria-labelledby references. Screen readers announce the
-  // "Line N" label as the dialog's accessible name.
+  // Why: stable per-instance id so coexisting popovers don't collide on aria-labelledby references.
   const labelId = useId()
-  // Why: `top` anchors the popover just below the selected line. Near the
-  // bottom of the editor viewport that downward box gets clipped by the pane's
-  // overflow container, so the resolved top may flip the popover above the line
-  // (see resolveDiffCommentPopoverTop). Start at `top` so the first paint is
-  // correct when there is room below; the layout effect refines it otherwise.
+  // Why: seed at `top` for a correct first paint when there's room below; the layout effect flips it above the line if clipped.
   const [resolvedTop, setResolvedTop] = useState(top)
 
-  // Why: read the freshest anchor inside `measure` (a stable callback) so the
-  // ResizeObserver below can stay mounted once instead of tearing down on every
-  // scroll frame, which updates `top` continuously while the popover is open.
+  // Why: mirror `top` into a ref so the measure callback stays stable and the ResizeObserver isn't re-mounted each scroll frame.
   const topRef = useRef(top)
   topRef.current = top
   const lineHeightRef = useRef(lineHeight)
@@ -115,15 +84,12 @@ export function DiffCommentPopover({
     )
   }, [])
 
-  // Why: re-resolve placement before paint whenever the anchor moves (scroll,
-  // font zoom) so the flip/clamp tracks the selected line without flicker.
+  // Why: re-resolve placement before paint when the anchor moves (scroll, font zoom) so flip/clamp tracks without flicker.
   useLayoutEffect(() => {
     measureResolvedTop()
   }, [top, lineHeight, measureResolvedTop])
 
-  // Why: the textarea auto-grows as the user types and the editor pane can be
-  // resized; observe both so a growing draft re-resolves and never ends up
-  // clipped at the bottom edge.
+  // Why: observe textarea auto-grow and pane resize so a growing draft re-resolves and never clips at the bottom.
   useEffect(() => {
     const popover = popoverRef.current
     const container = popover?.parentElement
@@ -137,14 +103,11 @@ export function DiffCommentPopover({
   }, [measureResolvedTop])
 
   const focusTextareaRef = useCallback((textarea: HTMLTextAreaElement | null): void => {
-    // Why: the draft field should receive focus as soon as the popover mounts;
-    // no external system needs a post-render Effect for this.
+    // Why: focus on mount via the ref callback so no post-render Effect is needed.
     textarea?.focus()
   }, [])
 
-  // Why: product B — the composer autofocuses its textarea, so a second
-  // add-review-note chord must not remount the draft; consume it on the
-  // popover subtree (not window) so other panes/surfaces keep their chord.
+  // Why: consume the add-review-note chord on the popover subtree, not window, so a repeat chord doesn't remount the draft.
   useEffect(() => {
     const popover = popoverRef.current
     if (!popover) {
@@ -153,11 +116,7 @@ export function DiffCommentPopover({
     return installOpenDraftAddReviewNoteGuard(popover)
   }, [])
 
-  // Why: Monaco's editor area does not bubble a synthetic React click up to
-  // the popover's onClick. Without a document-level mousedown listener, the
-  // popover has no way to detect clicks outside its own bounds. We keep the
-  // `onMouseDown={ev.stopPropagation()}` on the popover root so that this
-  // listener sees outside-clicks only.
+  // Why: Monaco's editor doesn't bubble React clicks up, so detect outside-clicks with a document-level mousedown listener.
   useEffect(() => {
     const onDocumentMouseDown = (ev: MouseEvent): void => {
       if (!popoverRef.current) {
@@ -166,14 +125,11 @@ export function DiffCommentPopover({
       if (popoverRef.current.contains(ev.target as Node)) {
         return
       }
-      // Why: outside-click is a soft dismiss, so preserve any non-whitespace
-      // draft even when submit's bounded scanner would reject it as too large.
+      // Why: soft dismiss — keep any non-whitespace draft even when submit's bounded scanner would reject it as too large.
       if (hasDraftText(bodyRef.current)) {
         return
       }
-      // Why: read the latest onCancel from the ref rather than closing over it
-      // so the listener does not need to be re-registered on every parent
-      // render (see onCancelRef comment above).
+      // Why: read the latest onCancel from the ref so the listener isn't re-registered on every parent render (see onCancelRef above).
       onCancelRef.current()
     }
     document.addEventListener('mousedown', onDocumentMouseDown)
@@ -257,16 +213,7 @@ export function DiffCommentPopover({
               onCancel()
               return
             }
-            // Why: plain Enter submits so the note popover behaves like a
-            // single-field form. Shift+Enter inserts a newline (browser default)
-            // so multi-line notes are still possible. We also accept
-            // Cmd/Ctrl+Enter as a submit alias so users who learned the old
-            // shortcut aren't silently broken. IME composition (isComposing) is
-            // excluded because Enter during composition only confirms the
-            // conversion candidate — submitting then would send a half-typed
-            // note for CJK/IME users. We guard against a second Enter while an
-            // earlier submit is still awaiting IPC — otherwise it would enqueue
-            // a duplicate addDiffComment call.
+            // Why: Shift+Enter inserts a newline; skip isComposing so IME composition Enter doesn't submit a half-typed CJK note.
             if (e.key === 'Enter' && !e.nativeEvent.isComposing && !e.shiftKey) {
               e.preventDefault()
               if (submitting) {
diff --git a/src/renderer/src/components/diff-comments/useDiffCommentDecorator.tsx b/src/renderer/src/components/diff-comments/useDiffCommentDecorator.tsx
index 50c590ba402..addfcb4e329 100644
--- a/src/renderer/src/components/diff-comments/useDiffCommentDecorator.tsx
+++ b/src/renderer/src/components/diff-comments/useDiffCommentDecorator.tsx
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: this hook owns the Monaco view-zone
-lifecycle, inline React roots, range selection, and scroll-to-comment
-coordination so those invariants stay in one place. */
+/* eslint-disable max-lines -- Why: this hook owns Monaco view-zone lifecycle, inline React roots, range selection, and scroll coordination in one place. */
 import { useCallback, useEffect, useMemo, useRef } from 'react'
 import * as monaco from 'monaco-editor'
 import type { editor as monacoEditor, IDisposable } from 'monaco-editor'
@@ -17,13 +15,7 @@ import { installDiffCommentZoneMouseDownStopper } from './diff-comment-zone-mous
 import { NotesSendMenu, type NotesSendMenuScope } from '../editor/NotesSendMenu'
 import { translate } from '@/i18n/i18n'
 
-// Why: Monaco glyph-margin *decorations* don't expose click events in a way
-// that lets us show a polished popover anchored to a line. So instead we own a
-// single absolutely-positioned "+" button inside the editor DOM node, and we
-// move it to follow the mouse-hovered line. Clicking calls the consumer which
-// opens a React popover. This keeps all interactive UI as React/DOM rather
-// than Monaco decorations, and we get pixel-accurate positioning via Monaco's
-// getTopForLineNumber.
+// Monaco glyph decorations don't expose usable click events, so we own an absolutely-positioned "+" button that follows the hovered line.
 
 export type DecoratedDiffComment = DiffComment & {
   author?: string
@@ -36,8 +28,7 @@ export type DecoratedDiffComment = DiffComment & {
 
 type DecoratorArgs = {
   editor: monacoEditor.ICodeEditor | null
-  // Why: Monaco destroys model-scoped view zones when a retained editor swaps
-  // models, so the decorator must rebuild even though the editor object is stable.
+  // Monaco destroys model-scoped view zones on model swap, so rebuild even though the editor object is stable.
   monacoModelIdentity?: string
   filePath: string
   worktreeId: string
@@ -46,15 +37,10 @@ type DecoratorArgs = {
   addButtonLabel?: string
   onAddCommentClick: (args: { lineNumber: number; startLine?: number; top: number }) => void
   onDeleteComment: (commentId: string) => void
-  // Why: present only on surfaces that allow editing the saved note (local
-  // diffs persisted to WorktreeMeta). GitHub PR review surfaces don't pass
-  // this — their notes are remote and can't be edited via this slice.
+  // Present only on surfaces that allow editing (local diffs); PR review notes are remote and can't be edited here.
   onUpdateComment?: (commentId: string, body: string) => Promise<boolean>
   formatCommentPrompt?: (comment: DecoratedDiffComment) => string
-  // Why: pending-scroll request from the SourceControl sidebar. When this id
-  // matches a comment in this surface the decorator reveals that line in the
-  // editor and calls the ack callback so the same id can be requested again
-  // later without the surface seeing a stale value.
+  // Pending scroll-to-note id from the sidebar; decorator reveals the line and acks so the same id can be re-requested later.
   pendingScrollCommentId?: string | null
   onPendingScrollConsumed?: () => void
 }
@@ -62,26 +48,16 @@ type DecoratorArgs = {
 type ZoneEntry = {
   zoneId: string
   domNode: HTMLElement
-  // Why: hold the IViewZone delegate so `layoutZone` re-reads our updated
-  // heightInPx during inline edits. Monaco's _layoutZone calls
-  // _computeWhitespaceProps(zone.delegate), which reads delegate.heightInPx —
-  // mutating the delegate is the supported way to grow a zone in place.
+  // Hold the delegate so layoutZone re-reads our updated heightInPx — mutating the delegate is the supported way to resize a zone in place.
   delegate: monacoEditor.IViewZone
   root: Root
   disposeMouseDownStopper: () => void
   lastRenderSignature: string
-  // Why: Monaco invokes IViewZone.onDomNodeTop on every render once the zone
-  // is in the layout. The first invocation is our deterministic "this zone is
-  // now part of the editor's vertical layout" signal — equivalent in role to
-  // VS Code's commentsController._computeAndSetPromise resolving before
-  // revealCommentThread runs. We use it to gate scroll-to-note instead of
-  // polling getTopForLineNumber until the value changes.
+  // First onDomNodeTop = deterministic "zone laid out" signal; gates scroll-to-note instead of polling getTopForLineNumber.
   laidOut: boolean
 }
 
-// Why: card chrome (header/meta/border/padding) plus per-line body height. Used
-// in two places — the initial heightInPx estimate and the live resize during
-// inline edit — so keep them in lockstep.
+// Card chrome + per-line body height; used by the initial estimate and the live resize, so keep in lockstep.
 const ZONE_CHROME_PX = 68
 const ZONE_LINE_PX = 20
 const ZONE_MIN_PX = 88
@@ -140,32 +116,15 @@ export function useDiffCommentDecorator({
     worktreeId ? (s.activeGroupIdByWorktree[worktreeId] ?? worktreeId) : worktreeId
   )
   const hoverLineRef = useRef<number | null>(null)
-  // Why: one React root per view zone. Body updates re-render into the
-  // existing root, so Monaco's zone DOM stays in place and only the card
-  // contents update — matching the diff-based pass that replaced the previous
-  // hand-built DOM implementation.
+  // One React root per view zone: body updates re-render into it so Monaco's zone DOM stays put and only the card contents change.
   const zonesRef = useRef<Map<string, ZoneEntry>>(new Map())
   const disposablesRef = useRef<IDisposable[]>([])
-  // Why: holds the comment id the sidebar last asked us to scroll to. We
-  // resolve it in two places — when the zone is created and Monaco's
-  // onDomNodeTop fires, and when the request arrives after the zone is
-  // already laid out — and clear it both times via the resolver. Using a
-  // ref (instead of a state-driven effect that re-runs) means the request
-  // survives across the renders that happen while we wait for layout, and
-  // the resolver is the only place that produces the scroll + ack.
+  // Pending scroll-to-note comment id; a ref (not state) so the request survives renders while we wait for layout.
   const pendingScrollRef = useRef<string | null>(null)
-  // Why: the diff-zones effect builds a `scrollToZone(commentId)` closure
-  // that has access to `editor` and the live zones Map. The request-effect
-  // (further below) needs to invoke it when a request arrives after the
-  // zone is already laid out. Stashing the closure in a ref lets the
-  // request-effect call the latest version without restructuring the
-  // diff-zones effect into a hook-level helper.
+  // Stash the diff-zones effect's scrollToZone closure so the request-effect can invoke the latest version.
   const scrollToZoneRef = useRef<((commentId: string) => void) | null>(null)
   const scrollToZoneFrameRef = useRef<number | null>(null)
-  // Why: stash the consumer callbacks in refs so the decorator effect's
-  // cleanup does not run on every parent render. The parent passes inline
-  // arrow functions; without this, each render would tear down and re-attach
-  // the "+" button and all view zones, producing visible flicker.
+  // Stash callbacks in refs so the effect doesn't tear down + re-attach on every parent render (parent passes inline arrows) — avoids flicker.
   const onAddCommentClickRef = useRef(onAddCommentClick)
   const onDeleteCommentRef = useRef(onDeleteComment)
   const onUpdateCommentRef = useRef(onUpdateComment)
@@ -214,10 +173,7 @@ export function useDiffCommentDecorator({
       return typeof h === 'number' && h > 0 ? h : 19
     }
 
-    // Why: cache last-applied style values so positionAtLine skips redundant
-    // DOM writes during mousemove. Monaco's onMouseMove fires at high
-    // frequency, and every style assignment to an element currently under the
-    // cursor can retrigger hover state and cause flicker.
+    // Cache last-applied styles so positionAtLine skips redundant DOM writes on high-freq mousemove (restyling under the cursor flickers).
     let lastTop: number | null = null
     let lastDisplay: string | null = null
 
@@ -229,11 +185,7 @@ export function useDiffCommentDecorator({
       lastDisplay = value
     }
 
-    // Why: keep the button a fixed 18px square (height set in CSS) and
-    // vertically center it within the hovered line's box. Previously the
-    // height tracked the line height, producing a rectangle on editors with
-    // taller line-heights. Centering relative to lineHeight keeps the button
-    // sitting neatly on whatever line the cursor is on.
+    // Fixed 18px square centered in the line box — tracking line-height made a rectangle on taller line-heights.
     const BUTTON_SIZE = 18
     let rangeDecorationIds: string[] = []
     let dragState: { startLine: number; endLine: number } | null = null
@@ -349,12 +301,7 @@ export function useDiffCommentDecorator({
     plus.addEventListener('mousedown', handleMouseDown)
 
     const onMouseMove = editor.onMouseMove((e) => {
-      // Why: Monaco reports null position when the cursor is over overlay DOM
-      // that sits inside the editor — including our own "+" button. Hiding on
-      // null would create a flicker loop: cursor enters button → null → hide
-      // → cursor is now over line text → show → repeat. Keep the button
-      // visible at its last line while the cursor is on it. The onMouseLeave
-      // handler still hides it when the cursor leaves the editor entirely.
+      // Monaco reports null position over our "+" button; hiding on null would flicker-loop, so keep it visible while the cursor's on it.
       const srcEvent = e.event?.browserEvent as MouseEvent | undefined
       if (srcEvent && plus.contains(srcEvent.target as Node)) {
         return
@@ -368,10 +315,7 @@ export function useDiffCommentDecorator({
       hoverLineRef.current = ln
       positionAtLine(ln)
     })
-    // Why: only hide the button on mouse-leave; keep hoverLineRef so that a
-    // click which lands on the button (possible during the brief window after
-    // Monaco's content area reports leave but before the button element does)
-    // still resolves to the last-hovered line instead of silently dropping.
+    // Keep hoverLineRef on mouse-leave: Monaco's content-area leave fires before the button's, so a click in that gap still resolves to the last-hovered line.
     const onMouseLeave = editor.onMouseLeave(() => {
       setDisplay('none')
     })
@@ -393,23 +337,8 @@ export function useDiffCommentDecorator({
       clearRangeDecoration()
       plus.removeEventListener('mousedown', handleMouseDown)
       plus.remove()
-      // Why: when the editor is swapped or torn down, its view zones go with
-      // it. Unmount the React roots and clear tracking so a subsequent editor
-      // mount starts from a known-empty state rather than trying to remove
-      // stale zone ids from a dead editor. The diff effect below deliberately
-      // has no cleanup so comment-only changes don't cause a full zone
-      // rebuild; this cleanup is the single place we reset zone tracking.
-      //
-      // Why defer the unmount: this cleanup can run inside React's commit work
-      // loop (e.g. when an editor is disposed during a parent render and the
-      // dispose listener's setState triggers a re-render that re-runs this
-      // effect). A synchronous root.unmount() in that window produces React
-      // 19's "Attempted to synchronously unmount a root while React was
-      // already rendering" warning. queueMicrotask lands the unmount at the
-      // end of the current task, before any next render, with no visible
-      // delay. Clear `zones` synchronously so a subsequent editor mount sees
-      // empty bookkeeping immediately. This matches the deferred unmount in
-      // the diff-pass effect below.
+      // Editor swapped/torn down: unmount roots and clear tracking so the next mount starts known-empty.
+      // Defer unmount via queueMicrotask: a sync unmount during React's commit triggers React 19's "unmount while rendering" warning; clear zones synchronously.
       const rootsToUnmount = Array.from(zones.values(), (z) => {
         z.disposeMouseDownStopper()
         return z.root
@@ -422,8 +351,7 @@ export function useDiffCommentDecorator({
           }
         })
       }
-      // Why: editor went away — drop both the in-flight scroll request and
-      // the resolver closure (which captured the now-disposed editor).
+      // Editor gone: drop the in-flight scroll request and resolver closure (captured the now-disposed editor).
       cancelScrollToZoneFrame()
       pendingScrollRef.current = null
       scrollToZoneRef.current = null
@@ -439,20 +367,10 @@ export function useDiffCommentDecorator({
     const relevantMap = new Map(relevant.map((c) => [c.id, c] as const))
 
     const zones = zonesRef.current
-    // Why: unmounting a React root inside Monaco's changeViewZones callback
-    // triggers synchronous DOM mutations that Monaco isn't expecting mid-flush
-    // and can race with its zone bookkeeping. Collect roots to unmount, run
-    // the Monaco batch, then unmount afterwards.
+    // Unmounting a root inside changeViewZones races Monaco's zone bookkeeping; collect roots and unmount after the batch.
     const rootsToUnmount: Root[] = []
 
-    // Why: re-measure the zone DOM and tell Monaco to grow/shrink the zone
-    // so the inline editor can expand without clipping the next editor line.
-    // Called from the card whenever it toggles edit mode or the textarea
-    // grows. Monaco's `_layoutZone` re-reads `delegate.heightInPx`, so we
-    // mutate the delegate first, then trigger a re-layout. Bails out if the
-    // zone has been removed since enqueuing. Defined outside changeViewZones
-    // so a future caller cannot mistakenly reach into the outer accessor —
-    // resizeZone always opens its own changeViewZones batch.
+    // Re-measure/re-layout the zone: mutate delegate.heightInPx first (Monaco's _layoutZone re-reads it) so inline edit expands without clipping.
     const resizeZone = (commentId: string): void => {
       const entry = zones.get(commentId)
       if (!entry) {
@@ -462,9 +380,7 @@ export function useDiffCommentDecorator({
       const wrapperStyle = window.getComputedStyle(entry.domNode)
       const verticalPadding =
         Number.parseFloat(wrapperStyle.paddingTop) + Number.parseFloat(wrapperStyle.paddingBottom)
-      // Why: Monaco pins the view-zone node to the previous height, so its
-      // scrollHeight cannot shrink. Measure the rendered card and wrapper
-      // padding instead so cancel/save can collapse the zone after edit mode.
+      // Monaco pins the zone node to its previous height (scrollHeight can't shrink), so measure the rendered card+padding to allow collapse.
       const measured = Math.ceil(
         (child?.getBoundingClientRect().height ?? entry.domNode.scrollHeight) + verticalPadding
       )
@@ -480,21 +396,8 @@ export function useDiffCommentDecorator({
       })
     }
 
-    // Why: one-shot scroll resolver. Called by both the request-arrives-late
-    // path and the layout-settles-late path, so the math + ack live in one
-    // place. Reads `getTopForLineNumber(line, /* includeZones */ true)` so the
-    // viewport centers on the line+card pair (the card sits in a view zone
-    // above the line). VS Code's commentThreadZoneWidget._goToComment uses
-    // `false` because it then adds (commentCoords.top - threadCoords.top) to
-    // pick a specific comment within a multi-comment thread; our notes are
-    // single-comment threads and we want the card visible, so centering on
-    // the zones-aware offset is the correct equivalent.
-    //
-    // The rAF defer is intentional: DiffViewer.handleMount schedules
-    // `restoreViewState` via rAF on a fresh mount, and that runs in the same
-    // frame this resolver could fire from onDomNodeTop. Deferring one frame
-    // guarantees we run after restoreViewState, so its cached scroll doesn't
-    // snap the editor back from the requested note.
+    // One-shot scroll resolver: getTopForLineNumber(line, includeZones=true) centers on the line+card pair (card sits in a zone above the line).
+    // rAF defer is intentional: run after DiffViewer's restoreViewState rAF so its cached scroll doesn't snap us back off the note.
     const scrollToZone = (commentId: string): void => {
       cancelScrollToZoneFrame()
       scrollToZoneFrameRef.current = requestAnimationFrame(() => {
@@ -515,13 +418,10 @@ export function useDiffCommentDecorator({
     }
     scrollToZoneRef.current = scrollToZone
 
-    // Why: render helper used by BOTH the new-zone branch and the patch-
-    // existing-zone branch so the card's prop wiring stays in lockstep — any
-    // future prop is added once.
+    // Shared by the new-zone and patch branches so the card's prop wiring stays in lockstep.
     const renderCard = (root: Root, comment: DecoratedDiffComment): void => {
       root.render(
-        // Why: Monaco view zones are separate React roots outside the app root,
-        // so context providers from App.tsx do not reach tooltip-using actions.
+        // View zones are separate React roots outside the app root, so App.tsx context providers don't reach them.
         <TooltipProvider delayDuration={400}>
           <DiffCommentCard
             lineNumber={comment.lineNumber}
@@ -567,67 +467,43 @@ export function useDiffCommentDecorator({
     }
 
     editor.changeViewZones((accessor) => {
-      // Why: remove only the zones whose comments are gone. Rebuilding all
-      // zones on every change caused flicker and dropped focus/selection in
-      // adjacent UI; a diff-based pass keeps the untouched cards stable.
+      // Remove only zones whose comments are gone; rebuilding all caused flicker and dropped focus/selection.
       for (const [commentId, entry] of zones) {
         if (!relevantMap.has(commentId)) {
           accessor.removeZone(entry.zoneId)
           entry.disposeMouseDownStopper()
           rootsToUnmount.push(entry.root)
           zones.delete(commentId)
-          // Why: if the user requested a scroll-to-note on a comment that
-          // was just deleted, drop the request so a future zone with the
-          // same id (unlikely but possible) doesn't pick up a stale request.
+          // Comment deleted: drop any pending scroll request so a future zone reusing the id can't pick up a stale request.
           if (pendingScrollRef.current === commentId) {
             pendingScrollRef.current = null
           }
         }
       }
 
-      // Add zones for newly-added comments.
       for (const c of relevant) {
         if (zones.has(c.id)) {
           continue
         }
         const dom = document.createElement('div')
         dom.className = 'orca-diff-comment-inline'
-        // Why: swallow mousedown on the whole zone so the editor does not
-        // steal focus (or start a selection drag) when the user interacts
-        // with anything inside the card. Delete still fires because click is
-        // attached directly on the button.
+        // Swallow mousedown on the zone so the editor doesn't steal focus / start a selection drag; Delete still fires (click is on the button).
         const disposeMouseDownStopper = installDiffCommentZoneMouseDownStopper(dom)
 
         const root = createRoot(dom)
 
-        // Why: estimate height from line count so the zone is close to the
-        // right size on first paint. Monaco sets heightInPx authoritatively at
-        // insertion and does not re-measure the DOM node, so an underestimate
-        // lets the card bleed into the following editor line. The constant
-        // covers fixed chrome (inline wrapper padding ~10, card border 2, card
-        // padding 12, header+meta ~24, body margin 2) and the per-line factor
-        // matches the 13.5px/1.5 body line-height.
+        // Estimate height up front: Monaco fixes heightInPx at insertion and never re-measures, so an underestimate bleeds into the next line.
         const lineCount = getCommentBodyLayoutLineCount(c.body)
         const heightInPx = Math.max(ZONE_MIN_PX, ZONE_CHROME_PX + lineCount * ZONE_LINE_PX)
 
-        // Why: suppressMouseDown: false so clicks inside the zone (Delete
-        // button) reach our DOM listeners. With true, Monaco intercepts the
-        // mousedown and routes it to the editor, so the Delete button never
-        // fires. The delete/body mousedown listeners stopPropagation so the
-        // editor still doesn't steal focus on interaction.
+        // suppressMouseDown: false so clicks (Delete button) reach our DOM listeners; true would route mousedown to the editor.
         const commentId = c.id
         const delegate: monacoEditor.IViewZone = {
           afterLineNumber: c.lineNumber,
           heightInPx,
           domNode: dom,
           suppressMouseDown: false,
-          // Why: Monaco invokes onDomNodeTop on every render once the zone is
-          // part of the layout (see vscode viewZones.ts render()). The first
-          // call is our deterministic "this zone is now placed" signal. If a
-          // sidebar scroll-to-note request was waiting on this comment, we
-          // resolve it here. We also flip `laidOut` so the request-effect
-          // path can scroll synchronously when the request arrives after the
-          // zone is already laid out.
+          // First onDomNodeTop = deterministic "zone placed" signal: resolve any waiting scroll and flip laidOut.
           onDomNodeTop: () => {
             const entry = zones.get(commentId)
             if (!entry) {
@@ -653,8 +529,7 @@ export function useDiffCommentDecorator({
         renderCard(root, c)
       }
 
-      // Patch existing zones whose visible props changed in place — re-render
-      // the same root instead of removing/re-adding the zone.
+      // Patch existing zones in place — re-render the same root instead of removing/re-adding.
       for (const c of relevant) {
         const entry = zones.get(c.id)
         if (!entry) {
@@ -669,8 +544,7 @@ export function useDiffCommentDecorator({
       }
     })
 
-    // Why: deferred unmount so Monaco has finished its zone batch before we
-    // tear down the React trees that were inside those zones.
+    // Deferred unmount so Monaco finishes its zone batch before we tear down the React trees.
     if (rootsToUnmount.length > 0) {
       queueMicrotask(() => {
         for (const root of rootsToUnmount) {
@@ -678,11 +552,7 @@ export function useDiffCommentDecorator({
         }
       })
     }
-    // Why: intentionally no cleanup. React would run cleanup BEFORE the next
-    // effect body on every `comments` identity change, wiping all zones and
-    // forcing a full rebuild — exactly the flicker this diff-based pass is
-    // meant to avoid. Zone teardown lives in the editor-scoped effect above,
-    // which only fires when the editor itself is replaced/unmounted.
+    // Intentionally no cleanup: React would wipe all zones on every comments change (flicker). Teardown lives in the editor-scoped effect above.
   }, [
     activeGroupId,
     cancelScrollToZoneFrame,
@@ -695,20 +565,12 @@ export function useDiffCommentDecorator({
     comments
   ])
 
-  // Why: route a sidebar scroll-to-note request into the decorator. We mirror
-  // VS Code's commentsController.revealCommentThread (which awaits
-  // `_computeAndSetPromise` before scrolling) by splitting resolution between
-  // two places: this effect for requests that arrive after the zone is laid
-  // out, and the zone's `onDomNodeTop` callback for requests that arrive
-  // before. `pendingScrollRef` carries the id between them; whoever resolves
-  // first scrolls and clears the ref via `scrollToZoneRef.current(id)`.
+  // Scroll-to-note resolution splits across this effect (request after layout) and onDomNodeTop (before), via pendingScrollRef.
   useEffect(() => {
     if (!editor) {
       return
     }
-    // Why: a null request (parent cleared the global, or routed away from
-    // diff) must drop any in-flight pending id so a late onDomNodeTop on a
-    // previously-requested zone doesn't snap-scroll the user.
+    // Null request: drop any in-flight pending id so a late onDomNodeTop doesn't snap-scroll the user.
     if (!pendingScrollCommentId) {
       cancelScrollToZoneFrame()
       pendingScrollRef.current = null
@@ -719,10 +581,7 @@ export function useDiffCommentDecorator({
         c.id === pendingScrollCommentId && c.filePath === filePath && c.worktreeId === worktreeId
     )
     if (!target) {
-      // Why: the request is for a comment this decorator doesn't own (different
-      // file/worktree). Drop any prior pending id so a late onDomNodeTop on a
-      // previously-requested zone in this decorator can't fire scrollToZone and
-      // ack — which would clear the global request meant for the owning surface.
+      // Not our comment; drop prior pending id so a late onDomNodeTop can't ack another surface's request.
       cancelScrollToZoneFrame()
       pendingScrollRef.current = null
       return
@@ -732,8 +591,7 @@ export function useDiffCommentDecorator({
     if (entry?.laidOut) {
       scrollToZoneRef.current?.(pendingScrollCommentId)
     }
-    // If !laidOut we wait — onDomNodeTop on the zone will pick the request
-    // up and call scrollToZone once Monaco's render pass places the zone.
+    // If !laidOut, onDomNodeTop picks up the request once Monaco places the zone.
   }, [
     cancelScrollToZoneFrame,
     editor,
diff --git a/src/renderer/src/components/editor/CombinedDiffViewer.tsx b/src/renderer/src/components/editor/CombinedDiffViewer.tsx
index 7622980a231..f75e7025997 100644
--- a/src/renderer/src/components/editor/CombinedDiffViewer.tsx
+++ b/src/renderer/src/components/editor/CombinedDiffViewer.tsx
@@ -1,8 +1,4 @@
-/* eslint-disable max-lines -- Why: combined diff behavior depends on one
-component-level state machine that coordinates lazy loading, inline editing,
-restore-on-remount caching, and scroll preservation. Splitting those pieces
-across smaller files would make the lifecycle edges harder to reason about and
-more error-prone than keeping the whole viewer flow together. */
+/* eslint-disable max-lines -- Why: the whole viewer is one state machine (lazy load, inline edit, restore-on-remount cache, scroll preservation); splitting it hides lifecycle edges. */
 /* oxlint-disable react-doctor/no-adjust-state-on-prop-change -- Why: diff entry changes must reset virtualizer measurement and generation state in lockstep with external scroll restoration. */
 import React, { useState, useEffect, useCallback, useRef, useLayoutEffect, useMemo } from 'react'
 import { elementScroll, useVirtualizer } from '@tanstack/react-virtual'
@@ -151,8 +147,7 @@ if (typeof window !== 'undefined') {
   window.addEventListener(ORCA_EDITOR_EXTERNAL_FILE_CHANGE_EVENT, (event) => {
     const detail = (event as CustomEvent<EditorPathMutationTarget>).detail
     if (detail?.relativePath) {
-      // Why: inactive combined-diff tabs are unmounted, so only a module-level
-      // cache bust can prevent a remount from replaying stale section bodies.
+      // Why: inactive combined-diff tabs are unmounted, so only a module-level cache bust stops a remount replaying stale bodies.
       invalidateCombinedDiffCachesForRelativePath(detail.relativePath)
     }
   })
@@ -164,8 +159,7 @@ const EMPTY_GIT_BRANCH_ENTRIES: GitBranchChangeEntry[] = []
 let combinedDiffCollapsedPreference: boolean | null = null
 let combinedDiffSideBySidePreference: boolean | null = null
 let combinedDiffFileTreeCollapsedPreference: boolean | null = null
-// Why: local Electron IPC has no RPC timeout; a hung git diff should turn into
-// a retryable row error instead of leaving the editor in "Loading..." forever.
+// Why: local Electron IPC has no RPC timeout; a hung git diff must become a retryable row error, not permanent "Loading...".
 const COMBINED_DIFF_SECTION_LOAD_TIMEOUT_MS = 30_000
 
 class CombinedDiffSectionLoadTimeoutError extends Error {
@@ -207,8 +201,7 @@ function getInitialCombinedDiffSideBySide(diffDefaultView: string | undefined):
 function getInitialCombinedDiffFileTreeCollapsed(
   combinedDiffFileTreeVisibleByDefault: boolean | undefined
 ): boolean {
-  // Why: the tree is opt-in for new sessions; only an explicit saved setting
-  // should make it the opening surface while settings are still loading.
+  // Why: the tree is opt-in; only an explicit saved setting should open it while settings are still loading.
   return combinedDiffFileTreeCollapsedPreference ?? combinedDiffFileTreeVisibleByDefault !== true
 }
 
@@ -265,25 +258,19 @@ export default function CombinedDiffViewer({
   const [isClearingNotes, setIsClearingNotes] = useState(false)
   const clearNotesDialogVisible = clearNotesDialogOpen && (diffCommentCount > 0 || isClearingNotes)
   if (clearNotesDialogOpen && !clearNotesDialogVisible) {
-    // Why: notes may be cleared outside this dialog; keep the modal closed in
-    // the same render instead of showing an empty confirmation for one frame.
+    // Why: notes may be cleared outside this dialog; close it this render instead of flashing an empty confirmation.
     setClearNotesDialogOpen(false)
   }
   const [notesCopied, setNotesCopied] = useState(false)
   const mountedRef = useRef(true)
-  // Why: copy feedback is created by the copy action, so the same handler owns
-  // its reset timer instead of repairing copied state after render.
+  // Why: the copy action owns its reset timer instead of repairing copied state after render.
   const notesCopiedResetTimerRef = useRef<number | null>(null)
-  // Why: clipboard IPC can resolve after the combined diff unmounts; skip
-  // copied feedback instead of starting a reset timer on a stale viewer.
+  // Why: clipboard IPC can resolve after unmount; skip copied feedback rather than start a reset timer on a stale viewer.
   const notesCopyMountedRef = useRef(false)
   const [fileTreeCollapsed, setFileTreeCollapsedState] = useState(() =>
     getInitialCombinedDiffFileTreeCollapsed(settings?.combinedDiffFileTreeVisibleByDefault)
   )
-  // Why: `generation` is a state counter used as a React key to force remounting
-  // DiffSectionItem components when the entry list changes. A separate ref
-  // (`generationRef`) is kept in sync for stale-async-result detection inside
-  // `loadSection`, where reading state would capture a stale closure value.
+  // Why: generation (state) keys DiffSectionItem remounts; generationRef mirrors it so loadSection's stale-async check avoids a stale closure.
   const [generation, setGeneration] = useState(0)
   const scrollContainerRef = useRef<HTMLDivElement>(null)
   const [scrollThumb, setScrollThumb] = useState<CombinedDiffScrollThumb>({
@@ -300,8 +287,7 @@ export default function CombinedDiffViewer({
   )
   const directScrollInputUntilRef = useRef(0)
   const [programmaticScrollMarks] = useState(createProgrammaticScrollMarks)
-  // Why: a scroll event pinned at a shrunken max is a browser clamp, not user
-  // input; bumping this asks the anchor restore to re-pin the viewport.
+  // Why: a scroll pinned at a shrunken max is a browser clamp, not user input; bump to ask the anchor restore to re-pin.
   const [clampRestoreCount, setClampRestoreCount] = useState(0)
   const lastScrollHeightRef = useRef(0)
   const activeScrollbarDragCleanupRef = useRef<CombinedDiffScrollbarDragCleanup | null>(null)
@@ -364,8 +350,7 @@ export default function CombinedDiffViewer({
       scrollContainerRef.current = node
       notesCopyMountedRef.current = node !== null
       if (node === null) {
-        // Why: copied feedback is tied to the combined-diff surface lifetime;
-        // the root ref unmount is the same boundary that disables stale feedback.
+        // Why: copied feedback is tied to the surface lifetime; the root-ref unmount is where stale feedback gets disabled.
         clearNotesCopiedResetTimer()
         cleanupActiveScrollbarDrag()
         return
@@ -389,9 +374,7 @@ export default function CombinedDiffViewer({
   )
   sectionsRef.current = sections
 
-  // Why: Settings should seed combined diffs until the user picks a toolbar
-  // mode in this session. After that, commit-to-commit navigation follows the
-  // last toolbar choice instead of snapping back to the global default.
+  // Why: seed from Settings until the user picks a toolbar mode this session, then follow that choice over the global default.
   useEffect(() => {
     if (settings?.diffDefaultView !== undefined && combinedDiffSideBySidePreference === null) {
       setSideBySide(settings.diffDefaultView === 'side-by-side')
@@ -421,12 +404,7 @@ export default function CombinedDiffViewer({
       : null
   const commitCompare = file.commitCompare?.commitOid ? file.commitCompare : null
 
-  // Why: prefer the snapshot taken at tab-open time so a commit that changes
-  // gitStatusByWorktree does not rebuild all sections and lose loaded content.
-  // The snapshot is already area-filtered by openAllDiffs; conflict filtering
-  // is applied here via snapshotEntries. The live path (getCombinedUncommittedEntries)
-  // adds its own area + conflict filtering as a fallback for tabs opened before
-  // the snapshot field existed.
+  // Why: prefer the tab-open snapshot so a commit changing gitStatusByWorktree doesn't rebuild sections and lose loaded content.
   const snapshotEntries = React.useMemo(
     () => file.uncommittedEntriesSnapshot?.filter((e) => e.conflictStatus !== 'unresolved'),
     [file.uncommittedEntriesSnapshot]
@@ -435,8 +413,7 @@ export default function CombinedDiffViewer({
     if (!snapshotEntries) {
       return getCombinedUncommittedEntries(gitStatusEntries, file.combinedAreaFilter)
     }
-    // Why: row load state changes must not rebuild the snapshot entry list;
-    // the ref is only consulted when live Git status changes.
+    // Why: row load-state changes must not rebuild the snapshot list; the ref is consulted only when live Git status changes.
     return resolveCombinedUncommittedSnapshotEntries(
       snapshotEntries,
       gitStatusEntries,
@@ -521,10 +498,7 @@ export default function CombinedDiffViewer({
     ]
   )
 
-  // Why: switching tabs or worktrees unmounts this viewer through the shared
-  // editor surface above it. Cache the rendered combined-diff state by the
-  // visible pane key so remounting can restore loaded sections and scroll
-  // position before the remounted surface paints at the top.
+  // Why: tab/worktree switches unmount this viewer; cache by pane key so remount restores sections+scroll before repaint.
   useLayoutEffect(() => {
     const cached = combinedDiffViewStateCache.get(viewStateKey)
     const canRestoreSnapshotSectionsByKey =
@@ -751,9 +725,7 @@ export default function CombinedDiffViewer({
   loadSectionRef.current = loadSectionNow
 
   useEffect(() => {
-    // Why: React StrictMode replays effect cleanup during development. Resetting
-    // here revives the scheduler for the replayed mount instead of leaving all
-    // later visibility requests ignored.
+    // Why: React StrictMode replays effect cleanup in dev; reset revives the scheduler for the replayed mount.
     const scheduler = loadSchedulerRef.current
     scheduler.reset()
     return () => scheduler.dispose()
@@ -768,9 +740,7 @@ export default function CombinedDiffViewer({
   }, [])
 
   useEffect(() => {
-    // Why: VS Code's multi-diff resolves an initial resource model before
-    // virtualizing editors. Queue the first rows deterministically so the
-    // visible viewport is not dependent on IntersectionObserver delivery.
+    // Why: queue the first rows deterministically so the visible viewport doesn't depend on IntersectionObserver delivery.
     const currentSections = sectionsRef.current
     for (let index = 0; index < currentSections.length; index += 1) {
       if (currentSections[index]?.loading && loadedIndicesRef.current.has(index)) {
@@ -855,13 +825,10 @@ export default function CombinedDiffViewer({
     },
     overscan: COMBINED_DIFF_OVERSCAN,
     initialOffset: () => scrollOffsetRef.current,
-    // Why: every scroll the virtualizer issues (scrollToIndex, measurement
-    // corrections) must be marked so scroll events can be attributed to the
-    // user only when this code didn't cause them.
+    // Why: mark every virtualizer-issued scroll so events are attributed to the user only when this code didn't cause them.
     scrollToFn: (offset, options, instance) => {
       const target = offset + (options.adjustments ?? 0)
-      // Why: a write to the current position emits no scroll event; marking
-      // it would leave a stale mark that can claim a later user scroll.
+      // Why: writing the current position emits no scroll event; a mark here would go stale and claim a later user scroll.
       if (instance.scrollElement?.scrollTop !== target) {
         programmaticScrollMarks.mark(target)
       }
@@ -958,11 +925,7 @@ export default function CombinedDiffViewer({
     [recordCombinedDiffDomScrollAnchor, writeCombinedDiffScrollAnchor]
   )
 
-  // Why: restore only on structural changes (rows added/removed/collapsed,
-  // remount, layout-mode flips, clamp recovery). Measurement churn during
-  // scrolling is compensated by the virtualizer itself; restoring on it wrote
-  // scrollTop against active wheel input whenever main-thread jank outlived
-  // the direct-input window.
+  // Why: restore only on structural changes — restoring on measurement churn overwrote scrollTop during active wheel input.
   const combinedDiffRestoreSignal = useMemo(
     () =>
       `${generation}|${sideBySide ? 'sbs' : 'inline'}|${clampRestoreCount}|${sections
@@ -990,9 +953,7 @@ export default function CombinedDiffViewer({
   })
 
   useLayoutEffect(() => {
-    // Why: inline vs side-by-side can change Monaco content heights across
-    // every loaded row. Re-measure on this explicit mode change, not on every
-    // section load.
+    // Why: inline vs side-by-side changes Monaco row heights; re-measure on the mode flip, not on every section load.
     virtualizer.measure()
   }, [sideBySide, virtualizer])
 
@@ -1023,8 +984,7 @@ export default function CombinedDiffViewer({
   const activeTreeSectionKey =
     activeTreeSectionState.entrySignature === entrySignature ? activeTreeSectionState.key : null
   if (activeTreeSectionState.entrySignature !== entrySignature) {
-    // Why: the tree highlight belongs to one diff entry set and must not flash
-    // on another entry set before an Effect reset would run.
+    // Why: the tree highlight belongs to one entry set; reset now so it can't flash on another before an Effect would.
     setActiveTreeSectionState({ entrySignature, key: null })
   }
   const viewedSectionKeys = React.useMemo(
@@ -1044,8 +1004,7 @@ export default function CombinedDiffViewer({
           scrollAnchorRef.current = null
           latestDomScrollAnchorRef.current = null
           virtualizer.scrollToIndex(index, { align: 'start' })
-          // Why: this jump is marked programmatic, so no scroll event records
-          // an anchor for it; snapshot the destination once layout settles.
+          // Why: this jump is programmatic (no scroll event records an anchor); snapshot the destination once layout settles.
           window.requestAnimationFrame(() => {
             scrollContainerRef.current?.dispatchEvent(
               new Event(VIRTUALIZED_SCROLL_ANCHOR_RECORD_EVENT)
@@ -1054,9 +1013,7 @@ export default function CombinedDiffViewer({
         }
       })
       if (navigatedIndex !== null) {
-        // Why: tree navigation is also the user's explicit "show me this diff"
-        // affordance. Re-selecting an already-loaded row must refetch in case
-        // the file or git index changed while the section stayed mounted.
+        // Why: re-selecting an already-loaded row must refetch — the file or git index may have changed while it stayed mounted.
         requestCombinedDiffSectionReload(navigatedIndex)
         setActiveTreeSectionState({
           entrySignature,
@@ -1341,8 +1298,7 @@ export default function CombinedDiffViewer({
       anchorIdleTimerId = window.setTimeout(() => {
         anchorIdleTimerId = null
         if (hasDirectScrollInput()) {
-          // Why: the first idle timer can fire while wheel input is still
-          // active and TanStack may be showing a transitional virtual window.
+          // Why: the idle timer can fire mid-wheel while TanStack still shows a transitional virtual window.
           scheduleSettledAnchorPersist()
           return
         }
@@ -1398,18 +1354,12 @@ export default function CombinedDiffViewer({
         return
       }
       if (shrank && scrollTop >= maxScrollTop - 1 && scrollOffsetRef.current > maxScrollTop + 1) {
-        // Why: pinned at a max that just shrank, coming from an offset the new
-        // range can't reach, is the browser clamping the viewport, not user
-        // input (a user scroll to the bottom starts from an in-range offset);
-        // ask the anchor restore to re-pin instead of recording the clamped
-        // position as intentional.
+        // Why: pinned at a just-shrunk max from an unreachable offset is a browser clamp, not user input — re-pin, don't record it.
         setClampRestoreCount((count) => count + 1)
         updateCombinedDiffScrollbar()
         return
       }
-      // Why: any unmarked scroll is the user's (wheel, momentum, keyboard,
-      // scrollbar drag) — including events whose input never reached the
-      // wheel handler because the main thread was janked past its window.
+      // Why: any unmarked scroll is the user's — even events delayed past their window by main-thread jank.
       recordCombinedDiffVirtualScrollAnchor(scrollTop)
       updateCachedScrollPosition({
         recordDomAnchor: false,
@@ -1419,10 +1369,7 @@ export default function CombinedDiffViewer({
       })
     }
 
-    // Why: React swaps the active editor DOM during tab changes. This listener
-    // must detach in the layout phase so the outgoing tab snapshots its last
-    // real scroll position before the soon-to-be-removed container emits a
-    // reset-to-top scroll event during teardown.
+    // Why: detach in the layout phase so the outgoing tab snapshots its real scroll before teardown fires a reset-to-top scroll.
     updateCombinedDiffScrollbar()
     const resizeObserver = new ResizeObserver(updateCombinedDiffScrollbar)
     resizeObserver.observe(container)
@@ -1586,8 +1533,7 @@ export default function CombinedDiffViewer({
         notesCopiedResetTimerRef.current = null
       }, 1500)
     } catch {
-      // Why: clipboard writes can fail while the app is not focused; this
-      // mirrors the sidebar notes action and keeps the popover non-blocking.
+      // Why: clipboard writes can fail while the app is unfocused; keep the popover non-blocking.
     }
   }, [clearNotesCopiedResetTimer, diffCommentCount, diffCommentsPrompt])
 
@@ -1944,9 +1890,7 @@ export default function CombinedDiffViewer({
                       data-combined-diff-section-key={section.key}
                       ref={virtualizer.measureElement}
                       className="absolute left-0 top-0 w-full"
-                      // Why: `top` preserves sticky file headers inside each row;
-                      // transform-based virtualization creates a containing block
-                      // that makes long-section headers feel jumpy while scrolling.
+                      // Why: position via top, not transform, so sticky file headers don't jump (transform creates a containing block).
                       style={{ top: `${virtualItem.start}px` }}
                     >
                       <DiffSectionItem
diff --git a/src/renderer/src/components/editor/DiffViewer.tsx b/src/renderer/src/components/editor/DiffViewer.tsx
index 079f03277a4..8bf174afb21 100644
--- a/src/renderer/src/components/editor/DiffViewer.tsx
+++ b/src/renderer/src/components/editor/DiffViewer.tsx
@@ -55,9 +55,7 @@ export default function DiffViewer({
   const updateDiffComment = useAppStore((s) => s.updateDiffComment)
   const scrollToDiffCommentId = useAppStore((s) => s.scrollToDiffCommentId)
   const setScrollToDiffCommentId = useAppStore((s) => s.setScrollToDiffCommentId)
-  // Why: subscribe to the raw comments array on the worktree so selector
-  // identity only changes when diffComments actually changes on this worktree.
-  // Filtering by relativePath happens in a memo below.
+  // Why: subscribe to the raw array so selector identity only changes when this worktree's comments change; filtering happens below.
   const allDiffComments = useAppStore((s): DiffComment[] | undefined =>
     selectWorktreeDiffComments(s, worktreeId)
   )
@@ -90,9 +88,7 @@ export default function DiffViewer({
   )
   const hasLineCommentAction = Boolean(worktreeId || onAddLineComment)
 
-  // Why: only forward the pending scroll id when this viewer owns the matching
-  // comment (worktree+path). Otherwise unrelated viewers would also try to
-  // scroll and ack the request first, racing the intended viewer.
+  // Why: only forward the pending scroll id when this viewer owns the comment, else unrelated viewers race to ack it.
   const pendingScrollForThisViewer = useMemo(() => {
     if (!worktreeId || !scrollToDiffCommentId) {
       return null
@@ -100,9 +96,7 @@ export default function DiffViewer({
     return diffComments.some((c) => c.id === scrollToDiffCommentId) ? scrollToDiffCommentId : null
   }, [scrollToDiffCommentId, diffComments, worktreeId])
 
-  // Why: gate the decorator on having a comment target. Local diffs persist
-  // notes to worktree metadata; GitHub PR diffs post line comments remotely.
-  // updateDiffComment is only wired for local diffs (worktreeId present).
+  // Why: gate the decorator on a comment target; updateDiffComment is only wired for local diffs (worktreeId present).
   useDiffCommentDecorator({
     editor: hasLineCommentAction ? modifiedEditor : null,
     monacoModelIdentity: modifiedModelKey ?? modelKey,
@@ -155,29 +149,17 @@ export default function DiffViewer({
       contentSub.dispose()
       layoutSub.dispose()
     }
-    // Why: depend on popover.lineNumber (not the whole popover object) so the
-    // effect doesn't re-subscribe on every top update it dispatches.
+    // Why: depend on popover.lineNumber (not the whole object) so the effect doesn't re-subscribe on every top update.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [modifiedEditor, popover?.lineNumber])
 
-  // Why: on a fresh open (no cached view state, no pending scroll-to-note),
-  // center the first diff change in the viewport. We do this from a dedicated
-  // effect — not from handleMount — so it sequences AFTER the comment
-  // decorator inserts its view zones. If we scrolled during handleMount, late
-  // zone insertion would shift content downward and the user would land on a
-  // note further down the file instead of the first change.
-  //
-  // `getTopForLineNumber(line, /* includeViewZones */ true)` accounts for any
-  // zones already in the layout, so the math survives whatever the decorator
-  // added in this render pass. The didScroll guard makes this strictly
-  // one-shot per mount.
+  // Why: center the first diff from a dedicated effect (not handleMount) so it runs after the decorator's view zones, which would otherwise shift content downward.
   const didAutoScrollFirstDiffRef = useRef(false)
   const didAutoScrollModelKeyRef = useRef(modelKey)
   useEffect(() => {
     if (didAutoScrollModelKeyRef.current !== modelKey) {
       didAutoScrollModelKeyRef.current = modelKey
-      // Why: the one-shot above is intentionally per-modelKey. Reset inside
-      // this Effect before its first-diff guard runs for the new file.
+      // Why: reset the per-modelKey one-shot here before the first-diff guard runs for the new file.
       didAutoScrollFirstDiffRef.current = false
     }
     const diffEditor = diffEditorRef.current
@@ -191,11 +173,7 @@ export default function DiffViewer({
       return
     }
     if (pendingScrollForThisViewer) {
-      // Why: the decorator owns this scroll for this mount, so permanently
-      // yield by setting the one-shot flag. Otherwise, when the decorator
-      // ack's and `pendingScrollForThisViewer` flips back to null, this
-      // effect would re-run with empty cache + un-set flag and overwrite
-      // the comment scroll with a jump to the first diff.
+      // Why: decorator owns this scroll, so set the one-shot flag; else we'd re-run and overwrite it when pendingScroll flips back to null.
       didAutoScrollFirstDiffRef.current = true
       return
     }
@@ -209,9 +187,7 @@ export default function DiffViewer({
         return
       }
       const line = Math.max(1, changes[0].modifiedStartLineNumber)
-      // Defer one frame so any view zones added in this render pass are part
-      // of the layout before we measure. Cancel any earlier pending rAF so
-      // a late onDidUpdateDiff can't enqueue a redundant scroll.
+      // Defer one frame so view zones are laid out before measuring; cancel any earlier rAF to avoid a redundant scroll.
       if (rafId !== null) {
         cancelAnimationFrame(rafId)
       }
@@ -227,8 +203,7 @@ export default function DiffViewer({
         didAutoScrollFirstDiffRef.current = true
       })
     }
-    // If the diff result is already available, run immediately; otherwise
-    // wait for it. onDidUpdateDiff fires once the diff computation lands.
+    // Run now if the diff is ready; otherwise onDidUpdateDiff fires once the computation lands.
     if (diffEditor.getLineChanges()) {
       run()
     }
@@ -242,12 +217,10 @@ export default function DiffViewer({
   }, [modifiedEditor, modelKey, pendingScrollForThisViewer])
 
   const handleEnterLargeDiffFallback = useCallback(() => {
-    // Why: when a tab transitions to the safety fallback, stale Monaco refs
-    // must not keep comment decorators or save handlers talking to disposed UI.
+    // Why: on fallback transition, drop stale Monaco refs so decorators/save handlers don't talk to disposed UI.
     lineNumberOptionsSubRef.current?.dispose()
     lineNumberOptionsSubRef.current = null
-    // Why: capture before nulling so we unregister the exact instance the
-    // navigator may still hold (identity guard no-ops a stale dispose).
+    // Why: capture before nulling so we unregister the exact instance (identity guard no-ops a stale dispose).
     const fallenBackEditor = diffEditorRef.current
     diffEditorRef.current = null
     if (fallenBackEditor) {
@@ -275,9 +248,7 @@ export default function DiffViewer({
     if (!worktreeId) {
       return
     }
-    // Why: await persistence before closing — if addDiffComment resolves null
-    // (store rolled back after IPC failure), keep the popover open so the user
-    // can retry instead of silently losing their draft.
+    // Why: await persistence — a null result (failed save) keeps the popover open for retry instead of losing the draft.
     const result = await addDiffComment({
       worktreeId,
       filePath: relativePath,
@@ -328,17 +299,12 @@ export default function DiffViewer({
       setupCopy(modifiedEditor, monaco, filePath, propsRef)
       setModifiedEditor(modifiedEditor)
 
-      // Why: restoring the full diff view state matches VS Code more closely
-      // than replaying scrollTop alone, and avoids divergent cursor/selection
-      // state between the original and modified panes.
+      // Why: restore full diff view state (not just scrollTop) so cursor/selection stay consistent across both panes.
       const savedViewState = diffViewStateCache.get(modelKey)
       if (savedViewState) {
         requestAnimationFrame(() => diffEditor.restoreViewState(savedViewState))
       }
-      // Auto-scroll to first diff is handled in a separate useEffect below so
-      // it can sequence after the comment-decorator inserts its view zones —
-      // otherwise late zones shift content downward and the user lands away
-      // from the first change (e.g. on a note further down the file).
+      // Auto-scroll to first diff lives in a separate effect below so it sequences after the decorator's view zones land.
 
       if (editable) {
         const cleanupSaveShortcut = installEditorSaveShortcut(
@@ -355,8 +321,7 @@ export default function DiffViewer({
           onContentChangeRef.current?.(modifiedEditor.getValue())
         })
         modifiedEditor.onDidDispose(() => {
-          // Why: editable diff views own both panes' shortcut bridges and the
-          // model subscription for the lifetime of this Monaco diff instance.
+          // Why: this diff instance owns both panes' shortcut bridges + the model sub, so dispose them with it.
           cleanupSaveShortcut()
           cleanupOriginalFindShortcut()
           cleanupModifiedFindShortcut()
@@ -368,8 +333,7 @@ export default function DiffViewer({
         diffEditor.focus()
       }
 
-      // Why: clear modifiedEditor on dispose so decorator effects (scroll-to-note,
-      // popover position) don't invoke methods on a disposed Monaco editor.
+      // Why: clear modifiedEditor on dispose so decorator effects don't call into a disposed Monaco editor.
       diffEditor.onDidDispose(() => {
         lineNumberOptionsSubRef.current?.dispose()
         lineNumberOptionsSubRef.current = null
@@ -382,9 +346,7 @@ export default function DiffViewer({
     [editable, setupCopy, modelKey, filePath, sideBySide, registerDiffEditor, unregisterDiffEditor]
   )
 
-  // Why: VS Code snapshots diff view state on deactivation, not on scroll events.
-  // The useLayoutEffect cleanup fires synchronously before React unmounts the
-  // component on tab switch, which is Orca's equivalent of VS Code's clearInput().
+  // Why: snapshot view state on deactivation (layoutEffect cleanup fires before unmount), not on scroll.
   useLayoutEffect(() => {
     return () => {
       const de = diffEditorRef.current
@@ -447,13 +409,8 @@ export default function DiffViewer({
             modified={modifiedContent}
             theme={isDark ? 'vs-dark' : 'vs'}
             onMount={handleMount}
-            // Why: A single file can have multiple live diff tabs at once
-            // (staged, unstaged, branch compare versions). The kept Monaco models
-            // must therefore key off the tab identity, not the raw file path, or
-            // one diff tab can incorrectly reuse another tab's model contents.
-            // Why: Changes mode sometimes needs to rotate only the original-side
-            // model after HEAD moves, while preserving the modified-side model's
-            // undo stack for continued editing.
+            // Why: a file can have multiple live diff tabs, so key models off tab identity (not file path) to avoid cross-tab reuse.
+            // Why: Changes mode rotates only the original-side model after HEAD moves, preserving the modified side's undo stack.
             originalModelPath={currentDiffModelPaths.originalModelPath}
             modifiedModelPath={currentDiffModelPaths.modifiedModelPath}
             keepCurrentOriginalModel
diff --git a/src/renderer/src/components/editor/EditorContent.tsx b/src/renderer/src/components/editor/EditorContent.tsx
index 2e5dcbea391..e6ee0f33257 100644
--- a/src/renderer/src/components/editor/EditorContent.tsx
+++ b/src/renderer/src/components/editor/EditorContent.tsx
@@ -1,9 +1,4 @@
-/* eslint-disable max-lines -- Why: EditorContent is the dispatch surface for
-every editor mode (edit, diff, conflict, markdown-preview, combined-diff, and
-now Changes view mode). Keeping the mode-selection branches colocated is easier
-to reason about than scattering the switch across per-mode wrappers. Individual
-renderers (MonacoEditor, DiffViewer, ChangesModeView, MarkdownPreview, etc.)
-already live in their own modules. */
+/* eslint-disable max-lines -- Why: dispatch surface for every editor mode; keeping the mode-selection branches colocated beats scattering the switch across per-mode wrappers. */
 import React from 'react'
 import { lazyWithRetry as lazy } from '@/lib/lazy-with-retry'
 import { AlertCircle, RefreshCw } from 'lucide-react'
@@ -46,9 +41,7 @@ const MermaidViewer = lazy(() => import('./MermaidViewer'))
 const CsvViewer = lazy(() => import('./CsvViewer'))
 const IpynbViewer = lazy(() => import('./IpynbViewer'))
 
-// Why: stable no-op callbacks for read-only tabs so Monaco never routes a
-// content-change or save through the writable pipeline (and so we don't create
-// a new function identity each render).
+// Why: module-level for a stable no-op identity so read-only tabs don't rebuild callbacks each render.
 const noopEditorContentChange = (_content: string): void => {}
 const noopEditorSave = (_content: string): void => {}
 
@@ -234,9 +227,7 @@ export function EditorContent({
           const line = blocks[nextIndex].startLine
           const markerLineLength = getGitConflictMarkerLineLength(content, line)
           setConflictNavigationIndexByFile((prev) => ({ ...prev, [file.id]: nextIndex }))
-          // Why: a same-location reveal can be requested twice before Monaco
-          // consumes the first one. Clearing first guarantees the prop changes
-          // and the mounted editor runs its reveal effect again.
+          // Why: clear first so a repeated same-location reveal still changes the prop and re-runs the editor's reveal effect.
           setPendingEditorReveal(null)
           queueMicrotask(() => {
             setPendingEditorReveal({
@@ -310,11 +301,7 @@ export function EditorContent({
   }
 
   const renderMonacoEditor = (fc: FileContent): React.JSX.Element => (
-    // Why: Without a key, React reuses the same MonacoEditor instance when
-    // switching tabs or split panes, just updating props. That means
-    // useLayoutEffect cleanup (which snapshots scroll position) never fires.
-    // Keying on the visible pane and path forces remount before a retained target
-    // model mounts, so the old path cannot receive the new file's reconciliation.
+    // Why: without a key React reuses the instance and skips cleanup (scroll snapshot); key forces a remount per pane+path.
     <MonacoEditor
       key={`${viewStateScopeId}\u0000${activeFile.filePath}`}
       fileId={activeFile.id}
@@ -323,9 +310,7 @@ export function EditorContent({
       relativePath={activeFile.relativePath}
       content={editBuffers[activeFile.id] ?? fc.content}
       language={monacoLanguage}
-      // Why: read-only tabs (AI Vault View Log) block edits in Monaco and no-op
-      // the change/save callbacks so no draft, dirty state, or write can occur —
-      // mirrors the conflict-review read-only rendering pattern.
+      // Why: read-only tabs no-op the change/save callbacks so no draft, dirty state, or write can occur.
       readOnly={activeFile.readOnly === true}
       liveTail={activeFile.liveTail === true}
       onContentChange={activeFile.readOnly === true ? noopEditorContentChange : handleContentChange}
@@ -362,14 +347,11 @@ export function EditorContent({
     })
 
     if (activeFile.conflict?.conflictStatus === 'unresolved') {
-      // Why: conflict markers are source text the user must edit directly.
-      // Rich/preview markdown modes can hide or reinterpret those marker lines.
+      // Why: rich/preview modes hide the conflict-marker source text the user must edit directly.
       return <div className="h-full min-h-0">{renderMonacoEditor(fc)}</div>
     }
 
-    // Why: the render-mode helper already folded size into the mode decision.
-    // Keep the explanatory banner here so the user understands why "rich" view
-    // currently shows Monaco instead.
+    // Why: banner explains why the "rich" view is showing Monaco source (size forced a source-mode fallback).
     if (renderMode === 'source' && mdViewMode === 'rich') {
       const richFallbackMessage =
         richModeUnsupportedMessage ??
@@ -385,11 +367,7 @@ export function EditorContent({
     }
 
     if (renderMode === 'rich-editor') {
-      // Why: front-matter is stripped before the rich editor sees the content
-      // because Tiptap has no front-matter node and would silently drop it.
-      // The raw block is displayed as a read-only banner and recombined with
-      // the body on every content change and save so the edit buffer always
-      // holds the complete document.
+      // Why: Tiptap has no front-matter node and would drop it, so strip it here and recombine on change/save.
       const fm = extractFrontMatter(currentContent)
       const editorContent = fm ? fm.body : currentContent
 
@@ -404,11 +382,7 @@ export function EditorContent({
       return (
         <div className="flex h-full min-h-0 flex-col">
           <div className="min-h-0 flex-1">
-            {/* Why: same remount reasoning as MonacoEditor — see renderMonacoEditor.
-                The boundary contains a TipTap/ProseMirror render crash (e.g.
-                when a setContent transaction throws under split-pane external
-                reload, issue #826) to this pane instead of letting it tear down
-                the whole renderer tree. */}
+            {/* Why: keyed for remount like MonacoEditor; boundary contains a TipTap render crash (issue #826) to this pane. */}
             <RichMarkdownErrorBoundary key={viewStateScopeId} fileId={activeFile.id}>
               <RichMarkdownEditor
                 fileId={activeFile.id}
@@ -428,10 +402,7 @@ export function EditorContent({
                 markdownAnnotationFilePath={activeFile.relativePath}
                 markdownSourceLineOffset={fm ? getMarkdownSourceLineOffset(fm.raw) : 0}
                 markdownReviewContent={currentContent}
-                // Why: render the front-matter banner below the editor toolbar
-                // (inside the editor shell) so formatting controls remain at
-                // the top of the pane — the banner is read-only context, not
-                // a header above the toolbar.
+                // Why: banner goes below the toolbar (inside the editor shell) so formatting controls stay at the top of the pane.
                 headerSlot={
                   fm && showMarkdownFrontmatter ? <FrontMatterBanner raw={fm.raw} /> : null
                 }
@@ -451,10 +422,7 @@ export function EditorContent({
               {richModeUnsupportedMessage}
             </div>
           ) : null}
-          {/* Why: before rich editing shipped, Orca already had a stable markdown
-          preview surface. If Tiptap cannot safely own a document, falling back
-          to that renderer preserves readable preview mode instead of forcing the
-          user out of preview entirely. Source mode remains available for edits. */}
+          {/* Why: fall back to the stable preview renderer when Tiptap can't safely own the document. */}
           <div className="min-h-0 flex-1">
             <MarkdownPreview
               key={viewStateScopeId}
@@ -474,10 +442,7 @@ export function EditorContent({
       )
     }
 
-    // Why: Monaco sizes itself against the immediate parent when `height="100%"`
-    // is used. Markdown source mode briefly wrapped it in a non-flex container
-    // with no explicit height, which made the code surface collapse even though
-    // the surrounding editor pane was tall enough.
+    // Why: Monaco with height="100%" sizes to its immediate parent, so the wrapper needs an explicit height or it collapses.
     return <div className="h-full min-h-0">{renderMonacoEditor(fc)}</div>
   }
 
@@ -913,8 +878,7 @@ export function EditorContent({
     modifiedDiffBuffer === undefined &&
     dc.modifiedContent.length === 0
   )
-  // Why: rendered once for every diff sub-branch below (preview and source)
-  // so a dirty markdown diff in preview mode surfaces the conflict too.
+  // Why: shared by both diff sub-branches (preview and source) so preview mode surfaces the external change too.
   const diffExternalChangeBanner =
     activeFile.externalMutation === 'changed' ? (
       <ExternalFileChangeBanner
@@ -928,10 +892,7 @@ export function EditorContent({
       <div className="flex h-full min-h-0 flex-col">
         {diffExternalChangeBanner}
         <div className="border-b border-border/60 bg-muted/40 px-3 py-2 text-xs text-muted-foreground">
-          {/* Why: a rendered markdown preview cannot express additions and
-          deletions simultaneously, so preview mode intentionally shows the
-          modified side of the diff. Source mode remains available for the
-          actual line-by-line comparison. */}
+          {/* Why: markdown preview can't show additions and deletions at once, so it shows only the modified side. */}
           {translate(
             'auto.components.editor.EditorContent.9640d1d3db',
             'Previewing the modified version of this diff. Switch to source mode to inspect changes.'
@@ -955,16 +916,13 @@ export function EditorContent({
       </div>
     )
   }
-  // Why: kept Monaco models ignore refreshed git blobs unless the model identity
-  // rotates. Key off fetched diff content and explicit reload nonce, not live
-  // edit-buffer text, so editable unstaged diffs keep their undo stack.
+  // Why: key off fetched diff content + reload nonce (not the edit buffer) so Monaco reloads refreshed blobs but keeps undo.
   const diffReloadNonce = activeFile.diffContentReloadNonce ?? 0
   const originalModelKey = `${diffViewStateKey}:original:${getDiffContentSignature(dc.originalContent)}`
   const modifiedModelKey = `${diffViewStateKey}:modified:${getDiffContentSignature(dc.modifiedContent)}:${diffReloadNonce}`
   const diffViewer = (
     <DiffViewer
-      // Why: content already refreshes in place via modifiedModelKey below, so
-      // keying the component off content too remounts Monaco and flashes on every save.
+      // Why: content refreshes via modifiedModelKey; keying off content too would remount Monaco and flash on every save.
       key={`${viewStateScopeId}:${diffReloadNonce}`}
       modelKey={diffViewStateKey}
       originalModelKey={originalModelKey}
@@ -983,17 +941,12 @@ export function EditorContent({
       onSave={isEditable ? (isMarkdown ? md.mdSave : handleSave) : undefined}
     />
   )
-  // Why: editable unstaged diffs can hold unsaved edits, so they get the same
-  // changed-on-disk recovery banner as edit tabs; its reload refetches the
-  // diff body rather than plain file content.
+  // Why: editable diffs get the changed-on-disk banner; its reload refetches the diff body, not plain file content.
   if (activeFile.externalMutation !== 'changed') {
     return diffViewer
   }
   return (
-    // Why: h-full (not flex-1) — the diff-mode container is not a flex parent,
-    // so flex-1 resolves to zero height and collapses this wrapper. The inner
-    // div must itself be a flex column because DiffViewer's root sizes with
-    // flex-1 and collapses to 0px inside a block parent.
+    // Why: parent isn't a flex container, so flex-1 collapses to 0px — use h-full here and a flex column inside.
     <div className="flex h-full min-h-0 flex-col">
       {diffExternalChangeBanner}
       <div className="flex min-h-0 flex-1 flex-col">{diffViewer}</div>
@@ -1001,10 +954,7 @@ export function EditorContent({
   )
 }
 
-// Why: a minimal read-only banner that shows the raw front-matter content
-// above the rich editor so the user knows it exists and can switch to source
-// mode to edit it. Kept deliberately simple — no collapsible state — to avoid
-// layout shifts that would interfere with ProseMirror's scroll management.
+// Why: no collapsible state — layout shifts would interfere with ProseMirror's scroll management.
 function FrontMatterBanner({ raw }: { raw: string }): React.JSX.Element {
   // Strip the opening/closing delimiters to show only the YAML/TOML content.
   const inner = raw
diff --git a/src/renderer/src/components/editor/MarkdownPreview.tsx b/src/renderer/src/components/editor/MarkdownPreview.tsx
index 3fa53012683..f74e48c4c3a 100644
--- a/src/renderer/src/components/editor/MarkdownPreview.tsx
+++ b/src/renderer/src/components/editor/MarkdownPreview.tsx
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: MarkdownPreview owns rendering, link interception,
-search, and viewport state for the preview surface in one place so markdown
-behavior stays coherent across split panes and preview tabs. */
+/* eslint-disable max-lines -- Why: MarkdownPreview keeps rendering, link interception, search, and viewport state together so preview behavior stays coherent. */
 /* oxlint-disable react-doctor/no-adjust-state-on-prop-change -- Why: search match state is synchronized with DOM highlights inserted into the rendered markdown body. */
 import React, {
   useCallback,
@@ -296,9 +294,7 @@ const markdownPreviewSanitizeSchema = {
   tagNames: [...(defaultSchema.tagNames ?? []), 'details', 'summary', 'kbd', 'sub', 'sup', 'ins'],
   protocols: {
     ...defaultSchema.protocols,
-    // Why: markdown preview owns file:// click routing and authorizes the
-    // user-selected path before opening it in Orca. Sanitization must preserve
-    // the target so the click handler can make that security decision.
+    // Why: keep file:// through sanitize so the click handler can authorize and open the target (the security decision lives there).
     href: [...(defaultSchema.protocols?.href ?? []), 'file'],
     src: [...(defaultSchema.protocols?.src ?? []), 'file']
   },
@@ -484,22 +480,19 @@ export default function MarkdownPreview({
     if (!input) {
       return
     }
-    // Why: opening preview search should select the query once, while typing
-    // and match-count updates must not keep re-selecting the field.
+    // Why: select the query once on open; typing and match-count updates must not keep re-selecting the field.
     input.focus()
     input.select()
   }, [])
   const matchesRef = useRef<Range[]>([])
-  // Stable token identifying this preview in the document-global highlight
-  // registry, so split/floating previews don't clobber each other's Find paint.
+  // Stable per-preview token in the doc-global highlight registry so split/floating previews don't clobber each other's Find paint.
   const searchInstanceRef = useRef<object>({})
   const lastAppliedInitialAnchorRef = useRef<string | null>(null)
   const pendingEditorRevealFrameIdsRef = useRef<number[]>([])
   const [isSearchOpen, setIsSearchOpen] = useState(false)
   const [query, setQuery] = useState('')
   const [matchCount, setMatchCount] = useState(0)
-  // Bumps whenever the match ranges are recomputed, so the active-highlight
-  // effect re-runs even when a streamed rerender yields the same count/index.
+  // Bumps when ranges recompute so the active-highlight effect re-runs even when a rerender yields the same count/index.
   const [searchRevision, setSearchRevision] = useState(0)
   const [activeMatchIndex, setActiveMatchIndex] = useState(-1)
   const isMac = navigator.userAgent.includes('Mac')
@@ -608,11 +601,7 @@ export default function MarkdownPreview({
   }, [renderedContent, filePath, imageRuntimeContext])
 
   const frontMatter = useMemo(() => extractFrontMatter(renderedContent), [renderedContent])
-  // Why: building the table of contents runs a full-document remark parse on
-  // every content change, and the preview's content churns on streamed/external
-  // file writes. The result is only used while the panel is open (closed by
-  // default), so gate the parse on visibility; showTableOfContents in the deps
-  // rebuilds the outline the moment it opens.
+  // Why: TOC parse is a full-document remark pass; gate on the (default-closed) panel's visibility so it only runs while open.
   const tableOfContentsItems = useMemo(
     () => selectMarkdownTableOfContents(showTableOfContents, renderedContent),
     [renderedContent, showTableOfContents]
@@ -630,21 +619,18 @@ export default function MarkdownPreview({
       .replace(/\r?\n(?:---|\+\+\+)\r?\n?$/, '')
       .trim()
   }, [frontMatter])
-  // Why: front matter shows by default and is toggled off from the markdown
-  // preview actions menu; the store map only carries per-file hide overrides.
+  // Why: front matter is visible by default; the store map only carries per-file hide overrides.
   const toggleableSourceFileId: string | null = sourceFileId ?? null
   const frontmatterVisible = toggleableSourceFileId
     ? (frontmatterVisibleByFile[toggleableSourceFileId] ?? true)
     : true
   const [activeAnnotationBlockKey, setActiveAnnotationBlockKey] = useState<string | null>(null)
   const activeAnnotationBlockKeyRef = useRef(activeAnnotationBlockKey)
-  // Why: mirrored in an effect (not the render body) so a discarded render
-  // pass cannot leak into the ref; keydown paths still write it eagerly.
+  // Why: mirror in an effect (not render body) so a discarded render can't leak into the ref; keydown paths still write eagerly.
   useEffect(() => {
     activeAnnotationBlockKeyRef.current = activeAnnotationBlockKey
   }, [activeAnnotationBlockKey])
-  // Why: line-derived block keys can go stale after content renumbers; drop them
-  // when the block no longer mounts so the shortcut cannot lock out forever.
+  // Why: line-derived block keys go stale after content renumbers; drop unmounted ones so the shortcut can't lock out forever.
   useEffect(() => {
     if (!activeAnnotationBlockKey) {
       return
@@ -653,18 +639,15 @@ export default function MarkdownPreview({
     if (!root || previewHasAnnotationBlockKey(root, activeAnnotationBlockKey)) {
       return
     }
-    // Why: the mirror effect above re-syncs the ref once this setState commits;
-    // only the same-tick keydown paths need an eager manual write.
+    // Why: the mirror effect re-syncs the ref after this commits; only same-tick keydown paths need an eager write.
     setActiveAnnotationBlockKey(null)
-    // Why: keyed on renderedContent (not content) — the DOM the block keys live
-    // in derives from it and can lag content during external-edit preservation.
+    // Why: key on renderedContent (not content) since block keys live in the DOM derived from it and can lag content.
   }, [activeAnnotationBlockKey, renderedContent])
   const [reviewNotesCopied, setReviewNotesCopied] = useState(false)
   const [copiedReviewNoteId, setCopiedReviewNoteId] = useState<string | null>(null)
   const reviewNotesCopiedResetTimerRef = useRef<number | null>(null)
   const copiedReviewNoteResetTimerRef = useRef<number | null>(null)
-  // Why: clipboard IPC can resolve after the preview unmounts; skip copied
-  // feedback instead of starting a reset timer on a stale preview.
+  // Why: clipboard IPC can resolve after unmount; skip copied feedback instead of starting a reset timer on a stale preview.
   const reviewNotesCopyMountedRef = useRef(false)
   const [activeReviewCommentId, setActiveReviewCommentId] = useState<string | null>(null)
   const [attentionReviewCommentId, setAttentionReviewCommentId] = useState<string | null>(null)
@@ -696,9 +679,7 @@ export default function MarkdownPreview({
     markdownAnnotationsEnabled && sourceWorktree && sourceRelativePath !== null
   )
 
-  // Why: each split pane needs its own markdown preview viewport even when the
-  // underlying file is shared. The caller passes a pane-scoped cache key so
-  // duplicate tabs do not overwrite each other's preview scroll state.
+  // Why: split panes share the file but each needs its own scroll viewport, so the caller passes a pane-scoped cache key.
 
   // Save scroll position with trailing throttle and synchronous unmount snapshot.
   useLayoutEffect(() => {
@@ -721,9 +702,7 @@ export default function MarkdownPreview({
 
     container.addEventListener('scroll', onScroll, { passive: true })
     return () => {
-      // Why: During React StrictMode double-mount (or rapid mount/unmount before
-      // react-markdown renders content), scrollHeight equals clientHeight and
-      // scrollTop is 0. Saving that would clobber a valid cached position.
+      // Why: on StrictMode double-mount scrollHeight==clientHeight and scrollTop is 0; saving that would clobber a valid cached position.
       if (container.scrollHeight > container.clientHeight || container.scrollTop > 0) {
         setWithLRU(scrollTopCache, scrollCacheKey, container.scrollTop)
       }
@@ -745,10 +724,7 @@ export default function MarkdownPreview({
     let frameId = 0
     let attempts = 0
 
-    // Why: react-markdown renders asynchronously, so scrollHeight may still be
-    // too small on the first frame. Retry up to 30 frames (~500ms at 60fps) to
-    // accommodate content loading. This matches CombinedDiffViewer's proven
-    // pattern for dynamic-height content restoration.
+    // Why: react-markdown renders async so scrollHeight lags; retry up to 30 frames (~500ms at 60fps) until content is tall enough.
     const tryRestore = (): void => {
       const maxScrollTop = Math.max(0, container.scrollHeight - container.clientHeight)
       const nextScrollTop = Math.min(targetScrollTop, maxScrollTop)
@@ -766,9 +742,7 @@ export default function MarkdownPreview({
 
     tryRestore()
     return () => window.cancelAnimationFrame(frameId)
-    // Why: content is included so the restore loop re-triggers when markdown
-    // content arrives or changes (e.g., async file load), since scrollHeight
-    // depends on rendered content and may not be large enough until then.
+    // Why: renderedContent is a dep so the restore re-triggers when async content arrives and scrollHeight finally grows.
   }, [scrollCacheKey, renderedContent])
 
   const moveToMatch = useCallback((direction: 1 | -1) => {
@@ -812,8 +786,7 @@ export default function MarkdownPreview({
   }, [])
 
   const cleanupPreviewSurfaceTimers = useCallback((): void => {
-    // Why: reveal/copy timers are event-owned, but the final cancellation
-    // belongs to the preview surface unmount.
+    // Why: reveal/copy timers are event-owned, but the final cancellation belongs to preview-surface unmount.
     cancelMarkdownPreviewEditorRevealFrames(pendingEditorRevealFrameIdsRef)
     clearMarkdownPreviewTimeout(attentionReviewCommentTimeoutRef)
     clearReviewNotesCopiedResetTimer()
@@ -877,9 +850,7 @@ export default function MarkdownPreview({
       return
     }
 
-    // Search decorations are painted via the CSS Custom Highlight API (Ranges,
-    // no DOM mutation) because the rendered preview is owned by react-markdown;
-    // splitting its nodes to inject <mark> corrupted react's tree (crash 237acef1).
+    // Why: paint via CSS Custom Highlight API (no DOM mutation) — injecting <mark> into react-markdown's tree crashed react (237acef1).
     const matches = applyMarkdownPreviewSearchHighlights(instanceId, body, query)
     matchesRef.current = matches
     setMatchCount(matches.length)
@@ -959,8 +930,7 @@ export default function MarkdownPreview({
         return
       }
       if (reviewNoteKey.action === 'clear-stale-and-ignore') {
-        // Why: drop a line-derived key that no longer mounts a composer so the
-        // shortcut cannot stay permanently consumed after content renumbers.
+        // Why: drop a stale line-derived key with no mounted composer so the shortcut can't stay consumed after content renumbers.
         activeAnnotationBlockKeyRef.current = null
         setActiveAnnotationBlockKey(null)
         return
@@ -1362,10 +1332,7 @@ export default function MarkdownPreview({
             return
           }
 
-          // Why: Cmd/Ctrl+Shift-click is the OS escape hatch — always hand the
-          // link to the system default handler, bypassing the classifier. For a
-          // dangling in-worktree .md, pre-check existence so the user sees a
-          // toast instead of the silent no-op from shell.openFileUri.
+          // Why: Cmd/Ctrl+Shift-click is the OS escape hatch — bypass the classifier; pre-check a dangling .md so the user gets a toast, not a silent openFileUri no-op.
           if (isMarkdownPreviewSystemBrowserModifier(event, isMac)) {
             if (sourceOwner.kind === 'unknown') {
               return
@@ -1402,8 +1369,7 @@ export default function MarkdownPreview({
                   { connectionId: sourceConnectionId }
                 )
               ) {
-                // Why: modifier-open delegates to the client OS. Server-local
-                // file:// targets from remote runtime/SSH worktrees cannot be opened locally.
+                // Why: modifier-open delegates to the client OS; server-local file:// from remote runtime/SSH worktrees can't open locally.
                 showLocalPathOpenBlockedToast()
                 return
               }
@@ -1412,8 +1378,7 @@ export default function MarkdownPreview({
                 classified?.kind === 'markdown' ||
                 (classified?.kind === 'file' && classified.line !== undefined)
               ) {
-                // Why: use the classifier's stripped absolutePath (no `:line:col`
-                // or `#L10` suffix) so the OS handler receives a clean file URI.
+                // Why: use the classifier's stripped absolutePath (no `:line:col`/`#L10`) so the OS handler gets a clean file URI.
                 const cleanUri = absolutePathToFileUri(classified.absolutePath)
                 void window.api.shell.pathExists(classified.absolutePath).then((exists) => {
                   if (!exists) {
@@ -1441,10 +1406,7 @@ export default function MarkdownPreview({
           }
 
           if (target.protocol === 'http:' || target.protocol === 'https:') {
-            // Why: route through openHttpLink (not raw shell.openUrl) so a plain
-            // click honors the "open links in Orca" setting; openHttpLink keeps
-            // remote runtimes on the system browser. (Cmd/Ctrl+Shift-click is
-            // handled above; this path only sees non-escape-hatch clicks.)
+            // Why: route through openHttpLink (not shell.openUrl) so a plain click honors "open links in Orca"; remote runtimes stay on the system browser.
             openHttpLink(
               target.toString(),
               resolveMarkdownPreviewHttpOpenOptions(
@@ -1473,10 +1435,7 @@ export default function MarkdownPreview({
               ? { line: classifiedFileTarget.line, column: classifiedFileTarget.column }
               : parseLineTarget(target.hash)
 
-          // Why: same-file anchors need no ownership/filesystem resolution (e.g.
-          // `./README.md#heading` when this file is README.md). Run before the
-          // unknown-ownership guard so ambiguous folder-workspace ownership still
-          // scrolls within the open document.
+          // Why: same-file anchors need no ownership resolution; run before the unknown-ownership guard so ambiguous ownership still scrolls in-doc.
           if (absolutePath === filePath && target.hash && !lineTarget) {
             void scrollToAnchor(target.hash.slice(1))
             return
@@ -1494,9 +1453,7 @@ export default function MarkdownPreview({
           )
           if (!targetWorktree) {
             if (sourceRoutingWorktreeId && worktreeRoot) {
-              // Why: floating markdown files are owned by a synthetic workspace,
-              // so there may be no repo worktree even though Orca can stat/open
-              // links relative to the source file root.
+              // Why: floating markdown lives in a synthetic workspace with no repo worktree, though Orca can still open links relative to the source root.
               void activateMarkdownLink(href, {
                 sourceFilePath: filePath,
                 worktreeId: sourceRoutingWorktreeId,
@@ -1515,8 +1472,7 @@ export default function MarkdownPreview({
                 { connectionId: sourceConnectionId }
               )
             ) {
-              // Why: without a workspace match, opening a file URI delegates to
-              // the client OS. Remote runtime/SSH paths are not local files.
+              // Why: without a workspace match, opening a file URI delegates to the client OS; remote runtime/SSH paths aren't local files.
               showLocalPathOpenBlockedToast()
               return
             }
@@ -1567,8 +1523,7 @@ export default function MarkdownPreview({
             return
           }
 
-          // Why: line targets like #L10 and path.ts:10 should reveal in Monaco,
-          // not open a preview tab or a literal path with the suffix included.
+          // Why: line targets like #L10 and path.ts:10 should reveal in Monaco, not open a preview tab or a literal suffixed path.
           if (lineTarget) {
             openFile({
               filePath: absolutePath,
@@ -1640,9 +1595,7 @@ export default function MarkdownPreview({
         )
       },
       img: function MarkdownImg({ src, alt, ...props }) {
-        // eslint-disable-next-line react-hooks/rules-of-hooks -- react-markdown
-        // instantiates component overrides as regular React components, so hooks
-        // are valid here despite the lowercase function name.
+        // eslint-disable-next-line react-hooks/rules-of-hooks -- react-markdown instantiates overrides as regular components, so hooks are valid despite the lowercase name.
         const resolvedSrc = useLocalImageSrc(src, filePath, undefined, imageRuntimeContext)
         const handleImageClick = (event: React.MouseEvent<HTMLImageElement>): void => {
           if (!isMarkdownPreviewOpenModifier(event, isMac)) {
@@ -1664,16 +1617,10 @@ export default function MarkdownPreview({
           })
         }
 
-        // Why: display uses IPC-backed blob URLs, but Cmd/Ctrl-click should open
-        // the original markdown target so local and SSH worktree images route
-        // through the same editor path as normal file links.
+        // Why: display uses IPC blob URLs, but Cmd/Ctrl-click opens the original target so local/SSH images use the normal file-link path.
         return <img {...props} src={resolvedSrc} alt={alt ?? ''} onClick={handleImageClick} />
       },
-      // Why: Intercept code elements to detect mermaid fenced blocks. rehype-highlight
-      // sets className="language-mermaid" on the <code> inside <pre> for ```mermaid blocks.
-      // We render those as SVG diagrams instead of highlighted source. Markdown preview
-      // opts out of Mermaid HTML labels because this path sanitizes the SVG before
-      // injection, and sanitized foreignObject labels disappear on some platforms.
+      // Why: render language-mermaid blocks as SVG; opt out of Mermaid HTML labels since sanitized foreignObject labels disappear on some platforms.
       code: ({ className, children, ...props }) => {
         if (/language-mermaid/.test(className || '')) {
           return (
@@ -1686,11 +1633,7 @@ export default function MarkdownPreview({
           </code>
         )
       },
-      // Why: Wrap <pre> blocks with a positioned container so a copy button can
-      // overlay the code block. Mermaid diagrams are detected and passed through
-      // unwrapped — MermaidBlock renders via useEffect/innerHTML, not React children,
-      // so CodeBlockCopyButton's extractText() would copy an empty string, and a
-      // <div> inside <pre> produces invalid HTML.
+      // Why: wrap <pre> for the copy button, but pass MermaidBlock through unwrapped (it renders via innerHTML so extractText copies nothing, and <div> in <pre> is invalid HTML).
       pre: ({ node, children, ...props }) => {
         const child = React.Children.toArray(children)[0]
         if (React.isValidElement(child) && child.type === MermaidBlock) {
@@ -1739,8 +1682,7 @@ export default function MarkdownPreview({
               }`.trim()}
               data-source-line={range.startLine}
               data-source-end-line={range.endLine}
-              // Why: only advertise the block to the add-review-note shortcut
-              // when the composer can actually render (mirrors wrapAnnotatedBlock).
+              // Why: only advertise the block to the add-review-note shortcut when the composer can render (mirrors wrapAnnotatedBlock).
               data-annotation-block-key={controls ? blockKey : undefined}
               onClick={(event) => handleAnnotatedMarkdownBlockClick(range, event)}
             >
@@ -1805,9 +1747,7 @@ export default function MarkdownPreview({
         )
       }
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- the `img` override calls useLocalImageSrc
-    // which is a hook, so react-markdown must see a stable component identity. The deps listed here
-    // cover every value the overrides actually close over; slugger is a ref.
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- img override calls useLocalImageSrc (a hook) so identity must stay stable; deps cover every closed-over value.
   }, [
     filePath,
     activateMarkdownLink,
@@ -1994,13 +1934,9 @@ export default function MarkdownPreview({
             ) : null}
           </div>
         ) : null}
-        {/* Why: translate="no" keeps browser/OS page-translation from swapping
-            text nodes react owns, which otherwise triggers the same
-            insertBefore/removeChild reconciliation crash (237acef1). */}
+        {/* Why: translate="no" stops OS page-translation swapping react-owned text nodes → insertBefore/removeChild crash (237acef1). */}
         <div ref={bodyRef} className="markdown-body" translate="no">
-          {/* Why: remarkFrontmatter strips front matter from normal markdown
-        output. When the user opts in from the preview actions menu, render the
-        raw metadata as a compact read-only block above the document body. */}
+          {/* Why: remarkFrontmatter strips front matter, so render it as a read-only block when the user opts in. */}
           {frontMatter && frontmatterVisible ? (
             <div className="mb-4 rounded border border-border/60 bg-muted/40 px-3 py-2">
               <div className="mb-1 text-[10px] font-medium uppercase tracking-wider text-muted-foreground">
@@ -2013,8 +1949,7 @@ export default function MarkdownPreview({
           ) : null}
           <Markdown
             components={components}
-            // Why: react-markdown filters file:// after rehype-sanitize; preview
-            // click handlers need the target so they can authorize and open it.
+            // Why: react-markdown filters file:// after sanitize; click handlers need the target to authorize and open it.
             urlTransform={markdownPreviewUrlTransform}
             remarkPlugins={[
               remarkGfm,
@@ -2023,10 +1958,7 @@ export default function MarkdownPreview({
               remarkMath,
               remarkMarkdownDocLinks
             ]}
-            // Why: raw HTML must be sanitized before any trusted renderer expands
-            // it into richer DOM. Running KaTeX and syntax highlighting after
-            // sanitize preserves VS Code-style math/code rendering without having
-            // to whitelist KaTeX's generated markup in the user-content schema.
+            // Why: sanitize raw HTML before KaTeX/highlight expand it, so their generated markup needn't be whitelisted in the schema.
             rehypePlugins={[
               rehypeRaw,
               [rehypeSanitize, markdownPreviewSanitizeSchema],
@@ -2093,9 +2025,7 @@ function MarkdownAnnotationComposer({
   const mountedRef = useMountedRef()
   const composerRef = useRef<HTMLDivElement | null>(null)
 
-  // Why: product B — composer focus is in the textarea, so consume the bindable
-  // add-review-note chord on the composer subtree (same guard as
-  // DiffCommentPopover) rather than window, so other surfaces keep their chord.
+  // Why: scope the add-review-note chord (product B) to the composer subtree like DiffCommentPopover, not window, so other surfaces keep theirs.
   useEffect(() => {
     const composer = composerRef.current
     if (!composer) {
@@ -2105,8 +2035,7 @@ function MarkdownAnnotationComposer({
   }, [])
 
   const focusTextareaRef = useCallback((textarea: HTMLTextAreaElement | null): void => {
-    // Why: opening an annotation composer should focus the draft field on the
-    // mount edge; no external subscription is needed.
+    // Why: callback ref focuses on the mount edge, so no effect subscription is needed.
     textarea?.focus()
   }, [])
 
diff --git a/src/renderer/src/components/editor/MonacoEditor.tsx b/src/renderer/src/components/editor/MonacoEditor.tsx
index ff187593da2..8caad87f633 100644
--- a/src/renderer/src/components/editor/MonacoEditor.tsx
+++ b/src/renderer/src/components/editor/MonacoEditor.tsx
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: MonacoEditor centralizes Monaco setup,
-source-mode markdown annotations, persistence-safe content sync, reveal
-handling, and editor-local UI overlays so split-pane state remains coherent. */
+/* eslint-disable max-lines -- Why: centralizes Monaco setup, markdown annotations, content sync, reveal handling, and editor-local UI overlays. */
 /* oxlint-disable react-doctor/no-adjust-state-on-prop-change -- Why: selection annotations are synchronized from Monaco editor selection and layout APIs, not derived React props. */
 import React, { useRef, useCallback, useEffect, useLayoutEffect, useMemo, useState } from 'react'
 import Editor, { type OnMount } from '@monaco-editor/react'
@@ -128,16 +126,10 @@ export default function MonacoEditor({
   const revealInnerRafRef = useRef<number | null>(null)
   const unregisterFileSearchSelectionRef = useRef<(() => void) | null>(null)
   const { setupCopy, toastNode } = useContextualCopySetup()
-  // Why: The scroll throttle timer must be accessible from useLayoutEffect cleanup
-  // so we can cancel any pending write before synchronously snapshotting the final
-  // scroll position on unmount. Without this, a pending timer could fire after
-  // cleanup and overwrite the correct value with a stale one.
+  // Why: hold the throttle timer in a ref so unmount cleanup can cancel a pending write before snapshotting the final scroll position.
   const scrollThrottleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const propsRef = useRef({ relativePath, language, onSave, onContentChange })
-  // Why: assigning during render keeps the ref current before any event handler
-  // or effect reads it, avoiding the one-render stale window that a useEffect
-  // would introduce. Refs are mutable and don't trigger re-renders, so this is
-  // safe to do unconditionally every render.
+  // Why: assign during render so the ref is current before any handler reads it (a useEffect would leave a one-render stale window).
   propsRef.current = { relativePath, language, onSave, onContentChange }
   const readOnlyRef = useRef(readOnly)
   readOnlyRef.current = readOnly
@@ -174,18 +166,8 @@ export default function MonacoEditor({
   const autoHeightLineHeight = Math.ceil(editorFontSize * 1.45)
   const autoHeightUsesInternalScroll =
     autoHeight && isMonacoAutoHeightCapped(renderedEditorHeight, autoHeightLineHeight)
-  // Why: `keepCurrentModel` retains Monaco models across unmounts, and
-  // @monaco-editor/react skips its value→model sync on the first render after
-  // a remount. Without explicit sync, external file changes that arrived
-  // while the tab was unmounted leave the retained model showing stale text.
-  // contentRef lets handleMount read the current content without re-binding;
-  // lastSyncedContentRef lets the update effect distinguish our own onChange
-  // emissions from real prop drift.
-  // Invariant: the mount path (handleMount's syncContentOnMount call) MUST
-  // read `contentRef.current`, never `lastSyncedContentRef.current`. The
-  // useLayoutEffect below can run before mount with `editorRef.current === null`
-  // and bails without updating lastSyncedContentRef, so that ref may be stale
-  // pre-mount; only contentRef is guaranteed to reflect the latest prop.
+  // Why: @monaco-editor/react skips its value→model sync on the first post-remount render, so retained models need an explicit sync or they show stale text.
+  // Invariant: the mount path must read `contentRef.current` (guaranteed latest), never `lastSyncedContentRef.current` (may be stale pre-mount).
   const contentRef = useRef(content)
   contentRef.current = content
   const lastSyncedContentRef = useRef<string>(content)
@@ -202,9 +184,7 @@ export default function MonacoEditor({
   const [commentPopover, setCommentPopover] = useState<MarkdownCommentPopoverState | null>(null)
   const [selectionAnnotationTarget, setSelectionAnnotationTarget] =
     useState<MonacoMarkdownSelectionAnnotationTarget | null>(null)
-  // Why: claim open drafts synchronously so a same-tick second chord cannot
-  // remount the composer before React commits commentPopover state. Mirrored
-  // in an effect so a discarded render pass cannot leak into the ref.
+  // Why: claim drafts synchronously so a same-tick second chord can't remount the composer before React commits state.
   const commentPopoverRef = useRef<MarkdownCommentPopoverState | null>(null)
   useEffect(() => {
     commentPopoverRef.current = commentPopover
@@ -231,8 +211,7 @@ export default function MonacoEditor({
 
   const shouldShowMarkdownAnnotations =
     markdownAnnotationsEnabled && language === 'markdown' && Boolean(worktreeId)
-  // Why: the Monaco mount closure installs its keydown listeners once, so the
-  // add-review-note shortcut reads the current enablement through a ref.
+  // Why: the mount closure installs keydown listeners once, so the shortcut reads current enablement through a ref.
   const shouldShowMarkdownAnnotationsRef = useRef(shouldShowMarkdownAnnotations)
   useEffect(() => {
     shouldShowMarkdownAnnotationsRef.current = shouldShowMarkdownAnnotations
@@ -310,19 +289,14 @@ export default function MonacoEditor({
       let waitFrames = 0
 
       const schedule = (): void => {
-        // Why: the search click path already waits two frames before publishing
-        // the reveal intent, but Monaco can still mount before its viewport math
-        // settles. Deferring the actual reveal by two editor-owned frames keeps
-        // scroll-to-match and inline highlight deterministic on fresh opens.
+        // Why: Monaco can mount before its viewport math settles, so defer the reveal two editor-owned frames for deterministic scroll/highlight.
         revealRafRef.current = requestAnimationFrame(() => {
           revealInnerRafRef.current = requestAnimationFrame(() => {
             revealRafRef.current = null
             revealInnerRafRef.current = null
             const modelLineCount = editorInstance.getModel()?.getLineCount() ?? 0
             if (line > 1 && modelLineCount < line && waitFrames < MAX_REVEAL_CONTENT_WAIT_FRAMES) {
-              // Why: fresh file opens can mount Monaco against an empty one-line
-              // model before the async file read arrives. Waiting prevents the
-              // requested line from being clamped to 1 and then cleared.
+              // Why: fresh opens can mount an empty 1-line model before the async read; waiting stops the target line clamping to 1.
               waitFrames += 2
               schedule()
               return
@@ -347,10 +321,7 @@ export default function MonacoEditor({
     [cancelScheduledReveal, clearTransientRevealHighlight]
   )
 
-  // Why: Monaco model reconciliation reuses real edit operations so retained
-  // models keep sane undo behavior. Those edits are programmatic, not user
-  // typing, so split panes must suppress the resulting onChange callback or a
-  // freshly mounted markdown source view can mark the shared file dirty.
+  // Why: reconciliation uses real edit ops (to keep undo sane), so these programmatic edits must suppress onChange or they'd mark the file dirty.
   const isApplyingProgrammaticContentRef = useRef(false)
   const isApplyingLargePasteRef = useRef(false)
 
@@ -389,9 +360,7 @@ export default function MonacoEditor({
       ensureMarkdownDocCompletionProvider(monaco)
       updateMarkdownCompletionDocuments()
 
-      // Why: see comment on contentRef — reconcile the retained model against
-      // the current prop before any user interaction so external changes that
-      // arrived while the tab was unmounted become visible immediately.
+      // Why: see contentRef — reconcile the retained model to the current prop before user interaction (surfaces edits made while unmounted).
       beginProgrammaticContentSync(filePath)
       isApplyingProgrammaticContentRef.current = true
       try {
@@ -419,8 +388,7 @@ export default function MonacoEditor({
         if (!model || !selection || selection.isEmpty()) {
           return null
         }
-        // Why: Monaco selections live in its text model, not the DOM selection
-        // API that app-level keyboard shortcuts can read.
+        // Why: Monaco selections live in its text model, not the DOM selection API that app shortcuts read.
         return model.getValueInRange(selection)
       })
 
@@ -432,17 +400,14 @@ export default function MonacoEditor({
       const cleanupFindShortcut = installMonacoEditorFindShortcut(editorInstance)
       // Opens the same composer as the selection "+" button.
       const cleanupAddReviewNoteShortcut = installEditorAddReviewNoteShortcut(editorDomNode, () => {
-        // Why: product B — keep an open draft instead of remounting (same-tick
-        // races and editor-focused second chords before the composer guard runs).
+        // Why: keep an open draft instead of remounting, to avoid same-tick chord races before the composer guard runs.
         if (commentPopoverRef.current) {
           return true
         }
         if (!shouldShowMarkdownAnnotationsRef.current) {
           return false
         }
-        // Why: the rendered target ref lags onDidChangeCursorSelection by a
-        // render, so a chord right after a drag could open on the previous
-        // selection (or miss a fresh one); read Monaco's live selection instead.
+        // Why: the rendered target ref lags selection by a render, so read Monaco's live selection to avoid opening on a stale one.
         const target = getMonacoMarkdownSelectionAnnotationTarget(
           editorInstance,
           editorInstance.getSelection(),
@@ -516,10 +481,7 @@ export default function MonacoEditor({
         })
       })
 
-      // Why: Writing to the Map at 60fps (every scroll frame) is unnecessary since
-      // we only need the final position when the user stops scrolling or switches
-      // tabs. A trailing throttle of ~150ms captures the resting position while
-      // avoiding excessive writes.
+      // Why: only the resting scroll position matters, so trailing-throttle writes (~150ms) instead of writing every 60fps frame.
       const scrollStateSub = editorInstance.onDidScrollChange((e) => {
         if (scrollThrottleTimerRef.current !== null) {
           clearTimeout(scrollThrottleTimerRef.current)
@@ -530,8 +492,7 @@ export default function MonacoEditor({
         }, 150)
       })
 
-      // Intercept right-click on line number gutter to show Radix context menu
-      // (same approach as VSCode: custom menu instead of Monaco's built-in one)
+      // Why: custom Radix gutter menu instead of Monaco's built-in right-click menu (VSCode approach).
       const gutterMouseDownSub = editorInstance.onMouseDown((e) => {
         if (
           e.event.rightButton &&
@@ -548,8 +509,6 @@ export default function MonacoEditor({
       })
 
       editorInstance.onDidDispose(() => {
-        // Why: keep editor-owned UI subscriptions symmetrical with the
-        // shortcut/decorator cleanup when Monaco tears this instance down.
         cursorPositionSub.dispose()
         scrollStateSub.dispose()
         gutterMouseDownSub.dispose()
@@ -573,9 +532,7 @@ export default function MonacoEditor({
 
       // If there's a pending reveal at mount time, execute it now
       const reveal = useAppStore.getState().pendingEditorReveal
-      // Why: search-result navigation sets the reveal before openFile switches
-      // the active tab. Without scoping consumption to the destination file,
-      // the previously mounted editor can clear the reveal on the first click.
+      // Why: scope reveal consumption to the destination file, or the previously mounted editor clears it before openFile switches tabs.
       const revealMatchesEditor = reveal?.fileId
         ? reveal.fileId === fileId
         : reveal?.filePath === filePath
@@ -587,11 +544,7 @@ export default function MonacoEditor({
         const savedCursor = cursorPositionCache.get(viewStateKey)
         const savedScrollTop = scrollTopCache.get(viewStateKey)
         if (savedScrollTop !== undefined || savedCursor) {
-          // Why: Monaco renders synchronously, so a single RAF is sufficient to
-          // wait for the layout pass. Unlike react-markdown or Tiptap, there is
-          // no async content loading that would require a retry loop.
-          // Focus is deferred into the same RAF to avoid a one-frame flash where
-          // the editor is focused at scroll position 0 before restoration.
+          // Why: Monaco renders synchronously so one RAF suffices; focus inside it to avoid a scroll-0 flash before restore.
           requestAnimationFrame(() => {
             if (savedCursor) {
               editorInstance.setPosition(savedCursor)
@@ -692,11 +645,7 @@ export default function MonacoEditor({
   const handleChange = useCallback(
     (value: string | undefined) => {
       if (value !== undefined) {
-        // Why: split panes that share a retained Monaco model all receive the
-        // same model change events. When one pane is reconciling prop content
-        // into the shared model, sibling panes must ignore the echoed onChange
-        // or they'll treat the programmatic sync as a user edit and mark the
-        // shared file dirty.
+        // Why: split panes share one retained model, so a sibling must ignore the echoed programmatic-sync onChange or it marks the file dirty.
         if (isApplyingLargePasteRef.current) {
           lastSyncedContentRef.current = value
           return
@@ -716,10 +665,7 @@ export default function MonacoEditor({
     [filePath, onContentChange]
   )
 
-  // Why: reconcile the model whenever `content` drifts from what we last
-  // synced (covers external file changes while mounted). The on-mount case
-  // is handled directly in handleMount. useLayoutEffect lets the overwrite
-  // land before paint so the user never sees stale text.
+  // Why: sync the model on external `content` drift; useLayoutEffect lands the overwrite before paint so no stale text flashes. On-mount handled in handleMount.
   useLayoutEffect(() => {
     const ed = editorRef.current
     if (!ed || lastSyncedContentRef.current === content) {
@@ -736,15 +682,10 @@ export default function MonacoEditor({
     }
   }, [content, filePath])
 
-  // Snapshot scroll position synchronously on unmount so tab switches always
-  // capture the latest value, even if the trailing throttle hasn't fired yet.
-  // Why useLayoutEffect: cleanup runs before @monaco-editor/react's useEffect
-  // disposes the editor instance, guaranteeing getScrollTop() reads valid state.
+  // Why useLayoutEffect: cleanup runs before @monaco-editor/react disposes the editor, so getScrollTop() still reads valid state on unmount.
   useLayoutEffect(() => {
     return () => {
-      // Why: Cancel any pending throttled scroll write so it cannot fire after
-      // this synchronous snapshot, which would overwrite the correct final
-      // position with a stale intermediate value.
+      // Why: cancel the pending throttled write so it can't fire after this snapshot and overwrite the final position with a stale value.
       if (scrollThrottleTimerRef.current !== null) {
         clearTimeout(scrollThrottleTimerRef.current)
         scrollThrottleTimerRef.current = null
@@ -794,8 +735,7 @@ export default function MonacoEditor({
       return
     }
 
-    // Why: Git conflict marker lines are ordinary file text; Monaco needs
-    // explicit decorations so unresolved blocks remain visible while editing.
+    // Why: conflict markers are ordinary file text, so Monaco needs explicit decorations to keep unresolved blocks visible.
     const decorations = buildGitConflictDecorations(content)
     if (!conflictDecorationsRef.current) {
       conflictDecorationsRef.current = ed.createDecorationsCollection(decorations)
@@ -826,10 +766,7 @@ export default function MonacoEditor({
       return
     }
     queueReveal(editorRef.current, revealLine, revealColumn ?? 1, revealMatchLength ?? 0, () => {
-      // Why: the reveal is intentionally delayed until Monaco finishes its
-      // own post-mount layout frames. Clearing the pending payload only after
-      // the queued reveal runs prevents lost navigation if the editor
-      // unmounts before those frames execute.
+      // Why: clear the pending payload only after the queued reveal runs, so navigation isn't lost if the editor unmounts first.
       setPendingEditorReveal(null)
     })
   }, [queueReveal, revealLine, revealColumn, revealMatchLength, setPendingEditorReveal])
@@ -885,17 +822,13 @@ export default function MonacoEditor({
       <Editor
         height={renderedEditorHeight === null ? '100%' : `${renderedEditorHeight}px`}
         language={language}
-        // Why: Orca's mount/layout reconciliation is the sole post-mount content
-        // owner; the wrapper's controlled read-only path would also call setValue.
+        // Why: defaultValue, not controlled value — Orca owns post-mount content sync; a controlled path would double setValue.
         defaultValue={content}
         theme={isDark ? 'vs-dark' : 'vs'}
         onChange={handleChange}
         onMount={handleMount}
         options={{
-          // Why: only the file editor honors editorMinimapEnabled. Monaco 0.55's
-          // DiffEditor hard-overrides minimap.enabled = false on its inner editors
-          // (see diffEditorEditors._adjustOptionsForSubEditor), so threading the
-          // setting into DiffViewer/DiffSectionItem would have no effect.
+          // Why: only the file editor honors this; Monaco 0.55 DiffEditor hard-overrides minimap.enabled=false on sub-editors (see diffEditorEditors._adjustOptionsForSubEditor).
           minimap: { enabled: settings?.editorMinimapEnabled ?? false },
           scrollBeyondLastLine: false,
           ...buildFileEditorWordWrapOptions(editorWordWrap),
@@ -920,16 +853,11 @@ export default function MonacoEditor({
             autoFindInSelection: 'never',
             seedSearchStringFromSelection: 'never'
           },
-          // Why: Monaco has its own Linux primary-selection integration; keep
-          // it aligned with Orca's app-level opt-out instead of relying on the
-          // global DOM hook, which does not own Monaco's rendered line surface.
+          // Why: Monaco owns its rendered line surface, so align its selection-clipboard with the app opt-out (the global DOM hook can't).
           selectionClipboard: settings?.primarySelectionMiddleClickPaste ?? isLinuxUserAgent()
         }}
         path={filePath}
-        // Why: keepCurrentModel preserves the Monaco text model so undo/redo
-        // survives tab switches, but @monaco-editor/react's own view-state Map
-        // would become a second state owner. Orca restores cursor/scroll from
-        // its explicit caches so close/reopen semantics stay under app control.
+        // Why: Orca owns cursor/scroll restoration, so disable @monaco-editor/react's competing view-state Map.
         saveViewState={false}
         keepCurrentModel
       />
diff --git a/src/renderer/src/components/editor/editor-autosave-controller.ts b/src/renderer/src/components/editor/editor-autosave-controller.ts
index 09763e148e2..22ae6e559c2 100644
--- a/src/renderer/src/components/editor/editor-autosave-controller.ts
+++ b/src/renderer/src/components/editor/editor-autosave-controller.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: autosave owns the save queue, quiesce
-coordination, and dirty-file shutdown hooks; keeping those lifecycles together
-avoids split-brain saves across visible and hidden editors. */
+/* eslint-disable max-lines -- Why: keeping the save queue, quiesce coordination, and dirty-file shutdown hooks together avoids split-brain saves. */
 import type { StoreApi } from 'zustand'
 import type { AppState } from '@/store'
 import type { OpenFile } from '@/store/slices/editor'
@@ -89,15 +87,12 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
           return
         }
 
-        // Why: hard no-op for read-only tabs (AI Vault View Log) even if a stray
-        // user/autosave save reached the queue — the integrity invariant is that
-        // View Log never writes the agent-owned artifact through editor paths.
+        // Why: read-only tabs (AI Vault View Log) must never write the agent-owned artifact through editor paths.
         if (liveFile.readOnly === true) {
           return
         }
 
-        // Why: explicit user saves proceed even while suspended (the banner
-        // warned) and clear both suspension flags below.
+        // Why: only autosave is blocked while suspended; explicit user saves proceed (the banner warned).
         if (trigger === 'autosave' && isAutosaveSuspendedForFile(liveFile)) {
           return
         }
@@ -108,11 +103,7 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
         const worktree = liveFile.worktreeId
           ? findWorktreeById(state.worktreesByRepo ?? {}, liveFile.worktreeId)
           : null
-        // Why: stamp before the write so the fs:changed event that our own
-        // write produces is ignored by useEditorExternalWatch instead of
-        // round-tripping back into a setContent that jumps the cursor to the
-        // end (and, under round-trip drift, can drop keystrokes typed in the
-        // debounce window). See editor-self-write-registry.
+        // Why: stamp before writing so useEditorExternalWatch ignores our own fs:changed echo (editor-self-write-registry).
         recordSelfWrite(
           liveFile.filePath,
           contentToSave,
@@ -133,9 +124,7 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
             contentToSave
           )
         } catch (error) {
-          // Why: the self-write stamp is only valid if a disk write actually
-          // happened. Clearing it on failure keeps the external watcher from
-          // suppressing a real third-party update that lands during the TTL.
+          // Why: the self-write stamp is only valid after a real write; clear on failure so it can't suppress a real update.
           clearSelfWrite(liveFile.filePath, liveFile.runtimeEnvironmentId)
           throw error
         }
@@ -151,16 +140,10 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
         if (!stillDirty) {
           nextState.clearEditorDraft(file.id)
         }
-        // Why: disk now holds contentToSave — future edits baseline on it, and
-        // a restore must not flag our own save as an external change. An
-        // explicit save also settles any pending baseline verification: the
-        // user chose to write, so there is nothing left to verify against.
+        // Why: disk now holds contentToSave — rebaseline so our own save isn't flagged external; drop pending verification.
         nextState.setLastKnownDiskSignature(file.id, getDiskBaselineSignature(contentToSave))
         nextState.clearPendingDiskBaselineVerification(file.id)
-        // Why: the write just made disk match the buffer, resolving any
-        // changed-on-disk conflict in favor of the user's content. The banner
-        // warned before this point; keeping the mark would show a stale
-        // conflict for a file that no longer diverges.
+        // Why: the write made disk match the buffer, so clear any now-stale changed-on-disk conflict.
         const savedFile = nextState.openFiles.find((openFile) => openFile.id === file.id)
         if (savedFile?.externalMutation === 'changed') {
           trackExternalChangeConflictAction(savedFile, 'save_overwrite')
@@ -185,9 +168,7 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
   }
 
   const quiesceFileSave = async (fileId: string): Promise<void> => {
-    // Why: rich markdown debounces serialization for typing performance, so a
-    // quiesce request must force any mounted editor to publish its pending
-    // draft before we cancel timers for rename/delete/discard flows.
+    // Why: rich markdown debounces serialization, so force the pending draft out before we cancel timers.
     flushPendingEditorChange(fileId)
     const pendingSave = saveQueue.get(fileId)
     clearAutoSaveTimer(fileId)
@@ -196,10 +177,7 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
   }
 
   const getLatestWritableContent = (file: OpenFile): string | null => {
-    // Why: only explicit user edits mark a tab dirty, and those edits are
-    // mirrored into editorDrafts on each change. The headless autosave
-    // controller deliberately depends on that narrow draft state instead of
-    // keeping the full editor UI mounted just to read component-local buffers.
+    // Why: headless controller reads editorDrafts rather than mounting the editor UI to read component-local buffers.
     return store.getState().editorDrafts[file.id] ?? null
   }
 
@@ -215,8 +193,7 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
         file &&
         file.isDirty &&
         canAutoSaveOpenFile(file) &&
-        // Why: suspension holds until the user picks a side via the banner
-        // (or saves manually) — see the queueSave guard.
+        // Why: suspension holds until the user picks a side via the banner (or saves manually).
         !isAutosaveSuspendedForFile(file) &&
         draft !== undefined
       if (!shouldKeepTimer) {
@@ -278,10 +255,7 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
 
       const duplicateDirtySavePaths = getDuplicateDirtySavePaths(dirtyFiles)
       if (duplicateDirtySavePaths.length > 0) {
-        // Why: a hidden autosave controller still has to respect that edit tabs
-        // and unstaged diff tabs may point at the same path while holding
-        // different drafts. Refusing the restart is safer than choosing a
-        // winner implicitly and persisting whichever save races last.
+        // Why: edit and diff tabs can share a path with different drafts; refuse rather than race an implicit winner.
         detail.reject(
           'Some unsaved files are open in multiple dirty tabs. Save them manually before restarting.'
         )
@@ -420,17 +394,11 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
       return
     }
 
-    // Why: dirty files must keep their draft — destroying unsaved edits on an
-    // external write is the data-loss half of issue #7265. Mark them
-    // changed-on-disk instead (backstop for tabs that became dirty during the
-    // notify debounce; the watch hook marks the ones dirty at event time).
+    // Why: keep dirty drafts on external writes (data-loss half of #7265); mark changed-on-disk as backstop for tabs turned dirty during the notify debounce.
     const reloadingFiles = matchingFiles.filter((file) => !file.isDirty)
     for (const file of matchingFiles) {
       if (file.isDirty) {
-        // Why: the self-write check keeps this backstop from marking on the
-        // echo of Orca's own save (the combined-Changes reload notification
-        // routes through here and would otherwise bypass the watch hook's
-        // echo verification).
+        // Why: skip Orca's own-save echo, which routes here bypassing the watch hook's echo verification.
         if (!hasRecentSelfWrite(file.filePath, file.runtimeEnvironmentId)) {
           markFileChangedOnDisk(state, file, {
             connectionId: getConnectionIdForFile(file.worktreeId, file.filePath) ?? undefined,
@@ -442,8 +410,7 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
       clearAutoSaveTimer(file.id)
       bumpSaveGeneration(file.id)
       state.markFileDirty(file.id, false)
-      // Why: this file is about to reload fresh disk content, so a stale
-      // changed-on-disk mark (set while it was dirty) is resolved.
+      // Why: about to reload fresh disk content, so a stale changed-on-disk mark is resolved.
       if (file.externalMutation === 'changed') {
         state.setExternalMutation(file.id, null)
       }
@@ -451,9 +418,7 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
     state.clearEditorDrafts(reloadingFiles.map((file) => file.id))
   }
 
-  // Why: the root store subscriber fires for every terminal title/focus tick.
-  // Autosave only reads these four inputs, so skip the open-files scan when
-  // unrelated store slices change.
+  // Why: the root subscriber fires on every store tick; skip the scan unless the four autosave inputs changed.
   let previousAutosaveInputs = getAutosaveSubscriberInputs(store.getState())
   const unsubscribe = store.subscribe(() => {
     const nextAutosaveInputs = getAutosaveSubscriberInputs(store.getState())
diff --git a/src/renderer/src/components/editor/editor-restored-tab-conflict-scan.ts b/src/renderer/src/components/editor/editor-restored-tab-conflict-scan.ts
index 26d7e4db0ca..ce0623e290d 100644
--- a/src/renderer/src/components/editor/editor-restored-tab-conflict-scan.ts
+++ b/src/renderer/src/components/editor/editor-restored-tab-conflict-scan.ts
@@ -1,13 +1,4 @@
-// Why: a dirty tab restored from a workspace session carries edits based on
-// disk content that may have changed while the app was closed (an agent write,
-// a sync tool). The in-memory changed-on-disk mark does not survive restarts,
-// so without this scan a resumed autosave would silently overwrite that newer
-// content (issue #7265 follow-up). The scan re-derives the conflict from
-// ground truth: it reads each restored dirty tab's file and compares the disk
-// signature against the persisted edit baseline. Autosave is hard-suspended
-// for those tabs (pendingDiskBaselineVerification, set at hydration) until a
-// verification resolves — otherwise the read would merely race the autosave
-// timer and a slow remote read would lose.
+// Why: a restored dirty tab's changed-on-disk mark doesn't survive restarts (issue #7265), so re-derive the conflict from disk — else a resumed autosave silently overwrites newer content; autosave stays suspended (pendingDiskBaselineVerification) until verification resolves.
 import type { StoreApi } from 'zustand'
 import type { AppState } from '@/store'
 import type { OpenFile } from '@/store/slices/editor'
@@ -20,38 +11,24 @@ import { markFileChangedOnDisk } from './editor-changed-on-disk-mark'
 
 type AppStoreApi = Pick<StoreApi<AppState>, 'getState' | 'subscribe'>
 
-// Why: SSH/runtime reads fail while the connection is still coming up after
-// launch. Retry fast for the first minute, then keep probing slowly —
-// giving up on a transport error would either strand the tab's autosave
-// suspension or lift it unverified right as the transport comes back up.
-// Only a definitive not-found (file deleted while the app was closed) ends
-// the loop early; see probeFileMissing.
+// Retry fast then slow: reads fail while SSH/runtime transport is still coming up; giving up would strand autosave suspension.
 const VERIFY_RETRY_MS = 2_000
 const VERIFY_SLOW_RETRY_MS = 15_000
 const VERIFY_FAST_ATTEMPTS = 30
-// Why: a session restored with many dirty tabs would otherwise fire one disk
-// read per tab simultaneously — on SSH/remote runtimes that's N concurrent
-// 15s-timeout RPCs competing with connection recovery at startup. Verifies
-// beyond the cap queue and start as slots free up; none are dropped.
+// Cap concurrent reads: many restored dirty tabs would otherwise fire N concurrent 15s RPCs competing with startup connection recovery.
 const MAX_CONCURRENT_VERIFY_READS = 3
 
 export function attachRestoredTabConflictScan(store: AppStoreApi): () => void {
-  // Why: dedupes queued + in-flight verifications; the store's pending flag is
-  // the durable "needs verification" signal.
+  // Dedupes queued + in-flight verifications; the store's pending flag is the durable "needs verification" signal.
   const inFlightFileIds = new Set<string>()
   const attemptsByFileId = new Map<string, number>()
   const retryTimers = new Set<ReturnType<typeof setTimeout>>()
-  // Why: queue ids, not OpenFile snapshots. Ids are paths, so a snapshot can go
-  // stale (close/reopen or save at the same path) while it waits for a slot;
-  // the live file is re-read at dispatch instead.
+  // Queue ids, not OpenFile snapshots: a snapshot can go stale (close/reopen or same-path save) while it waits for a slot.
   const verifyQueue: string[] = []
   let activeVerifyReads = 0
   let disposed = false
 
-  // Why: distinguishes "file was deleted while the app was closed" (a
-  // definitive not-found) from a transport still coming up. Only local/SSH
-  // paths can be probed — for runtime-owned files window.api.fs would stat
-  // the client-local path and misreport a remote file as gone.
+  // Only local/SSH paths can be probed: for runtime-owned files window.api.fs would stat the client path and misreport it as gone.
   const probeFileMissing = async (file: OpenFile): Promise<boolean> => {
     const settings = settingsForRuntimeOwner(store.getState().settings, file.runtimeEnvironmentId)
     if (settings?.activeRuntimeEnvironmentId?.trim()) {
@@ -70,9 +47,7 @@ export function attachRestoredTabConflictScan(store: AppStoreApi): () => void {
   }
 
   const verify = async (file: OpenFile): Promise<void> => {
-    // Why: OpenFile ids are file paths — a marker left behind by an early
-    // exit would silently skip every future verification of a reopened
-    // same-path tab. Only a scheduled retry may keep the marker set.
+    // ids are file paths: a stray leftover marker would skip a reopened same-path tab, so only a scheduled retry keeps it set.
     let retryScheduled = false
     try {
       const state = store.getState()
@@ -90,9 +65,7 @@ export function attachRestoredTabConflictScan(store: AppStoreApi): () => void {
       if (!liveFile) {
         return
       }
-      // Why: verification resolved — lift the autosave suspension regardless
-      // of outcome. If a save raced the read, the save already re-baselined
-      // and cleared the flag itself; wasPending distinguishes that case.
+      // Verification resolved: lift autosave suspension regardless of outcome; wasPending flags a save that already re-baselined.
       const wasPending = liveFile.pendingDiskBaselineVerification === true
       store.getState().clearPendingDiskBaselineVerification(file.id)
       if (
@@ -117,10 +90,7 @@ export function attachRestoredTabConflictScan(store: AppStoreApi): () => void {
         if (disposed) {
           return
         }
-        // Why: a definitive not-found IS ground truth — there is no newer
-        // disk content for a save to clobber, so verification is resolved.
-        // Converge to the live delete affordance (tombstone mark) instead of
-        // retrying forever with the tab's autosave silently suspended.
+        // Definitive not-found = resolved: no newer disk content for a save to clobber, so mark deleted instead of retrying forever.
         const liveFile = store.getState().openFiles.find((f) => f.id === file.id)
         if (!liveFile) {
           return
@@ -157,10 +127,7 @@ export function attachRestoredTabConflictScan(store: AppStoreApi): () => void {
   const pumpVerifyQueue = (): void => {
     while (!disposed && activeVerifyReads < MAX_CONCURRENT_VERIFY_READS && verifyQueue.length > 0) {
       const fileId = verifyQueue.shift()!
-      // Why: re-read the live file when the slot opens. A queued id may now
-      // resolve to a reopened or saved same-path tab, so re-validate it against
-      // the current state before spending a disk read; skipping frees the dedupe
-      // marker so a later scan can re-queue it if it needs verification again.
+      // Re-read live file: a queued id may now be a reopened/saved same-path tab; re-validate before a disk read, and skipping frees the dedupe marker so a later scan can re-queue it.
       const file = store.getState().openFiles.find((f) => f.id === fileId)
       if (
         !file ||
@@ -178,8 +145,7 @@ export function attachRestoredTabConflictScan(store: AppStoreApi): () => void {
         activeVerifyReads -= 1
         pumpVerifyQueue()
       }
-      // Why: verify() never rejects by design, but a rejection here must still
-      // release the slot or the queue stalls permanently.
+      // verify() never rejects, but a stray rejection must still free the slot or the queue stalls.
       void verify(file).then(onSettled, onSettled)
     }
   }
diff --git a/src/renderer/src/components/editor/rich-markdown-source-reconcile.ts b/src/renderer/src/components/editor/rich-markdown-source-reconcile.ts
index a1bdf3997a9..d568535b782 100644
--- a/src/renderer/src/components/editor/rich-markdown-source-reconcile.ts
+++ b/src/renderer/src/components/editor/rich-markdown-source-reconcile.ts
@@ -6,17 +6,10 @@ import {
   makePatches
 } from '@sanity/diff-match-patch'
 
-// Why: bound the safety re-parse cost — it builds a throwaway TipTap editor per
-// commit, whose parse time scales with document length (UTF-16 code units, the
-// unit `.length` returns and the closest cheap proxy for parse cost — not UTF-8
-// bytes). Measured ~50-67ms at the cap on fast HW (higher on low-end/SSH), under
-// the 300ms serialize debounce; a higher cap risks a main-thread stall on
-// slow/SSH hosts. Above the cap we use today's canonical output (no regression).
+// Why: cap document size in UTF-16 code units (`.length`) since re-parse cost scales with length — the per-commit throwaway TipTap safety re-parse (~50-67ms here) must stay under the 300ms serialize debounce so it can't stall the main thread on slow/SSH hosts.
 const RECONCILE_SIZE_CAP_CODE_UNITS = 50_000
 
-// Why: diff-match-patch defaults to a one-second search, which freezes the
-// renderer on replacement-heavy paste/edit paths. A timed-out coarse diff is
-// still safe because the round-trip proof below rejects any bad placement.
+// Why: dmp's default 1s search freezes the renderer on replacement-heavy paths; a coarse timed-out diff is safe since the round-trip proof below rejects bad placements.
 const RECONCILE_DIFF_TIMEOUT_SECONDS = 0.01
 
 export type ReconcileSerializedMarkdownParams = {
@@ -27,18 +20,15 @@ export type ReconcileSerializedMarkdownParams = {
   /** Canonical serialization after the user's edit (getMarkdown, always LF). */
   edited: string
   /**
-   * Re-serializes reconciled bytes through the live editor's pipeline. Injected
-   * so the reconcile logic is unit-testable without a DOM. Returns null when the
-   * throwaway serializer fails (treated as a safety mismatch → canonical fallback).
+   * Re-serializes reconciled bytes through the live editor's pipeline; injected so the reconcile logic is unit-testable without a DOM.
+   * Returns null when the throwaway serializer fails (treated as a safety mismatch → canonical fallback).
    */
   roundTrip: (markdown: string) => string | null
 }
 
 /**
- * Carries the user's edit into the original source style so untouched regions
- * keep their non-canonical bytes. Falls back to the canonical `edited` output
- * (today's behavior) whenever the source-preserving transform cannot be proven
- * render-equivalent — so it can never corrupt or relocate content.
+ * Carries the user's edit into the original source style so untouched regions keep their non-canonical bytes.
+ * Falls back to canonical `edited` when the transform can't be proven render-equivalent, so it never corrupts or relocates content.
  */
 export function reconcileSerializedMarkdown({
   originalSource,
@@ -46,32 +36,18 @@ export function reconcileSerializedMarkdown({
   edited,
   roundTrip
 }: ReconcileSerializedMarkdownParams): string {
-  // Branch 1: no semantic change vs the unedited doc → preserve the original
-  // bytes verbatim (incl. trailing newline / EOL); zero disk churn.
+  // Branch 1: no semantic change vs the unedited doc → return the original bytes verbatim, zero disk churn.
   if (edited === baseCanonical) {
     return originalSource
   }
 
-  // Work in LF space: getMarkdown emits LF while `originalSource` may be CRLF, so
-  // patching LF-context hunks against raw CRLF would fuzzy-match poorly and mix
-  // endings. The detected EOL is restored on EVERY non-verbatim return below so a
-  // uniform-CRLF file never silently flips to LF, even on a canonical fallback.
+  // Work in LF space (getMarkdown emits LF, `originalSource` may be CRLF → CRLF fuzzy-matches poorly); restoreEol on every non-verbatim return keeps a uniform-CRLF file from silently flipping to LF.
   const eol = detectDominantEol(originalSource)
   const originalSourceLf = toLf(originalSource)
   const baseLf = toLf(baseCanonical)
   const editedLf = toLf(edited)
 
-  // Branch 2: the source body equals the canonical `edited` body apart from its
-  // EOL/trailing newlines, so nothing non-canonical remains to preserve. Skip the
-  // expensive safety re-parse and carry the source's EOL + trailing newline onto
-  // the edit. Two guards keep the re-parse skip provably drift-free:
-  //  - source trailing run ≤ 1 newline: a longer trailing-blank run can
-  //    materialize a spurious `&nbsp;` empty paragraph on reload when the edit
-  //    turns the EOF block into a paragraph;
-  //  - `edited` has no trailing newline: getMarkdown keeps a trailing `\n\n` for a
-  //    real trailing empty paragraph, so stripping it here would silently drop a
-  //    block the user added.
-  // Both cases (rare) defer to the branch-6-verified path below instead.
+  // Branch 2: source == edited except for EOL/trailing newlines → carry the source's EOL onto the edit and skip the re-parse; guards avoid a spurious `&nbsp;` paragraph and dropping a real trailing block.
   const originalTrailingNewlines = originalSourceLf.match(/\n+$/)?.[0] ?? ''
   if (
     originalTrailingNewlines.length <= 1 &&
@@ -90,9 +66,7 @@ export function reconcileSerializedMarkdown({
   }
 
   // Branch 4: run the divergent-base patch entirely in LF space.
-  // Why: the dependency's half-match accelerator ignores its diff deadline and
-  // can spend 100ms+ scanning repeated long seeds. Returning canonical is safer
-  // than entering that unbounded path for highly repetitive replacements.
+  // Why: dmp's half-match accelerator ignores the diff deadline (100ms+ on repeated seeds), so bail to canonical for highly repetitive replacements.
   if (hasRepeatedHalfMatchSeed(baseLf, editedLf)) {
     return restoreEol(editedLf, eol)
   }
@@ -100,8 +74,7 @@ export function reconcileSerializedMarkdown({
     checkLines: true,
     timeout: RECONCILE_DIFF_TIMEOUT_SECONDS
   })
-  // Match makePatches(textA, textB)'s cleanup behavior while supplying the
-  // bounded diff ourselves instead of inheriting the library's 1s timeout.
+  // Match makePatches's cleanup while supplying our own bounded diff, avoiding the library's 1s timeout.
   if (diffs.length > 2) {
     diffs = cleanupSemantic(diffs)
     diffs = cleanupEfficiency(diffs)
@@ -109,16 +82,12 @@ export function reconcileSerializedMarkdown({
   const patches = makePatches(baseLf, diffs)
   const [reconciledLf, results] = applyPatches(patches, originalSourceLf)
 
-  // Branch 5: a hunk that failed to locate in the non-canonical source → the
-  // fuzzy match is unreliable here, so fall back to canonical.
+  // Branch 5: a hunk failed to locate in the non-canonical source → unreliable fuzzy match, fall back to canonical.
   if (results.some((applied) => !applied)) {
     return restoreEol(editedLf, eol)
   }
 
-  // Branch 6: prove the reconciled bytes render-equal the editor's document.
-  // Any fuzzy misplacement (e.g. onto a repeated substring) changes canonical
-  // output and is caught here → canonical fallback. Compared under norm so only
-  // style/EOL/EOF differences are tolerated.
+  // Branch 6: prove reconciled bytes render-equal the editor's document — any fuzzy misplacement changes canonical output and is caught here → canonical fallback.
   const reparsed = roundTrip(reconciledLf)
   if (reparsed === null || normalizeForSafety(reparsed) !== normalizeForSafety(editedLf)) {
     return restoreEol(editedLf, eol)
@@ -149,16 +118,12 @@ function restoreEol(lfText: string, eol: '\n' | '\r\n'): string {
 }
 
 function normalizeForSafety(text: string): string {
-  // Why: both operands are canonical getMarkdown outputs, so an equal-render
-  // reconciliation is byte-identical here apart from EOL. Compare exactly (only
-  // CRLF-normalized) — a trailing `\n\n` empty paragraph is semantic, so a lenient
-  // trimEnd would mask exactly the trailing-block drift branch 6 must catch.
+  // Why: compare exactly (only CRLF-normalized) — a trailing `\n\n` empty paragraph is semantic, so a lenient trimEnd would mask the trailing-block drift branch 6 must catch.
   return text.replace(/\r\n/g, '\n')
 }
 
 function hasRepeatedHalfMatchSeed(textA: string, textB: string): boolean {
-  // Match diff-match-patch's own prefix/suffix trimming so a small edit in a
-  // repetitive document is not mistaken for a repetitive replacement.
+  // Match diff-match-patch's prefix/suffix trimming so a small edit isn't mistaken for a repetitive replacement.
   const minimumLength = Math.min(textA.length, textB.length)
   let prefixLength = 0
   while (
diff --git a/src/renderer/src/components/github-project/ProjectViewWrapper.tsx b/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
index 09578f05c2f..a4ced82fb0c 100644
--- a/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
+++ b/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
@@ -1,7 +1,5 @@
 /* eslint-disable max-lines -- Why: top-level Project-mode container coordinates picker, view selection, query overrides, fetch lifecycle, and toolbar interactions; splitting these would fragment shared state. */
-// Why: top-level container for Project mode. Handles the picker, header,
-// filter label, count pill, Open-in-GitHub, and all Interaction States
-// documented in the design doc.
+// Top-level Project-mode container; interaction states per the design doc.
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import {
   ExternalLink,
@@ -116,22 +114,12 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
   const [parentDroppedToasted, setParentDroppedToasted] = useState<ReadonlySet<string>>(
     () => new Set()
   )
-  // Why: cache the project's view list per active project so the tab strip
-  // renders without flicker on re-renders and survives view switches without
-  // refetching. Keyed by `ownerType:owner:number`.
+  // Why: cache view list per project so the tab strip doesn't flicker/refetch on re-render; keyed `ownerType:owner:number`.
   const [viewListByProject, setViewListByProject] = useState<
     Record<string, GitHubProjectViewSummary[]>
   >({})
 
-  // Why: ephemeral search override, scoped to (project, view). Mirrors GitHub
-  // Projects' search box — pre-populated from `selectedView.filter`, applied
-  // on Enter/blur, cleared with the X button. The override is NEVER persisted
-  // to settings or to GitHub (per design doc §"Out of scope" line 36); a tab
-  // switch or refresh resets to the view's stored filter. Keyed by
-  // `ownerType:owner:number:viewId`. `undefined` (entry missing) means
-  // "use the view's filter as-is" so the cache key collapses to the
-  // unfiltered cache entry. The transient input string lives inside
-  // `ProjectSearchInput` so typing does not re-render the table.
+  // Why: ephemeral per-(project,view) search override, never persisted (design doc §"Out of scope"); `undefined` = use the view's filter as-is.
   const [appliedQueryByView, setAppliedQueryByView] = useState<Record<string, string>>({})
 
   const doFetch = useCallback(
@@ -158,8 +146,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
           setError({ error: res.error, totalCount: res.totalCount })
         }
       } finally {
-        // Why: a manual refresh can overlap with a tab/search fetch; an older
-        // request finishing first must not clear the newer refresh indicator.
+        // Why: an older overlapping fetch finishing first must not clear a newer refresh's loading indicator.
         if (mountedRef.current && fetchRunIdRef.current === runId) {
           setLoading(false)
         }
@@ -217,9 +204,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
     projectViewSourceScope
   ])
 
-  // Load the project's view list whenever the active project changes so the
-  // tab strip can render. The list is small and rarely changes — fetched once
-  // per project per session is fine.
+  // Load the view list once per project per session (small, rarely changes) so the tab strip can render.
   useEffect(() => {
     if (!activeProject) {
       return
@@ -248,8 +233,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
         if (cancelled) {
           return
         }
-        // Why: an IPC rejection here would surface as an unhandled rejection
-        // and dev-tools red — log and fall back to the empty-tabs UI.
+        // Why: swallow the IPC rejection (else unhandled/dev-tools red); fall back to the empty-tabs UI.
         console.warn('[project-view] listProjectViews threw:', err)
       })
     return () => {
@@ -267,11 +251,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
       if (current === viewId) {
         return
       }
-      // Persist the new view selection so reloads & the picker stay in sync.
-      // Why: read the freshest settings via getState() rather than the closure-
-      // captured `settings` — between callback creation and invocation another
-      // mutation (pin/recent update from elsewhere) may have landed, and the
-      // closure value would clobber it on write.
+      // Why: read freshest settings via getState() so a concurrent pin/recent mutation isn't clobbered on write.
       const freshSettings = useAppStore.getState().settings
       const prevSettings = freshSettings?.githubProjects ?? {
         pinned: [],
@@ -348,9 +328,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
     [table, slugIndexReady, lookupSlug, selectedRepoIds]
   )
   const lastFilteredTableRef = useRef<CachedVisibleProjectTable | null>(null)
-  // Why: this cache only prevents a blank table while the repo slug index
-  // rebuilds; a ref preserves the previous render value without scheduling
-  // a second render after every filtered-table change.
+  // Why: ref-cache prevents a blank table while the slug index rebuilds, without forcing a second render.
   lastFilteredTableRef.current = getNextVisibleProjectTableCache({
     currentCacheKey,
     selectedRepoFingerprint,
@@ -392,21 +370,14 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
     ? `${table.project.url}/views/${table.selectedView.number ?? ''}`
     : null
 
-  // ── Row action state ────────────────────────────────────────────────
-  // Why: when a row matches a registered repo, we open the full
-  // `GitHubItemDialog` in repo-backed mode; when it doesn't, we open the
-  // simplified slug-mode dialog. `repoNotInOrca` drives the fallback modal
-  // from the design doc's `repo-not-in-orca` interaction state.
+  // Why: matched-repo rows open `GitHubItemDialog`, unmatched the slug dialog; `repoNotInOrca` drives the `repo-not-in-orca` modal.
   const [dialogRepoItem, setDialogRepoItem] = useState<{
     workItem: GitHubWorkItem
     repoPath: string
     repoId: string
     origin: GitHubItemDialogProjectOrigin
   } | null>(null)
-  // Why: the slug dialog is only opened for rows whose repo isn't registered
-  // in Orca (matched repos go through the full GitHubItemDialog above), so
-  // there's no `matchedRepo` to track here. The repo-not-in-orca modal —
-  // owned by this parent, not the slug dialog — handles "Start work".
+  // Why: slug dialog only serves unregistered-repo rows; the parent (not this dialog) owns the repo-not-in-orca "Start work" flow.
   const [slugDialog, setSlugDialog] = useState<{
     origin: GitHubItemDialogProjectOrigin
   } | null>(null)
@@ -423,8 +394,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
     selectedRepoIds
   )
   if (resolvedDialogRepoItem !== dialogRepoItem) {
-    // Why: repo-backed Project dialogs cannot edit after their repo leaves
-    // Orca; clear them before the modal tree receives stale repo ids.
+    // Why: clear the repo-backed dialog when its repo leaves Orca, before the modal tree gets stale repo ids.
     setDialogRepoItem(resolvedDialogRepoItem)
   }
   const resolvedDialogRepo = resolvedDialogRepoItem
@@ -446,8 +416,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
     selectedRepoIds
   })
   if (resolvedMissingRepoDialogs.slugDialog !== slugDialog) {
-    // Why: once a previously missing repo is registered, Project rows should
-    // use the full repo-backed dialog instead of the slug fallback.
+    // Why: once a missing repo is registered, rows switch to the full repo-backed dialog, not the slug fallback.
     setSlugDialog(resolvedMissingRepoDialogs.slugDialog)
   }
   if (resolvedMissingRepoDialogs.repoNotInOrca !== repoNotInOrca) {
@@ -659,18 +628,14 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
       if (!workItem) {
         return
       }
-      // Why: issue #4756 changes the TaskPage "Create workspace" path only.
-      // Project view still means "start work now", so it stays on direct launch.
+      // Why: issue #4756 changed only TaskPage's "Create workspace"; Project view stays on direct "start work now" launch.
       void launchWorkItemDirect({
         item: workItem,
         repoId: resolution.repo.id,
         launchSource: 'task_page',
         telemetrySource: 'sidebar',
         openModalFallback: () => {
-          // Why: Project mode does not own the new-workspace composer modal.
-          // When `launchWorkItemDirect` wants user input (setupRunPolicy:'ask'
-          // or agent detection fails), fall back to opening the URL so the
-          // user keeps a path forward rather than a silent no-op.
+          // Why: Project mode lacks the new-workspace composer, so when launch needs user input, open the URL instead of a silent no-op.
           if (row.content.url) {
             void window.api.shell.openUrl(row.content.url)
           }
@@ -777,11 +742,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
           onSelect={handleSelect}
         />
         {currentProjectViewKey ? (
-          // Why: render the search input whenever a view is selected — even
-          // while a refetch is in flight and `table` has briefly cleared for
-          // the new cache key. Hiding the search box mid-search would make
-          // it look like the search vanished. `key` keeps the local input
-          // state stable across (project, view) changes only.
+          // Why: keep search box mounted through refetches so it doesn't vanish; `key` resets input per (project, view).
           <ProjectSearchInput
             key={currentProjectViewKey}
             viewFilter={table?.selectedView.filter ?? ''}
@@ -804,9 +765,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
                 }
                 return next
               })
-              // Why: force-fetch on user-initiated apply so the same
-              // query re-typed (or cache-stale entries within TTL) does
-              // not silently no-op.
+              // Why: force-fetch on user apply so a re-typed or TTL-cached query doesn't silently no-op.
               void doFetch(
                 {
                   owner: activeProject.owner,
@@ -943,8 +902,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
           onUse={(item) => {
             const current = resolvedDialogRepoItem
             setDialogRepoItem(null)
-            // Why: issue #4756 keeps project-view actions on the direct
-            // "start work now" path instead of the TaskPage background-create flow.
+            // Why: issue #4756 keeps project-view actions on the direct "start work now" path, not the TaskPage background-create flow.
             void launchWorkItemDirect({
               item,
               repoId: current.workItem.repoId,
@@ -977,11 +935,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
         />
       ) : null}
 
-      {/* Slug-only simplified dialog for rows whose repo isn't added to Orca.
-          Why: no Start-work affordance lives inside the slug dialog — the
-          parent's `handleStartWork`/`repoNotInOrca` modal owns that flow, so
-          having a duplicate (always-disabled or always-routing-to-fallback)
-          button here would only confuse the user. */}
+      {/* Slug-only dialog for unadded-repo rows; Start-work lives in the parent's `repoNotInOrca` modal, not here (avoids a confusing duplicate button). */}
       <ProjectItemSlugDialog
         projectOrigin={resolvedMissingRepoDialogs.slugDialog?.origin ?? null}
         sourceSettings={settings}
@@ -1036,11 +990,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
             ) : null}
             <Button
               onClick={async () => {
-                // Why: `addRepo` opens the OS folder picker — it's the only
-                // non-destructive way to register a repo today. Auto-cloning
-                // from a row click is out of v1 scope (design doc §Row
-                // actions). Close the modal regardless so the user isn't
-                // trapped if they cancel the picker.
+                // Why: `addRepo` opens the OS folder picker (auto-clone is out of v1 scope); close the modal regardless so a cancelled picker doesn't trap the user.
                 setRepoNotInOrca(null)
                 await addRepoFromStore()
               }}
@@ -1057,11 +1007,7 @@ export default function ProjectViewWrapper({ selectedRepoIds }: Props): React.JS
   )
 }
 
-// Why: owns the transient search input string locally so typing does not
-// re-render the parent (and therefore not the table). The parent only learns
-// the value when the user applies it (Enter/blur/clear), which is the only
-// moment that should trigger a refetch. Pre-populated from the view's stored
-// filter and remounted (via `key`) when the active project/view changes.
+// Why: keeps the input string local so typing doesn't re-render the parent/table; the parent only learns it on apply (Enter/blur/clear).
 function ProjectSearchInput({
   viewFilter,
   appliedOverride,
@@ -1078,8 +1024,7 @@ function ProjectSearchInput({
   const dirty = value !== applied
 
   const apply = (next: string): void => {
-    // Why: when the user reverts to the view's stored filter, drop the
-    // override so the cache key collapses back onto the unfiltered entry.
+    // Why: reverting to the view's stored filter drops the override so the cache key collapses to the unfiltered entry.
     onApply(next === viewFilter ? undefined : next)
   }
 
@@ -1195,10 +1140,7 @@ function ViewTabStrip({
   activeViewId: string | null
   onPick: (viewId: string) => void
 }): React.JSX.Element {
-  // Why: emulate GitHub Projects' tab strip — pill-shaped active tab with
-  // layout icon, sitting on a muted base bar with a bottom border. Inactive
-  // tabs are flat text; active gets a card background + outline. Disabled
-  // (non-table) layouts stay visible at low opacity.
+  // Why: emulate GitHub Projects' tab strip; non-table layouts stay visible but disabled.
   return (
     <div className="project-view-tab-strip flex min-h-[41px] min-w-0 flex-none items-end gap-1 overflow-x-auto overflow-y-hidden border-b border-border/50 bg-muted/20 px-3 pt-3">
       {views.map((v) => {
@@ -1302,9 +1244,7 @@ function ErrorState({
   totalCount?: number
   onOpenInGitHub: () => void
 }): React.JSX.Element {
-  // Auth/scope errors get a richer remediation UI driven by `gh auth
-  // status`. Bail early so the generic `command`/`copy` block below is
-  // only computed for non-auth error types.
+  // Auth/scope errors get a richer `gh auth status` remediation UI; bail early before the generic block.
   if (error.type === 'auth_required' || error.type === 'scope_missing') {
     return (
       <div className="flex flex-1 flex-col items-start gap-3 p-6 text-sm">
@@ -1347,9 +1287,7 @@ function ErrorState({
   )
 }
 
-// Why: matches the shape of ProjectViewList's header + rows so the table
-// doesn't visibly jump in height when real data lands. A 12-row stub fills
-// a typical viewport at the table's min-h-10 row height.
+// Why: mirror ProjectViewList's header + 12 rows so the table doesn't jump in height when real data lands.
 function ProjectTableSkeleton(): React.JSX.Element {
   const headerCols = 6
   const bodyCols = 5
diff --git a/src/renderer/src/components/native-chat/use-native-chat-live-session.ts b/src/renderer/src/components/native-chat/use-native-chat-live-session.ts
index 74a4d12b6c3..d742e426fe9 100644
--- a/src/renderer/src/components/native-chat/use-native-chat-live-session.ts
+++ b/src/renderer/src/components/native-chat/use-native-chat-live-session.ts
@@ -31,14 +31,11 @@ export type UseNativeChatLiveSessionArgs = {
   /** Composite `${tabId}:${leafId}` key — selects the live hook entry. */
   paneKey: string
   agent: AgentType
-  /** The agent's own session id, or null before the agent has reported one.
-   *  With null there is nothing to read/tail; the view shows live hook state. */
+  /** The agent's own session id, or null before it reports one — nothing to read/tail, so the view shows live hook state. */
   sessionId: string | null
-  /** Authoritative transcript path from the hook (providerSession), preferred
-   *  over reconstructing the path from sessionId. Null when not reported. */
+  /** Authoritative transcript path from the hook, preferred over reconstructing it from sessionId. Null when not reported. */
   transcriptPath?: string | null
-  /** Runtime owner of the pane (Model B). Non-null routes read/subscribe to the
-   *  remote runtime host; null/undefined keeps the local IPC path. */
+  /** Runtime owner (Model B): non-null routes read/subscribe to the remote host; null keeps the local IPC path. */
   runtimeEnvironmentId?: string | null
 }
 
@@ -55,9 +52,7 @@ export type NativeChatLiveSession = NativeChatSession & {
 // Stable empty-base reference so a non-ready read doesn't churn the base axis.
 const EMPTY_MESSAGES: readonly NativeChatMessage[] = []
 
-/** True when `whole`'s first `len` entries are referentially identical to
- *  `prefix` — i.e. `whole` is `prefix` extended at the tail, so the incremental
- *  assembler can splice just the suffix instead of resetting. */
+/** True when `whole`'s first `len` entries are referentially identical to `prefix` (a tail-extension), so the assembler can splice just the suffix. */
 function sharesPrefix(
   whole: readonly NativeChatMessage[],
   prefix: readonly NativeChatMessage[],
@@ -78,9 +73,7 @@ function nextSubscriptionId(): string {
   return `native-chat-${subscriptionCounter}-${Date.now()}`
 }
 
-// Why: a brand-new session's transcript can take seconds to minutes to appear
-// on disk (#8401), so a `notFound` miss retries — 1s/2s/4s/8s then every 10s —
-// until the window below elapses.
+// Why: a new session's transcript can take minutes to appear on disk (#8401); a `notFound` miss retries with backoff until the window below elapses.
 const NOTFOUND_RETRY_DELAYS_MS = [1_000, 2_000, 4_000, 8_000]
 const NOTFOUND_RETRY_FIXED_DELAY_MS = 10_000
 const NOTFOUND_RETRY_WINDOW_MS = 60_000
@@ -95,33 +88,24 @@ type ReadState =
   | { phase: 'error'; error: string }
 
 /**
- * Renderer hook that streams a NativeChatSession for a pane: initial windowed
- * read via `nativeChat.readSession`, live tail via `nativeChat.subscribe`, merged
- * with the pane's live hook turn-state. IO + store reads live here; the merge
- * itself stays pure (mergeNativeChatLiveSession → assembleNativeChatSession).
+ * Renderer hook that streams a NativeChatSession for a pane: windowed
+ * `readSession` + live `subscribe` tail, merged with live hook turn-state.
  *
- * Pagination: the read is windowed to the most recent `limit` turns (default
- * NATIVE_CHAT_INITIAL_LIMIT). `loadEarlier` raises the limit by a page and
- * re-reads to prepend older history; `hasMore` reflects whether the last read
- * filled the window. Read results replace the base list (they are an ordered
- * tail), while live appends accumulate separately so a re-read never drops them.
+ * Pagination: read is windowed to the most recent `limit` turns; `loadEarlier`
+ * re-reads a larger window to prepend older history. Read results replace the
+ * base list; live appends accumulate separately so a re-read never drops them.
  *
- * Transport: IO goes through a per-owner session transport selected by
- * getNativeChatSessionTransport. A runtime-owned pane (Model B) reads/tails the
- * REMOTE runtime host via the runtime RPCs; local- and ssh-owned panes keep the
- * local IPC path. The transport preserves the NativeChatApi read/subscribe shape,
- * so everything below (merge, assembler, pagination) is unchanged.
+ * Transport: per-owner (getNativeChatSessionTransport) — a runtime-owned pane
+ * (Model B) reads/tails the remote host; local/ssh panes keep the local IPC path.
  *
- * Teardown: the subscription is closed on unmount and whenever the owner, agent,
- * or sessionId change, so a toggle back to terminal, a session swap, or an
- * owner-flip never leaks a watcher (remote or local).
+ * Teardown: subscription closes on unmount and on owner/agent/sessionId change so
+ * a swap or owner-flip never leaks a watcher.
  */
 export function useNativeChatLiveSession(
   args: UseNativeChatLiveSessionArgs
 ): NativeChatLiveSession {
   const { paneKey, agent, sessionId, transcriptPath, runtimeEnvironmentId } = args
-  // Stable per owner id, so a re-render without an owner flip keeps the same
-  // transport identity and doesn't re-subscribe.
+  // Stable per owner id so a re-render without an owner flip keeps the same transport and doesn't re-subscribe.
   const transport = useMemo(
     () => getNativeChatSessionTransport(runtimeEnvironmentId ?? null),
     [runtimeEnvironmentId]
@@ -133,44 +117,33 @@ export function useNativeChatLiveSession(
   // The active read window; raised by loadEarlier to page in older history.
   const limitRef = useRef(NATIVE_CHAT_INITIAL_LIMIT)
 
-  // Appended messages accumulate separately from the initial snapshot so pagination
-  // (session change or load-earlier) doesn't lose in-flight appends mid-swap;
-  // they reset with the same effect that re-subscribes. Live frames merge by id
-  // (re-emitted ids replace in place, no unbounded concat) and the bucket is
-  // capped to the read window so a long run can't grow it without limit (#6).
+  // Appended messages accumulate separately from the snapshot so pagination doesn't lose in-flight appends; merged by id and capped to the read window (#6).
   const [appended, setAppended] = useState<NativeChatMessage[]>([])
-  // Stateful id-dedup merger backing `appended`; caches the id→index map so each
-  // live frame costs O(incoming), not O(existing) (#18 parity for desktop).
+  // Id-dedup merger backing `appended`; caches the id→index map so each live frame costs O(incoming), not O(existing) (#18).
   const appendMergerRef = useRef(createNativeChatMerger(NATIVE_CHAT_SOURCE_PRIORITY))
 
   const [hookState, hookStateStartedAt, hookHasWorkingSubagents] = useNativeChatHookStatus(paneKey)
 
   const latestSessionId = useRef<string | null>(sessionId)
   latestSessionId.current = sessionId
-  // Tracks the current owner's transport so a load-earlier resolve from a prior
-  // host is discarded after an owner flip (the session id can stay the same).
+  // Tracks the current transport so a load-earlier resolve from a prior host is discarded after an owner flip (session id can stay the same).
   const latestTransport = useRef(transport)
   latestTransport.current = transport
   const transcriptEpochRef = useRef(0)
 
-  // Incremental assembler: reset on the base axis (session/agent/read swap),
-  // applyAppends on the hot append axis. `appliedTranscriptRef` is the exact
-  // array last fed; a pure suffix-extension takes the fast append path, anything
-  // else forces a reset so the cache never drifts from a full rebuild (#17).
+  // Incremental assembler: suffix-extensions take the fast append path, anything else resets so the cache can't drift from a full rebuild (#17).
   const assemblerRef = useRef(createIncrementalAssembler())
   const appliedTranscriptRef = useRef<readonly NativeChatMessage[]>([])
   const baseSigRef = useRef<string | null>(null)
   const baseMessagesRef = useRef<readonly NativeChatMessage[]>(EMPTY_MESSAGES)
 
   useEffect(() => {
-    // Why: agent/path/owner rebinds can keep the same session and transport;
-    // every source generation must invalidate pagination captured before it.
+    // Why: agent/path/owner rebinds can keep the same session; every source generation must invalidate pagination captured before it.
     transcriptEpochRef.current += 1
     setLoadingEarlier(false)
     transcriptLifecycleControl.reset()
     if (!sessionId) {
-      // No session id yet: nothing to read or tail. Surface live hook state on
-      // an empty transcript; backfills once the id arrives (effect re-runs).
+      // No session id yet: surface live hook state on an empty transcript; backfills once the id arrives.
       setRead({ phase: 'ready', messages: [] })
       replaceList(appendMergerRef.current, [])
       setAppended([])
@@ -179,14 +152,11 @@ export function useNativeChatLiveSession(
     }
 
     let cancelled = false
-    // Set by the first authoritative snapshot/replacement frame so the
-    // independent readSession seed below can never clobber a live snapshot.
+    // Set by the first authoritative frame so the readSession seed below can't clobber a live snapshot.
     let frameArrived = false
     let retryTimer: ReturnType<typeof setTimeout> | null = null
     const retryStartedAt = Date.now()
-    // Re-bound as a plain const: TS doesn't retain the `!sessionId` narrowing
-    // above inside a nested function declaration (it's hoisted, so the
-    // narrowing can't be proven to hold at every call site).
+    // Re-bound as a const: TS drops the `!sessionId` narrowing inside the hoisted nested function.
     const activeSessionId = sessionId
     limitRef.current = NATIVE_CHAT_INITIAL_LIMIT
     setRead({ phase: 'loading' })
@@ -194,11 +164,7 @@ export function useNativeChatLiveSession(
     setAppended([])
     setHasMore(false)
 
-    // Independent initial seed: the subscribe stream normally delivers the first
-    // snapshot, but a persistent initial-drain error, or an older runtime whose
-    // subscribe only wires onAppend, would otherwise strand the view at 'loading'
-    // forever. Apply this only while no authoritative frame has landed yet, so a
-    // live snapshot always wins and a late seed never repaints it.
+    // Independent initial seed in case subscribe never delivers a snapshot; applied only until an authoritative frame lands so a live snapshot wins.
     function loadSession(attempt: number): void {
       if (frameArrived) {
         return
@@ -210,8 +176,7 @@ export function useNativeChatLiveSession(
             return
           }
           if (result && 'error' in result) {
-            // A not-yet-flushed transcript: stay in 'loading' and retry with
-            // backoff instead of settling into a permanent error (#8401).
+            // A not-yet-flushed transcript: stay in 'loading' and retry with backoff instead of a permanent error (#8401).
             if (result.notFound && Date.now() - retryStartedAt < NOTFOUND_RETRY_WINDOW_MS) {
               retryTimer = setTimeout(() => {
                 retryTimer = null
@@ -248,8 +213,7 @@ export function useNativeChatLiveSession(
       (frame) => {
         if (!cancelled) {
           if (frame.type === 'snapshot' || frame.type === 'replacement') {
-            // Why: reconnect snapshots and inode replacements are both
-            // authoritative generations; older pagination must not repaint them.
+            // Why: snapshots and inode replacements are authoritative generations; older pagination must not repaint them.
             frameArrived = true
             transcriptEpochRef.current += 1
             setLoadingEarlier(false)
@@ -265,10 +229,7 @@ export function useNativeChatLiveSession(
             return
           }
           transcriptLifecycleControl.append(frame.lifecycle)
-          // Merge by id (re-emits replace in place) then bound to the window so
-          // the bucket can't grow without limit. The base read still holds older
-          // turns, and the assembler re-dedups the concat, so trimming the recent
-          // append tail can't drop a turn the base window still covers (#6).
+          // Merge by id then bound to the window; the base read + assembler re-dedup mean trimming the append tail can't drop a covered turn (#6).
           setAppended(applyAppend(appendMergerRef.current, frame.messages, limitRef.current))
         }
       }
@@ -280,10 +241,7 @@ export function useNativeChatLiveSession(
         clearTimeout(retryTimer)
         retryTimer = null
       }
-      // Desktop returns a sync unsubscribe fn; the web RPC bridge returns a
-      // Promise instead (and can't deliver streaming callbacks). Calling a
-      // Promise as a function crashed the whole chat view, so resolve it first
-      // and only call the result when it's actually a function.
+      // Web RPC bridge returns a Promise (not the desktop sync unsubscribe fn); calling it as a function crashed the view, so resolve first.
       const teardown = unsubscribe as unknown
       if (typeof teardown === 'function') {
         ;(teardown as () => void)()
@@ -295,8 +253,7 @@ export function useNativeChatLiveSession(
         })
       }
     }
-    // `transport` identity changes on an owner flip, re-running this effect to
-    // tear down the old host's subscription and open one against the new host.
+    // `transport` identity changes on an owner flip, re-running this effect to re-subscribe against the new host.
   }, [agent, sessionId, transcriptPath, transport, transcriptLifecycleControl])
 
   const loadEarlier = useCallback(() => {
@@ -310,8 +267,7 @@ export function useNativeChatLiveSession(
     void transport
       .readSession(agent, sessionId, nextLimit, transcriptPath ?? undefined)
       .then((result) => {
-        // Ignore a stale resolve from a session that swapped OR an owner that
-        // flipped underneath us — either would paint the wrong host's history.
+        // Ignore a stale resolve from a swapped session or flipped owner — either would paint the wrong host's history.
         if (
           latestSessionId.current !== sessionId ||
           latestTransport.current !== transport ||
@@ -323,21 +279,16 @@ export function useNativeChatLiveSession(
           return
         }
         limitRef.current = nextLimit
-        // Read results are an ordered tail — replace the base list so the older
-        // page prepends in order; live appends stay in their separate bucket.
+        // Read results are an ordered tail: replace the base list so the older page prepends in order; live appends stay separate.
         setRead({ phase: 'ready', messages: result.messages })
         transcriptLifecycleControl.replaceFromPagination(result.lifecycle, lifecycleRevision)
         setHasMore(hasMoreNativeChatHistory(result.messages.length, nextLimit))
       })
       .catch(() => {
-        // Swallow a rejected earlier-page read (the IPC-backed call can reject):
-        // it's a "load more" action, so failing should leave the already-loaded
-        // transcript intact rather than surface an unhandled rejection.
+        // Swallow a rejected "load more" read: keep the already-loaded transcript intact rather than surface the rejection.
       })
       .finally(() => {
-        // Always clear the loading flag — even after a session swap — so a stale
-        // resolve can't leave loadingEarlier stuck true on the new session. Only
-        // APPLYING the result above is gated on the session-id match.
+        // Clear the loading flag on the current epoch even when the result is discarded, so a stale resolve can't wedge it true.
         if (transcriptEpochRef.current === requestEpoch) {
           setLoadingEarlier(false)
         }
@@ -353,16 +304,12 @@ export function useNativeChatLiveSession(
     transcriptLifecycleControl
   ])
 
-  // Assembled messages reuse the incremental assembler across appends. Computed
-  // outside the status memo: hookState changes only the status override, not the
-  // message set, so hook churn never re-runs the assembler (perf note in design).
+  // Computed outside the status memo so hookState churn (status-only) never re-runs the assembler.
   const baseMessages = read.phase === 'ready' ? read.messages : EMPTY_MESSAGES
   const assembledMessages = useMemo(() => {
     const transcript =
       appended.length > 0 ? [...baseMessages, ...appended] : (baseMessages as NativeChatMessage[])
-    // Base axis: the read's message array reference changes on session swap and
-    // loadEarlier; sessionId/agent identify the conversation. Any change forces a
-    // full reset so a missed trigger can't leave the cache stale.
+    // Base-axis signature: any change forces a full assembler reset so a missed trigger can't leave the cache stale.
     const baseSig = `${agent}\u0000${sessionId ?? ''}`
     const baseChanged = baseSig !== baseSigRef.current || baseMessages !== baseMessagesRef.current
     const applied = appliedTranscriptRef.current
@@ -383,15 +330,11 @@ export function useNativeChatLiveSession(
     baseMessagesRef.current = baseMessages
     appliedTranscriptRef.current = transcript
     return out
-    // baseMessages + appended are the only message-set inputs; sessionId/agent
-    // gate the base-axis reset. hookState is intentionally excluded.
+    // baseMessages/appended are the only message-set inputs; sessionId/agent gate the reset. hookState intentionally excluded.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [baseMessages, appended, sessionId, agent])
 
-  // Why: Claude-family harnesses record slash inputs as command envelopes,
-  // which the noise filter hides. A skill invocation is the user's chat turn,
-  // so surface it here — upstream of pending-echo pruning, view state, and the
-  // list — as the literal token; catalog commands keep their `Ran /x` marker.
+  // Why: skill invocations are user turns but Claude records them as noise-filtered command envelopes, so surface them as the literal token here.
   const surfacedMessages = useMemo(
     () =>
       surfaceSkillInvocationUserTurns(
@@ -410,10 +353,7 @@ export function useNativeChatLiveSession(
       stateStartedAt: hookStateStartedAt,
       transcriptLifecycle,
       hookHasWorkingSubagents,
-      // Why: a watcher append (fix for #8401) can land content while the read is
-      // still retrying ('loading') or after it settled into 'error' — in both
-      // cases showing the live content beats a spinner or a stale error, so each
-      // override only applies while there is nothing appended to render.
+      // Why: show live watcher-append content over a spinner/stale error (#8401), so overrides apply only when nothing is appended.
       loading: read.phase === 'loading' && appended.length === 0,
       ...(read.phase === 'error' && appended.length === 0 ? { error: read.error } : {})
     })
diff --git a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
index 1e019b0e0d1..f2749139eac 100644
--- a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
+++ b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: the smart name field owns source tabs,
-search orchestration, and result rendering so the unified create flow stays
-in one predictable form control instead of splitting state across fragments. */
+/* eslint-disable max-lines -- Why: owns source tabs, search orchestration, and result rendering as one create-flow form control. */
 /* oxlint-disable react-doctor/no-adjust-state-on-prop-change -- Why: this component's existing reset effects need a dedicated refactor outside the Linear API compatibility change. */
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import {
@@ -94,8 +92,7 @@ type SmartWorkspaceNameFieldProps = {
   value: string
   onValueChange: (value: string) => void
   onGitHubItemSelect: (item: GitHubWorkItem) => void
-  /** Optional so callers that pre-date GitLab support don't need to wire
-   *  it. When omitted, GitLab paste-URL detection is silently skipped. */
+  /** Optional; when omitted, GitLab paste-URL detection is silently skipped. */
   onGitLabItemSelect?: (item: GitLabWorkItem) => void
   onBranchSelect: (refName: string, localBranchName: string) => void
   onLinearIssueSelect: (issue: LinearIssue) => void
@@ -180,8 +177,7 @@ export default function SmartWorkspaceNameField({
   crossRepoSwitchTarget = 'project',
   onActiveSourceModeChange
 }: SmartWorkspaceNameFieldProps): React.JSX.Element {
-  // Why: tab/filter labels use the lightweight translate() helper; subscribing
-  // here makes them refresh even when language changes don't remount the field.
+  // Why: subscribe so translate()-based tab/filter labels refresh on language change without a remount.
   useTranslation()
   const {
     addRepo,
@@ -311,9 +307,7 @@ export default function SmartWorkspaceNameField({
   const repoSlugCacheRef = useRef<Map<string, RepoSlug | null>>(new Map())
   const handledCrossRepoUrlRef = useRef<string | null>(null)
   const localInputFocusFrameRef = useRef<number | null>(null)
-  // Why: dialog autofocus and other programmatic .focus() calls can look
-  // user-initiated in Electron, so gate the source popover until the user
-  // actually interacts with this field or tabs from another composer control.
+  // Why: Electron makes programmatic .focus() look user-initiated, so gate the source popover until real interaction.
   const deferSourcePopoverUntilInteractionRef = useRef(true)
   const [crossRepoPrompt, setCrossRepoPrompt] = useState<{
     link: NonNullable<ReturnType<typeof parseGitHubIssueOrPRLink>>
@@ -398,8 +392,7 @@ export default function SmartWorkspaceNameField({
         return
       }
       focusedSelectedSourceKeyRef.current = selectedSourceFocusKey
-      // Why: after Enter accepts a source row, the input unmounts. Move focus
-      // to the pill immediately so the next Enter advances to Agent.
+      // Why: input unmounts after Enter accepts a row; move focus to the pill so the next Enter advances to Agent.
       node.focus({ preventScroll: true })
     },
     [selectedSourceFocusKey]
@@ -877,16 +870,11 @@ export default function SmartWorkspaceNameField({
     return () => {
       stale = true
     }
-    // Why: list/search actions are stable store methods; depending on them
-    // would refetch on unrelated store writes.
+    // Why: list/search are stable store methods; depending on them would refetch on unrelated store writes.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [debouncedQuery, disabled, linearSourceContext, linearStatus.connected, shouldQueryLinear])
 
-  // Why: GitLab paste-URL flow. Watches the debounced query for a GitLab
-  // issue/MR URL (parseGitLabIssueOrMRLink already filters non-GitLab URLs
-  // via the project-internal `/-/` separator) and resolves it to a
-  // GitLabWorkItem via the IPC. Skipped silently when the host hook
-  // hasn't supplied an onGitLabItemSelect handler.
+  // Why: GitLab paste-URL flow; parseGitLabIssueOrMRLink filters non-GitLab URLs via the project-internal `/-/` separator.
   const parsedGlLink = useMemo(
     () => (sourceQueryWithinLimit ? parseGitLabIssueOrMRLink(debouncedQuery) : null),
     [debouncedQuery, sourceQueryWithinLimit]
@@ -900,8 +888,7 @@ export default function SmartWorkspaceNameField({
     (mode === 'smart' || mode === 'gitlab')
   useEffect(() => {
     if (!shouldQueryGitlab || disabled || !onGitLabItemSelect) {
-      // Why: don't clobber list-mode items here — the listMRs effect below
-      // is the sole writer when the user is in 'gitlab' mode without a URL.
+      // Why: don't clobber list-mode items — the listMRs effect below is the sole writer in 'gitlab' mode without a URL.
       if (!shouldQueryGitlab || (parsedGlLink === null && mode !== 'gitlab')) {
         setGitlabItems([])
       }
@@ -924,8 +911,7 @@ export default function SmartWorkspaceNameField({
           repoPath: target.repo.path,
           repoId: target.repo.id,
           sourceContext: target.gitlabSourceContext,
-          // Why: self-hosted GitLab URLs must resolve against their pasted
-          // hostname; gitlab.com is only one possible GitLab instance.
+          // Why: self-hosted GitLab URLs must resolve against their pasted hostname, not gitlab.com.
           host: parsedGlLink.slug.host,
           path: parsedGlLink.slug.path,
           iid: parsedGlLink.number,
@@ -954,11 +940,7 @@ export default function SmartWorkspaceNameField({
     }
   }, [disabled, mode, onGitLabItemSelect, parsedGlLink, repoBackedSearchTargets, shouldQueryGitlab])
 
-  // Why: when the user is on the GitLab tab (or in 'smart' mix) and
-  // hasn't pasted a URL, surface the project's MRs filtered by the
-  // current state chip. Default 'opened' matches gitlab.com's default
-  // MR list view. Smart mode includes GitLab MRs alongside GitHub
-  // items so the unified picker actually surfaces both providers.
+  // Why: list the project's MRs by state chip when no URL pasted; default 'opened' matches gitlab.com's default MR view.
   useEffect(() => {
     if (!shouldQueryGitlab || disabled || !onGitLabItemSelect) {
       if (!shouldQueryGitlab) {
@@ -978,9 +960,7 @@ export default function SmartWorkspaceNameField({
     }
     let stale = false
     setGitlabLoading(true)
-    // Why: thread the typed query through so the GitLab API filters MRs by
-    // name/number (mirrors the GitHub effect). shouldQueryGitlab already
-    // gates on sourceQueryWithinLimit, so an oversized query never reaches here.
+    // Why: thread the typed query so the GitLab API filters MRs by name/number (shouldQueryGitlab already gates oversized queries).
     const trimmedQuery = debouncedQuery.trim() || undefined
     void Promise.all(
       repoBackedSearchTargets.map((target) =>
@@ -1071,28 +1051,14 @@ export default function SmartWorkspaceNameField({
     }
   }, [rows])
 
-  // Why: source rows (GitHub/branches/Linear) are driven by debouncedQuery,
-  // so they're stale until the user pauses typing for SEARCH_DEBOUNCE_MS.
-  // We don't want to filter them out (causes flicker as results appear and
-  // disappear with each keystroke), but we do need to prevent cmdk's Enter
-  // handler from auto-selecting a stale source row. Two cases:
-  //   - Smart/Branches: a typed-text row (use-name / create-branch) exists
-  //     and is pinned at the top — force the highlight onto it so Enter
-  //     commits the typed text instead of a stale issue/PR/branch.
-  //   - GitHub/Linear: no typed-text fallback row, so clear the highlight
-  //     entirely; the input's Enter handler falls through to onPlainEnter.
+  // Why: source rows lag debouncedQuery, so keep Enter off a stale row.
   const valueWithinSourceLimit = isSmartWorkspaceSourceQueryWithinLimit(value)
   const debouncedQueryWithinSourceLimit = isSmartWorkspaceSourceQueryWithinLimit(debouncedQuery)
   const trimmedValue = valueWithinSourceLimit ? value.trim() : ''
   const trimmedDebouncedQuery = debouncedQueryWithinSourceLimit ? debouncedQuery.trim() : ''
   const isQueryStale = trimmedValue.length > 0 && trimmedDebouncedQuery !== trimmedValue
 
-  // Why: when the typed value is unambiguously a source reference — a
-  // GitHub issue/PR shorthand ("#1234"), a github.com issue/pull URL, or a
-  // Linear identifier ("STA-123") — the user is clearly looking up that
-  // specific source rather than naming a workspace. Once a matching row
-  // appears in the results, snap the highlight onto it so Enter picks it
-  // instead of the typed-text fallback.
+  // Why: when the typed value is an unambiguous source ref, snap the highlight to that row so Enter picks it over the typed-text fallback.
   const sourceIntent = useMemo<'github' | 'gitlab' | 'linear' | null>(() => {
     if (!isSmartWorkspaceSourceQueryWithinLimit(value)) {
       return null
@@ -1126,15 +1092,12 @@ export default function SmartWorkspaceNameField({
   const handleSelect = useCallback(
     (row: RowEntry) => {
       if (row.kind === 'use-name' || row.kind === 'create-branch') {
-        // Why: "create new branch" has no existing ref to base from, so
-        // it follows the same path as a typed name — the workspace's branch
-        // is derived from `name` and `baseBranch` stays unset (default base).
+        // Why: "create new branch" has no ref to base from, so it uses the typed-name path (default base).
         onValueChange(row.name)
       } else if (row.kind === 'github') {
         onGitHubItemSelect(row.item)
       } else if (row.kind === 'gitlab') {
-        // Why: optional handler — guarded so the surface degrades to a
-        // no-op for hosts that haven't wired GitLab support yet.
+        // Why: optional handler — guarded so it no-ops for hosts without GitLab support.
         onGitLabItemSelect?.(row.item)
       } else if (row.kind === 'branch') {
         onBranchSelect(row.refName, row.localBranchName)
@@ -1327,11 +1290,7 @@ export default function SmartWorkspaceNameField({
               variant="line"
               className="h-7 w-full justify-start gap-4 px-0"
               onFocusCapture={(event) => {
-                // Why: Radix Tabs uses roving focus and re-applies tabindex=0 to
-                // the active trigger on every render, so we can't keep it out of
-                // the natural Tab order via props or a MutationObserver (race
-                // with React commits). Instead, intercept focus on entry into
-                // the tabs list so forward Tab goes straight to the input.
+                // Why: Radix Tabs roving focus re-applies tabindex=0 to the active trigger (races React commits), so forward Tab to the input.
                 const previous = event.relatedTarget as HTMLElement | null
                 const list = tabsListRef.current
                 const input = localInputRef.current
@@ -1375,10 +1334,7 @@ export default function SmartWorkspaceNameField({
           <PopoverAnchor asChild>
             <div className="relative min-w-0">
               {selectedSource ? (
-                // Why: min-w-0 + w-full lets the pill shrink to its flex
-                // parent; without them the inner truncate's intrinsic
-                // min-content (long PR title) propagates up and pushes the
-                // dialog wider than its max-w.
+                // Why: min-w-0 + w-full let the pill shrink; else the inner truncate's min-content (long PR title) widens the dialog past its max-w.
                 <div
                   ref={setSelectedSourceNode}
                   data-workspace-source-pill="true"
@@ -1478,10 +1434,7 @@ export default function SmartWorkspaceNameField({
                       }
                     }}
                     onFocus={(event) => {
-                      // Why: only open when focus moves from another composer
-                      // control (Tab/Shift+Tab). Dialog autofocus comes from
-                      // outside the composer root and stays suppressed until
-                      // click/type/tab-within-composer engagement above.
+                      // Why: only open on focus from another composer control (Tab); dialog autofocus from outside stays suppressed.
                       if (!isComposerFieldToFieldFocus(event)) {
                         return
                       }
@@ -1520,11 +1473,7 @@ export default function SmartWorkspaceNameField({
                             handleSelect(row)
                             return
                           }
-                          // No highlighted row (e.g., stale results in
-                          // GitHub/Linear modes where the highlight was
-                          // cleared to avoid auto-selecting a stale source).
-                          // Fall through to onPlainEnter so the keypress
-                          // doesn't feel inert.
+                          // No highlighted row (e.g. cleared stale GitHub/Linear results); fall through to onPlainEnter so the keypress isn't inert.
                         }
                         onPlainEnter?.()
                       }
@@ -1545,14 +1494,11 @@ export default function SmartWorkspaceNameField({
             align="start"
             sideOffset={4}
             className="popover-scroll-content flex w-[var(--radix-popover-trigger-width)] flex-col p-0"
-            // Why: this popover lives inside the create-workspace dialog; a
-            // taller result list can cover the submit footer while typing.
+            // Why: capped height so the result list can't cover the create-workspace dialog's submit footer while typing.
             style={{ maxHeight: 'min(var(--radix-popover-content-available-height,7rem),7rem)' }}
             onOpenAutoFocus={(event) => event.preventDefault()}
             onPointerDownOutside={(event) => {
-              // Why: the input is a PopoverAnchor, not a PopoverTrigger, so
-              // Radix treats clicks on it as outside the popover. Keep focus
-              // clicks and mode-tab clicks from immediately closing results.
+              // Why: input is a PopoverAnchor not Trigger, so Radix counts clicks on it as outside; keep input/mode-tab clicks from closing results.
               const target = event.target as Node
               if (
                 localInputRef.current?.contains(target) ||
@@ -1572,9 +1518,7 @@ export default function SmartWorkspaceNameField({
             }}
           >
             {mode === 'gitlab' ? (
-              // Why: GitLab MR-state filter — Open / Merged / Closed / All —
-              // mirrors the gitlab.com merge-requests page tab strip so users
-              // arriving from the web UI find a familiar control.
+              // Why: MR-state filter mirrors gitlab.com's merge-requests tab strip so web-UI users find a familiar control.
               <div
                 className="flex shrink-0 items-center gap-1 border-b border-border/40 px-2 py-1.5"
                 onMouseDown={(e) => e.preventDefault()}
@@ -1712,12 +1656,7 @@ function RowIcon({ row }: { row: RowEntry }): React.JSX.Element {
     )
   }
   if (row.kind === 'gitlab') {
-    // Why: GitLab MRs use GitMerge (arrow-merge-into-line) rather than
-    // GitPullRequest so the row visually disambiguates from branches
-    // (GitBranch's fork shape reads similar to GitPullRequest at this
-    // size). GitMerge also matches gitlab.com's own MR iconography,
-    // so users coming from the web UI find it familiar. Issues stay
-    // on CircleDot — the shape is provider-agnostic.
+    // Why: MRs use GitMerge (not GitPullRequest, which reads like GitBranch at this size) and match gitlab.com's MR iconography.
     return row.item.type === 'mr' ? (
       <GitMerge className="size-3.5 shrink-0 text-muted-foreground" />
     ) : (
@@ -1735,8 +1674,7 @@ function SelectionIcon({ kind }: { kind: SmartWorkspaceNameSelection['kind'] }):
     return <GitPullRequest className="size-3.5 shrink-0 text-muted-foreground" />
   }
   if (kind === 'gitlab-mr') {
-    // Why: see RowIcon — GitMerge keeps MRs distinct from PRs and
-    // branches.
+    // Why: GitMerge keeps MRs distinct from PRs and branches (see RowIcon).
     return <GitMerge className="size-3.5 shrink-0 text-muted-foreground" />
   }
   if (kind === 'github-issue' || kind === 'gitlab-issue') {
@@ -1787,9 +1725,7 @@ function RowLabel({ row }: { row: RowEntry }): React.JSX.Element {
     )
   }
   if (row.kind === 'gitlab') {
-    // Why: GitLab uses `!N` for MRs and `#N` for issues — show the
-    // appropriate prefix so the row is unambiguous to users coming from
-    // gitlab.com's UI.
+    // Why: GitLab uses `!N` for MRs and `#N` for issues (gitlab.com convention).
     const prefix = row.item.type === 'mr' ? '!' : '#'
     return (
       <span className="min-w-0 truncate">
diff --git a/src/renderer/src/components/onboarding/use-onboarding-flow.ts b/src/renderer/src/components/onboarding/use-onboarding-flow.ts
index 2917c9075a3..e02cb931855 100644
--- a/src/renderer/src/components/onboarding/use-onboarding-flow.ts
+++ b/src/renderer/src/components/onboarding/use-onboarding-flow.ts
@@ -1,4 +1,4 @@
-/* eslint-disable max-lines -- Why: this hook is the single orchestrator for every onboarding-step transition (navigation, persistence, telemetry, ref-mirror, auto-select); splitting would force callers to coordinate ordering across multiple hooks and lose the controller-shape contract OnboardingFlow.tsx consumes. */
+/* eslint-disable max-lines -- Why: single orchestrator for every onboarding-step transition; splitting would scatter ordering across hooks and lose the controller-shape contract OnboardingFlow.tsx consumes. */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { toast } from 'sonner'
 import { getAgentCatalog } from '@/lib/agent-catalog'
@@ -132,14 +132,11 @@ export function remapOpenOnboardingLastCompletedStep({
   if (outcome === 'completed' && lastCompletedStep >= 4) {
     return ONBOARDING_FINAL_STEP
   }
-  // Why: v3 was the four-step flow before the Windows terminal preference
-  // page. Step 4 already meant notifications, so open progress should resume
-  // there rather than treating it as the newly inserted Windows step.
+  // Why: in v3 (four-step, pre-Windows-terminal) step 4 already meant notifications, so resume there.
   if (flowVersion === 3) {
     return Math.min(4, lastCompletedStep)
   }
-  // Why: v2 was the five-step flow; missing/older versions were seven-step
-  // data where step 4 was removed agent setup, not completed integrations.
+  // Why: v2 (five-step) and older seven-step data used step 4 for removed agent setup, not integrations.
   if (flowVersion === 2) {
     if (lastCompletedStep === 3) {
       return 2
@@ -183,8 +180,7 @@ export async function prepareSkippedOnboardingPreferences({
   setError
 }: SkippedOnboardingPreferenceOptions): Promise<boolean> {
   try {
-    // Why: theme tiles save immediately for a stable preview, but skip still
-    // means "do not keep this step's choice."
+    // Why: theme tiles save immediately for a stable preview, but skip must not keep this step's choice.
     if (currentStepId === 'theme') {
       const themeToRestore = themeBeforePreview ?? settingsTheme
       if (themeToRestore) {
@@ -193,8 +189,7 @@ export async function prepareSkippedOnboardingPreferences({
         await updateSettings({ theme: themeToRestore })
       }
     }
-    // Why: the repo step seeds folder terminals from saved settings. Preserve
-    // the visible agent choice when optional preferences are skipped.
+    // Why: the repo step seeds folder terminals from saved settings, so preserve the visible agent choice on skip.
     if (currentStepId === 'agent' && selectedAgent) {
       await updateSettings({ defaultTuiAgent: selectedAgent })
     }
@@ -242,11 +237,9 @@ export function useOnboardingFlow(
   const refreshPreflightStatus = useAppStore((s) => s.refreshPreflightStatus)
   const linearStatus = useAppStore((s) => s.linearStatus)
   const linearStatusChecked = useAppStore((s) => s.linearStatusChecked)
-  // Why: App hydrates repos before mounting onboarding. Reading the store
-  // synchronously lets the final step render its already-added state without a flash.
+  // Why: repos are hydrated before onboarding mounts; the sync read lets the final step render added state without a flash.
   const repos = useAppStore((s) => s.repos)
-  // Why: renderToStaticMarkup uses Zustand's initial server snapshot. The
-  // synchronous read keeps tests and the first client render aligned.
+  // Why: renderToStaticMarkup uses Zustand's initial snapshot; the sync read keeps tests and the first client render aligned.
   const effectivePreflightStatus = preflightStatus ?? useAppStore.getState().preflightStatus
 
   const skipIntegrations = shouldSkipIntegrationsStep(effectivePreflightStatus)
@@ -273,8 +266,7 @@ export function useOnboardingFlow(
       agentDefaultEnv: settings?.agentDefaultEnv
     }) !== 'manual'
   )
-  // Why: hydrate theme from saved settings instead of hardcoding 'dark' so users
-  // who already configured a theme see their choice preselected.
+  // Why: hydrate theme from saved settings so users who already chose one see it preselected.
   const [theme, setTheme] = useState<GlobalSettings['theme']>(settings?.theme ?? 'dark')
   const [cloneUrl, setCloneUrl] = useState('')
   const [serverPath, setServerPath] = useState('')
@@ -291,9 +283,7 @@ export function useOnboardingFlow(
   const [busyLabel, setBusyLabel] = useState<string | null>(null)
   const [error, setError] = useState<string | null>(null)
 
-  // Why: settings load async; the lazy useState initializers above run before
-  // settings hydrates. Re-sync once before commit so children never paint the
-  // fallback defaults, unless the user already interacted with that field.
+  // Why: settings hydrate async after the lazy initializers run; re-sync once before commit unless the user edited the field.
   const themeInteractedRef = useRef(false)
   const agentInteractedRef = useRef(false)
   const yoloPermissionsInteractedRef = useRef(false)
@@ -326,26 +316,19 @@ export function useOnboardingFlow(
     }
   }
 
-  // Why: track user interaction so async settings hydration above doesn't
-  // overwrite a value the user explicitly chose.
+  // Why: track interaction so async settings hydration doesn't overwrite a value the user chose.
   const setThemeInteractive = useCallback((value: GlobalSettings['theme']) => {
     themeInteractedRef.current = true
     setTheme(value)
   }, [])
-  // `fromCollapsedSection` is the click-site signal for whether the picked
-  // agent lived under the `<details>` disclosure in AgentStep. AgentStep is
-  // the only call site that has the real answer; main-side detected_count /
-  // detection_state are merged in here from the store.
+  // `fromCollapsedSection`: whether the picked agent lived under AgentStep's `<details>` disclosure — only that call site knows.
   const detectedAgentIdsRef = useRef<readonly TuiAgent[]>(detectedAgentIds ?? [])
   const isDetectingRef = useRef<boolean>(isDetectingAgents)
   const selectedAgentRef = useRef(selectedAgent)
-  // Why: refs let `setSelectedAgentInteractive` (a stable useCallback) read
-  // the freshest hydration classification at click time. Mirrors the
-  // detectedAgentIdsRef / isDetectingRef pattern.
+  // Why: refs let the stable `setSelectedAgentInteractive` read the freshest hydration classification at click time.
   const pathSourceRef = useRef(pathSource)
   const pathFailureReasonRef = useRef(pathFailureReason)
-  // Why: stable onboarding handlers read these values at click/async time, so
-  // keep the mirrors fresh before events can run.
+  // Why: keep these mirrors fresh so stable handlers read current values at click/async time.
   selectedAgentRef.current = selectedAgent
   detectedAgentIdsRef.current = detectedAgentIds ?? []
   isDetectingRef.current = isDetectingAgents
@@ -354,17 +337,13 @@ export function useOnboardingFlow(
   const setSelectedAgentInteractive = useCallback(
     (value: TuiAgent | null, fromCollapsedSection = false) => {
       agentInteractedRef.current = true
-      // Why: de-dup re-clicks on the current agent so dashboards count
-      // mind-changes only, not idle reselection of the same option.
+      // Why: de-dup re-clicks on the current agent so telemetry counts mind-changes, not idle reselection.
       const prev = selectedAgentRef.current
       setSelectedAgent(value)
       if (value === null || value === prev) {
         return
       }
-      // Why: emit at click time, not at step completion, so we capture
-      // mind-changes within the step. The payload builder is extracted so the
-      // store-fields-attached invariant has unit coverage — see
-      // agent-picked-payload.test.ts.
+      // Why: emit at click time (not step completion) to capture mind-changes; payload builder extracted for coverage — see agent-picked-payload.test.ts.
       track(
         'onboarding_agent_picked',
         buildAgentPickedPayload({
@@ -386,10 +365,7 @@ export function useOnboardingFlow(
 
   const detectedSet = useMemo(() => new Set(detectedAgentIds ?? []), [detectedAgentIds])
   const currentStep = STEPS[stepIndex]
-  // Why: the stepper shows exactly the steps the user will land on. Skipped
-  // optional steps — Windows terminal off Windows, integrations when the GitHub
-  // CLI is already installed — are dropped entirely rather than rendered as
-  // dead, unreachable dots the user silently skips past on Continue.
+  // Why: the stepper shows only steps the user will land on; skipped optional steps are dropped, not rendered as dead dots.
   const progressSteps = useMemo(
     () =>
       STEPS.map((step, index) => ({ step, index })).filter(
@@ -397,10 +373,7 @@ export function useOnboardingFlow(
       ),
     [skipOptions]
   )
-  // Why: while resuming, stepIndex can momentarily point at a step that just
-  // became skipped (preflight resolving to gh-installed) before the auto-skip
-  // effect advances it. Resolve forward so the count reflects the step we're
-  // about to land on instead of flashing "1 of N" with no active dot.
+  // Why: while resuming, stepIndex can briefly point at a just-skipped step; resolve forward so the count reflects the landing step.
   const displayedStepIndex = resolveStepIndex(stepIndex, skipOptions, 'forward')
   const progressStepIndex = Math.max(
     0,
@@ -411,8 +384,7 @@ export function useOnboardingFlow(
   // Why: pin start time once so onboarding_completed reports a real funnel duration.
   const startTimeRef = useRef<number>(Date.now())
 
-  // Why: track the latest persisted theme in a ref so the unmount-only revert
-  // below uses the freshest value without retriggering on each settings change.
+  // Why: ref so the unmount-only revert reads the freshest theme without retriggering on each settings change.
   const persistedThemeRef = useRef<GlobalSettings['theme']>(settings?.theme ?? 'dark')
   persistedThemeRef.current = settings?.theme ?? 'dark'
   const themeStepEntryThemeRef = useRef<GlobalSettings['theme'] | null>(null)
@@ -425,8 +397,7 @@ export function useOnboardingFlow(
     if (!settings || themeStepEntryCapturedRef.current) {
       return
     }
-    // Why: theme tile clicks persist immediately for normal progression, but
-    // "Skip to project setup" should keep the preference the user arrived with.
+    // Why: capture entry theme so "Skip to project setup" keeps the preference the user arrived with.
     themeStepEntryCapturedRef.current = true
     themeStepEntryThemeRef.current = settings.theme
   }, [currentStep.id, settings])
@@ -456,9 +427,7 @@ export function useOnboardingFlow(
     }
     const nextIndex = getNextStepIndex(stepIndex)
     setStepIndex(nextIndex)
-    // Why: users with gh already on PATH don't need this setup page, but
-    // persistence must still resume them at the next visible step instead of
-    // bouncing back through skipped optional pages.
+    // Why: persistence must resume at the next visible step, not bounce back through skipped optional pages.
     const skippedThroughStepNumber = Math.max(
       currentStep.stepNumber,
       STEPS[nextIndex].stepNumber - 1
@@ -484,16 +453,14 @@ export function useOnboardingFlow(
     stepIndex
   ])
 
-  // Why: ref guard prevents StrictMode's double-invoke from emitting
-  // `onboarding_started` twice on mount.
+  // Why: ref guard stops StrictMode's double-invoke from emitting onboarding_started twice.
   const startedTrackedRef = useRef(false)
   useEffect(() => {
     if (startedTrackedRef.current) {
       return
     }
     startedTrackedRef.current = true
-    // Why: `resumed_from_step` is the step the user finished, not the
-    // step we resume into.
+    // Why: resumed_from_step is the step the user finished, not the one we resume into.
     const lastCompleted = remappedLastCompletedStep
     track(
       'onboarding_started',
@@ -504,11 +471,7 @@ export function useOnboardingFlow(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
-  // Session-local step duration: re-pinned on every step view so a resumed
-  // user emits `duration_ms` for the visible step measuring only the
-  // post-resume time. Optional on the schema so a missing baseline (e.g. the
-  // _viewed effect was skipped or StrictMode double-mounted) fail-soft drops
-  // the field rather than the event. See docs/onboarding-telemetry-extensions.md.
+  // Why: re-pinned per step view so duration_ms measures only post-resume time; optional so a missing baseline drops the field, not the event. See docs/onboarding-telemetry-extensions.md.
   const stepStartedAtRef = useRef<number>(Date.now())
   useEffect(() => {
     stepStartedAtRef.current = Date.now()
@@ -526,8 +489,7 @@ export function useOnboardingFlow(
     if (node !== null) {
       return
     }
-    // Why: onboarding previews theme state outside this component; tie
-    // final cleanup to the modal root detaching instead of passive Effects.
+    // Why: theme preview mutates state outside this component, so revert on modal-root detach rather than a passive Effect.
     applyDocumentTheme(persistedThemeRef.current)
   }, [])
 
@@ -537,8 +499,7 @@ export function useOnboardingFlow(
       durationMs: number,
       advancedVia: 'button' | 'keyboard'
     ): void => {
-      // Why: one low-cardinality snapshot answers whether task sources were
-      // usable at step exit without paying for per-button telemetry.
+      // Why: one low-cardinality snapshot captures task-source usability at step exit without per-button telemetry.
       track('onboarding_task_sources_snapshot', {
         github_status: getGitHubTaskSourceStatus(preflightStatus, preflightStatusLoading),
         linear_status: getLinearTaskSourceStatus(linearStatus, linearStatusChecked),
@@ -550,17 +511,14 @@ export function useOnboardingFlow(
     [linearStatus, linearStatusChecked, preflightStatus, preflightStatusLoading]
   )
 
-  // Why: only auto-pick on first mount when detection completes; otherwise
-  // selecting an agent would re-trigger this effect and clobber/race user clicks.
+  // Why: auto-pick only on first mount; otherwise re-running would clobber/race the user's own agent selection.
   const didAutoSelectRef = useRef(false)
   useEffect(() => {
     if (didAutoSelectRef.current) {
       return
     }
     didAutoSelectRef.current = true
-    // Why: re-read PATH on wizard mount instead of reusing the session cache.
-    // The cache can be poisoned if a prior caller ran before shell PATH
-    // hydration finished, leaving the wizard with a false "no agents" state.
+    // Why: re-read PATH on mount; the session cache can be poisoned by callers that ran before shell PATH hydration, giving a false "no agents" state.
     void refreshDetectedAgents().then((ids) => {
       if (selectedAgentRef.current !== null) {
         return
@@ -580,8 +538,7 @@ export function useOnboardingFlow(
   const completeRepo = useCallback(
     async (projectId: string, isGit: boolean, path: 'open_folder' | 'clone_url') => {
       await fetchRepos()
-      // Why: once the project is persisted, a non-authoritative Git refresh
-      // should still complete onboarding onto the project row as a fallback.
+      // Why: a non-authoritative Git refresh should still complete onboarding onto the project row as a fallback.
       await fetchWorktrees(projectId, isGit ? { requireAuthoritative: true } : undefined)
       const worktrees = useAppStore.getState().worktreesByRepo[projectId] ?? []
       if (isGit) {
@@ -593,16 +550,12 @@ export function useOnboardingFlow(
       } else {
         const worktree = worktrees[0] ?? null
         if (worktree) {
-          // Why: onboarding asks for a default agent immediately before this step.
-          // Non-git folders skip the composer, so seed their first terminal here.
+          // Why: non-git folders skip the composer, so seed their first terminal with the chosen default agent here.
           const startup = buildOnboardingFolderAgentStartup(settings)
           activateAndRevealWorktree(worktree.id, { startup })
         }
       }
-      // Why: next() short-circuits the repo step, so emit step_completed here
-      // once the repo is successfully added to keep the funnel consistent.
-      // Gate on closeWith's success so a persistence failure doesn't
-      // double-count.
+      // Why: next() short-circuits the repo step; emit step_completed here, gated on closeWith success so a persistence failure can't double-count.
       const closed = await closeWith(
         'completed',
         isGit ? { addedRepo: true } : { addedFolder: true },
@@ -612,10 +565,7 @@ export function useOnboardingFlow(
       if (!closed) {
         return
       }
-      // Why: the repo step has no keyboard-vs-button advance — Cmd+Enter
-      // routes to `openFolder()` which collapses both into the path-clicked
-      // path. Emit `duration_ms` only; `advanced_via` is intentionally absent
-      // for the final step. See docs/onboarding-telemetry-extensions.md §3.
+      // Why: the final repo step has no keyboard-vs-button distinction, so emit duration_ms without advanced_via. See docs/onboarding-telemetry-extensions.md §3.
       track('onboarding_step_completed', {
         step: ONBOARDING_FINAL_STEP,
         value_kind: 'repo',
@@ -644,11 +594,7 @@ export function useOnboardingFlow(
     setError
   })
 
-  // Why: synchronous re-entry latch. `busyLabel` is React state and only
-  // commits after the awaited persistCurrentStep round-trip resolves, so a
-  // second Cmd+Enter (auto-repeat fires every ~30ms) re-enters next() before
-  // the first call's setStepIndex has run, advancing twice and skipping a
-  // step. A ref flips synchronously so re-entries bail immediately.
+  // Why: sync latch; busyLabel state commits too late to stop a ~30ms Cmd+Enter auto-repeat from re-entering next() and skipping a step.
   const nextInFlightRef = useRef(false)
   const trackCurrentStepCompleted = useCallback(
     (advancedVia: 'button' | 'keyboard'): void => {
@@ -709,8 +655,7 @@ export function useOnboardingFlow(
           const nextIndex = getNextStepIndex(stepIndex)
           const skippedThroughStepNumber = STEPS[nextIndex].stepNumber - 1
           if (skippedThroughStepNumber > currentStep.stepNumber) {
-            // Why: resolveStepIndex can skip optional pages before they render,
-            // but persisted progress must still resume at the visible page.
+            // Why: skipped optional pages must still persist progress at the next visible page.
             try {
               onOnboardingChange(await persistStep(skippedThroughStepNumber))
             } catch (err) {
@@ -929,8 +874,7 @@ export function useOnboardingFlow(
       const result = await importNestedRepos({
         parentPath: nestedScan.selectedPath,
         groupName: '',
-        // Why: Set insertion order can drift after deselect/reselect; import
-        // ordering should match the visible scan order users reviewed.
+        // Why: Set insertion order can drift after deselect/reselect; match the visible scan order users reviewed.
         projectPaths: selectedProjectPaths,
         ...(nestedImportScanId ? { scanId: nestedImportScanId } : {}),
         mode
@@ -960,8 +904,7 @@ export function useOnboardingFlow(
         )
       }
       for (const importedRepoId of importedRepoIds) {
-        // Why: imported repos are already persisted; non-authoritative SSH
-        // refreshes should not block onboarding from revealing the first project.
+        // Why: imported repos are already persisted, so a non-authoritative SSH refresh shouldn't block revealing the first project.
         await fetchWorktrees(importedRepoId, { requireAuthoritative: true })
       }
       await completeRepo(projectId, true, 'open_folder')
@@ -1029,8 +972,7 @@ export function useOnboardingFlow(
     onboardingNestedRepoRuntimeKind
   ])
 
-  // Why: lets the user back out of the nested-repo step in onboarding to
-  // re-pick a folder/clone target. Mirrors the dialog's left-aligned Back.
+  // Why: lets the user back out of the nested-repo step to re-pick a folder/clone target.
   const cancelNested = useCallback(() => {
     if (busyLabel !== null && !nestedScanInProgress) {
       return
@@ -1162,8 +1104,7 @@ export function useOnboardingFlow(
       if (!closed) {
         return
       }
-      // Why: the repo picker moved to the Add Project dialog, so skipping
-      // optional setup now closes onboarding and hands off to that modal.
+      // Why: repo picker now lives in the Add Project dialog, so skipping optional setup closes onboarding and hands off to it.
       track('onboarding_step_skipped', {
         step: stepNumber,
         value_kind: valueKind,
@@ -1248,12 +1189,9 @@ export function useOnboardingFlow(
       )
       return
     }
-    // Why: Settings renders behind the fullscreen onboarding layer; SSH users
-    // need a temporary detour without marking required repo setup dismissed.
+    // Why: SSH users need a temporary Settings detour without marking required repo setup dismissed.
     onSettingsDetourStart?.()
-    // Why: keep the target in the store before the Settings view mounts. A
-    // timer here can run before the lazy view subscribes and strand users on
-    // the default General pane.
+    // Why: set the target before the lazy Settings view mounts; a timer could fire before it subscribes and strand users on General.
     openSettingsTarget({ pane: 'ssh', repoId: null, sectionId: 'ssh' })
     openSettingsPage()
   }, [
diff --git a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
index 66ff0f85a35..fb1a8857aca 100644
--- a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
@@ -203,9 +203,7 @@ type HostedReviewCreationSnapshot = {
   data: HostedReviewCreationEligibility
 }
 
-// Confirmed readiness must drop when HEAD, dirty, upstream, base, or the
-// execution host move under the eligibility that produced it. Fingerprint those
-// fields so a stale snapshot cannot keep an enabled Create open.
+// Fingerprint HEAD/dirty/upstream/base/execution-host so a stale snapshot can't keep an enabled Create open when any of them move.
 function buildChecksPanelEligibilityGitFingerprint(input: {
   headOid: string | null
   hasUncommittedChanges: boolean | undefined
@@ -352,8 +350,7 @@ function gitLabMRCommentsToPRComments(
 ): PRComment[] {
   return (comments ?? []).map((comment) => {
     const { reactions: _reactions, ...compatibleComment } = comment
-    // Why: the shared comments renderer expects GitHub reaction content enums;
-    // GitLab emoji award names are open-ended, so omit them in this view.
+    // Why: the shared comments renderer expects GitHub reaction enums; GitLab award names are open-ended, so omit them here.
     return compatibleComment
   })
 }
@@ -417,16 +414,12 @@ async function resolveGitLabMRDiscussionForChecks(args: {
 }
 
 export default function ChecksPanel(): React.JSX.Element {
-  // Why: the sidebar stays mounted when closed (for performance). Gate
-  // polling on visibility so we don't fetch checks/comments — or poll the
-  // terminal cwd — in the background when the panel isn't visible.
+  // Why: the sidebar stays mounted when closed (perf); gate polling on visibility so we don't fetch checks/comments or poll cwd while hidden.
   const rightSidebarOpen = useAppStore((s) => s.rightSidebarOpen)
   const rightSidebarTab = useAppStore((s) => s.rightSidebarTab)
   const isPanelVisible = rightSidebarOpen && rightSidebarTab === 'checks'
 
-  // Follow the active terminal's cwd so linked-PR/checks state tracks the
-  // worktree the terminal is actually operating in (e.g. across a stack),
-  // falling back to the sidebar's selected worktree.
+  // Follow the active terminal's cwd so linked-PR/checks track the worktree it's operating in (e.g. across a stack), else the sidebar selection.
   const defaultActiveWorktree = useActiveWorktree()
   const { worktree: activeWorktree } = useChecksPanelTerminalWorktree({
     defaultActiveWorktree,
@@ -504,9 +497,7 @@ export default function ChecksPanel(): React.JSX.Element {
   )
   const [hostedReviewCreationSnapshot, setHostedReviewCreationSnapshot] =
     useState<HostedReviewCreationSnapshot | null>(null)
-  // Sticky observation of the most recent hard refresh error for the exact
-  // context. Persisted across queued/in-flight auto-retries so Create cannot
-  // flap back until a qualifying eligibility request clears it.
+  // Sticky record of the latest hard refresh error so Create can't flap back until a qualifying eligibility request clears it.
   const [hardRefreshError, setHardRefreshError] = useState<{
     observedAt: number
     errorType: PRRefreshErrorType
@@ -515,16 +506,12 @@ export default function ChecksPanel(): React.JSX.Element {
   const [gitStatusSnapshot, setGitStatusSnapshot] = useState<ChecksPanelGitStatusSnapshot | null>(
     null
   )
-  // Context key whose git-status probe failed with no usable snapshot, so the
-  // empty state can distinguish "checking branch status" from "could not check".
+  // Context key whose git-status probe failed with no snapshot, so the empty state can distinguish "checking branch status" from "could not check".
   const [gitStatusProbeErrorContextKey, setGitStatusProbeErrorContextKey] = useState<string | null>(
     null
   )
   const [gitStatusRefreshNonce, setGitStatusRefreshNonce] = useState(0)
-  // Bumped by a manual Retry/Refresh so eligibility re-runs even when the Git
-  // snapshot is unchanged. A hard error can only be cleared by an eligibility
-  // request that started strictly after the error, so an auth fix followed by
-  // Retry (which does not change Git state) must still trigger a fresh request.
+  // Bumped by manual Retry/Refresh so eligibility re-runs even when Git state is unchanged (e.g. an auth fix must still clear the hard error).
   const [eligibilityRefreshNonce, setEligibilityRefreshNonce] = useState(0)
   const [editingTitle, setEditingTitle] = useState(false)
   const [titleDraft, setTitleDraft] = useState('')
@@ -606,9 +593,7 @@ export default function ChecksPanel(): React.JSX.Element {
     [runtimeEnvironmentId, settings]
   )
   const repoConnectionId = repo?.connectionId?.trim() || null
-  // Local execution host variant (`wsl:{distro}` vs `host`). WSL is a local-host
-  // variant, not a runtime/SSH host, so it only applies when execution is local;
-  // remote contexts are already scoped by runtimeEnvironmentId / connectionId.
+  // Local execution host variant (wsl:{distro} vs host); applies only when local — remote contexts are scoped by runtimeEnvironmentId/connectionId.
   const localExecutionScope = useMemo<string | null>(() => {
     if (runtimeEnvironmentId != null || repoConnectionId != null) {
       return null
@@ -653,12 +638,7 @@ export default function ChecksPanel(): React.JSX.Element {
     [clearTitleInputFocusTimer]
   )
 
-  // Why: the sidebar no longer uses key={activeWorktreeId} to force a full
-  // remount on worktree switch (that caused an IPC storm on Windows). Reset
-  // branch-specific local state so stale UI from the previous context doesn't
-  // leak (e.g. mid-edit title, stale loading indicators, PR dialog fields).
-  // Done during render (not useEffect) so the reset takes effect on the same
-  // paint as the context change; useEffect would leave one stale render.
+  // Why: no key={worktreeId} remount (caused an IPC storm on Windows); reset branch-specific state during render (not useEffect) so it lands on the same paint.
   const [prevPanelContextKey, setPrevPanelContextKey] = useState(panelContextKey)
   const [prRefreshStateNow, setPrRefreshStateNow] = useState(() => Date.now())
   if (panelContextKey !== prevPanelContextKey) {
@@ -696,7 +676,6 @@ export default function ChecksPanel(): React.JSX.Element {
     }
   }
 
-  // Find active worktree and repo
   const isFolder = repo ? isFolderRepo(repo) : false
   const prCacheKey =
     repo && branch
@@ -727,8 +706,7 @@ export default function ChecksPanel(): React.JSX.Element {
     refreshContextKeyRef.current = refreshContextKey
     refreshRequestKeyRef.current = null
   }
-  // Why: background PR refreshes replace the cache map; Checks only renders
-  // the entry for the active repo and branch.
+  // Why: background PR refreshes replace the cache map; Checks only renders the entry for the active repo and branch.
   const prCacheEntry = useAppStore((s) => selectReviewCacheEntry(s.prCache, prCacheKey || null))
   const pr: PRInfo | null = prCacheEntry?.data ?? null
   const prCachedHasPR = prCacheEntry ? prCacheEntry.data !== null : null
@@ -742,9 +720,7 @@ export default function ChecksPanel(): React.JSX.Element {
     activeWorktree?.linkedAzureDevOpsPR ??
     activeWorktree?.linkedGiteaPR ??
     null
-  // Fetch PR data when the active worktree/branch changes.
-  // Why: branch lookup is lossy for fork/deleted-head PRs; reuse a known PR
-  // number from metadata or the visible cache whenever we have one.
+  // Why: branch lookup is lossy for fork/deleted-head PRs; reuse a known PR number from metadata or cache whenever we have one.
   const linkedPR = activeWorktree?.linkedPR ?? null
   const fallbackGitHubPRNumber = linkedPR == null ? (pr?.number ?? null) : null
   const linkedGitLabMR = activeWorktree?.linkedGitLabMR ?? null
@@ -788,8 +764,7 @@ export default function ChecksPanel(): React.JSX.Element {
         if (!token) {
           return
         }
-        // Why: time alone does not publish Zustand updates; this timeout clears
-        // abandoned active refresh UI without treating expiry as no-PR evidence.
+        // Why: time alone doesn't publish Zustand updates; this timeout clears abandoned refresh UI without treating expiry as no-PR evidence.
         recordChecksPanelPRRefreshBreadcrumb({
           event: 'stale_cleared',
           provider: 'github',
@@ -826,10 +801,7 @@ export default function ChecksPanel(): React.JSX.Element {
     panelVisibleSinceRef.current = Date.now()
   }, [isPanelVisible, panelContextKey])
 
-  // Record the latest hard refresh error for the exact context. Kept sticky
-  // (only cleared via computeChecksPanelConfirmedReadiness) so a background
-  // queued/in-flight auto-retry — which replaces `status: 'error'` — cannot
-  // silently re-enable Create while the lookup is still impossible here.
+  // Record the latest hard refresh error, kept sticky so a background auto-retry can't silently re-enable Create while lookup is impossible.
   useEffect(() => {
     const errorType = prRefreshState?.status === 'error' ? prRefreshState.errorType : undefined
     if (!isChecksPanelHardRefreshErrorType(errorType)) {
@@ -845,9 +817,7 @@ export default function ChecksPanel(): React.JSX.Element {
     })
   }, [prRefreshState])
 
-  // Why: select only timestamps (not whole cache records) so the entry-refresh
-  // effect doesn't re-run on every cache mutation. See
-  // docs/refresh-on-checks-tab.md.
+  // Why: select only timestamps, not whole cache records, so the entry-refresh effect doesn't re-run on every cache mutation. See docs/refresh-on-checks-tab.md.
   const prFetchedAt = useAppStore((s) =>
     prCacheKey ? s.prCache[prCacheKey]?.fetchedAt : undefined
   )
@@ -925,8 +895,7 @@ export default function ChecksPanel(): React.JSX.Element {
     gitStatusSnapshot?.contextKey === panelContextKey
       ? (gitStatusSnapshot.gitIdentity?.head ?? null)
       : null
-  // Read at eligibility request time via a ref so a HEAD move drops confirmed
-  // (fingerprint mismatch) without re-triggering the eligibility network call.
+  // Read via a ref so a HEAD move drops confirmed (fingerprint mismatch) without re-triggering the eligibility network call.
   const eligibilityHeadOidRef = useRef(eligibilityHeadOid)
   eligibilityHeadOidRef.current = eligibilityHeadOid
   const eligibilityGitFingerprint = gitStatusReadyForPanelContext
@@ -942,9 +911,7 @@ export default function ChecksPanel(): React.JSX.Element {
         localExecutionScope
       })
     : null
-  // Why: Create PR eligibility waits for the stricter panel snapshot, but the
-  // Publish affordance can use the active worktree poller when SSH snapshot
-  // refresh is delayed; publishing is still blocked for dirty fallback status.
+  // Why: Publish can use the worktree poller when the stricter panel snapshot is delayed; still blocked for dirty fallback status.
   const publishActionGitStatusInputs = readChecksPanelPublishActionGitStatus({
     snapshot: gitStatusSnapshot,
     contextKey: panelContextKey,
@@ -961,14 +928,7 @@ export default function ChecksPanel(): React.JSX.Element {
   const hostedReviewCreateProvider = resolveHostedReviewCreationProvider(
     hostedReviewCreation?.provider
   )
-  // Only GitHub contexts run the gh-based PR refresh coordinator. Bitbucket /
-  // Azure DevOps / Gitea / GitLab must never be driven by (or show copy from) a
-  // GitHub `gh` failure — that would hide a valid composer and mislabel the CLI.
-  // Prefer the resolved eligibility provider (authoritative); before it resolves,
-  // treat a non-GitHub linked review as a definite non-GitHub signal and stay
-  // GitHub-optimistic otherwise so GitHub status is not delayed on initial load.
-  // (`resolveHostedReviewCreationProvider` defaults null → 'github', so the raw
-  // value cannot distinguish "unknown" from "GitHub".)
+  // Only GitHub runs the gh refresh coordinator; re-derive GitHub-ness from linked reviews because resolveHostedReviewCreationProvider defaults null→'github' (can't tell unknown from GitHub), staying GitHub-optimistic pre-eligibility.
   const hasNonGitHubLinkedReview =
     activeWorktree?.linkedGitLabMR != null ||
     activeWorktree?.linkedBitbucketPR != null ||
@@ -978,19 +938,12 @@ export default function ChecksPanel(): React.JSX.Element {
     ? hostedReviewCreation.provider === 'github'
     : !hasNonGitHubLinkedReview
   const hostedReviewCreateCopy = localizedHostedReviewCopy(hostedReviewCreateProvider)
-  // The PR cache is branch/host scoped but not push-target scoped, so an accepted
-  // no-PR fetched for a previous push target could alias as `not_found` after the
-  // push target (or other exact-context field) changes. When an eligibility
-  // snapshot exists for a *different* context than the current one, the context
-  // has moved and that branch-scoped no-PR is not authoritative for it — demote
-  // it to unknown until eligibility re-resolves. Same-context background churn
-  // (snapshot matches, or no snapshot yet) keeps the sticky no-review intact.
+  // The PR cache isn't push-target scoped, so demote a branch-scoped no-PR to unknown when the eligibility snapshot is for a different context.
   const prCachedHasPRForContext =
     hostedReviewCreationSnapshot && hostedReviewCreationSnapshot.contextKey !== panelContextKey
       ? null
       : prCachedHasPR
-  // Four-state review evidence: replaces the old ambiguous-GitHub boolean so the
-  // empty state can never claim "No review found" without accepted evidence.
+  // Four-state review evidence so the empty state can never claim "No review found" without accepted evidence.
   const checksPanelReviewLookupResult = resolveChecksPanelReviewLookup({
     pr,
     prCachedHasPR: prCachedHasPRForContext,
@@ -1000,10 +953,7 @@ export default function ChecksPanel(): React.JSX.Element {
     eligibilityReview: hostedReviewCreation?.review ?? null
   })
   const checksPanelReviewLookup = checksPanelReviewLookupResult.state
-  // Confirmed readiness for the exact context, computed from the last confirmed
-  // eligibility snapshot rather than live `canCreate` (which would be circular
-  // and would flap during transient refresh/eligibility failures). This both
-  // gates the composer and clears the sticky hard-error block below.
+  // Confirmed readiness from the last eligibility snapshot, not live canCreate (which would be circular and flap during transient failures).
   const hardErrorObservedAt =
     isGitHubReviewContext && hardRefreshError && hardRefreshError.contextKey === panelContextKey
       ? hardRefreshError.observedAt
@@ -1021,8 +971,7 @@ export default function ChecksPanel(): React.JSX.Element {
     now: Date.now()
   }
   const confirmedReadiness = computeChecksPanelConfirmedReadiness(confirmedReadinessInput)
-  // A hard error stays active across auto-retries until a qualifying eligibility
-  // request clears it, so `status: 'queued' | 'in-flight'` no longer un-hides Create.
+  // A hard error persists until a qualifying eligibility request clears it; queued/in-flight status no longer un-hides Create.
   const checksPanelHasHardRefreshError =
     hardErrorObservedAt !== undefined && !isChecksPanelHardErrorCleared(confirmedReadinessInput)
   const activePullRequestGenerationKey = getPullRequestGenerationRecordKey({
@@ -1050,8 +999,7 @@ export default function ChecksPanel(): React.JSX.Element {
       if (!context.worktreeId || !context.worktreePath) {
         return
       }
-      // Why: AI PR detail generation can rebase before summarizing; persist the
-      // push requirement because ChecksPanel unmounts when users leave the tab.
+      // Why: AI PR generation can rebase before summarizing; persist the push requirement since ChecksPanel unmounts when users leave the tab.
       updatePullRequestGenerationRecord(generationKey, (record) =>
         markPullRequestGenerationRequiresPushBeforeCreate({
           record,
@@ -1100,10 +1048,7 @@ export default function ChecksPanel(): React.JSX.Element {
     () => (settings ? resolveSourceControlAiEnabled({ settings, repo }) : false),
     [repo, settings]
   )
-  // Confirmed-only composer gate. Driven by confirmed readiness (context match,
-  // fresh eligibility, matching git snapshot, cleared hard error) so an
-  // already-confirmed composer survives transient refresh/eligibility failures
-  // but a refresh failure never *opens* a never-confirmed Create.
+  // Confirmed-only gate: a confirmed composer survives transient refresh failures, but a failure never *opens* a never-confirmed Create.
   const createComposerOpen =
     !isFolder && !activeReview && Boolean(branch) && confirmedReadiness.confirmed
   const handleGeneratePullRequestFieldsForActive = useCallback(
@@ -1135,8 +1080,7 @@ export default function ChecksPanel(): React.JSX.Element {
       const previousRequiresPushBeforeCreate =
         useAppStore.getState().pullRequestGenerationRecords[generationKey]
           ?.requiresPushBeforeCreate === true
-      // Why: ChecksPanel unsets the create composer when the user navigates
-      // away; persist the request so generation can finish in the background.
+      // Why: ChecksPanel unsets the composer on navigate-away; persist the request so generation can finish in the background.
       const runningRecord = createRunningPullRequestGenerationRecord(context, seed, fieldRevisions)
       setPullRequestGenerationRecord(
         generationKey,
@@ -1302,8 +1246,7 @@ export default function ChecksPanel(): React.JSX.Element {
     submitting: isCreatingPr,
     prCreationDefaults,
     sourceControlAiActionsVisible,
-    // Preserve the draft when a hard refresh error hides the composer so the
-    // user's title/body/base survive recovery for the same exact context.
+    // Preserve the draft when a hard refresh error hides the composer so title/body/base survive recovery for the same context.
     retainDraftWhenClosed: true,
     generation: {
       generating: activePullRequestGenerationRecord?.status === 'running',
@@ -1319,8 +1262,7 @@ export default function ChecksPanel(): React.JSX.Element {
     }
   })
   useEffect(() => {
-    // Why: checks-panel PR generation can finish while this composer is hidden
-    // by a worktree switch; hydrate once the original composer is visible again.
+    // Why: PR generation can finish while this composer is hidden by a worktree switch; hydrate once the original composer is visible again.
     if (
       !activePullRequestGenerationKey ||
       !activePullRequestGenerationRecord ||
@@ -1416,9 +1358,7 @@ export default function ChecksPanel(): React.JSX.Element {
         linkedGiteaPR,
         staleWhileRevalidate: true
       })
-      // Why: the gh-based PR refresh coordinator is GitHub-only. Running it for
-      // Bitbucket/Azure/Gitea produced a spurious `gh_unavailable` hard error that
-      // hid a valid composer; those providers refresh via fetchHostedReviewForBranch.
+      // Why: the gh-based refresh coordinator is GitHub-only; running it elsewhere gave a spurious gh_unavailable error hiding a valid composer.
       if (activeWorktreeId && isGitHubReviewContext) {
         const refreshRequest = resolveChecksPanelPRRefreshRequest({
           cachedHasPR: prCachedHasPR,
@@ -1495,8 +1435,7 @@ export default function ChecksPanel(): React.JSX.Element {
         clearTimeout(gitStatusSnapshotRetryTimerRef.current)
         gitStatusSnapshotRetryTimerRef.current = null
       }
-      // Why: hiding the panel or temporarily losing SSH should stop new work,
-      // not erase same-context Create PR eligibility that can still be retried.
+      // Why: hiding the panel or losing SSH should stop new work, not erase same-context Create PR eligibility that can still be retried.
       return
     }
     let stale = false
@@ -1514,8 +1453,7 @@ export default function ChecksPanel(): React.JSX.Element {
       }
     }
     gitStatusSnapshotInFlightContextRef.current = requestContextKey
-    // Why: global status maps are keyed only by worktree. Use their changes as
-    // invalidation signals, then fetch a local snapshot for the active boundary.
+    // Why: global status maps are keyed only by worktree; use their changes as invalidation signals, then fetch a local snapshot.
     if (gitStatusSnapshotRetryTimerRef.current) {
       clearTimeout(gitStatusSnapshotRetryTimerRef.current)
       gitStatusSnapshotRetryTimerRef.current = null
@@ -1535,8 +1473,7 @@ export default function ChecksPanel(): React.JSX.Element {
         !stale &&
         shouldCommitChecksPanelGitStatusSnapshot(panelContextKeyRef.current, requestContextKey)
       ) {
-        // Why: the Checks tab can be the only visible git surface; commit
-        // branch identity before branch-scoped upstream refresh can fail.
+        // Why: the Checks tab can be the only visible git surface; commit branch identity before branch-scoped upstream refresh can fail.
         updateWorktreeGitIdentity(activeWorktreeId, {
           head: status.head,
           branch: status.branch ?? (status.head ? null : undefined)
@@ -1569,21 +1506,18 @@ export default function ChecksPanel(): React.JSX.Element {
               branch: status.branch ?? (status.head ? null : undefined)
             }
           })
-          // A fresh probe succeeded, so this context is no longer in the failed
-          // "could not check branch status" state.
+          // A fresh probe succeeded, so this context is no longer in the "could not check branch status" state.
           setGitStatusProbeErrorContextKey((key) => (key === requestContextKey ? null : key))
         }
       })
       .catch((error) => {
         console.warn('[ChecksPanel] git status refresh before eligibility failed', error)
         if (!stale) {
-          // Why: transient SSH/runtime flakes should not hide an already-valid
-          // Create PR state for this same branch; retry while the panel stays visible.
+          // Why: transient SSH/runtime flakes shouldn't hide an already-valid Create PR state for this branch; retry while visible.
           setGitStatusSnapshot((snapshot) =>
             shouldClearChecksPanelGitStatusSnapshot(snapshot, requestContextKey) ? null : snapshot
           )
-          // Mark the probe as failed so the empty state can show "Could not check
-          // branch status" instead of an indefinite "Checking branch status".
+          // Mark the probe failed so the empty state shows "Could not check branch status" instead of an indefinite "Checking branch status".
           if (
             shouldCommitChecksPanelGitStatusSnapshot(panelContextKeyRef.current, requestContextKey)
           ) {
@@ -1697,11 +1631,7 @@ export default function ChecksPanel(): React.JSX.Element {
         }
       })
       .catch(() => {
-        // Why: a transient GitHub outage makes the existing-review lookup inside
-        // eligibility rethrow. Do NOT tear down the last confirmed snapshot — a
-        // clean, already-confirmed composer must survive the outage. Confirmed
-        // readiness still gates it on context + git-fingerprint + freshness, so a
-        // stale snapshot can never open a never-confirmed Create.
+        // Why: a transient GitHub outage rethrows here; don't tear down the last confirmed snapshot so a clean composer survives the outage.
       })
     return () => {
       stale = true
@@ -1752,10 +1682,7 @@ export default function ChecksPanel(): React.JSX.Element {
       return
     }
 
-    // Why: the checks panel is the one place where stale conflict metadata is
-    // visibly wrong. Force-refresh conflicting PRs once when the panel sees
-    // them so we don't keep rendering cached branch summaries or empty file
-    // lists from an older payload.
+    // Why: stale conflict metadata is visibly wrong here; force-refresh conflicting PRs once to avoid stale cached summaries.
     conflictSummaryRefreshKeyRef.current = refreshKey
     setConflictDetailsRefreshing(true)
     void fetchPRForBranch(repo.path, branch, {
@@ -1765,9 +1692,7 @@ export default function ChecksPanel(): React.JSX.Element {
       linkedPRNumber: linkedPR,
       fallbackPRNumber: fallbackGitHubPRNumber ?? pr.number
     }).finally(() => {
-      // Why: fetchPRForBranch updates the PR cache before resolving, which
-      // can rerun this effect. Only the current refresh key may clear the
-      // spinner so stale requests don't race newer worktrees/branches.
+      // Why: fetchPRForBranch can rerun this effect; only the current key clears the spinner so stale requests don't race newer branches.
       if (conflictSummaryRefreshKeyRef.current === refreshKey) {
         setConflictDetailsRefreshing(false)
       }
@@ -1819,8 +1744,7 @@ export default function ChecksPanel(): React.JSX.Element {
         }
         setChecks(result)
 
-        // Exponential backoff: if checks haven't changed, double the interval (cap 120s).
-        // If they changed, reset to 30s.
+        // Exponential backoff: unchanged checks double the interval (cap 120s), changes reset to 30s.
         const signature = JSON.stringify(result.map((c) => `${c.name}:${c.status}:${c.conclusion}`))
         pollIntervalRef.current =
           signature === prevChecksRef.current
@@ -1943,8 +1867,7 @@ export default function ChecksPanel(): React.JSX.Element {
     // Reset backoff state on PR change
     pollIntervalRef.current = 30_000
     prevChecksRef.current = ''
-    // Why: PR check status is user-visible when the panel is open. Keep visible
-    // unfocused windows fresh, but stop timers and API work while hidden.
+    // Why: check status is user-visible; keep visible unfocused windows fresh but stop timers/API work while hidden.
     return installWindowVisibilityTimeoutPoller({
       run: () => fetchChecks(),
       getDelayMs: () => pollIntervalRef.current
@@ -1965,8 +1888,6 @@ export default function ChecksPanel(): React.JSX.Element {
   }, [activeGitLabReview, fetchGitLabDetails, isPanelVisible])
 
   // Fetch comments once when PR changes (no polling — comments change infrequently).
-  // The manual refresh path calls this directly; the auto-fetch effect below uses
-  // its own cancellation guard to discard stale responses after PR switches.
   const fetchComments = useCallback(
     async ({
       force = false,
@@ -2120,8 +2041,7 @@ export default function ChecksPanel(): React.JSX.Element {
     if (refreshInFlightRef.current) {
       return
     }
-    // Why: React has not disabled the button until the next render, so a rapid
-    // double-click must not start duplicate git status/upstream subprocesses.
+    // Why: button isn't disabled until next render; guard a rapid double-click from starting duplicate git subprocesses.
     refreshInFlightRef.current = true
     const initialRequestKey = checksPanelAsyncResultKey(
       prCacheKey,
@@ -2161,8 +2081,7 @@ export default function ChecksPanel(): React.JSX.Element {
             head: snapshotIdentity.head,
             branch: snapshotIdentity.branch
           })
-          // Why: this click discovered a terminal branch switch. Let the
-          // branch-keyed render/effects restart instead of refreshing old PR data.
+          // Why: this click discovered a terminal branch switch; let branch-keyed render/effects restart instead of refreshing old PR data.
           refreshOutcome = 'branch-changed'
           return
         }
@@ -2186,8 +2105,7 @@ export default function ChecksPanel(): React.JSX.Element {
               currentBranch: branch
             })
           ) {
-            // Why: this click discovered a terminal branch switch. Let the
-            // branch-keyed render/effects restart instead of refreshing old PR data.
+            // Why: this click discovered a terminal branch switch; let branch-keyed render/effects restart instead of refreshing old PR data.
             refreshOutcome = 'branch-changed'
             return
           }
@@ -2209,8 +2127,7 @@ export default function ChecksPanel(): React.JSX.Element {
             isCurrentRequest() &&
             shouldCommitChecksPanelGitStatusSnapshot(panelContextKeyRef.current, panelContextKey)
           ) {
-            // Why: the explicit Refresh click already paid for this status read;
-            // commit it so empty-state Publish/Create eligibility is fresh.
+            // Why: the Refresh click already paid for this status read; commit it so empty-state Publish/Create eligibility is fresh.
             setGitStatusSnapshot({
               contextKey: panelContextKey,
               hasUncommittedChanges: status.entries.length > 0,
@@ -2306,13 +2223,9 @@ export default function ChecksPanel(): React.JSX.Element {
         if (!isCurrentAsyncResult(initialRequestKey) && !isCurrentRequest()) {
           return
         }
-        // Why: a forced PR refresh can discover the PR number before React has
-        // repainted from prCache; make this refresh's follow-up checks current.
+        // Why: a forced refresh can find the PR number before React repaints from prCache; mark this refresh's checks current.
         asyncResultKeyRef.current = prRequestKey
-        // Why: call fetchPRChecks directly with the refreshed PR's headSha so
-        // we don't pass the stale headSha captured by `fetchChecks`'s closure
-        // before the PR refresh completed (covers external force-pushes and
-        // PR-number changes).
+        // Why: pass the refreshed headSha directly; fetchChecks's closure captured a stale one (force-pushes, PR-number changes).
         const refreshedChecks = fetchPRChecks(
           repo.path,
           refreshedPR.number,
@@ -2402,9 +2315,7 @@ export default function ChecksPanel(): React.JSX.Element {
       if (isCurrentRequest()) {
         refreshInFlightRef.current = false
         setIsRefreshing(false)
-        // Why: force a fresh eligibility request whose start time is after any
-        // current hard-refresh error, so a resolved auth/permission failure can
-        // clear the sticky hard error even when Git state did not change.
+        // Why: force fresh eligibility so a resolved auth failure clears the sticky hard error even when Git state is unchanged.
         setEligibilityRefreshNonce((value) => value + 1)
       }
     }
@@ -2448,10 +2359,7 @@ export default function ChecksPanel(): React.JSX.Element {
       if (!repo || !branch || !activeWorktreeId) {
         return
       }
-      // Why: entering the Checks tab is automatic UI behavior, not an explicit
-      // user refresh. Route PR refresh through the coordinator so rate-limit
-      // guards still apply; only force detail panes that the entry freshness rule
-      // already proved stale, so tab entry stays fresh without broad fan-out.
+      // Why: tab entry is automatic UI, not a user refresh; keep coordinator rate-limit guards and only force panes already proven stale.
       if (isGitLabReviewContext) {
         void fetchHostedReviewForBranch(repo.path, branch, {
           force: true,
@@ -2498,11 +2406,7 @@ export default function ChecksPanel(): React.JSX.Element {
     ]
   )
 
-  // Why: force a freshness check on each "entry" into the Checks tab so PRs
-  // opened outside Orca, externally force-pushed heads, and stale checks/comments
-  // appear without waiting for the cache TTL. The grace window suppresses
-  // duplicate fetches from rapid show/hide toggles. See
-  // docs/refresh-on-checks-tab.md.
+  // Why: force a freshness check on each Checks-tab entry so externally-changed PRs appear without waiting for the cache TTL. See docs/refresh-on-checks-tab.md.
   const entryKey =
     isPanelVisible && repo && !isFolder && branch
       ? `${activeWorktreeId ?? ''}::${activeGitLabReview ? hostedReviewCacheKey : prCacheKey}`
@@ -2510,9 +2414,7 @@ export default function ChecksPanel(): React.JSX.Element {
   const lastEntryKeyRef = useRef<string>('')
   useEffect(() => {
     if (!entryKey) {
-      // Resetting on hide is required so reopening the panel on the same PR
-      // re-evaluates freshness (a prevKey !== currentKey check alone would miss
-      // close-and-reopen of the same PR).
+      // Reset on hide so reopening the same PR re-evaluates freshness; a prevKey !== currentKey check alone would miss close-and-reopen.
       lastEntryKeyRef.current = ''
       return
     }
@@ -2539,8 +2441,7 @@ export default function ChecksPanel(): React.JSX.Element {
     const refreshComments =
       prNumber !== null && (commentsFetchedAt === undefined || commentsFetchedAt < cutoff)
 
-    // Reset polling attention state so the forced fetch's signature establishes
-    // a fresh baseline rather than colliding with the previous PR's backoff.
+    // Reset polling attention state so the forced fetch establishes a fresh baseline instead of colliding with the previous PR's backoff.
     pollIntervalRef.current = 30_000
     prevChecksRef.current = ''
     handleEntryRefresh({ refreshChecks, refreshComments })
@@ -2952,9 +2853,7 @@ export default function ChecksPanel(): React.JSX.Element {
     ]
   )
 
-  // Why: hosted-review conflict files come from the host mergeability check,
-  // not a local MERGE_HEAD, so the prompt must tell the agent how to reproduce
-  // the merge locally instead of reusing the live Source Control conflict prompt.
+  // Why: hosted-review conflicts come from the host mergeability check (no local MERGE_HEAD), so the prompt reproduces the merge locally.
   const handleResolveConflictsWithAI = useCallback(async (): Promise<void> => {
     if (!sourceControlAiActionsVisible || !activeWorktreeId || !activeConflictReview) {
       return
@@ -3372,8 +3271,7 @@ export default function ChecksPanel(): React.JSX.Element {
   const handleOpenPR = useCallback(
     (event: React.MouseEvent<HTMLButtonElement>) => {
       if (activeReview?.url) {
-        // Why: route through openHttpLink so PR/MR links honor the "open links
-        // in app" setting; Shift+Cmd/Ctrl keeps the terminal-link escape hatch.
+        // Why: route through openHttpLink so PR/MR links honor the "open links in app" setting; Shift+Cmd/Ctrl is the escape hatch.
         openChecksPanelHostedReviewUrl({
           url: activeReview.url,
           event: event.nativeEvent,
@@ -3472,8 +3370,7 @@ export default function ChecksPanel(): React.JSX.Element {
     } catch {
       // Store remote actions already surface the publish failure toast.
     } finally {
-      // Why: publishing changes the upstream boundary the Checks panel uses to
-      // decide between Publish, Create PR, and Push & Create PR.
+      // Why: publishing changes the upstream boundary the panel uses to decide between Publish, Create PR, and Push & Create PR.
       setGitStatusRefreshNonce((value) => value + 1)
       setIsPublishingBranch(false)
     }
@@ -3488,9 +3385,7 @@ export default function ChecksPanel(): React.JSX.Element {
     pushBranch
   ])
 
-  // Sync the branch with its upstream using the same runtime-scoped operation and
-  // push target as Source Control, so a `needs_sync` create blocker is actionable
-  // from the Checks panel instead of showing guidance with no button.
+  // Sync via the same runtime-scoped operation and push target as Source Control so a `needs_sync` create blocker is actionable here.
   const handleSyncBranch = useCallback(async (): Promise<void> => {
     if (!activeWorktreeId || !activeWorktree?.path || isSyncingBranch || isRemoteOperationActive) {
       return
@@ -3517,8 +3412,7 @@ export default function ChecksPanel(): React.JSX.Element {
     } catch {
       // Store remote actions already surface the sync failure toast.
     } finally {
-      // Why: syncing changes ahead/behind, which the panel uses to choose between
-      // Sync, Create PR, and Push & Create PR.
+      // Why: syncing changes ahead/behind, which the panel uses to choose between Sync, Create PR, and Push & Create PR.
       setGitStatusRefreshNonce((value) => value + 1)
       setIsSyncingBranch(false)
     }
@@ -3824,10 +3718,7 @@ export default function ChecksPanel(): React.JSX.Element {
   }
 
   if (!activeReview) {
-    // Why: during a rebase/merge/cherry-pick the worktree is on a detached
-    // HEAD, so there is no branch to look up a PR for. Showing "No pull
-    // request found" is misleading — the PR still exists on the original
-    // branch. Show an operation-aware message instead.
+    // Why: mid rebase/merge/cherry-pick HEAD is detached, so "No pull request found" misleads — the PR still exists on the original branch.
     const operationInProgress = conflictOperation !== 'unknown'
     const operationLabel =
       conflictOperation === 'rebase'
@@ -3851,12 +3742,7 @@ export default function ChecksPanel(): React.JSX.Element {
           hasUpstream: publishActionRemoteStatus?.hasUpstream,
           hasCurrentBranch: Boolean(branch)
         }))
-    // Non-GitHub providers (GitLab/Bitbucket/Azure/Gitea) have no typed GitHub
-    // refresh state; only feed the GitHub refresh classification into the selector
-    // for GitHub contexts. When a hard error is still active (sticky across
-    // auto-retries), surface it as the refresh state so the hard-error card and
-    // composer suppression persist even while a queued/in-flight retry is
-    // temporarily the live status.
+    // Feed refresh state only for GitHub; surface a sticky hard error so its card and composer suppression persist across retries.
     const emptyRefreshInput = !isGitHubReviewContext
       ? undefined
       : checksPanelHasHardRefreshError && hardRefreshError
@@ -3885,8 +3771,7 @@ export default function ChecksPanel(): React.JSX.Element {
       reviewLookup: checksPanelReviewLookup,
       openReviewUrl: checksPanelReviewLookupResult.openReviewUrl,
       eligibilityBlockedReason: hostedReviewCreation?.blockedReason,
-      // Confirmed readiness (not the live create gate) drives composer mode so
-      // the selector matches the preserved-composer semantics.
+      // Confirmed readiness (not the live create gate) drives composer mode to match preserved-composer semantics.
       confirmedReadiness: confirmedReadiness.confirmed,
       confirmedNeedsPush: confirmedReadiness.needsPush,
       refresh: emptyRefreshInput,
@@ -3906,19 +3791,14 @@ export default function ChecksPanel(): React.JSX.Element {
     const reviewRecoveryRetryDisabled =
       reviewState.retryDisabledUntil !== undefined && Date.now() < reviewState.retryDisabledUntil
     const reviewRecoveryLabelIsRefresh = reviewState.recovery.includes('refresh')
-    // Only offer Retry/Refresh when the selector's recovery set includes it;
-    // states like git-status loading, bare, or archived expose no recovery.
+    // Only offer Retry/Refresh when the selector's recovery set includes it; some states expose none.
     const reviewShowRetryOrRefresh =
       reviewState.recovery.includes('retry') || reviewRecoveryLabelIsRefresh
     const reviewShowOpenReview =
       reviewState.recovery.includes('open_review') && Boolean(reviewState.openReviewUrl)
-    // The selector is the authority for the Sync workflow action; a `needs_sync`
-    // create blocker must expose Sync Branch, not just guidance copy.
+    // A `needs_sync` create blocker must expose Sync Branch, not just guidance copy.
     const reviewShowSyncBranch = reviewState.workflowAction === 'sync_branch'
-    // The action row must render whenever any action is available — recovery
-    // actions (Retry/Refresh/Open Review) are shown independently of the composer
-    // so a preserved confirmed composer still exposes a working Retry during a
-    // transient failure.
+    // Recovery actions render independently of the composer so a preserved composer still exposes Retry during a transient failure.
     const reviewShowActionRow =
       canPublishBranch ||
       reviewShowSyncBranch ||
@@ -4072,18 +3952,14 @@ export default function ChecksPanel(): React.JSX.Element {
   const reviewShortLabel = activeReview.provider === 'gitlab' ? 'MR' : 'PR'
   const shouldShowReviewTriageStrip =
     activeConflictReview !== null || getBrokenChecks(checks).length > 0
-  // Why: mirror openHttpLink's global routing inputs so the hint only appears
-  // when the actual plain-click path would open inside Orca.
+  // Why: mirror openHttpLink's routing inputs so the hint only appears when a plain click would open inside Orca.
   const showHostedReviewSystemBrowserHint =
     Boolean(activeWorktreeId) &&
     settings?.openLinksInApp === true &&
     !settings.activeRuntimeEnvironmentId
   return (
     <div ref={setChecksPanelContentRef} className="flex-1 overflow-auto scrollbar-sleek">
-      {/* Why: a background refresh failed while cached PR data is still shown.
-          Surface it over the stale data so a GitHub outage doesn't look like a
-          normal (but silently out-of-date) panel. GitHub-only — GitLab reviews
-          don't flow through prRefreshState. */}
+      {/* Why: surface a background-refresh failure over stale cached PR data so a GitHub outage doesn't look like a normal panel. GitHub-only. */}
       {activeReview?.provider === 'github' && prRefreshState?.status === 'error' ? (
         <div
           role="alert"
@@ -4188,8 +4064,7 @@ export default function ChecksPanel(): React.JSX.Element {
       )}
       {activeConflictReview && (
         <>
-          {/* Why: the triage strip owns the single Resolve action for PR and MR
-              conflicts; the file list and fallback notice are informational. */}
+          {/* Why: the triage strip owns the single Resolve action; the file list and fallback notice are informational. */}
           <ConflictingFilesSection pr={activeConflictReview} />
           <MergeConflictNotice
             pr={activeConflictReview}
@@ -4197,9 +4072,7 @@ export default function ChecksPanel(): React.JSX.Element {
           />
         </>
       )}
-      {/* Why: when the hosted review has merge conflicts and no checks have been fetched,
-          showing "No checks configured" is misleading — checks may exist but
-          simply cannot run until conflicts are resolved. Hide the empty state. */}
+      {/* Why: with merge conflicts and no checks fetched, "No checks configured" is misleading — checks can't run until conflicts resolve. */}
       {!(activeConflictReview && checks.length === 0 && !checksLoading) && (
         <ChecksList
           checks={checks}
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index d9cb51a24a3..163af51eefa 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -377,13 +377,7 @@ export function resolveSourceControlBaseRef(input: {
   return worktreeBaseRef || input.repoBaseRef?.trim() || input.defaultBaseRef?.trim() || null
 }
 
-// Why: the compare/diff view's base is conceptually distinct from the PR/rebase
-// merge target (effectiveBaseRef). When the setting is on, default the compare
-// base to the current branch's upstream so the panel surfaces local changes
-// instead of the full delta vs the repo default branch. Branches without an
-// upstream fall back to effectiveBaseRef so the automatic policy never makes
-// the committed-changes comparison disappear unexpectedly. When the setting is
-// off, fall back to effectiveBaseRef so behavior is unchanged.
+// Why: the compare base is distinct from the PR/rebase target; when enabled it defaults to the branch upstream (else effectiveBaseRef) to surface local changes.
 export function resolveSourceControlCompareBaseRef(input: {
   enabled: boolean
   worktreeBaseRef?: string | null
@@ -401,10 +395,7 @@ export function resolveSourceControlCompareBaseRef(input: {
   return input.upstreamName?.trim() || input.fallbackBaseRef?.trim() || null
 }
 
-// Why: only drop a stale branch-compare summary once we know there is truly no
-// compare base. While upstream status is still loading (remoteStatus undefined)
-// compareBaseRef can momentarily resolve to null, so clearing then would make
-// the committed-changes summary flicker until upstream loads.
+// Why: only clear the branch-compare summary once we truly have no base; compareBaseRef is momentarily null while upstream loads, which would flicker.
 export function shouldClearBranchCompareForMissingBase(input: {
   isFolder: boolean
   compareBaseRef: string | null
@@ -499,13 +490,7 @@ function rewriteCompareBaseBranchFromCandidate(
 const EMPTY_GIT_STATUS_ENTRIES: GitStatusEntry[] = []
 const EMPTY_BRANCH_CHANGE_ENTRIES: GitBranchChangeEntry[] = []
 
-// Why: directional signifiers ahead of each primary action label. Commit
-// (✓) is affirmative; Push (↑) points in the direction data flows; Sync
-// (↕) is bidirectional; Publish gets a cloud-up to distinguish the
-// first-time publish from a subsequent push. Pull is intentionally
-// icon-less — the down-arrow read as a download/save affordance and was
-// removed. Keeping the mapping outside the render function avoids
-// reallocating it on every render.
+// Why: directional icons per action; Pull stays icon-less (down-arrow read as download/save). Hoisted out of render to avoid per-render alloc.
 const PRIMARY_ICONS: Partial<
   Record<
     PrimaryAction['kind'],
@@ -540,11 +525,9 @@ const CONFLICTS_SECTION_LABEL = {
   fallback: 'Conflicts'
 }
 
-// Why: 5s branch compare polling churned git subprocesses in large repos.
-// Explicit commit, remote, manual, and base-ref refresh paths still run immediately.
+// Why: 30s poll — 5s churned git subprocesses in large repos; explicit commit/remote/manual/base-ref refreshes still run immediately.
 export const BRANCH_REFRESH_INTERVAL_MS = 30_000
-// Why: row action buttons host Radix Tooltip triggers. Keeping the overlay
-// measurable prevents transient top-left tooltip placement during hover.
+// Why: keep the overlay measurable so Radix Tooltip triggers don't get transient top-left placement on hover.
 const SOURCE_CONTROL_ROW_ACTION_OVERLAY_CLASS =
   'absolute right-0 top-0 bottom-0 flex shrink-0 items-center gap-1.5 bg-accent pr-3 pl-2 opacity-0 pointer-events-none transition-opacity group-hover:opacity-100 group-hover:pointer-events-auto focus-within:opacity-100 focus-within:pointer-events-auto [@media(hover:none)]:opacity-100 [@media(hover:none)]:pointer-events-auto'
 const SOURCE_CONTROL_TREE_INDENT_PX = 12
@@ -575,8 +558,7 @@ function useCopyFeedbackState<T>(resetValue: T): [T, (value: T) => void] {
     }
   }, [])
 
-  // Why: copy feedback timers are event-owned, but still need unmount cleanup
-  // so delayed clipboard/timer work cannot update a destroyed component.
+  // Why: copy feedback timers are event-owned but still need unmount cleanup so delayed work can't update a destroyed component.
   useEffect(() => {
     mountedRef.current = true
     return () => {
@@ -631,9 +613,7 @@ function requestSourceControlEditorRevealFrame(
   }
 }
 
-// Why: the pure state-machine logic now lives in
-// ./source-control-primary-action.ts. It is imported directly by callers
-// (tests and other components) instead of going through this module.
+// The primary-action state machine now lives in ./source-control-primary-action.ts, imported directly by callers.
 
 type CommitDraftsByWorktree = Record<string, string>
 
@@ -757,9 +737,7 @@ export function refreshSourceControlAfterRemoteAction({
   refreshGitHistory: () => Promise<void>
   onError?: (error: unknown) => void
 }): void {
-  // Why: fetch/sync can move the remote base ref without changing local files.
-  // Refresh all three visible git projections so the branch comparison table
-  // re-runs against the newly fetched base instead of waiting for polling.
+  // Why: fetch/sync can move the remote base without touching local files; refresh all three projections so branch compare re-runs immediately.
   void Promise.all([refreshGitStatus(), refreshBranchCompare(), refreshGitHistory()]).catch(onError)
 }
 
@@ -810,16 +788,11 @@ export function clearRemoteActionErrorsForCompletedConflictOperations({
 
 function SourceControlInner(): React.JSX.Element {
   const sourceControlRef = useRef<HTMLDivElement | null>(null)
-  // Why: the changed-file sections virtualize against the panel's shared
-  // scroller rather than owning a nested scroll container. State (not a ref)
-  // so the lists re-render and start observing once the element attaches.
+  // Why: virtualize against the panel's shared scroller; use state (not a ref) so lists re-render and start observing once the element attaches.
   const [fileListScrollElement, setFileListScrollElement] = useState<HTMLDivElement | null>(null)
   const isMac = useMemo(() => navigator.userAgent.includes('Mac'), [])
   const pendingCommentEditorRevealFrameIdsRef = useRef<number[]>([])
-  // Why: React setState is async, so a rapid double-click on the Commit
-  // button can both pass the isCommitting state guard before the disabled
-  // state re-renders. A ref flipped synchronously at the start of
-  // handleCommit gives us a true single-flight lock.
+  // Why: setState is async, so a double-click can pass the isCommitting guard before re-render; a synchronously-flipped ref gives a true single-flight lock.
   const commitInFlightRef = useRef<Record<string, boolean>>({})
   const activeWorktree = useActiveWorktree()
   const activeWorktreeId = useAppStore((s) => s.activeWorktreeId)
@@ -860,8 +833,7 @@ function SourceControlInner(): React.JSX.Element {
     activeWorktreeId ? (s.gitConflictOperationByWorktree[activeWorktreeId] ?? 'unknown') : 'unknown'
   )
   const conflictOperationsByWorktree = useAppStore((s) => s.gitConflictOperationByWorktree)
-  // Why: leave undefined until fetchUpstreamStatus resolves for this worktree.
-  // A synthetic "no upstream" flashes "Publish Branch" during worktree switches.
+  // Why: leave undefined until fetchUpstreamStatus resolves; a synthetic "no upstream" flashes "Publish Branch" on worktree switch.
   const remoteStatus = useAppStore((s) =>
     activeWorktreeId ? s.remoteStatusesByWorktree[activeWorktreeId] : undefined
   )
@@ -892,15 +864,13 @@ function SourceControlInner(): React.JSX.Element {
           true
         )
       : null
-  // Why: background worktree review refreshes replace both cache maps; this
-  // large panel only needs the entries for its active repo and branch.
+  // Why: background review refreshes replace both cache maps; this panel only needs its active repo/branch entries.
   const hostedReviewEntry = useAppStore((s) =>
     selectReviewCacheEntry(s.hostedReviewCache, hostedReviewCacheKey)
   )
   const hostedReviewEntryData = hostedReviewEntry?.data ?? null
   const activePrFromQueue = useAppStore((s) => selectReviewCacheData(s.prCache, activePrCacheKey))
-  // Why: git/file mutations and repo metadata requests belong to the repo
-  // OWNER host, not the currently focused host in the sidebar.
+  // Why: git/file mutations and repo metadata belong to the repo OWNER host, not the currently focused sidebar host.
   const activeRepoSettings = useMemo(
     () =>
       getRepoOwnerRoutedSettings(
@@ -963,18 +933,12 @@ function SourceControlInner(): React.JSX.Element {
   const setScrollToDiffCommentId = useAppStore((s) => s.setScrollToDiffCommentId)
   const setRightSidebarOpen = useAppStore((s) => s.setRightSidebarOpen)
   const setRightSidebarTab = useAppStore((s) => s.setRightSidebarTab)
-  // Why: pass activeWorktreeId directly (even when null/undefined) so the
-  // selector returns its stable empty sentinel. An
-  // inline `[]` fallback would allocate a new array each store update, break
-  // Zustand's Object.is equality, and cause this component plus the
-  // diffCommentCountByPath memo to churn on every unrelated store change.
+  // Why: pass activeWorktreeId even when null so the selector returns its stable empty sentinel; an inline [] would break Zustand's Object.is and churn.
   const diffCommentsForActive = useAppStore((s) =>
     selectWorktreeDiffCommentsOrEmpty(s, activeWorktreeId)
   )
   const diffCommentCount = diffCommentsForActive.length
-  // Why: per-file counts are fed into each UncommittedEntryRow so a comment
-  // badge can appear next to the status letter. Compute once per render so
-  // rows don't each re-filter the full list.
+  // Why: compute per-file comment counts once per render so rows don't each re-filter the full list.
   const diffCommentCountByPath = useMemo(() => {
     const map = new Map<string, number>()
     for (const c of diffCommentsForActive) {
@@ -992,8 +956,7 @@ function SourceControlInner(): React.JSX.Element {
     useState<PendingDiffCommentsClear | null>(null)
   const [isClearingDiffComments, setIsClearingDiffComments] = useState(false)
   const setSourceControlRoot = useCallback((node: HTMLDivElement | null) => {
-    // Why: markdown-note reveal frames target the Source Control surface; cancel
-    // them when that surface unmounts instead of from a passive Effect.
+    // Why: markdown-note reveal frames target this surface; cancel them on unmount rather than via a passive Effect.
     if (node === null) {
       cancelSourceControlEditorRevealFrames(pendingCommentEditorRevealFrameIdsRef)
     }
@@ -1008,8 +971,7 @@ function SourceControlInner(): React.JSX.Element {
       await window.api.ui.writeClipboardText(diffCommentsPrompt)
       showDiffCommentsCopied(true)
     } catch {
-      // Why: swallow — clipboard write can fail when the window isn't focused.
-      // No dedicated error surface is warranted for a best-effort copy action.
+      // Why: swallow — clipboard write can fail when unfocused; best-effort copy needs no error surface.
     }
   }, [diffCommentsForActive, diffCommentsPrompt, showDiffCommentsCopied])
 
@@ -1028,8 +990,7 @@ function SourceControlInner(): React.JSX.Element {
     pendingCount: pendingDiffCommentsClearCount
   })
   if (resolvedPendingDiffCommentsClear !== pendingDiffCommentsClear) {
-    // Why: the confirmation is purely local UI state; clear impossible
-    // confirmations before children observe a stale open dialog.
+    // Why: the confirmation is local UI state; clear impossible ones before children observe a stale open dialog.
     setPendingDiffCommentsClear(resolvedPendingDiffCommentsClear)
   }
 
@@ -1087,13 +1048,10 @@ function SourceControlInner(): React.JSX.Element {
   const [collapsedTreeDirs, setCollapsedTreeDirs] = useState<Set<string>>(new Set())
   const [baseRefDialogOpen, setBaseRefDialogOpen] = useState(false)
   const [pendingDiscard, setPendingDiscard] = useState<PendingDiscardConfirmation | null>(null)
-  // Why: start null rather than 'origin/main' so branch compare doesn't fire
-  // with a fabricated ref before the IPC resolves. effectiveBaseRef stays
-  // falsy until we have a real answer from the main process.
+  // Why: start null (not 'origin/main') so branch compare doesn't fire with a fabricated ref before the IPC resolves.
   const [defaultBaseRef, setDefaultBaseRef] = useState<string | null>(null)
   const [filterQuery, setFilterQuery] = useState('')
-  // Why: Source Control unmounts when the user switches tabs, so keep commit
-  // drafts in a module-scoped session cache and restore them on remount.
+  // Why: Source Control unmounts on tab switch; keep commit drafts in a module-scoped session cache and restore on remount.
   const [commitDrafts, setCommitDrafts] = useState<CommitDraftsByWorktree>(() =>
     loadSessionCommitDrafts()
   )
@@ -1105,10 +1063,7 @@ function SourceControlInner(): React.JSX.Element {
   >({})
   const remoteActionErrorSequenceByWorktreeRef = useRef<Record<string, number>>({})
   const previousConflictOperationsRef = useRef<Record<string, GitConflictOperation>>({})
-  // Why: keep commit-in-flight state per-worktree. A single boolean would be
-  // cleared when the user switched worktrees, letting them double-click Commit
-  // on worktree A after briefly navigating to B and back while A's original
-  // commit is still running.
+  // Why: keep commit-in-flight per-worktree; a single boolean would clear on worktree switch, allowing a double-commit on the original.
   const [commitInFlightByWorktree, setCommitInFlightByWorktree] = useState<Record<string, boolean>>(
     {}
   )
@@ -1118,8 +1073,7 @@ function SourceControlInner(): React.JSX.Element {
   const isAbortingOperation = abortOperationInFlightByWorktree[activeWorktreeId ?? ''] ?? false
   const confirmAction = useConfirmationDialog()
   const isCommitting = commitInFlightByWorktree[activeWorktreeId ?? ''] ?? false
-  // Why: parallel state to commit. Same per-worktree shape so navigating between
-  // worktrees mid-generation never silently cancels the in-flight request.
+  // Why: per-worktree shape (like commit) so navigating worktrees mid-generation never cancels the in-flight request.
   const generateInFlightRef = useRef<Record<string, boolean>>({})
   const [generateInFlightByWorktree, setGenerateInFlightByWorktree] = useState<
     Record<string, boolean>
@@ -1175,8 +1129,7 @@ function SourceControlInner(): React.JSX.Element {
   )
   const getCreatePrIntentOperationTarget = useCallback(
     (token: CreatePrIntentRunToken): SourceControlOperationTarget => ({
-      // Why: Create PR intent continues after navigation; keep git commands
-      // pinned to the worktree and runtime host that started the sequence.
+      // Why: Create PR intent continues after navigation; pin git commands to the worktree/host that started the sequence.
       settings: activeRepoSettings,
       worktreeId: token.worktreeId,
       worktreePath: token.worktreePath,
@@ -1224,8 +1177,7 @@ function SourceControlInner(): React.JSX.Element {
   const updateCommitDrafts = useCallback(
     (updater: (drafts: CommitDraftsByWorktree) => CommitDraftsByWorktree): void => {
       const next = updater(commitDraftsRef.current)
-      // Why: Create PR intent reads this ref after awaits to avoid overwriting
-      // user edits made before React's passive state sync effect runs.
+      // Why: Create PR intent reads this ref after awaits so it doesn't overwrite user edits made before React's passive state sync runs.
       commitDraftsRef.current = next
       setCommitDrafts(next)
     },
@@ -1291,10 +1243,7 @@ function SourceControlInner(): React.JSX.Element {
     record: activePullRequestGenerationRecord
   })
   const rightSidebarOpen = useAppStore((s) => s.rightSidebarOpen)
-  // Why: gate polling on both the active tab AND the sidebar being open.
-  // The sidebar now stays mounted when closed (for performance), so without
-  // this guard the branchCompare interval and PR fetch would keep running
-  // with no visible consumer, wasting git process spawns and API calls.
+  // Why: the sidebar stays mounted when closed, so gate polling on tab AND open or branchCompare/PR fetch would run with no visible consumer.
   const isBranchVisible = rightSidebarTab === 'source-control' && rightSidebarOpen
 
   const refreshActiveGitStatus = useCallback(async (): Promise<void> => {
@@ -1336,11 +1285,7 @@ function SourceControlInner(): React.JSX.Element {
     }
   }, [refreshActiveGitStatus])
 
-  // Why: when status is truncated at the entry limit, offer (once per worktree)
-  // to .gitignore the folder most likely flooding it — the usual cause is a
-  // build/dependency dir that should have been ignored. Accepting writes the
-  // .gitignore and refreshes, which clears the huge flag and resumes polling.
-  // Local-only: the SSH huge-folder write path isn't wired, so skip remote.
+  // Why: when status is truncated, offer once per worktree to .gitignore the flooding folder; local-only since the SSH huge-folder write path isn't wired.
   useEffect(() => {
     if (!repositoryHuge || !activeWorktreeId || !worktreePath || activeConnectionId) {
       return
@@ -1376,8 +1321,7 @@ function SourceControlInner(): React.JSX.Element {
                 'Add to .gitignore'
               ),
               onClick: () => {
-                // Why: the toast can outlive its worktree; a purged probe must
-                // not write .gitignore in a same-path replacement.
+                // Why: the toast can outlive its worktree; a purged probe must not write .gitignore in a same-path replacement.
                 if (!hasDismissedHugeRepoWarning(warningProbe)) {
                   return
                 }
@@ -1410,8 +1354,7 @@ function SourceControlInner(): React.JSX.Element {
       }
       try {
         await refreshGitStatusForWorktree({
-          // Why: generation can finish after the user switches hosts; refresh
-          // the same host that owned the generation request.
+          // Why: generation can finish after a host switch; refresh the host that owned the generation request.
           settings: context.runtimeTargetSettings,
           worktreeId: context.worktreeId,
           worktreePath: context.worktreePath,
@@ -1443,11 +1386,7 @@ function SourceControlInner(): React.JSX.Element {
       return
     }
 
-    // Why: reset to null so that effectiveBaseRef becomes falsy until the IPC
-    // resolves.  This prevents the branch compare from firing with a stale
-    // defaultBaseRef left over from a *different* repo (e.g. 'origin/master'
-    // when the new repo uses 'origin/main'), which would cause a transient
-    // "invalid-base" error every time the user switches between repos.
+    // Why: reset to null so that effectiveBaseRef becomes falsy until the IPC resolves, so branch compare can't fire with a stale defaultBaseRef from a different repo (transient "invalid-base" on switch).
     setDefaultBaseRef(null)
 
     let stale = false
@@ -1457,17 +1396,13 @@ function SourceControlInner(): React.JSX.Element {
     )
       .then((result) => {
         if (!stale) {
-          // Why: IPC now returns a `{ defaultBaseRef, remoteCount }` envelope;
-          // this component only needs `defaultBaseRef`. `remoteCount` is used
-          // by BaseRefPicker for the multi-remote hint.
+          // IPC returns a { defaultBaseRef, remoteCount } envelope; only defaultBaseRef is needed here (remoteCount powers BaseRefPicker's multi-remote hint).
           setDefaultBaseRef(result.defaultBaseRef)
         }
       })
       .catch((err) => {
         console.error('[SourceControl] getBaseRefDefault failed', err)
-        // Why: leave defaultBaseRef null on failure instead of fabricating
-        // 'origin/main'. effectiveBaseRef stays falsy, so branch compare and
-        // PR fetch skip running against a ref that may not exist.
+        // Why: leave defaultBaseRef null on failure (not a fabricated 'origin/main') so branch compare/PR fetch skip a possibly-nonexistent ref.
         if (!stale) {
           setDefaultBaseRef(null)
         }
@@ -1477,8 +1412,7 @@ function SourceControlInner(): React.JSX.Element {
       stale = true
     }
   }, [
-    // Why: only repo/host ownership changes should reset the base; unrelated
-    // repo metadata churn must not indirectly restart eligibility's timeout.
+    // Why: only repo/host ownership changes should reset the base; unrelated metadata churn must not restart eligibility's timeout.
     activeRepoConnectionId,
     activeRepoExecutionHostId,
     activeRepoId,
@@ -1519,8 +1453,7 @@ function SourceControlInner(): React.JSX.Element {
     repoBaseRef: normalizedRepoBaseRef,
     defaultBaseRef
   })
-  // Why: the compare/diff view uses this base; the PR/rebase merge target keeps
-  // using effectiveBaseRef. When the setting is off, this equals effectiveBaseRef.
+  // Why: the compare/diff view uses this base; the PR/rebase merge target keeps effectiveBaseRef (equal when the setting is off).
   const compareBaseRef = resolveSourceControlCompareBaseRef({
     enabled: settings?.sourceControlCompareAgainstUpstream ?? false,
     worktreeBaseRef: normalizedWorktreeBaseRef,
@@ -1600,9 +1533,7 @@ function SourceControlInner(): React.JSX.Element {
     hostedReviewCreationRequestMatchesCurrent &&
     hostedReviewCreationRequestState.status === 'loading' &&
     hostedReview === null
-  // Why: without a linked review or probe result the provider is unknown; infer
-  // it from the remote host so a GitLab (etc.) repo shows its own review copy
-  // instead of the GitHub default during loading and after a probe failure.
+  // Why: infer provider from the remote host when unknown, so a GitLab (etc.) repo shows its own review copy instead of the GitHub default.
   const remoteInferredHostedReviewProvider = useMemo(
     () => parseRemoteRepo(activeRepo?.gitRemoteIdentity?.remoteUrl ?? '')?.provider ?? null,
     [activeRepo?.gitRemoteIdentity?.remoteUrl]
@@ -1680,9 +1611,7 @@ function SourceControlInner(): React.JSX.Element {
     provisionalHostedReviewProvider
   ])
   const hostedReviewCreationForHeader = useMemo(() => {
-    // Why: a fresh preflight must disable stale Create PR eligibility while
-    // upstream/dirty/base state is reconciling after commit or push, while
-    // preserving provider copy from the previous safe snapshot.
+    // Why: during a fresh preflight, disable stale Create PR eligibility while state reconciles, but preserve provider copy from the last snapshot.
     if (isHostedReviewCreationLoading) {
       const provider = resolveHostedReviewCreationProviderForTarget(
         hostedReviewCreationProviderHintRef.current,
@@ -1708,12 +1637,7 @@ function SourceControlInner(): React.JSX.Element {
     linkedAzureDevOpsPR,
     linkedGiteaPR
   })
-  // Why: when activeRepo.connectionId is truthy, neither the SourceControl
-  // effect below nor WorktreeCard.tsx fetches hostedReview for this branch,
-  // so hostedReviewEntry would stay undefined forever and would permanently
-  // block Publish Branch on SSH-backed worktrees with linked review metadata
-  // and no upstream. Skip the loading state for those repos so the publish
-  // gate doesn't latch.
+  // Why: SSH-backed (connectionId) repos never fetch hostedReview, so skip the loading state or it would permanently block Publish Branch.
   const isHostedReviewStateLoading =
     !activeRepo?.connectionId && hasHostedReviewLink && hostedReviewEntry === undefined
   const hasResolvableReviewPushTargetLink = hasResolvableHostedReviewPushTargetLink({
@@ -1722,8 +1646,7 @@ function SourceControlInner(): React.JSX.Element {
     linkedGitLabMR
   })
   useEffect(() => {
-    // Why: resolving review heads can hit provider/SSH APIs, so keep it tied
-    // to the visible Source Control branch view like the adjacent PR polling.
+    // Why: resolving review heads can hit provider/SSH APIs; gate on the visible branch view like the adjacent PR polling.
     if (!isBranchVisible || isFolder || !activeWorktreeId || activeWorktree?.pushTarget) {
       return
     }
@@ -1779,10 +1702,7 @@ function SourceControlInner(): React.JSX.Element {
     ) {
       return
     }
-    // Why: the Source Control panel renders branch review status directly.
-    // When a terminal checkout moves this worktree onto a new branch, fetch
-    // immediately; carry a known PR number because branch lookup is lossy for
-    // fork/deleted-head PRs.
+    // Why: fetch review immediately on branch change; carry a known PR number because branch lookup is lossy for fork/deleted-head PRs.
     void fetchHostedReviewForBranch(activeRepo.path, branchName, {
       repoId: activeRepo.id,
       linkedGitHubPR,
@@ -1793,8 +1713,7 @@ function SourceControlInner(): React.JSX.Element {
       linkedGiteaPR,
       staleWhileRevalidate: true
     })
-    // Why: the GitHub-specific cache powers grouping/check panels; keep that
-    // refresh behind the coordinator so Source Control does not bypass pacing.
+    // Why: keep the GitHub cache refresh behind the coordinator so Source Control doesn't bypass pacing.
     enqueueGitHubPRRefresh(activeWorktreeId, 'swr', 30)
   }, [
     activeRepo,
@@ -1812,12 +1731,7 @@ function SourceControlInner(): React.JSX.Element {
     linkedGiteaPR
   ])
 
-  // Why: eligibility is recomputed below, after prGenerating / isCreatingPr are
-  // available, so the effect can pause refetches while a user-initiated PR flow
-  // is in flight. AI generation runs `git fetch` + `git rebase`, which mutates
-  // ahead/behind counts; without this guard the next refetch would return
-  // canCreate:false (typically needs_push), flip primaryAction.kind off
-  // create_pr, unmount the composer, and cancel the in-flight generation.
+  // Why: eligibility is recomputed later to pause refetches during an in-flight PR flow, since AI gen's fetch+rebase would flip canCreate off and cancel generation.
 
   const grouped = useMemo(() => {
     const groups: SourceControlEntryGroups = { staged: [], unstaged: [], untracked: [] }
@@ -1870,8 +1784,7 @@ function SourceControlInner(): React.JSX.Element {
       roots[section.id] =
         section.id === 'conflicts'
           ? applyGitStatusEntryAreasToSourceControlTree(
-              // Why: conflict rows can mirror normal paths, so their folder
-              // collapse keys must not share state with normal area sections.
+              // Why: conflict rows can mirror normal paths, so their folder collapse keys must not share state with normal sections.
               namespaceSourceControlTreeDirectoryKeys(sectionRoots, 'conflicts')
             )
           : sectionRoots
@@ -1899,8 +1812,7 @@ function SourceControlInner(): React.JSX.Element {
     submoduleStatusByKey
   ])
 
-  // List view needs the same lazy submodule expansion as the tree view, just
-  // spliced into the flat entry list instead of the tree-row list.
+  // List view needs the same lazy submodule expansion as tree view, spliced into the flat entry list.
   const visibleListRowsBySection = useMemo(() => {
     const rows: Partial<Record<SourceControlDisplaySectionId, RenderableSubmoduleListItem[]>> = {}
     for (const section of displaySections) {
@@ -1926,9 +1838,7 @@ function SourceControlInner(): React.JSX.Element {
 
   const visibleSelectionEntries = useMemo(() => {
     const arr: FlatEntry[] = []
-    // Why: list view splices lazily-loaded submodule child rows into the
-    // rendered list, so selection/range/open-key bookkeeping must read the same
-    // injected rows instead of the pre-injection flat entries.
+    // Why: list view splices in lazy submodule rows, so selection/range bookkeeping must read the injected rows, not the pre-injection entries.
     if (sourceControlViewMode === 'list') {
       for (const section of displaySections) {
         if (collapsedSections.has(section.id)) {
@@ -2039,11 +1949,7 @@ function SourceControlInner(): React.JSX.Element {
     sourceControlAiActionsVisible
   ])
 
-  // Why: orphaned draft/error/in-flight entries accumulate when worktrees are
-  // removed from the store (long sessions with many create/destroy cycles).
-  // Prune them so a deleted-then-reused worktree ID doesn't inherit stale
-  // state — especially commitInFlightRef, which would permanently disable
-  // Commit for that ID if left stuck at `true`.
+  // Why: prune per-worktree state for removed worktrees so a reused ID doesn't inherit stale state (e.g. a stuck commitInFlightRef disabling Commit).
   useEffect(() => {
     const pruneRecord = <T,>(prev: Record<string, T>): Record<string, T> => {
       let changed = false
@@ -2102,9 +2008,7 @@ function SourceControlInner(): React.JSX.Element {
   }, [commitDrafts])
 
   useEffect(() => {
-    // Why: users often finish merge/rebase conflicts in a terminal. Once git
-    // status observes that operation end, the old Source Control failure banner
-    // is stale and should not survive the successful external continue/abort.
+    // Why: conflicts are often resolved in a terminal; clear the stale failure banner once git status sees the operation end.
     const previousConflictOperations = previousConflictOperationsRef.current
     setRemoteActionErrors((prev) =>
       clearRemoteActionErrorsForCompletedConflictOperations({
@@ -2116,10 +2020,7 @@ function SourceControlInner(): React.JSX.Element {
     previousConflictOperationsRef.current = conflictOperationsByWorktree
   }, [conflictOperationsByWorktree])
 
-  // Why: the sidebar no longer uses key={activeWorktreeId} to force a full
-  // remount on worktree switch (that caused an IPC storm on Windows).
-  // Instead, reset worktree-specific local state here so the previous
-  // worktree's UI state doesn't leak into the new one.
+  // Why: reset worktree-specific state manually instead of key-remounting on switch (which caused a Windows IPC storm).
   useEffect(() => {
     setFilterExpanded(false)
     setCollapsedSections(createDefaultCollapsedSections())
@@ -2128,24 +2029,13 @@ function SourceControlInner(): React.JSX.Element {
     setPendingDiscard(null)
     setPendingDiffCommentsClear(null)
     setIsClearingDiffComments(false)
-    // Why: do NOT reset defaultBaseRef here. It is repo-scoped, not
-    // worktree-scoped, and is resolved by the effect above on activeRepo
-    // change. Resetting it to a hard-coded 'origin/main' on every worktree
-    // switch within the same repo clobbered the correct value (e.g.
-    // 'origin/master' for repos whose default branch isn't main), causing
-    // a persistent "Branch compare unavailable" until the user switched
-    // repos and back to re-trigger the resolver.
+    // Why: don't reset defaultBaseRef here — it's repo-scoped (resolved on activeRepo change); resetting would clobber non-main defaults.
     setFilterQuery('')
     setIsExecutingBulk(false)
-    // Why: no reset for commit-in-flight state — it now lives in a per-worktree
-    // map, so it cannot leak across worktrees. Resetting here would actually
-    // clear in-flight state for the *incoming* worktree if the user is coming
-    // back to a worktree mid-commit, re-enabling the button while the commit
-    // still runs.
+    // Why: don't reset commit-in-flight state — it's per-worktree; resetting would re-enable Commit for an incoming worktree mid-commit.
   }, [activeWorktreeId])
 
-  // Why: returns true on success so compound actions ("Commit & Push" etc.)
-  // can skip the follow-up remote operation when the commit itself failed.
+  // Why: returns true on success so compound actions can skip the follow-up remote op when the commit failed.
   const handleCommit = useCallback(
     async (
       messageOverride?: string,
@@ -2201,12 +2091,7 @@ function SourceControlInner(): React.JSX.Element {
           return false
         }
 
-        // Why: the textarea stays enabled during the in-flight commit (only the
-        // button is disabled), so the user can keep typing after clicking Commit.
-        // Unconditionally clearing the draft here would silently discard those
-        // in-progress edits — the commit used the OLD `message` captured in this
-        // closure, so the dropped text would never have been committed either.
-        // Only clear when the current draft still matches what we committed.
+        // Why: textarea stays editable during commit, so only clear the draft when it still matches what we committed — else we'd discard edits typed after Commit.
         updateCommitDrafts((prev) => {
           const current = prev[target.worktreeId]
           if (current !== undefined && current.trim() !== message) {
@@ -2219,21 +2104,7 @@ function SourceControlInner(): React.JSX.Element {
         if (!options?.target) {
           void refreshActiveGitStatusAfterMutation()
         }
-        // Why: flip branchSummary to 'loading' synchronously so the empty-state
-        // guard
-        //   (!hasUncommittedEntries && branchSummary.status === 'ready' &&
-        //    branchEntries.length === 0)
-        // doesn't briefly read true between setGitStatus clearing the
-        // uncommitted list and the next branchCompare poll landing the new
-        // commit. Without this flip "No changes on this branch" flashes for
-        // the full poll-interval window.
-        //
-        // Then fire-and-forget refreshBranchCompare so the "Committed on
-        // Branch" section repopulates as soon as the IPC returns instead of
-        // waiting for the next poll. Unawaited on purpose:
-        // compound flows (runCompoundCommitAction) need handleCommit to
-        // resolve immediately so the push step starts without delay. Errors
-        // here are best-effort — the polling tick will retry.
+        // Why: flip branchSummary to 'loading' synchronously so "No changes on this branch" doesn't flash before the branchCompare poll lands the commit.
         if (!options?.target && compareBaseRef) {
           beginGitBranchCompareRequest(
             target.worktreeId,
@@ -2329,8 +2200,7 @@ function SourceControlInner(): React.JSX.Element {
         )
 
         if (!result.success) {
-          // Why: cancellation is a deliberate user action, not a failure to
-          // surface. Clear any prior error and stay quiet.
+          // Why: cancellation is a deliberate user action, not a failure to surface.
           if (result.canceled) {
             setGenerateErrors((prev) => ({ ...prev, [activeWorktreeId]: null }))
             updateCommitMessageGenerationRecord(activeCommitMessageGenerationKey, (record) =>
@@ -2364,9 +2234,7 @@ function SourceControlInner(): React.JSX.Element {
             message: result.message
           })
         )
-        // Why: race protection — the user may have started typing into the
-        // textarea while the agent was running. In that case we silently drop
-        // the generated message rather than overwrite their in-progress edits.
+        // Why: race protection — drop the generated message if the user typed into the textarea while the agent ran, rather than overwrite their edits.
         updateCommitDrafts((prev) => {
           const current = prev[activeWorktreeId]
           if (current && current.length > 0) {
@@ -2495,9 +2363,7 @@ function SourceControlInner(): React.JSX.Element {
       resolveCommitMessageGenerationCancel(record)
     )
     const connectionId = getConnectionId(activeWorktreeId) ?? undefined
-    // Why: fire-and-forget — the in-flight generateCommitMessage promise
-    // resolves with `{canceled: true}` once the kill propagates, which is
-    // where the spinner is cleared. Awaiting here would just delay UI feedback.
+    // Why: fire-and-forget; the in-flight promise resolves {canceled: true} where the spinner clears, so awaiting would just delay UI feedback.
     void cancelRuntimeGenerateCommitMessage({
       // Why: route the cancel by the repo OWNER host, not the focused runtime.
       settings: activeRepoSettings,
@@ -2513,14 +2379,8 @@ function SourceControlInner(): React.JSX.Element {
     worktreePath
   ])
 
-  // Why: a single dispatcher for every remote-only action the split button or
-  // chevron dropdown can trigger. Keeps the error-swallow pattern in one
-  // place — store slices already surface actionable toasts, so additional
-  // try/catch here would duplicate the notification.
-  // Why: callers must distinguish real failures from "a newer remote action won
-  // the sequence" and "this call was a no-op (missing target/base)". Collapsing
-  // those into `{ ok: false, error: null }` made Create PR treat supersession as
-  // a destructive remote failure.
+  // Why: single dispatcher for remote-only actions; error-swallow lives here since store slices already surface actionable toasts.
+  // Why: statuses distinguish real failures from supersession and no-ops; collapsing to { ok: false } made Create PR treat supersession as a destructive failure.
   type RunRemoteActionResult =
     | { status: 'ok' }
     | { status: 'failed'; error: SourceControlActionError }
@@ -2584,10 +2444,7 @@ function SourceControlInner(): React.JSX.Element {
           return { status: 'ok' }
         }
         if (kind === 'push') {
-          // Why: kind 'push' must stay a regular push. Force-with-lease is only
-          // for kind 'force_push' (and callers that choose it). Auto-upgrading
-          // here made the always-enabled dropdown Push row silently force-push
-          // while its tooltip claimed a normal push might merely fail.
+          // Why: kind 'push' must stay a regular push; auto-upgrading made the always-enabled dropdown Push row silently force-push against its tooltip.
           await pushBranch(
             target.worktreeId,
             target.worktreePath,
@@ -2672,10 +2529,7 @@ function SourceControlInner(): React.JSX.Element {
         }
         return { status: 'ok' }
       } catch (error) {
-        // Why: remote action failures are surfaced by editor-slice actions to keep
-        // one consistent toast path and avoid duplicate notifications in the UI.
-        // Keep the latest failure inline too: dropdown-only actions like Fetch can
-        // otherwise look like nothing happened once the menu closes.
+        // Why: editor-slice actions own the failure toast; keep the latest failure inline too since dropdown-only actions like Fetch look silent once the menu closes.
         if (remoteActionErrorSequenceByWorktreeRef.current[target.worktreeId] !== sequence) {
           return { status: 'superseded' }
         }
@@ -2821,23 +2675,14 @@ function SourceControlInner(): React.JSX.Element {
     [handleAbortMerge, handleAbortRebase]
   )
 
-  // Why: compound actions must commit first and only run the follow-up remote
-  // op when the commit succeeds. handleCommit's return value carries that
-  // signal — a failure leaves commitError populated and short-circuits here
-  // so we never push a commit the user didn't actually land. The primary
-  // button never takes this path (it always emits a single-action kind);
-  // compound flows are reached only from the dropdown, which offers
-  // 'commit_push' and 'commit_sync' (there is no 'Commit & Publish' row).
+  // Why: commit first and run the follow-up remote op only if handleCommit succeeded, so we never push a commit the user didn't land.
   const runCompoundCommitAction = useCallback(
     async (remoteKind: 'push' | 'sync'): Promise<void> => {
       const ok = await handleCommit()
       if (!ok) {
         return
       }
-      // Why: "Commit & Force Push" still invokes remoteKind 'push' from the
-      // dropdown kind map. Route to force_push when the upstream shape requires
-      // lease force so compound commit does not silently fall back to a regular
-      // push after we stopped auto-upgrading kind 'push'.
+      // Why: "Commit & Force Push" maps to remoteKind 'push', so route to force_push when the upstream shape requires lease force (kind 'push' no longer auto-upgrades).
       if (
         remoteKind === 'push' &&
         shouldForcePushWithLeaseForUpstream(remoteStatusForActions ?? remoteStatus)
@@ -2962,8 +2807,7 @@ function SourceControlInner(): React.JSX.Element {
   }, [setRightSidebarOpen, setRightSidebarTab])
 
   const handleBranchChangedByPullRequestGeneration = useCallback(async (): Promise<void> => {
-    // Why: AI PR detail generation may rebase before summarizing; if HEAD moved,
-    // refresh status before letting the user submit the generated draft.
+    // Why: AI PR detail generation may rebase before summarizing, so refresh status if HEAD moved before the user submits the draft.
     await refreshActiveGitStatusAfterMutation()
   }, [refreshActiveGitStatusAfterMutation])
 
@@ -2993,8 +2837,7 @@ function SourceControlInner(): React.JSX.Element {
         runtimeTargetSettings: activeRepoSettings
       }
       const seed = { ...fields }
-      // Why: SourceControl can unmount on tab switches; persisting the running
-      // record lets the embedded PR composer resume when the user returns.
+      // Why: SourceControl can unmount on tab switches; the persisted record lets the PR composer resume on return.
       setPullRequestGenerationRecord(
         generationKey,
         createRunningPullRequestGenerationRecord(context, seed, fieldRevisions)
@@ -3091,8 +2934,7 @@ function SourceControlInner(): React.JSX.Element {
       return resolvePullRequestGenerationCancel(current)
     })
     void cancelRuntimeGeneratePullRequestFields({
-      // Why: the user can switch hosts while generation runs; cancel the
-      // original request owner instead of the current focused host.
+      // Why: the user can switch hosts while generation runs; cancel the original request owner, not the focused host.
       settings: record.context.runtimeTargetSettings,
       worktreeId: record.context.worktreeId,
       worktreePath: record.context.worktreePath,
@@ -3203,8 +3045,7 @@ function SourceControlInner(): React.JSX.Element {
   ])
 
   useEffect(() => {
-    // Why: on Source Control remount, the PR fields hook seeds eligibility
-    // defaults in an effect; hydrating before that effect runs gets overwritten.
+    // Why: on remount the PR fields hook seeds eligibility defaults in an effect; hydrating before it runs gets overwritten.
     if (
       !activePullRequestGenerationKey ||
       !activePullRequestGenerationRecord ||
@@ -3245,8 +3086,7 @@ function SourceControlInner(): React.JSX.Element {
   ])
 
   useEffect(() => {
-    // Why: direct commit-message generation can finish after Source Control
-    // unmounts; the store record lets the remounted textarea consume it once.
+    // Why: generation can finish after Source Control unmounts; the store record lets the remounted textarea consume it once.
     if (
       !activeCommitMessageGenerationKey ||
       !activeWorktreeId ||
@@ -3291,10 +3131,7 @@ function SourceControlInner(): React.JSX.Element {
       setHostedReviewCreationRequestState(null)
       return
     }
-    // Why: skip refetches while the user's PR flow is mid-flight. AI generation,
-    // Create PR intent, and submission can all perturb ahead/behind or dirty
-    // state temporarily. Recomputing eligibility mid-flow can tear down the
-    // composer or rotate dropdown hints before the final refresh restores truth.
+    // Why: skip refetches while a PR flow is mid-flight — recomputing eligibility then can tear down the composer before the final refresh restores truth.
     if (prGenerating || isCreatingPr || isCreatePrIntentInFlight) {
       setHostedReviewCreationRequestState(null)
       return
@@ -3306,8 +3143,7 @@ function SourceControlInner(): React.JSX.Element {
       branch: branchName,
       status: 'loading'
     })
-    // Why: upstream/status changes can make the previous eligibility unsafe
-    // to click while the new preflight is still resolving.
+    // Why: upstream/status changes can make the previous eligibility unsafe to click while the new preflight resolves.
     setHostedReviewCreationState(null)
     void getHostedReviewCreationEligibility({
       repoPath: activeRepoPath,
@@ -3342,8 +3178,7 @@ function SourceControlInner(): React.JSX.Element {
         if (stale) {
           return
         }
-        // Why: a failed remote probe can provide branch guidance, but it cannot
-        // authorize hosted-review creation.
+        // Why: a failed remote probe can give branch guidance but cannot authorize hosted-review creation.
         const localBlocker = buildLocalBlockerHostedReviewCreationEligibility(
           resolveCurrentHostedReviewCreationProvider(),
           {
@@ -3418,8 +3253,7 @@ function SourceControlInner(): React.JSX.Element {
     }
 
     if (!hostedReviewCreation.canCreate) {
-      // Why: blocked Create Review clicks are intentional for actionable states;
-      // the inline notice tells users which prerequisite to clear next.
+      // Why: blocked Create Review clicks are intentional; the inline notice tells the user which prerequisite to clear.
       const message = resolveBlockedCreateReviewNoticeMessage(hostedReviewCreation)
       if (message) {
         setCreatePrIntentNoticeForWorktree(activeWorktreeId, {
@@ -3633,8 +3467,7 @@ function SourceControlInner(): React.JSX.Element {
           }
           if (generated.success) {
             fields = {
-              // Why: Create PR intent auto-submits; generated details should
-              // not retarget the review without user confirmation.
+              // Why: intent auto-submits, so generated details must not retarget the review without confirmation.
               base: fields.base,
               title: generated.fields.title.trim() || fields.title,
               body: generated.fields.body,
@@ -3785,8 +3618,7 @@ function SourceControlInner(): React.JSX.Element {
       beginGitBranchCompareRequest(token.worktreeId, requestKey, baseRef)
       const result = await getRuntimeGitBranchCompare(
         {
-          // Why: the intent flow may continue after a worktree switch; use the
-          // token's original host target, not whatever branch is focused later.
+          // Why: intent may continue after a worktree switch; use the token's original host target, not whatever is focused later.
           settings: activeRepoSettings,
           worktreeId: token.worktreeId,
           worktreePath: token.worktreePath,
@@ -3857,8 +3689,7 @@ function SourceControlInner(): React.JSX.Element {
       }
       const target = getCreatePrIntentOperationTarget(token)
       return await refreshGitStatusForWorktreeStrict({
-        // Why: Create PR intent can finish in the background after navigation,
-        // but branch-safety checks must inspect the worktree that started it.
+        // Why: intent can finish in the background after navigation; branch-safety checks must inspect the worktree that started it.
         settings: target.settings,
         worktreeId: target.worktreeId,
         worktreePath: target.worktreePath,
@@ -3902,8 +3733,7 @@ function SourceControlInner(): React.JSX.Element {
       worktreeId: activeWorktreeId,
       worktreePath,
       branch: branchName,
-      // Why: Create PR intent crosses async commit/push steps; the review
-      // target must stay tied to the base selected when the run started.
+      // Why: intent crosses async commit/push steps, so the base stays tied to what was selected when the run started.
       baseRef: effectiveBaseRef ?? null
     })
     const operationTarget = getCreatePrIntentOperationTarget(token)
@@ -3936,9 +3766,7 @@ function SourceControlInner(): React.JSX.Element {
         if (!refreshed) {
           return false
         }
-        // Why: terminal checkouts are observed by this strict status snapshot
-        // before React updates createPrIntentCurrentTargetRef. Stop before the
-        // intent flow stages, commits, or pushes on a different branch.
+        // Why: a terminal checkout may land in this snapshot before React updates the target ref; stop before staging/committing/pushing on a different branch.
         if (!createPrIntentGitStatusMatchesToken(token, refreshed.status)) {
           abortedByStaleTarget = true
           return false
@@ -3974,10 +3802,7 @@ function SourceControlInner(): React.JSX.Element {
         return
       }
 
-      // Why: fast-forward behind-only *before* commit so a dirty worktree does
-      // not become ahead+behind after Create PR commits, then dead-end at the
-      // explicit sync-first stop. --ff-only refuses if the branch diverged mid
-      // flight or local edits would be overwritten — never auto-merges.
+      // Why: fast-forward behind-only before commit so a dirty worktree can't become ahead+behind and dead-end at the sync-first stop; --ff-only never auto-merges.
       if (isBehindOnlyUpstream(latestUpstreamStatus)) {
         setCreatePrIntentNoticeForWorktree(token.worktreeId, {
           tone: 'muted',
@@ -4078,9 +3903,7 @@ function SourceControlInner(): React.JSX.Element {
           return
         }
         if (!committed) {
-          // Why: pre-commit/lint hooks may rewrite tracked files before
-          // failing. Re-stage those safe hook outputs so retrying Create PR
-          // does not strand changes outside the intended all-in commit.
+          // Why: pre-commit/lint hooks may rewrite tracked files before failing; re-stage those outputs so retrying Create PR doesn't strand changes.
           if (await refreshIntentSnapshot()) {
             await stageLatestIntentPaths()
           }
@@ -4143,8 +3966,7 @@ function SourceControlInner(): React.JSX.Element {
       if (remoteStep === 'blocked' || remoteStep === 'none') {
         setCreatePrIntentNoticeForWorktree(token.worktreeId, {
           tone: 'muted',
-          // Why: a diverged branch is deliberately not auto-prepared (that would
-          // merge without consent), so keep the explicit sync-first guidance.
+          // Why: a diverged branch is deliberately not auto-prepared (would merge without consent), so keep explicit sync-first guidance.
           message:
             eligibility.blockedReason === 'needs_sync'
               ? translate(
@@ -4161,8 +3983,7 @@ function SourceControlInner(): React.JSX.Element {
 
       setCreatePrIntentNoticeForWorktree(token.worktreeId, {
         tone: 'muted',
-        // Why: keep each translate() call on a string-literal key so the
-        // localization-catalog verifier can statically detect every key.
+        // Why: keep each translate() key a string literal so the localization-catalog verifier can statically detect it.
         message:
           remoteStep === 'publish'
             ? translate(
@@ -4468,10 +4289,7 @@ function SourceControlInner(): React.JSX.Element {
     ]
   )
 
-  // Why: maps both the primary button click and any chevron dropdown item
-  // click to the right handler. Commit-ish kinds flow through handleCommit
-  // (which returns a boolean); compound actions use runCompoundCommitAction;
-  // pure remote actions go through runRemoteAction.
+  // Dispatch primary + dropdown action kinds to their handlers.
   const handleActionInvoke = useCallback(
     (kind: DropdownActionKind): void => {
       if (prGenerating || isCreatingPr || isCreatePrIntentInFlight) {
@@ -4524,8 +4342,7 @@ function SourceControlInner(): React.JSX.Element {
     ]
   )
 
-  // Why: modifier-click should keep the current pane intact by opening the
-  // selected Source Control file in a fresh split to the right.
+  // Why: modifier-click keeps the current pane intact by opening the file in a fresh split to the right.
   const resolveSplitTargetGroupId = useCallback(
     (event?: SourceControlRowOpenEvent): string | undefined => {
       if (!event || !activeWorktreeId || !isSourceControlSplitOpenModifier(event, isMac)) {
@@ -4541,10 +4358,7 @@ function SourceControlInner(): React.JSX.Element {
     [activeGroupIdByWorktree, activeWorktreeId, createEmptySplitGroup, groupsByWorktree, isMac]
   )
 
-  // Why: a stable string signature keeps this selector referentially stable so
-  // the panel only re-renders when the active editor file (or its diff source)
-  // actually changes. Gated on the visible tab being an editor so the highlight
-  // clears when the user switches to a terminal or browser surface.
+  // Why: a stable string signature keeps this selector referentially stable so the panel re-renders only when the active editor file changes; null when the tab isn't an editor.
   const activeOpenFileSignature = useAppStore((s) => {
     if (!activeWorktreeId) {
       return null
@@ -4597,14 +4411,7 @@ function SourceControlInner(): React.JSX.Element {
       }
       const language = detectLanguage(entry.path)
       const filePath = joinPath(worktreePath, entry.path)
-      // Why: unstaged markdown diffs open as a normal edit tab in Changes
-      // view mode rather than a dedicated diff tab. This unifies sidebar
-      // clicks with the header's Edit|Changes toggle: there is exactly one
-      // tab per markdown file, and the sidebar click flips that tab's view
-      // mode. Staged diffs still open as a separate diff tab because the
-      // staged content is not what the editor would be editing. Non-markdown
-      // files keep the existing diff-tab flow until the diff-tab type is
-      // eventually collapsed (see reviews/changes-view-mode-plan.md §"Follow-up").
+      // Why: unstaged markdown diffs open as an edit tab in Changes view (one tab per file); staged diffs still get a separate diff tab since that isn't what the editor edits.
       if (language === 'markdown' && entry.area === 'unstaged') {
         openFile(
           {
@@ -4825,10 +4632,7 @@ function SourceControlInner(): React.JSX.Element {
     ]
   )
 
-  // Why: 'stage' primary stages every unstaged + untracked path in one
-  // bulkStage call. It bypasses handleActionInvoke because that handler is
-  // typed to DropdownActionKind and 'stage' is intentionally not in the
-  // dropdown union — the dropdown surface is unchanged.
+  // Why: bypasses handleActionInvoke because that handler is typed to DropdownActionKind and 'stage' is intentionally not in the dropdown union.
   const handleStageAllPrimary = useCallback(async (): Promise<void> => {
     if (!worktreePath || isExecutingBulk) {
       return
@@ -4868,22 +4672,14 @@ function SourceControlInner(): React.JSX.Element {
     refreshActiveGitStatusAfterMutation
   ])
 
-  // Why: PrimaryActionKind is narrowed to the single-action kinds the
-  // primary can emit ('commit' | 'stage' | 'push' | 'pull' | 'sync' |
-  // 'publish' | 'create_pr') — compound commit_* kinds are dropdown-only. An exhaustive
-  // switch keeps the mapping honest: if a new PrimaryActionKind is added,
-  // TypeScript lights up the missing case instead of silently falling
-  // through. 'stage' routes to a dedicated primary-only handler because
-  // handleActionInvoke is typed to DropdownActionKind.
+  // Why: 'stage' routes to a primary-only handler since handleActionInvoke is typed to DropdownActionKind (compound commit_* kinds are dropdown-only).
   const handlePrimaryClick = useCallback((): void => {
     switch (primaryAction.kind) {
       case 'stage':
         void handleStageAllPrimary()
         return
       case 'push':
-        // Why: primary labels "Force Push" while keeping kind 'push'. Invoke the
-        // explicit force path when lease force is required so regular push stays
-        // non-force for the dropdown.
+        // Why: primary labels "Force Push" but keeps kind 'push', so invoke the explicit force path when lease force is required.
         handleActionInvoke(
           shouldForcePushWithLeaseForUpstream(remoteStatusForActions ?? remoteStatus)
             ? 'force_push'
@@ -4938,13 +4734,7 @@ function SourceControlInner(): React.JSX.Element {
     const existingSummary =
       useAppStore.getState().gitBranchCompareSummaryByWorktree[activeWorktreeId]
 
-    // Why: only show the loading spinner for the very first branch compare
-    // request, or when the base ref has changed (user picked a new one, or
-    // getBaseRefDefault corrected a stale cross-repo value).  Polling retries
-    // — whether the previous result was 'ready' *or* an error — keep the
-    // current UI visible until the new IPC result arrives.  Resetting to
-    // 'loading' on every poll when the compare is in an error state caused a
-    // visible loading→error→loading→error flicker.
+    // Why: only reset to 'loading' on the first request or a base-ref change; resetting on every poll caused a visible loading→error→loading flicker.
     const baseRefChanged = existingSummary && existingSummary.baseRef !== compareBaseRef
     const shouldResetToLoading = !existingSummary || baseRefChanged
     if (shouldResetToLoading) {
@@ -5002,10 +4792,7 @@ function SourceControlInner(): React.JSX.Element {
 
     branchCompareInFlightRef.current = true
     const runPromise = (async (): Promise<void> => {
-      // Why: branch compare shells out to git from both event-driven refreshes
-      // and the fallback timer. Keep one compare chain in flight and
-      // collapse skipped ticks into one trailing refresh instead of stacking
-      // subprocesses while preserving the await contract for direct callers.
+      // Why: keep one branch-compare chain in flight and collapse skipped ticks into one trailing refresh instead of stacking git subprocesses.
       try {
         await runBranchCompare()
       } finally {
@@ -5130,8 +4917,7 @@ function SourceControlInner(): React.JSX.Element {
       return
     }
 
-    // Why: pushing a branch can move its remote-tracking base and ahead count
-    // without changing local HEAD, so the HEAD-change effect alone misses it.
+    // Why: pushing a branch can move its remote base and ahead count without changing local HEAD, which the HEAD-change effect alone misses.
     const current = {
       ahead: remoteStatus?.ahead ?? null,
       baseRef: compareBaseRef,
@@ -5162,8 +4948,7 @@ function SourceControlInner(): React.JSX.Element {
       return
     }
 
-    // Why: git-status HEAD changes refresh branch compare immediately. Keep a
-    // visible-window fallback for base refs or remote updates that do not move HEAD.
+    // Why: HEAD changes refresh branch compare immediately; keep a visible-window fallback for base/remote updates that don't move HEAD.
     return installWindowVisibilityInterval({
       run: () => void refreshBranchCompareRef.current(),
       intervalMs: BRANCH_REFRESH_INTERVAL_MS
@@ -5171,10 +4956,7 @@ function SourceControlInner(): React.JSX.Element {
   }, [activeWorktreeId, compareBaseRef, isBranchVisible, isFolder, worktreePath])
 
   useEffect(() => {
-    // Why: when the compare-base policy resolves to no base, runBranchCompare
-    // bails out; drop any stale summary so the
-    // committed-changes section and "vs" row disappear and only the working tree
-    // shows. Wait until upstream status has loaded so the summary doesn't flicker.
+    // Why: when compare-base resolves to no base, drop the stale summary (gate on loaded upstream status to avoid flicker).
     if (
       !activeWorktreeId ||
       !shouldClearBranchCompareForMissingBase({ isFolder, compareBaseRef, remoteStatus })
@@ -5185,15 +4967,13 @@ function SourceControlInner(): React.JSX.Element {
   }, [activeWorktreeId, clearGitBranchCompare, compareBaseRef, isFolder, remoteStatus])
 
   useEffect(() => {
-    // Why: history shells out to git. Defer the first load until the user
-    // expands Commits so source control stays cheap for large/remote repos.
+    // Why: history shells out to git; defer first load until the user expands Commits so source control stays cheap for large/remote repos.
     if (!isBranchVisible || !isGitHistoryExpanded || !isGitHistoryVisible) {
       return
     }
     void refreshGitHistoryRef.current()
   }, [
-    // Why: history is fetched with compareBaseRef, so re-run when the upstream
-    // compare base changes — effectiveBaseRef can stay put while it moves.
+    // Why: history is fetched with compareBaseRef, so re-run when it changes (effectiveBaseRef can stay put while it moves).
     activeWorktreeId,
     compareBaseRef,
     isBranchVisible,
@@ -5204,10 +4984,7 @@ function SourceControlInner(): React.JSX.Element {
   ])
 
   useEffect(() => {
-    // Why: gate on isBranchVisible so we don't spawn git processes while the
-    // sidebar is closed. Store-slice remote operations refresh upstream-status
-    // on success anyway, so the user's first sidebar open will show accurate
-    // state.
+    // Why: gate on isBranchVisible so we don't spawn git processes while the sidebar is closed.
     if (!activeWorktreeId || !worktreePath || isFolder || !isBranchVisible) {
       return
     }
@@ -5284,17 +5061,7 @@ function SourceControlInner(): React.JSX.Element {
       resolveSplitTargetGroupId
     })
 
-  // Why: a note's filePath is the same relative path used by GitStatusEntry /
-  // GitBranchChangeEntry, so we can route the click to whichever diff surface
-  // currently owns that file. Prefer the `unstaged` entry when a path is also
-  // staged — diff comments are authored against the working-tree (unstaged)
-  // diff card. Fall back to the branch compare, and finally just open the
-  // file as a normal editor tab so the user still gets navigation when
-  // neither side has the path anymore. When `commentId` is supplied and the
-  // route lands on a diff surface, also stamp scrollToDiffCommentId so the
-  // diff decorator scrolls that note into view; we clear any prior request
-  // first, so the editor-tab fallback then leaves the global null and a
-  // future DiffViewer mount can't accidentally consume a stale id.
+  // Why: route the note by relative filePath to whichever diff surface owns it — unstaged, then branch compare, else a plain editor tab.
   const handleOpenComment = useCallback(
     (comment: DiffComment) => {
       if (!activeWorktreeId || !worktreePath) {
@@ -5302,8 +5069,7 @@ function SourceControlInner(): React.JSX.Element {
       }
       const filePath = comment.filePath
       const commentId = comment.id
-      // Defensively clear any dangling prior scroll request before routing
-      // this click; only the diff branches below will re-stamp it.
+      // Clear any dangling prior scroll request; only the diff branches below re-stamp it.
       cancelSourceControlEditorRevealFrames(pendingCommentEditorRevealFrameIdsRef)
       setScrollToDiffCommentId(null)
       if (getDiffCommentSource(comment) === 'markdown') {
@@ -5352,13 +5118,7 @@ function SourceControlInner(): React.JSX.Element {
         }
         return
       }
-      // Why: fall through to a normal editor tab when neither the working-tree
-      // nor branch-compare diff has the file (e.g. the change has since been
-      // committed and merged, but the note still references the file). Force
-      // the editor tab into 'changes' mode and stamp scrollToDiffCommentId so
-      // the DiffViewer that EditorContent renders in changes mode picks up
-      // the scroll request — same surface the user can flip into manually
-      // via the editor's Edit/Changes toggle.
+      // Why: neither diff surface has the file (e.g. change committed+merged), so open a plain editor tab in 'changes' mode where DiffViewer picks up the scroll request.
       const absPath = joinPath(worktreePath, filePath)
       const language = detectLanguage(filePath)
       openFile({
@@ -5439,10 +5199,7 @@ function SourceControlInner(): React.JSX.Element {
     [activeRepoSettings, worktreePath, activeWorktreeId, refreshActiveGitStatusAfterMutation]
   )
 
-  // Why: split into two variants — `discardSingle` throws so bulk callers can
-  // aggregate failures into a single toast via `runDiscardAllForArea`'s
-  // onError, while `handleDiscard` swallows for the per-row fire-and-forget UI
-  // contract (no individual failure toast).
+  // Why: discardSingle throws so bulk callers can aggregate failures into one toast; handleDiscard swallows for per-row fire-and-forget.
   const discardSingle = useCallback(
     async (filePath: string) => {
       if (!worktreePath || !activeWorktreeId) {
@@ -5450,9 +5207,7 @@ function SourceControlInner(): React.JSX.Element {
       }
       const runtimeEnvironmentId =
         useAppStore.getState().settings?.activeRuntimeEnvironmentId?.trim() || null
-      // Why: git discard replaces the working tree version of this file. Any
-      // pending editor autosave must be quiesced first so it cannot recreate
-      // the discarded edits after git restores the file.
+      // Why: quiesce pending editor autosaves first so a delayed save can't recreate the discarded edits after git restores the file.
       await requestEditorSaveQuiesce({
         worktreeId: activeWorktreeId,
         worktreePath,
@@ -5487,9 +5242,7 @@ function SourceControlInner(): React.JSX.Element {
       }
       const runtimeEnvironmentId =
         useAppStore.getState().settings?.activeRuntimeEnvironmentId?.trim() || null
-      // Why: bulk discard replaces many working-tree files at once. Quiesce
-      // any matching editor autosaves before git mutates the files so a delayed
-      // save cannot recreate edits after the restore.
+      // Why: quiesce matching editor autosaves first so a delayed save can't recreate edits after git mutates the files.
       await Promise.all(
         filePaths.map((relativePath) =>
           requestEditorSaveQuiesce({
@@ -5529,22 +5282,14 @@ function SourceControlInner(): React.JSX.Element {
         await discardSingle(filePath)
         await refreshActiveGitStatusAfterMutation()
       } catch {
-        // Why: per-row discard is fire-and-forget for the UI; failures are not
-        // surfaced individually. Bulk callers use `discardSingle` directly so
-        // they can aggregate failures into a single toast.
+        // Why: per-row discard is fire-and-forget; bulk callers use discardSingle directly to aggregate failures into one toast.
       }
     },
     [discardSingle, refreshActiveGitStatusAfterMutation]
   )
 
-  // Why: "Discard all" mirrors the per-row discard rules — it skips unresolved
-  // and resolved_locally rows because discarding those can silently re-create
-  // the conflict or lose the resolution (no v1 UX to explain this clearly).
-  // The happy path uses bulk discard IPC; the sequencing helper falls back to
-  // per-file discard when an older SSH relay does not support that method yet.
-  // The sequencing + filter rules live in discard-all-sequence.ts so they can
-  // be unit-tested independently of the full component (staged area needs a
-  // bulk-unstage first, and a failed unstage must skip the discard loop).
+  // Why: "Discard all" skips unresolved/resolved_locally rows (discarding can re-create the conflict or lose the resolution; no v1 UX for it).
+  // Why: sequencing/filter rules live in discard-all-sequence.ts for independent unit tests, with per-file fallback when an older SSH relay lacks bulk discard.
   const handleRevertAllInArea = useCallback(
     async (area: DiscardAllArea, confirmedPaths?: readonly string[]) => {
       if (!worktreePath || !activeWorktreeId || isExecutingBulk) {
@@ -5557,10 +5302,7 @@ function SourceControlInner(): React.JSX.Element {
       setIsExecutingBulk(true)
       try {
         const connectionId = getConnectionId(activeWorktreeId) ?? undefined
-        // Why: `onError` fires once per failure — both for the bulk-unstage
-        // pre-step and for each per-file discard failure. Aggregate into one
-        // toast after the sequence completes so a partial failure across N
-        // files doesn't spam N error toasts.
+        // Why: onError fires per failure; aggregate into one toast so a partial failure across N files doesn't spam N toasts.
         const errors: unknown[] = []
         const result = await runDiscardAllForArea(area, paths, {
           bulkUnstage: (filePaths) =>
@@ -5592,9 +5334,7 @@ function SourceControlInner(): React.JSX.Element {
             }
           )
         } else if (result.failed.length > 0) {
-          // Why: only include the first error message to avoid a huge toast
-          // body on bulk failures; a short sample of failed paths gives users
-          // enough context to retry or investigate.
+          // Why: show only the first error + a sample of failed paths to avoid a huge toast body on bulk failures.
           const firstMsg = errors[0] instanceof Error ? errors[0].message : undefined
           const sample = result.failed.slice(0, 3).join(', ')
           const more = result.failed.length > 3 ? `, +${result.failed.length - 3} more` : ''
@@ -5737,14 +5477,7 @@ function SourceControlInner(): React.JSX.Element {
           </div>
         )}
 
-        {/* Why: Diff-comments live on the worktree and apply across every diff
-            view the user opens. The header row expands inline to show per-file
-            comment previews plus a Copy-all action so the user can hand the
-            set off to whichever tool they want without leaving the sidebar.
-            Hidden when count is 0: notes are created from the diff view, so
-            an empty Notes shelf in the sidebar is pure chrome — it adds a
-            border, a row of space, and an expand control that only reveals
-            a redirect hint. */}
+        {/* Why: hidden when count is 0 — notes are created from the diff view, so an empty Notes shelf here is pure chrome. */}
         {activeWorktreeId && worktreePath && diffCommentCount > 0 && (
           <div className="border-b border-border">
             <div className="flex items-center gap-1 pl-3 pr-2 py-1.5">
@@ -5911,10 +5644,7 @@ function SourceControlInner(): React.JSX.Element {
               />
             </div>
           )}
-          {/* Why: show operation banner when rebase/merge/cherry-pick is in progress
-              but there are no unresolved conflicts (e.g. between rebase steps, or
-              after resolving all conflicts before running --continue). The
-              ConflictSummaryCard handles the "has conflicts" case above. */}
+          {/* Why: show the operation banner when a rebase/merge/cherry-pick is in progress with no unresolved conflicts (the ConflictSummaryCard above handles the conflicts case). */}
           {unresolvedConflictReviewEntries.length === 0 && conflictOperation !== 'unknown' && (
             <div className="px-3 pb-2">
               <OperationBanner
@@ -5952,16 +5682,7 @@ function SourceControlInner(): React.JSX.Element {
             />
           )}
 
-          {/* Why: keep CommitArea mounted across normal source-control states.
-              The split-button primary rotates through Push / Pull / Sync /
-              Publish on a clean tree and disables Commit with a "Nothing to
-              commit" tooltip when nothing is staged — gating on
-              hasUncommittedEntries (added by #1448 for the older Commit-only
-              design) would unmount the whole action surface on clean
-              worktrees and tear it down mid-commit when the staged list
-              clears. Active merge/rebase/cherry-pick operations are the
-              exception: commits would be misleading before the user continues
-              or aborts the operation. */}
+          {/* Why: keep CommitArea mounted across normal states — gating on hasUncommittedEntries (#1448) would unmount the action surface on clean worktrees and mid-commit as the staged list clears. Active merge/rebase/cherry-pick is the exception. */}
           {activeWorktree?.pushTarget && activeWorktree.pushTarget.remoteName !== 'origin' ? (
             <div
               className="flex items-center gap-1.5 px-1 text-[11px] text-muted-foreground"
@@ -6075,14 +5796,8 @@ function SourceControlInner(): React.JSX.Element {
               {displaySections.map((section) => {
                 const { area, id, items } = section
                 const isCollapsed = collapsedSections.has(id)
-                // Why: "Stage all"/"Unstage all" operate on the *unfiltered*
-                // group for the area — acting on just the filter-visible subset
-                // would surprise users who don't realize a filter is active.
-                // The +/- is hidden when the filter is active to avoid that
-                // mismatch between what's shown and what would be staged.
-                // Why: visibility and execution both resolve paths through the
-                // same eligibility rules as the handlers so the button can
-                // never show for a set the handler would then filter to empty.
+                // Why: bulk stage/unstage act on the *unfiltered* group; the +/- hides while filtering to avoid acting on more than what's shown.
+                // Why: visibility and execution resolve paths via the same eligibility rules, so the button never shows for a set the handler would filter to empty.
                 const actionSection = unfilteredDisplaySectionsById.get(id) ?? section
                 const actionItems = actionSection.items
                 const stageAllPaths = actionItems
@@ -6108,24 +5823,12 @@ function SourceControlInner(): React.JSX.Element {
                       onToggle={() => toggleSection(id)}
                       actions={
                         <>
-                          {/* Why: bulk action buttons are hover-only on
-                              pointer devices to avoid cluttering the section
-                              header with persistent icons. On no-hover
-                              pointers (touch, and SSH sessions where hover
-                              state is unreliable — see AGENTS.md "SSH Use
-                              Case"), force them visible so they're reachable
-                              without tabbing. One outer wrapper so that
-                              focusing any action reveals all three siblings —
-                              otherwise keyboard users tab into an invisible
-                              next stop. */}
+                          {/* Why: bulk actions are hover-only, but forced visible on no-hover pointers (touch/SSH; see AGENTS.md "SSH Use Case"). One wrapper so focusing any action reveals all three (else keyboard tabs into an invisible stop). */}
                           <div className="flex items-center can-hover:opacity-0 transition-opacity group-hover/section:opacity-100 focus-within:opacity-100">
                             {canRevertAll && (
                               <ActionButton
                                 icon={area === 'untracked' ? Trash : Undo2}
-                                // Why: for untracked files, discard deletes the file
-                                // outright (rm -rf via git.discard's untracked branch).
-                                // A generic "Discard all" label hides that severity —
-                                // label explicitly for the destructive variant.
+                                // Why: for untracked files, discard deletes outright (rm -rf), so label the destructive variant explicitly.
                                 title={
                                   area === 'untracked'
                                     ? translate(
@@ -6447,9 +6150,7 @@ function SourceControlInner(): React.JSX.Element {
           )}
 
           {isGitHistoryVisible && (
-            // Why: the graph is reference context for the whole panel, so when
-            // file sections are short it should occupy the bottom, and when the
-            // pane scrolls it should remain docked as branch context.
+            // Why: the graph is reference context, so keep it docked at the bottom as the pane scrolls.
             <div className="sticky bottom-0 z-10 mt-auto shrink-0 border-t border-border bg-sidebar/95 backdrop-blur-sm">
               <GitHistoryPanel
                 state={gitHistoryState}
@@ -6741,19 +6442,9 @@ export function CommitArea({
   onPrimaryAction,
   onDropdownAction
 }: CommitAreaProps): React.JSX.Element {
-  // Why: cap at 12 rows so a pasted multi-page commit message doesn't push
-  // the Commit button off-screen. The textarea keeps `resize-none` (matching
-  // the existing style) — the browser scrolls internally past 12 rows.
+  // Why: cap at 12 rows so a pasted multi-page message doesn't push the Commit button off-screen (textarea scrolls internally past that).
   const rows = getCommitMessageTextareaRows(commitMessage)
-  // Why: only spin the primary when its label matches what's actually
-  // running. The commit-area resolver overrides the primary kind to mirror
-  // the in-flight op (e.g. user picks Sync from the dropdown → primary
-  // becomes "Sync"), so the equality check spins the button for any primary-
-  // eligible remote op the user triggered. Background ops the primary
-  // doesn't show (Fetch) leave primaryAction.kind unchanged and the
-  // mismatch keeps the spinner off — the disabled state alone is enough
-  // signal there. Commit still spins on isCommitting because that path
-  // doesn't go through inFlightRemoteOpKind.
+  // Why: only spin the primary when its label matches the running op; mismatched background ops (Fetch) keep it off. Commit spins via isCommitting instead.
   const primaryHostsRemoteOperation =
     primaryAction.kind === inFlightRemoteOpKind ||
     (primaryAction.kind === 'push' && inFlightRemoteOpKind === 'force_push')
@@ -6763,13 +6454,7 @@ export function CommitArea({
       : primaryAction.kind === 'commit'
         ? isCommitting
         : isRemoteOperationActive && primaryHostsRemoteOperation
-  // Why: when the primary doesn't host the in-flight op (e.g. Fetch, or any
-  // dropdown action that mismatches the primary's natural label) the click
-  // would otherwise be silent — the toast only fires on failure and a
-  // no-op fetch leaves status counts unchanged. Spinning the chevron gives
-  // the user immediate feedback that the action they picked is running,
-  // while still leaving the menu reachable to read the disabled-row
-  // tooltips.
+  // Why: spin the chevron when the primary doesn't host the in-flight op (e.g. Fetch), since the click is otherwise silent — no toast until failure, no count change on a no-op fetch.
   const showChevronSpinner =
     (isCommitting || isCreatingPr || isRemoteOperationActive) && !showSpinner
   const commitFailureSummary = useMemo(
@@ -6788,12 +6473,7 @@ export function CommitArea({
         : false,
     [commitError, commitFailureSummary]
   )
-  // Why: most primary-kind labels are anchored by a directional icon so
-  // the affirmative Commit (✓) reads distinctly from the remote-state
-  // labels sharing this slot — Push (↑), Sync (↕), Publish (☁︎↑). Pull is
-  // intentionally icon-less because the down-arrow read as a
-  // download/save affordance. The icon is decorative; the label and
-  // title attribute carry the meaning for assistive tech.
+  // Why: directional icons disambiguate the labels sharing this slot; Pull stays icon-less (down-arrow read as download). Icon is decorative — label/title carry a11y meaning.
   const PrimaryIcon = PRIMARY_ICONS[primaryAction.kind]
 
   const hasMessage = commitMessage.trim().length > 0
@@ -6816,10 +6496,8 @@ export function CommitArea({
     .filter(Boolean)
     .join(' ')
 
-  // Why: only render Generate when it has a runnable path; otherwise the
-  // composer should stay focused on the normal Commit action.
-  // Why: Create PR intent owns message generation and surfaces status via the
-  // inline notice; a second composer spinner stacks on the primary spinner.
+  // Why: only render Generate when it has a runnable path; else keep the composer focused on Commit.
+  // Why: Create PR intent owns generation, so a second composer spinner would stack on the primary spinner.
   const showGenerate =
     showComposer && aiEnabled && !isCreatePrIntentInFlight && (aiAgentConfigured || isGenerating)
   let generateDisabledReason: string | undefined
@@ -6909,21 +6587,15 @@ export function CommitArea({
               'Commit message'
             )}
             aria-describedby={describedBy || undefined}
-            // Why: reserve right padding so typed text does not slide under the
-            // absolute-positioned Generate icon in the top-right corner.
-            // Why: match Input surface tokens and pin disabled:border-input so
-            // Chromium's UA disabled styles don't wash out the field outline.
+            // Why: reserve right padding so text doesn't slide under the absolute-positioned Generate icon.
+            // Why: pin disabled:border-input so Chromium's UA disabled styles don't wash out the field outline.
             className={`mt-0.5 min-h-14 w-full resize-none appearance-none rounded-md border border-input bg-background shadow-xs px-2 py-1.5 text-xs text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:border-input disabled:bg-background disabled:text-foreground disabled:shadow-xs dark:bg-input/30 dark:disabled:bg-input/30 ${
               showGenerate ? 'pr-8' : ''
             }`}
           />
           {showGenerate &&
             (isGenerating ? (
-              // Why: while generating the icon doubles as the cancel affordance.
-              // Default state shows the spinning RefreshCw; on hover/focus we
-              // swap to a Square ("stop") with a destructive tint so the user
-              // sees that clicking will abort the run. Group/group-hover toggles
-              // keep this stateless on the React side.
+              // Why: while generating, the icon doubles as cancel — hover/focus swaps the spinner to a destructive Square via CSS group toggles (stateless in React).
               <Tooltip>
                 <TooltipTrigger asChild>
                   <button
@@ -6994,17 +6666,12 @@ export function CommitArea({
             ))}
         </div>
       ) : null}
-      {/* Why: the current manual action + chevron sit together as a visual
-          split button so the edit → commit → push loop stays in a single
-          vertical band. The chevron exposes the full action surface without
-          forcing morphing labels to carry every possible intent. */}
+      {/* Why: action + chevron form one split button so the edit → commit → push loop stays in a single vertical band. */}
       <div
         className={cn(showComposer ? 'mt-1 flex items-stretch gap-1' : 'flex items-stretch gap-1')}
       >
         <div className="flex flex-1 items-stretch">
-          {/* Why: match the hosted-review action buttons in Checks
-              (size="xs", px-3 text-[11px]) so the sidebar has a consistent
-              action-button shape across Source Control and Checks. */}
+          {/* Why: match the Checks hosted-review buttons so action-button shape is consistent across Source Control and Checks. */}
           <Tooltip>
             <TooltipTrigger asChild>
               <span className="flex flex-1">
@@ -7041,11 +6708,7 @@ export function CommitArea({
                       size="xs"
                       className={cn(
                         'rounded-l-none border-l border-border px-1.5 shrink-0',
-                        // Why: mirror the primary's disabled dimming so the split
-                        // button reads as one unit when Commit is unavailable. The
-                        // chevron itself stays clickable — its dropdown exposes
-                        // independently-gated remote actions (push / fetch / pull)
-                        // that are still valid when the primary is disabled.
+                        // Why: mirror the primary's disabled dimming for a unified look, but the chevron stays clickable (its push/fetch/pull stay valid when Commit is disabled).
                         primaryAction.disabled && 'opacity-50'
                       )}
                       aria-label={moreCommitAndRemoteActionsLabel}
@@ -7152,8 +6815,7 @@ export function CommitArea({
               : 'text-muted-foreground'
           )}
         >
-          {/* Why: Create Review blockers carry recovery steps; truncating them hides
-          the action the user needs in the default narrow sidebar. */}
+          {/* Why: Create Review blockers carry recovery steps; truncating hides the action the user needs in a narrow sidebar. */}
           <span className="min-w-0 flex-1 break-words leading-4 [overflow-wrap:anywhere]">
             {createPrIntentNotice.message}
           </span>
@@ -7430,10 +7092,7 @@ function SectionHeader({
   onToggle: () => void
   actions?: React.ReactNode
 }): React.JSX.Element {
-  // Why: wrap the toggle button and actions in a shared rounded container
-  // so the hover background spans the entire row instead of clipping around
-  // the label. The outer div keeps the vertical spacing that separates
-  // sections; the inner wrapper owns the hover rectangle.
+  // Why: shared rounded container so the hover background spans the whole row instead of clipping around the label.
   return (
     <div className="pl-1 pr-3 pt-3 pb-1">
       <div className="group/section flex items-center rounded-md pr-1 hover:bg-accent hover:text-accent-foreground">
@@ -7507,13 +7166,10 @@ function DiffCommentsInlineList({
   comments: DiffComment[]
   onDelete: (commentId: string) => void
   onClearFile: (filePath: string) => void
-  // Why: clicking the note row navigates the user to that file's diff (or
-  // editor as a fallback) and, when a `commentId` is supplied, scrolls the
-  // diff to that specific note via the scrollToDiffCommentId UI slice.
+  // Why: opens the comment's file diff (or editor fallback), scrolling to the note via scrollToDiffCommentId when an id is given.
   onOpen: (comment: DiffComment) => void
 }): React.JSX.Element {
-  // Why: group by filePath so the inline list mirrors the structure in the
-  // Notes tab — a compact section per file with line-number prefixes.
+  // Why: group by filePath so the inline list mirrors the Notes tab's per-file sections.
   const groups = useMemo(() => {
     const map = new Map<string, DiffComment[]>()
     for (const c of comments) {
@@ -7600,12 +7256,7 @@ function DiffCommentsInlineList({
               >
                 <button
                   type="button"
-                  // Why: a single inner button is the click/keyboard target so
-                  // the row's action buttons (copy/delete) can stay as
-                  // siblings without nesting interactive elements — that
-                  // pattern violates ARIA's no-interactive-descendants rule
-                  // for buttons and lets bubbled key events from the children
-                  // fire the row's open handler.
+                  // Why: single inner target keeps copy/delete as siblings, not nested interactive elements (violates ARIA no-interactive-descendants).
                   className="flex min-w-0 flex-1 cursor-pointer items-center gap-1.5 rounded text-left"
                   onClick={() => onOpen(c)}
                   title={translate(
@@ -7756,8 +7407,7 @@ export function ConflictSummaryCard({
         {(conflictOperation === 'merge' || conflictOperation === 'rebase') && onAbortOperation ? (
           <Button
             type="button"
-            // Why: abort is the escape hatch for this state, so match the quiet
-            // outline conflict-review action instead of reading as destructive.
+            // Why: abort is the escape hatch, so use the quiet outline action instead of reading as destructive.
             variant="outline"
             size="sm"
             className="mt-1.5 h-7 w-full text-xs"
@@ -7775,11 +7425,7 @@ export function ConflictSummaryCard({
   )
 }
 
-// Why: this banner is separate from ConflictSummaryCard because a rebase (or
-// merge/cherry-pick) can be in progress without any conflicts — e.g. between
-// rebase steps, or after resolving all conflicts but before --continue. The
-// user needs to see the operation state so they know the worktree is mid-rebase
-// and that they should run `git rebase --continue` or `--abort`.
+// Why: separate from ConflictSummaryCard because a rebase/merge/cherry-pick can be in progress with no conflicts (between steps, or resolved but pre-continue).
 export function OperationBanner({
   conflictOperation,
   isAbortingOperation = false,
@@ -7809,8 +7455,7 @@ export function OperationBanner({
       {(conflictOperation === 'merge' || conflictOperation === 'rebase') && onAbortOperation ? (
         <Button
           type="button"
-          // Why: abort is the escape hatch for this state, so match the quiet
-          // outline conflict-review action instead of reading as destructive.
+          // Why: abort is the escape hatch, so use the quiet outline action instead of reading as destructive.
           variant="outline"
           size="sm"
           className="mt-2 h-7 w-full text-xs"
@@ -7865,8 +7510,7 @@ function SourceControlTreeDirectoryRow({
   onStagePaths: (paths: readonly string[]) => Promise<void>
   onUnstagePaths: (paths: readonly string[]) => Promise<void>
 }): React.JSX.Element {
-  // Why: filtered tree nodes only contain visible descendants. Folder-wide
-  // bulk labels would overpromise if they acted on that filtered subset.
+  // Why: filtered tree nodes only contain visible descendants, so folder-wide bulk labels would overpromise on the subset.
   const canStage = !hideBulkActions && actionPaths.stagePaths.length > 0
   const canUnstage = !hideBulkActions && actionPaths.unstagePaths.length > 0
   const canDiscard = !hideBulkActions && actionPaths.discardPaths.length > 0
@@ -7993,9 +7637,7 @@ function SourceControlBranchTreeDirectoryRow({
   )
 }
 
-// Why: a compact +added/-removed magnitude lets users gauge change size at a
-// glance. Use git decoration tokens so the source-control sidebar follows the
-// documented light/dark status palette.
+// Why: use git decoration tokens so counts follow the documented light/dark status palette.
 function DiffLineCounts({
   added,
   removed
@@ -8085,8 +7727,7 @@ const UncommittedEntryRow = React.memo(function UncommittedEntryRow({
   onDiscard: (entry: GitStatusEntry) => void
   commentCount: number
   showPathHint?: boolean
-  // When set, the row is a dirty submodule: clicking toggles lazy expansion of
-  // its inner changes instead of opening a (uninformative) gitlink diff.
+  // When set, the row is a dirty submodule: clicking toggles lazy expansion instead of opening an uninformative gitlink diff.
   submoduleExpansion?: { isExpanded: boolean; onToggle: () => void }
 }): React.JSX.Element {
   const FileIcon = getFileTypeIcon(entry.path)
@@ -8098,22 +7739,11 @@ const UncommittedEntryRow = React.memo(function UncommittedEntryRow({
   const conflictLabel = entry.conflictKind
     ? getLocalizedConflictKindLabel(entry.conflictKind)
     : null
-  // Why: the hint text ("Open and edit…", "Decide whether to…") was removed
-  // from the sidebar because it's not actionable here — the user can only
-  // click the row, and the conflict-kind label alone is sufficient context.
-  // Why: Stage is suppressed for unresolved conflicts because `git add` would
-  // immediately erase the `u` record — the only live conflict signal in the
-  // sidebar — before the user has actually reviewed the file. The user should
-  // resolve in the editor first, then stage from the post-resolution state.
-  //
-  // Discard is hidden for both unresolved AND resolved_locally rows in v1.
-  // For unresolved: discarding is too easy to misfire on a high-risk file.
-  // For resolved_locally: discarding can silently re-create the conflict or
-  // lose the resolution, and v1 does not have UX to explain this clearly.
+  // Why: Stage is suppressed for unresolved conflicts because `git add` erases the `u` record (the only live conflict signal) before review.
+  // Why: Discard is hidden for unresolved (too easy to misfire) and resolved_locally (can silently re-create the conflict or lose the resolution) rows in v1.
   const canDiscard = canDiscardStatusEntry(entry)
   const canStage = canStageStatusEntry(entry)
-  // Why: a submodule-internal staged row is read-only from the parent worktree,
-  // so the parent repo's Unstage must not be offered (mirrors bulk unstage).
+  // Why: a submodule-internal staged row is read-only from the parent worktree, so don't offer Unstage (mirrors bulk unstage).
   const canUnstage = canUnstageStatusEntry(entry)
 
   return (
@@ -8133,9 +7763,7 @@ const UncommittedEntryRow = React.memo(function UncommittedEntryRow({
         data-testid="source-control-entry"
         data-source-control-path={entry.path}
         data-source-control-area={entry.area}
-        // Why: the currently open file gets the strongest "current row" accent
-        // (full `bg-accent` + `data-current`) per the styleguide, outranking the
-        // lighter bulk-selection tint so the open file always reads as active.
+        // Why: open file gets the strongest accent, outranking the bulk-selection tint so it always reads as active.
         data-current={isOpenFile ? 'true' : undefined}
         className={cn(
           'group relative flex cursor-pointer items-center gap-1 pr-3 py-1 transition-colors',
@@ -8157,8 +7785,7 @@ const UncommittedEntryRow = React.memo(function UncommittedEntryRow({
         }}
         onClick={(e) => {
           if (submoduleExpansion) {
-            // Why: a double-click emits two click events; without this guard it
-            // expands and immediately collapses the submodule row.
+            // Why: a double-click emits two click events; without this guard it expands then immediately collapses.
             if (e.detail > 1) {
               return
             }
@@ -8198,8 +7825,7 @@ const UncommittedEntryRow = React.memo(function UncommittedEntryRow({
             <div className="truncate text-[11px] text-muted-foreground">{conflictLabel}</div>
           )}
           {isSubmoduleWorktreeOnly && (
-            // Why: parent git can stage a changed gitlink, but not nested
-            // worktree dirtiness. Keep that boundary visible in the row.
+            // Why: parent git stages the changed gitlink but not nested worktree dirtiness; keep that boundary visible.
             <div
               className="truncate text-[11px] text-muted-foreground"
               title={SUBMODULE_WORKTREE_ONLY_TOOLTIP}
@@ -8209,9 +7835,7 @@ const UncommittedEntryRow = React.memo(function UncommittedEntryRow({
           )}
         </div>
         {commentCount > 0 && (
-          // Why: show a small note marker on any row that has diff notes
-          // so the user can tell at a glance which files have review notes
-          // attached, without opening the Notes tab.
+          // Why: surface a per-row marker so files with review notes are visible without opening the Notes tab.
           <span
             className="flex shrink-0 items-center gap-0.5 text-[10px] text-muted-foreground"
             title={translate(
@@ -8451,22 +8075,9 @@ export function ActionButton({
   onClick: (event: React.MouseEvent) => void
   disabled?: boolean
 }): React.JSX.Element {
-  // Why: use the Radix Tooltip instead of the native `title` attribute so the
-  // label matches the rest of the sidebar chrome (consistent styling, no OS
-  // delay quirks, dismissible on pointer leave).
-  //
-  // Why (no local TooltipProvider): the app root mounts a single
-  // TooltipProvider (see App.tsx); nesting another one here gives this subtree
-  // its own delay-timing state and breaks Radix's "skip the open delay when
-  // moving between adjacent tooltip triggers" handoff between sibling action
-  // buttons in the section header.
-  //
-  // Why (disabled handling): Radix's TooltipTrigger asChild on a disabled
-  // <button> gets pointer-events blocked in Chromium, which suppresses the
-  // tooltip entirely — a regression vs. the native `title` attribute it
-  // replaced. We keep the button interactive and rely on the caller's
-  // `isExecutingBulk` early-return to no-op the click during bulk ops;
-  // `aria-disabled` + visual dimming preserves the disabled affordance.
+  // Why: use Radix Tooltip (not native title) to match sidebar chrome.
+  // Why (no local TooltipProvider): reuse App.tsx's single one so Radix's adjacent-trigger delay-skip handoff still works.
+  // Why (disabled): a disabled <button> loses pointer-events in Chromium and hides the Radix tooltip; keep it interactive and no-op via the caller's isExecutingBulk early-return.
   return (
     <Tooltip>
       <TooltipTrigger asChild>
diff --git a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts
index 62801dcfe31..8ee0f549aa0 100644
--- a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts
@@ -1,5 +1,5 @@
 /* eslint-disable max-lines -- Why: this dropdown state machine keeps every action row in one table so priority and disabled-state regressions stay visible in tests. */
-// Why: split from source-control-primary-action because the primary and dropdown are independent derivations with different priority ladders; together they exceed the max-lines budget and tangle unrelated concerns.
+// Why: split from source-control-primary-action — primary and dropdown are independent derivations with different priority ladders.
 
 import type { PrimaryActionInputs } from './source-control-primary-action'
 import { canSubmitCommit, resolveCommitDisabledReason } from './source-control-commit-eligibility'
@@ -119,9 +119,8 @@ function reviewCopy(
 }
 
 /**
- * Resolve the chevron dropdown items. Every item is always rendered so the
- * menu shape stays stable across states; inapplicable rows are disabled
- * with a tooltip reason rather than hidden.
+ * Resolve the chevron dropdown items. Every row is always rendered — disabled with a
+ * tooltip reason rather than hidden — so the menu shape stays stable across states.
  */
 export function resolveDropdownItems(inputs: DropdownActionInputs): DropdownEntry[] {
   const {
@@ -145,17 +144,7 @@ export function resolveDropdownItems(inputs: DropdownActionInputs): DropdownEntr
 
   const hasStaged = stagedCount > 0
   const hasDirtyLocalChanges = hasStaged || inputs.hasUnstagedChanges
-  // Why: mirror the primary-action guard. When upstreamStatus is undefined,
-  // fetchUpstreamStatus hasn't resolved for this worktree yet. Collapsing that
-  // to hasUpstream=false would re-enable Publish Branch on an already-tracked
-  // branch during the post-worktree-switch transient window, and a click there
-  // would re-run `git push -u` and clobber the real upstream. Every
-  // upstream-dependent row disables itself while loading so the primary
-  // button's stable-frame guarantee extends to the dropdown. Explicit
-  // Push/Force Push are the exception for loading/unpublished branches: the
-  // git command resolves its target itself. Linked-review rows without a
-  // usable push target still block — otherwise we would push an unrelated
-  // configured upstream while the menu claimed first-publish semantics.
+  // Why: undefined upstreamStatus means loading (transient after a worktree switch), not unpublished — treating it as hasUpstream=false would re-enable Publish Branch and clobber the real upstream.
   const upstreamLoading = upstreamStatus === undefined
   const hasUpstream = upstreamStatus?.hasUpstream ?? false
   const hasOpenHostedReview = prState === 'open' || prState === 'draft'
@@ -165,9 +154,7 @@ export function resolveDropdownItems(inputs: DropdownActionInputs): DropdownEntr
     hasCurrentBranch &&
     branchCommitsAhead !== 0 &&
     canPushLinkedReviewWithoutUpstream
-  // Why: only the missing review head is a hard block. branchCommitsAhead === 0
-  // still means the target is known — primary Push stays available, and
-  // explicit Push must match that rather than claiming "target unavailable".
+  // Why: only a missing review head hard-blocks; branchCommitsAhead === 0 still means the target is known, so Push stays available.
   const pushBlockedByOpenHostedReviewTarget =
     !hasUpstream && hasOpenHostedReview && !canPushLinkedReviewWithoutUpstream
   const publishBlockedByMergedPR = !hasUpstream && prState === 'merged'
@@ -177,10 +164,7 @@ export function resolveDropdownItems(inputs: DropdownActionInputs): DropdownEntr
   const ahead = upstreamStatus?.ahead ?? 0
   const behind = upstreamStatus?.behind ?? 0
   const shouldForcePushWithLease = shouldForcePushWithLeaseForUpstream(upstreamStatus)
-  // Why: force-push counts prefer branch-compare when upstream ahead is missing
-  // or misleading — unpublished/loading branches report ahead=0, and
-  // patch-equivalent rewrites inflate ahead far above real branch commits.
-  // On a normal tracked branch, upstream ahead is the correct force-push size.
+  // Why: prefer branch-compare for force-push counts — unpublished/loading branches report ahead=0 and patch-equivalent rewrites inflate upstream ahead.
   const pushLabelCount =
     branchCommitsAhead !== undefined &&
     branchCommitsAhead > 0 &&
@@ -190,9 +174,7 @@ export function resolveDropdownItems(inputs: DropdownActionInputs): DropdownEntr
   const forcePushTitle = formatForcePushTitle(branchCommitsAhead, upstreamStatus?.upstreamName)
   const createReviewCopy = reviewCopy(hostedReviewCreation?.provider)
 
-  // Why: any in-flight commit or remote operation should lock the whole menu.
-  // A running push shouldn't let a second pull/sync click queue up behind it
-  // on a stale status snapshot.
+  // Why: lock the whole menu during any in-flight op so a second click can't queue on a stale status snapshot.
   const globalBusy = isCommitting || isRemoteOperationActive || isPullRequestOperationActive
 
   const commitDisabledReason = resolveCommitDisabledReason({
@@ -222,13 +204,7 @@ export function resolveDropdownItems(inputs: DropdownActionInputs): DropdownEntr
     disabled: !canCommit
   }
 
-  // Why: compound commit labels omit counts because the commit itself changes
-  // ahead/behind — surfacing pre-commit numbers would be misleading (e.g.
-  // "Commit & Push (2)" would still read "2" after the commit lands at 3).
-  // On an unpublished branch, Commit & Push is unavailable: the user must
-  // Publish Branch first (offered via the primary action), after which
-  // Commit & Push becomes enabled. Tooltips mirror pushItem/syncItem copy
-  // so the "publish first" instruction is consistent across the menu.
+  // Why: compound commit labels omit counts — the commit itself changes ahead/behind, so pre-commit numbers would mislead.
   const commitPushTitle = upstreamLoading
     ? 'Checking branch status…'
     : publishBlockedByPRLoading
@@ -251,9 +227,7 @@ export function resolveDropdownItems(inputs: DropdownActionInputs): DropdownEntr
     kind: 'commit_push',
     label: shouldForcePushWithLease ? 'Commit & Force Push' : 'Commit & Push',
     title: commitPushTitle,
-    // Why: match explicit Push — only an open linked review with a known head
-    // can commit+push without a git upstream. Missing heads still block; plain
-    // unpublished branches still need Publish first.
+    // Why: match explicit Push — only an open linked review with a known head can commit+push without a git upstream.
     disabled:
       globalBusy ||
       upstreamLoading ||
@@ -278,9 +252,7 @@ export function resolveDropdownItems(inputs: DropdownActionInputs): DropdownEntr
       return 'Check out a branch before syncing commits'
     }
     if (!hasUpstream) {
-      // Why: mirror pushItem/syncItem — direct the user to Publish Branch
-      // (the primary action on an unpublished branch) rather than naming a
-      // nonexistent compound action.
+      // Why: direct the user to Publish Branch (the primary action) rather than naming a nonexistent compound action.
       return 'Publish the branch first to sync commits'
     }
     if (shouldForcePushWithLease) {
@@ -327,10 +299,7 @@ export function resolveDropdownItems(inputs: DropdownActionInputs): DropdownEntr
                   : ahead === 0
                     ? `Nothing to push${upstreamStatus?.upstreamName ? ` to ${upstreamStatus.upstreamName}` : ''}`
                     : describePushCount(ahead),
-    // Why: keep Push available without an upstream (git resolves --set-upstream
-    // itself) and even when force-with-lease is recommended — regular Push must
-    // stay a non-force path. Only block detached HEAD and linked reviews whose
-    // push target is still unknown (otherwise we would push an unrelated upstream).
+    // Why: Push stays available without an upstream (git resolves --set-upstream) and under force-with-lease; only detached HEAD and unknown review targets block.
     disabled: globalBusy || publishBlockedByDetachedHead || pushBlockedByOpenHostedReviewTarget
   }
 
@@ -350,9 +319,7 @@ export function resolveDropdownItems(inputs: DropdownActionInputs): DropdownEntr
               : shouldForcePushWithLease
                 ? forcePushTitle
                 : formatManualForcePushTitle(pushLabelCount, behind, upstreamStatus?.upstreamName),
-    // Why: same target-safety gate as Push — force-with-lease to a wrong or
-    // unresolved review head is worse than blocking the row until the target
-    // is known. Explicit Force Push stays available without an upstream.
+    // Why: same target-safety gate as Push — force-with-lease to a wrong review head is worse than blocking; stays available without an upstream.
     disabled: globalBusy || publishBlockedByDetachedHead || pushBlockedByOpenHostedReviewTarget
   }
 
diff --git a/src/renderer/src/components/right-sidebar/useFileExplorerWatch.ts b/src/renderer/src/components/right-sidebar/useFileExplorerWatch.ts
index 23c718a09d5..afd7fa5b128 100644
--- a/src/renderer/src/components/right-sidebar/useFileExplorerWatch.ts
+++ b/src/renderer/src/components/right-sidebar/useFileExplorerWatch.ts
@@ -47,11 +47,7 @@ export function getExternalFileChangeRelativePath(
     return null
   }
 
-  // Why: EditorPanel only reloads open tabs after the renderer emits
-  // `orca:editor-external-file-change` with a worktree-relative path. The
-  // filesystem watcher reports absolute paths, so normalize them here before
-  // the explorer refresh path returns; otherwise terminal edits refresh the
-  // tree but leave the editor's cached file contents stale.
+  // Why: EditorPanel reloads tabs only from a worktree-relative path, not the watcher's absolute one; normalize or contents go stale.
   return normalizeRelativePath(relativePath)
 }
 
@@ -99,12 +95,7 @@ export function getFileExplorerWatchRuntimeEnvironmentId(
 /**
  * Reconciles File Explorer state on filesystem events for the active worktree.
  *
- * Why: `useEditorExternalWatch` (invoked once from App.tsx) owns the
- * `watchWorktree` / `unwatchWorktree` IPC lifecycle so editor reloads keep
- * firing even when the Explorer panel is unmounted (user switched to Source
- * Control, Checks, or Search). This hook just subscribes to the shared
- * `fs:changed` stream and filters to the active worktree for tree-cache
- * reconciliation.
+ * Why: `useEditorExternalWatch` owns the watch IPC lifecycle; this hook only subscribes to fs:changed for tree-cache reconciliation.
  */
 export function useFileExplorerWatch({
   worktreePath,
@@ -119,14 +110,12 @@ export function useFileExplorerWatch({
   dragSourcePath,
   isNativeDragOver
 }: UseFileExplorerWatchParams): void {
-  // Why: Explorer subscriptions are for the selected worktree. Host focus is
-  // only a default for legacy untagged worktrees, not an ownership signal.
+  // Why: subscriptions follow the selected worktree; host focus is only a legacy default, not an ownership signal.
   const activeRuntimeEnvironmentId = useAppStore((s) =>
     getFileExplorerWatchRuntimeEnvironmentId(s, activeWorktreeId)
   )
 
-  // Keep refs for values accessed inside the event handler to avoid
-  // re-subscribing the IPC listener on every render.
+  // Keep refs for handler-accessed values so the IPC listener isn't re-subscribed on every render.
   const dirCacheRef = useRef(dirCache)
   dirCacheRef.current = dirCache
 
@@ -145,11 +134,7 @@ export function useFileExplorerWatch({
   const isNativeDragOverRef = useRef(isNativeDragOver)
   isNativeDragOverRef.current = isNativeDragOver
 
-  // Why: refreshDir and refreshTree are stored as refs so the merged
-  // subscribe+event effect does not re-subscribe the IPC listener when
-  // `expanded` changes (which gives refreshTree a new identity). Without
-  // refs, every expand/collapse would tear down and re-create the watcher
-  // subscription and IPC listener unnecessarily (review issue §1).
+  // Why: refs keep the effect from re-subscribing when refreshTree's identity changes on expand/collapse (review issue §1).
   const refreshDirRef = useRef(refreshDir)
   refreshDirRef.current = refreshDir
 
@@ -159,20 +144,10 @@ export function useFileExplorerWatch({
   // Deferred events queue: events that arrive during inline input or drag
   const deferredRef = useRef<FsChangedPayload[]>([])
 
-  // Why: the flush effect (below) lives outside the subscribe effect that
-  // owns `processPayload`, but it needs to replay deferred payloads so the
-  // tree-cache reconciliation (design §6.2) converges on disk reality even
-  // when events arrived during inline input or drag. A ref bridges the two
-  // effects without tearing the subscription down on every render.
+  // Why: a ref bridges processPayload to the flush effect so it can replay deferred payloads without re-subscribing (design §6.2).
   const processPayloadRef = useRef<((payload: FsChangedPayload) => void) | null>(null)
 
-  // ── Subscribe, process events, and unsubscribe in one atomic effect ──
-  // Why: merging the subscribe/unsubscribe effect and the event-processing
-  // effect into a single useEffect eliminates a race where events from a
-  // new watcher could be lost during rapid worktree switches. When they were
-  // separate effects with the same `worktreePath` dependency, React could
-  // run the event-listener cleanup before the unsubscribe cleanup, creating
-  // a window where events arrive with no handler (review issue §3).
+  // Why: one atomic effect avoids a cleanup-ordering race that drops events on rapid worktree switches (review issue §3).
   useEffect(() => {
     if (!worktreePath) {
       return
@@ -181,9 +156,7 @@ export function useFileExplorerWatch({
     const currentWorktreePath = worktreePath
 
     function processPayload(payload: FsChangedPayload): void {
-      // Why: during rapid worktree switches, in-flight batched events from
-      // the old worktree can arrive after the switch. Processing them against
-      // the new worktree's tree state would corrupt dirCache (design §3).
+      // Why: stale batched events from the old worktree can arrive after a switch and corrupt dirCache (design §3).
       if (
         normalizeRuntimePathForComparison(payload.worktreePath) !==
         normalizeRuntimePathForComparison(currentWorktreePath)
@@ -218,9 +191,7 @@ export function useFileExplorerWatch({
         }
 
         if (evt.kind === 'delete') {
-          // Why: for delete events, isDirectory is undefined from the watcher
-          // (the path no longer exists). Infer from dirCache: if the deleted
-          // path is a dirCache key, it was an expanded directory (design §4.4).
+          // Why: watcher can't report isDirectory for deletes; a dirCache key means it was an expanded dir (design §4.4).
           const wasDirectory = normalizedPath in cache
 
           if (wasDirectory) {
@@ -228,8 +199,7 @@ export function useFileExplorerWatch({
             purgeExpandedDirsSubtree(wtId, normalizedPath)
           }
 
-          // Clear pendingExplorerReveal if it targets the deleted path or any
-          // descendant (for directory deletes). File deletes clear on exact match.
+          // Clear pendingExplorerReveal if it targets the deleted path or a descendant.
           clearStalePendingReveal(normalizedPath)
 
           // Clear selectedPath if it points into the deleted subtree
@@ -259,8 +229,7 @@ export function useFileExplorerWatch({
             dirsToRefresh.add(parent)
           }
         } else if (evt.kind === 'update') {
-          // Why: directory update events invalidate that directory. File-content
-          // update events are ignored in v1 (design §6.1).
+          // Why: only directory updates invalidate; file-content updates are ignored in v1 (design §6.1).
           if (evt.isDirectory === true) {
             if (normalizedPath in cache) {
               dirsToRefresh.add(normalizedPath)
@@ -275,10 +244,8 @@ export function useFileExplorerWatch({
         return
       }
 
-      // Only refresh directories that are already loaded (in cache) and are
-      // either the root, expanded, or already have cached children.
+      // Only refresh dirs already loaded and reachable (root, expanded, or cached).
       for (const dirPath of dirsToRefresh) {
-        // Check the dir is the root or an expanded directory or already in cache
         if (
           dirPath === normalizeExplorerAbsolutePath(currentWorktreePath) ||
           exp.has(dirPath) ||
@@ -289,17 +256,11 @@ export function useFileExplorerWatch({
       }
     }
 
-    // Why: expose `processPayload` to the flush effect so it can replay
-    // deferred payloads without re-subscribing the IPC listener.
+    // Why: expose processPayload to the flush effect so it can replay deferred payloads without re-subscribing.
     processPayloadRef.current = processPayload
 
     const handleFsChanged = (payload: FsChangedPayload): void => {
-      // Why: defer watcher-triggered refreshes while inline input or drag-drop
-      // is active to avoid displacing the inline input row or shifting rows
-      // under the drag cursor (design §6.2). Native OS file drags (e.g. PDFs)
-      // never set dragSourcePath, so we also check isNativeDragOver to prevent
-      // FS create events from the import racing with the tree refresh and
-      // causing the virtualizer to snap the scroll position.
+      // Why: defer refreshes during inline input/drag so rows don't shift; native drags only set isNativeDragOver (design §6.2).
       if (
         inlineInputRef.current !== null ||
         dragSourceRef.current !== null ||
@@ -315,8 +276,7 @@ export function useFileExplorerWatch({
     let disposed = false
     let unsubscribeListener: (() => void) | null = null
     if (activeRuntimeEnvironmentId?.trim() && activeWorktreeId) {
-      // Why: remote runtime watch events do not enter the local Electron
-      // fs:changed bus, so the Explorer subscribes directly while it is mounted.
+      // Why: remote runtime watch events don't enter the local Electron fs:changed bus, so subscribe directly.
       void subscribeRuntimeFileChanges(
         {
           settings: { activeRuntimeEnvironmentId },
@@ -371,19 +331,13 @@ export function useFileExplorerWatch({
       const requiresFullRefresh = worktreePath
         ? deferred.some((payload) => payloadRequiresDeferredTreeRefresh(payload, worktreePath))
         : false
-      // Why: replay every deferred payload through `processPayload` so the
-      // tree cache reconciles to disk state after inline input or drag ends
-      // (design §6.2). Editor-tab reloads are handled independently by
-      // `useEditorExternalWatch`, which listens to the same fs:changed
-      // stream at App-level and is not affected by Explorer deferral.
+      // Why: replay deferred payloads so the tree cache reconciles to disk after inline input or drag ends (design §6.2).
       if (processPayloadRef.current) {
         for (const payload of deferred) {
           processPayloadRef.current(payload)
         }
       }
-      // Why: create/delete/update payloads replay into targeted refreshDir
-      // calls above. Only event kinds this reconciler cannot apply safely
-      // should pay the full expanded-tree refresh cost after a deferred flush.
+      // Why: create/delete/update already replayed above; only kinds this reconciler can't apply (rename) pay the full-tree refresh.
       if (requiresFullRefresh) {
         void refreshTreeRef.current()
       }
diff --git a/src/renderer/src/components/settings/Settings.tsx b/src/renderer/src/components/settings/Settings.tsx
index 80a4facee4e..4c4f99ad4eb 100644
--- a/src/renderer/src/components/settings/Settings.tsx
+++ b/src/renderer/src/components/settings/Settings.tsx
@@ -180,9 +180,7 @@ function getSettingsSectionId(
   repoIdToRepresentative: Map<string, string>
 ): string {
   if (pane === 'repo' && repoId) {
-    // Why: a `{pane:'repo', repoId}` target can name any host's repo row, but
-    // Settings now renders one collapsed pane per project — resolve to that
-    // project's representative section so the deep link lands.
+    // Why: Settings renders one collapsed pane per project, so resolve a repoId target to its project's representative section.
     return `repo-${repoIdToRepresentative.get(repoId) ?? repoId}`
   }
   return pane
@@ -238,10 +236,7 @@ function getSettingsScrollTarget(
 }
 
 function scrollSubsectionIntoView(targetId: string, container?: HTMLElement | null): void {
-  // Why: deep links into Settings can target a specific subsection inside a
-  // pane (e.g. a particular row). The pane itself is now swapped in
-  // wholesale, so this only needs to nudge the inner scroll if the pane has
-  // grown taller than the viewport.
+  // Why: the pane is swapped in wholesale, so a subsection deep link only nudges inner scroll when the pane exceeds the viewport.
   const target = getSettingsScrollTarget(targetId, container)
   if (!target) {
     return
@@ -305,22 +300,18 @@ function Settings(): React.JSX.Element {
   const modelStates = useAppStore((s) => s.modelStates)
   const refreshModelStates = useAppStore((s) => s.refreshModelStates)
 
-  // Why: collapse repo rows into one entry per project (derived from repos so it
-  // matches the nav metadata exactly) — the source of truth for the pane list.
+  // Why: one entry per project (derived from repos to match nav metadata) — the source of truth for the pane list.
   const settingsProjectList = useMemo(() => buildSettingsProjectList(repos), [repos])
   const repoIdToRepresentative = useMemo(
     () => buildRepoIdToRepresentative(settingsProjectList),
     [settingsProjectList]
   )
-  // Why: lets a deep-link's repoId select the owning project's host so
-  // host-specific subsection anchors exist under the now-selected host.
+  // Why: lets a deep-link's repoId select the owning project's host so host-specific subsection anchors exist.
   const repoIdToHostSelection = useMemo(
     () => buildRepoIdToHostSelection(settingsProjectList),
     [settingsProjectList]
   )
-  // Why: the pane-level "Remove Project" removes the whole project (every host
-  // setup), not just the selected host — the per-host remove lives inside
-  // "Available Hosts".
+  // Why: pane-level "Remove Project" removes every host setup, not just the selected host (per-host remove lives in "Available Hosts").
   const removeProjectAllHosts = useCallback(
     (setups: readonly ProjectHostSetup[]): Promise<void> =>
       removeSettingsProjectFromAllHosts(setups, removeProject),
@@ -335,8 +326,7 @@ function Settings(): React.JSX.Element {
   const isMac = isMacUserAgent()
   const isWebClient = isWebClientLocation()
   const showDesktopOnlySettings = !isWebClient
-  // Why: the Linear capability section mirrors the nav registry's gate so the
-  // sidebar entry and the rendered section appear/disappear together.
+  // Why: mirror the nav registry's gate so the Linear sidebar entry and section appear/disappear together.
   const linearConnected = useLinearProviderConnected()
   const activeSkillRuntime = useActiveProjectSkillRuntime()
   const orchestrationSkill = useInstalledAgentSkill(ORCHESTRATION_SKILL_NAME, {
@@ -353,18 +343,14 @@ function Settings(): React.JSX.Element {
     discoveryTarget: activeSkillRuntime.discoveryTarget,
     sourceKinds: GLOBAL_AGENT_SKILL_SOURCE_KINDS
   })
-  // Why: mirror the setup cards — freshness only speaks for the validated global
-  // rail, which doesn't run under WSL, so the nav pill stays presence-only there.
+  // Why: skill freshness only covers the validated global rail (not WSL), so the nav pill stays presence-only under WSL.
   const { inventory: skillFreshnessInventory } = useSkillFreshness()
   const skillFreshnessApplies = activeSkillRuntime.agentRuntime?.runtime !== 'wsl'
   const [voiceModelStatesLoading, setVoiceModelStatesLoading] = useState(showDesktopOnlySettings)
-  // Why: the Terminal settings section shares one search index with the
-  // sidebar. We trim platform-only entries on other platforms so search never
-  // reveals controls that the renderer will intentionally hide.
+  // Why: trim platform-only Terminal entries from the shared search index so search never reveals hidden controls.
   const [scrollbackMode, setScrollbackMode] = useState<'preset' | 'custom'>('preset')
   const [prevScrollbackRows, setPrevScrollbackRows] = useState(settings?.terminalScrollbackRows)
-  // Why: Appearance owns terminal visual controls, but the Ghostty import flow
-  // still needs Settings-level state so the modal survives section remounts.
+  // Why: keep Ghostty import state at Settings level so the modal survives section remounts.
   const ghostty = useGhosttyImport(updateSettings, settings)
   const warpThemes = useWarpThemeImport(updateSettings, settings)
   const [fontSuggestions, setFontSuggestions] = useState<string[]>(
@@ -384,10 +370,7 @@ function Settings(): React.JSX.Element {
   const [hasUnsavedBranchPromptChanges, setHasUnsavedBranchPromptChanges] = useState(false)
   const [sourceControlAiPromptDiscardSignal, setSourceControlAiPromptDiscardSignal] = useState(0)
   const confirm = useConfirmationDialog()
-  // Why: the hidden-experimental group is an unlock — Shift-clicking the
-  // Experimental sidebar entry reveals it for the remainder of the session.
-  // Not persisted on purpose: it's a power-user affordance we don't want to
-  // leak through into a normal reopen of Settings.
+  // Why: session-only (deliberately not persisted) unlock — Shift-click the Experimental entry reveals the hidden group.
   const [hiddenExperimentalUnlocked, setHiddenExperimentalUnlocked] = useState(false)
   const contentScrollRef = useRef<HTMLDivElement | null>(null)
   const searchInputRef = useRef<HTMLInputElement | null>(null)
@@ -403,9 +386,7 @@ function Settings(): React.JSX.Element {
 
   const hasUnsavedSourceControlAiPromptChanges =
     hasUnsavedCommitPromptChanges || hasUnsavedBranchPromptChanges
-  // Why: the window-close guard registers once for Settings' lifetime, so it
-  // reads the latest dirty state from a ref instead of a closure that would lag
-  // behind the draft state until the next effect commit.
+  // Why: the close guard registers once, so it reads latest dirty state from a ref instead of a lagging closure.
   const hasUnsavedSourceControlAiPromptChangesRef = useRef(hasUnsavedSourceControlAiPromptChanges)
   hasUnsavedSourceControlAiPromptChangesRef.current = hasUnsavedSourceControlAiPromptChanges
 
@@ -433,8 +414,7 @@ function Settings(): React.JSX.Element {
       if (node) {
         return
       }
-      // Why: the settings search is a transient in-page filter. Leaving it behind makes the next
-      // visit look partially broken because whole sections stay hidden before the user types again.
+      // Why: clear the transient search filter on close, else the next visit opens with whole sections still hidden.
       setSettingsSearchQuery('')
     },
     [setSettingsSearchQuery]
@@ -445,14 +425,12 @@ function Settings(): React.JSX.Element {
     if (node !== null) {
       return
     }
-    // Why: pending subsection jumps are scoped to the scroll container; cancel
-    // them with the container so a stale deep-link frame cannot run after close.
+    // Why: cancel pending subsection jumps with the scroll container so a stale deep-link frame can't run after close.
     cancelPendingSettingsSubsectionScrollFrame(pendingSubsectionScrollFrameRef)
   }, [])
 
   useEffect(() => {
-    // Why: React dev StrictMode replays mount effects; async font requests
-    // should still commit while the Settings view is actually mounted.
+    // Why: StrictMode replays mount effects; async font requests should still commit while Settings is mounted.
     settingsMountedRef.current = true
     return () => {
       settingsMountedRef.current = false
@@ -470,8 +448,7 @@ function Settings(): React.JSX.Element {
         if (!settingsMountedRef.current) {
           return
         }
-        // Latch after the first successful attempt even when empty, so a font-less
-        // system doesn't reissue listFonts() on every picker interaction.
+        // Latch after the first successful attempt even when empty, so a font-less system doesn't reissue listFonts() each time.
         installedFontsLoadedRef.current = true
         if (fonts.length === 0) {
           return
@@ -486,9 +463,7 @@ function Settings(): React.JSX.Element {
       })
   }, [])
 
-  // Pure "discard and leave?" prompt — no side effects. Why separate from the
-  // discard helper below: the window-close guard must ask without clearing the
-  // drafts, since a later guard/handler can still cancel the close.
+  // Pure prompt (no side effects): the close guard must ask without clearing drafts, since a later guard can still cancel the close.
   const promptDiscardSourceControlAiPromptChanges = useCallback((): Promise<boolean> => {
     return confirm({
       title: translate(
@@ -535,8 +510,7 @@ function Settings(): React.JSX.Element {
       return
     }
     let canceled = false
-    // Why: modelStates starts empty, so Voice should not briefly look missing
-    // before the first speech-model scan reports the real installed state.
+    // Why: modelStates starts empty, so Voice shouldn't look missing before the first speech-model scan reports state.
     setVoiceModelStatesLoading(true)
     void refreshModelStates().finally(() => {
       if (!canceled) {
@@ -571,16 +545,11 @@ function Settings(): React.JSX.Element {
       if (event.key !== 'Escape' || event.defaultPrevented) {
         return
       }
-      // Why: nested dialogs and menus own Escape before Settings page-level
-      // navigation, including the unsaved Source Control AI confirmation dialog.
+      // Why: nested dialogs/menus own Escape before Settings page-level navigation.
       if (hasVisibleOverlay()) {
         return
       }
-      // Why: Escape in an editable control usually means "cancel this edit",
-      // not "close Settings". Closing the entire page would discard the user's
-      // in-progress typing. Defer to the field's own handler when focus is on
-      // an input/textarea/select or contenteditable region; a subsequent
-      // Escape (with focus back on the body) will then close the page.
+      // Why: Escape in an editable control means "cancel this edit", not "close Settings" — defer to the field's own handler.
       if (isEditableTarget(event.target)) {
         return
       }
@@ -614,14 +583,7 @@ function Settings(): React.JSX.Element {
     return () => document.removeEventListener('keydown', handleKeyDown)
   }, [activeSectionId, closeSettingsPageWithPromptGuard])
 
-  // Why: route window close / quit through the same discard dialog as in-app
-  // navigation. A raw beforeunload preventDefault only silently vetoes the close
-  // (no UI), which on the no-workspace Settings page reads as an unquittable
-  // window. Register one stable guard for Settings' lifetime, reading the latest
-  // dirty state from a ref. Why the pure prompt (no discard side effect): a
-  // downstream guard/handler can still cancel the close (e.g. a dirty-editor save
-  // dialog), and clearing the drafts up front would lose them while the window
-  // stays open; on an actual close they fall away with the renderer anyway.
+  // Why: route window close/quit through the discard dialog; a bare beforeunload veto shows no UI and reads as an unquittable window.
   useEffect(() => {
     return registerWindowCloseGuard(() => {
       if (isIntentionalAppRestartInProgress()) {
@@ -665,9 +627,7 @@ function Settings(): React.JSX.Element {
       settingsNavigationTarget.repoId,
       repoIdToRepresentative
     )
-    // Why: couple the deep link to the in-pane host switcher before scrolling —
-    // select the target repo's host so its host-specific subsection anchor
-    // (e.g. `repo-<remoteId>-source-control-ai`) renders and the scroll lands.
+    // Why: select the target repo's host before scrolling so its host-specific subsection anchor renders and the scroll lands.
     const targetRepoId = resolveSettingsTargetRepoId(
       settingsNavigationTarget,
       repoIdToHostSelection.keys()
@@ -680,8 +640,7 @@ function Settings(): React.JSX.Element {
     }
     pendingNavSectionRef.current = paneSectionId
     pendingScrollTargetRef.current = settingsNavigationTarget.sectionId ?? paneSectionId
-    // Why: Appearance nests status-bar controls under a collapsed accordion;
-    // force that accordion open before scrolling so the row is actually visible.
+    // Why: force Appearance's collapsed status-bar accordion open before scrolling so the row is visible.
     if (settingsNavigationTarget.pane === 'appearance') {
       const accordion = resolveAppearanceAccordionDeepLink(settingsNavigationTarget.sectionId)
       if (accordion) {
@@ -697,8 +656,7 @@ function Settings(): React.JSX.Element {
       }
       return new Set(previous).add(paneSectionId)
     })
-    // Why: target consumption stores refs, so bump state to guarantee the
-    // scroll effect runs even when the visible section set is otherwise stable.
+    // Why: bump state so the scroll effect runs even when the visible section set is unchanged (target is kept in refs).
     setPendingNavRequestTick((tick) => tick + 1)
     clearSettingsTarget()
   }, [
@@ -710,8 +668,7 @@ function Settings(): React.JSX.Element {
     settingsNavigationTarget
   ])
 
-  // Why: only recompute scrollback mode when the row value actually changes,
-  // not on every unrelated settings mutation.
+  // Why: recompute scrollback mode only when the row value changes, not on every settings mutation.
   if (settings?.terminalScrollbackRows !== prevScrollbackRows) {
     setPrevScrollbackRows(settings?.terminalScrollbackRows)
     if (settings) {
@@ -889,20 +846,16 @@ function Settings(): React.JSX.Element {
     windowsTerminalCapabilityOwnerKey,
     runtimeTarget
   )
-  // Why: WSL can be unsupported on macOS/Linux, or supported-but-unavailable on Windows.
-  // Only the latter should render disabled WSL controls.
+  // Why: only supported-but-unavailable WSL (Windows) should render disabled controls, not unsupported WSL (macOS/Linux).
   const wslSupportedPlatform = isWindows || windowsTerminalCapabilities.hostPlatform === 'win32'
   const isWindowsTerminalHost = isWindows || windowsTerminalCapabilities.hostPlatform === 'win32'
 
   if ([...neededSectionIds].some((id) => !mountedSectionIds.has(id))) {
-    // Why: lazy Settings sections are remembered for the session; record newly
-    // needed sections during render so panes do not wait for a follow-up Effect.
+    // Why: record newly needed sections during render so panes don't wait for a follow-up Effect.
     setMountedSectionIds(neededSectionIds)
   }
 
-  // Why: each mounted project pane renders its SELECTED host's repo, so hooks
-  // must load for that repo id — not the representative id parsed from the
-  // section string (they differ when a non-default host is selected).
+  // Why: load hooks for the selected host's repo id, not the representative id (they differ for non-default hosts).
   const neededRepos = useMemo(() => {
     const reposByHostIdentity = new Map<string, Repo>()
     for (const settingsProject of settingsProjectList) {
@@ -1005,10 +958,7 @@ function Settings(): React.JSX.Element {
     const scrollTargetId = pendingScrollTargetRef.current
     const pendingNavSectionId = pendingNavSectionRef.current
 
-    // Why: subsection deep links (scrollTarget ≠ pane id) must not keep a
-    // leftover search filter that can hide the target row. Pane-level deep
-    // links may intentionally pair with a filter (e.g. Appearance + "Usage
-    // percentages") so accordion sections force-open to the matching control.
+    // Why: subsection deep links clear a stale filter that could hide the target row; pane-level links keep it to force-open the matching accordion.
     if (
       scrollTargetId &&
       pendingNavSectionId &&
@@ -1020,9 +970,7 @@ function Settings(): React.JSX.Element {
     }
 
     if (scrollTargetId && pendingNavSectionId && visibleSectionIds.has(pendingNavSectionId)) {
-      // Why: inactive Settings panes no longer render in the empty-search view.
-      // Activate the pane first, then wait for the next render before looking
-      // for any subsection target inside it.
+      // Why: inactive panes don't render; activate the pane first, then find the subsection next render.
       if (activeSectionId !== pendingNavSectionId) {
         setActiveSectionId(pendingNavSectionId)
         return
@@ -1031,11 +979,9 @@ function Settings(): React.JSX.Element {
       if (container) {
         container.scrollTo({ top: 0 })
       }
-      // Why: deep links can target a row inside the pane; the pane itself is
-      // already in view because the sidebar swap rendered just it.
+      // Why: deep links can target a row inside the already-visible pane.
       if (scrollTargetId !== pendingNavSectionId) {
-        // Why: target navigation can arrive before the lazy section has mounted;
-        // keep the pending refs alive until the mounted-section update commits.
+        // Why: target can arrive before the lazy section mounts; keep pending refs until it does.
         if (!getSettingsScrollTarget(scrollTargetId, container)) {
           return
         }
@@ -1083,11 +1029,7 @@ function Settings(): React.JSX.Element {
       if (sectionId !== activeSectionId && !(await confirmDiscardSourceControlAiPromptChanges())) {
         return
       }
-      // Why: Shift-clicking the Experimental sidebar entry unlocks a hidden
-      // power-user group. Keep this scoped to the Experimental row so normal
-      // shortcut combos on other rows don't accidentally flip state. The
-      // unlock persists for the life of the Settings view (resets when
-      // Settings is reopened).
+      // Why: Shift-click the Experimental row unlocks the hidden power-user group (session-only).
       if (sectionId === 'experimental' && modifiers?.shiftKey) {
         setHiddenExperimentalUnlocked((previous) => !previous)
       }
@@ -1096,9 +1038,7 @@ function Settings(): React.JSX.Element {
         container.scrollTo({ top: 0 })
       }
       if (settingsSearchQuery.trim() !== '') {
-        // Why: sidebar search is a discovery tool. Once a user selects a
-        // section from the filtered results, show the actual pane instead of
-        // keeping another matching pane rendered by the stale query.
+        // Why: clear the search filter so selecting a result shows that pane, not the stale query's.
         setSettingsSearchQuery('')
       }
       setActiveSectionId(sectionId)
@@ -1121,8 +1061,7 @@ function Settings(): React.JSX.Element {
       setSettingsSearchQuery('')
       return
     }
-    // Why: the pending section refs do not schedule a render by themselves.
-    // When search is already clear, this reruns the centralized jump effect.
+    // Why: pending refs don't schedule a render; bump state to rerun the jump effect.
     setPendingNavRequestTick((tick) => tick + 1)
   }, [confirmDiscardSourceControlAiPromptChanges, setSettingsSearchQuery, settingsSearchQuery])
 
@@ -1766,9 +1705,7 @@ function Settings(): React.JSX.Element {
 
                 {settingsProjectList.map((settingsProject) => {
                   const repoSectionId = `repo-${settingsProject.representativeRepoId}`
-                  // Why: render the switcher-selected host's repo row (validated
-                  // against live setups) so identity edits and host-specific
-                  // settings follow the "Available Hosts" selection.
+                  // Why: use the switcher-selected host's repo so identity/host-specific edits follow "Available Hosts".
                   const repo = getSettingsProjectHostRepo(
                     settingsProject,
                     repos,
@@ -1794,8 +1731,7 @@ function Settings(): React.JSX.Element {
                       searchEntries={getSectionSearchEntries(repoSectionId)}
                     >
                       {isSectionMounted(repoSectionId) ? (
-                        // Why: same-id hosts otherwise reuse drafts and effects
-                        // from the previously selected host inside this pane.
+                        // Why: re-key per host so same-id hosts don't reuse the prior host's drafts/effects.
                         <RepositoryPane
                           key={repoHostIdentity}
                           repo={repo}
diff --git a/src/renderer/src/components/settings/TerminalSettingsPreview.tsx b/src/renderer/src/components/settings/TerminalSettingsPreview.tsx
index 6e94e4a3eab..f21b8b9390e 100644
--- a/src/renderer/src/components/settings/TerminalSettingsPreview.tsx
+++ b/src/renderer/src/components/settings/TerminalSettingsPreview.tsx
@@ -16,20 +16,11 @@ import { SettingsSwitch } from './SettingsFormControls'
 import type { GlobalSettings } from '../../../../shared/types'
 import { translate } from '@/i18n/i18n'
 
-// Why: pin cols/rows so PREVIEW_BUFFER never wraps. Sized so the longest
-// line (the def total signature, 32 chars) plus a few cols of margin fits
-// the xterm canvas in the xl right-column at the default 14px font with
-// the divider + stub pane carved off the right side. Larger fonts will
-// extend past the xterm box's right edge — the box clips, which is
-// preferable to wrapping mid-content.
+// Why: pinned so PREVIEW_BUFFER never wraps; 36 cols fits the 32-char longest line + margin (larger fonts clip, not wrap).
 const PREVIEW_COLS = 36
 const PREVIEW_ROWS = 15
 
-// Why: the old TerminalThemePreview rendered two side-by-side panes so the
-// user could see the divider + inactive opacity in context. Keep that
-// affordance with a real xterm on the left and a small color-only stub on
-// the right. 40px is wide enough to read the inactive opacity dim against
-// the active xterm, narrow enough not to crowd content.
+// Why: color-only stub pane; 40px is wide enough to read inactive-pane opacity dim, narrow enough not to crowd content.
 const STUB_PANE_PX = 40
 
 type PreviewMode = 'dark' | 'light'
@@ -39,18 +30,11 @@ type TerminalSettingsPreviewProps = {
   description?: string
   settings: GlobalSettings
   systemPrefersDark: boolean
-  /** Optional override for `settings.terminalFontFamily`. Set by the font
-   *  picker while the user hovers a dropdown option so they can preview a
-   *  font without committing the selection. */
+  /** Override for `settings.terminalFontFamily`; set by the font picker on hover to preview a font before committing. */
   previewFontFamily?: string | null
-  /** Force the preview into this mode regardless of app settings. Used by
-   *  the Dark/Light theme sections so each pins its own theme. When set,
-   *  the in-header theme toggle is hidden. */
+  /** Force the preview into this mode regardless of app settings; hides the in-header theme toggle when set. */
   modeOverride?: PreviewMode
-  /** When true, render a Moon/Sun toggle in the card header so the user
-   *  can flip the preview between dark and light themes without changing
-   *  the app theme. Initial mode follows the active app theme. Ignored
-   *  when `modeOverride` is set. */
+  /** Render a Moon/Sun header toggle to flip the preview theme without changing the app theme. Ignored when `modeOverride` is set. */
   showThemeToggle?: boolean
 }
 
@@ -82,29 +66,19 @@ export function TerminalSettingsPreview({
   const effectiveFontFamily = previewFontFamily || settings.terminalFontFamily
   const terminalLineHeight = normalizeTerminalLineHeight(settings.terminalLineHeight)
 
-  // Why: lazy-init from the active app theme so the toggle starts in the
-  // user's current mode. After init the toggle is independent — flipping
-  // it doesn't change app settings, and changing the app theme later
-  // doesn't reset the toggle.
+  // Why: lazy-init from the active app theme; after mount the toggle is independent of later app-theme changes.
   const [togglePreviewMode, setTogglePreviewMode] = useState<PreviewMode>(() =>
     resolveAppMode(settings, systemPrefersDark)
   )
   const [previewPaneDividerVisible, setPreviewPaneDividerVisible] = useState(false)
 
-  // Why: precedence — modeOverride pins the mode; otherwise the in-header
-  // toggle drives it; otherwise follow whatever the app is set to right
-  // now (recomputed each render so plain previews track app theme changes).
+  // Why: recomputed each render so plain previews (no override/toggle) track live app-theme changes.
   const effectiveMode: PreviewMode =
     modeOverride ??
     (showThemeToggle ? togglePreviewMode : resolveAppMode(settings, systemPrefersDark))
 
-  // Why: reuse the live-pane resolver so divider color, theme palette, and
-  // the dark/light variant rules (e.g. `useSeparateLightTheme`) stay in
-  // lockstep with what real terminal panes render.
-  // Why: list each property resolveEffectiveTerminalAppearance reads instead
-  // of the whole settings object so unrelated changes (font, cursor) don't
-  // re-derive the appearance. The lint can't see that settings flows through
-  // the helper to those specific properties.
+  // Why: reuse the live-pane resolver so divider color, theme palette, and dark/light variant rules stay in lockstep.
+  // Why: list resolveEffectiveTerminalAppearance's inputs explicitly so unrelated changes (font, cursor) don't re-derive.
   const appearance = useMemo(
     () =>
       resolveEffectiveTerminalAppearance({ ...settings, theme: effectiveMode }, systemPrefersDark),
@@ -121,8 +95,7 @@ export function TerminalSettingsPreview({
     ]
   )
 
-  // Why: same — list the composeActiveTerminalTheme inputs explicitly so font
-  // and cursor option changes don't trigger a buffer rewrite.
+  // Why: list composeActiveTerminalTheme inputs explicitly so font/cursor changes don't trigger a buffer rewrite.
   const composedTheme = useMemo(
     () => composeActiveTerminalTheme(appearance.theme, settings),
     // oxlint-disable-next-line react-hooks/exhaustive-deps
@@ -146,17 +119,12 @@ export function TerminalSettingsPreview({
     const weights = resolveTerminalFontWeights(settings.terminalFontWeight)
     skipInitialOptionMutationRef.current = true
     skipInitialThemeRewriteRef.current = true
-    // Why: DOM renderer only — multiple previews can mount at once and
-    // WebGL contexts are scarce.
-    // Why disableStdin: read-only preview. tabIndex/aria-hidden on the
-    // wrapper don't reach xterm's internal textarea; disableStdin does.
+    // Why: DOM renderer only — WebGL contexts are scarce and multiple previews can mount at once.
+    // Why disableStdin: read-only; tabIndex/aria-hidden on the wrapper don't reach xterm's internal textarea, but this does.
     const terminal = new Terminal({
       ...buildDefaultTerminalOptions(),
       disableStdin: true,
-      // Why mirror cursorInactiveStyle: xterm renders the cursor as a hollow
-      // outline when the terminal is not focused. The preview is read-only and
-      // never gets focused, so without mirroring the user wouldn't see their
-      // selected cursor shape on the trailing prompt.
+      // Why mirror cursorInactiveStyle: preview is never focused, and xterm defaults the unfocused cursor to a hollow outline.
       cursorInactiveStyle: settings.terminalCursorStyle,
       cursorStyle: settings.terminalCursorStyle,
       cursorBlink: settings.terminalCursorBlink,
@@ -188,14 +156,11 @@ export function TerminalSettingsPreview({
       terminal.dispose()
       terminalRef.current = null
     }
-    // Why empty deps: mount effect intentionally runs once. Subsequent
-    // setting changes (including cursor style) flow through the dedicated
-    // option-mutation effects below.
+    // Why empty deps: mount effect runs once; later setting changes flow through the option-mutation effects below.
     // oxlint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
-  // Why: font/cursor options are mutated directly so the preview repaints in
-  // xterm's normal cycle. No fit/refit needed since cols/rows are pinned.
+  // Why: mutate options directly so xterm repaints in its normal cycle; no refit needed since cols/rows are pinned.
   useEffect(() => {
     const terminal = terminalRef.current
     if (!terminal) {
@@ -212,8 +177,7 @@ export function TerminalSettingsPreview({
     terminal.options.fontWeightBold = weights.fontWeightBold
     terminal.options.lineHeight = terminalLineHeight
     terminal.options.cursorStyle = settings.terminalCursorStyle
-    // Why: see constructor — mirror so the unfocused cursor reflects the
-    // user's chosen shape (xterm defaults inactive to 'outline').
+    // Why: mirror so the unfocused cursor reflects the chosen shape (xterm defaults inactive to 'outline'; see constructor).
     terminal.options.cursorInactiveStyle = settings.terminalCursorStyle
     terminal.options.cursorBlink = settings.terminalCursorBlink
   }, [
@@ -231,21 +195,14 @@ export function TerminalSettingsPreview({
       return
     }
     terminal.options.theme = composedTheme
-    // Why: matches the live pane policy in applyTerminalAppearance — without
-    // this, an opacity < 1 background renders opaque inside xterm even though
-    // the theme color carries an alpha channel.
+    // Why: xterm renders an alpha-channel background opaque unless allowTransparency is set (matches applyTerminalAppearance).
     terminal.options.allowTransparency =
       settings.terminalBackgroundOpacity !== undefined && settings.terminalBackgroundOpacity < 1
     if (skipInitialThemeRewriteRef.current) {
       skipInitialThemeRewriteRef.current = false
       return
     }
-    // Why reset() not clear(): clear() keeps the row the cursor sits on, and
-    // our buffer ends mid-line on the prompt — so a follow-up clear+write
-    // would leave the trailing prompt fragment and append the new buffer
-    // beneath it, producing the duplicated content seen during font swaps.
-    // reset() restores cursor home + wipes the buffer so the rewrite starts
-    // from a clean slate.
+    // Why reset() not clear(): buffer ends mid-line on the prompt, so clear()+write would duplicate the trailing fragment.
     terminal.reset()
     terminal.write(PREVIEW_BUFFER)
   }, [composedTheme, settings.terminalBackgroundOpacity])
@@ -262,8 +219,7 @@ export function TerminalSettingsPreview({
       try {
         terminal.loadAddon(addon)
         ligaturesAddonRef.current = addon
-        // Why: the preview writes its sample before this effect runs; repaint
-        // so already-rendered operators switch to ligature glyphs immediately.
+        // Why: sample is written before this effect runs; repaint so already-rendered operators switch to ligature glyphs.
         terminal.refresh(0, terminal.rows - 1)
       } catch (err) {
         addon.dispose()
@@ -343,9 +299,7 @@ export function TerminalSettingsPreview({
         </div>
       </CardHeader>
       <CardContent className="px-4 pb-4">
-        {/* Why: flex layout with xterm on the left and a stub pane on the
-            right keeps inactive-pane opacity visible. The divider stays
-            preview-only and opt-in so the default preview remains clean. */}
+        {/* Why: stub pane on the right keeps inactive-pane opacity visible; divider is opt-in to keep the default preview clean. */}
         <div className="flex h-[300px] flex-col overflow-hidden rounded-md border border-border/50">
           <div className="flex min-h-0 flex-1 overflow-hidden" aria-hidden="true">
             <div
diff --git a/src/renderer/src/components/sidebar/RemoteFileBrowser.tsx b/src/renderer/src/components/sidebar/RemoteFileBrowser.tsx
index dc03bfacc7c..7673e023192 100644
--- a/src/renderer/src/components/sidebar/RemoteFileBrowser.tsx
+++ b/src/renderer/src/components/sidebar/RemoteFileBrowser.tsx
@@ -56,29 +56,21 @@ export function RemoteFileBrowser({
   const [error, setError] = useState<string | null>(null)
   const [filter, setFilter] = useState('')
   const [fileHint, setFileHint] = useState(false)
-  // Preview state drives the list while path mode is active. It is kept
-  // separate from committed state so typing `Documents/` does not silently
-  // change the `Select folder` target before the user commits.
+  // Drives the list during path mode; separate from committed state so typing doesn't move the Select target before commit.
   const [preview, setPreview] = useState<PreviewState | null>(null)
   const genRef = useRef(0)
   const previewGenRef = useRef(0)
   const inputRef = useRef<HTMLInputElement>(null)
   const fileHintTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
-  // Why: paste resolution intentionally runs next tick; closing the picker
-  // before then should cancel stale preview work.
+  // Why: paste resolution runs next tick; closing the picker before then must cancel stale preview work.
   const pasteResolveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const clickTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
-  // Cache directory listings by absolute resolved path for the lifetime of
-  // the picker so ordinary typing issues at most one remote call per newly
-  // committed segment. targetId does not change within a picker instance.
+  // Per-picker listing cache keyed by resolved path, so typing issues at most one remote call per committed segment.
   const listingCacheRef = useRef<Map<string, BrowseResult>>(new Map())
-  // Resolved remote home, cached after the first `browseDir('~')`. Used to
-  // anchor `~` and `~/...` paths without hardcoding a home directory.
+  // Resolved remote home, cached after the first browseDir('~'); anchors `~`/`~/...` without hardcoding a home dir.
   const homePathRef = useRef<string | null>(null)
-  // The committed-path portion of the raw input that the current preview
-  // reflects (everything up to and including the final `/`). If the user's
-  // next keystroke leaves this unchanged, we can skip re-resolving.
+  // Committed-path portion (through the final `/`) the preview reflects; if unchanged next keystroke, skip re-resolving.
   const lastCommittedPrefixRef = useRef<string>('')
 
   const clearFileHint = useCallback(() => {
@@ -99,8 +91,7 @@ export function RemoteFileBrowser({
       if (node !== null) {
         return
       }
-      // Why: remote browse generations and input timers are scoped to this
-      // picker owner; clear them when the owner detaches.
+      // Why: browse generations and timers are scoped to this picker owner; clear them when it detaches.
       invalidateBrowseRequests()
       for (const timerRef of [
         fileHintTimerRef,
@@ -130,10 +121,7 @@ export function RemoteFileBrowser({
             dirPath
           )
       listingCacheRef.current.set(result.resolvedPath, result)
-      // Also cache under the requested dirPath when it differs from the
-      // server-resolved canonical path (e.g. `~`, `~/foo`, or a relative
-      // input). Without this, the next identical request would miss the
-      // cache and re-hit the SSH backend.
+      // Also key by the requested dirPath (e.g. `~`, relative) so an identical request doesn't re-hit the SSH backend.
       if (dirPath !== result.resolvedPath) {
         listingCacheRef.current.set(dirPath, result)
       }
@@ -154,9 +142,7 @@ export function RemoteFileBrowser({
         }
         setResolvedPath(result.resolvedPath)
         setEntries(result.entries)
-        // Only the bare-tilde listing returns the home directory itself;
-        // `~/sub` resolves to `.../sub`, which must not overwrite the home
-        // anchor used for resolving later `~/...` inputs.
+        // Only bare `~` yields the home dir itself; `~/sub` resolves elsewhere and must not overwrite the home anchor.
         if (dirPath === '~') {
           homePathRef.current = result.resolvedPath
         }
@@ -175,10 +161,7 @@ export function RemoteFileBrowser({
     [fetchListing]
   )
 
-  // All user-initiated navigation goes through this wrapper so filter +
-  // preview + hint state is always cleared. Bumping previewGenRef here
-  // ensures any in-flight path preview whose target is no longer relevant
-  // can't overwrite committed state after a breadcrumb or row click.
+  // Central nav clears filter/preview/hint and bumps previewGenRef so a stale in-flight preview won't clobber committed state.
   const navigate = useCallback(
     (dirPath: string) => {
       setFilter('')
@@ -231,9 +214,7 @@ export function RemoteFileBrowser({
     }, FILE_HINT_MS)
   }, [])
 
-  // Resolve a path-mode input and push the result into preview state.
-  // Exposed as a ref-callback so it can run immediately on paste or on the
-  // debounce tick without re-creating on every keystroke.
+  // Resolve a path-mode input into preview state; stable callback so paste and the debounce tick share one instance.
   const resolvePathInput = useCallback(
     async (raw: string) => {
       const parsed = parsePathInput(raw)
@@ -253,8 +234,7 @@ export function RemoteFileBrowser({
         return
       }
 
-      // Pick the base path. For `~` we must know the resolved home; if we
-      // haven't fetched it yet, fetch once (and cache it) before resolving.
+      // Pick the base path; `~` needs the resolved home, so fetch and cache it once before resolving.
       let basePath: string
       if (parsed.base === 'root') {
         basePath = '/'
@@ -355,10 +335,7 @@ export function RemoteFileBrowser({
     [resolvedPath, fetchListing]
   )
 
-  // Called on every user edit to the input. Filter-mode edits stay local;
-  // path-mode edits trigger a debounced resolve. Partial trailing-segment
-  // changes that don't change committed segments only update the preview
-  // filter, so typing `Documents/orc` → `Documents/orca` is free.
+  // Filter-mode edits stay local; path-mode edits trigger a debounced resolve, but trailing-filter-only edits stay local too.
   const handleInputChange = useCallback(
     (raw: string) => {
       clearFileHint()
@@ -381,8 +358,7 @@ export function RemoteFileBrowser({
       }
 
       if (!isPathMode(raw)) {
-        // Leaving path mode: drop preview immediately so the committed
-        // directory re-appears without a flicker.
+        // Leaving path mode: drop preview immediately so the committed directory reappears without a flicker.
         if (preview) {
           setPreview(null)
           previewGenRef.current++
@@ -395,10 +371,7 @@ export function RemoteFileBrowser({
       }
 
       const parsed = parsePathInput(raw)
-      // Partial trailing-segment edits: if the committed-path portion of the
-      // input is unchanged from what the preview already resolved, update
-      // only the local filter. This is the fast path that guarantees typing
-      // `Documents/orc` → `Documents/orca` issues no `browseDir` call.
+      // Fast path: unchanged committed prefix updates only the local filter, so intra-segment typing issues no browseDir call.
       if (
         parsed.mode === 'path' &&
         preview &&
@@ -406,11 +379,7 @@ export function RemoteFileBrowser({
         !parsed.invalid &&
         committedPrefix(raw) === lastCommittedPrefixRef.current
       ) {
-        // Intentionally allow this fast path to run even while
-        // preview.loading is true: the committed prefix is unchanged, so
-        // the in-flight resolve will land on the same listing and only the
-        // trailing filter needs updating. Blocking on loading would make
-        // keystrokes during a slow resolve feel unresponsive.
+        // Runs even while preview.loading: unchanged prefix hits the same listing, so blocking keystrokes would only feel laggy.
         setPreview({ ...preview, filter: parsed.trailingFilter })
         return
       }
@@ -434,9 +403,7 @@ export function RemoteFileBrowser({
       if (shouldDeferRemoteFileBrowserPasteResolve(e.clipboardData.getData('text/plain'))) {
         return
       }
-      // Paste resolves immediately; no debounce. React's onChange still fires
-      // after the paste is applied to the input value, so we defer to the
-      // next tick so `filter` reflects the pasted value.
+      // Paste resolves immediately (no debounce), but defer a tick so onChange has applied the pasted value to filter.
       if (pasteResolveTimerRef.current) {
         clearTimeout(pasteResolveTimerRef.current)
       }
@@ -455,23 +422,17 @@ export function RemoteFileBrowser({
     [resolvePathInput]
   )
 
-  // Select always returns the committed current directory. Disabled while a
-  // path-mode preview is visible so the user can't silently select the old
-  // committed directory while the list shows a different preview directory.
+  // Select always returns the committed directory; disabled during a path preview to avoid a mismatched selection.
   const handleSelect = useCallback(() => {
     onSelect(resolvedPath)
   }, [resolvedPath, onSelect])
 
-  // Single-click navigates; double-click on a folder selects it.
-  // When preview is active, row clicks must be relative to the preview path,
-  // not the committed `resolvedPath`.
+  // When a preview is active, row clicks resolve relative to the preview path, not the committed resolvedPath.
   const listParentPath = preview?.resolvedPath ?? resolvedPath
 
   const handleRowClick = useCallback(
     (entry: DirEntry) => {
-      // Stale entries from the previous resolved listing can remain on
-      // screen while a new preview resolves; clicking them would navigate
-      // relative to a path that no longer matches what the user is typing.
+      // Stale rows from the prior listing may still show while a preview resolves; clicking them would navigate a mismatched path.
       if (preview?.loading) {
         return
       }
@@ -492,8 +453,7 @@ export function RemoteFileBrowser({
 
   const handleRowDoubleClick = useCallback(
     (entry: DirEntry) => {
-      // Same rationale as handleRowClick: do not act on stale rows while
-      // the preview listing is being re-resolved.
+      // Same as handleRowClick: don't act on stale rows while the preview listing re-resolves.
       if (!entry.isDirectory || preview?.loading) {
         return
       }
@@ -516,15 +476,13 @@ export function RemoteFileBrowser({
             return
           }
           const parsed = parsePathInput(filter)
-          // Fully-resolved directory (trailing `/` or bare base marker):
-          // navigate to the preview path itself.
+          // Fully-resolved directory (trailing `/` or bare base marker): navigate to the preview path itself.
           if (parsed.mode === 'path' && parsed.trailingFilter === '') {
             e.preventDefault()
             navigate(preview.resolvedPath)
             return
           }
-          // Trailing filter — try to resolve it to a single folder match in
-          // the preview listing, mirroring filter-mode Enter.
+          // Trailing filter: resolve to a single folder match in the preview listing, mirroring filter-mode Enter.
           const filtered = filterEntries(preview.entries, preview.filter)
           const action = decideEnterAction(filtered)
           if (action.type === 'navigate') {
@@ -556,8 +514,7 @@ export function RemoteFileBrowser({
           setFilter('')
           setPreview(null)
           previewGenRef.current++
-          // Cancel any pending debounced resolve so it can't fire after
-          // the user has already dismissed the preview with Escape.
+          // Cancel any pending debounced resolve so it can't fire after Escape dismisses the preview.
           if (debounceTimerRef.current) {
             clearTimeout(debounceTimerRef.current)
             debounceTimerRef.current = null
@@ -568,8 +525,7 @@ export function RemoteFileBrowser({
         }
       }
       if (e.key === 'Backspace' && filter === '' && !preview) {
-        // Backspace in an empty input climbs to the parent — only when the
-        // caret is in empty text, so in-word Backspaces are untouched.
+        // Backspace in an empty input climbs to the parent; in-word backspaces are untouched.
         if (resolvedPath !== '/') {
           e.preventDefault()
           navigateUp()
@@ -592,8 +548,7 @@ export function RemoteFileBrowser({
 
   const pathSegments = resolvedPath.split('/').filter(Boolean)
 
-  // What the list should render: preview listing (with its own filter and
-  // error) during path mode, committed listing otherwise.
+  // Render the preview listing (own filter/error) during path mode, the committed listing otherwise.
   const isPreviewActive = preview !== null
   const showPreviewLoading = isPreviewActive && preview!.loading
   const displayEntries = isPreviewActive ? previewFilteredEntries : filteredEntries
@@ -612,9 +567,7 @@ export function RemoteFileBrowser({
         { value0: noMatchesFilter }
       )
 
-  // Disable Select folder while a non-empty path-mode preview is visible so
-  // the committed directory isn't silently selected while the list shows a
-  // different preview directory.
+  // Disable Select during a non-empty path preview so the committed dir isn't silently selected under a different-looking list.
   const selectDisabled = loading || (isPreviewActive && filter !== '')
 
   return (
@@ -729,8 +682,7 @@ export function RemoteFileBrowser({
               </p>
             </div>
           ) : displayEntries.length === 0 && !preview?.error ? (
-            // Directory has contents; filter hides them all. Distinguishing
-            // filter emptiness from directory emptiness keeps copy accurate.
+            // Directory has contents but the filter hides them all — distinct from an empty directory so copy stays accurate.
             <div className="flex items-center justify-center h-full">
               <p className="text-xs text-muted-foreground">{displayNoMatchesCopy}</p>
               <p className="text-xs text-muted-foreground">{displayNoMatchesCopy}</p>
@@ -800,9 +752,7 @@ export function RemoteFileBrowser({
   )
 }
 
-// Returns the portion of `raw` before its final `/`, used to decide whether
-// a keystroke only changed the trailing filter (cheap local update) or
-// changed a committed segment (requires re-resolving).
+// Portion of raw before the final `/`; lets callers tell a trailing-filter-only edit from a committed-segment change.
 function committedPrefix(raw: string): string {
   const i = raw.lastIndexOf('/')
   return i === -1 ? '' : raw.slice(0, i + 1)
diff --git a/src/renderer/src/components/sidebar/WorktreeCard.tsx b/src/renderer/src/components/sidebar/WorktreeCard.tsx
index d49d080bee6..cabb1f3b08a 100644
--- a/src/renderer/src/components/sidebar/WorktreeCard.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCard.tsx
@@ -162,8 +162,7 @@ function getDirectoryName(folderPath: string): string {
   return parts.at(-1) || normalized || folderPath
 }
 
-// Why: the pinned repo icon and the compact inline badge share one chip shell;
-// keep the box + tooltip identical so both repo cues read as the same affordance.
+// Why: pinned repo icon and compact inline badge share this chip shell so both repo cues read as the same affordance.
 function RepoIdentityChip({
   repo,
   children
@@ -333,9 +332,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
 
   // SSH disconnected state
   const sshStatus = useAppStore((s) => {
-    // Why: runtime-owned (per-workspace-env) SSH targets are hidden and their relay health is
-    // owned by the runtime layer — Orca suppresses their ssh:state-changed broadcasts, so their
-    // state is absent here. Don't show a false "disconnected" SSH chip for them.
+    // Why: runtime-owned SSH targets suppress their ssh:state-changed broadcasts, so don't show a false "disconnected" chip for them.
     if (!repo?.connectionId || isRuntimeOwnedSshTargetId(repo.connectionId)) {
       return null
     }
@@ -343,17 +340,12 @@ const WorktreeCard = React.memo(function WorktreeCard({
     return state?.status ?? 'disconnected'
   })
   const isSshDisconnected = sshStatus != null && sshStatus !== 'connected'
-  // Why: a terminal view already carries its own in-pane reconnect overlay, so
-  // the blocking dialog would just duplicate it there; reserve the dialog for
-  // views without an in-context prompt. Default to terminal (suppress) for the
-  // ambiguous case so we err toward non-blocking.
+  // Why: terminal views have their own reconnect overlay; reserve the blocking dialog for non-terminal views (default to terminal when ambiguous).
   const activeViewIsTerminal = useAppStore(
     (s) => (s.activeTabTypeByWorktree?.[worktree.id] ?? 'terminal') === 'terminal'
   )
 
-  // Why: runtime ("Orca server") hosts get the same disconnected treatment as
-  // SSH — when the host's runtime environment has no live status, its worktrees
-  // are dimmed and marked disconnected instead of looking fully available.
+  // Why: runtime ("Orca server") hosts get the same disconnected dimming as SSH when their environment has no live status.
   const isRuntimeDisconnected = useAppStore((s) => {
     const parsed = parseExecutionHostId(repo?.executionHostId)
     if (parsed?.kind !== 'runtime') {
@@ -361,16 +353,11 @@ const WorktreeCard = React.memo(function WorktreeCard({
     }
     return !s.runtimeStatusByEnvironmentId.get(parsed.environmentId)?.status
   })
-  // Why: the reconnect dialog is blocking, so it is never auto-shown for a
-  // disconnected worktree just because it is the active/restored card — that
-  // would steal focus app-wide while the user works elsewhere. The card chip,
-  // status bar, and terminal overlay carry the non-blocking disconnected state;
-  // the dialog only opens on deliberate focus (see handleClick).
+  // Why: the reconnect dialog blocks, so it never auto-shows for the active card (would steal app-wide focus); opens only on deliberate focus (handleClick).
   const [showDisconnectedDialog, setShowDisconnectedDialog] = useState(false)
   const [titleRenaming, setTitleRenaming] = useState(false)
   const [showRenameErrorDialog, setShowRenameErrorDialog] = useState(false)
-  // Why: read the target label from the store (populated during hydration in
-  // useIpcEvents.ts) instead of calling listTargets IPC per card instance.
+  // Why: read the target label from the store (hydrated in useIpcEvents.ts) instead of a listTargets IPC per card.
   const sshTargetLabel = useAppStore((s) =>
     repo?.connectionId ? (s.sshTargetLabels.get(repo.connectionId) ?? '') : ''
   )
@@ -382,8 +369,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
   const folderWorkspaceId =
     workspaceScope?.type === 'folder' ? workspaceScope.folderWorkspaceId : null
   const isFolder = repo ? isFolderRepo(repo) : folderWorkspaceId !== null
-  // Why: project groups are the product gate for folder workspaces, so folder
-  // paths stay hidden from identity surfaces until that capability exists.
+  // Why: project groups gate folder workspaces, so folder paths stay hidden from identity surfaces until that capability exists.
   const hasProjectGroups = projectGroups.length > 0
   const branchIdentityDisplay = !isFolder && branch.length > 0 ? branch : undefined
   const folderPathIdentityDisplay =
@@ -430,8 +416,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
           true
         )
       : ''
-  // Why: use 'all' to fetch from all Linear workspaces. The issue might belong
-  // to a different workspace than the currently selected one.
+  // Why: use 'all' — the issue may belong to a different Linear workspace than the selected one.
   const linearIssueCacheKey = worktree.linkedLinearIssue ? `all::${worktree.linkedLinearIssue}` : ''
 
   // Subscribe to ONLY the specific cache entry, not entire review/issue caches.
@@ -465,10 +450,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
     linkedBitbucketPR !== null ||
     linkedAzureDevOpsPR !== null ||
     linkedGiteaPR !== null
-  // Why: ChecksPanel can discover a branch PR before hosted-review metadata
-  // warms, and transient older hosted-review misses can race with that cache.
-  // A newer miss only yields to merged PR cache when the stored worktree head
-  // proves the cached PR still describes the checked-out commit.
+  // Why: a newer hosted-review miss trusts the merged-PR cache only when the stored head proves it still describes the current commit.
   const cachedBranchPR = prCacheEntry?.data
   const cachedBranchPRFetchedAt = prCacheEntry?.fetchedAt
   const cachedMergedBranchPRMatchesCurrentHead = isCachedMergedBranchPRCurrentForWorktree(
@@ -528,9 +510,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
     (worktree.linkedIssue
       ? {
           number: worktree.linkedIssue,
-          // Why: linked metadata is persisted immediately, but GitHub details
-          // arrive asynchronously. Show the durable link number instead of
-          // making the worktree look unlinked while the cache warms.
+          // Why: linked metadata persists immediately but GitHub details arrive async; show the link number so it doesn't look unlinked.
           title: issue === null ? 'Issue details unavailable' : 'Loading issue...'
         }
       : null)
@@ -539,11 +519,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
     ? (linearIssueEntry?.data ?? linearIssueFallbackEntry?.data)
     : null
 
-  // Why: construct a Linear URL from the organizationUrlKey and identifier
-  // when the API hasn't returned the full issue data yet, so the user can
-  // still navigate to the issue even while it's loading.
-  // Use the issue's workspaceId if available to get the correct organizationUrlKey,
-  // otherwise fall back to the currently selected workspace.
+  // Why: build a fallback Linear URL from org key + identifier while full issue data is still loading, so the link stays navigable.
   const linearOrgUrlKey = linearStatus?.viewer?.organizationUrlKey
   const linearWorkspaceUrlKeys = linearStatus?.workspaces?.map((ws) => ({
     id: ws.id,
@@ -624,12 +600,9 @@ const WorktreeCard = React.memo(function WorktreeCard({
   const detailsHoverControl = useWorktreeCardDetailsHoverControl()
   const hoverDetailsOpen = detailsHoverControl.hoverOpen
 
-  // Skip hosted-review fetches when the corresponding card surfaces are hidden.
-  // This preference is purely presentational, so background refreshes would
-  // spend rate limit budget on data the user cannot see.
+  // Why: card surfaces are presentational, so skip hosted-review fetches when hidden to save rate-limit budget.
   useEffect(() => {
-    // Why: paired web should not fan out per-card decoration RPCs during
-    // startup; host session/tab parity is the critical path.
+    // Why: paired web must not fan out per-card decoration RPCs during startup; host session/tab parity is critical.
     if (isWebClient()) {
       return
     }
@@ -644,8 +617,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
       return
     }
     const refreshHostedReview = (): void => {
-      // Why: branch lookup is lossy for fork/deleted-head PRs; reuse a known PR
-      // number from explicit metadata whenever we have one.
+      // Why: branch lookup is lossy for fork/deleted-head PRs; reuse a known PR number from explicit metadata when we have one.
       void fetchHostedReviewForBranch(repo.path, branch, {
         repoId: repo.id,
         linkedGitHubPR: worktree.linkedPR ?? null,
@@ -660,8 +632,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
         staleWhileRevalidate: true
       })
     }
-    // Why: PRs created outside Orca (for example `gh pr create`) do not emit a
-    // renderer event; visible-card polling discovers them after an earlier miss.
+    // Why: PRs created outside Orca (e.g. `gh pr create`) emit no renderer event; poll visible cards to discover them.
     return installWindowVisibilityInterval({
       run: refreshHostedReview,
       intervalMs: HOSTED_REVIEW_CARD_REFRESH_INTERVAL_MS
@@ -697,8 +668,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
     ) {
       return
     }
-    // Why: hidden card metadata is revealed on whole-card hover. Fetch lazily
-    // here instead of restoring always-on background decoration polling.
+    // Why: hidden card metadata is revealed on whole-card hover, so fetch lazily instead of always-on polling.
     void fetchHostedReviewForBranch(repo.path, branch, {
       repoId: repo.id,
       linkedGitHubPR: worktree.linkedPR ?? null,
@@ -731,12 +701,9 @@ const WorktreeCard = React.memo(function WorktreeCard({
     hostedReviewCacheKey
   ])
 
-  // Same rationale for issues: once that surface is hidden, polling only burns
-  // GitHub calls and keeps stale-but-invisible data warm for no user benefit.
+  // Why: same as above for issues — hidden-surface polling only burns GitHub calls for invisible data.
   useEffect(() => {
-    // Why: paired web startup can render hundreds of visible workspace cards.
-    // The host is authoritative for repo metadata; issuing decoration lookups
-    // from the browser floods the runtime RPC path and delays live surfaces.
+    // Why: per-card decoration lookups from the browser flood the RPC path at paired-web startup; the host is authoritative.
     if (
       isWebClient() ||
       !repo ||
@@ -750,9 +717,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
 
     const issueNumber = worktree.linkedIssue
 
-    // Background poll as fallback (activity triggers handle the fast path).
-    // The interval itself is stopped while hidden so issue cards do not keep
-    // long-lived workspaces waking just to skip their fetch.
+    // Why: fallback poll behind activity triggers; stopped while hidden to avoid waking idle workspaces.
     return installWindowVisibilityInterval({
       run: () => void fetchIssue(repo.path, issueNumber, { repoId: repo.id }),
       intervalMs: 5 * 60_000
@@ -824,12 +789,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
         return
       }
       const selection = window.getSelection()
-      // Why: only suppress the click when the selection is *inside this card*
-      // (a real drag-select on the card's own text). A selection anchored
-      // elsewhere — e.g. inside the markdown preview while the AI is streaming
-      // writes — must not block worktree switching, otherwise the user can't
-      // leave the current worktree without first clicking into a terminal to
-      // clear the foreign selection.
+      // Why: only suppress the click for a selection inside this card; a foreign selection must not block worktree switching.
       if (selection && selection.toString().length > 0) {
         const card = event.currentTarget
         const anchor = selection.anchorNode
@@ -854,9 +814,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
         event.stopPropagation()
         return
       }
-      // Why: route sidebar clicks through the shared activation path so the
-      // back/forward stack stays complete for the primary worktree navigation
-      // surface instead of only recording palette-driven switches.
+      // Why: route sidebar clicks through the shared activation path so the back/forward stack stays complete.
       recordRendererCrashBreadcrumb('sidebar_worktree_activate', {
         worktreeId: worktree.id,
         repoId: worktree.repoId,
@@ -865,10 +823,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
       })
       onImmediateActivate?.(worktree.id, activationRowKey)
       void activateWorktreeFromSidebar(worktree.id)
-      // Why: clicking the card is a deliberate focus of this project, so the
-      // blocking reconnect prompt is appropriate here (unlike auto-restore) —
-      // but skip it when a terminal is active, since that pane already shows the
-      // in-context reconnect overlay and a second prompt would just duplicate it.
+      // Why: a deliberate card click warrants the blocking reconnect prompt; skip it when a terminal already shows the overlay.
       if (isSshDisconnected && !activeViewIsTerminal) {
         setShowDisconnectedDialog(true)
       }
@@ -929,8 +884,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
     },
     [worktree.id, worktree.isUnread, updateWorktreeMeta]
   )
-  // Why: delete is destructive, so it only appears while the user is holding
-  // Option/Alt instead of being part of the ordinary hover chrome.
+  // Why: delete is destructive, so it only appears while holding Option/Alt, not in the ordinary hover chrome.
   const showDeleteQuickAction =
     !affiliateListMode &&
     canShowWorkspaceDeleteQuickAction({
@@ -1039,16 +993,13 @@ const WorktreeCard = React.memo(function WorktreeCard({
 
   const stopQuickActionPointerPropagation = useCallback(
     (event: React.PointerEvent<HTMLButtonElement>) => {
-      // Why: the Kanban board is dismissed by document-level pointer handling.
-      // Quick card actions mutate metadata, but must not count as card activation.
+      // Why: document-level pointer handling dismisses the Kanban board; quick actions must not count as card activation.
       event.stopPropagation()
     },
     []
   )
 
-  // Why: unread is part of the left status lane, so the Status display toggle
-  // owns both the dot/PR slot and unread emphasis. The persisted
-  // `worktree.isUnread` flag is unchanged; only the rendering changes.
+  // Why: unread lives in the left status lane, so the Status toggle owns both the dot/PR slot and unread emphasis.
   const showUnreadEmphasis = showStatus && worktree.isUnread
   const hoverIssue = issueDisplay
   const hoverLinearIssue = linearIssueDisplay
@@ -1166,11 +1117,9 @@ const WorktreeCard = React.memo(function WorktreeCard({
   const cacheTtlMs = useAppStore((s) =>
     showAggregateCacheTimer ? (s.settings?.promptCacheTtlMs ?? 0) : 0
   )
-  // Why: pinned trees mix repos in one section; a leading repo icon keeps the
-  // list scannable, so it shows regardless of groupBy's hideRepoBadge.
+  // Why: pinned trees mix repos, so the repo icon shows regardless of groupBy's hideRepoBadge.
   const showPinnedRepoIcon = inPinnedSection && !!repo
-  // Why: the new card style retired the Compact/Detailed layout switch; repo
-  // identity uses the same compact chip as pinned cards instead of a lower pill.
+  // Why: new card style retired the Compact/Detailed switch; repo identity uses the compact chip, not a lower pill.
   const showRepoIdentityInTitle = newCardStyle || compactCards
   const showInlineRepoBadge =
     showRepoIdentityInTitle && !!repo && !hideRepoBadge && !isFolder && !showPinnedRepoIcon
@@ -1183,21 +1132,17 @@ const WorktreeCard = React.memo(function WorktreeCard({
     branch.length > 0 &&
     !newCardStyle &&
     (!compactCards || branch !== worktree.displayName)
-  // Why: rebases already surface in source control; keep dense cards from
-  // carrying a persistent rebase chip while preserving other interruption cues.
+  // Why: rebases already surface in source control, so dense cards skip the persistent rebase chip.
   const showConflictOperationBadge =
     !!conflictOperation && conflictOperation !== 'unknown' && conflictOperation !== 'rebase'
   const hasMetadataBadge = showConflictOperationBadge
   const showUnreadQuickAction = !affiliateListMode && showStatus && !newCardStyle
-  // Why: the slot owns the tiny unread/status lane; legacy keeps the bell
-  // toggle, while the experimental card keeps the status glyph passive.
+  // Why: the slot owns the unread/status lane; legacy keeps the bell toggle, the new card keeps the glyph passive.
   const showCombinedStatusSlot = showStatus
   const showTitleRowPrimary = compactCards && worktree.isMainWorktree && !isFolder
   const showMetaRowDetails = !newCardStyle && !compactCards && (hasDetails || hasPorts)
   const showTitleRowIndicators = (newCardStyle || compactCards) && (hasDetails || hasPorts)
-  // Why: detailed cards need a stable metadata lane only when it has content.
-  // Grouped project views can hide the repo badge; don't reserve a blank
-  // metadata lane unless branch or detached-head identity has content.
+  // Why: grouped views can hide the repo badge; don't reserve a blank metadata lane unless there's real content.
   const hasDetailedMetaRowContent = Boolean(
     (showRepoBadgeInMetaRow && repo) ||
     showHostContextBadge ||
@@ -1213,8 +1158,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
     ? hasMetadataBadge || cacheStartedAt != null
     : hasDetailedMetaRowContent
   const showHeaderActions = showTitleRowPrimary || showDeleteQuickAction
-  // Why: the hover owns full identity when the row truncates; normalize once
-  // so title/branch de-dupe and identity-only hover eligibility stay in sync.
+  // Why: normalize the title once so title/branch de-dupe and identity-only hover eligibility stay in sync.
   const trimmedVisibleCardTitle = visibleCardTitle.trim()
   const showBranchIdentityHover = newCardStyle
     ? Boolean(identityDisplay) &&
@@ -1242,8 +1186,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
     }) ||
       workspacePorts.length > 0 ||
       hasHoverIdentity)
-  // Why: the parent row owns metadata hover; avoid stacking the title's
-  // truncation tooltip on top of the richer details popover.
+  // Why: the parent row owns metadata hover; don't stack the title's truncation tooltip on the details popover.
   const titleWrapper = newCardStyle
     ? hasHoverDetails
       ? (title: React.ReactElement): React.ReactElement => title
@@ -1278,8 +1221,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
             }
             onOpenAutomation={affiliateListMode ? undefined : handleOpenAutomation}
             onOpenAutomationRun={affiliateListMode ? undefined : handleOpenAutomationRun}
-            // Why: compact mode hides the metadata badge row, so title hover
-            // carries the same explicit-link affordance without adding chrome.
+            // Why: compact mode hides the metadata badge row, so title hover carries the explicit-link affordance.
             onUnlinkReview={
               !affiliateListMode && hasExplicitLinkedReview ? handleUnlinkReview : undefined
             }
@@ -1288,8 +1230,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
           </WorktreeCardDetailsHover>
         )
       : undefined
-  // Why: sidebar rows need a small surface inset, while their content remains
-  // aligned with the pre-inset layout and the repo header hierarchy.
+  // Why: sidebar rows need a small surface inset while content stays aligned with the pre-inset layout.
   const applyNewCardStyleStatusLaneOffset = newCardStyle && showCombinedStatusSlot
   const cardPaddingLeft = flushSurface
     ? getFlushWorktreeCardPaddingLeft(contentIndent, applyNewCardStyleStatusLaneOffset)
@@ -1339,8 +1280,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
         }
         onOpenAutomation={affiliateListMode ? undefined : handleOpenAutomation}
         onOpenAutomationRun={affiliateListMode ? undefined : handleOpenAutomationRun}
-        // Why: branch lookup can show a review without persisted metadata. Only
-        // expose unlink when this workspace has an explicit linked PR/MR.
+        // Why: branch lookup can surface a review without persisted metadata; only unlink when explicitly linked.
         onUnlinkReview={
           !affiliateListMode && hasExplicitLinkedReview ? handleUnlinkReview : undefined
         }
@@ -1396,8 +1336,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
       <div
         className={cn(
           'flex min-w-0 flex-1 flex-col gap-1.5',
-          // Why: inline agent rows intentionally outdent into the card gutter;
-          // title/meta truncation is handled by their own inner elements.
+          // Why: inline agent rows intentionally outdent into the card gutter; inner elements handle truncation.
           showInlineAgentList || (!newCardStyle && lineageChildren)
             ? 'overflow-visible'
             : 'overflow-hidden'
@@ -1479,8 +1418,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
               </RepoIdentityChip>
             )}
 
-            {/* Why: unread alert lives in the left status lane; weight plus dimmed
-                 read titles carry scan contrast in the title row. */}
+            {/* Why: unread alert lives in the left status lane; title-row contrast comes from weight and dimmed read titles. */}
             <WorktreeTitleInlineRename
               displayName={visibleCardTitle}
               disabled={isDeleting || affiliateListMode}
@@ -1503,8 +1441,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
             {typeof worktree.firstAgentMessageRenameError === 'string' &&
             worktree.firstAgentMessageRenameError.length > 0 &&
             !titleRenaming ? (
-              // The full error can be raw agent CLI output, so the title-row
-              // badge opens a dialog instead of squeezing details into a tooltip.
+              // Why: the error can be raw agent CLI output, so the badge opens a dialog rather than a tooltip.
               <Tooltip>
                 <TooltipTrigger asChild>
                   <Button
@@ -1676,8 +1613,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
                 <TruncatedSidebarLabel
                   text={branch}
                   className="text-[11px] text-muted-foreground leading-none"
-                  // Why: the whole-card details hover already exposes full
-                  // identity; a nested tooltip would compete for the same hover.
+                  // Why: whole-card details hover already shows full identity; a nested tooltip would compete for it.
                   tooltipEnabled={!hasHoverDetails}
                 />
               ) : showDetachedHeadInMetaRow && detachedHeadDisplay ? (
@@ -1737,13 +1673,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
           />
         ) : null}
 
-        {/* Why: inline agent list. Gated on the 'inline-agents' card
-             property so users can hide it. Layout coupling: this block
-             grows the card height dynamically — WorktreeList uses
-             measureElement on each row, so the virtualizer re-measures
-             naturally when agents appear/disappear. When agents directly
-             follow the title, counterbalance the card stack gap so both rows
-             read as one compact header group. */}
+        {/* Why: counterbalance the card stack gap (-mt-1) so agents right after the title read as one header group. */}
         {showInlineAgentList && (
           <WorktreeCardAgents
             worktreeId={worktree.id}
@@ -1841,8 +1771,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
         }
         onOpenAutomation={affiliateListMode ? undefined : handleOpenAutomation}
         onOpenAutomationRun={affiliateListMode ? undefined : handleOpenAutomationRun}
-        // Why: branch lookup can show a review without persisted metadata. Only
-        // expose unlink when this workspace has an explicit linked PR/MR.
+        // Why: branch lookup can surface a review without persisted metadata; only unlink when explicitly linked.
         onUnlinkReview={
           !affiliateListMode && hasExplicitLinkedReview ? handleUnlinkReview : undefined
         }
diff --git a/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx b/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx
index 9e8faa70acd..87ab769d138 100644
--- a/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx
@@ -46,20 +46,11 @@ function revealCompactAgentCard(agentListRoot: HTMLElement | null): void {
 type Props = {
   worktreeId: string
   agents?: DashboardAgentRowData[]
-  /** Controls spacing from the card body above. Passed in so the parent can
-   *  decide whether a divider is appropriate — e.g. suppressed when the card
-   *  chrome already provides visual separation. */
+  /** Spacing from the card body above; parent decides whether a divider is appropriate. */
   className?: string
 }
 
-/**
- * Inline agent list rendered directly inside WorktreeCard when the
- * 'inline-agents' card property is enabled. Gives persistent per-card
- * visibility of each agent's live state, prompt, and last message.
- *
- * Reuses useWorktreeAgentRows + DashboardAgentRow so row layout and the
- * derivation stay consistent with the inline agent activity on each card.
- */
+/** Inline agent list rendered inside WorktreeCard when 'inline-agents' is enabled. */
 const WorktreeCardAgents = React.memo(function WorktreeCardAgents({
   worktreeId,
   agents: precomputedAgents,
@@ -70,9 +61,7 @@ const WorktreeCardAgents = React.memo(function WorktreeCardAgents({
   if (agents.length === 0) {
     return null
   }
-  // Why: gate the 30s tick behind non-empty rows by mounting the inner body
-  // only when there's something to show. The setInterval lives in the inner
-  // component's useNow, so idle worktrees don't pay per-card timer cost.
+  // Why: mount the inner body (owns the 30s useNow tick) only for non-empty rows, so idle worktrees pay no timer cost.
   return <WorktreeCardAgentsBody worktreeId={worktreeId} agents={agents} className={className} />
 })
 
@@ -94,24 +83,13 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
   const { targetMode: agentSendPopoverTargetMode, agentStatusEpoch } = useAppStore(
     useShallow((s) => selectSendTargetControlInputs(s, worktreeId))
   )
-  // Why: these five maps are read only to derive send-target eligibility, which
-  // matters only while the send-target popover targets THIS card. Two of them
-  // (runtimePaneTitlesByTabId, agentStatusByPaneKey) churn on every pane-title
-  // and agent-status write app-wide, so subscribing to them unconditionally made
-  // every mounted agent body re-render on unrelated terminals. Gate the
-  // subscription: return a stable empty constant when the popover isn't ours, so
-  // useShallow keeps the same result and idle bodies stop reacting to the churn.
+  // Why: return a stable empty constant unless the send-target popover is ours, so churny pane-title/agent-status maps don't re-render idle bodies.
   const sendTargetInputs = useAppStore(useShallow((s) => selectSendTargetInputs(s, worktreeId)))
   const sendPromptToSidebarAgentTarget = useAppStore((s) => s.sendPromptToSidebarAgentTarget)
   const focusedAgentPaneKey = useFocusedAgentPaneKey(worktreeId)
   const compactAgentListRootRef = useRef<HTMLDivElement | null>(null)
 
-  // Why: subscribe to the ack map reference (Object.is equality) and derive
-  // per-agent unvisited flags locally. Keeps the inline list's bold/mute
-  // behavior consistent with how acks flow elsewhere — rows bold on first
-  // appearance and mute once the user has visited the agent's tab
-  // (useAutoAckViewedAgent acks automatically on terminal focus). Without
-  // this, all inline rows stayed muted regardless of attention state.
+  // Why: derive per-agent unvisited flags from the ack map so rows bold on first appearance and mute once the tab is visited.
   const acknowledgedAgentsByPaneKey = useAppStore((s) => s.acknowledgedAgentsByPaneKey)
   const unvisitedByPaneKey = useMemo(() => {
     const out: Record<string, boolean> = {}
@@ -152,15 +130,12 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
       ])
     )
   }, [
-    // Why: stale-boundary timers bump this epoch without replacing the status
-    // map, so target eligibility must derive again when freshness flips.
+    // Why: stale-boundary timers bump this epoch without replacing the status map, so re-derive when freshness flips.
     agentStatusEpoch,
     agentSendPopoverTargetMode?.sendingPaneKey,
     agentSendPopoverTargetMode?.status,
     isAgentSendTargetModeActive,
-    // sendTargetInputs is a stable empty constant while inactive and a
-    // shallow-compared bundle of the five maps while active, so it covers all
-    // five former deps in one reference.
+    // sendTargetInputs: stable empty when inactive, shallow bundle of the five maps when active — one ref covers all five deps.
     sendTargetInputs,
     worktreeId
   ])
@@ -176,8 +151,7 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
     (tabId: string, paneKey: string) => {
       const parsed = parsePaneKey(paneKey)
       if (!parsed) {
-        // Why: malformed or legacy numeric keys cannot be resolved safely after
-        // pane replay/remount, so drop the stale row instead of guessing.
+        // Why: malformed/legacy numeric keys can't be resolved after pane replay/remount, so drop the stale row instead of guessing.
         console.warn('[WorktreeCardAgents] malformed paneKey, skipping pane focus', paneKey)
         dismissStaleAgentRowByKey(paneKey)
         return
@@ -190,13 +164,7 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
         dismissStaleAgentRowByKey(paneKey)
         return
       }
-      // Why: route through activateAndRevealWorktree so cross-repo clicks also
-      // set activeRepoId, record a nav-history entry, clear sidebar filters,
-      // reveal the card, and stamp focus recency — per the design doc rule
-      // "Every user-initiated worktree switch must route through
-      // activateAndRevealWorktree". Bypassing it (direct setActiveWorktree +
-      // markWorktreeVisited) silently skipped cross-repo activation and
-      // back/forward history for clicks from inline agent rows.
+      // Why: design-doc rule — every user-initiated worktree switch must route through activateAndRevealWorktree (cross-repo activation + nav history).
       activateAndRevealWorktree(worktreeId)
       const tabs = useAppStore.getState().tabsByWorktree[worktreeId] ?? []
       if (tabs.some((t) => t.id === tabId)) {
@@ -208,9 +176,7 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
       } else {
         const liveEntry = useAppStore.getState().agentStatusByPaneKey[paneKey]
         if (liveEntry?.worktreeId === worktreeId) {
-          // Why: orchestration worker status can be worktree-attributed before
-          // the renderer knows its tab. Keep the visible live row instead of
-          // dismissing it as stale just because it cannot be focused yet.
+          // Why: orchestration worker status can be worktree-attributed before the renderer knows its tab; keep the live row instead of dismissing as stale.
           return
         }
         dismissStaleAgentRowByKey(paneKey)
@@ -219,22 +185,17 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
     [worktreeId]
   )
   const handleActivateRetainedAgent = useCallback(() => {
-    // Why: hibernation-retained rows are passive completion evidence. Activating
-    // the worktree would resume sleeping sessions, so the row itself is inert.
+    // Why: hibernation-retained rows are passive completion evidence; activating would resume sleeping sessions, so the row is inert.
   }, [])
 
-  // Why: own one 30s tick per non-empty inline list. Cards with zero agents
-  // never mount this component (see WorktreeCardAgents), so idle worktrees
-  // don't pay any timer cost.
+  // Why: one 30s tick per non-empty inline list; zero-agent cards never mount this (see WorktreeCardAgents), so idle worktrees pay no timer cost.
   const now = useNow(30_000)
   const { rootRows: rootAgents, childrenByParentPaneKey } = useMemo(
     () => buildAgentRowLineageTree(agents),
     [agents]
   )
   const hasLineage = childrenByParentPaneKey.size > 0
-  // Why: keep disclosure state out of raw local useState so the WorktreeCard
-  // remount that fires on virtualizer recycle or a sibling child-worktrees
-  // toggle no longer resets it (which read as one section expanding the other).
+  // Why: keep disclosure state out of local useState so a WorktreeCard remount (virtualizer recycle / sibling toggle) doesn't reset it.
   const {
     collapsedLineageParents,
     compactRootListExpanded,
@@ -242,19 +203,14 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
     toggleCompactRootList
   } = useWorktreeAgentExpansionState(worktreeId)
 
-  // Why: reveal only on a genuine user collapse→expand within this mount.
-  // Seeding an already-expanded panel from the durable cache on a remount must
-  // not re-trigger the reveal scroll, or recycled cards would fight the scroll.
+  // Why: reveal only on a genuine user collapse→expand; seeding an already-expanded panel from cache on remount must not re-trigger the reveal scroll.
   const previousCompactExpandedRef = useRef(compactRootListExpanded)
   useLayoutEffect(() => {
     const wasExpanded = previousCompactExpandedRef.current
     previousCompactExpandedRef.current = compactRootListExpanded
     if (!wasExpanded && compactRootListExpanded && agentActivityDisplayMode === 'compact') {
       dispatchSuppressScrollAdjustment()
-      // Why: defer the reveal scroll out of the expand commit. Running it inline
-      // forces a synchronous sidebar layout that blocks the animation's opening
-      // frames (a visible jump); next-frame keeps the open smooth and the
-      // ScrollBehavior 'auto' still lands before the height transition finishes.
+      // Why: defer the reveal scroll to next frame; running it inline forces a sync sidebar layout that janks the opening animation.
       const handle = requestAnimationFrame(() => {
         revealCompactAgentCard(compactAgentListRootRef.current)
       })
@@ -274,10 +230,7 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
     e.stopPropagation()
   }, [])
 
-  // Why: when any root row has a disclosure chevron, root leaf siblings reserve
-  // a matching leading spacer so the state-dot column stays aligned across the
-  // card. Descendants already have the child rail indent, so adding this spacer
-  // there double-indents child agents.
+  // Why: root leaf siblings reserve a leading spacer when any root has a chevron, keeping the state-dot column aligned (descendants already indent).
   const anyRootHasChildren = rootAgents.some(
     (agent) => (childrenByParentPaneKey.get(agent.paneKey) ?? []).length > 0
   )
@@ -287,15 +240,13 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
     ancestorPaneKeys: ReadonlySet<string> = new Set()
   ): React.ReactNode => {
     if (ancestorPaneKeys.has(agent.paneKey)) {
-      // Why: orchestration metadata is external state and can be malformed.
-      // Bail out of repeated ancestors instead of recursing forever.
+      // Why: orchestration metadata is external and can be malformed; bail on repeated ancestors instead of recursing forever.
       return null
     }
     const childAgents = childrenByParentPaneKey.get(agent.paneKey) ?? []
     const hasChildAgents = childAgents.length > 0
     const isRootAgent = ancestorPaneKeys.size === 0
-    // Why: spawned child agents are actionable work, so they should be visible
-    // as soon as the parent appears; the disclosure remains available to fold noise.
+    // Why: spawned child agents are actionable work, so show them as soon as the parent appears (disclosure still folds noise).
     const expanded = !collapsedLineageParents.has(agent.paneKey)
     const sendTarget = isAgentSendTargetModeActive
       ? (sendTargetsByPaneKey.get(agent.paneKey) ?? {
@@ -314,39 +265,25 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
             agent.rowSource === 'retained' ? handleActivateRetainedAgent : handleActivateAgentTab
           }
           now={now}
-          // Why: bold an agent row until the user has visited its tab.
-          // useAutoAckViewedAgent acks automatically when the user
-          // focuses the agent's tab, which mutes the row in lockstep.
+          // Why: bold the row until the user visits its tab (useAutoAckViewedAgent auto-acks on focus, muting it).
           isUnvisited={unvisitedByPaneKey[agent.paneKey] ?? false}
-          // Why: inline rows pack tighter than a full-panel layout;
-          // 'md' reads as a second ~12px glyph users confuse with the
-          // agent identity icon right next to it. 'sm' keeps the two
-          // distinguishable at a glance.
+          // Why: inline rows are tight; 'md' reads as a second glyph users confuse with the adjacent identity icon, so use 'sm'.
           stateDotSize="sm"
-          // Why: in the per-card inline list clicking the row jumps
-          // directly to the agent, so the expand chevron is redundant.
-          // Keep the identity glyph (Claude/Gemini/…) so users can tell
-          // agents apart at a glance within a worktree.
+          // Why: clicking the row jumps straight to the agent, so the expand chevron is redundant (keep the identity glyph).
           hideExpand
-          // Why: fold orchestration children under the parent row's leading
-          // chevron so a parent reads as a tree node, not as a separate
-          // disclosure stripe below it. Variant B in the mockups.
+          // Why: fold children under the parent row's leading chevron so a parent reads as a tree node (Variant B in the mockups).
           childAgentCount={hasChildAgents ? childAgents.length : undefined}
           childAgentsExpanded={expanded}
           onToggleChildAgents={
             hasChildAgents ? () => toggleLineageParent(agent.paneKey) : undefined
           }
-          // Why: keep leaf rows aligned with parent rows in the same card —
-          // see anyRootHasChildren above.
+          // Why: keep leaf rows aligned with parent rows — see anyRootHasChildren above.
           reserveDisclosureGutter={isRootAgent && anyRootHasChildren && !hasChildAgents}
           isFocusedPane={agent.paneKey === focusedAgentPaneKey}
           sendTargetStatus={sendTarget?.status}
           sendTargetDisabledReason={sendTarget?.disabledReason}
           onSendTargetClick={isAgentSendTargetModeActive ? handleSendTargetClick : undefined}
-          // Why: the disclosure variant uses chevron + indentation to show
-          // hierarchy. The legacy L-connector / vertical-trunk decorations
-          // are pinned to a fixed left offset that doesn't match the
-          // chevron-shifted column and read as floating fragments.
+          // Why: hierarchy shows via chevron + indent; legacy L-connectors use a fixed offset that mismatches the column and reads as floating fragments.
           hideLineageConnectors
         />
         {hasChildAgents && expanded ? (
@@ -419,9 +356,7 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
 
   if (agentActivityDisplayMode === 'compact') {
     const summaryAgents = hasLineage ? rootAgents : agents
-    // Why: compact worktree cards keep multiple active agents to a single
-    // predictable status line, even when there are only two agents. In
-    // send-target mode, rows are the picker surface, so keep targets visible.
+    // Why: compact cards collapse multiple agents to one status line, except in send-target mode where rows are the picker surface.
     const shouldUseSummaryRow = summaryAgents.length > 1 && !isAgentSendTargetModeActive
     const subjectLabel = `${hasLineage ? rootAgents.length : agents.length} agents`
 
@@ -438,8 +373,7 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
         data-compact-agent-list="true"
       >
         {agents.length === 0 ? null : shouldUseSummaryRow ? (
-          // Why: the worktree card is already the surface. Expanded compact
-          // agents stay a quiet tree; only the collapsed summary reads as a pill.
+          // Why: expanded compact agents stay a quiet tree; only the collapsed summary reads as a pill.
           <div
             className={cn(
               'compact-agent-summary-panel',
@@ -469,8 +403,7 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
   }
 
   return (
-    // Why: swallow bubbling so clicks on the gutter around the agent rows
-    // don't reach WorktreeCard's activate / edit-meta handlers.
+    // Why: swallow bubbling so gutter clicks don't reach WorktreeCard's activate / edit-meta handlers.
     <div
       className={cn('flex flex-col mt-1', className)}
       onClick={stopBubble}
diff --git a/src/renderer/src/components/sidebar/WorktreeList.tsx b/src/renderer/src/components/sidebar/WorktreeList.tsx
index 137f364e084..a71753eaa5d 100644
--- a/src/renderer/src/components/sidebar/WorktreeList.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeList.tsx
@@ -312,9 +312,7 @@ type ProjectGroupDeleteDialogState = {
   removeContainedProjects: boolean
 }
 
-// How long to wait after a sortEpoch bump before actually re-sorting.
-// Prevents jarring position shifts when background events (AI starting work,
-// terminal title changes) trigger score recalculations.
+// Debounce re-sort after a sortEpoch bump so background score changes don't jar row positions.
 const SORT_SETTLE_MS = 3_000
 const USER_SCROLL_MEASUREMENT_ADJUSTMENT_SUPPRESS_MS = 500
 const EMPTY_PROJECT_GROUPS: readonly ProjectGroup[] = []
@@ -327,8 +325,7 @@ const EMPTY_RUNTIME_PANE_TITLES_BY_TAB_ID: AppState['runtimePaneTitlesByTabId']
 const EXPANDING_CARD_MEASUREMENT_ADJUSTMENT_SUPPRESS_MS = 300
 const NOOP_WORKSPACE_BOARD_DRAG_PREVIEW_CALLBACK = (): void => {}
 const WORKTREE_SIDEBAR_SCROLL_STYLE: React.CSSProperties = {
-  // Why: TanStack Virtual owns scroll correction. Native browser anchoring can
-  // fight virtual row measurement/remounts and produce visible jumps.
+  // Why: TanStack Virtual owns scroll correction; native overflow anchoring fights it and causes jumps.
   overflowAnchor: 'none'
 }
 
@@ -367,8 +364,7 @@ function isEditableTarget(target: EventTarget | null): boolean {
     return false
   }
 
-  // xterm uses a hidden textarea for terminal input. Treating it like a normal
-  // text field would make the sidebar's app-level worktree shortcuts unreachable.
+  // xterm's hidden input textarea isn't a real text field; treating it as one would block sidebar shortcuts.
   if (target.classList.contains('xterm-helper-textarea')) {
     return false
   }
@@ -400,8 +396,7 @@ function handleRepoHeaderActionPointerDown(event: React.PointerEvent<HTMLElement
 function handleRepoHeaderCollapseAffordancePointerDown(
   event: React.PointerEvent<HTMLElement>
 ): void {
-  // Why: repo-header drag arms from the row press surface; keep collapse
-  // clicks on the hover chevron from promoting into a drag session.
+  // Why: keep collapse-chevron clicks from arming the repo-header row drag.
   event.stopPropagation()
 }
 
@@ -666,10 +661,7 @@ type VirtualizedWorktreeViewportProps = {
   worktreeLineageById: Record<string, WorktreeLineage>
   workspaceLineageByChildKey: Record<string, WorkspaceLineage>
   repoOrder: Map<string, number>
-  // The full canonical state.repos id ordering — the drag controller commits
-  // permutations of this list, even when some repos aren't currently visible
-  // (filtered out / collapsed-only). Visible-only ids would silently drop the
-  // hidden repos on reorder.
+  // Full canonical repo-id order; must include hidden repos or a reorder silently drops them.
   allRepoIds: string[]
   onReorderHostSections: (orderedHostIds: ExecutionHostId[]) => void
   onHostDragActiveChange: (active: boolean) => void
@@ -708,9 +700,7 @@ type VirtualizedWorktreeViewportProps = {
     draggedIds: readonly string[]
     dropIndex: number
   }) => void
-  // Why: broad grouping changes still remount the viewport, while add/delete
-  // stays mounted for row-key anchoring and layout animation. These refs bridge
-  // both paths so the virtualizer never falls back to scrollTop 0.
+  // Why: grouping remounts the viewport, add/delete stays mounted; bridge both so the virtualizer never resets to scrollTop 0.
   scrollOffsetRef: React.MutableRefObject<number>
   scrollAnchorRef: React.MutableRefObject<VirtualizedScrollAnchor>
 }
@@ -749,8 +739,7 @@ function HostHeaderHealthIcon({
 }: {
   health: HostHeaderRow['health']
 }): React.JSX.Element | null {
-  // Why: healthy is the default state — indicating it adds noise. Only states
-  // needing active attention get a separate mark.
+  // Why: only surface states needing attention; healthy is the silent default.
   if (health === 'connecting') {
     return <Loader2 className="size-3 shrink-0 animate-spin text-muted-foreground" />
   }
@@ -761,16 +750,14 @@ function HostHeaderHealthIcon({
 }
 
 function getHostHeaderDetail(row: HostHeaderRow): { text: string; isWarning: boolean } | null {
-  // Why: a blocked compatibility verdict gets a compact warning treatment so one
-  // skewed host stands out without altering how its siblings render.
+  // Why: a blocked compatibility verdict earns a compact warning so the host stands out.
   if (row.health === 'blocked') {
     return {
       text: translate('auto.components.sidebar.WorktreeList.7a8b9c0d1e', 'Update required'),
       isWarning: true
     }
   }
-  // Why: auth-expired SSH hosts must say so in words — the plan requires a clear
-  // auth-needed status, and the health icon alone doesn't explain the fix.
+  // Why: auth-failed needs a worded status; the health icon alone doesn't tell the user to re-auth.
   if (row.connectionStatus === 'auth-failed') {
     return {
       text: translate(
@@ -786,8 +773,7 @@ function getHostHeaderDetail(row: HostHeaderRow): { text: string; isWarning: boo
       isWarning: false
     }
   }
-  // Why: the transport suffix only earns space on remote hosts; repeating
-  // "This computer" under the local host label is noise.
+  // Why: show the transport detail only for remote hosts; it's noise under the local label.
   if (row.kind !== 'local') {
     return { text: row.detail, isWarning: false }
   }
@@ -810,9 +796,7 @@ function HostSectionHeader({
   const detail = getHostHeaderDetail(row)
   return (
     <div className="px-2 pt-1">
-      {/* Why: hosts are machines, not just groups — the outlined card with a
-          server glyph keeps that distinction visible. Status stays quiet: a
-          mark renders only when the host needs attention. */}
+      {/* Why: outlined card + server glyph marks hosts as machines, not mere groups. */}
       <div
         role="button"
         tabIndex={0}
@@ -843,8 +827,7 @@ function HostSectionHeader({
           <Server className="size-3.5 shrink-0 text-muted-foreground" />
         )}
         <HostHeaderHealthIcon health={row.health} />
-        {/* Why: the badge hugs the label like repo headers do — anchoring it
-            right would leave it floating beside the hover-only controls. */}
+        {/* Why: badge hugs the label (like repo headers) instead of floating by the hover controls. */}
         <div className="flex min-w-0 flex-1 items-baseline gap-1.5">
           <span
             className={cn(
@@ -1037,8 +1020,7 @@ function shouldPreferSidebarStatusDropTarget(args: {
     return false
   }
   const sourceStatus = getWorkspaceStatusFromGroupKey(args.sourceGroupKey, args.workspaceStatuses)
-  // Why: source-group edge zones overlap adjacent status sections; the visible
-  // section under the pointer must win so the guide and committed drop agree.
+  // Why: overlapping edge zones — the section under the pointer must win so guide and drop agree.
   return sourceStatus !== null && args.target.status !== sourceStatus
 }
 
@@ -1164,8 +1146,7 @@ export function getPinnedWorktreeRevealCollapsedGroupKeys({
     return []
   }
   const keys: string[] = []
-  // Why: the reveal effect opens the owning host first; returning it here would
-  // toggle the same host closed again while React state is still stale.
+  // Why: the reveal effect already opens this host; re-returning it would toggle it back closed.
   if (collapsedGroups.has(PINNED_GROUP_KEY)) {
     keys.push(PINNED_GROUP_KEY)
   }
@@ -1445,8 +1426,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     (rowKey: string) => {
       clearRevealHighlightTimeout()
       clearRevealHighlightFrame()
-      // Why: remove before add restarts the CSS glow when the user repeatedly
-      // asks to reveal the same active workspace.
+      // Why: clear before set restarts the CSS glow when revealing the same row repeatedly.
       setHighlightedRevealRowKey(null)
       revealHighlightFrameIdRef.current = window.requestAnimationFrame(() => {
         revealHighlightFrameIdRef.current = null
@@ -1495,8 +1475,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     () =>
       installWorktreeVisibleRefreshVisibilityListener(() => {
         if (document.visibilityState !== 'visible') {
-          // Why: the visible row identity can be unchanged after returning
-          // from a hidden window; reset the key so visible PR/CI rows catch up.
+          // Why: row identity may be unchanged after a hidden window; reset the key so PR/CI rows refresh.
           lastVisibleRefreshKeyRef.current = '__document_hidden__'
           return
         }
@@ -1505,12 +1484,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     []
   )
 
-  // Why: a project reorder relocates a whole group (header + its worktree
-  // rows) but leaves totalSize unchanged, so the current scrollTop is already
-  // the visually-stable position. Flag direct scroll input (same refs as
-  // markDirectScrollInput, defined later) so the scroll-anchor restore effect
-  // skips re-pinning the old top row — otherwise it chases the moved row and
-  // yanks the viewport, which is the "jumpy" drop.
+  // Why: reorder keeps scrollTop stable; flag direct scroll input so anchor-restore won't chase the moved row (jumpy drop).
   const commitRepoReorder = useCallback(
     (orderedIds: string[]) => {
       const suppressUntil =
@@ -1733,8 +1707,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     },
     [updateProjectGroup]
   )
-  // Drag is only meaningful when repo headers are using manual order. The
-  // controller is still constructed for hook order stability when inert.
+  // Drag applies only in manual order; still construct the controller inert for stable hook order.
   const repoDrag = useRepoHeaderDrag({
     orderedRepoIds: allRepoIds,
     sidebarRepoHeaderIdsByBucket,
@@ -1923,8 +1896,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     (request: Parameters<typeof fetchFolderWorkspacePathStatus>[0]) => {
       const options = getFolderPathStatusRouteOptions(request)
       const cacheKey = getFolderWorkspacePathStatusCacheKey(request, options)
-      // Why: expired negative statuses should not keep disabling folder
-      // workspaces while a fresh status request is in flight.
+      // Why: don't let an expired negative status keep folder workspaces disabled while a refresh is in flight.
       void folderWorkspacePathStatuses[cacheKey]
       void folderPathStatusCacheExpiryTick
       return getFreshFolderWorkspacePathStatus(request, options)
@@ -1974,10 +1946,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
       if (!isCurrentVirtualRowElement(element)) {
         const index = getVirtualRowIndex(element)
         const measured = instance.getVirtualItems().find((item) => item.index === index)
-        // Why: TanStack's ResizeObserver can deliver a stale row after a
-        // collapse/delete/remount. Returning the current item size makes that
-        // observation a no-op instead of writing the stale element's height
-        // into whichever row now owns the old data-index.
+        // Why: a stale ResizeObserver row after remount would write a wrong height; return current size to no-op it.
         return (
           measured?.size ??
           estimateRenderRowSize(
@@ -2018,8 +1987,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     () => window.performance.now() < directScrollInputUntilRef.current,
     []
   )
-  // Why: programmatic scrolls should keep measurement correction quiet, but
-  // only direct input should block anchor restoration retries.
+  // Why: programmatic scrolls keep measurement correction quiet, but only direct input blocks anchor-restore retries.
   const shouldSkipScrollAnchorRestore = useCallback(
     () => window.performance.now() < directScrollInputUntilRef.current,
     []
@@ -2036,9 +2004,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         activeStickyHeaderIndexRef.current
       ),
     measureElement: measureCurrentVirtualRowElement,
-    // Why: TanStack memoizes range extraction by function identity. Header
-    // indexes must be deps so grouping/filtering cannot leave stale sticky
-    // slots rendering ordinary worktree rows.
+    // Why: TanStack memoizes rangeExtractor by identity; header indexes must be deps or sticky slots go stale.
     rangeExtractor: useCallback(
       (range: Range) => {
         stickyRangeStartIndexRef.current = range.startIndex
@@ -2052,29 +2018,17 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     ),
     overscan: 10,
     gap: 6,
-    // Why: the active sticky group header is rendered inside the virtual list,
-    // so TanStack's scroll math needs the same top inset as the exact DOM reveal.
+    // Why: the sticky group header lives inside the virtual list, so scroll math needs the same top inset as the DOM reveal.
     scrollPaddingStart: WORKTREE_SIDEBAR_REVEAL_TOP_INSET,
     isScrollingResetDelay: USER_SCROLL_MEASUREMENT_ADJUSTMENT_SUPPRESS_MS,
-    // Why: the sidebar rows are rich cards. Flushing their React render inside
-    // TanStack's native scroll listener can make wheel input wait on card work;
-    // overscan gives the async render enough runway to stay visually filled.
+    // Why: sync-flushing rich card renders in the scroll listener stalls wheel input; async + overscan keeps rows filled.
     useFlushSync: false,
-    // Why: tells the virtualizer to start its internal scrollOffset at the
-    // ref value rather than 0, so the first getVirtualItems() call after
-    // remount picks the correct window of rows. The sibling useLayoutEffect
-    // mirrors this onto the actual scrollElement.scrollTop so the DOM and
-    // virtualizer stay aligned across remounts.
+    // Why: seed scrollOffset from the ref (not 0) so the first getVirtualItems() after remount picks the right rows.
     initialOffset: () => scrollOffsetRef.current,
     getItemKey: getVirtualItemKey
   })
-  // Why: rich worktree cards remeasure while the user wheels through them.
-  // TanStack's default correction writes scrollTop in that path, which feels
-  // like rubber-banding. Structural mutations still use our explicit anchor
-  // restore after direct scroll input has settled.
-  // TODO(scroll-origin-migration): this wall-clock suppression misclassifies
-  // under main-thread jank; migrate to programmaticScrollMarks + restoreSignal
-  // (see CombinedDiffViewer) once that wiring is validated for the sidebar.
+  // Why: TanStack's default correction writes scrollTop while cards remeasure mid-wheel, which feels like rubber-banding.
+  // TODO(scroll-origin-migration): wall-clock suppression misclassifies under jank; migrate to programmaticScrollMarks + restoreSignal (see CombinedDiffViewer).
   virtualizer.shouldAdjustScrollPositionOnItemSizeChange = (_item, _delta, instance) =>
     shouldAdjustWorktreeSidebarMeasuredRowScroll({
       isScrolling: instance.isScrolling,
@@ -2084,8 +2038,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
 
   useEffect(() => {
     const handleSuppress = () => {
-      // Why: compact agent expansion changes measured row height; let the row
-      // grow in place instead of letting TanStack compensate scrollTop.
+      // Why: let an expanding agent row grow in place instead of TanStack compensating scrollTop.
       suppressMeasurementAdjustmentUntilRef.current =
         window.performance.now() + EXPANDING_CARD_MEASUREMENT_ADJUSTMENT_SUPPRESS_MS
     }
@@ -2236,8 +2189,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         }
 
         if (targetRow?.type !== 'lineage-group') {
-          // Why: virtual row indexing can leave the card edge slightly clipped;
-          // stage it into the mounted window, then retry the exact DOM reveal.
+          // Why: virtual indexing can leave the card edge clipped; stage it into the window, then retry the exact DOM reveal.
           virtualizer.scrollToIndex(targetIndex, {
             align: 'auto',
             behavior: 'auto'
@@ -2246,10 +2198,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
           return
         }
 
-        // Why: for grouped lineage rows the virtual row is only a staging
-        // target. Jump it into the mounted window first, then retry the exact
-        // card reveal instead of clearing while a smooth virtual scroll is
-        // still in flight.
+        // Why: for lineage groups the virtual row is only a staging target; jump into the window, then retry the exact reveal.
         virtualizer.scrollToIndex(targetIndex, {
           align: 'auto',
           behavior: 'auto'
@@ -2463,10 +2412,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
       activeRowKeys: activeRenderRowKeys,
       virtualizer
     })
-    // Why: after delete/collapse, TanStack may briefly retain the removed row's
-    // cached element. Measuring that disconnected node reports 0px and corrupts
-    // the next row's slot, so measure only elements whose DOM key still matches
-    // the row currently rendered at that index.
+    // Why: a stale retained element after delete/collapse measures 0px and corrupts the next slot; measure only key-matched rows.
     measureMountedRows()
     const frameId = window.requestAnimationFrame(measureMountedRows)
     return () => window.cancelAnimationFrame(frameId)
@@ -2506,11 +2452,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
 
   const navigateWorktree = useCallback(
     (direction: 'up' | 'down') => {
-      // Why: derive the cycling order from an all-expanded layout, not the
-      // rendered rows. Otherwise Cmd+Shift+Up/Down would skip any worktree
-      // hidden in a collapsed group — in particular it couldn't cross the
-      // Pinned/All boundary when either section is collapsed. Reveal will
-      // uncollapse the target section (see pendingRevealWorktree effect).
+      // Why: cycle over an all-expanded layout so navigation doesn't skip worktrees in collapsed groups; reveal uncollapses the target.
       const allWorktreeRows = buildRows(
         groupBy,
         worktrees,
@@ -2558,8 +2500,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
       }
 
       const nextWorktreeId = worktreeRows[nextIndex].worktree.id
-      // Why: keyboard cycling between worktrees is still real navigation, so
-      // it must flow through the same activation helper that records history.
+      // Why: keyboard cycling is real navigation; route through the activation helper that records history.
       activateAndRevealWorktree(nextWorktreeId)
 
       const rowIndex = findPreferredRenderRowIndexForWorktree(
@@ -2708,8 +2649,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
   const setScrollRootRef = useCallback(
     (node: HTMLDivElement | null) => {
       if (node === null && scrollRef.current !== null) {
-        // Why: sidebar drag previews, autoscroll frames, and reveal row
-        // snapshots are tied to the scroll root; clear them before it disappears.
+        // Why: drag previews, autoscroll frames, and reveal snapshots are tied to the scroll root; clear them before it unmounts.
         cancelPendingRevealFrames()
         clearRevealHighlightFrame()
         clearRevealHighlightTimeout()
@@ -2791,8 +2731,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
       if (ids.length === 0) {
         return
       }
-      // Why: dropping a nested card onto a reorder line is the escape hatch
-      // from accidental nesting, so clear only the directly dragged children.
+      // Why: dropping a nested card on a reorder line is the un-nest escape hatch; clear only the dragged children.
       void Promise.all(ids.map((id) => updateWorktreeLineage(id, { noParent: true }))).catch(
         (err) => {
           console.error('Failed to unnest workspace:', err)
@@ -2828,9 +2767,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
       clearWorktreeDrag()
       return
     }
-    // Why: reveal the companion board preview the moment a card drag begins so the
-    // user sees the drop target on the right and can choose whether to aim for it,
-    // rather than discovering it only after dragging into the sidebar edge.
+    // Why: show the board preview as soon as a card drag begins so the drop target is visible up front, not only at the sidebar edge.
     if (
       !drag.workspaceBoardDragPreviewRequested &&
       !workspaceBoardOpen &&
@@ -3758,8 +3695,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
       return
     }
     const currentWorktree = currentWorktreeId ? (worktreeMap.get(currentWorktreeId) ?? null) : null
-    // Why: this visible reporter feeds the GitHub coordinator; GitLab-only MR
-    // panels refresh through hosted-review paths instead.
+    // Why: this reporter feeds the GitHub coordinator; GitLab-only MR panels refresh via hosted-review paths.
     const sidebarWorktreeHasGitHubReview =
       currentWorktree !== null &&
       ((currentWorktree.linkedGitLabMR ?? null) === null ||
@@ -3912,8 +3848,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         clearWorktreeDrag()
         return
       }
-      // Match the status-drop scope to the drag-preview scope (#9083): with a live session use its
-      // precomputed expanded set; the session-less foreign-origin case expands the dataTransfer ids live.
+      // Match status-drop scope to drag-preview scope (#9083): session uses its expanded set, else expand dataTransfer ids live.
       onMoveWorktreesToStatus(
         session ? session.reorderDraggedIds : getReorderDraggedIds(worktreeIds),
         status
@@ -3981,9 +3916,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         clearWorktreeDrag()
         return
       }
-      // Why: status-group drops are captured before React sees them. When the
-      // pointer is still inside the source group, this is a reorder rather than
-      // a status move, so commit here and stop the status-drop capture handler.
+      // Why: pointer still inside the source group means reorder, not status move; commit here and stop the capture handler.
       event.preventDefault()
       event.stopPropagation()
       onReorderWorktrees({
@@ -4041,9 +3974,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     return () => document.removeEventListener('visibilitychange', handleVisibilityChange)
   }, [clearWorktreeDrag])
 
-  // Why: this session-less capture-phase committer is the primary native-drop path in packaged
-  // Electron. Expand at this call site (not in the shared hook, which WorkspaceKanbanDrawer uses for
-  // its flat board) so a dropped parent carries its visible lineage children (#9083).
+  // Why: expand here (not the shared hook, used by the flat board) so a dropped parent carries its lineage children (#9083).
   const moveWorktreesToStatusForDocumentDrop = useCallback(
     (ids: readonly string[], status: WorkspaceStatus) =>
       onMoveWorktreesToStatus(getReorderDraggedIds(ids), status),
@@ -4078,9 +4009,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         aria-multiselectable="true"
         aria-activedescendant={activeDescendantId}
         onKeyDown={handleContainerKeyDown}
-        // Why: trackpad momentum can continue as sparse scroll events after the
-        // original wheel/touch event stream quiets down. Keep measurement-based
-        // scroll correction suppressed until the viewport itself has stopped.
+        // Why: trackpad momentum fires sparse scroll events after the input stream quiets; suppress correction until the viewport stops.
         onScroll={handleScroll}
         onPointerDown={handleScrollPointerDown}
         onTouchMove={markDirectScrollInput}
@@ -4119,8 +4048,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
             }
 
             if (row.type === 'host-header') {
-              // Why: the host card is the outer hierarchy tier — it pins above
-              // group headers (z-30 vs z-20) and stays put while they hand off.
+              // Why: the host card is the outer tier; it pins above group headers (z-30 vs z-20) and stays put as they hand off.
               const isActiveStickyHost = activeStickyHostIndexRef.current === vItem.index
               const hasHeaderTopSpacing = shouldUseHeaderTopSpacing({
                 rows: renderRows,
@@ -4166,8 +4094,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
 
             if (row.type === 'header') {
               const isActiveStickyHeader = activeStickyHeaderIndexRef.current === vItem.index
-              // Why: when a host card is pinned, the group tier pins flush
-              // beneath it instead of at the viewport top.
+              // Why: when a host card is pinned, the group tier pins flush beneath it, not at the viewport top.
               const stickyTopClass =
                 activeStickyHostIndexRef.current !== null ? 'top-[35px]' : '-top-px'
               const hasHeaderTopSpacing = shouldUseHeaderTopSpacing({
@@ -4255,13 +4182,11 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
                   projectGroupPathStatus.reason === 'ambiguous-connection')
               const projectGroupDepth = row.projectGroupDepth ?? 0
               const isHeaderCollapsed = collapsedGroups.has(row.key)
-              // Why: repo/project and status headers use the same compact
-              // section chrome; flat "All" stays a simple label.
+              // Why: repo/project and status headers share compact section chrome; flat "All" stays a simple label.
               const showHeaderCollapseAffordance =
                 row.count > 0 &&
                 (isRepoHeader || isProjectGroupHeader || headerWorkspaceStatus !== null)
-              // Why: non-project section headers like "All" are labels for the
-              // flat list, so they should not reserve project hierarchy indent.
+              // Why: non-project headers like "All" are flat-list labels; don't reserve project hierarchy indent.
               const headerPaddingLeft =
                 isRepoHeader || isProjectGroupHeader
                   ? getProjectGroupHeaderPaddingLeft(projectGroupDepth)
@@ -4279,11 +4204,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
                   ref={measureVirtualRowElement}
                   className={cn(
                     'left-0 right-0',
-                    // Why: the inter-group spacer only applies while the header
-                    // scrolls in normally; the pinned header drops it to sit
-                    // flush at the top. The swap fires when the header row
-                    // reaches the top (see getActiveStickyHeaderIndexForScroll),
-                    // so the previous repo no longer stays pinned over it.
+                    // Why: drop the inter-group spacer once the header pins so it sits flush at top (see getActiveStickyHeaderIndexForScroll).
                     hasHeaderTopSpacing && !isActiveStickyHeader && 'pt-1',
                     isActiveStickyHeader
                       ? cn('sticky z-20 bg-worktree-sidebar', stickyTopClass)
@@ -4467,9 +4388,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
                             align="end"
                             side="bottom"
                             sideOffset={6}
-                            // Why: Radix portals preserve React bubbling through
-                            // the project header. Keep menu interactions from
-                            // arming row drag/collapse handlers behind it.
+                            // Why: Radix portals keep React bubbling through the project header; block menu events from arming row drag/collapse.
                             onPointerDown={stopRepoHeaderMenuEvent}
                             onMouseDown={stopRepoHeaderMenuEvent}
                             onPointerUp={stopRepoHeaderMenuEvent}
@@ -4596,9 +4515,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
                             align="end"
                             side="bottom"
                             sideOffset={6}
-                            // Why: Radix portals preserve React bubbling through
-                            // the project header. Keep menu interactions from
-                            // arming row drag/collapse handlers behind it.
+                            // Why: Radix portals keep React bubbling through the project header; block menu events from arming row drag/collapse.
                             onPointerDown={stopRepoHeaderMenuEvent}
                             onMouseDown={stopRepoHeaderMenuEvent}
                             onPointerUp={stopRepoHeaderMenuEvent}
@@ -4804,8 +4721,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
               const isFolderBackedRepoChild =
                 groupBy === 'repo' &&
                 Boolean(projectGroupId && folderBackedProjectGroupIds.has(projectGroupId))
-              // Why: experimental in-card lineage inherits the parent surface;
-              // legacy cards keep the old depth-based nested row geometry.
+              // Why: experimental in-card lineage inherits the parent surface; legacy cards keep depth-based nested geometry.
               const paddingDepth = nested ? Math.max(0, itemRow.depth - 1) : itemRow.depth
               const getCardContentIndent = (lineageDepth: number): number =>
                 isFolderBackedRepoChild
@@ -4826,8 +4742,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
                     lineageDepth: itemRow.depth
                   })
                 : null
-              // Why: grouped rows inherit their project/group header depth,
-              // while the card surface still spans the full hit/background row.
+              // Why: grouped rows inherit their header depth, but the card surface still spans the full row.
               const paddingLeft =
                 nested && groupBy !== 'none'
                   ? getWorktreeCardContentIndent({
@@ -4882,19 +4797,16 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
                   data-worktree-drag-group-key={worktreeDragGroupKey}
                   data-worktree-drag-group-index={worktreeDragGroupIndex}
                   className={cn(
-                    // Why: avoid transitioning 'transform' to prevent browser-side lag and flashing
-                    // when TanStack Virtual programmatically repositions adjacent rows.
+                    // Why: don't transition 'transform' — it lags/flashes when TanStack Virtual repositions adjacent rows.
                     'relative transition-[opacity,filter] duration-150 ease-out',
                     worktreeDragState.draggingWorktreeId === itemRow.worktree.id &&
-                      // Why: the fixed drag preview is the visible affordance; leaving the
-                      // source row translucent lets it bleed through sticky headers/footers.
+                      // Why: the fixed drag preview is the affordance; a translucent source row would bleed through sticky headers/footers.
                       'pointer-events-none opacity-0'
                   )}
                   data-scroll-reveal-highlight={
                     highlightedRevealRowKey === itemRow.rowKey ? 'true' : undefined
                   }
-                  // Why: nested child cards live inside the parent's clickable
-                  // card body; bubbling would activate/edit the parent too.
+                  // Why: nested child cards live inside the parent's clickable body; bubbling would activate/edit the parent too.
                   onClick={nested ? stopNestedWorktreeCardBubble : undefined}
                   onClickCapture={handleWorktreeRowClickCapture}
                   onDoubleClick={nested ? stopNestedWorktreeCardBubble : undefined}
@@ -4914,8 +4826,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
                     repo={itemRow.repo}
                     isActive={isActiveWorktree}
                     isCurrentWorktree={currentWorktreeId === itemRow.worktree.id}
-                    // Why: a child-active parent should look active without
-                    // running active-card side effects such as SSH reconnect UI.
+                    // Why: a child-active parent should look active without the active-card side effects (e.g. SSH reconnect UI).
                     isActiveSurface={forceActiveSurface || isActiveWorktree}
                     activeSurfaceVariant={
                       isActiveWorktree && !forceActiveSurface ? activeSurfaceVariant : 'primary'
@@ -4935,8 +4846,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
                     onCardDragStart={handleWorktreeCardDragStart}
                     onCardDragEnd={clearWorktreeDrag}
                     hideRepoBadge={groupBy === 'repo'}
-                    // Why: pinned worktrees mix repos in one section; only that
-                    // section needs the leading repo identity chip.
+                    // Why: pinned worktrees mix repos in one section, so only it needs the leading repo identity chip.
                     hostContextLabel={itemRow.hostContextLabel}
                     inPinnedSection={isPinnedOverlayRow}
                     renameRowKey={itemRow.rowKey}
@@ -5303,8 +5213,7 @@ const WorktreeList = React.memo(function WorktreeList({
   const clearPendingRevealWorktreeId = useAppStore((s) => s.clearPendingRevealWorktreeId)
   const clearPendingRevealSidebarRow = useAppStore((s) => s.clearPendingRevealSidebarRow)
   const agentSendPopoverTargetMode = useAppStore((s) => s.agentSendPopoverTargetMode)
-  // Why: agent-send eligibility only matters while the picker is open. When it
-  // is closed, avoid subscribing WorktreeList to wake-time terminal layout churn.
+  // Why: eligibility only matters while the picker is open; when closed, don't subscribe to wake-time layout churn.
   const agentTargetStatusByPaneKey = useAppStore((s) =>
     agentSendPopoverTargetMode ? s.agentStatusByPaneKey : EMPTY_AGENT_STATUS_BY_PANE_KEY
   )
@@ -5342,8 +5251,7 @@ const WorktreeList = React.memo(function WorktreeList({
       ? agentSendPopoverTargetMode.worktreeId
       : null
   }, [
-    // Why: eligibility can flip when the stale-boundary scheduler bumps this
-    // epoch without replacing the status map.
+    // Why: eligibility can flip when the stale-boundary scheduler bumps this epoch without replacing the status map.
     agentTargetStatusEpoch,
     agentSendPopoverTargetMode,
     agentTargetStatusByPaneKey,
@@ -5377,9 +5285,7 @@ const WorktreeList = React.memo(function WorktreeList({
 
   const sortEpoch = useAppStore((s) => s.sortEpoch)
 
-  // Count of non-archived worktrees — used to detect structural changes
-  // (add/remove) vs. pure reorders (score shifts) so the debounce below
-  // can apply immediately when the list shape changes.
+  // Non-archived count — detects structural changes (add/remove) so the debounce below can apply immediately.
   const worktreeCount = useMemo(() => {
     let count = 0
     for (const worktree of allWorktrees) {
@@ -5390,16 +5296,8 @@ const WorktreeList = React.memo(function WorktreeList({
     return count
   }, [allWorktrees])
 
-  // Why debounce: sort scores include a time-decaying activity component.
-  // Recomputing instantly on every sortEpoch bump (e.g. AI starting work,
-  // terminal title changes) recalculates all scores with a fresh `now`,
-  // causing worktrees to visibly jump even when the triggering event isn't
-  // about the worktree the user is looking at.  Settling for a few seconds
-  // lets rapid-fire events coalesce and prevents mid-interaction surprises.
-  //
-  // However, structural changes (worktree created or removed) must apply
-  // immediately — a new worktree should appear at its correct sorted
-  // position, not at the bottom for 3 seconds.
+  // Why debounce: scores are time-decaying, so recomputing on every sortEpoch bump makes worktrees jump; settle to coalesce.
+  // Structural changes (add/remove) bypass the debounce so a new worktree appears at its sorted position immediately.
   const [debouncedSortEpoch, setDebouncedSortEpoch] = useState(sortEpoch)
   const prevWorktreeCountRef = useRef(worktreeCount)
   useEffect(() => {
@@ -5407,12 +5305,10 @@ const WorktreeList = React.memo(function WorktreeList({
       return
     }
 
-    // Detect add/remove by comparing worktree count.
     const structuralChange = worktreeCount !== prevWorktreeCountRef.current
     prevWorktreeCountRef.current = worktreeCount
 
-    // Why: manual drag/drop is direct manipulation; delaying that repaint by
-    // the smart-sort settle window makes a successful drop look broken.
+    // Why: manual drag/drop is direct manipulation; the settle-window delay would make a successful drop look broken.
     if (structuralChange || sortBy === 'manual') {
       setDebouncedSortEpoch(sortEpoch)
       return
@@ -5422,26 +5318,13 @@ const WorktreeList = React.memo(function WorktreeList({
     return () => clearTimeout(timer)
   }, [sortEpoch, debouncedSortEpoch, worktreeCount, sortBy])
 
-  // Why a latching ref: persisted order is only a cold-start fallback. A live
-  // PTY or fresh attributed headless agent makes Smart authoritative, and it
-  // must stay authoritative after that activity ends.
+  // Why a latching ref: a live signal makes Smart authoritative for the session, even after that activity ends.
   const sessionHasHadLiveSmartSignal = useRef(false)
 
   // ── Stable sort order ──────────────────────────────────────────
-  // The sort order is cached and only recomputed when `sortEpoch` changes
-  // (worktree add/remove, terminal activity, backend refresh, etc.).
-  // Why: explicit selection also triggers local side-effects like clearing
-  // `isUnread` and force-refreshing the branch PR cache. Those updates are
-  // useful for card contents, but they must not participate in ordering or a
-  // sequence of clicks will keep reshuffling the sidebar underneath the user.
-  //
-  // Why useMemo instead of useEffect: the sort order must be computed
-  // synchronously *before* the worktrees memo reads it, otherwise the
-  // first render (and epoch bumps) would use stale/empty data from the ref.
-  // Why a ref alongside the memo: telemetry effects need access to the most
-  // recently computed attention map without forcing every render to read it
-  // from store state again. The ref captures whatever the memo last produced
-  // for the smart branch.
+  // Why sortEpoch (not selection): selection side-effects (clearing isUnread, PR-cache refresh) must not reorder the sidebar under the user.
+  // Why useMemo not useEffect: order must be computed synchronously before the worktrees memo reads it.
+  // Why a ref alongside the memo: telemetry effects need the last attention map without re-reading store state.
   const lastAttentionByWorktreeRef = useRef<Map<string, WorktreeAttention> | null>(null)
 
   const sortedIds = useMemo(() => {
@@ -5451,17 +5334,9 @@ const WorktreeList = React.memo(function WorktreeList({
     )
     const now = Date.now()
 
-    // Why cold-start detection: smart-class resolution depends on the
-    // agent-status snapshot (agentStatusByPaneKey) hydrating from the hook
-    // server, which lands asynchronously after launch. Running the warm
-    // comparator before that arrives would collapse every worktree to Class 4
-    // and shuffle the sidebar against the comparator's tiebreakers. Restore
-    // the pre-shutdown order from the persisted sortOrder snapshot until a
-    // live PTY or attributed headless agent appears, then use live classes.
+    // Why cold-start detection: agent-status hydrates async, so the warm comparator would collapse all to Class 4; keep the persisted order until a live signal appears.
     if (sortBy === 'smart' && !sessionHasHadLiveSmartSignal.current) {
-      // Why: `tabHasLivePty` (over `ptyIdsByTabId`) is the source of truth for
-      // liveness — slept terminals retain `tab.ptyId` as a wake hint, so reading
-      // it directly would falsely keep cold-start ordering off after restart.
+      // Why tabHasLivePty over tab.ptyId: slept terminals keep tab.ptyId as a wake hint, so it'd falsely keep cold-start ordering off.
       const hasAnyLivePty = Object.values(state.tabsByWorktree)
         .flat()
         .some((tab) => tabHasLivePty(state.ptyIdsByTabId, tab.id))
@@ -5480,10 +5355,7 @@ const WorktreeList = React.memo(function WorktreeList({
     }
 
     const currentTabs = state.tabsByWorktree
-    // Why precompute: this is the hot sidebar sort. Array.sort invokes the
-    // comparator O(N log N) times. Build the per-worktree attention map ONCE
-    // (O(E + N×T×H) where H = stateHistory length, bounded at 20) so the
-    // comparator does O(1) map lookups instead of re-resolving per comparison.
+    // Why precompute: hot sort — build the attention map once so the O(N log N) comparator does O(1) lookups.
     const attentionByWorktree =
       sortBy === 'smart'
         ? buildAttentionByWorktree(
@@ -5500,31 +5372,19 @@ const WorktreeList = React.memo(function WorktreeList({
     lastAttentionByWorktreeRef.current = sortBy === 'smart' ? attentionByWorktree : null
     nonArchivedWorktrees.sort(buildWorktreeComparator(sortBy, repoMap, now, attentionByWorktree))
     return nonArchivedWorktrees.map((w) => w.id)
-    // debouncedSortEpoch is an intentional trigger: it's not read inside the
-    // memo, but its change signals that the sort order should be recomputed.
-    // The debounce prevents jarring mid-interaction position shifts.
+    // debouncedSortEpoch is an intentional trigger not read in the memo; its change (debounced) signals a recompute.
     // oxlint-disable-next-line react-hooks/exhaustive-deps
   }, [debouncedSortEpoch, repoMap, sortBy])
 
-  // Why a ref of prior class per worktree: smart_sort_class_1_promotion must
-  // fire only on transitions INTO Class 1, not on every recompute that keeps
-  // a worktree there. Suppressing repeats with a ref keeps the event signal
-  // clean without growing component state.
+  // Why a ref of prior class: fire class_1_promotion only on transitions into Class 1, not every recompute that stays there.
   const prevClassByWorktreeIdRef = useRef<Map<string, SmartClass>>(new Map())
-  // Why gate the first observation: when Smart mode first activates (app
-  // start, or toggling away from Smart and back), the prev-class map is
-  // empty, so every existing Class-1 worktree would look like a fresh
-  // promotion and produce a burst of spurious events. Treat the first
-  // observation as a silent baseline — populate the map but don't fire.
+  // Why gate the first observation: an empty prev-class map makes every existing Class-1 worktree look freshly promoted; treat the first pass as a silent baseline.
   const hasObservedSmartOnceRef = useRef<boolean>(false)
 
   useEffect(() => {
     const attention = lastAttentionByWorktreeRef.current
     if (sortBy !== 'smart' || !attention) {
-      // Why reset: when the user switches off Smart, drop the prior-class map
-      // so re-entering Smart doesn't fire stale promotion events for worktrees
-      // whose state has since changed. Reset the first-observation gate too
-      // so the next Smart-mode session starts with a fresh silent baseline.
+      // Why reset: leaving Smart drops the prior-class map (and first-observation gate) so re-entry doesn't fire stale promotions.
       prevClassByWorktreeIdRef.current = new Map()
       hasObservedSmartOnceRef.current = false
       return
@@ -5542,9 +5402,7 @@ const WorktreeList = React.memo(function WorktreeList({
     hasObservedSmartOnceRef.current = true
   }, [sortBy, sortedIds])
 
-  // Why retry on sortedIds changes: Smart can become active before attention
-  // hydrates. Fire once when class data exists, then stay quiet until the user
-  // leaves Smart so this never becomes a telemetry heartbeat.
+  // Why retry on sortedIds: Smart may activate before attention hydrates; fire once, then stay quiet until the user leaves Smart.
   const hasTrackedSmartDistributionRef = useRef(false)
   useEffect(() => {
     if (sortBy !== 'smart') {
@@ -5583,9 +5441,7 @@ const WorktreeList = React.memo(function WorktreeList({
     hasTrackedSmartDistributionRef.current = true
   }, [sortBy, sortedIds])
 
-  // Why fire on the transition: switching away from Smart is the user signal
-  // we care about (regression). Use a ref to compare against the previous
-  // value so we don't double-fire when sortBy momentarily round-trips.
+  // Why fire on the transition: switching away from Smart is the signal; compare via ref so a round-trip doesn't double-fire.
   const prevSortByRef = useRef(sortBy)
   useEffect(() => {
     const prev = prevSortByRef.current
@@ -5595,21 +5451,17 @@ const WorktreeList = React.memo(function WorktreeList({
     }
   }, [sortBy])
 
-  // Persist the computed sort order so the sidebar can be restored after
-  // restart. Only persist during live sessions (live signal latched) —
-  // on cold start we are *reading* the persisted order, not overwriting it.
+  // Why: only persist during live sessions so cold start reads the persisted order instead of overwriting it.
   useEffect(() => {
     if (sortBy !== 'smart' || sortedIds.length === 0 || !sessionHasHadLiveSmartSignal.current) {
       return
     }
-    // Why: sortOrder is persisted in each host's worktreeMeta and enriched from
-    // the owner host, so persist each host's ids on that host.
+    // Why: sortOrder lives in each host's worktreeMeta, so persist each host's ids on that host.
     const state = useAppStore.getState()
     persistWorktreeSortOrderByHost(state, sortedIds)
   }, [sortedIds, sortBy])
 
-  // Flatten, filter, and apply stable sort order via the shared utility so
-  // the card order always matches the Cmd+1–9 shortcut numbering.
+  // Flatten/filter/sort via the shared utility so card order matches Cmd+1–9 numbering.
   const visibleWorktrees = useMemo(() => {
     void agentStatusEpoch
     const ids = computeVisibleWorktreeIds(worktreesByRepo, sortedIds, {
@@ -5618,8 +5470,7 @@ const WorktreeList = React.memo(function WorktreeList({
       tabsByWorktree,
       ptyIdsByTabId,
       browserTabsByWorktree,
-      // Why snapshot on agentStatusEpoch: membership must update immediately,
-      // while subscribing to the full map would repaint on every hook ping.
+      // Why snapshot on agentStatusEpoch: update membership immediately without repainting on every hook ping.
       worktreeIdsWithLiveAgent: showSleepingWorkspaces
         ? EMPTY_WORKTREE_ID_SET
         : getWorktreeIdsWithLiveAgent(
@@ -5640,9 +5491,7 @@ const WorktreeList = React.memo(function WorktreeList({
       !ids.includes(agentSendTargetWorktreeId) &&
       worktreeMap.has(agentSendTargetWorktreeId)
     ) {
-      // Why: send-target mode is a temporary picker overlay on the current
-      // sidebar. Make the target card reachable without rewriting the user's
-      // filters; closing the popover naturally restores the filtered view.
+      // Why: send-target mode is a temporary picker; surface the target card without rewriting the user's filters.
       ids.push(agentSendTargetWorktreeId)
     }
     return ids.map((id) => worktreeMap.get(id)).filter((w): w is Worktree => w != null)
@@ -5670,8 +5519,7 @@ const WorktreeList = React.memo(function WorktreeList({
   const collapsedGroups = useAppStore((s) => s.collapsedGroups)
   const toggleGroup = useAppStore((s) => s.toggleCollapsedGroup)
 
-  // Why: manual repo header order is bound to state.repos. Recent/Smart derive
-  // header order from the sorted visible worktree stream instead.
+  // Why: manual header order is bound to state.repos; Recent/Smart derive order from the sorted worktree stream.
   const repos = useAppStore((s) => s.repos)
   const projectHostSetupProjection = useProjectHostSetupProjection()
   const projectGrouping = useMemo(
@@ -5825,11 +5673,8 @@ const WorktreeList = React.memo(function WorktreeList({
   }, [filterRepoIds, groupBy, visibleReposForRows, visibleWorktrees, worktreesByRepo])
   const allRepoIds = useMemo(() => repos.map((r) => r.id), [repos])
 
-  // Why: buildRows only needs which creates exist and their repo. Subscribe on a
-  // flat key array (value-compared by useShallow) so progress updates
-  // (phase/loaderVisible) don't churn it and rebuild the whole sidebar row model
-  // on every creation tick. Split on the first space — the creationId is a UUID,
-  // so it has none and the repoId (which may contain spaces) stays intact.
+  // Why: subscribe on a flat key array (useShallow) so progress ticks don't rebuild the whole row model.
+  // Split on first space — creationId is a UUID (no space) so a space-containing repoId stays intact.
   const pendingCreationKeys = useAppStore(
     useShallow((s) =>
       Object.values(s.pendingWorktreeCreations ?? {}).map(
@@ -5872,7 +5717,6 @@ const WorktreeList = React.memo(function WorktreeList({
     [hostOptions]
   )
 
-  // Build flat row list for rendering
   const rows: Row[] = useMemo(
     () =>
       buildRows(
@@ -5935,9 +5779,7 @@ const WorktreeList = React.memo(function WorktreeList({
       const knownHostIds = new Set(hostOptionIds)
       const nextOrder: ExecutionHostId[] = [...orderedVisibleHostIds]
       const seen = new Set(nextOrder)
-      // Why: dragging only covers rendered host sections. Keep non-rendered
-      // SSH/runtime hosts in the saved preference so they return in the same
-      // place when their workspaces become visible again.
+      // Why: dragging only covers rendered hosts; keep non-rendered SSH/runtime hosts in the saved order so they return in place.
       for (const hostId of [...workspaceHostOrder, ...hostOptionIds]) {
         if (!knownHostIds.has(hostId) || visibleHostIds.has(hostId) || seen.has(hostId)) {
           continue
@@ -5959,8 +5801,7 @@ const WorktreeList = React.memo(function WorktreeList({
         defaultHostId,
         collapsedHostKeys: effectiveCollapsedGroups,
         forceCollapseHosts: hostDragActive,
-        // Why: projects/workspaces are now the primary sidebar object in every
-        // grouping mode; host sections are only an explicit host-filter view.
+        // Why: projects/workspaces are the primary sidebar object; host sections are only an explicit host-filter view.
         preferProjectGrouping: true
       }),
     [
@@ -5992,16 +5833,11 @@ const WorktreeList = React.memo(function WorktreeList({
     }
     return keys
   }, [sectionRows])
-  // Why: status headers change during wake (inactive -> active). Key only on
-  // the grouping mode so row identity survives those ordinary status moves.
+  // Why: status headers move during wake (inactive -> active); key only on grouping mode so row identity survives.
   const visibleHostResetKey = visibleWorkspaceHostIds?.join(',') ?? 'all'
   const viewportResetKey = `group:${groupBy}:host:${visibleHostResetKey}:lineage`
 
-  // Why: derive the rendered item order from the post-buildRows() row list,
-  // not the flat `worktrees` array, because grouping (groupBy: 'repo' or
-  // 'pr-status') can reorder cards into grouped sections. Using the flat
-  // order would cause Cmd+1–9 shortcuts to not match the visual card
-  // positions when grouping is active.
+  // Why: derive order from the built rows, not the flat worktrees array, so Cmd+1–9 match visual positions when grouping reorders cards.
   const renderedWorktrees = useMemo(
     () => getRenderedWorktreesInSidebarOrder(sectionRows, pinnedDisplayPolicy),
     [pinnedDisplayPolicy, sectionRows]
@@ -6018,8 +5854,7 @@ const WorktreeList = React.memo(function WorktreeList({
     selectionAnchorId,
     renderedWorktreeIds
   )
-  // Why: filters/grouping can hide selected cards. Prune during render so
-  // context menus and child rows never see stale ids for unrendered worktrees.
+  // Why: filters/grouping can hide selected cards; prune during render so nothing sees stale ids for unrendered worktrees.
   if (!areWorktreeSelectionsEqual(selectedWorktreeIds, prunedSelection.selectedIds)) {
     setSelectedWorktreeIds(prunedSelection.selectedIds)
   }
@@ -6073,8 +5908,7 @@ const WorktreeList = React.memo(function WorktreeList({
       })
       setSelectedWorktreeIds(result.selectedIds)
       setSelectionAnchorId(result.anchorId)
-      // Plain click keeps its existing navigation behavior; modifier gestures
-      // are selection-only so users can build a batch without switching away.
+      // Plain click navigates; modifier gestures are selection-only so a batch can build without switching away.
       return intent !== 'replace'
     },
     [renderedWorktreeIds, selectedWorktreeIds, selectionAnchorId]
@@ -6093,25 +5927,18 @@ const WorktreeList = React.memo(function WorktreeList({
   )
 
   const handleImmediateWorktreeActivate = useCallback((worktreeId: string, rowKey?: string) => {
-    // Why: React-rendering the full virtualized sidebar on the pointer path is
-    // visible latency. Mutate only the selected-row affordance; store state
-    // reconciles the same attributes after activation settles.
+    // Why: re-rendering the virtualized sidebar on the pointer path adds visible latency; mutate the row directly and let store state reconcile after.
     markSidebarWorktreeActiveImmediately(worktreeId, rowKey)
   }, [])
 
-  // Why: full-page navigation views are not scoped to one worktree, so no
-  // sidebar card should appear selected while one of them is active.
+  // Why: full-page nav views aren't scoped to a worktree, so no sidebar card should look selected.
   const selectedSidebarWorktreeId =
     activeView === 'tasks' || activeView === 'activity' ? null : currentSidebarWorktreeId
 
-  // Why layout effect instead of effect: the global Cmd/Ctrl+1–9 key handler
-  // can fire immediately after React commits the new grouped/collapsed order.
-  // Publishing after paint leaves a brief window where the sidebar shows the
-  // new numbering but the shortcut cache still points at the previous order.
+  // Why layout effect: the Cmd/Ctrl+1–9 handler can fire right after commit; publishing after paint would leave the shortcut cache stale.
   useLayoutEffect(() => {
     setVisibleWorktreeIds(renderedWorktreeIds)
-    // Why: collapsed/full-page sidebar states unmount the list. Clear the
-    // rendered-order cache so shortcuts fall back to the live store snapshot.
+    // Why: unmounting the list clears the rendered-order cache so shortcuts fall back to the live store snapshot.
     return () => setVisibleWorktreeIds([])
   }, [renderedWorktreeIds])
 
@@ -6169,8 +5996,7 @@ const WorktreeList = React.memo(function WorktreeList({
     async (projectId: string) => {
       const repo = repos.find((candidate) => candidate.id === projectId)
       let detected = detectedWorktreesByRepo[projectId]
-      // Why: baseline seeding depends on authoritative hidden paths; do not
-      // dismiss the initial prompt on a stale/non-authoritative snapshot.
+      // Why: baseline seeding needs authoritative hidden paths, so don't dismiss on a stale snapshot.
       if (detected?.authoritative !== true) {
         const refreshed = await fetchWorktrees(projectId, { requireAuthoritative: true })
         if (!refreshed) {
@@ -6403,8 +6229,7 @@ const WorktreeList = React.memo(function WorktreeList({
           removeContainedProjects: projectGroupRemoveContainedProjects
         }
       )
-      // Why: a missing group is already in the desired end state, so close
-      // quietly; only a real delete failure warrants an error toast.
+      // Why: a missing group is already the desired end state, so only a real delete failure warrants a toast.
       if (result.status === 'group-delete-failed') {
         toast.error(
           translate(
@@ -6442,8 +6267,7 @@ const WorktreeList = React.memo(function WorktreeList({
         )
       }
     } finally {
-      // Why: deleting contained projects can empty the sidebar and unmount this
-      // dialog before its own close handler runs, so the parent owns cleanup.
+      // Why: deleting contained projects can unmount this dialog before its close handler runs, so the parent owns cleanup.
       setProjectGroupDeleteDialog(null)
     }
   }, [
@@ -6541,8 +6365,7 @@ const WorktreeList = React.memo(function WorktreeList({
       if (updates.size === 0) {
         return
       }
-      // Why: showing an insertion line promises exact placement, so a
-      // cross-status sidebar drop must persist manual order for that section.
+      // Why: the insertion line promises exact placement, so persist manual order on a cross-status drop.
       if (order.changed) {
         setSortBy('manual')
       }
@@ -6589,9 +6412,7 @@ const WorktreeList = React.memo(function WorktreeList({
       if (!result.changed) {
         return
       }
-      // Why: a drag reorder is an explicit request for user-authored order.
-      // Switch modes only after a real move so accidental click-drags do not
-      // alter the user's selected sort.
+      // Why: only switch to Manual after a real move so accidental click-drags don't change the sort.
       setSortBy('manual')
       void updateWorktreesMeta(result.updates)
     },
@@ -6630,8 +6451,7 @@ const WorktreeList = React.memo(function WorktreeList({
       if (result.updates.size === 0) {
         return
       }
-      // Why: when the drop changes visual order, the board/sidebar must both
-      // switch to Manual so the committed placement remains visible.
+      // Why: switch to Manual when the drop changes order so the placement stays visible.
       if (result.shouldSwitchToManual) {
         setSortBy('manual')
       }
@@ -6641,11 +6461,7 @@ const WorktreeList = React.memo(function WorktreeList({
     [setSortBy, sortBy, updateWorktreesMeta, worktreeMap, workspaceStatuses]
   )
 
-  // Why: hideDefaultBranchWorkspace is counted as a filter here so the
-  // empty-sidebar escape hatch (Clear Filters button below) is reachable when
-  // it's the only reason the list is empty — otherwise a user whose only
-  // worktree is a default-branch row and who just toggled hide on would see
-  // "No workspaces found" with no way back short of reopening the filter menu.
+  // Why: count hideDefaultBranchWorkspace as a filter so the Clear Filters escape hatch stays reachable when it alone empties the list.
   const filterState = useMemo(
     () => ({
       showSleepingWorkspaces,
@@ -6753,8 +6569,7 @@ const WorktreeList = React.memo(function WorktreeList({
         return
       }
       if (!renderedWorktreeIds.includes(currentSidebarWorktreeId)) {
-        // Why: the toolbar action promises to reveal the current workspace; when
-        // sidebar filters hide it, relax those filters before queuing the reveal.
+        // Why: the reveal action must show the current workspace, so relax filters that hide it first.
         clearFilters()
       }
       revealWorktreeInSidebar(currentSidebarWorktreeId, {
@@ -6792,8 +6607,7 @@ const WorktreeList = React.memo(function WorktreeList({
     worktrees.length === 0 &&
     placeholderRepoIds.size === 0 &&
     importedWorktreesByRepo.size === 0
-  // Why: Project Group headers can render before workspace rows load, but when
-  // active filters hide everything the Clear Filters empty state must win.
+  // Why: when active filters hide every row, the Clear Filters empty state must win over Project Group headers.
   if (rows.length === 0 || filtersHideAllRows) {
     return (
       <div
diff --git a/src/renderer/src/components/sidebar/delete-worktree-flow.ts b/src/renderer/src/components/sidebar/delete-worktree-flow.ts
index ce2cedc5d1f..f5a653a42b9 100644
--- a/src/renderer/src/components/sidebar/delete-worktree-flow.ts
+++ b/src/renderer/src/components/sidebar/delete-worktree-flow.ts
@@ -23,16 +23,11 @@ type WorktreeBatchDeleteOptions = {
 type WorktreeDeleteWithToastOptions = {
   force?: boolean
   onForceDeleted?: (worktreeId: string) => void
-  // Why: batch deletes suppress the per-delete focus handoff and instead focus a
-  // single survivor after the whole batch settles (see runWorktreeDeletesInParallel).
+  // Why: batch deletes suppress the per-delete focus handoff to focus one survivor after the batch (see runWorktreeDeletesInParallel).
   focusSuccessorOnDelete?: boolean
 }
 
-// Why: a failed delete almost always means the worktree still has changes
-// that need attention (uncommitted work, unpushed commits, conflicts). The
-// "View" affordance should surface those changes directly, not just bring
-// the worktree into focus, so the user lands on the diff panel where the
-// blocking work is visible.
+// Why: a failed delete usually means unresolved changes, so land on the diff panel, not just focus the worktree.
 function viewWorktreeDiff(worktreeId: string): void {
   activateAndRevealWorktree(worktreeId)
   const state = useAppStore.getState()
@@ -51,20 +46,14 @@ export async function runWorktreeDeletesInParallel(
   targets: readonly Pick<Worktree, 'id' | 'displayName' | 'repoId' | 'path'>[],
   options: WorktreeDeleteWithToastOptions = {}
 ): Promise<string[]> {
-  // Why: capture the viewed workspace before any delete runs so we can focus a
-  // single survivor once the batch settles, rather than per delete.
+  // Why: capture the viewed workspace before any delete so we can focus one survivor after the batch settles, not per delete.
   const activeWorktreeIdBefore = useAppStore.getState().activeWorktreeId
   const commitBatchFocus = activeWorktreeIdBefore
     ? prepareActiveWorktreeFocusAfterDelete(activeWorktreeIdBefore)
     : null
-  // Why: deletes are serialized per repo to avoid git lock races, but every
-  // selected/lineage workspace should show in-flight feedback immediately.
+  // Why: mark every target deleting up front for immediate in-flight feedback, even though deletes serialize per repo.
   useAppStore.getState().markWorktreesDeleting(targets.map((target) => target.id))
-  // Why: `git worktree remove`/`prune`/`branch -D` mutate repo-wide ref state
-  // and contend on `.git/packed-refs.lock` and per-worktree HEAD.lock. Running
-  // every target through Promise.all races those locks on the same repo and
-  // intermittently fails one or more deletes. Serialize per repoId while
-  // still letting deletes across different repos run concurrently.
+  // Why: worktree remove/prune/branch -D race on shared ref locks; group by repoId to serialize per repo (cross-repo stays parallel).
   const groups = new Map<string, (typeof targets)[number][]>()
   for (const target of targets) {
     const group = groups.get(target.repoId)
@@ -75,9 +64,7 @@ export async function runWorktreeDeletesInParallel(
     }
   }
   for (const group of groups.values()) {
-    // Why: selected parent+child workspace deletes must remove nested children
-    // first. Otherwise the parent delete is correctly rejected because it still
-    // contains another registered worktree.
+    // Why: delete nested children first — else the parent delete is rejected while it still contains a registered worktree.
     group.sort((a, b) => b.path.length - a.path.length)
   }
   const groupResults = await Promise.all(
@@ -96,8 +83,7 @@ export async function runWorktreeDeletesInParallel(
         if (deleted) {
           deletedInGroup.push(target.id)
         } else {
-          // Why: after a descendant delete fails, deleting an ancestor can still
-          // remove that child from disk when it lives under the parent directory.
+          // Why: after a descendant delete fails, deleting an ancestor can still remove that child from disk (it lives under the parent).
           failedInGroup.push(target)
         }
       }
@@ -105,9 +91,7 @@ export async function runWorktreeDeletesInParallel(
     })
   )
   const deletedSet = new Set(groupResults.flat())
-  // Why: focus a survivor once, after the batch settles, rather than per delete —
-  // an intermediate focus could land on (and spawn a terminal in) a workspace this
-  // same batch is about to delete.
+  // Why: focus a survivor once after the batch settles — an intermediate focus could spawn a terminal in a to-be-deleted workspace.
   if (activeWorktreeIdBefore && deletedSet.has(activeWorktreeIdBefore)) {
     commitBatchFocus?.()
   }
@@ -115,17 +99,10 @@ export async function runWorktreeDeletesInParallel(
 }
 
 /**
- * Shared delete-with-toast flow used by both DeleteWorktreeDialog (confirm
- * path) and WorktreeContextMenu (skip-confirm path). Centralizes the error
- * toast copy, the "Force Delete" action wiring, and the "View" affordance so
- * both entry points behave identically from the user's perspective.
+ * Shared delete-with-toast flow for both DeleteWorktreeDialog (confirm) and
+ * WorktreeContextMenu (skip-confirm), so both entry points behave identically.
  *
- * Why this is a module helper rather than a store action: the behavior is
- * intrinsically UI-shaped — it shows sonner toasts, registers action/cancel
- * handlers, and depends on `activateAndRevealWorktree` (a renderer-only
- * helper). Keeping it in the renderer layer avoids bleeding toast/UI
- * concerns into the store slice while still preventing the two delete
- * entry points from drifting apart.
+ * A renderer-layer helper (not a store action) to keep UI concerns out of the store slice.
  */
 export function runWorktreeDeleteWithToast(
   worktreeId: string,
@@ -139,8 +116,7 @@ export function runWorktreeDeleteWithToast(
   return removeWorktree(worktreeId, options.force === true)
     .then((result) => {
       if (result.ok) {
-        // Why: keep the user on a live workspace instead of the Landing screen
-        // when they delete the one they were viewing.
+        // Why: keep the user on a live workspace instead of the Landing screen when they delete the one they were viewing.
         if (focusSuccessor) {
           commitFocus()
         }
@@ -158,9 +134,7 @@ export function runWorktreeDeleteWithToast(
         hasKnownChanges,
         onViewChanges: () => viewWorktreeDiff(worktreeId),
         onForceDelete: () => {
-          // Why: recapture at click time — the user may have navigated away
-          // while the failed-delete toast was open, so focus only hands off
-          // when this is still the workspace they are viewing.
+          // Why: recapture at click time — the user may have navigated away while the toast was open, so focus only hands off if still viewed.
           const commitForceFocus = prepareActiveWorktreeFocusAfterDelete(worktreeId)
           const forceRemoval = useAppStore.getState().removeWorktree(worktreeId, true)
           forceRemoval
@@ -226,18 +200,11 @@ export function runWorktreeDeleteWithToast(
 }
 
 /**
- * Shared funnel for the standard (non-folder) delete decision tree, called
- * from both WorktreeContextMenu and MemoryStatusSegment. Mirrors the
- * `runSleepWorktree` pattern: reads state imperatively so the helper can be
- * invoked from any handler without plumbing selectors through props, then
- * branches on the user's `skipDeleteWorktreeConfirm` preference — either
- * running the delete immediately with toast feedback, or opening the
- * confirmation modal.
+ * Shared funnel for the standard (non-folder) delete decision tree (WorktreeContextMenu,
+ * MemoryStatusSegment); branches on the `skipDeleteWorktreeConfirm` preference.
  *
- * The missing-record guard here is defense-in-depth — the caller is
- * responsible for disabling UI when this is known ahead of time, but we still
- * refuse to act if the record disappeared between render and click (e.g. a
- * concurrent delete or state reset).
+ * The missing-record guard is defense-in-depth: refuse to act if the record vanished
+ * between render and click (concurrent delete or state reset).
  */
 export function runWorktreeDelete(worktreeId: string): void {
   const state = useAppStore.getState()
@@ -247,8 +214,7 @@ export function runWorktreeDelete(worktreeId: string): void {
   }
   if (target.isMainWorktree) {
     const repo = state.repos.find((entry) => entry.id === target.repoId)
-    // Why: git refuses to delete the primary checkout, but users can still
-    // remove the owning project from Orca without deleting disk contents.
+    // Why: git refuses to delete the primary checkout; users can still remove the owning project from Orca (disk contents kept).
     state.openModal('confirm-remove-folder', {
       repoId: target.repoId,
       displayName: repo?.displayName ?? target.displayName
@@ -257,16 +223,8 @@ export function runWorktreeDelete(worktreeId: string): void {
   }
   state.clearWorktreeDeleteState(worktreeId)
 
-  // Why: a workspace on a removed/disconnected SSH host cannot go through the
-  // normal remote removal — its provider is gone, so worktrees:remove throws
-  // before any cleanup. Route to a dialog that offers reconnect-and-delete
-  // (when the target still exists) or a local-only forget.
-  //
-  // Skip this on paired web/mobile clients: SSH targets/labels/connection state
-  // are desktop-only, so those clients have empty sshTargetLabels and would
-  // misclassify every SSH repo as a ghost, routing to a forget dialog whose
-  // local-only backend is unavailable there. Their normal worktree.rm RPC path
-  // already handles the delete against the desktop runtime.
+  // Why: a disconnected SSH host has no provider, so worktrees:remove throws; route to reconnect-and-delete or local-only forget.
+  // Skip on paired web/mobile clients: SSH state is desktop-only, so empty sshTargetLabels misclassifies SSH repos as ghosts; their worktree.rm RPC still handles the delete.
   const matchingRepos = state.repos.filter((entry) => entry.id === target.repoId)
   const repo = target.hostId
     ? findRepoForHost(matchingRepos, target.repoId, { hostId: target.hostId })
@@ -281,11 +239,7 @@ export function runWorktreeDelete(worktreeId: string): void {
         sshTargetLabels: state.sshTargetLabels
       })
   if (sshResolution.kind === 'ghost' || sshResolution.kind === 'disconnected') {
-    // Why no lineage-children warning here (unlike the normal path below):
-    // forget-local is metadata-only and per-worktree, so it can't fail on a
-    // still-registered child the way a remote git removal would. Any descendants
-    // live on the same ghost host and remain independently visible/forgettable —
-    // they are not orphaned unrecoverably.
+    // Why no lineage-children warning: forget-local is metadata-only per-worktree, so it can't fail on a still-registered child.
     state.openModal('forget-ssh-workspace', {
       worktreeId,
       displayName: target.displayName,
@@ -338,8 +292,7 @@ export function runWorktreeBatchDelete(
     state.clearWorktreeDeleteState(target.id)
   }
 
-  // Why: bulk cleanup can destroy many directories at once, so batch deletes
-  // and Space-triggered deletes must keep an explicit confirmation step.
+  // Why: bulk cleanup can destroy many directories at once, so batch/Space deletes keep an explicit confirmation step.
   const singleTargetHasLineageChildren =
     targets.length === 1 &&
     getWorkspaceDeleteLineage(targets[0], state.allWorktrees(), state.worktreeLineageById)
diff --git a/src/renderer/src/components/sidebar/smart-attention.ts b/src/renderer/src/components/sidebar/smart-attention.ts
index 92da5726826..01a551428ca 100644
--- a/src/renderer/src/components/sidebar/smart-attention.ts
+++ b/src/renderer/src/components/sidebar/smart-attention.ts
@@ -19,35 +19,27 @@ import { parsePaneKey } from '../../../../shared/stable-pane-id'
  *   3 — Working (`working`)
  *   4 — Idle (no live entry, stale entry, or interrupted `done`)
  *
- * Class is the primary sort key; within a class the comparator falls back to
- * the resolved attention timestamp. See docs/smart-worktree-order-redesign.md.
+ * Primary sort key; ties fall back to the attention timestamp. See docs/smart-worktree-order-redesign.md.
  */
 export type SmartClass = 1 | 2 | 3 | 4
 
 /**
- * What surfaced a worktree into Class 1. Carried only for Class 1 results
- * because that's the only class the telemetry promotion event reports on.
+ * What surfaced a worktree into Class 1 (carried only for Class 1, the only class telemetry reports on).
  *   - `blocked` / `waiting`: hook entry in that state.
- *   - `title-heuristic`: no fresh hook entry; runtime pane title classified
- *     as `'permission'` by `detectAgentStatusFromTitle`.
+ *   - `title-heuristic`: no fresh hook entry; runtime pane title classified as `'permission'`.
  */
 export type AttentionCause = 'blocked' | 'waiting' | 'title-heuristic'
 
 /**
  * Per-worktree resolution computed once before sorting.
  *
- * `attentionTimestamp` semantics depend on the class:
- *   - Class 1 / 2: `stateStartedAt` of the current entry (when the agent
- *     entered the attention state).
- *   - Class 3: `stateStartedAt` of the most recent prior `done`/`blocked`/
- *     `waiting` entry in `stateHistory[]`, falling back to the current
- *     `working` `stateStartedAt` when no prior attention event exists.
- *   - Class 4: `0` — the comparator drops to `effectiveRecentActivity` for
- *     within-class ordering on idle worktrees.
+ * `attentionTimestamp` by class:
+ *   - Class 1 / 2: `stateStartedAt` of the current entry.
+ *   - Class 3: `stateStartedAt` of the most recent prior `done`/`blocked`/`waiting` entry,
+ *     falling back to the current `working` `stateStartedAt`.
+ *   - Class 4: `0` — comparator drops to `effectiveRecentActivity` for idle ordering.
  *
- * `cause` is set only when `cls === 1`, and reflects the input that won the
- * within-class max-timestamp comparison. Used for the
- * `smart_sort_class_1_promotion` telemetry event.
+ * `cause` is set only when `cls === 1`; feeds the `smart_sort_class_1_promotion` telemetry event.
  */
 export type WorktreeAttention = {
   cls: SmartClass
@@ -71,8 +63,7 @@ export function hasFreshAttributedAgentStatus(
     if (entry.worktreeId) {
       return true
     }
-    // Why: hook rows can omit the redundant stamp while paneKey still maps to
-    // a mirrored tab, which is enough to end the Smart cold-start fallback.
+    // Why: hook rows can omit the worktree stamp but still map via paneKey to a mirrored tab — enough to end cold-start.
     freshUnstampedTabIds.add(parsed.tabId)
   }
   if (freshUnstampedTabIds.size === 0) {
@@ -84,24 +75,18 @@ export function hasFreshAttributedAgentStatus(
 }
 
 /**
- * Walk a pane's state-history rows and return the timestamp of the most
- * recent `done`/`blocked`/`waiting` entry, ignoring `done` rows that were
- * interrupted (the user pressed Ctrl+C — that turn no longer demands
- * attention). Returns `null` when no qualifying row exists.
+ * Return the timestamp of the most recent `done`/`blocked`/`waiting` history row, ignoring
+ * interrupted `done` rows (Ctrl+C). Returns `null` when no qualifying row exists.
  */
 export function mostRecentAttentionInHistory(history: AgentStateHistoryEntry[]): number | null {
   let max = 0
   for (const h of history) {
-    // Why: setAgentStatus preserves `interrupted` on history rows when an
-    // interrupted `done` transitions out, so we can filter on history the
-    // same way the current entry does.
+    // Why: setAgentStatus preserves `interrupted` on history rows, so filter them like the current entry.
     if (h.state === 'done' && h.interrupted) {
       continue
     }
     if (h.state === 'done' || h.state === 'blocked' || h.state === 'waiting') {
-      // Why: NaN is silently skipped by `>`, but Infinity from a corrupted
-      // row would pin the worktree at the top of Class 3 forever. Treat
-      // non-finite values as missing.
+      // Why: Infinity from a corrupted row would pin the worktree atop Class 3 forever; treat non-finite as missing.
       if (!Number.isFinite(h.startedAt)) {
         continue
       }
@@ -114,27 +99,18 @@ export function mostRecentAttentionInHistory(history: AgentStateHistoryEntry[]):
 }
 
 /**
- * One pane's contribution to a worktree's attention class. Hook entries from
- * `agentStatusByPaneKey` are authoritative when fresh; otherwise we fall back
- * to the terminal-title heuristic for hookless agents (Edge case 9 in the
- * design doc). Hook authority is per-pane, not per-worktree — a worktree with
- * a fresh hook on pane A and only a title on pane B mixes both branches.
+ * One pane's contribution to a worktree's attention class. Fresh hook entries win; hookless
+ * panes fall back to the title heuristic (design doc Edge case 9). Authority is per-pane, not per-worktree.
  */
 export type PaneInput =
   | { kind: 'hook'; entry: AgentStatusEntry }
-  // Why: TerminalTab has no per-tab lastActivityAt; the worktree-level value
-  // is enough since within-class ordering compares across worktrees.
+  // Why: TerminalTab has no per-tab lastActivityAt; the worktree-level value suffices for cross-worktree ordering.
   | { kind: 'title'; status: AgentStatus | null; worktreeLastActivityAt: number }
 
 /**
  * Resolve a worktree's class + attention timestamp from its panes' inputs.
- * Stale hook entries (older than `AGENT_STATUS_STALE_AFTER_MS`) are skipped
- * — the worktree falls to Class 4 if no fresh hook entry and no recognized
- * title heuristic exists.
- *
- * Across multiple panes:
- *   - `cls` is the **min** (most attention-demanding pane wins).
- *   - `attentionTimestamp` is the **max** within the resolved class.
+ * Stale hook entries are skipped; the worktree falls to Class 4 with no fresh hook and no title heuristic.
+ * Across panes: `cls` is the **min** (most demanding pane wins), `attentionTimestamp` the **max** within that class.
  */
 export function resolveAttention(panes: PaneInput[], now: number): WorktreeAttention {
   let bestCls: SmartClass = 4
@@ -151,9 +127,7 @@ export function resolveAttention(panes: PaneInput[], now: number): WorktreeAtten
       if (!isExplicitAgentStatusFresh(entry, now, AGENT_STATUS_STALE_AFTER_MS)) {
         continue
       }
-      // Why: defensive guard. NaN/Infinity from a corrupted stateStartedAt would
-      // poison comparisons (NaN > anything === false), silently dropping the
-      // worktree to the bottom of its class. Treat as a missing entry.
+      // Why: non-finite stateStartedAt (NaN/Infinity) would poison comparisons; treat as a missing entry.
       if (!Number.isFinite(entry.stateStartedAt)) {
         continue
       }
@@ -163,8 +137,7 @@ export function resolveAttention(panes: PaneInput[], now: number): WorktreeAtten
         ts = entry.stateStartedAt
         cause = entry.state
       } else if (entry.state === 'done') {
-        // Why: an interrupted `done` (user pressed Ctrl+C) is the user signalling
-        // "I'm done with this turn". Treat as idle, not as Class 2 attention.
+        // Why: interrupted `done` (Ctrl+C) means the user is done with the turn; treat as idle, not Class 2.
         if (entry.interrupted) {
           continue
         }
@@ -173,32 +146,22 @@ export function resolveAttention(panes: PaneInput[], now: number): WorktreeAtten
       } else {
         // working
         cls = 3
-        // Why: within Class 3, sort by the most recent prior attention event so
-        // a worktree that just transitioned done→working stays above one that's
-        // been working for an hour. Falls back to the current stateStartedAt
-        // when stateHistory is empty (e.g. fresh after restart).
+        // Why: sort Class 3 by most recent prior attention so a just-started turn outranks one working for an hour.
         const prior = mostRecentAttentionInHistory(entry.stateHistory)
         if (prior === null) {
           ts = entry.stateStartedAt
         } else if (entry.agentType === 'command-code') {
-          // Why: Command Code has no UserPromptSubmit hook, so a new prompt while
-          // still `working` only advances stateStartedAt (no new history row). It
-          // must beat the stale prior-attention timestamp. Other agents keep the
-          // prior-attention ordering — their real state transitions already mark
-          // the turn boundary, so scoping avoids reordering them.
+          // Why: Command Code has no UserPromptSubmit hook; a new prompt only bumps stateStartedAt, so max beats stale prior-attention.
           ts = Math.max(prior, entry.stateStartedAt)
         } else {
           ts = prior
         }
       }
     } else {
-      // Title-heuristic fallback (no fresh hook entry for this pane). Hook
-      // wins when fresh; this branch only fires for hookless panes.
+      // Title-heuristic fallback: only fires for panes with no fresh hook entry.
       if (pane.status === 'permission') {
         cls = 1
-        // Why now: the title detector exposes no stateStartedAt. Using `now`
-        // pins the worktree to the top of Class 1 until a hook event or the
-        // next sort, matching the user's "just noticed" mental model.
+        // Why now: title detector exposes no stateStartedAt; `now` pins it to the top of Class 1 until a hook event.
         ts = now
         cause = 'title-heuristic'
       } else if (pane.status === 'working') {
@@ -210,9 +173,7 @@ export function resolveAttention(panes: PaneInput[], now: number): WorktreeAtten
       }
     }
 
-    // Why min on class: smaller class number = higher priority. Any pane in a
-    // more attention-demanding class promotes the whole worktree. Within the
-    // same class, take the max timestamp so the freshest attention event wins.
+    // Min class wins (higher priority); tie-break on max timestamp so the freshest attention event wins.
     if (cls < bestCls || (cls === bestCls && ts > bestTs)) {
       bestCls = cls
       bestTs = ts
@@ -226,10 +187,8 @@ export function resolveAttention(panes: PaneInput[], now: number): WorktreeAtten
 }
 
 /**
- * Build a `tabId → entries[]` index over `agentStatusByPaneKey`. Entries are
- * keyed by the `tabId` prefix of their paneKey (paneKey format:
- * `${tabId}:${paneId}`). Doing this once per sort lets each worktree's
- * resolution pay O(T) lookups instead of scanning the full map.
+ * Build a `tabId → entries[]` index over `agentStatusByPaneKey`, keyed by the paneKey's
+ * `tabId` prefix. Built once per sort so each worktree's resolution is O(T), not a full-map scan.
  */
 export function buildExplicitEntriesByTabId(
   agentStatusByPaneKey: Record<string, AgentStatusEntry> | undefined,
@@ -248,8 +207,7 @@ export function buildExplicitEntriesByTabId(
   }
   for (const entry of entries) {
     const parsed = parsePaneKey(entry.paneKey)
-    // Why: paneKey must be `${tabId}:${leafUuid}`. Skip malformed or legacy
-    // numeric entries rather than bucketing unroutable rows under a tab.
+    // Why: skip malformed/legacy-numeric paneKeys rather than bucketing unroutable rows under a tab.
     if (!parsed) {
       continue
     }
@@ -282,9 +240,7 @@ function buildExplicitEntriesByWorktreeId(
 }
 
 /**
- * Extract the stable leaf id from a `${tabId}:${leafId}` paneKey. Used for
- * per-pane authority: we need to know which leaves already have a fresh hook
- * entry so we don't double-count them via the title fallback.
+ * Extract the stable leaf id from a `${tabId}:${leafId}` paneKey.
  */
 function leafIdFromPaneKey(paneKey: string): string | null {
   return parsePaneKey(paneKey)?.leafId ?? null
@@ -292,15 +248,8 @@ function leafIdFromPaneKey(paneKey: string): string | null {
 
 /**
  * Build the per-worktree attention map consumed by the smart comparator.
- *
- * Hook authority is per-pane: each pane that has a fresh hook entry uses it;
- * each pane without one falls back to the title heuristic when its runtime
- * pane title (or tab title for unmounted tabs) maps to a known status. The
- * title branch is gated on `tabHasLivePty` so slept tabs whose preserved
- * titles still match a working pattern don't leak through.
- *
- * Cost: O(E + N × T × H) where E = total entries, N = worktrees, T = tabs per
- * worktree, H = history length (bounded at AGENT_STATE_HISTORY_MAX = 20).
+ * Hook authority is per-pane; panes without a fresh hook fall back to the title heuristic,
+ * gated on `tabHasLivePty` so slept tabs' stale working-pattern titles don't leak through.
  */
 export function buildAttentionByWorktree(
   worktrees: Worktree[],
@@ -321,9 +270,7 @@ export function buildAttentionByWorktree(
 
   for (const worktree of worktrees) {
     const tabs = tabsByWorktree?.[worktree.id] ?? []
-    // Why: hook stamps can arrive before the renderer mirrors a headless or
-    // remote tab. Once mirrored anywhere, live tab ownership is authoritative
-    // over a stale worktree stamp and must not promote both worktrees.
+    // Why: hook stamps can precede tab mirroring; once mirrored, live tab ownership wins so both worktrees aren't promoted.
     const panes: PaneInput[] = (byAttributedWorktree.get(worktree.id) ?? [])
       .filter((entry) => {
         const parsed = parsePaneKey(entry.paneKey)
@@ -336,16 +283,12 @@ export function buildAttentionByWorktree(
     }
     for (const tab of tabs) {
       const hookEntries = byTab.get(tab.id)
-      // Why: leaf ids covered by a hook entry skip the title fallback so we
-      // don't double-count them. Hook authority is per-pane.
+      // Why: leaves covered by a hook entry skip the title fallback so we don't double-count them.
       const hookLeafIds = new Set<string>()
       if (hookEntries) {
         for (const entry of hookEntries) {
           panes.push({ kind: 'hook', entry })
-          // Why: only fresh hook entries should suppress the title-heuristic
-          // fallback for their pane. A stale hook is filtered out by
-          // resolveAttention; if we marked its pane as "hook-covered" we'd hide
-          // the live title behind a dead entry and drop the worktree to Class 4.
+          // Why: only fresh hook entries suppress the title fallback; a stale one would hide the live title and drop to Class 4.
           if (!isExplicitAgentStatusFresh(entry, now, AGENT_STATUS_STALE_AFTER_MS)) {
             continue
           }
@@ -356,17 +299,14 @@ export function buildAttentionByWorktree(
         }
       }
 
-      // Why gate on tabHasLivePty: runtimePaneTitlesByTabId is preserved under
-      // sleep (keepIdentifiers), so a slept tab whose pane titles still match
-      // a working pattern would otherwise leak into the comparator.
+      // Why: runtimePaneTitlesByTabId survives sleep, so a slept tab's stale working-pattern title would leak in without this gate.
       if (!tabHasLivePty(ptyIdsByTabId, tab.id)) {
         continue
       }
 
       const paneTitles = runtimePaneTitlesByTabId[tab.id]
       if (paneTitles && Object.keys(paneTitles).length > 0) {
-        // Why: split-pane tabs can host multiple agents; each pane reports
-        // its own title. Mirrors the precedence used by getWorkingAgentsPerWorktree.
+        // Why: split-pane tabs host multiple agents, one title each; mirrors getWorkingAgentsPerWorktree precedence.
         const tabLayout = terminalLayoutsByTabId?.[tab.id]
         for (const [runtimePaneId, title] of Object.entries(paneTitles)) {
           const leafId = resolveRuntimePaneTitleLeafId(tabLayout, runtimePaneId)
@@ -380,9 +320,7 @@ export function buildAttentionByWorktree(
           })
         }
       } else if (hookLeafIds.size === 0) {
-        // Why: tabs we have not mounted yet (restored-but-unvisited) only
-        // expose the legacy tab title. Fall back to it only when no pane-level
-        // titles or hook entries exist for this tab.
+        // Why: unmounted tabs (restored-but-unvisited) expose only the legacy tab title.
         panes.push({
           kind: 'title',
           status: classifyTitleActivity(tab.title),
diff --git a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
index 5c9e580b5fa..6f29ed85a66 100644
--- a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
+++ b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
@@ -1,9 +1,4 @@
-/* eslint-disable max-lines -- Why: consolidating memory + sessions into one
-   surface deliberately co-locates the sparkline, worktree tree, session list,
-   daemon actions, and kill-confirm dialog so the popover body and badge stay
-   consistent. Splitting across files would scatter render-state that only
-   exists to serve this one status-bar segment. See
-   docs/resource-usage-merge-spec.md for the full design. */
+/* eslint-disable max-lines -- Why: one status-bar segment co-locates sparkline, worktree tree, session list, daemon actions, and kill-confirm; see docs/resource-usage-merge-spec.md. */
 import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import {
   AlertTriangle,
@@ -88,10 +83,7 @@ type SortOption = 'memory' | 'cpu' | 'name'
 const METRIC_COLUMNS_CLS = 'flex items-center shrink-0 tabular-nums'
 const CPU_COLUMN_CLS = 'w-12 text-right'
 const MEM_COLUMN_CLS = 'w-16 text-right'
-// Why: every row (session, worktree, repo, app) AND the column header
-// reserve this same trailing gutter so the CPU/Memory columns line up
-// regardless of whether a row carries a kill-X. The X button sits inside
-// this gutter for session rows; other rows leave it blank.
+// Why: every row and the header reserve this trailing gutter so CPU/Memory columns align whether or not the row has a kill-X.
 const ROW_TRAILING_GUTTER_CLS = 'w-5 shrink-0 flex items-center justify-end'
 
 // ─── Formatters ─────────────────────────────────────────────────────
@@ -319,8 +311,7 @@ function AppSection({
 // ─── Sorting ────────────────────────────────────────────────────────
 
 function compareMetricDesc(a: Metric, b: Metric): number {
-  // Why: null metrics (remote rows) sort last regardless of direction so
-  // they don't pollute the "biggest CPU/memory consumers" view.
+  // Why: null metrics (remote rows) sort last regardless of direction so they don't pollute the "biggest consumers" view.
   if (a === null && b === null) {
     return 0
   }
@@ -359,8 +350,7 @@ function sortProjectGroups(groups: UnifiedProjectGroup[], sort: SortOption): Uni
 
 // ─── Session row ────────────────────────────────────────────────────
 
-// Exported (with WorktreeRow) for row-level regression tests pinning the kill
-// affordance and remote-chip presentation for SSH/orphan rows.
+// Exported (with WorktreeRow) for row-level regression tests pinning the kill affordance and remote-chip presentation.
 export function SessionRow({
   session,
   worktreeId,
@@ -410,11 +400,7 @@ export function SessionRow({
         {session.label}
       </span>
       <MetricPair cpu={session.cpu} memory={session.memory} size="small" />
-      {/* Why: kill X lives inside the shared trailing gutter so CPU/Memory
-          columns stay aligned with the column header (whose gutter is empty).
-          Bound sessions hide the X until the row is hovered/focused (calm
-          list); orphan sessions show it always so the "this is reclaimable"
-          affordance survives. Mirrors Settings > Manage Sessions. */}
+      {/* Why: kill X sits in the shared gutter for column alignment; bound rows reveal it on hover/focus, orphan rows always show it as reclaimable. */}
       <span className={ROW_TRAILING_GUTTER_CLS}>
         <button
           type="button"
@@ -476,17 +462,11 @@ export function WorktreeRow({
   navigateToTab: (tabId: string, paneKey: string | null) => void
 }): React.JSX.Element {
   const hasResources = worktree.sessions.length > 0 || worktree.browsers.length > 0
-  // Why: synthetic buckets (orphan/unattributed) have no sidebar target to
-  // reveal. Real and SSH-resolved worktrees both qualify for navigation —
-  // navigateToWorktree handles the no-store-record case internally by
-  // bailing out of activateAndRevealWorktree if the worktree isn't known.
+  // Why: synthetic buckets (orphan/unattributed) have no sidebar target to reveal; real and SSH-resolved worktrees stay navigable.
   const isSynthetic =
     worktree.worktreeId === ORPHAN_WORKTREE_ID || worktree.repoId === UNATTRIBUTED_REPO_ID
   const isNavigable = !isSynthetic
-  // Why: Delete acts on a sidebar worktree record; without
-  // one (synthesized SSH rows whose worktreeId isn't in worktreeById, or
-  // synthetic buckets), or for the active worktree, we hide it but keep the
-  // row clickable for navigation.
+  // Why: Delete needs a sidebar worktree record; hidden for synthetic/SSH-only rows and the active worktree, but the row stays navigable.
   const showWorktreeActions =
     !isSynthetic && storeRecord !== null && worktree.worktreeId !== activeWorktreeId
   const isMainWorktree = storeRecord?.isMainWorktree ?? false
@@ -536,10 +516,7 @@ export function WorktreeRow({
           disabled={!isNavigable}
         >
           <span className="text-xs font-medium truncate">{rowLabel}</span>
-          {/* Why: chip is gated on the repo's SSH connectionId, not on
-              missing data. Warm-reattached local PTYs used to land here
-              with hasLocalSamples=false even though they're plainly
-              local. */}
+          {/* Why: gate the chip on SSH connectionId, not missing data — warm-reattached local PTYs land here with hasLocalSamples=false. */}
           {worktree.isRemote && (
             <span className="shrink-0 text-[9px] uppercase tracking-wide text-muted-foreground/70">
               {translate(
@@ -551,8 +528,7 @@ export function WorktreeRow({
         </button>
         <div className="flex items-center gap-2 shrink-0 pr-3">
           <div className="relative">
-            {/* Why: no-hover devices show the action overlay by default, so
-                the sparkline yields there just like it does during hover. */}
+            {/* Why: no-hover devices show the action overlay by default, so the sparkline yields there just like on hover. */}
             <span
               className={cn(
                 'block transition-opacity',
@@ -783,9 +759,7 @@ export function ResourceUsageStatusSegment({
       lastSeenScannedAt: workspaceSpaceScannedAt
     })
   )
-  // Why: tab titles can update on terminal keystrokes. The resource popover's
-  // merged tree needs them only while open, so closed status-bar badges should
-  // not subscribe to those high-churn maps.
+  // Why: tab titles churn on every keystroke; subscribe to those maps only while open so closed badges don't rerender.
   const runtimePaneTitlesByTabId = useAppStore((s) =>
     getResourceUsageRuntimePaneTitlesByTabId(s, open)
   )
@@ -793,13 +767,11 @@ export function ResourceUsageStatusSegment({
   const allWorktrees = useAppStore((s) => getResourceUsageAllWorktrees(s, open))
   const tabsByWorktree = useAppStore((s) => getResourceUsageTabsByWorktree(s, open))
   const browserTabsByWorktree = useAppStore((s) => getResourceUsageBrowserTabsByWorktree(s, open))
-  // Why: the closed trigger owns a scalar selector. Full binding maps stay
-  // behind open sentinels so unchanged counts do not rerender the segment.
+  // Why: full binding maps stay behind open sentinels so unchanged counts don't rerender the closed segment.
   const ptyIdsByTabId = useAppStore((s) => getResourceUsagePtyIdsByTabId(s, open))
   const terminalLayoutsByTabId = useAppStore((s) => getResourceUsageTerminalLayoutsByTabId(s, open))
   const resourceSnapshot = snapshot
-  // Why: ptyIdsByTabId intentionally tracks mounted/live panes only. Resource
-  // Manager also reads restored wake hints, but only for classification.
+  // Why: ptyIdsByTabId tracks mounted/live panes only; Resource Manager reads restored wake hints only for classification.
   const resourceSessionBindings = useMemo<ResourceSessionBindingInputs>(
     () => ({
       ptyIdsByTabId,
@@ -810,9 +782,7 @@ export function ResourceUsageStatusSegment({
     [ptyIdsByTabId, tabsByWorktree, terminalLayoutsByTabId, workspaceSessionReady]
   )
 
-  // Why: after a kill confirms and the session unmounts, focus would otherwise
-  // fall to <body>. We park a ref on the popover body so we can restore focus
-  // somewhere stable for keyboard users.
+  // Why: after a kill unmounts the session, focus would fall to <body>; park a ref on the popover body to restore it stably for keyboard users.
   const popoverBodyRef = useRef<HTMLDivElement | null>(null)
   const popoverBodyFocusFrameRef = useRef<number | null>(null)
   const mountedRef = useMountedRef()
@@ -862,8 +832,7 @@ export function ResourceUsageStatusSegment({
     }
   })
 
-  // Why: Space scans can finish after the user backs out of the full page or
-  // closes this popover; the status-bar trigger becomes the handoff point.
+  // Why: Space scans can finish after the user closes the full page/popover; the status-bar trigger becomes the handoff point.
   const nextSpaceScanSnapshot = resolveResourceUsageSpaceScanReady({
     snapshot: spaceScanSnapshot,
     open,
@@ -876,25 +845,19 @@ export function ResourceUsageStatusSegment({
     nextSpaceScanSnapshot.previousScanning !== spaceScanSnapshot.previousScanning ||
     nextSpaceScanSnapshot.lastSeenScannedAt !== spaceScanSnapshot.lastSeenScannedAt
   ) {
-    // Why: keep the scan transition render-time without mutating refs during
-    // render; React can safely retry this guarded state update before commit.
+    // Why: guarded render-time state update (no ref mutation during render); React can safely retry it before commit.
     setSpaceScanSnapshot(nextSpaceScanSnapshot)
   }
   const spaceScanReady = nextSpaceScanSnapshot.ready
 
-  // Poll memory when popover is open. Sessions are refreshed on open and after
-  // session actions; a closed status-bar badge must not globally inventory
-  // daemon PTYs because large preserved-session sets make that visible while
-  // typing.
+  // Poll memory only while open; a closed badge must not inventory daemon PTYs (large preserved-session sets stall typing).
   useEffect(() => {
     if (!open) {
       return
     }
     void fetchSnapshot()
     void refreshSessions()
-    // Why: only the memory snapshot keeps an interval while the popover is
-    // open. Session inventory is explicit-on-open/action because it can be
-    // expensive with many daemon-preserved terminals.
+    // Why: only memory polls on an interval; session inventory is explicit on open/action since it's expensive with many terminals.
     const memTimer = window.setInterval(() => {
       void fetchSnapshot()
     }, POLL_MS)
@@ -914,11 +877,7 @@ export function ResourceUsageStatusSegment({
     return map
   }, [repos])
 
-  // Why: drives the `· remote` chip predicate. A repo with a non-null
-  // connectionId is SSH-backed and its PTYs run on a remote host; that's
-  // the only honest signal for "remote." Building the map from the
-  // canonical store list avoids re-deriving remoteness from a missing
-  // memory sample.
+  // Why: non-null connectionId is the only honest "remote" signal (SSH PTYs run remote); build from the store, not a missing memory sample.
   const repoConnectionIdById = useMemo(() => {
     const map = new Map<string, string | null>()
     for (const repo of repos) {
@@ -927,8 +886,7 @@ export function ResourceUsageStatusSegment({
     return map
   }, [repos])
 
-  // Why: runtime-hosted repos never have local daemon samples or killable
-  // local sessions; this map drives their per-row exclusion in the merge.
+  // Why: runtime-hosted repos have no local daemon samples or killable sessions; this map drives their per-row exclusion in the merge.
   const repoRuntimeScopedById = useMemo(() => {
     const map = new Map<string, boolean>()
     for (const repo of repos) {
@@ -959,11 +917,7 @@ export function ResourceUsageStatusSegment({
     return count
   }, [allWorktrees, repoById])
 
-  // Why: skip the merge entirely when the popover is closed. The merged
-  // tree is only ever displayed inside <PopoverContent>; computing it on
-  // every store mutation (e.g. runtimePaneTitlesByTabId, which changes on
-  // every keystroke in any open terminal pane) was making the whole app
-  // feel laggy because the segment is always mounted in the status bar.
+  // Why: skip the merge when closed; the always-mounted segment recomputing on every keystroke-driven store mutation made the app laggy.
   const unifiedRepos = useMemo(
     () =>
       open
@@ -997,8 +951,7 @@ export function ResourceUsageStatusSegment({
     ]
   )
 
-  // Why: orphan detection needs daemon inventory. Keep it open-only so the
-  // closed badge never reintroduces a background global session scan.
+  // Why: orphan detection needs daemon inventory; keep it open-only so the closed badge never triggers a background global session scan.
   const orphanCount = useMemo(() => {
     if (!open || !workspaceSessionReady) {
       return 0
@@ -1020,15 +973,9 @@ export function ResourceUsageStatusSegment({
     }
   }, [resourceSnapshot])
 
-  // Why: memorySnapshotError is null both for "last fetch succeeded" and
-  // "never fetched". If session refresh fails before a memory snapshot exists,
-  // treat that as daemon-unreachable too.
+  // Why: memorySnapshotError null means "succeeded" OR "never fetched"; a sessions failure before any snapshot still counts as daemon-unreachable.
   const daemonUnreachable = sessionsError && (memorySnapshotError !== null || snapshot === null)
-  // Why: a partial failure where the sessions IPC fails but the snapshot
-  // IPC still works was silently invisible after the merge — the old
-  // SessionsTabPanel surfaced it as "Terminal sessions unavailable". Show
-  // a slim inline notice so the user understands why the session list is
-  // empty/stale even though the resource numbers look fine.
+  // Why: sessions IPC can fail while snapshot IPC works; flag it so the empty session list isn't mistaken for healthy.
   const sessionsOnlyError = sessionsError && memorySnapshotError === null
   const resourceManagerTooltipLines = getResourceManagerTooltipLines({
     memoryLabel: memBadgeLabel,
@@ -1064,9 +1011,7 @@ export function ResourceUsageStatusSegment({
     })
   }, [])
 
-  // Why: worktree navigation leaves the popover open so users can browse the
-  // tree without reopening it; bound terminal rows close explicitly because
-  // focus transfer is intentionally suppressed by onFocusOutside below.
+  // Why: keep popover open on worktree navigation so users can browse; onFocusOutside suppresses the bound-row focus transfer.
   const navigateToWorktree = useCallback((worktreeId: string): void => {
     if (worktreeId === ORPHAN_WORKTREE_ID || worktreeId.startsWith(`${UNATTRIBUTED_REPO_ID}::`)) {
       return
@@ -1099,16 +1044,10 @@ export function ResourceUsageStatusSegment({
 
   const handleKillSession = useCallback(
     (session: UnifiedSessionRow): void => {
-      // Why: orphan sessions have no tab in this Orca instance, so there's
-      // no "unsaved work in that pane" the user could lose by killing them.
-      // Skip the confirm dialog for orphans and fire the kill straight away
-      // (with optimistic removal) — same UX as a one-off kill from the
-      // bulk "Kill orphan terminals" button. Bound sessions still confirm.
+      // Why: orphan sessions have no tab here (no unsaved work to lose), so skip the confirm dialog; bound sessions still confirm.
       if (!session.bound) {
         setSessions((prev) => prev.filter((s) => s.id !== session.sessionId))
-        // Why: await the kill before refreshing — otherwise the optimistic
-        // removal races a refresh that re-reads the daemon list before the
-        // kill lands and re-adds the row that was just removed.
+        // Why: await the kill before refreshing, else the refresh re-reads the daemon list before the kill lands and re-adds the row.
         void (async () => {
           try {
             await window.api.pty.kill(session.sessionId)
@@ -1133,8 +1072,7 @@ export function ResourceUsageStatusSegment({
     if (orphans.length === 0) {
       return
     }
-    // Why: optimistic removal so rows disappear immediately instead of waiting
-    // for the next explicit daemon-side list refresh.
+    // Why: optimistic removal so rows disappear immediately instead of waiting for the next daemon-side list refresh.
     const orphanIds = new Set(orphans.map((s) => s.id))
     setSessions((prev) => prev.filter((s) => !orphanIds.has(s.id)))
     await Promise.allSettled(orphans.map((s) => window.api.pty.kill(s.id)))
@@ -1147,9 +1085,7 @@ export function ResourceUsageStatusSegment({
     }
     const target = killConfirm
     setKilling(true)
-    // Why: optimistic removal — the kill X was on the row that's about to be
-    // unmounted, so updating local state immediately avoids a flash where the
-    // dialog closes but the killed row waits for the next list refresh.
+    // Why: optimistic removal avoids a flash where the dialog closes but the killed row lingers until the next list refresh.
     setSessions((prev) => prev.filter((s) => s.id !== target.sessionId))
     try {
       await window.api.pty.kill(target.sessionId)
@@ -1159,9 +1095,7 @@ export function ResourceUsageStatusSegment({
       if (mountedRef.current) {
         setKilling(false)
         setKillConfirm(null)
-        // Why: after the killed row unmounts, focus would otherwise drop to
-        // <body>. Park focus on the popover body so keyboard users land back
-        // in the list rather than outside the popover.
+        // Why: killed row unmounts and focus would drop to <body>; park it on the popover body so keyboard users stay in the list.
         cancelPopoverBodyFocusFrame()
         if (popoverBodyRef.current) {
           popoverBodyFocusFrameRef.current = requestAnimationFrame(() => {
@@ -1266,11 +1200,7 @@ export function ResourceUsageStatusSegment({
         {...STATUS_BAR_CONTEXT_MENU_EXEMPT_PROPS}
         className="w-[26rem] max-w-[calc(100vw-2rem)] p-0"
         onOpenAutoFocus={(event) => event.preventDefault()}
-        // Why: clicking a terminal row activates a tab, which causes xterm
-        // to programmatically focus the terminal DOM node. Radix would
-        // interpret that as a focus-outside event and close the popover.
-        // Suppress focus-driven closes; the popover still closes on
-        // outside-click (onPointerDownOutside default) and Escape.
+        // Why: activating a tab focuses xterm's DOM node; Radix would read that as focus-outside and close. Outside-click and Escape still close.
         onFocusOutside={(event) => event.preventDefault()}
       >
         <div className="flex items-center justify-between gap-2 border-b border-border px-3 py-1.5">
@@ -1453,10 +1383,7 @@ export function ResourceUsageStatusSegment({
           </div>
         )}
 
-        {/* Why: pin body to a constant 420px so the popover surface doesn't
-            jump as worktrees expand/collapse or as sessions come and go. The
-            inner tree owns its own scroll. The footer renders below this
-            shell when orphan-bulk-kill is available. */}
+        {/* Why: fixed 420px height so the popover doesn't jump as worktrees expand/collapse or sessions change; inner tree owns its scroll. */}
         <div
           ref={setPopoverBodyNode}
           tabIndex={-1}
@@ -1517,9 +1444,7 @@ export function ResourceUsageStatusSegment({
                     )}
                   </button>
                 </div>
-                {/* Why: empty trailing gutter so the CPU/Memory header
-                    cells line up with the row cells; rows reserve the same
-                    width for the kill-X button. */}
+                {/* Why: empty trailing gutter keeps CPU/Memory header cells aligned with rows that reserve this width for the kill-X. */}
                 <span className={ROW_TRAILING_GUTTER_CLS} aria-hidden />
               </div>
             </div>
@@ -1611,11 +1536,7 @@ export function ResourceUsageStatusSegment({
 
         <WorkspaceSpaceCompactPanel onOpenFullPage={openSpaceResults} />
       </PopoverContent>
-      {/* Why: Radix Dialog must not be a descendant of PopoverContent — when
-          the popover unmounts (e.g. clicking outside, focus moving to the
-          confirm dialog), the Dialog unmounts mid-interaction and the kill
-          confirm flow disappears. Hoist it to a sibling so its lifetime is
-          independent of the popover. */}
+      {/* Why: hoisted to a sibling of PopoverContent — nested, the Dialog unmounts with the popover mid-interaction and the kill-confirm flow disappears. */}
       <Dialog
         open={killConfirm !== null}
         onOpenChange={(next) => {
diff --git a/src/renderer/src/components/status-bar/StatusBar.tsx b/src/renderer/src/components/status-bar/StatusBar.tsx
index 59e593ba0e8..ec626421357 100644
--- a/src/renderer/src/components/status-bar/StatusBar.tsx
+++ b/src/renderer/src/components/status-bar/StatusBar.tsx
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: the status bar keeps provider rendering,
-interaction menus, and compact-layout behavior together so the hover/click
-states stay consistent across Claude and Codex. */
+/* eslint-disable max-lines -- keeps provider rendering, menus, and compact-layout together for consistent Claude/Codex hover/click states. */
 import {
   AlertTriangle,
   Activity,
@@ -528,9 +526,7 @@ function getClaudeStatusAccountsFromSettings(
   }
 }
 
-// Why: with a Remote Orca Server active, accounts persisted in local
-// GlobalSettings describe this desktop, not the account owner; the snapshot
-// fetched from the server must win (#7973).
+// Why: with a Remote Orca Server, local GlobalSettings describe this desktop, not the owner — the server snapshot wins (#7973).
 export function resolveCodexStatusAccountState(
   settings: GlobalSettings | null | undefined,
   runtimeState: CodexRateLimitAccountsState
@@ -576,9 +572,7 @@ function CodexRestartStatusPrompt(): React.JSX.Element | null {
       <DropdownMenuSeparator />
       <div className="px-2 py-2">
         <div className="text-[11px] text-muted-foreground">
-          {/* Why: stale restart notices are tracked per PTY session, but the
-          bulk restart action operates per PTY-backed pane restart. Show
-          both counts so split panes do not make the number look wrong. */}
+          {/* Why: notices are per-PTY-session but restart is per-pane; show both counts so split panes don't look wrong. */}
           {staleCodexStatus.staleSessionCount === 1
             ? translate(
                 'auto.components.status.bar.StatusBar.605901a495',
@@ -721,8 +715,7 @@ function ClaudeSwitcherMenu({
   }, [])
 
   const activeRuntimeEnvironmentId = settings?.activeRuntimeEnvironmentId?.trim() || null
-  // Why: keyed on the owner id, not the settings object identity, so routine
-  // settings mutations don't re-run the remote snapshot round trip.
+  // Why: keyed on owner id, not settings identity, so routine settings mutations don't re-run the remote snapshot fetch.
   const loadAccounts = useCallback(async () => {
     const snapshot = await fetchProviderAccountsSnapshot({ activeRuntimeEnvironmentId })
     // Why: a failed Claude half is a substituted empty roster; keep prior state.
@@ -748,9 +741,7 @@ function ClaudeSwitcherMenu({
     }
   }, [])
 
-  // Why: inactive-account usage is needed only for the explicit switcher
-  // expansion, so fetch it on that event instead of one render later.
-  // Remote-owned accounts have no local inactive-usage cache to fill.
+  // Why: fetch inactive-account usage only on switcher expansion; remote-owned accounts have no local cache to fill.
   const handleAccountsExpandedToggle = useCallback((): void => {
     const nextExpanded = !accountsExpanded
     setAccountsExpanded(nextExpanded)
@@ -777,8 +768,7 @@ function ClaudeSwitcherMenu({
       if (mountedRef.current) {
         setAccounts(next)
       }
-      // Why: remote selections live on the server; local GlobalSettings
-      // account fields are untouched, so refetching them is pure churn.
+      // Why: remote selections live on the server; local GlobalSettings are untouched, so refetching is pure churn.
       if (!hasActiveRuntimeEnvironment) {
         await fetchSettings()
       }
@@ -945,10 +935,6 @@ function ClaudeSwitcherMenu({
   )
 }
 
-// ---------------------------------------------------------------------------
-// Mini progress bar (follows the selected usage percentage meaning, grey)
-// ---------------------------------------------------------------------------
-
 function MiniBar({
   usedPct,
   display
@@ -966,10 +952,7 @@ function MiniBar({
   )
 }
 
-// ---------------------------------------------------------------------------
-// Inline usage bars (compact bars for inactive accounts in the switcher)
-// ---------------------------------------------------------------------------
-
+// Compact usage bars for inactive accounts in the switcher.
 export function InlineUsageBars({
   limits,
   isFetching
@@ -980,16 +963,14 @@ export function InlineUsageBars({
   const display = normalizeUsagePercentageDisplay(
     useAppStore((state) => state.usagePercentageDisplay)
   )
-  // Why: tick the collapsed session countdown live (matches the popover) via one
-  // boundary-scheduled clock instead of only refreshing on the usage poll (#5399).
+  // Why: tick the session countdown live via one boundary-scheduled clock, not just the usage poll (#5399).
   const now = useResetCountdownClock([limits.session?.resetsAt])
   const usageWindows = [
     limits.session
       ? {
           key: 'session',
           used: clampUsedPercent(limits.session.usedPercent),
-          // Why: show the live reset countdown (matches the popover); '5h' window
-          // length only when resetsAt is unknown (#5399).
+          // Why: live reset countdown (matches popover); '5h' window length only when resetsAt is unknown (#5399).
           label: formatRateLimitWindowChipLabel(limits.session, now)
         }
       : null,
@@ -1098,10 +1079,6 @@ function InlineUsageSkeleton(): React.JSX.Element {
   )
 }
 
-// ---------------------------------------------------------------------------
-// Window label
-// ---------------------------------------------------------------------------
-
 function WindowLabel({
   w,
   label,
@@ -1118,12 +1095,7 @@ function WindowLabel({
   )
 }
 
-// ---------------------------------------------------------------------------
-// Provider segment
-// ---------------------------------------------------------------------------
-
-// Why: only Flash and the latest Pro are shown in the status bar —
-// the rest (Flash Lite, experimental) are secondary and would clutter the bar.
+// Why: show only Flash and latest Pro in the bar; the rest (Flash Lite, experimental) would clutter it.
 const STATUS_BAR_BUCKET_NAMES = new Set(['Flash', 'Pro', '1.5 Pro'])
 
 export function ProviderSegment({
@@ -1228,9 +1200,7 @@ export function ProviderSegment({
           label: translate('auto.components.status.bar.StatusBar.a79c64f87e', 'Fable')
         }
       : null,
-    // Why: monthly is chip-visible only when it's the sole window (Grok
-    // unified billing); providers with session/weekly data (OpenCode Go)
-    // keep monthly tooltip-only so the chip stays uncluttered.
+    // Why: show monthly on the chip only when it's the sole window (Grok); providers with session/weekly keep it tooltip-only.
     p.monthly && !p.session && !p.weekly
       ? {
           key: 'monthly',
@@ -1279,8 +1249,7 @@ function CodexSwitcherMenu({
   const [reauthenticatingAccountId, setReauthenticatingAccountId] = useState<string | null>(null)
   const mountedRef = useRef(true)
   const accountsExpandedRef = useRef(accountsExpanded)
-  // Why: Radix item selection is separate from the nested button click, so
-  // propagation stops alone do not prevent the row switch action.
+  // Why: Radix item-select is separate from the nested button click, so stopPropagation alone won't prevent the row switch.
   const suppressNextAccountSelectRef = useRef(false)
   const suppressNextAccountSelect = useCallback(() => {
     suppressNextAccountSelectRef.current = true
@@ -1324,8 +1293,7 @@ function CodexSwitcherMenu({
   const accountState = resolveCodexStatusAccountState(settings, accounts)
 
   const activeRuntimeEnvironmentId = settings?.activeRuntimeEnvironmentId?.trim() || null
-  // Why: keyed on the owner id, not the settings object identity, so routine
-  // settings mutations don't re-run the remote snapshot round trip.
+  // Why: keyed on owner id, not settings identity, so routine settings mutations don't re-run the remote snapshot fetch.
   const loadAccounts = useCallback(async () => {
     const snapshot = await fetchProviderAccountsSnapshot({ activeRuntimeEnvironmentId })
     // Why: a failed Codex half is a substituted empty roster; keep prior state.
@@ -1350,10 +1318,7 @@ function CodexSwitcherMenu({
   }, [accountsExpanded])
 
   useEffect(() => {
-    // Why: the status bar keeps its own lightweight account snapshot for the
-    // dropdown. Settings account actions mutate the main-process store outside
-    // this component, so we refresh when the persisted account roster changes
-    // or when the menu opens instead of leaving a stale account list mounted.
+    // Why: refresh our local account snapshot when the roster changes or the menu opens, since Settings mutates the store out-of-band.
     void loadAccounts().catch((error) => {
       console.error('Failed to load Codex accounts for status bar:', error)
     })
@@ -1378,8 +1343,7 @@ function CodexSwitcherMenu({
       if (mountedRef.current) {
         setAccounts(next)
       }
-      // Why: remote selections live on the server; local GlobalSettings
-      // account fields are untouched, so refetching them is pure churn.
+      // Why: remote selections live on the server; local GlobalSettings are untouched, so refetching is pure churn.
       if (!hasActiveRuntimeEnvironment) {
         await fetchSettings()
       }
@@ -1389,10 +1353,7 @@ function CodexSwitcherMenu({
           previousAccountLabel: getCodexAccountLabel(accountState, previousActiveAccountId),
           nextAccountLabel: getCodexAccountLabel(next, nextActiveAccountId)
         })
-        // Why: account switching can require a second explicit recovery step
-        // for live Codex terminals. Keeping the switcher open and collapsing
-        // back to the summary row lets the follow-up "restart open tabs"
-        // prompt appear in the same flow instead of feeling detached.
+        // Why: collapse to the summary row (not close) so the follow-up "restart open tabs" prompt appears in the same flow.
         if (mountedRef.current) {
           setAccountsExpanded(false)
         }
@@ -1499,9 +1460,7 @@ function CodexSwitcherMenu({
     const nextExpanded = !accountsExpanded
     setAccountsExpanded(nextExpanded)
     if (nextExpanded && !hasActiveRuntimeEnvironment) {
-      // Why: inactive-account usage is needed only for the explicit switcher
-      // expansion, so fetch it on that event instead of one render later.
-      // Remote-owned accounts have no local inactive-usage cache to fill.
+      // Why: fetch inactive-account usage only on switcher expansion; remote-owned accounts have no local cache to fill.
       void fetchInactiveCodexAccountUsage()
     }
   }, [accountsExpanded, fetchInactiveCodexAccountUsage, hasActiveRuntimeEnvironment])
@@ -1530,8 +1489,7 @@ function CodexSwitcherMenu({
     resetCreditCount !== null
       ? formatResetCreditExpiry(codex.rateLimitResetCredits?.nextExpiresAt, resetCreditCount)
       : null
-  // Why: reset credits redeem against the desktop's own Codex login; with a
-  // remote account owner the credit does not apply to the server's account.
+  // Why: reset credits redeem against the desktop's own Codex login, not a remote account owner's.
   const canRedeemReset =
     !hasActiveRuntimeEnvironment && resetCreditCount !== null && resetCreditCount > 0
 
@@ -1540,8 +1498,7 @@ function CodexSwitcherMenu({
       provider={codex}
       compact={compact}
       iconOnly={iconOnly}
-      // Why: Codex reset credits render beside the reset action below; showing
-      // them in the generic provider summary duplicates the same metadata.
+      // Why: reset credits render beside the reset action below; the generic summary would duplicate them.
       hidePanelResetCredits
       ariaLabel={translate(
         'auto.components.status.bar.StatusBar.ba55303942',
@@ -1672,8 +1629,7 @@ function CodexSwitcherMenu({
                   const inactiveUsage = target.id
                     ? inactiveCodexAccounts.find((a) => a.accountId === target.id)
                     : null
-                  // Why: sign-in spawns a local `codex login`; a remote-owned
-                  // account cannot be re-authenticated from this desktop.
+                  // Why: sign-in spawns a local `codex login`, so a remote-owned account can't be re-authed from this desktop.
                   const showSignInAction =
                     !hasActiveRuntimeEnvironment &&
                     !target.active &&
@@ -1686,10 +1642,7 @@ function CodexSwitcherMenu({
                     <DropdownMenuItem
                       key={`${selectedGroup.key}:${target.id ?? 'system'}`}
                       onSelect={(event) => {
-                        // Why: account switching may need an immediate follow-up
-                        // restart action for live Codex tabs. Prevent the menu from
-                        // auto-closing so that prompt can stay within the same
-                        // account-switcher interaction instead of jumping elsewhere.
+                        // Why: keep the menu open so the follow-up "restart live Codex tabs" prompt stays in this interaction.
                         event.preventDefault()
                         if (suppressNextAccountSelectRef.current) {
                           suppressNextAccountSelectRef.current = false
@@ -1845,8 +1798,7 @@ export function ProviderDetailsMenu({
             return
           }
           skipCloseAutoFocusRef.current = false
-          // Why: click-away should focus the clicked surface, especially xterm;
-          // Radix's default trigger restore steals that first click.
+          // Why: focus the clicked surface (esp. xterm) — Radix's default trigger restore steals that first click.
           event.preventDefault()
         }}
       >
@@ -1870,10 +1822,6 @@ export function ProviderDetailsMenu({
   )
 }
 
-// ---------------------------------------------------------------------------
-// StatusBar
-// ---------------------------------------------------------------------------
-
 const CLOSE_ALL_CONTEXT_MENUS_EVENT = 'orca-close-all-context-menus'
 
 function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Element | null {
@@ -1884,24 +1832,15 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
   const statusBarVisible = useAppStore((s) => s.statusBarVisible)
   const statusBarItems = useAppStore((s) => s.statusBarItems)
   const recordFeatureInteraction = useAppStore((s) => s.recordFeatureInteraction)
-  // Why: same launcher attention dot as the floating-button trigger, so an
-  // unacknowledged bell/agent-completion in the floating workspace is visible
-  // whichever trigger location the user picked (see FloatingTerminalToggleButton).
+  // Why: reuse the floating-button's unread dot so activity shows for either trigger location (see FloatingTerminalToggleButton).
   const hasFloatingUnread = useAppStore(selectFloatingWorkspaceHasUnread)
   const floatingTerminalEnabled = settings?.floatingTerminalEnabled === true
   const floatingTerminalTriggerLocation =
     settings?.floatingTerminalTriggerLocation ?? 'floating-button'
-  // Why: usage bars exist to surface CLI rate limits — showing one for an
-  // agent that isn't on the user's PATH is just noise (e.g. a fresh Ubuntu
-  // install showing "Gemini Usage" with no Gemini CLI installed). We gate
-  // the per-CLI bars on detection so the surface stays self-pruning, and
-  // re-show automatically once the agent appears on PATH.
+  // Why: gate per-CLI bars on PATH detection so an uninstalled agent isn't shown a noisy empty bar (auto re-shows when installed).
   const detectedAgentIds = useAppStore((s) => s.detectedAgentIds)
   const ensureDetectedAgents = useAppStore((s) => s.ensureDetectedAgents)
-  // Why: pet segment intentionally does NOT participate in statusBarItems
-  // (see design doc — gating with both the experimental flag and a
-  // statusBarItems checkbox would double-toggle the surface). It is driven
-  // purely by the experimentalPet settings flag.
+  // Why: pet segment is driven purely by experimentalPet, not statusBarItems, to avoid double-toggling the surface (see design doc).
   const petEnabled = useAppStore((s) => s.settings?.experimentalPet === true)
   const toggleStatusBarItem = useAppStore((s) => s.toggleStatusBarItem)
   const usageEmptyStateDismissed = useAppStore((s) => s.usageEmptyStateDismissed)
@@ -1927,10 +1866,7 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
     return () => window.removeEventListener(CLOSE_ALL_CONTEXT_MENUS_EVENT, closeMenu)
   }, [])
 
-  // Why: trigger PATH-based agent detection on mount so the per-CLI usage
-  // bars (Claude/Codex/Gemini) can hide themselves when the user doesn't
-  // have those CLIs installed. The slice deduplicates concurrent callers,
-  // so this is safe even if other surfaces also call it.
+  // Why: detect agents on mount so per-CLI usage bars hide when the CLI isn't installed; the slice dedupes concurrent callers.
   useEffect(() => {
     void ensureDetectedAgents()
   }, [ensureDetectedAgents])
@@ -1960,8 +1896,7 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
     }
     setIsRefreshing(true)
     try {
-      // Why: also re-run PATH detection so a freshly-installed CLI's bar
-      // appears (and a removed CLI's bar hides) without restarting Orca.
+      // Why: re-run PATH detection so a freshly-installed/removed CLI's bar appears/hides without restarting Orca.
       await Promise.all([refreshRateLimits(), refreshDetectedAgents()])
     } finally {
       if (mountedRef.current) {
@@ -1976,21 +1911,13 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
 
   const { claude, codex, gemini, opencodeGo, kimi, antigravity, minimax, grok } = rateLimits
 
-  // Why: a provider earns a bar from either a usable live snapshot or durable
-  // setup in Settings. The durable path keeps account switchers visible while
-  // usage snapshots hydrate, fail, or temporarily report unavailable.
-  // Detection-gating (see status-bar-agent-gating) additionally hides per-CLI
-  // bars when the agent isn't installed on PATH.
-  // Why: Antigravity usage has no separate persisted credential. A checked
-  // status item plus detected CLI is the durable signal that the user wants
-  // its usage slot visible while the first snapshot is still pending. The
-  // visibility module additionally requires geminiCliOAuthEnabled (already in
-  // settings) because the snapshot mirrors the Gemini fetch.
+  // Why: a bar is earned by a live snapshot or durable Settings setup; detection-gating hides per-CLI bars when the agent isn't on PATH.
+  // Why: Antigravity has no persisted credential, so a checked status item + detected CLI is the durable "show its slot" signal.
+  // Why: Antigravity visibility also requires geminiCliOAuthEnabled because its usage snapshot mirrors the Gemini fetch.
   const antigravityUsageConfigured =
     statusBarItems.includes('antigravity') &&
     isStatusBarItemAvailable('antigravity', detectedAgentIds)
-  // Why: thread non-GlobalSettings durability flags from renderer/main state so
-  // bars stay visible after a reload and between snapshot refreshes.
+  // Why: thread non-GlobalSettings durability flags so bars stay visible across reloads and snapshot refreshes.
   const usageSettings = {
     ...settings,
     antigravityUsageConfigured,
@@ -2024,15 +1951,13 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
     visibleAntigravity !== null &&
     statusBarItems.includes('antigravity') &&
     isStatusBarItemAvailable('antigravity', detectedAgentIds)
-  // Why: MiniMax is a cookie-auth provider, not a CLI on PATH, so detection-gating
-  // doesn't apply (same rationale as OpenCode Go below).
+  // Why: MiniMax is cookie-auth, not a CLI on PATH, so detection-gating doesn't apply.
   const showMiniMax = visibleMiniMax !== null && statusBarItems.includes('minimax')
   const showGrok =
     visibleGrok !== null &&
     statusBarItems.includes('grok') &&
     isStatusBarItemAvailable('grok', detectedAgentIds)
-  // Why: OpenCode Go is a web/cookie-auth provider, not a CLI on PATH, so
-  // detection-gating doesn't apply.
+  // Why: OpenCode Go is web/cookie-auth, not a CLI on PATH, so detection-gating doesn't apply.
   const visibleOpencodeGo = getVisibleUsageProvider('opencode-go', opencodeGo, usageSettings)
   const showOpencodeGo = visibleOpencodeGo !== null && statusBarItems.includes('opencode-go')
   const showSsh = statusBarItems.includes('ssh')
@@ -2040,9 +1965,7 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
   const showPorts = statusBarItems.includes('ports')
   const showFloatingTerminalToggle =
     floatingTerminalEnabled && floatingTerminalTriggerLocation === 'status-bar'
-  // Why: which usage-meter children actually render — excludes resource-usage
-  // and other non-meter status items so the % display change callout only
-  // opens when there is a real meter cluster to anchor to.
+  // Why: meter-only children (excludes resource-usage) so the % display callout anchors to a real meter cluster.
   const hasVisibleUsageMeters =
     showClaude ||
     showCodex ||
@@ -2053,16 +1976,12 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
     showMiniMax ||
     showGrok
   const anyVisible = hasVisibleUsageMeters || showResourceUsage
-  // Why: a brand-new user with no provider configured would otherwise see an
-  // empty left side of the status bar and wonder what's missing. Settings are
-  // included because managed accounts are durable even when live usage
-  // snapshots are still hydrating or unavailable after an update.
+  // Why: include Settings so durable managed accounts count — a configured user isn't shown the empty state while snapshots hydrate.
   const isEmptyUsageState = isUsageEmptyState(
     { claude, codex, gemini, opencodeGo, kimi, antigravity, minimax, grok },
     usageSettings
   )
-  // Why: the teaching CTA is a one-time nudge — once the user hides it, keep it
-  // hidden even after providers are disconnected again.
+  // Why: one-time nudge — once dismissed, stays hidden even if providers reconnect later.
   const showEmptyUsageCta = isEmptyUsageState && !usageEmptyStateDismissed
   const anyFetching =
     claude?.status === 'fetching' ||
@@ -2079,8 +1998,6 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
   const floatingTerminalActionLabel = floatingTerminalOpen
     ? 'Minimize Floating Workspace'
     : 'Show Floating Workspace'
-  // Why: only while the panel is closed; the dot reflects unacknowledged
-  // floating-workspace activity and clears via the shared unread paths.
   const showFloatingWorkspaceAttentionDot = !floatingTerminalOpen && hasFloatingUnread
 
   return (
@@ -2091,12 +2008,7 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
         if (!shouldOpenStatusBarContextMenu(event.target)) {
           return
         }
-        // Why: mirror the right-click pattern used across the app
-        // (WorktreeContextMenu, TerminalContextMenu, tab bar) — dispatch the
-        // global close event so peer menus dismiss, then place a hidden
-        // trigger at the cursor so the menu anchors there. This also lets a
-        // second right-click reposition the menu instead of leaving it where
-        // it first opened.
+        // Why: mirror the app-wide right-click pattern — close peer menus, then anchor a hidden trigger at the cursor so re-clicks reposition.
         event.preventDefault()
         window.dispatchEvent(new Event(CLOSE_ALL_CONTEXT_MENUS_EVENT))
         const bounds = event.currentTarget.getBoundingClientRect()
@@ -2110,8 +2022,7 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
             <StatusBarUsageEmptyCta />
           ) : null
         ) : (
-          // Why: one-time usage-display change callout anchors to this cluster so
-          // it sits next to the meters the user is confused by, not a global toast.
+          // Why: anchor the one-time %-display callout to this meter cluster, not a global toast.
           <UsagePercentageDisplayChangeNotice hasVisibleUsageMeters={hasVisibleUsageMeters}>
             {showClaude && (
               <ClaudeSwitcherMenu claude={visibleClaude} compact={compact} iconOnly={iconOnly} />
@@ -2242,8 +2153,7 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
                 >
                   <PanelsTopLeft className="size-3.5" />
                   {showFloatingWorkspaceAttentionDot ? (
-                    // Why: amber = Orca's "needs attention" convention; ring
-                    // matches the button fill so the dot reads on the icon.
+                    // Why: amber = Orca's "needs attention" convention; ring matches the fill so the dot reads on the icon.
                     <span
                       aria-hidden
                       data-floating-terminal-attention
diff --git a/src/renderer/src/components/tab-bar/SortableTab.tsx b/src/renderer/src/components/tab-bar/SortableTab.tsx
index 0b694fb6fd4..34f11a451fb 100644
--- a/src/renderer/src/components/tab-bar/SortableTab.tsx
+++ b/src/renderer/src/components/tab-bar/SortableTab.tsx
@@ -50,8 +50,7 @@ type SortableTabProps = {
   dragData: TabDragItemData
   dropIndicator?: DropIndicator
   includeTopTabBorder?: boolean
-  /** True when this tab is an agent terminal that can switch to the native chat
-   *  view. Surfaces the "Switch view" item in the tab context menu. */
+  /** True when this agent terminal can switch to native chat view; surfaces the "Switch view" context-menu item. */
   canToggleViewMode?: boolean
   /** True when the tab is currently showing the native chat view. */
   isChatView?: boolean
@@ -85,17 +84,13 @@ export default function SortableTab({
   isChatView = false,
   onToggleViewMode
 }: SortableTabProps): React.JSX.Element {
-  // Why: agent-completion unread is pane-keyed and exists even when the
-  // experimental generic terminal-attention setting is off. Collapse both
-  // sources to one per-tab primitive so unrelated tabs do not re-render.
+  // Why: agent-completion unread exists even with terminal-attention off; collapse both sources to one primitive so unrelated tabs don't re-render.
   const hasUnreadActivity = useAppStore(
     (s) =>
       s.unreadTerminalTabs[tab.id] === true ||
       hasUnreadAgentCompletionForTerminalTab(s.unreadAgentCompletionPanes, tab.id)
   )
-  // Why: the resolver returns a WorktreeStatus primitive, so unrelated agent
-  // updates can't repaint this tab. The per-tab pane bucketing it reads is
-  // memoized once per store snapshot, so this stays O(1) per tab per write.
+  // Why: resolver returns a primitive so unrelated agent updates can't repaint this tab (pane bucketing memoized per snapshot).
   const activityStatus = useAppStore((s) =>
     resolveTerminalTabActivityStatus({
       tab,
@@ -109,54 +104,37 @@ export default function SortableTab({
   const renamingTabId = useAppStore((s) => s.renamingTabId)
   const setRenamingTabId = useAppStore((s) => s.setRenamingTabId)
 
-  // Why: createTab stamps the shell used at creation time, so changing the
-  // default shell later does not repaint existing tabs as a different shell.
-  // Older persisted tabs without this field fall back to the generic icon.
+  // Why: shellOverride is stamped at create time, so changing the default shell later won't repaint existing tabs.
   const shellForIcon = tab.shellOverride
 
-  // Why: hook status and title evidence make the tab icon reflect the
-  // coding harness currently running in the pane, not just the launch command.
+  // Why: use hook status + title evidence so the icon reflects the harness running now, not just the launch command.
   const tabAgent = useTabAgent(tab)
 
-  // Why: when a provider icon is already shown, stripping the agent's own
-  // leading status glyph keeps the tab from presenting two icons for one agent.
+  // Why: with a provider icon shown, strip the agent's own leading glyph so the tab doesn't show two icons for one agent.
   const displayTitle =
     tab.customTitle ?? (tabAgent ? stripLeadingAgentTitleDecoration(tab.title) : tab.title)
 
   const { attributes, listeners, setNodeRef } = useSortable({
     id: tab.id,
-    // Why: carry the resolved agent into the drag overlay so dragged tabs keep
-    // the same provider glyph as the tab strip without another store lookup.
+    // Why: carry the resolved agent into the drag overlay so dragged tabs keep the same glyph without another store lookup.
     data: { ...dragData, agent: tabAgent }
   })
 
-  // Why: intentionally no transform/transition/opacity here. The PR's
-  // design is that tabs stay visually anchored during a drag — only the
-  // blue insertion bar moves. Siblings also don't shift (see
-  // SortableContext in TabBar.tsx, which omits a strategy for that reason).
+  // Why: no transform/transition/opacity so tabs stay anchored during drag, only the insertion bar moves (see TabBar.tsx).
   const [menuOpen, setMenuOpen] = useState(false)
   const [menuPoint, setMenuPoint] = useState({ x: 0, y: 0 })
   const [isEditing, setIsEditing] = useState(false)
-  // Why: a live working/needs-input state is newer and more specific than an
-  // unread event from the prior turn. It owns the icon until the turn ends;
-  // the unread completion bell then returns if the tab is still unvisited.
+  // Why: a live working/needs-input state is newer than a prior-turn unread, so it owns the icon until the turn ends.
   const showUnreadActivity =
     hasUnreadActivity && !isEditing && !isTerminalTabActivityLive(activityStatus)
   const [renameValue, setRenameValue] = useState('')
   const renameFocusFrameRef = useRef<number | null>(null)
-  // Why: React's synthetic onBlur fires during the Input's unmount when isEditing flips
-  // to false. Without this guard, pressing Escape (or committing via Enter) would cause
-  // the blur handler to run commitRename a second time and overwrite the title with the
-  // uncommitted edits the user just discarded. This ref lets cancelRename/commitRename
-  // mark the rename as already resolved so the unmount-driven blur is a no-op.
+  // Why: onBlur fires during Input unmount; mark rename resolved so it can't re-commit and overwrite discarded edits.
   const committedOrCancelledRef = useRef(false)
 
   const handleRenameOpen = useCallback(() => {
     committedOrCancelledRef.current = false
-    // Why: snapshot the current title once on open. If the underlying tab.title
-    // changes mid-edit (e.g., a shell writes a new title via OSC escape), we
-    // intentionally do NOT refresh renameValue — the user's in-progress edit
-    // takes precedence so their keystrokes are never silently overwritten.
+    // Why: snapshot title once; don't refresh if tab.title changes mid-edit (e.g. OSC) so the user's edits aren't overwritten.
     setRenameValue(tab.customTitle ?? tab.title)
     setIsEditing(true)
   }, [tab.customTitle, tab.title])
@@ -184,8 +162,7 @@ export default function SortableTab({
     if (!input) {
       return
     }
-    // Why: defer past Radix menu teardown/focus restore while still keying off
-    // input mount only; terminal title updates must not re-select in-progress text.
+    // Why: defer past Radix menu teardown/focus restore; key off input mount so title updates don't re-select edited text.
     renameFocusFrameRef.current = requestAnimationFrame(() => {
       renameFocusFrameRef.current = null
       input.focus()
@@ -193,9 +170,7 @@ export default function SortableTab({
     })
   }, [])
 
-  // Why: the tab.rename shortcut can't reach this component's local editing
-  // state directly, so it sets renamingTabId in the store; the matching tab
-  // opens its editor and immediately clears the flag so it fires once.
+  // Why: the tab.rename shortcut routes through store renamingTabId; open the editor and clear it so it fires once.
   useEffect(() => {
     if (renamingTabId !== tab.id) {
       return
@@ -210,11 +185,7 @@ export default function SortableTab({
     return () => window.removeEventListener(CLOSE_ALL_CONTEXT_MENUS_EVENT, closeMenu)
   }, [])
 
-  // Why: Electron <webview> elements run in a separate process, so clicking
-  // inside one never dispatches a pointerdown on the renderer document. Radix
-  // DropdownMenu relies on document pointerdown for outside-click detection,
-  // so it misses webview clicks. Listening for window blur catches the moment
-  // focus leaves the renderer (including into a webview).
+  // Why: webview clicks miss the renderer pointerdown Radix uses for outside-click, so dismiss on window blur instead.
   useEffect(() => {
     if (!menuOpen) {
       return
@@ -224,18 +195,12 @@ export default function SortableTab({
     return () => window.removeEventListener('blur', dismiss)
   }, [menuOpen])
 
-  // Why: while editing, suppress dnd-kit drag listeners and tab-activation/double-click
-  // handlers so typing/clicking inside the inline input doesn't start a drag, re-open the
-  // editor, or steal focus away from the input. We still spread `attributes` unconditionally
-  // so dnd-kit's a11y attributes (aria-roledescription, etc.) remain on the element — only
-  // the pointer listeners are gated so a drag can't start while typing.
+  // Why: while editing, drop drag listeners so typing can't start a drag; attributes stay spread to keep dnd-kit a11y.
   const dragListeners = isEditing ? undefined : listeners
   const handleActivate = useCallback(() => {
     onActivate(tab.id)
   }, [onActivate, tab.id])
-  // Why: defer activation to pointer-up so pressing a tab to drag it (reorder /
-  // move into another pane / split) does not switch the active tab or steal
-  // terminal focus mid-gesture. See tab-strip-pointer-activation.
+  // Why: defer activation to pointer-up so a drag doesn't switch tabs or steal focus mid-gesture (tab-strip-pointer-activation).
   const { onPointerDown: onTabPointerDown } = useTabStripPointerActivation({
     onActivate: handleActivate,
     disabled: isEditing
@@ -249,22 +214,12 @@ export default function SortableTab({
       data-tab-id={tab.id}
       data-tab-title={tabTitle}
       data-pinned={isPinned ? 'true' : 'false'}
-      // Why: expose the active/inactive flag as a DOM attribute so E2E specs
-      // can assert on user-observable selection state without reading the
-      // Zustand store. A store-only "is this tab active?" round-trip would
-      // pass even if the tab-bar render path had silently broken (the same
-      // tautology that let PR #1186's render crash ship past E2E in #1193).
+      // Why: DOM attribute lets E2E assert real selection state; a store-only check would miss render breaks (PR #1186 shipped in #1193).
       data-active={isActive ? 'true' : 'false'}
       data-agent-activity-status={activityStatus}
       {...attributes}
       {...dragListeners}
-      // Why: on unread activity, tint the whole tab with a subtle amber
-      // wash so the signal is visible at a glance even when the small
-      // bell icon is easy to miss in a long tab bar. Active tabs keep
-      // their existing highlight — the amber wash layers on top so the
-      // tab still reads as "selected + has activity". The wash is
-      // rendered as an absolutely-positioned child below so the ::after
-      // pseudo-element stays free for the drop indicator.
+      // Why: subtle amber wash flags unread activity at a glance, layered over the active highlight so it still reads selected.
       className={`group relative flex items-center h-full px-1.5 text-xs cursor-pointer select-none outline-none focus:outline-none focus-visible:outline-none ${getTabStripBorderClasses(hasTabsToRight, { includeTopBorder: includeTopTabBorder })} ${getDropIndicatorClasses(dropIndicator ?? null)} ${getTabRootStateClasses(isActive)}`}
       onDoubleClick={(e) => {
         if (isEditing) {
@@ -280,10 +235,7 @@ export default function SortableTab({
         )
       }}
       onMouseDown={(e) => {
-        // Why: prevent default browser middle-click behavior (auto-scroll)
-        // but do NOT close here — closing removes the element before mouseup,
-        // causing the mouseup to fall through to the terminal and trigger
-        // an X11 primary selection paste on Linux.
+        // Why: block middle-click auto-scroll; don't close here — removing the element pre-mouseup triggers a Linux X11 paste.
         if (e.button === 1) {
           e.preventDefault()
         }
@@ -305,8 +257,7 @@ export default function SortableTab({
     >
       {isActive && <span className={ACTIVE_TAB_INDICATOR_CLASSES} aria-hidden />}
       {showUnreadActivity && (
-        // Why: a real DOM child leaves both drop-indicator pseudo-elements
-        // available and keeps pointer events reaching the tab beneath it.
+        // Why: a real DOM child keeps both drop-indicator pseudo-elements free and pointer events reaching the tab.
         <span aria-hidden className="pointer-events-none absolute inset-0 bg-amber-500/10" />
       )}
       <TerminalTabLeadingIcon
@@ -332,8 +283,7 @@ export default function SortableTab({
           onChange={(event) => setRenameValue(event.target.value)}
           onBlur={commitRename}
           onKeyDown={(event) => {
-            // Why: an Enter that only confirms a CJK IME candidate must not
-            // commit the rename; wait for a non-composition Enter.
+            // Why: an Enter confirming a CJK IME candidate must not commit the rename; wait for a non-composition Enter.
             if (isImeCompositionKeyDown(event)) {
               return
             }
@@ -345,15 +295,10 @@ export default function SortableTab({
               cancelRename()
             }
           }}
-          // Why: stop pointer/mouse events from bubbling to the outer div, which
-          // would otherwise trigger tab activation or start a dnd-kit drag while
-          // the user is trying to click inside the input.
+          // Why: stop bubbling so clicking inside the input doesn't activate the tab or start a dnd-kit drag.
           onPointerDown={(event) => event.stopPropagation()}
           onMouseDown={(event) => {
-            // Why: stop propagation so the outer tab's activation/drag handlers
-            // don't fire on clicks inside the input. Also preventDefault on middle
-            // click (button 1) to block Linux X11 primary-selection paste into the
-            // rename field, matching the outer tab's behavior.
+            // Why: stopPropagation avoids outer tab activation/drag; preventDefault on middle-click blocks Linux X11 paste.
             event.stopPropagation()
             if (event.button === 1) {
               event.preventDefault()
@@ -362,10 +307,7 @@ export default function SortableTab({
           onClick={(event) => event.stopPropagation()}
           onDoubleClick={(event) => event.stopPropagation()}
           onAuxClick={(event) => event.stopPropagation()}
-          // Why: the base Input applies w-full min-w-0, which lets flex
-          // shrink it to ~0 when many tabs compete for horizontal space.
-          // Force a minimum width that matches the normal title box so the
-          // rename input stays usable even when the tab bar is saturated.
+          // Why: base Input's min-w-0 lets flex shrink it to ~0 in a saturated tab bar; force a usable minimum width.
           className="mr-1 h-5 min-w-[72px] flex-1 px-1 py-0 text-xs"
           spellCheck={false}
         />
@@ -418,10 +360,7 @@ export default function SortableTab({
                   ? 'text-muted-foreground hover:text-foreground hover:bg-muted focus-visible:text-foreground focus-visible:bg-muted'
                   : 'text-transparent group-hover:text-muted-foreground hover:!text-foreground hover:!bg-muted focus-visible:!text-foreground focus-visible:!bg-muted'
               }`}
-              // Why: per-tab close affordance needs a stable accessible name so
-              // E2E specs can drive the same path a user takes (hover, then X)
-              // instead of bypassing the render layer by calling closeTab() on
-              // the store. A store-only assertion would miss an unmounted button.
+              // Why: stable accessible name lets E2E drive the real close path (hover, then X) instead of calling the store.
               aria-label={translate(
                 'auto.components.tab.bar.SortableTab.6df69d9388',
                 'Close tab {{value0}}',
diff --git a/src/renderer/src/components/tab-bar/TabBar.tsx b/src/renderer/src/components/tab-bar/TabBar.tsx
index 7a7cc8f0c21..efc17089094 100644
--- a/src/renderer/src/components/tab-bar/TabBar.tsx
+++ b/src/renderer/src/components/tab-bar/TabBar.tsx
@@ -1,8 +1,4 @@
-/* oxlint-disable max-lines -- Why: rendering the drop-indicator prop on each
- * of three distinct tab components (terminal, browser, editor) adds 3 lines
- * to a file that was already ~398 code lines on main. The per-type render
- * branches share little beyond drag data, so consolidating them would cost
- * more clarity than the ~5 lines of bloat is worth. */
+/* oxlint-disable max-lines -- Why: per-type tab render branches (terminal/browser/editor) share little beyond drag data; consolidating costs more clarity than the ~5 lines it saves. */
 import React, { useEffect, useMemo, useRef, useState } from 'react'
 import { useShallow } from 'zustand/react/shallow'
 import { SortableContext } from '@dnd-kit/sortable'
@@ -311,13 +307,11 @@ function TabBarInner({
   const repos = useAppStore((s) => s.repos)
   const settings = useAppStore((s) => s.settings)
   const worktreesByRepo = useAppStore((s) => s.worktreesByRepo)
-  // Why: probe Windows shell capabilities on the host that owns this worktree, so
-  // the offered shells match the host that actually runs the terminal.
+  // Why: use the worktree's owning host so offered Windows shells match the host that actually runs the terminal.
   const activeRuntimeEnvironmentId = useAppStore(
     (s) => getRuntimeEnvironmentIdForWorktree(s, worktreeId)?.trim() || null
   )
-  // Why: retained tab strips rerun selectors on every store write; reuse the
-  // canonical worktree/repo indexes instead of flattening both slices here.
+  // Why: retained tab strips rerun selectors on every store write; reuse canonical indexes, don't flatten both slices here.
   const worktreeConnectionId = useAppStore(
     (s) => getConnectionIdFromState(s, worktreeId)?.trim() || null
   )
@@ -452,13 +446,9 @@ function TabBarInner({
     [unifiedTabs]
   )
 
-  // Why: gate the tab long-press view-mode toggle to the agent in its active leaf.
-  // Tab-wide launch/title hints are safe only before the terminal is split.
+  // Why: tab-wide launch/title hints are safe only before split; gate the view-mode toggle to the active leaf's agent.
   const toggleTabViewMode = useAppStore((s) => s.toggleTabViewMode)
-  // Why: the strip only needs each tab's stable agent identity, but the whole
-  // agentStatusByPaneKey map churns on every working↔idle transition app-wide.
-  // Select a shallow-stable { tabId: agentType } projection so the strip
-  // re-renders only when a tab gains/loses/changes its agent, not on status flips.
+  // Why: agentStatusByPaneKey churns on every status flip; project {tabId:agentType} to re-render only on agent identity change.
   const tabAgentTypesByTabId = useAppStore(
     useShallow((s) =>
       selectTabAgentTypesByTabId(s.agentStatusByPaneKey ?? {}, s.terminalLayoutsByTabId)
@@ -472,11 +462,7 @@ function TabBarInner({
     isNativeChatTranscriptLocalReadable(getConnectionIdFromState(s, worktreeId))
   )
 
-  // Why: Electron <webview> elements run in a separate process, so clicking
-  // inside one never dispatches a pointerdown on the renderer document.
-  // Radix DropdownMenu relies on document pointerdown to detect outside
-  // clicks, so it misses webview clicks entirely. Listening for window blur
-  // catches the moment focus leaves the renderer (including into a webview).
+  // Why: <webview> clicks are out-of-process, so Radix's document-pointerdown outside-click check misses them; use window blur.
   const [newTabMenuOpen, setNewTabMenuOpen] = useState(false)
   const [createMenuQuery, setCreateMenuQuery] = useState('')
   const pendingNewTabMenuFocusRef = useRef<(() => void) | null>(null)
@@ -520,9 +506,7 @@ function TabBarInner({
   const queueNewActiveTerminalFocusAfterNewTabMenuClose = (): void => {
     const previousActiveTabId = useAppStore.getState().activeTabId
     pendingNewTabMenuFocusRef.current = () => {
-      // Why: paired web/SSH runtime tab creation is async; wait for the host
-      // snapshot to publish the newly active terminal instead of focusing the
-      // pre-existing active tab.
+      // Why: paired web/SSH tab creation is async; await the host snapshot's new terminal instead of the pre-existing active tab.
       focusNewActiveTerminalWhenReady(
         previousActiveTabId,
         Date.now() + NEW_TAB_MENU_TERMINAL_FOCUS_TIMEOUT_MS
@@ -684,9 +668,7 @@ function TabBarInner({
       if (node !== null) {
         return
       }
-      // Why: the delayed focus handoff is scoped to this tab bar instance.
-      // A root ref cleanup cancels it at the DOM owner boundary without an
-      // otherwise cleanup-only React Effect.
+      // Why: cancel the delayed focus handoff via this root ref cleanup, avoiding an otherwise cleanup-only React Effect.
       clearPendingNewTabMenuFocusAnimation()
       clearPendingNewTabMenuFocusRetry()
     }
@@ -701,11 +683,7 @@ function TabBarInner({
           <DropdownMenuItem
             key={entry.shell}
             onSelect={() => {
-              // Why: the top-level Windows shell menu models shell
-              // categories, not concrete executables. When the user
-              // picked PowerShell 7+ in advanced settings, launching the
-              // "PowerShell" menu item must preserve that implementation
-              // instead of forcing inbox powershell.exe.
+              // Why: menu models shell categories not executables; preserve the user's chosen PowerShell 7+ over inbox powershell.exe.
               queueNewActiveTerminalFocusAfterNewTabMenuClose()
               onNewTerminalWithShell(
                 resolveWindowsShellLaunchTarget(
@@ -1030,11 +1008,7 @@ function TabBarInner({
     <div
       ref={clearPendingNewTabMenuFocusOnUnmount}
       className="flex items-stretch h-full overflow-hidden flex-1 min-w-0"
-      // Why: only drops aimed at the top tab/session strip should open files in
-      // Orca's editor. Terminal-pane drops need to keep inserting file paths
-      // into the active coding CLI, so preload routes native OS drops based on
-      // this explicit surface marker instead of treating the whole app as an
-      // editor drop zone.
+      // Why: preload routes native OS drops by this marker — only the tab strip opens files in the editor, not terminal panes.
       data-native-file-drop-target="editor"
     >
       {tabStripOverflowState.hasOverflow ? (
@@ -1065,27 +1039,16 @@ function TabBarInner({
           </TooltipContent>
         </Tooltip>
       ) : null}
-      {/* Why: no strategy means dnd-kit does not animate siblings aside for
-          the active tab. Combined with dropping transform/transition on the
-          dragged tab (see SortableTab etc.), this keeps every tab visually
-          anchored during a drag so only the blue insertion bar moves. */}
+      {/* Why: no strategy stops dnd-kit animating siblings, so tabs stay anchored during drag; only the insertion bar moves. */}
       <SortableContext items={sortableIds}>
-        {/* Why: no-drag lets tab interactions work inside the titlebar's drag
-            region. The outer container inherits drag so empty space after the
-            "+" button remains window-draggable. */}
+        {/* Why: no-drag lets tab interactions work inside the titlebar's drag region (outer container stays window-draggable). */}
         <div
           className="relative flex min-h-0 min-w-0 max-w-full flex-[0_1_auto]"
           style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
         >
           <div
             ref={tabStripRef}
-            // Why: only `border-r` on the strip — the trailing edge must stay
-            // visible even when tabs overflow-scroll past the last tab. The
-            // left edge is instead painted by the FIRST tab's own `border-l`
-            // (see per-tab components) so its rendering is identical to every
-            // between-tab separator. A strip-level `border-l` would render at
-            // a different box than the tab's own `border-t`, producing a
-            // heavier-looking L-corner at the leftmost tab when inactive.
+            // Why: only `border-r` here — a strip-level `border-l` would render a heavier L-corner than the first tab's own `border-l`.
             className={[
               'terminal-tab-strip flex h-full min-w-0 max-w-full flex-1 items-stretch overflow-x-auto overflow-y-hidden border-r border-border/70',
               getTabStripScrollMaskClassName(tabStripOverflowState)
@@ -1115,14 +1078,11 @@ function TabBarInner({
                   )
                 }
                 const unifiedTabForItem = unifiedTabByVisibleId.get(item.id)
-                // Carry the agent *identity* (not just "an agent exists") so the
-                // native-chat gate can reject unsupported agents like Grok.
+                // Carry the agent *identity* (not just "an agent exists") so the native-chat gate can reject agents like Grok.
                 const resolvedAgent =
                   resolveCommittedTitleAgentType(unifiedTabForItem?.label ?? '') ??
                   resolveCommittedTitleAgentType(terminalTab.title)
-                // Key the live-agent lookup by the backing terminal tab id —
-                // agent-status pane keys are `${terminalTab.id}:${leafId}`, and
-                // the unified tab id can differ from it.
+                // Key the live-agent lookup by the backing terminal tab id: agent-status pane keys use it, not the unified tab id.
                 const detectedAgent = tabAgentTypesByTabId[terminalTab.id] ?? null
                 const tabWideFallbackSafe =
                   nativeChatTabWideFallbackUnsafeTabsById[terminalTab.id] !== true
@@ -1280,9 +1240,7 @@ function TabBarInner({
       <DropdownMenu
         open={newTabMenuOpen}
         onOpenChange={setNewTabMenuOpen}
-        // Why: this menu can stay open after the Mobile Emulator "Hide" action,
-        // which shows a toast with a re-enable link; modal would disable body
-        // pointer events and make that toast (and other outside UI) unclickable.
+        // Why: modal would disable body pointer events, making the Mobile Emulator "Hide" re-enable toast unclickable.
         modal={false}
       >
         <DropdownMenuTrigger asChild>
@@ -1290,10 +1248,7 @@ function TabBarInner({
             className="ml-2 my-auto flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-muted-foreground hover:bg-accent/50 hover:text-foreground"
             style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
             title={translate('auto.components.tab.bar.TabBar.b1a132357f', 'New tab')}
-            // Why: aria-label matches the tooltip so E2E can locate the "+"
-            // affordance via getByRole('button', { name: 'New tab' }). The
-            // store-only createTab() round-trip that preceded this was a
-            // tautology — it would pass even if the + button had been deleted.
+            // Why: aria-label matches the tooltip so E2E can locate the "+" via getByRole('button', { name: 'New tab' }).
             aria-label={translate('auto.components.tab.bar.TabBar.b1a132357f', 'New tab')}
           >
             <Plus className="w-3.5 h-3.5" />
@@ -1304,9 +1259,7 @@ function TabBarInner({
           sideOffset={6}
           className="w-72 max-w-[calc(100vw-1rem)] rounded-[11px] border-border/80 p-1 shadow-[0_16px_36px_rgba(0,0,0,0.24)]"
           onCloseAutoFocus={(e) => {
-            // Why: terminal-producing menu actions activate a freshly-mounted
-            // xterm. Radix's default focus restore sends focus back to the "+"
-            // trigger after close, stealing it from the new terminal.
+            // Why: Radix restores focus to the "+" trigger on close, stealing it from the freshly-mounted terminal.
             e.preventDefault()
             runPendingNewTabMenuFocusAfterClose()
           }}
diff --git a/src/renderer/src/components/tab-group/TabGroupPanel.tsx b/src/renderer/src/components/tab-group/TabGroupPanel.tsx
index e6f237c9bc3..a9f7f2ac507 100644
--- a/src/renderer/src/components/tab-group/TabGroupPanel.tsx
+++ b/src/renderer/src/components/tab-group/TabGroupPanel.tsx
@@ -67,18 +67,9 @@ export default function TabGroupPanel({
     },
     disabled: !isTabDragActive
   })
-  // Why: browser and terminal panes for this worktree are rendered once at the worktree
-  // level (BrowserPaneOverlayLayer) and positioned over the owning group's
-  // body via CSS anchor positioning. Tagging this body with a per-group
-  // `anchor-name` lets the overlay reference it via `position-anchor`;
-  // moving a tab between groups only swaps which anchor-name the overlay
-  // targets. Browsers avoid `<webview>` reloads; terminals avoid remounting
-  // xterm and losing alt-screen TUI state.
+  // Why: per-group anchor-name lets the worktree-level overlay position panes via CSS anchor positioning, so moving a tab between groups re-targets the anchor instead of remounting xterm (loses alt-screen TUI state) or reloading `<webview>`.
   const bodyAnchorName = tabGroupBodyAnchorName(groupId)
-  // Why: memoize the style object so the literal isn't recreated on every
-  // render. A fresh object every render would make the body `<div>` appear
-  // to have a new `style` prop on every parent re-render, which defeats any
-  // downstream memoization keyed on referential equality.
+  // Why: memoize so a fresh style object each render doesn't break downstream memoization keyed on referential equality.
   const bodyAnchorStyle = useMemo(
     () => ({ anchorName: bodyAnchorName }) as React.CSSProperties,
     [bodyAnchorName]
@@ -98,15 +89,11 @@ export default function TabGroupPanel({
           commands.closeItem(item.id)
           return
         }
-        // Why: agent quick-launch can briefly desync unified/runtime tab ids
-        // before the host snapshot lands; still route close through the shared
-        // terminal close helper instead of no-op'ing.
+        // Why: agent quick-launch can briefly desync unified/runtime tab ids before the host snapshot lands, so still route close through the shared helper.
         closeTerminalTab(terminalId)
       }}
       onCloseOthers={(visibleId) => {
-        // Why: TabBar emits this with the entityId for terminals/browsers and
-        // the unifiedTabId for editors (see TabBar's per-type wiring). Match
-        // both so the menu works on every tab kind, not just terminals.
+        // Why: TabBar emits entityId for terminals/browsers but unifiedTabId for editors; match both so the menu works on every tab kind.
         const item = resolveGroupTabFromVisibleId(model.groupTabs, visibleId)
         if (item) {
           commands.closeOthers(item.id)
@@ -187,32 +174,17 @@ export default function TabGroupPanel({
 
   const menuButtonClassName =
     'my-auto flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-muted-foreground hover:bg-accent/50 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent'
-  // Why: focused-only — quick commands and Close split pane stay with the
-  // active pane so unfocused strips stay compact.
+  // Why: focused-only so quick commands and Close split pane stay with the active pane and unfocused strips stay compact.
   const focusedActionChromeClassName = `flex shrink-0 items-center gap-0.5 overflow-hidden transition-[opacity] duration-150 ${
     isFocused ? 'ml-1.5 pointer-events-auto opacity-100' : 'pointer-events-none opacity-0 w-0'
   }`
   return (
     <div
-      // Why: vertical borders are always `border-border` so the focus
-      // highlight doesn't introduce a near-white strip next to the split
-      // resize handle (--accent is ~#f5f5f5 in light mode, which reads as a
-      // visible gap between the dragger and the tab row). Only the bottom
-      // border changes color on focus, which is enough to cue the focused
-      // group without painting a bright line along the vertical edges.
-      // Why: unfocused split groups dim very subtly so the focused group
-      // reads as "selected" without making the unfocused content look
-      // washed out or hard to read. Only applied when `hasSplitGroups`
-      // because a lone group has nothing to contrast against.
+      // Why: vertical borders stay `border-border` so the focus highlight (--accent ~#f5f5f5 in light) doesn't paint a near-white strip by the resize handle; only the bottom border changes on focus.
+      // Why: unfocused split groups dim subtly so the focused one reads as selected; only when hasSplitGroups since a lone group has nothing to contrast against.
       className={`group/tab-group relative flex flex-col flex-1 min-w-0 min-h-0 overflow-hidden${
         hasSplitGroups
-          ? // Why: drop the outer borders on the edge-touching groups. The
-            // TabGroupSplitLayout wrapper already paints a full-height
-            // `border-l` at the sidebar seam, and the right sidebar paints
-            // its own `borderLeft` at the right seam — painting our own
-            // border-l/border-r in those spots stacks a second 1px line
-            // next to it, reading as a ~2px bar below the drag strip
-            // (where the sibling border continues alone above).
+          ? // Why: skip border-l/border-r on edge-touching groups; the split-layout wrapper and right sidebar already paint borders at those seams (double line otherwise).
             ` ${
               touchesLeftEdge || suppressLeftBorder ? '' : 'border-l'
             } ${touchesRightEdge || suppressRightBorder ? '' : 'border-r'} ${
@@ -223,20 +195,11 @@ export default function TabGroupPanel({
           : ''
       }`}
       onPointerDown={commands.focusGroup}
-      // Why: keyboard and assistive-tech users can move focus into an unfocused
-      // split group without generating a pointer event. Keeping the owning
-      // group in sync with DOM focus makes global shortcuts like New Markdown
-      // target the panel the user actually navigated into.
+      // Why: keyboard/AT focus can enter a split group without a pointer event, so sync group focus to DOM focus for global shortcuts.
       onFocusCapture={commands.focusGroup}
     >
-      {/* Why: every split group must keep its own real tab row because the app
-          can show multiple groups at once, while the window titlebar only has
-          one shared center slot. Rendering true tab chrome here preserves
-          per-group titles without making groups fight over one portal target. */}
-      {/* Why: the macOS window uses hiddenInset titleBarStyle, so the only
-          way to drag-move the window is via -webkit-app-region: drag. Without
-          this, the empty space after tabs in the center column is dead — the
-          user can only drag from the tiny left-sidebar header strip. */}
+      {/* Why: each split group needs its own tab row because multiple groups can show at once but the titlebar has only one shared center slot. */}
+      {/* Why: macOS hiddenInset titleBarStyle makes -webkit-app-region: drag the only way to move the window from this tab row. */}
       <div
         className="h-[32px] shrink-0 border-b border-border bg-card"
         data-tab-group-strip-id={groupId}
@@ -244,12 +207,7 @@ export default function TabGroupPanel({
         data-worktree-id={worktreeId}
       >
         <div className="flex h-full items-stretch pr-1.5">
-          {/* Why: Electron's native drag hit-test only respects no-drag on DOM
-              descendants, not z-index siblings. When the left sidebar is
-              collapsed, its header floats absolutely (z-10) over this tab row
-              from a separate DOM branch. An explicit no-drag spacer here
-              punches a hole in the drag surface so the floating sidebar toggle
-              and other titlebar controls remain clickable. */}
+          {/* Why: Electron drag hit-test respects no-drag only on DOM descendants, not z-index siblings, so this no-drag spacer keeps the collapsed left-sidebar's floating toggle clickable. */}
           {reserveCollapsedSidebarHeaderSpace && !sidebarOpen ? (
             <div
               className="shrink-0"
@@ -315,14 +273,7 @@ export default function TabGroupPanel({
               ) : null}
             </div>
           </div>
-          {/* Why: Electron's native drag hit-test ignores z-index — a no-drag
-              element only overrides drag when it's a DOM descendant, not a
-              sibling in another branch. The floating right-sidebar toggle and
-              the fixed-position window-controls overlay for custom desktop
-              chrome both sit in separate DOM trees, so we need an explicit
-              no-drag child here to punch holes in the drag surface beneath
-              them. The sidebar toggle is 40px (w-10); window controls add
-              --window-controls-width (138px when active, 0px otherwise) on top. */}
+          {/* Why: Electron drag hit-test respects no-drag only on DOM descendants, not z-index siblings, so this no-drag spacer keeps the floating right-sidebar toggle + window controls clickable. */}
           {reserveClosedExplorerToggleSpace && !rightSidebarOpen ? (
             <div
               className="shrink-0"
@@ -344,8 +295,7 @@ export default function TabGroupPanel({
         className="relative flex-1 min-h-0 overflow-hidden"
         style={bodyAnchorStyle}
       >
-        {/* Why: this empty anchor lets the agent-sessions tour read as a
-            terminal-area tip instead of attaching to toolbar chrome. */}
+        {/* Why: empty anchor so the agent-sessions tour reads as a terminal-area tip, not toolbar chrome. */}
         {isFocused ? (
           <div
             className="pointer-events-none absolute inset-x-0 top-1/4 h-px"
@@ -357,8 +307,7 @@ export default function TabGroupPanel({
           activeTab.contentType !== 'browser' &&
           activeTab.contentType !== 'simulator' && (
             <div className="absolute inset-0 flex min-h-0 min-w-0">
-              {/* Why: split groups render editor content inside a plain relative pane body
-                  instead of the legacy flex column in Terminal.tsx. */}
+              {/* Why: split groups render editor content in a plain relative pane body, not the legacy Terminal.tsx flex column. */}
               <Suspense
                 fallback={
                   <div className="flex flex-1 items-center justify-center text-sm text-muted-foreground">
@@ -374,11 +323,7 @@ export default function TabGroupPanel({
             </div>
           )}
 
-        {/* Why: terminal/browser/simulator panes are rendered at the worktree level by
-            overlay layers and absolutely positioned over this body element
-            via the slot registered above. Rendering them per-group caused
-            split moves to remount xterm, reparent Electron `<webview>`, or
-            reload the simulator stream. */}
+        {/* Why: terminal/browser/simulator panes render at the worktree level (overlay layers); per-group rendering remounted xterm/webview/simulator on split moves. */}
       </div>
     </div>
   )
diff --git a/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts b/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts
index 5920077ac52..d775d0347c4 100644
--- a/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts
+++ b/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts
@@ -1,6 +1,4 @@
-/* eslint-disable max-lines -- Why: the split-group workspace model intentionally keeps
-   group-scoped activation, close, split, and tab-order rules together so the extracted
-   controller cannot drift from the TabGroupPanel surface it coordinates. */
+/* eslint-disable max-lines -- Why: keeps group-scoped activation, close, split, and tab-order rules together with the TabGroupPanel surface. */
 import { useCallback, useMemo } from 'react'
 import { useShallow } from 'zustand/react/shallow'
 import type { OpenFile } from '@/store/slices/editor'
@@ -60,11 +58,7 @@ export function useTabGroupWorkspaceModel({
 }) {
   const worktreeState = useAppStore(
     useShallow((state) => ({
-      // Why: Zustand v5 expects selector snapshots to be referentially stable
-      // when the underlying store state has not changed. Allocating fresh
-      // fallback arrays here (`?? []`) makes React think every snapshot is
-      // new, which traps the split-group render path in an infinite update loop
-      // and blanks the window as soon as TabGroupPanel mounts.
+      // Why: reuse stable EMPTY_* fallbacks; fresh `?? []` arrays break Zustand v5 snapshot identity and cause an infinite render loop.
       groups: state.groupsByWorktree[worktreeId] ?? EMPTY_GROUPS,
       unifiedTabs: state.unifiedTabsByWorktree[worktreeId] ?? EMPTY_UNIFIED_TABS,
       terminalTabs: state.tabsByWorktree[worktreeId] ?? EMPTY_TERMINAL_TABS,
@@ -116,8 +110,7 @@ export function useTabGroupWorkspaceModel({
   )
   const activeItemId = group?.activeTabId ?? null
   const activeTab = groupTabs.find((item) => item.id === activeItemId) ?? null
-  // Why: split groups render tab labels from unified tabs, but terminal shell
-  // identity lives on the terminal tab so icons survive default-shell changes.
+  // Why: shell identity lives on the terminal tab (not the unified tab) so icons survive default-shell changes.
   const terminalTabById = useMemo(
     () => new Map(worktreeState.terminalTabs.map((item) => [item.id, item])),
     [worktreeState.terminalTabs]
@@ -153,10 +146,7 @@ export function useTabGroupWorkspaceModel({
             generation: terminalTab?.generation,
             shellOverride: terminalTab?.shellOverride,
             startupCwd: terminalTab?.startupCwd,
-            // Why: carry the launched agent through the rebuilt tab so the tab
-            // bar can show the provider icon before the agent's first hook —
-            // this object is reconstructed from the unified-tab model, so any
-            // store-only field (like launchAgent) is dropped unless copied here.
+            // Why: rebuilt from the unified-tab model, so copy store-only launchAgent or the provider icon is missing until the first hook.
             launchAgent: terminalTab?.launchAgent,
             pendingActivationSpawn: terminalTab?.pendingActivationSpawn
           }
@@ -208,9 +198,7 @@ export function useTabGroupWorkspaceModel({
       if (!otherReference) {
         const file = useAppStore.getState().openFiles.find((candidate) => candidate.id === entityId)
         if (file?.isDirty) {
-          // Why: split-group close actions bypass Terminal.tsx, but the unsaved
-          // confirmation + save/discard ordering must stay centralized there so
-          // tab close, bulk close, and window quit share one queueing flow.
+          // Why: route through Terminal.tsx so the unsaved-confirmation save/discard queue stays centralized across all close paths.
           requestEditorFileClose(entityId)
           return false
         }
@@ -226,11 +214,7 @@ export function useTabGroupWorkspaceModel({
     if (state.activeWorktreeId !== worktreeId) {
       return
     }
-    // Why: split-group close actions bypass the legacy Terminal.tsx handlers
-    // that used to deselect the worktree when its final visible surface
-    // closed. Without the same guard here, the renderer keeps an empty
-    // worktree selected and TabGroupPanel has nothing to render, producing a
-    // blank workspace instead of Orca's landing screen.
+    // Why: split-group closes bypass legacy Terminal.tsx; deselect the emptied worktree here or the window goes blank instead of landing.
     const { renderableTabCount } = state.reconcileWorktreeTabModel(worktreeId)
     if (renderableTabCount === 0) {
       setActiveWorktree(null)
@@ -260,13 +244,7 @@ export function useTabGroupWorkspaceModel({
       if (item.contentType === 'browser') {
         const browserState = useAppStore.getState()
         const hasLocalPages = (browserState.browserPagesByWorkspace[item.entityId] ?? []).length > 0
-        // Why: ask the host to close (idempotent) for a remote-owned browser, OR
-        // for a host-mirror whose local page list is momentarily empty — that
-        // pageless case was the bug: it has no remote-owned PAGES so the old gate
-        // skipped the host close AND the local close couldn't resolve it, leaving
-        // the tab un-closable. A genuine client-local fallback browser always has
-        // local pages, so it stays local. Always run local cleanup so the visible
-        // tab is removed no matter what.
+        // Why: host-close a remote-owned browser or a pageless host-mirror (else un-closable); local fallbacks have pages so stay local.
         const shouldCloseOnHost =
           isWebRuntimeSessionActive(runtimeEnvironmentId) &&
           (browserWorkspaceHasRemoteOwner(browserState, item.entityId, runtimeEnvironmentId) ||
@@ -316,15 +294,12 @@ export function useTabGroupWorkspaceModel({
           worktreeId
         )
         if (item.contentType === 'terminal' && isWebRuntimeSessionActive(runtimeEnvironmentId)) {
-          // Why: paired-host bulk close must revoke local resume and hook
-          // authority before asking the host to remove its canonical tab.
+          // Why: revoke local resume + hook authority before the host removes its canonical tab.
           closeTerminalTab(item.entityId)
           continue
         }
         if (item.contentType === 'browser') {
-          // Why: see closeItem — host-close a remote-owned browser OR a pageless
-          // host-mirror (the dead-end case), keep genuine local fallbacks local,
-          // and always remove the visible tab.
+          // Why: see closeItem — host-close a remote-owned browser or pageless host-mirror; always remove the visible tab.
           const browserState = useAppStore.getState()
           const hasLocalPages =
             (browserState.browserPagesByWorkspace[item.entityId] ?? []).length > 0
@@ -381,8 +356,7 @@ export function useTabGroupWorkspaceModel({
       setActiveTab(terminalId)
       setActiveTabType('terminal')
       const activeLeafId = worktreeState.terminalLayoutsByTabId[terminalId]?.activeLeafId ?? null
-      // Why: split terminal tab activation must restore xterm focus to the
-      // store-active leaf so keyboard input cannot drift to a sibling pane.
+      // Why: restore xterm focus to the store-active leaf so keyboard input can't drift to a sibling pane.
       focusTerminalTabSurface(terminalId, activeLeafId)
     },
     [
@@ -405,8 +379,7 @@ export function useTabGroupWorkspaceModel({
       if (!item) {
         return
       }
-      // Why: the tab-bar collapse icon stops pointer propagation, so it does
-      // not run the normal tab activation handler before toggling pane layout.
+      // Why: the collapse icon stops pointer propagation, so activate here since the normal tab handler won't have run.
       activateTerminal(terminalId)
       requestAnimationFrame(() => {
         window.dispatchEvent(
@@ -475,9 +448,7 @@ export function useTabGroupWorkspaceModel({
       if (!newGroupId) {
         return
       }
-      // Why: the tab-strip Split pane control adds a split pane to the right of
-      // the group that owns the button. Dragging tabs can still open other
-      // directions; this entry point always seeds a fresh terminal.
+      // Why: this Split entry point always seeds a fresh terminal (tab-drag can open other directions).
       const terminal = createTab(worktreeId, newGroupId)
       recordTerminalTabGroupSplit(terminal)
       setActiveTab(terminal.id)
@@ -501,9 +472,7 @@ export function useTabGroupWorkspaceModel({
     for (const item of items) {
       closeItem(item.id, { skipEmptyCheck: true })
     }
-    // Why: empty split groups are layout state, not tab state. The workspace
-    // model owns collapsing those placeholder panes so views do not need to
-    // understand when closing tabs is insufficient to remove a group shell.
+    // Why: closing tabs doesn't remove the group shell; empty split groups are layout state, collapse the placeholder pane here.
     closeEmptyGroup(worktreeId, groupId)
     leaveWorktreeIfEmpty()
   }, [closeEmptyGroup, closeItem, groupId, leaveWorktreeIfEmpty, worktreeId])
@@ -527,11 +496,7 @@ export function useTabGroupWorkspaceModel({
       if (!item) {
         return
       }
-      // Why: the store's closeOtherTabs helper unconditionally closes every non-pinned
-      // sibling unified tab, including dirty editor tabs — stranding those files in
-      // openFiles without a tab if the user cancels the save dialog. Collect the target
-      // ids here instead and route them through the same dirty-aware closeMany path
-      // used by individual tab closes so the Cancel -> zombie-file hazard is impossible.
+      // Why: store closeOtherTabs strands dirty files if the save dialog is cancelled; route via closeMany to stay dirty-aware.
       const siblingIds = groupTabs
         .filter((candidate) => candidate.id !== itemId && !candidate.isPinned)
         .map((candidate) => candidate.id)
@@ -542,11 +507,7 @@ export function useTabGroupWorkspaceModel({
 
   const closeToRight = useCallback(
     (itemId: string) => {
-      // Why: see closeOthers — the store's closeTabsToRight helper pre-closes dirty
-      // editor tabs before the save dialog resolves. Walking the group's tabOrder
-      // locally (unifiedTabsByWorktree is append-ordered, not visually ordered, so
-      // tabOrder is the canonical left-to-right sequence) and routing through
-      // closeMany keeps the dirty-aware flow intact.
+      // Why: store closeTabsToRight pre-closes dirty tabs; walk tabOrder (canonical L-to-R) via closeMany to stay dirty-aware.
       const order = group?.tabOrder ?? []
       const index = order.indexOf(itemId)
       if (index === -1) {
@@ -644,10 +605,7 @@ export function useTabGroupWorkspaceModel({
           })
         })()
       },
-      // Why: split-group actions must target their owning group explicitly.
-      // Relying on the ambient activeGroupIdByWorktree breaks keyboard and
-      // assistive-tech activation because the "+" menu can be triggered from
-      // an unfocused panel without first updating global group focus.
+      // Why: target the owning group explicitly; the "+" menu can fire from an unfocused panel without updating global group focus.
       newFileTab: async () => {
         await openNewMarkdownInActiveWorkspace(groupId)
       },
diff --git a/src/renderer/src/components/terminal-pane/TerminalPane.tsx b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
index ef17bad747c..0997a11c0e7 100644
--- a/src/renderer/src/components/terminal-pane/TerminalPane.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
@@ -163,9 +163,7 @@ function isInsideNativeChatRoot(target: EventTarget | null): boolean {
   return target instanceof Element && target.closest(NATIVE_CHAT_ROOT_SELECTOR) !== null
 }
 
-// Why: registry lives in a leaf module so the store slice can import it
-// without re-entering the `slice → TerminalPane → store → slice` cycle
-// that otherwise leaves createTerminalSlice undefined at store-init time.
+// Why: registry lives in a leaf module to break the slice → TerminalPane → store → slice import cycle that leaves createTerminalSlice undefined at init.
 import { shutdownBufferCaptures } from './shutdown-buffer-captures'
 import { mergeCapturedLeafState } from './merge-captured-leaf-state'
 import { pasteTerminalText } from './terminal-bracketed-paste'
@@ -210,14 +208,9 @@ type TerminalPaneProps = {
   isActive: boolean
   isVisible?: boolean
   isWorktreeActive?: boolean
-  // Why: when set (Activity portal), this pane visually isolates the given
-  // split pane so only that leaf is shown. Implemented as a transient layout
-  // override (separate snapshot ref) — does NOT touch expandedPaneId state
-  // or persist to the layout snapshot, so returning to the workspace shows
-  // the original split layout unchanged.
+  // When set (Activity portal), isolates one split pane as a transient override that doesn't touch expandedPaneId or persist the layout.
   isolatedPaneKey?: string | null
-  // Why: ephemeral one-off command terminals don't need the regular pane header's
-  // prominent split affordance, though standard split shortcuts remain available.
+  // Why: ephemeral one-off command terminals don't need the header's prominent split affordance (split shortcuts still work).
   showSplitButton?: boolean
   onPtyExit: (ptyId: string) => void
   onCloseTab: () => void
@@ -297,31 +290,19 @@ export default function TerminalPane({
     new Map()
   )
   const pendingPaneSizeRefreshFrameIdsRef = useRef<number[]>([])
-  // Why (separate from expandedStyleSnapshotRef): Activity isolation is a
-  // transient view override that must not collide with the user-facing
-  // expanded-pane state or the layout snapshot. Keeping its own snapshot
-  // map means applyExpandedLayoutTo's internal restore (which targets the
-  // ref it was passed) only clears Activity's overlay, not the user's.
+  // Separate from expandedStyleSnapshotRef so Activity's transient isolation override doesn't collide with the user's expanded-pane state or layout snapshot.
   const activityIsolationSnapshotRef = useRef<Map<HTMLElement, { display: string; flex: string }>>(
     new Map()
   )
   const paneTransportsRef = useRef<Map<number, PtyTransport>>(new Map())
-  // Why: per-pane live cwd tracked via OSC 7 for split-pane cwd inheritance.
-  // See docs/ssh-split-pane-inherit-cwd.md. The OSC 7 handler is installed
-  // in use-terminal-pane-lifecycle; keyboard and context-menu split actions
-  // read this map at dispatch time to pass cwd into splitPane.
+  // Why: per-pane live cwd via OSC 7 for split-pane cwd inheritance; split actions read it at dispatch. See docs/ssh-split-pane-inherit-cwd.md.
   const paneCwdRef = useRef<Map<number, { cwd: string; confirmed: boolean }>>(new Map())
   const paneMode2031Ref = useRef<Map<number, boolean>>(new Map())
-  // Why: per-pane mirror of the kitty keyboard flags negotiated by the pane's
-  // application (fed from PTY output in pty-connection). The keyboard policy
-  // reads it to encode Option chords as kitty CSI-u for opted-in TUIs.
+  // Why: per-pane mirror of kitty keyboard flags; the keyboard policy reads it to encode Option chords as kitty CSI-u for opted-in TUIs.
   const paneKittyKeyboardModesRef = useRef<Map<number, TerminalKittyKeyboardModeTracker>>(new Map())
   const paneLastThemeModeRef = useRef<Map<number, 'dark' | 'light'>>(new Map())
   const panePtyBindingsRef = useRef<Map<number, IDisposable>>(new Map())
-  // Why: tracks panes currently replaying recorded PTY bytes into xterm
-  // (cold-restore, daemon snapshot, scrollback restore, eager-buffer flush).
-  // While non-zero, pty-connection.ts drops xterm onData so auto-replies to
-  // embedded query sequences don't leak to the shell. See replay-guard.ts.
+  // Why: panes replaying recorded PTY bytes; while non-zero, pty-connection drops xterm onData so auto-replies don't leak to the shell. See replay-guard.ts.
   const replayingPanesRef = useRef<Map<number, number>>(new Map())
   const isActiveRef = useRef(isActive)
   isActiveRef.current = isActive
@@ -330,8 +311,7 @@ export default function TerminalPane({
   isVisibleRef.current = isRendererVisible
   const sshReconnectTargetId = useAppStore((store) => {
     const connectionId = getConnectionIdFromState(store, worktreeId)
-    // Why: runtime-owned SSH targets are internal plumbing users can't connect
-    // to directly, so a reconnect prompt would offer a misleading action.
+    // Why: runtime-owned SSH targets are internal plumbing users can't connect to, so a reconnect prompt would mislead.
     if (!connectionId || isRuntimeOwnedSshTargetId(connectionId)) {
       return null
     }
@@ -340,11 +320,8 @@ export default function TerminalPane({
   const nativeChatTranscriptIsLocalReadable = useAppStore((store) =>
     isNativeChatTranscriptLocalReadable(getConnectionIdFromState(store, worktreeId))
   )
-  // Which machine's SSH store this target belongs to: a remote Orca server's
-  // per-environment bucket, or null for this machine's local SSH maps. The
-  // explicit-owner resolver never lets a merely focused runtime make a
-  // local-owned workspace look remote. The paired web client mirrors its one
-  // host through the local maps instead.
+  // Which machine's SSH store this target belongs to: a remote server's per-environment bucket, or null for this machine's local SSH maps.
+  // Why: paired web clients force null — they mirror their one host through the local maps, not an explicit environment bucket.
   const sshReconnectEnvironmentId = useAppStore((store) =>
     sshReconnectTargetId && !isPairedWebClientWindow()
       ? getExplicitRuntimeEnvironmentIdForWorktree(store, worktreeId)
@@ -360,10 +337,7 @@ export default function TerminalPane({
       ? selectRuntimeAwareSshTargetLabel(store, sshReconnectEnvironmentId, sshReconnectTargetId)
       : ''
   )
-  // Why: the target was removed entirely (a ghost) when it's no longer a known
-  // SSH target on its owning host. Reconnecting to it can only fail ("SSH
-  // target not found"), so the overlay must offer to remove the workspace
-  // instead of Connect. The selector requires positive removal evidence.
+  // Why: a ghost target (removed from its host) can only fail reconnect, so the overlay offers Remove instead of Connect.
   const sshReconnectTargetRemoved = useAppStore((store) =>
     sshReconnectTargetId
       ? selectRuntimeAwareSshTargetRemoved(store, sshReconnectEnvironmentId, sshReconnectTargetId)
@@ -373,25 +347,16 @@ export default function TerminalPane({
     if (!sshReconnectEnvironmentId) {
       return
     }
-    // Why: an SSH-backed workspace can be mirrored before its owning
-    // environment's bucket ever hydrated (no-op once hydrated), and overlay
-    // state must come from fetched evidence, never from an empty default.
+    // Why: an SSH workspace can mirror before its environment bucket hydrated; overlay state must come from fetched evidence, not an empty default.
     void hydrateRuntimeEnvironmentSshState(sshReconnectEnvironmentId).catch(() => {})
   }, [sshReconnectEnvironmentId])
 
   useVisibleTerminalTabClaim({ isVisible, tabId })
 
   const [expandedPaneId, setExpandedPaneId] = useState<number | null>(null)
-  // Why: tracked in React state (not derived from managerRef.getPanes().length)
-  // so the render containing the portal map (which reads the imperative pane
-  // list via managerRef.current?.getPanes()) re-runs when a pane is split or
-  // closed. managerRef is imperative and doesn't trigger React's dependency
-  // tracking. The lifecycle hook updates this via setPaneCount on
-  // onPaneCreated / onPaneClosed / onLayoutChanged. The portal map reads the
-  // manager imperatively; the count also wakes leaf-ownership initialization.
+  // Why: React state (not the imperative managerRef) so the render re-runs on split/close; managerRef alone doesn't trigger React deps.
   const [paneCount, setPaneCount] = useState<number>(0)
-  // Why: pane reorders can move panes without changing count or size, so
-  // overlay rects need an explicit layout-change render trigger.
+  // Why: pane reorders can move panes without changing count or size, so overlay rects need an explicit layout-change render trigger.
   const [paneLayoutRevision, setPaneLayoutRevision] = useState(0)
   const [searchOpen, setSearchOpen] = useState(false)
   const searchOpenRef = useRef(false)
@@ -407,19 +372,13 @@ export default function TerminalPane({
   const [tabWideAgentHintLeafId, setTabWideAgentHintLeafId] = useState<string | null | undefined>(
     undefined
   )
-  // Why: the terminal menu can be the first quick-command entry point, so each
-  // Add action starts with a fresh draft instead of reusing cancelled text.
+  // Why: each Add action starts with a fresh draft so the terminal menu doesn't reuse cancelled quick-command text.
   const [quickCommandDraft, setQuickCommandDraft] = useState(createTerminalQuickCommandDraft)
   const [agentSessionFork, setAgentSessionFork] = useState<PreparedAgentSessionFork | null>(null)
   const [terminalError, setTerminalError] = useState<string | null>(null)
   const [sessionStateSaveFailureOpen, setSessionStateSaveFailureOpen] = useState(false)
   const daemonActions = useDaemonActions()
-  // Why: override state lives in a plain Map for perf (safeFit reads it on
-  // every resize). This counter forces a re-render when overrides change so
-  // the mobile-fit banner appears/disappears. On both transitions we also
-  // trigger safeFit on affected panes: mobile-fit shrinks the watcher's xterm
-  // to phone dims (matching the live phone-wrapped stream), and desktop-fit
-  // resizes back to desktop dimensions.
+  // Why: override state lives in a Map for perf; this counter forces a re-render on override change so the mobile-fit banner toggles.
   const [, setOverrideTick] = useState(0)
   useEffect(() => {
     const pendingFitFrames = new Set<number>()
@@ -447,8 +406,7 @@ export default function TerminalPane({
       if (!manager) {
         return
       }
-      // Why: pane IDs are per-tab, so resolve the affected PTY through this
-      // tab's live transport bindings instead of global numeric pane IDs.
+      // Why: pane IDs are per-tab, so resolve the affected PTY through this tab's live transport bindings, not global pane IDs.
       const getAffectedPanes = (): ReturnType<typeof manager.getPanes> =>
         getOverrideAffectedPanes(
           manager.getPanes(),
@@ -456,16 +414,8 @@ export default function TerminalPane({
           event.ptyId
         )
       if (event.mode === 'mobile-fit' || event.mode === 'remote-desktop-fit') {
-        // Why: when mobile starts driving, the agent re-renders its output at
-        // phone width and that phone-wrapped byte stream flows live into this
-        // passive watcher's xterm. xterm must shrink to the phone dims now or
-        // the wide desktop grid renders the narrow stream as overlapping,
-        // garbled lines. safeFit honors the active override and parks xterm at
-        // override.cols/rows, matching the incoming stream. rAF lets the DOM
-        // settle before the resize; no loud fallback is needed because the
-        // override branch of safeFit is itself the authoritative resize.
-        // Why: override events fan out to every terminal tab; skip the rAF
-        // unless this tab has a pane still parked at the wrong grid.
+        // Why: when mobile drives, xterm must shrink to phone dims or the wide desktop grid garbles the phone-wrapped stream.
+        // Why: override events fan out to every terminal tab; skip the rAF unless this tab has a mis-parked pane.
         const panesNeedingFit = getPanesNeedingOverrideFit(
           getAffectedPanes(),
           event.cols,
@@ -486,49 +436,24 @@ export default function TerminalPane({
         return
       }
       if (event.mode === 'desktop-fit') {
-        // Why: fitAddon.fit() measures DOM dimensions, so it must run after
-        // the browser has settled layout. Running synchronously inside the
-        // IPC callback can produce stale measurements. rAF ensures the DOM
-        // is ready. The follow-up timeout acts as a safety net: if
-        // fitAddon.fit() silently threw (its errors are caught), the timeout
-        // falls back to a direct terminal.resize() using the restored
-        // dimensions from the runtime. This guarantees xterm exits mobile
-        // dims even when the DOM-based fit path fails.
+        // Why: fitAddon.fit() measures the DOM, so run under rAF after layout settles; the timeout is a safety net if fit silently threw.
         const fitAffectedPanes = (): void => {
           for (const pane of getAffectedPanes()) {
             safeFit(pane)
           }
         }
         scheduleFitFrame(fitAffectedPanes)
-        // Why: belt-and-suspenders — if safeFit's fitAddon.fit() threw or
-        // was a no-op due to stale dimensions, fall back to a direct
-        // resize. ONLY fire if xterm is still parked at the prior
-        // mobile-fit dims, meaning safeFit failed to move it. Previously
-        // we also fired when xterm had moved to *any* size other than
-        // the captured baseline, which clobbered safeFit's correct
-        // DOM-measured fit when the desktop pane geometry had changed
-        // since mobile-fit started (e.g. user closed a split or resized
-        // the window while the phone was active). In that scenario the
-        // event.cols/rows is the stale baseline from the moment
-        // mobile-fit started, not the current pane geometry — applying
-        // it would shrink the terminal back to e.g. half-width.
+        // Why: direct-resize fallback if safeFit no-op'd, only while xterm is still at the prior mobile-fit dims; else event.cols/rows is a stale baseline that clobbers the fit.
         scheduleFallbackTimer(() => {
           for (const pane of getAffectedPanes()) {
-            // Why: skip the fallback for hidden/unmounted panes whose
-            // container is 0×0. Force-resizing xterm to the server's
-            // desktop dims while the DOM has no geometry leaves xterm
-            // with cols/rows that won't match when the tab is later
-            // activated (the activation refit will correct it). The
-            // fallback is for the *visible* pane that legitimately
-            // failed to refit via the rAF safeFit.
+            // Why: skip 0×0 hidden panes; forcing desktop dims with no DOM geometry leaves a mismatched grid (fallback is only for the visible pane that failed to refit).
             const rect = pane.container.getBoundingClientRect()
             if (rect.width === 0 || rect.height === 0) {
               continue
             }
             applyDesktopFitFallbackAfterReplay(pane, {
               ...event,
-              // Why: the timeout/replay queue can outlive this pane binding;
-              // never apply old server dimensions to a replacement PTY.
+              // Why: the timeout/replay queue can outlive this pane binding; never apply old server dims to a replacement PTY.
               shouldApply: () => getAffectedPanes().includes(pane)
             })
           }
@@ -549,9 +474,7 @@ export default function TerminalPane({
     }
   }, [])
 
-  // Why: presence-lock banner re-render. Driver state lives in a plain Map
-  // for perf; this counter forces a re-render when the driver flips so the
-  // lock banner appears/disappears. See docs/mobile-presence-lock.md.
+  // Why: driver state lives in a Map for perf; this counter re-renders on driver flips so the lock banner toggles. See docs/mobile-presence-lock.md.
   const [, setDriverTick] = useState(0)
   useEffect(
     () =>
@@ -561,8 +484,7 @@ export default function TerminalPane({
     []
   )
 
-  // Pane title state — keyed by ephemeral paneId, persisted via titlesByLeafId
-  // in the layout snapshot. Ref keeps persistLayoutSnapshot closures fresh.
+  // Pane title state keyed by ephemeral paneId, persisted via titlesByLeafId; ref keeps persistLayoutSnapshot closures fresh.
   const [paneTitles, setPaneTitles] = useState<Record<number, string>>({})
   const paneTitlesRef = useRef<Record<number, string>>({})
   paneTitlesRef.current = paneTitles
@@ -574,24 +496,16 @@ export default function TerminalPane({
   const [renamingPaneId, setRenamingPaneId] = useState<number | null>(null)
   const [renameValue, setRenameValue] = useState('')
   const renameInputRef = useRef<HTMLInputElement>(null)
-  // Guard against double-submit: when the user presses Enter, handleRenameSubmit
-  // runs and then the input unmounts causing onBlur to fire handleRenameSubmit
-  // again. Similarly, pressing Escape runs handleRenameCancel but blur would
-  // then call handleRenameSubmit, saving the title the user wanted to discard.
+  // Guard against double-submit: Enter/Escape act first, then the input's onBlur re-fires handleRenameSubmit, re-saving a discarded title.
   const renameSubmittedRef = useRef(false)
   const renameSessionIdRef = useRef(0)
   const renameBlurCommitEnabledRef = useRef(true)
-  // Why: delayed xterm/Radix focus handoffs look like blur but are not user
-  // intent. Only outside pointer/Tab navigation should make blur commit.
+  // Why: delayed xterm/Radix focus handoffs look like blur but aren't user intent; only outside pointer/Tab nav should commit.
   const renameUserRequestedBlurCommitRef = useRef(false)
   const renameFocusFrameRef = useRef<number | null>(null)
   const renameEnableBlurFrameRef = useRef<number | null>(null)
   const renameRefocusFrameRef = useRef<number | null>(null)
-  /**
-   * Cancels deferred focus/blur work from inline title editing.
-   * Rename sessions schedule multiple frames because xterm and Radix can both
-   * move focus after the menu closes.
-   */
+  /** Cancels deferred focus/blur frames from inline title editing (xterm and Radix can both move focus after the menu closes). */
   const cancelPendingRenameFrames = useCallback(() => {
     const frameRefs = [renameFocusFrameRef, renameEnableBlurFrameRef, renameRefocusFrameRef]
     for (const frameRef of frameRefs) {
@@ -602,10 +516,7 @@ export default function TerminalPane({
     }
   }, [])
 
-  /**
-   * Invalidates the active inline title edit session before unmount or cancel.
-   * Session IDs keep stale animation-frame callbacks from committing old titles.
-   */
+  /** Invalidates the active inline title edit session (bumping the session ID) so stale animation-frame callbacks can't commit old titles. */
   const closeRenameSession = useCallback(() => {
     renameSessionIdRef.current += 1
     renameBlurCommitEnabledRef.current = true
@@ -613,27 +524,20 @@ export default function TerminalPane({
     cancelPendingRenameFrames()
   }, [cancelPendingRenameFrames])
 
-  /**
-   * Owns the terminal container ref and closes rename work when that owner
-   * detaches, preventing delayed focus callbacks from targeting stale DOM.
-   */
+  /** Owns the terminal container ref; closes rename work when the owner detaches so delayed focus callbacks don't target stale DOM. */
   const setContainerRef = useCallback(
     (node: HTMLDivElement | null): void => {
       containerRef.current = node
       if (node !== null) {
         return
       }
-      // Why: inline title rename focus/blur frames are owned by the terminal
-      // container; invalidate them when that DOM owner detaches.
+      // Why: rename focus/blur frames are owned by the terminal container; invalidate them when that DOM owner detaches.
       closeRenameSession()
     },
     [closeRenameSession]
   )
 
-  /**
-   * Starts inline title editing from either the context menu or keyboard
-   * shortcut while resetting stale blur-submit state from prior sessions.
-   */
+  /** Starts inline title editing (menu or keyboard), resetting stale blur-submit state from prior sessions. */
   const handleStartRename = useCallback(
     (paneId: number) => {
       cancelPendingRenameFrames()
@@ -663,10 +567,7 @@ export default function TerminalPane({
     (store) => store.consumePendingCodexPaneRestart
   )
   const clearCodexRestartNotice = useAppStore((store) => store.clearCodexRestartNotice)
-  // Why: when this tab is in native chat view the chat surface is the active
-  // layer above the still-mounted terminal, so the terminal's own mobile-driver
-  // overlay must not render on top of it; the chat composer's guarded canSend
-  // communicates the presence-lock inside the chat surface instead (U9/R8).
+  // Why: in chat view the chat surface sits above the mounted terminal, so its mobile-driver overlay must not render over it (U9/R8).
   const unifiedTabId = useAppStore(
     (store) =>
       getCachedUnifiedTerminalTabForWorktree(store.unifiedTabsByWorktree, worktreeId, tabId)?.id
@@ -685,12 +586,7 @@ export default function TerminalPane({
   const runtimePaneTitlesByPaneId = useAppStore(
     useShallow((store) => store.runtimePaneTitlesByTabId[tabId] ?? {})
   )
-  // The native-chat toggle joins the pane header's split/close cluster. Eligible
-  // when Orca launched a *supported* agent here or one was detected live for the
-  // leaf, keyed `${tabId}:${leafId}`. Carry the agent identity, not just "an
-  // agent exists", so the gate can reject Grok et al.
-  // Scope to this tab's panes and reuse the shared map index so hidden tabs do
-  // not each rescan every agent entry on unrelated store writes.
+  // Carry each leaf's agent identity, not just "an agent exists", so the gate can reject unsupported agents; scoped to this tab's panes.
   const tabAgentTypeByLeaf = useAppStore((store) =>
     selectTerminalTabAgentTypesByLeaf(store.agentStatusByPaneKey, tabId)
   )
@@ -710,8 +606,7 @@ export default function TerminalPane({
   )
   const getNativeChatLeafIds = useCallback((): string[] => {
     const mountedLeafIds = managerRef.current?.getPanes().map((pane) => pane.leafId) ?? []
-    // Why: a partially hydrated manager can expose one pane from a restored
-    // split. Union both sources so tab-wide evidence stays disabled meanwhile.
+    // Why: a partially hydrated manager can expose one pane of a restored split; union both sources so tab-wide evidence stays disabled.
     return [...new Set([...expectedLayoutLeafIds, ...mountedLeafIds])]
   }, [expectedLayoutLeafIds])
   const getTabWideAgentHintLeafId = useCallback((): string | null => {
@@ -729,8 +624,7 @@ export default function TerminalPane({
     if (leafIds.length === 0) {
       return
     }
-    // Why: tab-wide launch/title metadata predates leaf ownership. Bind it only
-    // when the first concrete topology proves which sole leaf it can describe.
+    // Why: tab-wide launch/title metadata predates leaf ownership; bind it only when the first topology proves the sole leaf it describes.
     setTabWideAgentHintLeafId(leafIds.length === 1 ? leafIds[0] : null)
   }, [getNativeChatLeafIds, paneCount, tabWideAgentHintLeafId])
   const resolveTitleAgentForLeaf = useCallback(
@@ -753,11 +647,7 @@ export default function TerminalPane({
       unifiedTabLabel
     ]
   )
-  // Per-leaf eligibility: a split can mix a supported agent in one leaf with an
-  // unsupported one in another, so the toggle is gated by the specific leaf.
-  // A leaf's own live agent is authoritative; the tab-wide launch/title hints
-  // only fill in before hooks arrive (or for the single-pane case) so they
-  // can't enable the toggle on a sibling actually running an unsupported agent.
+  // Per-leaf: a split can mix supported/unsupported agents; the leaf's live agent is authoritative, tab-wide hints only fill in before hooks arrive.
   const isChatEligibleForLeaf = useCallback(
     (leafId: string | null): boolean => {
       const detectedAgent = leafId ? (tabAgentTypeByLeaf[leafId] ?? null) : null
@@ -819,14 +709,12 @@ export default function TerminalPane({
     [applyNativeChatLeafRoute, chatLeafId, isChatEligibleForLeaf, isChatViewMode]
   )
   useEffect(() => {
-    // Why: transport callbacks must only observe committed chat ownership;
-    // render work can be replayed or discarded under concurrent React.
+    // Why: transport callbacks must observe only committed chat ownership; render work can be replayed/discarded under concurrent React.
     onAgentExitedRef.current = handleConfirmedAgentExit
   }, [handleConfirmedAgentExit])
   const canToggleChatForLeaf = useCallback(
     (leafId: string | null): boolean => {
-      // Scope the "always allow toggling back" rule to the leaf actually showing
-      // chat; it must not make an unsupported sibling look eligible.
+      // Scope the "always allow toggling back" rule to the leaf showing chat; must not make an unsupported sibling look eligible.
       const isChatViewForLeaf = effectiveChatViewMode && leafId !== null && chatLeafId === leafId
       return (nativeChatEnabled && isChatViewForLeaf) || isChatEligibleForLeaf(leafId)
     },
@@ -885,8 +773,7 @@ export default function TerminalPane({
   const requestLinkRoutingPreference = useLinkRoutingPreferenceDialog()
   const keybindings = useAppStore((store) => store.keybindings)
   const rightClickToPaste = settings?.terminalRightClickToPaste ?? isWindowsUserAgent()
-  // Why: Windows ConPTY does not forward DECSET 2004 from foreground TUIs, so
-  // xterm may not know multi-line text needs bracketed-paste protection.
+  // Why: Windows ConPTY doesn't forward DECSET 2004 from TUIs, so xterm may not know multi-line paste needs bracketed protection.
   const forceBracketedMultilineTextPaste = isWindowsUserAgent()
   const [startup] = useState(() => useAppStore.getState().pendingStartupByTabId[tabId])
   const [shouldMeasureHiddenStartup, setShouldMeasureHiddenStartup] = useState(
@@ -910,14 +797,11 @@ export default function TerminalPane({
 
   useLayoutEffect(() => {
     if (isVisible && shouldMeasureHiddenStartup) {
-      // Why: hidden startup measurement is only for first launch. Keeping it
-      // after first visibility lets inactive agent tabs refit and SIGWINCH.
+      // Why: hidden startup measurement is first-launch only; keeping it past first visibility would let inactive tabs refit and SIGWINCH.
       setShouldMeasureHiddenStartup(false)
     }
     if (isVisible) {
-      // Why: a hidden pane that connected at 0×0 self-heals via the pane resize
-      // observer once shown, so clear that stale diagnostic. Scoped to the
-      // zero-dimensions message so genuine paste/save-failure errors survive.
+      // Why: a hidden 0×0 pane self-heals once shown; clear only the stale zero-dims diagnostic so real errors survive.
       setTerminalError((prev) => (prev && isTerminalZeroDimensionsDiagnostic(prev) ? null : prev))
     }
   }, [isVisible, shouldMeasureHiddenStartup])
@@ -1044,12 +928,7 @@ export default function TerminalPane({
     },
     [requestLinkRoutingPreference, updateSettings]
   )
-  // Why: the persisted setting can be 'auto' (default) or one of the four
-  // explicit modes. useEffectiveMacOptionAsAlt resolves 'auto' into
-  // 'true' | 'false' based on the probe's current layout category (US → 'true',
-  // anything else → 'false'), and re-renders when the OS layout changes.
-  // Downstream keyboard handlers read the ref, so the ref also tracks the
-  // effective value, not the raw setting.
+  // Why: 'auto' resolves to true/false by keyboard layout (US → alt); the ref tracks that effective value, not the raw setting.
   const effectiveMacOptionAsAlt = useEffectiveMacOptionAsAlt(settings?.terminalMacOptionAsAlt)
   const macOptionAsAltRef = useRef<MacOptionAsAlt>(effectiveMacOptionAsAlt)
   macOptionAsAltRef.current = effectiveMacOptionAsAlt
@@ -1060,11 +939,7 @@ export default function TerminalPane({
   const dispatchNotification = useNotificationDispatch(worktreeId)
   const setCacheTimerStartedAt = useAppStore((store) => store.setCacheTimerStartedAt)
 
-  // Memoized with useCallback so downstream hooks (useTerminalKeyboardShortcuts,
-  // useTerminalPaneLifecycle, createExpandCollapseActions) don't tear down and
-  // re-register event listeners on every render. All data it reads comes from
-  // refs (managerRef, containerRef, expandedPaneIdRef, paneTitlesRef) or
-  // stable values (tabId, setTabLayout), so the dependency array is minimal.
+  // Memoized so downstream hooks don't re-register listeners each render; reads only refs/stable values, so deps stay minimal.
   const persistLayoutSnapshot = useCallback((): void => {
     const manager = managerRef.current
     const container = containerRef.current
@@ -1086,9 +961,7 @@ export default function TerminalPane({
     const scrollbackPreserveLeafIds = new Set(
       [...currentLeafIds].filter((leafId) => !clearedScrollbackLeafIds.has(leafId))
     )
-    // Preserve existing buffersByLeafId so layout-only persists (resize, split,
-    // reorder) don't clobber previously captured scrollback. Drop entries for
-    // leaves that no longer exist.
+    // Preserve existing buffersByLeafId so layout-only persists don't clobber captured scrollback; drop dead leaves.
     const mergedBuffers = mergeCapturedLeafState({
       prior: existing?.buffersByLeafId,
       fresh: {},
@@ -1105,12 +978,7 @@ export default function TerminalPane({
     if (Object.keys(mergedScrollbackRefs).length > 0) {
       layout.scrollbackRefsByLeafId = mergedScrollbackRefs
     }
-    // Why: between pane creation and the deferred rAF where PTYs actually
-    // attach, all transports have getPtyId() === null. The merge below
-    // preserves the *prior* snapshot's leaf→PTY mappings while still letting
-    // any live transports overwrite them. Without preservation, a rapid
-    // successive remount (tab moved again before the first rAF) would lose
-    // the mappings and force fresh PTY spawns.
+    // Why: before PTYs attach (deferred rAF) transports return null; preserve prior leaf→PTY mappings so a fast remount doesn't force fresh spawns.
     const livePtyEntries = currentPanes
       .map((p) => [p.leafId, paneTransportsRef.current.get(p.id)?.getPtyId() ?? null] as const)
       .filter(
@@ -1130,9 +998,7 @@ export default function TerminalPane({
       activeLeafId: layout.activeLeafId,
       ptyIdsByLeafId: mergedPtyIds
     })
-    // Preserve pane titles — uses the live React state (via ref) rather than
-    // the stale Zustand value because React state reflects in-flight title
-    // edits that haven't been persisted yet.
+    // Preserve pane titles from live React state (via ref); Zustand is stale for in-flight edits not yet persisted.
     const titlesByLeafId: Record<string, string> = {}
     const removedTitleLeafIds = removedTitleLeafIdsRef.current
     for (const pane of currentPanes) {
@@ -1141,9 +1007,7 @@ export default function TerminalPane({
         titlesByLeafId[pane.leafId] = existingTitle
       }
     }
-    // Why: active agents can trigger layout persists while pane-title React
-    // state is catching up. Preserve existing leaf titles unless this pane
-    // explicitly removed them, then overlay the live local pane-title state.
+    // Why: agents can persist layout while pane-title React state lags, so keep existing titles unless removed before overlaying live state.
     const titles = paneTitlesRef.current
     for (const pane of currentPanes) {
       const title = titles[pane.id]
@@ -1156,9 +1020,7 @@ export default function TerminalPane({
       layout.titlesByLeafId = titlesByLeafId
     }
     setTabLayout(tabId, layout)
-    // Why: pane geometry is host-authoritative for remote-server tabs, so push
-    // ratios/expand/titles to the host or they revert on the next snapshot.
-    // Gate on a remote pty to avoid an RPC for purely-local tabs.
+    // Why: pane geometry is host-authoritative for remote tabs, so push ratios/expand/titles or they revert on the next snapshot.
     const hasRemotePane = Object.values(mergedPtyIds).some(
       (ptyId) => typeof ptyId === 'string' && isRemoteRuntimePtyId(ptyId)
     )
@@ -1180,14 +1042,11 @@ export default function TerminalPane({
     (pane: ManagedPane): void => {
       clearedScrollbackLeafIdsRef.current.add(pane.leafId)
       clearTerminalScrollbackAndFollowOutput(pane.terminal)
-      // Why: also clear the host buffer for remote-server panes, or the next
-      // host snapshot replays the scrollback we just cleared locally.
+      // Why: also clear the host buffer for remote-server panes, or the next host snapshot replays what we just cleared.
       const ptyId = paneTransportsRef.current.get(pane.id)?.getPtyId() ?? null
       const clearedRemoteHostBuffer = clearWebRuntimeTerminalBuffer(ptyId)
       if (!clearedRemoteHostBuffer && ptyId) {
-        // Why: local/daemon/SSH PTYs keep their own screen state (ConPTY on
-        // Windows), and a stale host cursor row makes the next prompt repaint
-        // land below a blank gap after a frontend-only clear.
+        // Why: local/daemon/SSH PTYs keep their own screen state (ConPTY on Windows); clear it too or the next prompt repaints below a blank gap.
         window.api.pty.clearBuffer(ptyId)
       }
       persistLayoutSnapshot()
@@ -1195,10 +1054,7 @@ export default function TerminalPane({
     [paneTransportsRef, persistLayoutSnapshot]
   )
 
-  /**
-   * Removes a custom pane title from React state, the fresh persistence ref,
-   * and the leaf-id tombstone set so the next layout snapshot stays cleared.
-   */
+  /** Removes a custom pane title from state, the persistence ref, and tombstones the leaf so the next snapshot stays cleared. */
   const removePaneTitle = useCallback(
     (paneId: number) => {
       setPaneTitles((prev) => {
@@ -1224,10 +1080,7 @@ export default function TerminalPane({
     [persistLayoutSnapshot]
   )
 
-  /**
-   * Ignores clear-title shortcuts for panes already using their automatic
-   * title, keeping the command idempotent and avoiding unnecessary snapshots.
-   */
+  /** Ignores clear-title shortcuts for panes already on their automatic title (idempotent, no wasted snapshot). */
   const handleClearPaneTitleShortcut = useCallback(
     (paneId: number) => {
       if (!paneTitlesRef.current[paneId]) {
@@ -1293,10 +1146,7 @@ export default function TerminalPane({
       if (ptyId) {
         setTabLayout(tabId, {
           ...layoutWithoutPtyBindings,
-          // Why: PTY ownership changes happen after the synchronous layout
-          // snapshot on mount. Persist the live pane→PTY binding here so
-          // remounts attach each pane to its current shell instead of a stale
-          // or missing PTY id from an earlier snapshot.
+          // Why: PTY ownership changes after the mount-time layout snapshot, so persist the live pane→PTY binding here for correct remount attachment.
           ptyIdsByLeafId: {
             ...existingBindings,
             [leafId]: ptyId
@@ -1316,9 +1166,7 @@ export default function TerminalPane({
         existingLayout.activeLeafId === leafId &&
         Object.keys(nextBindings).length > 0
       ) {
-        // Why: an active pane that lost its PTY would keep swallowing input if
-        // sibling bound panes are available; replacement/restart bookkeeping
-        // opts out so focus stays with the pane about to receive a fresh PTY.
+        // Why: repair focus off an active pane that lost its PTY (it would swallow input); restart bookkeeping opts out to keep the pane getting a fresh PTY.
         nextLayout.activeLeafId = resolveTerminalLayoutActiveLeafId({
           root: nextLayout.root,
           activeLeafId: nextLayout.activeLeafId,
@@ -1350,8 +1198,7 @@ export default function TerminalPane({
 
       const nextBindings = { ...existingBindings }
       delete nextBindings[leafId]
-      // Why: a focused pane that lost its PTY can swallow input while a live
-      // sibling still exists, so unexpected exits repair focus to a bound leaf.
+      // Why: a focused pane that lost its PTY swallows input while a live sibling exists, so repair focus to a bound leaf on unexpected exit.
       setTabLayout(tabId, {
         ...layoutWithoutPtyBindings,
         activeLeafId: resolveTerminalLayoutActiveLeafId({
@@ -1392,10 +1239,7 @@ export default function TerminalPane({
       if (manager.getPanes().length <= 1) {
         onCloseTab()
       } else {
-        // Why: clear the cache timer for this specific pane before closing it,
-        // so the sidebar doesn't show a stale countdown for a pane that no
-        // longer exists. The closeTab path handles bulk cleanup, but closing
-        // a single split pane doesn't go through closeTab.
+        // Why: closing a single split pane skips closeTab's bulk cleanup, so clear this pane's cache timer or the sidebar shows a stale countdown.
         const ptyId = paneTransportsRef.current.get(paneId)?.getPtyId() ?? null
         closeWebRuntimeTerminal(ptyId)
         clearSessionRestoredBannerForPane(paneId)
@@ -1411,10 +1255,7 @@ export default function TerminalPane({
     [clearSessionRestoredBannerForPane, onCloseTab, syncPanePtyLayoutBinding, tabId]
   )
 
-  // Cmd+W handler — shows a confirmation dialog when the pane's shell has
-  // a running child process (e.g. npm run dev), so the user doesn't
-  // accidentally kill it. An idle shell prompt closes immediately. Ctrl+D
-  // (explicit EOF) bypasses this by design.
+  // Cmd+W confirms before killing a shell with a running child (e.g. npm run dev); idle prompts close immediately, and Ctrl+D bypasses by design.
   const getCloseDialogCopyKind = useCallback(
     (paneId: number): CloseTerminalDialogCopyKind => {
       const leafId = managerRef.current?.getLeafId(paneId)
@@ -1430,10 +1271,7 @@ export default function TerminalPane({
 
   const handleRequestClosePane = useCallback(
     (paneId: number) => {
-      // Why: when closing the last pane of a pinned tab, the pin confirmation
-      // takes precedence over the running-process prompt — let executeClosePane
-      // fall through to closeTerminalTab, which raises the single pin dialog
-      // (confirming it kills the process). Non-pinned tabs keep the process prompt.
+      // Why: closing the last pane of a pinned tab prefers the pin dialog over the running-process prompt; non-pinned tabs keep the process prompt.
       const isLastPane = (managerRef.current?.getPanes().length ?? 0) <= 1
       if (isLastPane) {
         const state = useAppStore.getState()
@@ -1458,10 +1296,7 @@ export default function TerminalPane({
             setPendingCloseConfirmation({ paneId, copyKind: getCloseDialogCopyKind(paneId) })
           }
         })
-        // Why: if the child-process probe rejects (IPC wedged, handler
-        // missing on legacy providers), fall back to closing the pane — Cmd+W
-        // silently doing nothing is worse than closing a pane that might have
-        // had a child process. Matches the semantics of the !ptyId branch above.
+        // Why: if the child-process probe rejects (wedged IPC, legacy provider), close anyway — Cmd+W doing nothing is worse than closing a pane with a child.
         .catch(() => executeClosePane(paneId))
     },
     [executeClosePane, tabId, worktreeId, getCloseDialogCopyKind]
@@ -1607,9 +1442,7 @@ export default function TerminalPane({
     if (!manager || !restoredLayout.root) {
       return
     }
-    // Host-owned split layouts (web clients, or a desktop client viewing a
-    // remote server worktree) arrive via the host snapshot, so the reconciler
-    // must materialize their panes; local desktop tabs split directly.
+    // Why: host-owned split layouts (web / remote-server) arrive via snapshot, so the reconciler materializes their panes; local tabs split directly.
     if (
       !isHostAuthoritativeLayout({
         isWebClient: !!(globalThis as { __ORCA_WEB_CLIENT__?: boolean }).__ORCA_WEB_CLIENT__,
@@ -1633,11 +1466,8 @@ export default function TerminalPane({
       if (!ptyId || sourcePaneId === null || manager.getNumericIdForLeaf(insertion.newLeafId)) {
         continue
       }
-      // Why: paired web terminals receive host split-pane snapshots after the
-      // pane manager is already mounted. Adopt the host leaf + PTY instead of
-      // spawning a local-only web pane.
-      // Before-placement swaps [source, new] after splitPane, so invert the
-      // host first-child ratio before applying it to the temporary order.
+      // Why: host split-pane snapshots for paired web terminals arrive after mount, so adopt the host leaf + PTY instead of spawning a local-only web pane.
+      // Before-placement swaps [source, new] after splitPane, so invert the host first-child ratio for the temporary order.
       const splitRatio =
         insertion.ratio === undefined
           ? undefined
@@ -1675,23 +1505,11 @@ export default function TerminalPane({
     }
   }, [isActive, paneCount, persistLayoutSnapshot, restoredLayout])
 
-  // Why (Activity-only pane isolation): when this TerminalPane is being
-  // portaled into the Activity page for a specific agent pane, hide the
-  // other split siblings so the user only sees that agent's pane. Uses
-  // applyExpandedLayoutTo with a separate snapshot ref so the override is
-  // independent of the user-facing expanded-pane state and the persisted
-  // layout snapshot — closing Activity restores the original split layout.
-  // useLayoutEffect: layout style writes must land before paint to avoid
-  // a flash of all panes. paneCount is in deps so the effect re-applies
-  // after splits/closes change the manager's pane list.
+  // Activity-only isolation: when portaled into Activity for one agent pane, hide split siblings via a separate snapshot ref (independent of expand state).
+  // useLayoutEffect so style writes land before paint (no flash); paneCount in deps re-applies after splits/closes.
   useLayoutEffect(() => {
     const snapshots = activityIsolationSnapshotRef.current
-    // Why: refit on rAF so xterm measures the post-layout DOM, not the
-    // pre-toggle one. Mirrors expand-collapse.refreshPaneSizes. Both the
-    // apply and restore paths must refit — restoring without a fit leaves
-    // xterm sized for the isolated single-pane geometry, so the workspace
-    // view (or staging slot) renders at the wrong cols/rows until some
-    // unrelated event triggers another fit.
+    // Why: refit on rAF so xterm measures the post-layout DOM; both apply and restore paths must refit or xterm stays sized for the isolated single-pane geometry.
     const scheduleRefit = (): number =>
       requestAnimationFrame(() => {
         const manager = managerRef.current
@@ -1724,8 +1542,7 @@ export default function TerminalPane({
       restoreExpandedLayoutFrom(snapshots)
       const root = containerRef.current?.firstElementChild
       if (root instanceof HTMLElement) {
-        // Why: Activity requested an exact pane. If it cannot be resolved, fail
-        // closed instead of showing the whole split terminal as a fallback.
+        // Why: Activity requested an exact pane; if it can't be resolved, fail closed rather than show the whole split terminal.
         snapshots.set(root, { display: root.style.display, flex: root.style.flex })
         root.style.display = 'none'
       }
@@ -1740,9 +1557,7 @@ export default function TerminalPane({
     }
   }, [isolatedPaneKey, paneCount, tabId])
 
-  // Why: belt-and-suspenders unmount cleanup. If the component unmounts
-  // while isolation is active (e.g. tab closed mid-Activity-view), restore
-  // sibling display/flex so the captured DOM doesn't leak inline styles.
+  // Why: on unmount while isolation is active (e.g. tab closed mid-Activity), restore sibling display/flex so the captured DOM doesn't leak inline styles.
   useEffect(() => {
     const snapshots = activityIsolationSnapshotRef.current
     return () => {
@@ -1766,10 +1581,7 @@ export default function TerminalPane({
       if (existingPtyId) {
         suppressPtyExit(existingPtyId)
         clearCodexRestartNotice(existingPtyId)
-        // Why: pane-scoped Codex restarts should preserve the split layout and
-        // replace only the stale session in place. Clearing the PTY binding and
-        // consuming the upcoming suppressed exit keeps the pane mounted while a
-        // fresh PTY reconnects under the newly selected Codex account.
+        // Why: keep the pane mounted (clear binding, consume the suppressed exit) so a fresh PTY reconnects in place under the newly selected Codex account.
         clearTabPtyId(tabId, existingPtyId)
       }
 
@@ -1855,9 +1667,7 @@ export default function TerminalPane({
       if (!ptyId || !pendingCodexPaneRestartIds[ptyId]) {
         continue
       }
-      // Why: the status-bar switcher can request a global restart for stale
-      // Codex sessions, but the actual execution must stay pane scoped so a
-      // split tab does not lose unrelated non-Codex panes.
+      // Why: the status-bar switcher requests a global Codex restart, but execution stays pane-scoped so a split tab doesn't lose unrelated non-Codex panes.
       if (consumePendingCodexPaneRestart(ptyId)) {
         handleRestartCodexPane(pane.id)
       }
@@ -1898,18 +1708,13 @@ export default function TerminalPane({
 
   useTerminalPaneGlobalEffects({
     tabId,
-    // Why: use the pane's own `worktreeId` prop (not global activeWorktreeId)
-    // so the terminal-drop resolver routes to the worktree that actually owns
-    // this PTY. Reading from global state would race during worktree switches
-    // — the drop listener is already gated by `isActive`, and the pane's own
-    // id is the authoritative identity of the terminal being written to.
+    // Why: use the pane's own worktreeId prop, not global activeWorktreeId, so terminal-drop routes to this PTY's worktree without racing worktree switches.
     worktreeId,
     cwd,
     isActive,
     isVisible,
     isWorktreeActive,
-    // Why: hidden startup probes are opacity-hidden but measurable; ordinary
-    // hidden tabs are display:none and refit on visibility resume instead.
+    // Why: hidden startup probes are opacity-hidden but measurable; ordinary hidden tabs are display:none and refit on visibility resume.
     isSyncFitEnabled: isRendererVisible || shouldMeasureHiddenStartup,
     paneCount,
     managerRef,
@@ -1945,13 +1750,11 @@ export default function TerminalPane({
           if (!ptyId) {
             return
           }
-          // Why: match pty-connection resize guards so web refit retries do not
-          // forward SIGWINCH while mobile-lock or phone-fit overrides are active.
+          // Why: match pty-connection resize guards so web refits don't forward SIGWINCH during mobile-lock or phone-fit overrides.
           if (getFitOverrideForPty(ptyId) || isPtyLocked(ptyId)) {
             return
           }
-          // Why: skip forwarding a stale near-zero fit to the host PTY while the
-          // overlay is still settling after a worktree switch.
+          // Why: skip forwarding a stale near-zero fit to the host PTY while the overlay is still settling after a worktree switch.
           if (pane.terminal.cols < 8 || pane.terminal.rows < 4) {
             return
           }
@@ -1968,8 +1771,7 @@ export default function TerminalPane({
       cleanupCallbacks.push(() => window.clearTimeout(timerId))
     }
 
-    // Why: web-restored terminals can fit before the remote PTY transport is
-    // ready, then become xterm no-ops. Forward the settled cols explicitly.
+    // Why: web-restored terminals can fit before the remote PTY transport is ready (xterm no-op), so forward the settled cols explicitly.
     scheduleFrame()
     scheduleTimer(50)
     scheduleTimer(150)
@@ -1990,9 +1792,7 @@ export default function TerminalPane({
     }
     let ownsRegularTerminalFocus = false
     let releasedHelperOnWindowBlur: HTMLElement | null = null
-    // Why: the IME refresh's synchronous blur emits a focusout that would flip
-    // terminalInputFocused false mid-handoff; latch it so the main process keeps
-    // routing Terminal-first shortcuts until the refocus lands.
+    // Why: the IME refresh's blur emits a focusout that would clear terminalInputFocused mid-handoff; latch it so Terminal-first shortcut routing survives until refocus.
     let refreshingImeInputContext = false
     const syncFocused = (focused: boolean): void => {
       ownsRegularTerminalFocus = focused
@@ -2007,9 +1807,7 @@ export default function TerminalPane({
         return
       }
       syncFocused(true)
-      // Why: helper→helper pane handoffs skip window blur and can leave a stale
-      // macOS NSTextInputContext; the refresh's refocus arrives with a
-      // non-helper relatedTarget, so this cannot recurse.
+      // Why: helper→helper handoffs skip window blur and can leave a stale macOS NSTextInputContext; the refocus's non-helper relatedTarget prevents recursion.
       if (isXtermHelperTextarea(event.relatedTarget) && event.relatedTarget !== event.target) {
         refreshingImeInputContext = true
         try {
@@ -2040,8 +1838,7 @@ export default function TerminalPane({
       })
     }
     const onWindowBlur = (): void => {
-      // Why: webview/browser handoff leaves the helper textarea as DOM focus,
-      // so clear only the main-process mirror and let guest focus proceed.
+      // Why: webview/browser handoff keeps the helper textarea focused, so clear only the main-process mirror and let guest focus proceed.
       releasedHelperOnWindowBlur = releaseTerminalFocusForWindowBlur({
         container,
         activeElement: document.activeElement,
@@ -2049,8 +1846,7 @@ export default function TerminalPane({
       })
     }
     const onWindowFocus = (): void => {
-      // Why: app reactivation can preserve DOM focus on xterm after blur
-      // cleared the process-wide shortcut mirror, or move focus to body/null.
+      // Why: app reactivation may keep DOM focus on xterm after blur cleared the shortcut mirror, or move focus to body/null.
       if (
         resyncTerminalFocusForWindowFocus({
           container,
@@ -2080,26 +1876,15 @@ export default function TerminalPane({
       document.removeEventListener('pointerdown', onPointerDown, true)
       window.removeEventListener('blur', onWindowBlur)
       window.removeEventListener('focus', onWindowFocus)
-      // Why: the helper textarea may be removed before cleanup observes
-      // document.activeElement, so clear by this pane's mirrored ownership.
+      // Why: the helper textarea may be gone before cleanup reads document.activeElement, so clear by this pane's mirrored ownership.
       if (ownsRegularTerminalFocus) {
         syncFocused(false)
       }
     }
   }, [])
 
-  // Intercept paste at the keydown level (configurable terminal paste chords)
-  // AND as a fallback
-  // on the paste event. We must handle keydown because Chromium does not fire
-  // a paste event when the clipboard contains only image data (no text
-  // representation) and the target is a textarea — which is exactly how
-  // xterm.js receives focus. Without the keydown handler, image-only pastes
-  // are silently discarded and tools like Claude Code never receive the image.
-  //
-  // The paste event handler is kept as a fallback for non-keyboard paste
-  // triggers (Edit > Paste menu, programmatic paste, etc.) and also bypasses
-  // Chromium's native clipboard pipeline that can cause concurrent clipboard
-  // reads by CLI tools (e.g. Codex checking for images) to fail intermittently.
+  // Intercept paste at keydown: Chromium fires no paste event for image-only clipboard on a textarea (xterm's focus target), so image pastes would be lost.
+  // Paste-event handler is a fallback for non-keyboard triggers; it also bypasses Chromium's clipboard pipeline that intermittently fails concurrent CLI reads.
   useEffect(() => {
     if (!isActive) {
       return
@@ -2245,9 +2030,7 @@ export default function TerminalPane({
       )
       if (!matchesPaste) {
         if (shouldSuppressNativePaste(e)) {
-          // Why: bare Ctrl+V is readline's quote-insert on Windows/Linux. If
-          // Chromium turns it into a native paste event, suppress that follow-up
-          // paste while still letting xterm receive the original keydown.
+          // Why: bare Ctrl+V is readline's quote-insert on Windows/Linux; suppress the native paste Chromium may add while letting xterm keep the keydown.
           suppressNextNativePaste = true
           if (pasteSuppressionTimerId !== null) {
             window.clearTimeout(pasteSuppressionTimerId)
@@ -2280,8 +2063,7 @@ export default function TerminalPane({
       pasteFromClipboard(pane, 'keyboard')
     }
 
-    // Fallback: handle paste events triggered by non-keyboard sources
-    // (Edit > Paste menu, programmatic paste, etc.).
+    // Fallback: paste events from non-keyboard sources (Edit > Paste menu, programmatic paste, etc.).
     const onPaste = (e: ClipboardEvent): void => {
       const target = e.target
       if (
@@ -2367,22 +2149,8 @@ export default function TerminalPane({
     }
   }, [isActive, worktreeId, keybindings, forceBracketedMultilineTextPaste, tabId])
 
-  // Why: a click inside the terminal container is a deliberate interaction
-  // with the pane — dismiss the attention indicator for this tab and worktree
-  // (ghostty "show until interact" semantics). onData already covers
-  // keystrokes; pointerdown covers the mouse path, including right-click
-  // and middle-click paste, which also count as engagement with the pane.
-  //
-  // This listener is intentionally NOT gated on `isActive`. In multi-group
-  // split layouts (TabGroupPanel), several TerminalPane instances are
-  // simultaneously visible but only ONE has `isActive=true` (the focused
-  // group's active pane). When the user clicks into a visible-but-inactive
-  // split pane, TabGroupPanel's wrapper `onPointerDown={commands.focusGroup}`
-  // fires first; focusGroup clears tab-level unread but does NOT call
-  // clearWorktreeUnread — so the worktree-level sidebar dot would linger
-  // until another interaction. Attaching this listener unconditionally lets
-  // the first click dismiss both dots BEFORE focusGroup re-renders the pane
-  // as active and the effect deps change.
+  // Dismiss the pane's attention indicator on click (ghostty "show until interact"); pointerdown covers the mouse path onData doesn't.
+  // NOT gated on isActive: clicking a visible-but-inactive split pane must clear the worktree dot before focusGroup re-renders it active.
   useEffect(() => {
     const container = containerRef.current
     if (!container) {
@@ -2417,16 +2185,13 @@ export default function TerminalPane({
     return subscribeTerminalPaneAttention(tabId, applyTerminalPaneAttention)
   }, [tabId, paneCount, applyTerminalPaneAttention])
 
-  // Sync the pane title reservation before paint. Text/banner chrome stays
-  // outside xterm's DOM, but xterm must still fit below it so the first
-  // terminal row is never hidden under meaningful status UI.
+  // Sync title reservation before paint so xterm fits below out-of-DOM banner chrome and never hides the first row.
   useLayoutEffect(() => {
     const manager = managerRef.current
     if (!manager) {
       return
     }
-    // Show title space only for text/status chrome. Chromeless pane controls
-    // float over xterm so untitled panes keep their first row.
+    // Reserve title space only for text/status chrome; chromeless controls float over xterm so untitled panes keep their first row.
     const needsFit = syncSessionRestoredBannerTitleSpace({
       panes: manager.getPanes(),
       paneTitles,
@@ -2434,8 +2199,7 @@ export default function TerminalPane({
       sessionRestoredBannerPaneIds
     })
     if (needsFit && (isVisible || shouldMeasureHiddenStartup)) {
-      // Why: fitting hidden geometry changes PTY rows and wakes TUIs with
-      // SIGWINCH; the visible resume path owns any real layout correction.
+      // Why: fitting hidden geometry changes PTY rows and wakes TUIs via SIGWINCH; the visible resume path owns real layout correction.
       fitPanes(manager)
     }
   }, [
@@ -2492,9 +2256,7 @@ export default function TerminalPane({
       })
     }
 
-    // Why: the title UI is React-owned now, not a child of the xterm pane.
-    // Track pane geometry explicitly so it still appears attached to each
-    // split pane while avoiding xterm/Radix focus fights inside the pane DOM.
+    // Why: the title UI is React-owned (outside the xterm DOM), so track pane geometry to keep it attached without xterm/Radix focus fights.
     syncPaneTitleOverlayRects()
     const resizeObserver = new ResizeObserver(scheduleSync)
     resizeObserver.observe(container)
@@ -2530,8 +2292,7 @@ export default function TerminalPane({
     })
   }, [paneCount])
 
-  // Register a capture callback for shutdown. The beforeunload handler in
-  // App.tsx calls all registered callbacks to serialize terminal buffers.
+  // Register a shutdown capture callback; App.tsx's beforeunload handler invokes all to serialize terminal buffers.
   useEffect(() => {
     const captureBuffers = (options?: { includeLocalBuffers?: boolean }): void => {
       const manager = managerRef.current
@@ -2543,12 +2304,7 @@ export default function TerminalPane({
       if (panes.length === 0) {
         return
       }
-      // Why: setTabLayout REPLACES — it doesn't merge. captureBuffers can
-      // run during a transient window (post-remount, just-attached,
-      // mid-replay) where xterm hasn't rendered yet so serialize returns 0
-      // bytes. Without preservation, that empty pass would wipe a known-good
-      // buffer. Merge prior state in for leaves whose live capture came back
-      // empty. Same shape as persistLayoutSnapshot.
+      // Why: setTabLayout REPLACES, not merges; a transient empty capture (xterm not yet rendered) would wipe a known-good buffer, so merge prior state for empty leaves.
       const state = useAppStore.getState()
       const existing = state.terminalLayoutsByTabId[tabId]
       const includeLocalBuffers = options?.includeLocalBuffers ?? true
@@ -2562,8 +2318,7 @@ export default function TerminalPane({
         paneTransports: paneTransportsRef.current,
         paneTitlesByPaneId: paneTitlesRef.current,
         existingLayout: existing,
-        // Why: beforeunload skips local/floating bytes because session payloads
-        // immediately prune them; worktree sleep keeps them as defense-in-depth.
+        // Why: beforeunload skips local/floating bytes (session payloads prune them); worktree sleep keeps them as defense-in-depth.
         captureBuffers: shouldCaptureScrollbackBuffers,
         clearedScrollbackLeafIds: clearedScrollbackLeafIdsRef.current
       })
@@ -2574,8 +2329,7 @@ export default function TerminalPane({
     }
     shutdownBufferCaptures.set(tabId, captureBuffers)
     return () => {
-      // Why: only remove if the entry still points at this closure. A
-      // remount could have replaced it before the prior cleanup ran.
+      // Why: only remove if the entry still points at this closure; a remount may have replaced it first.
       if (shutdownBufferCaptures.get(tabId) === captureBuffers) {
         shutdownBufferCaptures.delete(tabId)
       }
@@ -2623,10 +2377,7 @@ export default function TerminalPane({
       return
     }
     setPaneTitles((prev) => ({ ...prev, [renamingPaneId]: trimmed }))
-    // Eagerly update the ref so persistLayoutSnapshot (which reads
-    // paneTitlesRef.current) sees the new title immediately, without
-    // waiting for React to re-render and assign it during the next
-    // render pass.
+    // Eagerly update the ref so persistLayoutSnapshot sees the new title before React's next render.
     paneTitlesRef.current = { ...paneTitlesRef.current, [renamingPaneId]: trimmed }
     const leafId = managerRef.current?.getPanes().find((pane) => pane.id === renamingPaneId)?.leafId
     if (leafId) {
@@ -2658,8 +2409,7 @@ export default function TerminalPane({
 
     const sessionId = renameSessionIdRef.current
     const paneId = renamingPaneId
-    // Why: the context-menu selection can be followed by a delayed Radix/xterm
-    // focus handoff. That synthetic early blur is not a title submission.
+    // Why: a delayed Radix/xterm focus handoff after context-menu selection fires a synthetic blur that isn't a title submission.
     renameRefocusFrameRef.current = requestAnimationFrame(() => {
       renameRefocusFrameRef.current = null
       if (renameSessionIdRef.current !== sessionId || renamingPaneId !== paneId) {
@@ -2672,8 +2422,7 @@ export default function TerminalPane({
       }
       input.focus()
       input.select()
-      // Why: if the OS/browser refuses this focus request, still do not
-      // submit. Synthetic focus loss is not a title-commit signal.
+      // Why: even if the OS refuses this focus, don't submit — synthetic focus loss isn't a title-commit signal.
       renameBlurCommitEnabledRef.current = true
     })
   }, [handleRenameSubmit, renamingPaneId])
@@ -2683,8 +2432,7 @@ export default function TerminalPane({
     [removePaneTitle]
   )
 
-  // Auto-focus and select-all in the rename input when the dialog opens.
-  // Also reset the submit guard so the new rename session can accept input.
+  // Auto-focus/select-all the rename input on open and reset the submit guard for the new session.
   useEffect(() => {
     if (renamingPaneId === null) {
       return
@@ -2769,18 +2517,15 @@ export default function TerminalPane({
   }, [])
 
   const scheduleRestoredTerminalRefit = useCallback((): void => {
-    // Why: desktop-fit events can clear runtime state before xterm has repainted;
-    // restore actions get one settled-frame pass that does not depend on focus.
+    // Why: desktop-fit events can clear runtime state before xterm repaints, so schedule a settled-frame refit that doesn't depend on focus.
     requestAnimationFrame(refitAndRefreshAllTerminalPanes)
     window.setTimeout(refitAndRefreshAllTerminalPanes, 100)
   }, [])
 
   const restorePaneTerminalFit = useCallback(
     async (pane: ManagedPane, ptyId: string): Promise<void> => {
-      // Why: local and remote runtime PTYs use different transports, but the
-      // desktop reclaim button should have one visible recovery behavior.
-      // Why: the banner was rendered for this PTY; stale portals must disappear
-      // before they can reclaim a different terminal that reused this pane slot.
+      // Why: local and remote runtime PTYs use different transports but share one reclaim behavior.
+      // Why: the banner was rendered for this PTY; if the slot now holds a different terminal, bail so a stale portal can't reclaim it.
       const currentPtyId = paneTransportsRef.current.get(pane.id)?.getPtyId() ?? null
       if (currentPtyId !== ptyId) {
         setOverrideTick((n) => n + 1)
@@ -2789,8 +2534,7 @@ export default function TerminalPane({
       const restored = await restoreTerminalFitToDesktop(ptyId, settingsRef.current ?? undefined)
       if (restored) {
         scheduleRestoredTerminalRefit()
-        // Why: after the overlay unmounts, focus would otherwise stay on the
-        // removed button/body instead of the terminal the user just reclaimed.
+        // Why: after the overlay unmounts, refocus the reclaimed terminal instead of the removed button/body.
         pane.terminal.focus()
       }
     },
@@ -2799,8 +2543,7 @@ export default function TerminalPane({
 
   const restoreAllTerminalFits = useCallback(
     async (focusPane: ManagedPane): Promise<void> => {
-      // Why: a mobile session can leave multiple PTYs held at phone size; bulk
-      // restore follows the same reclaim path as the per-pane button.
+      // Why: bulk restore follows the same reclaim path as the per-pane button for PTYs held at phone size.
       const restored = await restoreTerminalFitsToDesktop(
         getMobileOwnedTerminalPtyIds(),
         settingsRef.current ?? undefined
@@ -2975,8 +2718,7 @@ export default function TerminalPane({
     : null
   const terminalBackground =
     settings?.terminalColorOverrides?.background ?? effectiveAppearance?.theme?.background
-  // Why: app light/dark mode can diverge from the selected terminal theme, so
-  // pane-title contrast follows the effective terminal surface instead.
+  // Why: app light/dark can diverge from the terminal theme, so pane-title contrast follows the effective terminal surface.
   const titleUsesLightSurface = isTerminalBackgroundLight(terminalBackground, {
     appSurface: effectiveAppearance?.mode,
     backgroundOpacity: settings?.terminalBackgroundOpacity
@@ -2992,12 +2734,9 @@ export default function TerminalPane({
     ? { opacity: 0, pointerEvents: 'none' }
     : {}
   const terminalContainerStyle: CSSProperties = {
-    // Why: split groups can keep one terminal visible in an unfocused group so
-    // users still see its output while typing elsewhere. Hiding on `isActive`
-    // blanked the previously focused pane and exposed the white group body.
+    // Why: unfocused split groups keep a terminal visible; gating on isActive blanked the prior pane and exposed the white group body.
     display: terminalContentVisible ? 'flex' : 'none',
-    // Why: split divider lines intentionally overdraw inside the pane tree.
-    // `hidden` reliably clips that pseudo-element paint at the terminal body.
+    // Why: split dividers overdraw into the pane, so overflow:hidden clips that pseudo-element paint at the terminal body.
     overflow: 'hidden',
     ...hiddenStartupStyle,
     ['--orca-terminal-divider-color' as string]:
@@ -3057,9 +2796,7 @@ export default function TerminalPane({
   const activePaneIsChatLeaf = Boolean(
     isChatViewMode && activePane?.leafId && activePane.leafId === chatLeafId
   )
-  // Header toggle gates on the active leaf; the context-menu toggle gates on the
-  // leaf the menu was opened over — so a split mixing supported/unsupported
-  // agents shows the toggle only on the leaf that can actually render chat.
+  // Each toggle gates on its own leaf (header=active, menu=opened-over), so mixed splits show it only where chat can render.
   const activePaneCanToggleChat = canToggleChatForLeaf(activePane?.leafId ?? null)
   const contextMenuCanToggleChat = canToggleChatForLeaf(contextMenuLeafId)
   return (
@@ -3277,27 +3014,19 @@ export default function TerminalPane({
         onRenameBlur={handleRenameBlur}
       />
       {managedPanes.map((pane) => {
-        // Why: pane IDs can collide across tabs (e.g. tab 0 pane 1 and tab 1
-        // pane 1). Using the transport's actual ptyId avoids showing banners
-        // on the wrong pane when IDs overlap.
+        // Why: pane IDs collide across tabs, so key overlays by the transport's actual ptyId to avoid wrong-pane banners.
         const ptyId = paneTransportsRef.current.get(pane.id)?.getPtyId()
         if (!ptyId) {
           return null
         }
-        // Why: two-state lock UI. (1) Driver is mobile → presence-lock,
-        // input paused (docs/mobile-presence-lock.md). (2) No mobile driver
-        // but a phone-fit override is still in place → indefinite hold
-        // (docs/mobile-fit-hold.md). MobileDriverOverlay owns the visual
-        // treatment and collapse-to-chip state; both branches share the
-        // same local/remote desktop-restore route.
+        // Why: two-state lock — mobile driver → presence-lock (docs/mobile-presence-lock.md); phone-fit override → indefinite hold (docs/mobile-fit-hold.md).
         const driver = getDriverForPty(ptyId)
         const fitMode = getFitOverrideForPty(ptyId)?.mode ?? null
         const hasFitOverride = fitMode === 'mobile-fit'
         if (!shouldShowMobileDriverOverlay(driver.kind, fitMode)) {
           return null
         }
-        // Why: only the pane replaced by native chat should hide terminal-owned
-        // presence-lock/phone-fit chrome; sibling splits remain normal terminals.
+        // Why: only the chat-replaced pane hides presence-lock/phone-fit chrome; sibling splits stay normal terminals.
         const paneSurface =
           effectiveChatViewMode && pane.leafId === chatLeafId ? 'chat' : 'terminal'
         if (shouldChatTakeOverMobileSurface(paneSurface)) {
diff --git a/src/renderer/src/components/terminal-pane/agent-completion-coordinator.ts b/src/renderer/src/components/terminal-pane/agent-completion-coordinator.ts
index f71141e1045..a57f4bb1fdd 100644
--- a/src/renderer/src/components/terminal-pane/agent-completion-coordinator.ts
+++ b/src/renderer/src/components/terminal-pane/agent-completion-coordinator.ts
@@ -33,39 +33,23 @@ type LastCompletionIdentity = {
   agentIdentity: string | null
 }
 
-// Why: worktree switches can remount a pane while the underlying PTY and hook
-// stream stay live, so stale completion replays must outlive one coordinator.
+// Why: worktree switches remount a pane while the PTY/hook stream stays live, so stale completion replays must outlive one coordinator.
 const lastCompletionIdentityByPaneKey = new Map<string, LastCompletionIdentity>()
 
 const IDLE_POLL_INTERVAL_MS = 2_000
 const ACTIVE_POLL_INTERVAL_MS = 750
-// Why: a hidden pane only keeps the process-exit backstop alive — hook and title
-// completion signals are push-driven and fire regardless of poll cadence or
-// visibility — so it polls the OS process table far less often to cut idle CPU on
-// shared SSH relays. Follow-up to #6288 / PR #6667, which deduped scans within a
-// tick; this throttles the number of ticks. Visible panes keep full cadence.
+// Why: a hidden pane only needs the process-exit backstop (hook/title are push-driven), so poll the process table far less to cut idle CPU on SSH relays (#6288/#6667).
 const HIDDEN_POLL_INTERVAL_MS = 3_000
-// Why: on hosts where one inspection is a whole-process-table scan (local
-// Windows forks a powershell.exe CIM query, ~10-40x heavier than POSIX `ps`),
-// a visible idle shell with no agent evidence must not pay that every 2s
-// forever. It relaxes to this cadence; output/title/hook activity re-arms the
-// hot cadence (see NO_EVIDENCE_ACTIVITY_HOT_WINDOW_MS), so agent starts are
-// detected event-driven rather than by burning idle scans.
+// Why: where one inspection is a whole-process-table scan (Windows powershell CIM, ~10-40x heavier than `ps`), a no-evidence idle shell relaxes here; activity re-arms.
 const NO_EVIDENCE_POLL_INTERVAL_MS = 15_000
-// Why: pane activity (PTY output, title change, hook) means an agent may be
-// starting; poll at the full idle cadence this long after the last activity so
-// agent-start detection stays prompt without keeping idle panes hot.
+// Why: pane activity means an agent may be starting; keep full idle cadence this long after it so agent-start detection stays prompt.
 const NO_EVIDENCE_ACTIVITY_HOT_WINDOW_MS = 10_000
 const INSPECTION_TIMEOUT_MS = 15_000
 const PENDING_TITLE_TTL_MS = Math.max(2_000, INSPECTION_TIMEOUT_MS + 500)
 const PENDING_TITLE_MAX_TTL_MS = Math.max(30_000, PENDING_TITLE_TTL_MS)
 const COMPLETION_REPLAY_GUARD_MS = 1_000
 const HOOK_DONE_QUIET_MS = 1_500
-// Why: Codex fires its PermissionRequest hook at the human-input boundary before
-// the approval decision, so under "Approve for me" the review agent approves and
-// Codex resumes almost immediately. Debounce the OS attention notification behind
-// this quiet window so a self-resolving pause never raises a false "approval
-// required" banner (issue #8387). The visual status still updates immediately.
+// Why: under "Approve for me" Codex resumes almost immediately, so debounce the OS attention notification so a self-resolving pause raises no false banner (#8387).
 const CODEX_ATTENTION_QUIET_MS = 1_500
 
 const POLL_TIER_INTERVAL_MS: Record<PollCadenceTier, number> = {
@@ -76,16 +60,12 @@ const POLL_TIER_INTERVAL_MS: Record<PollCadenceTier, number> = {
 }
 
 function isCompletionHookState(state: ParsedAgentStatusPayload['state']): boolean {
-  // Why: only a genuine 'done' ends a turn. 'waiting'/'blocked' are handled by
-  // isAttentionHookState below.
+  // Why: only a genuine 'done' ends a turn; 'waiting'/'blocked' go through isAttentionHookState.
   return state === 'done'
 }
 
 function isAttentionHookState(state: ParsedAgentStatusPayload['state']): boolean {
-  // Why: 'waiting' (e.g. a Claude PermissionRequest) and 'blocked' (e.g. a
-  // Copilot elicitation dialog) pause mid-turn — the agent is still alive and
-  // has not completed, so they must not fire agent-task-complete. The "needs
-  // you" notification for these states is raised separately (smart-attention).
+  // Why: 'waiting'/'blocked' pause mid-turn — the agent is still alive, so they must not fire agent-task-complete (attention is raised separately).
   return state === 'waiting' || state === 'blocked'
 }
 
@@ -126,13 +106,9 @@ export function createAgentCompletionCoordinator(
   let inspectionInFlight = false
   let inspectionGeneration = 0
   let consecutiveInspectionErrors = 0
-  // Why: output/title activity can arrive before async PTY bind; it should
-  // only re-arm cadence after the bind path starts process tracking.
+  // Why: output/title activity can arrive before async PTY bind; only re-arm cadence after bind starts process tracking.
   let pollTrackingStarted = false
-  // Why: tracks which cadence tier the armed poll timer was scheduled at, so a
-  // tier change toward a faster cadence (hidden→visible flip, no-evidence pane
-  // gaining activity or evidence) re-arms promptly instead of waiting out the
-  // long delay (scheduleNextPoll otherwise no-ops while a timer is pending).
+  // Why: cadence tier the armed poll timer was scheduled at, so a shift to a faster tier can re-arm promptly instead of waiting out the long delay.
   let pollTimerTier: PollCadenceTier | null = null
   let lastPaneActivityAt = 0
 
@@ -209,8 +185,7 @@ export function createAgentCompletionCoordinator(
   }
 
   function doneShouldUseQuietWindow(payload: AgentCompletionStatusSnapshot): boolean {
-    // Why: Pi/OMP emit milestone 'done' while still working, so route their done
-    // through the quiet window (like a resumed turn) so later work can cancel it.
+    // Why: Pi/OMP emit milestone 'done' while still working, so route it through the quiet window so later work can cancel it.
     return workingStatusObserved || isPiCompatibleAgentType(hookCompletionAgentIdentity(payload))
   }
 
@@ -318,8 +293,7 @@ export function createAgentCompletionCoordinator(
     lastCompletedTurn = currentTurn
     lastCompletionSource = source
     workingStatusObserved = false
-    // Why: any committed completion (hook/title/process-exit) ends the turn, so a
-    // debounced Codex attention from an earlier pause must never fire after it.
+    // Why: any committed completion ends the turn, so a debounced Codex attention from an earlier pause must not fire after it.
     clearPendingCodexAttention()
     if (optionsOverride.completionIdentity) {
       lastCompletionIdentityByPaneKey.set(options.paneKey, optionsOverride.completionIdentity)
@@ -328,8 +302,7 @@ export function createAgentCompletionCoordinator(
       options.dispatchHookLifecycle?.(optionsOverride.agentStatus)
     }
     if (optionsOverride.quietedHookDone === true || source === 'process-exit') {
-      // Why: confirmed process death is independent completion evidence; keep
-      // its provenance so stale hook rows cannot veto the notification later.
+      // Why: confirmed process death is independent completion evidence; keep its provenance so stale hook rows can't veto it later.
       options.dispatchCompletion(title, {
         source,
         quietedHookDone: optionsOverride.quietedHookDone === true,
@@ -357,14 +330,10 @@ export function createAgentCompletionCoordinator(
       return
     }
     lastAttentionToken = token
-    // Why: the visual "needs input" status must update immediately for every
-    // agent; only the OS attention notification is debounced (Codex, below).
+    // Why: the visual "needs input" status updates immediately; only the OS attention notification is debounced (Codex, below).
     options.dispatchHookLifecycle?.(payload)
     if (payload.agentType === 'codex') {
-      // Why: a Codex PermissionRequest that "Approve for me" auto-resolves fires a
-      // working/completion hook inside this window, which cancels the pending
-      // notification (see CODEX_ATTENTION_QUIET_MS). Scoped to Codex so every other
-      // agent's genuine pause still notifies immediately.
+      // Why: an auto-resolved Codex "Approve for me" cancels this pending notification via a later hook; scoped to Codex so other agents notify at once.
       clearPendingCodexAttention()
       pendingCodexAttentionTimer = setTimeout(() => {
         pendingCodexAttentionTimer = null
@@ -384,8 +353,7 @@ export function createAgentCompletionCoordinator(
     if (pendingHookDoneTimer !== null) {
       return
     }
-    // Why: goal/mission agents can report a temporary done state between
-    // milestones. Wait for a short quiet window so resumed work can cancel it.
+    // Why: goal/mission agents can report a temporary done between milestones; wait a short quiet window so resumed work can cancel it.
     pendingHookDoneTimer = setTimeout(() => {
       pendingHookDoneTimer = null
       const pendingTitle = pendingHookDoneTitle
@@ -466,8 +434,7 @@ export function createAgentCompletionCoordinator(
 
   function holdTitleCompletionPending(title: string): void {
     const now = Date.now()
-    // Why: generic spinner titles can be just "⠋ cwd"; hold the completion
-    // only long enough for one foreground-process probe to prove an agent owns it.
+    // Why: generic spinner titles can be just "⠋ cwd"; hold completion only until one probe proves an agent owns the pane.
     pendingTitle = {
       id: ++pendingTitleSequence,
       title,
@@ -511,18 +478,13 @@ export function createAgentCompletionCoordinator(
       return true
     }
     if (pendingHookDoneTimer !== null || pendingCodexAttentionTimer !== null) {
-      // Why: a pending quiet-window 'done' or debounced Codex attention is the
-      // authoritative signal for this turn; tearing down agent evidence here (a
-      // transient null/shell foreground blip before the agent process is
-      // recognized) would make the timer's hasAgentRunEvidence guard silently
-      // drop it. Keep the fail-open contract for #8387 as for the done timer.
+      // Why: a pending quiet-window 'done'/debounced attention is authoritative; don't drop agent evidence on a transient blip or the timer guard loses it (#8387).
       scheduleNextPoll()
       return false
     }
     if (lastForegroundAgent && hasAgentRunEvidence) {
       if (result.hasChildProcesses) {
-        // Why: Codex can briefly report a shell/null foreground while its TUI or
-        // child work is still alive; do not announce completion from that blip.
+        // Why: Codex can briefly report a shell/null foreground while still alive; don't announce completion from that blip.
         pendingProcessExitAgent = null
         scheduleNextPoll()
         return false
@@ -532,8 +494,7 @@ export function createAgentCompletionCoordinator(
         pendingProcessExitAgent.agent !== lastForegroundAgent.agent ||
         pendingProcessExitAgent.processName !== lastForegroundAgent.processName
       ) {
-        // Why: macOS process inspection can transiently report no foreground
-        // child during prompt handoff; require the idle sample to repeat.
+        // Why: macOS inspection can transiently report no foreground child during prompt handoff; require the idle sample to repeat.
         pendingProcessExitAgent = lastForegroundAgent
         scheduleNextPoll()
         return false
@@ -611,9 +572,7 @@ export function createAgentCompletionCoordinator(
                 }
                 schedulePendingTitleExpiry()
               } else {
-                // Why: only the probe requested for this exact pending title
-                // can prove it belongs to an agent; older in-flight probes are
-                // stale even when they were also pending-title inspections.
+                // Why: only the probe for this exact pending title can prove agent ownership; older in-flight probes are stale.
                 requestInspection('pending-title')
               }
             }
@@ -625,9 +584,7 @@ export function createAgentCompletionCoordinator(
   }
 
   function shouldRunCadenceInspection(): boolean {
-    // Why: hidden idle terminals should not join the global process-inspection
-    // cadence. Once a pane has agent evidence, keep the backstop alive so an
-    // unannounced process exit can still produce/clear completion state.
+    // Why: hidden idle terminals skip the global cadence, but once a pane has agent evidence keep the backstop for unannounced process exits.
     return (
       hasAgentRunEvidence ||
       lastForegroundAgent !== null ||
@@ -636,9 +593,7 @@ export function createAgentCompletionCoordinator(
   }
 
   function isHiddenBackstop(): boolean {
-    // Why: cadence runs as a hidden-pane backstop only when visibility is known
-    // to be false. An undefined option (coordinators with no visibility source)
-    // keeps full cadence, matching pre-throttle behavior.
+    // Why: only run as hidden backstop when visibility is known false; undefined (no visibility source) keeps full pre-throttle cadence.
     return options.shouldPollProcessCadence?.() === false
   }
 
@@ -658,8 +613,7 @@ export function createAgentCompletionCoordinator(
     if (hasAgentRunEvidence) {
       return 'idle'
     }
-    // Why: only costly hosts relax the no-evidence cadence; recent pane
-    // activity keeps it hot so an agent start is inspected promptly.
+    // Why: only costly hosts relax the no-evidence cadence; recent activity keeps it hot so an agent start is inspected promptly.
     if (options.isProcessInspectionCostly?.() === true && !paneActivityWithinHotWindow()) {
       return 'no-evidence'
     }
@@ -667,13 +621,11 @@ export function createAgentCompletionCoordinator(
   }
 
   function nextPollInterval(tier: PollCadenceTier): number {
-    // Why: a hidden pane polls slowly (backstop only); a visible pane keeps full
-    // cadence so the foreground experience is unchanged.
+    // Why: hidden panes poll slowly (backstop only); visible panes keep full cadence.
     const base = POLL_TIER_INTERVAL_MS[tier]
     const backoff =
       consecutiveInspectionErrors > 0
-        ? // Why: max(base, ...) keeps error backoff from *accelerating* tiers
-          // already slower than the 10s backoff ceiling (no-evidence is 15s).
+        ? // Why: max(base, ...) keeps error backoff from accelerating tiers already slower than the 10s ceiling (no-evidence is 15s).
           Math.min(Math.max(10_000, base), base * 2 ** consecutiveInspectionErrors)
         : base
     const jitter = 1 + (Math.random() * 0.2 - 0.1)
@@ -686,9 +638,7 @@ export function createAgentCompletionCoordinator(
     }
     const tier = currentPollTier()
     if (pollTimer !== null) {
-      // Why: a pane whose tier moved to a faster cadence (hidden pane became
-      // visible, no-evidence pane saw activity or evidence) has a slow timer
-      // armed; re-arm at the faster cadence now instead of waiting it out.
+      // Why: a pane whose tier moved to a faster cadence has a slow timer armed; re-arm now instead of waiting it out.
       if (
         pollTimerTier !== null &&
         POLL_TIER_INTERVAL_MS[tier] < POLL_TIER_INTERVAL_MS[pollTimerTier]
@@ -715,9 +665,7 @@ export function createAgentCompletionCoordinator(
 
   function recordPaneActivity(): void {
     lastPaneActivityAt = Date.now()
-    // Why: activity is the escalation signal that ends the relaxed no-evidence
-    // cadence — re-arm only when the armed timer is the slow tier (or none is
-    // armed) so per-output-chunk calls stay near-free on hot panes.
+    // Why: activity ends the relaxed no-evidence cadence; re-arm only when the armed timer is slow (or none) so per-chunk calls stay near-free.
     if (pollTimer === null || pollTimerTier === 'no-evidence') {
       scheduleNextPoll()
     }
@@ -728,8 +676,7 @@ export function createAgentCompletionCoordinator(
   }
 
   function recordTitleWorking(): boolean {
-    // Why: hooks can report `done` before title tracking notices the next
-    // milestone. The title working signal must cancel that provisional done.
+    // Why: hooks can report `done` before title tracking notices the next milestone, so the working title must cancel that provisional done.
     clearPendingHookDone()
     if (
       lastCompletionSource === 'hook' &&
@@ -737,11 +684,7 @@ export function createAgentCompletionCoordinator(
     ) {
       return false
     }
-    // Why: a genuine Codex resume can surface as a working-spinner title before
-    // (or instead of) the resume 'working' hook, so cancel the debounced
-    // attention here or the self-resolving pause still fires a false banner
-    // (#8387). Placed after the replay guard so only an authoritative resume —
-    // not a stale post-completion title replay — drops a still-pending banner.
+    // Why: cancel debounced attention when a Codex resume surfaces as a working title (else false banner #8387); placed after the replay guard so a stale post-completion replay can't drop it.
     clearPendingCodexAttention()
     workingStatusObserved = true
     requiresFreshWorking = false
@@ -776,9 +719,7 @@ export function createAgentCompletionCoordinator(
         return
       }
       if (status === null && !titleHasExplicitAgentIdentity(title)) {
-        // Why: shells commonly restore cwd titles right after a short printf
-        // command. Treat generic completion titles as provisional until process
-        // inspection proves an agent still owns the pane.
+        // Why: shells restore cwd titles after short commands; hold generic completion as provisional until inspection proves agent ownership.
         holdTitleCompletionPending(title)
         lastTitleStatus = status
         return
@@ -796,8 +737,7 @@ export function createAgentCompletionCoordinator(
         holdTitleCompletionPending(title)
       }
     } else if (hadPendingTitle && status !== null && hasExplicitAgentIdentity) {
-      // Why: a shell can briefly restore cwd between "Codex working" and
-      // "Codex done"; the later explicit agent completion is authoritative.
+      // Why: a shell can briefly restore cwd between working and done; the later explicit agent completion is authoritative.
       dropPendingTitle()
       markTitleCompletionNotified(title)
       dispatchCompletion('title', title, {
@@ -832,8 +772,7 @@ export function createAgentCompletionCoordinator(
   function observeHookStatus(payload: AgentCompletionStatusSnapshot): void {
     recordPaneActivity()
     if (options.shouldSuppressHookCompletion?.(payload)) {
-      // Why: a suppressed permission pause must still cancel a provisional 'done'
-      // so the quiet-window timer never fires a false completion notification.
+      // Why: a suppressed permission pause must still cancel a provisional 'done' so the quiet-window timer can't fire a false completion.
       if (isAttentionHookState(payload.state)) {
         clearPendingHookDone()
         clearPendingCodexAttention()
@@ -845,8 +784,7 @@ export function createAgentCompletionCoordinator(
     }
     if (payload.state === 'working') {
       clearPendingHookDone()
-      // Why: resumed work (e.g. Codex after "Approve for me") cancels the debounced
-      // attention notification so the self-resolving pause never notifies.
+      // Why: resumed work cancels the debounced attention so a self-resolving pause never notifies.
       clearPendingCodexAttention()
       workingStatusObserved = true
       requiresFreshWorking = false
@@ -858,15 +796,13 @@ export function createAgentCompletionCoordinator(
       return
     }
     if (isAttentionHookState(payload.state)) {
-      // Why: a permission/elicitation pause arriving before the quiet window
-      // must cancel a provisional 'done' so it never becomes a false completion.
+      // Why: a pause arriving before the quiet window must cancel a provisional 'done' so it never becomes a false completion.
       clearPendingHookDone()
       dispatchAttention(payload)
       return
     }
     if (isCompletionHookState(payload.state)) {
-      // Why: the turn is ending, so a debounced attention from an earlier pause in
-      // this turn must not fire after the completion notification.
+      // Why: the turn is ending, so a debounced attention from an earlier pause must not fire after completion.
       clearPendingCodexAttention()
       if (isRecognizedAgentType(payload.agentType)) {
         establishAgentEvidence()
@@ -877,8 +813,7 @@ export function createAgentCompletionCoordinator(
         lastCompletionIdentity?.source === 'hook' &&
         hookIdentity === lastCompletionIdentity.identity
       ) {
-        // Why: activation/switching can replay the same main-process hook snapshot
-        // after the 1s guard; only pending quiet-window detail should refresh.
+        // Why: activation/switching can replay the same hook snapshot after the 1s guard; only pending quiet-window detail should refresh.
         if (payload.state === 'done' && pendingHookDoneTimer !== null) {
           scheduleHookDoneCompletion(payload.agentType ?? options.paneKey, payload)
         }
@@ -890,9 +825,7 @@ export function createAgentCompletionCoordinator(
         lastCompletedTurn === currentTurn &&
         Date.now() - lastCompletionAt >= COMPLETION_REPLAY_GUARD_MS
       ) {
-        // Why: some hook producers only emit terminal states. Treat later
-        // done-only hook completions as new turns without letting title/process
-        // backstops duplicate the same completion.
+        // Why: some hook producers only emit terminal states; treat later done-only completions as new turns without backstop dupes.
         currentTurn += 1
       }
       if (payload.state === 'done' && doneShouldUseQuietWindow(payload)) {
@@ -962,10 +895,7 @@ export function createAgentCompletionCoordinator(
     clearPendingHookDone()
     clearPendingCodexAttention()
     dropPendingTitle()
-    // Why: the dedup identity is module-scoped so it survives a live-stream remount
-    // (dispose-then-recreate with the same paneKey while isLive() stays true). Only
-    // evict it on genuine teardown — when the PTY is gone (isLive() false) — so the
-    // never-reused ${tabId}:${leafUUID} key can't leak one identity per closed pane.
+    // Why: module-scoped identity survives a live-stream remount; evict only on genuine teardown (isLive() false) so it can't leak per closed pane.
     if (!options.isLive()) {
       lastCompletionIdentityByPaneKey.delete(options.paneKey)
     }
diff --git a/src/renderer/src/components/terminal-pane/hidden-reveal-reconciliation.fuzz.test.ts b/src/renderer/src/components/terminal-pane/hidden-reveal-reconciliation.fuzz.test.ts
index 0c855bac3c3..f5c55cc72cd 100644
--- a/src/renderer/src/components/terminal-pane/hidden-reveal-reconciliation.fuzz.test.ts
+++ b/src/renderer/src/components/terminal-pane/hidden-reveal-reconciliation.fuzz.test.ts
@@ -20,25 +20,11 @@ import {
   writeChunksToTerminal
 } from '../../../../shared/terminal-restore-parity-fixture'
 
-// Property fuzz for the hidden-reveal seq-reconciliation path in
-// pty-connection.ts. When a pane is hidden, main keeps metering PTY output as
-// seq'd chunks. On reveal the renderer applies a HeadlessEmulator snapshot
-// captured at seq S (paints everything <= S), then stitches the racing tail
-// (chunks straddling / after S) on top WITHOUT duplicating or losing a byte.
-// The byte arithmetic lives in two non-exported closures:
-//   - getChunkDataAfterSnapshot            (pty-connection.ts ~L4629): slices a
-//     pending chunk against the snapshot seq.
-//   - reconcileChunkAgainstRestoredSnapshot (pty-connection.ts ~L4660): dedups
-//     backlog, detects a restarted seq domain, and heals dropped-output gaps by
-//     forcing a fresh restore.
-// This suite mirrors those rules EXACTLY (each branch tagged with its source
-// line) and asserts the invariant they guarantee: for any reveal boundary,
-// snapshot(hidden prefix) + reconciled tail reproduces the same screen an
-// always-visible terminal shows for the full stream. A wrong slice = a garble.
+// Property fuzz for the hidden-reveal seq-reconciliation path in pty-connection.ts: a hidden pane's snapshot at seq S plus
+// the reconciled racing tail must reproduce the always-visible screen without duplicating or losing a byte. Mirrors the two
+// non-exported closures EXACTLY: getChunkDataAfterSnapshot (~L4629) and reconcileChunkAgainstRestoredSnapshot (~L4660).
 //
-// Runtime knobs:
-//   FUZZ_ITERATIONS=2000  deep/nightly (default 200, <60s with the fidelity suite)
-//   FUZZ_SEED=1234        re-run exactly one seed
+// Runtime knobs: FUZZ_ITERATIONS=2000 (default 200) deep/nightly; FUZZ_SEED=1234 re-run exactly one seed.
 
 const DEFAULT_ITERATIONS = 200
 const FIXED_SEED = readPositiveIntEnv('FUZZ_SEED')
@@ -55,10 +41,8 @@ const DIMS: readonly AgentTuiStreamDims[] = [
   { cols: 100, rows: 30 }
 ]
 
-/** A metered chunk exactly as main delivers to onData: text, the seq of the
- *  LAST raw byte, the raw (pre-OSC-strip) length, and delivery-domain markers.
- *  domain increments across a ptyId-exit seq restart (production clears the
- *  restored baseline at that boundary, so the tail writes verbatim). */
+/** A metered chunk as main delivers to onData: text, the seq of the LAST raw byte, the pre-OSC-strip length, and a
+ *  delivery domain that increments across a ptyId-exit seq restart (past which the tail writes verbatim). */
 type MeteredChunk = {
   data: string
   seq?: number
@@ -67,11 +51,8 @@ type MeteredChunk = {
   droppedOutput?: boolean
 }
 
-/** Mirror of getChunkDataAfterSnapshot (pty-connection.ts ~L4629): how much of
- *  a chunk in the SNAPSHOT'S seq domain survives once the snapshot at
- *  snapshotSeq has painted everything <= snapshotSeq. null = "cannot slice,
- *  force a fresh snapshot" (OSC stripping desynced raw offsets). Byte-identical
- *  to production; each return tagged with its branch. */
+/** Mirror of getChunkDataAfterSnapshot (pty-connection.ts ~L4629): how much of a snapshot-domain chunk survives once the
+ *  snapshot at snapshotSeq has painted; null = "cannot slice, force a fresh snapshot" (OSC stripping desynced raw offsets). */
 function chunkDataAfterSnapshot(
   chunk: MeteredChunk,
   snapshotSeq: number | undefined
@@ -95,23 +76,14 @@ function chunkDataAfterSnapshot(
 }
 
 type RevealResult = {
-  /** Full normal-buffer content (visible + scrollback, trailing blanks
-   *  trimmed). Viewport-independent: a byte lost or duplicated by reconciliation
-   *  changes this even when the visible viewport happens to line up. */
+  /** Full normal-buffer content (visible + scrollback, trailing blanks trimmed). Viewport-independent, so it catches a lost/duped byte even when the viewport lines up. */
   content: string[]
   rows: string[]
   styles: string[]
   cursor: { x: number; y: number }
-  /** True when the buffer scrolled (baseY > 0). The visible viewport's top
-   *  anchor after a snapshot restore vs continuous writing can differ by a row
-   *  or two purely from trailing-blank trimming — a snapshot-scrollback-depth
-   *  concern owned by the fidelity suite, not seq reconciliation — so styles and
-   *  cursor (viewport-relative) are only asserted on non-scrolled scenarios. */
+  /** True when the buffer scrolled (baseY > 0); styles/cursor are only asserted on non-scrolled scenarios (viewport anchor differs after a restore — a fidelity concern). */
   scrolled: boolean
-  /** True when the terminal ended on the alternate screen. Alt has no
-   *  scrollback and a fixed viewport, so its content is the visible rows and the
-   *  normal-buffer content comparison does not apply (the alt-screen restore
-   *  contract is scrollback-free by design — serializeHeadlessTerminalBuffer). */
+  /** True when the terminal ended on the alternate screen: alt has no scrollback, so the normal-buffer content comparison does not apply. */
   alternate: boolean
   forcedFreshRestore: boolean
   knownSerializeWrapBug: boolean
@@ -133,11 +105,8 @@ async function readScreen(
   }
 }
 
-/** The renderer's screen for a hide→reveal cycle. `revealIdx` is the delivery
- *  index at which the pane is revealed: chunks [0, revealIdx) were captured by
- *  the HeadlessEmulator snapshot; chunks [revealIdx, end) are the racing tail.
- *  The snapshot seq is the seq of the last hidden chunk in the snapshot's
- *  domain; the tail is stitched via the production slice/reconcile rules. */
+/** The renderer's screen for a hide→reveal cycle. `revealIdx` splits delivery: chunks [0, revealIdx) are captured by the
+ *  snapshot; chunks [revealIdx, end) are the racing tail stitched via the production slice/reconcile rules. */
 async function revealFromSnapshot(
   dims: AgentTuiStreamDims,
   chunks: MeteredChunk[],
@@ -149,8 +118,7 @@ async function revealFromSnapshot(
     // Snapshot source = every hidden chunk painted in order.
     const hiddenChunks = chunks.slice(0, revealIdx).map((c) => c.data)
     await writeChunksToTerminal(source.terminal, hiddenChunks)
-    // Snapshot seq = seq of the last hidden chunk that carried one (the seq the
-    // emulator would report). undefined when the hidden prefix was unmetered.
+    // Snapshot seq = seq of the last hidden metered chunk; undefined when the hidden prefix was unmetered.
     let snapshotSeq: number | undefined
     let snapshotDomain = 0
     for (let i = revealIdx - 1; i >= 0; i--) {
@@ -161,15 +129,12 @@ async function revealFromSnapshot(
       }
     }
     const snapshot = buildParityMainBufferSnapshot(source, snapshotSeq ?? 0, {
-      // Mirror of HeadlessEmulator's ingest tracker: the hidden stream's
-      // trailing incomplete escape rides the snapshot out-of-band (Bug E fix).
+      // The hidden stream's trailing incomplete escape rides the snapshot out-of-band (Bug E fix).
       pendingEscapeTail: extractPartialEscapeTail(hiddenChunks.join(''))
     })
     const alt = snapshot.alternateScreen
     const knownSerializeWrapBug = bufferHasSerializeHostileWrappedRow(source.terminal)
-    // Mirror of applyMainBufferSnapshot's write order: the pending escape tail
-    // is the FINAL replay write — any later ESC (e.g. the post-replay reset)
-    // would abort the dangling sequence before the racing tail completes it.
+    // The pending escape tail must be the FINAL replay write (mirrors applyMainBufferSnapshot); a later ESC would abort the dangling sequence.
     const preamble =
       alt && snapshot.scrollbackAnsi !== undefined
         ? `\x1b[?1049l\x1b[2J\x1b[3J\x1b[H${snapshot.scrollbackAnsi}${SNAPSHOT_REPLAY_PREAMBLE_ALT}`
@@ -183,10 +148,7 @@ async function revealFromSnapshot(
       ...(snapshot.pendingEscapeTailAnsi ? [snapshot.pendingEscapeTailAnsi] : [])
     ])
 
-    // Stitch the tail. A chunk in the snapshot's domain is sliced against the
-    // snapshot seq (drains the painted prefix); a chunk from a later domain
-    // (post-exit seq restart) writes verbatim — production clears the baseline
-    // at the ptyId-exit boundary, so no seq dedupe applies across domains.
+    // Stitch the tail: same-domain chunks slice against the snapshot seq; later-domain (post-exit-restart) chunks write verbatim (main clears the restored baseline at the ptyId-exit restart, so no cross-domain seq dedupe).
     let forcedFreshRestore = false
     for (let i = revealIdx; i < chunks.length; i++) {
       const chunk = chunks[i]!
@@ -196,9 +158,7 @@ async function revealFromSnapshot(
       }
       const sliced = chunkDataAfterSnapshot(chunk, snapshotSeq)
       if (sliced === null) {
-        // Production re-fetches a fresh snapshot here; a fresh snapshot of the
-        // full stream trivially matches the always-visible screen, so mark the
-        // scenario as a fresh-restore (excluded from the stitch comparison).
+        // Production re-fetches a fresh snapshot here; that trivially matches live, so exclude the scenario from the comparison.
         forcedFreshRestore = true
         continue
       }
@@ -232,11 +192,8 @@ async function alwaysVisible(
   }
 }
 
-/** Reference for the seq-reconciliation gate: a snapshot of the WHOLE stream
- *  (reveal at the very end, no racing tail). Sharing the snapshot machinery with
- *  revealFromSnapshot cancels out snapshot-fidelity gaps (Bug C cursor restore,
- *  Bug B bold loss — owned by the fidelity suite), so a diff against a mid-point
- *  reveal is attributable purely to the tail-stitch seq arithmetic. */
+/** Reference for the seq-reconciliation gate: a snapshot of the WHOLE stream (no racing tail). Sharing snapshot machinery with
+ *  revealFromSnapshot cancels out fidelity gaps (Bugs B/C), so a diff vs a mid-point reveal is purely tail-stitch arithmetic. */
 async function fullSnapshotReference(
   dims: AgentTuiStreamDims,
   chunks: MeteredChunk[]
@@ -263,19 +220,11 @@ const TAIL_WORDS = [
   '+142 -37',
   'diff --git'
 ] as const
-// Why no SGR 7 (inverse): inverse marks trailing BLANK cells with an
-// inverse-fg the serializer round-trips slightly differently depending on how
-// much of the buffer it captures — a serialize SGR-fidelity nuance (the Bug B
-// class) that has nothing to do with seq reconciliation. Keeping it out of the
-// tail keeps the styles gate a clean function of the byte-stitch.
+// No SGR 7 (inverse): it round-trips through the serializer inconsistently (Bug B class), unrelated to seq reconciliation.
 const TAIL_SGR = ['\x1b[0m', '\x1b[31m', '\x1b[1m', '\x1b[38;5;204m', '\x1b[22m'] as const
 
-/** Append-only racing tail: SGR runs + text + newlines only. No absolute/
- *  relative cursor motion, scroll regions, alt frames, or DECSC — so the tail
- *  paints wherever the cursor sits and its screen effect is a pure function of
- *  which bytes the seq-reconciliation applies. Terminal-state-loss garbles
- *  (Bugs C/D/E, scroll region) are pinned separately; this suite isolates the
- *  seq slice. */
+/** Append-only racing tail (SGR + text + newlines, no cursor motion) so its screen effect is a pure function of which bytes
+ *  the seq-reconciliation applies; terminal-state-loss garbles (Bugs C/D/E) are pinned separately. */
 function buildAppendOnlyTail(rng: () => number, lines: number): string {
   const out: string[] = []
   for (let i = 0; i < lines; i++) {
@@ -290,20 +239,11 @@ function buildAppendOnlyTail(rng: () => number, lines: number): string {
   return out.join('')
 }
 
-/** Builds a seeded metered stream with a random reveal boundary. A running seq
- *  counter tags the LAST byte of each chunk; at most ONE mid-stream restart
- *  bumps the domain and resets the counter low (a revived ptyId with a fresh
- *  main-side counter — production clears the restored baseline at that exit
- *  boundary, so the post-restart tail writes verbatim). Rare unmetered chunks
- *  (no seq) and droppedOutput markers model no-metering runtimes and pending-cap
- *  trims. Op counts are kept modest so most scenarios reach the full
- *  non-scrolled comparison (the tail-stitch invariant); scrolled scenarios fall
- *  back to the snapshot-depth-tolerant path (see the assertion loop). */
+/** Builds a seeded metered stream with a random reveal boundary: a running seq tags each chunk's LAST byte, and at most one mid-stream restart bumps the domain. */
 function buildScenario(seed: number): Scenario {
   const rng = mulberry32(seed)
   const dims = DIMS[Math.floor(rng() * DIMS.length)]!
-  // Hidden prefix: full agent-TUI churn (cursor motion, panels, alt frames,
-  // scroll regions, DECSC…) so the SNAPSHOT is taken over rich state.
+  // Hidden prefix: full agent-TUI churn so the snapshot is taken over rich terminal state.
   const prefixOps = buildAgentTuiStreamOps(rng, dims, {
     includeMouseModes: false,
     includeOscHyperlinks: false,
@@ -314,8 +254,7 @@ function buildScenario(seed: number): Scenario {
     minLen: 2,
     maxLen: 64
   })
-  // Racing tail: append-only content. Isolates the seq-reconciliation byte
-  // stitch from terminal-state-loss garbles (Bugs C/D/E — pinned separately).
+  // Racing tail: append-only, isolating the seq-stitch from terminal-state-loss garbles (Bugs C/D/E, pinned separately).
   const tailStream = buildAppendOnlyTail(rng, 2 + Math.floor(rng() * 5))
   const tailRaw = splitIntoRandomChunks(mulberry32(seed ^ 0x2545f491), tailStream, {
     minLen: 2,
@@ -326,8 +265,7 @@ function buildScenario(seed: number): Scenario {
   let seq = 100 + Math.floor(rng() * 50)
   let domain = 0
   let hasDropped = false
-  // At most one restart, placed inside the tail so the snapshot's own domain
-  // has a stable prefix — mirrors a single mid-session ptyId revival.
+  // At most one restart, inside the tail so the snapshot's domain has a stable prefix — mirrors a mid-session ptyId revival.
   const restartAt =
     rng() < 0.25 ? prefixRaw.length + Math.floor(rng() * Math.max(1, tailRaw.length)) : -1
   const allRaw = [...prefixRaw, ...tailRaw]
@@ -340,8 +278,7 @@ function buildScenario(seed: number): Scenario {
     const rawLength = data.length
     seq += rawLength
     const chunk: MeteredChunk = { data, seq, rawLength, domain }
-    // Rare unmetered / dropped markers, only in the tail (the prefix must meter
-    // so the snapshot carries a seq).
+    // Rare unmetered / dropped markers, only in the tail (the prefix must meter so the snapshot carries a seq).
     if (i >= prefixRaw.length && rng() < 0.05) {
       delete chunk.seq
       delete chunk.rawLength
@@ -353,11 +290,7 @@ function buildScenario(seed: number): Scenario {
     chunks.push(chunk)
   }
 
-  // Reveal at or after the prefix ends, so the racing tail is purely the
-  // append-only region — the snapshot captures all cursor-motion/scroll/alt
-  // state and the tail cannot depend on unserialized terminal state. Landing
-  // the reveal at various points INSIDE the append-only tail exercises the
-  // straddle and "snapshot seq inside the tail" seq-slice cases.
+  // Reveal at or after the prefix ends so the tail is purely append-only; the snapshot captures all rich terminal state.
   const tailSpan = Math.max(1, chunks.length - prefixRaw.length)
   const revealIdx = Math.min(chunks.length, prefixRaw.length + Math.floor(rng() * tailSpan))
   return { seed, dims, chunks, revealIdx, domains: domain + 1, hasDropped }
@@ -388,9 +321,7 @@ function formatFailure(s: Scenario, stage: string, expected: unknown, actual: un
 
 describe('hidden reveal seq-reconciliation fuzz', () => {
   it('is a byte-exact identity when the snapshot seq splits a straddling chunk', async () => {
-    // Pin the core invariant on a hand-built case so the property test cannot
-    // pass vacuously. rawLength === data.length so the straddle slices cleanly.
-    // Chunk 0 fully hidden; chunk 1 straddles the reveal; chunk 2 is the tail.
+    // Pin the core invariant on a hand-built case so the property test cannot pass vacuously.
     const dims = { cols: 40, rows: 6 }
     const c0 = 'red line one\r\n'
     const c1 = 'green straddle\r\n'
@@ -400,17 +331,14 @@ describe('hidden reveal seq-reconciliation fuzz', () => {
       { data: c1, seq: c0.length + c1.length, rawLength: c1.length, domain: 0 },
       { data: c2, seq: c0.length + c1.length + c2.length, rawLength: c2.length, domain: 0 }
     ]
-    // Reveal after chunk 1 (snapshot seq = end of c1); tail = c2. Also exercise
-    // the straddle by revealing at chunk 1 with a snapshot seq mid-c1 handled by
-    // chunkDataAfterSnapshot when c1 is in the tail — covered by revealIdx=1.
+    // Reveal after chunk 1 (snapshot seq = end of c1); tail = c2. revealIdx=1 below exercises the straddle case.
     const revealAfterC1 = await revealFromSnapshot(dims, chunks, 2)
     const control = await alwaysVisible(dims, chunks)
     expect(revealAfterC1.rows).toEqual(control.rows)
     expect(revealAfterC1.styles).toEqual(control.styles)
     expect(revealAfterC1.cursor).toEqual(control.cursor)
 
-    // Reveal at chunk 1: c0 hidden (snapshot seq = end of c0), c1+c2 are the
-    // tail. c1 is fully after the snapshot seq so it writes whole — identity.
+    // Reveal at chunk 1: c0 hidden, c1+c2 tail; c1 is fully after the snapshot seq so it writes whole — identity.
     const revealAtC1 = await revealFromSnapshot(dims, chunks, 1)
     expect(revealAtC1.rows).toEqual(control.rows)
     expect(revealAtC1.styles).toEqual(control.styles)
@@ -418,12 +346,7 @@ describe('hidden reveal seq-reconciliation fuzz', () => {
   })
 
   // ── Bug D regression guard: DECSC saved-cursor register across hide/reveal ──
-  // The serialized screen cannot carry the VT100 saved-cursor register, so a
-  // hidden DECSC followed by a post-reveal DECRC restored to home and the next
-  // writes clobbered the wrong cells. FIXED: the snapshot epilogue re-saves at
-  // the source's saved position before the final absolute CUP
-  // (serializeWithAbsoluteCursor + readSavedCursorRegister). Found by fuzz
-  // seed 3; mechanism in notes/garble-fuzz-divergences.md (Bug D).
+  // The serialized screen can't carry the saved-cursor register, so a hidden DECSC + post-reveal DECRC restored to home. Seed 3; notes/garble-fuzz-divergences.md.
   it('preserves the DECSC saved-cursor register across a hide/reveal boundary', async () => {
     const dims = { cols: 20, rows: 4 }
     // Hidden: write 'AB', DECSC saves cursor at r0c2, move to r3c9, write 'CD'.
@@ -448,13 +371,7 @@ describe('hidden reveal seq-reconciliation fuzz', () => {
   })
 
   // ── Bug E regression guard: snapshot boundary mid-escape-sequence ──
-  // A PTY read (one delivery record) can split an escape; the partial lives in
-  // the emulator's parser, not the serialized screen, so the racing tail's
-  // continuation rendered literal ('ABmCD'). FIXED: the emulator tracks the
-  // unparsed trailing partial (terminal-partial-escape-tail.ts) and the
-  // snapshot ships it out-of-band (pendingEscapeTailAnsi); the reveal replay
-  // re-arms it as the final write. Found by fuzz seed 4; mechanism in
-  // notes/garble-fuzz-divergences.md (Bug E).
+  // A split escape's partial lives in the parser, not the serialized screen; the snapshot ships it out-of-band. Seed 4; notes/garble-fuzz-divergences.md.
   it('completes an escape sequence split across the hide/reveal boundary', async () => {
     const dims = { cols: 20, rows: 3 }
     // Hidden prefix ends mid-escape: 'AB' then ESC[3 (no final byte).
@@ -475,16 +392,8 @@ describe('hidden reveal seq-reconciliation fuzz', () => {
     for (let i = 0; i < ITERATIONS; i++) {
       const seed = FIXED_SEED ?? 1 + i
       const scenario = buildScenario(seed)
-      // Bug E (snapshot boundary mid-escape-sequence) is no longer tolerated:
-      // the snapshot now carries the trailing partial escape out-of-band and
-      // the reveal replay re-arms it last, so these scenarios must compare
-      // clean like any other — a regression fails the corpus loudly.
-      // Primary control: a snapshot of the WHOLE stream. Sharing the snapshot
-      // machinery isolates the seq-reconciliation tail-stitch from
-      // snapshot-fidelity gaps (fidelity suite's Bugs B/C). If snapshot-at-S +
-      // tail differs from snapshot-of-everything, a byte was lost/duped/mis-
-      // sliced. Also compare against always-visible where the two agree, to
-      // catch a tail that diverges from live output.
+      // Bug E (snapshot mid-escape) is no longer tolerated — a regression must fail the corpus loudly.
+      // Primary control is a full-stream snapshot: sharing snapshot machinery isolates the tail-stitch from fidelity gaps (Bugs B/C).
       const [reveal, reference, live] = await Promise.all([
         revealFromSnapshot(scenario.dims, scenario.chunks, scenario.revealIdx),
         fullSnapshotReference(scenario.dims, scenario.chunks),
@@ -503,8 +412,7 @@ describe('hidden reveal seq-reconciliation fuzz', () => {
           formatFailure(scenario, 'alt-screen-state', reference.alternate, reveal.alternate)
         )
       }
-      // Scrolled scenarios: top-row survival is a snapshot-depth question
-      // (fidelity suite), not seq reconciliation.
+      // Scrolled scenarios: top-row survival is a snapshot-depth question (fidelity suite), not seq reconciliation.
       if (reveal.scrolled || reference.scrolled) {
         statsSkippedScrolled += 1
         continue
@@ -525,9 +433,7 @@ describe('hidden reveal seq-reconciliation fuzz', () => {
       if (JSON.stringify(reveal.cursor) !== JSON.stringify(reference.cursor)) {
         expect.fail(formatFailure(scenario, 'tail-stitch-cursor', reference.cursor, reveal.cursor))
       }
-      // Stronger gate: when a full-stream SNAPSHOT already matches the
-      // always-visible LIVE screen (no fidelity gap in play), the mid-point
-      // reveal must match live too — a true end-to-end garble check.
+      // When a full-stream snapshot already matches the live screen (no fidelity gap), the mid-point reveal must match live too.
       if (
         !live.scrolled &&
         live.alternate === reference.alternate &&
@@ -546,8 +452,7 @@ describe('hidden reveal seq-reconciliation fuzz', () => {
         }
       }
     }
-    // Guard against a degenerate corpus that skips its way to green: a healthy
-    // fraction of scenarios must reach the full non-scrolled comparison.
+    // Guard against a degenerate corpus that skips its way to green.
     if (FIXED_SEED === null) {
       expect(statsCompared).toBeGreaterThan(ITERATIONS * 0.2)
     }
diff --git a/src/renderer/src/components/terminal-pane/layout-serialization.ts b/src/renderer/src/components/terminal-pane/layout-serialization.ts
index 0300bfd6b6e..add3280e658 100644
--- a/src/renderer/src/components/terminal-pane/layout-serialization.ts
+++ b/src/renderer/src/components/terminal-pane/layout-serialization.ts
@@ -27,111 +27,42 @@ export const EMPTY_LAYOUT: TerminalLayoutSnapshot = {
   expandedLeafId: null
 }
 
-// Why: xterm's SerializeAddon captures display state by emitting mode-setting
-// bytes (e.g. `\e[?1004h` for focus reporting) so a re-fed emulator lands in
-// the same mode as the snapshot source. That's correct for tmux-style
-// "attach to a still-running TUI" — but Orca restores scrollback against a
-// *fresh* shell, with no TUI to consume those modes. A stale focus-reporting
-// bit causes xterm to emit `\e[I`/`\e[O` on every pane click, which the
-// fresh zsh treats as unbound key input and rings the bell for.
-//
-// Reset the interactive modes most commonly left set by crashed/ended TUIs
-// so replayed mode bits do not leak into the fresh shell. ghostty achieves
-// the same end by not restoring state at all.
-//
-//   0 SP q              — DECSCUSR cursor style/blink reset (raw replay can
-//                         carry a stale steady cursor override; reset to the
-//                         user's configured xterm cursor)
-//   25                  — DECTCEM cursor visibility (SerializeAddon captures
-//                         `?25l` when the cursor was hidden at snapshot time;
-//                         without an explicit `?25h` here the cursor stays
-//                         invisible in the restored terminal)
-//   9/1000/1002/1003    — mouse reporting protocols
-//   1006/1016           — SGR mouse encodings
-//   1004                — focus event reporting (the actual bug source)
-//   2004                — bracketed paste
-//   <99u/=0u            — Kitty keyboard flags pushed by TUIs such as Codex
+// Why: SerializeAddon replays mode bits assuming reattach to a live TUI, but Orca restores against a fresh shell with none, so stale bits (e.g. focus reporting rings the bell on click) must be reset.
 export const RESET_TERMINAL_CURSOR_STYLE = '\x1b[0 q'
 export const RESET_KITTY_KEYBOARD_PROTOCOL = '\x1b[<99u\x1b[=0u'
-// Every mouse mode the daemon's buildRehydrateSequences can re-arm from a
-// snapshot: reporting protocols (9/1000/1002/1003) and SGR encodings
-// (1006/1016).
+// Every mouse mode the daemon can re-arm from a snapshot: protocols 9/1000/1002/1003 + SGR encodings 1006/1016.
 export const RESET_MOUSE_REPORTING =
   '\x1b[?9l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?1016l'
 
 export const POST_REPLAY_MODE_RESET = `${RESET_TERMINAL_CURSOR_STYLE}${RESET_KITTY_KEYBOARD_PROTOCOL}\x1b[?25h${RESET_MOUSE_REPORTING}\x1b[?1004l\x1b[?2004l`
 
-// Why: hidden-output recovery replays a snapshot of the same live renderer
-// session. Keep cursor/focus cleanup, but preserve Kitty keyboard flags that
-// the still-running foreground TUI may rely on.
+// Why: same-session live replay; keep cursor/focus cleanup but preserve Kitty flags the running TUI relies on.
 export const POST_REPLAY_LIVE_SNAPSHOT_RESET = `${RESET_TERMINAL_CURSOR_STYLE}\x1b[?25h\x1b[?1004l`
 
-// Why: daemon snapshot restore reattaches to a live session, so we avoid the
-// full POST_REPLAY_MODE_RESET bundle there. The default still clears the
-// stale mode bits most harmful to a plain shell after a TUI exits badly:
-//
-//   0 q  — DECSCUSR cursor style/blink reset: raw replay can contain a stale
-//          steady cursor override, while SerializeAddon does not preserve an
-//          authoritative current cursor style. Reset to the user's configured
-//          xterm cursor; the post-reattach SIGWINCH lets live TUIs repaint if
-//          they need a different cursor.
-//   25   — DECTCEM cursor visibility: snapshots can preserve hidden cursor
-//          state from a no-longer-running TUI; reset by default so shells do
-//          not inherit a permanently invisible cursor.
-//   1004 — focus event reporting: snapshots can preserve focus reporting from
-//          a no-longer-running TUI; reset by default so shells do not receive
-//          stray focus-in/focus-out bytes.
-//   mouse — the daemon's rehydrateSequences re-arm the mouse mode observed
-//           before an uncleanly-killed TUI, so every reattach resurrects it;
-//           a plain shell then echoes motion reports (`35;x;yM`) as literal
-//           input on each pointer move. Live agents keep mouse modes via
-//           POST_REPLAY_LIVE_AGENT_REATTACH_RESET.
-//   <99u/=0u — Kitty keyboard mode is renderer-side xterm state; stale copies
-//              can make the next Ctrl+C encode as CSI-u after reattach.
+// Why: daemon reattach hits a live session, so skip the full reset; still clear cursor/focus/mouse/Kitty bits harmful to a plain shell after a bad TUI exit — safe for live TUIs since the post-reattach SIGWINCH repaints the cursor.
 export const POST_REPLAY_REATTACH_RESET = `${RESET_TERMINAL_CURSOR_STYLE}${RESET_KITTY_KEYBOARD_PROTOCOL}\x1b[?25h${RESET_MOUSE_REPORTING}\x1b[?1004l`
 
-// Why: a live agent TUI legitimately owns focus reporting; resetting `?1004h`
-// would suppress the post-reattach focus-in the agent needs to move its real
-// cursor back to the input caret (the IME anchor).
+// Why: a live agent owns focus reporting; resetting ?1004h suppresses the focus-in it needs to re-anchor its cursor (IME).
 export const POST_REPLAY_LIVE_AGENT_REATTACH_RESET = `${RESET_TERMINAL_CURSOR_STYLE}${RESET_KITTY_KEYBOARD_PROTOCOL}\x1b[?25h`
 
-// Why: DECTCEM applies in emission order, so the payload's last ?25l/?25h is
-// the state the TUI left the cursor in.
+// Why: DECTCEM applies in emission order, so the payload's last ?25l/?25h is the cursor state the TUI left.
 export function replayPayloadEndsWithCursorHidden(payload: string): boolean {
   const hideIndex = payload.lastIndexOf('\x1b[?25l')
   return hideIndex !== -1 && hideIndex > payload.lastIndexOf('\x1b[?25h')
 }
 
-// Why: some live agents (Cursor Agent) intentionally hide the real cursor and
-// draw their own caret; re-showing it paints a stray cursor on the parked row.
-// Preserve the payload's own final cursor-visibility state instead of forcing
-// ?25h. Agent detection can still false-positive on a dead TUI's leftovers —
-// the post-replay viewport check in pty-connection re-shows the cursor once
-// the parsed screen disproves a live parked agent, so a shell cannot inherit
-// a permanently invisible cursor.
+// Why: some agents hide the real cursor and draw their own, so preserve the payload's final visibility (pty-connection re-shows it if the agent was actually a dead TUI).
 export function buildPostReplayLiveAgentReattachReset(payload: string): string {
   return replayPayloadEndsWithCursorHidden(payload)
     ? `${RESET_TERMINAL_CURSOR_STYLE}${RESET_KITTY_KEYBOARD_PROTOCOL}`
     : POST_REPLAY_LIVE_AGENT_REATTACH_RESET
 }
 
-// Why: hidden-output recovery replays into the same live session. When a live
-// agent still owns the pane it also owns cursor visibility and focus
-// reporting: forcing ?25h re-shows a parked cursor the agent hid on purpose,
-// and ?1004l permanently silences the focus-in the agent needs to unpark
-// (agents only enable ?1004h at startup, so nothing ever re-arms it).
+// Why: a live agent owns cursor/focus here; forcing ?25h/?1004l breaks a parked agent that only arms ?1004h at startup.
 export const POST_REPLAY_LIVE_AGENT_SNAPSHOT_RESET = RESET_TERMINAL_CURSOR_STYLE
 
-// Cross-platform monospace fallback chain ensures the terminal always has a
-// usable font regardless of OS.  macOS-only fonts like SF Mono and Menlo are
-// harmless on other platforms (the browser skips them), while Cascadia Mono /
-// Consolas cover Windows and DejaVu Sans Mono / Liberation Mono cover Linux.
-//
-// Why Nerd Fonts are listed after the regular monospace fonts: OMP, Powerline
-// prompts, and many shell plugins emit glyphs in the Unicode Private Use Area
-// (U+E000–U+F8FF) that no standard monospace font contains. The bundled symbol
-// font gives Orca a known-good fallback even on clean systems, while the
-// installed-font fallbacks keep users' existing terminal setups working.
+// Cross-platform monospace chain: browsers skip fonts absent on the current OS, so listing all is safe.
+// Nerd Fonts come last to cover PUA glyphs (U+E000–U+F8FF) from OMP/Powerline that standard monospace fonts lack.
 const FALLBACK_FONTS = [
   'SF Mono', // macOS 10.12+
   'Menlo', // macOS (older)
@@ -152,8 +83,7 @@ export function buildFontFamily(fontFamily: string): string {
   const trimmed = fontFamily.trim()
   const parts = trimmed ? [`"${trimmed}"`] : []
   const lowerParts = parts.map((p) => p.toLowerCase())
-  // Append each fallback unless the user's font name already contains it
-  // (case-insensitive) to avoid duplicates like '"SF Mono", "SF Mono"'.
+  // Append each fallback unless already present (case-insensitive) to avoid duplicates.
   for (const fallback of FALLBACK_FONTS) {
     const lower = fallback.toLowerCase()
     if (!lowerParts.some((p) => p.includes(lower))) {
@@ -196,7 +126,6 @@ export function serializePaneTree(node: HTMLElement | null): TerminalPaneLayoutN
   }
 
   // Capture the flex ratio so resized panes survive serialization round-trips.
-  // We read the computed flex-grow values to derive the first-child proportion.
   let ratio: number | undefined
   if (first && second) {
     const firstGrow = Number.parseFloat(first.style.flex) || 1
@@ -239,11 +168,8 @@ export function serializeTerminalLayout(
 }
 
 /**
- * Write saved scrollback buffers into the restored panes so the user sees
- * their previous terminal output after an app restart.  If a buffer was
- * captured while the alternate screen was active (e.g. an agent TUI was
- * running at shutdown), we exit alt-screen first so the user sees a usable
- * normal-mode terminal.
+ * Write saved scrollback buffers into restored panes so the user sees prior
+ * output after a restart. Exits alt-screen first if a buffer ended mid-TUI.
  */
 export function restoreScrollbackBuffers(
   manager: PaneManager,
@@ -266,11 +192,7 @@ export function restoreScrollbackBuffers(
     if (!pane) {
       continue
     }
-    // Why this breadcrumb: a restore write into an already-disposed xterm is
-    // fully silent (no throw; completion callbacks are dropped) and is the
-    // suspected deterministic producer of zombie panes at startup — the field
-    // signature is a wedged-release drip with zero error breadcrumbs. Naming
-    // the moment here turns the last unproven link into a logged fact.
+    // Breadcrumb: writes into a disposed xterm are silent (no throw), the suspected source of startup zombie panes.
     if (isXtermInstanceDisposed(pane.terminal)) {
       recordRendererCrashBreadcrumb('terminal_restore_write_target_disposed', {
         paneId: pane.id
@@ -282,33 +204,24 @@ export function restoreScrollbackBuffers(
         shouldRefreshViewportSynchronously: () => !manager.hasWebglRenderer(pane.id)
       }
       let buf = buffer
-      // If buffer ends in alt-screen mode (agent TUI was running at
-      // shutdown), exit alt-screen so the user sees a usable terminal.
+      // If the buffer ends in alt-screen (agent TUI at shutdown), exit it so the terminal is usable.
       const lastOn = buf.lastIndexOf(ALT_SCREEN_ON)
       const lastOff = buf.lastIndexOf(ALT_SCREEN_OFF)
       if (lastOn > lastOff) {
         buf = buf.slice(0, lastOn)
       }
       if (buf.length > 0) {
-        // Why replayIntoTerminal: the serialized buffer can contain query
-        // sequences from the prior session (DA1, DECRQM, OSC 10/11, focus,
-        // CPR). Writing those through xterm.write would trigger auto-replies
-        // that land in the new shell's stdin. See replay-guard.ts.
+        // replayIntoTerminal: buffer queries (DA1/DECRQM/CPR) would auto-reply into the new shell's stdin. See replay-guard.ts.
         replayIntoTerminal(pane, replayingPanesRef, buf, renderOptions)
-        // Ensure cursor is on a new line so the new shell prompt
-        // doesn't trigger zsh's PROMPT_EOL_MARK (%) indicator.
+        // Newline first so the new shell prompt doesn't trigger zsh's PROMPT_EOL_MARK (%) indicator.
         replayIntoTerminal(pane, replayingPanesRef, '\r\n', renderOptions)
-        // Clear any mode bits the serialized buffer replayed into xterm.
-        // The shell underneath is fresh and has no TUI consuming these modes.
-        // See POST_REPLAY_MODE_RESET comment.
+        // Clear mode bits the buffer replayed: the fresh shell has no TUI to consume them. See POST_REPLAY_MODE_RESET.
         replayIntoTerminal(pane, replayingPanesRef, POST_REPLAY_MODE_RESET, renderOptions)
-        // Why: connection resolution happens after layout replay; only the
-        // fresh-shell paths should move these visible rows into scrollback.
+        // Why: connection resolution runs after layout replay; only fresh-shell paths move these rows into scrollback.
         restoredViewportBlankingPanesRef?.current.add(pane.id)
       }
     } catch (error: unknown) {
-      // If restore fails, continue with blank terminal — but leave a trace:
-      // this catch was fully silent while zombie panes went undiagnosed.
+      // Breadcrumb: this catch was silent while zombie panes went undiagnosed.
       recordRendererCrashBreadcrumb('terminal_restore_write_failed', {
         paneId: pane.id,
         errorName: error instanceof Error ? error.name : typeof error,
diff --git a/src/renderer/src/components/terminal-pane/parked-terminal-byte-watcher.ts b/src/renderer/src/components/terminal-pane/parked-terminal-byte-watcher.ts
index 359f8815b68..1748cb8290f 100644
--- a/src/renderer/src/components/terminal-pane/parked-terminal-byte-watcher.ts
+++ b/src/renderer/src/components/terminal-pane/parked-terminal-byte-watcher.ts
@@ -1,17 +1,6 @@
 /**
  * Parked terminal side-effect watcher.
- *
- * Why: parking unmounts the TerminalPane subtree, which tears down the pane's
- * side-effect consumers — the parked tab's only source of bell, title,
- * agent-completion, and PR-link policy. (Losing them is the gap that sank the
- * first parking attempt.) Under main side-effect authority the watcher is
- * purely fact-driven (one pty:sideEffect consumer, no byte parsing); with the
- * kill switch off it registers the legacy byte parsers on the dispatcher
- * sidecar channel. DECSET 2031 ownership follows the hidden-delivery gate:
- * gate ON answers from main's '2031-subscribe' fact (no parked bytes exist),
- * gate OFF keeps the byte sidecar (parked-terminal-mode2031-responder.ts).
- * Either way the reply is sent from the renderer — query authority never
- * moves to main.
+ * Why: parking unmounts TerminalPane, so this replays its bell/title/agent-completion/PR-link side effects while parked.
  */
 import { isClaudeAgent } from '../../../../shared/agent-detection'
 import { makePaneKey } from '../../../../shared/stable-pane-id'
@@ -38,9 +27,7 @@ import {
 import { dispatchTerminalNotification } from './use-notification-dispatch'
 import { acquireHiddenRendererPtyDeliveryClaim } from './pty-renderer-delivery-claims'
 
-// Why: mirrors AGENT_TASK_COMPLETE_NOTIFICATION_GRACE_MS in pty-connection.ts.
-// The parked path must keep the live path's BEL-vs-completion race window so
-// notification behavior is identical whether a tab is parked or mounted.
+// Why: keep the live path's BEL-vs-completion race window so notification behavior is identical whether a tab is parked or mounted.
 const PARKED_NOTIFICATION_GRACE_MS = AGENT_TASK_COMPLETE_NOTIFICATION_GRACE_MS
 
 type StoreState = ReturnType<typeof useAppStore.getState>
@@ -57,22 +44,15 @@ export type ParkedTerminalByteWatcherOptions = {
   ptyId: string
   tabId: string
   worktreeId: string
-  /** Stable terminal-layout leaf UUID. Combined with tabId into the paneKey
-   *  used for cache-timer, unread, and notification attribution. */
+  /** Stable terminal-layout leaf UUID; combined with tabId into the paneKey for cache-timer, unread, and notification attribution. */
   leafId: string
-  /** PaneManager pane id the unmounted pane used. Runtime pane titles are
-   *  keyed by it, so the watcher must write the slot the live path wrote —
-   *  a different id would leave a stale (possibly "working") title behind. */
+  /** PaneManager pane id the unmounted pane used; the watcher must write this same slot or a stale "working" title strands. */
   paneId: number
-  /** Whether this PTY's pane was the tab's active split pane. Mirrors the
-   *  live path, where only the focused split drives the tab title. */
+  /** Whether this PTY's pane was the tab's active split — only the focused split drives the tab title. */
   drivesTabTitle?: boolean
-  /** The pane's last known runtime title at park time. Seeds the agent
-   *  tracker so an agent that was working when the pane unmounted still
-   *  fires its completion when it goes idle while parked. */
+  /** Last runtime title at park time; seeds the agent tracker so an agent working at unmount still fires completion when it goes idle. */
   initialTitle?: string
-  /** Pull main's title-only snapshot when a watcher starts before its pane
-   *  has ever mounted. Ordinary park cycles already have a current title. */
+  /** Pull main's title-only snapshot when a watcher starts before its pane ever mounted (ordinary park cycles already have a title). */
   restoreTitleOnRegister?: boolean
   /** Out-of-band reply channel to the PTY (mode-2031 color-scheme answers). */
   sendInput: (data: string) => void
@@ -87,16 +67,12 @@ export function startParkedTerminalByteWatcher(
   const drivesTabTitle = options.drivesTabTitle ?? true
   const paneKey = makePaneKey(tabId, options.leafId)
 
-  // Why: one watcher per PTY. A stale watcher from a previous park cycle would
-  // double-fire bell/completion side effects for the same bytes.
+  // Why: one watcher per PTY — a stale watcher from a previous park cycle would double-fire bell/completion for the same bytes.
   parkedWatcherDisposersByPtyId.get(ptyId)?.()
 
   let disposed = false
   let pendingBellNotification = false
-  // Why: a watcher-written runtime title (especially into a negative fallback
-  // slot) has no live pane to overwrite it after reveal; a stale 'working'
-  // entry would pin worktree status forever. Track writes so dispose can
-  // clear exactly the slot this watcher touched.
+  // Why: a watcher-written title has no pane to overwrite it after reveal (stale 'working' pins status); track writes so dispose clears the exact slot.
   let wroteRuntimeTitleSlot = false
   let bellNotificationTimer: ReturnType<typeof setTimeout> | null = null
   let agentTaskCompleteTimer: ReturnType<typeof setTimeout> | null = null
@@ -115,8 +91,7 @@ export function startParkedTerminalByteWatcher(
     }
   }
 
-  // Why: like the live path, a BEL OS notification only yields when the
-  // pending completion would itself produce an OS notification.
+  // Why: a BEL OS notification only yields when the pending completion would itself produce an OS notification (live-path parity).
   const hasPendingAgentTaskCompleteNotification = (): boolean =>
     agentTaskCompleteTimer !== null &&
     isAgentTaskCompleteOsNotificationEnabled(useAppStore.getState())
@@ -139,9 +114,7 @@ export function startParkedTerminalByteWatcher(
     }, PARKED_NOTIFICATION_GRACE_MS)
   }
 
-  // Why: one policy block for both consumption modes — byte parsing (kill
-  // switch off) and pty:sideEffect facts (main authority on). The semantics
-  // must be identical or flipping the switch changes notification behavior.
+  // Why: one policy block shared by both modes (byte parsing and facts) — semantics must be identical or flipping the switch changes behavior.
   const sideEffectCallbacks = {
     onTitleChange: (title: string): void => {
       const state = useAppStore.getState()
@@ -158,25 +131,20 @@ export function startParkedTerminalByteWatcher(
       if (state.settings?.experimentalTerminalAttention === true) {
         state.markTerminalPaneUnread(paneKey)
       }
-      // Why: agent CLIs often emit BEL in the same completion burst as their
-      // working→idle title change. Delay only the OS notification so the
-      // richer agent-task-complete notification can win (live-path parity).
+      // Why: agents emit BEL in the same burst as working→idle, so delay only the OS notification to let the richer completion notification win.
       pendingBellNotification = true
       if (!hasPendingAgentTaskCompleteNotification()) {
         scheduleTerminalBellNotification()
       }
     },
     onAgentBecameIdle: (title: string, meta?: { staleWorkingTitleClear?: boolean }): void => {
-      // Why: stale-derived idles come from main's unthrottled 3s timer, not
-      // observed bytes — clear session state, never schedule the completion
-      // notification a merely-paused agent did not earn (live-path parity).
+      // Why: stale-derived idles (main's 3s timer, not observed bytes) clear session state but must not schedule a completion a paused agent didn't earn.
       if (meta?.staleWorkingTitleClear) {
         useAppStore.getState().setCacheTimerStartedAt(paneKey, null)
         return
       }
       const state = useAppStore.getState()
-      // Why: mirrors pty-connection — null settings means "not hydrated yet";
-      // a spurious timestamp is harmless while a dropped one loses the timer.
+      // Why: null settings means "not hydrated yet"; a spurious timestamp is harmless while a dropped one loses the timer.
       if (
         isClaudeAgent(title) &&
         (state.settings === null || state.settings.promptCacheTimerEnabled)
@@ -192,8 +160,7 @@ export function startParkedTerminalByteWatcher(
         if (disposed) {
           return
         }
-        // Why: the completion supersedes a concurrent BEL so each completion
-        // burst yields exactly one OS notification, same as the live path.
+        // Why: completion supersedes a concurrent BEL so each burst yields exactly one OS notification (live-path parity).
         pendingBellNotification = false
         clearBellNotificationTimer()
         dispatchTerminalNotification(worktreeId, {
@@ -207,8 +174,7 @@ export function startParkedTerminalByteWatcher(
       }, PARKED_NOTIFICATION_GRACE_MS)
     },
     onAgentBecameWorking: (): void => {
-      // Why: a new API call refreshes the prompt-cache TTL, so clear any
-      // running countdown; it restarts when the agent next becomes idle.
+      // Why: a new API call refreshes the prompt-cache TTL, so clear the running countdown; it restarts when the agent next becomes idle.
       useAppStore.getState().setCacheTimerStartedAt(paneKey, null)
       clearAgentTaskCompleteTimer()
       if (pendingBellNotification) {
@@ -216,24 +182,17 @@ export function startParkedTerminalByteWatcher(
       }
     },
     onAgentExited: (): void => {
-      // Why: title reverting to a plain shell means the agent session ended;
-      // a stale countdown must not survive in the sidebar while parked.
+      // Why: title reverting to a plain shell means the agent session ended; clear the countdown so it doesn't survive in the sidebar while parked.
       useAppStore.getState().setCacheTimerStartedAt(paneKey, null)
     }
   }
 
-  // Why: parking eligibility excludes remote-runtime and SSH PTYs, so every
-  // watched PTY's bytes transit local main — when the authority switch is on,
-  // the watcher must NOT register byte parsers (the fact consumer below is
-  // the single policy consumer; double registration would double-fire bells).
+  // Why: with the authority switch on, the fact consumer is the single policy consumer — registering byte parsers too would double-fire bells.
   const mainSideEffectAuthority = isMainTerminalSideEffectAuthorityForPty({
     settings: useAppStore.getState().settings,
     runtimeEnvironmentId: null
   })
-  // Why: under the Phase-4 gate a parked PTY needs no renderer bytes at all —
-  // facts carry side effects and the reveal remount restores from the model
-  // snapshot. Decided once at watcher start: it picks which 2031 responder
-  // (byte sidecar vs fact reply) exists, so it must never flip per chunk.
+  // Why: decided once at watcher start — it picks which 2031 responder (byte sidecar vs fact reply) exists, so it must never flip per chunk.
   const hiddenDeliveryGateActive =
     mainSideEffectAuthority &&
     isRendererHiddenPtyDeliveryGateEnabled(useAppStore.getState().settings)
@@ -243,71 +202,50 @@ export function startParkedTerminalByteWatcher(
     sendInput(mode2031SequenceFor(resolveTerminalColorSchemeMode(settings, getSystemPrefersDark())))
   }
 
-  // Why (byte-parser mode only): reuse the transport's output processor so
-  // the parked path keeps the exact live-path parsing semantics — all-titles
-  // ordering, normalization, the cursor-agent native-title drop, the
-  // OSC-aware stateful bell detector, and the working/idle agent tracker.
-  // initialAgentTitle: an agent already working at park time must still
-  // produce a working→idle transition; main's continuous tracker covers this
-  // in fact-consumer mode.
+  // Why (byte-parser mode only): reuse the transport's output processor to keep exact live-path parsing semantics.
+  // initialAgentTitle: an agent already working at park time still produces a working→idle transition.
   const processor = mainSideEffectAuthority
     ? null
     : createPtyOutputProcessor({
         ...(options.initialTitle !== undefined ? { initialAgentTitle: options.initialTitle } : {}),
         ...sideEffectCallbacks
       })
-  // Why (byte-parser mode only): with main authority, pr-link facts arrive on
-  // the channel below; byte-scanning too would observe every link twice.
+  // Why (byte-parser mode only): under main authority, byte-scanning PR links too would observe every link twice (facts already carry them).
   const observeTerminalGitHubPRLink = mainSideEffectAuthority
     ? null
     : createTerminalGitHubPRLinkDetector()
   const unregisterFactConsumer = mainSideEffectAuthority
     ? registerTerminalSideEffectFactConsumer({
         ptyId,
-        // Why: ordinary park already has a current pane-owned title; the cold
-        // activation flag below requests a snapshot only when no pane did.
+        // Why: ordinary park already has a pane-owned title; the flag below requests a snapshot only when no pane did.
         callbacks: {
           ...sideEffectCallbacks,
           onPrLink: (link) =>
             useAppStore.getState().observeTerminalGitHubPullRequestLink(worktreeId, link),
-          // Why (gate mode only): bytes never arrive while gated, so the 2031
-          // subscribe arrives as a main-tracker fact instead of a byte scan.
-          // The reply is still sent from here — query authority stays with
-          // the view/watcher (model/view contract invariant 6).
+          // Why (gate mode only): the 2031 subscribe arrives as a fact, but the reply stays here — query authority stays with the view/watcher (invariant 6).
           ...(hiddenDeliveryGateActive ? { onMode2031Subscribe: sendMode2031Reply } : {})
         },
-        // Why: activation-deferred tabs can start a watcher before any pane
-        // restored the current title; ordinary parked tabs avoid this IPC.
+        // Why: activation-deferred tabs can start a watcher before any pane restored the title; ordinary parked tabs avoid this IPC.
         restoreTitleOnRegister: options.restoreTitleOnRegister === true
       })
     : null
 
-  // Why: no xterm exists while parked, so nothing answers a DECSET 2031
-  // subscription. With the hidden-delivery gate OFF the byte responder is the
-  // parked path's only byte consumer under main authority. With the gate ON it
-  // must NOT register: its subscribeToPtyData sidecar doubles as a
-  // delivery-interest signal that would force-feed bytes to the gated PTY —
-  // the fact callback above replaces the byte scan.
+  // Why: no xterm answers DECSET 2031 while parked; with the gate ON, the responder's sidecar would force-feed bytes to the gated PTY, so skip it.
   const stopMode2031Responder = hiddenDeliveryGateActive
     ? null
     : startParkedTerminalMode2031Responder({ ptyId, sendInput })
 
-  // Why: parked tabs are the canonical hidden view — mark the PTY gated so
-  // main stops renderer byte delivery; dispose clears the bit before the
-  // reveal remount re-registers pane handlers (existing dispose ordering).
+  // Why: parked tabs are the canonical hidden view — mark the PTY gated so main stops renderer byte delivery.
   const releaseHiddenDeliveryClaim = hiddenDeliveryGateActive
     ? acquireHiddenRendererPtyDeliveryClaim(ptyId)
     : null
 
-  // Why (byte-parser mode only): with main authority the watcher consumes
-  // pty:sideEffect facts exclusively and registers NO byte parsers here —
-  // title/bell/agent parsing and the PR-link scan would double-fire policy.
+  // Why (byte-parser mode only): under main authority, registering byte parsers here would double-fire policy already carried by facts.
   const unsubscribeByteParsers =
     processor === null
       ? null
       : subscribeToPtyData(ptyId, (data) => {
-          // Why: empty pane callbacks — the watcher wants only the parser
-          // side effects; there is no xterm to deliver bytes to.
+          // Why: empty pane callbacks — no xterm to deliver bytes to, the watcher wants only the parser side effects.
           processor.processData(data, {})
           if (observeTerminalGitHubPRLink) {
             for (const link of observeTerminalGitHubPRLink(data)) {
@@ -321,24 +259,17 @@ export function startParkedTerminalByteWatcher(
       return
     }
     disposed = true
-    // Why: unhide BEFORE the reveal remount registers pane handlers — main
-    // resumes delivery and (if bytes were dropped) emits the restore marker
-    // the remounted pane's restore machinery consumes.
+    // Why: unhide BEFORE the reveal remount registers pane handlers, so main resumes delivery and emits the restore marker the pane consumes.
     releaseHiddenDeliveryClaim?.()
     stopMode2031Responder?.()
     unsubscribeByteParsers?.()
     unregisterFactConsumer?.()
-    // Why: cancels the deferred side-effect drain, stale-title timer, and
-    // tracker/bell-detector state so the watcher cannot fire after the
-    // revealed pane's live parsers take over.
+    // Why: clears tracker/timer/detector state so the watcher can't fire after the revealed pane's live parsers take over.
     processor?.clearAccumulatedState()
     clearBellNotificationTimer()
     clearAgentTaskCompleteTimer()
     pendingBellNotification = false
-    // Why: the store merge never deletes title slots, so a watcher-written
-    // entry would strand after reveal (the revealing pane re-registers under
-    // its own pane id) and could pin worktree status 'working'. The revealed
-    // pane repopulates its slot via its own title flow.
+    // Why: store merge never deletes title slots, so a watcher-written entry would strand after reveal and pin worktree status 'working'.
     if (wroteRuntimeTitleSlot) {
       wroteRuntimeTitleSlot = false
       useAppStore.getState().clearRuntimePaneTitle(tabId, paneId)
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.test.ts b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
index 1da9467b225..609e6eb6a52 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
@@ -31,10 +31,7 @@ import type { PaneForegroundAgentEntry } from '@/store/slices/pane-foreground-ag
 // Repro command:
 //   pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/terminal-pane/pty-connection.test.ts -t "OpenTUI-style small ANSI redraw"
 
-// Why: the fresh-spawn and reattach paths now chain pre-signal → spawn →
-// register/settle through multiple microtasks. Tests that previously flushed
-// once with `await Promise.resolve()` must drain a few extra ticks before
-// asserting against IPC mocks. See docs/mobile-prefer-renderer-scrollback.md.
+// Why: fresh-spawn/reattach now settle across multiple microtasks, so tests must drain several ticks before asserting on IPC mocks. See docs/mobile-prefer-renderer-scrollback.md.
 async function flushAsyncTicks(count = 6): Promise<void> {
   for (let i = 0; i < count; i++) {
     await Promise.resolve()
@@ -320,16 +317,7 @@ vi.mock('sonner', () => ({
   }
 }))
 
-// Why: the working→idle test imports the real useNotificationDispatch to
-// verify producer → IPC end-to-end. useCallback is pure memoization for
-// that hook, so pass-through here lets it be invoked outside React.
-//
-// Scope note: this mock applies to every test in this file, not just the
-// working→idle test. It is safe today because no other test in this file
-// depends on useCallback identity stability — the suite does not render
-// React components. If that ever changes, either narrow this with
-// vi.doMock inside the it() block or extract the hook body into a plain
-// non-hook function so the test does not need to bypass React at all.
+// Why: the working→idle test invokes the real useNotificationDispatch hook outside React, so useCallback must pass through (safe suite-wide: no test here renders React).
 vi.mock('react', async (importOriginal) => {
   const actual = await importOriginal<typeof React>()
   return {
@@ -362,10 +350,7 @@ vi.mock('./remote-runtime-pty-transport', () => ({
   )
 }))
 
-// Why: the adopt-vs-reattach decision consults the eager-PTY buffer registry to
-// tell a still-live locally-spawned PTY (attach + replay) from a daemon session
-// to re-connect. Keep the real module but stub the lookup so tests can simulate
-// a live eager buffer without standing up the real IPC dispatcher.
+// Why: stub only getEagerPtyBufferHandle so tests can simulate a live eager buffer (adopt path) without standing up the real IPC dispatcher.
 vi.mock('./pty-dispatcher', async (importOriginal) => {
   const actual = await importOriginal<Record<string, unknown>>()
   return {
@@ -395,8 +380,7 @@ function createMockTransport(initialPtyId: string | null = null): MockTransport
     serializeBuffer: undefined
   } as MockTransport
   const sendInput = transport.sendInput as unknown as (data: string) => boolean
-  // Why: query replies now route through sendInputImmediate; delegate to the
-  // same spy so assertions on reply delivery still observe them (#7329).
+  // Why: query replies route through sendInputImmediate; delegate to the same spy so reply-delivery assertions still observe them (#7329).
   transport.sendInputImmediate = vi.fn((data: string) => sendInput(data))
   transport.sendInputAccepted = vi.fn(async (data: string) => sendInput(data))
   return transport
@@ -624,8 +608,7 @@ function configureTerminalFocusMode(
 const ANSI_POSITIONED_CURSOR_AGENT_REATTACH_SCREEN =
   '\x1b[4;3HCursor Agent\x1b[5;3Hv2026.06.29\x1b[9;3H→ Plan, search, build anything'
 
-// Why: setting activeRuntimeEnvironmentId in mockStoreState exercises the
-// remote-runtime path where the renderer still owns OSC 9999 status.
+// Why: activeRuntimeEnvironmentId exercises the remote-runtime path where the renderer still owns OSC 9999 status.
 function enableActiveRuntimeEnvironment(environmentId = 'env-1'): void {
   mockStoreState = {
     ...mockStoreState,
@@ -803,9 +786,7 @@ describe('connectPanePty', () => {
       sshConnectionStates: new Map(),
       transientClearedAgentStatusConnectionIds: {},
       cacheTimerByKey: {},
-      // Why: terminalMainSideEffectAuthority false pins the legacy renderer
-      // byte-parser wiring this suite asserts on (onTitleChange/onBell on the
-      // transport). The authority-on fact-consumer mode has its own tests.
+      // Why: terminalMainSideEffectAuthority false pins the legacy renderer byte-parser wiring this suite asserts on (onTitleChange/onBell); authority-on mode has its own tests.
       settings: {
         promptCacheTimerEnabled: true,
         experimentalTerminalAttention: true,
@@ -932,14 +913,7 @@ describe('connectPanePty', () => {
   })
 
   afterEach(async () => {
-    // Why: pane foreground-agent trackers run async foreground-confirm reads
-    // (`confirmForegroundProcess`) whose continuations settle on the microtask
-    // queue, not on fake timers. A test that ends with one still in flight
-    // leaks it into the NEXT test, where it resolves against that test's fresh
-    // store mock and calls e.g. clearAgentLaunchConfig with THIS test's pane
-    // key — a flaky cross-test call-count failure (seen in CI). Drain pending
-    // microtasks while this test still owns the store mock, before fake timers
-    // are torn down, so each test absorbs its own async fallout.
+    // Why: drain in-flight foreground-confirm microtasks while this test still owns the store mock, so its async fallout can't leak into (and flake) the next test.
     await flushAsyncTicks()
     vi.useRealTimers()
     if (originalRequestAnimationFrame) {
@@ -983,9 +957,7 @@ describe('connectPanePty', () => {
     logSpy.mockRestore()
   }, 30_000)
 
-  // Why: orchestration workers and CLI `terminal create` (no --focus) mount
-  // hidden panes that legitimately connect at 0×0 and refit when shown, so the
-  // zero-dimensions diagnostic must stay silent while the pane is not visible.
+  // Why: hidden panes (orchestration workers, CLI terminal create) legitimately connect at 0×0 and refit when shown, so the zero-dimensions diagnostic must stay silent.
   it('does not surface the zero-dimensions diagnostic for a hidden pane', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport()
@@ -1019,10 +991,7 @@ describe('connectPanePty', () => {
     )
   })
 
-  // Why: a late exit from a replaced PTY takes the stale-transport early
-  // return in onExit and skips the kitty mirror reset there — a fresh spawn
-  // must therefore reset the reused per-pane tracker itself, or a
-  // restart-in-place leaks the old TUI's kitty flags into a fresh shell.
+  // Why: a late exit from a replaced PTY skips onExit's kitty reset, so a fresh spawn must reset the reused per-pane tracker itself or restart-in-place leaks old kitty flags.
   it('resets a stale kitty keyboard mirror when spawning a fresh PTY', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const { TerminalKittyKeyboardModeTracker } =
@@ -1032,8 +1001,7 @@ describe('connectPanePty', () => {
     const staleTracker = new TerminalKittyKeyboardModeTracker()
     staleTracker.scan('\x1b[>1u')
     expect(staleTracker.flags).toBe(1)
-    // Why: a unique tab id keeps this pane's key clear of pendingSpawnByPaneKey
-    // entries from other tests, so the connect deterministically fresh-spawns.
+    // Why: a unique tab id keeps this pane's key clear of other tests' pendingSpawnByPaneKey entries so the connect deterministically fresh-spawns.
     const deps = createDeps({
       tabId: 'tab-kitty-fresh-spawn',
       paneKittyKeyboardModesRef: { current: new Map([[91, staleTracker]]) }
@@ -1101,12 +1069,7 @@ describe('connectPanePty', () => {
   })
 
   it('drops keystrokes while the replay guard is engaged, then forwards once it releases', async () => {
-    // Regression for the cold-restore reattach lockout: handleReattachResult's
-    // replay writes engaged the per-pane replay guard, and because xterm's parse
-    // callback never fired for the just-mounted pane the counter stuck non-zero.
-    // The onData handler then dropped EVERY keystroke — a live but unresponsive
-    // pane ("can't type after reconnecting"). This locks in the drop-site
-    // contract: engaged guard suppresses input, released guard forwards it.
+    // Regression (cold-restore reattach lockout): a stuck replay guard dropped every keystroke ("can't type after reconnecting"); engaged guard suppresses input, released forwards it.
     const { connectPanePty } = await import('./pty-connection')
     const pane = createPane(1)
     const transport = createMockTransport('ssh:ssh-1@@pty-1')
@@ -1927,17 +1890,12 @@ describe('connectPanePty', () => {
   })
 
   it('disarms input modes and resumes a hibernated agent session on visibility reveal', async () => {
-    // Regression: agent hibernation suppresses its kill's PTY exit while the
-    // pane is hidden. Before the wake fix, onExit consumed the suppression and
-    // permanently latched handledExitPtyId, so revealing the tab left a frozen
-    // alt-screen frame with mouse-tracking armed and no PTY — a fully inert
-    // ghost pane (no resume, no input, no selection).
+    // Regression: hibernation suppresses its kill's PTY exit while hidden; before the wake fix onExit permanently latched handledExitPtyId, leaving a frozen inert ghost pane on reveal.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-pane-2')
     transportFactoryQueue.push(transport)
     const manager = createManager(1)
-    // Hibernation only targets hidden background panes, so the exit lands while
-    // the pane is not visible and the wake must wait for the reveal.
+    // Hibernation only targets hidden panes, so the exit lands while not visible and the wake must wait for the reveal.
     const deps = createDeps({
       consumeSuppressedPtyExit: vi.fn(() => true),
       isVisibleRef: { current: false }
@@ -1966,16 +1924,13 @@ describe('connectPanePty', () => {
 
     const onPtyExit = createdTransportOptions[0]?.onPtyExit as ((ptyId: string) => void) | undefined
     expect(onPtyExit).toBeTypeOf('function')
-    // The deferred connect attached this transport to the persisted tab PTY,
-    // so the hibernation kill's exit must carry that id for the wake guard's
-    // same-pty check to model reality.
+    // The deferred connect attached this transport to the persisted tab PTY, so the kill's exit must carry that id for the wake guard's same-pty check.
     expect((transport.getPtyId as unknown as () => string | null)()).toBe('tab-pty')
     const connectCallsBeforeExit = transport.connect.mock.calls.length
     onPtyExit?.('tab-pty')
     await flushAsyncTicks()
 
-    // The frozen frame's input-eating modes are disarmed at hibernation-exit
-    // time (mouse tracking / bracketed paste would otherwise swallow clicks).
+    // The frozen frame's input-eating modes are disarmed at hibernation-exit (mouse tracking / bracketed paste would otherwise swallow clicks).
     const writesAfterExit = pane.terminal.write.mock.calls.flat().join('')
     expect(writesAfterExit).toContain('\x1b[?1003l')
     expect(writesAfterExit).toContain('\x1b[?2004l')
@@ -2000,9 +1955,7 @@ describe('connectPanePty', () => {
   })
 
   it('resumes a hibernated agent from a navigation-free wake without a visibility reveal', async () => {
-    // Mobile wake fanout drives wakeHibernatedAgentIfArmed on a still-hidden pane
-    // (no isVisible flip): the armed cold-restore --resume must fire exactly once
-    // even when the wake is delivered twice (INV-1 idempotency).
+    // Mobile wake fanout drives wakeHibernatedAgentIfArmed on a still-hidden pane (no isVisible flip): the armed --resume must fire exactly once even if delivered twice (INV-1).
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-pane-2')
     transportFactoryQueue.push(transport)
@@ -2041,8 +1994,7 @@ describe('connectPanePty', () => {
     // Still hidden: no reveal happened, so nothing respawned on exit.
     expect(transport.connect.mock.calls.length).toBe(connectCallsBeforeExit)
 
-    // The wake reports the claim it consumed so the dispatcher's generic
-    // resume never launches the same provider session into a second tab.
+    // The wake reports the claim it consumed so the dispatcher's generic resume never launches the same provider session into a second tab.
     const claimKey = 'wt-1\0claude\0session_id\0sess-hibernated-bg'
     expect(binding.wakeHibernatedAgentIfArmed(new Set([claimKey]))).toBeNull()
     expect(transport.connect.mock.calls.length).toBe(connectCallsBeforeExit)
@@ -2066,11 +2018,7 @@ describe('connectPanePty', () => {
   })
 
   it('latches a navigation-free wake that lands before the hibernation kill arms the pane', async () => {
-    // Race (#7906): mobile opens the worktree after the sleeping record is
-    // written but before the suppressed kill's exit sets hibernatedWakePtyId.
-    // The wake is edge-triggered and the phone never reveals the desktop pane,
-    // so without a latch the wake would be dropped and the phone left staring
-    // at a frozen terminal.
+    // Race (#7906): the edge-triggered wake can land after the sleeping record but before the kill sets hibernatedWakePtyId; without a latch it'd be dropped, leaving a frozen terminal.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-pane-2')
     transportFactoryQueue.push(transport)
@@ -2102,8 +2050,7 @@ describe('connectPanePty', () => {
     await flushAsyncTicks()
     expect((transport.getPtyId as unknown as () => string | null)()).toBe('tab-pty')
 
-    // Wake arrives mid-kill: nothing is armed yet, but the pane must claim the
-    // session (suppressing the generic resume) and latch the request.
+    // Wake arrives mid-kill: nothing is armed yet, but the pane must claim the session (suppressing the generic resume) and latch the request.
     const claimKey = 'wt-1\0claude\0session_id\0sess-hibernated-race'
     expect(binding.wakeHibernatedAgentIfArmed(new Set([claimKey]))).toBeNull()
     const claimedProviderSessions = new Set<string>()
@@ -2115,8 +2062,7 @@ describe('connectPanePty', () => {
     onPtyExit?.('tab-pty')
     await flushAsyncTicks()
 
-    // Arming consumed the latched wake — the --resume spawned with no reveal
-    // and no second wake event.
+    // Arming consumed the latched wake — the --resume spawned with no reveal and no second wake event.
     expect(transport.connect.mock.calls.length).toBeGreaterThan(connectCallsBeforeExit)
     const resumeConnectOptions = transport.connect.mock.calls.at(-1)?.[0] as
       | { command?: string }
@@ -2243,11 +2189,7 @@ describe('connectPanePty', () => {
   })
 
   it('auto-resumes a hibernated pane when its kill lands after the pane is already revealed', async () => {
-    // Race: the user reveals the background tab in the window between the
-    // coordinator confirming the candidate and the kill's exit arriving. The
-    // reveal's noteVisibilityResume runs before onExit arms the wake, so the
-    // arm-time foreground check must resume the pane instead of stranding a
-    // disarmed-but-dead frame until the next hide/reveal.
+    // Race: reveal's noteVisibilityResume runs before onExit arms the wake, so the arm-time foreground check must resume the pane instead of stranding a disarmed-but-dead frame.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-pane-2')
     transportFactoryQueue.push(transport)
@@ -2279,16 +2221,13 @@ describe('connectPanePty', () => {
 
     const onPtyExit = createdTransportOptions[0]?.onPtyExit as ((ptyId: string) => void) | undefined
     expect(onPtyExit).toBeTypeOf('function')
-    // The deferred connect attached this transport to the persisted tab PTY,
-    // so the hibernation kill's exit must carry that id for the wake guard's
-    // same-pty check to model reality.
+    // The deferred connect attached this transport to the persisted tab PTY, so the kill's exit must carry that id for the wake guard's same-pty check.
     expect((transport.getPtyId as unknown as () => string | null)()).toBe('tab-pty')
     const connectCallsBeforeExit = transport.connect.mock.calls.length
     onPtyExit?.('tab-pty')
     await flushAsyncTicks()
 
-    // No second reveal was needed: the foreground pane resumed its recorded
-    // session directly from the arm-time wake.
+    // No second reveal was needed: the foreground pane resumed its recorded session directly from the arm-time wake.
     expect(transport.connect.mock.calls.length).toBeGreaterThan(connectCallsBeforeExit)
     const resumeConnectOptions = transport.connect.mock.calls.at(-1)?.[0] as
       | { command?: string }
@@ -2304,11 +2243,7 @@ describe('connectPanePty', () => {
   })
 
   it('invalidates the hibernation wake when another flow rebinds the pane before reveal', async () => {
-    // Intentional restarts use the same exit suppression as hibernation. When
-    // one rebinds the pane to a fresh PTY while hidden, its spawn owns the
-    // pane: the armed wake must be discarded on reveal instead of launching a
-    // second resume over the restarted session — and discarded means gone, so
-    // a later death of the rebound PTY cannot revive the stale wake either.
+    // Why: intentional restarts share hibernation's exit suppression; a rebind while hidden owns the pane, so the armed wake must be discarded on reveal — permanently, not revived by a later death.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-pane-2')
     transportFactoryQueue.push(transport)
@@ -2352,8 +2287,7 @@ describe('connectPanePty', () => {
     // The rebound pane keeps its own session: no wake-driven resume spawn.
     expect(transport.connect.mock.calls.length).toBe(connectCallsBeforeExit)
 
-    // The rebound PTY later dies without a new sleeping record; the stale wake
-    // must not fire on the next reveal.
+    // The rebound PTY later dies without a new sleeping record; the stale wake must not fire on the next reveal.
     transport.getPtyId.mockReturnValue(null)
     binding.noteVisibilityResume()
     await flushAsyncTicks()
@@ -2361,10 +2295,7 @@ describe('connectPanePty', () => {
   })
 
   it('records hibernation activity from the core user-input signal, not synthetic onData replies', async () => {
-    // Regression: xterm auto-replies (focus in/out reports, DA/DSR responses)
-    // arrive through the same onData stream as typing. Recording them as pane
-    // input made the hibernation planner treat a pane hidden after its agent
-    // finished as "input after done" and never hibernate it.
+    // Regression: xterm auto-replies share the onData stream with typing; recording them as input made the planner see "input after done" and never hibernate.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-pane-2')
     transportFactoryQueue.push(transport)
@@ -2404,8 +2335,7 @@ describe('connectPanePty', () => {
   })
 
   it('falls back to onData hibernation recording when the core user-input signal is unavailable', async () => {
-    // If an xterm upgrade removes the internal signal, activity recording must
-    // degrade to the historical onData behavior — never to no tracking at all.
+    // If an xterm upgrade removes the internal signal, activity recording must degrade to the historical onData behavior — never to no tracking at all.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-pane-2')
     transportFactoryQueue.push(transport)
@@ -2465,10 +2395,7 @@ describe('connectPanePty', () => {
   })
 
   it('closes a hidden split pane whose PTY exits before output instead of keeping a ghost', async () => {
-    // Why (regression, ghost blank pane): the keep above is a visible-failure
-    // UX. A hidden pane's bytes are withheld by the hidden-delivery gate, so
-    // "no output" proves nothing there — keeping it strands a binding-less
-    // pane that remounts as a permanently blank ghost on reveal.
+    // Why (regression, ghost blank pane): a hidden pane's bytes are withheld by the hidden-delivery gate, so "no output" proves nothing — keeping it strands a blank ghost on reveal.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-pane-2')
     transportFactoryQueue.push(transport)
@@ -2491,11 +2418,7 @@ describe('connectPanePty', () => {
   })
 
   it('keeps a worktree sole terminal mounted when its freshly-spawned PTY exits before input (direnv failure)', async () => {
-    // Why (regression): a PR worktree can ship an .envrc whose direnv command
-    // fails, so the only terminal's login shell exits non-zero immediately. The
-    // sole-pane branch must NOT route to onPtyExitRef — that closes the tab and
-    // deactivates the just-created worktree (setActiveWorktree(null)), bouncing
-    // the user to the Landing screen. The dead pane stays mounted instead.
+    // Why (regression): a failing .envrc direnv makes the sole terminal's shell exit immediately; routing to onPtyExitRef would close the tab and bounce the user to Landing, so keep it mounted.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('tab-pty')
     transportFactoryQueue.push(transport)
@@ -2510,8 +2433,7 @@ describe('connectPanePty', () => {
     expect(onPtySpawn).toBeTypeOf('function')
     expect(onPtyExit).toBeTypeOf('function')
 
-    // A genuine fresh spawn (onPtySpawn fires only for non-reattach spawns) that
-    // the user never typed into.
+    // A genuine fresh spawn (onPtySpawn fires only for non-reattach spawns) the user never typed into.
     onPtySpawn?.('tab-pty')
     onPtyExit?.('tab-pty')
 
@@ -2520,8 +2442,7 @@ describe('connectPanePty', () => {
   })
 
   it('tears down the sole terminal when a freshly-spawned PTY exits after the user typed input', async () => {
-    // Why: an explicit `exit` (or any typed input) is a deliberate close, not a
-    // failed-startup shell, so the worktree should deactivate as before.
+    // Why: an explicit `exit` (or any typed input) is a deliberate close, not a failed-startup shell, so the worktree should deactivate as before.
     const { connectPanePty } = await import('./pty-connection')
     const pane = createPane(1)
     const transport = createMockTransport('tab-pty')
@@ -2546,9 +2467,7 @@ describe('connectPanePty', () => {
   })
 
   it('tears down the sole terminal when a reattached (not freshly spawned) PTY exits', async () => {
-    // Why: reattach/coldRestore skip onPtySpawn, so a previously-live session
-    // that is now dead must still route through onPtyExitRef — the keep-mounted
-    // guard is strictly for brand-new shells that died on startup.
+    // Why: reattach/coldRestore skip onPtySpawn, so a now-dead previously-live session must still route through onPtyExitRef; the keep-mounted guard is only for brand-new shells.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('tab-pty')
     transportFactoryQueue.push(transport)
@@ -2647,9 +2566,7 @@ describe('connectPanePty', () => {
   })
 
   it('does not send startup command via sendInput for local connections', async () => {
-    // Why: the local PTY provider already writes the command via
-    // writeStartupCommandWhenShellReady — sending it again from the renderer
-    // would cause the command to appear twice in the terminal.
+    // Why: the local PTY provider already writes the command via writeStartupCommandWhenShellReady; re-sending from the renderer would double it in the terminal.
     const { connectPanePty } = await import('./pty-connection')
 
     const capturedDataCallback: { current: ((data: string) => void) | null } = { current: null }
@@ -2677,8 +2594,7 @@ describe('connectPanePty', () => {
     // Simulate PTY output (shell prompt arriving)
     capturedDataCallback.current?.('(base) user@host $ ')
 
-    // Even after the debounce window, the renderer must not inject the command
-    // because the main process already wrote it via writeStartupCommandWhenShellReady.
+    // Even after the debounce, the renderer must not inject the command (main already wrote it via writeStartupCommandWhenShellReady).
     expect(transport.sendInput).not.toHaveBeenCalledWith(
       expect.stringContaining("claude 'say test'")
     )
@@ -4221,11 +4137,7 @@ describe('connectPanePty', () => {
   })
 
   it('drops xterm onData while pane is replaying restored bytes', async () => {
-    // Regression: during cold-restore / snapshot replay, xterm auto-replies
-    // to embedded query sequences (DA1, DECRQM, OSC 10/11, focus, CPR) via
-    // onData. Those replies must not pipe through to transport.sendInput, or
-    // they land as stray characters ("?1;2c", "2026;2$y", ...) on the new
-    // shell's prompt. See replay-guard.ts.
+    // Regression: during replay, xterm auto-replies to embedded queries (DA1/DECRQM/OSC/CPR) via onData must not reach transport.sendInput or they land as stray chars on the prompt. See replay-guard.ts.
     const { connectPanePty } = await import('./pty-connection')
 
     const transport = createMockTransport('pty-live')
@@ -4264,8 +4176,7 @@ describe('connectPanePty', () => {
     expect(transport.sendInput).toHaveBeenCalledWith('a')
     expect(transport.claimViewport).toHaveBeenCalledTimes(1)
     ;(onDataHandler as (data: string) => void)('b')
-    // The renderer stays parked until runtime convergence is acknowledged, so
-    // a second keystroke can retry a transient failed resize.
+    // The renderer stays parked until runtime convergence is acknowledged, so a second keystroke can retry a transient failed resize.
     expect(transport.claimViewport).toHaveBeenCalledTimes(2)
     setFitOverride('pty-live', 'desktop-fit', 0, 0)
   })
@@ -4539,8 +4450,7 @@ describe('connectPanePty', () => {
       }
       // Simulate xterm answering a TUI's DA1 query while the phone owns the PTY.
       ;(onDataHandler as unknown as (data: string) => void)('\x1b[?1;2c')
-      // Capability handlers are registered outside onData and must honor the
-      // same mobile query-authority lock.
+      // Capability handlers are registered outside onData and must honor the same mobile query-authority lock.
       const csiCalls = (
         pane.terminal.parser.registerCsiHandler as unknown as {
           mock: { calls: [{ final: string }, (params: (number | number[])[]) => boolean][] }
@@ -4716,8 +4626,7 @@ describe('connectPanePty', () => {
   })
 
   it('sends fast startup commands via sendInput for SSH connections', async () => {
-    // Capture the setTimeout callback directly so we can fire it without
-    // vi.useFakeTimers() (which would also replace the rAF mock from beforeEach).
+    // Capture the setTimeout callback directly so we can fire it without vi.useFakeTimers() (which would also replace beforeEach's rAF mock).
     const pendingTimeouts: (() => void)[] = []
     const originalSetTimeout = globalThis.setTimeout
     globalThis.setTimeout = vi.fn((fn: () => void) => {
@@ -4740,15 +4649,12 @@ describe('connectPanePty', () => {
       )
       transportFactoryQueue.push(transport)
 
-      // SSH connection: connectionId is set, relay receives command metadata
-      // for spawn context but the renderer owns fast command delivery.
+      // SSH connection: connectionId set; relay gets command metadata for spawn context but the renderer owns fast command delivery.
       mockStoreState = {
         ...mockStoreState,
         tabsByWorktree: { 'wt-1': [{ id: 'tab-1', ptyId: null }] },
         repos: [{ id: 'repo1', connectionId: 'ssh-conn-1' }],
-        // Why: startup delivery assumes a live connection; a disconnected
-        // target now routes through the deferred-connect gate instead of
-        // spawning synchronously.
+        // Why: startup delivery assumes a live connection; a disconnected target routes through the deferred-connect gate instead of spawning synchronously.
         sshConnectionStates: new Map([['ssh-conn-1', { status: 'connected' }]])
       }
 
@@ -4800,9 +4706,7 @@ describe('connectPanePty', () => {
         ...mockStoreState,
         tabsByWorktree: { 'wt-1': [{ id: 'tab-1', ptyId: null }] },
         repos: [{ id: 'repo1', connectionId: 'ssh-conn-1' }],
-        // Why: startup delivery assumes a live connection; a disconnected
-        // target now routes through the deferred-connect gate instead of
-        // spawning synchronously.
+        // Why: startup delivery assumes a live connection; a disconnected target routes through the deferred-connect gate instead of spawning synchronously.
         sshConnectionStates: new Map([['ssh-conn-1', { status: 'connected' }]])
       }
 
@@ -4868,8 +4772,7 @@ describe('connectPanePty', () => {
     await flushAsyncTicks()
     expect(capturedDataCallback.current).not.toBeNull()
 
-    // A focused xterm emits CSI I after Codex enables focus reporting. The
-    // startup draft must use the same transport instead of racing a direct IPC.
+    // A focused xterm emits CSI I after Codex enables focus reporting; the startup draft must reuse the same transport instead of racing a direct IPC.
     ;(
       pane.terminal.onData as unknown as {
         mock: { calls: [(data: string) => void][] }
@@ -4956,9 +4859,7 @@ describe('connectPanePty', () => {
         ...mockStoreState,
         tabsByWorktree: { 'wt-1': [{ id: 'tab-1', ptyId: null }] },
         repos: [{ id: 'repo1', connectionId: 'ssh-conn-1' }],
-        // Why: startup delivery assumes a live connection; a disconnected
-        // target now routes through the deferred-connect gate instead of
-        // spawning synchronously.
+        // Why: startup delivery assumes a live connection; a disconnected target routes through the deferred-connect gate instead of spawning synchronously.
         sshConnectionStates: new Map([['ssh-conn-1', { status: 'connected' }]])
       }
 
@@ -5015,9 +4916,7 @@ describe('connectPanePty', () => {
         ...mockStoreState,
         tabsByWorktree: { 'wt-1': [{ id: 'tab-1', ptyId: null }] },
         repos: [{ id: 'repo1', connectionId: 'ssh-conn-1' }],
-        // Why: startup delivery assumes a live connection; a disconnected
-        // target now routes through the deferred-connect gate instead of
-        // spawning synchronously.
+        // Why: startup delivery assumes a live connection; a disconnected target routes through the deferred-connect gate instead of spawning synchronously.
         sshConnectionStates: new Map([['ssh-conn-1', { status: 'connected' }]])
       }
 
@@ -5074,9 +4973,7 @@ describe('connectPanePty', () => {
         ...mockStoreState,
         tabsByWorktree: { 'wt-1': [{ id: 'tab-1', ptyId: null }] },
         repos: [{ id: 'repo1', connectionId: 'ssh-conn-1' }],
-        // Why: startup delivery assumes a live connection; a disconnected
-        // target now routes through the deferred-connect gate instead of
-        // spawning synchronously.
+        // Why: startup delivery assumes a live connection; a disconnected target routes through the deferred-connect gate instead of spawning synchronously.
         sshConnectionStates: new Map([['ssh-conn-1', { status: 'connected' }]])
       }
 
@@ -5130,9 +5027,7 @@ describe('connectPanePty', () => {
         ...mockStoreState,
         tabsByWorktree: { 'wt-1': [{ id: 'tab-1', ptyId: null }] },
         repos: [{ id: 'repo1', connectionId: 'ssh-conn-1' }],
-        // Why: startup delivery assumes a live connection; a disconnected
-        // target now routes through the deferred-connect gate instead of
-        // spawning synchronously.
+        // Why: startup delivery assumes a live connection; a disconnected target routes through the deferred-connect gate instead of spawning synchronously.
         sshConnectionStates: new Map([['ssh-conn-1', { status: 'connected' }]])
       }
 
@@ -5338,11 +5233,7 @@ describe('connectPanePty', () => {
   })
 
   it('confirms an Orca-launched Droid fresh spawn in a no-OSC shell (Git Bash)', async () => {
-    // Why: PowerShell gets an OSC 133 command-start that triggers the confirming
-    // foreground read, but Git Bash / cmd.exe emit no command boundary and the
-    // launch command is injected programmatically (no typed inference). Without a
-    // fresh-spawn sample the pane never earns routing trust, so Shift+Enter falls
-    // back to Esc+CR and Droid submits instead of inserting a newline (#7620).
+    // Why: no-OSC shells (Git Bash/cmd) emit no command boundary, so without a fresh-spawn sample the pane never earns routing trust and Shift+Enter regresses to Esc+CR (#7620).
     vi.useFakeTimers()
     const { connectPanePty } = await import('./pty-connection')
     vi.mocked(window.api.pty.getForegroundProcess).mockResolvedValue('droid')
@@ -5381,8 +5272,7 @@ describe('connectPanePty', () => {
   })
 
   it('trusts a launched Droid whose no-OSC boot only becomes foreground after retries', async () => {
-    // Why: the confirmation ladder must span Droid's boot — the shell is still
-    // foreground on the first read(s) before Droid takes over.
+    // Why: the confirmation ladder must span Droid's boot — the shell is still foreground on the first read(s) before Droid takes over.
     vi.useFakeTimers()
     const { connectPanePty } = await import('./pty-connection')
     const foregroundResults = ['bash.exe', 'bash.exe', 'droid']
@@ -5416,11 +5306,7 @@ describe('connectPanePty', () => {
   })
 
   it('stays recoverable when a launched Droid outlasts the fresh-spawn confirmation window', async () => {
-    // Why: if the bounded ladder misses (pathologically slow boot), the miss must
-    // NOT latch a known-agent shell-confirm — that would clear launch identity and
-    // block every later focus/reveal re-sample, permanently poisoning Shift+Enter
-    // for the session. A benign miss leaves the pane recoverable, so a later focus
-    // sample (once Droid is finally foreground) still earns routing trust.
+    // Why: a missed ladder (slow boot) must stay recoverable — latching a shell-confirm would clear launch identity and poison Shift+Enter for the session.
     vi.useFakeTimers()
     const { connectPanePty } = await import('./pty-connection')
     let foreground = 'bash.exe'
@@ -5969,9 +5855,7 @@ describe('connectPanePty', () => {
 
     connectPanePty(pane as never, manager as never, deps as never)
 
-    // Why: Option 2 deferred reattach uses connect({ sessionId }) instead of
-    // attach({ existingPtyId }) so the daemon's createOrAttach runs at the
-    // pane's real fitAddon dimensions.
+    // Why: deferred reattach uses connect({ sessionId }) not attach() so the daemon's createOrAttach runs at the pane's real fitAddon dimensions.
     expect(transport.connect).toHaveBeenCalledWith(
       expect.objectContaining({ sessionId: 'leaf-pty-2' })
     )
@@ -6025,11 +5909,7 @@ describe('connectPanePty', () => {
   })
 
   it('adopts a live eager PTY and withholds snapshots after its renderer dies', async () => {
-    // Why: background automation tabs spawn the agent PTY eagerly and register an
-    // eager buffer, then never mount until opened. On first mount the restored
-    // ptyId equals the tab ptyId, so without this guard the pane mis-routes into
-    // the daemon-reattach branch (connect) and spawns a fresh shell, orphaning the
-    // live agent PTY. A live eager buffer means "attach + replay", not "reattach".
+    // Why: a live eager buffer means "attach + replay", not "reattach" — else first mount mis-routes to daemon-reattach and orphans the eager agent PTY.
     const eagerPtyId = 'auto-eager-pty'
     vi.mocked(getEagerPtyBufferHandle).mockImplementation((ptyId: string) =>
       ptyId === eagerPtyId ? { flush: () => '', dispose: () => {} } : undefined
@@ -6084,8 +5964,7 @@ describe('connectPanePty', () => {
   })
 
   it('does not adopt another tab live eager PTY from a stale restored leaf binding', async () => {
-    // Why: restored leaf bindings can outlive tab ownership. A global eager
-    // buffer only proves the PTY is alive; ptyIdsByTabId proves this tab owns it.
+    // Why: restored leaf bindings can outlive tab ownership; a global eager buffer proves the PTY is alive, ptyIdsByTabId proves this tab owns it.
     const otherTabPtyId = 'other-tab-eager-pty'
     vi.mocked(getEagerPtyBufferHandle).mockImplementation((ptyId: string) =>
       ptyId === otherTabPtyId ? { flush: () => '', dispose: () => {} } : undefined
@@ -6175,9 +6054,7 @@ describe('connectPanePty', () => {
   })
 
   it('reattaches via the tab-level SSH pty id when deferred bookkeeping missed the tab', async () => {
-    // Why: restore can miss the deferred maps (e.g. activeConnectionIdsAtShutdown
-    // wasn't persisted). The tab's own app SSH pty id must still drive a
-    // connect-then-reattach instead of a fresh spawn into a missing provider.
+    // Why: restore can miss the deferred maps; the tab's SSH pty id must still drive connect-then-reattach, not a fresh spawn into a missing provider.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport()
     transportFactoryQueue.push(transport)
@@ -6205,8 +6082,7 @@ describe('connectPanePty', () => {
   })
 
   it('connects a disconnected SSH target before fresh-spawning instead of erroring', async () => {
-    // Why: spawning against a disconnected target throws "No PTY provider"
-    // and strands the pane behind a toast that never retries.
+    // Why: spawning against a disconnected target throws "No PTY provider" and strands the pane behind a toast that never retries.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('fresh-ssh-pty')
     transportFactoryQueue.push(transport)
@@ -6449,11 +6325,7 @@ describe('connectPanePty', () => {
   })
 
   it('resizes the pane to the snapshot grid before replaying daemon snapshot bytes (bug #7279)', async () => {
-    // Why: the daemon serializes soft-wrapped lines as continuous text. Replaying
-    // that at the pane's current column count rewraps rows one cell early/late.
-    // The reattach path must resize xterm to the snapshot's grid before writing
-    // the snapshot bytes, so a remote pane whose size drifted from the daemon's
-    // grid still repaints the exact host layout.
+    // Why: the daemon serializes soft-wrapped lines flat, so reattach must resize xterm to the snapshot grid before writing, or rows rewrap wrong.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('tab-pty')
     transport.connect.mockImplementation(async ({ sessionId }: { sessionId?: string }) => {
@@ -6475,8 +6347,7 @@ describe('connectPanePty', () => {
       }
     } as StoreState
 
-    // createPane opens the pane at 120x40, deliberately different from the
-    // daemon snapshot's 80x24 grid.
+    // createPane opens the pane at 120x40, deliberately different from the daemon snapshot's 80x24 grid.
     const pane = createPane(1)
     const manager = createManager(1)
     const deps = createDeps({
@@ -6597,8 +6468,7 @@ describe('connectPanePty', () => {
     await flushAsyncTicks(20)
     expect(pane.terminal.scrollToLine).not.toHaveBeenCalled()
 
-    // Model xterm's native pinned state after clear + replay: the old line
-    // number is no longer meaningful, but the old distance from bottom is.
+    // Model xterm's native pinned state after clear+replay: the old line number is meaningless, but distance-from-bottom is preserved.
     pane.terminal.buffer.active.baseY = 200
     pane.terminal.buffer.active.viewportY = 0
     while (parseCallbacks.length > 0) {
@@ -6792,10 +6662,7 @@ describe('connectPanePty', () => {
   })
 
   it('writes the daemon pendingEscapeTailAnsi after the reset on local reattach (#7329)', async () => {
-    // Why: the mid-escape tail must be re-armed LAST — after the reattach reset,
-    // whose ESC would abort it — so the racing live continuation completes it
-    // instead of rendering literally. Covers the local daemon reattach path,
-    // which previously dropped the field the remote path already honored.
+    // Why: re-arm the mid-escape tail LAST, after the reattach reset whose ESC would abort it, so a live continuation completes it.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('tab-pty')
     transport.connect.mockImplementation(async ({ sessionId }: { sessionId?: string }) => {
@@ -6839,10 +6706,7 @@ describe('connectPanePty', () => {
   })
 
   it('routes native onData query replies through sendInputImmediate, typed input through sendInput (#7329)', async () => {
-    // Why this test: the mock transport delegates sendInputImmediate to the
-    // sendInput spy, so reply-delivery assertions elsewhere cannot tell the two
-    // apart — reverting the onData isTerminalQueryReply branch used to pass the
-    // whole suite. This pins the routing decision itself.
+    // Why this test: the mock aliases sendInputImmediate to sendInput, so other tests can't tell them apart; this pins the routing decision.
     const { connectPanePty } = await import('./pty-connection')
     enableActiveRuntimeEnvironment()
     const pane = createPane(1)
@@ -6854,9 +6718,7 @@ describe('connectPanePty', () => {
     connectPanePty(pane as never, manager as never, deps as never)
     await flushAsyncTicks()
 
-    // xterm answers CSI 6n natively by emitting a CPR through onData, mixed
-    // with keystrokes. It must take the immediate path (skips the remote 8ms
-    // input debounce that corrupted it).
+    // xterm answers CSI 6n natively with a CPR via onData; it must take the immediate path (skips the remote 8ms debounce that corrupted it).
     sendTerminalInputThroughPane(pane, '\x1b[3;1R')
     expect(transport.sendInputImmediate).toHaveBeenCalledWith('\x1b[3;1R')
 
@@ -6868,15 +6730,13 @@ describe('connectPanePty', () => {
     expect(transport.sendInput).toHaveBeenCalledWith('\x1b[A')
     expect(transport.sendInputImmediate).not.toHaveBeenCalled()
 
-    // terminal-query-reply.test proves real xterm emits this as one fully framed
-    // onData reply; this pins that production-shaped reply to the immediate path.
+    // terminal-query-reply.test proves real xterm emits this as one framed onData reply; this pins it to the immediate path.
     transport.sendInputImmediate.mockClear()
     const xtversionReply = '\x1bP>|xterm.js(6.1.0-beta.287)\x1b\\'
     sendTerminalInputThroughPane(pane, xtversionReply)
     expect(transport.sendInputImmediate).toHaveBeenCalledWith(xtversionReply)
 
-    // Printable input is user-owned. Remote cooked echo comes back through PTY
-    // output, not onData, so xterm/OSC-looking text must stay on normal input.
+    // Printable input is user-owned: remote cooked echo returns via PTY output, not onData, so OSC-looking text stays on normal input.
     transport.sendInput.mockClear()
     transport.sendInputImmediate.mockClear()
     const printableInputs = [']10;hello', '>|xterm.js(6.1.0-beta.287)', ']|literal-text']
@@ -6888,10 +6748,7 @@ describe('connectPanePty', () => {
   })
 
   it('writes the onReplayData pendingEscapeTailAnsi meta last, after the replayed bytes (#7329)', async () => {
-    // Why this test: the remote snapshot path delivers the daemon tail through
-    // transport callbacks.onReplayData meta into drainReplayDataQueue. That
-    // consumer (and the replayDataCallback meta threading before it) had no
-    // failing test — severing the meta pass-through kept the suite green.
+    // Why this test: the onReplayData meta pass-through had no failing test — severing it kept the suite green.
     const { connectPanePty } = await import('./pty-connection')
     enableActiveRuntimeEnvironment()
     const pane = createPane(1)
@@ -6931,8 +6788,7 @@ describe('connectPanePty', () => {
     const tailIndex = writes.lastIndexOf('\x1b[3')
     expect(snapshotIndex).toBeGreaterThanOrEqual(0)
     expect(tailIndex).toBeGreaterThanOrEqual(0)
-    // The dangling tail is re-armed after the snapshot (and any reset), so the
-    // next live chunk's continuation completes it instead of rendering literally.
+    // The dangling tail is re-armed after the snapshot/reset, so the next live chunk completes it instead of rendering literally.
     expect(tailIndex).toBeGreaterThan(snapshotIndex)
     expect(writes.slice(tailIndex + 1)).toEqual([])
   })
@@ -6951,8 +6807,7 @@ describe('connectPanePty', () => {
 
     const pane = createPane(1)
     const textarea = {} as HTMLTextAreaElement
-    // Why: public xterm modes plus an agent title are the stable signal for a
-    // live focus-driven TUI; avoid private `_core` field probes.
+    // Why: public xterm modes plus an agent title are the stable signal for a live focus-driven TUI; avoid private `_core` probes.
     configureTerminalFocusMode(pane, textarea)
     await withMockedDocumentActiveElement(textarea, async () => {
       const manager = createManager(1)
@@ -6965,9 +6820,7 @@ describe('connectPanePty', () => {
       await flushAsyncTicks(20)
 
       expect(transport.sendInput).toHaveBeenCalledWith('\x1b[I')
-      // The snapshot ends with ?25l (Cursor Agent parks the real cursor and
-      // hides it); the reset must preserve that instead of forcing ?25h, or
-      // the parked cursor paints as a stray block below the prompt.
+      // Snapshot ends with ?25l (Cursor Agent parks/hides the cursor); the reset must preserve it, not force ?25h, or a stray block paints.
       expect(pane.terminal.write).toHaveBeenCalledWith(
         `${RESET_TERMINAL_CURSOR_STYLE}${RESET_KITTY_KEYBOARD_PROTOCOL}`,
         expect.any(Function)
@@ -7027,8 +6880,7 @@ describe('connectPanePty', () => {
     const pane = createPane(1)
     const textarea = {} as HTMLTextAreaElement
     configureTerminalFocusMode(pane, textarea)
-    // Why: a different element owns focus, so the reattach must not send a stray
-    // focus-in to a background pane.
+    // Why: a different element owns focus, so the reattach must not send a stray focus-in to a background pane.
     await withMockedDocumentActiveElement({}, async () => {
       const manager = createManager(1)
       const deps = createDeps({
@@ -7094,9 +6946,7 @@ describe('connectPanePty', () => {
       return null
     })
     transportFactoryQueue.push(transport)
-    // Why: launchAgent is launch ownership metadata that never decays after
-    // the agent exits; it must not preserve stale modes for the shell left
-    // behind after an unclean agent death.
+    // Why: launchAgent is launch-ownership metadata that never decays; it must not preserve stale modes for a shell left after agent death.
     mockStoreState = {
       ...mockStoreState,
       tabsByWorktree: {
@@ -7142,8 +6992,7 @@ describe('connectPanePty', () => {
       return null
     })
     transportFactoryQueue.push(transport)
-    // Why: broad token matching would classify this ordinary ssh title as an
-    // agent and preserve stale modes / inject focus-in into a bare shell.
+    // Why: broad token matching would classify this ordinary ssh title as an agent and preserve stale modes into a bare shell.
     setReattachPaneTitle('ssh devin@host')
 
     const pane = createPane(1)
@@ -7259,11 +7108,7 @@ describe('connectPanePty', () => {
     )
   })
 
-  // Why: when a reattach result carries both snapshot and replay (the daemon
-  // host serves the snapshot, the relay replay buffer covers the same tail),
-  // painting both into xterm doubles the same lines. This is the duplicated-
-  // TUI-output symptom users saw on worktree switch. Snapshot is the freshest
-  // authoritative source and wins by precedence.
+  // Why: a reattach with both snapshot and replay paints the same tail twice (dup-TUI-output on switch); snapshot wins by precedence.
   it('paints only the daemon snapshot when reattach result includes both snapshot and replay', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('tab-pty')
@@ -7332,9 +7177,7 @@ describe('connectPanePty', () => {
 
     expect(pane.terminal.write).toHaveBeenCalledWith('replay-payload', expect.any(Function))
     expect(pane.terminal.write).not.toHaveBeenCalledWith('cold-payload', expect.any(Function))
-    // Why: the replay branch supersedes cold-restore but must still ack so
-    // the daemon does not redeliver the cold-restore payload on the next
-    // reattach.
+    // Why: the replay branch supersedes cold-restore but must still ack, or the daemon redelivers the cold-restore payload next reattach.
     expect(window.api.pty.ackColdRestore).toHaveBeenCalledWith('tab-pty')
   })
 
@@ -7494,9 +7337,7 @@ describe('connectPanePty', () => {
     )
     expect(viewportClearOperation).toBeLessThan(recoveredResizeOperation)
 
-    // Model the real operation order. The previous behavior appended the
-    // recovered 20-column snapshot to a dirty 10-column xterm, leaving stale
-    // cells and wrapping each authoritative row at the wrong grid.
+    // Model the real op order: the old path appended a 20-col snapshot onto a dirty 10-col xterm, wrapping rows at the wrong grid.
     const rendered = new Terminal({
       cols: destinationCols,
       rows: destinationRows,
@@ -7737,8 +7578,7 @@ describe('connectPanePty', () => {
     })
     transportFactoryQueue.push(transport)
     const paneKey = makePaneKey('tab-1', LEAF_1)
-    // Why: after an app restart agentStatusByPaneKey is empty — the persisted
-    // sleeping record is the only source of the provider session id (#5232).
+    // Why: after restart agentStatusByPaneKey is empty — the persisted sleeping record is the only provider session id source (#5232).
     mockStoreState = {
       ...mockStoreState,
       tabsByWorktree: {
@@ -7798,8 +7638,7 @@ describe('connectPanePty', () => {
         })
       })
     )
-    // Why: consuming the record prevents a later worktree activation from
-    // launching a duplicate resume tab for the same session.
+    // Why: consuming the record prevents a later worktree activation from launching a duplicate resume tab.
     expect(mockStoreState.clearSleepingAgentSession).toHaveBeenCalledWith(paneKey)
   })
 
@@ -8659,8 +8498,7 @@ describe('connectPanePty', () => {
         if (!sessionId) {
           return null
         }
-        // Why: the real dispatcher drains bytes emitted after snapshot capture
-        // as soon as the spawn IPC resolves, before connect() returns.
+        // Why: the real dispatcher drains post-snapshot bytes as soon as spawn IPC resolves, before connect() returns.
         callbacks?.onData?.('post-snapshot-live')
         return { id: sessionId, snapshot: 'authoritative-snapshot' }
       }
@@ -8871,10 +8709,7 @@ describe('connectPanePty', () => {
     expect(deps.updateTabPtyId).not.toHaveBeenCalled()
   })
 
-  // Why: Phase 6 deleted the hidden-skip eligibility grammar. With the kill
-  // switch off, EVERY hidden chunk — plain, control-heavy, rich glyphs,
-  // synchronized frames, embedded queries — rides the bounded background
-  // scheduler queue and parses in xterm; nothing is content-scanned per chunk.
+  // Why: Phase 6 deleted the hidden-skip grammar — every hidden chunk rides the background scheduler, none content-scanned.
   it('queues hidden PTY bytes on the background scheduler without per-chunk scanning', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-id')
@@ -8991,8 +8826,7 @@ describe('connectPanePty', () => {
       dataCallback('hidden output\r\n', { seq: 16, rawLength: 16 })
       expect(setHiddenRendererPty).toHaveBeenCalledWith('pty-id', true)
 
-      // Why: with the skip grammar gone, gated drops latch the restore via
-      // main's out-of-band marker, not a renderer-side content scan.
+      // Why: with the skip grammar gone, gated drops latch the restore via main's out-of-band marker, not a renderer content scan.
       const { _dispatchPtyModelRestoreNeededForTest } = await import('./pty-model-restore-channel')
       _dispatchPtyModelRestoreNeededForTest({ id: 'pty-id', reason: 'hidden-drop', markerSeq: 64 })
 
@@ -9059,10 +8893,7 @@ describe('connectPanePty', () => {
     })
 
     it('kicks pane recovery when reveal finds the write pipeline certified dead', async () => {
-      // The 2026-07-13 fossil-pane incident shape: bytes drop while hidden,
-      // the pipeline is certified dead, and certification's own recovery
-      // request came up empty — reveal must re-kick recovery instead of
-      // silently skipping the restore and stranding the stale frame.
+      // 2026-07-13 fossil-pane incident: bytes drop while hidden, pipeline certified dead, cert recovery empty — reveal must re-kick it.
       enableMainAuthority()
       const remountTerminalTabForRecovery = vi.fn<(tabId: string) => boolean>(() => true)
       mockStoreState = { ...mockStoreState, remountTerminalTabForRecovery } as StoreState
@@ -9082,8 +8913,7 @@ describe('connectPanePty', () => {
 
       dataCallback('hidden output\r\n', { seq: 16, rawLength: 16 })
 
-      // Pipeline dies while hidden; the certification-time recovery request
-      // finds no remountable tab (budget stays unconsumed, no retry timer).
+      // Pipeline dies while hidden; certification-time recovery finds no remountable tab (budget unconsumed, no retry timer).
       remountTerminalTabForRecovery.mockReturnValueOnce(false)
       const ackCredit = vi.fn()
       const { writeTerminalOutput } =
@@ -9107,8 +8937,7 @@ describe('connectPanePty', () => {
       requestTerminalBacklogRecovery(pane.terminal as never)
       await flushAsyncTicks(20)
 
-      // Restore stays skipped (a dead pipeline can never parse the snapshot),
-      // but recovery got exactly one re-kick for the revealed pane.
+      // Restore stays skipped (a dead pipeline can't parse the snapshot), but recovery got exactly one re-kick.
       expect(getMainBufferSnapshot).not.toHaveBeenCalled()
       expect(remountTerminalTabForRecovery).toHaveBeenCalledTimes(2)
       expect(remountTerminalTabForRecovery).toHaveBeenLastCalledWith('tab-1')
@@ -9152,8 +8981,7 @@ describe('connectPanePty', () => {
       transportOptions.onPtySpawn?.('pty-id')
       const factsHandler = await import('./terminal-side-effect-facts-handler')
 
-      // Why: Phase 6 deleted the 10s codex window — codex startups gate like
-      // any hidden pane and the main responder answers their startup probes.
+      // Why: Phase 6 deleted the 10s codex window — codex startups gate like any hidden pane; main answers their startup probes.
       dataCallback('startup probe output\r\n')
       expect(setHiddenRendererPty).toHaveBeenCalledWith('pty-id', true)
 
@@ -9180,8 +9008,7 @@ describe('connectPanePty', () => {
         rows: 30,
         seq: 64
       })
-      // Why: the marker subscription is keyed by the live PTY id — the byte
-      // path latches it on the first hidden chunk, like the hidden mark.
+      // Why: the marker subscription is keyed by the live PTY id — the byte path latches it on the first hidden chunk.
       dataCallback('pre-drop output\r\n', { seq: 16, rawLength: 17 })
       const { _dispatchPtyModelRestoreNeededForTest } = await import('./pty-model-restore-channel')
 
@@ -9205,17 +9032,14 @@ describe('connectPanePty', () => {
       enableMainAuthority()
       const deps = createDeps({ isVisibleRef: { current: false } })
       const { transport } = await connectHiddenPane(deps)
-      // Simulate the transport's spawn completion so the pane registers its
-      // side-effect fact consumer (the mock transport never calls onPtySpawn).
+      // Simulate spawn completion so the pane registers its fact consumer (mock transport never calls onPtySpawn).
       const transportOptions = createdTransportOptions.at(-1) as {
         onPtySpawn?: (ptyId: string) => void
       }
       transportOptions.onPtySpawn?.('pty-id')
       const factsHandler = await import('./terminal-side-effect-facts-handler')
 
-      // Why: no pty:data has flowed, so no hidden mark was sent — the fact
-      // can outrun the mark (codex post-startup-window race) and must still
-      // reply: ownership is structural, never mark-dependent.
+      // Why: the fact can outrun the hidden mark (codex startup race) and must still reply — ownership is structural, not mark-dependent.
       factsHandler._dispatchTerminalSideEffectBatchForTest({
         ptyId: 'pty-id',
         seq: 12,
@@ -9224,9 +9048,7 @@ describe('connectPanePty', () => {
       expect(transport.sendInput).toHaveBeenCalledTimes(1)
       expect(transport.sendInput).toHaveBeenCalledWith('\x1b[?997;1n')
 
-      // Why: a visible gated pane still answers via the fact — the lifecycle
-      // suppresses the xterm CSI reply for gate-managed panes, so this stays
-      // the only reply for the new subscribe.
+      // Why: a visible gated pane still answers via the fact — the lifecycle suppresses xterm's CSI reply for gate-managed panes.
       ;(deps.isVisibleRef as { current: boolean }).current = true
       factsHandler._dispatchTerminalSideEffectBatchForTest({
         ptyId: 'pty-id',
@@ -9258,9 +9080,7 @@ describe('connectPanePty', () => {
       })
 
       expect(transport.sendInput).toHaveBeenCalledWith('\x1b[?997;1n')
-      // Why: without the registry write, applyTerminalAppearance's
-      // maybePushMode2031Flip never pushes CSI 997 after a theme change and
-      // the revealed TUI keeps a stale theme.
+      // Why: without the registry write, maybePushMode2031Flip won't push CSI 997 after a theme change, so the TUI keeps a stale theme.
       expect(recordPaneMode2031Subscription).toHaveBeenCalledWith(1, 'dark')
     })
 
@@ -9278,9 +9098,7 @@ describe('connectPanePty', () => {
       enableMainAuthority()
       const deps = createDeps({ isVisibleRef: { current: false } })
       const { transport } = await connectHiddenPane(deps)
-      // Why: waiting for the first dataCallback sync left a spawn-time query
-      // window where neither side replied (the spawn-time DA1 loss). The flag
-      // lets main mark the PTY hidden before its first byte.
+      // Why: mark the PTY hidden before its first byte, closing the spawn-time DA1-loss window where neither side replied.
       expect(transport.connect).toHaveBeenCalledWith(
         expect.objectContaining({ initiallyHidden: true })
       )
@@ -9300,11 +9118,7 @@ describe('connectPanePty', () => {
         startup: { command: 'codex' }
       })
       const { transport } = await connectHiddenPane(deps)
-      // Why: the 10s codex startup window is deleted — codex spawns are
-      // main-owned from byte zero, with the model responder answering their
-      // startup probes (including ConPTY's blocking DA1; the main-side pin is
-      // pty.test.ts 'answers DA1 from the model on the first chunk of a
-      // hidden-at-spawn PTY').
+      // Why: the 10s codex startup window is gone — codex spawns are main-owned from byte zero (main pin: pty.test.ts DA1-from-model).
       expect(transport.connect).toHaveBeenCalledWith(
         expect.objectContaining({ initiallyHidden: true })
       )
@@ -9318,8 +9132,7 @@ describe('connectPanePty', () => {
       } as StoreState['settings']
       const deps = createDeps({ isVisibleRef: { current: false } })
       const { transport, dataCallback, binding } = await connectHiddenPane(deps)
-      // Why: the lifecycle's xterm CSI observer consults this predicate —
-      // kill switch off must keep the legacy xterm reply path.
+      // Why: the lifecycle's xterm CSI observer consults this predicate — kill switch off keeps the legacy xterm reply path.
       expect(
         (
           binding as typeof binding & { isHiddenDeliveryGateManagedPty: () => boolean }
@@ -9334,8 +9147,7 @@ describe('connectPanePty', () => {
       dataCallback('hidden output\r\n')
       expect(setHiddenRendererPty).not.toHaveBeenCalled()
 
-      // Why: gate off keeps the byte-scan responder authoritative — the fact
-      // must not produce a second reply for the same subscribe.
+      // Why: gate off keeps the byte-scan responder authoritative — the fact must not produce a second reply.
       const factsHandler = await import('./terminal-side-effect-facts-handler')
       factsHandler._dispatchTerminalSideEffectBatchForTest({
         ptyId: 'pty-id',
@@ -9359,10 +9171,7 @@ describe('connectPanePty', () => {
     })
 
     it('never treats a live chunk that strips to empty as a restore marker', async () => {
-      // Why: a chunk that is purely OSC 9999 reaches the data callback as ''
-      // (transport stripping) — only the out-of-band pty:modelRestoreNeeded
-      // channel may trigger a snapshot restore, or visible panes would be
-      // spuriously cleared and repainted mid-session.
+      // Why: an all-OSC-9999 chunk arrives as '' after stripping; only pty:modelRestoreNeeded may trigger a restore, not the empty byte path.
       enableMainAuthority()
       const deps = createDeps({ isVisibleRef: { current: true } })
       const { dataCallback } = await connectHiddenPane(deps)
@@ -9403,10 +9212,7 @@ describe('connectPanePty', () => {
       expect(getMainBufferSnapshot).toHaveBeenCalledTimes(1)
 
       try {
-        // Why (rc.7.perf feedback loop): a second drop marker while the first
-        // snapshot is still serializing on a VISIBLE pane is this pane's own
-        // restore backpressure. Re-fetching per marker kept the loop alive for
-        // the whole flood — the marker must NOT schedule another fetch.
+        // Why (rc.7.perf): a second drop marker while the first snapshot serializes is self-backpressure; must NOT re-fetch.
         vi.useFakeTimers()
         _dispatchPtyModelRestoreNeededForTest({
           id: 'pty-id',
@@ -9417,8 +9223,7 @@ describe('connectPanePty', () => {
         await flushAsyncTicks(20)
         expect(getMainBufferSnapshot).toHaveBeenCalledTimes(1)
 
-        // Flood quiet: the suppression window elapses and exactly ONE deferred
-        // repaint fetches a fresh snapshot to heal the dropped gap.
+        // Flood quiet: suppression window elapses and exactly ONE deferred repaint heals the dropped gap.
         vi.advanceTimersByTime(2_100)
         await flushAsyncTicks(20)
         expect(getMainBufferSnapshot).toHaveBeenCalledTimes(2)
@@ -9499,8 +9304,7 @@ describe('connectPanePty', () => {
         pane.terminal.buffer.active.baseY = 100
         markTerminalPinnedViewport(pane.terminal)
 
-        // Flood while the snapshot is in flight: overflows the 512KB restore
-        // queue — the live stream is outrunning snapshot fetch+replay.
+        // Flood while the snapshot is in flight: overflows the 512KB restore queue.
         dataCallback('f'.repeat(300 * 1024), { seq: 300 * 1024 + 64, rawLength: 300 * 1024 })
         dataCallback('g'.repeat(300 * 1024), { seq: 600 * 1024 + 64, rawLength: 300 * 1024 })
 
@@ -9516,13 +9320,11 @@ describe('connectPanePty', () => {
           for (const callback of parseCallbacks.splice(0)) {
             callback()
           }
-          // The post-replay fit is part of the transaction now; let its promise
-          // settle before asserting that overflow abandonment owns later bytes.
+          // The post-replay fit is part of the transaction now; let its promise settle before asserting.
           await flushAsyncTicks(20)
           expect(pane.terminal.scrollToLine).toHaveBeenLastCalledWith(142)
 
-          // Cut 2: drop sentinels and seq-gap chunks during the flood window
-          // must not re-arm restores — the post-gap bytes write through.
+          // Cut 2: drop sentinels and seq-gap chunks during the flood window must not re-arm restores — post-gap bytes write through.
           dataCallback('', { droppedOutput: true })
           dataCallback('AFTER-FLOOD', { seq: 700 * 1024, rawLength: 11 })
           await flushAsyncTicks(8)
@@ -9544,8 +9346,7 @@ describe('connectPanePty', () => {
       it('sends salvaged queries immediately from an overflowing restore queue', async () => {
         const { pane, transport, dataCallback } = await startInFlightRestore()
 
-        // Queue 400KB, then overflow with color, CPR, and DA probes. The
-        // discarded probes need direct replies before their read windows close.
+        // Queue 400KB, then overflow with color/CPR/DA probes — the discarded probes need direct replies before their read windows close.
         dataCallback('a'.repeat(400 * 1024), { seq: 400 * 1024, rawLength: 400 * 1024 })
         const queries = '\x1b]11;?\x1b\\\x1b[6n\x1b[c'
         dataCallback(`${'b'.repeat(200 * 1024)}${queries}`, {
@@ -9677,8 +9478,7 @@ describe('connectPanePty', () => {
           seq: 80
         })
 
-        // rawLength (6) !== data.length (4): renderer-side OSC stripping makes
-        // the slice offset unmappable — restore from a fresh snapshot instead.
+        // rawLength (6) !== data.length (4): OSC stripping makes the slice offset unmappable — restore from a fresh snapshot instead.
         dataCallback('ABCD', { seq: 67, rawLength: 6 })
         await flushAsyncTicks(20)
 
@@ -9696,9 +9496,7 @@ describe('connectPanePty', () => {
           seq: 120
         })
 
-        // Why: a chunk starting past the continuity point (start seq 87 >
-        // expected 64) means main trimmed bytes after the one-shot overflow
-        // marker was consumed — only the model snapshot can heal the gap.
+        // Why: a chunk starting past the continuity point means main trimmed bytes after the overflow marker — only the model snapshot can heal the gap.
         dataCallback('AFTER-GAP', { seq: 96, rawLength: 9 })
         await flushAsyncTicks(20)
 
@@ -9708,12 +9506,7 @@ describe('connectPanePty', () => {
       })
 
       it('writes genuinely-new live output whose seq sits below an empty-backlog baseline', async () => {
-        // E2E twin (terminal-hidden-tui-visual-restore "keeps newer live
-        // output correct"): main's snapshot seq is a cumulative PTY counter
-        // (shell init + prompt echo + hidden frame), while a synthetic live
-        // chunk meters only its own frames — far below the baseline. With an
-        // empty pending queue main can never re-deliver seqs at or below the
-        // snapshot, so the chunk must write, never silently drop.
+        // E2E twin: a live chunk's seq sits below main's cumulative baseline, but with an empty pending queue main can never re-deliver — so it must write, not drop.
         enableMainAuthority()
         const isVisibleRef = { current: true }
         const deps = createDeps({ isVisibleRef })
@@ -9736,8 +9529,7 @@ describe('connectPanePty', () => {
           reason: 'hidden-drop',
           markerSeq: 2_472
         })
-        // Reveal: the snapshot covers everything ingested; pending queue empty
-        // (pendingDeliveryStartSeq === seq).
+        // Reveal: the snapshot covers everything ingested; pending queue empty (pendingDeliveryStartSeq === seq).
         getMainBufferSnapshot.mockResolvedValue({
           data: 'LOW_RISK_RESTORE_FRAME_40\r\n',
           cols: 100,
@@ -9753,8 +9545,7 @@ describe('connectPanePty', () => {
         expect(writtenData(pane)).toContain('LOW_RISK_RESTORE_FRAME_40')
         pane.terminal.write.mockClear()
 
-        // Newer live frame injected with a seq domain unrelated to main's
-        // counter (e2e __terminalPtyDataInjection twin).
+        // Newer live frame injected with a seq domain unrelated to main's counter (e2e __terminalPtyDataInjection twin).
         dataCallback('LOW_RISK_RESTORE_FRAME_41\r\n', { seq: 315, rawLength: 27 })
         await flushAsyncTicks(8)
         expect(writtenData(pane)).toContain('LOW_RISK_RESTORE_FRAME_41')
@@ -9795,8 +9586,7 @@ describe('connectPanePty', () => {
         await flushAsyncTicks(8)
         expect(writtenData(pane)).toContain('PAST-BASELINE')
 
-        // Below the pending window (≤ 80): main can never re-send these seqs,
-        // so this is a foreign seq domain — written, never silently dropped.
+        // Below the pending window (≤ 80): main can never re-send these seqs, so this foreign seq domain is written, never dropped.
         dataCallback('BELOW-WINDOW', { seq: 60, rawLength: 12 })
         await flushAsyncTicks(8)
         expect(writtenData(pane)).toContain('BELOW-WINDOW')
@@ -10840,9 +10630,7 @@ describe('connectPanePty', () => {
       capturedDataCallback.current?.('n')
       await flushAsyncTicks(20)
 
-      // A live agent owns ?25l (parked cursor) and ?1004h (focus reporting);
-      // the ?1004l in the plain reset would silence focus events until the
-      // agent restarts, since agents only enable focus reporting at startup.
+      // A live agent owns ?1004h (focus reporting); the plain reset's ?1004l would silence focus events until restart, since agents only enable it at startup.
       expect(pane.terminal.write).toHaveBeenCalledWith(
         POST_REPLAY_LIVE_AGENT_SNAPSHOT_RESET,
         expect.any(Function)
@@ -10977,9 +10765,7 @@ describe('connectPanePty', () => {
       await flushAsyncTicks(6)
       getMainBufferSnapshot.mockClear()
 
-      // Main hit the per-PTY pending cap while the renderer was starved and
-      // sent the droppedOutput sentinel: the stream has a gap, so the pane
-      // must repaint from the authoritative main-owned buffer.
+      // Main hit the per-PTY pending cap and sent the droppedOutput sentinel: the stream has a gap, so repaint from the authoritative main-owned buffer.
       capturedDataCallback.current?.('', { droppedOutput: true })
       await flushAsyncTicks(20)
 
@@ -11278,8 +11064,7 @@ describe('connectPanePty', () => {
   })
 
   it('does not apply stale background Codex query chunks after hidden snapshot restore', async () => {
-    // Fire-all like a real event target: the pane resync handler and the
-    // stale-visibility trust handler both listen for visibilitychange.
+    // Fire-all like a real event target: both the pane resync and stale-visibility trust handlers listen for visibilitychange.
     const visibilityChangeListeners: (() => void)[] = []
     const visibilityChangeHandler = {
       current: (): void => {
@@ -11322,8 +11107,7 @@ describe('connectPanePty', () => {
     const currentFrame = '\r\x1b[2KWorking current'
     const staleSeq = hiddenFrame.length + staleQueryFrame.length
     const currentSeq = staleSeq + currentFrame.length
-    // The main emulator has already parsed every frame, so the snapshot covers
-    // the query frame that is still in flight on the pty:data channel.
+    // The main emulator already parsed every frame, so the snapshot covers the query frame still in flight on the pty:data channel.
     getMainBufferSnapshot.mockResolvedValue({
       data: currentFrame,
       cols: 80,
@@ -11355,8 +11139,7 @@ describe('connectPanePty', () => {
     visibilityChangeHandler.current?.()
     await flushAsyncTicks(20)
 
-    // The in-flight chunks arrive in channel order after the restore already
-    // rebuilt the buffer from the newer snapshot.
+    // The in-flight chunks arrive in channel order after the restore already rebuilt the buffer from the newer snapshot.
     vi.useFakeTimers()
     try {
       capturedDataCallback.current?.(staleQueryFrame, {
@@ -11411,8 +11194,7 @@ describe('connectPanePty', () => {
     const visibleFrame = '\r\x1b[2KWorking now'
     const hiddenSeq = hiddenFrame.length
     const visibleSeq = hiddenSeq + visibleFrame.length
-    // Why 3 extra bytes: the main emulator typically runs ahead of the chunks
-    // the renderer has received, so the snapshot seq exceeds the channel seq.
+    // Why 3 extra bytes: the main emulator runs ahead of the renderer's received chunks, so the snapshot seq exceeds the channel seq.
     const preExitSnapshotSeq = visibleSeq + 3
     getMainBufferSnapshot.mockResolvedValue({
       data: visibleFrame,
@@ -11450,9 +11232,7 @@ describe('connectPanePty', () => {
     expect(onPtyExit).toBeTypeOf('function')
     onPtyExit?.('pty-id')
 
-    // Revived session: same ptyId, main seq counter restarted. The first
-    // revived chunk lands below the pre-exit snapshot seq but above the last
-    // channel seq, so only the exit reset can stop it being judged covered.
+    // Revived session: same ptyId, seq restarted — the revived chunk sits below the pre-exit snapshot seq; only the exit reset stops it being judged covered.
     ;(deps.isVisibleRef as { current: boolean }).current = false
     const revivedHiddenFrame = '\r\x1b[2KWorking revived'
     capturedDataCallback.current?.(revivedHiddenFrame, {
@@ -11524,9 +11304,7 @@ describe('connectPanePty', () => {
     })
     await flushAsyncTicks(6)
 
-    // Main lost the pty silently (no exit reached the renderer) and the seq
-    // counter restarted: the channel seq regression must invalidate the old
-    // high-water mark instead of covering the new stream.
+    // Main lost the pty silently and the seq counter restarted; the channel seq regression must invalidate the old high-water mark, not cover the new stream.
     ;(deps.isVisibleRef as { current: boolean }).current = false
     const revivedHiddenFrame = '\r\x1b[2KWorking revived'
     capturedDataCallback.current?.(revivedHiddenFrame, {
@@ -11606,8 +11384,7 @@ describe('connectPanePty', () => {
     const capturedDataCallback: {
       current: ((data: string, meta?: { seq?: number; rawLength?: number }) => void) | null
     } = { current: null }
-    // Why: with the skip grammar gone, the model restore for remote-runtime
-    // PTYs is latched by background-queue overflow, not per-chunk scanning.
+    // Why: with the skip grammar gone, remote-runtime model restore is latched by background-queue overflow, not per-chunk scanning.
     const hidden = 'x'.repeat(2 * 1024 * 1024 + 1)
     const live = 'visible remote output\r\n'
     transport.serializeBuffer = vi.fn().mockResolvedValue({
@@ -11686,8 +11463,7 @@ describe('connectPanePty', () => {
       disposable = connectPanePty(pane as never, manager as never, deps as never)
       await flushAsyncTicks(6)
 
-      // Why: overflowing the background queue is what latches the model
-      // restore now — the per-chunk skip grammar is gone.
+      // Why: overflowing the background queue latches the model restore now — the per-chunk skip grammar is gone.
       const hidden = 'x'.repeat(2 * 1024 * 1024 + 1)
       const live = 'visible inactive output\r\n'
       expect(capturedDataCallback.current).not.toBeNull()
@@ -11701,8 +11477,7 @@ describe('connectPanePty', () => {
 
       expect(getMainBufferSnapshot).not.toHaveBeenCalled()
 
-      // Why: inactive split restore is frame-spaced, so this waits past one
-      // scheduler tick without depending on fake timers for xterm callbacks.
+      // Why: inactive split restore is frame-spaced, so wait past one scheduler tick without fake timers for xterm callbacks.
       await new Promise((resolve) => setTimeout(resolve, 30))
       await flushAsyncTicks(20)
 
@@ -11835,9 +11610,7 @@ describe('connectPanePty', () => {
     disposable.dispose()
   })
 
-  // Why: pins the entire switch-off hidden fallback chain — hidden bytes ride
-  // the background queue, the 2MB lossy cap drops the backlog and latches the
-  // restore, and reveal repaints from the model snapshot.
+  // Why: pins the switch-off hidden fallback chain — 2MB lossy cap drops the backlog, latches restore, and reveal repaints from the model snapshot.
   it('restores hidden backlog overflow from the main terminal snapshot on foreground output', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-id')
@@ -12699,8 +12472,7 @@ describe('connectPanePty', () => {
 
   it('keeps recovery pending when hidden output arrives during an in-flight snapshot', async () => {
     let visibilityState: DocumentVisibilityState = 'visible'
-    // Fire-all like a real event target: the pane resync handler and the
-    // stale-visibility trust handler both listen for visibilitychange.
+    // Fire-all like a real event target: both the pane resync and stale-visibility trust handlers listen for visibilitychange.
     const visibilityChangeListeners: (() => void)[] = []
     const visibilityChangeHandler = {
       current: (): void => {
@@ -12967,8 +12739,7 @@ describe('connectPanePty', () => {
     }
     await flushAsyncTicks()
 
-    // Why: replay completion must not overwrite scroll intent recorded while
-    // xterm was still parsing the restored snapshot.
+    // Why: replay completion must not overwrite scroll intent recorded while xterm was still parsing the restored snapshot.
     expect(pane.terminal.scrollToLine).not.toHaveBeenCalled()
     disposable.dispose()
   })
@@ -13370,8 +13141,7 @@ describe('connectPanePty', () => {
     })
     await flushAsyncTicks(20)
 
-    // Why: hidden restore replays bypass live foreground output; force a paint
-    // after xterm parses the snapshot so stale WebGL cells cannot survive.
+    // Why: hidden restore replays bypass live foreground output; force a paint after parse so stale WebGL cells can't survive.
     expect(refresh).toHaveBeenCalledWith(0, 39, true)
     expect(deps.replayingPanesRef.current.size).toBe(0)
     disposable.dispose()
@@ -13464,9 +13234,7 @@ describe('connectPanePty', () => {
     setReattachPaneTitle('renamed shell')
 
     const pane = createPane(1)
-    // Why: an inspectable buffer whose visible rows carry no Cursor Agent
-    // screen models a shell foreground after a dead run left its screen in
-    // scrollback.
+    // Why: a buffer whose visible rows carry no Cursor Agent screen models a shell foreground after a dead run left its screen in scrollback.
     Object.assign(pane.terminal.buffer.active, {
       cursorX: 2,
       getLine: () => undefined
@@ -13479,8 +13247,7 @@ describe('connectPanePty', () => {
       const connection = connectPanePty(pane as never, manager as never, deps as never)
       await flushAsyncTicks(6)
 
-      // A dead run's screen with the cursor left hidden — the live-agent reset
-      // preserves the ?25l, so the veto must re-show the cursor for the shell.
+      // A dead run left the cursor hidden; the live-agent reset preserves ?25l, so the veto must re-show the cursor for the shell.
       capturedReplayCallback.current?.(`${ANSI_POSITIONED_CURSOR_AGENT_REATTACH_SCREEN}\x1b[?25l`)
       await flushAsyncTicks(12)
 
@@ -13959,8 +13726,7 @@ describe('connectPanePty', () => {
       capturedDataCallback.current?.('\x1b[?1049h\x1b[2J\x1b[HVim package.json')
 
       expect(scheduleTerminalWebglAtlasRecovery).not.toHaveBeenCalled()
-      // Why: xterm switches to the alternate buffer while parsing the chunk;
-      // the write callback observes the post-parse buffer state.
+      // Why: xterm switches to the alternate buffer while parsing; the write callback observes the post-parse state.
       ;(pane.terminal.buffer.active as { type: 'normal' | 'alternate' }).type = 'alternate'
       parseCallback?.()
       expect(refresh).toHaveBeenCalledWith(0, 39, true)
@@ -13998,9 +13764,7 @@ describe('connectPanePty', () => {
       connectPanePty(pane as never, createManager(1) as never, createDeps() as never)
       await flushAsyncTicks(6)
 
-      // Why: PTY reads split CSI sequences at arbitrary byte boundaries (real
-      // vim sessions split cursor moves at 1024-byte chunk edges), so the
-      // enter sequence itself can straddle two onData chunks.
+      // Why: PTY reads split CSI sequences at arbitrary byte boundaries, so the enter sequence can straddle two onData chunks.
       capturedDataCallback.current?.('\x1b[?104')
       parseCallback?.()
       expect(scheduleTerminalWebglAtlasRecovery).not.toHaveBeenCalled()
@@ -14043,9 +13807,7 @@ describe('connectPanePty', () => {
       connectPanePty(pane as never, createManager(1) as never, createDeps() as never)
       await flushAsyncTicks(6)
 
-      // Vim's final frame erases the status line and restores the normal
-      // buffer in one chunk; the atlas must still rebuild for the restored
-      // prompt even though the post-parse buffer is back to normal.
+      // Vim's final frame restores the normal buffer in one chunk; the atlas must still rebuild even though the post-parse buffer reads normal.
       capturedDataCallback.current?.('\x1b[34;1H\x1b[K\x1b[34;1H\x1b[?1049l\x1b[?25h')
       ;(pane.terminal.buffer.active as { type: 'normal' | 'alternate' }).type = 'normal'
       parseCallback?.()
@@ -14092,9 +13854,7 @@ describe('connectPanePty', () => {
       connectPanePty(pane as never, createManager(1) as never, createDeps() as never)
       await flushAsyncTicks(6)
 
-      // A coalesced backlog flush can parse a whole enter -> draw -> exit TUI
-      // interaction in one write, netting buffer type back to 'normal'; the
-      // buffer-switch count is what still marks it as alternate-screen work.
+      // A coalesced flush can parse enter -> draw -> exit in one write (buffer nets back to 'normal'); the switch count still marks it alternate-screen work.
       capturedDataCallback.current?.('\x1b[?1049h\x1b[2J\x1b[Hpager frame\x1b[K\x1b[?1049l')
       bufferChangeListener?.()
       bufferChangeListener?.()
@@ -14134,8 +13894,7 @@ describe('connectPanePty', () => {
       connectPanePty(pane as never, createManager(1) as never, createDeps() as never)
       await flushAsyncTicks(6)
 
-      // Captured from a real `vim package.json` session: a 1024-byte PTY read
-      // boundary cuts the cursor move \x1b[30;5H into "\x1b[30" + ";5H".
+      // Captured from a real vim session: a 1024-byte PTY read boundary cuts the cursor move \x1b[30;5H into "\x1b[30" + ";5H".
       capturedDataCallback.current?.('"rules": {\x1b[29;15H\x1b[K\x1b[30')
       parseCallback?.()
       expect(scheduleTerminalWebglAtlasRecovery).toHaveBeenCalledTimes(1)
@@ -14452,8 +14211,7 @@ describe('connectPanePty', () => {
         }
       )
       transportFactoryQueue.push(transport)
-      // Why: the missing-glyph workaround is renderer-scoped, not PTY-scoped.
-      // SSH changes where bytes originate, but Windows still paints them locally.
+      // Why: missing-glyph workaround is renderer-scoped, not PTY-scoped — SSH moves byte origin but Windows still paints locally.
       mockStoreState = {
         ...mockStoreState,
         repos: [{ id: 'repo1', connectionId: 'conn-1', displayName: 'orca' }]
@@ -14518,13 +14276,7 @@ describe('connectPanePty', () => {
   })
 
   it('schedules a follow-up repaint for Claude-style in-place prompt redraws on native Windows', async () => {
-    // Why: issue #5656/#5653 — Claude Code echoes prompt keystrokes by redrawing
-    // the input line in place (CR + CHA + reprint + erase-line) without DEC 2026.
-    // On native Windows ConPTY the xterm buffer is correct but the DOM renderer
-    // paints one frame late, leaving phantom/overwritten characters until a resize.
-    // The connection layer now requests a follow-up next-frame repaint; with the
-    // synchronous rAF stub that surfaces as a SECOND _core.refresh call. Without the
-    // fix only the single synchronous settle refresh runs.
+    // Why: issue #5656/#5653 — native Windows ConPTY paints Claude's in-place prompt redraw one frame late; needs a follow-up next-frame repaint.
     const restoreNavigator = temporarilySetNavigatorUserAgent(
       'Mozilla/5.0 (Windows NT 10.0; Win64; x64)'
     )
@@ -14592,8 +14344,7 @@ describe('connectPanePty', () => {
       connectPanePty(pane as never, createManager(1) as never, createDeps() as never)
       await flushAsyncTicks(6)
 
-      // The CR redraw still forces one synchronous refresh (cross-platform rewrite
-      // handling), but no native-Windows follow-up next-frame repaint is scheduled.
+      // CR redraw still forces one synchronous refresh, but no native-Windows follow-up repaint is scheduled.
       capturedDataCallback.current?.('\r\x1b[3Gzzzx\x1b[K')
 
       expect(refresh).toHaveBeenCalledTimes(1)
@@ -14643,11 +14394,7 @@ describe('connectPanePty', () => {
   })
 
   it('drains a post-submit synchronized frame on the fast path when its end marker arrives late', async () => {
-    // Why (STA-1041): OpenCode wraps each submit repaint in a DEC 2026 frame.
-    // Under CPU contention ConPTY splits the closing chunk past the 150ms redraw
-    // window, so classifying only by the end chunk's own arrival time would judge
-    // it non-latency-sensitive and stall the repaint behind the 1s coalesce
-    // fallback. The frame opened right after Enter, so it must drain in ~16ms.
+    // Why (STA-1041): a submit-opened DEC 2026 frame must drain fast (~16ms) by open time, even when ConPTY splits its close past the 150ms window.
     const restoreNavigator = temporarilySetNavigatorUserAgent(
       'Mozilla/5.0 (Windows NT 10.0; Win64; x64)'
     )
@@ -14693,10 +14440,7 @@ describe('connectPanePty', () => {
   })
 
   it('keeps coalescing a synchronized frame end with no recent input behind the 1s fallback', async () => {
-    // Why (STA-1041): the fast-path relaxation only applies when the frame opened
-    // right after a keystroke. A background synchronized redraw (no recent input)
-    // whose cursor restore is genuinely split must still wait the full coalesce
-    // fallback so Windows never rasterizes the transient cursor position.
+    // Why (STA-1041): fast path is keystroke-only; a background split redraw waits the full fallback so Windows never rasterizes the transient cursor.
     const restoreNavigator = temporarilySetNavigatorUserAgent(
       'Mozilla/5.0 (Windows NT 10.0; Win64; x64)'
     )
@@ -14720,8 +14464,7 @@ describe('connectPanePty', () => {
       // No terminal input: this synchronized redraw is not submit-driven.
       const repaintBody = 'opencode repaint '.repeat(200)
       capturedDataCallback.current?.(`\x1b[?2026h${repaintBody}`)
-      // Let the non-latency-sensitive frame body drain via its hold-safety
-      // fallback (250ms) before isolating the closing chunk.
+      // Let the frame body drain via its 250ms hold-safety fallback before isolating the closing chunk.
       vi.advanceTimersByTime(300)
       pane.terminal.write.mockClear()
 
@@ -14742,8 +14485,7 @@ describe('connectPanePty', () => {
   })
 
   it('does not leak the interactive latch across a same-chunk close+open to a stale frame', async () => {
-    // Why: a same-chunk close+open must re-evaluate the new frame from its own
-    // open time so a stale frame can't inherit the prior frame's fast path.
+    // Why: a same-chunk close+open re-evaluates the new frame from its own open time so it can't inherit the prior frame's fast path.
     const restoreNavigator = temporarilySetNavigatorUserAgent(
       'Mozilla/5.0 (Windows NT 10.0; Win64; x64)'
     )
@@ -14764,24 +14506,16 @@ describe('connectPanePty', () => {
       await flushAsyncTicks(6)
 
       vi.useFakeTimers()
-      // Load-bearing setup: Enter submits and opens an INTERACTIVE frame so the
-      // latch (synchronizedForegroundFrameInteractive) genuinely becomes true. The
-      // frame stays OPEN (active) — no end marker yet — which is the precondition
-      // for the leak: the buggy set-branch is gated on !active.
+      // Load-bearing: Enter opens an INTERACTIVE frame that stays OPEN — the leak precondition, since the buggy set-branch is gated on !active.
       sendTerminalInputThroughPane(pane, '\r')
       const repaintBody = 'opencode repaint '.repeat(200)
       expect(repaintBody.length).toBeGreaterThan(2048)
       capturedDataCallback.current?.(`\x1b[?2026h${repaintBody}`)
-      // Move well past the 400ms interactive window WITHOUT closing the frame, so
-      // any NEW frame opening now must be classified non-interactive.
+      // Move past the 400ms interactive window without closing the frame, so any new frame now classifies non-interactive.
       vi.advanceTimersByTime(500)
       pane.terminal.write.mockClear()
 
-      // A single chunk closes the still-active prior frame AND opens a new one.
-      // The new frame opened ~500ms after the keystroke. Pre-hardening, the prior
-      // frame's active flag skips the set-branch and the end marker skips the
-      // reset-branch, so the new frame leaks interactive=true; the recompute must
-      // judge it from its own open time and yield false.
+      // One chunk closes the prior frame and opens a new one ~500ms post-keystroke; the recompute must judge the new frame non-interactive from its own open time.
       capturedDataCallback.current?.(`\x1b[?2026l\x1b[?2026h${repaintBody}`)
       vi.advanceTimersByTime(40)
       pane.terminal.write.mockClear()
@@ -14805,8 +14539,7 @@ describe('connectPanePty', () => {
   })
 
   it('coalesces a second synchronized frame that opens after the window with no keystroke', async () => {
-    // Why: the second frame opens after the interactive window, so its START must
-    // be judged independently and stay on the 1s fallback path.
+    // Why: the second frame opens after the interactive window, so its start is judged independently and stays on the 1s fallback.
     const restoreNavigator = temporarilySetNavigatorUserAgent(
       'Mozilla/5.0 (Windows NT 10.0; Win64; x64)'
     )
@@ -15323,12 +15056,7 @@ describe('connectPanePty', () => {
     expect(remountDeps.syncPanePtyLayoutBinding).toHaveBeenCalledWith(1, 'pty-restarted')
   })
 
-  // Why: BEL (0x07) is the attention signal. connectPanePty wires an
-  // onBell handler that raises the worktree unread dot, the tab-level
-  // indicator, the pane marker, and an OS notification. The unread flags
-  // clear when the user actually interacts with the pane — keystroke via
-  // xterm onData or pointerdown on the container (see TerminalPane.tsx). This test
-  // locks in the mark wiring; separate tests below cover the clear path.
+  // Why: BEL (0x07) is the attention signal — onBell raises worktree/tab/pane unread + an OS notification.
   it('wires onBell to raise worktree unread, tab unread, and OS notification', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport()
@@ -15388,11 +15116,7 @@ describe('connectPanePty', () => {
     expect(deps.markTerminalPaneUnread).not.toHaveBeenCalled()
   })
 
-  // ─── Main side-effect authority (terminal-side-effect-authority.md) ────
-  //
-  // With the kill switch on (the default), local/SSH transports must not
-  // register title/bell/agent byte parsers; the pane's policy callbacks are
-  // registered as the PTY's single pty:sideEffect fact consumer instead.
+  // Kill switch on (default): no byte parsers; pane policy is the PTY's single fact consumer (terminal-side-effect-authority.md).
   describe('with main side-effect authority on', () => {
     const SIDE_EFFECT_PARSER_CALLBACKS = [
       'onTitleChange',
@@ -15421,8 +15145,7 @@ describe('connectPanePty', () => {
       for (const callback of SIDE_EFFECT_PARSER_CALLBACKS) {
         expect(createdTransportOptions[0]?.[callback]).toBeUndefined()
       }
-      // The lifecycle callbacks stay on the transport — only side-effect
-      // parsing moves to the fact consumer.
+      // Lifecycle callbacks stay on the transport; only side-effect parsing moves to the fact consumer.
       expect(createdTransportOptions[0]?.onPtySpawn).toBeTypeOf('function')
       expect(createdTransportOptions[0]?.onPtyExit).toBeTypeOf('function')
     })
@@ -15711,8 +15434,7 @@ describe('connectPanePty', () => {
         agentType: 'command-code'
       })
 
-      // Why: the done fact is a hint — the settle timer stays in the pane
-      // policy because it must consult the live status row before completing.
+      // Why: done is a hint — the settle timer stays in pane policy so it can consult the live status row before completing.
       handler._dispatchTerminalSideEffectBatchForTest({
         ptyId: 'pty-fact-cc',
         seq: 2,
@@ -15795,9 +15517,7 @@ describe('connectPanePty', () => {
     })
 
     it('honors the persisted kill switch for panes bound before settings hydrate', async () => {
-      // Pre-hydration: the store has no settings yet, but the user persisted
-      // the kill switch off. The pane must register byte parsers, not a fact
-      // consumer — and hydration must not produce a second consumer.
+      // Pre-hydration: settings not loaded but kill switch persisted off — pane registers byte parsers, not a fact consumer.
       mockStoreState.settings = null
       ;(window.api as unknown as Record<string, unknown>).settings = {
         getSync: vi.fn(() => ({ terminalMainSideEffectAuthority: false }))
@@ -15824,8 +15544,7 @@ describe('connectPanePty', () => {
       })
       expect(deps.markWorktreeUnread).not.toHaveBeenCalled()
 
-      // Hydration lands with the switch still off: byte parsing stays the
-      // single consumer — one BEL marks unread exactly once.
+      // Hydration with switch still off: byte parsing stays the single consumer — one BEL marks unread once.
       mockStoreState.settings = { terminalMainSideEffectAuthority: false }
       notifyStoreSubscribers()
       const onBell = createdTransportOptions[0]?.onBell as () => void
@@ -17068,9 +16787,7 @@ describe('connectPanePty', () => {
     })
   })
 
-  // Why: show-until-interact — a DOM keydown is the keyboard "user is here"
-  // signal that dismisses attention. Raw xterm onData is intentionally lower
-  // level because it can include terminal-generated replies/control bytes.
+  // Why: a DOM keydown signals "user is here"; raw xterm onData is lower-level (can include terminal replies/control bytes).
   it('clears tab and worktree unread on real keydown', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport()
@@ -17098,9 +16815,7 @@ describe('connectPanePty', () => {
   })
 
   it('clears tab, pane, and worktree unread on plain Escape keydown', async () => {
-    // Why: plain Escape produces real terminal input (\x1b) and so is a genuine
-    // "user is here" signal. The interrupt-intent early return must not skip the
-    // unread clears, or the attention dot would linger after the user presses Escape.
+    // Why: plain Escape is real input (\x1b) — a genuine "user is here" signal; the interrupt-intent early return must not skip the unread clears.
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport()
     transportFactoryQueue.push(transport)
@@ -17155,9 +16870,7 @@ describe('connectPanePty', () => {
     expect(transport.sendInput).toHaveBeenCalledWith('a')
   })
 
-  // Why: xterm auto-replies during replay must not masquerade as user
-  // interaction. If they did, a pane that BELed during its scrollback
-  // replay would instantly self-dismiss without the user ever seeing it.
+  // Why: xterm auto-replies during replay must not count as user interaction, or a BELed pane would self-dismiss unseen.
   it('does not clear unread when onData fires during replay', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport()
@@ -17184,18 +16897,12 @@ describe('connectPanePty', () => {
     expect(deps.clearWorktreeUnread).not.toHaveBeenCalled()
   })
 
-  // Why: symmetric to the replay guard — if the pane is stale-codex (pending
-  // account-switch restart), xterm onData bytes are either blocked synthetic
-  // input or keystrokes that would execute under the wrong account. Either
-  // way they must not count as user interaction and dismiss the bell. The
-  // production code also blocks the transport.sendInput call in this branch
-  // (see pty-connection.ts lines 275-277), so we assert that too.
+  // Why: on a stale-codex pane (pending account-switch restart), onData bytes must not count as user interaction; production also blocks sendInput here.
   it('does not clear unread when onData fires on a stale codex pane', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport('pty-codex-stale')
     transportFactoryQueue.push(transport)
-    // isCodexPaneStale reads codexRestartNoticeByPtyId from the store, so
-    // trigger the stale branch by seeding a restart notice for the pane's PTY.
+    // isCodexPaneStale reads codexRestartNoticeByPtyId; seed a restart notice to trigger the stale branch.
     mockStoreState = {
       ...mockStoreState,
       tabsByWorktree: {
@@ -17287,9 +16994,7 @@ describe('connectPanePty', () => {
     expect(mockStoreState.removeDeferredSshSessionId).toHaveBeenCalledWith('tab-1')
     expect(deps.syncPanePtyLayoutBinding).toHaveBeenCalledWith(1, 'leaf-session')
     expect(deps.updateTabPtyId).toHaveBeenCalledWith('tab-1', 'leaf-session')
-    // Why: the relay's replay buffer holds the full terminal history, so the
-    // client clears xterm before writing to prevent duplication with any
-    // content already in the terminal from a prior session.
+    // Why: the relay's replay buffer holds full history, so clear xterm before writing to avoid duplicating prior-session content.
     expect(writes).toContain('\x1b[2J\x1b[3J\x1b[H')
     expect(writes).toContain('restored-ssh-output')
     expect(writes).toContain(POST_REPLAY_REATTACH_RESET)
@@ -17424,19 +17129,7 @@ describe('connectPanePty', () => {
     expect(transport.connect).toHaveBeenCalledTimes(1)
   })
 
-  // Why: the working→idle transition fires an 'agent-task-complete' OS
-  // notification (user-toggleable in Settings) and raises the same visual
-  // attention marker as BEL so agents that don't emit BEL still leave a
-  // findable terminal highlight. Double-firing with a concurrent BEL is
-  // idempotent in the unread stores and collapsed by the per-worktree dedupe
-  // in main/ipc/notifications.ts.
-  //
-  // This test deliberately wires the real useNotificationDispatch hook into
-  // connectPanePty instead of a vi.fn() stub. A stub would let the producer
-  // be silently deleted and the test still pass by asserting "not called";
-  // routing through the real hook to window.api.notifications.dispatch means
-  // removing the producer breaks the IPC assertion, which is the user-facing
-  // contract.
+  // Why: wires the REAL useNotificationDispatch (not a stub) so deleting the producer breaks the IPC assertion — the user-facing contract.
   it('dispatches agent-task-complete on working→idle and raises tab/worktree unread', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const { useNotificationDispatch } = await vi.importActual<typeof UseNotificationDispatchModule>(
@@ -17445,13 +17138,7 @@ describe('connectPanePty', () => {
     const transport = createMockTransport()
     transportFactoryQueue.push(transport)
 
-    // Why: useNotificationDispatch uses useCallback internally; bypass the
-    // React machinery by invoking its body directly through a module call.
-    // Safe here because useCallback is pure memoization — the returned
-    // function has the same behavior as the callback passed in.
-    // Depends on the file-level vi.mock('react', ...) near the top of this
-    // file that replaces useCallback with a pass-through. Removing that
-    // mock breaks this test with a rules-of-hooks error.
+    // Why: invoke useNotificationDispatch's body directly (useCallback is pure memo); relies on the file-level vi.mock('react') useCallback pass-through.
     const realDispatchNotification = useNotificationDispatch('wt-1')
     const dispatchNotification = vi.fn((event) => realDispatchNotification(event))
     const paneKey = makePaneKey('tab-1', LEAF_1)
@@ -17460,10 +17147,7 @@ describe('connectPanePty', () => {
       prompt: 'Fix notification payloads',
       updatedAt: Date.now(),
       stateStartedAt: Date.now(),
-      // Why: the live completion title is '* Claude done' (explicit Claude), so
-      // the stored snapshot must name the same agent to be reused for the rich
-      // notification. A mismatched (e.g. codex) snapshot is treated as stale
-      // pane-reuse residue and dropped — see use-notification-dispatch.test.ts.
+      // Why: snapshot agent must match the live completion title ('* Claude done') to be reused; a mismatch is dropped as stale — see use-notification-dispatch.test.ts.
       agentType: 'claude',
       paneKey,
       terminalTitle: '* Claude done',
@@ -18059,17 +17743,11 @@ describe('connectPanePty', () => {
     const transport = createMockTransport('pty-replaced-codex')
     transportFactoryQueue.push(transport)
     vi.useFakeTimers()
-    // Why: the process-cadence poll interval carries ±10% Math.random jitter, so
-    // pin it to nominal cadence — otherwise the second null-foreground sample can
-    // land in the first advance window, confirming exit before the replacement
-    // hook owner is set and racing the very veto this test asserts.
+    // Why: pin the ±10% poll jitter to nominal so the 2nd null sample can't confirm exit before the replacement owner is set.
     const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0.5)
     try {
       const getForegroundProcess = vi.mocked(window.api.pty.getForegroundProcess)
-      // Why: call-count alone is flaky — one advanceTimersToNextTimerAsync can start
-      // multiple getForegroundProcess reads (completion cadence + pane tracker /
-      // confirmForegroundProcess alias). Gate the 2nd+ null sample until the
-      // replacement hook owner is installed so the confirming sample always sees it.
+      // Why: one timer advance can start multiple reads; gate the 2nd+ null sample until the replacement hook owner is installed.
       let idleMode = false
       let nullSamplesStarted = 0
       let releaseConfirmingNullSample: (() => void) | undefined
@@ -18112,8 +17790,7 @@ describe('connectPanePty', () => {
         }
         await vi.advanceTimersToNextTimerAsync()
       }
-      // Why: let the first null sample apply pendingProcessExitAgent before the
-      // replacement owner is installed; later samples stay gated until then.
+      // Why: let the first null sample apply pendingProcessExitAgent before the replacement owner is installed.
       await flushAsyncTicks()
 
       mockStoreState.agentStatusByPaneKey[paneKey] = {
@@ -18138,8 +17815,7 @@ describe('connectPanePty', () => {
         expect.any(Function)
       )
     } finally {
-      // Why: any assertion failure above must not pin Math.random for later tests
-      // in this large suite.
+      // Why: an assertion failure above must not leave Math.random pinned for later tests.
       randomSpy.mockRestore()
     }
   })
@@ -18910,8 +18586,7 @@ describe('connectPanePty', () => {
     expect('agentInterrupted' in dispatchArgs).toBe(false)
   })
 
-  // Why: title reversion clears cache UI, but agent-row removal belongs to
-  // process/PTY lifecycle so interrupts cannot disappear the activity row.
+  // Why: agent-row removal belongs to process/PTY lifecycle, not title reversion, so interrupts can't disappear the activity row.
   it('clears the cache timer without removing agent status when the title tracker sees exit', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport()
@@ -18954,8 +18629,7 @@ describe('connectPanePty', () => {
       })
 
       const binding = connectPanePty(createPane(2) as never, manager as never, deps as never)
-      // Why: clear the freshly-split early-return guard so onExit reaches the
-      // close branch, matching an established split pane the user has used.
+      // Why: clear the freshly-split early-return guard so onExit reaches the close branch (established, used split pane).
       capturedDataCallback.current?.('shell prompt')
 
       binding.reconcileIfSessionDead(new Set(['pty-pane-1']))
@@ -19041,9 +18715,7 @@ describe('connectPanePty', () => {
     })
 
     it('does NOT tear down a newborn pane when the snapshot was requested before it bound', async () => {
-      // Why (regression): a snapshot requested before the spawn bound cannot
-      // prove the fresh ptyId dead. Drives the REAL reconcile body to prove the
-      // boundAt wiring, not just forwarding.
+      // Why (regression): a snapshot requested before the spawn bound cannot prove the fresh ptyId dead (boundAt wiring).
       const { connectPanePty } = await import('./pty-connection')
       const capturedDataCallback: { current: ((data: string) => void) | null } = { current: null }
       const transport = createMockTransport('pty-pane-2')
@@ -19061,8 +18733,7 @@ describe('connectPanePty', () => {
       })
 
       const binding = connectPanePty(createPane(2) as never, manager as never, deps as never)
-      // Why: clear the freshly-split early-return guard so the ONLY remaining
-      // protection is the freshness guard this test exercises.
+      // Why: clear the freshly-split early-return guard so the only remaining protection is the freshness guard under test.
       capturedDataCallback.current?.('shell prompt')
       const onPtySpawn = createdTransportOptions[0]?.onPtySpawn as
         | ((ptyId: string) => void)
@@ -19208,10 +18879,7 @@ describe('connectPanePty', () => {
     })
 
     it('still closes the replacement PTY after a suppressed restart rebinds the pane', async () => {
-      // Why (regression): the exit guard is scoped to the exiting ptyId, not a
-      // bare one-shot boolean. An intentional suppressed restart keeps the pane
-      // mounted and rebinds to a NEW ptyId; that replacement's later real exit
-      // must still tear the pane down. A boolean guard would strand it.
+      // Why (regression): the exit guard is scoped to the exiting ptyId, not a one-shot boolean, so a rebound replacement's later real exit still tears down.
       const { connectPanePty } = await import('./pty-connection')
       const capturedDataCallback: { current: ((data: string) => void) | null } = { current: null }
       const transport = createMockTransport('pty-pane-2')
@@ -19244,8 +18912,7 @@ describe('connectPanePty', () => {
       onPtyExit?.('pty-pane-2')
       expect(manager.closePane).not.toHaveBeenCalled()
 
-      // The restart rebinds the pane to a new live PTY; its later real exit
-      // must NOT be ignored by a stale guard.
+      // Restart rebinds the pane to a new live PTY; its later real exit must not be ignored by a stale guard.
       transport.getPtyId.mockReturnValue('pty-pane-2-restarted')
       onPtyExit?.('pty-pane-2-restarted')
 
@@ -19265,8 +18932,7 @@ describe('connectPanePty', () => {
 
       const binding = connectPanePty(createPane(2) as never, manager as never, deps as never)
 
-      // Reattach to a new live session between snapshot and apply: the snapshot
-      // marked the OLD id dead, but getPtyId now returns the new (live) id.
+      // Reattach between snapshot and apply: snapshot marked the OLD id dead, but getPtyId now returns the new live id.
       transport.getPtyId.mockReturnValue('pty-pane-2-reattached')
       binding.reconcileIfSessionDead(new Set(['pty-pane-1', 'pty-pane-2-reattached']))
 
@@ -19345,10 +19011,7 @@ describe('connectPanePty', () => {
     const WRAPPER_RESOLVE_RETRY_MS = 1200
     const SECOND_WRAPPER_RETRY_MS = 6000
 
-    // Why: every connectPanePty binding in this file shares the tab-1/LEAF_1 pane
-    // key, and an undisposed reattach binding elsewhere can resolve a foreground
-    // read into this test's store slice. Give each sampling case its own tabId so
-    // no other test's publish can pollute the pane identity it asserts on.
+    // Why: bindings share the tab-1/LEAF_1 pane key; give each sampling case its own tabId so no other test's publish pollutes it.
     async function connectRestoredPaneForForegroundSampling(
       args: {
         ptyId?: string
@@ -19511,8 +19174,7 @@ describe('connectPanePty', () => {
         binding.sampleForegroundAgentOnFocus()
         await vi.advanceTimersByTimeAsync(10_000)
 
-        // Scope to this pane's pty id: a delayed confirm for another test's
-        // default `tab-pty` pane can fire during this advance and is not our subject.
+        // Scope to this pane's pty id: a delayed confirm for another test's pane can fire during this advance.
         expect(window.api.pty.confirmForegroundProcess).not.toHaveBeenCalledWith(ptyId)
       } finally {
         restoreUserAgent()
@@ -19639,9 +19301,7 @@ describe('connectPanePty', () => {
       )
       await flushAsyncTicks()
 
-      // The bounded ladder runs at least its initial read plus two retries; an
-      // incidental droid reconfirm can add one more, so assert the floor, not an
-      // exact count (matches the warm-reattach-to-shell sibling test above).
+      // Assert the floor (initial read + two retries), not an exact count: an incidental droid reconfirm can add one more.
       expect(
         vi.mocked(window.api.pty.confirmForegroundProcess).mock.calls.length
       ).toBeGreaterThanOrEqual(3)
@@ -19831,9 +19491,7 @@ describe('connectPanePty', () => {
     })
 
     it('fails closed when a leaked 133;D cancels identityless recovery', async () => {
-      // Why: a cached visible read has no routing authority. If a command
-      // boundary races it without an agent hint, cancel the sample and trust
-      // the shell marker instead of promoting stale process identity.
+      // Why: a cached visible read has no routing authority; on a racing command boundary, trust the shell marker over stale identity.
       vi.useFakeTimers()
       const { connectPanePty } = await import('./pty-connection')
       const getForegroundProcess = vi.mocked(window.api.pty.getForegroundProcess)
@@ -19920,9 +19578,7 @@ describe('connectPanePty', () => {
     })
 
     it('never probes the foreground for a visible remote/SSH restored pane', async () => {
-      // Why: foreground reads are local-only (expensive RPCs, replayed OSC
-      // streams). isTrackablePtyId must keep remote/SSH panes off the recovery
-      // probe entirely, so the fix stays local-only.
+      // Why: foreground reads are local-only (expensive RPCs); keep remote/SSH panes off the recovery probe.
       vi.useFakeTimers()
       const getForegroundProcess = vi.mocked(window.api.pty.getForegroundProcess)
       getForegroundProcess.mockResolvedValue('codex')
@@ -19936,9 +19592,7 @@ describe('connectPanePty', () => {
   })
 
   describe('terminal input liveness IPC gating (perf)', () => {
-    // Why (perf regression guard): listSessions() is a renderer→main→daemon
-    // round-trip over every live session. Terminal input must never start that
-    // enumeration; visibility reconcile and daemon exit events own liveness.
+    // Why (perf regression guard): listSessions() is a renderer→main→daemon round-trip; terminal input must never trigger it.
     async function connectActivePaneWithInput(): Promise<{
       binding: { noteVisibilityResume: () => void }
       transport: MockTransport
@@ -20026,13 +19680,7 @@ describe('connectPanePty', () => {
   })
 
   describe('PTY size re-assert on visibility resume', () => {
-    // Why: a resize dropped while the pane was hidden (suppression window,
-    // mobile-driver gate, provider no-op) leaves xterm and the PTY silently
-    // diverged. The renderer dedupes on what it *thinks* it sent, so a later
-    // same-cols layout never re-forwards — "resizing sometimes doesn't fix it".
-    // On resume the binding reads the PTY's ACTUAL size and re-asserts only on
-    // real drift. The visibility-resume path owns the post-WebGL fit, so this
-    // check verifies the current grid without fitting first.
+    // Why: a resize dropped while hidden leaves xterm and the PTY diverged, and dedupe hides it; resume re-asserts on real drift.
     async function connectResumablePane(depsOverrides: Record<string, unknown> = {}): Promise<{
       binding: { noteVisibilityResume: () => void }
       transport: MockTransport
@@ -20503,8 +20151,7 @@ describe('connectPanePty', () => {
           value: () => []
         })
         const release = holdPtyResizesForPaneSubtrees([pane.container])
-        // Prove this fixture is using the same held pane element before the
-        // production reassertion overwrites the queued placeholder size.
+        // Prove the fixture uses the same held pane before reassertion overwrites the queued placeholder size.
         expect(queuePanePtyResizeIfHeld(pane.container, 1, 1)).toBe(true)
         transport.resize.mockClear()
 
@@ -20564,9 +20211,7 @@ describe('connectPanePty', () => {
     })
 
     it('does NOT forward when the pane is hidden again before getSize resolves (stale hop)', async () => {
-      // The load-bearing safety property: a getSize promise resolving AFTER the
-      // pane was re-hidden must not emit a hidden-tab SIGWINCH (which can reset
-      // alt-screen TUIs). Suppression is the send-time visibility re-check.
+      // Stale getSize resolving after re-hide must not emit a hidden-tab SIGWINCH (which resets alt-screen TUIs).
       let resolveSize: (v: { cols: number; rows: number } | null) => void = () => {}
       vi.mocked(window.api.pty.getSize).mockImplementation(
         () =>
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.ts b/src/renderer/src/components/terminal-pane/pty-connection.ts
index 8e4ce78c00c..33f871f206b 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.ts
@@ -5413,9 +5413,7 @@ export function connectPanePty(
       clearHiddenOutputRestoreFloodRepaintTimer()
     }
 
-    // Extends the suppression window and (re)schedules the single deferred
-    // repaint for when the flood goes quiet. Every backpressure signal resets
-    // the timer, so it fires exactly once, SUPPRESS_MS after the last signal.
+    // Extends the suppression window; every backpressure signal resets the timer so the deferred repaint fires once, SUPPRESS_MS after the last signal.
     function noteHiddenOutputRestoreFloodBackpressure(): void {
       hiddenOutputRestoreFloodSuppressedUntil = Date.now() + HIDDEN_OUTPUT_RESTORE_FLOOD_SUPPRESS_MS
       const ptyId = transport.getPtyId()
@@ -5428,15 +5426,12 @@ export function connectPanePty(
         if (disposed || transport.getPtyId() !== ptyId) {
           return
         }
-        // Why one repaint: bytes were dropped during the flood, so the screen
-        // has a gap the live stream cannot heal. Now that the flood is quiet,
-        // a single snapshot restore repaints from main's authoritative buffer.
+        // Why one repaint: flood-dropped bytes leave a gap the live stream can't heal; once quiet, one snapshot restore repaints from main's authoritative buffer.
         markHiddenOutputRestoreNeeded()
       }, HIDDEN_OUTPUT_RESTORE_FLOOD_SUPPRESS_MS)
     }
 
-    // Why: main reports dropped renderer-bound bytes (hidden gate / pending
-    // cap) out-of-band — routed per PTY by pty-model-restore-channel.ts.
+    // Why: main reports dropped renderer-bound bytes out-of-band, routed per PTY by pty-model-restore-channel.ts.
     function handleModelRestoreNeededMarker(): void {
       if (disposed) {
         return
@@ -5444,22 +5439,14 @@ export function connectPanePty(
       recordTerminalFreezeBreadcrumb('restore-marker', {
         id: redactPtyIdForDiagnostics(transport.getPtyId() ?? '')
       })
-      // Why: dropped bytes invalidate every cross-chunk carry — a partial
-      // OSC-9999 prefix spanning the gap would corrupt the next live chunk.
+      // Why: dropped bytes invalidate cross-chunk carry — a partial OSC-9999 prefix spanning the gap would corrupt the next live chunk.
       transport.resetCrossChunkParserState?.()
-      // Why gated (rc.7.perf loop): on a visible pane these markers are the
-      // product of our own restore starving ACKs. Re-arming per marker kept
-      // the snapshot-fetch loop alive for the whole flood; defer to one
-      // post-flood repaint instead and let live bytes flow.
+      // Why gated (rc.7.perf loop): on a visible pane these markers come from our own restore starving ACKs; re-arming per marker kept the fetch loop alive all flood, so defer to one post-flood repaint.
       if (isForegroundRestoreBackpressureContext()) {
         noteHiddenOutputRestoreFloodBackpressure()
         return
       }
-      // Why: parity with the hidden skip path — a marker landing while a
-      // restore is in flight means the in-flight snapshot may predate the
-      // drop, so a fresh snapshot must follow. Captured BEFORE the mark: on a
-      // visible pane the mark starts a restore synchronously, which must not
-      // count as "already in flight".
+      // Why: a marker during an in-flight restore means that snapshot may predate the drop, so a fresh one must follow; capture BEFORE the mark, which starts a restore synchronously on a visible pane.
       const restoreWasInFlight = hiddenOutputRestoreInFlight !== null
       markHiddenOutputRestoreNeeded()
       if (restoreWasInFlight) {
@@ -5507,9 +5494,7 @@ export function connectPanePty(
         releaseHiddenDeliveryClaim()
         releaseHiddenDeliveryClaim = null
       } else if (isFirstSyncForPty) {
-        // Why: clear unconditionally on the first sync for a PTY — a stale
-        // main-side hidden bit can survive a renderer reload for
-        // daemon-backed PTYs that keep their session id.
+        // Why: clear unconditionally on first sync — a stale main-side hidden bit can survive a renderer reload for daemon-backed PTYs that keep their session id.
         declareRendererPtyDeliveryVisible(ptyId)
       }
     }
@@ -5551,9 +5536,7 @@ export function connectPanePty(
 
     function isLatencySensitiveForegroundOutput(data: string): boolean {
       if (!isActiveSplitPane()) {
-        // Why: many visible split panes can each emit tiny TUI frames. A shared
-        // budget keeps watched panes live while preventing aggregate xterm work
-        // from starving typing in the active pane.
+        // Why: many visible split panes each emit tiny TUI frames; a shared budget keeps them live without letting aggregate xterm work starve typing in the active pane.
         if (data.includes('\x1b[')) {
           return false
         }
@@ -5597,11 +5580,7 @@ export function connectPanePty(
       return decision.prefersRenderRefresh
     }
 
-    // Why: Vim-style TUI redraws are plain-ASCII in-place rewrites whose erased
-    // cells can keep stale WebGL glyphs until the shared atlas rebuilds. Whether
-    // a rewrite touched the alternate screen is only authoritative once xterm
-    // parses the chunk (enter/exit sequences can split across PTY chunks), so
-    // capture the pre-parse state and decide the rest at parse completion.
+    // Why: Vim-style rewrites leave stale WebGL glyphs until the atlas rebuilds; alt-screen membership is only authoritative post-parse (enter/exit can split chunks), so capture pre-parse and decide at parse completion.
     function alternateScreenRewriteAtlasRecoveryOnParsed(): () => void {
       const wasAlternateScreenBuffer = pane.terminal.buffer.active.type === 'alternate'
       const switchesBeforeParse = alternateScreenBufferSwitches
@@ -5632,8 +5611,7 @@ export function connectPanePty(
         }
       }
       if (rewriteOutputPrefersRenderRefresh) {
-        // Why: resize fixes these panes because xterm's buffer is right but
-        // in-place redraw cells can remain stale in the renderer until repaint.
+        // Why: xterm's buffer is right but in-place redraw cells stay stale in the renderer until a repaint (resize fixes it).
         return { refresh: true, inPlaceRewrite: true, recoverWebglAtlasAfterParse: false }
       }
       if (
@@ -5644,8 +5622,7 @@ export function connectPanePty(
           maxInteractiveRedrawChars: FOREGROUND_INTERACTIVE_REDRAW_CHARS
         })
       ) {
-        // Why: CJK/Korean from Microsoft Pinyin commits and native ConPTY agent
-        // output can leave stale wide-glyph cells in the local Windows DOM renderer.
+        // Why: CJK/Korean from Microsoft Pinyin commits and native ConPTY output can leave stale wide-glyph cells in the Windows DOM renderer.
         return { refresh: true, inPlaceRewrite: false, recoverWebglAtlasAfterParse: false }
       }
       return {
@@ -5670,8 +5647,7 @@ export function connectPanePty(
       }
       const settings = useAppStore.getState().settings
       const mode = resolveTerminalColorSchemeMode(settings, getSystemPrefersDark())
-      // Why: hidden snapshot-backed panes skip xterm.write for PTY bytes. Answer
-      // immediately so the reply cannot outlive the program's read window.
+      // Why: hidden snapshot-backed panes skip xterm.write for PTY bytes; answer immediately so the reply can't outlive the program's read window.
       deps.paneMode2031Ref.current.set(pane.id, true)
       sendDesktopQueryReplyImmediate(mode2031SequenceFor(mode))
       deps.paneLastThemeModeRef.current.set(pane.id, mode)
@@ -5683,9 +5659,7 @@ export function connectPanePty(
       foreground: boolean,
       opts?: { hiddenStartupRendererQuery?: boolean }
     ): void {
-      // Why: every application byte funnels through here (foreground, hidden,
-      // and background writes), so this is the one place the kitty keyboard
-      // mirror observes the pane's protocol negotiation.
+      // Why: every application byte funnels through here, so it's the one place the kitty keyboard mirror observes the pane's protocol negotiation.
       kittyKeyboardModes.scan(data)
       if (foreground) {
         resetHiddenOutputRestoreIfPtyChanged()
@@ -5712,8 +5686,7 @@ export function connectPanePty(
         shouldProtectNativeWindowsSynchronizedOutput &&
         foreground &&
         shouldSynchronizedOutputRemainActive(data, synchronizedForegroundOutputActive)
-      // Why: xterm's DOM renderer draws the cursor as row content; Windows
-      // cursor-only restores need row invalidation even outside DEC 2026.
+      // Why: xterm's DOM renderer draws the cursor as row content, so Windows cursor-only restores need row invalidation even outside DEC 2026.
       const nativeWindowsCursorRestore =
         shouldProtectNativeWindowsSynchronizedOutput && foreground && containsCursorRestore(data)
       const foregroundOutput = foreground || parseHiddenStartupOutput
@@ -5727,27 +5700,20 @@ export function connectPanePty(
         !foregroundOutput && hiddenOutputNeedsAtlasRecoveryAfterParse(data)
       const recoverWebglAtlasAfterParse =
         renderRefreshDecision.recoverWebglAtlasAfterParse || recoverHiddenWebglAtlasAfterParse
-      // Why: atlas recovery must repaint from the parsed xterm buffer, not a
-      // pre-write snapshot that a late TUI redraw can immediately stale.
+      // Why: atlas recovery must repaint from the parsed xterm buffer, not a pre-write snapshot a late TUI redraw can stale.
       const onParsedAtlasRecovery = recoverWebglAtlasAfterParse
         ? scheduleTerminalWebglAtlasRecovery
         : renderRefreshDecision.inPlaceRewrite
           ? alternateScreenRewriteAtlasRecoveryOnParsed()
           : undefined
       const foregroundRenderRefreshNeeded = renderRefreshDecision.refresh
-      // Why: see nativeWindowsRewriteNeedsFollowupRenderRefresh — Claude Code's
-      // in-place prompt redraws on Windows ConPTY can paint one frame late, so a
-      // follow-up repaint corrects the column desync without a window resize.
+      // Why: Claude Code's in-place prompt redraws on Windows ConPTY can paint one frame late; a follow-up repaint fixes the column desync without a resize.
       const nativeWindowsInPlaceRewriteFollowup = nativeWindowsRewriteNeedsFollowupRenderRefresh({
         isNativeWindowsConpty: shouldApplyNativeWindowsRewriteRefresh,
         isForeground: foreground,
         isInPlaceRewrite: renderRefreshDecision.inPlaceRewrite
       })
-      // Why: recompute the latch on every synchronized START so each frame's
-      // interactivity is judged by its own open time vs the last keystroke and
-      // can't leak across a same-chunk close+open; an active frame with no new
-      // start retains it (the split-end-marker headline fix), and we only clear
-      // it once we leave synchronized output on a chunk that is not the end.
+      // Why: recompute the latch on every synchronized START so each frame's interactivity is judged by its own open time and can't leak across a same-chunk close+open; clear only on leaving synchronized output.
       if (synchronizedForegroundOutput && synchronizedOutputStarted) {
         synchronizedForegroundFrameInteractive =
           performance.now() - lastTerminalInputAt <=
@@ -5755,10 +5721,7 @@ export function connectPanePty(
       } else if (!nextSynchronizedForegroundOutputActive && !synchronizedOutputEnded) {
         synchronizedForegroundFrameInteractive = false
       }
-      // Why: ConPTY can split the closing chunk of a submit repaint past the
-      // 150ms redraw window. Treat the whole frame as latency-sensitive when it
-      // opened right after a keystroke so the scheduler drains it on the fast
-      // path (~16-32ms) instead of the 1s synchronized-frame coalesce fallback.
+      // Why: ConPTY can split a submit repaint's closing chunk past the 150ms window, so treat a keystroke-opened frame as latency-sensitive to drain it fast (~16-32ms) not the 1s coalesce fallback.
       const synchronizedFrameLatencySensitive =
         synchronizedForegroundOutput && synchronizedForegroundFrameInteractive
       synchronizedForegroundOutputActive = nextSynchronizedForegroundOutputActive
@@ -5768,10 +5731,7 @@ export function connectPanePty(
       writeTerminalOutput(pane.terminal, data, {
         foreground: foregroundOutput,
         beforeWrite: beforeTerminalOutputWrite,
-        // Why: claims the in-progress pty:data delivery's parse-deferred ACK
-        // (null outside a delivery, e.g. snapshot replays / synthetic writes).
-        // The FIRST scheduler write of a delivery carries the whole credit;
-        // the scheduler fires it when the bytes are consumed.
+        // Why: claim the delivery's parse-deferred ACK credit (null outside a delivery); the FIRST scheduler write carries it all and fires when bytes are consumed.
         ackCredit: takeCurrentPtyDeliveryAckCredit() ?? undefined,
         onBackgroundBacklogDropped: markHiddenOutputRestoreNeeded,
         latencySensitive:
@@ -5785,8 +5745,7 @@ export function connectPanePty(
             foregroundRenderRefreshNeeded),
         followupForegroundRefresh:
           nativeWindowsCursorRestore || nativeWindowsInPlaceRewriteFollowup,
-        // Why: xterm already queued a WebGL frame while parsing this chunk;
-        // merge the repair into it instead of rendering the full grid twice.
+        // Why: xterm already queued a WebGL frame parsing this chunk; merge the repair into it instead of rendering the grid twice.
         shouldRefreshForegroundSynchronously,
         onParsed: onParsedAtlasRecovery,
         stripTransientCursorShows: shouldProtectNativeWindowsSynchronizedOutput && foreground,
@@ -5829,8 +5788,7 @@ export function connectPanePty(
       ) {
         return false
       }
-      // Why: CPR/DECRQM replies depend on ordered terminal state. Keep the rare
-      // clean stateful-query chunk live; after skipped bytes, avoid stale replies.
+      // Why: CPR/DECRQM replies depend on ordered state; keep a clean stateful-query chunk live, but after skipped bytes avoid stale replies.
       return hiddenRendererStateDirty || !containsStatefulRendererQuery(data)
     }
 
@@ -5841,9 +5799,7 @@ export function connectPanePty(
       )
       hiddenStartupRendererQueryPending = extracted.pending
       if (extracted.oscColorQueryData) {
-        // Why: Codex's startup palette probe has a 100 ms budget. Answer
-        // hidden color queries directly and immediately so neither renderer
-        // scheduling nor the remote input debounce (#7329) can miss it.
+        // Why: Codex's startup palette probe has a 100ms budget; answer hidden color queries immediately so scheduling/remote-input debounce (#7329) can't miss it.
         sendTerminalOscColorQueryReplies(
           extracted.oscColorQueryData,
           pane.terminal,
@@ -5855,8 +5811,7 @@ export function connectPanePty(
           hiddenStartupRendererQuery: true
         })
       }
-      // Stateful hidden queries require ordered terminal state. If this pane's
-      // hidden xterm is dirty, skipping is safer than sending stale CPR/DECRQM.
+      // Stateful hidden queries need ordered terminal state; if the hidden xterm is dirty, skip rather than send stale CPR/DECRQM.
     }
 
     function takeHiddenStartupRendererQueryPendingForForeground(data: string): {
@@ -5951,15 +5906,7 @@ export function connectPanePty(
       recordHiddenRendererSkip(data.length)
     }
 
-    // Why: discarding queued flood bytes must never swallow terminal queries —
-    // a lost DSR/CPR (or color/DA) reply hangs the querying program (the bench
-    // DSR timeout). The discarded CONTENT is owned by the snapshot repaint.
-    // Replies are synthesized through the immediate input path instead of
-    // replaying the queries into xterm: a drop always triggers a snapshot
-    // restore, whose replay guard swallows xterm auto-replies and whose
-    // discardTerminalOutput races away queued query writes — both killed the
-    // salvaged reply in practice. Only called for bytes being thrown away, so
-    // replies cannot double-fire against a later queue drain.
+    // Why: discarding flood bytes must not swallow terminal queries (a lost DSR/CPR hangs the program); the snapshot repaint owns the content, so synthesize replies via the immediate input path, not xterm replay.
     function salvageRendererQueriesFromDiscardedRestoreData(data: string): void {
       if (!data || !data.includes('\x1b')) {
         return
@@ -5977,9 +5924,7 @@ export function connectPanePty(
         extracted.statefulQueryData + extracted.statelessQueryData
       )) {
         if (sequence === '\x1b[6n') {
-          // CPR from the live buffer. Position may be mid-repaint stale — in a
-          // drop scenario positional accuracy is already forfeit; liveness is
-          // the contract (a blocked reader must unblock).
+          // CPR from the live buffer; may be mid-repaint stale, but in a drop scenario liveness (unblock the reader) is the contract, not accuracy.
           const buffer = pane.terminal.buffer.active
           const row = Math.min(buffer.cursorY + 1, pane.terminal.rows)
           const col = Math.min(buffer.cursorX + 1, pane.terminal.cols)
@@ -5991,8 +5936,7 @@ export function connectPanePty(
         }
       }
       if (unansweredQueryData) {
-        // Best-effort for the rarer queries (DECRQM, DA2, XTVERSION): replay
-        // into xterm and let its handlers answer when no replay is active.
+        // Best-effort for rarer queries (DECRQM, DA2, XTVERSION): replay into xterm so its handlers answer when no replay is active.
         writePtyOutputToXterm(unansweredQueryData, true, { hiddenStartupRendererQuery: true })
       }
     }
@@ -6025,9 +5969,7 @@ export function connectPanePty(
       hiddenOutputRestorePtyId = ptyId
       hiddenOutputRestoreNeeded = true
       if (hiddenOutputRestorePendingOverflow) {
-        // Why: the overflow latch means everything queued gets discarded at the
-        // next drain — queueing more only grows the discard. Salvage queries,
-        // drop the content.
+        // Why: the overflow latch discards everything queued at the next drain, so queueing more only grows the discard; salvage queries, drop content.
         salvageRendererQueriesFromDiscardedRestoreData(data)
         armHiddenOutputRestoreForegroundDeadline()
         return
@@ -6083,10 +6025,7 @@ export function connectPanePty(
       | { action: 'drop-duplicate' }
       | { action: 'force-fresh-restore' }
 
-    // Why: same slicing rules as getChunkDataAfterSnapshot, applied to LIVE
-    // chunks after a restore completed — main's ACK backlog keeps draining
-    // chunks at or before the snapshot seq, and pending-cap trims can drop
-    // seq ranges silently once the one-shot overflow marker was consumed.
+    // Why: same slicing as getChunkDataAfterSnapshot but for post-restore live chunks, which main's ACK backlog can still deliver at/before the snapshot seq (and can trim seq ranges silently).
     function reconcileChunkAgainstRestoredSnapshot(
       data: string,
       meta: PtyDataMeta | undefined
@@ -6099,19 +6038,14 @@ export function connectPanePty(
         return { action: 'write', data, meta }
       }
       if (typeof meta?.seq !== 'number') {
-        // Why: seq-less chunks (no runtime metering) cannot be reconciled;
-        // mirror getChunkDataAfterSnapshot and pass them through.
+        // Why: seq-less chunks (no runtime metering) can't be reconciled; pass them through like getChunkDataAfterSnapshot.
         return { action: 'write', data, meta }
       }
       if (
         restoredSnapshotDeliveryWindowStartSeq !== null &&
         meta.seq <= restoredSnapshotDeliveryWindowStartSeq
       ) {
-        // Why: every byte main could still deliver at snapshot time started
-        // AFTER this seq, and delivery is once-and-in-order — so this chunk
-        // cannot be a backlog duplicate. It is a new seq domain (restarted
-        // counter / synthetic source); retire the stale baseline and write
-        // instead of silently dropping genuinely-new live output.
+        // Why: all still-deliverable bytes started after this seq and delivery is in-order, so this can't be a backlog dup — it's a new seq domain; retire the baseline and write.
         clearRestoredSnapshotBaseline()
         return { action: 'write', data, meta }
       }
@@ -6120,9 +6054,7 @@ export function connectPanePty(
       const expectedStartSeq = restoredSnapshotExpectedStartSeq
       restoredSnapshotExpectedStartSeq = Math.max(expectedStartSeq ?? meta.seq, meta.seq)
       if (expectedStartSeq !== null && startSeq > expectedStartSeq) {
-        // Why: the chunk starts past the continuity point — bytes between
-        // were dropped (pending-cap trim after the marker fired). Only the
-        // model snapshot can heal the gap.
+        // Why: the chunk starts past the continuity point — bytes between were dropped (pending-cap trim); only a fresh snapshot heals the gap.
         return { action: 'force-fresh-restore' }
       }
       if (meta.seq <= restoredSnapshotBaselineSeq) {
@@ -6132,17 +6064,14 @@ export function connectPanePty(
         return { action: 'write', data, meta }
       }
       if (rawLength !== data.length) {
-        // Why: renderer-only OSC stripping makes raw sequence offsets
-        // impossible to map onto cleaned text — fetch a fresh snapshot
-        // instead of risking duplicate visible output.
+        // Why: renderer-only OSC stripping makes raw seq offsets unmappable onto cleaned text; refetch instead of risking duplicate output.
         return { action: 'force-fresh-restore' }
       }
       const sliced = data.slice(restoredSnapshotBaselineSeq - startSeq)
       return {
         action: 'write',
         data: sliced,
-        // Why: keep seq metadata consistent with the sliced payload so a
-        // later restore queue drain slices against accurate offsets.
+        // Why: keep seq metadata consistent with the sliced payload so a later queue drain slices against accurate offsets.
         meta: { ...meta, rawLength: sliced.length }
       }
     }
@@ -6164,12 +6093,7 @@ export function connectPanePty(
     }
 
     resetRendererOrderedSeqForPtyExit = (exitedPtyId: string): void => {
-      // Why: an exit ends this ptyId's seq domain. A revived session can reuse
-      // the id with a restarted main-side counter, and a stale high-water mark
-      // would wrongly cover — and silently drop — every hidden byte it emits.
-      // The restored-snapshot baseline is a seq high-water mark too and must
-      // die at the same boundary, or reconcile drops revived chunks as
-      // duplicates.
+      // Why: an exit ends this ptyId's seq domain; a revived id restarts main's counter, so both seq high-water marks (ordered + restored baseline) must reset here or they drop revived bytes as duplicates.
       if (restoredSnapshotBaselinePtyId === exitedPtyId) {
         clearRestoredSnapshotBaseline()
       }
@@ -6197,10 +6121,7 @@ export function connectPanePty(
         return
       }
       if (rendererChannelSeq !== null && meta.seq < rendererChannelSeq) {
-        // Why: pty:data delivery is FIFO per pty, so seq only moves backwards
-        // when the session was revived without an observed exit and restarted
-        // its counter. Drop the stale ordered baseline instead of letting it
-        // cover the new stream's bytes.
+        // Why: pty:data is FIFO, so seq regresses only when a session revived without an observed exit and restarted its counter; drop the stale baseline.
         if (rendererOrderedPtyId === ptyId) {
           rendererOrderedPtyId = null
           rendererOrderedSeq = null
@@ -6226,10 +6147,7 @@ export function connectPanePty(
       )
     }
 
-    // 'drained' painted every queued live byte; 'overflow' means the queue
-    // blew its cap during this restore (the stream is outrunning snapshot
-    // fetch+replay); 'refetch' means offsets were unmappable and only a
-    // fresher snapshot can realign.
+    // 'drained' = painted all queued bytes; 'overflow' = queue blew its cap (stream outran fetch+replay); 'refetch' = offsets unmappable, need a fresher snapshot.
     function drainPendingLiveChunksAfterSnapshot(
       snapshotSeq: number | undefined
     ): 'drained' | 'overflow' | 'refetch' {
@@ -6245,18 +6163,14 @@ export function connectPanePty(
         for (const [index, chunk] of chunks.entries()) {
           const data = getChunkDataAfterSnapshot(chunk, snapshotSeq)
           if (data === null) {
-            // Why: renderer-only OSC stripping makes raw sequence offsets
-            // impossible to map onto cleaned text. Fetch a fresher main
-            // snapshot instead of risking duplicate visible output.
+            // Why: renderer-only OSC stripping makes raw seq offsets unmappable onto cleaned text; refetch instead of risking duplicate output.
             for (const discarded of chunks.slice(index)) {
               salvageRendererQueriesFromDiscardedRestoreData(discarded.data)
             }
             discardPendingLiveChunksSalvagingQueries()
             return 'refetch'
           }
-          // Why: drained chunks advance the post-restore continuity point so
-          // the live-chunk reconciliation neither re-drops them as duplicates
-          // nor misreads the next live chunk as a gap.
+          // Why: advance the continuity point so reconciliation neither re-drops drained chunks as duplicates nor misreads the next live chunk as a gap.
           if (typeof chunk.seq === 'number' && restoredSnapshotExpectedStartSeq !== null) {
             restoredSnapshotExpectedStartSeq = Math.max(restoredSnapshotExpectedStartSeq, chunk.seq)
           }
@@ -6328,8 +6242,7 @@ export function connectPanePty(
         return
       }
       const deadlineGeneration = hiddenOutputRestoreGeneration
-      // Why: only foreground-visible output blocked behind recovery gets a
-      // deadline; hidden-time restore work can continue without user impact.
+      // Why: only foreground output blocked behind recovery gets a deadline; hidden-time restore work has no user impact.
       hiddenOutputRestoreForegroundDeadlineTimer = setTimeout(() => {
         hiddenOutputRestoreForegroundDeadlineTimer = null
         if (
@@ -6363,8 +6276,7 @@ export function connectPanePty(
         hiddenOutputSnapshotScrollRestore?.valid &&
         hiddenOutputSnapshotScrollRestore.ptyId === expectedPtyId
       ) {
-        // Why: same-PTY flood abandonment stops recovery bookkeeping, but its
-        // already-queued replay must keep the rebuild bracket and final pin.
+        // Why: flood abandonment stops recovery bookkeeping, but its already-queued replay must keep the rebuild bracket and final pin.
         hiddenOutputSnapshotScrollRestore.generation = hiddenOutputRestoreGeneration
       }
       hiddenOutputRestoreInFlight = null
@@ -6384,9 +6296,7 @@ export function connectPanePty(
       clearHiddenOutputRestoreForegroundDeadlineTimer()
       hiddenOutputRestoreDeferredRetryAttempts = 0
 
-      // Why quiet exists: flood cuts abandon deliberately and schedule a
-      // post-flood repaint — the "restore unavailable" warning would be
-      // misleading noise the repaint immediately wipes.
+      // Why quiet: flood cuts abandon deliberately and repaint post-flood, so the "restore unavailable" warning would be noise the repaint wipes.
       if (!opts.quiet) {
         writeRestoreUnavailableWarning()
       }
@@ -6432,8 +6342,7 @@ export function connectPanePty(
         return
       }
       hiddenOutputRestoreDeferredRetryAttempts += 1
-      // Why: null requested snapshots usually mean remote output was still
-      // mutating. Retry after one quiet tick instead of spinning synchronously.
+      // Why: a null snapshot usually means remote output was still mutating; retry after one quiet tick instead of spinning.
       hiddenOutputRestoreDeferredRetryTimer = setTimeout(() => {
         hiddenOutputRestoreDeferredRetryTimer = null
         if (disposed || !hiddenOutputRestoreNeeded) {
@@ -6468,8 +6377,7 @@ export function connectPanePty(
       if (scrollRestore.started) {
         cancelTerminalScrollIntentBufferRebuildCompletions(pane.terminal)
       }
-      // Why: invalidation suppresses restoration, but queued bytes still own
-      // the bracket until their FIFO sentinels prove parsing has finished.
+      // Why: invalidation suppresses restoration, but queued bytes still own the bracket until their FIFO sentinels prove parsing finished.
     }
     cancelHiddenOutputSnapshotScrollRestore = cancelSnapshotScrollRestore
 
@@ -6491,8 +6399,7 @@ export function connectPanePty(
       if (cols <= 2 || rows <= 0) {
         return
       }
-      // Why: a hidden alternate-screen TUI can miss the same-size restore
-      // SIGWINCH. A one-column pulse makes the repaint observable to the child.
+      // Why: a hidden alt-screen TUI can miss the same-size restore SIGWINCH; a one-column pulse makes the repaint observable to the child.
       transport.resize(cols - 1, rows)
       transport.resize(cols, rows)
     }
@@ -6518,8 +6425,7 @@ export function connectPanePty(
         return
       }
       if (transport.getPtyId() !== hiddenOutputRestorePtyId) {
-        // Why: renderer backlog is tied to the old PTY stream; after reattach,
-        // queued hidden bytes must not delay or replay before the new PTY.
+        // Why: renderer backlog is tied to the old PTY stream; after reattach it must not delay or replay before the new PTY.
         clearHiddenOutputRestoreState()
         clearRestoredSnapshotBaseline()
         clearPaneMode2031State()
@@ -6593,8 +6499,7 @@ export function connectPanePty(
               hasSnapshotDimensions &&
               (pane.terminal.cols !== snapshot.cols || pane.terminal.rows !== snapshot.rows)
             ) {
-              // Why: xterm parses writes later. Keep snapshot dimensions until
-              // the FIFO sentinel completes so serialized wraps stay exact.
+              // Why: xterm parses writes later; hold snapshot dimensions until the FIFO sentinel completes so serialized wraps stay exact.
               suppressStructuralReplayPtyResize = true
               try {
                 pane.terminal.resize(snapshot.cols, snapshot.rows)
@@ -6603,40 +6508,26 @@ export function connectPanePty(
               }
             }
             if (!snapshot.alternateScreen) {
-              // Why: this clear (incl. \x1b[3J) wipes xterm's scrollback. Alt-screen
-              // TUIs (Claude Code, vim) keep their scroll history in xterm, so
-              // clearing on restore loses scroll-up after a hidden->visible return.
-              // Mirrors the attach-time guard in pty-transport.ts.
+              // Why: \x1b[3J wipes xterm scrollback; alt-screen TUIs keep it in xterm, so clear only the normal buffer (mirrors pty-transport.ts).
               writeReplayData('\x1b[2J\x1b[3J\x1b[H')
             } else if (snapshot.scrollbackAnsi !== undefined) {
-              // Why: SerializeAddon captures normal and alternate buffers together.
-              // Rebuild normal while it is active, then return to a clean alt frame.
+              // Why: SerializeAddon captures normal + alt buffers together; rebuild normal while active, then return to a clean alt frame.
               writeReplayData('\x1b[?1049l\x1b[2J\x1b[3J\x1b[H')
               writeReplayData(snapshot.scrollbackAnsi)
               writeReplayData('\x1b[0m\x1b[?1049h\x1b[2J\x1b[H')
             } else {
-              // Why: the snapshot's own ?1049h is a no-op when the pane is already on
-              // the alternate screen, and the serialized frame skips blank cells — so
-              // without clearing the alt screen the pre-hide frame bleeds through
-              // every cell the final frame leaves blank. \x1b[2J on the alt buffer
-              // does not touch the normal buffer's scrollback the TUI returns to.
+              // Why: the snapshot's ?1049h no-ops when already on alt screen and skips blank cells; clear the alt buffer so the pre-hide frame can't bleed through blank cells (spares normal-buffer scrollback).
               writeReplayData('\x1b[0m\x1b[?1049h\x1b[2J\x1b[H')
             }
             writeReplayData(snapshot.data)
-            // Why: status/title-corroborated live agents own ?25l/?1004h (a forced
-            // ?1004l here would silence focus events until the agent restarts, since
-            // agents only enable focus reporting at startup).
+            // Why: live agents own ?25l/?1004h; a forced ?1004l here would silence focus events until restart (agents enable focus reporting only at startup).
             writeReplayData(
               hasLiveAgentReattachStatusOrTitleSignal()
                 ? POST_REPLAY_LIVE_AGENT_SNAPSHOT_RESET
                 : POST_REPLAY_LIVE_SNAPSHOT_RESET
             )
             if (snapshot.pendingEscapeTailAnsi) {
-              // Why last: the snapshot was taken with main's emulator mid-escape;
-              // re-arming the dangling sequence must be the FINAL replay write (any
-              // later ESC — including the reset above — aborts it) so the racing
-              // live tail's continuation completes it exactly as live, instead of
-              // rendering literally (Bug E fix / #7329).
+              // Why last: snapshot taken mid-escape; re-arm as the FINAL replay write (any later ESC aborts it) so the live tail completes it, not render literally (Bug E / #7329).
               writeReplayData(snapshot.pendingEscapeTailAnsi)
             }
             hiddenRendererStateDirty = false
@@ -6678,8 +6569,7 @@ export function connectPanePty(
                   if (replayChangedDimensions && isRendererPtyResizeAuthoritative()) {
                     transport.resize(pane.terminal.cols, pane.terminal.rows)
                     if (!isRemoteRuntimePtyId(currentPtyId)) {
-                      // Why: redundant SIGWINCH can make alternate-screen TUIs rebuild
-                      // their internal scroll viewport to the top on tab return.
+                      // Why: redundant SIGWINCH makes alt-screen TUIs rebuild their scroll viewport to the top on tab return.
                       window.api.pty.signal(currentPtyId, 'SIGWINCH')
                     }
                   }
@@ -6708,16 +6598,9 @@ export function connectPanePty(
     }
 
     function requestHiddenOutputRestoreIfNeeded(opts?: { bypassScheduler?: boolean }): boolean {
-      // Why: once the write pipeline is probe-certified dead, a restore can
-      // never parse — replaying just re-arms the wedged breadcrumb drip and
-      // wastes a snapshot fetch each time the delivery watchdog heals stuck
-      // in-flight bytes (~60s while idle). Recovery owns the pane now; the
-      // remounted pane gets a fresh xterm and a fresh restore.
+      // Why: once the write pipeline is probe-certified dead a restore can never parse; recovery owns the pane and the remount gets a fresh xterm + restore.
       if (isTerminalWritePipelineCertifiedDead(pane.terminal)) {
-        // Why the re-kick: certification's own recovery request can be
-        // budget-declined (or its scheduled retry cancelled by a sibling
-        // pane's remount). Without a fallback here, a revealed dead pane
-        // skips its restore forever and keeps the stale pre-death frame.
+        // Why the re-kick: certification's recovery request can be budget-declined or cancelled by a sibling remount; without this, a revealed dead pane keeps the stale frame forever.
         if (!certifiedDeadRestoreRecoveryRequested && !disposed) {
           certifiedDeadRestoreRecoveryRequested = true
           const storePtyId = useAppStore.getState().ptyIdsByTabId?.[deps.tabId]?.[0] ?? null
@@ -6751,9 +6634,7 @@ export function connectPanePty(
             hiddenOutputRestoreScheduled = true
             const scheduledPtyId = ptyId
             const scheduledGeneration = hiddenOutputRestoreGeneration
-            // Why: tab/worktree resume can make many split panes visible at once.
-            // Restore the focused pane immediately and spread inactive replays
-            // across frames so xterm scrollback replay does not block return.
+            // Why: resume can reveal many split panes at once; spread inactive replays across frames so xterm scrollback replay doesn't block return.
             scheduleHiddenOutputRestore(
               pane.terminal,
               () => {
@@ -6783,9 +6664,7 @@ export function connectPanePty(
       hiddenOutputRestoreRetryDeferred = false
 
       hiddenOutputRestoreInFlight = (async () => {
-        // Backstop for the rc.7.perf feedback loop: bound how many snapshot
-        // fetch+replay rounds one task may burn before it must yield to the
-        // live stream.
+        // Backstop (rc.7.perf loop): bound how many snapshot fetch+replay rounds one task burns before yielding to the live stream.
         let restoreIterations = 0
         while (!disposed) {
           const currentPtyId = hiddenOutputRestorePtyId
@@ -6823,10 +6702,7 @@ export function connectPanePty(
           const restorePtyChanged =
             transport.getPtyId() !== currentPtyId || hiddenOutputRestorePtyId !== currentPtyId
           if (restoreGenerationChanged || restorePtyChanged) {
-            // Why: the snapshot belongs to the requested PTY; after reattach,
-            // replaying it would show stale/cleared output in the new terminal.
-            // A stale generation may be an abandoned timeout while a newer
-            // restore for the same PTY owns the current hidden-recovery state.
+            // Why: the snapshot belongs to the requested PTY; after reattach it's stale, and a stale generation may be an abandoned timeout superseded by a newer restore.
             if (restorePtyChanged && hiddenOutputRestorePtyId === currentPtyId) {
               clearHiddenOutputRestoreState()
             }
@@ -6850,9 +6726,7 @@ export function connectPanePty(
           ) {
             return
           }
-          // Why: everything at or before snapshot.seq is now painted; chunks
-          // still draining from main's ACK backlog below that point are
-          // duplicates the dataCallback reconciliation must suppress.
+          // Why: everything at/before snapshot.seq is now painted; chunks still draining from main's ACK backlog below it are duplicates to suppress.
           setRestoredSnapshotBaseline(currentPtyId, snapshot)
           hiddenOutputRestoreReplayingSnapshot = null
           const needsFreshSnapshot = hiddenOutputRestoreFreshSnapshotNeeded
@@ -6865,25 +6739,18 @@ export function connectPanePty(
             return
           }
           if (!shouldWritePtyOutputForeground(deps.isVisibleRef.current)) {
-            // Why: hidden bytes that arrived during the snapshot were not kept
-            // in renderer memory. Leave recovery pending for the next visible
-            // moment instead of looping hidden snapshots in a throttled tab.
+            // Why: hidden bytes arriving during the snapshot aren't in renderer memory; leave recovery pending for reveal, don't loop snapshots in a throttled tab.
             hiddenOutputRestoreNeeded = true
             return
           }
           if (drainOutcome === 'overflow') {
-            // Cut 1 of the rc.7.perf feedback loop: a FOREGROUND queue
-            // overflow means the live stream outruns snapshot fetch+replay.
-            // Re-fetching would starve ACK processing again and feed the
-            // drop/re-arm cycle — abandon now, let bytes write through, and
-            // heal with one repaint after the flood.
+            // Cut 1 (rc.7.perf loop): a FOREGROUND queue overflow means the stream outruns fetch+replay; re-fetching starves ACKs, so abandon and heal with one post-flood repaint.
             noteHiddenOutputRestoreFloodBackpressure()
             abandonHiddenOutputRestoreAndDrainPendingForeground(currentPtyId, { quiet: true })
             return
           }
           if (restoreIterations >= HIDDEN_OUTPUT_RESTORE_MAX_LOOP_ITERATIONS) {
-            // Backstop: fresh-snapshot marks / unmappable slices re-looping
-            // this many times means the stream is winning the race.
+            // Backstop: re-looping this many times means the stream is winning the race.
             warnTerminalLifecycleAnomaly('hidden output restore hit its iteration cap', {
               tabId: deps.tabId,
               worktreeId: deps.worktreeId,
@@ -6922,9 +6789,7 @@ export function connectPanePty(
     }
 
     unregisterBacklogRecovery = registerTerminalBacklogRecovery(pane.terminal, () => {
-      // Why: clear the hidden-delivery bit BEFORE the restore snapshot
-      // request — bytes arriving between the unhide IPC and the snapshot
-      // are reconciled by the existing seq guard.
+      // Why: clear the hidden-delivery bit BEFORE the restore snapshot request; bytes arriving in between are reconciled by the seq guard.
       syncHiddenRendererPtyDelivery()
       return requestHiddenOutputRestoreIfNeeded()
     })
@@ -6934,18 +6799,14 @@ export function connectPanePty(
       typeof document.removeEventListener === 'function'
     ) {
       const onDocumentVisibilityChange = (): void => {
-        // Why: document hide/show flips the foreground predicate without any
-        // pane lifecycle event — re-sync the hidden-delivery gate both ways.
+        // Why: document hide/show flips the foreground predicate with no pane lifecycle event; re-sync the hidden-delivery gate both ways.
         syncHiddenRendererPtyDelivery()
         if (shouldWritePtyOutputForeground(deps.isVisibleRef.current)) {
           requestHiddenOutputRestoreIfNeeded()
         }
       }
       document.addEventListener('visibilitychange', onDocumentVisibilityChange)
-      // Why: when user input proves visibilityState is wedged at 'hidden'
-      // (stale macOS occlusion), run the same resync — no visibilitychange
-      // will ever fire in that state, and the gate would drop watched bytes
-      // forever.
+      // Why: on stale macOS occlusion (visibilityState wedged 'hidden'), user input forces a resync — no visibilitychange fires, else the gate drops bytes forever.
       const unregisterStaleVisibilityRecovery = registerStaleDocumentVisibilityRecovery(
         onDocumentVisibilityChange
       )
@@ -6964,8 +6825,7 @@ export function connectPanePty(
         return
       }
       if (deferredReattachLiveData !== null) {
-        // Why: a replacement stream must not inherit either bytes or a gap
-        // marker from the replay owner it superseded.
+        // Why: a replacement stream must not inherit bytes or a gap marker from the replay owner it superseded.
         deferredReattachLiveData = deferredReattachLiveData.filter(
           (chunk) => chunk.streamGeneration === streamGeneration
         )
@@ -6982,9 +6842,7 @@ export function connectPanePty(
           ...(meta ? { meta } : {})
         })
         deferredReattachLiveDataChars += deferredData.length
-        // Why: retaining one arbitrarily large IPC frame would bypass this
-        // queue's memory bound. Mark it as a stream gap so snapshot recovery
-        // replaces it instead of feeding a partial ANSI frame to xterm.
+        // Why: one huge IPC frame would bypass the queue's memory bound; mark a stream gap so snapshot recovery replaces it, not a partial ANSI frame.
         let dropped = oversized
         while (
           deferredReattachLiveData.length > 1 &&
@@ -7006,8 +6864,7 @@ export function connectPanePty(
       if (data.length > 0) {
         hasReceivedPtyOutput = true
         recordAgentHibernationPaneOutput(cacheKey)
-        // Why: output is the agent-start escalation signal that ends the relaxed
-        // no-evidence process-scan cadence (a starting agent always prints).
+        // Why: output is the agent-start signal that ends the relaxed no-evidence process-scan cadence (a starting agent always prints).
         agentCompletionCoordinator.observeOutputActivity()
       }
       if (sshShellReadyMarkerScan) {
@@ -7020,21 +6877,14 @@ export function connectPanePty(
       observeStartupDraftPasteReadiness(data)
       resetHiddenOutputRestoreIfPtyChanged()
       if (meta?.droppedOutput === true) {
-        // Why gated (rc.7.perf loop): a visible pane's cap-drop during its own
-        // restore is backpressure the restore itself caused — re-arming per
-        // sentinel kept the snapshot-fetch loop alive for the whole flood.
-        // Defer to one post-flood repaint; any carved-out query bytes riding
-        // the sentinel still flow through the normal write path below.
+        // Why gated (rc.7.perf loop): a visible pane's cap-drop during its own restore is self-caused backpressure; defer to one post-flood repaint instead of re-arming per sentinel.
         if (meta?.background !== true && isForegroundRestoreBackpressureContext()) {
           noteHiddenOutputRestoreFloodBackpressure()
         } else {
-          // Why: main dropped this PTY's buffered output at the pending cap
-          // (renderer was not receiving). The stream has a gap, so repaint the
-          // pane from the main-owned buffer snapshot instead of writing on.
+          // Why: main dropped buffered output at the pending cap, so the stream has a gap; repaint from the main-owned snapshot instead of writing on.
           markHiddenOutputRestoreNeeded()
           if (data) {
-            // The sentinel can carry query bytes carved out of the bulk drop
-            // (extractDroppedPtyQueryBytes in main) — replies must still flow.
+            // The sentinel can carry query bytes carved from the bulk drop (extractDroppedPtyQueryBytes in main); replies must still flow.
             salvageRendererQueriesFromDiscardedRestoreData(data)
           }
           return
@@ -7042,11 +6892,7 @@ export function connectPanePty(
       }
       respondToTerminalPixelSizeQueries(data)
       observeTerminalBracketedPasteModeOutput(pane.terminal, data)
-      // Why: with main side-effect authority, command-finished, pr-link, and
-      // the Command Code scrape arrive as pty:sideEffect facts —
-      // byte-scanning here too would double-fire the same policy.
-      // Remote-runtime PTYs (and the kill switch off) keep this byte path as
-      // their only parser.
+      // Why: under main side-effect authority these facts arrive via pty:sideEffect; byte-scanning here would double-fire. Remote PTYs / kill-switch-off keep this path.
       if (!mainSideEffectAuthority) {
         for (const link of observeTerminalGitHubPRLink(data)) {
           useAppStore.getState().observeTerminalGitHubPullRequestLink(deps.worktreeId, link)
@@ -7054,40 +6900,29 @@ export function connectPanePty(
         commandLifecycle.handlePtyData(data)
       }
       commandCodeOutputStatusDetector?.observe(data)
-      // Why: split-pane layouts have multiple visible-but-inactive panes whose
-      // output the user is watching. Throttle only when the pane or whole
-      // Electron document is hidden.
+      // Why: split panes have visible-but-inactive panes the user watches; throttle only when the pane or whole document is hidden.
       const foreground =
         shouldWritePtyOutputForeground(deps.isVisibleRef.current) && meta?.background !== true
-      // Why: latch the hidden-delivery gate from the byte path too — covers a
-      // PTY id arriving after the initial sync. No-op when state is current.
+      // Why: latch the hidden-delivery gate from the byte path too, covering a PTY id that arrives after the initial sync (no-op when current).
       if (!foreground) {
         syncHiddenRendererPtyDelivery()
       }
       if (foreground && hiddenMode2031ScanTail) {
         respondToSkippedMode2031Subscribe(data)
       }
-      // Why: post-restore reconciliation — drop/slice backlog chunks the
-      // restored snapshot already covers, and force a fresh restore for seq
-      // gaps or overlaps whose offsets cannot be mapped. Runs after the byte
-      // observers above (those bytes were never delivered before; their side
-      // effects are still real) but before any xterm write decision.
+      // Post-restore reconciliation: drop chunks the snapshot covers, force a fresh restore for unmappable seq gaps; runs after byte observers, before any xterm write.
       const reconciliation = reconcileChunkAgainstRestoredSnapshot(data, meta)
       if (reconciliation.action === 'drop-duplicate') {
         return
       }
       if (reconciliation.action === 'force-fresh-restore') {
-        // Why gated (rc.7.perf loop): during a foreground flood the seq gaps
-        // come from our own backpressure drops — fetching a snapshot per gap
-        // IS the feedback loop. Retire the stale baseline, write the post-gap
-        // bytes through, and heal with one repaint after the flood.
+        // Why gated (rc.7.perf loop): foreground-flood seq gaps are our own backpressure drops; snapshot-per-gap IS the loop, so retire the baseline and heal post-flood.
         if (foreground && isForegroundRestoreBackpressureContext()) {
           noteHiddenOutputRestoreFloodBackpressure()
           clearRestoredSnapshotBaseline()
           // fall through with the ORIGINAL data/meta — post-gap bytes are new
         } else {
-          // Why: in-flight captured BEFORE the mark — on a visible pane the
-          // mark starts the restore synchronously and must not flag itself.
+          // Why: capture in-flight BEFORE the mark — on a visible pane the mark starts the restore synchronously and must not flag itself.
           const restoreWasInFlight = hiddenOutputRestoreInFlight !== null
           markHiddenOutputRestoreNeeded()
           if (restoreWasInFlight) {
@@ -7099,8 +6934,7 @@ export function connectPanePty(
         data = reconciliation.data
         meta = reconciliation.meta
       }
-      // Why: a hidden Codex query can be split just before visibility changes;
-      // xterm needs the completed query, while other bytes still follow restore.
+      // Why: a hidden Codex query can split just before visibility flips; hand xterm the completed query while other bytes still follow restore.
       const pendingForegroundQuery = foreground
         ? takeHiddenStartupRendererQueryPendingForForeground(data)
         : null
@@ -7114,8 +6948,7 @@ export function connectPanePty(
         ? rendererData
         : getHiddenRendererDataAfterOrderedSeq(rendererData, rendererMeta)
       if (orderedRendererData === null) {
-        // Why: renderer-side filtering cannot map cleaned text back onto raw
-        // sequence offsets. Rebuild from main instead of risking stale bytes.
+        // Why: renderer filtering can't map cleaned text back to raw seq offsets; rebuild from main instead of risking stale bytes.
         markHiddenOutputRestoreNeeded()
         schedulePendingStartupCommandDelivery()
         return
@@ -7134,8 +6967,7 @@ export function connectPanePty(
         sendTerminalOscColorQueryReplies(
           pendingForegroundQuery.oscColorQueryData,
           pane.terminal,
-          // Why: OSC color reply — immediate so the remote debounce cannot delay
-          // it past the querying program's read window (#7329).
+          // Why: OSC color reply sent immediately so the remote debounce can't delay it past the program's read window (#7329).
           sendDesktopQueryReplyImmediate
         )
       }
@@ -7165,15 +6997,9 @@ export function connectPanePty(
           hiddenOutputRestoreNeeded = true
           hiddenOutputRestoreFreshSnapshotNeeded = true
         }
-        // Why: hidden chunks with a restore already latched are dropped here —
-        // the model snapshot fetched on reveal covers their bytes.
+        // Why: hidden chunks with a restore already latched are dropped; the reveal snapshot covers their bytes.
       } else {
-        // Why: gate-managed hidden panes normally receive no bytes (main
-        // drops after model ingestion). Any hidden chunk that still arrives
-        // (kill switch off, interest-held delivery) rides the bounded
-        // background scheduler queue; on overflow the scheduler latches the
-        // model restore. The kill-switch-off startup-query grammar above is
-        // the byte-identical fallback.
+        // Why: hidden panes normally get no bytes (main drops post-ingestion); stragglers ride the bounded background queue, overflow latches restore.
         if (pendingForegroundQuery?.statefulQueryData) {
           writePtyOutputToXterm(pendingForegroundQuery.statefulQueryData, true, {
             hiddenStartupRendererQuery: true
@@ -7232,9 +7058,7 @@ export function connectPanePty(
       if (disposed || !chunks) {
         return
       }
-      // Why: createOrAttach snapshots precede bytes emitted before its IPC
-      // reply. Paint the authoritative replay first, then admit those live
-      // chunks so the replay clear cannot erase newer output.
+      // Why: paint the authoritative replay first, then admit deferred live chunks so the replay clear can't erase newer output.
       let deliveredDeferredChunks = 0
       for (const chunk of chunks) {
         if (
@@ -7248,8 +7072,7 @@ export function connectPanePty(
         deliveredDeferredChunks += 1
       }
       if (deliveredDeferredChunks > 0) {
-        // Why: replay restores the viewport before these newer bytes parse;
-        // settle the bounded deferred slice, then apply the latest user intent.
+        // Why: replay restores the viewport before these newer bytes parse; settle the deferred slice, then apply the latest user intent.
         flushTerminalOutput(pane.terminal, { maxChars: MAX_DEFERRED_REATTACH_LIVE_CHARS })
         void waitForTerminalReplayWritesParsed(pane.terminal).then(() => {
           if (
@@ -7281,9 +7104,7 @@ export function connectPanePty(
         result && typeof result === 'object' && 'id' in result ? (result as PtyConnectResult) : null
 
       if (connectResult?.exitedBeforeAttach) {
-        // Why: the transport already delivered the dead session's final frame
-        // and exit. Treat it as terminal state, not a failed reattach that
-        // should silently replace a cancelled pinned exit with a fresh shell.
+        // Why: the transport already delivered the dead session's final frame + exit; treat as terminal state, not a failed reattach.
         return true
       }
 
@@ -7297,8 +7118,7 @@ export function connectPanePty(
           paneId: pane.id,
           ptyId: staleSessionId ?? null
         })
-        // Why: a stale restored daemon/SSH session can fail reattach after the
-        // pane is mounted. Do not leave xterm alive without a backing PTY.
+        // Why: a stale restored session can fail reattach after mount; don't leave xterm alive without a backing PTY.
         if (staleSessionId) {
           deps.clearExitedPanePtyLayoutBinding(pane.id, staleSessionId)
         } else {
@@ -7329,9 +7149,7 @@ export function connectPanePty(
         if (staleSessionId) {
           deps.clearTabPtyId(deps.tabId, staleSessionId)
         }
-        // Why: SSH sleep/reconnect can invalidate the relay-held PTY while
-        // leaving the tab mounted. Replace the dead lease in-place instead of
-        // stranding the pane behind a stale expired-session overlay.
+        // Why: SSH sleep/reconnect can invalidate the relay PTY while the tab stays mounted; replace the dead lease in-place, not a stale overlay.
         startFreshColdRestoreAgentResume(coldRestoreStartup, {
           forceBlankRestoredViewport: true
         })
@@ -7355,22 +7173,10 @@ export function connectPanePty(
       agentCompletionCoordinator.startProcessTracking()
       sampleVisiblePaneForegroundAgent()
 
-      // Why: mobile terminal streaming needs the exact screen state from
-      // xterm.js. The shared helper installs both the SerializeAddon-backed
-      // serializer and the onTitleChange-driven lastTitle source so the
-      // main-process hydration path has full status parity.
+      // Why: mobile streaming needs xterm's exact screen state; install the serializer + lastTitle source for main-process hydration parity.
       registerPaneSerializerFor(ptyId)
 
-      // Strict precedence: snapshot > replay > coldRestore. Paint exactly
-      // one source per reattach. Painting snapshot AND replay produced the
-      // duplicated TUI output users saw on worktree switch (the relay replay
-      // buffer's tail typically overlaps with the daemon snapshot's tail, so
-      // both writing into xterm doubles the same lines). Snapshot wins
-      // because the daemon's authoritative buffer is freshest when present;
-      // replay wins over coldRestore because the relay's last 100 KB is
-      // newer than disk-recorded scrollback. If we ever return all three,
-      // the daemon and relay are by definition tracking the same session
-      // and only the freshest source belongs on screen.
+      // Strict precedence snapshot > replay > coldRestore: paint exactly one, else overlapping tails duplicate TUI output on worktree switch.
       const hasStructuralReplay = Boolean(
         connectResult?.snapshot || connectResult?.replay || connectResult?.coldRestore
       )
@@ -7381,13 +7187,7 @@ export function connectPanePty(
         }
         if (connectResult?.snapshot) {
           rememberReattachPayloadAgentSignal(connectResult.snapshot, { fullScreenReplay: true })
-          // Why: the daemon serializes its grid with soft-wrapped lines as
-          // continuous text. Replaying that at a different column count rewraps
-          // rows one cell early/late (bug #7279). Replay at the snapshot's own
-          // dimensions first; safeFit below fits the pane back and resizes the
-          // remote PTY. Suppress the xterm->PTY forward so this layout-only
-          // resize does not SIGWINCH the live remote TUI. Mirrors
-          // applyMainBufferSnapshot.
+          // Why: replay at the snapshot's own dimensions to avoid rewrapping soft-wrapped rows at a different column count (#7279); suppress the PTY forward so this layout-only resize doesn't SIGWINCH the remote TUI.
           const snapshotCols = connectResult.snapshotCols
           const snapshotRows = connectResult.snapshotRows
           const hasSnapshotDimensions =
@@ -7409,39 +7209,27 @@ export function connectPanePty(
             }
           }
           writeReplayData('\x1b[2J\x1b[3J\x1b[H')
-          // Why: the daemon snapshot's rehydrate preamble carries the live
-          // session's kitty keyboard flags; re-arm the mirror from it so Option
-          // chords keep their kitty encoding after a window reload.
+          // Why: re-arm the kitty keyboard mirror from the snapshot preamble so Option chords keep their encoding after a window reload.
           kittyKeyboardModes.scanReplay(connectResult.snapshot)
           writeReplayData(connectResult.snapshot)
-          // Snapshot reattach keeps a live session, so avoid the broader mode
-          // reset. We only drop renderer-owned state that should not leak from
-          // replay bytes into the restored renderer terminal.
+          // Snapshot reattach keeps a live session, so drop only renderer-owned state instead of the broader mode reset.
           writeReplayData(reattachReplayResetSequence(connectResult.snapshot))
           if (connectResult.pendingEscapeTailAnsi) {
-            // Why last: re-arm the daemon's dangling mid-escape sequence AFTER the
-            // reset (whose ESC would abort it) so the racing live continuation
-            // completes it instead of rendering literally (#7329).
+            // Why last: re-arm the dangling mid-escape after the reset (whose ESC would abort it) so the live continuation completes it (#7329).
             writeReplayData(connectResult.pendingEscapeTailAnsi)
           }
           sendFocusedReattachFocusInAfterReplay(ptyId, attemptGeneration)
           if (connectResult.coldRestore) {
-            // Snapshot superseded the cold-restore payload — ack it so the
-            // daemon does not redeliver it on the next reattach.
+            // Snapshot superseded the cold-restore payload; ack so the daemon doesn't redeliver it.
             if (!isRemoteRuntimePtyId(ptyId)) {
               window.api.pty.ackColdRestore(ptyId)
             }
           }
         } else if (connectResult?.replay) {
           rememberReattachPayloadAgentSignal(connectResult.replay, { fullScreenReplay: true })
-          // Relay replay holds the last 100 KB of raw output. The xterm may
-          // already hold pre-disconnect content; clear first to avoid
-          // duplication. The reattach reset clears renderer-owned state without
-          // tearing down the still-running TUI's live modes.
+          // Relay replay may overlap xterm's pre-disconnect content; clear first to avoid duplication.
           writeReplayData('\x1b[2J\x1b[3J\x1b[H')
-          // Why: raw relay replay contains the application's own kitty pushes
-          // when they fall inside the retained window; re-arm the mirror with
-          // replay (set) semantics so redelivery cannot grow the stack.
+          // Why: raw relay replay may contain the app's own kitty pushes; re-arm with set semantics so redelivery can't grow the stack.
           kittyKeyboardModes.scanReplay(connectResult.replay)
           writeReplayData(connectResult.replay)
           writeReplayData(reattachReplayResetSequence(connectResult.replay))
@@ -7465,8 +7253,7 @@ export function connectPanePty(
           } catch {
             // The current xterm grid remains a safe lower bound for blanking.
           }
-          // Why: shrinking first would promote clipped stale viewport rows into
-          // scrollback, beyond the reach of a later viewport-only clear.
+          // Why: shrinking first would promote clipped stale viewport rows into scrollback, beyond the reach of a later viewport-only clear.
           writeReplayData('\x1b[2J\x1b[H')
           await waitForTerminalReplayWritesParsed(pane.terminal)
           if (!isCurrentReattachPayload()) {
@@ -7485,8 +7272,7 @@ export function connectPanePty(
             hasColdRestoreDimensions &&
             (pane.terminal.cols !== coldRestoreCols || pane.terminal.rows !== coldRestoreRows)
           ) {
-            // Why: recovered ANSI cursor positions belong to the checkpoint's
-            // grid. Keep this layout-only resize from reaching the fresh PTY.
+            // Why: recovered ANSI cursor positions belong to the checkpoint's grid; keep this layout-only resize from reaching the fresh PTY.
             suppressStructuralReplayPtyResize = true
             try {
               pane.terminal.resize(coldRestoreCols, coldRestoreRows)
@@ -7494,10 +7280,7 @@ export function connectPanePty(
               suppressStructuralReplayPtyResize = false
             }
           }
-          // replayIntoTerminal: the recorded scrollback is raw PTY output that
-          // may contain query sequences the previous agent CLI emitted;
-          // writing them through xterm.write would trigger auto-replies that
-          // land in the new shell's stdin. See replay-guard.ts.
+          // Why: recorded scrollback is raw PTY output that may hold query sequences; xterm.write would auto-reply into the new shell's stdin. See replay-guard.ts.
           writeReplayData(connectResult.coldRestore.scrollback)
           const preparedStartup = coldRestoreStartup ?? buildColdRestoreAgentResumeStartup()
           const didPrepareResume = applyColdRestoreAgentResumeStartup(preparedStartup)
@@ -7507,17 +7290,12 @@ export function connectPanePty(
             }
             clearSleepingRecordAfterColdRestoreSpawn(preparedStartup)
           }
-          // Cold-restore means the daemon lost the session and spawned a
-          // fresh shell — no TUI is consuming the mode-setting bytes that a
-          // crashed TUI (e.g. Claude's \e[?1004h) left in the scrollback, so
-          // reset them to match the fresh shell's expectations.
+          // Why: cold-restore spawned a fresh shell; reset mode bytes a crashed TUI (e.g. Claude's \e[?1004h) left in scrollback that no live TUI now consumes.
           writeReplayData(POST_REPLAY_MODE_RESET)
-          // Why: the dead run's scrollback was never scanned, and any kitty
-          // flags it pushed died with it — the fresh shell starts at zero.
+          // Why: the dead run's kitty flags died with it and its scrollback was never scanned — the fresh shell starts at zero.
           kittyKeyboardModes.reset()
           consumeRestoredViewportBlankingMarker()
-          // Why: a taller destination fit must not pull recovered rows back
-          // into the fresh shell's viewport after source-grid replay.
+          // Why: a taller destination fit must not pull recovered rows back into the fresh shell's viewport after source-grid replay.
           writeFreshShellViewportBlanking(Math.max(destinationRows, pane.terminal.rows))
           if (!isRemoteRuntimePtyId(ptyId)) {
             window.api.pty.ackColdRestore(ptyId)
@@ -7556,9 +7334,7 @@ export function connectPanePty(
               if (reattachCols > 0 && reattachRows > 0) {
                 transport.resize(reattachCols, reattachRows)
               }
-              // Why: POSIX only delivers SIGWINCH when terminal dimensions actually
-              // change. Sending it explicitly guarantees restored TUIs repaint at
-              // the correct cursor position after snapshot replay.
+              // Why: POSIX only sends SIGWINCH on an actual dimension change; signal explicitly so restored TUIs repaint at the correct cursor after replay.
               if (!isRemoteRuntimePtyId(reattachPtyId)) {
                 window.api.pty.signal(reattachPtyId, 'SIGWINCH')
               }
@@ -7575,8 +7351,7 @@ export function connectPanePty(
             }
           }
           if (fitCompleted && isCurrentReattachPayload() && deps.isVisibleRef.current) {
-            // Why: reattach resize is fire-and-forget; verify the provider's
-            // applied grid while this reveal still owns the visible pane.
+            // Why: reattach resize is fire-and-forget; verify the provider's applied grid while this reveal still owns the visible pane.
             ptySizeReassertion.request({ fit: false })
           }
         } else if (isCurrentReattachPayload() && !isRemoteRuntimePtyId(reattachPtyId)) {
@@ -7601,21 +7376,12 @@ export function connectPanePty(
       return true
     }
 
-    // Why: if this tab has a deferred SSH session ID, trigger the SSH
-    // connection now that the user has focused the tab. We check per-tab
-    // (not per-target) because multiple tabs for the same target each need
-    // to reattach independently. This must run before session ID resolution
-    // because the SSH provider isn't registered until after connect succeeds.
+    // Why: trigger the deferred SSH connect per-tab (not per-target) so multiple tabs for one target reattach independently.
+    // Must run before session-id resolution: the SSH provider isn't registered until connect succeeds.
     if (connectionId) {
       const storeState = useAppStore.getState()
-      // Why: the SSH target was removed entirely (a ghost workspace). Reattaching
-      // can only fail with "SSH target not found", which surfaces a red "file an
-      // issue" banner for what is an expected user action. Skip reattach — the
-      // terminal overlay already shows a "host removed" state with a remove
-      // action. Runtime-owned targets aren't user-managed, so they're exempt.
-      // A target map that exists but omits this id means the target was removed.
-      // (Guard the map's presence for minimal test stubs that omit it; an absent
-      // map is "not hydrated", not "target gone".)
+      // Why: a removed SSH target (ghost workspace) would fail reattach with a spurious "file an issue" banner for an expected action, so skip it (runtime-owned targets exempt).
+      // A present map missing this id = target removed; an absent map = not yet hydrated (test stubs), so don't treat it as gone.
       if (
         !isRuntimeOwnedSshTargetId(connectionId) &&
         storeState.sshTargetLabels instanceof Map &&
@@ -7645,14 +7411,8 @@ export function connectPanePty(
       )
       if (gate.enterDeferredFlow) {
         void (async () => {
-          // Why: if the target requires a passphrase/password and no credential
-          // is cached yet, auto-firing ssh.connect would surprise the user —
-          // a prompt pops unprompted just because they focused a tab / jumped
-          // via Cmd+J. Wait for the user to initiate the connect (via
-          // SshDisconnectedDialog → passphrase dialog) before proceeding with
-          // the PTY reattach. No-passphrase targets (ssh-agent, unencrypted
-          // key, cached creds) return false here and continue auto-connecting
-          // as before.
+          // Why: for a passphrase target with no cached credential, don't auto-fire ssh.connect — a prompt popping just from focusing a tab / Cmd+J would surprise the user.
+          // Wait for a user-initiated connect first; no-passphrase targets return false here and auto-connect as before.
           let needsPrompt = false
           try {
             needsPrompt = await window.api.ssh.needsPassphrasePrompt({
@@ -7660,9 +7420,7 @@ export function connectPanePty(
             })
           } catch (err) {
             console.warn('[pty-connection] needsPassphrasePrompt probe failed:', err)
-            // Why: if the probe fails, fall through to the existing auto-connect
-            // behavior rather than stranding the tab — a stuck tab is worse
-            // than a surprising prompt.
+            // Why: on probe failure fall through to auto-connect rather than stranding the tab — a stuck tab is worse than a surprising prompt.
           }
           if (disposed) {
             return
@@ -7671,20 +7429,11 @@ export function connectPanePty(
             const alreadyConnected =
               useAppStore.getState().sshConnectionStates.get(connectionId)?.status === 'connected'
             if (!alreadyConnected) {
-              // Wait for the user-driven connect (SshDisconnectedDialog →
-              // passphrase dialog → ssh.connect) to complete, then continue.
-              // Why: resolve on terminal-failure statuses too ('auth-failed',
-              // 'error', 'reconnection-failed') so this promise can't hang
-              // forever if the user cancels or the connect fails —
-              // waitForSshConnection below has its own error path that will
-              // surface the failure via reportError.
+              // Wait for the user-driven connect (SshDisconnectedDialog → passphrase → ssh.connect) to complete.
+              // Why: resolve on terminal-failure statuses too ('auth-failed'/'error'/'reconnection-failed') so it can't hang forever if the user cancels or the connect fails.
               const outcome = await new Promise<UserInitiatedSshConnectOutcome>((resolve) => {
-                // Why: 'disconnected' counts as terminal only after we've
-                // observed a non-disconnected status — i.e. the user actually
-                // initiated a connect attempt that returned to 'disconnected'
-                // (cancel/dismiss). Treating the entry-time 'disconnected'
-                // as terminal would skip the gate entirely, defeating the
-                // passphrase-prompt deferral.
+                // Why: 'disconnected' counts as terminal only after a non-disconnected status was seen (a real connect attempt that returned to 'disconnected').
+                // Treating the entry-time 'disconnected' as terminal would skip the gate, defeating the passphrase-prompt deferral.
                 let sawNonDisconnected =
                   useAppStore.getState().sshConnectionStates.get(connectionId)?.status !==
                     'disconnected' &&
@@ -7705,12 +7454,8 @@ export function connectPanePty(
                   resolve(resolvedOutcome)
                 }
                 const teardown = (): void => finish('cancelled')
-                // Why: registering a teardown lets dispose() actively
-                // unsubscribe + resolve if the pane is torn down while the
-                // wait is in flight. Without this the zustand subscriber and
-                // the surrounding async IIFE leak for the rest of the app
-                // session because the callback only checks `disposed` when
-                // it next fires — and it may never fire again.
+                // Why: register a teardown so dispose() can unsubscribe+resolve if the pane is torn down mid-wait.
+                // Else the zustand subscriber + async IIFE leak: the callback only checks `disposed` when it next fires, which may never happen.
                 waitTeardowns.push(teardown)
                 const unsub = useAppStore.subscribe((state) => {
                   if (disposed) {
@@ -7726,10 +7471,7 @@ export function connectPanePty(
                     finish(nextOutcome)
                   }
                 })
-                // Why: re-read state immediately after subscribing to close the
-                // race where status transitioned between the alreadyConnected
-                // check above and the subscribe registration — otherwise we'd
-                // wait forever for a state change that already happened.
+                // Why: re-read state after subscribing to catch a status change that landed between the alreadyConnected check and the subscribe — else we'd wait forever.
                 if (disposed) {
                   finish('cancelled')
                   return
@@ -7758,9 +7500,7 @@ export function connectPanePty(
             }
           }
 
-          // Why: ensure the SSH connection is established before attempting
-          // PTY reattach. Multiple panes/tabs may need the same connection,
-          // so we wait for it rather than returning early when in-flight.
+          // Why: wait for the shared SSH connection (multiple panes/tabs may need it) before PTY reattach, rather than returning early when it's in-flight.
           const connectResult = await waitForSshConnection(connectionId)
           if (!connectResult.connected) {
             reportError(`SSH connection failed: ${connectResult.error}`)
@@ -7777,14 +7517,10 @@ export function connectPanePty(
             console.warn(
               `[pty-connection] Attempting reattach for tab=${deps.tabId} sessionId=${pendingSessionId}`
             )
-            // Why: the saved remote PTY ID is single-use restore metadata.
-            // Clear it before attach/fallback so remounts don't keep retrying
-            // an expired session after a fresh shell has been created.
+            // Why: the saved remote PTY id is single-use restore metadata; clear it before attach so remounts don't keep retrying an expired session.
             useAppStore.getState().removeDeferredSshSessionId(deps.tabId)
-            // Why: pre-signal also for SSH-deferred reattach so the
-            // cooperation gate uniformly applies to remote sessions. Issue
-            // declare and connect back-to-back; Electron preserves order. See
-            // docs/mobile-prefer-renderer-scrollback.md.
+            // Why: pre-signal SSH-deferred reattach too so the cooperation gate applies uniformly to remote sessions (Electron preserves the declare→connect order).
+            // See docs/mobile-prefer-renderer-scrollback.md.
             const preSignalPromise =
               runtimeEnvironmentId || isRemoteRuntimePtyId(pendingSessionId)
                 ? Promise.resolve(null)
@@ -7915,9 +7651,7 @@ export function connectPanePty(
       }
     }
 
-    // Why: re-read session IDs inside the rAF instead of capturing before.
-    // The session could be cleaned up during the one-frame gap, and
-    // reading stale IDs would cause a reattach to a dead session.
+    // Why: re-read session IDs inside the rAF — cleanup during the one-frame gap could otherwise reattach a dead session.
     const restoredPtyId =
       deps.restoredLeafId && deps.restoredPtyIdByLeafId
         ? (deps.restoredPtyIdByLeafId[deps.restoredLeafId] ?? null)
@@ -7928,8 +7662,7 @@ export function connectPanePty(
     )?.ptyId
     const hasSleepingAgentSession = Boolean(getSleepingRecordForPane(storeSnapshot))
 
-    // Why: a setup sibling can publish its PTY while the main pane waits for split geometry;
-    // the tab-level fallback must not steal a PTY already owned by that sibling transport.
+    // Why: the tab-level fallback must not steal a PTY a setup sibling already published while the main pane waited for split geometry.
     const tabFallbackPtyId =
       existingPtyId &&
       !Array.from(deps.paneTransportsRef.current.entries()).some(
@@ -7973,23 +7706,16 @@ export function connectPanePty(
       !isRemoteRuntimePtyId(candidateReattachSessionId) &&
       getEagerPtyBufferHandle(candidateReattachSessionId)
     )
-    // Why: a still-live locally-spawned PTY (e.g. a background automation agent
-    // launched before its tab mounts) keeps an eager buffer until a pane adopts
-    // it. Such a PTY must be adopted via attach()+replay, not re-connected as a
-    // daemon session — connect({ sessionId }) on a non-session ptyId spawns a
-    // fresh shell and orphans the live agent. Presence of an eager buffer plus
-    // current-tab live ownership is the discriminator; route these to attach.
+    // Why: a still-live locally-spawned PTY (e.g. a background automation agent) keeps an eager buffer until a pane adopts it.
+    // It must be adopted via attach()+replay — connect({ sessionId }) on its non-session ptyId would spawn a fresh shell and orphan the agent.
     const eagerLivePtyId =
       candidateReattachSessionId &&
       candidateHasEagerBuffer &&
       currentTabLivePtyIds.includes(candidateReattachSessionId)
         ? candidateReattachSessionId
         : null
-    // Why: daemon session IDs encode `${worktreeId}@@${uuid}`. After a daemon
-    // crash + cold restore, corrupted or stale session-to-tab mappings can
-    // cause a tab in workspace A to hold a ptyId from workspace B. Restoring
-    // that session would paint the wrong terminal content in this pane. Drop
-    // the reattach and spawn a fresh session instead.
+    // Why: after a daemon crash + cold restore, a stale session-to-tab mapping can make a tab hold a ptyId from another worktree.
+    // Restoring it would paint the wrong terminal content, so drop the reattach and spawn fresh.
     const deferredReattachSessionId =
       candidateReattachSessionId &&
       !isRemoteRuntimePtyId(candidateReattachSessionId) &&
@@ -8005,14 +7731,8 @@ export function connectPanePty(
       allowInitialIdleCacheSeed = true
       recordPtyConnectDiagnostic(`pane=${pane.id} -> REATTACH ${deferredReattachSessionId}`)
 
-      // Why: reattach also pre-signals so the cooperation gate suppresses
-      // the daemon seed for this paneKey. Reattach paths register their
-      // serializer in handleReattachResult (via registerPaneSerializerFor),
-      // mirroring the fresh-spawn path. We issue declare and the reattach
-      // connect back-to-back without awaiting; Electron's ipcRenderer→ipcMain
-      // channel preserves order. See
-      // docs/mobile-prefer-renderer-scrollback.md (Renderer-side prerequisite
-      // requirement #4).
+      // Why: pre-signal (declare) before the reattach connect so the cooperation gate suppresses the daemon seed for this paneKey; Electron preserves IPC order.
+      // See docs/mobile-prefer-renderer-scrollback.md (Renderer-side prerequisite requirement #4).
       const preSignalPromise =
         runtimeEnvironmentId || isRemoteRuntimePtyId(deferredReattachSessionId)
           ? Promise.resolve(null)
@@ -8134,24 +7854,13 @@ export function connectPanePty(
           })
         })
     } else if (detachedRemoteLeafPtyId || detachedLivePtyId || eagerLivePtyId) {
-      // Why: mirrored web terminal layouts mount one pane per host leaf.
-      // Later leaves already have a pane transport, but must still attach to
-      // their exact remote PTY instead of spawning replacement host tabs.
-      // eagerLivePtyId covers a still-live background PTY (e.g. an automation
-      // agent) whose restored id may not equal the tab ptyId yet still has a
-      // live eager buffer to adopt.
+      // Why: mirrored web-leaf panes must attach to their exact remote PTY, not spawn a replacement host tab.
+      // eagerLivePtyId covers a still-live background PTY (e.g. an automation agent) with a live eager buffer to adopt.
       const attachPtyId = detachedRemoteLeafPtyId ?? detachedLivePtyId ?? eagerLivePtyId!
       recordPtyConnectDiagnostic(`pane=${pane.id} -> ATTACH detached=${attachPtyId}`)
       allowInitialIdleCacheSeed = false
-      // Why: surface synchronous attach failures (e.g., the PTY died between
-      // mount and remount, so window.api.pty.resize rejects) through
-      // reportError so the pane shows a diagnostic instead of silently
-      // leaving a blank surface. The deferred-reattach branch above uses
-      // `.catch(reportError)` for the same reason. Commit the pane/tab
-      // bindings only after attach returns: if attach throws, the stale
-      // ptyId must also be cleared from the tab and a fresh spawn kicked
-      // off — otherwise the next remount reads the same dead ptyId from
-      // the store and lands in this branch again in a loop.
+      // Why: surface synchronous attach failures via reportError so the pane shows a diagnostic instead of a blank surface.
+      // On throw, clear the stale ptyId from the tab and fresh-spawn — else the next remount reads the same dead id and loops here.
       try {
         clearPaneMode2031State()
         clearHiddenOutputRestoreState()
@@ -8189,11 +7898,8 @@ export function connectPanePty(
               return
             }
             if (!spawnedPtyId) {
-              // Why: React StrictMode in dev can mount, start a spawn, then
-              // immediately unmount/remount the pane. If the first mount never
-              // produced a usable PTY ID, the remounted pane must issue its own
-              // spawn instead of staying attached to a completed-but-empty
-              // promise and rendering a dead terminal surface.
+              // Why: React StrictMode can mount+spawn then immediately remount; if the first mount produced no PTY id,
+              // the remounted pane must issue its own spawn instead of attaching to a completed-but-empty promise (a dead surface).
               if (!isWebTerminalSurfaceTabId(deps.tabId)) {
                 console.warn(
                   `Pending PTY spawn for tab ${deps.tabId} resolved without a PTY id, retrying fresh spawn`
@@ -8216,8 +7922,7 @@ export function connectPanePty(
               callbacks: outputCallbacks.callbacks
             })
             const attachedPtyId = transport.getPtyId() ?? spawnedPtyId
-            // Why: this path reuses a PTY spawned by an earlier mount, so no
-            // later spawn event will bind this remounted pane's DOM/container.
+            // Why: this reuses a PTY spawned by an earlier mount, so no later spawn event will bind this remounted pane's DOM/container.
             bindActivePanePty(attachedPtyId, {
               updateTabPtyId: 'if-missing',
               sampleVisibleForegroundAgent: true
@@ -8238,17 +7943,12 @@ export function connectPanePty(
     scheduleRuntimeGraphSync()
   }
 
-  // Why: Wayland/CI compositors can keep timers and CDP responsive while the
-  // next rAF never arrives; the terminal must still start its PTY once.
+  // Why: Wayland/CI compositors can starve rAF while timers/CDP stay responsive; the terminal must still start its PTY once.
   connectFallbackTimer = setTimeout(runDeferredConnect, 250)
   connectFrame = requestAnimationFrame(runDeferredConnect)
 
-  // Why: on visibility resume a pane may still be bound to a daemon session
-  // reaped while hidden (the missed-exit defect). Route it through the SAME
-  // teardown a real onExit runs. Re-validate identity at apply time so a
-  // reattach racing the listSessions snapshot is never clobbered, and respect
-  // the remote/SSH guards. Suppression semantics come for free via onExit
-  // (which consults consumeSuppressedPtyExit) plus the per-ptyId guard above.
+  // Why: on visibility resume a pane may still be bound to a session reaped while hidden (missed-exit defect); route through onExit's teardown,
+  // re-validating identity at apply time so a reattach racing the listSessions snapshot isn't clobbered.
   const reconcileIfSessionDead = (
     liveSessionIds: Set<string>,
     snapshotRequestedAt?: number
@@ -8259,8 +7959,7 @@ export function connectPanePty(
     const currentPtyId = transport.getPtyId()
     if (
       !currentPtyId ||
-      // Why: the current ptyId's exit was already handled — onExit guards this
-      // too, but skipping here avoids a redundant shouldReconcile evaluation.
+      // Why: this exit was already handled — onExit guards it too, but skipping here avoids a redundant shouldReconcile evaluation.
       handledExitPtyId === currentPtyId ||
       !shouldReconcileDeadSession({
         ptyId: currentPtyId,
@@ -8324,24 +8023,20 @@ export function connectPanePty(
   return {
     syncProcessTracking() {
       agentCompletionCoordinator.startProcessTracking()
-      // Why: the lifecycle hook calls this on every pane visibility flip —
-      // the hidden-delivery gate must follow the same transitions.
+      // Why: the hidden-delivery gate must follow every pane visibility flip.
       syncHiddenRendererPtyDelivery()
     },
     isHiddenDeliveryGateManagedPty() {
       return isHiddenDeliveryGateManagedPty(transport.getPtyId())
     },
-    // Why: called from the lifecycle visibility effect so the visible-resume
-    // size readback can repair dropped hidden resizes without refitting against
-    // xterm's transient hidden DOM fallback.
+    // Why: visible-resume size readback repairs dropped hidden resizes without refitting against xterm's transient hidden DOM fallback.
     noteVisibilityResume() {
       ptySizeReassertion.request({ fit: false })
       consumeHibernatedAgentWake()
       requestKnownDroidReconfirmation()
       sampleVisiblePaneForegroundAgent()
     },
-    // Why: mobile wake reaches this pane while it stays hidden on the desktop, so
-    // it must consume only the armed hibernation wake — no size/foreground reads.
+    // Why: mobile wake reaches this pane while it's hidden on the desktop, so consume only the armed hibernation wake — no size/foreground reads.
     wakeHibernatedAgentIfArmed(claimedProviderSessions) {
       if (hibernatedWakeInFlightClaimKey) {
         if (claimedProviderSessions?.has(hibernatedWakeInFlightClaimKey)) {
@@ -8354,10 +8049,8 @@ export function connectPanePty(
       if (consumedClaimKey) {
         return consumedClaimKey
       }
-      // Why: wake arrived mid-hibernation-kill — the record exists but onExit
-      // has not armed the wake target yet (the transport is still bound to the
-      // dying PTY). Only the exact PTY already marked for suppressed shutdown
-      // may latch; a stale/manual record beside an ordinary live PTY must not.
+      // Why: wake arrived mid-hibernation-kill before onExit armed the wake target (transport still bound to the dying PTY).
+      // Only the exact PTY marked for suppressed shutdown may latch — never a stale/manual record beside an ordinary live PTY.
       const state = useAppStore.getState()
       const recordEntry = getSleepingRecordForPane(state)
       const currentPtyId = transport.getPtyId()
@@ -8389,8 +8082,7 @@ export function connectPanePty(
       if (shiftEnterReconfirmTimer !== null) {
         clearTimeout(shiftEnterReconfirmTimer)
       }
-      // Why: preserve rapid multiline input inside a confirmed Droid composer;
-      // confirm only after the Shift+Enter burst goes idle.
+      // Why: confirm the Droid composer only after the Shift+Enter burst goes idle, to preserve rapid multiline input.
       shiftEnterReconfirmTimer = setTimeout(() => {
         shiftEnterReconfirmTimer = null
         requestKnownDroidReconfirmation()
@@ -8404,15 +8096,13 @@ export function connectPanePty(
       cancelPendingSafeFitContinuations(pane)
       pendingHiddenSnapshotFit = null
       pendingReattachFit = null
-      // A normal park/reconnect/remount does not advance the recovery epoch;
-      // invalidate this concrete xterm so its delayed retry cannot hit the next.
+      // Why: park/reconnect/remount doesn't advance the recovery epoch, so invalidate this xterm or its delayed retry could hit the next instance.
       terminalRecoveryInstance.unregister()
       unregisterUndeliverableWriteHandler()
       cancelHiddenOutputSnapshotScrollRestore()
       structuralReplayCoordinator.dispose()
       cancelFreshSpawnFollowReset()
-      // Why: the post-spawn reconcile polls across frames; cancel its pending
-      // rAF so a torn-down pane cannot keep fitting/resizing after disposal.
+      // Why: cancel the post-spawn reconcile's pending rAF so a torn-down pane can't keep fitting/resizing after disposal.
       ptySizeReconcileHandle?.cancel()
       ptySizeReconcileHandle = null
       startupGridSettleHandle?.cancel()
@@ -8422,8 +8112,7 @@ export function connectPanePty(
         cancelAnimationFrame(pendingForegroundGridDriftCheckRaf)
         pendingForegroundGridDriftCheckRaf = null
       }
-      // Why: a pane unmount (tab move, parking teardown) must never leave its
-      // PTY gated — the parked watcher or the remounted pane re-decides.
+      // Why: a pane unmount must never leave its PTY delivery gated — the parked watcher or remounted pane re-decides.
       releaseHiddenRendererPtyDelivery()
       if (terminalKeyTargetSupportsEvents) {
         terminalKeyTarget.removeEventListener('keydown', onTerminalKeyDown, { capture: true })
@@ -8437,9 +8126,7 @@ export function connectPanePty(
         clearTimeout(shiftEnterReconfirmTimer)
         shiftEnterReconfirmTimer = null
       }
-      // Why: actively resolve any in-flight passphrase-gate waits so their
-      // zustand subscribers + async IIFEs don't hang for the rest of the
-      // session when the pane is torn down before SSH state changes.
+      // Why: resolve in-flight passphrase-gate waits so their zustand subscribers + async IIFEs don't hang when the pane is torn down before SSH state changes.
       while (waitTeardowns.length > 0) {
         const teardown = waitTeardowns.pop()
         teardown?.()
@@ -8472,8 +8159,7 @@ export function connectPanePty(
       unregisterDocumentVisibilityRecovery?.()
       unregisterDocumentVisibilityRecovery = null
       releaseRendererPtyVisibilityClaim(transport)
-      // Why: a parked-tab watcher may take over this PTY's facts in the same
-      // effect flush; the pane's consumer must be gone before that handoff.
+      // Why: the pane's fact consumer must be gone before a parked-tab watcher takes over this PTY's facts in the same effect flush.
       dropSideEffectFactConsumer()
       clearPanePtyFitBinding()
       discardTerminalOutput(pane.terminal)
@@ -8487,10 +8173,7 @@ export function connectPanePty(
         unsubscribeWindowsDoneTerminalModeReset = null
       }
       if (connectFrame !== null) {
-        // Why: StrictMode and split-group remounts can dispose a pane binding
-        // before its deferred PTY attach/spawn work runs. Cancel that queued
-        // frame so stale bindings cannot reattach the PTY and steal the live
-        // handler wiring from the current pane.
+        // Why: cancel the queued connect frame so a disposed pane (StrictMode/split-group remount) can't reattach the PTY and steal the live pane's handler wiring.
         cancelScheduledConnectFrame()
       }
       if (connectFallbackTimer !== null) {
diff --git a/src/renderer/src/components/terminal-pane/pty-dispatcher-pi-routing.test.ts b/src/renderer/src/components/terminal-pane/pty-dispatcher-pi-routing.test.ts
index ae74fb79d34..e961329eb3c 100644
--- a/src/renderer/src/components/terminal-pane/pty-dispatcher-pi-routing.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-dispatcher-pi-routing.test.ts
@@ -1,8 +1,4 @@
-// Why: reproduce the renderer-level Pi spinner pipeline from the
-// `pty:data` IPC event all the way down to onTitleChange. The electron
-// verification showed spinner frames arrive via IPC but the store never sees
-// "⠋ Pi" — this file pins the integration between the singleton dispatcher
-// and the transport's per-pty handler.
+// Why: reproduce the renderer Pi spinner pipeline (pty:data IPC → onTitleChange); electron verification showed frames arrive but the store never sees "⠋ Pi".
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -18,9 +14,7 @@ function flushPtySideEffects(): Promise<void> {
 describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
   const originalWindow = (globalThis as { window?: typeof window }).window
 
-  // The singleton dispatcher subscribes a SINGLE global `window.api.pty.onData`
-  // callback on first `ensurePtyDispatcher()`. We simulate the main process
-  // delivering IPC events by invoking that captured callback directly.
+  // The singleton dispatcher subscribes one global onData callback; we capture it to simulate main delivering IPC events directly.
   let dispatcherCallback:
     | ((payload: { id: string; data: string; rawLength?: number; background?: boolean }) => void)
     | null = null
@@ -51,11 +45,7 @@ describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
                 background?: boolean
               }) => void
             ) => {
-              // Only the first subscriber wins in production — the dispatcher
-              // calls onData exactly once (ensurePtyDispatcher guards with the
-              // `ptyDispatcherAttached` flag). Subsequent transport calls go
-              // through the same cached subscription, so we capture the first
-              // one and ignore the rest.
+              // Only the first subscriber wins in production (ensurePtyDispatcher's ptyDispatcherAttached guard), so capture the first callback and ignore the rest.
               if (!dispatcherCallback) {
                 dispatcherCallback = cb
               }
@@ -97,10 +87,7 @@ describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
   })
 
   it('signals main that the pty:data listener is live exactly once per page load', async () => {
-    // Why: main holds every pty send until this handshake arrives, so a send that
-    // silently became a no-op (it is optional-chained) would pin the delivery gate
-    // until the 10s self-heal watchdog. Assert it fires, and fires only once — the
-    // second transport attach must not re-signal (ptyDispatcherAttached guard).
+    // Why: main gates all pty sends on this handshake, so a silent no-op would stall delivery until the 10s watchdog; assert it fires exactly once.
     const { ensurePtyDispatcher } = await import('./pty-dispatcher')
 
     ensurePtyDispatcher()
@@ -118,9 +105,7 @@ describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
 
     expect(dispatcherCallback).not.toBeNull()
 
-    // Simulate the main process firing `pty:data` IPC for pty-pi. The
-    // dispatcher looks up `ptyDataHandlers.get('pty-pi')` and calls it with
-    // the data — the same path exercised by a real Pi session.
+    // Simulate main firing pty:data IPC — dispatcher routes to ptyDataHandlers.get('pty-pi'), the same path a real Pi session uses.
     dispatcherCallback?.({ id: 'pty-pi', data: idleTitle() })
     dispatcherCallback?.({ id: 'pty-pi', data: workingFrame('⠋') })
     dispatcherCallback?.({ id: 'pty-pi', data: workingFrame('⠙') })
@@ -134,10 +119,7 @@ describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
   })
 
   it('pipeline survives a chunk carrying shell output interleaved with spinner frames', async () => {
-    // Why: node-pty batches at 8ms on the main side, so the renderer often
-    // sees multiple OSC sequences and body bytes in one chunk. The transport
-    // handler extracts the LAST OSC title in each chunk — working frames that
-    // land as the last title in any chunk must surface through onTitleChange.
+    // Why: node-pty's 8ms batching packs multiple OSC titles + body into one chunk; the handler takes the LAST title, which must still surface working frames.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const onTitleChange = vi.fn()
 
@@ -157,20 +139,14 @@ describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
   })
 
   it('attach()-flow pipeline delivers working frames to onTitleChange', async () => {
-    // Why: the reattach code path (daemon-backed or intra-session remount)
-    // calls transport.attach() instead of transport.connect(). If the handler
-    // registration drifted between the two paths, Pi sessions restored after
-    // a tab remount would stop emitting spinner signals — consistent with
-    // the electron-level observation where poll-sampled runtimePaneTitlesByTabId
-    // never flipped to "⠋ Pi" during a live working window.
+    // Why: reattach uses attach() not connect(); if handler registration drifted between them, remounted Pi sessions would stop emitting spinner signals.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const onTitleChange = vi.fn()
 
     const transport = createIpcPtyTransport({ onTitleChange })
     transport.attach({ existingPtyId: 'pty-pi', callbacks: {} })
 
-    // Eager-buffer replay in attach() can flush initial titles through the
-    // same handler; only assert about frames we push AFTER attach resolves.
+    // attach()'s eager-buffer replay can flush initial titles; only assert on frames pushed after attach resolves.
     onTitleChange.mockClear()
 
     dispatcherCallback?.({ id: 'pty-pi', data: workingFrame('⠋') })
@@ -183,10 +159,7 @@ describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
   })
 
   it('reproduces "Pi is idle" state: after working→idle, onTitleChange ends on Pi', async () => {
-    // Why: the user-visible bug is that the store shows "Pi" (idle) even
-    // during working — meaning intermediate "⠋ Pi" updates never landed OR
-    // they landed and were then overwritten and dedupe-filtered. Assert that
-    // BOTH labels reach onTitleChange during a working→idle cycle, in order.
+    // Why: bug shows the store stuck at idle "Pi" while working — assert both working and idle labels reach onTitleChange, in order.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const onTitleChange = vi.fn()
 
@@ -208,16 +181,7 @@ describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
     transport.disconnect()
   })
 
-  // Why: regression test for the cursor spinner "solid after 500ms" bug.
-  // cursor-agent re-emits its native `OSC 0: "Cursor Agent"` title on every
-  // internal redraw mid-turn. Orca's main process injects synthesized
-  // "⠋ Cursor Agent" spinner frames from the hook server; the renderer must
-  // drop cursor's bare native title so it cannot overwrite the synthesized
-  // working title in `runtimePaneTitlesByTabId` (which drives `getWorktreeStatus`'s
-  // solid/spinning dot decision). If the bare title leaked through, the last
-  // title in the store would flip to "Cursor Agent" (which `detectAgentStatusFromTitle`
-  // classifies as null / not-working) and the sidebar would snap solid
-  // mid-turn.
+  // Why: regression for cursor's "solid after 500ms" bug — cursor re-emits its bare native title mid-turn; it must not overwrite the synthesized spinner frame.
   it('drops cursor-agent native "Cursor Agent" title so it cannot overwrite the synthesized spinner', async () => {
     const { createIpcPtyTransport } = await import('./pty-transport')
     const onTitleChange = vi.fn()
@@ -225,9 +189,7 @@ describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
     const transport = createIpcPtyTransport({ onTitleChange })
     await transport.connect({ url: '', callbacks: {} })
 
-    // Simulate the realistic interleave: Orca injects a synthesized working
-    // frame, cursor-agent re-emits its bare native title shortly after, Orca
-    // injects the next spinner frame, etc.
+    // Realistic interleave: synthesized working frame, cursor's bare native title, next spinner frame, etc.
     dispatcherCallback?.({ id: 'pty-pi', data: `${ESC}]0;⠋ Cursor Agent${BEL}` })
     dispatcherCallback?.({ id: 'pty-pi', data: `${ESC}]0;Cursor Agent${BEL}` })
     dispatcherCallback?.({ id: 'pty-pi', data: `${ESC}]0;⠙ Cursor Agent${BEL}` })
@@ -235,8 +197,6 @@ describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
     await flushPtySideEffects()
 
     const seenTitles = onTitleChange.mock.calls.map((c) => c[0])
-    // The two bare "Cursor Agent" titles must NOT reach the title-change
-    // pipeline. The two synthesized spinner frames must.
     expect(seenTitles).not.toContain('Cursor Agent')
     expect(seenTitles).toContain('⠋ Cursor Agent')
     expect(seenTitles).toContain('⠙ Cursor Agent')
@@ -245,8 +205,7 @@ describe('dispatcher → transport → onTitleChange for Pi spinner', () => {
   })
 
   it('still surfaces the synthesized "Cursor ready" idle title after working', async () => {
-    // Why: make sure the bare-title drop does not accidentally catch the
-    // decorated "Cursor ready" done frame Orca synthesizes on the `stop` hook.
+    // Why: the bare-title drop must not also catch the decorated "Cursor ready" done frame Orca synthesizes on the stop hook.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const onTitleChange = vi.fn()
 
diff --git a/src/renderer/src/components/terminal-pane/pty-dispatcher.ts b/src/renderer/src/components/terminal-pane/pty-dispatcher.ts
index efc103531ba..7386797b4bb 100644
--- a/src/renderer/src/components/terminal-pane/pty-dispatcher.ts
+++ b/src/renderer/src/components/terminal-pane/pty-dispatcher.ts
@@ -1,10 +1,4 @@
-/**
- * Singleton PTY event dispatcher and eager buffer helpers.
- *
- * Why extracted: keeps pty-transport.ts under the 300-line limit while
- * co-locating the global handler maps that both the transport factory
- * and the eager-buffer reconnection logic share.
- */
+/** Singleton PTY event dispatcher and eager buffer helpers, split out from pty-transport.ts. */
 import { TERMINAL_SCROLLBACK_SESSION_BUFFER_BYTE_LIMIT } from '../../../../shared/terminal-scrollback-limits'
 import {
   clearProcessedPtyCharTotal,
@@ -30,41 +24,29 @@ import { recordTerminalFreezeBreadcrumb } from './terminal-freeze-breadcrumbs'
 import { installTerminalFreezeReport } from './terminal-freeze-report'
 
 // ── Singleton PTY event dispatcher ───────────────────────────────────
-// One global IPC listener per channel, routes events to transports by
-// PTY ID. Eliminates the N-listener problem that triggers
-// MaxListenersExceededWarning with many panes/tabs.
+// One global IPC listener per channel (routed by PTY ID) avoids the N-listener MaxListenersExceededWarning with many panes.
 
 export type PtyDataMeta = {
   seq?: number
   rawLength?: number
   transformed?: boolean
   background?: boolean
-  /** Main dropped this PTY's buffered output at the pending cap; the pane
-   *  must repaint from the main-owned snapshot instead of the live stream. */
+  /** Main dropped this PTY's buffered output at the pending cap; repaint from the main-owned snapshot, not the live stream. */
   droppedOutput?: boolean
 }
 
 export const ptyDataHandlers = new Map<string, (data: string, meta?: PtyDataMeta) => void>()
-/** Sidecar subscriptions that observe PTY data without owning the primary
- *  handler. Used by features that need to react to the live byte stream
- *  (e.g. agent-paste-draft watching for DECSET 2004 / bracketed-paste-
- *  enable). Sidecars are invoked AFTER the primary handler so xterm rendering
- *  is never delayed by a side-effect-only watcher. Each Set entry is one
- *  active subscription; removal is by Set.delete inside the unsubscribe fn. */
+/** Sidecar PTY-data observers, invoked AFTER the primary handler so a side-effect-only watcher can't delay xterm rendering. */
 export const ptyDataSidecars = new Map<string, Set<(data: string) => void>>()
 
-/** Per-PTY replay handlers for relay pty.attach replay data. Routed through
- *  a dedicated pty:replay IPC channel so the renderer can engage the replay
- *  guard and suppress xterm auto-replies during replay. */
+/** Per-PTY replay handlers on a dedicated pty:replay channel so the renderer can engage the replay guard and suppress xterm auto-replies. */
 export const ptyReplayHandlers = new Map<string, (data: string) => void>()
 export const ptyExitHandlers = new Map<string, (code: number) => void>()
 const ptyExitSidecars = new Map<
   string,
   Set<(code: number, context: { hadPrimary: boolean }) => void>
 >()
-/** Per-PTY teardown callbacks registered by each transport to clear closure
- *  state (stale-title timer, agent tracker) that would otherwise fire after
- *  the data handler is removed. */
+/** Per-PTY teardown callbacks that clear closure state which would otherwise fire after the data handler is removed. */
 export const ptyTeardownHandlers = new Map<string, () => void>()
 let ptyDispatcherAttached = false
 
@@ -76,14 +58,8 @@ export type PtyDataHandlerShutdownSnapshot = {
 }
 
 /**
- * Remove data and status handlers for the given PTY IDs so that any final
- * data flushed by the main process during PTY teardown cannot trigger
- * bell / agent-status notifications from a worktree that is being shut down.
- * Also invokes per-transport teardown callbacks to cancel accumulated closure
- * state (e.g. staleTitleTimer, agent tracker) that could independently fire
- * stale notifications.
- * Exit handlers are intentionally kept alive so the normal exit-cleanup
- * path (unregister, clear stale timers, update store) still runs.
+ * Remove data/replay/teardown handlers so teardown-flush data can't fire bell/agent-status
+ * notifications from a shutting-down worktree; exit handlers stay for the normal exit-cleanup path.
  */
 export function unregisterPtyDataHandlers(ptyIds: string[]): PtyDataHandlerShutdownSnapshot[] {
   const snapshots: PtyDataHandlerShutdownSnapshot[] = []
@@ -121,10 +97,7 @@ export function restorePtyDataHandlersAfterFailedShutdown(
 
 let pushListenerUnsubscribes: (() => void)[] = []
 
-/** Detach and freshly re-subscribe every push-channel listener. Called by the
- *  delivery watchdog on a confirmed wedge: if the listener was somehow
- *  detached this restores delivery outright; if the channel itself is dead
- *  it is a safe no-op (removeListener on a gone listener does nothing). */
+/** Detach and re-subscribe every push-channel listener; called by the delivery watchdog on a confirmed wedge. */
 export function reattachPtyDispatcherPushListeners(): void {
   recordTerminalFreezeBreadcrumb('push-listeners-reattach', {
     staleListenerCount: pushListenerUnsubscribes.length
@@ -155,8 +128,7 @@ function attachPtyPushListeners(): void {
   const unsubscribes = pushListenerUnsubscribes
   unsubscribes.push(
     window.api.pty.onData((payload) => {
-      // Why: e2e-only wedge simulation — the chunk vanishes exactly as in the
-      // field failure: no receive count, no ACK credit, no handler dispatch.
+      // Why: e2e-only wedge simulation — drop the chunk exactly like the field failure (no receive count, ACK, or dispatch).
       if (isPtyPushDeliveryBlackholed()) {
         return
       }
@@ -206,13 +178,7 @@ function handleDispatchedPtyData(payload: {
     }
     const sidecars = ptyDataSidecars.get(payload.id)
     if (sidecars && sidecars.size > 0) {
-      // Why: snapshot the Set before iterating because watchers commonly
-      // unsubscribe themselves on the very chunk that satisfies them
-      // (e.g. agent-paste-draft resolves on DECSET 2004 and immediately
-      // tears down). Iterating the live Set in that case can skip a
-      // watcher or — if a watcher synchronously subscribes a sibling —
-      // double-fire. The Set is never large (one watcher per active
-      // ready-wait), so the array allocation is cheap.
+      // Why: snapshot before iterating — watchers often unsubscribe (or subscribe siblings) mid-iteration, and mutating the live Set would skip or double-fire.
       const snapshot = Array.from(sidecars)
       for (const watcher of snapshot) {
         watcher(payload.data)
@@ -220,11 +186,7 @@ function handleDispatchedPtyData(payload: {
     }
   }
   recordPtyDataReceived(payload.id, chars)
-  // Why deferred: main budgets renderer-bound output by bytes PARSED, not
-  // bytes received. The handler's scheduler write claims this delivery's
-  // credit and fires it when xterm consumes the bytes; deliveries that never
-  // reach the scheduler (dropped, pre-mount eager buffer) settle at return —
-  // a bad sidecar still cannot leave a PTY permanently backpressured.
+  // Why deferred: main budgets by bytes PARSED not received; ACK fires when xterm consumes, and undelivered chunks settle at return so no PTY stays backpressured.
   deliverPtyDataWithDeferredAck(payload.id, chars, dispatch)
 }
 
@@ -236,8 +198,7 @@ function attachPtySecondaryPushListeners(unsubscribes: (() => void)[]): void {
   )
   unsubscribes.push(
     window.api.pty.onExit((payload) => {
-      // Why: main drops its delivery accounting for this pty on exit; drop the
-      // cumulative totals too so a reused id restarts at zero on both sides.
+      // Why: main drops its accounting on exit; drop totals too so a reused id restarts at zero on both sides.
       clearProcessedPtyCharTotal(payload.id)
       clearReceivedPtyCharTotal(payload.id)
       const sidecars = ptyExitSidecars.get(payload.id)
@@ -246,8 +207,7 @@ function attachPtySecondaryPushListeners(unsubscribes: (() => void)[]): void {
       }
       const primary = ptyExitHandlers.get(payload.id)
       if (primary) {
-        // Why: exit handlers are one-shot owners. Remove before invocation so
-        // a throwing callback cannot stay registered for a duplicate exit.
+        // Why: one-shot owner — remove before invoking so a throwing callback can't stay registered for a duplicate exit.
         ptyExitHandlers.delete(payload.id)
       }
       deliverPtyExitToHandlers({
@@ -258,9 +218,7 @@ function attachPtySecondaryPushListeners(unsubscribes: (() => void)[]): void {
       })
     })
   )
-  // Why: main probes when delivery looks stuck on lost ACKs (data arriving
-  // for a fully gated PTY). Replying with the cumulative processed totals
-  // lets main reconcile verified state instead of resetting blindly.
+  // Why: main probes on suspected lost ACKs; replying with processed totals lets it reconcile instead of resetting blindly.
   const unsubscribeResync = window.api.pty.onDeliveryResyncRequest?.((payload) => {
     window.api.pty.respondDeliveryResync?.({
       requestId: payload.requestId,
@@ -270,10 +228,7 @@ function attachPtySecondaryPushListeners(unsubscribes: (() => void)[]): void {
   if (unsubscribeResync) {
     unsubscribes.push(unsubscribeResync)
   }
-  // Why: tell main the pty:data listener is live now. Before this fires (fresh
-  // load or post-reload boot window) main holds all sends — bytes sent into a
-  // listener-less page are silently dropped yet counted in-flight, which
-  // permanently pins the delivery gate. Fires once per page load.
+  // Why: tell main the pty:data listener is live; until it fires, bytes to a listener-less page are dropped-but-counted and pin the delivery gate.
   window.api.pty.rendererDispatcherReady?.()
 }
 
@@ -301,9 +256,7 @@ export function subscribeToPtyExit(
 }
 
 // ─── Eager PTY buffer for reconnection on restart ────────────────────
-// Why: On startup, PTYs are spawned before TerminalPane mounts. Shell output
-// (prompt, MOTD) arrives via pty:data before xterm exists. These helpers buffer
-// that output so transport.attach() can replay it when the pane finally mounts.
+// Why: PTYs spawn before TerminalPane mounts; buffer the early shell output (prompt/MOTD) so attach() can replay it.
 
 export type EagerPtyHandle = { flush: () => string; dispose: () => void }
 const eagerPtyHandles = new Map<string, EagerPtyHandle>()
@@ -312,9 +265,7 @@ export function getEagerPtyBufferHandle(ptyId: string): EagerPtyHandle | undefin
   return eagerPtyHandles.get(ptyId)
 }
 
-// Why: 512 KB matches the scrollback buffer cap used by TerminalPane's
-// serialization. Prevents unbounded memory growth if a restored shell
-// runs a long-lived command (e.g. tail -f) in a worktree the user never opens.
+// Why: cap matches TerminalPane's scrollback serialization limit so a restored shell (e.g. tail -f) can't grow unbounded.
 const EAGER_BUFFER_MAX_BYTES = TERMINAL_SCROLLBACK_SESSION_BUFFER_BYTE_LIMIT
 
 export function registerEagerPtyBuffer(
@@ -322,15 +273,13 @@ export function registerEagerPtyBuffer(
   onExit: (ptyId: string, code: number) => void
 ): EagerPtyHandle {
   ensurePtyDispatcher()
-  // Why: a head index instead of Array.shift() — shift() is O(n), making
-  // pre-attach buffering quadratic under many small chunks. Compaction is deferred.
+  // Why: head index instead of Array.shift() (O(n)) so pre-attach buffering isn't quadratic under many small chunks.
   const chunks: EagerBufferChunk[] = []
   let head = 0
   let bufferBytes = 0
 
   const dataHandler = (data: string): void => {
-    // A single chunk larger than the cap would otherwise bypass trimming and
-    // store the whole payload; keep only its most-recent tail.
+    // Why: a single over-cap chunk would bypass the trim loop below; keep only its most-recent tail.
     const chunk = clampUtf8Tail(data, EAGER_BUFFER_MAX_BYTES)
     chunks.push(chunk)
     bufferBytes += chunk.bytes
@@ -347,10 +296,7 @@ export function registerEagerPtyBuffer(
     }
   }
   const exitHandler = (code: number): void => {
-    // Shell died before TerminalPane attached — clean up and notify the store
-    // so the tab's ptyId is cleared and connectPanePty falls through to connect().
-    // Identity-guarded like dispose(): never delete a handler a transport has
-    // since registered for this id (#7894 detach/attach remount race).
+    // Shell died before attach; identity-guard so we never evict a handler a transport re-registered for this id (#7894 detach/attach race).
     if (ptyDataHandlers.get(ptyId) === dataHandler) {
       ptyDataHandlers.delete(ptyId)
       ptyReplayHandlers.delete(ptyId)
@@ -375,10 +321,7 @@ export function registerEagerPtyBuffer(
       return data
     },
     dispose() {
-      // Why: dispose runs at pane attach (mount completed) — the pane's own
-      // visibility sync now owns the hidden-delivery decision for this PTY.
-      // Only remove if the current handler is still the temp one (compare by
-      // reference). After attach() replaces the handler this becomes a no-op.
+      // Why: identity-guard removal — after attach() swaps in its own handler this must no-op, not evict it.
       if (ptyDataHandlers.get(ptyId) === dataHandler) {
         ptyDataHandlers.delete(ptyId)
         ptyReplayHandlers.delete(ptyId)
@@ -392,9 +335,7 @@ export function registerEagerPtyBuffer(
 
   eagerPtyHandles.set(ptyId, handle)
   drainPreHandlerPtyData(ptyId, dataHandler)
-  // Why: launcher callbacks often capture the returned handle so they can
-  // flush output on exit. Defer a pre-handler exit by one microtask so the
-  // caller receives that handle before onExit fires.
+  // Why: defer the pre-handler exit one microtask so the caller receives the returned handle before onExit fires.
   queueMicrotask(() => {
     if (ptyExitHandlers.get(ptyId) === exitHandler) {
       drainPreHandlerPtyExit(ptyId, exitHandler)
diff --git a/src/renderer/src/components/terminal-pane/pty-size-reconcile.test.ts b/src/renderer/src/components/terminal-pane/pty-size-reconcile.test.ts
index 93ef1b29558..1d7a23153d7 100644
--- a/src/renderer/src/components/terminal-pane/pty-size-reconcile.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-size-reconcile.test.ts
@@ -6,16 +6,9 @@ import {
 } from './pty-size-reconcile'
 
 /**
- * Reproduction harness for the terminal column-desync bug (Slack: Claude Code
- * renders garbled when a new worktree is opened with the side split panel on).
- *
- * The PTY is spawned at the wide window width, then the split/sidebar layout
- * narrows the pane some frames LATER. The fix must converge the PTY to the
- * settled narrow width regardless of WHEN the layout lands — including a settle
- * that arrives well after any fixed frame budget (the prior fix used a fixed
- * 12-frame budget that expired before the split equalized). The reconcile keeps
- * polling while the pane is not yet authoritative (the hidden mount window where
- * the live onResize is dropped) and hands off once authoritative + stable.
+ * Reproduction harness for the terminal column-desync bug: the PTY spawns wide and the split/sidebar
+ * narrows the pane frames later, so the fix must converge to the settled narrow width whenever the
+ * layout lands (the prior fixed 12-frame budget expired early), watching while hidden until authoritative.
  */
 
 /** A deterministic frame scheduler: callbacks queue, then run() drains them. */
@@ -46,11 +39,7 @@ function createFrameScheduler() {
   }
 }
 
-/**
- * A pane whose measured grid follows a timeline keyed by frame index: it starts
- * unmeasurable (null) or wide, then narrows at some frame. `measure()` is called
- * once per reconcile frame, so the call count tracks frames elapsed.
- */
+/** A pane whose measured grid follows a frame-indexed timeline; `measure()` is called once per reconcile frame, so call count = frames elapsed. */
 function createTimelinePane(timeline: (frame: number) => PtySizeReconcileDimensions | null) {
   let frame = 0
   return {
@@ -73,8 +62,7 @@ function runReconcile(
     spawnRows: 50,
     isAlive: () => true,
     isParked: () => false,
-    // Default: pane is visible (the common case). Specific tests override this
-    // to model the hidden mount window where the live onResize is dropped.
+    // Default visible; specific tests override to model the hidden mount window where onResize is dropped.
     isAuthoritative: () => true,
     resize,
     requestFrame: scheduler.requestFrame,
@@ -87,11 +75,7 @@ function runReconcile(
 
 describe('reconcilePtySizeAcrossFrames', () => {
   it('forwards a narrow settle that lands AFTER a fixed 12-frame budget — while hidden', () => {
-    // Golden repro: the pane mounts hidden (onResize dropped — the desync
-    // window), spawned wide (203), still measuring wide for the first 15 frames
-    // (split equalize / sidebar reflow in flight), then settles to 79. A
-    // 12-frame-budget reconcile would have stopped at frame 12 — still wide,
-    // leaving the PTY pinned. The convergent loop keeps watching while hidden.
+    // Golden repro: hidden pane spawned wide, narrows at frame 15 — a 12-frame budget stops still-wide; the convergent loop keeps watching.
     const NARROW_AT = 15
     const pane = createTimelinePane((frame) =>
       frame < NARROW_AT ? { cols: 203, rows: 50 } : { cols: 79, rows: 50 }
@@ -103,11 +87,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
   })
 
   it('forwards a narrow settle that lands LATE while hidden — no fixed frame floor', () => {
-    // The bug the adversarial review caught: a fixed MIN-frames floor (e.g. 24)
-    // would treat the still-wide spawn measurement as "settled" and stop before
-    // the real narrowing lands. A split that equalizes at frame 40 while the
-    // pane is still hidden must STILL be forwarded — the loop watches until it
-    // becomes authoritative (where onResize takes over) or the hard cap.
+    // A fixed MIN-frames floor would falsely settle on the wide spawn before a late narrowing lands — watch until authoritative or the cap.
     const NARROW_AT = 40
     const pane = createTimelinePane((frame) =>
       frame < NARROW_AT ? { cols: 203, rows: 50 } : { cols: 79, rows: 50 }
@@ -119,10 +99,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
   })
 
   it('forwards a late settle that lands just before the pane becomes authoritative', () => {
-    // Realistic handoff: hidden through the settle, narrows at frame 40, then
-    // the pane becomes visible at frame 45. The reconcile must have already
-    // forwarded the narrow width during the hidden window (its resize bypasses
-    // the visibility gate); the later authoritative+stable state lets it stop.
+    // Forwards the narrow width while hidden (resize bypasses the visibility gate), then stops once authoritative+stable.
     const NARROW_AT = 40
     const AUTHORITATIVE_AT = 45
     let frameSeen = 0
@@ -140,28 +117,17 @@ describe('reconcilePtySizeAcrossFrames', () => {
   })
 
   it('hands off after the pane is visible+stable, leaving later reflows to the live onResize', () => {
-    // Handoff boundary (verified design): once the pane is authoritative AND the
-    // grid has been stable for the settle window, the live onResize /
-    // ResizeObserver path owns any FURTHER reflow (it fires on every
-    // grid-changing fit() and is not suppressed for a visible desktop pane). So
-    // the reconcile is allowed to stop here — a split that equalizes much later,
-    // after this handoff, is caught by that backstop, not by the reconcile. This
-    // pins that the reconcile terminates promptly in the steady visible state
-    // rather than polling to the hard cap. The narrow-while-hidden window (where
-    // onResize is dropped) is covered by the dedicated tests above.
+    // Once authoritative + stable, onResize owns further reflow, so the reconcile stops here (later splits hit that backstop).
     const pane = createTimelinePane(() => ({ cols: 79, rows: 50 }))
     const { resize, framesRun } = runReconcile({ measure: pane.measure })
     expect(resize).toHaveBeenCalledTimes(1)
     expect(resize).toHaveBeenLastCalledWith(79, 50)
-    // Frame 1 forwards the single change (resets the window); frames 2..9 are
-    // authoritative + unchanged, so the loop settles exactly at SETTLE_FRAMES(8)
-    // observed-stable frames — i.e. 9 frames total, far short of the 180 cap.
+    // Frame 1 forwards the change; frames 2..9 stable → settles at SETTLE_FRAMES(8), i.e. 9 total (far short of the 180 cap).
     expect(framesRun).toBe(9)
   })
 
   it('keeps polling through unmeasurable frames (pane has no layout yet)', () => {
-    // A fresh split mount can be unmeasurable for many frames before the real
-    // grid lands. Unmeasurable frames must NOT count as "settled".
+    // A fresh split mount can be unmeasurable for many frames — those frames must NOT count as "settled".
     const NARROW_AT = 20
     const pane = createTimelinePane((frame) => (frame < NARROW_AT ? null : { cols: 80, rows: 24 }))
     const { resize } = runReconcile({ measure: pane.measure })
@@ -171,8 +137,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
   })
 
   it('hands off (stops) once authoritative and the grid has been stable', () => {
-    // Once visible and stable, the live onResize owns future corrections; the
-    // reconcile should stop rather than poll to the hard cap forever.
+    // Once visible and stable, the live onResize owns future corrections, so the reconcile stops (no polling to the cap).
     const pane = createTimelinePane(() => ({ cols: 79, rows: 50 }))
     const { framesRun } = runReconcile({ measure: pane.measure })
     // Should settle a few frames after the single resize, well short of the cap.
@@ -181,8 +146,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
   })
 
   it('does NOT hand off while hidden — keeps watching until the hard cap', () => {
-    // While never authoritative, a stable grid is not a safe stopping point
-    // (onResize cannot back us up), so the loop runs to the hard cap.
+    // While never authoritative, a stable grid is no safe stop (onResize can't back us up), so it runs to the hard cap.
     const pane = createTimelinePane(() => ({ cols: 79, rows: 50 }))
     const { framesRun } = runReconcile({
       measure: pane.measure,
@@ -208,8 +172,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
   })
 
   it('issues only a couple of SIGWINCH for a monotonic narrow settle (not one per frame)', () => {
-    // 203 → 120 → 79 over the first frames, then stable. The TUI should see the
-    // size change a small, bounded number of times during its own startup.
+    // 203 → 120 → 79 then stable — the TUI should see a small, bounded number of size changes during startup.
     const pane = createTimelinePane((frame) => {
       if (frame < 5) {
         return { cols: 203, rows: 50 }
@@ -237,9 +200,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
   })
 
   it('resumes and converges after a transient park (mobile take-back during mount)', () => {
-    // Parked frames are SKIPPED, not cancelled: if mobile transiently drives the
-    // PTY during the mount window and then hands control back, the reconcile must
-    // resume and forward the settled desktop width — not abort permanently.
+    // Parked frames are SKIPPED, not cancelled — after a transient mobile take-over the reconcile must resume, not abort.
     const PARKED_UNTIL = 10
     let frameSeen = 0
     const pane = createTimelinePane(() => ({ cols: 79, rows: 50 }))
@@ -257,8 +218,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
       cancelFrame: scheduler.cancelFrame
     })
     scheduler.run()
-    // While parked, measure()/resize() are skipped; after take-back the desktop
-    // width is measured and forwarded exactly once.
+    // While parked, measure()/resize() are skipped; after take-back the desktop width is forwarded exactly once.
     expect(resize).toHaveBeenCalledTimes(1)
     expect(resize).toHaveBeenLastCalledWith(79, 50)
   })
@@ -313,13 +273,9 @@ describe('reconcilePtySizeAcrossFrames', () => {
     expect(scheduler.pending()).toBe(0)
   })
 
-  // Why: the grid being stable only proves what the loop SENT held steady, not
-  // what the PTY APPLIED. transport.resize is fire-and-forget for daemon/SSH
-  // PTYs, so the loop can settle on a size the PTY dropped — the mount-time twin
-  // of the resume drift. getAppliedSize lets the loop confirm before handing off.
+  // Why: resize is fire-and-forget for daemon/SSH PTYs, so a stable grid can hide a dropped size; getAppliedSize confirms before handoff.
   describe('applied-size verification before handoff', () => {
-    /** Drain frames, flushing microtasks between each so async getAppliedSize
-     *  promises resolve and influence the next frame (mirrors real rAF timing). */
+    /** Drain frames, flushing microtasks between each so async getAppliedSize promises resolve before the next frame. */
     async function runAsync(
       scheduler: ReturnType<typeof createFrameScheduler>,
       maxFrames = 1000
@@ -337,8 +293,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
     it('keeps converging when the PTY drops the resize (applied stays wide)', async () => {
       const scheduler = createFrameScheduler()
       const resize = vi.fn()
-      // xterm settles narrow immediately, but the PTY never applies it: every
-      // applied-size read reports the stale wide spawn width.
+      // xterm settles narrow, but the PTY never applies it — every applied-size read reports the stale wide spawn width.
       const pane = createTimelinePane(() => ({ cols: 79, rows: 50 }))
       reconcilePtySizeAcrossFrames({
         spawnCols: 203,
@@ -354,9 +309,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
       })
       await runAsync(scheduler, 400)
 
-      // The loop must have re-forwarded the narrow size more than once (the
-      // initial settle plus at least one verify-driven re-forward) and only
-      // terminated at the hard cap, never falsely handing off on a dropped size.
+      // Must re-forward the narrow size more than once (verify-driven), never falsely handing off on a dropped size.
       const narrowForwards = resize.mock.calls.filter((c) => c[0] === 79 && c[1] === 50)
       expect(narrowForwards.length).toBeGreaterThan(1)
     })
@@ -413,9 +366,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
     it('does not verify or re-forward while parked — mobile drives at phone dims', async () => {
       const scheduler = createFrameScheduler()
       const resize = vi.fn()
-      // A mobile-driven PTY legitimately sits at phone dims (≠ our desktop grid).
-      // The parked gate must suppress the verify entirely so we never spin
-      // re-forwarding a desktop size the mobile gate would drop.
+      // Parked gate must suppress the verify entirely — mobile sits at phone dims, so any re-forward would be dropped.
       const getAppliedSize = vi.fn(async () => ({ cols: 40, rows: 30 }))
       const pane = createTimelinePane(() => ({ cols: 120, rows: 40 }))
       reconcilePtySizeAcrossFrames({
@@ -437,11 +388,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
 
     it('does NOT re-forward when a mobile-fit override parks the PTY mid-verification', async () => {
       const scheduler = createFrameScheduler()
-      // The race: the applied-size read is issued while NOT parked (desktop owns
-      // the PTY), but a mobile client takes it over and parks it at phone dims
-      // before the async read resolves. The resolution must re-check parked and
-      // skip the re-forward — otherwise it clobbers the phone dims with a
-      // desktop SIGWINCH. Regression for the visibility-resume mobile-fit leak.
+      // Race: PTY parks after the read is issued but before it resolves; resolution must re-check parked (visibility-resume mobile-fit leak regression).
       let parked = false
       const resize = vi.fn()
       const pane = createTimelinePane(() => ({ cols: 79, rows: 50 }))
@@ -453,8 +400,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
         isAuthoritative: () => true,
         measure: pane.measure,
         resize,
-        // The PTY reports the stale wide size, so a parked-blind loop would
-        // re-forward the narrow desktop grid on resolution.
+        // Stale wide applied size — a parked-blind loop would re-forward the narrow desktop grid on resolution.
         getAppliedSize: async () => {
           // Park the PTY while this read is in flight.
           parked = true
@@ -465,10 +411,7 @@ describe('reconcilePtySizeAcrossFrames', () => {
       })
       await runAsync(scheduler, 400)
 
-      // The only forwards allowed are the pre-park settle ones (79x50 while
-      // desktop owned the PTY); no forward may fire AFTER the override parked it.
-      // With the fix, the verify-driven re-forward at 79x50 is suppressed, so the
-      // narrow size is forwarded at most once (the initial settle), never again.
+      // Only the pre-park settle forward is allowed; the verify-driven re-forward must be suppressed once the override parks the PTY.
       const narrowForwards = resize.mock.calls.filter((c) => c[0] === 79 && c[1] === 50)
       expect(narrowForwards.length).toBeLessThanOrEqual(1)
     })
diff --git a/src/renderer/src/components/terminal-pane/pty-size-reconcile.ts b/src/renderer/src/components/terminal-pane/pty-size-reconcile.ts
index 310aed1c2dc..872f6bc38d8 100644
--- a/src/renderer/src/components/terminal-pane/pty-size-reconcile.ts
+++ b/src/renderer/src/components/terminal-pane/pty-size-reconcile.ts
@@ -1,29 +1,9 @@
-// Why: the deferred-rAF fit can spawn the PTY at a stale (wide) width when the
-// pane's real layout has not settled by the first frame — e.g. a tab that
-// MOUNTS with a split layout already present (a new worktree opened with the
-// side panel on). The PTY is born at the wide window width while xterm later
-// reflows to the narrower split/pane width. The corrective xterm onResize is
-// dropped during the mount window because it honors the visibility gate, which
-// is not yet authoritative (deps.isVisibleRef flips true after mount). So
-// process.stdout.columns stays pinned wide forever and interactive TUIs render
-// garbled (output sized for the wide width wrapping ~1 char per line into the
-// narrow pane). Only a later manual resize re-syncs it.
-//
-// This post-spawn reconcile bridges exactly that gap: it polls across frames,
-// forwarding xterm's measured grid to the PTY on every actual change. Its
-// resize is authoritative by definition, so it bypasses the visibility gate.
-// It keeps polling while the pane is NOT yet authoritative (the hidden mount
-// window where onResize is dropped) so a late-settling split/sidebar layout is
-// still forwarded; once the pane is authoritative and the grid has been stable,
-// it stops and hands off to the live onResize path, which catches any later
-// layout change. A hard frame cap guarantees termination.
-//
-// This loop tracks what it last SENT, not what the PTY actually applied, so a
-// forward dropped main-side (e.g. a mobile take-back resize-suppression window)
-// can still leave the PTY stale here. The visibility-resume re-assert in
-// pty-connection.ts is the backstop: on show it reads the PTY's real size
-// (pty:getSize) and re-forwards on true drift, healing a pane that later
-// hides/shows.
+// Why: the deferred-rAF fit can spawn the PTY at a stale (wide) width when the pane's layout hasn't settled by the first
+// frame (e.g. a tab mounting with a split already present) and the corrective xterm onResize is dropped during the hidden
+// mount window (visibility gate not yet authoritative), so TUIs render garbled until a manual resize. This post-spawn
+// reconcile bridges that gap: it polls across frames, forwarding xterm's measured grid (authoritative, bypasses the gate)
+// until the pane is authoritative and stable, then hands off to the live onResize path. It tracks what it last SENT, not
+// what the PTY applied; the visibility-resume re-assert in pty-connection.ts is the backstop that heals drift on hide/show.
 
 export type PtySizeReconcileDimensions = { cols: number; rows: number }
 
@@ -33,39 +13,15 @@ export type PtySizeReconcileOptions = {
   spawnRows: number
   /** True while this reconcile still owns a live PTY (not disposed / not rebound). */
   isAlive: () => boolean
-  /**
-   * True while the PTY is legitimately parked at non-pane dims (mobile-fit
-   * override / mobile driving). Such frames are skipped — neither fit nor
-   * forwarded — but still count toward the hard cap so a permanently-parked
-   * PTY cannot loop forever.
-   */
+  /** True while the PTY is legitimately parked at non-pane dims (mobile driving); such frames are skipped but still count toward the hard cap. */
   isParked: () => boolean
-  /**
-   * True once the live onResize path will forward future PTY resizes itself
-   * (i.e. the pane is visible / renderer resize is authoritative). The
-   * reconcile only needs to run while this is false (the mount window where
-   * onResize is dropped); once true and the grid is stable it hands off.
-   */
+  /** True once the live onResize path will forward future PTY resizes itself (pane visible); the reconcile only needs to run while this is false. */
   isAuthoritative: () => boolean
-  /**
-   * Fit the pane and return its current measured grid, or null when the pane is
-   * not yet measurable. A measured grid that differs from what the PTY was last
-   * told is forwarded; a matching grid counts toward the stability window.
-   */
+  /** Fit the pane and return its measured grid, or null when not yet measurable. */
   measure: () => PtySizeReconcileDimensions | null
   /** Forward the settled size to the PTY (authoritative — bypasses visibility). */
   resize: (cols: number, rows: number) => void
-  /**
-   * Read the size the PTY has ACTUALLY applied (vs what this loop last sent).
-   * Optional. resize() is fire-and-forget for remote (daemon/SSH) PTYs, so the
-   * loop can settle on a size it sent that the PTY silently dropped — the
-   * mount-time twin of the resume drift the visibility-resume re-assert heals.
-   * Before handing off, the loop reads this once; if it diverges from the
-   * last-sent grid it re-forwards and keeps converging. Returns null when the
-   * applied size cannot be confirmed (treated as "synced enough to hand off" so
-   * a provider without a readback, or a transient failure, cannot wedge the
-   * loop until MAX_FRAMES).
-   */
+  /** Read the size the PTY has ACTUALLY applied (vs what the loop last sent). Optional; remote resize() is fire-and-forget, so the loop verifies once before handoff. Null = can't confirm (treated as synced enough to hand off). */
   getAppliedSize?: () => Promise<PtySizeReconcileDimensions | null>
   /** Schedule the next frame; mirrors requestAnimationFrame's id contract. */
   requestFrame: (callback: () => void) => number
@@ -74,29 +30,12 @@ export type PtySizeReconcileOptions = {
 
 export type PtySizeReconcileHandle = { cancel: () => void }
 
-// Hand off (stop) once the grid has held steady for SETTLE_FRAMES of frames
-// observed *while authoritative*. Rationale for the two-part gate:
-//  - While hidden, the live onResize is dropped, so the reconcile is the SOLE
-//    corrector: it must keep polling and forwarding every change (a narrow that
-//    settles during the hidden window is the real shipped bug). Hidden frames
-//    therefore never count toward the settle window — the loop cannot hand off.
-//  - Once authoritative (pane visible), the live onResize/ResizeObserver path
-//    is the authoritative detector of any further reflow, so after a short
-//    stable window under authority the reconcile hands off to it. The settle
-//    window also gives a ~SETTLE-frame grace for a narrow landing right at the
-//    visibility transition before the handoff.
-// MAX_FRAMES (~3s at 60fps) guarantees termination for a pane that never
-// becomes authoritative (a permanently-hidden background spawn) or never
-// stabilizes; such panes re-fit via the resume-time path when shown.
+// Hand off once the grid holds steady for SETTLE_FRAMES observed *while authoritative* — hidden frames don't count, since the reconcile is the sole corrector then.
+// MAX_FRAMES (~3s at 60fps) guarantees termination for a pane that never becomes authoritative or never stabilizes.
 const POST_SPAWN_RECONCILE_SETTLE_FRAMES = 8
 const POST_SPAWN_RECONCILE_MAX_FRAMES = 180
 
-// Safe minimum grid forwarded as a last resort when a VISIBLE pane never became
-// measurable within the reconcile window and the PTY is still pinned at the
-// unusable 0×0 it was spawned at. A shell rendering into a 0-row grid shows a
-// blank/white pane (the "split terminal right → white screen" report); 80×24 is
-// the universal terminal default and the live onResize corrects it once the
-// pane finally lays out.
+// Fallback grid when a visible pane never measures and the PTY is stuck at 0×0 (blank/white pane); 80×24 is the terminal default.
 const POST_SPAWN_RECONCILE_FALLBACK_COLS = 80
 const POST_SPAWN_RECONCILE_FALLBACK_ROWS = 24
 
@@ -104,19 +43,13 @@ export function reconcilePtySizeAcrossFrames(
   options: PtySizeReconcileOptions
 ): PtySizeReconcileHandle {
   let frame = 0
-  // Counts consecutive unchanged frames observed *while authoritative*. Frames
-  // measured while hidden never advance it, so a long hidden-wide mount window
-  // cannot make the loop hand off the instant the pane becomes visible (before
-  // the split has equalized) on a width it never confirmed under authority.
+  // Consecutive unchanged frames seen *while authoritative*; hidden frames don't advance it, so we never hand off on an unconfirmed width.
   let authoritativeStableFrames = 0
   let lastSentCols = options.spawnCols
   let lastSentRows = options.spawnRows
   let pendingFrame: number | null = null
   let cancelled = false
-  // One-shot applied-size verification before handoff. `verifyInFlight` prevents
-  // re-issuing the async read every frame while it resolves; `appliedVerified`
-  // is the terminal "the PTY confirmed our size (or can't be read)" flag that
-  // lets the loop stop. A re-forward on divergence clears it so we re-verify.
+  // One-shot applied-size verify before handoff: verifyInFlight guards the in-flight read; appliedVerified lets the loop stop.
   let verifyInFlight = false
   let appliedVerified = options.getAppliedSize === undefined
 
@@ -130,37 +63,21 @@ export function reconcilePtySizeAcrossFrames(
       const measured = options.measure()
       if (measured && measured.cols > 0 && measured.rows > 0) {
         if (measured.cols !== lastSentCols || measured.rows !== lastSentRows) {
-          // Authoritative spawn-time correction: bypasses the visibility gate
-          // the live onResize honors (but the caller still skips parked frames).
-          // A real change resets the stability window so we wait for it to hold.
+          // Authoritative spawn-time correction: bypasses the visibility gate; a real change resets the stability window.
           options.resize(measured.cols, measured.rows)
           lastSentCols = measured.cols
           lastSentRows = measured.rows
           authoritativeStableFrames = 0
           appliedVerified = options.getAppliedSize === undefined
         } else if (options.isAuthoritative()) {
-          // Only stability seen *under authority* counts toward handoff — a grid
-          // that merely held steady while hidden is not a safe stopping point.
+          // Only stability seen *under authority* counts toward handoff (steady-while-hidden isn't a safe stop).
           authoritativeStableFrames += 1
         }
       }
       // A null/zero measurement makes no stability progress: layout isn't ready.
     }
-    // Why authoritative-gated rather than a fixed frame floor: while the pane is
-    // hidden the live onResize cannot forward, so the reconcile must keep
-    // watching (and forwarding, since its resize bypasses the gate) for a late
-    // layout settle. Once the pane has been visible AND its grid has held steady
-    // for the settle window, the live onResize/ResizeObserver path owns any
-    // further change, so we hand off. The hard cap guarantees termination.
     const gridStable = authoritativeStableFrames >= POST_SPAWN_RECONCILE_SETTLE_FRAMES
-    // Why verify before handoff: the grid being stable only proves what we SENT
-    // held steady, not what the PTY APPLIED. For a fire-and-forget remote resize
-    // the PTY can be pinned at a stale (wide) size while xterm reflowed narrow —
-    // the mount-time form of the bug that garbles alt-screen TUIs. Read the
-    // applied size once; re-forward and keep converging on divergence. Skip while
-    // parked: a mobile-driven PTY legitimately sits at phone dims (≠ our desktop
-    // grid), and verifying there would spin the loop re-forwarding a size the
-    // mobile gate correctly drops — the same reason measure/forward skip parked.
+    // Grid-stable proves what we SENT held, not what the PTY APPLIED (remote resize is fire-and-forget); verify once, skip parked.
     if (
       gridStable &&
       !appliedVerified &&
@@ -175,11 +92,7 @@ export function reconcilePtySizeAcrossFrames(
           if (cancelled || !options.isAlive()) {
             return
           }
-          // Why: the override can flip to parked while this async read is in
-          // flight (a mobile client takes the PTY mid-verification). Re-check
-          // here — the synchronous guard above only gated issuing the read, not
-          // this resolution — so we never re-forward desktop dims onto a PTY
-          // that is now legitimately parked at phone dims.
+          // Re-check parked: a mobile client can take the PTY mid-read; the sync guard above only gated issuing the read, not this resolution.
           if (options.isParked()) {
             return
           }
@@ -205,13 +118,7 @@ export function reconcilePtySizeAcrossFrames(
       pendingFrame = options.requestFrame(tick)
       return
     }
-    // Last resort on termination: a VISIBLE pane that never measured a usable
-    // grid (measure() returned null/zero every frame) and whose PTY is still
-    // pinned at the 0×0 it was spawned at would render blank — the split-right
-    // white-screen report. Forward a safe default so the shell has a real grid;
-    // the live onResize re-syncs the true size once the pane lays out. Skip
-    // while parked (mobile owns the size) and while hidden (a background spawn
-    // legitimately stays 0×0 and re-fits on show).
+    // Last resort: a visible pane still pinned at 0×0 renders blank (split-right white-screen report); forward a safe default.
     if (
       !settled &&
       !options.isParked() &&
diff --git a/src/renderer/src/components/terminal-pane/pty-transport.test.ts b/src/renderer/src/components/terminal-pane/pty-transport.test.ts
index aebc26fd73b..96efa506cf1 100644
--- a/src/renderer/src/components/terminal-pane/pty-transport.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-transport.test.ts
@@ -68,10 +68,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('leaves title tracking to the PTY data stream (no OpenCode IPC channel)', async () => {
-    // Why: the dedicated OpenCode status IPC channel was replaced by the
-    // unified agent-hooks server; the transport layer no longer has a
-    // per-agent status callback. Keep the smoke test so the transport
-    // still wires up onData/onExit handlers on a basic connect.
+    // Why: the OpenCode status IPC channel is gone (now the agent-hooks server), so the transport has no per-agent status callback.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const transport = createIpcPtyTransport({})
 
@@ -88,9 +85,7 @@ describe('createIpcPtyTransport', () => {
     const write = window.api.pty.write as unknown as ReturnType<typeof vi.fn>
     const transport = createIpcPtyTransport({})
 
-    // Generic spawn failure (e.g. daemon not ready during a startup restore):
-    // the error IS surfaced via onError, but the transport stays unbound and
-    // every later keystroke is dropped with no further signal.
+    // Generic spawn failure: onError fires, but the transport stays unbound and later keystrokes drop with no further signal.
     spawn.mockRejectedValueOnce(new Error('daemon socket not ready'))
     const onError = vi.fn()
     await transport.connect({ url: '', callbacks: { onError } })
@@ -100,9 +95,7 @@ describe('createIpcPtyTransport', () => {
     await flushPtySideEffects()
     expect(write).not.toHaveBeenCalled()
 
-    // The tombstoned-session rejection is swallowed with NO callback at all —
-    // a restored pane that hits it renders persisted content while eating
-    // keystrokes with zero user-visible signal (Discord #performance / #2836).
+    // Tombstoned-session rejection has no callback at all, so a restored pane silently eats keystrokes while showing content (#2836).
     spawn.mockRejectedValueOnce(new Error('TerminalKilledError: session xyz was explicitly killed'))
     const onErrorKilled = vi.fn()
     await transport.connect({ url: '', callbacks: { onError: onErrorKilled } })
@@ -169,10 +162,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('keeps the live handler when detach() runs after a newer transport attached to the same PTY', async () => {
-    // Why: pane->tab detach and split-group moves rehome the React subtree, so
-    // the NEW TerminalPane can attach to the same ptyId BEFORE the old pane's
-    // unmount detach() runs. An unconditional unregister deletes the live
-    // handler and the pane freezes with the PTY still alive (frozen-pane bug).
+    // Why: a new pane can attach the same ptyId before the old detaches; unconditional unregister deletes the live handler (frozen-pane bug).
     const { createIpcPtyTransport } = await import('./pty-transport')
     const receivedByNewPane = vi.fn()
     const replayedToNewPane = vi.fn()
@@ -448,9 +438,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('drops the OSC-9999 cross-chunk carry on resetAgentStatusCarry', async () => {
-    // Why: a model-restore marker means bytes were dropped between chunks —
-    // a partial OSC-9999 prefix carried across that gap would swallow the
-    // next live chunk's head as bogus status payload.
+    // Why: a restore marker means bytes dropped, so a carried partial OSC-9999 prefix would eat the next chunk's head.
     const { createPtyOutputProcessor } = await import('./pty-transport')
     const processor = createPtyOutputProcessor({})
     const callbacks = { onData: vi.fn() }
@@ -830,11 +818,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('suppresses attention side effects when replaying eager-buffered data during attach', async () => {
-    // Why: eager PTY buffers capture output produced before the pane mounted —
-    // typically catch-up bytes from a previous app session. A BEL or
-    // completion-style title arriving in that replay must NOT produce a fresh
-    // alert. onTitleChange still fires so the tab label restores correctly,
-    // but onBell and onAgentBecameIdle are gated by suppressAttentionEvents.
+    // Why: replayed eager output must not raise fresh alerts — bell/idle suppressed, title still restores.
     const { createIpcPtyTransport, registerEagerPtyBuffer } = await import('./pty-transport')
     const onTitleChange = vi.fn()
     const onBell = vi.fn()
@@ -865,9 +849,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('resets replay parser state after deferred side effects drain', async () => {
-    // Why: replay side effects run after xterm receives data. Attach cleanup
-    // still has to wait for them, or a replayed partial OSC can make the first
-    // live BEL look like an OSC terminator instead of an attention bell.
+    // Why: cleanup must await deferred replay side effects, else a partial OSC makes the first live BEL look like an OSC terminator.
     const { createIpcPtyTransport, registerEagerPtyBuffer } = await import('./pty-transport')
     const onBell = vi.fn()
 
@@ -910,11 +892,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('fires onBell for bare BELs but ignores BELs inside OSC sequences', async () => {
-    // Why: Claude's OSC titles end with a BEL terminator (`\e]0;…\a`). The
-    // stateful bell detector must know it is inside an OSC when that BEL
-    // arrives and ignore it — otherwise every agent title change would
-    // produce a spurious bell. A bare BEL outside an OSC is what actually
-    // raises attention.
+    // Why: OSC titles end with a BEL, so the detector must ignore in-OSC BELs or every title change would ring spuriously.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const onBell = vi.fn()
 
@@ -939,8 +917,7 @@ describe('createIpcPtyTransport', () => {
     const cap = 512 * 1024
     const handle = registerEagerPtyBuffer('pty-restored', vi.fn())
 
-    // 8 x 100 KB = 800 KB of distinct chunks, exceeding the 512 KB cap; the
-    // earliest chunks must be dropped while the prompt-bearing tail is kept.
+    // 800 KB of chunks exceeds the 512 KB cap; earliest chunks drop while the prompt-bearing tail is kept.
     for (let i = 0; i < 8; i += 1) {
       onData?.({ id: 'pty-restored', data: String.fromCharCode(65 + i).repeat(100 * 1024) })
     }
@@ -1014,8 +991,7 @@ describe('createIpcPtyTransport', () => {
     const originalShift = Array.prototype.shift
 
     try {
-      // Why: this hot path used to call Array.shift() once per trim, which
-      // reindexed the live buffer and made many small chunks quadratic.
+      // Why: Array.shift() per trim reindexed the buffer, making many small chunks quadratic.
       Object.defineProperty(Array.prototype, 'shift', {
         configurable: true,
         writable: true,
@@ -1040,10 +1016,7 @@ describe('createIpcPtyTransport', () => {
   it('routes eager-buffered bytes through onReplayData so the renderer can engage the replay guard', async () => {
     const { createIpcPtyTransport, registerEagerPtyBuffer } = await import('./pty-transport')
 
-    // Why: eager-buffered bytes often contain query sequences (e.g. DA1 `\x1b[c`)
-    // left over from a previous session. Routing them through onData instead of
-    // onReplayData would bypass pty-connection's replay guard and xterm would
-    // auto-reply to those queries, leaking stray input into the shell.
+    // Why: eager bytes carry DA1-style query sequences; onData bypasses the replay guard so xterm auto-replies, leaking input.
     const bufferedPayload = 'hello\x1b[cworld'
 
     const handle = registerEagerPtyBuffer('pty-restored', vi.fn())
@@ -1113,8 +1086,7 @@ describe('createIpcPtyTransport', () => {
       }
     })
 
-    // Why: title/control frames restore metadata but do not redraw a terminal
-    // frame; clearing before them would erase the persisted scrollback.
+    // Why: title/control frames restore metadata but don't redraw, so clearing before them would erase persisted scrollback.
     const clear = '\x1b[2J\x1b[3J\x1b[H'
     expect(onReplayData.mock.calls).toEqual([[bufferedPayload, { clearBeforeReplay: false }]])
     expect(onReplayData).not.toHaveBeenCalledWith(clear)
@@ -1196,8 +1168,7 @@ describe('createIpcPtyTransport', () => {
       }
     })
 
-    // Why: OSC 9999 is stripped before xterm receives replay data. A non-empty
-    // raw status frame must not clear restored scrollback and replay nothing.
+    // Why: OSC 9999 is stripped before xterm; a raw status frame must not clear restored scrollback and replay nothing.
     const clear = '\x1b[2J\x1b[3J\x1b[H'
     expect(onReplayData.mock.calls).toEqual([['', { clearBeforeReplay: false }]])
     expect(onReplayData).not.toHaveBeenCalledWith(clear)
@@ -1218,8 +1189,7 @@ describe('createIpcPtyTransport', () => {
       }
     })
 
-    // Why: restored scrollback may already be in xterm before attach. An
-    // empty eager buffer must not erase it and leave the pane cursor-only.
+    // Why: restored scrollback may already be in xterm before attach; an empty eager buffer must not erase it.
     expect(onReplayData).not.toHaveBeenCalled()
     expect(onDataCallback).not.toHaveBeenCalled()
   })
@@ -1240,8 +1210,7 @@ describe('createIpcPtyTransport', () => {
       }
     })
 
-    // Why: a live PTY can have an eager handle before any bytes arrive. Clearing
-    // here would destroy the scrollback restored by TerminalPane mount.
+    // Why: a live PTY can have an eager handle before any bytes arrive; clearing would destroy scrollback restored at mount.
     expect(onReplayData).not.toHaveBeenCalled()
     expect(onDataCallback).not.toHaveBeenCalled()
   })
@@ -1269,8 +1238,7 @@ describe('createIpcPtyTransport', () => {
       }
     })
 
-    // Why: alternate-screen snapshots already fill the viewport; emitting the
-    // clear would erase the restored content. Neither path should see it.
+    // Why: alternate-screen snapshots already fill the viewport, so emitting the clear would erase restored content.
     const clear = '\x1b[2J\x1b[3J\x1b[H'
     expect(onReplayData.mock.calls).toEqual([[bufferedPayload, { clearBeforeReplay: false }]])
     expect(onReplayData).not.toHaveBeenCalledWith(clear)
@@ -1407,10 +1375,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('threads the daemon pendingEscapeTailAnsi through the reattach connect result (#7329)', async () => {
-    // Why: the local daemon ships the mid-escape tail on the spawn/reattach
-    // result; dropping it here silently regressed the local half of #7329
-    // (the consumer test injects at the transport boundary, so only this
-    // asserts the IPC threading).
+    // Why: dropping the daemon's mid-escape tail from the reattach result silently regressed the local half of #7329.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const spawnMock = vi.fn().mockResolvedValue({
       id: 'pty-reattach-tail',
@@ -1481,8 +1446,7 @@ describe('createIpcPtyTransport', () => {
     const connectPromise = transport.connect({
       url: '',
       callbacks: {},
-      // A reattach targets a session that existed before this transport;
-      // destroying the view must not reap the user's live shell.
+      // A reattach targets a pre-existing session, so destroying the view must not reap the user's live shell.
       sessionId: 'pty-preexisting'
     })
 
@@ -1573,9 +1537,7 @@ describe('createIpcPtyTransport', () => {
     // Simulate shutdownWorktreeTerminals: unregister data handlers before kill.
     unregisterPtyDataHandlers(['pty-1'])
 
-    // Final data burst from main process (flushed before exit) — contains a
-    // title change and a BEL. Neither should produce a notification because
-    // the data handler was removed.
+    // Final burst after the handler was removed: its title change and BEL must not produce a notification.
     onData?.({ id: 'pty-1', data: ']0;Claude done' })
     expect(onAgentBecameIdle).not.toHaveBeenCalled()
     expect(onBell).not.toHaveBeenCalled()
@@ -1631,9 +1593,7 @@ describe('createIpcPtyTransport', () => {
       onData?.({ id: 'pty-1', data: 'some output without title\r\n' })
       vi.advanceTimersByTime(0)
 
-      // Simulate shutdownWorktreeTerminals: unregister handlers which should
-      // cancel the pending staleTitleTimer AND reset the agent tracker so the
-      // accumulated working state cannot produce a stale idle transition.
+      // Unregister must cancel the staleTitleTimer and reset the tracker so no stale idle transition fires.
       unregisterPtyDataHandlers(['pty-1'])
 
       // Advance past the 3 s stale-title timeout
@@ -1647,14 +1607,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('suppresses the error toast when pty:spawn rejects with TerminalKilledError', async () => {
-    // Why: after the user hits "Kill All" in Settings → Manage Sessions, a
-    // remounted pane's connect() will call pty:spawn with a killed session
-    // ID. The main-side tombstone rejects with TerminalKilledError. That
-    // rejection is the kill working as intended — not a bug — so the
-    // transport must not surface a "please file an issue" toast. Match the
-    // IPC-wrapped form Electron actually throws ("Error invoking remote
-    // method 'pty:spawn': TerminalKilledError: Session \"...\" was
-    // explicitly killed") to exercise the real error path.
+    // Why: a killed-session TerminalKilledError is intended, not a bug, so no toast; string is Electron's IPC-wrapped form to hit the real path.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const spawnMock = vi
       .fn()
@@ -1695,10 +1648,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('still surfaces non-kill spawn errors via onError', async () => {
-    // Why: the TerminalKilledError suppression must be narrowly scoped —
-    // unrelated spawn failures (no shell binary, bad cwd, etc.) still need
-    // to reach the user so they can act on them. Guard against an
-    // over-broad `.includes` match regressing and swallowing real errors.
+    // Why: keep TerminalKilledError suppression narrow so real spawn failures (bad cwd, missing shell) still reach the user.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const spawnMock = vi.fn().mockRejectedValue(new Error('ENOENT: spawn /bin/nope not found'))
 
@@ -1762,8 +1712,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('suppresses the SSH-not-active toast for a runtime-owned (per-workspace-env) target', async () => {
-    // Why: a runtime-owned SSH target disappearing is expected teardown (e.g. the workspace was
-    // deleted) — there's no reconnect dialog for it, so no toast should fire.
+    // Why: a runtime-owned SSH target disappearing is expected teardown (no reconnect dialog exists), so no toast should fire.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const spawnMock = vi
       .fn()
@@ -1795,10 +1744,7 @@ describe('createIpcPtyTransport', () => {
   })
 
   it('recovers a stale cross-connection SSH reattach as expired instead of a red error toast', async () => {
-    // Why: a restored SSH pty id embeds the connection it was created under. If
-    // the pane reattaches under a different connection the main-side router
-    // rejects with "belongs to SSH connection" — that session is unreachable, so
-    // we drop it (sessionExpired) and spawn fresh rather than surfacing a crash.
+    // Why: a cross-connection SSH reattach is unreachable ("belongs to SSH connection"), so drop it as sessionExpired instead of erroring.
     const { createIpcPtyTransport } = await import('./pty-transport')
     const spawnMock = vi
       .fn()
diff --git a/src/renderer/src/components/terminal-pane/pty-transport.ts b/src/renderer/src/components/terminal-pane/pty-transport.ts
index 1047477e69f..a1f59ddeb5c 100644
--- a/src/renderer/src/components/terminal-pane/pty-transport.ts
+++ b/src/renderer/src/components/terminal-pane/pty-transport.ts
@@ -1,7 +1,4 @@
-/* oxlint-disable max-lines -- Why: the PTY transport manages lifecycle, data flow,
-agent status extraction, and title tracking for terminal panes. Splitting would
-scatter the tightly coupled IPC ↔ xterm data pipeline across files with no clear
-module boundary, making the data flow harder to trace during debugging. */
+/* oxlint-disable max-lines -- Why: tightly coupled IPC ↔ xterm data pipeline (lifecycle, data, agent-status, titles) with no clean split point. */
 import {
   detectAgentStatusFromTitle,
   clearWorkingIndicators,
@@ -64,18 +61,11 @@ export type {
 export { extractLastOscTitle } from '../../../../shared/agent-detection'
 
 const SSH_SESSION_EXPIRED_ERROR = 'SSH_SESSION_EXPIRED'
-// Why: an app SSH PTY id embeds the connection it was created under. When a pane
-// restored after a workspace/host change reattaches a session that belongs to a
-// *different* connection, the main-side id router rejects it with this phrase.
-// That session is unreachable from this pane, so it is stale like an expired one
-// — recover by spawning fresh rather than surfacing a red "file an issue" crash.
+// Why: main rejects a session reattached under a different SSH connection with this phrase; treat as stale (spawn fresh), not a crash.
 const SSH_PTY_CONNECTION_MISMATCH_MARKER = 'belongs to SSH connection'
 const STALE_TITLE_TIMEOUT = 3000 // ms before stale working title is cleared
 const MAX_PTY_SIDE_EFFECTS_PER_DRAIN = 64
 
-// Why: onAgentStatus callback added to IpcPtyTransportOptions in pty-dispatcher
-// so the OSC 9999 status payloads can be forwarded to the store.
-
 type PtyOutputCallbacks = Parameters<PtyTransport['connect']>[0]['callbacks']
 
 type PtyOutputProcessorOptions = Pick<
@@ -87,9 +77,7 @@ type PtyOutputProcessorOptions = Pick<
   | 'onAgentExited'
   | 'onAgentStatus'
 > & {
-  /** Seed for processors that start mid-session (parked-tab byte watchers):
-   *  the pane's last known title, so a working agent that finishes while the
-   *  processor owns the stream still yields a working→idle transition. */
+  /** Seed for mid-session processors (parked-tab watchers): pane's last title, so an agent finishing mid-stream still yields a working→idle transition. */
   initialAgentTitle?: string
 }
 
@@ -97,9 +85,7 @@ type ProcessPtyOutputOptions = {
   replayingBufferedData?: boolean
   suppressAttentionEvents?: boolean
   clearBeforeReplay?: boolean
-  // Why: a mid-escape tail the daemon could not serialize. The replay consumer
-  // must write it LAST, after the post-replay reset, so the next live chunk
-  // completes it instead of rendering literally (#7329).
+  // Why: a mid-escape tail; the replay consumer writes it LAST (after the post-replay reset) so the next live chunk completes it, not renders it literally (#7329).
   pendingEscapeTailAnsi?: string
 }
 
@@ -157,13 +143,9 @@ export function createPtyOutputProcessor({
   resetAgentStatusCarry: () => void
 } {
   const bellDetector = createBellDetector()
-  // Why `let`: a model-restore marker means bytes were dropped between
-  // chunks; a partial OSC-9999 prefix carried across that gap would swallow
-  // the next live chunk's head as bogus payload. Reset recreates the parser.
+  // Why let: a model-restore marker drops bytes; recreating the parser stops a partial OSC-9999 carry from swallowing the next chunk's head.
   let processAgentStatusChunk = createAgentStatusOscProcessor()
-  // Why: seed both the emitted-title memory (stale-title probe) and the agent
-  // tracker so a mid-session processor behaves as if it had observed the
-  // pane's last live title — full parity with the live path it replaces.
+  // Why: seed emitted-title memory and the agent tracker so a mid-session processor behaves as if it had observed the pane's last live title.
   let lastEmittedTitle: string | null =
     initialAgentTitle !== undefined ? normalizeTerminalTitle(initialAgentTitle) : null
   let staleTitleTimer: ReturnType<typeof setTimeout> | null = null
@@ -216,8 +198,7 @@ export function createPtyOutputProcessor({
     if (sideEffectDrainTimer !== null) {
       return
     }
-    // Why: xterm.write() buffers parsing onto its own timer. Defer Orca's
-    // title/status/BEL store work so live terminal rendering gets the next turn.
+    // Why: defer title/status/BEL store work so xterm.write()'s own parse timer and live rendering get the next turn.
     sideEffectDrainTimer = setTimeout(drainPtySideEffects, 0)
   }
 
@@ -234,8 +215,7 @@ export function createPtyOutputProcessor({
       next.payloads.length === 0 &&
       !next.containsBell
     ) {
-      // Why: for adjacent no-op scans, only the latest event decides whether
-      // stale-title detection should remain cleared or be re-armed.
+      // Why: for adjacent no-op scans, only the latest event decides whether stale-title detection stays cleared or re-arms.
       prior.titleScanEffect = next.titleScanEffect
       pendingWorkingTitleSideEffects += workingTitleCount
       return
@@ -251,8 +231,7 @@ export function createPtyOutputProcessor({
   ): void {
     const scannedForTitles = Boolean(onTitleChange && data.includes('\x1b]'))
     const titles = scannedForTitles ? extractAllOscTitles(data) : []
-    // Why: Cursor emits this ignored title on every redraw; keep one ordered
-    // queue fact instead of one allocation and drain slot per native frame.
+    // Why: Cursor emits this ignored title every redraw; keep one queue fact instead of an allocation and drain slot per frame.
     const ignoredCursorNativeTitle = removeIgnoredCursorNativeTitles(titles)
     const deliveredPayloads =
       onAgentStatus && !suppressAttentionEvents && payloads.length > 0 ? payloads : []
@@ -276,9 +255,7 @@ export function createPtyOutputProcessor({
       return
     }
 
-    // Why: keep only compact derived side-effect facts here. Retaining raw
-    // PTY chunks duplicates the terminal scheduler backlog while timers are
-    // throttled in a backgrounded Electron window.
+    // Why: queue compact derived facts, not raw PTY chunks, which would duplicate the terminal scheduler backlog while timers are throttled.
     if (deliveredPayloads.length === 0 && titles.length === 0) {
       enqueuePtySideEffect({
         payloads: [],
@@ -381,9 +358,7 @@ export function createPtyOutputProcessor({
     }
     compactPendingSideEffectsIfNeeded(options.flushAll === true)
     if (pendingSideEffectIndex < pendingSideEffects.length) {
-      // Why: long-idle agent CLIs can queue thousands of OSC title/status
-      // facts while Chromium throttles timers. Bound each callback so cursor
-      // blink, paint, and terminal input get chances to run between batches.
+      // Why: thousands of queued OSC facts can pile up under timer throttling; bound each drain so paint and terminal input run between batches.
       scheduleSideEffectDrain()
     }
   }
@@ -401,10 +376,7 @@ export function createPtyOutputProcessor({
     if (!onTitleChange) {
       return
     }
-    // Why: feed EVERY OSC title in the chunk through the observer, not just
-    // the last one. node-pty + the main-process 8ms batch window commonly
-    // coalesce multiple title updates into a single IPC payload; processing
-    // titles in order preserves working-to-idle transitions.
+    // Why: process every OSC title in order, not just the last; batching coalesces titles into one payload and order preserves working→idle transitions.
     if (titles.length > 0) {
       clearStaleTitleTimer()
       for (const title of titles) {
@@ -439,15 +411,10 @@ export function createPtyOutputProcessor({
   ): void {
     const rawLength = meta?.rawLength ?? data.length
     const suppressAttentionEvents = options.suppressAttentionEvents === true
-    // Why: OSC 9999 is an Orca control protocol. Parse it before xterm sees
-    // the bytes, and keep parser state across chunks so partial PTY reads do
-    // not drop valid status updates or print escape garbage.
+    // Why: parse Orca's OSC 9999 before xterm; carry parser state across chunks so partial reads don't drop status or print escape garbage.
     const processed = processAgentStatusChunk(data)
     data = processed.cleanData
-    // Why: mirror the onBell / onAgentBecameIdle guard below — during eager-buffer
-    // replay we must not surface stale agent-status payloads from a prior app
-    // session into the live store. The parser still consumes the bytes so they
-    // do not leak into xterm, we just suppress the callback.
+    // Why: during eager-buffer replay, suppress stale agent-status callbacks from a prior session (bytes still consumed so nothing leaks into xterm).
     if (options.replayingBufferedData && callbacks.onReplayData) {
       const replayMeta = {
         ...(options.clearBeforeReplay === false ? { clearBeforeReplay: false } : {}),
@@ -455,8 +422,7 @@ export function createPtyOutputProcessor({
           ? { pendingEscapeTailAnsi: options.pendingEscapeTailAnsi }
           : {})
       }
-      // Why: preserve the bare-data call shape when there is no replay metadata,
-      // so eager-buffer replay (which passes neither) is unchanged.
+      // Why: preserve the bare-data call shape when there's no replay metadata, so eager-buffer replay (which passes none) is unchanged.
       if (Object.keys(replayMeta).length > 0) {
         callbacks.onReplayData(data, replayMeta)
       } else {
@@ -524,11 +490,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
   let connected = false
   let destroyed = false
   let ptyId: string | null = null
-  // Why: eager PTY buffers contain output produced before the pane attached —
-  // often from the previous app session. We still replay that data so titles
-  // and scrollback restore correctly, but it must not produce fresh bells,
-  // unread marks, or notifications for unrelated worktrees just because Orca
-  // is reconnecting background terminals on launch.
+  // Why: replayed eager-buffer data (often from a prior app session) must not fire fresh bells, unread marks, or notifications on reconnect.
   let suppressAttentionEvents = false
   const inputWriteQueue = createPtyInputWriteQueue({
     isWritable: (id) => connected && ptyId === id,
@@ -548,12 +510,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
   })
   let storedCallbacks: Parameters<PtyTransport['connect']>[0]['callbacks'] = {}
 
-  // Why: pane->tab detach / split-group moves rehome the React subtree, so a
-  // NEW TerminalPane can attach to the same ptyId before the OLD instance's
-  // detach() runs. Track the handlers THIS instance registered so unregister
-  // paths only delete map entries they still own — an unconditional delete
-  // destroys the live handler and the pane freezes (data diverts into the
-  // pre-handler buffer forever).
+  // Why: a new pane can attach to the same ptyId before the old instance's detach() runs; track owned handlers so unregister never deletes the live one.
   const ownedDataAndReplayHandlers = new Map<
     string,
     { data: (data: string, meta?: PtyDataMeta) => void; replay: (data: string) => void }
@@ -585,12 +542,8 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
     ownedDataAndReplayHandlers.delete(id)
   }
 
-  // Why: shared by connect() and attach() to avoid duplicating title/bell/exit
-  // logic across the two code paths that register a PTY.
   function registerPtyDataHandler(id: string): void {
-    // Why: relay pty.attach sends replay data via a dedicated pty:replay IPC
-    // channel. Route it through onReplayData so the renderer engages the
-    // replay guard and xterm auto-replies do not leak into the shell.
+    // Why: route relay replay data through onReplayData so the replay guard stops xterm auto-replies from leaking into the shell.
     const replayHandler = (data: string): void => {
       if (ptyId !== id) {
         return
@@ -659,8 +612,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
     const hadBufferedExit = hasPreHandlerPtyExit(id)
     const exitHandler = (code: number): void => {
       if (ptyId !== null && ptyId !== id) {
-        // Why: a preserved sleep/reconnect session can report its old exit
-        // after this transport has already rebound to a replacement PTY.
+        // Why: a preserved sleep/reconnect session can report its old exit after this transport already rebound to a replacement PTY.
         unregisterPtyHandlers(id)
         return
       }
@@ -674,12 +626,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
     }
     ptyExitHandlers.set(id, exitHandler)
     ownedExitHandlers.set(id, exitHandler)
-    // Why: shutdownWorktreeTerminals bypasses the transport layer — it
-    // kills PTYs directly via IPC without calling disconnect()/destroy().
-    // This teardown callback lets unregisterPtyDataHandlers cancel
-    // accumulated closure state (staleTitleTimer, agent tracker) that
-    // would otherwise fire stale notifications after the data handler
-    // is removed but before the exit event arrives.
+    // Why: shutdownWorktreeTerminals kills PTYs directly, bypassing disconnect/destroy; this cancels timers/tracker state that would fire stale notifications.
     ptyTeardownHandlers.set(id, clearAccumulatedState)
     try {
       drainPreHandlerPtyExit(id, exitHandler)
@@ -687,8 +634,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
       if (!hadBufferedExit) {
         throw error
       }
-      // Why: cleanup callback failures must not turn an already-delivered
-      // pre-attach exit into a generic connect rejection and fallback spawn.
+      // Why: a cleanup failure must not turn an already-delivered pre-attach exit into a connect rejection and fallback spawn.
       console.error('[pty] buffered pre-attach exit cleanup failed', error)
     }
     return hadBufferedExit
@@ -704,9 +650,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
       }
 
       if (options.sessionId && hasPreHandlerPtyExit(options.sessionId)) {
-        // Why: an exited parked session can be recreated under the same id by
-        // createOrAttach. Deliver its buffered final frame/exit before spawn so
-        // the dead incarnation cannot disconnect and orphan a fresh shell.
+        // Why: deliver the exited parked session's buffered final frame/exit before spawn, so the dead incarnation can't orphan a fresh shell reusing its id.
         ptyId = options.sessionId
         connected = true
         registerPtyDataHandler(options.sessionId)
@@ -719,17 +663,13 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
           ? options.sessionId
           : undefined
 
-      // Why: reconnecting may intentionally reuse a session id whose prior
-      // exit was consumed. Re-admit exits without clearing bytes already
-      // buffered for a still-live session before its pane registered.
+      // Why: reconnect may reuse a session id whose prior exit was consumed; re-admit exits without clearing bytes already buffered for the live session.
       if (admittedSessionId) {
         clearConsumedPreHandlerPtyExit(admittedSessionId)
       }
 
       try {
-        // Why: missing-cwd recovery is only valid for fresh local spawns —
-        // reattach must keep the session's exact cwd and SSH-tagged transports
-        // resolve cwd on the remote host.
+        // Why: cwd fallback is only for fresh local spawns — reattach keeps the session's cwd and SSH transports resolve cwd on the remote host.
         const shouldSendLocalCwdFallback =
           cwdFallback === 'worktree' && !connectionId && !admittedSessionId
         const result = await window.api.pty.spawn({
@@ -753,9 +693,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
             : {}),
           ...(connectionId ? { connectionId } : {}),
           ...(admittedSessionId ? { sessionId: admittedSessionId } : {}),
-          // Why: hidden-at-spawn mark must land in main before the PTY's
-          // first byte, so it rides the spawn IPC instead of the pane's
-          // first visibility sync (terminal-query-authority.md).
+          // Why: hidden-at-spawn mark must reach main before the PTY's first byte — ride the spawn IPC, not the visibility sync (terminal-query-authority.md).
           ...(options.initiallyHidden ? { initiallyHidden: true } : {}),
           worktreeId,
           ...(tabId ? { tabId } : {}),
@@ -770,12 +708,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
           ? spawnResult.launchAgent
           : undefined
 
-        // If destroyed while the connect was in flight, bail — and kill only
-        // what this connect CREATED. A fresh spawn is ours to reap, but a
-        // reattach (sessionId) resolves to a pre-existing session owned by the
-        // tab lifecycle: tab close kills it by id through its own path, and
-        // killing it here turns a remount racing a slow reattach into the loss
-        // of a live shell — the exact failure pane recovery exists to prevent.
+        // Why: on destroy mid-connect, kill only a fresh spawn — killing a reattached session (owned by the tab lifecycle) loses a live shell.
         if (destroyed) {
           if (!options.sessionId) {
             window.api.pty.kill(spawnResult.id)
@@ -786,9 +719,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
         ptyId = spawnResult.id
         connected = true
 
-        // Why: for deferred reattach (Option 2), the daemon returns snapshot/
-        // coldRestore data from createOrAttach. Skip onPtySpawn for reattach —
-        // it would reset lastActivityAt and destroy the recency sort order.
+        // Why: skip onPtySpawn for reattach/coldRestore — it would reset lastActivityAt and destroy the recency sort order.
         if (!spawnResult.isReattach && !spawnResult.coldRestore) {
           onPtySpawn?.(spawnResult.id)
         }
@@ -844,29 +775,13 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
             sessionExpired: true
           } satisfies PtyConnectResult
         }
-        // Why: after "Kill All" from Settings → Manage Sessions, mounted panes
-        // can still trigger pty:spawn with the killed session ID (tab remount,
-        // navigating back to the workspace). The main-side adapter correctly
-        // rejects with TerminalKilledError ("...was explicitly killed") via
-        // its tombstone. Surfacing that rejection as a red "Terminal error,
-        // please file an issue" toast misrepresents an intentional user
-        // action as a bug. The pane will already render "Process exited" via
-        // the normal lifecycle — that is the correct signal. Match against
-        // both the raw Error.message and Electron's IPC-wrapped form
-        // ("Error invoking remote method 'pty:spawn': TerminalKilledError:
-        // ..."). The phrase "was explicitly killed" only appears in that one
-        // error type (see src/main/daemon/daemon-pty-adapter.ts), so a
-        // substring match is safe.
+        // Why: re-spawning a Kill-All'd session throws TerminalKilledError; swallow it (pane still shows "Process exited"), don't toast (src/main/daemon/daemon-pty-adapter.ts).
         if (msg.includes('was explicitly killed')) {
           return undefined
         }
-        // Why: on cold start, SSH provider isn't registered yet so pty:spawn
-        // throws a raw IPC error. Replace with a friendly message since this
-        // is an expected state, not an application crash.
+        // Why: on cold start the SSH provider isn't registered yet, so pty:spawn throws a raw IPC error; replace with a friendly message.
         if (connectionId && msg.includes('No PTY provider for connection')) {
-          // Why: a runtime-owned (per-workspace-env) SSH target disappearing is an expected
-          // teardown state (e.g. the workspace was deleted) with no user-facing reconnect dialog —
-          // don't surface a "reconnect" toast for it.
+          // Why: a disappearing runtime-owned SSH target is expected teardown (e.g. workspace deleted); don't surface a reconnect toast.
           if (!isRuntimeOwnedSshTargetId(connectionId)) {
             storedCallbacks.onError?.(
               'SSH connection is not active. Use the reconnect dialog or Settings to connect.'
@@ -890,8 +805,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
       const id = options.existingPtyId
       ptyId = id
       connected = true
-      // Why: skip onPtySpawn — it would reset lastActivityAt and destroy the
-      // recency sort order that reconnectPersistedTerminals preserved.
+      // Why: skip onPtySpawn — it would reset lastActivityAt and destroy the recency sort order reconnectPersistedTerminals preserved.
       registerPtyDataHandler(id)
       registerPtyExitHandler(id)
       if (!connected || ptyId !== id) {
@@ -905,50 +819,28 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
           const replayData = trimIncompleteTerminalControlTail(buffered)
           const shouldClearBeforeReplay =
             !options.isAlternateScreen && hasTerminalDisplayContent(replayData)
-          // Why: hidden automation PTYs may have already rendered their TUI into
-          // the eager buffer. Clear stale pane contents before replaying
-          // terminal-visible bytes, but keep scrollback for control-only frames.
+          // Why: hidden PTYs may pre-render a TUI into the eager buffer; clear stale contents before replay, keep scrollback for control-only frames.
           if (shouldClearBeforeReplay && !storedCallbacks.onReplayData) {
             const clear = '\x1b[2J\x1b[3J\x1b[H'
             storedCallbacks.onData?.(clear)
           }
 
-          // Why: eager-buffered bytes are raw PTY output captured before the
-          // pane mounted — often from the previous app session. We replay
-          // them so titles/scrollback restore correctly, but must silence
-          // attention side effects during that replay: a historical BEL
-          // or completion captured from the prior session must not produce
-          // a fresh bell on the freshly mounted pane.
-          //
-          // The replay option routes the bytes through onReplayData so the
-          // renderer engages the replay guard — xterm's auto-replies to
-          // embedded query sequences would otherwise leak into shell stdin.
+          // Why: silence attention events during replay so a historical BEL from a prior session doesn't ring on the freshly mounted pane.
           suppressAttentionEvents = true
           try {
+            // Why: replayingBufferedData routes bytes through onReplayData so the replay guard blocks xterm query auto-replies from leaking into shell stdin.
             outputProcessor.processData(replayData, storedCallbacks, {
               replayingBufferedData: true,
               suppressAttentionEvents: true,
               clearBeforeReplay: shouldClearBeforeReplay
             })
           } finally {
-            // Why: replay side effects are intentionally deferred for live
-            // output, but replay cleanup must observe them before resetting
-            // parser state or a partial OSC can swallow the next live BEL.
+            // Why: flush deferred side effects before resetting parser state, else a partial OSC can swallow the next live BEL.
             outputProcessor.flushPendingSideEffects()
             suppressAttentionEvents = false
-            // Why: replaying eager-buffered bytes may have observed a "working" title
-            // without a follow-up title, starting a stale-title timer. That timer would
-            // fire 3s later — outside the suppression window — and trigger a spurious
-            // working→idle transition (and phantom cache-timer write) for a session
-            // that was never live in this app instance. Cancel it so the replay has
-            // no lingering side effects.
+            // Why: replay may arm a stale-title timer that fires 3s later (outside suppression) and force a spurious working→idle transition.
             outputProcessor.clearStaleTitleTimer()
-            // Why: eager-buffered bytes may end mid-OSC (truncated/partial session
-            // data), leaving bellDetector with inOsc = true. Without resetting, the
-            // next real BEL in live data would be silently classified as an OSC
-            // terminator and dropped. BEL is the sole attention signal per the PR
-            // design, so this reset guards the attention pipeline against a silent
-            // regression driven by replay state leaking into the live stream.
+            // Why: eager-buffered bytes may end mid-OSC (inOsc=true); reset so the next live BEL isn't swallowed as an OSC terminator.
             outputProcessor.resetBellDetector()
           }
         }
@@ -980,11 +872,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
       clearAccumulatedState()
       inputWriteQueue.clear()
       if (ptyId) {
-        // Why: detach() is used for in-session remounts such as moving a tab
-        // between split groups. Stop delivering data/title events into the
-        // unmounted pane immediately, but keep the PTY exit observer alive so
-        // a shell that dies during the remount gap can still clear stale
-        // tab/leaf bindings before the next pane attempts to reattach.
+        // Why: on remount keep the exit observer alive so a shell dying in the gap still clears stale tab/leaf bindings before reattach.
         unregisterPtyDataAndStatusHandlers(ptyId)
       }
       connected = false
@@ -999,10 +887,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
       return inputWriteQueue.enqueue(ptyId, data)
     },
 
-    // Why: the local write queue already drains a lone item in the same turn
-    // (no wall-clock debounce), so query replies are prompt without special
-    // handling. Kept as a distinct method so callers express intent and the
-    // remote transport can override with its flush-then-send behavior (#7329).
+    // Why: kept distinct from sendInput so the remote transport can override with flush-then-send (#7329); local queue drains same-turn.
     sendInputImmediate(data: string): boolean {
       if (!connected || !ptyId) {
         return false
@@ -1063,8 +948,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
       if (connectionId) {
         return null
       }
-      // Why: input routing and diagnostics must follow the launched PTY
-      // session, not later project setting changes.
+      // Why: input routing/diagnostics must follow the launched PTY session, not later project setting changes.
       return {
         ...(cwd ? { cwd } : {}),
         ...(shellOverride ? { shellOverride } : {})
@@ -1072,9 +956,7 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
     },
 
     resetCrossChunkParserState() {
-      // Why: only the OSC-9999 carry spans the dropped-byte gap a
-      // model-restore marker reports; title/bell trackers re-sync from the
-      // snapshot's side-effect replay and must not be reset here.
+      // Why: only the OSC-9999 carry spans the model-restore dropped-byte gap; title/bell re-sync from the snapshot replay.
       outputProcessor.resetAgentStatusCarry()
     },
 
diff --git a/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts b/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
index c93311ef453..af519bf240d 100644
--- a/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
+++ b/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
@@ -57,11 +57,7 @@ function isRemoteTerminalGoneMessage(message: string): boolean {
   )
 }
 
-/**
- * PTY transport backing a renderer terminal pane with a terminal on a remote Orca
- * runtime, over runtime RPC plus the multiplexed stream (create, subscribe, input,
- * resize, close, reattach).
- */
+/** PTY transport for a renderer pane backed by a terminal on a remote Orca runtime, over runtime RPC plus the multiplexed stream. */
 export function createRemoteRuntimePtyTransport(
   runtimeEnvironmentId: string,
   opts: IpcPtyTransportOptions = {}
@@ -112,8 +108,7 @@ export function createRemoteRuntimePtyTransport(
     }
     viewportClaimReadyWaiters.clear()
   }
-  // Why: tab/leaf ids identify the mirrored host pane, so every paired viewer
-  // shares them. The instance suffix keeps one viewer's refresh off peer records.
+  // Why: tab/leaf ids are shared by paired viewers; the instance suffix keeps one viewer's refresh off peer records.
   const clientId = `desktop:${tabId ?? 'tab'}:${leafId ?? 'leaf'}:${createBrowserUuid()}`
   const outputProcessor = createPtyOutputProcessor({
     onTitleChange,
@@ -189,8 +184,7 @@ export function createRemoteRuntimePtyTransport(
       if (remainingMs <= 0) {
         return null
       }
-      // Why: host mirrors can be published before their PTY handle is ready,
-      // but a stuck pending surface must not poll the runtime forever.
+      // Why: host mirrors can publish before their PTY handle is ready, but a stuck pending surface must not poll forever.
       await new Promise((resolve) =>
         setTimeout(resolve, Math.min(HOST_SESSION_ATTACH_POLL_MS, remainingMs))
       )
@@ -232,8 +226,7 @@ export function createRemoteRuntimePtyTransport(
           runtimeTerminalErrorMessage(lastListError)
         )
       }
-      // Why: a bounded wait without removal evidence is unknown liveness;
-      // keep the mounted pane for an external snapshot to reattach later.
+      // Why: a bounded wait without removal evidence is unknown liveness; keep the pane for a later snapshot to reattach.
       return undefined
     }
     while (!destroyed && connected && handle === previousHandle) {
@@ -263,16 +256,14 @@ export function createRemoteRuntimePtyTransport(
           return null
         }
       } catch (error) {
-        // Why: the session inventory can race the same runtime reconnect that
-        // invalidated the handle. Unknown liveness must not retire the pane.
+        // Why: the inventory can race the reconnect that invalidated the handle; unknown liveness must not retire the pane.
         lastListError = error
       }
       const remainingMs = HOST_SESSION_ATTACH_TIMEOUT_MS - (Date.now() - startedAt)
       if (remainingMs <= 0) {
         return finishWithUnknownLiveness()
       }
-      // Why: a stale response can precede publication of its replacement.
-      // Bounded backoff avoids retrying the known-stale handle in a hot loop.
+      // Why: a stale response can precede its replacement; bounded backoff avoids retrying the stale handle in a hot loop.
       await new Promise((resolve) => setTimeout(resolve, Math.min(pollMs, remainingMs)))
       pollMs = Math.min(pollMs * 2, HOST_SESSION_REPLACEMENT_POLL_MAX_MS)
     }
@@ -360,8 +351,7 @@ export function createRemoteRuntimePtyTransport(
         return false
       }
     }
-    // Why: normal remote sendInput may be waiting on yielded size validation;
-    // drain it before acknowledged writes so terminal bytes stay ordered.
+    // Why: normal sendInput may be awaiting size validation; drain it before acknowledged writes so terminal bytes stay ordered.
     const text = `${inputBatcher.takePending()}${data}`
     try {
       const tooLarge = isTerminalInputTooLargeWithDeferredMeasurement(text)
@@ -376,8 +366,7 @@ export function createRemoteRuntimePtyTransport(
         if (!connected || handle !== targetHandle) {
           return false
         }
-        // Why: acknowledged sends are ordered behind any pending debounce text,
-        // but they must not collapse large paste input back into one remote RPC.
+        // Why: acknowledged sends order behind pending debounce text but must not collapse large paste back into one remote RPC.
         const result = await callRuntime<{ send: RuntimeTerminalSend }>('terminal.send', {
           terminal: targetHandle,
           text: chunk,
@@ -390,8 +379,7 @@ export function createRemoteRuntimePtyTransport(
       }
       return true
     } catch (error) {
-      // Why: stale-handle errors must retire the mirror (recoverable via the
-      // next snapshot) rather than dead-end in a red xterm banner (#7718).
+      // Why: stale-handle errors must retire the mirror (recoverable via next snapshot), not dead-end in a red xterm banner (#7718).
       handleRemoteTerminalError(error)
       return false
     }
@@ -407,8 +395,7 @@ export function createRemoteRuntimePtyTransport(
       return
     }
     if (pendingViewportClaim) {
-      // Why: a claim during subscribe/reconnect has no stream record to own
-      // yet. Hold its input until the stream can emit claim+input in one order.
+      // Why: a claim during subscribe/reconnect has no stream record yet; hold its input so the stream emits claim+input in one order.
       pendingClaimInput += text
       return
     }
@@ -499,8 +486,7 @@ export function createRemoteRuntimePtyTransport(
     const replacedPtyId = remotePtyId
     handle = nextHandle
     remotePtyId = toRemoteRuntimePtyId(nextHandle, currentRuntimeEnvironmentId)
-    // Why: host handle rotation preserves the pane generation; only the store
-    // identity changes, without fresh-spawn or terminal-exit semantics.
+    // Why: host handle rotation preserves the pane generation; only the store identity changes, not spawn/exit semantics.
     if (replacedPtyId) {
       replaceFitOverridePtyId(replacedPtyId, remotePtyId)
       replaceDriverPtyId(replacedPtyId, remotePtyId)
@@ -547,14 +533,12 @@ export function createRemoteRuntimePtyTransport(
   function handleRemoteTerminalError(error: unknown): void {
     const message = runtimeTerminalErrorMessage(error)
     if (message === REMOTE_TERMINAL_SNAPSHOT_TOO_LARGE) {
-      // Why: an oversized initial snapshot is skipped but live output keeps
-      // flowing — informational, not fatal, so never surface a red xterm banner.
+      // Why: an oversized initial snapshot is skipped but live output keeps flowing — informational, not fatal.
       return
     }
     if (isRemoteTerminalStaleMessage(message)) {
       if (tabId && isWebTerminalSurfaceTabId(tabId)) {
-        // Why: reconnect can re-mint a mirrored pane's handle while its host tab
-        // remains alive. Keep xterm/composer state mounted while we re-resolve it.
+        // Why: reconnect can re-mint a mirrored pane's handle while its host tab lives; keep xterm/composer state mounted while re-resolving.
         closeMultiplexedStream()
         scheduleResubscribeAfterTransportClose(true)
       } else {
@@ -563,18 +547,14 @@ export function createRemoteRuntimePtyTransport(
       return
     }
     if (isRemoteTerminalGoneMessage(message)) {
-      // Why: an explicit terminal-gone response is terminal lifecycle evidence,
-      // unlike a replaceable stale handle observed during reconnect.
+      // Why: an explicit terminal-gone response is lifecycle evidence, unlike a replaceable stale handle seen during reconnect.
       retireRemoteTerminalId()
       return
     }
     storedCallbacks.onError?.(message)
   }
 
-  // Why: after a transport drop the host may have re-minted this pane's
-  // handle (reconnect, epoch or PTY change). Re-derive it from the current
-  // session snapshot instead of resubscribing the stale closure value, which
-  // would mirror (and type into) whatever PTY now sits behind it (#7718).
+  // Why: after a transport drop the host may have re-minted this handle; re-derive from the snapshot so we don't mirror/type into whatever PTY now sits behind the stale one (#7718).
   async function resubscribeAfterTransportClose(
     previousHandle: string,
     requireReplacement: boolean
@@ -593,8 +573,7 @@ export function createRemoteRuntimePtyTransport(
         return
       }
       if (!nextHandle) {
-        // Why: the host no longer publishes this surface; retire quietly and
-        // let the next session-tabs snapshot drive respawn/removal.
+        // Why: host no longer publishes this surface; retire quietly and let the next session-tabs snapshot drive respawn/removal.
         retireRemoteTerminalId()
         return
       }
@@ -611,13 +590,11 @@ export function createRemoteRuntimePtyTransport(
       return
     }
     if (requireReplacement && stopWaitingForPublishedHandle) {
-      // Why: once bounded polling has handed recovery to accepted snapshots,
-      // repeated sends to the known-stale handle must not re-arm inventory RPCs.
+      // Why: once recovery is handed to accepted snapshots, repeated sends to the stale handle must not re-arm inventory RPCs.
       return
     }
     if (resubscribing) {
-      // Why: concurrent stale errors belong to the handle that produced them.
-      // Do not carry an old handle's replacement requirement onto its successor.
+      // Why: concurrent stale errors belong to their own handle; don't carry an old handle's replacement requirement onto its successor.
       if (resubscribeRequestedHandle !== handle) {
         resubscribeRequestedHandle = handle
         resubscribeRequestedRequiresReplacement = requireReplacement
@@ -629,8 +606,7 @@ export function createRemoteRuntimePtyTransport(
     const resubscribeHandle = handle
     clearPublishedHandleWait()
     if (tabId && isWebTerminalSurfaceTabId(tabId)) {
-      // Why: subscribe before polling so a fresh host snapshot cannot land in
-      // the gap between the bounded inventory loop and its event-driven fallback.
+      // Why: subscribe before polling so a fresh host snapshot can't land in the gap between the inventory loop and its event-driven fallback.
       waitForPublishedHostSessionHandle(toHostSessionTabId(tabId), resubscribeHandle)
     }
     resubscribing = true
@@ -661,10 +637,7 @@ export function createRemoteRuntimePtyTransport(
     const subscribedPtyId = remotePtyId
     const generation = ++subscriptionGeneration
     let transportClosed = false
-    // Why: the viewport we hand the subscribe request. A resize landing during
-    // the round-trip falls back to the one-shot RPC, which is refresh-only (no
-    // leak) and no-ops before the stream record exists — so replay the latest
-    // remembered viewport through the stream once it's current (below).
+    // Why: viewport handed to subscribe; a resize during the round-trip falls back to the refresh-only one-shot RPC, replayed through the stream below once current.
     const subscribedViewport = desiredViewport
     const isCurrentSubscription = (): boolean =>
       !transportClosed &&
@@ -683,8 +656,7 @@ export function createRemoteRuntimePtyTransport(
           }
         },
         onSnapshot: (data, meta) => {
-          // Why: a snapshot with no body can still carry a pending mid-escape
-          // tail that must be replayed so the next live chunk completes it.
+          // Why: an empty snapshot can still carry a pending mid-escape tail that must replay so the next live chunk completes it.
           if ((data || meta?.pendingEscapeTailAnsi) && isCurrentSubscription()) {
             outputProcessor.processData(data, storedCallbacks, {
               replayingBufferedData: true,
@@ -765,10 +737,7 @@ export function createRemoteRuntimePtyTransport(
     closeMultiplexedStream()
     multiplexedStream = nextStream
     multiplexedStreamHandle = subscribedHandle
-    // Why: a viewport change that landed during the subscribe round-trip took
-    // the now-no-op one-shot fallback, so the stream record is still at the
-    // subscribe-time size. Replay the latest remembered viewport so the PTY
-    // tracks the current width instead of stalling until the next resize.
+    // Why: a viewport change during the subscribe round-trip hit the no-op one-shot fallback; replay the latest viewport so the PTY isn't stuck at subscribe-time size.
     if (pendingViewportClaim && desiredViewport) {
       nextStream.claimViewport(desiredViewport.cols, desiredViewport.rows)
       pendingViewportClaim = false
@@ -822,15 +791,13 @@ export function createRemoteRuntimePtyTransport(
           tabId,
           leafId,
           focus: false,
-          // Why: this transport is backing an already-mounted renderer pane;
-          // activation here is local state, not permission for remote UI reveal.
+          // Why: transport backs an already-mounted pane; activation is local state, not permission for remote UI reveal.
           presentation: 'background',
           ...(activate === true ? { activate: true } : {})
         })
         handle = created.terminal.handle
         if (destroyed) {
-          // Why: this is a cancelled launch, not a connected shared session.
-          // Close the server PTY so rapid tab-open/tab-close does not leak.
+          // Why: cancelled launch, not a shared session; close the server PTY so rapid tab-open/close does not leak.
           await closeRemoteTerminal(created.terminal.handle)
           return
         }
@@ -877,8 +844,7 @@ export function createRemoteRuntimePtyTransport(
         storedCallbacks.onError?.('Remote runtime terminal id is invalid.')
         return
       }
-      // Why: legacy restored ids omitted their runtime owner. Canonicalize at
-      // attach so renderer stores and lifecycle guards never share raw aliases.
+      // Why: legacy restored ids omit their runtime owner; canonicalize at attach so stores and lifecycle guards never share raw aliases.
       remotePtyId = toRemoteRuntimePtyId(handle, currentRuntimeEnvironmentId)
       connected = true
       desiredViewport = {
@@ -939,17 +905,11 @@ export function createRemoteRuntimePtyTransport(
       if (!data) {
         return true
       }
-      // Why: callers use \r or terminal.send's enter flag for semantic Enter;
-      // literal LF bytes from paste/programmatic input must survive the stream.
+      // Why: literal LF bytes from paste/programmatic input must survive; callers use \r or the enter flag for semantic Enter.
       return inputBatcher.push(data)
     },
 
-    // Why: terminal query replies (CPR/DSR/DA/OSC color/pixel size) are read by
-    // the querying program in raw mode with a short timeout. The 8ms input
-    // debounce makes the reply miss that window, so it lands on the shell prompt
-    // and is echoed literally / spliced into typed input (#7329). Flush any
-    // pending batched input first so byte order is preserved, then send the
-    // reply immediately without arming the debounce timer.
+    // Why: query replies (CPR/DSR/DA/OSC) are read in raw mode with a short timeout; the 8ms debounce would miss it and echo the reply onto the prompt (#7329).
     sendInputImmediate(data: string): boolean {
       const targetHandle = handle
       if (!connected || !targetHandle) {
@@ -958,14 +918,7 @@ export function createRemoteRuntimePtyTransport(
       if (!data) {
         return true
       }
-      // Why: earlier input (e.g. a large paste) may still be in async byte-length
-      // validation, so it is captured in the batcher's validationTail and NOT in
-      // takePending(). Bypassing the queue here would send the reply ahead of it
-      // and reorder bytes on the wire. In that rare window, route the reply
-      // through the batcher's ordered queue and flush what is already validated;
-      // the reply lands right after the pending input once its validation
-      // resolves. Order correctness beats the immediacy that the debounce
-      // normally trades away.
+      // Why: earlier input may still be in async byte-length validation (in validationTail, not takePending); route the reply through the ordered queue so it can't jump ahead and reorder bytes.
       if (inputBatcher.hasPendingValidation()) {
         const accepted = inputBatcher.push(data)
         inputBatcher.flush()
@@ -1014,8 +967,7 @@ export function createRemoteRuntimePtyTransport(
         sendViewportUpdate(cols, rows, true)
         return true
       }
-      // Why: xterm fit can emit resize bursts while the user drags panes or
-      // restores layouts. Remote runtimes only need the last viewport in a frame.
+      // Why: xterm fit emits resize bursts on drag/layout-restore; remote runtimes only need the last viewport per frame.
       viewportBatcher.queue(cols, rows)
       return true
     },
diff --git a/src/renderer/src/components/terminal-pane/replay-guard.ts b/src/renderer/src/components/terminal-pane/replay-guard.ts
index b7e43ff82cb..24ad07e42b4 100644
--- a/src/renderer/src/components/terminal-pane/replay-guard.ts
+++ b/src/renderer/src/components/terminal-pane/replay-guard.ts
@@ -10,56 +10,13 @@ import {
   recordTerminalParseProgress
 } from '@/lib/pane-manager/terminal-write-pipeline-health'
 
-// Why: xterm.js auto-responds to terminal query sequences (DA1 `CSI c`,
-// DECRQM `CSI ? Ps $ p`, OSC 10/11 color queries, focus events, CPR) by
-// emitting the reply through its onData callback. In pty-connection.ts that
-// callback is wired directly to `transport.sendInput`, which pipes the reply
-// to the shell's stdin. When we restore terminal state at startup or on
-// reattach we write recorded PTY bytes back into xterm — including any
-// queries the previous agent CLI emitted — and the auto-replies end up as
-// stray characters on the new shell's prompt (e.g. `?1;2c`, `2026;2$y`,
-// OSC 10/11 color fragments).
-//
-// xterm does not expose a `wasUserInput` flag on its public onData, so we
-// cannot distinguish replay-induced replies from real keystrokes after the
-// fact. Instead, we track an in-flight replay counter per pane: callers
-// replay into xterm via `replayIntoTerminal`, which increments the counter,
-// writes, and decrements in xterm's write-completion callback. The onData
-// handler in pty-connection.ts drops data while the counter is non-zero.
-//
-// The guard window is bounded by xterm's own parse completion, not a
-// wall-clock timer, so only replies generated while parsing the replayed
-// bytes are suppressed. User keystrokes typed after the replay completes
-// are unaffected. In practice replay finishes within milliseconds — before
-// the user could meaningfully type — so the few-ms window where real input
-// would also be dropped is acceptable relative to correctness.
+// Why this guard exists: xterm auto-replies to query sequences (DA1/DECRQM/OSC 10-11/CPR) via onData → shell stdin, so replaying recorded PTY bytes leaks stray replies onto the new shell's prompt.
+// No wasUserInput flag distinguishes replay replies from real keystrokes, so a per-pane in-flight counter gates onData; bounded by xterm's parse completion (not a timer), only auto-replies from replayed bytes are dropped.
 
 export type ReplayingPanesRef = React.RefObject<Map<number, number>>
 
-// Why stall handling exists: the decrement above only runs when xterm
-// completes the write. A wedged WriteBuffer (sync throw escaping a parse
-// handler or a write-completion callback — see
-// xterm-write-buffer-stall.repro.test.ts) or a disposed-terminal race can
-// drop that completion forever, leaving the guard latched on a live pane —
-// which silently eats every keystroke (Discord #performance / issue #2836).
-//
-// Why release is probe-certified, never time-based: a blind timeout release
-// while a slow replay is still parsing would let xterm's auto-replies leak
-// into the shell — and into agent TUIs, where a leaked ESC reads as the user
-// pressing Escape. Instead, when a completion looks overdue we enqueue an
-// empty probe write. xterm parses writes in order, so only three states are
-// possible, and release is provably safe in every state that releases:
-//   1. probe completes, replay callback already ran   → normal release won.
-//   2. probe completes, replay callback never ran     → every replay byte has
-//      parsed (FIFO), so no further auto-replies can exist; the completion
-//      was genuinely lost. Release.
-//   3. probe never completes                          → wedged OR merely
-//      behind. Other completions parsing after the probe was queued prove
-//      "behind" — the deadline extends until a fully quiet window passes.
-//      Only a quiet window certifies wedged: a dead parser can never emit
-//      auto-replies, so releasing then cannot leak anything — and the pane
-//      needs recovery, which the breadcrumb reports.
-// While the probe is pending (slow-but-alive replay), the guard HOLDS.
+// Why stall handling exists: the decrement only runs on xterm's write completion; a wedged WriteBuffer or disposed-terminal race can drop it forever, latching the guard so it eats every keystroke (issue #2836).
+// Why release is probe-certified, not time-based: a blind timeout during a slow replay would leak xterm auto-replies into the shell/agent TUIs, so an empty FIFO probe certifies wedged only after a fully quiet window.
 const REPLAY_GUARD_STALL_CHECK_MS = 10_000
 
 type ReplayTerminalOptions = {
@@ -80,9 +37,8 @@ type ReplayGuardWriteCallbacks = {
 
 /**
  * Engage the replay counter for one write and return its settlement callbacks.
- * Release runs exactly once — from xterm's write completion or, failing
- * that, from the probe-certified stall path — so a lost completion cannot
- * latch the guard.
+ * Release runs exactly once — from write completion or the probe-certified stall
+ * path — so a lost completion cannot latch the guard.
  */
 function engageReplayGuard(
   map: Map<number, number>,
@@ -119,8 +75,7 @@ function engageReplayGuard(
         `[terminal] replay guard released for pane ${paneId} — xterm rejected the replay write or its probe never parsed (undeliverable write pipeline; pane likely needs recovery)`
       )
       recordRendererCrashBreadcrumb('terminal_replay_guard_wedged_release', { paneId })
-      // Why: a rejected replay or silent probe makes the pipeline
-      // undeliverable — recover instead of leaving a fossil that eats input.
+      // Why: a rejected replay or silent probe makes the pipeline undeliverable; recover instead of a fossil that eats input.
       notifyUndeliverableWrite(terminal, 'replay-wedged')
     }
     onRelease?.()
@@ -130,11 +85,7 @@ function engageReplayGuard(
       if (released) {
         return
       }
-      // Why: completions parsed after the probe was queued prove the FIFO is
-      // alive and merely behind (hidden-restore backlogs parse slowly). A
-      // wedge verdict here would open the guard while replay bytes are still
-      // parsing — leaking auto-replies into the agent's stdin — and hand a
-      // healthy pane to recovery. Certify only after a fully quiet window.
+      // Why: completions after the probe prove the FIFO is alive, just behind; certify wedged only after a fully quiet window.
       if (hasTerminalParseProgressSince(terminal, quietSinceGeneration)) {
         armWedgeDeadline(captureTerminalParseProgressGeneration(terminal))
         return
@@ -148,15 +99,13 @@ function engageReplayGuard(
     }
     const probeQueuedAtGeneration = captureTerminalParseProgressGeneration(terminal)
     try {
-      // FIFO certification: this callback can only run after every replay
-      // byte queued before it has parsed (state 2 above).
+      // FIFO certification: this callback runs only after every replay byte queued before it has parsed.
       terminal.write('', () => {
         recordTerminalParseProgress(terminal)
         release('lost-completion')
       })
     } catch {
-      // write threw (terminal disposed mid-replay): nothing will ever parse,
-      // so no auto-replies can leak.
+      // write threw (terminal disposed mid-replay): nothing will parse, so no auto-replies can leak.
       release('wedged')
       return
     }
@@ -165,21 +114,18 @@ function engageReplayGuard(
   timer = setTimeout(probeForStall, stallCheckMs)
   return {
     onParsed: () => {
-      // Why recorded even after release: a late completion is still parse
-      // progress, and sibling guards' wedge deadlines consult it.
+      // Why record even after release: a late completion is still parse progress that sibling guards' wedge deadlines consult.
       recordTerminalParseProgress(terminal)
       release('parsed')
     },
-    // A rejected write produced no replay auto-replies, so release immediately
-    // and recover without recording fake parser progress.
+    // A rejected write produced no auto-replies, so release immediately without recording fake parser progress.
     onWriteFailure: () => release('wedged')
   }
 }
 
-/** Writes `data` into the pane's terminal with the replay guard engaged,
- *  so xterm's auto-replies to embedded query sequences do not leak to the
- *  shell as input. The counter increments/decrements so nested replays
- *  (e.g. clear-screen preamble + snapshot body) compose correctly. */
+/** Writes `data` into the pane's terminal with the replay guard engaged, so
+ *  xterm's auto-replies to embedded query sequences don't leak to the shell.
+ *  The counter increments/decrements so nested replays compose correctly. */
 export function replayIntoTerminal(
   pane: ManagedPane,
   replayingPanesRef: ReplayingPanesRef,
@@ -189,10 +135,7 @@ export function replayIntoTerminal(
   if (!data) {
     return
   }
-  // Why: a probe-certified dead pipeline can never parse this replay — each
-  // attempt only re-arms a guard destined for another wedged release (the
-  // production "zombie drip": restore retries every watchdog heal, forever).
-  // Recovery owns the pane once certified; skip the futile write.
+  // Why: a certified-dead pipeline never parses; retrying only re-arms a guard for another wedged release, so skip it.
   if (isTerminalWritePipelineCertifiedDead(pane.terminal)) {
     return
   }
@@ -203,8 +146,7 @@ export function replayIntoTerminal(
     pane.terminal,
     options.stallCheckMs ?? REPLAY_GUARD_STALL_CHECK_MS
   )
-  // Why: hidden/snapshot replay bypasses the live foreground write path, but
-  // WebGL/canvas renderers still need a post-parse repaint to drop stale cells.
+  // Why: hidden/snapshot replay skips the foreground path; WebGL/canvas still need a post-parse repaint to drop stale cells.
   writeForegroundTerminalChunk(pane.terminal, data, {
     forceViewportRefresh: true,
     followupViewportRefresh: true,
@@ -224,15 +166,13 @@ export function replayIntoTerminalAsync(
   if (!data) {
     return Promise.resolve()
   }
-  // Why: same certified-dead short-circuit as replayIntoTerminal; resolve so
-  // awaited restore chains complete instead of hanging on a dead parser.
+  // Why: same certified-dead short-circuit as replayIntoTerminal; resolve so awaited chains don't hang on a dead parser.
   if (isTerminalWritePipelineCertifiedDead(pane.terminal)) {
     return Promise.resolve()
   }
   ensureArabicShapingJoinerForText(pane.terminal, data)
   return new Promise((resolve) => {
-    // Why resolve on either release path: callers await this to sequence
-    // restore steps; a lost write completion must not hang the restore chain.
+    // Why resolve on either release path: callers await this; a lost completion must not hang the restore chain.
     const guardCallbacks = engageReplayGuard(
       replayingPanesRef.current,
       pane.id,
@@ -251,9 +191,8 @@ export function replayIntoTerminalAsync(
   })
 }
 
-/** Resolves after every replay write already queued on this terminal has
- * parsed. A delayed FIFO probe covers a lost sentinel callback without ever
- * treating elapsed time alone as proof that parsing finished. */
+/** Resolves once every replay write queued on this terminal has parsed. A delayed
+ *  FIFO probe covers a lost sentinel without treating elapsed time as proof. */
 export function waitForTerminalReplayWritesParsed(
   terminal: ReplayGuardWriteTarget,
   options: Pick<ReplayTerminalOptions, 'stallCheckMs'> = {}
@@ -277,8 +216,7 @@ export function waitForTerminalReplayWritesParsed(
         return
       }
       try {
-        // Why: an empty write is FIFO with earlier replay bytes. Its callback
-        // can recover a lost sentinel callback without changing parser state.
+        // Why: empty write is FIFO after replay bytes; its callback recovers a lost sentinel without changing parser state.
         terminal.write('', finish)
       } catch {
         // A disposed terminal cannot parse any remaining replay bytes.
@@ -287,8 +225,7 @@ export function waitForTerminalReplayWritesParsed(
     }
     stallTimer = setTimeout(queueProbe, options.stallCheckMs ?? REPLAY_GUARD_STALL_CHECK_MS)
     try {
-      // Why empty: pendingEscapeTailAnsi must remain the final replay bytes;
-      // xterm still orders this completion after every earlier write.
+      // Why empty: keep pendingEscapeTailAnsi as the final replay bytes; xterm still orders this completion after earlier writes.
       terminal.write('', finish)
     } catch {
       // A disposed terminal cannot parse any remaining replay bytes.
diff --git a/src/renderer/src/components/terminal-pane/terminal-appearance.test.ts b/src/renderer/src/components/terminal-pane/terminal-appearance.test.ts
index d0c060122af..68f20a382fd 100644
--- a/src/renderer/src/components/terminal-pane/terminal-appearance.test.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-appearance.test.ts
@@ -63,8 +63,7 @@ describe('maybePushMode2031Flip', () => {
   })
 
   it('suppresses repeat pushes when the resolved mode has not changed', () => {
-    // This is the spam-gate: applyTerminalAppearance re-runs on every font /
-    // opacity / cursor tweak, and we must not emit CSI 997 on each one.
+    // Spam-gate: applyTerminalAppearance re-runs on every font/opacity/cursor tweak; don't emit CSI 997 each time.
     const transport = fakeTransport()
     const subs = new Map([[1, true]])
     const last = new Map<number, 'dark' | 'light'>()
@@ -140,13 +139,7 @@ describe('maybePushMode2031Flip', () => {
   })
 })
 describe('installMode2031Handlers', () => {
-  // Regression coverage for the "random characters on restart" bug: a restored
-  // xterm buffer may contain `CSI ?2031h` emitted by the previous session's
-  // TUI (e.g. Claude Code). Before the fix, replaying that buffer fired our
-  // CSI handler and pushed `CSI ?997;1n` into the fresh shell via
-  // transport.sendInput — zsh then echoed the literal `^[[?997;1n` onto the
-  // prompt. These tests drive a real headless xterm parser so they cover the
-  // actual parser path, not a mock.
+  // Regression coverage for the "random characters on restart" bug: a replayed `CSI ?2031h` pushed `CSI ?997;1n` into the fresh shell.
 
   function writeSync(term: Terminal, data: string): Promise<void> {
     return new Promise((resolve) => term.write(data, resolve))
@@ -207,16 +200,11 @@ describe('installMode2031Handlers', () => {
   })
 
   it('does NOT fire onSubscribe or record state when the sequence arrives during replay', async () => {
-    // This is the regression: on cold restore the serialized xterm buffer is
-    // replayed through replayIntoTerminal, which sets the replay guard before
-    // xterm parses the bytes. The handler must skip both the push (so no
-    // CSI 997 leaks to the fresh shell) AND the bookkeeping (so a later theme
-    // flip doesn't push either).
+    // On cold restore the replay guard is set before xterm parses, so the handler must skip both the push and the bookkeeping.
     const h = setup()
     try {
       replayIntoTerminal(h.pane, h.replayingPanesRef, '\x1b[?2031h')
-      // write() is async-ish: the guard stays engaged until the
-      // write-completion callback fires. Await parser completion.
+      // write() is async: the replay guard stays engaged until the write-completion callback fires.
       await new Promise<void>((resolve) => h.term.write('', resolve))
 
       expect(h.onSubscribe).not.toHaveBeenCalled()
@@ -230,8 +218,7 @@ describe('installMode2031Handlers', () => {
   })
 
   it('still honors a real `CSI ?2031h` received after a replay window closes', async () => {
-    // If the user relaunches Claude Code after a cold restore, the real TUI
-    // emits `?2031h` itself — that must take effect normally.
+    // A real `?2031h` from a TUI relaunched after cold restore must take effect normally.
     const h = setup()
     try {
       replayIntoTerminal(h.pane, h.replayingPanesRef, '\x1b[?2031h')
@@ -247,10 +234,7 @@ describe('installMode2031Handlers', () => {
   })
 
   it('clears subscribe state on `CSI ?2031l` regardless of replay state', async () => {
-    // The `l` (unsubscribe) branch is intentionally not replay-guarded: a
-    // serialized buffer ending in `?2031l` means the TUI unsubscribed before
-    // shutdown, and clearing our stale bookkeeping is harmless — we only send
-    // on subscribe, never on unsubscribe.
+    // The `l` (unsubscribe) branch is intentionally not replay-guarded: clearing is harmless since we only send on subscribe.
     const h = setup()
     try {
       // Non-replay path: subscribe then unsubscribe clears state.
@@ -262,9 +246,7 @@ describe('installMode2031Handlers', () => {
       expect(h.paneMode2031.has(1)).toBe(false)
       expect(h.paneLastThemeMode.has(1)).toBe(false)
 
-      // Replay path: resubscribe, then receive `?2031l` during a replay
-      // window. The `l` handler must still clear — this is the invariant
-      // promised by the test name.
+      // Replay path: the `l` handler must still clear even during a replay window.
       await writeSync(h.term, '\x1b[?2031h')
       h.paneLastThemeMode.set(1, 'dark')
       expect(h.paneMode2031.get(1)).toBe(true)
@@ -279,22 +261,13 @@ describe('installMode2031Handlers', () => {
   })
 
   it('returns `false` so compound DEC private modes still reach xterm', async () => {
-    // Why: we return `false` from both handlers so compound sequences like
-    // `CSI ?25;2031h` still go through xterm's built-in DEC private mode
-    // handler. If a future refactor accidentally returned `true`, cursor
-    // visibility (and any other unrelated mode sharing the sequence) would
-    // desync. xterm's public API does not expose cursor visibility, so assert
-    // the handler's return value directly via a spy wrapping the real parser.
+    // Why: handlers return `false` so compound sequences like `CSI ?25;2031h` still reach xterm's built-in DEC private mode handler.
     const term = new Terminal({ cols: 80, rows: 24, allowProposedApi: true })
     const paneMode2031 = new Map<number, boolean>()
     const paneLastThemeMode = new Map<number, 'dark' | 'light'>()
     const onSubscribe = vi.fn()
     const returnValues: boolean[] = []
-    // Why the cast: the headless parser's registerCsiHandler callback
-    // returns just `boolean`, but our `Mode2031Parser` type reflects xterm's
-    // canonical `boolean | Promise<boolean>` signature. The spy wraps the
-    // real parser and synchronously records whatever the wrapped handler
-    // returned; in this codebase all mode-2031 handlers are synchronous.
+    // Cast: parser cb returns plain `boolean` but `Mode2031Parser` reflects xterm's `boolean | Promise<boolean>` (handlers here are sync).
     const spyParser: Parameters<typeof installMode2031Handlers>[0]['parser'] = {
       registerCsiHandler: (id, cb) =>
         term.parser.registerCsiHandler(id, (params) => {
@@ -317,8 +290,7 @@ describe('installMode2031Handlers', () => {
       // Our 2031 recording fired:
       expect(paneMode2031.get(1)).toBe(true)
       expect(onSubscribe).toHaveBeenCalledTimes(1)
-      // And every invocation of our handler returned `false`, so xterm's
-      // built-in DEC private mode handler still processes the sequence.
+      // Every handler invocation returned `false`, so xterm's built-in DEC private mode handler still processes the sequence.
       expect(returnValues.length).toBeGreaterThan(0)
       expect(returnValues.every((v) => v === false)).toBe(true)
     } finally {
@@ -330,9 +302,7 @@ describe('installMode2031Handlers', () => {
   })
 
   it('keeps per-pane state isolated when two panes share the parser API', async () => {
-    // Each pane registers its own handlers on its own xterm parser, but the
-    // subscribe bookkeeping map is shared across panes. A replay on pane 1
-    // must not leak into pane 2's live subscribe.
+    // The subscribe bookkeeping map is shared across panes, so a replay on pane 1 must not leak into pane 2's live subscribe.
     const shared2031 = new Map<number, boolean>()
     const sharedLast = new Map<number, 'dark' | 'light'>()
     const replayingPanesRef = makeReplayingRef()
@@ -382,12 +352,7 @@ describe('installMode2031Handlers', () => {
 })
 
 describe('applyTerminalAppearance theme assignment', () => {
-  // xterm's OptionsService fires the theme change on object IDENTITY, and
-  // ThemeService._setTheme then rebuilds the palette, discarding OSC
-  // 4/10/11/12 SET mutations. Attribute-neutral applies (font size, padding,
-  // zoom) compose a fresh-but-value-identical theme; assigning it anyway
-  // wipes TUI color mutations on visible panes while the deduped publisher
-  // keeps hidden overlays — so the assignment must be value-gated.
+  // xterm rebuilds the palette on any new theme-object identity (wiping OSC color mutations), so the assignment must be value-gated.
   function makePane(id: number): ManagedPane {
     return { id, terminal: { options: {}, cols: 80, rows: 24 } } as unknown as ManagedPane
   }
@@ -423,8 +388,7 @@ describe('applyTerminalAppearance theme assignment', () => {
 
     apply(pane, { ...settings, terminalFontSize: settings.terminalFontSize + 2 })
 
-    // Identity-stable theme means xterm never re-runs _setTheme, so a TUI's
-    // modifyColors mutation survives the font tweak.
+    // Identity-stable theme means xterm never re-runs _setTheme, so a TUI's modifyColors mutation survives the font tweak.
     expect(pane.terminal.options.theme).toBe(firstTheme)
     expect(pane.terminal.options.fontSize).toBe(settings.terminalFontSize + 2)
   })
@@ -444,9 +408,7 @@ describe('applyTerminalAppearance theme assignment', () => {
 })
 
 describe('publishTerminalViewAttributesAtAppStart', () => {
-  // Phase 6 prerequisite (terminal-query-authority.md): hidden-at-launch
-  // PTYs can query OSC 10/11 before any terminal pane mounts; the app-start
-  // publication must go out with no pane manager involved at all.
+  // Hidden-at-launch PTYs query OSC 10/11 before any pane mounts; publish with no pane manager (terminal-query-authority.md).
   it('publishes composed attributes without any pane mount and dedupes repeats', () => {
     _resetTerminalViewAttributesPublisherForTest()
     const sent: TerminalViewAttributes[] = []
@@ -476,8 +438,7 @@ describe('publishTerminalViewAttributesAtAppStart', () => {
       publishTerminalViewAttributesAtAppStart(settings, true)
       expect(publishMock).toHaveBeenCalledTimes(1)
 
-      // The first pane mount composes the identical app-global snapshot, so
-      // the publisher dedupe keeps it a single push.
+      // Identical app-global snapshot, so the publisher dedupe keeps it a single push.
       const manager = {
         getPanes: () => [],
         setPaneLigaturesEnabled: vi.fn(),
diff --git a/src/renderer/src/components/terminal-pane/terminal-appearance.ts b/src/renderer/src/components/terminal-pane/terminal-appearance.ts
index cf92bca5c65..40564024d9b 100644
--- a/src/renderer/src/components/terminal-pane/terminal-appearance.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-appearance.ts
@@ -25,65 +25,34 @@ import { publishTerminalViewAttributes } from './terminal-view-attributes-publis
 import { normalizeTerminalLineHeight } from '../../../../shared/terminal-line-height-settings'
 import { maybePushMode2031Flip } from './terminal-mode-2031-replies'
 
-// Why Pick<IParser, ...> over a hand-rolled structural type: keeps the helper
-// tied to xterm's canonical signature so any upstream tightening (added
-// fields on IFunctionIdentifier, narrower param type) surfaces here instead
-// of silently accepting a stale shape.
+// Why Pick over a hand-rolled type: stays tied to xterm's canonical signature so upstream tightening surfaces here.
 type Mode2031Parser = Pick<IParser, 'registerCsiHandler'>
 
 type Mode2031HandlerDeps = {
   paneId: number
   parser: Mode2031Parser
-  /** Called when a real (non-replayed) `CSI ?2031h` arrives, after the
-   *  subscribe flag has been set. Kept as a callback so the lifecycle hook
-   *  can keep its transport-aware `pushMode2031ForPane` closure intact. */
+  /** Called when a real (non-replayed) `CSI ?2031h` arrives, after the subscribe flag is set.
+   *  A callback so the lifecycle hook keeps its transport-aware `pushMode2031ForPane` closure. */
   onSubscribe: () => void
   isReplaying: () => boolean
   paneMode2031: Map<number, boolean>
   paneLastThemeMode: Map<number, 'dark' | 'light'>
 }
 
-// Why split out from the lifecycle hook: the CSI handlers are the defense
-// against a restored xterm buffer pushing `\x1b[?997;1n` into the fresh zsh
-// on cold restore (the "random characters on restart" bug). Keeping them in
-// a pure function lets the tests drive a real xterm parser end-to-end so we
-// catch regressions in the parser-path guard, not just a mock.
+// Why a pure function: lets tests drive a real xterm parser end-to-end against the "random characters on restart" guard.
 export function installMode2031Handlers(deps: Mode2031HandlerDeps): IDisposable[] {
   const hasMode2031 = (params: (number | number[])[]): boolean =>
     params.some((p) => (Array.isArray(p) ? p.includes(2031) : p === 2031))
 
-  // Why return false from both handlers: we only observe mode 2031.
-  // Returning false lets xterm's built-in DEC private mode handler
-  // continue processing the same sequence, so compound sequences like
-  // `CSI ?25;2031h` still update cursor visibility correctly.
+  // Why return false: we only observe mode 2031; false lets xterm's built-in DEC handler still process compound sequences.
   return [
     deps.parser.registerCsiHandler(
       { prefix: '?', final: 'h' },
       guardParserHandler('csi-mode2031-subscribe', (params) => {
         if (hasMode2031(params)) {
-          // Why: a restored xterm buffer may contain `CSI ?2031h` emitted by
-          // the previous session's TUI (e.g. Claude Code). Replaying that
-          // buffer runs this handler, and without the guard we'd push
-          // `CSI ?997;1n` via transport.sendInput into a fresh shell that has
-          // no TUI consuming it — zsh then echoes the literal escape sequence
-          // onto the prompt. The replay guard in pty-connection.ts only covers
-          // xterm's own onData auto-replies, not handler-triggered sends, so
-          // gate explicitly here. We also skip recording the subscribe bit:
-          // the fresh shell is not actually subscribed, so a later theme flip
-          // must not push either. A real TUI that starts up after restore will
-          // re-emit `?2031h` itself and register normally.
-          //
-          // Why this broad guard is safe across all replay sources: the only
-          // replay path that can carry raw `?2031h` is cold-restore scrollback
-          // (pty-connection.ts), which is disk-replayed PTY output against a
-          // fresh shell — the case this guard targets. Daemon snapshot payloads
-          // (`rehydrateSequences + SerializeAddon.serialize()`) and persisted
-          // scrollback (`SerializeAddon.serialize()`) never contain `?2031`:
-          // SerializeAddon's _serializeModes whitelists only ?1h/?66h/?2004h/
-          // [4h/?6h/?45h/?1004h/?7l/mouse modes/?25l, and buildRehydrateSequences
-          // emits only ?1049h/?2004h/?1h/mouse reporting modes. If xterm ever
-          // adds ?2031 to that whitelist, this guard would start suppressing
-          // legitimate subscribes during snapshot reattach — revisit then.
+          // Why gate on isReplaying: a restored buffer's replayed `?2031h` would push `?997;1n` into a fresh shell with no
+          // TUI, which echoes it as literal text; pty-connection's guard covers only xterm auto-replies, not handler sends.
+          // Return early (before recording the subscribe bit) so a later theme flip won't push into a shell that isn't subscribed.
           if (deps.isReplaying()) {
             return false
           }
@@ -93,10 +62,7 @@ export function installMode2031Handlers(deps: Mode2031HandlerDeps): IDisposable[
         return false
       })
     ),
-    // Why no replay guard on the unsubscribe branch: clearing stale bookkeeping
-    // is harmless. We only push CSI 997 on subscribe, never on unsubscribe, so
-    // even if a cold-restore replay carries `?2031l`, this handler just deletes
-    // map entries that a later real `?2031h` will re-populate normally.
+    // Why no replay guard here: we only push CSI 997 on subscribe; unsubscribe just clears map entries, so replay is harmless.
     deps.parser.registerCsiHandler(
       { prefix: '?', final: 'l' },
       guardParserHandler('csi-mode2031-unsubscribe', (params) => {
@@ -128,9 +94,7 @@ export function isHexColor(value: string): boolean {
   return HEX_COLOR_RE.test(value)
 }
 
-// Why: extracted from applyTerminalAppearance so the settings preview can
-// derive the same composed theme without depending on PaneManager. Keep
-// pure — no DOM, no manager, no side effects.
+// Why extracted: lets the settings preview compose the same theme without depending on PaneManager. Keep pure.
 export function composeActiveTerminalTheme(
   baseTheme: ITheme | null,
   settings: Pick<
@@ -141,12 +105,8 @@ export function composeActiveTerminalTheme(
   if (!baseTheme) {
     return null
   }
-  // Why: setting scrollbar.width enables xterm's overview ruler, whose border
-  // defaults to the foreground color and paints a bright vertical line beside
-  // the scrollbar. We only want the slimmer scrollbar, not the ruler chrome.
-  // Why: xterm's default slider alpha (~0.2) is nearly invisible on dark
-  // backgrounds; raise the contrast so the thumb reads. Placed before the
-  // spread so an explicit theme value still wins.
+  // Why transparent ruler border: scrollbar.width enables xterm's overview ruler, whose border would paint a bright line.
+  // Why raised slider alpha: xterm's default (~0.2) is nearly invisible on dark bg. Before the spread so explicit theme wins.
   let theme: ITheme = {
     overviewRulerBorder: 'transparent',
     scrollbarSliderBackground: 'rgba(180, 180, 185, 0.4)',
@@ -154,23 +114,18 @@ export function composeActiveTerminalTheme(
     scrollbarSliderActiveBackground: 'rgba(180, 180, 185, 0.8)',
     ...baseTheme
   }
-  // Why: merge user-imported Ghostty color overrides on top of the resolved
-  // base theme so individual colors can be tweaked without losing the rest.
+  // Why: merge Ghostty color overrides atop the base theme so individual colors can be tweaked without losing the rest.
   if (settings.terminalColorOverrides) {
     theme = { ...theme, ...settings.terminalColorOverrides }
   }
-  // Why: Ghostty's background-opacity controls the terminal's base alpha.
-  // Convert the hex background to rgba so xterm honors it when allowTransparency
-  // is also set on the Terminal instance.
+  // Why: convert the hex background to rgba so xterm honors the opacity when allowTransparency is set.
   if (settings.terminalBackgroundOpacity !== undefined && theme.background) {
     theme = {
       ...theme,
       background: hexToRgba(theme.background, settings.terminalBackgroundOpacity)
     }
   }
-  // Why: Ghostty's cursor-opacity applies alpha to the cursor color. Only
-  // converted when the resolved cursor is a hex value; named CSS colors are
-  // left untouched because hexToRgba expects a hex input.
+  // Why hex-only: hexToRgba expects a hex input, so named CSS cursor colors are left untouched.
   if (settings.terminalCursorOpacity !== undefined && theme.cursor && isHexColor(theme.cursor)) {
     theme = {
       ...theme,
@@ -180,12 +135,8 @@ export function composeActiveTerminalTheme(
   return theme
 }
 
-/** App-start publication (terminal-query-authority.md §Phase 6
- *  prerequisites): hidden-at-launch PTYs can query OSC 10/11 before any
- *  terminal pane mounts, and main's responder is silent-until-first-push.
- *  Composes the same theme applyTerminalAppearance would and publishes it
- *  through the same deduped publisher, so the later pane-mount apply is a
- *  no-op re-push. Returns whether a publish actually went out. */
+/** Publishes composed terminal appearance at app start so hidden-at-launch PTYs can query OSC 10/11
+ *  before any pane mounts (terminal-query-authority.md §Phase 6). Returns whether a publish went out. */
 export function publishTerminalViewAttributesAtAppStart(
   settings: GlobalSettings | null | undefined,
   systemPrefersDark: boolean,
@@ -202,8 +153,7 @@ export function publishTerminalViewAttributesAtAppStart(
     : publishTerminalViewAttributes(theme, appearance.mode, settings)
 }
 
-// Value equality over composed ITheme objects (flat string slots plus the
-// extendedAnsi string array), used to gate the per-pane options.theme write.
+// Value equality over composed ITheme objects (flat string slots plus the extendedAnsi array); gates the options.theme write.
 function composedTerminalThemesEqual(a: ITheme | undefined, b: ITheme): boolean {
   if (!a) {
     return false
@@ -242,10 +192,7 @@ export function applyTerminalAppearance(
   const paneStyles = resolvePaneStyleOptions(settings)
   const baseTheme: ITheme | null = appearance.theme ?? getBuiltinTheme(appearance.themeName)
   const theme = composeActiveTerminalTheme(baseTheme, settings)
-  // View-attribute bridge (Phase 5 slice 2): this is the single point where
-  // the composed app-global terminal appearance exists, so publish it to
-  // main's hidden-PTY query responder here. Deduped inside the publisher —
-  // per-pane re-applies and attribute-neutral tweaks do not re-push.
+  // Publish composed appearance to main's hidden-PTY query responder — the only point it exists; deduped in the publisher.
   publishTerminalViewAttributes(theme, appearance.mode, settings)
   const paneBackground = theme?.background ?? '#000000'
 
@@ -256,19 +203,11 @@ export function applyTerminalAppearance(
   )
 
   for (const pane of manager.getPanes()) {
-    // Why value-gated: xterm's OptionsService fires on object identity, and
-    // ThemeService._setTheme rebuilds the palette, discarding TUI OSC
-    // 4/10/11/12 SET mutations. Attribute-neutral applies (font size/family,
-    // line height, padding, per-pane zoom) compose a fresh-but-identical
-    // theme; skipping the write keeps visible-pane mutations alive (a
-    // pre-existing loss this also fixes) and matches the hidden responder's
-    // deduped overlay behavior, so hidden and visible no longer drift.
+    // Why value-gated: writing options.theme rebuilds the palette, discarding TUI OSC 4/10/11/12 mutations; skip on no-op change.
     if (theme && !composedTerminalThemesEqual(pane.terminal.options.theme, theme)) {
       pane.terminal.options.theme = theme
     }
-    // Why: xterm's allowTransparency has measurable rendering cost, so clear
-    // it explicitly when opacity is at (or above) 1 to avoid a stale `true`
-    // bleeding in from a prior opacity setting that has since been reset.
+    // Why clear explicitly: allowTransparency has rendering cost and a stale `true` could bleed in from a prior opacity.
     pane.terminal.options.allowTransparency =
       settings.terminalBackgroundOpacity !== undefined && settings.terminalBackgroundOpacity < 1
     const cursorStyle = settings.terminalCursorStyle ?? 'block'
@@ -286,24 +225,13 @@ export function applyTerminalAppearance(
     pane.terminal.options.fastScrollSensitivity = normalizeTerminalFastScrollSensitivity(
       settings.terminalFastScrollSensitivity
     )
-    // Why: xterm's macOptionIsMeta only flips on the 'true' mode. 'left' and
-    // 'right' are handled in the keydown policy (terminal-shortcut-policy),
-    // which needs Option to stay composable at the xterm level for the
-    // non-Meta side. Treating only 'true' as Meta here matches the pre-
-    // detection behavior; the detection layer simply decides *what* value
-    // `effectiveMacOptionAsAlt` carries.
+    // Why only 'true': 'left'/'right' are handled in the keydown policy, which needs Option composable at the xterm level.
     pane.terminal.options.macOptionIsMeta = effectiveMacOptionAsAlt === 'true'
     pane.terminal.options.lineHeight = normalizeTerminalLineHeight(settings.terminalLineHeight)
-    // Why call unconditionally: the per-pane helper is a no-op when the
-    // current addon state already matches, so passing the resolved value on
-    // every appearance apply keeps newly-created panes in sync without a
-    // separate hook and lets live toggles (settings change, font swap)
-    // land immediately.
+    // Why unconditional: the helper no-ops when addon state already matches, so this keeps new panes and live toggles in sync.
     manager.setPaneLigaturesEnabled(pane.id, ligaturesEnabled)
     const transport = paneTransports.get(pane.id)
-    // Why: skip PTY resize when a mobile-fit override is active — the PTY
-    // is already at the correct phone dimensions and must not be resized
-    // back to desktop dimensions by an appearance change.
+    // Why: PTY is already at phone dimensions under a mobile-fit override — don't resize it back to desktop.
     const appearancePtyId = transport?.getPtyId()
     if (transport?.isConnected() && (!appearancePtyId || !getFitOverrideForPty(appearancePtyId))) {
       maybePushMode2031Flip(pane.id, appearance.mode, transport, paneMode2031, paneLastThemeMode)
diff --git a/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts b/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts
index d58460161ab..8261e1a66c2 100644
--- a/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts
@@ -1,13 +1,9 @@
 /**
  * Parked terminal tab watcher lifecycle.
  *
- * Why: parking unmounts a tab's TerminalPane, so its PTYs lose the renderer
- * byte parsers. This module owns the pane-less replacement: it remembers the
- * unmounted panes' identities (pane id / leaf id), starts one
- * parked-terminal-byte-watcher per PTY when a tab parks, and disposes them on
- * reveal, tab close, PTY exit, or worktree teardown. The bookkeeping maps
- * live in terminal-parked-watcher-registry so the terminals store slice can
- * dispose watchers without importing this store-coupled module.
+ * Why: parking unmounts a tab's TerminalPane, so its PTYs lose the renderer byte
+ * parsers. This module runs a pane-less byte watcher per PTY while parked and
+ * disposes them on reveal, tab close, PTY exit, or worktree teardown.
  */
 import { isTerminalLeafId } from '../../../../shared/stable-pane-id'
 import type { TerminalTab } from '../../../../shared/types'
@@ -30,8 +26,7 @@ import {
   type ParkedTerminalPaneCapture
 } from './terminal-parked-watcher-registry'
 
-// Why: re-exported so park wiring keeps one import surface; the registry
-// split exists only to break the store-slice import cycle.
+// Why: re-export so callers keep one import surface; the registry split only breaks the store-slice import cycle.
 export {
   captureParkedTerminalPaneCandidates,
   disposeAllParkedTerminalWatchers,
@@ -53,11 +48,7 @@ type ParkedPaneFallbackState = {
   runtimePaneTitlesByTabId: ReturnType<typeof useAppStore.getState>['runtimePaneTitlesByTabId']
 }
 
-// Why: if no unmount capture exists (or it predates a PTY respawn), derive
-// pane identities from the persisted layout snapshot. Numeric pane ids are
-// unknown here: reuse the single existing runtime-title slot when unambiguous
-// so a stale "working" title still gets overwritten, otherwise use negative
-// slots that can never collide with real PaneManager ids.
+// Why: pane ids are unknown in this layout fallback; reuse the sole runtime-title slot when unambiguous to overwrite a stale title, else negative slots that can't collide with real PaneManager ids.
 export function fallbackParkedPaneCandidates(
   tab: ParkableTerminalTabModel,
   state: ParkedPaneFallbackState
@@ -79,16 +70,13 @@ export function fallbackParkedPaneCandidates(
   }))
 }
 
-// Why: unmount captures and layout fallbacks must resolve identically for the
-// watcher start path and the park-eligibility coverage check, or a tab could
-// pass the check and then start with different (uncoverable) candidates.
+// Why: start path and eligibility check must resolve identical candidates, or a tab passes the check then starts uncoverable.
 function resolveParkedTerminalPaneCandidates(
   tab: ParkableTerminalTabModel,
   state: ParkedPaneFallbackState
 ): ParkedTerminalPaneCapture[] {
   const captured = capturedPanesByTabId.get(tab.id)
-  // Why: a capture that no longer mentions the tab's current PTY is stale
-  // (the PTY was re-minted since the unmount); fall back to the layout.
+  // Why: a capture missing the tab's current PTY is stale (PTY re-minted since unmount); fall back to the layout.
   const capturedIsCurrent =
     captured !== undefined &&
     captured.panes.length > 0 &&
@@ -97,17 +85,14 @@ function resolveParkedTerminalPaneCandidates(
 }
 
 /**
- * Whether the parked byte watchers can fully cover this tab's PTYs (some
- * candidate exists and every candidate has a snapshot-backed PTY bound to a
- * valid leaf). Hosts must refuse to park a tab that fails this check —
- * parking it would silently drop bell/title/completion side effects, the
- * exact failure that sank the first parking attempt.
+ * Whether parked byte watchers can fully cover this tab's PTYs (every candidate
+ * has a snapshot-backed PTY on a valid leaf). Hosts must refuse to park a tab
+ * that fails this check, or bell/title/completion side effects silently drop.
  */
 export function canWatcherCoverParkedTerminalTab(
   worktreeId: string,
   tab: ParkableTerminalTabModel,
-  // Why: cold activation needs stronger provider snapshot support because the
-  // view has never mounted; ordinary parking can reattach a previously mounted v19 view.
+  // Why: cold activation needs stronger snapshot support (view never mounted); ordinary parking can reattach a mounted view.
   isPtyEligible: ParkedTerminalPtyEligibility = allowSnapshotBackedPty
 ): boolean {
   const panes = resolveParkedTerminalPaneCandidates(tab, useAppStore.getState())
@@ -134,10 +119,7 @@ function startParkedTabWatchers(
   const paneIdByPtyId = new Map<string, number>()
   for (const pane of panes) {
     const ptyId = pane.ptyId
-    // Why: the park policy already excludes non-snapshot-backed PTYs, but the
-    // tab model can change between the park decision and this effect — guard
-    // again so remote-runtime/SSH PTYs never get a local watcher. Legacy
-    // non-UUID leaf ids are skipped because makePaneKey throws on them.
+    // Why: re-guard — the tab model can change after the park decision, and legacy non-UUID leaf ids make makePaneKey throw.
     if (
       !ptyId ||
       disposersByPtyId.has(ptyId) ||
@@ -154,34 +136,24 @@ function startParkedTabWatchers(
       leafId: pane.leafId,
       paneId: pane.paneId,
       drivesTabTitle: pane.drivesTabTitle,
-      // Why: seed the watcher's agent tracker with the pane's last known
-      // title so an agent already working at park time still notifies when
-      // it finishes while parked.
+      // Why: seed the agent tracker with the last title so an agent working at park time still notifies on finish.
       ...(initialTitle !== undefined ? { initialTitle } : {}),
       ...(restoreTitleOnRegister ? { restoreTitleOnRegister: true } : {}),
-      // Why: no pane transport exists while parked; write straight to the
-      // PTY, the same channel background agent launches use.
+      // Why: no pane transport while parked, so write straight to the PTY (same channel as background launches).
       sendInput: (data) => window.api.pty.write(ptyId, data)
     })
-    // Why: a PTY that exits while parked has no pane to run exit cleanup; at
-    // minimum its watcher must not outlive it.
+    // Why: a PTY exiting while parked has no pane for cleanup, so its watcher must not outlive it.
     const unsubscribeExit = subscribeToPtyExit(ptyId, (_code, { hadPrimary }) => {
-      // Why: while parked this sidecar is the ONLY exit observer — the hosts'
-      // onPtyExit runs from a mounted TerminalPane. Run the observed-exit
-      // teardown here or a sole tab survives, while a dead split leaf can
-      // reattach on reveal and resurrect its exited session as a fresh shell.
+      // Why: while parked this sidecar is the only exit observer, so teardown must run here or dead leaves resurrect on reveal.
       useAppStore.getState().clearRuntimePaneTitle(tab.id, pane.paneId)
       if (hadPrimary) {
-        // Why: detach intentionally retains the pane transport's primary exit
-        // owner. It already performs the tab/leaf close; this sidecar only
-        // retires parked observation so one exit cannot queue two confirms.
+        // Why: primary exit owner already closes the tab/leaf; just retire parked observation so one exit can't double-confirm.
         disposersByPtyId.get(ptyId)?.()
         disposersByPtyId.delete(ptyId)
         return
       }
       if (disposersByPtyId.size > 1) {
-        // Why: this dead split leaf has no future mount. Consume its buffered
-        // frame and exit, and tombstone duplicate exit notifications.
+        // Why: dead split leaf never remounts; consume its buffered frame and tombstone duplicate exits.
         discardPreHandlerPtyState(ptyId)
         collapseParkedExitedLeaf(tab.id, ptyId)
         disposersByPtyId.get(ptyId)?.()
@@ -189,14 +161,11 @@ function startParkedTabWatchers(
         return
       }
 
-      // Why: the close may wait on pinned-tab confirmation. Dispose side
-      // effects now but retain the empty registry entry so parking does not
-      // restart a watcher against the dead PTY while the dialog is pending.
+      // Why: keep the empty entry so a pending pinned-close confirm can't let parking restart a watcher on the dead PTY.
       disposersByPtyId.get(ptyId)?.()
       disposersByPtyId.delete(ptyId)
       closeTerminalTab(tab.id, {
-        // Why: this autonomous PTY exit still needs the parked pinned-tab
-        // confirmation flow, but it must not become user reopen history.
+        // Why: autonomous PTY exit still needs pinned-tab confirmation but must not enter reopen history.
         captureRecentlyClosed: false,
         onClosed: () => {
           discardPreHandlerPtyState(ptyId)
@@ -205,8 +174,7 @@ function startParkedTabWatchers(
             parkedWatchersByTabId.delete(tab.id)
           }
         },
-        // Why: cancellation keeps the buffered final frame and exit for the
-        // reveal-mounted pane, matching a pinned terminal that exited mounted.
+        // Why: cancellation keeps the buffered final frame/exit for the reveal-mounted pane.
         onCancel: () => {}
       })
     })
@@ -216,8 +184,7 @@ function startParkedTabWatchers(
       disposeWatcher()
     })
   }
-  // Why: tracked even with zero watchers so parked-state introspection
-  // (window.__terminalParkingDebug) reflects every parked tab.
+  // Why: track even with zero watchers so window.__terminalParkingDebug reflects every parked tab.
   parkedWatchersByTabId.set(tab.id, {
     worktreeId,
     tabPtyId: tab.ptyId,
@@ -227,13 +194,11 @@ function startParkedTabWatchers(
 }
 
 /**
- * Hosts call this from their onPtyExit handlers before closing the tab.
- * Returns true when the close must be deferred: a parked tab has no
- * PaneManager to promote split siblings, so the live exit path degenerates to
- * "close the whole tab" — which would kill the surviving sibling panes. The
- * reveal remount handles dead PTYs per leaf instead. Single-leaf parked tabs
- * return false so exit→closeTab parity is preserved. Also clears the dead
- * leaf's runtime-title slot so a stale title cannot pin worktree status.
+ * Called from hosts' onPtyExit before closing the tab; returns true to defer.
+ * A parked tab has no PaneManager to promote split siblings, so the live exit
+ * path would close the whole tab and kill surviving siblings — reveal remount
+ * handles dead PTYs per leaf instead. Single-leaf tabs return false to keep
+ * exit→closeTab parity. Also clears the dead leaf's runtime-title slot.
  */
 export function shouldDeferParkedPtyExitTabClose(tabId: string, ptyId: string): boolean {
   const entry = parkedWatchersByTabId.get(tabId)
@@ -247,18 +212,13 @@ export function shouldDeferParkedPtyExitTabClose(tabId: string, ptyId: string):
   const remaining = entry.disposersByPtyId.size
   if (remaining === 0) {
     if (paneId !== undefined) {
-      // Why: an empty entry is the cancelled/pending pinned-close tombstone.
-      // The reveal-mounted pane owns the buffered exit now, so suppress its
-      // close once and drop the registry tombstone.
+      // Why: empty entry is the pinned-close tombstone; the reveal-mounted pane owns the exit, so suppress once and drop it.
       parkedWatchersByTabId.delete(tabId)
       return true
     }
     return false
   }
-  // Why: this runs from the PTY exit handler, before the exit sidecar above
-  // removes the dead PTY's watcher — so the watcher count still includes the
-  // exiting PTY. More than one watcher (or an exit for an unwatched PTY)
-  // means live sibling leaves remain.
+  // Why: runs before the sidecar removes the dead watcher, so >1 (or an unwatched PTY) means live siblings remain.
   const defer = remaining > 1 || !entry.disposersByPtyId.has(ptyId)
   if (defer) {
     collapseParkedExitedLeaf(tabId, ptyId)
@@ -266,12 +226,7 @@ export function shouldDeferParkedPtyExitTabClose(tabId: string, ptyId: string):
   return defer
 }
 
-// Why: deferring the tab close is not enough — a stale leaf binding left in
-// the stored layout reattaches on reveal, and the daemon re-creates the exited
-// session id as a fresh shell, resurrecting a pane whose shell already ended.
-// With no PaneManager mounted, the observed-exit teardown's data half runs
-// here instead: collapse the leaf out of the stored layout so the reveal
-// replays only the surviving panes.
+// Why: collapse the leaf from the stored layout so reveal can't reattach and resurrect the exited shell.
 function collapseParkedExitedLeaf(tabId: string, ptyId: string): void {
   const state = useAppStore.getState()
   const layout = state.terminalLayoutsByTabId[tabId]
@@ -308,8 +263,7 @@ function disposeClosedParkedTabWatchers(
   tabId: string,
   entry: { paneIdByPtyId: ReadonlyMap<string, number> }
 ): void {
-  // Why: another queued pinned-close request may close the tab before this
-  // exit request resolves. No pane can drain its retained final frame then.
+  // Why: a queued pinned-close may close the tab first, leaving no pane to drain retained frames.
   for (const ptyId of entry.paneIdByPtyId.keys()) {
     discardPreHandlerPtyState(ptyId)
   }
@@ -318,9 +272,8 @@ function disposeClosedParkedTabWatchers(
 
 /**
  * Reconciles watchers for one worktree against its rendered parked set.
- * Callers run this from an effect keyed on the committed render state, so
- * disposal lands in the same effect flush as a reveal remount (before any
- * PTY data IPC can be delivered) and start lands after the park unmount.
+ * Run from an effect keyed on committed render state so disposal shares the
+ * reveal remount's flush (before PTY data IPC) and start follows the park unmount.
  */
 export function syncParkedTerminalTabWatchers(args: {
   worktreeId: string
@@ -342,8 +295,7 @@ export function syncParkedTerminalTabWatchers(args: {
       disposeParkedTabWatchers(tabId)
     }
   }
-  // Why: captures for closed tabs have no future park/reveal; drop them so
-  // the registry stays bounded by live tabs.
+  // Why: closed tabs never park/reveal again; drop captures to keep the registry bounded.
   for (const [tabId, capture] of capturedPanesByTabId) {
     if (capture.worktreeId === args.worktreeId && !liveTabIds.has(tabId)) {
       capturedPanesByTabId.delete(tabId)
diff --git a/src/renderer/src/components/terminal-pane/terminal-shortcut-policy.ts b/src/renderer/src/components/terminal-pane/terminal-shortcut-policy.ts
index 976cfa9bb7a..b4029037a68 100644
--- a/src/renderer/src/components/terminal-pane/terminal-shortcut-policy.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-shortcut-policy.ts
@@ -13,8 +13,7 @@ export type TerminalShortcutEvent = {
 
 export type MacOptionAsAlt = 'true' | 'false' | 'left' | 'right'
 
-// Why: macOS composition replaces event.key for punctuation, so we map
-// event.code to the unmodified character for Esc+ sequences.
+// Why: macOS composition rewrites event.key for punctuation, so map event.code to the unmodified char for Esc+ sequences.
 const PUNCTUATION_CODE_MAP: Record<string, string> = {
   Period: '.',
   Comma: ',',
@@ -49,8 +48,7 @@ function kittyAltModifiers(shiftKey: boolean): number {
   return shiftKey ? 4 : 3
 }
 
-/** The un-shifted ASCII character for a physical key code (letters, digits,
- *  and the punctuation map above), or undefined for unmapped codes. */
+/** Un-shifted ASCII character for a physical key code (letters, digits, punctuation map), or undefined. */
 function resolveUnshiftedCharacterForCode(code: string | undefined): string | undefined {
   if (!code) {
     return undefined
@@ -65,9 +63,8 @@ function resolveUnshiftedCharacterForCode(code: string | undefined): string | un
 }
 
 /**
- * Resolves terminal keyboard events before xterm receives them.
- * Keeps configurable Orca shortcuts and terminal byte fallbacks in one
- * platform-aware policy so renderer handlers do not duplicate key checks.
+ * Resolves terminal keyboard events before xterm receives them, centralizing
+ * Orca shortcuts and terminal byte fallbacks in one platform-aware policy.
  */
 export function resolveTerminalShortcutAction(
   event: TerminalShortcutEvent,
@@ -76,30 +73,20 @@ export function resolveTerminalShortcutAction(
   optionKeyLocation: number = 0,
   isWindows: boolean = false,
   keybindings?: KeybindingOverrides,
-  // Why: lazily reports whether the active pane is a local native Windows
-  // ConPTY. Only consulted for Ctrl+Arrow, so execution-host lookup stays off
-  // every other keystroke.
+  // Why: lazy so execution-host lookup (local native Windows ConPTY) runs only on Ctrl+Arrow, not every keystroke.
   isLocalWindowsConptyPane?: () => boolean,
-  // Why: lazily reports whether the active pane's application has enabled the
-  // kitty keyboard protocol (CSI > u). Gates the Option-as-Alt compensation
-  // below on the application's own opt-in, so shells keep composition.
+  // Why: gates Option-as-Alt compensation on the app's own kitty-protocol (CSI > u) opt-in, so shells keep composition.
   isKittyKeyboardActivePane?: () => boolean,
-  // Why: kitty key reports carry the key's unshifted codepoint in the active
-  // layout; the physical-code table above is US QWERTY and reports the wrong
-  // key on Dvorak/Colemak/AZERTY-class layouts. This resolves through
-  // Chromium's KeyboardLayoutMap when it is available.
+  // Why: the physical-code table above is US QWERTY; resolve via Chromium's KeyboardLayoutMap for Dvorak/Colemak/AZERTY layouts.
   layoutBaseCharacterForCode?: (code: string) => string | undefined,
-  // Why: lazily resolves the active pane's Windows encoding. Only consulted for
-  // Shift+Enter so agent-state lookup stays off every other keystroke.
+  // Why: lazy so agent-state lookup for the pane's Windows encoding runs only on Shift+Enter, not every keystroke.
   getWindowsShiftEnterEncoding?: () => WindowsShiftEnterEncoding,
-  // Why: keybindings follow the client OS, but terminal byte protocols follow
-  // the PTY host. They differ for macOS clients attached to Windows runtimes.
+  // Why: keybindings follow the client OS, but byte protocols follow the PTY host — they differ for macOS clients on Windows runtimes.
   isWindowsTerminalHost: () => boolean = () => isWindows
 ): TerminalShortcutAction | null {
   const platform: NodeJS.Platform = isMac ? 'darwin' : isWindows ? 'win32' : 'linux'
 
-  // Why: native-only chords must be captured even on repeat without blocking
-  // the OS default that performs the input-source switch.
+  // Why: capture this chord even on repeat without blocking the OS default input-source switch.
   if (keybindingMatchesAction('terminal.switchInputSource', event, platform, keybindings)) {
     return { type: 'switchInputSource' }
   }
@@ -161,12 +148,10 @@ export function resolveTerminalShortcutAction(
     event.shiftKey &&
     event.key === 'Enter'
   ) {
-    // Why: negotiated KKP is authoritative on every host; trusted pane
-    // evidence additionally preserves Droid's Windows encoding without KKP.
+    // Why: negotiated KKP is authoritative everywhere; trusted pane evidence also preserves Droid's Windows encoding without KKP.
     const windowsHost = isWindowsTerminalHost()
     const hasTrustedWindowsCsiU = windowsHost && getWindowsShiftEnterEncoding?.() === 'csi-u'
-    // Why: CSI-u is application input, not a universal terminal sequence.
-    // Without trusted Windows agent evidence, require active KKP negotiation.
+    // Why: CSI-u is application input, not universal; without trusted Windows evidence, require active KKP negotiation.
     const canSendCsiU = hasTrustedWindowsCsiU || isKittyKeyboardActivePane?.() === true
     return { type: 'sendInput', data: canSendCsiU ? '\x1b[13;2u' : '\x1b\r' }
   }
@@ -178,13 +163,7 @@ export function resolveTerminalShortcutAction(
     !event.shiftKey &&
     event.key === 'Enter'
   ) {
-    // Why: xterm.js collapses Ctrl+Enter to a bare CR, so TUIs that expect
-    // modified Enter chords never receive the distinct input and treat it as
-    // plain Enter. Forward the kitty CSI-u sequence directly (modifier code
-    // 5 = Ctrl; cf. 2 = Shift above) so cue/queue behavior reaches the TUI.
-    // Sibling of the Shift+Enter case; a Windows fallback is not added yet
-    // because, unlike #2418's Codex-on-PowerShell inertness, no Windows TUI is
-    // known to drop the CSI-u form for Ctrl+Enter.
+    // Why: xterm.js collapses Ctrl+Enter to a bare CR, so forward kitty CSI-u (modifier 5 = Ctrl) so the chord reaches TUIs; no Windows fallback yet (#2418).
     return { type: 'sendInput', data: '\x1b[13;5u' }
   }
 
@@ -205,18 +184,14 @@ export function resolveTerminalShortcutAction(
     if (event.key === 'Delete') {
       return { type: 'sendInput', data: '\x0b' }
     }
-    // Why: Cmd+←/→ on macOS conventionally moves to start/end of line in
-    // terminals (iTerm2, Ghostty). xterm.js has no default mapping for
-    // Cmd+Arrow, so we translate to readline's Ctrl+A (\x01) / Ctrl+E (\x05),
-    // which work universally across bash/zsh/fish and most TUI editors.
+    // Why: xterm.js has no Cmd+Arrow mapping; translate Cmd+←/→ to readline Ctrl+A/Ctrl+E for line start/end (iTerm2/Ghostty).
     if (event.key === 'ArrowLeft') {
       return { type: 'sendInput', data: '\x01' }
     }
     if (event.key === 'ArrowRight') {
       return { type: 'sendInput', data: '\x05' }
     }
-    // Why: macOS terminal users expect Cmd+↑/↓ to jump through scrollback
-    // without writing escape bytes into the shell.
+    // Why: macOS users expect Cmd+↑/↓ to scroll scrollback, not write escape bytes to the shell.
     if (event.key === 'ArrowUp') {
       return { type: 'scrollViewport', position: 'top' }
     }
@@ -232,8 +207,7 @@ export function resolveTerminalShortcutAction(
     !event.shiftKey &&
     event.key === 'Backspace'
   ) {
-    // Why: a kitty-protocol TUI binds the CSI 127;3u that xterm's kitty
-    // encoder emits natively; the legacy \x1b\x7f fallback would bypass it.
+    // Why: a kitty-protocol TUI binds the CSI 127;3u xterm emits natively; the legacy \x1b\x7f fallback would bypass it.
     if (isKittyKeyboardActivePane?.()) {
       return null
     }
@@ -247,17 +221,11 @@ export function resolveTerminalShortcutAction(
     !event.shiftKey &&
     (event.key === 'ArrowLeft' || event.key === 'ArrowRight')
   ) {
-    // Why: a kitty-protocol TUI binds alt+arrow via the CSI 1;3D / 1;3C that
-    // xterm's kitty encoder emits natively; \eb/\ef would reach it as alt+b/f.
+    // Why: a kitty-protocol TUI binds alt+arrow via xterm's native CSI 1;3D/C; \eb/\ef would reach it as alt+b/f.
     if (isKittyKeyboardActivePane?.()) {
       return null
     }
-    // Why: xterm.js would otherwise emit \e[1;3D / \e[1;3C for option/alt+arrow,
-    // which default readline (bash, zsh) does not bind to backward-word /
-    // forward-word — so word navigation silently doesn't work without a custom
-    // inputrc. Translate to \eb / \ef (readline's default word-nav bindings) so
-    // option+←/→ on macOS and alt+←/→ on Linux/Windows behave like they do in
-    // iTerm2's "Esc+" option-key mode. Platform-agnostic: both produce altKey.
+    // Why: readline doesn't bind xterm's \e[1;3D/C for alt+←/→, so translate to \eb/\ef for word-nav (iTerm2 "Esc+" behavior).
     return { type: 'sendInput', data: event.key === 'ArrowLeft' ? '\x1bb' : '\x1bf' }
   }
 
@@ -269,46 +237,17 @@ export function resolveTerminalShortcutAction(
     !event.shiftKey &&
     (event.key === 'ArrowLeft' || event.key === 'ArrowRight')
   ) {
-    // Why: local Windows ConPTY shells (PowerShell/cmd via PSReadLine) already
-    // bind Ctrl+←/→ to word-nav, and they treat \eb/\ef (Alt+b/f) as
-    // Escape→RevertLine followed by a self-inserted "b"/"f" — so the translation
-    // below prints a stray letter instead of moving the cursor (issue: Ctrl+→
-    // types "b"/"f" in PowerShell). Defer to xterm's native \e[1;5D / \e[1;5C
-    // there. Remote/WSL panes on a Windows client run readline and still need
-    // the translation, so this is gated on a genuine local native ConPTY, not
-    // merely on the client being Windows.
+    // Why: local Windows ConPTY (PSReadLine) binds Ctrl+←/→ itself; sending \eb/\ef prints stray b/f. Remote/WSL run readline.
     if (isLocalWindowsConptyPane?.()) {
       return null
     }
-    // Why: default readline (bash, zsh) does not bind the \e[1;5D / \e[1;5C that
-    // xterm.js emits for Ctrl+←/→, so Linux and remote/WSL shells need the
-    // translation to \eb / \ef (same bytes as our Alt+Arrow rule) for word-nav
-    // to work without a custom inputrc.
-    //
-    // Mac-gated: Ctrl+Arrow on macOS is reserved for Mission Control / Spaces
-    // navigation at the OS level and should never reach the app.
+    // Why: readline ignores xterm's \e[1;5D/C, so translate Ctrl+←/→ to \eb/\ef for word-nav; !isMac since Mac reserves Ctrl+Arrow.
     return { type: 'sendInput', data: event.key === 'ArrowLeft' ? '\x1bb' : '\x1bf' }
   }
 
-  // Why: with macOptionIsMeta disabled (to let non-US keyboard layouts compose
-  // characters like @ and €), xterm.js no longer translates Option+letter into
-  // Esc+letter automatically. We match on event.code (physical key) rather than
-  // event.key because macOS composition replaces event.key with the composed
-  // character (e.g. Option+B reports key='∫', not key='b').
-  //
-  // The handling depends on the macOptionAsAlt setting (mirrors Ghostty):
-  // - 'true':  xterm handles all Option as Meta natively; nothing to do here.
-  // - kitty-protocol pane (any other mode): the TUI asked for modifier-accurate
-  //   keys, so every Option chord is encoded as kitty CSI-u with the physical
-  //   base key (Option+P → \x1b[112;3u). Without this, xterm's kitty encoder
-  //   reports the composed codepoint (alt+π), which no TUI binds — the chord
-  //   neither triggers the hotkey nor types the character (issue: OMP Alt+P /
-  //   Alt+M dead on compose layouts). Dead keys are exempt so composition
-  //   (Option+E → ´) keeps working.
-  // - 'false': compensate the three most critical readline shortcuts (B/F/D).
-  // - 'left'/'right': the designated Option key acts as full Meta (emit Esc+
-  //   for any single letter); the other key composes, with B/F/D compensated.
+  // Why: macOptionIsMeta stays off so non-US layouts can compose @/€; match event.code since composition rewrites event.key.
   if (isMac && !event.metaKey && !event.ctrlKey && event.altKey && macOptionAsAlt !== 'true') {
+    // Why: kitty pane — encode the physical base key as CSI-u; the composed codepoint (alt+π) binds nothing, Dead keys exempt to keep composition.
     if (event.key !== 'Dead' && isKittyKeyboardActivePane?.()) {
       const baseCharacter =
         (event.code ? layoutBaseCharacterForCode?.(event.code) : undefined) ??
@@ -322,10 +261,7 @@ export function resolveTerminalShortcutAction(
     }
 
     if (!event.shiftKey) {
-      // Why: event.location on a character key reports that key's position
-      // (always 0 for standard keys), NOT which modifier is held. The caller
-      // must track the Option key's own keydown location and pass it as
-      // optionKeyLocation.
+      // Why: event.location reflects the char key, not the held modifier, so the caller supplies Option's tracked keydown location.
       const isLeftOption = optionKeyLocation === 1
       const isRightOption = optionKeyLocation === 2
 
@@ -333,16 +269,13 @@ export function resolveTerminalShortcutAction(
         (macOptionAsAlt === 'left' && isLeftOption) || (macOptionAsAlt === 'right' && isRightOption)
 
       if (shouldActAsMeta) {
-        // Emit Esc+key (e.g. Option+B → \x1bb) for letters, digits, and
-        // mapped punctuation.
         const character = resolveUnshiftedCharacterForCode(event.code)
         if (character) {
           return { type: 'sendInput', data: `\x1b${character}` }
         }
       }
 
-      // In 'false', 'left', or 'right' mode, the compose-side Option key still
-      // needs the three most critical readline shortcuts patched.
+      // Compose-side Option still needs the critical readline shortcuts (B/F/D) patched.
       if (!shouldActAsMeta) {
         if (event.code === 'KeyB') {
           return { type: 'sendInput', data: '\x1bb' }
diff --git a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
index 90bdd83d304..05ddb589fc1 100644
--- a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
+++ b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
@@ -134,12 +134,10 @@ import {
 } from './terminal-pane-close-identity'
 
 export function resetTerminalKeyboardProtocolAfterInterrupt(terminal: Terminal): void {
-  // Use the guarded output path so a certified/throwing xterm cannot escape a
-  // keyboard handler or retain more writes while pane recovery is delayed.
+  // Guarded output path so a throwing xterm can't escape the key handler.
   writeTerminalOutput(terminal, RESET_KITTY_KEYBOARD_PROTOCOL, {
     foreground: true,
-    // The interrupt itself already took the synchronous input path. Queue the
-    // renderer reset so it cannot flush a PTY backlog inside the key handler.
+    // Queue the reset so it can't flush a PTY backlog inside the key handler.
     latencySensitive: false
   })
 }
@@ -207,8 +205,7 @@ type UseTerminalPaneLifecycleDeps = {
   cwd?: string
   startup?: {
     command: string
-    /** Renderer-delivered startup input for callers that need xterm paste
-     *  semantics before the submit Enter. */
+    /** Startup input needing xterm paste semantics before the submit Enter. */
     delivery?: 'terminal-paste'
     startupCommandDelivery?: StartupCommandDelivery
     env?: Record<string, string>
@@ -218,24 +215,20 @@ type UseTerminalPaneLifecycleDeps = {
     draftPrompt?: string
     /** Initial prompt-start status for agents that lack native prompt hooks. */
     initialAgentStatus?: { agent: TuiAgent; prompt: string }
-    /** Telemetry payload for `agent_started`. Forwarded to `pty:spawn`
-     *  so main fires the event only after the spawn succeeds. */
+    /** Telemetry for `agent_started`; forwarded to `pty:spawn` so main fires it only after spawn succeeds. */
     telemetry?: EventProps<'agent_started'>
     /** Show the restored-session banner when this startup command mounts. */
     showSessionRestoredBanner?: boolean
     /** Initial startup may be paired with a setup split that changes its grid. */
     waitForSetupSplitDirection?: SetupSplitDirection
   } | null
-  /** When present, the initial pane boots clean and a split pane is created
-   *  (vertical or horizontal per the user setting) to run the setup command —
-   *  keeping the main terminal interactive. */
+  /** Split pane runs the setup command so the main terminal stays interactive. */
   setupSplit?: {
     command: string
     env?: Record<string, string>
     direction: SetupSplitDirection
   } | null
-  /** When present, a split pane is created to run the repo's configured
-   *  issue-automation command with the linked issue number interpolated. */
+  /** Split pane runs the repo's issue-automation command with the issue number interpolated. */
   issueCommandSplit?: { command: string; env?: Record<string, string> } | null
   isActive: boolean
   isVisible: boolean
@@ -243,9 +236,7 @@ type UseTerminalPaneLifecycleDeps = {
   settings: GlobalSettings | null | undefined
   settingsRef: React.RefObject<GlobalSettings | null | undefined>
   requestOpenLinksInAppPreference: TerminalLinkRoutingPreferenceRequester
-  /** Resolved Option-as-Alt value: `'auto'` has already been mapped to
-   *  `'true' | 'false'` via the keyboard-layout probe. Passed separately
-   *  from `settings` because the probe lives outside the settings store. */
+  /** Resolved Option-as-Alt: `'auto'` already mapped to `'true'|'false'` via the layout probe, which lives outside the settings store. */
   effectiveMacOptionAsAlt: EffectiveMacOptionAsAlt
   effectiveMacOptionAsAltRef: React.RefObject<EffectiveMacOptionAsAlt>
   initialLayoutRef: React.RefObject<TerminalLayoutSnapshot>
@@ -256,9 +247,7 @@ type UseTerminalPaneLifecycleDeps = {
   >
   paneFontSizesRef: React.RefObject<Map<number, number>>
   paneTransportsRef: React.RefObject<Map<number, PtyTransport>>
-  /** Shared map of per-pane live cwd, populated by the OSC 7 handler
-   *  installed in onPaneCreated. Exposed to TerminalPane so keyboard and
-   *  context-menu split handlers can read it synchronously for cache hits. */
+  /** Per-pane live cwd (from the OSC 7 handler); read synchronously by split handlers for cache hits. */
   paneCwdRef: React.RefObject<PaneCwdMap>
   paneMode2031Ref: React.RefObject<Map<number, boolean>>
   paneKittyKeyboardModesRef: React.RefObject<Map<number, TerminalKittyKeyboardModeTracker>>
@@ -301,13 +290,9 @@ type UseTerminalPaneLifecycleDeps = {
   setPaneTitles: React.Dispatch<React.SetStateAction<Record<number, string>>>
   paneTitlesRef: React.RefObject<Record<number, string>>
   setRenamingPaneId: React.Dispatch<React.SetStateAction<number | null>>
-  // Why: TerminalPane exposes reactive pane metadata so effects that read the
-  // imperative pane list re-run when panes are split or closed. The
-  // imperative managerRef.getPanes().length is not reactive, so without this
-  // dispatcher structural changes wouldn't trigger dependent effects.
+  // Why: managerRef.getPanes() isn't reactive, so this dispatcher ticks effects when panes split/close.
   setPaneCount: React.Dispatch<React.SetStateAction<number>>
-  // Why: same pane count does not imply same geometry; drag-reorder can move
-  // panes without resizing them, so overlay rects need a layout-change tick.
+  // Why: same pane count != same geometry (drag-reorder moves without resizing), so overlay rects need a tick.
   setPaneLayoutRevision: React.Dispatch<React.SetStateAction<number>>
   resolveExternalPaneDropTarget?: PaneExternalDropResolver
   onExternalPaneDrop?: PaneExternalDropHandler
@@ -450,14 +435,7 @@ export function splitPaneWithOneShotStartup<TPane>(
   startup: SplitStartupPayload,
   splitPane: () => TPane
 ): TPane {
-  // Why: the startup payload is only for the pane created by this split.
-  // Pane creation fans out through onPaneCreated using a spread copy of `deps`,
-  // so connectPanePty cannot clear the caller's original object for us.
-  // Reset the shared field in finally so later user-driven splits never replay
-  // setup/issue commands, even if splitPane throws during creation.
-  // Relies on manager.splitPane → onPaneCreated → connectPanePty reading
-  // `deps.startup` synchronously before returning; if that chain ever becomes
-  // async, this helper must switch to awaiting the split before clearing.
+  // Why: startup is only for this split's pane; reset in finally so later splits never replay setup/issue commands. Assumes splitPane reads it synchronously.
   deps.startup = startup
   try {
     return splitPane()
@@ -472,17 +450,12 @@ export function shouldDetachPaneTransportOnUnmount(args: {
   ptyId: string | null
   worktreeTabs: readonly TerminalTab[] | undefined
 }): boolean {
-  // Why: mounted transport teardown is renderer-only; closeTab or the pane-close
-  // action already owns provider shutdown. Destroy only pending, ID-less spawns.
+  // Why: teardown is renderer-only (closeTab/pane-close owns provider shutdown); destroy only pending, ID-less spawns.
   return Boolean(args.ptyId)
 }
 
 /**
- * Self-gating dead-session reconcile pass scheduled from the isVisible effect.
- * Why self-gate: the effect fires on BOTH isVisible true and false, but we only
- * reconcile on resume (hidden to visible), never on hide or initial mount.
- * Returns true when the pass was scheduled so the resume-unit test can assert
- * the gate.
+ * Self-gating dead-session reconcile: true only on resume (hidden→visible), since the isVisible effect fires on both true and false.
  */
 export function isTerminalPaneVisibilityResume(args: {
   previousIsVisible: boolean | null
@@ -574,9 +547,7 @@ export function useTerminalPaneLifecycle({
   const terminalScrollbackRows = normalizeDesktopTerminalScrollbackRows(
     settings?.terminalScrollbackRows
   )
-  // Why here: the output scheduler's backlog cap scales with the same
-  // scrollback setting; applying it where the setting is read keeps the two
-  // in lockstep without a separate settings subscription.
+  // Why here: backlog cap scales with the scrollback setting; set it where the setting is read to stay in lockstep.
   configureTerminalOutputBacklogCap(settings?.terminalScrollbackRows)
   const systemPrefersDarkRef = useRef(systemPrefersDark)
   systemPrefersDarkRef.current = systemPrefersDark
@@ -585,8 +556,7 @@ export function useTerminalPaneLifecycle({
   const terminalHandleLinkDisposablesRef = useRef(new Map<number, IDisposable>())
   const fileLinkClickFallbackDisposablesRef = useRef(new Map<number, IDisposable>())
   const httpLinkClickFallbackDisposablesRef = useRef(new Map<number, IDisposable>())
-  // Why: read settingsRef at fire time so toggling "copy on select" takes
-  // effect without recreating panes.
+  // Why: read settingsRef at fire time so toggling "copy on select" applies without recreating panes.
   const selectionDisposablesRef = useRef(new Map<number, IDisposable>())
   const selectionCaptureTimersRef = useRef(new Map<number, number>())
   const mode2031DisposablesRef = useRef(new Map<number, IDisposable[]>())
@@ -676,9 +646,7 @@ export function useTerminalPaneLifecycle({
     const terminalHomePath = resolveTerminalHomePathFromEnv(startup?.env)
     const getPaneLinkCwd = (paneId: number): string =>
       resolvePaneLinkCwd(paneCwdRef.current, paneId, startupCwd)
-    // Why: existence probes can cross SSH/runtime boundaries. This cache is
-    // lifecycle-scoped, so external mutations and the initial 'active' runtime
-    // fallback can temporarily leave stale entries.
+    // Why: lifecycle-scoped cache for cross-SSH/runtime existence probes; may hold temporarily stale entries.
     const pathExistsCache = new Map<string, boolean>()
     const linkDeps: LinkHandlerDeps = {
       worktreeId,
@@ -718,10 +686,7 @@ export function useTerminalPaneLifecycle({
       setTabCanExpandPane(tabId, paneCount > 1)
     }
 
-    // Why: publish the current pane count to React state so effects depending
-    // on structural changes re-run on split/close. The pane list lives in an
-    // imperative PaneManager ref, so
-    // without this sync those effects would miss structural-only changes.
+    // Why: PaneManager's pane list is an imperative ref, so publish count to React state so effects re-run on split/close.
     const syncPaneCount = (): void => {
       setPaneCount(managerRef.current?.getPanes().length ?? 0)
     }
@@ -778,9 +743,7 @@ export function useTerminalPaneLifecycle({
       setCacheTimerStartedAt,
       syncPanePtyLayoutBinding,
       clearExitedPanePtyLayoutBinding,
-      // Why: a DECSET 2031 subscribe answered from main's fact channel must
-      // land in the same registries the xterm CSI handler writes — otherwise
-      // theme flips never push CSI 997 and the TUI keeps a stale theme.
+      // Why: record the main-answered 2031 subscribe in the CSI handler's registries, else theme flips never push CSI 997.
       recordPaneMode2031Subscription: (paneId: number, repliedMode: 'dark' | 'light') => {
         paneMode2031Ref.current.set(paneId, true)
         paneLastThemeModeRef.current.set(paneId, repliedMode)
@@ -803,20 +766,14 @@ export function useTerminalPaneLifecycle({
     let releaseWebviewDragPassthrough: (() => void) | null = null
 
     const manager = new PaneManager(container, {
-      // Why: `spawnHints` carries the resolved cwd from Cmd+D / context-menu
-      // Split actions so the new PTY inherits the source pane's live cwd.
-      // Split-pane CWD inheritance — see docs/ssh-split-pane-inherit-cwd.md.
+      // `spawnHints.cwd` (from Split actions) lets the new PTY inherit the source pane's cwd — see docs/ssh-split-pane-inherit-cwd.md.
       onPaneCreated: (pane, spawnHints) => {
-        // Install mode 2031 parser handlers before PTY attach so the child's
-        // initial CSI ?2031h (sent at startup) is captured.
+        // Install mode 2031 handlers before PTY attach so the child's initial CSI ?2031h is captured.
         const mode2031Disposables = installMode2031Handlers({
           paneId: pane.id,
           parser: pane.terminal.parser,
           onSubscribe: () => {
-            // Why: for hidden-delivery-gate-managed PTYs main's
-            // '2031-subscribe' fact is the sole responder — bytes reaching
-            // xterm live (foreground, sidecar interest) must not produce a
-            // second reply. The CSI handler still records the subscription.
+            // Why: for hidden-delivery-gate PTYs, main's '2031-subscribe' fact is the sole responder — don't send a second reply.
             const binding = panePtyBindings.get(pane.id) as
               | (IDisposable & { isHiddenDeliveryGateManagedPty?: () => boolean })
               | undefined
@@ -832,12 +789,7 @@ export function useTerminalPaneLifecycle({
         mode2031DisposablesRef.current.set(pane.id, mode2031Disposables)
 
         // OSC 52 — TUI-initiated clipboard writes (tmux/nvim/fzf/ssh).
-        // Why read settingsRef at fire time (not capture): the user may
-        // toggle the gate mid-session and we want that to take effect
-        // immediately without recreating panes. Return true ("handled") in
-        // both the enabled and disabled paths so xterm doesn't fall
-        // through to any other OSC 52 handler and so our intentional drop
-        // in the disabled path is explicit.
+        // Why: read settingsRef at fire time so mid-session gate toggles apply; return true in both paths so xterm doesn't fall through.
         const osc52Disposable = pane.terminal.parser.registerOscHandler(
           52,
           guardParserHandler('osc-52-clipboard', (data) =>
@@ -850,22 +802,8 @@ export function useTerminalPaneLifecycle({
         )
         osc52DisposablesRef.current.set(pane.id, osc52Disposable)
 
-        // OSC 7 — shell-reported current working directory. Drives split-pane
-        // cwd inheritance (Cmd+D / Cmd+Shift+D / context-menu Split). Handler
-        // install MUST remain before connectPanePty: the cold-restore path
-        // replays recorded PTY output into the terminal synchronously from the
-        // first PTY read, so a handler registered later would miss the first
-        // OSC 7 in replayed scrollback.
-        //
-        // Why the replay flag is reliable here: replayIntoTerminal increments
-        // a per-pane counter BEFORE xterm.write and decrements it in xterm's
-        // write-completion callback (replay-guard.ts). xterm parses OSC
-        // synchronously as it consumes the buffer, so every OSC 7 emitted
-        // during replay is seen with the counter non-zero.
-        //
-        // Return true so xterm marks the sequence handled. If a future
-        // consumer registers on code 7, registration order decides who sees
-        // each sequence.
+        // OSC 7 — shell-reported cwd; drives split-pane cwd inheritance. Install MUST stay before connectPanePty:
+        // cold-restore replays PTY output synchronously from the first read, so a later handler misses the first OSC 7.
         if (!paneCwdRef.current.has(pane.id)) {
           paneCwdRef.current.set(pane.id, {
             cwd: resolvePaneSeedCwd(spawnHints?.cwd, ptyDeps.cwd),
@@ -885,23 +823,12 @@ export function useTerminalPaneLifecycle({
         )
         osc7DisposablesRef.current.set(pane.id, osc7Disposable)
 
-        // Why: let host-handled keys bypass xterm's kitty CSI-u encoder.
-        // With vtExtensions.kittyKeyboard on, a CLI that activates progressive
-        // enhancement (Codex does, Claude Code does not) makes xterm encode
-        // Cmd+C as a CSI-u sequence with cancel=true, which preventDefaults
-        // the keydown and suppresses Chromium's native copy event — so the
-        // selection never reaches the clipboard. The same hook also bypasses
-        // matching keyups so kitty release sequences do not leak after a
-        // bypassed press. Returning false here short-circuits xterm before the
-        // encoder runs, letting the browser and Electron paths fire normally.
-        // See xterm-bypass-policy.ts for the rule derivation.
+        // Why: let host-handled keys bypass xterm's kitty CSI-u encoder — with kittyKeyboard on it preventDefaults Cmd+C and blocks Chromium's native copy. See xterm-bypass-policy.ts.
         let pendingTerminalInterruptKeyup = false
         const pendingTerminalImeCandidateKeyReleases =
           createTerminalImePendingCandidateKeyReleases()
         const isMac = navigator.userAgent.includes('Mac')
-        // Why: Android/ChromeOS UAs also contain "Linux"; keep the Sogou/fcitx
-        // candidate-key policy scoped to desktop Linux so paired web clients on
-        // those platforms keep their previous IME behavior.
+        // Why: Android/ChromeOS UAs also contain "Linux"; scope the fcitx candidate-key policy to desktop Linux.
         const isLinux =
           !isMac &&
           navigator.userAgent.includes('Linux') &&
@@ -917,9 +844,7 @@ export function useTerminalPaneLifecycle({
             linuxImeCandidateState?.dispose()
           }
         })
-        // Why: only known macOS native text paths need xterm keydown bypass.
-        // Source gates cover physical CJK/Vietnamese IME rewrites; synthetic
-        // Unicode key events are detected by missing physical key identity.
+        // Why: only known macOS native text paths (physical CJK/Vietnamese IME) need the keydown bypass; synthetic Unicode lacks physical key identity.
         const imeNativeTextForwarder = isMac
           ? installTerminalImeNativeTextForwarder({
               terminalElement: pane.terminal.element,
@@ -961,12 +886,10 @@ export function useTerminalPaneLifecycle({
             isLinux
           }
           if (shouldSuppressTerminalImeKeyboardEvent(e, imeKeyboardOptions)) {
-            // Why: clear before arm — a fresh keydown drops any stale pending
-            // release for its key before the new press arms its own.
+            // Why: clear before arm so a fresh keydown drops any stale pending release before arming its own.
             clearTerminalImePendingCandidateKeyRelease(pendingTerminalImeCandidateKeyReleases, e)
             if (shouldPreventDefaultTerminalImeCandidateKey(e, imeKeyboardOptions)) {
-              // Why: without preventDefault the suppressed candidate keydown
-              // still fires a keypress and mutates the helper textarea.
+              // Why: without preventDefault the suppressed candidate keydown still fires a keypress and mutates the helper textarea.
               e.preventDefault()
               armTerminalImePendingCandidateKeyRelease(
                 pendingTerminalImeCandidateKeyReleases,
@@ -990,12 +913,10 @@ export function useTerminalPaneLifecycle({
             })
           ) {
             if (e.type === 'keydown') {
-              // Why: xterm's kitty encoder can turn plain Ctrl+C into CSI-u;
-              // ETX must stay transport-agnostic through the existing onData path.
+              // Why: xterm's kitty encoder can turn plain Ctrl+C into CSI-u; keep ETX transport-agnostic via the onData path.
               pendingTerminalInterruptKeyup = true
               pane.terminal.input(TERMINAL_INTERRUPT_INPUT)
-              // Why: CLIs such as Codex can die on SIGINT before restoring
-              // xterm's renderer-side Kitty flags, leaving the shell corrupted.
+              // Why: CLIs like Codex can die on SIGINT before restoring xterm's Kitty flags, leaving the shell corrupted.
               resetTerminalKeyboardProtocolAfterInterrupt(pane.terminal)
             } else {
               pendingTerminalInterruptKeyup = false
@@ -1004,8 +925,7 @@ export function useTerminalPaneLifecycle({
             return false
           }
           if (shouldSuppressTerminalModifierKeyboardEvent(e)) {
-            // Why: stale Kitty keyboard reporting can encode standalone
-            // modifier presses before Ctrl+C reaches the interrupt handler.
+            // Why: stale Kitty keyboard reporting can encode standalone modifier presses before Ctrl+C reaches the interrupt handler.
             observeLinuxCandidateEvent()
             return false
           }
@@ -1016,8 +936,7 @@ export function useTerminalPaneLifecycle({
           })
           if (jisYenInput) {
             if (jisYenInput.type === 'input') {
-              // Why: this is a translated character, not a terminal shortcut.
-              // Keep it on xterm's onData path so PTY input guards still run.
+              // Why: translated character, not a shortcut — keep it on xterm's onData path so PTY input guards still run.
               pane.terminal.input(jisYenInput.data)
             }
             observeLinuxCandidateEvent()
@@ -1043,8 +962,7 @@ export function useTerminalPaneLifecycle({
           }
 
           if (imeNativeTextForwarder.claimKeyEvent(e)) {
-            // Why: bypass xterm's kitty encoder for native text keydowns so the
-            // committed glyph survives via the input event.
+            // Why: bypass xterm's kitty encoder for native text keydowns so the committed glyph survives via the input event.
             observeLinuxCandidateEvent()
             return false
           }
@@ -1084,8 +1002,7 @@ export function useTerminalPaneLifecycle({
         })
         httpLinkClickFallbackDisposables.set(pane.id, httpLinkClickFallbackDisposable)
         seedStartupSessionRestoredBanner(ptyDeps.startup, pane.id, onShowSessionRestoredBanner)
-        // Why: skip empty selections so clicking to deselect doesn't clobber
-        // whatever the user last copied elsewhere.
+        // Why: skip empty selections so click-to-deselect doesn't clobber whatever the user last copied.
         const selectionDisposable = pane.terminal.onSelectionChange(() => {
           const shouldWritePrimarySelection = isPrimarySelectionEnabled()
           const shouldWriteClipboard = settingsRef.current?.terminalClipboardOnSelect === true
@@ -1108,8 +1025,7 @@ export function useTerminalPaneLifecycle({
             if (existingTimer !== undefined) {
               window.clearTimeout(existingTimer)
             }
-            // Why: xterm fires selection changes while dragging; defer the
-            // primary-selection clipboard write to avoid clipboard churn.
+            // Why: xterm fires selection changes while dragging; defer the primary-selection write to avoid clipboard churn.
             const timer = window.setTimeout(() => {
               selectionCaptureTimersRef.current.delete(pane.id)
               if (!isPrimarySelectionEnabled() || !pane.terminal.hasSelection()) {
@@ -1138,14 +1054,12 @@ export function useTerminalPaneLifecycle({
           })
         })
         selectionDisposablesRef.current.set(pane.id, selectionDisposable)
-        // Hide mouse cursor while typing — classic terminal UX, scoped to the
-        // pane container so other UI elements keep their cursor.
+        // Hide mouse cursor while typing (scoped to the pane container so other UI keeps its cursor).
         if (settingsRef.current?.terminalMouseHideWhileTyping) {
           const mouseHideDisposable = installMouseHideWhileTyping(pane.terminal, pane.container)
           mouseHideDisposablesRef.current.set(pane.id, mouseHideDisposable)
         }
-        // Why: async tooltip formatting can resolve after hover changes, so a
-        // stale result must not overwrite the tooltip for a newer hover/leave.
+        // Why: async tooltip formatting can resolve after the hover changes; a stale result must not overwrite a newer hover/leave.
         let oscTooltipHoverToken = 0
         pane.terminal.options.linkHandler = {
           allowNonHttpProtocols: true,
@@ -1156,21 +1070,13 @@ export function useTerminalPaneLifecycle({
               runtimeEnvironmentId: linkDeps.getRuntimeEnvironmentIdForPane?.(pane.id) ?? null,
               requestOpenLinksInAppPreference
             })
-            // Why: Cmd/Ctrl+clicking a link activates Orca handling (open file,
-            // new browser tab, system browser) which can steal focus from the
-            // terminal before the click's mouseup reaches ownerDocument. Without
-            // that mouseup, xterm's SelectionService leaves its drag-select
-            // mousemove listener attached, so returning to the terminal and
-            // moving the mouse extends a selection until the next click/Esc.
-            // clearSelection() explicitly detaches those listeners (see
-            // SelectionService._removeMouseDownListeners).
+            // Why: link activation can steal focus before the click's mouseup reaches xterm, stranding its drag-select
+            // listener (runaway selection until next click/Esc); clearSelection detaches it (SelectionService._removeMouseDownListeners).
             if (handled) {
               pane.terminal.clearSelection()
             }
           },
-          // Show bottom-left tooltip on hover for OSC 8 hyperlinks (e.g.
-          // GitHub owner/repo#issue references emitted by CLI tools) — same
-          // behaviour as the WebLinksAddon provides for plain-text URLs.
+          // Show hover tooltip for OSC 8 hyperlinks — same behaviour WebLinksAddon gives plain-text URLs.
           hover: (_event, text) => {
             oscTooltipHoverToken += 1
             const hoverToken = oscTooltipHoverToken
@@ -1190,9 +1096,7 @@ export function useTerminalPaneLifecycle({
         applyAppearance(manager)
         const panePtyBinding = connectPanePty(pane, manager, {
           ...ptyDeps,
-          // Why: spread order matters — spawnHints.cwd (inherited from the
-          // source pane) must override the tab-level ptyDeps.cwd (worktree
-          // root) so Cmd+D splits boot in the live cwd.
+          // Why: spread order matters — spawnHints.cwd (source pane) must override ptyDeps.cwd (worktree root) so splits boot in the live cwd.
           ...(spawnHints?.cwd ? { cwd: spawnHints.cwd } : {}),
           restoredPtyIdByLeafId: spawnHints?.ptyId
             ? {
@@ -1202,17 +1106,7 @@ export function useTerminalPaneLifecycle({
             : ptyDeps.restoredPtyIdByLeafId,
           restoredLeafId: pane.leafId
         })
-        // Why: connectPanePty receives a spread copy of ptyDeps, so the
-        // `deps.startup = undefined` it performs internally only clears its
-        // local copy. If we don't also clear the outer ptyDeps.startup here,
-        // a later user-initiated splitPane (e.g. Cmd+D, context-menu "Split
-        // Right") fires onPaneCreated again with the original startup still
-        // attached — which re-runs the initial composer prompt in the newly
-        // created pane. Clearing here ensures the initial-startup payload is
-        // consumed exactly once, by the first pane. Setup/issue splits
-        // inject their own payload via splitPaneWithOneShotStartup, which
-        // sets deps.startup immediately before splitPane() and is therefore
-        // unaffected by this clear.
+        // Why: connectPanePty clears only its spread copy; clear outer ptyDeps.startup so the initial prompt runs once and later user splits don't replay it.
         ptyDeps.startup = null
         const nextInitialCwdState = clearQueuedInitialCwdAfterFirstPane(
           queuedInitialCwdRef.current,
@@ -1291,8 +1185,7 @@ export function useTerminalPaneLifecycle({
           osc7Disposable.dispose()
           osc7DisposablesRef.current.delete(paneId)
         }
-        // Why: drop the tracked cwd so the map doesn't accumulate dead
-        // entries across splits/closes over long sessions.
+        // Why: drop the tracked cwd so the map doesn't accumulate dead entries over long sessions.
         paneCwdRef.current.delete(paneId)
         const mouseHideDisposable = mouseHideDisposablesRef.current.get(paneId)
         if (mouseHideDisposable) {
@@ -1314,15 +1207,13 @@ export function useTerminalPaneLifecycle({
         }
         const leafId = closedPane?.leafId
         if (leafId && !isDetachedToTab) {
-          // Why: pane close permanently revokes only this pane's authority;
-          // an exact tombstone blocks queued hooks without suppressing siblings.
+          // Why: revoke only this pane's authority; an exact tombstone blocks queued hooks without suppressing siblings.
           const paneKey = makePaneKey(tabId, leafId)
           useAppStore.getState().retireAgentPaneAuthority(paneKey)
         }
         if (transport) {
           if (isDetachedToTab) {
-            // Why: pane-to-tab detach hands the PTY to a newly-created tab;
-            // detach renderer listeners without sending a process teardown.
+            // Why: detach hands the PTY to a new tab, so drop renderer listeners without a process teardown.
             transport.detach?.()
           } else {
             const ptyId = suppressIntentionalPaneCloseExit(
@@ -1330,9 +1221,7 @@ export function useTerminalPaneLifecycle({
               useAppStore.getState().suppressPtyExit
             )
             if (ptyId) {
-              // Why: user/CLI pane closes intentionally tear down this PTY after
-              // PaneManager has already promoted the sibling. Suppress that exit
-              // so the last-surviving pane is not mistaken for an exited tab.
+              // Why: PaneManager already promoted the sibling; suppress this exit so the survivor isn't mistaken for an exited tab.
               syncPanePtyLayoutBinding(paneId, null)
               clearTabPtyId(tabId, ptyId)
             }
@@ -1353,22 +1242,16 @@ export function useTerminalPaneLifecycle({
           delete next[paneId]
           return next
         })
-        // Eagerly update the ref so persistLayoutSnapshot (called from
-        // onLayoutChanged which fires right after onPaneClosed) reads the
-        // correct titles without waiting for React's async state flush.
+        // Eagerly update the ref so persistLayoutSnapshot (fires right after onPaneClosed) reads correct titles before React's async flush.
         if (paneId in paneTitlesRef.current) {
           const next = { ...paneTitlesRef.current }
           delete next[paneId]
           paneTitlesRef.current = next
         }
-        // Dismiss the rename dialog if it was open for the closed pane,
-        // otherwise it would submit against a non-existent pane.
+        // Dismiss the rename dialog if open for the closed pane, else it submits against a non-existent pane.
         setRenamingPaneId((prev) => (prev === paneId ? null : prev))
         syncPaneCount()
-        // Why: PaneManager.closePane() reassigns activePaneId directly without
-        // calling setActivePane(), so onActivePaneChange does not fire. Sync the
-        // tab title to the survivor's stored title here so the tab label doesn't
-        // stay stuck on the closed pane's last title.
+        // Why: closePane() reassigns activePaneId without firing onActivePaneChange, so sync the tab title to the survivor here.
         const newActivePane = managerRef.current?.getActivePane()
         if (newActivePane) {
           reportActiveRendererPtyForPane(paneTransportsRef.current, newActivePane.id)
@@ -1390,31 +1273,24 @@ export function useTerminalPaneLifecycle({
             ? (managerRef.current?.getNumericIdForLeaf(fallbackLeafId) ?? null)
             : null
           if (fallbackPaneId != null && fallbackPaneId !== pane.id) {
-            // Why: a pane whose PTY exited can remain visible; do not let a
-            // click park focus on a leaf that will swallow keyboard input.
+            // Why: a pane whose PTY exited can stay visible; don't let a click park focus on a leaf that swallows keyboard input.
             managerRef.current?.setActivePane(fallbackPaneId, { focus: true })
             return
           }
         }
         scheduleRuntimeGraphSync()
-        // Why: active pane lives in PaneManager; React consumers such as the
-        // header chat toggle need a render tick when focus moves between splits.
+        // Why: active pane lives in PaneManager; React consumers (e.g. header chat toggle) need a render tick when focus moves between splits.
         syncPaneLayoutRevision()
         if (shouldPersistLayout) {
           persistLayoutSnapshot()
         }
         reportActiveRendererPtyForPane(paneTransportsRef.current, pane.id)
-        // Why: the tab icon resolves from the active leaf's process identity;
-        // focusing a shell-marked pane whose agent is still running must
-        // re-sample it, since no further OSC boundary will.
+        // Why: the tab icon resolves from the active leaf's process; re-sample a shell-marked pane whose agent still runs, since no OSC boundary will.
         const focusedBinding = panePtyBindings.get(pane.id) as
           | (IDisposable & { sampleForegroundAgentOnFocus?: () => void })
           | undefined
         focusedBinding?.sampleForegroundAgentOnFocus?.()
-        // Why: when the user switches focus between split panes, update the
-        // tab title to the newly active pane's last-known title so the tab
-        // label reflects the focused agent — not a stale title from the
-        // previously focused pane.
+        // Why: on focus switch between splits, set the tab title to the newly active pane's last-known title so it doesn't show a stale one.
         const paneTitles = useAppStore.getState().runtimePaneTitlesByTabId[tabId] ?? {}
         const paneTitle = paneTitles[pane.id]
         if (paneTitle) {
@@ -1452,8 +1328,7 @@ export function useTerminalPaneLifecycle({
           (candidate) => candidate.id === tabId
         )
         const platformInfo = window.api.platform?.get?.()
-        // Why: launch identity belongs only to the pane consuming this one-shot
-        // startup. A tab-wide hint would leak Grok's KKP exception to shell splits.
+        // Why: launch identity is per-pane; a tab-wide hint would leak Grok's KKP exception to shell splits.
         const knownTuiAgent = resolvePaneKeyboardProtocolAgent(
           ptyDeps.startup,
           currentTab?.launchAgent
@@ -1469,10 +1344,7 @@ export function useTerminalPaneLifecycle({
         }
         const windowsPtyCompatibilityOptions =
           buildWindowsPtyCompatibilityOptions(ptyBackendContext)
-        // Why: local Windows ConPTY CLIs read the Kitty keyboard advertisement but
-        // do not decode CSI-u, so withhold it there to restore Enter/Up/Down nav
-        // (issue #2434); SSH and macOS/Linux panes keep enhanced reporting.
-        // Exception: Grok (tuiAgent) keeps the advertisement — see protocol module.
+        // Why: local Windows ConPTY reads the Kitty advertisement but can't decode CSI-u, so withhold it to restore Enter/Up/Down nav (issue #2434); Grok keeps it.
         const keyboardProtocolOptions = buildTerminalKeyboardProtocolOptions(ptyBackendContext)
         return {
           ...windowsPtyCompatibilityOptions,
@@ -1513,21 +1385,15 @@ export function useTerminalPaneLifecycle({
         })
       },
       formatLinkTooltip: (url, openLinkHint) => formatTerminalUrlTooltip(url, openLinkHint),
-      // Why: TerminalPane instances stay mounted for hidden visited worktrees
-      // so PTYs survive navigation. Creating WebGL for those offscreen panes
-      // still consumes Chromium's context budget and can blank visible panes.
+      // Why: hidden panes stay mounted so PTYs survive navigation, but their WebGL contexts drain Chromium's budget and can blank visible panes.
       initialRenderingSuspended: !isVisibleRef.current,
-      // Why: remote-runtime panes honor the user GPU setting too — snapshots
-      // that arrive after WebGL attaches are handled by the post-replay
-      // rebuildPaneWebgl in pty-connection's replay callback.
+      // Why: remote-runtime panes honor the GPU setting too; late snapshots are handled by post-replay rebuildPaneWebgl in pty-connection.
       terminalGpuAcceleration: settingsRef.current?.terminalGpuAcceleration ?? 'auto',
       debugLabel: `tab:${tabId}/wt:${worktreeId}`
     })
 
     managerRef.current = manager
-    // Why: E2E tests need to read terminal buffer content, but xterm.js renders
-    // to canvas and the accessibility addon is not loaded. Exposing the manager
-    // lets tests call serializeAddon.serialize() to read the buffer reliably.
+    // Why: xterm renders to canvas with no a11y addon; expose the manager so E2E can read the buffer via serializeAddon.serialize().
     if (e2eConfig.exposeStore) {
       window.__paneManagers = window.__paneManagers ?? new Map()
       window.__paneManagers.set(tabId, manager)
@@ -1547,25 +1413,20 @@ export function useTerminalPaneLifecycle({
       delete layoutWithoutRestoredBuffers.buffersByLeafId
       initialLayoutRef.current = layoutWithoutRestoredBuffers
       if (initialLayoutHadBuffers) {
-        // Why: raw replay bytes belong only to this mount. Drop legacy hydrated
-        // copies from Zustand so normal session writes stay ref-only.
+        // Why: raw replay bytes belong to this mount only; drop legacy hydrated copies from Zustand so session writes stay ref-only.
         useAppStore.getState().setTabLayout(tabId, layoutWithoutRestoredBuffers)
       }
     }
 
-    // Seed pane titles from the persisted snapshot using the same
-    // old-leafId → new-paneId mapping used for buffer restore.
+    // Seed pane titles via the same old-leafId → new-paneId mapping used for buffer restore.
     const restoredTitles = mapRestoredPaneTitlesByPaneId(
       initialLayoutRef.current.titlesByLeafId,
       restoredPaneByLeafId
     )
     if (Object.keys(restoredTitles).length > 0) {
-      // Merge (not replace) so we don't discard any concurrent state
-      // updates from onPaneClosed that React may have batched.
+      // Why: merge (not replace) so we don't discard concurrent onPaneClosed updates React may have batched.
       setPaneTitles((prev) => ({ ...prev, ...restoredTitles }))
-      // Why: the lifecycle immediately persists a fresh layout after restore,
-      // before React state has flushed. Keep the ref in sync now so that
-      // persist preserves restored titles instead of rewriting them away.
+      // Why: persist runs right after restore, before React state flushes; sync the ref now so persist keeps restored titles.
       paneTitlesRef.current = { ...paneTitlesRef.current, ...restoredTitles }
     }
 
@@ -1592,22 +1453,12 @@ export function useTerminalPaneLifecycle({
     } else {
       setExpandedPane(null)
     }
-    // Why: setup split creates a right-side pane for the setup script so the
-    // main (left) terminal stays immediately usable. We inject the setup command
-    // into ptyDeps.startup right before splitting and clear it immediately after
-    // — connectPanePty receives a spread copy (`{...ptyDeps}`), so mutations
-    // inside connectPanePty don't propagate back to ptyDeps. Without clearing
-    // here, any later user-initiated split (e.g. Cmd+D) would re-run the setup
-    // command in the newly created pane.
+    // Why: the setup command is injected into ptyDeps.startup then cleared post-split, else a later user split (Cmd+D) would re-run it.
     let issueAutomationAnchorPaneId: number | null = null
-    // Why: capture the main shell pane *before* any splits mutate the pane list.
-    // Both the setup and issue-command paths need to restore focus back to this
-    // pane after creating their splits, so we save the reference once rather
-    // than relying on getPanes()[0] which returns insertion order, not visual order.
+    // Why: capture the main shell pane before splits mutate the list; getPanes()[0] is insertion order, not visual order.
     const initialPane = manager.getActivePane() ?? manager.getPanes()[0]
 
-    // Why: setup/issue automation panes are internal workspace bootstrap flows,
-    // not the user-initiated terminal split interaction recorded below.
+    // Why: setup/issue panes are internal bootstrap flows, not the user-initiated split recorded below.
     if (setupSplit) {
       if (initialPane) {
         const setupPane = splitPaneWithOneShotStartup(
@@ -1616,22 +1467,16 @@ export function useTerminalPaneLifecycle({
           () => manager.splitPane(initialPane.id, setupSplit.direction)
         )
         issueAutomationAnchorPaneId = setupPane?.id ?? null
-        // Restore focus to the main pane so the user's terminal receives
-        // keyboard input — the setup pane runs unattended.
+        // Restore focus to the main pane for keyboard input; the setup pane runs unattended.
         manager.setActivePane(initialPane.id, { focus: isActive })
       }
     }
 
-    // Why: when the user links a GitHub issue during worktree creation and has
-    // enabled that repo's issue automation, spawn a separate split pane to run
-    // the agent command. This runs independently from setup: the issue command
-    // is a per-user prompt/template rather than repo bootstrap, so Orca should
-    // not guess at ordering requirements that vary by user workflow.
+    // Why: linked-issue automation spawns its own split independent of setup — it's a per-user prompt, not repo bootstrap, so don't impose ordering.
     if (issueCommandSplit) {
       let targetPane = manager.getActivePane() ?? manager.getPanes()[0] ?? null
       if (issueAutomationAnchorPaneId !== null) {
-        // Why: keep the same anchor-first fallback order without the ternary +
-        // nullish chain that `tsgo` currently misreads as always-nullish.
+        // Why: anchor-first fallback without the ternary + nullish chain that `tsgo` misreads as always-nullish.
         targetPane =
           manager.getPanes().find((pane) => pane.id === issueAutomationAnchorPaneId) ?? targetPane
       }
@@ -1641,10 +1486,7 @@ export function useTerminalPaneLifecycle({
           { command: issueCommandSplit.command, env: issueCommandSplit.env },
           () => manager.splitPane(targetPane.id, 'vertical')
         )
-        // Why: if setup already claimed the right half, nest issue automation
-        // inside that automation area instead of splitting the main shell again.
-        // This preserves the primary terminal as the dominant pane while setup
-        // and issue panes share the secondary column.
+        // Why: if setup already claimed the right half, nest issue automation there so the main terminal stays dominant while setup/issue share the secondary column.
         const focusPaneId =
           issueAutomationAnchorPaneId !== null ? (initialPane?.id ?? targetPane.id) : targetPane.id
         manager.setActivePane(focusPaneId, { focus: isActive })
@@ -1659,10 +1501,7 @@ export function useTerminalPaneLifecycle({
     persistLayoutSnapshot()
     scheduleRuntimeGraphSync()
 
-    // Why: CLI-driven splits go through splitPaneWithOneShotStartup so the
-    // startup command is delivered via the PTY connection path (which waits
-    // for shell readiness) instead of terminal.paste() which can lose input
-    // if the shell hasn't started reading stdin yet.
+    // Why: deliver the startup command via the PTY connection path (waits for shell readiness), not terminal.paste() which can lose input before the shell reads stdin.
     function onCliSplitPane(event: Event): void {
       const detail = (event as CustomEvent<SplitTerminalPaneDetail>).detail
       if (!detail?.tabId || detail.tabId !== tabId) {
@@ -1707,9 +1546,7 @@ export function useTerminalPaneLifecycle({
     }
     window.addEventListener(SPLIT_TERMINAL_PANE_EVENT, onCliSplitPane)
 
-    // Why: CLI-driven pane close dispatches a CustomEvent so PaneManager handles
-    // sibling promotion in split layouts. Falls back to closing the whole tab
-    // when the target pane is the only one remaining.
+    // Why: CLI-driven pane close goes via CustomEvent so PaneManager promotes a sibling; the last pane falls back to closing the tab.
     function onCliClosePane(event: Event): void {
       const detail = (event as CustomEvent<CloseTerminalPaneDetail>).detail
       if (!detail?.tabId || detail.tabId !== tabId) {
@@ -1720,9 +1557,7 @@ export function useTerminalPaneLifecycle({
         return
       }
       if (mgr.getPanes().length <= 1) {
-        // Why: route through closeTerminalTab (not the raw store closeTab) so a
-        // pinned tab hits the confirmation guard. Closing the last pane here was
-        // the one path that silently dropped pinned tabs.
+        // Why: route through closeTerminalTab (not raw closeTab) so a pinned tab hits the confirmation guard — this was the one path that silently dropped pinned tabs.
         closeTerminalTab(tabId)
       } else {
         mgr.closePane(detail.paneRuntimeId)
@@ -1782,9 +1617,7 @@ export function useTerminalPaneLifecycle({
         disposable.dispose()
       }
       imeNativeTextForwarderDisposables.clear()
-      // Why: hidden-view parking starts pane-less byte watchers right after
-      // this unmount; record pane identities before transports detach so the
-      // watchers write the same runtime-title slots the live panes used.
+      // Why: hidden-view parking starts pane-less byte watchers right after unmount; record pane identities first so watchers write the same runtime-title slots.
       captureParkedTerminalPaneCandidates(
         tabId,
         worktreeId,
@@ -1805,17 +1638,10 @@ export function useTerminalPaneLifecycle({
             worktreeTabs: currentWorktreeTabs
           })
         ) {
-          // Why: moving a terminal tab between groups currently rehomes the
-          // React subtree, which unmounts this TerminalPane even though the tab
-          // itself is still alive. Web session mirroring can also replace a
-          // temporary local tab with a host surface that owns the same PTY.
-          // Detaching preserves the running PTY so the remounted pane can
-          // reattach without restarting the user's shell.
-          // Transports that have not attached yet still have no PTY ID; those
-          // must be destroyed so any in-flight spawn resolves into a killed PTY
-          // instead of reviving a stale binding after unmount.
+          // Why: tab-move rehome and web-mirror remount unmount a still-live tab; detach preserves the running PTY so the remount reattaches without restarting the shell.
           transport.detach?.()
         } else {
+          // Why: un-attached transports have no PTY ID; destroy so an in-flight spawn resolves to a killed PTY, not a revived stale binding after unmount.
           transport.destroy?.()
         }
       }
@@ -1829,8 +1655,7 @@ export function useTerminalPaneLifecycle({
       releaseWebviewDragPassthrough = null
       managerRef.current = null
       if (e2eConfig.exposeStore) {
-        // Why: a replacement mount can register before this effect cleans up.
-        // Preserve the successor so E2E and recovery probes see the live pane.
+        // Why: a replacement mount can register before cleanup; preserve the successor so E2E/recovery probes see the live pane.
         if (window.__paneManagers?.get(tabId) === manager) {
           window.__paneManagers.delete(tabId)
         }
@@ -1841,10 +1666,7 @@ export function useTerminalPaneLifecycle({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [tabId, cwd])
 
-  // Why: mobile wake fanout — this pane self-selects by worktreeId and fires its
-  // own armed hibernation --resume while staying hidden on the desktop (no
-  // reveal, no focus/navigation change). Not-yet-mounted panes are covered by
-  // the background-mount fresh-connect cold-restore path instead.
+  // Why: mobile wake fanout — pane self-selects by worktreeId and fires its own armed --resume while staying hidden (no reveal/focus change).
   useEffect(() => {
     const onWakeHibernatedAgents = (event: Event): void => {
       const detail = (event as CustomEvent<WakeHibernatedAgentsWorktreeDetail>).detail
@@ -1857,10 +1679,7 @@ export function useTerminalPaneLifecycle({
             wakeHibernatedAgentIfArmed?: (claimedProviderSessions?: Set<string>) => string | null
           }
         ).wakeHibernatedAgentIfArmed?.(detail.wokenClaimKeys)
-        // Why: the dispatcher's follow-up generic resume must skip provider
-        // sessions this pane woke (or latched) in place — the sleeping record
-        // is only cleared after the in-place spawn succeeds, so without this
-        // the same session would resume twice.
+        // Why: mark woken sessions so the dispatcher's generic resume skips them; the sleeping record clears only after spawn, else the session resumes twice.
         if (claimKey) {
           detail.wokenClaimKeys?.add(claimKey)
         }
@@ -1887,21 +1706,19 @@ export function useTerminalPaneLifecycle({
         noteVisibilityResume?: () => void
       }
       bindingWithVisibility.syncProcessTracking?.()
-      // Why: visible-resume repairs dropped hidden resizes, but it must not fit
-      // against xterm's transient hidden DOM fallback.
+      // Why: visible-resume repairs dropped hidden resizes but must not fit against xterm's transient hidden DOM fallback.
       if (resumedFromHidden) {
         bindingWithVisibility.noteVisibilityResume?.()
       }
     }
     if (resumedFromHidden && typeof window.api.pty.hasPty === 'function') {
-      // Why: preserve missed-exit recovery without daemon-wide listSessions;
-      // providers can answer a single-PTY liveness check from in-memory state.
+      // Why: a single-PTY liveness check preserves missed-exit recovery without a daemon-wide listSessions.
       reconcileMissingSessions({
         bindings: panePtyBindingsRef.current.values() as Iterable<ReconcilableBinding>,
         hasPty: window.api.pty.hasPty
       })
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- Why: visibility and terminal identity changes must refresh existing PTY process tracking even though the ref object identity is stable.
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- refs are stable but visibility/identity changes must still refresh PTY process tracking
   }, [cwd, isVisible, isVisibleRef, panePtyBindingsRef, tabId])
 
   useEffect(() => {
@@ -1916,10 +1733,7 @@ export function useTerminalPaneLifecycle({
       const binding = panePtyBindingsRef.current.get(activePane.id) as
         | (IDisposable & { sampleForegroundAgentOnFocus?: () => void })
         | undefined
-      // Why: window refocus does not change the active leaf, so the pane
-      // manager's onActivePaneChange hook is not fired. Re-sample the same
-      // pane to revoke stale launch-only identity and confirm current Droid
-      // ownership before the next Windows Shift+Enter.
+      // Why: window refocus doesn't change the active leaf (no onActivePaneChange), so re-sample to revoke stale launch identity before the next Windows Shift+Enter.
       binding?.sampleForegroundAgentOnFocus?.()
     }
     window.addEventListener('focus', onWindowFocus)
@@ -1932,11 +1746,7 @@ export function useTerminalPaneLifecycle({
       return
     }
     applyAppearance(manager)
-    // Why: effectiveMacOptionAsAlt changes when the OS keyboard layout
-    // switches mid-session (focus-in probe re-runs) or when the user flips
-    // the explicit override. Either triggers a live re-apply of
-    // macOptionIsMeta on every pane so the change takes effect
-    // immediately.
+    // Why: effectiveMacOptionAsAlt can change mid-session (layout switch or override flip); re-apply macOptionIsMeta live on every pane.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [settings, systemPrefersDark, effectiveMacOptionAsAlt])
 
@@ -1949,8 +1759,7 @@ export function useTerminalPaneLifecycle({
     if (!manager) {
       return
     }
-    // Why: live row retention changes are xterm option updates only; they must
-    // not recreate panes, replay snapshots, refit, resize, or signal the PTY.
+    // Why: live row-retention changes are xterm option updates only — must not recreate/replay/refit/resize/signal the PTY.
     applyTerminalScrollbackRowsToMountedPanes(manager, terminalScrollbackRows)
   }, [managerRef, terminalScrollbackRows])
 

From d9d939a33b5858495ffb33489a952f1ac9293610 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Mon, 20 Jul 2026 12:58:56 +0000
Subject: [PATCH 54/54] Update README downloads badge

---
 docs/assets/readme-downloads.svg | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/assets/readme-downloads.svg b/docs/assets/readme-downloads.svg
index 4fdfa604199..a21f01fca97 100644
--- a/docs/assets/readme-downloads.svg
+++ b/docs/assets/readme-downloads.svg
@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="113" height="20" role="img" aria-label="downloads: 6.6m">
-  <title>downloads: 6.6m</title>
+<svg xmlns="http://www.w3.org/2000/svg" width="113" height="20" role="img" aria-label="downloads: 6.7m">
+  <title>downloads: 6.7m</title>
   <linearGradient id="s" x2="0" y2="100%">
     <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
     <stop offset="1" stop-opacity=".1"/>
@@ -15,7 +15,7 @@
   <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="11">
     <text x="37" y="15" fill="#010101" fill-opacity=".3">downloads</text>
     <text x="37" y="14">downloads</text>
-    <text x="93.5" y="15" fill="#010101" fill-opacity=".3">6.6m</text>
-    <text x="93.5" y="14">6.6m</text>
+    <text x="93.5" y="15" fill="#010101" fill-opacity=".3">6.7m</text>
+    <text x="93.5" y="14">6.7m</text>
   </g>
 </svg>